@voyantjs/finance 0.6.8 → 0.7.0

package/dist/service-vouchers-migration.js

@@ -0,0 +1,147 @@
+import { eq, sql } from "drizzle-orm";
+import { paymentInstruments, vouchers } from "./schema.js";
+/**
+ * Pulls a (possibly nested, array-wrapped, or null) value out of a JSONB
+ * metadata column. Keeps the narrow runtime checks local so callers can stay
+ * declarative about the shape they expect.
+ */
+function asRecord(metadata) {
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+        return null;
+    }
+    return metadata;
+}
+function asString(record, key) {
+    const value = record?.[key];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function asNumber(record, key) {
+    const value = record?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function asStringArray(record, key) {
+    const value = record?.[key];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((entry) => typeof entry === "string" && entry.length > 0);
+}
+function asDate(value) {
+    if (!value)
+        return null;
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+/**
+ * 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 async function migrateVouchersFromPaymentInstruments(db, options = {}) {
+    const dryRun = options.dryRun ?? false;
+    const skipped = [];
+    let migrated = 0;
+    const candidates = await db
+        .select()
+        .from(paymentInstruments)
+        .where(eq(paymentInstruments.instrumentType, "voucher"));
+    for (const instrument of candidates) {
+        const metadata = asRecord(instrument.metadata);
+        const code = asString(metadata, "code") ?? instrument.externalToken ?? instrument.directBillReference;
+        if (!code) {
+            skipped.push({ paymentInstrumentId: instrument.id, reason: "missing_code" });
+            continue;
+        }
+        const currency = asString(metadata, "currency");
+        if (!currency || currency.length !== 3) {
+            skipped.push({ paymentInstrumentId: instrument.id, reason: "missing_currency" });
+            continue;
+        }
+        const initialAmountCents = asNumber(metadata, "amountCents");
+        if (initialAmountCents === null || initialAmountCents <= 0) {
+            skipped.push({ paymentInstrumentId: instrument.id, reason: "missing_amount" });
+            continue;
+        }
+        const remainingAmountCents = asNumber(metadata, "remainingAmountCents") ?? initialAmountCents;
+        const [existing] = await db
+            .select({ id: vouchers.id })
+            .from(vouchers)
+            .where(sql `lower(${vouchers.code}) = ${code.toLowerCase()}`)
+            .limit(1);
+        if (existing) {
+            skipped.push({ paymentInstrumentId: instrument.id, reason: "already_migrated" });
+            continue;
+        }
+        const expiresAt = asDate(asString(metadata, "expiresAt"));
+        // OpenTravel uses `effectiveDate`; some legacy payloads also wrote
+        // `validFrom` directly. Check both so existing rows aren't silently
+        // dropped.
+        const validFrom = asDate(asString(metadata, "validFrom")) ?? asDate(asString(metadata, "effectiveDate"));
+        const seriesCode = asString(metadata, "seriesCode");
+        const bookingIds = asStringArray(metadata, "bookingIds");
+        const sourceBookingId = asString(metadata, "bookingId") ?? bookingIds[0] ?? null;
+        // Collapse the legacy status/balance pair onto the new enum. If there's no
+        // balance left, treat as already spent; otherwise follow the instrument's
+        // own active/inactive flag.
+        const status = remainingAmountCents <= 0 ? "redeemed" : instrument.status === "active" ? "active" : "void";
+        if (dryRun) {
+            migrated++;
+            options.onRowMigrated?.({ paymentInstrumentId: instrument.id, voucherCode: code });
+            continue;
+        }
+        try {
+            await db.insert(vouchers).values({
+                code,
+                seriesCode,
+                status,
+                currency: currency.toUpperCase(),
+                initialAmountCents,
+                remainingAmountCents: Math.max(0, remainingAmountCents),
+                issuedToPersonId: instrument.personId ?? null,
+                issuedToOrganizationId: instrument.organizationId ?? null,
+                // We don't know the original source (refund vs gift vs promo) from the
+                // legacy shape, so mark everything as `manual` — operators can reclassify
+                // later via PATCH /vouchers/:id.
+                sourceType: "manual",
+                sourceBookingId,
+                notes: instrument.notes ?? null,
+                validFrom,
+                expiresAt,
+                createdAt: instrument.createdAt,
+                updatedAt: instrument.updatedAt,
+            });
+            migrated++;
+            options.onRowMigrated?.({ paymentInstrumentId: instrument.id, voucherCode: code });
+        }
+        catch (error) {
+            // Unique-index collision is the only realistic insert failure here
+            // (another concurrent migration or a race with a manual issuance). Record
+            // it as a skip rather than aborting the batch so a retry finishes the
+            // rest.
+            const message = error instanceof Error ? error.message : String(error);
+            if (message.includes("uidx_vouchers_code") || message.includes("duplicate key")) {
+                skipped.push({ paymentInstrumentId: instrument.id, reason: "duplicate_code_collision" });
+                continue;
+            }
+            throw error;
+        }
+    }
+    return {
+        candidates: candidates.length,
+        migrated,
+        skipped,
+        dryRun,
+    };
+}

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;
+        createdAt: Date;
+        updatedAt: Date;
+        expiresAt: Date | null;
+        status: "void" | "expired" | "active" | "redeemed";
+        currency: string;
+        notes: string | null;
+        code: string;
+        sourceType: "manual" | "refund" | "cancellation_credit" | "gift" | "promo";
+        seriesCode: string | null;
+        initialAmountCents: number;
+        remainingAmountCents: number;
+        issuedToPersonId: string | null;
+        issuedToOrganizationId: string | null;
+        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;
+            voucherId: string;
+            paymentId: string | null;
+            amountCents: number;
+            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 };
+        });
+    },
+};