@tailor-platform/erp-kit 0.1.2 → 0.2.1

package/src/modules/item-management/command/activateItem.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../testing/index";
+import { type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { InvalidStateTransitionError, ItemNotFoundError } from "../lib/errors.generated";
+import { baseActiveItem, baseDraftItem, baseInactiveItem } from "../testing/fixtures";
+import { run } from "./activateItem";
+
+describe("activateItem", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["item-management:activateItem"],
+  };
+
+  it("returns error when item does not exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(undefined);
+
+    const result = await run(db, { id: "nonexistent" }, ctx);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ItemNotFoundError);
+    }
+  });
+
+  it("returns error when item is not DRAFT", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseActiveItem);
+
+    const result = await run(db, { id: baseActiveItem.id }, ctx);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateTransitionError);
+    }
+  });
+
+  it("returns error when item is INACTIVE", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseInactiveItem);
+
+    const result = await run(db, { id: baseInactiveItem.id }, ctx);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateTransitionError);
+    }
+  });
+
+  it("activates a DRAFT item", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const activatedItem = { ...baseDraftItem, status: "ACTIVE" };
+    spies.select.mockReturnValueOnce(baseDraftItem);
+    spies.update.mockReturnValue(activatedItem);
+
+    const result = await run(db, { id: baseDraftItem.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.item.status).toBe("ACTIVE");
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("activates from custom status when from is overridden", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const activatedItem = { ...baseInactiveItem, status: "ACTIVE" };
+    spies.select.mockReturnValueOnce(baseInactiveItem);
+    spies.update.mockReturnValue(activatedItem);
+
+    const result = await run(db, { id: baseInactiveItem.id, from: ["DRAFT", "INACTIVE"] }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.item.status).toBe("ACTIVE");
+    }
+  });
+});

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

@@ -0,0 +1,42 @@
+import { ok, err, type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { InvalidStateTransitionError, ItemNotFoundError } from "../lib/errors.generated";
+import { getItem } from "../query/getItem.generated";
+
+export interface ActivateItemInput {
+  id: string;
+  from?: string[];
+}
+
+/**
+ * Function: activateItem
+ *
+ * Transitions an item from DRAFT to ACTIVE status.
+ * Requires name, SKU, and UoM to be set.
+ */
+export async function run(db: DB, input: ActivateItemInput, ctx: CommandContext) {
+  const { id, from } = input;
+
+  // 1. Check item exists
+  const { item } = await getItem(db, { id }, ctx);
+
+  if (!item) {
+    return err(new ItemNotFoundError(id));
+  }
+
+  // 2. Check status is valid for activation
+  const validFromStatuses = from ?? ["DRAFT"];
+  if (!validFromStatuses.includes(item.status)) {
+    return err(new InvalidStateTransitionError(`${item.status} to ACTIVE`));
+  }
+
+  // 3. Update status to ACTIVE
+  const activatedItem = await db
+    .updateTable("Item")
+    .set({ status: "ACTIVE", updatedAt: new Date() })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ item: activatedItem });
+}

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

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

