exa-debug-bundle

# Exa Debug Bundle

## Current State
!`node --version 2>/dev/null || echo 'N/A'`
!`npm list exa-js 2>/dev/null | grep exa-js || echo 'exa-js not installed'`
!`echo "EXA_API_KEY: ${EXA_API_KEY:+SET (${#EXA_API_KEY} chars)}"`

## Overview
Collect all necessary diagnostic information for Exa support tickets. Exa error responses include a `requestId` field — always include it when contacting support at hello@exa.ai.

## Instructions

### Step 1: Quick Connectivity Test
```bash
set -euo pipefail

echo "=== Exa Connectivity Test ==="
echo "API Key: ${EXA_API_KEY:+SET (${#EXA_API_KEY} chars)}"
echo ""

# Test basic search endpoint
HTTP_CODE=$(curl -s -o /tmp/exa-debug.json -w "%{http_code}" \
  -X POST https://api.exa.ai/search \
  -H "x-api-key: $EXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"debug connectivity test","numResults":1}')

echo "HTTP Status: $HTTP_CODE"
if [ "$HTTP_CODE" = "200" ]; then
  echo "Status: HEALTHY"
  python3 -c "import json; d=json.load(open('/tmp/exa-debug.json')); print(f'Results: {len(d.get(\"results\",[]))}')" 2>/dev/null
else
  echo "Status: UNHEALTHY"
  echo "Response:"
  cat /tmp/exa-debug.json | python3 -m json.tool 2>/dev/null || cat /tmp/exa-debug.json
fi
```

### Step 2: Capture Request/Response Details
```typescript
import Exa from "exa-js";

const exa = new Exa(process.env.EXA_API_KEY);

async function debugSearch(query: string) {
  const startTime = performance.now();
  try {
    const result = await exa.searchAndContents(query, {
      numResults: 3,
      text: { maxCharacters: 500 },
    });

    const duration = performance.now() - startTime;
    console.log("=== Debug Info ===");
    console.log(`Query: "${query}"`);
    console.log(`Duration: ${duration.toFixed(0)}ms`);
    console.log(`Results: ${result.results.length}`);
    console.log(`Has autoprompt: ${!!result.autopromptString}`);
    for (const r of result.results) {
      console.log(`  [${r.score.toFixed(3)}] ${r.title} (${r.url})`);
      console.log(`    Text: ${r.text ? `${r.text.length} chars` : "none"}`);
    }
  } catch (err: any) {
    const duration = performance.now() - startTime;
    console.error("=== Error Debug ===");
    console.error(`Query: "${query}"`);
    console.error(`Duration: ${duration.toFixed(0)}ms`);
    console.error(`Status: ${err.status || "unknown"}`);
    console.error(`Message: ${err.message}`);
    console.error(`RequestId: ${err.requestId || err.request_id || "none"}`);
    console.error(`Error tag: ${err.error_tag || err.tag || "none"}`);
  }
}
```

### Step 3: Create Debug Bundle Script
```bash
#!/bin/bash
set -euo pipefail
# exa-debug-bundle.sh

BUNDLE_DIR="exa-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

echo "=== Exa Debug Bundle ===" > "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE_DIR/summary.txt"

# Environment info
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- Environment ---" >> "$BUNDLE_DIR/summary.txt"
echo "Node: $(node --version 2>/dev/null || echo 'N/A')" >> "$BUNDLE_DIR/summary.txt"
echo "npm: $(npm --version 2>/dev/null || echo 'N/A')" >> "$BUNDLE_DIR/summary.txt"
echo "OS: $(uname -a)" >> "$BUNDLE_DIR/summary.txt"
echo "EXA_API_KEY: ${EXA_API_KEY:+SET}" >> "$BUNDLE_DIR/summary.txt"

# SDK version
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- SDK ---" >> "$BUNDLE_DIR/summary.txt"
npm list exa-js 2>/dev/null >> "$BUNDLE_DIR/summary.txt" || echo "exa-js not found" >> "$BUNDLE_DIR/summary.txt"

# API connectivity test
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- API Test ---" >> "$BUNDLE_DIR/summary.txt"
HTTP_CODE=$(curl -s -o "$BUNDLE_DIR/api-response.json" -w "%{http_code}" \
  -X POST https://api.exa.ai/search \
  -H "x-api-key: ${EXA_API_KEY:-missing}" \
  -H "Content-Type: application/json" \
  -d '{"query":"debug test","numResults":1}' 2>/dev/null)
echo "HTTP Status: $HTTP_CODE" >> "$BUNDLE_DIR/summary.txt"

# Package bundle
tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
echo "Bundle created: $BUNDLE_DIR.tar.gz"
echo ""
echo "IMPORTANT: Review $BUNDLE_DIR/summary.txt before sharing."
echo "Include the requestId from any error responses when contacting hello@exa.ai"
```

## Output
- `exa-debug-YYYYMMDD-HHMMSS.tar.gz` archive containing:
  - `summary.txt` — environment, SDK version, API connectivity
  - `api-response.json` — raw API response from test query

## Sensitive Data Handling
**Always redact before sharing:**
- API keys and tokens
- Query content containing PII
- Internal URLs or domain names

**Safe to include:**
- HTTP status codes and error tags
- `requestId` from error responses
- SDK and runtime versions
- Latency measurements

## Error Handling
| Issue | Cause | Solution |
|-------|-------|----------|
| `curl: command not found` | curl not installed | Install curl or use node script |
| Empty API response | Network firewall | Check outbound HTTPS to api.exa.ai |
| 401 in connectivity test | Bad API key | Regenerate at dashboard.exa.ai |
| Bundle script fails | Missing permissions | Run with `bash` not `sh` |

## Resources
- [Exa Error Codes](https://docs.exa.ai/reference/error-codes)
- [Exa Support](mailto:hello@exa.ai)

## Next Steps
For rate limit issues, see `exa-rate-limits`. For common error solutions, see `exa-common-errors`.