@tailor-platform/erp-kit 0.1.2 → 0.2.1

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

@@ -0,0 +1,117 @@
+// @generated — do not edit
+import { createDomainError } from "../../shared/internal";
+
+export const ItemNotFoundError = createDomainError(
+  "ItemNotFoundError", "ITEM_NOT_FOUND",
+  (identifier: string) => `Specified item ID does not exist: ${identifier}`,
+);
+
+export const InvalidStateTransitionError = createDomainError(
+  "InvalidStateTransitionError", "INVALID_STATE_TRANSITION",
+  (identifier: string) => `Item is not in DRAFT status: ${identifier}`,
+);
+
+export const NodeNotFoundError = createDomainError(
+  "NodeNotFoundError", "NODE_NOT_FOUND",
+  (identifier: string) => `Specified taxonomy node ID does not exist: ${identifier}`,
+);
+
+export const DuplicateAssignmentError = createDomainError(
+  "DuplicateAssignmentError", "DUPLICATE_ASSIGNMENT",
+  (identifier: string) => `Item is already assigned to this taxonomy node: ${identifier}`,
+);
+
+export const DuplicateSkuError = createDomainError(
+  "DuplicateSkuError", "DUPLICATE_SKU",
+  (identifier: string) => `An item with the same SKU already exists: ${identifier}`,
+);
+
+export const DuplicateBarcodeError = createDomainError(
+  "DuplicateBarcodeError", "DUPLICATE_BARCODE",
+  (identifier: string) => `An item with the same barcode already exists: ${identifier}`,
+);
+
+export const UnitNotFoundError = createDomainError(
+  "UnitNotFoundError", "UNIT_NOT_FOUND",
+  (identifier: string) => `Referenced unit does not exist or is inactive: ${identifier}`,
+);
+
+export const DuplicateNodeCodeError = createDomainError(
+  "DuplicateNodeCodeError", "DUPLICATE_NODE_CODE",
+  (identifier: string) => `A node with the same code already exists: ${identifier}`,
+);
+
+export const ParentNodeNotFoundError = createDomainError(
+  "ParentNodeNotFoundError", "PARENT_NODE_NOT_FOUND",
+  (identifier: string) => `Specified parent node ID does not exist: ${identifier}`,
+);
+
+export const MaxDepthExceededError = createDomainError(
+  "MaxDepthExceededError", "MAX_DEPTH_EXCEEDED",
+  (identifier: string) => `Adding this child would exceed the configurable tree depth limit: ${identifier}`,
+);
+
+export const DeleteNonDraftError = createDomainError(
+  "DeleteNonDraftError", "DELETE_NON_DRAFT",
+  (identifier: string) => `Item is in ACTIVE or INACTIVE status — only DRAFT items can be deleted: ${identifier}`,
+);
+
+export const NodeHasChildrenError = createDomainError(
+  "NodeHasChildrenError", "NODE_HAS_CHILDREN",
+  (identifier: string) => `Node has one or more child nodes — children must be moved or deleted first: ${identifier}`,
+);
+
+export const NodeHasAssignmentsError = createDomainError(
+  "NodeHasAssignmentsError", "NODE_HAS_ASSIGNMENTS",
+  (identifier: string) => `Node has one or more item assignments — assignments must be removed first: ${identifier}`,
+);
+
+export const CircularReferenceError = createDomainError(
+  "CircularReferenceError", "CIRCULAR_REFERENCE",
+  (identifier: string) => `New parent is the node itself or one of its descendants: ${identifier}`,
+);
+
+export const AssignmentNotFoundError = createDomainError(
+  "AssignmentNotFoundError", "ASSIGNMENT_NOT_FOUND",
+  (identifier: string) => `No assignment exists for the specified item and taxonomy node combination: ${identifier}`,
+);
+
+export const SkuImmutableError = createDomainError(
+  "SkuImmutableError", "SKU_IMMUTABLE",
+  (identifier: string) => `Attempt to change the SKU field: ${identifier}`,
+);
+
+export const UomLockedError = createDomainError(
+  "UomLockedError", "UOM_LOCKED",
+  (identifier: string) => `UoM cannot be changed after item has been activated (status is ACTIVE or INACTIVE): ${identifier}`,
+);
+
+export const NoFieldsToUpdateError = createDomainError(
+  "NoFieldsToUpdateError", "NO_FIELDS_TO_UPDATE",
+  (identifier: string) => `No updatable fields were provided in the request: ${identifier}`,
+);
+
+export const CodeImmutableError = createDomainError(
+  "CodeImmutableError", "CODE_IMMUTABLE",
+  (identifier: string) => `Attempt to change the node code: ${identifier}`,
+);
+
+export const MissingRequiredFieldsError = createDomainError(
+  "MissingRequiredFieldsError", "MISSING_REQUIRED_FIELDS",
+  (identifier: string) => `Name not provided or empty: ${identifier}`,
+);
+
+export const SelfReferenceError = createDomainError(
+  "SelfReferenceError", "SELF_REFERENCE",
+  (identifier: string) => `Node is moved to itself as parent — returns isCircular: true: ${identifier}`,
+);
+
+export const NoAssignmentsError = createDomainError(
+  "NoAssignmentsError", "NO_ASSIGNMENTS",
+  (identifier: string) => `No item assignments exist for the given node — caller receives empty array: ${identifier}`,
+);
+
+export const NoChildrenError = createDomainError(
+  "NoChildrenError", "NO_CHILDREN",
+  (identifier: string) => `No child nodes exist for the given parent — caller receives empty array: ${identifier}`,
+);

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

