peeringdb/readme.hints.md

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:

{
  "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