includio-cms 0.36.9 → 0.37.0

package/dist/booking/client/use-booking.svelte.js

@@ -0,0 +1,56 @@
+import { createBookingClient, BookingClientError } from './index.js';
+/**
+ * Reactive self-service portal state for a booking access token. Loads the view
+ * on creation; `edit`/`reload` refresh it, `pay` returns a payment link. Errors
+ * (including `CONTACT_STAFF` 409s) surface via `error`. A `PHONE_REQUIRED` 2FA
+ * gate surfaces via `needsPhone`; call `verifyPhone` to clear it and re-load the
+ * view.
+ *
+ * @public
+ */
+export function useBooking(token, opts = {}) {
+    const client = createBookingClient(opts);
+    let view = $state(null);
+    let loading = $state(false);
+    let error = $state(null);
+    let needsPhone = $state(false);
+    async function run(fn) {
+        loading = true;
+        error = null;
+        try {
+            view = await fn();
+            needsPhone = false;
+        }
+        catch (e) {
+            if (e instanceof BookingClientError && e.code === 'PHONE_REQUIRED') {
+                needsPhone = true;
+            }
+            else {
+                error = e instanceof Error ? e.message : 'Error';
+            }
+        }
+        finally {
+            loading = false;
+        }
+    }
+    run(() => client.getByToken(token));
+    return {
+        get view() {
+            return view;
+        },
+        get loading() {
+            return loading;
+        },
+        get error() {
+            return error;
+        },
+        get needsPhone() {
+            return needsPhone;
+        },
+        reload: () => run(() => client.getByToken(token)),
+        edit: (changes) => run(() => client.edit(token, changes)),
+        pay: (amount) => client.pay(token, amount),
+        verifyPhone: (phone) => run(() => client.verifyPhone(token, phone)),
+        addTrips: (additions) => run(() => client.addTrips(token, additions))
+    };
+}

package/dist/booking/config.d.ts

