@tailor-platform/erp-kit 0.2.2 → 0.4.0

package/src/modules/audit/testing/fixtures.ts

@@ -0,0 +1,215 @@
+import type {
+  AuditableEntity,
+  AuditPolicy,
+  PolicyFieldRule,
+  AuditEntry,
+  ChangeDetail,
+  Schema,
+} from "../lib/types";
+
+// AuditableEntity fixtures
+export const companyBoundEntity = {
+  id: "entity-1",
+  entityName: "SalesOrder",
+  entityScope: "COMPANY_BOUND",
+  auditableFields: JSON.stringify([
+    { fieldName: "amount", fieldType: "scalar" },
+    { fieldName: "status", fieldType: "scalar" },
+    { fieldName: "customerId", fieldType: "relation" },
+  ]),
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies AuditableEntity<Schema>;
+
+export const globalEntity = {
+  id: "entity-2",
+  entityName: "User",
+  entityScope: "GLOBAL",
+  auditableFields: JSON.stringify([
+    { fieldName: "email", fieldType: "scalar" },
+    { fieldName: "role", fieldType: "scalar" },
+    { fieldName: "isActive", fieldType: "scalar" },
+  ]),
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies AuditableEntity<Schema>;
+
+// AuditPolicy fixtures
+export const draftPolicy = {
+  id: "policy-1",
+  entityName: "SalesOrder",
+  companyId: "company-1",
+  operationType: "UPDATE",
+  status: "DRAFT",
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies AuditPolicy<Schema>;
+
+export const activePolicy = {
+  id: "policy-2",
+  entityName: "SalesOrder",
+  companyId: "company-1",
+  operationType: "UPDATE",
+  status: "ACTIVE",
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies AuditPolicy<Schema>;
+
+export const inactivePolicy = {
+  id: "policy-3",
+  entityName: "SalesOrder",
+  companyId: "company-1",
+  operationType: "UPDATE",
+  status: "INACTIVE",
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies AuditPolicy<Schema>;
+
+export const globalDraftPolicy = {
+  id: "policy-4",
+  entityName: "User",
+  companyId: null,
+  operationType: "CREATE",
+  status: "DRAFT",
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies AuditPolicy<Schema>;
+
+export const globalActivePolicy = {
+  id: "policy-5",
+  entityName: "User",
+  companyId: null,
+  operationType: "CREATE",
+  status: "ACTIVE",
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies AuditPolicy<Schema>;
+
+export const draftReplacementPolicy = {
+  id: "policy-6",
+  entityName: "SalesOrder",
+  companyId: "company-1",
+  operationType: "UPDATE",
+  status: "DRAFT",
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies AuditPolicy<Schema>;
+
+// PolicyFieldRule fixtures
+export const captureFieldRule = {
+  id: "rule-1",
+  auditPolicyId: "policy-2",
+  fieldName: "amount",
+  sensitivityMode: "CAPTURE",
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies PolicyFieldRule<Schema>;
+
+export const maskFieldRule = {
+  id: "rule-2",
+  auditPolicyId: "policy-2",
+  fieldName: "customerId",
+  sensitivityMode: "MASK",
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies PolicyFieldRule<Schema>;
+
+export const hashFieldRule = {
+  id: "rule-3",
+  auditPolicyId: "policy-2",
+  fieldName: "status",
+  sensitivityMode: "HASH",
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies PolicyFieldRule<Schema>;
+
+export const excludeFieldRule = {
+  id: "rule-4",
+  auditPolicyId: "policy-2",
+  fieldName: "amount",
+  sensitivityMode: "EXCLUDE",
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies PolicyFieldRule<Schema>;
+
+// AuditEntry fixtures
+export const baseAuditEntry = {
+  id: "entry-1",
+  eventId: "event-uuid-1",
+  actorType: "USER",
+  actorId: "user-1",
+  entityType: "SalesOrder",
+  entityId: "so-1",
+  operationType: "UPDATE",
+  companyId: "company-1",
+  correlationId: null,
+  ipAddress: null,
+  userAgent: null,
+  sessionId: null,
+  requestId: null,
+  onBehalfOf: null,
+  timestamp: new Date("2024-01-15T10:30:00.000Z"),
+  createdAt: new Date("2024-01-15T10:30:00.000Z"),
+  updatedAt: null,
+} as const satisfies AuditEntry<Schema>;
+
+export const globalAuditEntry = {
+  id: "entry-2",
+  eventId: "event-uuid-2",
+  actorType: "SYSTEM",
+  actorId: "system-job-1",
+  entityType: "User",
+  entityId: "user-2",
+  operationType: "CREATE",
+  companyId: null,
+  correlationId: "corr-uuid-1",
+  ipAddress: "192.168.1.1",
+  userAgent: "AuditBot/1.0",
+  sessionId: "session-1",
+  requestId: "req-1",
+  onBehalfOf: "user-3",
+  timestamp: new Date("2024-01-16T12:00:00.000Z"),
+  createdAt: new Date("2024-01-16T12:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies AuditEntry<Schema>;
+
+// ChangeDetail fixtures
+export const baseChangeDetail = {
+  id: "detail-1",
+  auditEntryId: "entry-1",
+  fieldName: "amount",
+  oldValue: "100.00",
+  newValue: "95.00",
+  createdAt: new Date("2024-01-15T10:30:00.000Z"),
+  updatedAt: null,
+} as const satisfies ChangeDetail<Schema>;
+
+export const maskedChangeDetail = {
+  id: "detail-2",
+  auditEntryId: "entry-1",
+  fieldName: "customerId",
+  oldValue: "***",
+  newValue: "***",
+  createdAt: new Date("2024-01-15T10:30:00.000Z"),
+  updatedAt: null,
+} as const satisfies ChangeDetail<Schema>;
+
+export const excludedChangeDetail = {
+  id: "detail-3",
+  auditEntryId: "entry-1",
+  fieldName: "amount",
+  oldValue: null,
+  newValue: null,
+  createdAt: new Date("2024-01-15T10:30:00.000Z"),
+  updatedAt: null,
+} as const satisfies ChangeDetail<Schema>;
+
+export const createChangeDetail = {
+  id: "detail-4",
+  auditEntryId: "entry-2",
+  fieldName: "email",
+  oldValue: null,
+  newValue: "user@example.com",
+  createdAt: new Date("2024-01-16T12:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies ChangeDetail<Schema>;

package/src/modules/business-partner/README.md

@@ -0,0 +1,60 @@
+# README
+
+## Overview
+
+The Business Partner module manages the master data for all external parties the organization transacts with — suppliers, customers, or both. It provides a unified business partner entity following SAP's Business Partner model, where a single record can hold multiple roles (CUSTOMER, SUPPLIER) without duplication. Each partner is classified by type (ORGANIZATION or INDIVIDUAL), carries its own lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE), and is scoped to a company.
+
+Partners serve as the authoritative counterparty reference for all downstream transactional modules. Sales orders reference a partner as the customer; purchase orders reference a partner as the supplier; accounting entries reference partners for accounts payable and receivable. The module also manages partner-owned sub-entities: addresses (billing, shipping, registered), contact persons (individuals at an organization), bank accounts (for AP/AR payments), and identification documents (tax IDs, VAT numbers, DUNS).
+
+## Key Features
+
+- **[Partner Lifecycle](docs/features/partner-lifecycle.md)**: Unified business partner entity with type distinction (ORGANIZATION/INDIVIDUAL), lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE), and core master data. The central entity that all downstream modules reference as the counterparty
+- **[Partner Address Management](docs/features/partner-address-management.md)**: Multiple addresses per partner with type classification (BILLING, SHIPPING, REGISTERED, OTHER). Structured address format consistent with organization's Site addresses but separately owned for external parties
+- **[Contact Person Management](docs/features/contact-person-management.md)**: Link individual contacts to their parent organization with name, email, phone, job title, and primary contact designation. Contact persons are sub-entities of ORGANIZATION-type partners, distinct from user-management login accounts
+- **[Partner Role Classification](docs/features/partner-role-classification.md)**: Assign roles (CUSTOMER, SUPPLIER) to a partner additively. A single partner can serve multiple roles without record duplication, following SAP's unified BP model
+- **[Partner Bank Account](docs/features/partner-bank-account.md)**: Store partner banking details (bank name, account number, routing, IBAN/SWIFT) for AP/AR payments. Multiple accounts per partner with default designation and currency reference
+- **[Partner Identification](docs/features/partner-identification.md)**: Store tax IDs, VAT numbers, DUNS, company registry numbers, and other identification documents per partner. Supports multiple identification types with optional validity periods
+
+## Module Scope
+
+### In Scope
+
+- Business partner master data management (create, update, delete, status transitions)
+- Partner type distinction (ORGANIZATION and INDIVIDUAL)
+- Partner lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE)
+- Company-scoped partner records (each partner belongs to a company)
+- Multiple addresses per partner with type classification and default designation
+- Contact person management for ORGANIZATION-type partners
+- Role classification (CUSTOMER, SUPPLIER) with additive assignment
+- Bank account storage with default designation and currency reference
+- Identification document storage (tax IDs, VAT, DUNS, etc.) with uniqueness enforcement
+
+### Out of Scope
+
+- Customer relationship management and sales pipeline (CRM module)
+- Lead/prospect qualification and conversion workflows (CRM module)
+- Supplier onboarding workflows with approval gates (`purchase` module)
+- Supplier qualification, certification, and performance scoring (`purchase` module)
+- Supplier catalog — linking suppliers to items they supply (`purchase` module)
+- Payment terms and pricing rules (`payment-terms` module)
+- Duplicate detection and automated merge (future enhancement)
+- Partner portal and self-service capabilities (future enhancement)
+- Activity logging — calls, emails, meetings, notes (CRM module)
+- Know Your Customer (KYC) and sanctions screening workflows (compliance module)
+
+### Scope Decision Rationale
+
+Business-partner is scoped to **external party master data** — the "who we transact with" foundation. It owns the identity, classification, and contact details of every customer, supplier, or dual-role partner the organization deals with. This is separated from internal organizational structure (organization module) because external parties have fundamentally different lifecycles, data requirements, and access patterns than internal entities like companies, departments, and sites.
+
+The unified partner model (one entity with role classification rather than separate Customer and Supplier entities) follows the SAP Business Partner pattern. This prevents duplicate records when the same company is both a customer and a supplier, simplifies address and contact management, and provides a single reference point for downstream modules.
+
+Addresses are included here rather than in the organization module because partner addresses belong to external parties (billing/shipping for customers and suppliers), while organization's Site addresses belong to company-owned facilities. The address structure is consistent across both modules, but ownership and semantics differ.
+
+Contact persons are included because knowing who to communicate with at a partner organization is core master data, not a CRM concern. However, activity tracking (logging calls, meetings, emails) is excluded as CRM functionality.
+
+Supplier catalog (which suppliers provide which items), payment terms, and pricing are excluded because they involve transactional business rules that change at different rates than partner master data. A supplier catalog naturally fits in a purchasing module where it integrates with PO workflows. Payment terms belong in pricing/accounting where they interact with discount rules and installment plans.
+
+## Module Dependencies
+
+- [organization](../organization/README.md) — Company reference for partner scoping (each partner belongs to a company)
+- [primitives](../primitives/README.md) — Currency definitions for bank account currency assignment

package/src/modules/business-partner/command/activatePartner.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { defineCommand } from "../../../shared";
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./activatePartner";
+
+export const activatePartner = defineCommand(permissions.activatePartner, run);

package/src/modules/business-partner/command/activatePartner.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { InvalidStateTransitionError, PartnerNotFoundError } from "../lib/errors.generated";
+import { baseActivePartner, baseDraftPartner, baseInactivePartner } from "../testing/fixtures";
+import { run } from "./activatePartner";
+
+describe("activatePartner", () => {
+  it("activates a DRAFT partner", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const activatedPartner = { ...baseDraftPartner, status: "ACTIVE" };
+    spies.select.mockReturnValueOnce(baseDraftPartner);
+    spies.update.mockReturnValue(activatedPartner);
+
+    const result = await run(db, { id: baseDraftPartner.id });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.partner.status).toBe("ACTIVE");
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("returns error when partner not found", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValue(undefined);
+
+    const result = await run(db, { id: "nonexistent" });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(PartnerNotFoundError);
+    }
+  });
+
+  it("returns error when partner is ACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseActivePartner);
+
+    const result = await run(db, { id: baseActivePartner.id });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateTransitionError);
+    }
+  });
+
+  it("returns error when partner is INACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseInactivePartner);
+
+    const result = await run(db, { id: baseInactivePartner.id });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateTransitionError);
+    }
+  });
+});

package/src/modules/business-partner/command/activatePartner.ts

@@ -0,0 +1,45 @@
+import { ok, err } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { InvalidStateTransitionError, PartnerNotFoundError } from "../lib/errors.generated";
+
+export interface ActivatePartnerInput {
+  id: string;
+  from?: string[];
+}
+
+/**
+ * Function: activatePartner
+ *
+ * Transitions a business partner from DRAFT to ACTIVE status.
+ */
+export async function run(db: Transaction, input: ActivatePartnerInput) {
+  const { id, from } = input;
+
+  // 1. Check partner exists
+  const partner = await db
+    .selectFrom("BusinessPartner")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!partner) {
+    return err(new PartnerNotFoundError(id));
+  }
+
+  // 2. Check status is valid for activation
+  const validFromStatuses = from ?? ["DRAFT"];
+  if (!validFromStatuses.includes(partner.status)) {
+    return err(new InvalidStateTransitionError(`${partner.status} to ACTIVE`));
+  }
+
+  // 3. Update status to ACTIVE
+  const activatedPartner = await db
+    .updateTable("BusinessPartner")
+    .set({ status: "ACTIVE", updatedAt: new Date() })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ partner: activatedPartner });
+}

package/src/modules/business-partner/command/assignRoleToPartner.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { defineCommand } from "../../../shared";
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./assignRoleToPartner";
+
+export const assignRoleToPartner = defineCommand(permissions.assignRoleToPartner, run);

package/src/modules/business-partner/command/assignRoleToPartner.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  PartnerNotFoundError,
+  PartnerNotActiveError,
+  InvalidRoleError,
+} from "../lib/errors.generated";
+import {
+  baseActivePartner,
+  baseDraftPartner,
+  baseInactivePartner,
+  baseCustomerRole,
+  baseSupplierRole,
+} from "../testing/fixtures";
+import { run } from "./assignRoleToPartner";
+
+const ctx: CommandContext = {
+  actorId: "test-actor",
+  permissions: ["business-partner:assignRoleToPartner"],
+};
+
+describe("assignRoleToPartner", () => {
+  it("assigns CUSTOMER to partner with no roles", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseActivePartner); // partner lookup
+    spies.select.mockReturnValueOnce(undefined); // no existing role
+    spies.insert.mockReturnValue({ ...baseCustomerRole, id: "role-new" });
+
+    const result = await run(db, { partnerId: "partner-2", role: "CUSTOMER" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.partnerRole).toBeDefined();
+    }
+  });
+
+  it("assigns SUPPLIER to partner that already holds CUSTOMER", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseActivePartner); // partner lookup
+    spies.select.mockReturnValueOnce(undefined); // no existing SUPPLIER role
+    spies.insert.mockReturnValue({ ...baseSupplierRole, id: "role-new" });
+
+    const result = await run(db, { partnerId: "partner-2", role: "SUPPLIER" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.partnerRole).toBeDefined();
+    }
+  });
+
+  it("idempotent when role already assigned", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseActivePartner); // partner lookup
+    spies.select.mockReturnValueOnce(baseCustomerRole); // existing role found
+
+    const result = await run(db, { partnerId: "partner-2", role: "CUSTOMER" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.partnerRole).toEqual(baseCustomerRole);
+    }
+    expect(spies.insert).not.toHaveBeenCalled();
+  });
+
+  it("returns error when partner not found", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined); // partner not found
+
+    const result = await run(db, { partnerId: "nonexistent", role: "CUSTOMER" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(PartnerNotFoundError);
+    }
+  });
+
+  it("returns error when partner is INACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseInactivePartner); // partner in INACTIVE
+
+    const result = await run(db, { partnerId: "partner-3", role: "CUSTOMER" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(PartnerNotActiveError);
+    }
+  });
+
+  it("returns error when partner is DRAFT", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseDraftPartner); // partner in DRAFT
+
+    const result = await run(db, { partnerId: "partner-1", role: "CUSTOMER" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(PartnerNotActiveError);
+    }
+  });
+
+  it("returns error when role is invalid", async () => {
+    const { db } = createMockDb<Transaction>();
+
+    const result = await run(db, { partnerId: "partner-2", role: "INVALID_ROLE" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidRoleError);
+    }
+  });
+});

