@tailor-platform/erp-kit 0.1.1 → 0.2.0

package/skills/4-module-tdd-implementation/references/commands.md

@@ -1,45 +0,0 @@
-# Command Implementation
-
-## Dual Function Pattern
-
-Two functions per operation: internal `_fn` and public `fn`.
-
-**Internal function (`_myFunction`):**
-
-- Takes concrete `DB` type from `generated/kysely-tailordb`
-- Return type uses `Schema` from `lib/types`: `Promise<{ entity: Entity<Schema> }>`
-- Contains actual implementation
-
-**Public function (`myFunction`):**
-
-- Generic signature: `<T extends { Entity: object }>(db: Kysely<T>, ...)`
-- Return type uses generic `T`: `Promise<{ entity: Entity<T> }>`
-- Delegates to internal with type casting: `_fn(db as unknown as DB, ...) as unknown as Result`
-
-## Implementation Considerations
-
-- **Validation**: Check referenced entities exist before operating
-- **Idempotency**: For assign/revoke, return existing instead of throwing
-- **Return format**: Wrap in object `{ entity }` not just `entity`
-
-## Conventions
-
-- Input types: exported interfaces (`export interface MyFunctionInput`)
-- Use `.executeTakeFirst()` for single results
-- Include JSDoc: `/** Function: name \n Description */`
-
-## State Transitions
-
-For commands that transition between statuses, accept `from?: string[]` with a default:
-
-```typescript
-from?: string[];  // Default: ["ACTIVE"]
-
-const validFromStatuses = input.from ?? ["ACTIVE"];
-if (!validFromStatuses.includes(user.status)) {
-  throw new InvalidStatusTransitionError(user.status, targetStatus);
-}
-```
-
-- Default `from` contains the base valid source status
-- Parent modules can override to allow transitions from additional statuses

package/skills/4-module-tdd-implementation/references/errors.md

@@ -1,7 +0,0 @@
-# Error Classes
-
-Naming convention:
-
-- `name`: Class name exactly, `as const`
-- `code`: SCREAMING_SNAKE_CASE, `as const`
-- Constructor includes context (IDs, values)

package/skills/4-module-tdd-implementation/references/models.md

@@ -1,30 +0,0 @@
-# Database Models
-
-## Factory Function Pattern
-
-```typescript
-export function createEntityType(params: {
-  fields?: Record<string, unknown>;
-  additionalStatuses?: string[];
-});
-```
-
-- Include `...db.fields.timestamps()`
-- Use `.description()` for field docs
-- Apply permissions at model level
-
-## Stateful Model Enums
-
-Status enums are tied to the module's state machine. Base module defines core statuses; parent callers can only **extend, not replace**.
-
-```typescript
-// Good: extension only
-const BASE_STATUSES = ["PENDING", "ACTIVE", "INACTIVE"] as const;
-const statuses = [...BASE_STATUSES, ...(params.additionalStatuses ?? [])];
-
-// Bad: allows replacement
-const statuses = params.statuses ?? ["PENDING", "ACTIVE", "INACTIVE"];
-```
-
-- Name parameter `additionalX` to signal extension-only
-- Parent modules handle their additional status transitions

package/skills/4-module-tdd-implementation/references/structure.md

@@ -1,22 +0,0 @@
-# Module Directory Structure
-
-```
-src/
-├── db/           # Database models (one file per model)
-├── executor/     # Async executors (record triggers, job functions)
-├── command/      # Domain commands + tests (*.test.ts co-located)
-├── lib/          # Internal shared code (errors.ts, types.ts)
-├── testing/      # Test fixtures and helpers
-├── generated/    # Auto-generated code (do not edit)
-├── index.ts      # Public exports
-└── module.ts     # Module definition
-```
-
-## Rules
-
-- `db/`: Only documentable model definitions, no helpers
-- `executor/`: Async executors as factory functions (see executors.md)
-- `command/`: Domain commands + co-located tests, no utilities
-- `lib/`: Internal errors and types (not documented)
-- `testing/`: Fixtures for tests only
-- Run `pnpm generate` after modifying `db/` models

package/skills/4-module-tdd-implementation/references/testing.md