@@ -0,0 +1,17 @@
+// @generated — do not edit
+import { definePermissions } from "../../shared/internal";
+
+export const { permissions, own, all } = definePermissions("item-management", [
+  "activateItem",
+  "assignItemToTaxonomy",
+  "createItem",
+  "createTaxonomyNode",
+  "deactivateItem",
+  "deleteItem",
+  "deleteTaxonomyNode",
+  "moveTaxonomyNode",
+  "reactivateItem",
+  "removeItemFromTaxonomy",
+  "updateItem",
+  "updateTaxonomyNode",
+] as const);

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

@@ -0,0 +1,19 @@
+import type { InferSchema, Selectable, Insertable, Updateable } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
+
+export type Schema = InferSchema<DB>;
+
+export type Item<T extends { Item: object }> = Selectable<T["Item"]>;
+export type ItemCreate<T extends { Item: object }> = Insertable<T["Item"]>;
+export type ItemUpdate<T extends { Item: object }> = Updateable<T["Item"]>;
+
+export type TaxonomyNode<T extends { TaxonomyNode: object }> = Selectable<T["TaxonomyNode"]>;
+export type TaxonomyNodeCreate<T extends { TaxonomyNode: object }> = Insertable<T["TaxonomyNode"]>;
+export type TaxonomyNodeUpdate<T extends { TaxonomyNode: object }> = Updateable<T["TaxonomyNode"]>;
+
+export type ItemTaxonomyAssignment<T extends { ItemTaxonomyAssignment: object }> = Selectable<
+  T["ItemTaxonomyAssignment"]
+>;
+export type ItemTaxonomyAssignmentCreate<T extends { ItemTaxonomyAssignment: object }> = Insertable<
+  T["ItemTaxonomyAssignment"]
+>;

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

