@adcp/sdk 6.7.0 → 6.8.0

package/examples/README.md

@@ -6,23 +6,39 @@ This directory contains practical examples of how to use the `@adcp/sdk` library
 
 Pick the example whose AdCP role and specialism most closely match what you're building, fork the file, replace the `// SWAP:` markers, and follow the `FORK CHECKLIST` block at the top of each adapter for the unmarked but load-bearing constants. Each adapter is paired with a three-gate CI test (strict tsc / storyboard / upstream-traffic) so a regression in your fork fails CI before it ships.
 
-| If you're claiming…                | Fork                                              | Then…                                                                                                                                          |
-| ---------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `signal-marketplace` / `signal-owned` | `hello_signals_adapter_marketplace.ts`         | as-is for marketplace; `signal-owned` adopters drop the marketplace-specific tax/rev-share fields                                              |
-| `creative-template`                | `hello_creative_adapter_template.ts`              | as-is — single-tenant; production adopters add per-tenant workspace binding (see SWAP markers)                                                 |
-| `creative-generative`              | `hello_creative_adapter_template.ts`              | replace template-driven `buildCreative` with brief-driven generation; keep the `previewCreative` shape                                         |
-| `creative-ad-server`               | `hello_creative_adapter_template.ts`              | promote to `CreativeAdServerPlatform`, add `syncCreatives` library + `listCreatives` query + tag-rendering on `buildCreative`                  |
-| `sales-non-guaranteed`             | `hello_seller_adapter_social.ts`                  | drop OAuth (use static Bearer or your auth), add `getProducts` + `createMediaBuy` + `updateMediaBuy` + `getMediaBuyDelivery` + `getMediaBuys`  |
-| `sales-guaranteed`                 | `hello_seller_adapter_guaranteed.ts`              | as-is — covers the HITL flow                                                                                                                   |
-| `sales-broadcast-tv`               | `hello_seller_adapter_guaranteed.ts`              | replace `audience_targeting` with broadcast-DMA targeting; replace `Product.channels` with `linear_tv`                                         |
-| `sales-streaming-tv`               | `hello_seller_adapter_guaranteed.ts`              | adjust `Product.channels` to `ctv`                                                                                                             |
-| `sales-social`                     | `hello_seller_adapter_social.ts`                  | as-is                                                                                                                                          |
-| `sales-catalog-driven`             | `hello_seller_adapter_social.ts`                  | promote `syncCatalogs` to a real catalog ingestion + `getProducts` reads from the catalog                                                      |
-| `audience-sync`                    | `hello_seller_adapter_social.ts`                  | strip everything except `syncAudiences` + `pollAudienceStatuses`; this is the standalone audience-sync seller pattern                          |
+| If you're claiming…                                              | Fork                                   | Then…                                                                                                                                                                                                                     |
+| ---------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `signal-marketplace` / `signal-owned`                            | `hello_signals_adapter_marketplace.ts` | as-is for marketplace; `signal-owned` adopters drop the marketplace-specific tax/rev-share fields                                                                                                                         |
+| `creative-template`                                              | `hello_creative_adapter_template.ts`   | as-is — single-tenant; production adopters add per-tenant workspace binding (see SWAP markers)                                                                                                                            |
+| `creative-generative`                                            | `hello_creative_adapter_template.ts`   | replace template-driven `buildCreative` with brief-driven generation; keep the `previewCreative` shape                                                                                                                    |
+| `creative-ad-server`                                             | `hello_creative_adapter_ad_server.ts`  | as-is — covers the stateful library + tag generation + macro substitution + delivery reporting flow                                                                                                                       |
+| `sales-non-guaranteed`                                           | `hello_seller_adapter_non_guaranteed.ts` | as-is — covers sync confirmation, floor pricing, spend-only forecast, pacing propagation                                                                                                                                  |
+| `sales-guaranteed`                                               | `hello_seller_adapter_guaranteed.ts`   | as-is — covers the HITL flow                                                                                                                                                                                              |
+| `sales-broadcast-tv`                                             | `hello_seller_adapter_guaranteed.ts`   | replace `audience_targeting` with broadcast-DMA targeting; replace `Product.channels` with `linear_tv`                                                                                                                    |
+| `sales-streaming-tv`                                             | `hello_seller_adapter_guaranteed.ts`   | adjust `Product.channels` to `ctv`                                                                                                                                                                                        |
+| `sales-social`                                                   | `hello_seller_adapter_social.ts`       | as-is                                                                                                                                                                                                                     |
+| `sales-catalog-driven`                                           | `hello_seller_adapter_social.ts`       | promote `syncCatalogs` to a real catalog ingestion + `getProducts` reads from the catalog                                                                                                                                 |
+| `audience-sync`                                                  | `hello_seller_adapter_social.ts`       | strip everything except `syncAudiences` + `pollAudienceStatuses`; this is the standalone audience-sync seller pattern                                                                                                     |
 | `governance-spend-authority` / `property-lists` / `brand-rights` | `hello_seller_adapter_multi_tenant.ts` | as-is — multi-specialism + multi-tenant agency / holdco shape; closes adcp-client#1332 (governance) and adcp-client#1334 (brand-rights). Single-specialism adopters fork the relevant handler block out of the same file. |
 
 Naming convention: `hello_<role>_adapter_<specialism>.ts` where `<role>` is the AdCP protocol layer (`seller` for `media-buy`, `creative` for `creative`, `signals` for `signals`, `governance` for `governance`, `brand` for `brand`). `<specialism>` strips the role-implied prefix (so `creative-template` → `_template`, `sales-guaranteed` → `_guaranteed`). The multi-tenant holdco adapter sits outside this convention because it spans multiple roles (governance + brand-rights + property-lists) — naming follows the deployment shape rather than a single role.
 
