@tailor-platform/erp-kit 0.0.1 → 0.1.0

package/src/modules/primitives/README.md

@@ -0,0 +1,39 @@
+# README
+
+## Overview
+
+The Primitives module provides foundational reference data that other ERP modules depend on. It includes unit of measure (UoM) definitions for quantity handling and currency definitions for multi-currency financial operations. These are stable, rarely-changing entities that form the measurement and monetary foundation of the system.
+
+This module combines related configuration primitives to simplify dependency management while keeping tax-related functionality separate due to its regulatory complexity.
+
+## Key Features
+
+- **UoM Categories**: Group related units (e.g., Unit, Weight, Volume, Length, Time) with a designated reference unit for each category
+- **Unit Definitions**: Define individual units with symbols, names, and conversion factors relative to the reference unit
+- **Quantity Conversion**: Convert quantities between any two units within the same category using automatic factor calculation
+- **Rounding Precision**: Configure decimal precision per unit to ensure appropriate rounding for business operations
+- **Currency Definitions**: Define currencies with ISO 4217 codes, symbols, and decimal precision
+- **Base Currency**: Designate a company base currency for reporting and consolidation
+- **Exchange Rates**: Maintain date-based exchange rates between currency pairs
+- **Amount Conversion**: Convert monetary amounts between currencies using applicable rates
+
+## Module Scope
+
+### In Scope
+
+- UoM category and unit management with conversion factors
+- Currency definitions with ISO 4217 codes and symbols
+- Exchange rate storage with effective dates
+- Quantity conversion between compatible units
+- Amount conversion between currencies
+
+### Out of Scope
+
+- Tax configuration and fiscal positions (separate tax-configuration module)
+- Product definitions (product-management module)
+- Transaction recording (sales, purchase, accounting modules)
+- Automatic exchange rate fetching from external APIs
+
+## Module Dependencies
+
+- None (this is a foundational module)

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

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import {
+  createMockDb,
+  testNotFound,
+  testPermissionDenied,
+  testIdempotent,
+} from "../../testing/index";
+import { type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { UoMCategoryNotFoundError } from "../lib/errors";
+import { baseUoMCategory } from "../testing/fixtures";
+import { activateCategory } from "./activateCategory";
+
+describe("activateCategory", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["primitives:activateCategory"],
+  };
+
+  const inactiveCategory = {
+    ...baseUoMCategory,
+    isActive: false,
+  };
+
+  it(
+    "throws when category doesn't exist",
+    testNotFound(
+      activateCategory,
+      { categoryId: "nonexistent-category" },
+      ctx,
+      UoMCategoryNotFoundError,
+    ),
+  );
+
+  it(
+    "returns category unchanged when already active",
+    testIdempotent(
+      activateCategory,
+      { categoryId: baseUoMCategory.id },
+      ctx,
+      baseUoMCategory,
+      "category",
+    ),
+  );
+
+  // Success cases
+  it("activates inactive category", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const activatedCategory = {
+      ...inactiveCategory,
+      isActive: true,
+      updatedAt: new Date("2024-01-15T00:00:00.000Z"),
+    };
+
+    spies.select.mockReturnValue(inactiveCategory);
+    spies.update.mockReturnValue(activatedCategory);
+
+    const result = await activateCategory(
+      db,
+      {
+        categoryId: inactiveCategory.id,
+      },
+      ctx,
+    );
+
+    expect(result.category.isActive).toBe(true);
+    expect(result.category.updatedAt).not.toBeNull();
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it(
+    "throws when permission is missing",
+    testPermissionDenied(activateCategory, { categoryId: "cat-1" }),
+  );
+});

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

