@ninsei-labs/sdk 0.39.0

package/src/config.mjs

@@ -0,0 +1,277 @@
+// SDK CONFIGURATION: networks, tokens, thresholds - the engine's data, not the interface's constants.
+//
+// THE SETTLEMENT NETWORK IS NAMED BY THE PAIR "network + virtual machine": vm already lives in the engine's
+// network registry (`vm: "evm" | "bitcoin" | "solana" | "tron"`), and the SDK does not invent it anew. If there
+// is no leg driver for a vm, the call does not "quietly assume EVM" - it answers with a code naming what is
+// already supported: so adding Tron or Solana will not require edits in the quotes, the Monero leg and the state
+// machine.
+import * as engine from "./engine.mjs";
+import { CHECK_CODES, ERROR_CODES, STEP_CODES } from "./codes.mjs";
+import { fail } from "./errors.mjs";
+import { implementedVms, legFor } from "./legs/index.mjs";
+import { routeProviders } from "./legs/evm.mjs";
+
+// TOKENS ARE TAKEN BY AN ENGINE FUNCTION, NOT FROM A NETWORK FIELD: `tokensOf` returns the native coin first,
+// followed by the declared tokens - exactly the list the interface should show. The identifier is the lowercase
+// symbol ("usdc"), the same one used in quotes and in API paths.
+// TOKENS ARE TAKEN BY NETWORK IDENTIFIER AND WITHOUT A SILENT DEFAULT.
+//
+// The engine's `tokensOf` looks the network up by slug (`chainById`), and when it does not find it, it SILENTLY
+// returns the default network (`DEFAULT_CHAIN`). For the interface that makes sense: showing the default network
+// is better than showing emptiness. The core must not do that. A call `tokensOf(chain.chainId)` once stood here -
+// a NUMBER where a slug is expected: the network was never found, and the answer was assigned the tokens of
+// ANOTHER network, while the `id` field held the correct network identifier. The error was invisible: the list
+// looked plausible on an unknown network too.
+//
+// So the network is looked up by number honestly, absence is a refusal, and additionally it is VERIFIED that the
+// list belongs to exactly this network: if the engine ever substitutes the default network again, this will show
+// up here, not in a swap that went to the wrong network.
+const tokensOfNetwork = (chainId) => {
+  const network = typeof engine.config.chainByChainId === "function" ? engine.config.chainByChainId(chainId) : null;
+  if (!network) fail("bad-input", { field: "chain.chainId", unknown: chainId, why: "no-network-with-this-chainId" });
+  const got = engine.config.tokensOf(network.id);
+  const own = [network.native, ...(network.tokens || [])].filter(Boolean);
+  const asId = (t) => String(t.symbol).toLowerCase();
+  if (got.map(asId).join("|") !== own.map(asId).join("|")) {
+    fail("bad-input", { field: "chain.tokens", unknown: chainId, why: "tokens-belong-to-another-network" });
+  }
+  return got;
+};
+
+const chainConfig = (chain) => ({
+  id: chain.id,
+  name: chain.name,
+  vm: chain.vm || "evm",
+  chainId: chain.chainId,
+  nativeSymbol: chain.native && chain.native.symbol ? chain.native.symbol : null,
+  tokens: tokensOfNetwork(chain.chainId).map((t) => ({
+    id: String(t.symbol).toLowerCase(),
+    symbol: String(t.symbol),
+    address: t.address || null,
+    decimals: Number(t.decimals),
+  })),
+  dex: chain.dex ? { routes: chain.dex.routes || [] } : null,
+});
+
+// --- ADDRESSES AND PATHS THAT ARE SUPPLIED FROM OUTSIDE ------------------------------------
+//
+// The default is OUR service and our explorers: everything the engine already knows. Options can name others:
+// your own API, your own node, a third-party explorer, a different set of paths. This matters to whoever runs
+// the swap for themselves, not to whoever uses it, so it lives in options, not in the interface.
+//
+// A RULE THAT IS NOT UP FOR DISCUSSION: ADDRESSES are configurable, not CHECKS. Your own API, your own node,
+// your own explorer - fine. But the pre-signature guards (the price is not market, the amount is covered, the
+// token allowance, the deadlines from the chain) stay enabled under any configuration: otherwise "maximum
+// configurability" would become a way to switch the checks off with a single field, which is exactly what the
+// core exists to prevent.
+//
+// PATHS ARE NAMED BY NAMES, NOT BY STRINGS IN CODE. `route("swept", { id })` substitutes the value and encodes
+// it; the path holds `{id}`. So changing the host or using a third-party server is an edit of an object, not an
+// edit of the core.
+// WHY THESE PATHS DID NOT EXIST BEFORE AND WHERE THEY COME FROM. The "server" step (recording the swap with us
+// and watching the Monero address) is done with THE SAME requests as the current interface, so the paths are
+// named after its calls, not invented: the watch state - GET /swaps/{id} (www/js/core/chainSource.js:184,
+// fetchSession), the factory record of a swap - POST /evm-swaps (www/js/evm/auth.js:111, saveServerSwap; in app
+// the full path /api/evm-swaps is declared by the template /^\/api\/evm-swaps$/ in app/server.mjs:1230).
+export const DEFAULT_ROUTES = Object.freeze({
+  swaps: "/swaps",
+  swap: "/swaps/{id}",
+  evmSwaps: "/evm-swaps",
+  // A quote for an order: the provider's commitment under keys, not a market snapshot.
+  orderQuote: "/order-quote",
+  revealedHalf: "/escrow/revealed-half",
+  swept: "/swaps/{id}/swept",
+});
+
+// THE MONERO NODES THE ARRIVAL IS CHECKED AGAINST. Defaults are the list verified on 2026-10-02 (issue #85):
+// mainnet - four public nodes of different operators; stagenet - our node and the one independent public node.
+// `ready` opens only when two nodes of DIFFERENT operators agree on the block (see sdk/src/xmr-arrival.mjs), so
+// the list is a list of WITNESSES, not of equal endpoints.
+//
+// OVERRIDABLE BY THE INTERFACE AND THE USER: `options.nodes` replaces the list (an array for the chosen network,
+// or an object keyed by network) and `options.addNodes` appends to the defaults (that is how a user adds their
+// own node). The checks themselves are not configurable - only the addresses.
+export const DEFAULT_XMR_NODES = Object.freeze({
+  mainnet: [
+    { url: "https://xmr-node.cakewallet.com:18081", operator: "Cake Wallet" },
+    { url: "https://xmr.cryptostorm.is", operator: "cryptostorm" },
+    { url: "https://node.monero.fail", operator: "monero.fail" },
+    { url: "https://mainnet.xmr.kernal.eu:18089", operator: "kernal.eu" },
+  ],
+  stagenet: [
+    { url: "https://xmr.arrakisswap.trade", operator: "arrakisswap" },
+    { url: "https://stagenet.xmr.kernal.eu:38089", operator: "kernal.eu" },
+  ],
+});
+
+const nodeEntryOk = (raw) => (typeof raw === "string" && raw)
+  || (raw && typeof raw === "object" && typeof raw.url === "string" && raw.url);
+const nodesArrayOk = (a) => Array.isArray(a) && a.every(nodeEntryOk);
+
+// The resolved node map: the defaults, then the overrides. An unknown network key is a typo, not a silent no-op.
+const nodesOf = (options, selected) => {
+  const custom = options && options.nodes;
+  const extra = options && options.addNodes;
+  const out = { mainnet: [...DEFAULT_XMR_NODES.mainnet], stagenet: [...DEFAULT_XMR_NODES.stagenet] };
+  if (custom !== undefined && custom !== null) {
+    if (nodesArrayOk(custom)) {
+      if (!(selected in out)) fail("bad-input", { field: "nodes", network: selected });
+      out[selected] = [...custom];
+    } else if (custom && typeof custom === "object" && !Array.isArray(custom)) {
+      for (const name of Object.keys(custom)) {
+        if (!(name in out)) fail("bad-input", { field: "nodes", unknown: name, known: Object.keys(out) });
+        if (!nodesArrayOk(custom[name])) fail("bad-input", { field: "nodes." + name });
+        out[name] = [...custom[name]];
+      }
+    } else fail("bad-input", { field: "nodes" });
+  }
+  if (extra !== undefined && extra !== null) {
+    if (!nodesArrayOk(extra)) fail("bad-input", { field: "addNodes" });
+    if (!(selected in out)) fail("bad-input", { field: "addNodes", network: selected });
+    out[selected] = [...out[selected], ...extra];
+  }
+  return out;
+};
+
+const pathOf = (template, params) => template.replace(/\{([a-z]+)\}/g, (whole, name) => {
+  const value = params ? params[name] : undefined;
+  if (value === undefined || value === null || value === "") fail("bad-input", { field: "route.param", param: name });
+  return encodeURIComponent(String(value));
+});
+
+const routesOf = (options) => {
+  const custom = (options && options.routes) || {};
+  for (const name of Object.keys(custom)) {
+    // AN UNKNOWN NAME IS A TYPO, NOT "let's add our own": otherwise the path silently fails to apply, and the
+    // call falls back to a default nobody knows about.
+    if (!(name in DEFAULT_ROUTES)) fail("bad-input", { field: "routes", unknown: name, known: Object.keys(DEFAULT_ROUTES) });
+    if (typeof custom[name] !== "string" || !custom[name]) fail("bad-input", { field: "routes." + name });
+  }
+  return { ...DEFAULT_ROUTES, ...custom };
+};
+
+// THE POLL RATE AND TIMEOUT FOR WATCHING THE MONERO ADDRESS. The defaults come from the engine's settings, not
+// from numbers in the code: the rate is the same as the page's (www/js/core/chainSource.js, pollInterval =
+// API.pollMs), and the timeout is from the Monero timings (blockTimeReal x confirmTarget): that is how long it
+// takes to gather the confirmations of the target, and declaring the wait expired before that would be lying
+// about the money. Both numbers are overridable by the `watch` option.
+const positive = (v) => (Number.isFinite(Number(v)) && Number(v) > 0 ? Number(v) : null);
+const watchOf = (options) => {
+  const w = (options && options.watch) || {};
+  const pollMs = w.pollMs === undefined ? (positive(engine.config.API && engine.config.API.pollMs) || 5000) : Number(w.pollMs);
+  if (!Number.isFinite(pollMs) || pollMs <= 0) fail("bad-input", { field: "watch.pollMs" });
+  const monero = engine.config.MONERO || {};
+  const fallback = (positive(monero.blockTimeReal) || 120000) * (positive(monero.confirmTarget) || 10);
+  const timeoutMs = w.timeoutMs === undefined ? fallback : Number(w.timeoutMs);
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) fail("bad-input", { field: "watch.timeoutMs" });
+  return { pollMs, timeoutMs };
+};
+
+const endpointsOf = (raw, options) => {
+  const e = (options && options.endpoints) || {};
+  const explorer = e.explorer || {};
+  const rpc = e.rpc || {};
+  const text = (v) => (typeof v === "string" && v ? v : null);
+  return {
+    explorer: {
+      evmTx: text(explorer.evmTx) || text(raw.explorerTx),
+      evmAddr: text(explorer.evmAddr) || text(raw.explorerAddr),
+      evmName: text(explorer.evmName) || text(raw.explorerName),
+      // The engine builds the Monero explorer from the swap's network; here you can supply your own template with `{tx}`.
+      xmrTx: text(explorer.xmrTx),
+    },
+    rpc: {
+      // The EVM node: for the engine it serves as a parameter for wallet_addEthereumChain, for the core as the
+      // read address if the leg driver talks to it itself. Overriding is allowed, but the network and the
+      // contract addresses must change together: changing the node without the network produces refusals that
+      // look like a code error (that is why chainId is checked separately and that check is not configurable).
+      evm: text(rpc.evm) || text(raw.rpcUrl),
+      monero: text(rpc.monero),
+    },
+  };
+};
+
+export function buildConfig(options) {
+  const chains = engine.config.CHAINS.map(chainConfig);
+  const chosen = chains.find((c) => c.id === options.settlement.chain) || null;
+  if (!chosen) fail("bad-input", { field: "settlement.chain", known: chains.map((c) => c.id) });
+  const rawChain = engine.config.CHAINS.find((c) => c.id === options.settlement.chain) || {};
+  const routes = routesOf(options);
+  const watch = watchOf(options);
+  const endpoints = endpointsOf(rawChain, options);
+  const nodes = nodesOf(options, options.xmrNetwork);
+  const vm = options.settlement.vm || chosen.vm;
+  if (!vm) fail("bad-input", { field: "settlement.vm" });
+  if (vm !== chosen.vm) fail("bad-input", { field: "settlement.vm", chain: chosen.id, vm: chosen.vm, got: vm });
+  const leg = legFor(vm);
+  if (!leg) fail("not-implemented", { surface: "settlement.vm", vm, implemented: implementedVms() });
+
+  // ROUTE PROVIDERS: our declared routes today, an external aggregator when it arrives. The choice comes through
+  // options and is checked against the registry: an unknown provider is a typo, not "we'll try and see".
+  // One beating another is decided by an explicit order, not by response speed: otherwise the price would change
+  // based on who made it over the network first.
+  const known = routeProviders();
+  const prefer = Array.isArray(options.routing && options.routing.prefer) && options.routing.prefer.length
+    ? options.routing.prefer.map((id) => String(id))
+    : known.filter((id) => id === "declared");
+  for (const id of prefer) {
+    if (!known.includes(id)) fail("bad-input", { field: "routing.prefer", unknown: id, known });
+  }
+
+  // MONERO NETWORKS THE CORE KNOWS. The engine's registry declares only the one the demo is configured for
+  // (XMR_NETWORKS: stagenet). But the SDK contract (index.d.ts, xmrNetwork) names THREE standard names -
+  // mainnet/stagenet/testnet - and that is not about the demo: the withdrawal page takes the network FROM THE
+  // NODE, and on a production network its network is mainnet, not a typo. So three standard ones are added to
+  // the declared ones; anything else is still a refusal with the known list.
+  const STANDARD_XMR_NETWORKS = ["mainnet", "stagenet", "testnet"];
+  const xmrNetworks = [...new Set([...Object.values(engine.config.XMR_NETWORKS || {}), ...STANDARD_XMR_NETWORKS])];
+  if (!xmrNetworks.includes(options.xmrNetwork)) {
+    fail("bad-input", { field: "xmrNetwork", known: xmrNetworks });
+  }
+  const guards = engine.config.SIGNING_GUARDS || {};
+  return {
+    settlement: { chain: chosen, vm },
+    chains,
+    xmrNetworks,
+    assetsBase: options.assetsBase,
+    apiBase: options.apiBase,
+    mode: options.mode,
+    limits: {
+      // SIZE LIMITS COME WITH THE LIVE QUOTE, NOT FROM A FILE: the provider node declares them, and different
+      // nodes have different ones. While there is no quote, the honest value is null, not an invented number.
+      minAmount: null,
+      maxAmount: null,
+      stepAmount: null,
+      xmrConfirmTarget: engine.config.MONERO.confirmTarget ?? null,
+      // WATCH POLLING: the values above (engine settings or the `watch` option).
+      watchPollMs: watch.pollMs,
+      watchTimeoutMs: watch.timeoutMs,
+      // HOW MANY CONFIRMATIONS BEFORE `ready` - a NUMBER IN THE CONFIGURATION so it changes in one place. The
+      // default is the engine's target (10 blocks ~ 20 minutes at 2-minute blocks, the owner's decision). The
+      // confirmation window must fit before the ready deadline, or a hopeless trade would start - see
+      // xmr-arrival.mjs (assertTimeForConfirmations) and SIGNING_GUARDS.minReadyLeadSec under www/js.
+      xmrConfirmations: engine.config.MONERO.confirmTarget ?? 10,
+      xmrBlockTimeSec: Math.round((engine.config.MONERO.blockTimeReal ?? 120000) / 1000),
+      readyLeadWarnSec: guards.readyLeadWarnSec ?? null,
+      // THE PRICE POLL RATE AND THE REQUEST TIMEOUT - from the engine's settings, not from numbers in the SDK:
+      // two numbers in two places would silently diverge, and polling would become more frequent than the
+      // backend allows.
+      quotePollMs: engine.config.API.pollMs ?? 5000,
+      httpTimeoutMs: engine.config.API.timeoutMs ?? 20000,
+    },
+    routing: { providers: known, prefer },
+    // NAMED PATHS AND ADDRESSES: `route` substitutes parameters, `endpoints` carries the already-resolved values
+    // (the default from the registry, the override from the options).
+    routes: { ...routes },
+    endpoints,
+    // THE NODES THE XMR ARRIVAL IS CHECKED AGAINST - by network, with the defaults from the verified list and any
+    // overrides the caller (or the user) brought. `nodesFor` is the pick for one network.
+    xmrNodes: nodes,
+    nodesFor: (network) => (nodes && nodes[network]) ? nodes[network] : [],
+    route: (name, params) => {
+      if (!(name in routes)) fail("bad-input", { field: "route", unknown: name, known: Object.keys(routes) });
+      return pathOf(routes[name], params);
+    },
+    codes: { steps: STEP_CODES, checks: CHECK_CODES, errors: ERROR_CODES },
+  };
+}