@@ -0,0 +1,156 @@
+import type { PaymentAdapter } from '../shop/types.js';
+import type { PricingConfig } from './pricing.js';
+import type { ParticipantPricingConfig } from './participant-pricing.js';
+import type { FieldDef, AgeFlagConfig } from './participant-fields/types.js';
+/** One scheduled reminder rule, relative to the earliest departure date. */
+export interface ReminderRule {
+    /** Stable type tag for the reminder (e.g. `pre-departure`). */
+    type: string;
+    /** Whole days before departure to send. */
+    daysBefore: number;
+    /** Email template key to render (see booking email registry). */
+    templateKey: string;
+}
+/** Context handed to the client-supplied {@link BookingValidator} seam. */
+export interface BookingValidationContext {
+    operation: 'create' | 'edit';
+    bookingId: string | null;
+    items: Array<{
+        tripRef: string;
+        departureDate: Date | null;
+        participantsCount: number;
+    }>;
+    customer: Record<string, unknown>;
+}
+/**
+ * Client-specific validation seam (e.g. weekly-model term conflicts). Throws to
+ * reject. The framework only enforces generic capacity + not-below-paid.
+ */
+export type BookingValidator = (ctx: BookingValidationContext) => void | Promise<void>;
+/**
+ * User-facing booking configuration. Passed to `defineBooking` and registered
+ * via `defineConfig({ modules: [defineBooking({...})] })`.
+ *
+ * @public
+ */
+export interface BookingConfig {
+    /** ISO currency code, e.g. `PLN`. */
+    currency: string;
+    /** Slug of the (client-specific) trip catalog collection. Omit when none. */
+    catalogCollection?: string;
+    /**
+     * Dodatkowe kolekcje rdzenia wciągane do kontekstu „Rezerwacje" w adminie (obok katalogu) —
+     * np. kolekcja definiująca typy wypraw i pola uczestnika. Bez tego mieszkają w kontekście
+     * „Treści" i wyglądają jak doszyta kolekcja CMS-a, choć obsługują rezerwacje.
+     *
+     * Wyłącznie prezentacja: nie zmienia danych ani uprawnień.
+     *
+     * @experimental Docelowo moduł będzie wnosił typy wypraw sam (0.38) — patrz ROADMAP.
+     */
+    surfacedCollections?: string[];
+    /** Deposit that secures a reservation, in minor units (default 0). */
+    depositAmount?: number;
+    /** Discount rules (legacy per-line engine; booking now prices per-participant). */
+    pricing?: PricingConfig;
+    /**
+     * Per-participant pricing config (age bands + volume ladder + early-bird) as a
+     * resolver so values can come from an editable CMS singleton (globalSettings).
+     * Called per create/edit. Omit ⇒ no age/volume discounts (everyone full price).
+     */
+    participantPricing?: () => ParticipantPricingConfig | Promise<ParticipantPricingConfig>;
+    /** Customer field holding the arrival date — anchor for age + early-bird + reminders. Default `arrivalDate`. */
+    arrivalDateField?: string;
+    /** Payment adapters (reused from the shop module's adapter family). */
+    payment?: PaymentAdapter[];
+    /**
+     * Portal URL template handed to payment adapters as the post-payment return
+     * URL. Placeholder `{token}` → `booking.accessToken`. Must be absolute, e.g.
+     * `https://shop.example/rezerwacja/{token}`. Omit to disable redirect return.
+     */
+    portalUrlTemplate?: string;
+    /**
+     * Absolute return URL for the CHECKOUT deposit payment (post-payment landing,
+     * e.g. a thank-you page), when it should differ from the portal. Handed to the
+     * adapter as `ctx.continueUrl` for the deposit only; installments/balance keep
+     * `portalUrlTemplate`. Omit ⇒ deposit returns to the portal like other payments.
+     */
+    checkoutReturnUrl?: string;
+    /** Operator address for staff notifications. */
+    adminEmail?: string;
+    /** Business display name shown in transactional email footers; omit for none. */
+    brand?: string;
+    /** Minutes an unpaid draft is held before auto-cancel (default 60). */
+    depositTtlMinutes?: number;
+    /** Days before departure the balance is due; omit to disable forfeiture. */
+    balanceDueDaysBefore?: number;
+    /** Field on the catalog entry holding seat capacity; omit for unlimited. */
+    capacityField?: string;
+    /** Reminder schedule (offsets before departure). */
+    reminders?: ReminderRule[];
+    /** Client-specific validation seam. */
+    validateBooking?: BookingValidator;
+    /** In-process maintenance loop tuning. */
+    maintenance?: {
+        autoRun?: boolean;
+        intervalMinutes?: number;
+    };
+    /** Bearer token guarding the secured maintenance endpoint; omit to disable. */
+    maintenanceToken?: string;
+    /** Sekret HMAC dla sesji portalu (2FA telefonem); omit ⇒ portal fail-closed. */
+    portalSecret?: string;
+    /** Schemat pól uczestnika: statyczny lub resolver per wpis katalogu. */
+    participantFields?: FieldDef[] | ((catalogEntry: Record<string, unknown>) => FieldDef[]);
+    /** Flaga wieku (np. „Dziecko") z pola roli `birthDate` + próg. */
+    ageFlag?: AgeFlagConfig;
+    /**
+     * Opis pól worka `customer` — WYŁĄCZNIE dla prezentacji w adminie. Rdzeń nie zna kształtu
+     * `customer` (definiuje go projekt), więc bez tego panel „Klient" pokazuje uczłowieczone
+     * klucze (`referralSource` → „Referral source"). Podaj `label`, żeby nazwać pola po ludzku,
+     * i `role: 'birthDate'`, żeby rdzeń dopisał wiek obok daty.
+     *
+     * Klucze zagnieżdżone (kolumny tabel, np. manifest osób) adresuje się kropką:
+     * `{ key: 'people.birthDate', label: 'Data urodzenia', role: 'birthDate' }`.
+     *
+     * Nie waliduje ani nie zmienia danych — to czysta warstwa prezentacji.
+     *
+     * @experimental Świadomie NIEPEŁNE: pola uczestnika mają w rdzeniu prawdziwy schemat
+     * (`participantFields` — napędza walidację, render i formularz), a `customer` ma dziś tylko
+     * etykiety, bo formularz kontaktowy jest pisany ręcznie w projekcie. Skutek: worek `customer`
+     * ma DWIE deklaracje (etykiety tutaj, reguły w repo projektu) i może się rozjechać. Domknięcie
+     * w 0.38 — patrz ROADMAP.
+     */
+    customerFields?: FieldDef[];
+}
+/** Fully-defaulted booking config, carried on `CMSModule.config`. */
+export interface ResolvedBookingConfig {
+    currency: string;
+    catalogCollection: string | null;
+    surfacedCollections: string[];
+    depositAmount: number;
+    pricing: PricingConfig;
+    participantPricing: (() => ParticipantPricingConfig | Promise<ParticipantPricingConfig>) | null;
+    arrivalDateField: string;
+    payment: PaymentAdapter[];
+    portalUrlTemplate: string | null;
+    checkoutReturnUrl: string | null;
+    adminEmail: string | null;
+    brand: string | null;
+    depositTtlMinutes: number;
+    balanceDueDaysBefore: number | null;
+    capacityField: string | null;
+    reminders: ReminderRule[];
+    validateBooking: BookingValidator | null;
+    maintenance: {
+        autoRun: boolean;
+        intervalMinutes: number;
+    };
+    maintenanceToken: string | null;
+    portalSecret: string | null;
+    participantFields: FieldDef[] | ((catalogEntry: Record<string, unknown>) => FieldDef[]);
+    ageFlag: AgeFlagConfig | null;
+    customerFields: FieldDef[];
+}
+/** Resolves a raw {@link BookingConfig} into a {@link ResolvedBookingConfig}. */
+export declare function resolveBookingConfig(config: BookingConfig): ResolvedBookingConfig;
+/** Rozwiązuje schemat pól dla danego wpisu katalogu (array lub resolver). */
+export declare function resolveParticipantFields(config: ResolvedBookingConfig, catalogEntry: Record<string, unknown>): FieldDef[];

