studio-os 0.2.0

package/src/services/booking.js

@@ -0,0 +1,261 @@
+// Core booking engine. Pure DB logic — no email/HTTP side effects. Callers get
+// back event objects (e.g. promoted bookings) and decide whether to notify.
+// All mutating operations run inside a single better-sqlite3 transaction, so
+// capacity checks and credit movements are atomic.
+
+import { getSetting } from '../db/index.js';
+import { localDateStr, hoursBetween, addDays } from '../lib/time.js';
+
+export class BookingError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+const OCCUPYING = "('booked','attended','no_show')"; // statuses that hold a spot
+
+function bookedCount(db, instanceId) {
+  return db.prepare(
+    `SELECT COUNT(*) c FROM bookings WHERE class_instance_id = ? AND status IN ${OCCUPYING}`
+  ).get(instanceId).c;
+}
+
+/** Lazy monthly-credit cycle reset for a credit-based membership. */
+function refreshMembershipCycle(db, m, todayLocal) {
+  if (m.unlimited || !m.credits_per_month) return m;
+  let cycleStart = m.cycle_started_on || m.started_on;
+  let changed = false;
+  // advance cycle start by whole months until it is the current cycle
+  while (addMonths(cycleStart, 1) <= todayLocal) {
+    cycleStart = addMonths(cycleStart, 1);
+    changed = true;
+  }
+  if (changed) {
+    db.prepare('UPDATE memberships SET cycle_started_on = ?, credits_used_this_cycle = 0 WHERE id = ?')
+      .run(cycleStart, m.id);
+    m = { ...m, cycle_started_on: cycleStart, credits_used_this_cycle: 0 };
+  } else if (!m.cycle_started_on) {
+    db.prepare('UPDATE memberships SET cycle_started_on = ? WHERE id = ?').run(cycleStart, m.id);
+    m = { ...m, cycle_started_on: cycleStart };
+  }
+  return m;
+}
+
+function addMonths(dateStr, n) {
+  const [y, m, d] = dateStr.split('-').map(Number);
+  const dt = new Date(Date.UTC(y, m - 1 + n, 1));
+  const lastDay = new Date(Date.UTC(dt.getUTCFullYear(), dt.getUTCMonth() + 1, 0)).getUTCDate();
+  dt.setUTCDate(Math.min(d, lastDay));
+  return dt.toISOString().slice(0, 10);
+}
+
+/**
+ * Decide how a client would pay for a class, per spec priority:
+ * active membership → soonest-expiring pack with credits → drop-in.
+ * Returns { paidWith, passId?, membershipId? } without mutating anything.
+ */
+export function resolvePayment(db, clientId, instance, { now } = {}) {
+  const tz = getSetting(db, 'timezone', 'Asia/Hong_Kong');
+  const nowIso = now || new Date().toISOString();
+  const today = localDateStr(tz, nowIso);
+  const classDay = localDateStr(tz, instance.starts_at);
+  const creditsNeeded = instance.credits_required ?? 1;
+
+  // 1. active membership
+  const memberships = db.prepare(
+    "SELECT * FROM memberships WHERE client_id = ? AND status = 'active' ORDER BY unlimited DESC, id"
+  ).all(clientId);
+  for (let m of memberships) {
+    if (m.unlimited) return { paidWith: 'membership', membershipId: m.id };
+    m = refreshMembershipCycle(db, m, today);
+    if ((m.credits_per_month || 0) - m.credits_used_this_cycle >= creditsNeeded) {
+      return { paidWith: 'membership', membershipId: m.id };
+    }
+  }
+
+  // 2. pack with credits, soonest-expiring first (NULL expiry sorts last),
+  //    must not be expired before the class date
+  const pass = db.prepare(
+    `SELECT * FROM passes
+     WHERE client_id = ? AND credits_remaining >= ?
+       AND (expires_on IS NULL OR expires_on >= ?)
+     ORDER BY (expires_on IS NULL), expires_on, id LIMIT 1`
+  ).get(clientId, creditsNeeded, classDay > today ? classDay : today);
+  if (pass) return { paidWith: 'pack', passId: pass.id };
+
+  // 3. drop-in (caller decides online vs manual)
+  return { paidWith: 'drop_in' };
+}
+
+function deduct(db, resolution, creditsNeeded) {
+  if (resolution.paidWith === 'pack') {
+    const r = db.prepare(
+      'UPDATE passes SET credits_remaining = credits_remaining - ? WHERE id = ? AND credits_remaining >= ?'
+    ).run(creditsNeeded, resolution.passId, creditsNeeded);
+    if (r.changes !== 1) throw new BookingError('no_credits', 'Pass no longer has enough credits');
+  } else if (resolution.paidWith === 'membership') {
+    db.prepare(
+      'UPDATE memberships SET credits_used_this_cycle = credits_used_this_cycle + ? WHERE id = ? AND unlimited = 0'
+    ).run(creditsNeeded, resolution.membershipId);
+  }
+}
+
+function refund(db, booking, creditsNeeded) {
+  if (booking.paid_with === 'pack' && booking.pass_id) {
+    db.prepare('UPDATE passes SET credits_remaining = credits_remaining + ? WHERE id = ?')
+      .run(creditsNeeded, booking.pass_id);
+  } else if (booking.paid_with === 'membership' && booking.membership_id) {
+    db.prepare(
+      'UPDATE memberships SET credits_used_this_cycle = MAX(0, credits_used_this_cycle - ?) WHERE id = ? AND unlimited = 0'
+    ).run(creditsNeeded, booking.membership_id);
+  }
+}
+
+function loadInstance(db, instanceId) {
+  const inst = db.prepare(
+    `SELECT ci.*, ct.credits_required, ct.name AS class_name, ct.drop_in_price_cents
+     FROM class_instances ci JOIN class_types ct ON ct.id = ci.class_type_id
+     WHERE ci.id = ?`
+  ).get(instanceId);
+  if (!inst) throw new BookingError('not_found', 'Class not found');
+  return inst;
+}
+
+/**
+ * Book a client into a class instance.
+ * options: { paidWith } to force ('drop_in_online'|'drop_in_manual'|'comp'),
+ *          { now } ISO override for tests, { allowPast } for admin walk-ins.
+ * Returns the booking row plus { waitlisted: bool }.
+ */
+export function book(db, clientId, instanceId, options = {}) {
+  const nowIso = options.now || new Date().toISOString();
+  return db.transaction(() => {
+    const inst = loadInstance(db, instanceId);
+    if (inst.status !== 'scheduled') throw new BookingError('class_cancelled', 'Class is cancelled');
+    if (!options.allowPast && inst.starts_at <= nowIso) {
+      throw new BookingError('in_past', 'Class has already started');
+    }
+    const dup = db.prepare(
+      "SELECT id FROM bookings WHERE class_instance_id = ? AND client_id = ? AND status != 'cancelled'"
+    ).get(instanceId, clientId);
+    if (dup) throw new BookingError('already_booked', 'Client already has a booking for this class');
+
+    const creditsNeeded = inst.credits_required ?? 1;
+    let resolution;
+    if (options.paidWith && options.paidWith !== 'auto') {
+      resolution = { paidWith: options.paidWith };
+    } else {
+      resolution = resolvePayment(db, clientId, inst, { now: nowIso });
+      if (resolution.paidWith === 'drop_in') {
+        resolution.paidWith = options.dropInMode === 'online' ? 'drop_in_online' : 'drop_in_manual';
+      }
+    }
+
+    const full = bookedCount(db, instanceId) >= inst.capacity;
+    const status = full ? 'waitlist' : 'booked';
+    // Credits are deducted at booking time for confirmed spots only; waitlisted
+    // bookings deduct when promoted (spec is silent — pragmatic choice).
+    if (status === 'booked') deduct(db, resolution, creditsNeeded);
+
+    const info = db.prepare(
+      `INSERT INTO bookings (class_instance_id, client_id, status, paid_with, pass_id, membership_id, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`
+    ).run(instanceId, clientId, status, resolution.paidWith,
+      status === 'booked' ? resolution.passId ?? null : null,
+      status === 'booked' ? resolution.membershipId ?? null : null,
+      nowIso);
+    const booking = db.prepare('SELECT * FROM bookings WHERE id = ?').get(info.lastInsertRowid);
+    return { booking, waitlisted: full, instance: inst };
+  })();
+}
+
+/** Promote the first FIFO waitlisted booking of an instance. Internal + reused by cancelBooking. */
+function promoteNext(db, inst, nowIso) {
+  const next = db.prepare(
+    "SELECT * FROM bookings WHERE class_instance_id = ? AND status = 'waitlist' ORDER BY created_at, id LIMIT 1"
+  ).get(inst.id);
+  if (!next) return null;
+  const creditsNeeded = inst.credits_required ?? 1;
+  // Re-resolve payment at promotion time (their pass may have expired meanwhile).
+  let resolution = resolvePayment(db, next.client_id, inst, { now: nowIso });
+  if (resolution.paidWith === 'drop_in') resolution.paidWith = 'drop_in_manual';
+  deduct(db, resolution, creditsNeeded);
+  db.prepare(
+    'UPDATE bookings SET status = ?, paid_with = ?, pass_id = ?, membership_id = ? WHERE id = ?'
+  ).run('booked', resolution.paidWith, resolution.passId ?? null, resolution.membershipId ?? null, next.id);
+  return db.prepare('SELECT * FROM bookings WHERE id = ?').get(next.id);
+}
+
+/**
+ * Cancel a booking. Within the cancellation window → credit refunded; late →
+ * per policy (default forfeit). Auto-promotes the first waitlisted booking.
+ * Returns { booking, refunded, late, promoted } (promoted = booking row or null).
+ */
+export function cancelBooking(db, bookingId, options = {}) {
+  const nowIso = options.now || new Date().toISOString();
+  return db.transaction(() => {
+    const booking = db.prepare('SELECT * FROM bookings WHERE id = ?').get(bookingId);
+    if (!booking) throw new BookingError('not_found', 'Booking not found');
+    if (!['booked', 'waitlist'].includes(booking.status)) {
+      throw new BookingError('not_cancellable', `Cannot cancel a ${booking.status} booking`);
+    }
+    const inst = loadInstance(db, booking.class_instance_id);
+    const windowHours = Number(getSetting(db, 'cancellation_window_hours', '12'));
+    const policy = getSetting(db, 'late_cancel_policy', 'forfeit');
+    const hoursToStart = hoursBetween(nowIso, inst.starts_at);
+    const late = hoursToStart < windowHours;
+    const wasBooked = booking.status === 'booked';
+    const creditsNeeded = inst.credits_required ?? 1;
+
+    let refunded = false;
+    if (wasBooked && (!late || policy === 'refund' || options.forceRefund)) {
+      refund(db, booking, creditsNeeded);
+      refunded = booking.paid_with === 'pack' || booking.paid_with === 'membership';
+    }
+    db.prepare("UPDATE bookings SET status = 'cancelled', cancelled_at = ? WHERE id = ?")
+      .run(nowIso, bookingId);
+
+    // A freed confirmed spot promotes the first waitlisted booking.
+    let promoted = null;
+    if (wasBooked && bookedCount(db, inst.id) < inst.capacity) {
+      promoted = promoteNext(db, inst, nowIso);
+    }
+    return { booking: { ...booking, status: 'cancelled', cancelled_at: nowIso }, refunded, late, promoted, instance: inst };
+  })();
+}
+
+/** Staff roster actions. */
+export function markAttendance(db, bookingId, status) {
+  if (!['attended', 'no_show', 'booked'].includes(status)) {
+    throw new BookingError('bad_status', 'Invalid attendance status');
+  }
+  const r = db.prepare(
+    "UPDATE bookings SET status = ? WHERE id = ? AND status IN ('booked','attended','no_show')"
+  ).run(status, bookingId);
+  if (r.changes !== 1) throw new BookingError('not_found', 'Booking not found or not markable');
+}
+
+/**
+ * Cancel a whole class: refund credits of every confirmed booking (always,
+ * regardless of window — the studio cancelled), cancel all active bookings,
+ * mark the instance cancelled. Returns affected bookings for notification.
+ */
+export function cancelClass(db, instanceId, options = {}) {
+  const nowIso = options.now || new Date().toISOString();
+  return db.transaction(() => {
+    const inst = loadInstance(db, instanceId);
+    if (inst.status === 'cancelled') throw new BookingError('already_cancelled', 'Class already cancelled');
+    const creditsNeeded = inst.credits_required ?? 1;
+    const affected = db.prepare(
+      "SELECT * FROM bookings WHERE class_instance_id = ? AND status IN ('booked','waitlist')"
+    ).all(instanceId);
+    for (const b of affected) {
+      if (b.status === 'booked') refund(db, b, creditsNeeded);
+      db.prepare("UPDATE bookings SET status = 'cancelled', cancelled_at = ? WHERE id = ?")
+        .run(nowIso, b.id);
+    }
+    db.prepare("UPDATE class_instances SET status = 'cancelled' WHERE id = ?").run(instanceId);
+    return { instance: inst, affected };
+  })();
+}

