@adcp/sdk 12.1.0 → 13.0.0-rc.0

package/dist/lib/v2/projection/aao-reference-formats.json

@@ -5241,5 +5241,497 @@
     "canonical": {
       "kind": "agent_placement"
     }
+  },
+  {
+    "format_id": {
+      "agent_url": "https://creative.adcontextprotocol.org/",
+      "id": "display_320x50_html"
+    },
+    "name": "Mobile Leaderboard - HTML5",
+    "description": "320x50 HTML5 creative",
+    "type": "display",
+    "renders": [
+      {
+        "dimensions": {
+          "height": 50,
+          "responsive": {
+            "height": false,
+            "width": false
+          },
+          "width": 320
+        },
+        "role": "primary"
+      }
+    ],
+    "assets": [
+      {
+        "item_type": "individual",
+        "asset_id": "html_creative",
+        "required": true,
+        "asset_type": "html",
+        "requirements": {
+          "sandbox": "none",
+          "width": 320,
+          "height": 50,
+          "max_file_size_mb": 0.5,
+          "description": "HTML5 creative code"
+        }
+      },
+      {
+        "item_type": "individual",
+        "asset_id": "impression_tracker",
+        "required": false,
+        "asset_type": "pixel_tracker",
+        "requirements": {
+          "description": "3rd party impression tracking pixel URL"
+        },
+        "event": "impression",
+        "method": "img"
+      },
+      {
+        "item_type": "individual",
+        "asset_id": "viewability_tracker",
+        "required": false,
+        "asset_type": "pixel_tracker",
+        "event": "viewable_mrc_50",
+        "method": "img",
+        "requirements": {
+          "description": "MRC 50% viewable tracker pixel (1-second viewability for display, 2-seconds with audio for video). Optional — measurement vendor URLs the seller's renderer fires when the viewable threshold is met."
+        }
+      },
+      {
+        "item_type": "individual",
+        "asset_id": "click_tracker",
+        "required": false,
+        "asset_type": "pixel_tracker",
+        "event": "click",
+        "method": "img",
+        "requirements": {
+          "description": "Click measurement tracker pixel (distinct from landing_page_url, the destination). Optional — measurement vendor URL fired when the user clicks the creative, in addition to navigating to landing_page_url."
+        }
+      }
+    ],
+    "supported_macros": [
+      "MEDIA_BUY_ID",
+      "CREATIVE_ID",
+      "CACHEBUSTER",
+      "CLICK_URL",
+      "DEVICE_TYPE",
+      "GDPR",
+      "GDPR_CONSENT",
+      "US_PRIVACY",
+      "GPP_STRING"
+    ],
+    "assets_required": [
+      {
+        "asset_id": "html_creative",
+        "item_type": "individual",
+        "required": true,
+        "asset_type": "html",
+        "requirements": {
+          "sandbox": "none",
+          "width": 320,
+          "height": 50,
+          "max_file_size_mb": 0.5,
+          "description": "HTML5 creative code"
+        }
+      }
+    ],
+    "canonical": {
+      "kind": "html5"
+    }
+  },
+  {
+    "format_id": {
+      "agent_url": "https://creative.adcontextprotocol.org/",
+      "id": "display_300x50_html"
+    },
+    "name": "Mobile Banner - HTML5",
+    "description": "300x50 HTML5 creative",
+    "type": "display",
+    "renders": [
+      {
+        "dimensions": {
+          "height": 50,
+          "responsive": {
+            "height": false,
+            "width": false
+          },
+          "width": 300
+        },
+        "role": "primary"
+      }
+    ],
+    "assets": [
+      {
+        "item_type": "individual",
+        "asset_id": "html_creative",
+        "required": true,
+        "asset_type": "html",
+        "requirements": {
+          "sandbox": "none",
+          "width": 300,
+          "height": 50,
+          "max_file_size_mb": 0.5,
+          "description": "HTML5 creative code"
+        }
+      },
+      {
+        "item_type": "individual",
+        "asset_id": "impression_tracker",
+        "required": false,
+        "asset_type": "pixel_tracker",
+        "requirements": {
+          "description": "3rd party impression tracking pixel URL"
+        },
+        "event": "impression",
+        "method": "img"
+      },
+      {
+        "item_type": "individual",
+        "asset_id": "viewability_tracker",
+        "required": false,
+        "asset_type": "pixel_tracker",
+        "event": "viewable_mrc_50",
+        "method": "img",
+        "requirements": {
+          "description": "MRC 50% viewable tracker pixel (1-second viewability for display, 2-seconds with audio for video). Optional — measurement vendor URLs the seller's renderer fires when the viewable threshold is met."
+        }
+      },
+      {
+        "item_type": "individual",
+        "asset_id": "click_tracker",
+        "required": false,
+        "asset_type": "pixel_tracker",
+        "event": "click",
+        "method": "img",
+        "requirements": {
+          "description": "Click measurement tracker pixel (distinct from landing_page_url, the destination). Optional — measurement vendor URL fired when the user clicks the creative, in addition to navigating to landing_page_url."
+        }
+      }
+    ],
+    "supported_macros": [
+      "MEDIA_BUY_ID",
+      "CREATIVE_ID",
+      "CACHEBUSTER",
+      "CLICK_URL",
+      "DEVICE_TYPE",
+      "GDPR",
+      "GDPR_CONSENT",
+      "US_PRIVACY",
+      "GPP_STRING"
+    ],
+    "assets_required": [
+      {
+        "asset_id": "html_creative",
+        "item_type": "individual",
+        "required": true,
+        "asset_type": "html",
+        "requirements": {
+          "sandbox": "none",
+          "width": 300,
+          "height": 50,
+          "max_file_size_mb": 0.5,
+          "description": "HTML5 creative code"
+        }
+      }
+    ],
+    "canonical": {
+      "kind": "html5"
+    }
+  },
+  {
+    "format_id": {
+      "agent_url": "https://creative.adcontextprotocol.org/",
+      "id": "display_static"
+    },
+    "name": "Static Display",
+    "description": "Legacy static image display format (supports any dimensions)",
+    "type": "display",
+    "accepts_parameters": [
+      "dimensions"
+    ],
+    "assets": [
+      {
+        "item_type": "individual",
+        "asset_id": "banner_image",
+        "required": true,
+        "asset_type": "image",
+        "requirements": {
+          "containers": [
+            "jpg",
+            "png",
+            "gif",
+            "webp"
+          ]
+        }
+      },
+      {
+        "item_type": "individual",
+        "asset_id": "click_url",
+        "required": true,
+        "asset_type": "url",
+        "requirements": {
+          "url_type": "clickthrough",
+          "description": "Clickthrough destination URL"
+        }
+      },
+      {
+        "item_type": "individual",
+        "asset_id": "impression_tracker",
+        "required": false,
+        "asset_type": "pixel_tracker",
+        "requirements": {
+          "description": "3rd party impression tracking pixel URL"
+        },
+        "event": "impression",
+        "method": "img"
+      },
+      {
+        "item_type": "individual",
+        "asset_id": "viewability_tracker",
+        "required": false,
+        "asset_type": "pixel_tracker",
+        "event": "viewable_mrc_50",
+        "method": "img",
+        "requirements": {
+          "description": "MRC 50% viewable tracker pixel (1-second viewability for display, 2-seconds with audio for video). Optional — measurement vendor URLs the seller's renderer fires when the viewable threshold is met."
+        }
+      },
+      {
+        "item_type": "individual",
+        "asset_id": "click_tracker",
+        "required": false,
+        "asset_type": "pixel_tracker",
+        "event": "click",
+        "method": "img",
+        "requirements": {
+          "description": "Click measurement tracker pixel (distinct from landing_page_url, the destination). Optional — measurement vendor URL fired when the user clicks the creative, in addition to navigating to landing_page_url."
+        }
+      }
+    ],
+    "supported_macros": [
+      "MEDIA_BUY_ID",
+      "CREATIVE_ID",
+      "CACHEBUSTER",
+      "CLICK_URL",
+      "DEVICE_TYPE",
+      "GDPR",
+      "GDPR_CONSENT",
+      "US_PRIVACY",
+      "GPP_STRING"
+    ],
+    "assets_required": [
+      {
+        "asset_id": "banner_image",
+        "item_type": "individual",
+        "required": true,
+        "asset_type": "image",
+        "requirements": {
+          "containers": [
+            "jpg",
+            "png",
+            "gif",
+            "webp"
+          ]
+        }
+      },
+      {
+        "asset_id": "click_url",
+        "item_type": "individual",
+        "required": true,
+        "asset_type": "url",
+        "requirements": {
+          "url_type": "clickthrough",
+          "description": "Clickthrough destination URL"
+        }
+      }
+    ],
+    "canonical": {
+      "kind": "image"
+    }
+  },
+  {
+    "format_id": {
+      "agent_url": "https://creative.adcontextprotocol.org/",
+      "id": "video_hosted"
+    },
+    "name": "Hosted Video",
+    "description": "Legacy hosted video format (supports any duration)",
+    "type": "video",
+    "accepts_parameters": [
+      "duration"
+    ],
+    "assets": [
+      {
+        "item_type": "individual",
+        "asset_id": "video_file",
+        "required": true,
+        "asset_type": "video",
+        "requirements": {
+          "containers": [
+            "mp4",
+            "mov",
+            "webm"
+          ]
+        }
+      },
+      {
+        "item_type": "individual",
+        "asset_id": "impression_tracker",
+        "required": false,
+        "asset_type": "pixel_tracker",
+        "requirements": {
+          "description": "3rd party impression tracking pixel URL"
+        },
+        "event": "impression",
+        "method": "img"
+      },
+      {
+        "item_type": "individual",
+        "asset_id": "viewability_tracker",
+        "required": false,
+        "asset_type": "pixel_tracker",
+        "event": "viewable_mrc_50",
+        "method": "img",
+        "requirements": {
+          "description": "MRC 50% viewable tracker pixel (1-second viewability for display, 2-seconds with audio for video). Optional — measurement vendor URLs the seller's renderer fires when the viewable threshold is met."
+        }
+      },
+      {
+        "item_type": "individual",
+        "asset_id": "click_tracker",
+        "required": false,
+        "asset_type": "pixel_tracker",
+        "event": "click",
+        "method": "img",
+        "requirements": {
+          "description": "Click measurement tracker pixel (distinct from landing_page_url, the destination). Optional — measurement vendor URL fired when the user clicks the creative, in addition to navigating to landing_page_url."
+        }
+      }
+    ],
+    "supported_macros": [
+      "MEDIA_BUY_ID",
+      "CREATIVE_ID",
+      "CACHEBUSTER",
+      "CLICK_URL",
+      "DEVICE_TYPE",
+      "GDPR",
+      "GDPR_CONSENT",
+      "US_PRIVACY",
+      "GPP_STRING",
+      "VIDEO_ID",
+      "POD_POSITION",
+      "CONTENT_GENRE"
+    ],
+    "assets_required": [
+      {
+        "asset_id": "video_file",
+        "item_type": "individual",
+        "required": true,
+        "asset_type": "video",
+        "requirements": {
+          "containers": [
+            "mp4",
+            "mov",
+            "webm"
+          ]
+        }
+      }
+    ],
+    "canonical": {
+      "kind": "video_hosted"
+    }
+  },
+  {
+    "format_id": {
+      "agent_url": "https://creative.adcontextprotocol.org/",
+      "id": "audio_30s"
+    },
+    "name": "Hosted Audio - 30 seconds",
+    "description": "Legacy 30-second hosted audio format",
+    "type": "audio",
+    "assets": [
+      {
+        "item_type": "individual",
+        "asset_id": "audio_file",
+        "required": true,
+        "asset_type": "audio",
+        "requirements": {
+          "min_duration_ms": 30000,
+          "max_duration_ms": 30000,
+          "containers": [
+            "mp3",
+            "aac",
+            "m4a"
+          ]
+        }
+      },
+      {
+        "item_type": "individual",
+        "asset_id": "impression_tracker",
+        "required": false,
+        "asset_type": "pixel_tracker",
+        "requirements": {
+          "description": "3rd party impression tracking pixel URL"
+        },
+        "event": "impression",
+        "method": "img"
+      },
+      {
+        "item_type": "individual",
+        "asset_id": "viewability_tracker",
+        "required": false,
+        "asset_type": "pixel_tracker",
+        "event": "viewable_mrc_50",
+        "method": "img",
+        "requirements": {
+          "description": "MRC 50% viewable tracker pixel (1-second viewability for display, 2-seconds with audio for video). Optional — measurement vendor URLs the seller's renderer fires when the viewable threshold is met."
+        }
+      },
+      {
+        "item_type": "individual",
+        "asset_id": "click_tracker",
+        "required": false,
+        "asset_type": "pixel_tracker",
+        "event": "click",
+        "method": "img",
+        "requirements": {
+          "description": "Click measurement tracker pixel (distinct from landing_page_url, the destination). Optional — measurement vendor URL fired when the user clicks the creative, in addition to navigating to landing_page_url."
+        }
+      }
+    ],
+    "supported_macros": [
+      "MEDIA_BUY_ID",
+      "CREATIVE_ID",
+      "CACHEBUSTER",
+      "CLICK_URL",
+      "DEVICE_TYPE",
+      "GDPR",
+      "GDPR_CONSENT",
+      "US_PRIVACY",
+      "GPP_STRING",
+      "CONTENT_GENRE"
+    ],
+    "assets_required": [
+      {
+        "asset_id": "audio_file",
+        "item_type": "individual",
+        "required": true,
+        "asset_type": "audio",
+        "requirements": {
+          "min_duration_ms": 30000,
+          "max_duration_ms": 30000,
+          "containers": [
+            "mp3",
+            "aac",
+            "m4a"
+          ]
+        }
+      }
+    ],
+    "canonical": {
+      "kind": "audio_hosted"
+    }
   }
 ]

