@adcp/sdk 6.0.0 → 6.2.0

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

@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/property.json",
+  "title": "Property",
+  "description": "An advertising property that can be validated via adagents.json",
+  "type": "object",
+  "properties": {
+    "property_id": {
+      "$ref": "/schemas/core/property-id.json",
+      "description": "Unique identifier for this property (optional). Enables referencing properties by ID instead of repeating full objects."
+    },
+    "property_type": {
+      "$ref": "/schemas/enums/property-type.json",
+      "description": "Type of advertising property"
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable property name"
+    },
+    "identifiers": {
+      "type": "array",
+      "description": "Array of identifiers for this property",
+      "items": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "$ref": "/schemas/enums/identifier-types.json",
+            "description": "Type of identifier for this property"
+          },
+          "value": {
+            "type": "string",
+            "description": "The identifier value. For domain type: 'example.com' matches base domain plus www and m subdomains; 'edition.example.com' matches that specific subdomain; '*.example.com' matches ALL subdomains but NOT base domain"
+          }
+        },
+        "required": [
+          "type",
+          "value"
+        ],
+        "additionalProperties": true
+      },
+      "minItems": 1
+    },
+    "tags": {
+      "type": "array",
+      "description": "Tags for categorization and grouping (e.g., network membership, content categories)",
+      "items": {
+        "$ref": "/schemas/core/property-tag.json"
+      },
+      "uniqueItems": true
+    },
+    "publisher_domain": {
+      "type": "string",
+      "description": "Domain where adagents.json should be checked for authorization validation. Required for list_authorized_properties response. Optional in adagents.json (file location implies domain)."
+    }
+  },
+  "required": [
+    "property_type",
+    "name",
+    "identifiers"
+  ],
+  "additionalProperties": true
+}

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

