forgelayer-node 1.0.0

package/README.md

@@ -0,0 +1,225 @@
+# forgelayer-node
+
+> Node.js / Express middleware for accepting crypto payments via [ForgeLayer](https://forgelayer.io).
+
+Drop `createCheckout()` into any Express app and get crypto payment endpoints in seconds — address generation, real-time rate conversion, payment polling, and webhook verification all included.
+
+---
+
+## Install
+
+```bash
+npm install forgelayer-node
+```
+
+---
+
+## Quick Start
+
+```js
+const express = require('express');
+const { createCheckout } = require('forgelayer-node');
+
+const app = express();
+
+const checkout = createCheckout({
+  apiKey: process.env.FORGELAYER_API_KEY,
+
+  onConfirmed: async (orderId, order) => {
+    // Payment confirmed — update your database here
+    await db.markOrderPaid(orderId);
+  },
+});
+
+// Mounts /fl/create, /fl/status, /fl/webhook
+app.use('/fl', checkout.middleware());
+
+app.listen(3000);
+```
+
+Set your API key in `.env`:
+
+```
+FORGELAYER_API_KEY=flk_live_...
+```
+
+Get your API key at [forgelayer.io/dashboard](https://forgelayer.io/dashboard).
+
+---
+
+## How It Works
+
+```
+React / browser
+   │
+   ├── POST /fl/create   →  generates ForgeLayer deposit address
+   ├── GET  /fl/status   →  polls for payment confirmation
+   └── POST /fl/webhook  →  receives ForgeLayer webhook events (HMAC-verified)
+```
+
+Rates are fetched from CoinGecko once at startup and refreshed every 60 seconds in the background — checkout button clicks never wait on a network call.
+
+---
+
+## Configuration
+
+```js
+createCheckout({
+  // Required
+  apiKey: 'flk_live_...',
+
+  // Defaults (all optional — React frontend can override per button)
+  currency:             'USD',    // fiat currency for price display
+  defaultChain:         'ethereum',
+  defaultToken:         'USDT',
+  paymentWindowMinutes: 30,
+  reuseAddress:         false,
+
+  // Webhooks (optional — set via setupWebhook() instead)
+  webhookSecret: process.env.FORGELAYER_WEBHOOK_SECRET,
+
+  // Callbacks
+  onConfirmed:    async (orderId, orderData) => {},  // payment confirmed
+  onWebhookEvent: async (event, data) => {},         // any verified webhook event
+});
+```
+
+### Supported chains
+
+| Chain | Value |
+|---|---|
+| Ethereum | `ethereum` |
+| BNB Smart Chain | `bsc` |
+| Tron | `tron` |
+| Bitcoin | `bitcoin` |
+
+---
+
+## Routes
+
+Mounted at the path you choose (`app.use('/fl', checkout.middleware())`):
+
+| Method | Path | Description |
+|---|---|---|
+| `POST` | `/fl/create` | Generate a deposit address. Returns address, QR URL, crypto amount, expiry. |
+| `GET` | `/fl/status` | Poll payment status. Returns `pending`, `confirmed`, or `expired`. |
+| `POST` | `/fl/webhook` | Receive ForgeLayer `deposit_confirmed` events (HMAC-SHA256 verified). |
+
+### POST /fl/create
+
+**Request body:**
+
+```json
+{
+  "amount": 49.99,
+  "currency": "USD",
+  "chain": "ethereum",
+  "token": "USDT",
+  "orderId": "ORDER-123",
+  "paymentWindow": 30
+}
+```
+
+**Response:**
+
+```json
+{
+  "ok": true,
+  "address": "0xabc...",
+  "chain": "ethereum",
+  "chainName": "Ethereum",
+  "token": "USDT",
+  "amount": 49.99,
+  "currency": "USD",
+  "cryptoAmount": "49.99",
+  "expiresAt": 1718300000,
+  "orderId": "ORDER-123",
+  "qrUrl": "https://api.qrserver.com/...",
+  "sessionKey": "fl_abc123"
+}
+```
+
+### GET /fl/status
+
+```
+GET /fl/status?session=fl_abc123
+```
+
+```json
+{ "ok": true, "status": "pending" }
+{ "ok": true, "status": "confirmed" }
+{ "ok": true, "status": "expired" }
+```
+
+---
+
+## Webhook Setup
+
+Run once when you deploy (or whenever your public URL changes):
+
+```js
+const result = await checkout.setupWebhook('https://yoursite.com/fl/webhook');
+console.log(result.webhookId); // saved automatically for future restarts
+```
+
+The secret is saved to `.fl_webhook_secret` alongside your project and auto-loaded on every restart — you never need to manage it manually.
+
+---
+
+## Usage with forgelayer-react
+
+If you're using React on the frontend, pair this with [`forgelayer-react`](https://github.com/forgelayer-tech/forgelayer-react):
+
+```js
+// Backend — forgelayer-node
+app.use('/fl', checkout.middleware());
+```
+
+```jsx
+// Frontend — forgelayer-react
+import { ForgeLayerButton } from 'forgelayer-react';
+
+<ForgeLayerButton amount={49.99} chain="ethereum" token="USDT" baseUrl="/fl" />
+```
+
+Configure your Vite dev server to proxy `/fl` to your backend:
+
+```js
+// vite.config.js
+export default {
+  server: {
+    proxy: { '/fl': 'http://localhost:3000' },
+  },
+};
+```
+
+---
+
+## API Reference
+
+### `createCheckout(config)`
+
+Returns an object with:
+
+| Method | Description |
+|---|---|
+| `middleware()` | Returns an Express middleware function. Mount with `app.use('/fl', checkout.middleware())`. |
+| `setupWebhook(url, confirmations?)` | One-time webhook registration with ForgeLayer. Saves secret to `.fl_webhook_secret`. |
+| `handleCreate(req, res)` | Raw route handler for `POST /create`. |
+| `handleStatus(req, res)` | Raw route handler for `GET /status`. |
+| `handleWebhook(req, res)` | Raw route handler for `POST /webhook`. |
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `FORGELAYER_API_KEY` | Your ForgeLayer API key. |
+| `FORGELAYER_WEBHOOK_SECRET` | Optional — auto-managed by `setupWebhook()`. |
+
+---
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./src/server');

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "forgelayer-node",
+  "version": "1.0.0",
+  "description": "Node.js / Express middleware for crypto payments via ForgeLayer",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "src/server.js",
+    "src/browser.js",
+    "README.md"
+  ],
+  "keywords": [
+    "forgelayer", "crypto", "payments", "bitcoin", "ethereum",
+    "usdt", "express", "nodejs", "middleware", "checkout"
+  ],
+  "author": "ForgeLayer <support@forgelayer.io>",
+  "license": "MIT",
+  "homepage": "https://github.com/forgelayer-tech/forgelayer-node#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forgelayer-tech/forgelayer-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/forgelayer-tech/forgelayer-node/issues"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "dependencies": {
+    "node-fetch": "^2.7.0"
+  },
+  "devDependencies": {
+    "dotenv": "^17.4.2",
+    "express": "^5.2.1"
+  }
+}

