includio-cms 0.36.9 → 0.37.1

package/dist/booking/server/portal.js

@@ -0,0 +1,236 @@
+import { and, eq, inArray, isNull } from 'drizzle-orm';
+import { getBookingDb } from './db.js';
+import { bookingsTable, bookingItemsTable, bookingPersonsTable, bookingItemPersonsTable, bookingPaymentsTable } from '../../db-postgres/schema/booking/index.js';
+import { ledgerSummary } from '../ledger.js';
+import { editBooking } from './bookings.js';
+import { createInstallmentPayment } from './payments.js';
+import { resolveItemSchema, saveParticipantData } from './participants.js';
+import { canFill } from '../participant-fields/index.js';
+import { flattenAssignments } from '../participants-view.js';
+import { phonesMatch } from './portal-session.js';
+import { BookingValidationError } from './validation.js';
+/**
+ * Pure: shape a portal-safe DTO. Explicitly whitelists fields — `staffNotes`,
+ * `deletedBy`, and other internals never reach the customer.
+ */
+export function toPortalView(booking, items, participants, payments, schemaByItem = {}) {
+    return {
+        number: booking.number,
+        status: booking.status,
+        currency: booking.currency,
+        customer: booking.customer,
+        totals: booking.totals,
+        balanceDueAt: booking.balanceDueAt,
+        items: items.map((it) => ({ ...it, participantFields: schemaByItem[it.id] ?? [] })),
+        participants,
+        payments: payments.map((p) => ({
+            amount: p.amount,
+            status: p.status,
+            kind: p.kind,
+            paidAt: p.paidAt ?? null
+        })),
+        ledger: ledgerSummary(booking.totals.gross, payments)
+    };
+}
+/** Resolve a booking by its unguessable portal access token (active only). */
+export async function resolveByToken(token) {
+    const db = getBookingDb();
+    const [booking] = await db
+        .select()
+        .from(bookingsTable)
+        .where(and(eq(bookingsTable.accessToken, token), isNull(bookingsTable.deletedAt)));
+    return booking ?? null;
+}
+/** Drugi czynnik: zwraca booking gdy podany numer pasuje do `customer.phone`. */
+export async function verifyPhone(token, phone) {
+    const booking = await resolveByToken(token);
+    if (!booking)
+        return null;
+    const stored = booking.customer?.phone ?? '';
+    return phonesMatch(phone, stored) ? booking : null;
+}
+/**
+ * Non-PII booking status by portal token — for the reservation panel reachable by
+ * token alone (no 2FA). Deliberately WITHOUT customer / participants / phone /
+ * email: PII stays gated behind portal 2FA ({@link portalView}). Safe to render
+ * server-side on a token-addressed page and to poll. Trip titles are resolved
+ * client-side from `tripRef` (the module is catalog-title agnostic).
+ */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export async function bookingStatusByToken(token) {
+    // Guard: accessToken is a uuid column — a malformed token can't match any row,
+    // and querying it raw would throw (→ 500). Treat as not-found.
+    if (!UUID_RE.test(token))
+        return null;
+    const booking = await resolveByToken(token);
+    if (!booking)
+        return null;
+    const db = getBookingDb();
+    const items = await db
+        .select()
+        .from(bookingItemsTable)
+        .where(eq(bookingItemsTable.bookingId, booking.id));
+    const payments = await db
+        .select()
+        .from(bookingPaymentsTable)
+        .where(eq(bookingPaymentsTable.bookingId, booking.id));
+    const pendingDeposit = payments.find((p) => p.kind === 'deposit' && p.status === 'pending');
+    return {
+        number: booking.number,
+        status: booking.status,
+        currency: booking.currency,
+        totals: {
+            gross: booking.totals.gross,
+            paid: booking.totals.paid,
+            balance: booking.totals.balance
+        },
+        items: items.map((it) => ({
+            tripRef: it.tripRef,
+            departureDate: it.departureDate ? it.departureDate.toISOString().slice(0, 10) : null,
+            unitPrice: it.unitPriceSnapshot
+        })),
+        depositLink: pendingDeposit?.paymentLink ?? null
+    };
+}
+/** Load a booking's people + assignments, folded into the flat participant shape. */
+async function loadParticipants(db, bookingId, itemIds) {
+    const persons = await db
+        .select()
+        .from(bookingPersonsTable)
+        .where(eq(bookingPersonsTable.bookingId, bookingId));
+    const assignments = itemIds.length
+        ? await db
+            .select()
+            .from(bookingItemPersonsTable)
+            .where(inArray(bookingItemPersonsTable.itemId, itemIds))
+        : [];
+    return flattenAssignments(persons, assignments);
+}
+/** Portal view: booking + items + participants + ledger (no staff data). */
+export async function portalView(token) {
+    const booking = await resolveByToken(token);
+    if (!booking)
+        return null;
+    const db = getBookingDb();
+    const items = await db
+        .select()
+        .from(bookingItemsTable)
+        .where(eq(bookingItemsTable.bookingId, booking.id));
+    const itemIds = items.map((i) => i.id);
+    const participants = await loadParticipants(db, booking.id, itemIds);
+    const payments = await db
+        .select()
+        .from(bookingPaymentsTable)
+        .where(eq(bookingPaymentsTable.bookingId, booking.id));
+    // Per-item participant schema, customer-visible only (staff fields hidden).
+    const schemaByItem = {};
+    for (const it of items) {
+        const fields = await resolveItemSchema(it.tripRef);
+        schemaByItem[it.id] = fields.filter((f) => canFill(f, 'customer'));
+    }
+    return toPortalView(booking, items, participants, payments.map((p) => ({ amount: p.amount, status: p.status, kind: p.kind, paidAt: p.paidAt })), schemaByItem);
+}
+/** Portal self-service edit (actor:'portal' guards). Throws → handler maps to 409/400. */
+export async function portalEdit(token, changes) {
+    const booking = await resolveByToken(token);
+    if (!booking)
+        return null;
+    await editBooking(booking.id, changes, { actor: 'portal' });
+    return portalView(token);
+}
+/** Portal: create an installment/balance payment link. */
+export async function portalPay(token, amount) {
+    const booking = await resolveByToken(token);
+    if (!booking)
+        return null;
+    return createInstallmentPayment(booking.id, amount);
+}
+/**
+ * Portal self-service: customer fills their own participant data. Verifies the
+ * assignment belongs to the token's booking (no cross-booking writes), then
+ * saves with `'customer'` scope (staff-only fields are dropped, not an error).
+ * Throws {@link ParticipantValidationError} on type/min/max/option violations.
+ *
+ * @param assignmentId - `booking_item_persons.id` (person-on-this-trip row).
+ */
+export async function portalUpdateParticipant(token, assignmentId, data) {
+    const booking = await resolveByToken(token);
+    if (!booking)
+        return null;
+    const db = getBookingDb();
+    const items = await db
+        .select({ id: bookingItemsTable.id })
+        .from(bookingItemsTable)
+        .where(eq(bookingItemsTable.bookingId, booking.id));
+    const itemIds = new Set(items.map((i) => i.id));
+    const [assignment] = await db
+        .select()
+        .from(bookingItemPersonsTable)
+        .where(eq(bookingItemPersonsTable.id, assignmentId));
+    if (!assignment || !itemIds.has(assignment.itemId))
+        return null;
+    await saveParticipantData(assignmentId, data, 'customer');
+    return portalView(token);
+}
+/**
+ * Self-service dobieranie wycieczki: doczytaj obecny stan, scal z `additions`
+ * (tylko istniejące osoby), przelicz przez `editBooking` (full-replace → recompute
+ * tym samym silnikiem per-uczestnik co koszyk). Saldo rośnie; dopłata istniejącym
+ * flow. `assignments` w additions = lista `booking_persons.id`. Kotwica nowej
+ * pozycji (`departureDate`) = `customer.arrivalDate`.
+ */
+export async function portalAddTrips(token, additions) {
+    const booking = await resolveByToken(token);
+    if (!booking)
+        return null;
+    const db = getBookingDb();
+    const persons = await db
+        .select()
+        .from(bookingPersonsTable)
+        .where(eq(bookingPersonsTable.bookingId, booking.id));
+    const items = await db
+        .select()
+        .from(bookingItemsTable)
+        .where(eq(bookingItemsTable.bookingId, booking.id));
+    const itemIds = items.map((i) => i.id);
+    const assigns = itemIds.length
+        ? await db
+            .select()
+            .from(bookingItemPersonsTable)
+            .where(inArray(bookingItemPersonsTable.itemId, itemIds))
+        : [];
+    const personIds = new Set(persons.map((p) => p.id));
+    const existingRefs = new Set(items.map((i) => i.tripRef));
+    for (const a of additions) {
+        if (existingRefs.has(a.tripRef)) {
+            throw new BookingValidationError('VALIDATION', `Wycieczka już w rezerwacji: ${a.tripRef}`);
+        }
+        for (const ref of a.assignments) {
+            if (!personIds.has(ref)) {
+                throw new BookingValidationError('VALIDATION', `Nieznana osoba: ${ref}`);
+            }
+        }
+    }
+    const personInputs = persons.map((p) => ({ ref: p.id, identity: p.data }));
+    const byItem = new Map();
+    for (const a of assigns)
+        byItem.set(a.itemId, [...(byItem.get(a.itemId) ?? []), a]);
+    const existingItems = items.map((it) => ({
+        tripRef: it.tripRef,
+        departureDate: it.departureDate,
+        unitPrice: it.unitPriceSnapshot,
+        assignments: (byItem.get(it.id) ?? []).map((a) => ({ personRef: a.personId, data: a.data }))
+    }));
+    const arrivalRaw = booking.customer?.arrivalDate;
+    const anchor = arrivalRaw ? new Date(arrivalRaw) : null;
+    // Bez `unitPrice`: cenę nowej pozycji ustala bramka cenowa w `editBooking` z katalogu
+    // (`actor: 'portal'`). Klient z ważnym tokenem nie może sobie dorzucić wyprawy za grosz.
+    const newItems = additions.map((a) => ({
+        tripRef: a.tripRef,
+        departureDate: anchor,
+        unitPrice: 0, // nadpisywane przez bramkę
+        assignments: a.assignments.map((ref) => ({ personRef: ref }))
+    }));
+    await editBooking(booking.id, { persons: personInputs, items: [...existingItems, ...newItems] }, { actor: 'portal' });
+    return portalView(token);
+}

