Configure once, call everywhere
What applies to every request is written where the client is created, not at every call.
The rules of your requests are one list. A request passes it in this order, its response in reverse.
Basic usage →const api = createClient({
baseURL: "https://api.example.com/v1",
adapter: fetchAdapter(),
timeout: 10_000,
middlewares: [
onError({ 401: toLogin }),
refreshToken({ refresh: () => session.refresh() }),
tokenAuth({ cookieName: "token" }),
cache({ storage: new StorageSession() }),
],
});
Model Context Protocol
Your AI assistant, with the real API
A model that has not seen Punica Request guesses: an adapter that does not exist, a middleware in the list where it cannot work. One line gives your assistant the API of the version you have installed, and a checker for the code it writes.
claude mcp add punica-request -- npx -y @punica/request-mcp
What the assistant gets
get_guide- The rules of version 3: clients, requests, errors, the middlewares and their order
get_migration_guide- From 2.x to 3.0: every name that changed, with its replacement
search_api- Finds exports by name or by what they do
get_api- The exact declaration and documentation of an export
validate_code- Checks code for names of 2.x, wrong orders and wrong bodies; every problem comes with a fix
- Cache the list of countries for an hour.
get_guide()search_api("cache")cache (const, @punica/request-middleware) · StorageSession · StorageIndexedDB · CacheOptionsvalidate_code(…)line 4 v2: CacheMiddleware is a class of 2.x; middlewares are made by functions. [fix: cache({ storage })]validate_code(…)No problems- The countries are cached for an hour, checked against the version you have installed.
What you do not have to write
Tokens that renew themselves
On a 401 the token is refreshed once, for every request that failed together, and the requests are sent again.
Requests that step aside
A search that was replaced by a newer one is cancelled. A timeout covers the whole request, retries included.
A cache you ask for
A GET says when it may be answered from session storage, IndexedDB or a storage of your own, and for how long.
Errors in one place
A handler per status for what is the same everywhere: the redirect to the login, the general message.
Rules of your own
A middleware is one function around the rest of the chain. It changes a request, answers it or sends it again.
A transport you choose
fetch in the browser and in Node, or an adapter of a few lines that answers from memory in your tests.
Three things to know first
Version 3 does what you expect of a client today. If you know 2.x, these are the defaults that changed.
- A 404 or a 500 rejects, with an
HttpErrorthat carries the response. - JSON is taken care of.
jsonserialises a body; a response is read by itsContent-Type. - One list of middlewares, each a function that sees the request and its response.
try {
await api.get("items/999");
} catch (error) {
if (isHttpError(error)) {
error.status; // 404
error.response.data; // what the server sent
}
}
const response = await api.get("items/999", { throwHttpErrors: false });
response.ok; // false
response.status; // 404