@lumenwipe/sdk 0.2.0 → 0.7.0

package/README.md

@@ -25,16 +25,16 @@ const client = new LumenWipeClient({
   network: "mainnet", // or "testnet"
 });
 
-const account = await client.getAccount(address);
+const account = await client.getAccount(source);
 
 const plan = await client.closePlan({
-  address,
+  source,
   destination,
   // ...see @lumenwipe/types for the full request shape
 });
 
 const { transactions, remaining } = await client.closeTransactions({
-  address,
+  source,
   destination,
 });
 
@@ -49,7 +49,7 @@ instead of calling `closeTransactions`/`submit` by hand:
 import { runClose } from "@lumenwipe/sdk";
 
 await runClose({
-  getTransactions: () => client.closeTransactions({ address, destination }),
+  getTransactions: () => client.closeTransactions({ source, destination }),
   verify: (tx) => myVerify(tx), // see "Verification" below - this is your responsibility
   requiredWeight: (tx) => myRequiredWeight(tx),
   sign: (tx, xdr) => mySigner(tx, xdr),
@@ -57,6 +57,20 @@ await runClose({
 });
 ```
 
+## Headless example
+
+[`examples/headless-close.ts`](https://github.com/LumenWipe/lumenwipe/blob/main/packages/sdk/examples/headless-close.ts)
+closes a throwaway testnet account end to end from a plain Node/Bun process, with no browser or
+web UI: it funds two accounts, then runs `getAccount`, `closePlan`, `closeTransactions` and
+`submit` through `runClose`, signing with an in-process keypair. It decodes and verifies every
+transaction itself before signing (`examples/verify.ts`), which is the pattern to copy.
+
+```bash
+LUMENWIPE_API_KEY=... bun run --filter '@lumenwipe/sdk' example:headless
+```
+
+`LUMENWIPE_API_URL` overrides the default `https://api.lumenwipe.com`. Testnet only.
+
 ## Verification is the caller's responsibility
 
 This SDK does not verify or sign anything. Every transaction it returns is unsigned XDR built by
@@ -86,15 +100,16 @@ no separate install is needed.
 
 ## Errors
 
-- `LumenWipeApiError` - thrown on any non-2xx API response; carries `status` and the parsed
-  error `body`.
+- `LumenWipeApiError` - thrown on any non-2xx API response; carries `status`, `code`, `details`,
+  `retryAfterMs`, `requestId` and the parsed error `body`. Narrow with `isApiErrorCode`.
+- `LumenWipeAbortError` - thrown when the `signal` you passed aborts the request.
 - `LumenWipeTimeoutError` - thrown when a request exceeds the configured `timeout`
   (default 30s).
 
 ## Links
 
 - [Architecture](https://github.com/LumenWipe/lumenwipe/blob/main/docs/architecture.md)
-- [Full documentation](https://docs.lumenwipe.com)
+- [Full documentation](https://docs.lumenwipe.com/sdk/overview)
 - [Issues](https://github.com/LumenWipe/lumenwipe/issues)
 
 ## License

package/dist/index.cjs

@@ -1,8 +1,25 @@
 "use strict";
 var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+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));
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -21,22 +38,50 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   InsufficientSignatureWeightError: () => InsufficientSignatureWeightError,
+  LumenWipeAbortError: () => LumenWipeAbortError,
   LumenWipeApiError: () => LumenWipeApiError,
   LumenWipeClient: () => LumenWipeClient,
   LumenWipeTimeoutError: () => LumenWipeTimeoutError,
+  isApiErrorCode: () => isApiErrorCode,
   runClose: () => runClose
 });
 module.exports = __toCommonJS(index_exports);
 
 // 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`);
@@ -44,21 +89,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.7.0";
 
 // 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,
@@ -75,20 +189,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) {
@@ -98,77 +225,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" })
     );
   }
 };
@@ -227,8 +407,10 @@ async function signOrThrow(deps, tx, xdr, queue, requiresAnotherCall) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   InsufficientSignatureWeightError,
+  LumenWipeAbortError,
   LumenWipeApiError,
   LumenWipeClient,
   LumenWipeTimeoutError,
+  isApiErrorCode,
   runClose
 });