@tailor-platform/erp-kit 0.2.0 → 0.2.2

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

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

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

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { baseRootCategory } from "../testing/fixtures";
+import {
+  CategoryNotFoundError,
+  CodeImmutableError,
+  MissingRequiredFieldError,
+} from "../lib/errors.generated";
+import { run } from "./updateProductCategory";
+
+describe("updateProductCategory", () => {
+  it("should return CategoryNotFoundError when category does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+    const input = { id: "non-existent", name: "New Name" };
+    const result = await run(db, input);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CategoryNotFoundError);
+    }
+  });
+
+  it("should return CodeImmutableError when code is provided", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseRootCategory);
+    const input = {
+      id: baseRootCategory.id,
+      code: "NEW-CODE",
+    };
+    const result = await run(db, input);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CodeImmutableError);
+    }
+  });
+
+  it("should return MissingRequiredFieldError when no fields are provided", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseRootCategory);
+    const input = { id: baseRootCategory.id };
+    const result = await run(db, input);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldError);
+    }
+  });
+
+  it("should pass custom fields through to update", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseRootCategory);
+    const updatedCategory = { ...baseRootCategory, priority: 1, updatedAt: new Date() };
+    spies.update.mockReturnValueOnce(updatedCategory);
+
+    const result = await run(db, { id: baseRootCategory.id, priority: 1 });
+    expect(result.ok).toBe(true);
+    expect(spies.set).toHaveBeenCalledWith(
+      expect.objectContaining({
+        priority: 1,
+      }),
+    );
+  });
+
+  it("should update category name successfully", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseRootCategory);
+    const updatedCategory = { ...baseRootCategory, name: "Apparel", updatedAt: new Date() };
+    spies.update.mockReturnValueOnce(updatedCategory);
+
+    const input = {
+      id: baseRootCategory.id,
+      name: "Apparel",
+    };
+    const result = await run(db, input);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.category.name).toBe("Apparel");
+    }
+  });
+});

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

