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.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
// 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.
import { toBaseAmount, toDocumentAmount } from "./accounting-currency.ts";
import { credit, debit } from "./ledger.ts";
import { assertBalanced, EPSILON, round, SCALE } from "./precision.ts";
export type SalesPostingAmountsInput = {
quantity: number;
unitPrice?: number | null;
/** Line discount, a fraction 0..1. Discounts merchandise only
* (`quantity × unitPrice`); add-ons and shipping are never discounted. */
discountPercent?: number | null;
shippingCost?: number | null;
addOnCost?: number | null;
nonTaxableAddOnCost?: number | null;
taxPercent?: number | null;
allocatedHeaderShipping?: number;
};
export type SalesPostingAmounts = {
salesRevenueBase: number;
shippingRevenueBase: number;
salesTaxBase: number;
grossReceivableBase: number;
};
export type SalesPostingAccount = {
id: string;
class: string | null;
active: boolean;
isGroup: boolean;
companyGroupId: string;
};
export type SalesPostingMetadata = {
customerTypeId: string | null;
itemPostingGroupId: string | null;
itemId: string | null;
locationId: string | null;
costCenterId: string | null;
fixedAssetClassId: string | null;
/** The line's project. `buildSalesPostingLines` keeps it on the revenue-side
* legs only (Sales, Deferred Revenue, the Rental revenue legs); AR, tax,
* shipping and disposal legs carry no project. */
projectId?: string | null;
};
/** A rental revenue leg references the agreement it earns under, a contract
* line's revenue legs the contract; every other line (AR, tax, shipping,
* disposal) references the invoice. */
export type SalesPostingDocumentType =
| "Invoice"
| "Rental Agreement"
| "Contract";
export type SalesPostingJournalLine = {
accountId: string;
description: string;
amount: number;
quantity: number;
documentType: SalesPostingDocumentType;
documentId: string;
externalDocumentId?: string | null;
documentLineReference?: string | null;
journalLineReference: string;
intercompanyPartnerId?: string | null;
companyId: string;
};
type DisposalAccounts = {
gainAccount?: SalesPostingAccount | null;
lossAccount?: SalesPostingAccount | null;
};
export type SalesPostingDisposal = DisposalAccounts &
(
| {
mode: "direct";
acquisitionCost: number;
accumulatedDepreciation: number;
assetAccount?: SalesPostingAccount | null;
accumulatedDepreciationAccount?: SalesPostingAccount | null;
}
| {
mode: "shipment";
netBookValue: number;
clearingAccount?: SalesPostingAccount | null;
}
);
/** One slice of the sales revenue component, credited to `account`. A leg with
* a negative amount (a credit line) lands as the mirrored debit. */
export type SalesRevenueLeg = {
account: SalesPostingAccount | null | undefined;
accountClass: "Revenue" | "Liability" | "Asset";
description: string;
/** Base amount, signed like the line. Required on every leg but the last;
* the last leg takes whatever the others leave of `salesRevenueBase`, so the
* legs always sum to it exactly. */
amount?: number;
documentType?: SalesPostingDocumentType;
documentId?: string;
};
export type BuildSalesPostingLinesInput = {
line: SalesPostingAmountsInput & { invoiceLineType: string };
context: {
companyId: string;
companyGroupId: string;
documentId: string;
externalDocumentId?: string | null;
documentLineReference?: string | null;
journalLineReference: string;
intercompanyPartnerId?: string | null;
};
accounts: {
receivables?: SalesPostingAccount | null;
sales?: SalesPostingAccount | null;
shipping?: SalesPostingAccount | null;
tax?: SalesPostingAccount | null;
};
metadata: SalesPostingMetadata;
disposal?: SalesPostingDisposal;
/** Revenue recognition: when set, the sales revenue leg is credited to this
* Liability account as "Deferred Revenue" instead of `accounts.sales`; a
* recognition run later moves it to Sales. Shipping, tax and AR legs are
* unchanged. `amounts.salesRevenueBase` is the deferred leg's base amount. */
deferredRevenueAccount?: SalesPostingAccount | null;
/** Replaces the Sales Account leg with these legs (Rental lines, which never
* post to Sales: deferred revenue, contract asset or rental income by kind).
* Required for `Rental`; not allowed with `deferredRevenueAccount` or on a
* Fixed Asset line. */
revenueLegs?: SalesRevenueLeg[];
};
function finite(amount: number, label: string): number {
if (!Number.isFinite(amount)) throw new Error(`${label} must be finite`);
return amount;
}
/** `quantity × unitPrice × (1 − discountPercent)`: the discounted merchandise
* every revenue, tax, shipping-weight and intercompany amount is built on. */
function netMerchandise(line: SalesPostingAmountsInput): number {
const discountPercent = finite(line.discountPercent ?? 0, "Discount");
return finite(
finite(line.quantity, "Quantity") *
finite(line.unitPrice ?? 0, "Unit price") *
(1 - discountPercent),
"Merchandise"
);
}
/** Raw arithmetic shared by ledger and provider boundaries; prices are already base. */
export function calculateSalesPostingAmounts(
input: SalesPostingAmountsInput
): SalesPostingAmounts {
const merchandise = netMerchandise(input);
const shipping = finite(input.shippingCost ?? 0, "Line shipping");
const addOn = finite(input.addOnCost ?? 0, "Taxable add-on");
const nonTaxableAddOn = finite(
input.nonTaxableAddOnCost ?? 0,
"Non-taxable add-on"
);
const taxPercent = finite(input.taxPercent ?? 0, "Tax rate");
const salesRevenueBase = finite(
merchandise + addOn + nonTaxableAddOn,
"Sales revenue"
);
const shippingRevenueBase = finite(
shipping + finite(input.allocatedHeaderShipping ?? 0, "Header shipping"),
"Shipping revenue"
);
const salesTaxBase = finite(
(merchandise + shipping + addOn) * taxPercent,
"Sales tax"
);
return {
salesRevenueBase,
shippingRevenueBase,
salesTaxBase,
grossReceivableBase: finite(
salesRevenueBase + shippingRevenueBase + salesTaxBase,
"Gross receivable"
)
};
}
export function allocateSalesHeaderShipping(
lines: Array<
SalesPostingAmountsInput & { id: string; invoiceLineType: string }
>,
headerShipping: number
): Map<string, number> {
const header = toBaseAmount(headerShipping, 1);
const eligible = lines
.filter((line) => line.invoiceLineType !== "Comment")
.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
if (eligible.length === 0 && header !== 0) {
throw new Error("Header shipping requires a postable invoice line");
}
const weights = eligible.map((line) =>
finite(
netMerchandise(line) +
finite(line.shippingCost ?? 0, "Line shipping") +
finite(line.addOnCost ?? 0, "Taxable add-on"),
"Header shipping weight"
)
);
const totalWeight = finite(
weights.reduce((sum, weight) => sum + weight, 0),
"Total shipping weight"
);
let allocated = 0;
return new Map(
eligible.map((line, index) => {
const amount =
index === eligible.length - 1
? round(header - allocated)
: toBaseAmount(
header *
(totalWeight === 0
? 1 / eligible.length
: weights[index]! / totalWeight),
1
);
allocated = round(allocated + amount);
return [line.id, amount];
})
);
}
export function calculateSalesIntercompanyAmount(
lines: Array<SalesPostingAmountsInput & { invoiceLineType: string }>,
exchangeRate: number
): number {
// Preserve the buyer-compatible matching basis: exclude add-ons, tax and header shipping.
// Merchandise is net of the line discount: the buyer keys the price it is
// charged (post-purchase-invoice matches on quantity × supplierUnitPrice).
const base = lines.reduce(
(sum, line) =>
line.invoiceLineType === "Comment"
? sum
: sum +
netMerchandise(line) +
finite(line.shippingCost ?? 0, "Line shipping"),
0
);
// The buyer records its half with round() at internal SCALE
// (post-purchase-invoice), and generate_intercompany_matches pairs the two
// sides on exact NUMERIC equality with no tolerance. Rounding this half at
// settlement precision instead would leave every trade whose document amount
// carries sub-cent digits permanently Unmatched, so eliminations would never
// run. This is a matching key, not a settlement amount: both halves round at
// SCALE.
return toDocumentAmount(base, exchangeRate, SCALE);
}
/** The posted base amounts of one line: each component rounded at internal
* scale, with the rounding residual against the rounded total reconciled
* onto the largest component. These are exactly the amounts
* `buildSalesPostingLines` posts. */
export function roundSalesPostingAmounts(
line: SalesPostingAmountsInput
): SalesPostingAmounts {
const raw = calculateSalesPostingAmounts(line);
const componentKeys = [
"salesRevenueBase",
"shippingRevenueBase",
"salesTaxBase"
] as const;
const amounts: SalesPostingAmounts = {
salesRevenueBase: toBaseAmount(raw.salesRevenueBase, 1),
shippingRevenueBase: toBaseAmount(raw.shippingRevenueBase, 1),
salesTaxBase: toBaseAmount(raw.salesTaxBase, 1),
grossReceivableBase: toBaseAmount(raw.grossReceivableBase, 1)
};
const residual = round(
amounts.grossReceivableBase -
componentKeys.reduce((sum, key) => sum + amounts[key], 0)
);
// Only reconcile the rounding of these three components and their total.
// No rounding account or arbitrary balancing entry can hide an economic mismatch.
const roundingEnvelope =
(componentKeys.length + 1) / (2 * 10 ** SCALE) + EPSILON;
if (Math.abs(residual) > roundingEnvelope) {
throw new Error("Sales component rounding exceeds its precision envelope");
}
if (residual !== 0) {
const recipient = [...componentKeys].sort(
(a, b) => Math.abs(raw[b]) - Math.abs(raw[a])
)[0]!;
amounts[recipient] = round(amounts[recipient] + residual);
}
return amounts;
}
export function buildSalesPostingLines(input: BuildSalesPostingLinesInput): {
lines: SalesPostingJournalLine[];
metadata: SalesPostingMetadata[];
amounts: SalesPostingAmounts;
saleProceeds: number;
netBookValue: number | null;
gainLoss: number | null;
signedDebitTotal: number;
/** Base amount of each revenue leg as posted, in the order given (the Sales
* Account leg alone when no `revenueLegs` were passed; empty for assets). */
revenueLegAmounts: number[];
} {
const {
line,
context,
accounts,
disposal,
deferredRevenueAccount,
revenueLegs
} = input;
const empty = {
salesRevenueBase: 0,
shippingRevenueBase: 0,
salesTaxBase: 0,
grossReceivableBase: 0
};
if (line.invoiceLineType === "Comment") {
return {
lines: [],
metadata: [],
amounts: empty,
saleProceeds: 0,
netBookValue: null,
gainLoss: null,
signedDebitTotal: 0,
revenueLegAmounts: []
};
}
if (
![
"Part",
"Service",
"Consumable",
"Fixture",
"Material",
"Tool",
"Fixed Asset",
"Rental"
].includes(line.invoiceLineType)
) {
throw new Error(`Unsupported invoice line type: ${line.invoiceLineType}`);
}
const isAsset = line.invoiceLineType === "Fixed Asset";
if (isAsset && !disposal) {
throw new Error("Fixed asset posting requires disposal facts");
}
if (line.invoiceLineType === "Rental" && !revenueLegs?.length) {
throw new Error("Rental posting requires its revenue legs");
}
if (revenueLegs?.length && (isAsset || deferredRevenueAccount)) {
throw new Error(
"Revenue legs cannot be combined with a disposal or a deferred revenue account"
);
}
const amounts = roundSalesPostingAmounts(line);
if (
amounts.shippingRevenueBase !== 0 &&
accounts.shipping?.id === accounts.sales?.id &&
accounts.shipping?.id
) {
throw new Error("Shipping revenue and sales accounts must be distinct");
}
const lines: SalesPostingJournalLine[] = [];
const metadata: SalesPostingMetadata[] = [];
let signedDebitTotal = 0;
const push = (
account: SalesPostingAccount | null | undefined,
accountClass: "Asset" | "Revenue" | "Liability" | "Expense",
side: "debit" | "credit",
amount: number,
description: string,
isControl = false,
quantity = line.quantity,
document?: { documentType: SalesPostingDocumentType; documentId: string },
isRevenueSide = false
) => {
const baseAmount = toBaseAmount(amount, 1);
if (baseAmount === 0) return;
if (
!account ||
account.class !== accountClass ||
!account.active ||
account.isGroup ||
account.companyGroupId !== context.companyGroupId
) {
throw new Error(
`Invalid or missing ${description} account; expected an active ${accountClass} leaf in this company group`
);
}
const naturalClass = accountClass.toLowerCase() as
| "asset"
| "revenue"
| "liability"
| "expense";
lines.push({
accountId: account.id,
description,
amount:
side === "debit"
? debit(naturalClass, baseAmount)
: credit(naturalClass, baseAmount),
quantity: round(quantity),
documentType: document?.documentType ?? "Invoice",
documentId: document?.documentId ?? context.documentId,
externalDocumentId: context.externalDocumentId,
documentLineReference: context.documentLineReference,
journalLineReference: context.journalLineReference,
...(isControl
? { intercompanyPartnerId: context.intercompanyPartnerId }
: {}),
companyId: context.companyId
});
// The project dimensions the revenue side only, never AR, tax or shipping.
metadata.push(
isRevenueSide || !input.metadata.projectId
? { ...input.metadata }
: { ...input.metadata, projectId: null }
);
signedDebitTotal += side === "debit" ? baseAmount : -baseAmount;
};
const revenueLegAmounts: number[] = [];
if (revenueLegs?.length) {
const base = amounts.salesRevenueBase;
let explicit = 0;
const legAmounts = revenueLegs.map((leg, index) => {
const isLast = index === revenueLegs.length - 1;
if (isLast !== (leg.amount === undefined)) {
throw new Error(
"Every revenue leg but the last carries an amount; the last takes the remainder"
);
}
if (isLast) return round(base - explicit);
const amount = toBaseAmount(finite(leg.amount!, leg.description), 1);
// A leg is a slice of the line, so it shares the line's sign.
if (amount * base < 0) {
throw new Error(`${leg.description} must carry the line's sign`);
}
explicit = round(explicit + amount);
return amount;
});
if (Math.abs(explicit) > Math.abs(base) + EPSILON) {
throw new Error("Revenue legs exceed the line's revenue");
}
revenueLegs.forEach((leg, index) => {
push(
leg.account,
leg.accountClass,
"credit",
legAmounts[index]!,
leg.description,
false,
line.quantity,
leg.documentType
? {
documentType: leg.documentType,
documentId: leg.documentId ?? context.documentId
}
: undefined,
true
);
revenueLegAmounts.push(legAmounts[index]!);
});
} else if (!isAsset) {
revenueLegAmounts.push(amounts.salesRevenueBase);
if (deferredRevenueAccount) {
push(
deferredRevenueAccount,
"Liability",
"credit",
amounts.salesRevenueBase,
"Deferred Revenue",
false,
line.quantity,
undefined,
true
);
} else {
push(
accounts.sales,
"Revenue",
"credit",
amounts.salesRevenueBase,
"Sales Account",
false,
line.quantity,
undefined,
true
);
}
}
push(
accounts.shipping,
"Revenue",
"credit",
amounts.shippingRevenueBase,
"Shipping Revenue"
);
push(
accounts.tax,
"Liability",
"credit",
amounts.salesTaxBase,
"Sales Tax Payable"
);
push(
accounts.receivables,
"Asset",
"debit",
amounts.grossReceivableBase,
context.intercompanyPartnerId ? "IC Receivables" : "Accounts Receivable",
true
);
let netBookValue: number | null = null;
let gainLoss: number | null = null;
if (isAsset && disposal) {
if (disposal.mode === "direct") {
const cost = toBaseAmount(disposal.acquisitionCost, 1);
const depreciation = toBaseAmount(disposal.accumulatedDepreciation, 1);
netBookValue = round(cost - depreciation);
push(
disposal.accumulatedDepreciationAccount,
"Asset",
"debit",
depreciation,
"Clear accumulated depreciation",
false,
1
);
push(
disposal.assetAccount,
"Asset",
"credit",
cost,
"Remove asset at cost",
false,
1
);
} else {
netBookValue = toBaseAmount(disposal.netBookValue, 1);
push(
disposal.clearingAccount,
"Expense",
"credit",
netBookValue,
"Clear disposal clearing"
);
}
gainLoss = round(amounts.salesRevenueBase - netBookValue);
if (gainLoss > 0) {
push(
disposal.gainAccount,
"Revenue",
"credit",
gainLoss,
"Gain on disposal",
false,
disposal.mode === "direct" ? 1 : line.quantity
);
}
if (gainLoss < 0) {
push(
disposal.lossAccount,
"Expense",
"debit",
-gainLoss,
"Loss on disposal",
false,
disposal.mode === "direct" ? 1 : line.quantity
);
}
}
signedDebitTotal = round(signedDebitTotal);
assertBalanced(signedDebitTotal, 0, EPSILON, "Sales invoice charge journal");
return {
lines,
metadata,
amounts,
saleProceeds: amounts.salesRevenueBase,
netBookValue,
gainLoss,
signedDebitTotal,
revenueLegAmounts
};
}