@yourgpt/copilot-sdk 0.1.1 → 1.0.1

package/dist/{thread-CLmfwine.d.cts → ThreadManager-BjC15mh8.d.ts}

@@ -1,3 +1,5 @@
+import { k as Thread, l as ThreadData, _ as ThreadStorageAdapter, X as AsyncThreadStorageAdapter, g as Message } from './types-BtAaOV07.js';
+
 /**
  * Tool types for App Context Awareness
  */
@@ -207,194 +209,6 @@ interface CustomKeywords {
  */
 declare function createCustomDetector(customKeywords: CustomKeywords): (message: string) => IntentDetectionResult;
 
-/**
- * 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;
-
 /**
  * Supported LLM providers
  */
@@ -659,52 +473,391 @@ interface InternalKnowledgeBaseSearchResponse {
 }
 
 /**
- * Thread metadata (for listing threads)
+ * ThreadManagerState Interface
+ *
+ * Contract for framework-specific state implementations.
+ * Following the same pattern as ChatState for framework agnosticism.
  */
-interface Thread {
-    /** Unique thread identifier */
-    id: string;
-    /** Thread title (auto-generated from first message or manual) */
-    title?: string;
-    /** When thread was created */
-    createdAt: Date;
-    /** When thread was last updated */
-    updatedAt: Date;
+
+/**
+ * Load status for async operations
+ */
+type LoadStatus = "idle" | "loading" | "loaded" | "error";
+/**
+ * ThreadManagerState interface - Framework adapters implement this
+ *
+ * This is the key abstraction that enables framework-agnostic code.
+ * The ThreadManager class uses this interface, and each framework
+ * provides its own implementation.
+ *
+ * @example React implementation
+ * ```typescript
+ * class ReactThreadManagerState implements ThreadManagerState {
+ *   #threads: Thread[] = [];
+ *   #callbacks = new Set<() => void>();
+ *
+ *   get threads() { return this.#threads; }
+ *   set threads(t) {
+ *     this.#threads = t;
+ *     this.#callbacks.forEach(cb => cb()); // Trigger re-render
+ *   }
+ *
+ *   subscribe(cb: () => void) {
+ *     this.#callbacks.add(cb);
+ *     return () => this.#callbacks.delete(cb);
+ *   }
+ * }
+ * ```
+ */
+interface ThreadManagerState {
+    /** All threads (metadata only) */
+    threads: Thread[];
+    /** Currently selected thread ID */
+    currentThreadId: string | null;
+    /** Currently loaded thread data (with messages) */
+    currentThread: ThreadData | null;
+    /** Current loading status */
+    loadStatus: LoadStatus;
+    /** Current error if any */
+    error: Error | undefined;
+    /**
+     * Set all threads
+     */
+    setThreads(threads: Thread[]): void;
+    /**
+     * Set the current thread
+     */
+    setCurrentThread(thread: ThreadData | null): void;
+    /**
+     * Set the current thread ID
+     */
+    setCurrentThreadId(id: string | null): void;
+    /**
+     * Add a new thread to the list
+     */
+    addThread(thread: Thread): void;
+    /**
+     * Update a thread's metadata
+     */
+    updateThread(id: string, updates: Partial<Thread>): void;
+    /**
+     * Remove a thread from the list
+     */
+    removeThread(id: string): void;
+    /**
+     * Set loading status
+     */
+    setLoadStatus(status: LoadStatus): void;
+    /**
+     * Set error
+     */
+    setError(error: Error | undefined): void;
+    /**
+     * Subscribe to state changes
+     * Returns unsubscribe function
+     *
+     * This is used by React's useSyncExternalStore.
+     * Vue/Svelte may not need this (they use refs/stores).
+     */
+    subscribe?(callback: () => void): () => void;
+    /**
+     * Get immutable snapshot of threads
+     */
+    getThreadsSnapshot?(): Thread[];
+    /**
+     * Get current thread snapshot
+     */
+    getCurrentThreadSnapshot?(): ThreadData | null;
+    /**
+     * Get load status snapshot
+     */
+    getLoadStatusSnapshot?(): LoadStatus;
+    /**
+     * Get error snapshot
+     */
+    getErrorSnapshot?(): Error | undefined;
+}
+/**
+ * Default in-memory state implementation (for testing/vanilla JS)
+ */
+declare class SimpleThreadManagerState implements ThreadManagerState {
+    private _threads;
+    private _currentThreadId;
+    private _currentThread;
+    private _loadStatus;
+    private _error;
+    private callbacks;
+    get threads(): Thread[];
+    get currentThreadId(): string | null;
+    get currentThread(): ThreadData | null;
+    get loadStatus(): LoadStatus;
+    get error(): Error | undefined;
+    set threads(value: Thread[]);
+    setThreads(threads: Thread[]): void;
+    setCurrentThread(thread: ThreadData | null): void;
+    setCurrentThreadId(id: string | null): void;
+    addThread(thread: Thread): void;
+    updateThread(id: string, updates: Partial<Thread>): void;
+    removeThread(id: string): void;
+    setLoadStatus(status: LoadStatus): void;
+    setError(error: Error | undefined): void;
+    subscribe(callback: () => void): () => void;
+    getThreadsSnapshot(): Thread[];
+    getCurrentThreadSnapshot(): ThreadData | null;
+    getLoadStatusSnapshot(): LoadStatus;
+    getErrorSnapshot(): Error | undefined;
+    private notify;
 }
+
+/**
+ * localStorage Thread Storage Adapter
+ *
+ * Default adapter for thread persistence using browser localStorage.
+ * Stores all data in a single key for cleaner storage management.
+ */
+
 /**
- * Full thread data including messages
+ * Configuration for localStorage adapter
  */
-interface ThreadData extends Thread {
-    /** Messages in this thread */
-    messages: Message[];
-    /** Sources from knowledge base for this thread */
-    sources: Source[];
+interface LocalStorageAdapterConfig {
+    /**
+     * Storage key to use
+     * @default "copilot-sdk-store"
+     */
+    storageKey?: string;
 }
 /**
- * Persistence storage interface for custom adapters
+ * Create a localStorage adapter for thread storage
+ *
+ * All data is stored in a single key for cleaner storage management.
+ *
+ * @example Default usage
+ * ```typescript
+ * const adapter = createLocalStorageAdapter();
+ * const threadManager = new ThreadManager({ adapter });
+ * ```
+ *
+ * @example With custom key
+ * ```typescript
+ * const adapter = createLocalStorageAdapter({
+ *   storageKey: "my-app-copilot-store"
+ * });
+ * ```
+ */
+declare function createLocalStorageAdapter(config?: LocalStorageAdapterConfig): ThreadStorageAdapter;
+/**
+ * Default localStorage adapter instance
  */
-interface ThreadStorageAdapter {
-    /** Save threads to storage */
-    save: (threads: ThreadData[]) => Promise<void>;
-    /** Load threads from storage */
-    load: () => Promise<ThreadData[]>;
-    /** Clear all threads from storage */
-    clear: () => Promise<void>;
+declare const localStorageAdapter: ThreadStorageAdapter;
+
+/**
+ * In-Memory Thread Storage Adapter
+ *
+ * Non-persistent adapter useful for testing or ephemeral sessions.
+ */
+
+/**
+ * Create an in-memory adapter for thread storage
+ *
+ * This adapter stores threads in memory only - data is lost on page refresh.
+ * Useful for:
+ * - Testing
+ * - Server-side rendering (where localStorage is unavailable)
+ * - Ephemeral sessions where persistence isn't needed
+ *
+ * @example
+ * ```typescript
+ * const adapter = createMemoryAdapter();
+ * const threadManager = new ThreadManager({ adapter });
+ * ```
+ *
+ * @example Pre-populate with threads
+ * ```typescript
+ * const adapter = createMemoryAdapter([
+ *   { id: "1", title: "Test", messages: [], sources: [], createdAt: new Date(), updatedAt: new Date() }
+ * ]);
+ * ```
+ */
+declare function createMemoryAdapter(initialThreads?: ThreadData[]): ThreadStorageAdapter;
+/**
+ * No-op adapter that never saves or loads
+ * Useful when you want to completely disable persistence
+ */
+declare const noopAdapter: ThreadStorageAdapter;
+
+/**
+ * ThreadManager - Framework-agnostic Thread Management
+ *
+ * Manages thread state and persistence with pluggable storage adapters.
+ * Similar pattern to AbstractChat for framework agnosticism.
+ */
+
+/**
+ * Configuration for ThreadManager
+ */
+interface ThreadManagerConfig {
+    /**
+     * Storage adapter for persistence
+     * @default localStorage adapter
+     */
+    adapter?: ThreadStorageAdapter | AsyncThreadStorageAdapter;
+    /**
+     * Debounce delay for auto-save (ms)
+     * @default 1000
+     */
+    saveDebounce?: number;
+    /**
+     * Whether to auto-load threads on initialization
+     * @default true
+     */
+    autoLoad?: boolean;
+    /**
+     * Whether to auto-restore the last active thread on load
+     * Requires adapter to support getLastActiveThreadId/setLastActiveThreadId
+     * @default true
+     */
+    autoRestoreLastThread?: boolean;
+    /**
+     * Custom state implementation (for framework adapters)
+     * @default SimpleThreadManagerState
+     */
+    state?: ThreadManagerState;
 }
 /**
- * Persistence configuration
+ * Callbacks for ThreadManager events
+ */
+interface ThreadManagerCallbacks {
+    /** Called when threads are loaded */
+    onThreadsLoaded?: (threads: Thread[]) => void;
+    /** Called when a thread is created */
+    onThreadCreated?: (thread: ThreadData) => void;
+    /** Called when a thread is switched */
+    onThreadSwitched?: (thread: ThreadData | null) => void;
+    /** Called when a thread is updated */
+    onThreadUpdated?: (thread: ThreadData) => void;
+    /** Called when a thread is deleted */
+    onThreadDeleted?: (threadId: string) => void;
+    /** Called when an error occurs */
+    onError?: (error: Error) => void;
+}
+/**
+ * Options for creating a new thread
+ */
+interface CreateThreadOptions {
+    /** Custom thread ID (auto-generated if not provided) */
+    id?: string;
+    /** Thread title */
+    title?: string;
+    /** Initial messages */
+    messages?: Message[];
+}
+/**
+ * Options for updating a thread
+ */
+interface UpdateThreadOptions {
+    /** Update title */
+    title?: string;
+    /** Update messages */
+    messages?: Message[];
+    /** Custom metadata updates */
+    [key: string]: unknown;
+}
+/**
+ * ThreadManager - Manages thread state and persistence
+ *
+ * @example Basic usage with localStorage (default)
+ * ```typescript
+ * const manager = new ThreadManager();
+ * await manager.loadThreads();
+ *
+ * const thread = await manager.createThread();
+ * console.log(manager.threads);
+ * ```
+ *
+ * @example With custom adapter
+ * ```typescript
+ * const manager = new ThreadManager({
+ *   adapter: myDatabaseAdapter,
+ * });
+ * ```
  */
-interface PersistenceConfig {
-    /** Enable persistence (default: false) */
-    enabled: boolean;
-    /** Storage type */
-    storage?: "localStorage" | "custom";
-    /** Custom storage adapter (required if storage is 'custom') */
-    customStorage?: ThreadStorageAdapter;
+declare class ThreadManager {
+    protected state: ThreadManagerState;
+    protected adapter: ThreadStorageAdapter | AsyncThreadStorageAdapter;
+    protected callbacks: ThreadManagerCallbacks;
+    protected saveDebounce: number;
+    protected autoLoad: boolean;
+    protected autoRestoreLastThread: boolean;
+    private saveTimer;
+    private threadsData;
+    private initPromise;
+    constructor(config?: ThreadManagerConfig, callbacks?: ThreadManagerCallbacks);
+    /** All threads (metadata) */
+    get threads(): Thread[];
+    /** Currently selected thread ID */
+    get currentThreadId(): string | null;
+    /** Currently loaded thread (with messages) */
+    get currentThread(): ThreadData | null;
+    /** Whether threads are currently loading */
+    get isLoading(): boolean;
+    /** Current load status */
+    get loadStatus(): LoadStatus;
+    /** Current error */
+    get error(): Error | undefined;
+    /** Whether there are pending changes waiting to be saved */
+    get hasPendingChanges(): boolean;
+    /**
+     * Load all threads from storage
+     */
+    loadThreads(): Promise<void>;
+    /**
+     * Wait for initialization to complete
+     */
+    waitForInit(): Promise<void>;
+    /**
+     * Create a new thread
+     */
+    createThread(options?: CreateThreadOptions): Promise<ThreadData>;
+    /**
+     * Switch to a different thread
+     */
+    switchThread(id: string): Promise<ThreadData | null>;
+    /**
+     * Update the current thread
+     */
+    updateCurrentThread(updates: UpdateThreadOptions): Promise<void>;
+    /**
+     * Delete a thread
+     */
+    deleteThread(id: string): Promise<void>;
+    /**
+     * Clear the current thread selection
+     */
+    clearCurrentThread(): void;
+    /**
+     * Clear all threads
+     */
+    clearAllThreads(): Promise<void>;
+    /**
+     * Save changes immediately (bypass debounce)
+     */
+    saveNow(): Promise<void>;
+    /**
+     * Dispose of the manager and save pending changes
+     */
+    dispose(): Promise<void>;
+    /**
+     * Schedule a debounced save
+     */
+    protected scheduleSave(): void;
+    /**
+     * Save the last active thread ID (for session persistence)
+     */
+    protected saveLastActiveThread(threadId: string | null): void;
 }
 /**
- * Generate a thread title from message content
+ * Create a ThreadManager instance
  */
-declare function generateThreadTitle(content: string): string;
+declare function createThreadManager(config?: ThreadManagerConfig, callbacks?: ThreadManagerCallbacks): ThreadManager;
 
-export { createAssistantMessage as $, type ActionParameter as A, type ActionRenderProps as B, type ConsoleLogOptions as C, type KnowledgeBaseConfig as D, type Extension as E, type KnowledgeBaseResult as F, type KnowledgeBaseSearchRequest as G, type HttpMethod as H, type IntentDetectionResult as I, type KnowledgeBaseSearchResponse as J, type KnowledgeBaseProvider as K, type LLMProvider as L, type MessageAttachment as M, type NetworkRequestOptions as N, type InternalKnowledgeBaseConfig as O, type ParameterType as P, type InternalKnowledgeBaseResult as Q, type InternalKnowledgeBaseSearchResponse as R, type ScreenshotOptions as S, type ToolType as T, type Thread as U, type ThreadData as V, type PersistenceConfig as W, type ThreadStorageAdapter as X, generateThreadTitle as Y, createMessage as Z, createUserMessage as _, type ScreenshotResult as a, createToolMessage as a0, createToolCall as a1, parseToolCallArgs as a2, hasToolCalls as a3, isToolResult as a4, actionToTool as a5, getDefaultModel as a6, DEFAULT_MODELS as a7, type ConsoleLogResult as b, type ConsoleLogEntry as c, type NetworkRequestResult as d, type NetworkRequestEntry as e, type Source as f, detectIntent as g, hasToolSuggestions as h, getPrimaryTool as i, generateSuggestionReason as j, createCustomDetector as k, type ConsoleLogType as l, type ToolsConfig as m, type ToolConsentRequest as n, type ToolConsentResponse as o, type CapturedContext as p, type CustomKeywords as q, type MessageRole as r, type Message as s, type MessageMetadata as t, type ToolCall as u, type TokenUsage as v, type LLMConfig as w, type CloudConfig as x, type CopilotConfig as y, type ActionDefinition as z };
+export { type ThreadManagerState as $, type ActionParameter as A, type InternalKnowledgeBaseResult as B, type ConsoleLogOptions as C, type InternalKnowledgeBaseSearchResponse as D, type Extension as E, actionToTool as F, getDefaultModel as G, type HttpMethod as H, type IntentDetectionResult as I, DEFAULT_MODELS as J, type KnowledgeBaseProvider as K, type LLMProvider as L, ThreadManager as M, type NetworkRequestOptions as N, createThreadManager as O, type ParameterType as P, createLocalStorageAdapter as Q, localStorageAdapter as R, type ScreenshotOptions as S, type ToolType as T, createMemoryAdapter as U, noopAdapter as V, SimpleThreadManagerState as W, type ThreadManagerConfig as X, type ThreadManagerCallbacks as Y, type CreateThreadOptions as Z, type UpdateThreadOptions as _, type ScreenshotResult as a, type LoadStatus as a0, type LocalStorageAdapterConfig as a1, type ConsoleLogResult as b, type ConsoleLogEntry as c, type NetworkRequestResult as d, type NetworkRequestEntry as e, detectIntent as f, getPrimaryTool as g, hasToolSuggestions as h, generateSuggestionReason as i, createCustomDetector as j, type ConsoleLogType as k, type ToolsConfig as l, type ToolConsentRequest as m, type ToolConsentResponse as n, type CapturedContext as o, type CustomKeywords as p, type LLMConfig as q, type CloudConfig as r, type CopilotConfig as s, type ActionDefinition as t, type ActionRenderProps as u, type KnowledgeBaseConfig as v, type KnowledgeBaseResult as w, type KnowledgeBaseSearchRequest as x, type KnowledgeBaseSearchResponse as y, type InternalKnowledgeBaseConfig as z };