refactor(sales): implement comprehensive sales resolver and services

Restructured sales-related components to improve code organization and maintainability:
- Moved SalesResolver from graphql to services directory
- Updated import paths in composed resolver
- Enhanced SalesEntityService with comprehensive documentation
- Added detailed JSDoc comments for SalesService and SalesQueryStrategy
- Introduced comprehensive test coverage for SalesService, SalesQueryStrategy, and SalesResolver
- Improved error handling to return null for failed resolver queries
- Standardized code structure with other similar resolvers

Author: bitbeckers

src/graphql/schemas/resolvers/composed.ts

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

src/graphql/schemas/resolvers/salesResolver.ts

@@ -7,6 +7,13 @@ import type { EntityService } from "./EntityServiceFactory.js";
 import { createEntityService } from "./EntityServiceFactory.js";
 
 export type SaleSelect = Selectable<CachingDatabase["sales"]>;
+
+/**
+ * Service for handling sales-related database operations.
+ * This service provides functionality to:
+ * 1. Query multiple sales with filtering and pagination
+ * 2. Query a single sale by ID
+ */
 @injectable()
 export class SalesService {
   private entityService: EntityService<CachingDatabase["sales"], GetSalesArgs>;
@@ -19,10 +26,26 @@ export class SalesService {
     >("sales", "SalesEntityService", kyselyCaching);
   }
 
+  /**
+   * Retrieves multiple sales based on the provided query arguments.
+   *
+   * @param args - Query arguments including where conditions, sorting, and pagination
+   * @returns A promise resolving to an object containing:
+   *          - data: Array of sales matching the query criteria
+   *          - count: Total number of matching sales
+   * @throws {Error} If the database query fails
+   */
   async getSales(args: GetSalesArgs) {
     return this.entityService.getMany(args);
   }
 
+  /**
+   * Retrieves a single sale based on the provided query arguments.
+   *
+   * @param args - Query arguments including where conditions to identify the sale
+   * @returns A promise resolving to the matching sale
+   * @throws {Error} If the database query fails
+   */
   async getSale(args: GetSalesArgs) {
     return this.entityService.getSingle(args);
   }

src/services/database/entities/SalesEntityService.ts

@@ -2,16 +2,37 @@ import { Kysely } from "kysely";
 import { CachingDatabase } from "../../../types/kyselySupabaseCaching.js";
 import { QueryStrategy } from "./QueryStrategy.js";
 
+/**
+ * Query strategy for handling sales-related database operations.
+ * This strategy provides functionality to:
+ * 1. Build queries for fetching sales data
+ * 2. Build queries for counting sales
+ *
+ * The strategy is used by the SalesService to construct and execute database queries.
+ * It extends the base QueryStrategy class to provide sales-specific query building.
+ */
 export class SalesQueryStrategy extends QueryStrategy<
   CachingDatabase,
   "sales"
 > {
   protected readonly tableName = "sales" as const;
 
+  /**
+   * Builds a query to fetch sales data.
+   *
+   * @param db - The Kysely database instance
+   * @returns A query builder configured to select all fields from the sales table
+   */
   buildDataQuery(db: Kysely<CachingDatabase>) {
     return db.selectFrom(this.tableName).selectAll();
   }
 
+  /**
+   * Builds a query to count sales.
+   *
+   * @param db - The Kysely database instance
+   * @returns A query builder configured to count all rows in the sales table
+   */
   buildCountQuery(db: Kysely<CachingDatabase>) {
     return db.selectFrom(this.tableName).select((eb) => {
       return eb.fn.countAll().as("count");

src/services/database/strategies/SalesQueryStrategy.ts

@@ -0,0 +1,119 @@
+import { inject, injectable } from "tsyringe";
+import { Args, FieldResolver, Query, Resolver, Root } from "type-graphql";
+import { HypercertsService } from "../../database/entities/HypercertsEntityService.js";
+import { SalesService } from "../../database/entities/SalesEntityService.js";
+import { GetSalesArgs } from "../../../graphql/schemas/args/salesArgs.js";
+import {
+  Sale,
+  GetSalesResponse,
+} from "../../../graphql/schemas/typeDefs/salesTypeDefs.js";
+
+/**
+ * Resolver for handling sales-related GraphQL queries and field resolvers.
+ * This resolver provides functionality to:
+ * 1. Query sales with filtering and pagination
+ * 2. Resolve the associated hypercert for a sale
+ */
+@injectable()
+@Resolver(() => Sale)
+class SalesResolver {
+  constructor(
+    @inject(SalesService)
+    private salesService: SalesService,
+    @inject(HypercertsService)
+    private hypercertsService: HypercertsService,
+  ) {}
+
+  /**
+   * Query resolver for fetching sales with optional filtering and pagination.
+   *
+   * @param args - Query arguments including where conditions, sorting, and pagination
+   * @returns A promise resolving to:
+   *          - Object containing sales data and count if successful
+   *          - null if an error occurs during retrieval
+   *
+   * @example
+   * ```graphql
+   * query {
+   *   sales(
+   *     where: { hypercert_id: { eq: "123" } }
+   *     first: 10
+   *     offset: 0
+   *   ) {
+   *     data {
+   *       id
+   *       buyer
+   *       seller
+   *       hypercert {
+   *         id
+   *       }
+   *     }
+   *     count
+   *   }
+   * }
+   * ```
+   */
+  @Query(() => GetSalesResponse)
+  async sales(@Args() args: GetSalesArgs) {
+    try {
+      return await this.salesService.getSales(args);
+    } catch (e) {
+      console.error(
+        `[SalesResolver::sales] Error fetching sales: ${(e as Error).message}`,
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Field resolver for the hypercert associated with a sale.
+   * This resolver is called automatically when the hypercert field is requested in a query.
+   *
+   * @param sale - The sale for which to resolve the associated hypercert
+   * @returns A promise resolving to:
+   *          - The associated hypercert if found
+   *          - null if:
+   *            - No hypercert_id is available
+   *            - The hypercert is not found
+   *            - An error occurs during retrieval
+   *
+   * @example
+   * ```graphql
+   * query {
+   *   sales {
+   *     data {
+   *       id
+   *       hypercert {
+   *         id
+   *         hypercert_id
+   *       }
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  @FieldResolver({ nullable: true })
+  async hypercert(@Root() sale: Sale) {
+    if (!sale.hypercert_id) {
+      console.warn(`[SalesResolver::hypercert_id] Missing hypercert_id`);
+      return null;
+    }
+
+    try {
+      return await this.hypercertsService.getHypercert({
+        where: {
+          hypercert_id: {
+            eq: sale.hypercert_id,
+          },
+        },
+      });
+    } catch (e) {
+      console.error(
+        `[SalesResolver::hypercert] Error fetching hypercert: ${(e as Error).message}`,
+      );
+      return null;
+    }
+  }
+}
+
+export { SalesResolver };

src/services/graphql/resolvers/salesResolver.ts

@@ -0,0 +1,108 @@
+import { faker } from "@faker-js/faker";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { GetSalesArgs } from "../../../../src/graphql/schemas/args/salesArgs.js";
+import type { Sale } from "../../../../src/graphql/schemas/typeDefs/salesTypeDefs.js";
+import { SalesService } from "../../../../src/services/database/entities/SalesEntityService.js";
+import { generateHypercertId } from "../../../utils/testUtils.js";
+
+const mockEntityService = {
+  getMany: vi.fn(),
+  getSingle: vi.fn(),
+};
+
+// Mock the createEntityService function
+vi.mock(
+  "../../../../src/services/database/entities/EntityServiceFactory.js",
+  () => ({
+    createEntityService: () => mockEntityService,
+  }),
+);
+
+describe("SalesService", () => {
+  let service: SalesService;
+
+  beforeEach(() => {
+    service = new SalesService();
+  });
+
+  describe("getSales", () => {
+    it("should return sales for given arguments", async () => {
+      // Arrange
+      const args: GetSalesArgs = {
+        where: {
+          hypercert_id: { eq: generateHypercertId() },
+        },
+      };
+      const expectedResult = {
+        data: [
+          {
+            id: faker.string.uuid(),
+            hypercert_id: generateHypercertId(),
+            buyer: faker.string.alphanumeric(42),
+            seller: faker.string.alphanumeric(42),
+            currency: faker.string.alphanumeric(42),
+            collection: faker.string.alphanumeric(42),
+            transaction_hash: faker.string.alphanumeric(66),
+          } as Sale,
+        ],
+        count: 1,
+      };
+      mockEntityService.getMany.mockResolvedValue(expectedResult);
+
+      // Act
+      const result = await service.getSales(args);
+
+      // Assert
+      expect(mockEntityService.getMany).toHaveBeenCalledWith(args);
+      expect(result).toEqual(expectedResult);
+    });
+
+    it("should handle errors from entity service", async () => {
+      // Arrange
+      const args: GetSalesArgs = {};
+      const error = new Error("Entity service error");
+      mockEntityService.getMany.mockRejectedValue(error);
+
+      // Act & Assert
+      await expect(service.getSales(args)).rejects.toThrow(error);
+    });
+  });
+
+  describe("getSale", () => {
+    it("should return a single sale for given arguments", async () => {
+      // Arrange
+      const args: GetSalesArgs = {
+        where: {
+          id: { eq: faker.string.uuid() },
+        },
+      };
+      const expectedResult = {
+        id: faker.string.uuid(),
+        hypercert_id: generateHypercertId(),
+        buyer: faker.string.alphanumeric(42),
+        seller: faker.string.alphanumeric(42),
+        currency: faker.string.alphanumeric(42),
+        collection: faker.string.alphanumeric(42),
+        transaction_hash: faker.string.alphanumeric(66),
+      } as Sale;
+      mockEntityService.getSingle.mockResolvedValue(expectedResult);
+
+      // Act
+      const result = await service.getSale(args);
+
+      // Assert
+      expect(mockEntityService.getSingle).toHaveBeenCalledWith(args);
+      expect(result).toEqual(expectedResult);
+    });
+
+    it("should handle errors from entity service", async () => {
+      // Arrange
+      const args: GetSalesArgs = {};
+      const error = new Error("Entity service error");
+      mockEntityService.getSingle.mockRejectedValue(error);
+
+      // Act & Assert
+      await expect(service.getSale(args)).rejects.toThrow(error);
+    });
+  });
+});