@tailor-platform/erp-kit 0.0.1 → 0.1.1

package/src/integration.test.ts

@@ -0,0 +1,63 @@
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import fs from "node:fs";
+import path from "node:path";
+import { describe, it, expect } from "vitest";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_PATH = path.resolve(__dirname, "..", "dist", "cli.js");
+const REPO_ROOT = path.resolve(__dirname, "..", "..", "..");
+
+const skipReason = fs.existsSync(CLI_PATH) ? undefined : "Run `pnpm build` first";
+
+describe.skipIf(skipReason)("integration", () => {
+  it("check command runs against sdk-plugins modules", () => {
+    // mdschema may report validation errors in real docs, so we allow non-zero exit codes
+    // but verify the CLI itself doesn't crash with an unexpected error
+    try {
+      const result = execFileSync(
+        "node",
+        [CLI_PATH, "check", "--modules-root", "packages/erp-kit/src/modules"],
+        {
+          cwd: REPO_ROOT,
+          encoding: "utf-8",
+          env: { ...process.env },
+        },
+      );
+      expect(result).toBeDefined();
+    } catch (err: unknown) {
+      const error = err as { status: number; stderr: string };
+      // exit code 1 = validation errors in docs (acceptable)
+      // exit code 2 = CLI usage error (unexpected)
+      expect(error.status).toBe(1);
+    }
+  });
+
+  it("sync-check command runs against sdk-plugins modules", () => {
+    try {
+      const result = execFileSync(
+        "node",
+        [CLI_PATH, "sync-check", "--modules-root", "packages/erp-kit/src/modules"],
+        {
+          cwd: REPO_ROOT,
+          encoding: "utf-8",
+          env: { ...process.env },
+        },
+      );
+      expect(result).toContain("docs-sync-check");
+    } catch (err: unknown) {
+      const error = err as { status: number; stdout: string };
+      // sync-check may fail with errors=1 but should still produce a report
+      expect(error.stdout).toContain("docs-sync-check");
+    }
+  });
+
+  it("--help prints usage", () => {
+    const result = execFileSync("node", [CLI_PATH, "--help"], {
+      encoding: "utf-8",
+    });
+    expect(result).toContain("erp-kit");
+    expect(result).toContain("check");
+    expect(result).toContain("scaffold");
+  });
+});

package/src/mdschema.ts

@@ -0,0 +1,48 @@
+import path from "node:path";
+import fs from "node:fs";
+import { execFile } from "node:child_process";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+interface PackageJson {
+  bin?: string | Record<string, string>;
+}
+
+export function getMdschemaBin(): string {
+  const pkgPath = require.resolve("@jackchuka/mdschema/package.json");
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as PackageJson;
+  const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.mdschema;
+  if (!bin) {
+    throw new Error("Could not resolve mdschema binary from package.json bin field");
+  }
+  return path.join(path.dirname(pkgPath), bin);
+}
+
+export interface MdschemaResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export function runMdschema(args: string[], cwd?: string): Promise<MdschemaResult> {
+  return new Promise((resolve) => {
+    execFile(
+      getMdschemaBin(),
+      args,
+      { encoding: "utf-8", cwd, timeout: 30_000 },
+      (error, stdout, stderr) => {
+        if (error) {
+          const execError = error as NodeJS.ErrnoException & { status?: number };
+          resolve({
+            exitCode: execError.code === "ENOENT" ? 127 : (execError.status ?? 1),
+            stdout: stdout ?? "",
+            stderr: stderr ?? "",
+          });
+        } else {
+          resolve({ exitCode: 0, stdout: stdout ?? "", stderr: stderr ?? "" });
+        }
+      },
+    );
+  });
+}

package/src/mockServer.ts

