# Implementation Notes

## Architecture

This package implements a comprehensive TypeScript client for the PeeringDB API.

### Key Components

1. **Client Class** (`PeeringDbClient`)
   - Main entry point for the API
   - Uses @push.rocks/smartrequest fluent API
   - Automatic retry with 429 rate limiting handling
   - Supports both anonymous and authenticated requests

2. **Manager Classes** (10 managers)
   - OrganizationManager - Organizations
   - NetworkManager - Networks/ASNs
   - FacilityManager - Colocation facilities
   - ExchangeManager - Internet Exchanges
   - NetIxLanManager - Network-IX connections
   - NetFacManager - Network-facility connections
   - IxLanManager - IX LAN information
   - IxFacManager - IX-facility connections
   - IxPfxManager - IX IP prefixes
   - PocManager - Points of contact

3. **Type Definitions**
   - Comprehensive TypeScript interfaces for all resources
   - Type-safe query options
   - Field filter types

### HTTP Client

Uses @push.rocks/smartrequest with the fluent API:
- `.retry(3)` for automatic retry on failures including 429 rate limits
- Chainable methods for building requests
- Automatic JSON parsing
- **User-Agent header required**: PeeringDB API blocks requests without proper User-Agent
  - Format: `@apiclient.xyz/peeringdb/1.0.1 (Node.js)`
  - Without it, API returns 403 Forbidden

### Response Handling

PeeringDB API returns responses in this format:
```json
{
  "meta": {
    "status": "ok",
    "message": "optional"
  },
  "data": [...]
}
```

The client automatically unwraps the `data` array for convenience.

### Query Options

All manager list/search methods support:
- `limit` - Pagination limit
- `skip` - Offset for pagination
- `fields` - Field selection
- `depth` - Nested object expansion (0, 1, 2)
- `since` - Unix timestamp for recent updates
- `autoPaginate` - Auto-fetch all pages
- Field filters with operators (`__contains`, `__startswith`, `__in`, `__lt`, `__gte`, etc.)

### Testing

Tests use @git.zone/tstest and hit the real PeeringDB API anonymously.
To run tests: `pnpm test`

**Test Results:**
- Node.js: All 18 tests pass ✅
- Bun/Deno: Limited support due to smartrequest runtime compatibility issues

The package is fully functional and tested in Node.js, which is the primary target runtime.

### Rate Limiting

The smartrequest library automatically handles 429 responses with exponential backoff retry.

## Development Notes

- Follow sibling project patterns (DigitalOcean, GitLab, Cloudflare)
- Use fluent API for all HTTP requests
- Manager classes provide CRUD operations
- Convenience methods for common use cases
- Logging via @push.rocks/smartlog