includio-cms 0.36.9 → 0.37.0

package/dist/booking/pricing.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Booking discount rules engine — a pure, deterministic, module-agnostic
+ * function. No side effects, no clock access (the caller passes `now`).
+ *
+ * A rule is serializable data (`when` conditions → `then` effects). Rules carry
+ * an optional `group`: within a group the single largest-discount rule wins;
+ * across groups discounts sum. Amounts are in **minor units** (grosze).
+ */
+/** A condition; all conditions in a rule's `when` must hold (logical AND). */
+export type Condition = {
+    kind: 'minTripCount';
+    value: number;
+} | {
+    kind: 'minParticipants';
+    value: number;
+} | {
+    kind: 'minDaysBefore';
+    value: number;
+};
+/** An effect applied when a rule wins its group. */
+export type Effect = {
+    kind: 'percentOff';
+    value: number;
+} | {
+    kind: 'amountOff';
+    value: number;
+} | {
+    kind: 'percentOffCheapestLine';
+    value: number;
+} | {
+    kind: 'grantPerk';
+    label: string;
+    code?: string;
+};
+/** A serializable discount rule. */
+export interface DiscountRule {
+    /** Stable id (labels, audit, future UI). */
+    id: string;
+    /** Human label for admin/portal/email; defaults to `id`. */
+    label?: string;
+    /** Exclusivity group; rules in the same group compete (one wins). Omitted ⇒ own singleton group. */
+    group?: string;
+    /** Tiebreak within a group when discount amounts are equal (higher wins). Default 0. */
+    priority?: number;
+    when: Condition[];
+    then: Effect[];
+}
+export interface PricingConfig {
+    rules?: DiscountRule[];
+}
+/** A single priced line that retains trip identity (for cheapest/distinct-count). */
+export interface PricingLine {
+    /** Trip reference — identity for distinct-count and discount targeting. */
+    ref: string;
+    /** Unit price (minor units), per participant. */
+    unitPrice: number;
+    /** Participant count on this line. */
+    quantity: number;
+    /** Departure date — drives early-bird (earliest across lines). */
+    departureDate: Date | null;
+    /** Precomputed line gross (minor units); overrides unitPrice*quantity when set. */
+    subtotal?: number;
+}
+export interface AppliedRule {
+    ruleId: string;
+    /** Human label (rule.label ?? rule.id). */
+    label: string;
+    /** Monetary discount contributed, in minor units. */
+    amount: number;
+    /** Line `ref` this discount targets (set for line-targeted effects only). */
+    targetRef?: string;
+}
+export interface Perk {
+    code?: string;
+    label: string;
+}
+export interface PriceResult {
+    gross: number;
+    discountTotal: number;
+    net: number;
+    appliedRules: AppliedRule[];
+    perks: Perk[];
+}
+/** Whole days from `now` until `departureDate` (negative if departure is past). */
+export declare function daysUntil(departureDate: Date, now: Date): number;
+export declare function price(lines: PricingLine[], now: Date, config: PricingConfig): PriceResult;

package/dist/booking/pricing.js