@@ -0,0 +1,97 @@
+import { type TailorAnyDBField } from "@tailor-platform/sdk";
+import { type EmptyFields, type FieldsToInsertable } from "../shared/internal";
+import type { defineModule as definePrimitivesModule } from "../primitives";
+import { createItem } from "./command/createItem.generated";
+import { updateItem } from "./command/updateItem.generated";
+import { activateItem } from "./command/activateItem.generated";
+import { deactivateItem } from "./command/deactivateItem.generated";
+import { reactivateItem } from "./command/reactivateItem.generated";
+import { deleteItem } from "./command/deleteItem.generated";
+import { createTaxonomyNode } from "./command/createTaxonomyNode.generated";
+import { updateTaxonomyNode } from "./command/updateTaxonomyNode.generated";
+import { moveTaxonomyNode } from "./command/moveTaxonomyNode.generated";
+import { deleteTaxonomyNode } from "./command/deleteTaxonomyNode.generated";
+import { assignItemToTaxonomy } from "./command/assignItemToTaxonomy.generated";
+import { removeItemFromTaxonomy } from "./command/removeItemFromTaxonomy.generated";
+import { getItem } from "./query/getItem.generated";
+import { getTaxonomyNode } from "./query/getTaxonomyNode.generated";
+import { getTaxonomyNodeChildren } from "./query/getTaxonomyNodeChildren.generated";
+import { getItemTaxonomyAssignment } from "./query/getItemTaxonomyAssignment.generated";
+import { getTaxonomyNodeAssignments } from "./query/getTaxonomyNodeAssignments.generated";
+import { calculateNodeDepth } from "./query/calculateNodeDepth.generated";
+import { calculateSubtreeDepth } from "./query/calculateSubtreeDepth.generated";
+import { detectCircularReference } from "./query/detectCircularReference.generated";
+import { createItemType, type CreateItemTypeParams } from "./db/item";
+import { createTaxonomyNodeType, type CreateTaxonomyNodeTypeParams } from "./db/taxonomyNode";
+import {
+  createItemTaxonomyAssignmentType,
+  type CreateItemTaxonomyAssignmentTypeParams,
+} from "./db/itemTaxonomyAssignment";
+
+type PrimitivesModule = ReturnType<typeof definePrimitivesModule>;
+type PrimitivesDB = PrimitivesModule["db"];
+export type PrimitivesQueries = PrimitivesModule["queries"];
+
+const DEFAULT_MAX_DEPTH = 10;
+
+export interface DefineModuleParams<
+  IF extends Record<string, TailorAnyDBField>,
+  TNF extends Record<string, TailorAnyDBField>,
+  ITAF extends Record<string, TailorAnyDBField>,
+> {
+  item?: CreateItemTypeParams<IF>;
+  taxonomyNode?: CreateTaxonomyNodeTypeParams<TNF>;
+  itemTaxonomyAssignment?: CreateItemTaxonomyAssignmentTypeParams<ITAF>;
+  taxonomy?: { maxDepth?: number };
+  primitives: {
+    db: { unit: PrimitivesDB["unit"] };
+    queries: { getUnit: PrimitivesQueries["getUnit"] };
+  };
+}
+
+export const defineModule = <
+  const IF extends Record<string, TailorAnyDBField> = EmptyFields,
+  const TNF extends Record<string, TailorAnyDBField> = EmptyFields,
+  const ITAF extends Record<string, TailorAnyDBField> = EmptyFields,
+>(
+  params: DefineModuleParams<IF, TNF, ITAF>,
+) => {
+  const item = createItemType({
+    ...params.item,
+    unitType: params.primitives.db.unit,
+  });
+  const taxonomyNode = createTaxonomyNodeType(params.taxonomyNode ?? {});
+  const itemTaxonomyAssignment = createItemTaxonomyAssignmentType(
+    params.itemTaxonomyAssignment ?? {},
+  );
+
+  const maxDepth = params.taxonomy?.maxDepth ?? DEFAULT_MAX_DEPTH;
+
+  return {
+    db: { item, taxonomyNode, itemTaxonomyAssignment },
+    queries: {
+      getItem,
+      getTaxonomyNode,
+      getTaxonomyNodeChildren,
+      getItemTaxonomyAssignment,
+      getTaxonomyNodeAssignments,
+      calculateNodeDepth,
+      calculateSubtreeDepth,
+      detectCircularReference,
+    },
+    commands: {
+      createItem: createItem<FieldsToInsertable<IF>>(params.primitives.queries),
+      updateItem: updateItem<FieldsToInsertable<IF>>(params.primitives.queries),
+      activateItem: activateItem(),
+      deactivateItem: deactivateItem(),
+      reactivateItem: reactivateItem(),
+      deleteItem: deleteItem(),
+      createTaxonomyNode: createTaxonomyNode<FieldsToInsertable<TNF>>({ maxDepth }),
+      updateTaxonomyNode: updateTaxonomyNode<FieldsToInsertable<TNF>>(),
+      moveTaxonomyNode: moveTaxonomyNode({ maxDepth }),
+      deleteTaxonomyNode: deleteTaxonomyNode(),
+      assignItemToTaxonomy: assignItemToTaxonomy(),
+      removeItemFromTaxonomy: removeItemFromTaxonomy(),
+    },
+  };
+};

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

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

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

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { baseRootNode, baseChildNode, baseLeafNode } from "../testing/fixtures";
+import { run } from "./calculateNodeDepth";
+
+describe("calculateNodeDepth", () => {
+  it("returns depth 1 for root node", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseRootNode);
+
+    const result = await run(db, { nodeId: "node-1" });
+
+    expect(result.depth).toBe(1);
+  });
+
+  it("returns depth 2 for child of root", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseChildNode).mockReturnValueOnce(baseRootNode);
+
+    const result = await run(db, { nodeId: "node-2" });
+
+    expect(result.depth).toBe(2);
+  });
+
+  it("returns depth 3 for grandchild of root", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseLeafNode)
+      .mockReturnValueOnce(baseChildNode)
+      .mockReturnValueOnce(baseRootNode);
+
+    const result = await run(db, { nodeId: "node-3" });
+
+    expect(result.depth).toBe(3);
+  });
+
+  it("returns depth 1 when node not found", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { nodeId: "nonexistent" });
+
+    expect(result.depth).toBe(1);
+  });
+
+  it("handles broken ancestor chain gracefully", async () => {
+    const brokenNode = { ...baseChildNode, parentId: "missing-parent" };
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(brokenNode).mockReturnValueOnce(undefined);
+
+    const result = await run(db, { nodeId: "node-2" });
+
+    expect(result.depth).toBe(2);
+  });
+});

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

