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.
// What a service function does around the building block it calls: put the
// caller's identity on the payload (`payload`), read the building block's
// `{ data, error }` as the result (`unwrap`, `paged`), and turn a posting
// engine's throw into a refusal (`run`).
import { failSpan, inSpan } from "@carbon/logger/span";
import { databaseRefusal } from "./database-refusal";
import { RAISED_EXCEPTION, ServerFnError, toServerFnError } from "./errors";
import { SERVICE_RULE_ERROR_CODE } from "./rule-error";
import {
CarbonError,
type ErrorCategory,
type ServiceContext
} from "./service-fn.server";
type StampField =
| "companyId"
| "companyGroupId"
| "createdBy"
| "updatedBy"
| "userId";
const IDENTITY_KEYS = [
"createdBy",
"updatedBy",
"companyId",
"companyGroupId"
] as const;
function isRecord(value: unknown): value is Record<string, unknown> {
return value !== null && typeof value === "object" && !Array.isArray(value);
}
/** Overwrite an identity key the caller put in `value`; never add one. */
function overwriteIdentityKeys(ctx: ServiceContext, value: unknown): unknown {
if (!isRecord(value) || !IDENTITY_KEYS.some((key) => key in value)) {
return value;
}
const row = { ...value };
if ("createdBy" in row) row.createdBy = ctx.auditUserId;
if ("updatedBy" in row) row.updatedBy = ctx.auditUserId;
if ("companyId" in row) row.companyId = ctx.company.id;
if ("companyGroupId" in row) row.companyGroupId = ctx.company.groupId;
return row;
}
/**
* The payload with the caller's identity in `fields`. `operation` picks the audit field of an upsert: a create gets
* `createdBy` and loses `updatedBy`, an update the reverse (a service that
* branches on `"createdBy" in` or `"updatedBy" in` takes the right branch).
* Without it, `fields` naming only `updatedBy` means an update and only
* `createdBy` a create.
*
* The input keeps unknown keys, so an identity key (`companyId`,
* `companyGroupId`, `createdBy`, `updatedBy`) the caller put at the top level,
* one level down, or in a row of a list is overwritten too, listed in `fields`
* or not: a payload cannot name another company or forge who wrote it.
* `userId` is overwritten only when listed: some inputs name a target user
* with it.
*/
function stamp<T>(
ctx: ServiceContext,
value: T,
fields: StampField[],
operation?: "create" | "update"
): T {
if (!value || typeof value !== "object") return value;
if (Array.isArray(value)) {
// A row of a list is spread into an INSERT: only createdBy is added (on a
// create), the other identity keys only overwritten.
const addCreatedBy = operation !== "update" && fields.includes("createdBy");
return value.map((element) => {
if (!isRecord(element)) return element;
const row: Record<string, unknown> = { ...element };
if (addCreatedBy || "createdBy" in row) row.createdBy = ctx.auditUserId;
if ("updatedBy" in row) row.updatedBy = ctx.auditUserId;
if ("companyId" in row) row.companyId = ctx.company.id;
if ("companyGroupId" in row) row.companyGroupId = ctx.company.groupId;
return row;
}) as T;
}
const stamped: Record<string, unknown> = { ...(value as object) };
const sets = (field: StampField) =>
fields.includes(field) || field in stamped;
// Fields that name one audit column name the operation: an update must not
// rewrite a record's creator, nor a create its last editor.
operation ??= fields.includes("createdBy")
? fields.includes("updatedBy")
? undefined
: "create"
: fields.includes("updatedBy")
? "update"
: undefined;
if (operation === "update") delete stamped.createdBy;
else if (sets("createdBy")) stamped.createdBy = ctx.auditUserId;
if (operation === "create") delete stamped.updatedBy;
else if (sets("updatedBy")) stamped.updatedBy = ctx.auditUserId;
if (sets("companyId")) stamped.companyId = ctx.company.id;
if (sets("companyGroupId")) stamped.companyGroupId = ctx.company.groupId;
if (fields.includes("userId")) stamped.userId = ctx.auditUserId;
for (const [key, nested] of Object.entries(stamped)) {
stamped[key] = Array.isArray(nested)
? nested.map((element) => overwriteIdentityKeys(ctx, element))
: overwriteIdentityKeys(ctx, nested);
}
return stamped as T;
}
/**
* The payload a service writes, with the caller's identity on it: the
* company always (unless `withoutCompany`), the author by the terminal.
*
* - `forCreate()` — `createdBy`; a `updatedBy` the caller sent is dropped.
* - `forUpdate()` — `updatedBy`; a `createdBy` is dropped, so an update never
* rewrites a record's creator.
* - `forUpsert()` — both: a service that branches on `"createdBy" in` picks.
* - `for(operation)` — `forCreate`, `forUpdate` or `forUpsert` by value.
* - `build()` — no author: a read, or a service that stamps its own.
*
* Whatever the terminal, an identity key (`companyId`, `companyGroupId`,
* `createdBy`, `updatedBy`) the caller put in the payload, one level down or
* in a list's rows is overwritten: a payload cannot name another company or
* forge who wrote it. `userId` is set only with `withUser`, since some
* inputs name a target user with it.
*/
export function payload<T>(ctx: ServiceContext, value: T) {
const fields = new Set<StampField>(["companyId"]);
const done = (audit: StampField[], operation?: "create" | "update") =>
stamp(ctx, value, [...fields, ...audit], operation);
const builder = {
/** Also `userId`, as the caller. */
withUser() {
fields.add("userId");
return builder;
},
/** Also `companyGroupId`. */
withGroup() {
fields.add("companyGroupId");
return builder;
},
/** No `companyId`: the table has none. */
withoutCompany() {
fields.delete("companyId");
return builder;
},
forCreate: (): T => done(["createdBy"], "create"),
forUpdate: (): T => done(["updatedBy"], "update"),
forUpsert: (): T => done(["createdBy", "updatedBy"]),
for: (operation: "create" | "update" | undefined): T =>
done(["createdBy", "updatedBy"], operation),
build: (): T => done([])
};
return builder;
}
function serviceRefusal(ctx: ServiceContext, error: unknown): CarbonError {
if (isRecord(error) && error.code === SERVICE_RULE_ERROR_CODE) {
return ctx.error("rule", String(error.message));
}
// A RAISE in our own SQL: its message was written for the person.
if (
isRecord(error) &&
error.code === RAISED_EXCEPTION &&
typeof error.message === "string" &&
error.message !== ""
) {
return ctx.error("rule", error.message, error);
}
const known = databaseRefusal(error);
return known
? ctx.error(known.category, known.message, error)
: ctx.error("internal", "The operation could not be completed.", error);
}
const STATUS_CATEGORIES: Record<number, ErrorCategory> = {
400: "validation",
401: "unauthenticated",
402: "entitlement",
403: "forbidden",
404: "notFound",
409: "conflict",
422: "rule",
429: "rateLimited"
};
/**
* A server function's refusal as a `CarbonError`: its status picks the
* category. A message at 500 is a body's authored refusal (a plain throw,
* which `toServerFnError` keeps): the caller's to fix. Our own failures (a
* programming error, a thrown 5xx, the data layer, a server failure) arrive
* with none and are `internal`, with `fallback` as the message.
*/
export function serverFnRefusal(
ctx: ServiceContext,
error: { status: number; message: string },
fallback = "The operation could not be completed."
): CarbonError {
const { status, message } = error;
const category =
STATUS_CATEGORIES[status] ?? (message ? "validation" : "internal");
return ctx.error(category, message || fallback, error);
}
/**
* What the service returned, as the tool's result: its `data` (with the
* `count` of a paged list), or the refusal it reported. A service does not
* throw: its failure is an `error` in what it returns, a failed element of a
* list of results, or `{ ok: false }`.
*/
function read(
ctx: ServiceContext,
result: unknown,
paginates = false
): unknown {
if (!isRecord(result)) return result;
if (result.error instanceof ServerFnError) {
return serverFnRefusal(ctx, result.error);
}
if (result.error) return serviceRefusal(ctx, result.error);
if ("data" in result) {
return paginates
? { rows: result.data, count: (result.count as number | null) ?? null }
: result.data;
}
return result;
}
type Envelope = { data?: unknown; error?: unknown; count?: number | null };
type DataOf<R> = R extends { data: infer D } ? D : never;
/**
* What a building block returned, as the service function's result: the
* `data` of each `{ data, error }`, or the first refusal. One result gives
* its data; several give a tuple of them.
*/
export function unwrap<R extends Envelope>(
ctx: ServiceContext,
result: R
): DataOf<R> | CarbonError;
export function unwrap<R extends Envelope[]>(
ctx: ServiceContext,
...results: R
): { [K in keyof R]: DataOf<R[K]> } | CarbonError;
export function unwrap(ctx: ServiceContext, ...results: Envelope[]): unknown {
const values: unknown[] = [];
for (const result of results) {
const value = read(ctx, result);
if (value instanceof CarbonError) return value;
values.push(value);
}
return results.length === 1 ? values[0] : values;
}
/** A paged list's `{ data, count, error }`: its rows and total, or its refusal. */
export function paged<R extends Envelope>(
ctx: ServiceContext,
result: R
): { rows: DataOf<R>; count: number | null } | CarbonError {
return read(ctx, result, true) as
| { rows: DataOf<R>; count: number | null }
| CarbonError;
}
/**
* Run a posting engine's body (a server function ported from
* `@carbon/server-functions`): its value, or what it threw as the refusal
* `defineServerFn` made of it. A thrown message is shown to the caller unless
* it came from the data layer, so the engines keep their own wording; the
* status decides the category (`NotFoundError` → `notFound`). One span per
* call, named `function <name>` as before.
*/
export async function run<R>(
ctx: ServiceContext,
name: string,
body: () => Promise<R>,
defaultStatus = 500
): Promise<R | CarbonError> {
const out = await attempt(ctx, name, body, defaultStatus);
return out.error ? (read(ctx, out) as CarbonError) : out.data;
}
/**
* {@link run}, but the refusal is the `ServerFnError` itself, as
* `serverFns.invoke` returned it: for a caller that reads its status or body.
* `body` gets the span, to name the actor when only it knows who the caller is.
*/
export function attempt<R>(
ctx: Pick<ServiceContext, "actor">,
name: string,
body: (span: {
setAttribute(key: string, value: string): unknown;
}) => Promise<R>,
defaultStatus = 500
): Promise<{ data: R; error: null } | { data: null; error: ServerFnError }> {
return inSpan(
`function ${name}`,
{ "carbon.function": name, "carbon.function.actor": ctx.actor.type },
async (span) => {
try {
return { data: await body(span), error: null };
} catch (err) {
const error = toServerFnError(name, err, defaultStatus);
span.setAttribute("carbon.function.status", error.status);
// The span keeps the detail a 5xx withholds from the caller.
if (error.status >= 500) {
failSpan(
span,
error.message || (err instanceof Error ? err.message : String(err))
);
}
return { data: null, error };
}
}
);
}