@unicitylabs/sphere-sdk 0.14.1-dev.1 → 0.14.1-dev.2

package/dist/impl/nodejs/index.d.cts

@@ -1058,6 +1058,14 @@ interface FacadeSession {
     start(): Promise<void>;
     stop(): Promise<void>;
     subscribeStream(stream: 'inventory' | 'mailbox' | 'payment_requests', handler: () => void): () => void;
+    /** §5.1: the latched server syncEpoch ('' before first server contact). */
+    currentEpoch(): string;
+    /**
+     * §5.1 restore hook — REQUIRED so an unwired restore protocol is a COMPILE
+     * ERROR: handlers run and are AWAITED on a syncEpoch change BEFORE any
+     * stream nudge resumes. The facade registers handleEpochChange here.
+     */
+    subscribeEpochChange(handler: (epoch: string) => Promise<void>): () => void;
     /**
      * Optional connection-status feed (same wiring pattern as the streams; the
      * emission point is the session's existing `connection:status` transition).
@@ -1346,7 +1354,6 @@ interface PaymentsV2TransportArgs {
     /** Per-(network, address) scoped KV — refresh token, cursors, seen-set live here. */
     kv: ScopedKV;
     emitStatus: (status: ConnectionStatus) => void;
-    onEpochChange: (epoch: string) => Promise<void>;
 }
 /**
  * The `Sphere.init({ walletApi })` transport config — built by

package/dist/impl/nodejs/index.d.ts

@@ -1058,6 +1058,14 @@ interface FacadeSession {
     start(): Promise<void>;
     stop(): Promise<void>;
     subscribeStream(stream: 'inventory' | 'mailbox' | 'payment_requests', handler: () => void): () => void;
+    /** §5.1: the latched server syncEpoch ('' before first server contact). */
+    currentEpoch(): string;
+    /**
+     * §5.1 restore hook — REQUIRED so an unwired restore protocol is a COMPILE
+     * ERROR: handlers run and are AWAITED on a syncEpoch change BEFORE any
+     * stream nudge resumes. The facade registers handleEpochChange here.
+     */
+    subscribeEpochChange(handler: (epoch: string) => Promise<void>): () => void;
     /**
      * Optional connection-status feed (same wiring pattern as the streams; the
      * emission point is the session's existing `connection:status` transition).
@@ -1346,7 +1354,6 @@ interface PaymentsV2TransportArgs {
     /** Per-(network, address) scoped KV — refresh token, cursors, seen-set live here. */
     kv: ScopedKV;
     emitStatus: (status: ConnectionStatus) => void;
-    onEpochChange: (epoch: string) => Promise<void>;
 }
 /**
  * The `Sphere.init({ walletApi })` transport config — built by

package/dist/impl/shared/wallet-api/index.d.cts

@@ -451,6 +451,14 @@ interface FacadeSession {
     start(): Promise<void>;
     stop(): Promise<void>;
     subscribeStream(stream: 'inventory' | 'mailbox' | 'payment_requests', handler: () => void): () => void;
+    /** §5.1: the latched server syncEpoch ('' before first server contact). */
+    currentEpoch(): string;
+    /**
+     * §5.1 restore hook — REQUIRED so an unwired restore protocol is a COMPILE
+     * ERROR: handlers run and are AWAITED on a syncEpoch change BEFORE any
+     * stream nudge resumes. The facade registers handleEpochChange here.
+     */
+    subscribeEpochChange(handler: (epoch: string) => Promise<void>): () => void;
     /**
      * Optional connection-status feed (same wiring pattern as the streams; the
      * emission point is the session's existing `connection:status` transition).
@@ -739,7 +747,6 @@ interface PaymentsV2TransportArgs {
     /** Per-(network, address) scoped KV — refresh token, cursors, seen-set live here. */
     kv: ScopedKV;
     emitStatus: (status: ConnectionStatus) => void;
-    onEpochChange: (epoch: string) => Promise<void>;
 }
 /**
  * The `Sphere.init({ walletApi })` transport config — built by

package/dist/impl/shared/wallet-api/index.d.ts

@@ -451,6 +451,14 @@ interface FacadeSession {
     start(): Promise<void>;
     stop(): Promise<void>;
     subscribeStream(stream: 'inventory' | 'mailbox' | 'payment_requests', handler: () => void): () => void;
+    /** §5.1: the latched server syncEpoch ('' before first server contact). */
+    currentEpoch(): string;
+    /**
+     * §5.1 restore hook — REQUIRED so an unwired restore protocol is a COMPILE
+     * ERROR: handlers run and are AWAITED on a syncEpoch change BEFORE any
+     * stream nudge resumes. The facade registers handleEpochChange here.
+     */
+    subscribeEpochChange(handler: (epoch: string) => Promise<void>): () => void;
     /**
      * Optional connection-status feed (same wiring pattern as the streams; the
      * emission point is the session's existing `connection:status` transition).
@@ -739,7 +747,6 @@ interface PaymentsV2TransportArgs {
     /** Per-(network, address) scoped KV — refresh token, cursors, seen-set live here. */
     kv: ScopedKV;
     emitStatus: (status: ConnectionStatus) => void;
