@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

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

Embed Atlas (Wiki)

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');

Embed Nexus (File Storage)

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');

React Components

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

function App() {
  return (
    <div style={{ display: 'flex', height: '100vh' }}>
      {/* Embedded Wiki */}
      <SybilAtlas
        apiKey="sk_live_xxx"
        workspaceId="workspace-id"
        showSidebar={true}
        theme="dark"
        onPageChange={(page) => console.log(page)}
        style={{ flex: 1 }}
      />

      {/* Embedded File Storage */}
      <SybilNexus
        apiKey="sk_live_xxx"
        workspaceId="workspace-id"
        viewMode="list"
        onFileUpload={(file) => console.log(file)}
        style={{ flex: 1 }}
      />
    </div>
  );
}

React Hooks

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

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

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

Atlas Instance

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();

Nexus Instance

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:

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:

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

Documents

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');

YouTube

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

Chat (RAG)

// 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

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:

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