@adcp/sdk 6.0.0 → 6.2.0

package/dist/lib/schemas-data/v2.5/core/format.json

@@ -0,0 +1,324 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/format.json",
+  "title": "Format",
+  "description": "Represents a creative format with its requirements",
+  "type": "object",
+  "properties": {
+    "format_id": {
+      "$ref": "/schemas/core/format-id.json",
+      "description": "Structured format identifier with agent URL and format name"
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable format name"
+    },
+    "description": {
+      "type": "string",
+      "description": "Plain text explanation of what this format does and what assets it requires"
+    },
+    "preview_image": {
+      "type": "string",
+      "format": "uri",
+      "description": "DEPRECATED: Use format_card instead. Optional preview image URL for format browsing/discovery UI. Should be 400x300px (4:3 aspect ratio) PNG or JPG. Used as thumbnail/card image in format browsers. This field is maintained for backward compatibility but format_card provides a more flexible, structured approach."
+    },
+    "example_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Optional URL to showcase page with examples and interactive demos of this format"
+    },
+    "type": {
+      "$ref": "/schemas/enums/format-category.json",
+      "description": "Media type of this format - determines rendering method and asset requirements"
+    },
+    "accepts_parameters": {
+      "type": "array",
+      "description": "List of parameters this format accepts in format_id. Template formats define which parameters (dimensions, duration, etc.) can be specified when instantiating the format. Empty or omitted means this is a concrete format with fixed parameters.",
+      "items": {
+        "$ref": "/schemas/enums/format-id-parameter.json"
+      },
+      "uniqueItems": true
+    },
+    "renders": {
+      "type": "array",
+      "description": "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.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "role": {
+            "type": "string",
+            "description": "Semantic role of this rendered piece (e.g., 'primary', 'companion', 'mobile_variant')"
+          },
+          "parameters_from_format_id": {
+            "type": "boolean",
+            "description": "When true, parameters for this render (dimensions and/or duration) are specified in the format_id. Used for template formats that accept parameters. Mutually exclusive with specifying dimensions object explicitly."
+          },
+          "dimensions": {
+            "type": "object",
+            "description": "Dimensions for this rendered piece (in pixels)",
+            "properties": {
+              "width": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "Fixed width in pixels"
+              },
+              "height": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "Fixed height in pixels"
+              },
+              "min_width": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "Minimum width in pixels for responsive renders"
+              },
+              "min_height": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "Minimum height in pixels for responsive renders"
+              },
+              "max_width": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "Maximum width in pixels for responsive renders"
+              },
+              "max_height": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "Maximum height in pixels for responsive renders"
+              },
+              "responsive": {
+                "type": "object",
+                "description": "Indicates which dimensions are responsive/fluid",
+                "properties": {
+                  "width": {
+                    "type": "boolean"
+                  },
+                  "height": {
+                    "type": "boolean"
+                  }
+                },
+                "required": [
+                  "width",
+                  "height"
+                ]
+              },
+              "aspect_ratio": {
+                "type": "string",
+                "description": "Fixed aspect ratio constraint (e.g., '16:9', '4:3', '1:1')",
+                "pattern": "^\\d+:\\d+$"
+              }
+            }
+          }
+        },
+        "required": [
+          "role"
+        ],
+        "oneOf": [
+          {
+            "required": [
+              "dimensions"
+            ],
+            "not": {
+              "required": [
+                "parameters_from_format_id"
+              ]
+            }
+          },
+          {
+            "required": [
+              "parameters_from_format_id"
+            ],
+            "properties": {
+              "parameters_from_format_id": {
+                "const": true
+              }
+            },
+            "not": {
+              "required": [
+                "dimensions"
+              ]
+            }
+          }
+        ]
+      },
+      "minItems": 1
+    },
+    "assets_required": {
+      "type": "array",
+      "description": "Array of required assets or asset groups for this format. Each asset is identified by its asset_id, which must be used as the key in creative manifests. Can contain individual assets or repeatable asset sequences (e.g., carousel products, slideshow frames).",
+      "items": {
+        "oneOf": [
+          {
+            "description": "Individual asset requirement",
+            "type": "object",
+            "properties": {
+              "item_type": {
+                "type": "string",
+                "const": "individual",
+                "description": "Discriminator indicating this is an individual asset requirement"
+              },
+              "asset_id": {
+                "type": "string",
+                "description": "Unique identifier for this asset. Creative manifests MUST use this exact value as the key in the assets object."
+              },
+              "asset_type": {
+                "$ref": "/schemas/enums/asset-content-type.json",
+                "description": "Type of asset"
+              },
+              "asset_role": {
+                "type": "string",
+                "description": "Optional descriptive label for this asset's purpose (e.g., 'hero_image', 'logo'). Not used for referencing assets in manifests\u2014use asset_id instead. This field is for human-readable documentation and UI display only."
+              },
+              "required": {
+                "type": "boolean",
+                "description": "Whether this asset is required"
+              },
+              "requirements": {
+                "type": "object",
+                "description": "Technical requirements for this asset (dimensions, file size, duration, etc.). For template formats, use parameters_from_format_id: true to indicate asset parameters must match the format_id parameters (width/height/unit and/or duration_ms).",
+                "additionalProperties": true
+              }
+            },
+            "required": [
+              "item_type",
+              "asset_id",
+              "asset_type"
+            ]
+          },
+          {
+            "description": "Repeatable asset group (for carousels, slideshows, playlists, etc.)",
+            "type": "object",
+            "properties": {
+              "item_type": {
+                "type": "string",
+                "const": "repeatable_group",
+                "description": "Discriminator indicating this is a repeatable asset group"
+              },
+              "asset_group_id": {
+                "type": "string",
+                "description": "Identifier for this asset group (e.g., 'product', 'slide', 'card')"
+              },
+              "min_count": {
+                "type": "integer",
+                "description": "Minimum number of repetitions required",
+                "minimum": 1
+              },
+              "max_count": {
+                "type": "integer",
+                "description": "Maximum number of repetitions allowed",
+                "minimum": 1
+              },
+              "assets": {
+                "type": "array",
+                "description": "Assets within each repetition of this group",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "asset_id": {
+                      "type": "string",
+                      "description": "Identifier for this asset within the group"
+                    },
+                    "asset_type": {
+                      "$ref": "/schemas/enums/asset-content-type.json",
+                      "description": "Type of asset"
+                    },
+                    "asset_role": {
+                      "type": "string",
+                      "description": "Optional descriptive label for this asset's purpose (e.g., 'hero_image', 'logo'). Not used for referencing assets in manifests\u2014use asset_id instead. This field is for human-readable documentation and UI display only."
+                    },
+                    "required": {
+                      "type": "boolean",
+                      "description": "Whether this asset is required in each repetition"
+                    },
+                    "requirements": {
+                      "type": "object",
+                      "description": "Technical requirements for this asset. For template formats, use parameters_from_format_id: true to indicate asset parameters must match the format_id parameters (width/height/unit and/or duration_ms).",
+                      "additionalProperties": true
+                    }
+                  },
+                  "required": [
+                    "asset_id",
+                    "asset_type"
+                  ]
+                }
+              }
+            },
+            "required": [
+              "item_type",
+              "asset_group_id",
+              "min_count",
+              "max_count",
+              "assets"
+            ]
+          }
+        ]
+      }
+    },
+    "delivery": {
+      "type": "object",
+      "description": "Delivery method specifications (e.g., hosted, VAST, third-party tags)",
+      "additionalProperties": true
+    },
+    "supported_macros": {
+      "type": "array",
+      "description": "List of universal macros supported by this format (e.g., MEDIA_BUY_ID, CACHEBUSTER, DEVICE_ID). Used for validation and developer tooling.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "output_format_ids": {
+      "type": "array",
+      "description": "For generative formats: array of format IDs that this format can generate. When a format accepts inputs like brand_manifest and message, this specifies what concrete output formats can be produced (e.g., a generative banner format might output standard image banner formats).",
+      "items": {
+        "$ref": "/schemas/core/format-id.json"
+      }
+    },
+    "format_card": {
+      "type": "object",
+      "description": "Optional standard visual card (300x400px) for displaying this format in user interfaces. Can be rendered via preview_creative or pre-generated.",
+      "properties": {
+        "format_id": {
+          "$ref": "/schemas/core/format-id.json",
+          "description": "Creative format defining the card layout (typically format_card_standard)"
+        },
+        "manifest": {
+          "type": "object",
+          "description": "Asset manifest for rendering the card, structure defined by the format",
+          "additionalProperties": true
+        }
+      },
+      "required": [
+        "format_id",
+        "manifest"
+      ],
+      "additionalProperties": true
+    },
+    "format_card_detailed": {
+      "type": "object",
+      "description": "Optional detailed card with carousel and full specifications. Provides rich format documentation similar to ad spec pages.",
+      "properties": {
+        "format_id": {
+          "$ref": "/schemas/core/format-id.json",
+          "description": "Creative format defining the detailed card layout (typically format_card_detailed)"
+        },
+        "manifest": {
+          "type": "object",
+          "description": "Asset manifest for rendering the detailed card, structure defined by the format",
+          "additionalProperties": true
+        }
+      },
+      "required": [
+        "format_id",
+        "manifest"
+      ],
+      "additionalProperties": true
+    }
+  },
+  "required": [
+    "format_id",
+    "name",
+    "type"
+  ],
+  "additionalProperties": true
+}