-    onEpochChange: (epoch: string) => Promise<void>;
 }
 /**
  * The `Sphere.init({ walletApi })` transport config — built by

package/dist/impl/wallet-api-v2/index.cjs

@@ -742,7 +742,10 @@ var STORE_KEYS = {
   shortfalls: "shortfalls",
   settlingLinks: "settling",
   streamCursor: (s) => `cursor:${s}`,
-  epochLatch: "epoch-latch"
+  epochLatch: "epoch-latch",
+  // §5.2 InventoryView durable overlays (#625/#679).
+  suspectedSpent: "suspected-spent",
+  knownSpends: "known-spends"
 };
 
 // node_modules/@noble/curves/utils.js
@@ -2766,6 +2769,7 @@ var WalletApiSession = class {
   epochLatch = null;
   reseedChain = Promise.resolve();
   reseedsPending = 0;
+  epochHandlers = /* @__PURE__ */ new Set();
   handlers = /* @__PURE__ */ new Map();
   statusHandlers = /* @__PURE__ */ new Set();
   socket = null;
@@ -2868,6 +2872,18 @@ var WalletApiSession = class {
     await this.deps.kv.set(this.refreshKey, tokens.refreshToken);
   }
   // ── epoch latch (F12) ─────────────────────────────────────────────────────
+  /** §5.1: the latched server syncEpoch ('' before first server contact). */
+  currentEpoch() {
+    return this.epochLatch ?? "";
+  }
+  /**
+   * §5.1 restore hook (FacadeSession contract): handlers are AWAITED inside
+   * the reseed chain, BEFORE any stream nudge resumes.
+   */
+  subscribeEpochChange(handler) {
+    this.epochHandlers.add(handler);
+    return () => this.epochHandlers.delete(handler);
+  }
   noteEpoch(epoch) {
     if (this.epochLatch === epoch) return;
     const previous = this.epochLatch;
@@ -2881,7 +2897,7 @@ var WalletApiSession = class {
   }
   async runReseed(epoch, previous) {
     try {
-      await this.deps.onEpochChange(epoch);
+      for (const handler of [...this.epochHandlers]) await handler(epoch);
       await this.deps.kv.set(STORE_KEYS.epochLatch, epoch);
     } catch {
       if (this.epochLatch === epoch) this.epochLatch = previous;
@@ -4089,6 +4105,7 @@ var WalletApiDeliveryPort = class {
   wake;
   deriveFn;
   seenChain = new SerialChain();
+  lastIncomingEpoch = null;
   constructor(config) {
     this.client = config.client;
     this.kv = config.kv;
@@ -4183,6 +4200,7 @@ var WalletApiDeliveryPort = class {
     const seen = await this.readSeen();
     let page = await this.client.listMailbox(sinceCursor === void 0 ? 0 : Number(sinceCursor));
     for (; ; ) {
+      this.lastIncomingEpoch = String(page.syncEpoch);
       for (const entry of page.entries) {
         if (entry.status !== "unclaimed") continue;
         if (seen.has(entry.entryId)) continue;
@@ -4192,6 +4210,10 @@ var WalletApiDeliveryPort = class {
       page = await this.client.listMailbox(page.cursor);
     }
   }
+  /** §5.7: the page-honest epoch — the restore-detection source Receive keys on. */
+  incomingEpoch() {
+    return this.lastIncomingEpoch;
+  }
   toIncoming(entry) {
     const bundle = this.openEnvelope(entry);
     return {
@@ -4347,7 +4369,7 @@ var WalletApiSplitCheckpointStore = class {
     return utf8(`${transferId}:${String(opIndex)}`);
   }
   async put(transferId, opIndex, bytes) {
-    const { client, kv, fieldKey, signProgress } = this.config;
+    const { kv, fieldKey } = this.config;
     const aad = this.aad(transferId, opIndex);
     const cacheKey = this.cacheKey(transferId, opIndex);
     let envelope = await kv.get(cacheKey);
@@ -4355,10 +4377,21 @@ var WalletApiSplitCheckpointStore = class {
       envelope = encryptFieldBytes(fieldKey, bytes, aad);
       await kv.set(cacheKey, envelope);
     }
-    const signature = await signProgress(progressSignMessage(transferId, opIndex, envelope));
-    const record = await client.postProgress(transferId, opIndex, envelope, signature);
+    const record = await this.post(transferId, opIndex, envelope);
     return this.open(record.payload, aad);
   }
+  /** §5.1 restore (CheckpointReseeder): re-POST the cached ciphertext byte-identical; false = none cached. */
+  async reseedCheckpoint(transferId, opIndex) {
+    const envelope = await this.config.kv.get(this.cacheKey(transferId, opIndex));
+    if (envelope === null) return false;
+    await this.post(transferId, opIndex, envelope);
+    return true;
+  }
+  /** The ONE signed progress-append path put() and reseedCheckpoint() share. */
+  async post(transferId, opIndex, envelope) {
+    const signature = await this.config.signProgress(progressSignMessage(transferId, opIndex, envelope));
+    return this.config.client.postProgress(transferId, opIndex, envelope, signature);
+  }
   async get(transferId, opIndex) {
     const records = await this.config.client.getProgress(transferId);
     const record = records.find((r) => r.opIndex === opIndex);