@@ -0,0 +1,125 @@
+/**
+ * Booking discount rules engine — a pure, deterministic, module-agnostic
+ * function. No side effects, no clock access (the caller passes `now`).
+ *
+ * A rule is serializable data (`when` conditions → `then` effects). Rules carry
+ * an optional `group`: within a group the single largest-discount rule wins;
+ * across groups discounts sum. Amounts are in **minor units** (grosze).
+ */
+const MS_PER_DAY = 86_400_000;
+/** Whole days from `now` until `departureDate` (negative if departure is past). */
+export function daysUntil(departureDate, now) {
+    return Math.floor((departureDate.getTime() - now.getTime()) / MS_PER_DAY);
+}
+function conditionHolds(c, ctx) {
+    switch (c.kind) {
+        case 'minTripCount':
+            return ctx.distinctTrips >= c.value;
+        case 'minParticipants':
+            return ctx.totalQty >= c.value;
+        case 'minDaysBefore':
+            return ctx.daysBefore >= c.value;
+    }
+}
+/** Monetary amount of an effect, clamped to [0, gross]; null for non-monetary effects. */
+function effectMonetary(e, ctx) {
+    switch (e.kind) {
+        case 'percentOff':
+            return { amount: Math.max(0, Math.min(ctx.gross, Math.round((ctx.gross * e.value) / 100))) };
+        case 'amountOff':
+            return { amount: Math.max(0, Math.min(ctx.gross, Math.round(e.value))) };
+        case 'percentOffCheapestLine': {
+            if (!ctx.cheapest)
+                return null;
+            const amt = Math.round((ctx.cheapest.total * e.value) / 100);
+            return { amount: Math.max(0, Math.min(ctx.gross, amt)), targetRef: ctx.cheapest.ref };
+        }
+        case 'grantPerk':
+            return null;
+    }
+}
+/**
+ * Prices a set of lines against discount rules.
+ *
+ * @param lines - Priced lines retaining trip identity (minor units).
+ * @param now - Reference "current" time (injected for determinism).
+ * @param config - Discount rules (values from client config).
+ */
+/** Line gross: explicit subtotal when provided, else unitPrice * quantity. */
+function lineTotal(l) {
+    return l.subtotal ?? l.unitPrice * l.quantity;
+}
+export function price(lines, now, config) {
+    const gross = lines.reduce((s, l) => s + lineTotal(l), 0);
+    const totalQty = lines.reduce((s, l) => s + l.quantity, 0);
+    const distinctTrips = new Set(lines.map((l) => l.ref)).size;
+    const dated = lines.map((l) => l.departureDate).filter((d) => d instanceof Date);
+    const basis = dated.length ? new Date(Math.min(...dated.map((d) => d.getTime()))) : now;
+    const daysBefore = daysUntil(basis, now);
+    let cheapest = null;
+    for (const l of lines) {
+        const total = lineTotal(l);
+        if (!cheapest || total < cheapest.total)
+            cheapest = { ref: l.ref, total };
+    }
+    const ctx = { gross, totalQty, distinctTrips, daysBefore, cheapest };
+    // Eligible rules, preserving declaration order.
+    const eligible = (config.rules ?? [])
+        .map((r, i) => ({ r, i }))
+        .filter(({ r }) => r.when.every((c) => conditionHolds(c, ctx)));
+    // Bucket by exclusivity group (omitted group ⇒ unique singleton).
+    const groups = new Map();
+    for (const e of eligible) {
+        const key = e.r.group ?? `__single__${e.i}`;
+        const bucket = groups.get(key);
+        if (bucket)
+            bucket.push(e);
+        else
+            groups.set(key, [e]);
+    }
+    const appliedRules = [];
+    const perks = [];
+    for (const members of groups.values()) {
+        const evaluated = members.map(({ r, i }) => {
+            const effects = r.then.map((e) => ({ e, m: effectMonetary(e, ctx) }));
+            const monetary = effects.reduce((s, x) => s + (x.m?.amount ?? 0), 0);
+            return { r, i, effects, monetary };
+        });
+        // Winner: largest monetary, tie → higher priority, tie → earlier order.
+        evaluated.sort((a, b) => b.monetary - a.monetary || (b.r.priority ?? 0) - (a.r.priority ?? 0) || a.i - b.i);
+        const winner = evaluated[0];
+        if (!winner)
+            continue;
+        for (const { e, m } of winner.effects) {
+            if (e.kind === 'grantPerk') {
+                perks.push({ code: e.code, label: e.label });
+            }
+            else if (m && m.amount > 0) {
+                const ar = {
+                    ruleId: winner.r.id,
+                    label: winner.r.label ?? winner.r.id,
+                    amount: m.amount
+                };
+                if (m.targetRef)
+                    ar.targetRef = m.targetRef;
+                appliedRules.push(ar);
+            }
+        }
+    }
+    const discountTotal = Math.min(gross, appliedRules.reduce((s, a) => s + a.amount, 0));
+    const seen = new Set();
+    const dedupedPerks = perks.filter((p) => {
+        const k = p.code ?? p.label;
+        if (seen.has(k))
+            return false;
+        seen.add(k);
+        return true;
+    });
+    return {
+        gross,
+        discountTotal,
+        net: Math.max(0, gross - discountTotal),
+        appliedRules,
+        perks: dedupedPerks
+    };
+}

package/dist/booking/recompute.d.ts

