@tailor-platform/erp-kit 0.7.0 → 0.9.0

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

@@ -0,0 +1,166 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CompanyNotFoundError,
+  InvalidAllocationTypeError,
+  AccountingPeriodNotFoundError,
+  InvalidNameError,
+} from "../lib/errors.generated";
+import { baseCompany, baseAccountingPeriod, baseAllocationCycle } from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./createAllocationCycle";
+
+describe("createAllocationCycle", () => {
+  it("creates allocation cycle in DRAFT status with required fields", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany).mockReturnValueOnce(baseAccountingPeriod);
+    spies.insert.mockReturnValueOnce(baseAllocationCycle);
+
+    const result = await run(
+      db,
+      {
+        companyId: baseCompany.id,
+        name: "Q1 2024 Overhead",
+        allocationType: "ASSESSMENT",
+        accountingPeriodId: baseAccountingPeriod.id,
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.allocationCycle).toEqual(baseAllocationCycle);
+  });
+
+  it("returns error when company does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      {
+        companyId: "missing-company",
+        name: "Q1 2024 Overhead",
+        allocationType: "ASSESSMENT",
+        accountingPeriodId: baseAccountingPeriod.id,
+      },
+      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,
+      {
+        companyId: baseCompany.id,
+        name: "Q1 2024 Overhead",
+        allocationType: "ASSESSMENT",
+        accountingPeriodId: baseAccountingPeriod.id,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, CompanyNotFoundError);
+  });
+
+  it("returns error when allocation type is invalid", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany);
+
+    const result = await run(
+      db,
+      {
+        companyId: baseCompany.id,
+        name: "Q1 2024 Overhead",
+        allocationType: "INVALID_TYPE",
+        accountingPeriodId: baseAccountingPeriod.id,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidAllocationTypeError);
+  });
+
+  it("returns error when accounting period does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany).mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      {
+        companyId: baseCompany.id,
+        name: "Q1 2024 Overhead",
+        allocationType: "ASSESSMENT",
+        accountingPeriodId: "missing-period",
+      },
+      commandCtx,
+    );
+
+    expectErr(result, AccountingPeriodNotFoundError);
+  });
+
+  it("returns error when name is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany).mockReturnValueOnce(baseAccountingPeriod);
+
+    const result = await run(
+      db,
+      {
+        companyId: baseCompany.id,
+        name: "",
+        allocationType: "ASSESSMENT",
+        accountingPeriodId: baseAccountingPeriod.id,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidNameError);
+  });
+
+  it("allocation cycles from different companies are isolated", async () => {
+    const companyB = { id: "company-2", status: "ACTIVE" };
+    const cycleB = { ...baseAllocationCycle, id: "cycle-b", companyId: companyB.id };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(companyB).mockReturnValueOnce(baseAccountingPeriod);
+    spies.insert.mockReturnValueOnce(cycleB);
+
+    const result = await run(
+      db,
+      {
+        companyId: companyB.id,
+        name: "Q1 2024 Overhead",
+        allocationType: "ASSESSMENT",
+        accountingPeriodId: baseAccountingPeriod.id,
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.allocationCycle.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(baseAccountingPeriod);
+    spies.insert.mockReturnValueOnce(baseAllocationCycle);
+
+    const result = await run(
+      db,
+      {
+        companyId: baseCompany.id,
+        name: "Q1 2024 Overhead",
+        allocationType: "ASSESSMENT",
+        accountingPeriodId: baseAccountingPeriod.id,
+      },
+      commandCtx,
+    );
+
+    expectOk(result);
+    expect(spies.insert).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,68 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CompanyNotFoundError,
+  InvalidAllocationTypeError,
+  AccountingPeriodNotFoundError,
+  InvalidNameError,
+} from "../lib/errors.generated";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface CreateAllocationCycleInput {
+  companyId: string;
+  name: string;
+  allocationType: string;
+  accountingPeriodId: string;
+}
+
+export async function run(db: Transaction, input: CreateAllocationCycleInput, 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 allocation type
+  if (input.allocationType !== "ASSESSMENT" && input.allocationType !== "DISTRIBUTION") {
+    return err(new InvalidAllocationTypeError(input.allocationType));
+  }
+
+  // Validate accounting period exists
+  const accountingPeriod = await db
+    .selectFrom("AccountingPeriod" as never)
+    .where("id" as never, "=", input.accountingPeriodId as never)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (!accountingPeriod) {
+    return err(new AccountingPeriodNotFoundError(input.accountingPeriodId));
+  }
+
+  // Validate name is non-empty
+  if (!input.name || input.name.trim() === "") {
+    return err(new InvalidNameError(input.companyId));
+  }
+
+  // Create allocation cycle in DRAFT status
+  const allocationCycle = await db
+    .insertInto("AllocationCycle")
+    .values({
+      companyId: input.companyId,
+      name: input.name,
+      allocationType: input.allocationType,
+      accountingPeriodId: input.accountingPeriodId,
+      status: "DRAFT",
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ allocationCycle: allocationCycle! });
+}

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

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

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

@@ -0,0 +1,195 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AllocationCycleNotFoundError,
+  InvalidStateError,
+  SenderNotFoundError,
+  ReceiverNotFoundError,
+  SenderIsReceiverError,
+  InvalidPercentageError,
+} from "../lib/errors.generated";
+import {
+  baseAllocationCycle,
+  validatedAllocationCycle,
+  baseCostCenter,
+  baseCostCenter2,
+  baseAllocationRule,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./createAllocationRule";
+
+describe("createAllocationRule", () => {
+  it("adds an allocation rule to a DRAFT allocation cycle", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseAllocationCycle) // cycle lookup
+      .mockReturnValueOnce(baseCostCenter) // sender lookup
+      .mockReturnValueOnce(baseCostCenter2); // receiver lookup
+    spies.insert.mockReturnValueOnce(baseAllocationRule);
+
+    const result = await run(
+      db,
+      {
+        allocationCycleId: baseAllocationCycle.id,
+        senderCostCenterId: baseCostCenter.id,
+        receiverType: "CostCenter",
+        receiverId: baseCostCenter2.id,
+        percentage: 100,
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.allocationRule).toEqual(baseAllocationRule);
+  });
+
+  it("returns error when allocation cycle does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      {
+        allocationCycleId: "missing-id",
+        senderCostCenterId: baseCostCenter.id,
+        receiverType: "CostCenter",
+        receiverId: baseCostCenter2.id,
+        percentage: 100,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, AllocationCycleNotFoundError);
+  });
+
+  it("returns error when allocation cycle is not in DRAFT status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(validatedAllocationCycle);
+
+    const result = await run(
+      db,
+      {
+        allocationCycleId: validatedAllocationCycle.id,
+        senderCostCenterId: baseCostCenter.id,
+        receiverType: "CostCenter",
+        receiverId: baseCostCenter2.id,
+        percentage: 100,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidStateError);
+  });
+
+  it("returns error when sender cost center does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseAllocationCycle) // cycle
+      .mockReturnValueOnce(undefined); // sender
+
+    const result = await run(
+      db,
+      {
+        allocationCycleId: baseAllocationCycle.id,
+        senderCostCenterId: "missing-sender",
+        receiverType: "CostCenter",
+        receiverId: baseCostCenter2.id,
+        percentage: 100,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, SenderNotFoundError);
+  });
+
+  it("returns error when a receiver cost object does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseAllocationCycle) // cycle
+      .mockReturnValueOnce(baseCostCenter) // sender
+      .mockReturnValueOnce(undefined); // receiver
+
+    const result = await run(
+      db,
+      {
+        allocationCycleId: baseAllocationCycle.id,
+        senderCostCenterId: baseCostCenter.id,
+        receiverType: "CostCenter",
+        receiverId: "missing-receiver",
+        percentage: 100,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, ReceiverNotFoundError);
+  });
+
+  it("returns error when sender appears as a receiver", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseAllocationCycle) // cycle
+      .mockReturnValueOnce(baseCostCenter) // sender
+      .mockReturnValueOnce(baseCostCenter); // receiver (same as sender)
+
+    const result = await run(
+      db,
+      {
+        allocationCycleId: baseAllocationCycle.id,
+        senderCostCenterId: baseCostCenter.id,
+        receiverType: "CostCenter",
+        receiverId: baseCostCenter.id,
+        percentage: 100,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, SenderIsReceiverError);
+  });
+
+  it("returns error when percentage value is zero or negative", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseAllocationCycle) // cycle
+      .mockReturnValueOnce(baseCostCenter) // sender
+      .mockReturnValueOnce(baseCostCenter2); // receiver
+
+    const result = await run(
+      db,
+      {
+        allocationCycleId: baseAllocationCycle.id,
+        senderCostCenterId: baseCostCenter.id,
+        receiverType: "CostCenter",
+        receiverId: baseCostCenter2.id,
+        percentage: 0,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidPercentageError);
+  });
+
+  it("emits audit event recording the rule creation and acting user", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseAllocationCycle)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce(baseCostCenter2);
+    spies.insert.mockReturnValueOnce(baseAllocationRule);
+
+    const result = await run(
+      db,
+      {
+        allocationCycleId: baseAllocationCycle.id,
+        senderCostCenterId: baseCostCenter.id,
+        receiverType: "CostCenter",
+        receiverId: baseCostCenter2.id,
+        percentage: 100,
+      },
+      commandCtx,
+    );
+
+    expectOk(result);
+    expect(spies.insert).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,103 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AllocationCycleNotFoundError,
+  InvalidStateError,
+  SenderNotFoundError,
+  ReceiverNotFoundError,
+  SenderIsReceiverError,
+  InvalidPercentageError,
+} from "../lib/errors.generated";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface CreateAllocationRuleInput {
+  allocationCycleId: string;
+  senderCostCenterId: string;
+  receiverType: string;
+  receiverId: string;
+  percentage: number;
+}
+
+export async function run(db: Transaction, input: CreateAllocationRuleInput, ctx: CommandContext) {
+  void ctx;
+
+  // Validate allocation cycle exists
+  const cycle = await db
+    .selectFrom("AllocationCycle")
+    .where("id", "=", input.allocationCycleId)
+    .selectAll()
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!cycle) {
+    return err(new AllocationCycleNotFoundError(input.allocationCycleId));
+  }
+
+  // Validate status is DRAFT
+  if (cycle.status !== "DRAFT") {
+    return err(new InvalidStateError(input.allocationCycleId));
+  }
+
+  // Validate sender cost center exists
+  const sender = await db
+    .selectFrom("CostCenter")
+    .where("id", "=", input.senderCostCenterId)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (!sender) {
+    return err(new SenderNotFoundError(input.senderCostCenterId));
+  }
+
+  // Validate receiver exists (polymorphic lookup)
+  let receiver: unknown;
+  if (input.receiverType === "CostCenter") {
+    receiver = await db
+      .selectFrom("CostCenter")
+      .where("id", "=", input.receiverId)
+      .selectAll()
+      .executeTakeFirst();
+  } else if (input.receiverType === "ProfitCenter") {
+    receiver = await db
+      .selectFrom("ProfitCenter")
+      .where("id", "=", input.receiverId)
+      .selectAll()
+      .executeTakeFirst();
+  } else if (input.receiverType === "InternalOrder") {
+    receiver = await db
+      .selectFrom("InternalOrder")
+      .where("id", "=", input.receiverId)
+      .selectAll()
+      .executeTakeFirst();
+  }
+
+  if (!receiver) {
+    return err(new ReceiverNotFoundError(input.receiverId));
+  }
+
+  // Validate sender is not receiver
+  if (input.receiverType === "CostCenter" && input.senderCostCenterId === input.receiverId) {
+    return err(new SenderIsReceiverError(input.senderCostCenterId));
+  }
+
+  // Validate percentage is positive
+  if (input.percentage <= 0) {
+    return err(new InvalidPercentageError(input.allocationCycleId));
+  }
+
+  // Create allocation rule
+  const allocationRule = await db
+    .insertInto("AllocationRule")
+    .values({
+      allocationCycleId: input.allocationCycleId,
+      senderCostCenterId: input.senderCostCenterId,
+      receiverType: input.receiverType,
+      receiverId: input.receiverId,
+      percentage: input.percentage,
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ allocationRule: allocationRule! });
+}

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

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

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

