@routedock/routedock 0.3.0 → 0.4.0

package/dist/logger-DVa7VT4c.d.cts

@@ -0,0 +1,41 @@
+/**
+ * Structured logging hook shared by the client and provider adapters.
+ *
+ * The SDK used to write straight to `console` in a couple of dozen error
+ * paths, which is unusable on structured-logging runtimes (Cloudflare Workers,
+ * Datadog, …) and untestable without spying on `console`. Every internal
+ * diagnostic now goes through a {@link RouteDockLogger}, so a consumer can
+ * silence it, redirect it, or attach correlation fields.
+ *
+ * The default implementation is console-backed, so behaviour is unchanged when
+ * no logger is supplied.
+ */
+/** Severity of a log line. */
+type RouteDockLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Structured context attached to a log line, typically `{ error: err }`. Sinks
+ * receive the values unresolved, so a serialising sink must project non-JSON
+ * values such as `Error` itself.
+ */
+type RouteDockLogFields = Record<string, unknown>;
+/**
+ * Consumer-supplied log sink.
+ *
+ * `fields` carries the structured payload (the error, the channel id, …) that
+ * a bare string would drop at the boundary.
+ */
+type RouteDockLogger = (level: RouteDockLogLevel, message: string, fields?: RouteDockLogFields) => void;
+/**
+ * Default logger that forwards to the console at the matching level. Field
+ * values are spread as additional console arguments so `console.error(msg, err)`
+ * spies (and existing log shippers) keep seeing the raw error object.
+ */
+declare function createConsoleLogger(): RouteDockLogger;
+/** Shared console-backed logger — the default when none is configured. */
+declare const consoleLogger: RouteDockLogger;
+/** Logger that discards every line. */
+declare const noopLogger: RouteDockLogger;
+/** Resolve an optional logger to a concrete sink, defaulting to `fallback`. */
+declare function resolveLogger(logger: RouteDockLogger | undefined, fallback?: RouteDockLogger): RouteDockLogger;
+
+export { type RouteDockLogFields as R, type RouteDockLogLevel as a, type RouteDockLogger as b, consoleLogger as c, createConsoleLogger as d, noopLogger as n, resolveLogger as r };

package/dist/logger-DVa7VT4c.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Structured logging hook shared by the client and provider adapters.
+ *
+ * The SDK used to write straight to `console` in a couple of dozen error
+ * paths, which is unusable on structured-logging runtimes (Cloudflare Workers,
+ * Datadog, …) and untestable without spying on `console`. Every internal
+ * diagnostic now goes through a {@link RouteDockLogger}, so a consumer can
+ * silence it, redirect it, or attach correlation fields.
+ *
+ * The default implementation is console-backed, so behaviour is unchanged when
+ * no logger is supplied.
+ */
+/** Severity of a log line. */
+type RouteDockLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Structured context attached to a log line, typically `{ error: err }`. Sinks
+ * receive the values unresolved, so a serialising sink must project non-JSON
+ * values such as `Error` itself.
+ */
+type RouteDockLogFields = Record<string, unknown>;
+/**
+ * Consumer-supplied log sink.
+ *
+ * `fields` carries the structured payload (the error, the channel id, …) that
+ * a bare string would drop at the boundary.
+ */
+type RouteDockLogger = (level: RouteDockLogLevel, message: string, fields?: RouteDockLogFields) => void;
+/**
+ * Default logger that forwards to the console at the matching level. Field
+ * values are spread as additional console arguments so `console.error(msg, err)`
+ * spies (and existing log shippers) keep seeing the raw error object.
+ */
+declare function createConsoleLogger(): RouteDockLogger;
+/** Shared console-backed logger — the default when none is configured. */
+declare const consoleLogger: RouteDockLogger;
+/** Logger that discards every line. */
+declare const noopLogger: RouteDockLogger;
+/** Resolve an optional logger to a concrete sink, defaulting to `fallback`. */
+declare function resolveLogger(logger: RouteDockLogger | undefined, fallback?: RouteDockLogger): RouteDockLogger;
+
+export { type RouteDockLogFields as R, type RouteDockLogLevel as a, type RouteDockLogger as b, consoleLogger as c, createConsoleLogger as d, noopLogger as n, resolveLogger as r };

