includio-cms 0.36.8 → 0.37.0

package/dist/booking/server/emailTemplateRegistry.js

@@ -0,0 +1,125 @@
+/**
+ * Booking email template registry — file-based Handlebars with project override
+ * → package default → fallback-lang resolution. Self-contained (no shop / no
+ * CMS-singleton auto-fetch) to keep booking independent of the shop module.
+ *
+ * @internal — exported for testing; not part of the public API.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Handlebars from 'handlebars';
+const PACKAGE_TEMPLATES_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'templates');
+const cache = new Map();
+let helpersRegistered = false;
+/** Long pl-PL (or given locale) date; '' for null/invalid. @internal */
+export function formatBookingDate(value, locale = 'pl-PL') {
+    const d = value instanceof Date
+        ? value
+        : typeof value === 'string' || typeof value === 'number'
+            ? new Date(value)
+            : null;
+    if (!d || Number.isNaN(d.getTime()))
+        return '';
+    return new Intl.DateTimeFormat(locale, { dateStyle: 'long', timeZone: 'Europe/Warsaw' }).format(d);
+}
+/** Whole days from `now` to `value`, floored at 0; '' for invalid. @internal */
+export function daysUntilDate(value, now) {
+    const parse = (v) => v instanceof Date ? v : typeof v === 'string' || typeof v === 'number' ? new Date(v) : null;
+    const d = parse(value);
+    const n = parse(now);
+    if (!d || Number.isNaN(d.getTime()) || !n || Number.isNaN(n.getTime()))
+        return '';
+    return String(Math.max(0, Math.ceil((d.getTime() - n.getTime()) / 86_400_000)));
+}
+function registerHelpers() {
+    if (helpersRegistered)
+        return;
+    Handlebars.registerHelper('currency', (value, currency) => {
+        const num = typeof value === 'number' ? value : Number(value);
+        const cur = typeof currency === 'string' ? currency : 'PLN';
+        if (!Number.isFinite(num))
+            return '';
+        // Amounts are minor units (grosze) → convert to major for display.
+        return new Intl.NumberFormat('pl-PL', { style: 'currency', currency: cur }).format(num / 100);
+    });
+    Handlebars.registerHelper('date', (value, locale) => formatBookingDate(value, typeof locale === 'string' ? locale : 'pl-PL'));
+    Handlebars.registerHelper('daysUntil', (value, now) => daysUntilDate(value, now));
+    helpersRegistered = true;
+}
+function resolveTemplateSource(name, lang, fallbackLang, projectDir) {
+    const candidates = [
+        path.join(projectDir, `${name}.${lang}.html`),
+        path.join(projectDir, `${name}.html`),
+        path.join(PACKAGE_TEMPLATES_DIR, `${name}.${lang}.html`),
+        path.join(PACKAGE_TEMPLATES_DIR, `${name}.${fallbackLang}.html`)
+    ];
+    for (const filePath of candidates) {
+        try {
+            return fs.readFileSync(filePath, 'utf8');
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    throw new Error(`[booking] No email template for "${name}" (lang=${lang}, fallback=${fallbackLang}). ` +
+        `Looked in "${projectDir}" and package defaults.`);
+}
+const partialSourceCache = new Map();
+function readPartialSource(projectDir, name, lang, fallbackLang) {
+    const key = `${projectDir}|${name}|${lang}|${fallbackLang}`;
+    if (process.env.NODE_ENV === 'production' && partialSourceCache.has(key)) {
+        return partialSourceCache.get(key);
+    }
+    const candidates = [
+        path.join(projectDir, '_partials', `${name}.${lang}.html`),
+        path.join(projectDir, '_partials', `${name}.${fallbackLang}.html`),
+        path.join(PACKAGE_TEMPLATES_DIR, '_partials', `${name}.${lang}.html`),
+        path.join(PACKAGE_TEMPLATES_DIR, '_partials', `${name}.${fallbackLang}.html`)
+    ];
+    for (const filePath of candidates) {
+        try {
+            const source = fs.readFileSync(filePath, 'utf8');
+            partialSourceCache.set(key, source);
+            return source;
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    partialSourceCache.set(key, null);
+    return null;
+}
+/**
+ * Register `header`/`footer` partials for a render. Re-registers on every call
+ * (cheap — source is cached in prod) so booking's partials always win over the
+ * shop module's identically-named partials right before a booking render.
+ * @internal
+ */
+export function registerBookingPartials(projectDir, lang, fallbackLang) {
+    for (const name of ['header', 'footer']) {
+        const source = readPartialSource(projectDir, name, lang, fallbackLang);
+        if (source != null)
+            Handlebars.registerPartial(name, source);
+    }
+}
+/**
+ * Render a booking email template by name + language. Project overrides live in
+ * `<projectDir>/<name>.<lang>.html` (default `src/emails/booking`); package
+ * defaults ship under `booking/templates`.
+ */
+export function renderEmailTemplate(name, lang, context, opts = {}) {
+    registerHelpers();
+    const fallbackLang = opts.fallbackLang ?? 'pl';
+    const projectDir = opts.projectDir ?? path.join(process.cwd(), 'src/emails/booking');
+    registerBookingPartials(projectDir, lang, fallbackLang);
+    const key = `${projectDir}|${name}|${lang}|${fallbackLang}`;
+    let compiled = cache.get(key);
+    if (!compiled) {
+        const source = resolveTemplateSource(name, lang, fallbackLang, projectDir);
+        compiled = Handlebars.compile(source, { noEscape: false });
+        if (process.env.NODE_ENV === 'production')
+            cache.set(key, compiled);
+    }
+    return compiled(context);
+}

package/dist/booking/server/http/create-handler.d.ts

@@ -0,0 +1,5 @@
+import { type RequestHandler } from '@sveltejs/kit';
+/** Public self-serve booking creation. Mount at `POST /api/booking`. */
+export declare function createBookingHandler(): {
+    POST: RequestHandler;
+};

package/dist/booking/server/http/create-handler.js

@@ -0,0 +1,68 @@
+import { json } from '@sveltejs/kit';
+import { getCMS } from '../../../core/cms.js';
+import { checkRateLimit, clientKey } from '../../../server/security/rate-limit-handler.js';
+import { createBooking } from '../bookings.js';
+import { createDepositPayment } from '../payments.js';
+function bookingEnabled() {
+    try {
+        return getCMS().hasModule('booking');
+    }
+    catch {
+        return false;
+    }
+}
+/** Public self-serve booking creation. Mount at `POST /api/booking`. */
+export function createBookingHandler() {
+    return {
+        POST: async ({ request }) => {
+            if (!bookingEnabled())
+                return json({ error: 'Booking not enabled' }, { status: 404 });
+            const rl = checkRateLimit(clientKey(request, 'booking-create'), { limit: 5, windowSec: 60 });
+            if (!rl.allowed)
+                return json({ error: 'Rate limit exceeded' }, { status: 429 });
+            const body = (await request.json().catch(() => null));
+            if (!body || !Array.isArray(body.items) || body.items.length === 0) {
+                return json({ error: 'items required' }, { status: 400 });
+            }
+            try {
+                const persons = Array.isArray(body.persons)
+                    ? body.persons.map((p) => ({
+                        ref: String(p.ref),
+                        identity: p.identity && typeof p.identity === 'object' ? p.identity : {}
+                    }))
+                    : [];
+                const items = body.items.map((it) => ({
+                    tripRef: String(it.tripRef),
+                    unitPrice: Number(it.unitPrice) || 0,
+                    departureDate: it.departureDate ? new Date(it.departureDate) : null,
+                    assignments: Array.isArray(it.assignments)
+                        ? it.assignments.map((a) => ({
+                            personRef: String(a.personRef),
+                            data: a.data && typeof a.data === 'object' ? a.data : undefined
+                        }))
+                        : []
+                }));
+                const { booking, accessToken } = await createBooking({
+                    customer: body.customer ?? {},
+                    persons,
+                    items,
+                    language: body.language
+                });
+                const payment = await createDepositPayment(booking.id);
+                return json({
+                    bookingId: booking.id,
+                    number: booking.number,
+                    accessToken,
+                    status: booking.status,
+                    totals: booking.totals,
+                    paymentStatus: payment.status,
+                    requiresPaymentRedirect: payment.status === 'redirect',
+                    redirectUrl: payment.redirectUrl
+                });
+            }
+            catch (err) {
+                return json({ error: err instanceof Error ? err.message : 'Booking failed' }, { status: 400 });
+            }
+        }
+    };
+}

package/dist/booking/server/http/index.d.ts

@@ -0,0 +1,4 @@
+export { createBookingHandler } from './create-handler.js';
+export { createWebhookHandler } from './webhook-handler.js';
+export { createPortalHandler } from './portal-handler.js';
+export { createMaintenanceHandler } from './maintenance-handler.js';

package/dist/booking/server/http/index.js

@@ -0,0 +1,4 @@
+export { createBookingHandler } from './create-handler.js';
+export { createWebhookHandler } from './webhook-handler.js';
+export { createPortalHandler } from './portal-handler.js';
+export { createMaintenanceHandler } from './maintenance-handler.js';

package/dist/booking/server/http/maintenance-handler.d.ts

@@ -0,0 +1,9 @@
+import { type RequestHandler } from '@sveltejs/kit';
+/**
+ * Secured external trigger for booking maintenance — the swap-in for the
+ * in-process loop (e.g. a system cron hitting this endpoint). Requires
+ * `Authorization: Bearer <maintenanceToken>`. Mount at `POST /api/booking/maintenance`.
+ */
+export declare function createMaintenanceHandler(): {
+    POST: RequestHandler;
+};

package/dist/booking/server/http/maintenance-handler.js

@@ -0,0 +1,36 @@
+import { json } from '@sveltejs/kit';
+import { requireBookingConfig } from '../db.js';
+import { processDueReminders, processDueExpirations } from '../maintenance.js';
+/** Constant-time string compare (avoids leaking the token via timing). */
+function safeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let r = 0;
+    for (let i = 0; i < a.length; i++)
+        r |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return r === 0;
+}
+/**
+ * Secured external trigger for booking maintenance — the swap-in for the
+ * in-process loop (e.g. a system cron hitting this endpoint). Requires
+ * `Authorization: Bearer <maintenanceToken>`. Mount at `POST /api/booking/maintenance`.
+ */
+export function createMaintenanceHandler() {
+    return {
+        POST: async ({ request }) => {
+            const config = requireBookingConfig();
+            if (!config.maintenanceToken) {
+                return json({ error: 'Maintenance trigger disabled' }, { status: 404 });
+            }
+            const auth = request.headers.get('authorization') ?? '';
+            const token = auth.startsWith('Bearer ') ? auth.slice(7) : '';
+            if (!safeEqual(token, config.maintenanceToken)) {
+                return json({ error: 'Unauthorized' }, { status: 401 });
+            }
+            const now = new Date();
+            const reminders = await processDueReminders(now);
+            const expirations = await processDueExpirations(now);
+            return json({ ok: true, reminders, ...expirations });
+        }
+    };
+}

package/dist/booking/server/http/portal-handler.d.ts

@@ -0,0 +1,13 @@
+import { type RequestHandler } from '@sveltejs/kit';
+/**
+ * Self-service portal. Mount at `GET|POST /api/booking/portal/[token]`.
+ * Drugi czynnik (D9): token w linku = 1. czynnik; numer telefonu = 2. GET i
+ * wszystkie akcje poza `verify-phone` wymagają ważnego podpisanego cookie sesji
+ * (`?action=verify-phone` ustawia je po dopasowaniu numeru). Bez skonfigurowanego
+ * `portalSecret` portal jest fail-closed.
+ * `POST ?action=edit|pay|participant` jak dotąd; below-paid/terminal → 409.
+ */
+export declare function createPortalHandler(): {
+    GET: RequestHandler;
+    POST: RequestHandler;
+};

package/dist/booking/server/http/portal-handler.js

@@ -0,0 +1,99 @@
+import { json } from '@sveltejs/kit';
+import { checkRateLimit, resetRateLimit, clientKey } from '../../../server/security/rate-limit-handler.js';
+import { portalView, portalEdit, portalPay, portalUpdateParticipant, verifyPhone, portalAddTrips } from '../portal.js';
+import { signSession, verifySession, portalCookieName } from '../portal-session.js';
+import { requireBookingConfig } from '../db.js';
+import { LedgerError } from '../../ledger.js';
+import { BookingEditError } from '../../recompute.js';
+import { BookingValidationError } from '../validation.js';
+const SESSION_TTL = 7200;
+/**
+ * Self-service portal. Mount at `GET|POST /api/booking/portal/[token]`.
+ * Drugi czynnik (D9): token w linku = 1. czynnik; numer telefonu = 2. GET i
+ * wszystkie akcje poza `verify-phone` wymagają ważnego podpisanego cookie sesji
+ * (`?action=verify-phone` ustawia je po dopasowaniu numeru). Bez skonfigurowanego
+ * `portalSecret` portal jest fail-closed.
+ * `POST ?action=edit|pay|participant` jak dotąd; below-paid/terminal → 409.
+ */
+export function createPortalHandler() {
+    const secret = () => requireBookingConfig().portalSecret;
+    const isVerified = (cookies, token) => {
+        const s = secret();
+        if (!s)
+            return false;
+        return verifySession(cookies.get(portalCookieName(token)) ?? '', token, Math.floor(Date.now() / 1000), s);
+    };
+    return {
+        GET: async ({ params, cookies }) => {
+            const token = params.token ?? '';
+            if (!isVerified(cookies, token)) {
+                return json({ error: 'Wymagana weryfikacja', code: 'PHONE_REQUIRED' }, { status: 401 });
+            }
+            const view = await portalView(token);
+            return view ? json(view) : json({ error: 'Not found' }, { status: 404 });
+        },
+        POST: async ({ params, request, url, cookies }) => {
+            const rl = checkRateLimit(clientKey(request, 'booking-portal'), { limit: 10, windowSec: 60 });
+            if (!rl.allowed)
+                return json({ error: 'Rate limit exceeded' }, { status: 429 });
+            const token = params.token ?? '';
+            const action = url.searchParams.get('action');
+            const body = (await request.json().catch(() => ({})));
+            if (action === 'verify-phone') {
+                const s = secret();
+                if (!s)
+                    return json({ error: 'Portal not configured' }, { status: 503 });
+                const lock = checkRateLimit(`portal-verify:${token}`, { limit: 5, windowSec: 600 });
+                if (!lock.allowed)
+                    return json({ error: 'Za dużo prób', code: 'LOCKED' }, { status: 429 });
+                const booking = await verifyPhone(token, String(body.phone ?? ''));
+                if (!booking)
+                    return json({ error: 'Numer nie pasuje', code: 'PHONE_MISMATCH' }, { status: 401 });
+                resetRateLimit(`portal-verify:${token}`);
+                cookies.set(portalCookieName(token), signSession(token, Math.floor(Date.now() / 1000), SESSION_TTL, s), {
+                    httpOnly: true,
+                    sameSite: 'lax',
+                    secure: url.protocol === 'https:',
+                    path: '/api/booking/portal',
+                    maxAge: SESSION_TTL
+                });
+                const view = await portalView(token);
+                return view ? json(view) : json({ error: 'Not found' }, { status: 404 });
+            }
+            if (!isVerified(cookies, token)) {
+                return json({ error: 'Wymagana weryfikacja', code: 'PHONE_REQUIRED' }, { status: 401 });
+            }
+            try {
+                if (action === 'pay') {
+                    const out = await portalPay(token, Number(body.amount) || 0);
+                    return out ? json(out) : json({ error: 'Not found' }, { status: 404 });
+                }
+                if (action === 'edit') {
+                    const out = await portalEdit(token, body);
+                    return out ? json(out) : json({ error: 'Not found' }, { status: 404 });
+                }
+                if (action === 'participant') {
+                    const out = await portalUpdateParticipant(token, String(body.participantId ?? ''), (body.data ?? {}));
+                    return out ? json(out) : json({ error: 'Not found' }, { status: 404 });
+                }
+                if (action === 'add-trips') {
+                    const additions = Array.isArray(body.additions)
+                        ? body.additions
+                        : [];
+                    const out = await portalAddTrips(token, additions);
+                    return out ? json(out) : json({ error: 'Not found' }, { status: 404 });
+                }
+                return json({ error: 'Unknown action' }, { status: 400 });
+            }
+            catch (err) {
+                if (err instanceof LedgerError || err instanceof BookingEditError) {
+                    return json({ error: err.message, code: 'CONTACT_STAFF' }, { status: 409 });
+                }
+                if (err instanceof BookingValidationError) {
+                    return json({ error: err.message, code: err.code }, { status: 400 });
+                }
+                return json({ error: err instanceof Error ? err.message : 'Edit failed' }, { status: 400 });
+            }
+        }
+    };
+}

package/dist/booking/server/http/webhook-handler.d.ts

@@ -0,0 +1,9 @@
+import { type RequestHandler } from '@sveltejs/kit';
+/**
+ * Payment-provider webhook. Mount at `POST /api/booking/webhook/[provider]`.
+ * Delegates parsing to the matching adapter's `handleWebhook`, applies the event
+ * idempotently, then sends the right confirmation email on a settled payment.
+ */
+export declare function createWebhookHandler(): {
+    POST: RequestHandler;
+};

package/dist/booking/server/http/webhook-handler.js

@@ -0,0 +1,39 @@
+import { json } from '@sveltejs/kit';
+import { getCMS } from '../../../core/cms.js';
+import { requireBookingConfig } from '../db.js';
+import { applyWebhookPayment } from '../payments.js';
+import { sendBookingEmail } from '../email.js';
+/**
+ * Payment-provider webhook. Mount at `POST /api/booking/webhook/[provider]`.
+ * Delegates parsing to the matching adapter's `handleWebhook`, applies the event
+ * idempotently, then sends the right confirmation email on a settled payment.
+ */
+export function createWebhookHandler() {
+    return {
+        POST: async ({ request, params }) => {
+            try {
+                getCMS();
+            }
+            catch {
+                return json({ error: 'not ready' }, { status: 503 });
+            }
+            const config = requireBookingConfig();
+            const adapter = config.payment.find((a) => a.id === params.provider);
+            if (!adapter?.handleWebhook)
+                return json({ error: 'Unknown provider' }, { status: 404 });
+            let event;
+            try {
+                event = await adapter.handleWebhook(request);
+            }
+            catch (err) {
+                return json({ error: err instanceof Error ? err.message : 'bad webhook' }, { status: 400 });
+            }
+            const { applied, bookingId, kind } = await applyWebhookPayment(event);
+            if (applied && bookingId) {
+                const emailKind = kind === 'deposit' ? 'deposit-paid' : 'payment-received';
+                await sendBookingEmail(bookingId, emailKind).catch((e) => console.error('[booking] email failed', e));
+            }
+            return json({ ok: true });
+        }
+    };
+}

package/dist/booking/server/index.d.ts

@@ -0,0 +1,12 @@
+export * from './db.js';
+export * from './bookings.js';
+export * from './payments.js';
+export * from './adjustments.js';
+export * from './refunds.js';
+export * from './portal.js';
+export * from './reminders.js';
+export * from './maintenance.js';
+export * from './validation.js';
+export * from './catalog.js';
+export * from './email.js';
+export * from './http/index.js';

package/dist/booking/server/index.js

@@ -0,0 +1,14 @@
+// Node-only server barrel for the booking module → `includio-cms/booking/server`.
+// Keeps server services + HTTP handlers out of any client bundle.
+export * from './db.js';
+export * from './bookings.js';
+export * from './payments.js';
+export * from './adjustments.js';
+export * from './refunds.js';
+export * from './portal.js';
+export * from './reminders.js';
+export * from './maintenance.js';
+export * from './validation.js';
+export * from './catalog.js';
+export * from './email.js';
+export * from './http/index.js';

package/dist/booking/server/maintenance.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Send all due reminders (unsent, `scheduledFor <= now`) via the email adapter,
+ * stamping `sentAt` so they never re-send. Returns the count sent. Idempotent.
+ */
+export declare function processDueReminders(now?: Date): Promise<number>;
+/**
+ * Auto-cancel expired bookings: abandoned drafts (deposit hold lapsed) and
+ * balance-overdue bookings (deposit forfeited + cancellation email). Idempotent.
+ */
+export declare function processDueExpirations(now?: Date): Promise<{
+    abandoned: number;
+    forfeited: number;
+}>;
+/** Run one maintenance pass (reminders + expirations), guarded against overlap. */
+export declare function runBookingMaintenance(now?: Date): Promise<void>;
+/** Start the in-process loop (config-gated). Idempotent. Called from serverHooks.init. */
+export declare function startBookingMaintenance(): void;
+/**
+ * Conventional server-init entry run by `initCMS` via `serverHooks.initModule`
+ * (see the booking module in `../index.ts`). Server-only — kept out of the
+ * client-safe barrel so browser builds don't pull node:fs/url.
+ */
+export declare function serverInit(): void;
+export declare function stopBookingMaintenance(): void;
+export declare function getBookingMaintenanceStatus(): {
+    running: boolean;
+    lastRun: Date | null;
+};

package/dist/booking/server/maintenance.js

@@ -0,0 +1,134 @@
+import { eq, inArray, isNull } from 'drizzle-orm';
+import { getCMS } from '../../core/cms.js';
+import { getBookingDb } from './db.js';
+import { bookingsTable, bookingRemindersTable } from '../../db-postgres/schema/booking/index.js';
+import { selectDueReminders, decideExpirations } from '../expiry-logic.js';
+import { sendBookingEmail } from './email.js';
+/**
+ * Send all due reminders (unsent, `scheduledFor <= now`) via the email adapter,
+ * stamping `sentAt` so they never re-send. Returns the count sent. Idempotent.
+ */
+export async function processDueReminders(now = new Date()) {
+    const db = getBookingDb();
+    const rows = await db
+        .select()
+        .from(bookingRemindersTable)
+        .where(isNull(bookingRemindersTable.sentAt));
+    const dueIds = selectDueReminders(rows.map((r) => ({ id: r.id, scheduledFor: r.scheduledFor, sentAt: r.sentAt })), now);
+    let sent = 0;
+    for (const id of dueIds) {
+        const row = rows.find((r) => r.id === id);
+        if (!row)
+            continue;
+        try {
+            await sendBookingEmail(row.bookingId, row.templateKey);
+            await db
+                .update(bookingRemindersTable)
+                .set({ sentAt: now })
+                .where(eq(bookingRemindersTable.id, id));
+            sent++;
+        }
+        catch (e) {
+            console.error('[booking] reminder send failed', id, e);
+        }
+    }
+    return sent;
+}
+/**
+ * Auto-cancel expired bookings: abandoned drafts (deposit hold lapsed) and
+ * balance-overdue bookings (deposit forfeited + cancellation email). Idempotent.
+ */
+export async function processDueExpirations(now = new Date()) {
+    const db = getBookingDb();
+    const active = await db.select().from(bookingsTable).where(isNull(bookingsTable.deletedAt));
+    const { abandon, forfeit } = decideExpirations(active.map((b) => ({
+        id: b.id,
+        status: b.status,
+        holdExpiresAt: b.holdExpiresAt,
+        balanceDueAt: b.balanceDueAt,
+        totals: { balance: b.totals.balance }
+    })), now);
+    if (abandon.length > 0) {
+        await db
+            .update(bookingsTable)
+            .set({ status: 'cancelled', cancelReason: 'abandoned', updatedAt: now })
+            .where(inArray(bookingsTable.id, abandon));
+    }
+    for (const id of forfeit) {
+        await db
+            .update(bookingsTable)
+            .set({ status: 'cancelled', cancelReason: 'balance_overdue', updatedAt: now })
+            .where(eq(bookingsTable.id, id));
+        await sendBookingEmail(id, 'balance-overdue-cancelled').catch((e) => console.error('[booking] overdue email failed', e));
+    }
+    return { abandoned: abandon.length, forfeited: forfeit.length };
+}
+// --- In-process maintenance loop (no infra; secured endpoint is the swap-in) ---
+const STATE_KEY = Symbol.for('includio.booking.maintenance.state');
+function loopState() {
+    const g = globalThis;
+    if (!g[STATE_KEY])
+        g[STATE_KEY] = { timer: null, running: false, lastRun: null };
+    return g[STATE_KEY];
+}
+/** Run one maintenance pass (reminders + expirations), guarded against overlap. */
+export async function runBookingMaintenance(now = new Date()) {
+    const st = loopState();
+    if (st.running)
+        return;
+    st.running = true;
+    try {
+        await processDueReminders(now);
+        await processDueExpirations(now);
+        st.lastRun = now;
+    }
+    catch (e) {
+        console.warn('[booking-maintenance] error', e);
+    }
+    finally {
+        st.running = false;
+    }
+}
+/** Start the in-process loop (config-gated). Idempotent. Called from serverHooks.init. */
+export function startBookingMaintenance() {
+    const st = loopState();
+    if (st.timer)
+        return;
+    let cfg = null;
+    try {
+        cfg = getCMS().getModuleConfig('booking') ?? null;
+    }
+    catch {
+        return;
+    }
+    if (!cfg || cfg.maintenance.autoRun === false)
+        return;
+    const ms = cfg.maintenance.intervalMinutes * 60_000;
+    st.timer = setInterval(() => void runBookingMaintenance(), ms);
+    console.info(`[booking-maintenance] scheduled every ${cfg.maintenance.intervalMinutes}m`);
+}
+/**
+ * Conventional server-init entry run by `initCMS` via `serverHooks.initModule`
+ * (see the booking module in `../index.ts`). Server-only — kept out of the
+ * client-safe barrel so browser builds don't pull node:fs/url.
+ */
+export function serverInit() {
+    startBookingMaintenance();
+}
+export function stopBookingMaintenance() {
+    const st = loopState();
+    if (st.timer) {
+        clearInterval(st.timer);
+        st.timer = null;
+    }
+}
+export function getBookingMaintenanceStatus() {
+    const st = loopState();
+    return { running: st.running, lastRun: st.lastRun };
+}
+// Clean up the timer across Vite HMR so it doesn't accumulate.
+if (import.meta.hot) {
+    import.meta.hot.dispose(() => {
+        stopBookingMaintenance();
+    });
+}

package/dist/booking/server/participants.d.ts

@@ -0,0 +1,26 @@
+import { type FieldDef } from '../participant-fields/index.js';
+/** Who is editing — gates which fields a write may touch (see {@link canFill}). */
+export type EditScope = 'staff' | 'customer';
+/** Thrown when a write violates field types/min/max/option. Missing required is soft. */
+export declare class ParticipantValidationError extends Error {
+    errors: Array<{
+        key: string;
+        message: string;
+    }>;
+    constructor(errors: Array<{
+        key: string;
+        message: string;
+    }>);
+}
+/** Resolve the participant-field schema for a booking item's catalog entry. */
+export declare function resolveItemSchema(tripRef: string): Promise<FieldDef[]>;
+/**
+ * Merge a partial patch into a person's assignment, scoped to fields the
+ * `scope` audience may fill. Identity fields (role name/birthDate) are written
+ * once to the person row (shared across trips); the rest to this trip's
+ * assignment. Validates types/min/max/option (hard reject); missing required is
+ * allowed (soft status, surfaced in the UI elsewhere).
+ *
+ * @param assignmentId - `booking_item_persons.id` (the person-on-this-trip row).
+ */
+export declare function saveParticipantData(assignmentId: string, incoming: Record<string, unknown>, scope: EditScope): Promise<void>;