@@ -0,0 +1,50 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { UoMCategoryNotFoundError } from "../lib/errors";
+import { permissions } from "../permissions";
+
+export interface ActivateCategoryInput {
+  categoryId: string;
+}
+
+/**
+ * Function: activateCategory
+ *
+ * Re-enables a previously deactivated UoM category, making it and its units
+ * available for new product assignments and transactions.
+ */
+export const activateCategory = defineCommand(
+  permissions.activateCategory,
+  async (db: DB, input: ActivateCategoryInput) => {
+    // 1. Find category by ID
+    const category = await db
+      .selectFrom("UoMCategory")
+      .selectAll()
+      .where("id", "=", input.categoryId)
+      .executeTakeFirst();
+
+    // 2. If not found, throw error
+    if (!category) {
+      throw new UoMCategoryNotFoundError(input.categoryId);
+    }
+
+    // 3. If already active, return category (idempotent)
+    if (category.isActive) {
+      return { category };
+    }
+
+    // 4. Update isActive = true
+    const updatedCategory = await db
+      .updateTable("UoMCategory")
+      .set({
+        isActive: true,
+        updatedAt: new Date(),
+      })
+      .where("id", "=", input.categoryId)
+      .returningAll()
+      .executeTakeFirst();
+
+    // 5. Return updated category
+    return { category: updatedCategory! };
+  },
+);

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

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import {
+  createMockDb,
+  testNotFound,
+  testPermissionDenied,
+  testIdempotent,
+} from "../../testing/index";
+import { type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { CurrencyNotFoundError } from "../lib/errors";
+import { baseCurrencyUSD, inactiveCurrency } from "../testing/fixtures";
+import { activateCurrency } from "./activateCurrency";
+
+describe("activateCurrency", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["primitives:activateCurrency"],
+  };
+
+  it(
+    "throws when currency doesn't exist",
+    testNotFound(
+      activateCurrency,
+      { currencyId: "nonexistent-currency" },
+      ctx,
+      CurrencyNotFoundError,
+    ),
+  );
+
+  it(
+    "returns currency unchanged when already active",
+    testIdempotent(
+      activateCurrency,
+      { currencyId: baseCurrencyUSD.id },
+      ctx,
+      baseCurrencyUSD,
+      "currency",
+    ),
+  );
+
+  // Success cases
+  it("activates inactive currency", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const activatedCurrency = {
+      ...inactiveCurrency,
+      isActive: true,
+      updatedAt: new Date("2024-01-15T00:00:00.000Z"),
+    };
+
+    spies.select.mockReturnValue(inactiveCurrency);
+    spies.update.mockReturnValue(activatedCurrency);
+
+    const result = await activateCurrency(
+      db,
+      {
+        currencyId: inactiveCurrency.id,
+      },
+      ctx,
+    );
+
+    expect(result.currency.isActive).toBe(true);
+    expect(result.currency.updatedAt).not.toBeNull();
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it(
+    "throws when permission is missing",
+    testPermissionDenied(activateCurrency, { currencyId: "cur-1" }),
+  );
+});

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

