graphlit-client 1.0.20250531004 → 1.0.20250610001

package/dist/streaming/ui-event-adapter.js

@@ -0,0 +1,288 @@
+import { ConversationRoleTypes, } from "../generated/graphql-types.js";
+import { ChunkBuffer } from "./chunk-buffer.js";
+/**
+ * Adapter that transforms low-level streaming events into high-level UI events
+ * using GraphQL types for type safety
+ */
+export class UIEventAdapter {
+    onEvent;
+    conversationId;
+    model;
+    currentMessage = "";
+    isStreaming = false;
+    activeToolCalls = new Map();
+    lastUpdateTime = 0;
+    updateTimer;
+    showTokenStream;
+    chunkBuffer;
+    smoothingDelay = 30;
+    chunkQueue = []; // Queue of chunks waiting to be emitted
+    constructor(onEvent, conversationId, options = {}) {
+        this.onEvent = onEvent;
+        this.conversationId = conversationId;
+        this.showTokenStream = options.showTokenStream ?? true;
+        this.smoothingDelay = options.smoothingDelay ?? 30;
+        if (options.smoothingEnabled) {
+            this.chunkBuffer = new ChunkBuffer(options.chunkingStrategy || "word");
+        }
+    }
+    /**
+     * Process a raw streaming event and emit appropriate UI events
+     */
+    handleEvent(event) {
+        switch (event.type) {
+            case "start":
+                this.handleStart(event.conversationId);
+                break;
+            case "token":
+                if (this.showTokenStream) {
+                    this.handleToken(event.token);
+                }
+                break;
+            case "message":
+                this.handleMessage(event.message);
+                break;
+            case "tool_call_start":
+                this.handleToolCallStart(event.toolCall);
+                break;
+            case "tool_call_delta":
+                this.handleToolCallDelta(event.toolCallId, event.argumentDelta);
+                break;
+            case "tool_call_complete":
+                this.handleToolCallComplete(event.toolCall);
+                break;
+            case "complete":
+                this.handleComplete();
+                break;
+            case "error":
+                this.handleError(event.error);
+                break;
+        }
+    }
+    /**
+     * Set tool execution result directly (for tool handlers)
+     */
+    setToolResult(toolCallId, result, error) {
+        const toolData = this.activeToolCalls.get(toolCallId);
+        if (toolData) {
+            if (error) {
+                toolData.status = "failed";
+                this.emitUIEvent({
+                    type: "tool_update",
+                    toolCall: toolData.toolCall,
+                    status: "failed",
+                    error,
+                });
+            }
+            else {
+                toolData.status = "completed";
+                this.emitUIEvent({
+                    type: "tool_update",
+                    toolCall: toolData.toolCall,
+                    status: "completed",
+                    result,
+                });
+            }
+        }
+    }
+    handleStart(conversationId) {
+        this.conversationId = conversationId;
+        this.isStreaming = true;
+        this.emitUIEvent({
+            type: "conversation_started",
+            conversationId,
+            timestamp: new Date(),
+            model: this.model,
+        });
+    }
+    handleToken(token) {
+        if (this.chunkBuffer) {
+            const chunks = this.chunkBuffer.addToken(token);
+            // Add chunks to queue for all chunking modes (character, word, sentence)
+            this.chunkQueue.push(...chunks);
+            this.scheduleChunkEmission();
+        }
+        else {
+            // No chunking - emit tokens directly
+            this.currentMessage += token;
+            this.scheduleMessageUpdate();
+        }
+    }
+    handleMessage(message) {
+        this.currentMessage = message;
+        this.emitMessageUpdate(false);
+    }
+    handleToolCallStart(toolCall) {
+        const conversationToolCall = {
+            __typename: "ConversationToolCall",
+            id: toolCall.id,
+            name: toolCall.name,
+            arguments: "",
+        };
+        this.activeToolCalls.set(toolCall.id, {
+            toolCall: conversationToolCall,
+            status: "preparing",
+        });
+        this.emitUIEvent({
+            type: "tool_update",
+            toolCall: conversationToolCall,
+            status: "preparing",
+        });
+    }
+    handleToolCallDelta(toolCallId, argumentDelta) {
+        const toolData = this.activeToolCalls.get(toolCallId);
+        if (toolData && toolData.status === "preparing") {
+            toolData.toolCall.arguments += argumentDelta;
+            toolData.status = "executing";
+            this.emitUIEvent({
+                type: "tool_update",
+                toolCall: toolData.toolCall,
+                status: "executing",
+            });
+        }
+    }
+    handleToolCallComplete(toolCall) {
+        const toolData = this.activeToolCalls.get(toolCall.id);
+        if (toolData) {
+            toolData.toolCall.arguments = toolCall.arguments;
+            toolData.status = "completed";
+            this.emitUIEvent({
+                type: "tool_update",
+                toolCall: toolData.toolCall,
+                status: "completed",
+            });
+        }
+    }
+    handleComplete() {
+        // Flush any remaining chunks from buffer
+        if (this.chunkBuffer) {
+            const remaining = this.chunkBuffer.flush();
+            this.chunkQueue.push(...remaining);
+        }
+        // Clear any pending updates
+        if (this.updateTimer) {
+            globalThis.clearTimeout(this.updateTimer);
+            this.updateTimer = undefined;
+        }
+        // Immediately flush all queued chunks
+        while (this.chunkQueue.length > 0) {
+            const chunk = this.chunkQueue.shift();
+            this.currentMessage += chunk;
+        }
+        this.isStreaming = false;
+        // Create final message
+        const finalMessage = {
+            __typename: "ConversationMessage",
+            role: ConversationRoleTypes.Assistant,
+            message: this.currentMessage,
+            timestamp: new Date().toISOString(),
+            tokens: undefined, // Will be set by caller if available
+            toolCalls: Array.from(this.activeToolCalls.values()).map((t) => t.toolCall),
+        };
+        this.emitUIEvent({
+            type: "conversation_completed",
+            message: finalMessage,
+        });
+    }
+    handleError(error) {
+        this.isStreaming = false;
+        this.emitUIEvent({
+            type: "error",
+            error: {
+                message: error,
+                recoverable: false,
+            },
+            conversationId: this.conversationId,
+            timestamp: new Date(),
+        });
+    }
+    scheduleMessageUpdate() {
+        const now = Date.now();
+        const timeSinceLastUpdate = now - this.lastUpdateTime;
+        // If enough time has passed, update immediately
+        if (timeSinceLastUpdate >= this.smoothingDelay) {
+            this.emitMessageUpdate(true);
+            return;
+        }
+        // Otherwise, schedule an update
+        if (!this.updateTimer) {
+            const delay = this.smoothingDelay - timeSinceLastUpdate;
+            this.updateTimer = globalThis.setTimeout(() => {
+                this.emitMessageUpdate(true);
+            }, delay);
+        }
+    }
+    scheduleChunkEmission() {
+        // If timer is already running, let it handle the queue
+        if (this.updateTimer) {
+            return;
+        }
+        // If queue is empty, nothing to do
+        if (this.chunkQueue.length === 0) {
+            return;
+        }
+        const now = Date.now();
+        const timeSinceLastUpdate = now - this.lastUpdateTime;
+        // If enough time has passed, emit a chunk immediately
+        if (timeSinceLastUpdate >= this.smoothingDelay) {
+            this.emitNextChunk();
+            return;
+        }
+        // Otherwise, schedule the next chunk emission
+        const delay = this.smoothingDelay - timeSinceLastUpdate;
+        this.updateTimer = globalThis.setTimeout(() => {
+            this.emitNextChunk();
+        }, delay);
+    }
+    emitNextChunk() {
+        if (this.chunkQueue.length === 0) {
+            this.updateTimer = undefined;
+            return;
+        }
+        // Take one chunk from the queue
+        const chunk = this.chunkQueue.shift();
+        this.currentMessage += chunk;
+        // Emit the update
+        this.emitMessageUpdate(true);
+        // Schedule next chunk if queue is not empty
+        if (this.chunkQueue.length > 0) {
+            this.updateTimer = globalThis.setTimeout(() => {
+                this.emitNextChunk();
+            }, this.smoothingDelay);
+        }
+        else {
+            this.updateTimer = undefined;
+        }
+    }
+    emitMessageUpdate(isStreaming) {
+        this.lastUpdateTime = Date.now();
+        if (this.updateTimer) {
+            globalThis.clearTimeout(this.updateTimer);
+            this.updateTimer = undefined;
+        }
+        const message = {
+            __typename: "ConversationMessage",
+            role: ConversationRoleTypes.Assistant,
+            message: this.currentMessage,
+            timestamp: new Date().toISOString(),
+        };
+        this.emitUIEvent({
+            type: "message_update",
+            message,
+            isStreaming,
+        });
+    }
+    emitUIEvent(event) {
+        this.onEvent(event);
+    }
+    /**
+     * Clean up any pending timers
+     */
+    dispose() {
+        if (this.updateTimer) {
+            globalThis.clearTimeout(this.updateTimer);
+            this.updateTimer = undefined;
+        }
+        this.activeToolCalls.clear();
+    }
+}

