@rcs-campaigns/agent-toolkit 0.1.5

package/dist/tools.js

@@ -0,0 +1,1333 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOLS = exports.WEBHOOK_EVENT_NAMES = void 0;
+exports.findTool = findTool;
+exports.acceptsChannel = acceptsChannel;
+exports.withDefaultChannel = withDefaultChannel;
+/**
+ * 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.
+ */
+const client_1 = require("./client");
+/**
+ * Optional per-call channel, accepted by every tool that acts ON a channel.
+ *
+ * The gateway used to derive the channel from the org's signup brand alone, so
+ * a key belonging to a WhatsApp org could only ever drive the WhatsApp path —
+ * the RCS equivalents of these same tools were unreachable. Passing `channel`
+ * selects the path explicitly; the server validates it against the org's
+ * purchased add-on brands (403 when it is not entitled) and defaults to the
+ * org's own brand channel when omitted, so existing callers are unaffected.
+ */
+const CHANNEL_PROP = {
+    type: 'string',
+    enum: ['RCS', 'WHATSAPP'],
+    description: "Channel to act on (RCS or WHATSAPP). Defaults to your org's own brand channel; any other channel requires the matching add-on brand."
+};
+/**
+ * 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.
+ */
+exports.WEBHOOK_EVENT_NAMES = [
+    // Surveys (the original two).
+    'survey.completed',
+    'response.received',
+    // Messaging. These are what make the platform integrable at all — a CRM or
+    // a Zapier trigger reacting to real delivery, not just to survey answers.
+    'message.received',
+    'message.delivered',
+    'message.failed',
+    'broadcast.completed',
+    'contact.opted_out',
+    // A recipient tapped a `webhook` suggested action. Delivered here rather
+    // than by POSTing the author's per-template URL directly: this path is
+    // already signed, retried and logged, and it keeps arbitrary
+    // author-supplied outbound requests off the backend entirely.
+    'action.tapped',
+    // Bots and journeys (MSG-1827 / MSG-1808): a person entered a flow, and a
+    // run ended (with its exit reason and collected vars).
+    'flow.started',
+    'flow.completed',
+    // Payments in chat (MSG-1831). Fired ONLY from the signed Stripe Connect
+    // webhook handler — never from the request-payment route and never from the
+    // click path, because those know only that we ASKED, not that money moved.
+    // There is deliberately no `payment.expired`: a lapsed link is nothing to
+    // notify a CRM about.
+    'payment.completed',
+    'payment.failed',
+    // A lead reached us from outside (MSG-1832) — a click-to-chat `ref:` inbound
+    // or a third-party form POSTing the lead webhook. APPENDED, never renamed:
+    // this array is a contract with every stored WebhookEndpoint.events value.
+    'contact.lead_captured'
+];
+exports.TOOLS = [
+    {
+        name: 'capabilities',
+        description: 'Describe the gateway: tool catalog, the scopes this key holds, and pricing posture. Call first to plan what you may do.',
+        scope: '(none)',
+        method: 'GET',
+        path: '/capabilities',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false
+        },
+        toRequest: () => ({ method: 'GET', path: '/capabilities' })
+    },
+    {
+        name: 'search_templates',
+        description: 'Search the published RCS template marketplace. Returns normalized listings (id, name, rating, cloneCount, categoryKeys).',
+        scope: 'templates:read',
+        method: 'GET',
+        path: '/templates',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                q: {
+                    type: 'string',
+                    description: 'Free-text search over name + description.'
+                },
+                category: {
+                    type: 'string',
+                    description: 'MarketplaceCategory key, e.g. EVENTS.'
+                },
+                channel: { type: 'string', enum: ['RCS', 'WHATSAPP', 'SMS'] },
+                sort: { type: 'string', enum: ['rating', 'used'], default: 'rating' },
+                page: { type: 'number', minimum: 1 },
+                pageSize: { type: 'number', minimum: 1, maximum: 100 }
+            },
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'GET',
+            path: '/templates',
+            query: {
+                q: a.q,
+                category: a.category,
+                channel: a.channel,
+                sort: a.sort,
+                page: a.page,
+                pageSize: a.pageSize
+            }
+        })
+    },
+    {
+        name: 'get_template',
+        description: 'Fetch one template by id (a published marketplace listing or one your org owns).',
+        scope: 'templates:read',
+        method: 'GET',
+        path: '/templates/:id',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'GET',
+            path: `/templates/${encodeURIComponent(a.id)}`
+        })
+    },
+    {
+        name: 'render_template',
+        description: 'Validate a template and return the rendered RCS payload + variable-bound SMS/MMS fallback, without sending. Use to inspect before cloning/sending.',
+        scope: 'templates:read',
+        method: 'POST',
+        path: '/templates/:id/render',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                variables: {
+                    type: 'object',
+                    description: 'Merge fields ({{key}} -> value) to bind into the preview.',
+                    additionalProperties: { type: 'string' }
+                }
+            },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: `/templates/${encodeURIComponent(a.id)}/render`,
+            body: { variables: a.variables ?? {} }
+        })
+    },
+    {
+        name: 'create_template',
+        description: 'Create a template draft in your org. Compose a TemplateContent (text/card/carousel) with a REQUIRED non-empty smsFallback; the shared RCS validator gates it. Submit it (submit_template) and await provider approval before send_message for rich RCS; an unsubmitted template delivers as SMS fallback.',
+        scope: 'templates:write',
+        method: 'POST',
+        path: '/templates',
+        successStatus: 201,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                description: { type: 'string' },
+                channel: { type: 'string', enum: ['RCS', 'WHATSAPP', 'SMS'] },
+                category: {
+                    type: 'string',
+                    enum: ['MARKETING', 'UTILITY', 'AUTHENTICATION']
+                },
+                content: {
+                    type: 'object',
+                    description: 'TemplateContent. Must include a non-empty smsFallback. One of text/card/carousel is the primary body.'
+                },
+                tags: { type: 'array', items: { type: 'string' } }
+            },
+            required: ['name', 'content'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: '/templates',
+            body: {
+                name: a.name,
+                description: a.description,
+                channel: a.channel,
+                category: a.category,
+                content: a.content,
+                tags: a.tags
+            }
+        })
+    },
+    {
+        name: 'update_template',
+        description: 'Partially update a template your org owns: name, description, category, tags, knowledgeDoc, and content (re-validated by the shared RCS validator — a non-empty smsFallback is still required). Only the fields you pass change. Editing the CONTENT of an already-approved template invalidates that approval: submit_template it again and await approval, or it delivers as SMS fallback until then. Use get_template first to edit incrementally rather than overwriting blind.',
+        scope: 'templates:write',
+        method: 'PUT',
+        path: '/templates/:id',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                name: { type: 'string' },
+                description: { type: 'string' },
+                channel: {
+                    type: 'string',
+                    enum: ['RCS', 'WHATSAPP'],
+                    description: "Move the template to another channel. Requires the matching add-on brand; omit to leave it where it is."
+                },
+                category: {
+                    type: 'string',
+                    enum: ['MARKETING', 'UTILITY', 'AUTHENTICATION']
+                },
+                content: {
+                    type: 'object',
+                    description: 'Full replacement TemplateContent (not a deep merge). Must include a non-empty smsFallback.'
+                },
+                tags: { type: 'array', items: { type: 'string' } },
+                knowledgeDoc: { type: 'string' }
+            },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'PUT',
+            path: `/templates/${encodeURIComponent(a.id)}`,
+            body: {
+                name: a.name,
+                description: a.description,
+                channel: a.channel,
+                category: a.category,
+                content: a.content,
+                tags: a.tags,
+                knowledgeDoc: a.knowledgeDoc
+            }
+        })
+    },
+    {
+        name: 'duplicate_template',
+        description: 'Duplicate a template your org OWNS into a fresh private draft (e.g. to iterate a variant without touching the original). The copy keeps the content, channel, category, tags and knowledge base, but starts unsubmitted — it has no provider approval of its own until you submit_template it. For copying someone else\'s PUBLISHED marketplace listing, use clone_template instead.',
+        scope: 'templates:write',
+        method: 'POST',
+        path: '/templates/:id/duplicate',
+        successStatus: 201,
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: `/templates/${encodeURIComponent(a.id)}/duplicate`
+        })
+    },
+    {
+        name: 'delete_template',
+        description: 'Delete a template your org owns. IRREVERSIBLE, and it also removes the template from the provider (Twilio), so an approved template loses its approval and can no longer be sent. Broadcasts that already went out are unaffected. Prefer this only for drafts and abandoned iterations; ask the user before deleting anything they have submitted or sent.',
+        scope: 'templates:write',
+        method: 'DELETE',
+        path: '/templates/:id',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'DELETE',
+            path: `/templates/${encodeURIComponent(a.id)}`
+        })
+    },
+    {
+        name: 'clone_template',
+        description: 'Clone a published marketplace template into your org as a fresh private draft. Returns the new template. To deliver rich RCS rather than SMS fallback, submit_template it and await provider approval before send_message.',
+        scope: 'marketplace:clone',
+        method: 'POST',
+        path: '/marketplace/:id/clone',
+        successStatus: 201,
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: `/marketplace/${encodeURIComponent(a.id)}/clone`
+        })
+    },
+    {
+        name: 'submit_template',
+        description: 'Submit an org-owned template to the provider (Twilio) for approval. Returns the contentSid + approval status.',
+        scope: 'templates:submit',
+        method: 'POST',
+        path: '/templates/:id/submit',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: `/templates/${encodeURIComponent(a.id)}/submit`
+        })
+    },
+    {
+        name: 'send_message',
+        description: 'Send an org-owned template to a list of E.164 phone numbers (RCS-first with mandatory SMS/MMS fallback). Pass the template\'s blueprintId or id. The template sends as rich RCS only after submit_template + provider approval; until then it delivers as SMS fallback — the returned funnel\'s `fellBackToSms` count signals how many recipients got SMS instead of RCS. Bills your org. Returns the send funnel.',
+        scope: 'messages:send',
+        method: 'POST',
+        path: '/messages/send',
+        successStatus: 201,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                blueprintId: { type: 'string' },
+                to: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    minItems: 1,
+                    maxItems: 500
+                },
+                variables: { type: 'object', additionalProperties: { type: 'string' } },
+                name: { type: 'string' }
+            },
+            required: ['blueprintId', 'to'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: '/messages/send',
+            body: {
+                blueprintId: a.blueprintId,
+                to: a.to,
+                variables: a.variables,
+                name: a.name
+            }
+        })
+    },
+    // ── Survey tools (the conversational-survey surface) ──
+    {
+        name: 'search_surveys',
+        description: 'List/search the surveys your org owns. Returns each survey with its recipients + responses counts.',
+        scope: 'surveys:read',
+        method: 'GET',
+        path: '/surveys',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                q: { type: 'string', description: 'Free-text search over the name.' },
+                status: {
+                    type: 'string',
+                    enum: ['DRAFT', 'SCHEDULED', 'ACTIVE', 'CLOSED']
+                },
+                page: { type: 'number', minimum: 1 },
+                pageSize: { type: 'number', minimum: 1, maximum: 100 }
+            },
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'GET',
+            path: '/surveys',
+            query: { q: a.q, status: a.status, page: a.page, pageSize: a.pageSize }
+        })
+    },
+    {
+        name: 'get_survey',
+        description: 'Fetch one survey your org owns by id (its full definition).',
+        scope: 'surveys:read',
+        method: 'GET',
+        path: '/surveys/:id',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'GET',
+            path: `/surveys/${encodeURIComponent(a.id)}`
+        })
+    },
+    {
+        name: 'render_survey',
+        description: 'Preview a survey the way a respondent sees it: the text body + RCS chip titles for each question. Side-effect-free.',
+        scope: 'surveys:read',
+        method: 'POST',
+        path: '/surveys/:id/render',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: `/surveys/${encodeURIComponent(a.id)}/render`
+        })
+    },
+    {
+        name: 'create_survey',
+        description: 'Create a survey draft in your org. Provide a SurveyDefinition (intro? + questions[] of type rating/single_select/text/comment); the shared validator gates it. PICTURES: every question should carry an `imageUrl`, and the definition should carry `headerImageUrl` (start picture) and `outroImageUrl` (finish picture). If the user provided no pictures, WEB-SEARCH for suitable, relevant images first and pass their https URLs — the server automatically re-hosts every image onto the platform GCS bucket, so external URLs are safe to pass and never hotlinked.',
+        scope: 'surveys:write',
+        method: 'POST',
+        path: '/surveys',
+        successStatus: 201,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                description: { type: 'string' },
+                definition: {
+                    type: 'object',
+                    description: 'SurveyDefinition: { intro?, outro?, questions: [{ questionId, prompt, type, options?, minRating?, maxRating?, required? }] }.'
+                },
+                startDate: { type: 'string', description: 'ISO date; schedules the survey.' },
+                endDate: { type: 'string' },
+                timezone: { type: 'string' },
+                languageCode: { type: 'array', items: { type: 'string' } },
+                isPreferencesSurvey: { type: 'boolean' },
+                channel: CHANNEL_PROP
+            },
+            required: ['name', 'definition'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: '/surveys',
+            body: {
+                name: a.name,
+                description: a.description,
+                definition: a.definition,
+                startDate: a.startDate,
+                endDate: a.endDate,
+                timezone: a.timezone,
+                languageCode: a.languageCode,
+                isPreferencesSurvey: a.isPreferencesSurvey,
+                channel: a.channel
+            }
+        })
+    },
+    {
+        name: 'clone_survey',
+        description: 'Duplicate an org-owned survey into a fresh DRAFT (e.g. to iterate a variant). Returns the new survey.',
+        scope: 'marketplace:clone',
+        method: 'POST',
+        path: '/surveys/:id/clone',
+        successStatus: 201,
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: `/surveys/${encodeURIComponent(a.id)}/clone`
+        })
+    },
+    {
+        name: 'delete_survey',
+        description: 'Delete a survey your org owns. IRREVERSIBLE: its responses and sessions are deleted with it, so any results you have not already read are lost. Ask the user before deleting a survey that has been sent or has responses — read get_results first if in doubt.',
+        scope: 'surveys:write',
+        method: 'DELETE',
+        path: '/surveys/:id',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'DELETE',
+            path: `/surveys/${encodeURIComponent(a.id)}`
+        })
+    },
+    {
+        name: 'submit_survey',
+        description: "Submit a survey for provider approval: on RCS its button-question templates, on WhatsApp its single Flow template. Returns the survey with the resulting approval state.",
+        scope: 'surveys:submit',
+        method: 'POST',
+        path: '/surveys/:id/submit',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' }, channel: CHANNEL_PROP },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: `/surveys/${encodeURIComponent(a.id)}/submit`,
+            body: { channel: a.channel }
+        })
+    },
+    {
+        name: 'send_survey',
+        description: 'Send a survey to explicit E.164 numbers (the CRM-triggered single-customer send) and/or saved audiences. Flips the survey ACTIVE. Bills your org. Returns { recipients, sent }.',
+        scope: 'surveys:send',
+        method: 'POST',
+        path: '/surveys/:id/send',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                to: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    maxItems: 500,
+                    description: 'E.164 destinations, e.g. ["+15551234567"].'
+                },
+                audienceIds: { type: 'array', items: { type: 'string' }, maxItems: 100 },
+                channel: CHANNEL_PROP
+            },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: `/surveys/${encodeURIComponent(a.id)}/send`,
+            body: { to: a.to, audienceIds: a.audienceIds, channel: a.channel }
+        })
+    },
+    {
+        name: 'update_survey',
+        description: 'Partially update a survey: name, description, definition (re-validated; editing a submitted WhatsApp survey requires resubmission), startDate/endDate, and audienceIds — setting audienceIds on a future-dated survey schedules the send to fire automatically at startDate. PICTURES: as with create_survey, keep every question\'s `imageUrl` plus `headerImageUrl`/`outroImageUrl` populated — web-search for images when none were provided; the server re-hosts all image URLs onto GCS.',
+        scope: 'surveys:write',
+        method: 'PATCH',
+        path: '/surveys/:id',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                name: { type: 'string' },
+                description: { type: 'string' },
+                definition: { type: 'object' },
+                status: {
+                    type: 'string',
+                    enum: ['DRAFT', 'SCHEDULED', 'ACTIVE', 'CLOSED']
+                },
+                startDate: { type: 'string' },
+                endDate: { type: 'string' },
+                audienceIds: { type: 'array', items: { type: 'string' } },
+                channel: CHANNEL_PROP
+            },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'PATCH',
+            path: `/surveys/${encodeURIComponent(a.id)}`,
+            body: {
+                name: a.name,
+                description: a.description,
+                definition: a.definition,
+                status: a.status,
+                startDate: a.startDate,
+                endDate: a.endDate,
+                audienceIds: a.audienceIds,
+                channel: a.channel
+            }
+        })
+    },
+    {
+        name: 'list_survey_sends',
+        description: "A survey's outbound send log (live + test sends), newest first, with per-message delivery status — including failed/stubbed attempts and the reason they did not deliver.",
+        scope: 'surveys:read',
+        method: 'GET',
+        path: '/surveys/:id/sends',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'GET',
+            path: `/surveys/${encodeURIComponent(a.id)}/sends`
+        })
+    },
+    {
+        name: 'send_survey_test',
+        description: 'Send a one-off TEST of the survey to a single E.164 number (does not change status or audiences). Check list_survey_sends afterwards for the delivery outcome.',
+        scope: 'surveys:send',
+        method: 'POST',
+        path: '/surveys/:id/send-test',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                number: { type: 'string', description: 'E.164, e.g. +15551234567.' },
+                channel: CHANNEL_PROP
+            },
+            required: ['id', 'number'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: `/surveys/${encodeURIComponent(a.id)}/send-test`,
+            body: { number: a.number, channel: a.channel }
+        })
+    },
+    {
+        name: 'get_results',
+        description: 'Read a survey’s aggregated results: per-question option counts / rating averages / text samples + completion totals (multi-part questions aggregate per part; free-text answers are auto-translated to English).',
+        scope: 'results:read',
+        method: 'GET',
+        path: '/surveys/:id/results',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'GET',
+            path: `/surveys/${encodeURIComponent(a.id)}/results`
+        })
+    },
+    {
+        name: 'upload_media',
+        description: 'Store one picture on the platform GCS bucket and get its stable https URL — the only kind of URL survey/template media should use. Pass EITHER the image inline (base64 + mime) OR an https sourceUrl the server fetches and re-hosts (use this for web-searched pictures).',
+        scope: 'surveys:write',
+        method: 'POST',
+        path: '/media/upload',
+        successStatus: 201,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                base64: {
+                    type: 'string',
+                    description: 'Raw base64 or data: URL of the image bytes.'
+                },
+                mime: {
+                    type: 'string',
+                    description: 'Image MIME type (required with base64), e.g. image/png.'
+                },
+                filename: { type: 'string' },
+                sourceUrl: {
+                    type: 'string',
+                    description: 'https image URL to fetch and re-host onto GCS.'
+                }
+            },
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: '/media/upload',
+            body: {
+                base64: a.base64,
+                mime: a.mime,
+                filename: a.filename,
+                sourceUrl: a.sourceUrl
+            }
+        })
+    },
+    {
+        name: 'get_knowledge',
+        description: "Read a template's knowledge base: the grounding document text plus whether answering is enabled. Use before set_knowledge to edit a doc incrementally instead of overwriting it blind.",
+        scope: 'templates:read',
+        method: 'GET',
+        path: '/templates/:id/knowledge',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'GET',
+            path: `/templates/${encodeURIComponent(a.id)}/knowledge`
+        })
+    },
+    {
+        name: 'set_knowledge',
+        description: 'Set/replace a template\'s knowledge base: the grounding document AI answers are generated from when recipients reply. Include operating instructions in the doc itself — e.g. "Any question not answered by this document must be answered exactly: …". Setting a doc re-enables answering.',
+        scope: 'templates:write',
+        method: 'PUT',
+        path: '/templates/:id/knowledge',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                doc: {
+                    type: 'string',
+                    description: 'The knowledge document (markdown or plain text).'
+                }
+            },
+            required: ['id', 'doc'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'PUT',
+            path: `/templates/${encodeURIComponent(a.id)}/knowledge`,
+            body: { doc: a.doc }
+        })
+    },
+    {
+        name: 'delete_knowledge',
+        description: 'Delete a template\'s knowledge base document.',
+        scope: 'templates:write',
+        method: 'DELETE',
+        path: '/templates/:id/knowledge',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'DELETE',
+            path: `/templates/${encodeURIComponent(a.id)}/knowledge`
+        })
+    },
+    {
+        name: 'enable_knowledge',
+        description: 'Enable knowledge answering on a template (the doc is used again).',
+        scope: 'templates:write',
+        method: 'POST',
+        path: '/templates/:id/knowledge/enable',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: `/templates/${encodeURIComponent(a.id)}/knowledge/enable`
+        })
+    },
+    {
+        name: 'disable_knowledge',
+        description: 'Disable knowledge answering on a template WITHOUT deleting the doc (pause).',
+        scope: 'templates:write',
+        method: 'POST',
+        path: '/templates/:id/knowledge/disable',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: `/templates/${encodeURIComponent(a.id)}/knowledge/disable`
+        })
+    },
+    {
+        name: 'get_usage',
+        description: 'Read your org’s month-to-date metered message usage.',
+        scope: 'usage:read',
+        method: 'GET',
+        path: '/usage',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false
+        },
+        toRequest: () => ({ method: 'GET', path: '/usage' })
+    },
+    // ── Audience tools (contact-list authoring, e.g. importing leads) ──
+    {
+        name: 'search_audiences',
+        description: 'List/search the audiences (saved contact lists) your org owns. Returns each audience with its name, source, and contactCount.',
+        scope: 'audiences:read',
+        method: 'GET',
+        path: '/audiences',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                q: { type: 'string', description: 'Free-text search over the name.' },
+                page: { type: 'number', minimum: 1 },
+                pageSize: { type: 'number', minimum: 1, maximum: 100 }
+            },
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'GET',
+            path: '/audiences',
+            query: { q: a.q, page: a.page, pageSize: a.pageSize }
+        })
+    },
+    {
+        name: 'get_audience',
+        description: 'Fetch one audience your org owns by id.',
+        scope: 'audiences:read',
+        method: 'GET',
+        path: '/audiences/:id',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'GET',
+            path: `/audiences/${encodeURIComponent(a.id)}`
+        })
+    },
+    {
+        name: 'list_audience_contacts',
+        description: "Paginated list of an audience's contacts. Use `q` to find someone in a large imported batch instead of paging through it — it matches on the server, over the whole audience, so it keeps working on lists too big to page.",
+        scope: 'audiences:read',
+        method: 'GET',
+        path: '/audiences/:id/contacts',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                q: {
+                    type: 'string',
+                    maxLength: 120,
+                    description: 'Free-text over number, names and email. A number matches however it is written — "(206) 300-0001" finds "+12063000001".'
+                },
+                page: { type: 'number', minimum: 1 },
+                pageSize: { type: 'number', minimum: 1, maximum: 200 }
+            },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'GET',
+            path: `/audiences/${encodeURIComponent(a.id)}/contacts`,
+            query: { q: a.q, page: a.page, pageSize: a.pageSize }
+        })
+    },
+    {
+        name: 'create_audience',
+        description: 'Create a saved audience (contact list) in your org, optionally seeded with contacts (e.g. leads parsed from a CSV). Every contact needs a reachable E.164-ish `number` — a contact with no valid number fails the whole create with a 400 (fix the row rather than silently dropping it). Use `attributes` for any extra CSV columns you want available as {{key}} merge fields later.',
+        scope: 'audiences:write',
+        method: 'POST',
+        path: '/audiences',
+        successStatus: 201,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                description: { type: 'string' },
+                source: { type: 'string', description: 'Free-text provenance, e.g. "Jaipur wedding planners leads.csv".' },
+                contacts: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            firstName: { type: 'string' },
+                            lastName: { type: 'string' },
+                            number: { type: 'string', description: 'Phone number; required for the contact to be reachable.' },
+                            email: { type: 'string' },
+                            attributes: { type: 'object', additionalProperties: { type: 'string' } }
+                        },
+                        additionalProperties: false
+                    }
+                }
+            },
+            required: ['name'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: '/audiences',
+            body: {
+                name: a.name,
+                description: a.description,
+                source: a.source,
+                contacts: a.contacts
+            }
+        })
+    },
+    {
+        name: 'import_contacts',
+        description: 'Append contacts to an existing audience (e.g. more leads from a later CSV batch). Same reachability rule as create_audience: every contact needs a valid `number` or the whole import 400s.',
+        scope: 'audiences:write',
+        method: 'POST',
+        path: '/audiences/:id/contacts',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                contacts: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            firstName: { type: 'string' },
+                            lastName: { type: 'string' },
+                            number: { type: 'string' },
+                            email: { type: 'string' },
+                            attributes: { type: 'object', additionalProperties: { type: 'string' } }
+                        },
+                        additionalProperties: false
+                    },
+                    minItems: 1
+                }
+            },
+            required: ['id', 'contacts'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: `/audiences/${encodeURIComponent(a.id)}/contacts`,
+            body: { contacts: a.contacts }
+        })
+    },
+    {
+        name: 'delete_audience',
+        description: 'Delete an audience and all of its contacts (org-scoped, irreversible).',
+        scope: 'audiences:write',
+        method: 'DELETE',
+        path: '/audiences/:id',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'DELETE',
+            path: `/audiences/${encodeURIComponent(a.id)}`
+        })
+    },
+    // ── Conversation tools (the Inbox: read a thread, answer it, hand it over) ──
+    {
+        name: 'list_conversations',
+        description: 'List the org\'s conversation threads (one per phone number), newest activity first. Archived threads are hidden. Filter by free text, unread, unassigned, a specific assignee, or the campaign a thread was messaged in.',
+        scope: 'conversations:read',
+        method: 'GET',
+        path: '/conversations',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                search: {
+                    type: 'string',
+                    description: 'Match the number or the resolved display name.'
+                },
+                unread: {
+                    type: 'boolean',
+                    description: 'Only threads with unanswered arrivals (unreadCount > 0). Org-wide, not per-viewer: a key is not a person and has no read state.'
+                },
+                unassigned: { type: 'boolean', description: 'Only threads nobody owns.' },
+                assignedTo: {
+                    type: 'string',
+                    description: 'Only threads owned by this Clerk user id.'
+                },
+                broadcastId: {
+                    type: 'string',
+                    description: 'Only threads this campaign was sent to.'
+                },
+                page: { type: 'number', minimum: 1 },
+                pageSize: { type: 'number', minimum: 1, maximum: 100 }
+            },
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'GET',
+            path: '/conversations',
+            query: {
+                search: a.search,
+                unread: a.unread,
+                unassigned: a.unassigned,
+                assignedTo: a.assignedTo,
+                broadcastId: a.broadcastId,
+                page: a.page,
+                pageSize: a.pageSize
+            }
+        })
+    },
+    {
+        name: 'get_conversation',
+        description: 'Read one thread in a single call: its meta, the most recent messages (ascending), the contact summary (marketing status, tags, audiences) and whether the WhatsApp 24h service window is open. Internal team notes are deliberately NOT included.',
+        scope: 'conversations:read',
+        method: 'GET',
+        path: '/conversations/:id',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                limit: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 200,
+                    default: 50,
+                    description: 'How many of the most recent messages to include.'
+                }
+            },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'GET',
+            path: `/conversations/${encodeURIComponent(a.id)}`,
+            query: { limit: a.limit }
+        })
+    },
+    {
+        name: 'reply',
+        description: 'Reply into a thread — free text (with an optional image) or an approved template. Reaches a real phone and bills your org. Every gate an operator hits applies unchanged: an opted-out number is refused (409), the org allowance is enforced, WhatsApp free text needs the 24h window open (an approved template otherwise), and an RCS send always carries its SMS fallback. When the thread has an outbound language set, free text is translated into it first, exactly as the human composer does.',
+        scope: 'conversations:write',
+        method: 'POST',
+        path: '/conversations/:id/reply',
+        successStatus: 201,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                kind: { type: 'string', enum: ['text', 'template'] },
+                text: {
+                    type: 'string',
+                    maxLength: 4096,
+                    description: 'kind=text: the body. May be empty when mediaUrl carries the message.'
+                },
+                mediaUrl: {
+                    type: 'string',
+                    description: 'kind=text: a public https image URL to attach.'
+                },
+                blueprintId: {
+                    type: 'string',
+                    description: "kind=template: the org template to send."
+                },
+                variables: {
+                    type: 'object',
+                    additionalProperties: { type: 'string' },
+                    description: 'kind=template: values for the template\'s {{variables}}.'
+                }
+            },
+            required: ['id', 'kind'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: `/conversations/${encodeURIComponent(a.id)}/reply`,
+            body: {
+                kind: a.kind,
+                text: a.text,
+                mediaUrl: a.mediaUrl,
+                blueprintId: a.blueprintId,
+                variables: a.variables
+            }
+        })
+    },
+    {
+        name: 'assign_conversation',
+        description: 'Give a thread an owner, or release it back to the pool with `userId: null`. The assignee is a bare Clerk user id and is NOT validated against the org roster — a stale id degrades to "assigned to someone who left", visibly, rather than to an outage in a one-field write.',
+        scope: 'conversations:write',
+        method: 'POST',
+        path: '/conversations/:id/assign',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                userId: {
+                    type: ['string', 'null'],
+                    description: 'Clerk user id to hand the thread to; null releases it.'
+                }
+            },
+            required: ['id', 'userId'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: `/conversations/${encodeURIComponent(a.id)}/assign`,
+            body: { userId: a.userId ?? null }
+        })
+    },
+    // ── Webhook tools (subscribe yourself to platform events) ──
+    {
+        name: 'list_webhooks',
+        description: "The org's registered outbound webhook endpoints. The signing secret is redacted — it is shown only once, by create_webhook.",
+        scope: 'webhooks:manage',
+        method: 'GET',
+        path: '/webhooks',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false
+        },
+        toRequest: () => ({ method: 'GET', path: '/webhooks' })
+    },
+    {
+        name: 'create_webhook',
+        description: 'Register an HTTPS endpoint to receive signed platform events. The response carries the signing `secret` EXACTLY ONCE — store it now; every later read redacts it and there is no way to retrieve it again. Each delivery is signed `X-RCS-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<rawBody>">`.',
+        scope: 'webhooks:manage',
+        method: 'POST',
+        path: '/webhooks',
+        successStatus: 201,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                url: { type: 'string', description: 'HTTPS endpoint to POST events to.' },
+                events: {
+                    type: 'array',
+                    minItems: 1,
+                    items: { type: 'string', enum: [...exports.WEBHOOK_EVENT_NAMES] },
+                    description: 'Event types to subscribe to.'
+                },
+                description: { type: 'string', maxLength: 200 }
+            },
+            required: ['url', 'events'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: '/webhooks',
+            body: { url: a.url, events: a.events, description: a.description }
+        })
+    },
+    {
+        name: 'update_webhook',
+        description: 'Update an endpoint\'s url, subscribed events, description, or active flag. Only the fields you pass change. The signing secret is never returned or rotated here.',
+        scope: 'webhooks:manage',
+        method: 'PUT',
+        path: '/webhooks/:id',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                url: { type: 'string' },
+                events: {
+                    type: 'array',
+                    minItems: 1,
+                    items: { type: 'string', enum: [...exports.WEBHOOK_EVENT_NAMES] }
+                },
+                description: { type: ['string', 'null'], maxLength: 200 },
+                active: { type: 'boolean' }
+            },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'PUT',
+            path: `/webhooks/${encodeURIComponent(a.id)}`,
+            body: {
+                url: a.url,
+                events: a.events,
+                description: a.description,
+                active: a.active
+            }
+        })
+    },
+    {
+        name: 'delete_webhook',
+        description: 'Remove a webhook endpoint. Its delivery history is deleted with it; anything still queued for it stops.',
+        scope: 'webhooks:manage',
+        method: 'DELETE',
+        path: '/webhooks/:id',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'DELETE',
+            path: `/webhooks/${encodeURIComponent(a.id)}`
+        })
+    },
+    {
+        name: 'test_webhook',
+        description: 'Fire a synthetic signed event at one endpoint to verify the receiver. Returns the delivery id and whether it was accepted.',
+        scope: 'webhooks:manage',
+        method: 'POST',
+        path: '/webhooks/:id/test',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'POST',
+            path: `/webhooks/${encodeURIComponent(a.id)}/test`
+        })
+    },
+    // ── Contact tools (the org-level person record behind every audience) ──
+    {
+        name: 'list_contacts',
+        description: "Search the org's contact records (one person per number, across every audience). Returns consent, opt-out, number verdict, marketing status, merge fields and tags.",
+        scope: 'contacts:read',
+        method: 'GET',
+        path: '/contacts',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                q: {
+                    type: 'string',
+                    maxLength: 120,
+                    description: 'Free-text over number, names and email.'
+                },
+                status: {
+                    type: 'string',
+                    enum: ['SUBSCRIBED', 'UNSUBSCRIBED', 'UNDELIVERABLE', 'UNKNOWN'],
+                    description: 'Marketing status: SUBSCRIBED (consent, not opted out), UNSUBSCRIBED (opted out — sticky), UNDELIVERABLE (number known unreachable), UNKNOWN (no consent on record).'
+                },
+                tag: { type: 'string', maxLength: 64 },
+                audienceId: {
+                    type: 'string',
+                    description: 'Only people who are members of this audience.'
+                },
+                page: { type: 'number', minimum: 1 },
+                pageSize: { type: 'number', minimum: 1, maximum: 100 }
+            },
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'GET',
+            path: '/contacts',
+            query: {
+                q: a.q,
+                status: a.status,
+                tag: a.tag,
+                audienceId: a.audienceId,
+                page: a.page,
+                pageSize: a.pageSize
+            }
+        })
+    },
+    {
+        name: 'get_contact',
+        description: 'Fetch one contact by its public contact id, with the audiences they belong to.',
+        scope: 'contacts:read',
+        method: 'GET',
+        path: '/contacts/:id',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'GET',
+            path: `/contacts/${encodeURIComponent(a.id)}`
+        })
+    },
+    {
+        name: 'update_contact',
+        description: "Correct a contact's names, email, merge fields (`attributes`, a whole-map replace) or tags. Consent and opt-out are deliberately NOT reachable from here — recording or clearing them is a compliance-sensitive action that stays with a human operator.",
+        scope: 'contacts:write',
+        method: 'PATCH',
+        path: '/contacts/:id',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                firstName: { type: ['string', 'null'], maxLength: 120 },
+                lastName: { type: ['string', 'null'], maxLength: 120 },
+                email: { type: ['string', 'null'], maxLength: 200 },
+                attributes: {
+                    type: ['object', 'null'],
+                    additionalProperties: { type: 'string' },
+                    description: 'Whole-map replace of the {{merge field}} values.'
+                },
+                tags: { type: 'array', items: { type: 'string' }, maxItems: 50 }
+            },
+            required: ['id'],
+            additionalProperties: false
+        },
+        toRequest: (a) => ({
+            method: 'PATCH',
+            path: `/contacts/${encodeURIComponent(a.id)}`,
+            body: {
+                firstName: a.firstName,
+                lastName: a.lastName,
+                email: a.email,
+                attributes: a.attributes,
+                tags: a.tags
+            }
+        })
+    }
+];
+/** Look up a tool by name. */
+function findTool(name) {
+    return exports.TOOLS.find((t) => t.name === name);
+}
+/** Does this tool accept a `channel` argument at all? */
+function acceptsChannel(tool) {
+    return Object.prototype.hasOwnProperty.call(tool.inputSchema.properties ?? {}, 'channel');
+}
+/**
+ * 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.
+ */
+function withDefaultChannel(tool, args, defaultChannel) {
+    if (!acceptsChannel(tool))
+        return args;
+    if (args.channel !== undefined && args.channel !== null) {
+        // An explicit channel wins — but a brand id typed in its place (legacy
+        // `wa-templates` or canonical `wa-campaigns`, MSG-1867 phase 3) is resolved
+        // to the canonical channel enum the gateway expects. Unknown values pass
+        // through untouched so the server can reject them with its own message.
+        const canonical = (0, client_1.normalizeChannel)(args.channel);
+        return canonical && canonical !== args.channel
+            ? { ...args, channel: canonical }
+            : args;
+    }
+    if (!defaultChannel)
+        return args;
+    return { ...args, channel: defaultChannel };
+}