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

    Interface ReportingLedger

    interface ReportingLedger {
        ledgerSnapshotId: string;
        ledgerAsOf: string;
        changesCheckpoint?: string;
        accountId: string;
        scope: {
            period_start: string;
            period_end: string;
            scope_closed: boolean;
            media_buy_ids?: string[];
            all_accessible_media_buys: boolean;
            delivery_config_generations: {
                delivery_config_id: string;
                delivery_config_version: number;
                feed_purpose: ReportingFeedPurpose;
            }[];
            feed_purposes: ReportingFeedPurpose[];
            finality: ReportingFinality[];
            ledger_retained_from: string;
            coverage_complete: boolean;
        };
        obligations: ManagedReportingObligation[];
        revisions: ManagedReportingRevision[];
        materializations: {
            reporting_materialization_id: string;
            reporting_revision_id: string;
            reporting_obligation_id: string;
            delivery_config_id: string;
            delivery_config_version: number;
            destination_ref: string;
            feed_purpose: ReportingFeedPurpose;
            method: "file_transfer"
            | "dataset_share"
            | "warehouse_materialization";
            transport?: string;
            attempt: number;
            status: "available" | "failed" | "pending" | "delivered";
            ready_at?: string;
            failed_at?: string;
            failure_code?: string;
            resource?: {
                resource_ref: string;
                kind: "manifest" | "dataset" | "warehouse_relation";
                location: string;
                native_version_ref?: string;
                manifest_version?: "1.0";
                manifest_sha256?: string;
                immutability: "immutable_location" | "native_version";
                expires_at: string;
                reader_compatibility?: string[];
            };
            verification?: {
                verified_at: string;
                verification_path: "destination"
                | "producer"
                | "representative_consumer";
                verification_profile: ReportingVerificationProfile;
                row_count: number;
                control_totals: ReportingControlTotal[];
                canonical_content_digest?: ReportingCanonicalContentDigest;
                physical_checksums?: [
                    SHA256PhysicalChecksum
                    | SHA512PhysicalChecksum,
                    ...(SHA256PhysicalChecksum | SHA512PhysicalChecksum)[],
                ];
                native_commit_evidence?: {
                    native_version_ref: string;
                    observed_through: "destination" | "representative_consumer";
                };
            };
            created_at: string;
        }[];
        receipts: {
            reporting_receipt_id: string;
            reporting_obligation_id: string;
            reporting_revision_id: string;
            reporting_materialization_id: string;
            supersedes_reporting_receipt_id?: string;
            status: "rejected"
            | "accepted";
            verification_profile: ReportingVerificationProfile;
            observed_row_count: number;
            observed_control_totals: ReportingControlTotal[];
            observed_canonical_content_digest?: ReportingCanonicalContentDigest;
            observed_manifest_sha256?: string;
            observed_native_version_ref?: string;
            consumer_commit_ref?: string;
            rejection_codes?: [string, ...string[]];
            observed_at: string;
            received_at?: string;
        }[];
        adjustments?: ReportingAdjustment[];
        adjustmentReceipts?: {
            reporting_receipt_id: string;
            reporting_adjustment_id: string;
            adjusts_reporting_revision_id: string;
            supersedes_reporting_receipt_id?: string;
            status: "rejected"
            | "accepted";
            observed_adjustment_sha256: string;
            rejection_codes?: [string, ...string[]];
            observed_at: string;
            received_at?: string;
        }[];
        consumerStatuses?: {
            reporting_status_id: string;
            supersedes_reporting_status_id?: string;
            delivery_config_id: string;
            delivery_config_version: number;
            report_definition_id: string;
            period: { start: string; end: string; source_timezone: string };
            reporting_obligation_id?: string;
            reporting_revision_id?: string;
            observed_revision_content_sha256?: string;
            consumer_status:
                | "received"
                | "obligation_missing"
                | "revision_missing"
                | "unreadable"
                | "content_mismatch";
            status_as_of: string;
            mismatch_code?: | "scope_media_buy_missing"
            | "coverage_short"
            | "metric_missing"
            | "schema_nonconformant"
            | "currency_mismatch"
            | "period_mismatch";
            failure_code?: | "access_denied"
            | "resource_not_found"
            | "integrity_mismatch"
            | "reader_incompatible"
            | "transport_failed";
            consumer_commit_ref?: string;
            seller_ledger_snapshot_id?: string;
            seller_ledger_as_of?: string;
            recorded_at?: string;
        }[];
    }
    Index
    ledgerSnapshotId ledgerAsOf changesCheckpoint? accountId scope obligations revisions materializations receipts adjustments? adjustmentReceipts? consumerStatuses?
    ledgerSnapshotId: string
    ledgerAsOf: string
    changesCheckpoint?: string

    Persist only after every page in this snapshot has been consumed.

    accountId: string
    scope: {
        period_start: string;
        period_end: string;
        scope_closed: boolean;
        media_buy_ids?: string[];
        all_accessible_media_buys: boolean;
        delivery_config_generations: {
            delivery_config_id: string;
            delivery_config_version: number;
            feed_purpose: ReportingFeedPurpose;
        }[];
        feed_purposes: ReportingFeedPurpose[];
        finality: ReportingFinality[];
        ledger_retained_from: string;
        coverage_complete: boolean;
    }

    Type Declaration

    • period_start: string

      date-time

    • period_end: string

      date-time

    • scope_closed: boolean

      True only when no new obligation can enter this evaluated scope.

    • Optionalmedia_buy_ids?: string[]
    • all_accessible_media_buys: boolean

      True when media_buy_ids was omitted and the scope covers all caller-accessible account buys.

    • delivery_config_generations: {
          delivery_config_id: string;
          delivery_config_version: number;
          feed_purpose: ReportingFeedPurpose;
      }[]

      Exact independently reconciled configuration generations in the denominator.

    • feed_purposes: ReportingFeedPurpose[]
    • finality: ReportingFinality[]
    • ledger_retained_from: string

      Earliest period boundary for which anti-entropy metadata is retained for every selected configuration generation.

      date-time

    • coverage_complete: boolean

      Whether the requested horizon is fully inside retained ledger coverage. False means health cannot prove completeness for the whole requested horizon.

    obligations: ManagedReportingObligation[]
    revisions: ManagedReportingRevision[]
    materializations: {
        reporting_materialization_id: string;
        reporting_revision_id: string;
        reporting_obligation_id: string;
        delivery_config_id: string;
        delivery_config_version: number;
        destination_ref: string;
        feed_purpose: ReportingFeedPurpose;
        method: "file_transfer" | "dataset_share" | "warehouse_materialization";
        transport?: string;
        attempt: number;
        status: "available" | "failed" | "pending" | "delivered";
        ready_at?: string;
        failed_at?: string;
        failure_code?: string;
        resource?: {
            resource_ref: string;
            kind: "manifest" | "dataset" | "warehouse_relation";
            location: string;
            native_version_ref?: string;
            manifest_version?: "1.0";
            manifest_sha256?: string;
            immutability: "immutable_location" | "native_version";
            expires_at: string;
            reader_compatibility?: string[];
        };
        verification?: {
            verified_at: string;
            verification_path: "destination"
            | "producer"
            | "representative_consumer";
            verification_profile: ReportingVerificationProfile;
            row_count: number;
            control_totals: ReportingControlTotal[];
            canonical_content_digest?: ReportingCanonicalContentDigest;
            physical_checksums?: [
                SHA256PhysicalChecksum
                | SHA512PhysicalChecksum,
                ...(SHA256PhysicalChecksum | SHA512PhysicalChecksum)[],
            ];
            native_commit_evidence?: {
                native_version_ref: string;
                observed_through: "destination" | "representative_consumer";
            };
        };
        created_at: string;
    }[]

    Type Declaration

    • reporting_materialization_id: string
    • reporting_revision_id: string
    • reporting_obligation_id: string

      Destination-specific obligation this materialization attempts to satisfy.

    • delivery_config_id: string

      Durable configuration that requested this materialization.

    • delivery_config_version: number
    • destination_ref: string

      Immutable caller-owned destination generation selected by the account-authorized obligation. It may be reused by the same caller across other independently authorized accounts.

    • feed_purpose: ReportingFeedPurpose
    • method: "file_transfer" | "dataset_share" | "warehouse_materialization"
    • Optionaltransport?: string
    • attempt: number
    • status: "available" | "failed" | "pending" | "delivered"

      Lifecycle of this attempt. pending may transition once to available, delivered, or failed; terminal evidence is immutable. Staleness is evaluated in get_reporting_status health, not stored as a materialization state.

    • Optionalready_at?: string

      When consumer-path or destination verification completed.

    • Optionalfailed_at?: string
    • Optionalfailure_code?: string

      Stable safe failure classification. MUST NOT include credentials or provider response bodies.

    • Optionalresource?: {
          resource_ref: string;
          kind: "manifest" | "dataset" | "warehouse_relation";
          location: string;
          native_version_ref?: string;
          manifest_version?: "1.0";
          manifest_sha256?: string;
          immutability: "immutable_location" | "native_version";
          expires_at: string;
          reader_compatibility?: string[];
      }
      • resource_ref: string

        Seller-issued opaque reference to this exact authenticated resource descriptor.

      • kind: "manifest" | "dataset" | "warehouse_relation"

        Shape through which the durable revision is consumed.

      • location: string

        Non-secret provider-native object, relation, or share identifier. MUST NOT contain an activation URL, signed URL, bearer token, password, private key, or embedded credential.

      • Optionalnative_version_ref?: string
      • Optionalmanifest_version?: "1.0"

        Version of reporting-file-manifest.json used by a manifest resource.

      • Optionalmanifest_sha256?: string

        SHA-256 over the exact manifest bytes. Consumers verify this before parsing the manifest.

      • immutability: "immutable_location" | "native_version"

        How this descriptor selects the exact immutable materialization.

      • expires_at: string

        Mandatory finite lower-bound endpoint through which this exact resource remains resolvable; it cannot be earlier than the advertised retention contract.

      • Optionalreader_compatibility?: string[]

        Reader features or format constraints required to consume this resource. Readiness verification MUST use a representative supported reader.

    • Optionalverification?: {
          verified_at: string;
          verification_path: "destination" | "producer" | "representative_consumer";
          verification_profile: ReportingVerificationProfile;
          row_count: number;
          control_totals: ReportingControlTotal[];
          canonical_content_digest?: ReportingCanonicalContentDigest;
          physical_checksums?: [
              SHA256PhysicalChecksum
              | SHA512PhysicalChecksum,
              ...(SHA256PhysicalChecksum | SHA512PhysicalChecksum)[],
          ];
          native_commit_evidence?: {
              native_version_ref: string;
              observed_through: "destination" | "representative_consumer";
          };
      }
      • verified_at: string

        When the producer completed verification through the claimed consumer/destination path.

      • verification_path: "destination" | "producer" | "representative_consumer"

        Path on which verification succeeded. dataset_share readiness requires representative_consumer; delivered warehouse state requires destination.

      • verification_profile: ReportingVerificationProfile
      • row_count: number

        Verified row count. Zero explicitly distinguishes an empty committed revision from a missing revision.

      • control_totals: ReportingControlTotal[]

        Profile-defined totals recomputed through verification_path. Names MUST be unique.

      • Optionalcanonical_content_digest?: ReportingCanonicalContentDigest
      • Optionalphysical_checksums?: [
            SHA256PhysicalChecksum
            | SHA512PhysicalChecksum,
            ...(SHA256PhysicalChecksum | SHA512PhysicalChecksum)[],
        ]

        Method-specific byte/object checksums. Different encodings of the same logical revision normally have different values.

        1

      • Optionalnative_commit_evidence?: {
            native_version_ref: string;
            observed_through: "destination" | "representative_consumer";
        }

        Provider-native immutable version evidence observed through the named consumer or destination path.

    • created_at: string
    receipts: {
        reporting_receipt_id: string;
        reporting_obligation_id: string;
        reporting_revision_id: string;
        reporting_materialization_id: string;
        supersedes_reporting_receipt_id?: string;
        status: "rejected" | "accepted";
        verification_profile: ReportingVerificationProfile;
        observed_row_count: number;
        observed_control_totals: ReportingControlTotal[];
        observed_canonical_content_digest?: ReportingCanonicalContentDigest;
        observed_manifest_sha256?: string;
        observed_native_version_ref?: string;
        consumer_commit_ref?: string;
        rejection_codes?: [string, ...string[]];
        observed_at: string;
        received_at?: string;
    }[]

    Type Declaration

    • reporting_receipt_id: string
    • reporting_obligation_id: string
    • reporting_revision_id: string
    • reporting_materialization_id: string
    • Optionalsupersedes_reporting_receipt_id?: string

      Optional immutable rejected receipt replaced by this new receipt. It MUST name the caller's current rejected receipt for this obligation and revision; accepted current receipts are terminal.

    • status: "rejected" | "accepted"
    • verification_profile: ReportingVerificationProfile
    • observed_row_count: number
    • observed_control_totals: ReportingControlTotal[]
    • Optionalobserved_canonical_content_digest?: ReportingCanonicalContentDigest
    • Optionalobserved_manifest_sha256?: string
    • Optionalobserved_native_version_ref?: string
    • Optionalconsumer_commit_ref?: string

      Optional non-secret consumer checkpoint, transaction, or load identifier. It is evidence for operations, not authorization or a credential.

    • Optionalrejection_codes?: [string, ...string[]]

      1

    • observed_at: string
    • Optionalreceived_at?: string
    adjustments?: ReportingAdjustment[]

    Immutable post-official billing corrections visible in this snapshot.

    adjustmentReceipts?: {
        reporting_receipt_id: string;
        reporting_adjustment_id: string;
        adjusts_reporting_revision_id: string;
        supersedes_reporting_receipt_id?: string;
        status: "rejected" | "accepted";
        observed_adjustment_sha256: string;
        rejection_codes?: [string, ...string[]];
        observed_at: string;
        received_at?: string;
    }[]

    This authenticated consumer's append-only acknowledgement history for corrections.

    Type Declaration

    • reporting_receipt_id: string
    • reporting_adjustment_id: string
    • adjusts_reporting_revision_id: string
    • Optionalsupersedes_reporting_receipt_id?: string

      Optional immutable rejected receipt replaced by this new receipt for the same adjustment. Accepted current receipts are terminal.

    • status: "rejected" | "accepted"
    • observed_adjustment_sha256: string

      Digest recomputed from the adjustment using its canonical evidence rule.

    • Optionalrejection_codes?: [string, ...string[]]

      1

    • observed_at: string
    • Optionalreceived_at?: string
    consumerStatuses?: {
        reporting_status_id: string;
        supersedes_reporting_status_id?: string;
        delivery_config_id: string;
        delivery_config_version: number;
        report_definition_id: string;
        period: { start: string; end: string; source_timezone: string };
        reporting_obligation_id?: string;
        reporting_revision_id?: string;
        observed_revision_content_sha256?: string;
        consumer_status:
            | "received"
            | "obligation_missing"
            | "revision_missing"
            | "unreadable"
            | "content_mismatch";
        status_as_of: string;
        mismatch_code?: | "scope_media_buy_missing"
        | "coverage_short"
        | "metric_missing"
        | "schema_nonconformant"
        | "currency_mismatch"
        | "period_mismatch";
        failure_code?: | "access_denied"
        | "resource_not_found"
        | "integrity_mismatch"
        | "reader_incompatible"
        | "transport_failed";
        consumer_commit_ref?: string;
        seller_ledger_snapshot_id?: string;
        seller_ledger_as_of?: string;
        recorded_at?: string;
    }[]

    The authenticated caller's own append-only status history for this scope. Sellers disclose no other consumer's statements, so this is the only way to see the current leaf's content — which is what tells the buyer whether it has anything new to say.

    Type Declaration

    • reporting_status_id: string

      Consumer-issued immutable identity for this status statement. Exact retries reuse the ID and content; changed status uses a new ID and supersedes_reporting_status_id.

    • Optionalsupersedes_reporting_status_id?: string

      The authenticated consumer's current status leaf replaced by this statement. It must identify the same account, configuration generation, report definition, and period.

    • delivery_config_id: string
    • delivery_config_version: number
    • report_definition_id: string

      Exact immutable report definition accepted with the configuration generation, preventing unlike reporting promises from sharing a status chain.

    • period: { start: string; end: string; source_timezone: string }

      Expected half-open reporting period derived from the accepted configuration generation. This identity works even when the seller omitted the corresponding obligation.

    • Optionalreporting_obligation_id?: string

      Seller-issued obligation identity when one was visible. Omitted when the consumer is reporting a missing obligation.

    • Optionalreporting_revision_id?: string

      Exact revision successfully consumed or found unreadable. Omitted when no required revision was available.

    • Optionalobserved_revision_content_sha256?: string

      revision_content_sha256 independently recomputed from the exact consumed Core revision binding. Required for received and content_mismatch, where it proves which exact revision content the consumer read; unlike a Reconciled Billing receipt it carries no materialization evidence, row totals, canonical digest, or billing acceptance.

    • consumer_status:
          | "received"
          | "obligation_missing"
          | "revision_missing"
          | "unreadable"
          | "content_mismatch"

      received means the exact revision content was successfully consumed; obligation_missing means the independently expected period was absent from the seller ledger; revision_missing means the obligation existed but no required revision was available after expected_at; unreadable means a named revision was advertised but its exact content could not be consumed; content_mismatch means the exact revision content was read but contradicts a fact the accepted configuration generation already fixed, named by the closed mismatch_code. None of these values reconciles billing evidence, and content_mismatch in particular is not a measurement dispute.

    • status_as_of: string

      When the consumer established this status. For received, this is when the named revision first became consumable to this consumer; sellers use it as buyer-attributed arrival evidence rather than silently substituting publication time.

    • Optionalmismatch_code?:
          | "scope_media_buy_missing"
          | "coverage_short"
          | "metric_missing"
          | "schema_nonconformant"
          | "currency_mismatch"
          | "period_mismatch"

      Closed reason the consumed revision contradicts the accepted configuration generation. Each value is decidable from the obligation, the pinned report definition, and the revision itself, with no reference to either party's own measurement. scope_media_buy_missing: a media buy frozen in the obligation's media_buy_ids denominator is absent from the revision and is not represented by an explicit zero row, so the revision cannot distinguish zero delivery from an omitted buy. coverage_short: the revision covers fewer packages than the obligation's frozen coverage.covered_package_ids claims. metric_missing: a metric named in the pinned report definition's metrics[].name is absent from the revision. schema_nonconformant: rows do not validate against the reporting profile's pinned schema_uri and schema_sha256. currency_mismatch: a value's unit disagrees with the unit the pinned report definition fixed for that metric, or a control total's unit disagrees with the profile-defined unit for that name. period_mismatch: the revision carries a time dimension declared by the pinned grain whose values fall outside the obligation's half-open period. Precedence when more than one applies: schema_nonconformant is used only when the failure is structural validation against the pinned schema; a metric that is simply absent uses metric_missing even when the pinned schema declares it required. Each names a contract fact already fixed by the accepted generation, never a difference of opinion about counts. Agents dispatch on this value, not on prose.

    • Optionalfailure_code?:
          | "access_denied"
          | "resource_not_found"
          | "integrity_mismatch"
          | "reader_incompatible"
          | "transport_failed"

      Typed reason a named revision was unreadable. Agents dispatch on this value, not prose or provider response bodies.

    • Optionalconsumer_commit_ref?: string

      Optional opaque, non-secret consumer checkpoint, transaction, or load reference. It is operational evidence, not authorization, a credential, a URL, or instructions; receivers compare or display it as inert text and never dereference or execute it.

    • Optionalseller_ledger_snapshot_id?: string

      Optional seller-issued get_reporting_status snapshot on which this statement was based. It is evidence context, not consumer authority over that snapshot.

    • Optionalseller_ledger_as_of?: string

      ledger_as_of echoed from seller_ledger_snapshot_id. Present if and only if seller_ledger_snapshot_id is present.

    • Optionalrecorded_at?: string

      When the seller durably recorded this immutable statement.

    Settings
    Member Visibility

    On This Page
    Properties