@tailor-platform/erp-kit 0.2.1 → 0.3.0

package/src/modules/primitives/query/listUnitsByCategory.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { baseUnitKg, baseUnitGram, baseUnitPound } from "../testing/fixtures";
+import { run } from "./listUnitsByCategory";
+
+describe("listUnitsByCategory", () => {
+  it("returns paginated units with default page size", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([baseUnitKg, baseUnitGram]);
+
+    const result = await run(db, { categoryId: "category-1" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([baseUnitKg, baseUnitGram]);
+      expect(result.value.hasNextPage).toBe(false);
+    }
+  });
+
+  it("returns hasNextPage true when more results exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    // Simulate limit+1 rows returned (3 rows for limit=2)
+    spies.select.mockReturnValue([baseUnitKg, baseUnitGram, baseUnitPound]);
+
+    const result = await run(db, { categoryId: "category-1", limit: 2 });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toHaveLength(2);
+      expect(result.value.hasNextPage).toBe(true);
+    }
+  });
+
+  it("returns empty result when no units match", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([]);
+
+    const result = await run(db, { categoryId: "nonexistent" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([]);
+      expect(result.value.hasNextPage).toBe(false);
+    }
+  });
+
+  it("respects custom limit and offset", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([baseUnitGram]);
+
+    const result = await run(db, {
+      categoryId: "category-1",
+      limit: 1,
+      offset: 1,
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([baseUnitGram]);
+      expect(result.value.hasNextPage).toBe(false);
+    }
+  });
+
+  it("accepts orderBy and orderDirection", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([baseUnitGram, baseUnitKg]);
+
+    const result = await run(db, {
+      categoryId: "category-1",
+      orderBy: "name",
+      orderDirection: "desc",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([baseUnitGram, baseUnitKg]);
+    }
+  });
+});

package/src/modules/primitives/query/listUnitsByCategory.ts

@@ -1,16 +1,32 @@
-import type { ReadonlyDB } from "../../shared/internal";
+import {
+  ok,
+  type ReadonlyDB,
+  type PaginationInput,
+  buildPaginatedResult,
+  DEFAULT_PAGE_SIZE,
+} from "../../../shared";
 import type { DB } from "../generated/kysely-tailordb";
 
