@mohasinac/appkit 4.62.1 → 4.63.0

package/dist/_internal/shared/features/ledger/posting.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The posting rules — pure, so they can be tested by an audit rather than by
+ * a `*.test.ts` the project forbids.
+ *
+ * Nothing here touches Firestore. `assertBalanced` and `buildReversal` are
+ * the two decisions that must never be wrong, and keeping them pure is what
+ * lets `verify-posting-rules.mjs` exercise them directly — the same shape as
+ * `verify-shipment-allocation-guard.mjs`, which reproduces a real failure
+ * against the real data shape and carries negative controls.
+ */
+import type { JournalLine, JournalSourceEvent } from "../../../../features/ledger/schemas/firestore";
+/**
+ * `YYYY-MM` for a date, in the ONE place that derives it.
+ *
+ * 🛑 **LOCAL, not UTC, and the difference is a GST return.** A sale at 02:00
+ * IST on 1 November is 20:30 UTC on 31 October, so `getUTCMonth()` files it
+ * under the wrong month — and the month is exactly what a GSTR-1 period is.
+ * Every evening sale in India would land in the previous return.
+ *
+ * Local is correct because `vercel.json` pins functions to `bom1` and the
+ * Firebase region is `asia-south1`, so "local" IS IST on every server that
+ * runs this. It also matches `financialYearLabel`, which uses `getMonth()`
+ * for the same reason and whose boundary error would be unrecoverable —
+ * these two must agree or a March entry could sit in one FY and one period
+ * that disagree about which year it belongs to.
+ *
+ * 🛑 It therefore DISAGREES with nothing by accident but with
+ * `payPeriodFor`'s UTC-free local midnight by design — both are local; if
+ * either is ever moved to UTC, move both, and expect the invoice series to
+ * need the same treatment.
+ */
+export declare function periodOf(date: Date): string;
+/**
+ * 🛑 Money comparison needs a TOLERANCE, and omitting one is the same bug
+ * Root Cause #92 cost a million invocations a day.
+ *
+ * Every leg here is a rupee amount with at most two decimals, and the
+ * arithmetic that produces them (a GST split, a pro-rata allocation) is
+ * floating point — `0.1 + 0.2 !== 0.3`. An exact `===` on the two totals
+ * would refuse a correct entry whose halves differ in the last bit, and the
+ * refusal would look like a posting-rule bug rather than a float.
+ *
+ * Half of the smallest representable unit (0.005): tight enough that a real
+ * 0.01 imbalance still fails, loose enough that no accumulation of
+ * two-decimal values can reach it.
+ */
+export declare const BALANCE_TOLERANCE = 0.005;
+export interface PostingInput {
+    entryDate: Date;
+    sourceEvent: JournalSourceEvent;
+    sourceId?: string;
+    narration: string;
+    lines: JournalLine[];
+}
+export interface BalancedPosting extends PostingInput {
+    period: string;
+    totalDebit: number;
+    totalCredit: number;
+}
+export declare class UnbalancedEntryError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate a posting and compute its totals, or refuse it.
+ *
+ * 🛑 **Refuses rather than correcting.** A plausible repair — dropping a
+ * zero line, inferring the missing side from the difference — is how a wrong
+ * posting rule gets a correct-looking entry written for it, and the books
+ * then balance while saying something false. An unbalanced entry is always a
+ * bug in the rule that built it, and the only safe response is to not write.
+ *
+ * The five checks, each of which has a distinct failure it prevents:
+ */
+export declare function assertBalanced(input: PostingInput): BalancedPosting;
+/**
+ * The reversing entry for a posting — every leg's sides swapped.
+ *
+ * 🛑 **Swapped, never negated.** `debit: -100` would balance arithmetically
+ * and is wrong in every other way: it breaks the non-negative rule above, it
+ * makes a trial balance sum to the right number through cancelling errors
+ * rather than through correct postings, and a ledger export to Tally would
+ * reject it. A credit of 100 against a debit of 100 is what a reversal IS.
+ *
+ * 🛑 **The reversal's `entryDate` is the CALLER's, not the original's.** A
+ * correction discovered in November for an October entry posts in November
+ * when October is locked — that is the whole point of the lock, and
+ * back-dating the reversal to the original would silently reopen a filed
+ * period. The link between them is `reversesEntryId`, not a shared date.
+ */
+export declare function buildReversal(original: {
+    id: string;
+    lines: JournalLine[];
+    narration: string;
+}, at: Date, reason: string): PostingInput;
+/**
+ * Where a late correction must post.
+ *
+ * 🛑 Returns the entry's OWN period when it is open, and the caller's
+ * fallback when it is not — it never silently moves a posting. A rule that
+ * quietly re-dated anything landing in a closed period would make the lock
+ * invisible, and the first anyone knew of it would be a GST return that no
+ * longer reconciles to the books it was filed from.
+ */
+export declare function resolvePostingPeriod(wanted: string, isLocked: (period: string) => boolean, openFallback: string): {
+    period: string;
+    deferred: boolean;
+};

