Import Grants Stack Data Client

.github/workflows/grants-stack-data-client.yml

@@ -0,0 +1,45 @@
+name: Data client - Lint & Test & Typecheck
+on:
+  push:
+    branches:
+      - main
+      - release
+  pull_request:
+    branches:
+      - "**"
+jobs:
+  lint-test-typecheck:
+    concurrency: ci-data-client-${{ github.head_ref || github.run_id }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 1
+
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 8
+
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          cache: 'pnpm'
+
+      - name: Install Dependencies
+        run: |
+          pnpm install
+
+      # TODO
+      # - name: Lint Data Client
+      #   run: |
+      #     pnpm dc-lint
+
+      - name: Test Data Client
+        run: |
+          pnpm dc-test
+
+      # TODO    
+      # - name: Typecheck Explorer
+      #   run: |
+      #     pnpm ge-typecheck

.gitignore

@@ -6,4 +6,7 @@ node_modules
 .turbo
 .husky/
 .vercel
-/packages/verify-env/dist/
+dist/
+coverage/
+.eslintcache
+

lefthook.yml

@@ -27,12 +27,20 @@ pre-commit:
       run: pnpm --filter "grant-explorer" lint:local {staged_files}
       stage_fixed: true
 
+    lint-data-client:
+      root: "packages/grants-stack-data-client"
+      glob: "**/*.{js,ts,jsx,tsx}"
+      # TODO: harmonize command name with others
+      run: pnpm --filter "grants-stack-data-client" lint {staged_files}
+      stage_fixed: true
+
+
 pre-push:
   parallel: true
   commands:
     typecheck:
-      run: turbo run typecheck
+      run: pnpm turbo run typecheck
     build:
-      run: turbo run build
+      run: pnpm turbo run build
     test:
-      run: turbo run test
+      run: pnpm turbo run test

package.json

@@ -31,7 +31,9 @@
     "b-test": "pnpm test --filter=builder",
     "b-typecheck": "turbo run typecheck --filter=builder",
     "c-test": "turbo run test --filter=common",
-    "ve-test": "turbo run test --filter=verify-env"
+    "ve-test": "turbo run test --filter=verify-env",
+    "// data client script": "====== packages/builder specific ======",
+    "dc-test": "turbo run test --filter=grants-stack-data-client"
   },
   "devDependencies": {
     "@commitlint/cli": "^17.7.1",

packages/common/package.json

@@ -16,7 +16,7 @@
     "dompurify": "^2.4.3",
     "ethers": "^5.6.5",
     "framer-motion": "^10.12.7",
-    "grants-stack-data-client": "github:gitcoinco/grants-stack-data-client",
+    "grants-stack-data-client": "workspace:*",
     "markdown-it": "^13.0.1",
     "react": "^18.2.0",
     "react-hook-form": "^7.42.1",

packages/grants-stack-data-client/.eslintrc.json

@@ -0,0 +1,26 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "plugins": [
+    "prettier",
+    "@typescript-eslint",
+    "import"
+  ],
+  "extends": [
+    "eslint:recommended",
+    "prettier",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "env": {
+    "node": true
+  },
+  "rules": {
+    "@typescript-eslint/no-unused-vars": [
+      1,
+      {
+        "argsIgnorePattern": "^_"
+      }
+    ],
+    "import/no-default-export": "error"
+  }
+}

packages/grants-stack-data-client/.prettierrc.json

@@ -0,0 +1 @@
+{}

packages/grants-stack-data-client/README.md

@@ -0,0 +1,30 @@
+## Development
+
+To run tests in watch mode:
+
+```sh
+pnpm run test:watch
+```
+
+To update types from the [search service](https://gitcoin-search-dev.fly.dev/docs), run:
+
+```sh
+pnpm run generate:openapi
+```
+
+## Example
+
+```ts
+import { GrantsStackDataClient } from "grants-stack-data-client";
+
+const gsData = new GrantsStackDataClient({
+  baseUrl: "https://gitcoin-search-dev.fly.dev",
+});
+
+const { applications, pagination } = await gsData.query({
+  type: "applications-paginated",
+  page: 0,
+});
+```
+
+For more examples, see `src/grants-stack-data-client.test.ts`.

packages/grants-stack-data-client/openapitools.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json",
+  "spaces": 2,
+  "generator-cli": {
+    "version": "7.0.1"
+  }
+}

packages/grants-stack-data-client/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "grants-stack-data-client",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "dev": "tsx watch -r dotenv-flow/config src/index.ts",
+    "start": "node -r dotenv-flow/config dist/index.js",
+    "lint": "eslint --cache --max-warnings=0",
+    "lint:fix": "eslint --cache --max-warnings=0 --fix",
+    "lint:all": "eslint --cache --max-warnings=0 src",
+    "generate:openapi": "openapi-generator-cli generate -i https://gitcoin-search-dev.fly.dev/openapi.json -o src/openapi-search-client -g typescript-fetch --additional-properties=importFileExtension=.js",
+    "generate:openapi:local": "openapi-generator-cli generate -i http://localhost:8000/openapi.json -o src/openapi-search-client -g typescript-fetch --additional-properties=importFileExtension=.js",
+    "format": "prettier --write",
+    "lint:unused-exports": "ts-unused-exports ./tsconfig.json --maxIssues=0",
+    "test": "vitest run --coverage",
+    "build": "tsc",
+    "test:watch": "vitest watch",
+    "typecheck": "tsc --noEmit",
+    "typecheck:watch": "tsc --noEmit --watch",
+    "todo": "leasot 'src/**/*.ts'",
+    "prepare": "tsc"
+  },
+  "devDependencies": {
+    "@openapitools/openapi-generator-cli": "^2.7.0",
+    "@tsconfig/node18": "^18.2.2",
+    "@types/debug": "^4.1.8",
+    "@types/knuth-shuffle-seeded": "^1.0.1",
+    "@types/node": "^20.6.2",
+    "@typescript-eslint/eslint-plugin": "^6.7.0",
+    "@typescript-eslint/parser": "^6.7.0",
+    "@vitest/coverage-v8": "^0.34.4",
+    "eslint": "^8.49.0",
+    "eslint-config-prettier": "^9.0.0",
+    "eslint-plugin-import": "^2.28.1",
+    "eslint-plugin-prettier": "^5.0.0",
+    "leasot": "^13.3.0",
+    "lefthook": "^1.4.11",
+    "prettier": "^3.0.3",
+    "ts-unused-exports": "^10.0.1",
+    "tsx": "^3.12.10",
+    "typescript": "^5.2.2",
+    "vitest": "^0.34.4"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "cross-fetch": "^4.0.0",
+    "debug": "^4.3.4",
+    "dotenv-flow": "^3.3.0",
+    "knuth-shuffle-seeded": "^1.0.6",
+    "ts-essentials": "^9.4.1",
+    "zod": "^3.22.2"
+  }
+}

