@tailor-platform/erp-kit 0.5.1 → 0.7.0

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

@@ -0,0 +1,186 @@
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  FinancialStatementNotFoundError,
+  StatementAlreadyFinalizedError,
+  TrialBalanceNotFoundError,
+  TrialBalanceImbalancedError,
+  ComparativeTrialBalanceNotFoundError,
+} from "../lib/errors.generated";
+
+export interface RegenerateFinancialStatementInput {
+  id: string;
+}
+
+function getSectionType(classification: string, statementType: string): string {
+  if (statementType === "BALANCE_SHEET") {
+    if (classification === "ASSET") return "Assets";
+    if (classification === "LIABILITY") return "Liabilities";
+    return "Equity";
+  }
+  if (statementType === "PROFIT_AND_LOSS") {
+    if (classification === "REVENUE") return "Revenue";
+    return "Expenses";
+  }
+  // CASH_FLOW
+  if (classification === "REVENUE" || classification === "EXPENSE") return "Operating Activities";
+  if (classification === "ASSET") return "Investing Activities";
+  return "Financing Activities";
+}
+
+/**
+ * Function: regenerateFinancialStatement
+ *
+ * Replaces content of an existing DRAFT financial statement with fresh
+ * trial balance data. Only DRAFT statements can be regenerated —
+ * FINALIZED statements are immutable. Refetches trial balance data,
+ * replaces all line items, updates timestamps, and refreshes
+ * comparative data.
+ */
+export async function run(
+  db: Transaction,
+  input: RegenerateFinancialStatementInput,
+  ctx: CommandContext,
+) {
+  const { id } = input;
+  const auditTrail: { type: string; actorId?: string; timestamp?: Date }[] = [];
+
+  // 1. Find FinancialStatement by id with forUpdate()
+  const financialStatement = await db
+    .selectFrom("FinancialStatement")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!financialStatement) {
+    return err(new FinancialStatementNotFoundError(id));
+  }
+
+  // 2. Validate status is DRAFT
+  if (financialStatement.status !== "DRAFT") {
+    return err(new StatementAlreadyFinalizedError(id));
+  }
+
+  // 3. Find the trial balance using statement.trialBalanceId
+  const trialBalance = await db
+    .selectFrom("TrialBalance")
+    .selectAll()
+    .where("id", "=", financialStatement.trialBalanceId)
+    .executeTakeFirst();
+
+  if (!trialBalance) {
+    return err(new TrialBalanceNotFoundError(financialStatement.trialBalanceId));
+  }
+
+  // 4. Validate trial balance is balanced
+  if (!trialBalance.isBalanced || trialBalance.totalDebits !== trialBalance.totalCredits) {
+    const discrepancy = Math.abs(trialBalance.totalDebits - trialBalance.totalCredits);
+    return err(new TrialBalanceImbalancedError(`${trialBalance.id} (discrepancy: ${discrepancy})`));
+  }
+
+  // 5. If comparativePeriodTrialBalanceId is set, validate it exists
+  let comparativeLines: Record<string, unknown>[] = [];
+  if (financialStatement.comparativePeriodTrialBalanceId) {
+    const comparativeTrialBalance = await db
+      .selectFrom("TrialBalance")
+      .selectAll()
+      .where("id", "=", financialStatement.comparativePeriodTrialBalanceId)
+      .executeTakeFirst();
+
+    if (!comparativeTrialBalance) {
+      return err(
+        new ComparativeTrialBalanceNotFoundError(
+          financialStatement.comparativePeriodTrialBalanceId,
+        ),
+      );
+    }
+
+    comparativeLines = (await db
+      .selectFrom("TrialBalanceLine" as never)
+      .where(
+        "trialBalanceId" as never,
+        "=",
+        financialStatement.comparativePeriodTrialBalanceId as never,
+      )
+      .selectAll()
+      .execute()) as Record<string, unknown>[];
+  }
+
+  // Build comparative amount map
+  const comparativeMap = new Map<string, number>();
+  for (const line of comparativeLines) {
+    comparativeMap.set(line.accountId as string, line.closingBalance as number);
+  }
+
+  // 6. Delete existing line items for this statement
+  await db
+    .deleteFrom("FinancialStatementLineItem")
+    .where("financialStatementId", "=", id)
+    .execute();
+
+  // 7. Fetch trial balance lines and rebuild line items
+  const trialBalanceLines = (await db
+    .selectFrom("TrialBalanceLine")
+    .selectAll()
+    .where("trialBalanceId", "=", trialBalance.id)
+    .orderBy("sortOrder", "asc")
+    .execute()) as Record<string, unknown>[];
+
+  const now = new Date();
+  let sortOrder = 0;
+
+  // 8. Insert new line items
+  for (const tbLine of trialBalanceLines) {
+    // Look up the account to get classification for section type
+    const account = await db
+      .selectFrom("Account" as never)
+      .where("id" as never, "=", tbLine.accountId as never)
+      .selectAll()
+      .executeTakeFirst();
+
+    if (!account) continue;
+    const acct = account as Record<string, unknown>;
+
+    sortOrder++;
+    await db
+      .insertInto("FinancialStatementLineItem")
+      .values({
+        financialStatementId: id,
+        accountId: tbLine.accountId as string,
+        accountGroupId: (tbLine.accountGroupId as string | null) ?? null,
+        label: tbLine.accountName as string,
+        amount: tbLine.closingBalance as number,
+        comparativeAmount: comparativeMap.get(tbLine.accountId as string) ?? null,
+        lineType: "DETAIL" as never,
+        sectionType: getSectionType(
+          acct.classification as string,
+          financialStatement.statementType,
+        ),
+        sortOrder,
+        createdAt: now,
+      })
+      .returningAll()
+      .executeTakeFirstOrThrow();
+  }
+
+  // 9. Update generatedAt timestamp on the statement
+  const updatedStatement = await db
+    .updateTable("FinancialStatement")
+    .set({
+      generatedAt: now,
+      updatedAt: now,
+    })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirst();
+
+  // 10. Record audit event
+  auditTrail.push({
+    type: "STATEMENT_REGENERATED",
+    actorId: ctx.actorId,
+    timestamp: now,
+  });
+
+  return ok({ financialStatement: updatedStatement!, auditTrail });
+}

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

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