package/src/services/importer.js

@@ -0,0 +1,201 @@
+// Mindbody CSV importer core. Used by scripts/import-mindbody.mjs and the
+// admin import page. Idempotent by client email: re-running updates, never
+// duplicates. No external CSV dependency — small RFC-4180-ish parser below.
+
+/** Parse CSV text into an array of row objects keyed by header. Handles quoted
+ *  fields, embedded commas/newlines, and doubled quotes. */
+export function parseCsv(text) {
+  const rows = [];
+  let field = '', row = [], inQuotes = false;
+  const src = String(text).replace(/^/, ''); // strip BOM
+  for (let i = 0; i < src.length; i++) {
+    const ch = src[i];
+    if (inQuotes) {
+      if (ch === '"') {
+        if (src[i + 1] === '"') { field += '"'; i++; } else inQuotes = false;
+      } else field += ch;
+    } else if (ch === '"') {
+      inQuotes = true;
+    } else if (ch === ',') {
+      row.push(field); field = '';
+    } else if (ch === '\n' || ch === '\r') {
+      if (ch === '\r' && src[i + 1] === '\n') i++;
+      row.push(field); field = '';
+      if (row.length > 1 || row[0] !== '') rows.push(row);
+      row = [];
+    } else field += ch;
+  }
+  if (field !== '' || row.length) { row.push(field); if (row.length > 1 || row[0] !== '') rows.push(row); }
+  if (!rows.length) return [];
+  const headers = rows[0].map((h) => h.trim());
+  return rows.slice(1).map((r) => {
+    const obj = {};
+    headers.forEach((h, idx) => { obj[h] = (r[idx] ?? '').trim(); });
+    return obj;
+  });
+}
+
+// Default column mappings for standard Mindbody exports. Override via a JSON
+// mapping file ({ clients: {...}, passes: {...} }).
+export const DEFAULT_MAPPING = {
+  clients: {
+    firstName: ['First Name', 'FirstName', 'First'],
+    lastName: ['Last Name', 'LastName', 'Last'],
+    email: ['Email', 'Email Address', 'E-mail'],
+    phone: ['Phone', 'Mobile Phone', 'Cell Phone', 'Home Phone'],
+    notes: ['Notes'],
+    waiverSigned: ['Liability Waiver', 'Waiver Signed', 'Liability Release'],
+  },
+  passes: {
+    email: ['Email', 'Client Email', 'Email Address'],
+    clientName: ['Client', 'Client Name', 'Name'],
+    passName: ['Pricing Option', 'Service Name', 'Pricing Option Name'],
+    remaining: ['Remaining', 'Sessions Remaining', 'Count Remaining', 'Remaining Sessions'],
+    total: ['Total', 'Session Count', 'Total Sessions'],
+    expiration: ['Expiration', 'Expiration Date', 'Exp Date', 'Expires'],
+    pricePaid: ['Price Paid', 'Amount Paid', 'Price'],
+  },
+};
+
+function pick(row, candidates) {
+  for (const c of candidates) {
+    if (c in row && row[c] !== '') return row[c];
+  }
+  // case-insensitive fallback
+  const lower = Object.fromEntries(Object.entries(row).map(([k, v]) => [k.toLowerCase(), v]));
+  for (const c of candidates) {
+    const v = lower[c.toLowerCase()];
+    if (v !== undefined && v !== '') return v;
+  }
+  return '';
+}
+
+function normalizeDate(s) {
+  if (!s) return null;
+  const t = s.trim();
+  let m = t.match(/^(\d{4})-(\d{2})-(\d{2})/); // ISO
+  if (m) return `${m[1]}-${m[2]}-${m[3]}`;
+  m = t.match(/^(\d{1,2})\/(\d{1,2})\/(\d{4})/); // Mindbody M/D/YYYY
+  if (m) return `${m[3]}-${m[1].padStart(2, '0')}-${m[2].padStart(2, '0')}`;
+  return null;
+}
+
+function parseMoneyCents(s) {
+  if (!s) return 0;
+  const n = Number(String(s).replace(/[^0-9.\-]/g, ''));
+  return Number.isFinite(n) ? Math.round(n * 100) : 0;
+}
+
+/**
+ * Import Mindbody clients CSV. Returns { created, updated, skipped, rows:[...] }.
+ * dryRun: report what would happen without writing.
+ */
+export function importClients(db, csvText, { mapping = DEFAULT_MAPPING.clients, dryRun = false } = {}) {
+  const rows = parseCsv(csvText);
+  const result = { created: 0, updated: 0, skipped: 0, rows: [] };
+  const work = db.transaction(() => {
+    for (const row of rows) {
+      const email = pick(row, mapping.email).toLowerCase();
+      if (!email || !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) {
+        result.skipped++;
+        result.rows.push({ action: 'skip', reason: 'missing/invalid email', row });
+        continue;
+      }
+      const first = pick(row, mapping.firstName);
+      const last = pick(row, mapping.lastName);
+      const name = `${first} ${last}`.trim() || email.split('@')[0];
+      const phone = pick(row, mapping.phone);
+      const notes = pick(row, mapping.notes);
+      const waiverRaw = pick(row, mapping.waiverSigned).toLowerCase();
+      const waiverSigned = ['yes', 'y', 'true', 'signed', '1'].includes(waiverRaw);
+
+      const existing = db.prepare('SELECT * FROM clients WHERE email = ?').get(email);
+      if (existing) {
+        if (!dryRun) {
+          db.prepare(
+            `UPDATE clients SET name = ?, phone = CASE WHEN ? != '' THEN ? ELSE phone END,
+             notes = CASE WHEN ? != '' THEN ? ELSE notes END,
+             waiver_signed_at = COALESCE(waiver_signed_at, ?)
+             WHERE id = ?`
+          ).run(name, phone, phone, notes, notes,
+            waiverSigned ? new Date().toISOString() : null, existing.id);
+        }
+        result.updated++;
+        result.rows.push({ action: 'update', email, name });
+      } else {
+        if (!dryRun) {
+          db.prepare(
+            "INSERT INTO clients (name, email, phone, notes, waiver_signed_at, source) VALUES (?, ?, ?, ?, ?, 'import')"
+          ).run(name, email, phone, notes, waiverSigned ? new Date().toISOString() : null);
+        }
+        result.created++;
+        result.rows.push({ action: 'create', email, name });
+      }
+    }
+  });
+  work();
+  return result;
+}
+
+/**
+ * Import Mindbody pricing-option/pass CSV. Clients must exist (or are created
+ * as bare records from the email). Idempotent: a pass identified by
+ * (client, name, expiration) is updated in place, never duplicated.
+ */
+export function importPasses(db, csvText, { mapping = DEFAULT_MAPPING.passes, dryRun = false } = {}) {
+  const rows = parseCsv(csvText);
+  const result = { created: 0, updated: 0, skipped: 0, clientsCreated: 0, rows: [] };
+  const work = db.transaction(() => {
+    for (const row of rows) {
+      const email = pick(row, mapping.email).toLowerCase();
+      if (!email || !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) {
+        result.skipped++;
+        result.rows.push({ action: 'skip', reason: 'missing/invalid email', row });
+        continue;
+      }
+      const passName = pick(row, mapping.passName) || 'Imported pass';
+      const remaining = Math.max(0, parseInt(pick(row, mapping.remaining), 10) || 0);
+      const total = Math.max(remaining, parseInt(pick(row, mapping.total), 10) || remaining);
+      const expiresOn = normalizeDate(pick(row, mapping.expiration));
+      const priceCents = parseMoneyCents(pick(row, mapping.pricePaid));
+
+      let client = db.prepare('SELECT * FROM clients WHERE email = ?').get(email);
+      if (!client) {
+        const name = pick(row, mapping.clientName) || email.split('@')[0];
+        if (!dryRun) {
+          const info = db.prepare(
+            "INSERT INTO clients (name, email, source) VALUES (?, ?, 'import')"
+          ).run(name, email);
+          client = { id: info.lastInsertRowid };
+        } else {
+          client = { id: null };
+        }
+        result.clientsCreated++;
+      }
+
+      const existing = client.id === null ? null : db.prepare(
+        `SELECT * FROM passes WHERE client_id = ? AND name = ? AND source = 'import'
+         AND (expires_on IS ? OR expires_on = ?)`
+      ).get(client.id, passName, expiresOn, expiresOn);
+      if (existing) {
+        if (!dryRun) {
+          db.prepare('UPDATE passes SET credits_remaining = ?, credits_total = ? WHERE id = ?')
+            .run(remaining, total, existing.id);
+        }
+        result.updated++;
+        result.rows.push({ action: 'update', email, passName, remaining });
+      } else {
+        if (!dryRun) {
+          db.prepare(
+            `INSERT INTO passes (client_id, name, credits_total, credits_remaining, expires_on, price_paid_cents, source)
+             VALUES (?, ?, ?, ?, ?, ?, 'import')`
+          ).run(client.id, passName, total, remaining, expiresOn, priceCents);
+        }
+        result.created++;
+        result.rows.push({ action: 'create', email, passName, remaining });
+      }
+    }
+  });
+  work();
+  return result;
+}