@@ -0,0 +1,146 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/protocol-envelope.json",
+  "title": "Protocol Envelope",
+  "description": "Standard envelope structure for AdCP task responses. This envelope is added by the protocol layer (MCP, A2A, REST) and wraps the task-specific response payload. Task response schemas should NOT include these fields - they are protocol-level concerns.",
+  "type": "object",
+  "properties": {
+    "context_id": {
+      "type": "string",
+      "description": "Session/conversation identifier for tracking related operations across multiple task invocations. Managed by the protocol layer to maintain conversational context."
+    },
+    "task_id": {
+      "type": "string",
+      "description": "Unique identifier for tracking asynchronous operations. Present when a task requires extended processing time. Used to query task status and retrieve results when complete."
+    },
+    "status": {
+      "$ref": "/schemas/enums/task-status.json",
+      "description": "Current task execution state. Indicates whether the task is completed, in progress (working), submitted for async processing, failed, or requires user input. Managed by the protocol layer."
+    },
+    "message": {
+      "type": "string",
+      "description": "Human-readable summary of the task result. Provides natural language explanation of what happened, suitable for display to end users or for AI agent comprehension. Generated by the protocol layer based on the task response."
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when the response was generated. Useful for debugging, logging, cache validation, and tracking async operation progress."
+    },
+    "push_notification_config": {
+      "$ref": "/schemas/core/push-notification-config.json",
+      "description": "Push notification configuration for async task updates (A2A and REST protocols). Echoed from the request to confirm webhook settings. Specifies URL, authentication scheme (Bearer or HMAC-SHA256), and credentials. MCP uses progress notifications instead of webhooks."
+    },
+    "payload": {
+      "type": "object",
+      "description": "The actual task-specific response data. This is the content defined in individual task response schemas (e.g., get-products-response.json, create-media-buy-response.json). Contains only domain-specific data without protocol-level fields.",
+      "additionalProperties": true
+    }
+  },
+  "required": [
+    "status",
+    "payload"
+  ],
+  "additionalProperties": true,
+  "examples": [
+    {
+      "description": "Synchronous task response with immediate results",
+      "data": {
+        "context_id": "ctx_abc123",
+        "status": "completed",
+        "message": "Found 3 products matching your criteria for CTV inventory in California",
+        "timestamp": "2025-10-14T14:25:30Z",
+        "payload": {
+          "products": [
+            {
+              "product_id": "ctv_premium_ca",
+              "name": "CTV Premium - California",
+              "description": "Premium connected TV inventory across California",
+              "pricing": {
+                "model": "cpm",
+                "amount": 45.0,
+                "currency": "USD"
+              }
+            }
+          ]
+        }
+      }
+    },
+    {
+      "description": "Asynchronous task response with pending operation",
+      "data": {
+        "context_id": "ctx_def456",
+        "task_id": "task_789",
+        "status": "submitted",
+        "message": "Media buy creation submitted. Processing will take approximately 5-10 minutes. You'll receive updates via webhook.",
+        "timestamp": "2025-10-14T14:30:00Z",
+        "push_notification_config": {
+          "url": "https://buyer.example.com/webhooks/adcp",
+          "authentication": {
+            "schemes": [
+              "HMAC-SHA256"
+            ],
+            "credentials": "shared_secret_exchanged_during_onboarding_min_32_chars"
+          }
+        },
+        "payload": {
+          "buyer_ref": "campaign_2024_q1"
+        }
+      }
+    },
+    {
+      "description": "Task response requiring user input",
+      "data": {
+        "context_id": "ctx_ghi789",
+        "task_id": "task_101",
+        "status": "input-required",
+        "message": "This media buy requires manual approval. Please review the terms and confirm to proceed.",
+        "timestamp": "2025-10-14T14:32:15Z",
+        "payload": {
+          "media_buy_id": "mb_123456",
+          "buyer_ref": "campaign_2024_q1",
+          "packages": [
+            {
+              "package_id": "pkg_001",
+              "buyer_ref": "pkg_premium_ctv"
+            }
+          ],
+          "errors": [
+            {
+              "code": "APPROVAL_REQUIRED",
+              "message": "Budget exceeds auto-approval threshold",
+              "severity": "warning"
+            }
+          ]
+        }
+      }
+    },
+    {
+      "description": "Failed task response with error details",
+      "data": {
+        "context_id": "ctx_jkl012",
+        "status": "failed",
+        "message": "Unable to create media buy due to invalid targeting parameters",
+        "timestamp": "2025-10-14T14:28:45Z",
+        "payload": {
+          "errors": [
+            {
+              "code": "INVALID_TARGETING",
+              "message": "Geographic targeting codes are invalid",
+              "field": "targeting.geo_codes",
+              "severity": "error"
+            }
+          ]
+        }
+      }
+    }
+  ],
+  "notes": [
+    "Task response schemas (e.g., get-products-response.json) define ONLY the payload structure",
+    "Protocol implementations (MCP, A2A, REST) wrap the payload with this envelope",
+    "Different protocols may use different serialization formats but maintain the same semantic structure",
+    "MCP may represent this via tool response content fields and metadata",
+    "A2A may represent this via assistant messages with structured data",
+    "REST may use HTTP headers for status/task metadata and JSON body for payload",
+    "The envelope ensures consistent behavior across all protocol implementations"
+  ]
+}

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

