@tailor-platform/erp-kit 0.1.0 → 0.1.2

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/rules/app-compose/frontend/auth.md

@@ -1,55 +0,0 @@
----
-paths:
-  - "examples/**/frontend/src/App.tsx"
-  - "examples/**/frontend/src/lib/auth-client.ts"
-  - "examples/**/frontend/src/providers/graphql-provider.tsx"
----
-
-# Frontend Auth (AppShell AuthProvider)
-
-Use `@tailor-platform/app-shell` authentication as the default pattern for frontend apps.
-
-## Required Environment Variables
-
-- `VITE_TAILOR_APP_URL`
-- `VITE_TAILOR_CLIENT_ID`
-
-Fail fast at startup if either value is missing.
-
-## Auth Client Initialization
-
-Create a single shared auth client in `src/lib/auth-client.ts`:
-
-- Use `createAuthClient({ appUri, clientId })`
-- Export it as `authClient`
-- Do not create auth clients inside render functions
-
-## App Root Composition
-
-Wrap the app with `AuthProvider` in `src/App.tsx`:
-
-- `AuthProvider` must receive the shared `authClient`
-- Use `guardComponent` for unauthenticated/loading states
-- `guardComponent` should use `useAuth()` and handle:
-  - `!isReady`: loading UI
-  - `!isAuthenticated`: login UI with `login()`
-  - `error`: visible message
-
-Recommended order:
-
-1. `AuthProvider`
-2. `GraphQLProvider`
-3. `AppShell`
-
-## GraphQL Authentication
-
-`src/providers/graphql-provider.tsx` must attach OAuth headers for every request:
-
-- Accept `authClient` as a prop
-- Call `authClient.getAuthHeadersForQuery()`
-- Set both headers:
-  - `Authorization`
-  - `DPoP`
-- Keep `Content-Type: application/json`
-
-Do not use unauthenticated static headers for `/query`.

package/rules/app-compose/frontend/page.md

@@ -1,86 +0,0 @@
----
-paths:
-  - "examples/**/src/pages/**/page.tsx"
----
-
-# Page File Structure (File-Based Routing)
-
-Each `page.tsx` file should contain a default-exported page component with optional `appShellPageProps` static field.
-Pages are automatically discovered by the Vite plugin.
-
-## Path Convention
-
-The URL path is derived from the directory structure:
-
-```
-src/pages/
-├── page.tsx                  # / (root path)
-├── purchasing/
-│   ├── page.tsx              # /purchasing
-│   └── orders/
-│       ├── page.tsx          # /purchasing/orders
-│       └── [id]/
-│           └── page.tsx      # /purchasing/orders/:id
-└── (admin)/                  # Grouping (not included in path)
-    └── settings/
-        └── page.tsx          # /settings
-```
-
-| Directory Name | Converts To | Description                   |
-| -------------- | ----------- | ----------------------------- |
-| `orders`       | `orders`    | Static segment                |
-| `[id]`         | `:id`       | Dynamic parameter             |
-| `(group)`      | (excluded)  | Grouping only (not in path)   |
-| `_lib`         | (ignored)   | Not routed (for shared logic) |
-
-## Page Component Pattern
-
-```tsx
-import { Layout, type AppShellPageProps } from "@tailor-platform/app-shell";
-import { useQuery } from "urql";
-import { graphql } from "@/graphql";
-import { ErrorFallback } from "@/components/composed/error-fallback";
-import { Loading } from "@/components/composed/loading";
-
-const MyQuery = graphql(`...`);
-
-const MyPage = () => {
-  const [{ data, error, fetching }, reexecuteQuery] = useQuery({
-    query: MyQuery,
-  });
-
-  if (fetching) return <Loading />;
-
-  if (error || !data) {
-    return (
-      <ErrorFallback
-        title="Failed to load"
-        message="An error occurred while fetching data."
-        onReset={() => reexecuteQuery({ requestPolicy: "network-only" })}
-      />
-    );
-  }
-
-  return (
-    <Layout columns={1} title="My Page">
-      <Layout.Column>
-        <MyComponent data={data} />
-      </Layout.Column>
-    </Layout>
-  );
-};
-
-MyPage.appShellPageProps = {
-  meta: { title: "My Page" },
-} satisfies AppShellPageProps;
-
-export default MyPage;
-```
-
-## Key Points
-
-- Handle `fetching` state with `<Loading />`
-- Handle `error || !data` with `<ErrorFallback />` and `reexecuteQuery` for retry
-- Use `appShellPageProps` static field for metadata (title, icon) and guards
-- Guards on parent pages are automatically inherited by child pages
-- See `component.md` for fragment collocation

