refactor: use zod-openapi for name-tokens-api

[notrab]

Lite PR

Tip: Review docs on the ENSNode PR process

Summary

• Migrated name-tokens-api from hono-openapi (describeRoute/validate) to @hono/zod-openapi (createRoute/app.openapi), following the established pattern from prior migrations.
• Created name-tokens-api.routes.ts extracting the route definition and query schema; updated the handler to use createApp() and app.openapi().
• Registered the new routes in stub-routes.ts for OpenAPI spec generation.

---

Why

• Continuing the incremental migration to @hono/zod-openapi so all REST routes can generate an OpenAPI spec at runtime via stub-routes.ts.
• Follows the same pattern established in refactor: use zod-openapi for ensnode-api #1672 and prior PRs for amirealtime-api, resolution-api, and ensnode-api.

---

Testing

• typecheck passes
• lint passes
• Refactoring only
• no changes to schemas, validation logic, handler behaviour, response bodies, or status codes.

---

Notes for Reviewer (Optional)

• ⚠️ The config import and indexedSubregistries computation remain in the handler file (not the routes file), since they depend on runtime config/env vars that the stub routes must avoid importing.

After this, ensanalytics-api (2 routes), ensanalytics-api-v1 (3 routes) remain to be migrated.

---

Pre-Review Checklist (Blocking)

• This PR does not introduce significant changes and is low-risk to review quickly.
• Relevant changesets are included (or are not required)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
admin.ensnode.io	Skipped		Feb 26, 2026 6:50am
ensnode.io	Skipped		Feb 26, 2026 6:50am
ensrainbow.io	Skipped		Feb 26, 2026 6:50am

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5c1ecdf

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Warning

Rate limit exceeded

@notrab has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 13 minutes and 43 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 89307ae and 5c1ecdf.

📒 Files selected for processing (1)

• apps/ensapi/src/handlers/name-tokens-api.ts

📝 Walkthrough

Walkthrough

A new Name Tokens API route module is introduced with Zod-based query schema validation, allowing clients to query tokens by domain ID or name. The existing handler is refactored to use the externalized route definition and adds early indexing status guards with updated error handling. The new routes are registered in the stub routes configuration.

Changes

Cohort / File(s)	Summary
New Route Definition apps/ensapi/src/handlers/name-tokens-api.routes.ts	Introduces new route module exporting basePath, nameTokensQuerySchema (validates exactly one of domainId or name), NameTokensQuery type, and route definition with OpenAPI-style responses (200, 400, 404, 500, 503) using internal SDK schemas.
Handler Refactoring apps/ensapi/src/handlers/name-tokens-api.ts	Replaces inline route construction with externalized getNameTokensRoute via app.openapi(); switches from factory.createApp() to createApp(); adds early 503 guard for undefined indexingStatus; updates error handling and consolidates status checks; wires validated query data to token retrieval logic with subject-specific error messages.
Route Registration apps/ensapi/src/stub-routes.ts	Imports and registers nameTokensRoutes in the routeGroups array, enabling stub route inclusion for the Name Tokens API.

Sequence Diagram

sequenceDiagram
    actor Client
    participant Route as Route Handler
    participant Validator as Query Validator
    participant IndexCheck as Indexing Status
    participant SDK as SDK/Registry
    participant Response as Response

    Client->>Route: GET /api/name-tokens/?name=...
    Route->>Validator: Validate query (domainId OR name)
    Validator-->>Route: Query validated
    Route->>IndexCheck: Check indexingStatus
    alt IndexingStatus undefined
        IndexCheck-->>Route: Error (503)
        Route-->>Client: 503 Service Unavailable
    else IndexingStatus is error
        IndexCheck-->>Route: Error (503)
        Route-->>Client: 503 Service Unavailable
    else IndexingStatus OK
        IndexCheck-->>Route: Status OK
        Route->>SDK: Verify parent subregistry indexed
        alt Not indexed or ENS_ROOT
            SDK-->>Route: Not found
            Route-->>Client: 404 Not Found
        else Indexed
            SDK->>SDK: Compute namehash & retrieve tokens
            SDK-->>Route: Token data or empty
            alt Tokens found
                Route-->>Client: 200 OK with tokens
            else No tokens
                Route-->>Client: 404 Not Found
            end
        end
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat: zod-openapi for amirealtime-api #1661: Performs the same OpenAPI/Zod-route refactor pattern—externalized .routes metadata, createApp/OpenAPIHono migration, and stub-route registration.
• refactor: use zod-openapi for ensnode-api #1672: Migrates ENS API handlers to externalized zod-openapi route modules and switches app initialization from factory.createApp() to createApp().

