refactor(user): implement comprehensive user resolver and related components

Restructured user-related code to improve organization and maintainability:
- Moved UserResolver from graphql to services directory
- Updated import paths in composed resolver
- Enhanced UsersEntityService with comprehensive documentation
- Added detailed JSDoc comments for UserService, UsersQueryStrategy, and UserResolver
- Introduced comprehensive test coverage for UsersService, UsersQueryStrategy, and UserResolver
- Improved error handling to return null for failed resolver queries
- Standardized code structure with other similar resolvers
- Added test utilities for generating mock user and signature request data

Author: bitbeckers

src/graphql/schemas/resolvers/composed.ts

@@ -8,7 +8,7 @@ import { OrderResolver } from "./orderResolver.js";
 import { HyperboardResolver } from "./hyperboardResolver.js";
 import { AllowlistRecordResolver } from "../../../services/graphql/resolvers/allowlistRecordResolver.js";
 import { SalesResolver } from "../../../services/graphql/resolvers/salesResolver.js";
-import { UserResolver } from "./userResolver.js";
+import { UserResolver } from "../../../services/graphql/resolvers/userResolver.js";
 import { BlueprintResolver } from "../../../services/graphql/resolvers/blueprintResolver.js";
 import { SignatureRequestResolver } from "./signatureRequestResolver.js";
 import { CollectionResolver } from "./collectionResolver.js";

src/graphql/schemas/resolvers/userResolver.ts

@@ -23,11 +23,6 @@ export type BlueprintAdminSelect = Selectable<DataDatabase["users"]>;
  * - Handle blueprint minting and collection updates
  * - Transaction support for complex operations
  *
- * Error Handling:
- * - All database operations are wrapped in try-catch blocks
- * - Errors are logged and rethrown for proper error propagation
- * - Transaction rollback on failure for multi-step operations
- *
  * @singleton Marks the class as a singleton for dependency injection
  */
 @singleton()

src/services/database/entities/BlueprintsEntityService.ts

@@ -2,13 +2,34 @@ import { Kysely } from "kysely";
 import { DataDatabase } from "../../../types/kyselySupabaseData.js";
 import { QueryStrategy } from "./QueryStrategy.js";
 