package/dist/network.cjs

@@ -0,0 +1,57 @@
+'use strict';
+
+// src/network.ts
+var USDC_ISSUERS = {
+  testnet: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
+  mainnet: "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
+};
+var TESTNET_USDC_CONTRACT = "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA";
+var HORIZON_URLS = {
+  testnet: "https://horizon-testnet.stellar.org",
+  mainnet: "https://horizon.stellar.org"
+};
+function resolveNetwork(raw) {
+  return raw === "mainnet" ? "mainnet" : "testnet";
+}
+function resolveAssetContract(env, network) {
+  if (env.USDC_ASSET_CONTRACT) return env.USDC_ASSET_CONTRACT;
+  if (network === "testnet") return TESTNET_USDC_CONTRACT;
+  throw new Error("USDC_ASSET_CONTRACT is required for mainnet");
+}
+function findStellarConfigProblems(env, network) {
+  const problems = [];
+  if (!env.STELLAR_PAYEE_SECRET || !env.STELLAR_PAYEE_SECRET.startsWith("S")) {
+    problems.push("STELLAR_PAYEE_SECRET");
+  }
+  if (!env.STELLAR_PAYEE_ADDRESS) {
+    problems.push("STELLAR_PAYEE_ADDRESS");
+  }
+  if (network === "mainnet" && !env.USDC_ASSET_CONTRACT) {
+    problems.push("USDC_ASSET_CONTRACT");
+  }
+  return problems;
+}
+async function fetchXlmUsdcOrderBook(network, limit) {
+  const params = new URLSearchParams({
+    selling_asset_type: "native",
+    buying_asset_type: "credit_alphanum4",
+    buying_asset_code: "USDC",
+    buying_asset_issuer: USDC_ISSUERS[network],
+    limit: String(limit)
+  });
+  const response = await fetch(`${HORIZON_URLS[network]}/order_book?${params.toString()}`, {
+    headers: { accept: "application/json" }
+  });
+  if (!response.ok) {
+    throw new Error(`Horizon responded ${response.status}`);
+  }
+  return await response.json();
+}
+
+exports.HORIZON_URLS = HORIZON_URLS;
+exports.TESTNET_USDC_CONTRACT = TESTNET_USDC_CONTRACT;
+exports.USDC_ISSUERS = USDC_ISSUERS;
+exports.fetchXlmUsdcOrderBook = fetchXlmUsdcOrderBook;
+exports.findStellarConfigProblems = findStellarConfigProblems;
+exports.resolveAssetContract = resolveAssetContract;
+exports.resolveNetwork = resolveNetwork;

package/dist/network.d.cts

