@sybil-studio-devs/sdk

Official TypeScript/JavaScript SDK for Sybil AI - Embeddable wiki (Atlas), file storage (Nexus), document processing, YouTube analysis, and AI-powered knowledge management.

Installation

``bash
npm install @sybil-studio-devs/sdk


or

pnpm add @sybil-studio-devs/sdk

or

yarn add @sybil-studio-devs/sdk
`

Features

- Atlas - Embeddable Notion-like wiki with full editing capabilities
- Nexus - Embeddable Google Drive-like file storage
- Documents - AI-powered document processing and analysis
- YouTube - Video transcript extraction and analysis
- Chat - RAG-powered Q&A with your documents
- Pages - Programmatic page management

Quick Start

$3

`typescript
import { embedAtlas } from '@sybil-studio-devs/sdk';

const atlas = embedAtlas({
apiKey: 'sk_live_YOUR_API_KEY',
workspaceId: 'your-workspace-id',
container: '#wiki-container',
theme: 'dark',
showSidebar: true,
onPageChange: (page) => console.log('Page changed:', page),
onError: (error) => console.error('Error:', error),
});

// Navigate programmatically
atlas.navigateTo('page-id');

// Create a new page
const page = await atlas.createPage({ title: 'New Page' });

// Export page
const pdf = await atlas.exportPage('page-id', 'pdf');
`

$3

`typescript
import { embedNexus } from '@sybil-studio-devs/sdk';

const nexus = embedNexus({
apiKey: 'sk_live_YOUR_API_KEY',
workspaceId: 'your-workspace-id',
container: '#storage-container',
viewMode: 'grid',
allowUpload: true,
onFileSelect: (file) => console.log('Selected:', file),
onFileUpload: (file) => console.log('Uploaded:', file),
});

// Upload a file
const file = await nexus.uploadFile(fileBlob, 'folder-id');

// Navigate to folder
nexus.navigateTo('folder-id');

// Search files
const results = await nexus.search('quarterly report');
`

$3

`tsx
import { SybilAtlas, SybilNexus } from '@sybil-studio-devs/sdk/react';

function App() {
return (



);
}
`

$3

`tsx
import { useAtlas, useNexus } from '@sybil-studio-devs/sdk/react';

function WikiManager() {
const {
sidebar,
currentPage,
loading,
fetchSidebar,
createPage,
updatePage,
getLogs,
} = useAtlas({
apiKey: 'sk_live_xxx',
workspaceId: 'workspace-id',
logging: { enabled: true, level: 'debug' },
});

// Use the hook data...
}

