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

package/dist/lib/types/list-creatives.d.ts

@@ -150,132 +150,7 @@ export interface ListCreativesResponse {
     /**
      * 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 | AssetVariant[];
-        };
-        /**
-         * 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.
      */
@@ -861,6 +736,11 @@ export interface CSSAsset {
     provenance?: Provenance;
 }
 
+/**
+ * The v2 canonical-format-kind this v1 format projects to (`image`, `html5`, `display_tag`, `image_carousel`, `video_hosted`, `video_vast`, `audio_hosted`, `audio_daast`, `sponsored_placement`, `responsive_creative`, `agent_placement`, or `custom`).
+ */
+export type CanonicalFormatKind = 'image' | 'html5' | 'display_tag' | 'image_carousel' | 'video_hosted' | 'video_vast' | 'audio_hosted' | 'audio_daast' | 'sponsored_placement' | 'native_in_feed' | 'responsive_creative' | 'agent_placement' | 'custom';
+
 /**
  * A single card in a multi-card creative (image_carousel, future composed carousels). Carries: `media` (an image OR video asset), optional `headline` (short text), optional `description` (longer text), optional `cta` (call-to-action label), optional `landing_page_url` (url asset with `url_type: "clickthrough"`).
  *
@@ -1371,6 +1251,11 @@ export interface FlatFeePricing {
     ext?: ExtensionObject;
 }
 
+/**
+ * Discriminated reference to a product format option. The global canonical shape is still named by `format_kind`; this reference selects one concrete product `format_options[]` entry. `scope: "publisher"` identifies a publisher-declared catalog option by `{ publisher_domain, format_option_id }`. `scope: "product"` identifies a product-local option by `format_option_id`; the enclosing package/product context supplies the namespace.
+ */
+export type FormatOptionReference = PublisherCatalogFormatOptionReference | ProductLocalFormatOptionReference;
+
 /**
  * A JSON object — never a plain string — that identifies a creative format by its declaring agent and local slug. Required properties: agent_url (URI of the agent that owns the format) and id (slug matching [a-zA-Z0-9_-]+). Example: {"agent_url": "https://creative.adcontextprotocol.org", "id": "display_300x250"}. Can reference: (1) a concrete format with fixed dimensions (id only), (2) a template format without parameters (id only), or (3) a template format with parameters (id + dimensions/duration). Template formats accept parameters in format_id while concrete formats have fixed dimensions in their definition. Parameterized format IDs create unique, specific format variants. Using a plain string here is a schema violation.
  */
@@ -1531,6 +1416,262 @@ export interface JavaScriptAsset {
  */
 export type JavaScriptModuleType = 'esm' | 'commonjs' | 'script';
 
+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 | AssetVariant[];
+    };
+    /**
+     * 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[];
+}
+
+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]: AssetVariant | AssetVariant[];
+    };
+    /**
+     * 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[];
+}
+
 /**
  * Markdown-formatted text content following CommonMark specification
  */
@@ -1801,6 +1942,21 @@ export interface PlatformExtensionReference {
     digest: string;
 }
 
+/**
+ * Selects a product-local format option by ID within the enclosing package/product context. This branch deliberately forbids `publisher_domain` (`publisher_domain: false` in the schema) because product-local references are namespaced by the enclosing product only; include `scope: "publisher"` when the selector must cross into a publisher catalog.
+ */
+export interface ProductLocalFormatOptionReference {
+    /**
+     * Reference resolves only against the target product's inline `format_options[]`.
+     */
+    scope: 'product';
+    /**
+     * Stable format option ID from the target product's inline `format_options[]`.
+     */
+    format_option_id: string;
+    publisher_domain?: never;
+}
+
 /**
  * Provenance metadata for this asset, overrides manifest-level provenance
  */
@@ -2071,6 +2227,25 @@ export interface PublishedPostAsset {
     provenance?: Provenance;
 }
 
+/**
+ * Selects a publisher-catalog-backed product format option by publisher domain and format option ID.
+ */
+export interface PublisherCatalogFormatOptionReference {
+    /**
+     * Reference resolves against the named publisher's adagents.json top-level `formats[]` catalog.
+     */
+    scope: 'publisher';
+    /**
+     * Publisher domain where the adagents.json declaring this format option is hosted.
+     * @pattern ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$
+     */
+    publisher_domain: string;
+    /**
+     * Stable format option ID from the publisher's adagents.json top-level `formats[]`, matching a publisher-catalog-backed entry in the target product's `format_options[]`.
+     */
+    format_option_id: string;
+}
+
 /**
  * Optional webhook configuration for async terminal completion/failure notifications on curated discovery. Meaningful only for `buying_mode: "brief"` and `buying_mode: "refine"` requests that enter the async lifecycle. Submitted envelopes with `task_id` remain pollable through `get_task_status` (legacy `tasks/get`) whether or not this field is present. If a brief/refine request includes this field and the seller returns a Submitted envelope, the seller MUST deliver at least the terminal completion/failure notification to the configured URL; intermediate progress notifications are MAY. If the seller cannot honor the webhook channel, it MUST reject the request with a structured error instead of silently accepting. This field does not change wholesale timing semantics: sellers MUST NOT route `buying_mode: "wholesale"` requests through the async/Submitted arm or emit async delivery solely because `push_notification_config` is present; partial wholesale completion is reported via `incomplete[]`.
  */

package/dist/lib/types/manifest.generated.d.mts

@@ -1,5 +1,5 @@
 /**
- * Manifest-derived constants for AdCP 3.1.5.
+ * Manifest-derived constants for AdCP 3.1.8.
  *
  * Single source of truth for tool↔protocol grouping, error-code metadata
  * (description + recovery + suggestion), and specialism→required-tools
@@ -9,8 +9,8 @@
  * previously lived in `src/lib/utils/capabilities.ts` and
  * `src/lib/types/error-codes.ts`.
  *
- * Source: `schemas/cache/3.1.5/manifest.json` (adcp_version: 3.1.5, generated_at:
- * 2026-07-24T14:33:01.323Z). Re-run `npm run sync-schemas` then
+ * Source: `schemas/cache/3.1.8/manifest.json` (adcp_version: 3.1.8, generated_at:
+ * 2026-07-28T13:04:06.237Z). Re-run `npm run sync-schemas` then
  * `npm run generate-manifest-derived` to refresh after a spec bump.
  */
 export type ErrorRecovery = 'transient' | 'correctable' | 'terminal';

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

@@ -1,5 +1,5 @@
 /**
- * Manifest-derived constants for AdCP 3.1.5.
+ * Manifest-derived constants for AdCP 3.1.8.
  *
  * Single source of truth for tool↔protocol grouping, error-code metadata
  * (description + recovery + suggestion), and specialism→required-tools
@@ -9,8 +9,8 @@
  * previously lived in `src/lib/utils/capabilities.ts` and
  * `src/lib/types/error-codes.ts`.
  *
- * Source: `schemas/cache/3.1.5/manifest.json` (adcp_version: 3.1.5, generated_at:
- * 2026-07-24T14:33:01.323Z). Re-run `npm run sync-schemas` then
+ * Source: `schemas/cache/3.1.8/manifest.json` (adcp_version: 3.1.8, generated_at:
+ * 2026-07-28T13:04:06.237Z). Re-run `npm run sync-schemas` then
  * `npm run generate-manifest-derived` to refresh after a spec bump.
  */
 export type ErrorRecovery = 'transient' | 'correctable' | 'terminal';