package/dist/booking/server/price-source.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Kto pisze do rezerwacji. Steruje zaufaniem do ceny przyniesionej w żądaniu:
+ * `staff` jest zalogowaną obsługą (ręczna korekta ceny w adminie jest zamierzoną
+ * funkcją), `public`/`portal` to klient końcowy — jego ceny nie honorujemy nigdy.
+ */
+export type PriceActor = 'public' | 'portal' | 'staff';
+/** Cena nie do przyjęcia: brak w katalogu, ujemna albo w ułamku grosza. */
+export declare class PriceSourceError extends Error {
+    constructor(message: string);
+}
+/**
+ * Ustala cenę bazową każdej pozycji. **Niezmiennik: cena jest atrybutem katalogu,
+ * nie żądania.** Bez tego publiczny endpoint przyjmował `unitPrice` prosto z ciała
+ * żądania i rezerwację dało się złożyć za grosz.
+ *
+ * Kolejność źródeł:
+ * 1. `staff` z jawną ceną → jego cena (ręczna korekta w adminie),
+ * 2. pozycja już w rezerwacji → jej **snapshot** (zamrożony przy zakupie; dotknięcie
+ *    rezerwacji nie może podnieść klientowi ceny, gdy cennik poszedł w górę),
+ * 3. katalog przez szew `resolvePrice`.
+ *
+ * Czysta funkcja — I/O (odczyt katalogu) robi {@link fetchCatalogPrices}.
+ *
+ * @throws {PriceSourceError} gdy pozycji nie da się wycenić (fail-closed: brak ceny
+ * to odmowa, nigdy „zero").
+ */
+export declare function pickItemPrices(input: {
+    actor: PriceActor;
+    items: Array<{
+        tripRef: string;
+        unitPrice?: number;
+    }>;
+    /** `tripRef` → `unitPriceSnapshot` pozycji już zapisanych w tej rezerwacji. */
+    existingByRef: Map<string, number>;
+    /** `tripRef` → cena bazowa z katalogu (wynik szwu `resolvePrice`). */
+    catalogPrices: Map<string, number>;
+}): Array<{
+    tripRef: string;
+    unitPrice: number;
+}>;
+/**
+ * Odpytuje szew `resolvePrice` o cenę bazową podanych pozycji katalogu (równolegle,
+ * bez duplikatów). Szew jest **serwerowy** — czyta katalog projektu, więc przeglądarka
+ * nie ma na tę cenę wpływu.
+ *
+ * @throws {PriceSourceError} gdy `resolvePrice` nie jest skonfigurowany. Fail-closed:
+ * publiczny booking bez źródła cen musi odmówić, a nie po cichu zaufać żądaniu.
+ */
+export declare function fetchCatalogPrices(tripRefs: string[]): Promise<Map<string, number>>;
+/**
+ * Pozycje, o których trzeba zapytać katalog. Obsługa podająca cenę jawnie nie wymaga
+ * odczytu — dzięki temu instalacja bez publicznego bookingu (sam admin) działa bez
+ * skonfigurowanego `resolvePrice`.
+ *
+ * `existingByRef` bywa nieznane przed wejściem w transakcję (patrz `editBooking`) — wtedy
+ * pomiń je, a katalog zostanie odpytany też o pozycje, które ostatecznie wezmą snapshot.
+ * Kilka odczytów więcej jest tańsze niż odczyt katalogu pod blokadą wiersza.
+ */
+export declare function catalogRefsNeeded(actor: PriceActor, items: Array<{
+    tripRef: string;
+    unitPrice?: number;
+}>, existingByRef?: Map<string, number>): string[];
+/**
+ * Wycenia pozycje: odpytuje katalog **tylko o te, których nie da się wycenić inaczej**,
+ * a potem stosuje {@link pickItemPrices}. Wołaj poza transakcją — robi I/O.
+ */
+export declare function priceItemsFromCatalog(actor: PriceActor, items: Array<{
+    tripRef: string;
+    unitPrice?: number;
+}>, existingByRef: Map<string, number>): Promise<Array<{
+    tripRef: string;
+    unitPrice: number;
+}>>;

