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 { Constants } from "@carbon/database";
import { isUnsafeStoragePath } from "@carbon/files";
import {
type BatchRules,
isValidTimeZone,
resolveBatchRules
} from "@carbon/utils";
import { z } from "zod";
import { zfd } from "zod-form-data";
import { operationTypes, standardFactorType } from "../shared/shared.models";
// Batch compatibility rule levels — mirrors BatchRuleLevel in @carbon/utils.
// A tuple literal is needed for z.enum; kept in sync with BATCH_RULE_DIMENSIONS.
export const batchRuleLevels = ["must", "guide", "ignore"] as const;
// Seed the six process-form batch-rule fields from a stored (sparse/null)
// `batchRules` value, filling defaults. Used by the process create/edit forms so
// an untouched process shows Guide/Ignore defaults and a saved one round-trips.
export function batchRuleInitialValues(raw: BatchRules | null | undefined) {
const r = resolveBatchRules(raw);
return {
batchRuleItem: r.item,
batchRuleSubstance: r.substance,
batchRuleGrade: r.grade,
batchRuleDimension: r.dimension,
batchRuleForm: r.form,
batchRuleFinish: r.finish,
batchRuleProducedItem: r.producedItem
};
}
export const abilityCurveValidator = z.object({
data: z
.string()
.startsWith("[", { message: "Invalid JSON" })
.endsWith("]", { message: "Invalid JSON" }),
shadowWeeks: zfd.numeric(
z.number().min(0, { message: "Time shadowing is required" })
)
});
// An ability is a process's qualification: it is created ONLY by picking a
// process, and it carries no free-form name — the name derives from the linked
// process (renaming the process renames the ability).
export const abilityValidator = z.object({
processId: z.string().min(1, { message: "Process is required" }),
recertifyEveryDays: zfd.numeric(z.number().int().min(1).optional())
});
// The edit form only adjusts the recertification cadence; the process (and
// therefore the name) is fixed for the life of the ability.
export const abilityRecertifyValidator = z.object({
recertifyEveryDays: zfd.numeric(z.number().int().min(1).optional())
});
export const contractorValidator = z.object({
id: z.string().min(1, { message: "Supplier Contact is required" }),
supplierId: z.string().min(1, { message: "Supplier is required" }),
hoursPerWeek: zfd.numeric(
z.number().min(0, { message: "Hours are required" })
),
// abilities: z
// .array(z.string().min(1, { message: "Invalid ability" }))
// .optional(),
assignee: zfd.text(z.string().optional())
});
export const employeeAbilityCellValidator = z.object({
employeeId: z.string().min(1, { message: "Employee is required" }),
abilityId: z.string().min(1, { message: "Ability is required" }),
lastTrainingDate: zfd.text(z.string().optional()),
expiresAt: zfd.text(z.string().optional())
});
export const maintenanceFailureModeType = [
"Maintenance",
"Quality",
"Operations",
"Other"
] as const;
export const failureModeValidator = z.object({
id: zfd.text(z.string().optional()),
name: z.string().trim().min(1, { message: "Name is required" }),
type: z.enum(maintenanceFailureModeType)
});
export const locationValidator = z
.object({
id: zfd.text(z.string().optional()),
name: z.string().trim().min(1, { message: "Name is required" }),
code: zfd.text(z.string().optional()),
addressLine1: z.string().min(1, { message: "Address is required" }),
addressLine2: z.string().optional(),
city: z.string().min(1, { message: "City is required" }),
stateProvince: zfd.text(z.string().optional()),
postalCode: z.string().min(1, { message: "Postal Code is required" }),
countryCode: z.string().min(1, { message: "Country is required" }),
timezone: z
.string()
.min(1, { message: "Timezone is required" })
.refine(isValidTimeZone, { message: "Invalid timezone" }),
latitude: zfd.numeric(z.number().optional()),
longitude: zfd.numeric(z.number().optional())
})
.superRefine(({ latitude, longitude }, ctx) => {
if ((latitude && !longitude) || (!latitude && longitude)) {
ctx.addIssue({
code: "custom",
message: "Both latitude and longitude are required"
});
}
});
export const maintenanceDispatchCommentValidator = z.object({
id: zfd.text(z.string().optional()),
maintenanceDispatchId: z.string().min(1, { message: "Dispatch is required" }),
comment: z.string().min(1, { message: "Comment is required" })
});
export const maintenanceDispatchEventValidator = z
.object({
id: zfd.text(z.string().optional()),
maintenanceDispatchId: z
.string()
.min(1, { message: "Dispatch is required" }),
employeeId: z.string().min(1, { message: "Employee is required" }),
workCenterId: z.string().min(1, { message: "Work center is required" }),
startTime: z.string().min(1, { message: "Start time is required" }),
endTime: zfd.text(z.string().optional()),
notes: zfd.text(z.string().optional())
})
.refine(
(data) => {
if (data.endTime) {
return new Date(data.startTime) < new Date(data.endTime);
}
return true;
},
{
message: "Start time must be before end time",
path: ["endTime"]
}
);
export const maintenanceDispatchItemValidator = z.object({
id: zfd.text(z.string().optional()),
maintenanceDispatchId: z.string().min(1, { message: "Dispatch is required" }),
itemId: z.string().min(1, { message: "Item is required" }),
quantity: zfd.numeric(z.number().min(1)),
unitOfMeasureCode: z
.string()
.min(1, { message: "Unit of measure is required" }),
unitCost: zfd.numeric(z.number().min(0).optional())
});
export const maintenanceDispatchPriority = [
"Low",
"Medium",
"High",
"Critical"
] as const;
export const MaintenanceKPIs = [
{ key: "mttr", label: "Mean Time To Repair" },
{ key: "mtbf", label: "Mean Time Between Failures" },
{ key: "sparePartCost", label: "Spare Part Cost" },
{ key: "worstPerformingMachines", label: "Worst Performing Machines" },
{ key: "sparePartConsumption", label: "Spare Part Consumption" }
] as const;
export const maintenanceDispatchStatus = [
"Open",
"Assigned",
"In Progress",
"Completed",
"Cancelled"
] as const;
export const MAINTENANCE_DISPATCH_LOCKED_STATUSES = [
"Completed",
"Cancelled"
] as const;
export function isMaintenanceDispatchLocked(
status: string | null | undefined
): boolean {
return MAINTENANCE_DISPATCH_LOCKED_STATUSES.includes(
status as (typeof MAINTENANCE_DISPATCH_LOCKED_STATUSES)[number]
);
}
export const maintenanceDispatchValidator = z.object({
id: zfd.text(z.string().optional()),
status: z.enum(maintenanceDispatchStatus),
priority: z.enum(maintenanceDispatchPriority),
severity: z
.enum([
"Preventive",
"Operator Performed",
"Support Required",
"OEM Required"
] as const)
.optional(),
source: z
.enum(["Scheduled", "Reactive", "Non-Conformance"] as const)
.optional(),
oeeImpact: z
.enum(["Down", "Planned", "Impact", "No Impact"] as const)
.optional(),
workCenterId: zfd.text(z.string().optional()),
locationId: z.string().min(1, { message: "Location is required" }),
suspectedFailureModeId: zfd.text(z.string().optional()),
plannedStartTime: zfd.text(z.string().optional()),
plannedEndTime: zfd.text(z.string().optional()),
takesWorkCenterOffline: zfd.checkbox(),
assignee: zfd.text(z.string().optional()),
content: zfd.text(z.string().optional())
});
export const maintenanceDispatchWorkCenterValidator = z.object({
id: zfd.text(z.string().optional()),
maintenanceDispatchId: z.string().min(1, { message: "Dispatch is required" }),
workCenterId: z.string().min(1, { message: "Work center is required" })
});
export const maintenanceDispatchIssueValidator = z.object({
maintenanceDispatchItemId: z
.string()
.min(1, { message: "Maintenance Dispatch Item is required" }),
quantity: zfd.numeric(z.number()),
adjustmentType: z.enum(["Positive Adjmt.", "Negative Adjmt."])
});
export const maintenanceDispatchIssueTrackedEntityValidator = z.object({
maintenanceDispatchItemId: z.string(),
children: z.array(
z.object({
trackedEntityId: z.string(),
quantity: z.number()
})
)
});
export const maintenanceFrequency = [
"Daily",
"Weekly",
"Monthly",
"Quarterly",
"Annual"
] as const;
export const maintenanceScheduleItemValidator = z.object({
id: zfd.text(z.string().optional()),
maintenanceScheduleId: z.string().min(1, { message: "Schedule is required" }),
itemId: z.string().min(1, { message: "Item is required" }),
quantity: zfd.numeric(z.number().min(1)),
unitOfMeasureCode: z
.string()
.min(1, { message: "Unit of measure is required" })
});
export const maintenanceScheduleValidator = z
.object({
id: zfd.text(z.string().optional()),
name: z.string().trim().min(1, { message: "Name is required" }),
description: zfd.text(z.string().optional()),
workCenterId: z.string().min(1, { message: "Work center is required" }),
locationId: z.string().min(1, { message: "Location is required" }),
frequency: z.enum(maintenanceFrequency),
priority: z.enum(maintenanceDispatchPriority),
estimatedDuration: zfd.numeric(z.number().optional()),
takesWorkCenterOffline: zfd.checkbox(),
nextDueAt: zfd.text(z.string().optional()),
active: zfd.checkbox(),
// Day-of-week fields for daily frequency
monday: zfd.checkbox(),
tuesday: zfd.checkbox(),
wednesday: zfd.checkbox(),
thursday: zfd.checkbox(),
friday: zfd.checkbox(),
saturday: zfd.checkbox(),
sunday: zfd.checkbox(),
// Skip holidays option
skipHolidays: zfd.checkbox(),
// Procedure
procedureId: zfd.text(z.string().optional())
})
.superRefine((data, ctx) => {
// An offline PM subtracts its plannedStartTime → plannedEndTime window from the
// work center's capacity; plannedEndTime is derived from estimatedDuration, so
// without a duration the block would be open-ended. Require it when offline.
if (
data.takesWorkCenterOffline &&
(data.estimatedDuration === undefined ||
data.estimatedDuration === null ||
data.estimatedDuration <= 0)
) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
path: ["estimatedDuration"],
message:
"Estimated duration is required when the PM takes the work center offline"
});
}
});
export const maintenanceSeverity = [
"Preventive",
"Operator Performed",
"Support Required",
"OEM Required"
] as const;
export const maintenanceSource = [
"Scheduled",
"Reactive",
"Non-Conformance"
] as const;
export const oeeImpact = ["Down", "Planned", "Impact", "No Impact"] as const;
export const partnerValidator = z.object({
id: z.string().min(1, { message: "Supplier Location is required" }),
supplierId: zfd.text(z.string().optional()),
hoursPerWeek: zfd.numeric(
z.number().min(0, { message: "Hours are required" })
)
// abilityId: z.string().min(1, { message: "Invalid ability" }),
});
// What MES does when an operator lacks the ability a process requires.
// 'Warn' shows a banner; 'Block' refuses production work on the operation.
export const processAbilityPolicies =
Constants.public.Enums.processAbilityPolicy;
export const processValidator = z
.object({
id: zfd.text(z.string().optional()),
name: z.string().trim().min(1, { message: "Process name is required" }),
processType: z.enum(operationTypes, {
error: "Process type is required"
}),
defaultStandardFactor: z
.enum(standardFactorType, {
error: "Standard factor is required"
})
.optional(),
workCenters: z
.array(z.string().min(1, { message: "Invalid work center" }))
.optional(),
completeAllOnScan: zfd.checkbox(),
batchable: zfd.checkbox(),
batchType: z
.enum(["Sequential", "Simultaneous"])
.optional()
.default("Sequential"),
requiresAbility: zfd.checkbox(),
abilityPolicy: z.enum(processAbilityPolicies).optional(),
batchRuleItem: z.enum(batchRuleLevels).optional(),
batchRuleSubstance: z.enum(batchRuleLevels).optional(),
batchRuleGrade: z.enum(batchRuleLevels).optional(),
batchRuleDimension: z.enum(batchRuleLevels).optional(),
batchRuleForm: z.enum(batchRuleLevels).optional(),
batchRuleFinish: z.enum(batchRuleLevels).optional(),
batchRuleProducedItem: z.enum(batchRuleLevels).optional()
})
.refine((data) => {
if (data.processType !== "Outside Processing" && !data.workCenters) {
return { workCenters: ["Work center is required for inside process"] };
}
return true;
})
.refine((data) => {
if (
data.processType !== "Outside Processing" &&
!data.defaultStandardFactor
) {
return { defaultStandardFactor: ["Standard factor is required"] };
}
return true;
});
export const trainingAssignmentStatusOptions = [
"Completed",
"Pending",
"Overdue",
"Not Required"
] as const;
// An internal assignment points at a training; an external one only has a
// name, because the training happens in an outside system.
export const trainingAssignmentValidator = z
.object({
id: zfd.text(z.string().optional()),
isExternal: zfd.checkbox(),
trainingId: zfd.text(z.string().optional()),
name: zfd.text(z.string().trim().optional()),
groupIds: z
.array(z.string())
.min(1, { message: "At least one group is required" })
})
.superRefine((value, ctx) => {
if (value.isExternal && !value.name) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
path: ["name"],
message: "Name is required"
});
}
if (!value.isExternal && !value.trainingId) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
path: ["trainingId"],
message: "Training is required"
});
}
});
export const trainingCompletionValidator = z.object({
trainingAssignmentId: z
.string()
.min(1, { message: "Training assignment is required" }),
employeeId: z.string().min(1, { message: "Employee is required" }),
period: zfd.text(z.string().optional())
});
// Guide key: `{companyId}/training/{trainingId}/{uploadId}/{file name}` — the
// last segment is the name the author uploaded.
export function trainingGuideKeyPrefix(companyId: string, trainingId: string) {
return `${companyId}/training/${trainingId}/`;
}
// The browser posts the guide's key, so the server must not trust its shape.
export function isValidTrainingGuideKey(key: string, prefix: string) {
if (!key.startsWith(prefix) || isUnsafeStoragePath(key)) return false;
const segments = key.slice(prefix.length).split("/");
return segments.length === 2 && segments.every((segment) => segment !== "");
}
const YOUTUBE_HOSTS = new Set([
"youtube.com",
"www.youtube.com",
"m.youtube.com",
"music.youtube.com",
"youtube-nocookie.com",
"www.youtube-nocookie.com"
]);
const YOUTUBE_VIDEO_ID = /^[A-Za-z0-9_-]{11}$/;
// The video id of a YouTube link: watch, youtu.be, shorts, live and embed
// links. Null for anything else, so the server can refuse it.
export function getYouTubeVideoId(url: string) {
let parsed: URL;
try {
parsed = new URL(url.trim());
} catch {
return null;
}
if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return null;
const host = parsed.hostname.toLowerCase();
const segments = parsed.pathname.split("/").filter(Boolean);
let id: string | null | undefined = null;
if (host === "youtu.be") {
id = segments[0];
} else if (YOUTUBE_HOSTS.has(host)) {
if (segments[0] === "watch") id = parsed.searchParams.get("v");
else if (["shorts", "live", "embed", "v"].includes(segments[0] ?? ""))
id = segments[1];
}
return id && YOUTUBE_VIDEO_ID.test(id) ? id : null;
}
// A training's video is stored as the canonical watch link.
export function youTubeWatchUrl(videoId: string) {
return `https://www.youtube.com/watch?v=${videoId}`;
}
export function trainingCertificateKeyPrefix(
companyId: string,
trainingAssignmentId: string,
employeeId: string
) {
return `${companyId}/training-certificates/${trainingAssignmentId}/${employeeId}/`;
}
// A certificate is a PDF or a photo of one. HEIC is never stored: the ERP
// dropzone converts it to JPEG first, and phone browsers hand a JPEG to a file
// input that does not list HEIC.
export const trainingCertificateAccept = {
"application/pdf": [".pdf"],
"image/png": [".png"],
"image/jpeg": [".jpg", ".jpeg"]
};
export const TRAINING_CERTIFICATE_MAX_BYTES = 10 * 1024 * 1024;
const trainingCertificateExtensions = Object.values(trainingCertificateAccept)
.flat()
.map((extension) => extension.slice(1));
// The first bytes of each accepted type. The extension alone can be renamed
// onto any file.
const trainingCertificateSignatures: Record<string, number[]> = {
pdf: [0x25, 0x50, 0x44, 0x46, 0x2d], // %PDF-
png: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],
jpg: [0xff, 0xd8, 0xff],
jpeg: [0xff, 0xd8, 0xff]
};
export async function validateTrainingCertificate(
file: FormDataEntryValue | null
): Promise<
| { file: File; extension: string; error: null }
| { file: null; extension: null; error: string }
> {
if (!(file instanceof File) || file.size === 0) {
return { file: null, extension: null, error: "Upload a certificate file" };
}
const extension = file.name.split(".").pop()?.toLowerCase() ?? "";
const signature = trainingCertificateSignatures[extension];
if (!trainingCertificateExtensions.includes(extension) || !signature) {
return {
file: null,
extension: null,
error: "The certificate must be a PDF, PNG or JPG"
};
}
if (file.size > TRAINING_CERTIFICATE_MAX_BYTES) {
return {
file: null,
extension: null,
error: "The certificate must be 10 MB or smaller"
};
}
const head = new Uint8Array(
await file.slice(0, signature.length).arrayBuffer()
);
if (!signature.every((byte, index) => head[index] === byte)) {
return {
file: null,
extension: null,
error: "The certificate must be a PDF, PNG or JPG"
};
}
return { file, extension, error: null };
}
export const trainingFrequency = ["Once", "Quarterly", "Annual"] as const;
export const trainingQuestionType = [
"MultipleChoice",
"TrueFalse",
"MultipleAnswers",
"MatchingPairs",
"Numerical"
] as const;
export const trainingQuestionValidator = z
.object({
id: zfd.text(z.string().optional()),
trainingId: z.string().min(1, { message: "Training is required" }),
question: z.string().min(1, { message: "Question is required" }),
type: z.enum(trainingQuestionType, {
error: "Type is required"
}),
sortOrder: zfd.numeric(z.number().min(0).optional()),
required: zfd.checkbox().optional(),
// For MultipleChoice and MultipleAnswers
options: z.array(z.string()).optional(),
// Accept string (from Select) or array (from MultiSelect), normalize to array
correctAnswers: z
.union([z.string(), z.array(z.string())])
.optional()
.transform((val) => {
if (!val) return undefined;
if (Array.isArray(val)) return val.filter((v) => v.trim() !== "");
return val.trim() !== "" ? [val] : undefined;
}),
// For TrueFalse - accept string "true"/"false" and transform to boolean
correctBoolean: z
.union([z.boolean(), z.string()])
.optional()
.transform((val) => {
if (typeof val === "boolean") return val;
if (typeof val === "string") return val === "true";
return false;
}),
// For MatchingPairs - stored as JSON string
matchingPairs: zfd.text(z.string().optional()),
// For Numerical
correctNumber: zfd.numeric(z.number().optional()),
tolerance: zfd.numeric(z.number().min(0).optional())
})
.refine(
(data) => {
if (data.type === "MultipleChoice" || data.type === "MultipleAnswers") {
return (
!!data.options &&
data.options.length >= 2 &&
data.options.every((option) => option.trim() !== "")
);
}
return true;
},
{
message: "At least 2 options are required",
path: ["options"]
}
)
.refine(
(data) => {
if (data.type === "MultipleChoice") {
return !!data.correctAnswers && data.correctAnswers.length === 1;
}
return true;
},
{
message: "Exactly one correct answer is required for multiple choice",
path: ["correctAnswers"]
}
)
.refine(
(data) => {
if (data.type === "MultipleAnswers") {
return !!data.correctAnswers && data.correctAnswers.length >= 1;
}
return true;
},
{
message: "At least one correct answer is required",
path: ["correctAnswers"]
}
)
.refine(
(data) => {
if (data.type === "MatchingPairs") {
if (!data.matchingPairs) return false;
try {
const pairs = JSON.parse(data.matchingPairs);
return (
Array.isArray(pairs) &&
pairs.length >= 2 &&
pairs.every(
(pair: { left?: string; right?: string }) =>
pair.left?.trim() && pair.right?.trim()
)
);
} catch {
return false;
}
}
return true;
},
{
message: "At least 2 matching pairs are required",
path: ["matchingPairs"]
}
)
.refine(
(data) => {
if (data.type === "Numerical") {
return data.correctNumber !== undefined && data.correctNumber !== null;
}
return true;
},
{
message: "Correct number is required",
path: ["correctNumber"]
}
);
export const trainingStatus = ["Draft", "Active", "Archived"] as const;
export const trainingType = ["Mandatory", "Optional"] as const;
export const trainingValidator = z.object({
id: zfd.text(z.string().optional()),
name: z.string().trim().min(1, { message: "Name is required" }),
content: zfd.text(z.string().optional()),
grantsAbilityId: zfd.text(z.string().optional())
});
export const workCenterValidator = z
.object({
id: zfd.text(z.string().optional()),
name: z.string().trim().min(1, { message: "Name is required" }),
description: z.string(),
defaultStandardFactor: z.enum(standardFactorType, {
error: "Standard factor is required"
}),
departmentId: zfd.text(z.string().optional()),
laborRate: zfd.numeric(z.number().min(0)),
locationId: z.string().min(1, { message: "Location is required" }),
machineRate: zfd.numeric(z.number().min(0)),
overheadRate: zfd.numeric(z.number().min(0)),
processes: z
.array(z.string().min(1, { message: "Invalid process" }))
.optional(),
shifts: z.array(z.string().min(1, { message: "Invalid shift" })).optional(),
alwaysOn: zfd.checkbox(),
batchCapacity: zfd.numeric(z.number().int().min(1).optional()),
minimumBatchQuantity: zfd.numeric(z.number().int().min(1).optional())
})
.refine(
(data) =>
data.batchCapacity == null ||
data.minimumBatchQuantity == null ||
data.minimumBatchQuantity <= data.batchCapacity,
{
message: "Minimum batch quantity cannot exceed batch capacity",
path: ["minimumBatchQuantity"]
}
);
/**
* The work center form: its Operating hours choice is posted only to be
* checked, since "Some Shifts" with no shift picked would save as every
* shift. The API takes `workCenterValidator`, where `alwaysOn` and `shifts`
* say it all.
*/
export const workCenterFormValidator = workCenterValidator
.safeExtend({
operatingHours: zfd.text(z.enum(["all", "some", "lightsOut"]).optional())
})
.refine(
(data) => data.operatingHours !== "some" || (data.shifts?.length ?? 0) > 0,
{ message: "Select at least one shift", path: ["shifts"] }
);
/** The form's data as the API takes it: the choice was only for checking. */
export function withoutOperatingHours<T extends { operatingHours?: unknown }>({
operatingHours: _operatingHours,
...data
}: T): Omit<T, "operatingHours"> {
return data;
}