fulgur-bridge-client 0.0.1

package/README.md

@@ -0,0 +1,255 @@
+# fulgur-bridge-client
+
+A Bitcoin Lightning "donate router". Accept payments straight into your own LN wallet and hook up any automation: trigger functions on your web app, ping a server, control IoT devices, whatever you need. A few lines of code to get started; swap in BTCPay Server when you outgrow it.
+
+REST API + WebSocket + PoW anti-spam + QR codes + webhook verification. Works in Node.js, Bun, Deno, browsers, and edge runtimes. Webhook verification requires `node:crypto` (Node.js, Bun, Deno).
+
+## Install
+
+```bash
+npm install fulgur-bridge-client
+```
+
+## Quick start
+
+```ts
+import { RestGatewayClient } from 'fulgur-bridge-client';
+
+const gw = new RestGatewayClient('https://your-gateway.example.com');
+
+// Create a donation
+const { id, bolt11 } = await gw.createDonation({
+  destination: 'alice@getalby.com',
+  amountSat: 100,
+});
+
+// Wait for payment via WebSocket
+const status = await gw.waitForPayment(id, {
+  onStatusChange(s) { console.log('status:', s); },
+});
+
+console.log(status); // "success" | "failed" | "expired"
+```
+
+## API
+
+### `new RestGatewayClient(gatewayUrl)`
+
+```ts
+const gw = new RestGatewayClient('https://donate.example.com');
+```
+
+---
+
+### `gw.createDonation(params)`
+
+Create a new donation. Automatically solves a PoW challenge if required by the gateway.
+
+```ts
+const { id, bolt11, paymentHash } = await gw.createDonation({
+  destination: 'alice@getalby.com', // Lightning Address or BOLT12 offer
+  amountSat: 100,              // amount in millisatoshis
+  webhookUrl: 'https://myapp.com/hook',    // optional
+  webhookSecret: 'my-hmac-secret',         // optional HMAC-SHA256 signing key
+});
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `destination` | `string` | Lightning Address (`user@domain`) or BOLT12 offer (`lno1...`) |
+| `amountSat` | `number` | Amount in satoshis (min 1) |
+| `webhookUrl` | `string?` | URL to POST on successful payout |
+| `webhookSecret` | `string?` | HMAC-SHA256 key for signing webhook payloads (sent to the gateway, use HTTPS) |
+
+Returns `{ id, bolt11, paymentHash }`.
+
+---
+
+### `gw.waitForPayment(donationId, options?)`
+
+Subscribe to donation status updates via WebSocket. Resolves when the donation reaches a terminal status (`success`, `failed`, or `expired`).
+
+```ts
+const status = await gw.waitForPayment(id, {
+  onStatusChange(s) { console.log(s); },
+  timeoutMs: 600_000, // 10 minutes
+});
+```
+
+---
+
+### `gw.getDonation(id)`
+
+Fetch a single donation by ID.
+
+```ts
+const donation = await gw.getDonation('550e8400-...');
+console.log(donation.status, donation.amount_msat);
+```
+
+---
+
+### `gw.listDonations(params?)`
+
+List donations with optional pagination.
+
+```ts
+const donations = await gw.listDonations({ limit: 10, offset: 0 });
+```
+
+---
+
+### `gw.estimateFees(amountMsat)`
+
+Estimate gateway fees for a given amount.
+
+```ts
+const fees = await gw.estimateFees(1_000);
+console.log(`Payout: ${fees.payout_estimate_sat} sat`);
+console.log(`Total fee: ${fees.total_fee_estimate_sat} sat`);
+```
+
+---
+
+## Webhooks
+
+When you provide `webhookUrl` on donation creation, the gateway POSTs a JSON payload to that URL immediately after a successful payout. If delivery fails, it retries with increasing delays: 10s, 1m, 2m, 5m, 10m, 30m, 1h, then hourly up to 1 week.
+
+### Payload
+
+```json
+{
+  "event": "donation.success",
+  "donation": {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "ln_address": "alice@getalby.com",
+    "amount_msat": 100000,
+    "status": "success",
+    "payment_hash": "abc123...",
+    "bolt11": "lnbc1000n1...",
+    "payout_fee_msat": 400,
+    "created_at": "2025-03-28T10:30:00Z",
+    "updated_at": "2025-03-28T10:31:00Z"
+  }
+}
+```
+
+### Headers
+
+| Header | Description |
+|--------|-------------|
+| `Content-Type` | `application/json` |
+| `X-Event-Type` | `donation.success` |
+| `X-Signature-256` | HMAC-SHA256 hex signature (only if `webhookSecret` was provided) |
+
+### Verifying signatures
+
+The client exports helpers to verify and parse webhook payloads:
+
+#### `parseWebhookRequest(request, secret)` / Fetch API (Hono, Next.js, SvelteKit, Remix, Deno, Bun)
+
+```ts
+import { parseWebhookRequest } from 'fulgur-bridge-client';
+
+// Hono
+app.post('/webhook', async (c) => {
+  const payload = await parseWebhookRequest(c.req.raw, MY_SECRET);
+  if (!payload) return c.text('Bad signature', 401);
+  console.log('Donation succeeded:', payload.donation.id);
+  return c.text('OK');
+});
+```
+
+```ts
+// Next.js app router (app/api/webhook/route.ts)
+import { parseWebhookRequest } from 'fulgur-bridge-client';
+
+export async function POST(req: Request) {
+  const payload = await parseWebhookRequest(req, process.env.WEBHOOK_SECRET!);
+  if (!payload) return new Response('Bad signature', { status: 401 });
+  // payload.donation is fully typed
+  return new Response('OK');
+}
+```
+
+#### `parseWebhook(body, signature, secret)` / Express / Fastify / raw body
+
+```ts
+import { parseWebhook } from 'fulgur-bridge-client';
+
+// Express (with express.raw() middleware on this route)
+app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
+  const sig = req.headers['x-signature-256'] as string;
+  const payload = await parseWebhook(req.body, sig, MY_SECRET);
+  if (!payload) return res.status(401).send('Bad signature');
+  console.log(payload.donation.id);
+  res.sendStatus(200);
+});
+```
+
+#### `verifyWebhookSignature(body, signature, secret)`
+
+```ts
+import { verifyWebhookSignature } from 'fulgur-bridge-client';
+
+const valid = await verifyWebhookSignature(rawBody, signature, secret);
+```
+
+All functions are async. All signature checks use constant-time comparison.
+
+---
+
+## QR codes
+
+Generate QR codes for Lightning invoices or BOLT12 offers. Returns SVG strings, no canvas or browser APIs needed.
+
+```ts
+import { invoiceToSvg, invoiceToDataUrl } from 'fulgur-bridge-client';
+
+// SVG string (for innerHTML, SSR, etc.)
+const svg = invoiceToSvg(bolt11, { size: 300, color: '#1a1a2e' });
+
+// Data URL (for <img src="...">)
+const dataUrl = invoiceToDataUrl(bolt11);
+```
+
+BOLT11 invoices get a `LIGHTNING:` prefix for better wallet compatibility. BOLT12 offers are encoded as-is.
+
+---
+
+## Utilities
+
+### Lightning address detection
+
+Basic format checks for UI heuristics (icon switching, input hints). Full validation happens server-side.
+
+```ts
+import { isLnAddress, isBolt12Offer, detectDestinationType } from 'fulgur-bridge-client';
+
+isLnAddress('alice@getalby.com');              // true
+isBolt12Offer('lno1qgsqvgnwgcg35z6...');      // true
+detectDestinationType('alice@getalby.com');     // "lnAddress"
+```
+
+### PoW solver
+
+The gateway requires proof-of-work when an IP creates too many unpaid invoices (anti-spam). `createDonation()` handles this transparently. Picks the fastest available strategy:
+
+1. `node:crypto` (native C++): Node.js, Bun, Deno
+2. Pure JS SHA-256: Cloudflare Workers, edge runtimes
+3. `crypto.subtle` (async, yielding): browsers
+
+```ts
+import { solvePow, verifyPow } from 'fulgur-bridge-client';
+
+const nonce = await solvePow(challenge, difficulty);
+const valid = await verifyPow(challenge, nonce, difficulty);
+```
+
+---
+
+All types (`Donation`, `DonationStatus`, `CreateDonationParams`, `WebhookPayload`, etc.) are exported from the package root.
+
+## License
+
+MIT