@adcp/sdk 6.0.0 → 6.1.0

package/dist/lib/schemas-data/v2.5/media-buy/get-media-buy-delivery-response.json

@@ -0,0 +1,285 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/media-buy/get-media-buy-delivery-response.json",
+  "title": "Get Media Buy Delivery Response",
+  "description": "Response payload for get_media_buy_delivery task",
+  "type": "object",
+  "properties": {
+    "notification_type": {
+      "type": "string",
+      "enum": [
+        "scheduled",
+        "final",
+        "delayed",
+        "adjusted"
+      ],
+      "description": "Type of webhook notification (only present in webhook deliveries): scheduled = regular periodic update, final = campaign completed, delayed = data not yet available, adjusted = resending period with updated data"
+    },
+    "partial_data": {
+      "type": "boolean",
+      "description": "Indicates if any media buys in this webhook have missing/delayed data (only present in webhook deliveries)"
+    },
+    "unavailable_count": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Number of media buys with reporting_delayed or failed status (only present in webhook deliveries when partial_data is true)"
+    },
+    "sequence_number": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Sequential notification number (only present in webhook deliveries, starts at 1)"
+    },
+    "next_expected_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp for next expected notification (only present in webhook deliveries when notification_type is not 'final')"
+    },
+    "reporting_period": {
+      "type": "object",
+      "description": "Date range for the report. All periods use UTC timezone.",
+      "properties": {
+        "start": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 start timestamp in UTC (e.g., 2024-02-05T00:00:00Z)"
+        },
+        "end": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 end timestamp in UTC (e.g., 2024-02-05T23:59:59Z)"
+        }
+      },
+      "required": [
+        "start",
+        "end"
+      ],
+      "additionalProperties": true
+    },
+    "currency": {
+      "type": "string",
+      "description": "ISO 4217 currency code",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "aggregated_totals": {
+      "type": "object",
+      "description": "Combined metrics across all returned media buys. Only included in API responses (get_media_buy_delivery), not in webhook notifications.",
+      "properties": {
+        "impressions": {
+          "type": "number",
+          "description": "Total impressions delivered across all media buys",
+          "minimum": 0
+        },
+        "spend": {
+          "type": "number",
+          "description": "Total amount spent across all media buys",
+          "minimum": 0
+        },
+        "clicks": {
+          "type": "number",
+          "description": "Total clicks across all media buys (if applicable)",
+          "minimum": 0
+        },
+        "video_completions": {
+          "type": "number",
+          "description": "Total video completions across all media buys (if applicable)",
+          "minimum": 0
+        },
+        "media_buy_count": {
+          "type": "integer",
+          "description": "Number of media buys included in the response",
+          "minimum": 0
+        }
+      },
+      "required": [
+        "impressions",
+        "spend",
+        "media_buy_count"
+      ],
+      "additionalProperties": true
+    },
+    "media_buy_deliveries": {
+      "type": "array",
+      "description": "Array of delivery data for media buys. When used in webhook notifications, may contain multiple media buys aggregated by publisher. When used in get_media_buy_delivery API responses, typically contains requested media buys.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "media_buy_id": {
+            "type": "string",
+            "description": "Publisher's media buy identifier"
+          },
+          "buyer_ref": {
+            "type": "string",
+            "description": "Buyer's reference identifier for this media buy"
+          },
+          "status": {
+            "type": "string",
+            "description": "Current media buy status. In webhook context, reporting_delayed indicates data temporarily unavailable.",
+            "enum": [
+              "pending",
+              "active",
+              "paused",
+              "completed",
+              "failed",
+              "reporting_delayed"
+            ]
+          },
+          "expected_availability": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When delayed data is expected to be available (only present when status is reporting_delayed)"
+          },
+          "is_adjusted": {
+            "type": "boolean",
+            "description": "Indicates this delivery contains updated data for a previously reported period. Buyer should replace previous period data with these totals."
+          },
+          "pricing_model": {
+            "$ref": "/schemas/enums/pricing-model.json",
+            "description": "Pricing model used for this media buy"
+          },
+          "totals": {
+            "allOf": [
+              {
+                "$ref": "/schemas/core/delivery-metrics.json"
+              },
+              {
+                "type": "object",
+                "description": "Aggregate metrics for this media buy across all packages",
+                "properties": {
+                  "effective_rate": {
+                    "type": "number",
+                    "description": "Effective rate paid per unit based on pricing_model (e.g., actual CPM for 'cpm', actual cost per completed view for 'cpcv', actual cost per point for 'cpp')",
+                    "minimum": 0
+                  }
+                },
+                "required": [
+                  "spend"
+                ]
+              }
+            ]
+          },
+          "by_package": {
+            "type": "array",
+            "description": "Metrics broken down by package",
+            "items": {
+              "allOf": [
+                {
+                  "$ref": "/schemas/core/delivery-metrics.json"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "package_id": {
+                      "type": "string",
+                      "description": "Publisher's package identifier"
+                    },
+                    "buyer_ref": {
+                      "type": "string",
+                      "description": "Buyer's reference identifier for this package"
+                    },
+                    "pacing_index": {
+                      "type": "number",
+                      "description": "Delivery pace (1.0 = on track, <1.0 = behind, >1.0 = ahead)",
+                      "minimum": 0
+                    },
+                    "pricing_model": {
+                      "$ref": "/schemas/enums/pricing-model.json",
+                      "description": "The pricing model used for this package (e.g., cpm, cpcv, cpp). Indicates how the package is billed and which metrics are most relevant for optimization."
+                    },
+                    "rate": {
+                      "type": "number",
+                      "description": "The pricing rate for this package in the specified currency. For fixed-rate pricing, this is the agreed rate (e.g., CPM rate of 12.50 means $12.50 per 1,000 impressions). For auction-based pricing, this represents the effective rate based on actual delivery.",
+                      "minimum": 0
+                    },
+                    "currency": {
+                      "type": "string",
+                      "description": "ISO 4217 currency code (e.g., USD, EUR, GBP) for this package's pricing. Indicates the currency in which the rate and spend values are denominated. Different packages can use different currencies when supported by the publisher.",
+                      "pattern": "^[A-Z]{3}$"
+                    },
+                    "delivery_status": {
+                      "type": "string",
+                      "description": "System-reported operational state of this package. Reflects actual delivery state independent of buyer pause control.",
+                      "enum": [
+                        "delivering",
+                        "completed",
+                        "budget_exhausted",
+                        "flight_ended",
+                        "goal_met"
+                      ]
+                    },
+                    "paused": {
+                      "type": "boolean",
+                      "description": "Whether this package is currently paused by the buyer"
+                    }
+                  },
+                  "required": [
+                    "package_id",
+                    "spend",
+                    "pricing_model",
+                    "rate",
+                    "currency"
+                  ]
+                }
+              ]
+            }
+          },
+          "daily_breakdown": {
+            "type": "array",
+            "description": "Day-by-day delivery",
+            "items": {
+              "type": "object",
+              "properties": {
+                "date": {
+                  "type": "string",
+                  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+                  "description": "Date (YYYY-MM-DD)"
+                },
+                "impressions": {
+                  "type": "number",
+                  "description": "Daily impressions",
+                  "minimum": 0
+                },
+                "spend": {
+                  "type": "number",
+                  "description": "Daily spend",
+                  "minimum": 0
+                }
+              },
+              "required": [
+                "date",
+                "impressions",
+                "spend"
+              ],
+              "additionalProperties": true
+            }
+          }
+        },
+        "required": [
+          "media_buy_id",
+          "status",
+          "totals",
+          "by_package"
+        ],
+        "additionalProperties": true
+      }
+    },
+    "errors": {
+      "type": "array",
+      "description": "Task-specific errors and warnings (e.g., missing delivery data, reporting platform issues)",
+      "items": {
+        "$ref": "/schemas/core/error.json"
+      }
+    },
+    "context": {
+      "$ref": "/schemas/core/context.json"
+    },
+    "ext": {
+      "$ref": "/schemas/core/ext.json"
+    }
+  },
+  "required": [
+    "reporting_period",
+    "currency",
+    "media_buy_deliveries"
+  ],
+  "additionalProperties": true
+}

