@thecryptodonkey/toll-booth 1.0.0

package/dist/backends/lnbits.js

@@ -0,0 +1,58 @@
+/**
+ * Lightning backend adapter for LNbits.
+ *
+ * Uses the LNbits Payments API with `X-Api-Key` header authentication.
+ * Works with any LNbits instance — self-hosted or hosted (legend.lnbits.com).
+ *
+ * LNbits abstracts over multiple funding sources (LND, CLN, Phoenixd,
+ * LndHub, etc.), so this backend supports any node type that LNbits
+ * connects to.
+ *
+ * @see https://lnbits.com/
+ */
+export function lnbitsBackend(config) {
+    const baseUrl = config.url.replace(/\/$/, '');
+    const timeoutMs = config.timeout ?? 30_000;
+    const headers = {
+        'X-Api-Key': config.apiKey,
+        'Content-Type': 'application/json',
+    };
+    return {
+        async createInvoice(amountSats, memo) {
+            const res = await fetch(`${baseUrl}/api/v1/payments`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({
+                    out: false,
+                    amount: amountSats,
+                    memo: memo ?? 'toll-booth payment',
+                }),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                throw new Error(`LNbits createInvoice failed (${res.status}): ${text}`);
+            }
+            const data = await res.json();
+            return { bolt11: data.payment_request, paymentHash: data.payment_hash };
+        },
+        async checkInvoice(paymentHash) {
+            const res = await fetch(`${baseUrl}/api/v1/payments/${paymentHash}`, {
+                headers: { 'X-Api-Key': config.apiKey },
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (res.status === 404)
+                return { paid: false };
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                throw new Error(`LNbits checkInvoice failed (${res.status}): ${text}`);
+            }
+            const data = await res.json();
+            return {
+                paid: data.paid,
+                preimage: data.paid ? data.preimage : undefined,
+            };
+        },
+    };
+}
+//# sourceMappingURL=lnbits.js.map

package/dist/backends/lnbits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lnbits.js","sourceRoot":"","sources":["../../src/backends/lnbits.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,MAAoB;IAChD,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IAC7C,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,IAAI,MAAM,CAAA;IAC1C,MAAM,OAAO,GAA2B;QACtC,WAAW,EAAE,MAAM,CAAC,MAAM;QAC1B,cAAc,EAAE,kBAAkB;KACnC,CAAA;IAED,OAAO;QACL,KAAK,CAAC,aAAa,CAAC,UAAkB,EAAE,IAAa;YACnD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,kBAAkB,EAAE;gBACpD,MAAM,EAAE,MAAM;gBACd,OAAO;gBACP,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,GAAG,EAAE,KAAK;oBACV,MAAM,EAAE,UAAU;oBAClB,IAAI,EAAE,IAAI,IAAI,oBAAoB;iBACnC,CAAC;gBACF,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC;aACvC,CAAC,CAAA;YAEF,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;gBAC7C,MAAM,IAAI,KAAK,CAAC,gCAAgC,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAA;YACzE,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAuD,CAAA;YAClF,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,EAAE,IAAI,CAAC,YAAY,EAAE,CAAA;QACzE,CAAC;QAED,KAAK,CAAC,YAAY,CAAC,WAAmB;YACpC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,oBAAoB,WAAW,EAAE,EAAE;gBACnE,OAAO,EAAE,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE;gBACvC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC;aACvC,CAAC,CAAA;YAEF,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;gBAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAA;YAE9C,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;gBAC7C,MAAM,IAAI,KAAK,CAAC,+BAA+B,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAA;YACxE,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAA0C,CAAA;YACrE,OAAO;gBACL,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;aAChD,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/backends/lnd.d.ts

@@ -0,0 +1,21 @@
+import type { LightningBackend } from '../types.js';
+export interface LndConfig {
+    /** LND REST API URL (e.g. https://localhost:8080) */
+    url: string;
+    /** Admin macaroon as hex string */
+    macaroon?: string;
+    /** Path to admin.macaroon file (alternative to hex) */
+    macaroonPath?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Lightning backend adapter for LND's REST API.
+ *
+ * Authenticates via the `Grpc-Metadata-macaroon` header using a hex-encoded
+ * admin macaroon. The macaroon can be provided directly or read from a file.
+ *
+ * @see https://lightning.engineering/api-docs/api/lnd/
+ */
+export declare function lndBackend(config: LndConfig): LightningBackend;
+//# sourceMappingURL=lnd.d.ts.map

package/dist/backends/lnd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lnd.d.ts","sourceRoot":"","sources":["../../src/backends/lnd.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAA0B,MAAM,aAAa,CAAA;AAG3E,MAAM,WAAW,SAAS;IACxB,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAA;IACX,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,gBAAgB,CAsD9D"}

package/dist/backends/lnd.js

@@ -0,0 +1,59 @@
+import { readFileSync } from 'node:fs';
+/**
+ * Lightning backend adapter for LND's REST API.
+ *
+ * Authenticates via the `Grpc-Metadata-macaroon` header using a hex-encoded
+ * admin macaroon. The macaroon can be provided directly or read from a file.
+ *
+ * @see https://lightning.engineering/api-docs/api/lnd/
+ */
+export function lndBackend(config) {
+    const baseUrl = config.url.replace(/\/$/, '');
+    const timeoutMs = config.timeout ?? 30_000;
+    let macaroonHex;
+    if (config.macaroon) {
+        macaroonHex = config.macaroon;
+    }
+    else if (config.macaroonPath) {
+        macaroonHex = readFileSync(config.macaroonPath).toString('hex');
+    }
+    else {
+        throw new Error('LND backend requires either macaroon (hex) or macaroonPath');
+    }
+    return {
+        async createInvoice(amountSats, memo) {
+            const res = await fetch(`${baseUrl}/v1/invoices`, {
+                method: 'POST',
+                headers: {
+                    'Grpc-Metadata-macaroon': macaroonHex,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ value: String(amountSats), memo: memo ?? '' }),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                throw new Error(`LND createinvoice failed (${res.status}): ${text}`);
+            }
+            const data = await res.json();
+            const paymentHash = Buffer.from(data.r_hash, 'base64').toString('hex');
+            return { bolt11: data.payment_request, paymentHash };
+        },
+        async checkInvoice(paymentHash) {
+            const res = await fetch(`${baseUrl}/v1/invoice/${paymentHash}`, {
+                headers: { 'Grpc-Metadata-macaroon': macaroonHex },
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (!res.ok)
+                return { paid: false };
+            const data = await res.json();
+            return {
+                paid: data.settled,
+                preimage: data.settled && data.r_preimage
+                    ? Buffer.from(data.r_preimage, 'base64').toString('hex')
+                    : undefined,
+            };
+        },
+    };
+}
+//# sourceMappingURL=lnd.js.map

package/dist/backends/lnd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lnd.js","sourceRoot":"","sources":["../../src/backends/lnd.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAatC;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,MAAiB;IAC1C,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IAC7C,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,IAAI,MAAM,CAAA;IAE1C,IAAI,WAAmB,CAAA;IACvB,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACpB,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAA;IAC/B,CAAC;SAAM,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QAC/B,WAAW,GAAG,YAAY,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;IACjE,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAA;IAC/E,CAAC;IAED,OAAO;QACL,KAAK,CAAC,aAAa,CAAC,UAAkB,EAAE,IAAa;YACnD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,cAAc,EAAE;gBAChD,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,wBAAwB,EAAE,WAAW;oBACrC,cAAc,EAAE,kBAAkB;iBACnC;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC;gBACrE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC;aACvC,CAAC,CAAA;YAEF,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;gBAC7C,MAAM,IAAI,KAAK,CAAC,6BAA6B,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAA;YACtE,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAiD,CAAA;YAC5E,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;YAEtE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,EAAE,CAAA;QACtD,CAAC;QAED,KAAK,CAAC,YAAY,CAAC,WAAmB;YACpC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,eAAe,WAAW,EAAE,EAAE;gBAC9D,OAAO,EAAE,EAAE,wBAAwB,EAAE,WAAW,EAAE;gBAClD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC;aACvC,CAAC,CAAA;YAEF,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAA;YAEnC,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAA+C,CAAA;YAE1E,OAAO;gBACL,IAAI,EAAE,IAAI,CAAC,OAAO;gBAClB,QAAQ,EAAE,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,UAAU;oBACvC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;oBACxD,CAAC,CAAC,SAAS;aACd,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/backends/phoenixd.d.ts

@@ -0,0 +1,19 @@
+import type { LightningBackend } from '../types.js';
+export interface PhoenixdConfig {
+    url: string;
+    password: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Lightning backend adapter for Phoenixd's HTTP API.
+ *
+ * Phoenixd uses HTTP Basic auth with an empty username — the Authorization
+ * header encodes `:password` (note the leading colon) in base64.
+ * The createinvoice endpoint expects an `application/x-www-form-urlencoded`
+ * POST body, not JSON.
+ *
+ * @see https://phoenix.acinq.co/server/api
+ */
+export declare function phoenixdBackend(config: PhoenixdConfig): LightningBackend;
+//# sourceMappingURL=phoenixd.d.ts.map

package/dist/backends/phoenixd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phoenixd.d.ts","sourceRoot":"","sources":["../../src/backends/phoenixd.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAA0B,MAAM,aAAa,CAAA;AAE3E,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,MAAM,CAAA;IAChB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,gBAAgB,CAqDxE"}

package/dist/backends/phoenixd.js

@@ -0,0 +1,59 @@
+/**
+ * Lightning backend adapter for Phoenixd's HTTP API.
+ *
+ * Phoenixd uses HTTP Basic auth with an empty username — the Authorization
+ * header encodes `:password` (note the leading colon) in base64.
+ * The createinvoice endpoint expects an `application/x-www-form-urlencoded`
+ * POST body, not JSON.
+ *
+ * @see https://phoenix.acinq.co/server/api
+ */
+export function phoenixdBackend(config) {
+    const baseUrl = config.url.replace(/\/$/, '');
+    const authHeader = 'Basic ' + Buffer.from(`:${config.password}`).toString('base64');
+    const timeoutMs = config.timeout ?? 30_000;
+    return {
+        async createInvoice(amountSats, memo) {
+            const body = new URLSearchParams();
+            body.set('amountSat', String(amountSats));
+            if (memo)
+                body.set('description', memo);
+            body.set('externalId', '');
+            const res = await fetch(`${baseUrl}/createinvoice`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': authHeader,
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                },
+                body,
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                throw new Error(`Phoenixd createinvoice failed (${res.status}): ${text}`);
+            }
+            const data = await res.json();
+            return { bolt11: data.serialized, paymentHash: data.paymentHash };
+        },
+        async checkInvoice(paymentHash) {
+            const res = await fetch(`${baseUrl}/payments/incoming/${paymentHash}`, {
+                headers: { 'Authorization': authHeader },
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            // 404 = invoice not found (normal for unknown hashes)
+            if (res.status === 404)
+                return { paid: false };
+            // Auth failures and server errors must propagate so health checks detect them
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                throw new Error(`Phoenixd checkInvoice failed (${res.status}): ${text}`);
+            }
+            const data = await res.json();
+            return {
+                paid: data.isPaid,
+                preimage: data.isPaid ? data.preimage : undefined,
+            };
+        },
+    };
+}
+//# sourceMappingURL=phoenixd.js.map

package/dist/backends/phoenixd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phoenixd.js","sourceRoot":"","sources":["../../src/backends/phoenixd.ts"],"names":[],"mappings":"AASA;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,MAAsB;IACpD,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IAC7C,MAAM,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;IACnF,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,IAAI,MAAM,CAAA;IAE1C,OAAO;QACL,KAAK,CAAC,aAAa,CAAC,UAAkB,EAAE,IAAa;YACnD,MAAM,IAAI,GAAG,IAAI,eAAe,EAAE,CAAA;YAClC,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,CAAA;YACzC,IAAI,IAAI;gBAAE,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,CAAC,CAAA;YACvC,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,EAAE,CAAC,CAAA;YAE1B,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,gBAAgB,EAAE;gBAClD,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,eAAe,EAAE,UAAU;oBAC3B,cAAc,EAAE,mCAAmC;iBACpD;gBACD,IAAI;gBACJ,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC;aACvC,CAAC,CAAA;YAEF,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;gBAC7C,MAAM,IAAI,KAAK,CAAC,kCAAkC,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAA;YAC3E,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAiD,CAAA;YAC5E,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAA;QACnE,CAAC;QAED,KAAK,CAAC,YAAY,CAAC,WAAmB;YACpC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,sBAAsB,WAAW,EAAE,EAAE;gBACrE,OAAO,EAAE,EAAE,eAAe,EAAE,UAAU,EAAE;gBACxC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC;aACvC,CAAC,CAAA;YAEF,sDAAsD;YACtD,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;gBAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAA;YAE9C,8EAA8E;YAC9E,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;gBAC7C,MAAM,IAAI,KAAK,CAAC,iCAAiC,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAA;YAC1E,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAA4C,CAAA;YACvE,OAAO;gBACL,IAAI,EAAE,IAAI,CAAC,MAAM;gBACjB,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;aAClD,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/booth.d.ts

@@ -0,0 +1,54 @@
+import type { BoothConfig, EventHandler } from './types.js';
+import type { StorageBackend } from './storage/interface.js';
+import { StatsCollector } from './stats.js';
+export type AdapterType = 'express' | 'web-standard';
+export interface BoothOptions extends BoothConfig {
+    adapter: AdapterType;
+    storage?: StorageBackend;
+}
+/**
+ * Encapsulates the middleware, invoice-status handler, create-invoice handler,
+ * and wallet adapter endpoints with shared internal state.
+ *
+ * The `adapter` option selects the framework integration:
+ * - `'express'` — Express middleware and handlers
+ * - `'web-standard'` — Web Standards (Request/Response) handlers
+ *
+ * ```typescript
+ * const booth = new Booth({ adapter: 'express', ...config })
+ * app.get('/invoice-status/:paymentHash', booth.invoiceStatusHandler)
+ * app.post('/create-invoice', booth.createInvoiceHandler)
+ * app.use('/*', booth.middleware)
+ * ```
+ */
+export declare class Booth {
+    readonly middleware: unknown;
+    readonly invoiceStatusHandler: unknown;
+    readonly createInvoiceHandler: unknown;
+    readonly nwcPayHandler?: unknown;
+    readonly cashuRedeemHandler?: unknown;
+    /** Aggregate usage statistics. Resets on restart. */
+    readonly stats: StatsCollector;
+    private readonly storage;
+    private readonly engine;
+    private readonly rootKey;
+    private readonly redeemCashu?;
+    private readonly pruneTimer?;
+    constructor(config: BoothOptions & EventHandler);
+    /** Reset free-tier counters for all IPs. */
+    resetFreeTier(): void;
+    /**
+     * Recover Cashu redemptions that were claimed but never settled (crash recovery).
+     * Automatically called on startup when Cashu is enabled. Can also be called
+     * manually. This requires an idempotent `redeemCashu` implementation keyed by
+     * `paymentHash`. For each pending claim, retries the redeem call:
+     * - If recovery lease is acquired: attempts redeem
+     * - On success: settles with the credited amount
+     * - On failure: leaves the claim pending for the next recovery attempt
+     *
+     * Returns the number of successfully recovered claims.
+     */
+    recoverPendingClaims(redeemFn: (token: string, paymentHash: string) => Promise<number>): Promise<number>;
+    close(): void;
+}
+//# sourceMappingURL=booth.d.ts.map

package/dist/booth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"booth.d.ts","sourceRoot":"","sources":["../src/booth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAM5D,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAmB3C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,cAAc,CAAA;AAEpD,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC/C,OAAO,EAAE,WAAW,CAAA;IACpB,OAAO,CAAC,EAAE,cAAc,CAAA;CACzB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,KAAK;IAChB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAA;IACtC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAA;IACtC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAA;IAChC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAErC,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;IAE9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAyD;IACtF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAgC;gBAEhD,MAAM,EAAE,YAAY,GAAG,YAAY;IAgI/C,4CAA4C;IAC5C,aAAa,IAAI,IAAI;IAIrB;;;;;;;;;;OAUG;IACG,oBAAoB,CACxB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAChE,OAAO,CAAC,MAAM,CAAC;IA6BlB,KAAK,IAAI,IAAI;CAId"}

package/dist/booth.js

@@ -0,0 +1,200 @@
+import { createTollBooth } from './core/toll-booth.js';
+import { sqliteStorage } from './storage/sqlite.js';
+import { StatsCollector } from './stats.js';
+import { randomBytes } from 'node:crypto';
+import { REDEEM_LEASE_MS } from './core/cashu-redeem.js';
+import { createExpressMiddleware, createExpressInvoiceStatusHandler, createExpressCreateInvoiceHandler, createExpressNwcHandler, createExpressCashuHandler, } from './adapters/express.js';
+import { createWebStandardMiddleware, createWebStandardInvoiceStatusHandler, createWebStandardCreateInvoiceHandler, createWebStandardNwcHandler, createWebStandardCashuHandler, } from './adapters/web-standard.js';
+/**
+ * Encapsulates the middleware, invoice-status handler, create-invoice handler,
+ * and wallet adapter endpoints with shared internal state.
+ *
+ * The `adapter` option selects the framework integration:
+ * - `'express'` — Express middleware and handlers
+ * - `'web-standard'` — Web Standards (Request/Response) handlers
+ *
+ * ```typescript
+ * const booth = new Booth({ adapter: 'express', ...config })
+ * app.get('/invoice-status/:paymentHash', booth.invoiceStatusHandler)
+ * app.post('/create-invoice', booth.createInvoiceHandler)
+ * app.use('/*', booth.middleware)
+ * ```
+ */
+export class Booth {
+    middleware;
+    invoiceStatusHandler;
+    createInvoiceHandler;
+    nwcPayHandler;
+    cashuRedeemHandler;
+    /** Aggregate usage statistics. Resets on restart. */
+    stats;
+    storage;
+    engine;
+    rootKey;
+    redeemCashu;
+    pruneTimer;
+    constructor(config) {
+        if (!config.backend && !config.redeemCashu) {
+            throw new Error('At least one payment method required: provide a Lightning backend, redeemCashu callback, or both');
+        }
+        const rootKeyInput = config.rootKey ?? randomBytes(32).toString('hex');
+        if (!/^[0-9a-fA-F]{64}$/.test(rootKeyInput)) {
+            throw new Error('rootKey must be exactly 64 hex characters (32 bytes)');
+        }
+        this.rootKey = rootKeyInput;
+        if (config.storage && config.dbPath) {
+            throw new Error('Provide either storage or dbPath, not both');
+        }
+        this.storage = config.storage ?? sqliteStorage({ path: config.dbPath ?? './toll-booth.db' });
+        this.stats = new StatsCollector();
+        const defaultAmount = config.defaultInvoiceAmount ?? 1000;
+        // Wire stats collection while preserving user-provided callbacks
+        const userOnPayment = config.onPayment;
+        const userOnRequest = config.onRequest;
+        const userOnChallenge = config.onChallenge;
+        const stats = this.stats;
+        this.engine = createTollBooth({
+            backend: config.backend,
+            storage: this.storage,
+            pricing: config.pricing,
+            upstream: config.upstream,
+            defaultInvoiceAmount: defaultAmount,
+            rootKey: this.rootKey,
+            freeTier: config.freeTier,
+            strictPricing: config.strictPricing,
+            creditTiers: config.creditTiers,
+            onPayment: (event) => {
+                stats.recordPayment(event);
+                userOnPayment?.(event);
+            },
+            onRequest: (event) => {
+                stats.recordRequest(event);
+                userOnRequest?.(event);
+            },
+            onChallenge: (event) => {
+                stats.recordChallenge(event);
+                userOnChallenge?.(event);
+            },
+        });
+        const createInvoiceDeps = {
+            backend: config.backend,
+            storage: this.storage,
+            rootKey: this.rootKey,
+            tiers: config.creditTiers ?? [],
+            defaultAmount,
+        };
+        const invoiceStatusDeps = {
+            backend: config.backend,
+            storage: this.storage,
+            tiers: config.creditTiers,
+            nwcEnabled: !!config.nwcPayInvoice,
+            cashuEnabled: !!config.redeemCashu,
+        };
+        const upstream = config.upstream.replace(/\/$/, '');
+        const adapterConfig = {
+            engine: this.engine,
+            upstream,
+            trustProxy: config.trustProxy,
+            getClientIp: config.getClientIp,
+            responseHeaders: config.responseHeaders,
+            upstreamTimeout: config.upstreamTimeout,
+        };
+        const nwcPayDeps = config.nwcPayInvoice
+            ? { nwcPay: config.nwcPayInvoice, storage: this.storage }
+            : undefined;
+        const cashuRedeemDeps = config.redeemCashu
+            ? { redeem: config.redeemCashu, storage: this.storage }
+            : undefined;
+        switch (config.adapter) {
+            case 'express':
+                this.middleware = createExpressMiddleware(adapterConfig);
+                this.invoiceStatusHandler = createExpressInvoiceStatusHandler(invoiceStatusDeps);
+                this.createInvoiceHandler = createExpressCreateInvoiceHandler(createInvoiceDeps);
+                if (nwcPayDeps)
+                    this.nwcPayHandler = createExpressNwcHandler(nwcPayDeps);
+                if (cashuRedeemDeps) {
+                    this.redeemCashu = config.redeemCashu;
+                    this.cashuRedeemHandler = createExpressCashuHandler(cashuRedeemDeps);
+                }
+                break;
+            case 'web-standard':
+                this.middleware = createWebStandardMiddleware(adapterConfig);
+                this.invoiceStatusHandler = createWebStandardInvoiceStatusHandler(invoiceStatusDeps);
+                this.createInvoiceHandler = createWebStandardCreateInvoiceHandler(createInvoiceDeps);
+                if (nwcPayDeps)
+                    this.nwcPayHandler = createWebStandardNwcHandler(nwcPayDeps);
+                if (cashuRedeemDeps) {
+                    this.redeemCashu = config.redeemCashu;
+                    this.cashuRedeemHandler = createWebStandardCashuHandler(cashuRedeemDeps);
+                }
+                break;
+        }
+        // Invoice expiry pruning
+        const maxAge = config.invoiceMaxAgeMs ?? 86_400_000; // 24 hours
+        if (maxAge > 0) {
+            const timer = setInterval(() => {
+                this.storage.pruneExpiredInvoices(maxAge);
+                this.storage.pruneStaleRecords(maxAge);
+            }, 3_600_000); // every hour
+            timer.unref();
+            this.pruneTimer = timer;
+        }
+        // Auto-recover any pending Cashu claims from a previous crash
+        if (this.redeemCashu) {
+            const fn = this.redeemCashu;
+            this.recoverPendingClaims(fn).catch(() => {
+                // Recovery failures are non-fatal; claims stay pending for next restart
+            });
+        }
+    }
+    /** Reset free-tier counters for all IPs. */
+    resetFreeTier() {
+        this.engine.freeTier?.reset();
+    }
+    /**
+     * Recover Cashu redemptions that were claimed but never settled (crash recovery).
+     * Automatically called on startup when Cashu is enabled. Can also be called
+     * manually. This requires an idempotent `redeemCashu` implementation keyed by
+     * `paymentHash`. For each pending claim, retries the redeem call:
+     * - If recovery lease is acquired: attempts redeem
+     * - On success: settles with the credited amount
+     * - On failure: leaves the claim pending for the next recovery attempt
+     *
+     * Returns the number of successfully recovered claims.
+     */
+    async recoverPendingClaims(redeemFn) {
+        const claims = this.storage.pendingClaims();
+        let recovered = 0;
+        const renewIntervalMs = Math.max(1_000, Math.floor(REDEEM_LEASE_MS / 2));
+        for (const claim of claims) {
+            // Respect active leases so startup recovery does not race in-flight requests
+            // (or another process already handling this claim).
+            const leasedClaim = this.storage.tryAcquireRecoveryLease(claim.paymentHash, REDEEM_LEASE_MS);
+            if (!leasedClaim)
+                continue;
+            const timer = setInterval(() => {
+                this.storage.extendRecoveryLease(leasedClaim.paymentHash, REDEEM_LEASE_MS);
+            }, renewIntervalMs);
+            try {
+                const credited = await redeemFn(leasedClaim.token, leasedClaim.paymentHash);
+                if (this.storage.settleWithCredit(leasedClaim.paymentHash, credited)) {
+                    recovered++;
+                }
+            }
+            catch {
+                // Transient failure (network, mint outage) — leave claim pending
+                // for the next recovery attempt. Do NOT settle with 0.
+            }
+            finally {
+                clearInterval(timer);
+            }
+        }
+        return recovered;
+    }
+    close() {
+        if (this.pruneTimer)
+            clearInterval(this.pruneTimer);
+        this.storage.close();
+    }
+}
+//# sourceMappingURL=booth.js.map

package/dist/booth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"booth.js","sourceRoot":"","sources":["../src/booth.ts"],"names":[],"mappings":"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"}

package/dist/core/cashu-redeem.d.ts

@@ -0,0 +1,9 @@
+import type { StorageBackend } from '../storage/interface.js';
+import type { CashuRedeemRequest, CashuRedeemResult } from './types.js';
+export declare const REDEEM_LEASE_MS = 30000;
+export interface CashuRedeemDeps {
+    redeem: (token: string, paymentHash: string) => Promise<number>;
+    storage: StorageBackend;
+}
+export declare function handleCashuRedeem(deps: CashuRedeemDeps, request: CashuRedeemRequest): Promise<CashuRedeemResult>;
+//# sourceMappingURL=cashu-redeem.d.ts.map

package/dist/core/cashu-redeem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cashu-redeem.d.ts","sourceRoot":"","sources":["../../src/core/cashu-redeem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAC7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAGvE,eAAO,MAAM,eAAe,QAAS,CAAA;AAGrC,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC/D,OAAO,EAAE,cAAc,CAAA;CACxB;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CA8E5B"}

package/dist/core/cashu-redeem.js

@@ -0,0 +1,85 @@
+import { PAYMENT_HASH_RE } from './types.js';
+export const REDEEM_LEASE_MS = 30_000;
+const REDEEM_LEASE_RENEW_MS = Math.max(1_000, Math.floor(REDEEM_LEASE_MS / 2));
+export async function handleCashuRedeem(deps, request) {
+    try {
+        const { token, paymentHash, statusToken } = request;
+        if (typeof token !== 'string' || !token ||
+            !PAYMENT_HASH_RE.test(paymentHash) ||
+            typeof statusToken !== 'string' || !statusToken) {
+            return { success: false, error: 'Invalid request: token, paymentHash, and statusToken required', status: 400 };
+        }
+        const invoice = deps.storage.getInvoiceForStatus(paymentHash, statusToken);
+        if (!invoice) {
+            return { success: false, error: 'Unknown payment hash or invalid status token', status: 400 };
+        }
+        // Fast path: already settled
+        if (deps.storage.isSettled(paymentHash)) {
+            return {
+                success: true,
+                credited: 0,
+                tokenSuffix: deps.storage.getSettlementSecret(paymentHash) ?? '',
+            };
+        }
+        // Try to claim exclusively before the irreversible external redeem call.
+        if (!deps.storage.claimForRedeem(paymentHash, token, REDEEM_LEASE_MS)) {
+            // Already settled — idempotent success
+            if (deps.storage.isSettled(paymentHash)) {
+                return {
+                    success: true,
+                    credited: 0,
+                    tokenSuffix: deps.storage.getSettlementSecret(paymentHash) ?? '',
+                };
+            }
+            // Retry an expired lease. This is only correct when the redeem
+            // implementation is idempotent for the same paymentHash.
+            const pendingClaim = deps.storage.tryAcquireRecoveryLease(paymentHash, REDEEM_LEASE_MS);
+            if (pendingClaim) {
+                try {
+                    const credited = await withLeaseKeepAlive(deps.storage, paymentHash, () => deps.redeem(pendingClaim.token, paymentHash));
+                    const settlementSecret = globalThis.crypto.randomUUID();
+                    const newlySettled = deps.storage.settleWithCredit(paymentHash, credited, settlementSecret);
+                    return {
+                        success: true,
+                        credited: newlySettled ? credited : 0,
+                        tokenSuffix: newlySettled ? settlementSecret : deps.storage.getSettlementSecret(paymentHash) ?? '',
+                    };
+                }
+                catch {
+                    return { success: false, state: 'pending', retryAfterMs: 2000 };
+                }
+            }
+            return { success: false, state: 'pending', retryAfterMs: 2000 };
+        }
+        // We hold the exclusive claim — call the external mint
+        try {
+            const credited = await withLeaseKeepAlive(deps.storage, paymentHash, () => deps.redeem(token, paymentHash));
+            const settlementSecret = globalThis.crypto.randomUUID();
+            const newlySettled = deps.storage.settleWithCredit(paymentHash, credited, settlementSecret);
+            return {
+                success: true,
+                credited: newlySettled ? credited : 0,
+                tokenSuffix: newlySettled ? settlementSecret : deps.storage.getSettlementSecret(paymentHash) ?? '',
+            };
+        }
+        catch {
+            return { success: false, state: 'pending', retryAfterMs: 2000 };
+        }
+    }
+    catch (err) {
+        console.error('[toll-booth] Cashu redeem error:', err instanceof Error ? err.message : err);
+        return { success: false, error: 'Cashu redemption failed', status: 500 };
+    }
+}
+async function withLeaseKeepAlive(storage, paymentHash, fn) {
+    const timer = setInterval(() => {
+        storage.extendRecoveryLease(paymentHash, REDEEM_LEASE_MS);
+    }, REDEEM_LEASE_RENEW_MS);
+    try {
+        return await fn();
+    }
+    finally {
+        clearInterval(timer);
+    }
+}
+//# sourceMappingURL=cashu-redeem.js.map

package/dist/core/cashu-redeem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cashu-redeem.js","sourceRoot":"","sources":["../../src/core/cashu-redeem.ts"],"names":[],"mappings":"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"}

package/dist/core/create-invoice.d.ts

@@ -0,0 +1,19 @@
+import type { LightningBackend, CreditTier } from '../types.js';
+import type { StorageBackend } from '../storage/interface.js';
+import type { CreateInvoiceRequest, CreateInvoiceResult } from './types.js';
+export interface CreateInvoiceDeps {
+    backend?: LightningBackend;
+    storage: StorageBackend;
+    rootKey: string;
+    tiers: CreditTier[];
+    defaultAmount: number;
+}
+/**
+ * Framework-agnostic invoice creation handler.
+ *
+ * Validates the requested amount against configured tiers (if any),
+ * creates a new Lightning invoice, mints a macaroon, stores everything,
+ * and returns structured result data.
+ */
+export declare function handleCreateInvoice(deps: CreateInvoiceDeps, request: CreateInvoiceRequest): Promise<CreateInvoiceResult>;
+//# sourceMappingURL=create-invoice.d.ts.map