package/dist/booking/config.js

@@ -0,0 +1,36 @@
+/** Resolves a raw {@link BookingConfig} into a {@link ResolvedBookingConfig}. */
+export function resolveBookingConfig(config) {
+    return {
+        currency: config.currency,
+        catalogCollection: config.catalogCollection ?? null,
+        surfacedCollections: config.surfacedCollections ?? [],
+        depositAmount: config.depositAmount ?? 0,
+        pricing: config.pricing ?? { rules: [] },
+        participantPricing: config.participantPricing ?? null,
+        arrivalDateField: config.arrivalDateField ?? 'arrivalDate',
+        payment: config.payment ?? [],
+        portalUrlTemplate: config.portalUrlTemplate ?? null,
+        checkoutReturnUrl: config.checkoutReturnUrl ?? null,
+        adminEmail: config.adminEmail ?? null,
+        brand: config.brand ?? null,
+        depositTtlMinutes: config.depositTtlMinutes ?? 60,
+        balanceDueDaysBefore: config.balanceDueDaysBefore ?? null,
+        capacityField: config.capacityField ?? null,
+        reminders: config.reminders ?? [],
+        validateBooking: config.validateBooking ?? null,
+        maintenance: {
+            autoRun: config.maintenance?.autoRun ?? true,
+            intervalMinutes: config.maintenance?.intervalMinutes ?? 15
+        },
+        maintenanceToken: config.maintenanceToken ?? null,
+        portalSecret: config.portalSecret ?? null,
+        participantFields: config.participantFields ?? [],
+        ageFlag: config.ageFlag ?? null,
+        customerFields: config.customerFields ?? []
+    };
+}
+/** Rozwiązuje schemat pól dla danego wpisu katalogu (array lub resolver). */
+export function resolveParticipantFields(config, catalogEntry) {
+    const pf = config.participantFields;
+    return typeof pf === 'function' ? pf(catalogEntry) : pf;
+}