+/**
+ * Strategy for building queries related to user data.
+ * Implements the QueryStrategy interface for the users table.
+ *
+ * This strategy extends the base QueryStrategy to provide user-specific query building.
+ * It handles:
+ * - Basic data retrieval from the users table
+ * - Counting operations with appropriate joins
+ *
+ * @template DataDatabase - The database type containing the users table
+ */
 export class UsersQueryStrategy extends QueryStrategy<DataDatabase, "users"> {
   protected readonly tableName = "users" as const;
 
+  /**
+   * Builds a query to select all user data.
+   * @param db - Database connection
+   * @returns Query builder for selecting user data
+   */
   buildDataQuery(db: Kysely<DataDatabase>) {
     return db.selectFrom(this.tableName).selectAll();
   }
 
+  /**
+   * Builds a query to count total number of users.
+   * @param db - Database connection
+   * @returns Query builder for counting users
+   */
   buildCountQuery(db: Kysely<DataDatabase>) {
     return db.selectFrom(this.tableName).select((eb) => {
       return eb.fn.countAll().as("count");

src/services/database/strategies/UsersQueryStrategy.ts

@@ -0,0 +1,138 @@
+import { Args, FieldResolver, Query, Resolver, Root } from "type-graphql";
+
+import { GetUsersArgs } from "../../../graphql/schemas/args/userArgs.js";
+import { SignatureRequest } from "../../../graphql/schemas/typeDefs/signatureRequestTypeDefs.js";
+import GetUsersResponse, {
+  User,
+} from "../../../graphql/schemas/typeDefs/userTypeDefs.js";
+
+import { inject, injectable } from "tsyringe";
+import { SignatureRequestsService } from "../../database/entities/SignatureRequestsEntityService.js";
+import { UsersService } from "../../database/entities/UsersEntityService.js";
+
+/**
+ * GraphQL resolver for User operations.
+ * Handles queries for users and resolves related fields.
+ *
+ * This resolver provides:
+ * - Query for fetching users with optional filtering
+ * - Field resolution for signature requests associated with a user
+ *
+ * Error Handling:
+ * If an operation fails, it will:
+ * - Log the error internally for monitoring
+ * - Return null/empty data to the client
+ * - Include error information in the GraphQL response errors array
+ *
+ * @injectable Marks the class as injectable for dependency injection with tsyringe
+ * @resolver Marks the class as a GraphQL resolver for the User type
+ */
+@injectable()
+@Resolver(() => User)
+class UserResolver {
+  /**
+   * Creates a new instance of UserResolver.
+   *
+   * @param usersService - Service for handling user operations
+   * @param signatureRequestsService - Service for handling signature request operations
+   */
+  constructor(
+    @inject(UsersService)
+    private usersService: UsersService,
+    @inject(SignatureRequestsService)
+    private signatureRequestsService: SignatureRequestsService,
+  ) {}
+
+  /**
+   * Queries users based on provided arguments.
+   * Returns both the matching users and a total count.
+   *
+   * @param args - Query arguments for filtering users
+   * @returns A promise that resolves to an object containing:
+   *          - data: Array of users matching the query
+   *          - count: Total number of matching users
+   *
+   * @example
+   * ```graphql
+   * query {
+   *   users(
+   *     where: {
+   *       address: { eq: "0x..." },
+   *       chain_id: { eq: 1 }
+   *     }
+   *   ) {
+   *     data {
+   *       id
+   *       address
+   *       display_name
+   *       avatar
+   *     }
+   *     count
+   *   }
+   * }
+   * ```
+   */
+  @Query(() => GetUsersResponse)
+  async users(@Args() args: GetUsersArgs) {
+    try {
+      return await this.usersService.getUsers(args);
+    } catch (e) {
+      console.error(
+        `[UserResolver::users] Error fetching users: ${(e as Error).message}`,
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Resolves the signature_requests field for a user.
+   * This field resolver is called automatically when the signature_requests field is requested in a query.
+   *
+   * @param user - The user for which to resolve signature requests
+   * @returns A promise resolving to:
+   *          - Array of signature requests if found
+   *          - null if:
+   *            - No user address is available
+   *            - An error occurs during retrieval
+   *
+   * @example
+   * ```graphql
+   * query {
+   *   users {
+   *     data {
+   *       id
+   *       address
+   *       signature_requests {
+   *         id
+   *         message
+   *         status
+   *       }
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  @FieldResolver(() => [SignatureRequest])
+  async signature_requests(@Root() user: User) {
+    if (!user.address) {
+      return null;
+    }
+
+    try {
+      return await this.signatureRequestsService.getSignatureRequests({
+        where: {
+          safe_address: {
+            eq: user.address,
+          },
+        },
+      });
+    } catch (e) {
+      console.error(
+        `[UserResolver::signature_requests] Error fetching signature requests for user ${user.id}: ${(e as Error).message}`,
+      );
+      return null;
+    }
+  }
+}
+
+export { UserResolver };

src/services/graphql/resolvers/userResolver.ts

@@ -11,6 +11,7 @@ import {
   generateHypercertId,
   generateMockAddress,
   generateMockBlueprint,
+  generateMockUser,
 } from "../../../utils/testUtils.js";
 
 const mockDb = vi.fn();
@@ -148,14 +149,7 @@ describe("BlueprintsService", () => {
       const mockBlueprint = generateMockBlueprint();
       await db.insertInto("blueprints").values(mockBlueprint).execute();
 
-      const mockUser = {
-        id: "user1",
-        address: "0x123",
-        display_name: "Test Admin",
-        avatar: "test-avatar",
-        chain_id: 1,
-        created_at: new Date().toISOString(),
-      };
+      const mockUser = generateMockUser();
       await db.insertInto("users").values(mockUser).execute();
 
       await db