Embed Codiris Brainboard whiteboard functionality into your applications
npm install @codiris/brainboard-sdkEmbed Codiris Brainboard whiteboard functionality into your applications. Build collaborative visual experiences with AI-powered features.
``bash`
npm install @codiris/brainboard-sdkor
yarn add @codiris/brainboard-sdkor
pnpm add @codiris/brainboard-sdk
`typescript
import { BrainboardClient } from '@codiris/brainboard-sdk';
// Initialize the client
const client = new BrainboardClient({
apiKey: 'your-api-key',
workspaceId: 'your-workspace-id', // optional
});
// List boards
const { data: boards } = await client.listBoards();
// Create a board
const { data: board } = await client.createBoard({
name: 'My Board',
description: 'A collaborative whiteboard',
});
// Add objects to the board
await client.createObject(board.id, {
type: 'sticky',
x: 100,
y: 100,
width: 200,
height: 200,
text: 'Hello World!',
fill: '#ffeb3b',
});
`
`tsx
import { BrainboardProvider, BrainboardEmbed, useBoards } from '@codiris/brainboard-sdk/react';
// Wrap your app with the provider
function App() {
return (
);
}
// Use the embed component
function MyComponent() {
const { boards, createBoard } = useBoards();
return (
{boards[0] && (
width="100%"
height="600px"
showToolbar
onBoardChange={(board) => console.log('Board updated:', board)}
/>
)}
Features
$3
`typescript
// List boards with filtering
const { data } = await client.listBoards({
status: 'active',
search: 'project',
page: 1,
pageSize: 20,
});// Get a specific board
const { data: board } = await client.getBoard('board-id');
// Update a board
await client.updateBoard('board-id', {
name: 'Updated Name',
isPublic: true,
});
// Delete a board
await client.deleteBoard('board-id');
// Duplicate a board
const { data: newBoard } = await client.duplicateBoard('board-id', 'Copy of Board');
`$3
`typescript
// Create various object types
await client.createObject(boardId, {
type: 'text',
x: 100, y: 100,
text: 'Hello World',
fontSize: 24,
});await client.createObject(boardId, {
type: 'shape',
x: 200, y: 200,
width: 150, height: 100,
shapeType: 'rectangle',
fill: '#3b82f6',
});
await client.createObject(boardId, {
type: 'sticky',
x: 400, y: 100,
width: 200, height: 200,
text: 'Idea #1',
fill: '#fef08a',
});
// Batch create
await client.createObjects(boardId, [
{ type: 'sticky', x: 100, y: 100, text: 'Task 1' },
{ type: 'sticky', x: 320, y: 100, text: 'Task 2' },
{ type: 'sticky', x: 540, y: 100, text: 'Task 3' },
]);
// Update objects
await client.updateObject(boardId, objectId, {
text: 'Updated text',
fill: '#22c55e',
});
// Delete objects
await client.deleteObject(boardId, objectId);
await client.deleteObjects(boardId, [id1, id2, id3]);
`$3
| Type | Description |
|------|-------------|
|
sticky | Sticky note with text |
| text | Text block |
| shape | Shapes (rectangle, circle, triangle, diamond, star, etc.) |
| line | Connecting line |
| arrow | Arrow connector |
| image | Image element |
| card | Card with title, description, tags |
| table | Data table |
| kanban | Kanban board |
| code | Code block with syntax highlighting |
| chart | Chart (line, bar, pie, etc.) |
| embed | External embed (YouTube, Figma, etc.) |
| frame | Presentation frame |
| draw | Freehand drawing |$3
`typescript
// Get board members
const { data: members } = await client.getMembers(boardId);// Invite a member
await client.inviteMember(boardId, 'user@example.com', 'editor');
// Update member role
await client.updateMemberRole(boardId, memberId, 'viewer');
// Remove a member
await client.removeMember(boardId, memberId);
// Generate share link
const { data } = await client.generateShareLink(boardId, {
canEdit: false,
expiresAt: '2024-12-31T23:59:59Z',
});
console.log(data.shareUrl);
`$3
`typescript
// Get comments
const { data: comments } = await client.getComments(boardId);// Add a comment
await client.addComment(boardId, 'Great idea!', objectId);
// Reply to a comment
await client.addComment(boardId, 'I agree!', objectId, parentCommentId);
// Resolve a comment
await client.resolveComment(boardId, commentId);
`$3
`typescript
// Generate content
const { data } = await client.generateContent({
prompt: 'Create a user journey map for an e-commerce checkout flow',
type: 'diagram',
});// Chat with AI about board content
const { data: response } = await client.chat(boardId, [
{ role: 'user', content: 'What are the main themes on this board?' }
]);
console.log(response.content);
console.log(response.sources); // Cited sources from the board
// Execute natural language commands
await client.executeCommand(boardId, 'make all sticky notes blue');
await client.executeCommand(boardId, 'align selected items to the left', selectedIds);
// Generate audio overview
const { data: audio } = await client.generateAudioOverview(boardId, 'podcast');
console.log(audio.audioUrl, audio.script);
`$3
`typescript
// List templates
const { data: templates } = await client.listTemplates('brainstorming');// Create from template
const { data: board } = await client.createFromTemplate(
'template-id',
'My Brainstorm Session'
);
// Save board as template
await client.saveAsTemplate(boardId, 'My Template', 'Reusable board layout');
`$3
`typescript
// Import from URL
await client.importFromUrl(boardId, 'https://example.com/article', { x: 100, y: 100 });// Extract from PDF
await client.extractPdf(boardId, 'https://example.com/document.pdf');
// Create from interview data
await client.createFromInterview(interviewId, 'Interview Summary Board');
// Export
const { data: json } = await client.exportAsJson(boardId);
const { data: image } = await client.exportAsImage(boardId, 'png', { scale: 2 });
const { data: pdf } = await client.exportAsPdf(boardId, { includeFrames: true });
`React Hooks
$3
`tsx
const { board, loading, error, updateBoard } = useBoard('board-id');
`$3
`tsx
const { boards, total, loading, createBoard, deleteBoard } = useBoards({
status: 'active',
page: 1,
});
`$3
`tsx
const {
objects,
selectedObjects,
createObject,
updateObject,
deleteObject,
selectObject,
clearSelection,
} = useBoardObjects('board-id');
`$3
`tsx
const { members, inviteMember, removeMember } = useBoardMembers('board-id');
`$3
`tsx
const { comments, addComment, deleteComment } = useBoardComments('board-id');
`$3
`tsx
const { messages, loading, sendMessage, clearMessages } = useBrainboardChat('board-id');// Send message with source grounding
await sendMessage('What patterns do you see?', true);
`$3
`tsx
const { loading, generate } = useBrainboardGenerate();const result = await generate({
prompt: 'Create a SWOT analysis template',
type: 'diagram',
});
`$3
`tsx
useBrainboardEvent('object:created', (event) => {
console.log('New object:', event.data);
});
`$3
`tsx
const { templates, createFromTemplate } = useTemplates('planning');
`React Components
$3
Full-featured embedded board editor.
`tsx
boardId="board-id"
width="100%"
height="600px"
readOnly={false}
showToolbar={true}
showSidebar={false}
showComments={true}
showMinimap={true}
theme="light"
onReady={() => console.log('Ready!')}
onBoardChange={(board) => console.log(board)}
onObjectSelect={(objects) => console.log(objects)}
/>
`$3
Read-only board viewer.
`tsx
boardId="board-id"
width="100%"
height="400px"
showNavigation={true}
autoFit={true}
/>
`$3
Board thumbnail preview.
`tsx
board={board}
width={200}
height={150}
onClick={() => navigate(/boards/${board.id})}
/>
`$3
Grid view of boards.
`tsx
boards={boards}
gridColumns={3}
onSelect={(board) => setSelectedBoard(board)}
emptyMessage="No boards yet"
/>
`Events
Listen to real-time events:
`typescript
import { globalEvents } from '@codiris/brainboard-sdk';globalEvents.on('board:updated', (event) => {
console.log('Board updated:', event.data);
});
globalEvents.on('object:created', (event) => {
console.log('Object created:', event.data);
});
globalEvents.on('user:joined', (event) => {
console.log('User joined:', event.data);
});
// Listen to all events
globalEvents.onAll((event) => {
console.log(
${event.type}:, event.data);
});
`$3
| Event | Description |
|-------|-------------|
|
board:loaded | Board finished loading |
| board:updated | Board properties changed |
| object:created | New object added |
| object:updated | Object modified |
| object:deleted | Object removed |
| object:selected | Objects selected |
| object:deselected | Selection cleared |
| camera:moved | Viewport changed |
| user:joined | User joined the board |
| user:left | User left the board |
| cursor:moved | User cursor moved |
| comment:added | New comment added |
| error | Error occurred |Configuration
`typescript
const client = new BrainboardClient({
// Required
apiKey: 'your-api-key', // Optional
baseUrl: 'https://app.codiris.ai/api', // Custom API endpoint
workspaceId: 'workspace-id', // Default workspace
userId: 'user-id', // Current user ID
userEmail: 'user@example.com', // Current user email
userName: 'User Name', // Current user name
debug: false, // Enable debug logging
});
`TypeScript Support
The SDK is fully typed. Import types as needed:
`typescript
import type {
Board,
BoardObject,
BoardMember,
CreateBoardInput,
CreateObjectInput,
BrainboardConfig,
} from '@codiris/brainboard-sdk';
`Error Handling
All API methods return a consistent response format:
`typescript
const response = await client.getBoard('board-id');if (response.success) {
console.log(response.data);
} else {
console.error(response.error);
}
`With React hooks, errors are exposed via the
error property:`tsx
const { board, loading, error } = useBoard('board-id');if (error) {
return
Error: {error.message};
}
``MIT