@voyantjs/finance 0.6.9 → 0.8.0

package/dist/service-bookings-quick-create.js

@@ -0,0 +1,312 @@
+import { bookingGroupsService, bookingsService } from "@voyantjs/bookings";
+import { bookingTravelers } from "@voyantjs/bookings/schema";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { bookingPaymentSchedules, vouchers } from "./schema.js";
+import { VoucherServiceError, vouchersService } from "./service-vouchers.js";
+import { paymentScheduleStatusSchema, paymentScheduleTypeSchema } from "./validation-shared.js";
+// ---------- validation ----------
+const travelerInputSchema = z.object({
+    firstName: z.string().min(1).max(255),
+    lastName: z.string().min(1).max(255),
+    email: z.string().email().optional().nullable(),
+    phone: z.string().max(50).optional().nullable(),
+    personId: z.string().optional().nullable(),
+    participantType: z.enum(["traveler", "occupant", "other"]).default("traveler"),
+    travelerCategory: z.enum(["adult", "child", "infant", "senior", "other"]).optional().nullable(),
+    preferredLanguage: z.string().max(35).optional().nullable(),
+    accessibilityNeeds: z.string().optional().nullable(),
+    specialRequests: z.string().optional().nullable(),
+    /**
+     * option_unit_id the passenger is assigned to. Accepted by the input
+     * schema so the UI's PassengerListValue can round-trip, but not yet
+     * persisted — bookingTravelers has no room-assignment column and the
+     * allocation flow is owned by the items slice. Follow-up: add a traveler
+     * metadata JSONB or wire into booking_allocations.
+     */
+    roomUnitId: z.string().optional().nullable(),
+    isPrimary: z.boolean().optional().nullable(),
+    notes: z.string().optional().nullable(),
+});
+const paymentScheduleInputSchema = z.object({
+    scheduleType: paymentScheduleTypeSchema.default("balance"),
+    status: paymentScheduleStatusSchema.default("pending"),
+    dueDate: z.string().min(1),
+    currency: z.string().min(3).max(3),
+    amountCents: z.number().int().min(0),
+    notes: z.string().optional().nullable(),
+});
+const voucherRedemptionInputSchema = z.object({
+    voucherId: z.string().min(1),
+    amountCents: z.number().int().min(1),
+});
+const groupJoinSchema = z.object({
+    action: z.literal("join"),
+    groupId: z.string().min(1),
+    role: z.enum(["primary", "shared"]).default("shared"),
+});
+const groupCreateSchema = z.object({
+    action: z.literal("create"),
+    kind: z.enum(["shared_room", "other"]).default("shared_room"),
+    label: z.string().max(255).optional().nullable(),
+    optionUnitId: z.string().optional().nullable(),
+    /**
+     * When true (the default), the freshly-created booking becomes the group's
+     * primary booking. Operators creating a dual-booking can set this false and
+     * supply a different primaryBookingId — not wired in this slice, but the
+     * field is reserved.
+     */
+    makeBookingPrimary: z.boolean().default(true),
+});
+const groupMembershipInputSchema = z.discriminatedUnion("action", [
+    groupJoinSchema,
+    groupCreateSchema,
+]);
+export const quickCreateBookingSchema = z.object({
+    // Convert-product fields (mirrors convertProductSchema in bookings)
+    productId: z.string().min(1),
+    optionId: z.string().optional().nullable(),
+    slotId: z.string().optional().nullable(),
+    bookingNumber: z.string().min(1),
+    personId: z.string().optional().nullable(),
+    organizationId: z.string().optional().nullable(),
+    internalNotes: z.string().optional().nullable(),
+    // Orchestration fields
+    travelers: z.array(travelerInputSchema).optional(),
+    paymentSchedules: z.array(paymentScheduleInputSchema).optional(),
+    voucherRedemption: voucherRedemptionInputSchema.optional(),
+    groupMembership: groupMembershipInputSchema.optional(),
+});
+// ---------- service ----------
+/**
+ * Atomic booking-create orchestrator. Runs product conversion + travelers +
+ * payment schedules + voucher redemption + group membership inside a single
+ * transaction so partial failures (e.g. voucher insufficient-balance after
+ * schedules have been written) roll the whole thing back.
+ *
+ * Event emission is post-commit — if the tx rolls back, subscribers never
+ * hear about it.
+ *
+ * Why the orchestrator lives in `@voyantjs/finance`: finance already imports
+ * from `@voyantjs/bookings` (invoices-from-bookings, voucher service, payment
+ * schedules all sit here), so this is the one place that can compose the
+ * three packages without creating a new workspace dep cycle. The route wires
+ * it under `/v1/admin/bookings/quick-create` via a HonoExtension whose
+ * `module` targets `"bookings"`.
+ */
+/**
+ * Sentinel thrown inside the tx to force drizzle to roll back. Returning a
+ * non-ok result from the tx callback doesn't abort the tx — only a thrown
+ * error does — so the orchestrator uses this to unwind cleanly when a
+ * downstream step discovers a precondition failure.
+ */
+class QuickCreateAbort extends Error {
+    outcome;
+    constructor(outcome) {
+        super(`quick-create aborted: ${outcome.status}`);
+        this.outcome = outcome;
+        this.name = "QuickCreateAbort";
+    }
+}
+export async function quickCreateBooking(db, rawInput, options = {}) {
+    const { userId, runtime } = options;
+    // Parse through the schema so defaults (makeBookingPrimary, role,
+    // participantType, etc.) are applied even when callers bypass validation —
+    // unit tests and hand-written integrations commonly do.
+    const input = quickCreateBookingSchema.parse(rawInput);
+    // Validate voucher up-front so we can short-circuit before the tx starts.
+    // This is a cheap read — the authoritative balance check still happens
+    // inside the redeem savepoint so two concurrent redemptions can't double-
+    // spend.
+    if (input.voucherRedemption) {
+        const [voucher] = await db
+            .select()
+            .from(vouchers)
+            .where(eq(vouchers.id, input.voucherRedemption.voucherId))
+            .limit(1);
+        if (!voucher)
+            return { status: "voucher_not_found" };
+        if (voucher.status !== "active")
+            return { status: "voucher_inactive" };
+        if (voucher.validFrom && voucher.validFrom.getTime() > Date.now()) {
+            return { status: "voucher_not_started" };
+        }
+        if (voucher.expiresAt && voucher.expiresAt.getTime() < Date.now()) {
+            return { status: "voucher_expired" };
+        }
+        if (input.voucherRedemption.amountCents > voucher.remainingAmountCents) {
+            return { status: "voucher_insufficient_balance" };
+        }
+    }
+    let result;
+    try {
+        result = await db.transaction(async (tx) => {
+            // 1. Booking from product
+            const booking = await bookingsService.createBookingFromProduct(tx, {
+                productId: input.productId,
+                optionId: input.optionId ?? null,
+                slotId: input.slotId ?? null,
+                bookingNumber: input.bookingNumber,
+                personId: input.personId ?? null,
+                organizationId: input.organizationId ?? null,
+                internalNotes: input.internalNotes ?? null,
+            });
+            if (!booking) {
+                // Caller gave us a product that doesn't resolve. Throw so drizzle
+                // rolls back any writes the convert helper may have made.
+                throw new QuickCreateAbort({ status: "product_not_found" });
+            }
+            // 2. Travelers. roomUnitId is accepted on the input but not persisted
+            // yet — see travelerInputSchema for the follow-up note.
+            const travelers = [];
+            for (const traveler of input.travelers ?? []) {
+                const [row] = await tx
+                    .insert(bookingTravelers)
+                    .values({
+                    bookingId: booking.id,
+                    personId: traveler.personId ?? null,
+                    participantType: traveler.participantType,
+                    travelerCategory: traveler.travelerCategory ?? null,
+                    firstName: traveler.firstName,
+                    lastName: traveler.lastName,
+                    email: traveler.email ?? null,
+                    phone: traveler.phone ?? null,
+                    preferredLanguage: traveler.preferredLanguage ?? null,
+                    accessibilityNeeds: traveler.accessibilityNeeds ?? null,
+                    specialRequests: traveler.specialRequests ?? null,
+                    isPrimary: traveler.isPrimary ?? false,
+                    notes: traveler.notes ?? null,
+                })
+                    .returning();
+                if (row)
+                    travelers.push(row);
+            }
+            // 3. Payment schedules
+            const paymentSchedules = [];
+            for (const schedule of input.paymentSchedules ?? []) {
+                const [row] = await tx
+                    .insert(bookingPaymentSchedules)
+                    .values({
+                    bookingId: booking.id,
+                    scheduleType: schedule.scheduleType,
+                    status: schedule.status,
+                    dueDate: schedule.dueDate,
+                    currency: schedule.currency,
+                    amountCents: schedule.amountCents,
+                    notes: schedule.notes ?? null,
+                })
+                    .returning();
+                if (row)
+                    paymentSchedules.push(row);
+            }
+            // 4. Voucher redemption. Delegates to vouchersService so the balance
+            // decrement + redemption-log insert share the savepoint. If anything
+            // goes wrong (race with a concurrent redemption, mostly), the thrown
+            // VoucherServiceError surfaces as the outcome below.
+            let voucherRedemption = null;
+            if (input.voucherRedemption) {
+                const { voucher, redemption } = await vouchersService.redeem(tx, input.voucherRedemption.voucherId, {
+                    bookingId: booking.id,
+                    amountCents: input.voucherRedemption.amountCents,
+                }, userId);
+                if (redemption) {
+                    voucherRedemption = { voucher, redemption };
+                }
+            }
+            // 5. Group membership (partaj). Either attach to an existing group or
+            // spin up a new one with this booking as the primary.
+            let groupMembership = null;
+            if (input.groupMembership) {
+                if (input.groupMembership.action === "create") {
+                    const group = await bookingGroupsService.createBookingGroup(tx, {
+                        kind: input.groupMembership.kind,
+                        label: input.groupMembership.label ?? `Shared — ${booking.bookingNumber}`,
+                        productId: input.productId,
+                        optionUnitId: input.groupMembership.optionUnitId ?? null,
+                        primaryBookingId: input.groupMembership.makeBookingPrimary ? booking.id : null,
+                    });
+                    const memberResult = await bookingGroupsService.addGroupMember(tx, group.id, {
+                        bookingId: booking.id,
+                        role: input.groupMembership.makeBookingPrimary ? "primary" : "shared",
+                    });
+                    if (memberResult.status !== "ok") {
+                        // Shouldn't happen — we just created both rows — but throw so
+                        // the tx rolls back instead of leaving a half-created group.
+                        throw new QuickCreateAbort({ status: "group_not_found" });
+                    }
+                    groupMembership = { groupId: group.id, member: memberResult.member };
+                }
+                else {
+                    const memberResult = await bookingGroupsService.addGroupMember(tx, input.groupMembership.groupId, {
+                        bookingId: booking.id,
+                        role: input.groupMembership.role,
+                    });
+                    if (memberResult.status === "group_not_found") {
+                        throw new QuickCreateAbort({ status: "group_not_found" });
+                    }
+                    if (memberResult.status === "booking_not_found") {
+                        // Same booking we just inserted. Pg transaction visibility should
+                        // prevent this; surface as group_not_found for the caller — we
+                        // can't tell them the booking we created doesn't exist.
+                        throw new QuickCreateAbort({ status: "group_not_found" });
+                    }
+                    if (memberResult.status === "already_in_group") {
+                        throw new QuickCreateAbort({
+                            status: "booking_already_in_group",
+                            currentGroupId: memberResult.currentGroupId,
+                        });
+                    }
+                    groupMembership = {
+                        groupId: input.groupMembership.groupId,
+                        member: memberResult.member,
+                    };
+                }
+            }
+            return {
+                booking,
+                travelers,
+                paymentSchedules,
+                voucherRedemption,
+                groupMembership,
+            };
+        });
+    }
+    catch (error) {
+        if (error instanceof QuickCreateAbort) {
+            return error.outcome;
+        }
+        if (error instanceof VoucherServiceError) {
+            if (error.code === "voucher_not_found")
+                return { status: "voucher_not_found" };
+            if (error.code === "voucher_inactive")
+                return { status: "voucher_inactive" };
+            if (error.code === "voucher_not_started")
+                return { status: "voucher_not_started" };
+            if (error.code === "voucher_expired")
+                return { status: "voucher_expired" };
+            if (error.code === "insufficient_balance")
+                return { status: "voucher_insufficient_balance" };
+        }
+        throw error;
+    }
+    // Post-commit event emission. Fire-and-forget (the eventBus contract
+    // handles subscriber errors); callers that need strict delivery can
+    // re-emit from their own subscriber chain.
+    if (runtime?.eventBus) {
+        const event = {
+            bookingId: result.booking.id,
+            bookingNumber: result.booking.bookingNumber,
+            productId: input.productId,
+            travelerCount: result.travelers.length,
+            paymentScheduleCount: result.paymentSchedules.length,
+            voucherRedeemedCents: result.voucherRedemption
+                ? result.voucherRedemption.redemption.amountCents
+                : null,
+            groupId: result.groupMembership?.groupId ?? null,
+            createdByUserId: userId ?? null,
+            occurredAt: new Date(),
+        };
+        await runtime.eventBus.emit("booking.quick-created", event);
+    }
+    return { status: "ok", result };
+}

