@adcp/sdk 14.0.0-rc.37 → 14.0.0-rc.39

package/dist/lib/reporting/ledger/managed.d.mts

@@ -0,0 +1,355 @@
+import type { ReportingAdjustmentReceipt, ReportingDeliveryCapabilities, ReportingMaterialization, ReportingReceipt, ReportingResource, ReportingVerification, SyncReportingReceiptsResponse } from '../../types/index.mjs';
+import type { AdcpToolMap } from '../../server/create-adcp-server.mjs';
+import { createReportingDeliveryHandler, createReportingStatusHandler } from './handler.mjs';
+import type { ReportingStatusConsumerScopeOptionsV1 } from './handler.mjs';
+import type { ReportingLedgerAdjustmentV1, ReportingLedgerObligationV1, ReportingLedgerRevisionV1, ReportingLedgerStore, ReportingManagedDeliveryBindingV1 } from './types.mjs';
+export interface ReportingDestinationAuthorizationV1 {
+    account_id: string;
+    destination_ref: string;
+    generation: number;
+    authorized_at: string;
+    revoked_at?: string;
+    cleanup_completed_at?: string;
+}
+export interface ReportingManagedDeliveryLeaseV1 {
+    materialization: ReportingMaterialization;
+    binding: ReportingManagedDeliveryBindingV1;
+    obligation: ReportingLedgerObligationV1;
+    revision: ReportingLedgerRevisionV1;
+    owner: string;
+    generation: number;
+    expires_at: string;
+}
+export interface ReportingDestinationRevocationLeaseV1 {
+    authorization: ReportingDestinationAuthorizationV1;
+    owner: string;
+    generation: number;
+    expires_at: string;
+    /**
+     * SLA facts as the ledger's own clock sees them.
+     *
+     * The advertised window is measured from the instant the revocation was
+     * committed, so deciding whether a grant is still inside it on the worker's
+     * host clock lets skew silently extend or collapse the promise. A store
+     * that can compute them reports them here; `overdue` is true at the exact
+     * boundary, because the window is elapsed once it has been reached.
+     */
+    revoked_at?: string;
+    overdue?: boolean;
+    remaining_milliseconds?: number;
+}
+export type ReportingReceiptBatchEntryV1 = {
+    kind: 'revision';
+    receipt: ReportingReceipt;
+} | {
+    kind: 'adjustment';
+    receipt: ReportingAdjustmentReceipt;
+};
+export interface ReportingReceiptBatchInputV1 {
+    account_id: string;
+    consumer_id: string;
+    idempotency_key: string;
+    request_fingerprint: string;
+    entries: ReportingReceiptBatchEntryV1[];
+    received_at: string;
+}
+/** Agent-wide Managed Delivery promises durably shared by every replica. */
+export interface ReportingManagedDeliveryAdvertisedPoliciesV1 {
+    automatedRecoveryWindowSeconds: number;
+    statusRetentionDays: number;
+    resourceRetentionDays: number;
+    authorizationRevocationSeconds: number;
+}
+export interface ReportingManagedDeliveryStore {
+    /**
+     * Prove that this store shares the supplied Core authority and has its
+     * durable schema installed. Throw an actionable configuration error when
+     * either condition is false; return true only after an operational probe.
+     */
+    probe(coreStore: ReportingLedgerStore): Promise<boolean>;
+    /**
+     * Direct-store introspection of installed Core recovery windows.
+     *
+     * This is optional and non-authoritative for capability publication. Runtime
+     * factories use `adoptAdvertisedPolicies`, whose store-side transaction must
+     * validate binding compatibility while holding the policy fence.
+     */
+    listInstalledRecoveryWindowSeconds?(): Promise<number[]>;
+    /**
+     * Records the agent-wide advertised recovery window so the store can hold
+     * later binding installs to it.
+     *
+     * Optional on the structural interface for source compatibility with
+     * direct-store integrations. The runtime factory uses the combined atomic
+     * hook below; this separate hook remains useful when bindings are installed
+     * without a runtime.
+     */
+    adoptAdvertisedRecoveryWindowSeconds?(seconds: number): Promise<void>;
+    /**
+     * Durably registers the advertised `status_retention_days`.
+     *
+     * Direct-store integrations can use this separate hook when no runtime is
+     * publishing the full capability policy. The runtime factory uses the
+     * combined atomic hook below so a failed startup cannot partially register
+     * its promises.
+     */
+    adoptAdvertisedStatusRetentionDays?(days: number): Promise<void>;
+    /**
+     * Atomically adopts every policy advertised by a Managed Delivery runtime
+     * and returns the strongest values enforced across all replicas.
+     *
+     * Recovery and authorization-revocation windows are maximum-delay promises,
+     * so the adopted value may only decrease. Status and resource retention are
+     * minimum-duration promises, so the adopted value may only increase. The
+     * operation must serialize with `installBinding`, validate every installed
+     * binding against the adopted recovery bound while holding that fence, and
+     * leave all four values unchanged if any validation or write fails. The
+     * store must enforce the adopted resource and revocation values at its
+     * settlement and revocation-claim boundaries.
+     *
+     * Optional on the base interface so direct-store integrations that use the
+     * separate hooks remain source-compatible. Capability publication requires
+     * this combined hook because two independent writes cannot prevent a failed
+     * startup from leaving only one promise registered.
+     */
+    adoptAdvertisedPolicies?(policy: ReportingManagedDeliveryAdvertisedPoliciesV1): Promise<ReportingManagedDeliveryAdvertisedPoliciesV1>;
+    authorizeDestination(input: Omit<ReportingDestinationAuthorizationV1, 'revoked_at' | 'cleanup_completed_at'>): Promise<void>;
+    revokeDestination(input: {
+        account_id: string;
+        destination_ref: string;
+        generation: number;
+        revoked_at: string;
+    }): Promise<boolean>;
+    installBinding(binding: ReportingManagedDeliveryBindingV1): Promise<{
+        inserted: boolean;
+    }>;
+    planMaterializations(input?: {
+        account_id?: string;
+        limit?: number;
+    }): Promise<number>;
+    /**
+     * Fails materializations that have used every delivery attempt.
+     *
+     * The claim predicate stops handing them out, so without a sweep they stay
+     * `pending` forever — and the planner skips any obligation with a pending
+     * row, so the revision is never retried or replanned either.
+     */
+    failExhaustedMaterializations?(input?: {
+        account_id?: string;
+        limit?: number;
+    }): Promise<number>;
+    claimMaterialization(input: {
+        owner: string;
+        now: string;
+        lease_milliseconds: number;
+        account_id?: string;
+    }): Promise<ReportingManagedDeliveryLeaseV1 | null>;
+    settleMaterialization(input: {
+        lease: ReportingManagedDeliveryLeaseV1;
+        now: string;
+        /**
+         * Retention the store must see satisfied on its own clock.
+         *
+         * The worker checks it too, but a worker running behind would otherwise
+         * accept a resource the database already considers under-retained.
+         */
+        minimum_resource_retention_days?: number;
+        outcome: {
+            status: 'available' | 'delivered';
+            resource: ReportingResource;
+            verification: ReportingVerification;
+        } | {
+            status: 'failed';
+            failure_code: string;
+        };
+    }): Promise<boolean>;
+    claimRevocation(input: {
+        owner: string;
+        now: string;
+        lease_milliseconds: number;
+        account_id?: string;
+        /** Advertised window, so the store can compute SLA facts on its own clock. */
+        authorization_revocation_seconds?: number;
+    }): Promise<ReportingDestinationRevocationLeaseV1 | null>;
+    completeRevocation(input: {
+        lease: ReportingDestinationRevocationLeaseV1;
+        completed_at: string;
+    }): Promise<boolean>;
+    /**
+     * Releases a cleanup lease after a failed attempt so the grant is
+     * immediately reclaimable.
+     *
+     * Required, not optional: without it a failed attempt keeps its lease as
+     * the retry delay, which defers the next attempt and hides an overdue grant
+     * behind a lease that has not expired. `claimRevocation` orders by
+     * `cleanup_lease_generation`, and a failed attempt has already incremented
+     * it, so releasing cannot let one broken grant starve the queue.
+     */
+    releaseRevocation(input: {
+        lease: ReportingDestinationRevocationLeaseV1;
+        /** Holds the grant out of selection briefly so a retry is not a tight loop. */
+        backoff_milliseconds?: number;
+    }): Promise<boolean>;
+    getReadableResource(input: {
+        account_id: string;
+        resource_ref: string;
+    }): Promise<{
+        materialization: ReportingMaterialization;
+        binding: ReportingManagedDeliveryBindingV1;
+    } | null>;
+    isAuthorizationCurrent(input: {
+        account_id: string;
+        destination_ref: string;
+        generation: number;
+    }): Promise<boolean>;
+    syncReceiptBatch(input: ReportingReceiptBatchInputV1): Promise<SyncReportingReceiptsResponse['results']>;
+}
+export interface ReportingManagedDeliveryAdapterV1 {
+    /** Profiles this installed adapter can actually verify through its consumer/destination path. */
+    readonly verificationProfiles: readonly ReportingVerification['verification_profile'][];
+    /** Provider revoke installs a generation tombstone that fences late writes. */
+    readonly revocationFencesDeliveryGenerations: true;
+    deliver(input: Readonly<{
+        materialization: ReportingMaterialization;
+        binding: ReportingManagedDeliveryBindingV1;
+        obligation: ReportingLedgerObligationV1;
+        revision: ReportingLedgerRevisionV1;
+        maxBytes: number;
+    }>, context: {
+        signal: AbortSignal;
+    }): Promise<{
+        status: 'available' | 'delivered';
+        resource: ReportingResource;
+        verification: ReportingVerification;
+    }>;
+    read(input: Readonly<{
+        materialization: ReportingMaterialization;
+        binding: ReportingManagedDeliveryBindingV1;
+        resource: ReportingResource;
+        maxBytes: number;
+    }>, context: {
+        signal: AbortSignal;
+    }): Promise<Uint8Array>;
+    /** Remove seller-controlled provider grants. The durable deny is committed before this call. */
+    revoke(input: Readonly<{
+        authorization: ReportingDestinationAuthorizationV1;
+    }>, context: {
+        signal: AbortSignal;
+    }): Promise<void>;
+}
+export interface ReportingManagedDeliveryWorkerOptionsV1 {
+    signal?: AbortSignal;
+    now?: () => Date;
+    maxIterations?: number;
+    leaseMilliseconds?: number;
+    deliveryDeadlineMilliseconds?: number;
+    resourceMaxBytes?: number;
+    /** Capability minimum enforced in addition to each immutable binding. */
+    minimumResourceRetentionDays?: number;
+    /**
+     * Mirror of the advertised `authorization_revocation_seconds`. Supplying it
+     * makes the scheduler honour the promise instead of merely printing it: a
+     * cleanup attempt is never given a budget that would run past
+     * `revoked_at + authorizationRevocationSeconds`, a failed attempt never holds
+     * a retry lease longer than the whole promised window, and a grant that has
+     * already outlived the window is counted in `revocationsOverdue` so the
+     * breach is observable rather than silent. Omit it only for a worker that is
+     * not backing an advertised capability.
+     */
+    authorizationRevocationSeconds?: number;
+    account_id?: string;
+}
+export interface CreateReportingManagedDeliveryRuntimeOptionsV1<TContext extends {
+    account?: unknown;
+} = {
+    account?: unknown;
+}> {
+    coreStore: ReportingLedgerStore;
+    store: ReportingManagedDeliveryStore & Required<Pick<ReportingManagedDeliveryStore, 'adoptAdvertisedPolicies'>>;
+    adapter: ReportingManagedDeliveryAdapterV1;
+    offerings: ReportingDeliveryCapabilities['offerings'];
+    automatedRecoveryWindowSeconds: number;
+    statusRetentionDays: number;
+    resourceRetentionDays: number;
+    authorizationRevocationSeconds: number;
+    resolveConsumerId?: (context: TContext) => string | Promise<string>;
+    consumerMismatchEscalation?: ReportingStatusConsumerScopeOptionsV1<TContext>['consumerMismatchEscalation'];
+}
+export interface ReportingManagedDeliveryRuntimeV1<TContext extends {
+    account?: unknown;
+} = {
+    account?: unknown;
+}> {
+    reportingDeliveryCapabilities: ReportingDeliveryCapabilities;
+    getReportingStatus: ReturnType<typeof createReportingStatusHandler<TContext>>;
+    getMediaBuyDelivery: ReturnType<typeof createReportingDeliveryHandler>;
+    syncReportingReceipts?: (request: AdcpToolMap['sync_reporting_receipts']['params'], context: TContext & {
+        account?: unknown;
+    }) => Promise<SyncReportingReceiptsResponse>;
+    runWorker(options?: ReportingManagedDeliveryWorkerOptionsV1): Promise<{
+        planned: number;
+        claimed: number;
+        delivered: number;
+        failed: number;
+        revocationsCompleted: number;
+        revocationsOverdue: number;
+        /** Materializations failed for using every delivery attempt. */
+        exhausted: number;
+    }>;
+    readResource(input: {
+        account_id: string;
+        resource_ref: string;
+        signal?: AbortSignal;
+        maxBytes?: number;
+        deadlineMilliseconds?: number;
+    }): Promise<Uint8Array | null>;
+}
+/**
+ * Wires all operational components before returning any Managed Delivery
+ * capability claim. A missing receipt principal resolver limits the runtime to
+ * Managed Delivery even if a consumer-receipt offering was supplied.
+ */
+export declare function createReportingManagedDeliveryRuntime<TContext extends {
+    account?: unknown;
+} = {
+    account?: unknown;
+}>(options: CreateReportingManagedDeliveryRuntimeOptionsV1<TContext>): Promise<ReportingManagedDeliveryRuntimeV1<TContext>>;
+export declare function createSyncReportingReceiptsHandler<TContext extends {
+    account?: unknown;
+}>(store: ReportingManagedDeliveryStore, resolveConsumerId: (context: TContext) => string | Promise<string>, now?: () => Date): (request: AdcpToolMap["sync_reporting_receipts"]["params"], context: TContext) => Promise<SyncReportingReceiptsResponse>;
+export declare function runManagedDeliveryWorker(store: ReportingManagedDeliveryStore, adapter: ReportingManagedDeliveryAdapterV1, options?: ReportingManagedDeliveryWorkerOptionsV1): Promise<{
+    exhausted: number;
+    planned: number;
+    claimed: number;
+    delivered: number;
+    failed: number;
+    revocationsCompleted: number;
+    revocationsOverdue: number;
+}>;
+export declare function readManagedReportingResource(store: ReportingManagedDeliveryStore, adapter: ReportingManagedDeliveryAdapterV1, input: {
+    account_id: string;
+    resource_ref: string;
+    signal?: AbortSignal;
+    maxBytes?: number;
+    deadlineMilliseconds?: number;
+}): Promise<Uint8Array | null>;
+export declare function assertMaterializationOutcome(lease: ReportingManagedDeliveryLeaseV1, outcome: {
+    status: 'available' | 'delivered';
+    resource: ReportingResource;
+    verification: ReportingVerification;
+}, now: string, minimumResourceRetentionDays?: number): void;
+export declare function receiptEvidenceMatches(receipt: ReportingReceipt, materialization: ReportingMaterialization): boolean;
+export declare function adjustmentReceiptEvidenceMatches(receipt: ReportingAdjustmentReceipt, adjustment: ReportingLedgerAdjustmentV1): boolean;
+/**
+ * Refuses a retained resource location that carries credential syntax.
+ *
+ * Exported because the worker is not the only way a resource reaches
+ * storage: a caller driving `settleMaterialization` directly must be held to
+ * the same rule, or a presigned location is persisted and then published in
+ * `get_reporting_status`.
+ */
+export declare function assertCredentialFreeReportingResourceLocationV1(location: string): void;
+/** Stable helper for immutable binding creation. */
+export declare function reportingManagedDeliveryBindingV1(input: Omit<ReportingManagedDeliveryBindingV1, 'created_at' | 'semantic_fingerprint'> & {
+    created_at?: string;
+}): ReportingManagedDeliveryBindingV1;