@unicitylabs/sphere-sdk 0.14.11-dev.6 → 0.14.11-dev.8

package/dist/index.cjs

@@ -11361,6 +11361,33 @@ var SerialChain = class {
     return run;
   }
 };
+function coalesced(run, observe) {
+  let inFlight = false;
+  let queued = false;
+  const start = () => {
+    inFlight = true;
+    let running;
+    try {
+      running = run();
+    } catch {
+      running = Promise.resolve();
+    }
+    observe?.(running);
+    void running.catch(() => void 0).finally(() => {
+      inFlight = false;
+      if (!queued) return;
+      queued = false;
+      start();
+    });
+  };
+  return () => {
+    if (inFlight) {
+      queued = true;
+      return;
+    }
+    start();
+  };
+}
 
 // modules/payments-v2/stores.ts
 function createScopedKV(storage, network, chainPubkey) {
@@ -12808,6 +12835,16 @@ var InventoryView = class {
     this.inFlight.add(tokenId);
     this.deps.emit("inventory:updated");
   }
+  /** Reserve a whole plan as ONE change — per token emitted 54 events per send. */
+  markInFlightMany(tokenIds) {
+    let changed = false;
+    for (const tokenId of tokenIds) {
+      if (this.inFlight.has(tokenId)) continue;
+      this.inFlight.add(tokenId);
+      changed = true;
+    }
+    if (changed) this.deps.emit("inventory:updated");
+  }
   release(tokenId) {
     if (this.inFlight.delete(tokenId)) this.deps.emit("inventory:updated");
   }
@@ -13032,6 +13069,11 @@ var InventoryView = class {
   }
 };
 
+// modules/payments-v2/ports.ts
+function isRetryableAckError(err) {
+  return err !== null && typeof err === "object" && err.retryable === true;
+}
+
 // modules/payments-v2/receive/Receive.ts
 var ACK_BATCH_SIZE = 200;
 var REFRESH_INTERVAL_MS = 2500;
@@ -13088,6 +13130,17 @@ var Receive = class {
     await flushAcks(deps, pending, epochOf);
     deps.refreshView();
   }
