@tailor-platform/erp-kit 0.1.1 → 0.1.2

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/index.ts

@@ -28,13 +28,13 @@ export {
 } from "./lib/errors";
 
 // input types
-export { type ConvertQuantityInput } from "./command/convertQuantity";
+export { type ConvertQuantityInput } from "./query/convertQuantity";
 export { type ActivateCategoryInput } from "./command/activateCategory";
 export { type DeactivateCategoryInput } from "./command/deactivateCategory";
 export { type SetReferenceUnitInput } from "./command/setReferenceUnit";
 export { type ActivateUnitInput } from "./command/activateUnit";
 export { type DeactivateUnitInput } from "./command/deactivateUnit";
-export { type ConvertAmountInput } from "./command/convertAmount";
+export { type ConvertAmountInput } from "./query/convertAmount";
 export { type ActivateCurrencyInput } from "./command/activateCurrency";
 export { type DeactivateCurrencyInput } from "./command/deactivateCurrency";
 export { type SetBaseCurrencyInput } from "./command/setBaseCurrency";

package/src/modules/primitives/module.ts

@@ -9,11 +9,11 @@ import { deactivateCategory } from "./command/deactivateCategory";
 import { activateUnit } from "./command/activateUnit";
 import { deactivateUnit } from "./command/deactivateUnit";
 import { setReferenceUnit } from "./command/setReferenceUnit";
-import { convertQuantity } from "./command/convertQuantity";
+import { convertQuantity } from "./query/convertQuantity";
 import { activateCurrency } from "./command/activateCurrency";
 import { deactivateCurrency } from "./command/deactivateCurrency";
 import { setBaseCurrency } from "./command/setBaseCurrency";
-import { convertAmount } from "./command/convertAmount";
+import { convertAmount } from "./query/convertAmount";
 import { createUoMCategoryType, CreateUoMCategoryTypeParams } from "./db/uomCategory";
 import { createUnitType, CreateUnitTypeParams } from "./db/unit";
 import { createCurrencyType, CreateCurrencyTypeParams } from "./db/currency";
@@ -56,10 +56,12 @@ export const defineModule = <
       activateUnit,
       deactivateUnit,
       setReferenceUnit,
-      convertQuantity,
       activateCurrency,
       deactivateCurrency,
       setBaseCurrency,
+    },
+    queries: {
+      convertQuantity,
       convertAmount,
     },
   };

package/src/modules/primitives/permissions.ts

