@advertising-chat/mcp 0.2.1 → 0.17.3

package/README.md

@@ -1,21 +1,115 @@
 # @advertising-chat/mcp
 
-MCP server for [Advertising.chat](https://advertising.chat) — give any
-agent the ability to serve (clearly labeled) sponsored messages and earn
-revenue from its conversations.
+The MCP server for [Advertising.chat](https://advertising.chat). It runs in
+one of two modes:
+
+- **manage**: run Offer Manager from Claude Code, Claude Desktop, or any MCP
+  host, with your own login. Agents, moments, rules, and offers; why a
+  customer did or did not see an offer; the docs.
+- **serve**: give an agent the in-chat ad tools (`fetch_ad`,
+  `record_event`, `record_reply`) with an API key.
+
+## Manage Offer Manager
+
+Sign in once. The login is the same as the `ads` command line tool's
+(`~/.ads-cli`), so signing in with either signs in both:
 
 ```bash
-ADCHAT_API_KEY=... npx @advertising-chat/mcp
+npx @advertising-chat/mcp login
 ```
 
-Agent host config:
+Then add the server to your host:
+
+```json
+{
+  "mcpServers": {
+    "advertising-chat": {
+      "command": "npx",
+      "args": ["-y", "@advertising-chat/mcp", "manage"]
+    }
+  }
+}
+```
+
+Every call runs as you, with your role in the org: a viewer can read, and an
+editor can also create, change, and delete. Changes are recorded as made
+through the MCP server (`_audit.updatedBy.agent` is `mcp`).
+
+| Variable | Meaning |
+|---|---|
+| `ADCHAT_ORG` | The org to work in. Default: your own. |
+| `ADCHAT_TOKEN` | An access token to use instead of the cached login. |
+| `ADS_API_ROOT` | Another gateway, e.g. `http://localhost:8380/system`. |
+| `ADCHAT_SYSTEM_REQUEST` | `true` for sysops working in another org (with `ADCHAT_ORG`). |
+
+`manage --read-only` registers only the tools that read.
+
+### Tools
+
+| Tool | Kind | Role |
+|---|---|---|
+| `whoami`, `list_applications` | read | viewer |
+| `list_moments`, `get_moment` | read | viewer |
+| `create_moment`, `update_moment` | write | editor |
+| `list_attributes`, `get_attribute` | read | viewer |
+| `add_attribute`, `document_attribute`, `update_attribute` | write | editor |
+| `translate_rule_text`, `describe_rule`, `preview_rule_impact` | read | viewer |
+| `list_rules`, `get_rule` | read | viewer |
+| `create_rule`, `update_rule` | write | editor |
+| `list_offers`, `get_offer` | read | viewer |
+| `create_offer`, `update_offer`, `publish_offer`, `pause_offer` | write | editor |
+| `get_offer_limit` | read | viewer |
+| `set_offer_limit` | write | editor |
+| `delete_moment`, `delete_attribute`, `delete_rule`, `delete_offer` | destructive | editor |
+| `get_results`, `get_network_status` | read | viewer |
+| `set_network_ads` | write | editor |
+| `list_campaigns`, `get_campaign` | read | viewer |
+| `request_campaign`, `pause_campaign`, `resume_campaign`, `resubmit_campaign` | write | editor |
+| `find_requests`, `explain_decision`, `get_stats` | read | viewer |
+| `search_docs`, `read_doc` | read | viewer |
+
+Offers, rules, customer details (attributes), and translation need Offer
+Manager in the workspace, and campaigns need campaigns (`advertise`); the
+tool says so (`capability` in the table). Results, moments, and ads from the
+network work in any workspace. Every
+change carries a plain sentence for the person approving it
+(`approvalSentence(tool, input, before)`).
+
+Moments and rules belong to one agent: their tools take the agent as
+`application`. Rule inputs are the schemas of
+[`@advertising-chat/offer-rules`](https://docs.advertising.chat/reference/rules/),
+the package the platform validates rules with, and a rule is checked before
+it is sent. Rules are created disabled unless you ask to launch. How often
+an offer appears is its rule's `frequency`; the workspace's offer limit
+(`get_offer_limit`, `set_offer_limit`) caps how many of the brand's offers
+one customer sees in a period.
+
+### In your own code
+
+The tool table is importable. The Advertising.chat console's Assistant runs
+the same definitions in process:
+
+```ts
+import { DocsIndex, ManageClient, toolsByName } from '@advertising-chat/mcp';
+
+const client = new ManageClient({ authorization: `Bearer ${token}`, org });
+const rules = await toolsByName
+  .get('list_rules')!
+  .run({ client, docs: new DocsIndex() }, { application });
+```
+
+Each tool has a `kind` (`read`, `write`, `destructive`), a `roleFloor`, a
+zod `input` shape, and, for a change to one record, the `reader` tool that
+returns it.
+
+## Serve in-chat ads
 
 ```json
 {
   "mcpServers": {
     "adchat": {
       "command": "npx",
-      "args": ["-y", "@advertising-chat/mcp"],
+      "args": ["-y", "@advertising-chat/mcp", "serve"],
       "env": {
         "ADCHAT_API_KEY": "<your key from console.advertising.chat>",
         "ADCHAT_AD_UNIT": "<optional default ad unit>"
@@ -25,19 +119,30 @@ Agent host config:
 }
 ```
 
-## Tools
+Without a mode argument the server serves when `ADCHAT_API_KEY` is set, and
+manages otherwise.
+
+Use a fetch key: it is bound to one application (agent), so nothing else is
+needed. With any other key, also set `ADCHAT_APPLICATION` to the
+application's id, or fetches are rejected with a 422.
 
-- **`fetch_ad`** — fetch one sponsored message for the current
-  conversation. Takes `conversation_context` (a short topic/intent
-  summary used only to select the ad), optional `subscriber` (anonymous
-  id for frequency capping), `ad_unit`, `format`. Returns the ad with a
-  mandatory sponsored-disclosure reminder and click-tracked URLs, or
-  `no_ad`.
-- **`record_event`** — report engagement (`click`, `conversion` with
-  optional value/currency, or message lifecycle events) for a fetched ad.
+- **`fetch_ad`**: fetch one sponsored message for the current
+  conversation. Takes `conversation_context` (a short topic and intent
+  summary used only to select the ad), an optional `subscriber` (an
+  anonymous id for frequency capping), `ad_unit`, and `format`. Returns the
+  ad with a mandatory sponsored-disclosure reminder and click-tracked URLs,
+  or `no_ad`.
+- **`record_event`**: report engagement (`click`, `conversion` with an
+  optional value and currency, or message lifecycle events) for a fetched
+  ad.
+- **`record_reply`**: report that the user chose one of the ad's replies,
+  with the reply's `postback_data` from `fetch_ad`. A reply that accepts or
+  declines the offer is recorded as the customer's response, which rules
+  can use.
 
 Pair it with the [Ad Skill](https://github.com/advertising-chat/adkit/blob/main/skill/SKILL.md)
-so your assistant knows *when* to fetch and how to present ads.
+so your assistant knows when to fetch and how to present ads.
 
-Env: `ADCHAT_API_KEY` (required), `ADCHAT_AD_UNIT`, `ADCHAT_BASE_URL`.
-Quickstart: [docs.advertising.chat](https://docs.advertising.chat).
+Variables: `ADCHAT_API_KEY` (required), `ADCHAT_APPLICATION`,
+`ADCHAT_AD_UNIT`, `ADCHAT_BASE_URL`. Quickstart:
+[docs.advertising.chat](https://docs.advertising.chat).

package/bin/auth.d.ts

@@ -0,0 +1,46 @@
+export declare const AUTH0_DOMAIN = "advertising-chat.us.auth0.com";
+/** The "Advertising.chat CLI" Auth0 native client (device-code flow). */
+export declare const AUTH0_CLIENT_ID = "rZ67p5ctrl5dwcl38ZyjYNGVf7PFb11B";
+export declare const AUTH0_AUDIENCE = "https://api.advertising.chat/";
+export declare const TOKEN_CACHE_PATH: string;
+export interface CachedToken {
+    access_token: string;
+    token_type?: string;
+    expires_in?: number;
+    /** Epoch ms when the token was obtained. */
+    obtained_at?: number;
+    refresh_token?: string;
+}
+export interface TokenProviderOptions {
+    /** Explicit access token (ADCHAT_TOKEN). Wins over the cache. */
+    token?: string;
+    /** Cache path override (tests). */
+    cachePath?: string;
+    fetchFn?: typeof fetch;
+}
+export declare function loadCachedToken(path?: string): CachedToken | null;
+export declare function saveCachedToken(token: CachedToken, path?: string): void;
+export declare function clearCachedToken(path?: string): void;
+/** An async provider of a current access token. */
+export declare function createTokenProvider(options?: TokenProviderOptions): () => Promise<string>;
+export interface DeviceCode {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+}
+export interface DeviceLoginOptions {
+    cachePath?: string;
+    fetchFn?: typeof fetch;
+    /** Called once with the code the user confirms in the browser. */
+    prompt: (device: DeviceCode) => void;
+    /** Sleep between polls (tests). */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * The device-code flow: request a code, let the user confirm it in a
+ * browser, poll until Auth0 issues tokens, and cache them.
+ */
+export declare function deviceLogin(options: DeviceLoginOptions): Promise<CachedToken>;

package/bin/auth.js

@@ -0,0 +1,186 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOKEN_CACHE_PATH = exports.AUTH0_AUDIENCE = exports.AUTH0_CLIENT_ID = exports.AUTH0_DOMAIN = void 0;
+exports.loadCachedToken = loadCachedToken;
+exports.saveCachedToken = saveCachedToken;
+exports.clearCachedToken = clearCachedToken;
+exports.createTokenProvider = createTokenProvider;
+exports.deviceLogin = deviceLogin;
+/**
+ * Sign-in for the management tools: the user's own Auth0 login.
+ *
+ * `adchat-mcp login` runs the Auth0 device-code flow with the
+ * "Advertising.chat CLI" native client, the same client and token cache
+ * (`~/.ads-cli`) as `ads login` in ads-cli, so signing in with either signs
+ * in both. The server then reads the cache and refreshes the access token
+ * with the cached refresh token when it nears expiry, writing the new token
+ * back. `ADCHAT_TOKEN` overrides the cache with an explicit access token.
+ *
+ * Tokens are never logged.
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+exports.AUTH0_DOMAIN = 'advertising-chat.us.auth0.com';
+/** The "Advertising.chat CLI" Auth0 native client (device-code flow). */
+exports.AUTH0_CLIENT_ID = 'rZ67p5ctrl5dwcl38ZyjYNGVf7PFb11B';
+exports.AUTH0_AUDIENCE = 'https://api.advertising.chat/';
+exports.TOKEN_CACHE_PATH = `${os.homedir()}/.ads-cli`;
+/** Refresh five minutes before expiry. */
+const EXPIRY_BUFFER_MS = 5 * 60 * 1000;
+function loadCachedToken(path = exports.TOKEN_CACHE_PATH) {
+    try {
+        if (!fs.existsSync(path))
+            return null;
+        return JSON.parse(fs.readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function saveCachedToken(token, path = exports.TOKEN_CACHE_PATH) {
+    fs.writeFileSync(path, JSON.stringify(token, null, 2), { mode: 0o600 });
+}
+function clearCachedToken(path = exports.TOKEN_CACHE_PATH) {
+    if (fs.existsSync(path))
+        fs.unlinkSync(path);
+}
+function isExpired(token) {
+    // Without timing information there is no way to tell: assume valid.
+    if (!token.obtained_at || !token.expires_in)
+        return false;
+    return (Date.now() >= token.obtained_at + token.expires_in * 1000 - EXPIRY_BUFFER_MS);
+}
+async function postJson(fetchFn, path, body) {
+    const res = await fetchFn(`https://${exports.AUTH0_DOMAIN}${path}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    const data = (await res.json().catch(() => ({})));
+    return { ok: res.ok, status: res.status, data };
+}
+async function refresh(token, cachePath, fetchFn) {
+    if (!token.refresh_token) {
+        throw new Error('Your Advertising.chat session expired. Run `npx @advertising-chat/mcp login` to sign in again.');
+    }
+    const res = await postJson(fetchFn, '/oauth/token', {
+        grant_type: 'refresh_token',
+        client_id: exports.AUTH0_CLIENT_ID,
+        refresh_token: token.refresh_token,
+    });
+    if (!res.ok) {
+        throw new Error(`Token refresh failed (${res.status}). Run \`npx @advertising-chat/mcp login\` to sign in again.`);
+    }
+    const updated = {
+        access_token: res.data.access_token,
+        token_type: res.data.token_type,
+        expires_in: res.data.expires_in,
+        obtained_at: Date.now(),
+        refresh_token: res.data.refresh_token || token.refresh_token,
+    };
+    saveCachedToken(updated, cachePath);
+    return updated;
+}
+/** An async provider of a current access token. */
+function createTokenProvider(options = {}) {
+    const cachePath = options.cachePath || exports.TOKEN_CACHE_PATH;
+    const fetchFn = options.fetchFn || fetch.bind(globalThis);
+    return async () => {
+        if (options.token)
+            return options.token;
+        const cached = loadCachedToken(cachePath);
+        if (!cached) {
+            throw new Error('Not signed in. Run `npx @advertising-chat/mcp login` (or `ads login`), or set ADCHAT_TOKEN.');
+        }
+        if (isExpired(cached)) {
+            return (await refresh(cached, cachePath, fetchFn)).access_token;
+        }
+        return cached.access_token;
+    };
+}
+/**
+ * The device-code flow: request a code, let the user confirm it in a
+ * browser, poll until Auth0 issues tokens, and cache them.
+ */
+async function deviceLogin(options) {
+    const fetchFn = options.fetchFn || fetch.bind(globalThis);
+    const sleep = options.sleep || ((ms) => new Promise(r => setTimeout(r, ms)));
+    const code = await postJson(fetchFn, '/oauth/device/code', {
+        client_id: exports.AUTH0_CLIENT_ID,
+        audience: exports.AUTH0_AUDIENCE,
+        scope: 'openid profile email offline_access',
+    });
+    if (!code.ok)
+        throw new Error(`Could not start sign-in (${code.status}).`);
+    const device = code.data;
+    options.prompt(device);
+    const deadline = Date.now() + device.expires_in * 1000;
+    let interval = device.interval * 1000;
+    while (Date.now() < deadline) {
+        await sleep(interval);
+        const res = await postJson(fetchFn, '/oauth/token', {
+            grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+            client_id: exports.AUTH0_CLIENT_ID,
+            device_code: device.device_code,
+        });
+        if (res.ok) {
+            const token = {
+                access_token: res.data.access_token,
+                token_type: res.data.token_type,
+                expires_in: res.data.expires_in,
+                obtained_at: Date.now(),
+                refresh_token: res.data.refresh_token,
+            };
+            saveCachedToken(token, options.cachePath);
+            return token;
+        }
+        switch (res.data.error) {
+            case 'authorization_pending':
+                continue;
+            case 'slow_down':
+                interval += 5000;
+                continue;
+            case 'access_denied':
+                throw new Error('Sign-in was denied.');
+            case 'expired_token':
+                throw new Error('The sign-in code expired. Run login again.');
+            default:
+                throw new Error(`Sign-in failed: ${res.data.error ?? res.status}`);
+        }
+    }
+    throw new Error('The sign-in code expired. Run login again.');
+}
+//# sourceMappingURL=auth.js.map

package/bin/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/bin/cli.js

@@ -2,31 +2,99 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 /**
- * AdKit MCP server (stdio).
+ * adchat-mcp: the Advertising.chat MCP server (stdio).
  *
- * Usage: set ADCHAT_API_KEY (and optionally ADCHAT_AD_UNIT), then run
- * `npx @advertising-chat/mcp` from any MCP-capable agent host.
+ *   adchat-mcp login        sign in (device code; shares ~/.ads-cli with `ads login`)
+ *   adchat-mcp logout       forget the cached login
+ *   adchat-mcp manage       Offer Manager tools, as the signed-in user
+ *   adchat-mcp serve        in-chat ad tools (fetch_ad, record_event), with ADCHAT_API_KEY
+ *   adchat-mcp              `serve` when ADCHAT_API_KEY is set, otherwise `manage`
+ *
+ * manage: ADCHAT_ORG picks the org (default: the user's own), ADCHAT_TOKEN
+ * overrides the cached login, `--read-only` registers only read tools,
+ * ADS_API_ROOT points at another gateway (`http://localhost:8380/system`),
+ * and ADCHAT_SYSTEM_REQUEST=true (sysops, with ADCHAT_ORG) works in another
+ * org. serve: ADCHAT_APPLICATION, ADCHAT_AD_UNIT, ADCHAT_BASE_URL.
+ *
+ * stdout carries the MCP protocol, so everything for people goes to stderr.
  */
+const child_process_1 = require("child_process");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const auth_1 = require("./auth");
+const client_1 = require("./client");
+const serve_1 = require("./serve");
 const server_1 = require("./server");
-async function main() {
+const say = (line = '') => process.stderr.write(`${line}\n`);
+function openBrowser(url) {
+    const cmd = process.platform === 'darwin'
+        ? `open "${url}"`
+        : process.platform === 'win32'
+            ? `start "" "${url}"`
+            : `xdg-open "${url}"`;
+    (0, child_process_1.exec)(cmd, () => undefined);
+}
+function manageClient() {
+    const getToken = (0, auth_1.createTokenProvider)({ token: process.env.ADCHAT_TOKEN });
+    return new client_1.ManageClient({
+        authorization: async () => `Bearer ${await getToken()}`,
+        org: process.env.ADCHAT_ORG,
+        systemRequest: process.env.ADCHAT_SYSTEM_REQUEST === 'true',
+        baseUrl: process.env.ADS_API_ROOT,
+        agent: 'mcp',
+    });
+}
+async function login() {
+    await (0, auth_1.deviceLogin)({
+        prompt: device => {
+            say(`Your code: ${device.user_code}`);
+            say(`Confirm it at ${device.verification_uri_complete}`);
+            say('Waiting for you to sign in in the browser...');
+            openBrowser(device.verification_uri_complete);
+        },
+    });
+    const me = await manageClient().get('/user/me');
+    say(`Signed in as ${me?.email ?? 'unknown'}${me?.org?.name ? ` (${me.org.name})` : ''}. The login is cached at ${auth_1.TOKEN_CACHE_PATH}.`);
+}
+async function manage(readOnly) {
+    const server = (0, server_1.createManageServer)({ client: manageClient(), readOnly });
+    await server.connect(new stdio_js_1.StdioServerTransport());
+    say('Advertising.chat MCP server running (manage, stdio)');
+}
+async function serve() {
     const apiKey = process.env.ADCHAT_API_KEY;
     if (!apiKey) {
-        console.error('ADCHAT_API_KEY is required. Get an API key from the ' +
-            'Advertising.chat console (https://console.advertising.chat) and ' +
-            'set it in the MCP server environment.');
+        say('ADCHAT_API_KEY is required for serve. Create an API key in the console (https://console.advertising.chat) and set it in the MCP server environment.');
         process.exit(1);
     }
-    const server = (0, server_1.createAdKitServer)({
+    const server = (0, serve_1.createAdKitServer)({
         apiKey,
+        application: process.env.ADCHAT_APPLICATION,
         adUnit: process.env.ADCHAT_AD_UNIT,
         baseUrl: process.env.ADCHAT_BASE_URL,
     });
     await server.connect(new stdio_js_1.StdioServerTransport());
-    console.error('AdKit MCP server running (stdio)');
+    say('Advertising.chat MCP server running (serve, stdio)');
+}
+async function main(argv) {
+    const command = argv.find(a => !a.startsWith('-')) ??
+        (process.env.ADCHAT_API_KEY ? 'serve' : 'manage');
+    switch (command) {
+        case 'login':
+            return login();
+        case 'logout':
+            (0, auth_1.clearCachedToken)();
+            return say('Signed out.');
+        case 'manage':
+            return manage(argv.includes('--read-only'));
+        case 'serve':
+            return serve();
+        default:
+            say(`Unknown command "${command}". Use login, logout, manage, or serve.`);
+            process.exit(2);
+    }
 }
-main().catch(err => {
-    console.error('AdKit MCP server failed to start:', err);
+main(process.argv.slice(2)).catch(err => {
+    say(`adchat-mcp: ${err instanceof Error ? err.message : String(err)}`);
     process.exit(1);
 });
 //# sourceMappingURL=cli.js.map

package/bin/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;AACA;;;;;GAKG;AACH,wEAAiF;AACjF,qCAA6C;AAE7C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,CAAC,KAAK,CACX,sDAAsD;YACpD,kEAAkE;YAClE,uCAAuC,CAC1C,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,IAAA,0BAAiB,EAAC;QAC/B,MAAM;QACN,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc;QAClC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe;KACrC,CAAC,CAAC;IAEH,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,+BAAoB,EAAE,CAAC,CAAC;IACjD,OAAO,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;AACpD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;IACjB,OAAO,CAAC,KAAK,CAAC,mCAAmC,EAAE,GAAG,CAAC,CAAC;IACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/bin/client.d.ts

@@ -0,0 +1,70 @@
+/**
+ * HTTP client for the Advertising.chat management API, the api gateway's
+ * `/system/*` surface.
+ *
+ * Every request carries the user's own Auth0 bearer token, the org it acts
+ * in (`X-Adchat-Target-Org`), and the surface that made it
+ * (`X-Adchat-Agent`, stamped into `_audit` on every write). The client holds
+ * no platform credential, so a tool can do exactly what the user could do
+ * in the console and nothing more. Tokens are never logged.
+ */
+export declare const DEFAULT_API_URL = "https://api.advertising.chat/system";
+/** Surfaces that call the management API, as carried in `X-Adchat-Agent`. */
+export type Surface = 'mcp' | 'copilot' | 'cli' | 'console';
+export interface ManageClientOptions {
+    /**
+     * The `Authorization` header value (`Bearer <token>`), or an async
+     * provider of it (the MCP server refreshes the cached login).
+     */
+    authorization: string | (() => Promise<string>);
+    /**
+     * Target org id. When omitted, the client resolves the user's own org
+     * once with `GET /user/me`.
+     */
+    org?: string;
+    /**
+     * Sysop cross-org mode: also send `X-Adchat-System-Request: true`.
+     * Only meaningful for members of the sysop org; requires `org`.
+     */
+    systemRequest?: boolean;
+    /** The `/system` root. Defaults to production. */
+    baseUrl?: string;
+    /** Attribution for `_audit`. Defaults to `mcp`. */
+    agent?: Surface;
+    /** Per-request timeout. Default 30 seconds. */
+    timeoutMs?: number;
+    /** Override fetch (tests). */
+    fetchFn?: typeof fetch;
+}
+/** A non-2xx answer from the management API. */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    /** Parsed response body (JSON when the server sent JSON). */
+    readonly body?: unknown | undefined;
+    constructor(status: number, method: string, path: string, 
+    /** Parsed response body (JSON when the server sent JSON). */
+    body?: unknown | undefined);
+}
+export type QueryParams = Record<string, string | number | boolean | undefined>;
+export declare class ManageClient {
+    private readonly opts;
+    private org;
+    private readonly baseUrl;
+    private readonly agent;
+    constructor(opts: ManageClientOptions);
+    get<T = unknown>(path: string, query?: QueryParams): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown): Promise<T>;
+    delete<T = unknown>(path: string): Promise<T>;
+    /** The org requests act in, resolving the user's own org if needed. */
+    resolveOrg(): Promise<string>;
+    /** `path` is relative to `/system`, e.g. `/offer-manager/adunit`. */
+    request<T>(method: string, path: string, { query, body, withOrg, }: {
+        query?: QueryParams;
+        body?: unknown;
+        withOrg?: boolean;
+    }): Promise<T>;
+}