@channlize/mcp 0.4.0 → 0.6.0

package/dist/inbox.js

@@ -0,0 +1,587 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/inbox.ts
+var inbox_exports = {};
+__export(inbox_exports, {
+  CONVERSATION_PRIORITIES: () => CONVERSATION_PRIORITIES,
+  CONVERSATION_SORTS: () => CONVERSATION_SORTS,
+  CONVERSATION_STATUSES: () => CONVERSATION_STATUSES,
+  INBOX_TOOLS: () => INBOX_TOOLS,
+  INBOX_TOOL_NAMES: () => INBOX_TOOL_NAMES,
+  ROUTING_FIELDS: () => ROUTING_FIELDS,
+  ROUTING_OPERATORS: () => ROUTING_OPERATORS,
+  getInboxTool: () => getInboxTool,
+  inboxToolsAsJsonSchema: () => inboxToolsAsJsonSchema,
+  runInboxTool: () => runInboxTool
+});
+module.exports = __toCommonJS(inbox_exports);
+var z = __toESM(require("zod/v4"));
+
+// src/api.ts
+var import_core = require("@channlize/core");
+var ToolError = class extends Error {
+  constructor(message, statusCode, code, retryAt) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.retryAt = retryAt;
+    this.name = "ToolError";
+  }
+  statusCode;
+  code;
+  retryAt;
+};
+
+// src/inbox.ts
+function defineTool(tool) {
+  return tool;
+}
+var CONVERSATION_STATUSES = [
+  "open",
+  "pending",
+  "resolved",
+  "closed"
+];
+var CONVERSATION_PRIORITIES = [
+  "low",
+  "normal",
+  "high",
+  "urgent"
+];
+var CONVERSATION_SORTS = [
+  "recent",
+  "oldest",
+  "newest",
+  "priority"
+];
+var loose = z.looseObject({});
+var id = (what) => z.string().uuid().describe(`${what} ID`);
+var conversationId = id(
+  "Conversation (from list_conversations or search_conversations)"
+);
+var person = z.looseObject({
+  id: z.string(),
+  name: z.string().nullable().optional(),
+  email: z.string().nullable().optional()
+}).nullable();
+var conversationSummary = z.looseObject({
+  id: z.string(),
+  subject: z.string().nullable().optional(),
+  status: z.string(),
+  priority: z.string().optional(),
+  source: z.string().nullable().optional(),
+  tags: z.array(z.string()).optional(),
+  customer: person.optional(),
+  assignee: person.optional(),
+  triage: z.record(z.string(), z.unknown()).nullable().optional(),
+  needsReply: z.boolean().optional(),
+  lastActivityAt: z.string().nullable().optional()
+});
+var page = {
+  total: z.number(),
+  limit: z.number(),
+  offset: z.number(),
+  hasMore: z.boolean()
+};
+var listOutput = z.object({
+  conversations: z.array(conversationSummary),
+  ...page
+});
+var changeOutput = z.object({
+  conversation: z.looseObject({ id: z.string(), status: z.string() }),
+  changes: z.array(z.string())
+});
+var slackOutcome = z.string().describe(
+  "Slack mirror: queued, posted, no_thread (not in Slack), not_connected or failed"
+);
+var tags = z.array(z.string().trim().min(1).max(50)).max(20);
+var paging = {
+  limit: z.number().int().min(1).max(100).default(20).describe("How many to return (1-100, default 20)"),
+  offset: z.number().int().min(0).default(0).describe("Skip this many")
+};
+function oneOrMany(values) {
+  return z.union([z.enum(values), z.array(z.enum(values)).max(10)]).optional();
+}
+var asList = (v) => v === void 0 ? void 0 : Array.isArray(v) ? v.join(",") : v;
+var listFilters = {
+  status: oneOrMany(CONVERSATION_STATUSES).describe(
+    'Only these statuses: "open" or a list like ["open", "pending"]'
+  ),
+  priority: oneOrMany(CONVERSATION_PRIORITIES).describe(
+    'Only these priorities: "urgent" or a list'
+  ),
+  assignee: z.string().max(255).optional().describe('A teammate (user ID or email), "unassigned" or "assigned"'),
+  projectId: id("Project").optional(),
+  updatedSince: z.iso.datetime({ offset: true }).optional().describe("Updated or with a new message since (ISO 8601)"),
+  tag: z.string().max(50).optional().describe("Carrying this tag"),
+  source: z.string().max(32).optional().describe("Entry point, e.g. live_chat, contact_form, api, email"),
+  intent: z.string().max(64).optional().describe("AI triage intent (triaged conversations only)"),
+  urgency: z.string().max(64).optional().describe("AI triage urgency (triaged conversations only)"),
+  sort: z.enum(CONVERSATION_SORTS).optional().describe(
+    "recent (last activity, default), oldest, newest (created) or priority"
+  )
+};
+async function list(api, a) {
+  const r = await api.request("GET", "/v1/conversations", {
+    query: {
+      status: asList(a.status),
+      priority: asList(a.priority),
+      assignee: a.assignee,
+      projectId: a.projectId,
+      updatedSince: a.updatedSince,
+      tag: a.tag,
+      source: a.source,
+      intent: a.intent,
+      urgency: a.urgency,
+      sort: a.sort,
+      q: a.q,
+      limit: a.limit,
+      offset: a.offset
+    }
+  });
+  return {
+    conversations: r.conversations ?? [],
+    total: Number(r.total ?? 0),
+    limit: Number(r.limit ?? a.limit),
+    offset: Number(r.offset ?? a.offset),
+    hasMore: Boolean(r.hasMore)
+  };
+}
+var path = (cid, rest = "") => `/v1/conversations/${encodeURIComponent(cid)}${rest}`;
+async function patch(api, cid, body) {
+  const r = await api.request(
+    "PATCH",
+    path(cid),
+    { body }
+  );
+  return {
+    conversation: r.conversation,
+    changes: r.changes ?? []
+  };
+}
+var READ = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var CHANGE = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
+};
+var ROUTING_FIELDS = [
+  "source",
+  "project",
+  "widget",
+  "connection",
+  "page_url",
+  "page_domain",
+  "customer_email",
+  "customer_email_domain",
+  "message",
+  "subject",
+  "tags",
+  "priority",
+  "language"
+];
+var ROUTING_OPERATORS = [
+  "equals",
+  "not_equals",
+  "contains",
+  "not_contains",
+  "starts_with",
+  "ends_with",
+  "matches"
+];
+var routingConditions = z.object({
+  match: z.enum(["all", "any"]).describe("all = every condition holds, any = one is enough"),
+  conditions: z.array(
+    z.object({
+      field: z.enum(ROUTING_FIELDS),
+      operator: z.enum(ROUTING_OPERATORS),
+      value: z.union([z.string(), z.array(z.string())]).describe(
+        "A value, or a list (positive operators: any matches; negative: none does). Case-insensitive; matches uses * and ? wildcards."
+      )
+    })
+  ).max(50).describe("Empty = matches every new conversation (catch-all)")
+}).describe(
+  'Which new conversations the rule catches, tested on the first message, e.g. { "match": "any", "conditions": [{ "field": "message", "operator": "contains", "value": ["refund", "invoice"] }] }'
+);
+var ruleFields = {
+  name: z.string().trim().min(1).max(255).describe("Rule name"),
+  targetChannelId: z.string().regex(/^[A-Z0-9]{2,30}$/, "a Slack channel ID like C0123ABCD").describe("Slack channel ID to post matching conversations to"),
+  conditions: routingConditions,
+  projectId: id("Project (default: the oldest project)").optional(),
+  widgetId: id("Widget").nullable().optional(),
+  integrationId: id("Integration (default: the Slack workspace)").optional(),
+  assignToUserId: id("Teammate to assign matching conversations to").nullable().optional(),
+  isActive: z.boolean().optional().describe("Default true"),
+  priority: z.number().int().min(-1e6).max(1e6).optional().describe("Higher runs first (default: after every rule)")
+};
+var rule = z.looseObject({
+  id: z.string(),
+  name: z.string(),
+  priority: z.number(),
+  is_active: z.boolean(),
+  target_channel_id: z.string()
+});
+var INBOX_TOOLS = [
+  defineTool({
+    name: "list_conversations",
+    title: "List conversations",
+    description: "List support conversations, most recent activity first, filtered by status, priority, assignee, project, tag, source, last update or AI triage (intent/urgency). Each row has the customer, assignee, needsReply (the customer spoke last) and a preview of the latest message. Use get_conversation for the thread. Needs the inbox:read (or read) scope.",
+    scope: "inbox:read",
+    endpoint: "GET /v1/conversations",
+    inputSchema: z.object({ ...listFilters, ...paging }),
+    outputSchema: listOutput,
+    annotations: READ,
+    handler: (api, a) => list(api, a)
+  }),
+  defineTool({
+    name: "search_conversations",
+    title: "Search conversations",
+    description: "Find conversations whose subject, customer name or email, or any message contains the text (case-insensitive), with the same filters as list_conversations. Needs the inbox:read (or read) scope.",
+    scope: "inbox:read",
+    endpoint: "GET /v1/conversations?q=",
+    inputSchema: z.object({
+      query: z.string().trim().min(1).max(200).describe("Text to look for"),
+      ...listFilters,
+      ...paging
+    }),
+    outputSchema: listOutput,
+    annotations: READ,
+    handler: (api, { query, ...a }) => list(api, { ...a, q: query })
+  }),
+  defineTool({
+    name: "get_conversation",
+    title: "Get conversation",
+    description: "Read one conversation with its full thread: customer, agent, system and bot messages in order, internal notes included (isInternal: true, never seen by the customer), plus status, priority, tags, assignee, customer, triage and its Slack thread. Needs the inbox:read (or read) scope.",
+    scope: "inbox:read",
+    endpoint: "GET /v1/conversations/:id",
+    inputSchema: z.object({ conversationId }),
+    outputSchema: z.object({
+      conversation: z.looseObject({
+        id: z.string(),
+        status: z.string(),
+        messages: z.array(loose)
+      })
+    }),
+    annotations: READ,
+    handler: async (api, { conversationId: cid }) => {
+      const r = await api.request("GET", path(cid));
+      return { conversation: r.conversation };
+    }
+  }),
+  defineTool({
+    name: "reply_to_conversation",
+    title: "Reply to conversation",
+    description: 'Send a reply to the customer, as this API key (shown as "<key name> (agent)"). It reaches the customer like a dashboard reply (chat widget, email, SMS, ...) and is mirrored to the Slack thread; an open conversation becomes pending. Confirm the text with the user before sending. For a note only the team sees, use add_internal_note. Needs the inbox:write scope.',
+    scope: "inbox:write",
+    endpoint: "POST /v1/conversations/:id/reply",
+    inputSchema: z.object({
+      conversationId,
+      content: z.string().trim().min(1).max(1e4).describe("Reply text, as the customer will read it")
+    }),
+    outputSchema: z.object({
+      message: z.looseObject({ id: z.string() }),
+      conversationStatus: z.string(),
+      slack: slackOutcome
+    }),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    handler: async (api, { conversationId: cid, content }) => {
+      const r = await api.request("POST", path(cid, "/reply"), {
+        body: { content }
+      });
+      return {
+        message: r.message,
+        conversationStatus: String(r.conversationStatus ?? ""),
+        slack: String(r.slack ?? "")
+      };
+    }
+  }),
+  defineTool({
+    name: "add_internal_note",
+    title: "Add internal note",
+    description: "Add an internal note to a conversation: posted in its Slack thread for the team and kept in the conversation, never sent to the customer. Use it for findings, handoffs and suggested replies. Needs the inbox:write scope.",
+    scope: "inbox:write",
+    endpoint: "POST /v1/conversations/:id/notes",
+    inputSchema: z.object({
+      conversationId,
+      content: z.string().trim().min(1).max(1e4).describe("Note text")
+    }),
+    outputSchema: z.object({
+      note: z.looseObject({ id: z.string() }),
+      slack: slackOutcome
+    }),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    handler: async (api, { conversationId: cid, content }) => {
+      const r = await api.request("POST", path(cid, "/notes"), {
+        body: { content }
+      });
+      return { note: r.note, slack: String(r.slack ?? "") };
+    }
+  }),
+  defineTool({
+    name: "assign_conversation",
+    title: "Assign conversation",
+    description: "Assign a conversation to a teammate (by user ID or email; owners, admins and agents, not viewers), or unassign it with null. The teammate is notified, and the change shows in the timeline and Slack. Needs the inbox:write scope.",
+    scope: "inbox:write",
+    endpoint: "PATCH /v1/conversations/:id",
+    inputSchema: z.object({
+      conversationId,
+      assignee: z.string().min(1).max(255).nullable().describe("User ID or email of the teammate, or null to unassign")
+    }),
+    outputSchema: changeOutput,
+    annotations: CHANGE,
+    handler: (api, { conversationId: cid, assignee }) => patch(
+      api,
+      cid,
+      assignee === null ? { assigneeId: null } : assignee.includes("@") ? { assigneeEmail: assignee } : { assigneeId: assignee }
+    )
+  }),
+  defineTool({
+    name: "tag_conversation",
+    title: "Tag conversation",
+    description: "Add or remove tags on a conversation, or replace them all with `set`. Tags are lowercased; at most 20. Needs the inbox:write scope.",
+    scope: "inbox:write",
+    endpoint: "PATCH /v1/conversations/:id",
+    inputSchema: z.object({
+      conversationId,
+      add: tags.optional().describe("Tags to add"),
+      remove: tags.optional().describe("Tags to remove"),
+      set: tags.optional().describe("Replace every tag with these ([] clears them)")
+    }),
+    outputSchema: changeOutput,
+    annotations: CHANGE,
+    handler: (api, { conversationId: cid, add, remove, set }) => {
+      if (!add?.length && !remove?.length && !set) {
+        throw new ToolError("Pass tags to add, remove, or set.");
+      }
+      return patch(api, cid, {
+        ...set ? { tags: set } : {},
+        ...add?.length ? { addTags: add } : {},
+        ...remove?.length ? { removeTags: remove } : {}
+      });
+    }
+  }),
+  defineTool({
+    name: "close_conversation",
+    title: "Close conversation",
+    description: "Close a conversation (or mark it resolved). Nothing is sent to the customer; the change shows in the timeline and the Slack root post. Reply first if the customer should hear back. Needs the inbox:write scope.",
+    scope: "inbox:write",
+    endpoint: "PATCH /v1/conversations/:id",
+    inputSchema: z.object({
+      conversationId,
+      status: z.enum(["closed", "resolved"]).default("closed").describe("closed (default) or resolved")
+    }),
+    outputSchema: changeOutput,
+    annotations: CHANGE,
+    handler: (api, { conversationId: cid, status }) => patch(api, cid, { status })
+  }),
+  defineTool({
+    name: "reopen_conversation",
+    title: "Reopen conversation",
+    description: "Reopen a closed or resolved conversation (status open). Needs the inbox:write scope.",
+    scope: "inbox:write",
+    endpoint: "PATCH /v1/conversations/:id",
+    inputSchema: z.object({ conversationId }),
+    outputSchema: changeOutput,
+    annotations: CHANGE,
+    handler: (api, { conversationId: cid }) => patch(api, cid, { status: "open" })
+  }),
+  defineTool({
+    name: "get_analytics_summary",
+    title: "Get analytics summary",
+    description: "Support KPIs for a period (default the last 30 days): conversations started and resolved, median first-response and resolution times, messages in and out, each with the previous period; plus the inbox right now (open, pending, unassigned, urgent, awaiting a reply). Needs the analytics:read (or read) scope.",
+    scope: "analytics:read",
+    endpoint: "GET /v1/analytics/summary",
+    inputSchema: z.object({
+      days: z.number().int().min(1).max(366).optional().describe("Period length in days, ending today (default 30)"),
+      from: z.iso.date().optional().describe("First day, YYYY-MM-DD"),
+      to: z.iso.date().optional().describe("Last day, YYYY-MM-DD"),
+      tz: z.string().max(64).optional().describe("IANA time zone for day boundaries (default UTC)"),
+      projectId: id("Project").optional()
+    }),
+    outputSchema: z.looseObject({ range: loose, kpis: loose, inbox: loose }),
+    annotations: READ,
+    handler: async (api, args) => api.request(
+      "GET",
+      "/v1/analytics/summary",
+      { query: args }
+    )
+  }),
+  defineTool({
+    name: "list_routing_rules",
+    title: "List routing rules",
+    description: "List the routing rules in evaluation order (highest priority first): which new conversations each one sends to which Slack channel, and who it assigns. Needs the routing:write, inbox:read or read scope.",
+    scope: "routing:read",
+    endpoint: "GET /v1/routing-rules",
+    inputSchema: z.object({}),
+    outputSchema: z.object({ rules: z.array(rule) }),
+    annotations: READ,
+    handler: async (api) => {
+      const r = await api.request(
+        "GET",
+        "/v1/routing-rules"
+      );
+      return { rules: r.routing_rules ?? [] };
+    }
+  }),
+  defineTool({
+    name: "create_routing_rule",
+    title: "Create routing rule",
+    description: "Create a routing rule: new conversations whose first message matches `conditions` are posted to `targetChannelId` instead of the default channel (and optionally assigned). It runs after the existing rules unless `priority` is given. Confirm with the user first. Needs the routing:write scope.",
+    scope: "routing:write",
+    endpoint: "POST /v1/routing-rules",
+    inputSchema: z.object(ruleFields),
+    outputSchema: z.object({ rule }),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false
+    },
+    handler: async (api, body) => {
+      const r = await api.request(
+        "POST",
+        "/v1/routing-rules",
+        { body }
+      );
+      return { rule: r.routing_rule };
+    }
+  }),
+  defineTool({
+    name: "update_routing_rule",
+    title: "Update routing rule",
+    description: "Change a routing rule (from list_routing_rules); omitted fields keep their value, and `conditions` replaces the whole condition group. Use isActive: false to pause a rule. Needs the routing:write scope.",
+    scope: "routing:write",
+    endpoint: "PATCH /v1/routing-rules/:id",
+    inputSchema: z.object({
+      ruleId: id("Routing rule"),
+      name: ruleFields.name.optional(),
+      targetChannelId: ruleFields.targetChannelId.optional(),
+      conditions: routingConditions.optional(),
+      projectId: ruleFields.projectId,
+      widgetId: ruleFields.widgetId,
+      integrationId: ruleFields.integrationId,
+      assignToUserId: ruleFields.assignToUserId,
+      isActive: ruleFields.isActive,
+      priority: ruleFields.priority
+    }),
+    outputSchema: z.object({ rule }),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
+    handler: async (api, { ruleId, ...body }) => {
+      if (Object.values(body).every((v) => v === void 0)) {
+        throw new ToolError("Pass at least one field to change.");
+      }
+      const r = await api.request(
+        "PATCH",
+        `/v1/routing-rules/${encodeURIComponent(ruleId)}`,
+        { body }
+      );
+      return { rule: r.routing_rule };
+    }
+  }),
+  defineTool({
+    name: "delete_routing_rule",
+    title: "Delete routing rule",
+    description: "Delete a routing rule for good. To stop it temporarily, use update_routing_rule with isActive: false instead. Confirm with the user first. Needs the routing:write scope.",
+    scope: "routing:write",
+    endpoint: "DELETE /v1/routing-rules/:id",
+    inputSchema: z.object({ ruleId: id("Routing rule") }),
+    outputSchema: z.object({ deleted: z.boolean(), ruleId: z.string() }),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    },
+    handler: async (api, { ruleId }) => {
+      await api.request(
+        "DELETE",
+        `/v1/routing-rules/${encodeURIComponent(ruleId)}`
+      );
+      return { deleted: true, ruleId };
+    }
+  })
+];
+var INBOX_TOOL_NAMES = INBOX_TOOLS.map((t) => t.name);
+function getInboxTool(name) {
+  return INBOX_TOOLS.find((t) => t.name === name);
+}
+async function runInboxTool(api, name, args) {
+  const tool = getInboxTool(name);
+  if (!tool) throw new ToolError(`Unknown inbox tool "${name}"`);
+  const parsed = tool.inputSchema.safeParse(args ?? {});
+  if (!parsed.success) {
+    throw new ToolError(
+      `Invalid arguments for ${name}: ${parsed.error.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; ")}`
+    );
+  }
+  return await tool.handler(api, parsed.data);
+}
+function inboxToolsAsJsonSchema(filter = () => true) {
+  return INBOX_TOOLS.filter(filter).map((t) => ({
+    name: t.name,
+    description: t.description,
+    parameters: z.toJSONSchema(t.inputSchema, { io: "input" })
+  }));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CONVERSATION_PRIORITIES,
+  CONVERSATION_SORTS,
+  CONVERSATION_STATUSES,
+  INBOX_TOOLS,
+  INBOX_TOOL_NAMES,
+  ROUTING_FIELDS,
+  ROUTING_OPERATORS,
+  getInboxTool,
+  inboxToolsAsJsonSchema,
+  runInboxTool
+});
+//# sourceMappingURL=inbox.js.map