@ackplus/nest-auth-client
Framework-agnostic JavaScript/TypeScript client for @ackplus/nest-auth. Zero peer dependencies. Works anywhere modern JS runs — browsers, Node 18+, React Native, Cloudflare Workers, Deno, Bun.
📚 Full documentation: ack-solutions.github.io/nest-auth/docs/client
Why use it
The official client for the @ackplus/nest-auth backend. Use it directly from Vue, Angular, Svelte, vanilla JS, or as the foundation under @ackplus/nest-auth-react.
It handles the parts of auth that are tedious to write by hand: token persistence, automatic refresh on 401 with concurrent-request deduplication, cookie/header mode switching, MFA flows, multi-tenant context, and an event subscription API.
Install
pnpm add @ackplus/nest-auth-client
No peer dependencies. TypeScript definitions ship in the package.
Minimal example
import { AuthClient } from '@ackplus/nest-auth-client';
const auth = new AuthClient({
baseUrl: 'https://api.example.com',
});
await auth.signup({
email: '[email protected]',
password: 'correct horse battery staple',
firstName: 'Alice', // any extra field flows through to UserRegisteredEvent
});
await auth.login({
credentials: { email: '[email protected]', password: 'correct horse battery staple' },
});
if (auth.getIsAuthenticated()) {
const user = await auth.getSessionUserData();
console.log('Hello', user.email);
}
What's included
| Capability | Notes |
|---|---|
| Auth flows | signup, login, logout, logoutAll, refresh, passwordlessSend, switchTenant |
| MFA | send2fa, verify2fa, setupTotp, verifyTotpSetup, getMfaStatus, recovery codes |
| Password management | forgotPassword, verifyForgotPasswordOtp, resetPassword, changePassword |
| Email/phone verification | sendEmailVerification, verifyEmail, sendPhoneVerification, verifyPhone |
| Auto-refresh | 401 → refresh → retry once, with RefreshQueue deduplication so N parallel 401s only fire one refresh |
| Header or cookie mode | accessTokenType: 'header' | 'cookie' | null (auto-detect) |
| Storage adapters | MemoryStorage, LocalStorageAdapter, SessionStorageAdapter, CookieStorageAdapter, custom |
| HTTP adapters | FetchAdapter (default) or createAxiosAdapter(yourAxiosInstance), custom |
| Events | onTokensSet, onTokenRefreshed, onTokensRemoved, onLogout, onError, onSessionVerified |
| Utilities | decodeJwt, isTokenExpired, hasRole, hasPermission, hasAnyAccess, hasAllAccess |
Configuration
new AuthClient({
baseUrl: 'https://api.example.com',
storage: new LocalStorageAdapter('myapp_'),
httpAdapter: new FetchAdapter(),
accessTokenType: 'header', // or 'cookie' or null (auto-detect)
autoRefresh: true,
refreshThreshold: 60, // seconds before expiry
onTokenRefreshed: (tokens) => { /* … */ },
onLogout: () => { window.location.href = '/login'; },
onError: (err) => console.error(err),
});
React Native
import AsyncStorage from '@react-native-async-storage/async-storage';
import { AuthClient, type StorageAdapter } from '@ackplus/nest-auth-client';
const RNStorage: StorageAdapter = {
get: (k) => AsyncStorage.getItem(k),
set: (k, v) => AsyncStorage.setItem(k, v),
remove: (k) => AsyncStorage.removeItem(k),
clear: () => AsyncStorage.clear(),
};
export const auth = new AuthClient({
baseUrl: 'https://api.example.com',
storage: RNStorage,
});
Documentation
| Section | What's there |
|---|---|
AuthClient | Every method with TS signatures and examples |
| Config | All AuthClientConfig options |
| Storage Adapters | Built-ins and how to write your own |
| HTTP Adapters | Fetch (default), axios, custom |
| Events | Subscription API |
| Utilities | JWT helpers, role/permission checks |
Companion packages
| Package | Use when |
|---|---|
@ackplus/nest-auth | The NestJS backend module |
@ackplus/nest-auth-react | React provider, hooks, guards, and Next.js App Router helpers (recommended for React) |
@ackplus/nest-auth-contracts | Shared TS types (already a transitive dep of this package) |
All four packages release together with the same version number. Pin them all to the same version.