@advertising-chat/sdk 0.2.1

package/README.md

@@ -0,0 +1,41 @@
+# @advertising-chat/sdk
+
+Typed client for the [Advertising.chat](https://advertising.chat) ads API —
+fetch ads, track clicks and conversions, and render payloads for your
+channel. Zero runtime dependencies (uses native `fetch`, Node >= 18).
+
+```bash
+npm install @advertising-chat/sdk
+```
+
+```ts
+import { AdChat, renderWebchat, renderWhatsApp, UniversalAdPayload } from '@advertising-chat/sdk';
+
+const adchat = new AdChat({ apiKey: process.env.ADCHAT_API_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?' },
+    { role: 'assistant', text: 'Here are three options...' },
+  ],
+});
+
+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' });
+}
+```
+
+Always present ads clearly labeled as **Sponsored**.
+
+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

@@ -0,0 +1,72 @@
+import { Ad, AdContext, ClickUrlParams, FetchAdParams, RecordConversionParams, RecordEventParams } from './types';
+export interface AdChatOptions {
+    /** Org API key (from the Advertising.chat console). */
+    apiKey: string;
+    /**
+     * Base URL of the ads runtime API.
+     * Defaults to `https://ads.advertising.chat/v1`.
+     */
+    baseUrl?: string;
+    /** Override fetch implementation (mainly for tests). */
+    fetchFn?: typeof fetch;
+}
+/**
+ * Client for the Advertising.chat ads runtime API.
+ *
+ * ```ts
+ * const adchat = new AdChat({ apiKey: process.env.ADCHAT_API_KEY! });
+ * const ad = await adchat.fetchAd({ adUnit: 'my-ad-unit', context: summary });
+ * if (ad) {
+ *   // render ad.payload, then:
+ *   await adchat.recordEvent({ messageId: ad.messageId, type: 'send' });
+ * }
+ * ```
+ */
+export declare class AdChat {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchFn;
+    constructor(options: AdChatOptions);
+    /**
+     * Fetch an ad for a placement.
+     *
+     * Resolves with the served ad, or `null` when no ad is available for
+     * this request (no-fill: frequency caps, targeting, empty ad unit...).
+     * A no-fill is a normal outcome — simply continue the conversation
+     * without an ad.
+     *
+     * Throws {@link AdChatApiError} for request errors (unknown ad unit,
+     * unsupported format, bad API key...).
+     */
+    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.
+     */
+    recordEvent(params: RecordEventParams): Promise<void>;
+    /**
+     * Record a conversion for a previously fetched ad, optionally with a
+     * monetary value.
+     */
+    recordConversion(params: RecordConversionParams): Promise<void>;
+    /**
+     * 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
+     * you construct links yourself.
+     */
+    clickUrl(params: ClickUrlParams): string;
+    private headers;
+    private toApiError;
+}
+/**
+ * Derive the fetch API's structured `conversation` field from structured
+ * context turns. String context has no turn structure, so it is sent only
+ * in the `context` field.
+ */
+export declare function conversationFromContext(context: AdContext, subscriber?: string): {
+    conversationId: string;
+    messages: object[];
+} | undefined;

package/bin/client.js

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdChat = void 0;
+exports.conversationFromContext = conversationFromContext;
+const types_1 = require("./types");
+const DEFAULT_BASE_URL = 'https://ads.advertising.chat/v1';
+/**
+ * Client for the Advertising.chat ads runtime API.
+ *
+ * ```ts
+ * const adchat = new AdChat({ apiKey: process.env.ADCHAT_API_KEY! });
+ * const ad = await adchat.fetchAd({ adUnit: 'my-ad-unit', context: summary });
+ * if (ad) {
+ *   // render ad.payload, then:
+ *   await adchat.recordEvent({ messageId: ad.messageId, type: 'send' });
+ * }
+ * ```
+ */
+class AdChat {
+    apiKey;
+    baseUrl;
+    fetchFn;
+    constructor(options) {
+        if (!options?.apiKey) {
+            throw new Error('AdChat: apiKey is required');
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+        // Bind to globalThis so `fetch` keeps its expected receiver.
+        this.fetchFn = options.fetchFn || fetch.bind(globalThis);
+    }
+    /**
+     * Fetch an ad for a placement.
+     *
+     * Resolves with the served ad, or `null` when no ad is available for
+     * this request (no-fill: frequency caps, targeting, empty ad unit...).
+     * A no-fill is a normal outcome — simply continue the conversation
+     * without an ad.
+     *
+     * Throws {@link AdChatApiError} for request errors (unknown ad unit,
+     * unsupported format, bad API key...).
+     */
+    async fetchAd(params = {}) {
+        const body = {};
+        if (params.adUnit)
+            body.adUnit = params.adUnit;
+        if (params.format)
+            body.format = params.format;
+        if (params.subscriber)
+            body.subscriber = params.subscriber;
+        if (params.attributes)
+            body.attributes = params.attributes;
+        if (params.test)
+            body.test = true;
+        if (params.context !== undefined) {
+            body.context = params.context;
+            // Also populate the fetch API's structured `conversation` field so
+            // context-aware demand sources can use turn-level context today.
+            const conversation = conversationFromContext(params.context, params.subscriber);
+            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;
+    }
+    /**
+     * Record a lifecycle or engagement event ('send', 'deliver', 'read',
+     * 'click', 'conversion') for a previously fetched ad.
+     */
+    async recordEvent(params) {
+        const res = await this.fetchFn(`${this.baseUrl}/event`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify({
+                version: 2,
+                eventType: params.type,
+                fetchEventId: params.messageId,
+                ...(params.data ? { eventData: params.data } : {}),
+                ...(params.subscriber ? { subscriber: params.subscriber } : {}),
+                ...(params.timestamp ? { timestamp: params.timestamp } : {}),
+            }),
+        });
+        if (res.status !== 201) {
+            throw await this.toApiError(res);
+        }
+    }
+    /**
+     * Record a conversion for a previously fetched ad, optionally with a
+     * monetary value.
+     */
+    async recordConversion(params) {
+        return this.recordEvent({
+            messageId: params.messageId,
+            type: 'conversion',
+            subscriber: params.subscriber,
+            data: {
+                ...(params.name ? { conversionName: params.name } : {}),
+                ...(params.value !== undefined ? { value: params.value } : {}),
+                ...(params.currency ? { cur: params.currency } : {}),
+                ...(params.data || {}),
+            },
+        });
+    }
+    /**
+     * 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
+     * you construct links yourself.
+     */
+    clickUrl(params) {
+        const q = new URLSearchParams({
+            key: this.apiKey,
+            postbackData: `${params.messageId}_${params.actionId}`,
+            target: params.targetUrl,
+        });
+        return `${this.baseUrl}/click?${q.toString()}`;
+    }
+    headers() {
+        return {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${this.apiKey}`,
+            'User-Agent': '@advertising-chat/sdk',
+        };
+    }
+    async toApiError(res) {
+        let reason;
+        let description;
+        try {
+            const body = (await res.json());
+            reason = body?.reason;
+            description = body?.description || body?.title;
+        }
+        catch {
+            // non-JSON error body
+        }
+        return new types_1.AdChatApiError(res.status, reason, description
+            ? `Advertising.chat API error ${res.status}: ${description}`
+            : undefined);
+    }
+}
+exports.AdChat = AdChat;
+/**
+ * Derive the fetch API's structured `conversation` field from structured
+ * context turns. String context has no turn structure, so it is sent only
+ * in the `context` field.
+ */
+function conversationFromContext(context, subscriber) {
+    if (typeof context === 'string' || !Array.isArray(context))
+        return undefined;
+    if (context.length === 0)
+        return undefined;
+    const now = Date.now();
+    return {
+        conversationId: `adkit-${now.toString(36)}`,
+        messages: context.map((turn, i) => ({
+            messageId: `adkit-${now.toString(36)}-${i}`,
+            authorId: turn.role === 'assistant' ? 'bot' : subscriber || 'user',
+            text: turn.text,
+            timestamp: new Date(now).toISOString(),
+        })),
+    };
+}
+//# sourceMappingURL=client.js.map

package/bin/client.js.map

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

package/bin/index.d.ts

@@ -0,0 +1,4 @@
+export { AdChat, AdChatOptions, conversationFromContext } from './client';
+export * from './types';
+export { renderWebchat, WebchatMessage, WebchatButton } from './render/webchat';
+export { renderWhatsApp, WhatsAppMessage } from './render/whatsapp';

package/bin/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderWhatsApp = exports.renderWebchat = 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; } });
+__exportStar(require("./types"), exports);
+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; } });
+//# sourceMappingURL=index.js.map

package/bin/index.js.map

@@ -0,0 +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"}

package/bin/render/webchat.d.ts

@@ -0,0 +1,40 @@
+import { UniversalAdPayload } from '../types';
+/**
+ * A webchat-ready message: plain text plus tappable buttons. Maps 1:1
+ * onto typical webchat widget APIs (text + quick replies / buttons).
+ */
+export interface WebchatMessage {
+    /** Message text: title and subtitle on separate lines. */
+    text: string;
+    /** Card image, if the ad has one. */
+    imageUrl?: string;
+    /** Tappable buttons. `url` buttons already point at click-tracking URLs. */
+    buttons: WebchatButton[];
+    /**
+     * Disclosure label. Always render this visibly with the ad
+     * (e.g. as a badge or prefix) — sponsored content must be labeled.
+     */
+    disclosure: string;
+}
+export interface WebchatButton {
+    /** Button label. */
+    label: string;
+    /** Click-tracking URL to open (Navigate actions). */
+    url?: string;
+    /** Phone number to dial (Call actions). */
+    phoneNumber?: string;
+    /** Stable id for the button (the ad action id). */
+    id: string;
+}
+/**
+ * Render a universal ('direqt' format) ad payload as a webchat message.
+ *
+ * ```ts
+ * const ad = await adchat.fetchAd<UniversalAdPayload>({ adUnit: 'chat-footer' });
+ * if (ad) {
+ *   const msg = renderWebchat(ad.payload);
+ *   widget.send({ text: `${msg.disclosure}: ${msg.text}`, buttons: msg.buttons });
+ * }
+ * ```
+ */
+export declare function renderWebchat(payload: UniversalAdPayload): WebchatMessage;

package/bin/render/webchat.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderWebchat = renderWebchat;
+const types_1 = require("../types");
+/**
+ * Render a universal ('direqt' format) ad payload as a webchat message.
+ *
+ * ```ts
+ * const ad = await adchat.fetchAd<UniversalAdPayload>({ adUnit: 'chat-footer' });
+ * if (ad) {
+ *   const msg = renderWebchat(ad.payload);
+ *   widget.send({ text: `${msg.disclosure}: ${msg.text}`, buttons: msg.buttons });
+ * }
+ * ```
+ */
+function renderWebchat(payload) {
+    const lines = [payload.title, payload.subtitle].filter(Boolean);
+    return {
+        text: lines.join('\n') || payload.altText || '',
+        ...(payload.imageUrl ? { imageUrl: payload.imageUrl } : {}),
+        buttons: (payload.actions || []).map(action => ({
+            label: action.text,
+            ...(action.type === types_1.AdActionType.Navigate && action.navigate
+                ? { url: action.navigate.url }
+                : {}),
+            ...(action.type === types_1.AdActionType.Call && action.call
+                ? { phoneNumber: action.call.phoneNumber }
+                : {}),
+            id: action.actionId,
+        })),
+        disclosure: 'Sponsored',
+    };
+}
+//# sourceMappingURL=webchat.js.map

package/bin/render/webchat.js.map

@@ -0,0 +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"}

package/bin/render/whatsapp.d.ts

@@ -0,0 +1,34 @@
+import { UniversalAdPayload } from '../types';
+/**
+ * A WhatsApp Cloud API message object (`POST /<phone>/messages` body),
+ * minus the `to` field — spread in the recipient before sending:
+ *
+ * ```ts
+ * await waClient.post(`/${phoneId}/messages`, { ...renderWhatsApp(ad.payload), to });
+ * ```
+ */
+export type WhatsAppMessage = {
+    messaging_product: 'whatsapp';
+    recipient_type: 'individual';
+    type: 'interactive' | 'image' | 'text';
+    interactive?: object;
+    image?: {
+        link: string;
+        caption?: string;
+    };
+    text?: {
+        body: string;
+        preview_url?: boolean;
+    };
+};
+/**
+ * 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).
+ * - Otherwise → image with caption (or plain text if no image); Navigate
+ *   URLs are appended to the text, SMS-style.
+ */
+export declare function renderWhatsApp(payload: UniversalAdPayload): WhatsAppMessage;

package/bin/render/whatsapp.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderWhatsApp = renderWhatsApp;
+const types_1 = require("../types");
+/**
+ * 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).
+ * - Otherwise → image with caption (or plain text if no image); Navigate
+ *   URLs are appended to the text, SMS-style.
+ */
+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);
+    if (navigateActions.length === 1) {
+        const action = navigateActions[0];
+        return {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            type: 'interactive',
+            interactive: {
+                type: 'cta_url',
+                ...(payload.imageUrl
+                    ? { header: { type: 'image', image: { link: payload.imageUrl } } }
+                    : {}),
+                body: { text: bodyText },
+                footer: { text: 'Sponsored' },
+                action: {
+                    name: 'cta_url',
+                    parameters: {
+                        display_text: truncate(action.text, 20) || 'Learn more',
+                        // Already a click-tracking URL that 302s to the advertiser.
+                        url: action.navigate.url,
+                    },
+                },
+            },
+        };
+    }
+    // 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 {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            type: 'image',
+            image: { link: payload.imageUrl, caption },
+        };
+    }
+    return {
+        messaging_product: 'whatsapp',
+        recipient_type: 'individual',
+        type: 'text',
+        text: { body: caption, preview_url: true },
+    };
+}
+/** WhatsApp cta_url display_text is limited to 20 characters. */
+function truncate(s, max) {
+    if (!s)
+        return s;
+    return s.length <= max ? s : `${s.slice(0, max - 1)}…`;
+}
+//# sourceMappingURL=whatsapp.js.map

package/bin/render/whatsapp.js.map

@@ -0,0 +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"}

package/bin/types.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Types for the Advertising.chat ads runtime API (`ads.advertising.chat/v1`).
+ *
+ * These mirror the server's fetch v2 / event v2 contracts. Ground truth:
+ * the `ads` service (`src/ads-api/v1`) and `ads/ads-api/src/v1/fetch.ts`.
+ */
+/** Render formats supported by fetch v2 (`format` parameter). */
+export type RenderFormat = 'direqt' | 'sms' | 'fbm' | 'html' | 'rcs-google' | 'rcs-gsma' | 'slack' | 'dialogflow';
+/**
+ * One turn of conversation context.
+ *
+ * `role` is 'assistant' for messages authored by the bot/agent and 'user'
+ * for messages authored by the human subscriber.
+ */
+export interface ConversationTurn {
+    role: 'user' | 'assistant';
+    text: string;
+}
+/**
+ * Conversation context for semantic ad selection: either a free-text
+ * summary of the conversation so far, or the most recent turns.
+ */
+export type AdContext = string | ConversationTurn[];
+export interface FetchAdParams {
+    /**
+     * Ad unit code identifying the placement. If omitted, the org's default
+     * ad unit is used.
+     */
+    adUnit?: string;
+    /** Render format for the payload. Defaults to 'direqt' (universal JSON). */
+    format?: RenderFormat;
+    /**
+     * Opaque, org-specific subscriber identifier. Used for frequency caps
+     * and reporting. Never send PII — an anonymized/hashed id is ideal.
+     */
+    subscriber?: string;
+    /**
+     * Conversation context (summary string or recent turns). Passed to the
+     * server for context-aware ad selection.
+     */
+    context?: AdContext;
+    /** Targeting attributes (key/value pairs) for rule targeting. */
+    attributes?: Record<string, string>;
+    /**
+     * Marks the fetch as a test: excluded from normal reporting and
+     * performance statistics.
+     */
+    test?: boolean;
+}
+/** Action types on a universal ad payload. */
+export declare enum AdActionType {
+    Navigate = "Navigate",
+    Call = "Call"
+}
+/**
+ * A tappable action on an ad (button / suggested reply).
+ *
+ * For Navigate actions, `navigate.url` is already a wrapped click-tracking
+ * URL — send the user there directly and the click is recorded before the
+ * redirect to the advertiser.
+ */
+export interface AdAction {
+    type: AdActionType | string;
+    text: string;
+    navigate?: {
+        url: string;
+    };
+    call?: {
+        phoneNumber: string;
+    };
+    /** Postback data: `<messageId>_<actionId>`. */
+    context: string;
+    actionId: string;
+}
+/**
+ * The universal ('direqt' format) ad payload — a card with title,
+ * subtitle, image, and actions.
+ */
+export interface UniversalAdPayload {
+    title: string;
+    subtitle: string;
+    imageUrl: string;
+    actions: AdAction[];
+    /** Plain-text rendering of the ad (used for text-only channels). */
+    altText?: string;
+    displayUrl?: string;
+}
+/** The 'sms' format payload. */
+export interface SmsAdPayload {
+    text: string;
+}
+export interface AdMedia {
+    file_url: string;
+    thumbnail_url: string;
+    content_description: string;
+}
+/**
+ * A served ad, as returned by fetch v2.
+ */
+export interface Ad<P = unknown> {
+    /**
+     * Fetch id for this served ad (e.g. `direqt-<uuid>`). Pass it to
+     * recordEvent()/recordConversion() to attribute events to this ad.
+     */
+    messageId: string;
+    /** Render format of `payload`. */
+    format?: string;
+    /**
+     * The rendered ad. Shape depends on the requested format:
+     * UniversalAdPayload for 'direqt', SmsAdPayload for 'sms', channel-native
+     * JSON for the gateway formats.
+     */
+    payload: P;
+    properties?: Record<string, string>;
+    /** Media files that must be uploaded to the gateway (RBM/FBM only). */
+    media?: AdMedia[];
+    isTest?: boolean;
+}
+/** Event types accepted by the v2 event API. */
+export type AdEventType = 'send' | 'deliver' | 'read' | 'click' | 'conversion';
+export interface RecordEventParams {
+    /** The `messageId` from the fetch response this event belongs to. */
+    messageId: string;
+    /** Lifecycle or engagement event type. */
+    type: AdEventType;
+    /** Arbitrary JSON to associate with the event. */
+    data?: object;
+    /** Subscriber id (only needed if not sent with the fetch). */
+    subscriber?: string;
+    /** Event time (unix ms). Defaults to now, server-side. */
+    timestamp?: number;
+}
+export interface RecordConversionParams {
+    /** The `messageId` from the fetch response this conversion belongs to. */
+    messageId: string;
+    /** Name of the conversion (e.g. 'purchase', 'signup'). */
+    name?: string;
+    /** Monetary value of the conversion. */
+    value?: number;
+    /** ISO-4217 currency for `value` (e.g. 'USD'). */
+    currency?: string;
+    /** Additional JSON to associate with the conversion. */
+    data?: object;
+    subscriber?: string;
+}
+export interface ClickUrlParams {
+    /** The `messageId` from the fetch response. */
+    messageId: string;
+    /** The action id of the tapped action (from `AdAction.actionId`). */
+    actionId: string;
+    /** Destination URL the user should land on after click tracking. */
+    targetUrl: string;
+}
+/**
+ * Error thrown for non-2xx API responses.
+ *
+ * Note that "no ad available" is NOT an error: fetchAd() returns null for
+ * the server's 204 no-fill responses.
+ */
+export declare class AdChatApiError extends Error {
+    /** HTTP status returned by the API. */
+    readonly status: number;
+    /**
+     * Machine-readable reason from the API, when provided
+     * (e.g. 'UnknownAdUnit', 'UnsupportedFormat').
+     */
+    readonly reason?: string | undefined;
+    constructor(
+    /** HTTP status returned by the API. */
+    status: number, 
+    /**
+     * Machine-readable reason from the API, when provided
+     * (e.g. 'UnknownAdUnit', 'UnsupportedFormat').
+     */
+    reason?: string | undefined, message?: string);
+}

package/bin/types.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Types for the Advertising.chat ads runtime API (`ads.advertising.chat/v1`).
+ *
+ * These mirror the server's fetch v2 / event v2 contracts. Ground truth:
+ * 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;
+/** Action types on a universal ad payload. */
+var AdActionType;
+(function (AdActionType) {
+    AdActionType["Navigate"] = "Navigate";
+    AdActionType["Call"] = "Call";
+})(AdActionType || (exports.AdActionType = AdActionType = {}));
+/**
+ * Error thrown for non-2xx API responses.
+ *
+ * Note that "no ad available" is NOT an error: fetchAd() returns null for
+ * the server's 204 no-fill responses.
+ */
+class AdChatApiError extends Error {
+    status;
+    reason;
+    constructor(
+    /** HTTP status returned by the API. */
+    status, 
+    /**
+     * Machine-readable reason from the API, when provided
+     * (e.g. 'UnknownAdUnit', 'UnsupportedFormat').
+     */
+    reason, message) {
+        super(message || `Advertising.chat API error ${status} ${reason || ''}`);
+        this.status = status;
+        this.reason = reason;
+        this.name = 'AdChatApiError';
+    }
+}
+exports.AdChatApiError = AdChatApiError;
+//# sourceMappingURL=types.js.map

package/bin/types.js.map

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@advertising-chat/sdk",
+  "version": "0.2.1",
+  "description": "Typed client for the Advertising.chat ads API — fetch, click, and event tracking plus per-channel render helpers",
+  "license": "MIT",
+  "author": "Advertising.chat",
+  "homepage": "https://docs.advertising.chat/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/advertising-chat/adkit.git",
+    "directory": "packages/sdk"
+  },
+  "keywords": [
+    "advertising",
+    "ads",
+    "chatbot",
+    "llm",
+    "monetization",
+    "conversational-ai"
+  ],
+  "main": "bin/index.js",
+  "types": "bin/index.d.ts",
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "clean": "rm -rf ./bin",
+    "prepack": "npm run clean && npm run build",
+    "test": "mocha"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}