@tailor-platform/erp-kit 0.0.1 → 0.1.0

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

@@ -0,0 +1,198 @@
+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 {
+  InvalidEmailError,
+  MissingRequiredFieldError,
+  UserAlreadyExistsError,
+} from "../lib/errors";
+import { activeUser, baseAuditEvent, pendingUser } from "../testing/fixtures";
+import { makeCreateUser } from "./createUser";
+
+const createUser = makeCreateUser();
+
+describe("createUser", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["user-management:createUser"],
+  };
+
+  // Error cases
+  it("throws when email is empty", async () => {
+    const { db } = createMockDb<DB>();
+
+    await expect(
+      createUser(db, { email: "", name: "Test User", actorId: "actor-1" }, ctx),
+    ).rejects.toBeInstanceOf(MissingRequiredFieldError);
+  });
+
+  it("throws when name is empty", async () => {
+    const { db } = createMockDb<DB>();
+
+    await expect(
+      createUser(db, { email: "test@example.com", name: "", actorId: "actor-1" }, ctx),
+    ).rejects.toBeInstanceOf(MissingRequiredFieldError);
+  });
+
+  it("throws when name is whitespace only", async () => {
+    const { db } = createMockDb<DB>();
+
+    await expect(
+      createUser(db, { email: "test@example.com", name: "   ", actorId: "actor-1" }, ctx),
+    ).rejects.toBeInstanceOf(MissingRequiredFieldError);
+  });
+
+  it("throws when email format is invalid (no @)", async () => {
+    const { db } = createMockDb<DB>();
+
+    await expect(
+      createUser(db, { email: "invalidemail", name: "Test User", actorId: "actor-1" }, ctx),
+    ).rejects.toBeInstanceOf(InvalidEmailError);
+  });
+
+  it("throws when email format is invalid (no domain)", async () => {
+    const { db } = createMockDb<DB>();
+
+    await expect(
+      createUser(db, { email: "test@", name: "Test User", actorId: "actor-1" }, ctx),
+    ).rejects.toBeInstanceOf(InvalidEmailError);
+  });
+
+  it("throws when email already exists", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(activeUser);
+
+    await expect(
+      createUser(db, { email: activeUser.email, name: "New User", actorId: "actor-1" }, ctx),
+    ).rejects.toBeInstanceOf(UserAlreadyExistsError);
+  });
+
+  // Success cases
+  it("creates user with PENDING status", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const createdUser = {
+      ...pendingUser,
+      id: "new-user-id",
+      email: "new@example.com",
+      name: "New User",
+    };
+    const createdAuditEvent = {
+      ...baseAuditEvent,
+      id: "new-event-id",
+      eventType: "USER_CREATED" as const,
+      actorId: "actor-1",
+      targetId: "new-user-id",
+      targetType: "User",
+    };
+
+    spies.select.mockReturnValue(undefined); // No existing user
+    spies.insert.mockReturnValueOnce(createdUser).mockReturnValueOnce(createdAuditEvent);
+
+    const result = await createUser(
+      db,
+      {
+        email: "new@example.com",
+        name: "New User",
+        actorId: "actor-1",
+      },
+      ctx,
+    );
+
+    expect(result.user.email).toBe("new@example.com");
+    expect(result.user.name).toBe("New User");
+    expect(result.user.status).toBe("PENDING");
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("logs USER_CREATED audit event", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const createdUser = {
+      ...pendingUser,
+      id: "new-user-id",
+    };
+    const createdAuditEvent = {
+      ...baseAuditEvent,
+      eventType: "USER_CREATED" as const,
+      actorId: "actor-1",
+      targetId: "new-user-id",
+    };
+
+    spies.select.mockReturnValue(undefined);
+    spies.insert.mockReturnValueOnce(createdUser).mockReturnValueOnce(createdAuditEvent);
+
+    const result = await createUser(
+      db,
+      {
+        email: "test@example.com",
+        name: "Test User",
+        actorId: "actor-1",
+      },
+      ctx,
+    );
+
+    expect(result.auditEvent.eventType).toBe("USER_CREATED");
+    expect(result.auditEvent.actorId).toBe("actor-1");
+    expect(result.auditEvent.targetId).toBe(createdUser.id);
+  });
+
+  it("throws when permission is missing", async () => {
+    const { db } = createMockDb<DB>();
+    const denied: CommandContext = { actorId: "test-actor", permissions: [] };
+    await expect(
+      createUser(db, { email: "test@example.com", name: "Test User", actorId: "actor-1" }, denied),
+    ).rejects.toBeInstanceOf(InsufficientPermissionError);
+  });
+
+  it("passes custom fields through to insert", async () => {
+    const createUserWithFields = makeCreateUser<{ department: string }>();
+    const { db, spies } = createMockDb<DB>();
+    const createdUser = {
+      ...pendingUser,
+      id: "new-user-id",
+      email: "new@example.com",
+      name: "New User",
+      department: "Engineering",
+    };
+    const createdAuditEvent = {
+      ...baseAuditEvent,
+      id: "new-event-id",
+      eventType: "USER_CREATED" as const,
+      actorId: "actor-1",
+      targetId: "new-user-id",
+      targetType: "User",
+    };
+
+    spies.select.mockReturnValue(undefined);
+    spies.insert.mockReturnValueOnce(createdUser).mockReturnValueOnce(createdAuditEvent);
+
+    const result = await createUserWithFields(
+      db,
+      {
+        email: "new@example.com",
+        name: "New User",
+        actorId: "actor-1",
+        department: "Engineering",
+      },
+      ctx,
+    );
+
+    expect(result.user.id).toBe("new-user-id");
+    expect(spies.insert).toHaveBeenCalledTimes(2);
+
+    // User insert includes custom field
+    expect(spies.values).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ department: "Engineering" }),
+    );
+
+    // Audit event payload includes custom field
+    expect(spies.values).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        payload: expect.stringContaining('"department":"Engineering"'),
+      }),
+    );
+  });
+});

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

