@tailor-platform/erp-kit 0.6.0 → 0.8.0

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

@@ -0,0 +1,48 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import { CompanyNotFoundError, InvalidNameError } from "../lib/errors.generated";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface CreateCostCenterHierarchyInput {
+  companyId: string;
+  name: string;
+  version: string;
+}
+
+export async function run(
+  db: Transaction,
+  input: CreateCostCenterHierarchyInput,
+  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 name is non-empty
+  if (!input.name || input.name.trim() === "") {
+    return err(new InvalidNameError(input.companyId));
+  }
+
+  // Create hierarchy
+  const hierarchy = await db
+    .insertInto("CostCenterHierarchy")
+    .values({
+      companyId: input.companyId,
+      name: input.name,
+      version: input.version,
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ hierarchy: hierarchy! });
+}

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

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

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

@@ -0,0 +1,171 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  HierarchyNotFoundError,
+  ParentNodeNotFoundError,
+  DuplicateRootNodeError,
+  InvalidNameError,
+  SelfReferenceError,
+  CircularReferenceError,
+} from "../lib/errors.generated";
+import {
+  baseCostCenterHierarchy,
+  rootCostCenterNode,
+  childCostCenterNode,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./createCostCenterHierarchyNode";
+
+describe("createCostCenterHierarchyNode", () => {
+  it("returns error when name is empty", async () => {
+    const { db } = createMockDb<Transaction>();
+
+    const result = await run(db, { hierarchyId: baseCostCenterHierarchy.id, name: "" }, commandCtx);
+
+    expectErr(result, InvalidNameError);
+  });
+
+  it("returns error when hierarchy does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { hierarchyId: "missing-hierarchy", name: "Root" }, commandCtx);
+
+    expectErr(result, HierarchyNotFoundError);
+  });
+
+  it("returns error when parent node does not exist in hierarchy", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCostCenterHierarchy) // hierarchy exists
+      .mockReturnValueOnce(undefined); // parent node not found
+
+    const result = await run(
+      db,
+      {
+        hierarchyId: baseCostCenterHierarchy.id,
+        name: "Child",
+        parentNodeId: "missing-parent",
+      },
+      commandCtx,
+    );
+
+    expectErr(result, ParentNodeNotFoundError);
+  });
+
+  it("returns error when creating duplicate root node (no parentNodeId)", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCostCenterHierarchy) // hierarchy exists
+      .mockReturnValueOnce(rootCostCenterNode); // existing root found
+
+    const result = await run(
+      db,
+      { hierarchyId: baseCostCenterHierarchy.id, name: "Another Root" },
+      commandCtx,
+    );
+
+    expectErr(result, DuplicateRootNodeError);
+  });
+
+  it("creates root node when no root exists", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCostCenterHierarchy) // hierarchy exists
+      .mockReturnValueOnce(undefined); // no existing root
+    spies.insert.mockReturnValueOnce(rootCostCenterNode);
+
+    const result = await run(
+      db,
+      { hierarchyId: baseCostCenterHierarchy.id, name: "Root" },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.node).toEqual(rootCostCenterNode);
+  });
+
+  it("creates child node with correct computed level", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCostCenterHierarchy) // hierarchy exists
+      .mockReturnValueOnce(rootCostCenterNode) // parent node found (level 0)
+      .mockReturnValueOnce(rootCostCenterNode); // ancestor walk: root has no parent, loop ends
+    spies.insert.mockReturnValueOnce(childCostCenterNode);
+
+    const result = await run(
+      db,
+      {
+        hierarchyId: baseCostCenterHierarchy.id,
+        name: "Administration",
+        parentNodeId: rootCostCenterNode.id,
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.node).toEqual(childCostCenterNode);
+    expect(value.node.level).toBe(1);
+  });
+
+  it("returns error when node references itself as parent", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCostCenterHierarchy) // hierarchy exists
+      .mockReturnValueOnce(rootCostCenterNode) // parent node found
+      .mockReturnValueOnce({ ...rootCostCenterNode, parentNodeId: rootCostCenterNode.id }); // ancestor walk: self-loop detected
+
+    const result = await run(
+      db,
+      {
+        hierarchyId: baseCostCenterHierarchy.id,
+        name: "Child",
+        parentNodeId: rootCostCenterNode.id,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, SelfReferenceError);
+  });
+
+  it("returns error when node would create a circular reference", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    // Setup: node-a -> node-b -> node-a (circular chain)
+    const nodeA = { ...rootCostCenterNode, id: "node-a", parentNodeId: "node-b" };
+    const nodeB = { ...childCostCenterNode, id: "node-b", parentNodeId: "node-a" };
+
+    spies.select
+      .mockReturnValueOnce(baseCostCenterHierarchy) // hierarchy exists
+      .mockReturnValueOnce(nodeA) // parent node (A) found
+      .mockReturnValueOnce(nodeA) // ancestor walk iteration 1: fetch A, parentNodeId = "node-b"
+      .mockReturnValueOnce(nodeB); // ancestor walk iteration 2: fetch B, parentNodeId = "node-a" (already visited) → circular
+
+    const result = await run(
+      db,
+      {
+        hierarchyId: baseCostCenterHierarchy.id,
+        name: "New Child",
+        parentNodeId: "node-a",
+      },
+      commandCtx,
+    );
+
+    expectErr(result, CircularReferenceError);
+  });
+
+  it("emits audit event by calling insert", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCostCenterHierarchy).mockReturnValueOnce(undefined); // no root
+    spies.insert.mockReturnValueOnce(rootCostCenterNode);
+
+    const result = await run(
+      db,
+      { hierarchyId: baseCostCenterHierarchy.id, name: "Root" },
+      commandCtx,
+    );
+
+    expectOk(result);
+    expect(spies.insert).toHaveBeenCalled();
+  });
+});

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();
+  });
+});