package/dist/_internal/shared/features/ledger/posting.js

@@ -0,0 +1,165 @@
+/**
+ * The posting rules — pure, so they can be tested by an audit rather than by
+ * a `*.test.ts` the project forbids.
+ *
+ * Nothing here touches Firestore. `assertBalanced` and `buildReversal` are
+ * the two decisions that must never be wrong, and keeping them pure is what
+ * lets `verify-posting-rules.mjs` exercise them directly — the same shape as
+ * `verify-shipment-allocation-guard.mjs`, which reproduces a real failure
+ * against the real data shape and carries negative controls.
+ */
+/**
+ * `YYYY-MM` for a date, in the ONE place that derives it.
+ *
+ * 🛑 **LOCAL, not UTC, and the difference is a GST return.** A sale at 02:00
+ * IST on 1 November is 20:30 UTC on 31 October, so `getUTCMonth()` files it
+ * under the wrong month — and the month is exactly what a GSTR-1 period is.
+ * Every evening sale in India would land in the previous return.
+ *
+ * Local is correct because `vercel.json` pins functions to `bom1` and the
+ * Firebase region is `asia-south1`, so "local" IS IST on every server that
+ * runs this. It also matches `financialYearLabel`, which uses `getMonth()`
+ * for the same reason and whose boundary error would be unrecoverable —
+ * these two must agree or a March entry could sit in one FY and one period
+ * that disagree about which year it belongs to.
+ *
+ * 🛑 It therefore DISAGREES with nothing by accident but with
+ * `payPeriodFor`'s UTC-free local midnight by design — both are local; if
+ * either is ever moved to UTC, move both, and expect the invoice series to
+ * need the same treatment.
+ */
+export function periodOf(date) {
+    const y = date.getFullYear();
+    const m = String(date.getMonth() + 1).padStart(2, "0");
+    return `${y}-${m}`;
+}
+/**
+ * 🛑 Money comparison needs a TOLERANCE, and omitting one is the same bug
+ * Root Cause #92 cost a million invocations a day.
+ *
+ * Every leg here is a rupee amount with at most two decimals, and the
+ * arithmetic that produces them (a GST split, a pro-rata allocation) is
+ * floating point — `0.1 + 0.2 !== 0.3`. An exact `===` on the two totals
+ * would refuse a correct entry whose halves differ in the last bit, and the
+ * refusal would look like a posting-rule bug rather than a float.
+ *
+ * Half of the smallest representable unit (0.005): tight enough that a real
+ * 0.01 imbalance still fails, loose enough that no accumulation of
+ * two-decimal values can reach it.
+ */
+export const BALANCE_TOLERANCE = 0.005;
+export class UnbalancedEntryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnbalancedEntryError";
+    }
+}
+/**
+ * Validate a posting and compute its totals, or refuse it.
+ *
+ * 🛑 **Refuses rather than correcting.** A plausible repair — dropping a
+ * zero line, inferring the missing side from the difference — is how a wrong
+ * posting rule gets a correct-looking entry written for it, and the books
+ * then balance while saying something false. An unbalanced entry is always a
+ * bug in the rule that built it, and the only safe response is to not write.
+ *
+ * The five checks, each of which has a distinct failure it prevents:
+ */
+export function assertBalanced(input) {
+    const { lines } = input;
+    // 1. A single-legged entry is not double entry. One line can never balance,
+    //    and the commonest way to get one is a rule that forgot its credit.
+    if (lines.length < 2) {
+        throw new UnbalancedEntryError(`A journal entry needs at least two lines; got ${lines.length}.`);
+    }
+    let totalDebit = 0;
+    let totalCredit = 0;
+    for (const [i, line] of lines.entries()) {
+        const d = line.debit ?? 0;
+        const c = line.credit ?? 0;
+        // 2. NEGATIVE amounts are refused outright. A negative debit is a credit
+        //    written the wrong way round, and allowing it means every report has
+        //    to handle a sign it should never see — plus the two totals could
+        //    then balance while both sides are nonsense.
+        if (d < 0 || c < 0) {
+            throw new UnbalancedEntryError(`Line ${i} (${line.accountCode}) has a negative amount. A reversal swaps the sides; it never negates them.`);
+        }
+        // 3. EXACTLY ONE SIDE per line. A line carrying both is ambiguous about
+        //    what it asserts, and its net effect depends on a subtraction the
+        //    reader has to perform — which is precisely what two separate fields
+        //    exist to avoid.
+        if (d > 0 && c > 0) {
+            throw new UnbalancedEntryError(`Line ${i} (${line.accountCode}) carries both a debit and a credit. Split it into two lines.`);
+        }
+        // 4. A ZERO line asserts nothing and is almost always a rule that
+        //    computed an amount it then failed to use.
+        if (d === 0 && c === 0) {
+            throw new UnbalancedEntryError(`Line ${i} (${line.accountCode}) is zero on both sides.`);
+        }
+        totalDebit += d;
+        totalCredit += c;
+    }
+    // 5. The accounting identity itself.
+    if (Math.abs(totalDebit - totalCredit) > BALANCE_TOLERANCE) {
+        throw new UnbalancedEntryError(`Entry does not balance: debits ${totalDebit.toFixed(2)} vs credits ${totalCredit.toFixed(2)}.`);
+    }
+    return {
+        ...input,
+        period: periodOf(input.entryDate),
+        /*
+         * Rounded to two decimals AFTER the comparison, not before. Rounding
+         * first would mask a genuine sub-unit imbalance by making both sides
+         * equal; rounding after records a figure a human can reconcile against
+         * a bank statement.
+         */
+        totalDebit: Math.round(totalDebit * 100) / 100,
+        totalCredit: Math.round(totalCredit * 100) / 100,
+    };
+}
+/**
+ * The reversing entry for a posting — every leg's sides swapped.
+ *
+ * 🛑 **Swapped, never negated.** `debit: -100` would balance arithmetically
+ * and is wrong in every other way: it breaks the non-negative rule above, it
+ * makes a trial balance sum to the right number through cancelling errors
+ * rather than through correct postings, and a ledger export to Tally would
+ * reject it. A credit of 100 against a debit of 100 is what a reversal IS.
+ *
+ * 🛑 **The reversal's `entryDate` is the CALLER's, not the original's.** A
+ * correction discovered in November for an October entry posts in November
+ * when October is locked — that is the whole point of the lock, and
+ * back-dating the reversal to the original would silently reopen a filed
+ * period. The link between them is `reversesEntryId`, not a shared date.
+ */
+export function buildReversal(original, at, reason) {
+    return {
+        entryDate: at,
+        sourceEvent: "reversal",
+        sourceId: original.id,
+        narration: `Reversal of ${original.id}: ${reason}`,
+        lines: original.lines.map((l) => ({
+            accountCode: l.accountCode,
+            debit: l.credit,
+            credit: l.debit,
+            ...(l.memo ? { memo: l.memo } : {}),
+            ...(l.counterpartyId ? { counterpartyId: l.counterpartyId } : {}),
+        })),
+    };
+}
+/**
+ * Where a late correction must post.
+ *
+ * 🛑 Returns the entry's OWN period when it is open, and the caller's
+ * fallback when it is not — it never silently moves a posting. A rule that
+ * quietly re-dated anything landing in a closed period would make the lock
+ * invisible, and the first anyone knew of it would be a GST return that no
+ * longer reconciles to the books it was filed from.
+ */
+export function resolvePostingPeriod(wanted, isLocked, openFallback) {
+    if (!isLocked(wanted))
+        return { period: wanted, deferred: false };
+    if (isLocked(openFallback)) {
+        throw new UnbalancedEntryError(`Both ${wanted} and the fallback period ${openFallback} are locked; there is nowhere to post.`);
+    }
+    return { period: openFallback, deferred: true };
+}

