@tailor-platform/erp-kit 0.7.0 → 0.8.0

package/src/modules/accounting/command/createCostCenterHierarchyNode.ts

@@ -0,0 +1,117 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  HierarchyNotFoundError,
+  ParentNodeNotFoundError,
+  DuplicateRootNodeError,
+  SelfReferenceError,
+  CircularReferenceError,
+  InvalidNameError,
+} from "../lib/errors.generated";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface CreateCostCenterHierarchyNodeInput {
+  hierarchyId: string;
+  name: string;
+  parentNodeId?: string | null;
+  sortOrder?: number;
+}
+
+export async function run(
+  db: Transaction,
+  input: CreateCostCenterHierarchyNodeInput,
+  ctx: CommandContext,
+) {
+  void ctx;
+
+  // Validate name is non-empty
+  if (!input.name || input.name.trim() === "") {
+    return err(new InvalidNameError(input.hierarchyId));
+  }
+
+  // Validate hierarchy exists
+  const hierarchy = await db
+    .selectFrom("CostCenterHierarchy")
+    .where("id", "=", input.hierarchyId)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (!hierarchy) {
+    return err(new HierarchyNotFoundError(input.hierarchyId));
+  }
+
+  let level = 0;
+
+  if (input.parentNodeId) {
+    // Self-reference check (node cannot be its own parent - relevant for logical consistency)
+    // Note: for create, this is a guard against bad data passing nodeId == parentNodeId
+
+    // Validate parent node exists and belongs to the same hierarchy
+    const parentNode = await db
+      .selectFrom("CostCenterHierarchyNode")
+      .where("id", "=", input.parentNodeId)
+      .where("hierarchyId", "=", input.hierarchyId)
+      .selectAll()
+      .executeTakeFirst();
+
+    if (!parentNode) {
+      return err(new ParentNodeNotFoundError(input.parentNodeId));
+    }
+
+    // Check for self-reference and circular reference by walking the ancestor chain
+    const visited = new Set<string>();
+    let currentNodeId: string | null = input.parentNodeId;
+
+    while (currentNodeId !== null) {
+      if (visited.has(currentNodeId)) {
+        return err(new CircularReferenceError(input.parentNodeId));
+      }
+      visited.add(currentNodeId);
+
+      const currentNode = await db
+        .selectFrom("CostCenterHierarchyNode")
+        .where("id", "=", currentNodeId)
+        .select(["id", "parentNodeId"])
+        .executeTakeFirst();
+
+      if (!currentNode) break;
+
+      // Self-reference: node is its own parent
+      if (currentNode.parentNodeId === currentNode.id) {
+        return err(new SelfReferenceError(currentNodeId));
+      }
+
+      currentNodeId = currentNode.parentNodeId;
+    }
+
+    level = parentNode.level + 1;
+  } else {
+    // No parent means root node — check no existing root
+    const existingRoot = await db
+      .selectFrom("CostCenterHierarchyNode")
+      .where("hierarchyId", "=", input.hierarchyId)
+      .where("parentNodeId", "is", null)
+      .selectAll()
+      .executeTakeFirst();
+
+    if (existingRoot) {
+      return err(new DuplicateRootNodeError(input.hierarchyId));
+    }
+  }
+
+  // Create the node
+  const node = await db
+    .insertInto("CostCenterHierarchyNode")
+    .values({
+      hierarchyId: input.hierarchyId,
+      name: input.name,
+      parentNodeId: input.parentNodeId ?? null,
+      sortOrder: input.sortOrder ?? 1,
+      level,
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ node: node! });
+}

package/src/modules/accounting/command/createCostElement.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./createCostElement";
+import { defineCommand } from "@tailor-platform/erp-kit/module";
+
+export const createCostElement = defineCommand(permissions.createCostElement, run);

package/src/modules/accounting/command/createCostElement.test.ts

