@adcp/sdk 12.1.0 → 13.0.0-rc.0

package/dist/lib/version.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/lib/version.ts"],"sourcesContent":["// Generated version information\n// This file is auto-generated by sync-version.ts\n\n/**\n * AdCP SDK library version\n */\nexport const LIBRARY_VERSION = '12.1.0';\n\n/**\n * AdCP specification version this library is built for\n */\nexport const ADCP_VERSION = '3.1.5';\n\n/**\n * AdCP major version sent with every request (adcp_major_version field).\n * Sellers validate this against their supported versions and return\n * VERSION_UNSUPPORTED if the version is not in range.\n */\nexport const ADCP_MAJOR_VERSION = 3;\n\n/**\n * AdCP versions this library maintains backward compatibility with.\n *\n * Auto-derived from `ADCP_VERSION` by scripts/sync-version.ts. Do not edit\n * this list by hand; bumping the AdCP pin via `npm run sync-version`\n * extends it.\n */\nexport const COMPATIBLE_ADCP_VERSIONS = [\n  'v2.5',\n  'v2.6',\n  'v3',\n  '3.0.0-beta.1',\n  '3.0-beta.1',\n  '3.0-beta',\n  '3.0.0-beta.3',\n  '3.0-beta.3',\n  '3.0.0',\n  '3.0',\n  '3.0.1',\n  '3.0.2',\n  '3.0.3',\n  '3.0.4',\n  '3.0.5',\n  '3.0.6',\n  '3.0.7',\n  '3.0.8',\n  '3.0.9',\n  '3.0.10',\n  '3.0.11',\n  '3.0.12',\n  '3.1.0',\n  '3.1',\n  '3.1.1',\n  '3.1.2',\n  '3.1.3',\n  '3.1.4',\n  '3.1.5',\n] as const;\n\n/**\n * String literal union of every AdCP version the SDK formally supports.\n *\n * Used by the per-instance `adcpVersion` constructor option to give callers\n * autocomplete in editors. The intersection with `(string & {})` in the\n * config type preserves the escape hatch — any string is still accepted at\n * the type level — while the literal union surfaces canonical values first.\n */\nexport type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];\n\n/**\n * Full version information\n */\nexport const VERSION_INFO = {\n  library: '12.1.0',\n  adcp: '3.1.5',\n  compatibleVersions: COMPATIBLE_ADCP_VERSIONS,\n  generatedAt: '2026-07-25T23:35:53.939Z',\n} as const;\n\n/**\n * Get the AdCP specification version this library is built for\n */\nexport function getAdcpVersion(): string {\n  return ADCP_VERSION;\n}\n\n/**\n * Get the library version\n */\nexport function getLibraryVersion(): string {\n  return LIBRARY_VERSION;\n}\n\n/**\n * Check if this library version is compatible with a given AdCP version\n */\nexport function isCompatibleWith(adcpVersion: string): boolean {\n  return (COMPATIBLE_ADCP_VERSIONS as readonly string[]).includes(adcpVersion);\n}\n\n/**\n * Get all AdCP versions this library is compatible with\n */\nexport function getCompatibleVersions(): readonly string[] {\n  return COMPATIBLE_ADCP_VERSIONS;\n}\n\n/**\n * Extract the major version number from an AdCP version string.\n *\n * Accepts:\n *   - Semver: '3.0.0', '3.0.1', '3.1.0-beta.1' → 3\n *   - Legacy aliases: 'v3' → 3, 'v2.5' / 'v2.6' → 2\n *\n * Returns NaN for unrecognized strings — callers should validate before passing.\n */\nexport function parseAdcpMajorVersion(version: string): number {\n  const trimmed = version.trim();\n  const semverLike = trimmed.startsWith('v') ? trimmed.slice(1) : trimmed;\n  const major = parseInt(semverLike.split('.')[0] ?? '', 10);\n  return Number.isFinite(major) ? major : NaN;\n}\n\n/**\n * Normalize a full-semver AdCP version (`MAJOR.MINOR.PATCH[-prerelease]`) to\n * the release-precision form that AdCP 3.1+ requires on the wire:\n * `MAJOR.MINOR[-prerelease]` — the patch digit is dropped.\n *\n * Per the spec note on `adcp_version`: \"SDKs that read full-semver values\n * from bundle metadata (e.g. `ComplianceIndex.published_version =\n * \"3.1.0-beta.1\"`) MUST normalize to release-precision (`\"3.1-beta.1\"`)\n * before emitting on the wire — meta-field values are NOT valid wire\n * values.\" The wire regex (`^\\d+\\.\\d+(-[a-zA-Z0-9.-]+)?$`) rejects strings\n * with a patch digit.\n *\n * Behavior:\n *   - `\"3.1.0-beta.7\"` → `\"3.1-beta.7\"`\n *   - `\"3.1.0\"`        → `\"3.1\"`\n *   - `\"3.0.12\"`       → `\"3.0\"`\n *   - Already-release-precision input (`\"3.1\"`, `\"3.1-beta.7\"`) passes through\n *   - Legacy aliases (`\"v2.5\"`, `\"v3\"`) pass through unchanged — the wire\n *     regex doesn't accept them anyway; the v2.5 path uses\n *     `adcp_major_version` instead of `adcp_version` for transport.\n *   - Unrecognized strings pass through unchanged so callers can detect drift\n *     via the wire validator rather than have it masked by this helper.\n */\nexport function toReleasePrecisionVersion(version: string): string {\n  const trimmed = version.trim();\n  // Pre-release form `MAJOR.MINOR.PATCH-prerelease` → `MAJOR.MINOR-prerelease`\n  const semverMatch = trimmed.match(/^(\\d+)\\.(\\d+)\\.\\d+(-[A-Za-z0-9.-]+)?$/);\n  if (semverMatch) {\n    const [, major, minor, pre = ''] = semverMatch;\n    return `${major}.${minor}${pre}`;\n  }\n  // Already release-precision (no patch digit). Includes `3.1`, `3.1-beta.7`.\n  if (/^\\d+\\.\\d+(-[A-Za-z0-9.-]+)?$/.test(trimmed)) return trimmed;\n  // Legacy aliases (`v3`, `v2.5`, `v2.6`) and anything we don't recognize —\n  // pass through so the wire validator can flag genuine drift.\n  return version;\n}\n"],"mappings":"AAMO,MAAM,kBAAkB;AAKxB,MAAM,eAAe;AAOrB,MAAM,qBAAqB;AAS3B,MAAM,2BAA2B;AAAA,EACtC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAeO,MAAM,eAAe;AAAA,EAC1B,SAAS;AAAA,EACT,MAAM;AAAA,EACN,oBAAoB;AAAA,EACpB,aAAa;AACf;AAKO,SAAS,iBAAyB;AACvC,SAAO;AACT;AAKO,SAAS,oBAA4B;AAC1C,SAAO;AACT;AAKO,SAAS,iBAAiB,aAA8B;AAC7D,SAAQ,yBAA+C,SAAS,WAAW;AAC7E;AAKO,SAAS,wBAA2C;AACzD,SAAO;AACT;AAWO,SAAS,sBAAsB,SAAyB;AAC7D,QAAM,UAAU,QAAQ,KAAK;AAC7B,QAAM,aAAa,QAAQ,WAAW,GAAG,IAAI,QAAQ,MAAM,CAAC,IAAI;AAChE,QAAM,QAAQ,SAAS,WAAW,MAAM,GAAG,EAAE,CAAC,KAAK,IAAI,EAAE;AACzD,SAAO,OAAO,SAAS,KAAK,IAAI,QAAQ;AAC1C;AAyBO,SAAS,0BAA0B,SAAyB;AACjE,QAAM,UAAU,QAAQ,KAAK;AAE7B,QAAM,cAAc,QAAQ,MAAM,uCAAuC;AACzE,MAAI,aAAa;AACf,UAAM,CAAC,EAAE,OAAO,OAAO,MAAM,EAAE,IAAI;AACnC,WAAO,GAAG,KAAK,IAAI,KAAK,GAAG,GAAG;AAAA,EAChC;AAEA,MAAI,+BAA+B,KAAK,OAAO,EAAG,QAAO;AAGzD,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../../src/lib/version.ts"],"sourcesContent":["// Generated version information\n// This file is auto-generated by sync-version.ts\n\n/**\n * AdCP SDK library version\n */\nexport const LIBRARY_VERSION = '13.0.0-rc.0';\n\n/**\n * AdCP specification version this library is built for\n */\nexport const ADCP_VERSION = '3.1.5';\n\n/**\n * AdCP major version sent with every request (adcp_major_version field).\n * Sellers validate this against their supported versions and return\n * VERSION_UNSUPPORTED if the version is not in range.\n */\nexport const ADCP_MAJOR_VERSION = 3;\n\n/**\n * AdCP versions this library maintains backward compatibility with.\n *\n * Auto-derived from `ADCP_VERSION` by scripts/sync-version.ts. Do not edit\n * this list by hand; bumping the AdCP pin via `npm run sync-version`\n * extends it.\n */\nexport const COMPATIBLE_ADCP_VERSIONS = [\n  'v2.5',\n  'v2.6',\n  'v3',\n  '3.0.0-beta.1',\n  '3.0-beta.1',\n  '3.0-beta',\n  '3.0.0-beta.3',\n  '3.0-beta.3',\n  '3.0.0',\n  '3.0',\n  '3.0.1',\n  '3.0.2',\n  '3.0.3',\n  '3.0.4',\n  '3.0.5',\n  '3.0.6',\n  '3.0.7',\n  '3.0.8',\n  '3.0.9',\n  '3.0.10',\n  '3.0.11',\n  '3.0.12',\n  '3.1.0',\n  '3.1',\n  '3.1.1',\n  '3.1.2',\n  '3.1.3',\n  '3.1.4',\n  '3.1.5',\n] as const;\n\n/**\n * String literal union of every AdCP version the SDK formally supports.\n *\n * Used by the per-instance `adcpVersion` constructor option to give callers\n * autocomplete in editors. The intersection with `(string & {})` in the\n * config type preserves the escape hatch — any string is still accepted at\n * the type level — while the literal union surfaces canonical values first.\n */\nexport type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];\n\n/**\n * Full version information\n */\nexport const VERSION_INFO = {\n  library: '13.0.0-rc.0',\n  adcp: '3.1.5',\n  compatibleVersions: COMPATIBLE_ADCP_VERSIONS,\n  generatedAt: '2026-07-27T16:31:55.282Z',\n} as const;\n\n/**\n * Get the AdCP specification version this library is built for\n */\nexport function getAdcpVersion(): string {\n  return ADCP_VERSION;\n}\n\n/**\n * Get the library version\n */\nexport function getLibraryVersion(): string {\n  return LIBRARY_VERSION;\n}\n\n/**\n * Check if this library version is compatible with a given AdCP version\n */\nexport function isCompatibleWith(adcpVersion: string): boolean {\n  return (COMPATIBLE_ADCP_VERSIONS as readonly string[]).includes(adcpVersion);\n}\n\n/**\n * Get all AdCP versions this library is compatible with\n */\nexport function getCompatibleVersions(): readonly string[] {\n  return COMPATIBLE_ADCP_VERSIONS;\n}\n\n/**\n * Extract the major version number from an AdCP version string.\n *\n * Accepts:\n *   - Semver: '3.0.0', '3.0.1', '3.1.0-beta.1' → 3\n *   - Legacy aliases: 'v3' → 3, 'v2.5' / 'v2.6' → 2\n *\n * Returns NaN for unrecognized strings — callers should validate before passing.\n */\nexport function parseAdcpMajorVersion(version: string): number {\n  const trimmed = version.trim();\n  const semverLike = trimmed.startsWith('v') ? trimmed.slice(1) : trimmed;\n  const major = parseInt(semverLike.split('.')[0] ?? '', 10);\n  return Number.isFinite(major) ? major : NaN;\n}\n\n/**\n * Normalize a full-semver AdCP version (`MAJOR.MINOR.PATCH[-prerelease]`) to\n * the release-precision form that AdCP 3.1+ requires on the wire:\n * `MAJOR.MINOR[-prerelease]` — the patch digit is dropped.\n *\n * Per the spec note on `adcp_version`: \"SDKs that read full-semver values\n * from bundle metadata (e.g. `ComplianceIndex.published_version =\n * \"3.1.0-beta.1\"`) MUST normalize to release-precision (`\"3.1-beta.1\"`)\n * before emitting on the wire — meta-field values are NOT valid wire\n * values.\" The wire regex (`^\\d+\\.\\d+(-[a-zA-Z0-9.-]+)?$`) rejects strings\n * with a patch digit.\n *\n * Behavior:\n *   - `\"3.1.0-beta.7\"` → `\"3.1-beta.7\"`\n *   - `\"3.1.0\"`        → `\"3.1\"`\n *   - `\"3.0.12\"`       → `\"3.0\"`\n *   - Already-release-precision input (`\"3.1\"`, `\"3.1-beta.7\"`) passes through\n *   - Legacy aliases (`\"v2.5\"`, `\"v3\"`) pass through unchanged — the wire\n *     regex doesn't accept them anyway; the v2.5 path uses\n *     `adcp_major_version` instead of `adcp_version` for transport.\n *   - Unrecognized strings pass through unchanged so callers can detect drift\n *     via the wire validator rather than have it masked by this helper.\n */\nexport function toReleasePrecisionVersion(version: string): string {\n  const trimmed = version.trim();\n  // Pre-release form `MAJOR.MINOR.PATCH-prerelease` → `MAJOR.MINOR-prerelease`\n  const semverMatch = trimmed.match(/^(\\d+)\\.(\\d+)\\.\\d+(-[A-Za-z0-9.-]+)?$/);\n  if (semverMatch) {\n    const [, major, minor, pre = ''] = semverMatch;\n    return `${major}.${minor}${pre}`;\n  }\n  // Already release-precision (no patch digit). Includes `3.1`, `3.1-beta.7`.\n  if (/^\\d+\\.\\d+(-[A-Za-z0-9.-]+)?$/.test(trimmed)) return trimmed;\n  // Legacy aliases (`v3`, `v2.5`, `v2.6`) and anything we don't recognize —\n  // pass through so the wire validator can flag genuine drift.\n  return version;\n}\n"],"mappings":"AAMO,MAAM,kBAAkB;AAKxB,MAAM,eAAe;AAOrB,MAAM,qBAAqB;AAS3B,MAAM,2BAA2B;AAAA,EACtC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAeO,MAAM,eAAe;AAAA,EAC1B,SAAS;AAAA,EACT,MAAM;AAAA,EACN,oBAAoB;AAAA,EACpB,aAAa;AACf;AAKO,SAAS,iBAAyB;AACvC,SAAO;AACT;AAKO,SAAS,oBAA4B;AAC1C,SAAO;AACT;AAKO,SAAS,iBAAiB,aAA8B;AAC7D,SAAQ,yBAA+C,SAAS,WAAW;AAC7E;AAKO,SAAS,wBAA2C;AACzD,SAAO;AACT;AAWO,SAAS,sBAAsB,SAAyB;AAC7D,QAAM,UAAU,QAAQ,KAAK;AAC7B,QAAM,aAAa,QAAQ,WAAW,GAAG,IAAI,QAAQ,MAAM,CAAC,IAAI;AAChE,QAAM,QAAQ,SAAS,WAAW,MAAM,GAAG,EAAE,CAAC,KAAK,IAAI,EAAE;AACzD,SAAO,OAAO,SAAS,KAAK,IAAI,QAAQ;AAC1C;AAyBO,SAAS,0BAA0B,SAAyB;AACjE,QAAM,UAAU,QAAQ,KAAK;AAE7B,QAAM,cAAc,QAAQ,MAAM,uCAAuC;AACzE,MAAI,aAAa;AACf,UAAM,CAAC,EAAE,OAAO,OAAO,MAAM,EAAE,IAAI;AACnC,WAAO,GAAG,KAAK,IAAI,KAAK,GAAG,GAAG;AAAA,EAChC;AAEA,MAAI,+BAA+B,KAAK,OAAO,EAAG,QAAO;AAGzD,SAAO;AACT;","names":[]}

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

