web-agent-bridge 3.9.1 → 3.10.0

package/bin/wab.js

@@ -64,6 +64,60 @@ switch (command) {
       fs.writeFileSync(envTarget, defaultEnv);
       console.log('  Created default .env file.');
     }
+
+    // Generate wab.json — site manifest for agents
+    const wabJsonTarget = path.join(process.cwd(), 'wab.json');
+    if (fs.existsSync(wabJsonTarget)) {
+      console.log('  wab.json already exists. Skipping.');
+    } else {
+      const projectName = (() => {
+        try {
+          const pkgPath = path.join(process.cwd(), 'package.json');
+          if (fs.existsSync(pkgPath)) {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+            return pkg.name || path.basename(process.cwd());
+          }
+        } catch { /* ignore */ }
+        return path.basename(process.cwd());
+      })();
+
+      const wabJson = {
+        $schema: 'https://webagentbridge.com/schemas/wab.schema.json',
+        version: '1.0',
+        site: {
+          name: projectName,
+          domain: 'example.com',
+          description: 'A WAB-enabled site. Replace this with your real description.'
+        },
+        agentPermissions: {
+          readContent: true,
+          click: true,
+          fillForms: false,
+          scroll: true,
+          navigate: false,
+          apiAccess: false,
+          automatedLogin: false,
+          extractData: false
+        },
+        restrictions: {
+          allowedSelectors: [],
+          blockedSelectors: ['.private', '[data-private]'],
+          rateLimit: { maxCallsPerMinute: 60 }
+        },
+        actions: [
+          {
+            name: 'example_action',
+            description: 'Example action — replace with your real actions',
+            selector: '#example',
+            type: 'click'
+          }
+        ],
+        logging: { enabled: true, level: 'basic' }
+      };
+      fs.writeFileSync(wabJsonTarget, JSON.stringify(wabJson, null, 2) + '\n');
+      console.log('  Created wab.json site manifest.');
+      console.log('  Edit wab.json to describe your site and actions.');
+    }
     break;
   }
 

package/package.json

