@tailor-platform/erp-kit 0.6.0 → 0.7.0

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

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountingPeriodNotFoundError,
+  HasAssociatedJournalEntriesError,
+  HasActivePeriodCloseError,
+} from "../lib/errors.generated";
+import { baseAccountingPeriod, baseJournalEntry, basePeriodClose } from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./deleteAccountingPeriod";
+
+describe("deleteAccountingPeriod", () => {
+  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 accounting period has associated journal entries", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseAccountingPeriod).mockReturnValueOnce(baseJournalEntry);
+
+    const result = await run(db, { id: baseAccountingPeriod.id }, commandCtx);
+
+    expectErr(result, HasAssociatedJournalEntriesError);
+  });
+
+  it("returns error when accounting period has an active period close record", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseAccountingPeriod)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(basePeriodClose);
+
+    const result = await run(db, { id: baseAccountingPeriod.id }, commandCtx);
+
+    expectErr(result, HasActivePeriodCloseError);
+  });
+
+  it("deletes accounting period with no associated journal entries or period close", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseAccountingPeriod)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(undefined);
+    spies.delete.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: baseAccountingPeriod.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.deleted).toBe(true);
+  });
+
+  it("emits audit event recording acting user, timestamp, and deleted period details", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseAccountingPeriod)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(undefined);
+    spies.delete.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: baseAccountingPeriod.id }, commandCtx);
+
+    expectOk(result);
+    expect(spies.delete).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,55 @@
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountingPeriodNotFoundError,
+  HasAssociatedJournalEntriesError,
+  HasActivePeriodCloseError,
+} from "../lib/errors.generated";
+
+export interface DeleteAccountingPeriodInput {
+  id: string;
+}
+
+export async function run(
+  db: Transaction,
+  input: DeleteAccountingPeriodInput,
+  ctx: CommandContext,
+) {
+  const period = await db
+    .selectFrom("AccountingPeriod")
+    .selectAll()
+    .where("id", "=", input.id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!period) {
+    return err(new AccountingPeriodNotFoundError(input.id));
+  }
+
+  const journalEntry = await db
+    .selectFrom("JournalEntry")
+    .selectAll()
+    .where("accountingPeriodId", "=", input.id)
+    .executeTakeFirst();
+
+  if (journalEntry) {
+    return err(new HasAssociatedJournalEntriesError(input.id));
+  }
+
+  const periodClose = await db
+    .selectFrom("PeriodClose")
+    .selectAll()
+    .where("accountingPeriodId", "=", input.id)
+    .executeTakeFirst();
+
+  if (periodClose) {
+    return err(new HasActivePeriodCloseError(input.id));
+  }
+
+  await db.deleteFrom("AccountingPeriod").where("id", "=", input.id).executeTakeFirst();
+
+  // Emit audit event recording acting user, timestamp, and deleted period details
+  void ctx;
+
+  return ok({ deleted: true });
+}

package/src/modules/finance-ledger/command/deleteFiscalYear.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 "./deleteFiscalYear";
+
+export const deleteFiscalYear = defineCommand(permissions.deleteFiscalYear, run);

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

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { FiscalYearNotFoundError, HasAssociatedPeriodsError } from "../lib/errors.generated";
+import { baseFiscalYear, baseAccountingPeriod } from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./deleteFiscalYear";
+
+describe("deleteFiscalYear", () => {
+  it("returns error when fiscal year does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "non-existent" }, commandCtx);
+
+    expectErr(result, FiscalYearNotFoundError);
+  });
+
+  it("returns error when fiscal year has associated accounting periods", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseFiscalYear).mockReturnValueOnce(baseAccountingPeriod);
+
+    const result = await run(db, { id: baseFiscalYear.id }, commandCtx);
+
+    expectErr(result, HasAssociatedPeriodsError);
+  });
+
+  it("deletes fiscal year with no associated accounting periods", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseFiscalYear).mockReturnValueOnce(undefined);
+    spies.delete.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: baseFiscalYear.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.deleted).toBe(true);
+  });
+});

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

