refactor(signatureRequests): restructure signature request handling and enhance related components

- Moved signature request resolver and composed resolver to services dir
- Updaed SignatureRequestResolver with docs
- Enhanced SignatureRequestsService with detailed documentation and methods for managing signature requests.
- Added extensive test coverage for SignatureRequestsService and SignatureRequestResolver, ensuring robust functionality and error handling.
- Updated database schema to support signature requests and improved mock data generation utilities.

Author: bitbeckers

src/graphql/schemas/resolvers/composed.ts

@@ -16,6 +16,21 @@ export type SignatureRequestUpdate = Updateable<
   DataDatabase["signature_requests"]
 >;
 
+/**
+ * Service for handling signature request operations in the system.
+ * Provides methods for retrieving, creating and updating signature requests.
+ *
+ * A signature request represents a request for a user to sign a message, with:
+ * - Safe address (the address that needs to sign)
+ * - Message hash (hash of the message to be signed)
+ * - Status (pending, executed, canceled)
+ * - Purpose (e.g. update_user_data)
+ *
+ * This service uses an EntityService for database operations, providing:
+ * - Consistent error handling
+ * - Type safety through Kysely
+ * - Standard query interface
+ */
 @injectable()
 export class SignatureRequestsService {
   private entityService: EntityService<
@@ -31,16 +46,67 @@ export class SignatureRequestsService {
     >("signature_requests", "SignatureRequestsEntityService", kyselyData);
   }
 
+  /**
+   * Retrieves multiple signature requests based on provided arguments.
+   *
+   * @param args - Query arguments for filtering signature requests
+   * @returns A promise resolving to:
+   *          - data: Array of signature requests matching the criteria
+   *          - count: Total number of matching records
+   *
+   * @example
+   * ```typescript
+   * const result = await signatureRequestsService.getSignatureRequests({
+   *   where: {
+   *     safe_address: { eq: "0x1234...5678" }
+   *   }
+   * });
+   * ```
+   */
   async getSignatureRequests(args: GetSignatureRequestsArgs) {
     return this.entityService.getMany(args);
   }
 
+  /**
+   * Retrieves a single signature request based on provided arguments.
+   *
+   * @param args - Query arguments for filtering signature requests
+   * @returns A promise resolving to:
+   *          - The matching signature request if found
+   *          - null if no matching record exists
+   *
+   * @example
+   * ```typescript
+   * const request = await signatureRequestsService.getSignatureRequest({
+   *   where: {
+   *     safe_address: { eq: "0x1234...5678" },
+   *     message_hash: { eq: "0xabcd...ef12" }
+   *   }
+   * });
+   * ```
+   */
   async getSignatureRequest(args: GetSignatureRequestsArgs) {
     return this.entityService.getSingle(args);
   }
 
   // Mutations
 
+  /**
+   * Creates a new signature request.
+   *
+   * @param signatureRequest - The signature request data to insert
+   * @returns A promise resolving to the created signature request's safe_address and message_hash
+   *
+   * @example
+   * ```typescript
+   * const result = await signatureRequestsService.addSignatureRequest({
+   *   safe_address: "0x1234...5678",
+   *   message_hash: "0xabcd...ef12",
+   *   status: "pending",
+   *   purpose: "update_user_data"
+   * });
+   * ```
+   */
   async addSignatureRequest(signatureRequest: SignatureRequestInsert) {
     return this.dbService
       .getConnection()
@@ -50,6 +116,23 @@ export class SignatureRequestsService {
       .executeTakeFirst();
   }
 
+  /**
+   * Updates the status of an existing signature request.
+   *
+   * @param safe_address - The safe address associated with the request
+   * @param message_hash - The message hash of the request
+   * @param status - The new status to set
+   * @returns A promise resolving to the number of affected rows
+   *
+   * @example
+   * ```typescript
+   * await signatureRequestsService.updateSignatureRequestStatus(
+   *   "0x1234...5678",
+   *   "0xabcd...ef12",
+   *   "executed"
+   * );
+   * ```
+   */
   async updateSignatureRequestStatus(
     safe_address: string,
     message_hash: string,

src/graphql/schemas/resolvers/signatureRequestResolver.ts

@@ -2,16 +2,38 @@ import { Kysely } from "kysely";
 import { DataDatabase } from "../../../types/kyselySupabaseData.js";
 import { QueryStrategy } from "./QueryStrategy.js";
 
+/**
+ * Query strategy for signature requests.
+ * Handles building queries for retrieving and counting signature requests.
+ *
+ * A signature request represents a request for a user to sign a message, with:
+ * - Safe address (the address that needs to sign)
+ * - Message hash (hash of the message to be signed)
+ * - Status (pending, executed, canceled)
+ * - Purpose (e.g. update_user_data)
+ */
 export class SignatureRequestsQueryStrategy extends QueryStrategy<
   DataDatabase,
   "signature_requests"
 > {
   protected readonly tableName = "signature_requests" as const;
 
+  /**
+   * Builds a query to select all signature request data.
+   *
+   * @param db - The database connection
+   * @returns A query builder for selecting signature request data
+   */
   buildDataQuery(db: Kysely<DataDatabase>) {
     return db.selectFrom(this.tableName).selectAll();
   }
 
+  /**
+   * Builds a query to count signature requests.
+   *
+   * @param db - The database connection
+   * @returns A query builder for counting signature requests
+   */
   buildCountQuery(db: Kysely<DataDatabase>) {
     return db.selectFrom(this.tableName).select((eb) => {
       return eb.fn.countAll().as("count");

src/services/database/entities/SignatureRequestsEntityService.ts

@@ -0,0 +1,31 @@
+import { HypercertResolver } from "./hypercertResolver.js";
+import { MetadataResolver } from "./metadataResolver.js";
+import { ContractResolver } from "./contractResolver.js";
+import { FractionResolver } from "./fractionResolver.js";
+import { AttestationResolver } from "./attestationResolver.js";
+import { AttestationSchemaResolver } from "./attestationSchemaResolver.js";
+import { OrderResolver } from "./orderResolver.js";
+import { HyperboardResolver } from "./hyperboardResolver.js";
+import { AllowlistRecordResolver } from "./allowlistRecordResolver.js";
+import { SalesResolver } from "./salesResolver.js";
+import { UserResolver } from "./userResolver.js";
+import { BlueprintResolver } from "./blueprintResolver.js";
+import { SignatureRequestResolver } from "./signatureRequestResolver.js";
+import { CollectionResolver } from "./collectionResolver.js";
+
+export const resolvers = [
+  ContractResolver,
+  FractionResolver,
+  MetadataResolver,
+  HypercertResolver,
+  AttestationResolver,
+  AttestationSchemaResolver,
+  OrderResolver,
+  HyperboardResolver,
+  AllowlistRecordResolver,
+  SalesResolver,
+  UserResolver,
+  BlueprintResolver,
+  SignatureRequestResolver,
+  CollectionResolver,
+] as const;

src/services/database/strategies/SignatureRequestsQueryStrategy.ts

@@ -0,0 +1,53 @@
+import { Args, FieldResolver, Query, Resolver, Root } from "type-graphql";
+
+import { GetSignatureRequestsArgs } from "../../../graphql/schemas/args/signatureRequestArgs.js";
+import {
+  GetSignatureRequestResponse,
+  SignatureRequest,
+} from "../../../graphql/schemas/typeDefs/signatureRequestTypeDefs.js";
+
+import { inject, injectable } from "tsyringe";
+import { SignatureRequestsService } from "../../database/entities/SignatureRequestsEntityService.js";
+
+/**
+ * GraphQL resolver for signature requests.
+ * Handles queries for retrieving signature requests and resolves specific fields.
+ *
+ * A signature request represents a message that needs to be signed by a Safe wallet,
+ * typically used for user data updates or other authenticated operations.
+ */
+@injectable()
+@Resolver(() => SignatureRequest)
+export class SignatureRequestResolver {
+  constructor(
+    @inject(SignatureRequestsService)
+    private signatureRequestsService: SignatureRequestsService,
+  ) {}
+
+  /**
+   * Query resolver for fetching signature requests.
+   * Can be filtered by safe address and status.
+   *
+   * @param args - Query arguments including optional safe_address and status filters
+   * @returns A paginated response containing signature requests and total count
+   */
+  @Query(() => GetSignatureRequestResponse)
+  async signatureRequests(@Args() args: GetSignatureRequestsArgs) {
+    return await this.signatureRequestsService.getSignatureRequests(args);
+  }
+
+  /**
+   * Field resolver for the message field.
+   * Ensures consistent string representation of messages, whether they're
+   * stored as objects or strings.
+   *
+   * @param signatureRequest - The signature request containing the message
+   * @returns The message as a string, stringified if it's an object
+   */
+  @FieldResolver(() => String)
+  message(@Root() signatureRequest: SignatureRequest): string {
+    return typeof signatureRequest.message === "object"
+      ? JSON.stringify(signatureRequest.message)
+      : signatureRequest.message || "could not parse message";
+  }
+}