+  /** One listing pass: process each entry, flushing and refreshing as it goes. */
+  async drainPages(ctx, basis) {
+    const { deps, engine, pending, stored, pageEpoch } = ctx;
+    for await (const entry of deps.delivery.incoming(basis === null ? void 0 : String(basis.cursor))) {
+      const storedBefore = stored.length;
+      await this.processEntry(deps, engine, entry, pending, stored);
+      if (pending.length >= ACK_BATCH_SIZE) await flushAcks(deps, pending, pageEpoch);
+      if (stored.length > storedBefore) await this.maybeRefresh(deps, pending, pageEpoch);
+    }
+    await flushAcks(deps, pending, pageEpoch);
+  }
   async doDrain() {
     const deps = this.deps;
     this.lastRefreshAt = deps.now?.() ?? Date.now();
@@ -13099,13 +13152,7 @@ var Receive = class {
       const record = await deps.kv.get(STORE_KEYS.streamCursor("mailbox"));
       let basis = record !== null && record.syncEpoch === deps.syncEpoch() ? record : null;
       for (let pass = 0; pass < 2; pass++) {
-        for await (const entry of deps.delivery.incoming(basis === null ? void 0 : String(basis.cursor))) {
-          const storedBefore = stored.length;
-          await this.processEntry(deps, engine, entry, pending, stored);
-          if (pending.length >= ACK_BATCH_SIZE) await flushAcks(deps, pending, pageEpoch);
-          if (stored.length > storedBefore) await this.maybeRefresh(deps, pending, pageEpoch);
-        }
-        await flushAcks(deps, pending, pageEpoch);
+        await this.drainPages({ deps, engine, pending, stored, pageEpoch }, basis);
         const served = deps.delivery.incomingEpoch();
         if (basis === null || served === null || served === basis.syncEpoch) break;
         await deps.kv.remove(STORE_KEYS.streamCursor("mailbox"));
@@ -13113,10 +13160,12 @@ var Receive = class {
       }
     } catch (err) {
       logger.warn("PaymentsV2", "receive drain interrupted \u2014 unacked entries retry next drain:", err);
+      if (isRetryableAckError(err)) return stored;
       await flushAcks(deps, pending, pageEpoch).catch((flushErr) => {
         logger.warn("PaymentsV2", "receive ack flush failed \u2014 cursor holds at the acked prefix:", flushErr);
       });
     }
+    if (stored.length > 0) deps.refreshView?.();
     return stored;
   }
   async processEntry(deps, engine, entry, pending, stored) {
@@ -13187,14 +13236,18 @@ async function announce(deps, entry, record) {
   };
 }
 async function flushAcks(deps, pending, epochOf) {
+  if (pending.length === 0) return;
   let lastAcked = null;
   try {
-    while (pending.length > 0) {
-      const next = pending[0];
-      await ackOne(deps, next);
-      lastAcked = next.cursor;
-      pending.shift();
+    const settled = await settleAcks(deps, pending);
+    let i = 0;
+    while (i < pending.length && settled.has(pending[i].deliveryId)) {
+      lastAcked = pending[i].cursor;
+      i += 1;
     }
+    const stuck = pending.filter((p) => !settled.has(p.deliveryId));
+    pending.length = 0;
+    pending.push(...stuck);
   } finally {
     if (lastAcked !== null) {
       const record = { cursor: lastAcked, syncEpoch: epochOf() };
@@ -13202,14 +13255,65 @@ async function flushAcks(deps, pending, epochOf) {
     }
   }
 }
+async function settleAcks(deps, pending) {
+  const batch = deps.delivery.ackBatch?.bind(deps.delivery);
+  if (batch === void 0) return settleOneByOne(deps, pending);
+  let outcomes;
+  try {
+    outcomes = await batch(pending.map(toAckRequest));
+  } catch (err) {
+    if (isRetryableAckError(err)) throw err;
+    logger.warn("PaymentsV2", "batched mailbox ack failed \u2014 settling one at a time:", err);
+    return settleOneByOne(deps, pending);
+  }
+  const settled = new Set(outcomes.filter((o) => o.status === "settled").map((o) => o.deliveryId));
+  const conflicts = outcomes.filter((o) => o.status === "conflict").map((o) => o.deliveryId);
+  if (conflicts.length > 0) await resolveConflicts(deps, pending, conflicts, settled);
+  return settled;
+}
+async function resolveConflicts(deps, pending, conflicts, settled) {
+  for (const deliveryId of conflicts) {
+    const entry = pending.find((p) => p.deliveryId === deliveryId);
+    try {
+      await rejectStaleClaim(deps, deliveryId, entry?.transferId);
+    } catch (err) {
+      logger.warn("PaymentsV2", `stale-reject failed for ${deliveryId} \u2014 cursor holds here:`, err);
+      continue;
+    }
+    settled.add(deliveryId);
+  }
+}
+async function rejectStaleClaim(deps, deliveryId, transferId) {
+  logger.warn("PaymentsV2", `mailbox claim CONFLICT for ${deliveryId} \u2014 rejected('other') as stale`);
+  await deps.delivery.ack(deliveryId, "rejected", "other");
+  deps.attention(transferId ?? "", ATTENTION_CLAIM_CONFLICT, deliveryId);
+}
+async function settleOneByOne(deps, pending) {
+  const settled = /* @__PURE__ */ new Set();
+  for (const ack of pending) {
+    try {
+      await ackOne(deps, ack);
+    } catch (err) {
+      logger.warn("PaymentsV2", `mailbox ack failed for ${ack.deliveryId} \u2014 cursor holds here:`, err);
+      break;
+    }
+    settled.add(ack.deliveryId);
+  }
+  return settled;
+}
+function toAckRequest(ack) {
+  return {
+    deliveryId: ack.deliveryId,
+    disposition: ack.disposition,
+    ...ack.reason !== void 0 ? { reason: ack.reason } : {}
+  };
+}
 async function ackOne(deps, ack) {
   try {
     await deps.delivery.ack(ack.deliveryId, ack.disposition, ack.reason);
   } catch (err) {
     if (ack.disposition !== "claimed" || !isClaimConflict(err)) throw err;
-    logger.warn("PaymentsV2", `mailbox claim CONFLICT for ${ack.deliveryId} \u2014 rejected('other') as stale`);
-    await deps.delivery.ack(ack.deliveryId, "rejected", "other");
-    deps.attention(ack.transferId ?? "", ATTENTION_CLAIM_CONFLICT, ack.deliveryId);
+    await rejectStaleClaim(deps, ack.deliveryId, ack.transferId);
   }
 }
 function claimAck(entry) {
@@ -13963,26 +14067,6 @@ function parseAmount(raw) {
 function supportsDeterministicMint(engine) {
   return engine.deterministicMint === true;
 }
-function makeCoalescedRefresh(refresh) {
-  let inFlight = false;
-  let queued = false;
-  const run = () => {
-    inFlight = true;
-    void refresh().catch(() => void 0).finally(() => {
-      inFlight = false;
-      if (!queued) return;
-      queued = false;
-      run();
-    });
-  };
-  return () => {
-    if (inFlight) {
-      queued = true;
-      return;
-    }
-    run();
-  };
-}
 function composeFacadeParts(deps, hooks) {
   const ownPubkeyBytes = hexToBytes4(deps.ownPubkey);
   const ledger = new ReservationLedger();
@@ -14012,9 +14096,11 @@ function composeFacadeParts(deps, hooks) {
   const machineDeps = buildMachineDeps(deps, hooks, historyStore);
   const machineStores = createMachineStores(deps.kv);
   const heldStates = /* @__PURE__ */ new Map();
+  const refreshView = coalesced(() => view.delta(), hooks.track);
   return {
     ownPubkeyBytes,
     view,
+    refreshView,
     ledger,
     pins: buildPins(deps, hooks, { ledger, view, machineStores, machineDeps }),
     queue,
@@ -14023,7 +14109,7 @@ function composeFacadeParts(deps, hooks) {
     machineDeps,
     machine: new TransferMachine(machineDeps),
     heldStates,
-    receiveLoop: buildReceive(deps, hooks, historyStore, heldStates, view),
+    receiveLoop: buildReceive(deps, hooks, historyStore, heldStates, refreshView),
     requests: buildRequests(deps, hooks),
     restoreDeps: buildRestoreDeps(deps, machineDeps, machineStores, view)
   };
@@ -14090,7 +14176,7 @@ function buildMachineDeps(deps, hooks, historyStore) {
     }
   };
 }
-function buildReceive(deps, hooks, historyStore, heldStates, view) {
+function buildReceive(deps, hooks, historyStore, heldStates, refreshView) {
   return new Receive({
     delivery: deps.deliveryPort,
     engine: () => hooks.engine(),
@@ -14104,8 +14190,7 @@ function buildReceive(deps, hooks, historyStore, heldStates, view) {
     registry: deps.registry,
     recordReceived: (record) => recordReceived(historyStore, record),
     emit: (event, transfer) => deps.emit(event, transfer),
-    // Coalesced — see makeCoalescedRefresh.
-    refreshView: makeCoalescedRefresh(() => view.delta()),
+    refreshView,
     attention: (transferId, code, detail) => {
       deps.emit(
         "transfer:attention",
@@ -14154,10 +14239,11 @@ var PaymentsFacade = class {
     const parts = composeFacadeParts(deps, {
       engine: () => this.engine(),
       send: (request) => this.send(request),
-      isActiveOp: (id) => this.activeMoneyOps.has(id)
+      isActiveOp: (id) => this.activeMoneyOps.has(id),
+      track: (op) => this.trackTail(op)
     });
     this.view = parts.view;
-    this.wakeRefresh = makeCoalescedRefresh(() => this.view.delta());
+    this.wakeRefresh = parts.refreshView;
     this.ledger = parts.ledger;
     this.queue = parts.queue;
     this.machine = parts.machine;
@@ -14294,7 +14380,6 @@ var PaymentsFacade = class {
   }
   async receive() {
     const transfers = await this.track(this.receiveLoop.drainOnce());
-    if (transfers.length > 0) this.trackTail(this.view.delta());
     return { transfers };
   }
   mint(coinId, amount) {
@@ -14490,7 +14575,7 @@ var PaymentsFacade = class {
       ...spend.plan.direct,
       ...spend.plan.split !== void 0 ? [spend.plan.split.tokenId] : []
     ];
-    for (const tokenId of sourceIds) this.view.markInFlight(tokenId);
+    this.view.markInFlightMany(sourceIds);
     if (spend.plan.split !== void 0) {
       this.queue.declareExpectedChange(transferId, coinId, spend.plan.split.remainderAmount);
     }
@@ -14776,6 +14861,10 @@ var WalletApiHttpError = class extends Error {
     if (retryAfter !== void 0) this.retryAfter = retryAfter;
   }
 };
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([0, 408, 425, 429, 500, 502, 503, 504]);
+function isRetryableStatus(err) {
+  return err instanceof WalletApiHttpError && RETRYABLE_STATUSES.has(err.status);
+}
 function isWalletApiHttpError(err, status) {
   return err instanceof WalletApiHttpError && (status === void 0 || err.status === status);
 }
@@ -15488,6 +15577,23 @@ function computeDeliveryId(tokenIdHex, stateHashHex) {
   return bytesToHex3(sha256(joined));
 }
 var DELIVERY_SEEN_KEY = "delivery:seen";
+var ACK_CHUNK = 50;
+function chunked(items, size) {
+  const out = [];
+  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
+  return out;
+}
+var RetryableAckFailure = class extends Error {
+  retryable = true;
+  constructor(cause) {
+    super(`mailbox ack batch could not be attempted: ${String(cause)}`);
+    this.name = "RetryableAckFailure";
+    this.cause = cause;
+  }
+};
+function asRetryable(err) {
+  return isRetryableStatus(err) ? new RetryableAckFailure(err) : err;
+}
 var WalletApiDeliveryPort = class {
   custody;
   client;
@@ -15653,7 +15759,54 @@ var WalletApiDeliveryPort = class {
     } else {
       await this.client.reject([deliveryId], reason);
     }
-    await this.addSeen(deliveryId);
+    await this.addSeenAll([deliveryId]);
+  }
+  /**
+   * §5.7/#757 batched settle. Claims go out grouped, rejects grouped by reason
+   * (the endpoint takes one reason per call), and the seen-set is written ONCE
+   * after every HTTP call has succeeded — never on a throw, so an aborted batch
+   * re-lists rather than being silently forgotten.
+   */
+  async ackBatch(acks) {
+    const settled = [];
+    const outcomes = [];
+    try {
+      await this.settleClaims(acks, settled, outcomes);
+      await this.settleRejects(acks, settled);
+    } catch (err) {
+      await this.addSeenAll(settled).catch(() => void 0);
+      throw asRetryable(err);
+    }
+    await this.addSeenAll(settled);
+    return [...outcomes, ...settled.map((deliveryId) => ({ deliveryId, status: "settled" }))];
+  }
+  async settleClaims(acks, settled, outcomes) {
+    const ids = acks.filter((a) => a.disposition === "claimed").map((a) => a.deliveryId);
+    for (const chunk of chunked(ids, ACK_CHUNK)) {
+      const result = await this.client.claim(chunk, this.custody === "inventory");
+      settled.push(...result.claimed);
+      settled.push(...result.alreadyClaimed.map((e) => e.entryId));
+      for (const f of result.failed) {
+        if (f.code === "CONFLICT") outcomes.push({ deliveryId: f.entryId, status: "conflict" });
+        else throw new MailboxClaimFailedError(f.entryId, f.code);
+      }
+    }
+  }
+  async settleRejects(acks, settled) {
+    const byReason = /* @__PURE__ */ new Map();
+    for (const a of acks) {
+      if (a.disposition !== "rejected") continue;
+      const key = a.reason ?? "";
+      const group = byReason.get(key) ?? [];
+      group.push(a.deliveryId);
+      byReason.set(key, group);
+    }
+    for (const [reason, group] of byReason) {
+      for (const chunk of chunked(group, ACK_CHUNK)) {
+        await this.client.reject(chunk, reason === "" ? void 0 : reason);
+        settled.push(...chunk);
+      }
+    }
   }
   onWake(cb) {
     if (this.wake === null) return () => void 0;
@@ -15664,10 +15817,12 @@ var WalletApiDeliveryPort = class {
     const raw = await this.kv.get(DELIVERY_SEEN_KEY);
     return new Set(raw ?? []);
   }
-  addSeen(deliveryId) {
+  /** SerialChain settles-not-fulfills: a rejected write never bricks later acks. */
+  addSeenAll(deliveryIds) {
+    if (deliveryIds.length === 0) return Promise.resolve();
     return this.seenChain.enqueue(async () => {
       const seen = await this.readSeen();
-      seen.add(deliveryId);
+      for (const id of deliveryIds) seen.add(id);
       await this.kv.set(DELIVERY_SEEN_KEY, [...seen]);
     });
   }