platform-types 1.10.852 → 1.10.854

package/dist/account.d.ts

@@ -188,6 +188,12 @@ declare global {
          * payment): the obligation whose refund the debit books. Absent on every other row.
          */
         refundObligationId?: string;
+        /**
+         * On a link-credit reversal row (SK `LINKREV#{reversedAccountId}`, `paymentRef*` naming the linked
+         * payment): the ledger row it reverses — the payment's credit, or that credit's FX adjustment.
+         * Absent on every other row.
+         */
+        reversesAccountId?: string;
     }
     /**
      * `POST /account` — a new customer-ledger movement. Mirrors the request side of

package/dist/accountAllocation.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The cuenta-corriente allocator — which customer debits are still open, derived
+ * on read from `ACCOUNT#{storeId}` rows, in INTEGER MINOR UNITS. One
+ * implementation shared by the api, the operator app and the storefront, so the
+ * three agree on which debit a payment can still settle.
+ *
+ * No allocation entity is stored: a credit carries no pointer to the debit it
+ * paid, so every reader re-derives it, and two readers that derive it
+ * differently tell the customer two different things. The rules:
+ *
+ * 1. **Row order is `createdAt` ascending, NEVER `dated`.** A backdated row is
+ *    allocated where it was written. Ties: a debit before a credit (an order's
+ *    debit and its auto-linked payment can share a millisecond), then
+ *    `accountId`, so the result never depends on the order DynamoDB returned.
+ * 2. **A credit stamped with an `orderId` serves that order's open debits
+ *    first**, oldest first, and only debits already on the ledger — it cannot
+ *    reach a debit of that order written after it.
+ * 3. **Everything else applies oldest-first**: an unstamped credit, and the rest
+ *    of a stamped one once its order is paid (or has no debit yet).
+ * 4. **Credit with no open debit to land on waits unapplied** and is drained by
+ *    the next debit, so a deposit taken before the order is booked still pays
+ *    it. What is never drained is reported as `unappliedMinor`.
+ *
+ * Rows it reads, and how:
+ *
+ * - A `deleted` row, or one whose `createdAt` is past `asOf`, is skipped.
+ * - A synthesised opening row (`ACC000001`, `ACC000001-<suffix>` — the "Saldo
+ *   anterior" a statement leads with) is a movement of its `balance`: positive
+ *   is an orderless debit, negative an unstamped credit, and any `orderId` on
+ *   it is ignored. A `balance` on any OTHER row is a projected running total
+ *   and is ignored.
+ * - A row whose `debit` is above zero is a debit (its `credit` is then not
+ *   read); otherwise a row whose `credit` is above zero at the ledger scale is
+ *   a credit; anything else moves nothing. A stored `BALANCE-` checkpoint
+ *   carries neither, so it moves nothing — the ledger must be read from its
+ *   first row instead, because FIFO over a ledger with a missing debit is
+ *   wrong.
+ * - A refund-in-transit debit (`RIT#…`) is an ordinary debit stamped with its
+ *   order. It is reported like any other item; a consumer offering debits to
+ *   pay excludes it by its `accountId` if it must.
+ *
+ * ⚠️ **ONE ledger bucket — `ledgerCurrency` — never one per row label.** Every
+ * writer stores `debit`/`credit` already converted into the store's ledger
+ * denomination; a legacy manual row's `currency` labels what the operator
+ * TYPED, so bucketing by it files pesos as dollars. Opening rows follow the
+ * same rule, a legacy `ACC000001-usd` seed included. Every item therefore
+ * carries `ledgerCurrency`.
+ *
+ * ⚠️ **Exact, with no display tolerance.** An item is `paid` only at zero minor
+ * units. A reader that rounds to fewer decimals than the ledger scale (a store
+ * pricing in whole units on a two-decimal ledger) can call "paid" what this
+ * calls `partial`; that tolerance is the reader's to apply, on top of these
+ * figures. Amounts are quantised once per row — half away from zero after
+ * normalising the scaled value to 15 significant digits, the api ledger's own
+ * rule — and never summed as floats. A missing or non-finite amount is zero.
+ *
+ * Pure: no clock, no I/O, input rows never mutated.
+ */
+/** An item's allocation state, as a code — the reader owns the label. */
+export declare const ACCOUNT_ITEM_STATUSES: readonly ["open", "partial", "paid"];
+export type AccountItemStatus = (typeof ACCOUNT_ITEM_STATUSES)[number];
+/** The fields the allocator reads — a stored row and either wire projection all satisfy it. */
+export type AllocatableAccountRow = Pick<Account, 'accountId' | 'dated'> & Partial<Pick<Account, 'createdAt' | 'orderId' | 'dueDate' | 'details' | 'debit' | 'credit' | 'balance' | 'deleted'>>;
+export interface AccountAllocationOptions {
+    /** The store's ledger denomination (`store.config.displayCurrency` as a catalogId). Lowercased on output. */
+    ledgerCurrency: string;
+    /** Decimal places of `ledgerCurrency`'s minor unit, an integer 0–4. Defaults to 2. */
+    ledgerScale?: number;
+    /** Unix ms; rows written after it are left out. Omitted, every row counts. */
+    asOf?: number;
+}
+/** One debit row after allocation. */
+export interface AllocatedAccountItem {
+    /** The debit row's `Account.accountId`. */
+    accountId: string;
+    /** Absent for orderless debt — an empty `orderId` included, which allocation treats as orderless too. */
+    orderId?: string;
+    /** `AccountLedgerAllocation.currency`. */
+    currency: string;
+    /** `YYYYMMDD` ledger day the debit is dated — what an aging read buckets. */
+    dated: number;
+    /** `YYYYMMDD` due day stamped on the row. Absent means unspecified — never inferred from `dated`. */
+    dueDate?: number;
+    /** The row's `Account.details`, verbatim when the row carries the key. */
+    details?: string;
+    /** The row's `createdAt` — the axis allocation ran on. */
+    createdAt: number;
+    /** The debit, in minor units of `currency`. */
+    originalMinor: number;
+    /** How much of it credits have covered. */
+    paidMinor: number;
+    /** `originalMinor - paidMinor`, never negative. */
+    remainingMinor: number;
+    status: AccountItemStatus;
+}
+/** Every debit of one order, summed. */
+export interface AllocatedAccountOrder {
+    originalMinor: number;
+    paidMinor: number;
+    remainingMinor: number;
+    status: AccountItemStatus;
+}
+export interface AccountLedgerAllocation {
+    /** The ledger bucket every amount here is in: `ledgerCurrency`, lowercased. */
+    currency: string;
+    /** Decimal places of one minor unit of `currency`. */
+    scale: number;
+    /** Every debit row, in allocation order, paid ones included. */
+    items: AllocatedAccountItem[];
+    /** The items carrying an `orderId`, summed per order. */
+    orders: Record<string, AllocatedAccountOrder>;
+    /** Credit no debit absorbed — owed to the customer. Never negative. */
+    unappliedMinor: number;
+    /** Debits minus credits: positive is owed by the customer. Equals the open items' total minus `unappliedMinor`. */
+    saldoMinor: number;
+}
+/**
+ * Allocate a customer's ledger. Pass the WHOLE ledger — every movement from the
+ * first, or a synthesised opening row standing in for what precedes the rows —
+ * since a debit missing from the input leaves a later credit landing on the
+ * wrong one. Throws a `RangeError` on a scale outside 0–4.
+ */
+export declare const allocateAccountLedger: (rows: readonly AllocatableAccountRow[], options: AccountAllocationOptions) => AccountLedgerAllocation;
+/** The items of an allocation that still owe something, in allocation order. */
+export declare const openAccountItems: (allocation: AccountLedgerAllocation) => AllocatedAccountItem[];

