🤖 [Experimental] SDK Quality Improvements - Error Types, Docs & Timeout Support

[jeffzwang]

⚠️ Experimental PR - Generated by Claude Code

This PR was autonomously generated by Claude Code at @jwang's request. It's an experimental effort to improve SDK quality based on a comprehensive audit. Please review carefully!

---

Summary

This PR addresses several quality improvements identified in an SDK audit:

• Add specialized error types - RateLimitError, AuthenticationError, ValidationError, TimeoutError, NotFoundError, ServerError with relevant metadata
• Document ResearchClient - Added comprehensive JSDoc to all 8 public methods (was 0% documented)
• Add streaming timeout support - streamAnswer() now supports timeoutMs option with proper AbortController handling
• Modernize README - Complete rewrite with current API patterns, removed deprecated method examples
• Add Node.js version requirement - engines.node >= 18.0.0

Changes by File

File	Changes
src/errors.ts	+124 lines - 6 new error subclasses
src/research/client.ts	+182 lines - Complete JSDoc coverage
src/index.ts	+109 lines - Timeout support, @throws docs
README.md	Rewritten - Modern examples, error handling section
package.json	+3 lines - engines field

Error Types Added

import { 
  RateLimitError,      // 429 - includes retryAfter
  AuthenticationError, // 401 - invalid API key
  ValidationError,     // 400 - includes field, constraint  
  TimeoutError,        // 408 - includes timeoutMs
  NotFoundError,       // 404 - includes resourceId
  ServerError          // 500/503 - includes retryable boolean
} from "exa-js";

New Streaming Timeout

// Now supports timeout to prevent hung connections
for await (const chunk of exa.streamAnswer("query", {
  timeoutMs: 30000 // 30 second timeout (default: 60s)
})) {
  // ...
}

Test plan

• All 65 unit tests passing
• Build successful (CJS, ESM, DTS outputs)
• TypeScript compilation successful
• Manual testing of error types in real API calls
• Manual testing of streaming timeout behavior

---

🤖 Generated with Claude Code