@idevconn/api-client

Tiny JWT fetch wrapper with automatic token refresh, typed errors, and pluggable callbacks. Framework-agnostic. Zero runtime dependencies.

Features

• Auto-injects Authorization: Bearer <token> from your auth store.
• Retries once on 401 via a configurable refresh endpoint.
• Surfaces failures as a typed ApiError with status, body, and message.
• Wraps network failures (fetch reject) as ApiError(0, …) — never silent.
• Optional global onError notifier for crash reporting / default toasts.
• Skips Content-Type when sending FormData (browser sets the boundary).
• Returns undefined for 204 No Content.

Install

npm install @idevconn/api-client

Quick start

import { createApiClient, ApiError } from "@idevconn/api-client";

export const api = createApiClient({
  baseUrl: import.meta.env.VITE_API_URL,

  getAccessToken: () => authStore.getState().accessToken,
  getRefreshToken: () => authStore.getState().refreshToken,

  onTokenRefreshed: ({ accessToken, refreshToken }) =>
    authStore.getState().setAuth({ accessToken, refreshToken }),

  onUnauthorized: () => {
    authStore.getState().logout();
    window.location.href = "/login";
  },

  // Optional. Fires on every non-OK response and every network failure,
  // BEFORE the error is thrown. Does NOT fire on the 401→onUnauthorized path.
  onError: (err) => reportToCrashlytics(err, { status: err.status, body: err.body }),
});

// Usage
try {
  const me = await api<{ id: string }>("/me");
} catch (err) {
  if (err instanceof ApiError && err.status === 403) {
    showUpgradeModal();
  }
}

Configuration

Field	Type	Required	Default	Notes
baseUrl	string	yes	—	Prepended to every request path.
getAccessToken	() => string | null	yes	—	Read the current token from your store on each call (don't cache).
getRefreshToken	() => string | null	yes	—	Same.
onTokenRefreshed	({ accessToken, refreshToken }) => void	yes	—	Persist new tokens to your store. Called after a successful refresh.
onUnauthorized	() => void	yes	—	Called when refresh fails after a 401. Typically clears auth + redirects to login.
onError	(err: ApiError) => void	no	—	Global error notifier. Fires for non-OK responses + network failures (NOT the 401→unauthorized path).
refreshPath	string	no	/auth/refresh	Endpoint hit when refreshing.
refreshRequestField	string	no	refresh_token	Body field name sent to the refresh endpoint.
accessTokenField	string	no	access_token	Response field name carrying the new access token.
refreshTokenField	string	no	refresh_token	Response field name carrying the new refresh token.

ApiError

class ApiError extends Error {
  readonly status: number;       // 0 for network failures
  readonly body: unknown;         // parsed JSON response (or null)
  get isNetworkError(): boolean;  // status === 0
}

Status code, response body, and instanceof work in catch blocks and React Query onError handlers.

Error-handling semantics

Scenario	onError fires?	onUnauthorized fires?	Throws?
2xx with body	no	no	no (returns body)
204	no	no	no (returns undefined)
4xx / 5xx	yes	no	yes (ApiError)
401, refresh succeeds, retry OK	no	no	no (returns body)
401, refresh fails (or no refresh tok)	no	yes	yes (ApiError(401))
Network failure / fetch reject	yes	no	yes (ApiError(0))

The onError callback runs before the throw — your try/catch and React Query onError still run after it.

License

Apache-2.0