@tailor-platform/erp-kit 0.6.0 → 0.7.0

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

@@ -0,0 +1,197 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CompanyNotFoundError,
+  NameRequiredError,
+  InvalidDateRangeError,
+  OverlappingFiscalYearError,
+} from "../lib/errors.generated";
+import { baseCompany, baseFiscalYear } from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./createFiscalYear";
+
+describe("createFiscalYear", () => {
+  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: "FY 2024",
+        startDate: new Date("2024-01-01"),
+        endDate: new Date("2024-12-31"),
+      },
+      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: "FY 2024",
+        startDate: new Date("2024-01-01"),
+        endDate: new Date("2024-12-31"),
+      },
+      commandCtx,
+    );
+
+    expectErr(result, CompanyNotFoundError);
+  });
+
+  it("returns error when name is empty", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany);
+
+    const result = await run(
+      db,
+      {
+        companyId: baseCompany.id,
+        name: "",
+        startDate: new Date("2024-01-01"),
+        endDate: new Date("2024-12-31"),
+      },
+      commandCtx,
+    );
+
+    expectErr(result, NameRequiredError);
+  });
+
+  it("returns error when start date is not before end date", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany);
+
+    const result = await run(
+      db,
+      {
+        companyId: baseCompany.id,
+        name: "FY 2024",
+        startDate: new Date("2024-12-31"),
+        endDate: new Date("2024-01-01"),
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidDateRangeError);
+  });
+
+  it("returns error when fiscal year overlaps with an existing fiscal year for the same company", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany).mockReturnValueOnce(baseFiscalYear);
+
+    const result = await run(
+      db,
+      {
+        companyId: baseCompany.id,
+        name: "FY 2024 Overlap",
+        startDate: new Date("2024-06-01"),
+        endDate: new Date("2025-05-31"),
+      },
+      commandCtx,
+    );
+
+    expectErr(result, OverlappingFiscalYearError);
+  });
+
+  it("creates fiscal year with valid name, start date, and end date", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany).mockReturnValueOnce(undefined);
+    spies.insert.mockReturnValueOnce(baseFiscalYear);
+
+    const result = await run(
+      db,
+      {
+        companyId: baseCompany.id,
+        name: "FY 2024",
+        startDate: new Date("2024-01-01"),
+        endDate: new Date("2024-12-31"),
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.fiscalYear).toEqual(baseFiscalYear);
+  });
+
+  it("creates non-calendar fiscal year (e.g., April-to-March) with correct date boundaries", async () => {
+    const nonCalendarFiscalYear = {
+      ...baseFiscalYear,
+      id: "fiscal-year-non-calendar",
+      name: "FY 2024-2025",
+      startDate: new Date("2024-04-01"),
+      endDate: new Date("2025-03-31"),
+    };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany).mockReturnValueOnce(undefined);
+    spies.insert.mockReturnValueOnce(nonCalendarFiscalYear);
+
+    const result = await run(
+      db,
+      {
+        companyId: baseCompany.id,
+        name: "FY 2024-2025",
+        startDate: new Date("2024-04-01"),
+        endDate: new Date("2025-03-31"),
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.fiscalYear).toEqual(nonCalendarFiscalYear);
+  });
+
+  it("fiscal years from different companies are isolated", async () => {
+    const companyB = { id: "company-2", status: "ACTIVE" };
+    const fiscalYearCompanyB = {
+      ...baseFiscalYear,
+      id: "fiscal-year-company-b",
+      companyId: companyB.id,
+    };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(companyB).mockReturnValueOnce(undefined);
+    spies.insert.mockReturnValueOnce(fiscalYearCompanyB);
+
+    const result = await run(
+      db,
+      {
+        companyId: companyB.id,
+        name: "FY 2024",
+        startDate: new Date("2024-01-01"),
+        endDate: new Date("2024-12-31"),
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.fiscalYear.companyId).toBe(companyB.id);
+  });
+
+  it("emits audit event recording acting user, timestamp, company reference, and fiscal year details", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany).mockReturnValueOnce(undefined);
+    spies.insert.mockReturnValueOnce(baseFiscalYear);
+
+    const result = await run(
+      db,
+      {
+        companyId: baseCompany.id,
+        name: "FY 2024",
+        startDate: new Date("2024-01-01"),
+        endDate: new Date("2024-12-31"),
+      },
+      commandCtx,
+    );
+
+    expectOk(result);
+    expect(spies.insert).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,70 @@
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CompanyNotFoundError,
+  NameRequiredError,
+  InvalidDateRangeError,
+  OverlappingFiscalYearError,
+} from "../lib/errors.generated";
+
+export interface CreateFiscalYearInput {
+  companyId: string;
+  name: string;
+  startDate: Date;
+  endDate: Date;
+}
+
+export async function run(db: Transaction, input: CreateFiscalYearInput, 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 NameRequiredError(input.companyId));
+  }
+
+  // Validate start date is strictly before end date
+  if (input.startDate >= input.endDate) {
+    return err(new InvalidDateRangeError(input.companyId));
+  }
+
+  // Check for overlapping fiscal years for the same company
+  const overlapping = await db
+    .selectFrom("FiscalYear" as never)
+    .where("companyId" as never, "=", input.companyId as never)
+    .where("startDate" as never, "<", input.endDate as never)
+    .where("endDate" as never, ">", input.startDate as never)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (overlapping) {
+    return err(new OverlappingFiscalYearError(input.companyId));
+  }
+
+  // Create the fiscal year record
+  const fiscalYear = await db
+    .insertInto("FiscalYear")
+    .values({
+      companyId: input.companyId,
+      name: input.name,
+      startDate: input.startDate,
+      endDate: input.endDate,
+      yearEndCloseExecuted: false,
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ fiscalYear: fiscalYear! });
+}

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

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