function FileManager() {
const {
files,
folders,
uploadFile,
createFolder,
navigateTo,
getLogs,
} = useNexus({
apiKey: 'sk_live_xxx',
workspaceId: 'workspace-id',
});

// Use the hook data...
}
`

Atlas Configuration

`typescript
embedAtlas({
// Required
apiKey: string,
workspaceId: string,
container: HTMLElement | string,

// Optional - Theming
baseUrl?: string, // Default: 'https://app.sybil.studio'
theme?: 'light' | 'dark' | {
background?: string,
backgroundSecondary?: string,
text?: string,
textSecondary?: string,
textMuted?: string,
border?: string,
accent?: string,
sidebarBackground?: string,
},

// Optional - Layout
showSidebar?: boolean, // Default: true
sidebarWidth?: number, // Default: 260
sidebarCollapsible?: boolean, // Default: true

// Optional - Permissions
readOnly?: boolean, // Default: false
allowCreate?: boolean, // Default: true
allowDelete?: boolean, // Default: true
allowExport?: boolean, // Default: true

// Optional - Features
features?: {
favorites?: boolean,
teamspaces?: boolean,
search?: boolean,
export?: boolean,
coverImages?: boolean,
icons?: boolean,
minimap?: boolean,
floatingToolbar?: boolean,
aiAssist?: boolean,
},

// Optional - Logging (for debugging)
logging?: {
enabled: boolean,
level?: 'debug' | 'info' | 'warn' | 'error',
onLog?: (entry: AtlasLogEntry) => void,
},

// Optional - Navigation
defaultPageId?: string,

// Callbacks
onReady?: (instance: AtlasInstance) => void,
onPageChange?: (page: AtlasPage) => void,
onPageCreate?: (page: AtlasPage) => void,
onPageDelete?: (pageId: string) => void,
onPageUpdate?: (page: AtlasPage) => void,
onNavigate?: (pageId: string) => void,
onError?: (error: AtlasError) => void,
});
`

Nexus Configuration

`typescript
embedNexus({
// Required
apiKey: string,
workspaceId: string,
container: HTMLElement | string,

// Optional - Theming
baseUrl?: string,
theme?: 'light' | 'dark' | NexusTheme,

// Optional - Layout
initialFolderId?: string | null,
viewMode?: 'list' | 'grid', // Default: 'list'
showSidebar?: boolean, // Default: true
showActivityFeed?: boolean, // Default: true
showBreadcrumbs?: boolean, // Default: true
showSearch?: boolean, // Default: true

// Optional - Permissions
allowUpload?: boolean, // Default: true
allowDownload?: boolean, // Default: true
allowDelete?: boolean, // Default: true
allowMove?: boolean, // Default: true
allowRename?: boolean, // Default: true
allowCreateFolder?: boolean, // Default: true
allowMultiSelect?: boolean, // Default: true

// Optional - Upload constraints
maxUploadSize?: number, // In bytes
acceptedFileTypes?: string[], // e.g. ['image/*', 'application/pdf']

// Optional - Features
features?: {
aiAnalysis?: boolean,
labels?: boolean,
starring?: boolean,
trash?: boolean,
preview?: boolean,
thumbnails?: boolean,
dragAndDrop?: boolean,
keyboardShortcuts?: boolean,
commandMenu?: boolean,
bulkActions?: boolean,
},

// Optional - Logging
logging?: {
enabled: boolean,
level?: 'debug' | 'info' | 'warn' | 'error',
onLog?: (entry: NexusLogEntry) => void,
},

// Callbacks
onReady?: (instance: NexusInstance) => void,
onNavigate?: (folderId: string | null) => void,
onFileSelect?: (file: NexusFile) => void,
onFileOpen?: (file: NexusFile) => void,
onFileUpload?: (file: NexusFile) => void,
onFileDelete?: (fileId: string) => void,
onFolderCreate?: (folder: NexusFolder) => void,
onFolderDelete?: (folderId: string) => void,
onSelectionChange?: (items: NexusItem[]) => void,
onError?: (error: NexusError) => void,
});
`

Instance Methods

$3

`typescript
const atlas = embedAtlas({ ... });

// Page management
await atlas.getPages(); // Get sidebar data
await atlas.getPage('page-id'); // Get single page
await atlas.createPage({ title: 'New' }); // Create page
await atlas.updatePage('id', { title: 'Updated' }); // Update page
await atlas.deletePage('page-id'); // Delete page
await atlas.exportPage('id', 'pdf'); // Export as PDF/DOCX/MD

// Navigation
atlas.navigateTo('page-id');
atlas.getCurrentPage();

// UI controls
atlas.toggleSidebar();
atlas.setSidebarWidth(300);
atlas.setTheme('light');
atlas.refresh();

// Debugging
atlas.getLogs();
atlas.clearLogs();

// Cleanup
atlas.destroy();
`

$3

`typescript
const nexus = embedNexus({ ... });

// File operations
await nexus.getFiles('folder-id');
await nexus.getFile('file-id');
await nexus.uploadFile(file, 'folder-id', onProgress);
await nexus.uploadFiles(files, 'folder-id', onProgress);
await nexus.downloadFile('file-id');
await nexus.getDownloadUrl('file-id');
await nexus.deleteFile('file-id');
await nexus.moveFile('file-id', 'target-folder-id');
await nexus.renameFile('file-id', 'new-name.pdf');
await nexus.starFile('file-id', true);

