@adcp/sdk 5.23.0

package/dist/lib/schemas-data/3.0.1/core/optimization-goal.json

@@ -0,0 +1,285 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/3.0.1/core/optimization-goal.json",
+  "title": "Optimization Goal",
+  "description": "A single optimization target for a package. Packages accept an array of optimization_goals. When multiple goals are present, priority determines which the seller focuses on — 1 is highest priority (primary goal); higher numbers are secondary. Duplicate priority values result in undefined seller behavior.",
+  "oneOf": [
+    {
+      "type": "object",
+      "description": "Optimize for a seller-tracked delivery metric. No event source required — the seller tracks these natively.",
+      "properties": {
+        "kind": {
+          "type": "string",
+          "const": "metric"
+        },
+        "metric": {
+          "type": "string",
+          "enum": [
+            "clicks",
+            "views",
+            "completed_views",
+            "viewed_seconds",
+            "attention_seconds",
+            "attention_score",
+            "engagements",
+            "follows",
+            "saves",
+            "profile_visits",
+            "reach"
+          ],
+          "description": "Seller-native metric to optimize for. Delivery metrics: clicks (link clicks, swipe-throughs, CTA taps that navigate away), views (viewable impressions), completed_views (video/audio completions — see view_duration_seconds), reach (unique audience reach — see reach_unit and target_frequency). Duration/score metrics: viewed_seconds (time in view per impression), attention_seconds (attention time per impression), attention_score (vendor-specific attention score). Audience action metrics: engagements (any direct interaction with the ad unit beyond viewing — social reactions/comments/shares, story/unit opens, interactive overlay taps, companion banner interactions on audio and CTV), follows (new followers, page likes, artist/podcast/channel subscribes), saves (saves, bookmarks, playlist adds, pins — signals of intent to return), profile_visits (visits to the brand's in-platform page — profile, artist page, channel, or storefront. Does not include external website clicks, which are covered by 'clicks')."
+        },
+        "reach_unit": {
+          "allOf": [
+            {
+              "$ref": "/schemas/3.0.1/enums/reach-unit.json"
+            }
+          ],
+          "description": "Unit for reach measurement. Required when metric is 'reach'. Must be a value declared in the product's metric_optimization.supported_reach_units."
+        },
+        "target_frequency": {
+          "type": "object",
+          "description": "Target frequency band for reach optimization. Only applicable when metric is 'reach'. Frames frequency as an optimization signal: the seller should treat impressions toward entities already within the [min, max] band as lower-value, and impressions toward unreached entities as higher-value. This shifts budget toward fresh reach rather than re-reaching known users. When omitted, the seller maximizes unique reach without a frequency constraint. A hard cap can still be layered via targeting_overlay.frequency_cap if a ceiling is needed.",
+          "properties": {
+            "min": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Minimum frequency for an entity to be considered meaningfully reached within the window. Impressions that would bring an entity below this threshold are treated as high-value (growing reach). When omitted, the seller uses their platform default (typically 1)."
+            },
+            "max": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Frequency at which an entity is considered saturated within the window. Impressions toward entities at or above this threshold are treated as lower-value. When both min and max are present, max must be greater than or equal to min. When omitted, the seller determines the saturation point."
+            },
+            "window": {
+              "allOf": [
+                {
+                  "$ref": "/schemas/3.0.1/core/duration.json"
+                }
+              ],
+              "description": "Time window over which frequency is measured (e.g. {\"interval\": 7, \"unit\": \"days\"} or {\"interval\": 1, \"unit\": \"campaign\"} for the full flight). Weekly windows are typical for brand campaigns; daily windows suit high-cadence direct response."
+            }
+          },
+          "required": [
+            "window"
+          ],
+          "anyOf": [
+            {
+              "required": [
+                "min"
+              ]
+            },
+            {
+              "required": [
+                "max"
+              ]
+            }
+          ],
+          "additionalProperties": true
+        },
+        "view_duration_seconds": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "description": "Minimum video view duration in seconds that qualifies as a completed_view for this goal. Only applicable when metric is 'completed_views'. When omitted, the seller uses their platform default (typically 2–15 seconds). Common values: 2 (Snap/LinkedIn default), 6 (TikTok), 15 (Snap 15-second views, Meta ThruPlay). Sellers declare which durations they support in metric_optimization.supported_view_durations. Sellers must reject goals with unsupported values — silent rounding would create measurement discrepancies."
+        },
+        "target": {
+          "description": "Target for this metric. When omitted, the seller optimizes for maximum metric volume within budget.",
+          "oneOf": [
+            {
+              "type": "object",
+              "description": "Target cost per unit of the metric (e.g., cost per click, cost per completed view).",
+              "properties": {
+                "kind": {
+                  "type": "string",
+                  "const": "cost_per"
+                },
+                "value": {
+                  "type": "number",
+                  "exclusiveMinimum": 0,
+                  "description": "Target cost per metric unit in the buy currency"
+                }
+              },
+              "required": [
+                "kind",
+                "value"
+              ],
+              "additionalProperties": true
+            },
+            {
+              "type": "object",
+              "description": "Minimum per-impression rate for this metric. The metric defines the units: proportions for count metrics (e.g., 0.001 for 0.1% CTR, 0.70 for 70% viewability), seconds for duration metrics (e.g., 3.0 for 3s in view), or score for score metrics.",
+              "properties": {
+                "kind": {
+                  "type": "string",
+                  "const": "threshold_rate"
+                },
+                "value": {
+                  "type": "number",
+                  "exclusiveMinimum": 0,
+                  "description": "Minimum per-impression value. Units depend on the metric: proportion (clicks, views, completed_views), seconds (viewed_seconds, attention_seconds), or score (attention_score)."
+                }
+              },
+              "required": [
+                "kind",
+                "value"
+              ],
+              "additionalProperties": true
+            }
+          ]
+        },
+        "priority": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Relative priority among all optimization goals on this package. 1 = highest priority (primary goal); higher numbers are lower priority (secondary signals). When omitted, sellers may use array position as priority."
+        }
+      },
+      "required": [
+        "kind",
+        "metric"
+      ],
+      "additionalProperties": true
+    },
+    {
+      "type": "object",
+      "description": "Optimize for advertiser-tracked conversion events. Requires event sources registered via sync_event_sources.",
+      "properties": {
+        "kind": {
+          "type": "string",
+          "const": "event"
+        },
+        "event_sources": {
+          "type": "array",
+          "description": "Event source and type pairs that feed this goal. Each entry identifies a source and event type to include. When the seller supports multi_source_event_dedup (declared in get_adcp_capabilities), they deduplicate by event_id across all entries — the same business event from multiple sources counts once, using value_field and value_factor from the first matching entry. When multi_source_event_dedup is false or absent, buyers should use a single entry per goal; the seller will use only the first entry. All event sources must be configured via sync_event_sources.",
+          "items": {
+            "type": "object",
+            "properties": {
+              "event_source_id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Event source to include (must be configured on this account via sync_event_sources)"
+              },
+              "event_type": {
+                "$ref": "/schemas/3.0.1/enums/event-type.json",
+                "description": "Event type to include from this source (e.g., purchase, lead, app_install, refund)"
+              },
+              "custom_event_name": {
+                "type": "string",
+                "description": "Required when event_type is 'custom'. Platform-specific name for the custom event."
+              },
+              "value_field": {
+                "type": "string",
+                "description": "Which field in the event's custom_data carries the monetary value. The seller must use this field for value extraction and aggregation when computing ROAS and conversion value metrics. Required on at least one entry when target.kind is 'per_ad_spend' or 'maximize_value' — sellers must reject these target kinds when no event source entry includes value_field. When present without a value-oriented target, the seller may use it for delivery reporting (conversion_value, roas) but must not change the optimization objective. Common values: 'value', 'order_total', 'profit_margin'. This is not passed as a parameter to underlying platform APIs — the seller maps it to their platform's value ingestion mechanism."
+              },
+              "value_factor": {
+                "type": "number",
+                "default": 1,
+                "description": "Multiplier the seller must apply to value_field before aggregation. Use -1 for refund events (negate the value), 0.01 for values in cents, -0.01 for refunds in cents. A value of 0 zeroes out this source's value contribution (the source still counts for event dedup). Defaults to 1. This is not passed as a parameter to underlying platform APIs — the seller applies it when computing aggregated value metrics."
+              }
+            },
+            "required": [
+              "event_source_id",
+              "event_type"
+            ],
+            "additionalProperties": true
+          },
+          "minItems": 1
+        },
+        "target": {
+          "description": "Target cost or return for this event goal. When omitted, the seller optimizes for maximum conversion count within budget — regardless of whether value_field is present on event sources. The presence of value_field alone does not change the optimization objective; it only makes value available for reporting. An explicit target of maximize_value or per_ad_spend is required to steer toward value.",
+          "oneOf": [
+            {
+              "type": "object",
+              "description": "Target cost per conversion event (after deduplication across event_sources).",
+              "properties": {
+                "kind": {
+                  "type": "string",
+                  "const": "cost_per"
+                },
+                "value": {
+                  "type": "number",
+                  "exclusiveMinimum": 0,
+                  "description": "Target cost per event in the buy currency"
+                }
+              },
+              "required": [
+                "kind",
+                "value"
+              ],
+              "additionalProperties": true
+            },
+            {
+              "type": "object",
+              "description": "Target return per unit of ad spend, calculated as sum(value_field * value_factor) / spend across all deduplicated events. Requires value_field on at least one event_sources entry.",
+              "properties": {
+                "kind": {
+                  "type": "string",
+                  "const": "per_ad_spend"
+                },
+                "value": {
+                  "type": "number",
+                  "exclusiveMinimum": 0,
+                  "description": "Target return ratio (e.g., 4.0 means $4 of value per $1 spent)"
+                }
+              },
+              "required": [
+                "kind",
+                "value"
+              ],
+              "additionalProperties": true
+            },
+            {
+              "type": "object",
+              "description": "Maximize total conversion value within budget, without a specific return ratio target. Steers spend toward higher-value conversions rather than maximizing conversion count. Requires value_field on at least one event_sources entry.",
+              "properties": {
+                "kind": {
+                  "type": "string",
+                  "const": "maximize_value"
+                }
+              },
+              "required": [
+                "kind"
+              ],
+              "additionalProperties": true
+            }
+          ]
+        },
+        "attribution_window": {
+          "type": "object",
+          "description": "Attribution window for this optimization goal. Values must match an option declared in the seller's conversion_tracking.attribution_windows capability. Sellers must reject windows not in their declared capabilities. When omitted, the seller uses their default window.",
+          "properties": {
+            "post_click": {
+              "allOf": [
+                {
+                  "$ref": "/schemas/3.0.1/core/duration.json"
+                }
+              ],
+              "description": "Post-click attribution window. Conversions within this duration after a click are attributed to the ad (e.g. {\"interval\": 7, \"unit\": \"days\"})."
+            },
+            "post_view": {
+              "allOf": [
+                {
+                  "$ref": "/schemas/3.0.1/core/duration.json"
+                }
+              ],
+              "description": "Post-view attribution window. Conversions within this duration after an ad impression (without click) are attributed to the ad (e.g. {\"interval\": 1, \"unit\": \"days\"})."
+            }
+          },
+          "required": [
+            "post_click"
+          ],
+          "additionalProperties": true
+        },
+        "priority": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Relative priority among all optimization goals on this package. 1 = highest priority (primary goal); higher numbers are lower priority (secondary signals). When omitted, sellers may use array position as priority."
+        }
+      },
+      "required": [
+        "kind",
+        "event_sources"
+      ],
+      "additionalProperties": true
+    }
+  ]
+}

