includio-cms 0.36.8 → 0.37.0

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

@@ -0,0 +1,27 @@
+import { type AdjustmentKind, type BookingAdjustment } from '../adjustments.js';
+export interface AddAdjustmentInput {
+    kind: AdjustmentKind;
+    /** UI-entered POSITIVE magnitude (minor units). */
+    magnitude: number;
+    label: string;
+    reason?: string | null;
+}
+/** List all adjustments (active + voided) for a booking, newest first. */
+export declare function listBookingAdjustments(bookingId: string): Promise<BookingAdjustment[]>;
+/**
+ * Add a manual adjustment (surcharge/discount) and recompute the booking totals
+ * + derived status in one transaction. Rejects an adjustment that would push the
+ * net owed below zero. `amount` is stored signed (surcharge > 0, discount < 0).
+ */
+export declare function addBookingAdjustment(bookingId: string, input: AddAdjustmentInput, opts: {
+    actor: string;
+    now?: Date;
+}): Promise<BookingAdjustment>;
+/**
+ * Soft-void an adjustment (kept for audit) and recompute the booking totals +
+ * status. Throws if the adjustment is missing or already voided.
+ */
+export declare function voidBookingAdjustment(adjustmentId: string, opts: {
+    actor: string;
+    now?: Date;
+}): Promise<void>;

package/dist/booking/server/adjustments.js

@@ -0,0 +1,136 @@
+import { and, desc, eq, isNull } from 'drizzle-orm';
+import { getBookingDb, requireBookingConfig } from './db.js';
+import { bookingsTable, bookingPaymentsTable, bookingAdjustmentsTable } from '../../db-postgres/schema/booking/index.js';
+import { signedAmount, sumAdjustments, assertAdjustmentMagnitude } from '../adjustments.js';
+import { recomputeTotals, assertEditAllowed } from '../recompute.js';
+import { netOf } from '../totals.js';
+import { deriveStatus } from '../state-machine.js';
+import { priceFromExistingRows } from './bookings.js';
+/** List all adjustments (active + voided) for a booking, newest first. */
+export async function listBookingAdjustments(bookingId) {
+    const db = getBookingDb();
+    const rows = await db
+        .select()
+        .from(bookingAdjustmentsTable)
+        .where(eq(bookingAdjustmentsTable.bookingId, bookingId))
+        .orderBy(desc(bookingAdjustmentsTable.createdAt));
+    return rows;
+}
+/**
+ * Add a manual adjustment (surcharge/discount) and recompute the booking totals
+ * + derived status in one transaction. Rejects an adjustment that would push the
+ * net owed below zero. `amount` is stored signed (surcharge > 0, discount < 0).
+ */
+export async function addBookingAdjustment(bookingId, input, opts) {
+    assertAdjustmentMagnitude(input.magnitude);
+    const config = requireBookingConfig();
+    const db = getBookingDb();
+    const now = opts.now ?? new Date();
+    const amount = signedAmount(input.kind, input.magnitude);
+    return db.transaction(async (tx) => {
+        const [booking] = await tx
+            .select()
+            .from(bookingsTable)
+            .where(eq(bookingsTable.id, bookingId))
+            .for('update');
+        if (!booking)
+            throw new Error(`Booking ${bookingId} not found`);
+        assertEditAllowed(booking.status);
+        const result = await priceFromExistingRows(tx, bookingId, config, now);
+        const active = await tx
+            .select()
+            .from(bookingAdjustmentsTable)
+            .where(and(eq(bookingAdjustmentsTable.bookingId, bookingId), isNull(bookingAdjustmentsTable.voidedAt)));
+        const prospective = sumAdjustments([...active, { amount, voidedAt: null }]);
+        const payments = (await tx
+            .select()
+            .from(bookingPaymentsTable)
+            .where(eq(bookingPaymentsTable.bookingId, bookingId))).map((p) => ({ amount: p.amount, status: p.status, kind: p.kind }));
+        const totals = recomputeTotals(result, prospective, payments);
+        // Raw (unclamped) net — netOf() floors at 0, so guard on the raw value.
+        const rawNet = totals.gross - totals.discount - totals.manualDiscount + totals.surcharge;
+        if (rawNet < 0) {
+            throw new Error('Adjustment would make the booking total negative');
+        }
+        const [row] = await tx
+            .insert(bookingAdjustmentsTable)
+            .values({
+            bookingId,
+            kind: input.kind,
+            amount,
+            label: input.label,
+            reason: input.reason ?? null,
+            createdBy: opts.actor
+        })
+            .returning();
+        await tx
+            .update(bookingsTable)
+            .set({
+            totals,
+            status: deriveStatus({
+                gross: netOf(totals),
+                paid: totals.paid,
+                depositRequired: config.depositAmount,
+                current: booking.status
+            }),
+            updatedAt: now
+        })
+            .where(eq(bookingsTable.id, bookingId));
+        return row;
+    });
+}
+/**
+ * Soft-void an adjustment (kept for audit) and recompute the booking totals +
+ * status. Throws if the adjustment is missing or already voided.
+ */
+export async function voidBookingAdjustment(adjustmentId, opts) {
+    const config = requireBookingConfig();
+    const db = getBookingDb();
+    const now = opts.now ?? new Date();
+    await db.transaction(async (tx) => {
+        const [adj] = await tx
+            .select()
+            .from(bookingAdjustmentsTable)
+            .where(eq(bookingAdjustmentsTable.id, adjustmentId))
+            .for('update');
+        if (!adj)
+            throw new Error('Adjustment not found');
+        if (adj.voidedAt)
+            throw new Error('Adjustment already voided');
+        const [booking] = await tx
+            .select()
+            .from(bookingsTable)
+            .where(eq(bookingsTable.id, adj.bookingId))
+            .for('update');
+        if (!booking)
+            throw new Error('Booking not found');
+        assertEditAllowed(booking.status);
+        await tx
+            .update(bookingAdjustmentsTable)
+            .set({ voidedAt: now, voidedBy: opts.actor })
+            .where(eq(bookingAdjustmentsTable.id, adjustmentId));
+        const result = await priceFromExistingRows(tx, adj.bookingId, config, now);
+        const active = await tx
+            .select()
+            .from(bookingAdjustmentsTable)
+            .where(and(eq(bookingAdjustmentsTable.bookingId, adj.bookingId), isNull(bookingAdjustmentsTable.voidedAt)));
+        const payments = (await tx
+            .select()
+            .from(bookingPaymentsTable)
+            .where(eq(bookingPaymentsTable.bookingId, adj.bookingId))).map((p) => ({ amount: p.amount, status: p.status, kind: p.kind }));
+        const totals = recomputeTotals(result, sumAdjustments(active), payments);
+        await tx
+            .update(bookingsTable)
+            .set({
+            totals,
+            status: deriveStatus({
+                gross: netOf(totals),
+                paid: totals.paid,
+                depositRequired: config.depositAmount,
+                current: booking.status
+            }),
+            updatedAt: now
+        })
+            .where(eq(bookingsTable.id, adj.bookingId));
+    });
+}

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

