Events

Overview

The @authrim/core SDK provides a rich event system for observing authentication lifecycle events. Use events for logging, UI updates, analytics, and error monitoring.

Subscribing to Events

on() — Subscribe to an Event

const unsubscribe = client.on('token:refreshed', (event) => {
  console.log('Token refreshed at:', event.timestamp);
  console.log('Expires at:', event.expiresAt);
});

// Later, unsubscribe
unsubscribe();

once() — Subscribe to a Single Occurrence

client.once('auth:login_complete', (event) => {
  console.log('First login:', event.method);
});

off() — Unsubscribe

function handler(event) {
  console.log('Session started');
}

client.on('session:started', handler);

// Later
client.off('session:started', handler);

Event Payload

All events extend BaseEventPayload:

Property	Type	Description
timestamp	number	Event timestamp (epoch milliseconds)
source	'core' | 'web'	Which SDK layer emitted the event
operationId	string | undefined	Correlation ID for related events

Event Reference

Authentication Events (auth:*)

Event	Payload	Description
auth:init	BaseEventPayload	Authentication flow initialized
auth:redirecting	{ url: string }	Redirecting to authorization server
auth:callback	{ code: string, state: string }	Callback received with authorization code
auth:callback_processing	BaseEventPayload	Processing the callback (code exchange)
auth:callback_complete	{ success: boolean }	Callback processing completed
auth:login_complete	{ method: string, user?: UserInfo }	Login completed successfully
auth:logout_complete	{ method: string }	Logout completed
auth:required	{ reason: string }	Authentication is required
auth:popup_blocked	BaseEventPayload	Popup was blocked by the browser
auth:fallback	{ from: string, to: 'redirect', reason: string }	Falling back to a different auth method

Token Events (token:*)

Event	Payload	Description
token:refreshing	{ reason: string }	Token refresh started
token:refreshed	{ hasAccessToken, hasRefreshToken, hasIdToken, expiresAt }	Token refresh succeeded
token:refresh_failed	{ error: AuthrimError, willRetry: boolean, attempt: number }	Token refresh failed
token:expiring	{ expiresAt: number, expiresIn: number }	Token is about to expire
token:expired	{ expiredAt: number, hasRefreshToken: boolean }	Token has expired
token:error	{ error: AuthrimError, context: string }	Token operation error
token:exchanged	{ hasAccessToken, hasRefreshToken, issuedTokenType }	Token exchange completed

Session Events (session:*)

Event	Payload	Description
session:started	BaseEventPayload	Session started (user authenticated)
session:ended	BaseEventPayload	Session ended (logout or expiration)
session:changed	BaseEventPayload	Session state changed
session:sync	BaseEventPayload	Session synchronized across tabs
session:logout_broadcast	BaseEventPayload	Logout broadcast received from another tab

Error Events (error:*)

Event	Payload	Description
error:fatal	{ error: AuthrimError, context: string }	Fatal error — recovery not possible
error:recoverable	{ error: AuthrimError, context: string }	Recoverable error — automatic retry may occur

Warning Events (warning:*)

Event	Payload	Description
warning:deprecation	{ feature: string, alternative: string }	Feature deprecation notice
warning:security	{ issue: string, recommendation: string }	Security recommendation

Usage Examples

Logging

// Log all authentication events
client.on('auth:login_complete', (e) => {
  console.log(`User logged in via ${e.method}`);
});

client.on('auth:logout_complete', (e) => {
  console.log(`User logged out via ${e.method}`);
});

UI Updates

// Update UI when session changes
client.on('session:started', () => {
  showUserDashboard();
});

client.on('session:ended', () => {
  showLoginPage();
});

// Show loading state during token refresh
client.on('token:refreshing', () => {
  showSpinner();
});

client.on('token:refreshed', () => {
  hideSpinner();
});

Error Monitoring

// Monitor token refresh failures
client.on('token:refresh_failed', (event) => {
  if (!event.willRetry) {
    // Final failure — no more retries
    reportToErrorTracking({
      code: event.error.code,
      message: event.error.message,
      attempt: event.attempt,
    });
    redirectToLogin();
  }
});

// Monitor fatal errors
client.on('error:fatal', (event) => {
  reportToErrorTracking({
    code: event.error.code,
    message: event.error.message,
    context: event.context,
  });
});

Cross-Tab Logout

// Detect when another tab logs out
client.on('session:logout_broadcast', () => {
  // Clear UI state and redirect
  clearAppState();
  window.location.href = '/login';
});

Token Expiration Warning

client.on('token:expiring', (event) => {
  const minutesLeft = Math.floor(event.expiresIn / 60);
  showNotification(`Session expires in ${minutesLeft} minutes`);
});

Next Steps

• Error Handling — Error classification and recovery
• Token Management — Token lifecycle management
• Session & Logout — Session state management