@voyantjs/bookings 0.119.2 → 0.119.3

package/dist/pricing-assignment/age.d.ts

@@ -0,0 +1,33 @@
+import type { AssignmentRoleHint, BookingDraftTraveler, PricingAssignmentUnit, TravelerRole } from "./types.js";
+/**
+ * Compute integer age in full years from an ISO date-of-birth string.
+ * Returns null when the DOB is missing or unparseable.
+ */
+export declare function computeAgeYears(dob: string | null, now?: Date): number | null;
+/**
+ * Derive the age-banded traveler category from DOB + role hint.
+ * DOB-derived age wins; role hint is the fallback for travelers
+ * added before the operator filled in a birthday.
+ */
+export declare function deriveDraftPaxBand(traveler: Pick<BookingDraftTraveler, "dateOfBirth" | "role">, now?: Date): "adult" | "child" | "infant" | null;
+/**
+ * Pick the unit for a traveler pricing band. Priorities:
+ *   1. DOB-derived age that falls into a unit's `[minAge, maxAge]`
+ *   2. Role hint mapped to a representative age (infant→1, child→8,
+ *      adult→30) matched against bands. Works for products coded
+ *      `child_0_5` / `child_6_12` (not just literal `INFANT`/`CHILD`).
+ *   3. Code/name matching for legacy products with no min/max set.
+ */
+export declare function pickUnitForAge<TUnit extends PricingAssignmentUnit>(units: ReadonlyArray<TUnit>, age: number | null, roleHint?: AssignmentRoleHint | null): TUnit | undefined;
+/**
+ * Find the unit whose `[minAge, maxAge]` contains the DOB-derived
+ * age. Used by the UI to pre-pick a unit when a traveler attaches.
+ */
+export declare function matchUnitByDob<TUnit extends PricingAssignmentUnit>(units: ReadonlyArray<TUnit>, dob: string | null): string | null;
+/**
+ * Find the unit matching a role hint when DOB is missing. Same
+ * HINT_AGE mapping as `pickUnitForAge`. Returns null when the role
+ * carries no age signal (e.g. `lead`).
+ */
+export declare function matchUnitByRoleHint<TUnit extends PricingAssignmentUnit>(units: ReadonlyArray<TUnit>, role: TravelerRole | null): string | null;
+//# sourceMappingURL=age.d.ts.map

package/dist/pricing-assignment/age.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"age.d.ts","sourceRoot":"","sources":["../../src/pricing-assignment/age.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,YAAY,EACb,MAAM,YAAY,CAAA;AAEnB;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAUzF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,IAAI,CAAC,oBAAoB,EAAE,aAAa,GAAG,MAAM,CAAC,EAC5D,GAAG,GAAE,IAAiB,GACrB,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,IAAI,CAUrC;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,SAAS,qBAAqB,EAChE,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,EAC3B,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,QAAQ,GAAE,kBAAkB,GAAG,IAAW,GACzC,KAAK,GAAG,SAAS,CAoCnB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,SAAS,qBAAqB,EAChE,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,EAC3B,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB,MAAM,GAAG,IAAI,CASf;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,SAAS,qBAAqB,EACrE,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,EAC3B,IAAI,EAAE,YAAY,GAAG,IAAI,GACxB,MAAM,GAAG,IAAI,CAiBf"}

package/dist/pricing-assignment/age.js

