Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

13.0 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.

// Pure journal construction from authoritative, locked funding allocations.
// Cash/sourceAmount are document currency. Control, relief, carrying remainders,
// and the persisted per-application realized FX snapshots are company base.

import { assertExchangeRate, toBaseAmount } from "./accounting-currency.ts";
import {
  CUSTOMER_DEPOSIT_APPLIED_DESCRIPTION,
  CUSTOMER_DEPOSIT_DESCRIPTION,
  onAccountCreditDescription
} from "./accounting-posting.ts";
import { accountTypeFromClass, credit, debit } from "./ledger.ts";
import { assertBalanced, EPSILON, round } from "./precision.ts";

export interface PaymentJournalLine {
  accountId: string;
  description: string;
  amount: number;
  quantity: number;
  documentType: "Payment";
  documentId: string;
  documentLineReference?: string;
  journalLineReference: string;
  companyId: string;
}

export interface PaymentJournalApplicationInput {
  targetMemoId?: string | null;
  targetSalesInvoiceId?: string | null;
  targetPurchaseInvoiceId?: string | null;
  targetReimbursementId?: string | null;
  sourceAmount: number;
  sourcePaymentId: string | null;
  fxGainLossAmount: number;
  appliedAmount: number;
  discountAmount: number;
  writeOffAmount: number;
  targetExchangeRate: number;
  sourceExchangeRate: number;
  /** Original booked control accounts, resolved by the locked posting driver. */
  targetControlAccountId?: string;
  sourceControlAccountId?: string;
  /** The prior credit was booked as a customer deposit — a liability on the
   *  prepayment account — rather than on-account receivable credit, so its
   *  release debits a liability and is described as a deposit release. The
   *  driver reads this off the source's own journal line, never off today's
   *  defaults. */
  sourceIsDeposit?: boolean;
}

export interface PaymentJournalAccounts {
  controlAccountId: string | null;
  discountAccountId: string | null;
  /** The discount account's glAccountClass. Drives the discount line's natural-
   *  balance sign so a customer discount (Revenue) debits contra-revenue and a
   *  supplier discount (Expense/COGS) credits contra-cost. Resolved by index.ts;
   *  optional so callers without a discount need not supply it (falls back to
   *  "expense" for back-compat). */
  discountAccountClass?: string | null;
  writeOffAccountId: string | null;
  fxGainAccountId: string | null;
  fxLossAccountId: string | null;
}

// A fee withheld by a payment processor BEFORE the cash reaches the bank (e.g.
// Stripe Connect's per-charge commission) — never a fee billed separately. The
// caller resolves the account (a per-integration override or the company's
// service-charge default) and converts nothing; `amount` is in the payment's
// own currency, same as `totalAmount`, and gets the same exchangeRate applied.
export interface PaymentJournalFeeInput {
  amount: number;
  accountId: string;
  description?: string;
}

export interface BuildPaymentJournalInput {
  // Internal payment record id — becomes `documentId` on every line.
  paymentId: string;
  companyId: string;
  // Party determines the control account class; cash direction determines
  // debit/credit sides independently (including reusable refund arithmetic).
  isAR: boolean;
  /** An employee reimbursement payout. Structurally the AP arm — cash out,
   *  liability control debited — with `targetReimbursementId` as the target
   *  column and the reimbursement's own booked payable account (passed per
   *  application as `targetControlAccountId`) as the control. `isAR` stays
   *  false, so every sign in this builder is already correct. */
  isReimbursement?: boolean;
  cashIn: boolean;
  totalAmount: number;
  exchangeRate: number;
  bankAccount: string;
  // Resolved once by the driver (nanoid) so this stays pure.
  journalLineReference: string;
  applications: PaymentJournalApplicationInput[];
  /** Authoritative unused current-cash carrying remainder from funding allocation. */
  newOnAccountBase: number;
  accounts: PaymentJournalAccounts;
  fee?: PaymentJournalFeeInput;
  /** A customer deposit: the payment references a sales order or rental
   *  agreement. Its unapplied cash is a liability on `depositAccountId`
   *  (Customer Prepayments) instead of on-account receivable credit, and a
   *  Disbursement carrying the same reference refunds it from that account.
   *  Ignored for supplier payments; applications are unaffected. */
  isDeposit?: boolean;
  depositAccountId?: string | null;
}