package/dist/_internal/shared/features/ledger/reports.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Trial balance and P&L — derived views, pure, so the audit can exercise them.
+ *
+ * ## 🛑 These are REPORTS, not truth, and they carry the disclaimer
+ *
+ * Phase 12's `accounting-output` label applies to every figure produced
+ * here. The ledger is already a projection of orders and payouts; a report
+ * is a projection of the ledger. Nobody files a return from this without a
+ * CA reading it, and the label is what stops the number being treated as
+ * though they had.
+ *
+ * ## 🛑 Signs are applied ONCE, at the boundary
+ *
+ * A trial balance lists raw debit and credit totals per account, which is
+ * what makes it a check: the two columns must agree, and that is only
+ * meaningful if nothing has been netted on the way. The P&L is where a
+ * normal-balance sign is applied, and it is applied in exactly one place
+ * (`signedBalance`) so an income account can never be summed as though it
+ * were an expense.
+ */
+import type { AccountType, JournalEntryDocument, JournalLine } from "../../../../features/ledger/schemas/firestore";
+/** Which side increases this type. Duplicated from the schema's own helper? No — see below. */
+type Side = "debit" | "credit";
+export interface AccountTotals {
+    accountCode: string;
+    debit: number;
+    credit: number;
+}
+export interface TrialBalance {
+    period: string;
+    rows: AccountTotals[];
+    totalDebit: number;
+    totalCredit: number;
+    /** The identity. False means an entry was written outside `post()`. */
+    balanced: boolean;
+    /**
+     * Propagated from the read that produced it.
+     *
+     * 🛑 A truncated trial balance BALANCES — both columns lose the same
+     * entries — so `balanced: true` with `truncated: true` says nothing at
+     * all. A caller that renders the first and ignores the second is showing
+     * a reconciliation that did not happen.
+     */
+    truncated: boolean;
+}
+/** Sum every line by account. Raw columns, nothing netted. */
+export declare function trialBalance(period: string, entries: readonly JournalEntryDocument[], truncated?: boolean): TrialBalance;
+/**
+ * The net movement on an account, signed by its normal balance.
+ *
+ * 🛑 The ONE place a sign is applied. An income account with ₹1,000 credited
+ * and ₹100 debited has earned ₹900; the same raw figures on an expense
+ * account are a ₹900 loss in the other direction. Applying this per call
+ * site is how one of the two gets inverted and a P&L reads profitable.
+ */
+export declare function signedBalance(type: AccountType, totals: AccountTotals): number;
+export interface ProfitAndLoss {
+    period: string;
+    income: number;
+    expenses: number;
+    net: number;
+    truncated: boolean;
+}
+/**
+ * Income less expenses for a period.
+ *
+ * 🛑 Needs the account TYPES, which it takes as a map rather than inferring
+ * from the code's leading digit. The range convention is for humans (see the
+ * chart's own header); inferring from it makes the first out-of-range
+ * account silently land in the wrong half of the P&L, and the total would
+ * still look plausible.
+ */
+export declare function profitAndLoss(tb: TrialBalance, typeOf: (accountCode: string) => AccountType | undefined): ProfitAndLoss;
+/** Re-exported for the audit, which checks the two mappings agree. */
+export declare const NORMAL_SIDE_TABLE: Readonly<Record<AccountType, Side>>;
+export type { JournalLine };

