@voyant-travel/finance 0.119.5

package/dist/markets-ref.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Local reference to `markets.exchange_rates`. Finance stores plain-text
+ * `fx_rate_set_id` links and reads this table opportunistically to normalize
+ * cross-currency payment/document amounts without taking a hard markets dep.
+ */
+export declare const exchangeRatesRef: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "exchange_rates";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: string;
+            tableName: "exchange_rates";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: true;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        fxRateSetId: import("drizzle-orm/pg-core").PgColumn<{
+            name: string;
+            tableName: "exchange_rates";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        baseCurrency: import("drizzle-orm/pg-core").PgColumn<{
+            name: "base_currency";
+            tableName: "exchange_rates";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        quoteCurrency: import("drizzle-orm/pg-core").PgColumn<{
+            name: "quote_currency";
+            tableName: "exchange_rates";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        rateDecimal: import("drizzle-orm/pg-core").PgColumn<{
+            name: "rate_decimal";
+            tableName: "exchange_rates";
+            dataType: "string";
+            columnType: "PgNumeric";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        inverseRateDecimal: import("drizzle-orm/pg-core").PgColumn<{
+            name: "inverse_rate_decimal";
+            tableName: "exchange_rates";
+            dataType: "string";
+            columnType: "PgNumeric";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        observedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "observed_at";
+            tableName: "exchange_rates";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "exchange_rates";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+//# sourceMappingURL=markets-ref.d.ts.map

package/dist/markets-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markets-ref.d.ts","sourceRoot":"","sources":["../src/markets-ref.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS3B,CAAA"}

package/dist/markets-ref.js

@@ -0,0 +1,17 @@
+import { typeId, typeIdRef } from "@voyant-travel/db/lib/typeid-column";
+import { numeric, pgTable, text, timestamp } from "drizzle-orm/pg-core";
+/**
+ * Local reference to `markets.exchange_rates`. Finance stores plain-text
+ * `fx_rate_set_id` links and reads this table opportunistically to normalize
+ * cross-currency payment/document amounts without taking a hard markets dep.
+ */
+export const exchangeRatesRef = pgTable("exchange_rates", {
+    id: typeId("exchange_rates").primaryKey(),
+    fxRateSetId: typeIdRef("fx_rate_set_id").notNull(),
+    baseCurrency: text("base_currency").notNull(),
+    quoteCurrency: text("quote_currency").notNull(),
+    rateDecimal: numeric("rate_decimal", { precision: 18, scale: 8 }).notNull(),
+    inverseRateDecimal: numeric("inverse_rate_decimal", { precision: 18, scale: 8 }),
+    observedAt: timestamp("observed_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+});

package/dist/payment-link.d.ts

@@ -0,0 +1,23 @@
+export interface BuildPaymentLinkUrlOptions {
+    /**
+     * Customer-facing site base URL. When omitted in a browser, the current
+     * origin is used; outside a browser, the helper returns a root-relative URL.
+     */
+    baseUrl?: string | null;
+    /**
+     * Full customer-facing payment-session URL template. Supports `{sessionId}`.
+     * When supplied, it takes precedence over `baseUrl`.
+     */
+    invoicePayUrlTemplate?: string | null;
+}
+export declare function buildPaymentLinkUrl(paymentSessionId: string, options?: BuildPaymentLinkUrlOptions): string;
+export interface BookingCheckoutUrlSettings {
+    bookingCheckoutUrlTemplate?: string | null;
+}
+export interface BuildBookingCheckoutUrlOptions {
+    bookingId?: string | null;
+    bookingCode?: string | null;
+    settings?: BookingCheckoutUrlSettings | null;
+}
+export declare function buildBookingCheckoutUrl(options: BuildBookingCheckoutUrlOptions): string | null;
+//# sourceMappingURL=payment-link.d.ts.map

package/dist/payment-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-link.d.ts","sourceRoot":"","sources":["../src/payment-link.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACtC;AAED,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,MAAM,EACxB,OAAO,GAAE,0BAA+B,GACvC,MAAM,CAQR;AAED,MAAM,WAAW,0BAA0B;IACzC,0BAA0B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3C;AAED,MAAM,WAAW,8BAA8B;IAC7C,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,QAAQ,CAAC,EAAE,0BAA0B,GAAG,IAAI,CAAA;CAC7C;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,8BAA8B,GAAG,MAAM,GAAG,IAAI,CAU9F"}

package/dist/payment-link.js

@@ -0,0 +1,30 @@
+export function buildPaymentLinkUrl(paymentSessionId, options = {}) {
+    const template = normalizePaymentLinkBaseUrl(options.invoicePayUrlTemplate);
+    if (template)
+        return template.replaceAll("{sessionId}", encodeURIComponent(paymentSessionId));
+    const path = `/pay/${encodeURIComponent(paymentSessionId)}`;
+    const baseUrl = normalizePaymentLinkBaseUrl(options.baseUrl ?? getBrowserOrigin());
+    return baseUrl ? `${baseUrl}${path}` : path;
+}
+export function buildBookingCheckoutUrl(options) {
+    const template = options.settings?.bookingCheckoutUrlTemplate?.trim();
+    if (!template)
+        return null;
+    if (template.includes("{bookingCode}") && !options.bookingCode)
+        return null;
+    if (template.includes("{bookingId}") && !options.bookingId)
+        return null;
+    return template
+        .replaceAll("{bookingCode}", encodeURIComponent(options.bookingCode ?? ""))
+        .replaceAll("{bookingId}", encodeURIComponent(options.bookingId ?? ""));
+}
+function normalizePaymentLinkBaseUrl(baseUrl) {
+    const trimmed = baseUrl?.trim();
+    if (!trimmed)
+        return null;
+    return trimmed.replace(/\/+$/, "");
+}
+function getBrowserOrigin() {
+    const location = globalThis.location;
+    return typeof location?.origin === "string" && location.origin.length > 0 ? location.origin : null;
+}

package/dist/payment-policy.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Customer-facing payment policy primitive.
+ *
+ * Decides how to split a booking total into a payment schedule: full
+ * payment up-front, or a deposit now + balance due before departure.
+ * Pure function — no DB, no IO. Two policies in (the operator default
+ * + any per-supplier / per-category / per-listing override) plus the
+ * booking total + departure date, schedule rows out.
+ *
+ * Behaviour:
+ *
+ *   1. If `policy.deposit.kind === "none"` → one row, full total, due
+ *      immediately. Skips the rest of the rules.
+ *   2. If departure is too close (`< minDaysBeforeDepartureForDeposit`
+ *      from today) → also full payment now. The agency doesn't have
+ *      time to chase a balance.
+ *   3. Otherwise → two rows:
+ *        - deposit row, due today, amount = percent × total OR fixed
+ *          cents (capped at total).
+ *        - balance row, amount = total − deposit, due
+ *          `balanceDueDaysBeforeDeparture` before departure, but never
+ *          sooner than `balanceDueMinDaysFromNow` days from now.
+ *
+ * Cascade resolution lives in {@link resolveEffectivePaymentPolicy}:
+ * the most-specific layer that defines a policy wins (booking >
+ * listing > category > supplier > operator default), no field-level
+ * merging — so the audit trail is "this whole policy applied".
+ */
+export type DepositKind = "none" | "percent" | "fixed_cents";
+export interface DepositRule {
+    kind: DepositKind;
+    /** Required when `kind === "percent"`. 0–100 inclusive. */
+    percent?: number;
+    /** Required when `kind === "fixed_cents"`. Capped at total. */
+    amountCents?: number;
+}
+export interface PaymentPolicy {
+    deposit: DepositRule;
+    /** Below this many days before departure, deposits are rejected and
+     *  the booking is invoiced for the full amount up-front. */
+    minDaysBeforeDepartureForDeposit: number;
+    /** When the balance is due (days BEFORE departure). */
+    balanceDueDaysBeforeDeparture: number;
+    /** Floor on the balance due date so it's never sooner than this
+     *  many days from "now". Protects the customer from a tight squeeze
+     *  when departure is barely outside the deposit window. */
+    balanceDueMinDaysFromNow: number;
+}
+/** Default policy: 100% up-front, no deposit. Safe fallback for
+ *  agencies that haven't configured anything yet. */
+export declare const noDepositPolicy: PaymentPolicy;
+export type PaymentScheduleEntryType = "deposit" | "balance" | "full";
+export interface ComputedScheduleEntry {
+    scheduleType: PaymentScheduleEntryType;
+    amountCents: number;
+    currency: string;
+    /** ISO `YYYY-MM-DD`. */
+    dueDate: string;
+}
+export interface ComputeScheduleInput {
+    totalCents: number;
+    currency: string;
+    /** ISO `YYYY-MM-DD` (or full ISO string — we only look at the date). */
+    departureDate: string | null | undefined;
+    /** Defaults to `new Date()`. Injectable for deterministic tests. */
+    today?: Date;
+}
+/**
+ * Compute the customer-facing payment schedule for a booking.
+ *
+ * Always returns at least one row. When the policy resolves to no
+ * deposit (or the gate denies one), the single row is a `full`
+ * scheduled for today.
+ */
+export declare function computePaymentSchedule(input: ComputeScheduleInput, policy: PaymentPolicy): ComputedScheduleEntry[];
+/** True when this policy is empty / "inherit from parent". */
+export declare function isPaymentPolicyEmpty(policy: PaymentPolicy | null | undefined): boolean;
+export type PaymentPolicySource = "booking" | "listing" | "category" | "supplier" | "operator_default";
+export interface PaymentPolicyCascadeLayers {
+    bookingPolicy?: PaymentPolicy | null;
+    listingPolicy?: PaymentPolicy | null;
+    categoryPolicy?: PaymentPolicy | null;
+    supplierPolicy?: PaymentPolicy | null;
+    operatorDefault: PaymentPolicy;
+}
+export interface ResolvedPaymentPolicy {
+    policy: PaymentPolicy;
+    source: PaymentPolicySource;
+}
+/**
+ * Most-specific-wins cascade. Returns both the policy and which
+ * layer it came from so contracts and ops UIs can show the trace.
+ *
+ * A layer is "set" when it's not null/undefined AND not effectively
+ * empty (deposit kind === "none" with no other meaningful fields).
+ * That way operators who declare an explicit "no deposit" policy on
+ * a supplier override their parent's "50% deposit" — they pass an
+ * explicit `deposit: { kind: "none" }` AND set non-zero day fields
+ * to mark the layer as intentional.
+ *
+ * For v1 we rely on null/undefined to mean "inherit". The settings
+ * API stores `null` for "use parent". An explicit "none" policy
+ * needs to be modeled with a different deposit kind later if it
+ * proves useful.
+ */
+export declare function resolveEffectivePaymentPolicy(layers: PaymentPolicyCascadeLayers): ResolvedPaymentPolicy;
+/**
+ * Predicate the storefront UI uses to decide whether to surface the
+ * "deposit + balance" copy or just "pay full now". Returns true when
+ * the policy + departure date resolve to a single full-payment row.
+ */
+export declare function policyShouldRequireFullPayment(policy: PaymentPolicy, departureDate: string | null | undefined, today?: Date): boolean;
+//# sourceMappingURL=payment-policy.d.ts.map

package/dist/payment-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-policy.d.ts","sourceRoot":"","sources":["../src/payment-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,aAAa,CAAA;AAE5D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,WAAW,CAAA;IACjB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,WAAW,CAAA;IACpB;gEAC4D;IAC5D,gCAAgC,EAAE,MAAM,CAAA;IACxC,uDAAuD;IACvD,6BAA6B,EAAE,MAAM,CAAA;IACrC;;+DAE2D;IAC3D,wBAAwB,EAAE,MAAM,CAAA;CACjC;AAED;qDACqD;AACrD,eAAO,MAAM,eAAe,EAAE,aAK7B,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAA;AAErE,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,wBAAwB,CAAA;IACtC,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,wEAAwE;IACxE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;IACxC,oEAAoE;IACpE,KAAK,CAAC,EAAE,IAAI,CAAA;CACb;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,oBAAoB,EAC3B,MAAM,EAAE,aAAa,GACpB,qBAAqB,EAAE,CA8DzB;AAaD,8DAA8D;AAC9D,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAgBtF;AAED,MAAM,MAAM,mBAAmB,GAC3B,SAAS,GACT,SAAS,GACT,UAAU,GACV,UAAU,GACV,kBAAkB,CAAA;AAEtB,MAAM,WAAW,0BAA0B;IACzC,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI,CAAA;IACpC,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI,CAAA;IACpC,cAAc,CAAC,EAAE,aAAa,GAAG,IAAI,CAAA;IACrC,cAAc,CAAC,EAAE,aAAa,GAAG,IAAI,CAAA;IACrC,eAAe,EAAE,aAAa,CAAA;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,aAAa,CAAA;IACrB,MAAM,EAAE,mBAAmB,CAAA;CAC5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,0BAA0B,GACjC,qBAAqB,CAMvB;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,aAAa,EACrB,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACxC,KAAK,GAAE,IAAiB,GACvB,OAAO,CAKT"}

package/dist/payment-policy.js

@@ -0,0 +1,193 @@
+/**
+ * Customer-facing payment policy primitive.
+ *
+ * Decides how to split a booking total into a payment schedule: full
+ * payment up-front, or a deposit now + balance due before departure.
+ * Pure function — no DB, no IO. Two policies in (the operator default
+ * + any per-supplier / per-category / per-listing override) plus the
+ * booking total + departure date, schedule rows out.
+ *
+ * Behaviour:
+ *
+ *   1. If `policy.deposit.kind === "none"` → one row, full total, due
+ *      immediately. Skips the rest of the rules.
+ *   2. If departure is too close (`< minDaysBeforeDepartureForDeposit`
+ *      from today) → also full payment now. The agency doesn't have
+ *      time to chase a balance.
+ *   3. Otherwise → two rows:
+ *        - deposit row, due today, amount = percent × total OR fixed
+ *          cents (capped at total).
+ *        - balance row, amount = total − deposit, due
+ *          `balanceDueDaysBeforeDeparture` before departure, but never
+ *          sooner than `balanceDueMinDaysFromNow` days from now.
+ *
+ * Cascade resolution lives in {@link resolveEffectivePaymentPolicy}:
+ * the most-specific layer that defines a policy wins (booking >
+ * listing > category > supplier > operator default), no field-level
+ * merging — so the audit trail is "this whole policy applied".
+ */
+/** Default policy: 100% up-front, no deposit. Safe fallback for
+ *  agencies that haven't configured anything yet. */
+export const noDepositPolicy = {
+    deposit: { kind: "none" },
+    minDaysBeforeDepartureForDeposit: 0,
+    balanceDueDaysBeforeDeparture: 0,
+    balanceDueMinDaysFromNow: 0,
+};
+/**
+ * Compute the customer-facing payment schedule for a booking.
+ *
+ * Always returns at least one row. When the policy resolves to no
+ * deposit (or the gate denies one), the single row is a `full`
+ * scheduled for today.
+ */
+export function computePaymentSchedule(input, policy) {
+    const total = Math.max(0, Math.round(input.totalCents));
+    const today = input.today ?? new Date();
+    const todayIso = isoDate(today);
+    if (total === 0) {
+        return [{ scheduleType: "full", amountCents: 0, currency: input.currency, dueDate: todayIso }];
+    }
+    if (policy.deposit.kind === "none") {
+        return [
+            { scheduleType: "full", amountCents: total, currency: input.currency, dueDate: todayIso },
+        ];
+    }
+    const departure = parseIsoDate(input.departureDate);
+    if (!departure) {
+        // Without a departure date we can't anchor the balance, so fall
+        // back to full upfront — the operator can still split manually
+        // via a booking-level override later.
+        return [
+            { scheduleType: "full", amountCents: total, currency: input.currency, dueDate: todayIso },
+        ];
+    }
+    const daysUntilDeparture = wholeDaysBetween(today, departure);
+    if (daysUntilDeparture < policy.minDaysBeforeDepartureForDeposit) {
+        return [
+            { scheduleType: "full", amountCents: total, currency: input.currency, dueDate: todayIso },
+        ];
+    }
+    const depositCents = clampCents(computeDepositCents(total, policy.deposit), 0, total);
+    const balanceCents = total - depositCents;
+    if (depositCents <= 0 || balanceCents <= 0) {
+        // Edge: a policy that resolves to 0% deposit or 100% deposit
+        // collapses to a single row rather than emitting a zero-cent
+        // partner.
+        return [
+            { scheduleType: "full", amountCents: total, currency: input.currency, dueDate: todayIso },
+        ];
+    }
+    const rawBalanceDue = addDays(departure, -policy.balanceDueDaysBeforeDeparture);
+    const earliestBalanceDue = addDays(today, policy.balanceDueMinDaysFromNow);
+    const balanceDue = rawBalanceDue.getTime() > earliestBalanceDue.getTime() ? rawBalanceDue : earliestBalanceDue;
+    return [
+        {
+            scheduleType: "deposit",
+            amountCents: depositCents,
+            currency: input.currency,
+            dueDate: todayIso,
+        },
+        {
+            scheduleType: "balance",
+            amountCents: balanceCents,
+            currency: input.currency,
+            dueDate: isoDate(balanceDue),
+        },
+    ];
+}
+function computeDepositCents(total, rule) {
+    if (rule.kind === "percent") {
+        const pct = clampNumber(rule.percent ?? 0, 0, 100);
+        return Math.round((total * pct) / 100);
+    }
+    if (rule.kind === "fixed_cents") {
+        return Math.max(0, Math.round(rule.amountCents ?? 0));
+    }
+    return 0;
+}
+/** True when this policy is empty / "inherit from parent". */
+export function isPaymentPolicyEmpty(policy) {
+    if (!policy)
+        return true;
+    if (policy.deposit.kind === "none")
+        return true;
+    if (policy.deposit.kind === "percent" &&
+        (policy.deposit.percent === undefined || policy.deposit.percent === 0)) {
+        return true;
+    }
+    if (policy.deposit.kind === "fixed_cents" &&
+        (policy.deposit.amountCents === undefined || policy.deposit.amountCents === 0)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Most-specific-wins cascade. Returns both the policy and which
+ * layer it came from so contracts and ops UIs can show the trace.
+ *
+ * A layer is "set" when it's not null/undefined AND not effectively
+ * empty (deposit kind === "none" with no other meaningful fields).
+ * That way operators who declare an explicit "no deposit" policy on
+ * a supplier override their parent's "50% deposit" — they pass an
+ * explicit `deposit: { kind: "none" }` AND set non-zero day fields
+ * to mark the layer as intentional.
+ *
+ * For v1 we rely on null/undefined to mean "inherit". The settings
+ * API stores `null` for "use parent". An explicit "none" policy
+ * needs to be modeled with a different deposit kind later if it
+ * proves useful.
+ */
+export function resolveEffectivePaymentPolicy(layers) {
+    if (layers.bookingPolicy)
+        return { policy: layers.bookingPolicy, source: "booking" };
+    if (layers.listingPolicy)
+        return { policy: layers.listingPolicy, source: "listing" };
+    if (layers.categoryPolicy)
+        return { policy: layers.categoryPolicy, source: "category" };
+    if (layers.supplierPolicy)
+        return { policy: layers.supplierPolicy, source: "supplier" };
+    return { policy: layers.operatorDefault, source: "operator_default" };
+}
+/**
+ * Predicate the storefront UI uses to decide whether to surface the
+ * "deposit + balance" copy or just "pay full now". Returns true when
+ * the policy + departure date resolve to a single full-payment row.
+ */
+export function policyShouldRequireFullPayment(policy, departureDate, today = new Date()) {
+    if (policy.deposit.kind === "none")
+        return true;
+    const departure = parseIsoDate(departureDate);
+    if (!departure)
+        return true;
+    return wholeDaysBetween(today, departure) < policy.minDaysBeforeDepartureForDeposit;
+}
+// ─────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────
+function parseIsoDate(value) {
+    if (!value)
+        return null;
+    const trimmed = value.length >= 10 ? value.slice(0, 10) : value;
+    const parsed = new Date(`${trimmed}T00:00:00Z`);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+function isoDate(d) {
+    return d.toISOString().slice(0, 10);
+}
+function wholeDaysBetween(from, to) {
+    const fromMs = Date.UTC(from.getUTCFullYear(), from.getUTCMonth(), from.getUTCDate());
+    const toMs = Date.UTC(to.getUTCFullYear(), to.getUTCMonth(), to.getUTCDate());
+    return Math.floor((toMs - fromMs) / (24 * 60 * 60 * 1000));
+}
+function addDays(d, days) {
+    const next = new Date(d.getTime());
+    next.setUTCDate(next.getUTCDate() + days);
+    return next;
+}
+function clampCents(value, min, max) {
+    return Math.max(min, Math.min(max, Math.round(value)));
+}
+function clampNumber(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}

package/dist/route-runtime.d.ts

@@ -0,0 +1,22 @@
+import type { EventBus } from "@voyant-travel/core";
+import type { InvoiceFxOptions } from "./invoice-fx.js";
+import type { FinanceDocumentRouteOptions, InvoiceDocumentGenerator } from "./routes-documents.js";
+import type { FinanceSettlementRouteOptions, InvoiceSettlementPoller } from "./routes-settlement.js";
+import type { InvoiceDueDateResolver, InvoiceLineDescriptionResolver, PaymentScheduleLineDescriptionFormat } from "./service.js";
+export type FinanceRouteRuntime = {
+    invoiceDocumentGenerator?: InvoiceDocumentGenerator;
+    resolveDocumentDownloadUrl?: FinanceDocumentRouteOptions["resolveDocumentDownloadUrl"];
+    invoiceSettlementPollers: Record<string, InvoiceSettlementPoller>;
+    eventBus?: EventBus;
+    descriptionResolver?: InvoiceLineDescriptionResolver;
+    invoiceDueDateResolver?: InvoiceDueDateResolver;
+    paymentScheduleLineDescriptionFormat?: PaymentScheduleLineDescriptionFormat;
+} & InvoiceFxOptions;
+export declare const FINANCE_ROUTE_RUNTIME_CONTAINER_KEY = "providers.finance.runtime";
+export interface FinanceRuntimeOptions extends FinanceDocumentRouteOptions, FinanceSettlementRouteOptions, InvoiceFxOptions {
+    descriptionResolver?: InvoiceLineDescriptionResolver;
+    invoiceDueDateResolver?: InvoiceDueDateResolver;
+    paymentScheduleLineDescriptionFormat?: PaymentScheduleLineDescriptionFormat;
+}
+export declare function buildFinanceRouteRuntime(bindings: Record<string, unknown>, options?: FinanceRuntimeOptions): FinanceRouteRuntime;
+//# sourceMappingURL=route-runtime.d.ts.map

package/dist/route-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-runtime.d.ts","sourceRoot":"","sources":["../src/route-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAEnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,KAAK,EAAE,2BAA2B,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAA;AAClG,OAAO,KAAK,EAAE,6BAA6B,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AACpG,OAAO,KAAK,EACV,sBAAsB,EACtB,8BAA8B,EAC9B,oCAAoC,EACrC,MAAM,cAAc,CAAA;AAErB,MAAM,MAAM,mBAAmB,GAAG;IAChC,wBAAwB,CAAC,EAAE,wBAAwB,CAAA;IACnD,0BAA0B,CAAC,EAAE,2BAA2B,CAAC,4BAA4B,CAAC,CAAA;IACtF,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAA;IACjE,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,mBAAmB,CAAC,EAAE,8BAA8B,CAAA;IACpD,sBAAsB,CAAC,EAAE,sBAAsB,CAAA;IAC/C,oCAAoC,CAAC,EAAE,oCAAoC,CAAA;CAC5E,GAAG,gBAAgB,CAAA;AAEpB,eAAO,MAAM,mCAAmC,8BAA8B,CAAA;AAE9E,MAAM,WAAW,qBACf,SAAQ,2BAA2B,EACjC,6BAA6B,EAC7B,gBAAgB;IAClB,mBAAmB,CAAC,EAAE,8BAA8B,CAAA;IACpD,sBAAsB,CAAC,EAAE,sBAAsB,CAAA;IAC/C,oCAAoC,CAAC,EAAE,oCAAoC,CAAA;CAC5E;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,GAAE,qBAA0B,GAClC,mBAAmB,CAmBrB"}

package/dist/route-runtime.js

@@ -0,0 +1,18 @@
+export const FINANCE_ROUTE_RUNTIME_CONTAINER_KEY = "providers.finance.runtime";
+export function buildFinanceRouteRuntime(bindings, options = {}) {
+    return {
+        invoiceDocumentGenerator: options.resolveInvoiceDocumentGenerator?.(bindings) ?? options.invoiceDocumentGenerator,
+        resolveDocumentDownloadUrl: options.resolveDocumentDownloadUrl,
+        invoiceSettlementPollers: options.resolveInvoiceSettlementPollers?.(bindings) ?? options.invoiceSettlementPollers ?? {},
+        eventBus: options.resolveEventBus?.(bindings) ?? options.eventBus,
+        descriptionResolver: options.descriptionResolver,
+        invoiceDueDateResolver: options.invoiceDueDateResolver,
+        paymentScheduleLineDescriptionFormat: options.paymentScheduleLineDescriptionFormat,
+        invoiceFxSettings: options.invoiceFxSettings,
+        resolveInvoiceFxSettings: options.resolveInvoiceFxSettings,
+        updateInvoiceFxSettings: options.updateInvoiceFxSettings,
+        resolveInvoiceExchangeRate: options.resolveInvoiceExchangeRateResolver?.(bindings) ?? options.resolveInvoiceExchangeRate,
+        resolveInvoiceExchangeRateResolver: options.resolveInvoiceExchangeRateResolver,
+        onInvoiceFxResolutionError: options.onInvoiceFxResolutionError,
+    };
+}