@emblemvault/auth-sdk 2.3.2 → 2.3.3

package/README.md

@@ -103,6 +103,17 @@ Retrieves or generates the vault API key.
 #### `logout(): void`
 Clears the current session.
 
+#### `hydrateSession(session: AuthSession): void`
+Restores a session from external storage. Useful for Node.js environments where `localStorage` is not available. This activates the auto-refresh timer.
+
+```typescript
+// Restore session from file/database
+const saved = await loadSessionFromFile();
+if (saved) {
+  auth.hydrateSession(saved);
+}
+```
+
 #### `on(event, handler): void`
 Subscribe to authentication events.
 
@@ -143,6 +154,51 @@ const auth = new EmblemAuthSDK({
 - Calling `logout()` clears the persisted session
 - Works gracefully in private browsing mode (falls back to memory-only)
 
+### Node.js Usage
+
+In Node.js environments, `localStorage` is not available, so you must implement your own session persistence. The SDK's auto-refresh timer still works—use `hydrateSession()` to restore sessions and subscribe to events to keep your storage in sync.
+
+```typescript
+import { EmblemAuthSDK } from '@emblemvault/auth-sdk';
+import fs from 'fs/promises';
+
+const SESSION_FILE = './session.json';
+
+const auth = new EmblemAuthSDK({
+  appId: 'your-app-id',
+  persistSession: false // No effect in Node.js, but explicit
+});
+
+// Restore session from file on startup
+async function restoreSession() {
+  try {
+    const data = await fs.readFile(SESSION_FILE, 'utf-8');
+    const session = JSON.parse(data);
+    auth.hydrateSession(session); // Activates auto-refresh timer
+  } catch {
+    // No saved session
+  }
+}
+
+// Keep file in sync with SDK's auto-refresh
+auth.on('sessionRefreshed', async (session) => {
+  await fs.writeFile(SESSION_FILE, JSON.stringify(session));
+});
+
+auth.on('sessionExpired', async () => {
+  await fs.unlink(SESSION_FILE).catch(() => {});
+});
+
+// Initialize
+await restoreSession();
+```
+
+**Key points:**
+- `hydrateSession()` restores the session and starts the auto-refresh timer
+- The SDK will automatically refresh tokens ~60 seconds before expiry
+- Subscribe to `sessionRefreshed` to persist the new session after refresh
+- Subscribe to `sessionExpired` to clear your storage when refresh fails
+
 ### Types
 
 #### `VaultInfo`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emblemvault/auth-sdk",
-  "version": "2.3.2",
+  "version": "2.3.3",
   "description": "Official TypeScript SDK for Emblem Vault authentication and signing",
   "main": "dist/index.js",
   "module": "dist/index.mjs",