studio-os 0.2.0

package/scripts/seed.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// Seed a demo studio: settings + owner login, instructors, class types,
+// weekly schedule rules (materialized), pack products, membership plans,
+// a few clients with passes/memberships and two demo bookings.
+//
+// Usage: npm run seed            (refuses to touch a non-empty database)
+//        npm run seed -- --force (seed anyway)
+//        DB_PATH=... npm run seed
+import process from 'node:process';
+import { openDb, setSetting, getSetting } from '../src/db/index.js';
+import { createUser } from '../src/services/auth.js';
+import { generateInstances } from '../src/services/schedule.js';
+import { book } from '../src/services/booking.js';
+
+const force = process.argv.includes('--force');
+const db = openDb(process.argv.includes('--db') ? process.argv[process.argv.indexOf('--db') + 1] : undefined);
+
+const hasData = getSetting(db, 'setup_complete', '0') === '1'
+  || db.prepare('SELECT COUNT(*) c FROM clients').get().c > 0;
+if (hasData && !force) {
+  console.error('Database already has data — refusing to seed. Re-run with --force to seed anyway.');
+  process.exit(1);
+}
+
+const OWNER_EMAIL = 'owner@example.com';
+const OWNER_PASSWORD = 'studio-demo';
+
+db.transaction(() => {
+  // --- settings + owner ------------------------------------------------
+  setSetting(db, 'studio_name', 'Harbour Movement Studio');
+  setSetting(db, 'timezone', 'Asia/Hong_Kong');
+  setSetting(db, 'currency', 'HKD');
+  setSetting(db, 'cancellation_window_hours', '12');
+  setSetting(db, 'late_cancel_policy', 'forfeit');
+  setSetting(db, 'waiver_markdown', [
+    '## Liability waiver',
+    '',
+    'I understand that participation in classes at **Harbour Movement Studio** involves physical activity',
+    'and carries a risk of injury. I confirm that I am physically fit to participate, and I agree to',
+    'inform the instructor of any injuries or conditions before class.',
+    '',
+    'I release the studio and its instructors from liability for injuries sustained during normal',
+    'class activity, except where caused by negligence.',
+  ].join('\n'));
+  if (!db.prepare('SELECT id FROM users WHERE email = ?').get(OWNER_EMAIL)) {
+    createUser(db, { email: OWNER_EMAIL, password: OWNER_PASSWORD, name: 'Demo Owner', role: 'owner' });
+  }
+  setSetting(db, 'setup_complete', '1');
+
+  // --- instructors ------------------------------------------------------
+  const insInstructor = db.prepare('INSERT INTO instructors (name, bio) VALUES (?, ?)');
+  const mei = insInstructor.run('Mei Ling', 'RYT-500 vinyasa and yin teacher, 8 years.').lastInsertRowid;
+  const carlos = insInstructor.run('Carlos Reyes', 'Former gymnast; handstands and mobility.').lastInsertRowid;
+  const priya = insInstructor.run('Priya Nair', 'Mat and reformer pilates, pre/post-natal certified.').lastInsertRowid;
+
+  // --- class types ------------------------------------------------------
+  const insType = db.prepare(
+    'INSERT INTO class_types (name, description, duration_min, capacity, drop_in_price_cents, credits_required, color) VALUES (?, ?, ?, ?, ?, ?, ?)'
+  );
+  const vinyasa = insType.run('Vinyasa Flow', 'Breath-led flowing yoga, all levels.', 60, 14, 18000, 1, '#4f7cac').lastInsertRowid;
+  const pilates = insType.run('Mat Pilates', 'Core-focused mat work.', 55, 10, 20000, 1, '#a06cd5').lastInsertRowid;
+  const handstand = insType.run('Handstand Basics', 'Wall drills to freestanding holds.', 75, 8, 25000, 2, '#e07a5f').lastInsertRowid;
+  const yin = insType.run('Yin & Restore', 'Slow deep stretch. Great for beginners.', 60, 16, 16000, 1, '#3d8168').lastInsertRowid;
+
+  // --- weekly rules (studio-local times) --------------------------------
+  const insRule = db.prepare(
+    'INSERT INTO schedule_rules (class_type_id, instructor_id, weekday, start_time) VALUES (?, ?, ?, ?)'
+  );
+  insRule.run(vinyasa, mei, 1, '07:15');    // Mon
+  insRule.run(vinyasa, mei, 3, '07:15');    // Wed
+  insRule.run(vinyasa, mei, 6, '10:00');    // Sat
+  insRule.run(pilates, priya, 2, '18:30');  // Tue
+  insRule.run(pilates, priya, 4, '18:30');  // Thu
+  insRule.run(handstand, carlos, 6, '14:00'); // Sat
+  insRule.run(yin, mei, 0, '17:00');        // Sun
+  insRule.run(yin, priya, 5, '19:30');      // Fri
+
+  // --- products ---------------------------------------------------------
+  const insPack = db.prepare('INSERT INTO pack_products (name, credits, price_cents, validity_days) VALUES (?, ?, ?, ?)');
+  insPack.run('5 Class Pack', 5, 80000, 90);
+  insPack.run('10 Class Pack', 10, 150000, 180);
+  insPack.run('20 Class Pack', 20, 280000, 365);
+  const insPlan = db.prepare('INSERT INTO membership_plans (name, price_cents, unlimited, credits_per_month) VALUES (?, ?, ?, ?)');
+  insPlan.run('Unlimited Monthly', 128000, 1, null);
+  insPlan.run('8 Classes / Month', 88000, 0, 8);
+
+  // --- clients, passes, memberships ------------------------------------
+  const insClient = db.prepare(
+    "INSERT INTO clients (name, email, phone, waiver_signed_at, source) VALUES (?, ?, ?, ?, 'manual')"
+  );
+  const now = new Date().toISOString();
+  const alice = insClient.run('Alice Chan', 'alice.chan@example.com', '+852 9123 0001', now).lastInsertRowid;
+  const ben = insClient.run('Ben Kwok', 'ben.kwok@example.com', '+852 9123 0002', now).lastInsertRowid;
+  const carmen = insClient.run('Carmen Ho', 'carmen.ho@example.com', '+852 9123 0003', now).lastInsertRowid;
+  insClient.run('Dev Patel', 'dev.patel@example.com', '+852 9123 0004', null); // no waiver yet
+
+  const in6months = new Date(Date.now() + 182 * 86400000).toISOString().slice(0, 10);
+  db.prepare(
+    `INSERT INTO passes (client_id, name, credits_total, credits_remaining, expires_on, price_paid_cents, source)
+     VALUES (?, '10 Class Pack', 10, 7, ?, 150000, 'manual')`
+  ).run(alice, in6months);
+  db.prepare(
+    `INSERT INTO passes (client_id, name, credits_total, credits_remaining, expires_on, price_paid_cents, source)
+     VALUES (?, '5 Class Pack', 5, 5, ?, 80000, 'manual')`
+  ).run(ben, in6months);
+  const today = new Date().toISOString().slice(0, 10);
+  db.prepare(
+    `INSERT INTO memberships (client_id, plan_name, status, started_on, unlimited, cycle_started_on)
+     VALUES (?, 'Unlimited Monthly', 'active', ?, 1, ?)`
+  ).run(carmen, today, today);
+  db.prepare(
+    `INSERT INTO payments (client_id, amount_cents, currency, method, reference, what, status)
+     VALUES (?, 150000, 'HKD', 'cash', '10 Class Pack', 'pack', 'paid')`
+  ).run(alice);
+  db.prepare(
+    `INSERT INTO payments (client_id, amount_cents, currency, method, reference, what, status)
+     VALUES (?, 80000, 'HKD', 'fps', '5 Class Pack', 'pack', 'paid')`
+  ).run(ben);
+  db.prepare(
+    `INSERT INTO payments (client_id, amount_cents, currency, method, reference, what, status)
+     VALUES (?, 128000, 'HKD', 'cash', 'Unlimited Monthly', 'membership', 'paid')`
+  ).run(carmen);
+})();
+
+// Materialize the schedule, then drop two demo bookings on the nearest classes.
+const created = generateInstances(db);
+const upcoming = db.prepare(
+  "SELECT id FROM class_instances WHERE status = 'scheduled' AND starts_at > ? ORDER BY starts_at LIMIT 2"
+).all(new Date().toISOString());
+const aliceId = db.prepare('SELECT id FROM clients WHERE email = ?').get('alice.chan@example.com').id;
+const carmenId = db.prepare('SELECT id FROM clients WHERE email = ?').get('carmen.ho@example.com').id;
+let bookings = 0;
+for (const inst of upcoming) {
+  try {
+    book(db, aliceId, inst.id); bookings++;
+    book(db, carmenId, inst.id); bookings++;
+  } catch { /* capacity or duplicate — fine for a seed */ }
+}
+
+console.log(`Seeded demo studio "Harbour Movement Studio":
+  3 instructors, 4 class types, 8 weekly rules → ${created} class instances
+  3 pack products, 2 membership plans
+  4 clients (2 passes, 1 unlimited membership), ${bookings} demo bookings
+
+Admin login: ${OWNER_EMAIL} / ${OWNER_PASSWORD}
+Start the app: npm start  →  http://localhost:3000`);
+db.close();

