@marcohefti/request-network-api-client 0.5.1 → 0.5.5

package/README.md

@@ -1,26 +1,29 @@
 # Request Network API Client (TypeScript)
 
-TypeScript client for the Request Network hosted REST API. It provides typed, ergonomic
-helpers for core API domains such as requests, payouts, payer/compliance, client IDs,
-currencies, and payments, with runtime validation and webhook utilities built in.
+TypeScript client for the Request Network hosted REST API. Provides typed, ergonomic helpers for requests, payouts, payer/compliance, client IDs, currencies, and payments, with runtime validation and webhook utilities built in.
 
-This package targets the hosted REST API, not the protocol SDK.
+**Note**: This targets the hosted REST API, not the protocol SDK. See [SCOPE.md](docs/SCOPE.md) for when to use which.
 
 ## Installation
 
-Install via npm or pnpm:
-
 ```bash
-# npm
 npm install @marcohefti/request-network-api-client
-
-# pnpm
+# or
 pnpm add @marcohefti/request-network-api-client
+# or
+yarn add @marcohefti/request-network-api-client
 ```
 
-## Quick start
+## Features
 
-Node (API key) – tested on Node 20.x–24.x with the built‑in `fetch`:
+- **Typed API**: Full TypeScript support with types generated from OpenAPI spec
+- **Runtime Validation**: Zod schemas validate requests/responses (configurable)
+- **Webhook Helpers**: Signature verification, middleware, and event dispatchers
+- **Error Handling**: Consistent error model with retry/backoff
+- **Tree-Shakable**: Subpath exports for minimal bundle size
+- **Universal**: Works in Node 20+, browsers, and edge runtimes
+
+## Quick Start
 
 ```ts
 import {
@@ -34,64 +37,119 @@ const client = createRequestClient({
   apiKey: process.env.REQUEST_API_KEY!,
 });
 
-async function main() {
-  try {
-    const tokens = await client.currencies.list({ network: 'sepolia' });
-    console.log('Currencies:', tokens.length);
-  } catch (err) {
-    if (isRequestApiError(err)) {
-      console.error('API error', err.status, err.code, err.requestId, err.toJSON());
-    } else {
-      console.error(err);
-    }
+// Create a request
+const request = await client.requests.create({
+  amount: '12.5',
+  invoiceCurrency: 'USD',
+  paymentCurrency: 'USDC-sepolia',
+});
+
+// List currencies
+const tokens = await client.currencies.list({ network: 'sepolia' });
+
+// Error handling
+try {
+  await client.payments.search({ walletAddress: '0xabc' });
+} catch (err) {
+  if (isRequestApiError(err)) {
+    console.error('API error', err.status, err.code, err.requestId);
   }
 }
-
-main();
 ```
 
-From env:
+**From environment variables**:
 
 ```ts
 import { createRequestClientFromEnv } from '@marcohefti/request-network-api-client';
 
 const client = createRequestClientFromEnv();
-// Reads REQUEST_API_URL, REQUEST_API_KEY, REQUEST_CLIENT_ID (with legacy REQUEST_SDK_* fallbacks)
+// Reads: REQUEST_API_URL, REQUEST_API_KEY, REQUEST_CLIENT_ID
 ```
 
-## What this client covers
+## Documentation
 
-- REST v2 domains: requests, payouts, payer/compliance, payments, client IDs, currencies.
-- Legacy v1 routes where needed (via `client.<domain>.legacy` or versioned barrels).
-- Webhook helpers: signature verification, parser, dispatcher, and testing utilities.
-- Runtime validation via Zod schemas generated from the Request OpenAPI spec.
+- **[Quick Start](docs/QUICK-START.md)** - Installation, environment setup, common recipes
+- **[Domains](docs/DOMAINS.md)** - API reference for all domains (requests, payouts, payer, payments, currencies, client IDs)
+- **[HTTP & Errors](docs/HTTP-AND-ERRORS.md)** - HTTP client configuration, error handling, retry behavior
+- **[Webhooks](docs/WEBHOOKS.md)** - Signature verification, middleware, event handlers, local dev setup
+- **[Scope](docs/SCOPE.md)** - When to use this client vs the protocol SDK
+- **[Architecture](docs/ARCHITECTURE.md)** - System design and internals
+- **[Testing](docs/TESTING.md)** - Test strategy, commands, and coverage
+- **[Publishing](docs/PUBLISHING.md)** - Release checklist
+- **[Endpoints](docs/ENDPOINTS.md)** - API endpoint reference
 
-For deeper details (HTTP client options, domain facades, webhooks, error model), see:
+## Compatibility
 