@@ -686,11 +686,16 @@ For `getProducts`, any response that includes `products` or `unchanged: true` mu
 If you need manual control (e.g., with `createTaskCapableServer`), builders are available:
 
 ```typescript
-import { productsResponse, mediaBuyResponse, deliveryResponse, taskToolResponse } from '@adcp/sdk';
+import {
+  legacyProductsResponse,
+  legacyMediaBuyResponse,
+  legacyDeliveryResponse,
+  taskToolResponse,
+} from '@adcp/sdk';
 // For error envelopes, throw a typed error class — `AuthMissingError`,
 // `PermissionDeniedError`, `RateLimitedError`, etc. — from `@adcp/sdk/server`.
 
-const response = productsResponse({ products, cache_scope: 'public' });
+const response = legacyProductsResponse({ products, cache_scope: 'public' });
 ```
 
 ### Task Statuses (Server-Side Contract)

package/docs/guides/PREVIEW-ASSET-DURABILITY.md

@@ -81,11 +81,15 @@ campaign creative.
 batch preview helpers. That cache stores the result of `preview_creative`; it is
 not a durable asset store and is not shared across pods.
 
+`batchPreviewFormatsLegacy()` is intentionally a migration API for legacy
+named-format catalogs. Canonical product cards are self-contained and should be
+rendered from `product.product_card` without a creative-agent round trip.
+
 Production services that cache preview results should pass a shared
 `PreviewCacheBackend`:
 
 ```ts
-import { batchPreviewFormats, type PreviewCacheBackend } from '@adcp/sdk';
+import { batchPreviewFormatsLegacy, type PreviewCacheBackend } from '@adcp/sdk';
 import type { RedisClientType } from 'redis';
 
 function redisPreviewCache(redis: RedisClientType): PreviewCacheBackend {
@@ -103,7 +107,7 @@ function redisPreviewCache(redis: RedisClientType): PreviewCacheBackend {
   };
 }
 
-const previews = await batchPreviewFormats(formats, creativeAgentClient, {
+const previews = await batchPreviewFormatsLegacy(formats, creativeAgentClient, {
   cacheBackend: redisPreviewCache(redis),
 });
 ```