@@ -0,0 +1,45 @@
+import { bookingsTable } from '../../db-postgres/schema/booking/index.js';
+import { type CreateBookingInput, type PersonInput, type ItemAssignmentInput } from '../draft.js';
+import { type ParticipantPriceResult } from '../participant-pricing.js';
+import type { ResolvedBookingConfig } from '../config.js';
+import { type BookingTx } from './reminders.js';
+/** Edit payload: replace people + items (+assignments) and/or customer details. */
+export interface BookingEditChanges {
+    persons?: PersonInput[];
+    items?: Array<{
+        tripRef: string;
+        departureDate: Date | null;
+        unitPrice: number;
+        assignments: ItemAssignmentInput[];
+    }>;
+    customer?: Record<string, unknown>;
+}
+/**
+ * Create a booking (public self-serve or staff). Validates catalog capacity +
+ * the client seam, prices the draft per-participant, and persists booking +
+ * people + items + assignments + reminders in one transaction. Status starts
+ * `draft`; the deposit payment (and its webhook) drives the status forward.
+ */
+export declare function createBooking(input: CreateBookingInput, opts?: {
+    now?: Date;
+}): Promise<{
+    booking: typeof bookingsTable.$inferSelect;
+    accessToken: string;
+}>;
+/**
+ * Edit a booking (staff or portal). Recomputes totals per-participant + derived
+ * status, enforces the actor's guards (`portal` blocks dropping below paid),
+ * re-runs capacity + validate seam when items change, replaces people/items/
+ * assignments, and reschedules reminders on a departure change. One transaction.
+ */
+export declare function editBooking(bookingId: string, changes: BookingEditChanges, opts: {
+    actor: 'staff' | 'portal';
+    now?: Date;
+}): Promise<typeof bookingsTable.$inferSelect>;
+/**
+ * Price a booking from its CURRENTLY persisted people/items/assignments (no
+ * edit). Shared by adjustment recompute — mirrors the "no items change" branch
+ * of {@link editBooking}. Must run inside a transaction that has locked the
+ * booking row.
+ */
+export declare function priceFromExistingRows(tx: BookingTx, bookingId: string, config: ResolvedBookingConfig, now: Date): Promise<ParticipantPriceResult>;