package/dist/lib/schemas-data/v2.5/media-buy/get-products-async-response-input-required.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/media-buy/get-products-async-response-input-required.json",
+  "title": "Get Products - Input Required",
+  "description": "Payload when search is paused waiting for user clarification.",
+  "type": "object",
+  "properties": {
+    "reason": {
+      "type": "string",
+      "enum": [
+        "CLARIFICATION_NEEDED",
+        "BUDGET_REQUIRED"
+      ],
+      "description": "Reason code indicating why input is needed"
+    },
+    "partial_results": {
+      "type": "array",
+      "description": "Partial product results that may help inform the clarification",
+      "items": {
+        "$ref": "/schemas/core/product.json"
+      }
+    },
+    "suggestions": {
+      "type": "array",
+      "description": "Suggested values or options for the required input",
+      "items": {
+        "type": "string"
+      }
+    },
+    "context": {
+      "$ref": "/schemas/core/context.json"
+    },
+    "ext": {
+      "$ref": "/schemas/core/ext.json"
+    }
+  },
+  "additionalProperties": true
+}

package/dist/lib/schemas-data/v2.5/media-buy/get-products-async-response-submitted.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/media-buy/get-products-async-response-submitted.json",
+  "title": "Get Products - Submitted",
+  "description": "Payload acknowledging the search is queued. Usually for custom/bespoke product curation.",
+  "type": "object",
+  "properties": {
+    "estimated_completion": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Estimated completion time for the search"
+    },
+    "context": {
+      "$ref": "/schemas/core/context.json"
+    },
+    "ext": {
+      "$ref": "/schemas/core/ext.json"
+    }
+  },
+  "additionalProperties": true
+}

