feat: events fetcher & indexer client (#4)

# 🤖 Linear

Closes GIT-53 GIT-84 GIT-85

## Description
Implementation of 
- `data-flow` => `EventsFetcher`
- `indexer-client` => `EnvioIndexerClient`

## Checklist before requesting a review

- [x] I have conducted a self-review of my code.
- [x] I have conducted a QA.
- [x] If it is a core feature, I have included comprehensive tests.

packages/data-flow/README.md

@@ -0,0 +1,45 @@
+# @grants-stack-indexer/data-flow
+
+Is a library that provides the core components of the processing pipeline for gitcoin grants-stack-indexer.
+
+## Available Scripts
+
+Available scripts that can be run using `pnpm`:
+
+| Script        | Description                                             |
+| ------------- | ------------------------------------------------------- |
+| `build`       | Build library using tsc                                 |
+| `check-types` | Check types issues using tsc                            |
+| `clean`       | Remove `dist` folder                                    |
+| `lint`        | Run ESLint to check for coding standards                |
+| `lint:fix`    | Run linter and automatically fix code formatting issues |
+| `format`      | Check code formatting and style using Prettier          |
+| `format:fix`  | Run formatter and automatically fix issues              |
+| `test`        | Run tests using vitest                                  |
+| `test:cov`    | Run tests with coverage report                          |
+
+## Usage
+
+### Importing the Package
+
+You can import the package in your TypeScript or JavaScript files as follows:
+
+```typescript
+import { EventsFetcher } from "@grants-stack-indexer/data-flow";
+```
+
+### Example
+
+```typescript
+const eventsFetcher = new EventsFetcher(indexerClient);
+
+const chainId = 1;
+const blockNumber = 1000;
+const logIndex = 0;
+
+const result = await eventsFetcher.fetcEventsByBlockNumberAndLogIndex(
+    chainId,
+    blockNumber,
+    logIndex,
+);
+```

packages/data-flow/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "@grants-stack-indexer/data-flow",
+    "version": "0.0.1",
+    "private": true,
+    "description": "",
+    "license": "MIT",
+    "author": "Wonderland",
+    "type": "module",
+    "main": "./dist/src/index.js",
+    "types": "./dist/src/index.d.ts",
+    "directories": {
+        "src": "src"
+    },
+    "files": [
+        "dist/*",
+        "package.json",
+        "!**/*.tsbuildinfo"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "check-types": "tsc --noEmit -p ./tsconfig.json",
+        "clean": "rm -rf dist/",
+        "format": "prettier --check \"{src,test}/**/*.{js,ts,json}\"",
+        "format:fix": "prettier --write \"{src,test}/**/*.{js,ts,json}\"",
+        "lint": "eslint \"{src,test}/**/*.{js,ts,json}\"",
+        "lint:fix": "pnpm lint --fix",
+        "test": "vitest run --config vitest.config.ts --passWithNoTests",
+        "test:cov": "vitest run --config vitest.config.ts --coverage"
+    },
+    "dependencies": {
+        "@grants-stack-indexer/indexer-client": "workspace:*",
+        "@grants-stack-indexer/shared": "workspace:*",
+        "viem": "2.21.19"
+    }
+}

packages/data-flow/src/eventsFetcher.ts

@@ -0,0 +1,22 @@
+import { IIndexerClient } from "@grants-stack-indexer/indexer-client";
+import { AnyProtocolEvent } from "@grants-stack-indexer/shared";
+
+import { IEventsFetcher } from "./interfaces/index.js";
+
+export class EventsFetcher implements IEventsFetcher {
+    constructor(private indexerClient: IIndexerClient) {}
+    /* @inheritdoc */
+    async fetchEventsByBlockNumberAndLogIndex(
+        chainId: bigint,
+        blockNumber: bigint,
+        logIndex: number,
+        limit: number = 100,
+    ): Promise<AnyProtocolEvent[]> {
+        return await this.indexerClient.getEventsAfterBlockNumberAndLogIndex(
+            chainId,
+            blockNumber,
+            logIndex,
+            limit,
+        );
+    }
+}

packages/data-flow/src/external.ts

@@ -0,0 +1 @@
+export { EventsFetcher } from "./internal.js";

packages/data-flow/src/index.ts

@@ -0,0 +1 @@
+export * from "./external.js";

packages/data-flow/src/interfaces/index.ts

@@ -0,0 +1,20 @@
+import { AnyProtocolEvent } from "@grants-stack-indexer/shared";
+
+/**
+ * Interface for the events fetcher
+ */
+export interface IEventsFetcher {
+    /**
+     * Fetch the events by block number and log index for a chain
+     * @param chainId id of the chain
+     * @param blockNumber block number to fetch events from
+     * @param logIndex log index in the block to fetch events from
+     * @param limit limit of events to fetch
+     */
+    fetchEventsByBlockNumberAndLogIndex(
+        chainId: bigint,
+        blockNumber: bigint,
+        logIndex: number,
+        limit?: number,
+    ): Promise<AnyProtocolEvent[]>;
+}

