@sybil-studio-devs/sdk 0.1.1 → 0.2.0

package/README.md

@@ -1,135 +1,447 @@
-# @sybil-studio/sdk
+# @sybil-studio-devs/sdk
 
-Official TypeScript/JavaScript SDK for Sybil AI - Document processing, YouTube analysis, and AI-powered knowledge management.
+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
-npm install @sybil-studio/sdk
+npm install @sybil-studio-devs/sdk
+# or
+pnpm add @sybil-studio-devs/sdk
+# or
+yarn add @sybil-studio-devs/sdk
+```
 
-# pnpm
-pnpm add @sybil-studio/sdk
+## Features
 
-# yarn
-yarn add @sybil-studio/sdk
-```
+- **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)
+
 ```typescript
-import { SybilSDK } from '@sybil-studio/sdk';
+import { embedAtlas } from '@sybil-studio-devs/sdk';
 
-const sybil = new SybilSDK('sk_live_YOUR_API_KEY');
+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),
+});
 
-// Process a YouTube video
-const video = await sybil.youtube.process('https://youtube.com/watch?v=...');
+// Navigate programmatically
+atlas.navigateTo('page-id');
 
-// Chat with a document
-const response = await sybil.chat.send(video.document.id, 'Summarize the main points');
+// Create a new page
+const page = await atlas.createPage({ title: 'New Page' });
 
-// Create a page
-const page = await sybil.pages.create({
-  title: 'My Notes',
-  blocks: [
-    { type: 'paragraph', content: [{ type: 'text', text: 'Hello world' }] }
-  ]
-});
+// Export page
+const pdf = await atlas.exportPage('page-id', 'pdf');
 ```
 
-## Configuration
+### Embed Nexus (File Storage)
 
 ```typescript
-// Simple - just API key (uses default base URL)
-const sybil = new SybilSDK('sk_live_YOUR_API_KEY');
+import { embedNexus } from '@sybil-studio-devs/sdk';
 
-// Full configuration
-const sybil = new SybilSDK({
+const nexus = embedNexus({
   apiKey: 'sk_live_YOUR_API_KEY',
-  baseUrl: 'https://your-domain.com/api/sdk/v1', // Optional
-  timeout: 30000, // Optional, in milliseconds
+  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
+
+```tsx
+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>
+  );
+}
 ```
 
-## API Reference
+### React Hooks
+
+```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...
+}
 
-### Pages
+function FileManager() {
+  const {
+    files,
+    folders,
+    uploadFile,
+    createFolder,
+    navigateTo,
+    getLogs,
+  } = useNexus({
+    apiKey: 'sk_live_xxx',
+    workspaceId: 'workspace-id',
+  });
+
+  // Use the hook data...
+}
+```
+
+## Atlas Configuration
 
 ```typescript
-// List pages
-const { pages, pagination } = await sybil.pages.list({
-  limit: 20,
-  offset: 0,
-  parent_id: 'root', // or specific page ID
-  is_published: true
+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,
 });
+```
 
-// Create page
-const { page } = await sybil.pages.create({
-  title: 'New Page',
-  description: 'Optional description',
-  blocks: [
-    { type: 'heading', attrs: { level: 1 }, content: [{ type: 'text', text: 'Title' }] },
-    { type: 'paragraph', content: [{ type: 'text', text: 'Content here' }] },
-    { type: 'image', attrs: { src: 'https://...' } }
-  ],
-  parent_id: 'optional-parent-uuid'
+## 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,
 });
+```
 
-// Get page
-const { page } = await sybil.pages.get('page-id');
+## Instance Methods
 
-// Update page
-const { page } = await sybil.pages.update('page-id', {
-  title: 'Updated Title',
-  blocks: [...],
-  is_published: true
-});
+### Atlas Instance
+
+```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();
+```
 
-// Delete page
-await sybil.pages.delete('page-id');
+### Nexus Instance
 
-// Upload file (for use in pages)
-const upload = await sybil.pages.upload(file);
-console.log(upload.url); // Use this URL in image blocks
+```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();
 ```
 