@@ -0,0 +1,85 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import {
+  InvalidEmailError,
+  MissingRequiredFieldError,
+  UserAlreadyExistsError,
+} from "../lib/errors";
+import { permissions } from "../permissions";
+
+interface CreateUserInput {
+  email: string;
+  name: string;
+  actorId: string;
+}
+
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/**
+ * Function: createUser
+ *
+ * Creates a new user account in PENDING status.
+ * Validates email format and uniqueness, and logs a USER_CREATED audit event.
+ */
+export function makeCreateUser<CF extends Record<string, unknown>>() {
+  return defineCommand(permissions.createUser, async (db: DB, input: CreateUserInput & CF) => {
+    const { email, name, actorId, ...customFields } = input;
+
+    // 1. Validate email is provided
+    if (!email || email.trim() === "") {
+      throw new MissingRequiredFieldError("email");
+    }
+
+    // 2. Validate name is provided
+    if (!name || name.trim() === "") {
+      throw new MissingRequiredFieldError("name");
+    }
+
+    // 3. Validate email format
+    if (!EMAIL_PATTERN.test(email)) {
+      throw new InvalidEmailError(email);
+    }
+
+    // 4. Check if email already exists
+    const existingUser = await db
+      .selectFrom("User")
+      .selectAll()
+      .where("email", "=", email)
+      .executeTakeFirst();
+
+    if (existingUser) {
+      throw new UserAlreadyExistsError(email);
+    }
+
+    // 5. Create user with PENDING status
+    const user = await db
+      .insertInto("User")
+      .values({
+        ...(customFields as Record<string, unknown>),
+        email,
+        name,
+        status: "PENDING",
+        createdAt: new Date(),
+        updatedAt: null,
+      })
+      .returningAll()
+      .executeTakeFirst();
+
+    // 6. Log USER_CREATED audit event
+    const auditEvent = await db
+      .insertInto("AuditEvent")
+      .values({
+        eventType: "USER_CREATED",
+        actorId,
+        targetId: user!.id,
+        targetType: "User",
+        payload: JSON.stringify({ email, name, ...customFields }),
+        createdAt: new Date(),
+        updatedAt: null,
+      })
+      .returningAll()
+      .executeTakeFirst();
+
+    return { user: user!, auditEvent: auditEvent! };
+  });
+}

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

