@pacspace-io/sdk 0.1.0 → 0.2.1

package/dist/resources/balance.js

@@ -2,6 +2,25 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BalanceResource = void 0;
 const polling_1 = require("../utils/polling");
+const submission_1 = require("./submission");
+const toRecordStatus = (status) => {
+    const normalized = String(status ?? '').toUpperCase();
+    if (normalized === 'PROCESSING')
+        return 'PROCESSING';
+    if (normalized === 'VERIFIED')
+        return 'VERIFIED';
+    if (normalized === 'FAILED')
+        return 'FAILED';
+    return 'QUEUED';
+};
+const toCheckpointType = (value) => {
+    return String(value) === 'recordId' ? 'recordId' : 'proofRoot';
+};
+const toApiCheckpointType = (value) => {
+    if (!value)
+        return undefined;
+    return value;
+};
 /**
  * PacSpace Balance API resource.
  *
@@ -15,8 +34,12 @@ const polling_1 = require("../utils/polling");
  */
 class BalanceResource {
     /** @internal */
-    constructor(client) {
+    constructor(client, submissionOptions) {
         this.client = client;
+        this.submission = new submission_1.SubmissionCoordinator({
+            emitBatch: (deltas) => this.emitBatch(deltas),
+            options: submissionOptions,
+        });
     }
     // -------------------------------------------------------------------------
     // Emit
@@ -51,7 +74,8 @@ class BalanceResource {
             body.referenceId = referenceId;
         if (metadata !== undefined)
             body.metadata = metadata;
-        return this.client.post('/api/v1/balance/delta', body, requestOptions);
+        const response = await this.client.post('/api/v1/balance/delta', body, requestOptions);
+        return this.normalizeEmitResponse(response);
     }
     /**
      * Record a delta and wait for it to be verified.
@@ -82,11 +106,139 @@ class BalanceResource {
             signal,
         });
         // If already terminal, return immediately
-        if (['ANCHORED', 'VERIFIED', 'FAILED'].includes(initial.status)) {
+        if (['VERIFIED', 'FAILED'].includes(initial.status)) {
             return initial;
         }
-        // Poll for terminal status using the anchor endpoint from writes controller
-        return (0, polling_1.pollUntilTerminal)(() => this.client.get(`/api/v1/writes/${initial.anchorId}`, { signal }), { timeout, pollInterval, signal });
+        // Poll for terminal status using the balance delta endpoint, then merge
+        // the latest status with the original emit metadata.
+        const terminalStatus = await (0, polling_1.pollUntilTerminal)(() => this.deltaStatus(initial.recordId, { signal }), { timeout, pollInterval, signal });
+        return this.mergeEmitWithStatus(initial, terminalStatus);
+    }
+    /**
+     * Check the status of a previously emitted delta.
+     *
+     * @param recordId - The record ID returned from emit.
+     * @param options - Request overrides.
+     * @returns Delta status with receipt and transaction details.
+     *
+     * @example
+     * ```typescript
+     * const status = await pac.balance.deltaStatus('rec_abc123');
+     * console.log(status.status); // 'QUEUED', 'PROCESSING', etc.
+     * ```
+     */
+    async deltaStatus(recordId, options) {
+        const response = await this.client.get(`/api/v1/balance/delta/${encodeURIComponent(recordId)}`, options);
+        return this.normalizeDeltaStatusResponse(response);
+    }
+    /**
+     * Alias for `deltaStatus()` with lifecycle-oriented naming.
+     */
+    async getRecordStatus(recordId, options) {
+        return this.deltaStatus(recordId, options);
+    }
+    /**
+     * Poll record lifecycle until it reaches a terminal status.
+     *
+     * Terminal statuses are `VERIFIED` and `FAILED`.
+     */
+    async waitForVerified(recordId, options) {
+        const { timeout = 60000, pollInterval = 2000, signal, ...requestOptions } = options ?? {};
+        return (0, polling_1.pollUntilTerminal)(() => this.getRecordStatus(recordId, {
+            ...requestOptions,
+            signal,
+        }), { timeout, pollInterval, signal });
+    }
+    /**
+     * Retrieve tenant usage counters and remaining allotment.
+     */
+    async usage(options) {
+        return this.client.get('/api/v1/balance/usage', options);
+    }
+    /**
+     * Detect missing per-customer sequence ranges.
+     *
+     * Use this to identify gaps and re-emit missing deltas safely.
+     */
+    async gaps(customerId, options) {
+        const { fromSequence, toSequence, limit, ...requestOptions } = options ?? {};
+        const params = new URLSearchParams();
+        if (fromSequence !== undefined)
+            params.set('fromSequence', fromSequence);
+        if (toSequence !== undefined)
+            params.set('toSequence', toSequence);
+        if (limit !== undefined)
+            params.set('limit', String(limit));
+        const query = params.toString();
+        const path = `/api/v1/balance/gaps/${encodeURIComponent(customerId)}${query ? `?${query}` : ''}`;
+        const response = await this.client.get(path, requestOptions);
+        return this.normalizeSequenceGapsResponse(response);
+    }
+    /**
+     * Record multiple deltas in a single batch request.
+     *
+     * Ideal for end-of-day reconciliation or importing historical data.
+     * Up to 100 deltas per batch.
+     *
+     * @param deltas - Array of deltas to record.
+     * @param options - Request overrides.
+     * @returns Per-delta results with totals.
+     *
+     * @example
+     * ```typescript
+     * const result = await pac.balance.emitBatch([
+     *   { customerId: 'cust_123', delta: -100, reason: 'usage' },
+     *   { customerId: 'cust_456', delta: -200, reason: 'usage' },
+     * ]);
+     * console.log(result.totalQueued); // 2
+     * ```
+     */
+    async emitBatch(deltas, options) {
+        const { ...requestOptions } = options ?? {};
+        const response = await this.client.post('/api/v1/balance/delta/batch', { deltas }, requestOptions);
+        return this.normalizeBulkEmitResponse(response);
+    }
+    /**
+     * Queue one tenant-produced summary for SDK-managed submission.
+     */
+    queueSummary(summary) {
+        return this.submission.queueSummary(summary);
+    }
+    /**
+     * Queue multiple tenant-produced summaries.
+     */
+    queueSummaries(summaries) {
+        return this.submission.queueSummaries(summaries);
+    }
+    /**
+     * Flush queued summaries immediately.
+     */
+    async flushSummaries(options) {
+        return this.submission.flushSummaries(options);
+    }
+    /**
+     * Start periodic summary submission scheduling.
+     */
+    startSummaryScheduler() {
+        this.submission.start();
+    }
+    /**
+     * Stop periodic summary submission scheduling.
+     */
+    stopSummaryScheduler() {
+        this.submission.stop();
+    }
+    /**
+     * Get queue/scheduler state for summary submission automation.
+     */
+    getSummaryQueueState() {
+        return this.submission.getQueueState();
+    }
+    /**
+     * Stop scheduler and flush queued summaries (best for graceful shutdown).
+     */
+    async shutdownSummaryScheduler() {
+        await this.submission.shutdown();
     }
     // -------------------------------------------------------------------------
     // Derive
@@ -113,7 +265,7 @@ class BalanceResource {
      * ```
      */
     async derive(customerId, options) {
-        const { startingBalance, startingCheckpoint, startingCheckpointType, ...requestOptions } = options ?? {};
+        const { startingBalance, startingCheckpoint, startingCheckpointType, limit, offset, ...requestOptions } = options ?? {};
         // Build query string
         const params = new URLSearchParams();
         if (startingBalance !== undefined) {
@@ -122,12 +274,20 @@ class BalanceResource {
         if (startingCheckpoint !== undefined) {
             params.set('startingCheckpoint', startingCheckpoint);
         }
-        if (startingCheckpointType !== undefined) {
-            params.set('startingCheckpointType', startingCheckpointType);
+        const apiCheckpointType = toApiCheckpointType(startingCheckpointType);
+        if (apiCheckpointType !== undefined) {
+            params.set('startingCheckpointType', apiCheckpointType);
+        }
+        if (limit !== undefined) {
+            params.set('limit', String(limit));
+        }
+        if (offset !== undefined) {
+            params.set('offset', String(offset));
         }
         const query = params.toString();
         const path = `/api/v1/balance/derive/${encodeURIComponent(customerId)}${query ? `?${query}` : ''}`;
-        return this.client.get(path, requestOptions);
+        const response = await this.client.get(path, requestOptions);
+        return this.normalizeDeriveResponse(response);
     }
     // -------------------------------------------------------------------------
     // Compare
@@ -167,10 +327,12 @@ class BalanceResource {
         if (startingCheckpoint !== undefined) {
             body.startingCheckpoint = startingCheckpoint;
         }
-        if (startingCheckpointType !== undefined) {
-            body.startingCheckpointType = startingCheckpointType;
+        const apiCheckpointType = toApiCheckpointType(startingCheckpointType);
+        if (apiCheckpointType !== undefined) {
+            body.startingCheckpointType = apiCheckpointType;
         }
-        return this.client.post('/api/v1/balance/compare', body, requestOptions);
+        const response = await this.client.post('/api/v1/balance/compare', body, requestOptions);
+        return this.normalizeCompareResponse(response);
     }
     // -------------------------------------------------------------------------
     // Receipt
@@ -178,22 +340,59 @@ class BalanceResource {
     /**
      * Generate a verifiable receipt for a customer.
      *
-     * Returns a human-readable receipt containing all verified deltas
-     * and cryptographic proof data that any party can independently verify.
+     * When `options.period` is provided, returns a period-specific receipt (proof root,
+     * verifyUrl, verificationReference) suitable for sharing on invoices. When
+     * omitted, returns the full record receipt with all verified deltas.
      *
      * @param customerId - The customer account to generate a receipt for.
-     * @param options - Request overrides.
-     * @returns Receipt with verification data.
+     * @param options - Optional period (YYYY-MM) and request overrides.
+     * @returns Receipt with verification data; shape depends on whether period is set.
      *
      * @example
      * ```typescript
-     * const receipt = await pac.balance.receipt('cust_123');
-     * console.log(receipt.finalBalance);
-     * console.log(receipt.verification.itemHashes);
+     * // Period-specific receipt (shareable proof for invoices)
+     * const receipt = await pac.balance.receipt('cust_123', { period: '2026-02' });
+     * console.log(receipt.proofRoot);   // Include on invoice
+     * console.log(receipt.verifyUrl);   // Share with counterparty
+     *
+     * // Full record receipt
+     * const full = await pac.balance.receipt('cust_123');
+     * console.log(full.finalBalance);
      * ```
      */
     async receipt(customerId, options) {
-        return this.client.get(`/api/v1/balance/receipt/${encodeURIComponent(customerId)}`, options);
+        const opts = options ?? {};
+        const hasScopedReceipt = opts.period !== undefined ||
+            opts.timePreset !== undefined ||
+            opts.startDate !== undefined ||
+            opts.endDate !== undefined;
+        if (hasScopedReceipt) {
+            return this.receiptForPeriod(customerId, opts);
+        }
+        const { period: _period, timePreset: _timePreset, startDate: _startDate, endDate: _endDate, ...requestOptions } = opts;
+        const hasOverrides = Object.keys(requestOptions).length > 0;
+        const response = await this.client.get(`/api/v1/balance/receipt/${encodeURIComponent(customerId)}`, hasOverrides ? requestOptions : undefined);
+        return this.normalizeReceiptResponse(response);
+    }
+    /**
+     * @internal
+     * Generate a period-specific receipt (proof root, verifyUrl). Used by receipt().
+     */
+    async receiptForPeriod(customerId, options) {
+        const { period, timePreset, startDate, endDate, ...requestOptions } = options ?? {};
+        const params = new URLSearchParams();
+        if (period !== undefined)
+            params.set('period', period);
+        if (timePreset !== undefined)
+            params.set('timePreset', timePreset);
+        if (startDate !== undefined)
+            params.set('startDate', startDate);
+        if (endDate !== undefined)
+            params.set('endDate', endDate);
+        const query = params.toString();
+        const path = `/api/v1/balance/invoice-proof/${encodeURIComponent(customerId)}${query ? `?${query}` : ''}`;
+        const response = await this.client.get(path, requestOptions);
+        return this.normalizeInvoiceProofResponse(response);
     }
     // -------------------------------------------------------------------------
     // Checkpoint
@@ -201,30 +400,576 @@ class BalanceResource {
     /**
      * Commit a period-end checkpoint.
      *
-     * Computes a Merkle root over all verified deltas in the billing window
-     * and anchors it on-chain. The checkpoint hash can be included in invoices
-     * for instant counterparty verification.
+     * Computes a proof root over all verified deltas in the billing window
+     * and records it on the public verification layer. The proof root can be
+     * included in invoices for instant counterparty verification.
      *
      * @param customerId - Customer to checkpoint (omit for all customers).
      * @param options - Period (YYYY-MM) and request overrides.
-     * @returns Checkpoint details with Merkle root and status.
+     * @returns Checkpoint details with proof root and status.
      *
      * @example
      * ```typescript
      * const checkpoint = await pac.balance.checkpoint('cust_123', {
      *   period: '2026-02',
      * });
-     * console.log(checkpoint.merkleRoot); // Include in your invoice
+     * console.log(checkpoint.proofRoot); // Include in your invoice
      * ```
      */
     async checkpoint(customerId, options) {
-        const { period, ...requestOptions } = options ?? {};
+        const { period, timePreset, startDate, endDate, mode, fingerprints, ...requestOptions } = options ?? {};
         const body = {};
         if (customerId !== undefined)
             body.customerId = customerId;
         if (period !== undefined)
             body.period = period;
-        return this.client.post('/api/v1/balance/checkpoint', body, requestOptions);
+        if (timePreset !== undefined)
+            body.timePreset = timePreset;
+        if (startDate !== undefined)
+            body.startDate = startDate;
+        if (endDate !== undefined)
+            body.endDate = endDate;
+        if (mode !== undefined)
+            body.mode = mode;
+        if (fingerprints !== undefined)
+            body.fingerprints = fingerprints;
+        const response = await this.client.post('/api/v1/balance/checkpoint', body, requestOptions);
+        return this.normalizeCheckpointResponse(response);
+    }
+    // -------------------------------------------------------------------------
+    // List Checkpoints
+    // -------------------------------------------------------------------------
+    /**
+     * List committed checkpoints for your tenant.
+     *
+     * Returns a paginated list of checkpoints, optionally filtered by
+     * customer ID and/or billing period.
+     *
+     * @param options - Filter and pagination options.
+     * @returns Paginated list of checkpoints.
+     *
+     * @example
+     * ```typescript
+     * const { checkpoints } = await pac.balance.listCheckpoints({
+     *   period: '2026-02',
+     *   limit: 10,
+     * });
+     * ```
+     */
+    async listCheckpoints(options) {
+        const { customerId, period, timePreset, startDate, endDate, limit, offset, ...requestOptions } = options ?? {};
+        const params = new URLSearchParams();
+        if (customerId !== undefined)
+            params.set('customerId', customerId);
+        if (period !== undefined)
+            params.set('period', period);
+        if (timePreset !== undefined)
+            params.set('timePreset', timePreset);
+        if (startDate !== undefined)
+            params.set('startDate', startDate);
+        if (endDate !== undefined)
+            params.set('endDate', endDate);
+        if (limit !== undefined)
+            params.set('limit', String(limit));
+        if (offset !== undefined)
+            params.set('offset', String(offset));
+        const query = params.toString();
+        const path = `/api/v1/balance/checkpoints${query ? `?${query}` : ''}`;
+        const response = await this.client.get(path, requestOptions);
+        return this.normalizeListCheckpointsResponse(response);
+    }
+    // -------------------------------------------------------------------------
+    // Webhook Deliveries
+    // -------------------------------------------------------------------------
+    /**
+     * List webhook delivery history.
+     *
+     * @param options - Filter and pagination options.
+     * @returns Paginated list of webhook deliveries.
+     *
+     * @example
+     * ```typescript
+     * const { deliveries } = await pac.balance.listWebhookDeliveries({
+     *   status: 'failed',
+     *   limit: 10,
+     * });
+     * ```
+     */
+    async listWebhookDeliveries(options) {
+        const { status, limit, offset, ...requestOptions } = options ?? {};
+        const params = new URLSearchParams();
+        if (status !== undefined)
+            params.set('status', status);
+        if (limit !== undefined)
+            params.set('limit', String(limit));
+        if (offset !== undefined)
+            params.set('offset', String(offset));
+        const query = params.toString();
+        const path = `/api/v1/balance/webhooks${query ? `?${query}` : ''}`;
+        return this.client.get(path, requestOptions);
+    }
+    /**
+     * Retry a failed webhook delivery.
+     *
+     * @param eventId - The event ID of the failed delivery.
+     * @param options - Request overrides.
+     *
+     * @example
+     * ```typescript
+     * await pac.balance.retryWebhook('evt_abc123');
+     * ```
+     */
+    async retryWebhook(eventId, options) {
+        return this.client.post(`/api/v1/balance/webhooks/${encodeURIComponent(eventId)}/retry`, {}, options);
+    }
+    // -------------------------------------------------------------------------
+    // Customer Ledgers
+    // -------------------------------------------------------------------------
+    /**
+     * List all customer balance records for your account.
+     *
+     * Each unique customerId passed to emit() automatically creates an
+     * isolated customer record. This method returns a paginated list.
+     *
+     * @param options - Search, pagination, and request overrides.
+     * @returns Paginated list of customer records.
+     *
+     * @example
+     * ```typescript
+     * const { customers } = await pac.balance.customers();
+     * for (const c of customers) {
+     *   console.log(c.customerId, c.totalDeltas);
+     * }
+     * ```
+     */
+    async customers(options) {
+        const { search, limit, page, ...requestOptions } = options ?? {};
+        const params = new URLSearchParams();
+        if (search !== undefined)
+            params.set('search', search);
+        if (limit !== undefined)
+            params.set('limit', String(limit));
+        if (page !== undefined)
+            params.set('page', String(page));
+        const query = params.toString();
+        const path = `/api/v1/balance/customers${query ? `?${query}` : ''}`;
+        const response = await this.client.get(path, requestOptions);
+        return this.normalizeListCustomersResponse(response);
+    }
+    /**
+     * Get the full record detail for a specific customer.
+     *
+     * Returns the derived customer reference, computed balance, delta count,
+     * and latest checkpoint. The customer reference is deterministic.
+     *
+     * @param customerId - The customer to look up.
+     * @param options - Activity pagination and request overrides.
+     * @returns Customer detail including balance and references.
+     *
+     * @example
+     * ```typescript
+     * const customer = await pac.balance.customer('cust_001');
+     * console.log(customer.customerReference); // 0xA1b2...Ef34
+     * console.log(customer.computedBalance);   // 4500.00
+     * ```
+     */
+    async customer(customerId, options) {
+        const { deltaPage, deltaLimit, ...requestOptions } = options ?? {};
+        const params = new URLSearchParams();
+        if (deltaPage !== undefined)
+            params.set('deltaPage', String(deltaPage));
+        if (deltaLimit !== undefined)
+            params.set('deltaLimit', String(deltaLimit));
+        const query = params.toString();
+        const path = `/api/v1/balance/customers/${encodeURIComponent(customerId)}${query ? `?${query}` : ''}`;
+        const response = await this.client.get(path, requestOptions);
+        return this.normalizeCustomerDetailResponse(response);
+    }
+    normalizeEmitResponse(data) {
+        const proofRoot = String(data.proofRoot ?? data.receiptId ?? '');
+        return {
+            recordId: String(data.recordId ?? ''),
+            customerId: String(data.customerId ?? ''),
+            delta: Number(data.delta ?? 0),
+            sequenceNumber: data.sequenceNumber == null ? undefined : String(data.sequenceNumber),
+            status: toRecordStatus(data.status),
+            receiptId: String(data.receiptId ?? proofRoot),
+            proofRoot,
+            itemHashes: Array.isArray(data.itemHashes)
+                ? data.itemHashes.map((value) => String(value))
+                : [],
+            estimatedVerifiedDeltas: Number(data.estimatedVerifiedDeltas ?? 0),
+            estimatedCredits: Number(data.estimatedCredits ?? 0),
+            receivedAt: String(data.receivedAt ?? ''),
+            message: String(data.message ?? ''),
+        };
+    }
+    mergeEmitWithStatus(initial, status) {
+        const firstDelta = status.deltas[0];
+        const customerId = status.customerId ?? firstDelta?.customerId ?? initial.customerId;
+        const delta = status.delta ?? firstDelta?.delta ?? initial.delta;
+        const sequenceNumber = firstDelta?.sequenceNumber ?? initial.sequenceNumber;
+        return {
+            ...initial,
+            recordId: status.recordId || initial.recordId,
+            customerId: customerId == null ? initial.customerId : String(customerId),
+            delta: delta == null ? initial.delta : Number(delta),
+            sequenceNumber: sequenceNumber ?? undefined,
+            status: status.status,
+            receiptId: status.receiptId ?? initial.receiptId,
+            proofRoot: status.receiptId ?? initial.proofRoot,
+            receivedAt: status.receivedAt || initial.receivedAt,
+            message: status.status === 'VERIFIED'
+                ? 'Delta verified.'
+                : status.status === 'FAILED'
+                    ? 'Delta verification failed.'
+                    : initial.message,
+        };
+    }
+    normalizeDeltaStatusResponse(data) {
+        const deltas = Array.isArray(data.deltas)
+            ? data.deltas.map((entry) => {
+                const item = entry;
+                return {
+                    customerId: item.customerId == null ? null : String(item.customerId),
+                    delta: item.delta == null ? null : Number(item.delta),
+                    sequenceNumber: item.sequenceNumber == null ? null : String(item.sequenceNumber),
+                };
+            })
+            : [];
+        return {
+            recordId: String(data.recordId ?? ''),
+            status: toRecordStatus(data.status),
+            deltaCount: Number(data.deltaCount ?? deltas.length),
+            customerId: data.customerId == null ? null : String(data.customerId),
+            delta: data.delta == null ? null : Number(data.delta),
+            deltas,
+            receiptId: data.receiptId == null ? null : String(data.receiptId),
+            verificationReference: data.verificationReference == null ? null : String(data.verificationReference),
+            receivedAt: String(data.receivedAt ?? ''),
+            verifiedAt: data.verifiedAt == null ? null : String(data.verifiedAt),
+        };
+    }
+    normalizeDeriveResponse(data) {
+        const deltas = Array.isArray(data.deltas)
+            ? data.deltas.map((entry) => {
+                const item = entry;
+                const proofRoot = String(item.proofRoot ?? item.receiptId ?? '');
+                return {
+                    recordId: String(item.recordId ?? ''),
+                    itemHash: String(item.itemHash ?? ''),
+                    proofRoot,
+                    receiptId: String(item.receiptId ?? proofRoot),
+                    sequenceNumber: item.sequenceNumber == null ? null : String(item.sequenceNumber),
+                    delta: Number(item.delta ?? 0),
+                    reason: item.reason == null ? null : String(item.reason),
+                    referenceId: item.referenceId == null ? null : String(item.referenceId),
+                    window: String(item.window ?? ''),
+                    declaredTimestamp: item.declaredTimestamp == null
+                        ? null
+                        : String(item.declaredTimestamp),
+                    blockTimestamp: item.blockTimestamp == null ? null : String(item.blockTimestamp),
+                    dataPurged: Boolean(item.dataPurged),
+                    verified: true,
+                };
+            })
+            : [];
+        const verificationProof = (data.verificationProof ??
+            {});
+        const windowSummaries = Array.isArray(data.windowSummaries)
+            ? data.windowSummaries.map((entry) => {
+                const item = entry;
+                return {
+                    window: String(item.window ?? ''),
+                    deltasCount: Number(item.deltasCount ?? 0),
+                    netDelta: Number(item.netDelta ?? 0),
+                    firstBlockTimestamp: item.firstBlockTimestamp == null
+                        ? null
+                        : String(item.firstBlockTimestamp),
+                    lastBlockTimestamp: item.lastBlockTimestamp == null
+                        ? null
+                        : String(item.lastBlockTimestamp),
+                };
+            })
+            : [];
+        const pagination = (data.pagination ?? {});
+        const hint = data._hint;
+        return {
+            customerId: String(data.customerId ?? ''),
+            startingBalance: Number(data.startingBalance ?? 0),
+            startingCheckpoint: String(data.startingCheckpoint ?? 'genesis'),
+            startingCheckpointType: toCheckpointType(data.startingCheckpointType),
+            deltasCount: Number(data.deltasCount ?? deltas.length),
+            computedBalance: Number(data.computedBalance ?? 0),
+            latestCheckpoint: data.latestCheckpoint == null ? null : String(data.latestCheckpoint),
+            latestReceiptId: data.latestReceiptId == null ? null : String(data.latestReceiptId),
+            deltas,
+            windowSummaries,
+            verificationProof: {
+                proofRoot: verificationProof.proofRoot == null
+                    ? null
+                    : String(verificationProof.proofRoot),
+                message: String(verificationProof.message ?? ''),
+            },
+            pagination: {
+                total: Number(pagination.total ?? deltas.length),
+                limit: Number(pagination.limit ?? deltas.length),
+                offset: Number(pagination.offset ?? 0),
+            },
+            _hint: hint == null
+                ? undefined
+                : {
+                    message: String(hint.message ?? ''),
+                    recommendation: String(hint.recommendation ?? ''),
+                    docsUrl: String(hint.docsUrl ?? ''),
+                },
+        };
+    }
+    normalizeCompareResponse(data) {
+        const proof = (data.proof ?? {});
+        return {
+            customerId: String(data.customerId ?? ''),
+            yourBalance: Number(data.yourBalance ?? 0),
+            theirBalance: Number(data.theirBalance ?? 0),
+            neutralBalance: Number(data.neutralBalance ?? 0),
+            matchesYours: Boolean(data.matchesYours),
+            matchesTheirs: Boolean(data.matchesTheirs),
+            deltasVerified: Number(data.deltasVerified ?? 0),
+            discrepancyReport: data.discrepancyReport ?? null,
+            proof: {
+                proofRoot: proof.proofRoot == null ? null : String(proof.proofRoot),
+                latestCheckpoint: proof.latestCheckpoint == null ? null : String(proof.latestCheckpoint),
+                windowSummaries: proof.windowSummaries ??
+                    [],
+            },
+        };
+    }
+    normalizeReceiptResponse(data) {
+        const verification = (data.verification ?? {});
+        return {
+            customerId: String(data.customerId ?? ''),
+            generatedAt: String(data.generatedAt ?? ''),
+            deltasCount: Number(data.deltasCount ?? 0),
+            finalBalance: Number(data.finalBalance ?? 0),
+            proofRoot: data.proofRoot == null ? null : String(data.proofRoot),
+            receiptId: data.receiptId == null ? null : String(data.receiptId),
+            latestCheckpoint: data.latestCheckpoint == null ? null : String(data.latestCheckpoint),
+            deltas: data.deltas ?? [],
+            windowSummaries: data.windowSummaries ?? [],
+            verification: {
+                message: String(verification.message ?? ''),
+                itemHashes: Array.isArray(verification.itemHashes)
+                    ? verification.itemHashes.map((value) => String(value))
+                    : [],
+            },
+        };
+    }
+    normalizeInvoiceProofResponse(data) {
+        return {
+            customerId: String(data.customerId ?? ''),
+            period: String(data.period ?? ''),
+            proofRoot: String(data.proofRoot ?? ''),
+            verificationReference: data.verificationReference == null
+                ? null
+                : String(data.verificationReference),
+            verificationExplorerUrl: data.verificationExplorerUrl == null
+                ? null
+                : String(data.verificationExplorerUrl),
+            verifyUrl: data.verifyUrl == null ? null : String(data.verifyUrl),
+            deltaCount: Number(data.deltaCount ?? 0),
+            startingBalance: Number(data.startingBalance ?? 0),
+            finalBalance: Number(data.finalBalance ?? 0),
+            windowSummary: data.windowSummary ??
+                {
+                    window: '',
+                    deltasCount: 0,
+                    netDelta: 0,
+                    firstDeltaAt: null,
+                    lastDeltaAt: null,
+                },
+            deltas: data.deltas ?? [],
+            verification: data.verification ??
+                {
+                    proofRoot: null,
+                    totalBalance: 0,
+                    periodBalance: 0,
+                },
+        };
+    }
+    normalizeCheckpointResponse(data) {
+        return {
+            checkpointId: String(data.checkpointId ?? ''),
+            period: String(data.period ?? ''),
+            proofRoot: String(data.proofRoot ?? ''),
+            scope: data.scope,
+            mode: data.mode,
+            deltaCount: Number(data.deltaCount ?? 0),
+            selectedFingerprintCount: data.selectedFingerprintCount == null
+                ? undefined
+                : Number(data.selectedFingerprintCount),
+            eligibleFingerprintCount: data.eligibleFingerprintCount == null
+                ? undefined
+                : Number(data.eligibleFingerprintCount),
+            selectedFingerprints: Array.isArray(data.selectedFingerprints)
+                ? data.selectedFingerprints.map((value) => String(value))
+                : undefined,
+            fromIndex: Number(data.fromIndex ?? 0),
+            toIndex: Number(data.toIndex ?? 0),
+            customerId: String(data.customerId ?? ''),
+            status: toRecordStatus(data.status),
+            message: String(data.message ?? ''),
+        };
+    }
+    normalizeListCheckpointsResponse(data) {
+        const checkpoints = Array.isArray(data.checkpoints)
+            ? data.checkpoints.map((entry) => {
+                const item = entry;
+                return {
+                    checkpointId: String(item.checkpointId ?? ''),
+                    period: String(item.period ?? ''),
+                    proofRoot: item.proofRoot == null ? null : String(item.proofRoot),
+                    scope: item.scope,
+                    mode: item.mode,
+                    deltaCount: Number(item.deltaCount ?? 0),
+                    selectedFingerprintCount: item.selectedFingerprintCount == null
+                        ? undefined
+                        : Number(item.selectedFingerprintCount),
+                    eligibleFingerprintCount: item.eligibleFingerprintCount == null
+                        ? undefined
+                        : Number(item.eligibleFingerprintCount),
+                    customerId: String(item.customerId ?? ''),
+                    status: toRecordStatus(item.status),
+                    verificationReference: item.verificationReference == null
+                        ? null
+                        : String(item.verificationReference),
+                    verifiedAt: item.verifiedAt == null ? null : String(item.verifiedAt),
+                    receivedAt: String(item.receivedAt ?? ''),
+                };
+            })
+            : [];
+        const pagination = (data.pagination ?? {});
+        return {
+            checkpoints,
+            pagination: {
+                total: Number(pagination.total ?? checkpoints.length),
+                limit: Number(pagination.limit ?? checkpoints.length),
+                offset: Number(pagination.offset ?? 0),
+            },
+        };
+    }
+    normalizeSequenceGapsResponse(data) {
+        const gaps = Array.isArray(data.gaps)
+            ? data.gaps.map((entry) => {
+                const item = entry;
+                return {
+                    startSequence: String(item.startSequence ?? ''),
+                    endSequence: String(item.endSequence ?? ''),
+                    missingCount: String(item.missingCount ?? '0'),
+                };
+            })
+            : [];
+        return {
+            customerId: String(data.customerId ?? ''),
+            customerReference: String(data.customerReference ?? ''),
+            customerPartition: String(data.customerPartition ?? ''),
+            nextSequence: String(data.nextSequence ?? '0'),
+            rangeStart: String(data.rangeStart ?? '0'),
+            rangeEnd: String(data.rangeEnd ?? '0'),
+            gaps,
+            hasGaps: Boolean(data.hasGaps),
+            missingRanges: Number(data.missingRanges ?? gaps.length),
+            missingCountInPage: String(data.missingCountInPage ?? '0'),
+            truncated: Boolean(data.truncated),
+        };
+    }
+    normalizeBulkEmitResponse(data) {
+        const results = Array.isArray(data.results)
+            ? data.results.map((entry) => {
+                const item = entry;
+                return {
+                    index: Number(item.index ?? 0),
+                    customerId: String(item.customerId ?? ''),
+                    delta: Number(item.delta ?? 0),
+                    recordId: item.recordId == null ? undefined : String(item.recordId),
+                    itemHash: item.itemHash == null ? undefined : String(item.itemHash),
+                    receiptId: item.receiptId == null ? undefined : String(item.receiptId),
+                    referenceId: item.referenceId == null ? undefined : String(item.referenceId),
+                    sequenceNumber: item.sequenceNumber == null
+                        ? undefined
+                        : String(item.sequenceNumber),
+                    idempotent: item.idempotent == null ? undefined : Boolean(item.idempotent),
+                    status: String(item.status ?? ''),
+                    error: item.error == null ? undefined : String(item.error),
+                };
+            })
+            : [];
+        return {
+            totalQueued: Number(data.totalQueued ?? results.length),
+            totalFailed: Number(data.totalFailed ?? 0),
+            results,
+            _efficiency: data._efficiency,
+        };
+    }
+    normalizeListCustomersResponse(data) {
+        const customers = Array.isArray(data.customers)
+            ? data.customers.map((entry) => {
+                const item = entry;
+                return {
+                    customerId: String(item.customerId ?? ''),
+                    customerReference: String(item.customerReference ?? ''),
+                    totalDeltas: Number(item.totalDeltas ?? 0),
+                    firstDeltaAt: item.firstDeltaAt == null ? null : String(item.firstDeltaAt),
+                    lastDeltaAt: item.lastDeltaAt == null ? null : String(item.lastDeltaAt),
+                };
+            })
+            : [];
+        const pagination = (data.pagination ?? {});
+        return {
+            customers,
+            pagination: {
+                total: Number(pagination.total ?? customers.length),
+                page: Number(pagination.page ?? 1),
+                limit: Number(pagination.limit ?? customers.length),
+                totalPages: Number(pagination.totalPages ?? 1),
+            },
+        };
+    }
+    normalizeCustomerDetailResponse(data) {
+        return {
+            customerId: String(data.customerId ?? ''),
+            customerReference: String(data.customerReference ?? ''),
+            totalDeltas: Number(data.totalDeltas ?? 0),
+            firstDeltaAt: data.firstDeltaAt == null ? null : String(data.firstDeltaAt),
+            lastDeltaAt: data.lastDeltaAt == null ? null : String(data.lastDeltaAt),
+            customerPartition: String(data.customerPartition ?? ''),
+            computedBalance: Number(data.computedBalance ?? 0),
+            latestCheckpoint: data.latestCheckpoint == null ? null : String(data.latestCheckpoint),
+            privacyNote: String(data.privacyNote ?? ''),
+            recentActivity: data.recentActivity ??
+                {
+                    items: [],
+                    pagination: {
+                        total: 0,
+                        page: 1,
+                        limit: 20,
+                        totalPages: 1,
+                    },
+                },
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Invoice Proof (deprecated — use receipt with period)
+    // -------------------------------------------------------------------------
+    /**
+     * Generate an invoice-ready receipt for a customer's billing period.
+     *
+     * @deprecated Use `receipt(customerId, { period })` instead.
+     * @param customerId - The customer to generate the receipt for.
+     * @param options - Period selection and request overrides.
+     * @returns Receipt with proof root, verifyUrl, and verification data.
+     */
+    async invoiceProof(customerId, options) {
+        return this.receiptForPeriod(customerId, options);
     }
 }
 exports.BalanceResource = BalanceResource;