@tailor-platform/erp-kit 0.6.0 → 0.7.0

package/src/modules/finance-ledger/command/approveAndLockPeriod.ts

@@ -0,0 +1,72 @@
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  PeriodCloseNotFoundError,
+  InvalidStatusTransitionError,
+  InsufficientPermissionsError,
+} from "../lib/errors.generated";
+
+export interface ApproveAndLockPeriodInput {
+  id: string;
+}
+
+/**
+ * Function: approveAndLockPeriod
+ *
+ * Transitions a PeriodClose record from UNDER_REVIEW to SOFT_LOCKED status.
+ * Prevents accounting team from posting new journal entries while allowing
+ * advisor/auditor roles to post final adjustments. Records the approver's userId.
+ */
+export async function run(db: Transaction, input: ApproveAndLockPeriodInput, ctx: CommandContext) {
+  const { id } = input;
+
+  // 1. Find PeriodClose record
+  const periodClose = await db
+    .selectFrom("PeriodClose")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!periodClose) {
+    return err(new PeriodCloseNotFoundError(id));
+  }
+
+  // 2. Validate status is UNDER_REVIEW
+  if (periodClose.status !== "UNDER_REVIEW") {
+    return err(new InvalidStatusTransitionError(id));
+  }
+
+  // 3. Check permissions
+  if (
+    !ctx.permissions.includes("finance-ledger:approveAndLockPeriod") &&
+    !ctx.permissions.includes("finance-ledger:*")
+  ) {
+    return err(new InsufficientPermissionsError(id));
+  }
+
+  // 4. Transition to SOFT_LOCKED and record approver
+  const updated = await db
+    .updateTable("PeriodClose")
+    .set({
+      status: "SOFT_LOCKED",
+      completionPercentage: 87,
+      approvedByUserId: ctx.actorId,
+      updatedAt: new Date(),
+    })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  // 5. Emit audit event recording status transition
+  const auditTrail = [
+    {
+      type: "STATUS_TRANSITION",
+      from: "UNDER_REVIEW",
+      to: "SOFT_LOCKED",
+      actorId: ctx.actorId,
+    },
+  ];
+
+  return ok({ periodClose: updated, auditTrail });
+}

package/src/modules/finance-ledger/command/beginClose.generated.ts

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

