@unicitylabs/sphere-sdk 0.14.11-dev.5 → 0.14.11-dev.7

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

@@ -456,8 +456,22 @@ interface DeliveryPort {
      */
     incomingEpoch(): string | null;
     ack(deliveryId: string, disposition: 'claimed' | 'rejected', reason?: 'invalid' | 'not-owned' | 'storage-rejected' | 'other'): Promise<void>;
+    /** Settle many acks at once (#757). Contract pinned by the delivery-port contract suite. */
+    ackBatch?(acks: readonly AckRequest[]): Promise<readonly AckOutcome[]>;
     onWake?(cb: () => void): () => void;
 }
+interface AckRequest {
+    readonly deliveryId: string;
+    readonly disposition: 'claimed' | 'rejected';
+    readonly reason?: 'invalid' | 'not-owned' | 'storage-rejected' | 'other';
+}
+type AckOutcome = {
+    readonly deliveryId: string;
+    readonly status: 'settled';
+} | {
+    readonly deliveryId: string;
+    readonly status: 'conflict';
+};
 
 type StoragePortClient = Pick<WalletApiV2Client, 'listInventory' | 'blobUrls' | 'uploadUrls' | 'apply' | 'fetchBlob' | 'uploadBlob'>;
 declare class WalletApiStoragePort implements StoragePort {
@@ -528,9 +542,19 @@ declare class WalletApiDeliveryPort implements DeliveryPort {
     private openEnvelope;
     private fetchVerified;
     ack(deliveryId: string, disposition: 'claimed' | 'rejected', reason?: 'invalid' | 'not-owned' | 'storage-rejected' | 'other'): Promise<void>;
+    /**
+     * §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.
+     */
+    ackBatch(acks: readonly AckRequest[]): Promise<readonly AckOutcome[]>;
+    private settleClaims;
+    private settleRejects;
     onWake(cb: () => void): () => void;
     private readSeen;
-    private addSeen;
+    /** SerialChain settles-not-fulfills: a rejected write never bricks later acks. */
+    private addSeenAll;
 }
 
 /**

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

@@ -456,8 +456,22 @@ interface DeliveryPort {
      */
     incomingEpoch(): string | null;
     ack(deliveryId: string, disposition: 'claimed' | 'rejected', reason?: 'invalid' | 'not-owned' | 'storage-rejected' | 'other'): Promise<void>;
+    /** Settle many acks at once (#757). Contract pinned by the delivery-port contract suite. */
+    ackBatch?(acks: readonly AckRequest[]): Promise<readonly AckOutcome[]>;
     onWake?(cb: () => void): () => void;
 }
+interface AckRequest {
+    readonly deliveryId: string;
+    readonly disposition: 'claimed' | 'rejected';
+    readonly reason?: 'invalid' | 'not-owned' | 'storage-rejected' | 'other';
+}
+type AckOutcome = {
+    readonly deliveryId: string;
+    readonly status: 'settled';
+} | {
+    readonly deliveryId: string;
+    readonly status: 'conflict';
+};
 
 type StoragePortClient = Pick<WalletApiV2Client, 'listInventory' | 'blobUrls' | 'uploadUrls' | 'apply' | 'fetchBlob' | 'uploadBlob'>;
 declare class WalletApiStoragePort implements StoragePort {
@@ -528,9 +542,19 @@ declare class WalletApiDeliveryPort implements DeliveryPort {
     private openEnvelope;
     private fetchVerified;
     ack(deliveryId: string, disposition: 'claimed' | 'rejected', reason?: 'invalid' | 'not-owned' | 'storage-rejected' | 'other'): Promise<void>;
+    /**
+     * §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.
+     */
+    ackBatch(acks: readonly AckRequest[]): Promise<readonly AckOutcome[]>;
+    private settleClaims;
+    private settleRejects;
     onWake(cb: () => void): () => void;
     private readSeen;
-    private addSeen;
+    /** SerialChain settles-not-fulfills: a rejected write never bricks later acks. */
+    private addSeenAll;
 }
 
 /**

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

@@ -12,6 +12,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);
 }
@@ -4049,6 +4053,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;
@@ -4214,7 +4235,53 @@ 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) {
+      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;
@@ -4225,10 +4292,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]);
     });
   }