@tailor-platform/erp-kit 0.0.1 → 0.1.0

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

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