package/docs/llms.txt

@@ -244,6 +244,7 @@ await client.createMediaBuy({ ...params, ...useIdempotencyKey(key) });
 | Key | Stamped by | Purpose |
 |-----|-----------|---------|
 | `ext.adcp.disable_sandbox` | `adcp storyboard run --no-sandbox` | Hint (value: `true`) to bypass internal sandbox routing and exercise real adapter paths. Seller agents that honor this key serve production-shaped responses regardless of internal sandbox heuristics (env-var fallbacks, brand-domain detection, fixture substitutes). |
+| `ext.adcp.creative_wire` | SDK storyboard/conformance tooling | Transitional 3.1 hint (value: `legacy` or `canonical`) for read requests whose creative dialect is otherwise structurally ambiguous. Application buyer agents do not emit this key; normal SDK methods negotiate from capabilities and payload shape. |
 
 Third-party extensions MUST use a distinct namespace (e.g. `ext.com.example.*`) to avoid collisions with future `ext.adcp.*` keys.
 

package/examples/README.md

@@ -149,7 +149,7 @@ const client = ADCPMultiAgentClient.fromEnv();
 AdCP tools available on `AgentClient`:
 
 - `getProducts()` - Discover advertising products
-- `listCreativeFormats()` - Get supported creative formats
+- `listCreativeFormatsLegacy()` - Inspect the legacy named-format catalog during migration
 - `createMediaBuy()` - Create a media buy
 - `updateMediaBuy()` - Update a media buy
 - `syncCreatives()` - Sync creative assets

