@atcn/sdk 1.3.0

package/dist/subledger.d.ts

@@ -0,0 +1,670 @@
+import type { z } from "zod";
+import { type AllocationInputSchema, type AllocationRuleInputSchema, type AttestableField, type Correction, type DelegationEventInputSchema, type DelegationInputSchema, type EvidenceRef, type FinancialEventInput, type OperatorKeyRecord, type ProviderInputSchema, type ResponseType, type SignedClosure, type SignedReceipt, type TaskInputSchema } from "@atcn/subledger";
+import { AtcnClient, type ClientOptions } from "./client.js";
+type Json = Record<string, unknown>;
+type Opts = {
+    idempotencyKey?: string;
+};
+/** Caller-supplied references address records before their server IDs are known: ext("job-42"). */
+export declare const ext: (externalRef: string) => string;
+/** Idempotency key derived from the caller's stable references; long references are hashed to fit 8-200 chars. */
+export declare function stableKey(kind: string, ...parts: string[]): string;
+/**
+ * Small, independent subledger operations (PRD §15). Default idempotency keys derive from the caller's own
+ * stable references, so a retry from anywhere in the orchestrator never creates a second record.
+ */
+export declare class SubledgerClient {
+    readonly http: AtcnClient;
+    constructor(options: ClientOptions | AtcnClient);
+    createTask(input: z.input<typeof TaskInputSchema>, opts?: Opts): Promise<Json>;
+    getTask(taskId: string): Promise<Json>;
+    listTasks(query?: {
+        status?: "open" | "closed";
+        external_ref?: string;
+    }): Promise<{
+        items: Json[];
+    }>;
+    /** Admin only. Principals are "user:<id>" or "api_key:<id>". */
+    getTaskAccess(taskId: string): Promise<Json>;
+    updateTaskAccess(taskId: string, input: {
+        restricted?: boolean;
+        grant?: string[];
+        revoke?: string[];
+    }, opts?: Opts): Promise<Json>;
+    createDelegation(taskId: string, input: z.input<typeof DelegationInputSchema>, opts?: Opts): Promise<Json>;
+    assignProvider(delegationId: string, providerId: string, opts?: Opts): Promise<Json>;
+    appendDelegationEvent(delegationId: string, input: z.input<typeof DelegationEventInputSchema>, opts?: Opts): Promise<Json>;
+    recordFinancialEvent(input: FinancialEventInput, opts?: Opts): Promise<{
+        financial_event: Json;
+        deduplicated: boolean;
+        attributed?: boolean;
+        attribution: Json | null;
+        match_id: string | null;
+        exception_ids: string[];
+    }>;
+    importCsv(csv: string, opts?: Opts): Promise<{
+        imported: number;
+        deduplicated: number;
+        rejected: number;
+        rows: Json[];
+    }>;
+    listFinancialEvents(query?: {
+        unattributed?: "true" | "false";
+        source?: string;
+    }): Promise<{
+        items: Json[];
+    }>;
+    allocate(financialEventId: string, input: z.input<typeof AllocationInputSchema>, opts?: Opts): Promise<Json>;
+    createAllocationRule(input: z.input<typeof AllocationRuleInputSchema>, opts?: Opts): Promise<Json>;
+    listMatches(status?: "pending" | "confirmed" | "dismissed"): Promise<{
+        items: Json[];
+    }>;
+    confirmMatch(matchId: string, node: {
+        task_id: string;
+        delegation_id?: string | null;
+    }, opts?: Opts): Promise<Json>;
+    financialSummary(taskId: string, query?: {
+        report_currency?: string;
+        as_of?: string;
+    }): Promise<Json>;
+    listExceptions(query?: {
+        task_id?: string;
+        status?: "open" | "resolved" | "dismissed";
+    }): Promise<{
+        items: Json[];
+    }>;
+    resolveException(exceptionId: string, input: {
+        status: "resolved" | "dismissed";
+        resolution: string;
+    }, opts?: Opts): Promise<Json>;
+    reportCaptureGap(taskId: string, gap: {
+        delegation_id?: string | null;
+        kind: "capture_failed" | "queue_overflow" | "provider_undisclosed" | "manual_gap";
+        detail: string;
+    }, opts?: Opts): Promise<Json>;
+    closeTask(taskId: string, opts?: Opts): Promise<{
+        closure: SignedClosure;
+        digest: string;
+    }>;
+    getClosure(taskId: string, version?: number): Promise<{
+        payload: {
+            document_type: "atcn.subledger.closure";
+            schema_version: "1.3" | "1.2";
+            closure_id: string;
+            version: number;
+            previous_closure_id: string | null;
+            previous_closure_digest: string | null;
+            generated_at: string;
+            issuer: {
+                operator_id: string;
+                operator_name: string;
+                signed_by: "atcn-hosted-service" | "atcn-local-runner";
+            };
+            task: {
+                task_id: string;
+                external_ref: string;
+                currency: string;
+                budget_minor: number | null;
+                customer_ref: string | null;
+                project_ref: string | null;
+                cost_center: string | null;
+                scope_ref: string | null;
+                retrospective: boolean;
+                created_at: string;
+            };
+            delegations: {
+                delegation_id: string;
+                parent_delegation_id: string | null;
+                depth: number;
+                provider_id: string | null;
+                provider_name_stated: string | null;
+                provider_own_id: string | null;
+                external_ref: string | null;
+                provider_job_ref: string | null;
+                scope_ref: string | null;
+                currency: string;
+                quoted_max_minor: number | null;
+                quote_basis: string | null;
+                quote_valid_until: string | null;
+                accepted_amount_minor: number | null;
+                terms_digest: string | null;
+                expected_delivery: string | null;
+                downstream_visibility: "unknown" | "disclosed" | "none";
+                delivery_status: string;
+                retrospective: boolean;
+                created_at: string;
+            }[];
+            delivery_claims: {
+                event_id: string;
+                delegation_id: string;
+                type: "acceptance" | "completion" | "partial_completion" | "cancellation" | "provider_failure" | "terms_update" | "correction";
+                asserted_by: "provider" | "buyer" | "clearing_policy" | "dispute_reviewer" | "clearing_network";
+                assurance: ("contested" | "issuer_signed" | "buyer_recorded" | "network_recorded" | "recipient_viewed" | "link_authenticated_response" | "provider_identity_bound" | "provider_key_signed" | "superseded")[];
+                note: string | null;
+                evidence: {
+                    uri: string;
+                    digest: string | null;
+                    evidence_type: string;
+                }[];
+                supersedes_event_id: string | null;
+                reason: string | null;
+                retrospective: boolean;
+                occurred_at: string;
+                recorded_at: string;
+            }[];
+            financial_events: {
+                record: {
+                    financial_event_id: string;
+                    type: "quote" | "invoice" | "charge" | "payment_reported" | "refund" | "reversal" | "fee" | "credit" | "adjustment" | "fx_rate";
+                    source: string;
+                    source_event_id: string;
+                    provider_id: string | null;
+                    provider_reference: string | null;
+                    amount_minor: number;
+                    currency: string;
+                    event_date: string;
+                    imported_at: string;
+                    provider_status: string | null;
+                    normalized_status: "unknown" | "quoted" | "issued" | "pending" | "reported_paid" | "failed" | "refunded" | "reversed" | "void";
+                    evidence: {
+                        uri: string;
+                        digest: string | null;
+                        evidence_type: string;
+                    } | null;
+                    retrospective: boolean;
+                    payer: "provider" | "buyer" | "other";
+                    liability_owner: string | null;
+                    economic_event_id: string | null;
+                    included_in_event_id: string | null;
+                    reverses_event_id: string | null;
+                    settles_event_id: string | null;
+                    fx: {
+                        base_currency: string;
+                        quote_currency: string;
+                        rate_numerator: number;
+                        rate_denominator: number;
+                    } | null;
+                    reason: string | null;
+                };
+                event_digest: string;
+                attributed_to: string;
+            }[];
+            allocations: {
+                allocation_id: string;
+                financial_event_id: string;
+                version: number;
+                source_event_digest: string;
+                source_amount_minor: number;
+                currency: string;
+                lines: {
+                    target: {
+                        type: "task" | "delegation" | "cost_center" | "unallocated";
+                        id: string | null;
+                    };
+                    amount_minor: number;
+                }[];
+                rounding: {
+                    method: "largest_remainder" | "none";
+                    remainder_units: {
+                        line_index: number;
+                        units: number;
+                    }[];
+                };
+                rule: {
+                    rule_id: string;
+                    version: number;
+                } | null;
+                reason: string;
+                after_close: boolean;
+                created_by: string;
+                created_at: string;
+            }[];
+            rollup: {
+                root_task_id: string;
+                nodes: {
+                    node_id: string;
+                    parent_id: string | null;
+                    direct: Record<string, {
+                        quoted: number;
+                        accepted: number;
+                        invoiced: number;
+                        charged: number;
+                        fees: number;
+                        adjustments: number;
+                        refunded: number;
+                        credits: number;
+                        reported_paid: number;
+                        net_cost: number;
+                        unresolved: number;
+                        downstream_reported: number;
+                        allocated: number;
+                        unallocated: number;
+                    }>;
+                    descendant: Record<string, {
+                        quoted: number;
+                        accepted: number;
+                        invoiced: number;
+                        charged: number;
+                        fees: number;
+                        adjustments: number;
+                        refunded: number;
+                        credits: number;
+                        reported_paid: number;
+                        net_cost: number;
+                        unresolved: number;
+                        downstream_reported: number;
+                        allocated: number;
+                        unallocated: number;
+                    }>;
+                    total: Record<string, {
+                        quoted: number;
+                        accepted: number;
+                        invoiced: number;
+                        charged: number;
+                        fees: number;
+                        adjustments: number;
+                        refunded: number;
+                        credits: number;
+                        reported_paid: number;
+                        net_cost: number;
+                        unresolved: number;
+                        downstream_reported: number;
+                        allocated: number;
+                        unallocated: number;
+                    }>;
+                    event_ids: string[];
+                }[];
+                root_total: Record<string, {
+                    quoted: number;
+                    accepted: number;
+                    invoiced: number;
+                    charged: number;
+                    fees: number;
+                    adjustments: number;
+                    refunded: number;
+                    credits: number;
+                    reported_paid: number;
+                    net_cost: number;
+                    unresolved: number;
+                    downstream_reported: number;
+                    allocated: number;
+                    unallocated: number;
+                }>;
+                excluded_event_ids: {
+                    reversed: string[];
+                    reversals: string[];
+                    fx_rates: string[];
+                };
+            };
+            open_exceptions: {
+                exception_id: string;
+                kind: string;
+                status: "open" | "dismissed" | "resolved";
+                delegation_id: string | null;
+                financial_event_id: string | null;
+                detail: string;
+                created_at: string;
+            }[];
+            receipts: {
+                receipt_id: string;
+                delegation_id: string;
+                revision: number;
+                digest: string;
+            }[];
+            responses: {
+                response_id: string;
+                receipt_id: string;
+                receipt_revision: number;
+                provider_id: string | null;
+                statement: {
+                    document_type: "atcn.subledger.receipt_response";
+                    receipt_id: string;
+                    receipt_digest: string;
+                    receipt_revision: number;
+                    issuer_operator_id: string;
+                    response_type: "acknowledge_view" | "acknowledge_delivery" | "submit_evidence" | "propose_correction" | "signed_attestation";
+                    fields: ("delivery.status" | "delivery.evidence" | "scope.terms_digest" | "financial.amounts" | "financial.status")[];
+                    note: string | null;
+                    evidence: {
+                        uri: string;
+                        digest: string | null;
+                        evidence_type: string;
+                    }[];
+                    corrections: {
+                        field: "delivery.status" | "delivery.evidence" | "scope.terms_digest" | "financial.amounts" | "financial.status";
+                        proposed_value: string;
+                        reason: string;
+                    }[];
+                };
+                statement_digest: string;
+                provider_signature: {
+                    key_id: string;
+                    binding_id: string;
+                    value: string;
+                } | null;
+                assurance: ("contested" | "issuer_signed" | "buyer_recorded" | "network_recorded" | "recipient_viewed" | "link_authenticated_response" | "provider_identity_bound" | "provider_key_signed" | "superseded")[];
+                decision: {
+                    status: "accepted" | "rejected";
+                    reason: string;
+                    decided_by: string;
+                    decided_at: string;
+                } | null;
+                created_at: string;
+            }[];
+            key_bindings: {
+                binding_id: string;
+                provider_id: string;
+                key_id: string;
+                public_key: string;
+                method: "operator_configured" | "domain_challenge";
+                created_by: string;
+                created_at: string;
+                revoked_at: string | null;
+                domain?: string | null | undefined;
+            }[];
+            lineage: {
+                complete: boolean;
+                capture_gaps: {
+                    gap_id: string;
+                    delegation_id: string | null;
+                    kind: string;
+                    detail: string;
+                    reported_at: string;
+                }[];
+                unknown_downstream: string[];
+            };
+            disclosure: {
+                missing: string[];
+                unverified: string[];
+                contested: string[];
+                provider_reported: string[];
+                retrospective: string[];
+            };
+            obligation_links?: {
+                delegation_id: string;
+                obligation_id: string;
+                decision_id: string | null;
+                decision_digest: string | null;
+            }[] | undefined;
+        };
+        signature: {
+            key_id: string;
+            key_version: number;
+            algorithm: "Ed25519";
+            value: string;
+        };
+        operator_signatures?: {
+            key_id: string;
+            algorithm: "Ed25519";
+            value: string;
+            signed_at: string;
+        }[] | undefined;
+    }>;
+    createReceipt(taskId: string, delegationId: string, opts?: Opts): Promise<{
+        receipt: SignedReceipt;
+        digest: string;
+    }>;
+    getReceipt(receiptId: string): Promise<{
+        payload: {
+            document_type: "atcn.subledger.receipt";
+            schema_version: "1.3" | "1.2";
+            receipt_id: string;
+            revision: number;
+            previous_receipt_id: string | null;
+            previous_receipt_digest: string | null;
+            issued_at: string;
+            expires_at: string | null;
+            issuer: {
+                operator_id: string;
+                operator_name: string;
+                signed_by: "atcn-hosted-service" | "atcn-local-runner";
+            };
+            delegation: {
+                delegation_id: string;
+                root_task_id: string;
+                external_ref: string | null;
+                provider_job_ref: string | null;
+                shared_description: string | null;
+                terms_digest: string | null;
+                currency: string;
+                quoted_max_minor: number | null;
+                quote_basis: string | null;
+                accepted_amount_minor: number | null;
+                expected_delivery: string | null;
+                retrospective: boolean;
+                downstream_visibility: "unknown" | "disclosed" | "none";
+            };
+            provider: {
+                provider_id: string | null;
+                name_stated: string | null;
+                provider_own_id: string | null;
+                identity_binding: "key_bound" | "not_bound";
+            };
+            delivery_claims: {
+                type: "acceptance" | "completion" | "partial_completion" | "cancellation" | "provider_failure" | "terms_update" | "correction";
+                retrospective: boolean;
+                occurred_at: string;
+                asserted_by: "provider" | "buyer" | "clearing_policy" | "dispute_reviewer" | "clearing_network";
+                note: string | null;
+                evidence: {
+                    uri: string;
+                    digest: string | null;
+                    evidence_type: string;
+                }[];
+                supersedes_event_id: string | null;
+                reason: string | null;
+                event_id: string;
+                assurance: ("contested" | "issuer_signed" | "buyer_recorded" | "network_recorded" | "recipient_viewed" | "link_authenticated_response" | "provider_identity_bound" | "provider_key_signed" | "superseded")[];
+                recorded_at: string;
+            }[];
+            financial_events: {
+                type: "quote" | "invoice" | "charge" | "payment_reported" | "refund" | "reversal" | "fee" | "credit" | "adjustment" | "fx_rate";
+                currency: string;
+                retrospective: boolean;
+                provider_id: string | null;
+                evidence: {
+                    uri: string;
+                    digest: string | null;
+                    evidence_type: string;
+                } | null;
+                reason: string | null;
+                amount_minor: number;
+                event_date: string;
+                source: string;
+                source_event_id: string;
+                provider_reference: string | null;
+                provider_status: string | null;
+                normalized_status: "unknown" | "quoted" | "issued" | "pending" | "reported_paid" | "failed" | "refunded" | "reversed" | "void";
+                payer: "provider" | "buyer" | "other";
+                included_in_event_id: string | null;
+                reverses_event_id: string | null;
+                settles_event_id: string | null;
+                imported_at: string;
+                financial_event_id: string;
+                allocation_version: number;
+            }[];
+            totals: Record<string, {
+                quoted: number;
+                reported_paid: number;
+                refunded: number;
+                accepted: number;
+                invoiced: number;
+                charged: number;
+                fees: number;
+                adjustments: number;
+                credits: number;
+                net_cost: number;
+                unresolved: number;
+                downstream_reported: number;
+            }>;
+            field_status: Record<"delivery.status" | "delivery.evidence" | "scope.terms_digest" | "financial.amounts" | "financial.status", "contested" | "missing" | "imported" | "buyer_asserted" | "provider_reported">;
+            unverified_fields: ("delivery.status" | "delivery.evidence" | "scope.terms_digest" | "financial.amounts" | "financial.status")[];
+            corrections: {
+                response_id: string;
+                receipt_revision: number;
+                fields: ("delivery.status" | "delivery.evidence" | "scope.terms_digest" | "financial.amounts" | "financial.status")[];
+                decision: "accepted" | "rejected" | "open";
+            }[];
+            lineage: {
+                complete: boolean;
+                capture_gaps: {
+                    detail: string;
+                    reported_at: string;
+                    gap_id: string;
+                    kind: string;
+                }[];
+            };
+        };
+        signature: {
+            key_id: string;
+            key_version: number;
+            algorithm: "Ed25519";
+            value: string;
+        };
+        operator_signatures?: {
+            key_id: string;
+            algorithm: "Ed25519";
+            value: string;
+            signed_at: string;
+        }[] | undefined;
+    }>;
+    markReceiptDelivered(receiptId: string, channel: string, reference?: string | null, opts?: Opts): Promise<Json>;
+    createReceiptShare(receiptId: string, allowedActions?: string[], ttlHours?: number, opts?: Opts): Promise<{
+        share_id: string;
+        token: string;
+        url: string;
+        expires_at: string;
+        allowed_actions: string[];
+    }>;
+    revokeReceiptShare(shareId: string, opts?: Opts): Promise<Json>;
+    listResponses(receiptId: string): Promise<{
+        items: Json[];
+    }>;
+    /** Accepting appends the corrected records. A correction of financial fields needs the corrected events in `financialEvents`. */
+    decideCorrection(responseId: string, status: "accepted" | "rejected", reason: string, opts?: Opts & {
+        financialEvents?: FinancialEventInput[];
+    }): Promise<Json>;
+    createProvider(input: z.input<typeof ProviderInputSchema>, opts?: Opts): Promise<Json>;
+    bindProviderKey(providerId: string, keyId: string, publicKey: string, opts?: Opts): Promise<Json>;
+    /** Admin only. The provider publishes the returned txt_value at txt_name; then call verifyDomainChallenge. */
+    startDomainChallenge(providerId: string, input: {
+        key_id: string;
+        public_key: string;
+        domain?: string;
+    }, opts?: Opts): Promise<Json>;
+    verifyDomainChallenge(challengeId: string, opts?: Opts): Promise<Json>;
+    /** Admin only. Registers the public half of a key the operator holds; the private key stays with the operator. */
+    registerOperatorKey(keyId: string, publicKey: string, opts?: Opts): Promise<Json>;
+    revokeOperatorKey(keyId: string, reason: string, opts?: Opts): Promise<Json>;
+    operatorKeys(operatorId: string): Promise<{
+        items: OperatorKeyRecord[];
+    }>;
+    /** Signs the document's payload locally with the operator's private key and records the countersignature. */
+    countersign(signed: SignedClosure | SignedReceipt, keyId: string, privateKey: string, opts?: Opts): Promise<{
+        key_id: string;
+        algorithm: "Ed25519";
+        value: string;
+        signed_at: string;
+    }>;
+    productMetrics(): Promise<Json>;
+    serviceKeys(): Promise<{
+        items: Json[];
+    }>;
+}
+/** Provider-side access through a receipt link: no account, no API key, only the link's scope. */
+export declare class ReceiptLinkClient {
+    private readonly http;
+    constructor(options: {
+        baseUrl: string;
+        shareToken: string;
+        fetch?: typeof fetch;
+        retries?: number;
+    });
+    current(): Promise<{
+        receipt: SignedReceipt;
+        digest: string;
+        revisions: Json[];
+        allowed_actions: string[];
+        expires_at: string;
+        responses: Json[];
+        notice: string;
+    }>;
+    verification(receiptId: string): Promise<Json>;
+    respond(receipt: {
+        receipt_id: string;
+        digest: string;
+        revision: number;
+    }, response: {
+        response_type: ResponseType;
+        fields?: AttestableField[];
+        note?: string | null;
+        evidence?: EvidenceRef[];
+        corrections?: Correction[];
+    }, signing?: {
+        bindingId: string;
+        keyId: string;
+        privateKey: string;
+        issuerOperatorId: string;
+    }, opts?: Opts): Promise<Json>;
+}
+export interface CaptureOperation {
+    id: string;
+    method: "POST";
+    path: string;
+    body: unknown;
+    idempotencyKey: string;
+    enqueued_at: string;
+    attempts: number;
+    last_error: string | null;
+}
+export interface CaptureQueueOptions {
+    /** Documented maximum. When full, new operations are dropped (never the oldest) and counted. Default 1000. */
+    maxSize?: number;
+    /** Attempts before an operation moves to the failed list for export and replay. Default 5. */
+    maxAttempts?: number;
+}
+export interface FlushResult {
+    sent: number;
+    failed: number;
+    remaining: number;
+}
+/**
+ * Bounded local capture queue (PRD §15, acceptance 20-21). enqueue() and flush() never throw, so a capture
+ * outage never stops the orchestrator's work. Each operation keeps one idempotency key for its lifetime, so
+ * replays and retries create exactly one record. Drops and permanent failures are counted and can be
+ * reported as capture gaps, so the chain is never silently shown as complete.
+ *
+ * Overflow policy: reject the newest operation and increment `dropped`. Older operations keep their order,
+ * because later events (completions, charges) depend on earlier ones (tasks, delegations).
+ */
+export declare class CaptureQueue {
+    private readonly client;
+    readonly maxSize: number;
+    readonly maxAttempts: number;
+    private pending;
+    private failed;
+    private droppedCount;
+    private sequence;
+    constructor(client: SubledgerClient, options?: CaptureQueueOptions);
+    get dropped(): number;
+    get size(): number;
+    /** Queues one mutation. Returns false (and counts a drop) when the queue is full; never throws. */
+    enqueue(path: string, body: unknown, idempotencyKey?: string): boolean;
+    task(input: z.input<typeof TaskInputSchema>): boolean;
+    delegation(taskRef: string, input: z.input<typeof DelegationInputSchema>): boolean;
+    delegationEvent(delegationRef: string, input: z.input<typeof DelegationEventInputSchema>, idempotencyKey?: string): boolean;
+    financialEvent(input: FinancialEventInput): boolean;
+    /**
+     * Sends queued operations in order. A retryable failure (network, 5xx, 429) stops the flush and keeps the
+     * operation for the next flush; a non-retryable rejection moves it to the failed list. Never throws.
+     */
+    flush(): Promise<FlushResult>;
+    failedOperations(): CaptureOperation[];
+    /** Failed operations as JSON lines, for replay after the cause is fixed. */
+    exportFailed(): string;
+    /** Puts exported operations back in the queue with their original idempotency keys. */
+    replay(jsonLines: string): number;
+    /** Reports drops and permanent failures for a task as capture gaps (marks its lineage incomplete). Never throws. */
+    reportGaps(taskRef: string): Promise<boolean>;
+}
+export {};