package/dist/lib/schemas-data/v2.5/core/frequency-cap.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/frequency-cap.json",
+  "title": "Frequency Cap",
+  "description": "Frequency capping settings for package-level application",
+  "type": "object",
+  "properties": {
+    "suppress_minutes": {
+      "type": "number",
+      "description": "Minutes to suppress after impression",
+      "minimum": 0
+    }
+  },
+  "required": [
+    "suppress_minutes"
+  ],
+  "additionalProperties": true
+}

package/dist/lib/schemas-data/v2.5/core/mcp-webhook-payload.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/mcp-webhook-payload.json",
+  "title": "MCP Webhook Payload",
+  "description": "Standard envelope for HTTP-based push notifications (MCP). This defines the wire format sent to the URL configured in `pushNotificationConfig`. NOTE: This envelope is NOT used in A2A integration, which uses native Task/TaskStatusUpdateEvent messages with the AdCP payload nested in `status.message.parts[].data`.",
+  "type": "object",
+  "properties": {
+    "operation_id": {
+      "type": "string",
+      "description": "Publisher-defined operation identifier correlating a sequence of task updates across webhooks."
+    },
+    "task_id": {
+      "type": "string",
+      "description": "Unique identifier for this task. Use this to correlate webhook notifications with the original task submission."
+    },
+    "task_type": {
+      "$ref": "/schemas/enums/task-type.json",
+      "description": "Type of AdCP operation that triggered this webhook. Enables webhook handlers to route to appropriate processing logic."
+    },
+    "domain": {
+      "$ref": "/schemas/enums/adcp-domain.json",
+      "description": "AdCP domain this task belongs to. Helps classify the operation type at a high level."
+    },
+    "status": {
+      "$ref": "/schemas/enums/task-status.json",
+      "description": "Current task status. Webhooks are triggered for status changes after initial submission."
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when this webhook was generated."
+    },
+    "message": {
+      "type": "string",
+      "description": "Human-readable summary of the current task state. Provides context about what happened and what action may be needed."
+    },
+    "context_id": {
+      "type": "string",
+      "description": "Session/conversation identifier. Use this to continue the conversation if input-required status needs clarification or additional parameters."
+    },
+    "result": {
+      "$ref": "/schemas/core/async-response-data.json",
+      "description": "Task-specific payload matching the status. For completed/failed, contains the full task response. For working/input-required/submitted, contains status-specific data. This is the data layer that AdCP specs - same structure used in A2A status.message.parts[].data."
+    }
+  },
+  "required": [
+    "task_id",
+    "task_type",
+    "status",
+    "timestamp"
+  ],
+  "additionalProperties": true,
+  "examples": [
+    {
+      "description": "Webhook for input-required status (human approval needed)",
+      "data": {
+        "operation_id": "op_456",
+        "task_id": "task_456",
+        "task_type": "create_media_buy",
+        "domain": "media-buy",
+        "status": "input-required",
+        "timestamp": "2025-01-22T10:15:00Z",
+        "context_id": "ctx_abc123",
+        "message": "Campaign budget $150K requires VP approval to proceed",
+        "result": {
+          "reason": "BUDGET_EXCEEDS_LIMIT",
+          "errors": [
+            {
+              "code": "APPROVAL_REQUIRED",
+              "message": "Budget exceeds auto-approval threshold",
+              "field": "total_budget"
+            }
+          ]
+        }
+      }
+    },
+    {
+      "description": "Webhook for completed create_media_buy",
+      "data": {
+        "operation_id": "op_456",
+        "task_id": "task_456",
+        "task_type": "create_media_buy",
+        "domain": "media-buy",
+        "status": "completed",
+        "timestamp": "2025-01-22T10:30:00Z",
+        "message": "Media buy created successfully with 2 packages ready for creative assignment",
+        "result": {
+          "media_buy_id": "mb_12345",
+          "buyer_ref": "nike_q1_campaign_2024",
+          "creative_deadline": "2024-01-30T23:59:59Z",
+          "packages": [
+            {
+              "package_id": "pkg_12345_001",
+              "buyer_ref": "nike_ctv_package",
+              "product_id": "ctv_sports_premium",
+              "budget": 60000,
+              "pacing": "even",
+              "pricing_option_id": "cpm-fixed-sports",
+              "paused": false,
+              "creative_assignments": [],
+              "format_ids_to_provide": [
+                {
+                  "agent_url": "https://creative.adcontextprotocol.org",
+                  "id": "video_standard_30s"
+                }
+              ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "description": "Webhook for working status with progress",
+      "data": {
+        "operation_id": "op_456",
+        "task_id": "task_456",
+        "task_type": "create_media_buy",
+        "domain": "media-buy",
+        "status": "working",
+        "timestamp": "2025-01-22T10:20:00Z",
+        "message": "Validating inventory availability...",
+        "result": {
+          "percentage": 50,
+          "current_step": "inventory_validation",
+          "step_number": 2,
+          "total_steps": 4
+        }
+      }
+    },
+    {
+      "description": "Webhook for failed sync_creatives",
+      "data": {
+        "operation_id": "op_789",
+        "task_id": "task_789",
+        "task_type": "sync_creatives",
+        "domain": "media-buy",
+        "status": "failed",
+        "timestamp": "2025-01-22T10:46:00Z",
+        "message": "Creative sync failed due to invalid asset URLs",
+        "result": {
+          "errors": [
+            {
+              "code": "INVALID_ASSET_URL",
+              "message": "One or more creative assets could not be accessed",
+              "field": "creatives[0].asset_url"
+            }
+          ]
+        }
+      }
+    }
+  ]
+}

package/dist/lib/schemas-data/v2.5/core/measurement.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/measurement.json",
+  "title": "Measurement",
+  "description": "Measurement capabilities included with a product",
+  "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": {
+      "type": "string",
+      "description": "Attribution window",
+      "examples": [
+        "30_days",
+        "7_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/v2.5/core/media-buy.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/media-buy.json",
+  "title": "Media Buy",
+  "description": "Represents a purchased advertising campaign",
+  "type": "object",
+  "properties": {
+    "media_buy_id": {
+      "type": "string",
+      "description": "Publisher's unique identifier for the media buy"
+    },
+    "buyer_ref": {
+      "type": "string",
+      "description": "Buyer's reference identifier for this media buy"
+    },
+    "status": {
+      "$ref": "/schemas/enums/media-buy-status.json"
+    },
+    "promoted_offering": {
+      "type": "string",
+      "description": "Description of advertiser and what is being promoted"
+    },
+    "total_budget": {
+      "type": "number",
+      "description": "Total budget amount",
+      "minimum": 0
+    },
+    "packages": {
+      "type": "array",
+      "description": "Array of packages within this media buy",
+      "items": {
+        "$ref": "/schemas/core/package.json"
+      }
+    },
+    "creative_deadline": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp for creative upload deadline"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Creation timestamp"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Last update timestamp"
+    },
+    "ext": {
+      "$ref": "/schemas/core/ext.json"
+    }
+  },
+  "required": [
+    "media_buy_id",
+    "status",
+    "promoted_offering",
+    "total_budget",
+    "packages"
+  ],
+  "additionalProperties": true
+}

package/dist/lib/schemas-data/v2.5/core/package.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/package.json",
+  "title": "Package",
+  "description": "A specific product within a media buy (line item)",
+  "type": "object",
+  "properties": {
+    "package_id": {
+      "type": "string",
+      "description": "Publisher's unique identifier for the package"
+    },
+    "buyer_ref": {
+      "type": "string",
+      "description": "Buyer's reference identifier for this package"
+    },
+    "product_id": {
+      "type": "string",
+      "description": "ID of the product this package is based on"
+    },
+    "budget": {
+      "type": "number",
+      "description": "Budget allocation for this package in the currency specified by the pricing option",
+      "minimum": 0
+    },
+    "pacing": {
+      "$ref": "/schemas/enums/pacing.json"
+    },
+    "pricing_option_id": {
+      "type": "string",
+      "description": "ID of the selected pricing option from the product's pricing_options array"
+    },
+    "bid_price": {
+      "type": "number",
+      "description": "Bid price for auction-based CPM pricing (present if using cpm-auction-option)",
+      "minimum": 0
+    },
+    "impressions": {
+      "type": "number",
+      "description": "Impression goal for this package",
+      "minimum": 0
+    },
+    "targeting_overlay": {
+      "$ref": "/schemas/core/targeting.json"
+    },
+    "creative_assignments": {
+      "type": "array",
+      "description": "Creative assets assigned to this package",
+      "items": {
+        "$ref": "/schemas/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/core/format-id.json"
+      }
+    },
+    "paused": {
+      "type": "boolean",
+      "description": "Whether this package is paused by the buyer. Paused packages do not deliver impressions. Defaults to false.",
+      "default": false
+    },
+    "ext": {
+      "$ref": "/schemas/core/ext.json"
+    }
+  },
+  "required": [
+    "package_id"
+  ],
+  "additionalProperties": true
+}