@adcp/sdk 12.1.1 → 13.0.0-rc.0

package/examples/hello_creative_adapter_template.ts

@@ -41,7 +41,7 @@ import {
   assertNoExampleTlds,
   type DecisioningPlatform,
   type CreativeBuilderPlatform,
-  type BuildCreativeReturn,
+  type LegacyBuildCreativeReturn,
   type AccountStore,
   type Account,
 } from '@adcp/sdk/server';
@@ -55,13 +55,15 @@ import {
   urlRender,
   buildCreativeReturn,
   previewCreative,
-  type Format,
-  type ListCreativeFormatsResponse,
-  type BuildCreativeRequest,
-  type CreativeManifest,
-  type PreviewCreativeRequest,
-  type PreviewCreativeResponse,
 } from '@adcp/sdk';
+import type {
+  Format,
+  ListCreativeFormatsResponse,
+  BuildCreativeRequest,
+  CreativeManifest,
+  PreviewCreativeRequest,
+  PreviewCreativeResponse,
+} from '@adcp/sdk/types';
 import { randomUUID } from 'node:crypto';
 
 const UPSTREAM_URL = process.env['UPSTREAM_URL'] ?? 'http://127.0.0.1:4250';
@@ -410,7 +412,7 @@ class CreativeTemplateAdapter implements DecisioningPlatform<Record<string, neve
   };
 
   creative: CreativeBuilderPlatform<CreativeMeta> = defineCreativeBuilderPlatform<CreativeMeta>({
-    listCreativeFormats: async (_req, ctx): Promise<ListCreativeFormatsResponse> => {
+    listCreativeFormatsLegacy: async (_req, ctx): Promise<ListCreativeFormatsResponse> => {
       // `list_creative_formats` is a no-account tool — `ctx.account` is
       // narrowed to `Account<TCtxMeta> | undefined`. The default
       // listing workspace fallback in `accounts.resolve(undefined)` ensures
@@ -424,7 +426,7 @@ class CreativeTemplateAdapter implements DecisioningPlatform<Record<string, neve
       return { status: 'completed', formats: templates.map(templateToFormat) };
     },
 
-    buildCreative: async (req: BuildCreativeRequest, ctx): Promise<BuildCreativeReturn> => {
+    buildCreativeLegacy: async (req: BuildCreativeRequest, ctx): Promise<LegacyBuildCreativeReturn> => {
       const workspaceId = ctx.account.ctx_metadata.workspace_id;
 
       // Templates the workspace can render. Used to resolve the AdCP
@@ -472,7 +474,7 @@ class CreativeTemplateAdapter implements DecisioningPlatform<Record<string, neve
       return buildCreativeReturn.single(await buildOne(req.target_format_id, 0));
     },
 
-    previewCreative: async (req: PreviewCreativeRequest, ctx): Promise<PreviewCreativeResponse> => {
+    previewCreativeLegacy: async (req: PreviewCreativeRequest, ctx): Promise<PreviewCreativeResponse> => {
       // `preview_creative` is a no-account tool — the wire request schema
       // doesn't carry `account`, so the framework types `ctx.account` as
       // `Account<TCtxMeta> | undefined` per the framework's `NoAccountCtx` narrow.

package/examples/hello_seller_adapter_guaranteed.ts

@@ -71,7 +71,7 @@ import {
   type DecisioningPlatform,
   type SalesCorePlatform,
   type SalesIngestionPlatform,
-  type GetProductsPayload,
+  type GetProductsHandlerResult,
   type GetMediaBuyDeliveryPayload,
   type GetMediaBuysPayload,
   type AccountStore,
@@ -80,9 +80,8 @@ import {
   type SyncAccountsResultRow,
 } from '@adcp/sdk/server';
 import { buildGAMLikeRecipe, type GAMLikeRecipe } from '@adcp/sdk/mock-server';
+import type { CanonicalProduct, GetProductsRequest } from '@adcp/sdk';
 import type {
-  GetProductsRequest,
-  GetProductsResponse,
   CreateMediaBuyRequest,
   CreateMediaBuySuccess,
   UpdateMediaBuyRequest,
@@ -92,15 +91,13 @@ import type {
   GetMediaBuyDeliveryResponse,
 } from '@adcp/sdk/types';
 
-// `Product` isn't re-exported from `@adcp/sdk/types` (#1254 in the rollup);
-// derive the shape from the response array.
-type Product = NonNullable<GetProductsResponse['products']>[number];
 type AdcpPackage = NonNullable<UpdateMediaBuySuccess['affected_packages']>[number];
 
 const UPSTREAM_URL = process.env['UPSTREAM_URL'] ?? 'http://127.0.0.1:4450';
 const UPSTREAM_API_KEY = process.env['UPSTREAM_API_KEY'] ?? 'mock_sales_guaranteed_key_do_not_use_in_prod';
 const PORT = Number(process.env['PORT'] ?? 3004);
 const ADCP_AUTH_TOKEN = process.env['ADCP_AUTH_TOKEN'] ?? 'sk_harness_do_not_use_in_prod';
+const PUBLIC_AGENT_URL = process.env['PUBLIC_AGENT_URL'] ?? `http://127.0.0.1:${PORT}`;
 const DEFAULT_PRICING_OPTION_ID = 'cpm_guaranteed_fixed';
 // Test-kit principal for the `comply_controller_mode_gate` storyboard
 // (adcp#4028). The runner authenticates with this bearer to probe the
@@ -118,7 +115,6 @@ const DEFAULT_PRICING_OPTION_ID = 'cpm_guaranteed_fixed';
 // from a worked example.
 const ADCP_LIVE_MODE_AUTH_TOKEN = 'demo-acme-outdoor-live-v1';
 const LIVE_MODE_PROBE_PRINCIPAL = 'compliance-live-mode-probe' as const;
-const PUBLIC_AGENT_URL = process.env['PUBLIC_AGENT_URL'] ?? `http://127.0.0.1:${PORT}`;
 
 const KNOWN_PUBLISHERS = ['acmeoutdoor.example', 'pinnacle-agency.example', 'premium-sports.example'];
 assertNoExampleTlds(
@@ -447,8 +443,6 @@ interface NetworkMeta {
   [key: string]: unknown;
 }
 
-const FORMAT_AGENT_URL = PUBLIC_AGENT_URL;
-
 /** Project upstream product onto AdCP `Product`. The wire `Product` shape
  *  has many optional fields; we populate only the ones the storyboard
  *  validates plus the bare-minimum required spec fields. Production
@@ -462,9 +456,39 @@ const FORMAT_AGENT_URL = PUBLIC_AGENT_URL;
  *  the `sales_guaranteed` storyboard; the recipe is opt-in carrier the
  *  framework reads only when the buyer goes through proposal-mode.
  */
-function projectProduct(p: UpstreamProduct, publisherDomain: string): Product {
+function canonicalFormatOptions(p: UpstreamProduct): CanonicalProduct['format_options'] {
+  const options = p.format_ids.map(id => {
+    const durationSeconds = id.match(/(?:^|_)(\d+)s(?:_|$)/)?.[1];
+    if (p.channel === 'video' || p.channel === 'ctv') {
+      return {
+        format_option_id: id,
+        format_kind: 'video_hosted' as const,
+        params: durationSeconds ? { duration_ms_exact: Number(durationSeconds) * 1_000 } : {},
+      };
+    }
+    if (p.channel === 'audio') {
+      return {
+        format_option_id: id,
+        format_kind: 'audio_hosted' as const,
+        params: durationSeconds ? { duration_ms_exact: Number(durationSeconds) * 1_000 } : {},
+      };
+    }
+    const dimensions = id.match(/(?:^|_)(\d+)x(\d+)(?:_|$)/);
+    return {
+      format_option_id: id,
+      format_kind: 'image' as const,
+      params: dimensions ? { width: Number(dimensions[1]), height: Number(dimensions[2]) } : {},
+    };
+  });
+  if (options.length === 0) {
+    throw new AdcpError('INVALID_REQUEST', { message: `product ${p.product_id} has no creative formats` });
+  }
+  return [options[0]!, ...options.slice(1)];
+}
+
+function projectProduct(p: UpstreamProduct, publisherDomain: string): CanonicalProduct {
   const recipe = buildGAMLikeRecipe(p);
-  const product: Product = {
+  const product: CanonicalProduct = {
     product_id: p.product_id,
     name: p.name,
     description: `${p.name} — ${p.delivery_type} ${p.channel}`,
@@ -482,7 +506,7 @@ function projectProduct(p: UpstreamProduct, publisherDomain: string): Product {
             ? 'streaming_audio'
             : 'display',
     ],
-    format_ids: p.format_ids.map(id => ({ agent_url: FORMAT_AGENT_URL, id })),
+    format_options: canonicalFormatOptions(p),
     delivery_type: p.delivery_type,
     pricing_options: [
       {
@@ -802,7 +826,7 @@ class SalesGuaranteedAdapter implements DecisioningPlatform<Record<string, never
   // level. See `decisioning.type-checks.ts` for the regression-locked
   // patterns.
   sales: SalesCorePlatform<NetworkMeta> & SalesIngestionPlatform<NetworkMeta> = {
-    getProducts: async (req: GetProductsRequest, ctx): Promise<GetProductsPayload> => {
+    getProducts: async (req: GetProductsRequest, ctx): Promise<GetProductsHandlerResult> => {
       const networkCode = ctx.account.ctx_metadata.network_code;
       const publisherDomain = ctx.account.ctx_metadata.publisher_domain;
       // Storyboard sends buying_mode: 'brief' with a free-text brief —
@@ -819,10 +843,17 @@ class SalesGuaranteedAdapter implements DecisioningPlatform<Record<string, never
       // into `inventoryService` (catalog) + `forecastService.getDeliveryForecast`
       // (per-product forecast). Use the discrete `getForecast` below if
       // your backend can't fold forecast into the catalog response.
-      const briefBudget = (req.filters?.budget_range as { max?: number } | undefined)?.max;
+      const filters = req['filters'] as
+        | {
+            budget_range?: { max?: number };
+            start_date?: string;
+            end_date?: string;
+          }
+        | undefined;
+      const briefBudget = filters?.budget_range?.max;
       const products = await upstream.listProducts(networkCode, {
-        ...(req.filters?.start_date && { flightStart: req.filters.start_date }),
-        ...(req.filters?.end_date && { flightEnd: req.filters.end_date }),
+        ...(filters?.start_date && { flightStart: filters.start_date }),
+        ...(filters?.end_date && { flightEnd: filters.end_date }),
         ...(briefBudget !== undefined && { budget: briefBudget }),
       });
       return {
@@ -1166,15 +1197,9 @@ class SalesGuaranteedAdapter implements DecisioningPlatform<Record<string, never
       const rows: SyncCreativesRow[] = [];
       for (const c of creatives) {
         try {
-          if (!c.format_id) {
-            throw new AdcpError('INVALID_REQUEST', {
-              message: 'format_id required on creative manifest',
-              field: 'format_id',
-            });
-          }
           const created = await upstream.createCreative(networkCode, {
             name: c.name,
-            format_id: c.format_id.id,
+            format_id: c.format_kind,
             advertiser_id: networkCode,
           });
           rows.push({
@@ -1336,6 +1361,10 @@ serve(
       taskRegistry,
       idempotency: idempotencyStore,
       mediaBuyStore,
+      canonicalFormatLegacyResolver: context => {
+        if (context.source !== 'product' || !context.declaration.format_option_id) return undefined;
+        return { agent_url: PUBLIC_AGENT_URL, id: context.declaration.format_option_id };
+      },
       resolveSessionKey: ctx => {
         const acct = ctx.account as Account<NetworkMeta> | undefined;
         return acct?.id ?? 'anonymous';

package/examples/hello_seller_adapter_multi_tenant.ts

@@ -806,7 +806,7 @@ class MultiTenantAdapter implements DecisioningPlatform<Record<string, never>, T
       };
     },
 
-    getRights: async (req: GetRightsRequest, ctx): Promise<GetRightsSuccess> => {
+    getRightsLegacy: async (req: GetRightsRequest, ctx): Promise<GetRightsSuccess> => {
       const tenant = getTenant(ctx);
       const requestedUses = new Set(req.uses);
       const matches = Array.from(tenant.rights.values()).filter(r => {
@@ -833,7 +833,10 @@ class MultiTenantAdapter implements DecisioningPlatform<Record<string, never>, T
       };
     },
 
-    acquireRights: async (req: AcquireRightsRequest, ctx): Promise<AcquireRightsAcquired | AcquireRightsRejected> => {
+    acquireRightsLegacy: async (
+      req: AcquireRightsRequest,
+      ctx
+    ): Promise<AcquireRightsAcquired | AcquireRightsRejected> => {
       const tenant = getTenant(ctx);
       const offering = tenant.rights.get(req.rights_id);
       if (!offering) {
@@ -916,7 +919,7 @@ class MultiTenantAdapter implements DecisioningPlatform<Record<string, never>, T
       };
     },
 
-    updateRights: async (req: UpdateRightsRequest, _ctx): Promise<UpdateRightsSuccess> => {
+    updateRightsLegacy: 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

package/examples/hello_seller_adapter_non_guaranteed.ts

@@ -67,20 +67,18 @@ import {
   type DecisioningPlatform,
   type SalesCorePlatform,
   type SalesIngestionPlatform,
-  type GetProductsPayload,
+  type GetProductsHandlerResult,
   type GetMediaBuyDeliveryPayload,
   type GetMediaBuysPayload,
-  type ListCreativeFormatsPayload,
+  type SalesLegacyListCreativeFormatsPayload,
   type AccountStore,
   type Account,
   type AdcpMediaBuyStatus,
   type SyncCreativesRow,
   type SyncAccountsResultRow,
 } from '@adcp/sdk/server';
-import { FormatAsset } from '@adcp/sdk';
+import { FormatAsset, type CanonicalProduct, type GetProductsRequest } from '@adcp/sdk';
 import type {
-  GetProductsRequest,
-  GetProductsResponse,
   CreateMediaBuyRequest,
   CreateMediaBuySuccess,
   UpdateMediaBuyRequest,
@@ -90,8 +88,6 @@ import type {
   GetMediaBuyDeliveryResponse,
 } from '@adcp/sdk/types';
 
-// `Product` isn't re-exported from `@adcp/sdk/types`; derive from response.
-type Product = NonNullable<GetProductsResponse['products']>[number];
 type AdcpPackage = NonNullable<UpdateMediaBuySuccess['affected_packages']>[number];
 type ViewabilityMetrics = NonNullable<
   GetMediaBuyDeliveryResponse['media_buy_deliveries'][number]['totals']['viewability']
@@ -380,11 +376,41 @@ const toAdcpDateTime = (value: string, fallback: string): string => {
 /** Project upstream product onto AdCP `Product`. Auction-cleared inventory
  *  surfaces `min_cpm` as `floor_price` when buyers request auction pricing,
  *  while unfiltered protocol storyboards still get a fixed CPM option first. */
+function canonicalFormatOptions(p: UpstreamProduct): CanonicalProduct['format_options'] {
+  const options = p.format_ids.map(id => {
+    const durationSeconds = id.match(/(?:^|_)(\d+)s(?:_|$)/)?.[1];
+    if (p.channel === 'video' || p.channel === 'ctv') {
+      return {
+        format_option_id: id,
+        format_kind: 'video_hosted' as const,
+        params: durationSeconds ? { duration_ms_exact: Number(durationSeconds) * 1_000 } : {},
+      };
+    }
+    if (p.channel === 'audio') {
+      return {
+        format_option_id: id,
+        format_kind: 'audio_hosted' as const,
+        params: durationSeconds ? { duration_ms_exact: Number(durationSeconds) * 1_000 } : {},
+      };
+    }
+    const dimensions = id.match(/(?:^|_)(\d+)x(\d+)(?:_|$)/);
+    return {
+      format_option_id: id,
+      format_kind: 'image' as const,
+      params: dimensions ? { width: Number(dimensions[1]), height: Number(dimensions[2]) } : {},
+    };
+  });
+  if (options.length === 0) {
+    throw new AdcpError('INVALID_REQUEST', { message: `product ${p.product_id} has no creative formats` });
+  }
+  return [options[0]!, ...options.slice(1)];
+}
+
 function projectProduct(
   p: UpstreamProduct,
   publisherDomain: string,
   pricingMode: 'fixed' | 'auction' = 'fixed'
-): Product {
+): CanonicalProduct {
   const auctionMidpoint = p.pricing.target_cpm ?? round2(p.pricing.min_cpm * 1.3);
   const pricingOption =
     pricingMode === 'auction'
@@ -421,7 +447,7 @@ function projectProduct(
             ? 'streaming_audio'
             : 'display',
     ],
-    format_ids: p.format_ids.map(id => ({ agent_url: FORMAT_AGENT_URL, id })),
+    format_options: canonicalFormatOptions(p),
     delivery_type: 'non_guaranteed',
     pricing_options: [pricingOption],
     reporting_capabilities: {
@@ -638,20 +664,28 @@ class SalesNonGuaranteedAdapter implements DecisioningPlatform<Record<string, ne
   // all-optional and `RequiredPlatformsFor<'sales-non-guaranteed'>` requires
   // the closed shape on the way out.
   sales: SalesCorePlatform<NetworkMeta> & SalesIngestionPlatform<NetworkMeta> = {
-    getProducts: async (req: GetProductsRequest, ctx): Promise<GetProductsPayload> => {
+    getProducts: async (req: GetProductsRequest, ctx): Promise<GetProductsHandlerResult> => {
       const networkCode = ctx.account.ctx_metadata.network_code;
       const publisherDomain = ctx.account.ctx_metadata.publisher_domain;
       // When the buyer provides structured filters (flight dates, budget),
       // forward them so each product comes back with a per-query forecast.
       // Single upstream round-trip surfaces both the catalog and the
       // forecast curve.
-      const briefBudget = (req.filters?.budget_range as { max?: number } | undefined)?.max;
+      const filters = req['filters'] as
+        | {
+            budget_range?: { max?: number };
+            start_date?: string;
+            end_date?: string;
+            is_fixed_price?: boolean;
+          }
+        | undefined;
+      const briefBudget = filters?.budget_range?.max;
       const products = await upstream.listProducts(networkCode, {
-        ...(req.filters?.start_date && { flightStart: req.filters.start_date }),
-        ...(req.filters?.end_date && { flightEnd: req.filters.end_date }),
+        ...(filters?.start_date && { flightStart: filters.start_date }),
+        ...(filters?.end_date && { flightEnd: filters.end_date }),
         ...(briefBudget !== undefined && { budget: briefBudget }),
       });
-      const pricingMode = req.filters?.is_fixed_price === false ? 'auction' : 'fixed';
+      const pricingMode = filters?.is_fixed_price === false ? 'auction' : 'fixed';
       return {
         products: products.map(p => projectProduct(p, publisherDomain, pricingMode)),
         cache_scope: 'account',
@@ -1023,17 +1057,7 @@ class SalesNonGuaranteedAdapter implements DecisioningPlatform<Record<string, ne
       const advertiserId = networkCode; // SWAP: same collapse caveat as createMediaBuy.
       const out: SyncCreativesRow[] = [];
       for (const c of creatives) {
-        const formatRef = (c as { format_id?: { id?: string } | string }).format_id;
-        const formatId = typeof formatRef === 'string' ? formatRef : formatRef?.id;
-        if (!formatId) {
-          out.push({
-            creative_id: (c as { creative_id?: string }).creative_id ?? 'unknown',
-            action: 'failed',
-            status: 'rejected',
-            errors: [{ code: 'CREATIVE_REJECTED', message: 'format_id is required' }],
-          });
-          continue;
-        }
+        const formatId = c.format_kind;
         try {
           const creativeIdHint = (c as { creative_id?: string }).creative_id;
           const created = await upstream.createCreative(networkCode, {
@@ -1061,7 +1085,7 @@ class SalesNonGuaranteedAdapter implements DecisioningPlatform<Record<string, ne
       return out;
     },
 
-    listCreativeFormats: async (_req, _ctx): Promise<ListCreativeFormatsPayload> => {
+    listCreativeFormatsLegacy: async (_req, _ctx): Promise<SalesLegacyListCreativeFormatsPayload> => {
       // Publisher-owned format catalog. The mock doesn't have a discrete
       // formats endpoint (formats live inline on Product); production sellers
       // typically expose `/v1/formats` separately. SWAP: replace with your
@@ -1153,6 +1177,10 @@ serve(
       taskStore,
       idempotency: idempotencyStore,
       mediaBuyStore,
+      canonicalFormatLegacyResolver: context => {
+        if (context.source !== 'product' || !context.declaration.format_option_id) return undefined;
+        return { agent_url: FORMAT_AGENT_URL, id: context.declaration.format_option_id };
+      },
       resolveSessionKey: ctx => {
         const acct = ctx.account as Account<NetworkMeta> | undefined;
         return acct?.id ?? 'anonymous';

package/examples/hello_seller_adapter_proposal_mode.ts

@@ -51,6 +51,7 @@ import {
   type ProposalManager,
   type SalesCorePlatform,
 } from '@adcp/sdk/server';
+import type { CanonicalProduct, GetProductsRequest } from '@adcp/sdk';
 import { buildGAMLikeRecipe, GAM_LIKE_OVERLAP, type GAMLikeRecipe } from '@adcp/sdk/mock-server';
 import type {
   AccountReference,
@@ -60,16 +61,13 @@ import type {
   GetMediaBuyDeliveryResponse,
   GetMediaBuysRequest,
   GetMediaBuysResponse,
-  GetProductsRequest,
   GetProductsResponse,
   UpdateMediaBuyRequest,
   UpdateMediaBuySuccess,
 } from '@adcp/sdk/types';
 
-// Wire `Product` and `Proposal` aren't directly re-exported from
-// `@adcp/sdk/types` — derive from the response array (same pattern as
-// `hello_seller_adapter_guaranteed.ts`).
-type Product = NonNullable<GetProductsResponse['products']>[number];
+// Proposal remains a generated wire type. Products use the SDK's canonical
+// primary surface; legacy format IDs are projected only at the wire boundary.
 type Proposal = NonNullable<GetProductsResponse['proposals']>[number];
 type Package = CreateMediaBuySuccess['packages'][number];
 
@@ -274,13 +272,38 @@ const accounts: AccountStore<NetworkMeta> = {
 // recipes onto ctx.recipes for sales.createMediaBuy.
 // ---------------------------------------------------------------------------
 
-const FORMAT_AGENT_URL = PUBLIC_AGENT_URL;
+function canonicalFormatOptions(p: UpstreamProduct): CanonicalProduct['format_options'] {
+  const options = p.format_ids.map(id => {
+    const durationSeconds = id.match(/(?:^|_)(\d+)s(?:_|$)/)?.[1];
+    if (p.channel === 'video' || p.channel === 'ctv') {
+      return {
+        format_option_id: id,
+        format_kind: 'video_hosted' as const,
+        params: durationSeconds ? { duration_ms_exact: Number(durationSeconds) * 1_000 } : {},
+      };
+    }
+    if (p.channel === 'audio') {
+      return {
+        format_option_id: id,
+        format_kind: 'audio_hosted' as const,
+        params: durationSeconds ? { duration_ms_exact: Number(durationSeconds) * 1_000 } : {},
+      };
+    }
+    const dimensions = id.match(/(?:^|_)(\d+)x(\d+)(?:_|$)/);
+    return {
+      format_option_id: id,
+      format_kind: 'image' as const,
+      params: dimensions ? { width: Number(dimensions[1]), height: Number(dimensions[2]) } : {},
+    };
+  });
+  if (options.length === 0) {
+    throw new AdcpError('INVALID_REQUEST', { message: `product ${p.product_id} has no creative formats` });
+  }
+  return [options[0]!, ...options.slice(1)];
+}
 
-function projectProduct(p: UpstreamProduct, publisherDomain: string, recipe: GAMLikeRecipe): Product {
-  // The wire `Product` shape doesn't enumerate `implementation_config`
-  // — adapters attach it on the wire and the framework reads it back
-  // via cast in the dispatch helpers. We do the same on the way out.
-  const product: Product = {
+function projectProduct(p: UpstreamProduct, publisherDomain: string, recipe: GAMLikeRecipe): CanonicalProduct {
+  const product: CanonicalProduct = {
     product_id: p.product_id,
     name: p.name,
     description: `${p.name} — ${p.delivery_type} ${p.channel}`,
@@ -294,7 +317,7 @@ function projectProduct(p: UpstreamProduct, publisherDomain: string, recipe: GAM
             ? 'streaming_audio'
             : 'display',
     ],
-    format_ids: p.format_ids.map(id => ({ agent_url: FORMAT_AGENT_URL, id })),
+    format_options: canonicalFormatOptions(p),
     delivery_type: p.delivery_type,
     pricing_options: [
       {
@@ -314,8 +337,7 @@ function projectProduct(p: UpstreamProduct, publisherDomain: string, recipe: GAM
       date_range_support: 'date_range',
     },
   };
-  // Attach the recipe via cast so strict TS doesn't reject the field
-  // that's not in the generated `Product` interface.
+  // implementation_config is an adopter-private recipe carrier.
   (product as { implementation_config?: GAMLikeRecipe }).implementation_config = recipe;
   return product;
 }
@@ -627,6 +649,10 @@ serve(
       stateStore,
       mediaBuyStore,
       proposalStore,
+      canonicalFormatLegacyResolver: context => {
+        if (context.source !== 'product' || !context.declaration.format_option_id) return undefined;
+        return { agent_url: PUBLIC_AGENT_URL, id: context.declaration.format_option_id };
+      },
       resolveSessionKey: ctx => {
         const acct = ctx.account as Account<NetworkMeta> | undefined;
         return acct?.id ?? 'anonymous';

package/examples/hello_seller_adapter_social.ts

@@ -705,12 +705,6 @@ class SalesSocialAdapter implements DecisioningPlatform<Record<string, never>, A
       const rows: SyncCreativesRow[] = [];
       for (const c of creatives) {
         try {
-          if (!c.format_id) {
-            throw new AdcpError('INVALID_REQUEST', {
-              message: 'format_id required on creative manifest',
-              field: 'format_id',
-            });
-          }
           // Project AdCP `CreativeAsset.assets` (the asset map keyed by
           // asset_id) onto the upstream native creative shape. Asset values
           // carry an `asset_type` discriminator; we read the typed sub-shapes
@@ -722,11 +716,12 @@ class SalesSocialAdapter implements DecisioningPlatform<Record<string, never>, A
           const landingPageUrl =
             readUrl(assets['click_url']) ?? readUrl(assets['landing_page']) ?? 'https://example.com';
           const mediaUrl = readUrl(assets['image']) ?? readUrl(assets['video']) ?? 'https://example.com/asset';
+          const upstreamFormatId = c.format_kind === 'native_in_feed' ? 'native_feed' : c.format_kind;
 
           const created = await upstream.createCreative(advertiserId, {
             creative_id: c.creative_id,
             name: c.name,
-            format_id: c.format_id.id,
+            format_id: upstreamFormatId,
             primary_text: primaryText,
             landing_page_url: landingPageUrl,
             media_url: mediaUrl,

package/examples/inspect-card-formats.ts

@@ -29,7 +29,7 @@ async function main() {
 
   // List all formats
   console.log('📋 Fetching all creative formats...');
-  const result = await creativeAgent.listCreativeFormats({});
+  const result = await creativeAgent.listCreativeFormatsLegacy({});
 
   if (!result.success || !result.data) {
     console.error('❌ Failed to fetch formats:', result.error);

package/examples/simple-getting-started.ts

@@ -161,7 +161,7 @@ async function campaignWorkflow() {
 
     // Step 2: Check available creative formats
     console.log('\n2️⃣  Checking creative format options...');
-    const formats = await agent.listCreativeFormats(
+    const formats = await agent.listCreativeFormatsLegacy(
       {
         type: 'video',
       },

package/examples/test-helpers-demo.ts

@@ -180,7 +180,7 @@ async function variousOperations() {
 
     // List creative formats
     console.log('2. Listing creative formats...');
-    const formats = await testAgent.listCreativeFormats({});
+    const formats = await testAgent.listCreativeFormatsLegacy({});
     console.log(`   ${formats.success ? '✅' : '❌'} Formats: ${formats.data.formats?.length || 0}`);
 
     // Create a media buy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "12.1.1",
+  "version": "13.0.0-rc.0",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -568,7 +568,7 @@
     "email": "bugs@adcontextprotocol.org"
   },
   "dependencies": {
-    "@modelcontextprotocol/client": "2.0.0-beta.4",
+    "@modelcontextprotocol/client": "2.0.0-beta.5",
     "@modelcontextprotocol/node": "2.0.0-beta.4",
     "@modelcontextprotocol/server": "2.0.0-beta.4",
     "@types/ws": "^8.18.1",

package/skills/build-decisioning-creative-template/SKILL.md

@@ -104,7 +104,7 @@ class WatermarkPlatform implements DecisioningPlatform<WatermarkConfig, Watermar
 
   creative: CreativeBuilderPlatform<WatermarkMeta> = {
     /** Sync transform — fast operation, return result immediately. */
-    buildCreative: async (req: BuildCreativeRequest): Promise<CreativeManifest> => {
+    buildCreativeLegacy: async (req: BuildCreativeRequest): Promise<CreativeManifest> => {
       // requireAsset throws AdcpError with field path if missing/wrong type.
       // After the call, TS narrows `source` to `ImageAsset` — no cast needed.
       const source = requireAsset(req.creative_manifest, 'source_image', 'image');
@@ -132,7 +132,7 @@ class WatermarkPlatform implements DecisioningPlatform<WatermarkConfig, Watermar
     },
 
     /** Always sync — preview is just a sandbox URL. */
-    previewCreative: async (req: PreviewCreativeRequest): Promise<PreviewCreativeResponse> => {
+    previewCreativeLegacy: async (req: PreviewCreativeRequest): Promise<PreviewCreativeResponse> => {
       // Soft-form helper — preview is best-effort even if source is missing.
       const source = getAsset(req.creative_manifest, 'source_image', 'image');
       const sourceUrl = source?.url ?? '';
@@ -228,17 +228,17 @@ return {
 
 `CreativeBuilderPlatform` has 5 method slots. **For each method-pair you implement EXACTLY ONE — sync OR `*Task`** — `validatePlatform()` will throw at construction if you provide both.
 
-| Slot             | Sync variant                    | HITL `*Task` variant                        | Required?    |
-| ---------------- | ------------------------------- | ------------------------------------------- | ------------ |
-| build creative   | `buildCreative(req, ctx)`       | `buildCreativeTask(taskId, req, ctx)`       | One required |
-| preview creative | `previewCreative(req, ctx)`     | — (always sync)                             | Required     |
-| sync creatives   | `syncCreatives(creatives, ctx)` | `syncCreativesTask(taskId, creatives, ctx)` | One required |
+| Slot             | Sync variant                      | HITL `*Task` variant                        | Required?    |
+| ---------------- | --------------------------------- | ------------------------------------------- | ------------ |
+| build creative   | `buildCreativeLegacy(req, ctx)`   | `buildCreativeTask(taskId, req, ctx)`       | One required |
+| preview creative | `previewCreativeLegacy(req, ctx)` | — (always sync)                             | Required     |
+| sync creatives   | `syncCreatives(creatives, ctx)`   | `syncCreativesTask(taskId, creatives, ctx)` | One required |
 
 ### Sync vs `*Task` — pick by latency, not by preference
 
 | Your operation typically takes...                           | Pick                                                                                          |
 | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| Under ~5 seconds (image manipulation, simple template fill) | **Sync** (`buildCreative`)                                                                    |
+| Under ~5 seconds (image manipulation, simple template fill) | **Sync** (`buildCreativeLegacy`)                                                              |
 | 10-60 seconds (TTS, audio mixing, video transcode)          | **Sync** is fine — buyer awaits in the request                                                |
 | 1-30 minutes (heavy generation, multi-pass rendering)       | **HITL** (`buildCreativeTask`) — buyer immediately gets a `submitted` envelope with `task_id` |
 | Unknown / variable                                          | Pick sync; switch to `*Task` only if observed latency > 30s                                   |
@@ -310,7 +310,7 @@ Both helpers preserve the discriminator narrowing — `script.content` types cor
 Every method either returns its success type OR throws `AdcpError` for structured rejection. Generic thrown errors map to `SERVICE_UNAVAILABLE` with `recovery: 'transient'`.
 
 ```ts
-buildCreative: async req => {
+buildCreativeLegacy: async req => {
   if (!req.format_id?.id?.startsWith('image_')) {
     throw new AdcpError('UNSUPPORTED_FEATURE', {
       recovery: 'terminal',
@@ -352,7 +352,7 @@ The framework consumes `idempotency_key` on every mutating request before dispat
 What you SHOULD do: pass `req.idempotency_key` to your upstream API's idempotency parameter when you call into GAM / Snap / Meta / your internal services. That makes the dedupe story end-to-end — if the AdCP layer dedupes a request, your upstream platform won't double-charge a CPM either.
 
 ```ts
-buildCreative: async req => {
+buildCreativeLegacy: async req => {
   // Framework already deduped for the (idempotency_key, account) pair.
   // Thread the same key into the upstream call so YOUR platform's API
   // also dedupes if the same key arrives twice (defensive).
@@ -489,7 +489,7 @@ For HITL platforms, `server.awaitTask(taskId)` settles the background promise; `
 
 ❌ **Don't use `ctx.runAsync(...)` or `ctx.startTask(...)`.** The async story is dual-method (`xxx` vs `xxxTask`), period.
 
-❌ **Don't define both `buildCreative` and `buildCreativeTask`.** `validatePlatform()` will throw with a clear diagnostic. Pick one.
+❌ **Don't define both `buildCreativeLegacy` and `buildCreativeTask`.** `validatePlatform()` will throw with a clear diagnostic. Pick one.
 
 ❌ **Don't return error envelopes manually.** Throw `AdcpError`; the framework projects to the wire shape.