@tailor-platform/erp-kit 0.6.0 → 0.7.0

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

@@ -0,0 +1,138 @@
+import { describe, it, expect } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import {
+  FiscalYearNotFoundError,
+  NameRequiredError,
+  DatesImmutableError,
+  InvalidDateRangeError,
+  OverlappingFiscalYearError,
+} from "../lib/errors.generated";
+import { baseFiscalYear, baseFiscalYear2, baseAccountingPeriod } from "../testing/fixtures";
+import { run } from "./updateFiscalYear";
+
+describe("updateFiscalYear", () => {
+  it("returns error when fiscal year does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    expectErr(
+      await run(db, { id: "missing-id", yearName: "FY Updated" }, commandCtx),
+      FiscalYearNotFoundError,
+    );
+  });
+
+  it("returns error when name is empty", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseFiscalYear);
+
+    expectErr(
+      await run(db, { id: baseFiscalYear.id, yearName: "" }, commandCtx),
+      NameRequiredError,
+    );
+  });
+
+  it("returns error when attempting to change dates after accounting periods exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseFiscalYear).mockReturnValueOnce(baseAccountingPeriod);
+
+    expectErr(
+      await run(db, { id: baseFiscalYear.id, startDate: new Date("2024-02-01") }, commandCtx),
+      DatesImmutableError,
+    );
+  });
+
+  it("returns error when updated start date is not before end date", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseFiscalYear).mockReturnValueOnce(undefined); // no accounting periods
+
+    expectErr(
+      await run(
+        db,
+        {
+          id: baseFiscalYear.id,
+          startDate: new Date("2025-01-01"),
+          endDate: new Date("2024-06-01"),
+        },
+        commandCtx,
+      ),
+      InvalidDateRangeError,
+    );
+  });
+
+  it("returns error when updated date range overlaps with another fiscal year", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseFiscalYear)
+      .mockReturnValueOnce(undefined) // no accounting periods
+      .mockReturnValueOnce(baseFiscalYear2); // overlapping fiscal year found
+
+    expectErr(
+      await run(
+        db,
+        {
+          id: baseFiscalYear.id,
+          startDate: new Date("2024-06-01"),
+          endDate: new Date("2025-06-01"),
+        },
+        commandCtx,
+      ),
+      OverlappingFiscalYearError,
+    );
+  });
+
+  it("updates fiscal year name successfully", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updated = { ...baseFiscalYear, name: "FY 2024 Renamed" };
+    spies.select.mockReturnValueOnce(baseFiscalYear);
+    spies.update.mockReturnValueOnce(updated);
+
+    const result = await run(
+      db,
+      { id: baseFiscalYear.id, yearName: "FY 2024 Renamed" },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.fiscalYear).toEqual(updated);
+  });
+
+  it("updates fiscal year dates when no accounting periods exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const newStart = new Date("2024-02-01");
+    const newEnd = new Date("2024-11-30");
+    const updated = { ...baseFiscalYear, startDate: newStart, endDate: newEnd };
+    spies.select
+      .mockReturnValueOnce(baseFiscalYear)
+      .mockReturnValueOnce(undefined) // no accounting periods
+      .mockReturnValueOnce(undefined); // no overlapping fiscal years
+    spies.update.mockReturnValueOnce(updated);
+
+    const result = await run(
+      db,
+      { id: baseFiscalYear.id, startDate: newStart, endDate: newEnd },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.fiscalYear).toEqual(updated);
+  });
+
+  it("emits audit event recording acting user, timestamp, and changed fields", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updated = { ...baseFiscalYear, name: "FY 2024 Audited" };
+    spies.select.mockReturnValueOnce(baseFiscalYear);
+    spies.update.mockReturnValueOnce(updated);
+
+    const result = await run(
+      db,
+      { id: baseFiscalYear.id, yearName: "FY 2024 Audited" },
+      commandCtx,
+    );
+
+    // Verify the command completes successfully (audit event emission is a side effect)
+    const value = expectOk(result);
+    expect(value.fiscalYear).toEqual(updated);
+  });
+});

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