// Folder operations
await nexus.getFolders('parent-id');
await nexus.getFolderContents('folder-id');
await nexus.getFolderTree();
await nexus.createFolder('New Folder', 'parent-id');
await nexus.deleteFolder('folder-id');
await nexus.moveFolder('folder-id', 'new-parent-id');

// Navigation & selection
nexus.navigateTo('folder-id');
nexus.getCurrentFolder();
nexus.getSelection();
nexus.setSelection(['id1', 'id2']);
nexus.clearSelection();
nexus.selectAll();

// Search & stats
await nexus.search('query');
await nexus.getStats();
await nexus.getActivity(50);

// Labels
await nexus.getLabels();
await nexus.applyLabel(['file-id'], 'label-id');

// UI controls
nexus.setViewMode('grid');
nexus.toggleActivityFeed();
nexus.toggleSidebar();
nexus.setTheme('dark');
nexus.refresh();

// Debugging
nexus.getLogs();
nexus.clearLogs();

// Cleanup
nexus.destroy();
`

Debugging with Logs

Enable logging to debug issues:

`typescript
const atlas = embedAtlas({
// ...
logging: {
enabled: true,
level: 'debug', // 'debug' | 'info' | 'warn' | 'error'
onLog: (entry) => {
// entry.timestamp
// entry.level
// entry.category: 'api' | 'render' | 'navigation' | 'editor' | 'sync'
// entry.message
// entry.data
// entry.duration
console.log([${entry.category}] ${entry.message}, entry.data);
},
},
});

// Get all logs
const logs = atlas.getLogs();

// Clear logs
atlas.clearLogs();
`

Standalone Clients

For server-side or non-embed use cases:

`typescript
import { AtlasClient, NexusClient } from '@sybil-studio-devs/sdk';

// Atlas client
const atlas = new AtlasClient({
apiKey: 'sk_live_xxx',
workspaceId: 'workspace-id',
});

const sidebar = await atlas.getSidebar();
const page = await atlas.createPage({ title: 'New Page' });

// Nexus client
const nexus = new NexusClient({
apiKey: 'sk_live_xxx',
workspaceId: 'workspace-id',
});

const files = await nexus.listFiles('folder-id');
const folder = await nexus.createFolder('New Folder');
`

Legacy APIs

$3

`typescript
import { SybilSDK } from '@sybil-studio-devs/sdk';

const sybil = new SybilSDK('sk_live_YOUR_API_KEY');

// Process a document
const result = await sybil.documents.process(file);

// Wait for processing
const document = await sybil.documents.waitForProcessing(result.documentId);

// Get insights
const { insights } = await sybil.documents.insights('doc-id');
`

$3

`typescript
// Process YouTube video
const result = await sybil.youtube.process('https://youtube.com/watch?v=...');

// Get video with transcript
const { video } = await sybil.youtube.get('VIDEO_ID', {
includeTranscript: true,
});
`

$3

`typescript
// Chat with document
const result = await sybil.chat.send('document-id', 'What are the key findings?');

console.log(result.response);
console.log(result.sources);
`

Error Handling

`typescript
import { SybilError } from '@sybil-studio-devs/sdk';

try {
await atlas.createPage({ title: 'New' });
} catch (error) {
if (error instanceof SybilError) {
console.error(Error ${error.status}: ${error.message});
console.error(Code: ${error.code});
}
}

// Or use callbacks
embedAtlas({
// ...
onError: (error) => {
console.error([${error.code}] ${error.message});
console.error('Request ID:', error.requestId);
console.error('Details:', error.details);
},
});
`

TypeScript Types

All types are exported:

`typescript
import type {
// Atlas
AtlasPage,
AtlasSidebarData,
AtlasEmbedConfig,
AtlasInstance,
AtlasError,
AtlasLogEntry,

// Nexus
NexusFile,
NexusFolder,
NexusItem,
NexusEmbedConfig,
NexusInstance,
NexusError,
NexusLogEntry,

// Legacy
Page,
Document,
YouTubeVideo,
ChatResult,
} from '@sybil-studio-devs/sdk';
``

Browser & Node.js Support

Works in modern browsers and Node.js 18+.

License

MIT