@attrkit/mcp 1.2.1 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 1.4.0 (2026-10-21)
+
+### Added
+
+- `create_integration` accepts two optional options for a Meta or TikTok integration:
+  `delivery_scope` (`all` or `attributed`) and `renewal_event` (`purchase` or `custom`). Each is
+  sent only when you give it, so a create without them sends exactly what 1.3.0 sent, and the API
+  applies its defaults, `all` and `purchase`. Existing integrations are unchanged.
+- `update_integration` has a new action, `set_delivery_options`, which sets `delivery_scope`,
+  `renewal_event` or both in any status and leaves the credential and status as they were. The
+  API refuses the action when it names neither option, and refuses `attributed` or `custom` on a
+  Google integration.
+- `list_event_deliveries` names `attributed_only_suppressed` among the reasons it can return: the
+  connection sends only the events of installs attributed to its network, and this install is
+  organic or attributed to another network.
+
+## 1.3.0 (2026-10-20)
+
+### Added
+
+- `list_event_deliveries` (`GET /api/v1/apps/{appId}/deliveries`, read scope): what happened to
+  each event the app sent to its ad networks, one row per delivery, newest first. Each row gives
+  the state (`held`, `queued`, `sending`, `retrying`, `sent`, `suppressed` or `failed`), the reason
+  with a one-line explanation, the attempt count, the last attempt's time and HTTP status, and for
+  a held row the time it is expected to be released. Filters: `install_id`, `event_id`,
+  `connection_id`, `network`, `state`, `from`, `to`; paged with `cursor` and `limit` (50 by
+  default, 200 at most). No other tool changes.
+
 ## 1.2.1 (2026-10-03)
 
 ### Fixed

package/README.md

@@ -7,7 +7,7 @@ tenant scope is resolved from your secret management key.
 
 ## What it exposes
 
-The server provides 38 tools.
+The server provides 39 tools.
 
 | Area | Tools |
 |---|---|
@@ -17,7 +17,7 @@ The server provides 38 tools.
 | SDK keys | `get_publishable_key`, `rotate_publishable_key` |
 | Management keys | `list_api_keys`, `create_api_key`, `revoke_api_key` |
 | Campaign links | `list_links`, `create_campaign_link`, `update_link_status` |
-| Decisions and reporting | `list_campaigns`, `list_ads`, `list_recent_events`, `get_campaign_decision`, `record_campaign_decision`, `get_attribution_rollup`, `lookup_customer_attribution` |
+| Decisions and reporting | `list_campaigns`, `list_ads`, `list_recent_events`, `list_event_deliveries`, `get_campaign_decision`, `record_campaign_decision`, `get_attribution_rollup`, `lookup_customer_attribution` |
 | Spend and costs | `get_spend`, `import_spend`, `set_cost_model`, `pull_network_spend` |
 | Ad integrations | `list_integrations`, `create_integration`, `update_integration`, `delete_integration` |
 | RevenueCat | `get_revenuecat`, `configure_revenuecat` |
@@ -28,6 +28,16 @@ The server provides 38 tools.
 `get_campaign_decision` returns the engine's call verbatim. The model reports it;
 it does not recompute it.
 
+A Meta or TikTok integration has two delivery options. `delivery_scope` is `all`
+(the default: every install with measurement consent, organic ones included) or
+`attributed` (only installs AttriKit attributes to that network: a click ID, a link
+token, or a device match at or above the delivery floor). `renewal_event`
+is `purchase` (the default: a renewal is sent as Purchase) or `custom` (it is
+sent as the custom event `subscription_renewed`, with its value). Set them on
+`create_integration`, or later with `update_integration` and the action
+`set_delivery_options`, which leaves the credential and status as they are. A
+Google integration refuses `attributed` and `custom`.
+
 ## Before you connect
 
 Install Node.js 18 or newer. The `npx -y @attrkit/mcp` command downloads and

package/dist/cli.js

@@ -13710,6 +13710,33 @@ var CLASS_LISTS = [
   { ipClass: "relay", parsed: parseRanges(ip_class_ranges_default.apple_private_relay_egress, "relay") }
 ];
 var IP_CLASS_RANGES_VERSION = ip_class_ranges_default.ranges_version;
