formreader-session-timeout 0.2.0

package/README.md

@@ -0,0 +1,459 @@
+# @formreader/session-timeout
+
+A lightweight, fully configurable React microfrontend for **JWT token refresh management**, **idle session tracking**, and **auto-logout** with comprehensive event callbacks.
+
+## Features
+
+- ✅ **JWT Expiry Decoding** — Reads token expiry from JWT `exp` claim, no server roundtrip needed
+- ✅ **Configurable Refresh Timing** — Schedule token refresh at any point before expiry
+- ✅ **Idle Detection** — Automatic idle timeout with configurable warning dialogs
+- ✅ **Custom Payload Formatting** — Tailor refresh/logout request payloads to your API
+- ✅ **Flexible HTTP Integration** — Use your own axios/fetch client or rely on built-in fetch
+- ✅ **Event-Driven** — Full control via callbacks: `onRefreshSuccess`, `onIdle`, `onSessionExpired`, etc.
+- ✅ **Zero External Dependencies** — Works standalone; React is a peer dependency only
+- ✅ **Fully Typed** — TypeScript support out of the box
+- ✅ **Singleton Pattern** — Global session manager or per-component hooks
+
+---
+
+## Installation
+
+```bash
+npm install @formreader/session-timeout
+```
+
+Or using yarn:
+```bash
+yarn add @formreader/session-timeout
+```
+
+---
+
+## Quick Start
+
+### 1. Hook-Based Usage (Recommended)
+
+Import and use the `useSessionTimeout` hook in any React component:
+
+```typescript
+import React from 'react';
+import { useSessionTimeout } from '@formreader/session-timeout';
+
+export function MyComponent() {
+  const {
+    sessionState,
+    timeUntilIdle,
+    idleWarningVisible,
+    extendSession,
+    refreshToken,
+    logout,
+  } = useSessionTimeout({
+    enabled: true,
+    config: {
+      refreshThresholdMs: 2 * 60 * 1000,        // Refresh 2 min before expiry
+      idleTimeoutMs: 15 * 60 * 1000,            // Logout after 15 min idle
+      idleCheckIntervalMs: 10 * 1000,           // Check idle every 10 sec
+      idleWarningThresholdMs: 2 * 60 * 1000,    // Show warning 2 min before idle
+      autoRefresh: true,
+      showIdleWarning: true,
+      debug: true,
+      // Your API endpoints
+      refreshEndpoint: '/api/auth/refresh/',
+      logoutEndpoint: '/api/auth/logout/',
+      // Custom payload format (if needed)
+      refreshPayloadFormatter: (token) => ({ refresh: token }),
+    },
+    onRefreshSuccess: () => console.log('Token refreshed'),
+    onIdle: () => console.log('User idle'),
+    onSessionExpired: () => console.log('Session expired'),
+  });
+
+  return (
+    <div>
+      <p>Session: {sessionState.isActive ? '🟢 Active' : '🔴 Inactive'}</p>
+      {idleWarningVisible && (
+        <div className="warning">
+          <p>Your session is about to expire in {timeUntilIdle}ms</p>
+          <button onClick={extendSession}>Stay Logged In</button>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### 2. Service-Based Usage
+
+Use `SessionManager` directly for more control:
+
+```typescript
+import {
+  getSessionManager,
+  resetSessionManager,
+  getStoredToken,
+  getTokenInfo,
+} from '@formreader/session-timeout';
+
+// Initialize on app startup
+const manager = getSessionManager({
+  refreshThresholdMs: 2 * 60 * 1000,
+  idleTimeoutMs: 15 * 60 * 1000,
+  autoRefresh: true,
+  debug: true,
+  refreshEndpoint: '/api/auth/refresh/',
+  logoutEndpoint: '/api/auth/logout/',
+  refreshPayloadFormatter: (token) => ({ refresh: token }),
+});
+
+manager.init();
+
+// Listen to events
+manager.on('tokenRefreshed', () => console.log('Token refreshed'));
+manager.on('idle', () => console.log('User idle'));
+
+// Manual refresh if needed
+await manager.refreshToken();
+
+// Cleanup on logout or unmount
+manager.destroy();
+```
+
+---
+
+## Configuration
+
+All settings are optional and inherit sensible defaults. Pass them via the `config` object:
+
+### Session Timing
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `refreshThresholdMs` | number | `2 * 60 * 1000` | Milliseconds before token expiry to trigger refresh |
+| `idleTimeoutMs` | number | `15 * 60 * 1000` | Milliseconds of inactivity before session ends |
+| `idleCheckIntervalMs` | number | `10 * 1000` | How often to check for idle activity |
+| `idleWarningThresholdMs` | number | `2 * 60 * 1000` | Milliseconds before idle timeout to show warning |
+| `maxSessionDurationMs` | number | `8 * 60 * 60 * 1000` | Absolute max session duration (8 hours) |
+
+### API Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `refreshEndpoint` | string | `/auth/refresh/` | URL for token refresh |
+| `logoutEndpoint` | string | `/auth/logout/` | URL for logout |
+| `autoRefresh` | boolean | `true` | Auto-refresh tokens before expiry |
+
+### UI Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `showIdleWarning` | boolean | `true` | Show idle warning dialog |
+| `debug` | boolean | `false` | Log debug messages to console |
+
+### Custom Integration
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `httpClient?` | `{ post(...): Promise }` | Custom HTTP client (defaults to `fetch`) |
+| `refreshPayloadFormatter?` | `(token) => object` | Format refresh request payload |
+| `logoutPayloadFormatter?` | `(token) => object` | Format logout request payload |
+
+---
+
+## Custom HTTP Client
+
+If you have an existing axios instance or custom HTTP client, pass it to avoid dependencies:
+
+```typescript
+import axios from 'axios';
+
+const { useSessionTimeout } = require('@formreader/session-timeout');
+
+useSessionTimeout({
+  config: {
+    httpClient: {
+      post: (url, body, options) => axios.post(url, body, options),
+    },
+    refreshThresholdMs: 2 * 60 * 1000,
+    // ... other config
+  },
+});
+```
+
+---
+
+## Custom Payload Formatting
+
+Your API may expect a different payload structure. Use the formatters to customize:
+
+### Example 1: API requires `refresh` field
+
+```typescript
+useSessionTimeout({
+  config: {
+    refreshPayloadFormatter: (token) => ({
+      refresh: token, // API expects "refresh", not "token"
+    }),
+    logoutPayloadFormatter: (token) => ({
+      refresh: token,
+    }),
+  },
+});
+```
+
+**Request sent:**
+```json
+POST /api/auth/refresh/
+{ "refresh": "eyJhbGc..." }
+```
+
+### Example 2: Complex nested structure
+
+```typescript
+useSessionTimeout({
+  config: {
+    refreshPayloadFormatter: (token) => ({
+      action: 'refresh',
+      credentials: {
+        refresh_token: token,
+        client_id: 'my-client',
+      },
+    }),
+  },
+});
+```
+
+**Request sent:**
+```json
+POST /api/auth/refresh/
+{
+  "action": "refresh",
+  "credentials": {
+    "refresh_token": "eyJhbGc...",
+    "client_id": "my-client"
+  }
+}
+```
+
+---
+
+## Event Callbacks
+
+Full control over session lifecycle:
+
+```typescript
+useSessionTimeout({
+  config: { /* ... */ },
+  
+  // Called when token is about to expire
+  onSessionExpiring: () => {
+    console.warn('Token expiring soon');
+  },
+
+  // Called when user becomes idle
+  onIdle: () => {
+    console.log('User idle – logging out');
+  },
+
+  // Called when session has completely expired
+  onSessionExpired: () => {
+    console.log('Session expired – redirecting to login');
+    window.location.href = '/login';
+  },
+
+  // Called after successful token refresh
+  onRefreshSuccess: () => {
+    console.log('Token refreshed silently');
+  },
+
+  // Called on refresh failure
+  onRefreshFailure: (error) => {
+    console.error('Refresh failed:', error.message);
+  },
+});
+```
+
+---
+
+## Token Storage
+
+Tokens are stored in `sessionStorage` by default (cleared on browser close). To persist across tabs, use `localStorage`:
+
+```typescript
+import { storeToken, getStoredToken } from '@formreader/session-timeout';
+
+// Store persistently
+storeToken(token, true); // true = use localStorage
+
+// Retrieve (checks both storage types)
+const token = getStoredToken();
+```
+
+---
+
+## Token Inspection
+
+Decode and inspect JWT payloads without verification (client-side only):
+
+```typescript
+import { getTokenInfo, isTokenExpired, getTimeUntilExpiry } from '@formreader/session-timeout';
+
+const token = getStoredToken();
+
+// Get full token info
+const info = getTokenInfo(token);
+console.log(info.expiresAt);  // Unix timestamp (ms)
+console.log(info.expiresIn);  // Milliseconds until expiry
+console.log(info.payload);    // JWT payload object
+
+// Quick checks
+const expired = isTokenExpired(token);
+const timeLeft = getTimeUntilExpiry(token);
+```
+
+---
+
+## Global Session Manager
+
+For app-wide state, initialize the singleton once at startup:
+
+```typescript
+import { getSessionManager, resetSessionManager } from '@formreader/session-timeout';
+
+// App startup
+const manager = getSessionManager({
+  refreshThresholdMs: 2 * 60 * 1000,
+  idleTimeoutMs: 15 * 60 * 1000,
+  autoRefresh: true,
+  refreshEndpoint: '/api/auth/refresh/',
+  logoutEndpoint: '/api/auth/logout/',
+});
+
+manager.init();
+
+// Listen to events
+manager.on('tokenRefreshed', () => console.log('Token refreshed'));
+
+// Later, reset if needed (e.g., on logout)
+resetSessionManager();
+```
+
+---
+
+## TypeScript Support
+
+Full TypeScript definitions included:
+
+```typescript
+import {
+  SessionConfig,
+  SessionState,
+  TokenInfo,
+  JWTPayload,
+  RefreshTokenResponse,
+  UseSessionTimeoutOptions,
+} from '@formreader/session-timeout';
+
+const config: SessionConfig = {
+  refreshThresholdMs: 2 * 60 * 1000,
+  idleTimeoutMs: 15 * 60 * 1000,
+  // ... rest of config
+};
+```
+
+---
+
+## API Reference
+
+### `useSessionTimeout(options?)`
+
+React hook for session management in components.
+
+**Parameters:**
+- `options.enabled?: boolean` — Enable/disable the hook (default: `true`)
+- `options.config?: Partial<SessionConfig>` — Configuration (merged with defaults)
+- `options.onSessionExpiring?: () => void` — Callback before expiry
+- `options.onSessionExpired?: () => void` — Callback on expiry
+- `options.onIdle?: () => void` — Callback on idle
+- `options.onRefreshSuccess?: () => void` — Callback on refresh success
+- `options.onRefreshFailure?: (error: Error) => void` — Callback on refresh failure
+
+**Returns:**
+```typescript
+{
+  sessionState: SessionState;           // Current session state
+  timeUntilIdle: number | null;         // Milliseconds until idle
+  idleWarningVisible: boolean;          // Show idle warning
+  extendSession: () => void;            // Reset idle timer
+  refreshToken: () => Promise<boolean>; // Manually refresh
+  logout: () => Promise<void>;          // Logout
+  updateConfig: (newConfig) => void;    // Update config
+  manager: SessionManager;              // Underlying manager
+}
+```
+
+### `SessionManager`
+
+Direct access to session management service.
+
+**Methods:**
+- `init()` — Initialize session management
+- `refreshToken(): Promise<boolean>` — Refresh token
+- `logout(): Promise<void>` — Logout and cleanup
+- `extendSession()` — Reset idle timer
+- `getState(): SessionState` — Current state
+- `getConfig(): SessionConfig` — Current config
+- `updateConfig(newConfig)` — Update config
+- `on(event, callback): () => void` — Subscribe to events
+- `destroy()` — Cleanup and destroy manager
+
+**Events:**
+- `'initialized'` — Manager initialized
+- `'tokenRefreshed'` — Token successfully refreshed
+- `'idle'` — User became idle
+- `'activity'` — User activity detected
+- `'idleWarning'` — Idle warning (includes `timeRemaining`)
+- `'sessionExtended'` — Session extended
+- `'refreshFailed'` — Token refresh failed
+- `'loggedOut'` — Logged out
+
+### Token Service Functions
+
+- `getTokenInfo(token): TokenInfo | null` — Get token expiry and payload
+- `isTokenExpired(token, bufferMs?): boolean` — Check if token expired
+- `getTimeUntilExpiry(token): number` — Get milliseconds until expiry
+- `getStoredToken(): string | null` — Get token from storage
+- `storeToken(token, persistent?)` — Store token
+- `clearToken()` — Clear stored token
+- `validateToken(token)` — Validate token structure
+
+---
+
+## Production Checklist
+
+- [ ] Configure `refreshThresholdMs` for your token lifetime
+- [ ] Set `refreshEndpoint` to your backend refresh URL
+- [ ] Customize `refreshPayloadFormatter` if your API requires custom payload
+- [ ] Set appropriate `idleTimeoutMs` based on security requirements
+- [ ] Pass your app's HTTP client via `httpClient` option
+- [ ] Test token refresh before token expires
+- [ ] Test idle timeout and warning
+- [ ] Handle `onSessionExpired` to redirect to login
+- [ ] Disable `debug: true` in production
+- [ ] Monitor `onRefreshFailure` for refresh failures
+
+---
+
+## Browser Support
+
+- Chrome/Edge: ✅ All versions
+- Firefox: ✅ All versions
+- Safari: ✅ 12+
+- Mobile: ✅ iOS 12+, Android 5+
+
+Requires `fetch` API or polyfill.
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Session Timeout Micro Frontend Types
+ * Configurable, reusable types for multi-application token refresh management
+ */
+interface SessionConfig {
+    /** Time before token expiry to trigger refresh (milliseconds) */
+    refreshThresholdMs: number;
+    /** Interval to check for idle activity (milliseconds) */
+    idleCheckIntervalMs: number;
+    /** Time of inactivity before session expires (milliseconds) */
+    idleTimeoutMs: number;
+    /** Maximum session duration regardless of activity (milliseconds) */
+    maxSessionDurationMs: number;
+    /** Endpoint to call for token refresh */
+    refreshEndpoint: string;
+    /** Endpoint to call for logout */
+    logoutEndpoint: string;
+    /** Whether to show idle warning dialog */
+    showIdleWarning: boolean;
+    /** Time before idle timeout to show warning (milliseconds) */
+    idleWarningThresholdMs: number;
+    /** Callback when session is about to expire */
+    onSessionExpiring?: () => void;
+    /** Callback when user is idle */
+    onIdle?: () => void;
+    /** Callback when session has expired */
+    onSessionExpired?: () => void;
+    /** Callback on refresh success */
+    onRefreshSuccess?: () => void;
+    /** Callback on refresh failure */
+    onRefreshFailure?: (error: Error) => void;
+    /** Whether to auto-refresh before expiry */
+    autoRefresh: boolean;
+    /** Debug mode for logging */
+    debug: boolean;
+    /** Optional HTTP client to use for refresh/logout calls. If not provided, will use fetch. */
+    httpClient?: {
+        post: (url: string, body?: any, options?: any) => Promise<{
+            data: any;
+        }>;
+    };
+    /** Custom function to format the refresh request payload. Allows you to define exactly what data is sent to your API. */
+    refreshPayloadFormatter?: (token: string) => Record<string, any>;
+    /** Custom function to format the logout request payload. Allows you to define exactly what data is sent to your API. */
+    logoutPayloadFormatter?: (token: string) => Record<string, any>;
+}
+interface JWTPayload {
+    exp: number;
+    iat: number;
+    sub?: string;
+    [key: string]: any;
+}
+interface TokenInfo {
+    token: string;
+    expiresAt: number;
+    expiresIn: number;
+    payload: JWTPayload;
+}
+interface SessionState {
+    isActive: boolean;
+    isIdle: boolean;
+    tokenExpiry?: number;
+    lastActivityTime: number;
+    refreshAttempts: number;
+    isRefreshing: boolean;
+}
+interface RefreshTokenResponse {
+    token: string;
+    access_token?: string;
+    expiresIn?: number;
+    [key: string]: any;
+}
+declare const DEFAULT_SESSION_CONFIG: SessionConfig;
+
+/**
+ * Session Manager Service
+ * Manages token refresh, idle tracking, and session lifecycle
+ */
+
+declare class SessionManager {
+    private config;
+    private state;
+    private refreshTimer;
+    private idleTimer;
+    private idleCheckTimer;
+    private maxSessionTimer;
+    private listeners;
+    private requestDeduplication;
+    constructor(config: Partial<SessionConfig>);
+    /**
+     * Initialize session management
+     */
+    init(): void;
+    /**
+     * Setup token refresh before expiry
+     */
+    private setupTokenRefresh;
+    /**
+     * Setup idle activity tracking
+     */
+    private setupIdleTracking;
+    /**
+     * Setup max session duration timer
+     */
+    private setupMaxSessionDuration;
+    /**
+     * Refresh token
+     */
+    refreshToken(): Promise<boolean>;
+    /**
+     * Logout and cleanup
+     */
+    logout(): Promise<void>;
+    /**
+     * Extend session (reset idle timer)
+     */
+    extendSession(): void;
+    /**
+     * Get current state
+     */
+    getState(): SessionState;
+    /**
+     * Get current config
+     */
+    getConfig(): SessionConfig;
+    /**
+     * Update config
+     */
+    updateConfig(newConfig: Partial<SessionConfig>): void;
+    /**
+     * Event listeners
+     */
+    on(event: string, callback: Function): () => void;
+    /**
+     * Emit event
+     */
+    private emit;
+    /**
+     * Cleanup timers and listeners
+     */
+    private cleanup;
+    /**
+     * Destroy session manager
+     */
+    destroy(): void;
+    /**
+     * Logging utility
+     */
+    private log;
+}
+declare function getSessionManager(config?: Partial<SessionConfig>): SessionManager;
+declare function resetSessionManager(): void;
+
+/**
+ * Token Service
+ * Handles JWT token parsing, decoding, and expiry calculations
+ */
+
+/**
+ * Get token info including expiry time
+ */
+declare function getTokenInfo(token: string): TokenInfo | null;
+/**
+ * Check if token is expired
+ */
+declare function isTokenExpired(token: string, bufferMs?: number): boolean;
+/**
+ * Get remaining time until token expiry
+ */
+declare function getTimeUntilExpiry(token: string): number;
+/**
+ * Extract token from storage
+ */
+declare function getStoredToken(): string | null;
+/**
+ * Store token in appropriate storage
+ */
+declare function storeToken(token: string, persistent?: boolean): void;
+/**
+ * Clear stored token
+ */
+declare function clearToken(): void;
+/**
+ * Validate token structure and expiry
+ */
+declare function validateToken(token: string): {
+    valid: boolean;
+    error?: string;
+};
+
+/**
+ * useSessionTimeout Hook
+ * React hook for session timeout management in components
+ */
+
+interface UseSessionTimeoutOptions {
+    config?: Partial<SessionConfig>;
+    enabled?: boolean;
+    onSessionExpiring?: () => void;
+    onSessionExpired?: () => void;
+    onIdle?: () => void;
+    onRefreshSuccess?: () => void;
+}
+declare function useSessionTimeout(options?: UseSessionTimeoutOptions): {
+    sessionState: SessionState;
+    timeUntilExpiry: any;
+    timeUntilIdle: number;
+    idleWarningVisible: boolean;
+    extendSession: () => void;
+    refreshToken: () => Promise<boolean>;
+    logout: () => Promise<void>;
+    updateConfig: (newConfig: Partial<SessionConfig>) => void;
+    manager: SessionManager;
+};
+
+export { DEFAULT_SESSION_CONFIG, JWTPayload, RefreshTokenResponse, SessionConfig, SessionManager, SessionState, TokenInfo, UseSessionTimeoutOptions, clearToken, getSessionManager, getStoredToken, getTimeUntilExpiry, getTokenInfo, isTokenExpired, resetSessionManager, storeToken, useSessionTimeout, validateToken };