een-api-toolkit 0.3.38 → 0.3.43

package/.claude/agents/een-auth-agent.md

@@ -122,6 +122,32 @@ authStore.isAuthenticated // Computed: true if valid token exists
 authStore.isExpired      // Computed: true if token expired
 ```
 
+### authStore.initialize() - Session Restoration (CRITICAL)
+**Must be called in App.vue onMounted to restore sessions from storage.**
+
+Without this call, users must re-login after every page refresh, even with localStorage strategy:
+
+```vue
+<script setup lang="ts">
+import { onMounted, computed } from 'vue'
+import { useAuthStore } from 'een-api-toolkit'
+
+const authStore = useAuthStore()
+const isAuthenticated = computed(() => authStore.isAuthenticated)
+
+// CRITICAL: Restore session from storage on app mount
+onMounted(() => {
+  authStore.initialize()
+})
+</script>
+```
+
+What `initialize()` does:
+1. Loads token, expiration, session ID, base URL from storage
+2. If valid token exists: Sets up auto-refresh timer
+3. If expired token: Clears auth state (user must re-login)
+4. If no token: No action (user must login)
+
 ## Auth Guard Pattern
 
 **CRITICAL**: The OAuth callback check MUST come BEFORE the auth check in the global guard.
@@ -297,3 +323,5 @@ async function clearAuthState(page: Page): Promise<void> {
 | invalid_grant | Code expired or reused | Restart OAuth flow |
 | invalid_state | State mismatch | Clear storage, restart flow |
 | REFRESH_FAILED | Refresh token invalid | Redirect to login |
+| Session lost on refresh | Missing initialize() call | Add `authStore.initialize()` in App.vue onMounted |
+| Must login after refresh | Missing initialize() call | Add `authStore.initialize()` in App.vue onMounted |

package/.claude/agents/een-events-agent.md

@@ -269,12 +269,20 @@ async function fetchNotifications() {
 
 ## SSE (Server-Sent Events) for Real-Time Updates
 
+### SSE Subscription Behavior
+
+**Important: TTL is read-only and server-determined**
+- SSE subscriptions have a **15-minute TTL** (900 seconds) set by the server
+- The `timeToLiveSeconds` value **cannot be customized** when creating a subscription
+- The `subscriptionConfig` (including `lifeCycle` and `timeToLiveSeconds`) is returned in the API response but is not a configurable input
+- SSE URLs are **single-use**: once disconnected, you must create a new subscription
+
 ### SSE Lifecycle
 
-1. **Create Subscription** - Get a subscription with SSE URL
+1. **Create Subscription** - Get a subscription with SSE URL (server sets 15-min TTL)
 2. **Connect to Stream** - Open EventSource connection
 3. **Handle Events** - Process events as they arrive
-4. **Cleanup** - Delete subscription when done
+4. **Cleanup** - Delete subscription when done (or it auto-expires after 15 min of inactivity)
 
 ### createEventSubscription()
 ```typescript

package/.claude/agents/een-setup-agent.md

@@ -74,6 +74,35 @@ app.use(router)
 app.mount('#app')
 ```
 
+### App.vue Session Restoration (CRITICAL)
+**Users will need to re-login after every page refresh unless you call `authStore.initialize()` in App.vue.**
+
+```vue
+<script setup lang="ts">
+import { onMounted, computed } from 'vue'
+import { useAuthStore } from 'een-api-toolkit'
+
+const authStore = useAuthStore()
+const isAuthenticated = computed(() => authStore.isAuthenticated)
+
+// CRITICAL: Initialize auth store from storage on app mount
+// This restores the session if a valid token exists in localStorage/sessionStorage
+onMounted(() => {
+  authStore.initialize()
+})
+</script>
+```
+
+Without `initialize()`:
+- Token is saved to localStorage after login ✓
+- On page refresh, Pinia store starts with empty state
+- `isAuthenticated` returns false → user must login again
+
+With `initialize()`:
+- Token is loaded from localStorage on app mount
+- `isAuthenticated` returns true → session is restored
+- User can continue without re-logging in
+
 ### vite.config.ts for EEN OAuth
 ```typescript
 import { defineConfig } from 'vite'
