@lumenwipe/sdk 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# @lumenwipe/sdk
+
+Typed fetch client for the [LumenWipe](https://lumenwipe.com) API. LumenWipe closes Stellar
+accounts non-custodially: it unwinds everything holding an account open, converts leftovers to
+XLM, and merges the account into a destination wallet or exchange.
+
+This package only talks to the LumenWipe API over HTTP - it builds no transactions itself and has
+no `@stellar/stellar-sdk` dependency. Reading on-chain state and constructing every unsigned
+transaction happens server-side; this client just relays typed JSON and XDR strings.
+
+## Install
+
+```bash
+npm install @lumenwipe/sdk
+```
+
+## Quick start
+
+```ts
+import { LumenWipeClient } from "@lumenwipe/sdk";
+
+const client = new LumenWipeClient({
+  baseUrl: "https://api.lumenwipe.com",
+  apiKey: process.env.LUMENWIPE_API_KEY!,
+  network: "mainnet", // or "testnet"
+});
+
+const account = await client.getAccount(address);
+
+const plan = await client.closePlan({
+  address,
+  destination,
+  // ...see @lumenwipe/types for the full request shape
+});
+
+const { transactions, remaining } = await client.closeTransactions({
+  address,
+  destination,
+});
+
+// Sign and submit each transaction, then repeat while remaining.requiresAnotherCall is true.
+const result = await client.submit(signedXdr);
+```
+
+For a fully driven close loop (fetch -> verify -> sign -> submit -> repeat), use `runClose`
+instead of calling `closeTransactions`/`submit` by hand:
+
+```ts
+import { runClose } from "@lumenwipe/sdk";
+
+await runClose({
+  getTransactions: () => client.closeTransactions({ address, destination }),
+  verify: (tx) => myVerify(tx), // see "Verification" below - this is your responsibility
+  requiredWeight: (tx) => myRequiredWeight(tx),
+  sign: (tx, xdr) => mySigner(tx, xdr),
+  submit: (tx, xdr) => client.submit(xdr).then((r) => r.hash),
+});
+```
+
+## Verification is the caller's responsibility
+
+This SDK does not verify or sign anything. Every transaction it returns is unsigned XDR built by
+the API from data you provided - before signing, your own code must independently confirm the
+transaction does exactly what the user asked (correct destination, no unexpected operations, no
+added signers, matching amounts) using values from your own inputs, never from the API response
+alone. LumenWipe's own web client's verification logic (`assertCloseIntent` in
+[`apps/web/lib/stellar/verify.ts`](https://github.com/LumenWipe/lumenwipe/blob/main/apps/web/lib/stellar/verify.ts))
+is the reference implementation - read it before wiring up signing in a production integration.
+Never sign a transaction from this SDK without an equivalent check.
+
+## API surface
+
+- `health()` - service health check.
+- `getAccount(address, network?)` - current on-chain state for an account.
+- `getPaths(params, network?)` - conversion path quotes for a source asset.
+- `closePlan(body, network?)` - a preview of the full close plan, with blockers if any step
+  cannot be closed safely.
+- `closeTransactions(body, network?)` - builds the next round of unsigned transactions.
+- `submit(signedXdr, network?)` - submits a signed transaction.
+- `mediatorCheck(address, network?)` / `mediatorSign(transaction, network?)` - the exchange
+  mediator flow (see the architecture doc).
+- `runClose(deps)` - drives the full fetch/verify/sign/submit loop to completion.
+
+Request and response types come from `@lumenwipe/types` and are re-exported from this package, so
+no separate install is needed.
+
+## Errors
+
+- `LumenWipeApiError` - thrown on any non-2xx API response; carries `status` and the parsed
+  error `body`.
+- `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)
+- [Issues](https://github.com/LumenWipe/lumenwipe/issues)
+
+## License
+
+Apache-2.0

package/dist/index.cjs

@@ -0,0 +1,209 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  InsufficientSignatureWeightError: () => InsufficientSignatureWeightError,
+  LumenWipeApiError: () => LumenWipeApiError,
+  LumenWipeClient: () => LumenWipeClient,
+  LumenWipeTimeoutError: () => LumenWipeTimeoutError,
+  runClose: () => runClose
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var LumenWipeApiError = class extends Error {
+  constructor(status, body) {
+    super(`LumenWipe API error ${status}`);
+    this.status = status;
+    this.body = body;
+    this.name = "LumenWipeApiError";
+  }
+};
+var LumenWipeTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`LumenWipe API request timed out after ${timeoutMs}ms`);
+    this.timeoutMs = timeoutMs;
+    this.name = "LumenWipeTimeoutError";
+  }
+};
+
+// src/http.ts
+var HttpTransport = class {
+  constructor(baseUrl, apiKey, timeout, doFetch) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+    this.timeout = timeout;
+    this.doFetch = doFetch;
+  }
+  async request(method, path, body) {
+    const headers = { Authorization: `Bearer ${this.apiKey}` };
+    if (body !== void 0) headers["Content-Type"] = "application/json";
+    const controller = new AbortController();
+    const bounded = Number.isFinite(this.timeout) && this.timeout > 0;
+    const timer = bounded ? setTimeout(() => controller.abort(), this.timeout) : void 0;
+    try {
+      const res = await this.doFetch(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      const text = await res.text();
+      let parsed = void 0;
+      if (text) {
+        try {
+          parsed = JSON.parse(text);
+        } catch (e) {
+          parsed = text;
+        }
+      }
+      if (!res.ok) throw new LumenWipeApiError(res.status, parsed);
+      return parsed;
+    } catch (e) {
+      if (controller.signal.aborted) throw new LumenWipeTimeoutError(this.timeout);
+      throw e;
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+};
+
+// src/client.ts
+var LumenWipeClient = class {
+  constructor(options) {
+    var _a, _b, _c;
+    const resolved = (_a = options.fetch) != null ? _a : globalThis.fetch;
+    if (!resolved) {
+      throw new Error("No fetch implementation available; pass one via options.fetch.");
+    }
+    this.http = new HttpTransport(
+      options.baseUrl.replace(/\/+$/, ""),
+      options.apiKey,
+      (_b = options.timeout) != null ? _b : 3e4,
+      resolved
+    );
+    this.defaultNetwork = (_c = options.network) != null ? _c : "testnet";
+  }
+  health() {
+    return this.http.request("GET", "/health");
+  }
+  getAccount(address, network = this.defaultNetwork) {
+    return this.http.request(
+      "GET",
+      `/${network}/account/${encodeURIComponent(address)}`
+    );
+  }
+  getPaths(params, network = this.defaultNetwork) {
+    const query = new URLSearchParams({ fromAsset: params.fromAsset, amount: params.amount });
+    return this.http.request("GET", `/${network}/paths?${query.toString()}`);
+  }
+  closePlan(body, network = this.defaultNetwork) {
+    return this.http.request("POST", `/v1/${network}/close/plan`, body);
+  }
+  /**
+   * 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),
+   * 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) {
+    return this.http.request(
+      "POST",
+      `/v1/${network}/close/transactions`,
+      body
+    );
+  }
+  submit(signedXdr, network = this.defaultNetwork) {
+    return this.http.request("POST", `/v1/${network}/submit`, { signedXdr });
+  }
+  mediatorCheck(address, network = this.defaultNetwork) {
+    return this.http.request(
+      "GET",
+      `/${network}/mediator/check/${encodeURIComponent(address)}`
+    );
+  }
+  mediatorSign(transaction, network = this.defaultNetwork) {
+    return this.http.request("POST", `/${network}/mediator/sign`, {
+      transaction
+    });
+  }
+};
+
+// src/close-engine.ts
+var InsufficientSignatureWeightError = class extends Error {
+  constructor(pending) {
+    super(
+      `Transaction ${pending.tx.id} needs signing weight ${pending.requiredWeight} but only has ${pending.accumulatedWeight}.`
+    );
+    this.pending = pending;
+    this.name = "InsufficientSignatureWeightError";
+  }
+};
+async function runClose(deps, resume) {
+  var _a, _b;
+  const maxRounds = (_a = deps.maxRounds) != null ? _a : 25;
+  if (resume) {
+    await signOrThrow(deps, resume.tx, resume.xdr, resume.queue, resume.requiresAnotherCall);
+    await processTxs(deps, resume.queue, resume.requiresAnotherCall);
+    if (!resume.requiresAnotherCall) return;
+  }
+  for (let round = 0; round < maxRounds; round++) {
+    (_b = deps.onProgress) == null ? void 0 : _b.call(deps, "Preparing transactions\u2026");
+    const batch = await deps.getTransactions();
+    const txs = [...batch.transactions].sort((a, b) => a.order - b.order);
+    await processTxs(deps, txs, batch.remaining.requiresAnotherCall);
+    if (!batch.remaining.requiresAnotherCall) return;
+  }
+  throw new Error("The close did not converge after the maximum number of rounds.");
+}
+async function processTxs(deps, txs, requiresAnotherCall) {
+  for (let i = 0; i < txs.length; i++) {
+    const tx = txs[i];
+    await deps.verify(tx);
+    await signOrThrow(deps, tx, tx.xdr, txs.slice(i + 1), requiresAnotherCall);
+  }
+}
+async function signOrThrow(deps, tx, xdr, queue, requiresAnotherCall) {
+  var _a;
+  const required = deps.requiredWeight(tx);
+  const { xdr: signedXdr, weight } = await deps.sign(tx, xdr);
+  if (weight < required) {
+    throw new InsufficientSignatureWeightError({
+      tx,
+      xdr: signedXdr,
+      requiredWeight: required,
+      accumulatedWeight: weight,
+      queue,
+      requiresAnotherCall
+    });
+  }
+  const hash = await deps.submit(tx, signedXdr);
+  (_a = deps.onConfirmed) == null ? void 0 : _a.call(deps, tx, hash);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  InsufficientSignatureWeightError,
+  LumenWipeApiError,
+  LumenWipeClient,
+  LumenWipeTimeoutError,
+  runClose
+});