@tailor-platform/erp-kit 0.3.0 → 0.4.1

package/src/modules/item-management/command/updateTaxonomyNode.generated.ts

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

package/src/modules/item-management/command/updateTaxonomyNode.ts

@@ -1,10 +1,10 @@
-import { ok, err } from "../../../shared";
 import { Transaction } from "../generated/kysely-tailordb";
 import {
   CodeImmutableError,
   MissingRequiredFieldsError,
   NodeNotFoundError,
 } from "../lib/errors.generated";
+import { ok, err } from "@tailor-platform/erp-kit/module";
 
 export interface UpdateTaxonomyNodeInput {
   id: string;

package/src/modules/item-management/lib/errors.generated.ts

@@ -1,5 +1,5 @@
 // @generated — do not edit
-import { createDomainError } from "../../../shared";
+import { createDomainError } from "@tailor-platform/erp-kit/module";
 
 export const ItemNotFoundError = createDomainError(
   "ItemNotFoundError", "ITEM_MANAGEMENT_ITEM_NOT_FOUND",

package/src/modules/item-management/lib/permissions.generated.ts

@@ -1,5 +1,5 @@
 // @generated — do not edit
-import { definePermissions } from "../../../shared";
+import { definePermissions } from "@tailor-platform/erp-kit/module";
 
 export const { permissions, own, all } = definePermissions("item-management", [
   "activateItem",

package/src/modules/item-management/lib/types.ts

@@ -1,5 +1,10 @@
-import type { InferSchema, Selectable, Insertable, Updateable } from "../../../shared";
 import type { DB } from "../generated/kysely-tailordb";
+import type {
+  InferSchema,
+  Selectable,
+  Insertable,
+  Updateable,
+} from "@tailor-platform/erp-kit/module";
 
 export type Schema = InferSchema<DB>;
 

package/src/modules/item-management/module.ts

@@ -1,5 +1,4 @@
 import { type TailorAnyDBField } from "@tailor-platform/sdk";
-import { type EmptyFields, type FieldsToInsertable } from "../../shared";
 import type { defineModule as definePrimitivesModule } from "../primitives";
 import { createItem } from "./command/createItem.generated";
 import { updateItem } from "./command/updateItem.generated";
@@ -27,6 +26,7 @@ import {
   createItemTaxonomyAssignmentType,
   type CreateItemTaxonomyAssignmentTypeParams,
 } from "./db/itemTaxonomyAssignment";
+import { type EmptyFields, type FieldsToInsertable } from "@tailor-platform/erp-kit/module";
 
 type PrimitivesModule = ReturnType<typeof definePrimitivesModule>;
 type PrimitivesDB = PrimitivesModule["db"];

package/src/modules/item-management/query/calculateNodeDepth.generated.ts

@@ -1,5 +1,5 @@
 // @generated — do not edit
-import { defineQuery } from "../../../shared";
 import { run } from "./calculateNodeDepth";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
 
 export const calculateNodeDepth = defineQuery(run);

package/src/modules/item-management/query/calculateNodeDepth.ts

@@ -1,5 +1,5 @@
-import { ok, type ReadonlyDB } from "../../../shared";
 import type { DB } from "../generated/kysely-tailordb";
+import { ok, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
 
 export interface CalculateNodeDepthInput {
   nodeId: string;

package/src/modules/item-management/query/calculateSubtreeDepth.generated.ts

@@ -1,5 +1,5 @@
 // @generated — do not edit
-import { defineQuery } from "../../../shared";
 import { run } from "./calculateSubtreeDepth";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
 
 export const calculateSubtreeDepth = defineQuery(run);

package/src/modules/item-management/query/calculateSubtreeDepth.ts

@@ -1,5 +1,5 @@
-import { ok, type ReadonlyDB } from "../../../shared";
 import type { DB } from "../generated/kysely-tailordb";
+import { ok, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
 
 export interface CalculateSubtreeDepthInput {
   nodeId: string;

package/src/modules/item-management/query/detectCircularReference.generated.ts

@@ -1,5 +1,5 @@
 // @generated — do not edit
-import { defineQuery } from "../../../shared";
 import { run } from "./detectCircularReference";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
 
 export const detectCircularReference = defineQuery(run);

package/src/modules/item-management/query/detectCircularReference.ts

@@ -1,5 +1,5 @@
-import { ok, type ReadonlyDB } from "../../../shared";
 import type { DB } from "../generated/kysely-tailordb";
+import { ok, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
 
 export interface DetectCircularReferenceInput {
   nodeId: string;

package/src/modules/item-management/query/getItem.generated.ts

@@ -1,5 +1,5 @@
 // @generated — do not edit
-import { defineQuery } from "../../../shared";
 import { run } from "./getItem";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
 
 export const getItem = defineQuery(run);

package/src/modules/item-management/query/getItem.ts

@@ -1,5 +1,5 @@
-import { ok, type ReadonlyDB } from "../../../shared";
 import type { DB } from "../generated/kysely-tailordb";
+import { ok, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
 
 export type GetItemInput = { id: string } | { sku: string } | { barcode: string };
 

package/src/modules/item-management/query/getItemTaxonomyAssignment.generated.ts

@@ -1,5 +1,5 @@
 // @generated — do not edit
-import { defineQuery } from "../../../shared";
 import { run } from "./getItemTaxonomyAssignment";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
 
 export const getItemTaxonomyAssignment = defineQuery(run);

package/src/modules/item-management/query/getItemTaxonomyAssignment.ts

@@ -1,5 +1,5 @@
-import { ok, type ReadonlyDB } from "../../../shared";
 import type { DB } from "../generated/kysely-tailordb";
+import { ok, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
 
 export interface GetItemTaxonomyAssignmentInput {
   itemId: string;

package/src/modules/item-management/query/getTaxonomyNode.generated.ts

@@ -1,5 +1,5 @@
 // @generated — do not edit
-import { defineQuery } from "../../../shared";
 import { run } from "./getTaxonomyNode";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
 
 export const getTaxonomyNode = defineQuery(run);

package/src/modules/item-management/query/getTaxonomyNode.ts

@@ -1,5 +1,5 @@
-import { ok, type ReadonlyDB } from "../../../shared";
 import type { DB } from "../generated/kysely-tailordb";
+import { ok, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
 
 export type GetTaxonomyNodeInput = { id: string } | { code: string };
 

package/src/modules/item-management/query/getTaxonomyNodeAssignments.generated.ts

@@ -1,5 +1,5 @@
 // @generated — do not edit
-import { defineQuery } from "../../../shared";
 import { run } from "./getTaxonomyNodeAssignments";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
 
 export const getTaxonomyNodeAssignments = defineQuery(run);

package/src/modules/item-management/query/getTaxonomyNodeAssignments.ts

@@ -1,5 +1,5 @@
-import { ok, type ReadonlyDB } from "../../../shared";
 import type { DB } from "../generated/kysely-tailordb";
+import { ok, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
 
 export interface GetTaxonomyNodeAssignmentsInput {
   taxonomyNodeId: string;

package/src/modules/item-management/query/getTaxonomyNodeChildren.generated.ts

@@ -1,5 +1,5 @@
 // @generated — do not edit
-import { defineQuery } from "../../../shared";
 import { run } from "./getTaxonomyNodeChildren";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
 
 export const getTaxonomyNodeChildren = defineQuery(run);

package/src/modules/item-management/query/getTaxonomyNodeChildren.ts

@@ -1,5 +1,5 @@
-import { ok, type ReadonlyDB } from "../../../shared";
 import type { DB } from "../generated/kysely-tailordb";
+import { ok, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
 
 export interface GetTaxonomyNodeChildrenInput {
   parentId: string;

package/src/modules/organization/README.md

@@ -0,0 +1,57 @@
+# README
+
+## Overview
+
+The Organization module manages the foundational organizational structure of the ERP system — legal entities (companies), departments, and physical sites. It defines "who we are" and "where we operate" as the structural backbone that all transactional modules reference for scoping and context.
+
+Each company represents a legal entity with its own tax identity, registered address, and base currency assignment. Departments model the internal functional structure within a company, while sites represent the physical facilities (offices, warehouses, stores) where operations take place. Together, these entities provide the multi-company, multi-site foundation that downstream modules (accounting, sales, purchasing, inventory) depend on.
+
+## Key Features
+
+- **[Company Lifecycle](docs/features/company-lifecycle.md)**: Create and manage legal entities with lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE). Companies store legal name, tax ID, registration number, registered address, and base currency assignment. Fiscal calendar is owned by accounting
+- **[Department Management](docs/features/department-management.md)**: Create and manage departments within a company with self-referential hierarchy (parent department), unique code per company, and lifecycle state (ACTIVE/INACTIVE). Manager assignment is deferred to future HR/employee module
+- **[Site Management](docs/features/site-management.md)**: Manage physical sites/facilities owned by a company — offices, warehouses, stores, factories. Each site has a structured address, type classification, country, timezone, and lifecycle state. Warehouse storage layout (zones, bins, aisles) is owned by warehouse modules using separate `Warehouse`/`StorageLocation` entities
+
+## Module Scope
+
+### In Scope
+
+- Company/legal entity master data management (create, update, delete, status transitions)
+- Company lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE)
+- Tax identification number and registration number storage per company
+- Base currency assignment per company (currency master data owned by primitives module; organization stores only the company→currency reference)
+- Department CRUD with hierarchical parent-child structure
+- Department code uniqueness enforcement per company
+- Physical site management with structured addresses
+- Site type classification (office, warehouse, store, factory)
+- Site country and timezone assignment
+
+### Out of Scope
+
+- User account management and authentication (user-management module)
+- Employee profiles, HR attributes, and employment records (future HR/employee module)
+- Department manager assignment — requires employee/worker reference, not user ID (future HR/employee module)
+- Company-to-user membership and role mapping (future organization-membership or HR module)
+- Organizational hierarchy with multiple purposes and effective dates (future enhancement)
+- Business unit and division management for financial reporting (future accounting module)
+- Cost center and profit center management (future accounting module)
+- Fiscal calendar management — fiscal year, periods, cutoff dates (future accounting module)
+- Inter-company transaction configuration (future enhancement)
+- Warehouse storage layout — `Warehouse`/`StorageLocation` with zones, bins, aisles (future warehouse module; references organization `Site`)
+- Business partner addresses — billing, shipping (future business-partner module)
+
+### Scope Decision Rationale
+
+Organization is strictly scoped to **structural identity** — the legal, functional, and physical structure of the business. It answers "which legal entity?", "which department?", and "which site?" without owning any transactional or operational data.
+
+Company/legal entity is the root scoping entity. Nearly every transactional record in the ERP will carry a `companyId` referencing this module. This makes organization a foundational module that should remain stable and simple.
+
+Departments are included because they represent the internal functional structure that many modules reference (cost allocation, approval workflows, reporting). The self-referential hierarchy is sufficient for initial needs; a more flexible multi-purpose hierarchy system can be added later if required.
+
+Sites are included because physical facilities are referenced by inventory (stock holding), sales (ship-from), purchasing (delivery destination), and tax (jurisdiction). Organization owns the site identity and address; warehouse modules own the operational storage layout (`Warehouse`/`StorageLocation`) within a site.
+
+Employee/HR data is excluded because an employee is a business domain entity with its own lifecycle (hiring, termination, leave) that differs from organizational structure. A user account (user-management) is a login identity, an employee is an HR record, and a department membership is a structural assignment — these three concepts must remain separate. Consequently, department manager and company-to-user membership are also deferred: the manager of a department is an employee/worker, not a login identity, and membership requires an employee concept that this module does not own.
+
+## Module Dependencies
+
+- [primitives](../primitives/README.md) — Currency definitions for company base currency assignment

package/src/modules/organization/command/activateCompany.generated.ts

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

package/src/modules/organization/command/activateCompany.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CompanyNotFoundError,
+  InvalidStateError,
+  MissingRequiredFieldsError,
+  InvalidBaseCurrencyError,
+} from "../lib/errors.generated";
+import {
+  draftCompany,
+  activeCompany,
+  inactiveCompany,
+  draftCompanyNoCurrency,
+} from "../testing/fixtures";
+import { getCurrency } from "../../primitives/query/getCurrency.generated";
+import { run } from "./activateCompany";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+const ctx: CommandContext = {
+  actorId: "test-actor",
+  permissions: ["organization:activateCompany"],
+};
+
+const deps = { getCurrency };
+
+describe("activateCompany", () => {
+  it("activates DRAFT company with all required fields", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const activatedCompany = { ...draftCompany, status: "ACTIVE" };
+    spies.select
+      .mockReturnValueOnce(draftCompany) // company lookup
+      .mockReturnValueOnce({ id: "currency-usd", isActive: true }); // getCurrency
+    spies.update.mockReturnValue(activatedCompany);
+
+    const result = await run(db, { companyId: draftCompany.id }, ctx, deps);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.company.status).toBe("ACTIVE");
+    }
+  });
+
+  it("throws when company does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { companyId: "nonexistent" }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CompanyNotFoundError);
+    }
+  });
+
+  it("throws when company is already ACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(activeCompany);
+
+    const result = await run(db, { companyId: activeCompany.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateError);
+    }
+  });
+
+  it("throws when company is INACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(inactiveCompany);
+
+    const result = await run(db, { companyId: inactiveCompany.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateError);
+    }
+  });
+
+  it("throws when legal name is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const companyNoLegalName = { ...draftCompany, legalName: "" };
+    spies.select.mockReturnValueOnce(companyNoLegalName);
+
+    const result = await run(db, { companyId: companyNoLegalName.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldsError);
+    }
+  });
+
+  it("throws when base currency is not assigned", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftCompanyNoCurrency);
+
+    const result = await run(db, { companyId: draftCompanyNoCurrency.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldsError);
+    }
+  });
+
+  it("throws when base currency references a non-existent Currency", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(draftCompany) // company lookup
+      .mockReturnValueOnce(undefined); // getCurrency returns null
+
+    const result = await run(db, { companyId: draftCompany.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidBaseCurrencyError);
+    }
+  });
+
+  it("throws when base currency references an inactive Currency", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(draftCompany) // company lookup
+      .mockReturnValueOnce({ id: "currency-usd", isActive: false }); // getCurrency inactive
+
+    const result = await run(db, { companyId: draftCompany.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidBaseCurrencyError);
+    }
+  });
+
+  it("throws when address street is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const companyNoStreet = { ...draftCompany, street: null };
+    spies.select.mockReturnValueOnce(companyNoStreet);
+
+    const result = await run(db, { companyId: companyNoStreet.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldsError);
+    }
+  });
+
+  it("throws when address city is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const companyNoCity = { ...draftCompany, city: null };
+    spies.select.mockReturnValueOnce(companyNoCity);
+
+    const result = await run(db, { companyId: companyNoCity.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldsError);
+    }
+  });
+
+  it("throws when address postalCode is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const companyNoPostalCode = { ...draftCompany, postalCode: null };
+    spies.select.mockReturnValueOnce(companyNoPostalCode);
+
+    const result = await run(db, { companyId: companyNoPostalCode.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldsError);
+    }
+  });
+
+  it("throws when address country is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const companyNoCountry = { ...draftCompany, country: null };
+    spies.select.mockReturnValueOnce(companyNoCountry);
+
+    const result = await run(db, { companyId: companyNoCountry.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldsError);
+    }
+  });
+});

