@tailor-platform/erp-kit 0.0.1 → 0.1.0

package/src/modules/user-management/command/assignRoleToUser.test.ts

@@ -0,0 +1,162 @@
+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 { RoleNotFoundError, UserNotActiveError, UserNotFoundError } from "../lib/errors";
+import {
+  activeUser,
+  baseAuditEvent,
+  baseRole,
+  baseUserRole,
+  inactiveUser,
+  pendingUser,
+} from "../testing/fixtures";
+import { assignRoleToUser } from "./assignRoleToUser";
+
+describe("assignRoleToUser", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["user-management:assignRoleToUser"],
+  };
+
+  it("throws when user does not exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(undefined);
+
+    await expect(
+      assignRoleToUser(
+        db,
+        {
+          userId: "nonexistent-user",
+          roleId: baseRole.id,
+          actorId: "actor-1",
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(UserNotFoundError);
+  });
+
+  it("throws when role does not exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(activeUser).mockReturnValueOnce(undefined);
+
+    await expect(
+      assignRoleToUser(
+        db,
+        {
+          userId: activeUser.id,
+          roleId: "nonexistent-role",
+          actorId: "actor-1",
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(RoleNotFoundError);
+  });
+
+  it("throws when user is PENDING", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(pendingUser).mockReturnValueOnce(baseRole);
+
+    await expect(
+      assignRoleToUser(
+        db,
+        {
+          userId: pendingUser.id,
+          roleId: baseRole.id,
+          actorId: "actor-1",
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(UserNotActiveError);
+  });
+
+  it("throws when user is INACTIVE", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(inactiveUser).mockReturnValueOnce(baseRole);
+
+    await expect(
+      assignRoleToUser(
+        db,
+        {
+          userId: inactiveUser.id,
+          roleId: baseRole.id,
+          actorId: "actor-1",
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(UserNotActiveError);
+  });
+
+  it("returns success when assignment already exists (idempotent)", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const updatedUser = { ...activeUser, permissions: ["orders:read"] };
+    spies.select
+      .mockReturnValueOnce(activeUser)
+      .mockReturnValueOnce(baseRole)
+      .mockReturnValueOnce(baseUserRole) // Assignment exists
+      .mockReturnValueOnce([{ key: "orders:read" }]); // Permission keys from recompute
+    spies.update.mockReturnValueOnce(updatedUser);
+
+    const result = await assignRoleToUser(
+      db,
+      {
+        userId: activeUser.id,
+        roleId: baseRole.id,
+        actorId: "actor-1",
+      },
+      ctx,
+    );
+
+    expect(result.userRole).toEqual(baseUserRole);
+    expect(result.user.permissions).toEqual(["orders:read"]);
+    expect(spies.insert).not.toHaveBeenCalled();
+  });
+
+  it("creates UserRole and logs ROLE_ASSIGNED event", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const newUserRole = {
+      ...baseUserRole,
+      id: "new-user-role-id",
+    };
+    const createdAuditEvent = {
+      ...baseAuditEvent,
+      eventType: "ROLE_ASSIGNED" as const,
+      actorId: "actor-1",
+      targetId: activeUser.id,
+      targetType: "User",
+    };
+    const updatedUser = { ...activeUser, permissions: ["orders:read"] };
+
+    spies.select
+      .mockReturnValueOnce(activeUser)
+      .mockReturnValueOnce(baseRole)
+      .mockReturnValueOnce(undefined) // No existing assignment
+      .mockReturnValueOnce([{ key: "orders:read" }]); // Permission keys from recompute
+    spies.insert.mockReturnValueOnce(newUserRole).mockReturnValueOnce(createdAuditEvent);
+    spies.update.mockReturnValueOnce(updatedUser);
+
+    const result = await assignRoleToUser(
+      db,
+      {
+        userId: activeUser.id,
+        roleId: baseRole.id,
+        actorId: "actor-1",
+      },
+      ctx,
+    );
+
+    expect(result.userRole.userId).toBe(activeUser.id);
+    expect(result.userRole.roleId).toBe(baseRole.id);
+    expect(result.auditEvent?.eventType).toBe("ROLE_ASSIGNED");
+    expect(result.user.permissions).toEqual(["orders:read"]);
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("throws when permission is missing", async () => {
+    const { db } = createMockDb<DB>();
+    const denied: CommandContext = { actorId: "test-actor", permissions: [] };
+    await expect(
+      assignRoleToUser(db, { userId: "user-1", roleId: "role-1", actorId: "actor-1" }, denied),
+    ).rejects.toBeInstanceOf(InsufficientPermissionError);
+  });
+});

package/src/modules/user-management/command/assignRoleToUser.ts

@@ -0,0 +1,93 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { RoleNotFoundError, UserNotActiveError, UserNotFoundError } from "../lib/errors";
+import { recomputeUserPermissions } from "../lib/recomputeUserPermissions";
+import { permissions } from "../permissions";
+
+export interface AssignRoleToUserInput {
+  userId: string;
+  roleId: string;
+  actorId: string;
+}
+
+/**
+ * Function: assignRoleToUser
+ *
+ * Assigns a role to a user. Only ACTIVE users can receive role assignments.
+ * Operation is idempotent - assigning the same role twice does not create
+ * duplicate records or error.
+ */
+export const assignRoleToUser = defineCommand(
+  permissions.assignRoleToUser,
+  async (db: DB, input: AssignRoleToUserInput) => {
+    const user = await db
+      .selectFrom("User")
+      .selectAll()
+      .where("id", "=", input.userId)
+      .executeTakeFirst();
+
+    if (!user) {
+      throw new UserNotFoundError(input.userId);
+    }
+
+    const role = await db
+      .selectFrom("Role")
+      .selectAll()
+      .where("id", "=", input.roleId)
+      .executeTakeFirst();
+
+    if (!role) {
+      throw new RoleNotFoundError(input.roleId);
+    }
+
+    if (user.status !== "ACTIVE") {
+      throw new UserNotActiveError(input.userId, user.status);
+    }
+
+    // Idempotent: return existing assignment, recompute permissions for consistency
+    const existingAssignment = await db
+      .selectFrom("UserRole")
+      .selectAll()
+      .where("userId", "=", input.userId)
+      .where("roleId", "=", input.roleId)
+      .executeTakeFirst();
+
+    if (existingAssignment) {
+      const updatedUser = await recomputeUserPermissions(db, input.userId);
+      return { userRole: existingAssignment, user: updatedUser };
+    }
+
+    const userRole = await db
+      .insertInto("UserRole")
+      .values({
+        userId: input.userId,
+        roleId: input.roleId,
+        createdAt: new Date(),
+        updatedAt: null,
+      })
+      .returningAll()
+      .executeTakeFirst();
+
+    const auditEvent = await db
+      .insertInto("AuditEvent")
+      .values({
+        eventType: "ROLE_ASSIGNED",
+        actorId: input.actorId,
+        targetId: input.userId,
+        targetType: "User",
+        payload: JSON.stringify({
+          userId: input.userId,
+          roleId: input.roleId,
+          roleName: role.name,
+        }),
+        createdAt: new Date(),
+        updatedAt: null,
+      })
+      .returningAll()
+      .executeTakeFirst();
+
+    const updatedUser = await recomputeUserPermissions(db, input.userId);
+
+    return { userRole: userRole!, user: updatedUser, auditEvent: auditEvent! };
+  },
+);

package/src/modules/user-management/command/createPermission.test.ts

@@ -0,0 +1,143 @@
+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 {
+  DuplicatePermissionKeyError,
+  InvalidPermissionKeyFormatError,
+  MissingRequiredFieldError,
+} from "../lib/errors";
+import { basePermission } from "../testing/fixtures";
+import { makeCreatePermission } from "./createPermission";
+
+const createPermission = makeCreatePermission();
+
+describe("createPermission", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["user-management:createPermission"],
+  };
+
+  // Error cases
+  it("throws when key is empty", async () => {
+    const { db } = createMockDb<DB>();
+
+    await expect(createPermission(db, { key: "" }, ctx)).rejects.toBeInstanceOf(
+      MissingRequiredFieldError,
+    );
+  });
+
+  it("throws when key format is invalid (no colon)", async () => {
+    const { db } = createMockDb<DB>();
+
+    await expect(createPermission(db, { key: "invalidkey" }, ctx)).rejects.toBeInstanceOf(
+      InvalidPermissionKeyFormatError,
+    );
+  });
+
+  it("throws when key format is invalid (multiple colons)", async () => {
+    const { db } = createMockDb<DB>();
+
+    await expect(
+      createPermission(db, { key: "resource:action:extra" }, ctx),
+    ).rejects.toBeInstanceOf(InvalidPermissionKeyFormatError);
+  });
+
+  it("throws when key format is invalid (empty resource)", async () => {
+    const { db } = createMockDb<DB>();
+
+    await expect(createPermission(db, { key: ":action" }, ctx)).rejects.toBeInstanceOf(
+      InvalidPermissionKeyFormatError,
+    );
+  });
+
+  it("throws when key format is invalid (empty action)", async () => {
+    const { db } = createMockDb<DB>();
+
+    await expect(createPermission(db, { key: "resource:" }, ctx)).rejects.toBeInstanceOf(
+      InvalidPermissionKeyFormatError,
+    );
+  });
+
+  it("throws when permission key already exists", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(basePermission);
+
+    await expect(createPermission(db, { key: basePermission.key }, ctx)).rejects.toBeInstanceOf(
+      DuplicatePermissionKeyError,
+    );
+  });
+
+  // Success cases
+  it("creates permission with valid key", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const createdPermission = {
+      ...basePermission,
+      id: "new-permission-id",
+      key: "users:read",
+      description: null,
+    };
+
+    spies.select.mockReturnValue(undefined); // No existing permission
+    spies.insert.mockReturnValue(createdPermission);
+
+    const result = await createPermission(db, { key: "users:read" }, ctx);
+
+    expect(result.permission.key).toBe("users:read");
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("creates permission with description", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const createdPermission = {
+      ...basePermission,
+      id: "new-permission-id",
+      key: "users:write",
+      description: "Permission to write users",
+    };
+
+    spies.select.mockReturnValue(undefined);
+    spies.insert.mockReturnValue(createdPermission);
+
+    const result = await createPermission(
+      db,
+      {
+        key: "users:write",
+        description: "Permission to write users",
+      },
+      ctx,
+    );
+
+    expect(result.permission.key).toBe("users:write");
+    expect(result.permission.description).toBe("Permission to write users");
+  });
+
+  it("throws when permission is missing", async () => {
+    const { db } = createMockDb<DB>();
+    const denied: CommandContext = { actorId: "test-actor", permissions: [] };
+    await expect(createPermission(db, { key: "users:read" }, denied)).rejects.toBeInstanceOf(
+      InsufficientPermissionError,
+    );
+  });
+
+  it("passes custom fields through to insert", async () => {
+    const createPermissionWithFields = makeCreatePermission<{ module: string }>();
+    const { db, spies } = createMockDb<DB>();
+    const createdPermission = {
+      ...basePermission,
+      id: "new-permission-id",
+      key: "users:read",
+      module: "user-management",
+    };
+
+    spies.select.mockReturnValue(undefined);
+    spies.insert.mockReturnValue(createdPermission);
+
+    await createPermissionWithFields(db, { key: "users:read", module: "user-management" }, ctx);
+
+    expect(spies.values).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ module: "user-management" }),
+    );
+  });
+});

