@tailor-platform/erp-kit 0.0.1 → 0.1.0

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

@@ -0,0 +1,62 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { CannotDeactivateReferenceUnitError, UnitNotFoundError } from "../lib/errors";
+import { permissions } from "../permissions";
+
+export interface DeactivateUnitInput {
+  unitId: string;
+}
+
+/**
+ * Function: deactivateUnit
+ *
+ * Disables a unit of measure from being used in new product assignments
+ * and quantity conversions while preserving all historical data.
+ * Reference units cannot be deactivated.
+ */
+export const deactivateUnit = defineCommand(
+  permissions.deactivateUnit,
+  async (db: DB, input: DeactivateUnitInput) => {
+    // 1. Find unit by ID
+    const unit = await db
+      .selectFrom("Unit")
+      .selectAll()
+      .where("id", "=", input.unitId)
+      .executeTakeFirst();
+
+    // 2. If not found, throw error
+    if (!unit) {
+      throw new UnitNotFoundError(input.unitId);
+    }
+
+    // 3. Check if unit is reference unit for its category
+    const category = await db
+      .selectFrom("UoMCategory")
+      .selectAll()
+      .where("id", "=", unit.categoryId)
+      .executeTakeFirst();
+
+    if (category?.referenceUnitId === unit.id) {
+      throw new CannotDeactivateReferenceUnitError(input.unitId);
+    }
+
+    // 4. If already inactive, return unit (idempotent)
+    if (!unit.isActive) {
+      return { unit };
+    }
+
+    // 5. Update isActive = false
+    const updatedUnit = await db
+      .updateTable("Unit")
+      .set({
+        isActive: false,
+        updatedAt: new Date(),
+      })
+      .where("id", "=", input.unitId)
+      .returningAll()
+      .executeTakeFirst();
+
+    // 6. Return updated unit
+    return { unit: updatedUnit! };
+  },
+);

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

