@cogenta/commerce 0.2.0

package/dist/invoice/store.js

@@ -0,0 +1,221 @@
+import { CogentaError, identifier, newId, sql, } from '@cogenta/core';
+import { formatMoney } from '../money.js';
+import { toInt, toText } from '../rows.js';
+import { TABLES } from '../tables.js';
+import { renderInvoicePdf } from './pdf.js';
+function decode(row) {
+    return {
+        id: toText(row.id, 'invoice.id'),
+        orderId: toText(row.order_id, 'invoice.order_id'),
+        series: toText(row.series, 'invoice.series'),
+        seq: toInt(row.seq, 'invoice.seq'),
+        number: toText(row.number, 'invoice.number'),
+        issuedAt: toText(row.issued_at, 'invoice.issued_at'),
+        currency: toText(row.currency, 'invoice.currency'),
+        totalMinor: toInt(row.total_minor, 'invoice.total_minor'),
+        document: JSON.parse(toText(row.document, 'invoice.document')),
+    };
+}
+/** `2026-000042`. Zero-padded so the numbers sort as strings too. */
+export function formatInvoiceNumber(series, seq) {
+    return `${series}-${String(seq).padStart(6, '0')}`;
+}
+/**
+ * How many attempts at claiming the next number before giving up.
+ *
+ * The claim is a compare-and-set, so a loser retries with the value it just
+ * read. Under real contention two or three attempts is already unusual; ten is
+ * a number nobody reaches without something else being wrong, and failing
+ * loudly then is better than spinning.
+ */
+const CLAIM_ATTEMPTS = 10;
+export function createInvoiceStore(db, dependencies, now = Date.now) {
+    const d = db.dialect;
+    const invoices = identifier(TABLES.invoices, d);
+    const sequences = identifier(TABLES.invoiceSequences, d);
+    /**
+     * Takes the next number in a series, atomically.
+     *
+     * `update … set next_seq = next_seq + 1 where series = ? and next_seq = ?`
+     * — a compare-and-set whose `rowsAffected` decides the race, the same idiom
+     * that makes stock safe and a password reset token single use. Two invoices
+     * issued in the same millisecond get consecutive numbers, never the same
+     * one.
+     *
+     * Emphatically not `count(*) + 1`: that hands out a duplicate under any
+     * concurrency at all, and re-issues a number that a deleted row used to
+     * hold. A number, once handed out, is spent.
+     */
+    async function claimNumber(tx, series) {
+        for (let attempt = 0; attempt < CLAIM_ATTEMPTS; attempt += 1) {
+            const current = await tx.query(sql `select next_seq from ${sequences} where series = ${series}`);
+            const row = current.rows[0];
+            if (row === undefined) {
+                // First invoice of the series. A duplicate primary key here means
+                // somebody else created it in between, so the loop reads it and
+                // competes for the increment like everyone else.
+                try {
+                    await tx.query(sql `insert into ${sequences} (series, next_seq) values (${series}, ${2})`);
+                    return 1;
+                }
+                catch {
+                    continue;
+                }
+            }
+            const next = toInt(row.next_seq, 'invoice_sequence.next_seq');
+            const claimed = await tx.query(sql `
+        update ${sequences} set next_seq = ${next + 1}
+        where series = ${series} and next_seq = ${next}`);
+            if (claimed.rowsAffected > 0)
+                return next;
+        }
+        throw new CogentaError({
+            code: 'COMMERCE_INVOICE_SEQUENCE_CONFLICT',
+            message: `Could not take the next number in invoice series "${series}".`,
+            hint: 'The sequence is under unusually heavy contention. Retry the issue.',
+            details: { series, attempts: CLAIM_ATTEMPTS },
+        });
+    }
+    async function read(id, executor = db) {
+        const result = await executor.query(sql `select * from ${invoices} where id = ${id}`);
+        const row = result.rows[0];
+        return row === undefined ? null : decode(row);
+    }
+    function documentFor(order, number, issuedAt, buyer) {
+        const snapshot = {
+            number,
+            issuedAt,
+            orderReference: order.reference,
+            seller: dependencies.seller.address,
+            buyer: buyer.length > 0 ? buyer : [order.email],
+            currency: order.currency,
+            lines: order.lines.map((line) => ({
+                sku: line.sku,
+                title: line.title,
+                quantity: line.quantity,
+                unitPriceMinor: line.unitPriceMinor,
+                taxRateBp: line.taxRateBp,
+                totalMinor: line.totalMinor,
+            })),
+            subtotalMinor: order.subtotalMinor,
+            discountMinor: order.discountMinor,
+            shippingMinor: order.shippingMinor,
+            taxMinor: order.taxMinor,
+            totalMinor: order.totalMinor,
+            footer: dependencies.seller.footer ?? null,
+        };
+        return snapshot;
+    }
+    return {
+        issue: async (input) => {
+            const order = await dependencies.orders.read(input.orderId);
+            if (order === null) {
+                throw new CogentaError({
+                    code: 'COMMERCE_ORDER_NOT_FOUND',
+                    message: 'This order does not exist.',
+                    hint: 'Check the order reference.',
+                });
+            }
+            const existing = await db.query(sql `select * from ${invoices} where order_id = ${input.orderId}`);
+            if (existing.rows[0] !== undefined) {
+                throw new CogentaError({
+                    code: 'COMMERCE_INVOICE_ALREADY_ISSUED',
+                    message: 'This order has already been invoiced.',
+                    hint: 'An invoice is issued once. To correct one, issue a credit note against it.',
+                    details: { orderId: input.orderId },
+                });
+            }
+            const issuedAt = new Date(now()).toISOString();
+            const series = input.series ?? issuedAt.slice(0, 4);
+            const id = newId(now);
+            return db.transaction(async (tx) => {
+                // The number is taken inside the same transaction that writes the
+                // invoice. If the write fails, the increment rolls back with it and
+                // the number is not burned — which is what "gapless" requires.
+                const seq = await claimNumber(tx, series);
+                const number = formatInvoiceNumber(series, seq);
+                const document = documentFor(order, number, issuedAt, input.buyerAddress ?? []);
+                await tx.query(sql `
+            insert into ${invoices} (id, order_id, series, seq, number, issued_at, currency, total_minor, document)
+            values (${id}, ${order.id}, ${series}, ${seq}, ${number}, ${issuedAt},
+                    ${order.currency}, ${order.totalMinor}, ${JSON.stringify(document)})`);
+                await dependencies.orders.record(order.id, 'invoiced', { note: `Invoice ${number} issued.`, actorId: input.actorId ?? null }, tx);
+                const stored = await read(id, tx);
+                if (stored === null) {
+                    throw new CogentaError({
+                        code: 'COMMERCE_INVOICE_NOT_FOUND',
+                        message: 'The invoice was not stored.',
+                        hint: 'Check that the commerce tables exist (ensureCommerceTables).',
+                    });
+                }
+                return stored;
+            }, { immediate: true });
+        },
+        read,
+        readByOrder: async (orderId) => {
+            const result = await db.query(sql `select * from ${invoices} where order_id = ${orderId}`);
+            const row = result.rows[0];
+            return row === undefined ? null : decode(row);
+        },
+        readByNumber: async (number) => {
+            const result = await db.query(sql `select * from ${invoices} where number = ${number}`);
+            const row = result.rows[0];
+            return row === undefined ? null : decode(row);
+        },
+        list: async (options) => {
+            const result = options?.series === undefined
+                ? await db.query(sql `select * from ${invoices} order by series asc, seq asc`)
+                : await db.query(sql `select * from ${invoices} where series = ${options.series} order by seq asc`);
+            return result.rows.slice(0, options?.limit ?? 500).map(decode);
+        },
+        pdf: async (id) => {
+            const invoice = await read(id);
+            if (invoice === null) {
+                throw new CogentaError({
+                    code: 'COMMERCE_INVOICE_NOT_FOUND',
+                    message: 'This invoice does not exist.',
+                    hint: 'Check the invoice number.',
+                });
+            }
+            return renderInvoicePdf(pdfDocumentFor(invoice.document));
+        },
+    };
+}
+/**
+ * The stored snapshot, laid out for the PDF writer.
+ *
+ * A separate step on purpose: the snapshot is the record and the PDF is a
+ * rendering of it. Regenerating a PDF five years later from the same snapshot
+ * produces the same bytes, because nothing here reads a clock or a live row.
+ */
+export function pdfDocumentFor(document) {
+    const money = (amountMinor) => formatMoney({ amountMinor, currency: document.currency });
+    const totals = [['Subtotal', money(document.subtotalMinor)]];
+    if (document.discountMinor > 0)
+        totals.push(['Discount', `-${money(document.discountMinor)}`]);
+    if (document.shippingMinor > 0)
+        totals.push(['Shipping', money(document.shippingMinor)]);
+    if (document.taxMinor > 0)
+        totals.push(['Tax', money(document.taxMinor)]);
+    totals.push(['Total', money(document.totalMinor)]);
+    return {
+        title: 'Invoice',
+        number: document.number,
+        issuedAt: document.issuedAt.slice(0, 10),
+        seller: document.seller,
+        buyer: document.buyer,
+        columns: ['SKU', 'Description', 'Qty', 'Unit', 'Amount'],
+        lines: document.lines.map((line) => ({
+            cells: [
+                line.sku,
+                line.title,
+                String(line.quantity),
+                money(line.unitPriceMinor),
+                money(line.totalMinor),
+            ],
+        })),
+        totals,
+        ...(document.footer === null ? {} : { footer: document.footer }),
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/invoice/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/invoice/store.ts"],"names":[],"mappings":"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"}

package/dist/money.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Money, in the smallest unit of its currency, as an integer. Always.
+ *
+ * The three mandatory dialects (ADR-0006) do not agree on decimals: Postgres
+ * has exact `numeric`, MySQL has `decimal`, and SQLite has only `REAL` — a
+ * binary float where `0.1 + 0.2` is not `0.3`. A column that means something
+ * different on one of the three supported databases is a bug waiting for its
+ * first lost cent, so there is no decimal column anywhere in this package.
+ *
+ * One integer of minor units means the same thing everywhere, and
+ * `Number.MAX_SAFE_INTEGER` holds ninety thousand billion cents — no shop this
+ * CMS serves comes near it.
+ */
+export interface Money {
+    /** Cents, pence, øre… Never a major unit, never a float. */
+    readonly amountMinor: number;
+    /** ISO 4217, upper case. */
+    readonly currency: string;
+}
+export declare function minorUnitExponent(currency: string): number;
+export declare function normaliseCurrency(currency: string): string;
+export declare function assertCurrency(currency: string): string;
+/**
+ * Refuses anything that is not a whole, finite, non-negative number of minor
+ * units — including the float that arrives when someone multiplies a price by
+ * a tax rate and forgets to round.
+ */
+export declare function assertMinor(amount: number, what: string): number;
+/** Two amounts of the same currency, or a refusal. Never a silent conversion. */
+export declare function assertSameCurrency(left: string, right: string): string;
+/**
+ * A percentage of an amount, in basis points, rounded half up.
+ *
+ * Basis points rather than a float rate: `0.2` is not representable in binary,
+ * so a 20 % VAT expressed as a float already carries an error before the
+ * multiplication. `2000` basis points does not.
+ *
+ * Half-up rather than banker's rounding: it is what every invoice a European
+ * tax authority has ever accepted does, and matching the paper is worth more
+ * here than a marginally better statistical distribution.
+ */
+export declare function applyBasisPoints(amountMinor: number, basisPoints: number): number;
+/**
+ * Splits an amount over n shares so the parts add up to exactly the whole.
+ *
+ * Used when a cart-level discount has to be attributed to lines (an invoice
+ * must show per-line tax, and tax is computed after discount). Dividing and
+ * rounding each share independently loses or invents up to n-1 minor units;
+ * the remainder is therefore handed out one unit at a time to the largest
+ * weights first, which is both fair and exact.
+ */
+export declare function distribute(amountMinor: number, weights: readonly number[]): number[];
+/** For an invoice line or an admin screen. Never for arithmetic. */
+export declare function formatMoney(money: Money, locale?: string): string;
+//# sourceMappingURL=money.d.ts.map

package/dist/money.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"money.d.ts","sourceRoot":"","sources":["../src/money.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,KAAK;IACpB,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,4BAA4B;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AA2BD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUvD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAuBhE;AAED,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAWtE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAUjF;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAmBpF;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,SAAU,GAAG,MAAM,CAUlE"}

package/dist/money.js

@@ -0,0 +1,146 @@
+import { CogentaError } from '@cogenta/core';
+/**
+ * Currencies whose minor unit is not a hundredth.
+ *
+ * Only needed for display and for the amount handed to a payment gateway;
+ * arithmetic never looks at it. Deliberately short — this is the list of
+ * exceptions, not a currency database, and an unlisted currency gets the
+ * two-digit default that fits the overwhelming majority.
+ */
+const EXPONENTS = new Map([
+    ['JPY', 0],
+    ['KRW', 0],
+    ['VND', 0],
+    ['CLP', 0],
+    ['ISK', 0],
+    ['XAF', 0],
+    ['XOF', 0],
+    ['XPF', 0],
+    ['BHD', 3],
+    ['IQD', 3],
+    ['JOD', 3],
+    ['KWD', 3],
+    ['OMR', 3],
+    ['TND', 3],
+]);
+export function minorUnitExponent(currency) {
+    return EXPONENTS.get(normaliseCurrency(currency)) ?? 2;
+}
+export function normaliseCurrency(currency) {
+    return currency.trim().toUpperCase();
+}
+export function assertCurrency(currency) {
+    const code = normaliseCurrency(currency);
+    if (!/^[A-Z]{3}$/u.test(code)) {
+        throw new CogentaError({
+            code: 'COMMERCE_CURRENCY_INVALID',
+            message: `"${currency}" is not a currency code.`,
+            hint: 'Use a three-letter ISO 4217 code, such as EUR, USD or JPY.',
+        });
+    }
+    return code;
+}
+/**
+ * Refuses anything that is not a whole, finite, non-negative number of minor
+ * units — including the float that arrives when someone multiplies a price by
+ * a tax rate and forgets to round.
+ */
+export function assertMinor(amount, what) {
+    if (!Number.isFinite(amount) || !Number.isInteger(amount)) {
+        throw new CogentaError({
+            code: 'COMMERCE_AMOUNT_INVALID',
+            message: `${what} must be a whole number of minor units, got ${String(amount)}.`,
+            hint: 'Money is stored in cents (or the smallest unit of the currency), never as a decimal.',
+        });
+    }
+    if (amount < 0) {
+        throw new CogentaError({
+            code: 'COMMERCE_AMOUNT_INVALID',
+            message: `${what} cannot be negative (${String(amount)}).`,
+            hint: 'A refund is a separate record with its own sign, not a negative amount on the original one.',
+        });
+    }
+    if (amount > Number.MAX_SAFE_INTEGER) {
+        throw new CogentaError({
+            code: 'COMMERCE_AMOUNT_INVALID',
+            message: `${what} is larger than integer arithmetic can carry exactly.`,
+            hint: 'Check the amount: this is almost always a unit mistake (a major unit passed as a minor one).',
+        });
+    }
+    return amount;
+}
+/** Two amounts of the same currency, or a refusal. Never a silent conversion. */
+export function assertSameCurrency(left, right) {
+    const a = normaliseCurrency(left);
+    const b = normaliseCurrency(right);
+    if (a !== b) {
+        throw new CogentaError({
+            code: 'COMMERCE_CURRENCY_MISMATCH',
+            message: `Cannot combine ${a} with ${b}.`,
+            hint: 'A cart, an order and every line in it are in one currency. There is no exchange rate in this package.',
+        });
+    }
+    return a;
+}
+/**
+ * A percentage of an amount, in basis points, rounded half up.
+ *
+ * Basis points rather than a float rate: `0.2` is not representable in binary,
+ * so a 20 % VAT expressed as a float already carries an error before the
+ * multiplication. `2000` basis points does not.
+ *
+ * Half-up rather than banker's rounding: it is what every invoice a European
+ * tax authority has ever accepted does, and matching the paper is worth more
+ * here than a marginally better statistical distribution.
+ */
+export function applyBasisPoints(amountMinor, basisPoints) {
+    assertMinor(amountMinor, 'amount');
+    if (!Number.isInteger(basisPoints) || basisPoints < 0) {
+        throw new CogentaError({
+            code: 'COMMERCE_AMOUNT_INVALID',
+            message: `A rate must be a whole number of basis points, got ${String(basisPoints)}.`,
+            hint: '20 % is 2000 basis points. 5.5 % is 550.',
+        });
+    }
+    return Math.floor((amountMinor * basisPoints + 5000) / 10_000);
+}
+/**
+ * Splits an amount over n shares so the parts add up to exactly the whole.
+ *
+ * Used when a cart-level discount has to be attributed to lines (an invoice
+ * must show per-line tax, and tax is computed after discount). Dividing and
+ * rounding each share independently loses or invents up to n-1 minor units;
+ * the remainder is therefore handed out one unit at a time to the largest
+ * weights first, which is both fair and exact.
+ */
+export function distribute(amountMinor, weights) {
+    assertMinor(amountMinor, 'amount');
+    const total = weights.reduce((sum, weight) => sum + weight, 0);
+    if (weights.length === 0 || total <= 0)
+        return weights.map(() => 0);
+    const shares = weights.map((weight) => Math.floor((amountMinor * weight) / total));
+    let remainder = amountMinor - shares.reduce((sum, share) => sum + share, 0);
+    const order = weights
+        .map((weight, index) => ({ weight, index }))
+        .sort((left, right) => right.weight - left.weight || left.index - right.index);
+    for (const { index } of order) {
+        if (remainder <= 0)
+            break;
+        shares[index] = (shares[index] ?? 0) + 1;
+        remainder -= 1;
+    }
+    return shares;
+}
+/** For an invoice line or an admin screen. Never for arithmetic. */
+export function formatMoney(money, locale = 'en-US') {
+    const currency = assertCurrency(money.currency);
+    const exponent = minorUnitExponent(currency);
+    const major = money.amountMinor / 10 ** exponent;
+    return new Intl.NumberFormat(locale, {
+        style: 'currency',
+        currency,
+        minimumFractionDigits: exponent,
+        maximumFractionDigits: exponent,
+    }).format(major);
+}
+//# sourceMappingURL=money.js.map

package/dist/money.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"money.js","sourceRoot":"","sources":["../src/money.ts"],"names":[],"mappings":"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"}

package/dist/order/store.d.ts

@@ -0,0 +1,75 @@
+import { type DatabaseHandle, type SqlExecutor } from '@cogenta/core';
+import type { CartStore } from '../cart/store.js';
+import type { CatalogStore } from '../catalog/store.js';
+import type { StockShortfall } from '../catalog/types.js';
+import type { CouponStore } from '../coupon/store.js';
+import type { CustomerStore } from '../customer/store.js';
+import type { Order, OrderEvent, OrderEventKind, OrderStatus } from './types.js';
+export interface PlaceOrderInput {
+    readonly cartId: string;
+    readonly email: string;
+    readonly customerName?: string | null;
+    readonly actorId?: string | null;
+}
+/**
+ * Placing an order either produced one, or explains exactly what stopped it.
+ *
+ * A thrown error would be wrong for the two ordinary cases — a line went out
+ * of stock, a coupon ran out while the shopper was typing their address. Those
+ * are things that happen in a shop every day and the checkout has to render
+ * them, not log them.
+ */
+export type PlaceOrderOutcome = {
+    readonly kind: 'placed';
+    readonly order: Order;
+} | {
+    readonly kind: 'out_of_stock';
+    readonly shortfalls: readonly StockShortfall[];
+} | {
+    readonly kind: 'coupon_refused';
+    readonly reason: string;
+} | {
+    readonly kind: 'empty';
+};
+export interface OrderStoreDependencies {
+    readonly catalog: CatalogStore;
+    readonly carts: CartStore;
+    readonly customers: CustomerStore;
+    readonly coupons: CouponStore;
+}
+export interface OrderListOptions {
+    readonly status?: OrderStatus;
+    readonly customerId?: string;
+    readonly limit?: number;
+    readonly offset?: number;
+}
+export interface OrderStore {
+    /**
+     * Turns a priced cart into an order, in **one** transaction.
+     *
+     * Everything that must be true together is done together: stock is taken,
+     * the coupon redemption is claimed, the order and its lines are written, the
+     * cart is closed, and the first history event is recorded. If any one of
+     * them fails, none of them happened — no order with unreserved stock, no
+     * stock taken for an order that was never written, no coupon burned for a
+     * sale that did not occur.
+     */
+    place(input: PlaceOrderInput): Promise<PlaceOrderOutcome>;
+    read(id: string): Promise<Order | null>;
+    readByReference(reference: string): Promise<Order | null>;
+    list(options?: OrderListOptions): Promise<readonly Order[]>;
+    /** Moves the order along, refusing an impossible move. Returns the new order. */
+    transition(id: string, to: OrderStatus, options?: {
+        readonly actorId?: string | null;
+        readonly note?: string;
+    }): Promise<Order>;
+    history(id: string): Promise<readonly OrderEvent[]>;
+    /** Appends to the history without changing the status. */
+    record(id: string, kind: OrderEventKind, options?: {
+        readonly note?: string;
+        readonly actorId?: string | null;
+    }, tx?: SqlExecutor): Promise<void>;
+}
+export declare function referenceFrom(id: string): string;
+export declare function createOrderStore(db: DatabaseHandle, dependencies: OrderStoreDependencies, now?: () => number): OrderStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/order/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/order/store.ts"],"names":[],"mappings":"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"}