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

package/dist/modules/payments-v2/index.d.cts

@@ -226,6 +226,7 @@ interface PendingTransfer {
     deliveryPending: boolean;
     createdAt: number;
 }
+type ConnectionStatus = 'connected' | 'degraded' | 'offline';
 interface PaymentsV2 {
     assets(coinId?: string): Promise<Asset[]>;
     tokens(filter?: {
@@ -242,6 +243,7 @@ interface PaymentsV2 {
     }>;
     pendingTransfers(): Promise<PendingTransfer[]>;
     resumeNow(): Promise<void>;
+    connectionStatus(): ConnectionStatus;
     readonly requests: PaymentsRequestsApi;
 }
 interface PaymentsV2Events {
@@ -261,7 +263,7 @@ interface PaymentsV2Events {
         status: PaymentRequestStatus;
     };
     'connection:status': {
-        status: 'connected' | 'degraded' | 'offline';
+        status: ConnectionStatus;
     };
 }
 
@@ -955,7 +957,8 @@ interface DeterministicMintCapable {
 declare function supportsDeterministicMint(engine: ITokenEngine): engine is ITokenEngine & DeterministicMintCapable;
 interface RecipientInfo {
     chainPubkey: string;
-    network: string;
+    /** The recipient's PROVEN network — `null` when nothing proved one (§5.6). */
+    network: string | null;
     nametag?: string;
 }
 interface FacadeSession {
@@ -970,12 +973,17 @@ interface FacadeSession {
      * stream nudge resumes. The facade registers handleEpochChange here.
      */
     subscribeEpochChange(handler: (epoch: string) => Promise<void>): () => void;
+    /**
+     * The session's CURRENT status — REQUIRED, and the ONE source `connectionStatus()`
+     * and `connection:status` both come from ('offline' before first contact).
+     */
+    status(): ConnectionStatus;
     /**
      * Optional connection-status feed (same wiring pattern as the streams; the
      * emission point is the session's existing `connection:status` transition).
      * The facade's heartbeat resets its backoff on a 'connected' recovery.
      */
-    subscribeStatus?(handler: (status: 'connected' | 'degraded' | 'offline') => void): () => void;
+    subscribeStatus?(handler: (status: ConnectionStatus) => void): () => void;
 }
 /**
  * §5.1/§6 restore surface of the checkpoint store: re-POST the slot's cached
@@ -1027,6 +1035,8 @@ interface PaymentsFacadeDeps {
     receivePollMs?: number;
 }
 
+declare const ATTENTION_RECIPIENT_NETWORK_UNVERIFIED = "recipient:network-unverified";
+
 /** Max re-plans after a conflicted attempt (#625/#677 parity with the old send loop). */
 declare const MAX_RESELECT = 8;
 declare const ATTENTION_MINT_UNRESOLVED = "mint:unresolved";
@@ -1070,6 +1080,8 @@ declare class PaymentsFacade implements PaymentsV2 {
         before?: string;
         limit?: number;
     }): Promise<HistoryPage>;
+    /** §4: read through to the session — the same value `connection:status` carries (sphere#473). No session ⇒ 'offline'. */
+    connectionStatus(): ConnectionStatus;
     /** §4 pending-transfers UI surface — derived on read, never cached (convergence.ts). */
     pendingTransfers(): Promise<PendingTransfer[]>;
     send(request: SendRequest): Promise<TransferResult>;
@@ -1092,8 +1104,6 @@ declare class PaymentsFacade implements PaymentsV2 {
      *  'failed' invites a dApp re-send, i.e. a double-pay (#631/#676). */
     private emitCleanFailure;
     private sendWithPolicy;
-    /** §5.6 cross-network deposit trap: refused BEFORE any reserve/certification. */
-    private requireSameNetworkRecipient;
     private runAttempt;
     /** Partial (#677/#690): shortfall already durable (machine wrote it BEFORE
      *  complete); accumulate settled, re-plan ONLY the remainder, NEW transferId. */
@@ -1143,4 +1153,4 @@ declare class PaymentsFacade implements PaymentsV2 {
 declare const HEARTBEAT_SEED_MS = 5000;
 declare const HEARTBEAT_CAP_MS = 120000;
 
-export { ATTENTION_MINT_UNRESOLVED, ATTENTION_RESEED_REJECTED, type ApplyDeltaResult, type CheckpointReseeder, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, HEARTBEAT_CAP_MS, HEARTBEAT_SEED_MS, type HistoryEntry, type HistoryPage, type IncomingDelivery, type IntentBackstopEntry, type IntentPayload, type InventoryAsset, type InventoryItem, type InventoryPage, MAX_RESELECT, type MintJournalEntry, type MintResult, type OpOutcome, type OutcomeClass, type PaymentRequestStatus, type PaymentRequestView, PaymentsFacade, type PaymentsFacadeDeps, type PaymentsRequestsApi, type PaymentsV2, type PaymentsV2Events, type PendingTransfer, type PlannedOp, type RecipientInfo, STORE_KEYS, type ScopedKV, type SendRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, supportsDeterministicMint };
+export { ATTENTION_MINT_UNRESOLVED, ATTENTION_RECIPIENT_NETWORK_UNVERIFIED, ATTENTION_RESEED_REJECTED, type ApplyDeltaResult, type CheckpointReseeder, type ConnectionStatus, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, HEARTBEAT_CAP_MS, HEARTBEAT_SEED_MS, type HistoryEntry, type HistoryPage, type IncomingDelivery, type IntentBackstopEntry, type IntentPayload, type InventoryAsset, type InventoryItem, type InventoryPage, MAX_RESELECT, type MintJournalEntry, type MintResult, type OpOutcome, type OutcomeClass, type PaymentRequestStatus, type PaymentRequestView, PaymentsFacade, type PaymentsFacadeDeps, type PaymentsRequestsApi, type PaymentsV2, type PaymentsV2Events, type PendingTransfer, type PlannedOp, type RecipientInfo, STORE_KEYS, type ScopedKV, type SendRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, supportsDeterministicMint };

package/dist/modules/payments-v2/index.d.ts

@@ -226,6 +226,7 @@ interface PendingTransfer {
     deliveryPending: boolean;
     createdAt: number;
 }
+type ConnectionStatus = 'connected' | 'degraded' | 'offline';
 interface PaymentsV2 {
     assets(coinId?: string): Promise<Asset[]>;
     tokens(filter?: {
@@ -242,6 +243,7 @@ interface PaymentsV2 {
     }>;
     pendingTransfers(): Promise<PendingTransfer[]>;
     resumeNow(): Promise<void>;
+    connectionStatus(): ConnectionStatus;
     readonly requests: PaymentsRequestsApi;
 }
 interface PaymentsV2Events {
@@ -261,7 +263,7 @@ interface PaymentsV2Events {
         status: PaymentRequestStatus;
     };
     'connection:status': {
-        status: 'connected' | 'degraded' | 'offline';
+        status: ConnectionStatus;
     };
 }
 
@@ -955,7 +957,8 @@ interface DeterministicMintCapable {
 declare function supportsDeterministicMint(engine: ITokenEngine): engine is ITokenEngine & DeterministicMintCapable;
 interface RecipientInfo {
     chainPubkey: string;
-    network: string;
+    /** The recipient's PROVEN network — `null` when nothing proved one (§5.6). */
+    network: string | null;
     nametag?: string;
 }
 interface FacadeSession {
@@ -970,12 +973,17 @@ interface FacadeSession {
      * stream nudge resumes. The facade registers handleEpochChange here.
      */
     subscribeEpochChange(handler: (epoch: string) => Promise<void>): () => void;
+    /**
+     * The session's CURRENT status — REQUIRED, and the ONE source `connectionStatus()`
+     * and `connection:status` both come from ('offline' before first contact).
+     */
+    status(): ConnectionStatus;
     /**
      * Optional connection-status feed (same wiring pattern as the streams; the
      * emission point is the session's existing `connection:status` transition).
      * The facade's heartbeat resets its backoff on a 'connected' recovery.
      */
-    subscribeStatus?(handler: (status: 'connected' | 'degraded' | 'offline') => void): () => void;
+    subscribeStatus?(handler: (status: ConnectionStatus) => void): () => void;
 }
 /**
  * §5.1/§6 restore surface of the checkpoint store: re-POST the slot's cached
@@ -1027,6 +1035,8 @@ interface PaymentsFacadeDeps {
     receivePollMs?: number;
 }
 
+declare const ATTENTION_RECIPIENT_NETWORK_UNVERIFIED = "recipient:network-unverified";
+
 /** Max re-plans after a conflicted attempt (#625/#677 parity with the old send loop). */
 declare const MAX_RESELECT = 8;
 declare const ATTENTION_MINT_UNRESOLVED = "mint:unresolved";
@@ -1070,6 +1080,8 @@ declare class PaymentsFacade implements PaymentsV2 {
         before?: string;
         limit?: number;
     }): Promise<HistoryPage>;
+    /** §4: read through to the session — the same value `connection:status` carries (sphere#473). No session ⇒ 'offline'. */
+    connectionStatus(): ConnectionStatus;
     /** §4 pending-transfers UI surface — derived on read, never cached (convergence.ts). */
     pendingTransfers(): Promise<PendingTransfer[]>;
     send(request: SendRequest): Promise<TransferResult>;
@@ -1092,8 +1104,6 @@ declare class PaymentsFacade implements PaymentsV2 {
      *  'failed' invites a dApp re-send, i.e. a double-pay (#631/#676). */
     private emitCleanFailure;
     private sendWithPolicy;
-    /** §5.6 cross-network deposit trap: refused BEFORE any reserve/certification. */
-    private requireSameNetworkRecipient;
     private runAttempt;
     /** Partial (#677/#690): shortfall already durable (machine wrote it BEFORE
      *  complete); accumulate settled, re-plan ONLY the remainder, NEW transferId. */
@@ -1143,4 +1153,4 @@ declare class PaymentsFacade implements PaymentsV2 {
 declare const HEARTBEAT_SEED_MS = 5000;
 declare const HEARTBEAT_CAP_MS = 120000;
 
-export { ATTENTION_MINT_UNRESOLVED, ATTENTION_RESEED_REJECTED, type ApplyDeltaResult, type CheckpointReseeder, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, HEARTBEAT_CAP_MS, HEARTBEAT_SEED_MS, type HistoryEntry, type HistoryPage, type IncomingDelivery, type IntentBackstopEntry, type IntentPayload, type InventoryAsset, type InventoryItem, type InventoryPage, MAX_RESELECT, type MintJournalEntry, type MintResult, type OpOutcome, type OutcomeClass, type PaymentRequestStatus, type PaymentRequestView, PaymentsFacade, type PaymentsFacadeDeps, type PaymentsRequestsApi, type PaymentsV2, type PaymentsV2Events, type PendingTransfer, type PlannedOp, type RecipientInfo, STORE_KEYS, type ScopedKV, type SendRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, supportsDeterministicMint };
+export { ATTENTION_MINT_UNRESOLVED, ATTENTION_RECIPIENT_NETWORK_UNVERIFIED, ATTENTION_RESEED_REJECTED, type ApplyDeltaResult, type CheckpointReseeder, type ConnectionStatus, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, HEARTBEAT_CAP_MS, HEARTBEAT_SEED_MS, type HistoryEntry, type HistoryPage, type IncomingDelivery, type IntentBackstopEntry, type IntentPayload, type InventoryAsset, type InventoryItem, type InventoryPage, MAX_RESELECT, type MintJournalEntry, type MintResult, type OpOutcome, type OutcomeClass, type PaymentRequestStatus, type PaymentRequestView, PaymentsFacade, type PaymentsFacadeDeps, type PaymentsRequestsApi, type PaymentsV2, type PaymentsV2Events, type PendingTransfer, type PlannedOp, type RecipientInfo, STORE_KEYS, type ScopedKV, type SendRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, supportsDeterministicMint };

package/dist/modules/payments-v2/index.js

@@ -1476,6 +1476,31 @@ function distinctOpCount(entries) {
   return new Set(entries.map((entry) => entry.opIndex)).size;
 }
 
+// modules/payments-v2/recipient.ts
+var ATTENTION_RECIPIENT_NETWORK_UNVERIFIED = "recipient:network-unverified";
+async function requireSameNetworkRecipient(deps, identifier) {
+  const recipient = await deps.resolveRecipient(identifier);
+  if (recipient === null || recipient.chainPubkey === "") {
+    throw new SphereError(`Recipient ${identifier} has no published chain pubkey`, "INVALID_RECIPIENT");
+  }
+  if (recipient.network === null) {
+    deps.emit("transfer:attention", {
+      transferId: "",
+      // the gate precedes plan allocation — no transferId exists yet
+      code: ATTENTION_RECIPIENT_NETWORK_UNVERIFIED,
+      detail: `could not verify the network of recipient ${identifier} \u2014 assuming this session's "${deps.network}"`
+    });
+    return recipient;
+  }
+  if (recipient.network !== deps.network) {
+    throw new SphereError(
+      `Recipient ${identifier} is on network "${recipient.network}" but this session is on "${deps.network}" \u2014 a cross-network deposit is unrecoverable`,
+      "INVALID_RECIPIENT"
+    );
+  }
+  return recipient;
+}
+
 // modules/payments-v2/restore.ts
 var ATTENTION_RESEED_REJECTED = "intent:reseed-rejected";
 var ALL_STREAMS = ["inventory", "mailbox", "payment_requests", "history"];
@@ -4010,6 +4035,10 @@ var PaymentsFacade = class {
   history(page) {
     return this.historyStore.page(page ?? {});
   }
+  /** §4: read through to the session — the same value `connection:status` carries (sphere#473). No session ⇒ 'offline'. */
+  connectionStatus() {
+    return this.started ? this.deps.session.status() : "offline";
+  }
   /** §4 pending-transfers UI surface — derived on read, never cached (convergence.ts). */
   pendingTransfers() {
     return derivePendingTransfers(this.machineStores, this.machineDeps.decryptPayload);
@@ -4084,7 +4113,7 @@ var PaymentsFacade = class {
     this.deps.emit("transfer:updated", failed);
   }
   async sendWithPolicy(request, run) {
-    const recipient = await this.requireSameNetworkRecipient(request.recipient);
+    const recipient = await requireSameNetworkRecipient(this.deps, request.recipient);
     for (let attempt = 0; ; attempt++) {
       let ctx;
       try {
@@ -4107,20 +4136,6 @@ var PaymentsFacade = class {
       if (surfaced !== null) return surfaced;
     }
   }
-  /** §5.6 cross-network deposit trap: refused BEFORE any reserve/certification. */
-  async requireSameNetworkRecipient(identifier) {
-    const recipient = await this.deps.resolveRecipient(identifier);
-    if (recipient === null || recipient.chainPubkey === "") {
-      throw new SphereError(`Recipient ${identifier} has no published chain pubkey`, "INVALID_RECIPIENT");
-    }
-    if (recipient.network !== this.deps.network) {
-      throw new SphereError(
-        `Recipient ${identifier} is on network "${recipient.network}" but this session is on "${this.deps.network}" \u2014 a cross-network deposit is unrecoverable`,
-        "INVALID_RECIPIENT"
-      );
-    }
-    return recipient;
-  }
   async runAttempt(ctx) {
     this.activeMoneyOps.add(ctx.transferId);
     try {
@@ -4497,19 +4512,12 @@ var PaymentsFacade = class {
   }
   toUiToken(tokenId, coinId, amount) {
     const now = this.nowMs();
-    return toToken(
-      tokenId,
-      { assets: [], createdAt: now, updatedAt: now },
-      { coinId, amount: amount.toString() },
-      this.deps.registry,
-      { transferring: true, suspectedSpent: false }
-    );
+    const snapshot = { assets: [], createdAt: now, updatedAt: now };
+    const flags = { transferring: true, suspectedSpent: false };
+    return toToken(tokenId, snapshot, { coinId, amount: amount.toString() }, this.deps.registry, flags);
   }
   track(op) {
-    const settled = op.then(
-      () => void 0,
-      () => void 0
-    );
+    const settled = op.then(() => void 0, () => void 0);
     this.pendingOps.add(settled);
     void settled.finally(() => this.pendingOps.delete(settled));
     return op;
@@ -4520,6 +4528,7 @@ var PaymentsFacade = class {
 };
 export {
   ATTENTION_MINT_UNRESOLVED,
+  ATTENTION_RECIPIENT_NETWORK_UNVERIFIED,
   ATTENTION_RESEED_REJECTED,
   HEARTBEAT_CAP_MS,
   HEARTBEAT_SEED_MS,