@@ -1,93 +1,93 @@
-{
-  "name": "web-agent-bridge",
-  "version": "3.9.1",
-  "description": "Agent Transaction Bridge — the trust + transaction layer for agentic commerce. Signed intent contracts, idempotent transactions, Ed25519-verifiable receipts, explicit compensation. Plus the original WAB stack: sovereign browser, ShieldQR, SSL health, DNS discovery, agent mesh, and unified gateway for safe AI–website interaction.",
-  "author": "Web Agent Bridge <dev@webagentbridge.com>",
-  "main": "server/index.js",
-  "bin": {
-    "web-agent-bridge": "./bin/cli.js",
-    "wab": "./bin/cli.js",
-    "wab-agent": "./bin/cli.js",
-    "wab-init": "./bin/wab-init.js"
-  },
-  "scripts": {
-    "start": "node server/index.js",
-    "dev": "node server/index.js",
-    "test": "jest --forceExit --detectOpenHandles",
-    "build:script": "node scripts/build.js",
-    "prepublishOnly": "npm test"
-  },
-  "keywords": [
-    "ai",
-    "agent",
-    "bridge",
-    "protocol",
-    "platform",
-    "automation",
-    "web",
-    "ai-agent",
-    "agent-mesh",
-    "sovereign-browser",
-    "phone-shield",
-    "dns-discovery",
-    "api-gateway",
-    "browser-automation",
-    "webdriver-bidi"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/abokenan444/web-agent-bridge.git"
-  },
-  "homepage": "https://github.com/abokenan444/web-agent-bridge#readme",
-  "bugs": {
-    "url": "https://github.com/abokenan444/web-agent-bridge/issues"
-  },
-  "files": [
-    "bin/",
-    "server/",
-    "public/*.html",
-    "public/*.txt",
-    "public/*.xml",
-    "public/*.json",
-    "public/css/",
-    "public/js/",
-    "public/script/",
-    "public/assets/",
-    "public/.well-known/",
-    "script/",
-    "sdk/",
-    "templates/",
-    "examples/",
-    "README.md",
-    "README.ar.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "license": "MIT",
-  "dependencies": {
-    "bcryptjs": "^3.0.3",
-    "better-sqlite3": "^11.6.0",
-    "cors": "^2.8.5",
-    "dotenv": "^16.4.5",
-    "express": "^4.21.0",
-    "express-rate-limit": "^7.4.1",
-    "helmet": "^8.0.0",
-    "jsonwebtoken": "^9.0.2",
-    "nodemailer": "^8.0.7",
-    "stripe": "^20.4.1",
-    "ws": "^8.20.0"
-  },
-  "devDependencies": {
-    "all-contributors-cli": "^6.26.1",
-    "jest": "^30.3.0",
-    "supertest": "^7.2.2"
-  },
-  "jest": {
-    "testPathIgnorePatterns": [
-      "/node_modules/",
-      "/packages/"
-    ]
-  }
-}
+{
+  "name": "web-agent-bridge",
+  "version": "3.10.0",
+  "description": "Agent Transaction Bridge — the trust + transaction layer for agentic commerce. Signed intent contracts, idempotent transactions, Ed25519-verifiable receipts, explicit compensation. Plus the original WAB stack: sovereign browser, ShieldQR, SSL health, DNS discovery, agent mesh, and unified gateway for safe AI–website interaction.",
+  "author": "Web Agent Bridge <dev@webagentbridge.com>",
+  "main": "server/index.js",
+  "bin": {
+    "web-agent-bridge": "./bin/cli.js",
+    "wab": "./bin/cli.js",
+    "wab-agent": "./bin/cli.js",
+    "wab-init": "./bin/wab-init.js"
+  },
+  "scripts": {
+    "start": "node server/index.js",
+    "dev": "node server/index.js",
+    "test": "jest --forceExit --detectOpenHandles",
+    "build:script": "node scripts/build.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "bridge",
+    "protocol",
+    "platform",
+    "automation",
+    "web",
+    "ai-agent",
+    "agent-mesh",
+    "sovereign-browser",
+    "phone-shield",
+    "dns-discovery",
+    "api-gateway",
+    "browser-automation",
+    "webdriver-bidi"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abokenan444/web-agent-bridge.git"
+  },
+  "homepage": "https://github.com/abokenan444/web-agent-bridge#readme",
+  "bugs": {
+    "url": "https://github.com/abokenan444/web-agent-bridge/issues"
+  },
+  "files": [
+    "bin/",
+    "server/",
+    "public/*.html",
+    "public/*.txt",
+    "public/*.xml",
+    "public/*.json",
+    "public/css/",
+    "public/js/",
+    "public/script/",
+    "public/assets/",
+    "public/.well-known/",
+    "script/",
+    "sdk/",
+    "templates/",
+    "examples/",
+    "README.md",
+    "README.ar.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "bcryptjs": "^3.0.3",
+    "better-sqlite3": "^11.6.0",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "express": "^4.21.0",
+    "express-rate-limit": "^7.4.1",
+    "helmet": "^8.0.0",
+    "jsonwebtoken": "^9.0.2",
+    "nodemailer": "^8.0.7",
+    "stripe": "^20.4.1",
+    "ws": "^8.20.0"
+  },
+  "devDependencies": {
+    "all-contributors-cli": "^6.26.1",
+    "jest": "^30.3.0",
+    "supertest": "^7.2.2"
+  },
+  "jest": {
+    "testPathIgnorePatterns": [
+      "/node_modules/",
+      "/packages/"
+    ]
+  }
+}

package/public/forgot-password.html

@@ -0,0 +1,68 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Forgot password — Web Agent Bridge</title>
+  <style>body{background:#0a0e1a;color:#f0f4ff;font-family:Inter,-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;margin:0;min-height:100vh}</style>
+  <link rel="stylesheet" href="/css/styles.css?v=3.0.1">
+</head>
+<body>
+  <div class="auth-page">
+    <div class="auth-card fade-in">
+      <div style="text-align:center; margin-bottom:32px;">
+        <a href="/" class="navbar-brand" style="justify-content:center;">
+          <div class="brand-icon">⚡</div>
+          <span>WAB</span>
+        </a>
+      </div>
+      <h1 style="text-align:center;">Forgot password</h1>
+      <p class="subtitle" style="text-align:center;">Enter your email and we'll send you a reset link.</p>
+
+      <div class="alert alert-error" id="errorAlert"></div>
+      <div class="alert alert-success" id="successAlert" style="display:none;">If that email is registered, a reset link has been sent. Check your inbox.</div>
+
+      <form id="forgotForm">
+        <div class="form-group">
+          <label for="email">Email</label>
+          <input type="email" id="email" class="form-input" placeholder="you@example.com" required>
+        </div>
+        <button type="submit" class="btn btn-primary btn-lg">Send reset link</button>
+      </form>
+
+      <div class="auth-footer" style="display:flex;justify-content:space-between;flex-wrap:wrap;gap:8px;">
+        <a href="/login">Back to sign in</a>
+        <a href="/register">Create account</a>
+      </div>
+    </div>
+  </div>
+
+  <script>
+    document.getElementById('forgotForm').addEventListener('submit', async (e) => {
+      e.preventDefault();
+      const errorEl = document.getElementById('errorAlert');
+      const okEl = document.getElementById('successAlert');
+      errorEl.style.display = 'none';
+      okEl.style.display = 'none';
+      const email = document.getElementById('email').value;
+      try {
+        const res = await fetch('/api/auth/forgot-password', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ email })
+        });
+        const data = await res.json();
+        if (!res.ok) {
+          errorEl.textContent = data.error || 'Request failed';
+          errorEl.style.display = 'block';
+          return;
+        }
+        okEl.style.display = 'block';
+      } catch (err) {
+        errorEl.textContent = 'Connection error. Please try again.';
+        errorEl.style.display = 'block';
+      }
+    });
+  </script>
+</body>
+</html>

