@voyant-travel/finance 0.119.5

package/dist/service-invoice-numbering.d.ts

@@ -0,0 +1,227 @@
+import type { CreateInvoiceNumberSeriesInput, EnsureExternalInvoiceNumberSeriesInput, InvoiceNumberScope, InvoiceNumberSeriesListQuery, PostgresJsDatabase, UpdateInvoiceNumberSeriesInput } from "./service-shared.js";
+export declare const financeInvoiceNumberingService: {
+    listInvoiceNumberSeries(db: PostgresJsDatabase, query: InvoiceNumberSeriesListQuery): Promise<{
+        data: {
+            id: string;
+            code: string;
+            name: string;
+            prefix: string;
+            separator: string;
+            padLength: number;
+            currentSequence: number;
+            resetStrategy: "never" | "annual" | "monthly";
+            resetAt: Date | null;
+            scope: "invoice" | "proforma" | "credit_note";
+            isDefault: boolean;
+            externalProvider: string | null;
+            externalConfigKey: string | null;
+            active: boolean;
+            createdAt: Date;
+            updatedAt: Date;
+        }[];
+        total: number;
+        limit: number;
+        offset: number;
+    }>;
+    getInvoiceNumberSeriesById(db: PostgresJsDatabase, id: string): Promise<{
+        id: string;
+        code: string;
+        name: string;
+        prefix: string;
+        separator: string;
+        padLength: number;
+        currentSequence: number;
+        resetStrategy: "never" | "annual" | "monthly";
+        resetAt: Date | null;
+        scope: "invoice" | "proforma" | "credit_note";
+        isDefault: boolean;
+        externalProvider: string | null;
+        externalConfigKey: string | null;
+        active: boolean;
+        createdAt: Date;
+        updatedAt: Date;
+    } | null>;
+    resolveDefaultInvoiceNumberSeries(db: PostgresJsDatabase, scope: InvoiceNumberScope): Promise<{
+        id: string;
+        code: string;
+        name: string;
+        prefix: string;
+        separator: string;
+        padLength: number;
+        currentSequence: number;
+        resetStrategy: "never" | "annual" | "monthly";
+        resetAt: Date | null;
+        scope: "invoice" | "proforma" | "credit_note";
+        isDefault: boolean;
+        externalProvider: string | null;
+        externalConfigKey: string | null;
+        active: boolean;
+        createdAt: Date;
+        updatedAt: Date;
+    } | null>;
+    ensureExternalInvoiceNumberSeries(db: PostgresJsDatabase, inputs: EnsureExternalInvoiceNumberSeriesInput[]): Promise<{
+        id: string;
+        name: string;
+        code: string;
+        active: boolean;
+        createdAt: Date;
+        updatedAt: Date;
+        scope: "invoice" | "proforma" | "credit_note";
+        prefix: string;
+        separator: string;
+        padLength: number;
+        currentSequence: number;
+        resetStrategy: "never" | "annual" | "monthly";
+        resetAt: Date | null;
+        isDefault: boolean;
+        externalProvider: string | null;
+        externalConfigKey: string | null;
+    }[]>;
+    createInvoiceNumberSeries(db: PostgresJsDatabase, data: CreateInvoiceNumberSeriesInput): Promise<{
+        id: string;
+        name: string;
+        code: string;
+        active: boolean;
+        createdAt: Date;
+        updatedAt: Date;
+        scope: "invoice" | "proforma" | "credit_note";
+        prefix: string;
+        separator: string;
+        padLength: number;
+        currentSequence: number;
+        resetStrategy: "never" | "annual" | "monthly";
+        resetAt: Date | null;
+        isDefault: boolean;
+        externalProvider: string | null;
+        externalConfigKey: string | null;
+    } | null>;
+    updateInvoiceNumberSeries(db: PostgresJsDatabase, id: string, data: UpdateInvoiceNumberSeriesInput): Promise<{
+        id: string;
+        code: string;
+        name: string;
+        prefix: string;
+        separator: string;
+        padLength: number;
+        currentSequence: number;
+        resetStrategy: "never" | "annual" | "monthly";
+        resetAt: Date | null;
+        scope: "invoice" | "proforma" | "credit_note";
+        isDefault: boolean;
+        externalProvider: string | null;
+        externalConfigKey: string | null;
+        active: boolean;
+        createdAt: Date;
+        updatedAt: Date;
+    } | null>;
+    deleteInvoiceNumberSeries(db: PostgresJsDatabase, id: string): Promise<{
+        id: string;
+    } | null>;
+    /**
+     * Transactionally allocate the next invoice number from a series. Uses a
+     * `SELECT ... FOR UPDATE` row lock to ensure concurrent callers each receive
+     * a distinct sequence. Honours the series' `resetStrategy` (annual/monthly)
+     * by resetting `currentSequence` to 1 at period boundaries.
+     */
+    allocateInvoiceNumber(db: PostgresJsDatabase, seriesId: string): Promise<{
+        status: "not_found";
+        seriesId?: undefined;
+        sequence?: undefined;
+        formattedNumber?: undefined;
+    } | {
+        status: "inactive";
+        seriesId?: undefined;
+        sequence?: undefined;
+        formattedNumber?: undefined;
+    } | {
+        status: "allocated";
+        seriesId: string;
+        sequence: number;
+        formattedNumber: string;
+    }>;
+    applyExternalInvoiceAllocation(db: PostgresJsDatabase, invoiceId: string, data: {
+        invoiceNumber: string;
+        status?: "issued" | "draft";
+    }): Promise<{
+        status: "not_found";
+        invoice?: undefined;
+    } | {
+        status: "not_pending_external_allocation";
+        invoice: {
+            id: string;
+            invoiceNumber: string;
+            invoiceType: "invoice" | "proforma" | "credit_note";
+            convertedFromInvoiceId: string | null;
+            seriesId: string | null;
+            sequence: number | null;
+            templateId: string | null;
+            taxRegimeId: string | null;
+            language: string | null;
+            bookingId: string;
+            personId: string | null;
+            organizationId: string | null;
+            status: "void" | "paid" | "draft" | "pending_external_allocation" | "issued" | "partially_paid" | "overdue";
+            currency: string;
+            baseCurrency: string | null;
+            fxRateSetId: string | null;
+            subtotalCents: number;
+            baseSubtotalCents: number | null;
+            taxCents: number;
+            baseTaxCents: number | null;
+            totalCents: number;
+            baseTotalCents: number | null;
+            paidCents: number;
+            basePaidCents: number | null;
+            balanceDueCents: number;
+            baseBalanceDueCents: number | null;
+            commissionPercent: number | null;
+            commissionAmountCents: number | null;
+            issueDate: string;
+            dueDate: string;
+            notes: string | null;
+            voidedAt: Date | null;
+            voidReason: string | null;
+            createdAt: Date;
+            updatedAt: Date;
+        };
+    } | {
+        status: "applied";
+        invoice: {
+            subtotalCents: number;
+            currency: string;
+            id: string;
+            createdAt: Date;
+            updatedAt: Date;
+            taxRegimeId: string | null;
+            taxCents: number;
+            totalCents: number;
+            status: "void" | "paid" | "draft" | "pending_external_allocation" | "issued" | "partially_paid" | "overdue";
+            bookingId: string;
+            notes: string | null;
+            templateId: string | null;
+            dueDate: string;
+            invoiceNumber: string;
+            invoiceType: "invoice" | "proforma" | "credit_note";
+            convertedFromInvoiceId: string | null;
+            seriesId: string | null;
+            sequence: number | null;
+            language: string | null;
+            personId: string | null;
+            organizationId: string | null;
+            baseCurrency: string | null;
+            fxRateSetId: string | null;
+            baseSubtotalCents: number | null;
+            baseTaxCents: number | null;
+            baseTotalCents: number | null;
+            paidCents: number;
+            basePaidCents: number | null;
+            balanceDueCents: number;
+            baseBalanceDueCents: number | null;
+            commissionPercent: number | null;
+            commissionAmountCents: number | null;
+            issueDate: string;
+            voidedAt: Date | null;
+            voidReason: string | null;
+        };
+    }>;
+};
+//# sourceMappingURL=service-invoice-numbering.d.ts.map