package/dist/accountAllocation.js

@@ -0,0 +1,193 @@
+/**
+ * The cuenta-corriente allocator — which customer debits are still open, derived
+ * on read from `ACCOUNT#{storeId}` rows, in INTEGER MINOR UNITS. One
+ * implementation shared by the api, the operator app and the storefront, so the
+ * three agree on which debit a payment can still settle.
+ *
+ * No allocation entity is stored: a credit carries no pointer to the debit it
+ * paid, so every reader re-derives it, and two readers that derive it
+ * differently tell the customer two different things. The rules:
+ *
+ * 1. **Row order is `createdAt` ascending, NEVER `dated`.** A backdated row is
+ *    allocated where it was written. Ties: a debit before a credit (an order's
+ *    debit and its auto-linked payment can share a millisecond), then
+ *    `accountId`, so the result never depends on the order DynamoDB returned.
+ * 2. **A credit stamped with an `orderId` serves that order's open debits
+ *    first**, oldest first, and only debits already on the ledger — it cannot
+ *    reach a debit of that order written after it.
+ * 3. **Everything else applies oldest-first**: an unstamped credit, and the rest
+ *    of a stamped one once its order is paid (or has no debit yet).
+ * 4. **Credit with no open debit to land on waits unapplied** and is drained by
+ *    the next debit, so a deposit taken before the order is booked still pays
+ *    it. What is never drained is reported as `unappliedMinor`.
+ *
+ * Rows it reads, and how:
+ *
+ * - A `deleted` row, or one whose `createdAt` is past `asOf`, is skipped.
+ * - A synthesised opening row (`ACC000001`, `ACC000001-<suffix>` — the "Saldo
+ *   anterior" a statement leads with) is a movement of its `balance`: positive
+ *   is an orderless debit, negative an unstamped credit, and any `orderId` on
+ *   it is ignored. A `balance` on any OTHER row is a projected running total
+ *   and is ignored.
+ * - A row whose `debit` is above zero is a debit (its `credit` is then not
+ *   read); otherwise a row whose `credit` is above zero at the ledger scale is
+ *   a credit; anything else moves nothing. A stored `BALANCE-` checkpoint
+ *   carries neither, so it moves nothing — the ledger must be read from its
+ *   first row instead, because FIFO over a ledger with a missing debit is
+ *   wrong.
+ * - A refund-in-transit debit (`RIT#…`) is an ordinary debit stamped with its
+ *   order. It is reported like any other item; a consumer offering debits to
+ *   pay excludes it by its `accountId` if it must.
+ *
+ * ⚠️ **ONE ledger bucket — `ledgerCurrency` — never one per row label.** Every
+ * writer stores `debit`/`credit` already converted into the store's ledger
+ * denomination; a legacy manual row's `currency` labels what the operator
+ * TYPED, so bucketing by it files pesos as dollars. Opening rows follow the
+ * same rule, a legacy `ACC000001-usd` seed included. Every item therefore
+ * carries `ledgerCurrency`.
+ *
+ * ⚠️ **Exact, with no display tolerance.** An item is `paid` only at zero minor
+ * units. A reader that rounds to fewer decimals than the ledger scale (a store
+ * pricing in whole units on a two-decimal ledger) can call "paid" what this
+ * calls `partial`; that tolerance is the reader's to apply, on top of these
+ * figures. Amounts are quantised once per row — half away from zero after
+ * normalising the scaled value to 15 significant digits, the api ledger's own
+ * rule — and never summed as floats. A missing or non-finite amount is zero.
+ *
+ * Pure: no clock, no I/O, input rows never mutated.
+ */
+/** An item's allocation state, as a code — the reader owns the label. */
+export const ACCOUNT_ITEM_STATUSES = ['open', 'partial', 'paid'];
+const OPENING_ROW_ID = 'ACC000001';
+const DEFAULT_SCALE = 2;
+const MAX_SCALE = 4;
+const isOpeningRow = (accountId) => accountId === OPENING_ROW_ID || accountId.startsWith(`${OPENING_ROW_ID}-`);
+const finiteOrZero = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
+const toMinorUnits = (amount, scale) => {
+    const rounded = Math.round(Number(Math.abs(amount * 10 ** scale).toPrecision(15)));
+    // Never `-0`.
+    return amount < 0 && rounded !== 0 ? -rounded : rounded;
+};
+const statusOf = (originalMinor, paidMinor) => {
+    if (originalMinor - paidMinor <= 0)
+        return 'paid';
+    return paidMinor > 0 ? 'partial' : 'open';
+};
+const toMove = (row, scale) => {
+    const createdAt = finiteOrZero(row.createdAt);
+    if (isOpeningRow(row.accountId)) {
+        const opening = toMinorUnits(finiteOrZero(row.balance), scale);
+        return {
+            row,
+            createdAt,
+            isDebit: opening > 0,
+            debitMinor: Math.max(opening, 0),
+            creditMinor: Math.max(-opening, 0),
+        };
+    }
+    const debit = finiteOrZero(row.debit);
+    return {
+        row,
+        createdAt,
+        // The RAW amount decides the kind, as the operator app does: a debit too small to reach one
+        // minor unit is still a (zero) debit, and its `credit` is still not read.
+        isDebit: debit > 0,
+        debitMinor: toMinorUnits(debit, scale),
+        creditMinor: toMinorUnits(finiteOrZero(row.credit), scale),
+        ...(row.orderId ? { orderId: row.orderId } : {}),
+    };
+};
+const compareMoves = (a, b) => a.createdAt - b.createdAt || Number(b.isDebit) - Number(a.isDebit) || a.row.accountId.localeCompare(b.row.accountId);
+/** Serves `debits` in order; returns the credit left over. */
+const applyFifo = (debits, creditMinor) => {
+    let remaining = creditMinor;
+    for (const debit of debits) {
+        if (remaining <= 0)
+            break;
+        const open = debit.totalMinor - debit.paidMinor;
+        if (open <= 0)
+            continue;
+        const applied = Math.min(open, remaining);
+        debit.paidMinor += applied;
+        remaining -= applied;
+    }
+    return remaining;
+};
+const toItem = (tracker, currency) => {
+    const { row } = tracker;
+    return {
+        accountId: row.accountId,
+        ...(tracker.orderId ? { orderId: tracker.orderId } : {}),
+        currency,
+        dated: row.dated,
+        ...(row.dueDate === undefined ? {} : { dueDate: row.dueDate }),
+        ...(row.details === undefined ? {} : { details: row.details }),
+        createdAt: tracker.createdAt,
+        originalMinor: tracker.totalMinor,
+        paidMinor: tracker.paidMinor,
+        remainingMinor: Math.max(tracker.totalMinor - tracker.paidMinor, 0),
+        status: statusOf(tracker.totalMinor, tracker.paidMinor),
+    };
+};
+const summariseOrders = (items) => {
+    const orders = {};
+    for (const item of items) {
+        if (!item.orderId)
+            continue;
+        const originalMinor = (orders[item.orderId]?.originalMinor ?? 0) + item.originalMinor;
+        const paidMinor = (orders[item.orderId]?.paidMinor ?? 0) + item.paidMinor;
+        orders[item.orderId] = {
+            originalMinor,
+            paidMinor,
+            remainingMinor: Math.max(originalMinor - paidMinor, 0),
+            status: statusOf(originalMinor, paidMinor),
+        };
+    }
+    return orders;
+};
+/**
+ * Allocate a customer's ledger. Pass the WHOLE ledger — every movement from the
+ * first, or a synthesised opening row standing in for what precedes the rows —
+ * since a debit missing from the input leaves a later credit landing on the
+ * wrong one. Throws a `RangeError` on a scale outside 0–4.
+ */
+export const allocateAccountLedger = (rows, options) => {
+    const scale = options.ledgerScale ?? DEFAULT_SCALE;
+    if (!Number.isInteger(scale) || scale < 0 || scale > MAX_SCALE) {
+        throw new RangeError(`Ledger scale must be an integer in 0-${MAX_SCALE}, got ${scale}`);
+    }
+    const currency = options.ledgerCurrency.toLowerCase();
+    const { asOf } = options;
+    const moves = rows
+        .filter((row) => !row.deleted && (asOf === undefined || finiteOrZero(row.createdAt) <= asOf))
+        .map((row) => toMove(row, scale))
+        .sort(compareMoves);
+    const debits = [];
+    let unappliedMinor = 0;
+    let saldoMinor = 0;
+    for (const move of moves) {
+        if (move.isDebit) {
+            saldoMinor += move.debitMinor;
+            debits.push({
+                row: move.row,
+                createdAt: move.createdAt,
+                ...(move.orderId ? { orderId: move.orderId } : {}),
+                totalMinor: move.debitMinor,
+                paidMinor: 0,
+            });
+            unappliedMinor = applyFifo(debits, unappliedMinor);
+            continue;
+        }
+        if (move.creditMinor <= 0)
+            continue;
+        saldoMinor -= move.creditMinor;
+        const spare = move.orderId
+            ? applyFifo(debits.filter((debit) => debit.orderId === move.orderId), move.creditMinor)
+            : move.creditMinor;
+        unappliedMinor = applyFifo(debits, unappliedMinor + spare);
+    }
+    const items = debits.map((tracker) => toItem(tracker, currency));
+    return { currency, scale, items, orders: summariseOrders(items), unappliedMinor, saldoMinor };
+};
+/** The items of an allocation that still owe something, in allocation order. */
+export const openAccountItems = (allocation) => allocation.items.filter((item) => item.remainingMinor > 0);