package/src/services/mailer.js

@@ -0,0 +1,92 @@
+// Email delivery. SMTP via nodemailer when configured; otherwise every message
+// is written to data/outbox/*.eml so flows stay fully testable offline.
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function createMailer({ env = process.env, outboxDir } = {}) {
+  const smtpConfigured = Boolean(env.SMTP_HOST);
+  const outbox = outboxDir || path.join(process.cwd(), 'data', 'outbox');
+  let transportPromise = null;
+
+  async function getTransport() {
+    if (!transportPromise) {
+      const nodemailer = (await import('nodemailer')).default;
+      transportPromise = Promise.resolve(nodemailer.createTransport({
+        host: env.SMTP_HOST,
+        port: Number(env.SMTP_PORT || 587),
+        secure: Number(env.SMTP_PORT) === 465,
+        auth: env.SMTP_USER ? { user: env.SMTP_USER, pass: env.SMTP_PASS } : undefined,
+      }));
+    }
+    return transportPromise;
+  }
+
+  return {
+    smtpConfigured,
+    /** Fire-and-forget safe: never throws, logs failures. */
+    async send({ to, subject, text }) {
+      const from = env.SMTP_FROM || 'studio-os@localhost';
+      try {
+        if (smtpConfigured) {
+          const t = await getTransport();
+          await t.sendMail({ from, to, subject, text });
+        } else {
+          fs.mkdirSync(outbox, { recursive: true });
+          const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+          const safeTo = String(to).replace(/[^a-z0-9@._-]/gi, '_');
+          const eml = [
+            `From: ${from}`, `To: ${to}`, `Subject: ${subject}`,
+            `Date: ${new Date().toUTCString()}`, 'MIME-Version: 1.0',
+            'Content-Type: text/plain; charset=utf-8', '', text,
+          ].join('\r\n');
+          fs.writeFileSync(path.join(outbox, `${stamp}_${safeTo}.eml`), eml);
+        }
+        return true;
+      } catch (err) {
+        console.error('[mailer] send failed:', err.message);
+        return false;
+      }
+    },
+  };
+}
+
+// --- templates (plain text, keep it simple and readable) -------------------
+
+export const emails = {
+  bookingConfirmation({ studio, clientName, className, when, paidWith, magicUrl }) {
+    return {
+      subject: `Booked: ${className} — ${when}`,
+      text: `Hi ${clientName},\n\nYou're booked for ${className} on ${when} at ${studio}.\nPayment: ${paidWith}.\n\nManage your bookings: ${magicUrl}\n\nSee you there!\n${studio}`,
+    };
+  },
+  waitlisted({ studio, clientName, className, when, magicUrl }) {
+    return {
+      subject: `Waitlisted: ${className} — ${when}`,
+      text: `Hi ${clientName},\n\nThe ${className} class on ${when} is full — you're on the waitlist. We'll email you if a spot opens.\n\nManage your bookings: ${magicUrl}\n\n${studio}`,
+    };
+  },
+  cancellation({ studio, clientName, className, when, refunded }) {
+    return {
+      subject: `Cancelled: ${className} — ${when}`,
+      text: `Hi ${clientName},\n\nYour booking for ${className} on ${when} was cancelled.${refunded ? ' Your credit has been returned.' : ''}\n\n${studio}`,
+    };
+  },
+  waitlistPromotion({ studio, clientName, className, when, magicUrl }) {
+    return {
+      subject: `You're in! ${className} — ${when}`,
+      text: `Hi ${clientName},\n\nA spot opened up: you're now booked for ${className} on ${when}.\n\nCan't make it? Cancel here: ${magicUrl}\n\n${studio}`,
+    };
+  },
+  classCancelled({ studio, clientName, className, when }) {
+    return {
+      subject: `Class cancelled: ${className} — ${when}`,
+      text: `Hi ${clientName},\n\nSorry — ${className} on ${when} has been cancelled by the studio. Any credit used has been returned.\n\n${studio}`,
+    };
+  },
+  magicLink({ studio, clientName, magicUrl }) {
+    return {
+      subject: `${studio}: your booking management link`,
+      text: `Hi ${clientName},\n\nUse this link to view and manage your bookings:\n${magicUrl}\n\nThe link is valid for 7 days.\n\n${studio}`,
+    };
+  },
+};

