@atcn/sdk 1.3.0

package/dist/subledger.js

@@ -0,0 +1,300 @@
+import { buildResponseStatement, countersignPayload, signStatement, } from "@atcn/subledger";
+import { sha256Digest } from "@atcn/schema";
+import { AtcnApiError, AtcnClient } from "./client.js";
+/** Caller-supplied references address records before their server IDs are known: ext("job-42"). */
+export const ext = (externalRef) => `ext:${externalRef}`;
+/** Idempotency key derived from the caller's stable references; long references are hashed to fit 8-200 chars. */
+export function stableKey(kind, ...parts) {
+    const key = `sl:${kind}:${parts.join(":")}`;
+    return key.length <= 200 ? key : `sl:${kind}:${sha256Digest(parts.join(":"))}`;
+}
+/**
+ * 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 class SubledgerClient {
+    http;
+    constructor(options) {
+        this.http = options instanceof AtcnClient ? options : new AtcnClient(options);
+    }
+    createTask(input, opts = {}) {
+        return this.http.request("POST", "/v1/tasks", input, { idempotencyKey: opts.idempotencyKey ?? stableKey("task", input.external_ref) });
+    }
+    getTask(taskId) {
+        return this.http.request("GET", `/v1/tasks/${encodeURIComponent(taskId)}`);
+    }
+    listTasks(query = {}) {
+        return this.http.request("GET", "/v1/tasks", undefined, { query });
+    }
+    /** Admin only. Principals are "user:<id>" or "api_key:<id>". */
+    getTaskAccess(taskId) {
+        return this.http.request("GET", `/v1/tasks/${encodeURIComponent(taskId)}/access`);
+    }
+    updateTaskAccess(taskId, input, opts = {}) {
+        return this.http.request("POST", `/v1/tasks/${encodeURIComponent(taskId)}/access`, input, opts);
+    }
+    createDelegation(taskId, input, opts = {}) {
+        const key = opts.idempotencyKey ?? (input.external_ref ? stableKey("delegation", input.external_ref) : undefined);
+        return this.http.request("POST", `/v1/tasks/${encodeURIComponent(taskId)}/delegations`, input, { idempotencyKey: key });
+    }
+    assignProvider(delegationId, providerId, opts = {}) {
+        return this.http.request("POST", `/v1/delegations/${encodeURIComponent(delegationId)}/provider`, { provider_id: providerId }, opts);
+    }
+    appendDelegationEvent(delegationId, input, opts = {}) {
+        return this.http.request("POST", `/v1/delegations/${encodeURIComponent(delegationId)}/events`, input, opts);
+    }
+    recordFinancialEvent(input, opts = {}) {
+        return this.http.request("POST", "/v1/financial-events", input, { idempotencyKey: opts.idempotencyKey ?? stableKey("financial", input.source, input.source_event_id) });
+    }
+    importCsv(csv, opts = {}) {
+        return this.http.request("POST", "/v1/financial-events/import", undefined, {
+            idempotencyKey: opts.idempotencyKey,
+            textBody: { contentType: "text/csv", text: csv },
+        });
+    }
+    listFinancialEvents(query = {}) {
+        return this.http.request("GET", "/v1/financial-events", undefined, { query });
+    }
+    allocate(financialEventId, input, opts = {}) {
+        return this.http.request("POST", `/v1/financial-events/${financialEventId}/allocations`, input, opts);
+    }
+    createAllocationRule(input, opts = {}) {
+        return this.http.request("POST", "/v1/allocation-rules", input, opts);
+    }
+    listMatches(status) {
+        return this.http.request("GET", "/v1/matches", undefined, { query: { status } });
+    }
+    confirmMatch(matchId, node, opts = {}) {
+        return this.http.request("POST", `/v1/matches/${matchId}/confirm`, node, opts);
+    }
+    financialSummary(taskId, query = {}) {
+        return this.http.request("GET", `/v1/tasks/${encodeURIComponent(taskId)}/financial-summary`, undefined, { query });
+    }
+    listExceptions(query = {}) {
+        return this.http.request("GET", "/v1/subledger-exceptions", undefined, { query });
+    }
+    resolveException(exceptionId, input, opts = {}) {
+        return this.http.request("POST", `/v1/subledger-exceptions/${exceptionId}/resolve`, input, opts);
+    }
+    reportCaptureGap(taskId, gap, opts = {}) {
+        return this.http.request("POST", `/v1/tasks/${encodeURIComponent(taskId)}/capture-gaps`, gap, opts);
+    }
+    closeTask(taskId, opts = {}) {
+        return this.http.request("POST", `/v1/tasks/${taskId}/close`, {}, opts);
+    }
+    getClosure(taskId, version) {
+        return this.http.request("GET", `/v1/tasks/${taskId}/closure`, undefined, { query: { version } });
+    }
+    createReceipt(taskId, delegationId, opts = {}) {
+        return this.http.request("POST", `/v1/tasks/${taskId}/receipts`, { delegation_id: delegationId }, opts);
+    }
+    getReceipt(receiptId) {
+        return this.http.request("GET", `/v1/receipts/${receiptId}`);
+    }
+    markReceiptDelivered(receiptId, channel, reference = null, opts = {}) {
+        return this.http.request("POST", `/v1/receipts/${receiptId}/delivered`, { channel, reference }, opts);
+    }
+    createReceiptShare(receiptId, allowedActions = ["view"], ttlHours, opts = {}) {
+        return this.http.request("POST", "/v1/receipt-shares", { receipt_id: receiptId, allowed_actions: allowedActions, ttl_hours: ttlHours }, opts);
+    }
+    revokeReceiptShare(shareId, opts = {}) {
+        return this.http.request("DELETE", `/v1/receipt-shares/${shareId}`, undefined, opts);
+    }
+    listResponses(receiptId) {
+        return this.http.request("GET", `/v1/receipts/${receiptId}/responses`);
+    }
+    /** Accepting appends the corrected records. A correction of financial fields needs the corrected events in `financialEvents`. */
+    decideCorrection(responseId, status, reason, opts = {}) {
+        const body = { status, reason, financial_events: opts.financialEvents ?? [] };
+        return this.http.request("POST", `/v1/receipt-responses/${responseId}/decision`, body, { idempotencyKey: opts.idempotencyKey });
+    }
+    createProvider(input, opts = {}) {
+        return this.http.request("POST", "/v1/provider-identities", input, { idempotencyKey: opts.idempotencyKey ?? stableKey("provider", input.name) });
+    }
+    bindProviderKey(providerId, keyId, publicKey, opts = {}) {
+        return this.http.request("POST", `/v1/provider-identities/${providerId}/key-bindings`, { key_id: keyId, public_key: publicKey }, opts);
+    }
+    /** Admin only. The provider publishes the returned txt_value at txt_name; then call verifyDomainChallenge. */
+    startDomainChallenge(providerId, input, opts = {}) {
+        return this.http.request("POST", `/v1/provider-identities/${providerId}/domain-challenges`, input, opts);
+    }
+    verifyDomainChallenge(challengeId, opts = {}) {
+        return this.http.request("POST", `/v1/domain-challenges/${challengeId}/verify`, {}, opts);
+    }
+    /** Admin only. Registers the public half of a key the operator holds; the private key stays with the operator. */
+    registerOperatorKey(keyId, publicKey, opts = {}) {
+        return this.http.request("POST", "/v1/operator-keys", { key_id: keyId, public_key: publicKey }, opts);
+    }
+    revokeOperatorKey(keyId, reason, opts = {}) {
+        return this.http.request("POST", `/v1/operator-keys/${encodeURIComponent(keyId)}/revoke`, { reason }, opts);
+    }
+    operatorKeys(operatorId) {
+        return this.http.request("GET", `/v1/operators/${operatorId}/keys`);
+    }
+    /** Signs the document's payload locally with the operator's private key and records the countersignature. */
+    countersign(signed, keyId, privateKey, opts = {}) {
+        const signature = countersignPayload(signed.payload, privateKey);
+        const path = "closure_id" in signed.payload ? `closures/${signed.payload.closure_id}` : `receipts/${signed.payload.receipt_id}`;
+        return this.http.request("POST", `/v1/${path}/countersign`, { key_id: keyId, signature }, opts);
+    }
+    productMetrics() {
+        return this.http.request("GET", "/v1/metrics/product");
+    }
+    serviceKeys() {
+        return this.http.request("GET", "/v1/service/keys");
+    }
+}
+/** Provider-side access through a receipt link: no account, no API key, only the link's scope. */
+export class ReceiptLinkClient {
+    http;
+    constructor(options) {
+        const shareToken = options.shareToken;
+        const baseFetch = options.fetch ?? fetch;
+        // The share token replaces the API key: strip the Authorization header the base client adds.
+        const linkFetch = (input, init) => {
+            const headers = new Headers(init?.headers);
+            headers.delete("authorization");
+            headers.set("x-atcn-share-token", shareToken);
+            return baseFetch(input, { ...init, headers });
+        };
+        this.http = new AtcnClient({ baseUrl: options.baseUrl, apiKey: "", fetch: linkFetch, retries: options.retries });
+    }
+    current() {
+        return this.http.request("GET", "/v1/receipt-shares/current");
+    }
+    verification(receiptId) {
+        return this.http.request("GET", `/v1/receipts/${receiptId}/verification`);
+    }
+    respond(receipt, response, signing, opts = {}) {
+        let provider_signature = null;
+        if (signing) {
+            const statement = buildResponseStatement({
+                receipt: { receipt_id: receipt.receipt_id, digest: receipt.digest, revision: receipt.revision, issuer_operator_id: signing.issuerOperatorId },
+                response_type: response.response_type,
+                fields: response.fields ?? [],
+                note: response.note ?? null,
+                evidence: response.evidence ?? [],
+                corrections: response.corrections ?? [],
+            });
+            provider_signature = { binding_id: signing.bindingId, key_id: signing.keyId, value: signStatement(statement, signing.privateKey) };
+        }
+        return this.http.request("POST", `/v1/receipts/${receipt.receipt_id}/responses`, { receipt_digest: receipt.digest, receipt_revision: receipt.revision, ...response, provider_signature }, opts);
+    }
+}
+/**
+ * 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 class CaptureQueue {
+    client;
+    maxSize;
+    maxAttempts;
+    pending = [];
+    failed = [];
+    droppedCount = 0;
+    sequence = 0;
+    constructor(client, options = {}) {
+        this.client = client;
+        this.maxSize = options.maxSize ?? 1000;
+        this.maxAttempts = options.maxAttempts ?? 5;
+    }
+    get dropped() {
+        return this.droppedCount;
+    }
+    get size() {
+        return this.pending.length;
+    }
+    /** Queues one mutation. Returns false (and counts a drop) when the queue is full; never throws. */
+    enqueue(path, body, idempotencyKey) {
+        if (this.pending.length >= this.maxSize) {
+            this.droppedCount += 1;
+            return false;
+        }
+        this.sequence += 1;
+        this.pending.push({
+            id: `op_${Date.now()}_${this.sequence}`,
+            method: "POST",
+            path,
+            body,
+            idempotencyKey: idempotencyKey ?? stableKey("capture", crypto.randomUUID()),
+            enqueued_at: new Date().toISOString(),
+            attempts: 0,
+            last_error: null,
+        });
+        return true;
+    }
+    task(input) {
+        return this.enqueue("/v1/tasks", input, stableKey("task", input.external_ref));
+    }
+    delegation(taskRef, input) {
+        return this.enqueue(`/v1/tasks/${encodeURIComponent(taskRef)}/delegations`, input, input.external_ref ? stableKey("delegation", input.external_ref) : undefined);
+    }
+    delegationEvent(delegationRef, input, idempotencyKey) {
+        return this.enqueue(`/v1/delegations/${encodeURIComponent(delegationRef)}/events`, input, idempotencyKey);
+    }
+    financialEvent(input) {
+        return this.enqueue("/v1/financial-events", input, stableKey("financial", input.source, input.source_event_id));
+    }
+    /**
+     * 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.
+     */
+    async flush() {
+        let sent = 0;
+        let failed = 0;
+        while (this.pending.length > 0) {
+            const op = this.pending[0];
+            op.attempts += 1;
+            try {
+                await this.client.http.request(op.method, op.path, op.body, { idempotencyKey: op.idempotencyKey });
+                this.pending.shift();
+                sent += 1;
+            }
+            catch (error) {
+                op.last_error = error instanceof Error ? error.message : String(error);
+                const retryable = !(error instanceof AtcnApiError) || error.retryable;
+                if (retryable && op.attempts < this.maxAttempts)
+                    break;
+                this.failed.push(this.pending.shift());
+                failed += 1;
+            }
+        }
+        return { sent, failed, remaining: this.pending.length };
+    }
+    failedOperations() {
+        return [...this.failed];
+    }
+    /** Failed operations as JSON lines, for replay after the cause is fixed. */
+    exportFailed() {
+        return this.failed.map((op) => JSON.stringify(op)).join("\n");
+    }
+    /** Puts exported operations back in the queue with their original idempotency keys. */
+    replay(jsonLines) {
+        const replayed = new Set();
+        for (const line of jsonLines.split("\n").filter((l) => l.trim() !== "")) {
+            const op = JSON.parse(line);
+            if (this.enqueue(op.path, op.body, op.idempotencyKey))
+                replayed.add(op.idempotencyKey);
+        }
+        this.failed = this.failed.filter((f) => !replayed.has(f.idempotencyKey));
+        return replayed.size;
+    }
+    /** Reports drops and permanent failures for a task as capture gaps (marks its lineage incomplete). Never throws. */
+    async reportGaps(taskRef) {
+        if (this.droppedCount === 0 && this.failed.length === 0)
+            return true;
+        const detail = `${this.droppedCount} capture operation(s) dropped by queue overflow; ${this.failed.length} failed permanently`;
+        try {
+            await this.client.reportCaptureGap(taskRef, { kind: this.droppedCount > 0 ? "queue_overflow" : "capture_failed", detail });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@atcn/sdk",
+  "version": "1.3.0",
+  "description": "TypeScript SDK for ATCN: sign events, build terms and evidence envelopes, call the API, verify webhooks, closures, and closure packages",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fadnisnikhil/atcn.git",
+    "directory": "packages/sdk-ts"
+  },
+  "homepage": "https://github.com/fadnisnikhil/atcn/tree/main/packages/sdk-ts#readme",
+  "bugs": {
+    "url": "https://github.com/fadnisnikhil/atcn/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "atcn": "bin/atcn.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "atcn-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@atcn/core": "1.3.0",
+    "@atcn/schema": "1.3.0",
+    "@atcn/subledger": "1.3.0",
+    "@atcn/usage": "1.3.0",
+    "zod": "^4.1.0"
+  }
+}