routstrd 0.4.11 → 0.4.12

package/src/daemon/wallet/trusted-mints.ts

@@ -5,7 +5,7 @@ import { normalizeMintUrl } from "@cashu/coco-core";
  * always trusted, and a wallet is never allowed to point its default at a mint
  * it could not fetch.
  */
-export const DEFAULT_MINT_URL = "https://mint.cubabitcoin.org";
+export const DEFAULT_MINT_URL = "https://mint.minibits.cash/Bitcoin";
 
 /**
  * Mints routstrd trusts out of the box. Every entry is added as a trusted mint
@@ -16,7 +16,7 @@ export const DEFAULT_MINT_URL = "https://mint.cubabitcoin.org";
  */
 export const DEFAULT_TRUSTED_MINT_URLS: readonly string[] = [
   DEFAULT_MINT_URL,
-  "https://mint.minibits.cash/Bitcoin",
+  "https://mint.cubabitcoin.org",
 ];
 
 export interface TrustedMintSeeder {
@@ -84,4 +84,4 @@ export async function seedTrustedMints(
       options.onError?.(`Could not add trusted mint ${mintUrl}`, error);
     }
   }
-}
+}

package/src/daemon/wallet/wallet-client.ts

@@ -0,0 +1,206 @@
+import type { HistoryEntry } from "@cashu/coco-core";
+
+/**
+ * Contract shared by every wallet implementation.
+ *
+ * The wallet runs in-process (`createCocoClient` in `./coco-client`); this
+ * module only describes what the rest of routstrd is allowed to ask of it.
+ * Historically this lived in a `cocod-client` module that also shipped an
+ * HTTP/unix-socket client for the external `cocod` binary. That client was
+ * removed once the in-process wallet replaced it — see `./migration` and the
+ * `legacyCocod*` path helpers in `./paths` for the migration-only code that
+ * still knows about external cocod installs.
+ */
+
+export type WalletRuntimeState =
+  | "UNINITIALIZED"
+  | "LOCKED"
+  | "UNLOCKED"
+  | "RECOVERING"
+  | "ERROR";
+
+/** Live progress for background wallet recovery started at daemon startup. */
+export interface WalletRecoveryProgress {
+  state: "RECOVERING" | "UNLOCKED" | "ERROR";
+  /** Current recovery phase, e.g. "Mint recovery" or "done". */
+  phase: string;
+  pendingSends: number;
+  inflightProofs: number;
+  pendingMints: number;
+  /** Expired unpaid mint quotes failed locally without a mint round-trip. */
+  failedMintQuotes: number;
+  error?: string;
+}
+
+/** NPC (npubx.cash) Lightning address details for this wallet. */
+export interface NpcAddress {
+  /** Full Lightning address, e.g. "alice@npubx.cash" (npub fallback when no username is set). */
+  address: string;
+  /** NPC username, when one has been claimed. */
+  name?: string;
+  /** Nostr hex pubkey of the NPC account (only available from the in-process wallet). */
+  pubkey?: string;
+}
+
+/** Result of an NPC username claim attempt. */
+export interface NpcUsernameResult {
+  success: boolean;
+  /** Present when NPC requires payment to claim the username. */
+  paymentRequest?: {
+    amount?: number;
+    mints?: string[];
+    [key: string]: unknown;
+  };
+}
+
+/** Options for the wallet cleanup command. */
+export interface WalletCleanupOptions {
+  /** Only clean up operations for this mint URL. */
+  mintUrl?: string;
+  /** Minimum operation age in milliseconds (defaults to 7 days / 1 week). */
+  minAgeMs?: number;
+  /** Report what would be cleaned without applying changes. */
+  dryRun?: boolean;
+  /**
+   * Fail expired mint quotes without confirming UNPAID with the mint. Only for
+   * operators who accept the risk of stranding a quote that was paid before
+   * its invoice expired; recovery is the safe default.
+   */
+  force?: boolean;
+}
+
+/** Summary of a wallet cleanup run. */
+export interface WalletCleanupResult {
+  dryRun: boolean;
+  /** Expired quotes selected for checking; dry runs do not contact the mint. */
+  mintQuoteCandidates: number;
+  /** Number actually marked failed (always zero in a dry run). */
+  failedMintQuotes: number;
+  /** Expired quotes kept pending because they are paid/issued or unverified. */
+  leftForRecovery: number;
+  /** Number of stale pending send operations reclaimed. */
+  reclaimedSends: number;
+  /** Number of stale prepared melt operations cancelled. */
+  cancelledMelts: number;
+  /** Number of in-flight operations that were left untouched. */
+  skipped: number;
+  errors: Array<{ operationId: string; error: string }>;
+}
+
+export class WalletHttpError extends Error {
+  status: number;
+
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = "WalletHttpError";
+    this.status = status;
+  }
+}
+
+/** Progress of a Lightning top-up created with `receiveBolt11`. */
+export interface MintQuoteStatus {
+  operationId: string;
+  state: "pending" | "executing" | "finalized" | "failed";
+  /** Last quote state reported by the mint (UNPAID, PAID, ISSUED). */
+  mintState?: string;
+  amount: number;
+  mintUrl: string;
+  error?: string;
+}
+
+/** Options for explicit PAID mint-quote recovery. */
+export interface WalletMintQuoteRecoveryOptions {
+  /** Target only these operation ids (may include failed operations). */
+  operationIds?: string[];
+  /** Re-open failed operations instead of skipping them. */
+  includeFailed?: boolean;
+  /** Per-quote mint timeout in milliseconds. */
+  timeoutMs?: number;
+}
+
+/** Summary of a PAID mint-quote recovery run. */
+export interface WalletMintQuoteRecoveryResult {
+  /** Operations whose quote state was checked with the mint. */
+  checked: number;
+  /** Operations whose paid sats were minted or restored. */
+  recovered: number;
+  /** Quotes the mint still reports UNPAID; left pending. */
+  waiting: number;
+  /** Quotes the mint can no longer issue. */
+  terminal: number;
+  /** Failed operations moved back to pending before checking. */
+  reopened: number;
+  /** Operations left to a later run (mint unreachable, budget spent, non-terminal). */
+  retryable: number;
+  /** Operations skipped because an earlier recovery of them is still running. */
+  busy: number;
+  errors: Array<{ operationId: string; error: string }>;
+}
+
+/** Summary of a stuck-operation (send/melt/mint) recovery run. */
+export interface WalletStuckOperationRecoveryResult {
+  /** Timed-out waits; the underlying operation remains tracked. */
+  timedOut: number;
+  /** Operations for which recovery was attempted (not necessarily completed). */
+  attempted: number;
+  /** Locked operations or unfinished work from another pass; retry later. */
+  busy: number;
+  /** Operations skipped for unreachable mints, shutdown, or pass budget exhaustion. */
+  skipped: number;
+  /** Operations at reachable mints whose recovery still failed. */
+  failed: number;
+  /** Unreachable mint URL -> number of operations skipped there. */
+  skippedMints: Record<string, number>;
+}
+
+export interface WalletClient {
+  ping(): Promise<boolean>;
+  getStatus(): Promise<WalletRuntimeState>;
+  unlock(passphrase: string): Promise<string>;
+  getBalances(): Promise<Record<string, number>>;
+  receiveCashu(token: string): Promise<string>;
+  receiveBolt11(
+    amount: number,
+    mintUrl?: string,
+  ): Promise<{ invoice: string; operationId?: string }>;
+  /** Progress of a top-up, when the wallet tracks mint operations. */
+  getMintQuote?(operationId: string): Promise<MintQuoteStatus | null>;
+  sendCashu(amount: number, mintUrl?: string): Promise<string>;
+  sendBolt11(invoice: string, mintUrl?: string): Promise<string>;
+  listMints(): Promise<string[]>;
+  addMint(url: string): Promise<string>;
+  getMintInfo(url: string): Promise<unknown>;
+  getDefaultMint(): Promise<string | null>;
+  setDefaultMint(url: string): Promise<string>;
+  /** Release resources held by in-process wallet implementations. */
+  dispose?(): Promise<void>;
+  getHistory(offset?: number, limit?: number): Promise<HistoryEntry[]>;
+  /** Look up a single transaction by its history entry ID. */
+  getHistoryEntryById(id: string): Promise<HistoryEntry | null>;
+  /** NPC (npubx.cash) Lightning address for this wallet. */
+  getNpcAddress(): Promise<NpcAddress>;
+  /** Claim an NPC username; pass confirm=true to pay the claim fee from the wallet. */
+  setNpcUsername(username: string, confirm?: boolean): Promise<NpcUsernameResult>;
+  /** Manually trigger an NPC quote sync into the wallet. */
+  syncNpc(): Promise<void>;
+  /** Clear stuck pending/in-flight wallet operations that are safe to resolve. */
+  cleanupStuckOperations?(
+    options?: WalletCleanupOptions,
+  ): Promise<WalletCleanupResult>;
+  /**
+   * Re-issue PAID mint quotes whose sats were never claimed, optionally
+   * targeting specific operations (including ones coco already failed).
+   */
+  recoverMintQuotes?(
+    options?: WalletMintQuoteRecoveryOptions,
+    onProgress?: (message: string) => void,
+  ): Promise<WalletMintQuoteRecoveryResult>;
+  /**
+   * Recover stuck send/melt/mint operations whose mints answer a
+   * reachability probe. Operations a live execute holds are reported busy,
+   * never driven. Receive stays startup-only (receive dedup classification).
+   */
+  recoverStuckOperations?(): Promise<WalletStuckOperationRecoveryResult>;
+  /** Report background wallet recovery progress, when the wallet supports it. */
+  getRecoveryProgress?(): Promise<WalletRecoveryProgress>;
+}