@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb, testNotFound, testPermissionDenied } from "../../testing/index";
+import { type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { InvalidStatusTransitionError, UserNotFoundError } from "../lib/errors";
+import { activeUser, baseAuditEvent, inactiveUser, pendingUser } from "../testing/fixtures";
+import { deactivateUser } from "./deactivateUser";
+
+describe("deactivateUser", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["user-management:deactivateUser"],
+  };
+
+  it(
+    "throws when user does not exist",
+    testNotFound(
+      deactivateUser,
+      { userId: "nonexistent-user", actorId: "actor-1" },
+      ctx,
+      UserNotFoundError,
+    ),
+  );
+
+  it("throws when user is PENDING", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(pendingUser);
+
+    await expect(
+      deactivateUser(db, { userId: pendingUser.id, actorId: "actor-1" }, ctx),
+    ).rejects.toBeInstanceOf(InvalidStatusTransitionError);
+  });
+
+  it("throws when user is already INACTIVE", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(inactiveUser);
+
+    await expect(
+      deactivateUser(db, { userId: inactiveUser.id, actorId: "actor-1" }, ctx),
+    ).rejects.toBeInstanceOf(InvalidStatusTransitionError);
+  });
+
+  // Success cases
+  it("deactivates ACTIVE user to INACTIVE", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const deactivatedUser = {
+      ...activeUser,
+      status: "INACTIVE" as const,
+      updatedAt: new Date("2024-01-15T00:00:00.000Z"),
+    };
+    const createdAuditEvent = {
+      ...baseAuditEvent,
+      eventType: "USER_DEACTIVATED" as const,
+      actorId: "actor-1",
+      targetId: activeUser.id,
+    };
+
+    spies.select.mockReturnValue(activeUser);
+    spies.update.mockReturnValue(deactivatedUser);
+    spies.insert.mockReturnValue(createdAuditEvent);
+
+    const result = await deactivateUser(
+      db,
+      {
+        userId: activeUser.id,
+        actorId: "actor-1",
+      },
+      ctx,
+    );
+
+    expect(result.user.status).toBe("INACTIVE");
+    expect(result.user.updatedAt).not.toBeNull();
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("logs USER_DEACTIVATED audit event", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const deactivatedUser = {
+      ...activeUser,
+      status: "INACTIVE" as const,
+      updatedAt: new Date("2024-01-15T00:00:00.000Z"),
+    };
+    const createdAuditEvent = {
+      ...baseAuditEvent,
+      eventType: "USER_DEACTIVATED" as const,
+      actorId: "actor-1",
+      targetId: activeUser.id,
+    };
+
+    spies.select.mockReturnValue(activeUser);
+    spies.update.mockReturnValue(deactivatedUser);
+    spies.insert.mockReturnValue(createdAuditEvent);
+
+    const result = await deactivateUser(
+      db,
+      {
+        userId: activeUser.id,
+        actorId: "actor-1",
+      },
+      ctx,
+    );
+
+    expect(result.auditEvent.eventType).toBe("USER_DEACTIVATED");
+    expect(result.auditEvent.actorId).toBe("actor-1");
+    expect(result.auditEvent.targetId).toBe(activeUser.id);
+  });
+
+  it(
+    "throws when permission is missing",
+    testPermissionDenied(deactivateUser, { userId: "some-user", actorId: "actor-1" }),
+  );
+});

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