package/public/login.html

@@ -38,8 +38,9 @@
         <button type="submit" class="btn btn-primary btn-lg">Sign In</button>
       </form>
 
-      <div class="auth-footer">
-        Don't have an account? <a href="/register">Create one</a>
+      <div class="auth-footer" style="display:flex;justify-content:space-between;flex-wrap:wrap;gap:8px;">
+        <a href="/forgot-password.html">Forgot password?</a>
+        <span>Don't have an account? <a href="/register">Create one</a></span>
       </div>
     </div>
   </div>

package/public/reset-password.html

@@ -0,0 +1,84 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Reset password — Web Agent Bridge</title>
+  <style>body{background:#0a0e1a;color:#f0f4ff;font-family:Inter,-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;margin:0;min-height:100vh}</style>
+  <link rel="stylesheet" href="/css/styles.css?v=3.0.1">
+</head>
+<body>
+  <div class="auth-page">
+    <div class="auth-card fade-in">
+      <div style="text-align:center; margin-bottom:32px;">
+        <a href="/" class="navbar-brand" style="justify-content:center;">
+          <div class="brand-icon">⚡</div>
+          <span>WAB</span>
+        </a>
+      </div>
+      <h1 style="text-align:center;">Reset password</h1>
+      <p class="subtitle" style="text-align:center;">Choose a new password for your account.</p>
+
+      <div class="alert alert-error" id="errorAlert"></div>
+      <div class="alert alert-success" id="successAlert" style="display:none;">Password reset. Redirecting to sign-in…</div>
+
+      <form id="resetForm">
+        <div class="form-group">
+          <label for="password">New password</label>
+          <input type="password" id="password" class="form-input" placeholder="At least 8 characters" minlength="8" maxlength="128" required>
+        </div>
+        <div class="form-group">
+          <label for="password2">Confirm new password</label>
+          <input type="password" id="password2" class="form-input" minlength="8" maxlength="128" required>
+        </div>
+        <button type="submit" class="btn btn-primary btn-lg">Reset password</button>
+      </form>
+
+      <div class="auth-footer">
+        <a href="/login">Back to sign in</a>
+      </div>
+    </div>
+  </div>
+
+  <script>
+    const params = new URLSearchParams(window.location.search);
+    const token = params.get('token');
+    const errorEl = document.getElementById('errorAlert');
+    if (!token) {
+      errorEl.textContent = 'Missing reset token in URL.';
+      errorEl.style.display = 'block';
+    }
+
+    document.getElementById('resetForm').addEventListener('submit', async (e) => {
+      e.preventDefault();
+      errorEl.style.display = 'none';
+      const okEl = document.getElementById('successAlert');
+      const pw = document.getElementById('password').value;
+      const pw2 = document.getElementById('password2').value;
+      if (pw !== pw2) {
+        errorEl.textContent = 'Passwords do not match.';
+        errorEl.style.display = 'block';
+        return;
+      }
+      try {
+        const res = await fetch('/api/auth/reset-password', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ token, password: pw })
+        });
+        const data = await res.json();
+        if (!res.ok) {
+          errorEl.textContent = data.error || 'Reset failed';
+          errorEl.style.display = 'block';
+          return;
+        }
+        okEl.style.display = 'block';
+        setTimeout(() => { window.location.href = '/login'; }, 1500);
+      } catch (err) {
+        errorEl.textContent = 'Connection error. Please try again.';
+        errorEl.style.display = 'block';
+      }
+    });
+  </script>
+</body>
+</html>