package/dist/booking/draft.d.ts

@@ -0,0 +1,77 @@
+import type { ResolvedBookingConfig } from './config.js';
+import { type PricingParticipant, type PricedTrip, type ParticipantPricingConfig } from './participant-pricing.js';
+import { type BookingTotals } from './totals.js';
+import type { FieldDef } from './participant-fields/types.js';
+import type { AppliedRule } from './pricing.js';
+/**
+ * A person on the booking. Identity fields (name, date of birth — the
+ * role:name / role:birthDate participant fields) are entered ONCE and shared
+ * across every trip the person takes. `ref` is a client-stable key used to
+ * correlate the person with their item assignments within a single payload.
+ */
+export interface PersonInput {
+    ref: string;
+    identity: Record<string, unknown>;
+}
+/** Assignment of a person to a trip line, with that person's per-trip answers. */
+export interface ItemAssignmentInput {
+    /** References a {@link PersonInput.ref} in the same payload. */
+    personRef: string;
+    /** Per-trip custom-field answers (trip-type-specific). */
+    data?: Record<string, unknown>;
+}
+/** One requested trip line in a create/edit payload. */
+export interface BookingItemInput {
+    tripRef: string;
+    departureDate: Date | null;
+    /** Unit (adult) price (minor units) snapshotted at booking time. */
+    unitPrice: number;
+    /** Who takes this trip (+ their per-trip data). Count derives from this. */
+    assignments: ItemAssignmentInput[];
+}
+export interface CreateBookingInput {
+    customer: Record<string, unknown>;
+    /** People on the booking (identity, shared across trips). */
+    persons: PersonInput[];
+    items: BookingItemInput[];
+    language?: string;
+}
+/** Per-call pricing context (dynamic: from globalSettings + this booking's customer). */
+export interface DraftPricingContext {
+    participantPricing: ParticipantPricingConfig;
+    /** Arrival date — anchor for age + early-bird. Null ⇒ everyone full price. */
+    anchor: Date | null;
+    /** Identity field schema, used to locate the role:birthDate key for age. */
+    identityFields: FieldDef[];
+}
+export interface BookingDraft {
+    totals: BookingTotals;
+    persons: PersonInput[];
+    items: Array<{
+        tripRef: string;
+        departureDate: Date | null;
+        participantsCount: number;
+        unitPriceSnapshot: number;
+        subtotalSnapshot: number | null;
+        appliedDiscounts: AppliedRule[];
+        assignments: ItemAssignmentInput[];
+    }>;
+    reminders: Array<{
+        type: string;
+        templateKey: string;
+        scheduledFor: Date;
+    }>;
+    balanceDueAt: Date | null;
+    holdExpiresAt: Date;
+}
+/** Build the per-participant pricing inputs from a create payload. */
+export declare function pricingInputsFromCreate(input: CreateBookingInput, identityFields: FieldDef[]): {
+    participants: PricingParticipant[];
+    trips: PricedTrip[];
+};
+/**
+ * Pure: turn a create payload + config + pricing context + clock into the
+ * rows/totals to persist. Prices per-participant (age bands + volume ladder +
+ * early-bird), anchored to the arrival date in `ctx.anchor`.
+ */
+export declare function buildBookingDraft(input: CreateBookingInput, config: ResolvedBookingConfig, ctx: DraftPricingContext, now: Date): BookingDraft;

package/dist/booking/draft.js