@@ -0,0 +1,109 @@
+/**
+ * Compute integer age in full years from an ISO date-of-birth string.
+ * Returns null when the DOB is missing or unparseable.
+ */
+export function computeAgeYears(dob, now = new Date()) {
+    if (!dob)
+        return null;
+    const birth = new Date(dob);
+    if (Number.isNaN(birth.getTime()))
+        return null;
+    let age = now.getFullYear() - birth.getFullYear();
+    const beforeBirthday = now.getMonth() < birth.getMonth() ||
+        (now.getMonth() === birth.getMonth() && now.getDate() < birth.getDate());
+    if (beforeBirthday)
+        age -= 1;
+    return age >= 0 ? age : null;
+}
+/**
+ * Derive the age-banded traveler category from DOB + role hint.
+ * DOB-derived age wins; role hint is the fallback for travelers
+ * added before the operator filled in a birthday.
+ */
+export function deriveDraftPaxBand(traveler, now = new Date()) {
+    const age = computeAgeYears(traveler.dateOfBirth, now);
+    if (age == null) {
+        return traveler.role === "adult" || traveler.role === "child" || traveler.role === "infant"
+            ? traveler.role
+            : null;
+    }
+    if (age < 2)
+        return "infant";
+    if (age < 18)
+        return "child";
+    return "adult";
+}
+/**
+ * Pick the unit for a traveler pricing band. Priorities:
+ *   1. DOB-derived age that falls into a unit's `[minAge, maxAge]`
+ *   2. Role hint mapped to a representative age (infant→1, child→8,
+ *      adult→30) matched against bands. Works for products coded
+ *      `child_0_5` / `child_6_12` (not just literal `INFANT`/`CHILD`).
+ *   3. Code/name matching for legacy products with no min/max set.
+ */
+export function pickUnitForAge(units, age, roleHint = null) {
+    if (units.length === 0)
+        return undefined;
+    const personUnits = units.filter((u) => u.unitType == null || u.unitType === "person");
+    const pool = personUnits.length > 0 ? personUnits : units;
+    const sorted = [...pool].sort((a, b) => (a.minAge ?? 0) - (b.minAge ?? 0));
+    const matchByAge = (target) => sorted.find((u) => (u.minAge == null || target >= u.minAge) && (u.maxAge == null || target <= u.maxAge));
+    if (age != null) {
+        const match = matchByAge(age);
+        if (match)
+            return match;
+    }
+    if (roleHint) {
+        const HINT_AGE = { adult: 30, child: 8, infant: 1 };
+        const hintAge = HINT_AGE[roleHint];
+        // Only consider units with at least one explicit age bound.
+        // Without this, legacy units with null min/max (just bare
+        // ADULT/CHILD codes) would all match every hint age and collapse
+        // onto the first sorted entry. Code-matching below handles those.
+        const banded = sorted.filter((u) => u.minAge != null || u.maxAge != null);
+        const match = banded.find((u) => (u.minAge == null || hintAge >= u.minAge) && (u.maxAge == null || hintAge <= u.maxAge));
+        if (match)
+            return match;
+    }
+    const findByCode = (code) => sorted.find((u) => (u.unitCode ?? "").toUpperCase() === code) ??
+        sorted.find((u) => new RegExp(`\\b${code}\\b`, "i").test(u.unitName));
+    if (roleHint === "child")
+        return findByCode("CHILD") ?? sorted[0];
+    if (roleHint === "infant")
+        return findByCode("INFANT") ?? sorted[0];
+    return findByCode("ADULT") ?? sorted[sorted.length - 1] ?? sorted[0];
+}
+/**
+ * Find the unit whose `[minAge, maxAge]` contains the DOB-derived
+ * age. Used by the UI to pre-pick a unit when a traveler attaches.
+ */
+export function matchUnitByDob(units, dob) {
+    if (!dob)
+        return null;
+    const age = computeAgeYears(dob);
+    if (age == null)
+        return null;
+    const personUnits = units.filter((u) => u.unitType == null || u.unitType === "person");
+    const match = personUnits.find((u) => (u.minAge == null || age >= u.minAge) && (u.maxAge == null || age <= u.maxAge));
+    return match?.optionUnitId ?? null;
+}
+/**
+ * Find the unit matching a role hint when DOB is missing. Same
+ * HINT_AGE mapping as `pickUnitForAge`. Returns null when the role
+ * carries no age signal (e.g. `lead`).
+ */
+export function matchUnitByRoleHint(units, role) {
+    if (!role || role === "lead")
+        return null;
+    const HINT_AGE = {
+        adult: 30,
+        child: 8,
+        infant: 1,
+    };
+    const hintAge = HINT_AGE[role];
+    if (hintAge == null)
+        return null;
+    const banded = units.filter((u) => (u.unitType == null || u.unitType === "person") && (u.minAge != null || u.maxAge != null));
+    const match = banded.find((u) => (u.minAge == null || hintAge >= u.minAge) && (u.maxAge == null || hintAge <= u.maxAge));
+    return match?.optionUnitId ?? null;
+}

package/dist/pricing-assignment/draft.d.ts

