feat: add end-to-end REST API v2 test suite (DIS-71)

[ckorhonen]

feat: add end-to-end REST API v2 test suite (DIS-71)

Summary

Adds a comprehensive live end-to-end test suite (test/rest-api.test.ts) that exercises all OpenSea REST API v2 endpoint families. Tests are gated by LIVE_TEST=true and require OPENSEA_API_KEY to run. Uses raw fetch calls (following the pattern in src/client.ts) with Zod schema validation derived from the existing TypeScript types in src/types/api.ts.

Endpoint families covered: Collections (get, list, stats, traits), NFTs (get, listByCollection, listByContract, listByAccount, contract, refresh), Listings (all, best, bestForNFT), Offers (all, collection, bestForNFT, traits), Events (list, byCollection, byAccount, byNFT), Accounts, Tokens (trending, top, get), Search, Swap Quote, and Fulfillment Data (POST error-path only).

Per-endpoint validation: schema validation, pagination cursor verification, error handling (404s, invalid input, missing API key), rate-limit header presence, Cache-Control header presence, latency measurement, response size tracking.

Output: JSON report written to test-reports/rest-api-e2e-report.json with pass/fail per endpoint and latency percentiles (p50/p90/p95/p99).

Updates since last revision

Addressed all human reviewer and bot feedback. All 43 tests pass against the live API. Changes since initial PR:

Schema & assertion alignment (live test failures):

• CollectionSchema: Made editors, fees, rarity, payment_tokens, total_supply, created_date, and several social/URL fields optional — the list endpoint returns a sparser object than the detail endpoint.
• Invalid account address: API returns 200 with default data rather than 400/404. Assertion relaxed to < 500.
• Fulfillment POST endpoints: API returns 500 (not 4xx) for invalid order hashes. Assertion relaxed to >= 400.
• Unauthenticated request: Collections endpoint allows requests without an API key. Assertion relaxed to < 500.

Review feedback fixes:

• Moved test file from src/__tests__/ to test/ per repo conventions (.agents/rules.md)
• Fixed rate-limit header check: Headers.get() returns null not undefined, so toBeDefined() was ineffective. Now records missing headers as a schema violation instead of hard-failing.
• Fixed cache-control header check: same bug class — changed toBeDefined() → not.toBeNull()
• Added test-reports/ to .gitignore
• Added inline comment explaining why tokens pagination uses cursor param instead of next (matches sdk.ts TokensAPI)
• Removed unused _recordSkip helper (dead code)
• Added empty-array guard (expect(length).toBeGreaterThan(0)) before accessing nfts[0] in listByContract test

Review & Testing Checklist for Human

• Review the relaxed assertions — Several error-path tests were loosened after live validation. Confirm this is acceptable or whether the API should actually be returning stricter error codes (invalid addresses → 200, fulfillment → 500, no auth → 200). These could be masking real API issues worth filing separately.
• Verify Zod schemas against a fresh API run — Schemas were validated against live runs but may still have nullable/optional mismatches. Pay particular attention to CollectionSchema (many optional fields in list vs detail), NFTSchema.traits, AccountSchema.social_media_accounts, and TokenSchema/TokenDetailsSchema.
• Check rate-limit behavior — ~43 sequential live API calls with no retry/backoff logic. Confirm this won't trip rate limits in CI or consider adding a small delay between requests.
• Test plan: Run LIVE_TEST=true OPENSEA_API_KEY=<key> npx vitest run test/rest-api.test.ts, review the generated JSON report for any schema violations or unexpected failures, and verify the report file is written correctly.

Notes

• Fulfillment POST endpoints are only tested for error handling (invalid payloads → error status) since happy-path testing requires signed order data with a wallet.
• Hardcoded test fixtures (Azuki, vitalik.eth, WETH address) are well-known and stable but could theoretically change state.

Link to Devin session: https://app.devin.ai/sessions/b9696787113645248420b4decbef7ade
Requested by: @ckorhonen

---

[devin-ai-integration]

Original prompt from Chris K

Please work on ticket "[Testing] Build end-to-end agent test suite for REST API" ([DIS-71](https://linear.app/opensea/issue/DIS-71/testing-build-end-to-end-agent-test-suite-for-rest-api))

PLAYBOOK_md:
# Ticket to PR

## Overview

This playbook guides the process of taking a Linear ticket from initial scoping through implementation to final review. The workflow ensures proper context gathering, quality implementation, and thorough code review before delivery. The agent uses the Linear MCP to manage ticket status and communication throughout.

## What's Needed From User

- Linear ticket URL or ticket ID (e.g., `ENG-123` or `https://linear.app/team/issue/ENG-123/...`)
- Repository access for the codebase where changes will be made

<phase name="Disambiguation" id="1">
## Disambiguation Phase

Think about the full user intent. Tickets are sometimes sparse. Make sure you disambiguate to the full scope that the user intended.

1. Fetch the ticket details using the Linear MCP `get_issue` tool with the ticket ID
2. Before diving into code: use the devin MCP to get a high-level understanding of the relevant systems and architecture. Use `ask_question` to learn about the relevant systems – send queries for multiple repos that could be relevant to get the full picture. Use `read_wiki_contents` to then get a better understanding how different parts of the codebase connect to each other.
3. Gather additional context to understand what the ticket means and refers to:
   - Look at past tickets in the same project and from the same author to understand patterns and terminology
   - Search for related commits and PRs (by author and content) that may provide context on the affected systems
   - Check any linked documents, designs, or parent tickets
   - Investigate the actual code
4. Identify any ambiguity in what the ticket refers to or asks for, including jargon or project-specific terms and use all means necessary to answer this yourself
5. Consult your smart friend: pass in the ... (8110 chars truncated...)

[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

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[ckorhonen]

@devin Two items to address:

1. cursor vs next pagination inconsistency — In the tokens trending pagination test (~line 1045), you pass { limit: 2, cursor: page1.data.next } but every other pagination test uses next as the parameter name. Verify which is correct for the trending endpoint and make it consistent.

2. Unused _recordSkip helper — Lines ~176-189 define _recordSkip but it's never called. Either use it or remove it to avoid dead code.

[devin-ai-integration]

Both addressed in e5b32c2:

1. cursor vs next: Intentional — the tokens API uses cursor as its query param instead of next (see sdk.ts lines 314, 328). Added a comment in the test to make this clear.
2. _recordSkip: Removed.