SimpleHttpSkill

---

name: simple-http description: Make HTTP requests (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS) with custom headers, automatic retries, and graceful error handling. Use when the user needs to call an API, fetch a URL, send webhooks, or make any HTTP request without external dependencies.

---

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 " },
  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).