@adcp/sdk 5.23.0

package/dist/lib/schemas-data/3.0.1/account/report-usage-response.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/3.0.1/account/report-usage-response.json",
+  "title": "Report Usage Response",
+  "description": "Response from report_usage. Partial acceptance is valid — records that pass validation are stored even when others fail.",
+  "type": "object",
+  "properties": {
+    "accepted": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Number of usage records successfully stored."
+    },
+    "errors": {
+      "type": "array",
+      "description": "Validation errors for individual records. The field property identifies which record failed (e.g., 'usage[1].pricing_option_id').",
+      "items": {
+        "$ref": "/schemas/3.0.1/core/error.json"
+      }
+    },
+    "sandbox": {
+      "type": "boolean",
+      "description": "When true, the account is a sandbox account and no billing occurred."
+    },
+    "context": {
+      "$ref": "/schemas/3.0.1/core/context.json"
+    },
+    "ext": {
+      "$ref": "/schemas/3.0.1/core/ext.json"
+    }
+  },
+  "required": [
+    "accepted"
+  ],
+  "additionalProperties": true,
+  "examples": [
+    {
+      "description": "All records accepted",
+      "data": {
+        "accepted": 2
+      }
+    },
+    {
+      "description": "Partial acceptance — one record failed validation",
+      "data": {
+        "accepted": 1,
+        "errors": [
+          {
+            "code": "INVALID_PRICING_OPTION",
+            "message": "pricing_option_id 'po_unknown' does not exist on this account",
+            "field": "usage[1].pricing_option_id"
+          }
+        ]
+      }
+    }
+  ]
+}

package/dist/lib/schemas-data/3.0.1/account/sync-accounts-request.json