-export interface ListUnitsByCategoryInput {
+type UnitOrderByField = "name" | "symbol" | "createdAt";
+
+export interface ListUnitsByCategoryInput extends PaginationInput<UnitOrderByField> {
   categoryId: string;
 }
 
 export async function run(db: ReadonlyDB<DB>, input: ListUnitsByCategoryInput) {
+  const limit = input.limit ?? DEFAULT_PAGE_SIZE;
+  const offset = input.offset ?? 0;
+  const orderBy = input.orderBy ?? "id";
+  const orderDirection = input.orderDirection ?? "asc";
+
   const units = await db
     .selectFrom("Unit")
     .selectAll()
     .where("categoryId", "=", input.categoryId)
+    .orderBy(orderBy, orderDirection)
+    .limit(limit + 1)
+    .offset(offset)
     .execute();
 
-  return { units };
+  return ok(buildPaginatedResult(units, limit));
 }

package/src/modules/primitives/tailor.config.ts

@@ -1,11 +1,13 @@
-import { defineConfig, defineGenerators } from "@tailor-platform/sdk";
+import { defineConfig, definePlugins } from "@tailor-platform/sdk";
+import { kyselyTypePlugin } from "@tailor-platform/sdk/plugin/kysely-type";
+import { enumConstantsPlugin } from "@tailor-platform/sdk/plugin/enum-constants";
 
 export default defineConfig({
   name: "primitives",
   db: { "main-db": { files: [`./db/*.ts`] } },
 });
 
-export const generators = defineGenerators(
-  ["@tailor-platform/kysely-type", { distPath: `./generated/kysely-tailordb.ts` }],
-  ["@tailor-platform/enum-constants", { distPath: "./generated/enums.ts" }],
+export const plugins = definePlugins(
+  kyselyTypePlugin({ distPath: `./generated/kysely-tailordb.ts` }),
+  enumConstantsPlugin({ distPath: "./generated/enums.ts" }),
 );

package/src/modules/primitives/tailor.d.ts

@@ -0,0 +1,13 @@
+// This file is auto-generated by @tailor-platform/sdk
+// Do not edit this file manually
+// Regenerated automatically when running 'tailor-sdk apply' or 'tailor-sdk generate'
+
+declare module "@tailor-platform/sdk" {
+  interface AttributeMap {}
+  interface AttributeList {
+    __tuple?: [];
+  }
+  interface Env {}
+}
+
+export {};

package/src/modules/product-management/README.md

@@ -0,0 +1,52 @@
+# README
+
+## Overview
+
+The Product Management module serves as the Product Information Management (PIM) layer of the ERP system. It manages products, attributes, and variant generation. A product defines the commercial representation of a product — its name, description, attributes, and category classification. Variants are generated from attribute value combinations (e.g., Color × Size) and materialize as Items in the item-management module.
+
+## Key Features
+
+- **[Product Lifecycle](docs/features/product-lifecycle.md)**: Create, update, and manage products with lifecycle state machine (DRAFT → ACTIVE ↔ ARCHIVED). Products define the commercial view of a product and serve as the parent entity for variant generation
+- **[Attribute Management](docs/features/attribute-management.md)**: Define attributes and their values. All attributes are variant axes that drive variant generation
+- **[Variant Generation](docs/features/variant-generation.md)**: Generate product variants from attribute value combinations on a product. Each generated variant creates an Item in item-management with auto-generated SKU and inherited properties
+- **[Product Category](docs/features/product-category.md)**: Hierarchical category tree for product classification (many-to-many). Separate from item-management's taxonomy — categories organize the commercial/marketing view of products
+
+## Module Scope
+
+### In Scope
+
+- Product master data management (create, update, delete, status transitions)
+- Product lifecycle state machine (DRAFT → ACTIVE ↔ ARCHIVED)
+- Attribute definitions with predefined values
+- Variant generation from attribute value combinations
+- Item creation in item-management upon variant generation
+- Hierarchical product category management
+- Product-to-category classification (many-to-many)
+
+### Out of Scope
+
+- SKU-level item management and item lifecycle (item-management module)
+- Unit of measure definitions (primitives module)
+- Sales pricing, price lists, and discount rules (pricing module)
+- Channel/marketplace definitions and listing management (sales-channel module)
+- Inventory tracking and stock levels (inventory module)
+- Product images and digital asset management
+- Supplier-specific product information (supplier-management module)
+- Bill of Materials (manufacturing module)
+
+### Scope Decision Rationale
+
+This module focuses on the **commercial definition** of products — the "what we sell" perspective — while delegating operational concerns to specialized modules. Product-management owns the template layer (attributes, variants, categories) because these define the product's identity and structure before it enters any operational workflow.
+
+SKU-level management belongs to item-management because items have their own lifecycle and are the transactional entity referenced by sales, purchasing, and inventory. Variant generation bridges the two: product-management defines the combinations, but the resulting items live in item-management. This separation ensures that changes to product templates don't directly affect in-flight transactions.
+
+Pricing is excluded because prices are context-dependent — they vary by customer segment, quantity tier, date range, and promotional rules. A single product can have dozens of price points that change frequently, while the product definition itself is stable. Embedding pricing here would force product-management to understand sales contexts it shouldn't own. A dedicated pricing module can attach price lists to items independently and evolve its discount/tier logic without touching the product catalog.
+
+Channel/marketplace management is excluded because listing a product on a sales channel involves channel-specific data (listing status, channel fees, fulfillment rules, channel-specific descriptions) that are not part of the product's core identity. A product's definition is channel-agnostic — the same product may be listed differently on each channel. Coupling channels to product-management would create a dependency on external marketplace APIs and business rules that change per channel integration.
+
+Inventory and supplier data are similarly excluded because they follow independent business rules and change at different rates than product definitions.
+
+## Module Dependencies
+
+- [item-management](../item-management/README.md) — Variant generation creates Items via item-management commands
+- [primitives](../primitives/README.md) — UoM definitions inherited by generated Items

package/src/modules/product-management/command/activateProduct.generated.ts

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

package/src/modules/product-management/command/activateProduct.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { InvalidStateTransitionError, ProductNotFoundError } from "../lib/errors.generated";
+import { baseActiveProduct, baseDraftProduct } from "../testing/fixtures";
+import { run } from "./activateProduct";
+
+describe("activateProduct", () => {
+  it("returns error when product not found", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+    const result = await run(db, { id: "nonexistent" });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ProductNotFoundError);
+    }
+  });
+
+  it("returns error when not in DRAFT status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce({ ...baseActiveProduct });
+    const result = await run(db, { id: "product-2" });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateTransitionError);
+    }
+  });
+
+  it("activates DRAFT product to ACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const activated = { ...baseDraftProduct, status: "ACTIVE" };
+    spies.select.mockReturnValueOnce({ ...baseDraftProduct });
+    spies.update.mockReturnValueOnce(activated);
+    const result = await run(db, { id: "product-1" });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.product.status).toBe("ACTIVE");
+    }
+  });
+});

package/src/modules/product-management/command/activateProduct.ts