@@ -0,0 +1,92 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/publisher-property-selector.json",
+  "title": "Publisher Property Selector",
+  "description": "Selects properties from a publisher's adagents.json. Used for both product definitions and agent authorization. Supports three selection patterns: all properties, specific IDs, or by tags.",
+  "discriminator": {
+    "propertyName": "selection_type"
+  },
+  "oneOf": [
+    {
+      "type": "object",
+      "description": "Select all properties from the publisher domain",
+      "properties": {
+        "publisher_domain": {
+          "type": "string",
+          "description": "Domain where publisher's adagents.json is hosted (e.g., 'cnn.com')",
+          "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$"
+        },
+        "selection_type": {
+          "type": "string",
+          "const": "all",
+          "description": "Discriminator indicating all properties from this publisher are included"
+        }
+      },
+      "required": [
+        "publisher_domain",
+        "selection_type"
+      ],
+      "additionalProperties": true
+    },
+    {
+      "type": "object",
+      "description": "Select specific properties by ID",
+      "properties": {
+        "publisher_domain": {
+          "type": "string",
+          "description": "Domain where publisher's adagents.json is hosted (e.g., 'cnn.com')",
+          "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$"
+        },
+        "selection_type": {
+          "type": "string",
+          "const": "by_id",
+          "description": "Discriminator indicating selection by specific property IDs"
+        },
+        "property_ids": {
+          "type": "array",
+          "description": "Specific property IDs from the publisher's adagents.json",
+          "items": {
+            "$ref": "/schemas/core/property-id.json"
+          },
+          "minItems": 1
+        }
+      },
+      "required": [
+        "publisher_domain",
+        "selection_type",
+        "property_ids"
+      ],
+      "additionalProperties": true
+    },
+    {
+      "type": "object",
+      "description": "Select properties by tag membership",
+      "properties": {
+        "publisher_domain": {
+          "type": "string",
+          "description": "Domain where publisher's adagents.json is hosted (e.g., 'cnn.com')",
+          "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$"
+        },
+        "selection_type": {
+          "type": "string",
+          "const": "by_tag",
+          "description": "Discriminator indicating selection by property tags"
+        },
+        "property_tags": {
+          "type": "array",
+          "description": "Property tags from the publisher's adagents.json. Selector covers all properties with these tags",
+          "items": {
+            "$ref": "/schemas/core/property-tag.json"
+          },
+          "minItems": 1
+        }
+      },
+      "required": [
+        "publisher_domain",
+        "selection_type",
+        "property_tags"
+      ],
+      "additionalProperties": true
+    }
+  ]
+}

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

@@ -0,0 +1,48 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/push-notification-config.json",
+  "title": "Push Notification Config",
+  "description": "Webhook configuration for asynchronous task notifications. Uses A2A-compatible PushNotificationConfig structure. Supports Bearer tokens (simple) or HMAC signatures (production-recommended). This schema is designed for composition via allOf - consuming schemas should define their own additionalProperties constraints.",
+  "type": "object",
+  "properties": {
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Webhook endpoint URL for task status notifications"
+    },
+    "token": {
+      "type": "string",
+      "description": "Optional client-provided token for webhook validation. Echoed back in webhook payload to validate request authenticity.",
+      "minLength": 16
+    },
+    "authentication": {
+      "type": "object",
+      "description": "Authentication configuration for webhook delivery (A2A-compatible)",
+      "properties": {
+        "schemes": {
+          "type": "array",
+          "description": "Array of authentication schemes. Supported: ['Bearer'] for simple token auth, ['HMAC-SHA256'] for signature verification (recommended for production)",
+          "items": {
+            "$ref": "/schemas/enums/auth-scheme.json"
+          },
+          "minItems": 1,
+          "maxItems": 1
+        },
+        "credentials": {
+          "type": "string",
+          "description": "Credentials for authentication. For Bearer: token sent in Authorization header. For HMAC-SHA256: shared secret used to generate signature. Minimum 32 characters. Exchanged out-of-band during onboarding.",
+          "minLength": 32
+        }
+      },
+      "required": [
+        "schemes",
+        "credentials"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "url",
+    "authentication"
+  ]
+}

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