@@ -0,0 +1,69 @@
+import type { BookingDraftQuantities, BookingDraftTraveler, PricingAssignmentUnit, ResolvableExtraLine, ResolvedBookingDraft } from "./types.js";
+/**
+ * Resolve a booking-create draft into the per-unit quantities and
+ * per-traveler unit assignments the submit pipeline + price preview
+ * both need. Single source of truth for traveler→unit mapping.
+ *
+ * Shape branching:
+ *   - **Person-priced options** (only `person` units, no `room`):
+ *     quantities are derived from traveler assignments (1 adult + 1
+ *     child + 1 infant = 3 line items, not "3 x Adult"). Auto-source
+ *     travelers are re-derived against the current option's bands.
+ *   - **Accommodation options** (any `room` unit): operator-picked
+ *     stepper quantities are preserved (1 DBL room is 1 line). Per-
+ *     traveler room assignments still update `travelerIndexesByUnitId`
+ *     so `booking_item_travelers` rows can be created.
+ *
+ * Respects assignment sources:
+ *   - `none` → the corresponding field stays null
+ *   - `manual` → the existing unit is kept when valid for the chosen option
+ *   - `auto` → re-derived against current options
+ */
+export declare function resolveBookingDraft<TTraveler extends BookingDraftTraveler>(options: {
+    quantities: BookingDraftQuantities;
+    travelers: readonly TTraveler[];
+    units: readonly PricingAssignmentUnit[];
+    now?: Date;
+}): ResolvedBookingDraft<TTraveler>;
+/**
+ * Normalize per-person extras to charged traveler quantity and
+ * stamp traveler links + `clientLineKey` so the server can link
+ * each extra line to the travelers it applies to via
+ * `booking_item_travelers`.
+ *
+ * Per-person mode (`pricingMode === "per_person"` or
+ * `pricedPerPerson === true`): quantity multiplied by travelerCount,
+ * `travelerKeys` set to all travelers when stable keys are supplied;
+ * otherwise `travelerIndexes` is set as a deprecated fallback.
+ * Non-per-person lines pass through with `clientLineKey` only.
+ */
+export declare function resolveBookingExtraLines<TLine extends ResolvableExtraLine>(options: {
+    extraLines: readonly TLine[];
+    travelerCount: number;
+    travelerKeys?: readonly (string | null | undefined)[];
+}): TLine[];
+/**
+ * Project a resolved draft's traveler list into the wire-format
+ * `BookingCreateTravelerInput[]` shape the dialog submits. Derives
+ * the `travelerCategory` from DOB / role.
+ *
+ * `roomUnitId` is a deprecated compatibility alias for the pricing tier
+ * option unit. Inventory placement is expressed only by item lines and their
+ * `travelerKeys`; the server accepts this field but does not persist it.
+ */
+export declare function travelersToRows(value: {
+    travelers: readonly BookingDraftTraveler[];
+}, now?: Date): Array<{
+    clientTravelerKey: string | null;
+    personId: string | null;
+    firstName: string;
+    lastName: string;
+    email: string | null;
+    phone: string | null;
+    preferredLanguage: string | null;
+    participantType: "traveler";
+    travelerCategory: "adult" | "child" | "infant" | null;
+    isPrimary: boolean;
+    roomUnitId: string | null;
+}>;
+//# sourceMappingURL=draft.d.ts.map

package/dist/pricing-assignment/draft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft.d.ts","sourceRoot":"","sources":["../../src/pricing-assignment/draft.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,YAAY,CAAA;AAInB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,SAAS,oBAAoB,EAAE,OAAO,EAAE;IACnF,UAAU,EAAE,sBAAsB,CAAA;IAClC,SAAS,EAAE,SAAS,SAAS,EAAE,CAAA;IAC/B,KAAK,EAAE,SAAS,qBAAqB,EAAE,CAAA;IACvC,GAAG,CAAC,EAAE,IAAI,CAAA;CACX,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAkOlC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,SAAS,mBAAmB,EAAE,OAAO,EAAE;IACnF,UAAU,EAAE,SAAS,KAAK,EAAE,CAAA;IAC5B,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAA;CACtD,GAAG,KAAK,EAAE,CA0BV;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE;IAAE,SAAS,EAAE,SAAS,oBAAoB,EAAE,CAAA;CAAE,EACrD,GAAG,GAAE,IAAiB,GACrB,KAAK,CAAC;IACP,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,eAAe,EAAE,UAAU,CAAA;IAC3B,gBAAgB,EAAE,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,IAAI,CAAA;IACrD,SAAS,EAAE,OAAO,CAAA;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B,CAAC,CAcD"}

package/dist/pricing-assignment/draft.js

