@protoboxai/sdk 1.0.0

package/dist/errors/index.js

@@ -0,0 +1,319 @@
+"use strict";
+/**
+ * Custom Error Classes for @chanl/sdk
+ *
+ * TDD Phase: RED - These errors define the error handling contract
+ *
+ * Design Principles:
+ * - Error transparency: Include code, message, and context for debugging
+ * - HTTP status awareness: Map API response codes to specific error types
+ * - Serializable details: Allow JSON serialization for logging
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeoutError = exports.NetworkError = exports.ServerError = exports.RateLimitError = exports.ConflictError = exports.AuthorizationError = exports.AuthenticationError = exports.ValidationError = exports.NotFoundError = exports.ChanlError = void 0;
+exports.isChanlError = isChanlError;
+exports.isNotFoundError = isNotFoundError;
+exports.isValidationError = isValidationError;
+exports.isAuthenticationError = isAuthenticationError;
+exports.createErrorFromResponse = createErrorFromResponse;
+/**
+ * Base error class for all Chanl SDK errors
+ */
+class ChanlError extends Error {
+    constructor(message, options = {}) {
+        super(message);
+        this.name = 'ChanlError';
+        this.code = options.code ?? 'CHANL_ERROR';
+        // Only assign optional properties when defined (exactOptionalPropertyTypes)
+        if (options.statusCode !== undefined) {
+            this.statusCode = options.statusCode;
+        }
+        if (options.details !== undefined) {
+            this.details = options.details;
+        }
+        if (options.cause !== undefined) {
+            this.cause = options.cause;
+        }
+        if (options.requestId !== undefined) {
+            this.requestId = options.requestId;
+        }
+        // Maintains proper stack trace in V8 environments
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Convert error to JSON for logging/serialization
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            statusCode: this.statusCode,
+            details: this.details,
+            requestId: this.requestId,
+            stack: this.stack,
+        };
+    }
+}
+exports.ChanlError = ChanlError;
+/**
+ * Error thrown when a requested resource is not found (404)
+ */
+class NotFoundError extends ChanlError {
+    constructor(resourceType, resourceId, options = {}) {
+        const details = {
+            resourceType,
+            resourceId,
+            ...options.details,
+        };
+        super(`${resourceType} with ID '${resourceId}' not found`, {
+            code: 'NOT_FOUND',
+            statusCode: 404,
+            details,
+            requestId: options.requestId,
+        });
+        this.name = 'NotFoundError';
+        this.resourceType = resourceType;
+        this.resourceId = resourceId;
+    }
+}
+exports.NotFoundError = NotFoundError;
+/**
+ * Error thrown when input validation fails (400)
+ */
+class ValidationError extends ChanlError {
+    constructor(message, options = {}) {
+        const details = {
+            ...options.details,
+        };
+        if (options.fieldErrors !== undefined) {
+            details['fieldErrors'] = options.fieldErrors;
+        }
+        super(message, {
+            code: 'VALIDATION_ERROR',
+            statusCode: 400,
+            details,
+            requestId: options.requestId,
+        });
+        this.name = 'ValidationError';
+        if (options.fieldErrors !== undefined) {
+            this.fieldErrors = options.fieldErrors;
+        }
+    }
+    /**
+     * Get validation errors for a specific field
+     */
+    getFieldErrors(field) {
+        return this.fieldErrors?.[field] ?? [];
+    }
+    /**
+     * Check if a specific field has validation errors
+     */
+    hasFieldError(field) {
+        return (this.fieldErrors?.[field]?.length ?? 0) > 0;
+    }
+}
+exports.ValidationError = ValidationError;
+/**
+ * Error thrown when authentication fails (401)
+ */
+class AuthenticationError extends ChanlError {
+    constructor(message = 'Authentication required', options = {}) {
+        super(message, {
+            code: 'AUTHENTICATION_ERROR',
+            statusCode: 401,
+            details: options.details,
+            requestId: options.requestId,
+        });
+        this.name = 'AuthenticationError';
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+/**
+ * Error thrown when authorization fails (403)
+ */
+class AuthorizationError extends ChanlError {
+    constructor(message = 'Permission denied', options = {}) {
+        const details = {
+            ...options.details,
+        };
+        if (options.action !== undefined) {
+            details['action'] = options.action;
+        }
+        if (options.resource !== undefined) {
+            details['resource'] = options.resource;
+        }
+        super(message, {
+            code: 'AUTHORIZATION_ERROR',
+            statusCode: 403,
+            details,
+            requestId: options.requestId,
+        });
+        this.name = 'AuthorizationError';
+        if (options.action !== undefined) {
+            this.action = options.action;
+        }
+        if (options.resource !== undefined) {
+            this.resource = options.resource;
+        }
+    }
+}
+exports.AuthorizationError = AuthorizationError;
+/**
+ * Error thrown when there's a conflict (409)
+ */
+class ConflictError extends ChanlError {
+    constructor(message, options = {}) {
+        const details = {
+            ...options.details,
+        };
+        if (options.conflictingResource !== undefined) {
+            details['conflictingResource'] = options.conflictingResource;
+        }
+        super(message, {
+            code: 'CONFLICT_ERROR',
+            statusCode: 409,
+            details,
+            requestId: options.requestId,
+        });
+        this.name = 'ConflictError';
+        if (options.conflictingResource !== undefined) {
+            this.conflictingResource = options.conflictingResource;
+        }
+    }
+}
+exports.ConflictError = ConflictError;
+/**
+ * Error thrown when rate limit is exceeded (429)
+ */
+class RateLimitError extends ChanlError {
+    constructor(message = 'Rate limit exceeded', options = {}) {
+        const details = {
+            ...options.details,
+        };
+        if (options.retryAfter !== undefined) {
+            details['retryAfter'] = options.retryAfter;
+        }
+        super(message, {
+            code: 'RATE_LIMIT_ERROR',
+            statusCode: 429,
+            details,
+            requestId: options.requestId,
+        });
+        this.name = 'RateLimitError';
+        if (options.retryAfter !== undefined) {
+            this.retryAfter = options.retryAfter;
+        }
+    }
+}
+exports.RateLimitError = RateLimitError;
+/**
+ * Error thrown when API server fails (5xx)
+ */
+class ServerError extends ChanlError {
+    constructor(message = 'Internal server error', options = {}) {
+        super(message, {
+            code: 'SERVER_ERROR',
+            statusCode: options.statusCode ?? 500,
+            details: options.details,
+            requestId: options.requestId,
+        });
+        this.name = 'ServerError';
+    }
+}
+exports.ServerError = ServerError;
+/**
+ * Error thrown for network/connection issues
+ */
+class NetworkError extends ChanlError {
+    constructor(message = 'Network error', options = {}) {
+        super(message, {
+            code: 'NETWORK_ERROR',
+            cause: options.cause,
+            details: options.details,
+        });
+        this.name = 'NetworkError';
+    }
+}
+exports.NetworkError = NetworkError;
+/**
+ * Error thrown when request times out
+ */
+class TimeoutError extends ChanlError {
+    constructor(message = 'Request timeout', options = {}) {
+        const details = {
+            ...options.details,
+        };
+        if (options.timeoutMs !== undefined) {
+            details['timeoutMs'] = options.timeoutMs;
+        }
+        super(message, {
+            code: 'TIMEOUT_ERROR',
+            details,
+            requestId: options.requestId,
+        });
+        this.name = 'TimeoutError';
+        if (options.timeoutMs !== undefined) {
+            this.timeoutMs = options.timeoutMs;
+        }
+    }
+}
+exports.TimeoutError = TimeoutError;
+/**
+ * Type guard to check if error is a ChanlError
+ */
+function isChanlError(error) {
+    return error instanceof ChanlError;
+}
+/**
+ * Type guard to check if error is a NotFoundError
+ */
+function isNotFoundError(error) {
+    return error instanceof NotFoundError;
+}
+/**
+ * Type guard to check if error is a ValidationError
+ */
+function isValidationError(error) {
+    return error instanceof ValidationError;
+}
+/**
+ * Type guard to check if error is an AuthenticationError
+ */
+function isAuthenticationError(error) {
+    return error instanceof AuthenticationError;
+}
+/**
+ * Factory function to create appropriate error from API response
+ */
+function createErrorFromResponse(statusCode, message, options = {}) {
+    switch (statusCode) {
+        case 400:
+            return new ValidationError(message, options);
+        case 401:
+            return new AuthenticationError(message, options);
+        case 403:
+            return new AuthorizationError(message, options);
+        case 404:
+            // For 404, we need resourceType and resourceId which aren't in options
+            // Return a generic ChanlError instead
+            return new ChanlError(message, {
+                code: 'NOT_FOUND',
+                statusCode: 404,
+                details: options.details,
+                requestId: options.requestId,
+            });
+        case 409:
+            return new ConflictError(message, options);
+        case 429:
+            return new RateLimitError(message, options);
+        default:
+            if (statusCode >= 500) {
+                return new ServerError(message, { statusCode, ...options });
+            }
+            return new ChanlError(message, { statusCode, ...options });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export { ChanlSDK, ChanlSDK as Chanl, ChanlSDK as ProtoboxSDK, ChanlSDK as Protobox } from './client';
+export { ChanlConfig, ChanlAuthConfig } from './types/config';
+export { WorkspaceModule } from './modules/workspace';
+export { AuthModule } from './modules/auth';
+export { HealthModule } from './modules/health';
+export { PromptsModule } from './modules/prompts';
+export { ToolsModule } from './modules/tools';
+export { ToolsetsModule } from './modules/toolsets';
+export { McpModule } from './modules/mcp';
+export { KnowledgeModule } from './modules/knowledge';
+export { ChatModule } from './modules/chat';
+export * from './types/api';
+export * from './modules/prompts';
+export * from './types/tools';
+export * from './types/tool-calls';
+export * from './types/toolsets';
+export * from './modules/mcp';
+export * from './modules/knowledge';
+export * from './modules/chat';
+export * from './live';
+export * from './errors';
+export * from './adapters/openai';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,62 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatModule = exports.KnowledgeModule = exports.McpModule = exports.ToolsetsModule = exports.ToolsModule = exports.PromptsModule = exports.HealthModule = exports.AuthModule = exports.WorkspaceModule = exports.Protobox = exports.ProtoboxSDK = exports.Chanl = exports.ChanlSDK = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "ChanlSDK", { enumerable: true, get: function () { return client_1.ChanlSDK; } });
+Object.defineProperty(exports, "Chanl", { enumerable: true, get: function () { return client_1.ChanlSDK; } });
+Object.defineProperty(exports, "ProtoboxSDK", { enumerable: true, get: function () { return client_1.ChanlSDK; } });
+Object.defineProperty(exports, "Protobox", { enumerable: true, get: function () { return client_1.ChanlSDK; } });
+var workspace_1 = require("./modules/workspace");
+Object.defineProperty(exports, "WorkspaceModule", { enumerable: true, get: function () { return workspace_1.WorkspaceModule; } });
+var auth_1 = require("./modules/auth");
+Object.defineProperty(exports, "AuthModule", { enumerable: true, get: function () { return auth_1.AuthModule; } });
+var health_1 = require("./modules/health");
+Object.defineProperty(exports, "HealthModule", { enumerable: true, get: function () { return health_1.HealthModule; } });
+var prompts_1 = require("./modules/prompts");
+Object.defineProperty(exports, "PromptsModule", { enumerable: true, get: function () { return prompts_1.PromptsModule; } });
+var tools_1 = require("./modules/tools");
+Object.defineProperty(exports, "ToolsModule", { enumerable: true, get: function () { return tools_1.ToolsModule; } });
+var toolsets_1 = require("./modules/toolsets");
+Object.defineProperty(exports, "ToolsetsModule", { enumerable: true, get: function () { return toolsets_1.ToolsetsModule; } });
+var mcp_1 = require("./modules/mcp");
+Object.defineProperty(exports, "McpModule", { enumerable: true, get: function () { return mcp_1.McpModule; } });
+var knowledge_1 = require("./modules/knowledge");
+Object.defineProperty(exports, "KnowledgeModule", { enumerable: true, get: function () { return knowledge_1.KnowledgeModule; } });
+var chat_1 = require("./modules/chat");
+Object.defineProperty(exports, "ChatModule", { enumerable: true, get: function () { return chat_1.ChatModule; } });
+// Re-export all types from modules
+__exportStar(require("./types/api"), exports);
+__exportStar(require("./modules/prompts"), exports);
+// Export tool types
+__exportStar(require("./types/tools"), exports);
+// Export tool call types (shared across chat)
+__exportStar(require("./types/tool-calls"), exports);
+// Export toolset types
+__exportStar(require("./types/toolsets"), exports);
+// Export MCP types
+__exportStar(require("./modules/mcp"), exports);
+// Export Knowledge types
+__exportStar(require("./modules/knowledge"), exports);
+// Export Chat types
+__exportStar(require("./modules/chat"), exports);
+// Export live monitoring classes
+__exportStar(require("./live"), exports);
+// Export error classes
+__exportStar(require("./errors"), exports);
+// Export OpenAI adapter
+__exportStar(require("./adapters/openai"), exports);
+//# sourceMappingURL=index.js.map

package/dist/live/index.d.ts

@@ -0,0 +1,5 @@
+export { TypedEventEmitter } from './typed-emitter';
+export type { LiveOptions } from './types';
+export { LiveChat } from './live-chat';
+export type { LiveChatEvents, LiveChatSendOptions } from './live-chat';
+//# sourceMappingURL=index.d.ts.map

package/dist/live/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveChat = exports.TypedEventEmitter = void 0;
+// Base
+var typed_emitter_1 = require("./typed-emitter");
+Object.defineProperty(exports, "TypedEventEmitter", { enumerable: true, get: function () { return typed_emitter_1.TypedEventEmitter; } });
+// LiveChat
+var live_chat_1 = require("./live-chat");
+Object.defineProperty(exports, "LiveChat", { enumerable: true, get: function () { return live_chat_1.LiveChat; } });
+//# sourceMappingURL=index.js.map

package/dist/live/live-chat.d.ts

@@ -0,0 +1,71 @@
+import { TypedEventEmitter } from './typed-emitter';
+import type { ChanlSDK } from '../client';
+import type { ChatSessionResponse, ChatMessageResponse } from '../modules/chat';
+export type LiveChatEvents = {
+    'message': (message: ChatMessageResponse) => void;
+    'delta': (text: string) => void;
+    'ended': () => void;
+    'error': (error: Error) => void;
+};
+export interface LiveChatSendOptions {
+    /** Enable streaming — text arrives via `delta` events / `onChunk` callback */
+    stream?: boolean;
+    /** Per-message callback for streaming text chunks */
+    onChunk?: (delta: string) => void;
+}
+/**
+ * Live chat session wrapper.
+ *
+ * Wraps an active chat session, emitting typed events for messages and
+ * session lifecycle. Unlike LiveCall/LiveExecution, this is not polling-based —
+ * events fire in response to explicit `send()` and `end()` calls.
+ *
+ * @example Non-streaming
+ * ```typescript
+ * const chat = await sdk.chat.session(wsId, agentId);
+ * const reply = await chat.send('Hello!');
+ * console.log(reply.message);
+ * await chat.end();
+ * ```
+ *
+ * @example Streaming with event listener
+ * ```typescript
+ * const chat = await sdk.chat.session(wsId, agentId);
+ * chat.on('delta', (text) => process.stdout.write(text));
+ * const reply = await chat.send('Hello!', { stream: true });
+ * await chat.end();
+ * ```
+ *
+ * @example Streaming with callback
+ * ```typescript
+ * const chat = await sdk.chat.session(wsId, agentId);
+ * const reply = await chat.send('Hello!', {
+ *   stream: true,
+ *   onChunk: (delta) => process.stdout.write(delta),
+ * });
+ * await chat.end();
+ * ```
+ */
+export declare class LiveChat extends TypedEventEmitter<LiveChatEvents> {
+    private sdk;
+    readonly sessionId: string;
+    readonly agentName: string | undefined;
+    constructor(sdk: ChanlSDK, sessionData: ChatSessionResponse);
+    /**
+     * Send a message and receive the agent's response.
+     *
+     * With `{ stream: true }`, text arrives incrementally via the `delta`
+     * event and optional `onChunk` callback. The returned promise resolves
+     * with the complete response after the stream finishes.
+     *
+     * Without streaming (default), waits for the full response including
+     * tool calls and usage metadata.
+     */
+    send(text: string, options?: LiveChatSendOptions): Promise<ChatMessageResponse>;
+    /**
+     * End the chat session. Emits an `ended` event.
+     */
+    end(): Promise<void>;
+    private sendStreaming;
+}
+//# sourceMappingURL=live-chat.d.ts.map

package/dist/live/live-chat.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveChat = void 0;
+const typed_emitter_1 = require("./typed-emitter");
+/**
+ * Live chat session wrapper.
+ *
+ * Wraps an active chat session, emitting typed events for messages and
+ * session lifecycle. Unlike LiveCall/LiveExecution, this is not polling-based —
+ * events fire in response to explicit `send()` and `end()` calls.
+ *
+ * @example Non-streaming
+ * ```typescript
+ * const chat = await sdk.chat.session(wsId, agentId);
+ * const reply = await chat.send('Hello!');
+ * console.log(reply.message);
+ * await chat.end();
+ * ```
+ *
+ * @example Streaming with event listener
+ * ```typescript
+ * const chat = await sdk.chat.session(wsId, agentId);
+ * chat.on('delta', (text) => process.stdout.write(text));
+ * const reply = await chat.send('Hello!', { stream: true });
+ * await chat.end();
+ * ```
+ *
+ * @example Streaming with callback
+ * ```typescript
+ * const chat = await sdk.chat.session(wsId, agentId);
+ * const reply = await chat.send('Hello!', {
+ *   stream: true,
+ *   onChunk: (delta) => process.stdout.write(delta),
+ * });
+ * await chat.end();
+ * ```
+ */
+class LiveChat extends typed_emitter_1.TypedEventEmitter {
+    constructor(sdk, sessionData) {
+        super();
+        this.sdk = sdk;
+        this.sessionId = sessionData.interactionId || sessionData.sessionId;
+        this.agentName = sessionData.agentName;
+    }
+    /**
+     * Send a message and receive the agent's response.
+     *
+     * With `{ stream: true }`, text arrives incrementally via the `delta`
+     * event and optional `onChunk` callback. The returned promise resolves
+     * with the complete response after the stream finishes.
+     *
+     * Without streaming (default), waits for the full response including
+     * tool calls and usage metadata.
+     */
+    async send(text, options) {
+        if (options?.stream) {
+            return this.sendStreaming(text, options);
+        }
+        const response = await this.sdk.chat.sendMessage(this.sessionId, text);
+        if (!response.success || !response.data) {
+            const error = new Error(response.message || 'Failed to send message');
+            this.emit('error', error);
+            throw error;
+        }
+        this.emit('message', response.data);
+        return response.data;
+    }
+    /**
+     * End the chat session. Emits an `ended` event.
+     */
+    async end() {
+        try {
+            await this.sdk.chat.endSession(this.sessionId);
+        }
+        catch {
+            // Best-effort cleanup
+        }
+        this.emit('ended');
+    }
+    async sendStreaming(text, options) {
+        const response = await this.sdk.chat.streamMessage(this.sessionId, text, (delta) => {
+            this.emit('delta', delta);
+            options.onChunk?.(delta);
+        });
+        if (!response.success || !response.data) {
+            const error = new Error(response.message || 'Failed to send message');
+            this.emit('error', error);
+            throw error;
+        }
+        this.emit('message', response.data);
+        return response.data;
+    }
+}
+exports.LiveChat = LiveChat;
+//# sourceMappingURL=live-chat.js.map

package/dist/live/typed-emitter.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Type-safe EventEmitter wrapper.
+ *
+ * Uses composition (not inheritance) so `.emit()` stays protected —
+ * only subclasses can fire events, consumers can only subscribe.
+ */
+export declare class TypedEventEmitter<TEvents extends Record<string, (...args: any[]) => void>> {
+    private emitter;
+    on<K extends keyof TEvents & string>(event: K, listener: TEvents[K]): this;
+    once<K extends keyof TEvents & string>(event: K, listener: TEvents[K]): this;
+    off<K extends keyof TEvents & string>(event: K, listener: TEvents[K]): this;
+    protected emit<K extends keyof TEvents & string>(event: K, ...args: Parameters<TEvents[K]>): boolean;
+    removeAllListeners(): this;
+}
+//# sourceMappingURL=typed-emitter.d.ts.map

package/dist/live/typed-emitter.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypedEventEmitter = void 0;
+const events_1 = require("events");
+/**
+ * Type-safe EventEmitter wrapper.
+ *
+ * Uses composition (not inheritance) so `.emit()` stays protected —
+ * only subclasses can fire events, consumers can only subscribe.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+class TypedEventEmitter {
+    constructor() {
+        this.emitter = new events_1.EventEmitter();
+    }
+    on(event, listener) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.emitter.on(event, listener);
+        return this;
+    }
+    once(event, listener) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.emitter.once(event, listener);
+        return this;
+    }
+    off(event, listener) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.emitter.off(event, listener);
+        return this;
+    }
+    emit(event, ...args) {
+        return this.emitter.emit(event, ...args);
+    }
+    removeAllListeners() {
+        this.emitter.removeAllListeners();
+        return this;
+    }
+}
+exports.TypedEventEmitter = TypedEventEmitter;
+//# sourceMappingURL=typed-emitter.js.map

package/dist/live/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared types for live monitoring classes
+ */
+/**
+ * A single transcript segment from a call or voice scenario
+ */
+export interface TranscriptSegment {
+    speaker: string;
+    text: string;
+    start: number;
+    end: number;
+}
+/**
+ * Options for live monitoring (polling-based)
+ */
+export interface LiveOptions {
+    /** Poll interval in ms (default: 2000) */
+    pollInterval?: number;
+    /** Max polls before timeout (default: 150 = 5 min) */
+    maxPolls?: number;
+    /** External AbortSignal for cancellation */
+    signal?: AbortSignal;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/live/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Shared types for live monitoring classes
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map