@tailor-platform/erp-kit 0.4.0 → 0.5.0

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);
+  });
+});

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

@@ -0,0 +1,131 @@
+/* eslint-disable @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access */
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  EmptyPurchaseOrderLinesError,
+  ItemNotActiveError,
+  ItemNotFoundError,
+  InvalidQuantityError,
+  InvalidUnitPriceError,
+  PartnerNotSupplierError,
+  PaymentTermInactiveError,
+  ReceivingSiteNotFoundError,
+  ReceivingSiteRequiredError,
+  SupplierNotActiveError,
+  SupplierNotFoundError,
+} from "../lib/errors.generated";
+import {
+  buildPaymentTermSnapshot,
+  encodeJson,
+  getSupplierProfileByCompanyAndSupplier,
+  getSupplierRole,
+  isActiveStatus,
+  normalizeOrderLines,
+  selectOne,
+  type PurchaseOrderLineInput,
+} from "../lib/domain";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface CreatePurchaseOrderInput {
+  companyId: string;
+  supplierId: string;
+  orderDate?: Date;
+  documentReceivingSiteId?: string | null;
+  paymentTermId?: string | null;
+  externalSupplierOrderReference?: string;
+  lines: PurchaseOrderLineInput[];
+}
+
+export async function run(db: Transaction, input: CreatePurchaseOrderInput, ctx: CommandContext) {
+  void ctx;
+  const supplier = await selectOne(db, "BusinessPartner", "id", input.supplierId);
+  if (!supplier) {
+    return err(new SupplierNotFoundError(input.supplierId));
+  }
+  if (!isActiveStatus(supplier.status as string | null)) {
+    return err(new SupplierNotActiveError(input.supplierId));
+  }
+  if (!(await getSupplierRole(db, input.supplierId))) {
+    return err(new PartnerNotSupplierError(input.supplierId));
+  }
+  if (input.lines.length === 0) {
+    return err(new EmptyPurchaseOrderLinesError(input.companyId));
+  }
+
+  let selectedPaymentTermId = input.paymentTermId ?? null;
+  if (!selectedPaymentTermId) {
+    const supplierProfile = await getSupplierProfileByCompanyAndSupplier(
+      db,
+      input.companyId,
+      input.supplierId,
+    );
+    selectedPaymentTermId =
+      (supplierProfile?.defaultPurchasePaymentTermId as string | null) ?? null;
+  }
+
+  let paymentTermSnapshot: string | null = null;
+  if (selectedPaymentTermId) {
+    const paymentTerm = await selectOne(db, "PurchasePaymentTerm", "id", selectedPaymentTermId);
+    if (paymentTerm && !isActiveStatus(paymentTerm.status as string | null)) {
+      return err(new PaymentTermInactiveError(selectedPaymentTermId));
+    }
+    if (paymentTerm) {
+      paymentTermSnapshot = encodeJson(buildPaymentTermSnapshot(paymentTerm));
+    }
+  }
+
+  for (const line of input.lines) {
+    const item = await selectOne(db, "Item", "id", line.itemId);
+    if (!item) {
+      return err(new ItemNotFoundError(line.itemId));
+    }
+    if (!isActiveStatus(item.status as string | null)) {
+      return err(new ItemNotActiveError(line.itemId));
+    }
+    if (line.quantity <= 0) {
+      return err(new InvalidQuantityError(line.itemId));
+    }
+    if (line.unitPrice < 0) {
+      return err(new InvalidUnitPriceError(line.itemId));
+    }
+
+    const receivingSiteId = line.receivingSiteId ?? input.documentReceivingSiteId ?? null;
+    if ((line.requiresPhysicalReceipt ?? true) && !receivingSiteId) {
+      return err(new ReceivingSiteRequiredError(line.itemId));
+    }
+    if (receivingSiteId) {
+      const site = await selectOne(db, "Site", "id", receivingSiteId);
+      if (!site) {
+        return err(new ReceivingSiteNotFoundError(receivingSiteId));
+      }
+    }
+  }
+
+  const lines = normalizeOrderLines(
+    input.lines.map((line) => ({
+      ...line,
+      receivingSiteId: line.receivingSiteId ?? input.documentReceivingSiteId ?? null,
+    })),
+  );
+
+  const purchaseOrder = await db
+    .insertInto("PurchaseOrder")
+    .values({
+      companyId: input.companyId,
+      supplierId: input.supplierId,
+      documentReceivingSiteId: input.documentReceivingSiteId ?? null,
+      paymentTermId: selectedPaymentTermId,
+      status: "DRAFT",
+      orderDate: input.orderDate ?? new Date(),
+      externalSupplierOrderReference: input.externalSupplierOrderReference ?? null,
+      lines: encodeJson(lines),
+      paymentTermSnapshot,
+      rejectionReason: null,
+      closeReason: null,
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ purchaseOrder: purchaseOrder! });
+}

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

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

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