@@ -0,0 +1,67 @@
+import { computeBalanceDueAt, computeReminderSchedule } from './reminders-schedule.js';
+import { priceByParticipant } from './participant-pricing.js';
+import { resultToTotals, grossByTripRef } from './totals.js';
+import { NO_ADJUSTMENTS } from './adjustments.js';
+/** Build the per-participant pricing inputs from a create payload. */
+export function pricingInputsFromCreate(input, identityFields) {
+    const dobKey = identityFields.find((f) => f.role === 'birthDate')?.key ?? null;
+    const seen = new Set();
+    const trips = [];
+    for (const it of input.items) {
+        if (seen.has(it.tripRef))
+            continue;
+        seen.add(it.tripRef);
+        trips.push({ ref: it.tripRef, adultPrice: it.unitPrice });
+    }
+    const tripsByPersonRef = new Map();
+    for (const it of input.items) {
+        for (const a of it.assignments) {
+            const list = tripsByPersonRef.get(a.personRef);
+            if (list) {
+                if (!list.includes(it.tripRef))
+                    list.push(it.tripRef);
+            }
+            else {
+                tripsByPersonRef.set(a.personRef, [it.tripRef]);
+            }
+        }
+    }
+    const participants = input.persons.map((p) => {
+        const dobRaw = dobKey ? p.identity[dobKey] : null;
+        return {
+            id: p.ref,
+            dob: typeof dobRaw === 'string' ? dobRaw : null,
+            tripRefs: tripsByPersonRef.get(p.ref) ?? []
+        };
+    });
+    return { participants, trips };
+}
+/**
+ * Pure: turn a create payload + config + pricing context + clock into the
+ * rows/totals to persist. Prices per-participant (age bands + volume ladder +
+ * early-bird), anchored to the arrival date in `ctx.anchor`.
+ */
+export function buildBookingDraft(input, config, ctx, now) {
+    const dates = input.items.map((it) => it.departureDate);
+    const { participants, trips } = pricingInputsFromCreate(input, ctx.identityFields);
+    const result = priceByParticipant(participants, trips, ctx.anchor, now, ctx.participantPricing);
+    const totals = resultToTotals(result, NO_ADJUSTMENTS, 0);
+    const subtotalByRef = grossByTripRef(result);
+    const items = input.items.map((it) => ({
+        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),
+        assignments: it.assignments
+    }));
+    return {
+        totals,
+        persons: input.persons,
+        items,
+        reminders: computeReminderSchedule(dates, config.reminders),
+        balanceDueAt: computeBalanceDueAt(dates, config.balanceDueDaysBefore),
+        holdExpiresAt: new Date(now.getTime() + config.depositTtlMinutes * 60_000)
+    };
+}

package/dist/booking/expiry-logic.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Pure decision helpers for the booking maintenance cron. No clock/db access —
+ * the caller passes `now` and the rows. Tested in isolation; the DB wrappers in
+ * `server/maintenance.ts` just fetch rows and apply the results.
+ */
+import type { BookingStatus } from './state-machine.js';
+/** Ids of reminders that are due to send (unsent and `scheduledFor <= now`). */
+export declare function selectDueReminders(rows: Array<{
+    id: string;
+    scheduledFor: Date;
+    sentAt: Date | null;
+}>, now: Date): string[];
+/**
+ * Partition active bookings into those to auto-cancel:
+ *  - `abandon`: a `draft` whose deposit hold (`holdExpiresAt`) has lapsed.
+ *  - `forfeit`: any non-terminal booking past `balanceDueAt` with balance left
+ *    (deposit forfeited). `paid`/`completed`/`cancelled` are skipped.
+ */
+export declare function decideExpirations(bookings: Array<{
+    id: string;
+    status: BookingStatus;
+    holdExpiresAt: Date | null;
+    balanceDueAt: Date | null;
+    totals: {
+        balance: number;
+    };
+}>, now: Date): {
+    abandon: string[];
+    forfeit: string[];
+};

package/dist/booking/expiry-logic.js