package/src/engine.mjs

@@ -0,0 +1,53 @@
+// THE ENGINE SEAM, NOW SELF-CONTAINED.
+//
+// The engine modules the core depends on are mirrored under sdk/engine/ - byte-for-byte copies kept in
+// sync by tools/build-sdk-engine.mjs and guarded by tools/check-sdk-engine.mjs. This file is the ONLY
+// place that knows where the engine lives; no other SDK module does.
+//
+// WHY A VERIFIED MIRROR, NOT A MOVE. The very same modules are loaded by the demo page in the browser
+// (www/js), and the production web root is www/ alone - the sdk/ directory is not served there (see
+// tools/serve.mjs). Lifting the files out of www/js would 404 every engine import on the live site, and
+// dozens of repository checks read those sources by their www/js path. So the single source of truth
+// stays www/js and the SDK carries a copy: any drift reddens check-sdk-engine, so it cannot diverge
+// silently (the same rule build-sweep uses for the sweep/rfq copies).
+//
+// The mirror is generated - never edit sdk/engine/ by hand. Change www/js, then run:
+//   node tools/build-sdk-engine.mjs
+export * as config from "../engine/core/config.js";
+export * as guards from "../engine/core/preSignGuards.js";
+export * as restore from "../engine/recovery/restore.js";
+// STORES - THROUGH THIS SAME SEAM. Both modules take an adapter from outside (get/set/remove), and by default
+// use web storage if it is present: without an adapter they run in memory rather than fail on a missing DOM.
+export * as store from "../engine/core/store.js";
+export * as auth from "../engine/evm/auth.js";
+export * as swap from "../engine/core/swap.js";
+export * as recoveryFile from "../engine/recovery/recoveryFile.js";
+export * as halves from "../engine/atomic/halves.js";
+export * as orderContext from "../engine/atomic/orderContext.js";
+export * as order from "../engine/atomic/order.js";
+// HALF TRANSFER: the byte format and opening are the very same ones the page worker uses
+// (www/js/atomic/order-worker.js). The core keeps no copy of the format: the commitment is computed over those
+// exact bytes, and a second copy would silently drift from the calldata.
+export * as halfenc from "../engine/atomic/halfenc.js";
+// The engine's EVM layer: talking to the chain (order terms, sending, reading) - through this seam.
+export * as evm from "../engine/evm/index.js";
+// THE DEAL ENGINE NO LONGER LIVES IN www/js (#32, wave 3): the order flow moved into the package
+// (sdk/src/swap-flow.mjs) and is declared in sdk/index.d.ts. The page reaches it through the bridge, so the
+// mirror no longer carries core/swap-flow.js - what stays in the seam is the ORDER CLIENT (the half worker),
+// the ORDER QUOTE source and the shared CLAIM GAS LIMIT that the moved flow reads through this same seam.
+export * as orderClient from "../engine/atomic/order-client.js";
+export * as rfqSource from "../engine/core/rfqSource.js";
+export * as claimGas from "../engine/evm/claimGas.js";
+export * as escrow from "../engine/evm/escrow.js";
+export * as halvesSweep from "../engine/monero/halvesSweep.js";
+// MONERO ADDRESSES - THROUGH THE SAME MODULE THE DEMO USES. The format, the network prefixes and the address
+// check live in www/js/monero/address.js (checkAddress: base58 + keccak256 + network), and the page uses it
+// too. The wallet adapter needs exactly networkFromShape: its own address must belong to the network named by
+// the core, and that is checked by the same code, not by a private prefix table.
+export * as xmrAddress from "../engine/monero/address.js";
+// THE unlock_time RULE AND THE BLOCK READER - FROM THE SAME MIRROR, NOT A COPY. A second copy of "the output
+// is barred until a boundary" would be a second truth about money, so the rule lives under www/js
+// (monero/unlock.js) together with the Monero block parser (monero/scan.js), and the SDK reads them through
+// the engine mirror. check-sdk-engine reddens on any drift, so the two cannot diverge silently.
+export * as xmrUnlock from "../engine/monero/unlock.js";
+export * as xmrScan from "../engine/monero/scan.js";

