@tailor-platform/erp-kit 0.7.0 → 0.8.0

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

@@ -0,0 +1,38 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import { InternalOrderNotFoundError, InvalidStateError } from "../lib/errors.generated";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface CloseInternalOrderInput {
+  internalOrderId: string;
+  from?: string[];
+}
+
+export async function run(db: Transaction, input: CloseInternalOrderInput, ctx: CommandContext) {
+  void ctx;
+
+  const validFromStatuses = input.from ?? ["TECHNICALLY_COMPLETED"];
+
+  const order = await db
+    .selectFrom("InternalOrder")
+    .selectAll()
+    .where("id", "=", input.internalOrderId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!order) {
+    return err(new InternalOrderNotFoundError(input.internalOrderId));
+  }
+
+  if (!validFromStatuses.includes(order.status)) {
+    return err(new InvalidStateError(input.internalOrderId));
+  }
+
+  const updated = await db
+    .updateTable("InternalOrder")
+    .set({ status: "CLOSED", updatedAt: new Date() })
+    .where("id", "=", input.internalOrderId)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ internalOrder: updated! });
+}

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

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

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

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CommitmentNotFoundError,
+  InvalidConsumptionAmountError,
+  ConsumptionExceedsCommitmentError,
+} from "../lib/errors.generated";
+import { baseCommitment, partiallyConsumedCommitment } from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./consumeCommitment";
+
+const validInput = {
+  costElementId: baseCommitment.costElementId,
+  costObjectType: baseCommitment.costObjectType,
+  costObjectId: baseCommitment.costObjectId,
+  accountingPeriodId: baseCommitment.accountingPeriodId,
+  consumptionAmount: 2000,
+};
+
+describe("consumeCommitment", () => {
+  it("consumes a portion of an existing commitment", async () => {
+    const updatedCommitment = { ...baseCommitment, consumedAmount: 2000 };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCommitment);
+    spies.update.mockReturnValueOnce(updatedCommitment);
+
+    const result = await run(db, validInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.commitment.consumedAmount).toBe(2000);
+  });
+
+  it("reduces commitment amount by the consumption amount", async () => {
+    const updatedCommitment = { ...baseCommitment, consumedAmount: 2000 };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCommitment);
+    spies.update.mockReturnValueOnce(updatedCommitment);
+
+    const result = await run(db, validInput, commandCtx);
+
+    const value = expectOk(result);
+    // remaining = amount - consumedAmount = 5000 - 2000 = 3000
+    expect(value.commitment.amount - value.commitment.consumedAmount).toBe(3000);
+  });
+
+  it("increases actual amount by the consumption amount", async () => {
+    const updatedCommitment = { ...baseCommitment, consumedAmount: 2000 };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCommitment);
+    spies.update.mockReturnValueOnce(updatedCommitment);
+
+    const result = await run(db, validInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.commitment.consumedAmount).toBe(2000);
+  });
+
+  it("budget availability remains unchanged for the consumed portion", async () => {
+    const updatedCommitment = { ...baseCommitment, consumedAmount: 2000 };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCommitment);
+    spies.update.mockReturnValueOnce(updatedCommitment);
+
+    const result = await run(db, validInput, commandCtx);
+
+    const value = expectOk(result);
+    // The total obligation (consumedAmount) stays at same level of impact on budget
+    expect(value.commitment.amount).toBe(baseCommitment.amount);
+  });
+
+  it("returns error when commitment does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { ...validInput, costElementId: "missing-element" }, commandCtx);
+
+    expectErr(result, CommitmentNotFoundError);
+  });
+
+  it("returns error when consumption amount is zero or negative", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCommitment);
+
+    const result = await run(db, { ...validInput, consumptionAmount: 0 }, commandCtx);
+
+    expectErr(result, InvalidConsumptionAmountError);
+  });
+
+  it("returns error when consumption amount exceeds remaining commitment", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(partiallyConsumedCommitment); // remaining = 5000 - 2000 = 3000
+
+    const result = await run(db, { ...validInput, consumptionAmount: 4000 }, commandCtx);
+
+    expectErr(result, ConsumptionExceedsCommitmentError);
+  });
+
+  it("fully consumes a commitment when consumption equals remaining amount", async () => {
+    const consumed = { ...baseCommitment, consumedAmount: 5000, status: "CONSUMED" as const };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCommitment); // remaining = 5000
+    spies.update.mockReturnValueOnce(consumed);
+
+    const result = await run(db, { ...validInput, consumptionAmount: 5000 }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.commitment.status).toBe("CONSUMED");
+    expect(value.commitment.consumedAmount).toBe(5000);
+  });
+
+  it("emits audit event recording the consumption and acting user", async () => {
+    const updatedCommitment = { ...baseCommitment, consumedAmount: 2000 };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCommitment);
+    spies.update.mockReturnValueOnce(updatedCommitment);
+
+    const result = await run(db, validInput, commandCtx);
+
+    expectOk(result);
+    expect(spies.update).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,62 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CommitmentNotFoundError,
+  InvalidConsumptionAmountError,
+  ConsumptionExceedsCommitmentError,
+} from "../lib/errors.generated";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface ConsumeCommitmentInput {
+  costElementId: string;
+  costObjectType: string;
+  costObjectId: string;
+  accountingPeriodId: string;
+  consumptionAmount: number;
+}
+
+export async function run(db: Transaction, input: ConsumeCommitmentInput, ctx: CommandContext) {
+  void ctx;
+
+  // Find commitment by cost element + cost object + period
+  const commitment = await db
+    .selectFrom("Commitment")
+    .where("costElementId", "=", input.costElementId)
+    .where("costObjectType", "=", input.costObjectType)
+    .where("costObjectId", "=", input.costObjectId)
+    .where("accountingPeriodId", "=", input.accountingPeriodId)
+    .selectAll()
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!commitment) {
+    return err(new CommitmentNotFoundError(input.costElementId));
+  }
+
+  // Validate positive consumption amount
+  if (input.consumptionAmount <= 0) {
+    return err(new InvalidConsumptionAmountError(String(input.consumptionAmount)));
+  }
+
+  // Validate consumption does not exceed remaining
+  const remaining = commitment.amount - commitment.consumedAmount;
+  if (input.consumptionAmount > remaining) {
+    return err(new ConsumptionExceedsCommitmentError(String(input.consumptionAmount)));
+  }
+
+  // Update consumedAmount; if fully consumed, set status to CONSUMED
+  const newConsumedAmount = commitment.consumedAmount + input.consumptionAmount;
+  const newStatus = newConsumedAmount >= commitment.amount ? "CONSUMED" : commitment.status;
+
+  const updated = await db
+    .updateTable("Commitment")
+    .set({
+      consumedAmount: newConsumedAmount,
+      status: newStatus,
+      updatedAt: new Date(),
+    })
+    .where("id", "=", commitment.id)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ commitment: updated! });
+}

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

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

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