feat(ponder-sdk): create Ponder Client

.changeset/config.json

@@ -16,8 +16,9 @@
       "@ensnode/ponder-metadata",
       "@ensnode/ensnode-schema",
       "@ensnode/ensnode-react",
-      "@ensnode/ponder-subgraph",
       "@ensnode/ensnode-sdk",
+      "@ensnode/ponder-sdk",
+      "@ensnode/ponder-subgraph",
       "@ensnode/shared-configs",
       "@docs/ensnode",
       "@docs/ensrainbow",

.changeset/cozy-turkeys-fix.md

@@ -0,0 +1,5 @@
+---
+"@ensnode/ponder-sdk": minor
+---
+
+Introduce the `ponder-sdk` package, including an initial `PonderClient` implementation.

.github/workflows/release.yml

@@ -104,6 +104,7 @@ jobs:
               or .name == "@ensnode/ensrainbow-sdk"
               or .name == "@ensnode/namehash-ui"
               or .name == "@ensnode/ponder-metadata"
+              or .name == "@ensnode/ponder-sdk"
               or .name == "@ensnode/ponder-subgraph"
             ))
 

.github/workflows/release_preview.yml

@@ -305,8 +305,9 @@ jobs:
           pnpm add @ensnode/ensrainbow-sdk@${{ needs.validate-and-prepare.outputs.dist-tag }}
           pnpm add @ensnode/ensnode-schema@${{ needs.validate-and-prepare.outputs.dist-tag }}
           pnpm add @ensnode/ensnode-sdk@${{ needs.validate-and-prepare.outputs.dist-tag }}
-          pnpm add @ensnode/ponder-subgraph@${{ needs.validate-and-prepare.outputs.dist-tag }}
           pnpm add @ensnode/ponder-metadata@${{ needs.validate-and-prepare.outputs.dist-tag }}
+          pnpm add @ensnode/ponder-sdk@${{ needs.validate-and-prepare.outputs.dist-tag }}
+          pnpm add @ensnode/ponder-subgraph@${{ needs.validate-and-prepare.outputs.dist-tag }}
           pnpm add @ensnode/ens-referrals@${{ needs.validate-and-prepare.outputs.dist-tag }}
           pnpm add @ensnode/namehash-ui@${{ needs.validate-and-prepare.outputs.dist-tag }}
 

README.md

@@ -173,15 +173,19 @@ TypeScript library for interacting with the [ENSRainbow API](apps/ensrainbow).
 
 ### [`packages/ensnode-schema`](packages/ensnode-schema)
 
-Shared Drizzle schema definitions used by ENSNode
+Shared Drizzle schema definitions used by ENSNode.
+
+### [`packages/ponder-sdk`](packages/ponder-sdk)
+
+A utility library for interacting with Ponder apps and data.
 
 ### [`packages/ponder-subgraph`](packages/ponder-subgraph)
 
-Subgraph-compatible GraphQL API
+Subgraph-compatible GraphQL API.
 
 ### [`packages/shared-configs`](packages/shared-configs)
 
-Shared internal configuration files
+Shared internal configuration files.
 
 ## Docs
 

packages/ponder-sdk/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/ponder-sdk/README.md

@@ -0,0 +1,3 @@
+# Ponder SDK
+
+This package is a utility library for interacting with Ponder apps and data.

packages/ponder-sdk/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@ensnode/ponder-sdk",
+  "version": "1.5.1",
+  "type": "module",
+  "description": "A utility library for interacting with Ponder apps and data.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/namehash/ensnode.git",
+    "directory": "packages/ponder-sdk"
+  },
+  "homepage": "https://github.com/namehash/ensnode/tree/main/packages/ponder-sdk",
+  "keywords": [
+    "ENSNode",
+    "Ponder"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "import": {
+          "types": "./dist/index.d.ts",
+          "default": "./dist/index.js"
+        },
+        "require": {
+          "types": "./dist/index.d.cts",
+          "default": "./dist/index.cjs"
+        }
+      }
+    },
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "scripts": {
+    "prepublish": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "lint": "biome check --write .",
+    "lint:ci": "biome ci"
+  },
+  "devDependencies": {
+    "@ensnode/shared-configs": "workspace:*",
+    "@types/node": "catalog:",
+    "tsup": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:",
+    "zod": "catalog:"
+  },
+  "peerDependencies": {
+    "zod": "catalog:"
+  }
+}

packages/ponder-sdk/src/blocks.ts

@@ -0,0 +1,27 @@
+import { z } from "zod/v4";
+
+import { nonnegativeIntegerSchema } from "./numbers";
+import { unixTimestampSchema } from "./time";
+
+//// Block Number
+
+export const blockNumberSchema = nonnegativeIntegerSchema;
+
+/**
+ * Block Number
+ *
+ * Guaranteed to be a non-negative integer.
+ */
+export type BlockNumber = z.infer<typeof blockNumberSchema>;
+
+export const blockRefSchema = z.object({
+  number: blockNumberSchema,
+  timestamp: unixTimestampSchema,
+});
+
+/**
+ * BlockRef
+ *
+ * Reference to a block.
+ */
+export type BlockRef = z.infer<typeof blockRefSchema>;

packages/ponder-sdk/src/chains.ts