Poem

🐰 A route so clean, extracted out,
With schemas strict, devoid of doubt,
Query tokens by their name so bright,
Or by their hash—let validation light
The path to indexed domains fair,
Where tokens wait with careful care! 🎀

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: migrating name-tokens-api to use zod-openapi, which is the primary purpose of this refactoring PR.
Description check	✅ Passed	The PR description is well-structured, follows the template with all required sections (Summary, Why, Testing, Notes, Checklist), provides clear context about the migration pattern, explains the rationale, and documents testing verification.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch zod-openapi-name-tokens-api

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Greptile Summary

Successfully migrated name-tokens-api from hono-openapi to @hono/zod-openapi following the established pattern.

• Created name-tokens-api.routes.ts extracting route definition and query schema
• Updated handler to use createApp() and app.openapi() pattern
• Registered routes in stub-routes.ts for OpenAPI spec generation
• Handler logic is completely unchanged - pure refactoring with no behavioral changes
• All validation logic, error responses, and business logic remain identical

Confidence Score: 5/5

• This PR is safe to merge with no risk
• Pure refactoring with identical handler logic, follows established migration pattern, all files have maximum confidence scores
• No files require special attention

Important Files Changed

Filename	Overview
apps/ensapi/src/handlers/name-tokens-api.routes.ts	New routes file extracts route definition and query schema from handler, follows established pattern
apps/ensapi/src/handlers/name-tokens-api.ts	Successfully migrated from hono-openapi to @hono/zod-openapi, handler logic unchanged
apps/ensapi/src/stub-routes.ts	Added nameTokensRoutes import and registration for OpenAPI spec generation

_{Last reviewed commit: bdc9d7c}

[greptile-apps]

_{3 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[Copilot]

Pull request overview

This PR migrates the name-tokens-api from the legacy hono-openapi library (describeRoute/validate) to @hono/zod-openapi (createRoute/app.openapi), continuing the incremental migration started in PR #1672.

Changes:

• Created name-tokens-api.routes.ts with route definitions and query schema extracted from the handler
• Refactored name-tokens-api.ts to use createApp() and app.openapi() instead of factory.createApp() and describeRoute()
• Registered the new routes in stub-routes.ts for OpenAPI spec generation

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
apps/ensapi/src/stub-routes.ts	Imported and registered name-tokens-api routes for OpenAPI spec generation
apps/ensapi/src/handlers/name-tokens-api.ts	Migrated from describeRoute/validate to app.openapi; removed route definition code now in routes file; handler logic preserved
apps/ensapi/src/handlers/name-tokens-api.routes.ts	New file containing route definition, query schema, and basePath for OpenAPI spec generation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@apps/ensapi/src/handlers/name-tokens-api.ts`:
- Line 110: The error message string in name-tokens-api.ts used by the ENSNode
handler is missing a closing single quote after the template interpolation
'${name'; update the offending literal (the message starting "This ENSNode
instance has not been configured to index tokens for the requested name:
'${name") to include the closing single quote so it becomes '${name}' (adjusting
the surrounding quotes/escaping as needed) so the string is syntactically valid
where it’s used in the ENSNode-related error/throw.

---

ℹ️ Review info

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c6e7d5c and 89307ae.

📒 Files selected for processing (3)

• apps/ensapi/src/handlers/name-tokens-api.routes.ts
• apps/ensapi/src/handlers/name-tokens-api.ts
• apps/ensapi/src/stub-routes.ts

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[lightwalker-eth]

@notrab Looks good, thanks 👍