@rcs-campaigns/agent-toolkit 0.1.5

package/README.md

@@ -0,0 +1,176 @@
+# @rcs-campaigns/agent-toolkit
+
+Agent skins for the RCS Campaigns **agent gateway** (`/api/agent/*`): an **MCP
+server** (`rcs-mcp`) and a **CLI** (`rcs`), sharing one typed gateway client and
+one declarative tool catalog. Zero runtime dependencies.
+
+> Part of the agent-enablement work — see
+> [`docs/design/AGENT-ENABLEMENT-AND-X402-DESIGN.md`](../../docs/design/AGENT-ENABLEMENT-AND-X402-DESIGN.md).
+> This implements **P0–P4** (gateway client, MCP, CLI, skills). The x402
+> pay-per-call rail (P1/P5) is intentionally **not** included yet.
+
+The MCP server lets Claude (Claude Code, Claude Desktop, or any MCP host) search,
+read, render, create, clone, submit, and send RCS templates through your org's
+gateway — authenticated with one agent key.
+
+---
+
+## Setup (5 minutes)
+
+### 1. Get an agent key
+
+In the app at **https://app.rcs-campaigns.com**: **Settings → API keys → Create
+key** (Admin only). Pick the scopes the agent needs, then **copy the key — it is
+shown exactly once** (`rcsk_live_…`). Treat it like a password; you can
+revoke/rotate it from the same screen.
+
+Scopes: `templates:read`, `templates:write`, `templates:submit`,
+`marketplace:clone`, `messages:send`, `usage:read`, `surveys:read`,
+`surveys:write`, `surveys:submit`, `surveys:send`, `results:read`.
+
+### 2. Set the gateway URL
+
+```bash
+RCS_GATEWAY_URL=https://rcs-templates-api-dot-msg2ai-server.ue.r.appspot.com
+```
+
+> The key is tied to the environment it was minted in — a key from one
+> environment will **401** against another (they're different databases).
+
+### 3. Run it — published on npm
+
+The package is on the public registry, so the quickest path needs no checkout or
+build. It ships **two** bins (`rcs` and `rcs-mcp`), so under `npx` you must select
+one with `-p` (the package) followed by the bin name — `npx @rcs-campaigns/agent-toolkit rcs …`
+fails with *"could not determine executable to run"* because `agent-toolkit` is
+not itself a bin:
+
+```bash
+npx -y -p @rcs-campaigns/agent-toolkit rcs capabilities
+```
+
+Or install the bins globally and call them directly:
+
+```bash
+npm i -g @rcs-campaigns/agent-toolkit
+rcs capabilities
+rcs-mcp            # stdio MCP server
+```
+
+Monorepo contributors can run from source instead — build once from the root:
+
+```bash
+pnpm install
+pnpm --filter @rcs-campaigns/agent-toolkit build   # -> dist/mcp.js, dist/cli.js
+```
+
+### 4. Verify the key works (before wiring up a host)
+
+```bash
+export RCS_GATEWAY_URL=https://rcs-templates-api-dot-msg2ai-server.ue.r.appspot.com
+export RCS_AGENT_KEY=rcsk_live_…
+npx -y -p @rcs-campaigns/agent-toolkit rcs capabilities
+```
+
+A healthy response lists `grantedScopes` and the tool catalog. If you get
+`Gateway 401`, the key is wrong/rotated or points at the wrong environment.
+
+---
+
+## Add to an MCP host
+
+### Claude Code
+
+```bash
+claude mcp add rcs-campaigns \
+  --env RCS_GATEWAY_URL=https://rcs-templates-api-dot-msg2ai-server.ue.r.appspot.com \
+  --env RCS_AGENT_KEY=rcsk_live_… \
+  -- npx -y -p @rcs-campaigns/agent-toolkit rcs-mcp
+```
+
+Running from a local checkout instead? Swap the launch command for the built
+path: `-- node /ABSOLUTE/PATH/TO/rcs-templates/packages/agent-toolkit/dist/mcp.js`
+(use an **absolute** path). Confirm with `claude mcp list` (should show
+`rcs-campaigns`), then ask Claude to “list the RCS Campaigns tools.”
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json`
+(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`) and add:
+
+```json
+{
+  "mcpServers": {
+    "rcs-campaigns": {
+      "command": "npx",
+      "args": ["-y", "-p", "@rcs-campaigns/agent-toolkit", "rcs-mcp"],
+      "env": {
+        "RCS_GATEWAY_URL": "https://rcs-templates-api-dot-msg2ai-server.ue.r.appspot.com",
+        "RCS_AGENT_KEY": "rcsk_live_…"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The tools appear under the 🔌 menu. (From a local
+checkout, set `"command": "node"` and `"args"` to the absolute `dist/mcp.js` path
+instead.)
+
+### Tools exposed
+
+Templates: `capabilities`, `search_templates`, `get_template`,
+`render_template`, `create_template`, `clone_template`, `submit_template`,
+`send_message`, `get_usage`. Surveys: `search_surveys`, `get_survey`,
+`render_survey`, `create_survey`, `clone_survey`, `submit_survey`,
+`send_survey`, `get_results`. Each `*:write` / `*:send` tool needs the matching
+scope on your key.
+
+---
+
+## CLI (`rcs`)
+
+Same client, same auth — handy for scripts and a quick smoke test. Run it via
+`npx` (`npx -y -p @rcs-campaigns/agent-toolkit rcs <cmd>`), the global `rcs`
+binary, or `node dist/cli.js` from a checkout — all equivalent:
+
+```bash
+rcs capabilities
+rcs search "appointment reminder" --channel RCS --sort rating
+rcs get <id>
+rcs render <id> --var firstName=Ada
+rcs clone <id>
+rcs create --file template.json
+rcs send <blueprintId> --to +15551112222 --var firstName=Ada
+rcs usage
+```
+
+Config flags override env: `--url <gateway>` / `--key <rcsk_…>`. JSON in / JSON
+out — pipe into `jq`, wire into CI, or call from a skill.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| `No agent key configured` | `RCS_AGENT_KEY` not reaching the process — for MCP hosts it must be in the server's `env` block, not your shell. |
+| `Gateway 401` | Key wrong, revoked, or minted in a different environment than `RCS_GATEWAY_URL` points at. |
+| `Gateway 403` (scope) | The key lacks the tool's scope — mint a new key with it (scopes are fixed at creation). |
+| Host shows no tools | Wrong path to `dist/mcp.js`, or the package wasn't built (`pnpm --filter @rcs-campaigns/agent-toolkit build`). |
+| Empty search results | The org has no published/owned templates yet — clone one from the marketplace first. |
+
+---
+
+## Embed the client
+
+```ts
+import { GatewayClient, TOOLS } from '@rcs-campaigns/agent-toolkit';
+
+const client = GatewayClient.fromEnv(); // reads RCS_GATEWAY_URL + RCS_AGENT_KEY
+const { items } = await client.call({
+  method: 'GET',
+  path: '/templates',
+  query: { q: 'promo' }
+});
+```

package/dist/cli.d.ts

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

package/dist/cli.d.ts.map

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

package/dist/cli.js

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * `rcs` / `wa` — a thin CLI over the agent gateway. JSON in / JSON out so it
+ * composes in shells, CI, and skill-chain steps. Zero dependencies (Node 22
+ * argv + global fetch). It shares the SAME gateway client + tool catalog as the
+ * MCP server, so the two skins never diverge.
+ *
+ * One build, two bins. Invoked as `wa` it defaults to the WhatsApp channel and
+ * reads WA_* config; invoked as `rcs` it leaves the channel to the server (the
+ * org's own brand) and reads RCS_*. Either prefix is accepted under either bin.
+ *
+ * Config (flags override env):
+ *   --url <gateway base url>   | WA_GATEWAY_URL / RCS_GATEWAY_URL
+ *   --key <rcsk_…>             | WA_AGENT_KEY   / RCS_AGENT_KEY
+ *   --channel RCS|WHATSAPP     | WA_DEFAULT_CHANNEL / RCS_DEFAULT_CHANNEL
+ *
+ * Commands:
+ *   rcs capabilities
+ *   rcs search [query] [--channel ${CHANNEL_EG}] [--category EVENTS] [--sort rating|used]
+ *   rcs get <id>
+ *   rcs render <id> [--var key=value ...]
+ *   rcs create --file <template.json>
+ *   rcs clone <id>
+ *   rcs submit <id>
+ *   rcs send <blueprintId> --to +1555... [--to ...] [--var key=value ...] [--name "..."]
+ *   rcs usage
+ */
+const node_fs_1 = require("node:fs");
+const client_1 = require("./client");
+/** Minimal argv parser: --flag value, --bool, and repeatable --to/--var. */
+function parseArgs(argv) {
+    const out = { _: [], flags: {}, multi: { to: [], var: [], audience: [] } };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const key = a.slice(2);
+            const next = argv[i + 1];
+            const takesValue = next !== undefined && !next.startsWith('--');
+            const value = takesValue ? argv[++i] : true;
+            if (key === 'to' || key === 'var' || key === 'audience') {
+                if (typeof value === 'string')
+                    out.multi[key].push(value);
+            }
+            else {
+                out.flags[key] = value;
+            }
+        }
+        else {
+            out._.push(a);
+        }
+    }
+    return out;
+}
+/**
+ * Read a JSON body from a file, letting the skin's default channel apply when
+ * the document doesn't name one. An explicit `channel` in the file always wins,
+ * so this only decides what "unspecified" means — WhatsApp under `wa`, the org's
+ * own brand channel under `rcs`.
+ */
+function readBody(file, defaultChannel) {
+    const body = JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+    if (defaultChannel &&
+        body &&
+        typeof body === 'object' &&
+        !Array.isArray(body) &&
+        body.channel === undefined) {
+        return { ...body, channel: defaultChannel };
+    }
+    return body;
+}
+/** Turn ["key=value", ...] into { key: value }. */
+function kvPairs(pairs) {
+    const obj = {};
+    for (const p of pairs) {
+        const eq = p.indexOf('=');
+        if (eq > 0)
+            obj[p.slice(0, eq)] = p.slice(eq + 1);
+    }
+    return obj;
+}
+function print(data) {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+}
+const SKIN = (0, client_1.detectSkin)();
+const BIN = SKIN === 'wa' ? 'wa' : 'rcs';
+/** Show the channel this skin actually defaults to in its own help text. */
+const CHANNEL_EG = SKIN === 'wa' ? 'WHATSAPP' : 'RCS';
+const USAGE = `${BIN} — ${(0, client_1.skinLabels)(SKIN).product} agent CLI v${(0, client_1.readVersion)()}
+
+Usage:
+  ${BIN} capabilities
+  ${BIN} search [query] [--channel ${CHANNEL_EG}] [--category KEY] [--sort rating|used]
+  ${BIN} get <id>
+  ${BIN} render <id> [--var key=value ...]
+  ${BIN} create --file <template.json>
+  ${BIN} clone <id>
+  ${BIN} submit <id>
+  ${BIN} send <blueprintId> --to +1555... [--to ...] [--var key=value ...] [--name "..."]
+  ${BIN} upload-image (--file <image.png> | --from-url <https-url>)   # returns the GCS URL
+  ${BIN} knowledge <id> (--get | --set-file <doc.md> | --delete | --enable | --disable)
+  ${BIN} usage
+
+Surveys:
+  ${BIN} surveys [query] [--status DRAFT|SCHEDULED|ACTIVE|CLOSED]
+  ${BIN} survey get <id>
+  ${BIN} survey create --file <survey.json>
+  ${BIN} survey update <id> --file <patch.json>
+  ${BIN} survey submit <id>
+  ${BIN} survey send <id> [--to +1555... ...] [--audience <audienceId> ...]
+  ${BIN} survey send-test <id> --to +1555...
+  ${BIN} survey sends <id>
+  ${BIN} survey results <id>
+
+Config: --url/${BIN.toUpperCase()}_GATEWAY_URL, --key/${BIN.toUpperCase()}_AGENT_KEY`;
+async function run() {
+    const argv = parseArgs(process.argv.slice(2));
+    const cmd = argv._[0];
+    if (!cmd || cmd === 'help' || argv.flags.help) {
+        process.stdout.write(`${USAGE}\n`);
+        return;
+    }
+    const config = (0, client_1.resolveConfig)({
+        baseUrl: typeof argv.flags.url === 'string' ? argv.flags.url : undefined,
+        apiKey: typeof argv.flags.key === 'string' ? argv.flags.key : undefined
+    });
+    const client = new client_1.GatewayClient(config);
+    switch (cmd) {
+        case 'capabilities':
+            return print(await client.call({ method: 'GET', path: '/capabilities' }));
+        case 'search':
+            return print(await client.call({
+                method: 'GET',
+                path: '/templates',
+                query: {
+                    // Join the remaining positional words so `rcs search appointment
+                    // reminder` searches the full phrase, not just the first word.
+                    q: argv._.slice(1).join(' ') || undefined,
+                    channel: str(argv.flags.channel) ?? config.defaultChannel,
+                    category: str(argv.flags.category),
+                    sort: str(argv.flags.sort)
+                }
+            }));
+        case 'get':
+            requireArg(argv._[1], 'get <id>');
+            return print(await client.call({
+                method: 'GET',
+                path: `/templates/${enc(argv._[1])}`
+            }));
+        case 'render':
+            requireArg(argv._[1], 'render <id>');
+            return print(await client.call({
+                method: 'POST',
+                path: `/templates/${enc(argv._[1])}/render`,
+                body: { variables: kvPairs(argv.multi.var) }
+            }));
+        case 'create': {
+            const file = str(argv.flags.file);
+            if (!file)
+                fail('create requires --file <template.json>');
+            const body = readBody(file, config.defaultChannel);
+            return print(await client.call({ method: 'POST', path: '/templates', body }));
+        }
+        case 'clone':
+            requireArg(argv._[1], 'clone <id>');
+            return print(await client.call({
+                method: 'POST',
+                path: `/marketplace/${enc(argv._[1])}/clone`
+            }));
+        case 'submit':
+            requireArg(argv._[1], 'submit <id>');
+            return print(await client.call({
+                method: 'POST',
+                path: `/templates/${enc(argv._[1])}/submit`
+            }));
+        case 'send': {
+            requireArg(argv._[1], 'send <blueprintId> --to +1...');
+            if (argv.multi.to.length === 0)
+                fail('send requires at least one --to <E.164>');
+            return print(await client.call({
+                method: 'POST',
+                path: '/messages/send',
+                body: {
+                    blueprintId: argv._[1],
+                    to: argv.multi.to,
+                    variables: kvPairs(argv.multi.var),
+                    name: str(argv.flags.name)
+                }
+            }));
+        }
+        case 'upload-image': {
+            // Store a picture on the platform GCS bucket (the only URLs survey/
+            // template media should use). --from-url re-hosts a web image server-side.
+            const file = str(argv.flags.file);
+            const fromUrl = str(argv.flags['from-url']);
+            if (!file === !fromUrl) {
+                fail('upload-image requires exactly one of --file or --from-url');
+            }
+            if (fromUrl) {
+                return print(await client.call({
+                    method: 'POST',
+                    path: '/media/upload',
+                    body: { sourceUrl: fromUrl }
+                }));
+            }
+            const MIME_BY_EXT = {
+                png: 'image/png',
+                jpg: 'image/jpeg',
+                jpeg: 'image/jpeg',
+                webp: 'image/webp',
+                gif: 'image/gif'
+            };
+            const ext = file.split('.').pop()?.toLowerCase() ?? '';
+            const mime = MIME_BY_EXT[ext];
+            if (!mime)
+                fail('upload-image --file must be .png, .jpg, .webp, or .gif');
+            const bytes = (0, node_fs_1.readFileSync)(file);
+            return print(await client.call({
+                method: 'POST',
+                path: '/media/upload',
+                body: {
+                    base64: bytes.toString('base64'),
+                    mime,
+                    filename: file.split('/').pop()
+                }
+            }));
+        }
+        case 'knowledge': {
+            // Knowledge base management: read the grounding doc, set/replace it,
+            // delete it, or flip the answering master switch without touching it.
+            requireArg(argv._[1], 'knowledge <id> ...');
+            const id = enc(argv._[1]);
+            const setFile = str(argv.flags['set-file']);
+            const picked = [
+                argv.flags.get ? 'get' : null,
+                setFile ? 'set-file' : null,
+                argv.flags.delete ? 'delete' : null,
+                argv.flags.enable ? 'enable' : null,
+                argv.flags.disable ? 'disable' : null
+            ].filter(Boolean);
+            if (picked.length !== 1) {
+                fail('knowledge requires exactly one of --get, --set-file <doc>, --delete, --enable, --disable');
+            }
+            if (argv.flags.get) {
+                return print(await client.call({ method: 'GET', path: `/templates/${id}/knowledge` }));
+            }
+            if (setFile) {
+                return print(await client.call({
+                    method: 'PUT',
+                    path: `/templates/${id}/knowledge`,
+                    body: { doc: (0, node_fs_1.readFileSync)(setFile, 'utf8') }
+                }));
+            }
+            if (argv.flags.delete) {
+                return print(await client.call({ method: 'DELETE', path: `/templates/${id}/knowledge` }));
+            }
+            return print(await client.call({
+                method: 'POST',
+                path: `/templates/${id}/knowledge/${argv.flags.enable ? 'enable' : 'disable'}`
+            }));
+        }
+        case 'usage':
+            return print(await client.call({ method: 'GET', path: '/usage' }));
+        case 'surveys':
+            return print(await client.call({
+                method: 'GET',
+                path: '/surveys',
+                query: {
+                    q: argv._.slice(1).join(' ') || undefined,
+                    status: str(argv.flags.status)
+                }
+            }));
+        case 'survey': {
+            const sub = argv._[1];
+            const id = argv._[2];
+            switch (sub) {
+                case 'get':
+                    requireArg(id, 'survey get <id>');
+                    return print(await client.call({ method: 'GET', path: `/surveys/${enc(id)}` }));
+                case 'create': {
+                    const file = str(argv.flags.file);
+                    if (!file)
+                        fail('survey create requires --file <survey.json>');
+                    const body = readBody(file, config.defaultChannel);
+                    return print(await client.call({ method: 'POST', path: '/surveys', body }));
+                }
+                case 'update': {
+                    requireArg(id, 'survey update <id> --file <patch.json>');
+                    const file = str(argv.flags.file);
+                    if (!file)
+                        fail('survey update requires --file <patch.json>');
+                    const body = readBody(file, config.defaultChannel);
+                    return print(await client.call({
+                        method: 'PATCH',
+                        path: `/surveys/${enc(id)}`,
+                        body
+                    }));
+                }
+                case 'submit':
+                    requireArg(id, 'survey submit <id>');
+                    return print(await client.call({
+                        method: 'POST',
+                        path: `/surveys/${enc(id)}/submit`
+                    }));
+                case 'send': {
+                    requireArg(id, 'survey send <id> [--to +1555...] [--audience <id>]');
+                    if (argv.multi.to.length === 0 && argv.multi.audience.length === 0)
+                        fail('survey send requires --to and/or --audience');
+                    return print(await client.call({
+                        method: 'POST',
+                        path: `/surveys/${enc(id)}/send`,
+                        body: {
+                            to: argv.multi.to.length ? argv.multi.to : undefined,
+                            audienceIds: argv.multi.audience.length
+                                ? argv.multi.audience
+                                : undefined
+                        }
+                    }));
+                }
+                case 'send-test':
+                    requireArg(id, 'survey send-test <id> --to +1555...');
+                    if (argv.multi.to.length !== 1)
+                        fail('survey send-test requires exactly one --to <E.164>');
+                    return print(await client.call({
+                        method: 'POST',
+                        path: `/surveys/${enc(id)}/send-test`,
+                        body: { number: argv.multi.to[0] }
+                    }));
+                case 'sends':
+                    requireArg(id, 'survey sends <id>');
+                    return print(await client.call({
+                        method: 'GET',
+                        path: `/surveys/${enc(id)}/sends`
+                    }));
+                case 'results':
+                    requireArg(id, 'survey results <id>');
+                    return print(await client.call({
+                        method: 'GET',
+                        path: `/surveys/${enc(id)}/results`
+                    }));
+                default:
+                    fail(`Unknown survey subcommand: ${sub ?? '(none)'}\n\n${USAGE}`);
+            }
+            return;
+        }
+        default:
+            fail(`Unknown command: ${cmd}\n\n${USAGE}`);
+    }
+}
+function str(v) {
+    return typeof v === 'string' ? v : undefined;
+}
+function enc(v) {
+    return encodeURIComponent(v);
+}
+function requireArg(v, usage) {
+    if (!v)
+        fail(`Missing argument. Usage: rcs ${usage}`);
+}
+function fail(message) {
+    process.stderr.write(`${message}\n`);
+    process.exit(2);
+}
+run().catch((err) => {
+    if (err instanceof client_1.GatewayError) {
+        process.stderr.write(`Gateway ${err.status}: ${err.message}\n`);
+        if (err.details)
+            process.stderr.write(`${JSON.stringify(err.details)}\n`);
+    }
+    else {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    process.exit(1);
+});

package/dist/client.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Typed HTTP client for the RCS Campaigns `/api/agent/*` gateway.
+ *
+ * Shared by BOTH skins in this package (the MCP server and the CLI) so they can
+ * never drift on how they talk to the gateway — the same single contract the
+ * design calls for ("one gateway, three skins"). Zero dependencies: Node 22's
+ * global `fetch` is used directly.
+ *
+ * Auth is the agent key (`rcsk_…`) the org minted; it is sent as a Bearer token,
+ * exactly what agentAuth expects on the server. The base URL + key come from the
+ * environment or are passed explicitly.
+ *
+ * Two skins, one package: the same build ships as the RCS-branded `rcs`/`rcs-mcp`
+ * bins and the WhatsApp-branded `wa`/`wa-mcp` bins. They differ only in naming
+ * and in which channel they default to — the gateway, the key, and the tool
+ * catalog are identical. Environment variables are therefore accepted under
+ * BOTH prefixes (WA_* and RCS_*), so a user of either skin can configure it with
+ * the names that skin's docs use.
+ */
+/** The messaging channel a call acts on. Mirrors the gateway's own enum. */
+export type Channel = 'RCS' | 'WHATSAPP';
+export interface GatewayConfig {
+    /** Base URL of the RCS Campaigns server, e.g. https://api.example.com */
+    baseUrl: string;
+    /** The org-minted agent key (rcsk_live_…). */
+    apiKey: string;
+    /**
+     * Channel to assume when a call accepts one and the caller omits it. Undefined
+     * leaves the decision to the server, which falls back to the org's own brand
+     * channel — the historical behaviour, and what the `rcs` skin still does.
+     */
+    defaultChannel?: Channel;
+}
+/**
+ * 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'.
+ */
+export declare function detectSkin(argv?: readonly string[]): '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.
+ */
+export declare function readVersion(): string;
+/** Human-readable product + channel names for the running skin. */
+export declare function skinLabels(skin?: 'wa' | 'rcs'): {
+    product: string;
+    channel: string;
+    slug: string;
+};
+/**
+ * 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.
+ */
+export declare function normalizeChannel(value: unknown): Channel | undefined;
+export interface RequestSpec {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Path under the gateway root, e.g. "/templates" or "/marketplace/:id/clone". */
+    path: string;
+    /**
+     * Query parameters. Booleans serialise as the literal `true` / `false` the
+     * gateway's flag filters parse — never as a truthy/falsy coercion, which is
+     * how `?unread=false` would otherwise come out meaning "unread only".
+     */
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+}
+/** A gateway error carrying the HTTP status + the server's error envelope. */
+export declare class GatewayError extends Error {
+    status: number;
+    details?: unknown;
+    constructor(message: string, status: number, details?: unknown);
+}
+/**
+ * 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.
+ */
+export declare function resolveConfig(partial?: Partial<GatewayConfig>): GatewayConfig;
+export declare class GatewayClient {
+    private readonly config;
+    constructor(config: GatewayConfig);
+    static fromEnv(partial?: Partial<GatewayConfig>): GatewayClient;
+    /** Issue a request against the gateway and return `data` from the envelope. */
+    call<T = unknown>(spec: RequestSpec): Promise<T>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,4EAA4E;AAC5E,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,UAAU,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAE,SAAS,MAAM,EAAiB,GAAG,IAAI,GAAG,KAAK,CAO/E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,MAAM,CASpC;AAED,mEAAmE;AACnE,wBAAgB,UAAU,CAAC,IAAI,GAAE,IAAI,GAAG,KAAoB;;;;EAI3D;AA6BD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAMpE;AAOD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACpD,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IAC9D,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,8EAA8E;AAC9E,qBAAa,YAAa,SAAQ,KAAK;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;gBACN,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAM/D;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CA4B7E;AAED,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAElD,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa;IAI/D,+EAA+E;IACzE,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;CAmCvD"}