@@ -0,0 +1,17 @@
+import type { z } from "zod/v4";
+
+import { positiveIntegerSchema } from "./numbers";
+
+// Chain ID
+
+export const chainIdSchema = positiveIntegerSchema;
+
+/**
+ * Chain ID
+ *
+ * Represents a unique identifier for a chain.
+ * Guaranteed to be a positive integer.
+ *
+ * Chain id standards are organized by the Ethereum Community @ https://github.com/ethereum-lists/chains
+ **/
+export type ChainId = z.infer<typeof chainIdSchema>;

packages/ponder-sdk/src/client.test.ts

@@ -0,0 +1,122 @@
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+
+import { PonderClient } from "./client";
+import { deserializePonderIndexingStatus } from "./deserialize/indexing-status";
+import {
+  mockSerializedPonderIndexingStatusInvalidBlockNumber,
+  mockSerializedPonderIndexingStatusInvalidChainId,
+  mockSerializedPonderIndexingStatusValid,
+} from "./deserialize/indexing-status.mock";
+
+// Mock Fetch API
+const mockFetch = vi.fn<typeof fetch>();
+
+describe("Ponder Client", () => {
+  beforeAll(() => {
+    vi.stubGlobal("fetch", mockFetch);
+  });
+
+  afterEach(() => {
+    mockFetch.mockReset();
+  });
+
+  afterAll(() => {
+    vi.unstubAllGlobals();
+  });
+
+  describe("status()", () => {
+    it("should handle valid Ponder status response", async () => {
+      // Arrange
+      mockFetch.mockResolvedValueOnce(
+        new Response(JSON.stringify(mockSerializedPonderIndexingStatusValid), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        }),
+      );
+
+      const ponderClient = new PonderClient(new URL("http://localhost:3000"));
+
+      // Act & Assert
+      await expect(ponderClient.status()).resolves.toStrictEqual(
+        deserializePonderIndexingStatus(mockSerializedPonderIndexingStatusValid),
+      );
+    });
+
+    describe("Invalid response handling", () => {
+      it("should handle invalid block numbers in the response", async () => {
+        mockFetch.mockResolvedValueOnce(
+          new Response(JSON.stringify(mockSerializedPonderIndexingStatusInvalidBlockNumber), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          }),
+        );
+
+        const ponderClient = new PonderClient(new URL("http://localhost:3000"));
+
+        await expect(ponderClient.status()).rejects.toThrowError(
+          /Invalid serialized Ponder Indexing Status.*Value must be a non-negative integer/,
+        );
+      });
+
+      it("should handle invalid chain IDs in the response", async () => {
+        mockFetch.mockResolvedValueOnce(
+          new Response(JSON.stringify(mockSerializedPonderIndexingStatusInvalidChainId), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          }),
+        );
+
+        const ponderClient = new PonderClient(new URL("http://localhost:3000"));
+
+        await expect(ponderClient.status()).rejects.toThrowError(
+          /Invalid serialized Ponder Indexing Status.*Value must be a positive integer/,
+        );
+      });
+
+      it("should handle zero indexed chains in the response", async () => {
+        mockFetch.mockResolvedValueOnce(
+          new Response(JSON.stringify({}), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          }),
+        );
+
+        const ponderClient = new PonderClient(new URL("http://localhost:3000"));
+
+        await expect(ponderClient.status()).rejects.toThrowError(
+          /Invalid serialized Ponder Indexing Status.*Ponder Indexing Status must include at least one indexed chain/,
+        );
+      });
+    });
+
+    describe("HTTP error handling", () => {
+      it("should handle non-OK HTTP responses", async () => {
+        // Arrange
+        mockFetch.mockResolvedValueOnce(
+          new Response("Internal Server Error", {
+            status: 500,
+            statusText: "Internal Server Error",
+          }),
+        );
+        const ponderClient = new PonderClient(new URL("http://localhost:3000"));
+        // Act & Assert
+        await expect(ponderClient.status()).rejects.toThrowError(
+          /Failed to fetch Ponder Indexing Status response/,
+        );
+      });
+
+      it("should handle JSON parsing errors", async () => {
+        mockFetch.mockResolvedValueOnce(
+          new Response("not valid json", {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          }),
+        );
+        const ponderClient = new PonderClient(new URL("http://localhost:3000"));
+        await expect(ponderClient.status()).rejects.toThrowError(
+          /Failed to parse Ponder Indexing Status response as JSON/,
+        );
+      });
+    });
+  });
+});

packages/ponder-sdk/src/client.ts

@@ -0,0 +1,36 @@
+import { deserializePonderIndexingStatus } from "./deserialize/indexing-status";
+import type { PonderIndexingStatus } from "./indexing-status";
+
+/**
+ * PonderClient for fetching data from Ponder apps.
+ */
+export class PonderClient {
+  constructor(private baseUrl: URL) {}
+
+  /**
+   * Get Ponder Indexing Status
+   *
+   * @returns Ponder Indexing Status.
+   * @throws Error if the response could not be fetched or was invalid.
+   */
+  async status(): Promise<PonderIndexingStatus> {
+    const requestUrl = new URL("/status", this.baseUrl);
+    const response = await fetch(requestUrl);
+
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch Ponder Indexing Status response: ${response.status} ${response.statusText}`,
+      );
+    }
+
+    let responseData: unknown;
+
+    try {
+      responseData = await response.json();
+    } catch {
+      throw new Error("Failed to parse Ponder Indexing Status response as JSON");
+    }
+
+    return deserializePonderIndexingStatus(responseData);
+  }
+}