@tailor-platform/erp-kit 0.0.1 → 0.1.1

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

@@ -0,0 +1,91 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import {
+  CurrencyNotFoundError,
+  InactiveCurrencyError,
+  InvalidExchangeRateError,
+  SameCurrencyPairError,
+} from "../lib/errors";
+import { permissions } from "../permissions";
+
+interface CreateExchangeRateInput {
+  sourceCurrencyId: string;
+  targetCurrencyId: string;
+  rate: number;
+  effectiveDate: Date;
+}
+
+/**
+ * Function: createExchangeRate
+ *
+ * Establishes a new conversion ratio between a currency pair with a specific
+ * effective date. The rate specifies how many units of the target currency
+ * equal one unit of the source currency.
+ */
+export function makeCreateExchangeRate<CF extends Record<string, unknown>>() {
+  return defineCommand(
+    permissions.createExchangeRate,
+    async (db: DB, input: CreateExchangeRateInput & CF) => {
+      const { sourceCurrencyId, targetCurrencyId, rate, effectiveDate, ...customFields } = input;
+
+      // 1. Check source currency exists
+      const sourceCurrency = await db
+        .selectFrom("Currency")
+        .selectAll()
+        .where("id", "=", sourceCurrencyId)
+        .executeTakeFirst();
+
+      if (!sourceCurrency) {
+        throw new CurrencyNotFoundError(sourceCurrencyId);
+      }
+
+      // 2. Check source currency is active
+      if (!sourceCurrency.isActive) {
+        throw new InactiveCurrencyError(sourceCurrency.code);
+      }
+
+      // 3. Check target currency exists
+      const targetCurrency = await db
+        .selectFrom("Currency")
+        .selectAll()
+        .where("id", "=", targetCurrencyId)
+        .executeTakeFirst();
+
+      if (!targetCurrency) {
+        throw new CurrencyNotFoundError(targetCurrencyId);
+      }
+
+      // 4. Check target currency is active
+      if (!targetCurrency.isActive) {
+        throw new InactiveCurrencyError(targetCurrency.code);
+      }
+
+      // 5. Check source and target are different
+      if (sourceCurrencyId === targetCurrencyId) {
+        throw new SameCurrencyPairError(sourceCurrencyId);
+      }
+
+      // 6. Validate rate is positive
+      if (rate <= 0) {
+        throw new InvalidExchangeRateError(rate);
+      }
+
+      // 7. Create exchange rate
+      const exchangeRate = await db
+        .insertInto("ExchangeRate")
+        .values({
+          ...(customFields as Record<string, unknown>),
+          sourceCurrencyId,
+          targetCurrencyId,
+          rate,
+          effectiveDate,
+          createdAt: new Date(),
+          updatedAt: null,
+        })
+        .returningAll()
+        .executeTakeFirst();
+
+      return { exchangeRate: exchangeRate! };
+    },
+  );
+}

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

