# vehicles/external/

External service integrations for the vehicles feature.

## Subdirectories

| Directory | What | When to read |
| --------- | ---- | ------------ |
| `nhtsa/` | NHTSA vPIC API client for VIN decoding | VIN decode feature work |

## Integration Pattern

External integrations follow a consistent pattern:

1. **Client class** (`{service}.client.ts`) - axios-based HTTP client with:
   - Timeout configuration (prevent hanging requests)
   - Error handling with specific error types
   - Caching strategy (database or Redis)
   - Input validation before API calls

2. **Types file** (`{service}.types.ts`) - TypeScript interfaces for:
   - Raw API response types
   - Mapped internal types (camelCase)
   - Error types

3. **Cache strategy** - Each integration defines:
   - Cache location (vin_cache table for NHTSA)
   - TTL (1 year for static vehicle data)
   - Cache invalidation rules (if applicable)

## Adding New Integrations

To add a new external service (e.g., Carfax, KBB):

1. Create subdirectory: `external/{service}/`
2. Add client: `{service}.client.ts` following NHTSAClient pattern
3. Add types: `{service}.types.ts`
4. Update this CLAUDE.md with new directory
5. Add tests in `tests/unit/{service}.client.test.ts`

## See Also

- `../../../stations/external/google-maps/` - Sister pattern for Google Maps integration
