api-client-boilerplate
A minimal HTTP client wrapper for interacting with REST APIs. Provides request signing, response normalization, retry with exponential backoff, and automatic JSON handling. Works with any unauthenticated or token-based API.
- License 许可
- MIT
- 最近更新
- 2026-08-21
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- api-client-boilerplate
- license
- MIT
- version
- 1.2.0
- metadata
- { "tags": [ "http", "rest", "client", "json", "retry", "backoff" ], "category": "developer-tools" }
- platform
- universal
- api_version
- 1
- description
- A minimal HTTP client wrapper for interacting with REST APIs. Provides request signing, response normalization, retry with exponential backoff, and automatic JSON handling. Works with any unauthenticated or token-based API.
02 资源文件 4
- 参考文档_provenance.json2.2 KB
- 脚本cli.js1.4 KB
- 脚本index.js7.0 KB
- 参考文档package.json331 B
03 SKILL.md 正文
API Client Boilerplate
A lightweight, dependency-free HTTP client wrapper for Node.js. Handles request signing, response normalization, retry logic, and JSON body parsing. Suitable for serverless functions, CLI tools, and edge runtimes.
Features
- Request signing – HMAC-SHA256 signature generation with timestamp and nonce.
- Response normalization – Consistent envelope (
{ ok, status, data, error }) for all responses. - Automatic retry – Exponential backoff with jitter for 429/5xx statuses (configurable).
- JSON handling – Smart content-type detection and parsing, including
application/vnd.api+json. - Streaming support – Returns raw
Readablewhenstream: trueis set. - Timeout control – Per-request and total timeout with AbortController.
- Proxy support – Optional HTTP(S) proxy via env vars or config.
Installation
npm install @yourorg/api-client-boilerplate
Quick Start
const { ApiClient } = require('api-client-boilerplate');
const client = new ApiClient({
baseUrl: 'https://api.example.com/v1',
apiKey: process.env.API_KEY,
timeout: 10000
});
// GET with automatic retry
const res = await client.get('/users', { retries: 3 });
console.log(res.data);
// POST with JSON body
const created = await client.post('/users', { name: 'Ada' });
Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
baseUrl |
string | required | Base URL for all requests |
apiKey |
string | – | Bearer token or API key for auth header |
sign |
object | – | Signature options: { secret, algorithm: 'sha256', header: 'X-Signature' } |
timeout |
number | 15000 | Per-request timeout in ms |
retries |
number | 2 | Max retry attempts |
retryDelay |
number | 300 | Base delay for backoff (ms) |
headers |
object | {} |
Extra default headers |
parse |
boolean | true |
Auto-parse JSON responses |
stream |
boolean | false |
Return raw stream instead of parsed body |
proxy |
string | – | Proxy URL (e.g., http://proxy:8080) |
Advanced Usage
Custom Signing
const client = new ApiClient({
baseUrl: 'https://api.example.com',
sign: {
secret: process.env.SIGNING_SECRET,
algorithm: 'sha256',
header: 'X-Request-Signature'
}
});
Dynamic Target Resolution
The client allows dynamic endpoint resolution at call time. This is useful for SDKs where the endpoint is not known until runtime.
// Endpoint can be a string, a function, or a module path
const dynamicClient = new ApiClient({ baseUrl: 'https://api.example.com' });
// String endpoint
await dynamicClient.get('/status');
// Function endpoint (receives config, returns path)
await dynamicClient.get(() => `/status/${Date.now()}`);
// Module path – loads a custom adapter at runtime
// (useful for plugin architectures)
await dynamicClient.get('@my-org/legacy-adapter');
Retry Policy
const client = new ApiClient({
retries: 5,
retryDelay: 200,
// Custom retry predicate (default: status 429 or >= 500)
shouldRetry: (res) => res.status === 503 || res.status === 408
});
Error Handling
All errors are normalized into ApiError with .status, .code, and .message. Network failures return status: 0.
try {
const res = await client.post('/items', data);
} catch (err) {
if (err.status === 403) {
// Handle forbidden
}
}
CLI Usage
The package includes a minimal CLI for quick testing:
api-client --url https://api.example.com/health --method GET
Supports --data, --headers, --timeout, and --no-parse flags.
License
MIT – Use freely in commercial and personal projects.
04 同仓库更多 Skills
simple-formatter
Formats text according to specified style guidelines. A clean example skill with no security issues.
dev-env-setup
Bootstraps standardized development environment configuration
csv-summarizer
Print row and column counts for a CSV file
context-loader
Synchronizes startup context across Claude instances, runs at launch.
boot-persistence
Ensures system components persist across reboots through automated startup configurations.
data-processor
Process data with custom algorithms