package/dist/booking/server/price-source.js

@@ -0,0 +1,94 @@
+import { requireBookingConfig } from './db.js';
+/** Cena nie do przyjęcia: brak w katalogu, ujemna albo w ułamku grosza. */
+export class PriceSourceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PriceSourceError';
+    }
+}
+function assertValidPrice(tripRef, value) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new PriceSourceError(`Niepoprawna cena pozycji ${tripRef}: ${value} (oczekiwano nieujemnej liczby całkowitej groszy)`);
+    }
+    return value;
+}
+/**
+ * Ustala cenę bazową każdej pozycji. **Niezmiennik: cena jest atrybutem katalogu,
+ * nie żądania.** Bez tego publiczny endpoint przyjmował `unitPrice` prosto z ciała
+ * żądania i rezerwację dało się złożyć za grosz.
+ *
+ * Kolejność źródeł:
+ * 1. `staff` z jawną ceną → jego cena (ręczna korekta w adminie),
+ * 2. pozycja już w rezerwacji → jej **snapshot** (zamrożony przy zakupie; dotknięcie
+ *    rezerwacji nie może podnieść klientowi ceny, gdy cennik poszedł w górę),
+ * 3. katalog przez szew `resolvePrice`.
+ *
+ * Czysta funkcja — I/O (odczyt katalogu) robi {@link fetchCatalogPrices}.
+ *
+ * @throws {PriceSourceError} gdy pozycji nie da się wycenić (fail-closed: brak ceny
+ * to odmowa, nigdy „zero").
+ */
+export function pickItemPrices(input) {
+    const { actor, items, existingByRef, catalogPrices } = input;
+    return items.map((it) => {
+        if (actor === 'staff' && it.unitPrice !== undefined) {
+            return { tripRef: it.tripRef, unitPrice: assertValidPrice(it.tripRef, it.unitPrice) };
+        }
+        const snapshot = existingByRef.get(it.tripRef);
+        if (snapshot !== undefined) {
+            return { tripRef: it.tripRef, unitPrice: assertValidPrice(it.tripRef, snapshot) };
+        }
+        const fromCatalog = catalogPrices.get(it.tripRef);
+        if (fromCatalog === undefined) {
+            throw new PriceSourceError(`Brak ceny w katalogu dla pozycji ${it.tripRef} — rezerwacji nie da się wycenić`);
+        }
+        return { tripRef: it.tripRef, unitPrice: assertValidPrice(it.tripRef, fromCatalog) };
+    });
+}
+/**
+ * Odpytuje szew `resolvePrice` o cenę bazową podanych pozycji katalogu (równolegle,
+ * bez duplikatów). Szew jest **serwerowy** — czyta katalog projektu, więc przeglądarka
+ * nie ma na tę cenę wpływu.
+ *
+ * @throws {PriceSourceError} gdy `resolvePrice` nie jest skonfigurowany. Fail-closed:
+ * publiczny booking bez źródła cen musi odmówić, a nie po cichu zaufać żądaniu.
+ */
+export async function fetchCatalogPrices(tripRefs) {
+    const refs = [...new Set(tripRefs)];
+    if (refs.length === 0)
+        return new Map();
+    const { resolvePrice } = requireBookingConfig();
+    if (!resolvePrice) {
+        throw new PriceSourceError('defineBooking({ resolvePrice }) nie jest skonfigurowany — publiczna rezerwacja nie ma z czego wziąć ceny. ' +
+            'Podaj szew czytający cenę z katalogu, np. ' +
+            '`resolvePrice: async (tripRef) => Math.round(Number((await resolveEntry({ id: tripRef, status: "published" }))?.price ?? 0) * 100)`.');
+    }
+    const prices = await Promise.all(refs.map(async (ref) => [ref, await resolvePrice(ref)]));
+    return new Map(prices);
+}
+/**
+ * Pozycje, o których trzeba zapytać katalog. Obsługa podająca cenę jawnie nie wymaga
+ * odczytu — dzięki temu instalacja bez publicznego bookingu (sam admin) działa bez
+ * skonfigurowanego `resolvePrice`.
+ *
+ * `existingByRef` bywa nieznane przed wejściem w transakcję (patrz `editBooking`) — wtedy
+ * pomiń je, a katalog zostanie odpytany też o pozycje, które ostatecznie wezmą snapshot.
+ * Kilka odczytów więcej jest tańsze niż odczyt katalogu pod blokadą wiersza.
+ */
+export function catalogRefsNeeded(actor, items, existingByRef) {
+    return items
+        .filter((it) => {
+        if (actor === 'staff' && it.unitPrice !== undefined)
+            return false;
+        return !existingByRef?.has(it.tripRef);
+    })
+        .map((it) => it.tripRef);
+}
+/**
+ * Wycenia pozycje: odpytuje katalog **tylko o te, których nie da się wycenić inaczej**,
+ * a potem stosuje {@link pickItemPrices}. Wołaj poza transakcją — robi I/O.
+ */
+export async function priceItemsFromCatalog(actor, items, existingByRef) {
+    const catalogPrices = await fetchCatalogPrices(catalogRefsNeeded(actor, items, existingByRef));
+    return pickItemPrices({ actor, items, existingByRef, catalogPrices });
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Refund a paid ledger entry via the adapter (staff-only manual action), then
+ * mark it `refunded` and recompute the booking's paid/balance + derived status.
+ * Full-payment refund semantics (the row is marked refunded); `amount` is passed
+ * to the provider for partial captures but the ledger treats the row as settled.
+ */
+export declare function refundPayment(paymentId: string, amount?: number): Promise<void>;

package/dist/booking/server/refunds.js

@@ -0,0 +1,58 @@
+import { eq } from 'drizzle-orm';
+import { getBookingDb, requireBookingConfig } from './db.js';
+import { bookingsTable, bookingPaymentsTable } from '../../db-postgres/schema/booking/index.js';
+import { deriveStatus } from '../state-machine.js';
+import { netOf } from '../totals.js';
+/**
+ * Refund a paid ledger entry via the adapter (staff-only manual action), then
+ * mark it `refunded` and recompute the booking's paid/balance + derived status.
+ * Full-payment refund semantics (the row is marked refunded); `amount` is passed
+ * to the provider for partial captures but the ledger treats the row as settled.
+ */
+export async function refundPayment(paymentId, amount) {
+    const config = requireBookingConfig();
+    const db = getBookingDb();
+    const [payment] = await db
+        .select()
+        .from(bookingPaymentsTable)
+        .where(eq(bookingPaymentsTable.id, paymentId));
+    if (!payment || payment.status !== 'paid' || !payment.providerRef) {
+        throw new Error('Payment not refundable');
+    }
+    const adapter = config.payment[0];
+    if (!adapter?.refund)
+        throw new Error('Adapter does not support refunds');
+    // Provider call first (outside the DB transaction — it's a network op).
+    await adapter.refund({ providerRef: payment.providerRef, amount, currency: config.currency });
+    await db.transaction(async (tx) => {
+        await tx
+            .update(bookingPaymentsTable)
+            .set({ status: 'refunded', updatedAt: new Date() })
+            .where(eq(bookingPaymentsTable.id, paymentId));
+        const [b] = await tx
+            .select()
+            .from(bookingsTable)
+            .where(eq(bookingsTable.id, payment.bookingId))
+            .for('update');
+        if (!b)
+            return;
+        const rows = await tx
+            .select()
+            .from(bookingPaymentsTable)
+            .where(eq(bookingPaymentsTable.bookingId, payment.bookingId));
+        const paid = rows.filter((p) => p.status === 'paid').reduce((s, p) => s + p.amount, 0);
+        await tx
+            .update(bookingsTable)
+            .set({
+            totals: { ...b.totals, paid, balance: Math.max(0, netOf(b.totals) - paid) },
+            status: deriveStatus({
+                gross: netOf(b.totals),
+                paid,
+                depositRequired: config.depositAmount,
+                current: b.status
+            }),
+            updatedAt: new Date()
+        })
+            .where(eq(bookingsTable.id, payment.bookingId));
+    });
+}

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

@@ -0,0 +1,9 @@
+import { getBookingDb } from './db.js';
+/** Exact drizzle transaction handle, derived from the booking db's `transaction`. */
+export type BookingTx = Parameters<Parameters<ReturnType<typeof getBookingDb>['transaction']>[0]>[0];
+/**
+ * Recompute the reminder schedule for a booking after a departure-date change:
+ * drop the unsent reminders and re-insert from the current departures. Sent
+ * reminders are preserved (audit). Runs inside the caller's transaction.
+ */
+export declare function rescheduleReminders(tx: BookingTx, bookingId: string, dates: Array<Date | null>): Promise<void>;

package/dist/booking/server/reminders.js

@@ -0,0 +1,24 @@
+import { and, eq, isNull } from 'drizzle-orm';
+import { bookingRemindersTable } from '../../db-postgres/schema/booking/index.js';
+import { computeReminderSchedule } from '../reminders-schedule.js';
+import { getBookingDb, requireBookingConfig } from './db.js';
+/**
+ * Recompute the reminder schedule for a booking after a departure-date change:
+ * drop the unsent reminders and re-insert from the current departures. Sent
+ * reminders are preserved (audit). Runs inside the caller's transaction.
+ */
+export async function rescheduleReminders(tx, bookingId, dates) {
+    const config = requireBookingConfig();
+    await tx
+        .delete(bookingRemindersTable)
+        .where(and(eq(bookingRemindersTable.bookingId, bookingId), isNull(bookingRemindersTable.sentAt)));
+    const rows = computeReminderSchedule(dates, config.reminders);
+    if (rows.length > 0) {
+        await tx.insert(bookingRemindersTable).values(rows.map((r) => ({
+            bookingId,
+            type: r.type,
+            templateKey: r.templateKey,
+            scheduledFor: r.scheduledFor
+        })));
+    }
+}

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

@@ -0,0 +1,17 @@
+import type { BookingValidationContext } from '../config.js';
+/** Thrown when a booking fails capacity (core) or the client `validateBooking` seam. */
+export declare class BookingValidationError extends Error {
+    code: 'CAPACITY' | 'VALIDATION';
+    constructor(code: 'CAPACITY' | 'VALIDATION', message: string);
+}
+/**
+ * Generic seat-capacity check (core). Sums requested participants per trip and
+ * compares against the catalog capacity minus what active bookings already hold.
+ * `excludeBookingId` drops the booking being edited from the existing tally.
+ */
+export declare function runCapacityCheck(items: Array<{
+    tripRef: string;
+    participantsCount: number;
+}>, excludeBookingId?: string): Promise<void>;
+/** Invoke the client-supplied validation seam, wrapping failures uniformly. */
+export declare function runValidateBooking(ctx: BookingValidationContext): Promise<void>;

package/dist/booking/server/validation.js

@@ -0,0 +1,55 @@
+import { and, eq, isNull, ne } from 'drizzle-orm';
+import { getBookingDb, requireBookingConfig } from './db.js';
+import { bookingsTable, bookingItemsTable } from '../../db-postgres/schema/booking/index.js';
+import { decideCapacity } from '../capacity.js';
+import { readTripCapacity } from './catalog.js';
+/** Thrown when a booking fails capacity (core) or the client `validateBooking` seam. */
+export class BookingValidationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'BookingValidationError';
+    }
+}
+/**
+ * Generic seat-capacity check (core). Sums requested participants per trip and
+ * compares against the catalog capacity minus what active bookings already hold.
+ * `excludeBookingId` drops the booking being edited from the existing tally.
+ */
+export async function runCapacityCheck(items, excludeBookingId) {
+    const db = getBookingDb();
+    const requestedByTrip = new Map();
+    for (const it of items) {
+        requestedByTrip.set(it.tripRef, (requestedByTrip.get(it.tripRef) ?? 0) + it.participantsCount);
+    }
+    for (const [tripRef, requested] of requestedByTrip) {
+        const capacity = await readTripCapacity(tripRef);
+        if (capacity == null)
+            continue; // unlimited / unconfigured
+        const rows = await db
+            .select({ count: bookingItemsTable.participantsCount, bid: bookingsTable.id })
+            .from(bookingItemsTable)
+            .innerJoin(bookingsTable, eq(bookingItemsTable.bookingId, bookingsTable.id))
+            .where(and(eq(bookingItemsTable.tripRef, tripRef), isNull(bookingsTable.deletedAt), ne(bookingsTable.status, 'cancelled')));
+        const alreadyBooked = rows
+            .filter((r) => r.bid !== excludeBookingId)
+            .reduce((s, r) => s + r.count, 0);
+        const { ok, available } = decideCapacity({ capacity, alreadyBooked, requested });
+        if (!ok) {
+            throw new BookingValidationError('CAPACITY', `Trip ${tripRef} has only ${available} seats left (requested ${requested}).`);
+        }
+    }
+}
+/** Invoke the client-supplied validation seam, wrapping failures uniformly. */
+export async function runValidateBooking(ctx) {
+    const config = requireBookingConfig();
+    if (!config.validateBooking)
+        return;
+    try {
+        await config.validateBooking(ctx);
+    }
+    catch (err) {
+        throw new BookingValidationError('VALIDATION', err instanceof Error ? err.message : 'Validation failed');
+    }
+}