package/src/modules/organization/command/activateCompany.ts

@@ -0,0 +1,92 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CompanyNotFoundError,
+  InvalidStateError,
+  MissingRequiredFieldsError,
+  InvalidBaseCurrencyError,
+} from "../lib/errors.generated";
+import type { PrimitivesQueries } from "../module";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface ActivateCompanyInput {
+  companyId: string;
+}
+
+/**
+ * Function: activateCompany
+ *
+ * Transitions a company from DRAFT to ACTIVE status, making it available for
+ * transactional modules to reference. All required fields must be configured
+ * before activation.
+ */
+export async function run(
+  db: Transaction,
+  input: ActivateCompanyInput,
+  ctx: CommandContext,
+  primitivesQueries?: Pick<PrimitivesQueries, "getCurrency">,
+) {
+  const { companyId } = input;
+
+  // 1. Find company with forUpdate
+  const existing = await db
+    .selectFrom("Company")
+    .selectAll()
+    .where("id", "=", companyId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!existing) {
+    return err(new CompanyNotFoundError(companyId));
+  }
+
+  // 2. Must be DRAFT
+  if (existing.status !== "DRAFT") {
+    return err(new InvalidStateError(companyId));
+  }
+
+  // 3. Check required fields
+  if (
+    !existing.legalName ||
+    (typeof existing.legalName === "string" && existing.legalName.trim() === "")
+  ) {
+    return err(new MissingRequiredFieldsError(companyId));
+  }
+  if (!existing.baseCurrencyId) {
+    return err(new MissingRequiredFieldsError(companyId));
+  }
+  if (!existing.street) {
+    return err(new MissingRequiredFieldsError(companyId));
+  }
+  if (!existing.city) {
+    return err(new MissingRequiredFieldsError(companyId));
+  }
+  if (!existing.postalCode) {
+    return err(new MissingRequiredFieldsError(companyId));
+  }
+  if (!existing.country) {
+    return err(new MissingRequiredFieldsError(companyId));
+  }
+
+  // 4. Validate base currency exists and is active
+  if (primitivesQueries) {
+    const { currency } = (
+      await primitivesQueries.getCurrency(db, { id: existing.baseCurrencyId }, ctx)
+    ).value;
+    if (!currency?.isActive) {
+      return err(new InvalidBaseCurrencyError(companyId));
+    }
+  }
+
+  // 5. Set status ACTIVE
+  const company = await db
+    .updateTable("Company")
+    .set({
+      status: "ACTIVE",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", companyId)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ company: company! });
+}

package/src/modules/organization/command/createCompany.generated.ts

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