@unicitylabs/sphere-sdk 0.9.1-dev.10 → 0.9.1-dev.12

package/dist/index.d.cts

@@ -1890,6 +1890,26 @@ type WalletApiPaymentRequestsPage = {
     cursor: string | null;
     syncEpoch: bigint;
 };
+/**
+ * One §16 history wire record (§10 — the server never writes history rows).
+ * `memo` / `counterpartyNametag` are S6 `enc1.` envelopes, verbatim (§8.3) —
+ * encrypted on POST, returned encrypted on GET, decrypted by the owner only.
+ */
+interface WalletApiHistoryRecord {
+    dedupKey: string;
+    id: string;
+    type: string;
+    ts: string;
+    assets: {
+        coinId: string;
+        amount: string;
+    }[];
+    transferId?: string;
+    tokenId?: string;
+    counterpartyPubkey?: string;
+    memo?: string;
+    counterpartyNametag?: string;
+}
 /**
  * The narrow, STRUCTURAL slice of the wallet-api client this module needs:
  * the E.3 intent lifecycle, blob uploads for spend outputs, and the §10
@@ -1924,21 +1944,24 @@ interface PaymentsWalletApiPort {
     /** Upload to a presigned PUT (a 412 = already present = success — §5.2). */
     uploadBlob(putUrl: string, bytes: Uint8Array): Promise<void>;
     /** §10: client-asserted history records (§16 wire shape), deduped by dedupKey server-side. */
-    postHistoryRecords(records: {
-        dedupKey: string;
-        id: string;
-        type: string;
-        ts: string;
-        assets: {
-            coinId: string;
-            amount: string;
-        }[];
-        transferId?: string;
-        tokenId?: string;
-        counterpartyPubkey?: string;
-        memo?: string;
-        counterpartyNametag?: string;
-    }[]): Promise<void>;
+    postHistoryRecords(records: WalletApiHistoryRecord[]): Promise<void>;
+    /**
+     * §10/§16: read the client-written history log back — newest-first keyset
+     * pages (`{records, more, cursor, syncEpoch}`). The READ side of the §10 log:
+     * a reloaded thin wallet rebuilds its history from here (the in-memory cache
+     * is process-lifetime; the durable log lives on the server). `memo` /
+     * `counterpartyNametag` come back as the verbatim S6 `enc1.` envelopes — the
+     * owner decrypts them with its own field key on display (§8.3).
+     */
+    listHistory(options?: {
+        before?: string;
+        limit?: number;
+    }): Promise<{
+        records: WalletApiHistoryRecord[];
+        more: boolean;
+        cursor: string | null;
+        syncEpoch: bigint;
+    }>;
     /** Network name — scopes the persisted payment-request cursor (mirrors the mailbox cursor). */
     readonly network?: string;
     /** `POST /v1/payment-requests` (§16) — `memo` MUST already be an S6 envelope (§8.3). */