package/src/app.js

@@ -0,0 +1,141 @@
+import express from 'express';
+import cookieSession from 'cookie-session';
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getSetting, allSettings } from './db/index.js';
+import { formatInTz } from './lib/time.js';
+import { createRateLimiter } from './lib/ratelimit.js';
+import { createMailer } from './services/mailer.js';
+import { createStripeService } from './services/stripe.js';
+import setupRoutes from './routes/setup.js';
+import authRoutes from './routes/auth.js';
+import publicRoutes from './routes/public.js';
+import meRoutes from './routes/me.js';
+import adminRoutes from './routes/admin.js';
+import instructorRoutes from './routes/instructor.js';
+import webhookRoutes from './routes/webhooks.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Build the Express app. Dependencies are injectable for tests:
+ * createApp({ db, mailer?, stripeService?, env?, now? })
+ * `now` (clock) is used by the rate limiters so tests can move time.
+ */
+export function createApp({ db, mailer, stripeService, env = process.env, now = Date.now }) {
+  const app = express();
+  app.set('view engine', 'ejs');
+  app.set('views', path.join(__dirname, '..', 'views'));
+  app.disable('x-powered-by');
+
+  const services = {
+    db,
+    mailer: mailer || createMailer({ env }),
+    stripe: stripeService || createStripeService({ env }),
+    env,
+    baseUrl(req) {
+      return env.BASE_URL || `${req.protocol}://${req.get('host')}`;
+    },
+  };
+  app.locals.services = services;
+
+  // Stripe webhook needs the raw body for signature verification — mount
+  // before any body parser.
+  app.use('/webhooks/stripe', express.raw({ type: '*/*' }), webhookRoutes(services));
+
+  app.use(express.urlencoded({ extended: true }));
+  app.use(express.static(path.join(__dirname, '..', 'public')));
+  app.use(cookieSession({
+    name: 'studio_session',
+    keys: [getSetting(db, 'app_secret', 'dev-secret')],
+    sameSite: 'lax',
+    httpOnly: true,
+    maxAge: 30 * 24 * 3600000,
+  }));
+
+  // View locals: settings + formatting helpers, refreshed per request.
+  app.use((req, res, next) => {
+    const s = allSettings(db);
+    res.locals.settings = s;
+    res.locals.tz = s.timezone || 'Asia/Hong_Kong';
+    res.locals.currency = s.currency || 'HKD';
+    res.locals.fmtDt = (iso, opts) => formatInTz(res.locals.tz, iso, opts);
+    res.locals.fmtMoney = (cents) => new Intl.NumberFormat('en', {
+      style: 'currency', currency: res.locals.currency, minimumFractionDigits: 0,
+    }).format((cents || 0) / 100);
+    res.locals.user = req.session && req.session.userId
+      ? db.prepare('SELECT id, email, name, role FROM users WHERE id = ?').get(req.session.userId)
+      : null;
+    res.locals.stripeConfigured = services.stripe.configured;
+    res.locals.smtpConfigured = services.mailer.smtpConfigured;
+    res.locals.flash = req.session ? req.session.flash : null;
+    if (req.session) delete req.session.flash;
+    next();
+  });
+
+  // Rate limiting (before CSRF so hammering can't even probe tokens):
+  // in-memory fixed window, per IP + route. Single-process; resets on restart.
+  const RL_WINDOW = 15 * 60 * 1000;
+  app.post('/magic-link', createRateLimiter({
+    windowMs: RL_WINDOW, max: 5, env, now,
+    message: 'Too many link requests — please wait 15 minutes and try again.',
+  }));
+  app.post('/admin/login', createRateLimiter({
+    windowMs: RL_WINDOW, max: 10, env, now,
+    message: 'Too many login attempts — please wait 15 minutes and try again.',
+  }));
+  app.post(['/class/:id/book', '/buy/pack/:id', '/buy/membership/:id'], createRateLimiter({
+    windowMs: RL_WINDOW, max: 30, env, now,
+    message: 'Too many booking attempts from your address — please wait a few minutes and try again.',
+  }));
+
+  // CSRF protection: a random per-session token lives in the signed cookie
+  // session and must be echoed back (hidden `_csrf` input or `x-csrf-token`
+  // header) on every state-changing request. /webhooks/stripe is exempt — it
+  // is mounted before this middleware and authenticated by Stripe signature.
+  app.use((req, res, next) => {
+    if (!req.session.csrf) req.session.csrf = crypto.randomBytes(24).toString('hex');
+    res.locals.csrfToken = req.session.csrf;
+    if (!['POST', 'PUT', 'DELETE', 'PATCH'].includes(req.method)) return next();
+    if (req.path.startsWith('/webhooks/')) return next();
+    const sent = (req.body && req.body._csrf) || req.get('x-csrf-token') || '';
+    const a = Buffer.from(String(sent));
+    const b = Buffer.from(req.session.csrf);
+    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
+      return res.status(403).render('error', {
+        title: 'Session expired',
+        message: 'Your form session expired or the security token was missing. Please go back, refresh the page, and try again.',
+      });
+    }
+    next();
+  });
+
+  // First-run gate: until setup completes, everything routes to the wizard.
+  app.use((req, res, next) => {
+    const done = getSetting(db, 'setup_complete', '0') === '1';
+    if (!done && !req.path.startsWith('/setup') && !req.path.startsWith('/vendor')
+        && !req.path.startsWith('/css') && !req.path.startsWith('/js')) {
+      return res.redirect('/setup');
+    }
+    if (done && req.path.startsWith('/setup')) return res.redirect('/');
+    next();
+  });
+
+  app.use('/setup', setupRoutes(services));
+  app.use('/', authRoutes(services));
+  app.use('/admin', adminRoutes(services));
+  app.use('/instructor', instructorRoutes(services));
+  app.use('/me', meRoutes(services));
+  app.use('/', publicRoutes(services));
+
+  // 404 + error handler
+  app.use((req, res) => res.status(404).render('error', { title: 'Not found', message: 'Page not found.' }));
+  // eslint-disable-next-line no-unused-vars
+  app.use((err, req, res, next) => {
+    console.error('[error]', err);
+    res.status(500).render('error', { title: 'Error', message: err.expose ? err.message : 'Something went wrong.' });
+  });
+
+  return app;
+}

