@tailor-platform/erp-kit 0.5.1 → 0.7.0

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

@@ -0,0 +1,133 @@
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  InvalidPeriodStatusError,
+  AccountNotFoundError,
+  AccountNotActiveError,
+  InvalidAmountError,
+  CompanyMismatchError,
+} from "../lib/errors.generated";
+
+export interface ProcessManufacturingHandoffInput {
+  companyId: string;
+  accountingPeriodId: string;
+  sourceDocumentReference: string;
+  entryDate: Date;
+  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: ProcessManufacturingHandoffInput,
+  _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: "MANUFACTURING",
+      referenceNumber: input.sourceDocumentReference,
+      status: "POSTED",
+      description: input.description ?? null,
+      sourceDocumentReference: input.sourceDocumentReference,
+      postedAt: now,
+      createdAt: now,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  // 9. Create journal lines (debit + credit)
+  await db
+    .insertInto("JournalLine")
+    .values([
+      {
+        journalEntryId: journalEntry!.id,
+        accountId: input.debitAccountId,
+        debitAmount: input.amount,
+        creditAmount: null,
+        functionalDebitAmount: functionalAmount,
+        functionalCreditAmount: null,
+        currencyCode: input.currencyCode ?? null,
+        exchangeRate: input.exchangeRate ?? null,
+        createdAt: now,
+      },
+      {
+        journalEntryId: journalEntry!.id,
+        accountId: input.creditAccountId,
+        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/processPurchaseHandoff.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 "./processPurchaseHandoff";
+
+export const processPurchaseHandoff = defineCommand(permissions.processPurchaseHandoff, run);

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

@@ -0,0 +1,222 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  InvalidPeriodStatusError,
+  AccountNotFoundError,
+  AccountNotActiveError,
+  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 "./processPurchaseHandoff";
+
+describe("processPurchaseHandoff", () => {
+  const baseInput = {
+    companyId: baseCompany.id,
+    accountingPeriodId: baseAccountingPeriod.id,
+    sourceDocumentReference: "PO-001",
+    entryDate: new Date("2024-01-15"),
+    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: "PO-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 does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(undefined) // no existing entry
+      .mockReturnValueOnce(baseAccountingPeriod) // period lookup
+      .mockReturnValueOnce(undefined); // debit account lookup — not found
+
+    const result = await run(
+      db,
+      { ...baseInput, debitAccountId: "nonexistent-account" },
+      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 lookup — not found
+
+    const result = await run(
+      db,
+      { ...baseInput, creditAccountId: "nonexistent-account" },
+      commandCtx,
+    );
+
+    expectErr(result, AccountNotFoundError);
+  });
+
+  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("creates journal entry with correct type and amounts", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdEntry = {
+      ...baseJournalEntry,
+      journalType: "PURCHASE",
+      status: "POSTED",
+      sourceDocumentReference: "PO-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("PURCHASE");
+    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: "PURCHASE",
+      status: "POSTED",
+      sourceDocumentReference: "PO-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: "PO-002",
+        currencyCode: "currency-1",
+        exchangeRate: 1.5,
+        amount: 1000,
+      },
+      commandCtx,
+    );
+
+    const value = expectOk(result);
+    expect(value.journalEntry).toBeDefined();
+    expect(value.idempotent).toBe(false);
+    // Verify the values spy was called with amounts reflecting the exchange rate
+    expect(spies.values).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,133 @@
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  InvalidPeriodStatusError,
+  AccountNotFoundError,
+  AccountNotActiveError,
+  InvalidAmountError,
+  CompanyMismatchError,
+} from "../lib/errors.generated";
+
+export interface ProcessPurchaseHandoffInput {
+  companyId: string;
+  accountingPeriodId: string;
+  sourceDocumentReference: string;
+  entryDate: Date;
+  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: ProcessPurchaseHandoffInput,
+  _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 exists and 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 exists and 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: "PURCHASE",
+      referenceNumber: input.sourceDocumentReference,
+      status: "POSTED",
+      description: input.description ?? null,
+      sourceDocumentReference: input.sourceDocumentReference,
+      postedAt: now,
+      createdAt: now,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  // 9. Create journal lines (debit + credit)
+  await db
+    .insertInto("JournalLine")
+    .values([
+      {
+        journalEntryId: journalEntry!.id,
+        accountId: input.debitAccountId,
+        debitAmount: input.amount,
+        creditAmount: null,
+        functionalDebitAmount: functionalAmount,
+        functionalCreditAmount: null,
+        currencyCode: input.currencyCode ?? null,
+        exchangeRate: input.exchangeRate ?? null,
+        createdAt: now,
+      },
+      {
+        journalEntryId: journalEntry!.id,
+        accountId: input.creditAccountId,
+        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/processSalesHandoff.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 "./processSalesHandoff";
+
+export const processSalesHandoff = defineCommand(permissions.processSalesHandoff, run);