enssdk: core client + omnigraph module with gql.tada

.changeset/config.json

@@ -11,6 +11,10 @@
       "ensrainbow",
       "ensapi",
       "fallback-ensapi",
+      "enssdk",
+      "enscli",
+      "enskit",
+      "ensskills",
       "@ensnode/datasources",
       "@ensnode/ensrainbow-sdk",
       "@ensnode/ensdb-sdk",

.changeset/warm-snails-teach.md

@@ -0,0 +1,5 @@
+---
+"enssdk": minor
+---
+
+add core client factory with viem-style extend() and omnigraph module with gql.tada typed queries

.github/workflows/release.yml

@@ -105,6 +105,10 @@ jobs:
               or .name == "@ensnode/namehash-ui"
               or .name == "@ensnode/ponder-sdk"
               or .name == "@ensnode/ponder-subgraph"
+              or .name == "enssdk"
+              or .name == "enskit"
+              or .name == "enscli"
+              or .name == "ensskills"
             ))
 
       - name: Filter Published Packages For Lambdas

.github/workflows/test_ci.yml

@@ -89,6 +89,31 @@ jobs:
       - name: Validate OpenAPI spec with Mintlify
         run: pnpm dlx mint@^4.1.0 openapi-check docs/docs.ensnode.io/ensapi-openapi.json
 
+  graphql-schema-check:
+    name: "GraphQL Schema Check"
+    runs-on: blacksmith-4vcpu-ubuntu-2204
+    steps:
+      - uses: actions/checkout@v6
+      - uses: ./.github/actions/setup_node_environment
+
+      - name: Generate Schemas & Typings
+        run: pnpm generate:gqlschema
+
+      - name: Verify generated files are committed
+        run: |
+          if ! git diff --quiet packages/enssdk/src/omnigraph/generated/; then
+            echo "Error: Generated files are out of sync"
+            echo ""
+            echo "The following generated files differ from what is committed:"
+            git diff --name-status packages/enssdk/src/omnigraph/generated/
+            echo ""
+            echo "To fix, run:"
+            echo "  pnpm generate:gqlschema"
+            echo "Then commit the updated generated files."
+            exit 1
+          fi
+          echo "GraphQL schema generated files are in sync"
+
   integrity-check:
     name: "Integrity Check"
     runs-on: blacksmith-4vcpu-ubuntu-2204

.gitignore

@@ -19,6 +19,7 @@ dist
 
 # Ponder
 generated
+!packages/enssdk/src/omnigraph/generated/
 .ponder
 
 #jetbrains elements

.vscode/settings.json