@@ -0,0 +1,42 @@
+import { ok, err } from "../../../shared";
+import { Transaction } from "../generated/kysely-tailordb";
+import { ProductNotFoundError, InvalidStateTransitionError } from "../lib/errors.generated";
+
+export interface ActivateProductInput {
+  id: string;
+  from?: string[];
+}
+
+/**
+ * Function: activateProduct
+ *
+ * Transitions a product from DRAFT to ACTIVE.
+ */
+export async function run(db: Transaction, input: ActivateProductInput) {
+  const { id } = input;
+  const validFrom = input.from ?? ["DRAFT"];
+
+  const product = await db
+    .selectFrom("Product")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!product) {
+    return err(new ProductNotFoundError(id));
+  }
+
+  if (!validFrom.includes(product.status)) {
+    return err(new InvalidStateTransitionError(id));
+  }
+
+  const updated = await db
+    .updateTable("Product")
+    .set({ status: "ACTIVE", updatedAt: new Date() })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ product: updated! });
+}

package/src/modules/product-management/command/assignProductToCategory.generated.ts

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

package/src/modules/product-management/command/assignProductToCategory.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { baseActiveProduct, baseChildCategory, baseCategoryAssignment } from "../testing/fixtures";
+import { ProductNotFoundError, CategoryNotFoundError } from "../lib/errors.generated";
+import type { AssignProductToCategoryInput } from "./assignProductToCategory";
+import { run } from "./assignProductToCategory";
+
+describe("assignProductToCategory", () => {
+  it("should return ProductNotFoundError when product does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    // getProduct -> null
+    spies.select.mockReturnValueOnce(undefined);
+    const input: AssignProductToCategoryInput = {
+      productId: "non-existent",
+      categoryId: baseChildCategory.id,
+    };
+    const result = await run(db, input);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ProductNotFoundError);
+    }
+  });
+
+  it("should return CategoryNotFoundError when category does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    // 1st select: getProduct -> found
+    spies.select.mockReturnValueOnce(baseActiveProduct);
+    // 2nd select: getProductCategory -> null
+    spies.select.mockReturnValueOnce(undefined);
+    const input: AssignProductToCategoryInput = {
+      productId: baseActiveProduct.id,
+      categoryId: "non-existent",
+    };
+    const result = await run(db, input);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CategoryNotFoundError);
+    }
+  });
+
+  it("should create assignment successfully", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    // 1st select: getProduct -> found
+    spies.select.mockReturnValueOnce(baseActiveProduct);
+    // 2nd select: getProductCategory -> found
+    spies.select.mockReturnValueOnce(baseChildCategory);
+    // 3rd select: getProductCategoryAssignment -> null (no existing)
+    spies.select.mockReturnValueOnce(undefined);
+    // insert returns new assignment
+    const newAssignment = {
+      ...baseCategoryAssignment,
+      id: "new-assign-id",
+      productId: baseActiveProduct.id,
+      categoryId: baseChildCategory.id,
+    };
+    spies.insert.mockReturnValueOnce(newAssignment);
+
+    const input: AssignProductToCategoryInput = {
+      productId: baseActiveProduct.id,
+      categoryId: baseChildCategory.id,
+    };
+    const result = await run(db, input);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.assignment).toEqual(newAssignment);
+    }
+  });
+
+  it("should return existing assignment when already assigned (idempotent)", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    // 1st select: getProduct -> found
+    spies.select.mockReturnValueOnce(baseActiveProduct);
+    // 2nd select: getProductCategory -> found
+    spies.select.mockReturnValueOnce(baseChildCategory);
+    // 3rd select: getProductCategoryAssignment -> existing
+    spies.select.mockReturnValueOnce(baseCategoryAssignment);
+
+    const input: AssignProductToCategoryInput = {
+      productId: baseActiveProduct.id,
+      categoryId: baseChildCategory.id,
+    };
+    const result = await run(db, input);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.assignment).toEqual(baseCategoryAssignment);
+    }
+    expect(spies.insert).not.toHaveBeenCalled();
+  });
+});

package/src/modules/product-management/command/assignProductToCategory.ts