package/src/modules/user-management/command/createPermission.ts

@@ -0,0 +1,66 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import {
+  DuplicatePermissionKeyError,
+  InvalidPermissionKeyFormatError,
+  MissingRequiredFieldError,
+} from "../lib/errors";
+import { permissions } from "../permissions";
+
+interface CreatePermissionInput {
+  key: string;
+  description?: string;
+}
+
+const PERMISSION_KEY_PATTERN = /^[a-zA-Z0-9_-]+:[a-zA-Z0-9_-]+$/;
+
+/**
+ * Function: createPermission
+ *
+ * Creates a new permission with the specified key in resource:action format.
+ * Validates that the key follows the correct format and is unique.
+ */
+export function makeCreatePermission<CF extends Record<string, unknown>>() {
+  return defineCommand(
+    permissions.createPermission,
+    async (db: DB, input: CreatePermissionInput & CF) => {
+      const { key, description, ...customFields } = input;
+
+      // 1. Validate key is provided
+      if (!key || key.trim() === "") {
+        throw new MissingRequiredFieldError("key");
+      }
+
+      // 2. Validate key format (resource:action)
+      if (!PERMISSION_KEY_PATTERN.test(key)) {
+        throw new InvalidPermissionKeyFormatError(key);
+      }
+
+      // 3. Check if permission key already exists
+      const existingPermission = await db
+        .selectFrom("Permission")
+        .selectAll()
+        .where("key", "=", key)
+        .executeTakeFirst();
+
+      if (existingPermission) {
+        throw new DuplicatePermissionKeyError(key);
+      }
+
+      // 4. Create permission
+      const permission = await db
+        .insertInto("Permission")
+        .values({
+          ...(customFields as Record<string, unknown>),
+          key,
+          description: description ?? null,
+          createdAt: new Date(),
+          updatedAt: null,
+        })
+        .returningAll()
+        .executeTakeFirst();
+
+      return { permission: permission! };
+    },
+  );
+}