package/src/db/002-instructor-role.sql

@@ -0,0 +1,26 @@
+-- v2: instructor logins. Adds 'instructor' to the users role CHECK (SQLite
+-- cannot alter a CHECK in place, so the table is rebuilt — no FKs reference
+-- users) and a many-to-many instructor↔class assignment table.
+
+CREATE TABLE users_v2 (
+  id            INTEGER PRIMARY KEY,
+  email         TEXT NOT NULL UNIQUE COLLATE NOCASE,
+  password_hash TEXT NOT NULL,
+  name          TEXT NOT NULL DEFAULT '',
+  role          TEXT NOT NULL DEFAULT 'staff' CHECK (role IN ('owner','staff','instructor')),
+  created_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
+);
+INSERT INTO users_v2 (id, email, password_hash, name, role, created_at)
+  SELECT id, email, password_hash, name, role, created_at FROM users;
+DROP TABLE users;
+ALTER TABLE users_v2 RENAME TO users;
+
+-- instructor_id → users.id (role 'instructor'); class_id → class_instances.id.
+-- CASCADE so deleting an account or a not-yet-booked future instance (rule
+-- delete) never strands or blocks on an assignment row.
+CREATE TABLE IF NOT EXISTS instructor_class_assignments (
+  instructor_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  class_id      INTEGER NOT NULL REFERENCES class_instances(id) ON DELETE CASCADE,
+  PRIMARY KEY (instructor_id, class_id)
+);
+CREATE INDEX IF NOT EXISTS idx_ica_class ON instructor_class_assignments(class_id);

