@adcp/sdk 5.23.0

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

@@ -0,0 +1,199 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/3.0.1/core/job-item.json",
+  "title": "Job Item",
+  "description": "A job posting within a job-type catalog. Carries the position details that platforms use for job ads and recruitment campaigns. Maps to LinkedIn Jobs XML, Google DynamicJobsAsset, schema.org JobPosting, and similar formats.",
+  "type": "object",
+  "properties": {
+    "job_id": {
+      "type": "string",
+      "description": "Unique identifier for this job posting."
+    },
+    "title": {
+      "type": "string",
+      "description": "Job title (e.g., 'Senior Software Engineer', 'Marketing Manager')."
+    },
+    "company_name": {
+      "type": "string",
+      "description": "Hiring company or organization name."
+    },
+    "description": {
+      "type": "string",
+      "description": "Full job description including responsibilities and qualifications."
+    },
+    "location": {
+      "type": "string",
+      "description": "Job location as a display string (e.g., 'Amsterdam, NL', 'Remote', 'New York, NY'). Use 'Remote' for fully remote positions."
+    },
+    "employment_type": {
+      "type": "string",
+      "enum": [
+        "full_time",
+        "part_time",
+        "contract",
+        "temporary",
+        "internship",
+        "freelance"
+      ],
+      "description": "Type of employment."
+    },
+    "experience_level": {
+      "type": "string",
+      "enum": [
+        "entry_level",
+        "mid_level",
+        "senior",
+        "director",
+        "executive"
+      ],
+      "description": "Required experience level."
+    },
+    "salary": {
+      "type": "object",
+      "description": "Salary range. Specify min and/or max with currency and period.",
+      "properties": {
+        "min": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Minimum salary."
+        },
+        "max": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Maximum salary."
+        },
+        "currency": {
+          "type": "string",
+          "pattern": "^[A-Z]{3}$",
+          "description": "ISO 4217 currency code."
+        },
+        "period": {
+          "type": "string",
+          "enum": [
+            "hour",
+            "month",
+            "year"
+          ],
+          "description": "Pay period."
+        }
+      },
+      "required": [
+        "currency",
+        "period"
+      ],
+      "additionalProperties": false
+    },
+    "date_posted": {
+      "type": "string",
+      "format": "date",
+      "description": "Date the job was posted (ISO 8601 date)."
+    },
+    "valid_through": {
+      "type": "string",
+      "format": "date",
+      "description": "Application deadline (ISO 8601 date)."
+    },
+    "apply_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Direct application URL."
+    },
+    "job_functions": {
+      "type": "array",
+      "description": "Job function categories (e.g., 'engineering', 'marketing', 'sales', 'finance').",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1
+    },
+    "industries": {
+      "type": "array",
+      "description": "Industry classifications (e.g., 'technology', 'healthcare', 'retail').",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1
+    },
+    "tags": {
+      "type": "array",
+      "description": "Tags for filtering (e.g., 'remote', 'visa-sponsorship', 'equity').",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1
+    },
+    "assets": {
+      "type": "array",
+      "description": "Typed creative asset pools for this job. Uses the same OfferingAssetGroup structure as offering-type catalogs. Standard group IDs: 'images_landscape' (company/role hero), 'images_vertical' (9:16 for Stories), 'logo' (company logo). Enables formats to declare typed image requirements that map unambiguously to the right asset regardless of platform.",
+      "items": {
+        "$ref": "/schemas/3.0.1/core/offering-asset-group.json"
+      },
+      "minItems": 1
+    },
+    "ext": {
+      "$ref": "/schemas/3.0.1/core/ext.json"
+    }
+  },
+  "required": [
+    "job_id",
+    "title",
+    "company_name",
+    "description"
+  ],
+  "additionalProperties": true,
+  "examples": [
+    {
+      "description": "Senior engineering role",
+      "data": {
+        "job_id": "eng-sr-2025-042",
+        "title": "Senior Software Engineer",
+        "company_name": "Acme Corp",
+        "description": "We're looking for a senior engineer to lead our platform team. You'll design and build distributed systems serving millions of daily requests.",
+        "location": "Amsterdam, NL",
+        "employment_type": "full_time",
+        "experience_level": "senior",
+        "salary": {
+          "min": 80000,
+          "max": 110000,
+          "currency": "EUR",
+          "period": "year"
+        },
+        "date_posted": "2025-06-01",
+        "valid_through": "2025-08-01",
+        "apply_url": "https://acmecorp.com/careers/eng-sr-2025-042",
+        "job_functions": [
+          "engineering"
+        ],
+        "industries": [
+          "technology"
+        ],
+        "tags": [
+          "visa-sponsorship",
+          "equity"
+        ]
+      }
+    },
+    {
+      "description": "Remote contract role",
+      "data": {
+        "job_id": "mkt-contract-099",
+        "title": "Content Marketing Specialist",
+        "company_name": "Nova Brands",
+        "description": "6-month contract to develop and execute content strategy across owned channels.",
+        "location": "Remote",
+        "employment_type": "contract",
+        "salary": {
+          "min": 5000,
+          "max": 7000,
+          "currency": "USD",
+          "period": "month"
+        },
+        "apply_url": "https://novabrands.com/careers/mkt-099",
+        "tags": [
+          "remote",
+          "contract"
+        ]
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/3.0.1/core/limited-series.json",
+  "title": "Limited Series",
+  "description": "A bounded content run with a defined arc. Indicates the collection has a planned beginning, end, and installment count — distinguishing it from ongoing series.",
+  "type": "object",
+  "properties": {
+    "total_installments": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Planned number of installments in the series"
+    },
+    "starts": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the series begins (ISO 8601)"
+    },
+    "ends": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the series ends (ISO 8601)"
+    }
+  },
+  "required": [
+    "total_installments"
+  ],
+  "additionalProperties": true
+}

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

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/3.0.1/core/material-deadline.json",
+  "title": "Material Deadline",
+  "description": "A deadline for creative material submission. Sellers declare stages to distinguish draft materials (e.g., talking points, raw artwork) from production-ready assets (e.g., approved scripts, press-ready PDFs).",
+  "type": "object",
+  "properties": {
+    "stage": {
+      "type": "string",
+      "description": "Submission stage identifier. Use 'draft' for materials that need seller processing and 'final' for production-ready assets. Sellers may define additional stages.",
+      "examples": [
+        "draft",
+        "final"
+      ]
+    },
+    "due_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When materials for this stage are due (ISO 8601)"
+    },
+    "label": {
+      "type": "string",
+      "description": "What the seller needs at this stage (e.g., 'Talking points and brand guidelines', 'Press-ready PDF with bleed')"
+    }
+  },
+  "required": [
+    "stage",
+    "due_at"
+  ],
+  "additionalProperties": true
+}

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