@@ -0,0 +1,72 @@
+/**
+ * Canonical Stellar network constants and the small helpers shared by the
+ * client, the provider middleware and the provider apps.
+ *
+ * Kept in its own entry point (`@routedock/routedock/network`) so Workers
+ * bundles can import it without pulling in the whole client or provider
+ * surface: plain constants plus one fetch-based helper, no Node APIs, no
+ * crypto. Before this module existed each app kept its own copy of the USDC
+ * issuer table, the testnet SAC and the Horizon URLs, and a mainnet change
+ * had to be made in three places (issue #578).
+ */
+/** Canonical Circle USDC issuers keyed by Stellar network. */
+declare const USDC_ISSUERS: {
+    readonly testnet: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5";
+    readonly mainnet: "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN";
+};
+type Network = keyof typeof USDC_ISSUERS;
+/** Well-known USDC stablecoin asset contract on testnet. */
+declare const TESTNET_USDC_CONTRACT = "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA";
+/** Horizon REST endpoints keyed by Stellar network. */
+declare const HORIZON_URLS: {
+    readonly testnet: "https://horizon-testnet.stellar.org";
+    readonly mainnet: "https://horizon.stellar.org";
+};
+/**
+ * Normalize a STELLAR_NETWORK-style string to a {@link Network}.
+ * Anything other than the exact string 'mainnet' falls back to testnet, the
+ * safe default.
+ */
+declare function resolveNetwork(raw: string | undefined): Network;
+/**
+ * Resolve the USDC asset contract for `network`: an explicit
+ * `USDC_ASSET_CONTRACT` always wins, testnet falls back to the well-known
+ * testnet SAC, and mainnet without one configured is a hard failure rather
+ * than a silently empty asset contract in the manifest.
+ */
+declare function resolveAssetContract(env: {
+    USDC_ASSET_CONTRACT?: string | undefined;
+}, network: Network): string;
+/** The env fields the shared config check understands. */
+interface StellarConfigEnv {
+    STELLAR_PAYEE_SECRET?: string | undefined;
+    STELLAR_PAYEE_ADDRESS?: string | undefined;
+    USDC_ASSET_CONTRACT?: string | undefined;
+}
+/**
+ * Return the names of environment variables that are unset or malformed.
+ * Values are never included — only names, so this is safe to log or return
+ * to a caller directly. Providers append their own extra requirements
+ * (channel contract, commitment key) to this shared base list.
+ */
+declare function findStellarConfigProblems(env: StellarConfigEnv, network: Network): string[];
+interface OrderBookLevel {
+    price: string;
+    amount: string;
+}
+interface XlmUsdcOrderBook {
+    asks: OrderBookLevel[];
+    bids: OrderBookLevel[];
+}
+/**
+ * Fetch the XLM/USDC orderbook straight from Horizon's REST API.
+ *
+ * The provider Express build used `Horizon.Server(...).orderbook(...)`, which
+ * pulls the whole `@stellar/stellar-sdk` (and axios) into the bundle for what
+ * is a single GET. Calling the endpoint keeps Workers bundles small and drops
+ * the dependency, while the issuer and Horizon URL come from the canonical
+ * tables above.
+ */
+declare function fetchXlmUsdcOrderBook(network: Network, limit: number): Promise<XlmUsdcOrderBook>;
+
+export { HORIZON_URLS, type Network, type OrderBookLevel, type StellarConfigEnv, TESTNET_USDC_CONTRACT, USDC_ISSUERS, type XlmUsdcOrderBook, fetchXlmUsdcOrderBook, findStellarConfigProblems, resolveAssetContract, resolveNetwork };

