@channlize/mcp 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @channlize/mcp
 
+## 0.4.0
+
+### Minor Changes
+
+- Release every `@channlize/*` package under one shared version. From 0.4.0 on, core, react, mcp and skills always publish together at the same version, so matching versions work together.
+
+### Patch Changes
+
+- 5663cd2: Make `@channlize/core` the single source for what the packages share.
+
+  - core exports `DEFAULT_BASE_URL`, `DEFAULT_TIMEOUT`, `EVENT_SEVERITIES`, `EVENT_KEY_PATTERN`, `isValidEventKey`, `keyKind` (widget vs. server key), `readChannlizeEnv` (the `CHANNLIZE_*` variables) and `parseApiError` (the API's error shape). `createNotifier`, the client and `@channlize/mcp` use them instead of their own copies.
+  - `ChannlizeError` gains `requestId` and `details` (the API's error body, e.g. `limit`, `used` and `resetAt` on a plan-limit 429). When a legacy route puts its human-readable text in `error`, it becomes the message instead of `HTTP <status>`.
+  - The chat types document where the API differs from them (ISO string timestamps, session summaries without `messages`).
+  - `@channlize/react` and `@channlize/mcp` re-export the error classes as values, so `instanceof` works without importing core.
+  - mcp tool errors no longer end with a doubled period when a core error message ends with one.
+
+- Updated dependencies [5663cd2]
+- Updated dependencies
+  - @channlize/core@0.4.0
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -173,6 +173,15 @@ await server.runStdio(); // or: await server.runHttp({ port: 3333 })
 const mcp = buildServer({ serverApiKey: '…' });
 ```
 
+## Documentation
+
+- Guide: https://channlize.com/docs/mcp
+- All docs: https://channlize.com/docs (quick start, API keys, troubleshooting)
+
+## Changelog
+
+[CHANGELOG.md](./CHANGELOG.md) lists every release of `@channlize/mcp`. Product updates: https://channlize.com/docs/changelog
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as node_http from 'node:http';
 import { McpServer } from '@modelcontextprotocol/server';
-export { AuthenticationError, ChannlizeConfig, ChannlizeError, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, FileAttachment, NotifyResponse, RateLimitError, SendMessageResponse, ValidationError } from '@channlize/core';
+export { AuthenticationError, ChannlizeConfig, ChannlizeError, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, FileAttachment, KeyKind, NotifyResponse, RateLimitError, SendMessageResponse, ValidationError, keyKind } from '@channlize/core';
 
 /**
  * MCP-specific types and configuration for Channlize
@@ -54,9 +54,6 @@ interface HttpServerOptions {
 declare class ConfigError extends Error {
     constructor(message: string);
 }
-type KeyKind = 'widget' | 'server';
-/** `wk_…` is the public widget key; anything else is a server API key (`ch_live_…`). */
-declare function keyKind(key: string): KeyKind;
 interface ResolvedConfig {
     serverApiKey?: string;
     widgetKey?: string;
@@ -123,5 +120,5 @@ declare class ChannlizeMCPServer {
 /** Create a new Channlize MCP server. */
 declare function createMCPServer(options?: MCPServerOptions): ChannlizeMCPServer;
 
-export { ChannlizeMCPServer, ConfigError, ToolError, VERSION, buildServer, configFromEnv, createMCPServer, ChannlizeMCPServer as default, keyKind, resolveConfig };
-export type { ChannlizeMCPConfig, HttpServerOptions, KeyKind, MCPServerOptions, ResolvedConfig };
+export { ChannlizeMCPServer, ConfigError, ToolError, VERSION, buildServer, configFromEnv, createMCPServer, ChannlizeMCPServer as default, resolveConfig };
+export type { ChannlizeMCPConfig, HttpServerOptions, MCPServerOptions, ResolvedConfig };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as node_http from 'node:http';
 import { McpServer } from '@modelcontextprotocol/server';
-export { AuthenticationError, ChannlizeConfig, ChannlizeError, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, FileAttachment, NotifyResponse, RateLimitError, SendMessageResponse, ValidationError } from '@channlize/core';
+export { AuthenticationError, ChannlizeConfig, ChannlizeError, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, FileAttachment, KeyKind, NotifyResponse, RateLimitError, SendMessageResponse, ValidationError, keyKind } from '@channlize/core';
 
 /**
  * MCP-specific types and configuration for Channlize
@@ -54,9 +54,6 @@ interface HttpServerOptions {
 declare class ConfigError extends Error {
     constructor(message: string);
 }
-type KeyKind = 'widget' | 'server';
-/** `wk_…` is the public widget key; anything else is a server API key (`ch_live_…`). */
-declare function keyKind(key: string): KeyKind;
 interface ResolvedConfig {
     serverApiKey?: string;
     widgetKey?: string;
@@ -123,5 +120,5 @@ declare class ChannlizeMCPServer {
 /** Create a new Channlize MCP server. */
 declare function createMCPServer(options?: MCPServerOptions): ChannlizeMCPServer;
 
-export { ChannlizeMCPServer, ConfigError, ToolError, VERSION, buildServer, configFromEnv, createMCPServer, ChannlizeMCPServer as default, keyKind, resolveConfig };
-export type { ChannlizeMCPConfig, HttpServerOptions, KeyKind, MCPServerOptions, ResolvedConfig };
+export { ChannlizeMCPServer, ConfigError, ToolError, VERSION, buildServer, configFromEnv, createMCPServer, ChannlizeMCPServer as default, resolveConfig };
+export type { ChannlizeMCPConfig, HttpServerOptions, MCPServerOptions, ResolvedConfig };

package/dist/index.js

@@ -30,15 +30,19 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AuthenticationError: () => import_core4.AuthenticationError,
+  ChannlizeError: () => import_core4.ChannlizeError,
   ChannlizeMCPServer: () => ChannlizeMCPServer,
   ConfigError: () => ConfigError,
+  RateLimitError: () => import_core4.RateLimitError,
   ToolError: () => ToolError,
   VERSION: () => VERSION,
+  ValidationError: () => import_core4.ValidationError,
   buildServer: () => buildServer,
   configFromEnv: () => configFromEnv,
   createMCPServer: () => createMCPServer,
   default: () => index_default,
-  keyKind: () => keyKind,
+  keyKind: () => import_core2.keyKind,
   resolveConfig: () => resolveConfig
 });
 module.exports = __toCommonJS(index_exports);
@@ -75,7 +79,7 @@ function toToolError(err) {
   if (err instanceof ToolError) return err;
   if (err instanceof import_core.ChannlizeError) {
     return new ToolError(
-      err.statusCode ? hintFor(err.statusCode, err.message) : err.message,
+      err.statusCode ? hintFor(err.statusCode, err.message.replace(/\.$/, "")) : err.message,
       err.statusCode,
       err.code
     );
@@ -119,6 +123,7 @@ var ChannlizeApi = class {
           ...options.body !== void 0 ? { "Content-Type": "application/json" } : {},
           ...options.headers
         },
+        // oxlint-disable-next-line unicorn/no-invalid-fetch-options -- `method` is dynamic; GET calls never pass a body.
         body: options.body !== void 0 ? JSON.stringify(options.body) : void 0,
         signal: AbortSignal.timeout(this.config.timeout)
       });
@@ -145,13 +150,11 @@ var ChannlizeApi = class {
       }
     }
     if (!res.ok) {
-      const body = data ?? {};
-      const raw = Array.isArray(body.message) ? body.message.join(", ") : body.message;
-      const apiMessage = raw || (typeof body.error === "string" && /\s/.test(body.error) ? body.error : "") || `HTTP ${res.status} ${res.statusText}`.trim();
+      const { message, code } = (0, import_core.parseApiError)(res.status, data, res.statusText);
       throw new ToolError(
-        hintFor(res.status, apiMessage.replace(/\.$/, "")),
+        hintFor(res.status, message.replace(/\.$/, "")),
         res.status,
-        body.code ?? (typeof body.error === "string" ? body.error : void 0)
+        code
       );
     }
     if (data === void 0) {
@@ -213,17 +216,13 @@ var ChannlizeApi = class {
 };
 
 // src/config.ts
-var DEFAULT_BASE_URL = "https://api.channlize.com";
-var DEFAULT_TIMEOUT = 1e4;
+var import_core2 = require("@channlize/core");
 var ConfigError = class extends Error {
   constructor(message) {
     super(message);
     this.name = "ConfigError";
   }
 };
-function keyKind(key) {
-  return key.startsWith("wk_") ? "widget" : "server";
-}
 function clean(value) {
   const v = value?.trim();
   return v ? v : void 0;
@@ -232,18 +231,18 @@ function resolveConfig(config) {
   let serverApiKey = clean(config.serverApiKey);
   let widgetKey = clean(config.widgetKey);
   const apiKey = clean(config.apiKey);
-  if (serverApiKey && keyKind(serverApiKey) === "widget") {
+  if (serverApiKey && (0, import_core2.keyKind)(serverApiKey) === "widget") {
     throw new ConfigError(
       "CHANNLIZE_SERVER_API_KEY / --server-api-key holds a widget key (wk_\u2026). Widget keys are public and only work for the visitor tools: pass it as CHANNLIZE_WIDGET_KEY / --widget-key, and create a server API key (ch_live_\u2026) under SDK & Integration \u2192 API keys in the Channlize dashboard."
     );
   }
-  if (widgetKey && keyKind(widgetKey) === "server") {
+  if (widgetKey && (0, import_core2.keyKind)(widgetKey) === "server") {
     throw new ConfigError(
       "CHANNLIZE_WIDGET_KEY / --widget-key holds a server API key. Pass server keys (ch_live_\u2026) as CHANNLIZE_SERVER_API_KEY / --server-api-key; widget keys start with wk_."
     );
   }
   if (apiKey) {
-    if (keyKind(apiKey) === "widget") widgetKey ??= apiKey;
+    if ((0, import_core2.keyKind)(apiKey) === "widget") widgetKey ??= apiKey;
     else serverApiKey ??= apiKey;
   }
   if (!serverApiKey && !widgetKey) {
@@ -251,13 +250,13 @@ function resolveConfig(config) {
       "A Channlize key is required. Set CHANNLIZE_SERVER_API_KEY (or --server-api-key) to a server API key (ch_live_\u2026) from SDK & Integration \u2192 API keys in the Channlize dashboard. Use a read-scoped key for read-only access, or add the write scope to send events, logs and conversations."
     );
   }
-  const timeout = config.timeout ?? DEFAULT_TIMEOUT;
+  const timeout = config.timeout ?? import_core2.DEFAULT_TIMEOUT;
   if (!Number.isFinite(timeout) || timeout <= 0) {
     throw new ConfigError(
       `Invalid timeout "${config.timeout}": use milliseconds, e.g. 10000`
     );
   }
-  const baseUrl = (clean(config.baseUrl) ?? DEFAULT_BASE_URL).replace(
+  const baseUrl = (clean(config.baseUrl) ?? import_core2.DEFAULT_BASE_URL).replace(
     /\/+$/,
     ""
   );
@@ -265,7 +264,7 @@ function resolveConfig(config) {
     new URL(baseUrl);
   } catch {
     throw new ConfigError(
-      `Invalid base URL "${config.baseUrl}": use e.g. ${DEFAULT_BASE_URL}`
+      `Invalid base URL "${config.baseUrl}": use e.g. ${import_core2.DEFAULT_BASE_URL}`
     );
   }
   return {
@@ -277,15 +276,8 @@ function resolveConfig(config) {
   };
 }
 function configFromEnv(env = process.env) {
-  const timeout = clean(env.CHANNLIZE_TIMEOUT);
-  return {
-    serverApiKey: clean(env.CHANNLIZE_SERVER_API_KEY),
-    widgetKey: clean(env.CHANNLIZE_WIDGET_KEY),
-    apiKey: clean(env.CHANNLIZE_API_KEY),
-    projectId: clean(env.CHANNLIZE_PROJECT_ID),
-    baseUrl: clean(env.CHANNLIZE_BASE_URL),
-    timeout: timeout ? Number(timeout) : void 0
-  };
+  const { timeout, ...rest } = (0, import_core2.readChannlizeEnv)(env);
+  return { ...rest, timeout: timeout ? Number(timeout) : void 0 };
 }
 
 // src/prompts.ts
@@ -614,10 +606,9 @@ function registerResources(server, api) {
 
 // src/tools.ts
 var z2 = __toESM(require("zod/v4"));
+var import_core3 = require("@channlize/core");
 var STATUSES = ["open", "pending", "resolved", "closed"];
 var PRIORITIES = ["low", "normal", "high", "urgent"];
-var SEVERITIES = ["info", "warning", "error"];
-var EVENT_KEY = /^[a-z0-9][a-z0-9._-]*$/;
 function ok(data) {
   return {
     content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
@@ -852,7 +843,7 @@ function registerServerTools(server, api) {
       description: 'Post an Event to Slack: the event key (e.g. "user.subscribed") picks the channel and message template set under Events in the dashboard, and `data` fills its {{placeholders}}. An unknown key is saved as a disabled draft and answered with status "skipped". Needs the write scope. Pass an idempotencyKey so a retry never posts twice.',
       inputSchema: z2.object({
         event: z2.string().max(100).regex(
-          EVENT_KEY,
+          import_core3.EVENT_KEY_PATTERN,
           "lowercase letters, digits, dots, underscores or dashes"
         ).describe("Event key, e.g. user.subscribed"),
         data: record2.optional().describe(
@@ -939,7 +930,7 @@ function registerServerTools(server, api) {
       title: "Query logs",
       description: "Search log tracking (trackEvent / trackServerEvent / track_log), newest first. Filter by severity, source, text (matches the name and properties) and time range; paginate with limit/offset. Covers all projects unless projectId is given.",
       inputSchema: z2.object({
-        severity: z2.enum(SEVERITIES).optional(),
+        severity: z2.enum(import_core3.EVENT_SEVERITIES).optional(),
         source: z2.enum(["client_sdk", "server_api", "system"]).optional().describe(
           "client_sdk = browser (widget key), server_api = server key"
         ),
@@ -971,7 +962,7 @@ function registerServerTools(server, api) {
       description: "Record a log line under Log tracking from a trusted server context (source server_api). Needs the write scope. For Slack messages about product events use notify_event instead.",
       inputSchema: z2.object({
         name: z2.string().min(1).max(255).describe("Log name, e.g. payment.failed"),
-        severity: z2.enum(SEVERITIES).default("info"),
+        severity: z2.enum(import_core3.EVENT_SEVERITIES).default("info"),
         properties: record2.optional().describe("Extra fields")
       }),
       outputSchema: z2.object({ id: z2.string(), projectId: z2.string() }),
@@ -1191,7 +1182,8 @@ async function startHttpServer(factory, options = {}) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.3.0" : "0.0.0";
+var import_core4 = require("@channlize/core");
+var VERSION = true ? "0.4.0" : "0.0.0";
 var INSTRUCTIONS = `Channlize routes website conversations and app events to the team's Slack.
 - Inbox: list_conversations / get_conversation, then contacts. Replies and status changes happen in Slack or the dashboard.
 - Events (notify_event) post a Slack message per event key; list_event_definitions and list_event_deliveries explain what was sent or skipped.
@@ -1246,10 +1238,14 @@ function createMCPServer(options) {
 var index_default = ChannlizeMCPServer;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AuthenticationError,
+  ChannlizeError,
   ChannlizeMCPServer,
   ConfigError,
+  RateLimitError,
   ToolError,
   VERSION,
+  ValidationError,
   buildServer,
   configFromEnv,
   createMCPServer,