Develop

.env.template

@@ -30,8 +30,5 @@ SENTRY_AUTH_TOKEN="" #disabled for local
 # https://www.alchemy.com/
 ALCHEMY_API_KEY=""
 
-# https://www.infura.io/
-INFURA_API_KEY=""
-
 # https://drpc.org/
 DRPC_API_KEY=""

.github/workflows/ci-test-unit.yml

@@ -18,14 +18,15 @@ jobs:
 
       ALCHEMY_API_KEY: ${{ secrets.ALCHEMY_API_KEY }}
       DRPC_API_KEY: "test"
-      INFURA_API_KEY: "test"
       FILECOIN_API_KEY: "test"
 
       INDEXER_ENVIRONMENT: "test"
 
       CACHING_DATABASE_URL: "https://test.supabase.com"
       DATA_DATABASE_URL: "https://test.supabase.com"
 
+      ENABLE_CRON_JOBS: "false"
+
     permissions:
       # Required to checkout the code
       contents: read

.gitignore

@@ -36,9 +36,9 @@ yarn-error.log*
 *.tsbuildinfo
 next-env.d.ts
 
-# generated graphql files
-src/generated/
-
 dist
 .rollup.cache
 .idea
+
+# generated swagger files
+src/__generated__/

README.md

@@ -28,10 +28,10 @@ The API implements a fallback to the first available RPC. You can set the RPCs i
 
 ### Supabase
 
-* Install Docker
-* `git submodule init`
-* `git submodule update --remote`
-* `pnpm supabase:start:all`
+- Install Docker
+- `git submodule init`
+- `git submodule update --remote`
+- `pnpm supabase:start:all`
 
 This will spin up 2 Supabase instances in Docker, one for the indexer service (caching) and one for the data service (static data) which are both exposed by the API.
 
@@ -43,21 +43,21 @@ From both instances, you can get their respective keys and add them to the env v
 
 This will run a live production instance by running `swc` to compile the code and `nodemon` to restart the server on changes.
 
-You can then find the API at `localhost:4000/spec` (Swagger instance) and the GraphQL at `localhost:4000/v1/graphql`
+You can then find the API at `localhost:4000/spec` (Swagger instance) and the GraphQL at `localhost:4000/v2/graphql`
 
 ## Deployments
 
 Production: `https://api.hypercerts.org/`
 Staging: `https://staging-api.hypercerts.org`
 
 `/spec` - Swagger instance documenting the API and exposing a playground to experiment with the endpoints
-`/v1/graphql` - GraphQL API to access hypercerts data like claims, fractions, attestations, allow lists
+`/v2/graphql` - GraphQL API to access hypercerts data like claims, fractions, attestations, allow lists
 
 ## Scripts
 
 - `dev`: Starts the development server using `nodemon`, which will automatically restart the server whenever you save a file that the server uses.
 - `build`: Denerates the OpenAPI specification and routes using `tsoa`, and then compiles the TypeScript code into JavaScript using `swc`. The compiled code is output to the `dist` directory.
-- `start`: Starts the application in production mode. 
+- `start`: Starts the application in production mode.
 - `lint`: Runs `eslint` on the codebase to check for linting errors.
 - `test`: Runs tests using `vitest`
 
@@ -86,38 +86,38 @@ The API also provides an upload and validation endpoint for hypercert and allow
 graph TB
     Client[Client Applications]
     API[Hypercerts API :4000]
-    
+
     subgraph "API Endpoints"
         Swagger["/spec\nSwagger Documentation"]
-        GraphQL["/v1/graphql\nGraphQL Endpoint"]
+        GraphQL["/v2/graphql\nGraphQL Endpoint"]
         Upload["Upload & Validation\nEndpoints"]
     end
-    
+
     subgraph "Data Services"
         Static[("Static Data Service\n(Supabase DB)\n- User Data\n- Collections\n- Signed Orders")]
         Indexer[("Indexer Service\n(Supabase DB)\n- On-chain Data\n- IPFS Data")]
     end
-    
+
     subgraph "External Services"
         IPFS[(IPFS\nMetadata Storage)]
         Blockchain[(Blockchain\nSupported Chains)]
         EAS[(EAS\nAttestations)]
     end
-    
+
     Client --> API
     API --> Swagger
     API --> GraphQL
     API --> Upload
-    
+
     GraphQL --> Static
     GraphQL --> Indexer
     Upload --> IPFS
-    
+
     Indexer --> Blockchain
     Indexer --> IPFS
     Indexer --> EAS
-    
+
     class Swagger,GraphQL,Upload apiEndpoint;
     class Static,Indexer database;
     class IPFS,Blockchain,EAS external;
-```
+```

docs/DEVELOPMENT.md