package/src/browser.js

@@ -0,0 +1,402 @@
+/**
+ * ForgeLayer Checkout — browser script
+ *
+ * Served automatically by the Node.js middleware at GET /fl/checkout.js
+ * (or include manually from your own CDN / static host).
+ *
+ * Usage (data-attribute, zero JS needed):
+ *   <button class="fl-checkout-btn"
+ *           data-fl-amount="49.99"
+ *           data-fl-currency="USD"
+ *           data-fl-chain="ethereum"
+ *           data-fl-token="USDT"
+ *           data-fl-order-id="order_123">
+ *     Pay with Crypto
+ *   </button>
+ *
+ * Usage (programmatic):
+ *   ForgeLayerCheckout.mount('#my-btn', {
+ *     amount: 49.99, currency: 'USD', chain: 'ethereum', token: 'USDT',
+ *     orderId: 'order_123',
+ *     onSuccess: function(data) { window.location = '/thank-you'; },
+ *   });
+ *
+ * The server injects FL_CONFIG (createUrl, statusUrl) before this script runs.
+ */
+
+/* global FL_CONFIG */
+(function (global) {
+  'use strict';
+
+  // Endpoints injected by the server middleware (e.g. /fl/create, /fl/status)
+  var cfg = (typeof FL_CONFIG !== 'undefined' && FL_CONFIG) || {};
+  var DEFAULT_CREATE_URL = cfg.createUrl  || '/fl/create';
+  var DEFAULT_STATUS_URL = cfg.statusUrl  || '/fl/status';
+
+  // ── Modal singleton ───────────────────────────────────────────────────────
+  var backdrop = null;
+  var pollTmr  = null;
+  var cdTmr    = null;
+  var activeOrder = null;
+  var userCallbacks = {};
+
+  var MODAL_HTML = [
+    '<div class="fl-modal" id="fl-modal" role="dialog" aria-modal="true" aria-labelledby="fl-modal-title">',
+    '<div class="fl-mhd">',
+    '  <div class="fl-mtitle" id="fl-modal-title"><div class="fl-logo">FL</div>Pay with Crypto</div>',
+    '  <button class="fl-xbtn" id="fl-xbtn" aria-label="Close">&times;</button>',
+    '</div>',
+    '<div class="fl-mbody">',
+    /* loading */
+    '  <div id="fl-loading"><div class="fl-spinner"></div><p class="fl-spin-lbl">Generating payment address…</p></div>',
+    /* payment */
+    '  <div id="fl-pay" style="display:none">',
+    '    <div class="fl-sbar">',
+    '      <span class="fl-sdot pending" id="fl-sdot"></span>',
+    '      <span id="fl-stxt">Awaiting payment…</span>',
+    '      <span class="fl-timer" id="fl-timer">--:--</span>',
+    '    </div>',
+    '    <div class="fl-warn" id="fl-warn"></div>',
+    '    <div class="fl-grid">',
+    '      <div class="fl-qrside">',
+    '        <img class="fl-qrimg" id="fl-qr" src="" alt="QR code" loading="lazy" />',
+    '        <p class="fl-qrlbl">Scan with wallet</p>',
+    '      </div>',
+    '      <div class="fl-infoside">',
+    '        <div class="fl-iblk"><label>Amount to Send</label><div class="fl-amt" id="fl-amt"></div><div class="fl-amtsub" id="fl-amtsub"></div></div>',
+    '        <div class="fl-iblk"><label>Deposit Address</label>',
+    '          <div class="fl-arow"><span class="fl-aval" id="fl-addr"></span><button type="button" class="fl-cpbtn" id="fl-cpbtn">Copy</button></div>',
+    '        </div>',
+    '        <div class="fl-iblk"><label>Network</label><span class="fl-nbadge"><span class="fl-ndot"></span><span id="fl-net"></span></span></div>',
+    '      </div>',
+    '    </div>',
+    '  </div>',
+    /* success */
+    '  <div class="fl-rstate" id="fl-ok">',
+    '    <div class="fl-rico">✅</div>',
+    '    <div class="fl-rtitle">Payment Confirmed!</div>',
+    '    <div class="fl-rsub" id="fl-ok-sub">Your crypto payment has been received.</div>',
+    '  </div>',
+    /* expired */
+    '  <div class="fl-rstate" id="fl-exp">',
+    '    <div class="fl-rico">⏳</div>',
+    '    <div class="fl-rtitle">Payment Expired</div>',
+    '    <div class="fl-rsub">The payment window has closed. Please start a new payment.</div>',
+    '  </div>',
+    '</div>',
+    '<div class="fl-foot">Secured by <a href="https://forgelayer.io" target="_blank" rel="noopener">ForgeLayer</a></div>',
+    '</div>',
+  ].join('');
+
+  var MODAL_CSS = [
+    '.fl-checkout-btn{display:inline-flex;align-items:center;gap:8px;padding:12px 24px;background:#f7931a;color:#fff;border:none;border-radius:8px;font-size:15px;font-weight:600;cursor:pointer;transition:background .15s,transform .1s;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;line-height:1.2}',
+    '.fl-checkout-btn:hover{background:#e07b10}.fl-checkout-btn:active{transform:scale(.97)}.fl-checkout-btn:disabled{opacity:.6;cursor:not-allowed}',
+    '.fl-backdrop{display:none;position:fixed;inset:0;background:rgba(0,0,0,.6);z-index:99999;padding:16px}',
+    '.fl-backdrop.fl-open{display:flex;align-items:center;justify-content:center;animation:fl-fade .18s ease}',
+    '.fl-modal{background:#fff;border-radius:16px;width:100%;max-width:520px;box-shadow:0 24px 64px rgba(0,0,0,.28);overflow:hidden;animation:fl-up .22s ease;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;font-size:14px;color:#111}',
+    '.fl-mhd{display:flex;align-items:center;justify-content:space-between;padding:16px 18px;border-bottom:1px solid #e5e7eb;background:#fafafa}',
+    '.fl-mtitle{display:flex;align-items:center;gap:9px;font-size:15px;font-weight:700;color:#111}',
+    '.fl-logo{width:26px;height:26px;background:#f7931a;border-radius:6px;display:flex;align-items:center;justify-content:center;color:#fff;font-size:10px;font-weight:800;flex-shrink:0;letter-spacing:-.5px}',
+    '.fl-xbtn{background:none;border:none;font-size:22px;line-height:1;cursor:pointer;color:#6b7280;padding:4px 6px;border-radius:5px;transition:background .12s}',
+    '.fl-xbtn:hover{background:#f3f4f6;color:#111}',
+    '.fl-mbody{padding:20px 18px}',
+    '#fl-loading{text-align:center;padding:28px 0}',
+    '.fl-spinner{width:38px;height:38px;border:3px solid #e5e7eb;border-top-color:#f7931a;border-radius:50%;animation:fl-spin .7s linear infinite;margin:0 auto 14px}',
+    '.fl-spin-lbl{color:#6b7280;font-size:13px}',
+    '.fl-sbar{display:flex;align-items:center;gap:9px;padding:9px 13px;border-radius:8px;background:#f9fafb;border:1px solid #e5e7eb;margin-bottom:14px;font-size:13px}',
+    '.fl-sdot{width:8px;height:8px;border-radius:50%;flex-shrink:0}',
+    '.fl-sdot.pending{background:#f59e0b;animation:fl-pulse 1.6s ease-in-out infinite}',
+    '.fl-sdot.confirmed{background:#10b981}.fl-sdot.expired{background:#ef4444}',
+    '.fl-timer{margin-left:auto;font-weight:600;font-size:13px;color:#374151;font-variant-numeric:tabular-nums}.fl-timer.urgent{color:#ef4444}',
+    '.fl-warn{background:#fffbeb;border:1px solid #fde68a;border-radius:8px;padding:9px 13px;font-size:12px;color:#92400e;margin-bottom:14px;line-height:1.5}',
+    '.fl-grid{display:flex;gap:18px;margin-bottom:14px}',
+    '.fl-qrside{flex-shrink:0;display:flex;flex-direction:column;align-items:center;gap:6px}',
+    '.fl-qrimg{width:148px;height:148px;border:1px solid #e5e7eb;border-radius:10px;background:#f9fafb;display:block}',
+    '.fl-qrlbl{font-size:11px;color:#9ca3af}',
+    '.fl-infoside{flex:1;min-width:0;display:flex;flex-direction:column;gap:13px}',
+    '.fl-iblk label{display:block;font-size:10px;font-weight:700;color:#6b7280;text-transform:uppercase;letter-spacing:.06em;margin-bottom:4px}',
+    '.fl-amt{font-size:22px;font-weight:700;color:#111;line-height:1.2}.fl-amtsub{font-size:12px;color:#6b7280;margin-top:2px}',
+    '.fl-arow{display:flex;align-items:flex-start;gap:7px}',
+    '.fl-aval{font-family:"SFMono-Regular",Consolas,monospace;font-size:12px;color:#374151;word-break:break-all;flex:1;line-height:1.5}',
+    '.fl-cpbtn{flex-shrink:0;background:#fff;border:1px solid #d1d5db;border-radius:6px;padding:5px 11px;font-size:12px;cursor:pointer;color:#374151;transition:background .12s;white-space:nowrap}',
+    '.fl-cpbtn:hover{background:#f3f4f6}.fl-cpbtn.copied{border-color:#10b981;color:#059669}',
+    '.fl-nbadge{display:inline-flex;align-items:center;gap:5px;padding:3px 10px;background:#f3f4f6;border-radius:100px;font-size:12px;font-weight:500;color:#374151}',
+    '.fl-ndot{width:7px;height:7px;border-radius:50%;background:#10b981}',
+    '.fl-rstate{display:none;text-align:center;padding:30px 16px}',
+    '.fl-rstate.fl-show{display:block}',
+    '.fl-rico{font-size:52px;margin-bottom:14px}.fl-rtitle{font-size:19px;font-weight:700;color:#111;margin-bottom:7px}.fl-rsub{font-size:13px;color:#6b7280}',
+    '.fl-foot{padding:10px 18px 14px;text-align:center;font-size:11px;color:#9ca3af;border-top:1px solid #f3f4f6}',
+    '.fl-foot a{color:#f7931a;text-decoration:none}',
+    '@keyframes fl-fade{from{opacity:0}to{opacity:1}}',
+    '@keyframes fl-up{from{transform:translateY(18px);opacity:0}to{transform:translateY(0);opacity:1}}',
+    '@keyframes fl-spin{to{transform:rotate(360deg)}}',
+    '@keyframes fl-pulse{0%,100%{opacity:1}50%{opacity:.35}}',
+    '@media(max-width:460px){.fl-grid{flex-direction:column;align-items:center}.fl-qrside{flex-direction:row;gap:12px}}',
+  ].join('');
+
+  // ── DOM helpers ─────────────────────────────────────────────────────────────
+  function qs(id) { return document.getElementById(id); }
+
+  function injectStyles() {
+    if (document.getElementById('fl-styles')) return;
+    var s = document.createElement('style');
+    s.id = 'fl-styles';
+    s.textContent = MODAL_CSS;
+    (document.head || document.documentElement).appendChild(s);
+  }
+
+  function buildBackdrop() {
+    if (qs('fl-bd')) { backdrop = qs('fl-bd'); return; }
+    injectStyles();
+    backdrop = document.createElement('div');
+    backdrop.id        = 'fl-bd';
+    backdrop.className = 'fl-backdrop';
+    backdrop.innerHTML = MODAL_HTML;
+    document.body.appendChild(backdrop);
+
+    backdrop.addEventListener('click', function (e) { if (e.target === backdrop) closeModal(); });
+    qs('fl-xbtn').addEventListener('click', closeModal);
+    qs('fl-cpbtn').addEventListener('click', copyAddr);
+    document.addEventListener('keydown', function (e) { if (e.key === 'Escape') closeModal(); });
+  }
+
+  function copyAddr() {
+    var addr = qs('fl-addr').textContent;
+    var btn  = qs('fl-cpbtn');
+    var done = function () {
+      btn.textContent = 'Copied!'; btn.classList.add('copied');
+      setTimeout(function () { btn.textContent = 'Copy'; btn.classList.remove('copied'); }, 2000);
+    };
+    if (navigator.clipboard) { navigator.clipboard.writeText(addr).then(done).catch(done); }
+    else {
+      var ta = document.createElement('textarea');
+      ta.value = addr; ta.style.cssText = 'position:fixed;opacity:0;top:0;left:0';
+      document.body.appendChild(ta); ta.select();
+      try { document.execCommand('copy'); } catch (e) { /* ignore */ }
+      document.body.removeChild(ta); done();
+    }
+  }
+
+  // ── State machine ────────────────────────────────────────────────────────────
+  function showPane(id) {
+    ['fl-loading', 'fl-pay', 'fl-ok', 'fl-exp'].forEach(function (k) {
+      var el = qs(k); if (el) el.style.display = (k === id) ? 'block' : 'none';
+    });
+    ['fl-ok', 'fl-exp'].forEach(function (k) {
+      var el = qs(k); if (el) el.classList.toggle('fl-show', k === id);
+    });
+  }
+
+  function openModal() {
+    buildBackdrop();
+    backdrop.classList.add('fl-open');
+    document.body.style.overflow = 'hidden';
+    showPane('fl-loading');
+  }
+
+  function closeModal() {
+    if (backdrop) backdrop.classList.remove('fl-open');
+    document.body.style.overflow = '';
+    stopPoll(); stopCd();
+    if (userCallbacks.onCancel) userCallbacks.onCancel();
+    activeOrder = null;
+    userCallbacks = {};
+  }
+
+  function fillPayment(o) {
+    activeOrder = o;
+    qs('fl-qr').src  = o.qrUrl;
+    qs('fl-qr').alt  = 'Send to ' + o.address;
+    qs('fl-addr').textContent = o.address;
+    qs('fl-net').textContent  = o.chainName + ' · ' + o.token;
+
+    if (o.cryptoAmount) {
+      qs('fl-amt').textContent    = (+o.cryptoAmount).toFixed(8).replace(/\.?0+$/, '') + ' ' + o.token;
+      qs('fl-amtsub').textContent = '≈ ' + o.currency + ' ' + (+o.amount).toFixed(2);
+    } else {
+      qs('fl-amt').textContent    = o.currency + ' ' + (+o.amount).toFixed(2);
+      qs('fl-amtsub').textContent = '';
+    }
+
+    qs('fl-warn').innerHTML =
+      '<strong>⚠ Important:</strong> Send only <strong>' + o.token +
+      '</strong> on the <strong>' + o.chainName + '</strong> network. Wrong network = permanent loss.';
+
+    showPane('fl-pay');
+    startCd(o.expiresAt);
+    startPoll(o);
+  }
+
+  function triggerSuccess(o) {
+    showPane('fl-ok');
+    qs('fl-sdot').className = 'fl-sdot confirmed';
+    stopPoll(); stopCd();
+    if (userCallbacks.onSuccess) userCallbacks.onSuccess(o);
+    if (o.successUrl) setTimeout(function () { window.location.href = o.successUrl; }, 2200);
+  }
+
+  function triggerExpired() {
+    showPane('fl-exp');
+    stopPoll(); stopCd();
+    if (userCallbacks.onExpired) userCallbacks.onExpired();
+  }
+
+  // ── Countdown ────────────────────────────────────────────────────────────────
+  function startCd(expiresAt) {
+    stopCd();
+    function tick() {
+      var rem = expiresAt - Math.floor(Date.now() / 1000);
+      var el  = qs('fl-timer');
+      if (!el) return;
+      if (rem <= 0) { el.textContent = '00:00'; el.classList.add('urgent'); stopCd(); return; }
+      var m = Math.floor(rem / 60), s = rem % 60;
+      el.textContent = (m < 10 ? '0' : '') + m + ':' + (s < 10 ? '0' : '') + s;
+      if (rem <= 120) el.classList.add('urgent');
+    }
+    tick();
+    cdTmr = setInterval(tick, 1000);
+  }
+  function stopCd() { if (cdTmr) { clearInterval(cdTmr); cdTmr = null; } }
+
+  // ── Status polling ────────────────────────────────────────────────────────────
+  function startPoll(o) {
+    stopPoll();
+    pollTmr = setInterval(function () {
+      var url = (o.statusUrl || DEFAULT_STATUS_URL) + '?orderId=' + encodeURIComponent(o.orderId) + '&session=' + encodeURIComponent(o.sessionKey || '');
+      fetch(url, { headers: { 'X-Requested-With': 'XMLHttpRequest' } })
+        .then(function (r) { return r.json(); })
+        .then(function (d) {
+          if (!d.ok) return;
+          if (d.status === 'confirmed') triggerSuccess(o);
+          else if (d.status === 'expired') triggerExpired();
+        })
+        .catch(function () { /* keep polling */ });
+    }, 15000);
+  }
+  function stopPoll() { if (pollTmr) { clearInterval(pollTmr); pollTmr = null; } }
+
+  // ── Trigger a payment from a button or config object ─────────────────────────
+  function triggerPayment(params, callbacks) {
+    userCallbacks = callbacks || {};
+    openModal();
+
+    var createUrl = params.createUrl || params.serverUrl || DEFAULT_CREATE_URL;
+    var statusUrl = params.statusUrl  || DEFAULT_STATUS_URL;
+
+    fetch(createUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-Requested-With': 'XMLHttpRequest' },
+      body: JSON.stringify({
+        amount:        +params.amount || 0,
+        currency:      params.currency   || 'USD',
+        chain:         params.chain      || 'ethereum',
+        token:         params.token      || 'USDT',
+        orderId:       params.orderId    || '',
+        reuseAddress:  !!params.reuseAddress,
+        paymentWindow: +params.paymentWindow || 30,
+      }),
+    })
+      .then(function (r) { return r.json(); })
+      .then(function (d) {
+        if (!d.ok) {
+          closeModal();
+          if (userCallbacks.onError) userCallbacks.onError(new Error(d.error || 'Address generation failed.'));
+          else alert('ForgeLayer: ' + (d.error || 'Failed to generate payment address.'));
+          return;
+        }
+        fillPayment(Object.assign({}, d, {
+          statusUrl:  statusUrl,
+          successUrl: params.successUrl || '',
+        }));
+      })
+      .catch(function (e) {
+        closeModal();
+        if (userCallbacks.onError) userCallbacks.onError(e);
+        else alert('Network error: ' + e.message);
+      });
+  }
+
+  // ── Wire data-attribute buttons ───────────────────────────────────────────────
+  function handleDataBtn(btn) {
+    var ds = btn.dataset;
+    triggerPayment(
+      {
+        createUrl:     ds.flCreateUrl || ds.flEndpoint || DEFAULT_CREATE_URL,
+        statusUrl:     ds.flStatusUrl  || DEFAULT_STATUS_URL,
+        amount:        ds.flAmount,
+        currency:      ds.flCurrency,
+        chain:         ds.flChain,
+        token:         ds.flToken,
+        orderId:       ds.flOrderId,
+        reuseAddress:  ds.flReuse === '1',
+        paymentWindow: ds.flWindow,
+        successUrl:    ds.flSuccess,
+      },
+      {}
+    );
+  }
+
+  function wireBtns() {
+    document.querySelectorAll('.fl-checkout-btn').forEach(function (btn) {
+      if (btn.dataset.flWired) return;
+      btn.dataset.flWired = '1';
+      btn.addEventListener('click', function () { handleDataBtn(btn); });
+    });
+  }
+
+  // ── Public API ────────────────────────────────────────────────────────────────
+  var ForgeLayerCheckout = {
+    /**
+     * Programmatically mount a button and handle its click.
+     *
+     * @param {string|Element} selector - CSS selector or DOM element.
+     * @param {object} params           - Payment params (amount, currency, chain, token, orderId, …).
+     * @param {object} [callbacks]      - { onSuccess, onExpired, onCancel, onError }
+     */
+    mount: function (selector, params, callbacks) {
+      var el = typeof selector === 'string' ? document.querySelector(selector) : selector;
+      if (!el) return console.warn('ForgeLayerCheckout.mount: element not found:', selector);
+
+      // If the element is already a button, wire it; otherwise inject one
+      if (el.tagName === 'BUTTON') {
+        el.classList.add('fl-checkout-btn');
+        el.removeEventListener('click', el._flHandler);
+        el._flHandler = function () { triggerPayment(params, callbacks || {}); };
+        el.addEventListener('click', el._flHandler);
+        el.dataset.flWired = '1';
+      } else {
+        var btn = document.createElement('button');
+        btn.type = 'button';
+        btn.className = 'fl-checkout-btn';
+        btn.textContent = params.label || 'Pay with Crypto';
+        btn.addEventListener('click', function () { triggerPayment(params, callbacks || {}); });
+        btn.dataset.flWired = '1';
+        el.innerHTML = '';
+        el.appendChild(btn);
+      }
+    },
+
+    /** Open the modal immediately (e.g. from your own button). */
+    open: function (params, callbacks) {
+      triggerPayment(params, callbacks || {});
+    },
+
+    /** Close the modal. */
+    close: closeModal,
+  };
+
+  // ── Boot ───────────────────────────────────────────────────────────────────────
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', wireBtns);
+  } else {
+    wireBtns();
+  }
+  new MutationObserver(wireBtns).observe(
+    document.body || document.documentElement,
+    { childList: true, subtree: true }
+  );
+
+  // Expose globally
+  global.ForgeLayerCheckout = ForgeLayerCheckout;
+
+})(typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : this);