package/dist/lib/schemas-data/3.0.1/core/outcome-measurement.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/3.0.1/core/outcome-measurement.json",
+  "title": "Outcome Measurement",
+  "description": "Business outcome measurement capabilities included with a product (e.g., incremental sales lift, brand lift, foot traffic). Distinct from delivery_measurement, which declares who counts ad impressions.",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "description": "Type of measurement",
+      "examples": [
+        "incremental_sales_lift",
+        "brand_lift",
+        "foot_traffic"
+      ]
+    },
+    "attribution": {
+      "type": "string",
+      "description": "Attribution methodology",
+      "examples": [
+        "deterministic_purchase",
+        "probabilistic"
+      ]
+    },
+    "window": {
+      "allOf": [
+        {
+          "$ref": "/schemas/3.0.1/core/duration.json"
+        }
+      ],
+      "description": "Attribution window as a structured duration (e.g., {\"interval\": 30, \"unit\": \"days\"})."
+    },
+    "reporting": {
+      "type": "string",
+      "description": "Reporting frequency and format",
+      "examples": [
+        "weekly_dashboard",
+        "real_time_api"
+      ]
+    }
+  },
+  "required": [
+    "type",
+    "attribution",
+    "reporting"
+  ],
+  "additionalProperties": true
+}

package/dist/lib/schemas-data/3.0.1/core/overlay.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/3.0.1/core/overlay.json",
+  "title": "Overlay",
+  "description": "A publisher-controlled element that renders on top of buyer creative content within the ad placement. Creative agents should avoid placing critical content (CTAs, logos, key copy) within overlay bounds.",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Identifier for this overlay (e.g., 'play_pause', 'volume', 'publisher_logo', 'carousel_prev', 'carousel_next')"
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable explanation of what this overlay is and how buyers should account for it"
+    },
+    "visual": {
+      "type": "object",
+      "description": "Optional visual reference for this overlay element. Useful for creative agents compositing previews and for buyers understanding what will appear over their content. Must include at least one of: url, light, or dark.",
+      "properties": {
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to a theme-neutral overlay graphic (SVG or PNG). Use when a single file works for all backgrounds, e.g. an SVG using CSS custom properties or currentColor."
+        },
+        "light": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to the overlay graphic for use on light/bright backgrounds (SVG or PNG)"
+        },
+        "dark": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to the overlay graphic for use on dark backgrounds (SVG or PNG)"
+        }
+      },
+      "minProperties": 1,
+      "additionalProperties": false
+    },
+    "bounds": {
+      "type": "object",
+      "description": "Position and size of the overlay relative to the asset's own top-left corner. See 'unit' for coordinate interpretation.",
+      "properties": {
+        "x": {
+          "type": "number",
+          "description": "Horizontal offset from the asset's left edge"
+        },
+        "y": {
+          "type": "number",
+          "description": "Vertical offset from the asset's top edge"
+        },
+        "width": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Width of the overlay"
+        },
+        "height": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Height of the overlay"
+        },
+        "unit": {
+          "type": "string",
+          "enum": [
+            "px",
+            "fraction",
+            "inches",
+            "cm",
+            "mm",
+            "pt"
+          ],
+          "description": "'px' = absolute pixels from asset top-left. 'fraction' = proportional to asset dimensions (0.0 = edge, 1.0 = opposite edge). 'inches', 'cm', 'mm', 'pt' (1/72 inch) = physical units for print overlays, measured from asset top-left."
+        }
+      },
+      "required": [
+        "x",
+        "y",
+        "width",
+        "height",
+        "unit"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "id",
+    "bounds"
+  ],
+  "additionalProperties": false
+}

