@voyantjs/finance 0.3.0 → 0.4.0

package/dist/service-public.d.ts

@@ -0,0 +1,251 @@
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { PublicBookingFinanceDocuments, PublicBookingFinancePayments, PublicPaymentOptionsQuery, PublicStartPaymentSessionInput, PublicValidateVoucherInput } from "./validation-public.js";
+export declare const publicFinanceService: {
+    getBookingDocuments(db: PostgresJsDatabase, bookingId: string): Promise<PublicBookingFinanceDocuments | null>;
+    getBookingPaymentOptions(db: PostgresJsDatabase, bookingId: string, query: PublicPaymentOptionsQuery): Promise<{
+        bookingId: string;
+        accounts: {
+            id: string;
+            label: string;
+            provider: string | null;
+            instrumentType: "other" | "voucher" | "wallet" | "credit_card" | "debit_card" | "cash" | "direct_bill" | "bank_account";
+            status: "expired" | "revoked" | "active" | "inactive" | "failed_verification";
+            brand: string | null;
+            last4: string | null;
+            expiryMonth: number | null;
+            expiryYear: number | null;
+            isDefault: boolean;
+        }[];
+        schedules: {
+            id: string;
+            scheduleType: "other" | "deposit" | "installment" | "balance" | "hold";
+            status: "expired" | "cancelled" | "pending" | "paid" | "due" | "waived";
+            dueDate: string;
+            currency: string;
+            amountCents: number;
+            notes: string | null;
+        }[];
+        guarantees: {
+            id: string;
+            bookingPaymentScheduleId: string | null;
+            guaranteeType: "other" | "voucher" | "bank_transfer" | "credit_card" | "deposit" | "preauth" | "card_on_file" | "agency_letter";
+            status: "expired" | "cancelled" | "pending" | "released" | "failed" | "active";
+            currency: string | null;
+            amountCents: number | null;
+            provider: string | null;
+            referenceNumber: string | null;
+            expiresAt: string | null;
+            notes: string | null;
+        }[];
+        recommendedTarget: {
+            targetType: "booking_payment_schedule" | "booking_guarantee";
+            targetId: string | null;
+        } | null;
+    } | null>;
+    getBookingPayments(db: PostgresJsDatabase, bookingId: string): Promise<PublicBookingFinancePayments | null>;
+    getPaymentSession(db: PostgresJsDatabase, sessionId: string): Promise<{
+        id: string;
+        targetType: "other" | "booking" | "order" | "invoice" | "booking_payment_schedule" | "booking_guarantee";
+        targetId: string | null;
+        bookingId: string | null;
+        invoiceId: string | null;
+        bookingPaymentScheduleId: string | null;
+        bookingGuaranteeId: string | null;
+        status: "expired" | "cancelled" | "pending" | "failed" | "paid" | "requires_redirect" | "processing" | "authorized";
+        provider: string | null;
+        providerSessionId: string | null;
+        providerPaymentId: string | null;
+        externalReference: string | null;
+        clientReference: string | null;
+        currency: string;
+        amountCents: number;
+        paymentMethod: "other" | "voucher" | "wallet" | "bank_transfer" | "credit_card" | "debit_card" | "cash" | "cheque" | "direct_bill" | null;
+        payerEmail: string | null;
+        payerName: string | null;
+        redirectUrl: string | null;
+        returnUrl: string | null;
+        cancelUrl: string | null;
+        expiresAt: string | null;
+        completedAt: string | null;
+        failureCode: string | null;
+        failureMessage: string | null;
+    } | null>;
+    startBookingSchedulePaymentSession(db: PostgresJsDatabase, bookingId: string, scheduleId: string, input: PublicStartPaymentSessionInput): Promise<{
+        id: string;
+        targetType: "other" | "booking" | "order" | "invoice" | "booking_payment_schedule" | "booking_guarantee";
+        targetId: string | null;
+        bookingId: string | null;
+        invoiceId: string | null;
+        bookingPaymentScheduleId: string | null;
+        bookingGuaranteeId: string | null;
+        status: "expired" | "cancelled" | "pending" | "failed" | "paid" | "requires_redirect" | "processing" | "authorized";
+        provider: string | null;
+        providerSessionId: string | null;
+        providerPaymentId: string | null;
+        externalReference: string | null;
+        clientReference: string | null;
+        currency: string;
+        amountCents: number;
+        paymentMethod: "other" | "voucher" | "wallet" | "bank_transfer" | "credit_card" | "debit_card" | "cash" | "cheque" | "direct_bill" | null;
+        payerEmail: string | null;
+        payerName: string | null;
+        redirectUrl: string | null;
+        returnUrl: string | null;
+        cancelUrl: string | null;
+        expiresAt: string | null;
+        completedAt: string | null;
+        failureCode: string | null;
+        failureMessage: string | null;
+    } | null>;
+    startBookingGuaranteePaymentSession(db: PostgresJsDatabase, bookingId: string, guaranteeId: string, input: PublicStartPaymentSessionInput): Promise<{
+        id: string;
+        targetType: "other" | "booking" | "order" | "invoice" | "booking_payment_schedule" | "booking_guarantee";
+        targetId: string | null;
+        bookingId: string | null;
+        invoiceId: string | null;
+        bookingPaymentScheduleId: string | null;
+        bookingGuaranteeId: string | null;
+        status: "expired" | "cancelled" | "pending" | "failed" | "paid" | "requires_redirect" | "processing" | "authorized";
+        provider: string | null;
+        providerSessionId: string | null;
+        providerPaymentId: string | null;
+        externalReference: string | null;
+        clientReference: string | null;
+        currency: string;
+        amountCents: number;
+        paymentMethod: "other" | "voucher" | "wallet" | "bank_transfer" | "credit_card" | "debit_card" | "cash" | "cheque" | "direct_bill" | null;
+        payerEmail: string | null;
+        payerName: string | null;
+        redirectUrl: string | null;
+        returnUrl: string | null;
+        cancelUrl: string | null;
+        expiresAt: string | null;
+        completedAt: string | null;
+        failureCode: string | null;
+        failureMessage: string | null;
+    } | null>;
+    startInvoicePaymentSession(db: PostgresJsDatabase, invoiceId: string, input: PublicStartPaymentSessionInput): Promise<{
+        id: string;
+        targetType: "other" | "booking" | "order" | "invoice" | "booking_payment_schedule" | "booking_guarantee";
+        targetId: string | null;
+        bookingId: string | null;
+        invoiceId: string | null;
+        bookingPaymentScheduleId: string | null;
+        bookingGuaranteeId: string | null;
+        status: "expired" | "cancelled" | "pending" | "failed" | "paid" | "requires_redirect" | "processing" | "authorized";
+        provider: string | null;
+        providerSessionId: string | null;
+        providerPaymentId: string | null;
+        externalReference: string | null;
+        clientReference: string | null;
+        currency: string;
+        amountCents: number;
+        paymentMethod: "other" | "voucher" | "wallet" | "bank_transfer" | "credit_card" | "debit_card" | "cash" | "cheque" | "direct_bill" | null;
+        payerEmail: string | null;
+        payerName: string | null;
+        redirectUrl: string | null;
+        returnUrl: string | null;
+        cancelUrl: string | null;
+        expiresAt: string | null;
+        completedAt: string | null;
+        failureCode: string | null;
+        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;
+            provider: string | null;
+            currency: string | null;
+            amountCents: number | null;
+            remainingAmountCents: number | null;
+            expiresAt: string | null;
+        };
+    } | {
+        valid: false;
+        reason: "not_started";
+        voucher: {
+            id: string;
+            code: string;
+            label: string;
+            provider: string | null;
+            currency: string | null;
+            amountCents: number | null;
+            remainingAmountCents: number | null;
+            expiresAt: string | null;
+        };
+    } | {
+        valid: false;
+        reason: "expired";
+        voucher: {
+            id: string;
+            code: string;
+            label: string;
+            provider: string | null;
+            currency: string | null;
+            amountCents: number | null;
+            remainingAmountCents: number | null;
+            expiresAt: string | null;
+        };
+    } | {
+        valid: false;
+        reason: "booking_mismatch";
+        voucher: {
+            id: string;
+            code: string;
+            label: string;
+            provider: string | null;
+            currency: string | null;
+            amountCents: number | null;
+            remainingAmountCents: number | null;
+            expiresAt: string | null;
+        };
+    } | {
+        valid: false;
+        reason: "currency_mismatch";
+        voucher: {
+            id: string;
+            code: string;
+            label: string;
+            provider: string | null;
+            currency: string | null;
+            amountCents: number | null;
+            remainingAmountCents: number | null;
+            expiresAt: string | null;
+        };
+    } | {
+        valid: false;
+        reason: "insufficient_balance";
+        voucher: {
+            id: string;
+            code: string;
+            label: string;
+            provider: string | null;
+            currency: string | null;
+            amountCents: number | null;
+            remainingAmountCents: number | null;
+            expiresAt: string | null;
+        };
+    } | {
+        valid: true;
+        reason: null;
+        voucher: {
+            id: string;
+            code: string;
+            label: string;
+            provider: string | null;
+            currency: string | null;
+            amountCents: number | null;
+            remainingAmountCents: number | null;
+            expiresAt: string | null;
+        };
+    }>;
+};
+//# sourceMappingURL=service-public.d.ts.map

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

