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.
// Server-side sales-rules evaluator. Cross-app entry point — the ERP quote /
// sales-order / sales-invoice line actions call `evaluateSalesRuleLines`.
// Mirrors `../storage/server.ts`.
//
// All functions here are server-only. Never import from a client module.
import type { Database } from "@carbon/database";
import {
breakQuantities,
type CompiledRule,
compileSalesRuleWithCache,
evaluateRules,
type ItemFilter,
ruleAppliesToItem,
type SalesRuleSurface,
toItemFilter,
type Violation
} from "@carbon/utils";
import type { SupabaseClient } from "@supabase/supabase-js";
import { companyHasFeature } from "../../plan.server";
import { itemPostingGroupIdFromEmbed } from "../storage/context";
import {
buildConditionValueResolver,
dedupeViolations
} from "../storage/server";
import {
buildSalesRuleLineContext,
type CustomerCtxInput,
type SalesRuleItemCtxRow,
type SalesRuleLineInput
} from "./context";
import { getActiveSalesRulesForItems } from "./service";
// Block/dedupe semantics are identical to storage rules — the
// `@carbon/ee/rules.server` barrel (`../server.ts`) re-exports `isBlocked` /
// `dedupeViolations` from `../storage/server` for both families.
type Client = SupabaseClient<Database>;
// ---------------------------------------------------------------------------
// Plan gate
// ---------------------------------------------------------------------------
export const isSalesRulesEnabledForCompany = (
client: Client,
companyId: string
): Promise<boolean> =>
companyHasFeature(client, companyId, { feature: "SALES_RULES" });
// ---------------------------------------------------------------------------
// Per-line evaluator — single entry point the sales line actions call
// ---------------------------------------------------------------------------
export type EvaluateSalesRuleLinesArgs = {
client: Client;
companyId: string;
userId: string;
surface: SalesRuleSurface;
lines: SalesRuleLineInput[];
/** The sales document's customer. null → no customer ctx is built. */
customerId: string | null;
/** The document's ship-to location; resolves `customer.location.countryCode`. */
customerLocationId: string | null;
};
export type EvaluateSalesRuleLinesResult = {
violations: Violation[];
ruleNames: Record<string, string>;
};
// Fresh object per call — a shared literal returned by reference is one
// caller mutation away from poisoning every subsequent evaluation.
const emptyResult = (): EvaluateSalesRuleLinesResult => ({
violations: [],
ruleNames: {}
});
export async function evaluateSalesRuleLines({
client,
companyId,
userId,
surface,
lines,
customerId,
customerLocationId
}: EvaluateSalesRuleLinesArgs): Promise<EvaluateSalesRuleLinesResult> {
if (lines.length === 0) {
return emptyResult();
}
if (!(await isSalesRulesEnabledForCompany(client, companyId))) {
return emptyResult();
}
const itemIds = new Set<string>();
for (const line of lines) {
if (line.itemId) itemIds.add(line.itemId);
}
const [customerRes, locationRes, itemsRes, rulesRes] = await Promise.all([
customerId
? client
.from("customer")
.select("id, customerTypeId, customerStatusId, customFields")
.eq("id", customerId)
.eq("companyId", companyId)
.maybeSingle()
: Promise.resolve({ data: null, error: null }),
customerLocationId
? client
.from("customerLocation")
.select("id, address(countryCode)")
.eq("id", customerLocationId)
// companyId scope matters here: the invoice-post gate evaluates with
// the service-role client, so RLS is not backstopping this read.
// maybeSingle: a missing location is an expected state — the null
// country flows into required-field semantics (fail closed).
.eq("companyId", companyId)
.maybeSingle()
: Promise.resolve({ data: null, error: null }),
itemIds.size > 0
? client
.from("item")
// `itemPostingGroupId` lives on the 1:1 `itemCost` row — embed it
// so the `item.itemPostingGroupId` rule field + filters resolve.
// NOTE: `item` has no `customFields` column — custom fields live on
// the subtype tables (part/material/tool/consumable/service). Selecting
// it here made PostgREST fail the whole query (42703), which silently
// produced zero items and skipped every broadcast rule.
.select(
"id, readableIdWithRevision, name, type, replenishmentSystem, itemTrackingType, itemCost(itemPostingGroupId)"
)
.in("id", Array.from(itemIds))
.eq("companyId", companyId)
: Promise.resolve({ data: [], error: null }),
getActiveSalesRulesForItems(client, companyId, Array.from(itemIds))
]);
const { rules, assignmentsByItemId } = rulesRes;
// Same reasoning as the item load below: a failed rule fetch returns an empty
// `rules` array, which reads as "nothing to enforce" and lets the line through.
if (rulesRes.error) {
throw new Error(
`Sales rule evaluation could not load rules: ${
(rulesRes.error as { message?: string }).message ??
String(rulesRes.error)
}`
);
}
// A failed item load must never pass silently. Without item rows every
// BROADCAST rule is skipped (`!itemForLine` below), so a bad select turns
// enforcement off with no signal — which is exactly how a missing column
// went unnoticed. Surface it instead.
if (itemsRes.error) {
throw new Error(
`Sales rule evaluation could not load items: ${
itemsRes.error.message ?? String(itemsRes.error)
}`
);
}
// A failed customer or location read is indistinguishable from "no type /
// no country": the ctx would be built with nulls and a rule on those fields
// would emit a misleading "required" violation. Fail loud like the rule and
// item loads above.
if (customerRes.error || locationRes.error) {
const err = customerRes.error ?? locationRes.error;
throw new Error(
`Sales rule evaluation could not load the customer context: ${
(err as { message?: string })?.message ?? String(err)
}`
);
}
// If no active rules exist, nothing can fire.
if (rules.length === 0) {
return emptyResult();
}
// Resolve the ship-to country off the customerLocation → address embed
// (PostgREST may materialize the 1:1 embed as object or array).
const countryCode = (() => {
const row = locationRes.data as { address?: unknown } | null;
if (!row) return null;
const address = Array.isArray(row.address) ? row.address[0] : row.address;
return (
(address as { countryCode?: string | null } | undefined)?.countryCode ??
null
);
})();
// Id-only fallback when the customer row lookup missed (RLS, deleted row)
// keeps `{customer.id}` tokens resolving; unresolved fields then trip
// required-field semantics. `location` stays undefined — NEVER `{}` — when
// no country resolves, so `customer.location.countryCode` rules fire their
// required-field violation.
const customer: CustomerCtxInput | undefined = customerId
? {
id: customerId,
customerTypeId: customerRes.data?.customerTypeId ?? null,
customerStatusId: customerRes.data?.customerStatusId ?? null,
customFields:
(customerRes.data?.customFields as
| Record<string, unknown>
| null
| undefined) ?? undefined,
location: countryCode ? { countryCode } : undefined
}
: undefined;
const itemsById = new Map<string, SalesRuleItemCtxRow>();
for (const it of itemsRes.data ?? []) {
const row = it as unknown as Record<string, unknown>;
const readable = row.readableIdWithRevision as string | null | undefined;
// Flatten the 1:1 `itemCost` embed's posting group onto the item ctx; drop
// the nested object. `id` becomes the readable id for token interpolation
// (mirrors the storage evaluator).
const { itemCost, ...rest } = row;
itemsById.set(row.id as string, {
...rest,
id: readable ?? (row.id as string),
itemPostingGroupId: itemPostingGroupIdFromEmbed(itemCost) ?? undefined
});
}
const compiledById = new Map<string, CompiledRule>();
const filtersById = new Map<string, ItemFilter>();
const ruleNamesById = new Map<string, string>();
for (const rule of rules) {
compiledById.set(rule.id, compileSalesRuleWithCache(rule));
filtersById.set(rule.id, toItemFilter(rule));
ruleNamesById.set(rule.id, rule.name);
}
// `{condition[N].name}` tokens resolve stored ids (customer type, status,
// country) to their labels — same resolver the storage evaluator uses.
const resolveConditionValue = await buildConditionValueResolver(
client,
companyId,
(function* () {
for (const rule of compiledById.values()) yield* rule.conditions;
})()
);
const violations: Violation[] = [];
for (const line of lines) {
const explicit = line.itemId
? assignmentsByItemId.get(line.itemId)
: undefined;
// Keyed by real item id; ctx `id` is the readable id.
const itemForLine = line.itemId ? itemsById.get(line.itemId) : undefined;
// Per-line rule set: explicit assignments fire unconditionally; broadcasts
// are gated per item by the rule's type/group filters (empty filters =
// every item). A line whose item row didn't load can't match a broadcast
// (mirrors the storage evaluator) — only its explicit assignments fire.
const compiledForLine: CompiledRule[] = [];
for (const rule of rules) {
const isExplicit = explicit?.has(rule.id) ?? false;
if (!isExplicit) {
if (!itemForLine) continue;
const filter = filtersById.get(rule.id) ?? {};
if (!ruleAppliesToItem(itemForLine, filter)) continue;
}
compiledForLine.push(compiledById.get(rule.id)!);
}
if (compiledForLine.length === 0) continue;
const ctx = buildSalesRuleLineContext({
line,
surface,
userId,
item: itemForLine,
customer
});
const ruleViolations = evaluateRules(compiledForLine, ctx, surface, {
resolveConditionValue
});
for (let i = 0; i < ruleViolations.length; i++) {
// Stamp the originating line so a document-level gate can attribute the
// violation and deep-link to it.
violations.push({ ...ruleViolations[i]!, lineId: line.lineId });
}
}
const deduped = dedupeViolations(violations);
if (deduped.length === 0) {
return { violations: deduped, ruleNames: {} };
}
// Names come off the already-loaded rule rows — no second query.
const ruleNames: Record<string, string> = {};
for (let i = 0; i < deduped.length; i++) {
const ruleId = deduped[i]!.ruleId;
const name = ruleNamesById.get(ruleId);
if (name) ruleNames[ruleId] = name;
}
return { violations: deduped, ruleNames };
}
// ---------------------------------------------------------------------------
// Document evaluator — the terminal-gate entry point
// ---------------------------------------------------------------------------
export type SalesDocumentType =
| "salesRfq"
| "quote"
| "salesOrder"
| "salesInvoice";
export type EvaluateSalesRulesForSalesDocumentArgs = {
client: Client;
companyId: string;
userId: string;
documentType: SalesDocumentType;
documentId: string;
};
/**
* Resolve the ship-to location a sales order actually delivers to.
*
* A drop shipment overrides the header: the goods go to the drop-ship customer
* location, not the ordering customer's. Evaluating the header alone would
* clear an order that ships somewhere else entirely — which defeats any rule
* keyed on `customer.location.countryCode`.
*/
export async function resolveSalesOrderShipTo(
client: Client,
salesOrderId: string,
companyId: string
): Promise<{ customerId: string | null; customerLocationId: string | null }> {
const [orderRes, shipmentRes] = await Promise.all([
client
.from("salesOrder")
.select("customerId, customerLocationId")
.eq("id", salesOrderId)
.eq("companyId", companyId)
.maybeSingle(),
client
.from("salesOrderShipment")
.select("dropShipment, customerId, customerLocationId")
.eq("id", salesOrderId)
.eq("companyId", companyId)
.maybeSingle()
]);
// This resolves WHERE the goods go, which is what country rules gate on.
// Guessing on a failed read would evaluate the wrong destination.
if (orderRes.error || shipmentRes.error) {
const err = orderRes.error ?? shipmentRes.error;
throw new Error(
`Sales rule evaluation could not resolve the ship-to for ${salesOrderId}: ${
(err as { message?: string })?.message ?? String(err)
}`
);
}
const shipment = shipmentRes.data;
if (shipment?.dropShipment) {
// A drop shipment's real destination is the shipment's, never the header's.
// If it is missing we return null rather than falling back: the header
// address is a DIFFERENT country, so falling back would silently clear a
// rule that should have blocked. Null flows into the engine's required-field
// semantics and surfaces "Customer location is required" at the rule's
// severity. (The form validator requires the pair, but the column is
// nullable, so API and legacy rows can still reach here without it.)
return {
customerId: shipment.customerId ?? orderRes.data?.customerId ?? null,
customerLocationId: shipment.customerLocationId ?? null
};
}
return {
customerId: orderRes.data?.customerId ?? null,
customerLocationId: orderRes.data?.customerLocationId ?? null
};
}
/**
* Resolve the ship-to of a sales invoice's STANDALONE lines (lines with no
* source order): the invoice shipment's `customerLocationId`.
*
* Never the bill-to (`invoiceCustomerLocationId`) — a different address and
* frequently a different country, so substituting it would clear a rule that
* should have blocked. With no ship-to set the location is null, which flows
* into the engine's required-field semantics and fails closed. Order-derived
* lines resolve through `resolveSalesOrderShipTo` instead.
*/
export async function resolveSalesInvoiceShipTo(
client: Client,
invoiceId: string,
companyId: string
): Promise<{ customerId: string | null; customerLocationId: string | null }> {
const [invoiceRes, shipmentRes] = await Promise.all([
client
.from("salesInvoice")
.select("customerId")
.eq("id", invoiceId)
.eq("companyId", companyId)
.maybeSingle(),
client
.from("salesInvoiceShipment")
.select("customerLocationId")
.eq("id", invoiceId)
.eq("companyId", companyId)
.maybeSingle()
]);
// Guessing on a failed read would evaluate the wrong destination.
if (invoiceRes.error || shipmentRes.error) {
const err = invoiceRes.error ?? shipmentRes.error;
throw new Error(
`Sales rule evaluation could not resolve the ship-to for ${invoiceId}: ${
(err as { message?: string })?.message ?? String(err)
}`
);
}
return {
customerId: invoiceRes.data?.customerId ?? null,
customerLocationId: shipmentRes.data?.customerLocationId ?? null
};
}
/**
* Evaluate every item-bearing line on a sales document, using the context as it
* stands right now.
*
* This is the terminal-gate counterpart to `evaluateSalesRuleLines`: rather than
* trusting that each line was checked when it was written, it re-reads the
* whole document. That covers lines created by paths that never ran the
* per-line check (conversions, duplication, integrations, the API) and catches
* staleness — a rule authored later, a ship-to that changed, an item whose
* attributes moved.
*
* Returned violations carry `lineId`, so callers can attribute them.
*/
export async function evaluateSalesRulesForSalesDocument({
client,
companyId,
userId,
documentType,
documentId
}: EvaluateSalesRulesForSalesDocumentArgs): Promise<EvaluateSalesRuleLinesResult> {
if (!(await isSalesRulesEnabledForCompany(client, companyId))) {
return emptyResult();
}
// A sales RFQ has no surface of its own — its lines are evaluated under
// `quoteLine`, because converting is precisely what turns them into quote
// lines. Only lines that already carry an item can be evaluated: convert
// mints placeholder items for the rest, and a just-created item has no rule
// assignments and only default attributes, so nothing could fire on it.
if (documentType === "salesRfq") {
const [rfqRes, linesRes] = await Promise.all([
client
.from("salesRfq")
.select("customerId, customerLocationId")
.eq("id", documentId)
.eq("companyId", companyId)
.maybeSingle(),
client
.from("salesRfqLine")
.select("id, itemId, quantity")
.eq("salesRfqId", documentId)
.eq("companyId", companyId)
]);
// A read error that silently yields zero lines (or a null header, whose
// missing customer would soften country rules) turns the gate off.
if (rfqRes.error || linesRes.error) {
const err = rfqRes.error ?? linesRes.error;
throw new Error(
`Sales rule evaluation could not load salesRfq ${documentId}: ${err?.message}`
);
}
// Evaluate every quantity break — a min-quantity rule fires on the
// smallest break, a max-quantity rule on the largest; no single break is
// conservative for both. Dedupe collapses same-message repeats per line.
const lines: SalesRuleLineInput[] = (linesRes.data ?? [])
.filter((l) => !!l.itemId)
.flatMap((l) =>
breakQuantities(l.quantity).map((quantity) => ({
lineId: l.id,
itemId: l.itemId,
quantity
}))
);
return evaluateSalesRuleLines({
client,
companyId,
userId,
surface: "quoteLine",
lines,
customerId: rfqRes.data?.customerId ?? null,
customerLocationId: rfqRes.data?.customerLocationId ?? null
});
}
if (documentType === "quote") {
const [quoteRes, linesRes] = await Promise.all([
client
.from("quote")
.select("customerId, customerLocationId")
.eq("id", documentId)
.eq("companyId", companyId)
.maybeSingle(),
client
.from("quoteLine")
.select("id, itemId, quantity")
.eq("quoteId", documentId)
.eq("companyId", companyId)
]);
// A read error that silently yields zero lines (or a null header, whose
// missing customer would soften country rules) turns the gate off.
if (quoteRes.error || linesRes.error) {
const err = quoteRes.error ?? linesRes.error;
throw new Error(
`Sales rule evaluation could not load quote ${documentId}: ${err?.message}`
);
}
// A quote line carries an array of quantity breaks; evaluate each one —
// a min-quantity rule fires on the smallest break, a max-quantity rule on
// the largest. Dedupe collapses same-message repeats per line.
const lines: SalesRuleLineInput[] = (linesRes.data ?? [])
.filter((l) => !!l.itemId)
.flatMap((l) =>
breakQuantities(l.quantity).map((quantity) => ({
lineId: l.id,
itemId: l.itemId,
quantity
}))
);
return evaluateSalesRuleLines({
client,
companyId,
userId,
surface: "quoteLine",
lines,
customerId: quoteRes.data?.customerId ?? null,
customerLocationId: quoteRes.data?.customerLocationId ?? null
});
}
// A sales invoice can be raised with no upstream document at all, so this
// gate is the only checkpoint such an invoice ever passes. Ship-to is
// resolved PER SOURCE ORDER: a line converted from a sales order carries
// `salesOrderId` and resolves the real destination through that order
// (drop-ship included, staleness re-checked); a standalone line uses the
// invoice's own ship-to (`salesInvoiceShipment.customerLocationId`,
// `resolveSalesInvoiceShipTo`). None may be invented — the bill-to
// (`invoiceCustomerLocationId`) is a different address and frequently a
// different country, so substituting it would clear a rule that should
// have blocked. With no ship-to set, a null location flows into the
// engine's required-field semantics ("Customer country is required" at the
// rule's severity), so the information-poorer path fails closed.
if (documentType === "salesInvoice") {
const linesRes = await client
.from("salesInvoiceLine")
.select("id, itemId, quantity, salesOrderId")
.eq("invoiceId", documentId)
.eq("companyId", companyId);
// A read error that silently yields zero lines turns the gate off.
if (linesRes.error) {
throw new Error(
`Sales rule evaluation could not load sales invoice ${documentId}: ${linesRes.error.message}`
);
}
const itemLines = (linesRes.data ?? []).filter((l) => !!l.itemId);
// Group by source order so each group evaluates against the destination
// its goods actually ship to. The null key holds the standalone lines.
const groups = new Map<string | null, typeof itemLines>();
for (const line of itemLines) {
const key = line.salesOrderId ?? null;
const group = groups.get(key);
if (group) {
group.push(line);
} else {
groups.set(key, [line]);
}
}
// Per-group loads are bounded by the number of DISTINCT source orders on
// one invoice (typically 1–3), not by line count.
const results = await Promise.all(
[...groups].map(async ([salesOrderId, groupLines]) => {
const shipTo = salesOrderId
? await resolveSalesOrderShipTo(client, salesOrderId, companyId)
: await resolveSalesInvoiceShipTo(client, documentId, companyId);
return evaluateSalesRuleLines({
client,
companyId,
userId,
surface: "salesInvoiceLine",
lines: groupLines.map((l) => ({
lineId: l.id,
itemId: l.itemId,
quantity: l.quantity ?? 1
})),
customerId: shipTo.customerId,
customerLocationId: shipTo.customerLocationId
});
})
);
return {
violations: dedupeViolations(results.flatMap((r) => r.violations)),
ruleNames: Object.assign({}, ...results.map((r) => r.ruleNames))
};
}
if (documentType === "salesOrder") {
const [shipTo, linesRes] = await Promise.all([
resolveSalesOrderShipTo(client, documentId, companyId),
client
.from("salesOrderLine")
.select("id, itemId, saleQuantity")
.eq("salesOrderId", documentId)
.eq("companyId", companyId)
]);
// A lines-read error that silently yields zero lines turns the gate off.
if (linesRes.error) {
throw new Error(
`Sales rule evaluation could not load sales order lines for ${documentId}: ${linesRes.error.message}`
);
}
const lines: SalesRuleLineInput[] = (linesRes.data ?? [])
.filter((l) => !!l.itemId)
.map((l) => ({
lineId: l.id,
itemId: l.itemId,
quantity: l.saleQuantity ?? 1
}));
return evaluateSalesRuleLines({
client,
companyId,
userId,
surface: "salesOrderLine",
lines,
customerId: shipTo.customerId,
customerLocationId: shipTo.customerLocationId
});
}
// Exhaustiveness: a new document type must get its own branch — falling
// through to another document's query would silently evaluate nothing.
throw new Error(
`Unknown sales document type: ${documentType satisfies never}`
);
}