package/dist/network.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Canonical Stellar network constants and the small helpers shared by the
+ * client, the provider middleware and the provider apps.
+ *
+ * Kept in its own entry point (`@routedock/routedock/network`) so Workers
+ * bundles can import it without pulling in the whole client or provider
+ * surface: plain constants plus one fetch-based helper, no Node APIs, no
+ * crypto. Before this module existed each app kept its own copy of the USDC
+ * issuer table, the testnet SAC and the Horizon URLs, and a mainnet change
+ * had to be made in three places (issue #578).
+ */
+/** Canonical Circle USDC issuers keyed by Stellar network. */
+declare const USDC_ISSUERS: {
+    readonly testnet: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5";
+    readonly mainnet: "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN";
+};
+type Network = keyof typeof USDC_ISSUERS;
+/** Well-known USDC stablecoin asset contract on testnet. */
+declare const TESTNET_USDC_CONTRACT = "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA";
+/** Horizon REST endpoints keyed by Stellar network. */
+declare const HORIZON_URLS: {
+    readonly testnet: "https://horizon-testnet.stellar.org";
+    readonly mainnet: "https://horizon.stellar.org";
+};
+/**
+ * Normalize a STELLAR_NETWORK-style string to a {@link Network}.
+ * Anything other than the exact string 'mainnet' falls back to testnet, the
+ * safe default.
+ */
+declare function resolveNetwork(raw: string | undefined): Network;
+/**
+ * Resolve the USDC asset contract for `network`: an explicit
+ * `USDC_ASSET_CONTRACT` always wins, testnet falls back to the well-known
+ * testnet SAC, and mainnet without one configured is a hard failure rather
+ * than a silently empty asset contract in the manifest.
+ */
+declare function resolveAssetContract(env: {
+    USDC_ASSET_CONTRACT?: string | undefined;
+}, network: Network): string;
+/** The env fields the shared config check understands. */
+interface StellarConfigEnv {
+    STELLAR_PAYEE_SECRET?: string | undefined;
+    STELLAR_PAYEE_ADDRESS?: string | undefined;
+    USDC_ASSET_CONTRACT?: string | undefined;
+}
+/**
+ * Return the names of environment variables that are unset or malformed.
+ * Values are never included — only names, so this is safe to log or return
+ * to a caller directly. Providers append their own extra requirements
+ * (channel contract, commitment key) to this shared base list.
+ */
+declare function findStellarConfigProblems(env: StellarConfigEnv, network: Network): string[];
+interface OrderBookLevel {
+    price: string;
+    amount: string;
+}
+interface XlmUsdcOrderBook {
+    asks: OrderBookLevel[];
+    bids: OrderBookLevel[];
+}
+/**
+ * Fetch the XLM/USDC orderbook straight from Horizon's REST API.
+ *
+ * The provider Express build used `Horizon.Server(...).orderbook(...)`, which
+ * pulls the whole `@stellar/stellar-sdk` (and axios) into the bundle for what
+ * is a single GET. Calling the endpoint keeps Workers bundles small and drops
+ * the dependency, while the issuer and Horizon URL come from the canonical
+ * tables above.
+ */
+declare function fetchXlmUsdcOrderBook(network: Network, limit: number): Promise<XlmUsdcOrderBook>;
+
+export { HORIZON_URLS, type Network, type OrderBookLevel, type StellarConfigEnv, TESTNET_USDC_CONTRACT, USDC_ISSUERS, type XlmUsdcOrderBook, fetchXlmUsdcOrderBook, findStellarConfigProblems, resolveAssetContract, resolveNetwork };

package/dist/network.js

@@ -0,0 +1,49 @@
+// src/network.ts
+var USDC_ISSUERS = {
+  testnet: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
+  mainnet: "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
+};
+var TESTNET_USDC_CONTRACT = "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA";
+var HORIZON_URLS = {
+  testnet: "https://horizon-testnet.stellar.org",
+  mainnet: "https://horizon.stellar.org"
+};
+function resolveNetwork(raw) {
+  return raw === "mainnet" ? "mainnet" : "testnet";
+}
+function resolveAssetContract(env, network) {
+  if (env.USDC_ASSET_CONTRACT) return env.USDC_ASSET_CONTRACT;
+  if (network === "testnet") return TESTNET_USDC_CONTRACT;
+  throw new Error("USDC_ASSET_CONTRACT is required for mainnet");
+}
+function findStellarConfigProblems(env, network) {
+  const problems = [];
+  if (!env.STELLAR_PAYEE_SECRET || !env.STELLAR_PAYEE_SECRET.startsWith("S")) {
+    problems.push("STELLAR_PAYEE_SECRET");
+  }
+  if (!env.STELLAR_PAYEE_ADDRESS) {
+    problems.push("STELLAR_PAYEE_ADDRESS");
+  }
+  if (network === "mainnet" && !env.USDC_ASSET_CONTRACT) {
+    problems.push("USDC_ASSET_CONTRACT");
+  }
+  return problems;
+}
+async function fetchXlmUsdcOrderBook(network, limit) {
+  const params = new URLSearchParams({
+    selling_asset_type: "native",
+    buying_asset_type: "credit_alphanum4",
+    buying_asset_code: "USDC",
+    buying_asset_issuer: USDC_ISSUERS[network],
+    limit: String(limit)
+  });
+  const response = await fetch(`${HORIZON_URLS[network]}/order_book?${params.toString()}`, {
+    headers: { accept: "application/json" }
+  });
+  if (!response.ok) {
+    throw new Error(`Horizon responded ${response.status}`);
+  }
+  return await response.json();
+}
+
+export { HORIZON_URLS, TESTNET_USDC_CONTRACT, USDC_ISSUERS, fetchXlmUsdcOrderBook, findStellarConfigProblems, resolveAssetContract, resolveNetwork };

package/dist/node.cjs

@@ -0,0 +1,166 @@
+'use strict';
+
+var crypto = require('crypto');
+var fs = require('fs/promises');
+var path = require('path');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var fs__default = /*#__PURE__*/_interopDefault(fs);
+var path__default = /*#__PURE__*/_interopDefault(path);
+
+// src/store/FileSpendStore.ts
+var DEFAULT_LOCK_STALE_MS = 1e4;
+var DEFAULT_LOCK_TIMEOUT_MS = 15e3;
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var FileSpendStore = class {
+  filePath;
+  lockPath;
+  lockStaleMs;
+  lockTimeoutMs;
+  constructor(filePath, options = {}) {
+    this.filePath = filePath;
+    this.lockPath = `${filePath}.lock`;
+    this.lockStaleMs = options.lockStaleMs ?? DEFAULT_LOCK_STALE_MS;
+    this.lockTimeoutMs = options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+  }
+  async read() {
+    let data;
+    try {
+      data = await fs__default.default.readFile(this.filePath, "utf-8");
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        return null;
+      }
+      throw new Error(
+        `[FileSpendStore] Failed to read spend file at ${this.filePath}: ${err.message}`
+      );
+    }
+    try {
+      return JSON.parse(data);
+    } catch {
+      throw new Error(
+        `[FileSpendStore] Spend file at ${this.filePath} contains invalid JSON. Delete or repair it before resuming. Raw content: ${data.slice(0, 120)}`
+      );
+    }
+  }
+  async write(state) {
+    await this.withLock(async (assertHeld) => {
+      await this.writeFile(state, assertHeld);
+    });
+  }
+  /**
+   * Atomically read-modify-write the accumulator under the cross-process lock.
+   * `fn` receives the current state (or null) and returns the state to persist,
+   * or `undefined` to leave the file untouched. If `fn` throws, nothing is
+   * written and the lock is released.
+   */
+  async update(fn) {
+    return this.withLock(async (assertHeld) => {
+      const prev = await this.read();
+      const next = fn(prev);
+      if (next === void 0) return prev;
+      await this.writeFile(next, assertHeld);
+      return next;
+    });
+  }
+  // ── internals ──────────────────────────────────────────────────────────────
+  async writeFile(state, assertHeld) {
+    const tmpPath = `${this.filePath}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.tmp`;
+    try {
+      await fs__default.default.writeFile(tmpPath, JSON.stringify(state, null, 2), "utf-8");
+      await assertHeld();
+      await fs__default.default.rename(tmpPath, this.filePath);
+    } catch (err) {
+      await fs__default.default.rm(tmpPath, { force: true }).catch(() => {
+      });
+      throw err;
+    }
+  }
+  /** Run `fn` while holding the lock file; always releases it. */
+  async withLock(fn) {
+    await fs__default.default.mkdir(path__default.default.dirname(this.filePath), { recursive: true });
+    const token = `${process.pid}:${crypto.randomBytes(8).toString("hex")}`;
+    await this.acquireLock(token);
+    const heartbeat = setInterval(() => {
+      const now = /* @__PURE__ */ new Date();
+      fs__default.default.utimes(this.lockPath, now, now).catch(() => {
+      });
+    }, Math.max(10, Math.floor(this.lockStaleMs / 3)));
+    heartbeat.unref();
+    const assertHeld = async () => {
+      let current;
+      try {
+        current = await fs__default.default.readFile(this.lockPath, "utf-8");
+      } catch {
+        current = "";
+      }
+      if (current !== token) {
+        throw new Error(
+          `[FileSpendStore] Lost the lock on ${this.lockPath} before committing; refusing to overwrite the spend file. Retry the operation.`
+        );
+      }
+    };
+    try {
+      return await fn(assertHeld);
+    } finally {
+      clearInterval(heartbeat);
+      await this.releaseLock(token);
+    }
+  }
+  async acquireLock(token) {
+    const deadline = Date.now() + this.lockTimeoutMs;
+    let delay = 5;
+    for (; ; ) {
+      try {
+        const handle = await fs__default.default.open(this.lockPath, "wx");
+        try {
+          await handle.writeFile(token, "utf-8");
+        } finally {
+          await handle.close();
+        }
+        return;
+      } catch (err) {
+        if (err.code !== "EEXIST") {
+          throw new Error(
+            `[FileSpendStore] Failed to create lock file ${this.lockPath}: ${err.message}`
+          );
+        }
+      }
+      await this.breakIfStale();
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `[FileSpendStore] Timed out after ${this.lockTimeoutMs}ms waiting for ${this.lockPath}. Another process is holding the spend file lock; if none is running, delete the lock file.`
+        );
+      }
+      await sleep(delay + Math.floor(Math.random() * delay));
+      delay = Math.min(delay * 2, 50);
+    }
+  }
+  /** Remove the lock if its holder stopped refreshing it (crashed process). */
+  async breakIfStale() {
+    let before;
+    try {
+      before = await fs__default.default.stat(this.lockPath);
+    } catch {
+      return;
+    }
+    if (Date.now() - before.mtimeMs <= this.lockStaleMs) return;
+    try {
+      const after = await fs__default.default.stat(this.lockPath);
+      if (after.ino !== before.ino || after.mtimeMs !== before.mtimeMs) return;
+      await fs__default.default.unlink(this.lockPath);
+    } catch {
+    }
+  }
+  async releaseLock(token) {
+    try {
+      if (await fs__default.default.readFile(this.lockPath, "utf-8") === token) {
+        await fs__default.default.unlink(this.lockPath);
+      }
+    } catch {
+    }
+  }
+};
+
+exports.FileSpendStore = FileSpendStore;

