@usecrow/client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,424 @@
+/**
+ * Core types for @usecrow/client
+ */
+interface CrowClientConfig {
+    /** Your Crow product ID from the dashboard */
+    productId: string;
+    /** API URL (defaults to https://api.usecrow.org) */
+    apiUrl?: string;
+    /** Default model to use */
+    model?: string;
+}
+interface IdentifyOptions {
+    /** JWT token from your backend for user verification */
+    token: string;
+    /** Optional user display name */
+    name?: string;
+    /** Optional user email */
+    email?: string;
+    /** Any additional metadata */
+    [key: string]: unknown;
+}
+interface IdentityState {
+    token: string | null;
+    metadata: Record<string, unknown>;
+    isVerified: boolean;
+}
+interface Message {
+    id: string;
+    content: string;
+    role: 'user' | 'assistant';
+    timestamp: Date;
+    /** Citations from knowledge base */
+    citations?: Citation[];
+    /** Claude's reasoning/thinking trace */
+    thinking?: string;
+    /** Whether thinking is complete */
+    thinkingComplete?: boolean;
+}
+interface Citation {
+    document_id: string;
+    filename: string;
+    similarity?: number;
+    image_url?: string;
+    page?: number;
+}
+type StreamEvent = {
+    type: 'content';
+    text: string;
+    accumulated: string;
+} | {
+    type: 'thinking';
+    content: string;
+} | {
+    type: 'thinking_complete';
+} | {
+    type: 'citations';
+    citations: Citation[];
+} | {
+    type: 'tool_call_start';
+    toolName: string;
+    arguments: Record<string, unknown>;
+} | {
+    type: 'tool_call_complete';
+    toolName: string;
+    success: boolean;
+} | {
+    type: 'client_tool_call';
+    toolName: string;
+    arguments: Record<string, unknown>;
+} | {
+    type: 'workflow_started';
+    name: string;
+    todos: WorkflowTodo[];
+} | {
+    type: 'workflow_todo_updated';
+    todoId: string;
+    status: 'pending' | 'completed';
+} | {
+    type: 'workflow_ended';
+} | {
+    type: 'workflow_complete_prompt';
+} | {
+    type: 'verification_status';
+    isVerified: boolean;
+} | {
+    type: 'conversation_id';
+    conversationId: string;
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'done';
+};
+type ToolHandler = (args: Record<string, unknown>) => Promise<ToolResult> | ToolResult;
+interface ToolResult {
+    status: 'success' | 'error';
+    data?: unknown;
+    error?: string;
+}
+type ToolHandlers = Record<string, ToolHandler>;
+interface Conversation {
+    id: string;
+    name: string | null;
+    created_at: string;
+    updated_at: string;
+}
+interface WorkflowTodo {
+    id: string;
+    text: string;
+    status: 'pending' | 'completed';
+}
+interface ActiveWorkflow {
+    name: string;
+    todos: WorkflowTodo[];
+    isComplete?: boolean;
+}
+interface ContextData {
+    /** Current page URL or path */
+    page?: string;
+    /** Custom context data */
+    [key: string]: unknown;
+}
+interface CrowEventCallbacks {
+    onMessage?: (message: Message) => void;
+    onMessageUpdate?: (messageId: string, updates: Partial<Message>) => void;
+    onToolCall?: (event: StreamEvent & {
+        type: 'tool_call_start' | 'tool_call_complete' | 'client_tool_call';
+    }) => void;
+    onWorkflow?: (event: StreamEvent & {
+        type: 'workflow_started' | 'workflow_todo_updated' | 'workflow_ended' | 'workflow_complete_prompt';
+    }) => void;
+    onVerificationStatus?: (isVerified: boolean) => void;
+    onError?: (error: Error) => void;
+}
+
+/**
+ * CrowClient - Main headless client for Crow AI agents
+ */
+
+declare class CrowClient {
+    private config;
+    private identity;
+    private tools;
+    private conversations;
+    private context;
+    private abortController;
+    private callbacks;
+    private _messages;
+    private messageListeners;
+    private _isLoading;
+    private loadingListeners;
+    constructor(config: CrowClientConfig);
+    /**
+     * Get current product ID
+     */
+    get productId(): string;
+    /**
+     * Get current API URL
+     */
+    get apiUrl(): string;
+    /**
+     * Get/set current model
+     */
+    get model(): string;
+    set model(value: string);
+    /**
+     * Register event callbacks
+     */
+    on(callbacks: CrowEventCallbacks): void;
+    /**
+     * Identify the current user with a JWT token
+     */
+    identify(options: IdentifyOptions): void;
+    /**
+     * Reset user identity (call on logout)
+     */
+    resetUser(): void;
+    /**
+     * Check if user is identified
+     */
+    isIdentified(): boolean;
+    /**
+     * Check if user is verified by server
+     */
+    isVerified(): boolean;
+    /**
+     * Register client-side tool handlers
+     */
+    registerTools(tools: ToolHandlers): void;
+    /**
+     * Unregister a tool handler
+     */
+    unregisterTool(name: string): void;
+    /**
+     * Get list of registered tool names
+     */
+    getRegisteredTools(): string[];
+    /**
+     * Set context data to be sent with messages
+     */
+    setContext(data: ContextData): void;
+    /**
+     * Clear context data
+     */
+    clearContext(): void;
+    /**
+     * Get current messages
+     */
+    get messages(): Message[];
+    /**
+     * Check if currently loading/streaming
+     */
+    get isLoading(): boolean;
+    /**
+     * Subscribe to message changes
+     */
+    onMessages(callback: (messages: Message[]) => void): () => void;
+    /**
+     * Subscribe to loading state changes
+     */
+    onLoading(callback: (isLoading: boolean) => void): () => void;
+    /**
+     * Clear all messages and start new conversation
+     */
+    clearMessages(): void;
+    /**
+     * Load messages from history
+     */
+    loadMessages(messages: Message[]): void;
+    private notifyMessages;
+    private setLoading;
+    private addMessage;
+    private updateMessage;
+    private generateMessageId;
+    /**
+     * Get current conversation ID
+     */
+    get conversationId(): string | null;
+    /**
+     * Set current conversation ID
+     */
+    set conversationId(id: string | null);
+    /**
+     * Get list of conversations for verified user
+     */
+    getConversations(): Promise<Conversation[]>;
+    /**
+     * Load conversation history
+     */
+    loadHistory(conversationId: string): Promise<Message[]>;
+    /**
+     * Switch to a different conversation
+     */
+    switchConversation(conversationId: string): Promise<void>;
+    /**
+     * Send a message and receive streaming response
+     * Returns an async generator of stream events
+     */
+    sendMessage(content: string): AsyncGenerator<StreamEvent>;
+    /**
+     * Send a message and wait for complete response (non-streaming)
+     */
+    send(content: string): Promise<Message | null>;
+    /**
+     * Stop current generation
+     */
+    stop(): void;
+    /**
+     * Destroy the client and clean up resources
+     */
+    destroy(): void;
+}
+
+/**
+ * Identity management for user authentication
+ */
+
+declare class IdentityManager {
+    private state;
+    private listeners;
+    /**
+     * Identify the current user with a JWT token
+     */
+    identify(options: IdentifyOptions): void;
+    /**
+     * Update verification status (called when server confirms)
+     */
+    setVerified(isVerified: boolean): void;
+    /**
+     * Reset user identity (call on logout)
+     */
+    reset(): void;
+    /**
+     * Get current identity token
+     */
+    getToken(): string | null;
+    /**
+     * Get current identity state
+     */
+    getState(): IdentityState;
+    /**
+     * Check if user is identified
+     */
+    isIdentified(): boolean;
+    /**
+     * Check if user is verified
+     */
+    isVerified(): boolean;
+    /**
+     * Subscribe to identity changes
+     */
+    subscribe(callback: (state: IdentityState) => void): () => void;
+    private notify;
+}
+
+/**
+ * Client-side tool management
+ */
+
+declare class ToolManager {
+    private handlers;
+    /**
+     * Register client-side tool handlers
+     */
+    register(tools: ToolHandlers): void;
+    /**
+     * Unregister a tool handler
+     */
+    unregister(name: string): void;
+    /**
+     * Check if a tool is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered tool names
+     */
+    getRegisteredTools(): string[];
+    /**
+     * Execute a client-side tool
+     */
+    execute(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+}
+
+/**
+ * Conversation management
+ */
+
+declare class ConversationManager {
+    private productId;
+    private apiUrl;
+    private currentId;
+    constructor(productId: string, apiUrl: string);
+    /**
+     * Get localStorage key for this product
+     */
+    private getStorageKey;
+    /**
+     * Load conversation ID from localStorage
+     */
+    private loadFromStorage;
+    /**
+     * Save conversation ID to localStorage
+     */
+    private saveToStorage;
+    /**
+     * Clear conversation ID from localStorage
+     */
+    private clearStorage;
+    /**
+     * Get current conversation ID
+     */
+    getCurrentId(): string | null;
+    /**
+     * Set current conversation ID
+     */
+    setCurrentId(id: string | null): void;
+    /**
+     * Check if there's a restored conversation
+     */
+    hasRestoredConversation(): boolean;
+    /**
+     * Clear current conversation (start new)
+     */
+    clear(): void;
+    /**
+     * Fetch list of conversations for verified user
+     */
+    getConversations(identityToken: string): Promise<Conversation[]>;
+    /**
+     * Load conversation history for verified user
+     */
+    loadHistory(conversationId: string, identityToken: string): Promise<Message[]>;
+    /**
+     * Load conversation history for anonymous user
+     */
+    loadAnonymousHistory(conversationId: string): Promise<Message[]>;
+    /**
+     * Parse history messages from API format
+     */
+    private parseHistoryMessages;
+    /**
+     * Parse structured content (with thinking/text blocks) and extract just text
+     */
+    private parseContent;
+}
+
+/**
+ * SSE streaming utilities for parsing server-sent events
+ */
+
+/**
+ * Parse a single SSE data line into a StreamEvent
+ */
+declare function parseSSEData(data: string): StreamEvent | null;
+/**
+ * Parse SSE chunk into lines and extract data
+ */
+declare function parseSSEChunk(chunk: string): Generator<string>;
+/**
+ * Create an async generator that streams events from a Response
+ */
+declare function streamResponse(response: Response, signal?: AbortSignal): AsyncGenerator<StreamEvent>;
+
+export { type ActiveWorkflow, type Citation, type ContextData, type Conversation, ConversationManager, CrowClient, type CrowClientConfig, type CrowEventCallbacks, type IdentifyOptions, IdentityManager, type IdentityState, type Message, type StreamEvent, type ToolHandler, type ToolHandlers, ToolManager, type ToolResult, type WorkflowTodo, parseSSEChunk, parseSSEData, streamResponse };