@channlize/mcp 0.4.0 → 0.6.0

package/dist/inbox-BfpFVoK7.d.ts

@@ -0,0 +1,194 @@
+import * as z from 'zod/v4';
+import { ChannlizeClient } from '@channlize/core';
+
+/**
+ * MCP-specific types and configuration for Channlize
+ */
+interface ChannlizeMCPConfig {
+    /**
+     * Server API key (`ch_live_…`) for the project, conversation, contact,
+     * Events and log tools. A `read`-scoped key exposes the read tools; add
+     * the `write` scope to send events and logs and to open conversations.
+     */
+    serverApiKey?: string;
+    /**
+     * Public widget key (`wk_…`), only for the visitor-side tools (contact
+     * form, chat session). Optional.
+     */
+    widgetKey?: string;
+    /**
+     * Either kind of key, detected by its prefix (`wk_` → widget key,
+     * otherwise server key). Fills `serverApiKey` / `widgetKey` when unset.
+     */
+    apiKey?: string;
+    /**
+     * Project ID for Events, logs and project-scoped reads. Defaults to the
+     * first project of the key's organization.
+     */
+    projectId?: string;
+    /**
+     * Channlize for Agents: the agent the agent tools act as when a call
+     * doesn't pass `agentId`. Needed with a multi-agent key (unless it lists
+     * one agent); an agent key always acts as its own agent.
+     */
+    agentId?: string;
+    /** Base URL for the Channlize API (default https://api.channlize.com) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default 10000) */
+    timeout?: number;
+}
+interface MCPServerOptions {
+    /** Server name */
+    name?: string;
+    /** Server version */
+    version?: string;
+    /** Channlize configuration */
+    config?: ChannlizeMCPConfig;
+}
+
+/** A configuration problem the user must fix; the CLI prints it and exits 1. */
+declare class ConfigError extends Error {
+    constructor(message: string);
+}
+interface ResolvedConfig {
+    serverApiKey?: string;
+    widgetKey?: string;
+    projectId?: string;
+    /** Default agent for the agent tools (multi-agent keys). */
+    agentId?: string;
+    baseUrl: string;
+    timeout: number;
+}
+/**
+ * Normalizes the config: `apiKey` (either kind, detected by prefix) fills
+ * whichever of `serverApiKey` / `widgetKey` is missing, and a key passed in
+ * the wrong slot fails with a message that says which one to use.
+ */
+declare function resolveConfig(config: ChannlizeMCPConfig): ResolvedConfig;
+/** Reads `ChannlizeMCPConfig` from the environment (CLI flags override it). */
+declare function configFromEnv(env?: NodeJS.ProcessEnv): ChannlizeMCPConfig;
+
+type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'DELETE';
+/**
+ * A failed Channlize call, worded for the model: what went wrong and how
+ * to fix it (wrong key, missing scope, unknown id). Tool handlers throw it
+ * and the MCP server returns it as a tool error (`isError: true`).
+ */
+declare class ToolError extends Error {
+    statusCode?: number | undefined;
+    code?: string | undefined;
+    /** ISO time the call may succeed again (agent policies, takeovers). */
+    retryAt?: string | undefined;
+    constructor(message: string, statusCode?: number | undefined, code?: string | undefined, 
+    /** ISO time the call may succeed again (agent policies, takeovers). */
+    retryAt?: string | undefined);
+}
+type Query$1 = Record<string, string | number | boolean | undefined>;
+/** Maps a `@channlize/core` error to a `ToolError` with the same hints. */
+declare function toToolError(err: unknown): ToolError;
+/**
+ * Thin client for the API-key endpoints `@channlize/core` doesn't wrap
+ * (projects, the inbox, routing rules, contacts, Events and log reads,
+ * agents). Widget-key
+ * calls and `notify` go through `@channlize/core`.
+ */
+declare class ChannlizeApi {
+    readonly config: ResolvedConfig;
+    private projectIdPromise?;
+    private widgetClient?;
+    constructor(config: ResolvedConfig);
+    get hasServerKey(): boolean;
+    get hasWidgetKey(): boolean;
+    /** The default agent for the agent tools (`CHANNLIZE_AGENT_ID`). */
+    get agentId(): string | undefined;
+    private requireServerKey;
+    request<T>(method: HttpMethod, path: string, options?: {
+        query?: Query$1;
+        body?: unknown;
+        headers?: Record<string, string>;
+        /** Overrides the configured timeout, in ms (long-polls). */
+        timeout?: number;
+    }): Promise<T>;
+    /**
+     * `CHANNLIZE_PROJECT_ID`, or the first project of the key's organization
+     * (`GET /projects/me`), looked up once.
+     */
+    projectId(): Promise<string>;
+    /** `@channlize/core` client bound to the widget key (visitor tools). */
+    widget(): ChannlizeClient;
+    /** `@channlize/core` client for `notify` (server key + project). */
+    notifier(): Promise<ChannlizeClient>;
+}
+
+/**
+ * The Channlize inbox toolset: names, zod input/output schemas and handlers
+ * for working the inbox through the API-key endpoints under `/v1`.
+ *
+ * This module has no dependency on the MCP server or its transports, so any
+ * agent can import it (`@channlize/mcp/inbox`): the stdio/HTTP server
+ * registers these tools (`registerInboxTools` in `tools.ts`), and the
+ * dashboard copilot or an internal bot can run the same handlers with its own
+ * client (anything with a `request(method, path, { query, body })`).
+ *
+ * Writes act as a named agent: the API key's name. Replies show in Slack as
+ * "Replied by <key name> (agent)", and changes as "… by <key name> (agent)".
+ *
+ * Scopes (pick them when creating the key): `inbox:read`, `inbox:write`,
+ * `routing:write`, `analytics:read`. A `read` key can use the read tools.
+ */
+
+type Json = Record<string, unknown>;
+type Query = Record<string, string | number | boolean | undefined>;
+/** What a handler needs: `ChannlizeApi` from this package, or your own. */
+interface InboxRequester {
+    request<T>(method: HttpMethod, path: string, options?: {
+        query?: Query;
+        body?: unknown;
+    }): Promise<T>;
+}
+/** The API key scope a tool needs. `routing:read` is granted by `routing:write`, `inbox:read` or `read`. */
+type InboxScope = 'inbox:read' | 'inbox:write' | 'routing:read' | 'routing:write' | 'analytics:read';
+interface ToolAnnotations {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+}
+interface InboxTool<I extends z.ZodObject = z.ZodObject, O extends z.ZodObject = z.ZodObject> {
+    name: string;
+    title: string;
+    description: string;
+    scope: InboxScope;
+    /** The HTTP endpoint it calls, for docs and logs. */
+    endpoint: string;
+    inputSchema: I;
+    outputSchema: O;
+    annotations: ToolAnnotations;
+    handler: (api: InboxRequester, args: z.output<I>) => Promise<z.output<O>>;
+}
+declare const CONVERSATION_STATUSES: readonly ["open", "pending", "resolved", "closed"];
+declare const CONVERSATION_PRIORITIES: readonly ["low", "normal", "high", "urgent"];
+declare const CONVERSATION_SORTS: readonly ["recent", "oldest", "newest", "priority"];
+declare const ROUTING_FIELDS: readonly ["source", "project", "widget", "connection", "page_url", "page_domain", "customer_email", "customer_email_domain", "message", "subject", "tags", "priority", "language"];
+declare const ROUTING_OPERATORS: readonly ["equals", "not_equals", "contains", "not_contains", "starts_with", "ends_with", "matches"];
+declare const INBOX_TOOLS: readonly InboxTool[];
+declare const INBOX_TOOL_NAMES: string[];
+declare function getInboxTool(name: string): InboxTool | undefined;
+/**
+ * Validate `args` against the tool's input schema and run it. Throws
+ * `ToolError` for an unknown tool or invalid arguments, and for API
+ * failures (`toToolError` in `api.ts` words them for the model).
+ */
+declare function runInboxTool(api: InboxRequester, name: string, args: unknown): Promise<Json>;
+/**
+ * The tools as JSON Schema function definitions, for LLM APIs that take
+ * `{ name, description, parameters }` (OpenAI / OpenRouter style).
+ */
+declare function inboxToolsAsJsonSchema(filter?: (tool: InboxTool) => boolean): Array<{
+    name: string;
+    description: string;
+    parameters: Json;
+}>;
+
+export { ChannlizeApi as C, INBOX_TOOLS as I, ROUTING_FIELDS as R, CONVERSATION_PRIORITIES as b, CONVERSATION_SORTS as c, CONVERSATION_STATUSES as d, ConfigError as e, INBOX_TOOL_NAMES as f, ROUTING_OPERATORS as j, ToolError as l, configFromEnv as m, getInboxTool as n, inboxToolsAsJsonSchema as o, runInboxTool as p, resolveConfig as r, toToolError as t };
+export type { HttpMethod as H, MCPServerOptions as M, ToolAnnotations as T, ChannlizeMCPConfig as a, InboxRequester as g, InboxScope as h, InboxTool as i, ResolvedConfig as k };