package/src/modules/user-management/command/createRole.test.ts

@@ -0,0 +1,115 @@
+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 { DuplicateRoleNameError, MissingRequiredFieldError } from "../lib/errors";
+import { baseRole } from "../testing/fixtures";
+import { makeCreateRole } from "./createRole";
+
+const createRole = makeCreateRole();
+
+describe("createRole", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["user-management:createRole"],
+  };
+
+  // Error cases
+  it("throws when name is empty", async () => {
+    const { db } = createMockDb<DB>();
+
+    await expect(createRole(db, { name: "" }, ctx)).rejects.toBeInstanceOf(
+      MissingRequiredFieldError,
+    );
+  });
+
+  it("throws when name is whitespace only", async () => {
+    const { db } = createMockDb<DB>();
+
+    await expect(createRole(db, { name: "   " }, ctx)).rejects.toBeInstanceOf(
+      MissingRequiredFieldError,
+    );
+  });
+
+  it("throws when role name already exists", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(baseRole);
+
+    await expect(createRole(db, { name: baseRole.name }, ctx)).rejects.toBeInstanceOf(
+      DuplicateRoleNameError,
+    );
+  });
+
+  // Success cases
+  it("creates role with valid name", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const createdRole = {
+      ...baseRole,
+      id: "new-role-id",
+      name: "Viewer",
+      description: null,
+    };
+
+    spies.select.mockReturnValue(undefined); // No existing role
+    spies.insert.mockReturnValue(createdRole);
+
+    const result = await createRole(db, { name: "Viewer" }, ctx);
+
+    expect(result.role.name).toBe("Viewer");
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("creates role with description", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const createdRole = {
+      ...baseRole,
+      id: "new-role-id",
+      name: "Editor",
+      description: "Can edit content",
+    };
+
+    spies.select.mockReturnValue(undefined);
+    spies.insert.mockReturnValue(createdRole);
+
+    const result = await createRole(
+      db,
+      {
+        name: "Editor",
+        description: "Can edit content",
+      },
+      ctx,
+    );
+
+    expect(result.role.name).toBe("Editor");
+    expect(result.role.description).toBe("Can edit content");
+  });
+
+  it("throws when permission is missing", async () => {
+    const { db } = createMockDb<DB>();
+    const denied: CommandContext = { actorId: "test-actor", permissions: [] };
+    await expect(createRole(db, { name: "Test" }, denied)).rejects.toBeInstanceOf(
+      InsufficientPermissionError,
+    );
+  });
+
+  it("passes custom fields through to insert", async () => {
+    const createRoleWithFields = makeCreateRole<{ department: string }>();
+    const { db, spies } = createMockDb<DB>();
+    const createdRole = {
+      ...baseRole,
+      id: "new-role-id",
+      name: "Viewer",
+      department: "Engineering",
+    };
+
+    spies.select.mockReturnValue(undefined);
+    spies.insert.mockReturnValue(createdRole);
+
+    await createRoleWithFields(db, { name: "Viewer", department: "Engineering" }, ctx);
+
+    expect(spies.values).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ department: "Engineering" }),
+    );
+  });
+});