+## Common multi-specialism bundles
+
+Real platforms typically claim more than one specialism. Claim a specialism only if (a) you implement its required tools **and** (b) you are prepared to receive and service requests for that flow in production. Stub-throw or empty-array implementations are a smell — drop the claim instead.
+
+| Adopter shape                                              | Canonical specialism bundle                                                                  | Skills                                                                                                                                                            |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Retail-media network (Amazon Ads, Walmart Connect, Citrus) | `sales-catalog-driven` + `audience-sync` + `creative-template`                               | [retail-media](../skills/build-retail-media-agent/SKILL.md), [seller](../skills/build-seller-agent/SKILL.md), [creative](../skills/build-creative-agent/SKILL.md) |
+| Hybrid creative platform (Celtra, Bannerflow)              | `creative-template` + `creative-generative`                                                  | [creative](../skills/build-creative-agent/SKILL.md), [generative-seller](../skills/build-generative-seller-agent/SKILL.md)                                        |
+| Walled-garden social network (Meta, Snap, TikTok)          | `sales-social` + `audience-sync`                                                             | [seller](../skills/build-seller-agent/SKILL.md)                                                                                                                   |
+| Premium broadcaster (Paramount, Disney)                    | `sales-broadcast-tv` + `sales-streaming-tv` _(preview)_                                      | [seller](../skills/build-seller-agent/SKILL.md)                                                                                                                   |
+| DSP-side seller (Scope3, Trade Desk)                       | `sales-non-guaranteed` + `signal-marketplace`                                                | [seller](../skills/build-seller-agent/SKILL.md), [signals](../skills/build-signals-agent/SKILL.md)                                                                |
+| Identity provider (LiveRamp, ID5)                          | `signal-owned` + `audience-sync`                                                             | [signals](../skills/build-signals-agent/SKILL.md), [seller](../skills/build-seller-agent/SKILL.md)                                                                |
+| Governance vendor (IAS, DV)                                | `governance-delivery-monitor` + `measurement-verification` _(preview)_ + `content-standards` | [governance](../skills/build-governance-agent/SKILL.md)                                                                                                           |
+
+> Each specialism runs its own compliance storyboard independently — no joint multi-specialism storyboard exists yet. For cross-protocol bundles (e.g. DSP-side seller spans `media-buy` + `signals`), run each protocol's storyboard separately.
+
 ## Examples
 
 ### Basic Usage

package/examples/hello-cluster.ts

@@ -74,55 +74,94 @@ const HEALTH_TIMEOUT_MS = 5_000;
 const SHUTDOWN_GRACE_MS = 3_000;
 const REPO_ROOT = resolvePath(__dirname, '..');
 
