@rcs-campaigns/agent-toolkit 0.1.5

package/dist/client.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GatewayClient = exports.GatewayError = void 0;
+exports.detectSkin = detectSkin;
+exports.readVersion = readVersion;
+exports.skinLabels = skinLabels;
+exports.normalizeChannel = normalizeChannel;
+exports.resolveConfig = resolveConfig;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/**
+ * Which skin this process was launched as, from the bin name in argv.
+ *
+ * `wa`/`wa-mcp` mean the caller came in through the WhatsApp-branded docs and
+ * expects WhatsApp unless they say otherwise. Anything else (including being
+ * imported as a library) is treated as the neutral RCS skin, which leaves the
+ * channel to the server. Detection is deliberately conservative: an unknown
+ * argv, a bundler-rewritten path, or a direct import all fall through to 'rcs'.
+ */
+function detectSkin(argv = process.argv) {
+    const invoked = argv[1];
+    if (typeof invoked !== 'string')
+        return 'rcs';
+    // basename without extension, so ".../bin/wa-mcp.js" → "wa-mcp".
+    const base = invoked.split(/[\\/]/).pop() ?? '';
+    const name = base.replace(/\.(js|cjs|mjs|ts)$/, '');
+    return name === 'wa' || name === 'wa-mcp' ? 'wa' : 'rcs';
+}
+/**
+ * The package's own version, read at runtime rather than restated in a
+ * constant. A hardcoded copy silently goes stale the first time anyone bumps
+ * for a release, and both skins show this string to a user. From dist/ and from
+ * src/ alike the package root is one level up.
+ */
+function readVersion() {
+    try {
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, '..', 'package.json'), 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/** Human-readable product + channel names for the running skin. */
+function skinLabels(skin = detectSkin()) {
+    return skin === 'wa'
+        ? { product: 'WhatsApp Campaigns', channel: 'WhatsApp', slug: 'wa-campaigns' }
+        : { product: 'RCS Campaigns', channel: 'RCS', slug: 'rcs-campaigns' };
+}
+/** First environment variable that is set and non-empty, under either prefix. */
+function fromEnv(...names) {
+    for (const name of names) {
+        const value = process.env[name];
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+/**
+ * Brand ids a user may type where a channel is expected (MSG-1867 phase 3).
+ * CANONICAL ids first, then the LEGACY spellings that are still persisted in
+ * keys, org metadata and old docs until the brand-id data migration has run
+ * everywhere. Mirrors `BRAND_IDS` / `BRAND_ID_ALIASES` in
+ * `@msg2ai/template-core`; this package is zero-dependency and published to
+ * npm, so it cannot import that registry.
+ */
+const BRAND_CHANNELS = {
+    'rcs-campaigns': 'RCS',
+    'rcs-surveys': 'RCS',
+    'wa-campaigns': 'WHATSAPP',
+    'wa-surveys': 'WHATSAPP',
+    // legacy spellings — accepted, never emitted
+    'rcs-templates': 'RCS',
+    'wa-templates': 'WHATSAPP'
+};
+/**
+ * Normalize a channel from configuration or a tool argument. Accepts the channel
+ * enum itself (any case) AND a brand id — canonical or legacy — resolving it to
+ * that brand's channel. Always returns the canonical channel enum; unknown
+ * values are ignored.
+ */
+function normalizeChannel(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const v = value.trim();
+    const upper = v.toUpperCase();
+    if (upper === 'RCS' || upper === 'WHATSAPP')
+        return upper;
+    return BRAND_CHANNELS[v.toLowerCase()];
+}
+/** Normalize a channel from configuration; unknown values are ignored. */
+function readChannel(value) {
+    return normalizeChannel(value);
+}
+/** A gateway error carrying the HTTP status + the server's error envelope. */
+class GatewayError extends Error {
+    status;
+    details;
+    constructor(message, status, details) {
+        super(message);
+        this.name = 'GatewayError';
+        this.status = status;
+        this.details = details;
+    }
+}
+exports.GatewayError = GatewayError;
+/**
+ * Resolve config from explicit values, falling back to the environment.
+ *
+ * WA_* and RCS_* are accepted interchangeably. When both are set the one
+ * matching the running skin wins, so a machine configured for both does the
+ * expected thing under either bin.
+ */
+function resolveConfig(partial) {
+    const skin = detectSkin();
+    const [urlFirst, urlSecond] = skin === 'wa'
+        ? ['WA_GATEWAY_URL', 'RCS_GATEWAY_URL']
+        : ['RCS_GATEWAY_URL', 'WA_GATEWAY_URL'];
+    const [keyFirst, keySecond] = skin === 'wa'
+        ? ['WA_AGENT_KEY', 'RCS_AGENT_KEY']
+        : ['RCS_AGENT_KEY', 'WA_AGENT_KEY'];
+    const baseUrl = partial?.baseUrl ?? fromEnv(urlFirst, urlSecond) ?? 'http://localhost:3002';
+    const apiKey = partial?.apiKey ?? fromEnv(keyFirst, keySecond) ?? '';
+    if (!apiKey) {
+        throw new Error(`No agent key configured. Set ${keyFirst} or pass apiKey explicitly.`);
+    }
+    // Explicit beats env beats skin default. The wa skin assumes WhatsApp; the rcs
+    // skin stays silent and lets the server pick the org's own brand channel.
+    const defaultChannel = partial?.defaultChannel ??
+        readChannel(fromEnv('WA_DEFAULT_CHANNEL', 'RCS_DEFAULT_CHANNEL')) ??
+        (skin === 'wa' ? 'WHATSAPP' : undefined);
+    return { baseUrl: baseUrl.replace(/\/$/, ''), apiKey, defaultChannel };
+}
+class GatewayClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    static fromEnv(partial) {
+        return new GatewayClient(resolveConfig(partial));
+    }
+    /** Issue a request against the gateway and return `data` from the envelope. */
+    async call(spec) {
+        const url = new URL(`${this.config.baseUrl}/api/agent${spec.path}`);
+        for (const [k, v] of Object.entries(spec.query ?? {})) {
+            if (v !== undefined && v !== '')
+                url.searchParams.set(k, String(v));
+        }
+        const res = await fetch(url, {
+            method: spec.method,
+            headers: {
+                Authorization: `Bearer ${this.config.apiKey}`,
+                ...(spec.body !== undefined
+                    ? { 'Content-Type': 'application/json' }
+                    : {})
+            },
+            body: spec.body !== undefined ? JSON.stringify(spec.body) : undefined
+        });
+        const text = await res.text();
+        let parsed = undefined;
+        try {
+            parsed = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            // Non-JSON body (e.g. a proxy error page); surface the raw text.
+            if (!res.ok)
+                throw new GatewayError(text || res.statusText, res.status);
+        }
+        if (!res.ok || parsed?.success === false) {
+            throw new GatewayError(parsed?.error ?? `Request failed (${res.status})`, res.status, parsed?.details);
+        }
+        return (parsed?.data ?? parsed);
+    }
+}
+exports.GatewayClient = GatewayClient;

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @rcs-campaigns/agent-toolkit
+ *
+ * Two agent skins over one gateway client:
+ *   - the MCP server (`rcs-mcp` bin, ./mcp)
+ *   - the CLI (`rcs` bin, ./cli)
+ * sharing the typed gateway client (./client) and the declarative tool catalog
+ * (./tools). Importing the package gives you the client + catalog to embed in
+ * your own agent; the bins are the ready-made skins.
+ *
+ * @see docs/design/AGENT-ENABLEMENT-AND-X402-DESIGN.md
+ */
+export * from './client';
+export * from './tools';
+export * from './openapi';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,31 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * @rcs-campaigns/agent-toolkit
+ *
+ * Two agent skins over one gateway client:
+ *   - the MCP server (`rcs-mcp` bin, ./mcp)
+ *   - the CLI (`rcs` bin, ./cli)
+ * sharing the typed gateway client (./client) and the declarative tool catalog
+ * (./tools). Importing the package gives you the client + catalog to embed in
+ * your own agent; the bins are the ready-made skins.
+ *
+ * @see docs/design/AGENT-ENABLEMENT-AND-X402-DESIGN.md
+ */
+__exportStar(require("./client"), exports);
+__exportStar(require("./tools"), exports);
+__exportStar(require("./openapi"), exports);

package/dist/mcp.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":""}

package/dist/mcp.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * `rcs-mcp` — a Model Context Protocol (MCP) server exposing the RCS Campaigns
+ * agent gateway as tools, so Claude (and any MCP-capable agent) can search, read,
+ * render, create, clone, submit, and send RCS templates.
+ *
+ * Transport: stdio with newline-delimited JSON-RPC 2.0 (the MCP stdio framing).
+ * It is implemented by hand against the protocol so this package carries ZERO
+ * runtime dependencies — nothing to install, nothing to drift, and it slots into
+ * the workspace without touching the lockfile's external graph.
+ *
+ * Credentials: the agent key + gateway URL come from the environment
+ * (RCS_AGENT_KEY / RCS_GATEWAY_URL). This process holds the key only to forward
+ * it as a Bearer token to the gateway — all business logic stays server-side.
+ *
+ * Wire it up (e.g. Claude Code):
+ *   claude mcp add rcs-campaigns -- npx -y -p @rcs-campaigns/agent-toolkit rcs-mcp
+ *   (with RCS_AGENT_KEY + RCS_GATEWAY_URL set in the environment)
+ */
+const node_readline_1 = require("node:readline");
+const client_1 = require("./client");
+const tools_1 = require("./tools");
+const PROTOCOL_VERSION = '2024-11-05';
+/**
+ * The MCP host shows `serverInfo` and `instructions` to the user and injects the
+ * latter as system guidance. Both must match the skin the server was launched
+ * as: an agent that registered `wa-mcp` should not find "RCS Campaigns" and
+ * "RCS-first" in its own tool list, contradicting the docs that sent it here.
+ * Same catalog, same gateway — only the words the model reads differ.
+ */
+const SKIN = (0, client_1.detectSkin)();
+const { product: PRODUCT, channel: CHANNEL, slug: SLUG } = (0, client_1.skinLabels)(SKIN);
+const SERVER_INFO = { name: SLUG, version: (0, client_1.readVersion)() };
+/**
+ * Surfaced to MCP hosts as the initialize result's `instructions` string — hosts
+ * inject it as system guidance for the model. It teaches the canonical workflow
+ * so an agent does not have to discover the submit-before-RCS step by trial:
+ * without it, sends silently fall back to SMS and the agent has no cue why.
+ */
+const INSTRUCTIONS = [
+    `${PRODUCT} agent gateway — author, approve, and send ${CHANNEL}-first message`,
+    'templates and conversational surveys over one typed contract.',
+    '',
+    'Canonical template flow:',
+    '  search_templates → clone_template (into your org) → render_template (preview)',
+    '  → submit_template (provider approval) → send_message.',
+    'Surveys mirror it: search_surveys/create_survey → submit_survey → send_survey →',
+    'get_results.',
+    '',
+    `IMPORTANT — rich ${CHANNEL} requires approval. A freshly created or cloned`,
+    'template delivers as SMS fallback ONLY until it is submitted AND',
+    'provider-approved. send_message returns a funnel whose `fellBackToSms` count',
+    `is > 0 whenever the rich ${CHANNEL} path was unavailable — submit the template`,
+    `and wait for approval to deliver rich ${CHANNEL}. send_message/send_survey bill`,
+    'your org and are irreversible.',
+    '',
+    'Call `capabilities` first to see the tool catalog and which scopes your key holds.'
+].join('\n');
+/** Write one newline-delimited JSON-RPC message to stdout. */
+function send(msg) {
+    process.stdout.write(`${JSON.stringify(msg)}\n`);
+}
+function reply(id, result) {
+    send({ jsonrpc: '2.0', id, result });
+}
+function replyError(id, code, message, data) {
+    send({ jsonrpc: '2.0', id, error: { code, message, data } });
+}
+// Lazily build the client so `tools/list` works even before a key is set, but a
+// `tools/call` without a key fails cleanly with a helpful message.
+let client = null;
+let config = null;
+function getClient() {
+    if (!client) {
+        config = (0, client_1.resolveConfig)();
+        client = new client_1.GatewayClient(config);
+    }
+    return client;
+}
+async function handleToolCall(id, params) {
+    const name = params?.name;
+    const args = params?.arguments ?? {};
+    const tool = (0, tools_1.findTool)(name);
+    if (!tool) {
+        return replyError(id, -32602, `Unknown tool: ${name}`);
+    }
+    try {
+        const gateway = getClient();
+        // Resolve the skin's default channel before mapping args to a request, so
+        // `wa-mcp` sends WhatsApp without every caller repeating themselves.
+        const resolved = (0, tools_1.withDefaultChannel)(tool, args, config?.defaultChannel);
+        const data = await gateway.call(tool.toRequest(resolved));
+        // MCP tool results are content blocks; we return the JSON payload as text so
+        // the agent can parse it. isError stays false on success.
+        reply(id, {
+            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+            isError: false
+        });
+    }
+    catch (err) {
+        const message = err instanceof client_1.GatewayError
+            ? `Gateway ${err.status}: ${err.message}`
+            : err instanceof Error
+                ? err.message
+                : String(err);
+        // Surface the failure as an MCP tool error (not a protocol error) so the
+        // agent can read it and decide what to do (e.g. fix args, request a scope).
+        reply(id, {
+            content: [{ type: 'text', text: message }],
+            isError: true
+        });
+    }
+}
+function handleMessage(msg) {
+    switch (msg.method) {
+        case 'initialize': {
+            // Echo the client's requested protocol version when it sends one (the spec
+            // negotiates on it); fall back to the version we implement against.
+            const requested = msg.params?.protocolVersion;
+            reply(msg.id, {
+                protocolVersion: typeof requested === 'string' ? requested : PROTOCOL_VERSION,
+                capabilities: { tools: {} },
+                serverInfo: SERVER_INFO,
+                instructions: INSTRUCTIONS
+            });
+            return;
+        }
+        case 'notifications/initialized':
+            return; // notification: no response
+        case 'ping':
+            reply(msg.id, {});
+            return;
+        case 'tools/list':
+            reply(msg.id, {
+                tools: tools_1.TOOLS.map((t) => ({
+                    name: t.name,
+                    description: t.description,
+                    inputSchema: t.inputSchema
+                }))
+            });
+            return;
+        case 'tools/call':
+            void handleToolCall(msg.id, msg.params);
+            return;
+        default:
+            // Unknown request -> method-not-found; ignore unknown notifications.
+            if (msg.id !== undefined && msg.id !== null) {
+                replyError(msg.id, -32601, `Method not found: ${msg.method}`);
+            }
+    }
+}
+function main() {
+    const rl = (0, node_readline_1.createInterface)({ input: process.stdin });
+    rl.on('line', (line) => {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(trimmed);
+        }
+        catch {
+            return; // ignore malformed lines (no id to respond to)
+        }
+        try {
+            handleMessage(msg);
+        }
+        catch (err) {
+            if (msg.id !== undefined && msg.id !== null) {
+                replyError(msg.id, -32603, 'Internal error', String(err));
+            }
+        }
+    });
+    rl.on('close', () => process.exit(0));
+}
+main();

package/dist/openapi.d.ts

@@ -0,0 +1,36 @@
+export interface OpenApiServer {
+    url: string;
+    description: string;
+}
+export interface BuildOpenApiOptions {
+    /**
+     * The webhook event types to document under the top-level `webhooks` object.
+     *
+     * Defaults to `WEBHOOK_EVENT_NAMES`, which IS the vocabulary — `apps/server`
+     * re-exports it as `WEBHOOK_EVENTS` rather than declaring a second list, so
+     * the default is already the server's answer and passing it explicitly (as
+     * `routes/agent.ts` does) is a no-op that documents the intent. The override
+     * stays for an embedder generating a document for a gateway build that
+     * fires a different set.
+     */
+    webhookEvents?: readonly string[];
+    /** Document version stamped into `info.version`. */
+    version?: string;
+}
+/** Anything JSON-serialisable. The document is data, not a typed AST. */
+type Json = Record<string, any>;
+/** `/conversations/:id` → `/conversations/{id}` (OpenAPI path templating). */
+export declare function toOpenApiPath(path: string): string;
+/** The `:param` names in an Express-style path, in order. */
+export declare function pathParamsOf(path: string): string[];
+/**
+ * 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.
+ */
+export declare function buildOpenApiDocument(servers: OpenApiServer[], options?: BuildOpenApiOptions): Json;
+export {};
+//# sourceMappingURL=openapi.d.ts.map

package/dist/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,yEAAyE;AACzE,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAMhC,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,6DAA6D;AAC7D,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAEnD;AAwfD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,aAAa,EAAE,EACxB,OAAO,GAAE,mBAAwB,GAChC,IAAI,CAmFN"}