package/dist/lib/v2/projection/augment-response.d.mts

@@ -20,6 +20,20 @@
  * `toCanonicalOnlyProduct` / `toCanonicalOnlyResponse`.
  */
 import type { V1Product, V2ProductFormatDeclaration, ProjectionDiagnostic } from './types.mjs';
+import type { V1ToV2ProjectionOptions } from './v1-to-v2.mjs';
+import type { CanonicalFormatDeclaration } from './legacy-metadata.mjs';
+/** Protocol Error shape used for portable response-level projection advisories. */
+export interface CanonicalProjectionError {
+    code: ProjectionDiagnostic['code'];
+    message: string;
+    field: string;
+    recovery: 'correctable';
+    source: 'sdk';
+    sdk_id: string;
+    details: ProjectionDiagnostic['error']['details'];
+}
+/** Flatten the projector's internal diagnostic into the protocol `Error` shape. */
+export declare function projectionDiagnosticToError(diagnostic: ProjectionDiagnostic): CanonicalProjectionError;
 /**
  * A Product that has been augmented with `format_options[]` while
  * preserving the original `format_ids[]`. Carries the projection
@@ -52,7 +66,7 @@ export type V2AugmentedProduct<P> = P & {
  * @see toCanonicalOnlyProduct — the canonical-only counterpart that DROPS
  * `format_ids[]` for a fully-migrated consumer.
  */