packages/data-flow/src/internal.ts

@@ -0,0 +1 @@
+export * from "./eventsFetcher.js";

packages/data-flow/test/unit/eventsFetcher.spec.ts

@@ -0,0 +1,78 @@
+import { beforeEach, describe, expect, it, Mocked, vi } from "vitest";
+
+import { IIndexerClient } from "@grants-stack-indexer/indexer-client";
+import { AnyProtocolEvent } from "@grants-stack-indexer/shared";
+
+import { EventsFetcher } from "../../src/eventsFetcher.js";
+
+describe("EventsFetcher", () => {
+    let indexerClientMock: Mocked<IIndexerClient>;
+    let eventsFetcher: EventsFetcher;
+
+    beforeEach(() => {
+        indexerClientMock = {
+            getEventsAfterBlockNumberAndLogIndex: vi.fn(),
+        };
+
+        eventsFetcher = new EventsFetcher(indexerClientMock);
+    });
+
+    it("should fetch events by block number and log index", async () => {
+        const mockEvents: AnyProtocolEvent[] = [
+            {
+                chain_id: 1,
+                block_number: 12345,
+                block_timestamp: 123123123,
+                contract_name: "Allo",
+                event_name: "PoolCreated",
+                src_address: "0x1234567890123456789012345678901234567890",
+                log_index: 0,
+                params: { contractAddress: "0x1234" },
+            },
+            {
+                chain_id: 1,
+                block_number: 12345,
+                block_timestamp: 123123123,
+                contract_name: "Allo",
+                event_name: "PoolCreated",
+                src_address: "0x1234567890123456789012345678901234567890",
+                log_index: 0,
+                params: { contractAddress: "0x1234" },
+            },
+        ];
+        const chainId = 1n;
+        const blockNumber = 1000n;
+        const logIndex = 0;
+        const limit = 100;
+
+        indexerClientMock.getEventsAfterBlockNumberAndLogIndex.mockResolvedValue(mockEvents);
+
+        const result = await eventsFetcher.fetchEventsByBlockNumberAndLogIndex(
+            chainId,
+            blockNumber,
+            logIndex,
+        );
+
+        expect(indexerClientMock.getEventsAfterBlockNumberAndLogIndex).toHaveBeenCalledWith(
+            chainId,
+            blockNumber,
+            logIndex,
+            limit,
+        );
+        expect(result).toEqual(mockEvents);
+    });
+
+    it("should handle errors thrown by indexer client", async () => {
+        const chainId = 1n;
+        const blockNumber = 1000n;
+        const logIndex = 0;
+
+        indexerClientMock.getEventsAfterBlockNumberAndLogIndex.mockRejectedValue(
+            new Error("Network error"),
+        );
+
+        await expect(
+            eventsFetcher.fetchEventsByBlockNumberAndLogIndex(chainId, blockNumber, logIndex),
+        ).rejects.toThrow("Network error");
+    });
+});

packages/data-flow/tsconfig.build.json

@@ -0,0 +1,13 @@
+/* Based on total-typescript no-dom library config */
+/* https://github.com/total-typescript/tsconfig */
+{
+    "extends": "../../tsconfig.build.json",
+    "compilerOptions": {
+        "composite": true,
+        "declarationMap": true,
+        "declaration": true,
+        "outDir": "dist"
+    },
+    "include": ["src/**/*"],
+    "exclude": ["node_modules", "dist", "tests"]
+}

packages/data-flow/tsconfig.json

@@ -0,0 +1,4 @@
+{
+    "extends": "../../tsconfig.json",
+    "include": ["src/**/*"]
+}

packages/data-flow/vitest.config.ts

@@ -0,0 +1,22 @@
+import path from "path";
+import { configDefaults, defineConfig } from "vitest/config";
+
+export default defineConfig({
+    test: {
+        globals: true, // Use Vitest's global API without importing it in each file
+        environment: "node", // Use the Node.js environment
+        include: ["test/**/*.spec.ts"], // Include test files
+        exclude: ["node_modules", "dist"], // Exclude certain directories
+        coverage: {
+            provider: "v8",
+            reporter: ["text", "json", "html"], // Coverage reporters
+            exclude: ["node_modules", "dist", "src/index.ts", ...configDefaults.exclude], // Files to exclude from coverage
+        },
+    },
+    resolve: {
+        alias: {
+            // Setup path alias based on tsconfig paths
+            "@": path.resolve(__dirname, "src"),
+        },
+    },
+});

packages/indexer-client/README.md

