`auction-viewer/API_DOCUMENTATION.md`

552 lines
# LUXVAULT Auction API Documentation

## Base URL
`http://45.61.58.125:7500`

## Rate Limiting
- Standard endpoints: 100 requests per 15 minutes per IP
- Search endpoint: 30 requests per 15 minutes per IP

## Response Format
All endpoints return JSON with the following structure:
```json
{
  "success": true,
  "data": [...],
  "pagination": { ... },  // For paginated endpoints
  "cached": false         // Indicates if response was cached
}
```

---

## Endpoints

### Health Check
**GET** `/api/health`

Returns server health status, database connectivity, cache statistics, and metrics.

**Response:**
```json
{
  "status": "healthy",
  "timestamp": "2025-11-17T08:00:00.000Z",
  "uptime": 3600,
  "database": {
    "connected": true,
    "size": 16384,
    "records": 0
  },
  "cache": {
    "keys": 5,
    "hits": 150,
    "misses": 20,
    "hitRate": "88.24%"
  },
  "metrics": {
    "totalRequests": 170,
    "errors": 0,
    "avgResponseTime": "15ms"
  }
}
```

---

### Get Auctions (Paginated)
**GET** `/api/auctions`

Retrieve auctions with pagination, filtering, and sorting.

**Query Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | integer | 1 | Page number (min: 1) |
| `limit` | integer | 50 | Items per page (min: 1, max: 100) |
| `sort` | string | date_desc | Sort order (see below) |
| `brand` | string | - | Filter by brand/search term |
| `auction_house` | string | - | Filter by auction house |
| `min_price` | number | - | Minimum current price |
| `max_price` | number | - | Maximum current price |
| `min_savings` | number | - | Minimum savings amount |

**Sort Options:**
- `price_asc` - Price low to high
- `price_desc` - Price high to low
- `date_asc` - Oldest first
- `date_desc` - Newest first
- `savings_desc` - Highest savings first
- `savings_asc` - Lowest savings first

**Example Request:**
```
GET /api/auctions?page=1&limit=20&sort=savings_desc&brand=hermes&min_savings=1000
```

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "auction_id": "abc123",
      "title": "Hermes Birkin 35 Black",
      "auction_house": "Christie's",
      "current_price": 8000,
      "estimate_low": 10000,
      "estimate_high": 12000,
      "savings_percent": 20,
      "savings_amount": 2000,
      "end_date": "2025-11-15",
      "url": "https://...",
      "search_term": "Hermes Birkin",
      "created_at": "2025-11-17T06:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5,
    "hasMore": true
  },
  "filters": {
    "brand": "hermes",
    "min_savings": 1000
  },
  "sort": "savings_desc"
}
```

---

### Search Auctions
**GET** `/api/search`

Full-text search across auction titles, brands, and auction houses.

**Query Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | Yes | Search query (min: 2, max: 100 chars) |
| `page` | integer | No | Page number (default: 1) |
| `limit` | integer | No | Items per page (default: 20, max: 50) |

**Example Request:**
```
GET /api/search?q=birkin&page=1&limit=10
```

**Response:**
```json
{
  "success": true,
  "query": "birkin",
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 45,
    "totalPages": 5
  }
}
```

---

### Get Brand Analytics
**GET** `/api/brands`

Returns analytics for all brands including total auctions, average prices, and savings.

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "brand": "Hermes Birkin",
      "total_auctions": 150,
      "avg_price": 9500,
      "min_price": 3000,
      "max_price": 25000,
      "avg_savings_percent": 18.5,
      "with_price": 145
    }
  ],
  "total_brands": 22
}
```

---

### Get Trending Auctions
**GET** `/api/trending`

Returns auctions with the highest savings percentages.

**Query Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | integer | 20 | Number of results |

**Example Request:**
```
GET /api/trending?limit=10
```

**Response:**
```json
{
  "success": true,
  "data": [ ... ],
  "count": 10
}
```

---

### Get Best Values
**GET** `/api/best-values`

Returns best value auctions sorted by savings.

**Query Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `sort` | string | percent | Sort by 'percent' or 'dollar' savings |
| `limit` | integer | 100 | Number of results |

**Response:**
```json
{
  "success": true,
  "count": 100,
  "data": [ ... ],
  "sortedBy": "percent"
}
```

---

### Get Statistics
**GET** `/api/stats`

Returns overall statistics and recent activity.

**Response:**
```json
{
  "success": true,
  "stats": {
    "total": 1000,
    "byBrand": [
      { "search_term": "Hermes Birkin", "count": 150 }
    ],
    "byAuctionHouse": [
      { "auction_house": "Christie's", "count": 300 }
    ],
    "avgPrice": 8500,
    "priceRange": {
      "min_price": 500,
      "max_price": 50000
    },
    "recentActivity": [
      { "date": "2025-11-17", "count": 25 }
    ]
  }
}
```

---

### Get Scraper Status
**GET** `/api/scraper/status`

Returns information about scraper runs and health.

**Response:**
```json
{
  "success": true,
  "lastScrape": "2025-11-17T06:00:00Z",
  "lastBrand": "Hermes Birkin",
  "dailyStats": [
    { "date": "2025-11-17", "count": 25 }
  ],
  "recentLogs": [ ... ],
  "logFile": "/path/to/scraper.log",
  "nextScheduledRun": "06:00 UTC daily"
}
```