-export declare function augmentProductWithFormatOptions<P extends V1Product>(product: P): {
+export declare function augmentProductWithFormatOptions<P extends V1Product>(product: P, options?: V1ToV2ProjectionOptions): {
     product: V2AugmentedProduct<P>;
     diagnostics: ProjectionDiagnostic[];
 };
@@ -72,7 +86,7 @@ export declare function augmentProductWithFormatOptions<P extends V1Product>(pro
  */
 export declare function withFormatOptions<R extends {
     products?: V1Product[];
-}>(response: R): {
+}>(response: R, options?: V1ToV2ProjectionOptions): {
     response: R & {
         products: V2AugmentedProduct<V1Product>[];
     };
@@ -86,7 +100,8 @@ export declare function withFormatOptions<R extends {
  * silently bypass the canonical model.
  */
 export type CanonicalOnlyProduct<P> = Omit<P, 'format_ids'> & {
-    format_options: V2ProductFormatDeclaration[];
+    format_ids?: never;
+    format_options: CanonicalFormatDeclaration[];
 };
 /**
  * Project a single Product to the canonical-only shape: `format_options[]`
@@ -101,9 +116,9 @@ export type CanonicalOnlyProduct<P> = Omit<P, 'format_ids'> & {
  *     the projection can't map is surfaced as `FORMAT_PROJECTION_FAILED`.
  *   - **v2-native input** (`format_options[]` already present): keeps the
  *     seller's canonical surface and drops the redundant v1 fallback. If a
- *     `format_ids[]` entry exists that no `format_options[].v1_format_ref`
- *     covers, it surfaces as `LEGACY_FORMAT_ID_DROPPED_UNMAPPED` — the gap
- *     the projection path can't see.
+ *     legacy routing entry exists that no canonical option covers, it
+ *     surfaces a canonical-safe `LEGACY_FORMAT_ID_DROPPED_UNMAPPED`
+ *     diagnostic without echoing the routing identifier.
  *   - **neither shape**: returns `format_options: []`; there is nothing to
  *     project and nothing to lose.
  *
@@ -113,7 +128,7 @@ export type CanonicalOnlyProduct<P> = Omit<P, 'format_ids'> & {
  * non-invertibility tracked at adcontextprotocol/adcp#4842 — this is the
  * read-side transparency half.
  */
-export declare function toCanonicalOnlyProduct<P extends V1Product>(product: P): {
+export declare function toCanonicalOnlyProduct<P extends V1Product>(product: P, options?: V1ToV2ProjectionOptions): {
     product: CanonicalOnlyProduct<P>;
     diagnostics: ProjectionDiagnostic[];
 };
@@ -124,15 +139,20 @@ export declare function toCanonicalOnlyProduct<P extends V1Product>(product: P):
  * alongside the response's existing `errors[]`.
  *
  * Response-level counterpart to {@link toCanonicalOnlyProduct}; same
- * never-silently-lose-a-format guarantee, aggregated across products. The
- * canonical-only sibling of {@link withFormatOptions} (which is additive
- * and preserves `format_ids[]`).
+ * fail-closed guarantee, aggregated across products. A wholly unmappable
+ * legacy product cannot be represented as a canonical Product because the
+ * protocol requires `format_options` to contain at least one declaration. It
+ * is therefore omitted from the canonical list and surfaced through the
+ * response's portable `errors[]` plus the SDK convenience diagnostics. A
+ * partially mappable product remains with its mapped options and advisories
+ * for the refs that could not be projected.
  */
 export declare function toCanonicalOnlyResponse<R extends {
     products?: V1Product[];
-}>(response: R): {
+}>(response: R, options?: V1ToV2ProjectionOptions): {
     response: Omit<R, 'products'> & {
         products: CanonicalOnlyProduct<V1Product>[];
+        errors?: unknown[];
     };
     diagnostics: ProjectionDiagnostic[];
 };

package/dist/lib/v2/projection/augment-response.d.ts

@@ -20,6 +20,20 @@
  * `toCanonicalOnlyProduct` / `toCanonicalOnlyResponse`.
  */
 import type { V1Product, V2ProductFormatDeclaration, ProjectionDiagnostic } from './types';
+import type { V1ToV2ProjectionOptions } from './v1-to-v2';
+import type { CanonicalFormatDeclaration } from './legacy-metadata';
+/** Protocol Error shape used for portable response-level projection advisories. */
+export interface CanonicalProjectionError {
+    code: ProjectionDiagnostic['code'];
+    message: string;
+    field: string;
+    recovery: 'correctable';
+    source: 'sdk';
+    sdk_id: string;
+    details: ProjectionDiagnostic['error']['details'];
+}
+/** Flatten the projector's internal diagnostic into the protocol `Error` shape. */
+export declare function projectionDiagnosticToError(diagnostic: ProjectionDiagnostic): CanonicalProjectionError;
 /**
  * A Product that has been augmented with `format_options[]` while
  * preserving the original `format_ids[]`. Carries the projection
@@ -52,7 +66,7 @@ export type V2AugmentedProduct<P> = P & {
  * @see toCanonicalOnlyProduct — the canonical-only counterpart that DROPS
  * `format_ids[]` for a fully-migrated consumer.
  */
-export declare function augmentProductWithFormatOptions<P extends V1Product>(product: P): {
+export declare function augmentProductWithFormatOptions<P extends V1Product>(product: P, options?: V1ToV2ProjectionOptions): {
     product: V2AugmentedProduct<P>;
     diagnostics: ProjectionDiagnostic[];
 };
@@ -72,7 +86,7 @@ export declare function augmentProductWithFormatOptions<P extends V1Product>(pro
  */
 export declare function withFormatOptions<R extends {
     products?: V1Product[];
-}>(response: R): {
+}>(response: R, options?: V1ToV2ProjectionOptions): {
     response: R & {
         products: V2AugmentedProduct<V1Product>[];
     };
@@ -86,7 +100,8 @@ export declare function withFormatOptions<R extends {
  * silently bypass the canonical model.
  */
 export type CanonicalOnlyProduct<P> = Omit<P, 'format_ids'> & {
-    format_options: V2ProductFormatDeclaration[];
+    format_ids?: never;
+    format_options: CanonicalFormatDeclaration[];
 };
 /**
  * Project a single Product to the canonical-only shape: `format_options[]`
@@ -101,9 +116,9 @@ export type CanonicalOnlyProduct<P> = Omit<P, 'format_ids'> & {
  *     the projection can't map is surfaced as `FORMAT_PROJECTION_FAILED`.
  *   - **v2-native input** (`format_options[]` already present): keeps the
  *     seller's canonical surface and drops the redundant v1 fallback. If a
- *     `format_ids[]` entry exists that no `format_options[].v1_format_ref`
- *     covers, it surfaces as `LEGACY_FORMAT_ID_DROPPED_UNMAPPED` — the gap
- *     the projection path can't see.
+ *     legacy routing entry exists that no canonical option covers, it
+ *     surfaces a canonical-safe `LEGACY_FORMAT_ID_DROPPED_UNMAPPED`
+ *     diagnostic without echoing the routing identifier.
  *   - **neither shape**: returns `format_options: []`; there is nothing to
  *     project and nothing to lose.
  *
@@ -113,7 +128,7 @@ export type CanonicalOnlyProduct<P> = Omit<P, 'format_ids'> & {
  * non-invertibility tracked at adcontextprotocol/adcp#4842 — this is the
  * read-side transparency half.
  */
-export declare function toCanonicalOnlyProduct<P extends V1Product>(product: P): {
+export declare function toCanonicalOnlyProduct<P extends V1Product>(product: P, options?: V1ToV2ProjectionOptions): {
     product: CanonicalOnlyProduct<P>;
     diagnostics: ProjectionDiagnostic[];
 };
@@ -124,15 +139,20 @@ export declare function toCanonicalOnlyProduct<P extends V1Product>(product: P):
  * alongside the response's existing `errors[]`.
  *
  * Response-level counterpart to {@link toCanonicalOnlyProduct}; same
- * never-silently-lose-a-format guarantee, aggregated across products. The
- * canonical-only sibling of {@link withFormatOptions} (which is additive
- * and preserves `format_ids[]`).
+ * fail-closed guarantee, aggregated across products. A wholly unmappable
+ * legacy product cannot be represented as a canonical Product because the
+ * protocol requires `format_options` to contain at least one declaration. It
+ * is therefore omitted from the canonical list and surfaced through the
+ * response's portable `errors[]` plus the SDK convenience diagnostics. A
+ * partially mappable product remains with its mapped options and advisories
+ * for the refs that could not be projected.
  */
 export declare function toCanonicalOnlyResponse<R extends {
     products?: V1Product[];
-}>(response: R): {
+}>(response: R, options?: V1ToV2ProjectionOptions): {
     response: Omit<R, 'products'> & {
         products: CanonicalOnlyProduct<V1Product>[];
+        errors?: unknown[];
     };
     diagnostics: ProjectionDiagnostic[];
 };