package/dist/service-invoice-numbering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-invoice-numbering.d.ts","sourceRoot":"","sources":["../src/service-invoice-numbering.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,8BAA8B,EAC9B,sCAAsC,EACtC,kBAAkB,EAClB,4BAA4B,EAC5B,kBAAkB,EAClB,8BAA8B,EAC/B,MAAM,qBAAqB,CAAA;AAkB5B,eAAO,MAAM,8BAA8B;gCACP,kBAAkB,SAAS,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;mCAoBpD,kBAAkB,MAAM,MAAM;;;;;;;;;;;;;;;;;;0CASvB,kBAAkB,SAAS,kBAAkB;;;;;;;;;;;;;;;;;;0CAenF,kBAAkB,UACd,sCAAsC,EAAE;;;;;;;;;;;;;;;;;;kCA+Gd,kBAAkB,QAAQ,8BAA8B;;;;;;;;;;;;;;;;;;kCAkCtF,kBAAkB,MAClB,MAAM,QACJ,8BAA8B;;;;;;;;;;;;;;;;;;kCAoCF,kBAAkB,MAAM,MAAM;;;IAQlE;;;;;OAKG;8BAC6B,kBAAkB,YAAY,MAAM;;;;;;;;;;;;;;;;uCAiD9D,kBAAkB,aACX,MAAM,QACX;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAA;KAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6B/D,CAAA"}