---

### Get Metrics
**GET** `/api/metrics`

Returns server performance metrics.

**Response:**
```json
{
  "success": true,
  "metrics": {
    "apiCalls": 1500,
    "errors": 5,
    "cacheHits": 800,
    "cacheMisses": 200,
    "avgResponseTime": 15.5,
    "uptime": 86400,
    "memory": {
      "rss": 50000000,
      "heapTotal": 20000000,
      "heapUsed": 15000000
    },
    "cacheStats": { ... }
  }
}
```

---

### Clear Cache (Admin)
**POST** `/api/cache/clear`

Clears all cached responses.

**Response:**
```json
{
  "success": true,
  "message": "Cleared 25 cache entries"
}
```

---

### Get Logs
**GET** `/api/logs`

Returns recent scraper logs.

**Query Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `lines` | integer | 100 | Number of log lines |

**Response:**
```json
{
  "success": true,
  "logs": [ ... ],
  "count": 100
}
```

---

### Download CSV
**GET** `/api/download-csv`

Downloads the complete auction history as CSV file.

**Response:** File download

---

### System Status (Legacy)
**GET** `/api/status`

Returns basic system file status (backward compatible).

**Response:**
```json
{
  "success": true,
  "status": {
    "database": true,
    "csv": true,
    "logs": true,
    "dbSize": 16384,
    "csvSize": 1024,
    "logSize": 2048
  }
}
```

---

## Error Responses

All errors follow this format:
```json
{
  "success": false,
  "error": "Error message",
  "details": "Additional details if available"
}
```

**HTTP Status Codes:**
- `200` - Success
- `400` - Bad Request (invalid parameters)
- `429` - Too Many Requests (rate limit exceeded)
- `500` - Internal Server Error

---

## Caching

Responses are cached for 5 minutes to improve performance. Cached responses include `"cached": true` in the response body.

Cache can be cleared via the `/api/cache/clear` endpoint.

---

## Best Practices

1. **Use pagination** for large datasets
2. **Implement client-side caching** to reduce API calls
3. **Respect rate limits** to avoid throttling
4. **Use specific filters** instead of fetching all data
5. **Monitor the health endpoint** for system status

---

## Example Usage

### JavaScript (Fetch API)
```javascript
// Get paginated auctions with filters
async function getAuctions() {
  const params = new URLSearchParams({
    page: 1,
    limit: 20,
    sort: 'savings_desc',
    brand: 'hermes',
    min_savings: 1000
  });

  const response = await fetch(`http://45.61.58.125:7500/api/auctions?${params}`);
  const data = await response.json();

  if (data.success) {
    console.log(`Found ${data.pagination.total} auctions`);
    data.data.forEach(auction => {
      console.log(`${auction.title}: $${auction.current_price} (${auction.savings_percent}% off)`);
    });
  }
}
```

### Python (Requests)
```python
import requests

# Search for auctions
response = requests.get('http://45.61.58.125:7500/api/search', params={
    'q': 'birkin',
    'page': 1,
    'limit': 10
})

data = response.json()
if data['success']:
    print(f"Found {data['pagination']['total']} results")
    for auction in data['data']:
        print(f"{auction['title']}: ${auction['current_price']}")
```

### cURL
```bash
# Get trending auctions
curl "http://45.61.58.125:7500/api/trending?limit=10"

# Search with filters
curl "http://45.61.58.125:7500/api/auctions?page=1&limit=20&brand=chanel&sort=price_desc"

# Check health
curl "http://45.61.58.125:7500/api/health"
```

---

## Database Schema

### auctions table
```sql
CREATE TABLE auctions (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  auction_id TEXT UNIQUE,
  title TEXT,
  auction_house TEXT,
  current_price REAL,
  estimate_low REAL,
  estimate_high REAL,
  end_date TEXT,
  lot_number TEXT,
  url TEXT,
  search_term TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

### Indexes
- `idx_auctions_search_term` on `search_term`
- `idx_auctions_auction_house` on `auction_house`
- `idx_auctions_current_price` on `current_price`
- `idx_auctions_created_at` on `created_at`
- `idx_auctions_estimate_low` on `estimate_low`
- `idx_auctions_brand_price` on `(search_term, current_price)`
- `idx_auctions_price_estimate` on `(current_price, estimate_low)`

---

## Migration System

Run database migrations:
```bash
node migrations.js migrate
```

Check migration status:
```bash
node migrations.js status
```

Archive old auctions:
```bash
node migrations.js archive [days]
```

Optimize database:
```bash
node migrations.js optimize
```

---

## Monitoring

The API includes built-in monitoring:
- **Health checks** at `/api/health`
- **Metrics collection** at `/api/metrics`
- **Structured logging** with timestamps
- **Performance tracking** (response times, cache hit rates)
- **Error tracking** with detailed logs

Metrics are logged to `/data/auction-history/metrics.log` every minute.

---

## Support

For issues or questions, check the logs:
- API logs: Console output (JSON formatted)
- Scraper logs: `/data/auction-history/scraper.log`
- Error logs: `/data/auction-history/scraper-errors.log`
- Metrics logs: `/data/auction-history/metrics.log`