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

package/README.md

@@ -1,5 +1,9 @@
 # Request Network API Client (TypeScript)
 
+[![npm version](https://img.shields.io/npm/v/@marcohefti/request-network-api-client.svg)](https://www.npmjs.com/package/@marcohefti/request-network-api-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js CI](https://github.com/marcohefti/request-network-api-client-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/marcohefti/request-network-api-client-ts/actions/workflows/ci.yml)
+
 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.
 
 **Note**: This targets the hosted REST API, not the protocol SDK. See [SCOPE.md](docs/SCOPE.md) for when to use which.
@@ -57,15 +61,6 @@ try {
 }
 ```
 
-**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
-```
-
 ## Documentation
 
 - **[Quick Start](docs/QUICK-START.md)** - Installation, environment setup, common recipes
@@ -96,23 +91,138 @@ See [CHANGELOG.md](CHANGELOG.md) for release history.
 
 ## Troubleshooting
 
-**API Key Issues**
-- Ensure `REQUEST_API_KEY` is set and has necessary permissions
+### Common Issues
+
+#### API Key Problems
+
+**Error: 401 Unauthorized**
+- Ensure `REQUEST_API_KEY` is set correctly in your environment
+- Verify your API key is active in the Request API Portal
 - Test with a simple call: `await client.currencies.list({ network: 'sepolia' })`
+- Check for extra whitespace or quotes in your environment variable
+
+```bash
+# Verify your API key is set
+echo $REQUEST_API_KEY
+
+# Test with a simple command
+node -e "import('@marcohefti/request-network-api-client').then(m => m.createRequestClient({apiKey: process.env.REQUEST_API_KEY}).currencies.list()).then(console.log)"
+```
+
+#### CORS Errors (Browser)
+
+**Error: CORS policy blocks request**
+- Ensure you're using a Client ID, not an API key (API keys are server-only)
+- Verify your domain is in the `allowedDomains` list for your Client ID
+- Check the domain matches exactly (including protocol and port)
+- For localhost development, use `http://localhost:3000` format
+
+```typescript
+// ❌ Wrong - Using API key in browser
+const client = createRequestClient({
+  apiKey: 'rk_live_...'  // This will fail with CORS
+});
+
+// ✅ Correct - Using Client ID in browser
+const client = createRequestClient({
+  clientId: 'client_live_...'
+});
+```
+
+#### Module Not Found Errors
+
+**Error: Cannot find module '@marcohefti/request-network-api-client'**
+- Run `pnpm install` or `npm install`
+- Clear node_modules and reinstall: `rm -rf node_modules && pnpm install`
+- Check package.json includes the dependency
+- For local development, run `pnpm build` in the package directory
 
-**Runtime Validation Errors**
+**Error: Cannot find module '@marcohefti/request-network-api-client/requests'**
+- Ensure you're using the correct import path
+- Check package.json `exports` field matches your import
+- Update to the latest version: `pnpm update @marcohefti/request-network-api-client`
+
+#### Type Errors
+
+**Error: Property does not exist on type**
+- Ensure you're using the latest version of the client
+- Run `pnpm update @marcohefti/request-network-api-client`
+- Check your TypeScript version is >= 5.0
+- Clear TypeScript cache: `rm -rf node_modules/.cache`
+
+#### Runtime Validation Errors
+
+**Error: ValidationError - Response validation failed**
 - The API response didn't match the expected schema
-- Check you're using the latest client version
+- This usually means the API has changed or there's a bug
+- Update to the latest client version: `pnpm update @marcohefti/request-network-api-client`
 - Temporarily disable validation to debug: `runtimeValidation: false`
+- Report the issue with the full error message
+
+```typescript
+// Debug validation errors
+const client = createRequestClient({
+  apiKey: process.env.REQUEST_API_KEY,
+  runtimeValidation: false,  // Temporarily disable
+});
+```
+
+#### Timeout Issues
+
+**Error: Request timeout / AbortError**
+- Increase timeout for slow operations: `{ timeoutMs: 30_000 }`
+- Check your network connection
+- Verify the API is accessible: `curl https://api.request.network/v2/currencies`
+- Try with a different network/endpoint
+
+```typescript
+// Increase timeout for slow endpoints
+await client.requests.create(
+  { /* ... */ },
+  { timeoutMs: 30_000 }  // 30 seconds
+);
+```
 
-**Timeout Issues**
-- Set custom timeout: `await client.currencies.list({ network: 'sepolia' }, { timeoutMs: 10_000 })`
+#### Rate Limiting (429)
 
-**Rate Limiting (429)**
+**Error: Rate limit exceeded**
 - The client auto-retries with exponential backoff
-- Override retry policy: `meta: { retry: { maxAttempts: 5 } }`
+- Check `err.retryAfterMs` for when to retry
+- Reduce request frequency in your application
+- Consider caching responses for repeated queries
+
+```typescript
+try {
+  await client.currencies.list();
+} catch (err) {
+  if (isRequestApiError(err) && err.status === 429) {
+    console.log(`Rate limited. Retry after ${err.retryAfterMs}ms`);
+    // Client will automatically retry
+  }
+}
+```
+
+#### Network/Connection Errors
+
+**Error: fetch failed / ECONNREFUSED**
+- Check your internet connection
+- Verify API endpoint is accessible
+- Check for proxy/firewall blocking requests
+- Try setting a custom base URL: `baseUrl: 'https://api.request.network'`
+
+### Getting Help
+
+If you're still stuck:
 
-See [HTTP-AND-ERRORS.md](docs/HTTP-AND-ERRORS.md) for detailed error handling patterns.
+1. Check the [examples](examples/) directory for working code
+2. Review [HTTP-AND-ERRORS.md](docs/HTTP-AND-ERRORS.md) for detailed error handling
+3. Search [existing issues](https://github.com/marcohefti/request-network-api-client-ts/issues)
+4. Create a new issue with:
+   - Client version (`@marcohefti/request-network-api-client@x.x.x`)
+   - Node.js version (`node --version`)
+   - Minimal code sample that reproduces the issue
+   - Full error message and stack trace
+   - Request ID from error (if available)
 
 ## Support & Security
 

package/dist/cjs/index.js

@@ -2310,13 +2310,6 @@ function createRequestClient(options) {
     pay: createPayApi(http)
   };
 }
-function createRequestClientFromEnv(options) {
-  const env = options?.env ?? process.env;
-  const baseUrl = env.REQUEST_API_URL ?? env.REQUEST_SDK_BASE_URL;
-  const apiKey = env.REQUEST_API_KEY ?? env.REQUEST_SDK_API_KEY;
-  const clientId = env.REQUEST_CLIENT_ID ?? env.REQUEST_SDK_CLIENT_ID;
-  return createRequestClient({ baseUrl, apiKey, clientId });
-}
 
 // src/core/config/request-environment.config.ts
 var RequestEnvironment = {
@@ -3443,7 +3436,6 @@ exports.clientIds = client_ids_exports;
 exports.computeRetryDelay = computeRetryDelay;
 exports.createHttpClient = createHttpClient;
 exports.createRequestClient = createRequestClient;
-exports.createRequestClientFromEnv = createRequestClientFromEnv;
 exports.currencies = currencies_exports;
 exports.currenciesV1 = v1_exports;
 exports.isRequestApiError = isRequestApiError;