package/examples/batch-preview-test.ts

@@ -5,12 +5,12 @@
  *
  * This example demonstrates:
  * 1. Creating mock products/formats with product_card/format_card manifests
- * 2. Using batchPreviewProducts/batchPreviewFormats to render cards
+ * 2. Using batchPreviewProducts/batchPreviewFormatsLegacy to render cards
  * 3. Caching behavior
  */
 
 import { AdCPClient } from '../src/lib/core/AdCPClient';
-import { batchPreviewProducts, batchPreviewFormats, clearPreviewCache } from '../src/lib/utils/preview-utils';
+import { batchPreviewProducts, batchPreviewFormatsLegacy, clearPreviewCache } from '../src/lib/utils/preview-utils';
 import type { Product, Format } from '../src/lib/types/tools.generated';
 
 // Configuration
@@ -217,7 +217,7 @@ async function main() {
     console.log(`📦 Testing with ${testFormats.length} formats...`);
     const startTime = Date.now();
 
-    const formatPreviews = await batchPreviewFormats(testFormats, creativeAgent);
+    const formatPreviews = await batchPreviewFormatsLegacy(testFormats, creativeAgent);
 
     const elapsed = Date.now() - startTime;
     console.log(`✅ Batch preview completed in ${elapsed}ms\n`);

package/examples/conversation-client.ts

@@ -180,7 +180,7 @@ async function advancedHandlersExample() {
 
   try {
     console.log('🎯 Testing advanced input handling...');
-    const result = await agent.listCreativeFormats(
+    const result = await agent.listCreativeFormatsLegacy(
       {
         type: 'video',
       },
@@ -239,7 +239,7 @@ async function conversationHistoryExample() {
     });
 
     // Second request in same conversation
-    await agent.listCreativeFormats(
+    await agent.listCreativeFormatsLegacy(
       {
         type: 'display',
       },

package/examples/debug-preview-response.ts

@@ -22,7 +22,7 @@ async function main() {
   // Simple preview_creative request
   // Note: Using type assertion to bypass strict TypeScript validation
   // The actual creative agent expects plain strings for text assets
-  const response = await creativeAgent.previewCreative({
+  const response = await creativeAgent.previewCreativeLegacy({
     format_id: {
       agent_url: 'https://creative.adcontextprotocol.org/',
       id: 'product_card_standard',

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

@@ -34,11 +34,11 @@ import {
   type SalesCorePlatform,
   type SalesIngestionPlatform,
   type AccountStore,
-  type GetProductsPayload,
+  type GetProductsHandlerResult,
   type SyncCreativesRow,
 } from '@adcp/sdk/server';
+import type { GetProductsRequest } from '@adcp/sdk';
 import type {
-  GetProductsRequest,
   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<GetProductsPayload> => {
+    getProducts: async (req: GetProductsRequest): Promise<GetProductsHandlerResult> => {
       const promotedOffering = (req as { promoted_offering?: string }).promoted_offering ?? '';
       if (/political|cannabis|gambling/i.test(promotedOffering)) {
         throw new AdcpError('POLICY_VIOLATION', {
@@ -135,7 +135,13 @@ export class BroadcastTvSeller implements DecisioningPlatform<BroadcastTvConfig,
             product_id: 'prod_primetime_30s',
             name: 'Primetime 30s — M-F 8-11pm',
             description: 'Local broadcast primetime, :30 spots',
-            format_ids: [{ id: 'video_30s', agent_url: 'https://example.com/broadcast-creative-agent/mcp' }],
+            format_options: [
+              {
+                format_option_id: 'video_30s',
+                format_kind: 'video_hosted',
+                params: { duration_ms_exact: 30_000 },
+              },
+            ],
             delivery_type: 'guaranteed',
             publisher_properties: [{ publisher_domain: 'broadcast.example.com', selection_type: 'all' }],
             reporting_capabilities: DEFAULT_REPORTING_CAPABILITIES,

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

@@ -47,11 +47,11 @@ import {
   type SalesIngestionPlatform,
   type AccountStore,
   type AdcpStructuredError,
-  type GetProductsPayload,
+  type GetProductsHandlerResult,
   type SyncCreativesRow,
 } from '@adcp/sdk/server';
+import type { GetProductsRequest } from '@adcp/sdk';
 import type {
-  GetProductsRequest,
   CreateMediaBuyRequest,
   CreateMediaBuySuccess,
   UpdateMediaBuyRequest,
@@ -146,7 +146,7 @@ function rejectPreflight(errors: AdcpStructuredError[]): never {
   });
 }
 
-const SHARED_GET_PRODUCTS = async (_req: GetProductsRequest): Promise<GetProductsPayload> => ({
+const SHARED_GET_PRODUCTS = async (_req: GetProductsRequest): Promise<GetProductsHandlerResult> => ({
   cache_scope: 'account' as const,
   products: [
     {
@@ -154,7 +154,13 @@ const SHARED_GET_PRODUCTS = async (_req: GetProductsRequest): Promise<GetProduct
       name: 'Premium Video',
       description: 'Pre-roll video on premium inventory',
       delivery_type: 'non_guaranteed',
-      format_ids: [{ id: 'video_15s', agent_url: 'https://example.com/creative-agent/mcp' }],
+      format_options: [
+        {
+          format_option_id: 'video_15s',
+          format_kind: 'video_hosted',
+          params: { duration_ms_exact: 15_000 },
+        },
+      ],
       publisher_properties: [{ publisher_domain: 'publisher.example.com', selection_type: 'all' }],
       pricing_options: [
         {
@@ -176,7 +182,7 @@ const SHARED_GET_PRODUCTS = async (_req: GetProductsRequest): Promise<GetProduct
 const SHARED_SYNC_CREATIVES = async (creatives: CreativeAsset[]): Promise<SyncCreativesRow[]> => {
   return creatives.map(c => {
     const id = (c as { creative_id?: string }).creative_id ?? `cr_${Math.random()}`;
-    const needsReview = (c as { format_id?: { id?: string } }).format_id?.id?.startsWith('video_');
+    const needsReview = c.format_kind === 'video_hosted' || c.format_kind === 'video_vast';
     return {
       creative_id: id,
       action: 'created',
@@ -327,10 +333,11 @@ export function buildHybridServerExample(platform: MockHybridSeller) {
     version: '0.0.1',
     validation: { requests: 'off', responses: 'off' },
     mergeSeam: 'strict',
-    mediaBuy: {
-      // v5 leftover — listCreativeFormats isn't on SalesPlatform v1.0
-      // (deferred to rc.1). Custom handler here fills the gap until then.
-      listCreativeFormats: async () => ({ status: 'completed' as const, formats: [] }),
+    legacyHandlers: {
+      mediaBuy: {
+        // Explicit v5 raw-handler compatibility seam.
+        listCreativeFormats: async () => ({ status: 'completed' as const, formats: [] }),
+      },
     },
   });
 }

package/examples/decisioning-platform-programmatic.ts

@@ -28,11 +28,11 @@ import {
   type SalesCorePlatform,
   type SalesIngestionPlatform,
   type AccountStore,
-  type GetProductsPayload,
+  type GetProductsHandlerResult,
   type SyncCreativesRow,
 } from '@adcp/sdk/server';
+import type { GetProductsRequest } from '@adcp/sdk';
 import type {
-  GetProductsRequest,
   CreateMediaBuyRequest,
   CreateMediaBuySuccess,
   UpdateMediaBuyRequest,
@@ -97,14 +97,20 @@ export class ProgrammaticSeller implements DecisioningPlatform<ProgrammaticConfi
 
   sales: SalesCorePlatform<ProgrammaticMeta> & SalesIngestionPlatform<ProgrammaticMeta> = {
     /** Sync discovery: catalog read; no async ceremony. */
-    getProducts: async (_req: GetProductsRequest): Promise<GetProductsPayload> => ({
+    getProducts: async (_req: GetProductsRequest): Promise<GetProductsHandlerResult> => ({
       cache_scope: 'account' as const,
       products: [
         {
           product_id: 'prod_run_of_network_display',
           name: 'RON Display',
           description: 'Run-of-network display, 300x250 + 728x90',
-          format_ids: [{ id: 'display_300x250', agent_url: 'https://example.com/programmatic-creative-agent/mcp' }],
+          format_options: [
+            {
+              format_option_id: 'display_300x250',
+              format_kind: 'image',
+              params: { width: 300, height: 250 },
+            },
+          ],
           delivery_type: 'non_guaranteed',
           publisher_properties: [{ publisher_domain: 'programmatic.example.com', selection_type: 'all' }],
           reporting_capabilities: { ...DEFAULT_REPORTING_CAPABILITIES, expected_delay_minutes: 60 },
@@ -121,7 +127,13 @@ export class ProgrammaticSeller implements DecisioningPlatform<ProgrammaticConfi
           product_id: 'prod_premium_video_15s',
           name: 'Premium Video 15s',
           description: 'In-stream video on premium publishers',
-          format_ids: [{ id: 'video_15s', agent_url: 'https://example.com/programmatic-creative-agent/mcp' }],
+          format_options: [
+            {
+              format_option_id: 'video_15s',
+              format_kind: 'video_hosted',
+              params: { duration_ms_exact: 15_000 },
+            },
+          ],
           delivery_type: 'non_guaranteed',
           publisher_properties: [{ publisher_domain: 'programmatic.example.com', selection_type: 'all' }],
           reporting_capabilities: { ...DEFAULT_REPORTING_CAPABILITIES, expected_delay_minutes: 60 },
@@ -206,8 +218,7 @@ export class ProgrammaticSeller implements DecisioningPlatform<ProgrammaticConfi
     syncCreatives: async (creatives: CreativeAsset[]): Promise<SyncCreativesRow[]> => {
       return creatives.map(c => {
         const id = (c as { creative_id?: string }).creative_id ?? `cr_${Math.random()}`;
-        const formatId = (c as { format_id?: { id?: string } }).format_id?.id ?? '';
-        const needsReview = formatId.startsWith('video_');
+        const needsReview = c.format_kind === 'video_hosted' || c.format_kind === 'video_vast';
         if (needsReview) {
           // Schedule the pending → approved transition for the demo
           setTimeout(() => {

package/examples/error-compliant-server.ts

@@ -1,8 +1,8 @@
 /**
  * Example: AdCP-Compliant MCP Server
  *
- * Demonstrates building a server using @adcp/sdk response builders
- * for type-safe responses. Run with:
+ * Demonstrates the explicit legacy handler-bag server and its raw response
+ * builders. New servers should use `createAdcpServerFromPlatform` instead.
  *
  *   npx tsx examples/error-compliant-server.ts
  *
@@ -14,10 +14,10 @@
 import {
   createTaskCapableServer,
   adcpError,
-  capabilitiesResponse,
-  productsResponse,
-  mediaBuyResponse,
-  deliveryResponse,
+  legacyCapabilitiesResponse,
+  legacyProductsResponse,
+  legacyMediaBuyResponse,
+  legacyDeliveryResponse,
   serve,
   DEFAULT_REPORTING_CAPABILITIES,
 } from '@adcp/sdk';
@@ -26,7 +26,7 @@ import {
   CreateMediaBuyRequestSchema,
   GetMediaBuyDeliveryRequestSchema,
 } from '@adcp/sdk/schemas';
-import type { Product, ServerPayload } from '@adcp/sdk';
+import type { LegacyProduct, ServerPayload } from '@adcp/sdk';
 import type { GetAdCPCapabilitiesResponse } from '@adcp/sdk/types';
 
 // CreateMediaBuyRequestSchema requires account/brand per spec, but a lenient
@@ -38,17 +38,21 @@ const LenientCreateMediaBuyInput = CreateMediaBuyRequestSchema.extend({
 });
 
 // ---------------------------------------------------------------------------
-// Product catalog — typed as Product[] so the compiler enforces the schema
+// Product catalog for the explicit raw handler-bag example.
 // ---------------------------------------------------------------------------
-const PRODUCTS: Product[] = [
+const PRODUCTS: LegacyProduct[] = [
   {
     product_id: 'prod_display_300x250',
     name: 'Display Banner 300x250',
     description: 'Standard IAB display banner ad unit served across premium news and lifestyle sites.',
     publisher_properties: [{ publisher_domain: 'example-publisher.com', selection_type: 'all' }],
     channels: ['display'],
-    format_ids: [
-      { agent_url: 'https://creatives.adcontextprotocol.org', id: 'display_static', width: 300, height: 250 },
+    format_options: [
+      {
+        format_option_id: 'display-static-300x250',
+        format_kind: 'image',
+        params: { width: 300, height: 250 },
+      },
     ],
     delivery_type: 'non_guaranteed',
     pricing_options: [
@@ -68,7 +72,13 @@ const PRODUCTS: Product[] = [
     description: 'Skippable pre-roll video ads served on premium video content.',
     publisher_properties: [{ publisher_domain: 'example-publisher.com', selection_type: 'all' }],
     channels: ['olv'],
-    format_ids: [{ agent_url: 'https://creatives.adcontextprotocol.org', id: 'video_hosted' }],
+    format_options: [
+      {
+        format_option_id: 'video-hosted-15s',
+        format_kind: 'video_hosted',
+        params: { duration_ms_exact: 15000 },
+      },
+    ],
     delivery_type: 'non_guaranteed',
     pricing_options: [
       {
@@ -130,7 +140,7 @@ function createAgentServer() {
         },
       },
     };
-    return capabilitiesResponse(capabilities);
+    return legacyCapabilitiesResponse(capabilities);
   });
 
   // --- get_products ---
@@ -138,7 +148,7 @@ function createAgentServer() {
     const limited = checkRateLimit();
     if (limited) return limited;
 
-    return productsResponse({ products: PRODUCTS, cache_scope: 'public' });
+    return legacyProductsResponse({ products: PRODUCTS, cache_scope: 'public' });
   });
 
   // --- create_media_buy ---
@@ -197,7 +207,7 @@ function createAgentServer() {
 
       const mediaBuyId = `mb_${Date.now()}`;
 
-      return mediaBuyResponse({
+      return legacyMediaBuyResponse({
         media_buy_id: mediaBuyId,
         packages: (packages ?? []).map((pkg, i) => ({
           package_id: `pkg_${i}_${Date.now()}`,
@@ -221,7 +231,7 @@ function createAgentServer() {
       const now = new Date();
       const yesterday = new Date(now.getTime() - 86400000);
 
-      return deliveryResponse({
+      return legacyDeliveryResponse({
         reporting_period: {
           start: yesterday.toISOString(),
           end: now.toISOString(),

package/examples/generative-creative-demo.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env tsx
 // Demonstrates the new generative creative format support introduced in AdCP v1.7.0
-// This example shows how to use the new format_id and assets structure for both
+// This example shows how to use canonical format_kind and assets for both
 // static and generative creative workflows
 
 import { ADCPMultiAgentClient, imageAsset, textAsset, urlAsset, type SyncCreativesRequest } from '../src/lib';
@@ -24,17 +24,14 @@ async function demonstrateGenerativeCreatives() {
   console.log(`   Protocol: ${agent.config.protocol}\n`);
 
   // Example 1: Traditional static creative with new format
-  console.log('📝 Example 1: Static Creative with new format_id structure\n');
+  console.log('📝 Example 1: Static Creative with canonical format_kind\n');
 
   const staticCreativeRequest: SyncCreativesRequest = {
     creatives: [
       {
         creative_id: `static_banner_${Date.now()}`,
         name: 'Static Display Banner 300x250',
-        format_id: {
-          agent_url: 'https://creative.adcontextprotocol.org',
-          id: 'display_300x250',
-        },
+        format_kind: 'image',
         assets: {
           image: imageAsset({
             url: 'https://example.com/banner-300x250.jpg',
@@ -64,10 +61,7 @@ async function demonstrateGenerativeCreatives() {
       {
         creative_id: `gen_banner_${Date.now()}`,
         name: 'AI-Generated Display Banner',
-        format_id: {
-          agent_url: 'https://creative.adcontextprotocol.org',
-          id: 'display_300x250_generative',
-        },
+        format_kind: 'image',
         assets: {
           brand_context: urlAsset({
             url: 'https://example.com',
@@ -115,10 +109,7 @@ async function demonstrateGenerativeCreatives() {
       {
         creative_id: 'gen_banner_12345', // Existing creative ID from previous sync
         name: 'AI-Generated Display Banner',
-        format_id: {
-          agent_url: 'https://creative.adcontextprotocol.org',
-          id: 'display_300x250_generative',
-        },
+        format_kind: 'image',
         assets: {
           brand_context: urlAsset({
             url: 'https://example.com',
@@ -146,10 +137,7 @@ async function demonstrateGenerativeCreatives() {
       {
         creative_id: 'gen_banner_12345',
         name: 'AI-Generated Display Banner',
-        format_id: {
-          agent_url: 'https://creative.adcontextprotocol.org',
-          id: 'display_300x250_generative',
-        },
+        format_kind: 'image',
         assets: {
           brand_context: urlAsset({
             url: 'https://example.com',
@@ -172,7 +160,7 @@ async function demonstrateGenerativeCreatives() {
 
   console.log('🎉 Demo complete!');
   console.log('\n📚 Key Changes in AdCP v1.7.0:');
-  console.log('   ✓ format_id is now an object with agent_url and id');
+  console.log('   ✓ format_kind identifies the canonical creative format');
   console.log('   ✓ assets is now a flexible object keyed by asset_role');
   console.log('   ✓ New asset types: url and brand_manifest');
   console.log('   ✓ inputs array for defining preview contexts');

package/examples/hello_creative_adapter_ad_server.ts

@@ -67,15 +67,20 @@ import {
   type DecisioningPlatform,
   type SyncCreativesRow,
 } from '@adcp/sdk/server';
-import { FormatAsset, buildCreativeReturn, previewCreative, urlRender } from '@adcp/sdk';
+import {
+  FormatAsset,
+  buildCreativeReturn,
+  previewCreative,
+  urlRender,
+  type CanonicalCreativeAsset,
+  type CanonicalListedCreative,
+} from '@adcp/sdk';
 import type {
   BuildCreativeRequest,
   BuildCreativeSuccess,
-  CreativeAsset,
   GetCreativeDeliveryRequest,
   GetCreativeDeliveryResponse,
   ListCreativeFormatsResponse,
-  ListCreativesResponse,
   PreviewCreativeRequest,
   PreviewCreativeResponse,
 } from '@adcp/sdk/types';
@@ -328,17 +333,26 @@ function projectFormat(f: UpstreamFormat): ListCreativeFormatsResponse['formats'
   };
 }
 
-/** Project upstream creative → AdCP `CreativeAsset`. The list-creatives
- *  response schema requires `creative_id`, `name`, `format_id`, `status`,
- *  `created_date`, `updated_date`. We wrap the upstream snippet as a single
+function canonicalCreativeKind(formatId: string): CanonicalCreativeAsset['format_kind'] {
+  if (/video|vast|ctv/i.test(formatId)) return 'video_hosted';
+  if (/audio|daast/i.test(formatId)) return 'audio_hosted';
+  if (/native|feed|social/i.test(formatId)) return 'native_in_feed';
+  return 'image';
+}
+
+/** Project upstream creative onto the canonical SDK surface. We retain the
+ *  upstream option id as a product-scoped canonical reference so the explicit
+ *  canonical→legacy resolver below can restore the seller-owned format ID for
+ *  a 3.0 or legacy-3.1 buyer. We wrap the upstream snippet as a single
  *  inline html asset so adopters see how `assets` is keyed; production
  *  sellers project the upstream's structured asset graph (image_url,
  *  video_url, click_url, headline, etc.) here. */
-function projectCreative(c: UpstreamCreative): CreativeAsset {
+function projectCreative(c: UpstreamCreative): CanonicalListedCreative {
   return {
     creative_id: c.creative_id,
     name: c.name,
-    format_id: { agent_url: FORMAT_AGENT_URL, id: c.format_id },
+    format_kind: canonicalCreativeKind(c.format_id),
+    format_option_ref: { scope: 'product', format_option_id: c.format_id },
     status: mapCreativeStatus(c.status),
     created_date: c.created_at,
     updated_date: c.updated_at,
@@ -350,12 +364,12 @@ function projectCreative(c: UpstreamCreative): CreativeAsset {
         click_url: { asset_type: 'url', url: c.click_url },
       }),
     },
-    // CAST: schema-pickiness — `CreativeAsset` requires `assets` keys to
+    // CAST: schema-pickiness — the canonical creative requires `assets` keys to
     // satisfy the discriminated `AssetVariant` union. The `html` and `url`
     // variants we emit ARE valid (asset_type: 'html' + content; asset_type:
     // 'url' + url), but TS's structural inference can't prove it through
     // the spread. Adopters who project richer asset graphs can drop the cast.
-  } as unknown as CreativeAsset;
+  } as unknown as CanonicalListedCreative;
 }
 
 function mapCreativeStatus(s: UpstreamCreative['status']): 'approved' | 'pending_review' | 'rejected' {
@@ -466,7 +480,7 @@ class CreativeAdServerAdapter implements DecisioningPlatform<Record<string, neve
      * the creative first (push to upstream) then renders. SWAP for adapters
      * that don't support inline build to throw INVALID_REQUEST instead.
      */
-    buildCreative: async (req: BuildCreativeRequest, ctx): Promise<BuildCreativeSuccess> => {
+    buildCreativeLegacy: async (req: BuildCreativeRequest, ctx): Promise<BuildCreativeSuccess> => {
       const networkCode = ctx.account.ctx_metadata.network_code;
       const creativeId = (req as { creative_id?: string }).creative_id;
       const creativeManifest = (req as { creative_manifest?: { creative_id?: string; assets?: unknown } })
@@ -540,7 +554,7 @@ class CreativeAdServerAdapter implements DecisioningPlatform<Record<string, neve
      * request doesn't carry `account`. Resolver synthesizes a fallback
      * (KNOWN_PUBLISHERS[0]) so we have tenant context.
      */
-    previewCreative: async (req: PreviewCreativeRequest, ctx): Promise<PreviewCreativeResponse> => {
+    previewCreativeLegacy: async (req: PreviewCreativeRequest, ctx): Promise<PreviewCreativeResponse> => {
       // No-account narrow: ctx.account is `Account<NetworkMeta> | undefined`
       // per the type. Defensive guard per migration recipe #11.
       const acct = ctx.account as Account<NetworkMeta> | undefined;
@@ -588,7 +602,7 @@ class CreativeAdServerAdapter implements DecisioningPlatform<Record<string, neve
       };
     },
 
-    listCreativeFormats: async (_req, _ctx): Promise<ListCreativeFormatsResponse> => {
+    listCreativeFormatsLegacy: async (_req, _ctx): Promise<ListCreativeFormatsResponse> => {
       // No-account tool. Use the default workspace's catalog. Production
       // sellers expose a global format catalog or the workspace tied to
       // the API key's principal.
@@ -597,14 +611,14 @@ class CreativeAdServerAdapter implements DecisioningPlatform<Record<string, neve
       return { status: 'completed' as const, formats: upstreamFormats.map(projectFormat) };
     },
 
-    syncCreatives: async (creatives: CreativeAsset[], ctx): Promise<SyncCreativesRow[]> => {
+    syncCreatives: async (creatives: CanonicalCreativeAsset[], ctx): Promise<SyncCreativesRow[]> => {
       const networkCode = ctx.account.ctx_metadata.network_code;
       const advertiserId = ctx.account.id;
       const rows: SyncCreativesRow[] = [];
       for (const c of creatives) {
         const opaque = c as unknown as Record<string, unknown>;
-        const fmtRef = opaque['format_id'] as { id?: string } | string | undefined;
-        const formatId = typeof fmtRef === 'string' ? fmtRef : fmtRef?.id;
+        const optionRef = opaque['format_option_ref'] as { format_option_id?: string } | undefined;
+        const formatId = optionRef?.format_option_id ?? c.format_kind;
         const idempotencyHint =
           typeof opaque['creative_id'] === 'string' ? (opaque['creative_id'] as string) : undefined;
         // Extract upstream-specific fields the AdCP `CreativeAsset` shape
@@ -810,6 +824,13 @@ serve(
           },
         },
       },
+      canonicalFormatLegacyResolver: context => {
+        if (context.source !== 'creative') return undefined;
+        const optionRef = context.creative['format_option_ref'];
+        if (optionRef === null || typeof optionRef !== 'object' || Array.isArray(optionRef)) return undefined;
+        const formatOptionId = (optionRef as { format_option_id?: unknown }).format_option_id;
+        return typeof formatOptionId === 'string' ? { agent_url: FORMAT_AGENT_URL, id: formatOptionId } : undefined;
+      },
     }),
   {
     port: PORT,