@rcs-campaigns/agent-toolkit 0.1.5

package/dist/openapi.js

@@ -0,0 +1,590 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toOpenApiPath = toOpenApiPath;
+exports.pathParamsOf = pathParamsOf;
+exports.buildOpenApiDocument = buildOpenApiDocument;
+/**
+ * The agent gateway's OpenAPI 3.1 document, generated from `TOOLS`.
+ *
+ * Why generated, and why HERE: before MSG-1833 the public API reference was
+ * hand-copied into two website repos and the capabilities catalog was a
+ * hand-written literal in `apps/server` — four lists of the same surface, none
+ * of which checked the others. A route reached the docs only if somebody
+ * remembered to retype it twice. This module makes the catalog the source: the
+ * server serves `buildOpenApiDocument(...)` at `GET /api/agent/openapi.json`,
+ * so a tool that exists is documented and a tool that does not, is not.
+ *
+ * Pure and dependency-free by design (no `zod-to-openapi`, none is in the repo):
+ * `ToolDef.inputSchema` is already JSON Schema, and OpenAPI 3.1 embeds JSON
+ * Schema 2020-12 directly, so each tool's schema mounts near-verbatim.
+ *
+ * The one non-obvious rule is the parameter/body split:
+ *   - a property whose name matches a `:param` in `path` becomes a PATH
+ *     parameter (always required);
+ *   - of the rest, GET/DELETE expand into QUERY parameters and
+ *     POST/PUT/PATCH become the `requestBody`.
+ * Every current tool satisfies the invariant this rests on (every `:param` is
+ * also an `inputSchema` property); the toolkit's own tests pin it so a future
+ * tool cannot break the generator silently.
+ */
+const tools_1 = require("./tools");
+// ---------------------------------------------------------------------------
+// Small pure helpers
+// ---------------------------------------------------------------------------
+/** `/conversations/:id` → `/conversations/{id}` (OpenAPI path templating). */
+function toOpenApiPath(path) {
+    return path.replace(/:([A-Za-z0-9_]+)/g, '{$1}');
+}
+/** The `:param` names in an Express-style path, in order. */
+function pathParamsOf(path) {
+    return [...path.matchAll(/:([A-Za-z0-9_]+)/g)].map((m) => m[1]);
+}
+/** `create_webhook` → `CreateWebhook`. */
+function pascal(name) {
+    return name
+        .split(/[_\-\s]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
+}
+/**
+ * The first sentence of a tool description, for `summary`.
+ *
+ * Tool descriptions are written for a model and run long (they carry the
+ * gotchas an agent needs). A generated reference still wants a one-line label
+ * per operation, and the full text stays as `description`.
+ */
+function firstSentence(text) {
+    const trimmed = text.trim();
+    const stop = trimmed.search(/\.(\s|$)/);
+    const first = stop === -1 ? trimmed : trimmed.slice(0, stop + 1);
+    return first.length > 160 ? `${first.slice(0, 157)}…` : first;
+}
+/** Group a tool under a docs tag by the resource its path names. */
+function tagFor(tool) {
+    const head = tool.path.split('/')[1] ?? '';
+    switch (head) {
+        case 'templates':
+        case 'marketplace':
+            return 'Templates';
+        case 'surveys':
+            return 'Surveys';
+        case 'messages':
+            return 'Messages';
+        case 'media':
+            return 'Media';
+        case 'audiences':
+            return 'Audiences';
+        case 'contacts':
+            return 'Contacts';
+        case 'conversations':
+            return 'Conversations';
+        case 'webhooks':
+            return 'Webhooks';
+        case 'usage':
+            return 'Usage';
+        default:
+            return 'Discovery';
+    }
+}
+/**
+ * The tools that reach a real phone and bill the org, and so sit behind the
+ * TIGHTER per-key limiter (`agentSendLimiter`) rather than the general one.
+ * Named here so the generated 429 description carries the number that actually
+ * applies to the operation rather than a single averaged claim.
+ */
+const TIGHTLY_LIMITED = new Set([
+    'send_message',
+    'send_survey',
+    'send_survey_test',
+    'reply'
+]);
+const RATE_LIMIT_NOTE = 'Rate limits: 300 requests/minute per IP before authentication, 120/minute per key after it.';
+const SEND_RATE_LIMIT_NOTE = 'Rate limits: 300 requests/minute per IP before authentication, 120/minute per key after it, and 30/minute per key on this operation — it reaches a real handset and bills the org.';
+// ---------------------------------------------------------------------------
+// Shared response shapes
+// ---------------------------------------------------------------------------
+/**
+ * The failure envelope every route emits (`middleware/errorHandler.ts`).
+ * One schema, referenced by every documented error status, so a client can
+ * write one error branch.
+ */
+const ERROR_SCHEMA = {
+    type: 'object',
+    required: ['success', 'error'],
+    properties: {
+        success: { type: 'boolean', enum: [false] },
+        error: { type: 'string', description: 'Human-readable failure reason.' },
+        details: {
+            description: 'Present on validation failures: the field-level issues that caused the 400.'
+        }
+    }
+};
+/** The `{ success: true, data }` envelope every successful route emits. */
+function successSchema() {
+    return {
+        type: 'object',
+        required: ['success', 'data'],
+        properties: {
+            success: { type: 'boolean', enum: [true] },
+            data: { description: 'The operation result.' }
+        }
+    };
+}
+const ERROR_STATUSES = [
+    ['400', 'The request failed validation.'],
+    ['401', 'Missing, malformed, revoked or expired credential.'],
+    ['403', 'The key lacks the required scope, or the org is paused.'],
+    ['404', 'No such resource in the calling org (a cross-org id reads as absent).'],
+    ['409', 'Refused by a business rule — e.g. the recipient has opted out.'],
+    ['429', RATE_LIMIT_NOTE],
+    ['500', 'Unexpected server error.']
+];
+function errorResponses(toolName) {
+    const out = {};
+    for (const [status, description] of ERROR_STATUSES) {
+        out[status] = {
+            description: status === '429' && TIGHTLY_LIMITED.has(toolName)
+                ? SEND_RATE_LIMIT_NOTE
+                : description,
+            content: {
+                'application/json': {
+                    schema: { $ref: '#/components/schemas/Error' }
+                }
+            }
+        };
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Webhook payloads
+// ---------------------------------------------------------------------------
+const ISO = { type: 'string', format: 'date-time' };
+const NULLABLE_STRING = { type: ['string', 'null'] };
+/**
+ * The `data` shape per event, mirroring `services/webhookEvents.ts` (the one
+ * place those payloads are built) and the flow/survey emitters.
+ */
+const WEBHOOK_DATA_SCHEMAS = {
+    'survey.completed': {
+        type: 'object',
+        properties: {
+            surveyId: { type: 'string' },
+            respondentNumber: { type: 'string', description: 'E.164.' },
+            answers: { type: 'object', additionalProperties: true },
+            completedAt: ISO
+        }
+    },
+    'response.received': {
+        type: 'object',
+        properties: {
+            surveyId: { type: 'string' },
+            respondentNumber: { type: 'string', description: 'E.164.' },
+            questionId: { type: 'string' },
+            questionIndex: { type: 'integer' },
+            answer: {},
+            complete: { type: 'boolean' }
+        }
+    },
+    'message.received': {
+        type: 'object',
+        properties: {
+            number: { type: 'string', description: 'E.164.' },
+            body: NULLABLE_STRING,
+            postbackData: {
+                ...NULLABLE_STRING,
+                description: 'Set when the contact tapped a button rather than typing.'
+            },
+            conversationId: NULLABLE_STRING,
+            occurredAt: ISO
+        }
+    },
+    'message.delivered': {
+        type: 'object',
+        properties: {
+            number: { type: 'string', description: 'E.164.' },
+            providerSid: NULLABLE_STRING,
+            broadcastId: NULLABLE_STRING,
+            status: { type: 'string', enum: ['DELIVERED', 'READ'] },
+            channel: NULLABLE_STRING,
+            fellBackToSms: { type: 'boolean' },
+            occurredAt: ISO,
+            source: { type: 'string', enum: ['callback', 'reconcile'] }
+        }
+    },
+    'message.failed': {
+        type: 'object',
+        properties: {
+            number: { type: 'string', description: 'E.164.' },
+            providerSid: NULLABLE_STRING,
+            broadcastId: NULLABLE_STRING,
+            errorCode: {
+                ...NULLABLE_STRING,
+                description: "The PROVIDER's own code, unmodified (e.g. 63049)."
+            },
+            errorMessage: NULLABLE_STRING,
+            channel: NULLABLE_STRING,
+            occurredAt: ISO,
+            source: { type: 'string', enum: ['callback', 'reconcile'] }
+        }
+    },
+    'broadcast.completed': {
+        type: 'object',
+        properties: {
+            broadcastId: { type: 'string' },
+            name: NULLABLE_STRING,
+            channel: NULLABLE_STRING,
+            status: { type: 'string', enum: ['SENT', 'FAILED'] },
+            stats: {
+                type: 'object',
+                properties: {
+                    total: { type: 'integer' },
+                    delivered: { type: 'integer' },
+                    read: { type: 'integer' },
+                    failed: { type: 'integer' },
+                    fellBackToSms: { type: 'integer' }
+                }
+            },
+            completedAt: ISO
+        }
+    },
+    'contact.opted_out': {
+        type: 'object',
+        properties: {
+            number: { type: 'string', description: 'E.164.' },
+            body: {
+                ...NULLABLE_STRING,
+                description: 'What the contact actually sent, so the opt-out is auditable.'
+            },
+            occurredAt: ISO
+        }
+    },
+    'action.tapped': {
+        type: 'object',
+        properties: {
+            number: { type: 'string', description: 'E.164.' },
+            postbackData: {
+                type: 'string',
+                description: 'The stable machine id the author set on the action.'
+            },
+            text: { ...NULLABLE_STRING, description: 'The chip label the recipient saw.' },
+            templateId: NULLABLE_STRING,
+            templateName: NULLABLE_STRING,
+            configuredUrl: {
+                ...NULLABLE_STRING,
+                description: 'The URL the author configured on the action. The platform never POSTs there itself — route on it from here.'
+            },
+            occurredAt: ISO
+        }
+    },
+    'flow.started': {
+        type: 'object',
+        properties: {
+            runId: { type: 'string' },
+            flowId: { type: 'string' },
+            flowName: NULLABLE_STRING,
+            kind: { type: 'string', description: 'BOT or JOURNEY.' },
+            number: { type: 'string', description: 'E.164.' },
+            trigger: { type: 'string' },
+            startedAt: ISO
+        }
+    },
+    'flow.completed': {
+        type: 'object',
+        properties: {
+            runId: { type: 'string' },
+            flowId: { type: 'string' },
+            number: { type: 'string', description: 'E.164.' },
+            status: { type: 'string' },
+            exitReason: { type: 'string' },
+            vars: {
+                type: 'object',
+                additionalProperties: true,
+                description: 'The variables the run collected.'
+            },
+            endedAt: ISO
+        }
+    },
+    'contact.lead_captured': {
+        type: 'object',
+        properties: {
+            number: { type: 'string', description: 'E.164.' },
+            contactId: NULLABLE_STRING,
+            source: {
+                type: 'string',
+                description: 'The normalised source tag — what `Contact.attributes.leadSource` holds.'
+            },
+            origin: {
+                type: 'string',
+                enum: ['widget', 'webhook'],
+                description: 'How the lead reached us: a click-to-chat `ref:` inbound, or the lead webhook. The shape is identical either way.'
+            },
+            firstName: NULLABLE_STRING,
+            lastName: NULLABLE_STRING,
+            email: NULLABLE_STRING,
+            optInText: {
+                ...NULLABLE_STRING,
+                description: 'The wording the person agreed to — the legal artefact, verbatim.'
+            },
+            optInTextIsSystemDefault: {
+                type: 'boolean',
+                description: 'TRUE when `optInText` is wording the PLATFORM composed because the source supplied none — NOT wording the person was shown. Most integrations map no opt-in wording at all, so this is the common case: file a flagged sentence differently from captured consent.'
+            },
+            flowStarted: { type: 'boolean' },
+            welcomeSent: { type: 'boolean' },
+            occurredAt: ISO
+        }
+    }
+};
+/** One `webhooks` entry: the signed envelope + headers a receiver must verify. */
+function webhookOperation(event) {
+    const data = WEBHOOK_DATA_SCHEMAS[event] ?? {
+        type: 'object',
+        additionalProperties: true,
+        description: 'Event payload. This event has no published shape yet — inspect a delivery.'
+    };
+    return {
+        post: {
+            operationId: `webhook_${event.replace(/[^A-Za-z0-9]+/g, '_')}`,
+            summary: `${event} event`,
+            description: `The platform POSTs this to every active endpoint subscribed to \`${event}\`. ` +
+                'Verify `X-RCS-Signature` against the RAW body before trusting it. ' +
+                'Respond 2xx to acknowledge; anything else is retried up to 5 attempts with a 1m/5m/25m/60m/60m backoff, and a receiver slower than 8s is aborted.',
+            parameters: [
+                {
+                    name: 'X-RCS-Signature',
+                    in: 'header',
+                    required: true,
+                    schema: { type: 'string' },
+                    description: 't=<unixSeconds>,v1=<hex HMAC-SHA256 of "<t>.<rawBody>"> using the endpoint signing secret.'
+                },
+                {
+                    name: 'X-RCS-Event',
+                    in: 'header',
+                    required: true,
+                    schema: { type: 'string', enum: [event] },
+                    description: 'The event type.'
+                },
+                {
+                    name: 'X-RCS-Delivery',
+                    in: 'header',
+                    required: true,
+                    schema: { type: 'string' },
+                    description: 'Unique delivery id — use it as the idempotency key.'
+                }
+            ],
+            requestBody: {
+                required: true,
+                content: {
+                    'application/json': {
+                        schema: {
+                            type: 'object',
+                            required: ['id', 'type', 'createdAt', 'data'],
+                            properties: {
+                                id: { type: 'string', description: 'Event id (matches X-RCS-Delivery).' },
+                                type: { type: 'string', enum: [event] },
+                                createdAt: ISO,
+                                data
+                            }
+                        }
+                    }
+                }
+            },
+            responses: {
+                '2XX': { description: 'Acknowledged. Anything else is retried.' }
+            }
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// Operations
+// ---------------------------------------------------------------------------
+function parameterFor(name, schema, where, required) {
+    const { description, ...rest } = schema ?? {};
+    return {
+        name,
+        in: where,
+        required,
+        ...(description ? { description } : {}),
+        schema: rest
+    };
+}
+function operationFor(tool) {
+    const params = new Set(pathParamsOf(tool.path));
+    const properties = tool.inputSchema.properties ?? {};
+    const required = new Set(tool.inputSchema.required ?? []);
+    const hasBody = tool.method === 'POST' || tool.method === 'PUT' || tool.method === 'PATCH';
+    const parameters = [];
+    const bodyProps = {};
+    const bodyRequired = [];
+    for (const [name, raw] of Object.entries(properties)) {
+        const schema = (raw ?? {});
+        if (params.has(name)) {
+            // A path parameter is required by construction — the URL cannot be built
+            // without it, whatever the inputSchema happens to say.
+            parameters.push(parameterFor(name, schema, 'path', true));
+            continue;
+        }
+        if (hasBody) {
+            bodyProps[name] = schema;
+            if (required.has(name))
+                bodyRequired.push(name);
+        }
+        else {
+            parameters.push(parameterFor(name, schema, 'query', required.has(name)));
+        }
+    }
+    const successStatus = String(tool.successStatus ?? 200);
+    const operation = {
+        operationId: tool.name,
+        tags: [tagFor(tool)],
+        summary: firstSentence(tool.description),
+        description: tool.description,
+        ...(parameters.length ? { parameters } : {}),
+        responses: {
+            [successStatus]: {
+                description: 'Success.',
+                content: { 'application/json': { schema: successSchema() } }
+            },
+            ...errorResponses(tool.name)
+        }
+    };
+    // `(none)` is the scope string the catalog uses for the discovery endpoints.
+    // An empty `security` array is OpenAPI's way of saying "no requirement", and
+    // is the honest rendering of a route with no `requireScope`.
+    operation.security =
+        tool.scope === '(none)'
+            ? []
+            : [{ bearerAuth: [tool.scope] }, { oauth2: [tool.scope] }];
+    if (hasBody && Object.keys(bodyProps).length > 0) {
+        const schemaName = pascal(tool.name);
+        operation.requestBody = {
+            required: bodyRequired.length > 0,
+            content: {
+                'application/json': {
+                    schema: { $ref: `#/components/schemas/${schemaName}` }
+                }
+            }
+        };
+        operation['x-request-schema'] = schemaName;
+    }
+    return operation;
+}
+/**
+ * The component schema for a tool's request body — its `inputSchema` minus the
+ * properties that are carried in the URL. GET/DELETE tools get none: their
+ * whole input expands into parameters, so a component would be dead weight.
+ */
+function requestSchemaFor(tool) {
+    const hasBody = tool.method === 'POST' || tool.method === 'PUT' || tool.method === 'PATCH';
+    if (!hasBody)
+        return null;
+    const params = new Set(pathParamsOf(tool.path));
+    const properties = {};
+    for (const [name, schema] of Object.entries(tool.inputSchema.properties ?? {})) {
+        if (!params.has(name))
+            properties[name] = schema;
+    }
+    if (Object.keys(properties).length === 0)
+        return null;
+    const required = (tool.inputSchema.required ?? []).filter((name) => !params.has(name));
+    return {
+        type: 'object',
+        properties,
+        ...(required.length ? { required } : {}),
+        ...(tool.inputSchema.additionalProperties === false
+            ? { additionalProperties: false }
+            : {})
+    };
+}
+// ---------------------------------------------------------------------------
+// The document
+// ---------------------------------------------------------------------------
+/**
+ * Build the gateway's OpenAPI 3.1 document.
+ *
+ * `servers` is supplied by the caller because only the server knows which
+ * environment it is: a published spec whose host is a placeholder cannot be
+ * imported into Postman or a code generator without hand-editing, which is the
+ * exact defect this replaces.
+ */
+function buildOpenApiDocument(servers, options = {}) {
+    const events = options.webhookEvents ?? tools_1.WEBHOOK_EVENT_NAMES;
+    const paths = {};
+    const schemas = { Error: ERROR_SCHEMA };
+    for (const tool of tools_1.TOOLS) {
+        const url = toOpenApiPath(tool.path);
+        const item = (paths[url] ??= {});
+        const verb = tool.method.toLowerCase();
+        if (item[verb]) {
+            throw new Error(`Two tools claim ${tool.method} ${tool.path} (${item[verb].operationId} and ${tool.name})`);
+        }
+        item[verb] = operationFor(tool);
+        const requestSchema = requestSchemaFor(tool);
+        if (requestSchema)
+            schemas[pascal(tool.name)] = requestSchema;
+    }
+    const webhooks = {};
+    for (const event of events)
+        webhooks[event] = webhookOperation(event);
+    return {
+        openapi: '3.1.0',
+        info: {
+            title: 'RCS Campaigns agent gateway',
+            version: options.version ?? '1.0.0',
+            description: 'The machine-facing API behind the MCP server, the CLI and the skill chains. ' +
+                'Authenticate with a scoped `rcsk_live_…` agent key, or an OAuth 2.1 access token (`rcso_at_…`) from the remote MCP server. ' +
+                'Every response is the envelope `{ success: true, data }` or `{ success: false, error }`. ' +
+                'Generated from the shared tool catalog — the same list the MCP server and CLI run on — so it cannot drift from the implementation.',
+            license: { name: 'Proprietary', identifier: 'LicenseRef-Proprietary' }
+        },
+        servers,
+        // The default requirement; each operation restates its own scope, and the
+        // discovery endpoints override it with an empty array.
+        security: [{ bearerAuth: [] }, { oauth2: [] }],
+        tags: [
+            { name: 'Discovery', description: 'What this key may do, and this document.' },
+            { name: 'Templates', description: 'Author, render, submit and clone templates.' },
+            { name: 'Surveys', description: 'Author, submit, send and read conversational surveys.' },
+            { name: 'Messages', description: 'Send an approved template to a list of numbers.' },
+            { name: 'Conversations', description: 'Read threads, reply into them, hand them over.' },
+            { name: 'Contacts', description: 'The org-level person record behind every audience.' },
+            { name: 'Audiences', description: 'Saved contact lists.' },
+            { name: 'Webhooks', description: 'Subscribe to signed platform events.' },
+            { name: 'Media', description: 'Host an image on the platform bucket.' },
+            { name: 'Usage', description: 'Month-to-date metered usage.' }
+        ],
+        paths,
+        webhooks,
+        components: {
+            securitySchemes: {
+                bearerAuth: {
+                    type: 'http',
+                    scheme: 'bearer',
+                    description: 'A scoped agent key (`rcsk_live_…`), minted at Settings → API keys and shown exactly once. Send it as `Authorization: Bearer …`.'
+                },
+                oauth2: {
+                    type: 'oauth2',
+                    description: 'The remote MCP server is an OAuth 2.1 authorization server with PKCE and Dynamic Client Registration. Access tokens look like `rcso_at_…` and resolve to the same org + scopes as a key.',
+                    flows: {
+                        authorizationCode: {
+                            authorizationUrl: 'https://mcp.rcs-templates.com/oauth/authorize',
+                            tokenUrl: 'https://mcp.rcs-templates.com/oauth/token',
+                            refreshUrl: 'https://mcp.rcs-templates.com/oauth/token',
+                            scopes: Object.fromEntries([...new Set(tools_1.TOOLS.map((t) => t.scope))]
+                                .filter((scope) => scope !== '(none)')
+                                .sort()
+                                .map((scope) => [scope, scopeSummary(scope)]))
+                        }
+                    }
+                }
+            },
+            schemas
+        }
+    };
+}
+/** One line per scope for the OAuth flow's `scopes` map. */
+function scopeSummary(scope) {
+    const names = tools_1.TOOLS.filter((t) => t.scope === scope).map((t) => t.name);
+    return names.join(', ');
+}

package/dist/tools.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The shared agent tool catalog.
+ *
+ * One declarative list of the gateway's capabilities — name, description, the
+ * JSON-Schema for inputs (used verbatim as the MCP `inputSchema`), and a pure
+ * function that turns validated args into a gateway RequestSpec. Both the MCP
+ * server (tools/list + tools/call) and the CLI build on this list, so adding a
+ * capability means editing ONE place and both skins gain it.
+ */
+import { type Channel, type RequestSpec } from './client';
+/** The HTTP verbs the gateway routes are registered under. */
+export type ToolMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface ToolDef {
+    name: string;
+    description: string;
+    /** The gateway scope a key needs for this tool (informational/discovery). */
+    scope: string;
+    /**
+     * STATIC route metadata — the verb and the Express-param path this tool calls
+     * (`/conversations/:id`), relative to the gateway base.
+     *
+     * `toRequest` below builds a CONCRETE request for concrete args, so it can
+     * never answer "what shape is this endpoint?" without being invoked. These
+     * two fields can, which is what lets ONE catalog back the MCP server, the
+     * CLI, `GET /api/agent/capabilities`, the generated OpenAPI document, and the
+     * route-coverage test that fails CI when a gateway route has no entry here.
+     *
+     * The invariant the OpenAPI generator depends on, pinned by the toolkit's own
+     * tests: every `:param` in `path` is also a property of `inputSchema`.
+     */
+    method: ToolMethod;
+    path: string;
+    /**
+     * The status the route returns on success — 200 unless the call CREATES a
+     * row, which returns 201. Static for the same reason `method`/`path` are:
+     * the generated OpenAPI document has to name a success code, and guessing
+     * "POST ⇒ 201" would be wrong for `submit_template`, `send_survey` and every
+     * other POST-as-action on this gateway.
+     */
+    successStatus?: 200 | 201;
+    /** JSON Schema for the tool arguments (MCP inputSchema, draft-07 style). */
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+        additionalProperties?: boolean;
+    };
+    /** Build the HTTP request for these (already MCP-validated) args. */
+    toRequest: (args: Record<string, any>) => RequestSpec;
+}
+/**
+ * The outbound webhook event types an endpoint may subscribe to — THE list,
+ * not a copy of one.
+ *
+ * It lives here because this is the package both ends can reach: the toolkit
+ * is a standalone npm dependency and cannot import from `apps/server`, but
+ * `apps/server` already depends on the toolkit (`workspace:*`) for `TOOLS` and
+ * the OpenAPI generator, so the arrow only points one way. `services/webhooks.ts`
+ * re-exports this array as `WEBHOOK_EVENTS`; there is no second array to keep
+ * in step, and **adding an event means editing this one list**.
+ *
+ * It used to be hand-listed here and hand-listed again in the server, kept
+ * honest by an exact-equality test across the two packages. That test could
+ * only fail AFTER a merge — a branch adding an eleventh event to one list and
+ * a branch adding the enum to the other are each green alone and red together,
+ * and `deploy.yml` runs the server suite before deploying, so the desync would
+ * have blocked the backend deploy rather than merely CI. Deriving removes the
+ * failure mode instead of detecting it later.
+ *
+ * The values are persisted on `WebhookEndpoint.events`, so a name here is a
+ * contract with every endpoint already registered: ADD, never rename.
+ *
+ * `contact.lead_captured` (MSG-1832) is the eleventh, appended never renamed.
+ */
+export declare const WEBHOOK_EVENT_NAMES: readonly ["survey.completed", "response.received", "message.received", "message.delivered", "message.failed", "broadcast.completed", "contact.opted_out", "action.tapped", "flow.started", "flow.completed", "payment.completed", "payment.failed", "contact.lead_captured"];
+export declare const TOOLS: ToolDef[];
+/** Look up a tool by name. */
+export declare function findTool(name: string): ToolDef | undefined;
+/** Does this tool accept a `channel` argument at all? */
+export declare function acceptsChannel(tool: ToolDef): boolean;
+/**
+ * Fill in the skin's default channel for a call that accepts one and did not
+ * specify it.
+ *
+ * Both skins run the same catalog against the same gateway, so the only thing
+ * that should differ is which channel you get when you don't ask: the `wa` bins
+ * assume WhatsApp, the `rcs` bins stay silent and let the server fall back to
+ * the org's own brand channel. An explicit `channel` from the caller always
+ * wins, and tools that take no channel are returned untouched — so this can be
+ * applied unconditionally at the CLI/MCP boundary.
+ */
+export declare function withDefaultChannel(tool: ToolDef, args: Record<string, any>, defaultChannel?: Channel): Record<string, any>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAoB,KAAK,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5E,8DAA8D;AAC9D,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAErE,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;;OAYG;IACH,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC;IAC1B,4EAA4E;IAC5E,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;IACF,qEAAqE;IACrE,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,WAAW,CAAC;CACvD;AAmBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,mBAAmB,8QA+BtB,CAAC;AAEX,eAAO,MAAM,KAAK,EAAE,OAAO,EA4uC1B,CAAC;AAEF,8BAA8B;AAC9B,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAE1D;AAED,yDAAyD;AACzD,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAKrD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACzB,cAAc,CAAC,EAAE,OAAO,GACvB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAcrB"}