package/rules/module-development/cross-module-type-injection.md

@@ -1,28 +0,0 @@
----
-paths:
-  - "modules/*/src/db/*.ts"
-  - "modules/*/src/module.ts"
----
-
-# Cross-Module Type Injection
-
-## Typing External Module References
-
-- Derive types from the source module's `defineModule` return type, never use `any`
-- Use `import type` for type-only imports
-- All modules live in the same package (`@tailor-platform/erp-kit`), so use relative paths
-- Define a local type alias for readability: `type UnitType = ReturnType<typeof definePrimitivesModule>["unit"]`
-
-## DB Type Creator Pattern (`src/db/*.ts`)
-
-- Accept optional external type via `Create*TypeParams` (e.g., `unitType?: UnitType`)
-- Use a ternary on the param to conditionally add `.relation()`:
-  - **Present**: `db.uuid().relation({ type: "n-1", toward: { type: param }, backward: "..." })`
-  - **Absent**: `db.uuid()` (plain UUID, no relation) — preserves standalone usage
-- Export a default instance at file bottom with `{}` params for internal/standalone use
-
-## Module Wiring (`src/module.ts`)
-
-- Group external dependencies under a `primitives?` key in `DefineModuleParams`
-- Spread consumer's `Create*TypeParams` and merge the injected type: `{ ...params.productTemplate, unitType: params.primitives?.unit }`
-- Export `DefineModuleParams` type from `index.ts` so consumers can type their config

package/rules/module-development/dependency-modules.md

@@ -1,24 +0,0 @@
----
-paths:
-  - "modules/*/src/"
----
-
-# Dependency Modules
-
-When a module depends on another module, create `modules/<module-name>/src/dep.ts` to instantiate and re-export the dependency:
-
-```typescript
-import { defineModule } from "../../primitives/src/module";
-
-const primitives = defineModule();
-
-// Re-export db types for use in this module's db definitions and commands
-export const { unit, currency } = primitives.db;
-```
-
-## Module Return Structure
-
-`defineModule` returns an object with:
-
-- `db`: Object of database model types (keyed by name)
-- `executors`: Object of executor instances (keyed by name, if any)

package/rules/module-development/executors.md

@@ -1,67 +0,0 @@
----
-paths:
-  - "modules/*/src/executor/"
-  - "modules/*/src/module.ts"
----
-
-# Executors
-
-Executors handle asynchronous operations triggered by database record changes.
-
-## Factory Pattern
-
-Executors are **factory functions** that accept configuration and return an executor:
-
-```typescript
-export const myExecutor = function myExecutor({ namespace }: { namespace: string }) {
-  return createExecutor({
-    name: "myExecutor",
-    // ... executor config
-  });
-};
-```
-
-**Why factory functions:**
-
-- Executors need runtime configuration (db namespace) not known at import time
-- Named function expression enables better stack traces
-- Module consumers control configuration via `defineModule` params
-
-## File Organization
-
-- Place in `src/executor/` directory
-- Group related executors in one file (e.g., `recomputeOnRolePermissionChange.ts`)
-- Name files after the operation, not the trigger
-
-## Executor Structure
-
-Required fields:
-
-- `name`: Matches function name exactly
-- `description`: Human-readable purpose
-- `trigger`: `recordCreatedTrigger` or `recordDeletedTrigger` with `type`
-- `operation`: `kind: "jobFunction"` with async `body`
-
-## Database Access
-
-Use namespace parameter with `getDB`:
-
-```typescript
-// @ts-expect-error unsure at build time
-const db = getDB(namespace);
-```
-
-The `@ts-expect-error` comment is required because the namespace is validated at runtime.
-
-## Module Integration
-
-`defineModule` returns executors in a dedicated array:
-
-```typescript
-return {
-  db: [user, role, ...],
-  executors: [rolePermissionCreated, rolePermissionDeleted],
-};
-```
-
-Instantiate executors in `module.ts` with the `dbNamespace` parameter.