@tailor-platform/erp-kit 0.6.0 → 0.7.0

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

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

@@ -0,0 +1,438 @@
+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 {
+  JournalEntryNotFoundError,
+  InvalidStatusForLineAddError,
+  AccountNotFoundError,
+  AccountNotActiveError,
+  InvalidDebitCreditError,
+  CurrencyNotFoundError,
+} from "../lib/errors.generated";
+import {
+  baseJournalEntry,
+  postedJournalEntry,
+  reversedJournalEntry,
+  baseAccount,
+  baseAccount2,
+  inactiveAccount,
+  baseCurrency,
+  baseJournalLine,
+} from "../testing/fixtures";
+import { run } from "./addJournalLine";
+
+describe("addJournalLine", () => {
+  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",
+        accountId: baseAccount.id,
+        debitAmount: 1000,
+        creditAmount: null,
+        description: null,
+        currencyCode: null,
+        exchangeRate: null,
+      },
+      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,
+        accountId: baseAccount.id,
+        debitAmount: 1000,
+        creditAmount: null,
+        description: null,
+        currencyCode: null,
+        exchangeRate: null,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidStatusForLineAddError);
+  });
+
+  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,
+        accountId: baseAccount.id,
+        debitAmount: 1000,
+        creditAmount: null,
+        description: null,
+        currencyCode: null,
+        exchangeRate: null,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidStatusForLineAddError);
+  });
+
+  it("returns error when GL account does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseJournalEntry).mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        accountId: "missing-account",
+        debitAmount: 1000,
+        creditAmount: null,
+        description: null,
+        currencyCode: null,
+        exchangeRate: null,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, AccountNotFoundError);
+  });
+
+  it("returns error when GL account is not active", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseJournalEntry).mockReturnValueOnce(inactiveAccount);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        accountId: inactiveAccount.id,
+        debitAmount: 1000,
+        creditAmount: null,
+        description: null,
+        currencyCode: null,
+        exchangeRate: null,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, AccountNotActiveError);
+  });
+
+  it("returns error when both debit and credit amounts are specified", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseJournalEntry).mockReturnValueOnce(baseAccount);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        accountId: baseAccount.id,
+        debitAmount: 1000,
+        creditAmount: 500,
+        description: null,
+        currencyCode: null,
+        exchangeRate: null,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidDebitCreditError);
+  });
+
+  it("returns error when both debit and credit amounts are zero", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseJournalEntry).mockReturnValueOnce(baseAccount);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        accountId: baseAccount.id,
+        debitAmount: null,
+        creditAmount: null,
+        description: null,
+        currencyCode: null,
+        exchangeRate: null,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidDebitCreditError);
+  });
+
+  it("returns error when debit amount is negative", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseJournalEntry).mockReturnValueOnce(baseAccount);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        accountId: baseAccount.id,
+        debitAmount: -100,
+        creditAmount: null,
+        description: null,
+        currencyCode: null,
+        exchangeRate: null,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidDebitCreditError);
+  });
+
+  it("returns error when credit amount is negative", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseJournalEntry).mockReturnValueOnce(baseAccount);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        accountId: baseAccount.id,
+        debitAmount: null,
+        creditAmount: -200,
+        description: null,
+        currencyCode: null,
+        exchangeRate: null,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidDebitCreditError);
+  });
+
+  it("returns error when currency does not exist for multi-currency line", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseJournalEntry)
+      .mockReturnValueOnce(baseAccount)
+      .mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        accountId: baseAccount.id,
+        debitAmount: 1000,
+        creditAmount: null,
+        description: null,
+        currencyCode: "missing-currency",
+        exchangeRate: 1.5,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, CurrencyNotFoundError);
+  });
+
+  it("adds journal line with debit amount to DRAFT entry", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseJournalEntry).mockReturnValueOnce(baseAccount);
+    spies.insert.mockReturnValueOnce(baseJournalLine);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        accountId: baseAccount.id,
+        debitAmount: 1000,
+        creditAmount: null,
+        description: "Debit line",
+        currencyCode: null,
+        exchangeRate: null,
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.journalLine).toEqual(baseJournalLine);
+  });
+
+  it("adds journal line with credit amount to DRAFT entry", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const creditLine = {
+      ...baseJournalLine,
+      id: "journal-line-credit",
+      debitAmount: null,
+      creditAmount: 500,
+      functionalDebitAmount: null,
+      functionalCreditAmount: 500,
+    };
+    spies.select.mockReturnValueOnce(baseJournalEntry).mockReturnValueOnce(baseAccount2);
+    spies.insert.mockReturnValueOnce(creditLine);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        accountId: baseAccount2.id,
+        debitAmount: null,
+        creditAmount: 500,
+        description: null,
+        currencyCode: null,
+        exchangeRate: null,
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.journalLine).toEqual(creditLine);
+  });
+
+  it("adds multi-currency journal line with currency and exchange rate", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const multiCurrencyLine = {
+      ...baseJournalLine,
+      id: "journal-line-multi",
+      debitAmount: 1000,
+      currencyCode: baseCurrency.code,
+      exchangeRate: 1.5,
+      functionalDebitAmount: 1500,
+      functionalCreditAmount: null,
+    };
+    spies.select
+      .mockReturnValueOnce(baseJournalEntry)
+      .mockReturnValueOnce(baseAccount)
+      .mockReturnValueOnce(baseCurrency);
+    spies.insert.mockReturnValueOnce(multiCurrencyLine);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        accountId: baseAccount.id,
+        debitAmount: 1000,
+        creditAmount: null,
+        description: null,
+        currencyCode: baseCurrency.code,
+        exchangeRate: 1.5,
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.journalLine).toEqual(multiCurrencyLine);
+  });
+
+  it("defaults to functional currency with exchange rate 1.0 when currency not specified", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseJournalEntry).mockReturnValueOnce(baseAccount);
+    spies.insert.mockReturnValueOnce(baseJournalLine);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        accountId: baseAccount.id,
+        debitAmount: 1000,
+        creditAmount: null,
+        description: null,
+        currencyCode: null,
+        exchangeRate: null,
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.journalLine).toBeDefined();
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("computes functional currency amount as foreign amount multiplied by exchange rate", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const computedLine = {
+      ...baseJournalLine,
+      id: "journal-line-computed",
+      debitAmount: null,
+      creditAmount: 200,
+      currencyCode: baseCurrency.code,
+      exchangeRate: 2.5,
+      functionalDebitAmount: null,
+      functionalCreditAmount: 500,
+    };
+    spies.select
+      .mockReturnValueOnce(baseJournalEntry)
+      .mockReturnValueOnce(baseAccount)
+      .mockReturnValueOnce(baseCurrency);
+    spies.insert.mockReturnValueOnce(computedLine);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        accountId: baseAccount.id,
+        debitAmount: null,
+        creditAmount: 200,
+        description: null,
+        currencyCode: baseCurrency.code,
+        exchangeRate: 2.5,
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.journalLine).toEqual(computedLine);
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("adds journal line with optional description", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const lineWithDesc = {
+      ...baseJournalLine,
+      description: "Office supplies purchase",
+    };
+    spies.select.mockReturnValueOnce(baseJournalEntry).mockReturnValueOnce(baseAccount);
+    spies.insert.mockReturnValueOnce(lineWithDesc);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        accountId: baseAccount.id,
+        debitAmount: 1000,
+        creditAmount: null,
+        description: "Office supplies purchase",
+        currencyCode: null,
+        exchangeRate: null,
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.journalLine.description).toBe("Office supplies purchase");
+  });
+
+  it("emits audit event recording line addition and acting user", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseJournalEntry).mockReturnValueOnce(baseAccount);
+    spies.insert.mockReturnValueOnce(baseJournalLine);
+
+    const result = await run(
+      db,
+      {
+        journalEntryId: baseJournalEntry.id,
+        accountId: baseAccount.id,
+        debitAmount: 1000,
+        creditAmount: null,
+        description: null,
+        currencyCode: null,
+        exchangeRate: null,
+      },
+      commandCtx,
+    );
+
+    expectOk(result);
+    expect(spies.insert).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,122 @@
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  JournalEntryNotFoundError,
+  InvalidStatusForLineAddError,
+  AccountNotFoundError,
+  AccountNotActiveError,
+  InvalidDebitCreditError,
+  CurrencyNotFoundError,
+} from "../lib/errors.generated";
+
+export interface AddJournalLineInput {
+  journalEntryId: string;
+  accountId: string;
+  debitAmount: number | null;
+  creditAmount: number | null;
+  description: string | null;
+  currencyCode: string | null;
+  exchangeRate: number | null;
+}
+
+export async function run(db: Transaction, input: AddJournalLineInput, ctx: CommandContext) {
+  // 1. Fetch and validate journal entry
+  const entry = await db
+    .selectFrom("JournalEntry")
+    .selectAll()
+    .where("id", "=", input.journalEntryId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!entry) {
+    return err(new JournalEntryNotFoundError(input.journalEntryId));
+  }
+
+  if (entry.status !== "DRAFT") {
+    return err(new InvalidStatusForLineAddError(input.journalEntryId));
+  }
+
+  // 2. Validate GL account
+  const account = await db
+    .selectFrom("Account")
+    .selectAll()
+    .where("id", "=", input.accountId)
+    .executeTakeFirst();
+
+  if (!account) {
+    return err(new AccountNotFoundError(input.accountId));
+  }
+
+  if (account.status !== "ACTIVE") {
+    return err(new AccountNotActiveError(input.accountId));
+  }
+
+  // 3. Validate debit/credit
+  const hasDebit = input.debitAmount !== null && input.debitAmount !== undefined;
+  const hasCredit = input.creditAmount !== null && input.creditAmount !== undefined;
+
+  if (hasDebit && hasCredit) {
+    return err(new InvalidDebitCreditError(input.journalEntryId));
+  }
+
+  if (!hasDebit && !hasCredit) {
+    return err(new InvalidDebitCreditError(input.journalEntryId));
+  }
+
+  if (hasDebit && input.debitAmount! <= 0) {
+    return err(new InvalidDebitCreditError(input.journalEntryId));
+  }
+
+  if (hasCredit && input.creditAmount! <= 0) {
+    return err(new InvalidDebitCreditError(input.journalEntryId));
+  }
+
+  // 4. Multi-currency validation
+  let currencyCode = input.currencyCode;
+  let exchangeRate = input.exchangeRate ?? 1.0;
+
+  if (input.currencyCode) {
+    const currency = await db
+      .selectFrom("Currency")
+      .selectAll()
+      .where("code", "=", input.currencyCode)
+      .executeTakeFirst();
+
+    if (!currency?.isActive) {
+      return err(new CurrencyNotFoundError(input.currencyCode));
+    }
+  } else {
+    currencyCode = null;
+    exchangeRate = 1.0;
+  }
+
+  // 5. Compute functional amounts
+  const debitAmount = hasDebit ? input.debitAmount! : null;
+  const creditAmount = hasCredit ? input.creditAmount! : null;
+  const functionalDebitAmount = debitAmount !== null ? debitAmount * exchangeRate : null;
+  const functionalCreditAmount = creditAmount !== null ? creditAmount * exchangeRate : null;
+
+  // 6. Create journal line
+  const journalLine = await db
+    .insertInto("JournalLine")
+    .values({
+      journalEntryId: input.journalEntryId,
+      accountId: input.accountId,
+      debitAmount,
+      creditAmount,
+      description: input.description,
+      currencyCode,
+      exchangeRate: input.currencyCode ? exchangeRate : null,
+      functionalDebitAmount,
+      functionalCreditAmount,
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  // Emit audit event recording the line addition, acting user, and timestamp
+  void ctx;
+
+  return ok({ journalLine });
+}

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

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

@@ -0,0 +1,107 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  PeriodCloseNotFoundError,
+  InvalidStatusTransitionError,
+  InsufficientPermissionsError,
+} from "../lib/errors.generated";
+import {
+  underReviewPeriodClose,
+  softLockedPeriodClose,
+  inProgressPeriodClose,
+  basePeriodClose,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./approveAndLockPeriod";
+
+describe("approveAndLockPeriod", () => {
+  it("returns error when PeriodClose record does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "nonexistent" }, commandCtx);
+
+    expectErr(result, PeriodCloseNotFoundError);
+  });
+
+  it("returns error when PeriodClose is in NOT_STARTED status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(basePeriodClose);
+
+    const result = await run(db, { id: basePeriodClose.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  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, { id: inProgressPeriodClose.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("returns error when PeriodClose is already SOFT_LOCKED", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(softLockedPeriodClose);
+
+    const result = await run(db, { id: softLockedPeriodClose.id }, commandCtx);
+
+    expectErr(result, InvalidStatusTransitionError);
+  });
+
+  it("returns error when user lacks required permissions", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(underReviewPeriodClose);
+
+    const noPermCtx = { actorId: "test-actor", permissions: [] as string[] };
+    const result = await run(db, { id: underReviewPeriodClose.id }, noPermCtx);
+
+    expectErr(result, InsufficientPermissionsError);
+  });
+
+  it("transitions UNDER_REVIEW PeriodClose to SOFT_LOCKED with approvedByUserId and completionPercentage", async () => {
+    const updatedPeriodClose = {
+      ...underReviewPeriodClose,
+      status: "SOFT_LOCKED",
+      completionPercentage: 87,
+      approvedByUserId: commandCtx.actorId,
+    };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(underReviewPeriodClose);
+    spies.update.mockReturnValueOnce(updatedPeriodClose);
+
+    const result = await run(db, { id: underReviewPeriodClose.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.periodClose.status).toBe("SOFT_LOCKED");
+    expect(value.periodClose.approvedByUserId).toBe(commandCtx.actorId);
+    expect(value.periodClose.completionPercentage).toBe(87);
+  });
+
+  it("emits audit event recording status transition from UNDER_REVIEW to SOFT_LOCKED", async () => {
+    const updatedPeriodClose = {
+      ...underReviewPeriodClose,
+      status: "SOFT_LOCKED",
+      completionPercentage: 87,
+      approvedByUserId: commandCtx.actorId,
+    };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(underReviewPeriodClose);
+    spies.update.mockReturnValueOnce(updatedPeriodClose);
+
+    const result = await run(db, { id: underReviewPeriodClose.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.auditTrail).toContainEqual(
+      expect.objectContaining({
+        type: "STATUS_TRANSITION",
+        from: "UNDER_REVIEW",
+        to: "SOFT_LOCKED",
+        actorId: commandCtx.actorId,
+      }),
+    );
+  });
+});