89 lines
2.6 KiB
Markdown
89 lines
2.6 KiB
Markdown
# 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 |