@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),
});

Full config reference →

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.

Links

• 📚 Documentation
• 💬 Issue Tracker
• 📦 GitHub Repository

License

MIT