亮度客户端
Brightsy API的官方TypeScript/JavaScript客户端.
安装
npm install @brightsy/client
快速启动
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 参考
内容管理
CMA - 内容管理 API
包含完整 CRUD 操作的访问草稿内容 :
// 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 - 内容交付 API
访问已发布的内容( 只读) :
const posts = await client.cda()
.recordType('blog-post')
.where('published', 'eq', true)
.get();
CPA - 内容预览 API
访问草稿内容( 只读) :
const drafts = await client.cpa()
.recordType('blog-post')
.get();
探员
管理和与AI代理交互:
// 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()
});
假设
管理自动化方案:
// 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: '...' });
时间表
管理计划任务 :
// 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');
网络呼号
管理事件 Webhoks :
// 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');
应用程序
访问连接的应用程序/集成 :
// List connected apps
const apps = await client.apps().list();
// Get app details
const app = await client.apps().get('app-id');
文件
管理账户存储中的文件和文件夹 :
// 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 图像
AI 驱动图像操作 :
// 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);
图像分析 双子座2.5 用于图像的AI视觉分析的闪光. 您可以询问有关图像的具体问题或获得一般描述.
图像建议 返回关于改善图像的结构化建议,包括组成、颜色、亮度、技术和创造性建议.
图像生成 使用 Flux 1. 1 Pro 从文本提示创建新图像 。 生成的图像 URL 是临时的, 如果您需要坚持, 应该下载 .
// 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 密钥
管理团队 API 密钥 :
// 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');
高级使用
文件上传示例
浏览器( 有文件输入)
// 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);
节点.js(带有fs)
import fs from 'fs';
const fileBuffer = fs.readFileSync('./report.pdf');
const { fileUrl } = await client.files().upload({
path: 'documents',
filename: 'report.pdf',
file: fileBuffer
});
带有 Blob/ ArrayBaffer 的文件
const blob = new Blob(['Hello, world!'], { type: 'text/plain' });
const { fileUrl } = await client.files().upload({
path: 'notes',
filename: 'hello.txt',
file: blob
});
过滤和铺放
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();
处理错误
try {
const agent = await client.agents().get('invalid-id');
} catch (error) {
console.error('Error:', error.message);
}
流程代理回复
await client.agent('agent-id').chat({
message: 'Tell me a story',
stream: true,
onChunk: (chunk) => {
console.log(chunk);
}
});
开发和测试
运行测试
# 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
测试结构
测试套房包括:
-
单位测试 (单位:千美元)
src/*.test.ts(中文(简体) )Client.test.ts- 亮相类和生成UUIDoauth.test.ts- OAuth PKCE公用事业和OAuthClientstream-utils.test.ts- 信息格式化和JSON分析
-
API 集成测试 (单位:千美元)
src/api.test.ts(中文(简体) )- 对代理、情景、CMS、文件的测试
- 使用 MSW (Mock Service Worker) 来模拟 API
-
E2E 测试 (单位:千美元)
src/e2e.test.ts(中文(简体) )- 针对真实的亮光API的测试
- 要求数
BRIGHTSY_API_KEY财务报告和审定财务报表BRIGHTSY_ACCOUNT_ID环境 vars - 使用测试账户避免修改生产数据
大楼
pnpm build
认证
客户端支持带颗粒权限的团队API密钥. 从Brightsy仪表板取出你的API钥匙.
支助
- 联合国 https://docs.brights.ai (英语)
- GitHub : (中文(简体) ) https://github.com/brightsy/brightsy (中文(简体) )
- 电子邮件 : 支持@brightsy.ai
许可证
麻省理工学院