package/dist/_internal/shared/features/ledger/reports.js

@@ -0,0 +1,127 @@
+/**
+ * Trial balance and P&L — derived views, pure, so the audit can exercise them.
+ *
+ * ## 🛑 These are REPORTS, not truth, and they carry the disclaimer
+ *
+ * Phase 12's `accounting-output` label applies to every figure produced
+ * here. The ledger is already a projection of orders and payouts; a report
+ * is a projection of the ledger. Nobody files a return from this without a
+ * CA reading it, and the label is what stops the number being treated as
+ * though they had.
+ *
+ * ## 🛑 Signs are applied ONCE, at the boundary
+ *
+ * A trial balance lists raw debit and credit totals per account, which is
+ * what makes it a check: the two columns must agree, and that is only
+ * meaningful if nothing has been netted on the way. The P&L is where a
+ * normal-balance sign is applied, and it is applied in exactly one place
+ * (`signedBalance`) so an income account can never be summed as though it
+ * were an expense.
+ */
+/*
+ * 🛑 `normalBalanceFor` lives on the SCHEMA and is not imported here, for the
+ * same mechanical reason `periodOf` moved out of it: `verify-posting-rules`
+ * loads these modules through Node's type stripping, which erases
+ * `import type` but cannot resolve a runtime import against extensionless
+ * appkit source.
+ *
+ * So this is NOT a second definition — the table below is the same mapping,
+ * and the schema's function is what application code calls. Two copies of a
+ * rule is Root Cause #42, and the honest mitigation is that `R6` in the
+ * audit asserts they agree for all five types rather than trusting a
+ * comment to keep them in step.
+ */
+const NORMAL_SIDE = {
+    asset: "debit",
+    expense: "debit",
+    liability: "credit",
+    equity: "credit",
+    income: "credit",
+};
+/** Sum every line by account. Raw columns, nothing netted. */
+export function trialBalance(period, entries, truncated = false) {
+    const byAccount = new Map();
+    for (const entry of entries) {
+        for (const line of entry.lines) {
+            const row = byAccount.get(line.accountCode) ??
+                { accountCode: line.accountCode, debit: 0, credit: 0 };
+            row.debit += line.debit ?? 0;
+            row.credit += line.credit ?? 0;
+            byAccount.set(line.accountCode, row);
+        }
+    }
+    const rows = [...byAccount.values()]
+        .map((r) => ({
+        accountCode: r.accountCode,
+        debit: round2(r.debit),
+        credit: round2(r.credit),
+    }))
+        .sort((a, b) => a.accountCode.localeCompare(b.accountCode));
+    const totalDebit = round2(rows.reduce((s, r) => s + r.debit, 0));
+    const totalCredit = round2(rows.reduce((s, r) => s + r.credit, 0));
+    return {
+        period,
+        rows,
+        totalDebit,
+        totalCredit,
+        /*
+         * 🛑 Compared with the SAME tolerance the posting rules use. A trial
+         * balance stricter than the gate that wrote the entries would report an
+         * imbalance nobody can act on — every entry in it passed `assertBalanced`.
+         */
+        balanced: Math.abs(totalDebit - totalCredit) <= 0.005,
+        truncated,
+    };
+}
+/**
+ * The net movement on an account, signed by its normal balance.
+ *
+ * 🛑 The ONE place a sign is applied. An income account with ₹1,000 credited
+ * and ₹100 debited has earned ₹900; the same raw figures on an expense
+ * account are a ₹900 loss in the other direction. Applying this per call
+ * site is how one of the two gets inverted and a P&L reads profitable.
+ */
+export function signedBalance(type, totals) {
+    return NORMAL_SIDE[type] === "debit"
+        ? round2(totals.debit - totals.credit)
+        : round2(totals.credit - totals.debit);
+}
+/**
+ * Income less expenses for a period.
+ *
+ * 🛑 Needs the account TYPES, which it takes as a map rather than inferring
+ * from the code's leading digit. The range convention is for humans (see the
+ * chart's own header); inferring from it makes the first out-of-range
+ * account silently land in the wrong half of the P&L, and the total would
+ * still look plausible.
+ */
+export function profitAndLoss(tb, typeOf) {
+    let income = 0;
+    let expenses = 0;
+    for (const row of tb.rows) {
+        const type = typeOf(row.accountCode);
+        /*
+         * 🛑 An UNKNOWN account is skipped and that is why `truncated` is not
+         * the only honesty flag this needs — but it is the behaviour with the
+         * least bad failure: including it would need a guessed type, and a
+         * guessed type puts real money on the wrong side. An account code with
+         * no account is a `chartOfAccounts` wipe (the orphan case its
+         * `seedPurpose: "permanent"` exists to prevent), and the trial balance
+         * above still shows the row, so the discrepancy is visible there.
+         */
+        if (!type)
+            continue;
+        if (type === "income")
+            income += signedBalance(type, row);
+        else if (type === "expense")
+            expenses += signedBalance(type, row);
+    }
+    income = round2(income);
+    expenses = round2(expenses);
+    return { period: tb.period, income, expenses, net: round2(income - expenses), truncated: tb.truncated };
+}
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+/** Re-exported for the audit, which checks the two mappings agree. */
+export const NORMAL_SIDE_TABLE = NORMAL_SIDE;

