@drmhse/sso-sdk 0.2.7 → 0.2.9

package/README.md

@@ -12,6 +12,8 @@ A zero-dependency, strongly-typed TypeScript SDK for the multi-tenant SSO Platfo
 - **Zero Dependencies** - Built on native `fetch` API
 - **Strongly Typed** - Complete TypeScript definitions
 - **Framework Agnostic** - Works in any JavaScript environment
+- **Automatic Session Management** - Invisible token persistence and auto-refresh
+- **Smart Token Handling** - Auto-inject tokens and handle 401 errors transparently
 - **OAuth 2.0 Flows** - Support for GitHub, Google, Microsoft
 - **Password Authentication** - Native email/password auth with MFA
 - **Device Flow** - RFC 8628 for CLIs and headless apps
@@ -31,17 +33,21 @@ npm install @drmhse/sso-sdk
 ```typescript
 import { SsoClient } from '@drmhse/sso-sdk';
 
-// Initialize the client
+// Initialize the client - automatically loads tokens from localStorage
 const sso = new SsoClient({
-  baseURL: 'https://sso.example.com',
-  token: localStorage.getItem('sso_access_token')
+  baseURL: 'https://sso.example.com'
 });
 
-// Get user profile
+// Login - session is automatically saved
+await sso.auth.login({
+  email: 'user@example.com',
+  password: 'SecurePass123!'
+});
+
+// Make authenticated requests - tokens auto-injected and auto-refreshed
 const profile = await sso.user.getProfile();
 console.log(profile.email);
 
-// List organizations
 const orgs = await sso.organizations.list();
 console.log(orgs);
 ```
@@ -67,15 +73,18 @@ const loginUrl = sso.auth.getLoginUrl('github', {
 });
 window.location.href = loginUrl;
 
-// Handle callback
+// Handle callback - initialize client with token from OAuth callback
 const params = new URLSearchParams(window.location.search);
 const accessToken = params.get('access_token');
-const refreshToken = params.get('refresh_token');
 
-if (accessToken && refreshToken) {
-  sso.setAuthToken(accessToken);
-  localStorage.setItem('sso_access_token', accessToken);
-  localStorage.setItem('sso_refresh_token', refreshToken);
+if (accessToken) {
+  // Initialize SDK with OAuth token - automatically stored
+  const sso = new SsoClient({
+    baseURL: 'https://sso.example.com',
+    token: accessToken
+  });
+  // Token is now automatically stored and managed
+  window.location.href = '/dashboard';
 }
 ```
 
@@ -89,19 +98,20 @@ await sso.auth.register({
   org_slug: 'acme-corp'
 });
 
-// Login with password
-const tokens = await sso.auth.login({
+// Login with password - session automatically saved
+await sso.auth.login({
   email: 'user@example.com',
   password: 'SecurePass123!'
 });
-sso.setAuthToken(tokens.access_token);
+// Tokens are now automatically stored and injected on all requests
 
 // Enable MFA
 const mfaSetup = await sso.user.mfa.setup();
-console.log(mfaSetup.qr_code); // Display QR code to user
+console.log(mfaSetup.qr_code_svg); // Display QR code to user
 
-// Verify and enable
-await sso.user.mfa.verify('123456'); // TOTP code from authenticator app
+// Verify and enable - automatically saves backup codes
+const result = await sso.user.mfa.verify('123456'); // TOTP code from authenticator app
+console.log('Backup codes:', result.backup_codes); // Save these securely!
 ```
 
 ### Device Flow (for CLIs)
@@ -122,10 +132,16 @@ const interval = setInterval(async () => {
   try {
     const tokens = await sso.auth.deviceCode.exchangeToken({
       device_code: deviceAuth.device_code,
-      client_id: 'cli-client'
+      client_id: 'cli-client',
+      grant_type: 'urn:ietf:params:oauth:grant-type:device_code'
+    });
+
+    // Initialize SDK with the token - automatically stored
+    const authenticatedSso = new SsoClient({
+      baseURL: 'https://sso.example.com',
+      token: tokens.access_token
     });
 
-    sso.setAuthToken(tokens.access_token);
     clearInterval(interval);
     console.log('Authentication successful!');
   } catch (error) {
@@ -136,16 +152,29 @@ const interval = setInterval(async () => {
 
 ### Token Refresh
 
+**Automatic Token Refresh** - The SDK automatically refreshes expired tokens when it detects a 401 error:
+
 ```typescript
+// No manual refresh needed! Just make your API calls
 try {
-  const tokens = await sso.auth.refreshToken(storedRefreshToken);
-
-  sso.setAuthToken(tokens.access_token);
-  localStorage.setItem('sso_access_token', tokens.access_token);
-  localStorage.setItem('sso_refresh_token', tokens.refresh_token);
+  // If the access token is expired, the SDK will:
+  // 1. Detect the 401 error
+  // 2. Use the refresh token to get new tokens
+  // 3. Retry the request automatically
+  // 4. Return the result - you never see the 401!
+  const profile = await sso.user.getProfile();
+  console.log(profile);
 } catch (error) {
-  // Refresh failed - redirect to login
-  console.error('Token refresh failed:', error);
+  // You'll only see errors if refresh fails (e.g., refresh token expired)
+  console.error('Session expired - please log in again');
+  // Redirect to login
+}
+
+// Optional: Manually refresh if needed (advanced use case)
+const currentRefreshToken = await sso.getToken();
+if (currentRefreshToken) {
+  const tokens = await sso.auth.refreshToken(currentRefreshToken);
+  // Tokens automatically updated
 }
 ```
 
@@ -239,14 +268,26 @@ try {
     console.error(`Code: ${error.errorCode}`);
 
     if (error.status === 401) {
-      // Token expired - refresh or re-authenticate
+      // Session expired (refresh token also expired)
+      // Automatic refresh already tried and failed
+      // Redirect to login
+      window.location.href = '/login';
     } else if (error.status === 403) {
       // Forbidden - insufficient permissions
+      console.error('You do not have permission to access this resource');
     }
   } else {
     console.error('Unexpected error:', error);
   }
 }
+
+// React to authentication state changes
+sso.onAuthStateChange((isAuthenticated) => {
+  if (!isAuthenticated) {
+    // User logged out or session expired
+    window.location.href = '/login';
+  }
+});
 ```
 
 ## Platform Administration