Skip to main content

HTTP client for TypeScript

The rules of your requests, in one list. Written by you, or by AI.

Authentication, token refresh, cancellation, caching and error handling are middlewares a request passes in order. The transport is an adapter: fetch, or your own.

npm install @punica/request @punica/request-fetch @punica/request-middleware

No dependencies · ESM and CommonJS · Browser and Node · TypeScript

Loading…

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.

In your project
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
Set up and tools →
What happens when you ask
  1. Cache the list of countries for an hour.
  2. get_guide()
  3. search_api("cache")
  4. cache (const, @punica/request-middleware) · StorageSession · StorageIndexedDB · CacheOptions
  5. validate_code(…)
  6. line 4 v2: CacheMiddleware is a class of 2.x; middlewares are made by functions. [fix: cache({ storage })]
  7. validate_code(…)
  8. No problems
  9. The countries are cached for an hour, checked against the version you have installed.

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 HttpError that carries the response.
  • JSON is taken care of. json serialises a body; a response is read by its Content-Type.
  • One list of middlewares, each a function that sees the request and its response.
Coming from 2.x →
A response outside 2xx
try {
await api.get("items/999");
} catch (error) {
if (isHttpError(error)) {
error.status; // 404
error.response.data; // what the server sent
}
}
Or get it back
const response = await api.get("items/999", { throwHttpErrors: false });

response.ok; // false
response.status; // 404

A client in five minutes

Install three packages, list your rules, call.