-- Architecture: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
-- Endpoints & behaviour notes: [`docs/ENDPOINTS.md`](docs/ENDPOINTS.md)
-- Testing & live suites: [`docs/TESTING.md`](docs/TESTING.md)
-- Publishing checklist: [`docs/PUBLISHING.md`](docs/PUBLISHING.md)
-- Docs site (VitePress): `docs-site/` (see `pnpm docs:dev` and `pnpm docs:build`)
+| Runtime | Versions |
+|---------|----------|
+| Node.js | 20.x, 22.x, 24.x |
+| Browsers | Modern browsers with Fetch API |
+| Edge Runtimes | Cloudflare Workers, Vercel Edge, Deno, Bun |
 
-## Compatibility
+**Package Manager**: pnpm 10.17.1 recommended (`corepack enable pnpm@10.17.1`)
+
+## Versioning
+
+This package follows SemVer. While on `0.x`, minor/patch releases may include breaking changes as the API surface stabilizes. Once `1.0.0` is reached, breaking changes will require a major version bump.
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## Troubleshooting
+
+**API Key Issues**
+- Ensure `REQUEST_API_KEY` is set and has necessary permissions
+- Test with a simple call: `await client.currencies.list({ network: 'sepolia' })`
+
+**Runtime Validation Errors**
+- The API response didn't match the expected schema
+- Check you're using the latest client version
+- Temporarily disable validation to debug: `runtimeValidation: false`
 
-- Node.js: 20 / 22 / 24
-- Package manager: pnpm 10.17.1 (recommended via `corepack enable pnpm@10.17.1`)
+**Timeout Issues**
+- Set custom timeout: `await client.currencies.list({ network: 'sepolia' }, { timeoutMs: 10_000 })`
 
-## Versioning & support
+**Rate Limiting (429)**
+- The client auto-retries with exponential backoff
+- Override retry policy: `meta: { retry: { maxAttempts: 5 } }`
 
-- Versioning: this package follows SemVer, but while the major version is `0.x`, minor and patch releases may include breaking changes as the surface stabilises.
-- Support & issues: report bugs or request features via GitHub issues on [`marcohefti/request-network-api-client-ts`](https://github.com/marcohefti/request-network-api-client-ts).
+See [HTTP-AND-ERRORS.md](docs/HTTP-AND-ERRORS.md) for detailed error handling patterns.
+
+## Support & Security
+
+- **Issues**: Report bugs or request features via [GitHub Issues](https://github.com/marcohefti/request-network-api-client-ts/issues)
+- **Security**: See [SECURITY.md](SECURITY.md) for disclosure policy
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines
 
 ## Development
 
-Common commands:
+**Prerequisites**: Node 20/22/24, pnpm 10.17.1
+
+```bash
+# Install dependencies
+pnpm install
+
+# Type-check
+pnpm typecheck
+
+# Lint
+pnpm lint
+
+# Run tests
+pnpm test
+
+# Build
+pnpm build
+```
+
+**Full validation** (before submitting PRs):
+
+```bash
+pnpm coverage:matrix  # Node 20/22/24 coverage matrix
+pnpm build            # Verify packaging
+```
+
+See [TESTING.md](docs/TESTING.md) for test strategy and [CONTRIBUTING.md](CONTRIBUTING.md) for coding guidelines.
 
-- `pnpm lint` – lint the source and tests.
-- `pnpm typecheck` – run TypeScript diagnostics (`tsc`).
-- `pnpm test` – run the Vitest suite (MSW + OpenAPI parity guards).
-- `pnpm build` – build CJS/ESM + types into `dist/`.
+## License
 
-See [`docs/TESTING.md`](docs/TESTING.md) for the full test/coverage matrix and live integration setup, and
-[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the HTTP pipeline and domain layout.
+MIT - See [LICENSE](LICENSE) for details.

package/dist/cjs/index.js

@@ -3385,8 +3385,8 @@ function isAgreementRejected(payload) {
 }
 function complianceStatusSummary(payload) {
   const parts = [];
-  const kyc = payload.kycStatus ? String(payload.kycStatus).replace(/_/g, " ") : "unknown";
-  const agreement = payload.agreementStatus ? String(payload.agreementStatus).replace(/_/g, " ") : "unknown";
+  const kyc = payload.kycStatus ? payload.kycStatus.replace(/_/g, " ") : "unknown";
+  const agreement = payload.agreementStatus ? payload.agreementStatus.replace(/_/g, " ") : "unknown";
   parts.push(`KYC: ${kyc}`);
   parts.push(`Agreement: ${agreement}`);
   if (payload.clientUserId) {