@@ -0,0 +1,71 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/reporting-capabilities.json",
+  "title": "Reporting Capabilities",
+  "description": "Reporting capabilities available for a product",
+  "type": "object",
+  "properties": {
+    "available_reporting_frequencies": {
+      "type": "array",
+      "description": "Supported reporting frequency options",
+      "items": {
+        "$ref": "/schemas/enums/reporting-frequency.json"
+      },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "expected_delay_minutes": {
+      "type": "integer",
+      "description": "Expected delay in minutes before reporting data becomes available (e.g., 240 for 4-hour delay)",
+      "minimum": 0,
+      "examples": [
+        240,
+        300,
+        1440
+      ]
+    },
+    "timezone": {
+      "type": "string",
+      "description": "Timezone for reporting periods. Use 'UTC' or IANA timezone (e.g., 'America/New_York'). Critical for daily/monthly frequency alignment.",
+      "examples": [
+        "UTC",
+        "America/New_York",
+        "Europe/London",
+        "America/Los_Angeles"
+      ]
+    },
+    "supports_webhooks": {
+      "type": "boolean",
+      "description": "Whether this product supports webhook-based reporting notifications"
+    },
+    "available_metrics": {
+      "type": "array",
+      "description": "Metrics available in reporting. Impressions and spend are always implicitly included.",
+      "items": {
+        "$ref": "/schemas/enums/available-metric.json"
+      },
+      "uniqueItems": true,
+      "examples": [
+        [
+          "impressions",
+          "spend",
+          "clicks",
+          "video_completions"
+        ],
+        [
+          "impressions",
+          "spend",
+          "conversions"
+        ]
+      ]
+    }
+  },
+  "required": [
+    "available_reporting_frequencies",
+    "expected_delay_minutes",
+    "timezone",
+    "supports_webhooks",
+    "available_metrics"
+  ],
+  "additionalProperties": true
+}

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

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/response.json",
+  "title": "Protocol Response",
+  "description": "Protocol-level response wrapper (MCP/A2A) - contains AdCP task data plus protocol fields",
+  "type": "object",
+  "properties": {
+    "message": {
+      "type": "string",
+      "description": "Human-readable summary"
+    },
+    "context_id": {
+      "type": "string",
+      "description": "Session continuity identifier"
+    },
+    "data": {
+      "description": "AdCP task-specific response data (see individual task response schemas)"
+    }
+  },
+  "required": [
+    "message"
+  ],
+  "additionalProperties": true
+}

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

@@ -0,0 +1,35 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/signal-filters.json",
+  "title": "Signal Filters",
+  "description": "Filters to refine signal discovery results",
+  "type": "object",
+  "properties": {
+    "catalog_types": {
+      "type": "array",
+      "description": "Filter by catalog type",
+      "items": {
+        "$ref": "/schemas/enums/signal-catalog-type.json"
+      }
+    },
+    "data_providers": {
+      "type": "array",
+      "description": "Filter by specific data providers",
+      "items": {
+        "type": "string"
+      }
+    },
+    "max_cpm": {
+      "type": "number",
+      "description": "Maximum CPM price filter",
+      "minimum": 0
+    },
+    "min_coverage_percentage": {
+      "type": "number",
+      "description": "Minimum coverage requirement",
+      "minimum": 0,
+      "maximum": 100
+    }
+  },
+  "additionalProperties": true
+}

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

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/start-timing.json",
+  "title": "Start Timing",
+  "description": "Campaign start timing: 'asap' or ISO 8601 date-time",
+  "oneOf": [
+    {
+      "type": "string",
+      "const": "asap",
+      "description": "Start campaign as soon as possible"
+    },
+    {
+      "type": "string",
+      "format": "date-time",
+      "description": "Scheduled start date/time in ISO 8601 format"
+    }
+  ]
+}

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

