@snap-agent/core 0.1.0

package/dist/index-CDsqnM8L.d.ts

@@ -0,0 +1,680 @@
+/**
+ * Plugin system for extending agent capabilities
+ */
+interface BasePlugin {
+    name: string;
+    type: 'rag' | 'tool' | 'middleware' | 'analytics';
+    priority?: number;
+}
+interface RAGContext {
+    content: string;
+    sources?: Array<{
+        id: string;
+        title?: string;
+        score?: number;
+        type?: string;
+        [key: string]: any;
+    }>;
+    metadata?: Record<string, any>;
+}
+/**
+ * Document to be ingested into RAG system
+ */
+interface RAGDocument {
+    id: string;
+    content: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * Result of an ingestion operation
+ */
+interface IngestResult {
+    success: boolean;
+    indexed: number;
+    failed: number;
+    errors?: Array<{
+        id: string;
+        error: string;
+    }>;
+    metadata?: Record<string, any>;
+}
+/**
+ * Options for ingestion operations
+ */
+interface IngestOptions {
+    agentId?: string;
+    batchSize?: number;
+    skipExisting?: boolean;
+    overwrite?: boolean;
+    [key: string]: any;
+}
+/**
+ * Options for bulk operations
+ * For 'insert': document with full RAGDocument required
+ * For 'update': document with Partial<RAGDocument> optional
+ * For 'delete': document not needed
+ */
+type BulkOperation = {
+    type: 'insert';
+    id: string;
+    document: RAGDocument;
+} | {
+    type: 'update';
+    id: string;
+    document?: Partial<RAGDocument>;
+} | {
+    type: 'delete';
+    id: string;
+    document?: never;
+};
+interface BulkResult {
+    success: boolean;
+    inserted: number;
+    updated: number;
+    deleted: number;
+    failed: number;
+    errors?: Array<{
+        id: string;
+        operation: string;
+        error: string;
+    }>;
+}
+/**
+ * Authentication configuration for URL-based ingestion
+ */
+type URLSourceAuth = {
+    type: 'bearer';
+    token: string;
+} | {
+    type: 'basic';
+    username: string;
+    password: string;
+} | {
+    type: 'api-key';
+    header: string;
+    key: string;
+} | {
+    type: 'custom';
+    headers: Record<string, string>;
+};
+/**
+ * Configuration for transforming external data to RAGDocuments
+ */
+interface DataTransform {
+    documentPath?: string;
+    fieldMapping?: {
+        id?: string;
+        content?: string;
+        [key: string]: string | undefined;
+    };
+    customTransform?: (data: any) => RAGDocument[];
+}
+/**
+ * Schedule configuration for recurring ingestion
+ */
+interface IngestionSchedule {
+    cron?: string;
+    interval?: number;
+    timezone?: string;
+}
+/**
+ * URL source configuration for data ingestion
+ */
+interface URLSource {
+    url: string;
+    type: 'json' | 'csv' | 'xml' | 'api';
+    auth?: URLSourceAuth;
+    transform?: DataTransform;
+    schedule?: IngestionSchedule;
+    headers?: Record<string, string>;
+    timeout?: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Result of URL-based ingestion
+ */
+interface URLIngestResult extends IngestResult {
+    sourceUrl: string;
+    fetchedAt: Date;
+    documentsFetched: number;
+    scheduleId?: string;
+}
+interface RAGPlugin extends BasePlugin {
+    type: 'rag';
+    /**
+     * Retrieve contextual information for a message
+     */
+    retrieveContext(message: string, options: {
+        agentId: string;
+        threadId?: string;
+        filters?: Record<string, any>;
+        metadata?: Record<string, any>;
+    }): Promise<RAGContext>;
+    /**
+     * Optional: Format the context for the LLM
+     * If not provided, RAGContext.content will be used directly
+     */
+    formatContext?(context: RAGContext): string;
+    /**
+     * Optional: Ingest documents into the RAG system
+     * Allows plugins to provide their own indexing logic
+     */
+    ingest?(documents: RAGDocument[], options?: IngestOptions): Promise<IngestResult>;
+    /**
+     * Optional: Ingest documents from a URL source
+     * Supports CSV, JSON, XML, and API endpoints with authentication and scheduling
+     */
+    ingestFromUrl?(source: URLSource, options?: IngestOptions): Promise<URLIngestResult>;
+    /**
+     * Optional: Handle webhook payloads for real-time updates
+     * Useful for product updates, inventory changes, etc.
+     */
+    handleWebhook?(payload: any, source: string, options?: IngestOptions): Promise<IngestResult>;
+    /**
+     * Optional: Update a single document
+     */
+    update?(id: string, document: Partial<RAGDocument>, options?: IngestOptions): Promise<void>;
+    /**
+     * Optional: Delete document(s) by ID
+     */
+    delete?(ids: string | string[], options?: IngestOptions): Promise<number>;
+    /**
+     * Optional: Bulk operations for efficient batch processing
+     */
+    bulk?(operations: BulkOperation[], options?: IngestOptions): Promise<BulkResult>;
+}
+interface Tool {
+    name: string;
+    description: string;
+    parameters: Record<string, any>;
+    execute: (args: any) => Promise<any>;
+}
+interface ToolPlugin extends BasePlugin {
+    type: 'tool';
+    getTools(): Tool[];
+}
+interface MiddlewarePlugin extends BasePlugin {
+    type: 'middleware';
+    beforeRequest?(messages: any[], context: {
+        agentId: string;
+        threadId?: string;
+    }): Promise<{
+        messages: any[];
+        metadata?: any;
+    }>;
+    afterResponse?(response: string, context: {
+        agentId: string;
+        threadId?: string;
+        metadata?: any;
+    }): Promise<{
+        response: string;
+        metadata?: any;
+    }>;
+}
+/**
+ * Performance timing breakdown
+ */
+interface PerformanceTimings {
+    total: number;
+    llmApiTime?: number;
+    ragRetrievalTime?: number;
+    pluginExecutionTime?: number;
+    dbQueryTime?: number;
+    timeToFirstToken?: number;
+    timeToLastToken?: number;
+    queueTime?: number;
+}
+/**
+ * RAG-specific metrics
+ */
+interface RAGMetrics {
+    enabled: boolean;
+    documentsRetrieved?: number;
+    vectorSearchTime?: number;
+    embeddingTime?: number;
+    cacheHit?: boolean;
+    avgSimilarityScore?: number;
+    rerankTime?: number;
+    contextLength?: number;
+    contextTokens?: number;
+    sourcesCount?: number;
+}
+/**
+ * Token and cost metrics
+ */
+interface TokenMetrics {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    estimatedCost?: number;
+    embeddingTokens?: number;
+    embeddingCost?: number;
+}
+/**
+ * Request tracking data (extended)
+ */
+interface RequestTrackingData {
+    agentId: string;
+    threadId?: string;
+    userId?: string;
+    organizationId?: string;
+    message: string;
+    messageLength: number;
+    timestamp: Date;
+    model?: string;
+    provider?: string;
+}
+/**
+ * Response tracking data (extended)
+ */
+interface ResponseTrackingData {
+    agentId: string;
+    threadId?: string;
+    userId?: string;
+    organizationId?: string;
+    response: string;
+    responseLength: number;
+    timestamp: Date;
+    timings: PerformanceTimings;
+    tokens: TokenMetrics;
+    rag?: RAGMetrics;
+    success: boolean;
+    errorType?: string;
+    errorMessage?: string;
+    model?: string;
+    provider?: string;
+}
+/**
+ * Error tracking data
+ */
+interface ErrorTrackingData {
+    agentId: string;
+    threadId?: string;
+    timestamp: Date;
+    errorType: string;
+    errorMessage: string;
+    errorCode?: string;
+    isRetryable?: boolean;
+    component?: 'llm' | 'rag' | 'plugin' | 'database' | 'network';
+}
+interface AnalyticsPlugin extends BasePlugin {
+    type: 'analytics';
+    /**
+     * Track incoming request (basic - for backwards compatibility)
+     */
+    trackRequest(data: {
+        agentId: string;
+        threadId?: string;
+        message: string;
+        timestamp: Date;
+    }): Promise<void>;
+    /**
+     * Track response (basic - for backwards compatibility)
+     */
+    trackResponse(data: {
+        agentId: string;
+        threadId?: string;
+        response: string;
+        latency: number;
+        tokensUsed?: number;
+        timestamp: Date;
+    }): Promise<void>;
+    /**
+     * Track request with extended data (optional)
+     */
+    trackRequestExtended?(data: RequestTrackingData): Promise<void>;
+    /**
+     * Track response with extended metrics (optional)
+     */
+    trackResponseExtended?(data: ResponseTrackingData): Promise<void>;
+    /**
+     * Track errors (optional)
+     */
+    trackError?(data: ErrorTrackingData): Promise<void>;
+    /**
+     * Get aggregated metrics (optional)
+     */
+    getMetrics?(options?: {
+        agentId?: string;
+        startDate?: Date;
+        endDate?: Date;
+        groupBy?: 'hour' | 'day' | 'week' | 'month';
+    }): Promise<Record<string, any>>;
+}
+type Plugin = RAGPlugin | ToolPlugin | MiddlewarePlugin | AnalyticsPlugin;
+
+type ProviderType = 'openai' | 'anthropic' | 'google';
+interface ProviderConfig {
+    openai?: {
+        apiKey: string;
+    };
+    anthropic?: {
+        apiKey: string;
+    };
+    google?: {
+        apiKey: string;
+    };
+}
+/**
+ * RAG configuration for zero-config RAG setup
+ */
+interface RAGConfig {
+    /**
+     * Enable RAG with default plugin
+     */
+    enabled: boolean;
+    /**
+     * API key for embedding provider
+     * If not provided, will use the provider's API key from ClientConfig
+     */
+    embeddingProviderApiKey?: string;
+    /**
+     * Embedding provider to use
+     * @default 'openai'
+     */
+    embeddingProvider?: 'openai';
+    /**
+     * Embedding model to use
+     * @default 'text-embedding-3-small'
+     */
+    embeddingModel?: string;
+    /**
+     * Number of results to return
+     * @default 5
+     */
+    limit?: number;
+}
+interface AgentConfig {
+    name: string;
+    description?: string;
+    instructions: string;
+    provider: ProviderType;
+    model: string;
+    userId: string;
+    metadata?: Record<string, any>;
+    organizationId?: string;
+    phone?: string;
+    plugins?: Plugin[];
+    rag?: RAGConfig;
+}
+interface AgentData extends AgentConfig {
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    files: AgentFile[];
+}
+interface AgentFile {
+    fileId: string;
+    filename: string;
+    addedAt: Date;
+}
+interface ThreadConfig {
+    agentId: string;
+    userId: string;
+    name?: string;
+    metadata?: Record<string, any>;
+    organizationId?: string;
+    endUserId?: string;
+}
+interface ThreadData extends ThreadConfig {
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    messages: MessageData[];
+    isPendingThread: boolean;
+}
+type MessageRole = 'user' | 'assistant' | 'system';
+interface MessageData {
+    id: string;
+    role: MessageRole;
+    content: string;
+    timestamp: Date;
+    metadata?: Record<string, any>;
+    attachments?: MessageAttachment[];
+}
+interface MessageAttachment {
+    fileId: string;
+    filename: string;
+    contentType: string;
+    size: number;
+}
+interface ChatRequest {
+    threadId: string;
+    message: string;
+    attachments?: MessageAttachment[];
+    useRAG?: boolean;
+    ragFilters?: Record<string, any>;
+    contextLength?: number;
+}
+interface ChatResponse {
+    reply: string;
+    messageId: string;
+    threadId: string;
+    timestamp: Date;
+    metadata?: Record<string, any>;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+interface StreamCallbacks {
+    onChunk: (chunk: string) => void;
+    onComplete: (fullResponse: string, metadata?: Record<string, any>) => void;
+    onError: (error: Error) => void;
+}
+interface StorageAdapter {
+    createAgent(config: AgentConfig): Promise<string>;
+    getAgent(agentId: string): Promise<AgentData | null>;
+    updateAgent(agentId: string, updates: Partial<AgentConfig>): Promise<void>;
+    deleteAgent(agentId: string): Promise<void>;
+    listAgents(userId: string, organizationId?: string): Promise<AgentData[]>;
+    createThread(config: ThreadConfig): Promise<string>;
+    getThread(threadId: string): Promise<ThreadData | null>;
+    updateThread(threadId: string, updates: Partial<ThreadConfig>): Promise<void>;
+    deleteThread(threadId: string): Promise<void>;
+    listThreads(filters: {
+        userId?: string;
+        agentId?: string;
+        organizationId?: string;
+    }): Promise<ThreadData[]>;
+    addMessage(threadId: string, role: MessageRole, content: string, attachments?: MessageAttachment[]): Promise<string>;
+    getMessages(threadId: string, limit?: number): Promise<MessageData[]>;
+    getConversationContext(threadId: string, maxMessages?: number): Promise<Array<{
+        role: string;
+        content: string;
+    }>>;
+}
+interface ClientConfig {
+    storage: StorageAdapter;
+    providers: ProviderConfig;
+}
+declare class AgentSDKError extends Error {
+    constructor(message: string);
+}
+declare class AgentNotFoundError extends AgentSDKError {
+    constructor(agentId: string);
+}
+declare class ThreadNotFoundError extends AgentSDKError {
+    constructor(threadId: string);
+}
+declare class ProviderNotFoundError extends AgentSDKError {
+    constructor(provider: string);
+}
+declare class InvalidConfigError extends AgentSDKError {
+    constructor(message: string);
+}
+
+interface MongoDBStorageConfig {
+    uri: string;
+    dbName?: string;
+    agentsCollection?: string;
+    threadsCollection?: string;
+}
+/**
+ * MongoDB Storage Adapter
+ * Provides persistent storage for agents and threads using MongoDB
+ */
+declare class MongoDBStorage implements StorageAdapter {
+    private client;
+    private db;
+    private config;
+    constructor(config: MongoDBStorageConfig | string);
+    private ensureConnection;
+    disconnect(): Promise<void>;
+    createAgent(config: AgentConfig): Promise<string>;
+    getAgent(agentId: string): Promise<AgentData | null>;
+    updateAgent(agentId: string, updates: Partial<AgentConfig>): Promise<void>;
+    deleteAgent(agentId: string): Promise<void>;
+    listAgents(userId: string, organizationId?: string): Promise<AgentData[]>;
+    createThread(config: ThreadConfig): Promise<string>;
+    getThread(threadId: string): Promise<ThreadData | null>;
+    updateThread(threadId: string, updates: Partial<ThreadConfig>): Promise<void>;
+    deleteThread(threadId: string): Promise<void>;
+    listThreads(filters: {
+        userId?: string;
+        agentId?: string;
+        organizationId?: string;
+    }): Promise<ThreadData[]>;
+    addMessage(threadId: string, role: MessageRole, content: string, attachments?: MessageAttachment[]): Promise<string>;
+    getMessages(threadId: string, limit?: number): Promise<MessageData[]>;
+    getConversationContext(threadId: string, maxMessages?: number): Promise<Array<{
+        role: string;
+        content: string;
+    }>>;
+    private agentDocToData;
+    private threadDocToData;
+}
+
+/**
+ * In-Memory Storage Adapter
+ * Provides temporary storage for agents and threads (useful for testing and development)
+ */
+declare class MemoryStorage implements StorageAdapter {
+    private agents;
+    private threads;
+    private idCounter;
+    private generateId;
+    createAgent(config: AgentConfig): Promise<string>;
+    getAgent(agentId: string): Promise<AgentData | null>;
+    updateAgent(agentId: string, updates: Partial<AgentConfig>): Promise<void>;
+    deleteAgent(agentId: string): Promise<void>;
+    listAgents(userId: string, organizationId?: string): Promise<AgentData[]>;
+    createThread(config: ThreadConfig): Promise<string>;
+    getThread(threadId: string): Promise<ThreadData | null>;
+    updateThread(threadId: string, updates: Partial<ThreadConfig>): Promise<void>;
+    deleteThread(threadId: string): Promise<void>;
+    listThreads(filters: {
+        userId?: string;
+        agentId?: string;
+        organizationId?: string;
+    }): Promise<ThreadData[]>;
+    addMessage(threadId: string, role: MessageRole, content: string, attachments?: MessageAttachment[]): Promise<string>;
+    getMessages(threadId: string, limit?: number): Promise<MessageData[]>;
+    getConversationContext(threadId: string, maxMessages?: number): Promise<Array<{
+        role: string;
+        content: string;
+    }>>;
+    /**
+     * Clear all stored data
+     */
+    clear(): void;
+    /**
+     * Get statistics about stored data
+     */
+    getStats(): {
+        agents: number;
+        threads: number;
+        messages: number;
+    };
+}
+
+/**
+ * Upstash Redis configuration
+ */
+interface UpstashStorageConfig {
+    /**
+     * Upstash Redis REST URL
+     * @example "https://your-redis.upstash.io"
+     */
+    url: string;
+    /**
+     * Upstash Redis REST token
+     */
+    token: string;
+    /**
+     * Optional key prefix for multi-tenancy
+     * @default "snap-agent"
+     */
+    prefix?: string;
+}
+/**
+ * Upstash Redis Storage Adapter
+ *
+ * Edge-compatible persistent storage using Upstash Redis REST API.
+ * Works with Cloudflare Workers, Vercel Edge, Deno Deploy, and any WinterCG runtime.
+ *
+ * @example
+ * ```typescript
+ * import { UpstashStorage } from '@snap-agent/core/storage';
+ *
+ * const storage = new UpstashStorage({
+ *   url: process.env.UPSTASH_REDIS_REST_URL!,
+ *   token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+ * });
+ *
+ * const client = createClient({
+ *   storage,
+ *   providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } },
+ * });
+ * ```
+ */
+declare class UpstashStorage implements StorageAdapter {
+    private url;
+    private token;
+    private prefix;
+    constructor(config: UpstashStorageConfig);
+    private command;
+    private pipeline;
+    private key;
+    private generateId;
+    createAgent(config: AgentConfig): Promise<string>;
+    getAgent(agentId: string): Promise<AgentData | null>;
+    updateAgent(agentId: string, updates: Partial<AgentConfig>): Promise<void>;
+    deleteAgent(agentId: string): Promise<void>;
+    listAgents(userId: string, organizationId?: string): Promise<AgentData[]>;
+    createThread(config: ThreadConfig): Promise<string>;
+    getThread(threadId: string): Promise<ThreadData | null>;
+    updateThread(threadId: string, updates: Partial<ThreadConfig>): Promise<void>;
+    deleteThread(threadId: string): Promise<void>;
+    listThreads(filters: {
+        userId?: string;
+        agentId?: string;
+        organizationId?: string;
+    }): Promise<ThreadData[]>;
+    addMessage(threadId: string, role: MessageRole, content: string, attachments?: MessageAttachment[]): Promise<string>;
+    getMessages(threadId: string, limit?: number): Promise<MessageData[]>;
+    getConversationContext(threadId: string, maxMessages?: number): Promise<Array<{
+        role: string;
+        content: string;
+    }>>;
+    private parseStoredAgent;
+    private parseStoredThread;
+    /**
+     * Test connection to Upstash Redis
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Clear all data with this prefix (use with caution!)
+     */
+    clear(): Promise<void>;
+    /**
+     * Get storage statistics
+     */
+    getStats(): Promise<{
+        agents: number;
+        threads: number;
+    }>;
+}
+
+export { type AgentData as A, type BulkOperation as B, type ClientConfig as C, AgentSDKError as D, type ErrorTrackingData as E, AgentNotFoundError as F, ThreadNotFoundError as G, ProviderNotFoundError as H, type IngestOptions as I, InvalidConfigError as J, MongoDBStorage as K, MemoryStorage as L, type MessageRole as M, UpstashStorage as N, type MongoDBStorageConfig as O, type ProviderConfig as P, type UpstashStorageConfig as Q, type RAGDocument as R, type StorageAdapter as S, type ThreadData as T, type URLSource as U, type ProviderType as a, type AgentConfig as b, type AgentFile as c, type Plugin as d, type IngestResult as e, type BulkResult as f, type URLIngestResult as g, type ThreadConfig as h, type MessageAttachment as i, type MessageData as j, type ChatRequest as k, type ChatResponse as l, type StreamCallbacks as m, type RAGPlugin as n, type ToolPlugin as o, type MiddlewarePlugin as p, type AnalyticsPlugin as q, type RAGContext as r, type RAGConfig as s, type BasePlugin as t, type Tool as u, type PerformanceTimings as v, type RAGMetrics as w, type TokenMetrics as x, type RequestTrackingData as y, type ResponseTrackingData as z };