paprflare-sdk 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,759 @@
+import { z } from 'zod';
+import EventEmitter from 'eventemitter3';
+
+interface Message {
+    id: string;
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+    toolCalls?: ToolCall[];
+    toolResults?: ToolResult[];
+    metadata?: Record<string, unknown>;
+    timestamp?: number;
+}
+interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+interface ToolResult {
+    toolCallId: string;
+    result: unknown;
+    error?: string;
+}
+interface Tool {
+    name: string;
+    description: string;
+    parameters: z.ZodSchema;
+    execute?: (args: unknown) => Promise<unknown> | unknown;
+}
+type StreamEvent = {
+    type: 'text-delta';
+    delta: string;
+} | {
+    type: 'tool-call-start';
+    toolCall: ToolCall;
+} | {
+    type: 'tool-call-delta';
+    toolCallId: string;
+    delta: string;
+} | {
+    type: 'tool-call-end';
+    toolCall: ToolCall;
+} | {
+    type: 'tool-result';
+    result: ToolResult;
+} | {
+    type: 'metadata';
+    metadata: Record<string, unknown>;
+} | {
+    type: 'usage';
+    usage: TokenUsage;
+} | {
+    type: 'error';
+    error: string;
+} | {
+    type: 'done';
+    finalMessage: Message;
+} | {
+    type: 'artifact-start';
+    artifact: ArtifactMetadata;
+} | {
+    type: 'artifact-delta';
+    delta: string;
+} | {
+    type: 'artifact-end';
+    artifact: Artifact;
+};
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+interface ArtifactMetadata {
+    id: string;
+    type: 'code' | 'document' | 'chart' | 'ui-component' | 'custom';
+    language?: string;
+    title?: string;
+    description?: string;
+}
+interface Artifact extends ArtifactMetadata {
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+interface ChatConfig {
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    frequencyPenalty?: number;
+    presencePenalty?: number;
+    stop?: string[];
+    tools?: Tool[];
+    toolChoice?: 'auto' | 'required' | 'none' | {
+        name: string;
+    };
+    stream?: boolean;
+    output?: {
+        schema: z.ZodSchema;
+        mode?: 'json' | 'function';
+    };
+    artifacts?: {
+        enabled: boolean;
+        autoDetect?: boolean;
+    };
+    cache?: {
+        enabled: boolean;
+        ttl?: number;
+        key?: string;
+    };
+    retry?: {
+        maxAttempts: number;
+        initialDelay: number;
+        maxDelay: number;
+        backoffMultiplier: number;
+    };
+    metadata?: Record<string, unknown>;
+}
+interface ProviderConfig {
+    apiKey: string;
+    baseURL?: string;
+    organization?: string;
+    timeout?: number;
+    maxRetries?: number;
+    headers?: Record<string, string>;
+}
+type PaprFlareMode = 'cloud' | 'self-managed';
+interface CloudConfig {
+    apiKey: string;
+    baseURL?: string;
+    region?: 'in-mumbai' | 'in-delhi' | 'global';
+}
+interface SelfManagedConfig {
+    provider: ProviderCallback;
+    cache?: CacheConfig;
+}
+interface CacheConfig {
+    type: 'redis' | 'memory';
+    redis?: {
+        host: string;
+        port: number;
+        password?: string;
+        db?: number;
+    };
+    memory?: {
+        maxSize: number;
+    };
+}
+type ProviderCallback = (messages: Message[], config: ChatConfig) => AsyncGenerator<StreamEvent, void, unknown>;
+interface ChatResponse {
+    message: Message;
+    usage?: TokenUsage;
+    metadata?: Record<string, unknown>;
+}
+interface StreamingChatResponse {
+    stream: AsyncGenerator<StreamEvent, void, unknown>;
+    toReadableStream: () => ReadableStream<Uint8Array>;
+    pipeToResponse: (response: Response) => Promise<void>;
+    mergeStreams: (...streams: AsyncGenerator<StreamEvent>[]) => AsyncGenerator<StreamEvent>;
+}
+
+/**
+ * Chat state interface
+ */
+interface ChatState {
+    messages: Message[];
+    currentMessage: string;
+    isStreaming: boolean;
+    error: string | null;
+    artifacts: Artifact[];
+    currentArtifact: Artifact | null;
+    toolCalls: ToolCall[];
+    usage: TokenUsage | null;
+    metadata: Record<string, unknown>;
+    addMessage: (message: Message) => void;
+    updateMessage: (id: string, updates: Partial<Message>) => void;
+    setCurrentMessage: (message: string) => void;
+    setStreaming: (isStreaming: boolean) => void;
+    setError: (error: string | null) => void;
+    addArtifact: (artifact: Artifact) => void;
+    setCurrentArtifact: (artifact: Artifact | null) => void;
+    addToolCall: (toolCall: ToolCall) => void;
+    addToolResult: (result: ToolResult) => void;
+    setUsage: (usage: TokenUsage) => void;
+    setMetadata: (metadata: Record<string, unknown>) => void;
+    reset: () => void;
+}
+/**
+ * Hook configuration
+ */
+interface UsePaprFlareConfig {
+    apiEndpoint: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    defaultConfig?: Partial<ChatConfig>;
+    onError?: (error: Error) => void;
+    onComplete?: (message: Message) => void;
+    onArtifact?: (artifact: Artifact) => void;
+    onToolCall?: (toolCall: ToolCall) => void;
+}
+
+interface CacheOptions {
+    type: 'redis' | 'memory';
+    ttl?: number;
+    redis?: {
+        host: string;
+        port: number;
+        password?: string;
+        db?: number;
+        keyPrefix?: string;
+    };
+    memory?: {
+        maxSize: number;
+        maxAge?: number;
+    };
+}
+/**
+ * Abstract cache interface
+ */
+interface ICache {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+}
+/**
+ * Redis cache implementation for distributed caching
+ */
+declare class RedisCache implements ICache {
+    private client;
+    private keyPrefix;
+    private defaultTTL;
+    constructor(options: CacheOptions['redis'] & {
+        ttl?: number;
+    });
+    private getKey;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    disconnect(): Promise<void>;
+}
+/**
+ * In-memory LRU cache for single-instance or development use
+ */
+declare class MemoryCache implements ICache {
+    private cache;
+    constructor(options: CacheOptions['memory']);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+}
+/**
+ * Cache manager with automatic cache key generation
+ */
+declare class CacheManager {
+    private cache;
+    private enabled;
+    constructor(options: CacheOptions);
+    /**
+     * Generate cache key from messages and config
+     */
+    private generateCacheKey;
+    /**
+     * Get cached response
+     */
+    getCachedResponse(messages: Message[], config: ChatConfig): Promise<StreamEvent[] | null>;
+    /**
+     * Cache response
+     */
+    cacheResponse(messages: Message[], config: ChatConfig, events: StreamEvent[]): Promise<void>;
+    /**
+     * Invalidate cache
+     */
+    invalidate(messages: Message[], config: ChatConfig): Promise<void>;
+    /**
+     * Clear all cache
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Disable caching
+     */
+    disable(): void;
+    /**
+     * Enable caching
+     */
+    enable(): void;
+}
+
+interface PaprFlareClientConfig {
+    mode: PaprFlareMode;
+    cloud?: CloudConfig;
+    selfManaged?: SelfManagedConfig;
+    rateLimit?: {
+        maxConcurrent?: number;
+        interval?: number;
+        intervalCap?: number;
+    };
+    defaultRetry?: {
+        maxAttempts: number;
+        initialDelay: number;
+        maxDelay: number;
+        backoffMultiplier: number;
+    };
+}
+/**
+ * Main PaprFlare client for AI interactions
+ * Optimized for millions of throughputs with built-in caching, rate limiting, and retry logic
+ */
+declare class PaprFlareClient {
+    private mode;
+    private cloudConfig?;
+    private providerCallback?;
+    private cacheManager?;
+    private queue;
+    private mutex;
+    private defaultRetryConfig;
+    constructor(config: PaprFlareClientConfig);
+    /**
+     * Main chat method - handles both streaming and non-streaming responses
+     */
+    chat(messages: Message[], config?: ChatConfig): Promise<ChatResponse | StreamingChatResponse>;
+    /**
+     * Execute chat with retry logic
+     */
+    private executeChat;
+    /**
+     * Execute chat in cloud mode
+     */
+    private executeCloudChat;
+    /**
+     * Execute chat in self-managed mode
+     */
+    private executeSelfManagedChat;
+    /**
+     * Execute structured output generation
+     */
+    private executeStructuredOutput;
+    /**
+     * Create streaming response object
+     */
+    private createStreamingResponse;
+    /**
+     * Parse cloud API stream
+     */
+    private parseCloudStream;
+    /**
+     * Cache stream events
+     */
+    private cacheStream;
+    /**
+     * Convert events to generator
+     */
+    private eventsToGenerator;
+    /**
+     * Convert events to response
+     */
+    private eventsToResponse;
+    /**
+     * Validate configuration
+     */
+    private validateConfig;
+    /**
+     * Get queue statistics
+     */
+    getQueueStats(): {
+        size: number;
+        pending: number;
+        concurrency: number;
+    };
+    /**
+     * Clear cache
+     */
+    clearCache(): Promise<void>;
+}
+/**
+ * Create structured output helper
+ */
+declare function structuredOutput<T extends z.ZodSchema>(schema: T): {
+    schema: T;
+    mode: "json";
+};
+
+interface AnthropicConfig extends ProviderConfig {
+    model?: string;
+    anthropicVersion?: string;
+}
+/**
+ * Anthropic (Claude) provider for PaprFlare
+ */
+declare class AnthropicProvider {
+    private config;
+    private baseURL;
+    constructor(config: AnthropicConfig);
+    /**
+     * Create provider callback for PaprFlare client
+     */
+    createCallback(): ProviderCallback;
+    /**
+     * Stream chat completion
+     */
+    private streamChat;
+    /**
+     * Parse Anthropic SSE stream
+     */
+    private parseStream;
+    /**
+     * Format messages for Anthropic API
+     */
+    private formatMessages;
+    /**
+     * Format tools for Anthropic API
+     */
+    private formatTools;
+    /**
+     * Convert Zod schema to JSON Schema (simplified)
+     */
+    private zodToJsonSchema;
+}
+/**
+ * Create Anthropic provider instance
+ */
+declare function createAnthropicProvider(config: AnthropicConfig): ProviderCallback;
+
+interface GoogleConfig extends ProviderConfig {
+    model?: string;
+}
+/**
+ * Google (Gemini) provider for PaprFlare
+ */
+declare class GoogleProvider {
+    private config;
+    private baseURL;
+    constructor(config: GoogleConfig);
+    /**
+     * Create provider callback for PaprFlare client
+     */
+    createCallback(): ProviderCallback;
+    /**
+     * Stream chat completion
+     */
+    private streamChat;
+    /**
+     * Parse Google AI stream
+     */
+    private parseStream;
+    /**
+     * Format messages for Google AI API
+     */
+    private formatMessages;
+    /**
+     * Format tools for Google AI API
+     */
+    private formatTools;
+    /**
+     * Convert Zod schema to JSON Schema (simplified)
+     */
+    private zodToJsonSchema;
+}
+/**
+ * Create Google provider instance
+ */
+declare function createGoogleProvider(config: GoogleConfig): ProviderCallback;
+
+interface OpenAIConfig extends ProviderConfig {
+    model?: string;
+}
+/**
+ * OpenAI provider for PaprFlare
+ */
+declare class OpenAIProvider {
+    private config;
+    private baseURL;
+    constructor(config: OpenAIConfig);
+    /**
+     * Create provider callback for PaprFlare client
+     */
+    createCallback(): ProviderCallback;
+    /**
+     * Stream chat completion
+     */
+    private streamChat;
+    /**
+     * Parse OpenAI SSE stream
+     */
+    private parseStream;
+    /**
+     * Format messages for OpenAI API
+     */
+    private formatMessages;
+    /**
+     * Format tools for OpenAI API
+     */
+    private formatTools;
+    /**
+     * Convert Zod schema to JSON Schema (simplified)
+     */
+    private zodToJsonSchema;
+}
+/**
+ * Create OpenAI provider instance
+ */
+declare function createOpenAIProvider(config: OpenAIConfig): ProviderCallback;
+
+/**
+ * Token counter with caching for high performance
+ */
+declare class TokenCounter {
+    private encoding;
+    private cache;
+    private maxCacheSize;
+    constructor(model?: string, maxCacheSize?: number);
+    /**
+     * Count tokens in a string
+     */
+    countTokens(text: string): number;
+    /**
+     * Count tokens in messages
+     */
+    countMessageTokens(messages: Message[]): number;
+    /**
+     * Estimate cost based on token count
+     * Prices are approximate and should be updated based on actual provider pricing
+     */
+    estimateCost(promptTokens: number, completionTokens: number, model: string): number;
+    /**
+     * Clear the cache
+     */
+    clearCache(): void;
+    /**
+     * Free the encoding
+     */
+    dispose(): void;
+}
+/**
+ * Get the default token counter instance
+ */
+declare function getTokenCounter(model?: string): TokenCounter;
+/**
+ * Quick token counting function
+ */
+declare function countTokens(text: string, model?: string): number;
+/**
+ * Quick message token counting function
+ */
+declare function countMessageTokens(messages: Message[], model?: string): number;
+
+/**
+ * Generate a unique ID
+ */
+declare function generateId(prefix?: string): string;
+/**
+ * Create a stable hash for cache keys
+ */
+declare function createCacheKey(data: unknown): string;
+/**
+ * Format messages for provider APIs
+ */
+declare function formatMessages(messages: Message[]): Message[];
+/**
+ * Retry with exponential backoff
+ */
+declare function retry<T>(fn: () => Promise<T>, options: {
+    maxAttempts: number;
+    initialDelay: number;
+    maxDelay: number;
+    backoffMultiplier: number;
+    onRetry?: (attempt: number, error: Error) => void;
+}): Promise<T>;
+/**
+ * Sleep for a given duration
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Chunk an array into smaller arrays
+ */
+declare function chunk<T>(array: T[], size: number): T[][];
+/**
+ * Debounce a function
+ */
+declare function debounce<T extends (...args: any[]) => any>(fn: T, delay: number): (...args: Parameters<T>) => void;
+/**
+ * Throttle a function
+ */
+declare function throttle<T extends (...args: any[]) => any>(fn: T, limit: number): (...args: Parameters<T>) => void;
+/**
+ * Safely parse JSON
+ */
+declare function safeJsonParse<T = unknown>(json: string): T | null;
+/**
+ * Check if a value is a plain object
+ */
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Deep merge objects
+ */
+declare function deepMerge<T extends Record<string, any>>(target: T, ...sources: Partial<T>[]): T;
+/**
+ * Convert async generator to array
+ */
+declare function streamToArray<T>(stream: AsyncGenerator<T>): Promise<T[]>;
+/**
+ * Measure execution time
+ */
+declare function measureTime<T>(fn: () => Promise<T>): Promise<{
+    result: T;
+    duration: number;
+}>;
+
+/**
+ * StreamWriter for generating and managing streaming events
+ * Handles live event emission for real-time AI responses
+ */
+declare class StreamWriter extends EventEmitter {
+    private debug;
+    private events;
+    private currentText;
+    private currentToolCall;
+    private currentArtifact;
+    private metadata;
+    private closed;
+    constructor(debug?: boolean);
+    /**
+     * Write text delta
+     */
+    writeText(delta: string): void;
+    /**
+     * Start a tool call
+     */
+    startToolCall(name: string, toolCallId?: string): void;
+    /**
+     * Write tool call arguments delta
+     */
+    writeToolCallDelta(delta: string): void;
+    /**
+     * End tool call with complete arguments
+     */
+    endToolCall(args: Record<string, unknown>): void;
+    /**
+     * Write tool result
+     */
+    writeToolResult(toolCallId: string, result: unknown, error?: string): void;
+    /**
+     * Start an artifact
+     */
+    startArtifact(type: Artifact['type'], options?: {
+        id?: string;
+        language?: string;
+        title?: string;
+        description?: string;
+    }): void;
+    /**
+     * Write artifact content delta
+     */
+    writeArtifactDelta(delta: string): void;
+    /**
+     * End artifact
+     */
+    endArtifact(metadata?: Record<string, unknown>): void;
+    /**
+     * Write metadata
+     */
+    writeMetadata(metadata: Record<string, unknown>): void;
+    /**
+     * Write usage information
+     */
+    writeUsage(usage: TokenUsage): void;
+    /**
+     * Write error
+     */
+    writeError(error: string): void;
+    /**
+     * Complete the stream
+     */
+    done(finalMessage?: Partial<Message>): void;
+    /**
+     * Get all collected events
+     */
+    getEvents(): StreamEvent[];
+    /**
+     * Convert to async generator
+     */
+    toGenerator(): AsyncGenerator<StreamEvent>;
+    /**
+     * Emit event (internal)
+     */
+    private emitEvent;
+    /**
+     * Check if stream is closed
+     */
+    isClosed(): boolean;
+    /**
+     * Reset the writer
+     */
+    reset(): void;
+}
+/**
+ * Create a stream writer
+ */
+declare function createStreamWriter(debug?: boolean): StreamWriter;
+
+/**
+ * Parse SSE stream into structured events
+ */
+declare function parseSSEStream(stream: ReadableStream<Uint8Array>): AsyncGenerator<StreamEvent>;
+/**
+ * Convert async generator to ReadableStream
+ */
+declare function toReadableStream(generator: AsyncGenerator<StreamEvent>): ReadableStream<Uint8Array>;
+/**
+ * Pipe stream to HTTP response (h3 compatible)
+ */
+declare function pipeToResponse(generator: AsyncGenerator<StreamEvent>, response: any): Promise<void>;
+/**
+ * Merge multiple streams into one
+ */
+declare function mergeStreams(...generators: AsyncGenerator<StreamEvent>[]): AsyncGenerator<StreamEvent>;
+/**
+ * Transform stream events
+ */
+declare function transformStream<T>(generator: AsyncGenerator<StreamEvent>, transformer: (event: StreamEvent) => T | null): AsyncGenerator<T>;
+/**
+ * Filter stream events
+ */
+declare function filterStream(generator: AsyncGenerator<StreamEvent>, predicate: (event: StreamEvent) => boolean): AsyncGenerator<StreamEvent>;
+/**
+ * Collect stream into array
+ */
+declare function collectStream(generator: AsyncGenerator<StreamEvent>): Promise<StreamEvent[]>;
+/**
+ * Take first N events from stream
+ */
+declare function takeStream(generator: AsyncGenerator<StreamEvent>, count: number): AsyncGenerator<StreamEvent>;
+/**
+ * Batch stream events
+ */
+declare function batchStream(generator: AsyncGenerator<StreamEvent>, size: number, timeoutMs?: number): AsyncGenerator<StreamEvent[]>;
+
+declare class PaprFlareError extends Error {
+    code: string;
+    statusCode?: number | undefined;
+    details?: unknown | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined, details?: unknown | undefined);
+}
+declare class RateLimitError extends PaprFlareError {
+    retryAfter?: number | undefined;
+    constructor(message: string, retryAfter?: number | undefined);
+}
+declare class ValidationError extends PaprFlareError {
+    constructor(message: string, details?: unknown);
+}
+declare class ProviderError extends PaprFlareError {
+    provider: string;
+    constructor(message: string, provider: string, statusCode?: number);
+}
+
+export { type AnthropicConfig, AnthropicProvider, type Artifact, type ArtifactMetadata, type CacheConfig, CacheManager, type CacheOptions, type ChatConfig, type ChatResponse, type ChatState, type CloudConfig, type GoogleConfig, GoogleProvider, type ICache, MemoryCache, type Message, type OpenAIConfig, OpenAIProvider, PaprFlareClient, type PaprFlareClientConfig, PaprFlareError, type PaprFlareMode, type ProviderCallback, type ProviderConfig, ProviderError, RateLimitError, RedisCache, type SelfManagedConfig, type StreamEvent, StreamWriter, type StreamingChatResponse, TokenCounter, type TokenUsage, type Tool, type ToolCall, type ToolResult, type UsePaprFlareConfig, ValidationError, batchStream, chunk, collectStream, countMessageTokens, countTokens, createAnthropicProvider, createCacheKey, createGoogleProvider, createOpenAIProvider, createStreamWriter, debounce, deepMerge, filterStream, formatMessages, generateId, getTokenCounter, isPlainObject, measureTime, mergeStreams, parseSSEStream, pipeToResponse, retry, safeJsonParse, sleep, streamToArray, structuredOutput, takeStream, throttle, toReadableStream, transformStream };