@barry-rocks/sdk/http

Small HTTP client helpers: postJson and describeFetchFailure, which turns a failed fetch into a message that says what went wrong.

import { … } from "@barry-rocks/sdk/http";

API

Interfaces

JsonRequest

Properties

Property	Type	Description
body	unknown	-
describeHttpError?	(status, body) => string | undefined	Turns a non-OK response into a message. Return undefined to fall through to the generic one. Lets an adapter name its own setup problems — a 404 from Ollama means “run ollama pull”, a 401 from a hosted API means the key is wrong — while the transport stays shared.
headers?	Record<string, string>	-
timeoutMs	number	-
unavailableStatuses?	number[]	Statuses that mean the backend cannot serve at all, so a sweep should stop rather than retry per item. Anything else raises an ordinary Error.
url	string	-

Functions

describeFetchFailure()

describeFetchFailure(err, url, timeoutMs): string

Classify the wrapper’s abort as timeout, verified connection failures as unreachable, and other fetch errors without inventing a cause. See docs/decisions/0011-sdk-runtime-invariants.md for the retained rationale.

Parameters

Parameter	Type
err	unknown
url	string
timeoutMs	number

Returns

string

---

postJson()

postJson<T>(opts): Promise<T>

POST JSON and parse the reply, with one timeout and honest failure attribution.

Every vendor speaks HTTP+JSON, and each one had grown its own AbortController/timer/try-catch. The duplication is not just lines: it is three chances to get the diagnostic wrong in different ways.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
opts	JsonRequest

Returns

Promise<T>