@tailor-platform/erp-kit 0.2.1 → 0.3.0

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

@@ -1,8 +1,6 @@
-import { ok, err, type CommandContext } from "../../shared/internal";
-import { DB } from "../generated/kysely-tailordb";
+import { ok, err } from "../../../shared";
+import { Transaction } from "../generated/kysely-tailordb";
 import { CannotDeactivateReferenceUnitError, UnitNotFoundError } from "../lib/errors.generated";
-import { getUnit } from "../query/getUnit.generated";
-import { getUoMCategory } from "../query/getUoMCategory.generated";
 
 export interface DeactivateUnitInput {
   unitId: string;
@@ -15,9 +13,14 @@ export interface DeactivateUnitInput {
  * and quantity conversions while preserving all historical data.
  * Reference units cannot be deactivated.
  */
-export async function run(db: DB, input: DeactivateUnitInput, ctx: CommandContext) {
+export async function run(db: Transaction, input: DeactivateUnitInput) {
   // 1. Find unit by ID
-  const { unit } = await getUnit(db, { id: input.unitId }, ctx);
+  const unit = await db
+    .selectFrom("Unit")
+    .selectAll()
+    .where("id", "=", input.unitId)
+    .forUpdate()
+    .executeTakeFirst();
 
   // 2. If not found, throw error
   if (!unit) {
@@ -25,7 +28,11 @@ export async function run(db: DB, input: DeactivateUnitInput, ctx: CommandContex
   }
 
   // 3. Check if unit is reference unit for its category
-  const { uoMCategory } = await getUoMCategory(db, { id: unit.categoryId }, ctx);
+  const uoMCategory = await db
+    .selectFrom("UoMCategory")
+    .selectAll()
+    .where("id", "=", unit.categoryId)
+    .executeTakeFirst();
 
   if (uoMCategory?.referenceUnitId === unit.id) {
     return err(new CannotDeactivateReferenceUnitError(input.unitId));

package/src/modules/primitives/command/setBaseCurrency.generated.ts

@@ -1,5 +1,5 @@
 // @generated — do not edit
-import { defineCommand } from "../../shared/internal";
+import { defineCommand } from "../../../shared";
 import { permissions } from "../lib/permissions.generated";
 import { run } from "./setBaseCurrency";
 

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

@@ -1,7 +1,6 @@
 import { describe, expect, it } from "vitest";
-import { type CommandContext } from "../../shared/internal";
-import { createMockDb } from "../../testing/index";
-import { DB } from "../generated/kysely-tailordb";
+import { createMockDb } from "../../../testing/index";
+import { Transaction } from "../generated/kysely-tailordb";
 import {
   CannotSetInactiveAsBaseCurrencyError,
   CurrencyNotFoundError,
@@ -10,23 +9,14 @@ import { baseCurrencyEUR, baseCurrencyUSD, inactiveCurrency } from "../testing/f
 import { run } from "./setBaseCurrency";
 
 describe("setBaseCurrency", () => {
-  const ctx: CommandContext = {
-    actorId: "test-actor",
-    permissions: ["primitives:setBaseCurrency"],
-  };
-
   // Error cases
   it("throws when currency doesn't exist", async () => {
-    const { db, spies } = createMockDb<DB>();
+    const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValue(undefined);
 
-    const result = await run(
-      db,
-      {
-        currencyId: "nonexistent-currency",
-      },
-      ctx,
-    );
+    const result = await run(db, {
+      currencyId: "nonexistent-currency",
+    });
 
     expect(result.ok).toBe(false);
     if (!result.ok) {
@@ -35,16 +25,12 @@ describe("setBaseCurrency", () => {
   });
 
   it("throws when currency is inactive", async () => {
-    const { db, spies } = createMockDb<DB>();
+    const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValue(inactiveCurrency);
 
-    const result = await run(
-      db,
-      {
-        currencyId: inactiveCurrency.id,
-      },
-      ctx,
-    );
+    const result = await run(db, {
+      currencyId: inactiveCurrency.id,
+    });
 
     expect(result.ok).toBe(false);
     if (!result.ok) {
@@ -54,16 +40,12 @@ describe("setBaseCurrency", () => {
 
   // Idempotent cases
   it("returns currency unchanged when already base", async () => {
-    const { db, spies } = createMockDb<DB>();
+    const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValue(baseCurrencyUSD); // Already base currency
 
-    const result = await run(
-      db,
-      {
-        currencyId: baseCurrencyUSD.id,
-      },
-      ctx,
-    );
+    const result = await run(db, {
+      currencyId: baseCurrencyUSD.id,
+    });
 
     expect(result.ok).toBe(true);
     if (result.ok) {
@@ -74,7 +56,7 @@ describe("setBaseCurrency", () => {
 
   // Success cases
   it("changes base currency", async () => {
-    const { db, spies } = createMockDb<DB>();
+    const { db, spies } = createMockDb<Transaction>();
     const newBaseCurrency = {
       ...baseCurrencyEUR,
       isBaseCurrency: true,
@@ -88,13 +70,9 @@ describe("setBaseCurrency", () => {
       .mockReturnValueOnce({ ...baseCurrencyUSD, isBaseCurrency: false }) // Remove base from old
       .mockReturnValueOnce(newBaseCurrency); // Set base on new
 
-    const result = await run(
-      db,
-      {
-        currencyId: baseCurrencyEUR.id,
-      },
-      ctx,
-    );
+    const result = await run(db, {
+      currencyId: baseCurrencyEUR.id,
+    });
 
     expect(result.ok).toBe(true);
     if (result.ok) {

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

@@ -1,11 +1,9 @@
-import { ok, err, type CommandContext } from "../../shared/internal";
-import { DB } from "../generated/kysely-tailordb";
+import { ok, err } from "../../../shared";
+import { Transaction } from "../generated/kysely-tailordb";
 import {
   CannotSetInactiveAsBaseCurrencyError,
   CurrencyNotFoundError,
 } from "../lib/errors.generated";
-import { getCurrency } from "../query/getCurrency.generated";
-import { getBaseCurrency } from "../query/getBaseCurrency.generated";
 
 export interface SetBaseCurrencyInput {
   currencyId: string;
@@ -17,9 +15,14 @@ export interface SetBaseCurrencyInput {
  * Changes the organization's base currency to a different active currency.
  * The base currency serves as the default for financial reporting.
  */
-export async function run(db: DB, input: SetBaseCurrencyInput, ctx: CommandContext) {
+export async function run(db: Transaction, input: SetBaseCurrencyInput) {
   // 1. Find currency by ID
-  const { currency } = await getCurrency(db, { id: input.currencyId }, ctx);
+  const currency = await db
+    .selectFrom("Currency")
+    .selectAll()
+    .where("id", "=", input.currencyId)
+    .forUpdate()
+    .executeTakeFirst();
 
   // 2. If not found, throw error
   if (!currency) {
@@ -37,7 +40,12 @@ export async function run(db: DB, input: SetBaseCurrencyInput, ctx: CommandConte
   }
 
   // 5. Find current base currency
-  const { currency: currentBase } = await getBaseCurrency(db, undefined, ctx);
+  const currentBase = await db
+    .selectFrom("Currency")
+    .selectAll()
+    .where("isBaseCurrency", "=", true)
+    .forUpdate()
+    .executeTakeFirst();
 
   // 6. Remove base flag from current base
   if (currentBase) {

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

@@ -1,5 +1,5 @@
 // @generated — do not edit
-import { defineCommand } from "../../shared/internal";
+import { defineCommand } from "../../../shared";
 import { permissions } from "../lib/permissions.generated";
 import { run } from "./setReferenceUnit";
 

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

@@ -1,30 +1,20 @@
 import { describe, expect, it } from "vitest";
-import { createMockDb } from "../../testing/index";
-import { type CommandContext } from "../../shared/internal";
-import { DB } from "../generated/kysely-tailordb";
+import { createMockDb } from "../../../testing/index";
+import { Transaction } from "../generated/kysely-tailordb";
 import { UnitNotFoundError, UnitNotInCategoryError } from "../lib/errors.generated";
 import { baseUoMCategory, baseUnitGram, baseUnitKg, baseUnitLiter } from "../testing/fixtures";
 import { run } from "./setReferenceUnit";
 
 describe("setReferenceUnit", () => {
-  const ctx: CommandContext = {
-    actorId: "test-actor",
-    permissions: ["primitives:setReferenceUnit"],
-  };
-
   // Error cases
   it("throws when unit doesn't exist", async () => {
-    const { db, spies } = createMockDb<DB>();
+    const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValue(undefined);
 
-    const result = await run(
-      db,
-      {
-        unitId: "nonexistent-unit",
-        categoryId: baseUoMCategory.id,
-      },
-      ctx,
-    );
+    const result = await run(db, {
+      unitId: "nonexistent-unit",
+      categoryId: baseUoMCategory.id,
+    });
 
     expect(result.ok).toBe(false);
     if (!result.ok) {
@@ -33,17 +23,13 @@ describe("setReferenceUnit", () => {
   });
 
   it("throws when unit is not in specified category", async () => {
-    const { db, spies } = createMockDb<DB>();
+    const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValue(baseUnitLiter); // Unit is in category-2, not category-1
 
-    const result = await run(
-      db,
-      {
-        unitId: baseUnitLiter.id,
-        categoryId: baseUoMCategory.id, // category-1
-      },
-      ctx,
-    );
+    const result = await run(db, {
+      unitId: baseUnitLiter.id,
+      categoryId: baseUoMCategory.id, // category-1
+    });
 
     expect(result.ok).toBe(false);
     if (!result.ok) {
@@ -53,19 +39,15 @@ describe("setReferenceUnit", () => {
 
   // Idempotent cases
   it("returns category unchanged when unit is already reference", async () => {
-    const { db, spies } = createMockDb<DB>();
+    const { db, spies } = createMockDb<Transaction>();
     spies.select
       .mockReturnValueOnce(baseUnitKg) // Unit lookup
       .mockReturnValueOnce(baseUoMCategory); // Category lookup
 
-    const result = await run(
-      db,
-      {
-        unitId: baseUnitKg.id,
-        categoryId: baseUoMCategory.id,
-      },
-      ctx,
-    );
+    const result = await run(db, {
+      unitId: baseUnitKg.id,
+      categoryId: baseUoMCategory.id,
+    });
 
     expect(result.ok).toBe(true);
     if (result.ok) {
@@ -76,7 +58,7 @@ describe("setReferenceUnit", () => {
 
   // Success cases
   it("changes reference unit and recalculates conversion factors", async () => {
-    const { db, spies } = createMockDb<DB>();
+    const { db, spies } = createMockDb<Transaction>();
     // gram has conversion factor 0.001 (1g = 0.001kg)
     // When gram becomes reference, kg should become 1000 (1kg = 1000g)
     const updatedCategory = {
@@ -94,14 +76,10 @@ describe("setReferenceUnit", () => {
       .mockReturnValueOnce({ ...baseUnitGram, conversionFactor: 1.0 }) // Update gram factor
       .mockReturnValueOnce(updatedCategory); // Update category
 
-    const result = await run(
-      db,
-      {
-        unitId: baseUnitGram.id,
-        categoryId: baseUoMCategory.id,
-      },
-      ctx,
-    );
+    const result = await run(db, {
+      unitId: baseUnitGram.id,
+      categoryId: baseUoMCategory.id,
+    });
 
     expect(result.ok).toBe(true);
     if (result.ok) {

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

@@ -1,9 +1,6 @@
-import { ok, err, type CommandContext } from "../../shared/internal";
-import { DB } from "../generated/kysely-tailordb";
+import { ok, err } from "../../../shared";
+import { Transaction } from "../generated/kysely-tailordb";
 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;
@@ -16,9 +13,14 @@ export interface SetReferenceUnitInput {
  * Changes the reference unit for a UoM category. All conversion factors
  * are recalculated relative to the new reference unit.
  */
-export async function run(db: DB, input: SetReferenceUnitInput, ctx: CommandContext) {
+export async function run(db: Transaction, input: SetReferenceUnitInput) {
   // 1. Find unit by ID
-  const { unit } = await getUnit(db, { id: input.unitId }, ctx);
+  const unit = await db
+    .selectFrom("Unit")
+    .selectAll()
+    .where("id", "=", input.unitId)
+    .forUpdate()
+    .executeTakeFirst();
 
   if (!unit) {
     return err(new UnitNotFoundError(input.unitId));
@@ -30,7 +32,12 @@ export async function run(db: DB, input: SetReferenceUnitInput, ctx: CommandCont
   }
 
   // 3. Get category
-  const { uoMCategory } = await getUoMCategory(db, { id: input.categoryId }, ctx);
+  const uoMCategory = await db
+    .selectFrom("UoMCategory")
+    .selectAll()
+    .where("id", "=", input.categoryId)
+    .forUpdate()
+    .executeTakeFirst();
 
   // 4. If already reference unit, return (idempotent)
   if (uoMCategory?.referenceUnitId === input.unitId && uoMCategory) {
@@ -38,7 +45,12 @@ export async function run(db: DB, input: SetReferenceUnitInput, ctx: CommandCont
   }
 
   // 5. Get all units in category for recalculation
-  const { units } = await listUnitsByCategory(db, { categoryId: input.categoryId }, ctx);
+  const units = await db
+    .selectFrom("Unit")
+    .selectAll()
+    .where("categoryId", "=", input.categoryId)
+    .forUpdate()
+    .execute();
 
   // 6. Recalculate all conversion factors
   // new_factor = old_factor / new_reference_old_factor

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

@@ -31,3 +31,9 @@ flowchart TD
 ## Error Scenarios
 
 - **UOM_CATEGORY_NOT_FOUND**: Specified category ID does not exist
+
+## Test Cases
+
+- throws when category doesn
+- returns category unchanged when already active
+- activates inactive category

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

@@ -30,3 +30,9 @@ flowchart TD
 ## Error Scenarios
 
 - **CURRENCY_NOT_FOUND**: Specified currency ID does not exist
+
+## Test Cases
+
+- throws when currency doesn
+- returns currency unchanged when already active
+- activates inactive currency

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

@@ -31,3 +31,9 @@ flowchart TD
 ## Error Scenarios
 
 - **UNIT_NOT_FOUND**: Specified unit ID does not exist
+
+## Test Cases
+
+- throws when unit doesn
+- returns unit unchanged when already active
+- activates inactive unit

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

@@ -39,3 +39,9 @@ flowchart TD
 ## Error Scenarios
 
 - **DUPLICATE_CATEGORY_NAME**: Category with same name already exists
+
+## Test Cases
+
+- throws when category name already exists
+- creates category with reference unit
+- passes custom fields through to insert

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

@@ -44,3 +44,13 @@ flowchart TD
 - **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)
+
+## Test Cases
+
+- throws when ISO code is invalid format
+- throws when ISO code already exists
+- throws when decimal places is negative
+- throws when decimal places exceeds maximum
+- creates first currency as base currency
+- creates subsequent currency as non-base
+- passes custom fields through to insert

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

@@ -45,3 +45,14 @@ flowchart TD
 - **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
+
+## Test Cases
+
+- throws when source currency doesn
+- throws when source currency is inactive
+- throws when target currency doesn
+- throws when target currency is inactive
+- throws when source and target are the same
+- throws when rate is not positive
+- creates exchange rate successfully
+- passes custom fields through to insert

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

@@ -46,3 +46,13 @@ flowchart TD
 - **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
+
+## Test Cases
+
+- throws when category doesn
+- throws when category is inactive
+- throws when symbol already exists in category
+- throws when conversion factor is not positive
+- throws when rounding precision is negative
+- creates unit successfully
+- passes custom fields through to insert

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

@@ -35,3 +35,10 @@ flowchart TD
 
 - **UOM_CATEGORY_NOT_FOUND**: Specified category ID does not exist
 - **CATEGORY_HAS_ACTIVE_UNITS**: Category still contains active units that must be deactivated first
+
+## Test Cases
+
+- throws when category doesn
+- throws when category has active units
+- returns category unchanged when already inactive
+- deactivates active category with no active units

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

@@ -35,3 +35,10 @@ flowchart TD
 
 - **CURRENCY_NOT_FOUND**: Specified currency ID does not exist
 - **CANNOT_DEACTIVATE_BASE_CURRENCY**: Attempting to deactivate the base currency, must change base currency first
+
+## Test Cases
+
+- throws when currency doesn
+- throws when attempting to deactivate base currency
+- returns currency unchanged when already inactive
+- deactivates active non-base currency

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

@@ -35,3 +35,10 @@ flowchart TD
 
 - **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
+
+## Test Cases
+
+- throws when unit doesn
+- throws when attempting to deactivate reference unit
+- returns unit unchanged when already inactive
+- deactivates active non-reference unit

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

@@ -36,3 +36,10 @@ flowchart TD
 
 - **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
+
+## Test Cases
+
+- throws when currency doesn
+- throws when currency is inactive
+- returns currency unchanged when already base
+- changes base currency

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

@@ -40,3 +40,10 @@ flowchart TD
 
 - **UNIT_NOT_FOUND**: Specified unit ID does not exist
 - **UNIT_NOT_IN_CATEGORY**: Unit belongs to a different category than specified
+
+## Test Cases
+
+- throws when unit doesn
+- throws when unit is not in specified category
+- returns category unchanged when unit is already reference
+- changes reference unit and recalculates conversion factors

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

@@ -46,3 +46,17 @@ flowchart TD
 - **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
+
+## Test Cases
+
+- returns error when source currency doesn
+- returns error when target currency doesn
+- returns error when source currency is inactive
+- returns error when target currency is inactive
+- returns error when no exchange rate exists for the currency pair
+- returns same amount when source and target are the same currency
+- converts USD to EUR using direct rate
+- uses inverse rate when no direct rate exists
+- uses most recent rate on or before the conversion date
+- rounds to target currency decimal places (JPY has 0)
+- handles zero amount correctly

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

@@ -39,3 +39,16 @@ flowchart TD
 - **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
+
+## Test Cases
+
+- returns error when source unit doesn
+- returns error when target unit doesn
+- returns error when source unit is inactive
+- returns error when target unit is inactive
+- returns error when units belong to different categories
+- returns same quantity when source and target are the same unit
+- converts kg to grams correctly
+- converts grams to kg correctly
+- converts pounds to kg correctly
+- handles zero quantity correctly

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

@@ -30,3 +30,8 @@ flowchart TD
 ## Error Scenarios
 
 - None (returns null when no base currency is set instead of throwing)
+
+## Test Cases
+
+- returns base currency when set
+- returns null when no base currency is set

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

@@ -34,3 +34,10 @@ flowchart TD
 ## Error Scenarios
 
 - None (returns null when not found instead of throwing)
+
+## Test Cases
+
+- returns currency when found
+- returns null when currency not found
+- returns currency when found
+- returns null when currency not found

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

@@ -34,3 +34,10 @@ flowchart TD
 ## Error Scenarios
 
 - None (returns null when not found instead of throwing)
+
+## Test Cases
+
+- returns unit when found
+- returns null when unit not found
+- returns unit when found
+- returns null when unit not found

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

@@ -34,3 +34,10 @@ flowchart TD
 ## Error Scenarios
 
 - None (returns null when not found instead of throwing)
+
+## Test Cases
+
+- returns category when found
+- returns null when category not found
+- returns category when found
+- returns null when category not found

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

@@ -2,19 +2,21 @@
 
 ## Overview
 
-ListUnitsByCategory retrieves all units belonging to a specific UoM category. Used to find related units within a category and to validate category constraints such as ensuring a category has units before deactivation.
+ListUnitsByCategory retrieves paginated units belonging to a specific UoM category. Used to find related units within a category and to validate category constraints such as ensuring a category has units before deactivation.
 
 ## Business Rules
 
-- Returns all units with the matching categoryId
-- Returns empty array if no units match
+- Returns paginated units with the matching categoryId
+- Returns empty result if no units match
+- Supports limit, offset, orderBy, and orderDirection parameters
+- Indicates whether more results exist via hasNextPage
 
 ## Process Flow
 
 ```mermaid
 flowchart TD
-    A[Receive categoryId] --> B[SELECT from Unit where categoryId = input]
-    B --> C[Return units array]
+    A[Receive categoryId and pagination params] --> B[SELECT from Unit where categoryId = input with limit+1, offset, order]
+    B --> C[Build paginated result with items and hasNextPage]
 ```
 
 ## External Dependencies
@@ -24,3 +26,11 @@ flowchart TD
 ## Error Scenarios
 
 - None
+
+## Test Cases
+
+- returns paginated units with default page size
+- returns hasNextPage true when more results exist
+- returns empty result when no units match
+- respects custom limit and offset
+- accepts orderBy and orderDirection