@standardagents/client 0.1.0-dev.ffffff

package/dist/index.d.ts

@@ -0,0 +1,476 @@
+interface Message {
+    id: string;
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | null;
+    name?: string | null;
+    tool_calls?: string | null;
+    tool_call_id?: string | null;
+    log_id?: string | null;
+    created_at: number;
+    request_sent_at?: number | null;
+    response_completed_at?: number | null;
+    status?: "pending" | "completed" | "failed";
+    silent?: boolean;
+    tool_status?: "success" | "error" | null;
+    reasoning_content?: string | null;
+    reasoning_details?: string | null;
+    parent_id?: string | null;
+    depth?: number;
+    attachments?: string | null;
+}
+/**
+ * Attachment reference stored in messages.attachments (JSON array)
+ * Represents a file that has been uploaded to the thread's filesystem
+ */
+interface AttachmentRef {
+    id: string;
+    type: "file";
+    path: string;
+    name: string;
+    mimeType: string;
+    size: number;
+    width?: number;
+    height?: number;
+    description?: string;
+}
+/**
+ * Unified file representation for client-side state
+ * Represents both pending uploads and committed attachments
+ */
+interface ThreadFile {
+    id: string;
+    name: string;
+    mimeType: string;
+    size: number;
+    isImage: boolean;
+    localPreviewUrl: string | null;
+    status: 'uploading' | 'ready' | 'committed' | 'error';
+    error?: string;
+    path?: string;
+    width?: number;
+    height?: number;
+    messageId?: string;
+}
+interface WorkItem {
+    id: string;
+    type: "tool_call" | "tool_result";
+    name?: string;
+    content: string | null;
+    status?: "pending" | "success" | "error" | null;
+    tool_call_id?: string;
+}
+interface WorkMessage {
+    id: string;
+    type: "workblock";
+    content: string | null;
+    reasoning_content?: string | null;
+    workItems: WorkItem[];
+    status: "pending" | "completed" | "failed";
+    created_at: number;
+    depth?: number;
+}
+type ThreadMessage = Message | WorkMessage;
+interface AgentBuilderConfig {
+    endpoint: string;
+}
+interface GetMessagesOptions {
+    limit?: number;
+    offset?: number;
+    depth?: number;
+    includeSilent?: boolean;
+}
+interface MessageDataEvent {
+    type: "message_data";
+    message_id: string;
+    depth: number;
+    data: Message;
+}
+interface MessageChunkEvent {
+    type: "message_chunk";
+    message_id: string;
+    depth: number;
+    chunk: string;
+}
+interface ErrorEvent {
+    type: "error";
+    error: string;
+}
+/**
+ * Custom thread event emitted via emitThreadEvent on the backend
+ */
+interface ThreadEvent<T = unknown> {
+    type: "event";
+    eventType: string;
+    data: T;
+    timestamp: number;
+}
+type MessageStreamEvent = MessageDataEvent | MessageChunkEvent | ErrorEvent | ThreadEvent;
+interface LogDataEvent {
+    type: "log_data";
+    log_id: string;
+    data: any;
+}
+interface CustomEvent {
+    type: "custom";
+    customType: string;
+    value: any;
+    timestamp: number;
+}
+interface StoppedByUserEvent {
+    type: "stopped_by_user";
+    timestamp: number;
+}
+type LogStreamEvent = LogDataEvent | CustomEvent | StoppedByUserEvent;
+interface SendMessagePayload {
+    role: "user" | "assistant" | "system";
+    content: string;
+    silent?: boolean;
+    attachments?: string[];
+}
+interface Thread {
+    id: string;
+    agent_id: string;
+    metadata?: Record<string, any>;
+    created_at: number;
+}
+interface MessageWebSocketCallbacks {
+    onMessage?: (event: MessageDataEvent) => void;
+    onChunk?: (event: MessageChunkEvent) => void;
+    onEvent?: (event: ThreadEvent) => void;
+    onError?: (event: ErrorEvent) => void;
+    onOpen?: () => void;
+    onClose?: () => void;
+}
+interface LogWebSocketCallbacks {
+    onLog?: (event: LogDataEvent) => void;
+    onCustom?: (event: CustomEvent) => void;
+    onStopped?: (event: StoppedByUserEvent) => void;
+    onOpen?: () => void;
+    onClose?: () => void;
+}
+type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+interface ThreadConnectionCallbacks {
+    onMessage?: (event: MessageDataEvent) => void;
+    onChunk?: (event: MessageChunkEvent) => void;
+    onEvent?: (event: ThreadEvent) => void;
+    onError?: (event: ErrorEvent) => void;
+    onStatusChange?: (status: ConnectionStatus) => void;
+}
+interface CreateThreadPayload {
+    agent_id: string;
+    metadata?: Record<string, any>;
+}
+
+declare class AgentBuilderClient {
+    private endpoint;
+    private token;
+    constructor(endpoint: string);
+    /**
+     * Get the current endpoint
+     */
+    getEndpoint(): string;
+    /**
+     * Create a new thread
+     */
+    createThread(payload: CreateThreadPayload): Promise<Thread>;
+    /**
+     * Get thread metadata
+     */
+    getThread(id: string): Promise<Thread>;
+    /**
+     * Get messages from a thread with optional pagination and filtering
+     */
+    getMessages(id: string, options?: GetMessagesOptions): Promise<Message[]>;
+    /**
+     * Send a message to a thread
+     */
+    sendMessage(id: string, payload: SendMessagePayload): Promise<Message>;
+    /**
+     * Stop execution of a thread
+     */
+    stopExecution(id: string): Promise<void>;
+    /**
+     * Options for file upload
+     */
+    /**
+     * Upload a file to a thread's filesystem
+     * @param threadId - The thread ID
+     * @param file - The file to upload
+     * @param options - Optional upload options
+     * @param options.thumbnail - Base64-encoded thumbnail data (for images)
+     * @param options.width - Image width in pixels
+     * @param options.height - Image height in pixels
+     * @returns AttachmentRef with file metadata
+     */
+    uploadFile(threadId: string, file: File, options?: {
+        thumbnail?: string;
+        width?: number;
+        height?: number;
+    }): Promise<AttachmentRef>;
+    /**
+     * Convert a File to base64 string
+     */
+    private fileToBase64;
+    /**
+     * Get the full URL for a file in a thread's filesystem
+     */
+    getFileUrl(threadId: string, path: string): string;
+    /**
+     * Get the thumbnail URL for an image in a thread's filesystem
+     */
+    getThumbnailUrl(threadId: string, path: string): string;
+    /**
+     * Connect to message WebSocket for real-time message updates
+     */
+    connectMessageWebSocket(id: string, callbacks?: MessageWebSocketCallbacks, options?: {
+        includeSilent?: boolean;
+        depth?: number;
+    }): WebSocket;
+    /**
+     * Connect to log WebSocket for custom events
+     */
+    connectLogWebSocket(id: string, callbacks?: LogWebSocketCallbacks): WebSocket;
+    /**
+     * Get headers for HTTP requests
+     */
+    private getHeaders;
+}
+
+interface ThreadConnectionOptions {
+    /** Maximum message depth to stream (default: 0 for top-level only) */
+    depth?: number;
+    /** Whether to include silent messages (default: false) */
+    includeSilent?: boolean;
+    /** Heartbeat interval in milliseconds (default: 30000) */
+    heartbeatInterval?: number;
+    /** Maximum reconnection delay in milliseconds (default: 30000) */
+    maxReconnectDelay?: number;
+}
+/**
+ * ThreadConnectionManager handles WebSocket connection lifecycle for a thread.
+ * Provides automatic reconnection with exponential backoff and heartbeat keep-alive.
+ *
+ * This class is framework-agnostic. React and Vue SDKs use this internally
+ * and handle their own reactive state management.
+ *
+ * @example
+ * ```typescript
+ * const manager = new ThreadConnectionManager(client, 'thread-123', {
+ *   onMessage: (event) => updateMessages(event.data),
+ *   onChunk: (event) => appendChunk(event.chunk),
+ *   onStatusChange: (status) => setConnectionStatus(status),
+ * })
+ *
+ * manager.connect()
+ * // ... later
+ * manager.disconnect()
+ * ```
+ */
+declare class ThreadConnectionManager {
+    private client;
+    private threadId;
+    private callbacks;
+    private options;
+    private ws;
+    private status;
+    private reconnectAttempts;
+    private reconnectTimeout;
+    private heartbeatInterval;
+    private isReconnecting;
+    private shouldReconnect;
+    constructor(client: AgentBuilderClient, threadId: string, callbacks?: ThreadConnectionCallbacks, options?: ThreadConnectionOptions);
+    /**
+     * Get current connection status
+     */
+    getStatus(): ConnectionStatus;
+    /**
+     * Get the thread ID this manager is connected to
+     */
+    getThreadId(): string;
+    /**
+     * Connect to the thread WebSocket
+     */
+    connect(): void;
+    /**
+     * Disconnect from the thread WebSocket
+     */
+    disconnect(): void;
+    /**
+     * Update callbacks without reconnecting
+     */
+    updateCallbacks(callbacks: Partial<ThreadConnectionCallbacks>): void;
+    /**
+     * Update options (requires reconnect to take effect for depth/includeSilent)
+     */
+    updateOptions(options: Partial<ThreadConnectionOptions>): void;
+    private setStatus;
+    private startHeartbeat;
+    private clearHeartbeat;
+    private clearReconnectTimeout;
+    private clearTimers;
+    private scheduleReconnect;
+}
+
+/**
+ * FileUploadManager - Framework-agnostic file upload management
+ *
+ * Handles the common logic for file uploads across Vue and React packages.
+ * Each framework integrates this manager with its own state management.
+ */
+
+/**
+ * Callback for receiving file state updates during upload
+ */
+type FileUpdateCallback = (updates: Partial<ThreadFile>) => void;
+/**
+ * Options for upload execution
+ */
+interface UploadOptions {
+    /** Generate and upload thumbnail for images (default: true) */
+    generateThumbnail?: boolean;
+    /** Generate local preview URL for images (default: true) */
+    generatePreview?: boolean;
+}
+/**
+ * FileUploadManager handles the upload lifecycle for files.
+ *
+ * Usage:
+ * 1. Call queueFiles() to create pending file objects for immediate UI display
+ * 2. Call executeUpload() for each file to start the actual upload
+ * 3. Receive state updates via the callback to update your framework's state
+ *
+ * @example
+ * ```typescript
+ * const manager = new FileUploadManager()
+ *
+ * // Queue files for UI display
+ * const pendingFiles = manager.queueFiles(selectedFiles)
+ * setState(prev => [...prev, ...pendingFiles])
+ *
+ * // Start uploads
+ * for (const pending of pendingFiles) {
+ *   manager.executeUpload(threadId, file, pending.id, client, (updates) => {
+ *     setState(prev => prev.map(f =>
+ *       f.id === pending.id ? { ...f, ...updates } : f
+ *     ))
+ *   })
+ * }
+ * ```
+ */
+declare class FileUploadManager {
+    /**
+     * Create a pending file object from a File.
+     * The returned object can be immediately added to state for UI feedback.
+     */
+    createPendingFile(file: File): ThreadFile;
+    /**
+     * Queue multiple files for upload.
+     * Returns an array of pending file objects paired with their source File objects.
+     *
+     * @param files - Files to queue (File array or FileList)
+     * @returns Array of [ThreadFile, File] tuples
+     */
+    queueFiles(files: File[] | FileList): Array<{
+        pending: ThreadFile;
+        file: File;
+    }>;
+    /**
+     * Execute the upload for a file.
+     *
+     * This method:
+     * 1. Generates a local preview for images (async, non-blocking)
+     * 2. Generates a thumbnail for images (if supported)
+     * 3. Uploads the file to the server
+     * 4. Calls onUpdate with state changes at each step
+     *
+     * @param threadId - The thread to upload to
+     * @param file - The file to upload
+     * @param pendingId - The ID of the pending file (from queueFiles)
+     * @param client - The AgentBuilderClient instance
+     * @param onUpdate - Callback for state updates
+     * @param options - Upload options
+     */
+    executeUpload(threadId: string, file: File, pendingId: string, client: AgentBuilderClient, onUpdate: FileUpdateCallback, options?: UploadOptions): Promise<AttachmentRef>;
+    /**
+     * Execute uploads for multiple files in parallel.
+     *
+     * @param threadId - The thread to upload to
+     * @param items - Array of pending/file pairs from queueFiles()
+     * @param client - The AgentBuilderClient instance
+     * @param onUpdate - Callback receiving (pendingId, updates) for each file
+     * @param options - Upload options
+     * @returns Array of upload results (AttachmentRef or Error for each file)
+     */
+    executeUploads(threadId: string, items: Array<{
+        pending: ThreadFile;
+        file: File;
+    }>, client: AgentBuilderClient, onUpdate: (pendingId: string, updates: Partial<ThreadFile>) => void, options?: UploadOptions): Promise<Array<AttachmentRef | Error>>;
+}
+
+/**
+ * Transform a flat list of messages into a list with workblocks.
+ * Groups consecutive assistant tool_calls and their tool results into WorkMessage objects.
+ *
+ * A workblock starts when an assistant message has tool_calls,
+ * and includes all subsequent tool messages until:
+ * - A non-tool message appears
+ * - Another assistant message without tool_calls appears
+ */
+declare function transformToWorkblocks(messages: Message[]): ThreadMessage[];
+
+/**
+ * Parse attachments JSON from a message
+ * Returns empty array if no attachments or invalid JSON
+ */
+declare function parseAttachments(message: Message): AttachmentRef[];
+/**
+ * Check if a MIME type represents an image
+ */
+declare function isImageMimeType(mimeType: string): boolean;
+/**
+ * Convert messages to ThreadFile array
+ * Extracts all committed files from message attachments
+ */
+declare function messagesToFiles(messages: Message[]): ThreadFile[];
+
+/**
+ * Image processing utilities for thumbnail generation
+ * These functions require a browser environment with Canvas support
+ */
+/**
+ * Result of processing an image file
+ */
+interface ImageProcessingResult {
+    /** Base64-encoded thumbnail data (without data URL prefix) */
+    thumbnail: string;
+    /** Original image width */
+    width: number;
+    /** Original image height */
+    height: number;
+}
+/**
+ * Process an image file to generate a thumbnail
+ * @param file - The image file to process
+ * @returns Promise with thumbnail data and dimensions
+ */
+declare function generateImageThumbnail(file: File): Promise<ImageProcessingResult>;
+/**
+ * Check if the current environment supports Canvas (for thumbnail generation)
+ */
+declare function canGenerateThumbnails(): boolean;
+
+/**
+ * File upload helper utilities
+ */
+/**
+ * Generate a unique ID for pending file uploads.
+ * Uses timestamp + random string to ensure uniqueness.
+ */
+declare function generatePendingFileId(): string;
+/**
+ * Read a file as a data URL for image preview.
+ * Returns a base64-encoded data URL that can be used as an image src.
+ */
+declare function readFileAsDataUrl(file: File): Promise<string>;
+
+export { AgentBuilderClient, type AgentBuilderConfig, type AttachmentRef, type ConnectionStatus, type CreateThreadPayload, type CustomEvent, type ErrorEvent, type FileUpdateCallback, FileUploadManager, type GetMessagesOptions, type ImageProcessingResult, type LogDataEvent, type LogStreamEvent, type LogWebSocketCallbacks, type Message, type MessageChunkEvent, type MessageDataEvent, type MessageStreamEvent, type MessageWebSocketCallbacks, type SendMessagePayload, type StoppedByUserEvent, type Thread, type ThreadConnectionCallbacks, ThreadConnectionManager, type ThreadConnectionOptions, type ThreadEvent, type ThreadFile, type ThreadMessage, type UploadOptions, type WorkItem, type WorkMessage, canGenerateThumbnails, generateImageThumbnail, generatePendingFileId, isImageMimeType, messagesToFiles, parseAttachments, readFileAsDataUrl, transformToWorkblocks };