@@ -0,0 +1,22 @@
+import { type PaymentEntry } from './ledger.js';
+import { type BookingTotals } from './totals.js';
+import type { ParticipantPriceResult } from './participant-pricing.js';
+import type { AdjustmentSums } from './adjustments.js';
+import type { BookingStatus } from './state-machine.js';
+/** Thrown when an edit is not allowed (terminal booking). */
+export declare class BookingEditError extends Error {
+    constructor(message: string);
+}
+/**
+ * Pure recompute of a booking's money snapshot after an edit. Takes the
+ * already-computed per-participant pricing result (the caller prices from the
+ * edited or existing people/items) and folds in payments.
+ */
+export declare function recomputeTotals(result: ParticipantPriceResult, sums: AdjustmentSums, payments: PaymentEntry[]): BookingTotals;
+/** Block edits to terminal bookings (cancelled/completed). */
+export declare function assertEditAllowed(status: BookingStatus): void;
+/**
+ * Portal (self-service) edit guard: block terminal bookings AND any edit that
+ * would drop the gross below what's already paid (would owe a refund → staff).
+ */
+export declare function assertPortalEditAllowed(status: BookingStatus, newGross: number, payments: PaymentEntry[]): void;

package/dist/booking/recompute.js

@@ -0,0 +1,31 @@
+import { totalPaid, assertGrossNotBelowPaid } from './ledger.js';
+import { resultToTotals } from './totals.js';
+/** Thrown when an edit is not allowed (terminal booking). */
+export class BookingEditError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BookingEditError';
+    }
+}
+/**
+ * Pure recompute of a booking's money snapshot after an edit. Takes the
+ * already-computed per-participant pricing result (the caller prices from the
+ * edited or existing people/items) and folds in payments.
+ */
+export function recomputeTotals(result, sums, payments) {
+    return resultToTotals(result, sums, totalPaid(payments));
+}
+/** Block edits to terminal bookings (cancelled/completed). */
+export function assertEditAllowed(status) {
+    if (status === 'cancelled' || status === 'completed') {
+        throw new BookingEditError(`Cannot edit a ${status} booking`);
+    }
+}
+/**
+ * Portal (self-service) edit guard: block terminal bookings AND any edit that
+ * would drop the gross below what's already paid (would owe a refund → staff).
+ */
+export function assertPortalEditAllowed(status, newGross, payments) {
+    assertEditAllowed(status);
+    assertGrossNotBelowPaid(newGross, payments); // throws LedgerError when newGross < paid
+}

package/dist/booking/reminders-schedule.d.ts

@@ -0,0 +1,11 @@
+import type { ReminderRule } from './config.js';
+/** The earliest non-null departure across booking items, or null when none. */
+export declare function earliestDeparture(dates: Array<Date | null>): Date | null;
+/** Balance-due deadline = earliest departure − `balanceDueDaysBefore`; null if unconfigured. */
+export declare function computeBalanceDueAt(dates: Array<Date | null>, balanceDueDaysBefore: number | null): Date | null;
+/** One scheduled-reminder row per rule, anchored to the earliest departure. */
+export declare function computeReminderSchedule(dates: Array<Date | null>, rules: ReminderRule[]): Array<{
+    type: string;
+    templateKey: string;
+    scheduledFor: Date;
+}>;

package/dist/booking/reminders-schedule.js

@@ -0,0 +1,28 @@
+const MS_PER_DAY = 86_400_000;
+/** The earliest non-null departure across booking items, or null when none. */
+export function earliestDeparture(dates) {
+    const valid = dates.filter((d) => d instanceof Date);
+    if (valid.length === 0)
+        return null;
+    return valid.reduce((min, d) => (d.getTime() < min.getTime() ? d : min));
+}
+/** Balance-due deadline = earliest departure − `balanceDueDaysBefore`; null if unconfigured. */
+export function computeBalanceDueAt(dates, balanceDueDaysBefore) {
+    if (balanceDueDaysBefore == null)
+        return null;
+    const dep = earliestDeparture(dates);
+    if (!dep)
+        return null;
+    return new Date(dep.getTime() - balanceDueDaysBefore * MS_PER_DAY);
+}
+/** One scheduled-reminder row per rule, anchored to the earliest departure. */
+export function computeReminderSchedule(dates, rules) {
+    const dep = earliestDeparture(dates);
+    if (!dep || rules.length === 0)
+        return [];
+    return rules.map((r) => ({
+        type: r.type,
+        templateKey: r.templateKey,
+        scheduledFor: new Date(dep.getTime() - r.daysBefore * MS_PER_DAY)
+    }));
+}

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>;