web-agent-bridge 3.9.2 → 3.10.1

package/server/routes/auth.js

@@ -1,9 +1,27 @@
 const express = require('express');
+const crypto = require('crypto');
 const router = express.Router();
-const { registerUser, loginUser, findUserById } = require('../models/db');
+const {
+  registerUser, loginUser, findUserById, findUserByEmail,
+  createPasswordResetToken, consumePasswordResetToken, updateUserPassword,
+  createEmailVerificationToken, consumeEmailVerificationToken, isEmailVerified
+} = require('../models/db');
 const { generateToken, authenticateToken } = require('../middleware/auth');
 const { authLimiter, registerLimiter } = require('../middleware/rateLimits');
 const { validateEmail, sanitizeInput, auditLog, revokeJWT } = require('../services/security');
+const { sendEmail } = require('../services/email');
+
+const BASE_URL = process.env.BASE_URL || 'https://webagentbridge.com';
+
+function hashToken(token) {
+  return crypto.createHash('sha256').update(token).digest('hex');
+}
+
+function fireAndForget(promise, label) {
+  Promise.resolve(promise).catch((e) => {
+    console.error(`[email] ${label} failed (non-fatal):`, e && e.message);
+  });
+}
 
 router.post('/register', registerLimiter, (req, res) => {
   const { email, password, name, company } = req.body;
@@ -27,7 +45,25 @@ router.post('/register', registerLimiter, (req, res) => {
     const user = registerUser({ email: email.toLowerCase().trim(), password, name: cleanName, company: cleanCompany });
     const token = generateToken(user);
     auditLog({ actorType: 'user', actorId: String(user.id), action: 'register', ip: req.ip });
-    res.status(201).json({ user, token });
+
+    // Generate email-verification token and send it (best-effort, non-blocking)
+    try {
+      const verifyToken = crypto.randomBytes(32).toString('hex');
+      createEmailVerificationToken({ userId: user.id, tokenHash: hashToken(verifyToken) });
+      const verifyUrl = `${BASE_URL}/verify-email.html?token=${verifyToken}`;
+      fireAndForget(
+        sendEmail({ to: user.email, template: 'email_verification', data: { name: user.name, verifyUrl }, userId: user.id }),
+        'verification email'
+      );
+      fireAndForget(
+        sendEmail({ to: user.email, template: 'welcome', data: { name: user.name, dashboardUrl: `${BASE_URL}/dashboard` }, userId: user.id }),
+        'welcome email'
+      );
+    } catch (e) {
+      console.error('[register] verification setup failed:', e.message);
+    }
+
+    res.status(201).json({ user: { ...user, email_verified: 0 }, token });
   } catch (err) {
     if (err.message.includes('UNIQUE constraint')) {
       return res.status(409).json({ error: 'Email already registered' });
@@ -65,7 +101,74 @@ router.post('/logout', authenticateToken, (req, res) => {
 router.get('/me', authenticateToken, (req, res) => {
   const user = findUserById.get(req.user.id);
   if (!user) return res.status(404).json({ error: 'User not found' });
-  res.json({ user });
+  res.json({ user: { ...user, email_verified: isEmailVerified(req.user.id) ? 1 : 0 } });
+});
+
+// ─── Password Reset ────────────────────────────────────────────────────
+// Always returns success to avoid leaking which emails exist.
+router.post('/forgot-password', authLimiter, (req, res) => {
+  const { email } = req.body || {};
+  if (!email || !validateEmail(email)) {
+    return res.status(400).json({ error: 'Valid email required' });
+  }
+  try {
+    const user = findUserByEmail.get(email.toLowerCase().trim());
+    if (user) {
+      const token = crypto.randomBytes(32).toString('hex');
+      createPasswordResetToken({ userId: user.id, tokenHash: hashToken(token), ttlMinutes: 60 });
+      const resetUrl = `${BASE_URL}/reset-password.html?token=${token}`;
+      fireAndForget(
+        sendEmail({ to: user.email, template: 'password_reset', data: { name: user.name, resetUrl }, userId: user.id }),
+        'password_reset email'
+      );
+      auditLog({ actorType: 'user', actorId: String(user.id), action: 'password_reset_requested', ip: req.ip });
+    }
+  } catch (e) {
+    console.error('[forgot-password]', e.message);
+  }
+  res.json({ success: true, message: 'If that email is registered, a reset link has been sent.' });
+});
+
+router.post('/reset-password', authLimiter, (req, res) => {
+  const { token, password } = req.body || {};
+  if (!token || typeof token !== 'string') return res.status(400).json({ error: 'Token required' });
+  if (!password || password.length < 8 || password.length > 128) {
+    return res.status(400).json({ error: 'Password must be between 8 and 128 characters' });
+  }
+  const userId = consumePasswordResetToken(hashToken(token));
+  if (!userId) {
+    return res.status(400).json({ error: 'Invalid or expired token' });
+  }
+  updateUserPassword(userId, password);
+  auditLog({ actorType: 'user', actorId: String(userId), action: 'password_reset_completed', ip: req.ip });
+  res.json({ success: true });
+});
+
+// ─── Email Verification ────────────────────────────────────────────────
+router.post('/verify-email', (req, res) => {
+  const { token } = req.body || {};
+  if (!token || typeof token !== 'string') return res.status(400).json({ error: 'Token required' });
+  const userId = consumeEmailVerificationToken(hashToken(token));
+  if (!userId) return res.status(400).json({ error: 'Invalid or expired token' });
+  auditLog({ actorType: 'user', actorId: String(userId), action: 'email_verified', ip: req.ip });
+  res.json({ success: true });
+});
+
+router.post('/resend-verification', authenticateToken, (req, res) => {
+  const user = findUserById.get(req.user.id);
+  if (!user) return res.status(404).json({ error: 'User not found' });
+  if (isEmailVerified(req.user.id)) {
+    return res.json({ success: true, alreadyVerified: true });
+  }
+  const token = crypto.randomBytes(32).toString('hex');
+  createEmailVerificationToken({ userId: user.id, tokenHash: hashToken(token) });
+  const verifyUrl = `${BASE_URL}/verify-email.html?token=${token}`;
+  fireAndForget(
+    sendEmail({ to: user.email, template: 'email_verification', data: { name: user.name, verifyUrl }, userId: user.id }),
+    'resend verification'
+  );
+  auditLog({ actorType: 'user', actorId: String(req.user.id), action: 'verification_resent', ip: req.ip });
+  res.json({ success: true });
 });
 
 module.exports = router;

package/server/routes/premium.js

@@ -1,6 +1,6 @@
 const express = require('express');
 const router = express.Router();
-const { authenticateToken } = require('../middleware/auth');
+const { authenticateToken, requireTier } = require('../middleware/auth');
 const premium = require('../services/premium');
 const { findSiteById, findSitesByUser } = require('../models/db');
 
@@ -15,7 +15,7 @@ function requireSiteOwnership(req, res, next) {
 
 // ─── Traffic Intelligence ────────────────────────────────────────────────
 
-router.get('/traffic/:siteId/profiles', authenticateToken, requireSiteOwnership, async (req, res) => {
+router.get('/traffic/:siteId/profiles', authenticateToken, requireSiteOwnership, requireTier('business'), async (req, res) => {
   try {
     const { limit, offset, type } = req.query;
     const profiles = await premium.getAgentProfiles(req.params.siteId, {
@@ -29,7 +29,7 @@ router.get('/traffic/:siteId/profiles', authenticateToken, requireSiteOwnership,
   }
 });
 
-router.get('/traffic/:siteId/stats', authenticateToken, requireSiteOwnership, async (req, res) => {
+router.get('/traffic/:siteId/stats', authenticateToken, requireSiteOwnership, requireTier('business'), async (req, res) => {
   try {
     const days = req.query.days ? parseInt(req.query.days) : 30;
     const stats = await premium.getTrafficStats(req.params.siteId, days);
@@ -39,7 +39,7 @@ router.get('/traffic/:siteId/stats', authenticateToken, requireSiteOwnership, as
   }
 });
 
-router.get('/traffic/:siteId/alerts', authenticateToken, requireSiteOwnership, async (req, res) => {
+router.get('/traffic/:siteId/alerts', authenticateToken, requireSiteOwnership, requireTier('business'), async (req, res) => {
   try {
     const { limit, acknowledged } = req.query;
     const alerts = await premium.getAnomalyAlerts(req.params.siteId, {
@@ -52,7 +52,7 @@ router.get('/traffic/:siteId/alerts', authenticateToken, requireSiteOwnership, a
   }
 });
 
-router.post('/traffic/:siteId/alerts/:alertId/acknowledge', authenticateToken, requireSiteOwnership, async (req, res) => {
+router.post('/traffic/:siteId/alerts/:alertId/acknowledge', authenticateToken, requireSiteOwnership, requireTier('business'), async (req, res) => {
   try {
     const ok = await premium.acknowledgeAlert(req.params.alertId, req.params.siteId);
     if (!ok) return res.status(404).json({ error: 'Alert not found' });
@@ -62,7 +62,7 @@ router.post('/traffic/:siteId/alerts/:alertId/acknowledge', authenticateToken, r
   }
 });
 
-router.post('/traffic/:siteId/check-anomalies', authenticateToken, requireSiteOwnership, async (req, res) => {
+router.post('/traffic/:siteId/check-anomalies', authenticateToken, requireSiteOwnership, requireTier('business'), async (req, res) => {
   try {
     const alerts = await premium.checkForAnomalies(req.params.siteId);
     res.json({ alerts });
@@ -73,7 +73,7 @@ router.post('/traffic/:siteId/check-anomalies', authenticateToken, requireSiteOw
 
 // ─── Exploit Shield ──────────────────────────────────────────────────────
 
-router.get('/security/:siteId/events', authenticateToken, requireSiteOwnership, async (req, res) => {
+router.get('/security/:siteId/events', authenticateToken, requireSiteOwnership, requireTier('business'), async (req, res) => {
   try {
     const { limit, severity, since } = req.query;
     const events = await premium.getSecurityEvents(req.params.siteId, {
@@ -87,7 +87,7 @@ router.get('/security/:siteId/events', authenticateToken, requireSiteOwnership,
   }
 });
 
-router.get('/security/:siteId/report', authenticateToken, requireSiteOwnership, async (req, res) => {
+router.get('/security/:siteId/report', authenticateToken, requireSiteOwnership, requireTier('business'), async (req, res) => {
   try {
     const days = req.query.days ? parseInt(req.query.days) : 30;
     const report = await premium.getSecurityReport(req.params.siteId, days);
@@ -97,7 +97,7 @@ router.get('/security/:siteId/report', authenticateToken, requireSiteOwnership,
   }
 });
 
-router.get('/security/:siteId/blocked', authenticateToken, requireSiteOwnership, async (req, res) => {
+router.get('/security/:siteId/blocked', authenticateToken, requireSiteOwnership, requireTier('business'), async (req, res) => {
   try {
     const blocked = await premium.getBlockedAgents(req.params.siteId);
     res.json({ blocked });
@@ -106,7 +106,7 @@ router.get('/security/:siteId/blocked', authenticateToken, requireSiteOwnership,
   }
 });
 
-router.post('/security/:siteId/block', authenticateToken, requireSiteOwnership, async (req, res) => {
+router.post('/security/:siteId/block', authenticateToken, requireSiteOwnership, requireTier('business'), async (req, res) => {
   try {
     const { agentSignature, reason, expiresAt } = req.body;
     if (!agentSignature) return res.status(400).json({ error: 'agentSignature is required' });
@@ -117,7 +117,7 @@ router.post('/security/:siteId/block', authenticateToken, requireSiteOwnership,
   }
 });
 
-router.delete('/security/:siteId/block/:blockId', authenticateToken, requireSiteOwnership, async (req, res) => {
+router.delete('/security/:siteId/block/:blockId', authenticateToken, requireSiteOwnership, requireTier('business'), async (req, res) => {
   try {
     const ok = await premium.unblockAgent(req.params.blockId, req.params.siteId);
     if (!ok) return res.status(404).json({ error: 'Block record not found' });
@@ -193,7 +193,7 @@ router.delete('/actions/:siteId/install/:installId', authenticateToken, requireS
 
 // ─── Custom Agents ───────────────────────────────────────────────────────
 
-router.get('/agents/:siteId', authenticateToken, requireSiteOwnership, async (req, res) => {
+router.get('/agents/:siteId', authenticateToken, requireSiteOwnership, requireTier('pro'), async (req, res) => {
   try {
     const agents = await premium.getAgents(req.user.id, req.params.siteId);
     res.json({ agents });
@@ -202,7 +202,7 @@ router.get('/agents/:siteId', authenticateToken, requireSiteOwnership, async (re
   }
 });
 
-router.post('/agents/:siteId', authenticateToken, requireSiteOwnership, async (req, res) => {
+router.post('/agents/:siteId', authenticateToken, requireSiteOwnership, requireTier('pro'), async (req, res) => {
   try {
     const { name, description, steps, schedule } = req.body;
     if (!name || !steps) return res.status(400).json({ error: 'name and steps are required' });
@@ -213,7 +213,7 @@ router.post('/agents/:siteId', authenticateToken, requireSiteOwnership, async (r
   }
 });
 
-router.get('/agents/:siteId/:agentId', authenticateToken, requireSiteOwnership, async (req, res) => {
+router.get('/agents/:siteId/:agentId', authenticateToken, requireSiteOwnership, requireTier('pro'), async (req, res) => {
   try {
     const agent = await premium.getAgent(req.params.agentId, req.user.id);
     if (!agent) return res.status(404).json({ error: 'Agent not found' });
@@ -223,7 +223,7 @@ router.get('/agents/:siteId/:agentId', authenticateToken, requireSiteOwnership,
   }
 });
 
-router.put('/agents/:siteId/:agentId', authenticateToken, requireSiteOwnership, async (req, res) => {
+router.put('/agents/:siteId/:agentId', authenticateToken, requireSiteOwnership, requireTier('pro'), async (req, res) => {
   try {
     const { name, description, steps, schedule } = req.body;
     const ok = await premium.updateAgent(req.params.agentId, req.user.id, { name, description, steps, schedule });
@@ -234,7 +234,7 @@ router.put('/agents/:siteId/:agentId', authenticateToken, requireSiteOwnership,
   }
 });
 
-router.delete('/agents/:siteId/:agentId', authenticateToken, requireSiteOwnership, async (req, res) => {
+router.delete('/agents/:siteId/:agentId', authenticateToken, requireSiteOwnership, requireTier('pro'), async (req, res) => {
   try {
     const ok = await premium.deleteAgent(req.params.agentId, req.user.id);
     if (!ok) return res.status(404).json({ error: 'Agent not found' });
@@ -244,7 +244,7 @@ router.delete('/agents/:siteId/:agentId', authenticateToken, requireSiteOwnershi
   }
 });
 
-router.post('/agents/:siteId/:agentId/run', authenticateToken, requireSiteOwnership, async (req, res) => {
+router.post('/agents/:siteId/:agentId/run', authenticateToken, requireSiteOwnership, requireTier('pro'), async (req, res) => {
   try {
     const result = await premium.runAgent(req.params.agentId, req.user.id);
     res.json({ result });
@@ -253,7 +253,7 @@ router.post('/agents/:siteId/:agentId/run', authenticateToken, requireSiteOwners
   }
 });
 
-router.get('/agents/:siteId/:agentId/runs', authenticateToken, requireSiteOwnership, async (req, res) => {
+router.get('/agents/:siteId/:agentId/runs', authenticateToken, requireSiteOwnership, requireTier('pro'), async (req, res) => {
   try {
     const { limit } = req.query;
     const runs = await premium.getAgentRuns(req.params.agentId, {

package/server/routes/transactions.js

@@ -245,4 +245,36 @@ router.get('/platform/stats', publicReceiptLimiter, (req, res) => {
   res.json({ ok: true, data: stats });
 });
 
+// ─── Merchant commission endpoints ────────────────────────────────────────
+// Every merchant tx settled through ATP on a paid plan accrues a small
+// platform commission (default 0.10%). Merchants can inspect their own
+// accrual via these endpoints. Public commission rate is exposed for
+// transparency.
+const commissions = require('../services/commissions');
+
+router.get('/commissions/rate', (req, res) => {
+  res.json({
+    ok: true,
+    data: {
+      rate_bps: commissions.getCommissionBps(),
+      rate_percent: commissions.getCommissionBps() / 100,
+      min_tier: commissions.getMinTier(),
+      applies_to: 'Successful merchant transactions settled through ATP on a paid plan.',
+    },
+  });
+});
+
+router.get('/commissions', authenticateToken, (req, res) => {
+  const limit  = Math.min(200, Math.max(1, parseInt(req.query.limit, 10) || 50));
+  const offset = Math.max(0, parseInt(req.query.offset, 10) || 0);
+  const status = req.query.status || null;
+  const items = commissions.listCommissionsForMerchant(req.user.id, { limit, offset, status });
+  res.json({ ok: true, data: items, limit, offset });
+});
+
+router.get('/commissions/stats', authenticateToken, (req, res) => {
+  const stats = commissions.getMerchantCommissionStats(req.user.id);
+  res.json({ ok: true, data: stats });
+});
+
 module.exports = router;

package/server/services/commission-billing.js

@@ -0,0 +1,279 @@
+'use strict';
+
+/**
+ * ATP Commission Billing — v3.10.1
+ *
+ * Converts `pending` rows in atp_commissions into real Stripe invoices.
+ *
+ * Strategy:
+ *   - Group pending commissions by merchant_user_id + currency.
+ *   - One Stripe invoice per (merchant, currency) per cycle.
+ *   - One Stripe invoice item per commission row, so the merchant sees
+ *     a line-by-line breakdown.
+ *   - Mark rows `invoiced` and stamp the stripe invoice id into `notes`
+ *     inside the same transaction.
+ *
+ * Idempotency:
+ *   - Skips rows whose merchant has no Stripe customer yet.
+ *   - Aborts a merchant's batch on any Stripe error; rows stay `pending`.
+ *   - dry-run mode just returns the plan without touching Stripe or the DB.
+ *
+ * Trigger:
+ *   - Admin endpoint POST /api/admin/commissions/run-billing
+ *   - Optional periodic timer (env WAB_COMMISSION_BILLING_INTERVAL_HOURS).
+ */
+
+const { db, getStripeCustomer } = require('../models/db');
+
+function getMinAgeDays() {
+  const n = parseInt(process.env.WAB_COMMISSION_MIN_AGE_DAYS, 10);
+  if (Number.isFinite(n) && n >= 0 && n <= 365) return n;
+  return 0; // by default bill anything that's pending
+}
+
+function getMinAmountCents() {
+  const n = parseInt(process.env.WAB_COMMISSION_MIN_INVOICE_CENTS, 10);
+  if (Number.isFinite(n) && n >= 0) return n;
+  return 100; // 1 EUR/USD floor — Stripe rejects sub-50c invoices anyway
+}
+
+/**
+ * Build the per-merchant batches that would be billed in this cycle.
+ * Returns an array: [{ merchantUserId, currency, rows[], totalCents, stripeCustomerId|null, skipReason|null }]
+ */
+function planBillingCycle() {
+  const minAgeDays = getMinAgeDays();
+  const ageClause = minAgeDays > 0
+    ? `AND datetime(created_at) < datetime('now', '-${minAgeDays} days')`
+    : '';
+
+  const groups = db.prepare(`
+    SELECT merchant_user_id, currency,
+           COUNT(*) AS n,
+           COALESCE(SUM(commission_cents), 0) AS total_cents
+      FROM atp_commissions
+     WHERE status = 'pending'
+       ${ageClause}
+     GROUP BY merchant_user_id, currency
+     ORDER BY total_cents DESC
+  `).all();
+
+  const minAmount = getMinAmountCents();
+
+  const batches = [];
+  for (const g of groups) {
+    if (g.total_cents < minAmount) {
+      batches.push({
+        merchantUserId: g.merchant_user_id,
+        currency: g.currency,
+        rows: [],
+        totalCents: g.total_cents,
+        rowCount: g.n,
+        stripeCustomerId: null,
+        skipReason: `below_min_invoice (${g.total_cents}c < ${minAmount}c)`,
+      });
+      continue;
+    }
+    const cust = getStripeCustomer(g.merchant_user_id);
+    if (!cust || !cust.stripe_customer_id) {
+      batches.push({
+        merchantUserId: g.merchant_user_id,
+        currency: g.currency,
+        rows: [],
+        totalCents: g.total_cents,
+        rowCount: g.n,
+        stripeCustomerId: null,
+        skipReason: 'no_stripe_customer',
+      });
+      continue;
+    }
+    const rows = db.prepare(`
+      SELECT id, transaction_id, gross_amount_cents, commission_cents, commission_bps, created_at
+        FROM atp_commissions
+       WHERE merchant_user_id = ? AND currency = ? AND status = 'pending'
+       ${ageClause}
+       ORDER BY created_at ASC
+    `).all(g.merchant_user_id, g.currency);
+
+    batches.push({
+      merchantUserId: g.merchant_user_id,
+      currency: g.currency,
+      rows,
+      totalCents: g.total_cents,
+      rowCount: rows.length,
+      stripeCustomerId: cust.stripe_customer_id,
+      skipReason: null,
+    });
+  }
+  return batches;
+}
+
+/**
+ * Execute a billing cycle. When dryRun=true, returns the plan without
+ * touching Stripe or the DB.
+ */
+async function runBillingCycle({ dryRun = false } = {}) {
+  const startedAt = new Date().toISOString();
+  const batches = planBillingCycle();
+  const summary = {
+    started_at: startedAt,
+    dry_run: !!dryRun,
+    batches_total: batches.length,
+    batches_billed: 0,
+    batches_skipped: 0,
+    rows_invoiced: 0,
+    total_commission_cents: 0,
+    invoices: [],
+    errors: [],
+  };
+
+  if (dryRun) {
+    summary.batches_skipped = batches.filter((b) => b.skipReason).length;
+    summary.batches_billed  = batches.length - summary.batches_skipped;
+    summary.rows_invoiced   = batches.reduce((s, b) => s + (b.skipReason ? 0 : b.rowCount), 0);
+    summary.total_commission_cents = batches.reduce(
+      (s, b) => s + (b.skipReason ? 0 : b.totalCents),
+      0,
+    );
+    summary.plan = batches.map((b) => ({
+      merchant_user_id: b.merchantUserId,
+      currency: b.currency,
+      rows: b.rowCount,
+      total_cents: b.totalCents,
+      stripe_customer_id: b.stripeCustomerId,
+      skip_reason: b.skipReason,
+    }));
+    summary.finished_at = new Date().toISOString();
+    return summary;
+  }
+
+  const { getStripe, isStripeConfigured } = require('./stripe');
+  if (!isStripeConfigured()) {
+    summary.errors.push({ reason: 'stripe_not_configured' });
+    summary.finished_at = new Date().toISOString();
+    return summary;
+  }
+  const stripe = getStripe();
+
+  for (const batch of batches) {
+    if (batch.skipReason) {
+      summary.batches_skipped++;
+      continue;
+    }
+
+    try {
+      // 1) One invoice item per commission row → merchant gets a full ledger.
+      for (const r of batch.rows) {
+        await stripe.invoiceItems.create({
+          customer: batch.stripeCustomerId,
+          amount: r.commission_cents,
+          currency: (batch.currency || 'eur').toLowerCase(),
+          description: `WAB ATP commission (${(r.commission_bps / 100).toFixed(2)}%) · tx ${r.transaction_id} · ${r.created_at}`,
+          metadata: {
+            wab_commission_id: r.id,
+            wab_transaction_id: r.transaction_id,
+            wab_kind: 'atp_commission',
+          },
+        });
+      }
+
+      // 2) Finalize a single invoice for all the items above.
+      const invoice = await stripe.invoices.create({
+        customer: batch.stripeCustomerId,
+        collection_method: 'charge_automatically',
+        auto_advance: true,
+        description: `WAB ATP merchant commission · ${batch.rowCount} transactions`,
+        metadata: {
+          wab_kind: 'atp_commission_batch',
+          wab_merchant_user_id: batch.merchantUserId,
+          wab_currency: batch.currency,
+          wab_row_count: String(batch.rowCount),
+        },
+      });
+
+      // 3) Mark all rows invoiced inside a single DB transaction.
+      const ids = batch.rows.map((r) => r.id);
+      const stamp = `stripe_invoice:${invoice.id}@${new Date().toISOString()}`;
+      const markTx = db.transaction((commIds) => {
+        const upd = db.prepare(`
+          UPDATE atp_commissions
+             SET status = 'invoiced',
+                 notes = COALESCE(notes || ' | ', '') || ?,
+                 updated_at = datetime('now')
+           WHERE id = ? AND status = 'pending'
+        `);
+        for (const id of commIds) upd.run(stamp, id);
+      });
+      markTx(ids);
+
+      summary.batches_billed++;
+      summary.rows_invoiced += batch.rowCount;
+      summary.total_commission_cents += batch.totalCents;
+      summary.invoices.push({
+        merchant_user_id: batch.merchantUserId,
+        currency: batch.currency,
+        rows: batch.rowCount,
+        total_cents: batch.totalCents,
+        stripe_invoice_id: invoice.id,
+        stripe_invoice_status: invoice.status,
+      });
+    } catch (e) {
+      summary.errors.push({
+        merchant_user_id: batch.merchantUserId,
+        currency: batch.currency,
+        message: e && e.message ? e.message : String(e),
+      });
+    }
+  }
+
+  summary.finished_at = new Date().toISOString();
+  return summary;
+}
+
+/**
+ * Webhook hook — called from stripe.js when an invoice tied to a wab
+ * commission batch is paid or fails. Flips matching atp_commissions rows
+ * to 'collected' (paid) or leaves at 'invoiced' (failed → manual).
+ */
+function onStripeInvoicePaid(invoice) {
+  try {
+    const meta = invoice && invoice.metadata;
+    if (!meta || meta.wab_kind !== 'atp_commission_batch') return 0;
+    const r = db.prepare(`
+      UPDATE atp_commissions
+         SET status = 'collected',
+             notes  = COALESCE(notes || ' | ', '') || ?,
+             updated_at = datetime('now')
+       WHERE status = 'invoiced'
+         AND notes LIKE ?
+    `).run(`paid:${invoice.id}@${new Date().toISOString()}`, `%stripe_invoice:${invoice.id}%`);
+    return r.changes;
+  } catch (e) {
+    console.error('[commission-billing] onStripeInvoicePaid failed:', e.message);
+    return 0;
+  }
+}
+
+let _timer = null;
+function startPeriodicBilling() {
+  const hours = parseFloat(process.env.WAB_COMMISSION_BILLING_INTERVAL_HOURS);
+  if (!Number.isFinite(hours) || hours <= 0) return null;
+  const ms = Math.max(60_000, hours * 3_600_000);
+  if (_timer) clearInterval(_timer);
+  _timer = setInterval(() => {
+    runBillingCycle({ dryRun: false })
+      .then((s) => console.log(
+        `[commission-billing] cycle done: billed=${s.batches_billed} rows=${s.rows_invoiced} total_cents=${s.total_commission_cents} errors=${s.errors.length}`,
+      ))
+      .catch((e) => console.error('[commission-billing] cycle failed:', e.message));
+  }, ms);
+  if (_timer.unref) _timer.unref();
+  return { intervalHours: hours };
+}
+
+module.exports = {
+  planBillingCycle,
+  runBillingCycle,
+  onStripeInvoicePaid,
+  startPeriodicBilling,
+};