@@ -115,6 +144,7 @@ export default router
 - Pinia must be installed before initEenToolkit()
 - Never add trailing slashes to redirect URIs
 - Ensure VITE_PROXY_URL is set in .env file
+- **Always call `authStore.initialize()` in App.vue onMounted** for session persistence
 
 ## Common Errors and Solutions
 
@@ -124,3 +154,5 @@ export default router
 | "redirect_uri mismatch" | Wrong host/port | Use 127.0.0.1:3333 in vite.config.ts |
 | "Invalid redirect_uri" | Trailing slash | Remove trailing slash from redirect URI |
 | "CORS error" | Proxy not running | Start the OAuth proxy server |
+| Session lost on refresh | Missing initialize() call | Add `authStore.initialize()` in App.vue onMounted |
+| Must login after refresh | Missing initialize() call | Add `authStore.initialize()` in App.vue onMounted |

package/CHANGELOG.md

@@ -2,92 +2,26 @@
 
 All notable changes to this project will be documented in this file.
 
-## [0.3.38] - 2026-01-24
+## [0.3.43] - 2026-01-25
 
 ### Release Summary
 
-#### PR #74: fix: Add missing agent, fix E2E test, and improve CI stability
-## Summary
-- Add missing `een-grouping-agent` to the setup-agents.ts script
-- Fix timezone issue in datetime persistence E2E test (vue-media)
-- Increase AUTH_COMPLETE timeout for better CI stability
-
-## Changes
-- `3f04224` fix: Fix timezone issue in datetime persistence E2E test
-- `fbf300c` fix: Add missing een-grouping-agent to setup script
-- `ea6ba9a` fix: Increase AUTH_COMPLETE timeout for CI stability
-
-## Test Results
-- ✅ Lint: passed
-- ✅ Unit tests: 378 passed
-- ✅ Build: successful
-- ✅ E2E tests: 137 passed across 9 example apps
-
-## Version
-`0.3.35`
-
-🤖 Generated with [Claude Code](https://claude.ai/code)
-
-#### PR #75: fix: Skip datetime persistence test in CI environments
-## Summary
-Skip the datetime persistence E2E test in CI environments to avoid timezone-related flaky failures.
-
-## Changes
-- `fa1d667` fix: Skip datetime persistence test in CI environments
-
-## Details
-The datetime persistence test relies on local timezone calculations that produce inconsistent results between CI (UTC) and local development environments. The test passes locally but fails in CI due to 1-hour timezone offsets.
-
-## Version
-`0.3.35`
-
-🤖 Generated with [Claude Code](https://claude.ai/code)
-
-#### PR #77: fix: UTC timezone for datetime test and include examples in version bump
-## Summary
-- Force UTC timezone in datetime persistence test for consistent CI/local behavior
-- Include examples folder in Husky version bump trigger
-
-## Changes
-- `3641923` fix: Force UTC timezone in datetime persistence test for CI consistency
-- `3a40255` chore: Include examples folder in version bump trigger
-- `0a99fb8` chore: Bump version to 0.3.37
-
-## Details
-
-### UTC Timezone Fix
-Instead of skipping the datetime persistence test in CI, the browser is now forced to use UTC timezone by overriding `Date.getTimezoneOffset()` via Playwright's `addInitScript`. This ensures consistent behavior across CI (UTC) and local development environments.
-
-Addresses issue #76.
-
-### Husky Update
-Changes to `examples/**/*` now trigger a package version increment, ensuring example app updates are properly versioned.
-
-## Version
-`0.3.37`
-
-🤖 Generated with [Claude Code](https://claude.ai/code)
-
+No PR descriptions available for this release.
 
 ### Detailed Changes
 
 #### Bug Fixes
-- fix: Skip datetime persistence test in CI
-- fix: Force UTC timezone in datetime persistence test for CI consistency
-- fix: Skip datetime persistence test in CI environments
-- fix: Fix timezone issue in datetime persistence E2E test
-- fix: Add missing een-grouping-agent to setup script
+- fix: Add authStore.initialize() to all example apps for session persistence
 
 #### Other Changes
-- chore: Bump version to 0.3.36
-- chore: Include examples folder in version bump trigger
-- Update examples/vue-media/e2e/auth.spec.ts
-- refactor: Address Gemini review - use shared formatDateTimeLocal utility
-- docs: Add een-grouping-agent to CLAUDE.md and improve E2E test
+- test: Add session persistence tests for login/logout and multi-tab scenarios
+- test: Add auth store session persistence tests for all storage strategies
+- chore: Add Session Persistence section to AI doc generation
+- docs: Clarify SSE subscription TTL is read-only and server-determined
 
 ### Links
 - [npm package](https://www.npmjs.com/package/een-api-toolkit)
-- [Full Changelog](https://github.com/klaushofrichter/een-api-toolkit/compare/v0.3.35...v0.3.38)
+- [Full Changelog](https://github.com/klaushofrichter/een-api-toolkit/compare/v0.3.38...v0.3.43)
 
 ---
-*Released: 2026-01-24 15:57:26 CST*
+*Released: 2026-01-25 12:06:28 CST*

package/docs/AI-CONTEXT.md

@@ -1,6 +1,6 @@
 # EEN API Toolkit - AI Reference
 
-> **Version:** 0.3.38
+> **Version:** 0.3.43
 >
 > This documentation is optimized for AI assistants. It provides focused, domain-specific
 > references to help you understand and use the een-api-toolkit efficiently.

package/docs/ai-reference/AI-AUTH.md

@@ -1,6 +1,6 @@
 # Authentication - EEN API Toolkit
 
-> **Version:** 0.3.38
+> **Version:** 0.3.43
 >
 > OAuth flow implementation, token management, and session handling.
 > Load this document when implementing login, logout, or auth guards.
@@ -98,6 +98,47 @@ authStore.sessionId        // Session identifier
 
 ---
 
+## Session Persistence (IMPORTANT)
+
+**To restore sessions from storage on page load, you must call `authStore.initialize()` in your App.vue.**
+
+Without this call, users will need to log in again after every page refresh, even with `localStorage` strategy.
+
+### App.vue Setup
+
+```vue
+<script setup lang="ts">
+import { onMounted, computed } from 'vue'
+import { useAuthStore } from 'een-api-toolkit'
+
+const authStore = useAuthStore()
+const isAuthenticated = computed(() => authStore.isAuthenticated)
+
+// CRITICAL: Initialize auth store from storage on app mount
+// This restores the session if a valid token exists in localStorage/sessionStorage
+onMounted(() => {
+  authStore.initialize()
+})
+</script>
+```
+
+### What initialize() Does
+
+1. Loads token, expiration, session ID, and base URL from configured storage
+2. If token exists and is **not expired**: Sets up auto-refresh timer
+3. If token exists but **is expired**: Clears auth state (user must re-login)
+4. If no token: No action (user must login)
+
+### Storage Strategy Behavior
+
+| Strategy | Persists Across Refresh? | Requires initialize()? |
+|----------|-------------------------|------------------------|
+| `localStorage` | Yes | Yes |
+| `sessionStorage` | Yes (within tab) | Yes |
+| `memory` | No | No (always requires re-login) |
+
+---
+
 ## Vue Router Auth Guard
 
 Protect routes that require authentication:

package/docs/ai-reference/AI-DEVICES.md

@@ -1,6 +1,6 @@
 # Cameras & Bridges API - EEN API Toolkit
 
-> **Version:** 0.3.38
+> **Version:** 0.3.43
 >
 > Complete reference for camera and bridge management.
 > Load this document when working with devices.

package/docs/ai-reference/AI-EVENTS.md

@@ -1,6 +1,6 @@
 # Events, Alerts & Real-Time Streaming - EEN API Toolkit
 
-> **Version:** 0.3.38
+> **Version:** 0.3.43
 >
 > Complete reference for events, alerts, metrics, and SSE subscriptions.
 > Load this document when implementing event-driven features.
@@ -1632,7 +1632,7 @@ watch(selectedSubscriptionId, (newId) => {
       <ul class="warning-list">
         <li>SSE URLs are single-use. Once disconnected, the subscription cannot be reconnected.</li>
         <li>To receive events again after disconnecting, create a new subscription.</li>
-        <li>Subscriptions have a 15-minute TTL and expire if not connected.</li>
+        <li>SSE subscriptions have a server-determined 15-minute TTL (not configurable) and expire if not connected.</li>
       </ul>
     </div>
 

package/docs/ai-reference/AI-MEDIA.md

@@ -1,6 +1,6 @@
 # Media & Live Video - EEN API Toolkit
 
-> **Version:** 0.3.38
+> **Version:** 0.3.43
 >
 > Complete reference for media retrieval, live streaming, and video playback.
 > Load this document when implementing video features.

package/docs/ai-reference/AI-SETUP.md

@@ -1,6 +1,6 @@
 # Vue 3 Application Setup - EEN API Toolkit
 
-> **Version:** 0.3.38
+> **Version:** 0.3.43
 >
 > Complete guide for setting up a Vue 3 application with the een-api-toolkit.
 > Load this document when creating a new project or troubleshooting setup issues.

package/docs/ai-reference/AI-USERS.md

@@ -1,6 +1,6 @@
 # Users API - EEN API Toolkit
 
-> **Version:** 0.3.38
+> **Version:** 0.3.43
 >
 > Complete reference for user management.
 > Load this document when working with user data.

package/examples/vue-alerts-metrics/src/App.vue

@@ -1,9 +1,15 @@
 <script setup lang="ts">
+import { onMounted, computed } from 'vue'
 import { useAuthStore } from 'een-api-toolkit'
-import { computed } from 'vue'
 
 const authStore = useAuthStore()
 const isAuthenticated = computed(() => authStore.isAuthenticated)
+
+// Initialize auth store from storage on app mount
+// This restores the session if a valid token exists in localStorage/sessionStorage
+onMounted(() => {
+  authStore.initialize()
+})
 </script>
 
 <template>

package/examples/vue-bridges/e2e/auth.spec.ts

@@ -203,4 +203,101 @@ test.describe('Vue Bridges Example - Auth', () => {
     await expect(page.locator('[data-testid="not-authenticated"]')).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
     await expect(page.locator('[data-testid="nav-login"]')).toBeVisible()
   })
+
+  test('after logout, localStorage is cleared and new login flow is required', async ({ page }) => {
+    skipIfNoProxy()
+    skipIfNoCredentials()
+
+    // First login
+    await performLogin(page, TEST_USER!, TEST_PASSWORD!)
+    await expect(page.locator('[data-testid="nav-logout"]')).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+
+    // Verify we're authenticated
+    await expect(page.locator('[data-testid="nav-bridges"]')).toBeVisible()
+
+    // Logout
+    await page.click('[data-testid="nav-logout"]')
+    await page.waitForURL('**/')
+    await expect(page.locator('[data-testid="not-authenticated"]')).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+
+    // Verify localStorage is cleared (session data removed)
+    const tokenAfterLogout = await page.evaluate(() => localStorage.getItem('een_token'))
+    expect(tokenAfterLogout).toBeNull()
+
+    const sessionIdAfterLogout = await page.evaluate(() => localStorage.getItem('een_sessionId'))
+    expect(sessionIdAfterLogout).toBeNull()
+
+    const hostnameAfterLogout = await page.evaluate(() => localStorage.getItem('een_hostname'))
+    expect(hostnameAfterLogout).toBeNull()
+
+    // Verify the app shows not-authenticated state (proves our session is cleared)
+    await expect(page.locator('[data-testid="not-authenticated"]')).toBeVisible()
+    await expect(page.locator('[data-testid="nav-login"]')).toBeVisible()
+    await expect(page.locator('[data-testid="nav-logout"]')).not.toBeVisible()
+
+    // Click login to start new OAuth flow
+    await page.click('[data-testid="login-button"]')
+    await page.waitForURL('/login')
+
+    // Click OAuth login button - this initiates the OAuth redirect
+    await page.click('button:has-text("Login with Eagle Eye Networks")')
+
+    // Wait for either:
+    // 1. OAuth page (if IDP session expired) - user needs to enter credentials
+    // 2. Callback/bridges page (if IDP remembers user via cookies) - auto-login
+    // Either way, our localStorage was cleared and user had to initiate a new login
+    await page.waitForURL(/eagleeyenetworks\.com|127\.0\.0\.1:3333/, { timeout: TIMEOUTS.AUTH_COMPLETE })
+
+    // If we ended up back at our app (auto-login via IDP cookies), verify we're authenticated again
+    const currentUrl = page.url()
+    if (currentUrl.includes('127.0.0.1:3333')) {
+      // Auto-logged in - wait for the full flow to complete
+      await page.waitForURL('**/bridges', { timeout: TIMEOUTS.AUTH_COMPLETE })
+      await expect(page.locator('[data-testid="nav-bridges"]')).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+      await expect(page.locator('[data-testid="nav-logout"]')).toBeVisible()
+
+      // Verify localStorage has new token (proves it was cleared and refilled)
+      const newToken = await page.evaluate(() => localStorage.getItem('een_token'))
+      expect(newToken).not.toBeNull()
+    } else {
+      // At OAuth page - user needs to enter credentials
+      const emailInput = page.locator('#authentication--input__email')
+      await expect(emailInput).toBeVisible({ timeout: TIMEOUTS.ELEMENT_VISIBLE })
+    }
+  })
+
+  test('localStorage: second tab shares session without re-login', async ({ page, context }) => {
+    skipIfNoProxy()
+    skipIfNoCredentials()
+
+    // First tab: login
+    await performLogin(page, TEST_USER!, TEST_PASSWORD!)
+    await expect(page.locator('[data-testid="nav-logout"]')).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+
+    // Verify localStorage has token
+    const tokenInFirstTab = await page.evaluate(() => localStorage.getItem('een_token'))
+    expect(tokenInFirstTab).not.toBeNull()
+
+    // Open second tab in same browser context (shares localStorage)
+    const secondTab = await context.newPage()
+    await secondTab.goto('/')
+
+    // Second tab should be authenticated immediately (no login needed)
+    // because localStorage is shared and App.vue calls initialize()
+    await expect(secondTab.locator('[data-testid="nav-logout"]')).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+    await expect(secondTab.locator('[data-testid="nav-bridges"]')).toBeVisible()
+    await expect(secondTab.locator('[data-testid="nav-login"]')).not.toBeVisible()
+
+    // Verify second tab has the same token from localStorage
+    const tokenInSecondTab = await secondTab.evaluate(() => localStorage.getItem('een_token'))
+    expect(tokenInSecondTab).toBe(tokenInFirstTab)
+
+    // Navigate to bridges in second tab - should work without login
+    await secondTab.click('[data-testid="nav-bridges"]')
+    await secondTab.waitForURL('**/bridges')
+    await expect(secondTab.locator('.bridge-grid, .no-bridges')).toBeVisible({ timeout: TIMEOUTS.ELEMENT_VISIBLE })
+
+    // Clean up second tab
+    await secondTab.close()
+  })
 })

package/examples/vue-bridges/src/App.vue

@@ -1,9 +1,15 @@
 <script setup lang="ts">
+import { onMounted, computed } from 'vue'
 import { useAuthStore } from 'een-api-toolkit'
-import { computed } from 'vue'
 
 const authStore = useAuthStore()
 const isAuthenticated = computed(() => authStore.isAuthenticated)
+
+// Initialize auth store from storage on app mount
+// This restores the session if a valid token exists in localStorage/sessionStorage
+onMounted(() => {
+  authStore.initialize()
+})
 </script>
 
 <template>

package/examples/vue-cameras/src/App.vue

@@ -1,9 +1,15 @@
 <script setup lang="ts">
+import { onMounted, computed } from 'vue'
 import { useAuthStore } from 'een-api-toolkit'
-import { computed } from 'vue'
 
 const authStore = useAuthStore()
 const isAuthenticated = computed(() => authStore.isAuthenticated)
+
+// Initialize auth store from storage on app mount
+// This restores the session if a valid token exists in localStorage/sessionStorage
+onMounted(() => {
+  authStore.initialize()
+})
 </script>
 
 <template>

package/examples/vue-event-subscriptions/src/App.vue

@@ -1,12 +1,18 @@
 <script setup lang="ts">
+import { onMounted, computed } from 'vue'
 import { useAuthStore } from 'een-api-toolkit'
-import { computed } from 'vue'
 import { useRouter } from 'vue-router'
 
 const authStore = useAuthStore()
 const router = useRouter()
 
 const isAuthenticated = computed(() => authStore.isAuthenticated)
+
+// Initialize auth store from storage on app mount
+// This restores the session if a valid token exists in localStorage/sessionStorage
+onMounted(() => {
+  authStore.initialize()
+})
 const refreshFailed = computed(() => authStore.refreshFailed)
 const refreshFailedMessage = computed(() => authStore.refreshFailedMessage)
 const isRefreshing = computed(() => authStore.isRefreshing)

package/examples/vue-event-subscriptions/src/views/LiveEvents.vue

@@ -380,7 +380,7 @@ watch(selectedSubscriptionId, (newId) => {
       <ul class="warning-list">
         <li>SSE URLs are single-use. Once disconnected, the subscription cannot be reconnected.</li>
         <li>To receive events again after disconnecting, create a new subscription.</li>
-        <li>Subscriptions have a 15-minute TTL and expire if not connected.</li>
+        <li>SSE subscriptions have a server-determined 15-minute TTL (not configurable) and expire if not connected.</li>
       </ul>
     </div>
 

package/examples/vue-events/src/App.vue

@@ -1,9 +1,15 @@
 <script setup lang="ts">
+import { onMounted, computed } from 'vue'
 import { useAuthStore } from 'een-api-toolkit'
-import { computed } from 'vue'
 
 const authStore = useAuthStore()
 const isAuthenticated = computed(() => authStore.isAuthenticated)
+
+// Initialize auth store from storage on app mount
+// This restores the session if a valid token exists in localStorage/sessionStorage
+onMounted(() => {
+  authStore.initialize()
+})
 </script>
 
 <template>

package/examples/vue-layouts/src/App.vue

@@ -1,9 +1,15 @@
 <script setup lang="ts">
+import { onMounted, computed } from 'vue'
 import { useAuthStore } from 'een-api-toolkit'
-import { computed } from 'vue'
 
 const authStore = useAuthStore()
 const isAuthenticated = computed(() => authStore.isAuthenticated)
+
+// Initialize auth store from storage on app mount
+// This restores the session if a valid token exists in localStorage/sessionStorage
+onMounted(() => {
+  authStore.initialize()
+})
 </script>
 
 <template>

package/examples/vue-users/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "een-api-toolkit-example",
-  "version": "0.0.25",
+  "version": "0.0.26",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "een-api-toolkit-example",
-      "version": "0.0.25",
+      "version": "0.0.26",
       "dependencies": {
         "een-api-toolkit": "file:../..",
         "pinia": "^3.0.4",

package/examples/vue-users/package.json

@@ -1,6 +1,6 @@
 {
   "name": "een-api-toolkit-example",
-  "version": "0.0.25",
+  "version": "0.0.26",
   "private": true,
   "type": "module",
   "scripts": {

package/examples/vue-users/src/App.vue

@@ -1,9 +1,15 @@
 <script setup lang="ts">
+import { onMounted, computed } from 'vue'
 import { useAuthStore } from 'een-api-toolkit'
-import { computed } from 'vue'
 
 const authStore = useAuthStore()
 const isAuthenticated = computed(() => authStore.isAuthenticated)
+
+// Initialize auth store from storage on app mount
+// This restores the session if a valid token exists in localStorage/sessionStorage
+onMounted(() => {
+  authStore.initialize()
+})
 </script>
 
 <template>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "een-api-toolkit",
-  "version": "0.3.38",
+  "version": "0.3.43",
   "description": "EEN Video platform API v3.0 library for Vue 3",
   "type": "module",
   "main": "./dist/index.cjs",