@protoboxai/sdk 1.0.0

package/dist/modules/knowledge.d.ts

@@ -0,0 +1,202 @@
+import { ChanlSDK } from "../client";
+import { ApiResponse } from "../types/config";
+export type KnowledgeSource = "text" | "url" | "file" | "manual" | "document" | "faq" | "api_docs" | "transcript";
+export type ProcessingStatus = "pending" | "processing" | "completed" | "failed";
+export interface KnowledgeMetadata {
+    category?: string;
+    tags?: string[];
+    url?: string;
+    author?: string;
+}
+export interface CrawlOptions {
+    /** Crawl depth: 0 = single page only, 1 = page + direct links, 2 = two levels deep */
+    depth?: number;
+    /** Maximum number of pages to crawl (limit: 50) */
+    maxPages?: number;
+    /** Only follow links on the same domain */
+    sameDomainOnly?: boolean;
+}
+export interface ChunkingOptions {
+    /** Target chunk size in tokens (default: 512) */
+    chunkSizeTokens?: number;
+    /** Overlap between chunks in tokens (default: 50) */
+    overlapTokens?: number;
+    /** Preserve sentence boundaries (default: true) */
+    preserveSentences?: boolean;
+}
+export interface Knowledge {
+    id: string;
+    _id?: string;
+    title: string;
+    content?: string;
+    source: KnowledgeSource;
+    processingStatus: ProcessingStatus;
+    processingProgress?: number;
+    taskId?: string;
+    folderId?: string;
+    metadata?: KnowledgeMetadata;
+    externalReferenceIds?: Record<string, string>;
+    isEnabled?: boolean;
+    chunkCount?: number;
+    tokenCount?: number;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface KnowledgeChunk {
+    id: string;
+    _id?: string;
+    knowledgeId: string;
+    content: string;
+    index: number;
+    embedding?: number[];
+    tokenCount?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Unified create knowledge data - supports text, URL, and file sources
+ */
+export interface CreateKnowledgeData {
+    /** Title of the knowledge entry */
+    title: string;
+    /** Source type: "text" for direct content, "url" for web fetch, "file" for uploads */
+    source: KnowledgeSource;
+    /** Content (required for source="text" or legacy sources) */
+    content?: string;
+    /** URL to fetch (required for source="url") */
+    url?: string;
+    /** Folder ID to organize the document */
+    folderId?: string;
+    /** Additional metadata */
+    metadata?: KnowledgeMetadata;
+    /** Whether the entry is enabled for search */
+    isEnabled?: boolean;
+    /** External reference IDs for multi-tenant filtering */
+    externalReferenceIds?: Record<string, string>;
+    /** Chunking options for document processing */
+    chunkingOptions?: ChunkingOptions;
+    /** URL crawling options (only for source="url") */
+    crawlOptions?: CrawlOptions;
+}
+export interface UpdateKnowledgeData {
+    title?: string;
+    content?: string;
+    folderId?: string;
+    metadata?: KnowledgeMetadata;
+    isEnabled?: boolean;
+    externalReferenceIds?: Record<string, string>;
+}
+export interface KnowledgeFilters {
+    search?: string;
+    source?: KnowledgeSource;
+    folderId?: string;
+    isEnabled?: boolean;
+    processingStatus?: ProcessingStatus;
+    externalReferenceIds?: Record<string, string>;
+    page?: number;
+    limit?: number;
+}
+export interface SearchKnowledgeData {
+    query: string;
+    /** Search mode: hybrid (default), vector, or text */
+    mode?: "hybrid" | "vector" | "text";
+    /** Maximum number of results */
+    limit?: number;
+    /** Filter by external reference IDs */
+    externalReferenceIds?: Record<string, string>;
+    /** Minimum similarity score (0-1) */
+    minScore?: number;
+}
+export interface SearchResult {
+    id: string;
+    knowledgeId: string;
+    title: string;
+    content: string;
+    score: number;
+    metadata?: Record<string, unknown>;
+}
+export interface SearchResponse {
+    results: SearchResult[];
+    query: string;
+    mode: string;
+    totalResults: number;
+}
+export interface KnowledgeListResponse {
+    items: Knowledge[];
+    total: number;
+    pagination?: {
+        page: number;
+        limit: number;
+        totalPages: number;
+        hasNext: boolean;
+        hasPrev: boolean;
+    };
+}
+export interface ProcessingTaskResponse {
+    id: string;
+    status: ProcessingStatus;
+    progress: number;
+    currentStep?: string;
+    documentId?: string;
+    error?: string;
+    result?: {
+        chunkCount: number;
+        wordCount: number;
+        characterCount: number;
+        processingTimeMs: number;
+    };
+    createdAt: string;
+    startedAt?: string;
+    completedAt?: string;
+}
+export declare class KnowledgeModule {
+    private sdk;
+    constructor(sdk: ChanlSDK);
+    /**
+     * List all knowledge entries with optional filters
+     */
+    list(filters?: KnowledgeFilters): Promise<ApiResponse<KnowledgeListResponse>>;
+    /**
+     * Get a single knowledge entry by ID
+     */
+    get(id: string): Promise<ApiResponse<Knowledge>>;
+    /**
+     * Create a new knowledge entry (unified endpoint)
+     *
+     * Supports three input methods:
+     * - source='text': Direct text content (sync, immediate completion)
+     * - source='url': Fetch from URL (async, returns taskId)
+     * - source='file': Upload file via multipart (async, returns taskId)
+     *
+     * For file uploads, use createFromFile() method instead.
+     */
+    create(data: CreateKnowledgeData): Promise<ApiResponse<Knowledge>>;
+    /**
+     * Create knowledge from a file upload
+     *
+     * @param file - File buffer or Blob
+     * @param filename - Original filename
+     * @param options - Additional options (title, folderId, etc.)
+     */
+    createFromFile(file: Buffer | Blob, filename: string, options?: Omit<CreateKnowledgeData, "source" | "content" | "url">): Promise<ApiResponse<Knowledge>>;
+    /**
+     * Update an existing knowledge entry
+     */
+    update(id: string, data: UpdateKnowledgeData): Promise<ApiResponse<Knowledge>>;
+    /**
+     * Delete a knowledge entry
+     */
+    delete(id: string): Promise<ApiResponse<void>>;
+    /**
+     * Search knowledge base
+     */
+    search(data: SearchKnowledgeData): Promise<ApiResponse<SearchResponse>>;
+    /**
+     * Get processing task status
+     */
+    getTaskStatus(taskId: string): Promise<ApiResponse<ProcessingTaskResponse>>;
+    /**
+     * Get chunks for a knowledge entry
+     */
+    getChunks(knowledgeId: string): Promise<ApiResponse<KnowledgeChunk[]>>;
+}
+//# sourceMappingURL=knowledge.d.ts.map

package/dist/modules/knowledge.js

@@ -0,0 +1,147 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KnowledgeModule = void 0;
+const form_data_1 = __importDefault(require("form-data"));
+// ============================================================================
+// KNOWLEDGE MODULE
+// ============================================================================
+class KnowledgeModule {
+    constructor(sdk) {
+        this.sdk = sdk;
+    }
+    /**
+     * List all knowledge entries with optional filters
+     */
+    async list(filters) {
+        const queryParams = new URLSearchParams();
+        if (filters?.search) {
+            queryParams.append("search", filters.search);
+        }
+        if (filters?.source) {
+            queryParams.append("source", filters.source);
+        }
+        if (filters?.folderId) {
+            queryParams.append("folderId", filters.folderId);
+        }
+        if (filters?.isEnabled !== undefined) {
+            queryParams.append("isEnabled", String(filters.isEnabled));
+        }
+        if (filters?.processingStatus) {
+            queryParams.append("processingStatus", filters.processingStatus);
+        }
+        if (filters?.externalReferenceIds) {
+            queryParams.append("externalReferenceIds", JSON.stringify(filters.externalReferenceIds));
+        }
+        if (filters?.page) {
+            queryParams.append("page", filters.page.toString());
+        }
+        if (filters?.limit) {
+            queryParams.append("limit", filters.limit.toString());
+        }
+        const url = `/api/v1/knowledge${queryParams.toString() ? `?${queryParams.toString()}` : ""}`;
+        return this.sdk.request("GET", url);
+    }
+    /**
+     * Get a single knowledge entry by ID
+     */
+    async get(id) {
+        return this.sdk.request("GET", `/api/v1/knowledge/${id}`);
+    }
+    /**
+     * Create a new knowledge entry (unified endpoint)
+     *
+     * Supports three input methods:
+     * - source='text': Direct text content (sync, immediate completion)
+     * - source='url': Fetch from URL (async, returns taskId)
+     * - source='file': Upload file via multipart (async, returns taskId)
+     *
+     * For file uploads, use createFromFile() method instead.
+     */
+    async create(data) {
+        return this.sdk.request("POST", "/api/v1/knowledge", data);
+    }
+    /**
+     * Create knowledge from a file upload
+     *
+     * @param file - File buffer or Blob
+     * @param filename - Original filename
+     * @param options - Additional options (title, folderId, etc.)
+     */
+    async createFromFile(file, filename, options) {
+        const formData = new form_data_1.default();
+        // Add file - use form-data package for Node.js compatibility
+        if (file instanceof Buffer) {
+            formData.append("file", file, { filename });
+        }
+        else {
+            // For Blob (browser), convert to buffer first
+            const arrayBuffer = await file.arrayBuffer();
+            formData.append("file", Buffer.from(arrayBuffer), { filename });
+        }
+        // Add source
+        formData.append("source", "file");
+        // Add optional fields
+        if (options?.title) {
+            formData.append("title", options.title);
+        }
+        if (options?.folderId) {
+            formData.append("folderId", options.folderId);
+        }
+        if (options?.metadata) {
+            // Filter out undefined values and only append if there's actual data
+            const cleanMetadata = Object.fromEntries(Object.entries(options.metadata).filter(([, v]) => v !== undefined));
+            if (Object.keys(cleanMetadata).length > 0) {
+                formData.append("metadata", JSON.stringify(cleanMetadata));
+            }
+        }
+        if (options?.isEnabled !== undefined) {
+            formData.append("isEnabled", String(options.isEnabled));
+        }
+        if (options?.externalReferenceIds) {
+            formData.append("externalReferenceIds", JSON.stringify(options.externalReferenceIds));
+        }
+        if (options?.chunkingOptions) {
+            formData.append("chunkingOptions", JSON.stringify(options.chunkingOptions));
+        }
+        return this.sdk.request("POST", "/api/v1/knowledge", formData, {
+            headers: {
+                ...formData.getHeaders(),
+            },
+        });
+    }
+    /**
+     * Update an existing knowledge entry
+     */
+    async update(id, data) {
+        return this.sdk.request("PATCH", `/api/v1/knowledge/${id}`, data);
+    }
+    /**
+     * Delete a knowledge entry
+     */
+    async delete(id) {
+        return this.sdk.request("DELETE", `/api/v1/knowledge/${id}`);
+    }
+    /**
+     * Search knowledge base
+     */
+    async search(data) {
+        return this.sdk.request("POST", "/api/v1/knowledge/search", data);
+    }
+    /**
+     * Get processing task status
+     */
+    async getTaskStatus(taskId) {
+        return this.sdk.request("GET", `/api/v1/knowledge/tasks/${taskId}`);
+    }
+    /**
+     * Get chunks for a knowledge entry
+     */
+    async getChunks(knowledgeId) {
+        return this.sdk.request("GET", `/api/v1/knowledge/${knowledgeId}/chunks`);
+    }
+}
+exports.KnowledgeModule = KnowledgeModule;
+//# sourceMappingURL=knowledge.js.map

package/dist/modules/mcp.d.ts

@@ -0,0 +1,138 @@
+/**
+ * McpModule - SDK module for MCP server configuration and status
+ *
+ * Provides access to MCP server configuration and health status.
+ * Used by CLI and admin UI to get ready-to-use agent configurations.
+ */
+import { ChanlSDK } from '../client';
+import { ApiResponse } from '../types/config';
+export interface AgentConfig {
+    url: string;
+    headers: Record<string, string>;
+    transport?: string;
+}
+export interface AgentConfigs {
+    claude: {
+        mcpServers: {
+            chanl: AgentConfig;
+        };
+    };
+    cursor: {
+        mcpServers: {
+            chanl: AgentConfig;
+        };
+    };
+    generic: AgentConfig;
+}
+export interface McpConfigResponse {
+    serverUrl: string;
+    environment: 'production' | 'staging' | 'development';
+    status: 'active' | 'disabled';
+    toolCount: number;
+    resourceCount: number;
+    promptCount: number;
+    toolsetId?: string;
+    toolsetName?: string;
+    agentConfigs: AgentConfigs;
+}
+export interface McpStatusResponse {
+    healthy: boolean;
+    message: string;
+    responseTimeMs?: number;
+    error?: string;
+}
+export interface McpConfigOptions {
+    toolsetId?: string;
+}
+export interface McpTool {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+}
+export interface McpToolCallResult {
+    content: Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+    isError?: boolean;
+}
+export declare class McpModule {
+    private sdk;
+    constructor(sdk: ChanlSDK);
+    /**
+     * Get MCP configuration for a workspace
+     *
+     * @param options - Optional configuration options (e.g., toolsetId filter)
+     * @returns MCP configuration including server URL and agent configs
+     *
+     * @example
+     * typescript
+     * const { data } = await sdk.mcp.getConfig('ws_123');
+     * console.log(data.serverUrl);
+     * console.log(data.agentConfigs.claude);
+     */
+    getConfig(options?: McpConfigOptions): Promise<ApiResponse<McpConfigResponse>>;
+    /**
+     * Check MCP server health status
+     *
+     * @returns Health status of the MCP server
+     *
+     * @example
+     * typescript
+     * const { data } = await sdk.mcp.getStatus('ws_123');
+     * if (data.healthy) {
+     *   console.log('MCP server is running');
+     * }
+     */
+    getStatus(): Promise<ApiResponse<McpStatusResponse>>;
+    /**
+     * List MCP tools available for an agent
+     *
+     * @param agentId - Agent ID to list tools for
+     * @returns List of MCP tools with their schemas
+     *
+     * @example
+     * ```typescript
+     * const { data } = await sdk.mcp.listTools('ws_123', 'agent_456');
+     * for (const tool of data.tools) {
+     *   console.log(tool.name, tool.description);
+     * }
+     * ```
+     */
+    listTools(agentId: string): Promise<ApiResponse<{
+        tools: McpTool[];
+    }>>;
+    /**
+     * Call an MCP tool by name
+     *
+     * @param agentId - Agent ID that owns the tool
+     * @param toolName - Name of the tool to invoke
+     * @param args - Optional arguments to pass to the tool
+     * @returns Tool call result with content array
+     *
+     * @example
+     * ```typescript
+     * const { data } = await sdk.mcp.callTool('ws_123', 'agent_456', 'get_weather', { city: 'London' });
+     * if (!data.isError) {
+     *   console.log(data.content[0].text);
+     * }
+     * ```
+     */
+    callTool(agentId: string, toolName: string, args?: Record<string, unknown>): Promise<ApiResponse<McpToolCallResult>>;
+    /**
+     * Get details and schema for a specific MCP tool
+     *
+     * @param agentId - Agent ID that owns the tool
+     * @param toolName - Name of the tool to inspect
+     * @returns Tool details including input schema
+     *
+     * @example
+     * ```typescript
+     * const { data } = await sdk.mcp.getTool('ws_123', 'agent_456', 'get_weather');
+     * console.log(data.tool.inputSchema);
+     * ```
+     */
+    getTool(agentId: string, toolName: string): Promise<ApiResponse<McpTool>>;
+}
+//# sourceMappingURL=mcp.d.ts.map

package/dist/modules/mcp.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * McpModule - SDK module for MCP server configuration and status
+ *
+ * Provides access to MCP server configuration and health status.
+ * Used by CLI and admin UI to get ready-to-use agent configurations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpModule = void 0;
+// ============================================================================
+// MCP MODULE
+// ============================================================================
+class McpModule {
+    constructor(sdk) {
+        this.sdk = sdk;
+    }
+    /**
+     * Get MCP configuration for a workspace
+     *
+     * @param options - Optional configuration options (e.g., toolsetId filter)
+     * @returns MCP configuration including server URL and agent configs
+     *
+     * @example
+     * typescript
+     * const { data } = await sdk.mcp.getConfig('ws_123');
+     * console.log(data.serverUrl);
+     * console.log(data.agentConfigs.claude);
+     */
+    async getConfig(options) {
+        const queryParams = new URLSearchParams();
+        if (options?.toolsetId) {
+            queryParams.append('toolsetId', options.toolsetId);
+        }
+        const queryString = queryParams.toString();
+        const url = '/api/v1/mcp/config' + (queryString ? '?' + queryString : '');
+        return this.sdk.request('GET', url);
+    }
+    /**
+     * Check MCP server health status
+     *
+     * @returns Health status of the MCP server
+     *
+     * @example
+     * typescript
+     * const { data } = await sdk.mcp.getStatus('ws_123');
+     * if (data.healthy) {
+     *   console.log('MCP server is running');
+     * }
+     */
+    async getStatus() {
+        return this.sdk.request('GET', '/api/v1/mcp/status');
+    }
+    /**
+     * List MCP tools available for an agent
+     *
+     * @param agentId - Agent ID to list tools for
+     * @returns List of MCP tools with their schemas
+     *
+     * @example
+     * ```typescript
+     * const { data } = await sdk.mcp.listTools('ws_123', 'agent_456');
+     * for (const tool of data.tools) {
+     *   console.log(tool.name, tool.description);
+     * }
+     * ```
+     */
+    async listTools(agentId) {
+        return this.sdk.request('GET', `/api/v1/mcp/agents/${agentId}/tools`);
+    }
+    /**
+     * Call an MCP tool by name
+     *
+     * @param agentId - Agent ID that owns the tool
+     * @param toolName - Name of the tool to invoke
+     * @param args - Optional arguments to pass to the tool
+     * @returns Tool call result with content array
+     *
+     * @example
+     * ```typescript
+     * const { data } = await sdk.mcp.callTool('ws_123', 'agent_456', 'get_weather', { city: 'London' });
+     * if (!data.isError) {
+     *   console.log(data.content[0].text);
+     * }
+     * ```
+     */
+    async callTool(agentId, toolName, args) {
+        return this.sdk.request('POST', `/api/v1/mcp/agents/${agentId}/tools/call`, {
+            name: toolName,
+            arguments: args,
+        });
+    }
+    /**
+     * Get details and schema for a specific MCP tool
+     *
+     * @param agentId - Agent ID that owns the tool
+     * @param toolName - Name of the tool to inspect
+     * @returns Tool details including input schema
+     *
+     * @example
+     * ```typescript
+     * const { data } = await sdk.mcp.getTool('ws_123', 'agent_456', 'get_weather');
+     * console.log(data.tool.inputSchema);
+     * ```
+     */
+    async getTool(agentId, toolName) {
+        return this.sdk.request('GET', `/api/v1/mcp/agents/${agentId}/tools/${toolName}`);
+    }
+}
+exports.McpModule = McpModule;
+//# sourceMappingURL=mcp.js.map