package/src/errors.mjs

@@ -0,0 +1,24 @@
+// SDK ERRORS: a code plus params, with no human-facing text.
+//
+// message is deliberately equal to the code: it is read by logs and tests. The interface must do the
+// showing, taking the code and params - otherwise the wording would end up in the core, with nowhere left
+// to translate it.
+
+export class SdkError extends Error {
+  constructor(code, params = {}) {
+    super(code);
+    this.name = "SdkError";
+    this.code = code;
+    this.params = params;
+  }
+  toJSON() {
+    return { code: this.code, params: this.params };
+  }
+}
+
+export const fail = (code, params) => {
+  throw new SdkError(code, params);
+};
+
+// Refusal as a value: part of the SDK returns a refusal state instead of throwing (the quote snapshot, a guard verdict).
+export const refusal = (code, params = {}) => ({ ok: false, error: { code, params } });

package/src/http.mjs

@@ -0,0 +1,72 @@
+// THE SDK TRANSPORT: the API address and the fetch function COME FROM OUTSIDE.
+//
+// Why not a global fetch: the interface lives in different environments (browser, SSR, tests, later a mobile
+// app), and requiring a global fetch of it would mean dictating its environment. Besides, the timeout and the
+// response parsing must live in one place rather than in every call: otherwise one call forgets the timeout and
+// another forgets the status-code check, and a network refusal looks like an empty market.
+import { SdkError } from "./errors.mjs";
+
+const defaultFetch = () => (typeof fetch === "function" ? fetch : null);
+
+export function createHttp({ apiBase, fetchImpl = null, timeoutMs = 20_000 }) {
+  const impl = fetchImpl || defaultFetch();
+  return {
+    /** The response as data. A network refusal and a non-2xx are a code, not a transport exception. */
+    // METHOD, HEADERS AND BODY ARE PASSED FROM OUTSIDE: without that a POST with a body would silently leave as
+    // a GET, and the service would answer with a refusal to a request it did not understand. The defaults are
+    // the previous ones (GET without a body).
+    async json(path, { signal = null, method = "GET", headers = null, body = null } = {}) {
+      if (typeof impl !== "function") throw new SdkError("bad-input", { field: "fetch" });
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+      const abort = () => ctrl.abort();
+      if (signal) signal.addEventListener("abort", abort, { once: true });
+      try {
+                const init = { signal: ctrl.signal, method, headers: { accept: "application/json", ...(headers || {}) } };
+        if (body !== null && body !== undefined) init.body = body;
+        const res = await impl(apiBase + path, init);
+        if (!res || typeof res.ok !== "boolean") throw new SdkError("server-unavailable", { why: "bad-response" });
+        if (!res.ok) throw new SdkError("server-unavailable", { status: res.status });
+        return await res.json();
+      } catch (error) {
+        if (error instanceof SdkError) throw error;
+        throw new SdkError("server-unavailable", { why: error && error.name === "AbortError" ? "timeout" : "fetch" });
+      } finally {
+        clearTimeout(timer);
+        if (signal) signal.removeEventListener("abort", abort);
+      }
+    },
+    /**
+     * THE SAME AS `json`, BUT THE SERVICE'S REFUSAL IS RETURNED AS A VALUE: { ok, status, body }.
+     *
+     * Why a separate method. `json` throws server-unavailable {status} and LOSES the response body, while the
+     * body carries the service's reason (our app answers {ok:false,error:"..."}). For the "server" step the
+     * reason is needed in full: without it a 403 "the escrow belongs to another wallet" is indistinguishable
+     * from a 400 "an escrow address is required", and the interface gets "something went wrong" instead of an
+     * answer to its question. A connection error is still thrown as a code: "did not answer" and "answered and
+     * refused" are different things, and the caller must see them.
+     */
+    async tryJson(path, { signal = null, method = "GET", headers = null, body = null } = {}) {
+      if (typeof impl !== "function") throw new SdkError("bad-input", { field: "fetch" });
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+      const abort = () => ctrl.abort();
+      if (signal) signal.addEventListener("abort", abort, { once: true });
+      try {
+        const init = { signal: ctrl.signal, method, headers: { accept: "application/json", ...(headers || {}) } };
+        if (body !== null && body !== undefined) init.body = body;
+        const res = await impl(apiBase + path, init);
+        if (!res || typeof res.ok !== "boolean") throw new SdkError("server-unavailable", { why: "bad-response" });
+        let parsed = null;
+        try { parsed = await res.json(); } catch { parsed = null; }
+        return { ok: res.ok, status: res.status, body: parsed };
+      } catch (error) {
+        if (error instanceof SdkError) throw error;
+        throw new SdkError("server-unavailable", { why: error && error.name === "AbortError" ? "timeout" : "fetch" });
+      } finally {
+        clearTimeout(timer);
+        if (signal) signal.removeEventListener("abort", abort);
+      }
+    },
+  };
+}