@copilotz/chat-adapter 0.1.0 → 0.1.3

package/dist/index.d.ts

@@ -1,7 +1,93 @@
 import React from 'react';
-import { ChatUserContext, ChatConfig, ChatCallbacks, MemoryItem, ChatMessage, ChatThread, MediaAttachment } from '@copilotz/chat-ui';
+import { ChatUserContext, ChatConfig, ChatCallbacks, MemoryItem, AgentOption, ChatMessage, ChatThread, MediaAttachment } from '@copilotz/chat-ui';
 export { ChatCallbacks, ChatConfig, ChatMessage, ChatThread, ChatUserContext, MediaAttachment, MemoryItem } from '@copilotz/chat-ui';
 
+/**
+ * Configuration for URL parameter names
+ */
+interface UrlParamsConfig {
+    /** URL param name for thread ID (default: 'thread') */
+    thread?: string;
+    /** URL param name for agent ID (default: 'agent') */
+    agent?: string;
+    /** URL param name for initial prompt (default: 'prompt') */
+    prompt?: string;
+}
+/**
+ * URL sync behavior configuration
+ */
+interface UrlSyncConfig {
+    /** Enable/disable URL sync (default: true) */
+    enabled?: boolean;
+    /**
+     * How to update the URL when state changes:
+     * - 'push': Creates browser history entries (back button works)
+     * - 'replace': Updates URL without history entries (default)
+     * - 'read-only': Only reads from URL, never writes
+     */
+    mode?: 'push' | 'replace' | 'read-only';
+    /** Custom parameter names */
+    params?: UrlParamsConfig;
+    /**
+     * Behavior for the prompt parameter:
+     * - 'prefill': Pre-fills the input field (default)
+     * - 'auto-send': Automatically sends the message on load
+     */
+    promptBehavior?: 'prefill' | 'auto-send';
+    /**
+     * Whether to clear the prompt param from URL after reading
+     * Prevents re-sending on refresh (default: true)
+     */
+    clearPromptAfterRead?: boolean;
+}
+/**
+ * State values parsed from URL
+ */
+interface UrlState {
+    threadId: string | null;
+    agentId: string | null;
+    prompt: string | null;
+}
+/**
+ * Return type of useUrlState hook
+ */
+interface UseUrlStateReturn {
+    /** Current state parsed from URL */
+    state: UrlState;
+    /** Update thread ID in URL */
+    setThreadId: (threadId: string | null) => void;
+    /** Update agent ID in URL */
+    setAgentId: (agentId: string | null) => void;
+    /** Clear prompt from URL (call after consuming it) */
+    clearPrompt: () => void;
+    /** Whether URL sync is enabled */
+    isEnabled: boolean;
+}
+/**
+ * Hook to manage chat state persistence via URL parameters.
+ *
+ * Supports:
+ * - Thread ID: Navigate to specific conversation
+ * - Agent ID: Pre-select an agent
+ * - Prompt: Pre-fill or auto-send a message
+ *
+ * @example
+ * ```tsx
+ * const { state, setThreadId, setAgentId } = useUrlState({
+ *   enabled: true,
+ *   mode: 'replace',
+ *   params: { thread: 't', agent: 'a', prompt: 'q' }
+ * });
+ *
+ * // Read initial values
+ * console.log(state.threadId, state.agentId, state.prompt);
+ *
+ * // Update URL when thread changes
+ * setThreadId('abc123');
+ * ```
+ */
+declare function useUrlState(config?: UrlSyncConfig): UseUrlStateReturn;
+
 interface CopilotzChatProps {
     userId: string;
     userName?: string;
@@ -40,7 +126,41 @@ interface CopilotzChatProps {
     onUpdateMemory?: (memoryId: string, content: string) => void;
     /** Called when user deletes a memory */
     onDeleteMemory?: (memoryId: string) => void;
+    /** Empty-state suggestions */
+    suggestions?: string[];
+    /** Agent selector data (built-in ChatUI) */
+    agentOptions?: AgentOption[];
+    selectedAgentId?: string | null;
+    onSelectAgent?: (agentId: string) => void;
     className?: string;
+    /**
+     * URL state synchronization configuration.
+     * When enabled, syncs thread ID, agent, and prompt to/from URL parameters.
+     *
+     * Features:
+     * - `?thread=abc123` - Opens specific thread
+     * - `?agent=support-bot` - Pre-selects agent
+     * - `?prompt=Hello` - Pre-fills or auto-sends message
+     *
+     * @example
+     * ```tsx
+     * <CopilotzChat
+     *   userId="user123"
+     *   urlSync={{ enabled: true }}
+     * />
+     *
+     * // With custom param names
+     * <CopilotzChat
+     *   userId="user123"
+     *   urlSync={{
+     *     enabled: true,
+     *     params: { thread: 't', agent: 'a', prompt: 'q' },
+     *     promptBehavior: 'auto-send'
+     *   }}
+     * />
+     * ```
+     */
+    urlSync?: UrlSyncConfig;
 }
 declare const CopilotzChat: React.FC<CopilotzChatProps>;
 
@@ -56,8 +176,26 @@ interface UseCopilotzOptions {
     };
     defaultThreadName?: string;
     onToolOutput?: (output: Record<string, unknown>) => void;
+    preferredAgentName?: string | null;
+    /**
+     * URL state synchronization configuration.
+     * When enabled, thread ID and agent are synced to/from URL parameters.
+     *
+     * @example
+     * ```tsx
+     * const chat = useCopilotz({
+     *   userId: 'user123',
+     *   urlSync: {
+     *     enabled: true,
+     *     mode: 'replace',
+     *     params: { thread: 't', agent: 'a', prompt: 'q' }
+     *   }
+     * });
+     * ```
+     */
+    urlSync?: UrlSyncConfig;
 }
