@pacspace-io/sdk 0.2.0 → 0.3.0

package/dist/resources/balance.js

@@ -3,6 +3,24 @@ 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.
  *
@@ -56,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.
@@ -87,42 +106,45 @@ 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 balance delta endpoint
-        return (0, polling_1.pollUntilTerminal)(() => this.client.get(`/api/v1/balance/delta/${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 anchorId - The anchor ID returned from emit.
+     * @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('anc_abc123');
-     * console.log(status.status); // 'QUEUED', 'ANCHORED', etc.
+     * const status = await pac.balance.deltaStatus('rec_abc123');
+     * console.log(status.status); // 'QUEUED', 'PROCESSING', etc.
      * ```
      */
-    async deltaStatus(anchorId, options) {
-        return this.client.get(`/api/v1/balance/delta/${encodeURIComponent(anchorId)}`, options);
+    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 getAnchorStatus(anchorId, options) {
-        return this.deltaStatus(anchorId, options);
+    async getRecordStatus(recordId, options) {
+        return this.deltaStatus(recordId, options);
     }
     /**
-     * Poll anchor lifecycle until it reaches a terminal status.
+     * Poll record lifecycle until it reaches a terminal status.
      *
-     * Terminal statuses are `ANCHORED`, `VERIFIED`, and `FAILED`.
+     * Terminal statuses are `VERIFIED` and `FAILED`.
      */
-    async waitForAnchored(anchorId, options) {
+    async waitForVerified(recordId, options) {
         const { timeout = 60000, pollInterval = 2000, signal, ...requestOptions } = options ?? {};
-        return (0, polling_1.pollUntilTerminal)(() => this.getAnchorStatus(anchorId, {
+        return (0, polling_1.pollUntilTerminal)(() => this.getRecordStatus(recordId, {
             ...requestOptions,
             signal,
         }), { timeout, pollInterval, signal });
@@ -149,7 +171,8 @@ class BalanceResource {
             params.set('limit', String(limit));
         const query = params.toString();
         const path = `/api/v1/balance/gaps/${encodeURIComponent(customerId)}${query ? `?${query}` : ''}`;
-        return this.client.get(path, requestOptions);
+        const response = await this.client.get(path, requestOptions);
+        return this.normalizeSequenceGapsResponse(response);
     }
     /**
      * Record multiple deltas in a single batch request.
@@ -172,7 +195,8 @@ class BalanceResource {
      */
     async emitBatch(deltas, options) {
         const { ...requestOptions } = options ?? {};
-        return this.client.post('/api/v1/balance/delta/batch', { deltas }, requestOptions);
+        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.
@@ -241,7 +265,7 @@ class BalanceResource {
      * ```
      */
     async derive(customerId, options) {
-        const { startingBalance, startingCheckpoint, startingCheckpointType, limit, offset, ...requestOptions } = options ?? {};
+        const { startingBalance, startingCheckpoint, startingCheckpointType, limit, offset, period, timePreset, startDate, endDate, ...requestOptions } = options ?? {};
         // Build query string
         const params = new URLSearchParams();
         if (startingBalance !== undefined) {
@@ -250,8 +274,9 @@ 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));
@@ -259,9 +284,60 @@ class BalanceResource {
         if (offset !== undefined) {
             params.set('offset', String(offset));
         }
+        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/derive/${encodeURIComponent(customerId)}${query ? `?${query}` : ''}`;
-        return this.client.get(path, requestOptions);
+        const response = await this.client.get(path, requestOptions);
+        return this.normalizeDeriveResponse(response);
+    }
+    /**
+     * Convenience helper for deriving the current UTC month.
+     */
+    async deriveCurrentMonth(customerId, options) {
+        return this.derive(customerId, {
+            ...options,
+            timePreset: 'current_month',
+        });
+    }
+    /**
+     * Convenience helper for deriving a specific UTC month (`YYYY-MM`).
+     */
+    async deriveForPeriod(customerId, period, options) {
+        return this.derive(customerId, {
+            ...options,
+            period,
+        });
+    }
+    /**
+     * Convenience helper for deriving a rolling window of recent UTC months.
+     *
+     * For example, `months = 3` resolves from the start of month N-2 through the
+     * end of the current UTC month.
+     */
+    async deriveMonthsBack(customerId, months, options) {
+        if (!Number.isInteger(months) || months < 1) {
+            throw new TypeError('months must be a positive integer');
+        }
+        const now = new Date();
+        const endExclusive = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1));
+        const start = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - (months - 1), 1));
+        return this.derive(customerId, {
+            ...options,
+            timePreset: 'custom',
+            startDate: start.toISOString(),
+            endDate: endExclusive.toISOString(),
+        });
     }
     // -------------------------------------------------------------------------
     // Compare
@@ -291,7 +367,7 @@ class BalanceResource {
      * ```
      */
     async compare(customerId, balances, options) {
-        const { startingBalance = 0, startingCheckpoint, startingCheckpointType, ...requestOptions } = options ?? {};
+        const { startingBalance = 0, startingCheckpoint, startingCheckpointType, period, timePreset, startDate, endDate, ...requestOptions } = options ?? {};
         const body = {
             customerId,
             yourBalance: balances.yours,
@@ -301,10 +377,24 @@ class BalanceResource {
         if (startingCheckpoint !== undefined) {
             body.startingCheckpoint = startingCheckpoint;
         }
-        if (startingCheckpointType !== undefined) {
-            body.startingCheckpointType = startingCheckpointType;
+        const apiCheckpointType = toApiCheckpointType(startingCheckpointType);
+        if (apiCheckpointType !== undefined) {
+            body.startingCheckpointType = apiCheckpointType;
+        }
+        if (period !== undefined) {
+            body.period = period;
+        }
+        if (timePreset !== undefined) {
+            body.timePreset = timePreset;
+        }
+        if (startDate !== undefined) {
+            body.startDate = startDate;
+        }
+        if (endDate !== undefined) {
+            body.endDate = endDate;
         }
-        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
@@ -314,7 +404,7 @@ class BalanceResource {
      *
      * When `options.period` is provided, returns a period-specific receipt (proof root,
      * verifyUrl, verificationReference) suitable for sharing on invoices. When
-     * omitted, returns the full ledger receipt with all verified deltas.
+     * omitted, returns the full record receipt with all verified deltas.
      *
      * @param customerId - The customer account to generate a receipt for.
      * @param options - Optional period (YYYY-MM) and request overrides.
@@ -327,7 +417,7 @@ class BalanceResource {
      * console.log(receipt.proofRoot);   // Include on invoice
      * console.log(receipt.verifyUrl);   // Share with counterparty
      *
-     * // Full ledger receipt
+     * // Full record receipt
      * const full = await pac.balance.receipt('cust_123');
      * console.log(full.finalBalance);
      * ```
@@ -343,7 +433,8 @@ class BalanceResource {
         }
         const { period: _period, timePreset: _timePreset, startDate: _startDate, endDate: _endDate, ...requestOptions } = opts;
         const hasOverrides = Object.keys(requestOptions).length > 0;
-        return this.client.get(`/api/v1/balance/receipt/${encodeURIComponent(customerId)}`, hasOverrides ? requestOptions : undefined);
+        const response = await this.client.get(`/api/v1/balance/receipt/${encodeURIComponent(customerId)}`, hasOverrides ? requestOptions : undefined);
+        return this.normalizeReceiptResponse(response);
     }
     /**
      * @internal
@@ -362,7 +453,8 @@ class BalanceResource {
             params.set('endDate', endDate);
         const query = params.toString();
         const path = `/api/v1/balance/invoice-proof/${encodeURIComponent(customerId)}${query ? `?${query}` : ''}`;
-        return this.client.get(path, requestOptions);
+        const response = await this.client.get(path, requestOptions);
+        return this.normalizeInvoiceProofResponse(response);
     }
     // -------------------------------------------------------------------------
     // Checkpoint
@@ -376,14 +468,14 @@ class BalanceResource {
      *
      * @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) {
@@ -403,7 +495,8 @@ class BalanceResource {
             body.mode = mode;
         if (fingerprints !== undefined)
             body.fingerprints = fingerprints;
-        return this.client.post('/api/v1/balance/checkpoint', body, requestOptions);
+        const response = await this.client.post('/api/v1/balance/checkpoint', body, requestOptions);
+        return this.normalizeCheckpointResponse(response);
     }
     // -------------------------------------------------------------------------
     // List Checkpoints
@@ -444,7 +537,8 @@ class BalanceResource {
             params.set('offset', String(offset));
         const query = params.toString();
         const path = `/api/v1/balance/checkpoints${query ? `?${query}` : ''}`;
-        return this.client.get(path, requestOptions);
+        const response = await this.client.get(path, requestOptions);
+        return this.normalizeListCheckpointsResponse(response);
     }
     // -------------------------------------------------------------------------
     // Webhook Deliveries
@@ -494,13 +588,13 @@ class BalanceResource {
     // Customer Ledgers
     // -------------------------------------------------------------------------
     /**
-     * List all customer ledgers for your account.
+     * List all customer balance records for your account.
      *
      * Each unique customerId passed to emit() automatically creates an
-     * isolated ledger. This method returns a paginated list of all ledgers.
+     * isolated customer record. This method returns a paginated list.
      *
      * @param options - Search, pagination, and request overrides.
-     * @returns Paginated list of customer ledgers.
+     * @returns Paginated list of customer records.
      *
      * @example
      * ```typescript
@@ -521,36 +615,511 @@ class BalanceResource {
             params.set('page', String(page));
         const query = params.toString();
         const path = `/api/v1/balance/customers${query ? `?${query}` : ''}`;
-        return this.client.get(path, requestOptions);
+        const response = await this.client.get(path, requestOptions);
+        return this.normalizeListCustomersResponse(response);
     }
     /**
-     * Get the full ledger detail for a specific customer.
+     * Get the full record detail for a specific customer.
      *
-     * Returns the derived ledger identifier, computed balance, delta count,
-     * and latest checkpoint. The ledger identifier is deterministic --
-     * the same customerId always produces the same identifier.
+     * 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 ledger detail including balance and identifiers.
+     * @returns Customer detail including balance and references.
      *
      * @example
      * ```typescript
-     * const ledger = await pac.balance.customer('cust_001');
-     * console.log(ledger.ledgerIdentifier); // 0xA1b2...Ef34
-     * console.log(ledger.computedBalance);  // 4500.00
+     * 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 { deltaPage, deltaLimit, period, ...requestOptions } = options ?? {};
         const params = new URLSearchParams();
         if (deltaPage !== undefined)
             params.set('deltaPage', String(deltaPage));
         if (deltaLimit !== undefined)
             params.set('deltaLimit', String(deltaLimit));
+        if (period !== undefined)
+            params.set('period', period);
         const query = params.toString();
         const path = `/api/v1/balance/customers/${encodeURIComponent(customerId)}${query ? `?${query}` : ''}`;
-        return this.client.get(path, requestOptions);
+        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 scope = (data.scope ?? null);
+        const monthlyBreakdown = Array.isArray(data.monthlyBreakdown)
+            ? data.monthlyBreakdown.map((entry) => {
+                const item = entry;
+                const checkpoint = (item.checkpoint ?? null);
+                return {
+                    period: String(item.period ?? ''),
+                    periodStart: String(item.periodStart ?? ''),
+                    periodEndExclusive: String(item.periodEndExclusive ?? ''),
+                    deltaCount: Number(item.deltaCount ?? 0),
+                    netDelta: Number(item.netDelta ?? 0),
+                    runningBalance: Number(item.runningBalance ?? 0),
+                    checkpoint: checkpoint
+                        ? {
+                            checkpointId: String(checkpoint.checkpointId ?? ''),
+                            proofRoot: checkpoint.proofRoot == null
+                                ? null
+                                : String(checkpoint.proofRoot),
+                            status: toRecordStatus(checkpoint.status),
+                        }
+                        : null,
+                };
+            })
+            : undefined;
+        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 ?? ''),
+            },
+            scope: scope
+                ? {
+                    kind: String(scope.kind ?? 'period') === 'custom'
+                        ? 'custom'
+                        : String(scope.kind ?? 'period') === 'preset'
+                            ? 'preset'
+                            : 'period',
+                    periodId: scope.periodId == null ? null : String(scope.periodId),
+                    preset: scope.preset == null
+                        ? null
+                        : String(scope.preset),
+                    startDate: String(scope.startDate ?? ''),
+                    endDateExclusive: String(scope.endDateExclusive ?? ''),
+                    label: String(scope.label ?? ''),
+                }
+                : null,
+            monthlyBreakdown,
+            cumulativeBalance: data.cumulativeBalance == null
+                ? undefined
+                : Number(data.cumulativeBalance),
+            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 ?? {});
+        const scope = (data.scope ?? null);
+        const monthlyBreakdown = Array.isArray(data.monthlyBreakdown)
+            ? data.monthlyBreakdown.map((entry) => {
+                const item = entry;
+                const checkpoint = (item.checkpoint ?? null);
+                return {
+                    period: String(item.period ?? ''),
+                    periodStart: String(item.periodStart ?? ''),
+                    periodEndExclusive: String(item.periodEndExclusive ?? ''),
+                    deltaCount: Number(item.deltaCount ?? 0),
+                    netDelta: Number(item.netDelta ?? 0),
+                    runningBalance: Number(item.runningBalance ?? 0),
+                    checkpoint: checkpoint
+                        ? {
+                            checkpointId: String(checkpoint.checkpointId ?? ''),
+                            proofRoot: checkpoint.proofRoot == null
+                                ? null
+                                : String(checkpoint.proofRoot),
+                            status: toRecordStatus(checkpoint.status),
+                        }
+                        : null,
+                };
+            })
+            : undefined;
+        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 ??
+                    [],
+            },
+            scope: scope
+                ? {
+                    kind: String(scope.kind ?? 'period') === 'custom'
+                        ? 'custom'
+                        : String(scope.kind ?? 'period') === 'preset'
+                            ? 'preset'
+                            : 'period',
+                    periodId: scope.periodId == null ? null : String(scope.periodId),
+                    preset: scope.preset == null
+                        ? null
+                        : String(scope.preset),
+                    startDate: String(scope.startDate ?? ''),
+                    endDateExclusive: String(scope.endDateExclusive ?? ''),
+                    label: String(scope.label ?? ''),
+                }
+                : null,
+            monthlyBreakdown,
+            cumulativeBalance: data.cumulativeBalance == null
+                ? undefined
+                : Number(data.cumulativeBalance),
+        };
+    }
+    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) {
+        const period = (data.period ?? null);
+        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),
+            period: period
+                ? {
+                    id: String(period.id ?? ''),
+                    startDate: String(period.startDate ?? ''),
+                    endDateExclusive: String(period.endDateExclusive ?? ''),
+                    label: String(period.label ?? ''),
+                }
+                : undefined,
+            mostRecentActivePeriod: data.mostRecentActivePeriod == null
+                ? null
+                : String(data.mostRecentActivePeriod),
+            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)