@sybil-studio-devs/sdk 0.1.0

package/README.md

@@ -0,0 +1,244 @@
+# @sybil-studio/sdk
+
+Official TypeScript/JavaScript SDK for Sybil AI - Document processing, YouTube analysis, and AI-powered knowledge management.
+
+## Installation
+
+```bash
+# npm
+npm install @sybil-studio/sdk
+
+# pnpm
+pnpm add @sybil-studio/sdk
+
+# yarn
+yarn add @sybil-studio/sdk
+```
+
+## Quick Start
+
+```typescript
+import { SybilSDK } from '@sybil-studio/sdk';
+
+const sybil = new SybilSDK('sk_live_YOUR_API_KEY');
+
+// Process a YouTube video
+const video = await sybil.youtube.process('https://youtube.com/watch?v=...');
+
+// Chat with a document
+const response = await sybil.chat.send(video.document.id, 'Summarize the main points');
+
+// Create a page
+const page = await sybil.pages.create({
+  title: 'My Notes',
+  blocks: [
+    { type: 'paragraph', content: [{ type: 'text', text: 'Hello world' }] }
+  ]
+});
+```
+
+## Configuration
+
+```typescript
+// Simple - just API key (uses default base URL)
+const sybil = new SybilSDK('sk_live_YOUR_API_KEY');
+
+// Full configuration
+const sybil = new SybilSDK({
+  apiKey: 'sk_live_YOUR_API_KEY',
+  baseUrl: 'https://your-domain.com/api/sdk/v1', // Optional
+  timeout: 30000, // Optional, in milliseconds
+});
+```
+
+## API Reference
+
+### Pages
+
+```typescript
+// List pages
+const { pages, pagination } = await sybil.pages.list({
+  limit: 20,
+  offset: 0,
+  parent_id: 'root', // or specific page ID
+  is_published: true
+});
+
+// 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'
+});
+
+// Get page
+const { page } = await sybil.pages.get('page-id');
+
+// Update page
+const { page } = await sybil.pages.update('page-id', {
+  title: 'Updated Title',
+  blocks: [...],
+  is_published: true
+});
+
+// Delete page
+await sybil.pages.delete('page-id');
+
+// Upload file (for use in pages)
+const upload = await sybil.pages.upload(file);
+console.log(upload.url); // Use this URL in image blocks
+```
+
+### Documents
+
+```typescript
+// Process a document
+const result = await sybil.documents.process(file, {
+  fileName: 'document.pdf',
+  metadata: { category: 'reports' }
+});
+
+// Check processing status
+const status = await sybil.documents.status(result.documentId);
+
+// Wait for processing to complete (polling)
+const document = await sybil.documents.waitForProcessing(result.documentId, {
+  maxAttempts: 60,
+  interval: 3000
+});
+
+// List documents
+const { documents, pagination } = await sybil.documents.list({
+  status: 'processed',
+  fileType: 'application/pdf',
+  search: 'quarterly report'
+});
+
+// Get document with content
+const { document } = await sybil.documents.get('doc-id', {
+  includeContent: true,
+  includeInsights: true
+});
+
+// Get document insights
+const { insights, semanticAnalysis } = await sybil.documents.insights('doc-id');
+
+// Delete document
+await sybil.documents.delete('doc-id');
+```
+
+### YouTube
+
+```typescript
+// 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
+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
+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
+```
+
+## Error Handling
+
+```typescript
+import { SybilSDK, SybilError } from '@sybil-studio/sdk';
+
+try {
+  const result = await sybil.youtube.process('invalid-url');
+} 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
+    }
+  }
+}
+```
+
+## TypeScript Types
+
+All types are exported for use in your application:
+
+```typescript
+import type {
+  Page,
+  Document,
+  YouTubeVideo,
+  ChatResult,
+  Insight,
+  Block,
+  DocumentStatus,
+  // ... and more
+} from '@sybil-studio/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.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,396 @@
+interface SybilConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+interface RateLimitInfo {
+    limit: number;
+    remaining: number;
+    resetAt: string;
+}
+interface ApiResponse<T> {
+    data: T;
+    meta?: {
+        rateLimit?: RateLimitInfo;
+    };
+}
+interface ApiError {
+    error: {
+        message: string;
+        code?: string;
+    };
+}
+interface PaginationParams {
+    limit?: number;
+    offset?: number;
+}
+interface Pagination {
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+}
+interface Block {
+    type: string;
+    content?: Array<{
+        type: string;
+        text?: string;
+        [key: string]: any;
+    }>;
+    attrs?: Record<string, any>;
+    [key: string]: any;
+}
+interface Page {
+    id: string;
+    title: string;
+    slug: string;
+    description?: string;
+    blocks: Block[];
+    artifact_map?: Record<string, any>;
+    parent_id?: string | null;
+    is_published: boolean;
+    is_template: boolean;
+    version: number;
+    created_at: string;
+    updated_at: string;
+    metadata?: Record<string, any>;
+}
+interface CreatePageParams {
+    title?: string;
+    slug?: string;
+    description?: string;
+    blocks?: Block[];
+    parent_id?: string;
+}
+interface UpdatePageParams {
+    title?: string;
+    slug?: string;
+    description?: string | null;
+    blocks?: Block[];
+    is_published?: boolean;
+    parent_id?: string | null;
+}
+interface ListPagesParams extends PaginationParams {
+    parent_id?: string | 'root';
+    is_published?: boolean;
+}
+interface UploadResult {
+    url: string;
+    fileName: string;
+    fileSize: number;
+    mimeType: string;
+    path: string;
+}
+interface Document {
+    id: string;
+    title: string;
+    fileName: string;
+    fileType: string;
+    mimeType?: string;
+    fileSize: number;
+    status: DocumentStatus;
+    sourceUrl?: string;
+    sourceType?: string;
+    content?: string;
+    contentPreview?: string;
+    insights?: Insight[];
+    metadata?: DocumentMetadata;
+    createdAt: string;
+    updatedAt: string;
+    processedAt?: string;
+}
+type DocumentStatus = 'pending' | 'uploading' | 'processing' | 'extracting' | 'indexing' | 'processed' | 'completed' | 'failed';
+interface DocumentMetadata {
+    title?: string;
+    fileName?: string;
+    fileType?: string;
+    fileSize?: number;
+    documentType?: string;
+    category?: string;
+    keywords?: string[];
+    language?: string;
+    pageCount?: number;
+    wordCount?: number;
+    hasTranscript?: boolean;
+    semanticAnalysis?: SemanticAnalysis;
+}
+interface SemanticAnalysis {
+    topics?: string[];
+    entities?: Record<string, any[]>;
+    keyphrases?: string[];
+    domainTerms?: string[];
+}
+interface Insight {
+    id: string;
+    type: string;
+    title?: string;
+    content: string;
+    confidence?: number;
+    data?: any;
+    created_at?: string;
+}
+interface ProcessDocumentResult {
+    success: boolean;
+    documentId: string;
+    status: DocumentStatus;
+    message: string;
+    metadata: DocumentMetadata;
+    contentPreview?: string;
+    insights: Insight[];
+    processingTime: number;
+}
+interface DocumentStatusResult {
+    documentId: string;
+    status: DocumentStatus;
+    progress: number;
+    message: string;
+    startedAt?: string;
+    completedAt?: string;
+    error?: any;
+    hasInsights: boolean;
+    insightsCount: number;
+}
+interface ListDocumentsParams extends PaginationParams {
+    status?: DocumentStatus;
+    fileType?: string;
+    search?: string;
+}
+interface GetDocumentParams {
+    includeContent?: boolean;
+    includeInsights?: boolean;
+    includeMetadata?: boolean;
+}
+interface YouTubeVideo {
+    id: string;
+    videoId: string;
+    documentId: string;
+    title: string;
+    description?: string;
+    channelTitle: string;
+    channelId: string;
+    tags?: string[];
+    publishedAt: string;
+    duration: string;
+    viewCount: number;
+    likeCount: number;
+    commentCount: number;
+    thumbnailUrl: string;
+    transcriptAvailable: boolean;
+    transcriptLanguage?: string;
+    wordCount: number;
+    readingTime: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ProcessYouTubeResult {
+    status: 'success' | 'exists';
+    document: {
+        id: string;
+        title: string;
+        workspace_id: string;
+        source_url: string;
+        created_at: string;
+    };
+    video: {
+        videoId: string;
+        title: string;
+        channelTitle: string;
+        duration: string;
+        viewCount: number;
+        hasTranscript: boolean;
+    };
+    transcript: {
+        available: boolean;
+        wordCount: number;
+        chunkCount: number;
+    };
+    insights: {
+        count: number;
+        types: string[];
+    };
+    message: string;
+}
+interface GetYouTubeVideoParams {
+    includeTranscript?: boolean;
+    includeChunks?: boolean;
+    includeInsights?: boolean;
+}
+interface TranscriptChunk {
+    index: number;
+    startTime: number;
+    endTime: number;
+    content: string;
+    metadata?: Record<string, any>;
+}
+interface YouTubeVideoDetail extends YouTubeVideo {
+    transcript?: string;
+    chunks?: TranscriptChunk[];
+    insights?: Insight[];
+    semanticAnalysis?: SemanticAnalysis;
+}
+interface ChatMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+interface ChatParams {
+    query: string;
+    documentId: string;
+    conversationHistory?: ChatMessage[];
+    searchConfig?: {
+        semanticWeight?: number;
+        keywordWeight?: number;
+        maxResults?: number;
+        confidenceThreshold?: number;
+    };
+}
+interface ChatSource {
+    content: string;
+    similarity: number;
+    metadata?: Record<string, any>;
+}
+interface ChatResult {
+    response: string;
+    sources: ChatSource[];
+    metadata: {
+        documentId: string;
+        documentTitle: string;
+        sourcesCount: number;
+        confidence: number;
+        requestId: string;
+    };
+}
+interface ChatHistoryItem {
+    id: string;
+    query: string;
+    response: string;
+    type: string;
+    createdAt: string;
+    metadata?: Record<string, any>;
+}
+interface AnalyzeParams {
+    documentId: string;
+    forceRefresh?: boolean;
+}
+interface AnalysisResult {
+    analysis: any;
+    cached: boolean;
+    generatedAt: string;
+    document: {
+        id: string;
+        title: string;
+    };
+}
+
+declare class SybilSDK {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    pages: PagesAPI;
+    documents: DocumentsAPI;
+    youtube: YouTubeAPI;
+    chat: ChatAPI;
+    analyze: AnalyzeAPI;
+    constructor(config: string | SybilConfig);
+    request<T>(endpoint: string, options?: RequestInit): Promise<T>;
+}
+declare class SybilError extends Error {
+    status: number;
+    code?: string;
+    constructor(message: string, status: number, code?: string);
+}
+declare class PagesAPI {
+    private client;
+    constructor(client: SybilSDK);
+    list(params?: ListPagesParams): Promise<{
+        pages: Page[];
+        pagination: Pagination;
+    }>;
+    get(pageId: string): Promise<{
+        page: Page;
+    }>;
+    create(params?: CreatePageParams): Promise<{
+        page: Page;
+    }>;
+    update(pageId: string, params: UpdatePageParams): Promise<{
+        page: Page;
+    }>;
+    delete(pageId: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    upload(file: File | Blob, fileName?: string): Promise<UploadResult>;
+    deleteFile(filePath: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+}
+declare class DocumentsAPI {
+    private client;
+    constructor(client: SybilSDK);
+    list(params?: ListDocumentsParams): Promise<{
+        documents: Document[];
+        pagination: Pagination;
+    }>;
+    get(documentId: string, params?: GetDocumentParams): Promise<{
+        document: Document;
+    }>;
+    process(file: File | Blob, options?: {
+        fileName?: string;
+        metadata?: Record<string, any>;
+        collectionId?: string;
+    }): Promise<ProcessDocumentResult>;
+    status(documentId: string): Promise<DocumentStatusResult>;
+    insights(documentId: string, type?: string): Promise<{
+        documentId: string;
+        insights: Insight[];
+        semanticAnalysis?: any;
+    }>;
+    delete(documentId: string): Promise<{
+        success: boolean;
+        message: string;
+        documentId: string;
+    }>;
+    waitForProcessing(documentId: string, options?: {
+        maxAttempts?: number;
+        interval?: number;
+    }): Promise<Document>;
+}
+declare class YouTubeAPI {
+    private client;
+    constructor(client: SybilSDK);
+    list(params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        videos: YouTubeVideo[];
+        pagination: Pagination;
+    }>;
+    process(url: string, collectionId?: string): Promise<ProcessYouTubeResult>;
+    get(videoId: string, params?: GetYouTubeVideoParams): Promise<{
+        video: YouTubeVideoDetail;
+    }>;
+    delete(videoId: string): Promise<{
+        success: boolean;
+        message: string;
+        videoId: string;
+    }>;
+}
+declare class ChatAPI {
+    private client;
+    constructor(client: SybilSDK);
+    send(params: ChatParams): Promise<ChatResult>;
+    send(documentId: string, query: string): Promise<ChatResult>;
+    history(documentId: string, limit?: number): Promise<{
+        history: ChatHistoryItem[];
+        total: number;
+    }>;
+}
+declare class AnalyzeAPI {
+    private client;
+    constructor(client: SybilSDK);
+    run(params: AnalyzeParams): Promise<AnalysisResult>;
+    run(documentId: string, forceRefresh?: boolean): Promise<AnalysisResult>;
+    get(documentId: string): Promise<AnalysisResult>;
+}
+
+export { type AnalysisResult, type AnalyzeParams, type ApiError, type ApiResponse, type Block, type ChatHistoryItem, type ChatMessage, type ChatParams, type ChatResult, type ChatSource, type CreatePageParams, type Document, type DocumentMetadata, type DocumentStatus, type DocumentStatusResult, type GetDocumentParams, type GetYouTubeVideoParams, type Insight, type ListDocumentsParams, type ListPagesParams, type Page, type Pagination, type PaginationParams, type ProcessDocumentResult, type ProcessYouTubeResult, type RateLimitInfo, type SemanticAnalysis, type SybilConfig, SybilError, SybilSDK, type TranscriptChunk, type UpdatePageParams, type UploadResult, type YouTubeVideo, type YouTubeVideoDetail, SybilSDK as default };