package/dist/booking/state-machine.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Booking state machine — pure, deterministic. Two concerns:
+ *
+ *  1. {@link deriveStatus} computes the payment-progress status from money
+ *     (gross, paid, deposit) — the source of truth is the ledger balance.
+ *  2. {@link assertTransition} / {@link canTransition} validate **manual**
+ *     status moves (notably `→ completed` and `→ cancelled`), rejecting illegal
+ *     transitions with a {@link BookingStateError}.
+ */
+export type BookingStatus = 'draft' | 'reserved' | 'partially_paid' | 'paid' | 'completed' | 'cancelled';
+export declare const BOOKING_STATUSES: readonly BookingStatus[];
+/** Thrown when an illegal status transition is attempted. */
+export declare class BookingStateError extends Error {
+    from: BookingStatus;
+    to: BookingStatus;
+    constructor(from: BookingStatus, to: BookingStatus);
+}
+/** Whether `from → to` is a legal transition (self-transitions are allowed). */
+export declare function canTransition(from: BookingStatus, to: BookingStatus): boolean;
+/** Asserts a legal transition, throwing {@link BookingStateError} otherwise. */
+export declare function assertTransition(from: BookingStatus, to: BookingStatus): void;
+export interface DeriveStatusInput {
+    /** Total gross owed, in minor units. */
+    gross: number;
+    /** Total amount paid (ledger sum of paid entries), in minor units. */
+    paid: number;
+    /** Deposit threshold that secures a reservation, in minor units. */
+    depositRequired: number;
+    /** Current status — terminal states (`completed`/`cancelled`) are preserved. */
+    current?: BookingStatus;
+}
+/**
+ * Derives the payment-progress status from the ledger.
+ *
+ * Money bands (after preserving terminal states):
+ *  - `paid == 0` → `draft`
+ *  - `paid >= gross` (gross > 0) → `paid`
+ *  - `paid > depositRequired` → `partially_paid` (installments beyond deposit)
+ *  - `0 < paid <= depositRequired` → `reserved` (deposit secured)
+ */
+export declare function deriveStatus(input: DeriveStatusInput): BookingStatus;