HttpClientOptions

HttpClientOptions is decided once per target API. Essential fields must not be inferred implicitly by the application.

Essential Options

Option	Required	Default	Effect	Use when	Avoid if
baseUrl	Yes	None	Builds all relative URLs.	Always, with a stable root such as https://api.example.com/v1.	Do not set /users/42 or mix several backends.
auth	Yes	None	Produces the auth policy before application guards.	bearerAuth, cookieAuth, apiKeyAuth, basicAuth, or noAuth.	Do not simulate missing auth with an empty token.
parser	Yes	None	Transforms the raw body into ClientResult<T>.	Choose a REST, Laravel, Nest, GraphQL, or structured preset.	Do not parse inside UI components.
fetch	No	globalThis.fetch	Transport implementation used by the client.	Tests, specific runtimes, mocks, or low-level instrumentation.	Do not pass a detached window.fetch reference without binding in older environments.

Behavior Options

Option	Default	Precise Explanation
cache	Disabled	Cache store read/write is used only for GET when the request provides RequestOptions.cache. memoryCache supports TTL, tags, and max size.
notifier	consoleNotifier	Receives network, HTTP, and parsing events when defaults.shouldNotify allows it.
redirects	{ mode: "follow", maxHops: 5 }	Controls application redirects. Auth headers must be removed on cross-origin redirects.
plugins	[]	Plugins applied when the client is created and deduplicated by name.
guards	[]	Middleware pipeline executed in declared order after the internal auth guard.

Defaults

Option	Default	Recommended Usage
defaults.headers	{}	Constant headers: Accept-Language, X-App-Version, tenant id. Do not put Authorization here.
defaults.timeoutMs	No global timeout	Set a readable limit for an interactive API, for example 10_000.
defaults.shouldNotify	(result) => !result.ok	Filter validation 400 responses when they must stay inside forms.

Strict Example

import {
  bearerAuth,
  createApiParserStructured,
  createHttpClient,
  memoryCache
} from "@cedvict/http-guardian";

export const api = createHttpClient({
  baseUrl: "https://api.example.com/v1",
  auth: bearerAuth(() => authStore.accessToken(), {
    allowedOrigins: ["https://api.example.com"]
  }),
  parser: createApiParserStructured(),
  cache: memoryCache({ maxEntries: 500 }),
  defaults: {
    headers: { "X-App-Version": "web-1.0.0" },
    timeoutMs: 10_000,
    shouldNotify: ({ ok, status }) => !ok && (status === 0 || status >= 500)
  }
});