@codiris/brainboard-sdk

Embed Codiris Brainboard whiteboard functionality into your applications. Build collaborative visual experiences with AI-powered features.

Installation

``bash
npm install @codiris/brainboard-sdk


or

yarn add @codiris/brainboard-sdk

or

pnpm add @codiris/brainboard-sdk
`

Quick Start

$3

`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',
});
`

$3

`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 (



);
}
`

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

;
}
``

License

MIT