@@ -0,0 +1,67 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { InvalidStatusTransitionError, UserNotFoundError } from "../lib/errors";
+import { permissions } from "../permissions";
+
+export interface DeactivateUserInput {
+  userId: string;
+  actorId: string;
+  from?: string[];
+}
+
+/**
+ * Function: deactivateUser
+ *
+ * Transitions a user from ACTIVE to INACTIVE status.
+ * Role assignments are preserved for audit purposes.
+ */
+export const deactivateUser = defineCommand(
+  permissions.deactivateUser,
+  async (db: DB, input: DeactivateUserInput) => {
+    // 1. Find user by ID
+    const user = await db
+      .selectFrom("User")
+      .selectAll()
+      .where("id", "=", input.userId)
+      .executeTakeFirst();
+
+    // 2. If not found, throw error
+    if (!user) {
+      throw new UserNotFoundError(input.userId);
+    }
+
+    // 3. Validate status transition
+    const validFromStatuses = input.from ?? ["ACTIVE"];
+    if (!validFromStatuses.includes(user.status)) {
+      throw new InvalidStatusTransitionError(user.status, "INACTIVE");
+    }
+
+    // 4. Update status to INACTIVE
+    const updatedUser = await db
+      .updateTable("User")
+      .set({
+        status: "INACTIVE",
+        updatedAt: new Date(),
+      })
+      .where("id", "=", input.userId)
+      .returningAll()
+      .executeTakeFirst();
+
+    // 5. Log USER_DEACTIVATED audit event
+    const auditEvent = await db
+      .insertInto("AuditEvent")
+      .values({
+        eventType: "USER_DEACTIVATED",
+        actorId: input.actorId,
+        targetId: input.userId,
+        targetType: "User",
+        payload: JSON.stringify({ previousStatus: user.status }),
+        createdAt: new Date(),
+        updatedAt: null,
+      })
+      .returningAll()
+      .executeTakeFirst();
+
+    return { user: updatedUser!, auditEvent: auditEvent! };
+  },
+);

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

