@adcp/sdk 8.1.0-beta.7 → 8.1.0-beta.8

package/dist/lib/types/get-media-buys.d.ts

@@ -0,0 +1,1670 @@
+// AUTO-GENERATED — DO NOT EDIT.
+// Per-tool .d.ts slice for `get_media_buys`. Built from the published
+// `tools.generated.d.ts` + `core.generated.d.ts` + `enums.generated.d.ts`
+// by `scripts/generate-per-tool-types.ts`.
+//
+// Self-contained: imports nothing from the broader SDK. Adopters who
+// import only this slice pay a fraction of the tsc cost of pulling in
+// `@adcp/sdk` root — useful when strict + skipLibCheck:false adopters
+// hit memory pressure on the full surface.
+
+/**
+ * Request parameters for retrieving media buy status, creative approval state, and optional delivery snapshots
+ */
+export interface GetMediaBuysRequest {
+    /**
+     * Release-precision AdCP version (VERSION.RELEASE, e.g. "3.0", "3.1", "3.1-beta"). On a request: the buyer's release pin — the seller validates against its supported_versions and returns VERSION_UNSUPPORTED on cross-major mismatch, or downshifts to the highest supported release within the same major. On a response: the release the seller actually served — clients SHOULD validate the response against that release's schema, not against their pin. Patches are not negotiated; surface them as build_version on capabilities for operational visibility. When omitted, falls back to adcp_major_version (deprecated) or server default. Buyers SHOULD emit both adcp_version and adcp_major_version through 3.x to remain compatible with sellers that only read the legacy field. NORMALIZATION: SDKs that read full-semver values from bundle metadata (e.g. ComplianceIndex.published_version = "3.1.0-beta.1") MUST normalize to release-precision ("3.1-beta.1") before emitting on the wire — meta-field values are NOT valid wire values.
+     */
+    adcp_version?: string;
+    /**
+     * DEPRECATED in favor of adcp_version (release-precision string). Servers MUST continue to honor this field through 3.x. Removed in 4.0. Original semantics: 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.
+     */
+    adcp_major_version?: number;
+    account?: AccountReference;
+    /**
+     * Array of media buy IDs to retrieve. When omitted, returns a paginated set of accessible media buys matching status_filter.
+     */
+    media_buy_ids?: string[];
+    /**
+     * Filter by status. Can be a single status or array of statuses. Defaults to ["active"] when media_buy_ids is omitted. When media_buy_ids is provided, no implicit status filter is applied.
+     */
+    status_filter?: MediaBuyStatus | MediaBuyStatus[];
+    /**
+     * When true, include a near-real-time delivery snapshot for each package. Snapshots reflect the latest available entity-level stats from the platform (e.g., updated every ~15 minutes on GAM, ~1 hour on batch-only platforms). The staleness_seconds field on each snapshot indicates data freshness. If a snapshot cannot be returned, package.snapshot_unavailable_reason explains why. Defaults to false.
+     */
+    include_snapshot?: boolean;
+    /**
+     * When present, include the last N revision history entries for each media buy (returns min(N, available entries)). Each entry contains revision number, timestamp, actor, and a summary of what changed. Omit or set to 0 to exclude history (default). Recommended: 5-10 for monitoring, 50+ for audit.
+     * @minimum 0
+     * @maximum 1000
+     */
+    include_history?: number;
+    /**
+     * When true, each returned media buy includes a `webhook_activity` array describing recent delivery-report webhook fires for the calling principal. Used by buyer agents to verify whether a publisher actually fired against the buyer's registered endpoint and what the endpoint returned — closes the operator-ticket loop for webhook debugging. Scoped to the calling principal: a buyer sees only fires targeting its own endpoint, even when multiple principals share visibility into the same media buy. Defaults to false. See `webhook_activity_limit` for the per-buy cap.
+     */
+    include_webhook_activity?: boolean;
+    /**
+     * Maximum number of webhook delivery records to return per media buy, ordered most-recent first. Ignored when `include_webhook_activity` is false. Sellers that surface webhook activity MUST retain records for at least 30 days from each record's `completed_at` (see `webhook_activity` description in the response schema for the `pending`-status carve-out); sellers unable to honor that floor MUST omit the field entirely rather than truncate. When a buy has more historical fires than the limit, only the most recent are returned — there is no cursor for older fires; this surface is a debug aid, not a full audit log.
+     * @minimum 1
+     * @maximum 200
+     */
+    webhook_activity_limit?: number;
+    pagination?: PaginationRequest;
+    context?: ContextObject;
+    ext?: ExtensionObject;
+}
+
+/**
+ * Response payload for get_media_buys task. Returns media buy configuration, creative approval state, and optional delivery snapshots.
+ */
+export interface GetMediaBuysResponse {
+    /**
+     * Session/conversation identifier for tracking related operations across multiple task invocations. Managed by the protocol layer to maintain conversational context. Distinct from `context` (per-request opaque echo, see below).
+     */
+    context_id?: string;
+    context?: ContextObject;
+    /**
+     * Unique identifier for tracking asynchronous operations. Present when a task requires extended processing time. Used to query task status and retrieve results when complete.
+     */
+    task_id?: string;
+    status: TaskStatus;
+    /**
+     * 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.
+     */
+    message?: string;
+    /**
+     * ISO 8601 timestamp when the response was generated. Useful for debugging, logging, cache validation, and tracking async operation progress.
+     */
+    timestamp?: string;
+    /**
+     * Set to true when this response was returned from the idempotency cache rather than from a fresh execution. Set to false (or omitted) when the request was executed fresh. Buyers use this to distinguish cached replays from new executions — matters for billing reconciliation, audit logs, state-machine routing (cached state-tracking fields are historical snapshots, not current state — re-read via the resource's read endpoint), and any downstream system that assumes exactly-once event semantics. From 3.1 onward, `replayed` MAY appear on responses to any request that resolved via the idempotency cache, including read tools — universal `idempotency_key` (see security.mdx §Idempotency) means the cache holds read responses too.
+     */
+    replayed?: boolean;
+    adcp_error?: Error;
+    push_notification_config?: PushNotificationConfig;
+    /**
+     * Governance context token issued by the account's governance agent during check_governance. Buyers attach it to governed purchase requests (media buys, rights acquisitions, signal activations, creative services); sellers persist it and include it on all subsequent governance calls for that action's lifecycle. An account binds to one governance agent (see sync_governance); governance is phased across `purchase` / `modification` / `delivery`, not partitioned across specialist agents, so the envelope carries a single token for the full lifecycle.
+     *
+     * Value format: governance agents MUST emit a compact JWS per the AdCP JWS profile (see Security — Signed Governance Context). Sellers MAY verify; sellers that do not verify MUST persist and forward the token unchanged. In 3.1 all sellers MUST verify. Non-JWS values from pre-3.0 governance agents are deprecated.
+     *
+     * This is the primary correlation key for audit and reporting across the governance lifecycle.
+     */
+    governance_context?: string;
+    /**
+     * Conceptual grouping for the task-specific response data defined by individual task response schemas (e.g., get-products-response.json, create-media-buy-response.json). `payload` is a documentary construct — it is NOT a required wire field, and its on-the-wire shape depends on transport (see Transport serialization below). Task response schemas declare body fields without wrapping them in a `payload` object; the wire representation places those body fields per transport convention. On MCP the body fields appear as siblings of envelope fields at the root of the tool response; on A2A they appear inside `task.artifacts[0].parts[].DataPart`; on REST they appear at the root of the JSON body.
+     */
+    payload?: {};
+    /**
+     * Release-precision AdCP version (VERSION.RELEASE, e.g. "3.0", "3.1", "3.1-beta"). On a request: the buyer's release pin — the seller validates against its supported_versions and returns VERSION_UNSUPPORTED on cross-major mismatch, or downshifts to the highest supported release within the same major. On a response: the release the seller actually served — clients SHOULD validate the response against that release's schema, not against their pin. Patches are not negotiated; surface them as build_version on capabilities for operational visibility. When omitted, falls back to adcp_major_version (deprecated) or server default. Buyers SHOULD emit both adcp_version and adcp_major_version through 3.x to remain compatible with sellers that only read the legacy field. NORMALIZATION: SDKs that read full-semver values from bundle metadata (e.g. ComplianceIndex.published_version = "3.1.0-beta.1") MUST normalize to release-precision ("3.1-beta.1") before emitting on the wire — meta-field values are NOT valid wire values.
+     */
+    adcp_version?: string;
+    /**
+     * DEPRECATED in favor of adcp_version (release-precision string). Servers MUST continue to honor this field through 3.x. Removed in 4.0. Original semantics: 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.
+     */
+    adcp_major_version?: number;
+    /**
+     * Array of media buys with status, creative approval state, and optional delivery snapshots
+     */
+    media_buys: {
+        /**
+         * Seller's unique identifier for the media buy
+         */
+        media_buy_id: string;
+        account?: Account;
+        invoice_recipient?: BusinessEntity;
+        status: MediaBuyStatus;
+        /**
+         * Dependency health of the media buy, orthogonal to `status`. `ok` (default) when no upstream resource that this buy depends on is in an offline state. `impaired` when at least one such resource (audience, creative, catalog_item, event_source, property) is offline and affects delivery for one or more packages — `impairments[]` MUST be non-empty in that case. On terminal-status buys, the seller MAY leave this field in whatever state held at the terminal transition. See lifecycle.mdx § Compliance and the impairment.coherence assertion.
+         */
+        health?: MediaBuyHealth & string;
+        /**
+         * Open impairments — upstream dependency state changes that affect delivery for at least one package on this buy. Empty when `health` is `ok`; non-empty iff `health` is `impaired` (health-iff rule on non-terminal buys). Sellers MUST add an entry on the next read after a referenced resource transitions to an offline state, and MUST remove the entry when the resource returns to a serviceable state or stops being a dependency (e.g., via assignment swap via update_media_buy). Staleness budget: the snapshot MUST reflect the impairment within 5 minutes of `impairment.observed_at` regardless of buyer poll cadence — sellers cannot rely on rare buyer polls to defer write propagation. See impairment.coherence assertion for the cross-resource invariant.
+         */
+        impairments?: Impairment[];
+        /**
+         * Reason provided by the seller when status is 'rejected'. Present only when status is 'rejected'.
+         */
+        rejection_reason?: string;
+        /**
+         * ISO 4217 currency code (e.g., USD, EUR, GBP) for monetary values at this media buy level. total_budget is always denominated in this currency. Package-level fields may override with package.currency.
+         * @pattern ^[A-Z]{3}$
+         */
+        currency: string;
+        /**
+         * Total budget amount across all packages, denominated in media_buy.currency
+         * @minimum 0
+         */
+        total_budget?: number;
+        /**
+         * ISO 8601 flight start time for this media buy (earliest package start_time). Avoids requiring buyers to compute min(packages[].start_time).
+         * @format date-time
+         */
+        start_time?: string;
+        /**
+         * ISO 8601 flight end time for this media buy (latest package end_time). Avoids requiring buyers to compute max(packages[].end_time).
+         * @format date-time
+         */
+        end_time?: string;
+        /**
+         * ISO 8601 timestamp for creative upload deadline
+         * @format date-time
+         */
+        creative_deadline?: string;
+        /**
+         * ISO 8601 timestamp when the seller confirmed this media buy. A successful create_media_buy response constitutes order confirmation.
+         * @format date-time
+         */
+        confirmed_at?: string;
+        /**
+         * Cancellation metadata. Present only when status is 'canceled'.
+         */
+        cancellation?: {
+            /**
+             * ISO 8601 timestamp when this media buy was canceled.
+             * @format date-time
+             */
+            canceled_at: string;
+            canceled_by: CanceledBy;
+            /**
+             * Reason the media buy was canceled.
+             * @maxLength 500
+             */
+            reason?: string;
+        };
+        /**
+         * Current revision number. Pass this in update_media_buy for optimistic concurrency.
+         * @minimum 1
+         */
+        revision?: number;
+        /**
+         * Creation timestamp
+         * @format date-time
+         */
+        created_at?: string;
+        /**
+         * Last update timestamp
+         * @format date-time
+         */
+        updated_at?: string;
+        /**
+         * Flat-vocabulary actions the buyer can perform on this media buy in its current state. Eliminates the need for agents to internalize the state machine — the seller declares what is permitted right now. Deprecated in favor of `available_actions[]`, which carries `mode` (self_serve / conditional_self_serve / requires_proposal / requires_approval), optional SLA, and optional `terms_ref`. Sellers SHOULD populate both during the 3.x deprecation window; consumers MUST prefer `available_actions[]` when both are present. Removed in 4.0.
+         */
+        valid_actions?: MediaBuyValidAction[];
+        /**
+         * Structured per-buy resolution of the actions buyer can perform right now. Authoritative — divergence from product `allowed_actions[]` is expected (negotiated terms, account tier, buy-level overrides live on the deal, not the product). Each entry carries the resolved `mode` (singular, since the buy has a concrete state), optional `sla` commitment, and optional `terms_ref`. Predicate queries via #4425's `requires` grammar address fields by dotted path, e.g. `available_actions.extend_flight.sla.response_max`. Absent SLA means no commitment, not zero commitment — callers composing duration predicates MUST also compose with `present: true` to avoid silently matching sellers who never declared one.
+         */
+        available_actions?: MediaBuyAvailableAction[];
+        /**
+         * Recent reporting and health webhook fires for the calling principal, most-recent first. Present only when `include_webhook_activity` was true in the request AND the seller surfaces this debug capability for this buy. Three-state semantics: (a) field omitted — seller does not surface webhook activity (either does not persist fire history, or `capabilities.media_buy.propagation_surfaces` excludes webhook surfaces, or the buy has no registered `push_notification_config` for this principal); (b) empty array `[]` — seller persists fire history but has fired nothing recent for this principal; (c) non-empty array — actual fire records. Sellers whose declared `propagation_surfaces` does not include `webhook` MUST omit the field. **Retention (normative):** sellers that surface this field MUST retain records for at least 30 days from each record's `completed_at` (for records still in `pending` status the clock runs from `fired_at` until the attempt terminates, then resets to 30 days from `completed_at` — so retry trails do not age out mid-flight). Sellers that cannot honor the 30-day floor MUST omit the field entirely rather than return a shorter window. Sellers MAY return fewer than `webhook_activity_limit` records when fewer fire records exist within the retention window. Sellers MUST emit one record per attempt — single-attempt successes appear as a single record with `attempt: 1`. Record shape is canonical across resources: see [`/schemas/core/webhook-activity-record.json`](/schemas/v3/core/webhook-activity-record.json) and snapshot-and-log.mdx § Webhook activity log pattern.
+         */
+        webhook_activity?: WebhookActivityRecord[];
+        /**
+         * Revision history entries, most recent first. Only present when include_history > 0 in the request. Each entry represents a state change or update to the media buy. Entries are append-only: sellers MUST NOT modify or delete previously emitted history entries. Callers MAY cache entries by revision number. Returns min(N, available entries) when include_history exceeds the total.
+         */
+        history?: {
+            /**
+             * Revision number after this change was applied.
+             * @minimum 1
+             */
+            revision: number;
+            /**
+             * When this change occurred.
+             * @format date-time
+             */
+            timestamp: string;
+            /**
+             * Identity of who made the change — derived from authentication context, not caller-provided. Format is seller-defined (e.g., agent URL, user email, API key label).
+             */
+            actor?: string;
+            /**
+             * What happened. Standard actions: created, activated, paused, resumed, canceled, rejected, completed, updated_budget, updated_dates, updated_packages, package_canceled, package_paused, package_resumed. Sellers MAY use additional platform-specific actions (e.g., creative_approved, targeting_updated) — use ext on the history entry for structured metadata about custom actions.
+             */
+            action: string;
+            /**
+             * Human-readable summary of the change (e.g., 'Budget increased from $5,000 to $7,500 on pkg_abc').
+             * @maxLength 500
+             */
+            summary?: string;
+            /**
+             * Package affected, when the change targeted a specific package.
+             */
+            package_id?: string;
+            ext?: ExtensionObject;
+        }[];
+        /**
+         * Packages within this media buy, augmented with creative approval status and optional delivery snapshots
+         */
+        packages: PackageStatus[];
+        ext?: ExtensionObject;
+    }[];
+    /**
+     * Task-specific errors (e.g., media buy not found)
+     */
+    errors?: Error[];
+    pagination?: PaginationResponse;
+    /**
+     * When true, this response contains simulated data from sandbox mode.
+     */
+    sandbox?: boolean;
+    ext?: ExtensionObject;
+}
+
+/**
+ * Account billed for this media buy. Includes advertiser, billing proxy (if any), and rate card applied.
+ */
+export interface Account {
+    /**
+     * Unique identifier for this account
+     */
+    account_id: string;
+    /**
+     * Human-readable account name (e.g., 'Acme', 'Acme c/o Pinnacle')
+     */
+    name: string;
+    /**
+     * The advertiser whose rates apply to this account
+     */
+    advertiser?: string;
+    /**
+     * Optional intermediary who receives invoices on behalf of the advertiser (e.g., agency)
+     */
+    billing_proxy?: string;
+    status: AccountStatus;
+    brand?: BrandReference;
+    /**
+     * Domain of the entity operating this account. When the brand operates directly, this is the brand's domain.
+     * @pattern ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$
+     */
+    operator?: string;
+    billing?: BillingParty;
+    billing_entity?: BusinessEntity;
+    /**
+     * Identifier for the rate card applied to this account
+     */
+    rate_card?: string;
+    payment_terms?: PaymentTerms;
+    /**
+     * Maximum outstanding balance allowed
+     */
+    credit_limit?: {
+        /**
+         * @minimum 0
+         */
+        amount: number;
+        /**
+         * @pattern ^[A-Z]{3}$
+         */
+        currency: string;
+    };
+    /**
+     * Present when status is 'pending_approval'. Contains next steps for completing account activation.
+     */
+    setup?: {
+        /**
+         * URL where the human can complete the required action (credit application, legal agreement, add funds).
+         */
+        url?: string;
+        /**
+         * Human-readable description of what's needed.
+         */
+        message: string;
+        /**
+         * When this setup link expires.
+         * @format date-time
+         */
+        expires_at?: string;
+    };
+    account_scope?: AccountScope;
+    /**
+     * Governance agent endpoint registered on this account. Exactly one entry per sync_governance's one-agent-per-account invariant. The array shape is preserved for wire compatibility with 3.0; `maxItems: 1` is load-bearing and mirrors the singular `governance_context` on the protocol envelope. Authentication credentials are write-only and not included in responses — use sync_governance to set or update credentials.
+     */
+    governance_agents?: {
+        /**
+         * Governance agent endpoint URL. Must use HTTPS.
+         * @pattern ^https:\/\/
+         */
+        url: string;
+    }[];
+    /**
+     * Cloud storage bucket where the seller delivers offline reporting files for this account. Seller provisions a dedicated bucket or a per-account prefix within a shared bucket, and grants the buyer read access out-of-band. Access MUST be scoped at the IAM layer so each account can only read its own prefix — bucket-wide grants are non-compliant even with per-account prefixes. Seller MUST revoke access when the account's status transitions to inactive, suspended, or closed. See security considerations for offline delivery in docs/media-buy/media-buys/optimization-reporting. Only present when the seller supports offline delivery (reporting_delivery_methods includes 'offline' in capabilities).
+     */
+    reporting_bucket?: {
+        protocol: CloudStorageProtocol;
+        /**
+         * Bucket or container name
+         * @minLength 3
+         * @maxLength 63
+         * @pattern ^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$
+         */
+        bucket: string;
+        /**
+         * Path prefix within the bucket. Seller appends date-based partitioning beneath this prefix.
+         * @maxLength 512
+         * @pattern ^[a-zA-Z0-9\/_.-]+$
+         */
+        prefix?: string;
+        /**
+         * Cloud region for the bucket
+         * @maxLength 64
+         * @pattern ^[a-z0-9-]+$
+         */
+        region?: string;
+        /**
+         * File format for delivered files. Parquet, Avro, and ORC use internal compression (the top-level compression field is ignored for these formats).
+         */
+        format?: 'jsonl' | 'csv' | 'parquet' | 'avro' | 'orc';
+        /**
+         * Compression applied to delivered files
+         */
+        compression?: 'gzip' | 'none';
+        /**
+         * How long reporting files are retained in the bucket before deletion. Buyers must read files within this window. Minimum recommended: 14 days.
+         * @minimum 1
+         */
+        file_retention_days: number;
+        /**
+         * URL to documentation for configuring buyer read access to this bucket (IAM role, service account, etc.). Operator-facing documentation — buyer agents MUST NOT auto-fetch this URL; surface it to a human operator. If an implementation fetches it (for preview), apply webhook URL SSRF validation and do not pass the fetched content into an LLM context without indirect-prompt-injection guarding. See docs/media-buy/media-buys/optimization-reporting#security-considerations-for-offline-delivery.
+         * @pattern ^https:\/\/
+         */
+        setup_instructions?: string;
+    };
+    /**
+     * When true, this is a sandbox account — no real platform calls, no real spend. For explicit accounts (require_operator_auth: true), sandbox accounts are pre-existing test accounts on the platform discovered via list_accounts. For implicit accounts, sandbox is part of the natural key: the same brand/operator pair can have both a production and sandbox account.
+     */
+    sandbox?: boolean;
+    /**
+     * Account-level webhook subscriptions for notifications whose lifecycle outlives any single media buy (e.g., `creative.status_changed`, `creative.purged`, wholesale feed change payloads). Distinct from `push_notification_config` on individual operations, which anchors at a per-resource scope. Buyers register and update entries via `sync_accounts`; sellers echo the applied state here on `list_accounts` reads so buyers can verify what's active. `authentication.credentials` is write-only — sellers MUST NOT echo legacy auth credentials in this response. When two or more entries register the same `event_types`, each receives an independent fire — see #3009 multi-subscriber composition.
+     */
+    notification_configs?: NotificationConfig[];
+    ext?: ExtensionObject;
+}
+
+/**
+ * Account for product lookup. Returns products with pricing specific to this account's rate card.
+ */
+export type AccountReference = {
+    /**
+     * Seller-assigned account identifier (from sync_accounts or list_accounts)
+     */
+    account_id: string;
+} | {
+    brand: BrandReference;
+    /**
+     * Domain of the entity operating on the brand's behalf. When the brand operates directly, this is the brand's domain.
+     * @pattern ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$
+     */
+    operator: string;
+    /**
+     * When true, references the sandbox account for this brand/operator pair. Defaults to false (production account).
+     */
+    sandbox?: boolean;
+};
+
+/**
+ * How the seller scoped a billing account relative to the operator and brand dimensions.
+ */
+export type AccountScope = 'operator' | 'brand' | 'operator_brand' | 'agent';
+
+/**
+ * Account lifecycle status. See the Accounts Protocol overview for the operations matrix showing which tasks are permitted in each state.
+ */
+export type AccountStatus = 'active' | 'pending_approval' | 'rejected' | 'payment_required' | 'suspended' | 'closed';
+
+/**
+ * Methods for verifying user age for compliance. Does not include 'inferred' as it is not accepted for regulatory compliance.
+ */
+export type AgeVerificationMethod = 'facial_age_estimation' | 'id_document' | 'digital_id' | 'credit_card' | 'world_id';
+
+/**
+ * Legacy authentication schemes for the webhook auth block. Bearer: token sent in Authorization header. HMAC-SHA256: legacy shared-secret signing. Both are deprecated; new integrations SHOULD omit the authentication block and use the RFC 9421 webhook signing profile (applicable on schemas where authentication is optional). Removed in AdCP 4.0.
+ */
+export type AuthenticationScheme = 'Bearer' | 'HMAC-SHA256';
+
+/**
+ * Who is invoiced on this account. See billing_entity for the invoiced party's business details.
+ */
+export type BillingParty = 'operator' | 'agent' | 'advertiser';
+
+/**
+ * Brand identifier within the house portfolio. Optional for single-brand domains.
+ */
+export type BrandID = string;
+
+/**
+ * Brand reference for product discovery context. Resolved to full brand identity at execution time.
+ */
+export interface BrandReference {
+    /**
+     * Domain where /.well-known/brand.json is hosted, or the brand's operating domain
+     * @pattern ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$
+     */
+    domain: string;
+    brand_id?: BrandID;
+    /**
+     * Inline override for the brand's industries. Useful when the caller cannot modify the brand's canonical brand.json but needs to declare industries for governance (e.g., Annex III vertical detection). brand.json remains the canonical source; when omitted here, governance agents SHOULD resolve from brand.json.
+     */
+    industries?: string[];
+    /**
+     * Inline override for the brand's contestation contact point. Useful when the operator does not control brand.json but needs to discharge Art 22(3) for this plan. brand.json is canonical; when omitted, governance agents resolve brand → house → missing.
+     */
+    data_subject_contestation?: {
+        [k: string]: unknown | undefined;
+    };
+    /**
+     * Inline override for brand-kit fields normally resolved from `/.well-known/brand.json` on `domain` (logo, colors, voice, tagline). Use when brand.json is missing, stale, or inappropriate for this specific call — e.g., a campaign-scoped tagline, a co-branded creative, a freshly-rebranded color palette the brand.json hasn't shipped yet. Same inline-override pattern as `industries` and `data_subject_contestation` above: brand.json is canonical, the override is per-call. Adopters needing to override fields outside this subset (`voice_attributes`, `prohibited_terms`, etc.) MUST publish a different brand.json and reference it via a different `domain` — the inline override is intentionally narrow to a small high-traffic subset.
+     *
+     * **Merge semantics (normative).** The merge is **field-level**, not whole-object replacement. Each field within `brand_kit_override` (`logo`, `colors`, `voice`, `tagline`) is evaluated independently — when a field is present on the override the override value applies; when a field is absent the brand.json value applies (or is absent if brand.json doesn't carry one either). For composite fields (`colors.primary`, `colors.secondary`, `colors.accent`), the merge is one level deeper: each color slot is evaluated independently — a producer can override `colors.primary` while still inheriting `colors.secondary` from brand.json. SDKs MUST NOT treat a present `brand_kit_override.colors` as wiping the brand.json `colors` block entirely; only the per-slot fields present in the override take precedence. Without this rule, a partial-override semantics would diverge across SDKs and produce inconsistent rendering for the same payload.
+     */
+    brand_kit_override?: {
+        logo?: ImageAsset;
+        /**
+         * Override brand colors (hex strings).
+         */
+        colors?: {
+            /**
+             * @pattern ^#[0-9a-fA-F]{6}$
+             */
+            primary?: string;
+            /**
+             * @pattern ^#[0-9a-fA-F]{6}$
+             */
+            secondary?: string;
+            /**
+             * @pattern ^#[0-9a-fA-F]{6}$
+             */
+            accent?: string;
+        };
+        /**
+         * Override brand-voice description for surface-composed text/audio output.
+         */
+        voice?: string;
+        /**
+         * Override tagline.
+         */
+        tagline?: string;
+    };
+}
+
+/**
+ * Override the account's default billing entity for this specific buy. When provided, the seller invoices this entity instead. The seller MUST validate the invoice recipient is authorized for this account. When governance_agents are configured, the seller MUST include invoice_recipient in the check_governance request.
+ */
+export interface BusinessEntity {
+    /**
+     * Registered legal name of the business entity
+     * @maxLength 200
+     */
+    legal_name: string;
+    /**
+     * VAT identification number (e.g., DE123456789 for Germany, FR12345678901 for France). Required for B2B invoicing in the EU. Must be normalized: no spaces, dots, or dashes.
+     * @pattern ^[A-Z]{2}[A-Z0-9]{2,13}$
+     */
+    vat_id?: string;
+    /**
+     * Tax identification number for jurisdictions that do not use VAT (e.g., US EIN)
+     * @maxLength 30
+     */
+    tax_id?: string;
+    /**
+     * Company registration number (e.g., HRB 12345 for German Handelsregister)
+     * @maxLength 50
+     */
+    registration_number?: string;
+    /**
+     * Postal address for invoicing and legal correspondence
+     */
+    address?: {
+        /**
+         * Street address including building number
+         * @maxLength 200
+         */
+        street: string;
+        /**
+         * @maxLength 100
+         */
+        city: string;
+        /**
+         * @maxLength 20
+         */
+        postal_code: string;
+        /**
+         * State, province, or region
+         * @maxLength 100
+         */
+        region?: string;
+        /**
+         * ISO 3166-1 alpha-2 country code
+         * @pattern ^[A-Z]{2}$
+         */
+        country: string;
+    };
+    /**
+     * Contacts for billing, legal, and operational matters. Contains personal data subject to GDPR and equivalent regulations. Implementations MUST use this data only for invoicing and account management.
+     */
+    contacts?: {
+        /**
+         * Contact's functional role in the business relationship
+         */
+        role: 'billing' | 'legal' | 'creative' | 'general';
+        /**
+         * Full name of the contact
+         * @maxLength 200
+         */
+        name?: string;
+        /**
+         * @maxLength 254
+         * @format email
+         */
+        email?: string;
+        /**
+         * @maxLength 30
+         */
+        phone?: string;
+    }[];
+    /**
+     * Bank account details for payment processing. Write-only: included in requests to provide payment coordinates, but MUST NOT be echoed in responses. Sellers store these details and confirm receipt without returning them.
+     */
+    bank?: {
+        /**
+         * Name on the bank account
+         * @maxLength 200
+         */
+        account_holder: string;
+        /**
+         * International Bank Account Number (SEPA markets)
+         * @pattern ^[A-Z]{2}[0-9]{2}[A-Z0-9]{4,30}$
+         */
+        iban?: string;
+        /**
+         * Bank Identifier Code / SWIFT code (SEPA markets)
+         * @pattern ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$
+         */
+        bic?: string;
+        /**
+         * Bank routing number for non-SEPA markets (e.g., US ABA routing number, Canadian transit/institution number)
+         * @maxLength 30
+         */
+        routing_number?: string;
+        /**
+         * Bank account number for non-SEPA markets
+         * @maxLength 30
+         */
+        account_number?: string;
+    };
+    ext?: ExtensionObject;
+}
+
+/**
+ * C2PA action classification for this watermark
+ */
+export type C2PAWatermarkAction = 'c2pa.watermarked.bound' | 'c2pa.watermarked.unbound';
+
+/**
+ * Which party initiated the package cancellation.
+ */
+export type CanceledBy = 'buyer' | 'seller';
+
+/**
+ * Cloud storage protocol
+ */
+export type CloudStorageProtocol = 's3' | 'gcs' | 'azure_blob';
+
+/**
+ * Reference to a collection list for including specific collections (programs, shows) within this product. The package runs on the intersection of matched collections and this list. Use for inclusion-based collection targeting. Seller must declare support in get_adcp_capabilities.
+ */
+export interface CollectionListReference {
+    /**
+     * URL of the agent managing the collection list
+     */
+    agent_url: string;
+    /**
+     * Identifier for the collection list within the agent
+     * @minLength 1
+     */
+    list_id: string;
+    /**
+     * JWT or other authorization token for accessing the list. Optional if the list is public or caller has implicit access.
+     */
+    auth_token?: string;
+}
+
+/**
+ * Opaque correlation data that is echoed unchanged in responses. Used for internal tracking, UI session IDs, trace IDs, and other caller-specific identifiers that don't affect protocol behavior. Context data is never parsed by AdCP agents - it's simply preserved and returned.
+ */
+export interface ContextObject {
+}
+
+/**
+ * Approval state of a creative on a specific package
+ */
+export type CreativeApprovalStatus = 'pending_review' | 'approved' | 'rejected';
+
+/**
+ * Days of the week for daypart targeting
+ */
+export type DayOfWeek = 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sunday';
+
+/**
+ * A time window for daypart targeting. Specifies days of week and an hour range. start_hour is inclusive, end_hour is exclusive (e.g., 6-10 = 6:00am to 10:00am). Follows the Google Ads AdScheduleInfo / DV360 DayPartTargeting pattern.
+ */
+export interface DaypartTarget {
+    /**
+     * Days of week this window applies to. Use multiple days for compact targeting (e.g., monday-friday in one object).
+     */
+    days: DayOfWeek[];
+    /**
+     * Start hour (inclusive), 0-23 in 24-hour format. 0 = midnight, 6 = 6:00am, 18 = 6:00pm.
+     * @minimum 0
+     * @maximum 23
+     */
+    start_hour: number;
+    /**
+     * End hour (exclusive), 1-24 in 24-hour format. 10 = 10:00am, 24 = midnight. Must be greater than start_hour.
+     * @minimum 1
+     * @maximum 24
+     */
+    end_hour: number;
+    /**
+     * Optional human-readable name for this time window (e.g., 'Morning Drive', 'Prime Time')
+     */
+    label?: string;
+}
+
+/**
+ * Operating system platforms for device targeting. Browser values from Sec-CH-UA-Platform standard, extended for CTV.
+ */
+export type DevicePlatform = 'ios' | 'android' | 'windows' | 'macos' | 'linux' | 'chromeos' | 'tvos' | 'tizen' | 'webos' | 'fire_os' | 'roku_os' | 'unknown';
+
+/**
+ * Device form factor categories for targeting and reporting. Complements device-platform (operating system) with hardware classification. OpenRTB mapping: 1 (Mobile/Tablet General) → mobile, 2 (PC) → desktop, 4 (Phone) → mobile, 5 (Tablet) → tablet, 6 (Connected Device) → ctv, 7 (Set Top Box) → ctv. DOOH inventory uses dooh.
+ */
+export type DeviceType = 'desktop' | 'mobile' | 'tablet' | 'ctv' | 'dooh' | 'unknown';
+
+/**
+ * IPTC-aligned classification of AI involvement in producing this content
+ */
+export type DigitalSourceType = 'digital_capture' | 'digital_creation' | 'trained_algorithmic_media' | 'composite_with_trained_algorithmic_media' | 'algorithmic_media' | 'composite_capture' | 'composite_synthetic' | 'human_edits' | 'data_driven_media';
+
+/**
+ * How long the disclosure must persist during content playback or display
+ */
+export type DisclosurePersistence = 'continuous' | 'initial' | 'flexible';
+
+/**
+ * Where a required disclosure should appear within a creative. Used by creative briefs to specify disclosure placement and by formats to declare which positions they can render.
+ */
+export type DisclosurePosition = 'prominent' | 'footer' | 'audio' | 'subtitle' | 'overlay' | 'end_card' | 'pre_roll' | 'companion';
+
+/**
+ * A time duration expressed as an interval and unit. Used for frequency cap windows, attribution windows, reach optimization windows, time budgets, and other time-based settings. When unit is 'campaign', interval must be 1 — the window spans the full campaign flight.
+ */
+export interface Duration {
+    /**
+     * Number of time units. Must be 1 when unit is 'campaign'.
+     * @minimum 1
+     */
+    interval: number;
+    /**
+     * Time unit. 'seconds' for sub-minute precision. 'campaign' spans the full campaign flight.
+     */
+    unit: 'seconds' | 'minutes' | 'hours' | 'days' | 'campaign';
+}
+
+/**
+ * How provenance data is carried within the content
+ */
+export type EmbeddedProvenanceMethod = 'manifest_wrapper' | 'provenance_markers';
+
+/**
+ * Extension object for platform-specific, vendor-namespaced parameters. Extensions are always optional and must be namespaced under a vendor/platform key (e.g., ext.gam, ext.roku). Used for custom capabilities, partner-specific configuration, and features being proposed for standardization.
+ */
+export interface ExtensionObject {
+}
+
+/**
+ * A JSON object — never a plain string — that identifies a creative format by its declaring agent and local slug. Required properties: agent_url (URI of the agent that owns the format) and id (slug matching [a-zA-Z0-9_-]+). Example: {"agent_url": "https://creative.adcontextprotocol.org", "id": "display_300x250"}. Can reference: (1) a concrete format with fixed dimensions (id only), (2) a template format without parameters (id only), or (3) a template format with parameters (id + dimensions/duration). Template formats accept parameters in format_id while concrete formats have fixed dimensions in their definition. Parameterized format IDs create unique, specific format variants. Using a plain string here is a schema violation.
+ */
+export interface FormatReferenceStructuredObject {
+    /**
+     * URL of the agent that defines this format (e.g., 'https://creative.adcontextprotocol.org' for standard formats, or 'https://publisher.com/.well-known/adcp/sales' for custom formats). Callers comparing two `format-id` values MUST canonicalize `agent_url` per the AdCP URL canonicalization rules before treating two formats as the same. See docs/reference/url-canonicalization.
+     */
+    agent_url: string;
+    /**
+     * Format identifier within the agent's namespace (e.g., 'display_static', 'video_hosted', 'audio_standard'). When used alone, references a template format. When combined with dimension/duration fields, creates a parameterized format ID for a specific variant.
+     * @pattern ^[a-zA-Z0-9_-]+$
+     */
+    id: string;
+    /**
+     * Width in pixels for visual formats. When specified, height must also be specified. Both fields together create a parameterized format ID for dimension-specific variants.
+     * @minimum 1
+     */
+    width?: number;
+    /**
+     * Height in pixels for visual formats. When specified, width must also be specified. Both fields together create a parameterized format ID for dimension-specific variants.
+     * @minimum 1
+     */
+    height?: number;
+    /**
+     * Duration in milliseconds for time-based formats (video, audio). When specified, creates a parameterized format ID. Omit to reference a template format without parameters.
+     * @minimum 1
+     */
+    duration_ms?: number;
+}
+
+/**
+ * Frequency capping settings for package-level application. Two types of frequency control can be used independently or together: suppress enforces a cooldown between consecutive exposures; max_impressions + per + window caps total exposures per entity in a time window. When both suppress and max_impressions are set, an impression is delivered only if both constraints permit it (AND semantics). At least one of suppress, suppress_minutes, or max_impressions must be set.
+ */
+export type FrequencyCap = {
+    [k: string]: unknown | undefined;
+} & {
+    /**
+     * Cooldown period between consecutive exposures to the same entity. Prevents back-to-back ad delivery (e.g. {"interval": 60, "unit": "minutes"} for a 1-hour cooldown). Preferred over suppress_minutes.
+     */
+    suppress?: Duration;
+    /**
+     * Deprecated — use suppress instead. Cooldown period in minutes between consecutive exposures to the same entity (e.g. 60 for a 1-hour cooldown).
+     * @minimum 0
+     */
+    suppress_minutes?: number;
+    /**
+     * Maximum number of impressions per entity per window. For duration windows, implementations typically use a rolling window; 'campaign' applies a fixed cap across the full flight.
+     * @minimum 1
+     */
+    max_impressions?: number;
+    /**
+     * Entity granularity for impression counting. Required when max_impressions is set.
+     */
+    per?: ReachUnit;
+    /**
+     * Time window for the max_impressions cap (e.g. {"interval": 7, "unit": "days"} or {"interval": 1, "unit": "campaign"} for the full flight). Required when max_impressions is set.
+     */
+    window?: Duration;
+};
+
+/**
+ * Override logo asset.
+ */
+export interface ImageAsset {
+    /**
+     * Discriminator identifying this as an image asset. See /schemas/creative/asset-types for the registry.
+     */
+    asset_type: 'image';
+    /**
+     * URL to the image asset
+     */
+    url: string;
+    /**
+     * Width in pixels
+     * @minimum 1
+     */
+    width: number;
+    /**
+     * Height in pixels
+     * @minimum 1
+     */
+    height: number;
+    /**
+     * Image file format (jpg, png, gif, webp, etc.)
+     */
+    format?: string;
+    /**
+     * Alternative text for accessibility
+     */
+    alt_text?: string;
+    provenance?: Provenance;
+}
+
+/**
+ * A single upstream dependency state change that affects delivery for one or more packages within a media buy. An impairment is open until the underlying resource returns to a serviceable state. Materiality: an impairment MUST list at least one package whose ability to serve is degraded; cosmetic-only effects (e.g., one rejected creative when peers remain serviceable in the same package) MUST NOT be reported as impairments. Sellers MAY report conservatively when uncertain (list a package when the materiality join is expensive to compute); sellers MUST NOT report when serving is provably unaffected. Materiality is required (MUST) for resource types where the resource→buy join is cheap and 1:N — audience, event_source, property; SHOULD-strength for creative and catalog_item, where the resource is shared across a larger pool and the join cost is higher.
+ */
+export interface Impairment {
+    /**
+     * Stable identifier for this impairment, used as the notification_id when the impairment fires via webhook. Stable across re-emissions of the same open impairment (e.g., the seller re-fires after the buyer's receiver was down) and across the closing fire that signals resolution. A new impairment for the same resource_id after closure receives a new impairment_id. Distinct from the per-fire idempotency_key issued at the webhook transport layer — see snapshot-and-log Rule 1. Receivers correlate webhook fires to current impairments[] state by impairment_id; receivers suppress duplicate transport-layer retries by idempotency_key. Seeing the same impairment_id with different idempotency_keys is a re-emission signal, not a retry — the buyer should treat it as a notice that something may have been missed.
+     */
+    impairment_id: string;
+    /**
+     * The kind of upstream dependency that transitioned to an offline state. Values are drawn from the x-entity vocabulary (see core/x-entity-types.json) and identify a buyer-referenced object with its own lifecycle that the seller can take offline. This is the subset of x-entity types for which a media buy's serving depends on the resource — not a new typology, just the impairment-relevant slice.
+     */
+    resource_type: 'audience' | 'creative' | 'catalog_item' | 'event_source' | 'property';
+    /**
+     * Seller's identifier for the specific resource that transitioned. References the same id space as the corresponding sync_/list_ task responses (e.g., audience_id, creative_id).
+     */
+    resource_id: string;
+    /**
+     * Packages within this media buy whose delivery is degraded by the impairment. MUST list at least one package — cosmetic effects that do not degrade any package's ability to serve MUST NOT be reported as impairments.
+     */
+    package_ids: string[];
+    /**
+     * The resource-level status transition that triggered this impairment.
+     */
+    transition: {
+        /**
+         * Prior status of the resource (e.g., 'ready', 'approved', 'good'). Optional — sellers SHOULD include when known, MAY omit when the resource was discovered already in an offline state (e.g., a property depublished via brand.json crawl with no prior snapshot). Open string at the schema layer because each resource_type has its own serviceable-state vocabulary; the pattern constraint blocks free-form garbage, and the impairment.coherence assertion validates that 'from' is a known serviceable value for the resource_type.
+         * @pattern ^[a-z][a-z0-9_]*$
+         */
+        from?: string;
+        to: ImpairmentOfflineState;
+    };
+    reason_code: ImpairmentReasonCode;
+    /**
+     * Human-readable explanation. Supplements reason_code with seller-specific detail.
+     * @maxLength 500
+     */
+    reason?: string;
+    /**
+     * ISO 8601 timestamp when the seller observed the resource transition to its offline state.
+     * @format date-time
+     */
+    observed_at: string;
+    /**
+     * Action the buyer can take to clear the impairment, if any. Free text. Absent when no buyer-side remediation is possible (e.g., seller-initiated withdrawal pending re-publication).
+     * @maxLength 500
+     */
+    remediation?: string;
+}
+
+/**
+ * Current (offline) status of the resource. Drawn from the resource_type's canonical lifecycle enum; see impairment-offline-state for per-value resource_type pairing. The pairing is validated by impairment.coherence.
+ */
+export type ImpairmentOfflineState = 'suspended' | 'rejected' | 'withdrawn' | 'insufficient' | 'depublished';
+
+/**
+ * Categorical reason for the offline transition. Drives buyer-side remediation logic.
+ */
+export type ImpairmentReasonCode = 'policy_violation' | 'consent_expired' | 'ttl_expired' | 'pii_audit_failed' | 'seller_removed' | 'content_rejected' | 'source_offline' | 'property_depublished';
+
+/**
+ * Keyword targeting match type. broad: ads may serve on queries semantically related to the keyword. phrase: ads serve when the query contains the keyword phrase. exact: ads serve only when the query matches the keyword exactly.
+ */
+export type MatchType = 'broad' | 'phrase' | 'exact';
+
+/**
+ * How a seller honors a given action on a media buy. Buyers branch on this to decide whether to expect a synchronous response, an automatic-with-fallback flow, a proposal lifecycle round-trip, or an asynchronous human approval. The mode is declared on each entry of `allowed_actions[]` (product, as `modes[]` array) or `available_actions[]` (buy, as singular `mode`).
+ */
+export type MediaBuyActionMode = 'self_serve' | 'conditional_self_serve' | 'requires_proposal' | 'requires_approval';
+
+/**
+ * An action currently available on a media buy, resolved against the buy's current status, negotiated terms, account tier, and any buy-level overrides. Authoritative per-buy capability — buyer SDKs MUST read this rather than re-deriving from the product's `allowed_actions[]`, because divergence from the product template is expected (negotiated terms and IO addenda live on the deal, not the product SKU). The containing `available_actions[]` array is uniquely keyed by `action`; sellers MUST NOT emit two entries with the same `action` value (this is a contract-level invariant — JSON Schema `uniqueItems` only catches structurally identical objects, so validators MUST enforce action-uniqueness separately). Predicate evaluators consuming dotted paths like `available_actions.extend_flight.sla.response_max` MUST index by `action` rather than by array position. The `mode` and `sla` values are advisory at the moment of emission; sellers MAY resolve to a different mode by the time the mutation arrives (state can change), in which case the request is rejected with `ACTION_NOT_ALLOWED` (`reason: mode_mismatch`).
+ */
+export interface MediaBuyAvailableAction {
+    action: MediaBuyValidAction;
+    mode: MediaBuyActionMode;
+    sla?: SLAWindow;
+    /**
+     * Optional pointer into buy-terms negotiation (forward-references the buy-terms namespace landing via separate RFC). Schema accepts any string for now and will tighten to a structured reference when the buy-terms RFC ships.
+     */
+    terms_ref?: string;
+}
+
+/**
+ * Aggregate health of a media buy based on upstream dependency state. Orthogonal to media-buy-status — a buy can be paused-and-impaired, pending-and-impaired, or active-and-impaired. Always set; defaults to 'ok' when no open impairments exist.
+ */
+export type MediaBuyHealth = 'ok' | 'impaired';
+
+/**
+ * Status of a media buy.
+ */
+export type MediaBuyStatus = 'pending_creatives' | 'pending_start' | 'active' | 'paused' | 'completed' | 'rejected' | 'canceled';
+
+/**
+ * The action identifier.
+ */
+export type MediaBuyValidAction = 'pause' | 'resume' | 'cancel' | 'extend_flight' | 'shorten_flight' | 'update_flight_dates' | 'increase_budget' | 'decrease_budget' | 'reallocate_budget' | 'update_targeting' | 'update_pacing' | 'update_frequency_caps' | 'replace_creative' | 'update_creative_assignments' | 'remove_creative' | 'add_packages' | 'remove_packages' | 'update_budget' | 'update_dates' | 'update_packages' | 'sync_creatives';
+
+/**
+ * Metro classification system
+ */
+export type MetroAreaSystem = 'nielsen_dma' | 'uk_itl1' | 'uk_itl2' | 'eurostat_nuts2' | 'custom';
+
+/**
+ * Account-level webhook subscription for notifications whose lifecycle outlives any single media buy — creative state changes, library purges, wholesale feed change webhooks, and future account-scoped events. Distinct from `push-notification-config.json`, which anchors at a per-resource operation (a single task or media buy). An account MAY register multiple notification configs to fan a single seller's events out to multiple buyer-side endpoints; each entry filters by `event_types`. As with push-notification-config, the default signing scheme is the AdCP RFC 9421 webhook profile against the seller's brand.json `agents[]` JWKS; the optional `authentication` block opts into the deprecated Bearer / HMAC-SHA256 fallback for compatibility. Credentials and shared secrets in `authentication.credentials` are write-only — sellers MUST NOT echo them back in `list_accounts` responses. Sellers MUST verify endpoint control before activating account-level notification configs for high-volume event families such as wholesale feed changes; delivery-time SSRF validation still applies to every fire.
+ */
+export interface NotificationConfig {
+    /**
+     * Buyer-supplied identifier for this subscription endpoint. Echoed on every webhook payload and on every `webhook_activity[]` record fired against this config so the buyer can attribute fires across multiple endpoints. MUST be unique within the account's `notification_configs[]` — uniqueness is enforced by the seller at registration time; duplicates are rejected with `errors[]`. Always required (even with a single subscriber) so the SDK contract is uniform — no conditional required-when-multiple rules to trip up implementations. Format is opaque — recommended values are short kebab-case slugs (`buyer-primary`, `audit-bus`, `dx-team`).
+     * @minLength 1
+     * @maxLength 64
+     * @pattern ^[A-Za-z0-9_.:-]{1,64}$
+     */
+    subscriber_id: string;
+    /**
+     * Webhook endpoint URL. Same wire contract as `push-notification-config.url` — `format: "uri"`, no destination-port allowlist enforced by the protocol, SSRF protection via the IP-range check defined in docs/building/by-layer/L1/security.mdx#webhook-url-validation-ssrf. For wholesale feed subscribers, sellers MUST complete an activation challenge or equivalent proof-of-control before treating the subscriber as active.
+     */
+    url: string;
+    /**
+     * Notification types this subscriber wishes to receive on the registered `url`. The seller MUST NOT fire other types against this endpoint, and MUST NOT silently widen the filter when new types are added to `notification-type.json`. When omitted, the seller MUST default to a no-fire policy and surface an `errors[]` entry on `sync_accounts` so the buyer notices the missing filter. Values are drawn from `notification-type.json`, but only types whose contract anchors at the account scope are valid here — creative lifecycle events and wholesale feed change payloads are valid; media-buy-anchored types (`scheduled`, `final`, `delayed`, `adjusted`, `impairment`) belong on a media buy's `push_notification_config`, not on this surface; sellers MUST reject those entries as per-account validation failures with `INVALID_REQUEST` or `VALIDATION_ERROR` and `error.field` pointing at the invalid `event_types` entry rather than silently dropping them.
+     */
+    event_types: NotificationType[];
+    /**
+     * Legacy authentication selector. Same precedence and semantics as `push-notification-config.authentication` — presence opts the seller into Bearer or HMAC-SHA256 signing; absence selects the default RFC 9421 webhook profile keyed off the seller's brand.json `agents[]` JWKS. The same signed-registration downgrade-resistance rules apply to accounts[].notification_configs[].authentication. Deprecated; removed in AdCP 4.0. Credentials are write-only and MUST NOT be echoed on `list_accounts` reads.
+     */
+    authentication?: {
+        schemes: AuthenticationScheme[];
+        /**
+         * Credentials for the legacy scheme. Bearer: token. HMAC-SHA256: shared secret. Minimum 32 characters. Exchanged out-of-band during onboarding. Write-only.
+         * @minLength 32
+         */
+        credentials: string;
+    };
+    /**
+     * When false, the seller persists the configuration but suppresses fires. Use to pause a noisy subscriber without losing the registration. Sellers MUST NOT skip persisting the entry when `active: false` — the buyer's next `sync_accounts` MUST observe the same array, otherwise the buyer cannot distinguish pause from drop.
+     */
+    active?: boolean;
+    ext?: ExtensionObject;
+}
+
+/**
+ * Type of push notification fired by a seller agent. Media-buy-anchored notifications (`scheduled`, `final`, `delayed`, `adjusted`, `impairment`) fire against a media buy's `push_notification_config`. Account-anchored notifications (`creative.status_changed`, `creative.purged`, `product.*`, `signal.*`, `wholesale_feed.bulk_change`) fire against an account's `notification_configs[]` entries whose `event_types` include the value — these outlive any single media buy and anchor at the account. Wholesale feed notifications carry the actual change payload in `/schemas/core/wholesale-feed-webhook.json`; receivers use `get_products` / `get_signals` with `if_wholesale_feed_version` to repair or reconcile. New notification types added to this enum MUST declare their anchor (media-buy or account) and per-type `notification_id` semantics in the enumDescription. Sellers MUST reject `notification_configs[]` entries whose `event_types` include any media-buy-anchored type, and MUST reject `push_notification_config` registrations for account-anchored types.
+ */
+export type NotificationType = 'scheduled' | 'final' | 'delayed' | 'adjusted' | 'impairment' | 'creative.status_changed' | 'creative.purged' | 'product.created' | 'product.updated' | 'product.priced' | 'product.removed' | 'signal.created' | 'signal.updated' | 'signal.priced' | 'signal.removed' | 'wholesale_feed.bulk_change';
+
+/**
+ * Current status of a package within a media buy — includes creative approval state and optional delivery snapshot. For the creation input shape, see PackageRequest. For the creation output shape, see Package.
+ */
+export interface PackageStatus {
+    /**
+     * Seller's package identifier
+     */
+    package_id: string;
+    /**
+     * Product identifier this package is purchased from
+     */
+    product_id?: string;
+    /**
+     * Package budget amount, denominated in package.currency when present, otherwise media_buy.currency
+     * @minimum 0
+     */
+    budget?: number;
+    /**
+     * ISO 4217 currency code for monetary values at this package level (budget, bid_price, snapshot.spend). When absent, inherit media_buy.currency.
+     * @pattern ^[A-Z]{3}$
+     */
+    currency?: string;
+    /**
+     * Current bid price for auction-based packages. Denominated in package.currency when present, otherwise media_buy.currency. Relevant for automated price optimization loops.
+     * @minimum 0
+     */
+    bid_price?: number;
+    /**
+     * Goal impression count for impression-based packages
+     * @minimum 0
+     */
+    impressions?: number;
+    targeting_overlay?: TargetingOverlay;
+    /**
+     * ISO 8601 flight start time for this package. Use to determine whether the package is within its scheduled flight before interpreting delivery status.
+     * @format date-time
+     */
+    start_time?: string;
+    /**
+     * ISO 8601 flight end time for this package
+     * @format date-time
+     */
+    end_time?: string;
+    /**
+     * Whether this package is currently paused by the buyer
+     */
+    paused?: boolean;
+    /**
+     * Whether this package has been canceled. Canceled packages stop delivery and cannot be reactivated.
+     */
+    canceled?: boolean;
+    /**
+     * Cancellation metadata. Present only when canceled is true.
+     */
+    cancellation?: {
+        /**
+         * ISO 8601 timestamp when this package was canceled.
+         * @format date-time
+         */
+        canceled_at: string;
+        canceled_by: CanceledBy;
+        /**
+         * Reason the package was canceled.
+         * @maxLength 500
+         */
+        reason?: string;
+    };
+    /**
+     * ISO 8601 timestamp for creative upload or change deadline for this package. After this deadline, creative changes are rejected. When absent, the media buy's creative_deadline applies.
+     * @format date-time
+     */
+    creative_deadline?: string;
+    /**
+     * Approval status for each creative assigned to this package. Absent when no creatives have been assigned.
+     */
+    creative_approvals?: {
+        /**
+         * Creative identifier
+         */
+        creative_id: string;
+        approval_status?: CreativeApprovalStatus;
+        /**
+         * Human-readable explanation of why the creative was rejected. Present only when approval_status is 'rejected'.
+         */
+        rejection_reason?: string;
+    }[];
+    /**
+     * Format IDs from the original create_media_buy format_ids_to_provide that have not yet been uploaded via sync_creatives. When empty or absent, all required formats have been provided.
+     */
+    format_ids_pending?: FormatReferenceStructuredObject[];
+    snapshot_unavailable_reason?: SnapshotUnavailableReason;
+    /**
+     * Near-real-time delivery snapshot for this package. Only present when include_snapshot was true in the request. Represents the latest available entity-level stats from the platform — not billing-grade data.
+     */
+    snapshot?: {
+        /**
+         * ISO 8601 timestamp when this snapshot was captured by the platform
+         * @format date-time
+         */
+        as_of: string;
+        /**
+         * Maximum age of this data in seconds. For example, 900 means the data may be up to 15 minutes old. Use this to interpret zero delivery: a value of 900 means zero impressions is likely real; a value of 14400 means reporting may still be catching up.
+         * @minimum 0
+         */
+        staleness_seconds: number;
+        /**
+         * Total impressions delivered since package start
+         * @minimum 0
+         */
+        impressions: number;
+        /**
+         * Total spend since package start, denominated in snapshot.currency when present, otherwise package.currency or media_buy.currency
+         * @minimum 0
+         */
+        spend: number;
+        /**
+         * ISO 4217 currency code for spend in this snapshot. Optional when unchanged from package.currency or media_buy.currency.
+         * @pattern ^[A-Z]{3}$
+         */
+        currency?: string;
+        /**
+         * Total clicks since package start (when available)
+         * @minimum 0
+         */
+        clicks?: number;
+        /**
+         * Current delivery pace relative to expected (1.0 = on track, <1.0 = behind, >1.0 = ahead). Absent when pacing cannot be determined.
+         * @minimum 0
+         */
+        pacing_index?: number;
+        /**
+         * Operational delivery state of this package. 'not_delivering' means the package is within its scheduled flight but has delivered zero impressions for at least one full staleness cycle — the signal for automated price adjustments or buyer alerts. Implementers must not return 'not_delivering' until at least staleness_seconds have elapsed since package activation.
+         */
+        delivery_status?: 'delivering' | 'not_delivering' | 'completed' | 'budget_exhausted' | 'flight_ended' | 'goal_met';
+        ext?: ExtensionObject;
+    };
+    ext?: ExtensionObject;
+}
+
+/**
+ * Standard cursor-based pagination parameters for list operations
+ */
+export interface PaginationRequest {
+    /**
+     * Maximum number of items to return per page
+     * @minimum 1
+     * @maximum 100
+     */
+    max_results?: number;
+    /**
+     * Opaque cursor from a previous response to fetch the next page
+     */
+    cursor?: string;
+}
+
+/**
+ * Standard cursor-based pagination metadata for list responses
+ */
+export interface PaginationResponse {
+    /**
+     * Whether more results are available beyond this page
+     */
+    has_more: boolean;
+    /**
+     * Opaque cursor to pass in the next request to fetch the next page. Only present when has_more is true.
+     */
+    cursor?: string;
+    /**
+     * Total number of items matching the query across all pages. Optional because not all backends can efficiently compute this.
+     * @minimum 0
+     */
+    total_count?: number;
+}
+
+/**
+ * Payment terms agreed for this account. Binding for all invoices when the account is active.
+ */
+export type PaymentTerms = 'net_15' | 'net_30' | 'net_45' | 'net_60' | 'net_90' | 'prepay';
+
+/**
+ * Postal code system (e.g., 'us_zip', 'gb_outward')
+ */
+export type PostalCodeSystem = 'us_zip' | 'us_zip_plus_four' | 'gb_outward' | 'gb_full' | 'ca_fsa' | 'ca_full' | 'de_plz' | 'fr_code_postal' | 'au_postcode' | 'ch_plz' | 'at_plz';
+
+/**
+ * [AdCP 3.0] Reference to an externally managed property list. When provided, the sales agent should filter products to only those available on properties in the list.
+ */
+export interface PropertyListReference {
+    /**
+     * URL of the agent managing the property list
+     */
+    agent_url: string;
+    /**
+     * Identifier for the property list within the agent
+     * @minLength 1
+     */
+    list_id: string;
+    /**
+     * JWT or other authorization token for accessing the list. Optional if the list is public or caller has implicit access.
+     */
+    auth_token?: string;
+}
+
+/**
+ * Provenance metadata for this asset, overrides manifest-level provenance
+ */
+export interface Provenance {
+    digital_source_type?: DigitalSourceType;
+    /**
+     * AI system used to generate or modify this content. Aligns with IPTC 2025.1 AI metadata fields and C2PA claim_generator.
+     */
+    ai_tool?: {
+        /**
+         * Name of the AI tool or model (e.g., 'DALL-E 3', 'Stable Diffusion XL', 'Gemini')
+         */
+        name: string;
+        /**
+         * Version identifier for the AI tool or model (e.g., '25.1', '0125', '2.1'). For generative models, use the model version rather than the API version.
+         */
+        version?: string;
+        /**
+         * Organization that provides the AI tool (e.g., 'OpenAI', 'Stability AI', 'Google')
+         */
+        provider?: string;
+    };
+    /**
+     * Level of human involvement in the AI-assisted creation process. Independent of `disclosure.required` — the protocol does not derive disclosure obligations from oversight level. Some regulations include carve-outs for human-edited or human-directed AI output, but those carve-outs have factual prerequisites the schema cannot evaluate. Asserting `edited` or `directed` does not by itself justify `disclosure.required: false`.
+     */
+    human_oversight?: 'none' | 'prompt_only' | 'selected' | 'edited' | 'directed';
+    /**
+     * Party declaring this provenance. Identifies who attached the provenance claim, enabling receiving parties to assess trust.
+     */
+    declared_by?: {
+        /**
+         * URL of the agent or service that declared this provenance
+         */
+        agent_url?: string;
+        /**
+         * Role of the declaring party in the supply chain
+         */
+        role: 'creator' | 'advertiser' | 'agency' | 'platform' | 'tool';
+    };
+    /**
+     * When this provenance claim was made (ISO 8601). Distinct from created_time, which records when the content itself was produced. A provenance claim may be attached well after content creation, for example when retroactively declaring AI involvement for regulatory compliance.
+     * @format date-time
+     */
+    declared_at?: string;
+    /**
+     * When this content was created or generated (ISO 8601)
+     * @format date-time
+     */
+    created_time?: string;
+    /**
+     * C2PA sidecar manifest reference. Links to a detached cryptographic provenance manifest for this content. Note: file-level C2PA bindings break when ad servers transcode, resize, or re-encode assets. For pipelines with intermediaries, consider embedded_provenance as the primary provenance mechanism.
+     */
+    c2pa?: {
+        /**
+         * URL to the C2PA manifest store for this content
+         */
+        manifest_url: string;
+    };
+    /**
+     * Provenance metadata embedded within the content stream. Each entry declares one embedding layer: structured provenance data carried inside the content itself, as distinct from sidecar references (c2pa.manifest_url). Embedded provenance survives operations that break sidecar and file-level bindings: ad-server transcoding, CMS ingestion, copy-paste, reformatting, and CDN re-encoding. For ad-tech pipelines where content passes through multiple intermediaries, embedded provenance is the reliable path for provenance that persists from declaration through delivery. This is a declaration by the embedding party. The receiving party (the seller) is the verifier-of-record: it confirms the claim by calling a governance agent it trusts (typically one published in `creative_policy.accepted_verifiers`).
+     */
+    embedded_provenance?: {
+        method: EmbeddedProvenanceMethod;
+        /**
+         * Standard the embedding conforms to, if any (e.g., 'c2pa' for C2PA Section A.7 text manifest embedding)
+         */
+        standard?: string;
+        /**
+         * Organization that performed the embedding (e.g., 'Encypher', 'Digimarc'). Display label and audit context — not a wire identifier.
+         */
+        provider: string;
+        /**
+         * Buyer's representation that this embedding can be verified by a governance agent on the seller's `creative_policy.accepted_verifiers` list. The `agent_url` MUST match (canonicalized) one of the seller's published `accepted_verifiers[].agent_url` entries; sellers reject `sync_creatives` submissions whose `verify_agent.agent_url` is off-list with `PROVENANCE_VERIFIER_NOT_ACCEPTED`. This is buyer-supplied evidence, not buyer-driven routing — the seller is the verifier-of-record and the seller controls which agent it actually calls (the seller MAY use a different on-list agent if it determines this is more appropriate; the seller does not call buyer-asserted endpoints outside its allowlist). MAY be omitted for self-verifiable embeddings (e.g., a C2PA text manifest with a public key the seller already trusts).
+         */
+        verify_agent?: {
+            /**
+             * URL of the governance agent the buyer represents was used to embed/verify this layer. MUST use the `https://` scheme and MUST appear in the seller's `creative_policy.accepted_verifiers[].agent_url` list (canonicalized per /docs/reference/url-canonicalization: lowercase scheme and host, strip default port, normalize path dot-segments). Sellers MUST NOT call this URL until the canonicalized match is confirmed.
+             * @pattern ^https:\/\/
+             */
+            agent_url: string;
+            /**
+             * Optional `feature_id` the buyer represents the seller should request via `get_creative_features` (e.g., `encypher.markers_present_v2`). SHOULD match the `feature_id` declared on the matching `accepted_verifiers[]` entry, or be omitted to defer the selector to the seller. When the seller's entry pins a `feature_id`, that value wins; when neither side pins, the seller selects from the agent's `governance.creative_features` catalog.
+             */
+            feature_id?: string;
+        };
+        /**
+         * When the provenance data was embedded (ISO 8601)
+         * @format date-time
+         */
+        embedded_at?: string;
+    }[];
+    /**
+     * Content watermarks applied to this asset. Each entry declares one watermarking layer: a content modification that encodes an identifier or fingerprint within the asset. Watermarks differ from embedded provenance: a watermark encodes an identifier (who generated it, who owns it), while embedded provenance carries or references a structured provenance record (the full chain of custody). A single asset may carry both. Aligns with C2PA action taxonomy: c2pa.watermarked.bound (watermark linked to a C2PA manifest) and c2pa.watermarked.unbound (watermark independent of any manifest). This is a declaration by the watermarking party. The receiving party (the seller) is the verifier-of-record: it confirms the claim by calling a governance agent it trusts (typically one published in `creative_policy.accepted_verifiers`).
+     */
+    watermarks?: {
+        media_type: WatermarkMediaType;
+        /**
+         * Organization that applied the watermark (e.g., 'Imatag', 'Steg.AI', 'Encypher'). Display label and audit context — not a wire identifier.
+         */
+        provider: string;
+        /**
+         * Buyer's representation that this watermark can be detected by a governance agent on the seller's `creative_policy.accepted_verifiers` list. The `agent_url` MUST match (canonicalized) one of the seller's published `accepted_verifiers[].agent_url` entries; sellers reject `sync_creatives` submissions whose `verify_agent.agent_url` is off-list with `PROVENANCE_VERIFIER_NOT_ACCEPTED`. This is buyer-supplied evidence, not buyer-driven routing — the seller is the verifier-of-record and the seller controls which agent it actually calls (the seller MAY use a different on-list agent if it determines this is more appropriate; the seller does not call buyer-asserted endpoints outside its allowlist).
+         */
+        verify_agent?: {
+            /**
+             * URL of the governance agent the buyer represents was used to apply/detect this watermark. MUST use the `https://` scheme and MUST appear in the seller's `creative_policy.accepted_verifiers[].agent_url` list (canonicalized per /docs/reference/url-canonicalization: lowercase scheme and host, strip default port, normalize path dot-segments). Sellers MUST NOT call this URL until the canonicalized match is confirmed.
+             * @pattern ^https:\/\/
+             */
+            agent_url: string;
+            /**
+             * Optional `feature_id` the buyer represents the seller should request via `get_creative_features` (e.g., `imatag.watermark_detected`). SHOULD match the `feature_id` declared on the matching `accepted_verifiers[]` entry, or be omitted to defer the selector to the seller. When the seller's entry pins a `feature_id`, that value wins; when neither side pins, the seller selects from the agent's `governance.creative_features` catalog.
+             */
+            feature_id?: string;
+        };
+        c2pa_action?: C2PAWatermarkAction;
+        /**
+         * When the watermark was applied (ISO 8601)
+         * @format date-time
+         */
+        embedded_at?: string;
+    }[];
+    /**
+     * Regulatory disclosure requirements for this content. Indicates whether AI disclosure is required and under which jurisdictions.
+     */
+    disclosure?: {
+        /**
+         * The declaring party's claim that AI disclosure is required for this content under applicable regulations. This is a declared signal carried through the supply chain — useful as a routing and audit input — not a regulatory determination made by the protocol. Receiving parties remain responsible for their own jurisdictional analysis and should not treat `required: false` as compliance cover.
+         */
+        required: boolean;
+        /**
+         * Jurisdictions where disclosure obligations apply
+         */
+        jurisdictions?: {
+            /**
+             * ISO 3166-1 alpha-2 country code (e.g., 'US', 'DE', 'CN')
+             */
+            country: string;
+            /**
+             * Sub-national region code (e.g., 'CA' for California, 'BY' for Bavaria)
+             */
+            region?: string;
+            /**
+             * Regulation identifier (e.g., 'eu_ai_act_article_50', 'ca_sb_942', 'cn_deep_synthesis')
+             */
+            regulation: string;
+            /**
+             * Required disclosure label text for this jurisdiction, in the local language
+             */
+            label_text?: string;
+            /**
+             * How the disclosure should be rendered for this jurisdiction. Expresses the declaring party's intent for persistence and position based on regulatory requirements. Publishers control actual rendering but governance agents can audit whether guidance was followed.
+             */
+            render_guidance?: {
+                persistence?: DisclosurePersistence;
+                /**
+                 * Minimum display duration in milliseconds for initial persistence. Recommended when persistence is initial — without it, the duration is at the publisher's discretion. At serve time the publisher reads this from provenance since the brief is not available.
+                 * @minimum 1
+                 */
+                min_duration_ms?: number;
+                /**
+                 * Preferred disclosure positions in priority order. The first position a format supports should be used.
+                 */
+                positions?: DisclosurePosition[];
+                ext?: ExtensionObject;
+            };
+        }[];
+    };
+    /**
+     * Third-party verification or detection results for this content. Multiple services may independently evaluate the same content. Provenance is a claim — verification results attached by the declaring party are supplementary. The enforcing party (e.g., seller/publisher) should run its own verification via get_creative_features or calibrate_content.
+     */
+    verification?: {
+        /**
+         * Name of the verification service (e.g., 'DoubleVerify', 'Hive Moderation', 'Reality Defender')
+         */
+        verified_by: string;
+        /**
+         * When the verification was performed (ISO 8601)
+         * @format date-time
+         */
+        verified_time?: string;
+        /**
+         * Verification outcome
+         */
+        result: 'authentic' | 'ai_generated' | 'ai_modified' | 'inconclusive';
+        /**
+         * Confidence score of the verification result (0.0 to 1.0)
+         * @minimum 0
+         * @maximum 1
+         */
+        confidence?: number;
+        /**
+         * URL to the full verification report
+         */
+        details_url?: string;
+    }[];
+    ext?: ExtensionObject;
+}
+
+/**
+ * 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.
+ */
+export interface PushNotificationConfig {
+    /**
+     * Webhook endpoint URL for task status notifications. The wire contract is unconstrained beyond `format: "uri"` — in particular, publishers SHOULD NOT enforce a destination-port allowlist by default, since buyers legitimately host receivers on non-standard TLS ports (`:9443`, `:4443`, path-routed multi-tenant gateways). The SSRF guard the protocol relies on is the IP-range check + DNS-rebinding-resistant connect pin defined in [Webhook URL validation (SSRF)](/docs/building/by-layer/L1/security#webhook-url-validation-ssrf), not port filtering. Operators who want a hardened destination-port allowlist as defense-in-depth (e.g., locked-down enterprise egress) opt in explicitly — see [Destination port: permissive by default](/docs/building/by-layer/L1/security#destination-port-permissive-by-default).
+     */
+    url: string;
+    /**
+     * Buyer-supplied correlation identifier for the operation that will produce webhooks against this registration. The seller MUST echo this value verbatim into every webhook payload's `operation_id` field (see [`mcp-webhook-payload.json`](/schemas/core/mcp-webhook-payload.json) and [Webhooks — Operation IDs](/docs/building/by-layer/L3/webhooks#operation-ids-and-url-templates)). Buyers SHOULD generate a unique value per task invocation (UUID recommended). This field is the canonical registration channel for `operation_id`; buyers MAY additionally embed the same value in the URL path or query as a routing aid for their own HTTP server, but the URL is opaque to the seller and the wire-level source of truth is this field. Sellers MUST NOT parse the URL to recover `operation_id`. Sellers that receive a webhook registration without `operation_id` MAY reject the task with `INVALID_REQUEST`.
+     * @minLength 1
+     * @maxLength 255
+     * @pattern ^[A-Za-z0-9_.:-]{1,255}$
+     */
+    operation_id?: string;
+    /**
+     * Optional client-provided token for webhook validation. The seller MUST echo this value verbatim in every webhook payload's `token` field (see [`mcp-webhook-payload.json`](/schemas/core/mcp-webhook-payload.json) for the receiver-side validation obligation). Length bounds give receivers a defensive range check on the echoed value; senders SHOULD generate tokens with at least 128 bits of entropy (≥22 base64url characters). This is a complementary authenticity mechanism that can layer on top of the RFC 9421 webhook signature — unlike the `authentication` block below, it is not on the 4.0 removal track. Receivers that registered both a signing key (RFC 9421) and a `token` MUST NOT treat a valid token echo as authorization to skip signature verification; both checks remain independent obligations.
+     * @minLength 16
+     * @maxLength 4096
+     */
+    token?: string;
+    /**
+     * Legacy authentication configuration (A2A-compatible). Opts the seller into Bearer or HMAC-SHA256 signing instead of the default RFC 9421 webhook profile. Deprecated; removed in AdCP 4.0. **Precedence is a switch, not a fallback:** presence of this block selects the legacy scheme; absence selects 9421. A seller MUST NOT sign the same webhook both ways, and a buyer MUST NOT attempt 'try 9421 first, fall back to HMAC' verification — signature mode is determined solely by whether this block was present at registration time. The seller's baseline 9421 webhook-signing key published at its brand.json `agents[]` `jwks_uri` does not override this selector; it is always discoverable but only used when `authentication` is omitted. See docs/building/implementation/security.mdx#webhook-callbacks for the full precedence and downgrade-resistance rules (including the `webhook_mode_mismatch` rejection a buyer MUST apply when a received webhook's signing mode does not match the registered mode).
+     */
+    authentication?: {
+        /**
+         * Array of authentication schemes. Supported: ['Bearer'] for simple token auth, ['HMAC-SHA256'] for legacy shared-secret signing. Both are deprecated; new integrations SHOULD omit `authentication` and use the RFC 9421 webhook profile.
+         */
+        schemes: AuthenticationScheme[];
+        /**
+         * Credentials for the legacy scheme. 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
+         */
+        credentials: string;
+    };
+}
+
+/**
+ * Unit of measurement for reach and audience_size metrics in this forecast. Required for cross-channel forecast comparison.
+ */
+export type ReachUnit = 'individuals' | 'households' | 'devices' | 'accounts' | 'cookies' | 'custom';
+
+/**
+ * Optional SLA commitment for this action on this product. Absence means no commitment.
+ */
+export interface SLAWindow {
+    /**
+     * Maximum time from when the buyer issues the action to when the seller acknowledges receipt (mode-appropriate: synchronous response for self_serve, queue ack for requires_approval, proposal task creation for requires_proposal). ISO 8601 duration.
+     * @pattern ^P(?!$)(\d+Y)?(\d+M)?(\d+D)?(T(\d+H)?(\d+M)?(\d+S)?)?$
+     */
+    response_max?: string;
+    /**
+     * Maximum time from buyer issuing the action to the seller completing it (mutation applied, proposal finalized, approval resolved). ISO 8601 duration.
+     * @pattern ^P(?!$)(\d+Y)?(\d+M)?(\d+D)?(T(\d+H)?(\d+M)?(\d+S)?)?$
+     */
+    completion_max?: string;
+}
+
+/**
+ * Machine-readable reason the snapshot is omitted. Present only when include_snapshot was true and snapshot is unavailable for this package.
+ */
+export type SnapshotUnavailableReason = 'SNAPSHOT_UNSUPPORTED' | 'SNAPSHOT_TEMPORARILY_UNAVAILABLE' | 'SNAPSHOT_PERMISSION_DENIED';
+
+/**
+ * Optional restriction overlays for media buys. Most targeting should be expressed in the brief and handled by the publisher. These fields are for functional restrictions: geographic (RCT testing, regulatory compliance, proximity targeting), age verification (alcohol, gambling), device platform (app compatibility), language (localization), and keyword targeting (search/retail media).
+ */
+export interface TargetingOverlay {
+    /**
+     * Restrict delivery to specific countries. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE').
+     */
+    geo_countries?: string[];
+    /**
+     * Exclude specific countries from delivery. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE').
+     */
+    geo_countries_exclude?: string[];
+    /**
+     * Restrict delivery to specific regions/states. ISO 3166-2 subdivision codes (e.g., 'US-CA', 'GB-SCT').
+     */
+    geo_regions?: string[];
+    /**
+     * Exclude specific regions/states from delivery. ISO 3166-2 subdivision codes (e.g., 'US-CA', 'GB-SCT').
+     */
+    geo_regions_exclude?: string[];
+    /**
+     * Restrict delivery to specific metro areas. Each entry specifies the classification system and target values. Seller must declare supported systems in get_adcp_capabilities.
+     */
+    geo_metros?: {
+        system: MetroAreaSystem;
+        /**
+         * Metro codes within the system (e.g., ['501', '602'] for Nielsen DMAs)
+         */
+        values: string[];
+    }[];
+    /**
+     * Exclude specific metro areas from delivery. Each entry specifies the classification system and excluded values. Seller must declare supported systems in get_adcp_capabilities.
+     */
+    geo_metros_exclude?: {
+        system: MetroAreaSystem;
+        /**
+         * Metro codes to exclude within the system (e.g., ['501', '602'] for Nielsen DMAs)
+         */
+        values: string[];
+    }[];
+    /**
+     * Restrict delivery to specific postal areas. Each entry specifies the postal system and target values. Seller must declare supported systems in get_adcp_capabilities.
+     */
+    geo_postal_areas?: {
+        system: PostalCodeSystem;
+        /**
+         * Postal codes within the system (e.g., ['10001', '10002'] for us_zip)
+         */
+        values: string[];
+    }[];
+    /**
+     * Exclude specific postal areas from delivery. Each entry specifies the postal system and excluded values. Seller must declare supported systems in get_adcp_capabilities.
+     */
+    geo_postal_areas_exclude?: {
+        system: PostalCodeSystem;
+        /**
+         * Postal codes to exclude within the system (e.g., ['10001', '10002'] for us_zip)
+         */
+        values: string[];
+    }[];
+    /**
+     * Restrict delivery to specific time windows. Each entry specifies days of week and an hour range.
+     */
+    daypart_targets?: DaypartTarget[];
+    /**
+     * @deprecated
+     * Deprecated: Use TMP provider fields instead. AXE segment ID to include for targeting.
+     */
+    axe_include_segment?: string;
+    /**
+     * @deprecated
+     * Deprecated: Use TMP provider fields instead. AXE segment ID to exclude from targeting.
+     */
+    axe_exclude_segment?: string;
+    /**
+     * Restrict delivery to members of these first-party CRM audiences. Only users present in the uploaded lists are eligible. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Not for lookalike expansion — express that intent in the campaign brief. Seller must declare support in get_adcp_capabilities.
+     */
+    audience_include?: string[];
+    /**
+     * Suppress delivery to members of these first-party CRM audiences. Matched users are excluded regardless of other targeting. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Seller must declare support in get_adcp_capabilities.
+     */
+    audience_exclude?: string[];
+    frequency_cap?: FrequencyCap;
+    property_list?: PropertyListReference;
+    collection_list?: CollectionListReference;
+    collection_list_exclude?: CollectionListReference;
+    /**
+     * Age restriction for compliance. Use for legal requirements (alcohol, gambling), not audience targeting.
+     */
+    age_restriction?: {
+        /**
+         * Minimum age required
+         * @minimum 13
+         * @maximum 99
+         */
+        min: number;
+        /**
+         * Whether verified age (not inferred) is required for compliance
+         */
+        verification_required?: boolean;
+        /**
+         * Accepted verification methods. If omitted, any method the platform supports is acceptable.
+         */
+        accepted_methods?: AgeVerificationMethod[];
+    };
+    /**
+     * Restrict to specific platforms. Use for technical compatibility (app only works on iOS). Values from Sec-CH-UA-Platform standard, extended for CTV.
+     */
+    device_platform?: DevicePlatform[];
+    /**
+     * Restrict to specific device form factors. Use for campaigns targeting hardware categories rather than operating systems (e.g., mobile-only promotions, CTV campaigns).
+     */
+    device_type?: DeviceType[];
+    /**
+     * Exclude specific device form factors from delivery (e.g., exclude CTV for app-install campaigns).
+     */
+    device_type_exclude?: DeviceType[];
+    /**
+     * Target users within store catchment areas from a synced store catalog. Each entry references a store-type catalog and optionally narrows to specific stores or catchment zones.
+     */
+    store_catchments?: {
+        /**
+         * Synced store-type catalog ID from sync_catalogs.
+         */
+        catalog_id: string;
+        /**
+         * Filter to specific stores within the catalog. Omit to target all stores.
+         */
+        store_ids?: string[];
+        /**
+         * Catchment zone IDs to target (e.g., 'walk', 'drive'). Omit to target all catchment zones.
+         */
+        catchment_ids?: string[];
+    }[];
+    /**
+     * Target users within travel time, distance, or a custom boundary around arbitrary geographic points. Multiple entries use OR semantics — a user within range of any listed point is eligible. For campaigns targeting 10+ locations, consider using store_catchments with a location catalog instead. Seller must declare support in get_adcp_capabilities.
+     */
+    geo_proximity?: {
+        [k: string]: unknown | undefined;
+    }[];
+    /**
+     * Restrict to users with specific language preferences. ISO 639-1 codes (e.g., 'en', 'es', 'fr').
+     */
+    language?: string[];
+    /**
+     * Keyword targeting for search and retail media platforms. Restricts delivery to queries matching the specified keywords. Each keyword is identified by the tuple (keyword, match_type) — the same keyword string with different match types are distinct targets. Sellers SHOULD reject duplicate (keyword, match_type) pairs within a single request. Seller must declare support in get_adcp_capabilities.
+     */
+    keyword_targets?: {
+        /**
+         * The keyword to target
+         * @minLength 1
+         */
+        keyword: string;
+        match_type: MatchType;
+        /**
+         * Per-keyword bid price, denominated in the same currency as the package's pricing option. Overrides the package-level bid_price for this keyword. Inherits the max_bid interpretation from the pricing option: when max_bid is true, this is the keyword's bid ceiling; when false, this is the exact bid. If omitted, the package bid_price applies.
+         * @minimum 0
+         */
+        bid_price?: number;
+    }[];
+    /**
+     * Keywords to exclude from delivery. Queries matching these keywords will not trigger the ad. Each negative keyword is identified by the tuple (keyword, match_type). Seller must declare support in get_adcp_capabilities.
+     */
+    negative_keywords?: {
+        /**
+         * The keyword to exclude
+         * @minLength 1
+         */
+        keyword: string;
+        match_type: MatchType;
+    }[];
+}
+
+/**
+ * Current task execution state. Indicates whether the task is completed, in progress (working), submitted for async processing, failed, or requires user input. REQUIRED on every task response envelope. Synchronous tasks (including read-only metadata calls like `get_adcp_capabilities`) MUST emit `status: "completed"`; async tasks emit `submitted`, `working`, `input-required`, etc. per their lifecycle. Agents MUST NOT emit the legacy task_status or response_status fields alongside this field — the status field is the single authoritative task state.
+ */
+export type TaskStatus = 'submitted' | 'working' | 'input-required' | 'completed' | 'canceled' | 'failed' | 'rejected' | 'auth-required' | 'unknown';
+
+/**
+ * Media category of the watermarked content
+ */
+export type WatermarkMediaType = 'audio' | 'image' | 'video' | 'text';
+
+/**
+ * Single webhook delivery attempt surfaced to a calling principal as a buyer-side debug aid. Represents one HTTP attempt of a logical webhook fire from the seller to the buyer's registered endpoint — retries of the same logical fire share `idempotency_key` and differ by `attempt`. This is the canonical record shape for any AdCP resource that exposes a `webhook_activity[]` log on its read API; see snapshot-and-log.mdx § Webhook activity log pattern for the full normative contract (scoping, retention, three-state presence, request-field conventions).
+ */
+export interface WebhookActivityRecord {
+    /**
+     * Equals the `idempotency_key` carried in the webhook payload itself (see docs/building/by-layer/L3/webhooks.mdx § Dedup by `idempotency_key`). Stable across retry attempts of the same logical fire — retries with `attempt` > 1 reuse this key. Buyers correlate this surface with their own endpoint logs via this exact field; the spec deliberately reuses the payload key rather than minting a parallel `delivery_id` so callers do not need a join table. Format is sender-defined; callers MUST treat as opaque.
+     */
+    idempotency_key: string;
+    /**
+     * Identifies which registered webhook subscriber received this fire. **Required on records from account-anchored notification channels** (`notification_configs[]` registered via `sync_accounts`) — every subscriber has a `subscriber_id` at registration time, the seller MUST echo it on every fire and every activity record. **Optional on records from per-resource push channels** (`push_notification_config` on a media buy or task) — the calling principal is unambiguous in single-subscriber configurations and the field MAY be omitted; sellers MUST populate it once `reporting_webhook` adopts multi-subscriber (per #3009 in AdCP 4.0). Buyers MUST NOT use absence as a signal that no other subscribers exist; that information is not exposed by this surface.
+     */
+    subscriber_id?: string;
+    /**
+     * ISO 8601 timestamp when the seller initiated the HTTP request for this attempt.
+     * @format date-time
+     */
+    fired_at: string;
+    /**
+     * ISO 8601 timestamp when the seller observed the response (or terminal timeout / connection error — for `timeout` and `connection_error` outcomes, `completed_at` is set to the moment the seller declared the attempt terminal). Explicitly `null` when the attempt is still in flight or queued for retry (status `pending`); MUST be set as `null` rather than omitted so callers can distinguish 'still in flight' from 'field missing'.
+     * @format date-time
+     */
+    completed_at?: string | null;
+    notification_type: NotificationType;
+    /**
+     * Sequence number from the webhook payload. Surfaced here so the buyer can spot stale-sequence drops and gaps without correlating against their own endpoint log. Absent for notification types that do not carry a sequence number.
+     * @minimum 0
+     */
+    sequence_number?: number;
+    /**
+     * 1-indexed retry counter for this logical fire. Initial fire is attempt=1; retries increment. Sellers MUST emit one record per attempt, so a successful first-attempt fire appears as a single record with `attempt: 1` and a 3-attempt retry trail appears as three records sharing `idempotency_key`.
+     * @minimum 1
+     */
+    attempt: number;
+    /**
+     * Outcome of this attempt. `success` — response received with 2xx (`http_status_code` populated). `failed` — response received with non-2xx (`http_status_code` populated). `timeout` — no response within the seller's configured timeout (`http_status_code` null). `connection_error` — DNS / TLS / socket failure before any HTTP response (`http_status_code` null). `pending` — attempt is in flight or queued for retry (`completed_at` null, `http_status_code` null). The `timeout` / `connection_error` split is intentional and operationally distinct: `timeout` typically signals a slow / overloaded buyer endpoint, `connection_error` typically signals it is unreachable or misconfigured.
+     */
+    status: 'success' | 'failed' | 'timeout' | 'connection_error' | 'pending';
+    /**
+     * Target URL for this fire. Query string and fragment MUST be stripped before surfacing — buyers commonly stash bearer tokens in the query string and sellers MUST NOT echo those back through this debug surface. Sellers SHOULD additionally redact path segments matching obvious secret patterns (e.g., a path segment that is high-entropy random material or matches a UUID / token format). Buyers matching this against their own configured URL should compare by origin + path; query strings will not match and that mismatch is expected.
+     */
+    url: string;
+    /**
+     * HTTP status code returned by the buyer's endpoint. Explicitly `null` when no HTTP response was received (status `timeout`, `connection_error`, or `pending`); MUST be set as `null` rather than omitted.
+     * @minimum 100
+     * @maximum 599
+     */
+    http_status_code?: number | null;
+    /**
+     * Wall-clock latency between request send and response receipt, in milliseconds. Explicitly `null` when the attempt did not complete (`timeout`, `connection_error`, `pending`); MUST be set as `null` rather than omitted.
+     * @minimum 0
+     */
+    response_time_ms?: number | null;
+    /**
+     * Size of the request body the seller sent, in bytes. Useful for diagnosing oversized-payload rejections from the buyer's gateway.
+     * @minimum 0
+     */
+    payload_size_bytes?: number;
+    /**
+     * Short human-readable server-side classification of why this attempt did not succeed (e.g., `connection refused`, `TLS handshake timeout`, `HTTP 503 Service Unavailable`). Explicitly `null` for `success` (MUST be set as `null` rather than omitted). Sellers MUST NOT include request headers, request body content, or response body content in this field — payload surfacing is reserved for a future `include_webhook_payloads` extension and is subject to stricter access controls. Sellers SHOULD also avoid including buyer-endpoint internal hostnames, stack traces, or other implementation detail leaked by the response — keep it a stable classification string.
+     * @maxLength 500
+     */
+    error_message?: string | null;
+    ext?: ExtensionObject;
+}