package/dist/_internal/shared/features/ledger/rules.d.ts

@@ -0,0 +1,170 @@
+/**
+ * What each business event posts.
+ *
+ * ## 🛑 THIS FILE IS THE WHOLE SAFETY ARGUMENT
+ *
+ * "Every journal entry is machine-generated from a business event" is the
+ * one constraint that makes a ledger maintained by a web application
+ * trustworthy. If a human has to remember that a gateway fee is
+ * `Dr Bank Charges / Cr Bank`, it will eventually be posted backwards — and
+ * a backwards entry still balances, so nothing downstream objects. These
+ * functions are where that memory lives instead.
+ *
+ * Pure, and returning a `PostingInput` rather than writing: the caller hands
+ * the result to `journalRepository.post`, which is the only thing that
+ * touches Firestore and the only thing that checks the period lock. That
+ * separation is also what lets `verify-posting-rules` exercise the rules
+ * against real order shapes without a database.
+ *
+ * ## 🛑 Codes are referenced through ACCOUNT, never as bare strings
+ *
+ * A literal `"2200"` scattered across six rules is six chances to type
+ * `"2000"`, and a posting to an account that does not exist is silently
+ * dropped from the P&L by `profitAndLoss`'s unknown-account skip. One map,
+ * named, so a wrong code is a compile error.
+ */
+import type { PostingInput } from "./posting";
+import type { ExpenseCategory } from "../../../../features/ledger/schemas/expenses";
+/** The accounts these rules post to. Codes match `chartOfAccountsSeedData`. */
+export declare const ACCOUNT: {
+    readonly BANK: "1100";
+    readonly COURIER_FLOAT: "1150";
+    readonly GATEWAY_RECEIVABLE: "1200";
+    readonly INPUT_GST: "1300";
+    readonly SELLER_PAYABLE: "2100";
+    readonly ACCOUNTS_PAYABLE: "2300";
+    readonly OUTPUT_GST: "2200";
+    readonly BUYER_DEPOSITS: "2400";
+    readonly REFUNDS_PAYABLE: "2500";
+    readonly OPENING_EQUITY: "3900";
+    readonly COMMISSION_INCOME: "4100";
+    readonly SHIPPING_RECOVERED: "4200";
+    readonly ADDON_INCOME: "4300";
+    readonly GATEWAY_CHARGES: "5100";
+    readonly FREIGHT_PAID: "5200";
+};
+export interface OrderPostingInput {
+    orderId: string;
+    storeId: string;
+    placedAt: Date;
+    /** What the buyer paid in total, GST included. */
+    totalPrice: number;
+    /** Product GST inside `totalPrice`. */
+    gstAmount?: number;
+    /** Our commission, and the GST we charge on it. */
+    platformFee?: number;
+    platformFeeGst?: number;
+    /** What the buyer paid for delivery, inside `totalPrice`. */
+    shippingFee?: number;
+    /** Gift wrap, protection, WhatsApp — inside `totalPrice`. */
+    addonFees?: number;
+}
+/**
+ * A paid order.
+ *
+ * 🛑 **The seller payable is the RESIDUAL, not a computed share.** Everything
+ * the platform keeps is recognised explicitly — commission, its GST, the
+ * shipping the buyer paid, add-ons, and output GST — and what remains is what
+ * the seller is owed. Computing the seller's share independently and letting
+ * the two meet in the middle is how a rounding difference becomes an
+ * unbalanced entry that `assertBalanced` then refuses at checkout, turning a
+ * half-paisa into a failed order.
+ *
+ * 🛑 **Output GST is a LIABILITY, which is the entire point of the exercise.**
+ * `revenueRollup.totalRevenue` sums `order.totalPrice`, so today's "revenue"
+ * includes tax owed to the government and freight owed to a courier. Crediting
+ * 2200 here is what separates turnover from takings for the first time.
+ *
+ * 🛑 The debit is to GATEWAY RECEIVABLE, not Bank. Money captured is not
+ * money arrived — the settlement lands days later, net of MDR, and
+ * `settlementPosting` is what clears this account. Debiting Bank here would
+ * overstate cash by the whole float for the length of the settlement cycle.
+ */
+export declare function orderPlacedPosting(o: OrderPostingInput): PostingInput;
+export interface SettlementPostingInput {
+    settlementId: string;
+    settledAt: Date;
+    /** Gross captured in this settlement, matching what was debited to 1200. */
+    gross: number;
+    /** The gateway's real MDR for it. */
+    fee: number;
+    /** GST on that fee — an INPUT credit, not a cost. */
+    feeGst: number;
+}
+/**
+ * A gateway settlement arriving in the bank.
+ *
+ * 🛑 `fee` here is the gateway's REAL charge from the settlement report, and
+ * it is NOT `PayoutDocument.gatewayFee` — that field is our own withholding
+ * against a seller's gross, a different number with a different meaning.
+ * Posting one as the other overstates our costs and understates what we
+ * withheld, in opposite directions, so the error compounds.
+ *
+ * 🛑 The GST on the fee is an ASSET (input credit), not an expense. Nothing
+ * in this codebase could receive input tax before Part 4, so this was simply
+ * unrecoverable — which is money, every month, that was never claimable.
+ */
+export declare function settlementPosting(s: SettlementPostingInput): PostingInput;
+export interface PayoutPostingInput {
+    payoutId: string;
+    storeId: string;
+    paidAt: Date;
+    amount: number;
+}
+/**
+ * Paying a seller.
+ *
+ * Clears the payable raised at order time against real cash. Two legs and no
+ * income or expense — paying a debt is not a cost, and treating it as one
+ * double-counts every sale.
+ */
+export declare function payoutPosting(p: PayoutPostingInput): PostingInput;
+export interface ExpensePostingInput {
+    expenseId: string;
+    vendorId?: string;
+    vendorName: string;
+    category: ExpenseCategory;
+    billDate: Date;
+    amount: number;
+    inputGst?: number;
+    /** Paid outright, or on credit? Decides the funding leg. */
+    paid: boolean;
+}
+/**
+ * A bill.
+ *
+ * 🛑 The funding leg depends on whether it was PAID, and conflating the two
+ * is the commonest small-business bookkeeping error: crediting Bank for a
+ * bill not yet paid shows cash leaving that is still there, and crediting
+ * Accounts payable for one already settled leaves a debt that does not
+ * exist. Both balance; both are wrong; neither announces itself.
+ *
+ * 🛑 `inputGst` is DEBITED to an asset, never added to the cost. Expensing
+ * it is how input credit silently stops being claimable — the money is
+ * spent either way, but only one of the two gets it back.
+ */
+export declare function expensePosting(e: ExpensePostingInput): PostingInput;
+export interface RefundPostingInput {
+    orderId: string;
+    refundId: string;
+    refundedAt: Date;
+    amount: number;
+    /** The product GST inside the refunded amount, which is reclaimable. */
+    gstAmount?: number;
+}
+/**
+ * A refund.
+ *
+ * 🛑 **A refund is NOT a negative sale, and that distinction is why the top
+ * line is currently wrong.** `revenueRollup` removes a fully-refunded order
+ * from its sum entirely and does not reduce it at all for a partial — so
+ * revenue silently rewrites itself retroactively, and no two runs of the same
+ * report over the same period agree.
+ *
+ * Here it is its own event with its own date: the sale stays in the month it
+ * happened, the refund lands in the month it happened, and both are visible.
+ *
+ * 🛑 It DEBITS output GST, reclaiming tax already declared. Omitting that leg
+ * means paying GST on money that was given back.
+ */
+export declare function refundPosting(r: RefundPostingInput): PostingInput;