@@ -0,0 +1,66 @@
+import { ok, err } from "../../../shared";
+import { Transaction } from "../generated/kysely-tailordb";
+import {
+  CategoryNotFoundError,
+  CodeImmutableError,
+  MissingRequiredFieldError,
+} from "../lib/errors.generated";
+
+export interface UpdateProductCategoryInput {
+  id: string;
+  code?: string;
+  name?: string;
+}
+
+/**
+ * Function: updateProductCategory
+ *
+ * Updates the display name of an existing category.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: UpdateProductCategoryInput & CF,
+) {
+  const { id, code, name, ...customFields } = input;
+
+  const category = await db
+    .selectFrom("ProductCategory")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!category) {
+    return err(new CategoryNotFoundError(id));
+  }
+
+  if (code !== undefined) {
+    return err(new CodeImmutableError(id));
+  }
+
+  const hasNameUpdate = name !== undefined;
+  const hasCustomFields = Object.keys(customFields).length > 0;
+
+  if (!hasNameUpdate && !hasCustomFields) {
+    return err(new MissingRequiredFieldError(id));
+  }
+
+  if (hasNameUpdate && !name?.trim()) {
+    return err(new MissingRequiredFieldError("name"));
+  }
+
+  const updates: Record<string, unknown> = {
+    ...(customFields as Record<string, unknown>),
+    updatedAt: new Date(),
+  };
+  if (hasNameUpdate) updates.name = name;
+
+  const updated = await db
+    .updateTable("ProductCategory")
+    .set(updates)
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ category: updated! });
+}

package/src/modules/product-management/db/product.ts

@@ -0,0 +1,47 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { unit as unitStub } from "../lib/_db_deps";
+
+export const BASE_PRODUCT_STATUSES = ["DRAFT", "ACTIVE", "ARCHIVED"] as const;
+
+export interface CreateProductTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  additionalStatuses?: string[];
+  unitType: TailorAnyDBType;
+}
+
+export function createProductType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateProductTypeParams<F>,
+) {
+  const statuses = [...BASE_PRODUCT_STATUSES, ...(params.additionalStatuses ?? [])] as [
+    string,
+    ...string[],
+  ];
+
+  return db
+    .type("Product", {
+      code: db.string().unique().description("Globally unique, immutable product code"),
+      name: db.string().description("Product display name"),
+      description: db.string({ optional: true }).description("Optional product description"),
+      unitId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.unitType },
+          backward: "products",
+        })
+        .description("Foreign key to Unit"),
+      status: db.enum(statuses).description("Lifecycle status: DRAFT, ACTIVE, ARCHIVED"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const product = createProductType({ unitType: unitStub });

package/src/modules/product-management/db/productAttribute.ts

@@ -0,0 +1,26 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+
+export interface CreateProductAttributeTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createProductAttributeType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateProductAttributeTypeParams<F>,
+) {
+  return db
+    .type("ProductAttribute", {
+      code: db.string().unique().description("Globally unique, immutable attribute code"),
+      name: db.string().description("Attribute display name"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const productAttribute = createProductAttributeType({});

package/src/modules/product-management/db/productAttributeAssignment.ts

@@ -0,0 +1,58 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { product } from "./product";
+import { productAttribute } from "./productAttribute";
+import { productAttributeValue } from "./productAttributeValue";
+
+export interface CreateProductAttributeAssignmentTypeParams<
+  F extends Record<string, TailorAnyDBField>,
+> {
+  fields?: F;
+}
+
+export function createProductAttributeAssignmentType<
+  const F extends Record<string, TailorAnyDBField>,
+>(params: CreateProductAttributeAssignmentTypeParams<F>) {
+  return db
+    .type("ProductAttributeAssignment", {
+      productId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: product },
+          backward: "productAttributeAssignments",
+        })
+        .description("Foreign key to Product"),
+      attributeId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: productAttribute },
+          backward: "productAttributeAssignments",
+        })
+        .description("Foreign key to ProductAttribute"),
+      valueId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: productAttributeValue },
+          backward: "productAttributeAssignments",
+        })
+        .description("Foreign key to ProductAttributeValue"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .indexes({
+      fields: ["productId", "attributeId", "valueId"],
+      unique: true,
+      name: "product_attribute_assignment_unique_idx",
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const productAttributeAssignment = createProductAttributeAssignmentType({});

package/src/modules/product-management/db/productAttributeValue.ts

@@ -0,0 +1,39 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { productAttribute } from "./productAttribute";
+
+export interface CreateProductAttributeValueTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createProductAttributeValueType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateProductAttributeValueTypeParams<F>,
+) {
+  return db
+    .type("ProductAttributeValue", {
+      attributeId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: productAttribute },
+          backward: "productAttributeValues",
+        })
+        .description("Foreign key to ProductAttribute"),
+      label: db.string().description("Display label for this value option"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .indexes({
+      fields: ["attributeId", "label"],
+      unique: true,
+      name: "product_attribute_value_unique_idx",
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const productAttributeValue = createProductAttributeValueType({});

package/src/modules/product-management/db/productCategory.ts

@@ -0,0 +1,34 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+
+export interface CreateProductCategoryTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createProductCategoryType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateProductCategoryTypeParams<F>,
+) {
+  return db
+    .type("ProductCategory", {
+      code: db.string().unique().description("Globally unique, immutable category code"),
+      name: db.string().description("Category display name"),
+      parentId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: "self" },
+          backward: "children",
+        })
+        .description("Parent category ID (null for root categories)"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const productCategory = createProductCategoryType({});

package/src/modules/product-management/db/productCategoryAssignment.ts

@@ -0,0 +1,49 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { product } from "./product";
+import { productCategory } from "./productCategory";
+
+export interface CreateProductCategoryAssignmentTypeParams<
+  F extends Record<string, TailorAnyDBField>,
+> {
+  fields?: F;
+}
+
+export function createProductCategoryAssignmentType<
+  const F extends Record<string, TailorAnyDBField>,
+>(params: CreateProductCategoryAssignmentTypeParams<F>) {
+  return db
+    .type("ProductCategoryAssignment", {
+      productId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: product },
+          backward: "productCategoryAssignments",
+        })
+        .description("Foreign key to Product"),
+      categoryId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: productCategory },
+          backward: "productCategoryAssignments",
+        })
+        .description("Foreign key to ProductCategory"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .indexes({
+      fields: ["productId", "categoryId"],
+      unique: true,
+      name: "product_category_assignment_unique_idx",
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const productCategoryAssignment = createProductCategoryAssignmentType({});

package/src/modules/product-management/db/productVariant.ts

@@ -0,0 +1,52 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { item as itemStub } from "../lib/_db_deps";
+import { product } from "./product";
+
+export interface CreateProductVariantTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  itemType: TailorAnyDBType;
+}
+
+export function createProductVariantType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateProductVariantTypeParams<F>,
+) {
+  return db
+    .type("ProductVariant", {
+      productId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: product },
+          backward: "productVariants",
+        })
+        .description("Foreign key to Product"),
+      axisValueKey: db
+        .string()
+        .description("Canonical key derived from sorted axis value IDs (e.g., value-1|value-3)"),
+      itemId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.itemType },
+          backward: "productVariants",
+        })
+        .description("Foreign key to generated Item in item-management"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .indexes({
+      fields: ["productId", "axisValueKey"],
+      unique: true,
+      name: "product_variant_unique_idx",
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const productVariant = createProductVariantType({ itemType: itemStub });

package/src/modules/product-management/docs/commands/ActivateProduct.md

@@ -0,0 +1,39 @@
+# ActivateProduct
+
+## Overview
+
+activateProduct transitions a product from DRAFT to ACTIVE status, enabling variant generation and downstream operations. Once active, the set of assigned attributes and their values become locked to preserve variant consistency.
+
+## Business Rules
+
+- Target product must exist
+- Target product must be in DRAFT status
+- After activation, the attribute structure is locked: assigned attributes cannot be added or removed, and existing attribute values cannot be modified or removed. New values can still be added to existing attributes to support incremental variant generation
+- After activation, UoM is locked and cannot be changed
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B{Product exists?}
+    B -->|No| C[Return error: PRODUCT_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: INVALID_STATE_TRANSITION]
+    D -->|Yes| F[Update status to ACTIVE]
+    F --> G[Return activated product]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRODUCT_NOT_FOUND**: Specified product ID does not exist
+- **INVALID_STATE_TRANSITION**: Product is not in DRAFT status
+
+## Test Cases
+
+- returns error when product not found
+- returns error when not in DRAFT status
+- activates DRAFT product to ACTIVE

package/src/modules/product-management/docs/commands/AssignProductToCategory.md

@@ -0,0 +1,43 @@
+# AssignProductToCategory
+
+## Overview
+
+assignProductToCategory creates a many-to-many link between a product and a product category. Products can be assigned to multiple categories for multi-dimensional classification. Assignment is idempotent — assigning an already-assigned product returns the existing record without error.
+
+## Business Rules
+
+- Target product must exist
+- Target category must exist
+- The (productId, categoryId) combination must be unique
+- Assignment is idempotent — if the assignment already exists, return the existing record
+- Products in any status (DRAFT, ACTIVE, ARCHIVED) can be assigned to categories
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive assign request] --> B{Product exists?}
+    B -->|No| C[Return error: PRODUCT_NOT_FOUND]
+    B -->|Yes| D{Category exists?}
+    D -->|No| E[Return error: CATEGORY_NOT_FOUND]
+    D -->|Yes| F{Assignment already exists?}
+    F -->|Yes| G[Return existing assignment]
+    F -->|No| H[Create assignment record]
+    H --> I[Return created assignment]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRODUCT_NOT_FOUND**: Specified product ID does not exist
+- **CATEGORY_NOT_FOUND**: Specified category ID does not exist
+
+## Test Cases
+
+- should return ProductNotFoundError when product does not exist
+- should return CategoryNotFoundError when category does not exist
+- should create assignment successfully
+- should return existing assignment when already assigned (idempotent)

package/src/modules/product-management/docs/commands/CreateProduct.md

@@ -0,0 +1,48 @@
+# CreateProduct
+
+## Overview
+
+createProduct establishes a new product in DRAFT status with a unique code, name, optional description, and unit of measure reference. Products are the commercial representation of a product and serve as the parent entity for variant generation. All products start in DRAFT to allow review and attribute configuration before activation.
+
+## Business Rules
+
+- Product code is required, must be globally unique across all products, and is immutable after creation
+- Product name is required and must be non-empty
+- UoM is required and must reference an existing active Unit from the primitives module
+- Products are always created in DRAFT status (not configurable)
+- Description is optional
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Code provided?}
+    B -->|No| C[Return error: MISSING_REQUIRED_FIELD]
+    B -->|Yes| D{Code unique?}
+    D -->|No| E[Return error: DUPLICATE_CODE]
+    D -->|Yes| F{Name provided and non-empty?}
+    F -->|No| G[Return error: MISSING_REQUIRED_FIELD]
+    F -->|Yes| H{UoM valid and active?}
+    H -->|No| I[Return error: INVALID_UOM]
+    H -->|Yes| J[Create product in DRAFT status]
+    J --> K[Return created product]
+```
+
+## External Dependencies
+
+- [primitives::Unit](../../../primitives/docs/models/Unit.md) - Validates that the referenced UoM exists and is active
+
+## Error Scenarios
+
+- **DUPLICATE_CODE**: A product with the same code already exists
+- **MISSING_REQUIRED_FIELD**: Code, name, or UoM not provided
+- **INVALID_UOM**: Referenced unit does not exist or is inactive
+
+## Test Cases
+
+- returns error when code is empty
+- returns error when name is empty
+- returns error when code already exists
+- returns error when UoM is invalid
+- creates product in DRAFT status
+- passes custom fields through

package/src/modules/product-management/docs/commands/CreateProductAttribute.md

@@ -0,0 +1,39 @@
+# CreateProductAttribute
+
+## Overview
+
+createProductAttribute defines a new product attribute with a unique code and display name. All attributes are variant axes — they hold predefined values that drive variant generation. Values are created separately via createProductAttributeValue.
+
+## Business Rules
+
+- Attribute code is required, must be globally unique, and is immutable after creation
+- Attribute name is required and must be non-empty
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Code provided and unique?}
+    B -->|No| C[Return error: DUPLICATE_CODE or MISSING_REQUIRED_FIELD]
+    B -->|Yes| D{Name provided?}
+    D -->|No| E[Return error: MISSING_REQUIRED_FIELD]
+    D -->|Yes| F[Create attribute record]
+    F --> G[Return created attribute]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **DUPLICATE_CODE**: An attribute with the same code already exists
+- **MISSING_REQUIRED_FIELD**: Code or name not provided
+
+## Test Cases
+
+- returns error when code is empty
+- returns error when name is empty
+- returns error when code already exists
+- creates attribute successfully
+- passes custom fields through to insert

package/src/modules/product-management/docs/commands/CreateProductAttributeValue.md

@@ -0,0 +1,42 @@
+# CreateProductAttributeValue
+
+## Overview
+
+createProductAttributeValue creates a new predefined value for an existing attribute. Values define the available options for that attribute (e.g., adding "Yellow" to a Color attribute). Products using this attribute can then include the new value in variant generation.
+
+## Business Rules
+
+- Target attribute must exist
+- Value label is required and must be unique within the parent attribute
+- Values can be added at any time, regardless of whether the attribute is assigned to products
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create value request] --> B{Attribute exists?}
+    B -->|No| C[Return error: ATTRIBUTE_NOT_FOUND]
+    B -->|Yes| D{Label provided and non-empty?}
+    D -->|No| E[Return error: INVALID_LABEL]
+    D -->|Yes| F{Label unique within attribute?}
+    F -->|No| G[Return error: DUPLICATE_VALUE]
+    F -->|Yes| H[Create attribute value record]
+    H --> I[Return created value]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ATTRIBUTE_NOT_FOUND**: Specified attribute ID does not exist
+- **INVALID_LABEL**: Label is empty or blank
+- **DUPLICATE_VALUE**: A value with the same label already exists for this attribute
+
+## Test Cases
+
+- returns error when attribute not found
+- returns error when label is empty
+- returns error when label already exists
+- creates value successfully