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: LicenseRef-Carbon-Commercial
// Carbon Enterprise file, licensed only under the Carbon Commercial License
// (packages/ee/LICENSE). Not AGPL. Running, modifying, or copying it beyond those terms requires a commercial license.
import type { AccountingProvider } from "../providers";
import type { Qbo } from "../providers/quickbooks-online";
import { QboProvider } from "../providers/quickbooks-online";
import type { Rillet } from "../providers/rillet";
import { RilletProvider } from "../providers/rillet";
import type { Xero } from "../providers/xero";
import { XeroProvider } from "../providers/xero";
/**
* Provider-agnostic read of one Carbon-pushed provider journal, for the
* tie-out's external-fidelity check (v3 spec §5): net DEBIT-SIGNED totals
* per remote account ref (debits positive, credits negative).
*
* `found: false` means the entry is missing, voided, or deleted remotely —
* the same drift semantics as the weekly presence check. A missing entity
* NEVER throws (each provider's read returns null on failure); a
* RatelimitError raised by the provider client propagates untouched so
* callers can pace themselves.
*
* The account ref is whatever the provider's journal payload exposes:
* Xero `AccountCode`, Rillet `account_code`, QBO `AccountRef.value` (the
* provider account id). Callers map refs back to Carbon accounts via the
* account-mapping rows, which carry both the external id and the external
* code.
*/
export type RemoteJournalTotals = {
found: boolean;
/** Net debit-signed total per remote account ref. Empty when not found. */
debitTotalsByAccountRef: Map<string, number>;
};
function notFound(): RemoteJournalTotals {
return { found: false, debitTotalsByAccountRef: new Map() };
}
/** Accumulate in integer cents so per-ref nets carry no float residue. */
function addCents(
centsByRef: Map<string, number>,
ref: string | null | undefined,
cents: number
): void {
if (!ref) return;
centsByRef.set(ref, (centsByRef.get(ref) ?? 0) + cents);
}
function toAmounts(centsByRef: Map<string, number>): Map<string, number> {
const totals = new Map<string, number>();
for (const [ref, cents] of centsByRef) {
totals.set(ref, cents / 100);
}
return totals;
}
/** Xero manual-journal LineAmounts are debit-signed already; ref = AccountCode. */
export function sumXeroManualJournalDebitTotals(
journal: Pick<Xero.ManualJournal, "JournalLines">
): Map<string, number> {
const cents = new Map<string, number>();
for (const line of journal.JournalLines ?? []) {
addCents(
cents,
line.AccountCode,
Math.round((Number(line.LineAmount) || 0) * 100)
);
}
return toAmounts(cents);
}
/**
* Rillet items carry an unsigned 2-dp string amount plus an explicit side:
* DEBIT adds, CREDIT subtracts; ref = account_code (always present on the
* payload, unlike the server-resolved optional account_id).
*/
export function sumRilletJournalEntryDebitTotals(
entry: Pick<Rillet.JournalEntry, "items">
): Map<string, number> {
const cents = new Map<string, number>();
for (const item of entry.items ?? []) {
const magnitude = Math.round((Number(item.amount?.amount) || 0) * 100);
addCents(
cents,
item.account_code,
item.side === "CREDIT" ? -magnitude : magnitude
);
}
return toAmounts(cents);
}
/**
* QBO line Amounts are always positive; PostingType "Debit" adds, "Credit"
* subtracts; ref = JournalEntryLineDetail.AccountRef.value.
*/
export function sumQboJournalEntryDebitTotals(
entry: Pick<Qbo.JournalEntry, "Line">
): Map<string, number> {
const cents = new Map<string, number>();
for (const line of entry.Line ?? []) {
const detail = line.JournalEntryLineDetail;
if (!detail) continue;
const magnitude = Math.round((Number(line.Amount) || 0) * 100);
addCents(
cents,
detail.AccountRef.value,
detail.PostingType === "Credit" ? -magnitude : magnitude
);
}
return toAmounts(cents);
}
/**
* Fetch one pushed provider journal by external id and reduce it to net
* debit-signed totals per remote account ref. Dispatches on the concrete
* provider class (the same discrimination core/service.ts uses to build
* providers). A provider without a journal reader — or an unknown provider
* — resolves found:false rather than throwing.
*/
export async function fetchRemoteJournalTotals(
provider: AccountingProvider,
externalId: string
): Promise<RemoteJournalTotals> {
if (provider instanceof XeroProvider) {
if (typeof provider.getManualJournal !== "function") return notFound();
const journal = await provider.getManualJournal(externalId);
if (
!journal ||
journal.Status === "VOIDED" ||
journal.Status === "DELETED"
) {
return notFound();
}
return {
found: true,
debitTotalsByAccountRef: sumXeroManualJournalDebitTotals(journal)
};
}
if (provider instanceof RilletProvider) {
if (typeof provider.getJournalEntry !== "function") return notFound();
const entry = await provider.getJournalEntry(externalId);
if (!entry) return notFound();
return {
found: true,
debitTotalsByAccountRef: sumRilletJournalEntryDebitTotals(entry)
};
}
if (provider instanceof QboProvider) {
if (typeof provider.getJournalEntry !== "function") return notFound();
const entry = await provider.getJournalEntry(externalId);
if (!entry) return notFound();
return {
found: true,
debitTotalsByAccountRef: sumQboJournalEntryDebitTotals(entry)
};
}
return notFound();
}