@@ -0,0 +1,261 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CompanyNotFoundError,
+  AccountingPeriodNotFoundError,
+  InvalidJournalTypeError,
+  DuplicateReferenceNumberError,
+  InvalidEntryDateError,
+} from "../lib/errors.generated";
+import { baseCompany, baseAccountingPeriod, baseJournalEntry } from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./createJournalEntry";
+
+describe("createJournalEntry", () => {
+  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",
+        accountingPeriodId: baseAccountingPeriod.id,
+        journalType: "MISCELLANEOUS",
+        referenceNumber: "JE-001",
+        entryDate: new Date("2024-01-15"),
+      },
+      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,
+        accountingPeriodId: baseAccountingPeriod.id,
+        journalType: "MISCELLANEOUS",
+        referenceNumber: "JE-001",
+        entryDate: new Date("2024-01-15"),
+      },
+      commandCtx,
+    );
+
+    expectErr(result, CompanyNotFoundError);
+  });
+
+  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,
+        accountingPeriodId: "missing-period",
+        journalType: "MISCELLANEOUS",
+        referenceNumber: "JE-001",
+        entryDate: new Date("2024-01-15"),
+      },
+      commandCtx,
+    );
+
+    expectErr(result, AccountingPeriodNotFoundError);
+  });
+
+  it("returns error when journal type is invalid", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany).mockReturnValueOnce(baseAccountingPeriod);
+
+    const result = await run(
+      db,
+      {
+        companyId: baseCompany.id,
+        accountingPeriodId: baseAccountingPeriod.id,
+        journalType: "INVALID_TYPE",
+        referenceNumber: "JE-001",
+        entryDate: new Date("2024-01-15"),
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidJournalTypeError);
+  });
+
+  it("returns error when reference number already exists within the company", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(baseAccountingPeriod)
+      .mockReturnValueOnce(baseJournalEntry); // existing entry with same ref
+
+    const result = await run(
+      db,
+      {
+        companyId: baseCompany.id,
+        accountingPeriodId: baseAccountingPeriod.id,
+        journalType: "MISCELLANEOUS",
+        referenceNumber: baseJournalEntry.referenceNumber,
+        entryDate: new Date("2024-01-15"),
+      },
+      commandCtx,
+    );
+
+    expectErr(result, DuplicateReferenceNumberError);
+  });
+
+  it("returns error when entry date is invalid", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(baseAccountingPeriod)
+      .mockReturnValueOnce(undefined); // no duplicate ref
+
+    const result = await run(
+      db,
+      {
+        companyId: baseCompany.id,
+        accountingPeriodId: baseAccountingPeriod.id,
+        journalType: "MISCELLANEOUS",
+        referenceNumber: "JE-NEW",
+        entryDate: new Date("invalid-date"),
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidEntryDateError);
+  });
+
+  it("creates journal entry in DRAFT status with required fields", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(baseAccountingPeriod)
+      .mockReturnValueOnce(undefined); // no duplicate ref
+    spies.insert.mockReturnValueOnce(baseJournalEntry);
+
+    const result = await run(
+      db,
+      {
+        companyId: baseCompany.id,
+        accountingPeriodId: baseAccountingPeriod.id,
+        journalType: "MISCELLANEOUS",
+        referenceNumber: "JE-001",
+        entryDate: new Date("2024-01-15"),
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.journalEntry.status).toBe("DRAFT");
+  });
+
+  it("creates journal entry with optional description", async () => {
+    const entryWithDesc = { ...baseJournalEntry, description: "Monthly closing" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(baseAccountingPeriod)
+      .mockReturnValueOnce(undefined);
+    spies.insert.mockReturnValueOnce(entryWithDesc);
+
+    const result = await run(
+      db,
+      {
+        companyId: baseCompany.id,
+        accountingPeriodId: baseAccountingPeriod.id,
+        journalType: "MISCELLANEOUS",
+        referenceNumber: "JE-001",
+        entryDate: new Date("2024-01-15"),
+        description: "Monthly closing",
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.journalEntry.description).toBe("Monthly closing");
+  });
+
+  it("creates journal entry with optional source document reference", async () => {
+    const entryWithSrc = { ...baseJournalEntry, sourceDocumentReference: "INV-001" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseCompany)
+      .mockReturnValueOnce(baseAccountingPeriod)
+      .mockReturnValueOnce(undefined);
+    spies.insert.mockReturnValueOnce(entryWithSrc);
+
+    const result = await run(
+      db,
+      {
+        companyId: baseCompany.id,
+        accountingPeriodId: baseAccountingPeriod.id,
+        journalType: "MISCELLANEOUS",
+        referenceNumber: "JE-001",
+        entryDate: new Date("2024-01-15"),
+        sourceDocumentReference: "INV-001",
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.journalEntry.sourceDocumentReference).toBe("INV-001");
+  });
+
+  it("journal entries from different companies are isolated", async () => {
+    const companyB = { id: "company-2", status: "ACTIVE" };
+    const entryCompanyB = { ...baseJournalEntry, id: "je-company-b", companyId: companyB.id };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(companyB)
+      .mockReturnValueOnce(baseAccountingPeriod)
+      .mockReturnValueOnce(undefined);
+    spies.insert.mockReturnValueOnce(entryCompanyB);
+
+    const result = await run(
+      db,
+      {
+        companyId: companyB.id,
+        accountingPeriodId: baseAccountingPeriod.id,
+        journalType: "MISCELLANEOUS",
+        referenceNumber: "JE-001",
+        entryDate: new Date("2024-01-15"),
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.journalEntry.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)
+      .mockReturnValueOnce(undefined);
+    spies.insert.mockReturnValueOnce(baseJournalEntry);
+
+    const result = await run(
+      db,
+      {
+        companyId: baseCompany.id,
+        accountingPeriodId: baseAccountingPeriod.id,
+        journalType: "MISCELLANEOUS",
+        referenceNumber: "JE-001",
+        entryDate: new Date("2024-01-15"),
+      },
+      commandCtx,
+    );
+
+    expectOk(result);
+    expect(spies.insert).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,121 @@
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CompanyNotFoundError,
+  AccountingPeriodNotFoundError,
+  InvalidJournalTypeError,
+  DuplicateReferenceNumberError,
+  InvalidEntryDateError,
+} from "../lib/errors.generated";
+
+const VALID_JOURNAL_TYPES = new Set([
+  "SALES",
+  "PURCHASE",
+  "CASH",
+  "BANK",
+  "MISCELLANEOUS",
+  "OPENING",
+]);
+
+export interface CreateJournalEntryInput {
+  companyId: string;
+  accountingPeriodId: string;
+  journalType: string;
+  referenceNumber: string;
+  entryDate: Date;
+  description?: string;
+  sourceDocumentReference?: string;
+}
+
+/**
+ * Function: createJournalEntry
+ *
+ * Establishes a new journal entry in DRAFT status within the general ledger.
+ * Validates company, accounting period, journal type, reference number uniqueness,
+ * and entry date before creating.
+ */
+export async function run(db: Transaction, input: CreateJournalEntryInput, _ctx: CommandContext) {
+  const {
+    companyId,
+    accountingPeriodId,
+    journalType,
+    referenceNumber,
+    entryDate,
+    description,
+    sourceDocumentReference,
+  } = input;
+
+  // 1. Validate company exists and is ACTIVE
+  const company = await db
+    .selectFrom("Company")
+    .selectAll()
+    .where("id", "=", companyId)
+    .executeTakeFirst();
+
+  if (company?.status !== "ACTIVE") {
+    return err(new CompanyNotFoundError(companyId));
+  }
+
+  // 2. Validate accounting period exists
+  const period = await db
+    .selectFrom("AccountingPeriod")
+    .selectAll()
+    .where("id", "=", accountingPeriodId)
+    .executeTakeFirst();
+
+  if (!period) {
+    return err(new AccountingPeriodNotFoundError(accountingPeriodId));
+  }
+
+  // 3. Validate journal type
+  if (!VALID_JOURNAL_TYPES.has(journalType)) {
+    return err(new InvalidJournalTypeError(journalType));
+  }
+
+  // 4. Validate reference number uniqueness within company
+  const existingEntry = await db
+    .selectFrom("JournalEntry")
+    .selectAll()
+    .where("companyId", "=", companyId)
+    .where("referenceNumber", "=", referenceNumber)
+    .executeTakeFirst();
+
+  if (existingEntry) {
+    return err(new DuplicateReferenceNumberError(referenceNumber));
+  }
+
+  // 5. Validate entry date
+  if (!(entryDate instanceof Date) || isNaN(entryDate.getTime())) {
+    return err(new InvalidEntryDateError(String(entryDate)));
+  }
+
+  // 6. Create journal entry in DRAFT status
+  const journalEntry = await db
+    .insertInto("JournalEntry")
+    .values({
+      companyId,
+      accountingPeriodId,
+      journalType: journalType as
+        | "SALES"
+        | "PURCHASE"
+        | "CASH"
+        | "BANK"
+        | "MISCELLANEOUS"
+        | "OPENING"
+        | "CLOSING",
+      referenceNumber,
+      entryDate,
+      status: "DRAFT",
+      description: description ?? null,
+      sourceDocumentReference: sourceDocumentReference ?? null,
+      adjustingEntryType: null,
+      reversalOfId: null,
+      postedAt: null,
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ journalEntry: journalEntry! });
+}

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