@@ -0,0 +1,33 @@
+/**
+ * Pure decision helpers for the booking maintenance cron. No clock/db access —
+ * the caller passes `now` and the rows. Tested in isolation; the DB wrappers in
+ * `server/maintenance.ts` just fetch rows and apply the results.
+ */
+/** Ids of reminders that are due to send (unsent and `scheduledFor <= now`). */
+export function selectDueReminders(rows, now) {
+    return rows
+        .filter((r) => r.sentAt == null && r.scheduledFor.getTime() <= now.getTime())
+        .map((r) => r.id);
+}
+/**
+ * Partition active bookings into those to auto-cancel:
+ *  - `abandon`: a `draft` whose deposit hold (`holdExpiresAt`) has lapsed.
+ *  - `forfeit`: any non-terminal booking past `balanceDueAt` with balance left
+ *    (deposit forfeited). `paid`/`completed`/`cancelled` are skipped.
+ */
+export function decideExpirations(bookings, now) {
+    const abandon = [];
+    const forfeit = [];
+    for (const b of bookings) {
+        if (b.status === 'cancelled' || b.status === 'completed' || b.status === 'paid')
+            continue;
+        if (b.status === 'draft' && b.holdExpiresAt && b.holdExpiresAt.getTime() <= now.getTime()) {
+            abandon.push(b.id);
+            continue;
+        }
+        if (b.balanceDueAt && b.balanceDueAt.getTime() <= now.getTime() && b.totals.balance > 0) {
+            forfeit.push(b.id);
+        }
+    }
+    return { abandon, forfeit };
+}

package/dist/booking/index.d.ts

@@ -0,0 +1,18 @@
+import type { CMSModule } from '../types/modules.js';
+import { type BookingConfig } from './config.js';
+/**
+ * Defines the booking module — a long-lived, mutable reservation system with a
+ * payment ledger, layered on the CMS core as a {@link CMSModule}. The resolved
+ * config is reachable via `getCMS().getModuleConfig('booking')`.
+ *
+ * @public
+ */
+export declare function defineBooking(config: BookingConfig): CMSModule;
+export { type BookingConfig, type ResolvedBookingConfig, type ReminderRule, type BookingValidator, type BookingValidationContext } from './config.js';
+export { price, daysUntil, type Condition, type Effect, type DiscountRule, type PricingConfig, type PricingLine, type AppliedRule, type Perk, type PriceResult } from './pricing.js';
+export { priceByParticipant, bandPctFor, ladderTierFor, type AgeBand, type LadderTier, type EarlyBird, type ParticipantPricingConfig, type PricedTrip, type PricingParticipant, type ParticipantLine, type ParticipantBreakdown, type ParticipantPriceResult } from './participant-pricing.js';
+export { buildPricingInputs, type PersonRow, type ItemRow, type ItemPersonRow, type PricingInputs } from './pricing-inputs.js';
+export { deriveStatus, canTransition, assertTransition, BookingStateError, BOOKING_STATUSES, type BookingStatus } from './state-machine.js';
+export { signedAmount, sumAdjustments, assertAdjustmentMagnitude, NO_ADJUSTMENTS, type AdjustmentKind, type BookingAdjustment, type AdjustmentSums } from './adjustments.js';
+export { totalPaid, totalRefunded, totalPending, balance, isFullyPaid, canReduceGrossTo, assertGrossNotBelowPaid, ledgerSummary, LedgerError, type PaymentEntry, type PaymentKind, type PaymentStatus, type LedgerSummary } from './ledger.js';
+export * from './participant-fields/index.js';

package/dist/booking/index.js