package/dist/cjs/accountAllocation.js

@@ -0,0 +1,198 @@
+"use strict";
+/**
+ * The cuenta-corriente allocator — which customer debits are still open, derived
+ * on read from `ACCOUNT#{storeId}` rows, in INTEGER MINOR UNITS. One
+ * implementation shared by the api, the operator app and the storefront, so the
+ * three agree on which debit a payment can still settle.
+ *
+ * No allocation entity is stored: a credit carries no pointer to the debit it
+ * paid, so every reader re-derives it, and two readers that derive it
+ * differently tell the customer two different things. The rules:
+ *
+ * 1. **Row order is `createdAt` ascending, NEVER `dated`.** A backdated row is
+ *    allocated where it was written. Ties: a debit before a credit (an order's
+ *    debit and its auto-linked payment can share a millisecond), then
+ *    `accountId`, so the result never depends on the order DynamoDB returned.
+ * 2. **A credit stamped with an `orderId` serves that order's open debits
+ *    first**, oldest first, and only debits already on the ledger — it cannot
+ *    reach a debit of that order written after it.
+ * 3. **Everything else applies oldest-first**: an unstamped credit, and the rest
+ *    of a stamped one once its order is paid (or has no debit yet).
+ * 4. **Credit with no open debit to land on waits unapplied** and is drained by
+ *    the next debit, so a deposit taken before the order is booked still pays
+ *    it. What is never drained is reported as `unappliedMinor`.
+ *
+ * Rows it reads, and how:
+ *
+ * - A `deleted` row, or one whose `createdAt` is past `asOf`, is skipped.
+ * - A synthesised opening row (`ACC000001`, `ACC000001-<suffix>` — the "Saldo
+ *   anterior" a statement leads with) is a movement of its `balance`: positive
+ *   is an orderless debit, negative an unstamped credit, and any `orderId` on
+ *   it is ignored. A `balance` on any OTHER row is a projected running total
+ *   and is ignored.
+ * - A row whose `debit` is above zero is a debit (its `credit` is then not
+ *   read); otherwise a row whose `credit` is above zero at the ledger scale is
+ *   a credit; anything else moves nothing. A stored `BALANCE-` checkpoint
+ *   carries neither, so it moves nothing — the ledger must be read from its
+ *   first row instead, because FIFO over a ledger with a missing debit is
+ *   wrong.
+ * - A refund-in-transit debit (`RIT#…`) is an ordinary debit stamped with its
+ *   order. It is reported like any other item; a consumer offering debits to
+ *   pay excludes it by its `accountId` if it must.
+ *
+ * ⚠️ **ONE ledger bucket — `ledgerCurrency` — never one per row label.** Every
+ * writer stores `debit`/`credit` already converted into the store's ledger
+ * denomination; a legacy manual row's `currency` labels what the operator
+ * TYPED, so bucketing by it files pesos as dollars. Opening rows follow the
+ * same rule, a legacy `ACC000001-usd` seed included. Every item therefore
+ * carries `ledgerCurrency`.
+ *
+ * ⚠️ **Exact, with no display tolerance.** An item is `paid` only at zero minor
+ * units. A reader that rounds to fewer decimals than the ledger scale (a store
+ * pricing in whole units on a two-decimal ledger) can call "paid" what this
+ * calls `partial`; that tolerance is the reader's to apply, on top of these
+ * figures. Amounts are quantised once per row — half away from zero after
+ * normalising the scaled value to 15 significant digits, the api ledger's own
+ * rule — and never summed as floats. A missing or non-finite amount is zero.
+ *
+ * Pure: no clock, no I/O, input rows never mutated.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openAccountItems = exports.allocateAccountLedger = exports.ACCOUNT_ITEM_STATUSES = void 0;
+/** An item's allocation state, as a code — the reader owns the label. */
+exports.ACCOUNT_ITEM_STATUSES = ['open', 'partial', 'paid'];
+const OPENING_ROW_ID = 'ACC000001';
+const DEFAULT_SCALE = 2;
+const MAX_SCALE = 4;
+const isOpeningRow = (accountId) => accountId === OPENING_ROW_ID || accountId.startsWith(`${OPENING_ROW_ID}-`);
+const finiteOrZero = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
+const toMinorUnits = (amount, scale) => {
+    const rounded = Math.round(Number(Math.abs(amount * 10 ** scale).toPrecision(15)));
+    // Never `-0`.
+    return amount < 0 && rounded !== 0 ? -rounded : rounded;
+};
+const statusOf = (originalMinor, paidMinor) => {
+    if (originalMinor - paidMinor <= 0)
+        return 'paid';
+    return paidMinor > 0 ? 'partial' : 'open';
+};
+const toMove = (row, scale) => {
+    const createdAt = finiteOrZero(row.createdAt);
+    if (isOpeningRow(row.accountId)) {
+        const opening = toMinorUnits(finiteOrZero(row.balance), scale);
+        return {
+            row,
+            createdAt,
+            isDebit: opening > 0,
+            debitMinor: Math.max(opening, 0),
+            creditMinor: Math.max(-opening, 0),
+        };
+    }
+    const debit = finiteOrZero(row.debit);
+    return {
+        row,
+        createdAt,
+        // The RAW amount decides the kind, as the operator app does: a debit too small to reach one
+        // minor unit is still a (zero) debit, and its `credit` is still not read.
+        isDebit: debit > 0,
+        debitMinor: toMinorUnits(debit, scale),
+        creditMinor: toMinorUnits(finiteOrZero(row.credit), scale),
+        ...(row.orderId ? { orderId: row.orderId } : {}),
+    };
+};
+const compareMoves = (a, b) => a.createdAt - b.createdAt || Number(b.isDebit) - Number(a.isDebit) || a.row.accountId.localeCompare(b.row.accountId);
+/** Serves `debits` in order; returns the credit left over. */
+const applyFifo = (debits, creditMinor) => {
+    let remaining = creditMinor;
+    for (const debit of debits) {
+        if (remaining <= 0)
+            break;
+        const open = debit.totalMinor - debit.paidMinor;
+        if (open <= 0)
+            continue;
+        const applied = Math.min(open, remaining);
+        debit.paidMinor += applied;
+        remaining -= applied;
+    }
+    return remaining;
+};
+const toItem = (tracker, currency) => {
+    const { row } = tracker;
+    return {
+        accountId: row.accountId,
+        ...(tracker.orderId ? { orderId: tracker.orderId } : {}),
+        currency,
+        dated: row.dated,
+        ...(row.dueDate === undefined ? {} : { dueDate: row.dueDate }),
+        ...(row.details === undefined ? {} : { details: row.details }),
+        createdAt: tracker.createdAt,
+        originalMinor: tracker.totalMinor,
+        paidMinor: tracker.paidMinor,
+        remainingMinor: Math.max(tracker.totalMinor - tracker.paidMinor, 0),
+        status: statusOf(tracker.totalMinor, tracker.paidMinor),
+    };
+};
+const summariseOrders = (items) => {
+    const orders = {};
+    for (const item of items) {
+        if (!item.orderId)
+            continue;
+        const originalMinor = (orders[item.orderId]?.originalMinor ?? 0) + item.originalMinor;
+        const paidMinor = (orders[item.orderId]?.paidMinor ?? 0) + item.paidMinor;
+        orders[item.orderId] = {
+            originalMinor,
+            paidMinor,
+            remainingMinor: Math.max(originalMinor - paidMinor, 0),
+            status: statusOf(originalMinor, paidMinor),
+        };
+    }
+    return orders;
+};
+/**
+ * Allocate a customer's ledger. Pass the WHOLE ledger — every movement from the
+ * first, or a synthesised opening row standing in for what precedes the rows —
+ * since a debit missing from the input leaves a later credit landing on the
+ * wrong one. Throws a `RangeError` on a scale outside 0–4.
+ */
+const allocateAccountLedger = (rows, options) => {
+    const scale = options.ledgerScale ?? DEFAULT_SCALE;
+    if (!Number.isInteger(scale) || scale < 0 || scale > MAX_SCALE) {
+        throw new RangeError(`Ledger scale must be an integer in 0-${MAX_SCALE}, got ${scale}`);
+    }
+    const currency = options.ledgerCurrency.toLowerCase();
+    const { asOf } = options;
+    const moves = rows
+        .filter((row) => !row.deleted && (asOf === undefined || finiteOrZero(row.createdAt) <= asOf))
+        .map((row) => toMove(row, scale))
+        .sort(compareMoves);
+    const debits = [];
+    let unappliedMinor = 0;
+    let saldoMinor = 0;
+    for (const move of moves) {
+        if (move.isDebit) {
+            saldoMinor += move.debitMinor;
+            debits.push({
+                row: move.row,
+                createdAt: move.createdAt,
+                ...(move.orderId ? { orderId: move.orderId } : {}),
+                totalMinor: move.debitMinor,
+                paidMinor: 0,
+            });
+            unappliedMinor = applyFifo(debits, unappliedMinor);
+            continue;
+        }
+        if (move.creditMinor <= 0)
+            continue;
+        saldoMinor -= move.creditMinor;
+        const spare = move.orderId
+            ? applyFifo(debits.filter((debit) => debit.orderId === move.orderId), move.creditMinor)
+            : move.creditMinor;
+        unappliedMinor = applyFifo(debits, unappliedMinor + spare);
+    }
+    const items = debits.map((tracker) => toItem(tracker, currency));
+    return { currency, scale, items, orders: summariseOrders(items), unappliedMinor, saldoMinor };
+};
+exports.allocateAccountLedger = allocateAccountLedger;
+/** The items of an allocation that still owe something, in allocation order. */
+const openAccountItems = (allocation) => allocation.items.filter((item) => item.remainingMinor > 0);
+exports.openAccountItems = openAccountItems;