@@ -0,0 +1,159 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CompanyNotFoundError,
+  FiscalYearNotFoundError,
+  CostObjectNotFoundError,
+  PlanVersionNotFoundError,
+  InvalidNameError,
+  BudgetHolderRequiredError,
+} from "../lib/errors.generated";
+import {
+  baseCompany,
+  baseFiscalYear,
+  baseCostCenter,
+  basePlanVersion,
+  baseBudget,
+  baseUser,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./createBudget";
+
+const validInput = {
+  companyId: baseCompany.id,
+  name: "IT Budget 2024",
+  description: "Information Technology budget for FY2024",
+  budgetHolderId: baseUser.id,
+  fiscalYearId: baseFiscalYear.id,
+  costObjectType: "CostCenter" as const,
+  costObjectId: baseCostCenter.id,
+  planVersionId: basePlanVersion.id,
+};
+
+describe("createBudget", () => {
+  it("creates budget in DRAFT status with required fields", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(baseFiscalYear)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce(basePlanVersion);
+    spies.insert.mockReturnValueOnce(baseBudget);
+
+    const result = await run(db, validInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.budget).toEqual(baseBudget);
+  });
+
+  it("returns error when company does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { ...validInput, 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, validInput, commandCtx);
+
+    expectErr(result, CompanyNotFoundError);
+  });
+
+  it("returns error when fiscal year does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany).mockReturnValueOnce(undefined);
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectErr(result, FiscalYearNotFoundError);
+  });
+
+  it("returns error when cost object does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(baseFiscalYear)
+      .mockReturnValueOnce(undefined);
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectErr(result, CostObjectNotFoundError);
+  });
+
+  it("returns error when plan version does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(baseFiscalYear)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce(undefined);
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectErr(result, PlanVersionNotFoundError);
+  });
+
+  it("returns error when name is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(baseFiscalYear)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce(basePlanVersion);
+
+    const result = await run(db, { ...validInput, name: "" }, commandCtx);
+
+    expectErr(result, InvalidNameError);
+  });
+
+  it("returns error when budget holder is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(baseFiscalYear)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce(basePlanVersion);
+
+    const result = await run(db, { ...validInput, budgetHolderId: null }, commandCtx);
+
+    expectErr(result, BudgetHolderRequiredError);
+  });
+
+  it("budgets from different companies are isolated", async () => {
+    const companyB = { id: "company-2", status: "ACTIVE" };
+    const budgetCompanyB = { ...baseBudget, id: "budget-company-b", companyId: companyB.id };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(companyB)
+      .mockReturnValueOnce(baseFiscalYear)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce(basePlanVersion);
+    spies.insert.mockReturnValueOnce(budgetCompanyB);
+
+    const result = await run(db, { ...validInput, companyId: companyB.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.budget.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(baseFiscalYear)
+      .mockReturnValueOnce(baseCostCenter)
+      .mockReturnValueOnce(basePlanVersion);
+    spies.insert.mockReturnValueOnce(baseBudget);
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectOk(result);
+    expect(spies.insert).toHaveBeenCalled();
+  });
+});