export interface BuildPaymentJournalResult {
  lines: PaymentJournalLine[];
  // Running debit(+)/credit(−) balance; ~0 for a balanced entry.
  signedDebitTotal: number;
  // Accumulated realized FX in base currency (+gain / −loss). Mirrors the sum of
  // the applications' stored fxGainLossAmount.
  totalFxImpact: number;
}

function nonnegative(value: number, label: string): number {
  if (!Number.isFinite(value) || value < 0) {
    throw new Error(`${label} must be finite and nonnegative`);
  }
  return value;
}

export function buildPaymentJournal(
  input: BuildPaymentJournalInput
): BuildPaymentJournalResult {
  const {
    paymentId,
    companyId,
    isAR,
    isReimbursement = false,
    cashIn,
    totalAmount,
    exchangeRate,
    bankAccount,
    journalLineReference,
    applications,
    accounts,
    fee,
    depositAccountId
  } = input;
  const isDeposit = isAR && Boolean(input.isDeposit);
  if (!accounts.controlAccountId) {
    throw new Error("Missing control account default");
  }
  const grossBase = toBaseAmount(
    nonnegative(totalAmount, "Payment amount"),
    exchangeRate
  );
  const newOnAccountBase = toBaseAmount(
    nonnegative(input.newOnAccountBase, "New on-account carrying value"),
    1
  );
  if (
    fee &&
    (nonnegative(fee.amount, "Processor fee") > totalAmount || !fee.accountId)
  ) {
    throw new Error(
      "Processor fee requires an account and cannot exceed gross cash"
    );
  }
  const feeBase = fee ? toBaseAmount(fee.amount, exchangeRate) : 0;
  const lines: PaymentJournalLine[] = [];
  let signedDebitTotal = 0;
  const push = (
    side: "debit" | "credit",
    type: "asset" | "liability" | "equity" | "revenue" | "expense",
    magnitude: number,
    accountId: string | null,
    description: string,
    target?: string
  ) => {
    magnitude = toBaseAmount(nonnegative(magnitude, "Journal magnitude"), 1);
    if (magnitude === 0) return;
    if (!accountId) {
      throw new Error(`Missing account default for ${description}`);
    }
    signedDebitTotal += side === "debit" ? magnitude : -magnitude;
    lines.push({
      accountId,
      description,
      amount:
        side === "debit" ? debit(type, magnitude) : credit(type, magnitude),
      quantity: 1,
      documentType: "Payment",
      documentId: paymentId,
      documentLineReference: target,
      journalLineReference,
      companyId
    });
  };
  push(
    cashIn ? "debit" : "credit",
    "asset",
    round(grossBase - feeBase),
    bankAccount,
    "Bank / Cash"
  );
  if (fee) {
    push(
      cashIn ? "debit" : "credit",
      "expense",
      feeBase,
      fee.accountId,
      fee.description ?? "Payment Processing Fee"
    );
  }
  let totalFxImpact = 0;
  let currentCashReleased = 0;
  let currentDocumentReleased = 0;
  const priorCreditReleased = new Map<
    string,
    { amount: number; isDeposit: boolean }
  >();
  for (const app of applications) {
    const isRefund = !isReimbursement && cashIn !== isAR;
    const target = isReimbursement
      ? app.targetReimbursementId
      : isRefund
        ? app.targetMemoId
        : isAR
          ? app.targetSalesInvoiceId
          : app.targetPurchaseInvoiceId;
    if (
      !target ||
      (isReimbursement
        ? // A reimbursement payout carries no other target, no prior-credit
          // funding source, and no trade discount or write-off.
          app.targetSalesInvoiceId ||
          app.targetPurchaseInvoiceId ||
          app.targetMemoId ||
          app.sourcePaymentId ||
          app.discountAmount !== 0 ||
          app.writeOffAmount !== 0
        : isRefund
          ? app.targetSalesInvoiceId ||
            app.targetPurchaseInvoiceId ||
            app.targetReimbursementId ||
            app.sourcePaymentId ||
            app.discountAmount !== 0 ||
            app.writeOffAmount !== 0
          : app.targetMemoId ||
            app.targetReimbursementId ||
            (isAR ? app.targetPurchaseInvoiceId : app.targetSalesInvoiceId))
    ) {
      throw new Error("Invalid payment application target");
    }
    assertExchangeRate(app.targetExchangeRate);
    assertExchangeRate(app.sourceExchangeRate);
    const applied = nonnegative(app.appliedAmount, "Applied amount");
    const discount = nonnegative(app.discountAmount, "Discount amount");
    const writeOff = nonnegative(app.writeOffAmount, "Write-off amount");
    nonnegative(app.sourceAmount, "Source principal");
    if (!Number.isFinite(app.fxGainLossAmount)) {
      throw new Error("Settlement FX must be finite");
    }
    const releasedBase = round(
      applied + (cashIn ? app.fxGainLossAmount : -app.fxGainLossAmount)
    );
    nonnegative(releasedBase, "Released source carrying value");
    if (
      app.sourceAmount === 0 &&
      (releasedBase !== 0 || applied !== 0 || app.fxGainLossAmount !== 0)
    ) {
      throw new Error(
        "Zero source principal cannot release carrying value or realize FX"
      );
    }
    if (app.sourcePaymentId) {
      const sourceAccount =
        app.sourceControlAccountId ?? accounts.controlAccountId;
      const sourceIsDeposit = isAR && Boolean(app.sourceIsDeposit);
      const released = priorCreditReleased.get(sourceAccount);
      if (released && released.isDeposit !== sourceIsDeposit) {
        throw new Error(
          "Funding source account holds both deposit and on-account credit"
        );
      }
      priorCreditReleased.set(sourceAccount, {
        amount: round((released?.amount ?? 0) + releasedBase),
        isDeposit: sourceIsDeposit
      });
    } else {
      if (app.sourceExchangeRate !== exchangeRate) {
        throw new Error("Current cash rate does not match payment snapshot");
      }
      currentCashReleased += releasedBase;
      currentDocumentReleased += app.sourceAmount;
    }
    push(
      cashIn ? "credit" : "debit",
      isAR ? "asset" : "liability",
      round(applied + discount + writeOff),
      app.targetControlAccountId ?? accounts.controlAccountId,
      isReimbursement
        ? "Employee Reimbursements Payable"
        : isAR
          ? "Accounts Receivable"
          : "Accounts Payable",
      target
    );
    push(
      cashIn ? "debit" : "credit",
      accounts.discountAccountClass
        ? accountTypeFromClass(accounts.discountAccountClass)
        : "expense",
      discount,
      accounts.discountAccountId,
      isAR ? "Customer Payment Discount" : "Supplier Payment Discount",
      target
    );
    push(
      cashIn ? "debit" : "credit",
      isAR ? "expense" : "revenue",
      writeOff,
      accounts.writeOffAccountId,
      isAR ? "Bad Debt Expense" : "Vendor Write-Off Income",
      target
    );
    totalFxImpact += app.fxGainLossAmount;
  }
  if (currentDocumentReleased > totalAmount + EPSILON) {
    throw new Error("Applications exceed current document cash");
  }
  assertBalanced(
    grossBase,
    round(currentCashReleased + newOnAccountBase),
    EPSILON,
    "Current payment funding"
  );
  // Unapplied cash. A deposit is the customer's money held against a document,
  // so a Receipt books it as a liability on the prepayment account and a
  // Disbursement carrying the same reference refunds it from there — the same
  // two-direction leg the on-account credit below is, on a different account.
  if (isDeposit) {
    push(
      cashIn ? "credit" : "debit",
      "liability",
      newOnAccountBase,
      depositAccountId ?? null,
      CUSTOMER_DEPOSIT_DESCRIPTION
    );
  } else {
    push(
      cashIn ? "credit" : "debit",
      isAR ? "asset" : "liability",
      newOnAccountBase,
      accounts.controlAccountId,
      onAccountCreditDescription(isAR)
    );
  }
  for (const [accountId, released] of priorCreditReleased) {
    push(
      cashIn ? "debit" : "credit",
      released.isDeposit ? "liability" : isAR ? "asset" : "liability",
      released.amount,
      accountId,
      released.isDeposit
        ? CUSTOMER_DEPOSIT_APPLIED_DESCRIPTION
        : `${isAR ? "Accounts Receivable" : "Accounts Payable"} (credit applied)`
    );
  }
  totalFxImpact = round(totalFxImpact);
  if (totalFxImpact > 0) {
    push(
      "credit",
      "revenue",
      totalFxImpact,
      accounts.fxGainAccountId,
      "Realized FX Gain"
    );
  } else if (totalFxImpact < 0) {
    push(
      "debit",
      "expense",
      -totalFxImpact,
      accounts.fxLossAccountId,
      "Realized FX Loss"
    );
  }
  assertBalanced(
    signedDebitTotal,
    0,
    EPSILON,
    "Payment journal (base currency)"
  );
  return { lines, signedDebitTotal, totalFxImpact };
}