package/dist/lib/schemas-data/v2.5/media-buy/get-products-async-response-working.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/media-buy/get-products-async-response-working.json",
+  "title": "Get Products - Working",
+  "description": "Progress payload for active get_products task.",
+  "type": "object",
+  "properties": {
+    "percentage": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 100,
+      "description": "Progress percentage of the search operation"
+    },
+    "current_step": {
+      "type": "string",
+      "description": "Current step in the search process (e.g., 'searching_inventory', 'validating_availability')"
+    },
+    "total_steps": {
+      "type": "integer",
+      "description": "Total number of steps in the search process"
+    },
+    "step_number": {
+      "type": "integer",
+      "description": "Current step number (1-indexed)"
+    },
+    "context": {
+      "$ref": "/schemas/core/context.json"
+    },
+    "ext": {
+      "$ref": "/schemas/core/ext.json"
+    }
+  },
+  "additionalProperties": true
+}

package/dist/lib/schemas-data/v2.5/media-buy/get-products-request.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/media-buy/get-products-request.json",
+  "title": "Get Products Request",
+  "description": "Request parameters for discovering available advertising products",
+  "type": "object",
+  "properties": {
+    "brief": {
+      "type": "string",
+      "description": "Natural language description of campaign requirements"
+    },
+    "brand_manifest": {
+      "$ref": "/schemas/core/brand-manifest-ref.json",
+      "description": "Brand information manifest providing brand context, assets, and product catalog. Can be provided inline or as a URL reference to a hosted manifest."
+    },
+    "filters": {
+      "$ref": "/schemas/core/product-filters.json"
+    },
+    "context": {
+      "$ref": "/schemas/core/context.json"
+    },
+    "ext": {
+      "$ref": "/schemas/core/ext.json"
+    }
+  },
+  "required": [],
+  "additionalProperties": true
+}