package/src/modules/finance-ledger/command/beginClose.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { PeriodCloseNotFoundError, InvalidStatusTransitionError } from "../lib/errors.generated";
+import {
+  basePeriodClose,
+  inProgressPeriodClose,
+  subledgersVerifiedPeriodClose,
+  permanentlyClosedPeriodClose,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./beginClose";
+
+describe("beginClose", () => {
+  it("returns error when PeriodClose record does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "nonexistent" }, commandCtx);
+
+    expectErr(result, PeriodCloseNotFoundError);
+  });
+
+  it("returns error when PeriodClose is already IN_PROGRESS", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(inProgressPeriodClose);
+
+    const result = await run(db, { id: inProgressPeriodClose.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("returns error when PeriodClose is in SUBLEDGERS_VERIFIED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(subledgersVerifiedPeriodClose);
+
+    const result = await run(db, { id: subledgersVerifiedPeriodClose.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("returns error when PeriodClose is in PERMANENTLY_CLOSED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(permanentlyClosedPeriodClose);
+
+    const result = await run(db, { id: permanentlyClosedPeriodClose.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("transitions NOT_STARTED PeriodClose to IN_PROGRESS", async () => {
+    const updatedPeriodClose = {
+      ...basePeriodClose,
+      status: "IN_PROGRESS",
+      completionPercentage: 12,
+    };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(basePeriodClose);
+    spies.update.mockReturnValueOnce(updatedPeriodClose);
+
+    const result = await run(db, { id: basePeriodClose.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.periodClose.status).toBe("IN_PROGRESS");
+  });
+
+  it("records the acting user who began the close", async () => {
+    const updatedPeriodClose = {
+      ...basePeriodClose,
+      status: "IN_PROGRESS",
+      completionPercentage: 12,
+    };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(basePeriodClose);
+    spies.update.mockReturnValueOnce(updatedPeriodClose);
+
+    const result = await run(db, { id: basePeriodClose.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.auditTrail).toBeDefined();
+    expect(value.auditTrail[0].actorId).toBe(commandCtx.actorId);
+  });
+
+  it("emits audit event recording status transition from NOT_STARTED to IN_PROGRESS and acting user", async () => {
+    const updatedPeriodClose = {
+      ...basePeriodClose,
+      status: "IN_PROGRESS",
+      completionPercentage: 12,
+    };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(basePeriodClose);
+    spies.update.mockReturnValueOnce(updatedPeriodClose);
+
+    const result = await run(db, { id: basePeriodClose.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.auditTrail).toContainEqual(
+      expect.objectContaining({
+        type: "STATUS_TRANSITION",
+        from: "NOT_STARTED",
+        to: "IN_PROGRESS",
+        actorId: commandCtx.actorId,
+      }),
+    );
+  });
+});

package/src/modules/finance-ledger/command/beginClose.ts

@@ -0,0 +1,58 @@
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { PeriodCloseNotFoundError, InvalidStatusTransitionError } from "../lib/errors.generated";
+
+export interface BeginCloseInput {
+  id: string;
+}
+
+/**
+ * Function: beginClose
+ *
+ * Transitions a PeriodClose record from NOT_STARTED to IN_PROGRESS status,
+ * indicating that the close checklist execution has begun.
+ */
+export async function run(db: Transaction, input: BeginCloseInput, ctx: CommandContext) {
+  const { id } = input;
+
+  // 1. Find PeriodClose record
+  const periodClose = await db
+    .selectFrom("PeriodClose")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!periodClose) {
+    return err(new PeriodCloseNotFoundError(id));
+  }
+
+  // 2. Validate status is NOT_STARTED
+  if (periodClose.status !== "NOT_STARTED") {
+    return err(new InvalidStatusTransitionError(id));
+  }
+
+  // 3. Transition to IN_PROGRESS and record acting user
+  const updated = await db
+    .updateTable("PeriodClose")
+    .set({
+      status: "IN_PROGRESS",
+      completionPercentage: 12,
+      updatedAt: new Date(),
+    })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  // 4. Emit audit event recording status transition
+  const auditTrail = [
+    {
+      type: "STATUS_TRANSITION",
+      from: "NOT_STARTED",
+      to: "IN_PROGRESS",
+      actorId: ctx.actorId,
+    },
+  ];
+
+  return ok({ periodClose: updated, auditTrail });
+}

package/src/modules/finance-ledger/command/closePeriod.generated.ts

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

package/src/modules/finance-ledger/command/closePeriod.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountingPeriodNotFoundError,
+  InvalidStatusTransitionError,
+} from "../lib/errors.generated";
+import {
+  neverOpenedPeriod,
+  futureEnterablePeriod,
+  baseAccountingPeriod,
+  closedPeriod,
+  permanentlyClosedPeriod,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./closePeriod";
+
+describe("closePeriod", () => {
+  it("returns error when accounting period does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "non-existent" }, commandCtx);
+
+    expectErr(result, AccountingPeriodNotFoundError);
+  });
+
+  it("returns error when period is in NEVER_OPENED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(neverOpenedPeriod);
+
+    const result = await run(db, { id: neverOpenedPeriod.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("returns error when period is in FUTURE_ENTERABLE status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(futureEnterablePeriod);
+
+    const result = await run(db, { id: futureEnterablePeriod.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("returns error when period is in CLOSED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(closedPeriod);
+
+    const result = await run(db, { id: closedPeriod.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("returns error when period is in PERMANENTLY_CLOSED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(permanentlyClosedPeriod);
+
+    const result = await run(db, { id: permanentlyClosedPeriod.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("transitions OPEN period to CLOSED", async () => {
+    const updatedPeriod = { ...baseAccountingPeriod, status: "CLOSED" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseAccountingPeriod);
+    spies.update.mockReturnValueOnce(updatedPeriod);
+
+    const result = await run(db, { id: baseAccountingPeriod.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.accountingPeriod.status).toBe("CLOSED");
+  });
+
+  it("emits audit event recording status transition from OPEN to CLOSED and acting user", async () => {
+    const updatedPeriod = { ...baseAccountingPeriod, status: "CLOSED" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseAccountingPeriod);
+    spies.update.mockReturnValueOnce(updatedPeriod);
+
+    const result = await run(db, { id: baseAccountingPeriod.id }, commandCtx);
+
+    expectOk(result);
+    expect(spies.update).toHaveBeenCalled();
+  });
+});

package/src/modules/finance-ledger/command/closePeriod.ts

@@ -0,0 +1,44 @@
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountingPeriodNotFoundError,
+  InvalidStatusTransitionError,
+} from "../lib/errors.generated";
+
+export interface ClosePeriodInput {
+  id: string;
+}
+
+const from = ["OPEN"];
+
+export async function run(db: Transaction, input: ClosePeriodInput, ctx: CommandContext) {
+  const period = await db
+    .selectFrom("AccountingPeriod")
+    .selectAll()
+    .where("id", "=", input.id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!period) {
+    return err(new AccountingPeriodNotFoundError(input.id));
+  }
+
+  if (!from.includes(period.status as string)) {
+    return err(new InvalidStatusTransitionError(input.id));
+  }
+
+  const updated = await db
+    .updateTable("AccountingPeriod")
+    .set({
+      status: "CLOSED",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", input.id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  // Emit audit event recording status transition from OPEN to CLOSED and acting user
+  void ctx;
+
+  return ok({ accountingPeriod: updated });
+}

package/src/modules/finance-ledger/command/createAccountingPeriod.generated.ts

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