@@ -0,0 +1,55 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+export interface MockServer {
+  url: string;
+  port: number;
+  stop: () => Promise<void>;
+}
+
+/**
+ * Start a Mockoon mock server from a mock.json file.
+ * Returns a handle with the server URL and a stop function.
+ */
+export async function createMockServer(mockJsonPath: string, port?: number): Promise<MockServer> {
+  const { MockoonServer, createLoggerInstance, listenServerEvents } =
+    await import("@mockoon/commons-server");
+  type Environment = import("@mockoon/commons").Environment;
+
+  const resolvedPath = resolve(mockJsonPath);
+  const environment = JSON.parse(readFileSync(resolvedPath, "utf-8")) as Environment;
+  if (port !== undefined) {
+    environment.port = port;
+  }
+  const actualPort = environment.port;
+
+  const logger = createLoggerInstance(null);
+  const server = new MockoonServer(environment, {
+    environmentDirectory: dirname(resolvedPath),
+    enableAdminApi: false,
+    disableTls: true,
+    enableRandomLatency: false,
+    maxTransactionLogs: 100,
+    envVarsPrefix: "MOCKOON_",
+  });
+
+  listenServerEvents(server, environment, logger, false);
+
+  await new Promise<void>((resolve, reject) => {
+    server.on("started", resolve);
+    server.on("error", (errorCode, originalError) => {
+      reject(originalError ?? new Error(`Mockoon error: ${errorCode}`));
+    });
+    server.start();
+  });
+
+  return {
+    url: `http://127.0.0.1:${actualPort}`,
+    port: actualPort,
+    stop: () =>
+      new Promise<void>((resolve) => {
+        server.on("stopped", resolve);
+        server.stop();
+      }),
+  };
+}

package/src/module.ts

@@ -0,0 +1,86 @@
+// shared/internal
+export { defineCommand, type Command } from "./modules/shared/defineCommand";
+export { definePermissions } from "./modules/shared/definePermissions";
+export { requirePermission } from "./modules/shared/requirePermission";
+export { createDomainError, InsufficientPermissionError } from "./modules/shared/errors";
+export type { CommandContext } from "./modules/shared/types";
+export type {
+  InferSchema,
+  Selectable,
+  Insertable,
+  Updateable,
+  FieldsToInsertable,
+} from "./modules/shared/entityTypes";
+
+// primitives
+export { defineModule as definePrimitivesModule } from "./modules/primitives/module";
+export {
+  permissions as primitivesPermissions,
+  own as primitivesOwn,
+  all as primitivesAll,
+} from "./modules/primitives/permissions";
+export {
+  UoMCategoryNotFoundError,
+  UnitNotFoundError,
+  IncompatibleUnitsError,
+  InactiveUnitError,
+  CurrencyNotFoundError,
+  InactiveCurrencyError,
+  ExchangeRateNotFoundError,
+  CannotDeactivateReferenceUnitError,
+  CategoryNotActiveError,
+  DuplicateUnitSymbolError,
+  InvalidConversionFactorError,
+  InvalidRoundingPrecisionError,
+  DuplicateCategoryNameError,
+  CategoryHasActiveUnitsError,
+  UnitNotInCategoryError,
+  InvalidISOCodeError,
+  DuplicateCurrencyCodeError,
+  InvalidDecimalPlacesError,
+  CannotDeactivateBaseCurrencyError,
+  CannotSetInactiveAsBaseCurrencyError,
+  SameCurrencyPairError,
+  InvalidExchangeRateError,
+} from "./modules/primitives/lib/errors";
+export { type ConvertQuantityInput } from "./modules/primitives/command/convertQuantity";
+export { type ActivateCategoryInput } from "./modules/primitives/command/activateCategory";
+export { type DeactivateCategoryInput } from "./modules/primitives/command/deactivateCategory";
+export { type SetReferenceUnitInput } from "./modules/primitives/command/setReferenceUnit";
+export { type ActivateUnitInput } from "./modules/primitives/command/activateUnit";
+export { type DeactivateUnitInput } from "./modules/primitives/command/deactivateUnit";
+export { type ConvertAmountInput } from "./modules/primitives/command/convertAmount";
+export { type ActivateCurrencyInput } from "./modules/primitives/command/activateCurrency";
+export { type DeactivateCurrencyInput } from "./modules/primitives/command/deactivateCurrency";
+export { type SetBaseCurrencyInput } from "./modules/primitives/command/setBaseCurrency";
+// user-management
+export { defineModule as defineUserManagementModule } from "./modules/user-management/module";
+export {
+  permissions as userManagementPermissions,
+  own as userManagementOwn,
+  all as userManagementAll,
+} from "./modules/user-management/permissions";
+export { AuditEventEventType, UserStatus } from "./modules/user-management/generated/enums";
+export {
+  UserNotFoundError,
+  UserAlreadyExistsError,
+  UserNotActiveError,
+  InvalidEmailError,
+  MissingRequiredFieldError,
+  InvalidStatusTransitionError,
+  PermissionNotFoundError,
+  DuplicatePermissionKeyError,
+  InvalidPermissionKeyFormatError,
+  RoleNotFoundError,
+  DuplicateRoleNameError,
+  AssignmentNotFoundError,
+  InvalidEventTypeError,
+} from "./modules/user-management/lib/errors";
+export { type ActivateUserInput } from "./modules/user-management/command/activateUser";
+export { type DeactivateUserInput } from "./modules/user-management/command/deactivateUser";
+export { type ReactivateUserInput } from "./modules/user-management/command/reactivateUser";
+export { type AssignPermissionToRoleInput } from "./modules/user-management/command/assignPermissionToRole";
+export { type RevokePermissionFromRoleInput } from "./modules/user-management/command/revokePermissionFromRole";
+export { type AssignRoleToUserInput } from "./modules/user-management/command/assignRoleToUser";
+export { type RevokeRoleFromUserInput } from "./modules/user-management/command/revokeRoleFromUser";
+export { type LogAuditEventInput } from "./modules/user-management/command/logAuditEvent";