@@ -0,0 +1,214 @@
+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 {
+  CategoryNotActiveError,
+  DuplicateUnitSymbolError,
+  InvalidConversionFactorError,
+  InvalidRoundingPrecisionError,
+  UoMCategoryNotFoundError,
+} from "../lib/errors";
+import { baseUoMCategory, baseUnitKg } from "../testing/fixtures";
+import { makeCreateUnit } from "./createUnit";
+
+const createUnit = makeCreateUnit();
+
+describe("createUnit", () => {
+  const ctx: CommandContext = { actorId: "test-actor", permissions: ["primitives:createUnit"] };
+
+  const inactiveCategory = {
+    ...baseUoMCategory,
+    isActive: false,
+  };
+
+  // Error cases
+  it("throws when category doesn't exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(undefined);
+
+    await expect(
+      createUnit(
+        db,
+        {
+          categoryId: "nonexistent-category",
+          name: "Ounce",
+          symbol: "oz",
+          conversionFactor: 0.0283495,
+          roundingPrecision: 2,
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(UoMCategoryNotFoundError);
+  });
+
+  it("throws when category is inactive", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(inactiveCategory);
+
+    await expect(
+      createUnit(
+        db,
+        {
+          categoryId: inactiveCategory.id,
+          name: "Ounce",
+          symbol: "oz",
+          conversionFactor: 0.0283495,
+          roundingPrecision: 2,
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(CategoryNotActiveError);
+  });
+
+  it("throws when symbol already exists in category", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseUoMCategory) // Category lookup
+      .mockReturnValueOnce(baseUnitKg); // Existing unit with same symbol
+
+    await expect(
+      createUnit(
+        db,
+        {
+          categoryId: baseUoMCategory.id,
+          name: "Kilogram Duplicate",
+          symbol: "kg",
+          conversionFactor: 1.0,
+          roundingPrecision: 2,
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(DuplicateUnitSymbolError);
+  });
+
+  it("throws when conversion factor is not positive", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseUoMCategory) // Category lookup
+      .mockReturnValueOnce(undefined); // No duplicate symbol
+
+    await expect(
+      createUnit(
+        db,
+        {
+          categoryId: baseUoMCategory.id,
+          name: "Invalid Unit",
+          symbol: "inv",
+          conversionFactor: 0,
+          roundingPrecision: 2,
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(InvalidConversionFactorError);
+  });
+
+  it("throws when rounding precision is negative", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseUoMCategory) // Category lookup
+      .mockReturnValueOnce(undefined); // No duplicate symbol
+
+    await expect(
+      createUnit(
+        db,
+        {
+          categoryId: baseUoMCategory.id,
+          name: "Invalid Unit",
+          symbol: "inv",
+          conversionFactor: 1.0,
+          roundingPrecision: -1,
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(InvalidRoundingPrecisionError);
+  });
+
+  // Success cases
+  it("creates unit successfully", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const createdUnit = {
+      id: "new-unit-id",
+      name: "Ounce",
+      symbol: "oz",
+      categoryId: baseUoMCategory.id,
+      conversionFactor: 0.0283495,
+      roundingPrecision: 2,
+      isActive: true,
+      createdAt: new Date("2024-01-15T00:00:00.000Z"),
+      updatedAt: null,
+    };
+
+    spies.select
+      .mockReturnValueOnce(baseUoMCategory) // Category lookup
+      .mockReturnValueOnce(undefined); // No duplicate symbol
+    spies.insert.mockReturnValue(createdUnit);
+
+    const result = await createUnit(
+      db,
+      {
+        categoryId: baseUoMCategory.id,
+        name: "Ounce",
+        symbol: "oz",
+        conversionFactor: 0.0283495,
+        roundingPrecision: 2,
+      },
+      ctx,
+    );
+
+    expect(result.unit.name).toBe("Ounce");
+    expect(result.unit.symbol).toBe("oz");
+    expect(result.unit.isActive).toBe(true);
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("throws when permission is missing", async () => {
+    const { db } = createMockDb<DB>();
+    const denied: CommandContext = { actorId: "test-actor", permissions: [] };
+    await expect(
+      createUnit(
+        db,
+        {
+          categoryId: "cat-1",
+          name: "Test",
+          symbol: "t",
+          conversionFactor: 1,
+          roundingPrecision: 2,
+        },
+        denied,
+      ),
+    ).rejects.toBeInstanceOf(InsufficientPermissionError);
+  });
+
+  it("passes custom fields through to insert", async () => {
+    const createUnitWithFields = makeCreateUnit<{ displayOrder: number }>();
+    const { db, spies } = createMockDb<DB>();
+    const createdUnit = {
+      ...baseUnitKg,
+      id: "new-unit-id",
+      name: "Ounce",
+      symbol: "oz",
+      displayOrder: 5,
+    };
+
+    spies.select
+      .mockReturnValueOnce(baseUoMCategory) // Category lookup
+      .mockReturnValueOnce(undefined); // No duplicate symbol
+    spies.insert.mockReturnValue(createdUnit);
+
+    await createUnitWithFields(
+      db,
+      {
+        categoryId: baseUoMCategory.id,
+        name: "Ounce",
+        symbol: "oz",
+        conversionFactor: 0.0283495,
+        roundingPrecision: 2,
+        displayOrder: 5,
+      },
+      ctx,
+    );
+
+    expect(spies.values).toHaveBeenNthCalledWith(1, expect.objectContaining({ displayOrder: 5 }));
+  });
+});

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

@@ -0,0 +1,88 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import {
+  CategoryNotActiveError,
+  DuplicateUnitSymbolError,
+  InvalidConversionFactorError,
+  InvalidRoundingPrecisionError,
+  UoMCategoryNotFoundError,
+} from "../lib/errors";
+import { permissions } from "../permissions";
+
+interface CreateUnitInput {
+  categoryId: string;
+  name: string;
+  symbol: string;
+  conversionFactor: number;
+  roundingPrecision: number;
+}
+
+/**
+ * Function: createUnit
+ *
+ * Adds a new unit of measure to an existing category with its symbol,
+ * display name, and conversion factor relative to the reference unit.
+ */
+export function makeCreateUnit<CF extends Record<string, unknown>>() {
+  return defineCommand(permissions.createUnit, async (db: DB, input: CreateUnitInput & CF) => {
+    const { categoryId, name, symbol, conversionFactor, roundingPrecision, ...customFields } =
+      input;
+
+    // 1. Check category exists
+    const category = await db
+      .selectFrom("UoMCategory")
+      .selectAll()
+      .where("id", "=", categoryId)
+      .executeTakeFirst();
+
+    if (!category) {
+      throw new UoMCategoryNotFoundError(categoryId);
+    }
+
+    // 2. Check category is active
+    if (!category.isActive) {
+      throw new CategoryNotActiveError(categoryId);
+    }
+
+    // 3. Check symbol uniqueness within category
+    const existingUnit = await db
+      .selectFrom("Unit")
+      .selectAll()
+      .where("categoryId", "=", categoryId)
+      .where("symbol", "=", symbol)
+      .executeTakeFirst();
+
+    if (existingUnit) {
+      throw new DuplicateUnitSymbolError(symbol, categoryId);
+    }
+
+    // 4. Validate conversion factor
+    if (conversionFactor <= 0) {
+      throw new InvalidConversionFactorError(conversionFactor);
+    }
+
+    // 5. Validate rounding precision
+    if (roundingPrecision < 0) {
+      throw new InvalidRoundingPrecisionError(roundingPrecision);
+    }
+
+    // 6. Create unit
+    const unit = await db
+      .insertInto("Unit")
+      .values({
+        ...(customFields as Record<string, unknown>),
+        name,
+        symbol,
+        categoryId,
+        conversionFactor,
+        roundingPrecision,
+        isActive: true,
+        createdAt: new Date(),
+        updatedAt: null,
+      })
+      .returningAll()
+      .executeTakeFirst();
+
+    return { unit: unit! };
+  });
+}

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

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb, testNotFound, testPermissionDenied } from "../../testing/index";
+import { type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { CategoryHasActiveUnitsError, UoMCategoryNotFoundError } from "../lib/errors";
+import { baseUoMCategory, baseUnitKg } from "../testing/fixtures";
+import { deactivateCategory } from "./deactivateCategory";
+
+describe("deactivateCategory", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["primitives:deactivateCategory"],
+  };
+
+  const inactiveCategory = {
+    ...baseUoMCategory,
+    isActive: false,
+  };
+
+  it(
+    "throws when category doesn't exist",
+    testNotFound(
+      deactivateCategory,
+      { categoryId: "nonexistent-category" },
+      ctx,
+      UoMCategoryNotFoundError,
+    ),
+  );
+
+  it("throws when category has active units", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseUoMCategory) // Category lookup
+      .mockReturnValueOnce([baseUnitKg]); // Active units check
+
+    await expect(
+      deactivateCategory(
+        db,
+        {
+          categoryId: baseUoMCategory.id,
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(CategoryHasActiveUnitsError);
+  });
+
+  // Idempotent case needs multi-mock setup, kept inline
+  it("returns category unchanged when already inactive", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(inactiveCategory) // Category lookup
+      .mockReturnValueOnce([]); // No active units
+
+    const result = await deactivateCategory(
+      db,
+      {
+        categoryId: inactiveCategory.id,
+      },
+      ctx,
+    );
+
+    expect(result.category).toEqual(inactiveCategory);
+    expect(spies.update).not.toHaveBeenCalled();
+  });
+
+  // Success cases
+  it("deactivates active category with no active units", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const deactivatedCategory = {
+      ...baseUoMCategory,
+      isActive: false,
+      updatedAt: new Date("2024-01-15T00:00:00.000Z"),
+    };
+
+    spies.select
+      .mockReturnValueOnce(baseUoMCategory) // Category lookup
+      .mockReturnValueOnce([]); // No active units
+    spies.update.mockReturnValue(deactivatedCategory);
+
+    const result = await deactivateCategory(
+      db,
+      {
+        categoryId: baseUoMCategory.id,
+      },
+      ctx,
+    );
+
+    expect(result.category.isActive).toBe(false);
+    expect(result.category.updatedAt).not.toBeNull();
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it(
+    "throws when permission is missing",
+    testPermissionDenied(deactivateCategory, { categoryId: "cat-1" }),
+  );
+});

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

@@ -0,0 +1,62 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { CategoryHasActiveUnitsError, UoMCategoryNotFoundError } from "../lib/errors";
+import { permissions } from "../permissions";
+
+export interface DeactivateCategoryInput {
+  categoryId: string;
+}
+
+/**
+ * Function: deactivateCategory
+ *
+ * Disables a UoM category from being used in new product assignments
+ * while preserving historical data. All units must be deactivated first.
+ */
+export const deactivateCategory = defineCommand(
+  permissions.deactivateCategory,
+  async (db: DB, input: DeactivateCategoryInput) => {
+    // 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. Check for active units in this category
+    const activeUnits = await db
+      .selectFrom("Unit")
+      .selectAll()
+      .where("categoryId", "=", input.categoryId)
+      .where("isActive", "=", true)
+      .execute();
+
+    if (activeUnits.length > 0) {
+      throw new CategoryHasActiveUnitsError(input.categoryId);
+    }
+
+    // 4. If already inactive, return category (idempotent)
+    if (!category.isActive) {
+      return { category };
+    }
+
+    // 5. Update isActive = false
+    const updatedCategory = await db
+      .updateTable("UoMCategory")
+      .set({
+        isActive: false,
+        updatedAt: new Date(),
+      })
+      .where("id", "=", input.categoryId)
+      .returningAll()
+      .executeTakeFirst();
+
+    // 6. Return updated category
+    return { category: updatedCategory! };
+  },
+);

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

@@ -0,0 +1,85 @@
+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 { CannotDeactivateBaseCurrencyError, CurrencyNotFoundError } from "../lib/errors";
+import { baseCurrencyEUR, baseCurrencyUSD, inactiveCurrency } from "../testing/fixtures";
+import { deactivateCurrency } from "./deactivateCurrency";
+
+describe("deactivateCurrency", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["primitives:deactivateCurrency"],
+  };
+
+  it(
+    "throws when currency doesn't exist",
+    testNotFound(
+      deactivateCurrency,
+      { currencyId: "nonexistent-currency" },
+      ctx,
+      CurrencyNotFoundError,
+    ),
+  );
+
+  it("throws when attempting to deactivate base currency", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(baseCurrencyUSD); // USD is base currency
+
+    await expect(
+      deactivateCurrency(
+        db,
+        {
+          currencyId: baseCurrencyUSD.id,
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(CannotDeactivateBaseCurrencyError);
+  });
+
+  it(
+    "returns currency unchanged when already inactive",
+    testIdempotent(
+      deactivateCurrency,
+      { currencyId: inactiveCurrency.id },
+      ctx,
+      inactiveCurrency,
+      "currency",
+    ),
+  );
+
+  // Success cases
+  it("deactivates active non-base currency", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const deactivatedCurrency = {
+      ...baseCurrencyEUR,
+      isActive: false,
+      updatedAt: new Date("2024-01-15T00:00:00.000Z"),
+    };
+
+    spies.select.mockReturnValue(baseCurrencyEUR); // EUR is not base currency
+    spies.update.mockReturnValue(deactivatedCurrency);
+
+    const result = await deactivateCurrency(
+      db,
+      {
+        currencyId: baseCurrencyEUR.id,
+      },
+      ctx,
+    );
+
+    expect(result.currency.isActive).toBe(false);
+    expect(result.currency.updatedAt).not.toBeNull();
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it(
+    "throws when permission is missing",
+    testPermissionDenied(deactivateCurrency, { currencyId: "cur-1" }),
+  );
+});

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

@@ -0,0 +1,55 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { CannotDeactivateBaseCurrencyError, CurrencyNotFoundError } from "../lib/errors";
+import { permissions } from "../permissions";
+
+export interface DeactivateCurrencyInput {
+  currencyId: string;
+}
+
+/**
+ * Function: deactivateCurrency
+ *
+ * Disables a currency from being used in new transactions while preserving
+ * historical data. Base currency cannot be deactivated.
+ */
+export const deactivateCurrency = defineCommand(
+  permissions.deactivateCurrency,
+  async (db: DB, input: DeactivateCurrencyInput) => {
+    // 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. Check if base currency
+    if (currency.isBaseCurrency) {
+      throw new CannotDeactivateBaseCurrencyError(input.currencyId);
+    }
+
+    // 4. If already inactive, return currency (idempotent)
+    if (!currency.isActive) {
+      return { currency };
+    }
+
+    // 5. Update isActive = false
+    const updatedCurrency = await db
+      .updateTable("Currency")
+      .set({
+        isActive: false,
+        updatedAt: new Date(),
+      })
+      .where("id", "=", input.currencyId)
+      .returningAll()
+      .executeTakeFirst();
+
+    // 6. Return updated currency
+    return { currency: updatedCurrency! };
+  },
+);