@@ -0,0 +1,65 @@
+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 { JournalLineNotFoundError, InvalidStatusForLineRemoveError } from "../lib/errors.generated";
+import {
+  baseJournalEntry,
+  postedJournalEntry,
+  reversedJournalEntry,
+  baseJournalLine,
+} from "../testing/fixtures";
+import { run } from "./removeJournalLine";
+
+describe("removeJournalLine", () => {
+  it("returns error when journal line does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "missing-line" }, commandCtx);
+
+    expectErr(result, JournalLineNotFoundError);
+  });
+
+  it("returns error when parent journal entry is in POSTED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const postedLine = { ...baseJournalLine, journalEntryId: postedJournalEntry.id };
+    spies.select.mockReturnValueOnce(postedLine).mockReturnValueOnce(postedJournalEntry);
+
+    const result = await run(db, { id: postedLine.id }, commandCtx);
+
+    expectErr(result, InvalidStatusForLineRemoveError);
+  });
+
+  it("returns error when parent journal entry is in REVERSED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const reversedLine = { ...baseJournalLine, journalEntryId: reversedJournalEntry.id };
+    spies.select.mockReturnValueOnce(reversedLine).mockReturnValueOnce(reversedJournalEntry);
+
+    const result = await run(db, { id: reversedLine.id }, commandCtx);
+
+    expectErr(result, InvalidStatusForLineRemoveError);
+  });
+
+  it("removes journal line from DRAFT entry", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseJournalLine).mockReturnValueOnce(baseJournalEntry);
+    spies.delete.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: baseJournalLine.id }, commandCtx);
+
+    expectOk(result);
+    expect(spies.delete).toHaveBeenCalled();
+  });
+
+  it("emits audit event recording line removal and acting user", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseJournalLine).mockReturnValueOnce(baseJournalEntry);
+    spies.delete.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: baseJournalLine.id }, commandCtx);
+
+    expectOk(result);
+    expect(spies.delete).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,39 @@
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { JournalLineNotFoundError, InvalidStatusForLineRemoveError } from "../lib/errors.generated";
+
+export interface RemoveJournalLineInput {
+  id: string;
+}
+
+export async function run(db: Transaction, input: RemoveJournalLineInput, ctx: CommandContext) {
+  // 1. Fetch journal line
+  const existing = await db
+    .selectFrom("JournalLine")
+    .selectAll()
+    .where("id", "=", input.id)
+    .executeTakeFirst();
+
+  if (!existing) {
+    return err(new JournalLineNotFoundError(input.id));
+  }
+
+  // 2. Validate parent entry is DRAFT
+  const entry = await db
+    .selectFrom("JournalEntry")
+    .selectAll()
+    .where("id", "=", existing.journalEntryId)
+    .executeTakeFirst();
+
+  if (entry?.status !== "DRAFT") {
+    return err(new InvalidStatusForLineRemoveError(input.id));
+  }
+
+  // 3. Delete journal line
+  await db.deleteFrom("JournalLine").where("id", "=", input.id).executeTakeFirstOrThrow();
+
+  // Emit audit event recording the line removal, acting user, and timestamp
+  void ctx;
+
+  return ok({ removed: true });
+}

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

package/src/modules/finance-ledger/command/reopenPeriod.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 "./reopenPeriod";
+
+describe("reopenPeriod", () => {
+  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 OPEN status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseAccountingPeriod);
+
+    const result = await run(db, { id: baseAccountingPeriod.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 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 CLOSED period back to OPEN", async () => {
+    const updatedPeriod = { ...closedPeriod, status: "OPEN" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(closedPeriod);
+    spies.update.mockReturnValueOnce(updatedPeriod);
+
+    const result = await run(db, { id: closedPeriod.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.accountingPeriod.status).toBe("OPEN");
+  });
+
+  it("emits audit event recording status transition from CLOSED to OPEN and acting user", async () => {
+    const updatedPeriod = { ...closedPeriod, status: "OPEN" };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(closedPeriod);
+    spies.update.mockReturnValueOnce(updatedPeriod);
+
+    const result = await run(db, { id: closedPeriod.id }, commandCtx);
+
+    expectOk(result);
+    expect(spies.update).toHaveBeenCalled();
+  });
+});

package/src/modules/finance-ledger/command/reopenPeriod.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 ReopenPeriodInput {
+  id: string;
+}
+
+const from = ["CLOSED"];
+
+export async function run(db: Transaction, input: ReopenPeriodInput, 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: "OPEN",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", input.id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  // Emit audit event recording status transition from CLOSED to OPEN and acting user
+  void ctx;
+
+  return ok({ accountingPeriod: updated });
+}

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