@@ -2538,10 +2561,39 @@ declare class PaymentsModule {
      */
     addToHistory(entry: Omit<TransactionHistoryEntry, 'id' | 'dedupKey'>): Promise<void>;
     /**
-     * Load history from the local token storage provider into the in-memory cache.
-     * Also performs one-time migration from legacy KV storage.
+     * Load history into the in-memory cache.
+     *
+     * In the wallet-api composition (the `walletApi` client is present) the
+     * durable §10 history log lives on the SERVER — the thin storage provider
+     * keeps none — so the cache is rebuilt from `walletApi.listHistory()`. The
+     * twin of the #521 inventory reload bug: `_historyCache` is process-lifetime,
+     * so a reload (tab refresh) must re-pull it or render an empty history.
+     * Compositions WITHOUT `walletApi` keep the legacy local path below.
      */
     loadHistory(): Promise<void>;
+    /**
+     * Rebuild `_historyCache` from the server's §10 history log (the wallet-api
+     * composition). Pages newest-first via the keyset cursor until `more:false`
+     * or the page cap; dedups by `dedupKey` (a hydrate-then-receive in the same
+     * session must not double-list). The S6 `memo` / `counterpartyNametag`
+     * envelopes are decrypted with the owner's own field key on the way in.
+     *
+     * Best-effort, like the §10 history POST: history is untrusted DISPLAY data,
+     * so a backend outage during hydration must NEVER fail `load()` (the money
+     * path) — the in-session cache is left intact and the pull retries next load.
+     */
+    private hydrateHistoryFromServer;
+    /**
+     * Map one §16 history wire record onto the display
+     * {@link TransactionHistoryEntry}. `counterpartyNametag` lands on the role-
+     * appropriate field (sender for RECEIVED, recipient otherwise); the S6 memo +
+     * nametag envelopes decrypt under THIS wallet's field key (self-scoped at
+     * rest — §8.3), surfaced as absent if they don't decrypt rather than as
+     * ciphertext (same rule as mailbox/payment-request memos).
+     */
+    private historyEntryFromWire;
+    /** S6 field decrypt that surfaces an undecryptable envelope as absent (§8.3). */
+    private tryDecryptField;
     /**
      * Import history entries from remote TXF data into local store.
      * Delegates to the local TokenStorageProvider's importHistoryEntries() for
@@ -2760,6 +2812,16 @@ declare class PaymentsModule {
      * ones are not re-surfaced.
      */
     private pumpIncomingPaymentRequests;
+    /**
+     * Decrypt a payment-request's recipient-addressed memo envelope into
+     * `{ memo, senderNametag }` (the requester's message + nametag). The key is
+     * the ECDH shared secret between THIS wallet (the payer) and the requester's
+     * chain pubkey (`wire.fromPubkey`) — symmetric with the requester's
+     * create-time derivation. Returns an empty bundle (and logs at debug) on any
+     * absence/failure so the incoming view never wedges on an unreadable memo
+     * (PR twin of #546/#547).
+     */
+    private decryptPaymentRequestMemo;
     /**
      * Map a §16 wire request onto the public {@link IncomingPaymentRequest}
      * surface and notify (event + handlers). Only `open` requests are

package/dist/index.d.ts

@@ -1890,6 +1890,26 @@ type WalletApiPaymentRequestsPage = {
     cursor: string | null;
     syncEpoch: bigint;
 };
+/**
+ * One §16 history wire record (§10 — the server never writes history rows).
+ * `memo` / `counterpartyNametag` are S6 `enc1.` envelopes, verbatim (§8.3) —
+ * encrypted on POST, returned encrypted on GET, decrypted by the owner only.
+ */
+interface WalletApiHistoryRecord {
+    dedupKey: string;
+    id: string;
+    type: string;
+    ts: string;
+    assets: {
+        coinId: string;
+        amount: string;
+    }[];
+    transferId?: string;
+    tokenId?: string;
+    counterpartyPubkey?: string;
+    memo?: string;
+    counterpartyNametag?: string;
+}
 /**
  * The narrow, STRUCTURAL slice of the wallet-api client this module needs:
  * the E.3 intent lifecycle, blob uploads for spend outputs, and the §10
@@ -1924,21 +1944,24 @@ interface PaymentsWalletApiPort {
     /** Upload to a presigned PUT (a 412 = already present = success — §5.2). */
     uploadBlob(putUrl: string, bytes: Uint8Array): Promise<void>;
     /** §10: client-asserted history records (§16 wire shape), deduped by dedupKey server-side. */
-    postHistoryRecords(records: {
-        dedupKey: string;
-        id: string;
-        type: string;
-        ts: string;
-        assets: {
-            coinId: string;
-            amount: string;
-        }[];
-        transferId?: string;
-        tokenId?: string;
-        counterpartyPubkey?: string;
-        memo?: string;
-        counterpartyNametag?: string;
-    }[]): Promise<void>;
+    postHistoryRecords(records: WalletApiHistoryRecord[]): Promise<void>;
+    /**
+     * §10/§16: read the client-written history log back — newest-first keyset
+     * pages (`{records, more, cursor, syncEpoch}`). The READ side of the §10 log:
+     * a reloaded thin wallet rebuilds its history from here (the in-memory cache
+     * is process-lifetime; the durable log lives on the server). `memo` /
+     * `counterpartyNametag` come back as the verbatim S6 `enc1.` envelopes — the
+     * owner decrypts them with its own field key on display (§8.3).
+     */
+    listHistory(options?: {
+        before?: string;
+        limit?: number;
+    }): Promise<{
+        records: WalletApiHistoryRecord[];
+        more: boolean;
+        cursor: string | null;
+        syncEpoch: bigint;
+    }>;
     /** Network name — scopes the persisted payment-request cursor (mirrors the mailbox cursor). */
     readonly network?: string;
     /** `POST /v1/payment-requests` (§16) — `memo` MUST already be an S6 envelope (§8.3). */
@@ -2538,10 +2561,39 @@ declare class PaymentsModule {
      */
     addToHistory(entry: Omit<TransactionHistoryEntry, 'id' | 'dedupKey'>): Promise<void>;
     /**
-     * Load history from the local token storage provider into the in-memory cache.
-     * Also performs one-time migration from legacy KV storage.
+     * Load history into the in-memory cache.
+     *
+     * In the wallet-api composition (the `walletApi` client is present) the
+     * durable §10 history log lives on the SERVER — the thin storage provider
+     * keeps none — so the cache is rebuilt from `walletApi.listHistory()`. The
+     * twin of the #521 inventory reload bug: `_historyCache` is process-lifetime,
+     * so a reload (tab refresh) must re-pull it or render an empty history.
+     * Compositions WITHOUT `walletApi` keep the legacy local path below.
      */
     loadHistory(): Promise<void>;
+    /**
+     * Rebuild `_historyCache` from the server's §10 history log (the wallet-api
+     * composition). Pages newest-first via the keyset cursor until `more:false`
+     * or the page cap; dedups by `dedupKey` (a hydrate-then-receive in the same
+     * session must not double-list). The S6 `memo` / `counterpartyNametag`
+     * envelopes are decrypted with the owner's own field key on the way in.
+     *
+     * Best-effort, like the §10 history POST: history is untrusted DISPLAY data,
+     * so a backend outage during hydration must NEVER fail `load()` (the money
+     * path) — the in-session cache is left intact and the pull retries next load.
+     */
+    private hydrateHistoryFromServer;
+    /**
+     * Map one §16 history wire record onto the display
+     * {@link TransactionHistoryEntry}. `counterpartyNametag` lands on the role-
+     * appropriate field (sender for RECEIVED, recipient otherwise); the S6 memo +
+     * nametag envelopes decrypt under THIS wallet's field key (self-scoped at
+     * rest — §8.3), surfaced as absent if they don't decrypt rather than as
+     * ciphertext (same rule as mailbox/payment-request memos).
+     */
+    private historyEntryFromWire;
+    /** S6 field decrypt that surfaces an undecryptable envelope as absent (§8.3). */
+    private tryDecryptField;
     /**
      * Import history entries from remote TXF data into local store.
      * Delegates to the local TokenStorageProvider's importHistoryEntries() for
@@ -2760,6 +2812,16 @@ declare class PaymentsModule {
      * ones are not re-surfaced.
      */
     private pumpIncomingPaymentRequests;
+    /**
+     * Decrypt a payment-request's recipient-addressed memo envelope into
+     * `{ memo, senderNametag }` (the requester's message + nametag). The key is
+     * the ECDH shared secret between THIS wallet (the payer) and the requester's
+     * chain pubkey (`wire.fromPubkey`) — symmetric with the requester's
+     * create-time derivation. Returns an empty bundle (and logs at debug) on any
+     * absence/failure so the incoming view never wedges on an unreadable memo
+     * (PR twin of #546/#547).
+     */
+    private decryptPaymentRequestMemo;
     /**
      * Map a §16 wire request onto the public {@link IncomingPaymentRequest}
      * surface and notify (event + handlers). Only `open` requests are