@@ -0,0 +1,284 @@
+import { computeAgeYears, deriveDraftPaxBand, pickUnitForAge } from "./age.js";
+import { isInventoryUnit, isPersonUnit, optionKey, roleHintForTraveler } from "./unit-helpers.js";
+/**
+ * Resolve a booking-create draft into the per-unit quantities and
+ * per-traveler unit assignments the submit pipeline + price preview
+ * both need. Single source of truth for traveler→unit mapping.
+ *
+ * Shape branching:
+ *   - **Person-priced options** (only `person` units, no `room`):
+ *     quantities are derived from traveler assignments (1 adult + 1
+ *     child + 1 infant = 3 line items, not "3 x Adult"). Auto-source
+ *     travelers are re-derived against the current option's bands.
+ *   - **Accommodation options** (any `room` unit): operator-picked
+ *     stepper quantities are preserved (1 DBL room is 1 line). Per-
+ *     traveler room assignments still update `travelerIndexesByUnitId`
+ *     so `booking_item_travelers` rows can be created.
+ *
+ * Respects assignment sources:
+ *   - `none` → the corresponding field stays null
+ *   - `manual` → the existing unit is kept when valid for the chosen option
+ *   - `auto` → re-derived against current options
+ */
+export function resolveBookingDraft(options) {
+    const { quantities, travelers, now = new Date() } = options;
+    const units = [...options.units];
+    if (units.length === 0) {
+        return { quantities, travelers: [...travelers], travelerIndexesByUnitId: {} };
+    }
+    const unitsByOption = new Map();
+    const unitById = new Map();
+    const unitToOption = new Map();
+    for (const unit of units) {
+        const key = optionKey(unit);
+        unitById.set(unit.optionUnitId, unit);
+        unitToOption.set(unit.optionUnitId, key);
+        const list = unitsByOption.get(key);
+        if (list)
+            list.push(unit);
+        else
+            unitsByOption.set(key, [unit]);
+    }
+    const primaryInventoryByOption = new Map();
+    for (const [key, optionUnits] of unitsByOption) {
+        const inventoryUnit = optionUnits.find(isInventoryUnit);
+        if (inventoryUnit)
+            primaryInventoryByOption.set(key, inventoryUnit);
+    }
+    // An option is "person-priced" when it has at least one person unit
+    // and no inventory unit (room/vehicle). That's the excursion shape:
+    // line quantities derive from travelers, not from the stepper's
+    // primary-unit count. Multi-day packages with both a room AND a
+    // person-typed adult fee fall outside this set — the room
+    // quantity passes through unchanged.
+    const personPricedOptions = new Set();
+    for (const [key, optionUnits] of unitsByOption) {
+        const hasPerson = optionUnits.some(isPersonUnit);
+        const hasInventory = optionUnits.some(isInventoryUnit);
+        if (hasPerson && !hasInventory)
+            personPricedOptions.add(key);
+    }
+    const totalByOption = new Map();
+    for (const [unitId, quantity] of Object.entries(quantities)) {
+        if (quantity <= 0)
+            continue;
+        const key = unitToOption.get(unitId);
+        if (!key)
+            continue;
+        totalByOption.set(key, (totalByOption.get(key) ?? 0) + quantity);
+    }
+    const assignedForDefaulting = new Map();
+    for (const traveler of travelers) {
+        const inventorySource = traveler.inventoryUnitSource ?? "auto";
+        const pricingSource = traveler.pricingUnitSource ?? "auto";
+        const assignedUnitId = inventorySource !== "none" && traveler.inventoryUnitId
+            ? traveler.inventoryUnitId
+            : pricingSource !== "none"
+                ? traveler.pricingUnitId
+                : null;
+        if (!assignedUnitId)
+            continue;
+        const key = unitToOption.get(assignedUnitId);
+        if (!key)
+            continue;
+        assignedForDefaulting.set(key, (assignedForDefaulting.get(key) ?? 0) + 1);
+    }
+    const optionDemand = Array.from(totalByOption.entries());
+    const pickOptionWithDemand = () => optionDemand.find(([candidate, total]) => (assignedForDefaulting.get(candidate) ?? 0) < total)?.[0] ?? optionDemand[0]?.[0];
+    const resolvePricingUnitForTraveler = (traveler, key) => pickUnitForAge((unitsByOption.get(key) ?? []).filter(isPersonUnit), computeAgeYears(traveler.dateOfBirth, now), roleHintForTraveler(traveler));
+    const resolveTargetOption = (traveler) => {
+        const inventorySource = traveler.inventoryUnitSource ?? "auto";
+        if (inventorySource !== "none" && traveler.inventoryUnitId) {
+            const inventoryUnit = unitById.get(traveler.inventoryUnitId);
+            const key = unitToOption.get(traveler.inventoryUnitId);
+            if (key && inventoryUnit && isInventoryUnit(inventoryUnit))
+                return { key, fromDemand: false };
+        }
+        const pricingSource = traveler.pricingUnitSource ?? "auto";
+        if (pricingSource !== "none" && traveler.pricingUnitId) {
+            const pricingUnit = unitById.get(traveler.pricingUnitId);
+            const key = unitToOption.get(traveler.pricingUnitId);
+            if (key && pricingUnit && isPersonUnit(pricingUnit))
+                return { key, fromDemand: false };
+        }
+        const key = pickOptionWithDemand();
+        return key ? { key, fromDemand: true } : null;
+    };
+    const nextTravelers = travelers.map((traveler) => {
+        const target = resolveTargetOption(traveler);
+        const pricingSource = traveler.pricingUnitSource ?? "auto";
+        const inventorySource = traveler.inventoryUnitSource ?? "auto";
+        if (!target) {
+            return {
+                ...traveler,
+                pricingUnitId: null,
+                inventoryUnitId: null,
+                pricingUnitSource: pricingSource === "none" ? "none" : "auto",
+                inventoryUnitSource: inventorySource === "none" ? "none" : "auto",
+            };
+        }
+        const targetKey = target.key;
+        const currentPricingUnit = traveler.pricingUnitId
+            ? unitById.get(traveler.pricingUnitId)
+            : undefined;
+        const currentPricingKey = traveler.pricingUnitId
+            ? unitToOption.get(traveler.pricingUnitId)
+            : undefined;
+        const keepManualPricing = pricingSource === "manual" &&
+            currentPricingUnit &&
+            isPersonUnit(currentPricingUnit) &&
+            currentPricingKey === targetKey;
+        const nextPricingUnit = pricingSource === "none"
+            ? null
+            : keepManualPricing
+                ? currentPricingUnit
+                : (resolvePricingUnitForTraveler(traveler, targetKey) ?? null);
+        const currentInventoryUnit = traveler.inventoryUnitId
+            ? unitById.get(traveler.inventoryUnitId)
+            : undefined;
+        const currentInventoryKey = traveler.inventoryUnitId
+            ? unitToOption.get(traveler.inventoryUnitId)
+            : undefined;
+        const keepManualInventory = inventorySource === "manual" &&
+            currentInventoryUnit &&
+            isInventoryUnit(currentInventoryUnit) &&
+            currentInventoryKey === targetKey;
+        const targetInventoryUnit = primaryInventoryByOption.get(targetKey) ?? null;
+        const nextInventoryUnit = inventorySource === "none"
+            ? null
+            : keepManualInventory
+                ? currentInventoryUnit
+                : targetInventoryUnit;
+        if (target.fromDemand && (nextPricingUnit || nextInventoryUnit)) {
+            assignedForDefaulting.set(targetKey, (assignedForDefaulting.get(targetKey) ?? 0) + 1);
+        }
+        return {
+            ...traveler,
+            pricingUnitId: nextPricingUnit?.optionUnitId ?? null,
+            inventoryUnitId: nextInventoryUnit?.optionUnitId ?? null,
+            pricingUnitSource: pricingSource === "none" ? "none" : keepManualPricing ? "manual" : "auto",
+            inventoryUnitSource: inventorySource === "none" ? "none" : keepManualInventory ? "manual" : "auto",
+        };
+    });
+    const next = {};
+    const travelerIndexesByUnitId = {};
+    // Accommodation quantities pass through unchanged — 1 DBL room
+    // stays 1 line. Person-priced quantities are rebuilt from traveler
+    // assignments below.
+    for (const [unitId, quantity] of Object.entries(quantities)) {
+        if (quantity <= 0)
+            continue;
+        const key = unitToOption.get(unitId);
+        if (!key || personPricedOptions.has(key))
+            continue;
+        const submittedUnit = unitById.get(unitId);
+        const targetUnitId = submittedUnit && isInventoryUnit(submittedUnit)
+            ? unitId
+            : (primaryInventoryByOption.get(key)?.optionUnitId ?? unitId);
+        next[targetUnitId] = (next[targetUnitId] ?? 0) + quantity;
+    }
+    const assignedByOption = new Map();
+    for (const [index, traveler] of nextTravelers.entries()) {
+        const pricingSource = traveler.pricingUnitSource ?? "auto";
+        const inventorySource = traveler.inventoryUnitSource ?? "auto";
+        const pricingKey = pricingSource !== "none" && traveler.pricingUnitId
+            ? unitToOption.get(traveler.pricingUnitId)
+            : undefined;
+        const inventoryKey = inventorySource !== "none" && traveler.inventoryUnitId
+            ? unitToOption.get(traveler.inventoryUnitId)
+            : undefined;
+        const key = inventoryKey ?? pricingKey;
+        if (!key)
+            continue;
+        if (personPricedOptions.has(key)) {
+            if (!traveler.pricingUnitId || pricingSource === "none")
+                continue;
+            const unitIndexes = travelerIndexesByUnitId[traveler.pricingUnitId] ?? [];
+            unitIndexes.push(index);
+            travelerIndexesByUnitId[traveler.pricingUnitId] = unitIndexes;
+            next[traveler.pricingUnitId] = (next[traveler.pricingUnitId] ?? 0) + 1;
+            assignedByOption.set(key, (assignedByOption.get(key) ?? 0) + 1);
+        }
+        else if (traveler.inventoryUnitId && inventorySource !== "none") {
+            const unitIndexes = travelerIndexesByUnitId[traveler.inventoryUnitId] ?? [];
+            unitIndexes.push(index);
+            travelerIndexesByUnitId[traveler.inventoryUnitId] = unitIndexes;
+        }
+    }
+    // Person-priced residual: operator picked N seats but only added M
+    // travelers (M < N) → put the leftover on the option's adult unit
+    // so the line-item total matches the stepper.
+    for (const [key, total] of totalByOption) {
+        if (!personPricedOptions.has(key))
+            continue;
+        const assigned = assignedByOption.get(key) ?? 0;
+        const residual = Math.max(0, total - assigned);
+        if (residual === 0)
+            continue;
+        const adult = pickUnitForAge(unitsByOption.get(key) ?? [], null, "adult");
+        if (!adult)
+            continue;
+        next[adult.optionUnitId] = (next[adult.optionUnitId] ?? 0) + residual;
+    }
+    return { quantities: next, travelers: nextTravelers, travelerIndexesByUnitId };
+}
+/**
+ * Normalize per-person extras to charged traveler quantity and
+ * stamp traveler links + `clientLineKey` so the server can link
+ * each extra line to the travelers it applies to via
+ * `booking_item_travelers`.
+ *
+ * Per-person mode (`pricingMode === "per_person"` or
+ * `pricedPerPerson === true`): quantity multiplied by travelerCount,
+ * `travelerKeys` set to all travelers when stable keys are supplied;
+ * otherwise `travelerIndexes` is set as a deprecated fallback.
+ * Non-per-person lines pass through with `clientLineKey` only.
+ */
+export function resolveBookingExtraLines(options) {
+    const travelerIndexes = Array.from({ length: options.travelerCount }, (_, index) => index);
+    const travelerKeys = (options.travelerKeys ?? []).filter((key) => typeof key === "string" && key.trim().length > 0);
+    const useTravelerKeys = travelerKeys.length === options.travelerCount;
+    return options.extraLines.map((line) => {
+        const perPerson = line.pricingMode === "per_person" || line.pricedPerPerson === true;
+        if (!perPerson) {
+            return {
+                ...line,
+                clientLineKey: line.clientLineKey ?? `extra:${line.productExtraId}`,
+            };
+        }
+        const quantity = Math.max(1, options.travelerCount) * line.quantity;
+        return {
+            ...line,
+            clientLineKey: line.clientLineKey ?? `extra:${line.productExtraId}`,
+            quantity,
+            totalSellAmountCents: line.unitSellAmountCents == null
+                ? line.totalSellAmountCents
+                : line.unitSellAmountCents * quantity,
+            ...(useTravelerKeys ? { travelerKeys } : { travelerIndexes }),
+        };
+    });
+}
+/**
+ * Project a resolved draft's traveler list into the wire-format
+ * `BookingCreateTravelerInput[]` shape the dialog submits. Derives
+ * the `travelerCategory` from DOB / role.
+ *
+ * `roomUnitId` is a deprecated compatibility alias for the pricing tier
+ * option unit. Inventory placement is expressed only by item lines and their
+ * `travelerKeys`; the server accepts this field but does not persist it.
+ */
+export function travelersToRows(value, now = new Date()) {
+    return value.travelers.map((traveler) => ({
+        clientTravelerKey: traveler.clientTravelerKey?.trim() || null,
+        personId: traveler.personId,
+        firstName: traveler.firstName.trim(),
+        lastName: traveler.lastName.trim(),
+        email: traveler.email.trim() || null,
+        phone: traveler.phone.trim() || null,
+        preferredLanguage: traveler.preferredLanguage.trim() || null,
+        participantType: "traveler",
+        travelerCategory: deriveDraftPaxBand(traveler, now),
+        isPrimary: traveler.role === "lead",
+        roomUnitId: traveler.pricingUnitSource === "none" ? null : traveler.pricingUnitId,
+    }));
+}

