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

package/dist/lib/types/list-accounts.d.ts

@@ -0,0 +1,851 @@
+// AUTO-GENERATED — DO NOT EDIT.
+// Per-tool .d.ts slice for `list_accounts`. 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 listing accounts accessible to the authenticated agent
+ */
+export interface ListAccountsRequest {
+    /**
+     * 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;
+    /**
+     * Filter accounts by status. Omit to return accounts in all statuses.
+     */
+    status?: 'active' | 'pending_approval' | 'rejected' | 'payment_required' | 'suspended' | 'closed';
+    pagination?: PaginationRequest;
+    /**
+     * Filter by sandbox status. true returns only sandbox accounts, false returns only production accounts. Omit to return all accounts. Primarily used with explicit accounts (require_operator_auth: true) where sandbox accounts are pre-existing test accounts on the platform.
+     */
+    sandbox?: boolean;
+    context?: ContextObject;
+    ext?: ExtensionObject;
+}
+
+/**
+ * Response payload for list_accounts task
+ */
+export interface ListAccountsResponse {
+    /**
+     * 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 accounts accessible to the authenticated agent. Each entry is the full Account object plus an optional `authorization` object describing what the calling agent is permitted to do on that account.
+     */
+    accounts: (Account & {
+        authorization?: AccountAuthorization;
+    })[];
+    /**
+     * Task-specific errors and warnings
+     */
+    errors?: Error[];
+    pagination?: PaginationResponse;
+    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;
+}
+
+/**
+ * Optional. The caller's scope grant against this account. Vendor agents of any type (media-buy, signals, governance, creative, brand) that support scope introspection SHOULD populate this so callers can preempt SCOPE_INSUFFICIENT / FIELD_NOT_PERMITTED errors rather than discovering scope by trial and error. Media-buy sales agents claiming the `attestation_verifier` standard scope MUST populate it. Absence means the vendor agent does not advertise introspectable scope for this account — callers MUST NOT infer access from absence, and fall back to error-driven discovery via the RBAC error codes.
+ */
+export interface AccountAuthorization {
+    /**
+     * Canonical snake_case task names the caller may invoke against this account (e.g., get_media_buys, update_media_buy, create_media_buy, sync_creatives). Absence of a task from this list MUST be interpreted as 'not permitted' — invoking an absent task MUST return SCOPE_INSUFFICIENT. This list reflects the caller's grant, not the seller's universal capability surface (for that, see get_adcp_capabilities). A seller may grant narrower subsets to different callers on the same account.
+     */
+    allowed_tasks: string[];
+    /**
+     * Optional per-task allowlist of request fields the caller may set. Keys are task names (which MUST also appear in allowed_tasks). Values are arrays of top-level request-field paths permitted for that task. When a task appears in field_scopes, requests to that task with any field outside the allowlist MUST be rejected with FIELD_NOT_PERMITTED. Implicit framing fields are always permitted and do NOT need to appear in the allowlist — they identify the resource or shape the call rather than mutating business state. The list is non-exhaustive but covers the common cases: typed entity references (`account`, `media_buy_id`, `package_id`, `creative_id`, `signal_id`, `format_id`, `proposal_id`, `plan_id`, `session_id`), concurrency/idempotency (`revision`, `idempotency_key`), buyer-side correlation (`buyer_ref`, `po_number`), mode flags (`dry_run`), pagination (`pagination`, `cursor`, `max_results`), and envelope fields (`context`, `ext`, `adcp_major_version`, `push_notification_config` — transport-level async receipt, not business state). Any other typed entity-id parameter or query-shaping field on a read task SHOULD be treated as framing and not require listing. Tasks absent from field_scopes have no field-level restriction beyond what the task schema already enforces. An entry with an empty array means 'framing fields only, no business fields' — semantically distinct from the task being absent from field_scopes.
+     */
+    field_scopes?: {
+        [k: string]: string[] | undefined;
+    };
+    /**
+     * Optional named scope identifier. When present, callers and the vendor agent can reason about the grant by name rather than by enumerating allowed_tasks and field_scopes. Modeled as a discriminated union so code generators produce a literal type for the standard scope(s) and a distinct type for agent-defined values — this prevents a typo of `attestation_verifier` from being silently accepted as a custom scope. Agent-defined scope names MUST use a `custom:` prefix to avoid collision with future standard scopes. The prefix is protocol-neutral: a signals agent, a governance agent, or a creative agent defines custom scopes the same way a media-buy sales agent does.
+     */
+    scope_name?: StandardScope | CustomScope;
+    /**
+     * Convenience flag. When true, the caller is permitted only non-mutating tasks. Sellers MUST reject any mutation from a read-only caller with READ_ONLY_SCOPE. Sellers MAY omit this field; omission is equivalent to `false`. Callers MUST NOT infer read-only from `allowed_tasks` alone — the seller MUST set this explicitly when it applies.
+     */
+    read_only?: 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';
+
+/**
+ * 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';
+
+/**
+ * Cloud storage protocol
+ */
+export type CloudStorageProtocol = 's3' | 'gcs' | 'azure_blob';
+
+/**
+ * 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 {
+}
+
+/**
+ * Agent-defined scope name, prefixed with `custom:`. Any vendor agent (media-buy seller, signals agent, governance agent, creative agent, brand agent) MAY define custom scopes. Callers MUST NOT assume any semantics from a custom-prefixed scope name.
+ * @pattern ^custom:[a-z][a-z0-9_]*$
+ */
+export type CustomScope = string;
+
+/**
+ * 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';
+
+/**
+ * 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 {
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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';
+
+/**
+ * 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';
+
+/**
+ * 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;
+    };
+}
+
+/**
+ * Standard named scopes defined by the AdCP spec. `attestation_verifier` binds to the AAO Verified (Live) qualifier (a Media Buy Protocol flow — live observation requires real ad delivery) — the authorization mechanism itself is protocol-neutral, but this particular named scope is media-buy-specific.
+ */
+export type StandardScope = 'attestation_verifier';
+
+/**
+ * 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';