@@ -1,37 +0,0 @@
-# Testing Patterns
-
-## Test Coverage Goal
-
-Tests should cover all paths in the corresponding `docs/commands/*.md`:
-
-- **Process Flow**: Each branch in the mermaid flowchart = one test case
-- **Error Scenarios**: Each error code listed = one test case
-- **Idempotent paths**: If flowchart shows "Already exists? → Return existing"
-
-## Mock Database
-
-```typescript
-const { db, spies } = createMockDb<DB>();
-
-// Single return
-spies.select.mockReturnValue(entity);
-
-// Sequential returns (in query execution order)
-spies.select.mockReturnValueOnce(first).mockReturnValueOnce(second);
-```
-
-## Custom Fields Passthrough
-
-For `makeCreateX` factory commands, add one test verifying custom fields reach `.values()`:
-
-- Instantiate with concrete type: `makeCreateX<{ myField: string }>()`
-- Assert with `spies.values`: `expect(spies.values).toHaveBeenNthCalledWith(1, expect.objectContaining({ myField: "value" }))`
-- Use `toHaveBeenNthCalledWith(n, ...)` when multiple inserts occur (e.g., audit events)
-
-## Fixtures (`src/testing/fixtures.ts`)
-
-- Import `Schema` from `lib/types` (not `Namespace` from generated code)
-- Pattern: `export const baseEntity = { ... } as const satisfies Entity<Schema>`
-- Fixed IDs for traceability: `"entity-1"`
-- Consistent timestamp: `new Date("2024-01-01T00:00:00.000Z")`
-- `updatedAt: null` for base fixtures

package/skills/5-module-implementation-review/references/commands.md

@@ -1,45 +0,0 @@
-# Command Implementation
-
-## Dual Function Pattern
-
-Two functions per operation: internal `_fn` and public `fn`.
-
-**Internal function (`_myFunction`):**
-
-- Takes concrete `DB` type from `generated/kysely-tailordb`
-- Return type uses `Schema` from `lib/types`: `Promise<{ entity: Entity<Schema> }>`
-- Contains actual implementation
-
-**Public function (`myFunction`):**
-
-- Generic signature: `<T extends { Entity: object }>(db: Kysely<T>, ...)`
-- Return type uses generic `T`: `Promise<{ entity: Entity<T> }>`
-- Delegates to internal with type casting: `_fn(db as unknown as DB, ...) as unknown as Result`
-
-## Implementation Considerations
-
-- **Validation**: Check referenced entities exist before operating
-- **Idempotency**: For assign/revoke, return existing instead of throwing
-- **Return format**: Wrap in object `{ entity }` not just `entity`
-
-## Conventions
-
-- Input types: exported interfaces (`export interface MyFunctionInput`)
-- Use `.executeTakeFirst()` for single results
-- Include JSDoc: `/** Function: name \n Description */`
-
-## State Transitions
-
-For commands that transition between statuses, accept `from?: string[]` with a default:
-
-```typescript
-from?: string[];  // Default: ["ACTIVE"]
-
-const validFromStatuses = input.from ?? ["ACTIVE"];
-if (!validFromStatuses.includes(user.status)) {
-  throw new InvalidStatusTransitionError(user.status, targetStatus);
-}
-```
-
-- Default `from` contains the base valid source status
-- Parent modules can override to allow transitions from additional statuses

package/skills/5-module-implementation-review/references/errors.md

@@ -1,7 +0,0 @@
-# Error Classes
-
-Naming convention:
-
-- `name`: Class name exactly, `as const`
-- `code`: SCREAMING_SNAKE_CASE, `as const`
-- Constructor includes context (IDs, values)

package/skills/5-module-implementation-review/references/exports.md

@@ -1,8 +0,0 @@
-# Module Exports
-
-Export order:
-
-1. `defineModule` from module.ts
-2. Generated types (enum values + types separately)
-3. Error classes (for typed catch blocks)
-4. Domain functions with input types

package/skills/5-module-implementation-review/references/models.md