package/dist/pricing-assignment/types.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Pure, transport-agnostic logic for mapping travelers onto option_units
+ * at booking-create time. Lives in `@voyantjs/bookings` so the
+ * booking-create dialog (preview + submit) is the only call site today,
+ * but the server can import the same module to validate or re-resolve
+ * submit payloads in a follow-up — that wiring is not yet in place.
+ *
+ * Vocabulary:
+ *   - A **pricing tier** (`unit_type='person'`) is a per-pax price band
+ *     a traveler is billed as (Adult / Child 6-12 / Infant 0-5 / …).
+ *   - An **inventory unit** (`'room' | 'vehicle' | 'seat'`) is a finite
+ *     container a traveler is placed into (one DBL room holds 2 pax).
+ *   - "Person-priced options" are options that only have pricing tiers
+ *     (no inventory). Excursions. For these, line-item quantities
+ *     **derive from the traveler list** (1 adult + 1 child + 1 infant).
+ *   - "Accommodation options" have inventory units (and usually a
+ *     paired person unit for per-pax fees). For these, line-item
+ *     quantities **stay as the operator picked them** (1 DBL room is
+ *     still 1 line, not 2).
+ *
+ * The `pricingUnitSource` and `inventoryUnitSource` enums on the
+ * traveler track operator intent so the resolver knows when to
+ * re-derive ("auto") versus respect an explicit choice ("manual" /
+ * "none" for No room).
+ *
+ * No React, no DB, no HTTP — just the assignment math.
+ *
+ * Tracking: voyantjs/voyant#1267.
+ */
+export type TravelerRole = "lead" | "adult" | "child" | "infant";
+export type AssignmentRoleHint = "adult" | "child" | "infant";
+export type BookingDraftUnitAssignmentSource = "auto" | "manual" | "none";
+export interface BookingDraftTraveler {
+    /** Stable client-side traveler key used by wire-format travelerKeys links. */
+    clientTravelerKey?: string | null;
+    personId: string | null;
+    firstName: string;
+    lastName: string;
+    email: string;
+    phone: string;
+    preferredLanguage: string;
+    role: TravelerRole;
+    dateOfBirth: string | null;
+    /** option_unit_id of the person pricing tier this traveler is billed as. */
+    pricingUnitId: string | null;
+    /** option_unit_id of the room/vehicle this traveler occupies, when applicable. */
+    inventoryUnitId: string | null;
+    /**
+     * Tracks operator intent around `pricingUnitId`.
+     *
+     * - `auto`: derived from product shape, DOB, role hints, and
+     *   selected quantity. Eligible for re-derivation on every render.
+     * - `manual`: operator explicitly clicked a category button. The
+     *   resolver respects the value when it's in the current unit set;
+     *   otherwise it re-derives.
+     * - `none`: no pricing unit should be assigned.
+     */
+    pricingUnitSource?: BookingDraftUnitAssignmentSource;
+    /**
+     * Tracks operator intent around `inventoryUnitId`.
+     *
+     * - `auto`: derived from selected quantity and product shape.
+     * - `manual`: operator explicitly clicked a room/vehicle control.
+     * - `none`: operator explicitly picked "No room". Stays null.
+     */
+    inventoryUnitSource?: BookingDraftUnitAssignmentSource;
+}
+export interface PricingAssignmentUnit {
+    /** Option the unit belongs to. Null for product-level units. */
+    optionId?: string | null;
+    /** Stable id of the unit (option_unit primary key). */
+    optionUnitId: string;
+    /** Display name (e.g. "Adult", "Child 6-12", "DBL room"). */
+    unitName: string;
+    /** Stable code from the products schema (`ADULT`, `child_6_12`, …) when present. */
+    unitCode?: string | null;
+    /** Inclusive lower age bound for this unit, when configured. */
+    minAge?: number | null;
+    /** Inclusive upper age bound for this unit, when configured. */
+    maxAge?: number | null;
+    /** Unit category — drives the pricing-tier vs inventory split. */
+    unitType?: "person" | "group" | "room" | "vehicle" | "service" | "other" | null;
+}
+export type BookingDraftQuantities = Record<string, number>;
+export interface ResolvedBookingDraft<TTraveler extends BookingDraftTraveler> {
+    quantities: BookingDraftQuantities;
+    travelers: TTraveler[];
+    /**
+     * For each unit that ended up assigned, the indexes (into the input
+     * traveler array) of travelers mapped to it. Used at submit time to
+     * stamp stable `travelerKeys` on `booking_item` lines so the server
+     * can link items to travelers through `booking_item_travelers`.
+     */
+    travelerIndexesByUnitId: Record<string, number[]>;
+}
+/**
+ * Minimal structural shape `resolveBookingExtraLines` needs from an
+ * extra line. Real callers (booking-create dialog) pass the full
+ * `BookingCreateExtraLineInput` from `@voyantjs/bookings-react`; this
+ * type avoids a cyclic dependency.
+ */
+export interface ResolvableExtraLine {
+    productExtraId: string;
+    pricingMode?: string | null;
+    pricedPerPerson?: boolean | null;
+    quantity: number;
+    unitSellAmountCents?: number | null;
+    totalSellAmountCents?: number | null;
+    clientLineKey?: string | null;
+    travelerKeys?: string[] | null;
+    travelerIndexes?: number[] | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/pricing-assignment/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/pricing-assignment/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAA;AAChE,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAA;AAC7D,MAAM,MAAM,gCAAgC,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEzE,MAAM,WAAW,oBAAoB;IACnC,8EAA8E;IAC9E,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,iBAAiB,EAAE,MAAM,CAAA;IACzB,IAAI,EAAE,YAAY,CAAA;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,4EAA4E;IAC5E,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,kFAAkF;IAClF,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B;;;;;;;;;OASG;IACH,iBAAiB,CAAC,EAAE,gCAAgC,CAAA;IACpD;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,gCAAgC,CAAA;CACvD;AAED,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAA;IACpB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAA;IAChB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,IAAI,CAAA;CAChF;AAED,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAE3D,MAAM,WAAW,oBAAoB,CAAC,SAAS,SAAS,oBAAoB;IAC1E,UAAU,EAAE,sBAAsB,CAAA;IAClC,SAAS,EAAE,SAAS,EAAE,CAAA;IACtB;;;;;OAKG;IACH,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;CAClD;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,MAAM,CAAA;IACtB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,eAAe,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;IAChC,QAAQ,EAAE,MAAM,CAAA;IAChB,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnC,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;IAC9B,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;CAClC"}

package/dist/pricing-assignment/types.js

@@ -0,0 +1,30 @@
+/**
+ * Pure, transport-agnostic logic for mapping travelers onto option_units
+ * at booking-create time. Lives in `@voyantjs/bookings` so the
+ * booking-create dialog (preview + submit) is the only call site today,
+ * but the server can import the same module to validate or re-resolve
+ * submit payloads in a follow-up — that wiring is not yet in place.
+ *
+ * Vocabulary:
+ *   - A **pricing tier** (`unit_type='person'`) is a per-pax price band
+ *     a traveler is billed as (Adult / Child 6-12 / Infant 0-5 / …).
+ *   - An **inventory unit** (`'room' | 'vehicle' | 'seat'`) is a finite
+ *     container a traveler is placed into (one DBL room holds 2 pax).
+ *   - "Person-priced options" are options that only have pricing tiers
+ *     (no inventory). Excursions. For these, line-item quantities
+ *     **derive from the traveler list** (1 adult + 1 child + 1 infant).
+ *   - "Accommodation options" have inventory units (and usually a
+ *     paired person unit for per-pax fees). For these, line-item
+ *     quantities **stay as the operator picked them** (1 DBL room is
+ *     still 1 line, not 2).
+ *
+ * The `pricingUnitSource` and `inventoryUnitSource` enums on the
+ * traveler track operator intent so the resolver knows when to
+ * re-derive ("auto") versus respect an explicit choice ("manual" /
+ * "none" for No room).
+ *
+ * No React, no DB, no HTTP — just the assignment math.
+ *
+ * Tracking: voyantjs/voyant#1267.
+ */
+export {};

package/dist/pricing-assignment/unit-helpers.d.ts

@@ -0,0 +1,11 @@
+import type { AssignmentRoleHint, BookingDraftTraveler, PricingAssignmentUnit } from "./types.js";
+/**
+ * Inventory units are finite containers a traveler is placed into.
+ * Rooms (hotels), vehicles (transfers), seats (where modeled
+ * explicitly). Distinct from pricing tiers (`person`).
+ */
+export declare function optionKey(unit: PricingAssignmentUnit): string;
+export declare function isPersonUnit(unit: PricingAssignmentUnit): boolean;
+export declare function isInventoryUnit(unit: PricingAssignmentUnit): boolean;
+export declare function roleHintForTraveler(traveler: BookingDraftTraveler): AssignmentRoleHint | null;
+//# sourceMappingURL=unit-helpers.d.ts.map