@adcp/sdk 8.1.0-beta.11 → 8.1.0-beta.12

package/dist/lib/wholesale-feed-sync/webhook-notification.js

@@ -0,0 +1,232 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeWholesaleFeedWebhookNotification = exports.WholesaleFeedWebhookNotificationError = void 0;
+exports.parseWholesaleFeedWebhookNotification = parseWholesaleFeedWebhookNotification;
+const errors_1 = require("../errors");
+class WholesaleFeedWebhookNotificationError extends errors_1.ADCPError {
+    code;
+    field;
+    constructor(code, message, details = {}) {
+        super(message, details);
+        this.code = code;
+        this.field = details.field;
+    }
+}
+exports.WholesaleFeedWebhookNotificationError = WholesaleFeedWebhookNotificationError;
+const WHOLESALE_FEED_NOTIFICATION_TYPES = new Set([
+    'product.created',
+    'product.updated',
+    'product.priced',
+    'product.removed',
+    'signal.created',
+    'signal.updated',
+    'signal.priced',
+    'signal.removed',
+    'wholesale_feed.bulk_change',
+]);
+/**
+ * Parse and normalize a canonical wholesale-feed webhook notification.
+ *
+ * The normalized shape intentionally separates `idempotencyKey` (delivery
+ * replay/dedupe) from `eventId` / `notificationId` (domain event identity).
+ * It validates envelope-level invariants, including the canonical
+ * `notification_id === event.event_id` match.
+ */
+function parseWholesaleFeedWebhookNotification(input) {
+    const parsed = parseInput(input);
+    const webhook = readRecord(parsed, '$');
+    const event = readRecord(webhook.event, 'event');
+    const idempotencyKey = readRequiredString(webhook, 'idempotency_key');
+    const notificationId = readRequiredString(webhook, 'notification_id');
+    const notificationType = readNotificationType(readRequiredString(webhook, 'notification_type'), 'notification_type');
+    const firedAt = readRequiredString(webhook, 'fired_at');
+    const subscriberId = readRequiredString(webhook, 'subscriber_id');
+    const accountId = readRequiredString(webhook, 'account_id');
+    const wholesaleFeedVersion = readRequiredString(webhook, 'wholesale_feed_version');
+    const previousWholesaleFeedVersion = readOptionalString(webhook, 'previous_wholesale_feed_version');
+    const cacheScope = readCacheScope(readRequiredString(webhook, 'cache_scope'), 'cache_scope');
+    const eventId = readRequiredString(event, 'event.event_id');
+    if (notificationId !== eventId) {
+        throw new WholesaleFeedWebhookNotificationError('wholesale_feed_webhook_field_invalid', 'wholesale-feed webhook notification_id must match event.event_id.', { field: 'notification_id', expected: eventId, actual: notificationId });
+    }
+    const eventType = readNotificationType(readRequiredString(event, 'event.event_type'), 'event.event_type');
+    if (notificationType !== eventType) {
+        throw new WholesaleFeedWebhookNotificationError('wholesale_feed_webhook_notification_type_mismatch', 'wholesale-feed webhook notification_type must match event.event_type.', { field: 'notification_type', expected: eventType, actual: notificationType });
+    }
+    const entityType = readEntityType(readRequiredString(event, 'event.entity_type'), 'event.entity_type');
+    assertEntityTypeMatchesNotification(notificationType, entityType);
+    const entityId = readRequiredString(event, 'event.entity_id');
+    const eventCreatedAt = readRequiredString(event, 'event.created_at');
+    const payload = readRecord(event.payload, 'event.payload');
+    const payloadScope = readRequiredPayloadScope(payload);
+    if (payloadScope !== cacheScope) {
+        throw new WholesaleFeedWebhookNotificationError('wholesale_feed_webhook_cache_scope_mismatch', 'wholesale-feed webhook cache_scope must match event.payload.applies_to.scope.', { field: 'cache_scope', expected: payloadScope, actual: cacheScope });
+    }
+    const affectedEntityType = validatePayloadForEvent(notificationType, entityId, payload);
+    return {
+        idempotencyKey,
+        notificationId,
+        notificationType,
+        accountId,
+        subscriberId,
+        firedAt,
+        wholesaleFeedVersion,
+        ...(previousWholesaleFeedVersion !== undefined && { previousWholesaleFeedVersion }),
+        cacheScope,
+        eventId,
+        eventType,
+        entityType,
+        entityId,
+        eventCreatedAt,
+        ...(affectedEntityType !== undefined && { affectedEntityType }),
+        event: event,
+        webhook: webhook,
+    };
+}
+exports.normalizeWholesaleFeedWebhookNotification = parseWholesaleFeedWebhookNotification;
+function parseInput(input) {
+    if (typeof input === 'string')
+        return parseJson(input);
+    if (input instanceof Uint8Array)
+        return parseJson(new TextDecoder().decode(input));
+    return input;
+}
+function parseJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new WholesaleFeedWebhookNotificationError('wholesale_feed_webhook_body_malformed', 'wholesale-feed webhook body must be valid JSON.', { field: '$', actual: err instanceof Error ? err.message : String(err) });
+    }
+}
+function readRecord(value, field) {
+    if (value && typeof value === 'object' && !Array.isArray(value))
+        return value;
+    throw new WholesaleFeedWebhookNotificationError(field === '$' ? 'wholesale_feed_webhook_body_malformed' : 'wholesale_feed_webhook_field_invalid', field === '$'
+        ? 'wholesale-feed webhook body must be a JSON object.'
+        : `wholesale-feed webhook field ${field} must be an object.`, { field, expected: 'object', actual: describeValue(value) });
+}
+function readRequiredRecord(obj, field) {
+    const key = field.includes('.') ? field.slice(field.lastIndexOf('.') + 1) : field;
+    const value = obj[key];
+    if (value === undefined) {
+        throw new WholesaleFeedWebhookNotificationError('wholesale_feed_webhook_field_missing', `wholesale-feed webhook field ${field} must be an object.`, { field, expected: 'object', actual: describeValue(value) });
+    }
+    return readRecord(value, field);
+}
+function readRequiredString(obj, field) {
+    const key = field.includes('.') ? field.slice(field.lastIndexOf('.') + 1) : field;
+    const value = obj[key];
+    if (typeof value === 'string' && value.length > 0)
+        return value;
+    throw new WholesaleFeedWebhookNotificationError(value === undefined ? 'wholesale_feed_webhook_field_missing' : 'wholesale_feed_webhook_field_invalid', `wholesale-feed webhook field ${field} must be a non-empty string.`, { field, expected: 'non-empty string', actual: describeValue(value) });
+}
+function readRequiredNonEmptyArray(obj, field) {
+    const key = field.includes('.') ? field.slice(field.lastIndexOf('.') + 1) : field;
+    const value = obj[key];
+    if (Array.isArray(value) && value.length > 0)
+        return value;
+    throw new WholesaleFeedWebhookNotificationError(value === undefined ? 'wholesale_feed_webhook_field_missing' : 'wholesale_feed_webhook_field_invalid', `wholesale-feed webhook field ${field} must be a non-empty array.`, { field, expected: 'non-empty array', actual: describeValue(value) });
+}
+function readRequiredPositiveInteger(obj, field) {
+    const key = field.includes('.') ? field.slice(field.lastIndexOf('.') + 1) : field;
+    const value = obj[key];
+    if (Number.isInteger(value) && value > 0)
+        return value;
+    throw new WholesaleFeedWebhookNotificationError(value === undefined ? 'wholesale_feed_webhook_field_missing' : 'wholesale_feed_webhook_field_invalid', `wholesale-feed webhook field ${field} must be a positive integer.`, { field, expected: 'positive integer', actual: describeValue(value) });
+}
+function readOptionalString(obj, field) {
+    const value = obj[field];
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'string' && value.length > 0)
+        return value;
+    throw new WholesaleFeedWebhookNotificationError('wholesale_feed_webhook_field_invalid', `wholesale-feed webhook field ${field} must be a non-empty string when present.`, { field, expected: 'non-empty string', actual: describeValue(value) });
+}
+function readNotificationType(value, field) {
+    if (WHOLESALE_FEED_NOTIFICATION_TYPES.has(value)) {
+        return value;
+    }
+    throw new WholesaleFeedWebhookNotificationError('wholesale_feed_webhook_field_invalid', `wholesale-feed webhook field ${field} is not a supported wholesale-feed notification type.`, { field, expected: [...WHOLESALE_FEED_NOTIFICATION_TYPES], actual: value });
+}
+function readCacheScope(value, field) {
+    if (value === 'public' || value === 'account')
+        return value;
+    throw new WholesaleFeedWebhookNotificationError('wholesale_feed_webhook_field_invalid', `wholesale-feed webhook field ${field} must be "public" or "account".`, { field, expected: ['public', 'account'], actual: value });
+}
+function readEntityType(value, field) {
+    if (value === 'product' || value === 'signal' || value === 'feed')
+        return value;
+    throw new WholesaleFeedWebhookNotificationError('wholesale_feed_webhook_field_invalid', `wholesale-feed webhook field ${field} must be "product", "signal", or "feed".`, { field, expected: ['product', 'signal', 'feed'], actual: value });
+}
+function assertEntityTypeMatchesNotification(notificationType, entityType) {
+    const expected = notificationType.startsWith('product.')
+        ? 'product'
+        : notificationType.startsWith('signal.')
+            ? 'signal'
+            : 'feed';
+    if (entityType !== expected) {
+        throw new WholesaleFeedWebhookNotificationError('wholesale_feed_webhook_entity_type_mismatch', 'wholesale-feed webhook event.entity_type does not match event.event_type.', { field: 'event.entity_type', expected, actual: entityType });
+    }
+}
+function validatePayloadForEvent(notificationType, entityId, payload) {
+    switch (notificationType) {
+        case 'product.created':
+        case 'product.updated': {
+            assertEntityIdMatchesPayload(entityId, readRequiredString(payload, 'event.payload.product_id'), 'product_id');
+            readRequiredRecord(payload, 'event.payload.product');
+            return undefined;
+        }
+        case 'product.priced': {
+            assertEntityIdMatchesPayload(entityId, readRequiredString(payload, 'event.payload.product_id'), 'product_id');
+            readRequiredNonEmptyArray(payload, 'event.payload.pricing_options');
+            return undefined;
+        }
+        case 'product.removed': {
+            assertEntityIdMatchesPayload(entityId, readRequiredString(payload, 'event.payload.product_id'), 'product_id');
+            return undefined;
+        }
+        case 'signal.created':
+        case 'signal.updated': {
+            assertEntityIdMatchesPayload(entityId, readRequiredString(payload, 'event.payload.signal_agent_segment_id'), 'signal_agent_segment_id');
+            readRequiredRecord(payload, 'event.payload.signal');
+            return undefined;
+        }
+        case 'signal.priced': {
+            assertEntityIdMatchesPayload(entityId, readRequiredString(payload, 'event.payload.signal_agent_segment_id'), 'signal_agent_segment_id');
+            readRequiredNonEmptyArray(payload, 'event.payload.pricing_options');
+            return undefined;
+        }
+        case 'signal.removed': {
+            assertEntityIdMatchesPayload(entityId, readRequiredString(payload, 'event.payload.signal_agent_segment_id'), 'signal_agent_segment_id');
+            return undefined;
+        }
+        case 'wholesale_feed.bulk_change':
+            readRequiredString(payload, 'event.payload.summary');
+            readRequiredPositiveInteger(payload, 'event.payload.affected_count');
+            return readBulkChangeAffectedEntityType(payload);
+    }
+}
+function assertEntityIdMatchesPayload(entityId, payloadEntityId, payloadField) {
+    if (entityId === payloadEntityId)
+        return;
+    throw new WholesaleFeedWebhookNotificationError('wholesale_feed_webhook_field_invalid', `wholesale-feed webhook event.entity_id must match event.payload.${payloadField}.`, { field: 'event.entity_id', expected: payloadEntityId, actual: entityId });
+}
+function readRequiredPayloadScope(payload) {
+    const appliesToRecord = readRequiredRecord(payload, 'event.payload.applies_to');
+    return readCacheScope(readRequiredString(appliesToRecord, 'event.payload.applies_to.scope'), 'event.payload.applies_to.scope');
+}
+function readBulkChangeAffectedEntityType(payload) {
+    const affected = payload.affected_entity_type;
+    if (affected === 'product' || affected === 'signal')
+        return affected;
+    throw new WholesaleFeedWebhookNotificationError('wholesale_feed_webhook_bulk_change_invalid', 'wholesale_feed.bulk_change payload requires affected_entity_type of "product" or "signal".', { field: 'event.payload.affected_entity_type', expected: ['product', 'signal'], actual: describeValue(affected) });
+}
+function describeValue(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+//# sourceMappingURL=webhook-notification.js.map

package/dist/lib/wholesale-feed-sync/webhook-notification.js.map

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

package/docs/guides/BUILD-AN-AGENT.md

@@ -9,7 +9,7 @@ We'll build a **signals agent** that serves audience segments via the `get_signa
 ## Prerequisites
 
 - Node.js 18+
-- `@adcp/sdk` installed (`npm install @adcp/sdk`)
+- `@adcp/sdk` installed from the beta line while validating AdCP 3.1 (`npm install @adcp/sdk@beta`)
 - `@modelcontextprotocol/sdk` (installed as a dependency of `@adcp/sdk`)
 
 ## The server entry point
@@ -86,8 +86,8 @@ Start it and test immediately:
 
 ```bash
 npx tsx agent.ts
-npx @adcp/sdk@latest http://localhost:3001/mcp                    # discover tools
-npx @adcp/sdk@latest http://localhost:3001/mcp get_signals '{}'   # call get_signals
+npx @adcp/sdk@beta http://localhost:3001/mcp                    # discover tools
+npx @adcp/sdk@beta http://localhost:3001/mcp get_signals '{}'   # call get_signals
 ```
 
 `definePlatform` / `defineSignalsPlatform` (and the sibling
@@ -133,14 +133,20 @@ const platform = definePlatform({
     list: async (filter, ctx) => db.listAccounts(filter, { agentUrl: ctx?.agent?.agent_url }),
   },
   sales: defineSalesCorePlatform({
-    getProducts: async (req, ctx) => ({ products: catalog.search(req) }), // req typed ✓
+    getProducts: async (req, ctx) => {
+      const result = catalog.search(req);
+      return {
+        products: result.products,
+        cache_scope: result.usesAccountSpecificPricing ? 'account' : 'public',
+      };
+    }, // req typed ✓
     createMediaBuy: async (req, ctx) => ({
       media_buy_id: `mb_${Date.now()}`,
-      status: 'pending_creatives',
+      media_buy_status: 'pending_creatives',
       confirmed_at: new Date().toISOString(),
       packages: [],
     }),
-    updateMediaBuy: async (id, patch, ctx) => ({ media_buy_id: id, status: 'active' }),
+    updateMediaBuy: async (id, patch, ctx) => ({ media_buy_id: id, media_buy_status: 'active' }),
     getMediaBuyDelivery: async (req, ctx) => ({ media_buys: [] }),
     getMediaBuys: async (req, ctx) => ({ media_buys: [] }),
   }),
@@ -299,9 +305,13 @@ Every handler receives `ctx.store` — a key-value store for persisting domain o
 ```typescript
 mediaBuy: {
   createMediaBuy: async (params, ctx) => {
-    const mediaBuy = { media_buy_id: `mb_${Date.now()}`, status: 'pending', packages: [] };
+    const mediaBuy = { media_buy_id: `mb_${Date.now()}`, status: 'pending_creatives', packages: [] };
     await ctx.store.put('media_buys', mediaBuy.media_buy_id, mediaBuy);
-    return mediaBuy;
+    return {
+      media_buy_id: mediaBuy.media_buy_id,
+      media_buy_status: mediaBuy.status,
+      packages: mediaBuy.packages,
+    };
   },
   getMediaBuys: async (params, ctx) => {
     if (params.media_buy_ids?.length) {
@@ -346,7 +356,7 @@ const platform = definePlatform({
     getProducts: async (req, ctx) => {
       // ctx.account is the resolved account
       const products = await catalog.search(req, ctx.account.id);
-      return { products };
+      return { products, cache_scope: 'account' };
     },
     /* ... */
   }),
@@ -575,12 +585,18 @@ return wrapEnvelope(
 
 ### Response Builders
 
-With `createAdcpServerFromPlatform`, response builders are applied automatically — return raw data and the framework wraps it. If you need manual control (e.g., with `createTaskCapableServer`), builders are available:
+With `createAdcpServerFromPlatform`, return handler payloads, not full wire envelopes. The framework owns protocol fields such as task `status`, `task_id`, `adcp_version`, context echoing, and response validation. Domain lifecycle fields remain part of your payload: for media buys use `media_buy_status`, while nested resources such as accounts, creatives, audiences, and `media_buys[]` keep their resource `status` fields.
+
+For `getProducts`, any response that includes `products` or `unchanged: true` must also include `cache_scope`. Use `public` for a universal rate card and `account` when the response includes account-specific rate cards or pricing overlays. The framework can safely infer `public` only when there is no inline account and no auth-derived/resolved account; account-scoped product responses should set the field explicitly.
+
+If you need manual control (e.g., with `createTaskCapableServer`), builders are available:
 
 ```typescript
 import { productsResponse, mediaBuyResponse, deliveryResponse, taskToolResponse } from '@adcp/sdk';
 // For error envelopes, throw a typed error class — `AuthRequiredError`,
 // `PermissionDeniedError`, `RateLimitedError`, etc. — from `@adcp/sdk/server`.
+
+const response = productsResponse({ products, cache_scope: 'public' });
 ```
 
 ### Task Statuses (Server-Side Contract)
@@ -708,7 +724,7 @@ const httpServer = createServer(async (req, res) => {
 ### Tool Discovery
 
 ```bash
-npx @adcp/sdk@latest http://localhost:3001/mcp
+npx @adcp/sdk@beta http://localhost:3001/mcp
 ```
 
 This lists all tools your agent exposes, their descriptions, and parameters. If `get_signals` appears with the correct schema, your agent is wired up correctly.
@@ -717,16 +733,16 @@ This lists all tools your agent exposes, their descriptions, and parameters. If
 
 ```bash
 # All segments
-npx @adcp/sdk@latest http://localhost:3001/mcp get_signals '{"signal_spec":"audience segments"}'
+npx @adcp/sdk@beta http://localhost:3001/mcp get_signals '{"signal_spec":"audience segments"}'
 
 # Filtered by text
-npx @adcp/sdk@latest http://localhost:3001/mcp get_signals '{"signal_spec":"shoppers"}'
+npx @adcp/sdk@beta http://localhost:3001/mcp get_signals '{"signal_spec":"shoppers"}'
 
 # Filtered by catalog type
-npx @adcp/sdk@latest http://localhost:3001/mcp get_signals '{"filters":{"catalog_types":["marketplace"]}}'
+npx @adcp/sdk@beta http://localhost:3001/mcp get_signals '{"filters":{"catalog_types":["marketplace"]}}'
 
 # JSON output for scripting
-npx @adcp/sdk@latest http://localhost:3001/mcp get_signals '{}' --json
+npx @adcp/sdk@beta http://localhost:3001/mcp get_signals '{}' --json
 ```
 
 ```bash
@@ -734,7 +750,7 @@ npx @adcp/sdk@latest http://localhost:3001/mcp get_signals '{}' --json
 # Schema traps: idempotency_key must be 16-255 chars (UUID v4 recommended);
 # package-level budget is a plain number (not {amount,currency}); brand uses {domain} (not {brand_id});
 # packages require product_id, budget, and pricing_option_id
-npx @adcp/sdk@latest http://localhost:3001/mcp create_media_buy '{
+npx @adcp/sdk@beta http://localhost:3001/mcp create_media_buy '{
   "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
   "account": { "account_id": "acct_123" },
   "brand": { "domain": "acme.example" },
@@ -749,7 +765,7 @@ npx @adcp/sdk@latest http://localhost:3001/mcp create_media_buy '{
 ### Compliance Check
 
 ```bash
-npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp
+npx @adcp/sdk@beta storyboard run http://localhost:3001/mcp
 ```
 
 This runs a standard validation suite against your agent to check AdCP compliance. For the full validation picture — storyboard runner, property-based fuzzing (`adcp fuzz`), multi-instance testing, webhook conformance, request-signing, schema-driven validation, and the skill→agent→grader dogfood harness — see [**VALIDATE-YOUR-AGENT.md**](./VALIDATE-YOUR-AGENT.md).

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-05-22
-> Library: @adcp/sdk v8.1.0-beta.0
+> Generated at: 2026-05-26
+> Library: @adcp/sdk v8.1.0-beta.11
 > AdCP major version: 3
 > Canonical URL: https://adcontextprotocol.github.io/adcp-client/llms.txt
 > Note: the `Library` stamp reflects the package.json version at doc-generation time. The narrative below describes the surface that lands on the next-published minor — including any 6.7 helpers documented here ahead of the release tag.
@@ -312,6 +312,10 @@ Request parameters for discovering available advertising products.
 **Response (success branch):**
 - Optional: `products: object[]`, `extensions: object`, `proposals: object[]`, `errors: object[]`, `property_list_applied: boolean`, `catalog_applied: boolean`, `refinement_applied: object[]`, `incomplete: object[]`, +8 more
 
+**Watch out:**
+- `cache_scope` is required whenever the response includes `products` or `unchanged: true`. Use `public` for the universal rate card and `account` for account-specific rate cards or pricing overlays.
+- SDK server handlers may omit `cache_scope` only for no-account product feeds; the framework can safely infer `public` only when there is no inline account and no auth-derived/resolved account.
+
 #### `list_creative_formats`
 
 Request parameters for discovering format IDs and creative agents supported by this sales agent.
@@ -340,6 +344,9 @@ Request parameters for creating a media buy.
 - Required: `media_buy_id: string`, `packages: object[]`
 - Optional: `account: Account`, `invoice_recipient: Business Entity`, `media_buy_status: Media Buy Status`, `status: Media Buy Status`, `confirmed_at: string`, `creative_deadline: string`, `revision: integer`, `currency: string`, +6 more
 
+**Watch out:**
+- Server handlers should return business lifecycle state as `media_buy_status`. The framework owns the task envelope `status`; do not return top-level `status` as the media-buy state.
+
 #### `update_media_buy`
 
 Request parameters for updating campaign and package settings.
@@ -352,6 +359,9 @@ Request parameters for updating campaign and package settings.
 - Required: `media_buy_id: string`
 - Optional: `media_buy_status: Media Buy Status`, `status: Media Buy Status`, `revision: integer`, `currency: string`, `total_budget: number`, `implementation_date: string,null`, `invoice_recipient: Business Entity`, `affected_packages: object[]`, +4 more
 
+**Watch out:**
+- Server handlers should return business lifecycle state as `media_buy_status`. The framework owns the task envelope `status`; do not return top-level `status` as the media-buy state.
+
 #### `get_media_buys`
 
 Request parameters for retrieving media buy status, creative approvals, and delivery snapshots.
@@ -1416,4 +1426,4 @@ JSON schemas (source of truth): `schemas/cache/latest/index.json` (local only)
 - Documentation: https://adcontextprotocol.github.io/adcp-client/
 - npm: https://www.npmjs.com/package/@adcp/sdk
 - Spec: https://adcontextprotocol.org
-- CLI: `npx @adcp/sdk@latest`
+- CLI: `npx @adcp/sdk@beta` for the 8.1 / AdCP 3.1 beta line

package/examples/decisioning-platform-broadcast-tv.ts

@@ -34,11 +34,11 @@ import {
   type SalesCorePlatform,
   type SalesIngestionPlatform,
   type AccountStore,
+  type GetProductsPayload,
   type SyncCreativesRow,
 } from '@adcp/sdk/server';
 import type {
   GetProductsRequest,
-  GetProductsResponse,
   CreateMediaBuyRequest,
   CreateMediaBuySuccess,
   UpdateMediaBuyRequest,
@@ -117,7 +117,7 @@ export class BroadcastTvSeller implements DecisioningPlatform<BroadcastTvConfig,
      * the eventual products via `publishStatusChange` on
      * `resource_type: 'proposal'`.
      */
-    getProducts: async (req: GetProductsRequest): Promise<GetProductsResponse> => {
+    getProducts: async (req: GetProductsRequest): Promise<GetProductsPayload> => {
       const promotedOffering = (req as { promoted_offering?: string }).promoted_offering ?? '';
       if (/political|cannabis|gambling/i.test(promotedOffering)) {
         throw new AdcpError('POLICY_VIOLATION', {
@@ -129,7 +129,7 @@ export class BroadcastTvSeller implements DecisioningPlatform<BroadcastTvConfig,
       }
 
       return {
-        status: 'completed' as const,
+        cache_scope: 'account' as const,
         products: [
           {
             product_id: 'prod_primetime_30s',

package/examples/decisioning-platform-mock-seller.ts

@@ -47,11 +47,11 @@ import {
   type SalesIngestionPlatform,
   type AccountStore,
   type AdcpStructuredError,
+  type GetProductsPayload,
   type SyncCreativesRow,
 } from '@adcp/sdk/server';
 import type {
   GetProductsRequest,
-  GetProductsResponse,
   CreateMediaBuyRequest,
   CreateMediaBuySuccess,
   UpdateMediaBuyRequest,
@@ -146,8 +146,8 @@ function rejectPreflight(errors: AdcpStructuredError[]): never {
   });
 }
 
-const SHARED_GET_PRODUCTS = async (_req: GetProductsRequest): Promise<GetProductsResponse> => ({
-  status: 'completed' as const,
+const SHARED_GET_PRODUCTS = async (_req: GetProductsRequest): Promise<GetProductsPayload> => ({
+  cache_scope: 'account' as const,
   products: [
     {
       product_id: 'prod_premium_video',

package/examples/decisioning-platform-programmatic.ts

@@ -28,11 +28,11 @@ import {
   type SalesCorePlatform,
   type SalesIngestionPlatform,
   type AccountStore,
+  type GetProductsPayload,
   type SyncCreativesRow,
 } from '@adcp/sdk/server';
 import type {
   GetProductsRequest,
-  GetProductsResponse,
   CreateMediaBuyRequest,
   CreateMediaBuySuccess,
   UpdateMediaBuyRequest,
@@ -97,8 +97,8 @@ export class ProgrammaticSeller implements DecisioningPlatform<ProgrammaticConfi
 
   sales: SalesCorePlatform<ProgrammaticMeta> & SalesIngestionPlatform<ProgrammaticMeta> = {
     /** Sync discovery: catalog read; no async ceremony. */
-    getProducts: async (_req: GetProductsRequest): Promise<GetProductsResponse> => ({
-      status: 'completed' as const,
+    getProducts: async (_req: GetProductsRequest): Promise<GetProductsPayload> => ({
+      cache_scope: 'account' as const,
       products: [
         {
           product_id: 'prod_run_of_network_display',

package/examples/hello_seller_adapter_proposal_mode.ts

@@ -47,6 +47,7 @@ import {
   type DecisioningPlatform,
   type FinalizeProposalRequest,
   type FinalizeProposalSuccess,
+  type GetProductsPayload,
   type ProposalManager,
   type SalesCorePlatform,
 } from '@adcp/sdk/server';
@@ -349,11 +350,11 @@ const proposalManager: ProposalManager<GAMLikeRecipe, NetworkMeta> = {
     availabilityReservations: true,
   },
 
-  async getProducts(req: GetProductsRequest, ctx): Promise<GetProductsResponse> {
+  async getProducts(req: GetProductsRequest, ctx): Promise<GetProductsPayload> {
     const networkCode = ctx.account.ctx_metadata.network_code;
     const publisherDomain = ctx.account.ctx_metadata.publisher_domain;
     const products = await upstream.listProducts(networkCode);
-    if (products.length === 0) return { status: 'completed', products: [], cache_scope: 'account' };
+    if (products.length === 0) return { products: [], cache_scope: 'account' };
 
     // brief + total_budget signals → curated proposal. Without a brief
     // the buyer is browsing the catalog; skip proposal generation.
@@ -362,7 +363,7 @@ const proposalManager: ProposalManager<GAMLikeRecipe, NetworkMeta> = {
     if (!brief) {
       // Catalog mode — return products with recipes, no proposals.
       const productsOut = products.map(p => projectProduct(p, publisherDomain, buildGAMLikeRecipe(p)));
-      return { status: 'completed', products: productsOut, cache_scope: 'account' };
+      return { products: productsOut, cache_scope: 'account' };
     }
 
     const draft = await upstream.createProposal(networkCode, {
@@ -374,14 +375,13 @@ const proposalManager: ProposalManager<GAMLikeRecipe, NetworkMeta> = {
       .filter(p => referencedIds.has(p.product_id))
       .map(p => projectProduct(p, publisherDomain, buildGAMLikeRecipe(p)));
     return {
-      status: 'completed',
       products: productsOut,
       proposals: [projectProposal(draft, totalBudget)],
       cache_scope: 'account',
     };
   },
 
-  async refineProducts(req: GetProductsRequest, ctx): Promise<GetProductsResponse> {
+  async refineProducts(req: GetProductsRequest, ctx): Promise<GetProductsPayload> {
     const networkCode = ctx.account.ctx_metadata.network_code;
     const publisherDomain = ctx.account.ctx_metadata.publisher_domain;
     const refine =
@@ -402,7 +402,6 @@ const proposalManager: ProposalManager<GAMLikeRecipe, NetworkMeta> = {
       .filter(p => referencedIds.has(p.product_id))
       .map(p => projectProduct(p, publisherDomain, buildGAMLikeRecipe(p)));
     return {
-      status: 'completed',
       products: productsOut,
       proposals: [projectProposal(refined)],
       cache_scope: 'account',
@@ -463,7 +462,7 @@ const sales: SalesCorePlatform<NetworkMeta> = {
   // getProducts is owned by proposalManager when wired; the framework
   // routes there. We keep this empty at the type level — the framework
   // never reaches it.
-  getProducts: async () => ({ status: 'completed', products: [], cache_scope: 'account' }),
+  getProducts: async () => ({ products: [], cache_scope: 'account' }),
 
   async createMediaBuy(req: CreateMediaBuyRequest, ctx): Promise<CreateMediaBuySuccess> {
     const networkCode = ctx.account.ctx_metadata.network_code;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "8.1.0-beta.11",
+  "version": "8.1.0-beta.12",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",

package/skills/build-decisioning-platform/SKILL.md

@@ -104,6 +104,7 @@ class MyPlatform implements DecisioningPlatform {
     getProducts: async (req, ctx) => {
       const products = await this.platform.searchInventory(req.brief, req.promoted_offering);
       return {
+        cache_scope: 'account',
         products: products.map(p => ({
           product_id: p.id,
           name: p.name,

package/skills/build-decisioning-platform/advanced/REFERENCE.md

@@ -57,6 +57,7 @@ const platform = {
   sales: {
     getProducts: async (req, ctx) => ({
       status: 'completed',
+      cache_scope: 'account',
       products: [
         {
           product_id: 'p_homepage',
@@ -139,7 +140,7 @@ getProducts: async (req, ctx) => {
   for (const p of products) {
     await ctx.ctxMetadata?.set('product', p.id, { gam: { ad_unit_ids: p.adUnitIds } });
   }
-  return { products: products.map(toAdcpProduct) };
+  return { products: products.map(toAdcpProduct), cache_scope: 'account' };
 },
 
 // Read on the way in (subsequent call referencing the same ID):

package/skills/call-adcp-agent/SKILL.md

@@ -136,7 +136,7 @@ Every validation failure produces:
 }
 ```
 
-Returns `{ products: [{ product_id, name, description, delivery_type, pricing_options, ... }] }`.
+Returns `{ cache_scope: "public" | "account", products: [{ product_id, name, description, delivery_type, pricing_options, ... }] }`.
 
 ### create_media_buy