@protoboxai/sdk 1.0.0

package/README.md

@@ -0,0 +1,51 @@
+# @protoboxai/sdk
+
+Public TypeScript SDK for [Protobox](https://protobox.app) — managed MCP servers, tools, agents, knowledge resources, prompts, and chat.
+
+Forked from [`@chanl/sdk`](https://www.npmjs.com/package/@chanl/sdk) (source: `../chanl-v2/chanl-sdk`). Same API surface; Protobox-branded package for npm publish.
+
+## Install
+
+```bash
+npm install @protoboxai/sdk
+```
+
+## Quick start
+
+```typescript
+import { ProtoboxSDK } from '@protoboxai/sdk';
+
+const sdk = new ProtoboxSDK({
+  apiKey: process.env.PROTOBOX_API_KEY!,
+  baseUrl: 'https://platform.protobox.ai', // or http://localhost:3100
+});
+
+// MCP-focused surface
+const tools = await sdk.tools.list();
+const resources = await sdk.knowledge.list();
+const prompts = await sdk.prompts.list();
+```
+
+## Modules
+
+| Module | Purpose |
+|--------|---------|
+| `tools` / `toolsets` | HTTP/OpenAPI tools exposed via MCP |
+| `knowledge` | Knowledge base (documents, URLs, files) |
+| `prompts` | MCP prompt templates |
+| `agents` | Workspace agents |
+| `mcp` | MCP server helpers |
+| `chat` | Text chat with agents |
+
+## Sync from upstream
+
+When `chanl-sdk` changes, refresh this package from the monorepo root:
+
+```bash
+make sync-public-sdk
+make build-public-sdk
+```
+
+## Publish
+
+Package is publish-ready (`publishConfig.access: public`). Bump version in `package.json` before `npm publish` from `packages/protobox-sdk`.

package/dist/adapters/openai.d.ts

@@ -0,0 +1,106 @@
+/**
+ * OpenAI Adapter for @chanl/sdk
+ *
+ * TDD Phase: GREEN - Implementation to make tests pass
+ *
+ * Provides integration with OpenAI's function calling format:
+ * 1. Convert Chanl tools to OpenAI ChatCompletionTool format
+ * 2. Execute tool calls from OpenAI responses
+ */
+import { ChanlSDK } from '../client';
+/**
+ * OpenAI function definition
+ */
+export interface OpenAIFunction {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/**
+ * OpenAI ChatCompletionTool format
+ */
+export interface OpenAIChatCompletionTool {
+    type: 'function';
+    function: OpenAIFunction;
+}
+/**
+ * OpenAI tool call from assistant response
+ */
+export interface OpenAIToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/**
+ * Tool output for OpenAI messages
+ * Matches OpenAI's ChatCompletionToolMessageParam
+ */
+export interface ToolOutput {
+    tool_call_id: string;
+    role: 'tool';
+    content: string;
+}
+/**
+ * Options for fetching tools
+ */
+export interface GetToolsOptions {
+    /** Filter by tag */
+    tag?: string;
+}
+/**
+ * Adapter to integrate Chanl tools with OpenAI's function calling
+ *
+ * @example
+ * ```typescript
+ * const adapter = new OpenAIAdapter(sdk, 'ws_abc123');
+ *
+ * // Get tools as OpenAI functions
+ * const tools = await adapter.getToolsAsOpenAIFunctions();
+ *
+ * // Use with OpenAI
+ * const response = await openai.chat.completions.create({
+ *   model: 'gpt-4',
+ *   messages: [...],
+ *   tools,
+ * });
+ *
+ * // Execute tool calls from response
+ * if (response.choices[0].message.tool_calls) {
+ *   const results = await adapter.executeToolCalls(
+ *     response.choices[0].message.tool_calls
+ *   );
+ * }
+ * ```
+ */
+export declare class OpenAIAdapter {
+    private sdk;
+    /** Cached tools for lookup during execution */
+    private toolsCache;
+    constructor(sdk: ChanlSDK);
+    /**
+     * Convert Chanl tools to OpenAI function calling format
+     *
+     * @param options - Optional filters for which tools to include
+     * @returns Array of OpenAI ChatCompletionTool objects
+     */
+    getToolsAsOpenAIFunctions(options?: GetToolsOptions): Promise<OpenAIChatCompletionTool[]>;
+    /**
+     * Execute tool calls from an OpenAI response
+     *
+     * @param toolCalls - Array of tool calls from OpenAI assistant message
+     * @returns Array of tool outputs ready for OpenAI messages
+     */
+    executeToolCalls(toolCalls: OpenAIToolCall[]): Promise<ToolOutput[]>;
+    /**
+     * Convert a single Chanl tool to OpenAI function format
+     */
+    private convertToolToOpenAI;
+    /**
+     * Execute a single tool call
+     */
+    private executeSingleToolCall;
+}
+//# sourceMappingURL=openai.d.ts.map

package/dist/adapters/openai.js

@@ -0,0 +1,185 @@
+"use strict";
+/**
+ * OpenAI Adapter for @chanl/sdk
+ *
+ * TDD Phase: GREEN - Implementation to make tests pass
+ *
+ * Provides integration with OpenAI's function calling format:
+ * 1. Convert Chanl tools to OpenAI ChatCompletionTool format
+ * 2. Execute tool calls from OpenAI responses
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIAdapter = void 0;
+/**
+ * Adapter to integrate Chanl tools with OpenAI's function calling
+ *
+ * @example
+ * ```typescript
+ * const adapter = new OpenAIAdapter(sdk, 'ws_abc123');
+ *
+ * // Get tools as OpenAI functions
+ * const tools = await adapter.getToolsAsOpenAIFunctions();
+ *
+ * // Use with OpenAI
+ * const response = await openai.chat.completions.create({
+ *   model: 'gpt-4',
+ *   messages: [...],
+ *   tools,
+ * });
+ *
+ * // Execute tool calls from response
+ * if (response.choices[0].message.tool_calls) {
+ *   const results = await adapter.executeToolCalls(
+ *     response.choices[0].message.tool_calls
+ *   );
+ * }
+ * ```
+ */
+class OpenAIAdapter {
+    constructor(sdk) {
+        this.sdk = sdk;
+        /** Cached tools for lookup during execution */
+        this.toolsCache = new Map();
+    }
+    /**
+     * Convert Chanl tools to OpenAI function calling format
+     *
+     * @param options - Optional filters for which tools to include
+     * @returns Array of OpenAI ChatCompletionTool objects
+     */
+    async getToolsAsOpenAIFunctions(options = {}) {
+        const filters = {
+            isEnabled: true,
+        };
+        if (options.tag) {
+            filters.tag = options.tag;
+        }
+        const response = await this.sdk.tools.list(filters);
+        if (!response.success || !response.data?.tools) {
+            return [];
+        }
+        // Cache tools for later execution
+        this.toolsCache.clear();
+        for (const tool of response.data.tools) {
+            this.toolsCache.set(tool.name, tool);
+        }
+        return response.data.tools.map((tool) => this.convertToolToOpenAI(tool));
+    }
+    /**
+     * Execute tool calls from an OpenAI response
+     *
+     * @param toolCalls - Array of tool calls from OpenAI assistant message
+     * @returns Array of tool outputs ready for OpenAI messages
+     */
+    async executeToolCalls(toolCalls) {
+        if (toolCalls.length === 0) {
+            return [];
+        }
+        // Refresh cache if empty
+        if (this.toolsCache.size === 0) {
+            await this.getToolsAsOpenAIFunctions();
+        }
+        const results = [];
+        for (const toolCall of toolCalls) {
+            const result = await this.executeSingleToolCall(toolCall);
+            results.push(result);
+        }
+        return results;
+    }
+    /**
+     * Convert a single Chanl tool to OpenAI function format
+     */
+    convertToolToOpenAI(tool) {
+        return {
+            type: 'function',
+            function: {
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.inputSchema,
+            },
+        };
+    }
+    /**
+     * Execute a single tool call
+     */
+    async executeSingleToolCall(toolCall) {
+        const { id, function: func } = toolCall;
+        const { name, arguments: argsString } = func;
+        // Find the tool
+        const tool = this.toolsCache.get(name);
+        if (!tool) {
+            return {
+                tool_call_id: id,
+                role: 'tool',
+                content: JSON.stringify({
+                    error: `Tool '${name}' not found`,
+                }),
+            };
+        }
+        // Parse arguments
+        let args;
+        try {
+            args = JSON.parse(argsString);
+        }
+        catch {
+            return {
+                tool_call_id: id,
+                role: 'tool',
+                content: JSON.stringify({
+                    error: `Invalid JSON arguments: ${argsString}`,
+                }),
+            };
+        }
+        // Execute the tool
+        try {
+            const response = await this.sdk.tools.execute(tool.id, args);
+            if (!response.success) {
+                return {
+                    tool_call_id: id,
+                    role: 'tool',
+                    content: JSON.stringify({
+                        error: response.message ?? 'Tool execution failed',
+                    }),
+                };
+            }
+            const execution = response.data;
+            // Handle undefined execution data
+            if (!execution) {
+                return {
+                    tool_call_id: id,
+                    role: 'tool',
+                    content: JSON.stringify({
+                        error: 'No execution data returned',
+                    }),
+                };
+            }
+            // Check if execution failed
+            if (!execution.success) {
+                return {
+                    tool_call_id: id,
+                    role: 'tool',
+                    content: JSON.stringify({
+                        error: execution.error ?? 'Execution failed',
+                    }),
+                };
+            }
+            // Return successful output
+            return {
+                tool_call_id: id,
+                role: 'tool',
+                content: JSON.stringify(execution.data ?? {}),
+            };
+        }
+        catch (error) {
+            return {
+                tool_call_id: id,
+                role: 'tool',
+                content: JSON.stringify({
+                    error: error instanceof Error ? error.message : 'Unknown execution error',
+                }),
+            };
+        }
+    }
+}
+exports.OpenAIAdapter = OpenAIAdapter;
+//# sourceMappingURL=openai.js.map

package/dist/client.d.ts

@@ -0,0 +1,60 @@
+import { ChanlConfig, RequestConfig, ApiResponse } from "./types/config";
+import { WorkspaceModule } from "./modules/workspace";
+import { AuthModule } from "./modules/auth";
+import { HealthModule } from "./modules/health";
+import { PromptsModule } from "./modules/prompts";
+import { ToolsModule } from "./modules/tools";
+import { ToolsetsModule } from "./modules/toolsets";
+import { McpModule } from "./modules/mcp";
+import { KnowledgeModule } from "./modules/knowledge";
+import { ChatModule } from "./modules/chat";
+export declare class ChanlSDK {
+    private config;
+    readonly workspace: WorkspaceModule;
+    readonly auth: AuthModule;
+    readonly health: HealthModule;
+    readonly prompts: PromptsModule;
+    readonly tools: ToolsModule;
+    readonly toolsets: ToolsetsModule;
+    readonly mcp: McpModule;
+    readonly knowledge: KnowledgeModule;
+    readonly chat: ChatModule;
+    constructor(config: ChanlConfig);
+    /**
+     * Make a request to the API
+     */
+    /**
+     * Rewrite `/api/v1/...` paths for local OSS servers (flat routes).
+     */
+    resolveRequestPath(path: string): string;
+    request<T = unknown>(method: string, url: string, data?: unknown, config?: RequestConfig): Promise<ApiResponse<T>>;
+    /**
+     * 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).
+     */
+    requestStream(method: string, url: string, data?: unknown): Promise<Response>;
+    /**
+     * Recursively normalize _id → id in response data.
+     * Skips if id already exists to avoid overwriting.
+     */
+    private normalizeIds;
+    /**
+     * Update authentication credentials
+     */
+    updateAuth(authConfig: {
+        apiKey?: string;
+        jwtToken?: string;
+    }): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): ChanlConfig;
+    /**
+     * Enable/disable debug logging
+     */
+    setDebug(enabled: boolean): void;
+}
+//# sourceMappingURL=client.d.ts.map