package/dist/types/agent.d.ts

@@ -0,0 +1,39 @@
+export type ToolHandler = (args: any) => Promise<any>;
+export interface AgentOptions {
+    maxToolRounds?: number;
+    timeout?: number;
+}
+export interface AgentResult {
+    message: string;
+    conversationId: string;
+    error?: AgentError;
+}
+export interface StreamAgentOptions {
+    maxToolRounds?: number;
+    abortSignal?: AbortSignal;
+    showTokenStream?: boolean;
+    smoothingEnabled?: boolean;
+    chunkingStrategy?: 'character' | 'word' | 'sentence';
+    smoothingDelay?: number;
+}
+export interface ToolCallResult {
+    id: string;
+    name: string;
+    arguments: any;
+    result?: any;
+    error?: string;
+    duration?: number;
+}
+export interface UsageInfo {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cost?: number;
+    model?: string;
+}
+export interface AgentError {
+    message: string;
+    code?: string;
+    recoverable: boolean;
+    details?: any;
+}

package/dist/types/agent.js

@@ -0,0 +1 @@
+export {};

package/dist/types/streaming.d.ts

@@ -0,0 +1,58 @@
+export declare enum SmoothChunkingStrategy {
+    Word = "word",
+    Sentence = "sentence",
+    Character = "char"
+}
+export interface SmoothStreamOptions {
+    /** Enable smooth streaming. Set to false to get raw tokens. Default: true */
+    enabled?: boolean;
+    /** Delay between chunk emissions in milliseconds. Default varies by provider */
+    delay?: number;
+    /** How to break up content into chunks */
+    chunking?: SmoothChunkingStrategy | RegExp | ((buffer: string) => string | null);
+}
+/**
+ * Configuration options for UI streaming mode
+ */
+export interface StreamOptions {
+    /**
+     * Enable UI-focused streaming mode
+     * @default true (simplified events for better DX)
+     */
+    enabled?: boolean;
+    /**
+     * Whether to show real-time token streaming in the UI
+     * @default true
+     */
+    showTokenStream?: boolean;
+    /**
+     * Minimum interval between message updates (in milliseconds)
+     * Helps prevent UI flicker with very fast token streams
+     * @default 30
+     */
+    updateInterval?: number;
+    /**
+     * Whether to include token usage information in metadata
+     * @default false
+     */
+    includeUsage?: boolean;
+    /**
+     * Custom tool descriptions for better UI display
+     * Maps tool names to human-readable descriptions
+     */
+    toolDescriptions?: Record<string, string>;
+    /**
+     * Whether to automatically retry on recoverable errors
+     * @default true
+     */
+    autoRetry?: boolean;
+    /**
+     * Maximum number of retry attempts
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Smooth streaming options
+     */
+    smooth?: SmoothStreamOptions;
+}