@@ -0,0 +1,85 @@
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  FiscalYearNotFoundError,
+  NameRequiredError,
+  DatesImmutableError,
+  InvalidDateRangeError,
+  OverlappingFiscalYearError,
+} from "../lib/errors.generated";
+
+export interface UpdateFiscalYearInput {
+  id: string;
+  yearName?: string;
+  startDate?: Date;
+  endDate?: Date;
+}
+
+export async function run(db: Transaction, input: UpdateFiscalYearInput, ctx: CommandContext) {
+  const existing = await db
+    .selectFrom("FiscalYear")
+    .selectAll()
+    .where("id", "=", input.id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!existing) {
+    return err(new FiscalYearNotFoundError(input.id));
+  }
+
+  const yearName = input.yearName ?? existing.name;
+  if (!yearName || yearName.trim() === "") {
+    return err(new NameRequiredError(input.id));
+  }
+
+  const datesRequested = input.startDate !== undefined || input.endDate !== undefined;
+
+  if (datesRequested) {
+    const periodsExist = await db
+      .selectFrom("AccountingPeriod")
+      .selectAll()
+      .where("fiscalYearId", "=", input.id)
+      .executeTakeFirst();
+
+    if (periodsExist) {
+      return err(new DatesImmutableError(input.id));
+    }
+
+    const newStartDate = input.startDate ?? existing.startDate;
+    const newEndDate = input.endDate ?? existing.endDate;
+
+    if (newStartDate >= newEndDate) {
+      return err(new InvalidDateRangeError(input.id));
+    }
+
+    const overlapping = await db
+      .selectFrom("FiscalYear")
+      .selectAll()
+      .where("companyId", "=", existing.companyId)
+      .where("id", "!=", input.id)
+      .where("startDate", "<", newEndDate)
+      .where("endDate", ">", newStartDate)
+      .executeTakeFirst();
+
+    if (overlapping) {
+      return err(new OverlappingFiscalYearError(input.id));
+    }
+  }
+
+  const fiscalYear = await db
+    .updateTable("FiscalYear")
+    .set({
+      name: yearName,
+      ...(input.startDate !== undefined ? { startDate: input.startDate } : {}),
+      ...(input.endDate !== undefined ? { endDate: input.endDate } : {}),
+      updatedAt: new Date(),
+    })
+    .where("id", "=", input.id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  // Emit audit event recording the acting user, timestamp, and changed fields
+  void ctx;
+
+  return ok({ fiscalYear });
+}

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

package/src/modules/finance-ledger/command/updateJournalEntry.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 {
+  JournalEntryNotFoundError,
+  InvalidStatusForUpdateError,
+  DuplicateReferenceNumberError,
+  JournalTypeImmutableError,
+} from "../lib/errors.generated";
+import { baseJournalEntry, postedJournalEntry, reversedJournalEntry } from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./updateJournalEntry";
+
+describe("updateJournalEntry", () => {
+  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",
+        description: "Updated",
+      },
+      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,
+        description: "Updated",
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidStatusForUpdateError);
+  });
+
+  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,
+        description: "Updated",
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidStatusForUpdateError);
+  });
+
+  it("returns error when attempting to change journal type", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseJournalEntry);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        journalType: "SALES",
+      },
+      commandCtx,
+    );
+
+    expectErr(result, JournalTypeImmutableError);
+  });
+
+  it("updates description on a DRAFT journal entry", async () => {
+    const updatedEntry = { ...baseJournalEntry, description: "New description" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseJournalEntry);
+    spies.update.mockReturnValueOnce(updatedEntry);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        description: "New description",
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.journalEntry.description).toBe("New description");
+  });
+
+  it("updates source document reference on a DRAFT journal entry", async () => {
+    const updatedEntry = { ...baseJournalEntry, sourceDocumentReference: "INV-999" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseJournalEntry);
+    spies.update.mockReturnValueOnce(updatedEntry);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        sourceDocumentReference: "INV-999",
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.journalEntry.sourceDocumentReference).toBe("INV-999");
+  });
+
+  it("updates entry date on a DRAFT journal entry", async () => {
+    const newDate = new Date("2024-01-20");
+    const updatedEntry = { ...baseJournalEntry, entryDate: newDate };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseJournalEntry);
+    spies.update.mockReturnValueOnce(updatedEntry);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        entryDate: newDate,
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.journalEntry.entryDate).toEqual(newDate);
+  });
+
+  it("updates reference number on a DRAFT journal entry with uniqueness check", async () => {
+    const updatedEntry = { ...baseJournalEntry, referenceNumber: "JE-NEW" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseJournalEntry) // entry lookup
+      .mockReturnValueOnce(undefined); // no duplicate ref
+    spies.update.mockReturnValueOnce(updatedEntry);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        referenceNumber: "JE-NEW",
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.journalEntry.referenceNumber).toBe("JE-NEW");
+  });
+
+  it("returns error when updated reference number already exists", async () => {
+    const existingOther = { ...baseJournalEntry, id: "other-entry", referenceNumber: "JE-TAKEN" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseJournalEntry) // entry lookup
+      .mockReturnValueOnce(existingOther); // duplicate ref found
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        referenceNumber: "JE-TAKEN",
+      },
+      commandCtx,
+    );
+
+    expectErr(result, DuplicateReferenceNumberError);
+  });
+
+  it("emits audit event recording previous and new field values and acting user", async () => {
+    const updatedEntry = { ...baseJournalEntry, description: "Audited update" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseJournalEntry);
+    spies.update.mockReturnValueOnce(updatedEntry);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        description: "Audited update",
+      },
+      commandCtx,
+    );
+
+    expectOk(result);
+    expect(spies.update).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,86 @@
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  JournalEntryNotFoundError,
+  InvalidStatusForUpdateError,
+  DuplicateReferenceNumberError,
+  JournalTypeImmutableError,
+} from "../lib/errors.generated";
+
+export interface UpdateJournalEntryInput {
+  journalEntryId: string;
+  journalType?: string;
+  description?: string;
+  sourceDocumentReference?: string;
+  entryDate?: Date;
+  referenceNumber?: string;
+}
+
+/**
+ * Function: updateJournalEntry
+ *
+ * Modifies the header fields of an existing journal entry that is in DRAFT status.
+ * Posted and reversed entries are immutable and cannot be updated.
+ */
+export async function run(db: Transaction, input: UpdateJournalEntryInput, _ctx: CommandContext) {
+  const { journalEntryId, description, sourceDocumentReference, entryDate, referenceNumber } =
+    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 InvalidStatusForUpdateError(journalEntryId));
+  }
+
+  // 2b. Journal type cannot be changed after creation
+  if (input.journalType !== undefined && input.journalType !== existing.journalType) {
+    return err(new JournalTypeImmutableError(journalEntryId));
+  }
+
+  // 3. If referenceNumber is being updated, check uniqueness within company
+  if (referenceNumber !== undefined) {
+    const duplicate = await db
+      .selectFrom("JournalEntry")
+      .selectAll()
+      .where("companyId", "=", existing.companyId)
+      .where("referenceNumber", "=", referenceNumber)
+      .where("id", "!=", journalEntryId)
+      .executeTakeFirst();
+
+    if (duplicate) {
+      return err(new DuplicateReferenceNumberError(referenceNumber));
+    }
+  }
+
+  // 4. Build update object from provided fields
+  const updateData: Record<string, unknown> = {
+    updatedAt: new Date(),
+  };
+
+  if (description !== undefined) updateData.description = description;
+  if (sourceDocumentReference !== undefined)
+    updateData.sourceDocumentReference = sourceDocumentReference;
+  if (entryDate !== undefined) updateData.entryDate = entryDate;
+  if (referenceNumber !== undefined) updateData.referenceNumber = referenceNumber;
+
+  // 5. Update journal entry
+  const journalEntry = await db
+    .updateTable("JournalEntry")
+    .set(updateData)
+    .where("id", "=", journalEntryId)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ journalEntry: journalEntry! });
+}

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