package/src/services/schedule.js

@@ -0,0 +1,71 @@
+// Rolling instance generator: materializes schedule_rules into class_instances
+// over a horizon (default 8 weeks). Idempotent — keyed on (rule_id, starts_at).
+
+import { getSetting } from '../db/index.js';
+import { zonedToUtc, localDateStr, addDays, weekdayOf } from '../lib/time.js';
+
+/**
+ * Generate class_instances for all active rules from today through
+ * today + horizonWeeks*7 (studio-local days). Never touches existing rows.
+ * Returns number of instances created.
+ */
+export function generateInstances(db, { now } = {}) {
+  const tz = getSetting(db, 'timezone', 'Asia/Hong_Kong');
+  const horizonWeeks = Number(getSetting(db, 'horizon_weeks', '8'));
+  const today = localDateStr(tz, now || new Date());
+  const rules = db.prepare(
+    `SELECT sr.*, ct.capacity AS type_capacity, ct.duration_min
+     FROM schedule_rules sr JOIN class_types ct ON ct.id = sr.class_type_id
+     WHERE sr.active = 1 AND ct.active = 1`
+  ).all();
+  if (!rules.length) return 0;
+
+  const insert = db.prepare(
+    `INSERT OR IGNORE INTO class_instances
+     (class_type_id, instructor_id, rule_id, starts_at, duration_min, capacity, status)
+     VALUES (?, ?, ?, ?, ?, ?, 'scheduled')`
+  );
+  let created = 0;
+  db.transaction(() => {
+    for (const rule of rules) {
+      const [hh, mm] = rule.start_time.split(':').map(Number);
+      for (let i = 0; i < horizonWeeks * 7; i++) {
+        const day = addDays(today, i);
+        if (weekdayOf(day) !== rule.weekday) continue;
+        if (rule.active_from && day < rule.active_from) continue;
+        if (rule.active_until && day > rule.active_until) continue;
+        const [y, m, d] = day.split('-').map(Number);
+        const startsAt = zonedToUtc(tz, y, m, d, hh, mm).toISOString().replace(/\.\d{3}Z$/, 'Z');
+        const r = insert.run(
+          rule.class_type_id, rule.instructor_id, rule.id, startsAt,
+          rule.duration_min, rule.capacity_override ?? rule.type_capacity
+        );
+        created += r.changes;
+      }
+    }
+  })();
+  return created;
+}
+
+/** Upcoming scheduled instances joined with type + instructor, for listings. */
+export function upcomingInstances(db, { days = 14, from, classTypeId, instructorId, includeCancelled = false } = {}) {
+  const fromIso = from || new Date().toISOString();
+  const toIso = new Date(new Date(fromIso).getTime() + days * 86400000).toISOString();
+  let sql = `
+    SELECT ci.*, ct.name AS class_name, ct.color, ct.credits_required, ct.drop_in_price_cents,
+           ct.description AS class_description, i.name AS instructor_name,
+           (SELECT COUNT(*) FROM bookings b WHERE b.class_instance_id = ci.id
+              AND b.status IN ('booked','attended','no_show')) AS booked_count,
+           (SELECT COUNT(*) FROM bookings b WHERE b.class_instance_id = ci.id
+              AND b.status = 'waitlist') AS waitlist_count
+    FROM class_instances ci
+    JOIN class_types ct ON ct.id = ci.class_type_id
+    LEFT JOIN instructors i ON i.id = ci.instructor_id
+    WHERE ci.starts_at >= ? AND ci.starts_at < ?`;
+  const params = [fromIso, toIso];
+  if (!includeCancelled) sql += " AND ci.status = 'scheduled'";
+  if (classTypeId) { sql += ' AND ci.class_type_id = ?'; params.push(classTypeId); }
+  if (instructorId) { sql += ' AND ci.instructor_id = ?'; params.push(instructorId); }
+  sql += ' ORDER BY ci.starts_at';
+  return db.prepare(sql).all(...params);
+}