@@ -0,0 +1,140 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CompanyNotFoundError,
+  EmptyScheduleError,
+  InvalidDiscountConfigurationError,
+  InvalidInstallmentTotalError,
+  InvalidScheduleLineError,
+} from "../lib/errors.generated";
+import {
+  baseCompany,
+  basePaymentTerm,
+  baseScheduleLines,
+  installmentScheduleLines,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./createPurchasePaymentTerm";
+
+describe("createPurchasePaymentTerm", () => {
+  it("creates an active payment term with one schedule line", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany);
+    spies.insert.mockReturnValueOnce(basePaymentTerm);
+
+    const result = await run(
+      db,
+      { companyId: basePaymentTerm.companyId, name: "Net 30", scheduleLines: baseScheduleLines },
+      commandCtx,
+    );
+
+    expect(expectOk(result).paymentTerm.status).toBe("ACTIVE");
+  });
+
+  it("creates an installment payment term when percentages total 100 percent", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany);
+    spies.insert.mockReturnValueOnce({
+      ...basePaymentTerm,
+      scheduleLines: JSON.stringify(installmentScheduleLines),
+    });
+
+    const result = await run(
+      db,
+      {
+        companyId: basePaymentTerm.companyId,
+        name: "Installment",
+        scheduleLines: installmentScheduleLines,
+      },
+      commandCtx,
+    );
+
+    expect(expectOk(result).paymentTerm.scheduleLines).toContain("INSTALLMENT");
+  });
+
+  it("returns error when company does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      { companyId: "missing-company", name: "Net 30", scheduleLines: baseScheduleLines },
+      commandCtx,
+    );
+
+    expectErr(result, CompanyNotFoundError);
+  });
+
+  it("returns error when no schedule lines are provided", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany);
+
+    const result = await run(
+      db,
+      { companyId: basePaymentTerm.companyId, name: "Empty", scheduleLines: [] },
+      commandCtx,
+    );
+
+    expectErr(result, EmptyScheduleError);
+  });
+
+  it("returns error when installment percentages do not total 100 percent", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePaymentTerm.companyId,
+        name: "Broken",
+        scheduleLines: [{ kind: "INSTALLMENT", days: 30, percentage: 90 }],
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidInstallmentTotalError);
+  });
+
+  it("returns error when a schedule line contains a negative amount or percentage", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePaymentTerm.companyId,
+        name: "Broken",
+        scheduleLines: [{ kind: "INSTALLMENT", days: 30, percentage: -10 }],
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidScheduleLineError);
+  });
+
+  it("returns error when discount cutoff is after the final due date", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompany);
+
+    const result = await run(
+      db,
+      {
+        companyId: basePaymentTerm.companyId,
+        name: "Broken",
+        scheduleLines: [
+          {
+            kind: "NET_DAYS",
+            days: 30,
+            discountDays: 40,
+            discountPercentage: 2,
+            discountBasis: "GROSS_AMOUNT",
+          },
+        ],
+      },
+      commandCtx,
+    );
+
+    expectErr(result, InvalidDiscountConfigurationError);
+  });
+});