Simple HTTP Skill

intent

Make HTTP requests using only Node.js built-in modules without external dependencies. Use this skill when you need to call an API, fetch a URL, send webhooks, or make any HTTP request with automatic retry logic, custom headers, and graceful error handling that never throws. The client always resolves with an inspectable response object so you can handle both success and failure paths predictably.

inputs

• url (string, required): fully qualified URL to request (http:// or https://).
• method (string, optional): HTTP verb. default GET. accepts GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.
• headers (object, optional): custom request headers merged with defaultHeaders. object keys are header names (case-insensitive).
• body (string | Buffer | object, optional): request body. objects auto-serialize to JSON with content-type application/json. strings and buffers sent as-is.
• maxRetries (number, optional): retry attempts for transient failures. default 3. set to 0 to disable retries.
• timeout (number, optional): socket timeout in milliseconds. default 30000 (30 seconds). connection fails if exceeded.
• backoffBase (number, optional): base delay in milliseconds for exponential backoff. default 500.
• backoffMax (number, optional): maximum backoff delay cap in milliseconds. default 30000.
• defaultHeaders (object, optional, client-level): headers applied to every request made by this client instance. useful for auth tokens or api keys.

no external connections required. uses node.js http and https modules only.

procedure

1. import the client from src/http-client.js and create an instance:

const { HttpClient } = require("./src/http-client");
const client = new HttpClient({
  defaultHeaders: { Authorization: "Bearer <token>" },
  maxRetries: 3,
  timeout: 30000
});

2. make a GET request:

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

output: response object with keys ok, status, headers, body, error.

3. make a POST request with JSON body:

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

output: response object. status is 201 or 200 on success, body contains server response.

4. make a PUT request with custom headers:

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

output: response object. custom headers merged with defaultHeaders. body sent as JSON.

5. make a DELETE request:

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

output: response object. typically 204 or 200 on success, body may be empty.

6. make a generic request with any HTTP method:

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

output: response object. method can be any HTTP verb.

7. inspect the response:

if (resp.ok) {
  console.log("success:", resp.status, resp.body);
} else {
  console.log("failed:", resp.status, resp.error);
}

output: branching logic based on resp.ok boolean flag.

decision points

• if status is 2xx (200-299): resp.ok is true. treat as success. resp.error is null. inspect resp.body for data.
• if status is 429 (too many requests) or 5xx (500-599): client retries automatically up to maxRetries times with exponential backoff. if all retries exhausted, resolves with last error response. resp.ok is false, resp.error contains reason.
• if status is 4xx (400-499) except 429: client does not retry. returns immediately with resp.ok false. resp.error is null (use resp.status to distinguish from network errors).
• if network error (connection refused, hostname not found, socket timeout): client retries automatically. if all retries exhausted, resp.status is null and resp.error contains the error message. resp.ok is false.
• if body is an object: client auto-serializes to JSON and sets content-type header to application/json. if body is string or buffer, sent as-is.
• if response content-type is application/json: resp.body is parsed JSON object or array. if parsing fails, body is the raw string.
• if response content-type is not JSON: resp.body is raw string.
• if timeout exceeded: treated as network error. client retries if maxRetries > 0. after retries exhausted, resolves with resp.status null and resp.error with timeout message.
• if url is malformed or not fully qualified: client may throw on parsing. always validate url before passing to client.
• if defaultHeaders conflict with request headers: request-level headers take precedence. merging is shallow (headers object completely overwrites defaultHeaders, not deep merge).

output contract

every call resolves (never rejects) with a response object:

{
  ok: boolean,              // true if status 200-299, false otherwise
  status: number | null,    // http status code (e.g. 200, 404, 500) or null on network failure
  headers: object,          // response headers as key-value pairs (header names lowercase)
  body: any,                // parsed json (if content-type json), else string, else empty string
  error: string | null      // human-readable error message on failure, null on success
}

response is always an object. no exceptions thrown. caller must always check resp.ok or resp.error to determine outcome.

if request is retried, only the final attempt response is returned. intermediate retry attempts are not visible to the caller.

outcome signal

you know the skill worked when:

• resp.ok is true and resp.status is in the 200-299 range.
• resp.body contains the expected data (parsed JSON or string).
• resp.headers contains response headers including content-type, content-length, etc.
• resp.error is null.

you know the skill failed when:

• resp.ok is false.
• resp.error is a non-null string describing the failure (e.g. "socket timeout", "connection refused", "unable to parse response").
• resp.status is a 4xx or 5xx code, or null if network-level failure.
• if you expected JSON but resp.body is a string, check resp.headers['content-type'] to confirm server sent JSON.

common success indicators: status 200 (GET, POST, PUT, PATCH), 201 (POST create), 204 (DELETE, no content).

common failure indicators: status 400 (bad request), 401 (unauthorized), 404 (not found), 500 (server error), status null with error "socket timeout" or "connection refused".