@tailor-platform/erp-kit 0.6.0 → 0.8.0

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

@@ -0,0 +1,392 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  PeriodCloseNotFoundError,
+  InvalidStatusTransitionError,
+  InvalidAdjustingEntryTypeError,
+  UnbalancedAdjustingEntriesError,
+} from "../lib/errors.generated";
+import {
+  subledgersVerifiedPeriodClose,
+  inProgressPeriodClose,
+  adjustmentsPostedPeriodClose,
+  baseAccount,
+  baseAccount2,
+  baseAccountingPeriod,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run, type PostAdjustingEntriesInput } from "./postAdjustingEntries";
+
+const balancedAccrualInput: PostAdjustingEntriesInput = {
+  periodCloseId: subledgersVerifiedPeriodClose.id,
+  adjustingEntries: [
+    {
+      adjustingEntryType: "ACCRUAL",
+      description: "Accrued revenue",
+      lines: [
+        { accountId: baseAccount.id, debitAmount: 1000, creditAmount: null, description: "Debit" },
+        {
+          accountId: baseAccount2.id,
+          debitAmount: null,
+          creditAmount: 1000,
+          description: "Credit",
+        },
+      ],
+    },
+  ],
+};
+
+const balancedDeferralInput: PostAdjustingEntriesInput = {
+  periodCloseId: subledgersVerifiedPeriodClose.id,
+  adjustingEntries: [
+    {
+      adjustingEntryType: "DEFERRAL",
+      description: "Deferred expense",
+      lines: [
+        { accountId: baseAccount.id, debitAmount: 500, creditAmount: null, description: "Debit" },
+        {
+          accountId: baseAccount2.id,
+          debitAmount: null,
+          creditAmount: 500,
+          description: "Credit",
+        },
+      ],
+    },
+  ],
+};
+
+const balancedReclassificationInput: PostAdjustingEntriesInput = {
+  periodCloseId: subledgersVerifiedPeriodClose.id,
+  adjustingEntries: [
+    {
+      adjustingEntryType: "RECLASSIFICATION",
+      description: "Reclassification entry",
+      lines: [
+        { accountId: baseAccount.id, debitAmount: 2000, creditAmount: null, description: "Debit" },
+        {
+          accountId: baseAccount2.id,
+          debitAmount: null,
+          creditAmount: 2000,
+          description: "Credit",
+        },
+      ],
+    },
+  ],
+};
+
+describe("postAdjustingEntries", () => {
+  it("returns error when PeriodClose record does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined); // PeriodClose lookup
+
+    const result = await run(
+      db,
+      { ...balancedAccrualInput, periodCloseId: "nonexistent" },
+      commandCtx,
+    );
+
+    expectErr(result, PeriodCloseNotFoundError);
+  });
+
+  it("returns error when PeriodClose is in IN_PROGRESS status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(inProgressPeriodClose);
+
+    const result = await run(
+      db,
+      { ...balancedAccrualInput, periodCloseId: inProgressPeriodClose.id },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("returns error when PeriodClose is already in ADJUSTMENTS_POSTED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(adjustmentsPostedPeriodClose);
+
+    const result = await run(
+      db,
+      { ...balancedAccrualInput, periodCloseId: adjustmentsPostedPeriodClose.id },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("returns error when adjusting entry type is invalid", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(subledgersVerifiedPeriodClose);
+
+    const input: PostAdjustingEntriesInput = {
+      periodCloseId: subledgersVerifiedPeriodClose.id,
+      adjustingEntries: [
+        {
+          adjustingEntryType: "INVALID_TYPE",
+          description: "Bad type",
+          lines: [
+            {
+              accountId: baseAccount.id,
+              debitAmount: 100,
+              creditAmount: null,
+              description: "Debit",
+            },
+            {
+              accountId: baseAccount2.id,
+              debitAmount: null,
+              creditAmount: 100,
+              description: "Credit",
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = await run(db, input, commandCtx);
+
+    expectErr(result, InvalidAdjustingEntryTypeError);
+  });
+
+  it("returns error when adjusting entries are not balanced", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(subledgersVerifiedPeriodClose);
+
+    const input: PostAdjustingEntriesInput = {
+      periodCloseId: subledgersVerifiedPeriodClose.id,
+      adjustingEntries: [
+        {
+          adjustingEntryType: "ACCRUAL",
+          description: "Unbalanced entry",
+          lines: [
+            {
+              accountId: baseAccount.id,
+              debitAmount: 1000,
+              creditAmount: null,
+              description: "Debit",
+            },
+            {
+              accountId: baseAccount2.id,
+              debitAmount: null,
+              creditAmount: 500,
+              description: "Credit",
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = await run(db, input, commandCtx);
+
+    expectErr(result, UnbalancedAdjustingEntriesError);
+  });
+
+  it("posts accrual adjusting entries and transitions to ADJUSTMENTS_POSTED", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(subledgersVerifiedPeriodClose)
+      .mockReturnValueOnce(baseAccountingPeriod);
+
+    const postedJournalEntry = {
+      id: "je-accrual-1",
+      adjustingEntryType: "ACCRUAL",
+      status: "POSTED",
+    };
+    const postedLine1 = { id: "line-1" };
+    const postedLine2 = { id: "line-2" };
+    spies.insert
+      .mockReturnValueOnce(postedJournalEntry)
+      .mockReturnValueOnce(postedLine1)
+      .mockReturnValueOnce(postedLine2);
+
+    const updatedPeriodClose = {
+      ...subledgersVerifiedPeriodClose,
+      status: "ADJUSTMENTS_POSTED",
+      completionPercentage: 50,
+    };
+    spies.update.mockReturnValueOnce(updatedPeriodClose);
+
+    const result = await run(db, balancedAccrualInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.periodClose.status).toBe("ADJUSTMENTS_POSTED");
+    expect(value.postedEntries).toHaveLength(1);
+    expect(value.postedEntries[0].adjustingEntryType).toBe("ACCRUAL");
+  });
+
+  it("posts deferral adjusting entries and transitions to ADJUSTMENTS_POSTED", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(subledgersVerifiedPeriodClose)
+      .mockReturnValueOnce(baseAccountingPeriod);
+
+    const postedJournalEntry = {
+      id: "je-deferral-1",
+      adjustingEntryType: "DEFERRAL",
+      status: "POSTED",
+    };
+    const postedLine1 = { id: "line-1" };
+    const postedLine2 = { id: "line-2" };
+    spies.insert
+      .mockReturnValueOnce(postedJournalEntry)
+      .mockReturnValueOnce(postedLine1)
+      .mockReturnValueOnce(postedLine2);
+
+    const updatedPeriodClose = {
+      ...subledgersVerifiedPeriodClose,
+      status: "ADJUSTMENTS_POSTED",
+      completionPercentage: 50,
+    };
+    spies.update.mockReturnValueOnce(updatedPeriodClose);
+
+    const result = await run(db, balancedDeferralInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.periodClose.status).toBe("ADJUSTMENTS_POSTED");
+    expect(value.postedEntries).toHaveLength(1);
+    expect(value.postedEntries[0].adjustingEntryType).toBe("DEFERRAL");
+  });
+
+  it("posts reclassification adjusting entries and transitions to ADJUSTMENTS_POSTED", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(subledgersVerifiedPeriodClose)
+      .mockReturnValueOnce(baseAccountingPeriod);
+
+    const postedJournalEntry = {
+      id: "je-reclass-1",
+      adjustingEntryType: "RECLASSIFICATION",
+      status: "POSTED",
+    };
+    const postedLine1 = { id: "line-1" };
+    const postedLine2 = { id: "line-2" };
+    spies.insert
+      .mockReturnValueOnce(postedJournalEntry)
+      .mockReturnValueOnce(postedLine1)
+      .mockReturnValueOnce(postedLine2);
+
+    const updatedPeriodClose = {
+      ...subledgersVerifiedPeriodClose,
+      status: "ADJUSTMENTS_POSTED",
+      completionPercentage: 50,
+    };
+    spies.update.mockReturnValueOnce(updatedPeriodClose);
+
+    const result = await run(db, balancedReclassificationInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.periodClose.status).toBe("ADJUSTMENTS_POSTED");
+    expect(value.postedEntries).toHaveLength(1);
+    expect(value.postedEntries[0].adjustingEntryType).toBe("RECLASSIFICATION");
+  });
+
+  it("adjusting entries are flagged distinctly from regular journal entries", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(subledgersVerifiedPeriodClose)
+      .mockReturnValueOnce(baseAccountingPeriod);
+
+    const postedJournalEntry = {
+      id: "je-accrual-1",
+      adjustingEntryType: "ACCRUAL",
+      status: "POSTED",
+    };
+    const postedLine1 = { id: "line-1" };
+    const postedLine2 = { id: "line-2" };
+    spies.insert
+      .mockReturnValueOnce(postedJournalEntry)
+      .mockReturnValueOnce(postedLine1)
+      .mockReturnValueOnce(postedLine2);
+
+    const updatedPeriodClose = {
+      ...subledgersVerifiedPeriodClose,
+      status: "ADJUSTMENTS_POSTED",
+      completionPercentage: 50,
+    };
+    spies.update.mockReturnValueOnce(updatedPeriodClose);
+
+    const result = await run(db, balancedAccrualInput, commandCtx);
+
+    const value = expectOk(result);
+    // Adjusting entries have adjustingEntryType set (not null), unlike regular journal entries
+    for (const entry of value.postedEntries) {
+      expect(entry.adjustingEntryType).not.toBeNull();
+      expect(VALID_ADJUSTING_ENTRY_TYPES).toContain(entry.adjustingEntryType);
+    }
+  });
+
+  it("updates completionPercentage after posting adjusting entries", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(subledgersVerifiedPeriodClose)
+      .mockReturnValueOnce(baseAccountingPeriod);
+
+    const postedJournalEntry = {
+      id: "je-accrual-1",
+      adjustingEntryType: "ACCRUAL",
+      status: "POSTED",
+    };
+    const postedLine1 = { id: "line-1" };
+    const postedLine2 = { id: "line-2" };
+    spies.insert
+      .mockReturnValueOnce(postedJournalEntry)
+      .mockReturnValueOnce(postedLine1)
+      .mockReturnValueOnce(postedLine2);
+
+    const updatedPeriodClose = {
+      ...subledgersVerifiedPeriodClose,
+      status: "ADJUSTMENTS_POSTED",
+      completionPercentage: 50,
+    };
+    spies.update.mockReturnValueOnce(updatedPeriodClose);
+
+    const result = await run(db, balancedAccrualInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.periodClose.completionPercentage).toBe(50);
+    expect(value.periodClose.completionPercentage).toBeGreaterThan(
+      subledgersVerifiedPeriodClose.completionPercentage,
+    );
+  });
+
+  it("emits audit event recording adjusting entry details and status transition", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(subledgersVerifiedPeriodClose)
+      .mockReturnValueOnce(baseAccountingPeriod);
+
+    const postedJournalEntry = {
+      id: "je-accrual-1",
+      adjustingEntryType: "ACCRUAL",
+      status: "POSTED",
+    };
+    const postedLine1 = { id: "line-1" };
+    const postedLine2 = { id: "line-2" };
+    spies.insert
+      .mockReturnValueOnce(postedJournalEntry)
+      .mockReturnValueOnce(postedLine1)
+      .mockReturnValueOnce(postedLine2);
+
+    const updatedPeriodClose = {
+      ...subledgersVerifiedPeriodClose,
+      status: "ADJUSTMENTS_POSTED",
+      completionPercentage: 50,
+    };
+    spies.update.mockReturnValueOnce(updatedPeriodClose);
+
+    const result = await run(db, balancedAccrualInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.auditEvent).toBeDefined();
+    expect(value.auditEvent.type).toBe("ADJUSTING_ENTRIES_POSTED");
+    expect(value.auditEvent.actorId).toBe(commandCtx.actorId);
+    expect(value.auditEvent.from).toBe("SUBLEDGERS_VERIFIED");
+    expect(value.auditEvent.to).toBe("ADJUSTMENTS_POSTED");
+    expect(value.auditEvent.timestamp).toBeDefined();
+    expect(value.auditEvent.adjustingEntries).toBeDefined();
+    expect(value.auditEvent.adjustingEntries).toHaveLength(1);
+    expect(value.auditEvent.adjustingEntries[0].adjustingEntryType).toBe("ACCRUAL");
+  });
+});
+
+const VALID_ADJUSTING_ENTRY_TYPES = ["ACCRUAL", "DEFERRAL", "RECLASSIFICATION"];

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

@@ -0,0 +1,156 @@
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  PeriodCloseNotFoundError,
+  InvalidStatusTransitionError,
+  InvalidAdjustingEntryTypeError,
+  UnbalancedAdjustingEntriesError,
+} from "../lib/errors.generated";
+
+export interface AdjustingEntryLineInput {
+  accountId: string;
+  debitAmount: number | null;
+  creditAmount: number | null;
+  description: string | null;
+}
+
+export interface AdjustingEntryInput {
+  adjustingEntryType: string;
+  description: string | null;
+  lines: AdjustingEntryLineInput[];
+}
+
+export interface PostAdjustingEntriesInput {
+  periodCloseId: string;
+  adjustingEntries: AdjustingEntryInput[];
+}
+
+const VALID_ADJUSTING_ENTRY_TYPES = ["ACCRUAL", "DEFERRAL", "RECLASSIFICATION"];
+
+/**
+ * Function: postAdjustingEntries
+ *
+ * Records adjusting entries (accruals, deferrals, reclassifications) during the
+ * period-end close process and transitions the PeriodClose from SUBLEDGERS_VERIFIED
+ * to ADJUSTMENTS_POSTED status.
+ */
+export async function run(db: Transaction, input: PostAdjustingEntriesInput, ctx: CommandContext) {
+  const { periodCloseId, adjustingEntries } = input;
+
+  // 1. Find PeriodClose record
+  const periodClose = await db
+    .selectFrom("PeriodClose")
+    .selectAll()
+    .where("id", "=", periodCloseId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!periodClose) {
+    return err(new PeriodCloseNotFoundError(periodCloseId));
+  }
+
+  // 2. Validate status is SUBLEDGERS_VERIFIED
+  if (periodClose.status !== "SUBLEDGERS_VERIFIED") {
+    return err(new InvalidStatusTransitionError(periodCloseId));
+  }
+
+  // 3. Validate all adjusting entry types
+  for (const entry of adjustingEntries) {
+    if (!VALID_ADJUSTING_ENTRY_TYPES.includes(entry.adjustingEntryType)) {
+      return err(new InvalidAdjustingEntryTypeError(entry.adjustingEntryType));
+    }
+  }
+
+  // 4. Validate each adjusting entry is balanced (total debits == total credits)
+  for (const entry of adjustingEntries) {
+    const totalDebits = entry.lines.reduce((sum, line) => sum + (line.debitAmount ?? 0), 0);
+    const totalCredits = entry.lines.reduce((sum, line) => sum + (line.creditAmount ?? 0), 0);
+    if (totalDebits !== totalCredits) {
+      return err(new UnbalancedAdjustingEntriesError(periodCloseId));
+    }
+  }
+
+  // 5. Look up accounting period to get companyId
+  const accountingPeriod = await db
+    .selectFrom("AccountingPeriod")
+    .selectAll()
+    .where("id", "=", periodClose.accountingPeriodId)
+    .executeTakeFirst();
+
+  // 6. Post adjusting entries as journal entries
+  const now = new Date();
+  const postedEntries = [];
+
+  let entryIndex = 0;
+  for (const entry of adjustingEntries) {
+    entryIndex++;
+    const journalEntry = await db
+      .insertInto("JournalEntry")
+      .values({
+        companyId: accountingPeriod!.companyId,
+        accountingPeriodId: periodClose.accountingPeriodId,
+        entryDate: now,
+        journalType: "MISCELLANEOUS",
+        referenceNumber: `ADJ-${periodCloseId}-${entryIndex}`,
+        status: "POSTED",
+        description: entry.description,
+        adjustingEntryType: entry.adjustingEntryType as "ACCRUAL" | "DEFERRAL" | "RECLASSIFICATION",
+        postedAt: now,
+        createdAt: now,
+      })
+      .returningAll()
+      .executeTakeFirst();
+
+    // Insert journal lines for this entry
+    for (const line of entry.lines) {
+      await db
+        .insertInto("JournalLine")
+        .values({
+          journalEntryId: journalEntry!.id,
+          accountId: line.accountId,
+          debitAmount: line.debitAmount,
+          creditAmount: line.creditAmount,
+          functionalDebitAmount: line.debitAmount,
+          functionalCreditAmount: line.creditAmount,
+          description: line.description,
+          createdAt: now,
+        })
+        .returningAll()
+        .executeTakeFirst();
+    }
+
+    postedEntries.push(journalEntry!);
+  }
+
+  // 7. Transition PeriodClose to ADJUSTMENTS_POSTED
+  const updatedPeriodClose = await db
+    .updateTable("PeriodClose")
+    .set({
+      status: "ADJUSTMENTS_POSTED",
+      completionPercentage: 50,
+      updatedAt: now,
+    })
+    .where("id", "=", periodCloseId)
+    .returningAll()
+    .executeTakeFirst();
+
+  // 8. Build audit event
+  const auditEvent = {
+    type: "ADJUSTING_ENTRIES_POSTED",
+    actorId: ctx.actorId,
+    timestamp: now,
+    periodCloseId,
+    from: "SUBLEDGERS_VERIFIED",
+    to: "ADJUSTMENTS_POSTED",
+    adjustingEntries: adjustingEntries.map((e) => ({
+      adjustingEntryType: e.adjustingEntryType,
+      lineCount: e.lines.length,
+    })),
+  };
+
+  return ok({
+    periodClose: updatedPeriodClose!,
+    postedEntries,
+    auditEvent,
+  });
+}

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