@@ -0,0 +1,98 @@
+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 { CannotSetInactiveAsBaseCurrencyError, CurrencyNotFoundError } from "../lib/errors";
+import { baseCurrencyEUR, baseCurrencyUSD, inactiveCurrency } from "../testing/fixtures";
+import { setBaseCurrency } from "./setBaseCurrency";
+
+describe("setBaseCurrency", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["primitives:setBaseCurrency"],
+  };
+
+  // Error cases
+  it("throws when currency doesn't exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(undefined);
+
+    await expect(
+      setBaseCurrency(
+        db,
+        {
+          currencyId: "nonexistent-currency",
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(CurrencyNotFoundError);
+  });
+
+  it("throws when currency is inactive", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(inactiveCurrency);
+
+    await expect(
+      setBaseCurrency(
+        db,
+        {
+          currencyId: inactiveCurrency.id,
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(CannotSetInactiveAsBaseCurrencyError);
+  });
+
+  // Idempotent cases
+  it("returns currency unchanged when already base", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(baseCurrencyUSD); // Already base currency
+
+    const result = await setBaseCurrency(
+      db,
+      {
+        currencyId: baseCurrencyUSD.id,
+      },
+      ctx,
+    );
+
+    expect(result.currency).toEqual(baseCurrencyUSD);
+    expect(spies.update).not.toHaveBeenCalled();
+  });
+
+  // Success cases
+  it("changes base currency", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const newBaseCurrency = {
+      ...baseCurrencyEUR,
+      isBaseCurrency: true,
+      updatedAt: new Date("2024-01-15T00:00:00.000Z"),
+    };
+
+    spies.select
+      .mockReturnValueOnce(baseCurrencyEUR) // Target currency lookup
+      .mockReturnValueOnce(baseCurrencyUSD); // Current base currency lookup
+    spies.update
+      .mockReturnValueOnce({ ...baseCurrencyUSD, isBaseCurrency: false }) // Remove base from old
+      .mockReturnValueOnce(newBaseCurrency); // Set base on new
+
+    const result = await setBaseCurrency(
+      db,
+      {
+        currencyId: baseCurrencyEUR.id,
+      },
+      ctx,
+    );
+
+    expect(result.currency.isBaseCurrency).toBe(true);
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("throws when permission is missing", async () => {
+    const { db } = createMockDb<DB>();
+    const denied: CommandContext = { actorId: "test-actor", permissions: [] };
+    await expect(setBaseCurrency(db, { currencyId: "cur-1" }, denied)).rejects.toBeInstanceOf(
+      InsufficientPermissionError,
+    );
+  });
+});

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

@@ -0,0 +1,74 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { CannotSetInactiveAsBaseCurrencyError, CurrencyNotFoundError } from "../lib/errors";
+import { permissions } from "../permissions";
+
+export interface SetBaseCurrencyInput {
+  currencyId: string;
+}
+
+/**
+ * Function: setBaseCurrency
+ *
+ * Changes the organization's base currency to a different active currency.
+ * The base currency serves as the default for financial reporting.
+ */
+export const setBaseCurrency = defineCommand(
+  permissions.setBaseCurrency,
+  async (db: DB, input: SetBaseCurrencyInput) => {
+    // 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 currency is active
+    if (!currency.isActive) {
+      throw new CannotSetInactiveAsBaseCurrencyError(input.currencyId);
+    }
+
+    // 4. If already base currency, return (idempotent)
+    if (currency.isBaseCurrency) {
+      return { currency };
+    }
+
+    // 5. Find current base currency
+    const currentBase = await db
+      .selectFrom("Currency")
+      .selectAll()
+      .where("isBaseCurrency", "=", true)
+      .executeTakeFirst();
+
+    // 6. Remove base flag from current base
+    if (currentBase) {
+      await db
+        .updateTable("Currency")
+        .set({
+          isBaseCurrency: false,
+          updatedAt: new Date(),
+        })
+        .where("id", "=", currentBase.id)
+        .returningAll()
+        .executeTakeFirst();
+    }
+
+    // 7. Set base flag on target currency
+    const updatedCurrency = await db
+      .updateTable("Currency")
+      .set({
+        isBaseCurrency: true,
+        updatedAt: new Date(),
+      })
+      .where("id", "=", input.currencyId)
+      .returningAll()
+      .executeTakeFirst();
+
+    return { currency: updatedCurrency! };
+  },
+);

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

@@ -0,0 +1,108 @@
+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 { UnitNotFoundError, UnitNotInCategoryError } from "../lib/errors";
+import { baseUoMCategory, baseUnitGram, baseUnitKg, baseUnitLiter } from "../testing/fixtures";
+import { setReferenceUnit } from "./setReferenceUnit";
+
+describe("setReferenceUnit", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["primitives:setReferenceUnit"],
+  };
+
+  // Error cases
+  it("throws when unit doesn't exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(undefined);
+
+    await expect(
+      setReferenceUnit(
+        db,
+        {
+          unitId: "nonexistent-unit",
+          categoryId: baseUoMCategory.id,
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(UnitNotFoundError);
+  });
+
+  it("throws when unit is not in specified category", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(baseUnitLiter); // Unit is in category-2, not category-1
+
+    await expect(
+      setReferenceUnit(
+        db,
+        {
+          unitId: baseUnitLiter.id,
+          categoryId: baseUoMCategory.id, // category-1
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(UnitNotInCategoryError);
+  });
+
+  // Idempotent cases
+  it("returns category unchanged when unit is already reference", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseUnitKg) // Unit lookup
+      .mockReturnValueOnce(baseUoMCategory); // Category lookup
+
+    const result = await setReferenceUnit(
+      db,
+      {
+        unitId: baseUnitKg.id,
+        categoryId: baseUoMCategory.id,
+      },
+      ctx,
+    );
+
+    expect(result.category.referenceUnitId).toBe(baseUnitKg.id);
+    expect(spies.update).not.toHaveBeenCalled();
+  });
+
+  // Success cases
+  it("changes reference unit and recalculates conversion factors", async () => {
+    const { db, spies } = createMockDb<DB>();
+    // gram has conversion factor 0.001 (1g = 0.001kg)
+    // When gram becomes reference, kg should become 1000 (1kg = 1000g)
+    const updatedCategory = {
+      ...baseUoMCategory,
+      referenceUnitId: baseUnitGram.id,
+      updatedAt: new Date("2024-01-15T00:00:00.000Z"),
+    };
+
+    spies.select
+      .mockReturnValueOnce(baseUnitGram) // Unit lookup
+      .mockReturnValueOnce(baseUoMCategory) // Category lookup
+      .mockReturnValueOnce([baseUnitKg, baseUnitGram]); // All units in category
+    spies.update
+      .mockReturnValueOnce({ ...baseUnitKg, conversionFactor: 1000 }) // Update kg factor
+      .mockReturnValueOnce({ ...baseUnitGram, conversionFactor: 1.0 }) // Update gram factor
+      .mockReturnValueOnce(updatedCategory); // Update category
+
+    const result = await setReferenceUnit(
+      db,
+      {
+        unitId: baseUnitGram.id,
+        categoryId: baseUoMCategory.id,
+      },
+      ctx,
+    );
+
+    expect(result.category.referenceUnitId).toBe(baseUnitGram.id);
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("throws when permission is missing", async () => {
+    const { db } = createMockDb<DB>();
+    const denied: CommandContext = { actorId: "test-actor", permissions: [] };
+    await expect(
+      setReferenceUnit(db, { unitId: "unit-1", categoryId: "cat-1" }, denied),
+    ).rejects.toBeInstanceOf(InsufficientPermissionError);
+  });
+});

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

@@ -0,0 +1,84 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { UnitNotFoundError, UnitNotInCategoryError } from "../lib/errors";
+import { permissions } from "../permissions";
+
+export interface SetReferenceUnitInput {
+  unitId: string;
+  categoryId: string;
+}
+
+/**
+ * Function: setReferenceUnit
+ *
+ * Changes the reference unit for a UoM category. All conversion factors
+ * are recalculated relative to the new reference unit.
+ */
+export const setReferenceUnit = defineCommand(
+  permissions.setReferenceUnit,
+  async (db: DB, input: SetReferenceUnitInput) => {
+    // 1. Find unit by ID
+    const unit = await db
+      .selectFrom("Unit")
+      .selectAll()
+      .where("id", "=", input.unitId)
+      .executeTakeFirst();
+
+    if (!unit) {
+      throw new UnitNotFoundError(input.unitId);
+    }
+
+    // 2. Check unit belongs to specified category
+    if (unit.categoryId !== input.categoryId) {
+      throw new UnitNotInCategoryError(input.unitId, input.categoryId);
+    }
+
+    // 3. Get category
+    const category = await db
+      .selectFrom("UoMCategory")
+      .selectAll()
+      .where("id", "=", input.categoryId)
+      .executeTakeFirst();
+
+    // 4. If already reference unit, return (idempotent)
+    if (category?.referenceUnitId === input.unitId && category) {
+      return { category };
+    }
+
+    // 5. Get all units in category for recalculation
+    const units = await db
+      .selectFrom("Unit")
+      .selectAll()
+      .where("categoryId", "=", input.categoryId)
+      .execute();
+
+    // 6. Recalculate all conversion factors
+    // new_factor = old_factor / new_reference_old_factor
+    const newReferenceFactor = unit.conversionFactor;
+    for (const u of units) {
+      const newFactor = u.conversionFactor / newReferenceFactor;
+      await db
+        .updateTable("Unit")
+        .set({
+          conversionFactor: newFactor,
+          updatedAt: new Date(),
+        })
+        .where("id", "=", u.id)
+        .returningAll()
+        .executeTakeFirst();
+    }
+
+    // 7. Update category reference unit
+    const updatedCategory = await db
+      .updateTable("UoMCategory")
+      .set({
+        referenceUnitId: input.unitId,
+        updatedAt: new Date(),
+      })
+      .where("id", "=", input.categoryId)
+      .returningAll()
+      .executeTakeFirst();
+
+    return { category: updatedCategory! };
+  },
+);

package/src/modules/primitives/db/currency.ts

@@ -0,0 +1,30 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+
+export interface CreateCurrencyTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createCurrencyType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateCurrencyTypeParams<F>,
+) {
+  return db
+    .type("Currency", {
+      code: db.string().unique().description("ISO 4217 currency code (e.g., USD)"),
+      name: db.string().description("Currency display name (e.g., US Dollar)"),
+      symbol: db.string().description("Currency symbol (e.g., $)"),
+      decimalPlaces: db.int().description("Number of decimal places (0-4)"),
+      isBaseCurrency: db.bool().description("Whether this is the base currency"),
+      isActive: db.bool().description("Whether the currency is active"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const currency = createCurrencyType({});

package/src/modules/primitives/db/exchangeRate.ts

@@ -0,0 +1,28 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+
+export interface CreateExchangeRateTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createExchangeRateType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateExchangeRateTypeParams<F>,
+) {
+  return db
+    .type("ExchangeRate", {
+      sourceCurrencyId: db.uuid().description("Foreign key to source Currency"),
+      targetCurrencyId: db.uuid().description("Foreign key to target Currency"),
+      rate: db.float().description("Conversion rate (source x rate = target)"),
+      effectiveDate: db.date().description("Date from which this rate applies"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const exchangeRate = createExchangeRateType({});

package/src/modules/primitives/db/unit.ts

@@ -0,0 +1,32 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+
+export interface CreateUnitTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createUnitType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateUnitTypeParams<F>,
+) {
+  return db
+    .type("Unit", {
+      name: db.string().description("Unit display name (e.g., Kilogram)"),
+      symbol: db.string().description("Short symbol (e.g., kg)"),
+      categoryId: db.uuid().description("Foreign key to UoMCategory"),
+      conversionFactor: db
+        .float()
+        .description("Multiplier relative to reference unit (reference unit = 1.0)"),
+      roundingPrecision: db.int().description("Decimal places for rounding"),
+      isActive: db.bool().description("Whether the unit is active"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const unit = createUnitType({});

package/src/modules/primitives/db/uomCategory.ts

@@ -0,0 +1,32 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+
+export interface CreateUoMCategoryTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createUoMCategoryType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateUoMCategoryTypeParams<F>,
+) {
+  return db
+    .type("UoMCategory", {
+      name: db.string().unique().description("Category name (e.g., Weight, Volume, Length)"),
+      description: db
+        .string({ optional: true })
+        .description("Optional description of the category"),
+      referenceUnitId: db
+        .uuid({ optional: true })
+        .description("Foreign key to the reference Unit for conversions"),
+      isActive: db.bool().description("Whether the category is active"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const uomCategory = createUoMCategoryType({});

package/src/modules/primitives/docs/commands/ActivateCategory.md

@@ -0,0 +1,34 @@
+# ActivateCategory
+
+## Overview
+
+ActivateCategory re-enables a previously deactivated UoM category, making it and its units available for new product assignments and transactions. This command supports scenarios where a temporarily suspended category needs to be restored to active use.
+
+## Business Rules
+
+- Target category must exist in the system
+- Target category must be in Inactive status
+- Activating an already active category returns success with no state change
+- All units within the category remain in their current state (active or inactive)
+- Products previously using this category's units are not automatically re-enabled
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B{Category exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Current status?}
+    D -->|Active| E[Return success: already active]
+    D -->|Inactive| F[Update status to Active]
+    F --> G[Return activated category]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **Category not found**: Specified category ID does not exist - return not found error
+- **Invalid category ID**: Malformed or empty ID provided - return validation error

package/src/modules/primitives/docs/commands/ActivateCurrency.md

@@ -0,0 +1,33 @@
+# ActivateCurrency
+
+## Overview
+
+ActivateCurrency re-enables a previously deactivated currency, making it available for new transactions. This command supports scenarios where a temporarily suspended currency needs to be restored to active use, such as resuming operations in a market after a temporary exit.
+
+## Business Rules
+
+- Target currency must exist in the system
+- Target currency must be in Inactive status
+- Activating an already active currency returns success with no state change
+- No impact on historical transactions that used this currency while inactive
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B{Currency exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Current status?}
+    D -->|Active| E[Return success: already active]
+    D -->|Inactive| F[Update status to Active]
+    F --> G[Return activated currency]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **Currency not found**: Specified currency ID does not exist - return not found error
+- **Invalid currency ID**: Malformed or empty ID provided - return validation error

package/src/modules/primitives/docs/commands/ActivateUnit.md

@@ -0,0 +1,34 @@
+# ActivateUnit
+
+## Overview
+
+ActivateUnit re-enables a previously deactivated unit of measure, making it available for new product assignments and quantity conversions. This command supports scenarios where a temporarily suspended unit needs to be restored to active use.
+
+## Business Rules
+
+- Target unit must exist in the system
+- Target unit must be in Inactive status
+- Activating an already active unit returns success with no state change
+- The unit's category must be active for the unit to be usable in new assignments
+- Historical transactions using this unit are not affected by activation
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B{Unit exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Current status?}
+    D -->|Active| E[Return success: already active]
+    D -->|Inactive| F[Update status to Active]
+    F --> G[Return activated unit]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **Unit not found**: Specified unit ID does not exist - return not found error
+- **Invalid unit ID**: Malformed or empty ID provided - return validation error