initial

readme.hints.md

@@ -0,0 +1,89 @@
+# 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