@@ -0,0 +1,176 @@
+# Development Guide: Implementing a New Entity
+
+This guide explains how to implement a new entity in the Hypercerts API, from type definition to resolver implementation.
+
+## Overview
+
+The Hypercerts API uses a modular architecture where each entity follows a consistent pattern:
+
+1. Type Definition
+2. Query Arguments
+3. Entity Service
+4. Resolver
+
+## Step-by-Step Implementation
+
+### 1. Define Entity Types
+
+Create a new file in `src/graphql/schemas/typeDefs/` for your entity types:
+
+```typescript
+// src/graphql/schemas/typeDefs/yourEntityTypeDefs.ts
+import { Field, ObjectType } from "type-graphql";
+import { BaseEntity } from "./baseTypes.js";
+
+@ObjectType()
+export class YourEntity extends BaseEntity {
+  @Field(() => String)
+  name: string;
+
+  @Field(() => String, { nullable: true })
+  description?: string;
+
+  // Add other fields as needed
+}
+
+@ObjectType()
+export class GetYourEntitiesResponse {
+  @Field(() => [YourEntity])
+  data: YourEntity[];
+
+  @Field(() => Int)
+  count: number;
+}
+```
+
+### 2. Define Query Arguments
+
+Create a new file in `src/graphql/schemas/args/` for your query arguments:
+
+```typescript
+// src/graphql/schemas/args/yourEntityArgs.ts
+import { ArgsType } from "type-graphql";
+import { createEntityArgs } from "../../../lib/graphql/createEntityArgs.js";
+import { EntityTypeDefs } from "../typeDefs/typeDefs.js";
+
+// Define your entity fields
+const fields = {
+  name: "string",
+  description: "string",
+  // Add other fields as needed
+} as const;
+
+// Create query arguments
+export const { WhereInput, SortOptions } = createEntityArgs(
+  "YourEntity" as EntityTypeDefs,
+  fields,
+);
+
+@ArgsType()
+export class GetYourEntitiesArgs {
+  first?: number;
+  offset?: number;
+  where?: typeof WhereInput;
+  sortBy?: typeof SortOptions;
+}
+```
+
+### 3. Create Entity Service
+
+Create a new file in `src/services/database/entities/` for your entity service:
+
+```typescript
+// src/services/database/entities/YourEntityService.ts
+import { injectable } from "tsyringe";
+import { createEntityService } from "./EntityServiceFactory.js";
+import { GetYourEntitiesArgs } from "../../../graphql/schemas/args/yourEntityArgs.js";
+import { YourEntity } from "../../../graphql/schemas/typeDefs/yourEntityTypeDefs.js";
+
+@injectable()
+export class YourEntityService {
+  private service = createEntityService<YourEntity, GetYourEntitiesArgs>(
+    "your_entity_table",
+    {
+      // Add any custom query modifiers if needed
+    },
+  );
+
+  async getYourEntities(args: GetYourEntitiesArgs) {
+    return this.service.getMany(args);
+  }
+
+  async getYourEntity(args: GetYourEntitiesArgs) {
+    return this.service.getSingle(args);
+  }
+}
+```
+
+### 4. Implement Resolver
+
+Create a new file in `src/graphql/schemas/resolvers/` for your resolver:
+
+```typescript
+// src/graphql/schemas/resolvers/yourEntityResolver.ts
+import { inject, injectable } from "tsyringe";
+import { Args, Query, Resolver } from "type-graphql";
+import { YourEntityService } from "../../../services/database/entities/YourEntityService.js";
+import { GetYourEntitiesArgs } from "../args/yourEntityArgs.js";
+import {
+  GetYourEntitiesResponse,
+  YourEntity,
+} from "../typeDefs/yourEntityTypeDefs.js";
+
+@injectable()
+@Resolver(() => YourEntity)
+class YourEntityResolver {
+  constructor(
+    @inject(YourEntityService)
+    private yourEntityService: YourEntityService,
+  ) {}
+
+  @Query(() => GetYourEntitiesResponse)
+  async yourEntities(@Args() args: GetYourEntitiesArgs) {
+    return this.yourEntityService.getYourEntities(args);
+  }
+}
+```
+
+### 5. Register the Resolver
+
+Add your resolver to the list of resolvers in `src/graphql/schemas/resolvers/index.ts`:
+
+```typescript
+export * from "./yourEntityResolver.js";
+```
+
+## Best Practices
+
+1. **Type Safety**: Always use TypeScript's type system to ensure type safety across your implementation.
+2. **Consistent Naming**: Follow the existing naming conventions in the codebase.
+3. **Error Handling**: Implement proper error handling in your service and resolver methods.
+4. **Testing**: Write unit tests for your new entity implementation.
+5. **Documentation**: Add JSDoc comments to document your types, methods, and classes.
+
+## Example Implementation
+
+For a complete example, you can look at the implementation of existing entities like `Contract`, `Metadata`, or `AttestationSchema` in the codebase.
+
+## Common Pitfalls
+
+1. **Type Registration**: Ensure all your types are properly registered in the GraphQL schema.
+2. **Dependency Injection**: Use the `@injectable()` and `@inject()` decorators correctly.
+3. **Query Arguments**: Make sure your query arguments match the expected structure.
+4. **Database Schema**: Ensure your database table matches the entity structure.
+
+## Testing Your Implementation
+
+1. Start the development server: `pnpm dev`
+2. Access the GraphQL playground at `http://localhost:4000/v2/graphql`
+3. Test your queries and mutations
+4. Run the test suite: `pnpm test`
+
+## Additional Resources
+
+- [TypeGraphQL Documentation](https://typegraphql.com/)
+- [Kysely Documentation](https://kysely.dev/docs/intro)
+- [Supabase Documentation](https://supabase.com/docs)

eslint.config.js

@@ -9,4 +9,14 @@ export default tseslint.config(
       "@typescript-eslint/no-extraneous-class": "off",
     },
   },
+  {
+    files: ["**/*.test.ts"],
+    rules: {
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { argsIgnorePattern: "^_" },
+      ],
+    },
+  },
 );