@tailor-platform/erp-kit 0.4.1 → 0.5.1

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

@@ -0,0 +1,104 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unused-vars */
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CurrencyNotFoundError,
+  DuplicateRulePrecedenceError,
+  InvalidEffectiveRangeError,
+  InvalidMinimumQuantityError,
+  InvalidUnitPriceError,
+  ItemNotActiveError,
+  ItemNotFoundError,
+  PriceRuleNotFoundError,
+  UnitNotFoundError,
+} from "../lib/errors.generated";
+import { findRuleConflict, isActiveStatus, selectOne } from "../lib/domain";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface UpdatePurchasePriceRuleInput {
+  id: string;
+  itemId?: string;
+  currencyId?: string;
+  unitId?: string;
+  minimumQuantity?: number;
+  unitPrice?: number;
+  effectiveFrom?: Date;
+  effectiveTo?: Date | null;
+  priority?: number;
+  notes?: string | null;
+}
+
+export async function run(
+  db: Transaction,
+  input: UpdatePurchasePriceRuleInput,
+  ctx: CommandContext,
+) {
+  const existing = await selectOne(db, "PurchasePriceRule", "id", input.id, true);
+  if (!existing) {
+    return err(new PriceRuleNotFoundError(input.id));
+  }
+
+  const itemId = input.itemId ?? (existing.itemId as string);
+  const currencyId = input.currencyId ?? (existing.currencyId as string);
+  const unitId = input.unitId ?? (existing.unitId as string);
+  const minimumQuantity = input.minimumQuantity ?? (existing.minimumQuantity as number);
+  const unitPrice = input.unitPrice ?? (existing.unitPrice as number);
+  const effectiveFrom = input.effectiveFrom ?? (existing.effectiveFrom as Date);
+  const effectiveTo =
+    input.effectiveTo === undefined
+      ? ((existing.effectiveTo as Date | null) ?? null)
+      : input.effectiveTo;
+
+  const item = await selectOne(db, "Item", "id", itemId);
+  if (!item) {
+    return err(new ItemNotFoundError(itemId));
+  }
+  if (!isActiveStatus(item.status as string | null)) {
+    return err(new ItemNotActiveError(itemId));
+  }
+  if (!(await selectOne(db, "Currency", "id", currencyId))) {
+    return err(new CurrencyNotFoundError(currencyId));
+  }
+  if (!(await selectOne(db, "Unit", "id", unitId))) {
+    return err(new UnitNotFoundError(unitId));
+  }
+  if (unitPrice <= 0) {
+    return err(new InvalidUnitPriceError(String(unitPrice)));
+  }
+  if (minimumQuantity < 0) {
+    return err(new InvalidMinimumQuantityError(String(minimumQuantity)));
+  }
+  if (effectiveTo && effectiveTo < effectiveFrom) {
+    return err(new InvalidEffectiveRangeError(input.id));
+  }
+
+  const conflictingRule = await findRuleConflict(db, {
+    itemId,
+    currencyId,
+    unitId,
+    minimumQuantity,
+    effectiveFrom,
+  });
+  if (conflictingRule && conflictingRule.id !== input.id) {
+    return err(new DuplicateRulePrecedenceError(input.id));
+  }
+
+  const purchasePriceRule = await db
+    .updateTable("PurchasePriceRule")
+    .set({
+      itemId,
+      currencyId,
+      unitId,
+      minimumQuantity,
+      unitPrice,
+      effectiveFrom,
+      effectiveTo,
+      priority: input.priority ?? existing.priority,
+      notes: input.notes === undefined ? existing.notes : input.notes,
+      updatedAt: new Date(),
+    })
+    .where("id", "=", input.id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ purchasePriceRule });
+}

package/src/modules/purchase/db/goodsReceipt.ts