package/dist/types/streaming.js

@@ -0,0 +1,7 @@
+// Smooth streaming configuration
+export var SmoothChunkingStrategy;
+(function (SmoothChunkingStrategy) {
+    SmoothChunkingStrategy["Word"] = "word";
+    SmoothChunkingStrategy["Sentence"] = "sentence";
+    SmoothChunkingStrategy["Character"] = "char";
+})(SmoothChunkingStrategy || (SmoothChunkingStrategy = {}));

package/dist/types/ui-events.d.ts

@@ -0,0 +1,38 @@
+import { ConversationMessage, ConversationToolCall } from "../generated/graphql-types.js";
+/**
+ * Tool execution status for streaming
+ */
+export type ToolExecutionStatus = "preparing" | "executing" | "completed" | "failed";
+/**
+ * Simplified UI-focused streaming events using GraphQL types
+ */
+export type AgentStreamEvent = {
+    type: "conversation_started";
+    conversationId: string;
+    timestamp: Date;
+    model?: string;
+} | {
+    type: "message_update";
+    message: Partial<ConversationMessage> & {
+        message: string;
+    };
+    isStreaming: boolean;
+} | {
+    type: "tool_update";
+    toolCall: ConversationToolCall;
+    status: ToolExecutionStatus;
+    result?: unknown;
+    error?: string;
+} | {
+    type: "conversation_completed";
+    message: ConversationMessage;
+} | {
+    type: "error";
+    error: {
+        message: string;
+        code?: string;
+        recoverable?: boolean;
+    };
+    conversationId: string;
+    timestamp: Date;
+};

package/dist/types/ui-events.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "graphlit-client",
-  "version": "1.0.20250531004",
-  "description": "Graphlit API TypeScript Client",
+  "version": "1.0.20250610001",
+  "description": "Graphlit API Client for TypeScript",
   "main": "dist/client.js",
   "types": "dist/client.d.ts",
   "repository": {
@@ -16,7 +16,13 @@
   },
   "scripts": {
     "generate": "graphql-codegen --config codegen.yml",
-    "build": "tsc -p tsconfig.json"
+    "format": "prettier --write .",
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:coverage": "vitest --coverage",
+    "test:ui": "vitest --ui",
+    "test:streaming": "vitest --run src/tests/streaming"
   },
   "keywords": [
     "Graphlit",
@@ -37,11 +43,32 @@
     "@graphql-codegen/typescript": "^4.1.6",
     "@graphql-codegen/typescript-operations": "^4.6.0",
     "graphql": "^16.10.0",
-    "jsonwebtoken": "^9.0.2"
+    "jsonwebtoken": "^9.0.2",
+    "prettier": "^3.5.3"
+  },
+  "peerDependenciesMeta": {
+    "openai": {
+      "optional": true
+    },
+    "@anthropic-ai/sdk": {
+      "optional": true
+    },
+    "@google/generative-ai": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@graphql-codegen/typescript-document-nodes": "^4.0.16",
     "@types/jsonwebtoken": "^9.0.9",
-    "typescript": "^5.8.2"
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^1.0.0",
+    "dotenv": "^16.5.0",
+    "typescript": "^5.8.2",
+    "vitest": "^1.0.0"
+  },
+  "optionalDependencies": {
+    "@anthropic-ai/sdk": "^0.53.0",
+    "@google/generative-ai": "^0.24.1",
+    "openai": "^5.2.0"
   }
 }