package/src/integrations/pi.ts

@@ -18,6 +18,7 @@ export type ThinkingLevelMap = Partial<Record<PiThinkingLevel, string | null>>;
 
 export type PiModelEntry = {
   id: string;
+  api?: string;
   contextWindow?: number;
   name?: string;
   input?: string[];
@@ -90,6 +91,14 @@ export function deriveThinkingFields(
 }
 
 const isDeepSeekModel = (id: string): boolean => id.startsWith("deepseek");
+const isGptModel = (id: string): boolean => id.startsWith("gpt-");
+/**
+ * Anthropic-served models (claude-opus-5.5, claude-sonnet-5, claude-fable-5.1,
+ * ...). routstr nodes proxy the Anthropic-native `messages` route, so pi's
+ * Anthropic transport can talk to the node's own endpoint instead of the
+ * OpenAI-shaped translation.
+ */
+const isClaudeModel = (id: string): boolean => id.startsWith("claude");
 
 /** Project one daemon model onto a pi config entry. */
 export function buildPiModelEntry(
@@ -113,6 +122,26 @@ export function buildPiModelEntry(
   if (mods.includes("image")) input.push("image");
   entry.input = input;
 
+  // Per-model transport pins. `api` is per-model while the provider `baseUrl`
+  // is shared, and the transports disagree about what a base URL means: the
+  // OpenAI SDKs append only their endpoint (`/chat/completions`, `/responses`)
+  // while Anthropic SDKs append `/v1/messages` themselves. The provider base
+  // URL is therefore the daemon ROOT (see installPiIntegration), which is the
+  // one spelling that resolves correctly for every transport:
+  //   gpt-*   -> {root}/responses        -> `responses`
+  //   claude* -> {root}/v1/messages      -> `messages`
+  //   other   -> {root}/chat/completions -> `chat/completions`
+  // Pins override a curated value: a stale `anthropic-messages` left on a
+  // non-claude model picks an endpoint the daemon is not expecting, and the
+  // user cannot see from models.json which family needs which transport.
+  if (isGptModel(model.id)) {
+    entry.api = "openai-responses";
+  } else if (isClaudeModel(model.id)) {
+    entry.api = "anthropic-messages";
+  } else if (previous?.api !== undefined) {
+    entry.api = previous.api;
+  }
+
   const derived = deriveThinkingFields(model);
   if (derived) {
     entry.reasoning = derived.reasoning;
@@ -154,17 +183,36 @@ type PiConfig = {
   providers?: Record<string, PiProviderConfig>;
 };
 
+export type PiIntegrationDeps = {
+  callDaemon: typeof callDaemon;
+  getDaemonBaseUrl: typeof getDaemonBaseUrl;
+};
+
 export async function installPiIntegration(
   config: RoutstrdConfig,
   apiKey: string,
   integrationConfig: IntegrationConfig,
+  // Injectable I/O so tests don't need mock.module, whose overrides leak
+  // across test files for the rest of the run under bun's runner.
+  deps: Partial<PiIntegrationDeps> = {},
 ): Promise<void> {
   const { name, configPath } = integrationConfig;
+  const callDaemonFn = deps.callDaemon ?? callDaemon;
+  const getDaemonBaseUrlFn = deps.getDaemonBaseUrl ?? getDaemonBaseUrl;
 
   console.log("\nInstalling routstr models in pi models.json...");
   console.log(`Using API key for ${name}`);
 
-  const baseUrl = `${getDaemonBaseUrl(config)}/v1`;
+  // The daemon ROOT, deliberately without `/v1`. Every transport appends its
+  // own endpoint path, and only the Anthropic ones add a version prefix
+  // (`/v1/messages`); a base URL that already carries `/v1` therefore yields
+  // the doubled `/v1/v1/messages`, which routstr-core rejects with a 404 from
+  // every provider in the pool (it canonicalizes exactly one optional `v1/`).
+  // At the root, openai-completions -> `/chat/completions`, openai-responses
+  // -> `/responses` and anthropic-messages -> `/v1/messages` all land on an
+  // allowed route. getDaemonBaseUrl() strips any trailing slash, so no path
+  // can be double-slashed either.
+  const baseUrl = getDaemonBaseUrlFn(config);
 
   let piConfig: PiConfig = {};
 
@@ -186,7 +234,7 @@ export async function installPiIntegration(
     // Ensure directory exists
     mkdirSync(dirname(configPath), { recursive: true });
 
-    const data = await callDaemon("/models");
+    const data = await callDaemonFn("/models");
     const models = (data.output as { models: RoutstrModel[] } | undefined)?.models || [];
 
     if (models.length === 0) {
@@ -198,7 +246,9 @@ export async function installPiIntegration(
     // models.json is always a faithful projection of the daemon's state.
     // Thinking fields are derived from the model's published reasoning allowlist;
     // when the daemon has none, the user's hand-curated values are preserved.
-    // `compat` stays user-curated, except for the deepseek* pin applied below.
+    // `compat` stays user-curated, except for the deepseek* pin applied below;
+    // `api` is pinned per family (see buildPiModelEntry), since the family
+    // decides which transport — and so which endpoint — the model is served by.
     const existingModels = new Map<string, PiModelEntry>(
       (piConfig.providers["routstr"]?.models ?? []).map((m) => [m.id, m]),
     );

package/src/utils/config.ts

@@ -46,8 +46,9 @@ export interface RoutstrdConfig {
   port: number;
   host: string;
   provider: string | null;
-  cocodPath: string | null;
   mode?: "xcashu" | "apikeys";
+  /** Opt into SDK automatic model-path selection for DeepSeek V4.1 Flash. Disabled by default; requires daemon restart after changing. */
+  autoModelPath?: boolean;
   /** Raw upstream request/response logging. Disabled by default because logs can contain sensitive prompts, outputs, and auth/payment headers. */
   requestResponseLogging?: {
     /** Enable raw request/response file logging. */
@@ -85,7 +86,7 @@ export const DEFAULT_CONFIG: RoutstrdConfig = {
   port: 8008,
   host: "127.0.0.1",
   provider: null,
-  cocodPath: null,
   mode: "apikeys",
+  autoModelPath: false,
   maxTokens: 64000,
 };

package/src/utils/cooldowns.ts

@@ -0,0 +1,134 @@
+/**
+ * Cooldown reporting, shared by the daemon (`GET /cooldowns`) and the
+ * `routstrd cooldowns` CLI command.
+ *
+ * Cooldown state is owned by the SDK: its `ProviderManager` writes
+ * `providersOnCooldown` into the SdkStore, and every entry blocks routing for
+ * the length of the cooldown window (`getCooldownDurationMs()`, 210s today).
+ * An entry with a `modelId` cools down only that model on the provider; an
+ * entry without one cools down every model on the provider.
+ *
+ * The SDK prunes expired entries lazily (on the next routing decision), so a
+ * read of the persisted list can contain entries that already timed out.
+ * Reporting therefore filters by age and never mutates the store.
+ */
+
+/** One persisted cooldown entry, as stored by the SDK. */
+export interface StoredCooldownEntry {
+  baseUrl: string;
+  /** Present for model-scoped entries; absent for provider-wide ones. */
+  modelId?: string;
+  /** When the cooldown started (ms since epoch). */
+  timestamp: number;
+}
+
+export interface CooldownSummary {
+  baseUrl: string;
+  /** Model id for model-scoped cooldowns, `null` for provider-wide ones. */
+  modelId: string | null;
+  scope: "provider" | "model";
+  startedAt: number;
+  expiresAt: number;
+  remainingMs: number;
+}
+
+export interface CooldownsOutput {
+  /** Server time the payload was built at (ms since epoch). */
+  now: number;
+  cooldownDurationMs: number;
+  /** Number of active cooldown entries (provider- and model-scoped). */
+  count: number;
+  /** Number of distinct providers with at least one active entry. */
+  providerCount: number;
+  cooldowns: CooldownSummary[];
+}
+
+/**
+ * Build the `/cooldowns` payload: drop expired entries, tag each entry's
+ * scope, and compute when it lifts. Longest remaining cooldown comes first.
+ */
+export function buildCooldownsOutput(
+  entries: StoredCooldownEntry[],
+  cooldownDurationMs: number,
+  now: number = Date.now(),
+): CooldownsOutput {
+  const cooldowns = entries
+    .filter((entry) => now - entry.timestamp < cooldownDurationMs)
+    .map((entry): CooldownSummary => {
+      const modelId = entry.modelId ?? null;
+      const expiresAt = entry.timestamp + cooldownDurationMs;
+      return {
+        baseUrl: entry.baseUrl,
+        modelId,
+        scope: modelId === null ? "provider" : "model",
+        startedAt: entry.timestamp,
+        expiresAt,
+        remainingMs: Math.max(0, expiresAt - now),
+      };
+    })
+    .sort(
+      (a, b) =>
+        b.remainingMs - a.remainingMs ||
+        a.baseUrl.localeCompare(b.baseUrl) ||
+        (a.modelId ?? "").localeCompare(b.modelId ?? ""),
+    );
+
+  return {
+    now,
+    cooldownDurationMs,
+    count: cooldowns.length,
+    providerCount: new Set(cooldowns.map((entry) => entry.baseUrl)).size,
+    cooldowns,
+  };
+}
+
+/** Format a remaining-time value for the terminal, e.g. `2m 05s` or `42s`. */
+export function formatCooldownRemaining(ms: number): string {
+  const totalSeconds = Math.max(0, Math.ceil(ms / 1000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return minutes > 0
+    ? `${minutes}m ${String(seconds).padStart(2, "0")}s`
+    : `${seconds}s`;
+}
+
+/** Render a `/cooldowns` payload for `routstrd cooldowns`. */
+export function formatCooldowns(output: CooldownsOutput): string {
+  const windowSeconds = Math.round(output.cooldownDurationMs / 1000);
+  const heading = `Cooldowns (${windowSeconds}s window)`;
+
+  if (output.cooldowns.length === 0) {
+    return `${heading}\n\n  Nothing is on cooldown right now.`;
+  }
+
+  const scopeCell = (entry: CooldownSummary) =>
+    entry.scope === "provider" ? "PROVIDER" : "MODEL";
+  const urlWidth = Math.max(
+    ...output.cooldowns.map((entry) => entry.baseUrl.length),
+  );
+  const modelWidth = Math.max(
+    0,
+    ...output.cooldowns.map((entry) => (entry.modelId ?? "").length),
+  );
+
+  const lines = [
+    heading,
+    "",
+    `  ${output.count} active across ${output.providerCount} ${
+      output.providerCount === 1 ? "provider" : "providers"
+    }:`,
+    "",
+  ];
+
+  for (const entry of output.cooldowns) {
+    const cells = [scopeCell(entry).padEnd("PROVIDER".length), entry.baseUrl.padEnd(urlWidth)];
+    if (entry.scope === "model") {
+      cells.push((entry.modelId ?? "").padEnd(modelWidth));
+    }
+    lines.push(
+      `  ${cells.join("  ")}  expires in ${formatCooldownRemaining(entry.remainingMs)}`,
+    );
+  }
+
+  return lines.join("\n");
+}

package/src/utils/daemon-client.ts

@@ -56,6 +56,32 @@ class DaemonConnectionError extends Error {
   }
 }
 
+/**
+ * Upper bound for a single daemon request, including response-body
+ * consumption. The daemon bounds its own NWC operations, so this only guards
+ * against a wedged server; without it a hung request would block the CLI
+ * forever.
+ */
+export const DAEMON_REQUEST_TIMEOUT_MS = 120_000;
+
+/**
+ * Upper bound for value-moving wallet routes. A cashu melt/swap can
+ * legitimately run longer than {@link DAEMON_REQUEST_TIMEOUT_MS} (the mint has
+ * no request timeout in routstrd), so these get a more generous bound that
+ * still prevents an indefinite CLI hang.
+ */
+export const DAEMON_LONG_REQUEST_TIMEOUT_MS = 600_000;
+
+/** Routes that may legitimately outlive the default request timeout. */
+const LONG_RUNNING_ROUTES = ["/wallet/send/", "/wallet/receive/"];
+
+function requestTimeoutMs(path: string): number {
+  const pathname = path.split("?")[0] ?? path;
+  return LONG_RUNNING_ROUTES.some((route) => pathname.startsWith(route))
+    ? DAEMON_LONG_REQUEST_TIMEOUT_MS
+    : DAEMON_REQUEST_TIMEOUT_MS;
+}
+
 export function getDaemonBaseUrl(config: RoutstrdConfig): string {
   if (config.daemonUrl) {
     return config.daemonUrl.replace(/\/$/, "");
@@ -70,7 +96,7 @@ export function getAuthBaseUrl(config: RoutstrdConfig): string {
   return getDaemonBaseUrl(config);
 }
 
-async function _callUrl(
+export async function callDaemonUrl(
   baseUrl: string,
   path: string,
   options: { method?: "GET" | "POST" | "PATCH" | "DELETE"; body?: object },
@@ -99,23 +125,41 @@ async function _callUrl(
   if (authorization) headers.set("Authorization", authorization);
   if (bodyString) headers.set("Content-Type", "application/json");
 
+  const timeoutMs = requestTimeoutMs(path);
+  const timeoutError = () =>
+    new Error(
+      `Daemon request timed out after ${timeoutMs / 1000}s; ` +
+        "any payment outcome is unknown — check before retrying",
+    );
+  // The signal stays armed while the body is read, so a daemon that sends
+  // headers and then stalls the body cannot hang the CLI either. Aborting
+  // here never cancels the daemon's operation — see timeoutError's warning.
+  const signal = AbortSignal.timeout(timeoutMs);
+
   let response: Response;
   try {
     response = await fetch(url, {
       method,
       headers,
       body: bodyString,
+      signal,
     });
   } catch (error) {
+    if (signal.aborted) throw timeoutError();
+    // Only connection failures qualify for alternate-host retries.
     throw new DaemonConnectionError(error);
   }
 
-  if (!response.ok) {
-    const errorData = (await response.json()) as { error?: string };
-    throw new Error(errorData.error || `HTTP ${response.status}`);
+  try {
+    if (!response.ok) {
+      const errorData = (await response.json()) as { error?: string };
+      throw new Error(errorData.error || `HTTP ${response.status}`);
+    }
+    return (await response.json()) as CommandResponse;
+  } catch (error) {
+    if (signal.aborted) throw timeoutError();
+    throw error;
   }
-
-  return response.json() as Promise<CommandResponse>;
 }
 
 async function callLocalDaemon(
@@ -127,7 +171,7 @@ async function callLocalDaemon(
   let connectionError: DaemonConnectionError | undefined;
   for (const baseUrl of localDaemonBaseUrls(config)) {
     try {
-      return await _callUrl(baseUrl, path, options, config);
+      return await callDaemonUrl(baseUrl, path, options, config);
     } catch (error) {
       if (!(error instanceof DaemonConnectionError)) throw error;
       connectionError = error;
@@ -142,7 +186,7 @@ export async function callDaemon(
 ): Promise<CommandResponse> {
   const config = await loadConfig();
   if (config.daemonUrl) {
-    return _callUrl(getDaemonBaseUrl(config), path, options, config);
+    return callDaemonUrl(getDaemonBaseUrl(config), path, options, config);
   }
   return callLocalDaemon(path, options, config);
 }
@@ -157,7 +201,7 @@ export async function callAuth(
   if (!config.authUrl && !config.daemonUrl) {
     return callLocalDaemon(path, options, config);
   }
-  return _callUrl(getAuthBaseUrl(config), path, options, config);
+  return callDaemonUrl(getAuthBaseUrl(config), path, options, config);
 }
 
 export async function isDaemonRunning(): Promise<boolean> {

package/src/utils/history.ts

@@ -0,0 +1,9 @@
+/** Transaction types understood by the wallet history type filter. */
+export const HISTORY_ENTRY_TYPES = ["mint", "melt", "send", "receive"] as const;
+
+export type HistoryEntryType = (typeof HISTORY_ENTRY_TYPES)[number];
+
+/** True when `value` is a recognized history transaction type. */
+export function isHistoryEntryType(value: string): value is HistoryEntryType {
+  return (HISTORY_ENTRY_TYPES as readonly string[]).includes(value);
+}

package/src/utils/with-timeout.ts

@@ -0,0 +1,21 @@
+/**
+ * Rejects when `timeoutMs` elapses before `promise` settles.
+ * This bounds the caller's wait; it does not cancel the underlying operation.
+ *
+ * Used to bound requests that may otherwise wait forever — notably NWC calls
+ * whose underlying library applies its own timeout only after a support/encryption
+ * handshake that can itself hang on a stale relay subscription.
+ */
+export function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  message = "Operation timed out",
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(message)), timeoutMs);
+  });
+  return Promise.race([promise, timeout]).finally(() => {
+    if (timer !== undefined) clearTimeout(timer);
+  });
+}