package/src/db/index.js

@@ -0,0 +1,82 @@
+import Database from 'better-sqlite3';
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const MIGRATIONS = [
+  { version: 1, file: 'schema.sql' },
+  { version: 2, file: '002-instructor-role.sql' },
+];
+
+const DEFAULT_SETTINGS = {
+  studio_name: '',
+  timezone: 'Asia/Hong_Kong',
+  currency: 'HKD',
+  cancellation_window_hours: '12',
+  late_cancel_policy: 'forfeit', // forfeit | refund
+  waiver_markdown: '## Liability Waiver\n\nI understand that participation in classes involves physical activity and I take part at my own risk. I confirm I am in good health and will inform the instructor of any injuries or conditions.\n\nBy checking the box I agree to this waiver.',
+  setup_complete: '0',
+  horizon_weeks: '8',
+};
+
+/**
+ * Open (or create) the database, enable WAL, run migrations, seed defaults.
+ * @param {string} [dbPath] file path or ':memory:' (tests)
+ */
+export function openDb(dbPath) {
+  const file = dbPath || process.env.DB_PATH || path.join(process.cwd(), 'data', 'studio.db');
+  if (file !== ':memory:') fs.mkdirSync(path.dirname(file), { recursive: true });
+  const db = new Database(file);
+  db.pragma('journal_mode = WAL');
+  db.pragma('foreign_keys = ON');
+  db.pragma('busy_timeout = 5000');
+  migrate(db);
+  return db;
+}
+
+function migrate(db) {
+  db.exec('CREATE TABLE IF NOT EXISTS schema_migrations (version INTEGER PRIMARY KEY, applied_at TEXT NOT NULL)');
+  const applied = new Set(db.prepare('SELECT version FROM schema_migrations').all().map((r) => r.version));
+  for (const m of MIGRATIONS) {
+    if (applied.has(m.version)) continue;
+    const sql = fs.readFileSync(path.join(__dirname, m.file), 'utf8');
+    db.transaction(() => {
+      db.exec(sql);
+      db.prepare('INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)')
+        .run(m.version, new Date().toISOString());
+    })();
+  }
+  // seed default settings (INSERT OR IGNORE keeps existing values)
+  const ins = db.prepare('INSERT OR IGNORE INTO settings (key, value) VALUES (?, ?)');
+  for (const [k, v] of Object.entries(DEFAULT_SETTINGS)) ins.run(k, v);
+  // app secret: generated once, persisted, overridable via env
+  if (!process.env.APP_SECRET) {
+    ins.run('app_secret', crypto.randomBytes(32).toString('hex'));
+  }
+}
+
+export function getSetting(db, key, fallback = '') {
+  if (key === 'app_secret' && process.env.APP_SECRET) return process.env.APP_SECRET;
+  const row = db.prepare('SELECT value FROM settings WHERE key = ?').get(key);
+  return row ? row.value : fallback;
+}
+
+export function setSetting(db, key, value) {
+  db.prepare('INSERT INTO settings (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value')
+    .run(key, String(value));
+}
+
+export function allSettings(db) {
+  const out = {};
+  for (const r of db.prepare('SELECT key, value FROM settings').all()) out[r.key] = r.value;
+  if (process.env.APP_SECRET) out.app_secret = process.env.APP_SECRET;
+  return out;
+}
+
+export function audit(db, who, action, entity = '') {
+  db.prepare('INSERT INTO audit_log (who, action, entity, at) VALUES (?, ?, ?, ?)')
+    .run(who || '', action, entity, new Date().toISOString());
+}