@@ -0,0 +1,317 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CompanyNotFoundError,
+  DuplicateCostElementCodeError,
+  InvalidCostElementTypeError,
+  InvalidCategoryForTypeError,
+  GlAccountRequiredError,
+  GlAccountNotFoundError,
+  GlAccountNotAllowedError,
+  DuplicateGlAccountReferenceError,
+  InvalidValidityPeriodError,
+} from "../lib/errors.generated";
+import {
+  baseCompany,
+  baseAccount,
+  inactiveAccount,
+  baseChartOfAccounts,
+  inactiveChartOfAccounts,
+  baseCostElement,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./createCostElement";
+
+describe("createCostElement", () => {
+  const validPrimaryInput = {
+    companyId: baseCompany.id,
+    code: "CE-NEW",
+    name: "New Cost Element",
+    type: "PRIMARY",
+    category: "overhead",
+    glAccountId: baseAccount.id,
+  };
+
+  it("creates cost element in DRAFT status with required fields", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    // company lookup, code uniqueness check, account lookup, CoA lookup, duplicate GL check
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(baseAccount)
+      .mockReturnValueOnce(baseChartOfAccounts)
+      .mockReturnValueOnce(undefined);
+    spies.insert.mockReturnValueOnce({
+      ...baseCostElement,
+      code: "CE-NEW",
+      name: "New Cost Element",
+    });
+
+    const result = await run(db, validPrimaryInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.costElement).toBeDefined();
+    expect(value.costElement.code).toBe("CE-NEW");
+  });
+
+  it("returns error when company does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { ...validPrimaryInput, companyId: "missing" }, commandCtx);
+
+    expectErr(result, CompanyNotFoundError);
+  });
+
+  it("returns error when company is not ACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce({ ...baseCompany, status: "INACTIVE" });
+
+    const result = await run(db, validPrimaryInput, commandCtx);
+
+    expectErr(result, CompanyNotFoundError);
+  });
+
+  it("returns error when code already exists within the company", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany).mockReturnValueOnce(baseCostElement);
+
+    const result = await run(db, { ...validPrimaryInput, code: baseCostElement.code }, commandCtx);
+
+    expectErr(result, DuplicateCostElementCodeError);
+  });
+
+  it("returns error when type is not PRIMARY or SECONDARY", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany).mockReturnValueOnce(undefined);
+
+    const result = await run(db, { ...validPrimaryInput, type: "TERTIARY" }, commandCtx);
+
+    expectErr(result, InvalidCostElementTypeError);
+  });
+
+  it("returns error when category does not match the type (secondary category on primary element)", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany).mockReturnValueOnce(undefined);
+
+    const result = await run(db, { ...validPrimaryInput, category: "assessment" }, commandCtx);
+
+    expectErr(result, InvalidCategoryForTypeError);
+  });
+
+  it("returns error when category does not match the type (primary category on secondary element)", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany).mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      { ...validPrimaryInput, type: "SECONDARY", category: "overhead", glAccountId: undefined },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidCategoryForTypeError);
+  });
+
+  it("returns error when PRIMARY element is missing glAccountId", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany).mockReturnValueOnce(undefined);
+
+    const result = await run(db, { ...validPrimaryInput, glAccountId: undefined }, commandCtx);
+
+    expectErr(result, GlAccountRequiredError);
+  });
+
+  it("returns error when GL account does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      { ...validPrimaryInput, glAccountId: "missing-account" },
+      commandCtx,
+    );
+
+    expectErr(result, GlAccountNotFoundError);
+  });
+
+  it("returns error when GL account is not active", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(inactiveAccount);
+
+    const result = await run(
+      db,
+      { ...validPrimaryInput, glAccountId: inactiveAccount.id },
+      commandCtx,
+    );
+
+    expectErr(result, GlAccountNotFoundError);
+  });
+
+  it("returns error when GL account is not in an active Chart of Accounts", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce({ ...baseAccount, chartOfAccountsId: inactiveChartOfAccounts.id })
+      .mockReturnValueOnce(inactiveChartOfAccounts);
+
+    const result = await run(db, validPrimaryInput, commandCtx);
+
+    expectErr(result, GlAccountNotFoundError);
+  });
+
+  it("returns error when SECONDARY element provides a glAccountId", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany).mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      {
+        ...validPrimaryInput,
+        type: "SECONDARY",
+        category: "assessment",
+        glAccountId: baseAccount.id,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, GlAccountNotAllowedError);
+  });
+
+  it("returns error when another PRIMARY element in the same company references the same GL account", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(baseAccount)
+      .mockReturnValueOnce(baseChartOfAccounts)
+      .mockReturnValueOnce(baseCostElement);
+
+    const result = await run(db, validPrimaryInput, commandCtx);
+
+    expectErr(result, DuplicateGlAccountReferenceError);
+  });
+
+  it("returns error when validFrom is after validTo", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(baseAccount)
+      .mockReturnValueOnce(baseChartOfAccounts)
+      .mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      { ...validPrimaryInput, validFrom: new Date("2025-12-31"), validTo: new Date("2025-01-01") },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidValidityPeriodError);
+  });
+
+  it("creates cost element with optional description", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const withDesc = { ...baseCostElement, description: "A description" };
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(baseAccount)
+      .mockReturnValueOnce(baseChartOfAccounts)
+      .mockReturnValueOnce(undefined);
+    spies.insert.mockReturnValueOnce(withDesc);
+
+    const result = await run(
+      db,
+      { ...validPrimaryInput, description: "A description" },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.costElement.description).toBe("A description");
+  });
+
+  it("creates cost element with validFrom and validTo dates", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const withDates = {
+      ...baseCostElement,
+      validFrom: new Date("2025-01-01"),
+      validTo: new Date("2025-12-31"),
+    };
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(baseAccount)
+      .mockReturnValueOnce(baseChartOfAccounts)
+      .mockReturnValueOnce(undefined);
+    spies.insert.mockReturnValueOnce(withDates);
+
+    const result = await run(
+      db,
+      { ...validPrimaryInput, validFrom: new Date("2025-01-01"), validTo: new Date("2025-12-31") },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.costElement.validFrom).toEqual(new Date("2025-01-01"));
+    expect(value.costElement.validTo).toEqual(new Date("2025-12-31"));
+  });
+
+  it("creates cost element without validity dates (indefinitely valid)", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(baseAccount)
+      .mockReturnValueOnce(baseChartOfAccounts)
+      .mockReturnValueOnce(undefined);
+    spies.insert.mockReturnValueOnce(baseCostElement);
+
+    const result = await run(db, validPrimaryInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.costElement.validFrom).toBeNull();
+    expect(value.costElement.validTo).toBeNull();
+  });
+
+  it("cost elements from different companies are isolated", async () => {
+    const companyB = { id: "company-2", status: "ACTIVE" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(companyB)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(baseAccount)
+      .mockReturnValueOnce(baseChartOfAccounts)
+      .mockReturnValueOnce(undefined);
+    const costElementB = { ...baseCostElement, companyId: companyB.id };
+    spies.insert.mockReturnValueOnce(costElementB);
+
+    const result = await run(db, { ...validPrimaryInput, companyId: companyB.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.costElement.companyId).toBe(companyB.id);
+  });
+
+  it("emits audit event recording acting user, timestamp, and initial field values", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(baseAccount)
+      .mockReturnValueOnce(baseChartOfAccounts)
+      .mockReturnValueOnce(undefined);
+    spies.insert.mockReturnValueOnce(baseCostElement);
+
+    const result = await run(db, validPrimaryInput, commandCtx);
+
+    expectOk(result);
+    expect(spies.insert).toHaveBeenCalled();
+  });
+});

