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 type { Database } from "@carbon/database";
import type {
BuyPriceBreak,
CurrencyRate,
SupplierPriceBreak,
SupplierPriceMap
} from "@carbon/database/supplier-part-price";
import { TiptapText } from "@carbon/files/markdown";
import { z } from "zod";
import { zfd } from "zod-form-data";
export const chartIntervals = [
{ key: "week", label: "Week" },
{ key: "month", label: "Month" },
{ key: "quarter", label: "Quarter" },
{ key: "year", label: "Year" },
{ key: "custom", label: "Custom" }
];
export { documentTypes } from "@carbon/files";
export const incoterms = [
"EXW",
"FCA",
"FAS",
"FOB",
"CPT",
"CIP",
"CFR",
"CIF",
"DAP",
"DPU",
"DDP"
] as const;
export const inspectionStatus = ["Pass", "Fail"] as const;
export const tablesWithTags = [
"consumable",
"fixture",
"job",
"material",
"part",
"service",
"suggestion",
"tool"
];
// Item types that can appear as a BOM/method material component. Tool and
// Service are intentionally excluded — tools attach to operations
// (methodOperationTool) and services are billable activities bought or
// performed; neither is ever consumed as a component.
export const methodItemType = ["Part", "Material", "Consumable"] as const;
// Item types that can appear as a top-level quote/sales-order/purchase-order/
// invoice line. Tools and services are bought and sold even though neither is
// a method component, so this is wider than methodItemType.
export const itemType = [
"Part",
"Material",
"Tool",
"Consumable",
"Service"
] as const;
export const months = [
"January",
"February",
"March",
"April",
"May",
"June",
"July",
"August",
"September",
"October",
"November",
"December"
] as const;
export const methodOperationOrders = [
"After Previous",
"With Previous"
] as const;
export const methodType = [
"Purchase to Order",
"Pull from Inventory",
"Make to Order"
] as const;
export const sourcingType = [
"Specified",
"Drop Ship",
"Ship from Inventory"
] as const;
export const taxExemptionReasons = [
"Resale",
"Government",
"Nonprofit",
"Agriculture",
"Industrial",
"Export",
"Medical",
"Educational",
"Religious",
"Other"
] as const;
export const validMethodTypesByReplenishment: Record<
string,
readonly (typeof methodType)[number][]
> = {
Buy: ["Pull from Inventory", "Purchase to Order"],
Make: ["Pull from Inventory", "Make to Order"],
"Buy and Make": ["Pull from Inventory", "Purchase to Order"]
};
export function getValidMethodTypes(
replenishmentSystem: string
): readonly (typeof methodType)[number][] {
return validMethodTypesByReplenishment[replenishmentSystem] ?? [];
}
export const noteValidator = z.object({
id: zfd.text(z.string().optional()),
documentId: z.string().min(1),
note: z.string().min(1, { message: "Note is required" })
});
// The single operation classification, shared by operations (methodOperation /
// quoteOperation / jobOperation) and by processes (process.processType) — one
// Postgres enum backs both so they can never drift. Subcontract logic keys on
// === "Outside Processing"; in-house logic keys on !== "Outside Processing"
// (never an enumeration of the in-house values) so future in-house types inherit
// costing/scheduling/PO behavior unchanged.
// See .ai/specs/2026-07-20-operation-type-consolidation.md.
export const operationTypes = [
"Process",
"Assembly",
"Inspection",
"Outside Processing"
] as const;
export type OperationType = (typeof operationTypes)[number];
// Each operation type has exactly one instruction-source pointer: Process →
// procedureId, Assembly → assemblyInstructionId, Inspection →
// inspectionDocumentId. Writes go through this so a stale pointer can't survive
// a type change (sanitize() only nullifies present-undefined keys — it never
// clears an omitted field). See .ai/specs/2026-07-21-operation-instruction-sources.md.
// The same holds for the work center: Outside Processing runs at the supplier,
// and a work center left over from an in-house type put the operation on the
// MES Work Centers board.
/**
* A yes/no field. An API caller sends a JSON boolean and a form posts
* `"true"` / `"false"`; both parse to a boolean. Typed as taking a boolean, so
* the published API schema says `boolean`: the form's strings are its own.
*/
export const booleanField = () =>
z.preprocess(
(value) => (value === "true" ? true : value === "false" ? false : value),
z.boolean()
) as unknown as z.ZodType<boolean, boolean>;
/**
* A JSON value. A form posts it as text in a hidden field; an API caller sends
* the value itself. Typed as the value, so the published API schema describes
* it instead of "anything". Text that is not JSON is left for `schema` to refuse.
*/
export const jsonInput = <T extends z.ZodTypeAny>(schema: T) =>
z.preprocess((value) => {
if (typeof value !== "string") return value;
if (value.trim() === "") return undefined;
try {
return JSON.parse(value);
} catch {
return value;
}
}, schema) as unknown as T;
export function normalizeOperationSourceIds<
T extends {
operationType?: string;
procedureId?: string | null;
assemblyInstructionId?: string | null;
inspectionDocumentId?: string | null;
workCenterId?: string | null;
}
>(operation: T): T {
// The type's own pointer is written only when the caller sent it (a form
// clearing it sends the key); a partial update that left it out keeps it.
const own = <K extends keyof T>(key: K, type: string) =>
operation.operationType !== type
? { [key]: null }
: key in operation
? { [key]: operation[key] || null }
: {};
return {
...operation,
...(operation.operationType === "Outside Processing"
? { workCenterId: null }
: {}),
...own("procedureId", "Process"),
...own("assemblyInstructionId", "Assembly"),
...own("inspectionDocumentId", "Inspection")
};
}
export const procedureStepType = [
"Task",
"Value",
"Measurement",
"Checkbox",
"Timestamp",
"Person",
"List",
"File",
"Inspection"
] as const;
export const feedbackValidator = z.object({
feedback: z.string().min(1, { message: "" }),
attachmentPath: z.string().optional(),
location: z.string()
});
export const processTypes = [
"Inside",
"Outside",
"Inside and Outside"
] as const;
export const suggestionValidator = z.object({
suggestion: z.string().min(1, { message: "Suggestion is required" }),
emoji: z.string().default("💡"),
attachmentPath: z.string().optional(),
path: z.string(),
userId: zfd.text(z.string().optional()),
sendToCarbon: zfd
.text(z.string().optional())
.transform((value) => value === "true")
});
export const oAuthCallbackSchema = z.object({
code: z.string(),
state: z.string()
});
/**
* Coerces whatever a caller sent for a rich-text column into a tiptap document
* object. Accepts Markdown text, a JSON-encoded document (a form post), or the
* document itself (an MCP / API JSON body). `format: "text"` stores text as
* typed instead of reading it as Markdown.
*
* Rich-text columns (`internalNotes`, `externalNotes`, step descriptions) are
* `json`, and they MUST hold an object. A JSON string scalar stored there is
* read back by supabase-js as a JS string; when the row is later copied through
* Kysely (quote → sales order, RFQ → quote, quote → revision, method copies)
* the Postgres driver sends that string as raw text and Postgres rejects it
* with `invalid input syntax for type json`. The server functions serialise on
* their side too (`@carbon/database/json`), but the write side must never store the
* scalar in the first place. Never drops content to `{}`.
*
* Returns `any`: the doc is consumed both as a DB Json value and as editor
* JSONContent, and a narrower type breaks one of the two call sites.
*/
export function toTiptapDoc(
value: unknown,
format: "markdown" | "text" = "markdown"
): any {
return TiptapText(value, { format }).toDocument();
}
/**
* Optional rich-text field: absent or empty leaves the column untouched,
* anything else is stored as a tiptap document via `toTiptapDoc`. Declared as
* `string | object` on the input side so the MCP manifest (which publishes the
* INPUT schema) tells a caller both shapes are accepted, instead of the bare
* `{}` a `z.any()` produced.
*/
// A node's `content` must be a list of nodes, at every depth: a document
// whose content was a string reached the editor and RichTextView, which walk
// it as an array.
type TiptapNodeInput = { type: string; content?: TiptapNodeInput[] };
const tiptapNodeInput: z.ZodType<TiptapNodeInput> = z.lazy(() =>
z.looseObject({
type: z.string().min(1),
text: z.string().optional(),
content: z.array(tiptapNodeInput).optional()
})
);
const tiptapDocumentInput = z.looseObject({
type: z.literal("doc"),
content: z.array(tiptapNodeInput).optional()
});
const tiptapDocInput = (format?: "markdown" | "text") =>
z
.union([
z.string(),
// A Tiptap document, or `{}` to clear; any other object is refused.
tiptapDocumentInput,
z.strictObject({})
])
.transform((value): any =>
value === "" ? undefined : toTiptapDoc(value, format)
)
// `.optional()` LAST so the inferred key is optional (`notes?:`) — placing
// it before the transform makes zod infer a required key and every caller
// that omits `notes` stops compiling.
.optional();
/** Text read as Markdown. */
export const optionalTiptapDoc = tiptapDocInput();
/**
* Text stored as typed, for a field edited in a plain textarea that reads it
* back with `TiptapText(…).toString()`: Markdown markers would not survive that
* round trip (`1. Ship` would come back as `Ship`).
*/
export const optionalPlainTextDoc = tiptapDocInput("text");
/** Required rich text: Markdown, or a Tiptap document. */
export const requiredTiptapDoc = z
.union([z.string().trim().min(1), tiptapDocumentInput])
.transform((value): any => toTiptapDoc(value));
/**
* A List step's options. Blank rows (the empty row "Add option" leaves) are
* dropped before the step's refine runs, so a trailing empty row never blocks a
* save and is never stored.
*/
export const stepListValues = z
.array(z.string())
.transform((values) => values.filter((value) => value.trim() !== ""))
.optional();
export const operationStepValidator = z
.object({
id: zfd.text(z.string().optional()),
operationId: z.string().min(1, { message: "Operation is required" }),
name: z.string().trim().min(1, { message: "Name is required" }),
description: z
.string()
.min(1, { message: "Description is required" })
.transform((val): any => toTiptapDoc(val)),
type: z.enum(procedureStepType, {
error: "Type is required"
}),
unitOfMeasureCode: zfd.text(z.string().optional()),
minValue: zfd.numeric(z.number().min(0).optional()),
maxValue: zfd.numeric(z.number().min(0).optional()),
listValues: stepListValues,
sortOrder: zfd.numeric(z.number().min(0).optional())
})
.refine(
(data) => {
if (data.type === "Measurement") {
return !!data.unitOfMeasureCode;
}
return true;
},
{
message: "Unit of measure is required",
path: ["unitOfMeasureCode"]
}
)
.refine(
(data) => {
if (data.type === "List") {
return Array.isArray(data.listValues) && data.listValues.length > 0;
}
return true;
},
{
message: "List options are required",
path: ["listValues"]
}
)
.refine(
(data) => {
if (data.minValue != null && data.maxValue != null) {
return data.maxValue >= data.minValue;
}
return true;
},
{
message: "Maximum value must be greater than or equal to minimum value",
path: ["maxValue"]
}
);
// Display sizes for a step reference image, honored in the BOP editor grid and the MES
// operator view. Kept as a plain const tuple so both the zod enum and the UI reuse it.
export const slideSizes = ["small", "medium", "large"] as const;
export type SlideSize = (typeof slideSizes)[number];
// A single numbered annotation pin overlaid on a slide image. x/y are fractions (0..1) of
// the image box so a pin stays put at any rendered size. The pin's number is its position
// in the array (index + 1); label + color are optional.
export const slideAnnotationValidator = z.object({
id: z.string(),
x: z.number().min(0).max(1),
y: z.number().min(0).max(1),
label: z.string().optional(),
color: z.string().optional(),
// Optional "smart hotspot" link: the tool (item) this pin points at. Matches an
// operationTool.toolId, so the MES view can name the tool and badge it with the
// pin's sequence number. The pin's number (array index + 1) is the fastener order.
toolId: z.string().optional()
});
export type SlideAnnotation = z.infer<typeof slideAnnotationValidator>;
// A reference "slide" attached to an operation step — either an image (`imagePath`) or a
// 3D model (`modelUploadId` → modelUpload; STEP sources are converted to GLB by the
// assembler service). Authored on the method and copied to job/quote by get-method.
// A create must carry one of the two; updates may omit both (sanitize() drops absent
// fields so a caption/size-only save never wipes the content). Pins are image-only.
// `annotations` arrives over FormData as a JSON string and is parsed into an array here.
export const operationStepSlideValidator = z
.object({
id: zfd.text(z.string().optional()),
stepId: z.string().min(1, { message: "Step is required" }),
imagePath: zfd.text(z.string().optional()),
modelUploadId: zfd.text(z.string().optional()),
caption: zfd.text(z.string().optional()),
sortOrder: zfd.numeric(z.number().min(0).optional()),
size: zfd.text(z.enum(slideSizes).optional()),
// Absent = "not changed" (preserve on update / default on insert); a JSON string (incl.
// "[]" to clear) = the new pin set. Returning undefined when absent lets sanitize() drop
// it so a caption/size-only save never wipes existing annotations.
annotations: zfd.text(z.string().optional()).transform((value, ctx) => {
if (!value) return undefined;
try {
return z.array(slideAnnotationValidator).parse(JSON.parse(value));
} catch {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "Invalid annotations"
});
return z.NEVER;
}
})
})
.superRefine((slide, ctx) => {
if (!slide.id && !slide.imagePath && !slide.modelUploadId) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "An image or model is required",
path: ["imagePath"]
});
}
});
export const operationToolValidator = z.object({
id: zfd.text(z.string().optional()),
operationId: z.string().min(1, { message: "Operation is required" }),
toolId: z.string().min(1, { message: "Tool is required" }),
quantity: zfd.numeric(
z.number().min(0.000001, { message: "Quantity is required" })
)
});
export const operationParameterValidator = z.object({
id: zfd.text(z.string().optional()),
operationId: z.string().min(1, { message: "Operation is required" }),
key: z.string().min(1, { message: "Key is required" }),
value: z.string().min(1, { message: "Value is required" })
});
export const savedViewValidator = z.object({
id: zfd.text(z.string().optional()),
table: z.string(),
name: z
.string()
.trim()
.min(1, { message: "A name is required to save a view" }),
description: z.string().optional(),
filter: z.string().optional(),
sort: z.string().optional(),
state: z.string(),
type: z.enum(["Public", "Private"])
});
export const savedViewStateValidator = z.object({
columnOrder: z.array(z.string()),
columnPinning: z.any(),
columnVisibility: z.record(z.string(), z.boolean()),
filters: z.array(z.string()).optional(),
sorts: z.array(z.string()).optional()
});
/**
* An Inspection operation needs its inspection plan: unlike times, units and
* rates, nothing can fill it in. Spread into `.refine(...)`.
*/
export const inspectionPlanRequired: [
(operation: {
operationType: string;
inspectionDocumentId?: string;
}) => boolean,
{ message: string; path: string[] }
] = [
(operation) =>
operation.operationType !== "Inspection" ||
!!operation.inspectionDocumentId,
{ message: "Inspection Plan is required", path: ["inspectionDocumentId"] }
];
export const standardFactorType = [
"Hours/Piece",
"Hours/100 Pieces",
"Hours/1000 Pieces",
"Minutes/Piece",
"Minutes/100 Pieces",
"Minutes/1000 Pieces",
"Pieces/Hour",
"Pieces/Minute",
"Seconds/Piece",
"Total Hours",
"Total Minutes"
] as const;
/** A costing break: inventory quantity, base-currency price per inventory unit. */
export type PriceBreak = BuyPriceBreak;
export type { SupplierPriceMap };
/**
* A supplier part's pricing as the supplier quoted it — per purchase unit, in
* `currency.currencyCode` — with that currency's current rate.
*/
export type SupplierPartPricing = {
priceBreaks: SupplierPriceBreak[];
supplierUnitPrice: number | null;
currency: CurrencyRate;
};
export type NoteField = "internalNotes" | "externalNotes" | "notes";
type PublicTables = Database["public"]["Tables"];
/**
* The notes fields a person edits in the app, per table: what `setNotes` may
* set. Each one is a column of its table (checked below).
*/
export const noteFields = {
salesRfq: ["internalNotes", "externalNotes"],
salesRfqLine: ["internalNotes", "externalNotes"],
quote: ["internalNotes", "externalNotes"],
quoteLine: ["internalNotes", "externalNotes"],
salesOrder: ["internalNotes", "externalNotes"],
salesOrderLine: ["internalNotes", "externalNotes"],
salesInvoice: ["internalNotes", "externalNotes"],
salesInvoiceLine: ["internalNotes", "externalNotes"],
purchasingRfq: ["internalNotes"],
purchasingRfqLine: ["internalNotes", "externalNotes"],
supplierQuote: ["internalNotes", "externalNotes"],
supplierQuoteLine: ["internalNotes", "externalNotes"],
purchaseOrder: ["internalNotes", "externalNotes"],
purchaseOrderLine: ["internalNotes", "externalNotes"],
purchaseInvoice: ["internalNotes"],
purchaseInvoiceLine: ["internalNotes"],
receipt: ["internalNotes"],
shipment: ["internalNotes", "externalNotes"],
job: ["notes"],
item: ["notes"],
fixedAsset: ["notes"],
pickingList: ["notes"],
stockTransfer: ["notes"]
} as const satisfies {
readonly [T in keyof PublicTables]?: readonly (keyof PublicTables[T]["Row"] &
NoteField)[];
};
export type NoteTable = keyof typeof noteFields;
export const noteTables = Object.keys(noteFields) as [
NoteTable,
...NoteTable[]
];
/** The tables with an `assignee` column: what `assignRecord` may assign. */
export const assignableTables = [
"changeOrder",
"changeOrderActionTask",
"customer",
"item",
"job",
"jobOperation",
"lease",
"maintenanceDispatch",
"nonConformance",
"nonConformanceActionTask",
"nonConformanceApprovalTask",
"nonConformanceReviewer",
"pickingList",
"planningAction",
"procedure",
"purchaseInvoice",
"purchaseOrder",
"purchaseReturnOrder",
"purchasingRfq",
"qualityDocument",
"quote",
"receipt",
"riskRegister",
"salesInvoice",
"salesOrder",
"salesOrderShipment",
"salesReturnOrder",
"salesRfq",
"shipment",
"stockTransfer",
"supplier",
"supplierQuote",
"training"
] as const;