@thecryptodonkey/toll-booth 3.5.0 → 3.7.0

package/dist/core/melt-to-lightning.d.ts

@@ -0,0 +1,24 @@
+import type { Proof } from '@cashu/cashu-ts';
+export type MeltResult = {
+    paid: true;
+    amountSats: number;
+    preimage?: string;
+} | {
+    paid: false;
+    error: string;
+};
+/**
+ * Melts Cashu proofs to pay a Lightning invoice on the operator's node.
+ * Handles the full flow: invoice creation → melt quote → coin selection → melt.
+ * Discards change proofs (fee overpayment donated to mint).
+ *
+ * @param opts.mintUrl - The mint that issued the proofs
+ * @param opts.proofs - Server-side proofs from wallet.receive()
+ * @param opts.createInvoice - Callback to create a BOLT11 invoice on the operator's node
+ */
+export declare function meltToLightning(opts: {
+    mintUrl: string;
+    proofs: Proof[];
+    createInvoice: (amountSats: number) => Promise<string>;
+}): Promise<MeltResult>;
+//# sourceMappingURL=melt-to-lightning.d.ts.map

package/dist/core/melt-to-lightning.js

@@ -0,0 +1,43 @@
+import { Wallet } from '@cashu/cashu-ts';
+/**
+ * Melts Cashu proofs to pay a Lightning invoice on the operator's node.
+ * Handles the full flow: invoice creation → melt quote → coin selection → melt.
+ * Discards change proofs (fee overpayment donated to mint).
+ *
+ * @param opts.mintUrl - The mint that issued the proofs
+ * @param opts.proofs - Server-side proofs from wallet.receive()
+ * @param opts.createInvoice - Callback to create a BOLT11 invoice on the operator's node
+ */
+export async function meltToLightning(opts) {
+    const { mintUrl, proofs, createInvoice } = opts;
+    const totalSats = proofs.reduce((sum, p) => sum + p.amount, 0);
+    if (totalSats <= 0) {
+        return { paid: false, error: 'No proofs to melt' };
+    }
+    const wallet = new Wallet(mintUrl, { unit: 'sat' });
+    // Create invoice for the full proof amount
+    const invoice = await createInvoice(totalSats);
+    // Get melt quote to learn fee_reserve
+    const meltQuote = await wallet.createMeltQuoteBolt11(invoice);
+    const needed = meltQuote.amount + meltQuote.fee_reserve;
+    if (needed > totalSats) {
+        return {
+            paid: false,
+            error: `Proofs insufficient for fees (have ${totalSats}, need ${needed} including ${meltQuote.fee_reserve} fee reserve)`,
+        };
+    }
+    // Coin selection
+    const { send } = await wallet.send(needed, proofs, { includeFees: true });
+    // Melt — pay the Lightning invoice via the mint
+    const meltResponse = await wallet.meltProofsBolt11(meltQuote, send);
+    if (meltResponse.quote.state === 'PAID') {
+        // Discard change proofs (keep + change) — bearer instruments not retained
+        return {
+            paid: true,
+            amountSats: meltQuote.amount,
+            preimage: meltResponse.quote.payment_preimage ?? undefined,
+        };
+    }
+    return { paid: false, error: `Melt state: ${meltResponse.quote.state}` };
+}
+//# sourceMappingURL=melt-to-lightning.js.map

package/dist/core/toll-booth.js

@@ -65,6 +65,19 @@ export function createTollBooth(config) {
                 const challengeHeaders = {};
                 const challengeBody = {};
                 const normalisedPrice = normalisedPricing[req.path] ?? { sats: defaultAmount };
+                // HEAD requests return a lightweight price probe without creating
+                // invoices or storing state. Useful for lnget --dry-run and indexers.
+                if (req.method === 'HEAD') {
+                    if (normalisedPrice.sats !== undefined) {
+                        challengeHeaders['X-L402-Price-Sats'] = String(normalisedPrice.sats);
+                    }
+                    if (normalisedPrice.usd !== undefined) {
+                        challengeHeaders['X-L402-Price-Usd'] = String(normalisedPrice.usd);
+                    }
+                    challengeHeaders['WWW-Authenticate'] = 'L402 price-only';
+                    challengeBody.message = 'Payment required.';
+                    return { action: 'challenge', status: 402, headers: challengeHeaders, body: challengeBody };
+                }
                 for (const rail of rails) {
                     if (rail.canChallenge && !rail.canChallenge(normalisedPrice))
                         continue;

package/dist/core/xcashu-rail.js

@@ -91,6 +91,18 @@ export function createXCashuRail(config, storage) {
             if (creditedAmount <= 0) {
                 return FAIL;
             }
+            // Fire onProofsReceived callback (non-blocking, fire-and-forget)
+            if (config.onProofsReceived) {
+                try {
+                    const cbResult = config.onProofsReceived(receivedProofs, tokenMint, creditedAmount);
+                    if (cbResult && typeof cbResult.catch === 'function') {
+                        cbResult.catch(() => { });
+                    }
+                }
+                catch {
+                    // Callback errors silently discarded — never block the payment flow
+                }
+            }
             // Generate payment ID and settlement secret
             const paymentId = randomBytes(32).toString('hex');
             const settlementSecret = randomBytes(32).toString('hex');

package/dist/index.d.ts

@@ -29,6 +29,8 @@ export type { X402RailConfig, X402Facilitator, X402Payment, X402VerifyResult } f
 export { DEFAULT_USDC_ASSETS } from './core/x402-types.js';
 export { createXCashuRail } from './core/xcashu-rail.js';
 export type { XCashuConfig } from './types.js';
+export { meltToLightning } from './core/melt-to-lightning.js';
+export type { MeltResult } from './core/melt-to-lightning.js';
 export { mintMacaroon, verifyMacaroon, parseCaveats } from './macaroon.js';
 export type { VerifyContext, VerifyResult } from './macaroon.js';
 export { FreeTier, CreditFreeTier } from './free-tier.js';

package/dist/index.js

@@ -18,6 +18,7 @@ export { createL402Rail } from './core/l402-rail.js';
 export { createX402Rail } from './core/x402-rail.js';
 export { DEFAULT_USDC_ASSETS } from './core/x402-types.js';
 export { createXCashuRail } from './core/xcashu-rail.js';
+export { meltToLightning } from './core/melt-to-lightning.js';
 // Utilities
 export { mintMacaroon, verifyMacaroon, parseCaveats } from './macaroon.js';
 export { FreeTier, CreditFreeTier } from './free-tier.js';

package/dist/types.d.ts

@@ -43,6 +43,7 @@ export interface LightningBackend {
      */
     checkInvoice(paymentHash: string): Promise<InvoiceStatus>;
 }
+import type { Proof } from '@cashu/cashu-ts';
 import type { Currency, PricingEntry } from './core/payment-rail.js';
 import type { X402RailConfig } from './core/x402-types.js';
 /**
@@ -81,6 +82,12 @@ export interface XCashuConfig {
     mints: string[];
     /** Currency unit, default 'sat' */
     unit?: Currency;
+    /**
+     * Called after successful token swap with the server-side proofs.
+     * Fire-and-forget — the rail does NOT await this callback.
+     * Use for melting, persisting, or forwarding received ecash.
+     */
+    onProofsReceived?: (proofs: Proof[], mintUrl: string, amount: number) => void | Promise<void>;
 }
 /**
  * Configuration for a toll-booth instance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thecryptodonkey/toll-booth",
-  "version": "3.5.0",
+  "version": "3.7.0",
   "type": "module",
   "description": "Monetise any API with HTTP 402 payments. Payment-rail agnostic middleware for Express, Hono, Deno, Bun, and Workers.",
   "license": "MIT",