@adcp/sdk 13.0.0-rc.0 → 13.0.0-rc.2

package/dist/lib/types/core.generated.d.ts

@@ -16140,132 +16140,7 @@ export type ListCreativesResponse = ProtocolEnvelope & {
     /**
      * Array of creative assets matching the query
      */
-    creatives: {
-        /**
-         * Unique identifier for the creative
-         */
-        creative_id: string;
-        account?: Account;
-        /**
-         * Human-readable creative name
-         */
-        name: string;
-        format_id: FormatReferenceStructuredObject;
-        status: CreativeStatus;
-        /**
-         * When the creative was created
-         * @format date-time
-         */
-        created_date: string;
-        /**
-         * When the creative was last modified
-         * @format date-time
-         */
-        updated_date: string;
-        /**
-         * Assets for this creative, keyed by asset_id. Each slot value is either a single asset object or an array of asset objects (for slots with `min`/`max > 1`). Each asset value carries an `asset_type` discriminator that selects the matching asset schema.
-         */
-        assets?: {
-            /**
-             * This interface was referenced by `undefined`'s JSON-Schema definition
-             * via the `patternProperty` "^[a-z0-9_]+$".
-             */
-            [k: string]: AssetVariant | AssetVariant1[];
-        };
-        /**
-         * User-defined tags for organization and searchability
-         */
-        tags?: string[];
-        /**
-         * Creative concept this creative belongs to. Concepts group related creatives across sizes and formats.
-         */
-        concept_id?: string;
-        /**
-         * Human-readable concept name
-         */
-        concept_name?: string;
-        /**
-         * Dynamic content variables (DCO slots) for this creative. Included when include_variables=true.
-         */
-        variables?: CreativeVariable[];
-        /**
-         * Current package assignments (included when include_assignments=true)
-         */
-        assignments?: {
-            /**
-             * Total number of active package assignments
-             * @minimum 0
-             */
-            assignment_count: number;
-            /**
-             * List of packages this creative is assigned to
-             */
-            assigned_packages?: {
-                /**
-                 * Package identifier
-                 */
-                package_id: string;
-                /**
-                 * When this assignment was created
-                 * @format date-time
-                 */
-                assigned_date: string;
-            }[];
-        };
-        /**
-         * Lightweight delivery snapshot (included when include_snapshot=true). For detailed performance analytics, use get_creative_delivery.
-         */
-        snapshot?: {
-            /**
-             * When this snapshot was captured by the platform
-             * @format date-time
-             */
-            as_of: string;
-            /**
-             * Maximum age of this data in seconds. For example, 3600 means the data may be up to 1 hour old.
-             * @minimum 0
-             */
-            staleness_seconds: number;
-            /**
-             * Lifetime impressions across all assignments. Not scoped to any date range.
-             * @minimum 0
-             */
-            impressions: number;
-            /**
-             * Last time this creative served an impression. Absent when the creative has never served.
-             * @format date-time
-             */
-            last_served?: string;
-        };
-        snapshot_unavailable_reason?: SnapshotUnavailableReason;
-        /**
-         * Items for multi-asset formats like carousels and native ads (included when include_items=true)
-         */
-        items?: CreativeItem[];
-        /**
-         * Pricing options for using this creative (serving, delivery). Used by ad servers and library agents. Transformation agents expose format-level pricing on list_creative_formats instead. Present when include_pricing=true and account provided. The buyer passes the applied pricing_option_id in report_usage.
-         */
-        pricing_options?: VendorPricingOption[];
-        /**
-         * Tombstone block — present only when this record is a soft-purged creative surfaced via `include_purged: true`. The record's `status` field reflects the last status before purge (frozen — buyers MUST treat the creative as gone; assignments, snapshot, and serving operations no longer apply). Tombstones surface for the seller's webhook activity retention window (30 days from `purge.at`). Hard purges (`purge_kind: hard` on the webhook) do not surface on this read — the [`creative.purged`](https://adcontextprotocol.org/schemas/v3/creative/creative-purged-webhook.json) webhook is the only signal.
-         */
-        purge?: {
-            /**
-             * Always `soft` on tombstones — hard purges do not surface on this read.
-             */
-            kind: 'soft';
-            /**
-             * ISO 8601 timestamp when the creative was destroyed. Matches the `purged_at` field on the corresponding `creative.purged` webhook fire.
-             * @format date-time
-             */
-            at: string;
-            reason_code: CreativeEventReasonCode;
-        };
-        /**
-         * Recent webhook fires scoped to this creative — `creative.status_changed` and `creative.purged` deliveries. Present only when the request set `include_webhook_activity: true`. Each item is a `webhook-activity-record`; the `notification_type` field discriminates between status changes and purges. The `ext.creative_id` slot MAY be populated on records nested inside larger reads where the parent does not already key the array; on `list_creatives` the parent creative_id is unambiguous and `ext.creative_id` MAY be omitted. Retention: 30 days from `completed_at` (MUST). See `snapshot-and-log.mdx § Webhook activity log pattern` for the full normative contract.
-         */
-        webhook_activity?: WebhookActivityRecord[];
-    }[];
+    creatives: (LegacyListedCreativeNamedFormatReference | ListedCreativeCanonicalFormatKind)[];
     /**
      * Breakdown of creatives by format. Keys are agent-defined format identifiers, optionally including dimensions (e.g., 'display_static_300x250', 'video_30s_vast'). Key construction is platform-specific — there is no required format.
      */
@@ -16366,6 +16241,133 @@ export type CreativeItem = {
  * Categorical reason for the purge. Matches the value the seller emitted on the corresponding `creative.purged` webhook fire.
  */
 export type CreativeEventReasonCode = 'review_passed' | 'review_failure' | 'processing_failure' | 'seller_rereview' | 'policy_revocation' | 'content_drift' | 'identity_authorization_revoked' | 'identity_authorization_expired' | 'source_private' | 'source_deleted' | 'takedown_request' | 'advertiser_request' | 'seller_archive' | 'account_closed' | 'account_suspended' | 'retention_expired' | 'legal_erasure';
+export interface LegacyListedCreativeNamedFormatReference {
+    /**
+     * Unique identifier for the creative
+     */
+    creative_id: string;
+    account?: Account;
+    /**
+     * Human-readable creative name
+     */
+    name: string;
+    format_id: FormatReferenceStructuredObject;
+    format_option_ref?: FormatOptionReference;
+    status: CreativeStatus;
+    /**
+     * When the creative was created
+     * @format date-time
+     */
+    created_date: string;
+    /**
+     * When the creative was last modified
+     * @format date-time
+     */
+    updated_date: string;
+    /**
+     * Assets for this creative, keyed by asset_id. Each slot value is either a single asset object or an array of asset objects (for slots with `min`/`max > 1`). Each asset value carries an `asset_type` discriminator that selects the matching asset schema.
+     */
+    assets?: {
+        /**
+         * This interface was referenced by `undefined`'s JSON-Schema definition
+         * via the `patternProperty` "^[a-z0-9_]+$".
+         */
+        [k: string]: AssetVariant | AssetVariant1[];
+    };
+    /**
+     * User-defined tags for organization and searchability
+     */
+    tags?: string[];
+    /**
+     * Creative concept this creative belongs to. Concepts group related creatives across sizes and formats.
+     */
+    concept_id?: string;
+    /**
+     * Human-readable concept name
+     */
+    concept_name?: string;
+    /**
+     * Dynamic content variables (DCO slots) for this creative. Included when include_variables=true.
+     */
+    variables?: CreativeVariable[];
+    /**
+     * Current package assignments (included when include_assignments=true)
+     */
+    assignments?: {
+        /**
+         * Total number of active package assignments
+         * @minimum 0
+         */
+        assignment_count: number;
+        /**
+         * List of packages this creative is assigned to
+         */
+        assigned_packages?: {
+            /**
+             * Package identifier
+             */
+            package_id: string;
+            /**
+             * When this assignment was created
+             * @format date-time
+             */
+            assigned_date: string;
+        }[];
+    };
+    /**
+     * Lightweight delivery snapshot (included when include_snapshot=true). For detailed performance analytics, use get_creative_delivery.
+     */
+    snapshot?: {
+        /**
+         * When this snapshot was captured by the platform
+         * @format date-time
+         */
+        as_of: string;
+        /**
+         * Maximum age of this data in seconds. For example, 3600 means the data may be up to 1 hour old.
+         * @minimum 0
+         */
+        staleness_seconds: number;
+        /**
+         * Lifetime impressions across all assignments. Not scoped to any date range.
+         * @minimum 0
+         */
+        impressions: number;
+        /**
+         * Last time this creative served an impression. Absent when the creative has never served.
+         * @format date-time
+         */
+        last_served?: string;
+    };
+    snapshot_unavailable_reason?: SnapshotUnavailableReason;
+    /**
+     * Items for multi-asset formats like carousels and native ads (included when include_items=true)
+     */
+    items?: CreativeItem[];
+    /**
+     * Pricing options for using this creative (serving, delivery). Used by ad servers and library agents. Transformation agents expose format-level pricing on list_creative_formats instead. Present when include_pricing=true and account provided. The buyer passes the applied pricing_option_id in report_usage.
+     */
+    pricing_options?: VendorPricingOption[];
+    /**
+     * Tombstone block — present only when this record is a soft-purged creative surfaced via `include_purged: true`. The record's `status` field reflects the last status before purge (frozen — buyers MUST treat the creative as gone; assignments, snapshot, and serving operations no longer apply). Tombstones surface for the seller's webhook activity retention window (30 days from `purge.at`). Hard purges (`purge_kind: hard` on the webhook) do not surface on this read — the [`creative.purged`](https://adcontextprotocol.org/schemas/v3/creative/creative-purged-webhook.json) webhook is the only signal.
+     */
+    purge?: {
+        /**
+         * Always `soft` on tombstones — hard purges do not surface on this read.
+         */
+        kind: 'soft';
+        /**
+         * ISO 8601 timestamp when the creative was destroyed. Matches the `purged_at` field on the corresponding `creative.purged` webhook fire.
+         * @format date-time
+         */
+        at: string;
+        reason_code: CreativeEventReasonCode;
+    };
+    /**
+     * Recent webhook fires scoped to this creative — `creative.status_changed` and `creative.purged` deliveries. Present only when the request set `include_webhook_activity: true`. Each item is a `webhook-activity-record`; the `notification_type` field discriminates between status changes and purges. The `ext.creative_id` slot MAY be populated on records nested inside larger reads where the parent does not already key the array; on `list_creatives` the parent creative_id is unambiguous and `ext.creative_id` MAY be omitted. Retention: 30 days from `completed_at` (MUST). See `snapshot-and-log.mdx § Webhook activity log pattern` for the full normative contract.
+     */
+    webhook_activity?: WebhookActivityRecord[];
+}
 /**
  * A dynamic content variable (DCO slot) on a creative. Variables represent content that can change at serve time — headlines, images, product data, etc.
  */
@@ -16455,6 +16457,133 @@ export interface WebhookActivityRecord {
     error_message?: string | null;
     ext?: ExtensionObject;
 }
+export interface ListedCreativeCanonicalFormatKind {
+    /**
+     * Unique identifier for the creative
+     */
+    creative_id: string;
+    account?: Account;
+    /**
+     * Human-readable creative name
+     */
+    name: string;
+    format_kind: CanonicalFormatKind;
+    format_option_ref?: FormatOptionReference;
+    status: CreativeStatus;
+    /**
+     * When the creative was created
+     * @format date-time
+     */
+    created_date: string;
+    /**
+     * When the creative was last modified
+     * @format date-time
+     */
+    updated_date: string;
+    /**
+     * Assets for this creative, keyed by asset_id. Each slot value is either a single asset object or an array of asset objects (for slots with `min`/`max > 1`). Each asset value carries an `asset_type` discriminator that selects the matching asset schema.
+     */
+    assets?: {
+        /**
+         * This interface was referenced by `undefined`'s JSON-Schema definition
+         * via the `patternProperty` "^[a-z0-9_]+$".
+         */
+        [k: string]: AssetVariant2 | AssetVariant3[];
+    };
+    /**
+     * User-defined tags for organization and searchability
+     */
+    tags?: string[];
+    /**
+     * Creative concept this creative belongs to. Concepts group related creatives across sizes and formats.
+     */
+    concept_id?: string;
+    /**
+     * Human-readable concept name
+     */
+    concept_name?: string;
+    /**
+     * Dynamic content variables (DCO slots) for this creative. Included when include_variables=true.
+     */
+    variables?: CreativeVariable[];
+    /**
+     * Current package assignments (included when include_assignments=true)
+     */
+    assignments?: {
+        /**
+         * Total number of active package assignments
+         * @minimum 0
+         */
+        assignment_count: number;
+        /**
+         * List of packages this creative is assigned to
+         */
+        assigned_packages?: {
+            /**
+             * Package identifier
+             */
+            package_id: string;
+            /**
+             * When this assignment was created
+             * @format date-time
+             */
+            assigned_date: string;
+        }[];
+    };
+    /**
+     * Lightweight delivery snapshot (included when include_snapshot=true). For detailed performance analytics, use get_creative_delivery.
+     */
+    snapshot?: {
+        /**
+         * When this snapshot was captured by the platform
+         * @format date-time
+         */
+        as_of: string;
+        /**
+         * Maximum age of this data in seconds. For example, 3600 means the data may be up to 1 hour old.
+         * @minimum 0
+         */
+        staleness_seconds: number;
+        /**
+         * Lifetime impressions across all assignments. Not scoped to any date range.
+         * @minimum 0
+         */
+        impressions: number;
+        /**
+         * Last time this creative served an impression. Absent when the creative has never served.
+         * @format date-time
+         */
+        last_served?: string;
+    };
+    snapshot_unavailable_reason?: SnapshotUnavailableReason;
+    /**
+     * Items for multi-asset formats like carousels and native ads (included when include_items=true)
+     */
+    items?: CreativeItem[];
+    /**
+     * Pricing options for using this creative (serving, delivery). Used by ad servers and library agents. Transformation agents expose format-level pricing on list_creative_formats instead. Present when include_pricing=true and account provided. The buyer passes the applied pricing_option_id in report_usage.
+     */
+    pricing_options?: VendorPricingOption[];
+    /**
+     * Tombstone block — present only when this record is a soft-purged creative surfaced via `include_purged: true`. The record's `status` field reflects the last status before purge (frozen — buyers MUST treat the creative as gone; assignments, snapshot, and serving operations no longer apply). Tombstones surface for the seller's webhook activity retention window (30 days from `purge.at`). Hard purges (`purge_kind: hard` on the webhook) do not surface on this read — the [`creative.purged`](https://adcontextprotocol.org/schemas/v3/creative/creative-purged-webhook.json) webhook is the only signal.
+     */
+    purge?: {
+        /**
+         * Always `soft` on tombstones — hard purges do not surface on this read.
+         */
+        kind: 'soft';
+        /**
+         * ISO 8601 timestamp when the creative was destroyed. Matches the `purged_at` field on the corresponding `creative.purged` webhook fire.
+         * @format date-time
+         */
+        at: string;
+        reason_code: CreativeEventReasonCode;
+    };
+    /**
+     * Recent webhook fires scoped to this creative — `creative.status_changed` and `creative.purged` deliveries. Present only when the request set `include_webhook_activity: true`. Each item is a `webhook-activity-record`; the `notification_type` field discriminates between status changes and purges. The `ext.creative_id` slot MAY be populated on records nested inside larger reads where the parent does not already key the array; on `list_creatives` the parent creative_id is unambiguous and `ext.creative_id` MAY be omitted. Retention: 30 days from `completed_at` (MUST). See `snapshot-and-log.mdx § Webhook activity log pattern` for the full normative contract.
+     */
+    webhook_activity?: WebhookActivityRecord[];
+}
 /**
  * Request parameters for discovering account-scoped creative transformers offered by this creative agent. Brief-filterable and paginated. Transformers are the creative analog of media-buy products: agent-offered, account-scoped, selectable units of build capability. Use `expand_params` to additionally return account-scoped option VALUES (e.g. the buyer's configured voices) for named enumerable params.
  */
@@ -28843,7 +28972,7 @@ export interface PropertyListChangedWebhook {
  *
  * **Direction of truth (normative).** This registry is authoritative for **v1 → v2 projection only**. v2 → v1 projection MUST rely on `v1_format_ref` on the v2 `ProductFormatDeclaration` — sellers assert the v1 pairing explicitly. SDKs MUST NOT synthesize a v1 `format_id` from the registry by inverting structural matches: the registry's `id` slugs lack the `agent_url` half of a `FormatId`, and registry entries with `format_id_glob: '*'` or pure-structural matches have no single literal to invert to. SDKs that synthesize unilaterally produce inter-SDK divergence on structurally-equal values (different SDKs pick different `agent_url` and `id` patterns for the same v2 declaration). When a v2 declaration carries no `v1_format_ref` and a v1-only buyer queries the product, the SDK reports the canonical as v1-unreachable via `FORMAT_DECLARATION_V1_AMBIGUOUS` and lets the buyer surface it to the seller; the seller's path is to add `v1_format_ref` to disambiguate.
  *
- * Best-effort inversion is not available from this registry: as of 3.1 all published entries are pure-structural (family-level), and structural matches are not invertible to a specific v1 `format_id`. Future versions MAY add literal `format_id_glob` entries for platform-specific v1 conventions; in that case SDKs MAY do best-effort inversion for non-wildcarded literals only, AND only when the seller hasn't authored a contradicting `v1_format_ref` — even then, the projection is non-normative and downstream consumers MUST NOT depend on it.
+ * Best-effort inversion is available only from this registry's non-wildcarded literal format_id_glob entries. Structural matches remain family-level and are not invertible to a specific v1 format_id. SDKs MAY do best-effort inversion for non-wildcarded literals only, AND only when the seller hasn't authored a contradicting `v1_format_ref` — even then, the projection is non-normative and downstream consumers MUST NOT depend on it.
  *
  * **Resolution order** (per RFC #3305 amendment #3767, normative):
  * 1. **Authoritative v2→v1 link**: if any v2 `ProductFormatDeclaration` on the same product carries `v1_format_ref` pointing at this v1 format_id, use that v2 declaration. Highest priority — seller asserts the link directly. SDKs SHOULD run the *narrows* check (canonical-formats.mdx 'Narrows — formal definition') between the v2 declaration's `params` and the referenced v1 format's `requirements`; on conflict, surface `FORMAT_DECLARATION_DIVERGENT` on the `get_products` response `errors[]`. Without the narrowing check, `v1_format_ref` is a hint rather than a contract.
@@ -28854,14 +28983,14 @@ export interface PropertyListChangedWebhook {
  * 6. **Fail closed**: SDK MUST NOT emit `format_options` for products carrying this format. SDKs MUST augment the response's `errors[]` array with an entry carrying `source: "sdk"`, `sdk_id: "<package>@<version>"`, `code: "FORMAT_PROJECTION_FAILED"`, `field: "products[N].format_ids[K]"`, and `error.details: { format_id, product_id, resolution_failure: "no_explicit_canonical" | "no_registry_match" | "no_structural_match" }`. Single mandated surface (`errors[]` augmentation) — lint-output channels are NOT acceptable; the multi-hop agent network needs warnings to propagate across SDK boundaries via the wire response. Logger-only warnings die in DEBUG. The advisory is non-fatal: the response stays 200/success, the product is still valid on the v1 path, only the v2 `format_options` projection is absent. Consumer-side counterpart to the producer SHOULD (sellers should add a v2 declaration with `v1_format_ref`, an explicit `canonical` field, or file a registry PR).
  *
  * **Match modes:**
- * - `format_id_glob` — exact / glob match against the v1 `format_id.id`. **As of 3.1 the registry carries zero literal entries**: AAO-catalog-published formats (display_300x250_image, video_vast_30s, audio_standard_30s, etc.) project via resolution-order step 2 (catalog entry's `canonical:` annotation), and platform-specific formats (e.g., Meta Reels, TikTok Spark Ads) project via structural fallback or via the platform's own adagents.json `formats[]` block (#4620). A future literal entry is only justified when (a) the v1 name carries semantic narrowing not recoverable from slot shape AND (b) no platform-published adagents.json exists; such entries land via the AAO governance PR process with a documented rationale. The whole point of canonical-formats is parametrization: ONE `image` canonical with width/height params, not 8 per-size variants. Glob syntax: `*` matches any segment.
+ * - `format_id_glob` — exact / glob match against the v1 `format_id.id`. Published non-wildcarded literals cover independently observed legacy conventions whose names carry semantic narrowing (duration, dimensions, or VAST delivery) that slot shape alone cannot recover. Each literal mapping preserves those constraints in canonical parameters; AAO-catalog-published formats with explicit canonical annotations still project via resolution-order step 2. Glob syntax: `*` matches any segment.
  * - `structural` — match against the format's slot shape, asset types, and version constraints. The PRIMARY fallback for v1 wire traffic — catches custom v1 formats (a publisher's `acme_homepage_300x250` is structurally an IAB MREC) without enumerating every possible v1 name. v1 sellers in the wild naming things their own way are handled here, not by literal globs.
  *
  * **Alias collision precedence (normative).** When a v1 format's `assets[i]` carries multiple `asset_group_id` aliases that resolve to the same canonical asset_group (e.g., two slots both aliasing to `landing_page_url`), the SDK MUST resolve deterministically: the v1 format's `assets[*]` array order is authoritative — the first slot in declaration order wins, subsequent collisions are dropped from the projected v2 manifest and surfaced via `FORMAT_PROJECTION_FAILED` with `error.details: { collision_kind: "asset_group_id_alias", asset_group_id, winning_slot_id, dropped_slot_ids }`. SDKs MUST NOT silently pick one and discard the other without surfacing — silent picking creates inter-SDK divergence. Producers SHOULD avoid the collision by deduplicating aliased slots or using distinct `asset_group_id` values when both slots are semantically meaningful.
  *
  * **Governance**: same vocabulary-governance rules as `asset-group-vocabulary.json` and `format-shape-vocabulary.json` — additions land via PR with rationale + ≥1 reference adopter; AAO maintainer review; versioned + content-digested. Entries are additive; once published they are not removed (they may be marked `deprecated: true` if superseded).
  *
- * **Initial scope (3.1)**: 7 pure-structural fallback entries covering VAST 4.x / legacy VAST, DAAST 1.x, HTML5 zip bundles, hosted video, hosted audio, and url-shaped display tags. Per-size and per-duration literals (display_300x250_image, video_vast_30s, etc.) are NOT enumerated here — those project via catalog `canonical:` annotation (resolution-order step 2), keeping the registry aligned with the canonical-formats parametrization principle. Platform-specific formats (Meta Reels, TikTok Spark Ads, etc.) project via structural fallback or via the platform's own adagents.json `formats[]` block (#4620). The full v1-format audit dataset (~76% of formats from the 12-platform / 86-format audit in #3305) seeds the long-term roadmap and informs future literal-entry decisions.
+ * **Scope**: 7 structural fallback entries cover VAST 4.x / legacy VAST, DAAST 1.x, HTML5 zip bundles, hosted video, hosted audio, and url-shaped display tags. Literal entries cover independently observed legacy duration-, dimension-, and VAST-token naming conventions. Durationless placement ids video_pre_roll and video_mid_roll are deliberately omitted: projecting either to video_hosted without duration_ms_exact would resolve to an untraffickable format and defer failure until ad-server line-item creation. Failing closed during discovery is safer. Platform-specific formats (Meta Reels, TikTok Spark Ads, etc.) project via structural fallback or via the platform's own adagents.json `formats[]` block (#4620). The full v1-format audit dataset (~76% of formats from the 12-platform / 86-format audit in #3305) seeds the long-term roadmap and informs future literal-entry decisions.
  *
  * Digest the file content (sha256) when emitting in capabilities responses or referencing from SDK output. Buyers cache by `version` + `digest`.
  */