@@ -1,7 +1,6 @@
 import { definePermissions } from "../shared/internal";
 
 export const { permissions, own, all } = definePermissions("primitives", [
-  "convertQuantity",
   "createCategory",
   "activateCategory",
   "deactivateCategory",
@@ -9,7 +8,6 @@ export const { permissions, own, all } = definePermissions("primitives", [
   "createUnit",
   "activateUnit",
   "deactivateUnit",
-  "convertAmount",
   "createCurrency",
   "activateCurrency",
   "deactivateCurrency",

package/src/modules/primitives/{command → query}/convertAmount.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest";
-import { InsufficientPermissionError, type CommandContext } from "../../shared/internal";
 import { createMockDb } from "../../testing/index";
 import { DB } from "../generated/kysely-tailordb";
+import type { QueryContext } from "../../shared/internal";
 import {
   CurrencyNotFoundError,
   ExchangeRateNotFoundError,
@@ -19,7 +19,7 @@ import {
 import { convertAmount } from "./convertAmount";
 
 describe("convertAmount", () => {
-  const ctx: CommandContext = { actorId: "test-actor", permissions: ["primitives:convertAmount"] };
+  const ctx: QueryContext = { actorId: "test-actor" };
 
   // Error cases first
   it("throws when source currency doesn't exist", async () => {
@@ -255,21 +255,4 @@ describe("convertAmount", () => {
 
     expect(result.convertedAmount).toBe(0);
   });
-
-  it("throws when permission is missing", async () => {
-    const { db } = createMockDb<DB>();
-    const denied: CommandContext = { actorId: "test-actor", permissions: [] };
-    await expect(
-      convertAmount(
-        db,
-        {
-          amount: 100,
-          sourceCurrencyCode: "USD",
-          targetCurrencyCode: "EUR",
-          conversionDate: "2024-01-15",
-        },
-        denied,
-      ),
-    ).rejects.toBeInstanceOf(InsufficientPermissionError);
-  });
 });

package/src/modules/primitives/query/convertAmount.ts

@@ -0,0 +1,122 @@
+import { defineQuery, type ReadonlyDB } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
+import {
+  CurrencyNotFoundError,
+  ExchangeRateNotFoundError,
+  InactiveCurrencyError,
+} from "../lib/errors";
+
+export interface ConvertAmountInput {
+  amount: number;
+  sourceCurrencyCode: string;
+  targetCurrencyCode: string;
+  conversionDate: string;
+}
+
+/**
+ * Function: convertAmount
+ *
+ * Converts a monetary amount from one currency to another using the applicable
+ * exchange rate for a given date. Currencies are identified by their ISO 4217
+ * code (e.g., "USD", "EUR", "JPY"). The function looks up the most recent exchange
+ * rate on or before the specified date. If no direct rate exists, it calculates
+ * the inverse rate. Result is rounded to the target currency's decimal precision.
+ */
+export const convertAmount = defineQuery(async (db: ReadonlyDB<DB>, input: ConvertAmountInput) => {
+  // 1. Validate source currency exists
+  const sourceCurrency = await db
+    .selectFrom("Currency")
+    .selectAll()
+    .where("code", "=", input.sourceCurrencyCode)
+    .executeTakeFirst();
+
+  if (!sourceCurrency) {
+    throw new CurrencyNotFoundError(input.sourceCurrencyCode);
+  }
+
+  // 2. Validate target currency exists
+  const targetCurrency = await db
+    .selectFrom("Currency")
+    .selectAll()
+    .where("code", "=", input.targetCurrencyCode)
+    .executeTakeFirst();
+
+  if (!targetCurrency) {
+    throw new CurrencyNotFoundError(input.targetCurrencyCode);
+  }
+
+  // 3. Validate both currencies are active
+  if (!sourceCurrency.isActive) {
+    throw new InactiveCurrencyError(input.sourceCurrencyCode);
+  }
+
+  if (!targetCurrency.isActive) {
+    throw new InactiveCurrencyError(input.targetCurrencyCode);
+  }
+
+  // 4. Same currency - return original amount
+  if (sourceCurrency.id === targetCurrency.id) {
+    return {
+      convertedAmount: input.amount,
+      exchangeRate: 1,
+      sourceCurrency,
+      targetCurrency,
+      exchangeRateRecord: null,
+    };
+  }
+
+  // 5. Find direct exchange rate (most recent on or before conversion date)
+  const conversionDate = new Date(input.conversionDate);
+  const directRate = await db
+    .selectFrom("ExchangeRate")
+    .selectAll()
+    .where("sourceCurrencyId", "=", sourceCurrency.id)
+    .where("targetCurrencyId", "=", targetCurrency.id)
+    .where("effectiveDate", "<=", conversionDate)
+    .orderBy("effectiveDate", "desc")
+    .executeTakeFirst();
+
+  let exchangeRate: number;
+  let exchangeRateRecord = null;
+
+  if (directRate) {
+    exchangeRate = directRate.rate;
+    exchangeRateRecord = directRate;
+  } else {
+    // 6. Try inverse rate
+    const inverseRate = await db
+      .selectFrom("ExchangeRate")
+      .selectAll()
+      .where("sourceCurrencyId", "=", targetCurrency.id)
+      .where("targetCurrencyId", "=", sourceCurrency.id)
+      .where("effectiveDate", "<=", conversionDate)
+      .orderBy("effectiveDate", "desc")
+      .executeTakeFirst();
+
+    if (!inverseRate) {
+      throw new ExchangeRateNotFoundError(
+        input.sourceCurrencyCode,
+        input.targetCurrencyCode,
+        input.conversionDate,
+      );
+    }
+
+    exchangeRate = 1 / inverseRate.rate;
+    exchangeRateRecord = inverseRate;
+  }
+
+  // 7. Calculate converted amount
+  const rawResult = input.amount * exchangeRate;
+
+  // 8. Round to target currency's decimal places
+  const roundingFactor = Math.pow(10, targetCurrency.decimalPlaces);
+  const convertedAmount = Math.round(rawResult * roundingFactor) / roundingFactor;
+
+  return {
+    convertedAmount,
+    exchangeRate,
+    sourceCurrency,
+    targetCurrency,
+    exchangeRateRecord,
+  };
+});

package/src/modules/primitives/{command → query}/convertQuantity.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest";
 import { createMockDb } from "../../testing/index";
-import { InsufficientPermissionError, type CommandContext } from "../../shared/internal";
 import { DB } from "../generated/kysely-tailordb";
+import type { QueryContext } from "../../shared/internal";
 import { InactiveUnitError, IncompatibleUnitsError, UnitNotFoundError } from "../lib/errors";
 import {
   baseUnitGram,
@@ -13,10 +13,7 @@ import {
 import { convertQuantity } from "./convertQuantity";
 
 describe("convertQuantity", () => {
-  const ctx: CommandContext = {
-    actorId: "test-actor",
-    permissions: ["primitives:convertQuantity"],
-  };
+  const ctx: QueryContext = { actorId: "test-actor" };
 
   // Error cases first
   it("throws when source unit doesn't exist", async () => {
@@ -208,12 +205,4 @@ describe("convertQuantity", () => {
 
     expect(result.convertedQuantity).toBe(0);
   });
-
-  it("throws when permission is missing", async () => {
-    const { db } = createMockDb<DB>();
-    const denied: CommandContext = { actorId: "test-actor", permissions: [] };
-    await expect(
-      convertQuantity(db, { quantity: 1, sourceUnitSymbol: "kg", targetUnitSymbol: "g" }, denied),
-    ).rejects.toBeInstanceOf(InsufficientPermissionError);
-  });
 });

package/src/modules/primitives/{command → query}/convertQuantity.ts

@@ -1,7 +1,6 @@
-import { defineCommand } from "../../shared/internal";
-import { DB } from "../generated/kysely-tailordb";
+import { defineQuery, type ReadonlyDB } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
 import { InactiveUnitError, IncompatibleUnitsError, UnitNotFoundError } from "../lib/errors";
-import { permissions } from "../permissions";
 
 export interface ConvertQuantityInput {
   quantity: number;
@@ -17,9 +16,8 @@ export interface ConvertQuantityInput {
  * The conversion uses each unit's conversion factor relative to the category's reference unit.
  * Result is rounded to the target unit's precision setting.
  */
-export const convertQuantity = defineCommand(
-  permissions.convertQuantity,
-  async (db: DB, input: ConvertQuantityInput) => {
+export const convertQuantity = defineQuery(
+  async (db: ReadonlyDB<DB>, input: ConvertQuantityInput) => {
     // 1. Validate source unit exists
     const sourceUnit = await db
       .selectFrom("Unit")

package/src/modules/shared/defineQuery.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it, vi } from "vitest";
+import { defineQuery } from "./defineQuery";
+import type { QueryContext } from "./types";
+
+describe("defineQuery", () => {
+  const ctx: QueryContext = { actorId: "user-1" };
+
+  it("calls impl with db, input, and ctx", async () => {
+    const impl = vi.fn().mockResolvedValue({ result: "ok" });
+    const query = defineQuery(impl);
+
+    const result = await query("fake-db", { foo: "bar" }, ctx);
+
+    expect(result).toEqual({ result: "ok" });
+    expect(impl).toHaveBeenCalledWith("fake-db", { foo: "bar" }, ctx);
+  });
+
+  it("passes ctx with actorId to impl", async () => {
+    const impl = vi.fn().mockResolvedValue({});
+    const query = defineQuery(impl);
+
+    await query("fake-db", { x: 1 }, ctx);
+
+    expect(impl).toHaveBeenCalledTimes(1);
+    expect(impl.mock.calls[0]).toHaveLength(3);
+    expect(impl.mock.calls[0][2]).toEqual({ actorId: "user-1" });
+  });
+});

package/src/modules/shared/defineQuery.ts

@@ -0,0 +1,16 @@
+import type { QueryContext } from "./types";
+
+export type Query<TInput, TResult> = (
+  db: unknown,
+  input: TInput,
+  ctx: QueryContext,
+) => Promise<TResult>;
+
+export function defineQuery<TInput, TResult>(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  impl: (db: any, input: TInput, ctx: QueryContext) => Promise<TResult>,
+): Query<TInput, TResult> {
+  return async (db, input, ctx) => {
+    return impl(db, input, ctx);
+  };
+}

package/src/modules/shared/internal.ts

@@ -1,8 +1,9 @@
 export { defineCommand, type Command } from "./defineCommand";
+export { defineQuery, type Query } from "./defineQuery";
 export { definePermissions } from "./definePermissions";
 export { requirePermission } from "./requirePermission";
 export { createDomainError, InsufficientPermissionError } from "./errors";
-export type { CommandContext } from "./types";
+export type { CommandContext, QueryContext, ReadonlyDB } from "./types";
 export type {
   InferSchema,
   Selectable,

package/src/modules/shared/types.ts

@@ -1,4 +1,12 @@
+export interface QueryContext {
+  actorId: string;
+}
+
 export interface CommandContext {
   actorId: string;
   permissions: readonly string[];
 }
+
+// Strips write methods (updateTable, insertInto, deleteFrom) from a Kysely DB instance.
+// Query handlers use this instead of the full DB type to get compile-time write prevention.
+export type ReadonlyDB<T extends { selectFrom: unknown }> = Pick<T, "selectFrom">;

package/src/modules/user-management/docs/models/AuditEvent.md

@@ -16,6 +16,8 @@ AppendOnly
 
 - [logAuditEvent](../commands/LogAuditEvent.md)
 
+### Query Definitions
+
 ### Models
 
 - AuditEvent

package/src/modules/user-management/docs/models/Permission.md

@@ -16,6 +16,8 @@ Standard
 
 - [createPermission](../commands/CreatePermission.md)
 
+### Query Definitions
+
 ### Models
 
 - Permission

package/src/modules/user-management/docs/models/Role.md

@@ -16,6 +16,8 @@ Standard
 
 - [createRole](../commands/CreateRole.md)
 
+### Query Definitions
+
 ### Models
 
 - Role

package/src/modules/user-management/docs/models/RolePermission.md

@@ -17,6 +17,8 @@ Standard
 - [assignPermissionToRole](../commands/AssignPermissionToRole.md)
 - [revokePermissionFromRole](../commands/RevokePermissionFromRole.md)
 
+### Query Definitions
+
 ### Models
 
 - RolePermission

package/src/modules/user-management/docs/models/User.md

@@ -29,6 +29,8 @@ stateDiagram-v2
 - [deactivateUser](../commands/DeactivateUser.md)
 - [reactivateUser](../commands/ReactivateUser.md)
 
+### Query Definitions
+
 ### Models
 
 - User

package/src/modules/user-management/docs/models/UserRole.md

@@ -17,6 +17,8 @@ Standard
 - [assignRoleToUser](../commands/AssignRoleToUser.md)
 - [revokeRoleFromUser](../commands/RevokeRoleFromUser.md)
 
+### Query Definitions
+
 ### Models
 
 - UserRole

package/src/schemas.ts

@@ -8,6 +8,7 @@ export const MODULE_SCHEMAS = {
   command: path.join(SCHEMAS_ROOT, "module", "command.yml"),
   model: path.join(SCHEMAS_ROOT, "module", "model.yml"),
   feature: path.join(SCHEMAS_ROOT, "module", "feature.yml"),
+  query: path.join(SCHEMAS_ROOT, "module", "query.yml"),
 } as const;
 
 export const APP_COMPOSE_SCHEMAS = {

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

@@ -1,126 +0,0 @@
-import { defineCommand } from "../../shared/internal";
-import { DB } from "../generated/kysely-tailordb";
-import {
-  CurrencyNotFoundError,
-  ExchangeRateNotFoundError,
-  InactiveCurrencyError,
-} from "../lib/errors";
-import { permissions } from "../permissions";
-
-export interface ConvertAmountInput {
-  amount: number;
-  sourceCurrencyCode: string;
-  targetCurrencyCode: string;
-  conversionDate: string;
-}
-
-/**
- * Function: convertAmount
- *
- * Converts a monetary amount from one currency to another using the applicable
- * exchange rate for a given date. Currencies are identified by their ISO 4217
- * code (e.g., "USD", "EUR", "JPY"). The function looks up the most recent exchange
- * rate on or before the specified date. If no direct rate exists, it calculates
- * the inverse rate. Result is rounded to the target currency's decimal precision.
- */
-export const convertAmount = defineCommand(
-  permissions.convertAmount,
-  async (db: DB, input: ConvertAmountInput) => {
-    // 1. Validate source currency exists
-    const sourceCurrency = await db
-      .selectFrom("Currency")
-      .selectAll()
-      .where("code", "=", input.sourceCurrencyCode)
-      .executeTakeFirst();
-
-    if (!sourceCurrency) {
-      throw new CurrencyNotFoundError(input.sourceCurrencyCode);
-    }
-
-    // 2. Validate target currency exists
-    const targetCurrency = await db
-      .selectFrom("Currency")
-      .selectAll()
-      .where("code", "=", input.targetCurrencyCode)
-      .executeTakeFirst();
-
-    if (!targetCurrency) {
-      throw new CurrencyNotFoundError(input.targetCurrencyCode);
-    }
-
-    // 3. Validate both currencies are active
-    if (!sourceCurrency.isActive) {
-      throw new InactiveCurrencyError(input.sourceCurrencyCode);
-    }
-
-    if (!targetCurrency.isActive) {
-      throw new InactiveCurrencyError(input.targetCurrencyCode);
-    }
-
-    // 4. Same currency - return original amount
-    if (sourceCurrency.id === targetCurrency.id) {
-      return {
-        convertedAmount: input.amount,
-        exchangeRate: 1,
-        sourceCurrency,
-        targetCurrency,
-        exchangeRateRecord: null,
-      };
-    }
-
-    // 5. Find direct exchange rate (most recent on or before conversion date)
-    const conversionDate = new Date(input.conversionDate);
-    const directRate = await db
-      .selectFrom("ExchangeRate")
-      .selectAll()
-      .where("sourceCurrencyId", "=", sourceCurrency.id)
-      .where("targetCurrencyId", "=", targetCurrency.id)
-      .where("effectiveDate", "<=", conversionDate)
-      .orderBy("effectiveDate", "desc")
-      .executeTakeFirst();
-
-    let exchangeRate: number;
-    let exchangeRateRecord = null;
-
-    if (directRate) {
-      exchangeRate = directRate.rate;
-      exchangeRateRecord = directRate;
-    } else {
-      // 6. Try inverse rate
-      const inverseRate = await db
-        .selectFrom("ExchangeRate")
-        .selectAll()
-        .where("sourceCurrencyId", "=", targetCurrency.id)
-        .where("targetCurrencyId", "=", sourceCurrency.id)
-        .where("effectiveDate", "<=", conversionDate)
-        .orderBy("effectiveDate", "desc")
-        .executeTakeFirst();
-
-      if (!inverseRate) {
-        throw new ExchangeRateNotFoundError(
-          input.sourceCurrencyCode,
-          input.targetCurrencyCode,
-          input.conversionDate,
-        );
-      }
-
-      exchangeRate = 1 / inverseRate.rate;
-      exchangeRateRecord = inverseRate;
-    }
-
-    // 7. Calculate converted amount
-    const rawResult = input.amount * exchangeRate;
-
-    // 8. Round to target currency's decimal places
-    const roundingFactor = Math.pow(10, targetCurrency.decimalPlaces);
-    const convertedAmount = Math.round(rawResult * roundingFactor) / roundingFactor;
-
-    return {
-      convertedAmount,
-      exchangeRate,
-      sourceCurrency,
-      targetCurrency,
-      exchangeRateRecord,
-    };
-  },
-);