@yourgpt/copilot-sdk 2.0.1 → 2.0.2-beta.2

package/dist/types-DG2ya08y.d.cts

@@ -0,0 +1,367 @@
+/**
+ * Message roles in a conversation (OpenAI format)
+ */
+type MessageRole = "user" | "assistant" | "system" | "tool";
+/**
+ * A source document from knowledge base
+ */
+interface Source {
+    /** Unique identifier */
+    id: string;
+    /** Source title or filename */
+    title: string;
+    /** Relevant content snippet */
+    content: string;
+    /** URL if available */
+    url?: string;
+    /** Relevance score (0-1) */
+    score?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Tool/function call in OpenAI format
+ * Used in assistant messages when AI wants to call tools
+ */
+interface ToolCall {
+    /** Unique identifier for this call */
+    id: string;
+    /** Always "function" for OpenAI compatibility */
+    type: "function";
+    /** Function details */
+    function: {
+        /** Name of the function/tool */
+        name: string;
+        /** Arguments as JSON string (OpenAI format) */
+        arguments: string;
+    };
+}
+/**
+ * Attachment in a message (images, files, etc.)
+ *
+ * Attachments can be stored as:
+ * - Base64 data (free tier, embedded in message)
+ * - URL (premium cloud storage, lighter payload)
+ */
+interface MessageAttachment {
+    /** Type of attachment */
+    type: "image" | "file" | "audio" | "video";
+    /** Base64 data (for embedded attachments) */
+    data?: string;
+    /** URL for cloud-stored attachments (managed cloud storage) */
+    url?: string;
+    /** MIME type */
+    mimeType: string;
+    /** Optional filename */
+    filename?: string;
+}
+/**
+ * Token usage information
+ */
+interface TokenUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens?: number;
+}
+/**
+ * Message metadata (flexible container for provider-specific data)
+ */
+interface MessageMetadata {
+    /** Extended thinking/reasoning (Claude, DeepSeek) */
+    thinking?: string;
+    /** Knowledge base sources */
+    sources?: Source[];
+    /** Attachments (images, files) */
+    attachments?: MessageAttachment[];
+    /** Model used to generate this message */
+    model?: string;
+    /** Token usage */
+    usage?: TokenUsage;
+    /** Any additional data */
+    [key: string]: unknown;
+}
+/**
+ * A message in the conversation (OpenAI format)
+ *
+ * This format is compatible with OpenAI's Chat Completions API
+ * and can be stored directly in a database (1 row per message).
+ *
+ * Message types:
+ * - user: User's input message
+ * - assistant: AI's response (may include tool_calls)
+ * - tool: Result of a tool execution (has tool_call_id)
+ * - system: System prompt (usually first message)
+ *
+ * @example
+ * // User message
+ * { role: "user", content: "What's the weather?" }
+ *
+ * // Assistant requesting tool
+ * { role: "assistant", content: null, tool_calls: [{...}] }
+ *
+ * // Tool result
+ * { role: "tool", content: '{"temp": 72}', tool_call_id: "call_abc" }
+ *
+ * // Final assistant response
+ * { role: "assistant", content: "The temperature is 72°F" }
+ */
+interface Message {
+    /** Unique identifier */
+    id: string;
+    /** Thread/conversation ID (for multi-session apps) */
+    thread_id?: string;
+    /** Role of the message sender */
+    role: MessageRole;
+    /** Text content (null for tool-calling assistant messages) */
+    content: string | null;
+    /**
+     * Tool calls made by assistant (OpenAI format)
+     * Only present when role is "assistant" and AI wants to call tools
+     */
+    tool_calls?: ToolCall[];
+    /**
+     * Tool call ID this message is responding to
+     * Only present when role is "tool"
+     */
+    tool_call_id?: string;
+    /**
+     * Flexible metadata container
+     * Contains: thinking, sources, attachments, model, usage, etc.
+     */
+    metadata?: MessageMetadata;
+    /** When the message was created */
+    created_at: Date;
+}
+/**
+ * Helper to parse tool call arguments
+ */
+declare function parseToolCallArgs<T = Record<string, unknown>>(toolCall: ToolCall): T;
+/**
+ * Helper to create a tool call
+ */
+declare function createToolCall(id: string, name: string, args: Record<string, unknown>): ToolCall;
+/**
+ * Create a new message with defaults
+ */
+declare function createMessage(partial: Partial<Message> & Pick<Message, "role"> & {
+    content?: string | null;
+}): Message;
+/**
+ * Create a user message
+ */
+declare function createUserMessage(content: string, options?: {
+    id?: string;
+    thread_id?: string;
+    attachments?: MessageAttachment[];
+}): Message;
+/**
+ * Create an assistant message
+ */
+declare function createAssistantMessage(content: string | null, options?: {
+    id?: string;
+    thread_id?: string;
+    tool_calls?: ToolCall[];
+    thinking?: string;
+    sources?: Source[];
+    model?: string;
+}): Message;
+/**
+ * Create a tool result message
+ */
+declare function createToolMessage(toolCallId: string, result: {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+    message?: string;
+}, options?: {
+    id?: string;
+    thread_id?: string;
+}): Message;
+/**
+ * Check if a message has tool calls
+ */
+declare function hasToolCalls(message: Message): boolean;
+/**
+ * Check if a message is a tool result
+ */
+declare function isToolResult(message: Message): boolean;
+
+/**
+ * Thread metadata (for listing threads)
+ */
+interface Thread {
+    /** Unique thread identifier */
+    id: string;
+    /** Thread title (auto-generated from first message or manual) */
+    title?: string;
+    /** Preview of the first message (for thread lists) */
+    preview?: string;
+    /** Number of messages in this thread */
+    messageCount?: number;
+    /** When thread was created */
+    createdAt: Date;
+    /** When thread was last updated */
+    updatedAt: Date;
+}
+/**
+ * Full thread data including messages
+ */
+interface ThreadData extends Thread {
+    /** Messages in this thread */
+    messages: Message[];
+    /** Sources from knowledge base for this thread */
+    sources: Source[];
+}
+/**
+ * Persistence storage interface for custom adapters
+ */
+interface ThreadStorageAdapter$1 {
+    /** Save threads to storage */
+    save: (threads: ThreadData[]) => Promise<void>;
+    /** Load threads from storage */
+    load: () => Promise<ThreadData[]>;
+    /** Clear all threads from storage */
+    clear: () => Promise<void>;
+}
+/**
+ * Persistence configuration
+ */
+interface PersistenceConfig {
+    /** Enable persistence (default: false) */
+    enabled: boolean;
+    /** Storage type */
+    storage?: "localStorage" | "custom";
+    /** Custom storage adapter (required if storage is 'custom') */
+    customStorage?: ThreadStorageAdapter$1;
+}
+/**
+ * Generate a thread title from message content
+ */
+declare function generateThreadTitle(content: string): string;
+
+/**
+ * Thread Storage Adapter Types
+ *
+ * Interfaces for thread persistence adapters.
+ */
+
+/**
+ * Basic thread storage adapter interface
+ * Used by ThreadManager for persistence
+ */
+interface ThreadStorageAdapter {
+    /** Save all threads to storage */
+    save: (threads: ThreadData[]) => Promise<void>;
+    /** Load all threads from storage */
+    load: () => Promise<ThreadData[]>;
+    /** Clear all threads from storage */
+    clear: () => Promise<void>;
+    /**
+     * Get the last active thread ID
+     * Optional - used for session persistence
+     */
+    getLastActiveThreadId?: () => Promise<string | null>;
+    /**
+     * Set the last active thread ID
+     * Optional - used for session persistence
+     */
+    setLastActiveThreadId?: (threadId: string | null) => Promise<void>;
+}
+/**
+ * Pagination options for listing threads
+ */
+interface ListThreadsOptions {
+    /** Maximum number of threads to return */
+    limit?: number;
+    /** Number of threads to skip */
+    offset?: number;
+    /** Sort order (default: updatedAt desc) */
+    orderBy?: "createdAt" | "updatedAt";
+    /** Sort direction */
+    orderDir?: "asc" | "desc";
+}
+/**
+ * Paginated response for thread listing
+ */
+interface ListThreadsResult {
+    /** Threads for current page */
+    threads: Thread[];
+    /** Total number of threads */
+    total: number;
+    /** Whether there are more threads */
+    hasMore: boolean;
+}
+/**
+ * Async thread storage adapter with optimized single-thread operations
+ *
+ * Use this interface when implementing database backends (Supabase, Firebase, etc.)
+ * These methods are optional - if not provided, ThreadManager falls back to
+ * full save/load operations.
+ *
+ * @example Supabase adapter
+ * ```typescript
+ * const supabaseAdapter: AsyncThreadStorageAdapter = {
+ *   save: async (threads) => { /* batch upsert *\/ },
+ *   load: async () => { /* select all *\/ },
+ *   clear: async () => { /* delete all *\/ },
+ *
+ *   // Optimized operations
+ *   getThread: async (id) => {
+ *     const { data } = await supabase
+ *       .from('threads')
+ *       .select('*, messages(*)')
+ *       .eq('id', id)
+ *       .single();
+ *     return data;
+ *   },
+ *   createThread: async (thread) => {
+ *     const { data } = await supabase.from('threads').insert(thread).select().single();
+ *     return data;
+ *   },
+ *   updateThread: async (id, updates) => {
+ *     const { data } = await supabase.from('threads').update(updates).eq('id', id).select().single();
+ *     return data;
+ *   },
+ *   deleteThread: async (id) => {
+ *     await supabase.from('threads').delete().eq('id', id);
+ *   },
+ *   listThreads: async ({ limit, offset }) => {
+ *     const { data, count } = await supabase
+ *       .from('threads')
+ *       .select('*', { count: 'exact' })
+ *       .order('updatedAt', { ascending: false })
+ *       .range(offset, offset + limit - 1);
+ *     return { threads: data, total: count, hasMore: (offset + limit) < count };
+ *   },
+ * };
+ * ```
+ */
+interface AsyncThreadStorageAdapter extends ThreadStorageAdapter {
+    /**
+     * Get a single thread by ID
+     * If provided, used instead of loading all threads
+     */
+    getThread?: (id: string) => Promise<ThreadData | null>;
+    /**
+     * Create a new thread
+     * If provided, used instead of saving all threads
+     */
+    createThread?: (thread: ThreadData) => Promise<ThreadData>;
+    /**
+     * Update an existing thread
+     * If provided, used instead of saving all threads
+     */
+    updateThread?: (id: string, updates: Partial<ThreadData>) => Promise<ThreadData>;
+    /**
+     * Delete a thread by ID
+     * If provided, used instead of saving all threads
+     */
+    deleteThread?: (id: string) => Promise<void>;
+    /**
+     * List threads with pagination
+     * If provided, used for efficient thread listing
+     */
+    listThreads?: (options?: ListThreadsOptions) => Promise<ListThreadsResult>;
+}
+
+export { type AsyncThreadStorageAdapter as A, type ListThreadsOptions as L, type Message as M, type PersistenceConfig as P, type Source as S, type Thread as T, type ThreadData as a, type ThreadStorageAdapter as b, type MessageAttachment as c, type MessageRole as d, type MessageMetadata as e, type ToolCall as f, type TokenUsage as g, type ThreadStorageAdapter$1 as h, generateThreadTitle as i, createMessage as j, createUserMessage as k, createAssistantMessage as l, createToolMessage as m, createToolCall as n, hasToolCalls as o, parseToolCallArgs as p, isToolResult as q, type ListThreadsResult as r };