@@ -0,0 +1,201 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/3.0.1/account/sync-accounts-request.json",
+  "title": "Sync Accounts Request",
+  "description": "Sync advertiser accounts with a seller using upsert semantics. The agent declares which brands it represents, who operates on each brand's behalf, and the billing model. The seller provisions or links accounts accordingly, returning per-account status.",
+  "x-mutates-state": true,
+  "type": "object",
+  "properties": {
+    "adcp_major_version": {
+      "type": "integer",
+      "description": "The AdCP major version the buyer's payloads conform to. Sellers validate against their supported major_versions and return VERSION_UNSUPPORTED if unsupported. When omitted, the seller assumes its highest supported version.",
+      "minimum": 1,
+      "maximum": 99
+    },
+    "idempotency_key": {
+      "type": "string",
+      "description": "Client-generated unique key for at-most-once execution. Natural per-account upsert keys (brand, operator) handle resource-level dedup, but the envelope triggers onboarding webhooks, billing setup, and audit events — this key prevents those side effects from firing twice on retry. MUST be unique per (seller, request) pair. Use a fresh UUID v4 for each request.",
+      "minLength": 16,
+      "maxLength": 255,
+      "pattern": "^[A-Za-z0-9_.:-]{16,255}$"
+    },
+    "accounts": {
+      "type": "array",
+      "description": "Advertiser accounts to sync",
+      "items": {
+        "type": "object",
+        "description": "An advertiser account the agent wants to operate on the seller",
+        "properties": {
+          "brand": {
+            "$ref": "/schemas/3.0.1/core/brand-ref.json",
+            "description": "Brand reference identifying the advertiser. Uses the brand's house domain and optional brand_id from brand.json."
+          },
+          "operator": {
+            "type": "string",
+            "description": "Domain of the entity operating on the brand's behalf (e.g., 'pinnacle-media.com'). When the brand operates directly, this is the brand's domain. Verified against the brand's authorized_operators in brand.json.",
+            "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$"
+          },
+          "billing": {
+            "$ref": "/schemas/3.0.1/enums/billing-party.json",
+            "description": "Who should be invoiced. The seller must either accept this billing model or reject the request."
+          },
+          "billing_entity": {
+            "$ref": "/schemas/3.0.1/core/business-entity.json",
+            "description": "Business entity details for the party responsible for payment. The agent provides this so the seller has the legal name, tax IDs, address, and bank details needed for formal B2B invoicing."
+          },
+          "payment_terms": {
+            "$ref": "/schemas/3.0.1/enums/payment-terms.json",
+            "description": "Payment terms for this account. The seller must either accept these terms or reject the account — terms are never silently remapped. When omitted, the seller applies its default terms."
+          },
+          "sandbox": {
+            "type": "boolean",
+            "description": "When true, provision this as a sandbox account with no real platform calls or billing. Only applicable to implicit accounts (require_operator_auth: false). For explicit accounts, sandbox accounts are pre-existing test accounts discovered via list_accounts."
+          },
+          "preferred_reporting_protocol": {
+            "$ref": "/schemas/3.0.1/enums/cloud-storage-protocol.json",
+            "description": "Buyer's preferred cloud storage protocol for offline reporting delivery. The seller provisions the account's reporting_bucket using this protocol if supported. When omitted, the seller chooses from its supported offline_delivery_protocols. Only meaningful when the seller's reporting_delivery_methods includes 'offline'."
+          }
+        },
+        "required": [
+          "brand",
+          "operator",
+          "billing"
+        ],
+        "additionalProperties": true
+      },
+      "maxItems": 1000
+    },
+    "delete_missing": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, accounts previously synced by this agent but not included in this request will be deactivated. Scoped to the authenticated agent — does not affect accounts managed by other agents. Use with caution."
+    },
+    "dry_run": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, preview what would change without applying. Returns what would be created/updated/deactivated."
+    },
+    "push_notification_config": {
+      "$ref": "/schemas/3.0.1/core/push-notification-config.json",
+      "description": "Webhook for async notifications when account status changes (e.g., pending_approval transitions to active)."
+    },
+    "context": {
+      "$ref": "/schemas/3.0.1/core/context.json"
+    },
+    "ext": {
+      "$ref": "/schemas/3.0.1/core/ext.json"
+    }
+  },
+  "required": [
+    "idempotency_key",
+    "accounts"
+  ],
+  "additionalProperties": true,
+  "examples": [
+    {
+      "description": "Agency syncing multiple advertisers with different billing",
+      "data": {
+        "idempotency_key": "a7f9c2e4-1234-4567-89ab-cdef01234567",
+        "accounts": [
+          {
+            "brand": {
+              "domain": "nova-brands.com",
+              "brand_id": "spark"
+            },
+            "operator": "pinnacle-media.com",
+            "billing": "operator"
+          },
+          {
+            "brand": {
+              "domain": "nova-brands.com",
+              "brand_id": "glow"
+            },
+            "operator": "pinnacle-media.com",
+            "billing": "agent"
+          }
+        ]
+      }
+    },
+    {
+      "description": "Brand buying direct with payment terms",
+      "data": {
+        "idempotency_key": "b8e0d3f5-2345-4678-9abc-def012345678",
+        "accounts": [
+          {
+            "brand": {
+              "domain": "acme-corp.com"
+            },
+            "operator": "acme-corp.com",
+            "billing": "operator",
+            "payment_terms": "net_30"
+          }
+        ]
+      }
+    },
+    {
+      "description": "Agent consolidating billing with net-60 terms",
+      "data": {
+        "idempotency_key": "c9f1e4a6-3456-4789-abcd-ef0123456789",
+        "accounts": [
+          {
+            "brand": {
+              "domain": "nova-brands.com",
+              "brand_id": "spark"
+            },
+            "operator": "pinnacle-media.com",
+            "billing": "agent",
+            "payment_terms": "net_60"
+          },
+          {
+            "brand": {
+              "domain": "nova-brands.com",
+              "brand_id": "glow"
+            },
+            "operator": "pinnacle-media.com",
+            "billing": "agent",
+            "payment_terms": "net_60"
+          }
+        ]
+      }
+    },
+    {
+      "description": "Advertiser billed directly with structured billing entity (DACH B2B)",
+      "data": {
+        "idempotency_key": "d0a2f5b7-4567-489a-bcde-f01234567890",
+        "accounts": [
+          {
+            "brand": {
+              "domain": "acme-corp.com"
+            },
+            "operator": "pinnacle-media.com",
+            "billing": "advertiser",
+            "billing_entity": {
+              "legal_name": "Acme Corporation GmbH",
+              "vat_id": "DE987654321",
+              "registration_number": "HRB 67890",
+              "address": {
+                "street": "Hauptstrasse 42",
+                "city": "Munich",
+                "postal_code": "80331",
+                "country": "DE"
+              },
+              "contacts": [
+                {
+                  "role": "billing",
+                  "name": "AP Department",
+                  "email": "billing@acme-corp.com"
+                }
+              ],
+              "bank": {
+                "account_holder": "Acme Corporation GmbH",
+                "iban": "DE75512108001245126199",
+                "bic": "SOLADEST600"
+              }
+            },
+            "payment_terms": "net_30"
+          }
+        ]
+      }
+    }
+  ]
+}

package/dist/lib/schemas-data/3.0.1/account/sync-accounts-response.json

