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.
import { posting } from "@carbon/api/postings.server";
import type { Database } from "@carbon/database";
import type { Kysely, KyselyDatabase } from "@carbon/database/client";
import { endSensorMachineTime } from "@carbon/database/machine-time";
import { getLogger } from "@carbon/logger";
import { datetime } from "@carbon/utils";
import type { SupabaseClient } from "@supabase/supabase-js";
import { EntitlementError, requireEntitlement } from "../entitlements.server";
import { integrations } from "../index";
import { resolveIntegrationSecrets } from "../integrations/secrets";
import { companyHasFeature } from "../plan.server";
import { machineTimeRefusal } from "./assignable";
import { createOeeProvider, isOeeProviderId } from "./registry";
import type { OeeProvider } from "./types";
/**
* OEE provider server functions. The authoring writes embed
* `requireEntitlement("INTEGRATIONS")`; `getOeeProvider` is the runtime path
* and degrades through `companyHasFeature` instead of throwing.
*/
const logger = getLogger("ee", "oee");
type Result<T> = { data: T; error: null } | { data: null; error: string };
const fail = (error: unknown): { data: null; error: string } => {
if (error instanceof EntitlementError) throw error;
return {
data: null,
error: error instanceof Error ? error.message : String(error)
};
};
export async function getOeeProvider(
serviceClient: SupabaseClient<Database>,
companyId: string,
integrationId: string
): Promise<Result<{ provider: OeeProvider; minimumStateSeconds: number }>> {
try {
const entitled = await companyHasFeature(serviceClient, companyId, {
feature: "INTEGRATIONS"
});
if (!entitled) return { data: null, error: "Not entitled" };
const integration = await serviceClient
.from("companyIntegration")
.select("metadata, secretRef, active")
.eq("companyId", companyId)
.eq("id", integrationId)
.maybeSingle();
if (integration.error) return fail(integration.error.message);
if (!integration.data?.active) {
return { data: null, error: "Integration is not active" };
}
const metadata = (await resolveIntegrationSecrets(
serviceClient,
companyId,
integrationId,
integration.data.metadata,
integration.data.secretRef
)) as Record<string, unknown>;
return { data: createOeeProvider(integrationId, metadata), error: null };
} catch (error) {
return fail(error);
}
}
/**
* Posts the Machine events that sensor time ended (machine and overhead cost
* to WIP), as an operator's press posts the events it ends. Call it after the
* transaction that ended them commits. A failure is logged, never thrown: the
* operation-finish and job-completion catch-ups post what is still unposted.
*/
export async function postEndedMachineEvents(
db: Kysely<KyselyDatabase>,
args: { companyId: string; userId: string; productionEventIds: string[] }
) {
if (args.productionEventIds.length === 0) return;
const handles = { db, companyId: args.companyId, userId: args.userId };
for (const productionEventId of args.productionEventIds) {
const posted = await posting("post-production-event", handles, {
productionEventId
});
// `success: false` is an event with nothing to post yet (no duration):
// the catch-ups take it once it has one.
if (posted.error) {
logger.error("Failed to post a Machine event", {
companyId: args.companyId,
productionEventId,
error: posted.error.message
});
}
}
}
export async function upsertWorkCenterDevice(
client: SupabaseClient<Database>,
db: Kysely<KyselyDatabase>,
args: {
companyId: string;
userId: string;
integration: string;
externalDeviceId: string;
externalSiteId: string | null;
siteTimezone: string | null;
deviceName: string;
workCenterId: string;
}
): Promise<Result<{ id: string }>> {
await requireEntitlement(client, args.companyId, "INTEGRATIONS");
try {
// Only an active OEE integration maps devices: a row for any other
// integration would hold the work center's one device slot, and nothing
// would ever sync it.
if (!isOeeProviderId(args.integration)) {
return {
data: null,
error: `${args.integration} is not an OEE provider`
};
}
let endedEventIds: string[] = [];
const result = await db.transaction().execute(async (trx) => {
const integration = await trx
.selectFrom("companyIntegration")
.select("active")
.where("id", "=", args.integration)
.where("companyId", "=", args.companyId)
.executeTakeFirst();
if (!integration?.active) {
return { data: null, error: "Integration is not active" };
}
// Kysely skips RLS, and the id comes from the form: the work center
// must be this company's (the composite FK refuses it too).
const workCenter = await trx
.selectFrom("workCenter")
.select("id")
.where("id", "=", args.workCenterId)
.where("companyId", "=", args.companyId)
.executeTakeFirst();
if (!workCenter) return { data: null, error: "Work center not found" };
const current = await trx
.selectFrom("workCenterDevice")
.select(["id", "workCenterId"])
.where("integration", "=", args.integration)
.where("externalDeviceId", "=", args.externalDeviceId)
.where("companyId", "=", args.companyId)
.forUpdate()
.executeTakeFirst();
if (current?.workCenterId === args.workCenterId) {
return { data: { id: current.id }, error: null };
}
const taken = await trx
.selectFrom("workCenterDevice")
.innerJoin("workCenter", (join) =>
join
.onRef("workCenter.id", "=", "workCenterDevice.workCenterId")
.onRef("workCenter.companyId", "=", "workCenterDevice.companyId")
)
.select([
"workCenterDevice.deviceName",
"workCenterDevice.integration",
"workCenter.name as workCenterName"
])
.where("workCenterDevice.workCenterId", "=", args.workCenterId)
.where("workCenterDevice.companyId", "=", args.companyId)
.executeTakeFirst();
if (taken) {
return {
data: null,
error: `${taken.workCenterName} already has ${taken.deviceName} from ${
integrations.find((entry) => entry.id === taken.integration)
?.name ?? taken.integration
}`
};
}
// A remap starts fresh: a new mapping time and no applied state. The
// time the device opened on its old work center ends now; no later
// sync of the old mapping will close it.
if (current) {
({ endedEventIds } = await endSensorMachineTime(trx, {
workCenterId: current.workCenterId,
companyId: args.companyId,
userId: args.userId,
at: datetime.timestamp()
}));
await trx
.deleteFrom("workCenterDevice")
.where("id", "=", current.id)
.where("companyId", "=", args.companyId)
.execute();
}
const inserted = await trx
.insertInto("workCenterDevice")
.values({
companyId: args.companyId,
workCenterId: args.workCenterId,
integration: args.integration,
externalDeviceId: args.externalDeviceId,
externalSiteId: args.externalSiteId,
siteTimezone: args.siteTimezone,
deviceName: args.deviceName,
createdBy: args.userId
})
.returning("id")
.executeTakeFirstOrThrow();
return { data: { id: inserted.id }, error: null };
});
await postEndedMachineEvents(db, {
companyId: args.companyId,
userId: args.userId,
productionEventIds: endedEventIds
});
return result;
} catch (error) {
return fail(error);
}
}
export async function deleteWorkCenterDevice(
client: SupabaseClient<Database>,
db: Kysely<KyselyDatabase>,
args: {
companyId: string;
userId: string;
integration: string;
externalDeviceId: string;
}
): Promise<Result<null>> {
await requireEntitlement(client, args.companyId, "INTEGRATIONS");
try {
const endedEventIds = await db.transaction().execute(async (trx) => {
const device = await trx
.selectFrom("workCenterDevice")
.select(["id", "workCenterId"])
.where("integration", "=", args.integration)
.where("externalDeviceId", "=", args.externalDeviceId)
.where("companyId", "=", args.companyId)
.forUpdate()
.executeTakeFirst();
if (!device) return [];
// Nothing syncs this work center after the delete, so the time its
// sensor opened ends now instead of staying open forever.
const ended = await endSensorMachineTime(trx, {
workCenterId: device.workCenterId,
companyId: args.companyId,
userId: args.userId,
at: datetime.timestamp()
});
await trx
.deleteFrom("workCenterDevice")
.where("id", "=", device.id)
.where("companyId", "=", args.companyId)
.execute();
return ended.endedEventIds;
});
await postEndedMachineEvents(db, {
companyId: args.companyId,
userId: args.userId,
productionEventIds: endedEventIds
});
return { data: null, error: null };
} catch (error) {
return fail(error);
}
}
/**
* Assign unattributed time to an operation: insert a Machine event for its
* interval and delete the row, then post the event. The event is the record;
* the row was only a question waiting for an answer.
*/
export async function assignUnattributedMachineTime(
client: SupabaseClient<Database>,
db: Kysely<KyselyDatabase>,
args: {
companyId: string;
userId: string;
unattributedMachineTimeId: string;
jobOperationId: string;
}
): Promise<Result<{ productionEventId: string }>> {
await requireEntitlement(client, args.companyId, "INTEGRATIONS");
try {
const result = await db.transaction().execute(async (trx) => {
const row = await trx
.selectFrom("unattributedMachineTime")
.select(["workCenterId", "startTime", "endTime"])
.where("id", "=", args.unattributedMachineTimeId)
.where("companyId", "=", args.companyId)
.forUpdate()
.executeTakeFirst();
if (!row) return { data: null, error: "Machine time not found" };
if (!row.endTime) {
return { data: null, error: "The machine is still running" };
}
// Checked under row locks, in this transaction: a job closed between
// the route's check and this insert must still refuse the time.
const operation = await trx
.selectFrom("jobOperation")
.innerJoin("job", (join) =>
join
.onRef("job.id", "=", "jobOperation.jobId")
.onRef("job.companyId", "=", "jobOperation.companyId")
)
.select(["jobOperation.status", "job.status as jobStatus"])
.where("jobOperation.id", "=", args.jobOperationId)
.where("jobOperation.companyId", "=", args.companyId)
.forUpdate()
.executeTakeFirst();
if (!operation) return { data: null, error: "Operation not found" };
const refusal = machineTimeRefusal(operation.status, operation.jobStatus);
if (refusal === "Locked") {
return {
data: null,
error: "Cannot modify a locked job. Reopen it first."
};
}
if (refusal) return { data: null, error: `The operation is ${refusal}` };
const event = await trx
.insertInto("productionEvent")
.values({
type: "Machine",
jobOperationId: args.jobOperationId,
workCenterId: row.workCenterId,
startTime: row.startTime,
endTime: row.endTime,
employeeId: null,
companyId: args.companyId,
createdBy: args.userId
})
.returning("id")
.executeTakeFirstOrThrow();
await trx
.deleteFrom("unattributedMachineTime")
.where("id", "=", args.unattributedMachineTimeId)
.where("companyId", "=", args.companyId)
.execute();
return { data: { productionEventId: event.id }, error: null };
});
if (result.data) {
await postEndedMachineEvents(db, {
companyId: args.companyId,
userId: args.userId,
productionEventIds: [result.data.productionEventId]
});
}
return result;
} catch (error) {
return fail(error);
}
}
/** Dismiss unattributed time: it was not job time, so the row is deleted. */
export async function dismissUnattributedMachineTime(
client: SupabaseClient<Database>,
db: Kysely<KyselyDatabase>,
args: {
companyId: string;
unattributedMachineTimeId: string;
}
): Promise<Result<null>> {
await requireEntitlement(client, args.companyId, "INTEGRATIONS");
try {
// A running row is still the sync's to close: deleting it would let the
// next sync open the same time again.
const deleted = await db
.deleteFrom("unattributedMachineTime")
.where("id", "=", args.unattributedMachineTimeId)
.where("companyId", "=", args.companyId)
.where("endTime", "is not", null)
.returning("id")
.executeTakeFirst();
if (!deleted) {
return {
data: null,
error: "Machine time not found, or the machine is still running"
};
}
return { data: null, error: null };
} catch (error) {
return fail(error);
}
}