@@ -0,0 +1,179 @@
+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 { InvalidEventTypeError, MissingRequiredFieldError } from "../lib/errors";
+import { baseAuditEvent } from "../testing/fixtures";
+import { logAuditEvent } from "./logAuditEvent";
+
+describe("logAuditEvent", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["user-management:logAuditEvent"],
+  };
+
+  it("throws when actorId is empty", async () => {
+    const { db } = createMockDb<DB>();
+
+    await expect(
+      logAuditEvent(
+        db,
+        {
+          eventType: "USER_CREATED",
+          actorId: "",
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(MissingRequiredFieldError);
+  });
+
+  it("throws when eventType is invalid", async () => {
+    const { db } = createMockDb<DB>();
+
+    await expect(
+      logAuditEvent(
+        db,
+        {
+          eventType: "INVALID_EVENT" as "USER_CREATED",
+          actorId: "user-1",
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(InvalidEventTypeError);
+  });
+
+  it("creates audit event with minimal fields", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const createdEvent = {
+      ...baseAuditEvent,
+      id: "new-event-id",
+      eventType: "USER_CREATED" as const,
+      actorId: "user-1",
+      targetId: null,
+      targetType: null,
+      payload: null,
+    };
+
+    spies.insert.mockReturnValue(createdEvent);
+
+    const result = await logAuditEvent(
+      db,
+      {
+        eventType: "USER_CREATED",
+        actorId: "user-1",
+      },
+      ctx,
+    );
+
+    expect(result.auditEvent.eventType).toBe("USER_CREATED");
+    expect(result.auditEvent.actorId).toBe("user-1");
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("creates audit event with target info", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const createdEvent = {
+      ...baseAuditEvent,
+      id: "new-event-id",
+      eventType: "ROLE_ASSIGNED" as const,
+      actorId: "user-1",
+      targetId: "user-2",
+      targetType: "User",
+      payload: null,
+    };
+
+    spies.insert.mockReturnValue(createdEvent);
+
+    const result = await logAuditEvent(
+      db,
+      {
+        eventType: "ROLE_ASSIGNED",
+        actorId: "user-1",
+        targetId: "user-2",
+        targetType: "User",
+      },
+      ctx,
+    );
+
+    expect(result.auditEvent.eventType).toBe("ROLE_ASSIGNED");
+    expect(result.auditEvent.targetId).toBe("user-2");
+    expect(result.auditEvent.targetType).toBe("User");
+  });
+
+  it("creates audit event with payload", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const payload = JSON.stringify({ roleId: "role-1", userId: "user-2" });
+    const createdEvent = {
+      ...baseAuditEvent,
+      id: "new-event-id",
+      eventType: "ROLE_ASSIGNED" as const,
+      actorId: "user-1",
+      targetId: "user-2",
+      targetType: "User",
+      payload,
+    };
+
+    spies.insert.mockReturnValue(createdEvent);
+
+    const result = await logAuditEvent(
+      db,
+      {
+        eventType: "ROLE_ASSIGNED",
+        actorId: "user-1",
+        targetId: "user-2",
+        targetType: "User",
+        payload,
+      },
+      ctx,
+    );
+
+    expect(result.auditEvent.payload).toBe(payload);
+  });
+
+  it("creates audit event for each valid event type", async () => {
+    const eventTypes = [
+      "USER_CREATED",
+      "USER_ACTIVATED",
+      "USER_DEACTIVATED",
+      "USER_REACTIVATED",
+      "ROLE_ASSIGNED",
+      "ROLE_REVOKED",
+      "PERMISSION_ASSIGNED",
+      "PERMISSION_REVOKED",
+    ] as const;
+
+    for (const eventType of eventTypes) {
+      const { db, spies } = createMockDb<DB>();
+      const createdEvent = {
+        ...baseAuditEvent,
+        id: "new-event-id",
+        eventType,
+        actorId: "user-1",
+        targetId: null,
+        targetType: null,
+        payload: null,
+      };
+
+      spies.insert.mockReturnValue(createdEvent);
+
+      const result = await logAuditEvent(
+        db,
+        {
+          eventType,
+          actorId: "user-1",
+        },
+        ctx,
+      );
+
+      expect(result.auditEvent.eventType).toBe(eventType);
+    }
+  });
+
+  it("throws when permission is missing", async () => {
+    const { db } = createMockDb<DB>();
+    const denied: CommandContext = { actorId: "test-actor", permissions: [] };
+    await expect(
+      logAuditEvent(db, { eventType: "USER_CREATED", actorId: "user-1" }, denied),
+    ).rejects.toBeInstanceOf(InsufficientPermissionError);
+  });
+});

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

@@ -0,0 +1,59 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { AuditEventEventType } from "../generated/enums";
+import { InvalidEventTypeError, MissingRequiredFieldError } from "../lib/errors";
+import { permissions } from "../permissions";
+
+export interface LogAuditEventInput {
+  eventType: AuditEventEventType;
+  actorId: string;
+  targetId?: string;
+  targetType?: string;
+  payload?: string;
+}
+
+const VALID_EVENT_TYPES = new Set<string>([
+  "USER_CREATED",
+  "USER_ACTIVATED",
+  "USER_DEACTIVATED",
+  "USER_REACTIVATED",
+  "ROLE_ASSIGNED",
+  "ROLE_REVOKED",
+  "PERMISSION_ASSIGNED",
+  "PERMISSION_REVOKED",
+]);
+
+/**
+ * Function: logAuditEvent
+ *
+ * Creates an immutable audit record of a security-relevant event.
+ * Records are created with timestamp and cannot be modified or deleted.
+ */
+export const logAuditEvent = defineCommand(
+  permissions.logAuditEvent,
+  async (db: DB, input: LogAuditEventInput) => {
+    if (!input.actorId || input.actorId.trim() === "") {
+      throw new MissingRequiredFieldError("actorId");
+    }
+
+    if (!VALID_EVENT_TYPES.has(input.eventType)) {
+      throw new InvalidEventTypeError(input.eventType);
+    }
+
+    const auditEvent = await db
+      .insertInto("AuditEvent")
+      .values({
+        eventType: input.eventType,
+        actorId: input.actorId,
+        targetId: input.targetId ?? null,
+        targetType: input.targetType ?? null,
+        payload: input.payload ?? null,
+        createdAt: new Date(),
+        updatedAt: null,
+      })
+      .returningAll()
+      .executeTakeFirst();
+
+    return { auditEvent: auditEvent! };
+  },
+);