@@ -0,0 +1,346 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/3.0.1/account/sync-accounts-response.json",
+  "title": "Sync Accounts Response",
+  "description": "Response from account sync operation. Returns per-account results with status and billing, or operation-level errors on complete failure.",
+  "type": "object",
+  "oneOf": [
+    {
+      "title": "SyncAccountsSuccess",
+      "description": "Sync operation processed accounts (individual accounts may be pending or have action=failed)",
+      "type": "object",
+      "properties": {
+        "dry_run": {
+          "type": "boolean",
+          "description": "Whether this was a dry run (no actual changes made)"
+        },
+        "accounts": {
+          "type": "array",
+          "description": "Results for each account processed",
+          "items": {
+            "type": "object",
+            "properties": {
+              "account_id": {
+                "type": "string",
+                "description": "Seller-assigned account identifier. Use this in subsequent create_media_buy and other account-scoped operations.",
+                "x-entity": "account"
+              },
+              "brand": {
+                "$ref": "/schemas/3.0.1/core/brand-ref.json",
+                "description": "Brand reference, echoed from the request"
+              },
+              "operator": {
+                "type": "string",
+                "description": "Operator domain, echoed from request"
+              },
+              "name": {
+                "type": "string",
+                "description": "Human-readable account name assigned by the seller"
+              },
+              "action": {
+                "type": "string",
+                "enum": [
+                  "created",
+                  "updated",
+                  "unchanged",
+                  "failed"
+                ],
+                "description": "Action taken for this account. created: new account provisioned. updated: existing account modified. unchanged: no changes needed. failed: could not process (see errors)."
+              },
+              "status": {
+                "type": "string",
+                "enum": [
+                  "active",
+                  "pending_approval",
+                  "rejected",
+                  "payment_required",
+                  "suspended",
+                  "closed"
+                ],
+                "description": "Account status. active: ready for use. pending_approval: seller reviewing (credit, legal). rejected: seller declined the account request. payment_required: credit limit reached or funds depleted. suspended: was active, now paused. closed: was active, now terminated."
+              },
+              "billing": {
+                "$ref": "/schemas/3.0.1/enums/billing-party.json",
+                "description": "Who is invoiced on this account. Matches the requested billing model."
+              },
+              "billing_entity": {
+                "$ref": "/schemas/3.0.1/core/business-entity.json",
+                "description": "Business entity details for the party responsible for payment, echoed from the request. Sellers MAY add fields the agent omitted (e.g., filling in registration_number from a credit check), but MUST NOT return data from a different entity. Bank details are omitted (write-only)."
+              },
+              "account_scope": {
+                "$ref": "/schemas/3.0.1/enums/account-scope.json"
+              },
+              "setup": {
+                "type": "object",
+                "description": "Setup information for pending accounts. Provides the agent (or human) with next steps to complete account activation.",
+                "properties": {
+                  "url": {
+                    "type": "string",
+                    "format": "uri",
+                    "description": "URL where the human can complete the required action (credit application, legal agreement, add funds)"
+                  },
+                  "message": {
+                    "type": "string",
+                    "description": "Human-readable description of what's needed"
+                  },
+                  "expires_at": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "When this setup link expires"
+                  }
+                },
+                "required": [
+                  "message"
+                ],
+                "additionalProperties": true
+              },
+              "rate_card": {
+                "type": "string",
+                "description": "Rate card applied to this account"
+              },
+              "payment_terms": {
+                "$ref": "/schemas/3.0.1/enums/payment-terms.json",
+                "description": "Payment terms agreed for this account. When the account is active, these are the binding terms for all invoices on this account."
+              },
+              "credit_limit": {
+                "type": "object",
+                "properties": {
+                  "amount": {
+                    "type": "number",
+                    "minimum": 0
+                  },
+                  "currency": {
+                    "type": "string",
+                    "pattern": "^[A-Z]{3}$"
+                  }
+                },
+                "required": [
+                  "amount",
+                  "currency"
+                ]
+              },
+              "errors": {
+                "type": "array",
+                "description": "Per-account errors (only present when action is 'failed')",
+                "items": {
+                  "$ref": "/schemas/3.0.1/core/error.json"
+                }
+              },
+              "warnings": {
+                "type": "array",
+                "description": "Non-fatal warnings about this account",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "sandbox": {
+                "type": "boolean",
+                "description": "Whether this is a sandbox account, echoed from the request. Only present for implicit accounts."
+              }
+            },
+            "required": [
+              "brand",
+              "operator",
+              "action",
+              "status"
+            ],
+            "additionalProperties": true
+          }
+        },
+        "context": {
+          "$ref": "/schemas/3.0.1/core/context.json"
+        },
+        "ext": {
+          "$ref": "/schemas/3.0.1/core/ext.json"
+        }
+      },
+      "required": [
+        "accounts"
+      ],
+      "additionalProperties": true,
+      "not": {
+        "required": [
+          "errors"
+        ]
+      }
+    },
+    {
+      "title": "SyncAccountsError",
+      "description": "Operation failed completely, no accounts were processed",
+      "type": "object",
+      "properties": {
+        "errors": {
+          "type": "array",
+          "description": "Operation-level errors (e.g., authentication failure, service unavailable)",
+          "items": {
+            "$ref": "/schemas/3.0.1/core/error.json"
+          },
+          "minItems": 1
+        },
+        "context": {
+          "$ref": "/schemas/3.0.1/core/context.json"
+        },
+        "ext": {
+          "$ref": "/schemas/3.0.1/core/ext.json"
+        }
+      },
+      "required": [
+        "errors"
+      ],
+      "additionalProperties": true,
+      "not": {
+        "anyOf": [
+          {
+            "required": [
+              "accounts"
+            ]
+          },
+          {
+            "required": [
+              "dry_run"
+            ]
+          }
+        ]
+      }
+    }
+  ],
+  "examples": [
+    {
+      "description": "Mixed results — one active, one pending approval",
+      "data": {
+        "accounts": [
+          {
+            "account_id": "acc_spark_001",
+            "brand": {
+              "domain": "nova-brands.com",
+              "brand_id": "spark"
+            },
+            "operator": "pinnacle-media.com",
+            "name": "Spark (via Pinnacle)",
+            "action": "created",
+            "status": "active",
+            "billing": "operator",
+            "account_scope": "operator_brand"
+          },
+          {
+            "account_id": "acc_glow_pending",
+            "brand": {
+              "domain": "nova-brands.com",
+              "brand_id": "glow"
+            },
+            "operator": "pinnacle-media.com",
+            "name": "Glow",
+            "action": "created",
+            "status": "pending_approval",
+            "billing": "operator",
+            "account_scope": "operator_brand",
+            "setup": {
+              "url": "https://seller.example.com/advertiser-onboard",
+              "message": "Complete advertiser registration and credit application",
+              "expires_at": "2026-03-10T00:00:00Z"
+            }
+          }
+        ]
+      }
+    },
+    {
+      "description": "Rejected account — no account_id assigned",
+      "data": {
+        "accounts": [
+          {
+            "brand": {
+              "domain": "acme-corp.com",
+              "brand_id": "clearance"
+            },
+            "operator": "acme-corp.com",
+            "action": "created",
+            "status": "rejected",
+            "warnings": [
+              "Account request declined: advertiser category not accepted on this platform."
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "description": "Unsupported billing — seller rejects the request",
+      "data": {
+        "accounts": [
+          {
+            "brand": {
+              "domain": "acme-corp.com"
+            },
+            "operator": "acme-corp.com",
+            "action": "failed",
+            "status": "rejected",
+            "errors": [
+              {
+                "code": "BILLING_NOT_SUPPORTED",
+                "message": "Operator billing is not supported. This seller only accepts agent billing."
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "description": "Advertiser billed directly with billing entity (bank details omitted in response)",
+      "data": {
+        "accounts": [
+          {
+            "account_id": "acc_acme_direct_bill",
+            "brand": {
+              "domain": "acme-corp.com"
+            },
+            "operator": "pinnacle-media.com",
+            "name": "Acme Corp (billed direct)",
+            "action": "created",
+            "status": "active",
+            "billing": "advertiser",
+            "billing_entity": {
+              "legal_name": "Acme Corporation GmbH",
+              "vat_id": "DE987654321",
+              "registration_number": "HRB 67890",
+              "address": {
+                "street": "Hauptstrasse 42",
+                "city": "Munich",
+                "postal_code": "80331",
+                "country": "DE"
+              },
+              "contacts": [
+                {
+                  "role": "billing",
+                  "name": "AP Department",
+                  "email": "billing@acme-corp.com"
+                }
+              ]
+            },
+            "account_scope": "operator_brand",
+            "payment_terms": "net_30"
+          }
+        ]
+      }
+    },
+    {
+      "description": "Unsupported payment terms — seller rejects the request",
+      "data": {
+        "accounts": [
+          {
+            "brand": {
+              "domain": "acme-corp.com"
+            },
+            "operator": "acme-corp.com",
+            "action": "failed",
+            "status": "rejected",
+            "errors": [
+              {
+                "code": "PAYMENT_TERMS_NOT_SUPPORTED",
+                "message": "Net-60 payment terms are not available. Omit payment_terms to accept this seller's default terms (net_30)."
+              }
+            ]
+          }
+        ]
+      }
+    }
+  ]
+}