Skip to content

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.

19.4 KB
Raw Blame
// 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;