@lumenwipe/sdk 0.2.0 → 0.5.1

package/dist/index.js

@@ -1,12 +1,58 @@
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+
 // src/errors.ts
+function parseRetryAfterMs(value) {
+  if (!value) return void 0;
+  const trimmed = value.trim();
+  if (/^\d+$/.test(trimmed)) return Number(trimmed) * 1e3;
+  const at = Date.parse(trimmed);
+  return Number.isNaN(at) ? void 0 : Math.max(0, at - Date.now());
+}
+function readEnvelope(body) {
+  if (typeof body !== "object" || body === null || !("error" in body)) return void 0;
+  const error = body.error;
+  if (typeof error !== "object" || error === null) return void 0;
+  const { code, message, details } = error;
+  if (typeof code !== "string" || typeof message !== "string") return void 0;
+  return { code, message, details };
+}
 var LumenWipeApiError = class extends Error {
-  constructor(status, body) {
-    super(`LumenWipe API error ${status}`);
+  constructor(status, body, headers) {
+    var _a, _b;
+    const envelope = readEnvelope(body);
+    super(
+      envelope ? `LumenWipe API error ${status} ${envelope.code}: ${envelope.message}` : `LumenWipe API error ${status}`
+    );
     this.status = status;
     this.body = body;
     this.name = "LumenWipeApiError";
+    this.code = (_a = envelope == null ? void 0 : envelope.code) != null ? _a : "upstream_error";
+    this.details = envelope == null ? void 0 : envelope.details;
+    this.retryAfterMs = parseRetryAfterMs(headers == null ? void 0 : headers.get("Retry-After"));
+    this.requestId = (_b = headers == null ? void 0 : headers.get("X-Request-Id")) != null ? _b : void 0;
   }
 };
+function isApiErrorCode(error, code) {
+  return error instanceof LumenWipeApiError && error.code === code;
+}
 var LumenWipeTimeoutError = class extends Error {
   constructor(timeoutMs) {
     super(`LumenWipe API request timed out after ${timeoutMs}ms`);
@@ -14,21 +60,90 @@ var LumenWipeTimeoutError = class extends Error {
     this.name = "LumenWipeTimeoutError";
   }
 };
+var LumenWipeAbortError = class extends Error {
+  constructor(reason) {
+    super("LumenWipe API request was aborted");
+    this.reason = reason;
+    this.name = "LumenWipeAbortError";
+  }
+};
+
+// src/version.ts
+var SDK_VERSION = "0.5.1";
 
 // src/http.ts
+var MAX_DELAY_MS = 3e4;
+var TRANSIENT_STATUSES = /* @__PURE__ */ new Set([429, 502, 503, 504]);
+var THROTTLE_STATUSES = /* @__PURE__ */ new Set([429, 503]);
 var HttpTransport = class {
-  constructor(baseUrl, apiKey, timeout, doFetch) {
+  constructor(baseUrl, apiKey, timeout, doFetch, retry) {
     this.baseUrl = baseUrl;
     this.apiKey = apiKey;
     this.timeout = timeout;
     this.doFetch = doFetch;
+    this.retry = retry;
   }
-  async request(method, path, body) {
-    const headers = { Authorization: `Bearer ${this.apiKey}` };
+  async request(method, path, body, opts) {
+    var _a, _b;
+    const attempts = opts.retry === "never" ? 1 : Math.max(1, Math.floor((_b = (_a = this.retry) == null ? void 0 : _a.attempts) != null ? _b : 1));
+    for (let attempt = 1; ; attempt++) {
+      try {
+        return await this.once(method, path, body, opts.signal);
+      } catch (e) {
+        if (attempt >= attempts || !this.shouldRetry(opts.retry, e)) throw e;
+        await this.sleep(this.delayMs(e, attempt), opts.signal);
+      }
+    }
+  }
+  shouldRetry(policy, e) {
+    if (e instanceof LumenWipeApiError) {
+      const statuses = policy === "transient" ? TRANSIENT_STATUSES : THROTTLE_STATUSES;
+      return statuses.has(e.status);
+    }
+    return policy === "transient" && !(e instanceof LumenWipeTimeoutError) && !(e instanceof LumenWipeAbortError);
+  }
+  delayMs(e, attempt) {
+    var _a, _b;
+    if (e instanceof LumenWipeApiError && e.retryAfterMs !== void 0) {
+      return Math.min(e.retryAfterMs, MAX_DELAY_MS);
+    }
+    const base = (_b = (_a = this.retry) == null ? void 0 : _a.baseDelayMs) != null ? _b : 0;
+    return Math.min(base * 2 ** (attempt - 1) * (0.5 + Math.random() / 2), MAX_DELAY_MS);
+  }
+  sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+      if (signal == null ? void 0 : signal.aborted) return reject(new LumenWipeAbortError(signal.reason));
+      const onAbort = () => {
+        clearTimeout(timer);
+        reject(new LumenWipeAbortError(signal == null ? void 0 : signal.reason));
+      };
+      const timer = setTimeout(() => {
+        signal == null ? void 0 : signal.removeEventListener("abort", onAbort);
+        resolve();
+      }, ms);
+      signal == null ? void 0 : signal.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+  async once(method, path, body, callerSignal) {
+    if (callerSignal == null ? void 0 : callerSignal.aborted) throw new LumenWipeAbortError(callerSignal.reason);
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "X-LumenWipe-SDK": `sdk/${SDK_VERSION}`
+    };
     if (body !== void 0) headers["Content-Type"] = "application/json";
     const controller = new AbortController();
+    let timedOut = false;
+    let callerAborted = false;
+    const onCallerAbort = () => {
+      callerAborted = true;
+      controller.abort();
+    };
+    callerSignal == null ? void 0 : callerSignal.addEventListener("abort", onCallerAbort, { once: true });
     const bounded = Number.isFinite(this.timeout) && this.timeout > 0;
-    const timer = bounded ? setTimeout(() => controller.abort(), this.timeout) : void 0;
+    const timer = bounded ? setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, this.timeout) : void 0;
     try {
       const res = await this.doFetch(`${this.baseUrl}${path}`, {
         method,
@@ -45,20 +160,33 @@ var HttpTransport = class {
           parsed = text;
         }
       }
-      if (!res.ok) throw new LumenWipeApiError(res.status, parsed);
+      if (!res.ok) throw new LumenWipeApiError(res.status, parsed, res.headers);
       return parsed;
     } catch (e) {
-      if (controller.signal.aborted) throw new LumenWipeTimeoutError(this.timeout);
+      if (callerAborted) throw new LumenWipeAbortError(callerSignal == null ? void 0 : callerSignal.reason);
+      if (timedOut) throw new LumenWipeTimeoutError(this.timeout);
       throw e;
     } finally {
       if (timer) clearTimeout(timer);
+      callerSignal == null ? void 0 : callerSignal.removeEventListener("abort", onCallerAbort);
     }
   }
 };
 
 // src/client.ts
+function isPlaintextRemote(baseUrl) {
+  try {
+    const url = new URL(baseUrl);
+    if (url.protocol !== "http:") return false;
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    return !(host === "localhost" || host === "::1" || /^127\./.test(host));
+  } catch (e) {
+    return false;
+  }
+}
 var LumenWipeClient = class {
   constructor(options) {
+    this.warnedDefaultNetwork = false;
     var _a, _b, _c;
     const resolved = (_a = options.fetch) != null ? _a : globalThis.fetch;
     if (!resolved) {
@@ -68,77 +196,130 @@ var LumenWipeClient = class {
       options.baseUrl.replace(/\/+$/, ""),
       options.apiKey,
       (_b = options.timeout) != null ? _b : 3e4,
-      resolved
+      resolved,
+      options.retry
     );
-    this.defaultNetwork = (_c = options.network) != null ? _c : "testnet";
+    this.defaultNetwork = options.network;
+    this.log = (_c = options.logger) != null ? _c : ((message) => console.warn(message));
+    if (isPlaintextRemote(options.baseUrl)) {
+      this.log(
+        "LumenWipe: baseUrl uses http:// for a non-local host. The API key is sent in clear text; use https://."
+      );
+    }
+  }
+  resolveNetwork(network) {
+    if (network) return network;
+    if (this.defaultNetwork) return this.defaultNetwork;
+    if (!this.warnedDefaultNetwork) {
+      this.warnedDefaultNetwork = true;
+      this.log(
+        'LumenWipe: no network given, defaulting to "testnet". Pass `network` to the client or the call to silence this.'
+      );
+    }
+    return "testnet";
   }
-  health() {
-    return this.http.request("GET", "/health");
+  health(options) {
+    return this.http.request("GET", "/health", void 0, __spreadProps(__spreadValues({}, options), {
+      retry: "transient"
+    }));
   }
-  getAccount(address, network = this.defaultNetwork) {
+  getAccount(address, network, options) {
     return this.http.request(
       "GET",
-      `/${network}/account/${encodeURIComponent(address)}`
+      `/${this.resolveNetwork(network)}/account/${encodeURIComponent(address)}`,
+      void 0,
+      __spreadProps(__spreadValues({}, options), { retry: "transient" })
     );
   }
-  getPaths(params, network = this.defaultNetwork) {
+  getPaths(params, network, options) {
     const query = new URLSearchParams({ fromAsset: params.fromAsset, amount: params.amount });
-    return this.http.request("GET", `/${network}/paths?${query.toString()}`);
+    return this.http.request(
+      "GET",
+      `/${this.resolveNetwork(network)}/paths?${query.toString()}`,
+      void 0,
+      __spreadProps(__spreadValues({}, options), { retry: "transient" })
+    );
   }
-  closePlan(body, network = this.defaultNetwork) {
-    return this.http.request("POST", `/v1/${network}/close/plan`, body);
+  closePlan(body, network, options) {
+    return this.http.request(
+      "POST",
+      `/v1/${this.resolveNetwork(network)}/close/plan`,
+      body,
+      __spreadProps(__spreadValues({}, options), { retry: "throttle" })
+    );
   }
   /**
    * Builds the next unsigned transaction(s) for a close. A close can span several
-   * transactions (a fused close, or separate claim / cleanup / mediator-merge steps),
+   * transactions (a single transaction, or separate claim / cleanup / mediator-merge steps),
    * so the response's `remaining.requiresAnotherCall` says whether more follow: sign and
    * submit the returned transactions in `order`, wait for confirmation, then call this
    * again until `requiresAnotherCall` is false.
    */
-  closeTransactions(body, network = this.defaultNetwork) {
+  closeTransactions(body, network, options) {
     return this.http.request(
       "POST",
-      `/v1/${network}/close/transactions`,
-      body
+      `/v1/${this.resolveNetwork(network)}/close/transactions`,
+      body,
+      __spreadProps(__spreadValues({}, options), { retry: "throttle" })
     );
   }
-  submit(signedXdr, network = this.defaultNetwork) {
-    return this.http.request("POST", `/v1/${network}/submit`, { signedXdr });
+  submit(signedXdr, network, options) {
+    return this.http.request(
+      "POST",
+      `/v1/${this.resolveNetwork(network)}/submit`,
+      { signedXdr },
+      __spreadProps(__spreadValues({}, options), { retry: "never" })
+    );
   }
-  mediatorCheck(address, network = this.defaultNetwork) {
+  mediatorCheck(address, network, options) {
     return this.http.request(
       "GET",
-      `/${network}/mediator/check/${encodeURIComponent(address)}`
+      `/${this.resolveNetwork(network)}/mediator/check/${encodeURIComponent(address)}`,
+      void 0,
+      __spreadProps(__spreadValues({}, options), { retry: "transient" })
     );
   }
-  mediatorSign(transaction, network = this.defaultNetwork) {
-    return this.http.request("POST", `/${network}/mediator/sign`, {
-      transaction
-    });
+  mediatorSign(transaction, network, options) {
+    return this.http.request(
+      "POST",
+      `/${this.resolveNetwork(network)}/mediator/sign`,
+      {
+        transaction
+      },
+      __spreadProps(__spreadValues({}, options), { retry: "never" })
+    );
   }
   /** Wraps a wind-down transaction (its own fee already zero) in a signed CAP-15 fee-bump
    *  envelope for an account that cannot pay its own fee (architecture.md §8.1). The caller
    *  submits the returned XDR through `submit()`, exactly like any other close transaction. */
-  feeBumpSponsor(transaction, network = this.defaultNetwork) {
-    return this.http.request("POST", `/${network}/fee-bump/sponsor`, {
-      transaction
-    });
+  feeBumpSponsor(transaction, network, options) {
+    return this.http.request(
+      "POST",
+      `/${this.resolveNetwork(network)}/fee-bump/sponsor`,
+      {
+        transaction
+      },
+      __spreadProps(__spreadValues({}, options), { retry: "throttle" })
+    );
   }
   /** Every live SEP-41 allowance the account has granted (architecture.md §12). Independent of
    *  closing an account - a standalone security utility. */
-  getAllowances(address, network = this.defaultNetwork) {
+  getAllowances(address, network, options) {
     return this.http.request(
       "GET",
-      `/${network}/allowances/${encodeURIComponent(address)}`
+      `/${this.resolveNetwork(network)}/allowances/${encodeURIComponent(address)}`,
+      void 0,
+      __spreadProps(__spreadValues({}, options), { retry: "transient" })
     );
   }
   /** Builds the unsigned `approve(owner, spender, 0, 0)` transaction that revokes one allowance.
    *  The caller signs and submits it through `submit()`, like any other transaction here. */
-  revokeAllowance(params, network = this.defaultNetwork) {
+  revokeAllowance(params, network, options) {
     return this.http.request(
       "POST",
-      `/${network}/allowances/revoke`,
-      params
+      `/${this.resolveNetwork(network)}/allowances/revoke`,
+      params,
+      __spreadProps(__spreadValues({}, options), { retry: "throttle" })
     );
   }
 };
@@ -196,8 +377,10 @@ async function signOrThrow(deps, tx, xdr, queue, requiresAnotherCall) {
 }
 export {
   InsufficientSignatureWeightError,
+  LumenWipeAbortError,
   LumenWipeApiError,
   LumenWipeClient,
   LumenWipeTimeoutError,
+  isApiErrorCode,
   runClose
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenwipe/sdk",
-  "version": "0.2.0",
+  "version": "0.5.1",
   "description": "Typed fetch client for the LumenWipe API - non-custodial Stellar account closing.",
   "license": "Apache-2.0",
   "type": "module",
@@ -44,12 +44,14 @@
     "build": "bun run build:types && api-extractor run --local && cp dist/index.d.ts dist/index.d.cts",
     "build:types": "bun run --filter '@lumenwipe/types' build && tsup src/index.ts --format esm,cjs --clean && tsc -p tsconfig.build.json",
     "check-api": "api-extractor run",
-    "type-check": "tsc --noEmit && tsc -p tests/tsconfig.json --noEmit",
-    "lint": "eslint src",
-    "test": "bun test tests"
+    "type-check": "tsc --noEmit && tsc -p tests/tsconfig.json --noEmit && tsc -p examples/tsconfig.json --noEmit",
+    "lint": "eslint src examples",
+    "test": "bun test tests",
+    "example:headless": "bun run examples/headless-close.ts"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.59.0",
+    "@stellar/stellar-sdk": "16.0.1",
     "@types/bun": "^1.4.0",
     "@typescript-eslint/eslint-plugin": "^8.69.0",
     "@typescript-eslint/parser": "^8.69.0",