@tailor-platform/erp-kit 0.5.1 → 0.7.0

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

@@ -0,0 +1,257 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  InvalidPeriodStatusError,
+  AccountNotActiveError,
+  AccountNotFoundError,
+  InvalidAmountError,
+  CompanyMismatchError,
+} from "../lib/errors.generated";
+import {
+  baseAccountingPeriod,
+  neverOpenedPeriod,
+  closedPeriod,
+  baseAccount,
+  baseAccount2,
+  inactiveAccount,
+  baseCompany,
+  baseJournalEntry,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./processSalesHandoff";
+
+describe("processSalesHandoff", () => {
+  const baseInput = {
+    companyId: baseCompany.id,
+    accountingPeriodId: baseAccountingPeriod.id,
+    sourceDocumentReference: "INV-001",
+    entryDate: new Date("2024-01-15"),
+    documentType: "INVOICE",
+    debitAccountId: baseAccount.id,
+    creditAccountId: baseAccount2.id,
+    amount: 1000,
+  };
+
+  it("returns existing entry for idempotent duplicate", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const existingEntry = { ...baseJournalEntry, sourceDocumentReference: "INV-001" };
+    spies.select.mockReturnValueOnce(existingEntry);
+
+    const result = await run(db, baseInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.journalEntry).toEqual(existingEntry);
+    expect(value.idempotent).toBe(true);
+    expect(spies.insert).not.toHaveBeenCalled();
+  });
+
+  it("returns error when amount is zero or negative", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined); // no existing entry
+
+    const result = await run(db, { ...baseInput, amount: 0 }, commandCtx);
+
+    expectErr(result, InvalidAmountError);
+  });
+
+  it("returns error when amount is negative", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined); // no existing entry
+
+    const result = await run(db, { ...baseInput, amount: -100 }, commandCtx);
+
+    expectErr(result, InvalidAmountError);
+  });
+
+  it("returns error when period is not OPEN or FUTURE_ENTERABLE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(undefined) // no existing entry
+      .mockReturnValueOnce(neverOpenedPeriod); // period lookup
+
+    const result = await run(
+      db,
+      { ...baseInput, accountingPeriodId: neverOpenedPeriod.id },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidPeriodStatusError);
+  });
+
+  it("returns error when period is CLOSED", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(undefined) // no existing entry
+      .mockReturnValueOnce(closedPeriod); // period lookup
+
+    const result = await run(db, { ...baseInput, accountingPeriodId: closedPeriod.id }, commandCtx);
+
+    expectErr(result, InvalidPeriodStatusError);
+  });
+
+  it("returns error when company does not match period company", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(undefined) // no existing entry
+      .mockReturnValueOnce(baseAccountingPeriod); // period lookup
+
+    const result = await run(db, { ...baseInput, companyId: "other-company" }, commandCtx);
+
+    expectErr(result, CompanyMismatchError);
+  });
+
+  it("returns error when debit account is not active", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(undefined) // no existing entry
+      .mockReturnValueOnce(baseAccountingPeriod) // period lookup
+      .mockReturnValueOnce(inactiveAccount); // debit account lookup
+
+    const result = await run(db, { ...baseInput, debitAccountId: inactiveAccount.id }, commandCtx);
+
+    expectErr(result, AccountNotActiveError);
+  });
+
+  it("returns error when credit account is not active", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(undefined) // no existing entry
+      .mockReturnValueOnce(baseAccountingPeriod) // period lookup
+      .mockReturnValueOnce(baseAccount) // debit account lookup (active)
+      .mockReturnValueOnce(inactiveAccount); // credit account lookup
+
+    const result = await run(db, { ...baseInput, creditAccountId: inactiveAccount.id }, commandCtx);
+
+    expectErr(result, AccountNotActiveError);
+  });
+
+  it("returns error when debit account does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(undefined) // no existing entry
+      .mockReturnValueOnce(baseAccountingPeriod) // period lookup
+      .mockReturnValueOnce(undefined); // debit account not found
+
+    const result = await run(db, baseInput, commandCtx);
+
+    expectErr(result, AccountNotFoundError);
+  });
+
+  it("returns error when credit account does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(undefined) // no existing entry
+      .mockReturnValueOnce(baseAccountingPeriod) // period lookup
+      .mockReturnValueOnce(baseAccount) // debit account lookup (active)
+      .mockReturnValueOnce(undefined); // credit account not found
+
+    const result = await run(db, baseInput, commandCtx);
+
+    expectErr(result, AccountNotFoundError);
+  });
+
+  it("creates journal entry with correct type and amounts", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdEntry = {
+      ...baseJournalEntry,
+      journalType: "SALES",
+      status: "POSTED",
+      sourceDocumentReference: "INV-001",
+    };
+    spies.select
+      .mockReturnValueOnce(undefined) // no existing entry
+      .mockReturnValueOnce(baseAccountingPeriod) // period lookup
+      .mockReturnValueOnce(baseAccount) // debit account lookup
+      .mockReturnValueOnce(baseAccount2); // credit account lookup
+    spies.insert
+      .mockReturnValueOnce(createdEntry) // journal entry insert
+      .mockReturnValueOnce([]); // journal lines insert
+
+    const result = await run(db, baseInput, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.journalEntry.journalType).toBe("SALES");
+    expect(value.journalEntry.status).toBe("POSTED");
+    expect(value.idempotent).toBe(false);
+    expect(value.acknowledged).toBe(true);
+  });
+
+  it("handles multi-currency with exchange rate", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdEntry = {
+      ...baseJournalEntry,
+      journalType: "SALES",
+      status: "POSTED",
+      sourceDocumentReference: "INV-002",
+    };
+    spies.select
+      .mockReturnValueOnce(undefined) // no existing entry
+      .mockReturnValueOnce(baseAccountingPeriod) // period lookup
+      .mockReturnValueOnce(baseAccount) // debit account lookup
+      .mockReturnValueOnce(baseAccount2); // credit account lookup
+    spies.insert
+      .mockReturnValueOnce(createdEntry) // journal entry insert
+      .mockReturnValueOnce([]); // journal lines insert
+
+    const result = await run(
+      db,
+      {
+        ...baseInput,
+        sourceDocumentReference: "INV-002",
+        currencyCode: "USD",
+        exchangeRate: 1.5,
+        amount: 1000,
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.journalEntry).toBeDefined();
+    expect(value.idempotent).toBe(false);
+    expect(spies.values).toHaveBeenCalled();
+  });
+
+  it("swaps debit and credit accounts for credit note document type", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdEntry = {
+      ...baseJournalEntry,
+      journalType: "SALES",
+      status: "POSTED",
+      sourceDocumentReference: "CN-001",
+    };
+    spies.select
+      .mockReturnValueOnce(undefined) // no existing entry
+      .mockReturnValueOnce(baseAccountingPeriod) // period lookup
+      .mockReturnValueOnce(baseAccount) // debit account lookup
+      .mockReturnValueOnce(baseAccount2); // credit account lookup
+    spies.insert
+      .mockReturnValueOnce(createdEntry) // journal entry insert
+      .mockReturnValueOnce([]); // journal lines insert
+
+    const result = await run(
+      db,
+      { ...baseInput, sourceDocumentReference: "CN-001", documentType: "CREDIT_NOTE" },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.journalEntry.journalType).toBe("SALES");
+    expect(value.idempotent).toBe(false);
+    // Verify lines were inserted with swapped accounts (credit account becomes debit, debit becomes credit)
+    expect(spies.values).toHaveBeenCalledWith(
+      expect.arrayContaining([
+        expect.objectContaining({
+          accountId: baseInput.creditAccountId,
+          debitAmount: baseInput.amount,
+          creditAmount: null,
+        }),
+        expect.objectContaining({
+          accountId: baseInput.debitAccountId,
+          debitAmount: null,
+          creditAmount: baseInput.amount,
+        }),
+      ]),
+    );
+  });
+});

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

