@voyant-travel/finance 0.167.0 → 0.168.0

package/dist/service-vouchers.d.ts

@@ -0,0 +1,157 @@
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { z } from "zod";
+import type { insertVoucherSchema, redeemVoucherSchema, updateVoucherSchema, voucherListQuerySchema } from "./validation-vouchers.js";
+type CreateVoucherInput = z.infer<typeof insertVoucherSchema>;
+type UpdateVoucherInput = z.infer<typeof updateVoucherSchema>;
+type RedeemVoucherInput = z.infer<typeof redeemVoucherSchema>;
+type VoucherListQuery = z.infer<typeof voucherListQuerySchema>;
+/**
+ * Raised by the voucher service. Code + message; route handlers map to HTTP.
+ * Reasons the route layer cares about:
+ *  - `code_in_use`        — supplied code collides with an existing voucher
+ *  - `voucher_not_found`  — id-not-found / code-not-found read path
+ *  - `voucher_inactive`   — redeem attempted against non-active status
+ *  - `voucher_not_started`— validFrom is set and hasn't happened yet
+ *  - `voucher_expired`    — expiresAt has passed
+ *  - `insufficient_balance` — requested amount > remainingAmountCents
+ */
+export declare class VoucherServiceError extends Error {
+    readonly code: "code_in_use" | "voucher_not_found" | "voucher_inactive" | "voucher_not_started" | "voucher_expired" | "insufficient_balance";
+    constructor(code: "code_in_use" | "voucher_not_found" | "voucher_inactive" | "voucher_not_started" | "voucher_expired" | "insufficient_balance", message?: string);
+}
+export declare const vouchersService: {
+    list(db: PostgresJsDatabase, query: VoucherListQuery): Promise<{
+        data: {
+            id: string;
+            code: string;
+            seriesCode: string | null;
+            status: "void" | "expired" | "active" | "redeemed";
+            currency: string;
+            initialAmountCents: number;
+            remainingAmountCents: number;
+            issuedToPersonId: string | null;
+            issuedToOrganizationId: string | null;
+            sourceType: "manual" | "refund" | "cancellation_credit" | "gift" | "promo";
+            sourceBookingId: string | null;
+            sourcePaymentId: string | null;
+            validFrom: Date | null;
+            expiresAt: Date | null;
+            notes: string | null;
+            issuedByUserId: string | null;
+            createdAt: Date;
+            updatedAt: Date;
+        }[];
+        total: number;
+        limit: number;
+        offset: number;
+    }>;
+    getById(db: PostgresJsDatabase, id: string): Promise<{
+        redemptions: {
+            id: string;
+            voucherId: string;
+            bookingId: string;
+            paymentId: string | null;
+            amountCents: number;
+            createdAt: Date;
+            createdByUserId: string | null;
+        }[];
+        id: string;
+        code: string;
+        seriesCode: string | null;
+        status: "void" | "expired" | "active" | "redeemed";
+        currency: string;
+        initialAmountCents: number;
+        remainingAmountCents: number;
+        issuedToPersonId: string | null;
+        issuedToOrganizationId: string | null;
+        sourceType: "manual" | "refund" | "cancellation_credit" | "gift" | "promo";
+        sourceBookingId: string | null;
+        sourcePaymentId: string | null;
+        validFrom: Date | null;
+        expiresAt: Date | null;
+        notes: string | null;
+        issuedByUserId: string | null;
+        createdAt: Date;
+        updatedAt: Date;
+    } | null>;
+    create(db: PostgresJsDatabase, input: CreateVoucherInput, issuedByUserId?: string): Promise<{
+        id: string;
+        status: "void" | "expired" | "active" | "redeemed";
+        notes: string | null;
+        createdAt: Date;
+        updatedAt: Date;
+        currency: string;
+        expiresAt: Date | null;
+        code: string;
+        seriesCode: string | null;
+        initialAmountCents: number;
+        remainingAmountCents: number;
+        issuedToPersonId: string | null;
+        issuedToOrganizationId: string | null;
+        sourceType: "manual" | "refund" | "cancellation_credit" | "gift" | "promo";
+        sourceBookingId: string | null;
+        sourcePaymentId: string | null;
+        validFrom: Date | null;
+        issuedByUserId: string | null;
+    } | null>;
+    update(db: PostgresJsDatabase, id: string, input: UpdateVoucherInput): Promise<{
+        id: string;
+        code: string;
+        seriesCode: string | null;
+        status: "void" | "expired" | "active" | "redeemed";
+        currency: string;
+        initialAmountCents: number;
+        remainingAmountCents: number;
+        issuedToPersonId: string | null;
+        issuedToOrganizationId: string | null;
+        sourceType: "manual" | "refund" | "cancellation_credit" | "gift" | "promo";
+        sourceBookingId: string | null;
+        sourcePaymentId: string | null;
+        validFrom: Date | null;
+        expiresAt: Date | null;
+        notes: string | null;
+        issuedByUserId: string | null;
+        createdAt: Date;
+        updatedAt: Date;
+    } | null>;
+    /**
+     * Apply a voucher against a booking. Runs in a transaction so
+     * `remainingAmountCents` and the redemption row either both land or neither.
+     * Guards: voucher must exist, be active, not expired, and have enough
+     * balance for the requested amount. When remaining hits zero the voucher
+     * flips to `status = 'redeemed'`.
+     */
+    redeem(db: PostgresJsDatabase, voucherId: string, input: RedeemVoucherInput, userId?: string): Promise<{
+        voucher: {
+            id: string;
+            code: string;
+            seriesCode: string | null;
+            status: "void" | "expired" | "active" | "redeemed";
+            currency: string;
+            initialAmountCents: number;
+            remainingAmountCents: number;
+            issuedToPersonId: string | null;
+            issuedToOrganizationId: string | null;
+            sourceType: "manual" | "refund" | "cancellation_credit" | "gift" | "promo";
+            sourceBookingId: string | null;
+            sourcePaymentId: string | null;
+            validFrom: Date | null;
+            expiresAt: Date | null;
+            notes: string | null;
+            issuedByUserId: string | null;
+            createdAt: Date;
+            updatedAt: Date;
+        };
+        redemption: {
+            id: string;
+            createdAt: Date;
+            bookingId: string;
+            amountCents: number;
+            paymentId: string | null;
+            voucherId: string;
+            createdByUserId: string | null;
+        } | null;
+    }>;
+};
+export {};
+//# sourceMappingURL=service-vouchers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"service-vouchers.d.ts","sourceRoot":"","sources":["../src/service-vouchers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AACjE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAG5B,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,0BAA0B,CAAA;AAEjC,KAAK,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAC7D,KAAK,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAC7D,KAAK,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAC7D,KAAK,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE9D;;;;;;;;;GASG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAE1C,QAAQ,CAAC,IAAI,EACT,aAAa,GACb,mBAAmB,GACnB,kBAAkB,GAClB,qBAAqB,GACrB,iBAAiB,GACjB,sBAAsB;gBANjB,IAAI,EACT,aAAa,GACb,mBAAmB,GACnB,kBAAkB,GAClB,qBAAqB,GACrB,iBAAiB,GACjB,sBAAsB,EAC1B,OAAO,CAAC,EAAE,MAAM;CAKnB;AAsBD,eAAO,MAAM,eAAe;aACX,kBAAkB,SAAS,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;gBAuCxC,kBAAkB,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAW/B,kBAAkB,SAAS,kBAAkB,mBAAmB,MAAM;;;;;;;;;;;;;;;;;;;;eAiCtE,kBAAkB,MAAM,MAAM,SAAS,kBAAkB;;;;;;;;;;;;;;;;;;;;IA0B1E;;;;;;OAMG;eAEG,kBAAkB,aACX,MAAM,SACV,kBAAkB,WAChB,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0ClB,CAAA"}

