Simple HTTP Skill

Make HTTP requests using only Node.js built-in modules. Supports all standard methods, arbitrary headers, automatic retries with exponential backoff, and never throws on failure — always resolves with an inspectable response object.

Required Inputs

• url (string): Fully qualified URL to request.
• method (string, optional): HTTP method. Default GET.
• headers (object, optional): Request headers.
• body (string | Buffer | object, optional): Request body. Objects are auto-serialized to JSON.
• maxRetries (number, optional): Retry attempts for transient failures. Default 3.
• timeout (number, optional): Socket timeout in ms. Default 30000.

Step-by-Step Workflow

1. Import the client from src/http-client.js:

const { HttpClient } = require("./src/http-client");

2. Create a client instance (optionally set default headers shared across calls):

const client = new HttpClient({
  defaultHeaders: { Authorization: "Bearer <token>" },
  maxRetries: 3,
});

3. Make requests using convenience methods or the generic request():

// GET
const resp = await client.get("https://api.example.com/items");

// POST with JSON body
const resp = await client.post("https://api.example.com/items", {
  body: { name: "widget" },
});

// PUT with custom headers
const resp = await client.put("https://api.example.com/items/1", {
  headers: { "X-Request-Id": "abc123" },
  body: { name: "updated" },
});

// DELETE
const resp = await client.delete("https://api.example.com/items/1");

// Generic form — any method
const resp = await client.request("PATCH", "https://api.example.com/items/1", {
  body: { qty: 5 },
});

4. Inspect the response:

if (resp.ok) {
  console.log(resp.body);      // parsed JSON or raw string
  console.log(resp.status);    // e.g. 200
  console.log(resp.headers);   // response headers object
} else {
  console.log(resp.error);     // human-readable error (null if HTTP error with status)
  console.log(resp.status);    // HTTP status code or null for network errors
}

Output Format

Every call resolves with an object containing:

Key	Type	Description
ok	boolean	true if status is 2xx
status	number | null	HTTP status code; null for network-level errors
headers	object	Response headers
body	any	Parsed JSON (if content-type is JSON), else string
error	string | null	Error description on failure; null on success

Error Handling & Retry Behavior

• Retried automatically: Connection errors, timeouts, and HTTP 429 / 5xx responses.
• Not retried: 4xx errors (except 429) — returned immediately.
• Backoff: Exponential with jitter (base 500ms, capped at 30s).
• Graceful failure: The client never throws. After exhausting retries, it resolves with the last error response so the caller can always inspect resp.ok and resp.error.

Configuration Options

All options can be set at the client level (constructor) and overridden per-request:

Option	Default	Description
defaultHeaders	{}	Headers applied to every request
maxRetries	3	Max retry attempts
timeout	30000	Socket timeout in ms
backoffBase	500	Base delay (ms) for exponential backoff
backoffMax	30000	Maximum backoff delay cap (ms)

Dependencies

None — uses only Node.js built-in modules (http, https, url).