@@ -0,0 +1,135 @@
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  InvalidPeriodStatusError,
+  AccountNotActiveError,
+  AccountNotFoundError,
+  InvalidAmountError,
+  CompanyMismatchError,
+} from "../lib/errors.generated";
+
+export interface ProcessSalesHandoffInput {
+  companyId: string;
+  accountingPeriodId: string;
+  sourceDocumentReference: string;
+  entryDate: Date;
+  documentType: string;
+  debitAccountId: string;
+  creditAccountId: string;
+  amount: number;
+  currencyCode?: string;
+  exchangeRate?: number;
+  description?: string;
+}
+
+const VALID_PERIOD_STATUSES = ["OPEN", "FUTURE_ENTERABLE"];
+
+export async function run(db: Transaction, input: ProcessSalesHandoffInput, _ctx: CommandContext) {
+  // 1. Idempotency check: look for existing entry with same sourceDocumentReference + companyId
+  const existing = await db
+    .selectFrom("JournalEntry")
+    .selectAll()
+    .where("sourceDocumentReference", "=", input.sourceDocumentReference)
+    .where("companyId", "=", input.companyId)
+    .executeTakeFirst();
+  if (existing) return ok({ journalEntry: existing, acknowledged: true, idempotent: true });
+
+  // 2. Validate amount > 0
+  if (input.amount <= 0) return err(new InvalidAmountError(input.sourceDocumentReference));
+
+  // 3. Find and validate period
+  const period = await db
+    .selectFrom("AccountingPeriod")
+    .selectAll()
+    .where("id", "=", input.accountingPeriodId)
+    .executeTakeFirst();
+  if (!period || !VALID_PERIOD_STATUSES.includes(period.status))
+    return err(new InvalidPeriodStatusError(input.accountingPeriodId));
+
+  // 4. Validate company matches period's company
+  if (period.companyId !== input.companyId) return err(new CompanyMismatchError(input.companyId));
+
+  // 5. Validate debit account is ACTIVE
+  const debitAccount = await db
+    .selectFrom("Account")
+    .selectAll()
+    .where("id", "=", input.debitAccountId)
+    .executeTakeFirst();
+  if (!debitAccount) return err(new AccountNotFoundError(input.debitAccountId));
+  if (debitAccount.status !== "ACTIVE") return err(new AccountNotActiveError(input.debitAccountId));
+
+  // 6. Validate credit account is ACTIVE
+  const creditAccount = await db
+    .selectFrom("Account")
+    .selectAll()
+    .where("id", "=", input.creditAccountId)
+    .executeTakeFirst();
+  if (!creditAccount) return err(new AccountNotFoundError(input.creditAccountId));
+  if (creditAccount.status !== "ACTIVE")
+    return err(new AccountNotActiveError(input.creditAccountId));
+
+  // 7. Calculate functional amounts
+  const rate = input.exchangeRate ?? 1;
+  const functionalAmount = input.amount * rate;
+
+  // 8. Create journal entry (auto-posted)
+  const now = new Date();
+  const journalEntry = await db
+    .insertInto("JournalEntry")
+    .values({
+      companyId: input.companyId,
+      accountingPeriodId: input.accountingPeriodId,
+      entryDate: input.entryDate,
+      journalType: "SALES",
+      referenceNumber: input.sourceDocumentReference,
+      status: "POSTED",
+      description: input.description ?? null,
+      sourceDocumentReference: input.sourceDocumentReference,
+      postedAt: now,
+      createdAt: now,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  // 9. Create journal lines (debit + credit)
+  // For credit notes, swap debit/credit accounts to create a reversing entry
+  const isCreditNote = input.documentType === "CREDIT_NOTE";
+  const debitLineAccountId = isCreditNote ? input.creditAccountId : input.debitAccountId;
+  const creditLineAccountId = isCreditNote ? input.debitAccountId : input.creditAccountId;
+
+  await db
+    .insertInto("JournalLine")
+    .values([
+      {
+        journalEntryId: journalEntry!.id,
+        accountId: debitLineAccountId,
+        debitAmount: input.amount,
+        creditAmount: null,
+        functionalDebitAmount: functionalAmount,
+        functionalCreditAmount: null,
+        currencyCode: input.currencyCode ?? null,
+        exchangeRate: input.exchangeRate ?? null,
+        createdAt: now,
+      },
+      {
+        journalEntryId: journalEntry!.id,
+        accountId: creditLineAccountId,
+        debitAmount: null,
+        creditAmount: input.amount,
+        functionalDebitAmount: null,
+        functionalCreditAmount: functionalAmount,
+        currencyCode: input.currencyCode ?? null,
+        exchangeRate: input.exchangeRate ?? null,
+        createdAt: now,
+      },
+    ])
+    .returningAll()
+    .execute();
+
+  return ok({
+    journalEntry: journalEntry!,
+    acknowledged: true,
+    acknowledgedAt: now,
+    idempotent: false,
+  });
+}

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

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

@@ -0,0 +1,129 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  FinancialStatementNotFoundError,
+  StatementAlreadyFinalizedError,
+  TrialBalanceNotFoundError,
+  TrialBalanceImbalancedError,
+  ComparativeTrialBalanceNotFoundError,
+} from "../lib/errors.generated";
+import {
+  baseFinancialStatement,
+  finalizedFinancialStatement,
+  baseTrialBalance,
+  baseTrialBalanceLine,
+  baseAccount,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./regenerateFinancialStatement";
+
+describe("regenerateFinancialStatement", () => {
+  it("returns error when financial statement does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined); // statement lookup
+
+    const result = await run(db, { id: "nonexistent" }, commandCtx);
+
+    expectErr(result, FinancialStatementNotFoundError);
+  });
+
+  it("returns error when financial statement is already FINALIZED", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(finalizedFinancialStatement); // statement lookup
+
+    const result = await run(db, { id: finalizedFinancialStatement.id }, commandCtx);
+
+    expectErr(result, StatementAlreadyFinalizedError);
+  });
+
+  it("returns error when trial balance is not found", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseFinancialStatement); // statement lookup
+    spies.select.mockReturnValueOnce(undefined); // trial balance lookup
+
+    const result = await run(db, { id: baseFinancialStatement.id }, commandCtx);
+
+    expectErr(result, TrialBalanceNotFoundError);
+  });
+
+  it("returns error when trial balance is imbalanced", async () => {
+    const imbalancedTrialBalance = {
+      ...baseTrialBalance,
+      isBalanced: false,
+      totalDebits: 10000,
+      totalCredits: 9000,
+    };
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseFinancialStatement); // statement lookup
+    spies.select.mockReturnValueOnce(imbalancedTrialBalance); // trial balance lookup
+
+    const result = await run(db, { id: baseFinancialStatement.id }, commandCtx);
+
+    expectErr(result, TrialBalanceImbalancedError);
+  });
+
+  it("returns error when comparative trial balance is not found", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const statementWithComparative = {
+      ...baseFinancialStatement,
+      comparativePeriodTrialBalanceId: "comparative-tb-1",
+    };
+    spies.select.mockReturnValueOnce(statementWithComparative); // statement lookup
+    spies.select.mockReturnValueOnce(baseTrialBalance); // trial balance lookup
+    spies.select.mockReturnValueOnce(undefined); // comparative trial balance lookup - not found
+
+    const result = await run(db, { id: baseFinancialStatement.id }, commandCtx);
+
+    expectErr(result, ComparativeTrialBalanceNotFoundError);
+  });
+
+  it("regenerates statement with fresh data and updates generatedAt", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedStatement = {
+      ...baseFinancialStatement,
+      generatedAt: new Date(),
+      updatedAt: new Date(),
+    };
+
+    spies.select.mockReturnValueOnce(baseFinancialStatement); // statement lookup
+    spies.select.mockReturnValueOnce(baseTrialBalance); // trial balance lookup
+    spies.select.mockReturnValueOnce([baseTrialBalanceLine]); // trial balance lines (execute)
+    spies.select.mockReturnValueOnce(baseAccount); // account lookup for line
+    spies.insert.mockReturnValue({}); // line item insert
+    spies.update.mockReturnValueOnce(updatedStatement); // statement update
+
+    const result = await run(db, { id: baseFinancialStatement.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.financialStatement).toBeDefined();
+    expect(value.financialStatement.generatedAt).toBeDefined();
+  });
+
+  it("emits audit event recording statement regeneration", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedStatement = {
+      ...baseFinancialStatement,
+      generatedAt: new Date(),
+      updatedAt: new Date(),
+    };
+
+    spies.select.mockReturnValueOnce(baseFinancialStatement); // statement lookup
+    spies.select.mockReturnValueOnce(baseTrialBalance); // trial balance lookup
+    spies.select.mockReturnValueOnce([baseTrialBalanceLine]); // trial balance lines (execute)
+    spies.select.mockReturnValueOnce(baseAccount); // account lookup for line
+    spies.insert.mockReturnValue({}); // line item insert
+    spies.update.mockReturnValueOnce(updatedStatement); // statement update
+
+    const result = await run(db, { id: baseFinancialStatement.id }, commandCtx);
+
+    const value = expectOk(result);
+    expect(value.auditTrail).toBeDefined();
+    expect(value.auditTrail).toContainEqual(
+      expect.objectContaining({
+        type: "STATEMENT_REGENERATED",
+        actorId: commandCtx.actorId,
+      }),
+    );
+  });
+});