Brightsy Client

Official TypeScript/JavaScript client for the Brightsy API.

Installation

npm install @brightsy/client

Quick Start

import { BrightsyClient } from '@brightsy/client';

const client = new BrightsyClient({
  api_key: 'bsy_your_api_key',
  account_id: 'your_account_id',
  endpoint: 'https://brightsy.ai' // optional
});

API Reference

Content Management (CMS)

CMA - Content Management API

Access draft content with full CRUD operations:

// List records
const posts = await client.cma()
  .recordType('blog-post')
  .where('status', 'eq', 'draft')
  .pageSize(10)
  .get();

// Create a record
const newPost = await client.cma()
  .recordType('blog-post')
  .create({
    title: 'My Post',
    content: '...'
  });

// Update a record
await client.cma()
  .recordType('blog-post')
  .id('record-id')
  .update({ title: 'Updated Title' });

// Delete a record
await client.cma()
  .recordType('blog-post')
  .id('record-id')
  .delete();

CDA - Content Delivery API

Access published content (read-only):

const posts = await client.cda()
  .recordType('blog-post')
  .where('published', 'eq', true)
  .get();

CPA - Content Preview API

Access draft content (read-only):

const drafts = await client.cpa()
  .recordType('blog-post')
  .get();

Agents

Manage and interact with AI agents:

// List agents
const agents = await client.agents().list({ search: 'customer' });

// Create an agent
const agent = await client.agents().create({
  name: 'Customer Support',
  description: 'Handles customer inquiries',
  system_instruction: '...'
});

// Get agent details
const agent = await client.agents().get('agent-id');

// Update an agent
await client.agents().update('agent-id', {
  name: 'Updated Name'
});

// Delete an agent
await client.agents().delete('agent-id');

// Chat with an agent (execution)
const response = await client.agent('agent-id').chat({
  message: 'Hello!',
  chat_id: client.createChatId()
});

Scenarios

Manage automation scenarios:

// List scenarios
const scenarios = await client.scenarios().list();

// Create a scenario
const scenario = await client.scenarios().create({
  name: 'Welcome Email',
  description: '...',
  trigger_type: 'webhook',
  run_as_user_id: 'user-uuid' // Optional user context for webhook/signature runs
});

// Get, update, delete
await client.scenarios().get('scenario-id');
await client.scenarios().update('scenario-id', { run_as_user_id: 'user-uuid' });
await client.scenarios().delete('scenario-id');

// Trigger a scenario (legacy method)
await client.scenario('scenario-id').trigger({ data: '...' });

Schedules

Manage scheduled tasks:

// List schedules
const schedules = await client.schedules().list();

// Create a schedule
const schedule = await client.schedules().create({
  name: 'Daily Backup',
  cron: '0 0 * * *',
  scenario_id: 'scenario-id'
});

// Get, update, delete
await client.schedules().get('schedule-id');
await client.schedules().update('schedule-id', { /* ... */ });
await client.schedules().delete('schedule-id');

Webhooks

Manage event webhooks:

// List webhooks
const webhooks = await client.webhooks().list();

// Create a webhook
const webhook = await client.webhooks().create({
  name: 'Content Published',
  webhook_type: 'http',
  endpoint_url: 'https://example.com/webhook',
  triggers: {
    cms: {
      'blog-post': {
        publish: true
      }
    }
  }
});

// Get, update, delete
await client.webhooks().get('webhook-id');
await client.webhooks().update('webhook-id', { /* ... */ });
await client.webhooks().delete('webhook-id');

// Test a webhook
await client.webhooks().test('webhook-id');

Apps

Access connected apps/integrations:

// List connected apps
const apps = await client.apps().list();

// Get app details
const app = await client.apps().get('app-id');

Files

Manage files and folders in account storage:

// List files
const files = await client.files().list({ 
  path: 'public/images',
  search: 'logo' 
});

// Create folder
await client.files().createFolder({
  path: 'public',
  folderName: 'images'
});

// Upload file
await client.files().upload({
  path: 'public',
  filename: 'image.jpg',
  file: fileBlob
});

// Get signed URL for private file
const { signedUrl } = await client.files().signedUrl({
  path: 'public/image.jpg',
  expiresIn: 3600
});

// Move/rename file
await client.files().move('old/path.jpg', 'new/path.jpg');

// Delete file
await client.files().delete('path/to/file.jpg');

AI Images

AI-powered image operations:

// Analyze an image
const analysis = await client.images().analyze({
  imageUrl: 'https://example.com/image.jpg',
  prompt: 'What objects are in this image?', // optional
  model: 'gemini_2_5_flash_preview_09_2025' // optional
});
console.log(analysis.data.response);

// Get improvement suggestions
const suggestions = await client.images().suggestEdits({
  imageUrl: 'https://example.com/image.jpg',
  model: 'gemini_2_5_flash_preview_09_2025' // optional
});
console.log(suggestions.data.suggestions);
// Returns structured suggestions with category, title, description, priority