@@ -0,0 +1,62 @@
+import { ok, err } from "../../../shared";
+import { Transaction } from "../generated/kysely-tailordb";
+import { ProductNotFoundError, CategoryNotFoundError } from "../lib/errors.generated";
+
+export interface AssignProductToCategoryInput {
+  productId: string;
+  categoryId: string;
+}
+
+/**
+ * Function: assignProductToCategory
+ *
+ * Assigns a product to a category. Idempotent.
+ */
+export async function run(db: Transaction, input: AssignProductToCategoryInput) {
+  const { productId, categoryId } = input;
+
+  // Validate product exists
+  const product = await db
+    .selectFrom("Product")
+    .select("id")
+    .where("id", "=", productId)
+    .executeTakeFirst();
+  if (!product) {
+    return err(new ProductNotFoundError(productId));
+  }
+
+  // Validate category exists
+  const category = await db
+    .selectFrom("ProductCategory")
+    .select("id")
+    .where("id", "=", categoryId)
+    .executeTakeFirst();
+  if (!category) {
+    return err(new CategoryNotFoundError(categoryId));
+  }
+
+  // Check if already assigned (idempotent, with lock for uniqueness)
+  const existing = await db
+    .selectFrom("ProductCategoryAssignment")
+    .selectAll()
+    .where("productId", "=", productId)
+    .where("categoryId", "=", categoryId)
+    .forUpdate()
+    .executeTakeFirst();
+  if (existing) {
+    return ok({ assignment: existing });
+  }
+
+  const assignment = await db
+    .insertInto("ProductCategoryAssignment")
+    .values({
+      productId,
+      categoryId,
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ assignment });
+}

package/src/modules/product-management/command/createProduct.generated.ts

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

package/src/modules/product-management/command/createProduct.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { CommandContext } from "../../../shared";
+import type { GetUnitInput } from "../../primitives/query/getUnit";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  DuplicateCodeError,
+  InvalidUomError,
+  MissingRequiredFieldError,
+} from "../lib/errors.generated";
+import { baseDraftProduct } from "../testing/fixtures";
+import { run } from "./createProduct";
+
+describe("createProduct", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["product-management:createProduct"],
+  };
+
+  const baseUnit = {
+    id: "unit-pcs",
+    symbol: "pcs",
+    name: "Pieces",
+    roundingPrecision: 0,
+    isActive: true,
+    createdAt: new Date("2024-01-01"),
+    updatedAt: null,
+    categoryId: "uom-cat-1",
+    conversionFactor: 1,
+  };
+
+  const mockGetUnit = (_db: unknown, input: GetUnitInput) =>
+    Promise.resolve({
+      ok: true as const,
+      value: {
+        unit: "id" in input && input.id === "unit-pcs" ? baseUnit : null,
+      },
+    });
+  const primitivesQueries = { getUnit: mockGetUnit };
+
+  it("returns error when code is empty", async () => {
+    const { db } = createMockDb<Transaction>();
+    const result = await run(
+      db,
+      { code: "", name: "Test", unitId: "unit-pcs" },
+      ctx,
+      primitivesQueries,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldError);
+    }
+  });
+
+  it("returns error when name is empty", async () => {
+    const { db } = createMockDb<Transaction>();
+    const result = await run(
+      db,
+      { code: "PROD-1", name: "", unitId: "unit-pcs" },
+      ctx,
+      primitivesQueries,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldError);
+    }
+  });
+
+  it("returns error when code already exists", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    // getProduct select returns existing product
+    spies.select.mockReturnValueOnce(baseDraftProduct);
+    const result = await run(
+      db,
+      { code: "CLASSIC-TSHIRT", name: "Another Shirt", unitId: "unit-pcs" },
+      ctx,
+      primitivesQueries,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(DuplicateCodeError);
+    }
+  });
+
+  it("returns error when UoM is invalid", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    // getProduct select returns no existing product
+    spies.select.mockReturnValueOnce(undefined);
+    const result = await run(
+      db,
+      { code: "PROD-1", name: "Test Product", unitId: "unit-invalid" },
+      ctx,
+      primitivesQueries,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidUomError);
+    }
+  });
+
+  it("creates product in DRAFT status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    // getProduct select returns no existing product
+    spies.select.mockReturnValueOnce(undefined);
+    // insert returns the new product
+    spies.insert.mockReturnValueOnce({ ...baseDraftProduct });
+    const result = await run(
+      db,
+      { code: "CLASSIC-TSHIRT", name: "Classic T-Shirt", unitId: "unit-pcs" },
+      ctx,
+      primitivesQueries,
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.product).toEqual(baseDraftProduct);
+    }
+    expect(spies.values).toHaveBeenCalledWith(
+      expect.objectContaining({
+        code: "CLASSIC-TSHIRT",
+        name: "Classic T-Shirt",
+        unitId: "unit-pcs",
+        status: "DRAFT",
+      }),
+    );
+  });
+
+  it("passes custom fields through", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+    spies.insert.mockReturnValueOnce({ ...baseDraftProduct, customField1: "value1" });
+    const result = await run(
+      db,
+      {
+        code: "CLASSIC-TSHIRT",
+        name: "Classic T-Shirt",
+        unitId: "unit-pcs",
+        customField1: "value1",
+      },
+      ctx,
+      primitivesQueries,
+    );
+    expect(result.ok).toBe(true);
+    expect(spies.values).toHaveBeenCalledWith(
+      expect.objectContaining({
+        customField1: "value1",
+      }),
+    );
+  });
+});