@@ -0,0 +1,34 @@
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { FiscalYearNotFoundError, HasAssociatedPeriodsError } from "../lib/errors.generated";
+
+export interface DeleteFiscalYearInput {
+  id: string;
+}
+
+export async function run(db: Transaction, input: DeleteFiscalYearInput, _ctx: CommandContext) {
+  const fiscalYear = await db
+    .selectFrom("FiscalYear")
+    .selectAll()
+    .where("id", "=", input.id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!fiscalYear) {
+    return err(new FiscalYearNotFoundError(input.id));
+  }
+
+  const period = await db
+    .selectFrom("AccountingPeriod")
+    .selectAll()
+    .where("fiscalYearId", "=", input.id)
+    .executeTakeFirst();
+
+  if (period) {
+    return err(new HasAssociatedPeriodsError(input.id));
+  }
+
+  await db.deleteFrom("FiscalYear").where("id", "=", input.id).executeTakeFirst();
+
+  return ok({ deleted: true });
+}

package/src/modules/finance-ledger/command/deleteJournalEntry.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 "./deleteJournalEntry";
+
+export const deleteJournalEntry = defineCommand(permissions.deleteJournalEntry, run);

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

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { JournalEntryNotFoundError, InvalidStatusForDeleteError } from "../lib/errors.generated";
+import { baseJournalEntry, postedJournalEntry, reversedJournalEntry } from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./deleteJournalEntry";
+
+describe("deleteJournalEntry", () => {
+  it("returns error when journal entry does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { journalEntryId: "missing-entry" }, commandCtx);
+
+    expectErr(result, JournalEntryNotFoundError);
+  });
+
+  it("returns error when journal entry is in POSTED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(postedJournalEntry);
+
+    const result = await run(db, { journalEntryId: postedJournalEntry.id }, commandCtx);
+
+    expectErr(result, InvalidStatusForDeleteError);
+  });
+
+  it("returns error when journal entry is in REVERSED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(reversedJournalEntry);
+
+    const result = await run(db, { journalEntryId: reversedJournalEntry.id }, commandCtx);
+
+    expectErr(result, InvalidStatusForDeleteError);
+  });
+
+  it("deletes DRAFT journal entry and all associated journal lines", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseJournalEntry);
+
+    const result = await run(db, { journalEntryId: baseJournalEntry.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.journalEntryId).toBe(baseJournalEntry.id);
+    // Verify journal lines were deleted first, then the entry
+    expect(spies.delete).toHaveBeenCalledTimes(2);
+  });
+
+  it("emits audit event recording the deletion and acting user", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseJournalEntry);
+
+    const result = await run(db, { journalEntryId: baseJournalEntry.id }, commandCtx);
+
+    expectOk(result);
+    expect(spies.delete).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,43 @@
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { JournalEntryNotFoundError, InvalidStatusForDeleteError } from "../lib/errors.generated";
+
+export interface DeleteJournalEntryInput {
+  journalEntryId: string;
+}
+
+/**
+ * Function: deleteJournalEntry
+ *
+ * Removes a journal entry and all its associated journal lines from the system.
+ * Only DRAFT entries can be deleted. Posted entries must be reversed rather than
+ * deleted to preserve the audit trail.
+ */
+export async function run(db: Transaction, input: DeleteJournalEntryInput, _ctx: CommandContext) {
+  const { journalEntryId } = input;
+
+  // 1. Find journal entry with forUpdate
+  const existing = await db
+    .selectFrom("JournalEntry")
+    .selectAll()
+    .where("id", "=", journalEntryId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!existing) {
+    return err(new JournalEntryNotFoundError(journalEntryId));
+  }
+
+  // 2. Must be DRAFT
+  if (existing.status !== "DRAFT") {
+    return err(new InvalidStatusForDeleteError(journalEntryId));
+  }
+
+  // 3. Delete all associated journal lines first
+  await db.deleteFrom("JournalLine").where("journalEntryId", "=", journalEntryId).execute();
+
+  // 4. Delete the journal entry
+  await db.deleteFrom("JournalEntry").where("id", "=", journalEntryId).execute();
+
+  return ok({ journalEntryId });
+}

package/src/modules/finance-ledger/command/executeYearEndClose.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 "./executeYearEndClose";
+
+export const executeYearEndClose = defineCommand(permissions.executeYearEndClose, run);

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

