Narrative Overhaul: Client Packages

[shrugs]

We want the answer for 'which package do i install' to be extremely clear for new/existing developers, and the existing array of packages is a bit unclear. The new branding (enssdk, enskit, enscli, ensskills) is intentionally general-purpose ENS ecosystem branding — these tools are not ENSNode-specific and will be useful to the broader ENS community, but obviously have first-class integration with ENSNode, which likely powers most of their capabilities.

Package Architecture

The foundational layer is enssdk, a new unscoped package containing all shared ENS types and client-focused libraries. @ensnode/sdk (renamed from @ensnode/ensnode-sdk) depends on enssdk (dependency inversion from the current structure) to acquire shared types and ENS-specific client libs, while retaining its own operator-focused, ENSNode-specific exports and its @ensnode/sdk/internal subpath for internal implementation details shared between ENSNode services.

• enssdk — foundational ENS client library (unscoped npm package)

  • no dependency on @ensnode/sdk — this is the base layer
  • shared ENS types and client-focused utilities that were previously in @ensnode/sdk migrate here
  • subpath exports for treeshaking and modularity
  • enssdk/omnigraph — provides typed access to the Omnigraph API via gql.tada
  • (future) enssdk/registrars — Registrar Actions API
  • (future) enssdk/identity — Identity API
  • (future) enssdk/resolution — Resolution API
  • (future) enssdk/analytics — Analytics API
  • (future) enssdk/tokenscope — Tokenscope API
  • (future) enssdk/meta — Config, Indexing Status, Realtime
  • (or whatever the correct split between these modules should be)

• @ensnode/sdk — operator-focused ENSNode-specific exports

  • depends on enssdk for shared types
  • @ensnode/sdk/internal — internal-only shared types/libs between ENSNode services

• enskit — framework-specific wrappers of enssdk (unscoped npm package)

  • enskit/react — React hooks and components wrapping enssdk
  • enskit/react/omnigraph — opinionated urql-based Omnigraph client with logical defaults
  • room for enskit/svelte, etc. in the future

• enscli (see Narrative Overhaul: ENSNode CLI #1741)

  • agent-and-human-friendly CLI wrapping enssdk
  • used by agent skills via npx enscli

• ensskills — agent skills for ENS

Omnigraph API Evolution

In the short term, APIs like Registrar Actions and Tokenscope may be surfaced within the Omnigraph directly (the current ENSv2 plugin already slightly overlaps with these). In the long term, the Omnigraph may encompass all ENSNode APIs, potentially offering 100% feature parity between a GraphQL surface and an equivalent HTTP/JSON surface. We're not close enough to propose specifics on the unified API yet, but the subpath structure of enssdk is designed to accommodate this evolution.

Testing

We should integrate the client libs into the integration test environment and confirm that those pathways operate against the devnet as expected. This sort of integration test over the (thin) clients would be much more valuable than mocking the api responses, since there's very little actual control flow in most of the client methods to test.

Breaking Changes and Transition

Due to the nascent usage of ENSNode in the ecosystem, a major breaking change is acceptable and we don't need to offer any transition period.

Timeline

Ordered by priority. Goal is user-facing experience ready within one month.

1. enssdk package — scaffold the package, establish subpath exports, migrate shared types and client-focused code from @ensnode/sdk

• tightly focused on omnigraph api support
• integration tested against devnet in integration-test-env using well-known example-queries.ts

2. enskit package — scaffold with enskit/react and enskit/react/omnigraph, migrate from @ensnode/react
3. ensskills — agent skills
4. enscli — CLI wrapping enssdk
5. @ensnode/sdk refactor — dependency inversion, consolidate @ensnode/ensrainbow-sdk and @ensnode/ensdb-sdk into subpath exports