package/src/modules/business-partner/command/assignRoleToPartner.ts

@@ -0,0 +1,72 @@
+import { ok, err, type CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  PartnerNotFoundError,
+  PartnerNotActiveError,
+  InvalidRoleError,
+} from "../lib/errors.generated";
+
+type ValidRole = "CUSTOMER" | "SUPPLIER";
+const VALID_ROLES: readonly ValidRole[] = ["CUSTOMER", "SUPPLIER"] as const;
+
+export interface AssignRoleToPartnerInput {
+  partnerId: string;
+  role: string;
+}
+
+/**
+ * Function: assignRoleToPartner
+ *
+ * Assigns a CUSTOMER or SUPPLIER role to an ACTIVE partner. Idempotent —
+ * returns the existing role if already assigned.
+ */
+export async function run(db: Transaction, input: AssignRoleToPartnerInput, _ctx: CommandContext) {
+  const { partnerId, role } = input;
+
+  // 1. Validate role
+  if (!VALID_ROLES.includes(role as ValidRole)) {
+    return err(new InvalidRoleError(role ?? ""));
+  }
+  const validRole = role as ValidRole;
+
+  // 2. Check partner exists and is ACTIVE
+  const partner = await db
+    .selectFrom("BusinessPartner")
+    .selectAll()
+    .where("id", "=", partnerId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!partner) {
+    return err(new PartnerNotFoundError(partnerId));
+  }
+
+  if (partner.status !== "ACTIVE") {
+    return err(new PartnerNotActiveError(partnerId));
+  }
+
+  // 3. Check if role already assigned (idempotent)
+  const existingRole = await db
+    .selectFrom("PartnerRole")
+    .selectAll()
+    .where("partnerId", "=", partnerId)
+    .where("role", "=", validRole)
+    .executeTakeFirst();
+
+  if (existingRole) {
+    return ok({ partnerRole: existingRole });
+  }
+
+  // 4. Create new role
+  const partnerRole = await db
+    .insertInto("PartnerRole")
+    .values({
+      partnerId,
+      role: validRole,
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ partnerRole: partnerRole! });
+}

package/src/modules/business-partner/command/createContactPerson.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { defineCommand } from "../../../shared";
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./createContactPerson";
+
+export const createContactPerson = defineCommand(permissions.createContactPerson, run);