package/src/modules/item-management/command/assignItemToTaxonomy.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../testing/index";
+import { type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import {
+  DuplicateAssignmentError,
+  ItemNotFoundError,
+  NodeNotFoundError,
+} from "../lib/errors.generated";
+import { baseActiveItem, baseAssignment, baseChildNode } from "../testing/fixtures";
+import { run } from "./assignItemToTaxonomy";
+
+describe("assignItemToTaxonomy", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["item-management:assignItemToTaxonomy"],
+  };
+
+  it("returns error when item does not exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(undefined); // Item not found
+
+    const result = await run(db, { itemId: "nonexistent", taxonomyNodeId: baseChildNode.id }, ctx);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ItemNotFoundError);
+    }
+  });
+
+  it("returns error when node does not exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseActiveItem) // Item exists
+      .mockReturnValueOnce(undefined); // Node not found
+
+    const result = await run(db, { itemId: baseActiveItem.id, taxonomyNodeId: "nonexistent" }, ctx);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(NodeNotFoundError);
+    }
+  });
+
+  it("returns error when assignment already exists", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseActiveItem) // Item exists
+      .mockReturnValueOnce(baseChildNode) // Node exists
+      .mockReturnValueOnce(baseAssignment); // Assignment exists
+
+    const result = await run(
+      db,
+      { itemId: baseActiveItem.id, taxonomyNodeId: baseChildNode.id },
+      ctx,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(DuplicateAssignmentError);
+    }
+  });
+
+  it("creates assignment successfully", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const createdAssignment = {
+      ...baseAssignment,
+      id: "new-assignment-id",
+      itemId: baseActiveItem.id,
+      taxonomyNodeId: baseChildNode.id,
+    };
+    spies.select
+      .mockReturnValueOnce(baseActiveItem) // Item exists
+      .mockReturnValueOnce(baseChildNode) // Node exists
+      .mockReturnValueOnce(undefined); // No existing assignment
+    spies.insert.mockReturnValue(createdAssignment);
+
+    const result = await run(
+      db,
+      { itemId: baseActiveItem.id, taxonomyNodeId: baseChildNode.id },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.assignment.itemId).toBe(baseActiveItem.id);
+      expect(result.value.assignment.taxonomyNodeId).toBe(baseChildNode.id);
+    }
+    expect(spies.insert).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,63 @@
+import { ok, err, type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import {
+  DuplicateAssignmentError,
+  ItemNotFoundError,
+  NodeNotFoundError,
+} from "../lib/errors.generated";
+import { getItem } from "../query/getItem.generated";
+import { getTaxonomyNode } from "../query/getTaxonomyNode.generated";
+import { getItemTaxonomyAssignment } from "../query/getItemTaxonomyAssignment.generated";
+
+export interface AssignItemToTaxonomyInput {
+  itemId: string;
+  taxonomyNodeId: string;
+}
+
+/**
+ * Function: assignItemToTaxonomy
+ *
+ * Creates a link between an item and a taxonomy node for many-to-many classification.
+ */
+export async function run(db: DB, input: AssignItemToTaxonomyInput, ctx: CommandContext) {
+  const { itemId, taxonomyNodeId } = input;
+
+  // 1. Check item exists
+  const { item } = await getItem(db, { id: itemId }, ctx);
+
+  if (!item) {
+    return err(new ItemNotFoundError(itemId));
+  }
+
+  // 2. Check node exists
+  const { node } = await getTaxonomyNode(db, { id: taxonomyNodeId }, ctx);
+
+  if (!node) {
+    return err(new NodeNotFoundError(taxonomyNodeId));
+  }
+
+  // 3. Check for duplicate assignment
+  const { assignment: existing } = await getItemTaxonomyAssignment(
+    db,
+    { itemId, taxonomyNodeId },
+    ctx,
+  );
+
+  if (existing) {
+    return err(new DuplicateAssignmentError(`${itemId} in ${taxonomyNodeId}`));
+  }
+
+  // 4. Create assignment
+  const assignment = await db
+    .insertInto("ItemTaxonomyAssignment")
+    .values({
+      itemId,
+      taxonomyNodeId,
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ assignment: assignment });
+}

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

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

package/src/modules/item-management/command/createItem.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../testing/index";
+import { type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import {
+  DuplicateBarcodeError,
+  DuplicateSkuError,
+  UnitNotFoundError,
+} from "../lib/errors.generated";
+import { baseActiveItem, baseDraftItem } from "../testing/fixtures";
+import { getUnit } from "../../primitives";
+import { run } from "./createItem";
+
+describe("createItem", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["item-management:createItem"],
+  };
+
+  it("returns error when SKU already exists", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseDraftItem); // SKU lookup finds existing
+
+    const result = await run(db, { sku: "SKU-001", name: "Widget", unitId: "unit-kg" }, ctx, {
+      getUnit,
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(DuplicateSkuError);
+    }
+  });
+
+  it("returns error when barcode already exists", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(undefined) // SKU unique
+      .mockReturnValueOnce(baseActiveItem); // Barcode lookup finds existing
+
+    const result = await run(
+      db,
+      { sku: "SKU-NEW", name: "Widget", barcode: "BAR-002", unitId: "unit-kg" },
+      ctx,
+      { getUnit },
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(DuplicateBarcodeError);
+    }
+  });
+
+  it("returns error when UoM does not exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(undefined) // SKU unique
+      .mockReturnValueOnce(undefined); // UoM lookup fails
+
+    const result = await run(
+      db,
+      { sku: "SKU-NEW", name: "Widget", unitId: "nonexistent-unit" },
+      ctx,
+      { getUnit },
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnitNotFoundError);
+    }
+  });
+
+  it("creates item in DRAFT status by default", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const activeUnit = { id: "unit-kg", isActive: true };
+    const createdItem = { ...baseDraftItem, id: "new-item-id", sku: "SKU-NEW" };
+
+    spies.select
+      .mockReturnValueOnce(undefined) // SKU unique
+      .mockReturnValueOnce(activeUnit); // UoM valid
+    spies.insert.mockReturnValue(createdItem);
+
+    const result = await run(db, { sku: "SKU-NEW", name: "Widget", unitId: "unit-kg" }, ctx, {
+      getUnit,
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.item.sku).toBe("SKU-NEW");
+      expect(result.value.item.status).toBe("DRAFT");
+    }
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("creates item in ACTIVE status", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const activeUnit = { id: "unit-kg", isActive: true };
+    const createdItem = { ...baseActiveItem, id: "new-item-id", sku: "SKU-NEW" };
+
+    spies.select
+      .mockReturnValueOnce(undefined) // SKU unique
+      .mockReturnValueOnce(activeUnit); // UoM valid
+    spies.insert.mockReturnValue(createdItem);
+
+    const result = await run(
+      db,
+      { sku: "SKU-NEW", name: "New Widget", unitId: "unit-kg", status: "ACTIVE" },
+      ctx,
+      { getUnit },
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.item.status).toBe("ACTIVE");
+    }
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("skips barcode uniqueness check when barcode is not provided", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const activeUnit = { id: "unit-kg", isActive: true };
+    const createdItem = { ...baseDraftItem, id: "new-item-id" };
+
+    spies.select
+      .mockReturnValueOnce(undefined) // SKU unique
+      .mockReturnValueOnce(activeUnit); // UoM valid (no barcode check)
+    spies.insert.mockReturnValue(createdItem);
+
+    const result = await run(db, { sku: "SKU-001", name: "Widget", unitId: "unit-kg" }, ctx, {
+      getUnit,
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.item).toBeDefined();
+    }
+    expect(spies.select).toHaveBeenCalledTimes(2); // Only SKU + UoM checks
+  });
+
+  it("passes custom fields through to insert", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const activeUnit = { id: "unit-kg", isActive: true };
+    const createdItem = { ...baseDraftItem, id: "new-item-id", priority: 5 };
+
+    spies.select
+      .mockReturnValueOnce(undefined) // SKU unique
+      .mockReturnValueOnce(activeUnit); // UoM valid
+    spies.insert.mockReturnValue(createdItem);
+
+    await run(db, { sku: "SKU-NEW", name: "Widget", unitId: "unit-kg", priority: 5 }, ctx, {
+      getUnit,
+    });
+
+    expect(spies.values).toHaveBeenNthCalledWith(1, expect.objectContaining({ priority: 5 }));
+  });
+});

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