package/public/verify-email.html

@@ -0,0 +1,76 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Verify email — Web Agent Bridge</title>
+  <style>body{background:#0a0e1a;color:#f0f4ff;font-family:Inter,-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;margin:0;min-height:100vh}</style>
+  <link rel="stylesheet" href="/css/styles.css?v=3.0.1">
+</head>
+<body>
+  <div class="auth-page">
+    <div class="auth-card fade-in">
+      <div style="text-align:center; margin-bottom:32px;">
+        <a href="/" class="navbar-brand" style="justify-content:center;">
+          <div class="brand-icon">⚡</div>
+          <span>WAB</span>
+        </a>
+      </div>
+      <h1 style="text-align:center;" id="title">Verifying…</h1>
+      <p class="subtitle" style="text-align:center;" id="message">Please wait while we confirm your email.</p>
+
+      <div class="alert alert-error" id="errorAlert"></div>
+      <div class="alert alert-success" id="successAlert" style="display:none;">Email verified. You can now use all features.</div>
+
+      <div class="auth-footer" style="text-align:center;">
+        <a href="/dashboard" id="dashLink" style="display:none;">Go to dashboard</a>
+        <a href="/login" id="loginLink">Back to sign in</a>
+      </div>
+    </div>
+  </div>
+
+  <script>
+    (async function () {
+      const params = new URLSearchParams(window.location.search);
+      const token = params.get('token');
+      const titleEl = document.getElementById('title');
+      const msgEl = document.getElementById('message');
+      const errorEl = document.getElementById('errorAlert');
+      const okEl = document.getElementById('successAlert');
+      const dashLink = document.getElementById('dashLink');
+
+      if (!token) {
+        titleEl.textContent = 'Missing token';
+        msgEl.textContent = 'This link is invalid. Sign in and request a new verification email.';
+        errorEl.textContent = 'No verification token in URL.';
+        errorEl.style.display = 'block';
+        return;
+      }
+      try {
+        const res = await fetch('/api/auth/verify-email', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ token })
+        });
+        const data = await res.json();
+        if (!res.ok) {
+          titleEl.textContent = 'Verification failed';
+          msgEl.textContent = data.error || 'Token invalid or expired.';
+          errorEl.textContent = data.error || 'Verification failed';
+          errorEl.style.display = 'block';
+          return;
+        }
+        titleEl.textContent = 'Verified ✓';
+        msgEl.textContent = 'Your email has been confirmed.';
+        okEl.style.display = 'block';
+        dashLink.style.display = 'inline';
+      } catch (err) {
+        titleEl.textContent = 'Network error';
+        msgEl.textContent = 'Please try again later.';
+        errorEl.textContent = 'Connection error.';
+        errorEl.style.display = 'block';
+      }
+    })();
+  </script>
+</body>
+</html>