@@ -0,0 +1,163 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/3.0.1/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": {
+    "idempotency_key": {
+      "type": "string",
+      "description": "Sender-generated key stable across retries of the same webhook event. Publishers MUST generate a cryptographically random value (UUID v4 recommended) per distinct event and reuse the same key on every retry of that event. Receivers MUST dedupe by this key, scoped to the authenticated sender identity (HMAC secret or Bearer credential) — keys from different publishers are independent. This is the canonical dedup field — the (task_id, status, timestamp) tuple is insufficient when a single transition is retried with unchanged timestamp or when two transitions share a timestamp.",
+      "minLength": 16,
+      "maxLength": 255,
+      "pattern": "^[A-Za-z0-9_.:-]{16,255}$"
+    },
+    "operation_id": {
+      "type": "string",
+      "description": "Client-generated identifier that was embedded in the webhook URL by the buyer. Publishers echo this back in webhook payloads so clients can correlate notifications without parsing URL paths. Typically generated as a unique ID per task invocation."
+    },
+    "task_id": {
+      "type": "string",
+      "description": "Unique identifier for this task. Use this to correlate webhook notifications with the original task submission.",
+      "x-entity": "task"
+    },
+    "task_type": {
+      "$ref": "/schemas/3.0.1/enums/task-type.json",
+      "description": "Type of AdCP operation that triggered this webhook. Enables webhook handlers to route to appropriate processing logic."
+    },
+    "protocol": {
+      "$ref": "/schemas/3.0.1/enums/adcp-protocol.json",
+      "description": "AdCP protocol this task belongs to. Helps classify the operation type at a high level."
+    },
+    "status": {
+      "$ref": "/schemas/3.0.1/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/3.0.1/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": [
+    "idempotency_key",
+    "task_id",
+    "task_type",
+    "status",
+    "timestamp"
+  ],
+  "additionalProperties": true,
+  "examples": [
+    {
+      "description": "Webhook for input-required status (human approval needed)",
+      "data": {
+        "idempotency_key": "whk_01HW9D2T3VXQ5M7K9N1P3R5S7U",
+        "operation_id": "op_456",
+        "task_id": "task_456",
+        "task_type": "create_media_buy",
+        "protocol": "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": {
+        "idempotency_key": "whk_01HW9D3H8FZP2N6R8T0V4X6Z9B",
+        "operation_id": "op_456",
+        "task_id": "task_456",
+        "task_type": "create_media_buy",
+        "protocol": "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",
+          "creative_deadline": "2024-01-30T23:59:59Z",
+          "packages": [
+            {
+              "package_id": "pkg_12345_001",
+              "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": {
+        "idempotency_key": "whk_01HW9D4K5RMS7P8T2V4X6Z8B0D",
+        "operation_id": "op_456",
+        "task_id": "task_456",
+        "task_type": "create_media_buy",
+        "protocol": "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": {
+        "idempotency_key": "whk_01HW9D5N9TQV4M6P8R0T2V4X6Z",
+        "operation_id": "op_789",
+        "task_id": "task_789",
+        "task_type": "sync_creatives",
+        "protocol": "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/3.0.1/core/measurement-readiness.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/3.0.1/core/measurement-readiness.json",
+  "title": "Measurement Readiness",
+  "description": "Per-product assessment of whether the buyer's event source setup is sufficient for the product's optimization capabilities. Sellers evaluate this in the context of the buyer's account — the same product may show different readiness for different buyers depending on their event source configuration.",
+  "type": "object",
+  "properties": {
+    "status": {
+      "$ref": "/schemas/3.0.1/enums/assessment-status.json",
+      "description": "Overall measurement readiness level for this product given the buyer's event setup. 'insufficient' means the product cannot optimize effectively with the current setup."
+    },
+    "required_event_types": {
+      "type": "array",
+      "description": "Event types this product needs for effective optimization. Buyers should ensure their event sources cover these types.",
+      "items": {
+        "$ref": "/schemas/3.0.1/enums/event-type.json"
+      },
+      "minItems": 1
+    },
+    "missing_event_types": {
+      "type": "array",
+      "description": "Event types this product requires that the buyer has not configured. Empty or absent when all required types are covered.",
+      "items": {
+        "$ref": "/schemas/3.0.1/enums/event-type.json"
+      }
+    },
+    "issues": {
+      "type": "array",
+      "description": "Actionable issues preventing full measurement readiness. Sellers should limit to the top 3-5 most actionable items. Buyer agents should sort by severity rather than relying on array position.",
+      "items": {
+        "$ref": "/schemas/3.0.1/core/diagnostic-issue.json"
+      }
+    },
+    "notes": {
+      "type": "string",
+      "description": "Seller explanation of the readiness assessment, recommendations for improvement, or context about what the buyer needs to change."
+    }
+  },
+  "required": [
+    "status"
+  ],
+  "additionalProperties": true
+}

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

@@ -0,0 +1,63 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/3.0.1/core/measurement-terms.json",
+  "title": "Measurement Terms",
+  "description": "Billing measurement and makegood terms for media buys. Declares who counts the billing metric and what remedies apply when thresholds are breached. Appears on products (seller defaults), package requests (buyer proposals), and confirmed packages (agreed terms). All fields are optional — presence indicates the term is declared or proposed.",
+  "type": "object",
+  "properties": {
+    "billing_measurement": {
+      "type": "object",
+      "description": "Which vendor's count of the billing metric governs invoicing. The billing metric is determined by the pricing_model on the selected pricing_option (e.g., impressions for CPM, completed views for CPCV).",
+      "properties": {
+        "vendor": {
+          "$ref": "/schemas/3.0.1/core/brand-ref.json",
+          "description": "Vendor whose measurement of the billing metric is authoritative for invoicing (e.g., { domain: 'campaignmanager.google.com' } for buyer's DCM, { domain: 'admanager.google.com' } for seller's GAM)."
+        },
+        "max_variance_percent": {
+          "type": "number",
+          "minimum": 0,
+          "exclusiveMaximum": 100,
+          "description": "Maximum acceptable variance between the billing vendor's count and the other party's count before resolution is triggered (e.g., 10 means a 10% divergence triggers review)."
+        },
+        "measurement_window": {
+          "type": "string",
+          "description": "Which measurement maturation stage the billing metric is reconciled against. References a window_id from the product's reporting_capabilities.measurement_windows. Examples: 'c7' for broadcast TV guarantees (live + 7 days DVR), 'final' for DOOH after IVT/fraud-check processing, 'post_sivt' for digital after sophisticated invalid-traffic filtering, 'downloads_30d' for podcast. When absent, billing is based on the seller's standard reporting without windowed maturation.",
+          "examples": [
+            "live",
+            "c3",
+            "c7",
+            "tentative",
+            "final",
+            "post_ivt",
+            "post_sivt",
+            "downloads_30d"
+          ]
+        }
+      },
+      "required": [
+        "vendor"
+      ],
+      "additionalProperties": true
+    },
+    "makegood_policy": {
+      "type": "object",
+      "description": "Remedies available when a performance standard or billing measurement variance is breached. Seller declares which remedy types they support. When a breach occurs, the seller proposes a remedy from this menu; the buyer accepts or disputes.",
+      "properties": {
+        "available_remedies": {
+          "type": "array",
+          "description": "Remedy types the seller supports. Ordered by seller preference (first = preferred). Seller proposes from this list when a breach occurs; buyer accepts or disputes.",
+          "items": {
+            "$ref": "/schemas/3.0.1/enums/makegood-remedy.json"
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      },
+      "required": [
+        "available_remedies"
+      ],
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

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

@@ -0,0 +1,54 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/3.0.1/core/measurement-window.json",
+  "title": "Measurement Window",
+  "description": "A measurement maturation stage for any channel where billing-grade data is produced in phases rather than arriving final on day one. Each window represents an accumulation or processing stage with its own expected availability. Examples: broadcast/linear TV (live → C3 → C7 DVR accumulation), DOOH (tentative plays → post-IVT/fraud-check final), digital (raw impressions → GIVT filtered → SIVT filtered), podcast (7-day downloads → 30-day downloads), audio/radio (tentative → diary/panel-certified). Sellers whose data is final on first delivery omit this.",
+  "type": "object",
+  "properties": {
+    "window_id": {
+      "type": "string",
+      "maxLength": 50,
+      "description": "Identifier for this maturation stage. Standard broadcast values: 'live' (real-time viewers only), 'c3' (live + 3 days time-shifted), 'c7' (live + 7 days time-shifted). Standard values for other channels include 'tentative' (provisional data available quickly), 'final' (post-processing certified data), 'post_ivt' (digital after invalid-traffic filtering), 'post_sivt' (digital after sophisticated-IVT filtering), 'downloads_7d' / 'downloads_30d' (podcast download maturation). Sellers may define custom IDs.",
+      "examples": [
+        "live",
+        "c3",
+        "c7",
+        "tentative",
+        "final",
+        "post_ivt",
+        "downloads_30d"
+      ]
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Human-readable description of what this window measures",
+      "examples": [
+        "Live broadcast impressions only",
+        "Live plus 7 days of time-shifted viewing",
+        "Tentative plays before IVT and fraud-check processing",
+        "Final plays after IVT and fraud-check processing",
+        "Impressions after sophisticated invalid-traffic filtering"
+      ]
+    },
+    "duration_days": {
+      "type": "integer",
+      "description": "Number of days of accumulation included in this window before processing begins. For broadcast, this is DVR accumulation (0 = live only, 3 = live + 3 days DVR, 7 = live + 7 days DVR). For channels without an accumulation period (DOOH tentative→final, digital IVT filtering), this is 0 — maturation is entirely vendor processing time captured in expected_availability_days.",
+      "minimum": 0
+    },
+    "expected_availability_days": {
+      "type": "integer",
+      "description": "Expected number of days after delivery before this window's data is available from the measurement vendor. Captures accumulation time plus vendor processing time. Examples: broadcast C7 from VideoAmp ~22 days (7-day accumulation + ~15-day processing); DOOH tentative plays same-day; DOOH final (post-IVT/fraud-check) ~1 day; digital post-SIVT ~2–3 days.",
+      "minimum": 0
+    },
+    "is_guarantee_basis": {
+      "type": "boolean",
+      "description": "Whether this window is the basis for delivery guarantees, reconciliation, and invoicing. A product typically has one guarantee basis window (e.g., C7 for most US broadcast, post-IVT final for DOOH). Buyers reconcile against the guarantee basis window's final numbers."
+    }
+  },
+  "required": [
+    "window_id",
+    "duration_days"
+  ],
+  "additionalProperties": true
+}

package/dist/lib/schemas-data/3.0.1/core/media-buy-features.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/3.0.1/core/media-buy-features.json",
+  "title": "Media Buy Features",
+  "description": "Optional media-buy protocol features. Used in capability declarations (seller declares support) and product filters (buyer requires support). If a seller declares a feature as true, they MUST honor requests using that feature.",
+  "type": "object",
+  "properties": {
+    "inline_creative_management": {
+      "type": "boolean",
+      "description": "Supports creatives provided inline in create_media_buy requests"
+    },
+    "property_list_filtering": {
+      "type": "boolean",
+      "description": "Honors property_list parameter in get_products to filter results to buyer-approved properties"
+    },
+    "catalog_management": {
+      "type": "boolean",
+      "description": "Supports sync_catalogs task for catalog feed management with platform review and approval"
+    }
+  },
+  "additionalProperties": {
+    "type": "boolean"
+  }
+}