@adcp/sdk 6.7.0 → 6.9.0

package/examples/hello_creative_adapter_template.ts

@@ -50,6 +50,7 @@ import {
   parameterizedRender,
   htmlAsset,
   javascriptAsset,
+  audioAsset,
   urlRender,
   type Format,
   type ListCreativeFormatsResponse,
@@ -82,9 +83,13 @@ interface UpstreamTemplate {
   name: string;
   description: string;
   channel: 'display' | 'video' | 'audio' | 'ctv' | 'native';
+  // SWAP: include any output_kinds your platform emits. The mock supports
+  // four (display HTML, JS, VAST, audio URL); production audio platforms
+  // (AudioStack, ElevenLabs, Resemble) typically output `audio_url` to a
+  // signed CDN endpoint.
   dimensions?: { width: number; height: number };
   duration_seconds?: { min: number; max: number };
-  output_kind: 'html_tag' | 'javascript_tag' | 'vast_xml';
+  output_kind: 'html_tag' | 'javascript_tag' | 'vast_xml' | 'audio_url';
   slots: Array<{
     slot_id: string;
     asset_type: 'image' | 'video' | 'audio' | 'text' | 'click_url';
@@ -102,6 +107,7 @@ interface UpstreamRender {
     tag_html?: string;
     tag_javascript?: string;
     vast_xml?: string;
+    audio_url?: string;
     preview_url?: string;
     assets?: Array<Record<string, unknown>>;
   };
@@ -242,6 +248,37 @@ function projectSlot(s: UpstreamTemplate['slots'][number]) {
   }
 }
 
+/** Output asset slot. The format's `assets[]` mixes input slots (image,
+ *  headline, script — what the buyer provides) with the build_creative
+ *  output slot (`serving_tag` — what the adapter returns). Per
+ *  creative-manifest.json:14 every key in `creative_manifest.assets` MUST
+ *  match a declared `assets[].asset_id`; without the output slot here, our
+ *  build_creative response's `serving_tag` would key against an undeclared
+ *  slot. `required: false` because the buyer doesn't supply this — the
+ *  adapter generates it. asset_type is driven by upstream `output_kind` so
+ *  the discriminator in the response (html / javascript / vast / audio)
+ *  matches the slot the buyer can resolve from `get_format`. */
+function outputSlot(t: UpstreamTemplate) {
+  switch (t.output_kind) {
+    case 'html_tag':
+      return FormatAsset.html({ asset_id: 'serving_tag', required: false });
+    case 'javascript_tag':
+      return FormatAsset.javascript({ asset_id: 'serving_tag', required: false });
+    case 'vast_xml':
+      return FormatAsset.vast({ asset_id: 'serving_tag', required: false });
+    case 'audio_url':
+      return FormatAsset.audio({ asset_id: 'serving_tag', required: false });
+    default: {
+      // Exhaustiveness gate. If `output_kind` grows a fifth case (image_url,
+      // daast_xml, etc.) the unreachable assertion fires at compile time so
+      // adopters extending the upstream type can't ship a silent `undefined`
+      // entry into format.assets[].
+      const exhaustive: never = t.output_kind;
+      throw new Error(`unhandled output_kind: ${exhaustive as string}`);
+    }
+  }
+}
+
 function templateToFormat(t: UpstreamTemplate): Format {
   // Each `renders[]` entry MUST be `{ role, dimensions: { width, height } }`
   // OR `{ role, parameters_from_format_id: true }`. A bare `{ role, width,
@@ -257,15 +294,25 @@ function templateToFormat(t: UpstreamTemplate): Format {
     name: t.name,
     description: t.description,
     renders,
-    assets: t.slots.map(projectSlot),
+    // Input slots (what the buyer provides) + the output slot (what the
+    // adapter generates and returns via build_creative).
+    assets: [...t.slots.map(projectSlot), outputSlot(t)],
   };
 }
 
 /** Project an upstream `render.output` onto AdCP `creative_manifest.assets`.
- *  The mock returns one of three output shapes (HTML tag, JS tag, VAST);
- *  AdCP creative-manifest assets are keyed by asset_id and discriminated by
- *  asset_type. Use the `htmlAsset`/`javascriptAsset` builders to inject the
- *  discriminator — a bare `{ content }` fails the asset-union oneOf. */
+ *  The mock returns one of four output shapes (HTML tag, JS tag, VAST, audio
+ *  URL); AdCP creative-manifest assets are keyed by asset_id and discriminated
+ *  by asset_type. Use the `htmlAsset` / `javascriptAsset` / `audioAsset`
+ *  builders to inject the discriminator — a bare `{ content }` or `{ url }`
+ *  fails the asset-union oneOf.
+ *
+ *  The `serving_tag` asset_id matches the output slot declared by
+ *  `outputSlot(t)` in `templateToFormat`, satisfying creative-manifest.json:14
+ *  ("each key MUST match an asset_id from the format's assets array"). All
+ *  four output kinds (HTML / JS / VAST / audio) key under the same id; the
+ *  asset_type discriminator on the value picks the matching slot's typed
+ *  branch. */
 function projectRenderToManifest(
   render: UpstreamRender,
   formatId: { agent_url: string; id: string }
@@ -284,6 +331,14 @@ function projectRenderToManifest(
     // creative-template storyboard's build step asserts `assets` presence
     // rather than a specific asset_type.
     assets['serving_tag'] = htmlAsset({ content: out.vast_xml });
+  } else if (out.audio_url) {
+    // Audio templates render to a hosted MP3. Real audio platforms return
+    // signed CDN URLs with TTL — the buyer must fetch within the lifetime.
+    // The `audioAsset` builder injects the `asset_type: 'audio'` discriminator
+    // that the AdCP creative-manifest oneOf requires. Reuses the same
+    // `serving_tag` asset_id as the HTML / JS / VAST branches — the asset_type
+    // discriminator is what the buyer keys on, not the asset_id.
+    assets['serving_tag'] = audioAsset({ url: out.audio_url });
   }
   return { format_id: formatId, assets };
 }

package/examples/hello_seller_adapter_guaranteed.ts

@@ -48,6 +48,7 @@
 import {
   createAdcpServerFromPlatform,
   createMediaBuyStore,
+  createInMemoryTaskRegistry,
   InMemoryStateStore,
   serve,
   verifyApiKey,
@@ -55,6 +56,8 @@ import {
   createUpstreamHttpClient,
   memoryBackend,
   AdcpError,
+  getAccountMode,
+  assertMediaBuyTransition,
   type DecisioningPlatform,
   type SalesCorePlatform,
   type SalesIngestionPlatform,
@@ -481,8 +484,56 @@ class SalesGuaranteedAdapter implements DecisioningPlatform<Record<string, never
      *  uses brand.domain, mapped 1:1 onto the mock's `adcp_publisher` field.
      *  Production may use account.publisher or a separate auth-derived
      *  binding. */
-    resolve: async ref => {
-      if (!ref) return null;
+    resolve: async (ref, ctx) => {
+      // ─── TEST-ONLY: auth-derived sandbox fallback ────────────────────
+      // DELETE THIS BLOCK BEFORE DEPLOYING. The framework calls
+      // `accounts.resolve(undefined, ctx)` for tools whose wire request
+      // doesn't carry an account ref — most importantly `tasks/get`, which
+      // the runner's `pollTaskCompletion` uses to follow HITL completions.
+      // Without resolving from `ctx.authInfo` alone, the framework's tenant
+      // boundary on tasks/get refuses every poll (record.accountId set,
+      // resolvedAccountId undefined → REFERENCE_NOT_FOUND fail-closed).
+      //
+      // This worked example accepts a single API key (the test-only token
+      // wired below in `verifyApiKey`), so any authenticated `undefined`
+      // ref is the compliance runner. Synthesize the sandbox singleton.
+      // Production sellers handle this via a real tenant store keyed by
+      // `ctx.authInfo.credential.key_id` (api_key) or
+      // `ctx.authInfo.credential.client_id` (oauth) — they never
+      // synthesize accounts.
+      if (!ref) {
+        if (!ctx?.authInfo) return null;
+        // Mirror whichever account was used at the original
+        // tool-dispatch site so the framework's tenant boundary on
+        // tasks/get treats the auth-derived poll as the same tenant.
+        // The Hello adapter has two account-construction paths:
+        //   (1) the cascade-scenario sandbox arm below, keyed by
+        //       `ref.sandbox === true` and stamped with `mode: 'sandbox'`
+        //       and a `${SANDBOX_ID_PREFIX}${network_code}` id.
+        //   (2) the production path below, keyed by `ref.brand.domain`
+        //       and stamped with the bare `network_code` id (no mode).
+        // The compliance runner exercises path (2) for the
+        // sales_guaranteed HITL flow (no `sandbox: true` on the create
+        // step's account), so the auth-derived ref-less fallback
+        // returns the matching production account here. Production
+        // sellers key this off `ctx.authInfo.credential.key_id` /
+        // `client_id` against a real tenant store.
+        const publisherDomain = 'acmeoutdoor.example';
+        const network = await upstream.lookupNetwork(publisherDomain);
+        if (!network) return null;
+        return {
+          id: network.network_code,
+          name: network.display_name,
+          status: 'active',
+          brand: { domain: network.adcp_publisher },
+          ctx_metadata: {
+            network_code: network.network_code,
+            publisher_domain: network.adcp_publisher,
+          },
+        };
+      }
+      // ─── /TEST-ONLY (auth-derived fallback) ──────────────────────────
+
       // AccountReference discriminated union — see the worked-example notes
       // on the same pattern in hello_seller_adapter_social. The mock has no
       // account_id → network_code index, so the account_id arm is
@@ -502,10 +553,15 @@ class SalesGuaranteedAdapter implements DecisioningPlatform<Record<string, never
       // sandbox tenant their IO desk owns; either way, this in-example
       // synthesis isn't appropriate for prod traffic.
       //
-      // Gate is `ADCP_SANDBOX === '1'` exclusively — single-source so
-      // accidentally setting `ADCP_SANDBOX` in any non-sandbox environment
-      // is the only way this branch fires.
-      if (ref.sandbox === true && process.env['ADCP_SANDBOX'] === '1') {
+      // Gate is `ref.sandbox === true` from the wire `AccountReference`
+      // (per `core/account-ref.json`). Stamping `mode: 'sandbox'` on the
+      // returned `Account` is what admits the framework's
+      // `comply_test_controller` gate — see
+      // `src/lib/server/decisioning/runtime/from-platform.ts` and
+      // `docs/proposals/lifecycle-state-and-sandbox-authority.md`. No env
+      // var is consulted; production traffic that doesn't set
+      // `sandbox: true` on the wire never hits this branch.
+      if (ref.sandbox === true) {
         const sandboxDomain = 'acmeoutdoor.example';
         const network = await upstream.lookupNetwork(sandboxDomain);
         if (!network) return null;
@@ -513,6 +569,7 @@ class SalesGuaranteedAdapter implements DecisioningPlatform<Record<string, never
           id: `${SANDBOX_ID_PREFIX}${network.network_code}`,
           name: `Sandbox: ${network.display_name}`,
           status: 'active',
+          mode: 'sandbox',
           ...(ref.operator !== undefined && { operator: ref.operator }),
           brand: { domain: ref.brand.domain ?? sandboxDomain },
           ctx_metadata: {
@@ -789,6 +846,9 @@ class SalesGuaranteedAdapter implements DecisioningPlatform<Record<string, never
         // but no creatives have been assigned. Buyers transition to
         // `active` after `sync_creatives` lands, which the framework
         // surfaces via `publishStatusChange` on `resource_type: 'media_buy'`.
+        // Stamp the buy's lifecycle entry so update_media_buy can enforce
+        // the spec's MediaBuyStatus state machine on subsequent patches.
+        localBuyStatus.set(order.order_id, 'pending_creatives');
         return {
           media_buy_id: order.order_id,
           status: 'pending_creatives',
@@ -797,7 +857,7 @@ class SalesGuaranteedAdapter implements DecisioningPlatform<Record<string, never
         };
       };
 
-      // ─── TEST-ONLY: HITL bypass for sandbox accounts ─────────────────
+      // ─── TEST-ONLY: HITL bypass for sandbox cascade scenarios ────────
       // DELETE THIS BLOCK BEFORE DEPLOYING. The compliance runner expects
       // synchronous `media_buy_id` for `media_buy_seller/*` cascade
       // scenarios (pending_creatives_to_start / inventory_list_* /
@@ -805,13 +865,21 @@ class SalesGuaranteedAdapter implements DecisioningPlatform<Record<string, never
       // BASE `sales_guaranteed` storyboard tests the IO-signing async
       // path. Production sellers route every buy through the same path —
       // either always-HITL or always-sync, never both based on a runtime
-      // flag. Belt-and-suspenders env re-check below: if the env flag
-      // isn't set even though the id flowed in marked sandbox, fall
-      // through to the production HITL path. Defends against an
-      // upstream-resolved account that somehow carries the sandbox prefix
-      // without the env being sandbox-mode.
-      const isSandbox = ctx.account.id.startsWith(SANDBOX_ID_PREFIX) && process.env['ADCP_SANDBOX'] === '1';
-      if (isSandbox) {
+      // flag.
+      //
+      // Bypass conditions, both required:
+      //   1. Resolver stamped `mode: 'sandbox'` (per `Account.mode`, AdCP
+      //      6.7+). Production accounts default to `'live'` and never hit
+      //      this branch.
+      //   2. Buyer did NOT supply `push_notification_config`. That field is
+      //      the buyer's explicit "I expect HITL / async; webhook me on
+      //      task completion" signal — honoring it is non-negotiable per
+      //      the spec narrative on `sales_guaranteed`. When present, the
+      //      bypass yields to the HITL handoff so the runner's
+      //      `task_completion.<path>` context_outputs resolve from the
+      //      terminal artifact.
+      const buyerWantsHitl = req.push_notification_config != null;
+      if (!buyerWantsHitl && getAccountMode(ctx.account) === 'sandbox') {
         return completeIoAndCreateLineItems();
       }
       // ─── /TEST-ONLY ──────────────────────────────────────────────────
@@ -849,12 +917,36 @@ class SalesGuaranteedAdapter implements DecisioningPlatform<Record<string, never
           }
         }
       }
+
+      // State-machine enforcement. Lifecycle states the upstream mock doesn't
+      // track (`canceled`, `paused`) live in the local tracker; everything else
+      // reads from the upstream order.status mapping. Production sellers swap
+      // this for a single durable lookup against their order DB.
+      //
+      // The spec's `core/state-machine.yaml` declares `canceled` as a sink and
+      // a re-cancel as illegal — `assertMediaBuyTransition` throws
+      // `NOT_CANCELLABLE` on `canceled → canceled`, which is the
+      // `media_buy_seller/invalid_transitions` storyboard's contract.
+      const localStatus = localBuyStatus.get(buyId);
+      const currentStatus: MediaBuyStatus =
+        localStatus === 'canceled' || localStatus === 'paused' ? localStatus : mapMediaBuyStatus(order.status);
+      let nextStatus: MediaBuyStatus = currentStatus;
+      if ((patch as { canceled?: boolean }).canceled === true) {
+        assertMediaBuyTransition(currentStatus, 'canceled');
+        nextStatus = 'canceled';
+        localBuyStatus.set(buyId, nextStatus);
+      } else if ((patch as { paused?: boolean }).paused === true && currentStatus === 'active') {
+        assertMediaBuyTransition(currentStatus, 'paused');
+        nextStatus = 'paused';
+        localBuyStatus.set(buyId, nextStatus);
+      }
+
       // Mock doesn't model partial updates; production wires each patch
       // field onto the upstream's OrderService update endpoint. The
-      // worked example just echoes success.
+      // worked example just echoes success with the post-transition status.
       return {
         media_buy_id: buyId,
-        status: mapMediaBuyStatus(order.status),
+        status: nextStatus,
       };
     },
 
@@ -964,10 +1056,21 @@ class SalesGuaranteedAdapter implements DecisioningPlatform<Record<string, never
           // breakdown from upstream — include an empty array OR project
           // the line-item-level rows the mock returns. Mock's
           // line_item_breakdown carries impressions+spend per LI.
+          //
+          // Required per `media-buy/get-media-buy-delivery-response.json`
+          // (3.0.6): package_id, spend, pricing_model, rate, currency.
+          // The mock doesn't return per-package pricing breakdown, so
+          // the worked example uses the buy-level currency and
+          // 'cpm_guaranteed_fixed' as the pricing model. Production
+          // sellers SWAP for the real per-package pricing record
+          // (look up by package_id against the original buy).
           by_package: (d.line_item_breakdown ?? []).map(li => ({
             package_id: li.line_item_id,
             impressions: li.impressions,
             spend: li.spend,
+            pricing_model: 'cpm' as const,
+            rate: li.impressions > 0 ? (li.spend / li.impressions) * 1000 : 0,
+            currency: d.currency,
           })),
         })),
       };
@@ -997,6 +1100,26 @@ const simulatedDelivery = new Map<
 >();
 // ─── /TEST-ONLY ──────────────────────────────────────────────────────────
 
+// Local per-buy status tracker for state-machine enforcement on
+// `update_media_buy`. The mock-server doesn't model lifecycle transitions
+// (POST /v1/orders/{id} doesn't exist; cancellation is purely an adapter
+// concern in this worked example). Production sellers track buy state in
+// their order DB and check `MEDIA_BUY_TRANSITIONS` against the current
+// status before applying a patch — this Map stands in for that.
+//
+// SWAP: replace with a query against your order/lifecycle service. The
+// `media_buy_seller/invalid_transitions` storyboard exercises NOT_CANCELLABLE
+// on re-cancel (canceled → canceled is illegal per `core/state-machine.yaml`).
+type MediaBuyStatus =
+  | 'pending_creatives'
+  | 'pending_start'
+  | 'active'
+  | 'paused'
+  | 'completed'
+  | 'rejected'
+  | 'canceled';
+const localBuyStatus = new Map<string, MediaBuyStatus>();
+
 // Persist `packages[].targeting_overlay` from create_media_buy and echo it
 // on get_media_buys. The seller spec MANDATES this echo for any seller
 // claiming property-lists / collection-lists, and SHOULD echo any persisted
@@ -1006,12 +1129,21 @@ const simulatedDelivery = new Map<
 const stateStore = new InMemoryStateStore();
 const mediaBuyStore = createMediaBuyStore({ store: stateStore });
 
+// HITL task registry. Hoisted OUTSIDE the `serve()` factory so the
+// instance persists across requests — a fresh registry per request would
+// lose every submitted task between create_media_buy and the buyer's
+// first tasks_get poll. SWAP `createInMemoryTaskRegistry()` for
+// `createPostgresTaskRegistry({ pool })` in production; in-memory
+// in-flight tasks are lost on process restart.
+const taskRegistry = createInMemoryTaskRegistry();
+
 serve(
   ({ taskStore }) =>
     createAdcpServerFromPlatform(platform, {
       name: 'hello-seller-adapter-guaranteed',
       version: '1.0.0',
       taskStore,
+      taskRegistry,
       idempotency: idempotencyStore,
       mediaBuyStore,
       resolveSessionKey: ctx => {
@@ -1024,17 +1156,18 @@ serve(
       // state transitions deterministically across cascade scenarios.
       // Production sellers don't need this surface — and shouldn't ship
       // it. Per `examples/comply-controller-seller.ts`, the recommended
-      // production posture is "don't register the controller at all";
-      // a seller running their own sandbox tenant gates registration on
-      // an env flag controlled by the deploy pipeline (`ADCP_SANDBOX=1`).
+      // production posture is "don't register the controller at all".
       //
-      // SECURITY: gate is `ADCP_SANDBOX === '1'` exclusively — single env
-      // var. Don't add an `|| NODE_ENV === 'test'` clause — staging boxes
-      // commonly run with `NODE_ENV=test` and the controller would open
-      // there too. The gate test (`test/examples/hello-seller-adapter-
-      // guaranteed.test.js`) sets `ADCP_SANDBOX=1` in `extraEnv`.
+      // No `sandboxGate` here — the framework gate inside
+      // `createAdcpServerFromPlatform` resolves the calling principal
+      // through `accounts.resolve` and admits only when the resolved
+      // account's `mode` is `'sandbox'` or `'mock'` (per `Account.mode`
+      // in AdCP 6.7+). The synthesis branch in `accounts.resolve` above
+      // stamps `mode: 'sandbox'` on cascade-scenario refs; production
+      // refs flow through the live path with the field unset (default
+      // `'live'`), so the framework gate refuses dispatch for them.
+      // See `docs/proposals/lifecycle-state-and-sandbox-authority.md`.
       complyTest: {
-        sandboxGate: () => process.env['ADCP_SANDBOX'] === '1',
         seed: {
           media_buy: ({ media_buy_id, fixture }) => {
             const existing = seededMediaBuys.get(media_buy_id);

package/examples/hello_seller_adapter_multi_tenant.ts

@@ -99,8 +99,6 @@ import type {
   DeletePropertyListRequest,
   DeletePropertyListResponse,
   PropertyList,
-} from '@adcp/sdk/types';
-import type {
   GetBrandIdentityRequest,
   GetBrandIdentitySuccess,
   GetRightsRequest,
@@ -108,9 +106,15 @@ import type {
   AcquireRightsRequest,
   AcquireRightsAcquired,
   AcquireRightsRejected,
+  UpdateRightsRequest,
+  UpdateRightsSuccess,
+  CreativeApprovalRequest,
+  CreativeApproved,
+  CreativeRejected,
+  CreativePendingReview,
   RightUse,
   RightType,
-} from '@adcp/sdk/types/core.generated';
+} from '@adcp/sdk/types';
 import { createHash, randomUUID } from 'node:crypto';
 
 const PORT = Number(process.env['PORT'] ?? 3003);
@@ -541,7 +545,7 @@ class MultiTenantAdapter implements DecisioningPlatform<Record<string, never>, T
           // SWAP: row-level write under tenant transaction.
           tenant.governanceBindings.set(brandDomain, {
             governance_agent_url: govUrl,
-            active_plan_id: tenant.active_plan_id,
+            ...(tenant.active_plan_id !== undefined && { active_plan_id: tenant.active_plan_id }),
           });
         } else {
           tenant.governanceBindings.delete(brandDomain);
@@ -665,7 +669,7 @@ class MultiTenantAdapter implements DecisioningPlatform<Record<string, never>, T
       plan.audit.push({
         timestamp: new Date().toISOString(),
         kind: 'outcome',
-        check_id: req.check_id,
+        ...(req.check_id !== undefined && { check_id: req.check_id }),
         detail: { outcome: req.outcome, purchase_type: req.purchase_type, committed_budget: committed },
       });
       return {
@@ -907,6 +911,36 @@ class MultiTenantAdapter implements DecisioningPlatform<Record<string, never>, T
         },
       };
     },
+
+    updateRights: async (req: UpdateRightsRequest, _ctx): Promise<UpdateRightsSuccess> => {
+      // Hello adapter doesn't persist a grant ledger; production adopters
+      // hydrate by `req.rights_id`, apply the patch (extend dates, adjust
+      // impression cap, change pricing, pause/resume), and re-issue
+      // `generation_credentials` + `rights_constraint`. UNSUPPORTED_FEATURE
+      // is the spec-canonical code (manifest.json:702) for "operation supported
+      // by the protocol but not by this implementation" — buyers consult
+      // get_adcp_capabilities to discover supported operations.
+      throw new AdcpError('UNSUPPORTED_FEATURE', {
+        message:
+          'update_rights is not supported by the hello multi-tenant adapter — fork and persist a grant ledger to enable.',
+        details: { rights_id: req.rights_id },
+      });
+    },
+
+    reviewCreativeApproval: async (
+      req: CreativeApprovalRequest,
+      _ctx
+    ): Promise<CreativeApproved | CreativeRejected | CreativePendingReview> => {
+      // Webhook handler dispatched from the adopter's HTTP route at
+      // `acquire_rights.approval_webhook`. Hello adapter auto-approves; real
+      // adopters validate brand-guideline compliance, queue for human review,
+      // or reject with structured `reason` + `suggestions[]`.
+      return {
+        status: 'approved',
+        rights_id: req.rights_id,
+        ...(req.creative_id !== undefined && { creative_id: req.creative_id }),
+      };
+    },
   });
 
   /**