package/dist/lib/schemas-data/3.0.1/core/package.json

@@ -0,0 +1,170 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/3.0.1/core/package.json",
+  "title": "Package",
+  "description": "A specific product within a media buy (line item)",
+  "type": "object",
+  "properties": {
+    "package_id": {
+      "type": "string",
+      "description": "Seller's unique identifier for the package",
+      "x-entity": "package"
+    },
+    "product_id": {
+      "type": "string",
+      "description": "ID of the product this package is based on",
+      "x-entity": "product"
+    },
+    "budget": {
+      "type": "number",
+      "description": "Budget allocation for this package in the currency specified by the pricing option",
+      "minimum": 0
+    },
+    "pacing": {
+      "$ref": "/schemas/3.0.1/enums/pacing.json"
+    },
+    "pricing_option_id": {
+      "type": "string",
+      "description": "ID of the selected pricing option from the product's pricing_options array",
+      "x-entity": "product_pricing_option"
+    },
+    "bid_price": {
+      "type": "number",
+      "description": "Bid price for auction-based pricing. This is the exact bid/price to honor unless the selected pricing option has max_bid=true, in which case bid_price is the buyer's maximum willingness to pay (ceiling).",
+      "minimum": 0
+    },
+    "price_breakdown": {
+      "description": "Breakdown of the effective price for this package. On fixed-price packages, echoes the pricing option's breakdown. On auction packages, shows the clearing price breakdown including any commission or settlement terms.",
+      "$ref": "/schemas/3.0.1/pricing-options/price-breakdown.json"
+    },
+    "impressions": {
+      "type": "number",
+      "description": "Impression goal for this package",
+      "minimum": 0
+    },
+    "catalogs": {
+      "type": "array",
+      "description": "Catalogs this package promotes. Each catalog MUST have a distinct type (e.g., one product catalog, one store catalog). This constraint is enforced at the application level — sellers MUST reject requests containing multiple catalogs of the same type with a validation_error. Echoed from the create_media_buy request.",
+      "items": {
+        "$ref": "/schemas/3.0.1/core/catalog.json"
+      }
+    },
+    "format_ids": {
+      "type": "array",
+      "description": "Format IDs active for this package. Echoed from the create_media_buy request; omitted means all formats for the product are active.",
+      "items": {
+        "$ref": "/schemas/3.0.1/core/format-id.json"
+      }
+    },
+    "targeting_overlay": {
+      "$ref": "/schemas/3.0.1/core/targeting.json"
+    },
+    "measurement_terms": {
+      "$ref": "/schemas/3.0.1/core/measurement-terms.json",
+      "description": "Agreed billing measurement and makegood terms for this package. Reflects what was negotiated — may differ from the buyer's proposal or the product's defaults. When present, these terms are binding for the package's duration."
+    },
+    "performance_standards": {
+      "type": "array",
+      "description": "Agreed performance standards for this package. When any entry specifies a vendor, creatives assigned to this package MUST include corresponding tracker_script or tracker_pixel assets from that vendor.",
+      "items": {
+        "$ref": "/schemas/3.0.1/core/performance-standard.json"
+      },
+      "minItems": 1
+    },
+    "creative_assignments": {
+      "type": "array",
+      "description": "Creative assets assigned to this package",
+      "items": {
+        "$ref": "/schemas/3.0.1/core/creative-assignment.json"
+      }
+    },
+    "format_ids_to_provide": {
+      "type": "array",
+      "description": "Format IDs that creative assets will be provided for this package",
+      "items": {
+        "$ref": "/schemas/3.0.1/core/format-id.json"
+      }
+    },
+    "optimization_goals": {
+      "type": "array",
+      "description": "Optimization targets for this package. The seller optimizes delivery toward these goals in priority order. Common pattern: event goals (purchase, install) as primary targets at priority 1; metric goals (clicks, views) as secondary proxy signals at priority 2+.",
+      "items": {
+        "$ref": "/schemas/3.0.1/core/optimization-goal.json"
+      },
+      "minItems": 1
+    },
+    "start_time": {
+      "type": "string",
+      "format": "date-time",
+      "not": {
+        "const": "asap"
+      },
+      "description": "Flight start date/time for this package in ISO 8601 format. When omitted, the package inherits the media buy's start_time. Sellers SHOULD always include the resolved value in responses, even when inherited."
+    },
+    "end_time": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Flight end date/time for this package in ISO 8601 format. When omitted, the package inherits the media buy's end_time. Sellers SHOULD always include the resolved value in responses, even when inherited."
+    },
+    "paused": {
+      "type": "boolean",
+      "description": "Whether this package is paused by the buyer. Paused packages do not deliver impressions. Defaults to false.",
+      "default": false
+    },
+    "canceled": {
+      "type": "boolean",
+      "description": "Whether this package has been canceled. Canceled packages stop delivery and cannot be reactivated. Defaults to false.",
+      "default": false
+    },
+    "cancellation": {
+      "type": "object",
+      "description": "Cancellation metadata. Present only when canceled is true.",
+      "required": [
+        "canceled_at",
+        "canceled_by"
+      ],
+      "properties": {
+        "canceled_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp when this package was canceled."
+        },
+        "canceled_by": {
+          "$ref": "/schemas/3.0.1/enums/canceled-by.json",
+          "description": "Which party initiated the package cancellation."
+        },
+        "reason": {
+          "type": "string",
+          "description": "Reason the package was canceled.",
+          "maxLength": 500
+        },
+        "acknowledged_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp when the seller acknowledged the cancellation. Confirms inventory has been released and billing stopped. Absent until the seller processes the cancellation."
+        }
+      },
+      "additionalProperties": false
+    },
+    "agency_estimate_number": {
+      "type": "string",
+      "maxLength": 100,
+      "description": "Agency estimate or authorization number for this package. Echoed from the buyer's request. When present on the package, takes precedence over the media buy-level estimate number."
+    },
+    "creative_deadline": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp for creative upload or change deadline for this package. After this deadline, creative changes are rejected. When absent, the media buy's creative_deadline applies."
+    },
+    "context": {
+      "$ref": "/schemas/3.0.1/core/context.json"
+    },
+    "ext": {
+      "$ref": "/schemas/3.0.1/core/ext.json"
+    }
+  },
+  "required": [
+    "package_id"
+  ],
+  "additionalProperties": true
+}

package/dist/lib/schemas-data/3.0.1/core/pagination-request.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/3.0.1/core/pagination-request.json",
+  "title": "Pagination Request",
+  "description": "Standard cursor-based pagination parameters for list operations",
+  "type": "object",
+  "properties": {
+    "max_results": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100,
+      "default": 50,
+      "description": "Maximum number of items to return per page"
+    },
+    "cursor": {
+      "type": "string",
+      "description": "Opaque cursor from a previous response to fetch the next page"
+    }
+  },
+  "additionalProperties": false
+}

package/dist/lib/schemas-data/3.0.1/core/pagination-response.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/3.0.1/core/pagination-response.json",
+  "title": "Pagination Response",
+  "description": "Standard cursor-based pagination metadata for list responses",
+  "type": "object",
+  "properties": {
+    "has_more": {
+      "type": "boolean",
+      "description": "Whether more results are available beyond this page"
+    },
+    "cursor": {
+      "type": "string",
+      "description": "Opaque cursor to pass in the next request to fetch the next page. Only present when has_more is true."
+    },
+    "total_count": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total number of items matching the query across all pages. Optional because not all backends can efficiently compute this."
+    }
+  },
+  "required": [
+    "has_more"
+  ],
+  "additionalProperties": false
+}