# WoW Item Data Fetching Scripts

This directory contains scripts to fetch World of Warcraft item data from various APIs.

## Scripts

### `fetch-item-data.js` - Basic Item Fetcher

A simple script that fetches item information from Wowhead API.

**Usage:**
```bash
# Fetch specific items by ID
npm run fetch-items 242494 242495 242481

# Fetch data for all existing items in drop files
npm run fetch-items --existing
```

**Features:**
- Fetches item name, slot, icon from Wowhead
- Supports both XML and JSON Wowhead APIs
- Rate limiting to avoid overwhelming servers
- Saves results to JSON file

### `fetch-items-enhanced.js` - Advanced Item Fetcher

Enhanced script with multiple API sources and additional features.

**Usage:**
```bash
# Basic usage
npm run fetch-items-enhanced 242494 242495 242481

# Fetch and validate existing items
npm run fetch-items-enhanced --existing --validate

# Generate TypeScript code for new dungeon
npm run fetch-items-enhanced --generate "new-dungeon" 123456 123457

# Use only specific API
npm run fetch-items-enhanced --wowhead-only 242494
npm run fetch-items-enhanced --blizzard-only 242494
```

**Features:**
- Multiple API sources (Wowhead + Blizzard)
- Data validation against existing project data
- TypeScript code generation
- Detailed reporting and analysis
- Fallback mechanisms

### `blizzard-api.js` - Blizzard API Client

Handles authentication and data fetching from Blizzard's official API.

**Setup for Blizzard API:**
1. Create an application at https://develop.battle.net/
2. Get your Client ID and Client Secret
3. Set environment variables:
   ```bash
   export BLIZZARD_CLIENT_ID="your_client_id"
   export BLIZZARD_CLIENT_SECRET="your_client_secret"
   ```

**Features:**
- OAuth2 token management
- Item data and media fetching
- Detailed item metadata

## Data Sources

### Wowhead API
- **Pros:** Reliable, no authentication required, good icon data
- **Cons:** Unofficial API, rate limiting needed
- **Best for:** Basic item info, icons, quick lookups

### Blizzard API
- **Pros:** Official API, detailed metadata, reliable
- **Cons:** Requires authentication setup, more complex
- **Best for:** Detailed item data, official information

## Output Files

- `fetched-items.json` - Basic fetch results
- `fetched-items-detailed-{timestamp}.json` - Enhanced fetch results with all API responses
- `{source-name}.ts` - Generated TypeScript code for new item sources

## Examples

### Fetch a few specific items
```bash
npm run fetch-items 242494 242495 242481
```

### Validate all existing project items
```bash
npm run fetch-items-enhanced --existing --validate
```

### Create a new dungeon data file
```bash
npm run fetch-items-enhanced --generate "mists-of-tirna-scithe" 178692 178693 178694
```

### Use only Wowhead (no Blizzard setup needed)
```bash
npm run fetch-items-enhanced --wowhead-only --existing
```

## Rate Limiting

Both scripts include rate limiting (1 second between requests) to be respectful to the APIs. For large batches of items, expect the process to take some time.

## Error Handling

The scripts will continue processing even if individual items fail to fetch. Check the console output and generated files for detailed results and any errors encountered.