@unicitylabs/sphere-sdk 0.14.0-dev.5 → 0.14.0-dev.6

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

@@ -547,6 +547,25 @@ interface PaymentsRequestsApi {
     decline(id: string): Promise<void>;
     dismissProcessed(): void;
 }
+/**
+ * A pending-transfers row, derived ON READ from the §6 stores (intent backstop
+ * + delivery journal + shortfalls) — never a cached mirror. kind 'shortfall' =
+ * a completed partial (#690) whose `amount` is the remainder still owed;
+ * legs.certified counts journaled legs (certified, delivery still owed).
+ */
+interface PendingTransfer {
+    transferId: string;
+    kind: 'open' | 'shortfall';
+    recipient: string;
+    coinId: string;
+    amount: string;
+    legs: {
+        certified: number;
+        total: number;
+    };
+    deliveryPending: boolean;
+    createdAt: number;
+}
 interface PaymentsV2 {
     assets(coinId?: string): Promise<Asset[]>;
     tokens(filter?: {
@@ -561,6 +580,8 @@ interface PaymentsV2 {
     receive(): Promise<{
         transfers: IncomingTransfer[];
     }>;
+    pendingTransfers(): Promise<PendingTransfer[]>;
+    resumeNow(): Promise<void>;
     readonly requests: PaymentsRequestsApi;
 }
 interface PaymentsV2Events {
@@ -919,6 +940,12 @@ interface FacadeSession {
     start(): Promise<void>;
     stop(): Promise<void>;
     subscribeStream(stream: 'inventory' | 'mailbox' | 'payment_requests', handler: () => void): () => void;
+    /**
+     * 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;
 }
 interface IntentWireLike {
     transferId: string;
@@ -980,6 +1007,12 @@ declare class PaymentsFacade implements PaymentsV2 {
     private readonly pendingOps;
     private unsubscribers;
     private started;
+    private readonly heartbeat;
+    private readonly converger;
+    /** Resume single-flight (§7): ticks, start() and resumeNow() coalesce onto ONE pass. */
+    private readonly resumeFlight;
+    /** §7 ownership: ids with an in-process machine attempt — the pass never adopts one. */
+    private readonly activeMoneyOps;
     constructor(deps: PaymentsFacadeDeps);
     start(): Promise<void>;
     /** §7 same-address restart gate: resolves only after in-flight ops settle. */
@@ -994,11 +1027,17 @@ declare class PaymentsFacade implements PaymentsV2 {
         before?: string;
         limit?: number;
     }): Promise<HistoryPage>;
+    /** §4 pending-transfers UI surface — derived on read, never cached (convergence.ts). */
+    pendingTransfers(): Promise<PendingTransfer[]>;
     send(request: SendRequest): Promise<TransferResult>;
     receive(): Promise<{
         transfers: IncomingTransfer[];
     }>;
     mint(coinId: string, amount: bigint): Promise<MintResult>;
+    resumeNow(): Promise<void>;
+    /** One single-flighted pass + its reschedule: concurrent callers coalesce. */
+    private runConvergencePass;
+    private nowMs;
     private sendWithPolicy;
     /** §5.6 cross-network deposit trap: refused BEFORE any reserve/certification. */
     private requireSameNetworkRecipient;
@@ -1043,18 +1082,22 @@ declare class PaymentsFacade implements PaymentsV2 {
     private stampTransferId;
     private softAbort;
     private mintInner;
+    private mintUnderJournal;
     private finalizeMint;
+    /** @returns how many journal entries were RESOLVED (cleared) — heartbeat progress. */
     private replayMints;
     private replayMint;
     private mintParams;
     private tokenInServerInventory;
     private engine;
     private newId;
-    private runResume;
     private seedHeldStates;
     private toUiToken;
     private track;
     private trackTail;
 }
 
-export { ATTENTION_MINT_UNRESOLVED, type ApplyDeltaResult, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, 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 PlannedOp, type RecipientInfo, STORE_KEYS, type ScopedKV, type SendRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, supportsDeterministicMint };
+declare const HEARTBEAT_SEED_MS = 5000;
+declare const HEARTBEAT_CAP_MS = 120000;
+
+export { ATTENTION_MINT_UNRESOLVED, type ApplyDeltaResult, 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

@@ -547,6 +547,25 @@ interface PaymentsRequestsApi {
     decline(id: string): Promise<void>;
     dismissProcessed(): void;
 }
+/**
+ * A pending-transfers row, derived ON READ from the §6 stores (intent backstop
+ * + delivery journal + shortfalls) — never a cached mirror. kind 'shortfall' =
+ * a completed partial (#690) whose `amount` is the remainder still owed;
+ * legs.certified counts journaled legs (certified, delivery still owed).
+ */
+interface PendingTransfer {
+    transferId: string;
+    kind: 'open' | 'shortfall';
+    recipient: string;
+    coinId: string;
+    amount: string;
+    legs: {
+        certified: number;
+        total: number;
+    };
+    deliveryPending: boolean;
+    createdAt: number;
+}
 interface PaymentsV2 {
     assets(coinId?: string): Promise<Asset[]>;
     tokens(filter?: {
@@ -561,6 +580,8 @@ interface PaymentsV2 {
     receive(): Promise<{
         transfers: IncomingTransfer[];
     }>;
+    pendingTransfers(): Promise<PendingTransfer[]>;
+    resumeNow(): Promise<void>;
     readonly requests: PaymentsRequestsApi;
 }
 interface PaymentsV2Events {
@@ -919,6 +940,12 @@ interface FacadeSession {
     start(): Promise<void>;
     stop(): Promise<void>;
     subscribeStream(stream: 'inventory' | 'mailbox' | 'payment_requests', handler: () => void): () => void;
+    /**
+     * 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;
 }
 interface IntentWireLike {
     transferId: string;
@@ -980,6 +1007,12 @@ declare class PaymentsFacade implements PaymentsV2 {
     private readonly pendingOps;
     private unsubscribers;
     private started;
+    private readonly heartbeat;
+    private readonly converger;
+    /** Resume single-flight (§7): ticks, start() and resumeNow() coalesce onto ONE pass. */
+    private readonly resumeFlight;
+    /** §7 ownership: ids with an in-process machine attempt — the pass never adopts one. */
+    private readonly activeMoneyOps;
     constructor(deps: PaymentsFacadeDeps);
     start(): Promise<void>;
     /** §7 same-address restart gate: resolves only after in-flight ops settle. */
@@ -994,11 +1027,17 @@ declare class PaymentsFacade implements PaymentsV2 {
         before?: string;
         limit?: number;
     }): Promise<HistoryPage>;
+    /** §4 pending-transfers UI surface — derived on read, never cached (convergence.ts). */
+    pendingTransfers(): Promise<PendingTransfer[]>;
     send(request: SendRequest): Promise<TransferResult>;
     receive(): Promise<{
         transfers: IncomingTransfer[];
     }>;
     mint(coinId: string, amount: bigint): Promise<MintResult>;
+    resumeNow(): Promise<void>;
+    /** One single-flighted pass + its reschedule: concurrent callers coalesce. */
+    private runConvergencePass;
+    private nowMs;
     private sendWithPolicy;
     /** §5.6 cross-network deposit trap: refused BEFORE any reserve/certification. */
     private requireSameNetworkRecipient;
@@ -1043,18 +1082,22 @@ declare class PaymentsFacade implements PaymentsV2 {
     private stampTransferId;
     private softAbort;
     private mintInner;
+    private mintUnderJournal;
     private finalizeMint;
+    /** @returns how many journal entries were RESOLVED (cleared) — heartbeat progress. */
     private replayMints;
     private replayMint;
     private mintParams;
     private tokenInServerInventory;
     private engine;
     private newId;
-    private runResume;
     private seedHeldStates;
     private toUiToken;
     private track;
     private trackTail;
 }
 
-export { ATTENTION_MINT_UNRESOLVED, type ApplyDeltaResult, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, 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 PlannedOp, type RecipientInfo, STORE_KEYS, type ScopedKV, type SendRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, supportsDeterministicMint };
+declare const HEARTBEAT_SEED_MS = 5000;
+declare const HEARTBEAT_CAP_MS = 120000;
+
+export { ATTENTION_MINT_UNRESOLVED, type ApplyDeltaResult, 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 };