@@ -0,0 +1,239 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountingPeriodNotFoundError,
+  NotFinalPeriodError,
+  StandardCloseNotCompleteError,
+  DuplicateYearEndCloseError,
+  RetainedEarningsAccountNotFoundError,
+  NewFiscalYearNotDefinedError,
+} from "../lib/errors.generated";
+import {
+  baseAccountingPeriod,
+  lastPeriodOfYear,
+  baseFiscalYear,
+  baseFiscalYear2,
+  softLockedPeriodClose,
+  baseCompany,
+  baseChartOfAccounts,
+  retainedEarningsAccount,
+  revenueAccount,
+  expenseAccount,
+  baseAccount,
+  baseAccount2,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./executeYearEndClose";
+
+describe("executeYearEndClose", () => {
+  it("returns error when accounting period does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined); // period lookup
+
+    const result = await run(db, { accountingPeriodId: "non-existent" }, commandCtx);
+
+    expectErr(result, AccountingPeriodNotFoundError);
+  });
+
+  it("returns error when period is not the final period of its fiscal year", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseAccountingPeriod) // period lookup (Jan, not final)
+      .mockReturnValueOnce(baseFiscalYear); // fiscal year lookup
+
+    const result = await run(db, { accountingPeriodId: baseAccountingPeriod.id }, commandCtx);
+
+    expectErr(result, NotFinalPeriodError);
+  });
+
+  it("returns error when standard close checklist is not complete", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(lastPeriodOfYear) // period lookup (Dec, final)
+      .mockReturnValueOnce(baseFiscalYear) // fiscal year lookup
+      .mockReturnValueOnce(undefined); // no PeriodClose record
+
+    const result = await run(db, { accountingPeriodId: lastPeriodOfYear.id }, commandCtx);
+
+    expectErr(result, StandardCloseNotCompleteError);
+  });
+
+  it("returns error when year-end close has already been executed", async () => {
+    const alreadyClosedFiscalYear = {
+      ...baseFiscalYear,
+      yearEndCloseExecuted: true,
+    };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(lastPeriodOfYear) // period lookup
+      .mockReturnValueOnce(alreadyClosedFiscalYear) // fiscal year lookup
+      .mockReturnValueOnce(softLockedPeriodClose); // period close lookup
+
+    const result = await run(db, { accountingPeriodId: lastPeriodOfYear.id }, commandCtx);
+
+    expectErr(result, DuplicateYearEndCloseError);
+  });
+
+  it("returns error when no retained earnings account exists", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(lastPeriodOfYear) // period lookup
+      .mockReturnValueOnce(baseFiscalYear) // fiscal year lookup
+      .mockReturnValueOnce(softLockedPeriodClose) // period close lookup
+      .mockReturnValueOnce(baseChartOfAccounts) // chart of accounts lookup
+      .mockReturnValueOnce(undefined); // no retained earnings account
+
+    const result = await run(db, { accountingPeriodId: lastPeriodOfYear.id }, commandCtx);
+
+    expectErr(result, RetainedEarningsAccountNotFoundError);
+  });
+
+  it("returns error when no new fiscal year is defined", async () => {
+    const revenueJournalLine = {
+      id: "jl-revenue",
+      journalEntryId: "je-1",
+      accountId: revenueAccount.id,
+      classification: "REVENUE",
+      debitAmount: null,
+      creditAmount: 5000,
+      functionalDebitAmount: null,
+      functionalCreditAmount: 5000,
+    };
+    const expenseJournalLine = {
+      id: "jl-expense",
+      journalEntryId: "je-1",
+      accountId: expenseAccount.id,
+      classification: "EXPENSE",
+      debitAmount: 3000,
+      creditAmount: null,
+      functionalDebitAmount: 3000,
+      functionalCreditAmount: null,
+    };
+
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(lastPeriodOfYear) // period lookup
+      .mockReturnValueOnce(baseFiscalYear) // fiscal year lookup
+      .mockReturnValueOnce(softLockedPeriodClose) // period close lookup
+      .mockReturnValueOnce(baseChartOfAccounts) // chart of accounts lookup
+      .mockReturnValueOnce(retainedEarningsAccount) // retained earnings account
+      .mockImplementationOnce(() => [{ id: lastPeriodOfYear.id }]) // allPeriods lookup
+      .mockImplementationOnce(() => [revenueJournalLine, expenseJournalLine]); // journal lines with join
+    spies.insert.mockReturnValueOnce({ id: "closing-entry-1" }); // closing entry insert
+    spies.insert.mockImplementationOnce(() => []); // closing lines insert
+    spies.select.mockReturnValueOnce(undefined); // no next fiscal year
+
+    const result = await run(db, { accountingPeriodId: lastPeriodOfYear.id }, commandCtx);
+
+    expectErr(result, NewFiscalYearNotDefinedError);
+  });
+
+  it("successfully executes year-end close", async () => {
+    const revenueJournalLine = {
+      id: "jl-revenue",
+      journalEntryId: "je-1",
+      accountId: revenueAccount.id,
+      classification: "REVENUE",
+      debitAmount: null,
+      creditAmount: 5000,
+      functionalDebitAmount: null,
+      functionalCreditAmount: 5000,
+    };
+    const expenseJournalLine = {
+      id: "jl-expense",
+      journalEntryId: "je-1",
+      accountId: expenseAccount.id,
+      classification: "EXPENSE",
+      debitAmount: 3000,
+      creditAmount: null,
+      functionalDebitAmount: 3000,
+      functionalCreditAmount: null,
+    };
+    const assetJournalLine = {
+      id: "jl-asset",
+      journalEntryId: "je-1",
+      accountId: baseAccount.id,
+      classification: "ASSET",
+      debitAmount: 10000,
+      creditAmount: null,
+      functionalDebitAmount: 10000,
+      functionalCreditAmount: null,
+    };
+    const liabilityJournalLine = {
+      id: "jl-liability",
+      journalEntryId: "je-1",
+      accountId: baseAccount2.id,
+      classification: "LIABILITY",
+      debitAmount: null,
+      creditAmount: 8000,
+      functionalDebitAmount: null,
+      functionalCreditAmount: 8000,
+    };
+
+    const closingEntry = {
+      id: "closing-entry-1",
+      companyId: baseCompany.id,
+      journalType: "CLOSING",
+      status: "POSTED",
+    };
+    const openingEntry = {
+      id: "opening-entry-1",
+      companyId: baseCompany.id,
+      journalType: "OPENING",
+      status: "POSTED",
+    };
+    const newFirstPeriod = {
+      id: "new-period-1",
+      fiscalYearId: baseFiscalYear2.id,
+      startDate: new Date("2025-01-01"),
+    };
+
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(lastPeriodOfYear) // period lookup
+      .mockReturnValueOnce(baseFiscalYear) // fiscal year lookup
+      .mockReturnValueOnce(softLockedPeriodClose) // period close lookup
+      .mockReturnValueOnce(baseChartOfAccounts) // chart of accounts lookup
+      .mockReturnValueOnce(retainedEarningsAccount) // retained earnings account
+      .mockImplementationOnce(() => [{ id: lastPeriodOfYear.id }]) // allPeriods lookup
+      .mockImplementationOnce(() => [
+        revenueJournalLine,
+        expenseJournalLine,
+        assetJournalLine,
+        liabilityJournalLine,
+      ]); // journal lines with join
+
+    // After closing entry creation
+    spies.insert.mockReturnValueOnce(closingEntry); // closing entry insert
+    spies.insert.mockImplementationOnce(() => []); // closing lines insert
+
+    // Next fiscal year lookup
+    spies.select.mockReturnValueOnce(baseFiscalYear2);
+    // New first period lookup
+    spies.select.mockReturnValueOnce(newFirstPeriod);
+
+    // Opening entry creation
+    spies.insert.mockReturnValueOnce(openingEntry); // opening entry insert
+    spies.insert.mockImplementationOnce(() => []); // opening lines insert
+
+    // Fiscal year update and period close update
+    spies.update.mockReturnValueOnce({ ...baseFiscalYear, yearEndCloseExecuted: true });
+    spies.update.mockReturnValueOnce({ ...softLockedPeriodClose, yearEndCloseExecuted: true });
+
+    const result = await run(db, { accountingPeriodId: lastPeriodOfYear.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.closingEntry).toBeDefined();
+    expect(value.closingEntry.journalType).toBe("CLOSING");
+    expect(value.closingEntry.status).toBe("POSTED");
+    expect(value.openingEntry).toBeDefined();
+    expect(value.openingEntry.journalType).toBe("OPENING");
+    expect(value.openingEntry.status).toBe("POSTED");
+    expect(value.auditTrail).toBeDefined();
+    expect(value.auditTrail.length).toBeGreaterThan(0);
+    expect(value.auditTrail[0].type).toBe("YEAR_END_CLOSE");
+    expect(value.auditTrail[0].netIncome).toBe(2000); // 5000 revenue - 3000 expense
+    expect(spies.update).toHaveBeenCalled();
+  });
+});