@realtimex/sdk 1.0.8 → 1.1.1

package/README.md

@@ -24,8 +24,9 @@ Before using this SDK, ensure your Supabase database is set up:
 ```typescript
 import { RealtimeXSDK } from '@realtimex/sdk';
 
-// No config needed - RTX_APP_ID is auto-detected from environment
-const sdk = new RealtimeXSDK();
+const sdk = new RealtimeXSDK({
+  permissions: ['activities.read', 'activities.write', 'webhook.trigger']
+});
 
 // Insert activity
 const activity = await sdk.activities.insert({
@@ -119,6 +120,158 @@ const threads = await sdk.api.getThreads('sales');
 const task = await sdk.api.getTask('task-uuid');
 ```
 
+### LLM Module
+
+Access AI capabilities through the RealtimeX proxy:
+
+```typescript
+const sdk = new RealtimeXSDK({
+  permissions: ['llm.chat', 'llm.embed', 'llm.providers', 'vectors.write', 'vectors.read']
+});
+```
+
+#### List Providers & Models
+
+```typescript
+const { llm, embedding } = await sdk.llm.getProviders();
+// llm[]: Array of LLM providers with models
+// embedding[]: Array of embedding providers with models
+```
+
+#### Chat Completion
+
+```typescript
+// Sync Chat
+const response = await sdk.llm.chat(
+  [
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'What is RealtimeX?' }
+  ],
+  { 
+    model: 'gpt-4o',           // Optional: specific model
+    provider: 'openai',        // Optional: specific provider
+    temperature: 0.7,          // Optional: 0.0-2.0
+    max_tokens: 1000           // Optional: max response tokens
+  }
+);
+console.log(response.response?.content);
+
+// Streaming Chat
+for await (const chunk of sdk.llm.chatStream(messages, options)) {
+  process.stdout.write(chunk.textResponse || '');
+}
+```
+
+#### Generate Embeddings
+
+```typescript
+const { embeddings, dimensions, provider, model } = await sdk.llm.embed(
+  ['Hello world', 'Goodbye'],
+  { provider: 'openai', model: 'text-embedding-3-small' } // Optional
+);
+// embeddings: number[][] - vector arrays
+// dimensions: number - vector dimension (e.g., 1536)
+```
+
+#### Vector Store Operations
+
+```typescript
+// Upsert vectors with metadata
+await sdk.llm.vectors.upsert([
+  { 
+    id: 'chunk-1', 
+    vector: embeddings[0], 
+    metadata: { 
+      text: 'Hello world',      // Original text (for retrieval)
+      documentId: 'doc-1',       // Logical grouping
+      customField: 'any value'   // Any custom metadata
+    } 
+  }
+], { 
+  workspaceId: 'ws-123'          // Optional: physical namespace isolation
+});
+
+// Query similar vectors
+const results = await sdk.llm.vectors.query(queryVector, {
+  topK: 5,                       // Number of results
+  workspaceId: 'ws-123',         // Optional: search in specific workspace
+  filter: { documentId: 'doc-1' } // Optional: filter by document
+});
+// returns: { success, results: [{ id, score, metadata }] }
+
+// List all workspaces for this app
+const { workspaces } = await sdk.llm.vectors.listWorkspaces();
+// returns: { success, workspaces: ['ws-123', 'default', ...] }
+
+// Delete all vectors in a workspace
+await sdk.llm.vectors.delete({ 
+  deleteAll: true, 
+  workspaceId: 'ws-123' 
+});
+```
+
+#### High-Level Helpers
+
+These combine multiple operations for common RAG patterns:
+
+```typescript
+// embedAndStore: Text → Embed → Store (one call)
+await sdk.llm.embedAndStore(
+  ['Document text 1', 'Document text 2'],  // texts to embed
+  {
+    documentId: 'doc-123',                  // Optional: logical grouping
+    workspaceId: 'ws-456',                  // Optional: physical isolation
+    provider: 'openai',                     // Optional: embedding provider
+    model: 'text-embedding-3-small'         // Optional: embedding model
+  }
+);
+
+// search: Query → Embed → Search (one call)
+const searchResults = await sdk.llm.search(
+  'What is RealtimeX?',                     // search query (text, not vector)
+  {
+    topK: 5,                                // Number of results
+    workspaceId: 'ws-123',                  // Optional: search in workspace
+    documentId: 'doc-1',                    // Optional: filter by document
+    provider: 'openai',                     // Optional: embedding provider
+    model: 'text-embedding-3-small'         // Optional: embedding model
+  }
+);
+// returns: [{ id, score, metadata: { text, documentId, ... } }]
+```
+
+> **Note on Isolation:**
+> - `workspaceId`: Creates **physical namespace** (`sdk_{appId}_{wsId}`) - data completely isolated
+> - `documentId`: Stored as **metadata**, filtered after search (post-filter)
+
+### Error Handling
+
+The SDK provides specific error classes for handling LLM-related issues:
+
+```typescript
+import { LLMPermissionError, LLMProviderError } from '@realtimex/sdk';
+
+try {
+  for await (const chunk of sdk.llm.chatStream(messages)) {
+    process.stdout.write(chunk.textResponse || '');
+  }
+} catch (error) {
+  if (error instanceof LLMPermissionError) {
+    // Permission not granted: 'llm.chat' etc.
+    console.error(`Permission required: ${error.permission}`);
+  } else if (error instanceof LLMProviderError) {
+    // Provider errors: rate limit, timeout, model unavailable, etc.
+    console.error(`Provider error: ${error.message} (code: ${error.code})`);
+    // Common codes: LLM_STREAM_ERROR, RATE_LIMIT, PROVIDER_UNAVAILABLE
+  }
+}
+```
+
+| Error Class | Common Codes | Description |
+|-------------|--------------|-------------|
+| `LLMPermissionError` | `PERMISSION_REQUIRED` | Missing or denied permission |
+| `LLMProviderError` | `LLM_STREAM_ERROR`, `RATE_LIMIT`, `PROVIDER_UNAVAILABLE` | AI provider issues |
+
 ## Environment Variables
 
 | Variable | Description |

