@tailor-platform/erp-kit 0.2.1 → 0.3.0

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

@@ -0,0 +1,102 @@
+import { ok, err } from "../../../shared";
+import { Transaction } from "../generated/kysely-tailordb";
+import {
+  ProductNotFoundError,
+  AttributeNotFoundError,
+  ProductArchivedError,
+  AxisStructureLockedError,
+  InvalidValueError,
+} from "../lib/errors.generated";
+
+export interface SetProductAttributeAssignmentInput {
+  productId: string;
+  attributeId: string;
+  valueId: string;
+}
+
+/**
+ * Function: setProductAttributeAssignment
+ *
+ * Adds an attribute value assignment to a product (multi-value).
+ * Each record is uniquely identified by (productId, attributeId, valueId).
+ * If the exact triple already exists, the operation is a no-op (idempotent).
+ * All attributes are variant axes, so axis locking rules always apply.
+ */
+export async function run(db: Transaction, input: SetProductAttributeAssignmentInput) {
+  const { productId, attributeId, valueId } = input;
+
+  // Check product exists
+  const product = await db
+    .selectFrom("Product")
+    .selectAll()
+    .where("id", "=", productId)
+    .executeTakeFirst();
+  if (!product) {
+    return err(new ProductNotFoundError(productId));
+  }
+
+  // Check attribute exists
+  const attribute = await db
+    .selectFrom("ProductAttribute")
+    .select("id")
+    .where("id", "=", attributeId)
+    .executeTakeFirst();
+  if (!attribute) {
+    return err(new AttributeNotFoundError(attributeId));
+  }
+
+  // Validate value: must reference a valid ProductAttributeValue for the attribute
+  const attrValue = await db
+    .selectFrom("ProductAttributeValue")
+    .selectAll()
+    .where("id", "=", valueId)
+    .where("attributeId", "=", attributeId)
+    .executeTakeFirst();
+  if (!attrValue) {
+    return err(new InvalidValueError(valueId));
+  }
+
+  // Read existing assignments (with lock for insert safety)
+  const existingAssignments = await db
+    .selectFrom("ProductAttributeAssignment")
+    .selectAll()
+    .where("productId", "=", productId)
+    .where("attributeId", "=", attributeId)
+    .forUpdate()
+    .execute();
+
+  // Idempotent no-op: if exact triple already exists, return existing
+  const exactMatch = existingAssignments.find((a) => a.valueId === valueId);
+  if (exactMatch) {
+    return ok({ assignment: exactMatch });
+  }
+
+  // Status-based rules
+  if (product.status === "ARCHIVED") {
+    return err(new ProductArchivedError(productId));
+  }
+
+  if (product.status === "ACTIVE") {
+    // ACTIVE: can add new values to already-assigned attribute (additive-only)
+    // but cannot assign a new attribute (structure locked)
+    if (existingAssignments.length === 0) {
+      return err(new AxisStructureLockedError(productId));
+    }
+    // existingAssignments.length > 0 means attribute is already assigned → additive OK
+  }
+
+  // Insert new assignment
+  const assignment = await db
+    .insertInto("ProductAttributeAssignment")
+    .values({
+      productId,
+      attributeId,
+      valueId,
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ assignment });
+}

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

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

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