+// ../shared/src/meta-errors.ts
+var META_NOT_SERVING_CODES = new Set([
+  2,
+  4,
+  17,
+  32,
+  341,
+  613,
+  80000,
+  80001,
+  80002,
+  80003,
+  80004,
+  80005,
+  80006,
+  80008,
+  80009,
+  80014
+]);
+var META_TOKEN_CODES = new Set([102, 190]);
+var META_ACCESS_CODES = new Set([
+  10,
+  ...Array.from({ length: 100 }, (_, offset) => 200 + offset)
+]);
+var META_ACCESS_SUBCODES = new Map([
+  [100, new Set([33])]
+]);
 // ../shared/src/canonical-events.ts
 var LEDGER_ONLY_CANONICAL_EVENT_NAMES = Object.freeze(["refund_reversed"]);
 // ../shared/src/derived-events.ts
@@ -14850,11 +14877,11 @@ function invalidResult(code, message) {
     json: { error: { code, message } }
   };
 }
-function buildRequestUrl(baseUrl2, path, query) {
+function buildRequestUrl(baseUrl, path, query) {
   if (!path.startsWith("/") || hasUnsafePathCharacter(path)) {
     throw new Error("path must be an absolute URL path without whitespace or control characters");
   }
-  const url = new URL(`${baseUrl2.href.replace(/\/+$/, "")}${path}`);
+  const url = new URL(`${baseUrl.href.replace(/\/+$/, "")}${path}`);
   for (const [key, value] of Object.entries(query ?? {})) {
     if (value !== undefined && value !== "")
       url.searchParams.set(key, value);
@@ -14919,15 +14946,15 @@ function apiResultFromResponse(response, text, expectedResponse) {
 }
 async function callApi(config, path, options = {}) {
   const doFetch = options.fetchImpl ?? fetch;
-  let baseUrl2;
+  let baseUrl;
   try {
-    baseUrl2 = validatedApiBaseUrl(config.apiUrl);
+    baseUrl = validatedApiBaseUrl(config.apiUrl);
   } catch (error) {
     return invalidResult("invalid_api_url", `ATTRKIT_API_URL is invalid: ${error instanceof Error ? error.message : String(error)}`);
   }
   let url;
   try {
-    url = buildRequestUrl(baseUrl2, path, options.query);
+    url = buildRequestUrl(baseUrl, path, options.query);
   } catch (error) {
     return invalidResult("invalid_path", `AttriKit API path is invalid: ${error instanceof Error ? error.message : String(error)}`);
   }
@@ -15055,13 +15082,15 @@ ${body}`
     structuredContent: structured
   }, result.nextCursor);
 }
-var SERVER_VERSION = "1.2.1";
+var SERVER_VERSION = "1.4.0";
 var periodSchema = z5.enum(["7d", "30d", "90d", "all"]).describe("Reporting window. Omit to use the endpoint's documented default.").optional();
 var appIdSchema = z5.string().describe("Optional app id to scope the result to one app.").optional();
 var requiredAppIdSchema = z5.string().min(1).describe("The AttriKit app id.");
 var encodeOpaquePathSegment = (value) => encodeURIComponent(value).replaceAll(".", "%252E");
 var idempotencyKeySchema = z5.string().max(255).describe("Stable retry key for this exact mutation.").optional();
 var ownersSchema = z5.record(z5.string(), z5.enum(["attrkit", "revenuecat", "customer"]));
+var deliveryScopeSchema = z5.enum(["all", "attributed"]).optional().describe("Which events a Meta or TikTok integration sends. all (the API's default): the events of every install with measurement consent, organic ones included. attributed: send only events of installs AttriKit attributes to this connection's network (click ID, link token, or device match at or above the delivery floor); others are suppressed with attributed_only_suppressed. Meta and TikTok only: a Google integration refuses attributed.");
+var renewalEventSchema = z5.enum(["purchase", "custom"]).optional().describe("How a renewal reaches Meta website and TikTok web events. purchase (the API's default): as Purchase with its price and currency. custom: as the custom event subscription_renewed with its price and currency, so Purchase counts one-time purchases only. App events are unchanged. A Google integration refuses custom.");
 var cursorSchema = z5.string().optional().describe("Pass the next_cursor from the previous response to fetch the following page. Omit for the first page.");
 var listLimitSchema = z5.number().int().min(1).max(200).optional().describe("Rows per page, 1-200. The API defaults to 50, so a workspace with more than that needs paging.");
 var calendarDaySchema = z5.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Use a UTC calendar day, YYYY-MM-DD.");
@@ -15413,6 +15442,35 @@ function createServer(config, fetchImpl) {
       limit: limit === undefined ? undefined : String(limit)
     }
   })));
+  server.registerTool("list_event_deliveries", {
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    title: "List what happened to each event sent to ad networks",
+    description: "Return one row per delivery of an event to a network connection, newest first: its state (held, queued, sending, retrying, sent, suppressed or failed), the reason with a one-line explanation (for example consent_suppressed, attributed_only_suppressed or destination_event_too_old), attempts, the last HTTP status, and for a held row when it is expected to be released. Use it to answer why an event did not reach Meta, TikTok or Google. Read scope is enough.",
+    inputSchema: {
+      app_id: requiredAppIdSchema,
+      install_id: z5.string().optional().describe("Only this install: the install epoch id the events feed and the export call the install id."),
+      event_id: z5.string().optional().describe("Only this event's deliveries, one per connection that receives it."),
+      connection_id: z5.string().optional().describe("Only this network connection, as returned by list_integrations."),
+      network: z5.string().optional().describe("Only connections to this network, for example meta."),
+      state: z5.enum(["held", "queued", "sending", "retrying", "sent", "suppressed", "failed"]).optional().describe("Only deliveries in this state."),
+      from: calendarDaySchema.optional().describe("First UTC day the event was received, YYYY-MM-DD. May be sent without to."),
+      to: calendarDaySchema.optional().describe("Last UTC day the event was received, YYYY-MM-DD, inclusive. May be sent without from."),
+      cursor: cursorSchema,
+      limit: listLimitSchema
+    }
+  }, async ({ app_id, install_id, event_id, connection_id, network, state, from, to, cursor, limit }) => toToolResult(await call(`/api/v1/apps/${encodeOpaquePathSegment(app_id)}/deliveries`, {
+    query: {
+      installId: install_id,
+      eventId: event_id,
+      connectionId: connection_id,
+      network,
+      state,
+      from,
+      to,
+      cursor,
+      limit: limit === undefined ? undefined : String(limit)
+    }
+  })));
   server.registerTool("get_campaign_decision", {
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     title: "Get campaign decisions (scale / cut / hold)",
@@ -15661,33 +15719,48 @@ function createServer(config, fetchImpl) {
   server.registerTool("create_integration", {
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     title: "Create an ad-network integration",
-    description: "Store encrypted network credentials and choose, for each of the eight event families (install, session, trial, subscription, purchase, refund, paywall, business), which source's copy AttriKit forwards to the network. AttriKit always does the sending; the owner only picks the copy. attrkit = the events your app reports through the AttriKit SDK (the RevenueCat copy of that family is dropped). revenuecat = the events AttriKit received from your RevenueCat webhook (the SDK copy is dropped); RevenueCat itself sends nothing to the network. customer = events your own servers post to AttriKit. If your app reports subscriptions only through RevenueCat, set trial, subscription, purchase and refund to revenuecat, or none of them reach the network.",
+    description: "Store encrypted network credentials and choose, for each of the eight event families (install, session, trial, subscription, purchase, refund, paywall, business), which source's copy AttriKit forwards to the network. AttriKit always does the sending; the owner only picks the copy. attrkit = the events your app reports through the AttriKit SDK (the RevenueCat copy of that family is dropped). revenuecat = the events AttriKit received from your RevenueCat webhook (the SDK copy is dropped); RevenueCat itself sends nothing to the network. customer = events your own servers post to AttriKit. If your app reports subscriptions only through RevenueCat, set trial, subscription, purchase and refund to revenuecat, or none of them reach the network. For Meta and TikTok, delivery_scope and renewal_event are optional; left out, the integration sends every install's events and renewals as Purchase.",
     inputSchema: {
       network: z5.enum(["meta", "google", "tiktok"]),
       account_ref: z5.string().min(1),
       credential: z5.string().min(1),
       owners: ownersSchema.describe("For each event family, whose copy is forwarded: attrkit, revenuecat or customer (see the tool description). Enabling a destination requires ALL eight families to be present, or the API rejects the call."),
       enable: z5.boolean().optional(),
+      delivery_scope: deliveryScopeSchema,
+      renewal_event: renewalEventSchema,
       idempotency_key: idempotencyKeySchema
     }
-  }, async ({ network, account_ref, credential, owners, enable, idempotency_key }) => toToolResult(await call("/api/v1/integrations", {
-    method: "POST",
-    idempotencyKey: idempotency_key,
-    body: { network, account_ref, credential, owners, enable: enable ?? false }
-  })));
+  }, async ({ network, account_ref, credential, owners, enable, delivery_scope, renewal_event, idempotency_key }) => {
+    const body = { network, account_ref, credential, owners, enable: enable ?? false };
+    if (delivery_scope !== undefined)
+      body.delivery_scope = delivery_scope;
+    if (renewal_event !== undefined)
+      body.renewal_event = renewal_event;
+    return toToolResult(await call("/api/v1/integrations", {
+      method: "POST",
+      idempotencyKey: idempotency_key,
+      body
+    }));
+  });
   server.registerTool("update_integration", {
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     title: "Update an ad-network integration",
-    description: "Rotate credentials or enable/disable an integration.",
+    description: "Rotate credentials or enable/disable an integration. set_delivery_options changes delivery_scope, renewal_event or both on a Meta or TikTok integration, in any status, without touching its credential or status; give at least one of the two.",
     inputSchema: {
       connection_id: z5.string(),
-      action: z5.enum(["rotate", "disable", "enable"]),
+      action: z5.enum(["rotate", "disable", "enable", "set_delivery_options"]),
       credential: z5.string().optional(),
       owners: ownersSchema.optional(),
+      delivery_scope: deliveryScopeSchema,
+      renewal_event: renewalEventSchema,
       idempotency_key: idempotencyKeySchema
     }
-  }, async ({ connection_id, action, credential, owners, idempotency_key }) => {
+  }, async ({ connection_id, action, credential, owners, delivery_scope, renewal_event, idempotency_key }) => {
     const body = { action };
+    if (delivery_scope !== undefined)
+      body.delivery_scope = delivery_scope;
+    if (renewal_event !== undefined)
+      body.renewal_event = renewal_event;
     if (credential !== undefined)
       body.credential = credential;
     if (owners)
@@ -15957,8 +16030,15 @@ function readHidden(input, prompt, write, idleMs = 50) {
     };
     const onData = (chunk) => {
       for (const character of chunk) {
+        if (character === "\x03" || character === "\x04")
+          return finish(null);
         if (mode === "drain")
           continue;
+        if (character === "\r" || character === `
+`) {
+          mode = "drain";
+          continue;
+        }
         if (mode === "escape") {
           mode = character === "[" ? "csi" : character === "O" ? "ss3" : "text";
         } else if (mode === "csi") {
@@ -15966,13 +16046,8 @@ function readHidden(input, prompt, write, idleMs = 50) {
             mode = "text";
         } else if (mode === "ss3") {
           mode = "text";
-        } else if (character === "\x03") {
-          return finish(null);
         } else if (character === "\x1B") {
           mode = "escape";
-        } else if (character === "\r" || character === `
-`) {
-          mode = "drain";
         } else if (character === "" || character === "\b") {
           value = value.slice(0, -1);
         } else if (character >= " ") {
@@ -16071,10 +16146,19 @@ async function runLogout(options = {}) {
     return 1;
   }
   const result = await (options.runSecurity ?? defaultSecurityRunner)(["delete-generic-password", "-s", KEYCHAIN_SERVICE]);
-  write(result.code === 0 ? `Removed the attrkit-mcp item from the macOS Keychain.
-` : `Nothing was stored in the Keychain for attrkit-mcp.
+  if (result.code === 0) {
+    write(`Removed the attrkit-mcp item from the macOS Keychain.
 `);
-  return 0;
+    return 0;
+  }
+  if (result.code === 44) {
+    write(`No attrkit-mcp item was found in the macOS Keychain; nothing to remove.
+`);
+    return 0;
+  }
+  write(`Could not remove the attrkit-mcp item from the macOS Keychain (security exit ${result.code}). It may still be stored.
+`);
+  return 1;
 }
 
 // src/main.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attrkit/mcp",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "AttriKit's stdio MCP server for its public Management API",
   "keywords": [
     "attrkit",
@@ -32,19 +32,19 @@
   "scripts": {
     "build": "bun build ./src/cli.ts --outdir ./dist --target=node --format=esm --external @modelcontextprotocol/sdk --external zod",
     "prepack": "bun run build",
-    "typecheck": "../../node_modules/typescript-7/bin/tsc --noEmit",
-    "lint": "eslint .",
+    "typecheck": "tsrs --noEmit",
+    "lint": "node ../../scripts/checks/code-quality-eslint.mjs --workspace packages/mcp",
     "test": "cd ../.. && vitest run packages/mcp/src"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.30.0",
-    "zod": "4.4.3"
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "zod": "4.6.7"
   },
   "devDependencies": {
     "@attrkit/shared": "workspace:*",
-    "@types/node": "26.1.1",
+    "@types/node": "26.6.5",
     "typescript": "6.0.3",
-    "vitest": "4.1.10"
+    "vitest": "5.0.4"
   },
   "publishConfig": {
     "access": "public"