@adcp/sdk API Reference - v14.3.0
    Preparing search index...

    Interface AccountChangeDrainPage

    interface AccountChangeDrainPage {
        acknowledge(
            commit: (cursor: DurableAccountChangeCursor) => Promise<void>,
        ): Promise<void>;
        context_id?: string;
        context?: ContextObject;
        task_id?: string;
        status: "completed";
        message?: string;
        timestamp?: string;
        replayed?: boolean;
        adcp_error?: Error;
        push_notification_config?: PushNotificationConfig;
        governance_context?: string;
        payload?: {};
        adcp_version?: string;
        adcp_major_version?: number;
        changes: AccountChange[];
        has_more: boolean;
        available_since: string;
        generated_at: string;
        source_coverage?: {
            source_id: string;
            kind: "seller" | "connected_platform";
            status: "unavailable" | "delayed" | "current" | "not_configured";
            coverage_start?: string;
            observed_through?: string;
            last_successful_sync_at?: string;
            stale_after_seconds?: number;
            resource_types: string[];
        }[] & {
            source_id: string;
            kind: "seller"
            | "connected_platform";
            status: "unavailable" | "delayed" | "current" | "not_configured";
            coverage_start?: string;
            observed_through?: string;
            last_successful_sync_at?: string;
            stale_after_seconds?: number;
            resource_types: string[];
        }[];
        errors?: Error[];
        ext?: ExtensionObject;
    }

    Hierarchy

    Index
    context_id?: string

    Transport-managed conversation identifier. On A2A, this maps to the native Message/Task contextId used to associate messages with a conversation; it is not carried inside the AdCP DataPart. On MCP, a request-body context_id, where admitted by the selected request schema, is a compatibility-only field: servers MUST ignore it, callers MUST NOT rely on it for continuity, and it MUST NOT select session state, identity, account, authorization, task continuation, or idempotency scope. MCP continuity, if provided, comes from the transport session. Distinct from context (per-request opaque echo, see below) and from task_id (AdCP operation tracking).

    context?: ContextObject
    task_id?: string

    Unique identifier for tracking asynchronous operations. Present when a task requires extended processing time. Used to query task status and retrieve results when complete.

    status: "completed"
    message?: string

    Human-readable summary of the task result. Provides natural language explanation of what happened, suitable for display to end users or for AI agent comprehension. Generated by the protocol layer based on the task response.

    timestamp?: string

    ISO 8601 timestamp when the response was generated. Useful for debugging, logging, cache validation, and tracking async operation progress.

    replayed?: boolean

    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. replayed appears only when the request actually resolved through the idempotency cache. Pure reads may ignore an optional idempotency_key; when a seller voluntarily caches keyed reads, those responses use the same replay indicator and full cache contract.

    adcp_error?: Error
    push_notification_config?: PushNotificationConfig
    governance_context?: string

    Opaque authorization context issued only by an approved check_governance decision. Buyers attach it to governed requests across protocol roles (media buys, rights acquisitions, signal activations, creative services); receiving services persist it and forward it on subsequent execution and lifecycle checks. The context is the authoritative plan binding at service boundaries, so a service MUST NOT require a separate plan_id.

    Governance agents MUST emit a compact JWS per the AdCP JWS profile. Verifiers validate standard authorization claims such as signature, issuer, audience, expiry, and replay protection, but intermediaries MUST NOT interpret embedded governance state for business logic. A conditions or denied verdict never carries an authorization context.

    This is the primary correlation key for audit and reporting across the governance lifecycle.

    payload?: {}

    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.

    adcp_version?: string

    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_major_version?: number

    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.

    changes: AccountChange[]

    Matching changes in oldest-first total account order. Timestamps are descriptive and do not define this order.

    100

    has_more: boolean

    True when more retained matching changes were available at generation time. False means caught up to seller ingestion, not necessarily to an unavailable or delayed connected source.

    available_since: string

    Oldest time for which the seller currently retains change records for this account and caller. The capability guarantees at least 90 days after adoption; pre-adoption history is not fabricated.

    date-time

    generated_at: string

    Seller time when this page and its source-coverage watermarks were generated.

    date-time

    source_coverage?: {
        source_id: string;
        kind: "seller" | "connected_platform";
        status: "unavailable" | "delayed" | "current" | "not_configured";
        coverage_start?: string;
        observed_through?: string;
        last_successful_sync_at?: string;
        stale_after_seconds?: number;
        resource_types: string[];
    }[] & {
        source_id: string;
        kind: "seller"
        | "connected_platform";
        status: "unavailable" | "delayed" | "current" | "not_configured";
        coverage_start?: string;
        observed_through?: string;
        last_successful_sync_at?: string;
        stale_after_seconds?: number;
        resource_types: string[];
    }[]

    Account-specific feed and connector coverage. Buyers use this to distinguish feed catch-up from upstream freshness. Omission means no additional connected-source coverage is declared.

    Type Declaration

    • source_id: string

      Opaque seller or connection reference.

      255

    • kind: "seller" | "connected_platform"
    • status: "unavailable" | "delayed" | "current" | "not_configured"

      Connector freshness classification. For connected_platform, current means last_successful_sync_at is no older than stale_after_seconds at generated_at and the seller knows of no ingestion gap; delayed means that threshold is exceeded or a gap is known.

    • Optionalcoverage_start?: string

      Earliest upstream time covered by this source after connection or retention limits.

      date-time

    • Optionalobserved_through?: string

      Latest upstream point the seller has successfully observed.

      date-time

    • Optionallast_successful_sync_at?: string

      date-time

    • Optionalstale_after_seconds?: number

      Maximum age of last_successful_sync_at at generated_at for this connected source to self-classify as current. Required by the protocol contract whenever a connected source reports current.

      1

      2592000

      int

    • resource_types: string[]

      50

    • source_id: string

      Opaque seller or connection reference.

      255

    • kind: "seller" | "connected_platform"
    • status: "unavailable" | "delayed" | "current" | "not_configured"

      Connector freshness classification. For connected_platform, current means last_successful_sync_at is no older than stale_after_seconds at generated_at and the seller knows of no ingestion gap; delayed means that threshold is exceeded or a gap is known.

    • Optionalcoverage_start?: string

      Earliest upstream time covered by this source after connection or retention limits.

      date-time

    • Optionalobserved_through?: string

      Latest upstream point the seller has successfully observed.

      date-time

    • Optionallast_successful_sync_at?: string

      date-time

    • Optionalstale_after_seconds?: number

      Maximum age of last_successful_sync_at at generated_at for this connected source to self-classify as current. Required by the protocol contract whenever a connected source reports current.

      1

      2592000

      int

    • resource_types: string[]

      50

    50

    errors?: Error[]
    • Call after repairing this page's invalidations. The hook owns the atomic projection/checkpoint commit. Failure never advances the stream. Each page, including an empty tail, must be acknowledged before requesting the next.

      Parameters

      Returns Promise<void>