@tailor-platform/erp-kit 0.4.1 → 0.5.1

package/src/modules/purchase/command/createPurchaseBill.test.ts

@@ -0,0 +1,277 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  DuplicateSupplierInvoiceNumberError,
+  EmptyBillLinesError,
+  InvalidBilledQuantityError,
+  PaymentTermSnapshotMissingError,
+  PurchaseOrderCancelledError,
+  PurchaseOrderLineNotFoundError,
+  SupplierNotFoundError,
+  SupplierTaxIdentificationMissingError,
+} from "../lib/errors.generated";
+import {
+  basePurchaseBill,
+  basePurchaseBillLines,
+  basePurchaseOrder,
+  baseSupplier,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./createPurchaseBill";
+
+describe("createPurchaseBill", () => {
+  it("creates a draft purchase bill with valid line references", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdBill = { ...basePurchaseBill, id: "purchase-bill-new" };
+    spies.select
+      .mockReturnValueOnce(baseSupplier)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce([basePurchaseOrder]);
+    spies.insert.mockReturnValueOnce(createdBill);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseBill.companyId,
+        supplierId: baseSupplier.id,
+        invoiceNumber: "INV-NEW",
+        invoiceDate: basePurchaseBill.invoiceDate,
+        lines: basePurchaseBillLines,
+        supplierTaxIdentification: "TAX-SNAPSHOT",
+      },
+      commandCtx,
+    );
+
+    expect(expectOk(result).purchaseBill.status).toBe("DRAFT");
+    expect(spies.values).toHaveBeenCalledWith(
+      expect.objectContaining({ invoiceNumber: "INV-NEW", status: "DRAFT" }),
+    );
+  });
+
+  it("snapshots payment-term data at create time", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseSupplier)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce([basePurchaseOrder]);
+    spies.insert.mockReturnValueOnce(basePurchaseBill);
+
+    await run(
+      db,
+      {
+        companyId: basePurchaseBill.companyId,
+        supplierId: baseSupplier.id,
+        invoiceNumber: "INV-SNAPSHOT",
+        invoiceDate: basePurchaseBill.invoiceDate,
+        lines: basePurchaseBillLines,
+        supplierTaxIdentification: "TAX-SNAPSHOT",
+      },
+      commandCtx,
+    );
+
+    expect(spies.values).toHaveBeenCalledWith(
+      expect.objectContaining({ paymentTermSnapshot: basePurchaseOrder.paymentTermSnapshot }),
+    );
+  });
+
+  it("snapshots supplier tax identification at create time", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseSupplier)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce([basePurchaseOrder])
+      .mockReturnValueOnce({ value: "TAX-DEFAULT" });
+    spies.insert.mockReturnValueOnce({
+      ...basePurchaseBill,
+      supplierTaxIdentification: "TAX-DEFAULT",
+    });
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseBill.companyId,
+        supplierId: baseSupplier.id,
+        invoiceNumber: "INV-TAX",
+        invoiceDate: basePurchaseBill.invoiceDate,
+        lines: basePurchaseBillLines,
+      },
+      commandCtx,
+    );
+
+    expect(expectOk(result).purchaseBill.supplierTaxIdentification).toBe("TAX-DEFAULT");
+    expect(spies.values).toHaveBeenCalledWith(
+      expect.objectContaining({ supplierTaxIdentification: "TAX-DEFAULT" }),
+    );
+  });
+
+  it("returns error when supplier does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseBill.companyId,
+        supplierId: "missing-supplier",
+        invoiceNumber: "INV-001",
+        invoiceDate: basePurchaseBill.invoiceDate,
+        lines: basePurchaseBillLines,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, SupplierNotFoundError);
+  });
+
+  it("returns error when invoice number is duplicated", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseSupplier).mockReturnValueOnce(basePurchaseBill);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseBill.companyId,
+        supplierId: baseSupplier.id,
+        invoiceNumber: basePurchaseBill.invoiceNumber,
+        invoiceDate: basePurchaseBill.invoiceDate,
+        lines: basePurchaseBillLines,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, DuplicateSupplierInvoiceNumberError);
+  });
+
+  it("returns error when no bill lines are provided", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseSupplier).mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseBill.companyId,
+        supplierId: baseSupplier.id,
+        invoiceNumber: "INV-EMPTY",
+        invoiceDate: basePurchaseBill.invoiceDate,
+        lines: [],
+      },
+      commandCtx,
+    );
+
+    expectErr(result, EmptyBillLinesError);
+  });
+
+  it("returns error when a purchase-order line does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseSupplier)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce([basePurchaseOrder]);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseBill.companyId,
+        supplierId: baseSupplier.id,
+        invoiceNumber: "INV-MISSING-LINE",
+        invoiceDate: basePurchaseBill.invoiceDate,
+        lines: [{ ...basePurchaseBillLines[0], purchaseOrderLineId: "missing-line" }],
+      },
+      commandCtx,
+    );
+
+    expectErr(result, PurchaseOrderLineNotFoundError);
+  });
+
+  it("returns error when billed quantity is zero or negative", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseSupplier)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce([basePurchaseOrder]);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseBill.companyId,
+        supplierId: baseSupplier.id,
+        invoiceNumber: "INV-BAD-QTY",
+        invoiceDate: basePurchaseBill.invoiceDate,
+        lines: [{ ...basePurchaseBillLines[0], quantity: 0 }],
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidBilledQuantityError);
+  });
+
+  it("returns error when referenced purchase order is cancelled", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const cancelledOrder = { ...basePurchaseOrder, status: "CANCELLED" };
+    spies.select
+      .mockReturnValueOnce(baseSupplier)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce([cancelledOrder]);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseBill.companyId,
+        supplierId: baseSupplier.id,
+        invoiceNumber: "INV-CANCELLED",
+        invoiceDate: basePurchaseBill.invoiceDate,
+        lines: basePurchaseBillLines,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, PurchaseOrderCancelledError);
+  });
+
+  it("returns error when no payment-term snapshot is available", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseSupplier)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce([{ ...basePurchaseOrder, paymentTermSnapshot: null }]);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseBill.companyId,
+        supplierId: baseSupplier.id,
+        invoiceNumber: "INV-NO-TERM",
+        invoiceDate: basePurchaseBill.invoiceDate,
+        lines: basePurchaseBillLines,
+        supplierTaxIdentification: "TAX-SNAPSHOT",
+      },
+      commandCtx,
+    );
+
+    expectErr(result, PaymentTermSnapshotMissingError);
+  });
+
+  it("returns error when supplier tax identification cannot be snapshotted", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseSupplier)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce([basePurchaseOrder])
+      .mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseBill.companyId,
+        supplierId: baseSupplier.id,
+        invoiceNumber: "INV-NO-TAX",
+        invoiceDate: basePurchaseBill.invoiceDate,
+        lines: basePurchaseBillLines,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, SupplierTaxIdentificationMissingError);
+  });
+});