package/dist/node.d.cts

@@ -0,0 +1,77 @@
+import { S as SpendStore, D as DailySpend } from './SpendStore-s_dfcemj.cjs';
+import './logger-DVa7VT4c.cjs';
+
+/** Tuning for the cross-process lock that guards read-modify-write. */
+interface FileSpendStoreOptions {
+    /**
+     * A lock file whose mtime is older than this is treated as left behind by a
+     * crashed process and broken. A live holder refreshes it, so this only needs
+     * to exceed the refresh interval. Default 10 000 ms.
+     */
+    lockStaleMs?: number;
+    /**
+     * How long to wait for the lock before giving up. A spend cap must fail
+     * closed, so a timeout rejects instead of proceeding unlocked. Must be longer
+     * than `lockStaleMs` to survive a crashed holder. Default 15 000 ms.
+     */
+    lockTimeoutMs?: number;
+}
+/**
+ * File-backed durable {@link SpendStore}.
+ *
+ * Persists the daily spend accumulator to a JSON file on disk, preserving
+ * cumulative spending totals across process restarts, crashes, and redeploys.
+ *
+ * ### Error semantics
+ * - File absent (ENOENT): returns null — legitimately no spend recorded yet.
+ * - File present but unreadable or malformed: throws — a safety control must
+ *   fail closed, not assume nothing was spent.
+ *
+ * ### Write atomicity
+ * Writes go to a tmp file that is unique per write (`<filePath>.<pid>.<random>.tmp`),
+ * then `fs.rename` onto the target. `rename` is atomic within a filesystem, so
+ * there is no window where the target file is truncated but not yet fully
+ * written, and two writers can never share (and clobber, or `ENOENT` on) one
+ * tmp file.
+ *
+ * ### Sharing the file between processes
+ * `read()` + `write()` alone is not enough when several processes use the same
+ * file (the MCP server and the E2E agent both default to
+ * `~/.routedock/spend.json`): both can read the same total and both write back
+ * `total + amount`. {@link FileSpendStore.update} closes that race — it holds an
+ * exclusive lock file (`<filePath>.lock`, created with `O_EXCL`) across the
+ * read, the callback and the write, and `RouteDockClient` uses it automatically.
+ * `write()` takes the same lock, so every mutation is serialized.
+ *
+ * The lock is advisory and file-based: it works for processes on one machine
+ * (and on filesystems with working `O_EXCL`), not for a file on a flaky network
+ * share. A lock whose mtime goes stale (crashed holder) is broken after
+ * `lockStaleMs`; a live holder keeps refreshing it. If the lock cannot be
+ * acquired within `lockTimeoutMs`, the call rejects — it never proceeds
+ * unlocked.
+ */
+declare class FileSpendStore implements SpendStore {
+    readonly filePath: string;
+    private readonly lockPath;
+    private readonly lockStaleMs;
+    private readonly lockTimeoutMs;
+    constructor(filePath: string, options?: FileSpendStoreOptions);
+    read(): Promise<DailySpend | null>;
+    write(state: DailySpend): Promise<void>;
+    /**
+     * Atomically read-modify-write the accumulator under the cross-process lock.
+     * `fn` receives the current state (or null) and returns the state to persist,
+     * or `undefined` to leave the file untouched. If `fn` throws, nothing is
+     * written and the lock is released.
+     */
+    update(fn: (prev: DailySpend | null) => DailySpend | undefined): Promise<DailySpend | null>;
+    private writeFile;
+    /** Run `fn` while holding the lock file; always releases it. */
+    private withLock;
+    private acquireLock;
+    /** Remove the lock if its holder stopped refreshing it (crashed process). */
+    private breakIfStale;
+    private releaseLock;
+}
+
+export { FileSpendStore, type FileSpendStoreOptions };

