@tailor-platform/erp-kit 0.0.1 → 0.1.0

package/src/modules/primitives/testing/fixtures.ts

@@ -0,0 +1,161 @@
+import type { Currency, ExchangeRate, Schema, UoMCategory, Unit } from "../lib/types";
+
+export const baseUoMCategory = {
+  id: "category-1",
+  name: "Weight",
+  description: "Weight units",
+  referenceUnitId: "unit-kg",
+  isActive: true,
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies UoMCategory<Schema>;
+
+export const baseUnitKg = {
+  id: "unit-kg",
+  name: "Kilogram",
+  symbol: "kg",
+  categoryId: "category-1",
+  conversionFactor: 1.0,
+  roundingPrecision: 2,
+  isActive: true,
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies Unit<Schema>;
+
+export const baseUnitGram = {
+  id: "unit-g",
+  name: "Gram",
+  symbol: "g",
+  categoryId: "category-1",
+  conversionFactor: 0.001,
+  roundingPrecision: 0,
+  isActive: true,
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies Unit<Schema>;
+
+export const baseUnitPound = {
+  id: "unit-lb",
+  name: "Pound",
+  symbol: "lb",
+  categoryId: "category-1",
+  conversionFactor: 0.453592,
+  roundingPrecision: 2,
+  isActive: true,
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies Unit<Schema>;
+
+export const baseUnitLiter = {
+  id: "unit-l",
+  name: "Liter",
+  symbol: "L",
+  categoryId: "category-2",
+  conversionFactor: 1.0,
+  roundingPrecision: 2,
+  isActive: true,
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies Unit<Schema>;
+
+export const inactiveUnit = {
+  id: "unit-inactive",
+  name: "Inactive Unit",
+  symbol: "iu",
+  categoryId: "category-1",
+  conversionFactor: 1.0,
+  roundingPrecision: 2,
+  isActive: false,
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies Unit<Schema>;
+
+// Currency fixtures
+export const baseCurrencyUSD = {
+  id: "currency-usd",
+  code: "USD",
+  name: "US Dollar",
+  symbol: "$",
+  decimalPlaces: 2,
+  isBaseCurrency: true,
+  isActive: true,
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies Currency<Schema>;
+
+export const baseCurrencyEUR = {
+  id: "currency-eur",
+  code: "EUR",
+  name: "Euro",
+  symbol: "€",
+  decimalPlaces: 2,
+  isBaseCurrency: false,
+  isActive: true,
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies Currency<Schema>;
+
+export const baseCurrencyJPY = {
+  id: "currency-jpy",
+  code: "JPY",
+  name: "Japanese Yen",
+  symbol: "¥",
+  decimalPlaces: 0,
+  isBaseCurrency: false,
+  isActive: true,
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies Currency<Schema>;
+
+export const inactiveCurrency = {
+  id: "currency-inactive",
+  code: "XXX",
+  name: "Inactive Currency",
+  symbol: "X",
+  decimalPlaces: 2,
+  isBaseCurrency: false,
+  isActive: false,
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies Currency<Schema>;
+
+// ExchangeRate fixtures
+export const baseExchangeRateUSDtoEUR = {
+  id: "rate-usd-eur-1",
+  sourceCurrencyId: "currency-usd",
+  targetCurrencyId: "currency-eur",
+  rate: 0.92,
+  effectiveDate: new Date("2024-01-15T00:00:00.000Z"),
+  createdAt: new Date("2024-01-15T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies ExchangeRate<Schema>;
+
+export const baseExchangeRateUSDtoJPY = {
+  id: "rate-usd-jpy-1",
+  sourceCurrencyId: "currency-usd",
+  targetCurrencyId: "currency-jpy",
+  rate: 148.5,
+  effectiveDate: new Date("2024-01-15T00:00:00.000Z"),
+  createdAt: new Date("2024-01-15T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies ExchangeRate<Schema>;
+
+export const olderExchangeRateUSDtoEUR = {
+  id: "rate-usd-eur-old",
+  sourceCurrencyId: "currency-usd",
+  targetCurrencyId: "currency-eur",
+  rate: 0.85,
+  effectiveDate: new Date("2024-01-01T00:00:00.000Z"),
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies ExchangeRate<Schema>;
+
+export const baseExchangeRateEURtoUSD = {
+  id: "rate-eur-usd-1",
+  sourceCurrencyId: "currency-eur",
+  targetCurrencyId: "currency-usd",
+  rate: 1.087,
+  effectiveDate: new Date("2024-01-15T00:00:00.000Z"),
+  createdAt: new Date("2024-01-15T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies ExchangeRate<Schema>;

package/src/modules/shared/createContext.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { createContext } from "./createContext";
+
+describe("createContext", () => {
+  it("uses permissions array attribute when present", () => {
+    const ctx = createContext({
+      user: {
+        id: "user-1",
+        attributes: {
+          permissions: ["user-management:createUser", "user-management:activateUser"],
+        },
+      },
+    });
+
+    expect(ctx.actorId).toBe("user-1");
+    expect(ctx.permissions).toEqual(["user-management:createUser", "user-management:activateUser"]);
+  });
+
+  it("returns empty permissions when attributes exists but permissions is absent", () => {
+    const ctx = createContext({
+      user: {
+        id: "user-1",
+        attributes: {},
+      },
+    });
+
+    expect(ctx.actorId).toBe("user-1");
+    expect(ctx.permissions).toEqual([]);
+  });
+
+  it("returns empty permissions when attributes is null", () => {
+    const ctx = createContext({
+      user: { id: "user-1", attributes: null },
+    });
+
+    expect(ctx.actorId).toBe("user-1");
+    expect(ctx.permissions).toEqual([]);
+  });
+});

package/src/modules/shared/createContext.ts

@@ -0,0 +1,15 @@
+import type { CommandContext } from "./types";
+
+interface ResolverContext {
+  user: {
+    id: string;
+    attributes: { permissions?: string[] } | null;
+  };
+}
+
+export function createContext(context: ResolverContext): CommandContext {
+  return {
+    actorId: context.user.id,
+    permissions: [...new Set(context.user.attributes?.permissions ?? [])],
+  };
+}

package/src/modules/shared/defineCommand.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it, vi } from "vitest";
+import { defineCommand } from "./defineCommand";
+import { InsufficientPermissionError } from "./errors";
+import type { CommandContext } from "./types";
+
+describe("defineCommand", () => {
+  const ctx: CommandContext = {
+    actorId: "user-1",
+    permissions: ["mod:doThing"],
+  };
+
+  it("calls impl with db and input when permission is present", async () => {
+    const impl = vi.fn().mockResolvedValue({ result: "ok" });
+    const command = defineCommand("mod:doThing", impl);
+
+    const result = await command("fake-db", { foo: "bar" }, ctx);
+
+    expect(result).toEqual({ result: "ok" });
+    expect(impl).toHaveBeenCalledWith("fake-db", { foo: "bar" });
+  });
+
+  it("throws InsufficientPermissionError when permission is missing", async () => {
+    const impl = vi.fn();
+    const command = defineCommand("mod:doThing", impl);
+    const denied: CommandContext = { actorId: "user-1", permissions: [] };
+
+    await expect(command("fake-db", {}, denied)).rejects.toBeInstanceOf(
+      InsufficientPermissionError,
+    );
+    expect(impl).not.toHaveBeenCalled();
+  });
+
+  it("does not pass ctx to impl", async () => {
+    const impl = vi.fn().mockResolvedValue({});
+    const command = defineCommand("mod:doThing", impl);
+
+    await command("fake-db", { x: 1 }, ctx);
+
+    expect(impl).toHaveBeenCalledTimes(1);
+    expect(impl.mock.calls[0]).toHaveLength(2);
+  });
+});

package/src/modules/shared/defineCommand.ts

@@ -0,0 +1,19 @@
+import type { CommandContext } from "./types";
+import { requirePermission } from "./requirePermission";
+
+export type Command<TInput, TResult> = (
+  db: unknown,
+  input: TInput,
+  ctx: CommandContext,
+) => Promise<TResult>;
+
+export function defineCommand<TInput, TResult>(
+  permission: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  impl: (db: any, input: TInput) => Promise<TResult>,
+): Command<TInput, TResult> {
+  return async (db, input, ctx) => {
+    requirePermission(ctx, permission);
+    return impl(db, input);
+  };
+}

package/src/modules/shared/definePermissions.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it } from "vitest";
+import { definePermissions } from "./definePermissions";
+
+describe("definePermissions", () => {
+  describe("basic usage (no deps, no aliases)", () => {
+    it("creates permissions with moduleName:commandName keys", () => {
+      const result = definePermissions("primitives", [
+        "createCategory",
+        "updateCategory",
+        "deleteCategory",
+      ] as const);
+
+      expect(result.permissions.createCategory).toBe("primitives:createCategory");
+      expect(result.permissions.updateCategory).toBe("primitives:updateCategory");
+      expect(result.permissions.deleteCategory).toBe("primitives:deleteCategory");
+    });
+
+    it("sets own and all to the same values", () => {
+      const result = definePermissions("primitives", [
+        "createCategory",
+        "activateCategory",
+      ] as const);
+
+      expect(result.own).toEqual(["primitives:createCategory", "primitives:activateCategory"]);
+      expect(result.all).toEqual(result.own);
+    });
+
+    it("does not include aliases", () => {
+      const result = definePermissions("primitives", ["createCategory"] as const);
+      expect(result).not.toHaveProperty("aliases");
+    });
+  });
+
+  describe("with deps array shorthand", () => {
+    it("combines own and deps into all", () => {
+      const result = definePermissions("inventory", ["createItem", "updateItem"] as const, [
+        "primitives:createCategory",
+        "primitives:updateCategory",
+      ]);
+
+      expect(result.own).toEqual(["inventory:createItem", "inventory:updateItem"]);
+      expect(result.all).toEqual([
+        "inventory:createItem",
+        "inventory:updateItem",
+        "primitives:createCategory",
+        "primitives:updateCategory",
+      ]);
+    });
+
+    it("deduplicates when deps overlap with own", () => {
+      const result = definePermissions("inventory", ["createItem"] as const, [
+        "primitives:createCategory",
+        "inventory:createItem",
+      ]);
+
+      expect(result.all).toEqual(["inventory:createItem", "primitives:createCategory"]);
+    });
+  });
+
+  describe("with options object", () => {
+    it("supports deps without aliases", () => {
+      const result = definePermissions("inventory", ["createItem"] as const, {
+        deps: ["primitives:createCategory"],
+      });
+
+      expect(result.all).toEqual(["inventory:createItem", "primitives:createCategory"]);
+      expect(result).not.toHaveProperty("aliases");
+    });
+
+    it("supports aliases without deps", () => {
+      const result = definePermissions(
+        "primitives",
+        ["createCategory", "activateCategory", "createUnit", "activateUnit"] as const,
+        {
+          aliases: {
+            uom: ["createCategory", "activateCategory"],
+            unit: ["createUnit", "activateUnit"],
+          },
+        },
+      );
+
+      expect(result.aliases.uom).toEqual([
+        "primitives:createCategory",
+        "primitives:activateCategory",
+      ]);
+      expect(result.aliases.unit).toEqual(["primitives:createUnit", "primitives:activateUnit"]);
+    });
+
+    it("supports both deps and aliases", () => {
+      const result = definePermissions(
+        "inventory",
+        ["createItem", "updateItem", "viewItem"] as const,
+        {
+          deps: ["primitives:convertQuantity"],
+          aliases: {
+            write: ["createItem", "updateItem"],
+            read: ["viewItem"],
+          },
+        },
+      );
+
+      expect(result.all).toContain("primitives:convertQuantity");
+      expect(result.aliases.write).toEqual(["inventory:createItem", "inventory:updateItem"]);
+      expect(result.aliases.read).toEqual(["inventory:viewItem"]);
+    });
+  });
+
+  describe("diamond dependency deduplication", () => {
+    it("deduplicates shared transitive deps", () => {
+      const primitives = definePermissions("primitives", ["createCategory"] as const);
+
+      const inventory = definePermissions("inventory", ["createItem"] as const, primitives.all);
+
+      const product = definePermissions("product", ["createProduct"] as const, primitives.all);
+
+      // manufacturing depends on both inventory and product
+      const manufacturing = definePermissions("manufacturing", ["createWorkOrder"] as const, [
+        ...inventory.all,
+        ...product.all,
+      ]);
+
+      // primitives:createCategory should appear only once
+      const primitivesCount = manufacturing.all.filter(
+        (k) => k === "primitives:createCategory",
+      ).length;
+      expect(primitivesCount).toBe(1);
+
+      expect(manufacturing.all).toEqual([
+        "manufacturing:createWorkOrder",
+        "inventory:createItem",
+        "primitives:createCategory",
+        "product:createProduct",
+      ]);
+    });
+  });
+
+  describe("type inference", () => {
+    it("infers literal types for permission keys", () => {
+      const result = definePermissions("primitives", ["createCategory", "updateCategory"] as const);
+
+      // TypeScript verifies these are literal types at compile time
+      const key: "primitives:createCategory" = result.permissions.createCategory;
+      expect(key).toBe("primitives:createCategory");
+    });
+  });
+});

package/src/modules/shared/definePermissions.ts

@@ -0,0 +1,94 @@
+type PermissionKey<M extends string, C extends string> = `${M}:${C}`;
+
+type PermissionsRecord<M extends string, T extends readonly string[]> = {
+  readonly [K in T[number]]: PermissionKey<M, K>;
+};
+
+interface PermissionResultBase<M extends string, T extends readonly string[]> {
+  permissions: PermissionsRecord<M, T>;
+  own: readonly string[];
+  all: readonly string[];
+}
+
+interface PermissionResultWithAliases<
+  M extends string,
+  T extends readonly string[],
+  A extends Record<string, readonly T[number][]>,
+> extends PermissionResultBase<M, T> {
+  aliases: { readonly [K in keyof A]: readonly PermissionKey<M, T[number]>[] };
+}
+
+interface DefinePermissionsOptions<T extends readonly string[]> {
+  deps?: readonly string[];
+  aliases?: Record<string, readonly T[number][]>;
+}
+
+// Overload: no deps, no aliases
+export function definePermissions<const M extends string, const T extends readonly string[]>(
+  moduleName: M,
+  commands: T,
+): PermissionResultBase<M, T>;
+
+// Overload: deps array shorthand
+export function definePermissions<const M extends string, const T extends readonly string[]>(
+  moduleName: M,
+  commands: T,
+  deps: readonly string[],
+): PermissionResultBase<M, T>;
+
+// Overload: options object with aliases
+export function definePermissions<
+  const M extends string,
+  const T extends readonly string[],
+  const A extends Record<string, readonly T[number][]>,
+>(
+  moduleName: M,
+  commands: T,
+  options: { deps?: readonly string[]; aliases: A },
+): PermissionResultWithAliases<M, T, A>;
+
+// Overload: options object without aliases
+export function definePermissions<const M extends string, const T extends readonly string[]>(
+  moduleName: M,
+  commands: T,
+  options: { deps?: readonly string[] },
+): PermissionResultBase<M, T>;
+
+// Implementation
+export function definePermissions(
+  moduleName: string,
+  commands: readonly string[],
+  depsOrOptions?: readonly string[] | DefinePermissionsOptions<readonly string[]>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): any {
+  const isArray = Array.isArray(depsOrOptions);
+  const deps: readonly string[] = isArray
+    ? depsOrOptions
+    : ((depsOrOptions as DefinePermissionsOptions<readonly string[]> | undefined)?.deps ?? []);
+  const aliasDefs = !isArray
+    ? (depsOrOptions as DefinePermissionsOptions<readonly string[]> | undefined)?.aliases
+    : undefined;
+
+  const permissions: Record<string, string> = {};
+  const own: string[] = [];
+
+  for (const cmd of commands) {
+    const key = `${moduleName}:${cmd}`;
+    permissions[cmd] = key;
+    own.push(key);
+  }
+
+  const all = [...new Set([...own, ...deps])];
+
+  const result: Record<string, unknown> = { permissions, own, all };
+
+  if (aliasDefs) {
+    const aliases: Record<string, string[]> = {};
+    for (const [alias, cmds] of Object.entries(aliasDefs)) {
+      aliases[alias] = cmds.map((cmd) => `${moduleName}:${cmd}`);
+    }
+    result.aliases = aliases;
+  }
+
+  return result;
+}

package/src/modules/shared/entityTypes.ts

@@ -0,0 +1,15 @@
+import type { output } from "@tailor-platform/sdk";
+import type { Kysely, Selectable, Insertable, Updateable } from "kysely";
+
+export type InferSchema<T> = T extends Kysely<infer S> ? S : never;
+export type { Selectable, Insertable, Updateable };
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type, @typescript-eslint/consistent-type-definitions
+export type EmptyFields = {};
+
+// TODO: Ideally use Kysely Insertable-equivalent type from SDK instead of inferring from output<T>
+export type FieldsToInsertable<F> = {
+  [K in keyof F as null extends output<F[K]> ? never : K]: output<F[K]>;
+} & {
+  [K in keyof F as null extends output<F[K]> ? K : never]?: output<F[K]>;
+};

package/src/modules/shared/errors.ts

@@ -0,0 +1,22 @@
+export function createDomainError<
+  TName extends string,
+  TCode extends string,
+  TArgs extends unknown[],
+>(name: TName, code: TCode, messageFactory: (...args: TArgs) => string) {
+  const ErrorClass = class extends Error {
+    override name: TName = name;
+    code: TCode = code;
+    constructor(...args: TArgs) {
+      super(messageFactory(...args));
+    }
+  };
+  Object.defineProperty(ErrorClass, "name", { value: name });
+  return ErrorClass;
+}
+
+export const InsufficientPermissionError = createDomainError(
+  "InsufficientPermissionError",
+  "INSUFFICIENT_PERMISSION",
+  (actorId: string, requiredPermission: string) =>
+    `Actor ${actorId} lacks required permission: ${requiredPermission}`,
+);

package/src/modules/shared/index.ts

@@ -0,0 +1 @@
+export { createContext } from "./createContext";

package/src/modules/shared/internal.ts

@@ -0,0 +1,13 @@
+export { defineCommand, type Command } from "./defineCommand";
+export { definePermissions } from "./definePermissions";
+export { requirePermission } from "./requirePermission";
+export { createDomainError, InsufficientPermissionError } from "./errors";
+export type { CommandContext } from "./types";
+export type {
+  InferSchema,
+  Selectable,
+  Insertable,
+  Updateable,
+  FieldsToInsertable,
+  EmptyFields,
+} from "./entityTypes";

package/src/modules/shared/requirePermission.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { InsufficientPermissionError } from "./errors";
+import { requirePermission } from "./requirePermission";
+import type { CommandContext } from "./types";
+
+describe("requirePermission", () => {
+  const ctx: CommandContext = {
+    actorId: "user-1",
+    permissions: [
+      "primitives:createCategory",
+      "primitives:activateCategory",
+      "inventory:createItem",
+    ],
+  };
+
+  it("does not throw when permission is present", () => {
+    expect(() => requirePermission(ctx, "primitives:createCategory")).not.toThrow();
+    expect(() => requirePermission(ctx, "inventory:createItem")).not.toThrow();
+  });
+
+  it("throws InsufficientPermissionError when permission is missing", () => {
+    expect(() => requirePermission(ctx, "primitives:deleteCategory")).toThrow(
+      InsufficientPermissionError,
+    );
+  });
+
+  it("includes actorId and permission key in error", () => {
+    try {
+      requirePermission(ctx, "orders:createOrder");
+      expect.fail("Should have thrown");
+    } catch (err) {
+      const error = err as InstanceType<typeof InsufficientPermissionError>;
+      expect(error.name).toBe("InsufficientPermissionError");
+      expect(error.code).toBe("INSUFFICIENT_PERMISSION");
+      expect(error.message).toContain("user-1");
+      expect(error.message).toContain("orders:createOrder");
+    }
+  });
+
+  it("throws when permissions array is empty", () => {
+    const emptyCtx: CommandContext = { actorId: "user-2", permissions: [] };
+
+    expect(() => requirePermission(emptyCtx, "primitives:createCategory")).toThrow(
+      InsufficientPermissionError,
+    );
+  });
+});

package/src/modules/shared/requirePermission.ts

@@ -0,0 +1,8 @@
+import type { CommandContext } from "./types";
+import { InsufficientPermissionError } from "./errors";
+
+export function requirePermission(ctx: CommandContext, key: string): void {
+  if (!ctx.permissions.includes(key)) {
+    throw new InsufficientPermissionError(ctx.actorId, key);
+  }
+}

package/src/modules/shared/types.ts

@@ -0,0 +1,4 @@
+export interface CommandContext {
+  actorId: string;
+  permissions: readonly string[];
+}