@@ -0,0 +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,EAC5B,yBAAyB,EACzB,8BAA8B,EAC9B,0BAA0B,EAC3B,MAAM,wBAAwB,CAAA;AA4H/B,eAAO,MAAM,oBAAoB;4BAEzB,kBAAkB,aACX,MAAM,GAChB,OAAO,CAAC,6BAA6B,GAAG,IAAI,CAAC;iCAqE1C,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"}

package/dist/service-public.js

@@ -0,0 +1,418 @@
+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 { financeService } from "./service.js";
+function normalizeDateTime(value) {
+    if (!value) {
+        return null;
+    }
+    return value instanceof Date ? value.toISOString() : value;
+}
+function isDefaultInstrument(metadata) {
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+        return false;
+    }
+    const record = metadata;
+    return record.default === true || record.isDefault === true;
+}
+function getMetadataRecord(metadata) {
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+        return null;
+    }
+    return metadata;
+}
+function getMetadataString(record, key) {
+    const value = record?.[key];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function getMetadataNumber(record, key) {
+    const value = record?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function getMetadataStringArray(record, key) {
+    const value = record?.[key];
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => typeof entry === "string" && entry.length > 0);
+}
+function maybeUrl(value) {
+    if (!value) {
+        return null;
+    }
+    return /^https?:\/\//i.test(value) ? value : null;
+}
+function getMetadataDownloadUrl(record) {
+    const directKeys = [
+        "downloadUrl",
+        "download_url",
+        "signedUrl",
+        "signed_url",
+        "publicUrl",
+        "public_url",
+        "fileUrl",
+        "file_url",
+        "url",
+    ];
+    for (const key of directKeys) {
+        const value = getMetadataString(record, key);
+        const url = maybeUrl(value);
+        if (url) {
+            return url;
+        }
+    }
+    const artifact = record?.artifact;
+    if (artifact && typeof artifact === "object" && !Array.isArray(artifact)) {
+        const nested = artifact;
+        for (const key of ["downloadUrl", "download_url", "signedUrl", "publicUrl", "url"]) {
+            const value = nested[key];
+            if (typeof value === "string") {
+                const url = maybeUrl(value);
+                if (url) {
+                    return url;
+                }
+            }
+        }
+    }
+    return null;
+}
+function toPublicPaymentSession(session) {
+    return {
+        id: session.id,
+        targetType: session.targetType,
+        targetId: session.targetId ?? null,
+        bookingId: session.bookingId ?? null,
+        invoiceId: session.invoiceId ?? null,
+        bookingPaymentScheduleId: session.bookingPaymentScheduleId ?? null,
+        bookingGuaranteeId: session.bookingGuaranteeId ?? null,
+        status: session.status,
+        provider: session.provider ?? null,
+        providerSessionId: session.providerSessionId ?? null,
+        providerPaymentId: session.providerPaymentId ?? null,
+        externalReference: session.externalReference ?? null,
+        clientReference: session.clientReference ?? null,
+        currency: session.currency,
+        amountCents: session.amountCents,
+        paymentMethod: session.paymentMethod ?? null,
+        payerEmail: session.payerEmail ?? null,
+        payerName: session.payerName ?? null,
+        redirectUrl: session.redirectUrl ?? null,
+        returnUrl: session.returnUrl ?? null,
+        cancelUrl: session.cancelUrl ?? null,
+        expiresAt: normalizeDateTime(session.expiresAt),
+        completedAt: normalizeDateTime(session.completedAt),
+        failureCode: session.failureCode ?? null,
+        failureMessage: session.failureMessage ?? null,
+    };
+}
+export const publicFinanceService = {
+    async getBookingDocuments(db, bookingId) {
+        const [booking] = await db
+            .select({ id: bookings.id })
+            .from(bookings)
+            .where(eq(bookings.id, bookingId))
+            .limit(1);
+        if (!booking) {
+            return null;
+        }
+        const invoiceRows = await db
+            .select()
+            .from(invoices)
+            .where(eq(invoices.bookingId, bookingId))
+            .orderBy(desc(invoices.createdAt));
+        if (invoiceRows.length === 0) {
+            return { bookingId, documents: [] };
+        }
+        const renditionRows = await db
+            .select()
+            .from(invoiceRenditions)
+            .where(or(...invoiceRows.map((invoice) => eq(invoiceRenditions.invoiceId, invoice.id))))
+            .orderBy(desc(invoiceRenditions.createdAt));
+        const renditionByInvoiceId = new Map();
+        for (const rendition of renditionRows) {
+            const existing = renditionByInvoiceId.get(rendition.invoiceId) ?? [];
+            existing.push(rendition);
+            renditionByInvoiceId.set(rendition.invoiceId, existing);
+        }
+        return {
+            bookingId,
+            documents: invoiceRows.map((invoice) => {
+                const renditions = renditionByInvoiceId.get(invoice.id) ?? [];
+                const selectedRendition = renditions.find((rendition) => rendition.status === "ready") ?? renditions[0] ?? null;
+                const metadata = getMetadataRecord(selectedRendition?.metadata ?? null);
+                const downloadUrl = getMetadataDownloadUrl(metadata) ?? maybeUrl(selectedRendition?.storageKey ?? null);
+                return {
+                    invoiceId: invoice.id,
+                    invoiceNumber: invoice.invoiceNumber,
+                    invoiceType: invoice.invoiceType,
+                    invoiceStatus: invoice.status,
+                    currency: invoice.currency,
+                    totalCents: invoice.totalCents,
+                    paidCents: invoice.paidCents,
+                    balanceDueCents: invoice.balanceDueCents,
+                    issueDate: invoice.issueDate,
+                    dueDate: invoice.dueDate,
+                    renditionId: selectedRendition?.id ?? null,
+                    documentStatus: selectedRendition?.status ?? "missing",
+                    format: selectedRendition?.format ?? null,
+                    language: selectedRendition?.language ?? null,
+                    generatedAt: normalizeDateTime(selectedRendition?.generatedAt),
+                    fileSize: selectedRendition?.fileSize ?? null,
+                    checksum: selectedRendition?.checksum ?? null,
+                    downloadUrl,
+                };
+            }),
+        };
+    },
+    async getBookingPaymentOptions(db, bookingId, query) {
+        const [booking] = await db
+            .select({ id: bookings.id })
+            .from(bookings)
+            .where(eq(bookings.id, bookingId))
+            .limit(1);
+        if (!booking) {
+            return null;
+        }
+        const instrumentConditions = [eq(paymentInstruments.ownerType, "client")];
+        if (!query.includeInactive) {
+            instrumentConditions.push(eq(paymentInstruments.status, "active"));
+        }
+        if (query.personId) {
+            instrumentConditions.push(eq(paymentInstruments.personId, query.personId));
+        }
+        if (query.organizationId) {
+            instrumentConditions.push(eq(paymentInstruments.organizationId, query.organizationId));
+        }
+        if (query.provider) {
+            instrumentConditions.push(eq(paymentInstruments.provider, query.provider));
+        }
+        if (query.instrumentType) {
+            instrumentConditions.push(eq(paymentInstruments.instrumentType, query.instrumentType));
+        }
+        const [accounts, schedules, guarantees] = await Promise.all([
+            db
+                .select()
+                .from(paymentInstruments)
+                .where(and(...instrumentConditions))
+                .orderBy(desc(paymentInstruments.updatedAt))
+                .limit(50),
+            db
+                .select()
+                .from(bookingPaymentSchedules)
+                .where(and(eq(bookingPaymentSchedules.bookingId, bookingId), or(eq(bookingPaymentSchedules.status, "pending"), eq(bookingPaymentSchedules.status, "due"))))
+                .orderBy(asc(bookingPaymentSchedules.dueDate), asc(bookingPaymentSchedules.createdAt)),
+            db
+                .select()
+                .from(bookingGuarantees)
+                .where(and(eq(bookingGuarantees.bookingId, bookingId), or(eq(bookingGuarantees.status, "pending"), eq(bookingGuarantees.status, "failed"), eq(bookingGuarantees.status, "expired"))))
+                .orderBy(desc(bookingGuarantees.createdAt)),
+        ]);
+        const recommendedSchedule = schedules[0] ?? null;
+        const recommendedGuarantee = recommendedSchedule === null ? (guarantees[0] ?? null) : null;
+        return {
+            bookingId,
+            accounts: accounts.map((account) => ({
+                id: account.id,
+                label: account.label,
+                provider: account.provider ?? null,
+                instrumentType: account.instrumentType,
+                status: account.status,
+                brand: account.brand ?? null,
+                last4: account.last4 ?? null,
+                expiryMonth: account.expiryMonth ?? null,
+                expiryYear: account.expiryYear ?? null,
+                isDefault: isDefaultInstrument(account.metadata),
+            })),
+            schedules: schedules.map((schedule) => ({
+                id: schedule.id,
+                scheduleType: schedule.scheduleType,
+                status: schedule.status,
+                dueDate: schedule.dueDate,
+                currency: schedule.currency,
+                amountCents: schedule.amountCents,
+                notes: schedule.notes ?? null,
+            })),
+            guarantees: guarantees.map((guarantee) => ({
+                id: guarantee.id,
+                bookingPaymentScheduleId: guarantee.bookingPaymentScheduleId ?? null,
+                guaranteeType: guarantee.guaranteeType,
+                status: guarantee.status,
+                currency: guarantee.currency ?? null,
+                amountCents: guarantee.amountCents ?? null,
+                provider: guarantee.provider ?? null,
+                referenceNumber: guarantee.referenceNumber ?? null,
+                expiresAt: normalizeDateTime(guarantee.expiresAt),
+                notes: guarantee.notes ?? null,
+            })),
+            recommendedTarget: recommendedSchedule || recommendedGuarantee
+                ? {
+                    targetType: recommendedSchedule
+                        ? "booking_payment_schedule"
+                        : "booking_guarantee",
+                    targetId: recommendedSchedule?.id ?? recommendedGuarantee?.id ?? null,
+                }
+                : null,
+        };
+    },
+    async getBookingPayments(db, bookingId) {
+        const [booking] = await db
+            .select({ id: bookings.id })
+            .from(bookings)
+            .where(eq(bookings.id, bookingId))
+            .limit(1);
+        if (!booking) {
+            return null;
+        }
+        const invoiceRows = await db
+            .select({
+            id: invoices.id,
+            invoiceNumber: invoices.invoiceNumber,
+            invoiceType: invoices.invoiceType,
+        })
+            .from(invoices)
+            .where(eq(invoices.bookingId, bookingId))
+            .orderBy(desc(invoices.createdAt));
+        if (invoiceRows.length === 0) {
+            return { bookingId, payments: [] };
+        }
+        const invoiceById = new Map(invoiceRows.map((invoice) => [invoice.id, invoice]));
+        const paymentRows = await db
+            .select()
+            .from(payments)
+            .where(or(...invoiceRows.map((invoice) => eq(payments.invoiceId, invoice.id))))
+            .orderBy(desc(payments.paymentDate), desc(payments.createdAt));
+        return {
+            bookingId,
+            payments: paymentRows.flatMap((payment) => {
+                const invoice = invoiceById.get(payment.invoiceId);
+                if (!invoice) {
+                    return [];
+                }
+                return [
+                    {
+                        id: payment.id,
+                        invoiceId: invoice.id,
+                        invoiceNumber: invoice.invoiceNumber,
+                        invoiceType: invoice.invoiceType,
+                        status: payment.status,
+                        paymentMethod: payment.paymentMethod,
+                        amountCents: payment.amountCents,
+                        currency: payment.currency,
+                        paymentDate: payment.paymentDate,
+                        referenceNumber: payment.referenceNumber ?? null,
+                        notes: payment.notes ?? null,
+                    },
+                ];
+            }),
+        };
+    },
+    async getPaymentSession(db, sessionId) {
+        const session = await financeService.getPaymentSessionById(db, sessionId);
+        return session ? toPublicPaymentSession(session) : null;
+    },
+    async startBookingSchedulePaymentSession(db, bookingId, scheduleId, input) {
+        const [schedule] = await db
+            .select({
+            id: bookingPaymentSchedules.id,
+        })
+            .from(bookingPaymentSchedules)
+            .where(and(eq(bookingPaymentSchedules.id, scheduleId), eq(bookingPaymentSchedules.bookingId, bookingId)))
+            .limit(1);
+        if (!schedule) {
+            return null;
+        }
+        const session = await financeService.createPaymentSessionFromBookingSchedule(db, scheduleId, input);
+        return session ? toPublicPaymentSession(session) : null;
+    },
+    async startBookingGuaranteePaymentSession(db, bookingId, guaranteeId, input) {
+        const [guarantee] = await db
+            .select({
+            id: bookingGuarantees.id,
+        })
+            .from(bookingGuarantees)
+            .where(and(eq(bookingGuarantees.id, guaranteeId), eq(bookingGuarantees.bookingId, bookingId)))
+            .limit(1);
+        if (!guarantee) {
+            return null;
+        }
+        const session = await financeService.createPaymentSessionFromBookingGuarantee(db, guaranteeId, input);
+        return session ? toPublicPaymentSession(session) : null;
+    },
+    async startInvoicePaymentSession(db, invoiceId, input) {
+        const session = await financeService.createPaymentSessionFromInvoice(db, invoiceId, input);
+        return session ? toPublicPaymentSession(session) : null;
+    },
+    async validateVoucher(db, input) {
+        const normalizedCode = input.code.trim().toLowerCase();
+        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}`),
+        ];
+        if (input.provider) {
+            voucherConditions.push(eq(paymentInstruments.provider, input.provider));
+        }
+        const [voucher] = await db
+            .select()
+            .from(paymentInstruments)
+            .where(and(...voucherConditions))
+            .orderBy(desc(paymentInstruments.updatedAt))
+            .limit(1);
+        if (!voucher) {
+            return { valid: false, reason: "not_found", voucher: null };
+        }
+        const metadata = getMetadataRecord(voucher.metadata);
+        const voucherCode = getMetadataString(metadata, "code") ??
+            voucher.externalToken ??
+            voucher.directBillReference ??
+            input.code;
+        const currency = getMetadataString(metadata, "currency");
+        const amountCents = getMetadataNumber(metadata, "amountCents");
+        const remainingAmountCents = getMetadataNumber(metadata, "remainingAmountCents") ?? amountCents;
+        const validFrom = getMetadataString(metadata, "validFrom");
+        const expiresAt = getMetadataString(metadata, "expiresAt");
+        const bookingIds = getMetadataStringArray(metadata, "bookingIds");
+        const bookingId = getMetadataString(metadata, "bookingId");
+        const appliesToBookingIds = bookingId ? [bookingId, ...bookingIds] : bookingIds;
+        const publicVoucher = {
+            id: voucher.id,
+            code: voucherCode,
+            label: voucher.label,
+            provider: voucher.provider ?? null,
+            currency,
+            amountCents,
+            remainingAmountCents,
+            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 };
+    },
+};