package/dist/lib/schemas-data/v2.5/media-buy/get-products-response.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/media-buy/get-products-response.json",
+  "title": "Get Products Response",
+  "description": "Response payload for get_products task",
+  "type": "object",
+  "properties": {
+    "products": {
+      "type": "array",
+      "description": "Array of matching products",
+      "items": {
+        "$ref": "/schemas/core/product.json"
+      }
+    },
+    "errors": {
+      "type": "array",
+      "description": "Task-specific errors and warnings (e.g., product filtering issues)",
+      "items": {
+        "$ref": "/schemas/core/error.json"
+      }
+    },
+    "context": {
+      "$ref": "/schemas/core/context.json"
+    },
+    "ext": {
+      "$ref": "/schemas/core/ext.json"
+    }
+  },
+  "required": [
+    "products"
+  ],
+  "additionalProperties": true
+}

package/dist/lib/schemas-data/v2.5/media-buy/list-authorized-properties-request.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/media-buy/list-authorized-properties-request.json",
+  "title": "List Authorized Properties Request",
+  "description": "Request parameters for discovering which publishers this agent is authorized to represent",
+  "type": "object",
+  "properties": {
+    "publisher_domains": {
+      "type": "array",
+      "description": "Filter to specific publisher domains (optional). If omitted, returns all publishers this agent represents.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$",
+        "description": "Publisher domain to filter by (e.g., 'cnn.com', 'espn.com')"
+      },
+      "minItems": 1
+    },
+    "context": {
+      "$ref": "/schemas/core/context.json"
+    },
+    "ext": {
+      "$ref": "/schemas/core/ext.json"
+    }
+  },
+  "additionalProperties": true
+}

package/dist/lib/schemas-data/v2.5/media-buy/list-authorized-properties-response.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/media-buy/list-authorized-properties-response.json",
+  "title": "List Authorized Properties Response",
+  "description": "Response payload for list_authorized_properties task. Lists publisher domains and authorization scope (property_ids or property_tags). Buyers fetch actual property definitions from each publisher's canonical adagents.json file.",
+  "type": "object",
+  "properties": {
+    "publisher_domains": {
+      "type": "array",
+      "description": "Publisher domains this agent is authorized to represent. Buyers should fetch each publisher's adagents.json to see property definitions and verify this agent is in their authorized_agents list with authorization scope.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$",
+        "description": "Domain where publisher's adagents.json is hosted (e.g., 'cnn.com')"
+      },
+      "minItems": 1
+    },
+    "primary_channels": {
+      "type": "array",
+      "description": "Primary advertising channels represented in this property portfolio. Helps buying agents quickly filter relevance.",
+      "items": {
+        "$ref": "/schemas/enums/channels.json"
+      },
+      "minItems": 1
+    },
+    "primary_countries": {
+      "type": "array",
+      "description": "Primary countries (ISO 3166-1 alpha-2 codes) where properties are concentrated. Helps buying agents quickly filter relevance.",
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Z]{2}$"
+      },
+      "minItems": 1
+    },
+    "portfolio_description": {
+      "type": "string",
+      "description": "Markdown-formatted description of the property portfolio, including inventory types, audience characteristics, and special features.",
+      "minLength": 1,
+      "maxLength": 5000
+    },
+    "advertising_policies": {
+      "type": "string",
+      "description": "Publisher's advertising content policies, restrictions, and guidelines in natural language. May include prohibited categories, blocked advertisers, restricted tactics, brand safety requirements, or links to full policy documentation.",
+      "minLength": 1,
+      "maxLength": 10000
+    },
+    "last_updated": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of when the agent's publisher authorization list was last updated. Buyers can use this to determine if their cached publisher adagents.json files might be stale."
+    },
+    "errors": {
+      "type": "array",
+      "description": "Task-specific errors and warnings (e.g., property availability issues)",
+      "items": {
+        "$ref": "/schemas/core/error.json"
+      }
+    },
+    "context": {
+      "$ref": "/schemas/core/context.json"
+    },
+    "ext": {
+      "$ref": "/schemas/core/ext.json"
+    }
+  },
+  "required": [
+    "publisher_domains"
+  ],
+  "additionalProperties": true
+}