@@ -0,0 +1,50 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { CurrencyNotFoundError } from "../lib/errors";
+import { permissions } from "../permissions";
+
+export interface ActivateCurrencyInput {
+  currencyId: string;
+}
+
+/**
+ * Function: activateCurrency
+ *
+ * Re-enables a previously deactivated currency, making it available
+ * for new transactions.
+ */
+export const activateCurrency = defineCommand(
+  permissions.activateCurrency,
+  async (db: DB, input: ActivateCurrencyInput) => {
+    // 1. Find currency by ID
+    const currency = await db
+      .selectFrom("Currency")
+      .selectAll()
+      .where("id", "=", input.currencyId)
+      .executeTakeFirst();
+
+    // 2. If not found, throw error
+    if (!currency) {
+      throw new CurrencyNotFoundError(input.currencyId);
+    }
+
+    // 3. If already active, return currency (idempotent)
+    if (currency.isActive) {
+      return { currency };
+    }
+
+    // 4. Update isActive = true
+    const updatedCurrency = await db
+      .updateTable("Currency")
+      .set({
+        isActive: true,
+        updatedAt: new Date(),
+      })
+      .where("id", "=", input.currencyId)
+      .returningAll()
+      .executeTakeFirst();
+
+    // 5. Return updated currency
+    return { currency: updatedCurrency! };
+  },
+);

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

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import {
+  createMockDb,
+  testNotFound,
+  testPermissionDenied,
+  testIdempotent,
+} from "../../testing/index";
+import { type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { UnitNotFoundError } from "../lib/errors";
+import { baseUnitKg, inactiveUnit } from "../testing/fixtures";
+import { activateUnit } from "./activateUnit";
+
+describe("activateUnit", () => {
+  const ctx: CommandContext = { actorId: "test-actor", permissions: ["primitives:activateUnit"] };
+
+  it(
+    "throws when unit doesn't exist",
+    testNotFound(activateUnit, { unitId: "nonexistent-unit" }, ctx, UnitNotFoundError),
+  );
+
+  it(
+    "returns unit unchanged when already active",
+    testIdempotent(activateUnit, { unitId: baseUnitKg.id }, ctx, baseUnitKg, "unit"),
+  );
+
+  // Success cases
+  it("activates inactive unit", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const activatedUnit = {
+      ...inactiveUnit,
+      isActive: true,
+      updatedAt: new Date("2024-01-15T00:00:00.000Z"),
+    };
+
+    spies.select.mockReturnValue(inactiveUnit);
+    spies.update.mockReturnValue(activatedUnit);
+
+    const result = await activateUnit(
+      db,
+      {
+        unitId: inactiveUnit.id,
+      },
+      ctx,
+    );
+
+    expect(result.unit.isActive).toBe(true);
+    expect(result.unit.updatedAt).not.toBeNull();
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("throws when permission is missing", testPermissionDenied(activateUnit, { unitId: "unit-1" }));
+});

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

@@ -0,0 +1,50 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { UnitNotFoundError } from "../lib/errors";
+import { permissions } from "../permissions";
+
+export interface ActivateUnitInput {
+  unitId: string;
+}
+
+/**
+ * Function: activateUnit
+ *
+ * Re-enables a previously deactivated unit of measure, making it available
+ * for new product assignments and quantity conversions.
+ */
+export const activateUnit = defineCommand(
+  permissions.activateUnit,
+  async (db: DB, input: ActivateUnitInput) => {
+    // 1. Find unit by ID
+    const unit = await db
+      .selectFrom("Unit")
+      .selectAll()
+      .where("id", "=", input.unitId)
+      .executeTakeFirst();
+
+    // 2. If not found, throw error
+    if (!unit) {
+      throw new UnitNotFoundError(input.unitId);
+    }
+
+    // 3. If already active, return unit (idempotent)
+    if (unit.isActive) {
+      return { unit };
+    }
+
+    // 4. Update isActive = true
+    const updatedUnit = await db
+      .updateTable("Unit")
+      .set({
+        isActive: true,
+        updatedAt: new Date(),
+      })
+      .where("id", "=", input.unitId)
+      .returningAll()
+      .executeTakeFirst();
+
+    // 5. Return updated unit
+    return { unit: updatedUnit! };
+  },
+);

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

@@ -0,0 +1,275 @@
+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 {
+  CurrencyNotFoundError,
+  ExchangeRateNotFoundError,
+  InactiveCurrencyError,
+} from "../lib/errors";
+import {
+  baseCurrencyEUR,
+  baseCurrencyJPY,
+  baseCurrencyUSD,
+  baseExchangeRateUSDtoEUR,
+  baseExchangeRateUSDtoJPY,
+  inactiveCurrency,
+  olderExchangeRateUSDtoEUR,
+} from "../testing/fixtures";
+import { convertAmount } from "./convertAmount";
+
+describe("convertAmount", () => {
+  const ctx: CommandContext = { actorId: "test-actor", permissions: ["primitives:convertAmount"] };
+
+  // Error cases first
+  it("throws when source currency doesn't exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(undefined);
+
+    await expect(
+      convertAmount(
+        db,
+        {
+          amount: 100,
+          sourceCurrencyCode: "XYZ",
+          targetCurrencyCode: baseCurrencyEUR.code,
+          conversionDate: "2024-01-20",
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(CurrencyNotFoundError);
+  });
+
+  it("throws when target currency doesn't exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseCurrencyUSD) // source exists
+      .mockReturnValueOnce(undefined); // target doesn't exist
+
+    await expect(
+      convertAmount(
+        db,
+        {
+          amount: 100,
+          sourceCurrencyCode: baseCurrencyUSD.code,
+          targetCurrencyCode: "XYZ",
+          conversionDate: "2024-01-20",
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(CurrencyNotFoundError);
+  });
+
+  it("throws when source currency is inactive", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(inactiveCurrency) // source inactive
+      .mockReturnValueOnce(baseCurrencyEUR); // target exists
+
+    await expect(
+      convertAmount(
+        db,
+        {
+          amount: 100,
+          sourceCurrencyCode: inactiveCurrency.code,
+          targetCurrencyCode: baseCurrencyEUR.code,
+          conversionDate: "2024-01-20",
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(InactiveCurrencyError);
+  });
+
+  it("throws when target currency is inactive", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseCurrencyUSD) // source exists
+      .mockReturnValueOnce(inactiveCurrency); // target inactive
+
+    await expect(
+      convertAmount(
+        db,
+        {
+          amount: 100,
+          sourceCurrencyCode: baseCurrencyUSD.code,
+          targetCurrencyCode: inactiveCurrency.code,
+          conversionDate: "2024-01-20",
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(InactiveCurrencyError);
+  });
+
+  it("throws when no exchange rate exists for the currency pair", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseCurrencyUSD) // source exists
+      .mockReturnValueOnce(baseCurrencyEUR) // target exists
+      .mockReturnValueOnce(undefined) // no direct rate
+      .mockReturnValueOnce(undefined); // no inverse rate
+
+    await expect(
+      convertAmount(
+        db,
+        {
+          amount: 100,
+          sourceCurrencyCode: baseCurrencyUSD.code,
+          targetCurrencyCode: baseCurrencyEUR.code,
+          conversionDate: "2024-01-20",
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(ExchangeRateNotFoundError);
+  });
+
+  // Success cases
+  it("returns same amount when source and target are the same currency", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseCurrencyUSD).mockReturnValueOnce(baseCurrencyUSD);
+
+    const result = await convertAmount(
+      db,
+      {
+        amount: 100,
+        sourceCurrencyCode: baseCurrencyUSD.code,
+        targetCurrencyCode: baseCurrencyUSD.code,
+        conversionDate: "2024-01-20",
+      },
+      ctx,
+    );
+
+    expect(result.convertedAmount).toBe(100);
+    expect(result.exchangeRate).toBe(1);
+  });
+
+  it("converts USD to EUR using direct rate", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseCurrencyUSD) // source
+      .mockReturnValueOnce(baseCurrencyEUR) // target
+      .mockReturnValueOnce(baseExchangeRateUSDtoEUR); // rate = 0.92
+
+    // 100 USD * 0.92 = 92 EUR
+    const result = await convertAmount(
+      db,
+      {
+        amount: 100,
+        sourceCurrencyCode: baseCurrencyUSD.code,
+        targetCurrencyCode: baseCurrencyEUR.code,
+        conversionDate: "2024-01-20",
+      },
+      ctx,
+    );
+
+    expect(result.convertedAmount).toBe(92);
+    expect(result.exchangeRate).toBe(0.92);
+  });
+
+  it("uses inverse rate when no direct rate exists", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseCurrencyEUR) // source
+      .mockReturnValueOnce(baseCurrencyUSD) // target
+      .mockReturnValueOnce(undefined) // no direct EUR->USD rate
+      .mockReturnValueOnce(baseExchangeRateUSDtoEUR); // inverse USD->EUR rate = 0.92
+
+    // 100 EUR * (1/0.92) = 108.70 USD (rounded to 2 decimal places)
+    const result = await convertAmount(
+      db,
+      {
+        amount: 100,
+        sourceCurrencyCode: baseCurrencyEUR.code,
+        targetCurrencyCode: baseCurrencyUSD.code,
+        conversionDate: "2024-01-20",
+      },
+      ctx,
+    );
+
+    expect(result.convertedAmount).toBe(108.7);
+    expect(result.exchangeRate).toBeCloseTo(1 / 0.92, 5);
+  });
+
+  it("uses most recent rate on or before the conversion date", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseCurrencyUSD) // source
+      .mockReturnValueOnce(baseCurrencyEUR) // target
+      .mockReturnValueOnce(olderExchangeRateUSDtoEUR); // rate = 0.85 from 2024-01-01
+
+    // Querying for 2024-01-10, should use rate from 2024-01-01
+    // 100 USD * 0.85 = 85 EUR
+    const result = await convertAmount(
+      db,
+      {
+        amount: 100,
+        sourceCurrencyCode: baseCurrencyUSD.code,
+        targetCurrencyCode: baseCurrencyEUR.code,
+        conversionDate: "2024-01-10",
+      },
+      ctx,
+    );
+
+    expect(result.convertedAmount).toBe(85);
+    expect(result.exchangeRate).toBe(0.85);
+  });
+
+  it("rounds to target currency decimal places (JPY has 0)", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseCurrencyUSD) // source
+      .mockReturnValueOnce(baseCurrencyJPY) // target (0 decimal places)
+      .mockReturnValueOnce(baseExchangeRateUSDtoJPY); // rate = 148.5
+
+    // 100.50 USD * 148.5 = 14924.25 -> rounded to 14924 JPY
+    const result = await convertAmount(
+      db,
+      {
+        amount: 100.5,
+        sourceCurrencyCode: baseCurrencyUSD.code,
+        targetCurrencyCode: baseCurrencyJPY.code,
+        conversionDate: "2024-01-20",
+      },
+      ctx,
+    );
+
+    expect(result.convertedAmount).toBe(14924);
+  });
+
+  it("handles zero amount correctly", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseCurrencyUSD)
+      .mockReturnValueOnce(baseCurrencyEUR)
+      .mockReturnValueOnce(baseExchangeRateUSDtoEUR);
+
+    const result = await convertAmount(
+      db,
+      {
+        amount: 0,
+        sourceCurrencyCode: baseCurrencyUSD.code,
+        targetCurrencyCode: baseCurrencyEUR.code,
+        conversionDate: "2024-01-20",
+      },
+      ctx,
+    );
+
+    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);
+  });
+});