package/dist/node.d.ts

@@ -0,0 +1,77 @@
+import { S as SpendStore, D as DailySpend } from './SpendStore-BUclV02i.js';
+import './logger-DVa7VT4c.js';
+
+/** Tuning for the cross-process lock that guards read-modify-write. */
+interface FileSpendStoreOptions {
+    /**
+     * A lock file whose mtime is older than this is treated as left behind by a
+     * crashed process and broken. A live holder refreshes it, so this only needs
+     * to exceed the refresh interval. Default 10 000 ms.
+     */
+    lockStaleMs?: number;
+    /**
+     * How long to wait for the lock before giving up. A spend cap must fail
+     * closed, so a timeout rejects instead of proceeding unlocked. Must be longer
+     * than `lockStaleMs` to survive a crashed holder. Default 15 000 ms.
+     */
+    lockTimeoutMs?: number;
+}
+/**
+ * File-backed durable {@link SpendStore}.
+ *
+ * Persists the daily spend accumulator to a JSON file on disk, preserving
+ * cumulative spending totals across process restarts, crashes, and redeploys.
+ *
+ * ### Error semantics
+ * - File absent (ENOENT): returns null — legitimately no spend recorded yet.
+ * - File present but unreadable or malformed: throws — a safety control must
+ *   fail closed, not assume nothing was spent.
+ *
+ * ### Write atomicity
+ * Writes go to a tmp file that is unique per write (`<filePath>.<pid>.<random>.tmp`),
+ * then `fs.rename` onto the target. `rename` is atomic within a filesystem, so
+ * there is no window where the target file is truncated but not yet fully
+ * written, and two writers can never share (and clobber, or `ENOENT` on) one
+ * tmp file.
+ *
+ * ### Sharing the file between processes
+ * `read()` + `write()` alone is not enough when several processes use the same
+ * file (the MCP server and the E2E agent both default to
+ * `~/.routedock/spend.json`): both can read the same total and both write back
+ * `total + amount`. {@link FileSpendStore.update} closes that race — it holds an
+ * exclusive lock file (`<filePath>.lock`, created with `O_EXCL`) across the
+ * read, the callback and the write, and `RouteDockClient` uses it automatically.
+ * `write()` takes the same lock, so every mutation is serialized.
+ *
+ * The lock is advisory and file-based: it works for processes on one machine
+ * (and on filesystems with working `O_EXCL`), not for a file on a flaky network
+ * share. A lock whose mtime goes stale (crashed holder) is broken after
+ * `lockStaleMs`; a live holder keeps refreshing it. If the lock cannot be
+ * acquired within `lockTimeoutMs`, the call rejects — it never proceeds
+ * unlocked.
+ */
+declare class FileSpendStore implements SpendStore {
+    readonly filePath: string;
+    private readonly lockPath;
+    private readonly lockStaleMs;
+    private readonly lockTimeoutMs;
+    constructor(filePath: string, options?: FileSpendStoreOptions);
+    read(): Promise<DailySpend | null>;
+    write(state: DailySpend): Promise<void>;
+    /**
+     * Atomically read-modify-write the accumulator under the cross-process lock.
+     * `fn` receives the current state (or null) and returns the state to persist,
+     * or `undefined` to leave the file untouched. If `fn` throws, nothing is
+     * written and the lock is released.
+     */
+    update(fn: (prev: DailySpend | null) => DailySpend | undefined): Promise<DailySpend | null>;
+    private writeFile;
+    /** Run `fn` while holding the lock file; always releases it. */
+    private withLock;
+    private acquireLock;
+    /** Remove the lock if its holder stopped refreshing it (crashed process). */
+    private breakIfStale;
+    private releaseLock;
+}
+
+export { FileSpendStore, type FileSpendStoreOptions };