@@ -1,30 +0,0 @@
-# Database Models
-
-## Factory Function Pattern
-
-```typescript
-export function createEntityType(params: {
-  fields?: Record<string, unknown>;
-  additionalStatuses?: string[];
-});
-```
-
-- Include `...db.fields.timestamps()`
-- Use `.description()` for field docs
-- Apply permissions at model level
-
-## Stateful Model Enums
-
-Status enums are tied to the module's state machine. Base module defines core statuses; parent callers can only **extend, not replace**.
-
-```typescript
-// Good: extension only
-const BASE_STATUSES = ["PENDING", "ACTIVE", "INACTIVE"] as const;
-const statuses = [...BASE_STATUSES, ...(params.additionalStatuses ?? [])];
-
-// Bad: allows replacement
-const statuses = params.statuses ?? ["PENDING", "ACTIVE", "INACTIVE"];
-```
-
-- Name parameter `additionalX` to signal extension-only
-- Parent modules handle their additional status transitions

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,
-    };
-  },
-);

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

@@ -1,73 +0,0 @@
-import { defineCommand } from "../../shared/internal";
-import { DB } from "../generated/kysely-tailordb";
-import { InactiveUnitError, IncompatibleUnitsError, UnitNotFoundError } from "../lib/errors";
-import { permissions } from "../permissions";
-
-export interface ConvertQuantityInput {
-  quantity: number;
-  sourceUnitSymbol: string;
-  targetUnitSymbol: string;
-}
-
-/**
- * Function: convertQuantity
- *
- * Converts a quantity from one unit of measure to another within the same category.
- * Units are identified by their symbol (e.g., "kg", "lb", "g").
- * 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) => {
-    // 1. Validate source unit exists
-    const sourceUnit = await db
-      .selectFrom("Unit")
-      .selectAll()
-      .where("symbol", "=", input.sourceUnitSymbol)
-      .executeTakeFirst();
-
-    if (!sourceUnit) {
-      throw new UnitNotFoundError(input.sourceUnitSymbol);
-    }
-
-    // 2. Validate target unit exists
-    const targetUnit = await db
-      .selectFrom("Unit")
-      .selectAll()
-      .where("symbol", "=", input.targetUnitSymbol)
-      .executeTakeFirst();
-
-    if (!targetUnit) {
-      throw new UnitNotFoundError(input.targetUnitSymbol);
-    }
-
-    // 3. Validate both units are active
-    if (!sourceUnit.isActive) {
-      throw new InactiveUnitError(input.sourceUnitSymbol);
-    }
-
-    if (!targetUnit.isActive) {
-      throw new InactiveUnitError(input.targetUnitSymbol);
-    }
-
-    // 4. Validate units belong to the same category
-    if (sourceUnit.categoryId !== targetUnit.categoryId) {
-      throw new IncompatibleUnitsError(input.sourceUnitSymbol, input.targetUnitSymbol);
-    }
-
-    // 5. Perform conversion
-    // Formula: result = quantity * sourceConversionFactor / targetConversionFactor
-    const rawResult = (input.quantity * sourceUnit.conversionFactor) / targetUnit.conversionFactor;
-
-    // 6. Apply rounding to target unit's precision
-    const roundingFactor = Math.pow(10, targetUnit.roundingPrecision);
-    const convertedQuantity = Math.round(rawResult * roundingFactor) / roundingFactor;
-
-    return {
-      convertedQuantity,
-      sourceUnit,
-      targetUnit,
-    };
-  },
-);

package/src/modules/primitives/lib/errors.ts

@@ -1,138 +0,0 @@
-import { createDomainError } from "../../shared/internal";
-
-export const UoMCategoryNotFoundError = createDomainError(
-  "UoMCategoryNotFoundError",
-  "UOM_CATEGORY_NOT_FOUND",
-  (identifier: string) => `UoM category not found: ${identifier}`,
-);
-
-export const UnitNotFoundError = createDomainError(
-  "UnitNotFoundError",
-  "UNIT_NOT_FOUND",
-  (symbol: string) => `Unit not found: ${symbol}`,
-);
-
-export const IncompatibleUnitsError = createDomainError(
-  "IncompatibleUnitsError",
-  "INCOMPATIBLE_UNITS",
-  (sourceSymbol: string, targetSymbol: string) =>
-    `Cannot convert between incompatible units: ${sourceSymbol} and ${targetSymbol} belong to different categories`,
-);
-
-export const InactiveUnitError = createDomainError(
-  "InactiveUnitError",
-  "INACTIVE_UNIT",
-  (symbol: string) => `Unit is inactive: ${symbol}`,
-);
-
-export const CurrencyNotFoundError = createDomainError(
-  "CurrencyNotFoundError",
-  "CURRENCY_NOT_FOUND",
-  (code: string) => `Currency not found: ${code}`,
-);
-
-export const InactiveCurrencyError = createDomainError(
-  "InactiveCurrencyError",
-  "INACTIVE_CURRENCY",
-  (code: string) => `Currency is inactive: ${code}`,
-);
-
-export const ExchangeRateNotFoundError = createDomainError(
-  "ExchangeRateNotFoundError",
-  "EXCHANGE_RATE_NOT_FOUND",
-  (sourceCode: string, targetCode: string, date: string) =>
-    `No exchange rate found for ${sourceCode} to ${targetCode} on or before ${date}`,
-);
-
-export const CannotDeactivateReferenceUnitError = createDomainError(
-  "CannotDeactivateReferenceUnitError",
-  "CANNOT_DEACTIVATE_REFERENCE_UNIT",
-  (unitId: string) => `Cannot deactivate reference unit: ${unitId}. Change reference unit first.`,
-);
-
-export const CategoryNotActiveError = createDomainError(
-  "CategoryNotActiveError",
-  "CATEGORY_NOT_ACTIVE",
-  (categoryId: string) => `Category is not active: ${categoryId}`,
-);
-
-export const DuplicateUnitSymbolError = createDomainError(
-  "DuplicateUnitSymbolError",
-  "DUPLICATE_UNIT_SYMBOL",
-  (symbol: string, categoryId: string) =>
-    `Unit with symbol "${symbol}" already exists in category ${categoryId}`,
-);
-
-export const InvalidConversionFactorError = createDomainError(
-  "InvalidConversionFactorError",
-  "INVALID_CONVERSION_FACTOR",
-  (factor: number) => `Conversion factor must be positive: ${factor}`,
-);
-
-export const InvalidRoundingPrecisionError = createDomainError(
-  "InvalidRoundingPrecisionError",
-  "INVALID_ROUNDING_PRECISION",
-  (precision: number) => `Rounding precision must be non-negative: ${precision}`,
-);
-
-export const DuplicateCategoryNameError = createDomainError(
-  "DuplicateCategoryNameError",
-  "DUPLICATE_CATEGORY_NAME",
-  (name: string) => `Category with name "${name}" already exists`,
-);
-
-export const CategoryHasActiveUnitsError = createDomainError(
-  "CategoryHasActiveUnitsError",
-  "CATEGORY_HAS_ACTIVE_UNITS",
-  (categoryId: string) => `Cannot deactivate category ${categoryId}: has active units`,
-);
-
-export const UnitNotInCategoryError = createDomainError(
-  "UnitNotInCategoryError",
-  "UNIT_NOT_IN_CATEGORY",
-  (unitId: string, categoryId: string) =>
-    `Unit ${unitId} does not belong to category ${categoryId}`,
-);
-
-export const InvalidISOCodeError = createDomainError(
-  "InvalidISOCodeError",
-  "INVALID_ISO_CODE",
-  (code: string) => `Invalid ISO 4217 code: "${code}". Must be exactly 3 uppercase letters.`,
-);
-
-export const DuplicateCurrencyCodeError = createDomainError(
-  "DuplicateCurrencyCodeError",
-  "DUPLICATE_CURRENCY_CODE",
-  (code: string) => `Currency with code "${code}" already exists`,
-);
-
-export const InvalidDecimalPlacesError = createDomainError(
-  "InvalidDecimalPlacesError",
-  "INVALID_DECIMAL_PLACES",
-  (decimalPlaces: number) => `Decimal places must be between 0 and 4: ${decimalPlaces}`,
-);
-
-export const CannotDeactivateBaseCurrencyError = createDomainError(
-  "CannotDeactivateBaseCurrencyError",
-  "CANNOT_DEACTIVATE_BASE_CURRENCY",
-  (currencyId: string) =>
-    `Cannot deactivate base currency: ${currencyId}. Change base currency first.`,
-);
-
-export const CannotSetInactiveAsBaseCurrencyError = createDomainError(
-  "CannotSetInactiveAsBaseCurrencyError",
-  "CANNOT_SET_INACTIVE_AS_BASE_CURRENCY",
-  (currencyId: string) => `Cannot set inactive currency as base: ${currencyId}. Activate it first.`,
-);
-
-export const SameCurrencyPairError = createDomainError(
-  "SameCurrencyPairError",
-  "SAME_CURRENCY_PAIR",
-  (currencyId: string) => `Source and target currency cannot be the same: ${currencyId}`,
-);
-
-export const InvalidExchangeRateError = createDomainError(
-  "InvalidExchangeRateError",
-  "INVALID_EXCHANGE_RATE",
-  (rate: number) => `Exchange rate must be positive: ${rate}`,
-);

package/src/modules/user-management/lib/errors.ts

@@ -1,81 +0,0 @@
-import { createDomainError } from "../../shared/internal";
-
-export const UserNotFoundError = createDomainError(
-  "UserNotFoundError",
-  "USER_NOT_FOUND",
-  (userId: string) => `User not found: ${userId}`,
-);
-
-export const UserAlreadyExistsError = createDomainError(
-  "UserAlreadyExistsError",
-  "USER_ALREADY_EXISTS",
-  (email: string) => `User with email "${email}" already exists`,
-);
-
-export const UserNotActiveError = createDomainError(
-  "UserNotActiveError",
-  "USER_NOT_ACTIVE",
-  (userId: string, status: string) => `User ${userId} is not active (current status: ${status})`,
-);
-
-export const InvalidEmailError = createDomainError(
-  "InvalidEmailError",
-  "INVALID_EMAIL",
-  (email: string) => `Invalid email format: ${email}`,
-);
-
-export const MissingRequiredFieldError = createDomainError(
-  "MissingRequiredFieldError",
-  "MISSING_REQUIRED_FIELD",
-  (field: string) => `Missing required field: ${field}`,
-);
-
-export const InvalidStatusTransitionError = createDomainError(
-  "InvalidStatusTransitionError",
-  "INVALID_STATUS_TRANSITION",
-  (currentStatus: string, targetStatus: string) =>
-    `Invalid status transition from ${currentStatus} to ${targetStatus}`,
-);
-
-export const PermissionNotFoundError = createDomainError(
-  "PermissionNotFoundError",
-  "PERMISSION_NOT_FOUND",
-  (permissionId: string) => `Permission not found: ${permissionId}`,
-);
-
-export const DuplicatePermissionKeyError = createDomainError(
-  "DuplicatePermissionKeyError",
-  "DUPLICATE_PERMISSION_KEY",
-  (key: string) => `Permission with key "${key}" already exists`,
-);
-
-export const InvalidPermissionKeyFormatError = createDomainError(
-  "InvalidPermissionKeyFormatError",
-  "INVALID_PERMISSION_KEY_FORMAT",
-  (key: string) => `Invalid permission key format: "${key}". Expected format: resource:action`,
-);
-
-export const RoleNotFoundError = createDomainError(
-  "RoleNotFoundError",
-  "ROLE_NOT_FOUND",
-  (roleId: string) => `Role not found: ${roleId}`,
-);
-
-export const DuplicateRoleNameError = createDomainError(
-  "DuplicateRoleNameError",
-  "DUPLICATE_ROLE_NAME",
-  (name: string) => `Role with name "${name}" already exists`,
-);
-
-export const AssignmentNotFoundError = createDomainError(
-  "AssignmentNotFoundError",
-  "ASSIGNMENT_NOT_FOUND",
-  (sourceType: string, sourceId: string, targetType: string, targetId: string) =>
-    `Assignment not found: ${sourceType} ${sourceId} -> ${targetType} ${targetId}`,
-);
-
-export const InvalidEventTypeError = createDomainError(
-  "InvalidEventTypeError",
-  "INVALID_EVENT_TYPE",
-  (eventType: string) => `Invalid event type: ${eventType}`,
-);