@omnikit-ai/sdk 2.2.1 → 2.2.3

package/dist/index.d.mts

@@ -10,7 +10,7 @@ export { cleanTokenFromUrl, getAccessToken, isTokenInUrl, removeAccessToken, sav
  * SECURITY: getAccessToken requires service token authentication.
  * Only available to backend functions, not frontend code.
  */
-type ConnectorType = 'slack' | 'google_calendar' | 'gmail' | 'notion' | 'salesforce';
+type ConnectorType = 'slack' | 'google_calendar' | 'gmail' | 'google_sheets' | 'notion' | 'salesforce';
 interface ConnectorAccessTokenResponse {
     success: boolean;
     access_token: string;
@@ -178,7 +178,30 @@ interface AppSchema {
     platform_version?: number;
 }
 /**
- * MongoDB-style list options (Mongoose-compatible)
+ * Paginated response for cursor-based pagination (Google/Notion style)
+ * Returned by list() and filter() methods
+ *
+ * @example
+ * ```typescript
+ * // First page
+ * const page1 = await Task.list({}, { limit: 100 });
+ * // page1 = { data: [...], hasMore: true, nextCursor: "abc123" }
+ *
+ * // Next page
+ * const page2 = await Task.list({}, { limit: 100, after: page1.nextCursor });
+ * // page2 = { data: [...], hasMore: false, nextCursor: null }
+ * ```
+ */
+interface PaginatedResult<T = CollectionRecord> {
+    /** Array of records for this page */
+    data: T[];
+    /** Whether there are more records after this page */
+    hasMore: boolean;
+    /** Cursor to pass to 'after' parameter for next page (null if no more pages) */
+    nextCursor: string | null;
+}
+/**
+ * MongoDB-style list options with cursor-based pagination
  * Used in the second parameter of list(filter, options)
  *
  * @example
@@ -189,17 +212,29 @@ interface AppSchema {
  * // Sort descending by timestamp
  * await Entity.list({}, { sort: { timestamp: -1 } })
  *
- * // With pagination
+ * // Cursor-based pagination (RECOMMENDED for large datasets)
+ * const page1 = await Entity.list({}, { limit: 100 });
+ * const page2 = await Entity.list({}, { limit: 100, after: page1.nextCursor });
+ *
+ * // Legacy offset pagination (still supported)
  * await Entity.list({}, { sort: { created_at: -1 }, limit: 20, offset: 10 })
  * ```
  */
 interface ListOptions {
     /** Sort order: { field: 1 } for ascending, { field: -1 } for descending. Also accepts string format: 'field' or '-field' */
     sort?: Record<string, 1 | -1> | string;
-    /** Maximum number of results to return */
+    /** Maximum number of results to return (default: 100) */
     limit?: number;
-    /** Number of results to skip (for pagination) */
+    /**
+     * Number of results to skip (for offset-based pagination)
+     * @deprecated Use 'after' cursor for better performance on large datasets
+     */
     offset?: number;
+    /**
+     * Cursor for pagination - pass nextCursor from previous response
+     * More efficient than offset for large datasets (O(1) vs O(n))
+     */
+    after?: string;
 }
 /**
  * @deprecated Use separate filter and ListOptions parameters instead
@@ -285,13 +320,28 @@ interface EmailParams {
     from_name?: string;
 }
 interface LLMMessage {
-    role: 'system' | 'user' | 'assistant';
+    role: 'system' | 'user' | 'assistant' | 'tool';
     content: string | Array<{
         type: string;
         text?: string;
         file?: any;
         image_url?: any;
     }>;
+    /**
+     * For role="tool" messages - links to the tool_calls[].id from the assistant message.
+     * Required when role is "tool".
+     */
+    tool_call_id?: string;
+    /**
+     * For role="tool" messages - the function name that was called.
+     * Optional but recommended for clarity.
+     */
+    name?: string;
+    /**
+     * For assistant messages - tool calls the assistant wants to make.
+     * Present when the assistant decides to use tools.
+     */
+    tool_calls?: ToolCall[];
 }
 /**
  * Available LLM models:
@@ -347,6 +397,33 @@ interface ToolCall {
     name: string;
     arguments: Record<string, any>;
 }
+/**
+ * Configuration for server-side persistence of LLM results.
+ * When provided, the backend automatically saves the result to the specified collection,
+ * ensuring data is not lost if the user navigates away before polling completes.
+ *
+ * @example
+ * ```typescript
+ * await invokeLLM({
+ *   prompt: 'Analyze this data...',
+ *   saveResult: {
+ *     collection: 'analysis_results',
+ *     field: 'result',
+ *     additionalFields: { status: 'completed' }
+ *   }
+ * });
+ * ```
+ */
+interface SaveResultConfig {
+    /** Collection name to save the result to */
+    collection: string;
+    /** Document ID to update. If omitted, creates a new document */
+    documentId?: string;
+    /** Field name to save the LLM result to (default: 'content') */
+    field?: string;
+    /** Additional fields to include when creating/updating the document */
+    additionalFields?: Record<string, any>;
+}
 interface LLMParams {
     /** Message-based format for advanced use */
     messages?: LLMMessage[];
@@ -441,6 +518,25 @@ interface LLMParams {
      * @param toolCall - The tool call with id, name, and arguments
      */
     onToolCall?: (toolCall: ToolCall) => void | Promise<void>;
+    /**
+     * Server-side persistence configuration.
+     * When provided, the backend saves the LLM result directly to the app's database,
+     * ensuring data is not lost if the user navigates away before polling completes.
+     *
+     * @example
+     * ```typescript
+     * await invokeLLM({
+     *   prompt: 'Analyze this data...',
+     *   saveResult: {
+     *     collection: 'analysis_results',
+     *     field: 'result',
+     *     additionalFields: { status: 'completed' }
+     *   }
+     * });
+     * // Result is saved server-side even if user navigates away!
+     * ```
+     */
+    saveResult?: SaveResultConfig;
 }
 /**
  * Grounding chunk from Google Search results
@@ -567,6 +663,14 @@ interface LLMResponse {
      * In non-streaming mode, they are included in the response.
      */
     tool_calls?: ToolCall[];
+    /**
+     * Server-side save result (when saveResult was provided in the request).
+     * Contains the collection and document ID where the result was saved.
+     */
+    saved_to?: {
+        collection: string;
+        document_id: string;
+    };
     /** @deprecated Use google_search_used instead */
     web_search_used?: boolean;
 }
@@ -1399,6 +1503,156 @@ interface IntegrationPackage {
 interface IntegrationSchema {
     installed_packages: IntegrationPackage[];
 }
+/**
+ * Message in an assistant thread
+ */
+interface AssistantMessage {
+    role: 'user' | 'assistant' | 'tool';
+    content: string;
+}
+/**
+ * Action call made by the assistant during execution
+ */
+interface AssistantActionCall {
+    id: string;
+    name: string;
+    arguments: Record<string, any>;
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    output?: any;
+    error?: string;
+}
+/**
+ * Parameters for running an assistant
+ */
+interface AssistantRunParams {
+    /**
+     * Messages to send to the assistant
+     */
+    messages: AssistantMessage[];
+    /**
+     * Optional thread ID to continue an existing conversation.
+     * If not provided, a new thread will be created.
+     */
+    threadId?: string;
+    /**
+     * Callback when a text token is received during streaming
+     */
+    onToken?: (token: string) => void;
+    /**
+     * Callback when an action starts executing
+     */
+    onActionStart?: (action: {
+        id: string;
+        name: string;
+        arguments: Record<string, any>;
+    }) => void;
+    /**
+     * Callback when an action completes successfully
+     */
+    onActionComplete?: (action: {
+        id: string;
+        name: string;
+        output: any;
+    }) => void;
+    /**
+     * Callback when an action fails
+     */
+    onActionFailed?: (action: {
+        id: string;
+        name: string;
+        error: string;
+    }) => void;
+    /**
+     * Callback when the run completes
+     */
+    onComplete?: (result: AssistantRunResult) => void;
+    /**
+     * Callback when an error occurs
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Result from running an assistant
+ */
+interface AssistantRunResult {
+    /** Thread ID (for continuing the conversation) */
+    threadId: string;
+    /** Number of messages in the thread */
+    messageCount: number;
+    /** Full response text from the assistant */
+    response: string;
+}
+/**
+ * Callbacks for thread subscription via WebSocket
+ */
+interface ThreadSubscriptionCallbacks {
+    /**
+     * Called when connection is established
+     */
+    onConnected?: (info: {
+        threadId: string;
+        assistantName: string;
+        messageCount: number;
+    }) => void;
+    /**
+     * Called when a text token is received
+     */
+    onToken?: (token: string) => void;
+    /**
+     * Called when an action starts
+     */
+    onActionStart?: (action: {
+        id: string;
+        name: string;
+        arguments: Record<string, any>;
+    }) => void;
+    /**
+     * Called when an action completes
+     */
+    onActionComplete?: (action: {
+        id: string;
+        name: string;
+        output: any;
+    }) => void;
+    /**
+     * Called when an action fails
+     */
+    onActionFailed?: (action: {
+        id: string;
+        name: string;
+        error: string;
+    }) => void;
+    /**
+     * Called when the run completes
+     */
+    onRunComplete?: (result: {
+        threadId: string;
+        messageCount: number;
+    }) => void;
+    /**
+     * Called when an error occurs
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Called when connection closes
+     */
+    onDisconnect?: () => void;
+}
+/**
+ * SSE event types for assistant streaming
+ */
+interface AssistantStreamEvent {
+    type: 'token' | 'action_start' | 'action_complete' | 'action_failed' | 'done' | 'error';
+    content?: string;
+    id?: string;
+    name?: string;
+    arguments?: Record<string, any>;
+    output?: any;
+    error?: string;
+    message?: string;
+    thread_id?: string;
+    message_count?: number;
+}
 /**
  * Available voice options for Live Voice AI
  */
@@ -1822,6 +2076,63 @@ declare class APIClient implements OmnikitClient {
      * @returns A LiveVoiceSession object to control the session
      */
     createLiveVoiceSession(config?: LiveVoiceConfig): LiveVoiceSession;
+    /**
+     * Run an assistant with streaming response.
+     *
+     * Assistants are server-side AI agents with custom instructions and built-in actions.
+     * They can create/update/delete records, send emails, make HTTP requests, etc.
+     *
+     * @example
+     * ```typescript
+     * const result = await omnikit.runAssistant('customer_support', {
+     *   messages: [{ role: 'user', content: 'Help me track my order #12345' }],
+     *   onToken: (token) => setResponse(prev => prev + token),
+     *   onActionStart: (action) => console.log(`Starting: ${action.name}`),
+     *   onActionComplete: (action) => console.log(`Completed: ${action.name}`),
+     * });
+     *
+     * // Continue the conversation
+     * await omnikit.runAssistant('customer_support', {
+     *   messages: [{ role: 'user', content: 'When will it arrive?' }],
+     *   threadId: result.threadId,
+     *   onToken: (token) => setResponse(prev => prev + token),
+     * });
+     * ```
+     *
+     * @param assistantName - Name of the assistant to run
+     * @param params - Run parameters including messages and callbacks
+     * @returns Promise resolving to the run result with threadId
+     */
+    runAssistant(assistantName: string, params: AssistantRunParams): Promise<AssistantRunResult>;
+    /**
+     * Subscribe to a thread via WebSocket for real-time updates.
+     *
+     * Use this to watch a thread without triggering a run. Useful for:
+     * - Showing live updates when another client runs the assistant
+     * - Reconnecting after page navigation
+     * - Observing thread activity in real-time
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to a thread
+     * const unsubscribe = omnikit.subscribeToThread(threadId, {
+     *   onConnected: (info) => console.log(`Connected to ${info.assistantName}`),
+     *   onToken: (token) => setResponse(prev => prev + token),
+     *   onActionStart: (action) => console.log(`Action: ${action.name}`),
+     *   onActionComplete: (action) => console.log(`Result: ${JSON.stringify(action.output)}`),
+     *   onRunComplete: (result) => console.log(`Run complete, ${result.messageCount} messages`),
+     *   onError: (error) => console.error(error),
+     * });
+     *
+     * // Later: disconnect
+     * unsubscribe();
+     * ```
+     *
+     * @param threadId - Thread ID to subscribe to
+     * @param callbacks - Event callbacks for real-time updates
+     * @returns Unsubscribe function to close the WebSocket
+     */
+    subscribeToThread(threadId: string, callbacks: ThreadSubscriptionCallbacks): () => void;
     /**
      * Invoke a backend function by name.
      *
@@ -2121,4 +2432,4 @@ declare class Analytics {
 }
 declare function createAnalytics(config: AnalyticsConfig): Analytics;
 
-export { APIClient, Analytics, type AnalyticsConfig, type AppMetadata, type AppSchema, type AsyncJobCreatedResponse, type AsyncJobStatus, type AsyncJobStatusResponse, type AsyncJobType, type AsyncOptions, type AuthModule, type AuthResponse, type BuiltInIntegration, type BulkResult, type CachedMetadata, type CheckJobStatusParams, type CollectionClass, type CollectionDefinition, type CollectionField, type CollectionRecord, type ConnectorAccessTokenResponse, type ConnectorStatusResponse, type ConnectorType, type ConnectorsModule, type EmailParams, type Entity, type EntityClass, type EntityDefinition, type EntityField, type EntityRecord, type EventPayload, type ExtractParams, type GroundingChunk, type GroundingMetadata, type GroundingSupport, type ImageParams, type ImportResult, type InitialMetadata, type IntegrationEndpoint, type IntegrationMethod, type IntegrationPackage, type IntegrationSchema, type LLMMessage, type LLMModel, type LLMParams, type LLMResponse, type LLMStreamEvent, type LLMStreamResult, type ListOptions, type LiveVoiceClientMessage, type LiveVoiceConfig, type LiveVoiceServerMessage, type LiveVoiceSession, LiveVoiceSessionImpl, type LiveVoiceStatus, type LiveVoiceVoice, type OAuthProvider, type OAuthProvidersResponse, type OmnikitClient, type OmnikitConfig, OmnikitError, type QueryOptions, type RequestOptions, type SMSParams, type ServiceDefinition, type ServiceResponse, type ServiceRoleClient, type ServicesSchema, type SpeechParams, type TemplateDefinition, type ToolCall, type ToolDefinition, type ToolParameter, type UrlContextMetadata, type UrlMetadata, type UrlRetrievalStatus, type UserCollectionClass, type UserEntityClass, type UserInfo, type VideoParams, type VideoStatusParams, createAnalytics, createClient, createClientFromRequest, createServerClient };
+export { APIClient, Analytics, type AnalyticsConfig, type AppMetadata, type AppSchema, type AssistantActionCall, type AssistantMessage, type AssistantRunParams, type AssistantRunResult, type AssistantStreamEvent, type AsyncJobCreatedResponse, type AsyncJobStatus, type AsyncJobStatusResponse, type AsyncJobType, type AsyncOptions, type AuthModule, type AuthResponse, type BuiltInIntegration, type BulkResult, type CachedMetadata, type CheckJobStatusParams, type CollectionClass, type CollectionDefinition, type CollectionField, type CollectionRecord, type ConnectorAccessTokenResponse, type ConnectorStatusResponse, type ConnectorType, type ConnectorsModule, type EmailParams, type Entity, type EntityClass, type EntityDefinition, type EntityField, type EntityRecord, type EventPayload, type ExtractParams, type GroundingChunk, type GroundingMetadata, type GroundingSupport, type ImageParams, type ImportResult, type InitialMetadata, type IntegrationEndpoint, type IntegrationMethod, type IntegrationPackage, type IntegrationSchema, type LLMMessage, type LLMModel, type LLMParams, type LLMResponse, type LLMStreamEvent, type LLMStreamResult, type ListOptions, type LiveVoiceClientMessage, type LiveVoiceConfig, type LiveVoiceServerMessage, type LiveVoiceSession, LiveVoiceSessionImpl, type LiveVoiceStatus, type LiveVoiceVoice, type OAuthProvider, type OAuthProvidersResponse, type OmnikitClient, type OmnikitConfig, OmnikitError, type PaginatedResult, type QueryOptions, type RequestOptions, type SMSParams, type SaveResultConfig, type ServiceDefinition, type ServiceResponse, type ServiceRoleClient, type ServicesSchema, type SpeechParams, type TemplateDefinition, type ThreadSubscriptionCallbacks, type ToolCall, type ToolDefinition, type ToolParameter, type UrlContextMetadata, type UrlMetadata, type UrlRetrievalStatus, type UserCollectionClass, type UserEntityClass, type UserInfo, type VideoParams, type VideoStatusParams, createAnalytics, createClient, createClientFromRequest, createServerClient };