package/src/modules/purchase/command/createPurchaseBill.ts

@@ -0,0 +1,107 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  DuplicateSupplierInvoiceNumberError,
+  EmptyBillLinesError,
+  InvalidBilledQuantityError,
+  PaymentTermSnapshotMissingError,
+  PurchaseOrderCancelledError,
+  PurchaseOrderLineNotFoundError,
+  SupplierNotFoundError,
+  SupplierTaxIdentificationMissingError,
+} from "../lib/errors.generated";
+import {
+  encodeJson,
+  findOrderLine,
+  findPurchaseBillDuplicate,
+  getDefaultPartnerIdentification,
+  normalizeBillLines,
+  type PurchaseBillLineInput,
+} from "../lib/domain";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface CreatePurchaseBillInput {
+  companyId: string;
+  supplierId: string;
+  invoiceNumber: string;
+  invoiceDate: Date;
+  lines: PurchaseBillLineInput[];
+  supplierTaxIdentification?: string;
+}
+
+export async function run(db: Transaction, input: CreatePurchaseBillInput, ctx: CommandContext) {
+  void ctx;
+  const supplier = await db
+    .selectFrom("BusinessPartner")
+    .selectAll()
+    .where("id", "=", input.supplierId)
+    .executeTakeFirst();
+  if (!supplier) {
+    return err(new SupplierNotFoundError(input.supplierId));
+  }
+  if (await findPurchaseBillDuplicate(db, input.companyId, input.supplierId, input.invoiceNumber)) {
+    return err(new DuplicateSupplierInvoiceNumberError(input.invoiceNumber));
+  }
+  if (input.lines.length === 0) {
+    return err(new EmptyBillLinesError(input.invoiceNumber));
+  }
+
+  const purchaseOrders = await db.selectFrom("PurchaseOrder").selectAll().execute();
+  const normalizedLines: ReturnType<typeof normalizeBillLines> = [];
+  for (const line of normalizeBillLines(input.lines)) {
+    const match = findOrderLine(purchaseOrders, line.purchaseOrderLineId);
+    if (!match) {
+      return err(new PurchaseOrderLineNotFoundError(line.purchaseOrderLineId));
+    }
+    if (line.quantity <= 0) {
+      return err(new InvalidBilledQuantityError(line.purchaseOrderLineId));
+    }
+    if (match.order.status === "CANCELLED") {
+      return err(new PurchaseOrderCancelledError(String(match.order.id)));
+    }
+    normalizedLines.push({
+      ...line,
+      billedUnitPrice: line.billedUnitPrice ?? match.line.unitPrice,
+    });
+  }
+
+  const firstMatch = normalizedLines[0]
+    ? findOrderLine(purchaseOrders, normalizedLines[0].purchaseOrderLineId)
+    : null;
+  if (!firstMatch?.order.paymentTermSnapshot) {
+    return err(new PaymentTermSnapshotMissingError(input.invoiceNumber));
+  }
+
+  const supplierTaxIdentification =
+    input.supplierTaxIdentification ??
+    ((await getDefaultPartnerIdentification(db, input.supplierId))?.value as string | undefined);
+  if (!supplierTaxIdentification) {
+    return err(new SupplierTaxIdentificationMissingError(input.supplierId));
+  }
+
+  const purchaseBill = await db
+    .insertInto("PurchaseBill")
+    .values({
+      companyId: input.companyId,
+      supplierId: input.supplierId,
+      invoiceNumber: input.invoiceNumber,
+      invoiceDate: input.invoiceDate,
+      status: "DRAFT",
+      lines: encodeJson(normalizedLines),
+      paymentTermSnapshot: firstMatch.order.paymentTermSnapshot as string,
+      supplierTaxIdentification,
+      matchingMode: null,
+      varianceReason: null,
+      releaseReason: null,
+      dueSchedule: null,
+      downstreamAccepted: false,
+      comparisonEvidence: null,
+      billReadyHandoff: null,
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ purchaseBill: purchaseBill! });
+}

