Devraj Labs · API Kit

The API client that handles auth so you don't have to.

Token attachment. Silent refresh. Race-condition safety. Works everywhere.

You've written the interceptor. You've debugged the race condition where five requests all tried to refresh at once. You've added the retry logic, the logger, the storage adapter. You've done it on every project.

API Kit does all of it — once, correctly.

What it does

ApiClient.getInstance({
  baseURL: "https://api.example.com",
  storage: myStorage,
  hooks: {
    onAuthFailure: () => router.push("/login"),
  },
});

// That's it. Every request from here automatically:
// - attaches Bearer token
// - refreshes silently when it expires
// - retries if the server hiccups
// - routes exactly ONE refresh call even if 10 requests fire at once
const { data } = await client.get<User>("/api/me");

Features

Token lifecycle — fully automatic

• Attaches Authorization: Bearer <token> to every request
• Detects 401s and transparently refreshes + replays the failed request
• Pre-emptive refresh — renews the token before it expires, configurable via preemptiveRefreshSeconds

Race-condition safe

• Concurrent 401s collapse into exactly one refresh call
• All queued requests drain together the moment refresh completes
• Pre-emptive refresh shares the same single-flight promise — no double-refresh under load

Platform agnostic

• Works in browser, React Native, and Node.js
• Bring your own storage — any object implementing getAccessToken / setTokens / clearTokens
• Ships with MemoryTokenStorage, LocalStorageTokenStorage, and AsyncStorageTokenStorage
• First-class support for @devraj-labs/rn-storage-kit (encrypted keychain on mobile)

Production grade

• Exponential backoff with full jitter on transient errors (408, 429, 5xx)
• Auth event hooks — onTokenRefreshed · onAuthFailure · onLogout
• Bring-your-own logger — any { debug, info, warn, error } object (console, @devraj-labs/logger, etc.)
• Singleton pattern — initialise once, use everywhere, no prop drilling

TypeScript first

• Full generics on every method: client.get<User>("/api/me")
• Exported interfaces for every extension point

Install

npm install @devraj-labs/api-kit axios

Quick start

// bootstrap.ts — run this once at app entry (index.ts / App.tsx)
import { ApiClient, LocalStorageTokenStorage } from "@devraj-labs/api-kit";

ApiClient.getInstance({
  baseURL: "https://api.example.com",
  storage: new LocalStorageTokenStorage(),
  hooks: {
    onAuthFailure() {
      window.location.href = "/login";
    },
  },
});

// anywhere in your app — no config needed
import { ApiClient } from "@devraj-labs/api-kit";

const client = ApiClient.getInstance();

const { data: user }    = await client.get<User>("/api/me");
const { data: post }    = await client.post<Post>("/api/posts", { title });
const { data: updated } = await client.patch<Post>("/api/posts/1", { title });

After login, store the tokens and every subsequent request is handled:

import { ApiClient } from "@devraj-labs/api-kit";

async function login(username: string, password: string) {
  const res = await fetch("/auth/login", {
    method: "POST",
    body: JSON.stringify({ username, password }),
  });
  const tokens = await res.json();

  // hand tokens to api-kit — it takes it from here
  const client = ApiClient.getInstance();
  await client.storage.setTokens(tokens);
}

Storage

| Adapter | Environment | Security | |---|---|---| | MemoryTokenStorage | Any | Cleared on page reload | | LocalStorageTokenStorage | Browser | Vulnerable to XSS — dev/demo only | | AsyncStorageTokenStorage | React Native | Unencrypted — dev/demo only | | @devraj-labs/rn-storage-kit | React Native | Encrypted keychain — recommended for prod |

Implement your own with three methods:

import type { TokenStorage } from "@devraj-labs/api-kit";

const myStorage: TokenStorage = {
  getAccessToken:  () => secureGet("access_token"),
  getRefreshToken: () => secureGet("refresh_token"),
  setTokens:       (t) => secureSet(t),
  clearTokens:     ()  => secureClear(),
};

Full guide → docs/storage.md

Logger

Pass any object with debug / info / warn / error — no adapter needed:

// console
ApiClient.getInstance({ ..., logger: console });

// @devraj-labs/logger
import { logger } from "@devraj-labs/logger";
ApiClient.getInstance({ ..., logger: logger.child({ module: "api-kit" }) });

// silent (default)
ApiClient.getInstance({ ...config }); // omit logger entirely

Full guide → docs/logger.md

Documentation

| | | |---|---| | Getting Started | Install, minimal setup, platform examples | | Configuration | All config options, types, and defaults | | Token Storage | Built-in adapters, custom storage, rn-storage-kit | | Logger Integration | Using @devraj-labs/logger or any compatible logger | | Race Condition Guard | How concurrent 401s are handled | | Pre-emptive Refresh | Proactive token renewal before expiry | | Examples | Node.js · Browser · React Native · custom storage | | Demo | Running the interactive demo app locally |

Run the demo

Hosted demo — no setup needed: https://web-self-delta-77.vercel.app/

See token refresh, race-condition guard, and live expiry countdown in action. Login with alice / password123.

Or run it locally:

npm run demo

Opens a Vite + React app at http://localhost:5173 backed by a local Express server. Full guide → docs/demo.md

License

MIT © Devraj Labs