package/src/server.js

@@ -0,0 +1,516 @@
+'use strict';
+
+/**
+ * ForgeLayer Checkout — Node.js middleware
+ *
+ * Mounts on an Express sub-path and provides:
+ *   GET  <base>/checkout.js  → browser script (auto-configured with endpoint URLs)
+ *   POST <base>/create       → generate ForgeLayer deposit address
+ *   GET  <base>/status       → poll payment status
+ *   POST <base>/webhook      → receive ForgeLayer deposit_confirmed events
+ *
+ * USAGE (Express):
+ *   const { createCheckout } = require('forgelayer-checkout');
+ *   const checkout = createCheckout({ apiKey: 'flk_live_...' });
+ *   app.use('/fl', checkout.middleware());
+ *
+ *   // One-time setup (run once from a setup script, not on every request):
+ *   await checkout.setupWebhook('https://mysite.com/fl/webhook');
+ *
+ * Then in HTML:
+ *   <script src="/fl/checkout.js"></script>
+ *   <button class="fl-checkout-btn"
+ *           data-fl-amount="49.99" data-fl-currency="USD"
+ *           data-fl-chain="ethereum" data-fl-token="USDT"
+ *           data-fl-order-id="order_123">Pay with Crypto</button>
+ */
+
+const fs     = require('fs');
+const path   = require('path');
+const crypto = require('crypto');
+
+// Use built-in fetch (Node 18+) or fall back to node-fetch v2
+let fetchFn;
+try {
+  fetchFn = global.fetch || require('node-fetch');
+} catch (_) {
+  fetchFn = global.fetch;
+}
+
+const FL_API_BASE   = 'https://api.forgelayer.io/v1';
+const CG_API_BASE   = 'https://api.coingecko.com/api/v3';
+const SDK_VERSION   = '1.0.0';
+
+// Stablecoins pegged 1:1 to USD — skip CoinGecko for these
+const USD_STABLECOINS = new Set([
+  'USDT', 'USDC', 'BUSD', 'DAI', 'TUSD', 'USDP', 'GUSD', 'FRAX', 'LUSD', 'USDD',
+]);
+
+// Token symbol → CoinGecko coin ID (mirrors forgelayer-shopify/lib/coingecko.js)
+const CG_MAP = {
+  // Native coins
+  ETH:   'ethereum',       BNB:   'binancecoin',      BTC:   'bitcoin',
+  TRX:   'tron',
+  // Stablecoins
+  USDT:  'tether',         USDC:  'usd-coin',         BUSD:  'binance-usd',
+  DAI:   'dai',            TUSD:  'true-usd',         USDP:  'pax-dollar',
+  FRAX:  'frax',           LUSD:  'liquity-usd',      GUSD:  'gemini-dollar',
+  USDD:  'usdd',
+  // Wrapped
+  WBTC:  'wrapped-bitcoin', WETH: 'weth',             WBNB:  'wbnb',
+  // DeFi
+  LINK:  'chainlink',      UNI:   'uniswap',          AAVE:  'aave',
+  COMP:  'compound-governance-token', MKR: 'maker',   SNX:   'havven',
+  YFI:   'yearn-finance',  SUSHI: 'sushi',            CRV:   'curve-dao-token',
+  BAL:   'balancer',       LDO:   'lido-dao',
+  // L2 / Infra
+  MATIC: 'matic-network',  ARB:   'arbitrum',         OP:    'optimism',
+  GRT:   'the-graph',
+  // Meme
+  SHIB:  'shiba-inu',      PEPE:  'pepe',             FLOKI: 'floki',
+  DOGE:  'dogecoin',
+  // Gaming
+  SAND:  'the-sandbox',    MANA:  'decentraland',     AXS:   'axie-infinity',
+  APE:   'apecoin',        IMX:   'immutable-x',      GALA:  'gala',
+  // BSC
+  CAKE:  'pancakeswap-token', XVS: 'venus',
+  // Tron
+  BTT:   'bittorrent',     WIN:   'wink',             JST:   'just',
+  SUN:   'sun-token',
+  // Other
+  CRO:   'crypto-com-chain', BAT: 'basic-attention-token', ZRX: '0x',
+  ENS:   'ethereum-name-service', CHZ: 'chiliz',      FTM:   'fantom',
+  GMT:   'stepn',
+};
+
+const CHAIN_NAMES = {
+  ethereum: 'Ethereum',
+  bsc:      'BNB Smart Chain',
+  tron:     'Tron',
+  bitcoin:  'Bitcoin',
+};
+
+// In-memory order store — replace with a real DB for production
+const orderStore = new Map();
+
+// In-memory rate cache: "batch_{currency}" → { rates: { coinId: price }, at: ms }
+//
+// Because Node.js is single-process, this Map is shared across ALL concurrent
+// requests — so the first request in any 60-second window fetches from CoinGecko
+// and every subsequent request reads from memory. No file or Redis needed.
+//
+// Layout example:
+//   "batch_usd" → {
+//     at: 1718300000000,           // Date.now() when fetched
+//     rates: {
+//       "ethereum": 1678.39,
+//       "bitcoin":  64000,
+//       "tether":   0.9995,
+//       ...all ~60 coins...
+//     }
+//   }
+const rateCache  = new Map();
+
+// ── ForgeLayer API calls ────────────────────────────────────────────────────
+
+async function flRequest(method, path, apiKey, body, query) {
+  let url = FL_API_BASE + path;
+  if (query && Object.keys(query).length) {
+    url += '?' + new URLSearchParams(query).toString();
+  }
+  const init = {
+    method,
+    headers: {
+      'Authorization': 'Bearer ' + apiKey,
+      'Content-Type':  'application/json',
+      'Accept':        'application/json',
+      'User-Agent':    'ForgeLayer-JS-Plugin/' + SDK_VERSION + ' Node/' + process.version,
+    },
+  };
+  if (body && method !== 'GET') init.body = JSON.stringify(body);
+  const res = await fetchFn(url, init);
+  const text = await res.text();
+  let json;
+  try { json = JSON.parse(text); } catch (_) {
+    throw new Error('Invalid JSON from ForgeLayer (HTTP ' + res.status + ')');
+  }
+  if (json && json.success === false) {
+    throw new Error(json.error?.message || json.message || 'ForgeLayer API error');
+  }
+  return json.data ?? json;
+}
+
+async function generateAddress(apiKey, chain, label) {
+  const data = await flRequest('POST', '/addresses', apiKey, { chain, label });
+  if (!data.address) throw new Error('No address in ForgeLayer response.');
+  return data.address;
+}
+
+async function getBalance(apiKey, address, chain) {
+  const data = await flRequest('GET', '/addresses/' + encodeURIComponent(address) + '/balance', apiKey, null, { chain });
+  return parseFloat(data.balance ?? 0);
+}
+
+// ── CoinGecko rate ───────────────────────────────────────────────────────────
+
+// Fetch all ~60 coin prices for a given currency in one CoinGecko request and
+// write the result into rateCache. Called by the background timer and, as a
+// one-shot fallback, by getCoinGeckoRate if the cache is completely empty.
+async function fetchAllRates(currency) {
+  const cur    = currency.toLowerCase();
+  const allIds = [...new Set(Object.values(CG_MAP))].join(',');
+  const url    = `${CG_API_BASE}/simple/price?ids=${allIds}&vs_currencies=${cur}`;
+
+  const res = await fetchFn(url, { headers: { 'Accept': 'application/json' } });
+
+  if (res.status === 429) {
+    console.warn('[ForgeLayer] CoinGecko rate limit (429) — keeping existing cache.');
+    return; // keep whatever is already cached
+  }
+  if (!res.ok) {
+    console.warn('[ForgeLayer] CoinGecko error ' + res.status + ' — keeping existing cache.');
+    return;
+  }
+
+  const json = await res.json();
+  // CoinGecko sometimes returns {"status": {"error_code": ...}} on errors
+  if (json.status && json.status.error_code) {
+    console.warn('[ForgeLayer] CoinGecko API error:', json.status.error_message);
+    return;
+  }
+
+  const rates = {};
+  for (const [id, prices] of Object.entries(json)) {
+    if (prices[cur] != null) rates[id] = parseFloat(prices[cur]);
+  }
+
+  if (Object.keys(rates).length > 0) {
+    rateCache.set('batch_' + cur, { rates, at: Date.now() });
+  }
+}
+
+// Read the cached rate for a token/currency pair.
+// Falls back to a one-shot fetch ONLY on the very first call before the
+// background timer has had a chance to populate the cache.
+async function getCoinGeckoRate(token, currency) {
+  const sym = token.toUpperCase();
+  const cur = currency.toLowerCase();
+
+  // Stablecoins are always ≈ 1 USD — never hit CoinGecko
+  if (cur === 'usd' && USD_STABLECOINS.has(sym)) return 1.0;
+
+  const coinId = CG_MAP[sym];
+  if (!coinId) {
+    throw new Error(
+      'No CoinGecko mapping for token: ' + token +
+      '. Supported: ' + Object.keys(CG_MAP).join(', ')
+    );
+  }
+
+  const cached = rateCache.get('batch_' + cur);
+
+  // Cache is populated and fresh — use it (normal path after background timer runs)
+  if (cached && Object.keys(cached.rates).length > 0) {
+    const rate = parseFloat(cached.rates[coinId] ?? 0);
+    if (rate > 0) return rate;
+  }
+
+  // Cache is empty (process just started, timer hasn't fired yet) — fetch once now
+  await fetchAllRates(cur);
+
+  const refreshed = rateCache.get('batch_' + cur);
+  const rate = parseFloat(refreshed?.rates[coinId] ?? 0);
+  if (rate <= 0) {
+    throw new Error('No rate available for ' + sym + '/' + currency.toUpperCase() + ' — CoinGecko may be unavailable.');
+  }
+  return rate;
+}
+
+// ── Middleware factory ────────────────────────────────────────────────────────
+
+function createCheckout(config) {
+  if (!config || !config.apiKey) {
+    throw new Error('ForgeLayer: apiKey is required.');
+  }
+
+  const apiKey               = String(config.apiKey).trim();
+  // Webhook secret: from config, or env var, or the saved secret file
+  let   webhookSecret        = String(
+    config.webhookSecret || process.env.FORGELAYER_WEBHOOK_SECRET || loadSavedWebhookSecret() || ''
+  ).trim();
+  const defaultCurrency      = (config.currency             || 'USD').toUpperCase();
+  const defaultChain         = config.defaultChain          || 'ethereum';
+  const defaultToken         = (config.defaultToken         || 'USDT').toUpperCase();
+  const defaultPaymentWindow = Math.max(1, +(config.paymentWindowMinutes || 30));
+  const defaultReuseAddress  = !!config.reuseAddress;
+  const onConfirmed          = config.onConfirmed           || null; // async (orderId, data) => {}
+  const onWebhookEvent       = config.onWebhookEvent        || null; // async (event, data) => {}
+
+  // ── Background rate refresh ─────────────────────────────────────────────────
+  // Fetch CoinGecko prices immediately on startup, then every 60 seconds.
+  // This keeps the cache warm so checkout button clicks never wait on a network call.
+  const _refreshCurrency = defaultCurrency.toLowerCase();
+  fetchAllRates(_refreshCurrency).catch(e =>
+    console.warn('[ForgeLayer] Initial rate fetch failed:', e.message)
+  );
+  const _rateTimer = setInterval(
+    () => fetchAllRates(_refreshCurrency).catch(e =>
+      console.warn('[ForgeLayer] Rate refresh failed:', e.message)
+    ),
+    60_000
+  );
+  // Don't block process exit — the interval is fire-and-forget
+  if (_rateTimer.unref) _rateTimer.unref();
+
+  // Read browser.js once at startup
+  const browserJsPath = path.join(__dirname, 'browser.js');
+  const browserJsRaw  = fs.readFileSync(browserJsPath, 'utf8');
+
+  // ── Route handlers ──────────────────────────────────────────────────────────
+
+  async function handleCreate(req, res, basePath) {
+    if (req.method !== 'POST') {
+      return res.status(405).json({ ok: false, error: 'POST required.' });
+    }
+
+    let body = req.body;
+    if (!body || typeof body !== 'object') {
+      try {
+        const raw = await readBody(req);
+        body = JSON.parse(raw || '{}');
+      } catch (_) {
+        body = {};
+      }
+    }
+
+    const amount     = parseFloat(body.amount || 0);
+    const currency   = ((body.currency   || defaultCurrency)).toUpperCase();
+    const chain      = (body.chain       || defaultChain).toLowerCase();
+    const token      = ((body.token      || defaultToken)).toUpperCase();
+    const orderId    = body.orderId      || ('fl_' + Date.now() + '_' + Math.random().toString(36).slice(2));
+    const reuse      = body.reuseAddress !== undefined ? !!body.reuseAddress : defaultReuseAddress;
+    const window_    = Math.max(1, +(body.paymentWindow || defaultPaymentWindow));
+
+    if (amount <= 0)                        return res.status(400).json({ ok: false, error: 'Amount must be > 0.' });
+    if (!CHAIN_NAMES[chain])                return res.status(400).json({ ok: false, error: 'Unsupported chain: ' + chain });
+
+    let address;
+    try { address = await generateAddress(apiKey, chain, orderId); }
+    catch (e) { return res.status(500).json({ ok: false, error: 'Address generation failed: ' + e.message }); }
+
+    let cryptoAmount = null;
+    try {
+      const rate = await getCoinGeckoRate(token, currency);
+      if (rate > 0) cryptoAmount = (amount / rate).toFixed(8).replace(/\.?0+$/, '');
+    } catch (_) { /* show fiat only */ }
+
+    const expiresAt  = Math.floor(Date.now() / 1000) + window_ * 60;
+    const sessionKey = 'fl_' + orderId.replace(/[^a-z0-9]/gi, '');
+    const qrUrl      = 'https://api.qrserver.com/v1/create-qr-code/?size=160x160&margin=2&data=' + encodeURIComponent(address);
+
+    // Save order
+    orderStore.set(sessionKey, {
+      orderId, address, chain, token, amount, currency,
+      cryptoAmount, expiresAt, status: 'pending',
+    });
+
+    return res.json({
+      ok: true,
+      address, chain,
+      chainName:    CHAIN_NAMES[chain] || chain,
+      token, amount, currency, cryptoAmount,
+      expiresAt, orderId, qrUrl, sessionKey,
+    });
+  }
+
+  async function handleStatus(req, res) {
+    const orderId    = req.query?.orderId    || (new URLSearchParams(req.url.split('?')[1] || '')).get('orderId')    || '';
+    const sessionKey = req.query?.session    || (new URLSearchParams(req.url.split('?')[1] || '')).get('session')    || '';
+
+    const key = sessionKey || ('fl_' + orderId.replace(/[^a-z0-9]/gi, ''));
+    const order = orderStore.get(key);
+    if (!order) return res.status(404).json({ ok: false, error: 'Order not found.' });
+
+    if (order.status === 'confirmed') return res.json({ ok: true, status: 'confirmed' });
+
+    // Server-authoritative expiry
+    if (Math.floor(Date.now() / 1000) >= order.expiresAt) {
+      order.status = 'expired';
+      return res.json({ ok: true, status: 'expired' });
+    }
+
+    // Check balance
+    try {
+      const balance  = await getBalance(apiKey, order.address, order.chain);
+      const expected = parseFloat(order.cryptoAmount || 0);
+      if (expected > 0 && balance >= expected * 0.99) {
+        order.status = 'confirmed';
+        if (onConfirmed) {
+          onConfirmed(order.orderId, order).catch(e => console.error('[ForgeLayer] onConfirmed error:', e));
+        }
+        return res.json({ ok: true, status: 'confirmed' });
+      }
+    } catch (_) { /* best-effort */ }
+
+    return res.json({ ok: true, status: 'pending' });
+  }
+
+  function serveBrowserScript(req, res, basePath) {
+    const createUrl = basePath + '/create';
+    const statusUrl  = basePath + '/status';
+    const config_js  = 'var FL_CONFIG={"createUrl":"' + createUrl + '","statusUrl":"' + statusUrl + '"};';
+    res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
+    res.setHeader('Cache-Control', 'public, max-age=300');
+    res.end(config_js + '\n' + browserJsRaw);
+  }
+
+  // ── Webhook setup ───────────────────────────────────────────────────────────
+
+  async function setupWebhook(webhookUrl, confirmations) {
+    if (!webhookUrl || typeof webhookUrl !== 'string') {
+      throw new Error('setupWebhook: webhookUrl is required.');
+    }
+    confirmations = Math.max(1, +(confirmations || 1));
+
+    // Generate a fresh secret
+    const newSecret = crypto.randomBytes(32).toString('hex');
+
+    // Delete the old webhook if we have its ID on file
+    const oldId = loadSavedWebhookId();
+    if (oldId) {
+      try {
+        await flRequest('DELETE', '/webhooks/' + encodeURIComponent(oldId), apiKey);
+      } catch (_) { /* best-effort — old webhook may already be gone */ }
+    }
+
+    // Register with ForgeLayer
+    const data = await flRequest('POST', '/webhooks', apiKey, {
+      url:           webhookUrl,
+      secret:        newSecret,
+      events:        ['deposit_confirmed'],
+      confirmations,
+    });
+
+    const webhookId = data.id || data.webhookId || '';
+
+    // Persist for next restart
+    saveWebhookSecret(newSecret);
+    if (webhookId) saveWebhookId(webhookId);
+
+    // Update the live secret so the running process verifies correctly immediately
+    webhookSecret = newSecret;
+
+    return { webhookId, webhookUrl, confirmations };
+  }
+
+  // ── Webhook handler ─────────────────────────────────────────────────────────
+
+  async function handleWebhook(req, res) {
+    if (req.method !== 'POST') {
+      return res.status(405).json({ ok: false, error: 'POST required.' });
+    }
+
+    const rawBody = await readBody(req);
+    const sig     = req.headers['x-fl-signature'] || '';
+
+    if (!webhookSecret) {
+      console.error('[ForgeLayer] Webhook received but no webhookSecret is configured. Call setupWebhook() first.');
+      return res.status(500).json({ ok: false, error: 'Webhook secret not configured.' });
+    }
+
+    const expected = crypto.createHmac('sha256', webhookSecret).update(rawBody).digest('hex');
+    if (!crypto.timingSafeEqual(Buffer.from(sig, 'utf8'), Buffer.from(expected, 'utf8'))) {
+      return res.status(401).json({ ok: false, error: 'Invalid signature.' });
+    }
+
+    let event;
+    try { event = JSON.parse(rawBody); } catch (_) {
+      return res.status(400).json({ ok: false, error: 'Invalid JSON body.' });
+    }
+
+    if (event.event === 'deposit_confirmed') {
+      const orderId    = event.data?.orderId || event.data?.label || '';
+      const sessionKey = 'fl_' + orderId.replace(/[^a-z0-9]/gi, '');
+      const order      = orderStore.get(sessionKey);
+      if (order) {
+        order.status = 'confirmed';
+        if (onConfirmed) {
+          onConfirmed(orderId, order).catch(e => console.error('[ForgeLayer] onConfirmed error:', e));
+        }
+      }
+    }
+
+    if (onWebhookEvent) {
+      onWebhookEvent(event.event, event.data).catch(e => console.error('[ForgeLayer] onWebhookEvent error:', e));
+    }
+
+    return res.status(200).json({ ok: true });
+  }
+
+  // ── Express middleware ──────────────────────────────────────────────────────
+
+  function middleware() {
+    return function forgeLayerMiddleware(req, res, next) {
+      // Determine the path relative to where this middleware is mounted
+      const mountPath = req.baseUrl || '';
+      const urlPath   = (req.path || '/').replace(/\/$/, '') || '/';
+
+      if (urlPath === '/checkout.js' && req.method === 'GET') {
+        return serveBrowserScript(req, res, mountPath);
+      }
+      if (urlPath === '/create' && req.method === 'POST') {
+        return handleCreate(req, res, mountPath).catch(next);
+      }
+      if (urlPath === '/status' && req.method === 'GET') {
+        return handleStatus(req, res).catch(next);
+      }
+      if (urlPath === '/webhook' && req.method === 'POST') {
+        return handleWebhook(req, res).catch(next);
+      }
+      return next();
+    };
+  }
+
+  return { middleware, setupWebhook, handleCreate, handleStatus, handleWebhook, serveBrowserScript };
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function readBody(req) {
+  return new Promise(function (resolve, reject) {
+    // If Express (or body-parser) already consumed the body, return it as a raw Buffer
+    if (req.body !== undefined) {
+      const raw = typeof req.body === 'string'
+        ? req.body
+        : (Buffer.isBuffer(req.body) ? req.body.toString('utf8') : JSON.stringify(req.body));
+      return resolve(raw);
+    }
+    const chunks = [];
+    req.on('data', function (chunk) { chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)); });
+    req.on('end',  function () { resolve(Buffer.concat(chunks).toString('utf8')); });
+    req.on('error', reject);
+  });
+}
+
+// ── Webhook secret/ID file persistence ───────────────────────────────────────
+
+const SECRET_FILE = path.join(__dirname, '..', '.fl_webhook_secret');
+const ID_FILE     = path.join(__dirname, '..', '.fl_webhook_id');
+
+function loadSavedWebhookSecret() {
+  try { return fs.readFileSync(SECRET_FILE, 'utf8').trim(); } catch (_) { return ''; }
+}
+
+function saveWebhookSecret(secret) {
+  fs.writeFileSync(SECRET_FILE, secret, { encoding: 'utf8', mode: 0o600 });
+}
+
+function loadSavedWebhookId() {
+  try { return fs.readFileSync(ID_FILE, 'utf8').trim(); } catch (_) { return ''; }
+}
+
+function saveWebhookId(id) {
+  fs.writeFileSync(ID_FILE, id, 'utf8');
+}
+
+module.exports = { createCheckout };