@tailor-platform/erp-kit 0.0.1 → 0.1.1

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

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

@@ -0,0 +1,191 @@
+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 {
+  DuplicateCurrencyCodeError,
+  InvalidDecimalPlacesError,
+  InvalidISOCodeError,
+} from "../lib/errors";
+import { baseCurrencyUSD } from "../testing/fixtures";
+import { makeCreateCurrency } from "./createCurrency";
+
+const createCurrency = makeCreateCurrency();
+
+describe("createCurrency", () => {
+  const ctx: CommandContext = { actorId: "test-actor", permissions: ["primitives:createCurrency"] };
+
+  // Error cases
+  it("throws when ISO code is invalid format", async () => {
+    const { db } = createMockDb<DB>();
+
+    await expect(
+      createCurrency(
+        db,
+        {
+          code: "us", // Should be 3 uppercase letters
+          name: "US Dollar",
+          symbol: "$",
+          decimalPlaces: 2,
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(InvalidISOCodeError);
+  });
+
+  it("throws when ISO code already exists", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(baseCurrencyUSD);
+
+    await expect(
+      createCurrency(
+        db,
+        {
+          code: "USD",
+          name: "US Dollar",
+          symbol: "$",
+          decimalPlaces: 2,
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(DuplicateCurrencyCodeError);
+  });
+
+  it("throws when decimal places is negative", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(undefined); // No existing currency
+
+    await expect(
+      createCurrency(
+        db,
+        {
+          code: "XXX",
+          name: "Test Currency",
+          symbol: "X",
+          decimalPlaces: -1,
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(InvalidDecimalPlacesError);
+  });
+
+  it("throws when decimal places exceeds maximum", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(undefined); // No existing currency
+
+    await expect(
+      createCurrency(
+        db,
+        {
+          code: "XXX",
+          name: "Test Currency",
+          symbol: "X",
+          decimalPlaces: 5,
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(InvalidDecimalPlacesError);
+  });
+
+  // Success cases
+  it("creates first currency as base currency", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const createdCurrency = {
+      id: "new-currency-id",
+      code: "USD",
+      name: "US Dollar",
+      symbol: "$",
+      decimalPlaces: 2,
+      isBaseCurrency: true,
+      isActive: true,
+      createdAt: new Date("2024-01-15T00:00:00.000Z"),
+      updatedAt: null,
+    };
+
+    spies.select
+      .mockReturnValueOnce(undefined) // No existing with same code
+      .mockReturnValueOnce(undefined); // No existing currencies (first currency)
+    spies.insert.mockReturnValue(createdCurrency);
+
+    const result = await createCurrency(
+      db,
+      {
+        code: "USD",
+        name: "US Dollar",
+        symbol: "$",
+        decimalPlaces: 2,
+      },
+      ctx,
+    );
+
+    expect(result.currency.code).toBe("USD");
+    expect(result.currency.isBaseCurrency).toBe(true);
+    expect(result.currency.isActive).toBe(true);
+  });
+
+  it("creates subsequent currency as non-base", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const createdCurrency = {
+      id: "new-currency-id",
+      code: "EUR",
+      name: "Euro",
+      symbol: "€",
+      decimalPlaces: 2,
+      isBaseCurrency: false,
+      isActive: true,
+      createdAt: new Date("2024-01-15T00:00:00.000Z"),
+      updatedAt: null,
+    };
+
+    spies.select
+      .mockReturnValueOnce(undefined) // No existing with same code
+      .mockReturnValueOnce(baseCurrencyUSD); // Existing currency exists
+    spies.insert.mockReturnValue(createdCurrency);
+
+    const result = await createCurrency(
+      db,
+      {
+        code: "EUR",
+        name: "Euro",
+        symbol: "€",
+        decimalPlaces: 2,
+      },
+      ctx,
+    );
+
+    expect(result.currency.code).toBe("EUR");
+    expect(result.currency.isBaseCurrency).toBe(false);
+  });
+
+  it("throws when permission is missing", async () => {
+    const { db } = createMockDb<DB>();
+    const denied: CommandContext = { actorId: "test-actor", permissions: [] };
+    await expect(
+      createCurrency(db, { code: "USD", name: "US Dollar", symbol: "$", decimalPlaces: 2 }, denied),
+    ).rejects.toBeInstanceOf(InsufficientPermissionError);
+  });
+
+  it("passes custom fields through to insert", async () => {
+    const createCurrencyWithFields = makeCreateCurrency<{ region: string }>();
+    const { db, spies } = createMockDb<DB>();
+    const createdCurrency = {
+      ...baseCurrencyUSD,
+      id: "new-currency-id",
+      code: "GBP",
+      region: "Europe",
+    };
+
+    spies.select
+      .mockReturnValueOnce(undefined) // No existing with same code
+      .mockReturnValueOnce(undefined); // No existing currencies
+    spies.insert.mockReturnValue(createdCurrency);
+
+    await createCurrencyWithFields(
+      db,
+      { code: "GBP", name: "British Pound", symbol: "£", decimalPlaces: 2, region: "Europe" },
+      ctx,
+    );
+
+    expect(spies.values).toHaveBeenNthCalledWith(1, expect.objectContaining({ region: "Europe" }));
+  });
+});

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

@@ -0,0 +1,77 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import {
+  DuplicateCurrencyCodeError,
+  InvalidDecimalPlacesError,
+  InvalidISOCodeError,
+} from "../lib/errors";
+import { permissions } from "../permissions";
+
+interface CreateCurrencyInput {
+  code: string;
+  name: string;
+  symbol: string;
+  decimalPlaces: number;
+}
+
+const ISO_CODE_PATTERN = /^[A-Z]{3}$/;
+
+/**
+ * Function: createCurrency
+ *
+ * Establishes a new monetary unit with its ISO 4217 code, display symbol,
+ * name, and decimal precision. The first currency becomes the base currency.
+ */
+export function makeCreateCurrency<CF extends Record<string, unknown>>() {
+  return defineCommand(
+    permissions.createCurrency,
+    async (db: DB, input: CreateCurrencyInput & CF) => {
+      const { code, name, symbol, decimalPlaces, ...customFields } = input;
+
+      // 1. Validate ISO code format
+      if (!ISO_CODE_PATTERN.test(code)) {
+        throw new InvalidISOCodeError(code);
+      }
+
+      // 2. Check code uniqueness
+      const existingCurrency = await db
+        .selectFrom("Currency")
+        .selectAll()
+        .where("code", "=", code)
+        .executeTakeFirst();
+
+      if (existingCurrency) {
+        throw new DuplicateCurrencyCodeError(code);
+      }
+
+      // 3. Validate decimal places
+      if (decimalPlaces < 0 || decimalPlaces > 4) {
+        throw new InvalidDecimalPlacesError(decimalPlaces);
+      }
+
+      // 4. Check if this is the first currency
+      const anyCurrency = await db.selectFrom("Currency").selectAll().executeTakeFirst();
+
+      const isBaseCurrency = !anyCurrency;
+
+      // 5. Create currency
+      const currency = await db
+        .insertInto("Currency")
+        .values({
+          ...(customFields as Record<string, unknown>),
+          code,
+          name,
+          symbol,
+          decimalPlaces,
+          isBaseCurrency,
+          isActive: true,
+          createdAt: new Date(),
+          updatedAt: null,
+        })
+        .returningAll()
+        .executeTakeFirst();
+
+      return { currency: currency! };
+    },
+  );
+}

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

@@ -0,0 +1,216 @@
+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,
+  InactiveCurrencyError,
+  InvalidExchangeRateError,
+  SameCurrencyPairError,
+} from "../lib/errors";
+import {
+  baseCurrencyEUR,
+  baseCurrencyUSD,
+  baseExchangeRateUSDtoEUR,
+  inactiveCurrency,
+} from "../testing/fixtures";
+import { makeCreateExchangeRate } from "./createExchangeRate";
+
+const createExchangeRate = makeCreateExchangeRate();
+
+describe("createExchangeRate", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["primitives:createExchangeRate"],
+  };
+
+  // Error cases
+  it("throws when source currency doesn't exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(undefined);
+
+    await expect(
+      createExchangeRate(
+        db,
+        {
+          sourceCurrencyId: "nonexistent-currency",
+          targetCurrencyId: baseCurrencyEUR.id,
+          rate: 0.92,
+          effectiveDate: new Date("2024-01-15"),
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(CurrencyNotFoundError);
+  });
+
+  it("throws when source currency is inactive", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(inactiveCurrency);
+
+    await expect(
+      createExchangeRate(
+        db,
+        {
+          sourceCurrencyId: inactiveCurrency.id,
+          targetCurrencyId: baseCurrencyEUR.id,
+          rate: 0.92,
+          effectiveDate: new Date("2024-01-15"),
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(InactiveCurrencyError);
+  });
+
+  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(
+      createExchangeRate(
+        db,
+        {
+          sourceCurrencyId: baseCurrencyUSD.id,
+          targetCurrencyId: "nonexistent-currency",
+          rate: 0.92,
+          effectiveDate: new Date("2024-01-15"),
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(CurrencyNotFoundError);
+  });
+
+  it("throws when target currency is inactive", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseCurrencyUSD) // Source exists and active
+      .mockReturnValueOnce(inactiveCurrency); // Target is inactive
+
+    await expect(
+      createExchangeRate(
+        db,
+        {
+          sourceCurrencyId: baseCurrencyUSD.id,
+          targetCurrencyId: inactiveCurrency.id,
+          rate: 0.92,
+          effectiveDate: new Date("2024-01-15"),
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(InactiveCurrencyError);
+  });
+
+  it("throws when source and target are the same", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(baseCurrencyUSD);
+
+    await expect(
+      createExchangeRate(
+        db,
+        {
+          sourceCurrencyId: baseCurrencyUSD.id,
+          targetCurrencyId: baseCurrencyUSD.id,
+          rate: 1.0,
+          effectiveDate: new Date("2024-01-15"),
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(SameCurrencyPairError);
+  });
+
+  it("throws when rate is not positive", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseCurrencyUSD).mockReturnValueOnce(baseCurrencyEUR);
+
+    await expect(
+      createExchangeRate(
+        db,
+        {
+          sourceCurrencyId: baseCurrencyUSD.id,
+          targetCurrencyId: baseCurrencyEUR.id,
+          rate: 0,
+          effectiveDate: new Date("2024-01-15"),
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(InvalidExchangeRateError);
+  });
+
+  // Success cases
+  it("creates exchange rate successfully", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const createdRate = {
+      id: "new-rate-id",
+      sourceCurrencyId: baseCurrencyUSD.id,
+      targetCurrencyId: baseCurrencyEUR.id,
+      rate: 0.92,
+      effectiveDate: new Date("2024-01-15T00:00:00.000Z"),
+      createdAt: new Date("2024-01-15T00:00:00.000Z"),
+      updatedAt: null,
+    };
+
+    spies.select.mockReturnValueOnce(baseCurrencyUSD).mockReturnValueOnce(baseCurrencyEUR);
+    spies.insert.mockReturnValue(createdRate);
+
+    const result = await createExchangeRate(
+      db,
+      {
+        sourceCurrencyId: baseCurrencyUSD.id,
+        targetCurrencyId: baseCurrencyEUR.id,
+        rate: 0.92,
+        effectiveDate: new Date("2024-01-15"),
+      },
+      ctx,
+    );
+
+    expect(result.exchangeRate.rate).toBe(0.92);
+    expect(result.exchangeRate.sourceCurrencyId).toBe(baseCurrencyUSD.id);
+    expect(result.exchangeRate.targetCurrencyId).toBe(baseCurrencyEUR.id);
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("throws when permission is missing", async () => {
+    const { db } = createMockDb<DB>();
+    const denied: CommandContext = { actorId: "test-actor", permissions: [] };
+    await expect(
+      createExchangeRate(
+        db,
+        {
+          sourceCurrencyId: "cur-1",
+          targetCurrencyId: "cur-2",
+          rate: 1.5,
+          effectiveDate: new Date("2024-01-15"),
+        },
+        denied,
+      ),
+    ).rejects.toBeInstanceOf(InsufficientPermissionError);
+  });
+
+  it("passes custom fields through to insert", async () => {
+    const createExchangeRateWithFields = makeCreateExchangeRate<{ source: string }>();
+    const { db, spies } = createMockDb<DB>();
+    const createdRate = {
+      ...baseExchangeRateUSDtoEUR,
+      id: "new-rate-id",
+      source: "ECB",
+    };
+
+    spies.select.mockReturnValueOnce(baseCurrencyUSD).mockReturnValueOnce(baseCurrencyEUR);
+    spies.insert.mockReturnValue(createdRate);
+
+    await createExchangeRateWithFields(
+      db,
+      {
+        sourceCurrencyId: baseCurrencyUSD.id,
+        targetCurrencyId: baseCurrencyEUR.id,
+        rate: 0.92,
+        effectiveDate: new Date("2024-01-15"),
+        source: "ECB",
+      },
+      ctx,
+    );
+
+    expect(spies.values).toHaveBeenNthCalledWith(1, expect.objectContaining({ source: "ECB" }));
+  });
+});