-declare function useCopilotz({ userId, initialContext, bootstrap, defaultThreadName, onToolOutput }: UseCopilotzOptions): {
+declare function useCopilotz({ userId, initialContext, bootstrap, defaultThreadName, onToolOutput, preferredAgentName, urlSync }: UseCopilotzOptions): {
     messages: ChatMessage[];
     threads: ChatThread[];
     currentThreadId: string | null;
@@ -73,6 +211,14 @@ declare function useCopilotz({ userId, initialContext, bootstrap, defaultThreadN
     fetchAndSetThreadsState: (uid: string, preferredExternalId?: string | null) => Promise<string | null | undefined>;
     loadThreadMessages: (threadId: string) => Promise<void>;
     reset: () => void;
+    /** Initial prompt from URL (if urlSync enabled) - use for pre-filling input */
+    initialPrompt: string | null;
+    /** Clear the initial prompt from URL (call after consuming it) */
+    clearInitialPrompt: () => void;
+    /** URL agent ID (if urlSync enabled) - use for agent pre-selection */
+    urlAgentId: string | null;
+    /** Update agent ID in URL */
+    setUrlAgentId: (agentId: string | null) => void;
 };
 
 type RestThread = {
@@ -122,6 +268,7 @@ type RunOptions = {
         args: Record<string, unknown>;
         id?: string;
     }>;
+    selectedAgent?: string | null;
 } & StreamCallbacks;
 type CopilotzStreamResult = {
     text: string;
@@ -152,4 +299,4 @@ type WithMetadata = {
 };
 declare function resolveAssetsInMessages<T extends WithMetadata>(messages: T[]): Promise<T[]>;
 
-export { CopilotzChat, type CopilotzStreamResult, copilotzService, deleteMessagesByThreadId, deleteThread, fetchThreadMessages, fetchThreads, getAssetDataUrl, resolveAssetsInMessages, runCopilotzStream, updateThread, useCopilotz };
+export { CopilotzChat, type CopilotzStreamResult, type UrlParamsConfig, type UrlState, type UrlSyncConfig, type UseUrlStateReturn, copilotzService, deleteMessagesByThreadId, deleteThread, fetchThreadMessages, fetchThreads, getAssetDataUrl, resolveAssetsInMessages, runCopilotzStream, updateThread, useCopilotz, useUrlState };