// Generate a new image
const generation = await client.images().generate({
  prompt: 'A beautiful sunset over mountains',
  width: 1024,  // optional, default: 1024
  height: 768,  // optional, default: 768
  model: 'gemini_nano_banana_2_1' // optional; catalog key or OpenRouter id
});
console.log(generation.data.imageUrl);

Image Analysis uses Gemini 2.5 Flash for AI vision analysis of images. You can ask specific questions about the image or get a general description.

Image Suggestions returns structured recommendations for improving the image, including composition, color, brightness, technical, and creative suggestions.

Image Generation creates new images from text prompts using Flux 1.1 Pro. The generated image URL is temporary and should be downloaded if you need to persist it.

// List files
const files = await client.files().list({
  path: 'documents',
  search: 'invoice'
});

// Create a folder
await client.files().createFolder({
  path: 'documents',
  folderName: '2024'
});

// Option 1: Direct upload (convenience method)
const { fileUrl, path } = await client.files().upload({
  path: 'documents',
  filename: 'report.pdf',
  file: fileData // File, Blob, or Buffer
});

// Option 2: Manual two-step upload
const { uploadUrl, fileUrl } = await client.files().uploadUrl({
  path: 'documents',
  filename: 'report.pdf'
});

await fetch(uploadUrl, {
  method: 'PUT',
  body: fileData
});

// Get signed download URL
const { signedUrl } = await client.files().signedUrl({
  path: 'documents/report.pdf',
  expiresIn: 3600
});

// Delete a file
await client.files().delete('documents/report.pdf');

// Move/rename a file
await client.files().move('old-path.pdf', 'new-path.pdf');

API Keys

Manage team API keys:

// List API keys
const keys = await client.apikeys().list();

// Create an API key
const newKey = await client.apikeys().create({
  name: 'Production Key',
  permissions: {
    cms: {
      'blog-post': {
        read: true,
        create: true
      }
    }
  }
});

// Get, update, delete
await client.apikeys().get('key-id');
await client.apikeys().update('key-id', { name: 'Updated' });
await client.apikeys().delete('key-id');

// Rotate an API key
const { key } = await client.apikeys().rotate('key-id');

Advanced Usage

File Upload Examples

Browser (with File input)

// From file input
const fileInput = document.getElementById('fileInput') as HTMLInputElement;
const file = fileInput.files[0];

const { fileUrl } = await client.files().upload({
  path: 'uploads',
  filename: file.name,
  file: file
});

console.log('File uploaded to:', fileUrl);

Node.js (with fs)

import fs from 'fs';

const fileBuffer = fs.readFileSync('./report.pdf');

const { fileUrl } = await client.files().upload({
  path: 'documents',
  filename: 'report.pdf',
  file: fileBuffer
});

With Blob/ArrayBuffer

const blob = new Blob(['Hello, world!'], { type: 'text/plain' });

const { fileUrl } = await client.files().upload({
  path: 'notes',
  filename: 'hello.txt',
  file: blob
});

Filtering and Pagination

const results = await client.cma()
  .recordType('blog-post')
  .where('status', 'eq', 'published')
  .where('views', 'gt', 1000)
  .orderBy('created_at', 'desc')
  .page(1)
  .pageSize(20)
  .select('title', 'slug', 'created_at')
  .get();

Error Handling

try {
  const agent = await client.agents().get('invalid-id');
} catch (error) {
  console.error('Error:', error.message);
}

Streaming Agent Responses

await client.agent('agent-id').chat({
  message: 'Tell me a story',
  stream: true,
  onChunk: (chunk) => {
    console.log(chunk);
  }
});

Development & Testing

Running Tests

# Run all unit tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run API integration tests (with MSW mocks)
pnpm test:api

# Run E2E tests against REAL API
# Option 1: Use CLI login (recommended)
brightsy login  # Run once to authenticate
pnpm test:e2e

# Option 2: Use environment variables
BRIGHTSY_API_KEY=bsy_xxx BRIGHTSY_ACCOUNT_ID=xxx pnpm test:e2e

# Run tests with coverage
pnpm test:coverage

Test Structure

The test suite includes:

• Unit Tests (src/*.test.ts)

  • Client.test.ts - BrightsyClient class and generateUUID
  • oauth.test.ts - OAuth PKCE utilities and OAuthClient
  • stream-utils.test.ts - Message formatting and JSON parsing

• API Integration Tests (src/api.test.ts)

  • Tests for Agents, Scenarios, CMS, Files APIs
  • Uses MSW (Mock Service Worker) for API mocking

• E2E Tests (src/e2e.test.ts)

  • Tests against the real Brightsy API
  • Requires BRIGHTSY_API_KEY and BRIGHTSY_ACCOUNT_ID env vars
  • Use a test account to avoid modifying production data

Building

pnpm build

Authentication

The client supports team API keys with granular permissions. Get your API key from the Brightsy dashboard.

Support

• Documentation: https://docs.brightsy.ai
• GitHub: https://github.com/brightsy/brightsy
• Email: [email protected]

License

MIT