@protoboxai/sdk 1.0.0

package/dist/client.js

@@ -0,0 +1,307 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChanlSDK = void 0;
+const workspace_1 = require("./modules/workspace");
+const auth_1 = require("./modules/auth");
+const health_1 = require("./modules/health");
+const prompts_1 = require("./modules/prompts");
+const tools_1 = require("./modules/tools");
+const toolsets_1 = require("./modules/toolsets");
+const mcp_1 = require("./modules/mcp");
+const knowledge_1 = require("./modules/knowledge");
+const chat_1 = require("./modules/chat");
+class ChanlSDK {
+    constructor(config) {
+        const server = config.server;
+        const baseUrl = config.baseUrl ||
+            (typeof server === 'string' && server.length > 0 ? server : '');
+        if (!baseUrl) {
+            throw new Error('ChanlSDK: baseUrl or server is required');
+        }
+        this.config = {
+            timeout: 30000,
+            debug: false,
+            retry: {
+                maxRetries: 3,
+                retryDelay: 1000,
+                backoffMultiplier: 2,
+            },
+            ...config,
+            baseUrl,
+        };
+        // Initialize modules
+        this.workspace = new workspace_1.WorkspaceModule(this);
+        this.auth = new auth_1.AuthModule(this);
+        this.health = new health_1.HealthModule(this);
+        this.prompts = new prompts_1.PromptsModule(this);
+        this.tools = new tools_1.ToolsModule(this);
+        this.toolsets = new toolsets_1.ToolsetsModule(this);
+        this.mcp = new mcp_1.McpModule(this);
+        this.knowledge = new knowledge_1.KnowledgeModule(this);
+        this.chat = new chat_1.ChatModule(this);
+    }
+    /**
+     * Make a request to the API
+     */
+    /**
+     * Rewrite `/api/v1/...` paths for local OSS servers (flat routes).
+     */
+    resolveRequestPath(path) {
+        const explicit = this.config.apiPrefix;
+        if (explicit !== undefined) {
+            const trimmed = explicit.replace(/^\/+|\/+$/g, '');
+            if (trimmed === '') {
+                if (path.startsWith('/api/v1/')) {
+                    return path.replace(/^\/api\/v1/, '') || '/';
+                }
+                return path;
+            }
+            if (path.startsWith('/api/v1/')) {
+                return `/${trimmed}${path.slice('/api/v1'.length)}`;
+            }
+            return path;
+        }
+        if (this.config.deployment === 'local' && path.startsWith('/api/v1/')) {
+            return path.replace(/^\/api\/v1/, '') || '/';
+        }
+        return path;
+    }
+    async request(method, url, data, config) {
+        // Check if data is FormData (Node.js form-data package or native FormData)
+        const isNodeFormData = data != null &&
+            typeof data
+                .getHeaders === "function";
+        const isNativeFormData = typeof FormData !== "undefined" && data instanceof FormData;
+        const isFormData = isNodeFormData || isNativeFormData;
+        const path = this.resolveRequestPath(url);
+        // Build full URL
+        const fullUrl = new URL(path, this.config.baseUrl).toString();
+        // Build headers
+        const headers = {
+            ...this.config.headers,
+            ...config?.headers,
+        };
+        // Set Content-Type for non-FormData requests (FormData sets its own boundary)
+        if (!isFormData && !headers["Content-Type"]) {
+            headers["Content-Type"] = "application/json";
+        }
+        // Remove Content-Type for FormData to let fetch/runtime set it with boundary
+        if (isFormData) {
+            delete headers["Content-Type"];
+        }
+        // Add authentication
+        if (this.config.apiKey) {
+            headers["X-API-Key"] = this.config.apiKey;
+        }
+        else if (this.config.jwtToken) {
+            headers["Authorization"] = `Bearer ${this.config.jwtToken}`;
+        }
+        // Add workspace context (flat local APIs do not use this header)
+        const skipWorkspaceHeader = this.config.deployment === "local" || this.config.apiPrefix === "";
+        if (this.config.workspaceId && !skipWorkspaceHeader) {
+            headers["x-workspace-id"] = this.config.workspaceId;
+        }
+        // Setup timeout via AbortController
+        const timeout = config?.timeout ?? this.config.timeout ?? 30000;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        // Build fetch options
+        const fetchOptions = {
+            method,
+            headers,
+            signal: controller.signal,
+        };
+        // Attach body if present
+        if (data != null) {
+            if (isFormData) {
+                // Pass FormData directly (works for both Node.js form-data and native FormData)
+                fetchOptions.body = data;
+            }
+            else {
+                fetchOptions.body = JSON.stringify(data);
+            }
+        }
+        try {
+            const response = await fetch(fullUrl, fetchOptions);
+            if (!response.ok) {
+                // Try to parse error body for a meaningful message
+                let errorMessage = "API Error";
+                try {
+                    const errorBody = (await response.json());
+                    errorMessage =
+                        errorBody.error?.message || errorBody.message || "API Error";
+                }
+                catch {
+                    // JSON parse failed, use status text
+                    errorMessage = response.statusText || "API Error";
+                }
+                throw new Error(errorMessage);
+            }
+            // Handle 204 No Content
+            if (response.status === 204) {
+                return {};
+            }
+            const json = await response.json();
+            const body = json;
+            // Normalize response shape to { success, data, message, timestamp }.
+            // API responses come in several shapes depending on the service/gateway:
+            //   1. { success, data, message, timestamp } — standard ResponseInterceptor
+            //   2. { data: { ... } }                    — partial wrapper (no success)
+            //   3. { agents, pagination }               — raw unwrapped
+            let normalized;
+            if (body['success'] !== undefined) {
+                // Case 1: fully wrapped
+                normalized = json;
+            }
+            else if (body['data'] !== undefined && Object.keys(body).length <= 3) {
+                // Case 2: has { data } wrapper but no success — add success
+                normalized = {
+                    success: true,
+                    data: body['data'],
+                    message: body['message'] || 'Success',
+                    timestamp: body['timestamp'] || new Date().toISOString(),
+                };
+            }
+            else {
+                // Case 3: raw unwrapped — wrap entire body as data
+                normalized = {
+                    success: true,
+                    data: json,
+                    message: 'Success',
+                    timestamp: new Date().toISOString(),
+                };
+            }
+            // Normalize _id → id in response data
+            if (normalized.data !== undefined) {
+                normalized.data = this.normalizeIds(normalized.data);
+            }
+            // Unwrap single-entity responses: { agent: {...} } → {...}
+            // API get-by-id endpoints return { entityName: { ...entity } }.
+            // Unwrap so consumers get the entity directly as `data`.
+            if (normalized.data !== null && typeof normalized.data === 'object' && !Array.isArray(normalized.data)) {
+                const dataObj = normalized.data;
+                const keys = Object.keys(dataObj);
+                const singleKey = keys.length === 1 ? keys[0] : undefined;
+                if (singleKey) {
+                    const value = dataObj[singleKey];
+                    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+                        normalized.data = value;
+                    }
+                }
+            }
+            return normalized;
+        }
+        catch (error) {
+            if (error instanceof DOMException && error.name === "AbortError") {
+                throw new Error(`Request timeout after ${timeout}ms`);
+            }
+            // Re-throw errors we already created above, or wrap unknown errors
+            if (error instanceof Error) {
+                throw error;
+            }
+            throw new Error("Network Error");
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Make a streaming request that returns the raw Response.
+     *
+     * Unlike `request()`, this does NOT parse JSON or apply timeout.
+     * The caller reads `response.body` via `getReader()`.
+     * Used for SSE / chunked-transfer endpoints (e.g., chat streaming).
+     */
+    async requestStream(method, url, data) {
+        const fullUrl = new URL(url, this.config.baseUrl).toString();
+        const headers = {
+            ...this.config.headers,
+            'Content-Type': 'application/json',
+            'Accept': 'text/event-stream',
+        };
+        if (this.config.apiKey) {
+            headers['X-API-Key'] = this.config.apiKey;
+        }
+        else if (this.config.jwtToken) {
+            headers['Authorization'] = `Bearer ${this.config.jwtToken}`;
+        }
+        if (this.config.workspaceId) {
+            headers['x-workspace-id'] = this.config.workspaceId;
+        }
+        const fetchOptions = {
+            method,
+            headers,
+        };
+        if (data != null) {
+            fetchOptions.body = JSON.stringify(data);
+        }
+        const response = await fetch(fullUrl, fetchOptions);
+        if (!response.ok) {
+            let errorMessage = 'API Error';
+            try {
+                const errorBody = (await response.json());
+                errorMessage =
+                    errorBody.error?.message || errorBody.message || 'API Error';
+            }
+            catch {
+                errorMessage = response.statusText || 'API Error';
+            }
+            throw new Error(errorMessage);
+        }
+        return response;
+    }
+    /**
+     * Recursively normalize _id → id in response data.
+     * Skips if id already exists to avoid overwriting.
+     */
+    normalizeIds(data) {
+        if (data === null || data === undefined || typeof data !== "object") {
+            return data;
+        }
+        if (Array.isArray(data)) {
+            return data.map((item) => this.normalizeIds(item));
+        }
+        const obj = data;
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            if (key === "_id" && !("id" in obj)) {
+                result["id"] = value;
+            }
+            else if (key === "_id" && "id" in obj) {
+                // Skip _id when id already exists
+                continue;
+            }
+            else {
+                result[key] = this.normalizeIds(value);
+            }
+        }
+        return result;
+    }
+    /**
+     * Update authentication credentials
+     */
+    updateAuth(authConfig) {
+        if (authConfig.apiKey) {
+            this.config.apiKey = authConfig.apiKey;
+            delete this.config.jwtToken;
+        }
+        else if (authConfig.jwtToken) {
+            this.config.jwtToken = authConfig.jwtToken;
+            delete this.config.apiKey;
+        }
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Enable/disable debug logging
+     */
+    setDebug(enabled) {
+        this.config.debug = enabled;
+    }
+}
+exports.ChanlSDK = ChanlSDK;
+//# sourceMappingURL=client.js.map

package/dist/errors/index.d.ts

@@ -0,0 +1,179 @@
+/**
+ * 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
+ */
+/**
+ * Options type for ChanlError constructor
+ * Uses explicit `| undefined` to be compatible with exactOptionalPropertyTypes
+ */
+interface ChanlErrorOptions {
+    code?: string | undefined;
+    statusCode?: number | undefined;
+    details?: Record<string, unknown> | undefined;
+    cause?: Error | undefined;
+    requestId?: string | undefined;
+}
+/**
+ * Base error class for all Chanl SDK errors
+ */
+export declare class ChanlError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: string;
+    /** HTTP status code if from API response */
+    readonly statusCode?: number;
+    /** Additional error details for debugging */
+    readonly details?: Record<string, unknown>;
+    /** Original error if wrapping another error */
+    readonly cause?: Error;
+    /** Request ID from API for tracing */
+    readonly requestId?: string;
+    constructor(message: string, options?: ChanlErrorOptions);
+    /**
+     * Convert error to JSON for logging/serialization
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown when a requested resource is not found (404)
+ */
+export declare class NotFoundError extends ChanlError {
+    /** The type of resource that was not found */
+    readonly resourceType: string;
+    /** The identifier that was used to look up the resource */
+    readonly resourceId: string;
+    constructor(resourceType: string, resourceId: string, options?: {
+        details?: Record<string, unknown> | undefined;
+        requestId?: string | undefined;
+    });
+}
+/**
+ * Error thrown when input validation fails (400)
+ */
+export declare class ValidationError extends ChanlError {
+    /** Field-level validation errors */
+    readonly fieldErrors?: Record<string, string[]>;
+    constructor(message: string, options?: {
+        fieldErrors?: Record<string, string[]> | undefined;
+        details?: Record<string, unknown> | undefined;
+        requestId?: string | undefined;
+    });
+    /**
+     * Get validation errors for a specific field
+     */
+    getFieldErrors(field: string): string[];
+    /**
+     * Check if a specific field has validation errors
+     */
+    hasFieldError(field: string): boolean;
+}
+/**
+ * Error thrown when authentication fails (401)
+ */
+export declare class AuthenticationError extends ChanlError {
+    constructor(message?: string, options?: {
+        details?: Record<string, unknown> | undefined;
+        requestId?: string | undefined;
+    });
+}
+/**
+ * Error thrown when authorization fails (403)
+ */
+export declare class AuthorizationError extends ChanlError {
+    /** The action that was attempted */
+    readonly action?: string;
+    /** The resource that was being accessed */
+    readonly resource?: string;
+    constructor(message?: string, options?: {
+        action?: string | undefined;
+        resource?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        requestId?: string | undefined;
+    });
+}
+/**
+ * Error thrown when there's a conflict (409)
+ */
+export declare class ConflictError extends ChanlError {
+    /** The conflicting resource identifier */
+    readonly conflictingResource?: string;
+    constructor(message: string, options?: {
+        conflictingResource?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        requestId?: string | undefined;
+    });
+}
+/**
+ * Error thrown when rate limit is exceeded (429)
+ */
+export declare class RateLimitError extends ChanlError {
+    /** When the rate limit resets (Unix timestamp) */
+    readonly retryAfter?: number;
+    constructor(message?: string, options?: {
+        retryAfter?: number | undefined;
+        details?: Record<string, unknown> | undefined;
+        requestId?: string | undefined;
+    });
+}
+/**
+ * Error thrown when API server fails (5xx)
+ */
+export declare class ServerError extends ChanlError {
+    constructor(message?: string, options?: {
+        statusCode?: number | undefined;
+        details?: Record<string, unknown> | undefined;
+        requestId?: string | undefined;
+    });
+}
+/**
+ * Error thrown for network/connection issues
+ */
+export declare class NetworkError extends ChanlError {
+    constructor(message?: string, options?: {
+        cause?: Error | undefined;
+        details?: Record<string, unknown> | undefined;
+    });
+}
+/**
+ * Error thrown when request times out
+ */
+export declare class TimeoutError extends ChanlError {
+    /** Timeout duration in milliseconds */
+    readonly timeoutMs?: number;
+    constructor(message?: string, options?: {
+        timeoutMs?: number | undefined;
+        details?: Record<string, unknown> | undefined;
+        requestId?: string | undefined;
+    });
+}
+/**
+ * Type guard to check if error is a ChanlError
+ */
+export declare function isChanlError(error: unknown): error is ChanlError;
+/**
+ * Type guard to check if error is a NotFoundError
+ */
+export declare function isNotFoundError(error: unknown): error is NotFoundError;
+/**
+ * Type guard to check if error is a ValidationError
+ */
+export declare function isValidationError(error: unknown): error is ValidationError;
+/**
+ * Type guard to check if error is an AuthenticationError
+ */
+export declare function isAuthenticationError(error: unknown): error is AuthenticationError;
+/**
+ * Factory function to create appropriate error from API response
+ */
+export declare function createErrorFromResponse(statusCode: number, message: string, options?: {
+    details?: Record<string, unknown> | undefined;
+    requestId?: string | undefined;
+    fieldErrors?: Record<string, string[]> | undefined;
+}): ChanlError;
+export {};
+//# sourceMappingURL=index.d.ts.map