package/dist/service-public.d.ts

@@ -156,16 +156,12 @@ export declare const publicFinanceService: {
         failureMessage: string | null;
     } | null>;
     validateVoucher(db: PostgresJsDatabase, input: PublicValidateVoucherInput): Promise<{
-        valid: false;
-        reason: "not_found";
-        voucher: null;
-    } | {
         valid: false;
         reason: "inactive";
         voucher: {
             id: string;
             code: string;
-            label: string;
+            label: string | null;
             provider: string | null;
             currency: string | null;
             amountCents: number | null;
@@ -178,7 +174,7 @@ export declare const publicFinanceService: {
         voucher: {
             id: string;
             code: string;
-            label: string;
+            label: string | null;
             provider: string | null;
             currency: string | null;
             amountCents: number | null;
@@ -191,7 +187,7 @@ export declare const publicFinanceService: {
         voucher: {
             id: string;
             code: string;
-            label: string;
+            label: string | null;
             provider: string | null;
             currency: string | null;
             amountCents: number | null;
@@ -204,7 +200,7 @@ export declare const publicFinanceService: {
         voucher: {
             id: string;
             code: string;
-            label: string;
+            label: string | null;
             provider: string | null;
             currency: string | null;
             amountCents: number | null;
@@ -217,7 +213,7 @@ export declare const publicFinanceService: {
         voucher: {
             id: string;
             code: string;
-            label: string;
+            label: string | null;
             provider: string | null;
             currency: string | null;
             amountCents: number | null;
@@ -230,7 +226,7 @@ export declare const publicFinanceService: {
         voucher: {
             id: string;
             code: string;
-            label: string;
+            label: string | null;
             provider: string | null;
             currency: string | null;
             amountCents: number | null;
@@ -243,13 +239,17 @@ export declare const publicFinanceService: {
         voucher: {
             id: string;
             code: string;
-            label: string;
+            label: string | null;
             provider: string | null;
             currency: string | null;
             amountCents: number | null;
             remainingAmountCents: number | null;
             expiresAt: string | null;
         };
+    } | {
+        valid: false;
+        reason: "not_found";
+        voucher: null;
     }>;
 };
 //# sourceMappingURL=service-public.d.ts.map

package/dist/service-public.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service-public.d.ts","sourceRoot":"","sources":["../src/service-public.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAWjE,OAAO,KAAK,EACV,6BAA6B,EAC7B,4BAA4B,EAE5B,2BAA2B,EAC3B,yBAAyB,EACzB,8BAA8B,EAC9B,0BAA0B,EAC3B,MAAM,wBAAwB,CAAA;AAE/B,MAAM,WAAW,2BAA2B;IAC1C,0BAA0B,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,GAAG,IAAI,CAAA;CAC5F;AA8HD,eAAO,MAAM,oBAAoB;4BAEzB,kBAAkB,aACX,MAAM,YACR,2BAA2B,GACnC,OAAO,CAAC,6BAA6B,GAAG,IAAI,CAAC;+BA6C1C,kBAAkB,aACX,MAAM,YACR,2BAA2B,GACnC,OAAO,CAAC,2BAA2B,GAAG,IAAI,CAAC;iCA0CxC,kBAAkB,aACX,MAAM,SACV,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAoH5B,kBAAkB,aACX,MAAM,GAChB,OAAO,CAAC,4BAA4B,GAAG,IAAI,CAAC;0BA2DnB,kBAAkB,aAAa,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;2CAM3D,kBAAkB,aACX,MAAM,cACL,MAAM,SACX,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;4CA4BjC,kBAAkB,aACX,MAAM,eACJ,MAAM,SACZ,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;mCAuBjC,kBAAkB,aACX,MAAM,SACV,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAMb,kBAAkB,SAAS,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8FhF,CAAA"}
+{"version":3,"file":"service-public.d.ts","sourceRoot":"","sources":["../src/service-public.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAYjE,OAAO,KAAK,EACV,6BAA6B,EAC7B,4BAA4B,EAE5B,2BAA2B,EAC3B,yBAAyB,EACzB,8BAA8B,EAC9B,0BAA0B,EAC3B,MAAM,wBAAwB,CAAA;AAE/B,MAAM,WAAW,2BAA2B;IAC1C,0BAA0B,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,GAAG,IAAI,CAAA;CAC5F;AA8HD,eAAO,MAAM,oBAAoB;4BAEzB,kBAAkB,aACX,MAAM,YACR,2BAA2B,GACnC,OAAO,CAAC,6BAA6B,GAAG,IAAI,CAAC;+BA6C1C,kBAAkB,aACX,MAAM,YACR,2BAA2B,GACnC,OAAO,CAAC,2BAA2B,GAAG,IAAI,CAAC;iCA0CxC,kBAAkB,aACX,MAAM,SACV,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAoH5B,kBAAkB,aACX,MAAM,GAChB,OAAO,CAAC,4BAA4B,GAAG,IAAI,CAAC;0BA2DnB,kBAAkB,aAAa,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;2CAM3D,kBAAkB,aACX,MAAM,cACL,MAAM,SACX,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;4CA4BjC,kBAAkB,aACX,MAAM,eACJ,MAAM,SACZ,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;mCAuBjC,kBAAkB,aACX,MAAM,SACV,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAMb,kBAAkB,SAAS,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsEhF,CAAA"}

package/dist/service-public.js

@@ -1,6 +1,6 @@
 import { bookings } from "@voyantjs/bookings/schema";
 import { and, asc, desc, eq, or, sql } from "drizzle-orm";
-import { bookingGuarantees, bookingPaymentSchedules, invoiceRenditions, invoices, paymentInstruments, payments, } from "./schema.js";
+import { bookingGuarantees, bookingPaymentSchedules, invoiceRenditions, invoices, paymentInstruments, payments, vouchers, } from "./schema.js";
 import { financeService } from "./service.js";
 function normalizeDateTime(value) {
     if (!value) {
@@ -350,10 +350,20 @@ export const publicFinanceService = {
         return session ? toPublicPaymentSession(session) : null;
     },
     async validateVoucher(db, input) {
-        const normalizedCode = input.code.trim().toLowerCase();
+        const normalizedCode = input.code.trim();
+        const normalizedCodeLower = normalizedCode.toLowerCase();
+        // New path: first-class `vouchers` table. Covers any voucher issued via
+        // POST /v1/finance/vouchers.
+        const resolvedFromNewTable = await resolveVoucherFromNewTable(db, normalizedCode);
+        if (resolvedFromNewTable) {
+            return evaluateVoucherValidity(resolvedFromNewTable, input);
+        }
+        // Fallback path: legacy payment_instruments rows with instrumentType =
+        // 'voucher' and balance carried in metadata JSONB. Kept working until the
+        // migration script flips remaining rows over to the new table.
         const voucherConditions = [
             eq(paymentInstruments.instrumentType, "voucher"),
-            or(sql `lower(coalesce(${paymentInstruments.externalToken}, '')) = ${normalizedCode}`, sql `lower(coalesce(${paymentInstruments.directBillReference}, '')) = ${normalizedCode}`, sql `lower(coalesce(${paymentInstruments.metadata} ->> 'code', '')) = ${normalizedCode}`),
+            or(sql `lower(coalesce(${paymentInstruments.externalToken}, '')) = ${normalizedCodeLower}`, sql `lower(coalesce(${paymentInstruments.directBillReference}, '')) = ${normalizedCodeLower}`, sql `lower(coalesce(${paymentInstruments.metadata} ->> 'code', '')) = ${normalizedCodeLower}`),
         ];
         if (input.provider) {
             voucherConditions.push(eq(paymentInstruments.provider, input.provider));
@@ -380,7 +390,7 @@ export const publicFinanceService = {
         const bookingIds = getMetadataStringArray(metadata, "bookingIds");
         const bookingId = getMetadataString(metadata, "bookingId");
         const appliesToBookingIds = bookingId ? [bookingId, ...bookingIds] : bookingIds;
-        const publicVoucher = {
+        return evaluateVoucherValidity({
             id: voucher.id,
             code: voucherCode,
             label: voucher.label,
@@ -388,38 +398,71 @@ export const publicFinanceService = {
             currency,
             amountCents,
             remainingAmountCents,
+            validFrom,
             expiresAt,
-        };
-        if (voucher.status !== "active") {
-            return { valid: false, reason: "inactive", voucher: publicVoucher };
-        }
-        if (validFrom && new Date(validFrom) > new Date()) {
-            return { valid: false, reason: "not_started", voucher: publicVoucher };
-        }
-        if (expiresAt && new Date(expiresAt) < new Date()) {
-            return { valid: false, reason: "expired", voucher: publicVoucher };
-        }
-        if (input.bookingId &&
-            appliesToBookingIds.length > 0 &&
-            !appliesToBookingIds.includes(input.bookingId)) {
-            return { valid: false, reason: "booking_mismatch", voucher: publicVoucher };
-        }
-        if (input.currency && currency && input.currency !== currency) {
-            return {
-                valid: false,
-                reason: "currency_mismatch",
-                voucher: publicVoucher,
-            };
-        }
-        if (input.amountCents &&
-            remainingAmountCents !== null &&
-            input.amountCents > remainingAmountCents) {
-            return {
-                valid: false,
-                reason: "insufficient_balance",
-                voucher: publicVoucher,
-            };
-        }
-        return { valid: true, reason: null, voucher: publicVoucher };
+            appliesToBookingIds,
+            status: voucher.status === "active" ? "active" : "inactive",
+        }, input);
     },
 };
+async function resolveVoucherFromNewTable(db, code) {
+    const [row] = await db
+        .select()
+        .from(vouchers)
+        .where(sql `lower(${vouchers.code}) = ${code.toLowerCase()}`)
+        .limit(1);
+    if (!row)
+        return null;
+    return {
+        id: row.id,
+        code: row.code,
+        label: null,
+        provider: null,
+        currency: row.currency,
+        amountCents: row.initialAmountCents,
+        remainingAmountCents: row.remainingAmountCents,
+        validFrom: row.validFrom ? row.validFrom.toISOString() : null,
+        expiresAt: row.expiresAt ? row.expiresAt.toISOString() : null,
+        appliesToBookingIds: row.sourceBookingId ? [row.sourceBookingId] : [],
+        status: row.status === "active" ? "active" : "inactive",
+    };
+}
+function evaluateVoucherValidity(voucher, input) {
+    const publicVoucher = {
+        id: voucher.id,
+        code: voucher.code,
+        label: voucher.label,
+        provider: voucher.provider,
+        currency: voucher.currency,
+        amountCents: voucher.amountCents,
+        remainingAmountCents: voucher.remainingAmountCents,
+        expiresAt: voucher.expiresAt,
+    };
+    if (voucher.status !== "active") {
+        return { valid: false, reason: "inactive", voucher: publicVoucher };
+    }
+    if (voucher.validFrom && new Date(voucher.validFrom) > new Date()) {
+        return { valid: false, reason: "not_started", voucher: publicVoucher };
+    }
+    if (voucher.expiresAt && new Date(voucher.expiresAt) < new Date()) {
+        return { valid: false, reason: "expired", voucher: publicVoucher };
+    }
+    if (input.bookingId &&
+        voucher.appliesToBookingIds.length > 0 &&
+        !voucher.appliesToBookingIds.includes(input.bookingId)) {
+        return { valid: false, reason: "booking_mismatch", voucher: publicVoucher };
+    }
+    if (input.currency && voucher.currency && input.currency !== voucher.currency) {
+        return { valid: false, reason: "currency_mismatch", voucher: publicVoucher };
+    }
+    if (input.amountCents &&
+        voucher.remainingAmountCents !== null &&
+        input.amountCents > voucher.remainingAmountCents) {
+        return {
+            valid: false,
+            reason: "insufficient_balance",
+            voucher: publicVoucher,
+        };
+    }
+    return { valid: true, reason: null, voucher: publicVoucher };
+}

package/dist/service-vouchers-migration.d.ts

@@ -0,0 +1,44 @@
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+export interface VoucherMigrationOptions {
+    /**
+     * When true, report what would happen without writing. Defaults to false.
+     */
+    dryRun?: boolean;
+    /**
+     * Per-row hook for progress reporting. Not called on skipped rows.
+     */
+    onRowMigrated?: (info: {
+        paymentInstrumentId: string;
+        voucherCode: string;
+    }) => void;
+}
+export interface VoucherMigrationSkip {
+    paymentInstrumentId: string;
+    reason: "already_migrated" | "missing_code" | "missing_currency" | "missing_amount" | "duplicate_code_collision";
+}
+export interface VoucherMigrationResult {
+    candidates: number;
+    migrated: number;
+    skipped: VoucherMigrationSkip[];
+    dryRun: boolean;
+}
+/**
+ * Backfill the `vouchers` table from legacy voucher rows in
+ * `payment_instruments`. A legacy voucher is a row with `instrumentType =
+ * 'voucher'` whose code lives in one of `metadata.code`, `external_token`, or
+ * `direct_bill_reference`, and whose balance lives in
+ * `metadata.remainingAmountCents` (falling back to `metadata.amountCents` when
+ * no redemption has touched the row).
+ *
+ * The migration is idempotent: rows whose code already exists in the new
+ * `vouchers` table are skipped so re-running the script after a partial run
+ * (or after issuing new vouchers via the first-class API) is safe.
+ *
+ * Why skip rather than update: the new table treats `code` as a primary lookup
+ * key and the legacy path has already been read-only-fallback since #256
+ * landed, so any voucher that exists in both tables is by definition already
+ * migrated. Picking one source of truth avoids clobbering balances the
+ * operator may have adjusted through the new redemption flow.
+ */
+export declare function migrateVouchersFromPaymentInstruments(db: PostgresJsDatabase, options?: VoucherMigrationOptions): Promise<VoucherMigrationResult>;
+//# sourceMappingURL=service-vouchers-migration.d.ts.map

package/dist/service-vouchers-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-vouchers-migration.d.ts","sourceRoot":"","sources":["../src/service-vouchers-migration.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAsCjE,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,mBAAmB,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;CACrF;AAED,MAAM,WAAW,oBAAoB;IACnC,mBAAmB,EAAE,MAAM,CAAA;IAC3B,MAAM,EACF,kBAAkB,GAClB,cAAc,GACd,kBAAkB,GAClB,gBAAgB,GAChB,0BAA0B,CAAA;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,oBAAoB,EAAE,CAAA;IAC/B,MAAM,EAAE,OAAO,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,qCAAqC,CACzD,EAAE,EAAE,kBAAkB,EACtB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CA4GjC"}