packages/grants-stack-data-client/src/grants-stack-data-client.ts

@@ -0,0 +1,141 @@
+import shuffle from "knuth-shuffle-seeded";
+import { UnreachableCaseError } from "ts-essentials";
+import _fetch from "cross-fetch";
+import {
+  DataClientInteraction,
+  ExtractQuery,
+  ExtractResponse,
+} from "./grants-stack-data-client.types.js";
+import {
+  ApplicationSummary,
+  DefaultApi as SearchApi,
+  Configuration as SearchApiConfiguration,
+} from "./openapi-search-client/index.js";
+
+export class GrantsStackDataClient {
+  private pageSize: number;
+  private searchApi: SearchApi;
+
+  constructor({
+    fetch,
+    baseUrl,
+    pagination,
+  }: {
+    fetch?: typeof _fetch;
+    pagination?: { pageSize: number };
+    baseUrl: string;
+  }) {
+    this.searchApi = new SearchApi(
+      new SearchApiConfiguration({
+        fetchApi: fetch,
+        basePath: baseUrl,
+      }),
+    );
+    this.pageSize = pagination?.pageSize ?? 10;
+  }
+
+  async query(
+    q: ExtractQuery<DataClientInteraction, "applications-by-refs">,
+  ): Promise<ExtractResponse<DataClientInteraction, "applications-by-refs">>;
+  async query(
+    q: ExtractQuery<DataClientInteraction, "applications-paginated">,
+  ): Promise<ExtractResponse<DataClientInteraction, "applications-paginated">>;
+  async query(
+    q: ExtractQuery<DataClientInteraction, "applications-search">,
+  ): Promise<ExtractResponse<DataClientInteraction, "applications-search">>;
+  async query(
+    q: DataClientInteraction["query"],
+  ): Promise<DataClientInteraction["response"]> {
+    switch (q.type) {
+      case "applications-search": {
+        const { results } = await this.searchApi.searchSearchGet({
+          q: q.queryString,
+        });
+
+        // TODO consider unifying with /applications endpoint
+        const pageStart = q.page * this.pageSize;
+        const pageEnd = pageStart + this.pageSize;
+        const page = results.slice(pageStart, pageEnd);
+
+        return {
+          results: page,
+          pagination: {
+            currentPage: q.page,
+            totalPages: Math.ceil(results.length / this.pageSize),
+            totalItems: results.length,
+          },
+        };
+      }
+
+      case "applications-by-refs": {
+        const { applicationSummaries } =
+          await this.searchApi.getApplicationsApplicationsGet();
+
+        return {
+          applications: applicationSummaries.filter((a) =>
+            q.refs.includes(a.applicationRef),
+          ),
+        };
+      }
+
+      case "applications-paginated": {
+        const { applicationSummaries } =
+          await this.searchApi.getApplicationsApplicationsGet();
+
+        const pageStart = q.page * this.pageSize;
+        const pageEnd = pageStart + this.pageSize;
+
+        let filteredApplicationSummaries: ApplicationSummary[];
+        if (q.filter === undefined) {
+          filteredApplicationSummaries = applicationSummaries;
+        } else if (q.filter.type === "chain") {
+          const { chainId } = q.filter;
+          filteredApplicationSummaries = applicationSummaries.filter(
+            (a) => a.chainId === chainId,
+          );
+        } else if (q.filter.type === "refs") {
+          const { refs } = q.filter;
+          filteredApplicationSummaries = applicationSummaries.filter((a) =>
+            refs.includes(a.applicationRef),
+          );
+        } else {
+          throw new Error(`Unreachable brank invoked`);
+        }
+
+        let orderedApplicationSummaries: ApplicationSummary[];
+        if (q.order === undefined) {
+          orderedApplicationSummaries = filteredApplicationSummaries;
+        } else if (q.order.type === "random") {
+          orderedApplicationSummaries = shuffle(
+            filteredApplicationSummaries,
+            q.order.seed,
+          );
+        } else {
+          const { direction, type: property } = q.order;
+          orderedApplicationSummaries = [...filteredApplicationSummaries].sort(
+            (a, b) =>
+              direction === "asc"
+                ? a[property] - b[property]
+                : b[property] - a[property],
+          );
+        }
+
+        const page = orderedApplicationSummaries.slice(pageStart, pageEnd);
+
+        return {
+          applications: page,
+          pagination: {
+            currentPage: q.page,
+            totalPages: Math.ceil(
+              filteredApplicationSummaries.length / this.pageSize,
+            ),
+            totalItems: filteredApplicationSummaries.length,
+          },
+        };
+      }
+
+      default:
+        throw new UnreachableCaseError(q);
+    }
+  }
+}