package/src/db/schema.sql

@@ -0,0 +1,164 @@
+-- Studio OS schema v1. All timestamps are UTC ISO-8601 strings.
+
+CREATE TABLE IF NOT EXISTS settings (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL DEFAULT ''
+);
+
+CREATE TABLE IF NOT EXISTS users (
+  id            INTEGER PRIMARY KEY,
+  email         TEXT NOT NULL UNIQUE COLLATE NOCASE,
+  password_hash TEXT NOT NULL,
+  name          TEXT NOT NULL DEFAULT '',
+  role          TEXT NOT NULL DEFAULT 'staff' CHECK (role IN ('owner','staff')),
+  created_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
+);
+
+CREATE TABLE IF NOT EXISTS instructors (
+  id     INTEGER PRIMARY KEY,
+  name   TEXT NOT NULL,
+  bio    TEXT NOT NULL DEFAULT '',
+  active INTEGER NOT NULL DEFAULT 1
+);
+
+CREATE TABLE IF NOT EXISTS class_types (
+  id                  INTEGER PRIMARY KEY,
+  name                TEXT NOT NULL,
+  description         TEXT NOT NULL DEFAULT '',
+  duration_min        INTEGER NOT NULL DEFAULT 60,
+  capacity            INTEGER NOT NULL DEFAULT 10,
+  drop_in_price_cents INTEGER NOT NULL DEFAULT 0,
+  credits_required    INTEGER NOT NULL DEFAULT 1,
+  color               TEXT NOT NULL DEFAULT '#4f7cac',
+  active              INTEGER NOT NULL DEFAULT 1
+);
+
+CREATE TABLE IF NOT EXISTS schedule_rules (
+  id                INTEGER PRIMARY KEY,
+  class_type_id     INTEGER NOT NULL REFERENCES class_types(id),
+  instructor_id     INTEGER REFERENCES instructors(id),
+  weekday           INTEGER NOT NULL CHECK (weekday BETWEEN 0 AND 6), -- 0=Sunday
+  start_time        TEXT NOT NULL,                                    -- 'HH:MM' studio-local
+  capacity_override INTEGER,
+  active_from       TEXT,                                             -- 'YYYY-MM-DD' local
+  active_until      TEXT,
+  active            INTEGER NOT NULL DEFAULT 1
+);
+
+CREATE TABLE IF NOT EXISTS class_instances (
+  id            INTEGER PRIMARY KEY,
+  class_type_id INTEGER NOT NULL REFERENCES class_types(id),
+  instructor_id INTEGER REFERENCES instructors(id),
+  rule_id       INTEGER REFERENCES schedule_rules(id),
+  starts_at     TEXT NOT NULL,               -- UTC ISO
+  duration_min  INTEGER NOT NULL DEFAULT 60,
+  capacity      INTEGER NOT NULL DEFAULT 10,
+  status        TEXT NOT NULL DEFAULT 'scheduled' CHECK (status IN ('scheduled','cancelled')),
+  notes         TEXT NOT NULL DEFAULT ''
+);
+CREATE UNIQUE INDEX IF NOT EXISTS uq_instance_rule_start
+  ON class_instances(rule_id, starts_at) WHERE rule_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_instances_starts ON class_instances(starts_at);
+
+CREATE TABLE IF NOT EXISTS clients (
+  id               INTEGER PRIMARY KEY,
+  name             TEXT NOT NULL,
+  email            TEXT NOT NULL UNIQUE COLLATE NOCASE,
+  phone            TEXT NOT NULL DEFAULT '',
+  notes            TEXT NOT NULL DEFAULT '',
+  waiver_signed_at TEXT,
+  source           TEXT NOT NULL DEFAULT 'manual' CHECK (source IN ('manual','import','self')),
+  created_at       TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
+);
+
+CREATE TABLE IF NOT EXISTS passes (
+  id               INTEGER PRIMARY KEY,
+  client_id        INTEGER NOT NULL REFERENCES clients(id),
+  name             TEXT NOT NULL,
+  credits_total    INTEGER NOT NULL,
+  credits_remaining INTEGER NOT NULL,
+  expires_on       TEXT,                     -- 'YYYY-MM-DD' local date, inclusive
+  price_paid_cents INTEGER NOT NULL DEFAULT 0,
+  source           TEXT NOT NULL DEFAULT 'manual' CHECK (source IN ('purchase','import','manual')),
+  created_at       TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
+);
+CREATE INDEX IF NOT EXISTS idx_passes_client ON passes(client_id);
+
+CREATE TABLE IF NOT EXISTS membership_plans (
+  id                INTEGER PRIMARY KEY,
+  name              TEXT NOT NULL,
+  price_cents       INTEGER NOT NULL DEFAULT 0,
+  interval          TEXT NOT NULL DEFAULT 'month',
+  unlimited         INTEGER NOT NULL DEFAULT 1,
+  credits_per_month INTEGER,
+  stripe_price_id   TEXT,
+  active            INTEGER NOT NULL DEFAULT 1
+);
+
+-- Purchasable class-pack products shown on the buy page (SPEC is silent on a
+-- pack catalogue; passes are per-client, so products live here).
+CREATE TABLE IF NOT EXISTS pack_products (
+  id              INTEGER PRIMARY KEY,
+  name            TEXT NOT NULL,
+  credits         INTEGER NOT NULL,
+  price_cents     INTEGER NOT NULL DEFAULT 0,
+  validity_days   INTEGER,                    -- NULL = never expires
+  stripe_price_id TEXT,
+  active          INTEGER NOT NULL DEFAULT 1
+);
+
+CREATE TABLE IF NOT EXISTS memberships (
+  id                      INTEGER PRIMARY KEY,
+  client_id               INTEGER NOT NULL REFERENCES clients(id),
+  plan_id                 INTEGER REFERENCES membership_plans(id),
+  plan_name               TEXT NOT NULL,
+  status                  TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','paused','cancelled')),
+  started_on              TEXT NOT NULL,     -- 'YYYY-MM-DD'
+  renews_on               TEXT,
+  stripe_subscription_id  TEXT,
+  unlimited               INTEGER NOT NULL DEFAULT 1,
+  credits_per_month       INTEGER,
+  credits_used_this_cycle INTEGER NOT NULL DEFAULT 0,
+  cycle_started_on        TEXT               -- 'YYYY-MM-DD'
+);
+CREATE INDEX IF NOT EXISTS idx_memberships_client ON memberships(client_id);
+
+CREATE TABLE IF NOT EXISTS bookings (
+  id                INTEGER PRIMARY KEY,
+  class_instance_id INTEGER NOT NULL REFERENCES class_instances(id),
+  client_id         INTEGER NOT NULL REFERENCES clients(id),
+  status            TEXT NOT NULL DEFAULT 'booked'
+                    CHECK (status IN ('booked','waitlist','cancelled','attended','no_show')),
+  paid_with         TEXT NOT NULL
+                    CHECK (paid_with IN ('pack','membership','drop_in_online','drop_in_manual','comp')),
+  pass_id           INTEGER REFERENCES passes(id),
+  membership_id     INTEGER REFERENCES memberships(id),
+  created_at        TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now')),
+  cancelled_at      TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS uq_booking_active
+  ON bookings(class_instance_id, client_id) WHERE status != 'cancelled';
+CREATE INDEX IF NOT EXISTS idx_bookings_instance ON bookings(class_instance_id);
+CREATE INDEX IF NOT EXISTS idx_bookings_client ON bookings(client_id);
+
+CREATE TABLE IF NOT EXISTS payments (
+  id                INTEGER PRIMARY KEY,
+  client_id         INTEGER REFERENCES clients(id),
+  amount_cents      INTEGER NOT NULL,
+  currency          TEXT NOT NULL DEFAULT 'HKD',
+  method            TEXT NOT NULL CHECK (method IN ('stripe','cash','fps','other')),
+  reference         TEXT NOT NULL DEFAULT '',
+  what              TEXT NOT NULL CHECK (what IN ('drop_in','pack','membership')),
+  status            TEXT NOT NULL DEFAULT 'paid' CHECK (status IN ('paid','pending')),
+  stripe_session_id TEXT UNIQUE,
+  created_at        TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
+);
+CREATE INDEX IF NOT EXISTS idx_payments_created ON payments(created_at);
+
+CREATE TABLE IF NOT EXISTS audit_log (
+  id     INTEGER PRIMARY KEY,
+  who    TEXT NOT NULL DEFAULT '',
+  action TEXT NOT NULL,
+  entity TEXT NOT NULL DEFAULT '',
+  at     TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
+);

package/src/lib/ratelimit.js

@@ -0,0 +1,50 @@
+// Tiny in-memory fixed-window rate limiter. No dependencies.
+//
+// Deliberately simple and honest about its limits: counters live in this
+// process's memory, so they reset on restart and are per-process (a
+// multi-instance deployment would need a shared store). Behind a reverse
+// proxy, set TRUST_PROXY=1 so the client IP is read from the first
+// X-Forwarded-For hop; without it the header is ignored (spoofable) and the
+// socket address is used.
+
+export function clientIp(req, env = process.env) {
+  if (env.TRUST_PROXY) {
+    const xff = req.get('x-forwarded-for');
+    if (xff) return xff.split(',')[0].trim();
+  }
+  return (req.socket && req.socket.remoteAddress) || 'unknown';
+}
+
+/**
+ * createRateLimiter({ windowMs, max, env?, now?, message? }) → Express middleware.
+ * Fixed window keyed on client IP + matched route pattern (so /class/1/book
+ * and /class/2/book share one bucket). `now` is injectable for tests.
+ */
+export function createRateLimiter({ windowMs, max, env = process.env, now = Date.now, message } = {}) {
+  const buckets = new Map(); // key → { window, count }
+  const mw = (req, res, next) => {
+    const windowId = Math.floor(now() / windowMs);
+    const route = (req.route && req.route.path) || req.path;
+    const key = `${clientIp(req, env)}|${req.method} ${route}`;
+    let b = buckets.get(key);
+    if (!b || b.window !== windowId) {
+      b = { window: windowId, count: 0 };
+      buckets.set(key, b);
+    }
+    b.count += 1;
+    if (b.count > max) {
+      res.set('Retry-After', String(Math.ceil(windowMs / 1000)));
+      return res.status(429).render('error', {
+        title: 'Too many requests',
+        message: message || 'Too many requests from your address — please wait a few minutes and try again.',
+      });
+    }
+    // opportunistic cleanup so the map cannot grow without bound
+    if (buckets.size > 10000) {
+      for (const [k, v] of buckets) if (v.window !== windowId) buckets.delete(k);
+    }
+    next();
+  };
+  mw.buckets = buckets; // exposed for tests/inspection
+  return mw;
+}