package/server/index.js

@@ -232,6 +232,15 @@ const licenseLimiter = rateLimit({
   }
 });
 
+// Visitor analytics — record every public page hit (HTML routes only) before
+// they're served by express.static. Skips assets, /api, /admin and other noise.
+try {
+  const visitorTracker = require('./services/visitor-tracker');
+  app.use(visitorTracker.middleware());
+} catch (e) {
+  console.warn('[wab] visitor-tracker disabled:', e.message);
+}
+
 // Whitepaper guard — must run BEFORE express.static so we can apply strict headers
 // and intercept both /whitepaper and /whitepaper.html with the same protections.
 const whitepaperHandler = (req, res) => {

package/server/middleware/auth.js

@@ -47,4 +47,45 @@ function optionalAuth(req, res, next) {
   next();
 }
 
-module.exports = { generateToken, authenticateToken, optionalAuth };
+// Tier hierarchy for requireTier()
+const TIER_ORDER = { free: 0, starter: 1, pro: 2, business: 3, enterprise: 4 };
+
+function tierRank(t) {
+  return TIER_ORDER[String(t || 'free').toLowerCase()] ?? 0;
+}
+
+// requireTier('pro') — must be used AFTER a middleware that puts a site on req.site
+// (e.g. requireSiteOwnership). If no req.site exists, falls back to the user's
+// highest tier across their owned sites.
+function requireTier(minTier) {
+  const required = tierRank(minTier);
+  return (req, res, next) => {
+    let actualTier = 'free';
+    if (req.site && req.site.tier) {
+      actualTier = req.site.tier;
+    } else if (req.user && req.user.id) {
+      try {
+        const { findSitesByUser } = require('../models/db');
+        const sites = findSitesByUser.all(req.user.id) || [];
+        for (const s of sites) {
+          if (tierRank(s.tier) > tierRank(actualTier)) actualTier = s.tier;
+        }
+      } catch (e) {
+        // DB layer may not be ready in tests — be permissive there.
+        if (process.env.NODE_ENV === 'test') return next();
+        return res.status(500).json({ error: 'Tier lookup failed' });
+      }
+    }
+    if (tierRank(actualTier) < required) {
+      return res.status(402).json({
+        error: 'Plan upgrade required',
+        required_tier: minTier,
+        current_tier: actualTier,
+        upgrade_url: '/premium.html'
+      });
+    }
+    next();
+  };
+}
+
+module.exports = { generateToken, authenticateToken, optionalAuth, requireTier };

package/server/migrations/021_visitor_analytics.sql

@@ -0,0 +1,31 @@
+-- ─────────────────────────────────────────────────────────────────────────────
+-- Migration 021 — Visitor analytics (page_visits)
+--
+-- Captures every public page request (registered or anonymous) so the admin
+-- panel can show real traffic data. IPs are hashed for privacy.
+-- ─────────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS page_visits (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  path            TEXT    NOT NULL,
+  query_string    TEXT,
+  referrer        TEXT,
+  host            TEXT,
+  user_agent      TEXT,
+  ip_hash         TEXT,         -- sha256(ip + salt), first 32 chars
+  country         TEXT,         -- best-effort from Cloudflare/CF-IPCountry; nullable
+  device          TEXT,         -- desktop | mobile | tablet | bot
+  is_bot          INTEGER NOT NULL DEFAULT 0,
+  session_id      TEXT,         -- random per-visitor cookie or derived from ip_hash+UA
+  user_id         TEXT,         -- nullable; populated if request carried an auth cookie/token
+  status_code     INTEGER,      -- HTTP status that was returned
+  duration_ms     INTEGER,      -- server-side handler time
+  created_at      TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_pv_created       ON page_visits(created_at);
+CREATE INDEX IF NOT EXISTS idx_pv_path          ON page_visits(path);
+CREATE INDEX IF NOT EXISTS idx_pv_ip            ON page_visits(ip_hash);
+CREATE INDEX IF NOT EXISTS idx_pv_session       ON page_visits(session_id);
+CREATE INDEX IF NOT EXISTS idx_pv_is_bot        ON page_visits(is_bot);
+CREATE INDEX IF NOT EXISTS idx_pv_user          ON page_visits(user_id);

package/server/migrations/022_auth_recovery_verification.sql

@@ -0,0 +1,27 @@
+-- Email verification + password reset
+ALTER TABLE users ADD COLUMN email_verified INTEGER DEFAULT 0;
+ALTER TABLE users ADD COLUMN email_verified_at TEXT;
+
+CREATE TABLE IF NOT EXISTS password_reset_tokens (
+  token_hash TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  expires_at TEXT NOT NULL,
+  used_at TEXT,
+  created_at TEXT DEFAULT (datetime('now')),
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_prt_user ON password_reset_tokens(user_id);
+CREATE INDEX IF NOT EXISTS idx_prt_expires ON password_reset_tokens(expires_at);
+
+CREATE TABLE IF NOT EXISTS email_verification_tokens (
+  token_hash TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  expires_at TEXT NOT NULL,
+  used_at TEXT,
+  created_at TEXT DEFAULT (datetime('now')),
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_evt_user ON email_verification_tokens(user_id);
+CREATE INDEX IF NOT EXISTS idx_evt_expires ON email_verification_tokens(expires_at);

package/server/migrations/023_atp_merchant_commission.sql

@@ -0,0 +1,43 @@
+-- ─────────────────────────────────────────────────────────────────────────────
+-- Migration 023 — ATP Merchant Commission (v3.10.0)
+--
+-- WAB takes a small platform commission (default 0.1% / 10 bps) on every
+-- successful merchant transaction settled through ATP on a paid plan.
+-- Free-tier sites and platform self-payments are exempt.
+--
+-- One row per settled atp_transactions.id. State machine:
+--   pending   → newly recorded
+--   invoiced  → rolled into a Stripe invoice / payout cycle
+--   collected → billed and paid by merchant
+--   refunded  → underlying tx was compensated
+--   waived   → manually waived by an admin
+-- ─────────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS atp_commissions (
+  id                  TEXT PRIMARY KEY,                     -- atp_com_<ulid>
+  transaction_id      TEXT NOT NULL UNIQUE,                 -- one commission per tx
+  intent_id           TEXT NOT NULL,
+  merchant_user_id    TEXT NOT NULL,                        -- the site owner
+  merchant_site_id    TEXT,
+  merchant_tier       TEXT NOT NULL,                        -- snapshot at charge time
+  gross_amount_cents  INTEGER NOT NULL,
+  currency            TEXT NOT NULL DEFAULT 'EUR',
+  commission_bps      INTEGER NOT NULL DEFAULT 10,          -- 10 bps = 0.10%
+  commission_cents    INTEGER NOT NULL DEFAULT 0,
+  status              TEXT NOT NULL DEFAULT 'pending'
+                      CHECK (status IN ('pending','invoiced','collected','refunded','waived')),
+  external_ref        TEXT,                                 -- payment gateway ref (PI id, etc.)
+  notes               TEXT,
+  created_at          TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at          TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (transaction_id) REFERENCES atp_transactions(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_atp_commissions_merchant
+  ON atp_commissions(merchant_user_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_atp_commissions_site
+  ON atp_commissions(merchant_site_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_atp_commissions_status
+  ON atp_commissions(status, created_at DESC);