@@ -0,0 +1,168 @@
+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 {
+  CodeImmutableError,
+  InvalidUomError,
+  MissingRequiredFieldError,
+  NoFieldsToUpdateError,
+  ProductNotFoundError,
+  UomLockedError,
+} from "../lib/errors.generated";
+import { baseActiveProduct, baseDraftProduct } from "../testing/fixtures";
+import { run } from "./updateProduct";
+
+describe("updateProduct", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["product-management:updateProduct"],
+  };
+
+  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 product not found", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+    const result = await run(db, { id: "nonexistent", name: "New Name" }, ctx, primitivesQueries);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ProductNotFoundError);
+    }
+  });
+
+  it("returns error when code change attempted", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce({ ...baseDraftProduct });
+    const result = await run(db, { id: "product-1", code: "NEW-CODE" }, ctx, primitivesQueries);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CodeImmutableError);
+    }
+  });
+
+  it("returns error when no fields provided", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce({ ...baseDraftProduct });
+    const result = await run(db, { id: "product-1" }, ctx, primitivesQueries);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(NoFieldsToUpdateError);
+    }
+  });
+
+  it("returns error when name is empty", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce({ ...baseDraftProduct });
+    const result = await run(db, { id: "product-1", name: "" }, ctx, primitivesQueries);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldError);
+    }
+  });
+
+  it("returns error when UoM locked on non-DRAFT", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce({ ...baseActiveProduct });
+    const result = await run(db, { id: "product-2", unitId: "unit-pcs" }, ctx, primitivesQueries);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UomLockedError);
+    }
+  });
+
+  it("returns error when UoM is invalid", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce({ ...baseDraftProduct });
+    const result = await run(
+      db,
+      { id: "product-1", unitId: "unit-invalid" },
+      ctx,
+      primitivesQueries,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidUomError);
+    }
+  });
+
+  it("updates description successfully", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updated = { ...baseDraftProduct, description: "A new description" };
+    spies.select.mockReturnValueOnce({ ...baseDraftProduct });
+    spies.update.mockReturnValueOnce(updated);
+    const result = await run(
+      db,
+      { id: "product-1", description: "A new description" },
+      ctx,
+      primitivesQueries,
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.product.description).toBe("A new description");
+    }
+  });
+
+  it("updates UoM successfully on DRAFT product", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updated = { ...baseDraftProduct, unitId: "unit-pcs" };
+    spies.select.mockReturnValueOnce({ ...baseDraftProduct });
+    spies.update.mockReturnValueOnce(updated);
+    const result = await run(db, { id: "product-1", unitId: "unit-pcs" }, ctx, primitivesQueries);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.product.unitId).toBe("unit-pcs");
+    }
+  });
+
+  it("updates name successfully", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updated = { ...baseDraftProduct, name: "Updated Name" };
+    spies.select.mockReturnValueOnce({ ...baseDraftProduct });
+    spies.update.mockReturnValueOnce(updated);
+    const result = await run(db, { id: "product-1", name: "Updated Name" }, ctx, primitivesQueries);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.product.name).toBe("Updated Name");
+    }
+  });
+
+  it("passes custom fields through", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updated = { ...baseDraftProduct, customField1: "value1" };
+    spies.select.mockReturnValueOnce({ ...baseDraftProduct });
+    spies.update.mockReturnValueOnce(updated);
+    const result = await run(
+      db,
+      { id: "product-1", name: "Updated", customField1: "value1" },
+      ctx,
+      primitivesQueries,
+    );
+    expect(result.ok).toBe(true);
+    expect(spies.set).toHaveBeenCalledWith(
+      expect.objectContaining({
+        customField1: "value1",
+      }),
+    );
+  });
+});

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

