fulgur-bridge-client 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,127 @@
+type DonationStatus = "invoice_created" | "payment_received" | "paying_out" | "success" | "failed" | "expired";
+/**
+ * Donation as returned by the gateway REST API.
+ *
+ * Field names use snake_case to match the JSON wire format. Pass server
+ * responses directly without mapping.
+ */
+interface Donation {
+    id: string;
+    ln_address: string;
+    amount_msat: number;
+    status: DonationStatus;
+    payment_hash: string;
+    bolt11: string;
+    payout_fee_msat: number | null;
+    error_message: string | null;
+    webhook_url: string | null;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateDonationParams {
+    /**
+     * Payment destination: Lightning Address (`user@domain.com`)
+     * or BOLT12 offer (`lno1...`).
+     */
+    destination: string;
+    /** Amount in satoshis. Minimum 1 sat. */
+    amountSat: number;
+    /**
+     * Optional webhook URL. Receives a POST with the donation payload
+     * immediately after successful payout. Retries on failure:
+     * 10s, 1m, 2m, 5m, 10m, 30m, 1h, then hourly up to 1 week.
+     */
+    webhookUrl?: string;
+    /**
+     * Optional HMAC-SHA256 secret. When set, the gateway signs webhook
+     * payloads and sends the hex signature in the `X-Signature-256` header.
+     */
+    webhookSecret?: string;
+}
+interface CreateDonationResult {
+    id: string;
+    bolt11: string;
+    paymentHash: string;
+}
+interface FeeEstimate {
+    amount_sat: number;
+    receive_fee_sat: number;
+    send_fee_estimate_sat: number;
+    total_fee_estimate_sat: number;
+    payout_estimate_sat: number;
+}
+interface ListDonationsParams {
+    limit?: number;
+    offset?: number;
+}
+interface WaitForPaymentOptions {
+    /** Called on each status transition. */
+    onStatusChange?: (status: DonationStatus) => void;
+    /** Timeout in milliseconds. Rejects with error on expiry. */
+    timeoutMs?: number;
+}
+interface PowChallenge {
+    challenge: string;
+    difficulty: number;
+    expires_in_secs: number;
+}
+/** Webhook POST body. See README for headers and retry schedule. */
+interface WebhookPayload {
+    event: "donation.success";
+    donation: Donation;
+}
+
+/** Gateway REST + WebSocket client. Handles PoW automatically. */
+declare class RestGatewayClient {
+    private baseUrl;
+    constructor(gatewayUrl: string);
+    /** Returns null when the gateway doesn't require PoW for this IP. */
+    getChallenge(): Promise<PowChallenge | null>;
+    /** Create a donation. Solves PoW challenge if the gateway requires one. */
+    createDonation(params: CreateDonationParams): Promise<CreateDonationResult>;
+    getDonation(id: string): Promise<Donation>;
+    listDonations(params?: ListDonationsParams): Promise<Donation[]>;
+    estimateFees(amountSat: number): Promise<FeeEstimate>;
+    /** Subscribe via WS, resolve on terminal status. */
+    waitForPayment(donationId: string, options?: WaitForPaymentOptions): Promise<DonationStatus>;
+}
+
+/**
+ * Hashcash PoW solver. Finds nonce where SHA256(challenge:nonce) has
+ * N leading zero bits. Auto-picks the fastest runtime strategy:
+ * node:crypto > pure JS SHA-256 > crypto.subtle (browser, async).
+ */
+declare function solvePow(challenge: string, difficulty: number): Promise<number>;
+declare function verifyPow(challenge: string, nonce: number, difficulty: number): Promise<boolean>;
+
+interface QrOptions {
+    /** SVG width/height in pixels. Default: 256. */
+    size?: number;
+    /** Dark module color. Default: "#000". */
+    color?: string;
+    /** Prepend `LIGHTNING:` prefix to BOLT11 for wallet compat. Default: true. */
+    withPrefix?: boolean;
+}
+/** Generate an SVG QR code. Works with both BOLT11 invoices and BOLT12 offers. */
+declare function invoiceToSvg(invoice: string, options?: QrOptions): string;
+/** SVG data URL for use in `<img src="...">`. */
+declare function invoiceToDataUrl(invoice: string, options?: QrOptions): string;
+
+/** BOLT12 offer strings start with "lno1". */
+declare function isBolt12Offer(s: string): boolean;
+/** Basic format check (user@domain). Does not verify the domain. */
+declare function isLnAddress(s: string): boolean;
+type DestinationType = "bolt12Offer" | "lnAddress" | "unknown";
+declare function detectDestinationType(s: string): DestinationType;
+
+/** Verify `X-Signature-256` header. Pass the raw body, not parsed JSON. */
+declare function verifyWebhookSignature(body: string | Buffer | Uint8Array, signature: string, secret: string): Promise<boolean>;
+/** Verify + parse in one step. Returns null on bad signature. */
+declare function parseWebhook(body: string | Buffer | Uint8Array, signature: string, secret: string): Promise<WebhookPayload | null>;
+/**
+ * Verify + parse from a Fetch API `Request` (Hono, Next.js, SvelteKit, etc.).
+ * Requires `node:crypto`. Won't work in browsers or Cloudflare Workers.
+ */
+declare function parseWebhookRequest(request: Request, secret: string): Promise<WebhookPayload | null>;
+
+export { type CreateDonationParams, type CreateDonationResult, type DestinationType, type Donation, type DonationStatus, type FeeEstimate, type ListDonationsParams, type PowChallenge, type QrOptions, RestGatewayClient, type WaitForPaymentOptions, type WebhookPayload, detectDestinationType, invoiceToDataUrl, invoiceToSvg, isBolt12Offer, isLnAddress, parseWebhook, parseWebhookRequest, solvePow, verifyPow, verifyWebhookSignature };

package/dist/index.js

@@ -0,0 +1,426 @@
+// src/pow.ts
+function leadingZeroBits(hash) {
+  let count = 0;
+  for (const byte of hash) {
+    if (byte === 0) {
+      count += 8;
+    } else {
+      count += Math.clz32(byte) - 24;
+      break;
+    }
+  }
+  return count;
+}
+var _nodeCrypto;
+async function getNodeCrypto() {
+  if (_nodeCrypto !== void 0) return _nodeCrypto;
+  try {
+    _nodeCrypto = await import("crypto");
+    return _nodeCrypto;
+  } catch {
+    _nodeCrypto = null;
+    return null;
+  }
+}
+function solveWithNodeCrypto(crypto2, challenge, difficulty) {
+  const prefix = `${challenge}:`;
+  for (let nonce = 0; ; nonce++) {
+    const hash = crypto2.createHash("sha256").update(`${prefix}${nonce}`).digest();
+    if (leadingZeroBits(hash) >= difficulty) return nonce;
+  }
+}
+var K = new Uint32Array([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
+function sha256js(bytes) {
+  const len = bytes.length;
+  const bitLen = len * 8;
+  const padLen = len + 9 + 63 & ~63;
+  const buf = new Uint8Array(padLen);
+  buf.set(bytes);
+  buf[len] = 128;
+  const dv = new DataView(buf.buffer);
+  dv.setUint32(padLen - 4, bitLen, false);
+  let h0 = 1779033703, h1 = 3144134277, h2 = 1013904242, h3 = 2773480762;
+  let h4 = 1359893119, h5 = 2600822924, h6 = 528734635, h7 = 1541459225;
+  const w = new Uint32Array(64);
+  for (let off = 0; off < padLen; off += 64) {
+    for (let i = 0; i < 16; i++) w[i] = dv.getUint32(off + i * 4, false);
+    for (let i = 16; i < 64; i++) {
+      const s0 = (w[i - 15] >>> 7 | w[i - 15] << 25) ^ (w[i - 15] >>> 18 | w[i - 15] << 14) ^ w[i - 15] >>> 3;
+      const s1 = (w[i - 2] >>> 17 | w[i - 2] << 15) ^ (w[i - 2] >>> 19 | w[i - 2] << 13) ^ w[i - 2] >>> 10;
+      w[i] = w[i - 16] + s0 + w[i - 7] + s1 | 0;
+    }
+    let a = h0, b = h1, c = h2, d = h3, e = h4, f = h5, g = h6, h = h7;
+    for (let i = 0; i < 64; i++) {
+      const S1 = (e >>> 6 | e << 26) ^ (e >>> 11 | e << 21) ^ (e >>> 25 | e << 7);
+      const ch = e & f ^ ~e & g;
+      const t1 = h + S1 + ch + K[i] + w[i] | 0;
+      const S0 = (a >>> 2 | a << 30) ^ (a >>> 13 | a << 19) ^ (a >>> 22 | a << 10);
+      const maj = a & b ^ a & c ^ b & c;
+      const t2 = S0 + maj | 0;
+      h = g;
+      g = f;
+      f = e;
+      e = d + t1 | 0;
+      d = c;
+      c = b;
+      b = a;
+      a = t1 + t2 | 0;
+    }
+    h0 = h0 + a | 0;
+    h1 = h1 + b | 0;
+    h2 = h2 + c | 0;
+    h3 = h3 + d | 0;
+    h4 = h4 + e | 0;
+    h5 = h5 + f | 0;
+    h6 = h6 + g | 0;
+    h7 = h7 + h | 0;
+  }
+  const out = new Uint8Array(32);
+  const odv = new DataView(out.buffer);
+  odv.setUint32(0, h0);
+  odv.setUint32(4, h1);
+  odv.setUint32(8, h2);
+  odv.setUint32(12, h3);
+  odv.setUint32(16, h4);
+  odv.setUint32(20, h5);
+  odv.setUint32(24, h6);
+  odv.setUint32(28, h7);
+  return out;
+}
+function solveWithPureJs(challenge, difficulty) {
+  const encoder = new TextEncoder();
+  const prefix = encoder.encode(`${challenge}:`);
+  for (let nonce = 0; ; nonce++) {
+    const suffix = encoder.encode(String(nonce));
+    const msg = new Uint8Array(prefix.length + suffix.length);
+    msg.set(prefix);
+    msg.set(suffix, prefix.length);
+    if (leadingZeroBits(sha256js(msg)) >= difficulty) return nonce;
+  }
+}
+async function solveWithSubtle(challenge, difficulty) {
+  const BATCH_SIZE = 5e3;
+  const encoder = new TextEncoder();
+  for (let start = 0; ; start += BATCH_SIZE) {
+    for (let nonce = start; nonce < start + BATCH_SIZE; nonce++) {
+      const data = encoder.encode(`${challenge}:${nonce}`);
+      const buffer = await crypto.subtle.digest("SHA-256", data);
+      if (leadingZeroBits(new Uint8Array(buffer)) >= difficulty) return nonce;
+    }
+    await new Promise((r) => setTimeout(r, 0));
+  }
+}
+var isBrowser = typeof window !== "undefined" && typeof window.document !== "undefined";
+async function solvePow(challenge, difficulty) {
+  const nodeCrypto = await getNodeCrypto();
+  if (nodeCrypto) return solveWithNodeCrypto(nodeCrypto, challenge, difficulty);
+  if (!isBrowser) return solveWithPureJs(challenge, difficulty);
+  return solveWithSubtle(challenge, difficulty);
+}
+async function verifyPow(challenge, nonce, difficulty) {
+  const nodeCrypto = await getNodeCrypto();
+  if (nodeCrypto) {
+    const hash = nodeCrypto.createHash("sha256").update(`${challenge}:${nonce}`).digest();
+    return leadingZeroBits(hash) >= difficulty;
+  }
+  const encoder = new TextEncoder();
+  return leadingZeroBits(sha256js(encoder.encode(`${challenge}:${nonce}`))) >= difficulty;
+}
+
+// src/rest.ts
+var RestGatewayClient = class {
+  baseUrl;
+  constructor(gatewayUrl) {
+    this.baseUrl = gatewayUrl.replace(/\/$/, "");
+  }
+  /** Returns null when the gateway doesn't require PoW for this IP. */
+  async getChallenge() {
+    const resp = await fetch(`${this.baseUrl}/api/v1/pow-challenge`);
+    if (resp.status === 400) return null;
+    if (!resp.ok) throw new Error(`Challenge request failed: ${resp.status}`);
+    return resp.json();
+  }
+  /** Create a donation. Solves PoW challenge if the gateway requires one. */
+  async createDonation(params) {
+    const challenge = await this.getChallenge();
+    let pow;
+    if (challenge) {
+      const nonce = await solvePow(challenge.challenge, challenge.difficulty);
+      pow = { challenge: challenge.challenge, nonce };
+    }
+    const body = {
+      ln_address: params.destination,
+      amount_msat: params.amountSat * 1e3
+    };
+    if (pow) body.pow = pow;
+    if (params.webhookUrl) body.webhook_url = params.webhookUrl;
+    if (params.webhookSecret) body.webhook_secret = params.webhookSecret;
+    const resp = await fetch(`${this.baseUrl}/api/v1/donations`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    if (!resp.ok) {
+      const err = await resp.json().catch(() => ({ error: "unknown" }));
+      throw new Error(
+        `Create donation failed (${resp.status}): ${err.error || JSON.stringify(err)}`
+      );
+    }
+    const data = await resp.json();
+    return {
+      id: data.id,
+      bolt11: data.bolt11,
+      paymentHash: data.payment_hash
+    };
+  }
+  async getDonation(id) {
+    const resp = await fetch(`${this.baseUrl}/api/v1/donations/${id}`);
+    if (!resp.ok) {
+      const err = await resp.json().catch(() => ({ error: "unknown" }));
+      throw new Error(
+        `Get donation failed (${resp.status}): ${err.error || JSON.stringify(err)}`
+      );
+    }
+    return resp.json();
+  }
+  async listDonations(params) {
+    const query = new URLSearchParams();
+    if (params?.limit != null) query.set("limit", String(params.limit));
+    if (params?.offset != null) query.set("offset", String(params.offset));
+    const qs = query.toString();
+    const resp = await fetch(
+      `${this.baseUrl}/api/v1/donations${qs ? `?${qs}` : ""}`
+    );
+    if (!resp.ok) {
+      const err = await resp.json().catch(() => ({ error: "unknown" }));
+      throw new Error(
+        `List donations failed (${resp.status}): ${err.error || JSON.stringify(err)}`
+      );
+    }
+    const data = await resp.json();
+    return data.donations;
+  }
+  async estimateFees(amountSat) {
+    const resp = await fetch(
+      `${this.baseUrl}/api/v1/estimate-fees?amount_msat=${amountSat * 1e3}`
+    );
+    if (!resp.ok) {
+      const err = await resp.json().catch(() => ({ error: "unknown" }));
+      throw new Error(
+        `Fee estimate failed (${resp.status}): ${err.error || JSON.stringify(err)}`
+      );
+    }
+    return resp.json();
+  }
+  /** Subscribe via WS, resolve on terminal status. */
+  waitForPayment(donationId, options) {
+    return new Promise((resolve, reject) => {
+      const wsUrl = this.baseUrl.replace(/^http/, "ws") + `/ws/donations/${donationId}`;
+      const ws = new WebSocket(wsUrl);
+      const TERMINAL = /* @__PURE__ */ new Set(["success", "failed", "expired"]);
+      let settled = false;
+      let timer;
+      const settle = (fn) => {
+        if (!settled) {
+          settled = true;
+          clearTimeout(timer);
+          fn();
+        }
+      };
+      ws.addEventListener("message", (event) => {
+        const msg = JSON.parse(String(event.data));
+        const status = msg.status;
+        options?.onStatusChange?.(status);
+        if (TERMINAL.has(status)) {
+          settle(() => resolve(status));
+          ws.close();
+        }
+      });
+      ws.addEventListener("error", () => {
+        settle(() => reject(new Error("WebSocket connection failed")));
+      });
+      ws.addEventListener("close", () => {
+        settle(() => reject(new Error("WebSocket closed before terminal status")));
+      });
+      if (options?.timeoutMs) {
+        timer = setTimeout(() => {
+          ws.close();
+          settle(() => reject(new Error("waitForPayment timed out")));
+        }, options.timeoutMs);
+      }
+    });
+  }
+};
+
+// src/qr.ts
+import { encode } from "uqr";
+
+// src/lightning.ts
+function isBolt12Offer(s) {
+  return s.startsWith("lno1");
+}
+function isLnAddress(s) {
+  const at = s.indexOf("@");
+  if (at < 1) return false;
+  const domain = s.slice(at + 1);
+  return domain.includes(".") && !domain.startsWith(".") && !domain.endsWith(".");
+}
+function detectDestinationType(s) {
+  if (isBolt12Offer(s)) return "bolt12Offer";
+  if (isLnAddress(s)) return "lnAddress";
+  return "unknown";
+}
+
+// src/qr.ts
+var SAFE_COLOR = /^#[0-9a-fA-F]{3,8}$|^rgb\(\d|^rgba\(\d|^[a-z]+$/;
+function invoiceToSvg(invoice, options) {
+  const size = options?.size ?? 256;
+  const color = options?.color ?? "#000";
+  if (!SAFE_COLOR.test(color)) throw new Error(`Invalid color: ${color}`);
+  const withPrefix = options?.withPrefix ?? true;
+  let content;
+  if (withPrefix && !isBolt12Offer(invoice)) {
+    content = `LIGHTNING:${invoice.toUpperCase()}`;
+  } else {
+    content = invoice;
+  }
+  const { data } = encode(content);
+  const modules = data.length;
+  const cellSize = size / modules;
+  let path = "";
+  for (let y = 0; y < modules; y++) {
+    for (let x = 0; x < modules; x++) {
+      if (data[y][x]) {
+        path += `M${x * cellSize},${y * cellSize}h${cellSize}v${cellSize}h-${cellSize}z`;
+      }
+    }
+  }
+  return [
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${size} ${size}" width="${size}" height="${size}">`,
+    `<rect width="100%" height="100%" fill="white"/>`,
+    `<path d="${path}" fill="${color}"/>`,
+    `</svg>`
+  ].join("");
+}
+function invoiceToDataUrl(invoice, options) {
+  const svg = invoiceToSvg(invoice, options);
+  return `data:image/svg+xml,${encodeURIComponent(svg)}`;
+}
+
+// src/webhook.ts
+var _crypto;
+async function getNodeCrypto2() {
+  if (_crypto) return _crypto;
+  if (_crypto === null) {
+    throw new Error(
+      "Webhook verification requires Node.js, Bun, or Deno (node:crypto not available)"
+    );
+  }
+  try {
+    _crypto = await import("crypto");
+    return _crypto;
+  } catch {
+    _crypto = null;
+    throw new Error(
+      "Webhook verification requires Node.js, Bun, or Deno (node:crypto not available)"
+    );
+  }
+}
+async function verifyWebhookSignature(body, signature, secret) {
+  const crypto2 = await getNodeCrypto2();
+  const expected = crypto2.createHmac("sha256", secret).update(body).digest();
+  try {
+    return crypto2.timingSafeEqual(expected, Buffer.from(signature, "hex"));
+  } catch {
+    return false;
+  }
+}
+async function parseWebhook(body, signature, secret) {
+  if (!await verifyWebhookSignature(body, signature, secret)) return null;
+  const text = typeof body === "string" ? body : new TextDecoder().decode(body);
+  return JSON.parse(text);
+}
+async function parseWebhookRequest(request, secret) {
+  const signature = request.headers.get("x-signature-256");
+  if (!signature) return null;
+  const body = await request.text();
+  return parseWebhook(body, signature, secret);
+}
+export {
+  RestGatewayClient,
+  detectDestinationType,
+  invoiceToDataUrl,
+  invoiceToSvg,
+  isBolt12Offer,
+  isLnAddress,
+  parseWebhook,
+  parseWebhookRequest,
+  solvePow,
+  verifyPow,
+  verifyWebhookSignature
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "fulgur-bridge-client",
+  "version": "0.0.1",
+  "description": "JavaScript client for the Fulgur Bridge Lightning donation proxy. REST API + WebSocket with PoW anti-spam.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "keywords": [
+    "lightning",
+    "bitcoin",
+    "donation",
+    "bolt12",
+    "lnurl",
+    "proof-of-work",
+    "websocket"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "uqr": "^0.1.2"
+  }
+}