feat: add search command for collections, NFTs, tokens, and accounts

[chrismaddern]

feat: add search command for collections, NFTs, tokens, and accounts

Summary

Adds a new search command group to the CLI that enables searching across OpenSea's marketplace data. Since the OpenSea REST API (api.opensea.io/api/v2) does not expose search endpoints, this uses the GraphQL API (gql.opensea.io/graphql) via four existing queries: collectionsByQuery, itemsByQuery, currenciesByQuery, and accountsByQuery.

Changes:

• src/client.ts: Added graphql() method to OpenSeaClient (alongside existing get/post for REST), with new graphqlUrl config option. Includes proper error handling for HTTP errors, GraphQL errors array, and missing data responses.
• src/commands/search.ts: New command file with 4 subcommands: collections, nfts, tokens, accounts
• src/sdk.ts: New SearchAPI class exposed as client.search.* for programmatic usage
• src/types/api.ts: New search result interfaces (SearchCollectionResult, SearchNFTResult, SearchTokenResult, SearchAccountResult)
• src/types/index.ts: Added graphqlUrl to OpenSeaClientConfig
• README.md: CLI reference + examples for all search subcommands

Usage:

opensea search collections mfers
opensea search nfts "cool cat" --collection tiny-dinos-eth --limit 5
opensea search tokens usdc --chain base
opensea search accounts vitalik

SDK usage:

const results = await client.search.collections("mfers", { limit: 5 })
const nfts = await client.search.nfts("ape", { collection: "boredapeyachtclub", chains: ["ethereum"] })

Updates since last revision

• Fixed graphql() method to explicitly guard against missing data in GraphQL responses. Previously json.data as T could return undefined and crash callers; now throws OpenSeaAPIError(500, "GraphQL response missing data", "graphql").
• Merged main into branch (brings in test suite, CI workflow, shared mocks from test: add full unit and integration test suite with CI workflow #20).
• Added full test coverage for the search feature (19 new tests, all passing):
  • test/client.test.ts: 5 tests for graphql() method — success path, custom graphqlUrl, HTTP errors, GraphQL errors array, missing data guard
  • test/commands/search.test.ts: 10 tests for the search CLI command — all 4 subcommands with default/custom options, table format output
  • test/sdk.test.ts: 4 tests for SearchAPI — verifies correct GraphQL query strings and variable passing for each method
  • test/mocks.ts: Added graphql to MockClient type and createCommandTestContext()

Review & Testing Checklist for Human

• Verify GraphQL queries work against the live API — The queries were modeled after opensea-mcp but were NOT tested end-to-end. Run each subcommand with a real API key to confirm the queries execute and return expected data shapes. Field names and types in the result interfaces may not match what the API actually returns. The new unit tests verify wiring only, not query correctness.
• Duplicate GraphQL queries in command vs SDK — The same query strings exist in both src/commands/search.ts and src/sdk.ts. Consider whether these should be deduplicated into a shared location.
• Search result types use camelCase (matching GraphQL) while existing REST types use snake_case — This is intentional but means search results have a different shape convention than other command outputs. Verify this is acceptable UX.

Recommended test plan:

export OPENSEA_API_KEY=your-key
opensea search collections mfers
opensea search nfts "ape" --limit 3
opensea search tokens eth --chain base --limit 3
opensea search accounts vitalik --limit 3
opensea --format table search collections "bored ape"

Notes

• Confidence: 🟡 MEDIUM — High confidence on the code structure/patterns (follows existing conventions well) and test coverage (113 tests passing, including 19 new tests for search). Medium confidence on the GraphQL queries actually working since they were not tested against the live endpoint. Type definitions are best-effort based on the opensea-mcp reference implementation.
• Link to Devin run: https://app.devin.ai/sessions/9848738941ed4994b46a79d50942a881
• Requested by: @chrismaddern (search feature), @ryanio (test additions)

[devin-ai-integration]

Original prompt from chris.maddern@opensea.io

can you add a search command to this repo please?

https://github.com/ProjectOpenSea/opensea-cli

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

⚙️ Control Options:

• Disable automatic comment and CI monitoring