@@ -0,0 +1,72 @@
+import { ok, err, type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import {
+  DuplicateBarcodeError,
+  DuplicateSkuError,
+  UnitNotFoundError,
+} from "../lib/errors.generated";
+import { getItem } from "../query/getItem.generated";
+import { type PrimitivesQueries } from "../module";
+
+export interface CreateItemInput {
+  sku: string;
+  name: string;
+  barcode?: string;
+  unitId: string;
+  status?: "DRAFT" | "ACTIVE";
+}
+/**
+ * Function: createItem
+ *
+ * Creates a new item with a unique SKU in DRAFT or ACTIVE status.
+ * DRAFT items allow review before activation; ACTIVE items are immediately available.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: DB,
+  input: CreateItemInput & CF,
+  ctx: CommandContext,
+  primitivesQueries?: Pick<PrimitivesQueries, "getUnit">,
+) {
+  const { sku, name, barcode, unitId, status = "DRAFT", ...customFields } = input;
+
+  // 1. Check SKU uniqueness
+  const { item: existingSku } = await getItem(db, { sku }, ctx);
+
+  if (existingSku) {
+    return err(new DuplicateSkuError(sku));
+  }
+
+  // 2. Check barcode uniqueness (when provided)
+  if (barcode) {
+    const { item: existingBarcode } = await getItem(db, { barcode }, ctx);
+
+    if (existingBarcode) {
+      return err(new DuplicateBarcodeError(barcode));
+    }
+  }
+
+  // 3. Validate UoM exists and is active
+  const { unit } = await primitivesQueries!.getUnit(db, { id: unitId }, ctx);
+
+  if (!unit?.isActive) {
+    return err(new UnitNotFoundError(unitId));
+  }
+
+  // 4. Create item
+  const item = await db
+    .insertInto("Item")
+    .values({
+      ...(customFields as Record<string, unknown>),
+      sku,
+      name,
+      barcode: barcode ?? null,
+      unitId,
+      status,
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ item: item! });
+}

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

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

package/src/modules/item-management/command/createTaxonomyNode.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../testing/index";
+import { type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import {
+  DuplicateNodeCodeError,
+  MaxDepthExceededError,
+  ParentNodeNotFoundError,
+} from "../lib/errors.generated";
+import { baseChildNode, baseLeafNode, baseRootNode } from "../testing/fixtures";
+import { run } from "./createTaxonomyNode";
+
+describe("createTaxonomyNode", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["item-management:createTaxonomyNode"],
+  };
+
+  it("returns error when code already exists", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseRootNode); // Code lookup finds existing
+
+    const result = await run(db, { code: "ELECTRONICS", name: "Electronics" }, ctx, {
+      maxDepth: 10,
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(DuplicateNodeCodeError);
+    }
+  });
+
+  it("returns error when parent does not exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(undefined) // Code unique
+      .mockReturnValueOnce(undefined); // Parent not found
+
+    const result = await run(
+      db,
+      { code: "LAPTOPS", name: "Laptops", parentId: "nonexistent" },
+      ctx,
+      { maxDepth: 10 },
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ParentNodeNotFoundError);
+    }
+  });
+
+  it("returns error when max depth would be exceeded", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(undefined) // getTaxonomyNode: code unique
+      .mockReturnValueOnce(baseLeafNode) // getTaxonomyNode: parent exists (node-3)
+      .mockReturnValueOnce(baseLeafNode) // calculateNodeDepth: lookup node-3 (parentId=node-2)
+      .mockReturnValueOnce(baseChildNode) // calculateNodeDepth: lookup node-2 (parentId=node-1)
+      .mockReturnValueOnce(baseRootNode); // calculateNodeDepth: lookup node-1 (parentId=null, stop)
+
+    // parentDepth=3, new node depth=4 > maxDepth=3
+    const result = await run(
+      db,
+      { code: "DEEP", name: "Too Deep", parentId: baseLeafNode.id },
+      ctx,
+      { maxDepth: 3 },
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MaxDepthExceededError);
+    }
+  });
+
+  it("creates a root node", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const createdNode = { ...baseRootNode, id: "new-node-id", code: "CLOTHING" };
+    spies.select.mockReturnValueOnce(undefined); // Code unique
+    spies.insert.mockReturnValue(createdNode);
+
+    const result = await run(db, { code: "CLOTHING", name: "Clothing" }, ctx, { maxDepth: 10 });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.node.code).toBe("CLOTHING");
+      expect(result.value.node.parentId).toBeNull();
+    }
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("creates a child node under existing parent", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const createdNode = {
+      ...baseChildNode,
+      id: "new-node-id",
+      code: "TABLETS",
+      parentId: baseRootNode.id,
+    };
+    spies.select
+      .mockReturnValueOnce(undefined) // getTaxonomyNode: code unique
+      .mockReturnValueOnce(baseRootNode) // getTaxonomyNode: parent exists (root)
+      .mockReturnValueOnce(baseRootNode); // calculateNodeDepth: lookup root (parentId=null, depth=1)
+    spies.insert.mockReturnValue(createdNode);
+
+    const result = await run(
+      db,
+      { code: "TABLETS", name: "Tablets", parentId: baseRootNode.id },
+      ctx,
+      { maxDepth: 10 },
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.node.code).toBe("TABLETS");
+      expect(result.value.node.parentId).toBe(baseRootNode.id);
+    }
+  });
+
+  it("passes custom fields through to insert", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const createdNode = { ...baseRootNode, id: "new-node-id", sortOrder: 1 };
+    spies.select.mockReturnValueOnce(undefined); // Code unique
+    spies.insert.mockReturnValue(createdNode);
+
+    await run(db, { code: "SORTED", name: "Sorted Node", sortOrder: 1 }, ctx, { maxDepth: 10 });
+
+    expect(spies.values).toHaveBeenNthCalledWith(1, expect.objectContaining({ sortOrder: 1 }));
+  });
+});