@adcp/sdk 6.6.0 → 6.7.0

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

@@ -2291,7 +2291,7 @@ export interface Error {
      */
     message: string;
     /**
-     * Field path associated with the error (e.g., 'packages[0].targeting')
+     * Field path associated with the error in JSONPath-lite format (e.g., 'packages[0].targeting'). When `issues[]` is also present, sellers MUST set this to `issues[0].pointer` translated from RFC 6901 to JSONPath-lite (e.g., '/packages/0/targeting' → 'packages[0].targeting') so pre-3.1 consumers reading `field` only get deterministic behavior. Will be deprecated in a future major version in favor of `issues[].pointer`.
      */
     field?: string;
     /**
@@ -2303,7 +2303,28 @@ export interface Error {
      */
     retry_after?: number;
     /**
-     * Additional task-specific error details
+     * Structured list of validation failures. Primary use is `VALIDATION_ERROR`, where multi-field rejections are common and `field` (singular) cannot carry the full pointer map. MAY appear on other error codes that reject multiple fields at once. When `issues` is present, sellers MUST also populate `field` from `issues[0]` for backward compatibility with pre-3.1 consumers that read `field` only — translating the RFC 6901 `pointer` format to the JSONPath-lite format `field` uses (e.g., `/packages/0/targeting` → `packages[0].targeting`). MUST (not SHOULD) so consumers reading `field` get deterministic behavior across sellers — the cost is one line of dual-write per seller; the cost of SHOULD is a long tail of seller-A-vs-seller-B inconsistency. Future major versions will deprecate `field` in favor of `issues[].pointer`.
+     */
+    issues?: {
+        /**
+         * RFC 6901 JSON Pointer to the offending field in the request payload (e.g., '/packages/0/targeting/geo_countries/2'). Format chosen to match Ajv's native validation output (`instancePath`); standardized and unambiguous on keys containing `/` or `~`. NOTE: this differs from the legacy top-level `field` which uses JSONPath-lite (`packages[0].targeting.geo_countries[2]`). When sellers populate `field` from `issues[0].pointer` for backward compatibility (see `field` description), they MUST translate the format — `/packages/0/x` → `packages[0].x`. Future major versions will deprecate `field` in favor of `issues[].pointer`.
+         */
+        pointer: string;
+        /**
+         * Human-readable description of why this specific field was rejected.
+         */
+        message: string;
+        /**
+         * Schema keyword that rejected the payload, drawn from the JSON Schema vocabulary (e.g., 'required', 'type', 'format', 'enum', 'pattern', 'minimum', 'maxLength'). Matches the keyword names emitted by JSON Schema validators (Ajv, jsonschema, etc.) so agents can pattern-match on rejection class without parsing message text. Implementers SHOULD use the validator's native keyword name; do not invent custom values here.
+         */
+        keyword: string;
+        /**
+         * Optional. Path inside the schema that rejected the payload (e.g., '#/properties/packages/items/properties/targeting/oneOf/1'). Sellers SHOULD NOT emit on production-facing endpoints — `schemaPath` leaks which `oneOf` branch the validator selected before semantic rejection, which is a probe oracle for adversarial callers crafting payloads against polymorphic unions. Sellers MAY emit in dev/sandbox modes where the diagnostic value outweighs the fingerprinting risk.
+         */
+        schemaPath?: string;
+    }[];
+    /**
+     * Additional task-specific error details. Sellers MAY mirror `issues[]` here as `details.issues` for backward compatibility with pre-3.1 consumers reading from `details`; new consumers SHOULD prefer the top-level `issues` field.
      */
     details?: {};
     /**
@@ -2409,6 +2430,10 @@ export interface ListCreativeFormatsRequest {
  * Types of parameters that template formats accept in format_id objects to create parameterized format identifiers
  */
 export type FormatIDParameter = 'dimensions' | 'duration';
+/**
+ * Unit of measurement for width/height values. Defaults to 'px' when absent. Print formats use 'inches' or 'cm'.
+ */
+export type DimensionUnit = 'px' | 'dp' | 'inches' | 'cm' | 'mm' | 'pt';
 /**
  * Image asset
  */
@@ -2596,8 +2621,56 @@ export interface Format {
      * Specification of rendered pieces for this format. Most formats produce a single render. Companion ad formats (video + banner), adaptive formats, and multi-placement formats produce multiple renders. Each render specifies its role and dimensions.
      */
     renders?: ({
-        [k: string]: unknown | undefined;
+        /**
+         * Semantic role of this rendered piece (e.g., 'primary', 'companion', 'mobile_variant')
+         */
+        role: string;
+        /**
+         * Dimensions for this rendered piece. Defaults to pixels when unit is absent.
+         */
+        dimensions: {
+            /**
+             * Fixed width. Interpretation depends on unit (default: pixels).
+             */
+            width?: number;
+            /**
+             * Fixed height. Interpretation depends on unit (default: pixels).
+             */
+            height?: number;
+            /**
+             * Minimum width for responsive renders
+             */
+            min_width?: number;
+            /**
+             * Minimum height for responsive renders
+             */
+            min_height?: number;
+            /**
+             * Maximum width for responsive renders
+             */
+            max_width?: number;
+            /**
+             * Maximum height for responsive renders
+             */
+            max_height?: number;
+            unit?: DimensionUnit;
+            /**
+             * Indicates which dimensions are responsive/fluid
+             */
+            responsive?: {
+                width: boolean;
+                height: boolean;
+            };
+            /**
+             * Fixed aspect ratio constraint (e.g., '16:9', '4:3', '1:1', '1.91:1')
+             */
+            aspect_ratio?: string;
+        };
     } | {
+        /**
+         * Semantic role of this rendered piece (e.g., 'primary', 'companion', 'mobile_variant')
+         */
+        role: string;
         parameters_from_format_id: true;
     })[];
     /**
@@ -3043,6 +3116,13 @@ export type DevicePlatform = 'ios' | 'android' | 'windows' | 'macos' | 'linux' |
  * Device form factor categories for targeting and reporting. Complements device-platform (operating system) with hardware classification. OpenRTB mapping: 1 (Mobile/Tablet General) → mobile, 2 (PC) → desktop, 4 (Phone) → mobile, 5 (Tablet) → tablet, 6 (Connected Device) → ctv, 7 (Set Top Box) → ctv. DOOH inventory uses dooh.
  */
 export type DeviceType = 'desktop' | 'mobile' | 'tablet' | 'ctv' | 'dooh' | 'unknown';
+/**
+ * Canonical union of all asset variant schemas. Referenced from creative-asset.json and creative-manifest.json to ensure a single named type is emitted by schema-to-TypeScript tooling. Add new asset types here and to the creative/asset-types registry.
+ *
+ * This interface was referenced by `undefined`'s JSON-Schema definition
+ * via the `patternProperty` "^[a-z0-9_]+$".
+ */
+export type AssetVariant = ImageAsset | VideoAsset | AudioAsset | VASTAsset | TextAsset | URLAsset | HTMLAsset | JavaScriptAsset | WebhookAsset | CSSAsset | DAASTAsset | MarkdownAsset | BriefAsset | CatalogAsset;
 /**
  * IPTC-aligned classification of AI involvement in producing this content
  */
@@ -3125,7 +3205,7 @@ export type VASTVersion = '2.0' | '3.0' | '4.0' | '4.1' | '4.2';
  */
 export type VASTTrackingEvent = 'impression' | 'creativeView' | 'loaded' | 'start' | 'firstQuartile' | 'midpoint' | 'thirdQuartile' | 'complete' | 'mute' | 'unmute' | 'pause' | 'resume' | 'rewind' | 'skip' | 'playerExpand' | 'playerCollapse' | 'fullscreen' | 'exitFullscreen' | 'progress' | 'notUsed' | 'otherAdInteraction' | 'interactiveStart' | 'clickTracking' | 'customClick' | 'close' | 'closeLinear' | 'error' | 'viewable' | 'notViewable' | 'viewUndetermined' | 'measurableImpression' | 'viewableImpression';
 /**
- * Type of URL asset: 'clickthrough' for user click destination (landing page), 'tracker_pixel' for impression/event tracking via HTTP request (fires GET, expects pixel/204 response), 'tracker_script' for measurement SDKs that must load as <script> tag (OMID verification, native event trackers using method:2)
+ * Mechanism a receiver uses to invoke this URL (distinct from purpose, which lives in `url-asset-requirements.role`): `clickthrough` for user click destination (landing page), `tracker_pixel` for impression/event tracking via HTTP request (fires GET, expects pixel/204 response), `tracker_script` for measurement SDKs that must load as a <script> tag (OMID verification, native event trackers using method:2). SHOULD be present on every URL asset; senders that omit it force the receiver into the role-based fallback described in this schema's top-level description.
  */
 export type URLAssetType = 'clickthrough' | 'tracker_pixel' | 'tracker_script';
 /**
@@ -3649,11 +3729,7 @@ export interface CreativeAsset {
      * Assets required by the format, keyed by asset_id. 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]: ImageAsset | VideoAsset | AudioAsset | VASTAsset | TextAsset | URLAsset | HTMLAsset | JavaScriptAsset | WebhookAsset | CSSAsset | DAASTAsset | MarkdownAsset | BriefAsset | CatalogAsset;
+        [k: string]: AssetVariant | undefined;
     };
     /**
      * Preview contexts for generative formats - defines what scenarios to generate previews for
@@ -4036,7 +4112,7 @@ export interface TextAsset {
     provenance?: Provenance;
 }
 /**
- * URL reference asset
+ * URL reference asset. `url_type` declares the mechanism a receiver uses to invoke the URL (clickthrough vs. tracker_pixel vs. tracker_script) and is distinct from the URL's purpose, which the format declares in `url-asset-requirements.role` (clickthrough, landing_page, impression_tracker, click_tracker, viewability_tracker, third_party_tracker). Senders SHOULD include `url_type` on every URL asset. When `url_type` is absent, receivers SHOULD fall back to the format's `url-asset-requirements.role` per this mapping: clickthrough/landing_page → `clickthrough`; impression_tracker/click_tracker → `tracker_pixel`; viewability_tracker → `tracker_script` (OMID and equivalent verification SDKs require a <script> tag — firing them as a pixel produces no measurement); third_party_tracker → no safe fallback (mechanism is integration-specific — DV/IAS ship both pixel and script forms — receivers MAY reject or warn). When neither `url_type` nor a format-side `role` is available, receivers MUST NOT silently pick a mechanism; they SHOULD reject the manifest. Note: VAST/DAAST tag URLs are not URL assets — use `asset_type: "vast"` (or the dedicated tracker types pending RFC #2915), not `asset_type: "url"` with a tracker_pixel mechanism.
  */
 export interface URLAsset {
     /**
@@ -7012,11 +7088,7 @@ export interface CreativeManifest {
      * Each asset value carries an `asset_type` discriminator (image, video, audio, vast, daast, text, markdown, url, html, css, webhook, javascript, brief, catalog) that selects the matching asset schema. Validators with OpenAPI-style discriminator support use `asset_type` to report errors against only the selected branch instead of all branches.
      */
     assets: {
-        /**
-         * This interface was referenced by `undefined`'s JSON-Schema definition
-         * via the `patternProperty` "^[a-z0-9_]+$".
-         */
-        [k: string]: ImageAsset | VideoAsset | AudioAsset | VASTAsset | TextAsset | URLAsset | HTMLAsset | JavaScriptAsset | WebhookAsset | CSSAsset | DAASTAsset | MarkdownAsset | BriefAsset | CatalogAsset;
+        [k: string]: AssetVariant | undefined;
     };
     /**
      * Rights constraints attached to this creative. Each entry represents constraints from a single rights holder. A creative may combine multiple rights constraints (e.g., talent likeness + music license). For v1, rights constraints are informational metadata — the buyer/orchestrator manages creative lifecycle against these terms.
@@ -8010,11 +8082,7 @@ export interface ListCreativesResponse {
          * Assets for this creative, keyed by asset_id. 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]: ImageAsset | VideoAsset | AudioAsset | VASTAsset | TextAsset | URLAsset | HTMLAsset | JavaScriptAsset | WebhookAsset | CSSAsset | DAASTAsset | MarkdownAsset | BriefAsset | CatalogAsset;
+            [k: string]: AssetVariant | undefined;
         };
         /**
          * User-defined tags for organization and searchability
@@ -10527,9 +10595,66 @@ export interface SyncPlansRequest {
          * Budget authorization parameters.
          */
         budget: {
-            [k: string]: unknown | undefined;
+            /**
+             * Total authorized budget.
+             */
+            total: number;
+            /**
+             * ISO 4217 currency code.
+             */
+            currency: string;
+            /**
+             * Maximum percentage of budget that can go to a single seller.
+             */
+            per_seller_max_pct?: number;
+            /**
+             * Amount above which budget reallocations require human escalation. The orchestrator can reallocate spend across sellers, channels, or purchase types up to this threshold per change without asking a human. Set equal to `total` for effectively unlimited reallocation; set to 0 to require approval for every reallocation. Separate from `plan.human_review_required`, which governs decisions affecting data subjects (targeting, creative, delivery) under GDPR Art 22 / EU AI Act Annex III. Denominated in `budget.currency`.
+             */
+            reallocation_threshold: number;
+            /**
+             * Optional budget partition across purchase types. Keys are purchase-type enum values (media_buy, rights_license, signal_activation, creative_services). When present, the governance agent validates spend against both the total and the per-type allocation. When absent, all spend counts against the single total regardless of purchase type.
+             */
+            allocations?: {
+                [k: string]: {
+                    /**
+                     * Maximum budget for this purchase type.
+                     */
+                    amount?: number;
+                    /**
+                     * Maximum percentage of total budget for this purchase type.
+                     */
+                    max_pct?: number;
+                } | undefined;
+            };
         } | {
+            /**
+             * Total authorized budget.
+             */
+            total: number;
+            /**
+             * ISO 4217 currency code.
+             */
+            currency: string;
+            /**
+             * Maximum percentage of budget that can go to a single seller.
+             */
+            per_seller_max_pct?: number;
             reallocation_unlimited: true;
+            /**
+             * Optional budget partition across purchase types. Keys are purchase-type enum values (media_buy, rights_license, signal_activation, creative_services). When present, the governance agent validates spend against both the total and the per-type allocation. When absent, all spend counts against the single total regardless of purchase type.
+             */
+            allocations?: {
+                [k: string]: {
+                    /**
+                     * Maximum budget for this purchase type.
+                     */
+                    amount?: number;
+                    /**
+                     * Maximum percentage of total budget for this purchase type.
+                     */
+                    max_pct?: number;
+                } | undefined;
+            };
         };
         /**
          * Channel constraints. If omitted, all channels are allowed.