Skip to main content

SessionClient

The SessionClient is the central orchestrator for client-side session management. It manages the user's state, handles token refreshes, and coordinates with authentication adapters.

Since v9 it is generic over both the user and the credentials type: SessionClient<User, Credentials> — type it with the credentials union your adapter supports (e.g. CombinedCookieAuthCredentials for web, NativeAuthCredentials for native).

import { SessionClient } from '@archibald/auth';

const sessionClient = new SessionClient(OPTIONS);

Options​

  • Type: SessionClientOptions

The SessionClientOptions object has the following properties:

NameTypeDefaultDescription
apiCreateApi✔️ The API creator instance for making requests.
adapterAuthAdapter classCookieAuthAdapterThe class (not instance) of the auth adapter.
authenticateOnServerbooleanfalseWhether to prefetch user data on the server during SSR.
userCacheTimenumber300000 (5 min)TTL for user data in the cache (ms).
refreshValidExpirationTimeInterval for automatic token refresh (e.g., '10m').
storageStorageAdapter class | 'local' | 'cookie''cookie'Storage adapter used for client-side token persistence.
oidcConfigOidcConfigOIDC client configuration — queryParamsWhitelist controls which query params login() may forward to GET auth/login. See OIDC Login Flow.

Methods​

initialize​

Idempotently initializes the client: starts the refresh interval, performs the initial check(), and publishes the initialized event. Called automatically by useUser/SessionClientProvider.

  • Returns: Promise<void>

logIn​

Authenticates the user with the provided credentials.

  • Parameters: credentials: Credentials
  • Returns: Promise<AuthResponse>
OIDC

With authProtocol: 'oidc' (web/cookie adapter) this triggers a full-page redirect: the call resolves { success: true, redirect: true } without setting loggedIn or publishing a login event — the session materializes on the SSR render after the IdP round trip. See OIDC Login Flow.

logOut​

Terminates the user's session and cleans up local state.

  • Returns: Promise<AuthResponse>

refresh​

Manually triggers a token refresh using the refresh token.

  • Returns: Promise<AuthResponse>

check​

Checks if the current session is still valid by calling the backend.

  • Returns: Promise<AuthResponse>

isLoggedIn​

Synchronously returns whether the user is currently considered logged in.

  • Returns: boolean

loadUser​

Fetches the full user profile data from the backend.

  • Returns: Promise<User | null>

prefetchUser / refetchUser​

prefetchUser() warms the user cache (used during SSR with authenticateOnServer); refetchUser(options?) invalidates and reloads the cached user.

subscribe​

Subscribes to session events.

  • Parameters:
    • events: AuthEvent[] (e.g., 'login', 'logoff')
    • callback: EventCallback
  • Returns: () => void (Unsubscribe function)

Usage Example​

import { SessionClient, CookieAuthAdapter } from '@archibald/auth';
import { api } from './api';

const sessionClient = new SessionClient({
    api,
    adapter: CookieAuthAdapter,
    authenticateOnServer: true,
    refresh: '10m'
});

// Subscribe to login events
const unsubscribe = sessionClient.subscribe(['login'], (result) => {
    console.log('User logged in:', result.data);
});

// Perform login
await sessionClient.logIn({ authProtocol: 'password', username: 'user@example.com', password: 'password' });

Relates to​

  • SessionClientProvider: The client instance must be passed to this provider (typically via ProviderComposer) to be available via hooks.
  • ProviderComposer: The standard way to bootstrap SessionClientProvider alongside other core providers in the App component.
  • AuthAdapter: SessionClient delegates actual network calls and token storage to an adapter (e.g., CookieAuthAdapter).
  • Hooks: useUser, useLogin, and useLogOut all use the SessionClient instance internally.
  • DataClient: SessionClient integrates with the DataClient to cache user data under the session-user key.