package/dist/index.d.mts

@@ -8,6 +8,7 @@ interface SDKConfig {
         appName?: string;
     };
     defaultPort?: number;
+    permissions?: string[];
 }
 interface Activity {
     id: string;
@@ -86,7 +87,12 @@ interface Task {
 declare class ActivitiesModule {
     private baseUrl;
     private appId;
-    constructor(realtimexUrl: string, appId: string);
+    private appName;
+    constructor(realtimexUrl: string, appId: string, appName?: string);
+    /**
+     * Request a single permission from Electron via internal API
+     */
+    private requestPermission;
     private request;
     /**
      * Insert a new activity
@@ -114,15 +120,16 @@ declare class ActivitiesModule {
     }): Promise<Activity[]>;
 }
 
-/**
- * Webhook Module - Call RealtimeX webhook
- */
-
 declare class WebhookModule {
     private realtimexUrl;
     private appName?;
     private appId?;
     constructor(realtimexUrl: string, appName?: string, appId?: string);
+    /**
+     * Request a single permission from Electron via internal API
+     */
+    private requestPermission;
+    private request;
     triggerAgent(payload: TriggerAgentPayload): Promise<TriggerAgentResponse>;
     ping(): Promise<{
         success: boolean;
@@ -135,11 +142,34 @@ declare class WebhookModule {
  * API Module - Call RealtimeX public APIs
  */
 
+/**
+ * Error thrown when a permission is permanently denied
+ */
+declare class PermissionDeniedError extends Error {
+    readonly permission: string;
+    constructor(permission: string, message?: string);
+}
+/**
+ * Error thrown when a permission needs to be granted
+ */
+declare class PermissionRequiredError extends Error {
+    readonly permission: string;
+    constructor(permission: string, message?: string);
+}
 declare class ApiModule {
     private realtimexUrl;
     private appId;
-    constructor(realtimexUrl: string, appId: string);
+    private appName;
+    constructor(realtimexUrl: string, appId: string, appName?: string);
     private getHeaders;
+    /**
+     * Request a single permission from Electron via internal API
+     */
+    private requestPermission;
+    /**
+     * Make an API call with automatic permission handling
+     */
+    private apiCall;
     getAgents(): Promise<Agent[]>;
     getWorkspaces(): Promise<Workspace[]>;
     getThreads(workspaceSlug: string): Promise<Thread[]>;
@@ -219,6 +249,297 @@ declare class PortModule {
     getPort(): Promise<number>;
 }
 
+/**
+ * LLM Module for RealtimeX SDK
+ *
+ * Provides access to LLM capabilities:
+ * - Chat completion (sync and streaming)
+ * - Embedding generation
+ * - Provider/model listing
+ * - Vector storage (upsert, query, delete)
+ */
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+interface ChatOptions {
+    model?: string;
+    provider?: string;
+    temperature?: number;
+    max_tokens?: number;
+}
+interface ChatResponse {
+    success: boolean;
+    response?: {
+        content: string;
+        model: string;
+        provider?: string;
+        metrics?: {
+            prompt_tokens: number;
+            completion_tokens: number;
+            total_tokens: number;
+            duration?: number;
+            outputTps?: number;
+        };
+    };
+    error?: string;
+    code?: string;
+}
+interface StreamChunk {
+    uuid?: string;
+    type?: string;
+    textResponse?: string;
+    close?: boolean;
+    error?: boolean;
+}
+interface EmbedOptions {
+    provider?: string;
+    model?: string;
+}
+interface EmbedResponse {
+    success: boolean;
+    embeddings?: number[][];
+    provider?: string;
+    model?: string;
+    dimensions?: number;
+    error?: string;
+    code?: string;
+    errors?: string[];
+}
+interface Provider {
+    provider: string;
+    models: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+interface ProvidersResponse {
+    success: boolean;
+    llm?: Provider[];
+    embedding?: Provider[];
+    error?: string;
+    code?: string;
+}
+interface VectorRecord {
+    id: string;
+    vector: number[];
+    metadata?: {
+        text?: string;
+        documentId?: string;
+        workspaceId?: string;
+        [key: string]: unknown;
+    };
+}
+interface VectorUpsertOptions {
+    workspaceId?: string;
+}
+interface VectorUpsertResponse {
+    success: boolean;
+    upserted?: number;
+    namespace?: string;
+    error?: string;
+    code?: string;
+    errors?: string[];
+}
+interface VectorQueryOptions {
+    topK?: number;
+    filter?: {
+        workspaceId?: string;
+        documentId?: string;
+    };
+    workspaceId?: string;
+    provider?: string;
+    model?: string;
+}
+interface VectorQueryResult {
+    id: string;
+    score: number;
+    metadata?: {
+        text?: string;
+        documentId?: string;
+        workspaceId?: string;
+        [key: string]: unknown;
+    };
+}
+interface VectorQueryResponse {
+    success: boolean;
+    results?: VectorQueryResult[];
+    error?: string;
+    code?: string;
+}
+interface VectorDeleteOptions {
+    workspaceId?: string;
+    deleteAll: true;
+}
+interface VectorDeleteResponse {
+    success: boolean;
+    deleted?: number;
+    message?: string;
+    error?: string;
+    code?: string;
+    errors?: string[];
+}
+interface VectorListWorkspacesResponse {
+    success: boolean;
+    workspaces?: string[];
+    error?: string;
+    code?: string;
+}
+declare class LLMPermissionError extends Error {
+    permission: string;
+    code: string;
+    constructor(permission: string, code?: string);
+}
+declare class LLMProviderError extends Error {
+    code: string;
+    constructor(message: string, code?: string);
+}
+declare class VectorStore {
+    private baseUrl;
+    private appId;
+    constructor(baseUrl: string, appId: string);
+    private get headers();
+    /**
+     * Upsert (insert or update) vectors into storage
+     *
+     * @example
+     * ```ts
+     * await sdk.llm.vectors.upsert([
+     *   { id: 'chunk-1', vector: embeddings[0], metadata: { text: 'Hello', documentId: 'doc-1' } }
+     * ], { workspaceId: 'ws-123' });
+     * ```
+     */
+    upsert(vectors: VectorRecord[], options?: VectorUpsertOptions): Promise<VectorUpsertResponse>;
+    /**
+     * Query similar vectors by embedding
+     *
+     * @example
+     * ```ts
+     * const results = await sdk.llm.vectors.query(queryVector, {
+     *   topK: 5,
+     *   filter: { documentId: 'doc-1' },
+     *   workspaceId: 'ws-123'
+     * });
+     * ```
+     */
+    query(vector: number[], options?: VectorQueryOptions): Promise<VectorQueryResponse>;
+    /**
+     * Delete vectors from storage
+     *
+     * Note: Currently only supports deleteAll: true
+     * Use workspaceId to scope deletion to a specific workspace
+     *
+     * @example
+     * ```ts
+     * await sdk.llm.vectors.delete({ deleteAll: true, workspaceId: 'ws-123' });
+     * ```
+     */
+    delete(options: VectorDeleteOptions): Promise<VectorDeleteResponse>;
+    /**
+     * List all available workspaces (namespaces) for this app
+     *
+     * @example
+     * ```ts
+     * const { workspaces } = await sdk.llm.vectors.listWorkspaces();
+     * console.log('Workspaces:', workspaces);
+     * ```
+     */
+    listWorkspaces(): Promise<VectorListWorkspacesResponse>;
+}
+declare class LLMModule {
+    private baseUrl;
+    private appId;
+    vectors: VectorStore;
+    constructor(baseUrl: string, appId: string);
+    private get headers();
+    /**
+     * Get available LLM and embedding providers/models
+     *
+     * @example
+     * ```ts
+     * const { llm, embedding } = await sdk.llm.getProviders();
+     * console.log('Available LLM models:', llm[0].models);
+     * ```
+     */
+    getProviders(): Promise<ProvidersResponse>;
+    /**
+     * Send a chat completion request (synchronous)
+     *
+     * @example
+     * ```ts
+     * const response = await sdk.llm.chat([
+     *   { role: 'system', content: 'You are a helpful assistant.' },
+     *   { role: 'user', content: 'Hello!' }
+     * ], { model: 'gpt-4o', temperature: 0.7 });
+     *
+     * console.log(response.response?.content);
+     * ```
+     */
+    chat(messages: ChatMessage[], options?: ChatOptions): Promise<ChatResponse>;
+    /**
+     * Send a streaming chat completion request (SSE)
+     *
+     * @example
+     * ```ts
+     * for await (const chunk of sdk.llm.chatStream([
+     *   { role: 'user', content: 'Tell me a story' }
+     * ])) {
+     *   process.stdout.write(chunk.textResponse || '');
+     * }
+     * ```
+     */
+    chatStream(messages: ChatMessage[], options?: ChatOptions): AsyncGenerator<StreamChunk, void, unknown>;
+    /**
+     * Generate vector embeddings from text
+     *
+     * @example
+     * ```ts
+     * // Single text
+     * const { embeddings } = await sdk.llm.embed('Hello world');
+     *
+     * // Multiple texts
+     * const { embeddings } = await sdk.llm.embed(['Hello', 'World']);
+     * ```
+     */
+    embed(input: string | string[], options?: EmbedOptions): Promise<EmbedResponse>;
+    /**
+     * Helper: Embed text and store as vectors in one call
+     *
+     * @example
+     * ```ts
+     * await sdk.llm.embedAndStore({
+     *   texts: ['Hello world', 'Goodbye world'],
+     *   documentId: 'doc-123',
+     *   workspaceId: 'ws-456'
+     * });
+     * ```
+     */
+    embedAndStore(params: {
+        texts: string[];
+        documentId?: string;
+        workspaceId?: string;
+        idPrefix?: string;
+        provider?: string;
+        model?: string;
+    }): Promise<VectorUpsertResponse>;
+    /**
+     * Helper: Search similar documents by text query
+     *
+     * @example
+     * ```ts
+     * const results = await sdk.llm.search('What is RealtimeX?', {
+     *   topK: 5,
+     *   workspaceId: 'ws-123'
+     * });
+     *
+     * for (const result of results) {
+     *   console.log(result.metadata?.text, result.score);
+     * }
+     * ```
+     */
+    search(query: string, options?: VectorQueryOptions): Promise<VectorQueryResult[]>;
+}
+
 /**
  * RealtimeX Local App SDK
  *
@@ -232,14 +553,22 @@ declare class RealtimeXSDK {
     api: ApiModule;
     task: TaskModule;
     port: PortModule;
+    llm: LLMModule;
     readonly appId: string;
     readonly appName: string | undefined;
+    private readonly realtimexUrl;
+    private readonly permissions;
     private static DEFAULT_REALTIMEX_URL;
     constructor(config?: SDKConfig);
+    /**
+     * Register app with RealtimeX hub and request declared permissions upfront.
+     * This is called automatically if permissions are provided in constructor.
+     */
+    register(permissions?: string[]): Promise<void>;
     /**
      * Get environment variable (works in Node.js and browser)
      */
     private getEnvVar;
 }
 
-export { ActivitiesModule, type Activity, type Agent, ApiModule, PortModule, RealtimeXSDK, type SDKConfig, type Task, TaskModule, type TaskRun, type Thread, type TriggerAgentPayload, type TriggerAgentResponse, WebhookModule, type Workspace };
+export { ActivitiesModule, type Activity, type Agent, ApiModule, type ChatMessage, type ChatOptions, type ChatResponse, type EmbedOptions, type EmbedResponse, LLMModule, LLMPermissionError, LLMProviderError, PermissionDeniedError, PermissionRequiredError, PortModule, type Provider, type ProvidersResponse, RealtimeXSDK, type SDKConfig, type StreamChunk, type Task, TaskModule, type TaskRun, type Thread, type TriggerAgentPayload, type TriggerAgentResponse, type VectorDeleteOptions, type VectorDeleteResponse, type VectorQueryOptions, type VectorQueryResponse, type VectorQueryResult, type VectorRecord, VectorStore, type VectorUpsertOptions, type VectorUpsertResponse, WebhookModule, type Workspace };