package/dist/inbox.d.mts

@@ -0,0 +1,3 @@
+import 'zod/v4';
+export { b as CONVERSATION_PRIORITIES, c as CONVERSATION_SORTS, d as CONVERSATION_STATUSES, H as HttpMethod, I as INBOX_TOOLS, f as INBOX_TOOL_NAMES, g as InboxRequester, h as InboxScope, i as InboxTool, R as ROUTING_FIELDS, j as ROUTING_OPERATORS, T as ToolAnnotations, n as getInboxTool, o as inboxToolsAsJsonSchema, p as runInboxTool } from './inbox-BfpFVoK7.mjs';
+import '@channlize/core';

package/dist/inbox.d.ts

@@ -0,0 +1,3 @@
+import 'zod/v4';
+export { b as CONVERSATION_PRIORITIES, c as CONVERSATION_SORTS, d as CONVERSATION_STATUSES, H as HttpMethod, I as INBOX_TOOLS, f as INBOX_TOOL_NAMES, g as InboxRequester, h as InboxScope, i as InboxTool, R as ROUTING_FIELDS, j as ROUTING_OPERATORS, T as ToolAnnotations, n as getInboxTool, o as inboxToolsAsJsonSchema, p as runInboxTool } from './inbox-BfpFVoK7.js';
+import '@channlize/core';