package/src/modules/accounting/command/createCostElement.ts

@@ -0,0 +1,149 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CompanyNotFoundError,
+  DuplicateCostElementCodeError,
+  InvalidCostElementTypeError,
+  InvalidCategoryForTypeError,
+  GlAccountRequiredError,
+  GlAccountNotFoundError,
+  GlAccountNotAllowedError,
+  DuplicateGlAccountReferenceError,
+  InvalidValidityPeriodError,
+} from "../lib/errors.generated";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+const PRIMARY_CATEGORIES = ["overhead", "material", "labor", "depreciation"];
+const SECONDARY_CATEGORIES = [
+  "assessment",
+  "distribution",
+  "internal_activity_allocation",
+  "settlement",
+];
+
+export interface CreateCostElementInput {
+  companyId: string;
+  code: string;
+  name: string;
+  type: string;
+  category: string;
+  glAccountId?: string | null;
+  validFrom?: Date | null;
+  validTo?: Date | null;
+  description?: string | null;
+}
+
+/** Command: createCostElement
+ * Establishes a new cost element in DRAFT status within the management accounting module.
+ */
+export async function run(db: Transaction, input: CreateCostElementInput, ctx: CommandContext) {
+  void ctx;
+
+  // Validate company exists and is ACTIVE
+  const company = await db
+    .selectFrom("Company" as never)
+    .where("id" as never, "=", input.companyId as never)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (!company || (company as Record<string, unknown>).status !== "ACTIVE") {
+    return err(new CompanyNotFoundError(input.companyId));
+  }
+
+  // Validate code uniqueness within company
+  const existingCode = await db
+    .selectFrom("CostElement")
+    .where("companyId", "=", input.companyId)
+    .where("code", "=", input.code)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (existingCode) {
+    return err(new DuplicateCostElementCodeError(input.code));
+  }
+
+  // Validate type
+  if (input.type !== "PRIMARY" && input.type !== "SECONDARY") {
+    return err(new InvalidCostElementTypeError(input.type));
+  }
+
+  // Validate category matches type
+  if (input.type === "PRIMARY" && !PRIMARY_CATEGORIES.includes(input.category)) {
+    return err(new InvalidCategoryForTypeError(input.category));
+  }
+  if (input.type === "SECONDARY" && !SECONDARY_CATEGORIES.includes(input.category)) {
+    return err(new InvalidCategoryForTypeError(input.category));
+  }
+
+  // GL account validation for PRIMARY
+  if (input.type === "PRIMARY") {
+    if (!input.glAccountId) {
+      return err(new GlAccountRequiredError(input.code));
+    }
+
+    // Validate GL account exists and is active in an active CoA
+    const account = await db
+      .selectFrom("Account" as never)
+      .where("id" as never, "=", input.glAccountId as never)
+      .selectAll()
+      .executeTakeFirst();
+
+    if (!account || (account as Record<string, unknown>).status !== "ACTIVE") {
+      return err(new GlAccountNotFoundError(input.glAccountId));
+    }
+
+    const chartOfAccounts = await db
+      .selectFrom("ChartOfAccounts" as never)
+      .where("id" as never, "=", (account as Record<string, unknown>).chartOfAccountsId as never)
+      .selectAll()
+      .executeTakeFirst();
+
+    if (!chartOfAccounts || (chartOfAccounts as Record<string, unknown>).status !== "ACTIVE") {
+      return err(new GlAccountNotFoundError(input.glAccountId));
+    }
+
+    // Check no other PRIMARY element references same GL account in same company
+    const duplicateGlRef = await db
+      .selectFrom("CostElement")
+      .where("companyId", "=", input.companyId)
+      .where("glAccountId", "=", input.glAccountId)
+      .where("type", "=", "PRIMARY")
+      .selectAll()
+      .executeTakeFirst();
+
+    if (duplicateGlRef) {
+      return err(new DuplicateGlAccountReferenceError(input.glAccountId));
+    }
+  }
+
+  // GL account validation for SECONDARY - must NOT provide glAccountId
+  if (input.type === "SECONDARY" && input.glAccountId) {
+    return err(new GlAccountNotAllowedError(input.code));
+  }
+
+  // Validate validity dates
+  if (input.validFrom && input.validTo && input.validFrom > input.validTo) {
+    return err(new InvalidValidityPeriodError(input.code));
+  }
+
+  // Create cost element in DRAFT status
+  const costElement = await db
+    .insertInto("CostElement")
+    .values({
+      companyId: input.companyId,
+      code: input.code,
+      name: input.name,
+      type: input.type,
+      category: input.category,
+      glAccountId: input.glAccountId ?? null,
+      validFrom: input.validFrom ?? null,
+      validTo: input.validTo ?? null,
+      description: input.description ?? null,
+      status: "DRAFT",
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ costElement: costElement! });
+}

package/src/modules/accounting/command/createInternalOrder.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./createInternalOrder";
+import { defineCommand } from "@tailor-platform/erp-kit/module";
+
+export const createInternalOrder = defineCommand(permissions.createInternalOrder, run);