-### Documents
+## Debugging with Logs
+
+Enable logging to debug issues:
 
 ```typescript
-// Process a document
-const result = await sybil.documents.process(file, {
-  fileName: 'document.pdf',
-  metadata: { category: 'reports' }
+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);
+    },
+  },
 });
 
-// Check processing status
-const status = await sybil.documents.status(result.documentId);
+// Get all logs
+const logs = atlas.getLogs();
 
-// Wait for processing to complete (polling)
-const document = await sybil.documents.waitForProcessing(result.documentId, {
-  maxAttempts: 60,
-  interval: 3000
-});
+// Clear logs
+atlas.clearLogs();
+```
+
+## Standalone Clients
 
-// List documents
-const { documents, pagination } = await sybil.documents.list({
-  status: 'processed',
-  fileType: 'application/pdf',
-  search: 'quarterly report'
+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',
 });
 
-// Get document with content
-const { document } = await sybil.documents.get('doc-id', {
-  includeContent: true,
-  includeInsights: true
+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',
 });
 
-// Get document insights
-const { insights, semanticAnalysis } = await sybil.documents.insights('doc-id');
+const files = await nexus.listFiles('folder-id');
+const folder = await nexus.createFolder('New Folder');
+```
+
+## Legacy APIs
+
+### Documents
+
+```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);
 
-// Delete document
-await sybil.documents.delete('doc-id');
+// Get insights
+const { insights } = await sybil.documents.insights('doc-id');
 ```
 
 ### YouTube
@@ -138,106 +450,81 @@ await sybil.documents.delete('doc-id');
 // Process YouTube video
 const result = await sybil.youtube.process('https://youtube.com/watch?v=...');
 
-// List processed videos
-const { videos } = await sybil.youtube.list({ limit: 20 });
-
-// Get video details with transcript
+// Get video with transcript
 const { video } = await sybil.youtube.get('VIDEO_ID', {
   includeTranscript: true,
-  includeChunks: true
 });
-
-// Delete video
-await sybil.youtube.delete('VIDEO_ID');
 ```
 
 ### Chat (RAG)
 
 ```typescript
-// Simple chat
+// Chat with document
 const result = await sybil.chat.send('document-id', 'What are the key findings?');
 
-// Chat with options
-const result = await sybil.chat.send({
-  documentId: 'document-id',
-  query: 'Explain the methodology',
-  conversationHistory: [
-    { role: 'user', content: 'Previous question' },
-    { role: 'assistant', content: 'Previous answer' }
-  ],
-  searchConfig: {
-    semanticWeight: 0.4,
-    maxResults: 15
-  }
-});
-
 console.log(result.response);
-console.log(result.sources); // Relevant passages
-console.log(result.metadata.confidence);
-
-// Get chat history
-const { history } = await sybil.chat.history('document-id', 50);
-```
-
-### Analysis
-
-```typescript
-// Run RAG analysis
-const result = await sybil.analyze.run('document-id');
-
-// Force refresh
-const result = await sybil.analyze.run('document-id', true);
-
-// Get existing analysis (no regeneration)
-const result = await sybil.analyze.get('document-id');
-
-console.log(result.analysis);
-console.log(result.cached); // true if from cache
+console.log(result.sources);
 ```
 
 ## Error Handling
 
 ```typescript
-import { SybilSDK, SybilError } from '@sybil-studio/sdk';
+import { SybilError } from '@sybil-studio-devs/sdk';
 
 try {
-  const result = await sybil.youtube.process('invalid-url');
+  await atlas.createPage({ title: 'New' });
 } catch (error) {
   if (error instanceof SybilError) {
     console.error(`Error ${error.status}: ${error.message}`);
     console.error(`Code: ${error.code}`);
-
-    if (error.status === 429) {
-      // Rate limited - wait and retry
-    }
   }
 }
+
+// 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 for use in your application:
+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,
-  Insight,
-  Block,
-  DocumentStatus,
-  // ... and more
-} from '@sybil-studio/sdk';
+} from '@sybil-studio-devs/sdk';
 ```
 
 ## Browser & Node.js Support
 
-This SDK works in both browser and Node.js environments. It uses the native `fetch` API, which is available in:
-- Modern browsers
-- Node.js 18+
-
-For older Node.js versions, you may need a `fetch` polyfill.
+Works in modern browsers and Node.js 18+.
 
 ## License