package/dist/service-invoice-numbering.js

@@ -0,0 +1,260 @@
+import { and, currentPeriodBoundary, desc, ExternalInvoiceNumberSeriesCollisionError, eq, formatNumber, InvoiceNumberConflictError, invoiceNumberSeries, invoices, isInvoiceNumberUniqueConstraintError, ne, paginate, sql, toTimestamp, } from "./service-shared.js";
+export const financeInvoiceNumberingService = {
+    async listInvoiceNumberSeries(db, query) {
+        const conditions = [];
+        if (query.scope)
+            conditions.push(eq(invoiceNumberSeries.scope, query.scope));
+        if (typeof query.active === "boolean")
+            conditions.push(eq(invoiceNumberSeries.active, query.active));
+        const where = conditions.length ? and(...conditions) : undefined;
+        return paginate(db
+            .select()
+            .from(invoiceNumberSeries)
+            .where(where)
+            .limit(query.limit)
+            .offset(query.offset)
+            .orderBy(desc(invoiceNumberSeries.updatedAt)), db.select({ total: sql `count(*)::int` }).from(invoiceNumberSeries).where(where), query.limit, query.offset);
+    },
+    async getInvoiceNumberSeriesById(db, id) {
+        const [row] = await db
+            .select()
+            .from(invoiceNumberSeries)
+            .where(eq(invoiceNumberSeries.id, id))
+            .limit(1);
+        return row ?? null;
+    },
+    async resolveDefaultInvoiceNumberSeries(db, scope) {
+        const [row] = await db
+            .select()
+            .from(invoiceNumberSeries)
+            .where(and(eq(invoiceNumberSeries.scope, scope), eq(invoiceNumberSeries.active, true)))
+            .orderBy(desc(invoiceNumberSeries.isDefault), desc(invoiceNumberSeries.updatedAt), desc(invoiceNumberSeries.createdAt))
+            .limit(1);
+        return row ?? null;
+    },
+    async ensureExternalInvoiceNumberSeries(db, inputs) {
+        return db.transaction(async (tx) => {
+            const rows = [];
+            for (const input of inputs) {
+                const now = new Date();
+                const code = input.code ?? `${input.provider}-${input.scope}`;
+                const active = input.active ?? true;
+                const isDefault = active === false ? false : (input.isDefault ?? true);
+                const [existingExternal] = await tx
+                    .select()
+                    .from(invoiceNumberSeries)
+                    .where(and(eq(invoiceNumberSeries.scope, input.scope), eq(invoiceNumberSeries.externalProvider, input.provider)))
+                    .orderBy(desc(invoiceNumberSeries.isDefault), desc(invoiceNumberSeries.updatedAt), desc(invoiceNumberSeries.createdAt))
+                    .limit(1);
+                const [existingByCode] = existingExternal
+                    ? [null]
+                    : await tx
+                        .select()
+                        .from(invoiceNumberSeries)
+                        .where(eq(invoiceNumberSeries.code, code))
+                        .limit(1);
+                if (existingByCode &&
+                    (existingByCode.scope !== input.scope ||
+                        existingByCode.externalProvider !== input.provider)) {
+                    throw new ExternalInvoiceNumberSeriesCollisionError({
+                        seriesCode: code,
+                        provider: input.provider,
+                        scope: input.scope,
+                        existingProvider: existingByCode.externalProvider,
+                        existingScope: existingByCode.scope,
+                    });
+                }
+                const existing = existingExternal ?? existingByCode;
+                const nextCode = existingExternal ? existingExternal.code : code;
+                if (isDefault) {
+                    const defaultScopeWhere = existing
+                        ? and(eq(invoiceNumberSeries.scope, input.scope), ne(invoiceNumberSeries.id, existing.id))
+                        : eq(invoiceNumberSeries.scope, input.scope);
+                    await tx
+                        .update(invoiceNumberSeries)
+                        .set({ isDefault: false, updatedAt: now })
+                        .where(defaultScopeWhere);
+                }
+                if (existing) {
+                    const [row] = await tx
+                        .update(invoiceNumberSeries)
+                        .set({
+                        code: nextCode,
+                        name: input.name,
+                        prefix: input.prefix ?? existing.prefix,
+                        separator: input.separator ?? existing.separator,
+                        padLength: input.padLength ?? existing.padLength,
+                        resetStrategy: input.resetStrategy ?? existing.resetStrategy,
+                        scope: input.scope,
+                        isDefault,
+                        externalProvider: input.provider,
+                        externalConfigKey: input.externalConfigKey ?? null,
+                        active,
+                        updatedAt: now,
+                    })
+                        .where(eq(invoiceNumberSeries.id, existing.id))
+                        .returning();
+                    if (row)
+                        rows.push(row);
+                    continue;
+                }
+                const [row] = await tx
+                    .insert(invoiceNumberSeries)
+                    .values({
+                    code,
+                    name: input.name,
+                    prefix: input.prefix ?? "",
+                    separator: input.separator ?? "",
+                    padLength: input.padLength ?? 0,
+                    currentSequence: 0,
+                    resetStrategy: input.resetStrategy ?? "never",
+                    resetAt: null,
+                    scope: input.scope,
+                    isDefault,
+                    externalProvider: input.provider,
+                    externalConfigKey: input.externalConfigKey ?? null,
+                    active,
+                })
+                    .returning();
+                if (row)
+                    rows.push(row);
+            }
+            return rows;
+        });
+    },
+    async createInvoiceNumberSeries(db, data) {
+        return db.transaction(async (tx) => {
+            const isDefault = data.active === false ? false : data.isDefault;
+            if (isDefault) {
+                await tx
+                    .update(invoiceNumberSeries)
+                    .set({ isDefault: false, updatedAt: new Date() })
+                    .where(eq(invoiceNumberSeries.scope, data.scope));
+            }
+            const [row] = await tx
+                .insert(invoiceNumberSeries)
+                .values({
+                code: data.code,
+                name: data.name,
+                prefix: data.prefix,
+                separator: data.separator,
+                padLength: data.padLength,
+                currentSequence: data.currentSequence,
+                resetStrategy: data.resetStrategy,
+                resetAt: toTimestamp(data.resetAt),
+                scope: data.scope,
+                isDefault,
+                externalProvider: data.externalProvider ?? null,
+                externalConfigKey: data.externalConfigKey ?? null,
+                active: data.active,
+            })
+                .returning();
+            return row ?? null;
+        });
+    },
+    async updateInvoiceNumberSeries(db, id, data) {
+        return db.transaction(async (tx) => {
+            const [existing] = await tx
+                .select()
+                .from(invoiceNumberSeries)
+                .where(eq(invoiceNumberSeries.id, id))
+                .limit(1);
+            if (!existing)
+                return null;
+            const { resetAt, ...rest } = data;
+            const nextScope = rest.scope ?? existing.scope;
+            const nextActive = rest.active ?? existing.active;
+            const nextIsDefault = nextActive === false ? false : (rest.isDefault ?? existing.isDefault);
+            if (nextIsDefault) {
+                await tx
+                    .update(invoiceNumberSeries)
+                    .set({ isDefault: false, updatedAt: new Date() })
+                    .where(and(eq(invoiceNumberSeries.scope, nextScope), ne(invoiceNumberSeries.id, id)));
+            }
+            const [row] = await tx
+                .update(invoiceNumberSeries)
+                .set({
+                ...rest,
+                isDefault: nextIsDefault,
+                ...(resetAt !== undefined ? { resetAt: toTimestamp(resetAt) } : {}),
+                updatedAt: new Date(),
+            })
+                .where(eq(invoiceNumberSeries.id, id))
+                .returning();
+            return row ?? null;
+        });
+    },
+    async deleteInvoiceNumberSeries(db, id) {
+        const [row] = await db
+            .delete(invoiceNumberSeries)
+            .where(eq(invoiceNumberSeries.id, id))
+            .returning({ id: invoiceNumberSeries.id });
+        return row ?? null;
+    },
+    /**
+     * Transactionally allocate the next invoice number from a series. Uses a
+     * `SELECT ... FOR UPDATE` row lock to ensure concurrent callers each receive
+     * a distinct sequence. Honours the series' `resetStrategy` (annual/monthly)
+     * by resetting `currentSequence` to 1 at period boundaries.
+     */
+    async allocateInvoiceNumber(db, seriesId) {
+        return db.transaction(async (tx) => {
+            const lockResult = await tx.execute(
+            // agent-quality: raw-sql reviewed -- owner: finance; dynamic SQL interpolation uses Drizzle parameter binding or vetted SQL identifiers.
+            sql `SELECT id, prefix, separator, pad_length, current_sequence, reset_strategy, reset_at, active FROM invoice_number_series WHERE id = ${seriesId} FOR UPDATE`);
+            const row = lockResult[0];
+            if (!row)
+                return { status: "not_found" };
+            if (!row.active)
+                return { status: "inactive" };
+            const now = new Date();
+            const boundary = currentPeriodBoundary(row.reset_strategy, now);
+            const shouldReset = boundary !== null && (row.reset_at === null || row.reset_at < boundary);
+            const nextSequence = shouldReset ? 1 : row.current_sequence + 1;
+            const nextResetAt = boundary ?? row.reset_at;
+            await tx
+                .update(invoiceNumberSeries)
+                .set({
+                currentSequence: nextSequence,
+                resetAt: nextResetAt,
+                updatedAt: now,
+            })
+                .where(eq(invoiceNumberSeries.id, seriesId));
+            const formattedNumber = formatNumber(row.prefix, row.separator, row.pad_length, nextSequence);
+            return {
+                status: "allocated",
+                seriesId,
+                sequence: nextSequence,
+                formattedNumber,
+            };
+        });
+    },
+    async applyExternalInvoiceAllocation(db, invoiceId, data) {
+        const [existing] = await db.select().from(invoices).where(eq(invoices.id, invoiceId)).limit(1);
+        if (!existing)
+            return { status: "not_found" };
+        if (existing.status !== "pending_external_allocation") {
+            return { status: "not_pending_external_allocation", invoice: existing };
+        }
+        let invoice;
+        try {
+            const [updatedInvoice] = await db
+                .update(invoices)
+                .set({
+                invoiceNumber: data.invoiceNumber,
+                status: data.status ?? "issued",
+                updatedAt: new Date(),
+            })
+                .where(eq(invoices.id, invoiceId))
+                .returning();
+            invoice = updatedInvoice;
+        }
+        catch (error) {
+            if (isInvoiceNumberUniqueConstraintError(error)) {
+                throw new InvoiceNumberConflictError(data.invoiceNumber);
+            }
+            throw error;
+        }
+        return invoice ? { status: "applied", invoice } : { status: "not_found" };
+    },
+};