@@ -0,0 +1,28 @@
+import type { ReadonlyDB } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
+
+export interface CalculateNodeDepthInput {
+  nodeId: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: CalculateNodeDepthInput) {
+  let depth = 1;
+  let currentId: string | null = input.nodeId;
+
+  while (currentId) {
+    const node = await db
+      .selectFrom("TaxonomyNode")
+      .selectAll()
+      .where("id", "=", currentId)
+      .executeTakeFirst();
+
+    if (!node) break;
+
+    if (!node.parentId) break;
+
+    depth++;
+    currentId = node.parentId;
+  }
+
+  return { depth };
+}

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

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

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

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { baseChildNode, baseLeafNode } from "../testing/fixtures";
+import { run } from "./calculateSubtreeDepth";
+
+describe("calculateSubtreeDepth", () => {
+  it("returns 1 for leaf node (no children)", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce([]);
+
+    const result = await run(db, { nodeId: "node-3" });
+
+    expect(result.depth).toBe(1);
+  });
+
+  it("returns 2 for node with one level of children", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce([baseLeafNode]).mockReturnValueOnce([]);
+
+    const result = await run(db, { nodeId: "node-1" });
+
+    expect(result.depth).toBe(2);
+  });
+
+  it("returns 3 for node with two levels of children", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce([baseChildNode])
+      .mockReturnValueOnce([baseLeafNode])
+      .mockReturnValueOnce([]);
+
+    const result = await run(db, { nodeId: "node-1" });
+
+    expect(result.depth).toBe(3);
+  });
+
+  it("returns max depth for node with multiple branches", async () => {
+    const shortChild = {
+      id: "short-1",
+      code: "S",
+      name: "Short",
+      parentId: "node-1",
+      createdAt: new Date("2024-01-01T00:00:00.000Z"),
+      updatedAt: null,
+    };
+    const deepChild = {
+      id: "deep-1",
+      code: "D",
+      name: "Deep",
+      parentId: "node-1",
+      createdAt: new Date("2024-01-01T00:00:00.000Z"),
+      updatedAt: null,
+    };
+    const deepGrandchild = {
+      id: "deep-2",
+      code: "DG",
+      name: "Deep Grand",
+      parentId: "deep-1",
+      createdAt: new Date("2024-01-01T00:00:00.000Z"),
+      updatedAt: null,
+    };
+
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce([shortChild, deepChild])
+      .mockReturnValueOnce([])
+      .mockReturnValueOnce([deepGrandchild])
+      .mockReturnValueOnce([]);
+
+    const result = await run(db, { nodeId: "node-1" });
+
+    expect(result.depth).toBe(3);
+  });
+});

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

@@ -0,0 +1,29 @@
+import type { ReadonlyDB } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
+
+export interface CalculateSubtreeDepthInput {
+  nodeId: string;
+}
+
+async function getSubtreeDepth(db: ReadonlyDB<DB>, nodeId: string): Promise<number> {
+  const children = await db
+    .selectFrom("TaxonomyNode")
+    .selectAll()
+    .where("parentId", "=", nodeId)
+    .execute();
+
+  if (!children || children.length === 0) return 1;
+
+  let maxChildDepth = 0;
+  for (const child of children) {
+    const childDepth = await getSubtreeDepth(db, child.id);
+    if (childDepth > maxChildDepth) maxChildDepth = childDepth;
+  }
+
+  return 1 + maxChildDepth;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: CalculateSubtreeDepthInput) {
+  const depth = await getSubtreeDepth(db, input.nodeId);
+  return { depth };
+}

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

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

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

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { baseRootNode, baseChildNode, baseLeafNode } from "../testing/fixtures";
+import { run } from "./detectCircularReference";
+
+describe("detectCircularReference", () => {
+  it("detects self-reference as circular", async () => {
+    const { db } = createMockDb<DB>();
+
+    const result = await run(db, { nodeId: "node-1", newParentId: "node-1" });
+
+    expect(result.isCircular).toBe(true);
+  });
+
+  it("detects moving node under its child as circular", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseChildNode);
+
+    const result = await run(db, { nodeId: "node-1", newParentId: "node-2" });
+
+    expect(result.isCircular).toBe(true);
+  });
+
+  it("detects moving node under its grandchild as circular", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseLeafNode).mockReturnValueOnce(baseChildNode);
+
+    const result = await run(db, { nodeId: "node-1", newParentId: "node-3" });
+
+    expect(result.isCircular).toBe(true);
+  });
+
+  it("returns not circular for valid move", async () => {
+    const secondRoot = { ...baseRootNode, id: "node-4", parentId: null };
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(secondRoot);
+
+    const result = await run(db, { nodeId: "node-3", newParentId: "node-4" });
+
+    expect(result.isCircular).toBe(false);
+  });
+
+  it("returns not circular when new parent is root", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseRootNode);
+
+    const result = await run(db, { nodeId: "node-2", newParentId: "node-1" });
+
+    expect(result.isCircular).toBe(false);
+  });
+
+  it("handles broken ancestor chain gracefully (not circular)", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { nodeId: "node-1", newParentId: "missing-node" });
+
+    expect(result.isCircular).toBe(false);
+  });
+});

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

