@adcp/sdk 14.0.0-beta.26 → 14.0.0-beta.28

package/dist/lib/reporting/reconciliation.d.mts

@@ -0,0 +1,199 @@
+import type { GetReportingStatusRequest, GetReportingStatusResponse, ReportingCanonicalContentDigest, ReportingControlTotal, ReportingMaterialization, ReportingObligation, ReportingReceipt, ReportingRevision, SyncReportingReceiptsRequest, SyncReportingReceiptsResponse } from '../types/tools.generated.mjs';
+import { type ReportingCredentialProvider, type ReportingManifestInspectorOptions, type ReportingResourceReader } from './inspection.mjs';
+type ManagedReportingObligation = ReportingObligation & {
+    scope_resolved_at?: string;
+    coverage?: ReportingCoverageEvidence;
+};
+export interface ReportingCoverageLimitation {
+    reason: 'offering_unsupported' | 'account_entitlement_unavailable' | 'credential_scope_insufficient' | 'provider_limitation' | 'capability_unknown';
+    media_buy_id: string;
+    package_ids?: string[];
+}
+export interface ReportingCoverageEvidence {
+    status: 'full' | 'partial' | 'none' | 'unknown';
+    evaluated_at: string;
+    media_buy_ids: string[];
+    fully_covered_media_buy_ids: string[];
+    partially_covered_media_buy_ids: string[];
+    unsupported_media_buy_ids: string[];
+    unknown_media_buy_ids: string[];
+    package_ids: string[];
+    covered_package_ids: string[];
+    unsupported_package_ids: string[];
+    unknown_package_ids: string[];
+    limitations: ReportingCoverageLimitation[];
+}
+export type ExpectedReportingCoverage = Omit<ReportingCoverageEvidence, 'evaluated_at' | 'limitations'>;
+export type ReportingCanonicalDigestEvidence = ReportingCanonicalContentDigest & {
+    canonicalization_uri: string;
+};
+type ManagedReportingRevision = Omit<ReportingRevision, 'canonical_content_digest'> & {
+    report_definition_uri?: string;
+    report_definition_sha256?: string;
+    finality_basis?: 'source_final' | 'contractual_cutoff' | 'stabilized';
+    finality_policy_id?: string;
+    finalized_at?: string;
+    coverage?: ReportingCoverageEvidence;
+    canonical_content_digest?: ReportingCanonicalDigestEvidence;
+};
+export interface ReportingReconciliationClient {
+    getReportingStatus(params: GetReportingStatusRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<GetReportingStatusResponse>;
+    syncReportingReceipts(params: SyncReportingReceiptsRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<SyncReportingReceiptsResponse>;
+}
+export interface ReportingLedger {
+    ledgerSnapshotId: string;
+    ledgerAsOf: string;
+    accountId: string;
+    scope: NonNullable<GetReportingStatusResponse['scope']>;
+    obligations: ManagedReportingObligation[];
+    revisions: ManagedReportingRevision[];
+    materializations: ReportingMaterialization[];
+    receipts: ReportingReceipt[];
+}
+export interface ReportingLedgerLimits {
+    maxPages?: number;
+    maxRecords?: number;
+    maxLoadMs?: number;
+}
+interface ExpectedReportingPeriodBase {
+    deliveryConfigId: string;
+    deliveryConfigVersion: number;
+    reportDefinitionId: string;
+    feedPurpose: ReportingObligation['feed_purpose'];
+    reportingProfile: string;
+    mediaBuyIds: string[];
+    destinationRef: string;
+    deliveryMethod: ReportingMaterialization['method'];
+    requiredFinality: ReportingObligation['required_finality'];
+    reconciliationMode: ReportingObligation['reconciliation_mode'];
+    coverageRequirement: 'full' | 'allow_partial';
+    coverage: ExpectedReportingCoverage;
+    reportDefinitionUri: string;
+    reportDefinitionSha256: string;
+    schemaVersion: string;
+    schemaUri: string;
+    schemaSha256: string;
+    schemaDialect: 'https://json-schema.org/draft/2020-12/schema';
+    schemaRefPolicy: 'local_fragment_only';
+    /** Consumer-pinned finality rule, required whenever an official revision is accepted. */
+    officialFinality?: {
+        policyId: string;
+        basis: 'source_final' | 'contractual_cutoff' | 'stabilized';
+    };
+    periodStart: string;
+    periodEnd: string;
+}
+interface ExpectedCanonicalization {
+    id: string;
+    uri: string;
+    sha256: string;
+    primaryKeys: string[];
+}
+export type ExpectedReportingPeriod = ExpectedReportingPeriodBase & ({
+    verificationProfile: 'canonical_digest';
+    canonicalization: ExpectedCanonicalization;
+} | {
+    verificationProfile: 'manifest_checksums' | 'native_commit';
+    canonicalization?: never;
+});
+export interface ReportingObservation {
+    rowCount: number;
+    controlTotals: ReportingControlTotal[];
+    canonicalContentDigest?: ReportingCanonicalDigestEvidence;
+    manifestSha256?: string;
+    nativeVersionRef?: string;
+    consumerCommitRef?: string;
+}
+export interface ReportingCheckpointKey {
+    /** Caller-defined stable seller + authenticated-principal scope. */
+    consumerScope: string;
+    accountId: string;
+    reportingObligationId: string;
+    reportingRevisionId: string;
+    reportingMaterializationId: string;
+    destinationRef: string;
+}
+export interface ReportingCheckpoint {
+    receipt: ReportingReceipt;
+    receiptSyncIdempotencyKey: string;
+    /** SHA-256 of the exact obligation, revision, materialization, and consumer expectation inspected. */
+    contextFingerprint: string;
+}
+export interface ReportingCheckpointStore {
+    get(key: ReportingCheckpointKey): Promise<ReportingCheckpoint | undefined>;
+    put(key: ReportingCheckpointKey, checkpoint: ReportingCheckpoint): Promise<void>;
+}
+export interface ReportingInspectionContext {
+    obligation: ManagedReportingObligation;
+    revision: ManagedReportingRevision;
+    materialization: ReportingMaterialization;
+    /** Independently selected consumer contract and coverage expectations. */
+    expected: ExpectedReportingPeriod;
+}
+export interface ObligationReconciliation {
+    reportingObligationId: string;
+    definitive: boolean;
+    reportingRevisionId?: string;
+    reportingMaterializationId?: string;
+    reasons: string[];
+}
+export interface ReportingReconciliationResult {
+    definitive: boolean;
+    ledger: ReportingLedger;
+    obligations: ObligationReconciliation[];
+    missingExpectedPeriods: ExpectedReportingPeriod[];
+    submittedReceipts: ReportingReceipt[];
+    totalsByRevision: Array<{
+        reportingRevisionId: string;
+        rowCount: number;
+        controlTotals: ReportingControlTotal[];
+        coverageStatus: ReportingCoverageEvidence['status'];
+        coveredPackageIds: string[];
+        packageIds: string[];
+    }>;
+}
+interface ReconcileReportingBaseOptions {
+    client: ReportingReconciliationClient;
+    request: Omit<GetReportingStatusRequest, 'view' | 'pagination'>;
+    expectedPeriods: ExpectedReportingPeriod[];
+    maxSnapshotRestarts?: number;
+    maxInspectionAttempts?: number;
+    inspectionRetryBaseDelayMs?: number;
+    ledgerLimits?: ReportingLedgerLimits;
+    now?: Date;
+}
+type ReportingCheckpointOptions = {
+    checkpointStore?: never;
+    checkpointScope?: never;
+} | {
+    checkpointStore: ReportingCheckpointStore;
+    /** Stable non-secret seller + authenticated-principal scope. */
+    checkpointScope: string;
+};
+export type ReconcileReportingOptions<TCredential = unknown> = ReconcileReportingBaseOptions & ReportingCheckpointOptions & ({
+    /** Advanced inspection override. */
+    inspect: (context: ReportingInspectionContext) => Promise<ReportingObservation>;
+    resourceReader?: never;
+    credentialProvider?: never;
+    manifestInspectorOptions?: never;
+} | {
+    inspect?: never;
+    /** Pluggable destination reader used by the SDK-managed manifest inspector. */
+    resourceReader: ReportingResourceReader<TCredential>;
+    credentialProvider?: ReportingCredentialProvider<TCredential>;
+    manifestInspectorOptions: Omit<ReportingManifestInspectorOptions<TCredential>, 'reader' | 'credentialProvider'>;
+});
+export declare class ReportingReconciliationError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function isReportingCoverageEvidence(value: unknown): value is ReportingCoverageEvidence;
+export declare function loadReportingLedger(client: ReportingReconciliationClient, request: Omit<GetReportingStatusRequest, 'view' | 'pagination'>, maxSnapshotRestarts?: number, limits?: ReportingLedgerLimits): Promise<ReportingLedger>;
+export declare function evaluateReportingLedger(ledger: ReportingLedger, expectedPeriods: ExpectedReportingPeriod[] | undefined, now?: Date): Omit<ReportingReconciliationResult, 'submittedReceipts'>;
+export declare function buildReportingReceipt(context: ReportingInspectionContext, observation: ReportingObservation, reportingReceiptId?: string, observedAt?: string): ReportingReceipt;
+export declare function reconcileReporting<TCredential = unknown>(options: ReconcileReportingOptions<TCredential>): Promise<ReportingReconciliationResult>;
+export {};

package/dist/lib/reporting/reconciliation.d.ts

@@ -0,0 +1,199 @@
+import type { GetReportingStatusRequest, GetReportingStatusResponse, ReportingCanonicalContentDigest, ReportingControlTotal, ReportingMaterialization, ReportingObligation, ReportingReceipt, ReportingRevision, SyncReportingReceiptsRequest, SyncReportingReceiptsResponse } from '../types/tools.generated';
+import { type ReportingCredentialProvider, type ReportingManifestInspectorOptions, type ReportingResourceReader } from './inspection';
+type ManagedReportingObligation = ReportingObligation & {
+    scope_resolved_at?: string;
+    coverage?: ReportingCoverageEvidence;
+};
+export interface ReportingCoverageLimitation {
+    reason: 'offering_unsupported' | 'account_entitlement_unavailable' | 'credential_scope_insufficient' | 'provider_limitation' | 'capability_unknown';
+    media_buy_id: string;
+    package_ids?: string[];
+}
+export interface ReportingCoverageEvidence {
+    status: 'full' | 'partial' | 'none' | 'unknown';
+    evaluated_at: string;
+    media_buy_ids: string[];
+    fully_covered_media_buy_ids: string[];
+    partially_covered_media_buy_ids: string[];
+    unsupported_media_buy_ids: string[];
+    unknown_media_buy_ids: string[];
+    package_ids: string[];
+    covered_package_ids: string[];
+    unsupported_package_ids: string[];
+    unknown_package_ids: string[];
+    limitations: ReportingCoverageLimitation[];
+}
+export type ExpectedReportingCoverage = Omit<ReportingCoverageEvidence, 'evaluated_at' | 'limitations'>;
+export type ReportingCanonicalDigestEvidence = ReportingCanonicalContentDigest & {
+    canonicalization_uri: string;
+};
+type ManagedReportingRevision = Omit<ReportingRevision, 'canonical_content_digest'> & {
+    report_definition_uri?: string;
+    report_definition_sha256?: string;
+    finality_basis?: 'source_final' | 'contractual_cutoff' | 'stabilized';
+    finality_policy_id?: string;
+    finalized_at?: string;
+    coverage?: ReportingCoverageEvidence;
+    canonical_content_digest?: ReportingCanonicalDigestEvidence;
+};
+export interface ReportingReconciliationClient {
+    getReportingStatus(params: GetReportingStatusRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<GetReportingStatusResponse>;
+    syncReportingReceipts(params: SyncReportingReceiptsRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<SyncReportingReceiptsResponse>;
+}
+export interface ReportingLedger {
+    ledgerSnapshotId: string;
+    ledgerAsOf: string;
+    accountId: string;
+    scope: NonNullable<GetReportingStatusResponse['scope']>;
+    obligations: ManagedReportingObligation[];
+    revisions: ManagedReportingRevision[];
+    materializations: ReportingMaterialization[];
+    receipts: ReportingReceipt[];
+}
+export interface ReportingLedgerLimits {
+    maxPages?: number;
+    maxRecords?: number;
+    maxLoadMs?: number;
+}
+interface ExpectedReportingPeriodBase {
+    deliveryConfigId: string;
+    deliveryConfigVersion: number;
+    reportDefinitionId: string;
+    feedPurpose: ReportingObligation['feed_purpose'];
+    reportingProfile: string;
+    mediaBuyIds: string[];
+    destinationRef: string;
+    deliveryMethod: ReportingMaterialization['method'];
+    requiredFinality: ReportingObligation['required_finality'];
+    reconciliationMode: ReportingObligation['reconciliation_mode'];
+    coverageRequirement: 'full' | 'allow_partial';
+    coverage: ExpectedReportingCoverage;
+    reportDefinitionUri: string;
+    reportDefinitionSha256: string;
+    schemaVersion: string;
+    schemaUri: string;
+    schemaSha256: string;
+    schemaDialect: 'https://json-schema.org/draft/2020-12/schema';
+    schemaRefPolicy: 'local_fragment_only';
+    /** Consumer-pinned finality rule, required whenever an official revision is accepted. */
+    officialFinality?: {
+        policyId: string;
+        basis: 'source_final' | 'contractual_cutoff' | 'stabilized';
+    };
+    periodStart: string;
+    periodEnd: string;
+}
+interface ExpectedCanonicalization {
+    id: string;
+    uri: string;
+    sha256: string;
+    primaryKeys: string[];
+}
+export type ExpectedReportingPeriod = ExpectedReportingPeriodBase & ({
+    verificationProfile: 'canonical_digest';
+    canonicalization: ExpectedCanonicalization;
+} | {
+    verificationProfile: 'manifest_checksums' | 'native_commit';
+    canonicalization?: never;
+});
+export interface ReportingObservation {
+    rowCount: number;
+    controlTotals: ReportingControlTotal[];
+    canonicalContentDigest?: ReportingCanonicalDigestEvidence;
+    manifestSha256?: string;
+    nativeVersionRef?: string;
+    consumerCommitRef?: string;
+}
+export interface ReportingCheckpointKey {
+    /** Caller-defined stable seller + authenticated-principal scope. */
+    consumerScope: string;
+    accountId: string;
+    reportingObligationId: string;
+    reportingRevisionId: string;
+    reportingMaterializationId: string;
+    destinationRef: string;
+}
+export interface ReportingCheckpoint {
+    receipt: ReportingReceipt;
+    receiptSyncIdempotencyKey: string;
+    /** SHA-256 of the exact obligation, revision, materialization, and consumer expectation inspected. */
+    contextFingerprint: string;
+}
+export interface ReportingCheckpointStore {
+    get(key: ReportingCheckpointKey): Promise<ReportingCheckpoint | undefined>;
+    put(key: ReportingCheckpointKey, checkpoint: ReportingCheckpoint): Promise<void>;
+}
+export interface ReportingInspectionContext {
+    obligation: ManagedReportingObligation;
+    revision: ManagedReportingRevision;
+    materialization: ReportingMaterialization;
+    /** Independently selected consumer contract and coverage expectations. */
+    expected: ExpectedReportingPeriod;
+}
+export interface ObligationReconciliation {
+    reportingObligationId: string;
+    definitive: boolean;
+    reportingRevisionId?: string;
+    reportingMaterializationId?: string;
+    reasons: string[];
+}
+export interface ReportingReconciliationResult {
+    definitive: boolean;
+    ledger: ReportingLedger;
+    obligations: ObligationReconciliation[];
+    missingExpectedPeriods: ExpectedReportingPeriod[];
+    submittedReceipts: ReportingReceipt[];
+    totalsByRevision: Array<{
+        reportingRevisionId: string;
+        rowCount: number;
+        controlTotals: ReportingControlTotal[];
+        coverageStatus: ReportingCoverageEvidence['status'];
+        coveredPackageIds: string[];
+        packageIds: string[];
+    }>;
+}
+interface ReconcileReportingBaseOptions {
+    client: ReportingReconciliationClient;
+    request: Omit<GetReportingStatusRequest, 'view' | 'pagination'>;
+    expectedPeriods: ExpectedReportingPeriod[];
+    maxSnapshotRestarts?: number;
+    maxInspectionAttempts?: number;
+    inspectionRetryBaseDelayMs?: number;
+    ledgerLimits?: ReportingLedgerLimits;
+    now?: Date;
+}
+type ReportingCheckpointOptions = {
+    checkpointStore?: never;
+    checkpointScope?: never;
+} | {
+    checkpointStore: ReportingCheckpointStore;
+    /** Stable non-secret seller + authenticated-principal scope. */
+    checkpointScope: string;
+};
+export type ReconcileReportingOptions<TCredential = unknown> = ReconcileReportingBaseOptions & ReportingCheckpointOptions & ({
+    /** Advanced inspection override. */
+    inspect: (context: ReportingInspectionContext) => Promise<ReportingObservation>;
+    resourceReader?: never;
+    credentialProvider?: never;
+    manifestInspectorOptions?: never;
+} | {
+    inspect?: never;
+    /** Pluggable destination reader used by the SDK-managed manifest inspector. */
+    resourceReader: ReportingResourceReader<TCredential>;
+    credentialProvider?: ReportingCredentialProvider<TCredential>;
+    manifestInspectorOptions: Omit<ReportingManifestInspectorOptions<TCredential>, 'reader' | 'credentialProvider'>;
+});
+export declare class ReportingReconciliationError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function isReportingCoverageEvidence(value: unknown): value is ReportingCoverageEvidence;
+export declare function loadReportingLedger(client: ReportingReconciliationClient, request: Omit<GetReportingStatusRequest, 'view' | 'pagination'>, maxSnapshotRestarts?: number, limits?: ReportingLedgerLimits): Promise<ReportingLedger>;
+export declare function evaluateReportingLedger(ledger: ReportingLedger, expectedPeriods: ExpectedReportingPeriod[] | undefined, now?: Date): Omit<ReportingReconciliationResult, 'submittedReceipts'>;
+export declare function buildReportingReceipt(context: ReportingInspectionContext, observation: ReportingObservation, reportingReceiptId?: string, observedAt?: string): ReportingReceipt;
+export declare function reconcileReporting<TCredential = unknown>(options: ReconcileReportingOptions<TCredential>): Promise<ReportingReconciliationResult>;
+export {};