package/src/modules/primitives/README.md

@@ -0,0 +1,39 @@
+# README
+
+## Overview
+
+The Primitives module provides foundational reference data that other ERP modules depend on. It includes unit of measure (UoM) definitions for quantity handling and currency definitions for multi-currency financial operations. These are stable, rarely-changing entities that form the measurement and monetary foundation of the system.
+
+This module combines related configuration primitives to simplify dependency management while keeping tax-related functionality separate due to its regulatory complexity.
+
+## Key Features
+
+- **UoM Categories**: Group related units (e.g., Unit, Weight, Volume, Length, Time) with a designated reference unit for each category
+- **Unit Definitions**: Define individual units with symbols, names, and conversion factors relative to the reference unit
+- **Quantity Conversion**: Convert quantities between any two units within the same category using automatic factor calculation
+- **Rounding Precision**: Configure decimal precision per unit to ensure appropriate rounding for business operations
+- **Currency Definitions**: Define currencies with ISO 4217 codes, symbols, and decimal precision
+- **Base Currency**: Designate a company base currency for reporting and consolidation
+- **Exchange Rates**: Maintain date-based exchange rates between currency pairs
+- **Amount Conversion**: Convert monetary amounts between currencies using applicable rates
+
+## Module Scope
+
+### In Scope
+
+- UoM category and unit management with conversion factors
+- Currency definitions with ISO 4217 codes and symbols
+- Exchange rate storage with effective dates
+- Quantity conversion between compatible units
+- Amount conversion between currencies
+
+### Out of Scope
+
+- Tax configuration and fiscal positions (separate tax-configuration module)
+- Product definitions (product-management module)
+- Transaction recording (sales, purchase, accounting modules)
+- Automatic exchange rate fetching from external APIs
+
+## Module Dependencies
+
+- None (this is a foundational module)

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

@@ -0,0 +1,75 @@
+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 { UoMCategoryNotFoundError } from "../lib/errors";
+import { baseUoMCategory } from "../testing/fixtures";
+import { activateCategory } from "./activateCategory";
+
+describe("activateCategory", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["primitives:activateCategory"],
+  };
+
+  const inactiveCategory = {
+    ...baseUoMCategory,
+    isActive: false,
+  };
+
+  it(
+    "throws when category doesn't exist",
+    testNotFound(
+      activateCategory,
+      { categoryId: "nonexistent-category" },
+      ctx,
+      UoMCategoryNotFoundError,
+    ),
+  );
+
+  it(
+    "returns category unchanged when already active",
+    testIdempotent(
+      activateCategory,
+      { categoryId: baseUoMCategory.id },
+      ctx,
+      baseUoMCategory,
+      "category",
+    ),
+  );
+
+  // Success cases
+  it("activates inactive category", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const activatedCategory = {
+      ...inactiveCategory,
+      isActive: true,
+      updatedAt: new Date("2024-01-15T00:00:00.000Z"),
+    };
+
+    spies.select.mockReturnValue(inactiveCategory);
+    spies.update.mockReturnValue(activatedCategory);
+
+    const result = await activateCategory(
+      db,
+      {
+        categoryId: inactiveCategory.id,
+      },
+      ctx,
+    );
+
+    expect(result.category.isActive).toBe(true);
+    expect(result.category.updatedAt).not.toBeNull();
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it(
+    "throws when permission is missing",
+    testPermissionDenied(activateCategory, { categoryId: "cat-1" }),
+  );
+});

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