@@ -0,0 +1,52 @@
+import { resolveBookingConfig } from './config.js';
+/**
+ * Defines the booking module — a long-lived, mutable reservation system with a
+ * payment ledger, layered on the CMS core as a {@link CMSModule}. The resolved
+ * config is reachable via `getCMS().getModuleConfig('booking')`.
+ *
+ * @public
+ */
+export function defineBooking(config) {
+    const resolved = resolveBookingConfig(config);
+    // Katalog + kolekcje wspierające booking (np. typy wypraw definiujące pola uczestnika).
+    // Pusta lista ⇒ `undefined`, żeby nie zmieniać semantyki „brak wciągniętych kolekcji".
+    const surfaced = [
+        ...(resolved.catalogCollection ? [resolved.catalogCollection] : []),
+        ...resolved.surfacedCollections
+    ];
+    return {
+        id: 'booking',
+        label: { pl: 'Rezerwacje', en: 'Bookings' },
+        icon: 'calendar',
+        context: {
+            contextLabel: { pl: 'Rezerwacje', en: 'Bookings' },
+            landingUrl: '/admin/booking',
+            sections: [
+                {
+                    key: 'reservations',
+                    title: { pl: 'Rezerwacje', en: 'Reservations' },
+                    url: '/admin/booking/reservations',
+                    icon: 'clipboard-list'
+                }
+            ],
+            surfacedCollections: surfaced.length > 0 ? surfaced : undefined
+        },
+        config: resolved,
+        serverHooks: {
+            // A plain string, NOT an inline import: this barrel is client-safe (re-exported
+            // via `includio-cms/booking`), and inlining `import('./server/...')` here makes
+            // client bundlers pull server-only code (node:fs/url via the email template
+            // registry) and break browser builds. `initCMS` (server-only) imports this
+            // specifier at runtime and runs its `serverInit` — see ModuleServerHooks.initModule.
+            initModule: 'includio-cms/booking/server'
+        }
+    };
+}
+export {} from './config.js';
+export { price, daysUntil } from './pricing.js';
+export { priceByParticipant, bandPctFor, ladderTierFor } from './participant-pricing.js';
+export { buildPricingInputs } from './pricing-inputs.js';
+export { deriveStatus, canTransition, assertTransition, BookingStateError, BOOKING_STATUSES } from './state-machine.js';
+export { signedAmount, sumAdjustments, assertAdjustmentMagnitude, NO_ADJUSTMENTS } from './adjustments.js';
+export { totalPaid, totalRefunded, totalPending, balance, isFullyPaid, canReduceGrossTo, assertGrossNotBelowPaid, ledgerSummary, LedgerError } from './ledger.js';
+export * from './participant-fields/index.js';

package/dist/booking/ledger.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Booking payment ledger — pure helpers over a list of payment entries. The
+ * ledger is the source of truth for "how much is paid"; the booking status is
+ * {@link import('./state-machine.js').deriveStatus | derived} from the balance.
+ *
+ * All amounts are in **minor units** (grosze).
+ */
+export type PaymentKind = 'deposit' | 'installment' | 'cash' | 'online';
+export type PaymentStatus = 'pending' | 'paid' | 'failed' | 'refunded';
+export interface PaymentEntry {
+    amount: number;
+    status: PaymentStatus;
+    kind?: PaymentKind;
+}
+/** Thrown when an edit would push the gross below what has already been paid. */
+export declare class LedgerError extends Error {
+    constructor(message: string);
+}
+/** Sum of entries currently in `paid` state. */
+export declare function totalPaid(payments: PaymentEntry[]): number;
+/** Sum of entries that were refunded. */
+export declare function totalRefunded(payments: PaymentEntry[]): number;
+/** Sum of entries still pending (links generated, not yet settled). */
+export declare function totalPending(payments: PaymentEntry[]): number;
+/** Outstanding balance: `gross − paid` (never below 0). */
+export declare function balance(gross: number, payments: PaymentEntry[]): number;
+/** Whether the booking is fully settled (`gross > 0` and balance reached 0). */
+export declare function isFullyPaid(gross: number, payments: PaymentEntry[]): boolean;
+/** Whether the gross may be reduced to `newGross` without going below paid. */
+export declare function canReduceGrossTo(newGross: number, payments: PaymentEntry[]): boolean;
+/**
+ * Asserts an edit's new gross does not drop below the already-paid total.
+ * @throws {LedgerError} when `newGross < totalPaid`.
+ */
+export declare function assertGrossNotBelowPaid(newGross: number, payments: PaymentEntry[]): void;
+export interface LedgerSummary {
+    gross: number;
+    paid: number;
+    pending: number;
+    refunded: number;
+    balance: number;
+    /** Amount paid beyond gross (e.g. after a downward edit), 0 when none. */
+    overpaid: number;
+}
+/** Full ledger snapshot for a given gross. */
+export declare function ledgerSummary(gross: number, payments: PaymentEntry[]): LedgerSummary;