package/dist/cjs/index.js

@@ -23,6 +23,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // the published ESM build keeps the extension Node's resolver demands — bare
 // `export * from "./account"` would throw ERR_MODULE_NOT_FOUND at import time.
 __exportStar(require("./account.js"), exports);
+__exportStar(require("./accountAllocation.js"), exports);
 __exportStar(require("./afip.js"), exports);
 __exportStar(require("./ai.js"), exports);
 __exportStar(require("./api.js"), exports);
@@ -103,6 +104,7 @@ __exportStar(require("./rma.js"), exports);
 __exportStar(require("./roles.js"), exports);
 __exportStar(require("./sentry.js"), exports);
 __exportStar(require("./serviceOrder.js"), exports);
+__exportStar(require("./serviceTracking.js"), exports);
 __exportStar(require("./serviceTemplate.js"), exports);
 __exportStar(require("./socket.js"), exports);
 __exportStar(require("./stock.js"), exports);

package/dist/cjs/payment.js

@@ -1,2 +1,46 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAYMENT_CREDIT_REVERSAL_LOCK_REASONS = exports.PAYMENT_CREDIT_REVERSAL_ERROR_CODES = void 0;
+/**
+ * The credit reversal's refusals (`PaymentCreditReversalRequest`). Each writes nothing.
+ *
+ * - `ADMIN_REQUIRED` · 403 — the token is below the ADMIN tier (an `ACCOUNTANT` is `403 ROLE_FORBIDDEN`, earlier).
+ * - `INVALID_INPUT` · 400 — the path's `source` is not `mp`, `stripe` or `mp_movement`.
+ * - `VALIDATION_FAILED` · 400 — the body is not `{ mode, reason }` or the reason is refused.
+ * - `PAYMENT_NOT_FOUND` · 404 — the store has no such payment.
+ * - `LINK_LOCKED` · 409 — `reason` is one of {@link PAYMENT_CREDIT_REVERSAL_LOCK_REASONS}.
+ * - `CUSTOMER_MERGED` · 409 — the credit's owner is mid-merge (or the payment carries a historical
+ *   merged-refund flag); `data.mergedInto` names the survivor.
+ * - `CUSTOMER_ANONYMIZED` · 409 — a legacy credit naming no customer, on an erased customer.
+ * - `CUSTOMER_NOT_FOUND` · 404 — the customer whose balance the credit moved is gone.
+ */
+exports.PAYMENT_CREDIT_REVERSAL_ERROR_CODES = [
+    'ADMIN_REQUIRED',
+    'INVALID_INPUT',
+    'VALIDATION_FAILED',
+    'PAYMENT_NOT_FOUND',
+    'LINK_LOCKED',
+    'CUSTOMER_MERGED',
+    'CUSTOMER_ANONYMIZED',
+    'CUSTOMER_NOT_FOUND',
+];
+/**
+ * Every `reason` of the credit reversal's `409 LINK_LOCKED`:
+ *
+ * - `credit-reversed` — this credit was already reversed (`reversalAccountId` names the row): a second
+ *   reversal of the same credit, a replay included.
+ * - `not-credited` — the payment's `accountId` names no credit of its own (never credited, or a pointer to
+ *   a row this payment did not write), or the payment names no customer (un-linked by hand).
+ * - `refund-obligation` — a refund obligation already debited part of this credit as in transit
+ *   (`refundObligationId`); reversing it all would debit that share twice.
+ * - `edited-ledger-pointer` — the payment's `fxAdjustmentAccountId` names a row that is not its own FX
+ *   adjustment for the credit's customer, so the delta to reverse cannot be named.
+ * - `concurrent-link` — the payment or its ledger rows kept changing while the reversal ran; retry.
+ */
+exports.PAYMENT_CREDIT_REVERSAL_LOCK_REASONS = [
+    'credit-reversed',
+    'not-credited',
+    'refund-obligation',
+    'edited-ledger-pointer',
+    'concurrent-link',
+];

