@tailor-platform/erp-kit 0.0.1 → 0.1.1

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

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

@@ -0,0 +1,126 @@
+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.test.ts

@@ -0,0 +1,219 @@
+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 { InactiveUnitError, IncompatibleUnitsError, UnitNotFoundError } from "../lib/errors";
+import {
+  baseUnitGram,
+  baseUnitKg,
+  baseUnitLiter,
+  baseUnitPound,
+  inactiveUnit,
+} from "../testing/fixtures";
+import { convertQuantity } from "./convertQuantity";
+
+describe("convertQuantity", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["primitives:convertQuantity"],
+  };
+
+  // Error cases first
+  it("throws when source unit doesn't exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(undefined);
+
+    await expect(
+      convertQuantity(
+        db,
+        {
+          quantity: 10,
+          sourceUnitSymbol: "xyz",
+          targetUnitSymbol: baseUnitGram.symbol,
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(UnitNotFoundError);
+  });
+
+  it("throws when target unit doesn't exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseUnitKg) // source unit exists
+      .mockReturnValueOnce(undefined); // target unit doesn't exist
+
+    await expect(
+      convertQuantity(
+        db,
+        {
+          quantity: 10,
+          sourceUnitSymbol: baseUnitKg.symbol,
+          targetUnitSymbol: "xyz",
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(UnitNotFoundError);
+  });
+
+  it("throws when source unit is inactive", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(inactiveUnit) // source unit inactive
+      .mockReturnValueOnce(baseUnitGram); // target unit exists
+
+    await expect(
+      convertQuantity(
+        db,
+        {
+          quantity: 10,
+          sourceUnitSymbol: inactiveUnit.symbol,
+          targetUnitSymbol: baseUnitGram.symbol,
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(InactiveUnitError);
+  });
+
+  it("throws when target unit is inactive", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseUnitKg) // source unit exists
+      .mockReturnValueOnce(inactiveUnit); // target unit inactive
+
+    await expect(
+      convertQuantity(
+        db,
+        {
+          quantity: 10,
+          sourceUnitSymbol: baseUnitKg.symbol,
+          targetUnitSymbol: inactiveUnit.symbol,
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(InactiveUnitError);
+  });
+
+  it("throws when units belong to different categories", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseUnitKg) // Weight category
+      .mockReturnValueOnce(baseUnitLiter); // Volume category
+
+    await expect(
+      convertQuantity(
+        db,
+        {
+          quantity: 10,
+          sourceUnitSymbol: baseUnitKg.symbol,
+          targetUnitSymbol: baseUnitLiter.symbol,
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(IncompatibleUnitsError);
+  });
+
+  // Success cases
+  it("returns same quantity when source and target are the same unit", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseUnitKg).mockReturnValueOnce(baseUnitKg);
+
+    const result = await convertQuantity(
+      db,
+      {
+        quantity: 10,
+        sourceUnitSymbol: baseUnitKg.symbol,
+        targetUnitSymbol: baseUnitKg.symbol,
+      },
+      ctx,
+    );
+
+    expect(result.convertedQuantity).toBe(10);
+    expect(result.sourceUnit).toEqual(baseUnitKg);
+    expect(result.targetUnit).toEqual(baseUnitKg);
+  });
+
+  it("converts kg to grams correctly", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseUnitKg) // 1 kg = 1.0 (reference)
+      .mockReturnValueOnce(baseUnitGram); // 1 g = 0.001 kg
+
+    // 5 kg * 1.0 / 0.001 = 5000 g
+    const result = await convertQuantity(
+      db,
+      {
+        quantity: 5,
+        sourceUnitSymbol: baseUnitKg.symbol,
+        targetUnitSymbol: baseUnitGram.symbol,
+      },
+      ctx,
+    );
+
+    expect(result.convertedQuantity).toBe(5000); // rounded to 0 decimal places (gram precision)
+  });
+
+  it("converts grams to kg correctly", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseUnitGram) // 1 g = 0.001 kg
+      .mockReturnValueOnce(baseUnitKg); // 1 kg = 1.0 (reference)
+
+    // 2500 g * 0.001 / 1.0 = 2.5 kg
+    const result = await convertQuantity(
+      db,
+      {
+        quantity: 2500,
+        sourceUnitSymbol: baseUnitGram.symbol,
+        targetUnitSymbol: baseUnitKg.symbol,
+      },
+      ctx,
+    );
+
+    expect(result.convertedQuantity).toBe(2.5); // rounded to 2 decimal places (kg precision)
+  });
+
+  it("converts pounds to kg correctly", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseUnitPound) // 1 lb = 0.453592 kg
+      .mockReturnValueOnce(baseUnitKg); // 1 kg = 1.0 (reference)
+
+    // 10 lb * 0.453592 / 1.0 = 4.53592 kg, rounded to 4.54
+    const result = await convertQuantity(
+      db,
+      {
+        quantity: 10,
+        sourceUnitSymbol: baseUnitPound.symbol,
+        targetUnitSymbol: baseUnitKg.symbol,
+      },
+      ctx,
+    );
+
+    expect(result.convertedQuantity).toBe(4.54);
+  });
+
+  it("handles zero quantity correctly", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseUnitKg).mockReturnValueOnce(baseUnitGram);
+
+    const result = await convertQuantity(
+      db,
+      {
+        quantity: 0,
+        sourceUnitSymbol: baseUnitKg.symbol,
+        targetUnitSymbol: baseUnitGram.symbol,
+      },
+      ctx,
+    );
+
+    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/convertQuantity.ts

@@ -0,0 +1,73 @@
+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,
+    };
+  },
+);