package/src/modules/purchase/command/createPurchaseOrder.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./createPurchaseOrder";
+import { defineCommand } from "@tailor-platform/erp-kit/module";
+
+export const createPurchaseOrder = defineCommand(permissions.createPurchaseOrder, run);

package/src/modules/purchase/command/createPurchaseOrder.test.ts

@@ -0,0 +1,291 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  EmptyPurchaseOrderLinesError,
+  ItemNotActiveError,
+  ItemNotFoundError,
+  InvalidQuantityError,
+  InvalidUnitPriceError,
+  PartnerNotSupplierError,
+  PaymentTermInactiveError,
+  ReceivingSiteNotFoundError,
+  ReceivingSiteRequiredError,
+  SupplierNotActiveError,
+  SupplierNotFoundError,
+} from "../lib/errors.generated";
+import {
+  baseItem,
+  basePaymentTerm,
+  basePurchaseOrder,
+  basePurchaseOrderLines,
+  baseReceivingSite,
+  baseSupplier,
+  baseSupplierProfile,
+  inactiveSupplier,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./createPurchaseOrder";
+
+describe("createPurchaseOrder", () => {
+  it("creates a draft purchase order with valid supplier and lines", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseSupplier)
+      .mockReturnValueOnce({ role: "SUPPLIER" })
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(baseItem)
+      .mockReturnValueOnce(baseReceivingSite);
+    spies.insert.mockReturnValueOnce(basePurchaseOrder);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseOrder.companyId,
+        supplierId: baseSupplier.id,
+        lines: basePurchaseOrderLines,
+      },
+      commandCtx,
+    );
+
+    expect(expectOk(result).purchaseOrder.status).toBe("DRAFT");
+  });
+
+  it("inherits default payment term from supplier profile when present", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseSupplier)
+      .mockReturnValueOnce({ role: "SUPPLIER" })
+      .mockReturnValueOnce(baseSupplierProfile)
+      .mockReturnValueOnce(basePaymentTerm)
+      .mockReturnValueOnce(baseItem)
+      .mockReturnValueOnce(baseReceivingSite);
+    spies.insert.mockReturnValueOnce(basePurchaseOrder);
+
+    await run(
+      db,
+      {
+        companyId: basePurchaseOrder.companyId,
+        supplierId: baseSupplier.id,
+        lines: basePurchaseOrderLines,
+      },
+      commandCtx,
+    );
+
+    expect(spies.values).toHaveBeenCalledWith(
+      expect.objectContaining({ paymentTermId: basePaymentTerm.id }),
+    );
+  });
+
+  it("returns error when supplier does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseOrder.companyId,
+        supplierId: "missing",
+        lines: basePurchaseOrderLines,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, SupplierNotFoundError);
+  });
+
+  it("returns error when supplier is inactive", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(inactiveSupplier);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseOrder.companyId,
+        supplierId: inactiveSupplier.id,
+        lines: basePurchaseOrderLines,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, SupplierNotActiveError);
+  });
+
+  it("returns error when partner is not a supplier", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseSupplier).mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseOrder.companyId,
+        supplierId: baseSupplier.id,
+        lines: basePurchaseOrderLines,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, PartnerNotSupplierError);
+  });
+
+  it("returns error when no lines are provided", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseSupplier).mockReturnValueOnce({ role: "SUPPLIER" });
+
+    const result = await run(
+      db,
+      { companyId: basePurchaseOrder.companyId, supplierId: baseSupplier.id, lines: [] },
+      commandCtx,
+    );
+
+    expectErr(result, EmptyPurchaseOrderLinesError);
+  });
+
+  it("returns error when an item does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseSupplier)
+      .mockReturnValueOnce({ role: "SUPPLIER" })
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseOrder.companyId,
+        supplierId: baseSupplier.id,
+        lines: basePurchaseOrderLines,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, ItemNotFoundError);
+  });
+
+  it("returns error when an item is inactive", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseSupplier)
+      .mockReturnValueOnce({ role: "SUPPLIER" })
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce({ ...baseItem, status: "INACTIVE" });
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseOrder.companyId,
+        supplierId: baseSupplier.id,
+        lines: basePurchaseOrderLines,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, ItemNotActiveError);
+  });
+
+  it("returns error when quantity is zero or negative", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseSupplier)
+      .mockReturnValueOnce({ role: "SUPPLIER" })
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(baseItem);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseOrder.companyId,
+        supplierId: baseSupplier.id,
+        lines: [{ ...basePurchaseOrderLines[0], quantity: 0 }],
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidQuantityError);
+  });
+
+  it("returns error when unit price is negative", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseSupplier)
+      .mockReturnValueOnce({ role: "SUPPLIER" })
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(baseItem);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseOrder.companyId,
+        supplierId: baseSupplier.id,
+        lines: [{ ...basePurchaseOrderLines[0], unitPrice: -1 }],
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidUnitPriceError);
+  });
+
+  it("returns error when receiving site is missing for a physical line", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseSupplier)
+      .mockReturnValueOnce({ role: "SUPPLIER" })
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(baseItem);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseOrder.companyId,
+        supplierId: baseSupplier.id,
+        lines: [{ ...basePurchaseOrderLines[0], receivingSiteId: null }],
+      },
+      commandCtx,
+    );
+
+    expectErr(result, ReceivingSiteRequiredError);
+  });
+
+  it("returns error when receiving site does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseSupplier)
+      .mockReturnValueOnce({ role: "SUPPLIER" })
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(baseItem)
+      .mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseOrder.companyId,
+        supplierId: baseSupplier.id,
+        lines: basePurchaseOrderLines,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, ReceivingSiteNotFoundError);
+  });
+
+  it("returns error when inherited payment term is inactive", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseSupplier)
+      .mockReturnValueOnce({ role: "SUPPLIER" })
+      .mockReturnValueOnce(baseSupplierProfile)
+      .mockReturnValueOnce({ ...basePaymentTerm, status: "INACTIVE" });
+
+    const result = await run(
+      db,
+      {
+        companyId: basePurchaseOrder.companyId,
+        supplierId: baseSupplier.id,
+        lines: basePurchaseOrderLines,
+      },
+      commandCtx,
+    );
+
+    expectErr(result, PaymentTermInactiveError);
+  });
+});