package/dist/booking/server/bookings.js

@@ -0,0 +1,288 @@
+import { and, eq, inArray, isNull } from 'drizzle-orm';
+import { getBookingDb, requireBookingConfig } from './db.js';
+import { bookingsTable, bookingItemsTable, bookingPersonsTable, bookingItemPersonsTable, bookingPaymentsTable, bookingRemindersTable, bookingAdjustmentsTable } from '../../db-postgres/schema/booking/index.js';
+import { buildBookingDraft, pricingInputsFromCreate } from '../draft.js';
+import { buildPricingInputs } from '../pricing-inputs.js';
+import { priceByParticipant } from '../participant-pricing.js';
+import { grossByTripRef, netOf } from '../totals.js';
+import { sumAdjustments } from '../adjustments.js';
+import { resolveItemSchema } from './participants.js';
+import { generateBookingNumber } from '../number.js';
+import { recomputeTotals, assertEditAllowed, assertPortalEditAllowed } from '../recompute.js';
+import { deriveStatus } from '../state-machine.js';
+import { runCapacityCheck, runValidateBooking } from './validation.js';
+import { rescheduleReminders } from './reminders.js';
+/** Resolve personRef → DB person id; throws on a dangling assignment reference. */
+function personIdLookup(map, ref) {
+    const id = map.get(ref);
+    if (!id)
+        throw new Error(`Assignment references unknown personRef "${ref}"`);
+    return id;
+}
+/** Parse the arrival-date anchor from a customer field value (Date or ISO string). */
+function parseAnchor(raw) {
+    if (raw instanceof Date)
+        return raw;
+    if (typeof raw === 'string' && !Number.isNaN(Date.parse(raw)))
+        return new Date(raw);
+    return null;
+}
+/**
+ * Resolve the per-call pricing context: the editable participant-pricing config
+ * (from the client resolver, e.g. globalSettings), the arrival-date anchor from
+ * the customer, and the identity field schema (to locate the dob key).
+ */
+async function buildPricingContext(config, customer, tripRefForSchema) {
+    const participantPricing = config.participantPricing
+        ? await config.participantPricing()
+        : { ageBands: [], ladder: [], earlyBird: null };
+    const anchor = parseAnchor(customer[config.arrivalDateField]);
+    const identityFields = tripRefForSchema ? await resolveItemSchema(tripRefForSchema) : [];
+    return { participantPricing, anchor, identityFields };
+}
+/**
+ * Create a booking (public self-serve or staff). Validates catalog capacity +
+ * the client seam, prices the draft per-participant, and persists booking +
+ * people + items + assignments + reminders in one transaction. Status starts
+ * `draft`; the deposit payment (and its webhook) drives the status forward.
+ */
+export async function createBooking(input, opts = {}) {
+    const config = requireBookingConfig();
+    const db = getBookingDb();
+    const now = opts.now ?? new Date();
+    const validationItems = input.items.map((it) => ({
+        tripRef: it.tripRef,
+        departureDate: it.departureDate,
+        participantsCount: it.assignments.length
+    }));
+    await runCapacityCheck(validationItems);
+    await runValidateBooking({
+        operation: 'create',
+        bookingId: null,
+        items: validationItems,
+        customer: input.customer
+    });
+    const ctx = await buildPricingContext(config, input.customer, input.items[0]?.tripRef);
+    const draft = buildBookingDraft(input, config, ctx, now);
+    // Unique booking number with collision retry (~25 bits → rare).
+    let number = generateBookingNumber();
+    for (let i = 0; i < 5; i++) {
+        const hit = await db
+            .select({ id: bookingsTable.id })
+            .from(bookingsTable)
+            .where(eq(bookingsTable.number, number));
+        if (hit.length === 0)
+            break;
+        number = generateBookingNumber();
+    }
+    return db.transaction(async (tx) => {
+        const [booking] = await tx
+            .insert(bookingsTable)
+            .values({
+            number,
+            status: 'draft',
+            currency: config.currency,
+            customer: input.customer,
+            totals: draft.totals,
+            balanceDueAt: draft.balanceDueAt,
+            holdExpiresAt: draft.holdExpiresAt,
+            language: input.language ?? null
+        })
+            .returning();
+        const personIdByRef = new Map();
+        for (const p of draft.persons) {
+            const [person] = await tx
+                .insert(bookingPersonsTable)
+                .values({ bookingId: booking.id, data: p.identity })
+                .returning();
+            personIdByRef.set(p.ref, person.id);
+        }
+        for (const it of draft.items) {
+            const [item] = await tx
+                .insert(bookingItemsTable)
+                .values({
+                bookingId: booking.id,
+                tripRef: it.tripRef,
+                departureDate: it.departureDate,
+                participantsCount: it.participantsCount,
+                unitPriceSnapshot: it.unitPriceSnapshot,
+                subtotalSnapshot: it.subtotalSnapshot,
+                appliedDiscounts: it.appliedDiscounts
+            })
+                .returning();
+            if (it.assignments.length > 0) {
+                await tx.insert(bookingItemPersonsTable).values(it.assignments.map((a) => ({
+                    itemId: item.id,
+                    personId: personIdLookup(personIdByRef, a.personRef),
+                    data: a.data ?? {}
+                })));
+            }
+        }
+        if (draft.reminders.length > 0) {
+            await tx.insert(bookingRemindersTable).values(draft.reminders.map((r) => ({
+                bookingId: booking.id,
+                type: r.type,
+                templateKey: r.templateKey,
+                scheduledFor: r.scheduledFor
+            })));
+        }
+        return { booking, accessToken: booking.accessToken };
+    });
+}
+/**
+ * Edit a booking (staff or portal). Recomputes totals per-participant + derived
+ * status, enforces the actor's guards (`portal` blocks dropping below paid),
+ * re-runs capacity + validate seam when items change, replaces people/items/
+ * assignments, and reschedules reminders on a departure change. One transaction.
+ */
+export async function editBooking(bookingId, changes, opts) {
+    const config = requireBookingConfig();
+    const db = getBookingDb();
+    const now = opts.now ?? new Date();
+    return db.transaction(async (tx) => {
+        const [booking] = await tx
+            .select()
+            .from(bookingsTable)
+            .where(eq(bookingsTable.id, bookingId))
+            .for('update');
+        if (!booking)
+            throw new Error(`Booking ${bookingId} not found`);
+        const existingItems = await tx
+            .select()
+            .from(bookingItemsTable)
+            .where(eq(bookingItemsTable.bookingId, bookingId));
+        const customerForCtx = changes.customer ?? booking.customer;
+        const tripRefForSchema = changes.items?.[0]?.tripRef ?? existingItems[0]?.tripRef;
+        const ctx = await buildPricingContext(config, customerForCtx, tripRefForSchema);
+        // Pricing inputs: from the edit when items change, else from existing rows.
+        let participants;
+        let trips;
+        if (changes.items) {
+            const pi = pricingInputsFromCreate({ customer: customerForCtx, persons: changes.persons ?? [], items: changes.items }, ctx.identityFields);
+            participants = pi.participants;
+            trips = pi.trips;
+        }
+        else {
+            const existingItemIds = existingItems.map((i) => i.id);
+            const persons = await tx
+                .select()
+                .from(bookingPersonsTable)
+                .where(eq(bookingPersonsTable.bookingId, bookingId));
+            const assignments = existingItemIds.length
+                ? await tx
+                    .select()
+                    .from(bookingItemPersonsTable)
+                    .where(inArray(bookingItemPersonsTable.itemId, existingItemIds))
+                : [];
+            const pi = buildPricingInputs(persons.map((p) => ({ id: p.id, data: p.data })), existingItems.map((i) => ({ id: i.id, tripRef: i.tripRef, unitPrice: i.unitPriceSnapshot })), assignments.map((a) => ({ itemId: a.itemId, personId: a.personId })), ctx.identityFields);
+            participants = pi.participants;
+            trips = pi.trips;
+        }
+        const result = priceByParticipant(participants, trips, ctx.anchor, now, ctx.participantPricing);
+        const dates = (changes.items ?? existingItems).map((it) => it.departureDate);
+        const payments = (await tx
+            .select()
+            .from(bookingPaymentsTable)
+            .where(eq(bookingPaymentsTable.bookingId, bookingId))).map((p) => ({ amount: p.amount, status: p.status, kind: p.kind }));
+        const adjustments = await tx
+            .select()
+            .from(bookingAdjustmentsTable)
+            .where(and(eq(bookingAdjustmentsTable.bookingId, bookingId), isNull(bookingAdjustmentsTable.voidedAt)));
+        const sums = sumAdjustments(adjustments);
+        const totals = recomputeTotals(result, sums, payments);
+        if (opts.actor === 'portal')
+            assertPortalEditAllowed(booking.status, netOf(totals), payments);
+        else
+            assertEditAllowed(booking.status);
+        if (changes.items) {
+            const validationItems = changes.items.map((it) => ({
+                tripRef: it.tripRef,
+                departureDate: it.departureDate,
+                participantsCount: it.assignments.length
+            }));
+            await runCapacityCheck(validationItems, bookingId);
+            await runValidateBooking({
+                operation: 'edit',
+                bookingId,
+                items: validationItems,
+                customer: customerForCtx
+            });
+            const subtotalByRef = grossByTripRef(result);
+            // Replace people + items + assignments (item delete cascades assignments).
+            await tx.delete(bookingItemsTable).where(eq(bookingItemsTable.bookingId, bookingId));
+            await tx.delete(bookingPersonsTable).where(eq(bookingPersonsTable.bookingId, bookingId));
+            const personIdByRef = new Map();
+            for (const p of changes.persons ?? []) {
+                const [person] = await tx
+                    .insert(bookingPersonsTable)
+                    .values({ bookingId, data: p.identity })
+                    .returning();
+                personIdByRef.set(p.ref, person.id);
+            }
+            for (const it of changes.items) {
+                const [item] = await tx
+                    .insert(bookingItemsTable)
+                    .values({
+                    bookingId,
+                    tripRef: it.tripRef,
+                    departureDate: it.departureDate,
+                    participantsCount: it.assignments.length,
+                    unitPriceSnapshot: it.unitPrice,
+                    subtotalSnapshot: subtotalByRef.get(it.tripRef) ?? null,
+                    appliedDiscounts: totals.appliedRules.filter((r) => r.targetRef === it.tripRef)
+                })
+                    .returning();
+                if (it.assignments.length > 0) {
+                    await tx.insert(bookingItemPersonsTable).values(it.assignments.map((a) => ({
+                        itemId: item.id,
+                        personId: personIdLookup(personIdByRef, a.personRef),
+                        data: a.data ?? {}
+                    })));
+                }
+            }
+        }
+        const status = deriveStatus({
+            gross: netOf(totals),
+            paid: totals.paid,
+            depositRequired: config.depositAmount,
+            current: booking.status
+        });
+        const [updated] = await tx
+            .update(bookingsTable)
+            .set({ totals, status, customer: customerForCtx, updatedAt: now })
+            .where(eq(bookingsTable.id, bookingId))
+            .returning();
+        if (changes.items)
+            await rescheduleReminders(tx, bookingId, dates);
+        return updated;
+    });
+}
+/**
+ * Price a booking from its CURRENTLY persisted people/items/assignments (no
+ * edit). Shared by adjustment recompute — mirrors the "no items change" branch
+ * of {@link editBooking}. Must run inside a transaction that has locked the
+ * booking row.
+ */
+export async function priceFromExistingRows(tx, bookingId, config, now) {
+    const [booking] = await tx.select().from(bookingsTable).where(eq(bookingsTable.id, bookingId));
+    if (!booking)
+        throw new Error(`Booking ${bookingId} not found`);
+    const existingItems = await tx
+        .select()
+        .from(bookingItemsTable)
+        .where(eq(bookingItemsTable.bookingId, bookingId));
+    const ctx = await buildPricingContext(config, booking.customer, existingItems[0]?.tripRef);
+    const persons = await tx
+        .select()
+        .from(bookingPersonsTable)
+        .where(eq(bookingPersonsTable.bookingId, bookingId));
+    const itemIds = existingItems.map((i) => i.id);
+    const assignments = itemIds.length
+        ? await tx
+            .select()
+            .from(bookingItemPersonsTable)
+            .where(inArray(bookingItemPersonsTable.itemId, itemIds))
+        : [];
+    const pi = buildPricingInputs(persons.map((p) => ({ id: p.id, data: p.data })), existingItems.map((i) => ({ id: i.id, tripRef: i.tripRef, unitPrice: i.unitPriceSnapshot })), assignments.map((a) => ({ itemId: a.itemId, personId: a.personId })), ctx.identityFields);
+    return priceByParticipant(pi.participants, pi.trips, ctx.anchor, now, ctx.participantPricing);
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Read a trip's seat capacity from the catalog collection.
+ *
+ * Contract: `tripRef` is the catalog **entry id** (`Entry._id`). The client
+ * storefront stores the resolved trip's `_id` on each booking item. Returns
+ * `null` (treated as unlimited) when no `capacityField` is configured, the entry
+ * is missing/unpublished, or the field is absent/non-numeric.
+ */
+export declare function readTripCapacity(tripRef: string): Promise<number | null>;

package/dist/booking/server/catalog.js

@@ -0,0 +1,20 @@
+import { resolveEntry } from '../../core/server/entries/operations/resolveEntry.js';
+import { requireBookingConfig } from './db.js';
+/**
+ * Read a trip's seat capacity from the catalog collection.
+ *
+ * Contract: `tripRef` is the catalog **entry id** (`Entry._id`). The client
+ * storefront stores the resolved trip's `_id` on each booking item. Returns
+ * `null` (treated as unlimited) when no `capacityField` is configured, the entry
+ * is missing/unpublished, or the field is absent/non-numeric.
+ */
+export async function readTripCapacity(tripRef) {
+    const config = requireBookingConfig();
+    if (!config.capacityField)
+        return null;
+    const entry = await resolveEntry({ id: tripRef, status: 'published' });
+    if (!entry)
+        return null;
+    const raw = entry[config.capacityField];
+    return typeof raw === 'number' ? raw : null;
+}

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

@@ -0,0 +1,7 @@
+import type { ResolvedBookingConfig } from '../index.js';
+/** Returns the Drizzle handle, asserting the postgres adapter is in use. */
+export declare function getBookingDb(): import("drizzle-orm/postgres-js/driver", { with: { "resolution-mode": "require" } }).PostgresJsDatabase<typeof import("../../db-postgres/schema/index.js")> & {
+    $client: import("postgres").Sql<{}>;
+};
+/** Returns the resolved booking config, throwing when the module is not registered. */
+export declare function requireBookingConfig(): ResolvedBookingConfig;

package/dist/booking/server/db.js

@@ -0,0 +1,18 @@
+import { getCMS } from '../../core/cms.js';
+/** Returns the Drizzle handle, asserting the postgres adapter is in use. */
+export function getBookingDb() {
+    const cms = getCMS();
+    const adapter = cms.databaseAdapter;
+    if (!adapter._drizzle) {
+        throw new Error('Booking requires the db-postgres adapter (Drizzle instance missing).');
+    }
+    return adapter._drizzle;
+}
+/** Returns the resolved booking config, throwing when the module is not registered. */
+export function requireBookingConfig() {
+    const cfg = getCMS().getModuleConfig('booking');
+    if (!cfg) {
+        throw new Error('Booking is not configured. Add `defineBooking({...})` to `modules` in your CMS config.');
+    }
+    return cfg;
+}

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

@@ -0,0 +1,23 @@
+/** The transactional emails the booking module can send. */
+export type BookingEmailKind = 'booking-received' | 'deposit-paid' | 'payment-received' | 'payment-link' | 'balance-due' | 'balance-overdue-cancelled';
+/** Template file name for a kind (1:1 — kept as a function for future indirection). */
+export declare function pickEmailTemplate(kind: BookingEmailKind): string;
+/** Localised subject for a kind, falling back to English. */
+export declare function subjectFor(kind: BookingEmailKind, lang: string): string;
+/** Render a booking email's HTML body for the given language + context. */
+export declare function renderBookingEmail(kind: BookingEmailKind, lang: string, context: Record<string, unknown>): Promise<string>;
+/** Pure render-context builder for a booking email. @internal */
+export declare function buildEmailContext(booking: {
+    accessToken: string;
+    customer: Record<string, unknown>;
+} & Record<string, unknown>, config: {
+    currency: string;
+    brand: string | null;
+    portalUrlTemplate: string | null;
+}, now: Date, extra?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Send a transactional booking email to the booker. No-op when no email adapter
+ * is configured, the booking is missing, or it has no customer email. `extra` is
+ * merged into the render context (e.g. `{ amount, paymentLink }` for payment-link).
+ */
+export declare function sendBookingEmail(bookingId: string, kind: BookingEmailKind, extra?: Record<string, unknown>): Promise<void>;

package/dist/booking/server/email.js

@@ -0,0 +1,59 @@
+import { eq } from 'drizzle-orm';
+import { getCMS } from '../../core/cms.js';
+import { getBookingDb, requireBookingConfig } from './db.js';
+import { bookingsTable } from '../../db-postgres/schema/booking/index.js';
+import { renderEmailTemplate } from './emailTemplateRegistry.js';
+/** Template file name for a kind (1:1 — kept as a function for future indirection). */
+export function pickEmailTemplate(kind) {
+    return kind;
+}
+const SUBJECTS = {
+    'booking-received': { pl: 'Rezerwacja przyjęta', en: 'Booking received' },
+    'deposit-paid': { pl: 'Zadatek zaksięgowany', en: 'Deposit received' },
+    'payment-received': { pl: 'Płatność zaksięgowana', en: 'Payment received' },
+    'payment-link': { pl: 'Link do płatności', en: 'Payment link' },
+    'balance-due': { pl: 'Przypomnienie o dopłacie', en: 'Balance reminder' },
+    'balance-overdue-cancelled': { pl: 'Rezerwacja anulowana', en: 'Booking cancelled' }
+};
+/** Localised subject for a kind, falling back to English. */
+export function subjectFor(kind, lang) {
+    return SUBJECTS[kind][lang] ?? SUBJECTS[kind].en;
+}
+/** Render a booking email's HTML body for the given language + context. */
+export async function renderBookingEmail(kind, lang, context) {
+    return renderEmailTemplate(pickEmailTemplate(kind), lang, context);
+}
+/** Pure render-context builder for a booking email. @internal */
+export function buildEmailContext(booking, config, now, extra = {}) {
+    const portalUrl = config.portalUrlTemplate
+        ? config.portalUrlTemplate.replace('{token}', booking.accessToken)
+        : undefined;
+    return { booking, currency: config.currency, brand: config.brand, portalUrl, now, ...extra };
+}
+/**
+ * Send a transactional booking email to the booker. No-op when no email adapter
+ * is configured, the booking is missing, or it has no customer email. `extra` is
+ * merged into the render context (e.g. `{ amount, paymentLink }` for payment-link).
+ */
+export async function sendBookingEmail(bookingId, kind, extra = {}) {
+    const cms = getCMS();
+    const email = cms.emailAdapter;
+    if (!email)
+        return;
+    const config = requireBookingConfig();
+    const db = getBookingDb();
+    const [booking] = await db.select().from(bookingsTable).where(eq(bookingsTable.id, bookingId));
+    if (!booking)
+        return;
+    const lang = booking.language ?? cms.languages[0] ?? 'pl';
+    const to = String(booking.customer.email ?? '');
+    if (!to)
+        return;
+    const context = buildEmailContext(booking, {
+        currency: config.currency,
+        brand: config.brand,
+        portalUrlTemplate: config.portalUrlTemplate
+    }, new Date(), extra);
+    const html = await renderBookingEmail(kind, lang, context);
+    await email.sendMail({ to, subject: subjectFor(kind, lang), html });
+}

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

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+type Lang = string;
+/** Long pl-PL (or given locale) date; '' for null/invalid. @internal */
+export declare function formatBookingDate(value: unknown, locale?: string): string;
+/** Whole days from `now` to `value`, floored at 0; '' for invalid. @internal */
+export declare function daysUntilDate(value: unknown, now: unknown): string;
+/**
+ * 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 declare function registerBookingPartials(projectDir: string, lang: Lang, fallbackLang: Lang): void;
+/**
+ * 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 declare function renderEmailTemplate(name: string, lang: Lang, context: Record<string, unknown>, opts?: {
+    projectDir?: string;
+    fallbackLang?: Lang;
+}): string;
+export {};