package/dist/cjs/serviceOrder.js

@@ -301,6 +301,11 @@ exports.SERVICE_ORDER_ERROR_CODES = [
     'WARRANTY_BELOW_LEGAL_MINIMUM',
     'TECHNICIAN_NOT_FOUND',
     'TECHNICIAN_NOT_ELIGIBLE',
+    // The customer tracking link (`mode: 'trackingLink'`) — see `SERVICE_TRACKING_OPERATOR_ERROR_CODES`
+    'SERVICE_TRACKING_DISABLED',
+    'SERVICE_TRACKING_NO_ADDRESS',
+    'SERVICE_TRACKING_LINK_LAPSED',
+    'ADMIN_REQUIRED',
     'CUSTODY_ILLEGAL_TRANSITION',
     'SERVICE_ORDER_BILLABLE_FROZEN',
     'SERVICE_ORDER_EDIT_CHANGED',

package/dist/cjs/serviceTracking.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Customer service-order tracking — the page a customer opens from a link a
+ * shop sends (`/servicio/{handle}`), and the same view for a signed-in customer
+ * on their account.
+ *
+ * The HANDLE is 16 base62 characters (~95 bits), stored server-side and a
+ * bearer credential over exactly ONE service order of one store. It authorises
+ * the read (`GET /services/tracking?handle=`) and the current presupuesto PDF
+ * (`GET /services/tracking?handle=&mode=quote-pdf`), and nothing else. Every
+ * earlier link of an order dies when staff revoke it. A link stops reading
+ * `serviceTrackingLinkDaysAfterClose` days (platform global, default 90) after
+ * the order reached a terminal status.
+ *
+ * The gate is `ecommerce.config.serviceTracking` AND the `workshop` module on.
+ * With the gate off, staff cannot mint and the signed-in reads refuse, but a
+ * link minted earlier keeps reading (STORE_MODULES rule 4).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVICE_TRACKING_HANDLE_RE = exports.SERVICE_TRACKING_PATH_PREFIX = exports.SERVICE_TRACKING_LINK_ACTIONS = exports.SERVICE_TRACKING_OPERATOR_ERROR_CODES = exports.SERVICE_TRACKING_ACCOUNT_ERROR_CODES = exports.SERVICE_TRACKING_ERROR_CODES = void 0;
+/**
+ * The refusals the PUBLIC tracking routes answer themselves.
+ *
+ * - SERVICE_TRACKING_TOKEN_INVALID (401): every reason a handle cannot be
+ *   honoured — missing, malformed, unknown, revoked, past the lifetime,
+ *   presented on another store's host or with no store host at all, or naming
+ *   an order that is gone or disabled — with one identical body, so a handle is
+ *   never an oracle.
+ * - SERVICE_QUOTE_NOT_FOUND (404, `mode=quote-pdf` only): the order has no
+ *   current presupuesto a customer was sent.
+ */
+exports.SERVICE_TRACKING_ERROR_CODES = ['SERVICE_TRACKING_TOKEN_INVALID', 'SERVICE_QUOTE_NOT_FOUND'];
+/**
+ * The refusals of the signed-in reads (`GET /user?mode=service-orders` and
+ * `?mode=service-order&serviceOrderId=`).
+ *
+ * - SERVICE_TRACKING_DISABLED (403): the store's gate is off.
+ * - SERVICE_ORDER_NOT_FOUND (404): no such order, a disabled one, or one that
+ *   belongs to another customer — one answer for all three.
+ */
+exports.SERVICE_TRACKING_ACCOUNT_ERROR_CODES = ['SERVICE_TRACKING_DISABLED', 'SERVICE_ORDER_NOT_FOUND'];
+/**
+ * The refusals of the staff `POST /services { mode: 'trackingLink' }`, beside
+ * the router's own (`ROLE_FORBIDDEN`, `VALIDATION_FAILED`, `SERVICE_ORDER_NOT_FOUND`).
+ *
+ * - SERVICE_TRACKING_DISABLED (403, mint only): the store's gate is off.
+ * - SERVICE_TRACKING_NO_ADDRESS (409, mint only): the store has no public
+ *   storefront address to build the link on (no slug, or public links off).
+ * - SERVICE_TRACKING_LINK_LAPSED (409, mint only): the order closed more than
+ *   `serviceTrackingLinkDaysAfterClose` days ago, so a link would not read.
+ * - ADMIN_REQUIRED (403, revoke only): revoking takes ADMIN, SUPERVISOR or MANAGER.
+ */
+exports.SERVICE_TRACKING_OPERATOR_ERROR_CODES = [
+    'SERVICE_TRACKING_DISABLED',
+    'SERVICE_TRACKING_NO_ADDRESS',
+    'SERVICE_TRACKING_LINK_LAPSED',
+    'ADMIN_REQUIRED',
+];
+/** `POST /services { mode: 'trackingLink' }` actions. */
+exports.SERVICE_TRACKING_LINK_ACTIONS = ['mint', 'revoke'];
+/** The storefront path a tracking link opens: `/servicio/{handle}`. */
+exports.SERVICE_TRACKING_PATH_PREFIX = '/servicio/';
+/** The handle's exact shape: 16 base62 characters. */
+exports.SERVICE_TRACKING_HANDLE_RE = /^[0-9A-Za-z]{16}$/;