@@ -0,0 +1,36 @@
+# @grants-stack-indexer/indexer-client
+
+Is library for interacting with blockchain event indexing services.
+
+## Available Scripts
+
+Available scripts that can be run using `pnpm`:
+
+| Script        | Description                                             |
+| ------------- | ------------------------------------------------------- |
+| `build`       | Build library using tsc                                 |
+| `check-types` | Check types issues using tsc                            |
+| `clean`       | Remove `dist` folder                                    |
+| `lint`        | Run ESLint to check for coding standards                |
+| `lint:fix`    | Run linter and automatically fix code formatting issues |
+| `format`      | Check code formatting and style using Prettier          |
+| `format:fix`  | Run formatter and automatically fix issues              |
+| `test`        | Run tests using vitest                                  |
+| `test:cov`    | Run tests with coverage report                          |
+
+## Usage
+
+### Importing the Package
+
+You can import the package in your TypeScript or JavaScript files as follows:
+
+```typescript
+import { EnvioIndexerClient } from "@grants-stack-indexer/indexer-client";
+```
+
+### Example
+
+```typescript
+const envioIndexerClient = new EnvioIndexerClient("http://example.com/graphql", "secret");
+await envioIndexerClient.getEventsByBlockNumberAndLogIndex(1, 12345, 0);
+```

packages/indexer-client/package.json

@@ -0,0 +1,34 @@
+{
+    "name": "@grants-stack-indexer/indexer-client",
+    "version": "0.0.1",
+    "private": true,
+    "description": "",
+    "license": "MIT",
+    "author": "Wonderland",
+    "type": "module",
+    "main": "./dist/src/index.js",
+    "types": "./dist/src/index.d.ts",
+    "directories": {
+        "src": "src"
+    },
+    "files": [
+        "dist/*",
+        "package.json",
+        "!**/*.tsbuildinfo"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "check-types": "tsc --noEmit -p ./tsconfig.json",
+        "clean": "rm -rf dist/",
+        "format": "prettier --check \"{src,test}/**/*.{js,ts,json}\"",
+        "format:fix": "prettier --write \"{src,test}/**/*.{js,ts,json}\"",
+        "lint": "eslint \"{src,test}/**/*.{js,ts,json}\"",
+        "lint:fix": "pnpm lint --fix",
+        "test": "vitest run --config vitest.config.ts --passWithNoTests",
+        "test:cov": "vitest run --config vitest.config.ts --coverage"
+    },
+    "dependencies": {
+        "@grants-stack-indexer/shared": "workspace:*",
+        "graphql-request": "7.1.0"
+    }
+}

packages/indexer-client/src/exceptions/index.ts

@@ -0,0 +1,2 @@
+export * from "./invalidIndexerResponse.exception.js";
+export * from "./indexerClientError.exception.js";

packages/indexer-client/src/exceptions/indexerClientError.exception.ts

@@ -0,0 +1,6 @@
+export class IndexerClientError extends Error {
+    constructor(message: string) {
+        super(`Indexer client error - ${message}`);
+        this.name = "IndexerClientError";
+    }
+}

packages/indexer-client/src/exceptions/invalidIndexerResponse.exception.ts

@@ -0,0 +1,6 @@
+export class InvalidIndexerResponse extends Error {
+    constructor(response: string) {
+        super(`Indexer response is invalid - ${response}`);
+        this.name = "InvalidIndexerResponse";
+    }
+}

packages/indexer-client/src/external.ts

@@ -0,0 +1,3 @@
+export type { IIndexerClient } from "./internal.js";
+
+export { EnvioIndexerClient } from "./internal.js";

packages/indexer-client/src/index.ts

@@ -0,0 +1 @@
+export * from "./external.js";

packages/indexer-client/src/interfaces/index.ts

@@ -0,0 +1 @@
+export * from "./indexerClient.js";

packages/indexer-client/src/interfaces/indexerClient.ts

@@ -0,0 +1,20 @@
+import { AnyProtocolEvent } from "@grants-stack-indexer/shared";
+
+/**
+ * Interface for the indexer client
+ */
+export interface IIndexerClient {
+    /**
+     * Get the events by block number and log index from the indexer service
+     * @param chainId Id of the chain
+     * @param fromBlock Block number to start fetching events from
+     * @param logIndex Log index in the block
+     * @param limit Limit of events to fetch
+     */
+    getEventsAfterBlockNumberAndLogIndex(
+        chainId: bigint,
+        fromBlock: bigint,
+        logIndex: number,
+        limit?: number,
+    ): Promise<AnyProtocolEvent[]>;
+}

packages/indexer-client/src/internal.ts

@@ -0,0 +1,3 @@
+export * from "./exceptions/index.js";
+export * from "./interfaces/index.js";
+export * from "./providers/index.js";