package/dist/lib/schemas-data/v2.5/media-buy/list-creative-formats-request.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/media-buy/list-creative-formats-request.json",
+  "title": "List Creative Formats Request",
+  "description": "Request parameters for discovering supported creative formats",
+  "type": "object",
+  "properties": {
+    "format_ids": {
+      "type": "array",
+      "description": "Return only these specific format IDs (e.g., from get_products response)",
+      "items": {
+        "$ref": "/schemas/core/format-id.json"
+      }
+    },
+    "type": {
+      "$ref": "/schemas/enums/format-category.json",
+      "description": "Filter by format type (technical categories with distinct requirements)"
+    },
+    "asset_types": {
+      "type": "array",
+      "description": "Filter to formats that include these asset types. For third-party tags, search for 'html' or 'javascript'. E.g., ['image', 'text'] returns formats with images and text, ['javascript'] returns formats accepting JavaScript tags.",
+      "items": {
+        "$ref": "/schemas/enums/asset-content-type.json"
+      }
+    },
+    "max_width": {
+      "type": "integer",
+      "description": "Maximum width in pixels (inclusive). Returns formats where ANY render has width <= this value. For multi-render formats, matches if at least one render fits."
+    },
+    "max_height": {
+      "type": "integer",
+      "description": "Maximum height in pixels (inclusive). Returns formats where ANY render has height <= this value. For multi-render formats, matches if at least one render fits."
+    },
+    "min_width": {
+      "type": "integer",
+      "description": "Minimum width in pixels (inclusive). Returns formats where ANY render has width >= this value."
+    },
+    "min_height": {
+      "type": "integer",
+      "description": "Minimum height in pixels (inclusive). Returns formats where ANY render has height >= this value."
+    },
+    "is_responsive": {
+      "type": "boolean",
+      "description": "Filter for responsive formats that adapt to container size. When true, returns formats without fixed dimensions."
+    },
+    "name_search": {
+      "type": "string",
+      "description": "Search for formats by name (case-insensitive partial match)"
+    },
+    "context": {
+      "$ref": "/schemas/core/context.json"
+    },
+    "ext": {
+      "$ref": "/schemas/core/ext.json"
+    }
+  },
+  "additionalProperties": true
+}

package/dist/lib/schemas-data/v2.5/media-buy/list-creative-formats-response.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/media-buy/list-creative-formats-response.json",
+  "title": "List Creative Formats Response",
+  "description": "Response payload for list_creative_formats task",
+  "type": "object",
+  "properties": {
+    "formats": {
+      "type": "array",
+      "description": "Full format definitions for all formats this agent supports. Each format's authoritative source is indicated by its agent_url field.",
+      "items": {
+        "$ref": "/schemas/core/format.json"
+      }
+    },
+    "creative_agents": {
+      "type": "array",
+      "description": "Optional: Creative agents that provide additional formats. Buyers can recursively query these agents to discover more formats. No authentication required for list_creative_formats.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "agent_url": {
+            "type": "string",
+            "format": "uri",
+            "description": "Base URL for the creative agent (e.g., 'https://reference.adcp.org', 'https://dco.example.com'). Call list_creative_formats on this URL to get its formats."
+          },
+          "agent_name": {
+            "type": "string",
+            "description": "Human-readable name for the creative agent"
+          },
+          "capabilities": {
+            "type": "array",
+            "description": "Capabilities this creative agent provides",
+            "items": {
+              "$ref": "/schemas/enums/creative-agent-capability.json"
+            }
+          }
+        },
+        "required": [
+          "agent_url"
+        ]
+      }
+    },
+    "errors": {
+      "type": "array",
+      "description": "Task-specific errors and warnings (e.g., format availability issues)",
+      "items": {
+        "$ref": "/schemas/core/error.json"
+      }
+    },
+    "context": {
+      "$ref": "/schemas/core/context.json"
+    },
+    "ext": {
+      "$ref": "/schemas/core/ext.json"
+    }
+  },
+  "required": [
+    "formats"
+  ],
+  "additionalProperties": true
+}