package/src/modules/user-management/command/createRole.ts

@@ -0,0 +1,52 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { DuplicateRoleNameError, MissingRequiredFieldError } from "../lib/errors";
+import { permissions } from "../permissions";
+
+interface CreateRoleInput {
+  name: string;
+  description?: string;
+}
+
+/**
+ * Function: createRole
+ *
+ * Creates a new role with the specified name.
+ * Validates that the name is unique within the system.
+ */
+export function makeCreateRole<CF extends Record<string, unknown>>() {
+  return defineCommand(permissions.createRole, async (db: DB, input: CreateRoleInput & CF) => {
+    const { name, description, ...customFields } = input;
+
+    // 1. Validate name is provided
+    if (!name || name.trim() === "") {
+      throw new MissingRequiredFieldError("name");
+    }
+
+    // 2. Check if role name already exists
+    const existingRole = await db
+      .selectFrom("Role")
+      .selectAll()
+      .where("name", "=", name)
+      .executeTakeFirst();
+
+    if (existingRole) {
+      throw new DuplicateRoleNameError(name);
+    }
+
+    // 3. Create role
+    const role = await db
+      .insertInto("Role")
+      .values({
+        ...(customFields as Record<string, unknown>),
+        name,
+        description: description ?? null,
+        createdAt: new Date(),
+        updatedAt: null,
+      })
+      .returningAll()
+      .executeTakeFirst();
+
+    return { role: role! };
+  });
+}