package/dist/booking/ledger.js

@@ -0,0 +1,60 @@
+/**
+ * Booking payment ledger — pure helpers over a list of payment entries. The
+ * ledger is the source of truth for "how much is paid"; the booking status is
+ * {@link import('./state-machine.js').deriveStatus | derived} from the balance.
+ *
+ * All amounts are in **minor units** (grosze).
+ */
+/** Thrown when an edit would push the gross below what has already been paid. */
+export class LedgerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LedgerError';
+    }
+}
+/** Sum of entries currently in `paid` state. */
+export function totalPaid(payments) {
+    return payments.reduce((sum, p) => (p.status === 'paid' ? sum + p.amount : sum), 0);
+}
+/** Sum of entries that were refunded. */
+export function totalRefunded(payments) {
+    return payments.reduce((sum, p) => (p.status === 'refunded' ? sum + p.amount : sum), 0);
+}
+/** Sum of entries still pending (links generated, not yet settled). */
+export function totalPending(payments) {
+    return payments.reduce((sum, p) => (p.status === 'pending' ? sum + p.amount : sum), 0);
+}
+/** Outstanding balance: `gross − paid` (never below 0). */
+export function balance(gross, payments) {
+    return Math.max(0, gross - totalPaid(payments));
+}
+/** Whether the booking is fully settled (`gross > 0` and balance reached 0). */
+export function isFullyPaid(gross, payments) {
+    return gross > 0 && totalPaid(payments) >= gross;
+}
+/** Whether the gross may be reduced to `newGross` without going below paid. */
+export function canReduceGrossTo(newGross, payments) {
+    return newGross >= totalPaid(payments);
+}
+/**
+ * Asserts an edit's new gross does not drop below the already-paid total.
+ * @throws {LedgerError} when `newGross < totalPaid`.
+ */
+export function assertGrossNotBelowPaid(newGross, payments) {
+    const paid = totalPaid(payments);
+    if (newGross < paid) {
+        throw new LedgerError(`Cannot set gross to ${newGross}: already paid ${paid} (would owe a refund of ${paid - newGross}).`);
+    }
+}
+/** Full ledger snapshot for a given gross. */
+export function ledgerSummary(gross, payments) {
+    const paid = totalPaid(payments);
+    return {
+        gross,
+        paid,
+        pending: totalPending(payments),
+        refunded: totalRefunded(payments),
+        balance: Math.max(0, gross - paid),
+        overpaid: Math.max(0, paid - gross)
+    };
+}

package/dist/booking/number.d.ts

@@ -0,0 +1,2 @@
+/** Random `BK-XXXXX` booking number (~25 bits). Caller retries on UNIQUE collision. */
+export declare function generateBookingNumber(): string;

package/dist/booking/number.js

@@ -0,0 +1,11 @@
+// Crockford base32 alphabet — unambiguous (no I, L, O, U).
+const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+/** Random `BK-XXXXX` booking number (~25 bits). Caller retries on UNIQUE collision. */
+export function generateBookingNumber() {
+    const bytes = new Uint8Array(5);
+    crypto.getRandomValues(bytes);
+    let out = '';
+    for (let i = 0; i < 5; i++)
+        out += ALPHABET[bytes[i] % 32];
+    return `BK-${out}`;
+}

package/dist/booking/participant-fields/access.d.ts

@@ -0,0 +1,10 @@
+import type { FieldDef } from './types.js';
+/**
+ * Whether a given audience may fill/edit a field. Default `whoFills` is `'both'`.
+ *
+ * Staff (admin) is **privileged** — it may edit every field regardless of
+ * `whoFills` (operators must always be able to correct/complete any datum).
+ * `whoFills` therefore only gates the **customer/portal** side: a `'staff'`
+ * field is simply hidden from the portal, not locked away from the operator.
+ */
+export declare function canFill(field: FieldDef, audience: 'customer' | 'staff'): boolean;