@tailor-platform/erp-kit 0.0.1 → 0.1.0

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

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

@@ -0,0 +1,126 @@
+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 { DuplicateCategoryNameError } from "../lib/errors";
+import { baseUoMCategory, baseUnitKg } from "../testing/fixtures";
+import { makeCreateCategory } from "./createCategory";
+
+const createCategory = makeCreateCategory();
+
+describe("createCategory", () => {
+  const ctx: CommandContext = { actorId: "test-actor", permissions: ["primitives:createCategory"] };
+
+  // Error cases
+  it("throws when category name already exists", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(baseUoMCategory);
+
+    await expect(
+      createCategory(
+        db,
+        {
+          name: baseUoMCategory.name,
+          referenceUnit: {
+            name: "Kilogram",
+            symbol: "kg",
+            roundingPrecision: 2,
+          },
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(DuplicateCategoryNameError);
+  });
+
+  // Success cases
+  it("creates category with reference unit", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const createdCategory = {
+      ...baseUoMCategory,
+      id: "new-category-id",
+      referenceUnitId: "new-unit-id",
+    };
+    const createdUnit = {
+      ...baseUnitKg,
+      id: "new-unit-id",
+      categoryId: "new-category-id",
+    };
+
+    spies.select.mockReturnValue(undefined); // No existing category
+    spies.insert.mockReturnValueOnce(createdCategory).mockReturnValueOnce(createdUnit);
+    spies.update.mockReturnValue({ ...createdCategory, referenceUnitId: "new-unit-id" });
+
+    const result = await createCategory(
+      db,
+      {
+        name: "Weight",
+        description: "Weight units",
+        referenceUnit: {
+          name: "Kilogram",
+          symbol: "kg",
+          roundingPrecision: 2,
+        },
+      },
+      ctx,
+    );
+
+    expect(result.category.name).toBe("Weight");
+    expect(result.category.isActive).toBe(true);
+    expect(result.referenceUnit.conversionFactor).toBe(1.0);
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("throws when permission is missing", async () => {
+    const { db } = createMockDb<DB>();
+    const denied: CommandContext = { actorId: "test-actor", permissions: [] };
+    await expect(
+      createCategory(
+        db,
+        { name: "Test", referenceUnit: { name: "Unit", symbol: "u", roundingPrecision: 2 } },
+        denied,
+      ),
+    ).rejects.toBeInstanceOf(InsufficientPermissionError);
+  });
+
+  it("passes custom fields through to insert", async () => {
+    const createCategoryWithFields = makeCreateCategory<
+      { priority: number },
+      { tolerance: number }
+    >();
+    const { db, spies } = createMockDb<DB>();
+    const createdCategory = {
+      ...baseUoMCategory,
+      id: "new-category-id",
+      referenceUnitId: "new-unit-id",
+    };
+    const createdUnit = {
+      ...baseUnitKg,
+      id: "new-unit-id",
+      categoryId: "new-category-id",
+    };
+
+    spies.select.mockReturnValue(undefined);
+    spies.insert.mockReturnValueOnce(createdCategory).mockReturnValueOnce(createdUnit);
+    spies.update.mockReturnValue({ ...createdCategory, referenceUnitId: "new-unit-id" });
+
+    await createCategoryWithFields(
+      db,
+      {
+        name: "Weight",
+        priority: 1,
+        referenceUnit: {
+          name: "Kilogram",
+          symbol: "kg",
+          roundingPrecision: 2,
+          tolerance: 0.01,
+        },
+      },
+      ctx,
+    );
+
+    // Category insert includes category custom field
+    expect(spies.values).toHaveBeenNthCalledWith(1, expect.objectContaining({ priority: 1 }));
+    // Unit insert includes unit custom field
+    expect(spies.values).toHaveBeenNthCalledWith(2, expect.objectContaining({ tolerance: 0.01 }));
+  });
+});

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

@@ -0,0 +1,89 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { DuplicateCategoryNameError } from "../lib/errors";
+import { permissions } from "../permissions";
+
+interface CreateCategoryInput<UnitCF extends Record<string, unknown>> {
+  name: string;
+  description?: string;
+  referenceUnit: {
+    name: string;
+    symbol: string;
+    roundingPrecision: number;
+  } & UnitCF;
+}
+
+/**
+ * Function: createCategory
+ *
+ * Establishes a new unit of measure category that groups related units.
+ * Creates the category with a reference unit that has conversion factor 1.0.
+ */
+export function makeCreateCategory<
+  CatCF extends Record<string, unknown>,
+  UnitCF extends Record<string, unknown>,
+>() {
+  return defineCommand(
+    permissions.createCategory,
+    async (db: DB, input: CreateCategoryInput<UnitCF> & CatCF) => {
+      const { name, description, referenceUnit, ...categoryCustomFields } = input;
+      const { name: unitName, symbol, roundingPrecision, ...unitCustomFields } = referenceUnit;
+
+      // 1. Check if category name already exists
+      const existingCategory = await db
+        .selectFrom("UoMCategory")
+        .selectAll()
+        .where("name", "=", name)
+        .executeTakeFirst();
+
+      if (existingCategory) {
+        throw new DuplicateCategoryNameError(name);
+      }
+
+      // 2. Create category without reference unit first
+      const category = await db
+        .insertInto("UoMCategory")
+        .values({
+          ...(categoryCustomFields as Record<string, unknown>),
+          name,
+          description: description ?? null,
+          referenceUnitId: null,
+          isActive: true,
+          createdAt: new Date(),
+          updatedAt: null,
+        })
+        .returningAll()
+        .executeTakeFirst();
+
+      // 3. Create reference unit with conversion factor 1.0
+      const createdReferenceUnit = await db
+        .insertInto("Unit")
+        .values({
+          ...(unitCustomFields as Record<string, unknown>),
+          name: unitName,
+          symbol,
+          categoryId: category!.id,
+          conversionFactor: 1.0,
+          roundingPrecision,
+          isActive: true,
+          createdAt: new Date(),
+          updatedAt: null,
+        })
+        .returningAll()
+        .executeTakeFirst();
+
+      // 4. Update category with reference unit ID
+      const updatedCategory = await db
+        .updateTable("UoMCategory")
+        .set({
+          referenceUnitId: createdReferenceUnit!.id,
+          updatedAt: new Date(),
+        })
+        .where("id", "=", category!.id)
+        .returningAll()
+        .executeTakeFirst();
+
+      return { category: updatedCategory!, referenceUnit: createdReferenceUnit! };
+    },
+  );
+}