@@ -0,0 +1,79 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/sub-asset.json",
+  "title": "Sub-Asset",
+  "description": "Sub-asset for multi-asset creative formats, including carousel images and native ad template variables",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "asset_kind": {
+          "type": "string",
+          "const": "media",
+          "description": "Discriminator indicating this is a media asset with content_uri"
+        },
+        "asset_type": {
+          "type": "string",
+          "description": "Type of asset. Common types: thumbnail_image, product_image, featured_image, logo"
+        },
+        "asset_id": {
+          "type": "string",
+          "description": "Unique identifier for the asset within the creative"
+        },
+        "content_uri": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL for media assets (images, videos, etc.)"
+        }
+      },
+      "required": [
+        "asset_kind",
+        "asset_type",
+        "asset_id",
+        "content_uri"
+      ],
+      "additionalProperties": true
+    },
+    {
+      "type": "object",
+      "properties": {
+        "asset_kind": {
+          "type": "string",
+          "const": "text",
+          "description": "Discriminator indicating this is a text asset with content"
+        },
+        "asset_type": {
+          "type": "string",
+          "description": "Type of asset. Common types: headline, body_text, cta_text, price_text, sponsor_name, author_name, click_url"
+        },
+        "asset_id": {
+          "type": "string",
+          "description": "Unique identifier for the asset within the creative"
+        },
+        "content": {
+          "oneOf": [
+            {
+              "type": "string",
+              "description": "Single text content value"
+            },
+            {
+              "type": "array",
+              "description": "Multiple text content values (for A/B testing or variations)",
+              "items": {
+                "type": "string"
+              }
+            }
+          ],
+          "description": "Text content for text-based assets like headlines, body text, CTA text, etc."
+        }
+      },
+      "required": [
+        "asset_kind",
+        "asset_type",
+        "asset_id",
+        "content"
+      ],
+      "additionalProperties": true
+    }
+  ]
+}

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

@@ -0,0 +1,50 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/targeting.json",
+  "title": "Targeting Overlay",
+  "description": "Optional geographic refinements for media buys. Most targeting should be expressed in the brief and handled by the publisher. These fields are primarily for geographic restrictions (RCT testing, regulatory compliance).",
+  "type": "object",
+  "properties": {
+    "geo_country_any_of": {
+      "type": "array",
+      "description": "Restrict delivery to specific countries (ISO codes). Use for regulatory compliance or RCT testing.",
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Z]{2}$"
+      }
+    },
+    "geo_region_any_of": {
+      "type": "array",
+      "description": "Restrict delivery to specific regions/states. Use for regulatory compliance or RCT testing.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "geo_metro_any_of": {
+      "type": "array",
+      "description": "Restrict delivery to specific metro areas (DMA codes). Use for regulatory compliance or RCT testing.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "geo_postal_code_any_of": {
+      "type": "array",
+      "description": "Restrict delivery to specific postal/ZIP codes. Use for regulatory compliance or RCT testing.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "axe_include_segment": {
+      "type": "string",
+      "description": "AXE segment ID to include for targeting"
+    },
+    "axe_exclude_segment": {
+      "type": "string",
+      "description": "AXE segment ID to exclude from targeting"
+    },
+    "frequency_cap": {
+      "$ref": "/schemas/core/frequency-cap.json"
+    }
+  },
+  "additionalProperties": true
+}

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

@@ -0,0 +1,43 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/core/tasks-get-request.json",
+  "title": "Tasks Get Request",
+  "description": "Request parameters for retrieving a specific task by ID with optional conversation history across all AdCP domains",
+  "type": "object",
+  "properties": {
+    "task_id": {
+      "type": "string",
+      "description": "Unique identifier of the task to retrieve"
+    },
+    "include_history": {
+      "type": "boolean",
+      "default": false,
+      "description": "Include full conversation history for this task (may increase response size)"
+    },
+    "context": {
+      "$ref": "/schemas/core/context.json"
+    },
+    "ext": {
+      "$ref": "/schemas/core/ext.json"
+    }
+  },
+  "required": [
+    "task_id"
+  ],
+  "additionalProperties": true,
+  "examples": [
+    {
+      "description": "Check task status",
+      "data": {
+        "task_id": "task_456"
+      }
+    },
+    {
+      "description": "Get task with full conversation history",
+      "data": {
+        "task_id": "task_123",
+        "include_history": true
+      }
+    }
+  ]
+}