fix: resolve type errors across test suite

tests/unit/controllers/CompanyController.test.ts

@@ -0,0 +1,188 @@
+import { describe, test, expect } from "bun:test";
+import { CompanyController } from "../../../src/controllers/CompanyController";
+import { buildMockCompany } from "../../setup";
+
+const mockCwData = {
+  company: {
+    addressLine1: "123 Main St",
+    addressLine2: null,
+    city: "Springfield",
+    state: "IL",
+    zip: "62701",
+    country: { name: "United States" },
+    _info: { contacts_href: "" },
+  } as any,
+  defaultContact: {
+    id: 100,
+    firstName: "John",
+    lastName: "Doe",
+    inactiveFlag: false,
+    title: "CEO",
+    defaultPhoneNbr: "555-1234",
+    communicationItems: [
+      { type: { name: "Email" }, value: "john@test.com" },
+      { type: { name: "Phone" }, value: "555-1234" },
+    ],
+  } as any,
+  allContacts: [] as any[],
+};
+
+describe("CompanyController", () => {
+  // -------------------------------------------------------------------
+  // Constructor
+  // -------------------------------------------------------------------
+  describe("constructor", () => {
+    test("sets public properties from company data", () => {
+      const data = buildMockCompany();
+      const ctrl = new CompanyController(data);
+      expect(ctrl.id).toBe("company-1");
+      expect(ctrl.name).toBe("Test Company");
+      expect(ctrl.cw_Identifier).toBe("TestCo");
+      expect(ctrl.cw_CompanyId).toBe(123);
+    });
+
+    test("accepts optional CW data", () => {
+      const data = buildMockCompany();
+      const ctrl = new CompanyController(data, mockCwData);
+      expect(ctrl.cw_Data).toBeDefined();
+      expect(ctrl.cw_Data?.company.city).toBe("Springfield");
+    });
+
+    test("cw_Data is undefined when not provided", () => {
+      const data = buildMockCompany();
+      const ctrl = new CompanyController(data);
+      expect(ctrl.cw_Data).toBeUndefined();
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // toJson
+  // -------------------------------------------------------------------
+  describe("toJson()", () => {
+    test("returns base fields without options", () => {
+      const ctrl = new CompanyController(buildMockCompany(), mockCwData);
+      const json = ctrl.toJson();
+      expect(json.id).toBe("company-1");
+      expect(json.name).toBe("Test Company");
+      expect(json.cw_Identifier).toBe("TestCo");
+      expect(json.cw_CompanyId).toBe(123);
+    });
+
+    test("excludes address when includeAddress is false", () => {
+      const ctrl = new CompanyController(buildMockCompany(), mockCwData);
+      const json = ctrl.toJson({
+        includeAddress: false,
+        includePrimaryContact: false,
+      });
+      expect(json.cw_Data.address).toBeUndefined();
+    });
+
+    test("includes address when includeAddress is true", () => {
+      const ctrl = new CompanyController(buildMockCompany(), mockCwData);
+      const json = ctrl.toJson({
+        includeAddress: true,
+        includePrimaryContact: false,
+      });
+      expect(json.cw_Data.address).toBeDefined();
+      expect(json.cw_Data.address!.city).toBe("Springfield");
+      expect(json.cw_Data.address!.state).toBe("IL");
+    });
+
+    test("includes primary contact when includePrimaryContact is true", () => {
+      const ctrl = new CompanyController(buildMockCompany(), mockCwData);
+      const json = ctrl.toJson({
+        includeAddress: false,
+        includePrimaryContact: true,
+      });
+      expect(json.cw_Data.primaryContact).toBeDefined();
+      expect(json.cw_Data.primaryContact!.firstName).toBe("John");
+      expect(json.cw_Data.primaryContact!.lastName).toBe("Doe");
+      expect(json.cw_Data.primaryContact!.email).toBe("john@test.com");
+    });
+
+    test("excludes primary contact when includePrimaryContact is false", () => {
+      const ctrl = new CompanyController(buildMockCompany(), mockCwData);
+      const json = ctrl.toJson({
+        includeAddress: false,
+        includePrimaryContact: false,
+      });
+      expect(json.cw_Data.primaryContact).toBeUndefined();
+    });
+
+    test("includes allContacts when includeAllContacts is true", () => {
+      const cwDataWithContacts = {
+        ...mockCwData,
+        allContacts: [
+          {
+            id: 200,
+            firstName: "Jane",
+            lastName: "Smith",
+            inactiveFlag: false,
+            title: "CTO",
+            defaultPhoneNbr: "555-5678",
+            communicationItems: [
+              { type: { name: "Email" }, value: "jane@test.com" },
+            ],
+          } as any,
+        ],
+      };
+      const ctrl = new CompanyController(
+        buildMockCompany(),
+        cwDataWithContacts,
+      );
+      const json = ctrl.toJson({
+        includeAddress: false,
+        includePrimaryContact: false,
+        includeAllContacts: true,
+      });
+      expect(json.cw_Data.allContacts).toBeDefined();
+      expect(json.cw_Data.allContacts).toHaveLength(1);
+      expect(json.cw_Data.allContacts![0]!.firstName).toBe("Jane");
+    });
+
+    test("email is null when no Email communication item", () => {
+      const noEmailCw = {
+        ...mockCwData,
+        defaultContact: {
+          ...mockCwData.defaultContact,
+          communicationItems: [{ type: { name: "Phone" }, value: "555" }],
+        },
+      };
+      const ctrl = new CompanyController(buildMockCompany(), noEmailCw);
+      const json = ctrl.toJson({
+        includeAddress: false,
+        includePrimaryContact: true,
+      });
+      expect(json.cw_Data.primaryContact!.email).toBeNull();
+    });
+
+    test("email is null when communicationItems is missing", () => {
+      const noCIData = {
+        ...mockCwData,
+        defaultContact: {
+          ...mockCwData.defaultContact,
+          communicationItems: undefined,
+        },
+      };
+      const ctrl = new CompanyController(buildMockCompany(), noCIData);
+      const json = ctrl.toJson({
+        includeAddress: false,
+        includePrimaryContact: true,
+      });
+      expect(json.cw_Data.primaryContact!.email).toBeNull();
+    });
+
+    test("country defaults to United States when null", () => {
+      const noCntry = {
+        ...mockCwData,
+        company: { ...mockCwData.company, country: null },
+      };
+      const ctrl = new CompanyController(buildMockCompany(), noCntry);
+      const json = ctrl.toJson({
+        includeAddress: true,
+        includePrimaryContact: false,
+      });
+      expect(json.cw_Data.address!.country).toBe("United States");
+    });
+  });
+});

tests/unit/controllers/CredentialController.test.ts

@@ -0,0 +1,195 @@
+import { describe, test, expect } from "bun:test";
+import { CredentialController } from "../../../src/controllers/CredentialController";
+import { buildMockCredential } from "../../setup";
+import { ValueType } from "../../../src/modules/credentials/credentialTypeDefs";
+
+describe("CredentialController", () => {
+  // -------------------------------------------------------------------
+  // Constructor & _buildFields
+  // -------------------------------------------------------------------
+  describe("constructor", () => {
+    test("sets public properties from credential data", () => {
+      const data = buildMockCredential();
+      const ctrl = new CredentialController(data);
+      expect(ctrl.id).toBe("cred-1");
+      expect(ctrl.name).toBe("Test Credential");
+      expect(ctrl.notes).toBeNull();
+      expect(ctrl.typeId).toBe("ctype-1");
+      expect(ctrl.companyId).toBe("company-1");
+      expect(ctrl.subCredentialOfId).toBeNull();
+    });
+
+    test("builds fields from type definition", () => {
+      const data = buildMockCredential();
+      const ctrl = new CredentialController(data);
+      expect(Array.isArray(ctrl.fields)).toBe(true);
+      expect(ctrl.fields).toHaveLength(2);
+    });
+
+    test("plain fields have value from raw data", () => {
+      const data = buildMockCredential();
+      const ctrl = new CredentialController(data);
+      const usernameField = ctrl.fields.find((f: any) => f.id === "username");
+      expect(usernameField).toBeDefined();
+      expect(usernameField.value).toBe("admin");
+      expect(usernameField.secure).toBe(false);
+    });
+
+    test("secure fields reference secure value ID", () => {
+      const data = buildMockCredential();
+      const ctrl = new CredentialController(data);
+      const passwordField = ctrl.fields.find((f: any) => f.id === "password");
+      expect(passwordField).toBeDefined();
+      expect(passwordField.secure).toBe(true);
+      expect(passwordField.value).toBe("secure-sv-1");
+    });
+
+    test("handles sub-credentials in constructor", () => {
+      const subCred = buildMockCredential({
+        id: "sub-cred-1",
+        name: "Sub Cred",
+        subCredentialOfId: "cred-1",
+        type: {
+          id: "ctype-1",
+          name: "Login Credential",
+          permissionScope: "credential.login",
+          icon: null,
+          fields: [
+            {
+              id: "username",
+              name: "Username",
+              required: true,
+              secure: false,
+              valueType: "plain_text",
+            },
+          ],
+        },
+        securevalues: [],
+        subCredentials: [],
+      });
+      const parent = buildMockCredential({
+        subCredentials: [subCred],
+      });
+      const ctrl = new CredentialController(parent);
+      // The parent should have the sub-credential processed
+      expect(ctrl.id).toBe("cred-1");
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // getType / getCompany
+  // -------------------------------------------------------------------
+  describe("getType() / getCompany()", () => {
+    test("getType returns the credential type", () => {
+      const ctrl = new CredentialController(buildMockCredential());
+      const type = ctrl.getType();
+      expect(type.id).toBe("ctype-1");
+      expect(type.name).toBe("Login Credential");
+    });
+
+    test("getCompany returns the company", () => {
+      const ctrl = new CredentialController(buildMockCredential());
+      const company = ctrl.getCompany();
+      expect(company.id).toBe("company-1");
+      expect(company.name).toBe("Test Company");
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // toJson
+  // -------------------------------------------------------------------
+  describe("toJson()", () => {
+    test("returns structured JSON without secure field IDs by default", () => {
+      const ctrl = new CredentialController(buildMockCredential());
+      const json = ctrl.toJson();
+      expect(json.id).toBe("cred-1");
+      expect(json.name).toBe("Test Credential");
+      expect(json.typeId).toBe("ctype-1");
+      expect(json.companyId).toBe("company-1");
+      expect(json.type.id).toBe("ctype-1");
+      expect(json.company.id).toBe("company-1");
+      expect(json.secureFieldIds).toBeUndefined();
+    });
+
+    test("includes secure field IDs when includeSecureValues is true", () => {
+      const ctrl = new CredentialController(buildMockCredential());
+      const json = ctrl.toJson({ includeSecureValues: true });
+      expect(json.secureFieldIds).toBeDefined();
+      expect(json.secureFieldIds).toContain("password");
+    });
+
+    test("includes subCredentialOfId when present", () => {
+      const data = buildMockCredential({ subCredentialOfId: "parent-1" });
+      const ctrl = new CredentialController(data);
+      const json = ctrl.toJson();
+      expect(json.subCredentialOfId).toBe("parent-1");
+    });
+
+    test("excludes subCredentialOfId when null", () => {
+      const ctrl = new CredentialController(buildMockCredential());
+      const json = ctrl.toJson();
+      expect(json.subCredentialOfId).toBeUndefined();
+    });
+
+    test("includes timestamp fields", () => {
+      const ctrl = new CredentialController(buildMockCredential());
+      const json = ctrl.toJson();
+      expect(json.createdAt).toBeDefined();
+      expect(json.updatedAt).toBeDefined();
+    });
+
+    test("subCredentials is undefined when empty", () => {
+      const ctrl = new CredentialController(buildMockCredential());
+      const json = ctrl.toJson();
+      expect(json.subCredentials).toBeUndefined();
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // Sub-credential field building
+  // -------------------------------------------------------------------
+  describe("sub-credential field building", () => {
+    test("builds fields differently for sub-credentials", () => {
+      const subData = buildMockCredential({
+        id: "sub-1",
+        subCredentialOfId: "parent-1",
+        fields: { sub_user: "jdoe" },
+        type: {
+          id: "ctype-1",
+          name: "Login",
+          permissionScope: "credential.login",
+          icon: null,
+          fields: [
+            {
+              id: "sub_user",
+              name: "Sub User",
+              required: true,
+              secure: false,
+              valueType: ValueType.PLAIN_TEXT,
+            },
+          ],
+        },
+        securevalues: [
+          {
+            id: "sv-2",
+            name: "sub_pass",
+            content: "enc",
+            hash: "hash",
+            credentialId: "sub-1",
+            createdAt: new Date("2025-01-01"),
+            updatedAt: new Date("2025-01-01"),
+          },
+        ],
+      });
+      const ctrl = new CredentialController(subData);
+      // Sub-credential fields are built as array with id/value/secure
+      expect(Array.isArray(ctrl.fields)).toBe(true);
+      const plainField = ctrl.fields.find((f: any) => f.id === "sub_user");
+      expect(plainField).toBeDefined();
+      expect(plainField.secure).toBe(false);
+      const secureField = ctrl.fields.find((f: any) => f.id === "sub_pass");
+      expect(secureField).toBeDefined();
+      expect(secureField.secure).toBe(true);
+    });
+  });
+});

tests/unit/controllers/CredentialTypeController.test.ts

@@ -0,0 +1,144 @@
+import { describe, test, expect } from "bun:test";
+import { CredentialTypeController } from "../../../src/controllers/CredentialTypeController";
+import { buildMockCredentialType } from "../../setup";
+import { ValueType } from "../../../src/modules/credentials/credentialTypeDefs";
+
+describe("CredentialTypeController", () => {
+  // -------------------------------------------------------------------
+  // Constructor
+  // -------------------------------------------------------------------
+  describe("constructor", () => {
+    test("sets public properties", () => {
+      const ctrl = new CredentialTypeController(buildMockCredentialType());
+      expect(ctrl.id).toBe("ctype-1");
+      expect(ctrl.name).toBe("Login Credential");
+      expect(ctrl.permissionScope).toBe("credential.login");
+      expect(ctrl.icon).toBeNull();
+      expect(ctrl.fields).toHaveLength(2);
+    });
+
+    test("parses timestamps", () => {
+      const ctrl = new CredentialTypeController(buildMockCredentialType());
+      expect(ctrl.createdAt).toBeInstanceOf(Date);
+      expect(ctrl.updatedAt).toBeInstanceOf(Date);
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // getFieldDefinition
+  // -------------------------------------------------------------------
+  describe("getFieldDefinition()", () => {
+    test("returns matching field", () => {
+      const ctrl = new CredentialTypeController(buildMockCredentialType());
+      const field = ctrl.getFieldDefinition("username");
+      expect(field).toBeDefined();
+      expect(field!.name).toBe("Username");
+    });
+
+    test("returns undefined for unknown field", () => {
+      const ctrl = new CredentialTypeController(buildMockCredentialType());
+      expect(ctrl.getFieldDefinition("nonexistent")).toBeUndefined();
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // getRequiredFields
+  // -------------------------------------------------------------------
+  describe("getRequiredFields()", () => {
+    test("returns only required fields", () => {
+      const data = buildMockCredentialType({
+        fields: [
+          {
+            id: "a",
+            name: "A",
+            required: true,
+            secure: false,
+            valueType: ValueType.PLAIN_TEXT,
+          },
+          {
+            id: "b",
+            name: "B",
+            required: false,
+            secure: false,
+            valueType: ValueType.PLAIN_TEXT,
+          },
+          {
+            id: "c",
+            name: "C",
+            required: true,
+            secure: true,
+            valueType: ValueType.PASSWORD,
+          },
+        ],
+      });
+      const ctrl = new CredentialTypeController(data);
+      const required = ctrl.getRequiredFields();
+      expect(required).toHaveLength(2);
+      expect(required.map((f) => f.id)).toEqual(["a", "c"]);
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // getSecureFields
+  // -------------------------------------------------------------------
+  describe("getSecureFields()", () => {
+    test("returns only secure fields", () => {
+      const ctrl = new CredentialTypeController(buildMockCredentialType());
+      const secure = ctrl.getSecureFields();
+      expect(secure).toHaveLength(1);
+      expect(secure[0]!.id).toBe("password");
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // countCredentials
+  // -------------------------------------------------------------------
+  describe("countCredentials()", () => {
+    test("returns 0 when no credentials", () => {
+      const ctrl = new CredentialTypeController(buildMockCredentialType());
+      expect(ctrl.countCredentials()).toBe(0);
+    });
+
+    test("returns correct count", () => {
+      const data = buildMockCredentialType({
+        credentials: [{ id: "c1" }, { id: "c2" }, { id: "c3" }],
+      });
+      const ctrl = new CredentialTypeController(data);
+      expect(ctrl.countCredentials()).toBe(3);
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // toJson
+  // -------------------------------------------------------------------
+  describe("toJson()", () => {
+    test("returns base JSON without credential count by default", () => {
+      const ctrl = new CredentialTypeController(buildMockCredentialType());
+      const json = ctrl.toJson();
+      expect(json.id).toBe("ctype-1");
+      expect(json.name).toBe("Login Credential");
+      expect(json.credentialCount).toBeUndefined();
+    });
+
+    test("includes credential count when option is set", () => {
+      const data = buildMockCredentialType({
+        credentials: [{ id: "c1" }, { id: "c2" }],
+      });
+      const ctrl = new CredentialTypeController(data);
+      const json = ctrl.toJson({ includeCredentialCount: true });
+      expect(json.credentialCount).toBe(2);
+    });
+
+    test("includes all expected keys", () => {
+      const ctrl = new CredentialTypeController(buildMockCredentialType());
+      const json = ctrl.toJson();
+      expect(json).toHaveProperty("id");
+      expect(json).toHaveProperty("name");
+      expect(json).toHaveProperty("permissionScope");
+      expect(json).toHaveProperty("icon");
+      expect(json).toHaveProperty("fields");
+      expect(json).toHaveProperty("createdAt");
+      expect(json).toHaveProperty("updatedAt");
+    });
+  });
+});

tests/unit/controllers/RoleController.test.ts

@@ -0,0 +1,73 @@
+import { describe, test, expect } from "bun:test";
+import { RoleController } from "../../../src/controllers/RoleController";
+import { buildMockRole, buildMockUser } from "../../setup";
+
+describe("RoleController", () => {
+  // -------------------------------------------------------------------
+  // Constructor
+  // -------------------------------------------------------------------
+  describe("constructor", () => {
+    test("sets public properties from role data", () => {
+      const data = buildMockRole();
+      const ctrl = new RoleController(data);
+      expect(ctrl.id).toBe("role-1");
+      expect(ctrl.title).toBe("Test Role");
+      expect(ctrl.moniker).toBe("test-role");
+      expect(ctrl.deleted).toBe(false);
+    });
+
+    test("sets timestamps", () => {
+      const ctrl = new RoleController(buildMockRole());
+      expect(ctrl.createdAt).toBeInstanceOf(Date);
+      expect(ctrl.updatedAt).toBeInstanceOf(Date);
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // getUsers
+  // -------------------------------------------------------------------
+  describe("getUsers()", () => {
+    test("returns empty collection when no users", () => {
+      const ctrl = new RoleController(buildMockRole({ users: [] }));
+      const users = ctrl.getUsers();
+      expect(users.size).toBe(0);
+    });
+
+    test("returns collection of UserController instances", () => {
+      const userData = buildMockUser({ id: "u-1" });
+      const ctrl = new RoleController(buildMockRole({ users: [userData] }));
+      const users = ctrl.getUsers();
+      expect(users.size).toBe(1);
+      expect(users.get("u-1")).toBeDefined();
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // toJson
+  // -------------------------------------------------------------------
+  describe("toJson()", () => {
+    test("returns base JSON without permissions or users by default", () => {
+      const ctrl = new RoleController(buildMockRole());
+      const json = ctrl.toJson();
+      expect(json.id).toBe("role-1");
+      expect(json.title).toBe("Test Role");
+      expect(json.moniker).toBe("test-role");
+      expect(json.permissions).toBeUndefined();
+      expect(json.users).toBeUndefined();
+      expect(json.createdAt).toBeDefined();
+      expect(json.updatedAt).toBeDefined();
+    });
+
+    test("includes users when viewUsers is true", () => {
+      const userData = buildMockUser({
+        id: "u-1",
+        roles: [{ id: "role-1", moniker: "test-role" }],
+      });
+      const ctrl = new RoleController(buildMockRole({ users: [userData] }));
+      const json = ctrl.toJson({ viewUsers: true });
+      expect(json.users).toBeDefined();
+      expect(json.users).toHaveLength(1);
+      expect(json.users![0]!.id).toBe("u-1");
+    });
+  });
+});

tests/unit/controllers/SessionController.test.ts

@@ -0,0 +1,58 @@
+import { describe, test, expect } from "bun:test";
+import { SessionController } from "../../../src/controllers/SessionController";
+import { buildMockSession } from "../../setup";
+
+describe("SessionController", () => {
+  // -------------------------------------------------------------------
+  // Constructor
+  // -------------------------------------------------------------------
+  describe("constructor", () => {
+    test("sets all public properties from session data", () => {
+      const data = buildMockSession();
+      const ctrl = new SessionController(data);
+      expect(ctrl.id).toBe("session-1");
+      expect(ctrl.sessionKey).toBe("sk-abc123");
+      expect(ctrl.userId).toBe("user-1");
+      expect(ctrl.expires).toBeInstanceOf(Date);
+      expect(ctrl.refreshedAt).toBeNull();
+      expect(ctrl.invalidatedAt).toBeNull();
+      expect(ctrl.terminated).toBe(false);
+    });
+
+    test("sets custom values from overrides", () => {
+      const refreshDate = new Date("2025-06-01");
+      const ctrl = new SessionController(
+        buildMockSession({ refreshedAt: refreshDate }),
+      );
+      expect(ctrl.refreshedAt).toEqual(refreshDate);
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // invalidate
+  // -------------------------------------------------------------------
+  describe("invalidate()", () => {
+    test("throws when session is already invalidated", async () => {
+      const ctrl = new SessionController(
+        buildMockSession({ invalidatedAt: new Date() }),
+      );
+      await expect(ctrl.invalidate()).rejects.toThrow(
+        "Session has already been invalidated",
+      );
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // generateTokens
+  // -------------------------------------------------------------------
+  describe("generateTokens()", () => {
+    test("throws when tokens have already been generated", async () => {
+      const ctrl = new SessionController(
+        buildMockSession({ refreshTokenGenerated: true }),
+      );
+      await expect(ctrl.generateTokens()).rejects.toThrow(
+        "Tokens have alredy been generated",
+      );
+    });
+  });
+});

tests/unit/controllers/UnifiSiteController.test.ts

@@ -0,0 +1,43 @@
+import { describe, test, expect } from "bun:test";
+import { UnifiSiteController } from "../../../src/controllers/UnifiSiteController";
+import { buildMockUnifiSite } from "../../setup";
+
+describe("UnifiSiteController", () => {
+  describe("constructor", () => {
+    test("sets all properties from site data", () => {
+      const ctrl = new UnifiSiteController(buildMockUnifiSite());
+      expect(ctrl.id).toBe("usite-1");
+      expect(ctrl.name).toBe("Main Office");
+      expect(ctrl.siteId).toBe("default");
+      expect(ctrl.companyId).toBeNull();
+    });
+
+    test("accepts non-null companyId", () => {
+      const ctrl = new UnifiSiteController(
+        buildMockUnifiSite({ companyId: "company-1" }),
+      );
+      expect(ctrl.companyId).toBe("company-1");
+    });
+  });
+
+  describe("toJson()", () => {
+    test("returns all properties", () => {
+      const ctrl = new UnifiSiteController(
+        buildMockUnifiSite({ companyId: "comp-abc" }),
+      );
+      const json = ctrl.toJson();
+      expect(json).toEqual({
+        id: "usite-1",
+        name: "Main Office",
+        siteId: "default",
+        companyId: "comp-abc",
+      });
+    });
+
+    test("companyId is null when unlinked", () => {
+      const ctrl = new UnifiSiteController(buildMockUnifiSite());
+      const json = ctrl.toJson();
+      expect(json.companyId).toBeNull();
+    });
+  });
+});

tests/unit/controllers/UserController.test.ts

@@ -0,0 +1,117 @@
+import { describe, test, expect } from "bun:test";
+import UserController from "../../../src/controllers/UserController";
+import { buildMockUser } from "../../setup";
+
+describe("UserController", () => {
+  // -------------------------------------------------------------------
+  // Constructor
+  // -------------------------------------------------------------------
+  describe("constructor", () => {
+    test("sets all public properties", () => {
+      const ctrl = new UserController(buildMockUser());
+      expect(ctrl.id).toBe("user-1");
+      expect(ctrl.name).toBe("Test User");
+      expect(ctrl.login).toBe("test@example.com");
+      expect(ctrl.email).toBe("test@example.com");
+      expect(ctrl.image).toBeNull();
+    });
+
+    test("sets timestamps", () => {
+      const ctrl = new UserController(buildMockUser());
+      expect(ctrl.createdAt).toBeInstanceOf(Date);
+      expect(ctrl.updatedAt).toBeInstanceOf(Date);
+    });
+
+    test("builds roles collection", () => {
+      const mockRole = {
+        id: "role-1",
+        title: "Admin",
+        moniker: "admin",
+        permissions: "tok",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+      const ctrl = new UserController(buildMockUser({ roles: [mockRole] }));
+      // _roles is private, but we can verify via toJson
+      const json = ctrl.toJson();
+      expect(json.roles).toContain("admin");
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // toJson
+  // -------------------------------------------------------------------
+  describe("toJson()", () => {
+    test("returns full JSON by default", () => {
+      const ctrl = new UserController(buildMockUser());
+      const json = ctrl.toJson();
+      expect(json.id).toBe("user-1");
+      expect(json.name).toBe("Test User");
+      expect(json.login).toBe("test@example.com");
+      expect(json.email).toBe("test@example.com");
+      expect(json.image).toBeNull();
+      expect(json.createdAt).toBeDefined();
+      expect(json.updatedAt).toBeDefined();
+    });
+
+    test("safeReturn hides sensitive fields", () => {
+      const ctrl = new UserController(buildMockUser());
+      const json = ctrl.toJson({ safeReturn: true });
+      expect(json.id).toBe("user-1");
+      expect(json.name).toBe("Test User");
+      expect(json.login).toBeUndefined();
+      expect(json.email).toBeUndefined();
+      expect(json.roles).toBeUndefined();
+      expect(json.permissions).toBeUndefined();
+    });
+
+    test("roles is undefined when user has no roles", () => {
+      const ctrl = new UserController(buildMockUser({ roles: [] }));
+      const json = ctrl.toJson();
+      // _roles.size == 0, so roles is undefined
+      expect(json.roles).toBeUndefined();
+    });
+
+    test("roles returns monikers when present", () => {
+      const mockRoles = [
+        {
+          id: "r1",
+          title: "Admin",
+          moniker: "admin",
+          permissions: "t",
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        },
+        {
+          id: "r2",
+          title: "User",
+          moniker: "user",
+          permissions: "t",
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        },
+      ];
+      const ctrl = new UserController(buildMockUser({ roles: mockRoles }));
+      const json = ctrl.toJson();
+      expect(json.roles).toHaveLength(2);
+      expect(json.roles).toContain("admin");
+      expect(json.roles).toContain("user");
+    });
+
+    test("permissions returns empty array when user has no permissions token", () => {
+      const ctrl = new UserController(buildMockUser({ permissions: null }));
+      const json = ctrl.toJson();
+      expect(json.permissions).toEqual([]);
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // readPermissions
+  // -------------------------------------------------------------------
+  describe("readPermissions()", () => {
+    test("returns empty array when permissions is null", () => {
+      const ctrl = new UserController(buildMockUser({ permissions: null }));
+      expect(ctrl.readPermissions()).toEqual([]);
+    });
+  });
+});