+/** Every mock-server exposes auth-free `GET /_debug/traffic` returning a
+ *  JSON object — used as the universal liveness probe across the cluster.
+ *  Matches what the mock-servers ship today; if a future mock drops this
+ *  surface, swap to a specialism-specific lookup path here. */
+const UNIVERSAL_PROBE_PATH = '/_debug/traffic';
+
 const ADAPTERS: AdapterConfig[] = [
   {
     name: 'signals',
     specialism: 'signal-marketplace',
     port: 3001,
     entrypoint: 'examples/hello_signals_adapter_marketplace.ts',
-    upstream: {
-      envVar: 'UPSTREAM_URL',
-      defaultUrl: 'http://127.0.0.1:4150',
-      // /_lookup/operator answers 200 with `{}` when the operator is unknown,
-      // so any HTTP response means the mock-server's listener is up.
-      probePath: '/_lookup/operator?adcp_operator=preflight',
-    },
+    upstream: { envVar: 'UPSTREAM_URL', defaultUrl: 'http://127.0.0.1:4150', probePath: UNIVERSAL_PROBE_PATH },
   },
   {
-    name: 'sales',
-    specialism: 'sales-non-guaranteed',
+    name: 'creative-template',
+    specialism: 'creative-template',
     port: 3002,
-    entrypoint: 'examples/hello_seller_adapter_non_guaranteed.ts',
+    entrypoint: 'examples/hello_creative_adapter_template.ts',
+    upstream: { envVar: 'UPSTREAM_URL', defaultUrl: 'http://127.0.0.1:4250', probePath: UNIVERSAL_PROBE_PATH },
   },
   {
-    name: 'governance',
-    specialism: 'governance-spend-authority',
+    name: 'sales-social',
+    specialism: 'sales-social',
     port: 3003,
-    entrypoint: 'examples/hello_governance_adapter_spend_authority.ts',
-    tracking: '#1332',
+    entrypoint: 'examples/hello_seller_adapter_social.ts',
+    upstream: { envVar: 'UPSTREAM_URL', defaultUrl: 'http://127.0.0.1:4350', probePath: UNIVERSAL_PROBE_PATH },
   },
   {
-    name: 'creative',
-    specialism: 'creative-ad-server',
+    name: 'sales-guaranteed',
+    specialism: 'sales-guaranteed',
     port: 3004,
+    entrypoint: 'examples/hello_seller_adapter_guaranteed.ts',
+    upstream: { envVar: 'UPSTREAM_URL', defaultUrl: 'http://127.0.0.1:4450', probePath: UNIVERSAL_PROBE_PATH },
+  },
+  {
+    name: 'sales-non-guaranteed',
+    specialism: 'sales-non-guaranteed',
+    port: 3005,
+    entrypoint: 'examples/hello_seller_adapter_non_guaranteed.ts',
+    upstream: { envVar: 'UPSTREAM_URL', defaultUrl: 'http://127.0.0.1:4451', probePath: UNIVERSAL_PROBE_PATH },
+  },
+  {
+    name: 'creative-ad-server',
+    specialism: 'creative-ad-server',
+    port: 3006,
     entrypoint: 'examples/hello_creative_adapter_ad_server.ts',
-    tracking: '#1333',
+    upstream: { envVar: 'UPSTREAM_URL', defaultUrl: 'http://127.0.0.1:4452', probePath: UNIVERSAL_PROBE_PATH },
+  },
+  {
+    name: 'sponsored-intelligence',
+    specialism: 'sponsored-intelligence',
+    port: 3007,
+    entrypoint: 'examples/hello_si_adapter_brand.ts',
+    upstream: { envVar: 'UPSTREAM_URL', defaultUrl: 'http://127.0.0.1:4504', probePath: UNIVERSAL_PROBE_PATH },
+  },
+  {
+    // The multi-tenant adapter claims governance-spend-authority +
+    // property-lists + brand-rights against in-memory state — no upstream
+    // mock to probe. Useful as the agency / holdco worked example.
+    name: 'multi-tenant',
+    specialism: 'governance-spend-authority+property-lists+brand-rights',
+    port: 3008,
+    entrypoint: 'examples/hello_seller_adapter_multi_tenant.ts',
   },
+  // ─── Pending-tracking entries — auto-skip until the example file lands.
+  // The `pending:` block in the manifest surfaces them so adopters know
+  // what's coming.
   {
-    name: 'brand',
+    name: 'governance',
+    specialism: 'governance-spend-authority',
+    port: 3010,
+    entrypoint: 'examples/hello_governance_adapter_spend_authority.ts',
+    tracking: '#1332',
+  },
+  {
+    name: 'brand-rights',
     specialism: 'brand-rights',
-    port: 3005,
+    port: 3011,
     entrypoint: 'examples/hello_brand_adapter_rights.ts',
     tracking: '#1334',
   },
   {
     // `sales-retail-media` is a preview specialism in 3.0 — claiming it
-    // advertises intent; no storyboard backs it yet. A real retail-media
-    // adapter would also claim `sales-catalog-driven`; the manifest's
-    // single-specialism slot is a forced fit at the hello tier.
+    // advertises intent; no storyboard backs it yet.
     name: 'retail-media',
     specialism: 'sales-retail-media',
-    port: 3006,
+    port: 3012,
     entrypoint: 'examples/hello_seller_adapter_retail_media.ts',
   },
 ];