@@ -0,0 +1,32 @@
+import type { ReadonlyDB } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
+
+export interface DetectCircularReferenceInput {
+  nodeId: string;
+  newParentId: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: DetectCircularReferenceInput) {
+  if (input.newParentId === input.nodeId) {
+    return { isCircular: true };
+  }
+
+  // Walk up from new parent to root, checking if the moved node appears
+  let ancestorId: string | null = input.newParentId;
+  while (ancestorId) {
+    const ancestor = await db
+      .selectFrom("TaxonomyNode")
+      .selectAll()
+      .where("id", "=", ancestorId)
+      .executeTakeFirst();
+
+    if (!ancestor) break;
+
+    ancestorId = ancestor.parentId;
+    if (ancestorId === input.nodeId) {
+      return { isCircular: true };
+    }
+  }
+
+  return { isCircular: false };
+}

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

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

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

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { baseActiveItem, baseDraftItem } from "../testing/fixtures";
+import { run } from "./getItem";
+
+describe("getItem", () => {
+  describe("by id", () => {
+    it("returns item when found", async () => {
+      const { db, spies } = createMockDb<DB>();
+      spies.select.mockReturnValue(baseDraftItem);
+
+      const result = await run(db, { id: "item-1" });
+
+      expect(result.item).toEqual(baseDraftItem);
+    });
+
+    it("returns null when item not found", async () => {
+      const { db, spies } = createMockDb<DB>();
+      spies.select.mockReturnValue(undefined);
+
+      const result = await run(db, { id: "nonexistent" });
+
+      expect(result.item).toBeNull();
+    });
+  });
+
+  describe("by sku", () => {
+    it("returns item when found", async () => {
+      const { db, spies } = createMockDb<DB>();
+      spies.select.mockReturnValue(baseDraftItem);
+
+      const result = await run(db, { sku: "SKU-001" });
+
+      expect(result.item).toEqual(baseDraftItem);
+    });
+
+    it("returns null when item not found", async () => {
+      const { db, spies } = createMockDb<DB>();
+      spies.select.mockReturnValue(undefined);
+
+      const result = await run(db, { sku: "NONEXISTENT" });
+
+      expect(result.item).toBeNull();
+    });
+  });
+
+  describe("by barcode", () => {
+    it("returns item when found", async () => {
+      const { db, spies } = createMockDb<DB>();
+      spies.select.mockReturnValue(baseActiveItem);
+
+      const result = await run(db, { barcode: "BAR-002" });
+
+      expect(result.item).toEqual(baseActiveItem);
+    });
+
+    it("returns null when item not found", async () => {
+      const { db, spies } = createMockDb<DB>();
+      spies.select.mockReturnValue(undefined);
+
+      const result = await run(db, { barcode: "NONEXISTENT" });
+
+      expect(result.item).toBeNull();
+    });
+  });
+});

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

@@ -0,0 +1,20 @@
+import type { ReadonlyDB } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
+
+export type GetItemInput = { id: string } | { sku: string } | { barcode: string };
+
+export async function run(db: ReadonlyDB<DB>, input: GetItemInput) {
+  let query = db.selectFrom("Item").selectAll();
+
+  if ("id" in input) {
+    query = query.where("id", "=", input.id);
+  } else if ("sku" in input) {
+    query = query.where("sku", "=", input.sku);
+  } else {
+    query = query.where("barcode", "=", input.barcode);
+  }
+
+  const item = await query.executeTakeFirst();
+
+  return { item: item ?? null };
+}

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

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