@@ -0,0 +1,62 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { businessPartner as businessPartnerStub, company as companyStub } from "../lib/_db_deps";
+import { purchaseOrder } from "./purchaseOrder";
+
+export const GOODS_RECEIPT_STATUSES: [string, string, string] = ["DRAFT", "POSTED", "CANCELLED"];
+
+export interface CreateGoodsReceiptTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  companyType?: TailorAnyDBType;
+  supplierType?: TailorAnyDBType;
+  purchaseOrderType?: TailorAnyDBType;
+}
+
+export function createGoodsReceiptType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateGoodsReceiptTypeParams<F>,
+) {
+  return db
+    .type("GoodsReceipt", {
+      companyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.companyType ?? companyStub },
+          backward: "goodsReceipts",
+        })
+        .description("Foreign key to Company"),
+      supplierId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.supplierType ?? businessPartnerStub },
+          backward: "goodsReceipts",
+        })
+        .description("Foreign key to supplier BusinessPartner"),
+      purchaseOrderId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.purchaseOrderType ?? purchaseOrder },
+          backward: "goodsReceipts",
+        })
+        .description("Foreign key to PurchaseOrder"),
+      receiptDate: db.date().description("Receipt document date"),
+      status: db.enum(GOODS_RECEIPT_STATUSES).description("Goods-receipt lifecycle status"),
+      lines: db.string().description("Serialized receipt-line collection"),
+      inventoryHandoff: db
+        .string({ optional: true })
+        .description("Serialized inbound inventory handoff payload"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const goodsReceipt = createGoodsReceiptType({});

package/src/modules/purchase/db/purchaseBill.ts

@@ -0,0 +1,74 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { businessPartner as businessPartnerStub, company as companyStub } from "../lib/_db_deps";
+
+export const PURCHASE_BILL_STATUSES: [string, string, string, string] = [
+  "DRAFT",
+  "BLOCKED",
+  "MATCHED",
+  "CANCELLED",
+];
+
+export interface CreatePurchaseBillTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  companyType?: TailorAnyDBType;
+  supplierType?: TailorAnyDBType;
+}
+
+export function createPurchaseBillType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreatePurchaseBillTypeParams<F>,
+) {
+  return db
+    .type("PurchaseBill", {
+      companyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.companyType ?? companyStub },
+          backward: "purchaseBills",
+        })
+        .description("Foreign key to Company"),
+      supplierId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.supplierType ?? businessPartnerStub },
+          backward: "purchaseBills",
+        })
+        .description("Foreign key to supplier BusinessPartner"),
+      invoiceNumber: db.string().description("Supplier invoice number"),
+      invoiceDate: db.date().description("Supplier invoice date"),
+      status: db.enum(PURCHASE_BILL_STATUSES).description("Purchase-bill lifecycle status"),
+      lines: db.string().description("Serialized purchase-bill line collection"),
+      paymentTermSnapshot: db
+        .string({ optional: true })
+        .description("Serialized immutable payment-term snapshot"),
+      supplierTaxIdentification: db
+        .string({ optional: true })
+        .description("Snapshotted supplier tax identification"),
+      matchingMode: db.string({ optional: true }).description("Recorded matching mode"),
+      varianceReason: db.string({ optional: true }).description("Blocked variance reason"),
+      releaseReason: db.string({ optional: true }).description("Release override reason"),
+      dueSchedule: db.string({ optional: true }).description("Serialized payable due schedule"),
+      downstreamAccepted: db
+        .bool()
+        .description("Whether downstream AP or accounting accepted the handoff"),
+      comparisonEvidence: db
+        .string({ optional: true })
+        .description("Serialized matching evidence and comparison basis"),
+      billReadyHandoff: db
+        .string({ optional: true })
+        .description("Serialized downstream bill-ready handoff"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const purchaseBill = createPurchaseBillType({});

package/src/modules/purchase/db/purchaseOrder.ts

@@ -0,0 +1,100 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import {
+  businessPartner as businessPartnerStub,
+  company as companyStub,
+  site as siteStub,
+} from "../lib/_db_deps";
+import { purchasePaymentTerm } from "./purchasePaymentTerm";
+
+export const PURCHASE_ORDER_STATUSES: [
+  string,
+  string,
+  string,
+  string,
+  string,
+  string,
+  string,
+  string,
+  string,
+] = [
+  "DRAFT",
+  "SUBMITTED",
+  "ORDERED",
+  "PARTIALLY_RECEIVED",
+  "RECEIVED",
+  "PARTIALLY_BILLED",
+  "BILLED",
+  "CANCELLED",
+  "CLOSED",
+];
+
+export interface CreatePurchaseOrderTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  companyType?: TailorAnyDBType;
+  supplierType?: TailorAnyDBType;
+  siteType?: TailorAnyDBType;
+  paymentTermType?: TailorAnyDBType;
+}
+
+export function createPurchaseOrderType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreatePurchaseOrderTypeParams<F>,
+) {
+  return db
+    .type("PurchaseOrder", {
+      companyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.companyType ?? companyStub },
+          backward: "purchaseOrders",
+        })
+        .description("Foreign key to Company"),
+      supplierId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.supplierType ?? businessPartnerStub },
+          backward: "purchaseOrders",
+        })
+        .description("Foreign key to supplier BusinessPartner"),
+      documentReceivingSiteId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: params.siteType ?? siteStub },
+          backward: "purchaseOrders",
+        })
+        .description("Optional document-level receiving Site"),
+      paymentTermId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: params.paymentTermType ?? purchasePaymentTerm },
+          backward: "purchaseOrders",
+        })
+        .description("Optional selected PurchasePaymentTerm"),
+      status: db.enum(PURCHASE_ORDER_STATUSES).description("Purchase-order lifecycle status"),
+      orderDate: db.date().description("Purchase-order document date"),
+      externalSupplierOrderReference: db
+        .string({ optional: true })
+        .description("Optional external supplier order reference"),
+      lines: db.string().description("Serialized purchase-order line collection"),
+      paymentTermSnapshot: db
+        .string({ optional: true })
+        .description("Serialized immutable payment-term snapshot"),
+      rejectionReason: db.string({ optional: true }).description("Latest rejection reason"),
+      closeReason: db.string({ optional: true }).description("Close or write-off reason"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const purchaseOrder = createPurchaseOrderType({});

package/src/modules/purchase/db/purchasePaymentTerm.ts

@@ -0,0 +1,46 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { company as companyStub } from "../lib/_db_deps";
+
+export const PURCHASE_PAYMENT_TERM_STATUSES: [string, string] = ["ACTIVE", "INACTIVE"];
+
+export interface CreatePurchasePaymentTermTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  companyType?: TailorAnyDBType;
+}
+
+export function createPurchasePaymentTermType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreatePurchasePaymentTermTypeParams<F>,
+) {
+  return db
+    .type("PurchasePaymentTerm", {
+      companyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.companyType ?? companyStub },
+          backward: "purchasePaymentTerms",
+        })
+        .description("Foreign key to Company"),
+      name: db.string().description("Payment-term display name"),
+      code: db.string({ optional: true }).description("Optional payment-term code"),
+      status: db
+        .enum(PURCHASE_PAYMENT_TERM_STATUSES)
+        .description("Lifecycle status: ACTIVE, INACTIVE"),
+      scheduleLines: db
+        .string()
+        .description("Serialized schedule-line definition for payable scheduling"),
+      notes: db.string({ optional: true }).description("Optional descriptive notes"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const purchasePaymentTerm = createPurchasePaymentTermType({});

package/src/modules/purchase/db/purchasePriceList.ts

@@ -0,0 +1,53 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { businessPartner as businessPartnerStub, company as companyStub } from "../lib/_db_deps";
+
+export const PURCHASE_PRICE_LIST_STATUSES: [string, string] = ["ACTIVE", "INACTIVE"];
+
+export interface CreatePurchasePriceListTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  companyType?: TailorAnyDBType;
+  supplierType?: TailorAnyDBType;
+}
+
+export function createPurchasePriceListType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreatePurchasePriceListTypeParams<F>,
+) {
+  return db
+    .type("PurchasePriceList", {
+      companyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.companyType ?? companyStub },
+          backward: "purchasePriceLists",
+        })
+        .description("Foreign key to Company"),
+      supplierId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.supplierType ?? businessPartnerStub },
+          backward: "purchasePriceLists",
+        })
+        .description("Foreign key to supplier BusinessPartner"),
+      name: db.string().description("Price-list display name"),
+      code: db.string({ optional: true }).description("Optional price-list code"),
+      priority: db.int().description("Deterministic list priority within supplier scope"),
+      status: db
+        .enum(PURCHASE_PRICE_LIST_STATUSES)
+        .description("Lifecycle status: ACTIVE, INACTIVE"),
+      notes: db.string({ optional: true }).description("Optional descriptive notes"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const purchasePriceList = createPurchasePriceListType({});

package/src/modules/purchase/db/purchasePriceRule.ts

@@ -0,0 +1,74 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { currency as currencyStub, item as itemStub, unit as unitStub } from "../lib/_db_deps";
+import { purchasePriceList } from "./purchasePriceList";
+
+export const PURCHASE_PRICE_RULE_STATUSES: [string, string] = ["ACTIVE", "INACTIVE"];
+
+export interface CreatePurchasePriceRuleTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  priceListType?: TailorAnyDBType;
+  itemType?: TailorAnyDBType;
+  currencyType?: TailorAnyDBType;
+  unitType?: TailorAnyDBType;
+}
+
+export function createPurchasePriceRuleType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreatePurchasePriceRuleTypeParams<F>,
+) {
+  return db
+    .type("PurchasePriceRule", {
+      priceListId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.priceListType ?? purchasePriceList },
+          backward: "purchasePriceRules",
+        })
+        .description("Foreign key to PurchasePriceList"),
+      itemId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.itemType ?? itemStub },
+          backward: "purchasePriceRules",
+        })
+        .description("Foreign key to Item"),
+      currencyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.currencyType ?? currencyStub },
+          backward: "purchasePriceRules",
+        })
+        .description("Foreign key to Currency"),
+      unitId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.unitType ?? unitStub },
+          backward: "purchasePriceRules",
+        })
+        .description("Foreign key to Unit"),
+      minimumQuantity: db.float().description("Minimum quantity break for this rule"),
+      unitPrice: db.float().description("Rule price per purchase unit"),
+      effectiveFrom: db.date().description("Rule effective start date"),
+      effectiveTo: db.date({ optional: true }).description("Optional effective end date"),
+      priority: db.int().description("Deterministic rule priority within the list"),
+      status: db
+        .enum(PURCHASE_PRICE_RULE_STATUSES)
+        .description("Lifecycle status: ACTIVE, INACTIVE"),
+      notes: db.string({ optional: true }).description("Optional descriptive notes"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const purchasePriceRule = createPurchasePriceRuleType({});

package/src/modules/purchase/db/supplierProfile.ts

@@ -0,0 +1,59 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { businessPartner as businessPartnerStub, company as companyStub } from "../lib/_db_deps";
+import { purchasePaymentTerm } from "./purchasePaymentTerm";
+
+export interface CreateSupplierProfileTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  companyType?: TailorAnyDBType;
+  supplierType?: TailorAnyDBType;
+  paymentTermType?: TailorAnyDBType;
+}
+
+export function createSupplierProfileType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateSupplierProfileTypeParams<F>,
+) {
+  return db
+    .type("SupplierProfile", {
+      companyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.companyType ?? companyStub },
+          backward: "supplierProfiles",
+        })
+        .description("Foreign key to Company"),
+      supplierId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.supplierType ?? businessPartnerStub },
+          backward: "supplierProfiles",
+        })
+        .description("Foreign key to supplier BusinessPartner"),
+      defaultPurchasePaymentTermId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: params.paymentTermType ?? purchasePaymentTerm },
+          backward: "supplierProfiles",
+        })
+        .description("Optional default PurchasePaymentTerm"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .indexes({
+      fields: ["companyId", "supplierId"],
+      unique: true,
+      name: "supplier_profile_company_supplier_unique_idx",
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const supplierProfile = createSupplierProfileType({});

package/src/modules/purchase/docs/commands/ActivatePurchasePaymentTerm.md

@@ -0,0 +1,39 @@
+# ActivatePurchasePaymentTerm
+
+## Overview
+
+ActivatePurchasePaymentTerm re-enables a previously deactivated payment term so it can default onto new purchase orders and supplier bills again.
+
+## Business Rules
+
+- Target payment term must exist
+- Activating an already active payment term returns success without changing state
+- The term's schedule definition must still be internally valid at activation time
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B{Payment term exists?}
+    B -->|No| C[Return PAYMENT_TERM_NOT_FOUND]
+    B -->|Yes| D{Already active?}
+    D -->|Yes| E[Return success with no-op]
+    D -->|No| F[Set status to ACTIVE]
+    F --> G[Return activated term]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PAYMENT_TERM_NOT_FOUND**: Target payment term does not exist
+- **INVALID_TERM_CONFIGURATION**: Term definition is no longer valid for activation
+
+## Test Cases
+
+- activates an inactive payment term
+- returns success when the payment term is already active
+- returns error when payment term does not exist
+- returns error when the payment term schedule is invalid at activation time

package/src/modules/purchase/docs/commands/ActivatePurchasePriceList.md

@@ -0,0 +1,37 @@
+# ActivatePurchasePriceList
+
+## Overview
+
+ActivatePurchasePriceList re-enables a previously retired supplier price list so its active rules can participate in new purchase price resolution.
+
+## Business Rules
+
+- Target price list must exist
+- Activating an already active list returns success without changing state
+- Reactivated lists do not alter historical order snapshots
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B{Price list exists?}
+    B -->|No| C[Return PRICE_LIST_NOT_FOUND]
+    B -->|Yes| D{Already active?}
+    D -->|Yes| E[Return success with no-op]
+    D -->|No| F[Set status to ACTIVE]
+    F --> G[Return activated list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRICE_LIST_NOT_FOUND**: Target price list does not exist
+
+## Test Cases
+
+- activates an inactive price list
+- returns success when the list is already active
+- returns error when price list does not exist