@tailor-platform/erp-kit 0.1.1 → 0.2.0

package/src/modules/primitives/command/setReferenceUnit.test.ts

@@ -1,10 +1,10 @@
 import { describe, expect, it } from "vitest";
 import { createMockDb } from "../../testing/index";
-import { InsufficientPermissionError, type CommandContext } from "../../shared/internal";
+import { type CommandContext } from "../../shared/internal";
 import { DB } from "../generated/kysely-tailordb";
-import { UnitNotFoundError, UnitNotInCategoryError } from "../lib/errors";
+import { UnitNotFoundError, UnitNotInCategoryError } from "../lib/errors.generated";
 import { baseUoMCategory, baseUnitGram, baseUnitKg, baseUnitLiter } from "../testing/fixtures";
-import { setReferenceUnit } from "./setReferenceUnit";
+import { run } from "./setReferenceUnit";
 
 describe("setReferenceUnit", () => {
   const ctx: CommandContext = {
@@ -17,32 +17,38 @@ describe("setReferenceUnit", () => {
     const { db, spies } = createMockDb<DB>();
     spies.select.mockReturnValue(undefined);
 
-    await expect(
-      setReferenceUnit(
-        db,
-        {
-          unitId: "nonexistent-unit",
-          categoryId: baseUoMCategory.id,
-        },
-        ctx,
-      ),
-    ).rejects.toBeInstanceOf(UnitNotFoundError);
+    const result = await run(
+      db,
+      {
+        unitId: "nonexistent-unit",
+        categoryId: baseUoMCategory.id,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnitNotFoundError);
+    }
   });
 
   it("throws when unit is not in specified category", async () => {
     const { db, spies } = createMockDb<DB>();
     spies.select.mockReturnValue(baseUnitLiter); // Unit is in category-2, not category-1
 
-    await expect(
-      setReferenceUnit(
-        db,
-        {
-          unitId: baseUnitLiter.id,
-          categoryId: baseUoMCategory.id, // category-1
-        },
-        ctx,
-      ),
-    ).rejects.toBeInstanceOf(UnitNotInCategoryError);
+    const result = await run(
+      db,
+      {
+        unitId: baseUnitLiter.id,
+        categoryId: baseUoMCategory.id, // category-1
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnitNotInCategoryError);
+    }
   });
 
   // Idempotent cases
@@ -52,7 +58,7 @@ describe("setReferenceUnit", () => {
       .mockReturnValueOnce(baseUnitKg) // Unit lookup
       .mockReturnValueOnce(baseUoMCategory); // Category lookup
 
-    const result = await setReferenceUnit(
+    const result = await run(
       db,
       {
         unitId: baseUnitKg.id,
@@ -61,7 +67,10 @@ describe("setReferenceUnit", () => {
       ctx,
     );
 
-    expect(result.category.referenceUnitId).toBe(baseUnitKg.id);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.uoMCategory.referenceUnitId).toBe(baseUnitKg.id);
+    }
     expect(spies.update).not.toHaveBeenCalled();
   });
 
@@ -85,7 +94,7 @@ describe("setReferenceUnit", () => {
       .mockReturnValueOnce({ ...baseUnitGram, conversionFactor: 1.0 }) // Update gram factor
       .mockReturnValueOnce(updatedCategory); // Update category
 
-    const result = await setReferenceUnit(
+    const result = await run(
       db,
       {
         unitId: baseUnitGram.id,
@@ -94,15 +103,10 @@ describe("setReferenceUnit", () => {
       ctx,
     );
 
-    expect(result.category.referenceUnitId).toBe(baseUnitGram.id);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.uoMCategory.referenceUnitId).toBe(baseUnitGram.id);
+    }
     expect(spies.update).toHaveBeenCalled();
   });
-
-  it("throws when permission is missing", async () => {
-    const { db } = createMockDb<DB>();
-    const denied: CommandContext = { actorId: "test-actor", permissions: [] };
-    await expect(
-      setReferenceUnit(db, { unitId: "unit-1", categoryId: "cat-1" }, denied),
-    ).rejects.toBeInstanceOf(InsufficientPermissionError);
-  });
 });

package/src/modules/primitives/command/setReferenceUnit.ts

@@ -1,7 +1,9 @@
-import { defineCommand } from "../../shared/internal";
+import { ok, err, type CommandContext } from "../../shared/internal";
 import { DB } from "../generated/kysely-tailordb";
-import { UnitNotFoundError, UnitNotInCategoryError } from "../lib/errors";
-import { permissions } from "../permissions";
+import { UnitNotFoundError, UnitNotInCategoryError } from "../lib/errors.generated";
+import { getUnit } from "../query/getUnit.generated";
+import { getUoMCategory } from "../query/getUoMCategory.generated";
+import { listUnitsByCategory } from "../query/listUnitsByCategory.generated";
 
 export interface SetReferenceUnitInput {
   unitId: string;
@@ -14,71 +16,56 @@ export interface SetReferenceUnitInput {
  * Changes the reference unit for a UoM category. All conversion factors
  * are recalculated relative to the new reference unit.
  */
-export const setReferenceUnit = defineCommand(
-  permissions.setReferenceUnit,
-  async (db: DB, input: SetReferenceUnitInput) => {
-    // 1. Find unit by ID
-    const unit = await db
-      .selectFrom("Unit")
-      .selectAll()
-      .where("id", "=", input.unitId)
-      .executeTakeFirst();
-
-    if (!unit) {
-      throw new UnitNotFoundError(input.unitId);
-    }
+export async function run(db: DB, input: SetReferenceUnitInput, ctx: CommandContext) {
+  // 1. Find unit by ID
+  const { unit } = await getUnit(db, { id: input.unitId }, ctx);
 
-    // 2. Check unit belongs to specified category
-    if (unit.categoryId !== input.categoryId) {
-      throw new UnitNotInCategoryError(input.unitId, input.categoryId);
-    }
+  if (!unit) {
+    return err(new UnitNotFoundError(input.unitId));
+  }
 
-    // 3. Get category
-    const category = await db
-      .selectFrom("UoMCategory")
-      .selectAll()
-      .where("id", "=", input.categoryId)
-      .executeTakeFirst();
+  // 2. Check unit belongs to specified category
+  if (unit.categoryId !== input.categoryId) {
+    return err(new UnitNotInCategoryError(`${input.unitId} in ${input.categoryId}`));
+  }
 
-    // 4. If already reference unit, return (idempotent)
-    if (category?.referenceUnitId === input.unitId && category) {
-      return { category };
-    }
+  // 3. Get category
+  const { uoMCategory } = await getUoMCategory(db, { id: input.categoryId }, ctx);
 
-    // 5. Get all units in category for recalculation
-    const units = await db
-      .selectFrom("Unit")
-      .selectAll()
-      .where("categoryId", "=", input.categoryId)
-      .execute();
+  // 4. If already reference unit, return (idempotent)
+  if (uoMCategory?.referenceUnitId === input.unitId && uoMCategory) {
+    return ok({ uoMCategory });
+  }
 
-    // 6. Recalculate all conversion factors
-    // new_factor = old_factor / new_reference_old_factor
-    const newReferenceFactor = unit.conversionFactor;
-    for (const u of units) {
-      const newFactor = u.conversionFactor / newReferenceFactor;
-      await db
-        .updateTable("Unit")
-        .set({
-          conversionFactor: newFactor,
-          updatedAt: new Date(),
-        })
-        .where("id", "=", u.id)
-        .returningAll()
-        .executeTakeFirst();
-    }
+  // 5. Get all units in category for recalculation
+  const { units } = await listUnitsByCategory(db, { categoryId: input.categoryId }, ctx);
 
-    // 7. Update category reference unit
-    const updatedCategory = await db
-      .updateTable("UoMCategory")
+  // 6. Recalculate all conversion factors
+  // new_factor = old_factor / new_reference_old_factor
+  const newReferenceFactor = unit.conversionFactor;
+  for (const u of units) {
+    const newFactor = u.conversionFactor / newReferenceFactor;
+    await db
+      .updateTable("Unit")
       .set({
-        referenceUnitId: input.unitId,
+        conversionFactor: newFactor,
         updatedAt: new Date(),
       })
-      .where("id", "=", input.categoryId)
+      .where("id", "=", u.id)
       .returningAll()
       .executeTakeFirst();
+  }
 
-    return { category: updatedCategory! };
-  },
-);
+  // 7. Update category reference unit
+  const updatedCategory = await db
+    .updateTable("UoMCategory")
+    .set({
+      referenceUnitId: input.unitId,
+      updatedAt: new Date(),
+    })
+    .where("id", "=", input.categoryId)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ uoMCategory: updatedCategory! });
+}

package/src/modules/primitives/db/unit.ts

@@ -1,12 +1,15 @@
 import {
   db,
   type TailorAnyDBField,
+  type TailorAnyDBType,
   unsafeAllowAllGqlPermission,
   unsafeAllowAllTypePermission,
 } from "@tailor-platform/sdk";
+import { uomCategory } from "./uomCategory";
 
 export interface CreateUnitTypeParams<F extends Record<string, TailorAnyDBField>> {
   fields?: F;
+  uomCategoryType: TailorAnyDBType;
 }
 
 export function createUnitType<const F extends Record<string, TailorAnyDBField>>(
@@ -15,8 +18,15 @@ export function createUnitType<const F extends Record<string, TailorAnyDBField>>
   return db
     .type("Unit", {
       name: db.string().description("Unit display name (e.g., Kilogram)"),
-      symbol: db.string().description("Short symbol (e.g., kg)"),
-      categoryId: db.uuid().description("Foreign key to UoMCategory"),
+      symbol: db.string().unique().description("Short symbol (e.g., kg)"),
+      categoryId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.uomCategoryType },
+          backward: "units",
+        })
+        .description("Foreign key to UoMCategory"),
       conversionFactor: db
         .float()
         .description("Multiplier relative to reference unit (reference unit = 1.0)"),
@@ -29,4 +39,4 @@ export function createUnitType<const F extends Record<string, TailorAnyDBField>>
     .gqlPermission(unsafeAllowAllGqlPermission);
 }
 
-export const unit = createUnitType({});
+export const unit = createUnitType({ uomCategoryType: uomCategory });

package/src/modules/primitives/docs/commands/ActivateCategory.md

@@ -30,5 +30,4 @@ flowchart TD
 
 ## Error Scenarios
 
-- **Category not found**: Specified category ID does not exist - return not found error
-- **Invalid category ID**: Malformed or empty ID provided - return validation error
+- **UOM_CATEGORY_NOT_FOUND**: Specified category ID does not exist

package/src/modules/primitives/docs/commands/ActivateCurrency.md

@@ -29,5 +29,4 @@ flowchart TD
 
 ## Error Scenarios
 
-- **Currency not found**: Specified currency ID does not exist - return not found error
-- **Invalid currency ID**: Malformed or empty ID provided - return validation error
+- **CURRENCY_NOT_FOUND**: Specified currency ID does not exist

package/src/modules/primitives/docs/commands/ActivateUnit.md

@@ -30,5 +30,4 @@ flowchart TD
 
 ## Error Scenarios
 
-- **Unit not found**: Specified unit ID does not exist - return not found error
-- **Invalid unit ID**: Malformed or empty ID provided - return validation error
+- **UNIT_NOT_FOUND**: Specified unit ID does not exist

package/src/modules/primitives/docs/commands/CreateCategory.md

@@ -38,7 +38,4 @@ flowchart TD
 
 ## Error Scenarios
 
-- **Missing category name**: Name not provided - return validation error
-- **Duplicate category name**: Category with same name already exists - return conflict error
-- **Missing reference unit**: No reference unit details provided - return validation error indicating reference unit is required
-- **Invalid reference unit**: Reference unit details are incomplete or invalid - return validation error with specific issues
+- **DUPLICATE_CATEGORY_NAME**: Category with same name already exists

package/src/modules/primitives/docs/commands/CreateCurrency.md

@@ -41,7 +41,6 @@ flowchart TD
 
 ## Error Scenarios
 
-- **Invalid ISO code format**: Code is not exactly 3 uppercase letters - return validation error with format requirements
-- **Duplicate ISO code**: Currency with same code already exists - return conflict error with existing currency reference
-- **Invalid decimal places**: Value is negative or exceeds maximum (typically 4) - return validation error with valid range
-- **Missing required fields**: Symbol or name not provided - return validation error listing missing fields
+- **INVALID_ISO_CODE**: Code is not exactly 3 uppercase letters
+- **DUPLICATE_CURRENCY_CODE**: Currency with same code already exists
+- **INVALID_DECIMAL_PLACES**: Value is negative or exceeds maximum (typically 4)

package/src/modules/primitives/docs/commands/CreateExchangeRate.md

@@ -41,8 +41,7 @@ flowchart TD
 
 ## Error Scenarios
 
-- **Invalid source currency**: Source currency does not exist or is inactive - return error identifying the currency
-- **Invalid target currency**: Target currency does not exist or is inactive - return error identifying the currency
-- **Same currency pair**: Source and target currencies are the same - return error indicating self-conversion is not allowed
-- **Invalid rate value**: Rate is zero, negative, or not a valid number - return validation error with acceptable range
-- **Missing effective date**: No effective date provided - return validation error indicating date is required
+- **CURRENCY_NOT_FOUND**: Source or target currency does not exist
+- **INACTIVE_CURRENCY**: Source or target currency is inactive
+- **SAME_CURRENCY_PAIR**: Source and target currencies are the same
+- **INVALID_EXCHANGE_RATE**: Rate is zero, negative, or not a valid number

package/src/modules/primitives/docs/commands/CreateUnit.md

@@ -41,8 +41,8 @@ flowchart TD
 
 ## Error Scenarios
 
-- **Invalid category**: Category does not exist or is inactive - return error identifying the category
-- **Missing symbol**: Unit symbol not provided - return validation error
-- **Duplicate symbol**: Unit with same symbol already exists in category - return conflict error
-- **Invalid conversion factor**: Factor is zero, negative, or not a valid number - return validation error
-- **Invalid rounding precision**: Precision is negative - return validation error with acceptable range
+- **UOM_CATEGORY_NOT_FOUND**: Category does not exist
+- **CATEGORY_NOT_ACTIVE**: Category is inactive
+- **DUPLICATE_UNIT_SYMBOL**: Unit with same symbol already exists in category
+- **INVALID_CONVERSION_FACTOR**: Factor is zero, negative, or not a valid number
+- **INVALID_ROUNDING_PRECISION**: Precision is negative

package/src/modules/primitives/docs/commands/DeactivateCategory.md

@@ -33,6 +33,5 @@ flowchart TD
 
 ## Error Scenarios
 
-- **Category not found**: Specified category ID does not exist - return not found error
-- **Has active units**: Category still contains active units - return error listing active units that must be deactivated first
-- **Invalid category ID**: Malformed or empty ID provided - return validation error
+- **UOM_CATEGORY_NOT_FOUND**: Specified category ID does not exist
+- **CATEGORY_HAS_ACTIVE_UNITS**: Category still contains active units that must be deactivated first

package/src/modules/primitives/docs/commands/DeactivateCurrency.md

@@ -33,6 +33,5 @@ flowchart TD
 
 ## Error Scenarios
 
-- **Currency not found**: Specified currency ID does not exist - return not found error
-- **Base currency protection**: Attempting to deactivate the base currency - return error indicating base currency must be changed first
-- **Invalid currency ID**: Malformed or empty ID provided - return validation error
+- **CURRENCY_NOT_FOUND**: Specified currency ID does not exist
+- **CANNOT_DEACTIVATE_BASE_CURRENCY**: Attempting to deactivate the base currency, must change base currency first

package/src/modules/primitives/docs/commands/DeactivateUnit.md

@@ -33,6 +33,5 @@ flowchart TD
 
 ## Error Scenarios
 
-- **Unit not found**: Specified unit ID does not exist - return not found error
-- **Reference unit protection**: Attempting to deactivate the category's reference unit - return error indicating reference unit must be changed first
-- **Invalid unit ID**: Malformed or empty ID provided - return validation error
+- **UNIT_NOT_FOUND**: Specified unit ID does not exist
+- **CANNOT_DEACTIVATE_REFERENCE_UNIT**: Attempting to deactivate the category's reference unit, must change reference unit first

package/src/modules/primitives/docs/commands/SetBaseCurrency.md

@@ -34,6 +34,5 @@ flowchart TD
 
 ## Error Scenarios
 
-- **Currency not found**: Specified currency ID does not exist - return not found error
-- **Inactive currency**: Target currency is not in Active status - return error indicating currency must be activated first
-- **Invalid currency ID**: Malformed or empty ID provided - return validation error
+- **CURRENCY_NOT_FOUND**: Specified currency ID does not exist
+- **CANNOT_SET_INACTIVE_AS_BASE_CURRENCY**: Target currency is not in Active status, must be activated first

package/src/modules/primitives/docs/commands/SetReferenceUnit.md

@@ -38,6 +38,5 @@ flowchart TD
 
 ## Error Scenarios
 
-- **Unit not found**: Specified unit ID does not exist - return not found error
-- **Unit not in category**: Unit belongs to a different category than specified - return error with category mismatch details
-- **Invalid unit ID**: Malformed or empty ID provided - return validation error
+- **UNIT_NOT_FOUND**: Specified unit ID does not exist
+- **UNIT_NOT_IN_CATEGORY**: Unit belongs to a different category than specified

package/src/modules/primitives/docs/models/Currency.md

@@ -29,6 +29,10 @@ stateDiagram-v2
 - [deactivateCurrency](../commands/DeactivateCurrency.md)
 - [setBaseCurrency](../commands/SetBaseCurrency.md)
 
+### Query Definitions
+
+- [convertAmount](../queries/ConvertAmount.md)
+
 ### Models
 
 - Currency

package/src/modules/primitives/docs/models/ExchangeRate.md

@@ -15,7 +15,10 @@ AppendOnly
 ### Command Definitions
 
 - [createExchangeRate](../commands/CreateExchangeRate.md)
-- [convertAmount](../commands/ConvertAmount.md)
+
+### Query Definitions
+
+- [convertAmount](../queries/ConvertAmount.md)
 
 ### Models
 

package/src/modules/primitives/docs/models/Unit.md

@@ -27,7 +27,10 @@ stateDiagram-v2
 - [createUnit](../commands/CreateUnit.md)
 - [activateUnit](../commands/ActivateUnit.md)
 - [deactivateUnit](../commands/DeactivateUnit.md)
-- [convertQuantity](../commands/ConvertQuantity.md)
+
+### Query Definitions
+
+- [convertQuantity](../queries/ConvertQuantity.md)
 
 ### Models
 

package/src/modules/primitives/docs/models/UoMCategory.md

@@ -28,6 +28,8 @@ stateDiagram-v2
 - [deactivateCategory](../commands/DeactivateCategory.md)
 - [setReferenceUnit](../commands/SetReferenceUnit.md)
 
+### Query Definitions
+
 ### Models
 
 - UoMCategory

package/src/modules/primitives/docs/{commands → queries}/ConvertAmount.md

@@ -43,8 +43,6 @@ flowchart TD
 
 ## Error Scenarios
 
-- **Inactive currency**: Either source or target currency is inactive - return error identifying the inactive currency
-- **No exchange rate**: No rate found for the currency pair on or before the specified date - return error with date and currency pair
-- **Invalid amount**: Negative amount provided - return validation error
-- **Currency not found**: Specified currency code/ID does not exist - return not found error
-- **Date in future**: Conversion date is in the future and no forward rate exists - return error or use most recent rate based on configuration
+- **INACTIVE_CURRENCY**: Either source or target currency is inactive
+- **EXCHANGE_RATE_NOT_FOUND**: No rate found for the currency pair on or before the specified date
+- **CURRENCY_NOT_FOUND**: Specified currency code/ID does not exist

package/src/modules/primitives/docs/{commands → queries}/ConvertQuantity.md

@@ -36,8 +36,6 @@ flowchart TD
 
 ## Error Scenarios
 
-- **Incompatible units**: Source and target units belong to different categories - return error with message indicating the mismatch
-- **Inactive unit**: Either source or target unit is inactive - return error identifying the inactive unit
-- **Invalid quantity**: Negative quantity provided - return validation error (or allow based on configuration)
-- **Unit not found**: Specified unit ID does not exist - return not found error
-- **Overflow**: Calculation produces a number exceeding system limits - return overflow error
+- **INCOMPATIBLE_UNITS**: Source and target units belong to different categories
+- **INACTIVE_UNIT**: Either source or target unit is inactive
+- **UNIT_NOT_FOUND**: Specified unit ID does not exist

package/src/modules/primitives/docs/queries/GetBaseCurrency.md

@@ -0,0 +1,32 @@
+# GetBaseCurrency
+
+## Overview
+
+GetBaseCurrency retrieves the currency designated as the organization's base currency. Returns the currency record if a base currency has been set, or null if no base currency exists.
+
+This function supports financial reporting and default currency selection workflows.
+
+## Business Rules
+
+- Returns the single currency where `isBaseCurrency` is true
+- At most one currency can be the base currency at any time
+- Returns null if no base currency has been configured (e.g., before any currencies are created)
+- Does not require any input parameters
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive request] --> B[Query Currency where isBaseCurrency = true]
+    B --> C{Found?}
+    C -->|Yes| D[Return base currency]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- None (returns null when no base currency is set instead of throwing)

package/src/modules/primitives/docs/queries/GetCurrency.md

@@ -0,0 +1,36 @@
+# GetCurrency
+
+## Overview
+
+GetCurrency retrieves a single currency by its unique identifier or ISO 4217 code. Returns the currency record if found, or null if no matching currency exists.
+
+This function supports currency validation and lookup operations across all modules that reference currencies.
+
+## Business Rules
+
+- Lookup by `id` performs an exact UUID match
+- Lookup by `code` performs an exact string match against ISO 4217 codes (e.g., "USD", "EUR", "JPY")
+- Returns the full currency record including status, decimal places, and base currency flag
+- Does not filter by active status - returns both active and inactive currencies
+- Exactly one lookup key must be provided (id or code)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive lookup request] --> B{Lookup by id or code?}
+    B -->|id| C[Query Currency by id]
+    B -->|code| D[Query Currency by code]
+    C --> E{Found?}
+    D --> E
+    E -->|Yes| F[Return currency]
+    E -->|No| G[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- None (returns null when not found instead of throwing)

package/src/modules/primitives/docs/queries/GetUnit.md

@@ -0,0 +1,36 @@
+# GetUnit
+
+## Overview
+
+GetUnit retrieves a single unit of measure by its unique identifier or symbol. Returns the unit record if found, or null if no matching unit exists.
+
+This function supports unit validation and lookup operations across all modules that reference units of measure.
+
+## Business Rules
+
+- Lookup by `id` performs an exact UUID match
+- Lookup by `symbol` performs an exact string match (e.g., "kg", "lb", "g")
+- Returns the full unit record including status, conversion factor, and rounding precision
+- Does not filter by active status - returns both active and inactive units
+- Exactly one lookup key must be provided (id or symbol)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive lookup request] --> B{Lookup by id or symbol?}
+    B -->|id| C[Query Unit by id]
+    B -->|symbol| D[Query Unit by symbol]
+    C --> E{Found?}
+    D --> E
+    E -->|Yes| F[Return unit]
+    E -->|No| G[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- None (returns null when not found instead of throwing)

package/src/modules/primitives/docs/queries/GetUoMCategory.md

@@ -0,0 +1,36 @@
+# GetUoMCategory
+
+## Overview
+
+GetUoMCategory retrieves a single UoM category by its unique identifier or name. Returns the category record if found, or null if no matching category exists.
+
+This function supports category validation and lookup operations for unit management workflows.
+
+## Business Rules
+
+- Lookup by `id` performs an exact UUID match
+- Lookup by `name` performs an exact string match (e.g., "Weight", "Volume", "Length")
+- Returns the full category record including status, description, and reference unit ID
+- Does not filter by active status - returns both active and inactive categories
+- Exactly one lookup key must be provided (id or name)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive lookup request] --> B{Lookup by id or name?}
+    B -->|id| C[Query UoMCategory by id]
+    B -->|name| D[Query UoMCategory by name]
+    C --> E{Found?}
+    D --> E
+    E -->|Yes| F[Return category]
+    E -->|No| G[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- None (returns null when not found instead of throwing)