@@ -0,0 +1,50 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { UoMCategoryNotFoundError } from "../lib/errors";
+import { permissions } from "../permissions";
+
+export interface ActivateCategoryInput {
+  categoryId: string;
+}
+
+/**
+ * Function: activateCategory
+ *
+ * Re-enables a previously deactivated UoM category, making it and its units
+ * available for new product assignments and transactions.
+ */
+export const activateCategory = defineCommand(
+  permissions.activateCategory,
+  async (db: DB, input: ActivateCategoryInput) => {
+    // 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. If already active, return category (idempotent)
+    if (category.isActive) {
+      return { category };
+    }
+
+    // 4. Update isActive = true
+    const updatedCategory = await db
+      .updateTable("UoMCategory")
+      .set({
+        isActive: true,
+        updatedAt: new Date(),
+      })
+      .where("id", "=", input.categoryId)
+      .returningAll()
+      .executeTakeFirst();
+
+    // 5. Return updated category
+    return { category: updatedCategory! };
+  },
+);

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

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

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

@@ -0,0 +1,50 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { CurrencyNotFoundError } from "../lib/errors";
+import { permissions } from "../permissions";
+
+export interface ActivateCurrencyInput {
+  currencyId: string;
+}
+
+/**
+ * Function: activateCurrency
+ *
+ * Re-enables a previously deactivated currency, making it available
+ * for new transactions.
+ */
+export const activateCurrency = defineCommand(
+  permissions.activateCurrency,
+  async (db: DB, input: ActivateCurrencyInput) => {
+    // 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. If already active, return currency (idempotent)
+    if (currency.isActive) {
+      return { currency };
+    }
+
+    // 4. Update isActive = true
+    const updatedCurrency = await db
+      .updateTable("Currency")
+      .set({
+        isActive: true,
+        updatedAt: new Date(),
+      })
+      .where("id", "=", input.currencyId)
+      .returningAll()
+      .executeTakeFirst();
+
+    // 5. Return updated currency
+    return { currency: updatedCurrency! };
+  },
+);

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

@@ -0,0 +1,53 @@
+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 { UnitNotFoundError } from "../lib/errors";
+import { baseUnitKg, inactiveUnit } from "../testing/fixtures";
+import { activateUnit } from "./activateUnit";
+
+describe("activateUnit", () => {
+  const ctx: CommandContext = { actorId: "test-actor", permissions: ["primitives:activateUnit"] };
+
+  it(
+    "throws when unit doesn't exist",
+    testNotFound(activateUnit, { unitId: "nonexistent-unit" }, ctx, UnitNotFoundError),
+  );
+
+  it(
+    "returns unit unchanged when already active",
+    testIdempotent(activateUnit, { unitId: baseUnitKg.id }, ctx, baseUnitKg, "unit"),
+  );
+
+  // Success cases
+  it("activates inactive unit", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const activatedUnit = {
+      ...inactiveUnit,
+      isActive: true,
+      updatedAt: new Date("2024-01-15T00:00:00.000Z"),
+    };
+
+    spies.select.mockReturnValue(inactiveUnit);
+    spies.update.mockReturnValue(activatedUnit);
+
+    const result = await activateUnit(
+      db,
+      {
+        unitId: inactiveUnit.id,
+      },
+      ctx,
+    );
+
+    expect(result.unit.isActive).toBe(true);
+    expect(result.unit.updatedAt).not.toBeNull();
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("throws when permission is missing", testPermissionDenied(activateUnit, { unitId: "unit-1" }));
+});

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

@@ -0,0 +1,50 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { UnitNotFoundError } from "../lib/errors";
+import { permissions } from "../permissions";
+
+export interface ActivateUnitInput {
+  unitId: string;
+}
+
+/**
+ * Function: activateUnit
+ *
+ * Re-enables a previously deactivated unit of measure, making it available
+ * for new product assignments and quantity conversions.
+ */
+export const activateUnit = defineCommand(
+  permissions.activateUnit,
+  async (db: DB, input: ActivateUnitInput) => {
+    // 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. If already active, return unit (idempotent)
+    if (unit.isActive) {
+      return { unit };
+    }
+
+    // 4. Update isActive = true
+    const updatedUnit = await db
+      .updateTable("Unit")
+      .set({
+        isActive: true,
+        updatedAt: new Date(),
+      })
+      .where("id", "=", input.unitId)
+      .returningAll()
+      .executeTakeFirst();
+
+    // 5. Return updated unit
+    return { unit: updatedUnit! };
+  },
+);