package/dist/service-vouchers.js

@@ -0,0 +1,191 @@
+import { and, asc, desc, eq, gt, ilike, or, sql } from "drizzle-orm";
+import { voucherRedemptions, vouchers } from "./schema.js";
+/**
+ * Raised by the voucher service. Code + message; route handlers map to HTTP.
+ * Reasons the route layer cares about:
+ *  - `code_in_use`        — supplied code collides with an existing voucher
+ *  - `voucher_not_found`  — id-not-found / code-not-found read path
+ *  - `voucher_inactive`   — redeem attempted against non-active status
+ *  - `voucher_not_started`— validFrom is set and hasn't happened yet
+ *  - `voucher_expired`    — expiresAt has passed
+ *  - `insufficient_balance` — requested amount > remainingAmountCents
+ */
+export class VoucherServiceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message ?? code);
+        this.code = code;
+        this.name = "VoucherServiceError";
+    }
+}
+const CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+/**
+ * Generate a short, human-friendly voucher code. Crockford-style alphabet
+ * (no 0/O/1/I) so codes stay readable when typed from a receipt or email.
+ * 12 chars from a 32-symbol alphabet ≈ 60 bits of entropy; unique-index on
+ * `code` catches the astronomically-unlikely collision.
+ */
+function generateVoucherCode() {
+    const bytes = new Uint8Array(12);
+    crypto.getRandomValues(bytes);
+    let out = "";
+    for (let i = 0; i < bytes.length; i++) {
+        const index = (bytes[i] ?? 0) % CODE_ALPHABET.length;
+        out += CODE_ALPHABET[index];
+        if (i === 3 || i === 7)
+            out += "-";
+    }
+    return out;
+}
+export const vouchersService = {
+    async list(db, query) {
+        const conditions = [];
+        if (query.status)
+            conditions.push(eq(vouchers.status, query.status));
+        if (query.seriesCode)
+            conditions.push(eq(vouchers.seriesCode, query.seriesCode));
+        if (query.issuedToPersonId) {
+            conditions.push(eq(vouchers.issuedToPersonId, query.issuedToPersonId));
+        }
+        if (query.issuedToOrganizationId) {
+            conditions.push(eq(vouchers.issuedToOrganizationId, query.issuedToOrganizationId));
+        }
+        if (query.hasBalance) {
+            conditions.push(gt(vouchers.remainingAmountCents, 0));
+        }
+        if (query.search) {
+            const term = `%${query.search}%`;
+            conditions.push(or(ilike(vouchers.code, term), ilike(vouchers.notes, term)));
+        }
+        const where = conditions.length ? and(...conditions) : undefined;
+        const [rows, countResult] = await Promise.all([
+            db
+                .select()
+                .from(vouchers)
+                .where(where)
+                .limit(query.limit)
+                .offset(query.offset)
+                .orderBy(desc(vouchers.createdAt)),
+            db.select({ count: sql `count(*)::int` }).from(vouchers).where(where),
+        ]);
+        return {
+            data: rows,
+            total: countResult[0]?.count ?? 0,
+            limit: query.limit,
+            offset: query.offset,
+        };
+    },
+    async getById(db, id) {
+        const [row] = await db.select().from(vouchers).where(eq(vouchers.id, id)).limit(1);
+        if (!row)
+            return null;
+        const redemptions = await db
+            .select()
+            .from(voucherRedemptions)
+            .where(eq(voucherRedemptions.voucherId, id))
+            .orderBy(asc(voucherRedemptions.createdAt));
+        return { ...row, redemptions };
+    },
+    async create(db, input, issuedByUserId) {
+        const code = input.code?.trim() || generateVoucherCode();
+        const [existing] = await db
+            .select({ id: vouchers.id })
+            .from(vouchers)
+            .where(eq(vouchers.code, code))
+            .limit(1);
+        if (existing) {
+            throw new VoucherServiceError("code_in_use");
+        }
+        const [row] = await db
+            .insert(vouchers)
+            .values({
+            code,
+            seriesCode: input.seriesCode ?? null,
+            currency: input.currency,
+            initialAmountCents: input.amountCents,
+            remainingAmountCents: input.amountCents,
+            issuedToPersonId: input.issuedToPersonId ?? null,
+            issuedToOrganizationId: input.issuedToOrganizationId ?? null,
+            sourceType: input.sourceType,
+            sourceBookingId: input.sourceBookingId ?? null,
+            sourcePaymentId: input.sourcePaymentId ?? null,
+            validFrom: input.validFrom ? new Date(input.validFrom) : null,
+            expiresAt: input.expiresAt ? new Date(input.expiresAt) : null,
+            notes: input.notes ?? null,
+            issuedByUserId: issuedByUserId ?? null,
+        })
+            .returning();
+        return row ?? null;
+    },
+    async update(db, id, input) {
+        const [row] = await db
+            .update(vouchers)
+            .set({
+            ...(input.status !== undefined ? { status: input.status } : {}),
+            ...(input.seriesCode !== undefined ? { seriesCode: input.seriesCode } : {}),
+            ...(input.validFrom !== undefined
+                ? { validFrom: input.validFrom ? new Date(input.validFrom) : null }
+                : {}),
+            ...(input.expiresAt !== undefined
+                ? { expiresAt: input.expiresAt ? new Date(input.expiresAt) : null }
+                : {}),
+            ...(input.notes !== undefined ? { notes: input.notes } : {}),
+            ...(input.issuedToPersonId !== undefined
+                ? { issuedToPersonId: input.issuedToPersonId }
+                : {}),
+            ...(input.issuedToOrganizationId !== undefined
+                ? { issuedToOrganizationId: input.issuedToOrganizationId }
+                : {}),
+            updatedAt: new Date(),
+        })
+            .where(eq(vouchers.id, id))
+            .returning();
+        return row ?? null;
+    },
+    /**
+     * Apply a voucher against a booking. Runs in a transaction so
+     * `remainingAmountCents` and the redemption row either both land or neither.
+     * Guards: voucher must exist, be active, not expired, and have enough
+     * balance for the requested amount. When remaining hits zero the voucher
+     * flips to `status = 'redeemed'`.
+     */
+    async redeem(db, voucherId, input, userId) {
+        return db.transaction(async (tx) => {
+            const [voucher] = await tx.select().from(vouchers).where(eq(vouchers.id, voucherId)).limit(1);
+            if (!voucher)
+                throw new VoucherServiceError("voucher_not_found");
+            if (voucher.status !== "active")
+                throw new VoucherServiceError("voucher_inactive");
+            if (voucher.validFrom && voucher.validFrom.getTime() > Date.now()) {
+                throw new VoucherServiceError("voucher_not_started");
+            }
+            if (voucher.expiresAt && voucher.expiresAt.getTime() < Date.now()) {
+                throw new VoucherServiceError("voucher_expired");
+            }
+            if (input.amountCents > voucher.remainingAmountCents) {
+                throw new VoucherServiceError("insufficient_balance");
+            }
+            const [redemption] = await tx
+                .insert(voucherRedemptions)
+                .values({
+                voucherId: voucher.id,
+                bookingId: input.bookingId,
+                paymentId: input.paymentId ?? null,
+                amountCents: input.amountCents,
+                createdByUserId: userId ?? null,
+            })
+                .returning();
+            const newRemaining = voucher.remainingAmountCents - input.amountCents;
+            const [updated] = await tx
+                .update(vouchers)
+                .set({
+                remainingAmountCents: newRemaining,
+                status: newRemaining === 0 ? "redeemed" : voucher.status,
+                updatedAt: new Date(),
+            })
+                .where(eq(vouchers.id, voucher.id))
+                .returning();
+            return { voucher: updated ?? voucher, redemption: redemption ?? null };
+        });
+    },
+};