@@ -1,6 +1,7 @@
 {
-  "typescript.tsdk": "node_modules/typescript/lib",
-  "typescript.preferences.importModuleSpecifier": "non-relative",
+  "js/ts.tsdk.path": "node_modules/typescript/lib",
+  "js/ts.preferences.importModuleSpecifier": "non-relative",
+  "js/ts.tsdk.promptToUseWorkspaceVersion": true,
   "files.insertFinalNewline": true,
   "editor.formatOnSave": true,
   "editor.codeActionsOnSave": {

apps/ensapi/package.json

@@ -18,7 +18,8 @@
     "test:integration": "vitest run --config vitest.integration.config.ts",
     "lint": "biome check --write .",
     "lint:ci": "biome ci",
-    "typecheck": "tsgo --noEmit"
+    "typecheck": "tsgo --noEmit",
+    "generate:gqlschema": "tsx src/graphql-api/lib/write-graphql-schema.ts"
   },
   "dependencies": {
     "@ensdomains/ensjs": "^4.0.2",

apps/ensapi/src/graphql-api/lib/write-graphql-schema.ts

@@ -0,0 +1,44 @@
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { lexicographicSortSchema, printSchema } from "graphql";
+
+import { makeLogger } from "@/lib/logger";
+
+const logger = makeLogger("write-graphql-schema");
+
+const MONOREPO_ROOT = resolve(import.meta.dirname, "../../../../../");
+const ENSSDK_ROOT = resolve(MONOREPO_ROOT, "packages/enssdk/");
+const OUTPUT_PATH = resolve(ENSSDK_ROOT, "src/omnigraph/generated/schema.graphql");
+
+async function _writeGraphQLSchema() {
+  const { schema } = await import("@/graphql-api/schema");
+  const schemaAsString = printSchema(lexicographicSortSchema(schema));
+
+  await writeFile(OUTPUT_PATH, schemaAsString);
+}
+
+/**
+ * Attempts to write the GraphQL Schema, swallowing any errors.
+ */
+export async function writeGraphQLSchema() {
+  try {
+    await _writeGraphQLSchema();
+    logger.info(`Wrote SDL to ${OUTPUT_PATH}`);
+  } catch (error) {
+    logger.warn(error, `Unable to write SDL to ${OUTPUT_PATH}`);
+  }
+}
+
+// when executed directly (`pnpm generate:gqlschema`), write generated schema and produce an exit code
+if (resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    await _writeGraphQLSchema();
+    console.log(`Wrote SDL to ${OUTPUT_PATH}`);
+    process.exit(0);
+  } catch (error) {
+    console.error(error);
+    process.exit(1);
+  }
+}

apps/ensapi/src/handlers/api/graphql/ensnode-graphql-api.ts

@@ -6,7 +6,7 @@ import { createApp } from "@/lib/hono-factory";
 
 const app = createApp();
 
-// 503 if ensv2 plugin not available
+// 503 if prerequisites not met
 app.use(async (c, next) => {
   const prerequisite = hasGraphqlApiConfigSupport(config.ensIndexerPublicConfig);
   if (!prerequisite.supported) {

apps/ensapi/src/index.ts

@@ -7,6 +7,7 @@ import { getReferralLeaderboardEditionsCaches } from "@/cache/referral-leaderboa
 import { referralProgramEditionConfigSetCache } from "@/cache/referral-program-edition-set.cache";
 import { referrerLeaderboardCache } from "@/cache/referrer-leaderboard.cache";
 import { redactEnsApiConfig } from "@/config/redact";
+import { writeGraphQLSchema } from "@/graphql-api/lib/write-graphql-schema";
 import { sdk } from "@/lib/instrumentation";
 import logger from "@/lib/logger";
 
@@ -26,12 +27,15 @@ const server = serve(
   async (info) => {
     logger.info({ config: redactEnsApiConfig(config) }, `ENSApi listening on port ${info.port}`);
 
+    // Write the generated graphql schema in the background
+    void writeGraphQLSchema();
+
     // Trigger proactive initialization of the indexing status cache at startup.
     // SWRCache with proactivelyInitialize: true starts fetching immediately upon
     // construction, but construction is deferred via the lazy proxy until first
     // access — so we access it explicitly here rather than waiting for the first
     // user request.
-    indexingStatusCache.read();
+    void indexingStatusCache.read();
   },
 );
 

docker-compose.yml

@@ -7,7 +7,7 @@ services:
     environment:
       # Override environment variables to point to docker instances
       DATABASE_URL: postgresql://postgres:password@postgres:5432/postgres
-      DATABASE_SCHEMA: ensindexer_0
+      DATABASE_SCHEMA: docker_compose_ensindexer_schema
       ENSRAINBOW_URL: http://ensrainbow:3223
     env_file:
       # NOTE: must define apps/ensindexer/.env.local (see apps/ensindexer/.env.local.example)
@@ -35,7 +35,7 @@ services:
     environment:
       # Override environment variables to point to docker instances
       DATABASE_URL: postgresql://postgres:password@postgres:5432/postgres
-      ENSINDEXER_SCHEMA_NAME: ensindexer_0
+      ENSINDEXER_SCHEMA_NAME: docker_compose_ensindexer_schema
     env_file:
       # NOTE: must define apps/ensapi/.env.local (see apps/ensapi/.env.local.example)
       # Copy .env.local.example to .env.local and configure all required values

package.json

@@ -22,7 +22,8 @@
     "docker:build:ensrainbow": "docker build -f apps/ensrainbow/Dockerfile -t ghcr.io/namehash/ensnode/ensrainbow:latest .",
     "docker:build:ensapi": "docker build -f apps/ensapi/Dockerfile -t ghcr.io/namehash/ensnode/ensapi:latest .",
     "otel-desktop-viewer": "docker run -p 8000:8000 -p 4317:4317 -p 4318:4318 davetron5000/otel-desktop-viewer:alpine-3",
-    "generate:openapi": "pnpm -r --if-present generate:openapi"
+    "generate:openapi": "pnpm -r --if-present generate:openapi",
+    "generate:gqlschema": "pnpm -F ensapi generate:gqlschema && pnpm -F enssdk generate:gqlschema"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.1",

packages/enscli/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NameHash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/enscli/README.md

@@ -0,0 +1,5 @@
+# enscli
+
+This package name is reserved for the [ENSNode](https://ensnode.io) project by [NameHash Labs](https://namehashlabs.org).
+
+For more information, visit [ensnode.io](https://ensnode.io).

packages/enscli/package.json

@@ -0,0 +1,13 @@
+{
+  "private": true,
+  "name": "enscli",
+  "version": "1.9.0",
+  "description": "Reserved for the ENSNode project by NameHash Labs. See https://ensnode.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/namehash/ensnode.git",
+    "directory": "packages/enscli"
+  },
+  "license": "MIT",
+  "homepage": "https://ensnode.io"
+}

packages/enskit/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NameHash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/enskit/README.md

@@ -0,0 +1,5 @@
+# enskit
+
+This package name is reserved for the [ENSNode](https://ensnode.io) project by [NameHash Labs](https://namehashlabs.org).
+
+For more information, visit [ensnode.io](https://ensnode.io).

packages/enskit/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "enskit",
+  "version": "1.9.0",
+  "description": "Reserved for the ENSNode project by NameHash Labs. See https://ensnode.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/namehash/ensnode.git",
+    "directory": "packages/enskit"
+  },
+  "license": "MIT",
+  "homepage": "https://ensnode.io"
+}

packages/enssdk/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NameHash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/enssdk/README.md

@@ -0,0 +1,53 @@
+# enssdk
+
+The foundational ENS developer library. Isomorphic, tree-shakable, with composable modules via subpath exports.
+
+Learn more about [ENSNode](https://ensnode.io/) from [the ENSNode docs](https://ensnode.io/docs).
+
+## Installation
+
+```bash
+npm install enssdk
+```
+
+## Usage
+
+### Core Client
+
+```typescript
+import { createEnsNodeClient } from "enssdk/core";
+
+const client = createEnsNodeClient({ url: "https://api.alpha.ensnode.io" });
+```
+
+### Omnigraph (Typed GraphQL)
+
+```typescript
+import { createEnsNodeClient } from "enssdk/core";
+import { omnigraph, graphql } from "enssdk/omnigraph";
+
+const client = createEnsNodeClient({ url: "https://api.alpha.ensnode.io" })
+  .extend(omnigraph);
+
+const MyQuery = graphql(`
+  query MyQuery($name: Name!) {
+    domain(by: { name: $name }) {
+      name
+      registration { expiry }
+    }
+  }
+`);
+
+const result = await client.omnigraph.query({
+  query: MyQuery,
+  variables: { name: "nick.eth" },
+});
+```
+
+Modules are composable via `extend()` — only import what you use.
+
+## License
+
+Licensed under the MIT License, Copyright © 2025-present [NameHash Labs](https://namehashlabs.org).
+
+See [LICENSE](./LICENSE) for more information.

packages/enssdk/biome.jsonc

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.3.2/schema.json",
+  "extends": "//",
+  "files": {
+    "includes": ["**", "!src/omnigraph/generated"]
+  }
+}