@advertising-chat/sdk 0.2.1 → 0.17.3

package/README.md

@@ -8,14 +8,17 @@ channel. Zero runtime dependencies (uses native `fetch`, Node >= 18).
 npm install @advertising-chat/sdk
 ```
 
+Basic serving is two steps: **fetch an ad, render it with a "Sponsored"
+label.** You don't manage ad units, and you don't wire up tracking —
+impressions and clicks are attributed server-side via your fetch key.
+
 ```ts
-import { AdChat, renderWebchat, renderWhatsApp, UniversalAdPayload } from '@advertising-chat/sdk';
+import { AdChat, renderWebchat, UniversalAdPayload } from '@advertising-chat/sdk';
 
-const adchat = new AdChat({ apiKey: process.env.ADCHAT_API_KEY! });
+const adchat = new AdChat({ fetchKey: process.env.ADCHAT_FETCH_KEY! });
 
 // Fetch an ad, passing conversation context for relevance.
 const ad = await adchat.fetchAd<UniversalAdPayload>({
-  adUnit: 'my-ad-unit',
   subscriber: sessionId, // anonymous id — enables frequency capping
   context: [
     { role: 'user', text: 'Best hotels in Rome?' },
@@ -26,16 +29,181 @@ const ad = await adchat.fetchAd<UniversalAdPayload>({
 if (ad) {
   // null means no-fill: continue without an ad.
   const msg = renderWebchat(ad.payload); // { text, imageUrl, buttons, disclosure }
-  const wa = renderWhatsApp(ad.payload); // WhatsApp Cloud API message object
-
-  // Button URLs are click-tracking URLs (302 to the advertiser) — use verbatim.
-  await adchat.recordEvent({ messageId: ad.messageId, type: 'send' });
-  await adchat.recordConversion({ messageId: ad.messageId, name: 'purchase', value: 19.99, currency: 'USD' });
+  // Render msg with a "Sponsored" label. Button URLs are already
+  // click-tracking URLs (302 to the advertiser) — use them verbatim.
 }
 ```
 
 Always present ads clearly labeled as **Sponsored**.
 
+## Your key is a fetch key
+
+The key you pass is a **dataplane fetch key** — a per-Application API key
+(`type: 'fetch'`) that authenticates ad fetches and lets the server attribute
+impressions, clicks, and conversions for you. It is different from a
+**management key** (`type: 'management'`), which the console and CLI use to
+configure your account. Never ship a management key into client code.
+
+`fetchKey` is the preferred field; `apiKey` is a back-compatible alias for the
+same value.
+
+A fetch key is bound to one Application (agent), so fetches made with it
+need nothing more. With any other key, name the application, once on the
+client or per call:
+
+```ts
+const adchat = new AdChat({ apiKey: KEY, application: 'APPLICATION_ID' });
+const ad = await adchat.fetchAd({ application: 'OTHER_APPLICATION_ID' });
+```
+
+A request that resolves to no application is rejected with a 422
+(`MissingRequiredParameter`), and one that names an application other than
+its fetch key's is rejected with `ApplicationMismatch`.
+
+## Ad units are optional
+
+Most publishers never set `adUnit`. It's an **Offer Manager** concept for
+pinning a specific placement; a plain in-chat-ads integration doesn't need
+one. Omit it and the fetch fills against the application's **default ad
+unit** (created on first use). Advanced users who run multiple placements can
+pin one by code; codes are unique within an application:
+
+```ts
+const ad = await adchat.fetchAd({ adUnit: 'trip-planner-sidebar' });
+```
+
+## Blocking categories and advertisers
+
+Keep unwanted ads out with a high-level blocklist — set it once on the client
+(applies to every fetch) and/or per call:
+
+```ts
+const adchat = new AdChat({
+  fetchKey: process.env.ADCHAT_FETCH_KEY!,
+  block: { categories: ['gambling', 'alcohol'], advertisers: ['AcmeCorp'] },
+});
+
+// Per-call blocks merge with the client-wide list:
+const ad = await adchat.fetchAd({ block: { categories: ['politics'] } });
+```
+
+> **Roadmap / beta.** The SDK sends your blocklist on every fetch and it is
+> honored where server-side category/advertiser enforcement is available.
+> That enforcement is still rolling out (tracked as an `ads` follow-up), so
+> treat the blocklist as best-effort for now — the SDK surface and wire
+> contract are stable, so your code is ready as enforcement lands.
+
+## No-fill vs. misconfiguration
+
+`fetchAd()` returns `null` for a **no-fill** — a normal outcome (frequency
+caps, nothing eligible right now). Just continue the conversation without an
+ad; a `null` is never an error.
+
+While you are setting up, a `null` can be hard to tell apart from a
+misconfiguration (a typo in the ad unit code, or an ad unit that has no
+eligible line items yet). Two tools make the first-run experience concrete:
+
+**Sandbox ad unit** — the reserved `SANDBOX_AD_UNIT` (`'__sandbox__'`) code
+**always** fills with a clearly-labeled demo card, regardless of your account
+config. Use it to prove your integration end-to-end before your real ad units
+have line items. It records no billing or impression events.
+
+```ts
+import { AdChat, SANDBOX_AD_UNIT } from '@advertising-chat/sdk';
+
+const ad = await adchat.fetchAd({ adUnit: SANDBOX_AD_UNIT }); // always non-null
+```
+
+**`fetchAdDebug()`** — same request as `fetchAd()`, but returns a
+discriminated result with the *reason* for a no-fill instead of collapsing it
+to `null`. Use it for setup checks and health probes (not the hot path):
+
+```ts
+const r = await adchat.fetchAdDebug({ adUnit: 'my-ad-unit' });
+if (r.filled) {
+  render(r.ad.payload);
+} else {
+  // r.reason: 'unknown_ad_unit' | 'ad_unit_disabled' | 'no_eligible_line_items'
+  //         | 'frequency_capped' | 'appropriateness_suppressed' | 'no_demand'
+  console.warn(`no ad — ${r.reason}: ${r.message}`);
+}
+```
+
+`unknown_ad_unit`, `ad_unit_disabled`, and `no_eligible_line_items` mean
+something needs fixing; `frequency_capped`, `appropriateness_suppressed`, and
+`no_demand` are legitimate empty results (the same conditions under which
+`fetchAd()` returns `null`). `fetchAdDebug()` still throws
+`AdChatApiError` for genuine request errors that are not a no-fill (bad API
+key, unsupported format).
+
+## Reply taps
+
+An ad's reply actions (RCS suggested replies, Messenger quick replies,
+WhatsApp reply buttons, webchat reply buttons) come back to your agent as an ordinary message that
+carries the action's postback data. Report the tap so it counts as an
+interaction and, for an accept or decline reply, records the customer's
+response for your rules:
+
+```ts
+import { messengerPostbackData } from '@advertising-chat/sdk';
+
+// In your Messenger webhook, for each `messaging` event:
+const postbackData = messengerPostbackData(event);
+if (postbackData) {
+  await adchat.recordInteraction(postbackData);
+}
+```
+
+On WhatsApp, `renderWhatsApp` sends replies as reply buttons, and
+`whatsAppPostbackData(message)` reads the tap from your webhook's
+`messages[]`. On other channels, pass the postback data the channel returns
+(RBM `suggestionResponse.postbackData`, or a webchat button's `postbackData`
+from `renderWebchat`). `isAdPostbackData()` tells an ad's postback data from your
+agent's own reply payloads.
+
+## LLM tool loops
+
+When a model presents the ad through function tools (OpenAI-style tools or
+your own framework) instead of the MCP server, `describeAd(ad)` returns the
+result the MCP server's `fetch_ad` gives: the sponsored-disclosure duty, the
+click URLs, and each reply's `postback_data`, which your `record_reply` tool
+passes to `adchat.recordInteraction`.
+
+```ts
+import { describeAd } from '@advertising-chat/sdk';
+
+const ad = await adchat.fetchAd<UniversalAdPayload>({ subscriber });
+return ad ? describeAd(ad) : { status: 'no_ad' };
+```
+
+## Advanced / attribution
+
+You don't need any of this for standard serving — fetching with your fetch key
+and rendering the "Sponsored" label is enough, and impressions/clicks are
+attributed server-side. These helpers exist for surfaces that report
+engagement or conversions the server can't observe on its own:
+
+```ts
+// Report an engagement event the server can't see (e.g. a custom surface).
+await adchat.recordEvent({ messageId: ad.messageId, type: 'read' });
+
+// Measure a post-click outcome yourself.
+await adchat.recordConversion({
+  messageId: ad.messageId,
+  name: 'purchase',
+  value: 19.99,
+  currency: 'USD',
+});
+
+// Build a click-tracking URL only when you construct links yourself;
+// Navigate actions in the payload are already wrapped.
+const url = adchat.clickUrl({
+  messageId: ad.messageId,
+  actionId: ad.payload.actions[0].actionId,
+  targetUrl: 'https://example.com/landing',
+});
+```
+
 Full quickstarts: [docs.advertising.chat](https://docs.advertising.chat).
 Part of [AdKit](https://github.com/advertising-chat/adkit) — see also
 `@advertising-chat/mcp` (MCP server) and the Ad Skill.

package/bin/client.d.ts

@@ -1,7 +1,31 @@
-import { Ad, AdContext, ClickUrlParams, FetchAdParams, RecordConversionParams, RecordEventParams } from './types';
+import { Ad, AdContext, BlockList, ClickUrlParams, FetchAdParams, FetchAdResult, InteractionResult, RecordConversionParams, RecordEventParams } from './types';
 export interface AdChatOptions {
-    /** Org API key (from the Advertising.chat console). */
-    apiKey: string;
+    /**
+     * Your Advertising.chat **fetch key** — a dataplane API key scoped to an
+     * Application, from the console. It authenticates ad fetches and lets the
+     * server attribute impressions/clicks/conversions for you, so basic serving
+     * needs no manual tracking calls. Prefer {@link fetchKey}; `apiKey` is a
+     * back-compatible alias for the same value.
+     *
+     * A fetch key (`type: 'fetch'`) is distinct from a *management* key
+     * (`type: 'management'`, used by the console/CLI to configure your account).
+     * Never ship a management key to a client.
+     */
+    apiKey?: string;
+    /** Preferred alias for {@link apiKey} — your dataplane fetch key. */
+    fetchKey?: string;
+    /**
+     * Id of the Application (agent) every fetch from this client is for. A
+     * fetch key is bound to one application, so this is needed only with
+     * another kind of key. Per-call {@link FetchAdParams.application} wins.
+     */
+    application?: string;
+    /**
+     * Block categories/advertisers on **every** fetch from this client. Merged
+     * with any per-call {@link FetchAdParams.block}. See {@link BlockList}
+     * (roadmap / beta — enforcement is rolling out server-side).
+     */
+    block?: BlockList;
     /**
      * Base URL of the ads runtime API.
      * Defaults to `https://ads.advertising.chat/v1`.
@@ -13,19 +37,29 @@ export interface AdChatOptions {
 /**
  * Client for the Advertising.chat ads runtime API.
  *
+ * Basic serving is just two steps: fetch an ad with your Application fetch
+ * key, then render it with a clear "Sponsored" label. Impressions and clicks
+ * are attributed server-side via the fetch key — you don't have to call the
+ * tracking methods for a standard integration.
+ *
  * ```ts
- * const adchat = new AdChat({ apiKey: process.env.ADCHAT_API_KEY! });
- * const ad = await adchat.fetchAd({ adUnit: 'my-ad-unit', context: summary });
+ * const adchat = new AdChat({ fetchKey: process.env.ADCHAT_FETCH_KEY! });
+ * const ad = await adchat.fetchAd({ context: summary }); // adUnit optional
  * if (ad) {
- *   // render ad.payload, then:
- *   await adchat.recordEvent({ messageId: ad.messageId, type: 'send' });
+ *   // render ad.payload with a "Sponsored" label — that's it.
  * }
  * ```
+ *
+ * {@link recordEvent}, {@link recordConversion}, and {@link clickUrl} are
+ * advanced attribution helpers for surfaces that need to report engagement
+ * or conversions explicitly — most publishers can ignore them.
  */
 export declare class AdChat {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly fetchFn;
+    private readonly blockDefault?;
+    private readonly application?;
     constructor(options: AdChatOptions);
     /**
      * Fetch an ad for a placement.
@@ -40,27 +74,79 @@ export declare class AdChat {
      */
     fetchAd<P = unknown>(params?: FetchAdParams): Promise<Ad<P> | null>;
     /**
-     * Record a lifecycle or engagement event ('send', 'deliver', 'read',
-     * 'click', 'conversion') for a previously fetched ad.
+     * Like {@link fetchAd}, but instead of collapsing every no-fill to `null`,
+     * returns a discriminated result that distinguishes a served ad from a
+     * no-fill *and its reason* — so you can tell a legitimate empty result
+     * (`no_demand`, `frequency_capped`) apart from a misconfiguration
+     * (`unknown_ad_unit`, `no_eligible_line_items`).
+     *
+     * Intended for setup/onboarding diagnostics and health checks, not the hot
+     * path — in production use {@link fetchAd} (a `null` no-fill is normal and
+     * needs no branching).
+     *
+     * ```ts
+     * const r = await adchat.fetchAdDebug({ adUnit: 'my-ad-unit' });
+     * if (r.filled) render(r.ad);
+     * else console.warn(`no ad: ${r.reason} — ${r.message}`);
+     * ```
+     *
+     * Still throws {@link AdChatApiError} for genuine request errors that are
+     * not a no-fill (bad API key, unsupported format).
+     */
+    fetchAdDebug<P = unknown>(params?: FetchAdParams): Promise<FetchAdResult<P>>;
+    /** Build the fetch v2 request body shared by fetchAd/fetchAdDebug. */
+    private fetchBody;
+    /**
+     * **Advanced / attribution.** Record a lifecycle or engagement event
+     * ('send', 'deliver', 'read', 'click', 'conversion') for a previously
+     * fetched ad. Standard serving does not need this — impressions and clicks
+     * are attributed server-side via the fetch key. Use it only when you want
+     * to report engagement the server can't observe on its own.
      */
     recordEvent(params: RecordEventParams): Promise<void>;
     /**
-     * Record a conversion for a previously fetched ad, optionally with a
-     * monetary value.
+     * **Advanced / attribution.** Record a conversion for a previously fetched
+     * ad, optionally with a monetary value. Only needed when you measure
+     * post-click outcomes (purchase, signup) yourself.
      */
     recordConversion(params: RecordConversionParams): Promise<void>;
     /**
-     * Build a click-tracking URL that records the click and 302-redirects
-     * to `targetUrl`.
+     * Report a tap on one of the ad's reply actions (an RCS suggested reply, a
+     * Messenger quick reply, a webchat reply button). The channel hands the tap
+     * back to your agent with the action's postback data, the `context` of the
+     * `AdAction` (`<messageId>_<actionId>`); pass it here. A reply with an
+     * accept or decline role records the customer's response, which rules can
+     * then use.
+     *
+     * ```ts
+     * // Messenger webhook
+     * const postbackData = messengerPostbackData(messagingEvent);
+     * if (postbackData) await adchat.recordInteraction(postbackData);
+     * ```
+     *
+     * Throws {@link AdChatApiError} for request errors (422 for postback data
+     * that is not `<messageId>_<actionId>`).
+     */
+    recordInteraction(postbackData: string): Promise<InteractionResult>;
+    /**
+     * **Advanced / attribution.** Build a click-tracking URL that records the
+     * click and 302-redirects to `targetUrl`.
      *
      * NOTE: Navigate actions in fetched payloads already contain wrapped
-     * click URLs — use those directly. This helper is for surfaces where
+     * click URLs — use those directly. This helper is only for surfaces where
      * you construct links yourself.
      */
     clickUrl(params: ClickUrlParams): string;
     private headers;
     private toApiError;
 }
+/**
+ * Merge a client-wide {@link BlockList} with a per-call one into a single
+ * blocklist for the wire. Categories and advertisers are unioned (deduped,
+ * order-preserving). Returns `undefined` when neither list contributes
+ * anything, so an empty blocklist is omitted from the request body.
+ */
+export declare function mergeBlockLists(base?: BlockList, override?: BlockList): BlockList | undefined;
 /**
  * Derive the fetch API's structured `conversation` field from structured
  * context turns. String context has no turn structure, so it is sent only
@@ -70,3 +156,25 @@ export declare function conversationFromContext(context: AdContext, subscriber?:
     conversationId: string;
     messages: object[];
 } | undefined;
+/**
+ * True for postback data that belongs to an ad action. Your agent's own
+ * replies carry their own payloads; report only the ad's to
+ * {@link AdChat.recordInteraction}.
+ */
+export declare function isAdPostbackData(data: unknown): data is string;
+/**
+ * The ad postback data in a Messenger webhook `messaging` event, or
+ * `undefined` when the event is not a tap on an ad's quick reply. The `fbm`
+ * format renders an ad's Text actions as quick replies whose payload is the
+ * action's postback data; Messenger returns it as
+ * `message.quick_reply.payload`.
+ *
+ * https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messages
+ */
+export declare function messengerPostbackData(event: {
+    message?: {
+        quick_reply?: {
+            payload?: unknown;
+        };
+    };
+}): string | undefined;

package/bin/client.js

@@ -1,30 +1,46 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AdChat = void 0;
+exports.mergeBlockLists = mergeBlockLists;
 exports.conversationFromContext = conversationFromContext;
+exports.isAdPostbackData = isAdPostbackData;
+exports.messengerPostbackData = messengerPostbackData;
 const types_1 = require("./types");
 const DEFAULT_BASE_URL = 'https://ads.advertising.chat/v1';
 /**
  * Client for the Advertising.chat ads runtime API.
  *
+ * Basic serving is just two steps: fetch an ad with your Application fetch
+ * key, then render it with a clear "Sponsored" label. Impressions and clicks
+ * are attributed server-side via the fetch key — you don't have to call the
+ * tracking methods for a standard integration.
+ *
  * ```ts
- * const adchat = new AdChat({ apiKey: process.env.ADCHAT_API_KEY! });
- * const ad = await adchat.fetchAd({ adUnit: 'my-ad-unit', context: summary });
+ * const adchat = new AdChat({ fetchKey: process.env.ADCHAT_FETCH_KEY! });
+ * const ad = await adchat.fetchAd({ context: summary }); // adUnit optional
  * if (ad) {
- *   // render ad.payload, then:
- *   await adchat.recordEvent({ messageId: ad.messageId, type: 'send' });
+ *   // render ad.payload with a "Sponsored" label — that's it.
  * }
  * ```
+ *
+ * {@link recordEvent}, {@link recordConversion}, and {@link clickUrl} are
+ * advanced attribution helpers for surfaces that need to report engagement
+ * or conversions explicitly — most publishers can ignore them.
  */
 class AdChat {
     apiKey;
     baseUrl;
     fetchFn;
+    blockDefault;
+    application;
     constructor(options) {
-        if (!options?.apiKey) {
-            throw new Error('AdChat: apiKey is required');
+        const key = options?.fetchKey || options?.apiKey;
+        if (!key) {
+            throw new Error('AdChat: a fetchKey (apiKey) is required');
         }
-        this.apiKey = options.apiKey;
+        this.apiKey = key;
+        this.blockDefault = options.block;
+        this.application = options.application;
         this.baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
         // Bind to globalThis so `fetch` keeps its expected receiver.
         this.fetchFn = options.fetchFn || fetch.bind(globalThis);
@@ -41,7 +57,95 @@ class AdChat {
      * unsupported format, bad API key...).
      */
     async fetchAd(params = {}) {
+        const res = await this.fetchFn(`${this.baseUrl}/fetch/v2`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify(this.fetchBody(params)),
+        });
+        if (res.status === 204) {
+            return null; // no fill
+        }
+        if (!res.ok) {
+            throw await this.toApiError(res);
+        }
+        const ad = (await res.json());
+        // Defensive: some no-fill paths respond 200 with an empty body/payload.
+        if (!ad || !ad.payload)
+            return null;
+        return ad;
+    }
+    /**
+     * Like {@link fetchAd}, but instead of collapsing every no-fill to `null`,
+     * returns a discriminated result that distinguishes a served ad from a
+     * no-fill *and its reason* — so you can tell a legitimate empty result
+     * (`no_demand`, `frequency_capped`) apart from a misconfiguration
+     * (`unknown_ad_unit`, `no_eligible_line_items`).
+     *
+     * Intended for setup/onboarding diagnostics and health checks, not the hot
+     * path — in production use {@link fetchAd} (a `null` no-fill is normal and
+     * needs no branching).
+     *
+     * ```ts
+     * const r = await adchat.fetchAdDebug({ adUnit: 'my-ad-unit' });
+     * if (r.filled) render(r.ad);
+     * else console.warn(`no ad: ${r.reason} — ${r.message}`);
+     * ```
+     *
+     * Still throws {@link AdChatApiError} for genuine request errors that are
+     * not a no-fill (bad API key, unsupported format).
+     */
+    async fetchAdDebug(params = {}) {
+        const res = await this.fetchFn(`${this.baseUrl}/fetch/v2`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify({ ...this.fetchBody(params), debug: 1 }),
+        });
+        if (res.ok) {
+            const data = (await res.json().catch(() => null));
+            // The server's debug path reports a no-fill as { filled:false, reason }.
+            if (data && data.filled === false && data.reason) {
+                return {
+                    filled: false,
+                    reason: data.reason,
+                    message: data.message || 'No ad was served.',
+                };
+            }
+            if (data && data.payload) {
+                return { filled: true, ad: data };
+            }
+            return {
+                filled: false,
+                reason: 'no_demand',
+                message: 'No ad was served.',
+            };
+        }
+        // A bare 204 can still occur if the server does not honor the debug flag.
+        if (res.status === 204) {
+            return {
+                filled: false,
+                reason: 'no_demand',
+                message: 'No ad was served.',
+            };
+        }
+        const err = await this.toApiError(res);
+        // Surface the classic onboarding misconfiguration (an unknown ad unit is
+        // a distinct 4xx on the server) as a diagnosable reason rather than
+        // throwing, so callers get a uniform result to branch on.
+        if (err.status === 422 && err.reason === 'UnknownAdUnit') {
+            return {
+                filled: false,
+                reason: 'unknown_ad_unit',
+                message: err.message,
+            };
+        }
+        throw err;
+    }
+    /** Build the fetch v2 request body shared by fetchAd/fetchAdDebug. */
+    fetchBody(params) {
         const body = {};
+        const application = params.application || this.application;
+        if (application)
+            body.application = application;
         if (params.adUnit)
             body.adUnit = params.adUnit;
         if (params.format)
@@ -50,6 +154,13 @@ class AdChat {
             body.subscriber = params.subscriber;
         if (params.attributes)
             body.attributes = params.attributes;
+        // Merge the client-wide blocklist with any per-call one and pass it
+        // through on the wire as `block`. Roadmap/beta: the server honors this
+        // where category/advertiser enforcement is available (rolling out); the
+        // SDK always sends it so integrations are ready as enforcement lands.
+        const block = mergeBlockLists(this.blockDefault, params.block);
+        if (block)
+            body.block = block;
         if (params.test)
             body.test = true;
         if (params.context !== undefined) {
@@ -60,26 +171,14 @@ class AdChat {
             if (conversation)
                 body.conversation = conversation;
         }
-        const res = await this.fetchFn(`${this.baseUrl}/fetch/v2`, {
-            method: 'POST',
-            headers: this.headers(),
-            body: JSON.stringify(body),
-        });
-        if (res.status === 204) {
-            return null; // no fill
-        }
-        if (!res.ok) {
-            throw await this.toApiError(res);
-        }
-        const ad = (await res.json());
-        // Defensive: some no-fill paths respond 200 with an empty body/payload.
-        if (!ad || !ad.payload)
-            return null;
-        return ad;
+        return body;
     }
     /**
-     * Record a lifecycle or engagement event ('send', 'deliver', 'read',
-     * 'click', 'conversion') for a previously fetched ad.
+     * **Advanced / attribution.** Record a lifecycle or engagement event
+     * ('send', 'deliver', 'read', 'click', 'conversion') for a previously
+     * fetched ad. Standard serving does not need this — impressions and clicks
+     * are attributed server-side via the fetch key. Use it only when you want
+     * to report engagement the server can't observe on its own.
      */
     async recordEvent(params) {
         const res = await this.fetchFn(`${this.baseUrl}/event`, {
@@ -99,8 +198,9 @@ class AdChat {
         }
     }
     /**
-     * Record a conversion for a previously fetched ad, optionally with a
-     * monetary value.
+     * **Advanced / attribution.** Record a conversion for a previously fetched
+     * ad, optionally with a monetary value. Only needed when you measure
+     * post-click outcomes (purchase, signup) yourself.
      */
     async recordConversion(params) {
         return this.recordEvent({
@@ -116,11 +216,39 @@ class AdChat {
         });
     }
     /**
-     * Build a click-tracking URL that records the click and 302-redirects
-     * to `targetUrl`.
+     * Report a tap on one of the ad's reply actions (an RCS suggested reply, a
+     * Messenger quick reply, a webchat reply button). The channel hands the tap
+     * back to your agent with the action's postback data, the `context` of the
+     * `AdAction` (`<messageId>_<actionId>`); pass it here. A reply with an
+     * accept or decline role records the customer's response, which rules can
+     * then use.
+     *
+     * ```ts
+     * // Messenger webhook
+     * const postbackData = messengerPostbackData(messagingEvent);
+     * if (postbackData) await adchat.recordInteraction(postbackData);
+     * ```
+     *
+     * Throws {@link AdChatApiError} for request errors (422 for postback data
+     * that is not `<messageId>_<actionId>`).
+     */
+    async recordInteraction(postbackData) {
+        const q = new URLSearchParams({ postbackData });
+        const res = await this.fetchFn(`${this.baseUrl}/interact?${q.toString()}`, {
+            method: 'POST',
+            headers: this.headers(),
+        });
+        if (!res.ok) {
+            throw await this.toApiError(res);
+        }
+        return (await res.json());
+    }
+    /**
+     * **Advanced / attribution.** Build a click-tracking URL that records the
+     * click and 302-redirects to `targetUrl`.
      *
      * NOTE: Navigate actions in fetched payloads already contain wrapped
-     * click URLs — use those directly. This helper is for surfaces where
+     * click URLs — use those directly. This helper is only for surfaces where
      * you construct links yourself.
      */
     clickUrl(params) {
@@ -144,7 +272,7 @@ class AdChat {
         try {
             const body = (await res.json());
             reason = body?.reason;
-            description = body?.description || body?.title;
+            description = body?.description || body?.title || body?.message;
         }
         catch {
             // non-JSON error body
@@ -155,6 +283,31 @@ class AdChat {
     }
 }
 exports.AdChat = AdChat;
+/**
+ * Merge a client-wide {@link BlockList} with a per-call one into a single
+ * blocklist for the wire. Categories and advertisers are unioned (deduped,
+ * order-preserving). Returns `undefined` when neither list contributes
+ * anything, so an empty blocklist is omitted from the request body.
+ */
+function mergeBlockLists(base, override) {
+    const categories = dedupe([
+        ...(base?.categories ?? []),
+        ...(override?.categories ?? []),
+    ]);
+    const advertisers = dedupe([
+        ...(base?.advertisers ?? []),
+        ...(override?.advertisers ?? []),
+    ]);
+    const result = {};
+    if (categories.length)
+        result.categories = categories;
+    if (advertisers.length)
+        result.advertisers = advertisers;
+    return categories.length || advertisers.length ? result : undefined;
+}
+function dedupe(values) {
+    return [...new Set(values)];
+}
 /**
  * Derive the fetch API's structured `conversation` field from structured
  * context turns. String context has no turn structure, so it is sent only
@@ -176,4 +329,27 @@ function conversationFromContext(context, subscriber) {
         })),
     };
 }
+/** Ad message ids are `direqt-<uuid>`; postback data appends `_<actionId>`. */
+const AD_POSTBACK = /^direqt-[^_]+_.+$/;
+/**
+ * True for postback data that belongs to an ad action. Your agent's own
+ * replies carry their own payloads; report only the ad's to
+ * {@link AdChat.recordInteraction}.
+ */
+function isAdPostbackData(data) {
+    return typeof data === 'string' && AD_POSTBACK.test(data);
+}
+/**
+ * The ad postback data in a Messenger webhook `messaging` event, or
+ * `undefined` when the event is not a tap on an ad's quick reply. The `fbm`
+ * format renders an ad's Text actions as quick replies whose payload is the
+ * action's postback data; Messenger returns it as
+ * `message.quick_reply.payload`.
+ *
+ * https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messages
+ */
+function messengerPostbackData(event) {
+    const payload = event?.message?.quick_reply?.payload;
+    return isAdPostbackData(payload) ? payload : undefined;
+}
 //# sourceMappingURL=client.js.map

package/bin/client.js.map

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

package/bin/index.d.ts

@@ -1,4 +1,5 @@
-export { AdChat, AdChatOptions, conversationFromContext } from './client';
+export { AdChat, AdChatOptions, conversationFromContext, isAdPostbackData, mergeBlockLists, messengerPostbackData, } from './client';
 export * from './types';
+export { AdToolAction, AdToolResult, SPONSORED_DISCLOSURE, describeAd, } from './render/llm';
 export { renderWebchat, WebchatMessage, WebchatButton } from './render/webchat';
-export { renderWhatsApp, WhatsAppMessage } from './render/whatsapp';
+export { renderWhatsApp, WhatsAppMessage, whatsAppPostbackData, } from './render/whatsapp';

package/bin/index.js

@@ -14,13 +14,20 @@ 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 });
-exports.renderWhatsApp = exports.renderWebchat = exports.conversationFromContext = exports.AdChat = void 0;
+exports.whatsAppPostbackData = exports.renderWhatsApp = exports.renderWebchat = exports.describeAd = exports.SPONSORED_DISCLOSURE = exports.messengerPostbackData = exports.mergeBlockLists = exports.isAdPostbackData = exports.conversationFromContext = exports.AdChat = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "AdChat", { enumerable: true, get: function () { return client_1.AdChat; } });
 Object.defineProperty(exports, "conversationFromContext", { enumerable: true, get: function () { return client_1.conversationFromContext; } });
+Object.defineProperty(exports, "isAdPostbackData", { enumerable: true, get: function () { return client_1.isAdPostbackData; } });
+Object.defineProperty(exports, "mergeBlockLists", { enumerable: true, get: function () { return client_1.mergeBlockLists; } });
+Object.defineProperty(exports, "messengerPostbackData", { enumerable: true, get: function () { return client_1.messengerPostbackData; } });
 __exportStar(require("./types"), exports);
+var llm_1 = require("./render/llm");
+Object.defineProperty(exports, "SPONSORED_DISCLOSURE", { enumerable: true, get: function () { return llm_1.SPONSORED_DISCLOSURE; } });
+Object.defineProperty(exports, "describeAd", { enumerable: true, get: function () { return llm_1.describeAd; } });
 var webchat_1 = require("./render/webchat");
 Object.defineProperty(exports, "renderWebchat", { enumerable: true, get: function () { return webchat_1.renderWebchat; } });
 var whatsapp_1 = require("./render/whatsapp");
 Object.defineProperty(exports, "renderWhatsApp", { enumerable: true, get: function () { return whatsapp_1.renderWhatsApp; } });
+Object.defineProperty(exports, "whatsAppPostbackData", { enumerable: true, get: function () { return whatsapp_1.whatsAppPostbackData; } });
 //# sourceMappingURL=index.js.map

package/bin/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,mCAA0E;AAAjE,gGAAA,MAAM,OAAA;AAAiB,iHAAA,uBAAuB,OAAA;AACvD,0CAAwB;AACxB,4CAAgF;AAAvE,wGAAA,aAAa,OAAA;AACtB,8CAAoE;AAA3D,0GAAA,cAAc,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,mCAOkB;AANhB,gGAAA,MAAM,OAAA;AAEN,iHAAA,uBAAuB,OAAA;AACvB,0GAAA,gBAAgB,OAAA;AAChB,yGAAA,eAAe,OAAA;AACf,+GAAA,qBAAqB,OAAA;AAEvB,0CAAwB;AACxB,oCAKsB;AAFpB,2GAAA,oBAAoB,OAAA;AACpB,iGAAA,UAAU,OAAA;AAEZ,4CAAgF;AAAvE,wGAAA,aAAa,OAAA;AACtB,8CAI2B;AAHzB,0GAAA,cAAc,OAAA;AAEd,gHAAA,oBAAoB,OAAA"}

package/bin/render/llm.d.ts

@@ -0,0 +1,48 @@
+import { Ad, UniversalAdPayload } from '../types';
+/**
+ * The disclosure duty that travels with every ad handed to a model. It
+ * tells the model to label the ad as sponsored, present it faithfully, and
+ * use click URLs verbatim so clicks are attributed.
+ */
+export declare const SPONSORED_DISCLOSURE: string;
+/** One action of an ad, as a model sees it. */
+export interface AdToolAction {
+    label: string;
+    /** Click-tracking URL to share verbatim (Navigate actions). */
+    click_url?: string;
+    /** Phone number to offer (Call actions). */
+    phone_number?: string;
+    /**
+     * For a reply (Text action): pass it to `AdChat.recordInteraction` when
+     * the user chooses the reply.
+     */
+    postback_data?: string;
+}
+/** A filled ad as a tool result for a model. */
+export interface AdToolResult {
+    status: 'filled';
+    message_id: string;
+    sponsored_disclosure: string;
+    ad: {
+        title: string;
+        subtitle: string;
+        image_url?: string;
+        alt_text?: string;
+        actions: AdToolAction[];
+    };
+    /** A ready-to-send rendering: the sponsored line, then the first link. */
+    suggested_text: string;
+}
+/**
+ * Convert a fetched ad into a tool result for a model: the essentials for
+ * presenting it, the disclosure duty, and each reply's `postback_data`.
+ * This is the result the MCP server's `fetch_ad` returns; use it in any
+ * other tool loop (OpenAI-style function tools, a custom framework) so the
+ * model sees the same shape.
+ *
+ * ```ts
+ * const ad = await adchat.fetchAd<UniversalAdPayload>({ subscriber });
+ * return ad ? describeAd(ad) : { status: 'no_ad' };
+ * ```
+ */
+export declare function describeAd(ad: Ad<UniversalAdPayload>): AdToolResult;

package/bin/render/llm.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPONSORED_DISCLOSURE = void 0;
+exports.describeAd = describeAd;
+const types_1 = require("../types");
+/**
+ * The disclosure duty that travels with every ad handed to a model. It
+ * tells the model to label the ad as sponsored, present it faithfully, and
+ * use click URLs verbatim so clicks are attributed.
+ */
+exports.SPONSORED_DISCLOSURE = 'This is a paid advertisement. When you present it, you MUST clearly ' +
+    "label it as sponsored (e.g. prefix with 'Sponsored:' or an equivalent " +
+    'disclosure in the conversation language). Present the ad content ' +
+    'faithfully — do not exaggerate, embellish, or add claims of your own. ' +
+    'Use the provided click_url values verbatim for any links, so clicks ' +
+    'are attributed.';
+/**
+ * Convert a fetched ad into a tool result for a model: the essentials for
+ * presenting it, the disclosure duty, and each reply's `postback_data`.
+ * This is the result the MCP server's `fetch_ad` returns; use it in any
+ * other tool loop (OpenAI-style function tools, a custom framework) so the
+ * model sees the same shape.
+ *
+ * ```ts
+ * const ad = await adchat.fetchAd<UniversalAdPayload>({ subscriber });
+ * return ad ? describeAd(ad) : { status: 'no_ad' };
+ * ```
+ */
+function describeAd(ad) {
+    const p = ad.payload;
+    const actions = (p.actions || []).map(a => ({
+        label: a.text,
+        ...(a.navigate?.url ? { click_url: a.navigate.url } : {}),
+        ...(a.call?.phoneNumber ? { phone_number: a.call.phoneNumber } : {}),
+        ...(a.type === types_1.AdActionType.Text && a.context
+            ? { postback_data: a.context }
+            : {}),
+    }));
+    const firstUrl = actions.find(a => a.click_url)?.click_url;
+    return {
+        status: 'filled',
+        message_id: ad.messageId,
+        sponsored_disclosure: exports.SPONSORED_DISCLOSURE,
+        ad: {
+            title: p.title,
+            subtitle: p.subtitle,
+            ...(p.imageUrl ? { image_url: p.imageUrl } : {}),
+            ...(p.altText ? { alt_text: p.altText } : {}),
+            actions,
+        },
+        suggested_text: [
+            `Sponsored: ${[p.title, p.subtitle].filter(Boolean).join(' — ') || p.altText || ''}`,
+            ...(firstUrl ? [firstUrl] : []),
+        ].join('\n'),
+    };
+}
+//# sourceMappingURL=llm.js.map

package/bin/render/llm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.js","sourceRoot":"","sources":["../../src/render/llm.ts"],"names":[],"mappings":";;;AAyDA,gCA2BC;AApFD,oCAAgE;AAEhE;;;;GAIG;AACU,QAAA,oBAAoB,GAC/B,sEAAsE;IACtE,wEAAwE;IACxE,mEAAmE;IACnE,wEAAwE;IACxE,sEAAsE;IACtE,iBAAiB,CAAC;AAgCpB;;;;;;;;;;;GAWG;AACH,SAAgB,UAAU,CAAC,EAA0B;IACnD,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC;IACrB,MAAM,OAAO,GAAmB,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC1D,KAAK,EAAE,CAAC,CAAC,IAAI;QACb,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzD,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,oBAAY,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO;YAC3C,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE;YAC9B,CAAC,CAAC,EAAE,CAAC;KACR,CAAC,CAAC,CAAC;IACJ,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC3D,OAAO;QACL,MAAM,EAAE,QAAQ;QAChB,UAAU,EAAE,EAAE,CAAC,SAAS;QACxB,oBAAoB,EAAE,4BAAoB;QAC1C,EAAE,EAAE;YACF,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChD,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7C,OAAO;SACR;QACD,cAAc,EAAE;YACd,cAAc,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,IAAI,EAAE,EAAE;YACpF,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SAChC,CAAC,IAAI,CAAC,IAAI,CAAC;KACb,CAAC;AACJ,CAAC"}

package/bin/render/webchat.d.ts

@@ -23,6 +23,11 @@ export interface WebchatButton {
     url?: string;
     /** Phone number to dial (Call actions). */
     phoneNumber?: string;
+    /**
+     * Postback data for a reply (Text actions). When the user taps the button,
+     * pass it to `AdChat.recordInteraction`.
+     */
+    postbackData?: string;
     /** Stable id for the button (the ad action id). */
     id: string;
 }

package/bin/render/webchat.js

@@ -26,6 +26,9 @@ function renderWebchat(payload) {
             ...(action.type === types_1.AdActionType.Call && action.call
                 ? { phoneNumber: action.call.phoneNumber }
                 : {}),
+            ...(action.type === types_1.AdActionType.Text
+                ? { postbackData: action.context }
+                : {}),
             id: action.actionId,
         })),
         disclosure: 'Sponsored',

package/bin/render/webchat.js.map

@@ -1 +1 @@
-{"version":3,"file":"webchat.js","sourceRoot":"","sources":["../../src/render/webchat.ts"],"names":[],"mappings":";;AA0CA,sCAiBC;AA3DD,oCAA4D;AA+B5D;;;;;;;;;;GAUG;AACH,SAAgB,aAAa,CAAC,OAA2B;IACvD,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAChE,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,OAAO,IAAI,EAAE;QAC/C,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,OAAO,EAAE,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAC9C,KAAK,EAAE,MAAM,CAAC,IAAI;YAClB,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,oBAAY,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ;gBAC1D,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE;gBAC9B,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,oBAAY,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI;gBAClD,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE;gBAC1C,CAAC,CAAC,EAAE,CAAC;YACP,EAAE,EAAE,MAAM,CAAC,QAAQ;SACpB,CAAC,CAAC;QACH,UAAU,EAAE,WAAW;KACxB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"webchat.js","sourceRoot":"","sources":["../../src/render/webchat.ts"],"names":[],"mappings":";;AA+CA,sCAoBC;AAnED,oCAA4D;AAoC5D;;;;;;;;;;GAUG;AACH,SAAgB,aAAa,CAAC,OAA2B;IACvD,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAChE,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,OAAO,IAAI,EAAE;QAC/C,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,OAAO,EAAE,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAC9C,KAAK,EAAE,MAAM,CAAC,IAAI;YAClB,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,oBAAY,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ;gBAC1D,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE;gBAC9B,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,oBAAY,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI;gBAClD,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE;gBAC1C,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,oBAAY,CAAC,IAAI;gBACnC,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,OAAO,EAAE;gBAClC,CAAC,CAAC,EAAE,CAAC;YACP,EAAE,EAAE,MAAM,CAAC,QAAQ;SACpB,CAAC,CAAC;QACH,UAAU,EAAE,WAAW;KACxB,CAAC;AACJ,CAAC"}

package/bin/render/whatsapp.d.ts

@@ -26,9 +26,39 @@ export type WhatsAppMessage = {
  * message object.
  *
  * Mapping (faithful to the platform's channel renderers):
- * - One Navigate action → interactive `cta_url` message: image header,
- *   title/subtitle body, "Sponsored" footer, URL button (click-tracked).
+ * - Text (reply) actions → interactive `button` message: image header,
+ *   title/subtitle body (Navigate URLs appended), "Sponsored" footer, and
+ *   up to three reply buttons whose id is the action's postback data. A tap
+ *   comes back on your webhook as `interactive.button_reply.id`; pass it to
+ *   `AdChat.recordInteraction` (see {@link whatsAppPostbackData}).
+ * - Otherwise one Navigate action → interactive `cta_url` message: image
+ *   header, title/subtitle body, "Sponsored" footer, URL button
+ *   (click-tracked).
  * - Otherwise → image with caption (or plain text if no image); Navigate
  *   URLs are appended to the text, SMS-style.
+ *
+ * WhatsApp does not mix URL and reply buttons in one message, so an ad with
+ * both shows its replies as buttons and its links in the body.
  */
 export declare function renderWhatsApp(payload: UniversalAdPayload): WhatsAppMessage;
+/**
+ * The ad postback data in a WhatsApp Cloud API webhook message, or
+ * `undefined` when the message is not a tap on an ad's reply button.
+ * {@link renderWhatsApp} sets each reply button's id to the action's
+ * postback data; WhatsApp returns it as `interactive.button_reply.id`.
+ *
+ * ```ts
+ * // entry[].changes[].value.messages[]
+ * const postbackData = whatsAppPostbackData(message);
+ * if (postbackData) await adchat.recordInteraction(postbackData);
+ * ```
+ *
+ * https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/payload-examples
+ */
+export declare function whatsAppPostbackData(message: {
+    interactive?: {
+        button_reply?: {
+            id?: unknown;
+        };
+    };
+}): string | undefined;

package/bin/render/whatsapp.js

@@ -1,22 +1,68 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderWhatsApp = renderWhatsApp;
+exports.whatsAppPostbackData = whatsAppPostbackData;
+const client_1 = require("../client");
 const types_1 = require("../types");
+/** WhatsApp Cloud API limits for interactive messages. */
+const MAX_REPLY_BUTTONS = 3;
+const MAX_BUTTON_TITLE = 20;
+const MAX_BUTTON_ID = 256;
+const MAX_BODY = 1024;
 /**
  * Render a universal ('direqt' format) ad payload as a WhatsApp Cloud API
  * message object.
  *
  * Mapping (faithful to the platform's channel renderers):
- * - One Navigate action → interactive `cta_url` message: image header,
- *   title/subtitle body, "Sponsored" footer, URL button (click-tracked).
+ * - Text (reply) actions → interactive `button` message: image header,
+ *   title/subtitle body (Navigate URLs appended), "Sponsored" footer, and
+ *   up to three reply buttons whose id is the action's postback data. A tap
+ *   comes back on your webhook as `interactive.button_reply.id`; pass it to
+ *   `AdChat.recordInteraction` (see {@link whatsAppPostbackData}).
+ * - Otherwise one Navigate action → interactive `cta_url` message: image
+ *   header, title/subtitle body, "Sponsored" footer, URL button
+ *   (click-tracked).
  * - Otherwise → image with caption (or plain text if no image); Navigate
  *   URLs are appended to the text, SMS-style.
+ *
+ * WhatsApp does not mix URL and reply buttons in one message, so an ad with
+ * both shows its replies as buttons and its links in the body.
  */
 function renderWhatsApp(payload) {
     const bodyText = [payload.title, payload.subtitle].filter(Boolean).join('\n') ||
         payload.altText ||
         '';
-    const navigateActions = (payload.actions || []).filter(a => a.type === types_1.AdActionType.Navigate && a.navigate?.url);
+    const actions = payload.actions || [];
+    const navigateActions = actions.filter(a => a.type === types_1.AdActionType.Navigate && a.navigate?.url);
+    const urls = navigateActions.map(a => a.navigate.url);
+    const header = payload.imageUrl
+        ? { header: { type: 'image', image: { link: payload.imageUrl } } }
+        : {};
+    const replies = actions
+        .filter((a) => a.type === types_1.AdActionType.Text &&
+        !!a.text &&
+        !!a.context &&
+        a.context.length <= MAX_BUTTON_ID)
+        .slice(0, MAX_REPLY_BUTTONS);
+    if (replies.length) {
+        return {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            type: 'interactive',
+            interactive: {
+                type: 'button',
+                ...header,
+                body: { text: truncate([bodyText, ...urls].join('\n'), MAX_BODY) },
+                footer: { text: 'Sponsored' },
+                action: {
+                    buttons: replies.map(a => ({
+                        type: 'reply',
+                        reply: { id: a.context, title: truncate(a.text, MAX_BUTTON_TITLE) },
+                    })),
+                },
+            },
+        };
+    }
     if (navigateActions.length === 1) {
         const action = navigateActions[0];
         return {
@@ -25,15 +71,13 @@ function renderWhatsApp(payload) {
             type: 'interactive',
             interactive: {
                 type: 'cta_url',
-                ...(payload.imageUrl
-                    ? { header: { type: 'image', image: { link: payload.imageUrl } } }
-                    : {}),
+                ...header,
                 body: { text: bodyText },
                 footer: { text: 'Sponsored' },
                 action: {
                     name: 'cta_url',
                     parameters: {
-                        display_text: truncate(action.text, 20) || 'Learn more',
+                        display_text: truncate(action.text, MAX_BUTTON_TITLE) || 'Learn more',
                         // Already a click-tracking URL that 302s to the advertiser.
                         url: action.navigate.url,
                     },
@@ -42,7 +86,6 @@ function renderWhatsApp(payload) {
         };
     }
     // Fallback: degrade like the SMS renderer — text plus URL(s).
-    const urls = navigateActions.map(a => a.navigate.url);
     const caption = ['Sponsored', bodyText, ...urls].filter(Boolean).join('\n');
     if (payload.imageUrl) {
         return {
@@ -59,7 +102,25 @@ function renderWhatsApp(payload) {
         text: { body: caption, preview_url: true },
     };
 }
-/** WhatsApp cta_url display_text is limited to 20 characters. */
+/**
+ * The ad postback data in a WhatsApp Cloud API webhook message, or
+ * `undefined` when the message is not a tap on an ad's reply button.
+ * {@link renderWhatsApp} sets each reply button's id to the action's
+ * postback data; WhatsApp returns it as `interactive.button_reply.id`.
+ *
+ * ```ts
+ * // entry[].changes[].value.messages[]
+ * const postbackData = whatsAppPostbackData(message);
+ * if (postbackData) await adchat.recordInteraction(postbackData);
+ * ```
+ *
+ * https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/payload-examples
+ */
+function whatsAppPostbackData(message) {
+    const id = message?.interactive?.button_reply?.id;
+    return (0, client_1.isAdPostbackData)(id) ? id : undefined;
+}
+/** WhatsApp limits button titles to 20 characters and bodies to 1024. */
 function truncate(s, max) {
     if (!s)
         return s;

package/bin/render/whatsapp.js.map

@@ -1 +1 @@
-{"version":3,"file":"whatsapp.js","sourceRoot":"","sources":["../../src/render/whatsapp.ts"],"names":[],"mappings":";;AA6BA,wCAqDC;AAlFD,oCAA4D;AAmB5D;;;;;;;;;GASG;AACH,SAAgB,cAAc,CAAC,OAA2B;IACxD,MAAM,QAAQ,GACZ,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAC5D,OAAO,CAAC,OAAO;QACf,EAAE,CAAC;IAEL,MAAM,eAAe,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,MAAM,CACpD,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,oBAAY,CAAC,QAAQ,IAAI,CAAC,CAAC,QAAQ,EAAE,GAAG,CACzD,CAAC;IAEF,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;QAClC,OAAO;YACL,iBAAiB,EAAE,UAAU;YAC7B,cAAc,EAAE,YAAY;YAC5B,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE;gBACX,IAAI,EAAE,SAAS;gBACf,GAAG,CAAC,OAAO,CAAC,QAAQ;oBAClB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,EAAE;oBAClE,CAAC,CAAC,EAAE,CAAC;gBACP,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACxB,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE;gBAC7B,MAAM,EAAE;oBACN,IAAI,EAAE,SAAS;oBACf,UAAU,EAAE;wBACV,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,YAAY;wBACvD,4DAA4D;wBAC5D,GAAG,EAAE,MAAM,CAAC,QAAS,CAAC,GAAG;qBAC1B;iBACF;aACF;SACF,CAAC;IACJ,CAAC;IAED,8DAA8D;IAC9D,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAS,CAAC,GAAG,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,CAAC,WAAW,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE5E,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,OAAO;YACL,iBAAiB,EAAE,UAAU;YAC7B,cAAc,EAAE,YAAY;YAC5B,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE;SAC3C,CAAC;IACJ,CAAC;IACD,OAAO;QACL,iBAAiB,EAAE,UAAU;QAC7B,cAAc,EAAE,YAAY;QAC5B,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE;KAC3C,CAAC;AACJ,CAAC;AAED,iEAAiE;AACjE,SAAS,QAAQ,CAAC,CAAS,EAAE,GAAW;IACtC,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACjB,OAAO,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;AACzD,CAAC"}
+{"version":3,"file":"whatsapp.js","sourceRoot":"","sources":["../../src/render/whatsapp.ts"],"names":[],"mappings":"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"}

package/bin/types.d.ts

@@ -21,10 +21,51 @@ export interface ConversationTurn {
  * summary of the conversation so far, or the most recent turns.
  */
 export type AdContext = string | ConversationTurn[];
+/**
+ * A high-level blocklist: categories and/or advertisers a publisher never
+ * wants served into their conversations. Set it once on the {@link AdChat}
+ * client (applies to every fetch) and/or per {@link FetchAdParams} call
+ * (merged with the client-wide list).
+ *
+ * ```ts
+ * const adchat = new AdChat({
+ *   fetchKey: process.env.ADCHAT_FETCH_KEY!,
+ *   block: { categories: ['gambling', 'alcohol'], advertisers: ['AcmeCorp'] },
+ * });
+ * ```
+ *
+ * @remarks **Roadmap / beta.** Block lists are sent to the server on every
+ * fetch and are honored where server-side enforcement is available;
+ * category/advertiser enforcement is still rolling out, so treat this as a
+ * best-effort filter rather than a guarantee for now. The SDK surface and the
+ * wire contract are stable — enforcement is tracked as an `ads` follow-up.
+ */
+export interface BlockList {
+    /**
+     * Category codes/labels to block (e.g. `'gambling'`, `'alcohol'`,
+     * `'politics'`). Matched against each candidate ad's categories.
+     */
+    categories?: string[];
+    /**
+     * Advertiser names/ids to block. Ads from these advertisers are excluded
+     * from selection.
+     */
+    advertisers?: string[];
+}
 export interface FetchAdParams {
     /**
-     * Ad unit code identifying the placement. If omitted, the org's default
-     * ad unit is used.
+     * Id of the Application (agent) this fetch is for. Not needed with a fetch
+     * key, which is bound to one application. Required with any other key.
+     * When both are present they must agree. Overrides
+     * {@link AdChatOptions.application}.
+     */
+    application?: string;
+    /**
+     * **Optional — most publishers can omit this.** Ad units are an *Offer
+     * Manager* concept for pinning a specific placement; a plain in-chat-ads
+     * integration doesn't need one. When omitted, the fetch fills against the
+     * application's default ad unit (created on first use). Advanced users pin
+     * a specific unit by code; codes are unique within an application.
      */
     adUnit?: string;
     /** Render format for the payload. Defaults to 'direqt' (universal JSON). */
@@ -41,6 +82,12 @@ export interface FetchAdParams {
     context?: AdContext;
     /** Targeting attributes (key/value pairs) for rule targeting. */
     attributes?: Record<string, string>;
+    /**
+     * Block categories/advertisers for this fetch only. Merged with any
+     * client-wide {@link AdChatOptions.block}. See {@link BlockList} (roadmap /
+     * beta — enforcement is rolling out server-side).
+     */
+    block?: BlockList;
     /**
      * Marks the fetch as a test: excluded from normal reporting and
      * performance statistics.
@@ -50,7 +97,9 @@ export interface FetchAdParams {
 /** Action types on a universal ad payload. */
 export declare enum AdActionType {
     Navigate = "Navigate",
-    Call = "Call"
+    Call = "Call",
+    /** A reply: the tap comes back to your agent with the postback data. */
+    Text = "Text"
 }
 /**
  * A tappable action on an ad (button / suggested reply).
@@ -116,6 +165,46 @@ export interface Ad<P = unknown> {
     media?: AdMedia[];
     isTest?: boolean;
 }
+/**
+ * Reserved, always-fills sandbox ad unit. Fetching this ad unit returns a
+ * canned, clearly-labeled demo card regardless of account configuration —
+ * use it to verify your integration end-to-end before your real ad units
+ * have eligible line items. It records no billing or impression events.
+ */
+export declare const SANDBOX_AD_UNIT = "__sandbox__";
+/**
+ * Machine-readable reason a fetch produced no ad. Returned by
+ * {@link AdChat.fetchAdDebug} so a legitimate empty result can be told apart
+ * from a misconfiguration:
+ *
+ * - `unknown_ad_unit` — no ad unit with that code exists for this org
+ *   (typo, or the API key belongs to a different org). **Misconfiguration.**
+ * - `ad_unit_disabled` — the ad unit exists but is disabled.
+ *   **Misconfiguration.**
+ * - `no_eligible_line_items` — the ad unit exists but has no line
+ *   items configured, or none eligible for this request. **Misconfiguration**
+ *   during onboarding (nothing to serve yet).
+ * - `frequency_capped` — this subscriber has hit the configured frequency
+ *   cap. Normal.
+ * - `appropriateness_suppressed` — serving was suppressed because the
+ *   conversational context was assessed as inappropriate for advertising.
+ *   Normal.
+ * - `no_demand` — everything is configured correctly; there was simply no
+ *   ad to serve right now. Normal (a legitimate no-fill).
+ */
+export type NoFillReason = 'unknown_ad_unit' | 'ad_unit_disabled' | 'no_eligible_line_items' | 'frequency_capped' | 'appropriateness_suppressed' | 'no_demand';
+/**
+ * Result of {@link AdChat.fetchAdDebug}: either a served ad, or a no-fill
+ * with a machine-readable {@link NoFillReason} explaining why.
+ */
+export type FetchAdResult<P = unknown> = {
+    filled: true;
+    ad: Ad<P>;
+} | {
+    filled: false;
+    reason: NoFillReason;
+    message: string;
+};
 /** Event types accepted by the v2 event API. */
 export type AdEventType = 'send' | 'deliver' | 'read' | 'click' | 'conversion';
 export interface RecordEventParams {
@@ -143,6 +232,19 @@ export interface RecordConversionParams {
     data?: object;
     subscriber?: string;
 }
+/**
+ * Result of {@link AdChat.recordInteraction}: the tapped action, and for a
+ * reply with an accept or decline role, the response recorded in the
+ * customer's history.
+ */
+export interface InteractionResult {
+    /** The tapped action's id. */
+    actionId: string;
+    /** The tapped reply's role, if it has one. */
+    role?: 'accept' | 'decline';
+    /** The response recorded in subscriber history, if any. */
+    recorded?: 'accepted' | 'declined';
+}
 export interface ClickUrlParams {
     /** The `messageId` from the fetch response. */
     messageId: string;

package/bin/types.js

@@ -6,13 +6,22 @@
  * the `ads` service (`src/ads-api/v1`) and `ads/ads-api/src/v1/fetch.ts`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AdChatApiError = exports.AdActionType = void 0;
+exports.AdChatApiError = exports.SANDBOX_AD_UNIT = exports.AdActionType = void 0;
 /** Action types on a universal ad payload. */
 var AdActionType;
 (function (AdActionType) {
     AdActionType["Navigate"] = "Navigate";
     AdActionType["Call"] = "Call";
+    /** A reply: the tap comes back to your agent with the postback data. */
+    AdActionType["Text"] = "Text";
 })(AdActionType || (exports.AdActionType = AdActionType = {}));
+/**
+ * Reserved, always-fills sandbox ad unit. Fetching this ad unit returns a
+ * canned, clearly-labeled demo card regardless of account configuration —
+ * use it to verify your integration end-to-end before your real ad units
+ * have eligible line items. It records no billing or impression events.
+ */
+exports.SANDBOX_AD_UNIT = '__sandbox__';
 /**
  * Error thrown for non-2xx API responses.
  *

package/bin/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAyDH,8CAA8C;AAC9C,IAAY,YAGX;AAHD,WAAY,YAAY;IACtB,qCAAqB,CAAA;IACrB,6BAAa,CAAA;AACf,CAAC,EAHW,YAAY,4BAAZ,YAAY,QAGvB;AA0GD;;;;;GAKG;AACH,MAAa,cAAe,SAAQ,KAAK;IAGrB;IAKA;IAPlB;IACE,uCAAuC;IACvB,MAAc;IAC9B;;;OAGG;IACa,MAAe,EAC/B,OAAgB;QAEhB,KAAK,CAAC,OAAO,IAAI,8BAA8B,MAAM,IAAI,MAAM,IAAI,EAAE,EAAE,CAAC,CAAC;QARzD,WAAM,GAAN,MAAM,CAAQ;QAKd,WAAM,GAAN,MAAM,CAAS;QAI/B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAdD,wCAcC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAyGH,8CAA8C;AAC9C,IAAY,YAKX;AALD,WAAY,YAAY;IACtB,qCAAqB,CAAA;IACrB,6BAAa,CAAA;IACb,wEAAwE;IACxE,6BAAa,CAAA;AACf,CAAC,EALW,YAAY,4BAAZ,YAAY,QAKvB;AAmED;;;;;GAKG;AACU,QAAA,eAAe,GAAG,aAAa,CAAC;AA2F7C;;;;;GAKG;AACH,MAAa,cAAe,SAAQ,KAAK;IAGrB;IAKA;IAPlB;IACE,uCAAuC;IACvB,MAAc;IAC9B;;;OAGG;IACa,MAAe,EAC/B,OAAgB;QAEhB,KAAK,CAAC,OAAO,IAAI,8BAA8B,MAAM,IAAI,MAAM,IAAI,EAAE,EAAE,CAAC,CAAC;QARzD,WAAM,GAAN,MAAM,CAAQ;QAKd,WAAM,GAAN,MAAM,CAAS;QAI/B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAdD,wCAcC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@advertising-chat/sdk",
-  "version": "0.2.1",
+  "version": "0.17.3",
   "description": "Typed client for the Advertising.chat ads API — fetch, click, and event tracking plus per-channel render helpers",
   "license": "MIT",
   "author": "Advertising.chat",