forgelayer-node 1.0.0 → 1.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 > 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.
+Drop `createCheckout()` into any Express app and get crypto payment endpoints in seconds — address generation, real-time rate conversion, payment polling, webhook verification, and pluggable storage all included.
 
 ---
 
@@ -72,12 +72,18 @@ createCheckout({
   currency:             'USD',    // fiat currency for price display
   defaultChain:         'ethereum',
   defaultToken:         'USDT',
-  paymentWindowMinutes: 30,
-  reuseAddress:         false,
+  paymentWindowMinutes: 30,       // browser countdown timer
+  gracePeriodMinutes:   0,        // extra server-side window after expiry (see below)
+  reuseAddress:         false,    // return same address for same orderId if still pending
 
   // Webhooks (optional — set via setupWebhook() instead)
   webhookSecret: process.env.FORGELAYER_WEBHOOK_SECRET,
 
+  // Storage hooks — recommended for production (see Storage section below)
+  async getOrder(sessionKey)           { return await db.findOne({ sessionKey }); },
+  async saveOrder(sessionKey, order)   { await db.insertOne({ sessionKey, ...order }); },
+  async updateOrder(sessionKey, patch) { await db.updateOne({ sessionKey }, { $set: patch }); },
+
   // Callbacks
   onConfirmed:    async (orderId, orderData) => {},  // payment confirmed
   onWebhookEvent: async (event, data) => {},         // any verified webhook event
@@ -95,6 +101,97 @@ createCheckout({
 
 ---
 
+## Storage Hooks
+
+By default, orders are kept in a process-local `Map` (fine for development). In production you should plug in your own database:
+
+```js
+// MongoDB example
+const checkout = createCheckout({
+  apiKey: process.env.FORGELAYER_API_KEY,
+
+  async getOrder(sessionKey) {
+    return await Order.findOne({ sessionKey }).lean();
+  },
+  async saveOrder(sessionKey, order) {
+    await Order.create({ sessionKey, ...order });
+  },
+  async updateOrder(sessionKey, patch) {
+    await Order.updateOne({ sessionKey }, { $set: patch });
+  },
+
+  onConfirmed: async (orderId, order) => {
+    await Order.updateOne({ orderId }, { $set: { paid: true } });
+    await sendConfirmationEmail(order.email);
+  },
+});
+```
+
+```js
+// PostgreSQL / Prisma example
+const checkout = createCheckout({
+  apiKey: process.env.FORGELAYER_API_KEY,
+
+  async getOrder(sessionKey) {
+    return await prisma.order.findUnique({ where: { sessionKey } });
+  },
+  async saveOrder(sessionKey, order) {
+    await prisma.order.create({ data: { sessionKey, ...order } });
+  },
+  async updateOrder(sessionKey, patch) {
+    await prisma.order.update({ where: { sessionKey }, data: patch });
+  },
+});
+```
+
+All three hooks must be provided together. If any are omitted the plugin falls back to the built-in in-memory store.
+
+### In-memory store behaviour
+
+The default store is suitable for development and simple single-process deployments:
+- Orders are lost on process restart
+- Does not work with multiple server instances (clusters)
+- Auto-cleans orders older than 24 hours to prevent memory leaks
+
+---
+
+## Grace Period
+
+`gracePeriodMinutes` extends the server-side payment acceptance window beyond what the browser countdown shows.
+
+**Use case:** Slow networks or Bitcoin (where a transaction can take hours to confirm after broadcast). The browser sees the timer expire and shows an "expired" UI, but your server continues checking balances and accepting webhook confirmations for the extra time.
+
+```js
+createCheckout({
+  apiKey: '...',
+  paymentWindowMinutes: 30,   // browser shows 30-min countdown
+  gracePeriodMinutes:   60,   // server accepts payment for 90 min total
+  onConfirmed: async (orderId, order) => {
+    // Fires even if payment arrived after the browser countdown ended
+    await sendLatePaymentConfirmationEmail(order);
+  },
+});
+```
+
+The `onConfirmed` callback receives the order with `status: 'confirmed'` regardless of whether the payment arrived during or after the payment window.
+
+---
+
+## Address Reuse
+
+When `reuseAddress: true`, calling `/fl/create` with the same `orderId` within the payment window returns the existing deposit address instead of generating a new one:
+
+```js
+createCheckout({
+  apiKey: '...',
+  reuseAddress: true,  // or pass per-request: { reuseAddress: true } in the POST body
+});
+```
+
+This prevents a new address being generated every time a user navigates back to the payment page.
+
+---
+
 ## Routes
 
 Mounted at the path you choose (`app.use('/fl', checkout.middleware())`):
@@ -116,7 +213,8 @@ Mounted at the path you choose (`app.use('/fl', checkout.middleware())`):
   "chain": "ethereum",
   "token": "USDT",
   "orderId": "ORDER-123",
-  "paymentWindow": 30
+  "paymentWindow": 30,
+  "reuseAddress": false
 }
 ```
 
@@ -139,6 +237,8 @@ Mounted at the path you choose (`app.use('/fl', checkout.middleware())`):
 }
 ```
 
+When the same address is reused, the response also includes `"reused": true`.
+
 ### GET /fl/status
 
 ```
@@ -220,6 +320,19 @@ Returns an object with:
 
 ---
 
+## Changelog
+
+### 1.1.0
+- **Storage hooks** — plug in any database via `getOrder` / `saveOrder` / `updateOrder` config options
+- **Grace period** — `gracePeriodMinutes` keeps the server accepting payments after the browser timer expires
+- **Address reuse fix** — `reuseAddress: true` now correctly returns the existing address across restarts when storage hooks are provided
+- **In-memory TTL cleanup** — default store auto-removes orders older than 24 hours
+
+### 1.0.0
+- Initial release
+
+---
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgelayer-node",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Node.js / Express middleware for crypto payments via ForgeLayer",
   "main": "index.js",
   "exports": {

package/src/server.js

@@ -10,19 +10,20 @@
  *   POST <base>/webhook      → receive ForgeLayer deposit_confirmed events
  *
  * USAGE (Express):
- *   const { createCheckout } = require('forgelayer-checkout');
+ *   const { createCheckout } = require('forgelayer-node');
  *   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');
+ * STORAGE HOOKS (recommended for production):
+ *   createCheckout({
+ *     apiKey: '...',
+ *     async getOrder(sessionKey)           { return await db.orders.findOne({ sessionKey }); },
+ *     async saveOrder(sessionKey, order)   { await db.orders.insertOne({ sessionKey, ...order }); },
+ *     async updateOrder(sessionKey, patch) { await db.orders.updateOne({ sessionKey }, patch); },
+ *   });
  *
- * 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>
+ *   Without these hooks the plugin uses an in-memory store (fine for dev/testing,
+ *   orders are lost on restart).
  */
 
 const fs     = require('fs');
@@ -37,47 +38,37 @@ try {
   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';
+const FL_API_BASE = 'https://api.forgelayer.io/v1';
+const CG_API_BASE = 'https://api.coingecko.com/api/v3';
+const SDK_VERSION = '1.1.1';
 
 // 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)
+// Token symbol → CoinGecko coin ID
 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',
@@ -90,31 +81,37 @@ const CHAIN_NAMES = {
   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;
+// ── In-memory rate cache (process-wide, shared across all requests) ───────────
+const rateCache = new Map();
+
+// ── Default in-memory order store ─────────────────────────────────────────────
+// Used when the developer does not supply getOrder/saveOrder/updateOrder hooks.
+// Auto-cleans orders older than 24 hours to prevent memory leaks.
+function createMemoryAdapter() {
+  const store = new Map();
+
+  const cleanupTimer = setInterval(() => {
+    const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+    for (const [key, order] of store) {
+      if ((order._savedAt || 0) < cutoff) store.delete(key);
+    }
+  }, 60 * 60 * 1000); // run every hour
+  if (cleanupTimer.unref) cleanupTimer.unref();
+
+  return {
+    async getOrder(key)           { return store.get(key) || null; },
+    async saveOrder(key, order)   { store.set(key, { ...order, _savedAt: Date.now() }); },
+    async updateOrder(key, patch) {
+      const existing = store.get(key);
+      if (existing) store.set(key, { ...existing, ...patch, _savedAt: existing._savedAt });
+    },
+  };
+}
+
+// ── ForgeLayer API ────────────────────────────────────────────────────────────
+
+async function flRequest(method, urlPath, apiKey, body, query) {
+  let url = FL_API_BASE + urlPath;
   if (query && Object.keys(query).length) {
     url += '?' + new URLSearchParams(query).toString();
   }
@@ -128,7 +125,7 @@ async function flRequest(method, path, apiKey, body, query) {
     },
   };
   if (body && method !== 'GET') init.body = JSON.stringify(body);
-  const res = await fetchFn(url, init);
+  const res  = await fetchFn(url, init);
   const text = await res.text();
   let json;
   try { json = JSON.parse(text); } catch (_) {
@@ -151,21 +148,19 @@ async function getBalance(apiKey, address, chain) {
   return parseFloat(data.balance ?? 0);
 }
 
-// ── CoinGecko rate ───────────────────────────────────────────────────────────
+// ── CoinGecko rates ───────────────────────────────────────────────────────────
 
-// 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' } });
+  const res    = await fetchFn(
+    `${CG_API_BASE}/simple/price?ids=${allIds}&vs_currencies=${cur}`,
+    { headers: { 'Accept': 'application/json' } }
+  );
 
   if (res.status === 429) {
     console.warn('[ForgeLayer] CoinGecko rate limit (429) — keeping existing cache.');
-    return; // keep whatever is already cached
+    return;
   }
   if (!res.ok) {
     console.warn('[ForgeLayer] CoinGecko error ' + res.status + ' — keeping existing cache.');
@@ -173,8 +168,7 @@ async function fetchAllRates(currency) {
   }
 
   const json = await res.json();
-  // CoinGecko sometimes returns {"status": {"error_code": ...}} on errors
-  if (json.status && json.status.error_code) {
+  if (json.status?.error_code) {
     console.warn('[ForgeLayer] CoinGecko API error:', json.status.error_message);
     return;
   }
@@ -183,41 +177,30 @@ async function fetchAllRates(currency) {
   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(', ')
-    );
+    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
+  // First call before background timer has fired — fetch once now
   await fetchAllRates(cur);
-
   const refreshed = rateCache.get('batch_' + cur);
   const rate = parseFloat(refreshed?.rates[coinId] ?? 0);
   if (rate <= 0) {
@@ -229,71 +212,115 @@ async function getCoinGeckoRate(token, currency) {
 // ── Middleware factory ────────────────────────────────────────────────────────
 
 function createCheckout(config) {
-  if (!config || !config.apiKey) {
-    throw new Error('ForgeLayer: apiKey is required.');
-  }
+  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(
+  const apiKey              = String(config.apiKey).trim();
+  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) => {}
+  const defaultCurrency     = (config.currency             || 'USD').toUpperCase();
+  const defaultChain        = config.defaultChain          || 'ethereum';
+  const defaultToken        = (config.defaultToken         || 'USDT').toUpperCase();
+  const defaultWindow       = Math.max(1, +(config.paymentWindowMinutes || 30));
+  const defaultReuse        = !!config.reuseAddress;
+  const gracePeriodSeconds  = Math.max(0, +(config.gracePeriodMinutes || 0)) * 60;
+  const onConfirmed         = config.onConfirmed    || null;
+  const onWebhookEvent      = config.onWebhookEvent || null;
+
+  // ── Storage adapter ─────────────────────────────────────────────────────────
+  // Use developer-supplied hooks if provided, otherwise fall back to in-memory.
+  const storage = (config.getOrder && config.saveOrder && config.updateOrder)
+    ? {
+        getOrder:    config.getOrder.bind(config),
+        saveOrder:   config.saveOrder.bind(config),
+        updateOrder: config.updateOrder.bind(config),
+      }
+    : createMemoryAdapter();
+
+  if (!config.getOrder) {
+    console.warn(
+      '[ForgeLayer] No storage hooks provided — using in-memory store. ' +
+      'Orders will be lost on restart. Pass getOrder/saveOrder/updateOrder for production.'
+    );
+  }
 
   // ── 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 _cur = defaultCurrency.toLowerCase();
+  fetchAllRates(_cur).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)
-    ),
+    () => fetchAllRates(_cur).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');
+  const browserJsRaw = fs.readFileSync(path.join(__dirname, 'browser.js'), 'utf8');
 
-  // ── Route handlers ──────────────────────────────────────────────────────────
+  // ── Helpers ─────────────────────────────────────────────────────────────────
 
-  async function handleCreate(req, res, basePath) {
-    if (req.method !== 'POST') {
-      return res.status(405).json({ ok: false, error: 'POST required.' });
+  function toSessionKey(orderId) {
+    // SHA-256 so ORDER-1 and ORDER_1 don't collapse to the same key
+    return 'fl_' + crypto.createHash('sha256').update(String(orderId)).digest('hex').slice(0, 32);
+  }
+
+  async function markConfirmed(sessionKey, order) {
+    await storage.updateOrder(sessionKey, { status: 'confirmed' });
+    if (onConfirmed) {
+      onConfirmed(order.orderId, { ...order, status: 'confirmed' })
+        .catch(e => console.error('[ForgeLayer] onConfirmed error:', e));
     }
+  }
+
+  // ── POST /create ─────────────────────────────────────────────────────────────
+
+  async function handleCreate(req, res) {
+    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 = {};
-      }
+      try { body = JSON.parse(await readBody(req) || '{}'); } 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 });
+    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 : defaultReuse;
+    const window_  = Math.max(1, +(body.paymentWindow || defaultWindow));
+
+    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 });
+
+    const sessionKey = toSessionKey(orderId);
+
+    // ── Address reuse ─────────────────────────────────────────────────────────
+    // If reuseAddress is true and an active order already exists for this orderId,
+    // return the existing address instead of generating a new one.
+    if (reuse) {
+      const existing = await storage.getOrder(sessionKey);
+      if (existing && existing.status === 'pending') {
+        const now = Math.floor(Date.now() / 1000);
+        if (now < existing.expiresAt) {
+          return res.json({
+            ok: true, reused: true,
+            address:     existing.address,
+            chain:       existing.chain,
+            chainName:   CHAIN_NAMES[existing.chain] || existing.chain,
+            token:       existing.token,
+            amount:      existing.amount,
+            currency:    existing.currency,
+            cryptoAmount: existing.cryptoAmount,
+            expiresAt:   existing.expiresAt,
+            orderId:     existing.orderId,
+            qrUrl:       'https://api.qrserver.com/v1/create-qr-code/?size=160x160&margin=2&data=' + encodeURIComponent(existing.address),
+            sessionKey,
+          });
+        }
+      }
+    }
 
+    // ── Generate new address ──────────────────────────────────────────────────
     let address;
     try { address = await generateAddress(apiKey, chain, orderId); }
     catch (e) { return res.status(500).json({ ok: false, error: 'Address generation failed: ' + e.message }); }
@@ -302,171 +329,162 @@ function createCheckout(config) {
     try {
       const rate = await getCoinGeckoRate(token, currency);
       if (rate > 0) cryptoAmount = (amount / rate).toFixed(8).replace(/\.?0+$/, '');
-    } catch (_) { /* show fiat only */ }
+    } catch (_) { /* show fiat amount 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);
+    const expiresAt = Math.floor(Date.now() / 1000) + window_ * 60;
+    const order = { orderId, address, chain, token, amount, currency, cryptoAmount, expiresAt, status: 'pending' };
 
-    // Save order
-    orderStore.set(sessionKey, {
-      orderId, address, chain, token, amount, currency,
-      cryptoAmount, expiresAt, status: 'pending',
-    });
+    await storage.saveOrder(sessionKey, order);
 
     return res.json({
       ok: true,
       address, chain,
       chainName:    CHAIN_NAMES[chain] || chain,
       token, amount, currency, cryptoAmount,
-      expiresAt, orderId, qrUrl, sessionKey,
+      expiresAt, orderId, sessionKey,
+      qrUrl: 'https://api.qrserver.com/v1/create-qr-code/?size=160x160&margin=2&data=' + encodeURIComponent(address),
     });
   }
 
+  // ── GET /status ───────────────────────────────────────────────────────────────
+
   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 qs         = new URLSearchParams((req.url || '').split('?')[1] || '');
+    const sessionKey = req.query?.session || qs.get('session') || '';
+    const orderIdQ   = req.query?.orderId || qs.get('orderId') || '';
+    const key        = sessionKey || toSessionKey(orderIdQ);
 
-    const key = sessionKey || ('fl_' + orderId.replace(/[^a-z0-9]/gi, ''));
-    const order = orderStore.get(key);
+    const order = await storage.getOrder(key);
     if (!order) return res.status(404).json({ ok: false, error: 'Order not found.' });
 
+    // Already confirmed
     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';
+    const now          = Math.floor(Date.now() / 1000);
+    const graceEndsAt  = order.expiresAt + gracePeriodSeconds;
+
+    // Past grace period entirely — hard expired, no more checks
+    if (now >= graceEndsAt) {
+      await storage.updateOrder(key, { status: 'expired' });
       return res.json({ ok: true, status: 'expired' });
     }
 
-    // Check balance
+    // Check balance — works both within and outside the payment window
     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));
-        }
+        await markConfirmed(key, order);
         return res.json({ ok: true, status: 'confirmed' });
       }
     } catch (_) { /* best-effort */ }
 
+    // Payment window closed — tell the browser "expired" so it stops showing the UI,
+    // but we keep accepting via webhook until the grace period ends.
+    if (now >= order.expiresAt) {
+      return res.json({ ok: true, status: 'expired' });
+    }
+
     return res.json({ ok: true, status: 'pending' });
   }
 
+  // ── GET /checkout.js ──────────────────────────────────────────────────────────
+
   function serveBrowserScript(req, res, basePath) {
-    const createUrl = basePath + '/create';
-    const statusUrl  = basePath + '/status';
-    const config_js  = 'var FL_CONFIG={"createUrl":"' + createUrl + '","statusUrl":"' + statusUrl + '"};';
+    const config_js = 'var FL_CONFIG={"createUrl":"' + basePath + '/create","statusUrl":"' + basePath + '/status"};';
     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 ─────────────────────────────────────────────────────────
+  // ── POST /webhook ─────────────────────────────────────────────────────────────
 
   async function handleWebhook(req, res) {
-    if (req.method !== 'POST') {
-      return res.status(405).json({ ok: false, error: 'POST required.' });
-    }
+    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.');
+      console.error('[ForgeLayer] Webhook received but no webhookSecret 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'))) {
+    // timingSafeEqual throws if buffer lengths differ, so check length first
+    const sigBuf = Buffer.from(sig);
+    const expBuf = Buffer.from(expected);
+    if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
       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.' });
-    }
+    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));
+      const sessionKey = toSessionKey(orderId);
+      const order      = await storage.getOrder(sessionKey);
+
+      if (order && order.status !== 'confirmed') {
+        const now         = Math.floor(Date.now() / 1000);
+        const graceEndsAt = order.expiresAt + gracePeriodSeconds;
+
+        // Accept payment if within the payment window OR within the grace period
+        if (now < graceEndsAt) {
+          await markConfirmed(sessionKey, order);
+        } else {
+          console.warn('[ForgeLayer] Late payment received for order ' + orderId + ' but grace period has ended.');
         }
       }
     }
 
     if (onWebhookEvent) {
-      onWebhookEvent(event.event, event.data).catch(e => console.error('[ForgeLayer] onWebhookEvent error:', e));
+      onWebhookEvent(event.event, event.data)
+        .catch(e => console.error('[ForgeLayer] onWebhookEvent error:', e));
     }
 
     return res.status(200).json({ ok: true });
   }
 
-  // ── Express middleware ──────────────────────────────────────────────────────
+  // ── Webhook registration ──────────────────────────────────────────────────────
+
+  async function setupWebhook(webhookUrl, confirmations) {
+    if (!webhookUrl || typeof webhookUrl !== 'string') throw new Error('setupWebhook: webhookUrl is required.');
+    confirmations = Math.max(1, +(confirmations || 1));
+
+    const newSecret = crypto.randomBytes(32).toString('hex');
+
+    const oldId = loadSavedWebhookId();
+    if (oldId) {
+      try { await flRequest('DELETE', '/webhooks/' + encodeURIComponent(oldId), apiKey); }
+      catch (_) {}
+    }
+
+    const data = await flRequest('POST', '/webhooks', apiKey, {
+      url: webhookUrl, secret: newSecret, events: ['deposit_confirmed'], confirmations,
+    });
+
+    const webhookId = data.id || data.webhookId || '';
+    saveWebhookSecret(newSecret);
+    if (webhookId) saveWebhookId(webhookId);
+    webhookSecret = newSecret;
+
+    return { webhookId, webhookUrl, confirmations };
+  }
+
+  // ── 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);
-      }
+      if (urlPath === '/checkout.js' && req.method === 'GET') return serveBrowserScript(req, res, mountPath);
+      if (urlPath === '/create'      && req.method === 'POST') return handleCreate(req, res).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();
     };
   }
@@ -474,11 +492,10 @@ function createCheckout(config) {
   return { middleware, setupWebhook, handleCreate, handleStatus, handleWebhook, serveBrowserScript };
 }
 
-// ── Helpers ──────────────────────────────────────────────────────────────────
+// ── 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
@@ -486,29 +503,28 @@ function readBody(req) {
       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('data',  chunk => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+    req.on('end',   ()    => resolve(Buffer.concat(chunks).toString('utf8')));
     req.on('error', reject);
   });
 }
 
-// ── Webhook secret/ID file persistence ───────────────────────────────────────
+// ── Webhook secret/ID persistence ─────────────────────────────────────────────
 
-const SECRET_FILE = path.join(__dirname, '..', '.fl_webhook_secret');
-const ID_FILE     = path.join(__dirname, '..', '.fl_webhook_id');
+// Use process.cwd() so the file lands in the developer's project root,
+// not inside node_modules/forgelayer-node/ where it gets wiped on reinstall.
+const SECRET_FILE = path.join(process.cwd(), '.fl_webhook_secret');
+const ID_FILE     = path.join(process.cwd(), '.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');
 }