🔐 LoginManager – Simple, Universal Auth Manager

A tiny, framework-agnostic authentication manager for JavaScript & TypeScript.
Works with fetch, axios, or any custom request function.
Handles access tokens, refresh tokens, cookie sessions, auto-refresh, and more.

🚀 Install

npm install my-login-manager
# or
yarn add my-login-manager

✨ Features
✅ Universal – Works with fetch, axios, superagent, etc.

✅ Token Strategy Agnostic – Supports:

Access token in header + refresh token in HttpOnly cookie

Both access & refresh in headers

Both access & refresh in HttpOnly cookies (session-based)

✅ Auto-Refresh – Optionally refresh before token expiry

✅ Race Condition Safe – Queues refresh requests

✅ Pluggable Storage – Use memory, localStorage, sessionStorage, or custom

✅ Error & Event Hooks – onLogin, onLogout, onRefresh, onError

✅ Tiny & Dependency-Free

🛠 Usage
1️⃣ Setup

import { LoginManager } from "login-manager";

const auth = new LoginManager({
  request: fetch, // or axios, or your own request function
  getToken: (data) => data.accessToken, // extract token from response
  saveToken: (token) => localStorage.setItem("access_token", token),
  clearToken: () => localStorage.removeItem("access_token"),
  getExpiry: (token) => decodeJwt(token).exp * 1000, // optional, for auto-refresh
  autoRefresh: true,
  onLogin: (user) => console.log("✅ Logged in:", user),
  onLogout: (reason) => console.log("👋 Logged out:", reason),
  onError: (err) => console.error("❌ Auth error:", err.message),
});
2️⃣ Login & Store User

await auth.login("/api/login", { email, password });
console.log(auth.getUser()); // current user
console.log(auth.isLoggedIn()); // true
3️⃣ Secure API Calls

const securedFetch = auth.withAuth(fetch);

// token is automatically attached
await securedFetch("/api/private-data");
4️⃣ Refresh Tokens (Manual or Auto)

// Manual refresh
await auth.refresh("/api/refresh");
When autoRefresh: true and getExpiry() is provided, LoginManager refreshes before expiry automatically.

5️⃣ Logout

auth.logout("User clicked logout");
🌍 Works With Any Token Strategy
Scenario	How It Works
Access token in header, refresh token in cookie	Store access token via saveToken(). Call refresh() → backend reads refresh cookie → returns new access token.
Both in headers	Store both tokens manually. Pass refresh token in header via config.headers.
Both in cookies	Skip saveToken() and storage. LoginManager just tracks user in memory.

⚙️ API
new LoginManager(options)
Option	Type	Description
request	(url, config) => Promise<Response>	Required. Your fetch/axios function.
storage	Storage | null	Defaults to localStorage. Set null for cookie-only sessions.
tokenKey	string	Key to store token under. Default: "access_token".
getToken	(data) => string | null	Extract token from login/refresh response.
saveToken	(token: string) => void	Custom token storage logic.
clearToken	() => void	Clear token on logout.
getExpiry	(token: string) => number	Return expiry timestamp (ms). Enables auto-refresh.
autoRefresh	boolean	Automatically refresh before expiry.
onLogin	(user) => void	Called after successful login.
onLogout	(reason?) => void	Called after logout.
onRefresh	(user) => void	Called after successful refresh.
onError	(error) => void	Called on login/refresh errors.

Methods
Method	Returns	Description
login(endpoint, credentials, config?)	Promise<user>	Logs in, saves token, sets user.
refresh(endpoint, config?)	Promise<user>	Refresh token and update user/token.
logout(reason?)	void	Clears token and user state.
getUser()	any	Returns current user.
isLoggedIn()	boolean	Returns true if user is logged in.
withAuth(requestFn)	(url, config) => Promise<Response>	Wraps request function and injects token automatically.

🔐 Security Tips
Store refresh tokens in HttpOnly, SameSite=Strict cookies when possible.

Only store access tokens in memory or localStorage if necessary.

Use HTTPS in production to protect all token transport.

🧪 Example with Axios

import axios from "axios";
import { LoginManager } from "login-manager";

const auth = new LoginManager({
  request: (url, config) => axios({ url, ...config }),
  getToken: (data) => data.accessToken,
});

await auth.login("/api/login", { username, password });

const securedAxios = auth.withAuth(axios);
const response = await securedAxios("/api/private-data");
console.log(response.data);

## 🍼 Examples

See [`examples/`](./examples) folder for baby-simple demos:
- **1-basic-login.js** – Quick login/logout
- **2-with-axios.js** – Works with Axios
- **3-cookie-session.js** – No token storage needed
- **4-auto-refresh.js** – Auto-refresh access tokens
- **5-custom-storage.js** – Store tokens anywhere (memory, IndexedDB)
- **6-force-logout.js** – Securely log out on refresh failure

## ⚛️ React Usage

We provide simple React examples too!

- **[react-basic.jsx](./examples/react-basic.jsx)** → Basic login/logout with React state
- **[react-advanced.jsx](./examples/react-advanced.jsx)** → Context + Auto-Refresh + Secure API calls

📦 License
MIT © Martins Kelvin