@arkade-os/sdk 0.4.19 → 0.4.21

package/dist/types/worker/messageBus.d.ts

@@ -1,4 +1,5 @@
 import { ArkProvider } from "../providers/ark";
+import { type SerializedIdentity, type LegacySerializedIdentity } from "../identity";
 import { ReadonlyWallet, Wallet } from "../wallet/wallet";
 import type { SettlementConfig } from "../wallet/vtxo-manager";
 import type { ContractWatcherConfig } from "../contracts/contractWatcher";
@@ -45,11 +46,29 @@ export interface MessageHandler<REQ extends RequestEnvelope = RequestEnvelope, R
      * Handle routed messages from the clients
      **/
     handleMessage(message: REQ): Promise<RES | null>;
+    /**
+     * Optional opt-out from the bus-level message timeout.
+     *
+     * Long-running flows (e.g. settlement) surrender control to remote peers
+     * and can legitimately sit idle for longer than `messageTimeoutMs`. When
+     * this returns true, the bus awaits `handleMessage` without a deadline.
+     * Defaults to false.
+     */
+    isLongRunning?(message: REQ): boolean;
 }
 type Options = {
     messageHandlers: MessageHandler[];
     tickIntervalMs?: number;
     messageTimeoutMs?: number;
+    /**
+     * Per-operation timeout overrides. Keys are either message types
+     * (e.g. "SETTLE") or handler tags (e.g. "WALLET_UPDATER"). Message-type
+     * matches take precedence over tag matches. Unspecified operations use
+     * `messageTimeoutMs`. These are treated as defaults: any map supplied
+     * via `INITIALIZE_MESSAGE_BUS` overrides per-key and is re-applied on
+     * every (re-)init.
+     */
+    messageTimeoutOverrides?: Record<string, number>;
     debug?: boolean;
     buildServices?: (config: Initialize["config"]) => Promise<{
         arkProvider: ArkProvider;
@@ -61,11 +80,7 @@ type Initialize = {
     type: "INITIALIZE_MESSAGE_BUS";
     id: string;
     config: {
-        wallet: {
-            privateKey: string;
-        } | {
-            publicKey: string;
-        };
+        wallet: SerializedIdentity | LegacySerializedIdentity;
         arkServer: {
             url: string;
             publicKey?: string;
@@ -75,6 +90,12 @@ type Initialize = {
         esploraUrl?: string;
         settlementConfig?: SettlementConfig | false;
         watcherConfig?: Partial<Omit<ContractWatcherConfig, "indexerProvider">>;
+        /**
+         * Page-supplied per-operation timeout map. Keys are message types
+         * (e.g. "SETTLE"). Overrides constructor-supplied
+         * `messageTimeoutOverrides` per-key; re-applied on every init.
+         */
+        messageTimeouts?: Record<string, number>;
     };
 };
 export declare class MessageBus {
@@ -83,6 +104,9 @@ export declare class MessageBus {
     private handlers;
     private tickIntervalMs;
     private messageTimeoutMs;
+    private readonly constructorTimeoutOverrides;
+    private messageTimeoutOverrides;
+    private lateDeliveries;
     private running;
     private tickTimeout;
     private tickInProgress;
@@ -91,7 +115,7 @@ export declare class MessageBus {
     private readonly buildServicesFn;
     private readonly boundOnMessage;
     /** Create the service-worker message bus with repositories and handler configuration. */
-    constructor(walletRepository: WalletRepository, contractRepository: ContractRepository, { messageHandlers, tickIntervalMs, messageTimeoutMs, debug, buildServices, }: Options);
+    constructor(walletRepository: WalletRepository, contractRepository: ContractRepository, { messageHandlers, tickIntervalMs, messageTimeoutMs, messageTimeoutOverrides, debug, buildServices, }: Options);
     /** Start the message bus and attach service-worker event listeners. */
     start(): Promise<void>;
     /** Stop the message bus, cancel ticks, and stop all registered handlers. */
@@ -104,10 +128,46 @@ export declare class MessageBus {
     private processMessage;
     /**
      * Race `promise` against a timeout. Note: this does NOT cancel the
-     * underlying work — the original promise keeps running. This is safe
-     * here because only the caller (not the handler) posts the response.
+     * underlying work — the original promise keeps running. Call
+     * `attachLateDelivery` after catching the timeout to surface the
+     * eventual result so the message id does not go silent.
      */
     private withTimeout;
+    /**
+     * Extract the declared `type` from a request envelope (e.g. "SETTLE").
+     * Not every envelope carries a type (PING/INIT are special cased
+     * earlier), so this returns undefined for envelopes that lack one.
+     */
+    private extractMessageType;
+    /**
+     * Resolve the timeout for an operation. Message-type overrides take
+     * precedence over handler-tag overrides, with the bus-wide default
+     * (`messageTimeoutMs`) as the final fallback.
+     */
+    private resolveTimeoutMs;
+    /**
+     * Build a human-readable label for timeout errors. Format:
+     * `"<MESSAGE_TYPE> via <HANDLER_TAG>"` when both are known, else the
+     * handler tag alone. Used so timeout errors name the operation the
+     * client actually triggered (e.g. SETTLE) rather than just the
+     * handler that received it (e.g. WALLET_UPDATER).
+     */
+    private labelFor;
+    /**
+     * Post a response to the originating client. When `source` is null
+     * (client tab closed, detached frame, etc.) the response cannot be
+     * delivered; we log the drop in debug mode so it is not invisible.
+     */
+    private deliverResponse;
+    /**
+     * After a handler times out the client has already received a timeout
+     * error, but the handler keeps running. Attach a follow-up so the
+     * handler's eventual result (or error) is delivered under the same
+     * message id, or — if the handler never completes within
+     * {@link LATE_DELIVERY_GRACE_MS} — an "Operation abandoned" error is
+     * sent so the client's listener (if still attached) does not hang.
+     */
+    private attachLateDelivery;
     /**
      * Returns the registered SW for the path.
      * It uses the functions in `service-worker-manager.ts` module.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/sdk",
-  "version": "0.4.19",
+  "version": "0.4.21",
   "description": "TypeScript SDK for building Bitcoin wallets using the Arkade protocol",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -87,7 +87,8 @@
     "@scure/base": "2.0.0",
     "@scure/bip39": "2.0.1",
     "@scure/btc-signer": "2.0.1",
-    "bip68": "1.0.4"
+    "bip68": "1.0.4",
+    "ws-electrumx-client": "1.0.5"
   },
   "devDependencies": {
     "@types/better-sqlite3": "7.6.13",