@@ -0,0 +1,95 @@
+import { ok, err, type CommandContext } from "../../../shared";
+import { Transaction } from "../generated/kysely-tailordb";
+import {
+  ProductNotFoundError,
+  CodeImmutableError,
+  NoFieldsToUpdateError,
+  UomLockedError,
+  InvalidUomError,
+  MissingRequiredFieldError,
+} from "../lib/errors.generated";
+import type { PrimitivesQueries } from "../module";
+
+export interface UpdateProductInput {
+  id: string;
+  code?: string;
+  name?: string;
+  description?: string;
+  unitId?: string;
+}
+
+/**
+ * Function: updateProduct
+ *
+ * Updates mutable fields of an existing product.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: UpdateProductInput & CF,
+  ctx: CommandContext,
+  primitivesQueries: Pick<PrimitivesQueries, "getUnit">,
+) {
+  const { id, code, name, description, unitId, ...customFields } = input;
+
+  // Check product exists (with lock)
+  const product = await db
+    .selectFrom("Product")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!product) {
+    return err(new ProductNotFoundError(id));
+  }
+
+  // Code is immutable
+  if (code !== undefined) {
+    return err(new CodeImmutableError(id));
+  }
+
+  // Check if any fields to update
+  const hasNameUpdate = name !== undefined;
+  const hasDescriptionUpdate = description !== undefined;
+  const hasUnitUpdate = unitId !== undefined;
+  const hasCustomFields = Object.keys(customFields).length > 0;
+
+  if (!hasNameUpdate && !hasDescriptionUpdate && !hasUnitUpdate && !hasCustomFields) {
+    return err(new NoFieldsToUpdateError(id));
+  }
+
+  // Validate name if provided
+  if (hasNameUpdate && !name?.trim()) {
+    return err(new MissingRequiredFieldError("name"));
+  }
+
+  // UoM can only be updated in DRAFT status
+  if (hasUnitUpdate) {
+    if (product.status !== "DRAFT") {
+      return err(new UomLockedError(id));
+    }
+    const unitResult = await primitivesQueries.getUnit(db, { id: unitId }, ctx);
+    if (!unitResult.ok) return err(new InvalidUomError(unitId));
+    if (!unitResult.value.unit?.isActive) {
+      return err(new InvalidUomError(unitId));
+    }
+  }
+
+  // Build update payload
+  const updates: Record<string, unknown> = {
+    ...(customFields as Record<string, unknown>),
+    updatedAt: new Date(),
+  };
+  if (hasNameUpdate) updates.name = name;
+  if (hasDescriptionUpdate) updates.description = description ?? null;
+  if (hasUnitUpdate) updates.unitId = unitId;
+
+  const updated = await db
+    .updateTable("Product")
+    .set(updates)
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ product: updated! });
+}

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

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

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

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import { Transaction } from "../generated/kysely-tailordb";
+import {
+  AttributeNotFoundError,
+  CodeImmutableError,
+  MissingRequiredFieldError,
+} from "../lib/errors.generated";
+import { baseColorAttribute } from "../testing/fixtures";
+import { run } from "./updateProductAttribute";
+
+describe("updateProductAttribute", () => {
+  it("returns error when attribute not found", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "nonexistent", name: "New Name" });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(AttributeNotFoundError);
+    }
+  });
+
+  it("returns error when trying to change code", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseColorAttribute);
+
+    const result = await run(db, {
+      id: baseColorAttribute.id,
+      code: "NEW-CODE",
+      name: "Color",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CodeImmutableError);
+    }
+  });
+
+  it("returns error when no fields provided", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseColorAttribute);
+
+    const result = await run(db, { id: baseColorAttribute.id });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldError);
+    }
+  });
+
+  it("returns error when name is empty string", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseColorAttribute);
+
+    const result = await run(db, { id: baseColorAttribute.id, name: "" });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldError);
+    }
+  });
+
+  it("passes custom fields through to update", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedAttribute = { ...baseColorAttribute, name: "Updated Color", priority: 10 };
+
+    spies.select.mockReturnValueOnce(baseColorAttribute);
+    spies.update.mockReturnValue(updatedAttribute);
+
+    await run(db, {
+      id: baseColorAttribute.id,
+      name: "Updated Color",
+      priority: 10,
+    });
+
+    expect(spies.set).toHaveBeenCalledWith(
+      expect.objectContaining({
+        priority: 10,
+        name: "Updated Color",
+      }),
+    );
+  });
+
+  it("updates name successfully", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedAttribute = { ...baseColorAttribute, name: "Updated Color" };
+
+    spies.select.mockReturnValueOnce(baseColorAttribute);
+    spies.update.mockReturnValue(updatedAttribute);
+
+    const result = await run(db, { id: baseColorAttribute.id, name: "Updated Color" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.attribute.name).toBe("Updated Color");
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,68 @@
+import { ok, err } from "../../../shared";
+import { Transaction } from "../generated/kysely-tailordb";
+import {
+  AttributeNotFoundError,
+  CodeImmutableError,
+  MissingRequiredFieldError,
+} from "../lib/errors.generated";
+
+export interface UpdateProductAttributeInput {
+  id: string;
+  code?: string;
+  name?: string;
+}
+
+/**
+ * Function: updateProductAttribute
+ *
+ * Updates the display name of an existing attribute.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: UpdateProductAttributeInput & CF,
+) {
+  const { id, code, name, ...rawCustomFields } = input;
+
+  const customFields = rawCustomFields as Record<string, unknown>;
+
+  const attribute = await db
+    .selectFrom("ProductAttribute")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!attribute) {
+    return err(new AttributeNotFoundError(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,
+    updatedAt: new Date(),
+  };
+  if (hasNameUpdate) updates.name = name;
+
+  const updated = await db
+    .updateTable("ProductAttribute")
+    .set(updates)
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ attribute: updated! });
+}

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

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

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

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import { Transaction } from "../generated/kysely-tailordb";
+import {
+  ValueNotFoundError,
+  InvalidLabelError,
+  DuplicateValueError,
+} from "../lib/errors.generated";
+import { baseColorRed, baseColorBlue } from "../testing/fixtures";
+import { run } from "./updateProductAttributeValue";
+
+describe("updateProductAttributeValue", () => {
+  it("returns error when value not found", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined); // value not found
+
+    const result = await run(db, { id: "nonexistent", label: "Green" });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ValueNotFoundError);
+    }
+  });
+
+  it("returns error when label is empty", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseColorRed); // value found
+
+    const result = await run(db, { id: baseColorRed.id, label: "" });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidLabelError);
+    }
+  });
+
+  it("returns error when label already exists on same attribute", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseColorRed) // value found
+      .mockReturnValueOnce(baseColorBlue); // duplicate label exists
+
+    const result = await run(db, { id: baseColorRed.id, label: "Blue" });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(DuplicateValueError);
+    }
+  });
+
+  it("returns error when label is whitespace only", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseColorRed); // value found
+
+    const result = await run(db, { id: baseColorRed.id, label: "   " });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidLabelError);
+    }
+  });
+
+  it("updates label successfully", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedValue = { ...baseColorRed, label: "Crimson" };
+
+    spies.select
+      .mockReturnValueOnce(baseColorRed) // value found
+      .mockReturnValueOnce(undefined); // no duplicate
+    spies.update.mockReturnValue(updatedValue);
+
+    const result = await run(db, { id: baseColorRed.id, label: "Crimson" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.value.label).toBe("Crimson");
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,58 @@
+import { ok, err } from "../../../shared";
+import { Transaction } from "../generated/kysely-tailordb";
+import {
+  ValueNotFoundError,
+  InvalidLabelError,
+  DuplicateValueError,
+} from "../lib/errors.generated";
+
+export interface UpdateProductAttributeValueInput {
+  id: string;
+  label: string;
+}
+
+/**
+ * Function: updateProductAttributeValue
+ *
+ * Updates the display label of an existing attribute value.
+ */
+export async function run(db: Transaction, input: UpdateProductAttributeValueInput) {
+  const { id, label } = input;
+
+  const value = await db
+    .selectFrom("ProductAttributeValue")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!value) {
+    return err(new ValueNotFoundError(id));
+  }
+
+  if (!label?.trim()) {
+    return err(new InvalidLabelError(id));
+  }
+
+  // Check label uniqueness within same attribute
+  const existingValue = await db
+    .selectFrom("ProductAttributeValue")
+    .selectAll()
+    .where("attributeId", "=", value.attributeId)
+    .where("label", "=", label)
+    .where("id", "!=", id)
+    .executeTakeFirst();
+
+  if (existingValue) {
+    return err(new DuplicateValueError(label));
+  }
+
+  const updated = await db
+    .updateTable("ProductAttributeValue")
+    .set({ label, updatedAt: new Date() })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ value: updated! });
+}