win-portal-auth-sdk 1.1.2 → 1.2.1

package/README.md

@@ -64,10 +64,23 @@ import authClient from '@/lib/auth-client';
 
 // Authentication
 const loginResult = await authClient.auth.login('user@example.com', 'password');
+
+// ✅ Set JWT token with explicit type (recommended for better performance)
+authClient.setToken(loginResult.token, 'jwt');
+
+// Or use hybrid mode (backward compatible)
+authClient.setToken(loginResult.token); // defaults to 'jwt'
+authClient.setAuthType('hybrid'); // will try JWT first, then OAuth
+
 const profile = await authClient.auth.profile();
 const refreshed = await authClient.auth.refresh(refreshToken);
 await authClient.auth.logout();
 
+// OAuth Token Usage
+// ✅ Set OAuth token with explicit type (recommended for better performance)
+const oauthToken = await authClient.oauth.exchangeCode(code, codeVerifier);
+authClient.setToken(oauthToken.access_token, 'oauth');
+
 // TOTP (Two-Factor Authentication)
 // 1. Setup TOTP for user
 const totpSetup = await authClient.auth.setupTotp('My App');
@@ -329,10 +342,90 @@ const client = new AuthClient({
 
 #### Utility Methods
 
+- `setToken(token, type?)` - Set authentication token
+  - `type`: `'jwt'` (default) | `'oauth'` | `'hybrid'`
+  - Recommended to specify type for better performance
+- `getAuthType()` - Get current authentication type
+- `setAuthType(type)` - Change authentication type
+- `clearToken()` - Clear authentication token
+- `getTokenMasked()` - Get masked token for display
 - `setApiKey(apiKey)` - Update API key
 - `getApiKeyMasked()` - Get masked API key for display
 - `getAxiosInstance()` - Get underlying axios instance
 
+## Authentication Types
+
+The SDK supports three authentication types through the `X-Auth-Type` header:
+
+### JWT Authentication (Recommended for internal users)
+
+```typescript
+// Login and get JWT token
+const session = await authClient.auth.login('user@example.com', 'password');
+
+// ✅ Specify 'jwt' for best performance (fast path validation)
+authClient.setToken(session.token, 'jwt');
+
+// All subsequent requests will include:
+// Authorization: Bearer <jwt_token>
+// X-Auth-Type: jwt
+```
+
+**Use JWT when:**
+
+- User logs in with username/password
+- Internal application users
+- Need session-based authentication
+
+### OAuth Authentication (Recommended for external apps)
+
+```typescript
+// Exchange authorization code for tokens
+const tokens = await authClient.oauth.exchangeCode(code, codeVerifier);
+
+// ✅ Specify 'oauth' for best performance (fast path validation)
+authClient.setToken(tokens.access_token, 'oauth');
+
+// All subsequent requests will include:
+// Authorization: Bearer <oauth_access_token>
+// X-Auth-Type: oauth
+```
+
+**Use OAuth when:**
+
+- Third-party application integration
+- User consent-based access
+- Need scope-based permissions
+
+### Hybrid Mode (Backward compatible)
+
+```typescript
+// Don't know token type or want automatic detection
+authClient.setToken(someToken, 'hybrid');
+
+// All subsequent requests will include:
+// Authorization: Bearer <token>
+// X-Auth-Type: hybrid
+
+// API will try JWT first, then fallback to OAuth
+```
+
+**Use Hybrid when:**
+
+- Backward compatibility needed
+- Token type is unknown
+- Migrating from old implementation
+
+### Performance Comparison
+
+| Auth Type | Validation           | Performance               | Use Case                       |
+| --------- | -------------------- | ------------------------- | ------------------------------ |
+| `jwt`     | JWT only             | ⚡ Fast (1 validation)    | Internal users, password login |
+| `oauth`   | OAuth only           | ⚡ Fast (1 validation)    | External apps, OAuth flow      |
+| `hybrid`  | JWT → OAuth fallback | 🐌 Slower (2 validations) | Unknown token type             |
+
+**💡 Tip:** Always specify `'jwt'` or `'oauth'` explicitly for ~50% faster authentication!
+
 ## Security Best Practices
 
 1. **Never commit API keys** - Use environment variables

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "win-portal-auth-sdk",
-  "version": "1.1.2",
-  "description": "Shared authentication SDK for Win Portal applications using API Key authentication",
+  "version": "1.2.1",
+  "description": "Shared authentication SDK for Win Portal applications with JWT and OAuth support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [