een-api-toolkit 0.3.16 → 0.3.22

package/examples/vue-event-subscriptions/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "vue-event-subscriptions-example",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "stop": "lsof -ti :3333 2>/dev/null | xargs -r kill -9 || echo 'Port 3333 is free'",
+    "dev": "npm run stop && vite",
+    "build": "vue-tsc && vite build",
+    "preview": "vite preview",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui"
+  },
+  "dependencies": {
+    "een-api-toolkit": "file:../..",
+    "hls.js": "^1.6.15",
+    "pinia": "^3.0.4",
+    "vue": "^3.4.0",
+    "vue-router": "^4.2.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.57.0",
+    "@vitejs/plugin-vue": "^6.0.0",
+    "dotenv": "^17.2.3",
+    "typescript": "~5.8.0",
+    "vite": "^7.3.0",
+    "vue-tsc": "^3.2.1"
+  }
+}

package/examples/vue-event-subscriptions/playwright.config.ts

@@ -0,0 +1,47 @@
+import { defineConfig, devices } from '@playwright/test'
+import dotenv from 'dotenv'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+// Load .env files: parent first, then local with override to replace any conflicts
+// In CI, env vars are passed directly via workflow
+dotenv.config({ path: path.resolve(__dirname, '../../.env') })
+dotenv.config({ path: path.resolve(__dirname, '.env'), override: true })
+
+const redirectUri = process.env.VITE_REDIRECT_URI || 'http://127.0.0.1:3333'
+if (!redirectUri.startsWith('http://127.0.0.1:') && !redirectUri.startsWith('http://localhost:')) {
+  throw new Error('VITE_REDIRECT_URI must use localhost or 127.0.0.1 for security')
+}
+export const baseURL = redirectUri
+
+export default defineConfig({
+  testDir: './e2e',
+  testMatch: '**/*.spec.ts',
+  fullyParallel: false, // Run tests sequentially for predictable order
+  forbidOnly: !!process.env.CI,
+  retries: 0, // No retries - fail fast
+  maxFailures: 1, // Stop on first failure
+  workers: 1,
+  reporter: [['html', { open: 'never' }]],
+  timeout: 60000, // Longer timeout for SSE operations
+  use: {
+    baseURL,
+    trace: 'on-first-retry',
+    video: 'retain-on-failure'
+  },
+  outputDir: './e2e-results/',
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] }
+    }
+  ],
+  webServer: {
+    command: 'npm run dev',
+    url: baseURL,
+    reuseExistingServer: !process.env.CI,
+    timeout: 30000
+  }
+})

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

@@ -0,0 +1,193 @@
+<script setup lang="ts">
+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)
+const refreshFailed = computed(() => authStore.refreshFailed)
+const refreshFailedMessage = computed(() => authStore.refreshFailedMessage)
+const isRefreshing = computed(() => authStore.isRefreshing)
+
+function dismissRefreshError() {
+  authStore.clearRefreshFailed()
+}
+
+function handleRelogin() {
+  authStore.logout()
+  router.push('/login')
+}
+</script>
+
+<template>
+  <div class="app">
+    <!-- Session refresh banner -->
+    <div v-if="refreshFailed" class="refresh-banner error-banner">
+      <span>Session refresh failed: {{ refreshFailedMessage }}</span>
+      <div class="banner-actions">
+        <button class="small" @click="handleRelogin">Re-login</button>
+        <button class="small secondary" @click="dismissRefreshError">Dismiss</button>
+      </div>
+    </div>
+    <div v-else-if="isRefreshing" class="refresh-banner info-banner">
+      <span>Refreshing session...</span>
+    </div>
+
+    <header>
+      <h1 data-testid="app-title">EEN Event Subscriptions</h1>
+      <nav>
+        <router-link data-testid="nav-home" to="/">Home</router-link>
+        <router-link data-testid="nav-subscriptions" v-if="isAuthenticated" to="/subscriptions">Subscriptions</router-link>
+        <router-link data-testid="nav-live" v-if="isAuthenticated" to="/live">Live Events</router-link>
+        <router-link data-testid="nav-login" v-if="!isAuthenticated" to="/login">Login</router-link>
+        <router-link data-testid="nav-logout" v-if="isAuthenticated" to="/logout">Logout</router-link>
+      </nav>
+    </header>
+    <main>
+      <router-view />
+    </main>
+  </div>
+</template>
+
+<style>
+* {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen,
+    Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
+  line-height: 1.6;
+  color: #333;
+}
+
+.app {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 20px;
+}
+
+header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 30px;
+  padding-bottom: 20px;
+  border-bottom: 1px solid #eee;
+}
+
+header h1 {
+  font-size: 1.5rem;
+}
+
+nav {
+  display: flex;
+  gap: 20px;
+}
+
+nav a {
+  color: #42b883;
+  text-decoration: none;
+}
+
+nav a:hover {
+  text-decoration: underline;
+}
+
+nav a.router-link-active {
+  font-weight: bold;
+}
+
+button {
+  background: #42b883;
+  color: white;
+  border: none;
+  padding: 10px 20px;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 1rem;
+}
+
+button:hover {
+  background: #3aa876;
+}
+
+button:disabled {
+  background: #ccc;
+  cursor: not-allowed;
+}
+
+button.danger {
+  background: #e74c3c;
+}
+
+button.danger:hover {
+  background: #c0392b;
+}
+
+button.secondary {
+  background: #95a5a6;
+}
+
+button.secondary:hover {
+  background: #7f8c8d;
+}
+
+.error {
+  color: #e74c3c;
+  padding: 10px;
+  background: #fdf2f2;
+  border-radius: 4px;
+  margin: 10px 0;
+}
+
+.loading {
+  color: #666;
+  font-style: italic;
+}
+
+.success {
+  color: #27ae60;
+  padding: 10px;
+  background: #eafaf1;
+  border-radius: 4px;
+  margin: 10px 0;
+}
+
+/* Session refresh banner */
+.refresh-banner {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 12px 20px;
+  margin-bottom: 15px;
+  border-radius: 4px;
+  font-size: 14px;
+}
+
+.error-banner {
+  background: #fdf2f2;
+  color: #e74c3c;
+  border: 1px solid #f5c6cb;
+}
+
+.info-banner {
+  background: #e8f4fd;
+  color: #2980b9;
+  border: 1px solid #bee5eb;
+}
+
+.banner-actions {
+  display: flex;
+  gap: 8px;
+}
+
+button.small {
+  padding: 6px 12px;
+  font-size: 12px;
+}
+</style>

package/examples/vue-event-subscriptions/src/composables/useHlsPlayer.ts

@@ -0,0 +1,272 @@
+import { ref, nextTick, onUnmounted, type Ref } from 'vue'
+import { listMedia, formatTimestamp, useAuthStore } from 'een-api-toolkit'
+import Hls from 'hls.js'
+import { useMediaSessionStore } from '../stores/mediaSession'
+
+// Constants
+const SEARCH_WINDOW_MS = 60 * 60 * 1000 // 1 hour before/after target timestamp
+const MAX_MEDIA_PAGE_SIZE = 100 // Limit results for performance
+const MAX_NETWORK_RETRIES = 3 // Maximum retry attempts for network errors
+
+// Debug utility - logs only when VITE_DEBUG=true
+const isDebug = import.meta.env?.VITE_DEBUG === 'true'
+function debugError(...args: unknown[]): void {
+  if (isDebug) {
+    console.error('[useHlsPlayer]', ...args)
+  }
+}
+
+/** Return type for the useHlsPlayer composable */
+export interface HlsPlayerReturn {
+  videoUrl: Ref<string | null>
+  videoError: Ref<string | null>
+  loadingVideo: Ref<boolean>
+  videoRef: Ref<HTMLVideoElement | null>
+  loadVideo: (deviceId: string, timestamp: string) => Promise<void>
+  resetVideo: () => void
+  destroyHls: () => void
+}
+
+/**
+ * Composable for HLS video playback from EEN recordings.
+ * Handles media session initialization, interval search, and HLS.js setup.
+ * Uses Pinia store for media session state to ensure consistent behavior
+ * across all component instances.
+ */
+export function useHlsPlayer(): HlsPlayerReturn {
+  const authStore = useAuthStore()
+  const mediaSessionStore = useMediaSessionStore()
+
+  // State
+  const videoUrl = ref<string | null>(null)
+  const videoError = ref<string | null>(null)
+  const loadingVideo = ref(false)
+  const videoRef = ref<HTMLVideoElement | null>(null)
+
+  let hlsInstance: Hls | null = null
+  let networkRetryCount = 0
+
+  /**
+   * Initialize media session with caching via Pinia store.
+   * Only calls the API once per session, subsequent calls return cached result.
+   */
+  async function ensureMediaSession(): Promise<boolean> {
+    const success = await mediaSessionStore.ensureInitialized()
+    if (!success && mediaSessionStore.error) {
+      videoError.value = mediaSessionStore.error
+    }
+    return success
+  }
+
+  /**
+   * Destroy the HLS instance and clean up resources.
+   */
+  function destroyHls() {
+    if (hlsInstance) {
+      hlsInstance.destroy()
+      hlsInstance = null
+    }
+  }
+
+  /**
+   * Initialize HLS.js with proper authentication and error handling.
+   */
+  function initHls() {
+    if (!videoUrl.value || !videoRef.value) return
+
+    destroyHls()
+
+    // Always use hls.js even on Safari - native HLS cannot send Authorization headers
+    if (!Hls.isSupported()) {
+      videoError.value = 'HLS is not supported in this browser. Please use a modern browser like Chrome, Firefox, or Edge.'
+      return
+    }
+
+    // Configure hls.js to send Authorization header for authentication
+    hlsInstance = new Hls({
+      xhrSetup: function(xhr) {
+        xhr.setRequestHeader('Authorization', `Bearer ${authStore.token}`)
+      }
+    })
+
+    hlsInstance.loadSource(videoUrl.value)
+    hlsInstance.attachMedia(videoRef.value)
+
+    hlsInstance.on(Hls.Events.MANIFEST_PARSED, () => {
+      // Reset retry counter on successful manifest parse
+      networkRetryCount = 0
+      videoRef.value?.play().catch(() => {
+        // Autoplay may be blocked, user can manually play
+      })
+    })
+
+    // Enhanced error handling for different error types
+    hlsInstance.on(Hls.Events.ERROR, (_, data) => {
+      debugError('HLS error:', data)
+
+      if (data.fatal) {
+        switch (data.type) {
+          case Hls.ErrorTypes.NETWORK_ERROR:
+            // Network error - could be auth issue or connectivity
+            if (data.response?.code === 401) {
+              videoError.value = 'Authentication expired. Please refresh the page and try again.'
+              // Don't retry on auth errors - requires user action
+              destroyHls()
+            } else if (data.response?.code === 403) {
+              videoError.value = 'Access denied to video stream.'
+              // Don't retry on permission errors
+              destroyHls()
+            } else {
+              // Retry other network errors with limit
+              networkRetryCount++
+              if (networkRetryCount <= MAX_NETWORK_RETRIES) {
+                videoError.value = `Network error loading video: ${data.details}. Retry ${networkRetryCount}/${MAX_NETWORK_RETRIES}...`
+                hlsInstance?.startLoad()
+              } else {
+                videoError.value = `Network error loading video: ${data.details}. Max retries (${MAX_NETWORK_RETRIES}) exceeded.`
+                destroyHls()
+              }
+            }
+            break
+
+          case Hls.ErrorTypes.MEDIA_ERROR:
+            // Media error - try to recover
+            videoError.value = `Media error: ${data.details}. Attempting recovery...`
+            hlsInstance?.recoverMediaError()
+            break
+
+          default:
+            // Other fatal errors
+            videoError.value = `HLS error: ${data.type} - ${data.details}`
+            destroyHls()
+        }
+      }
+    })
+  }
+
+  /**
+   * Load and play HLS video for a given device and timestamp.
+   *
+   * @param deviceId - The camera device ID
+   * @param timestamp - ISO timestamp string (the target time to find video for)
+   * @returns Promise that resolves when video is ready or error occurs
+   */
+  async function loadVideo(deviceId: string, timestamp: string): Promise<void> {
+    loadingVideo.value = true
+    videoError.value = null
+    videoUrl.value = null
+    networkRetryCount = 0 // Reset retry counter for new video load
+
+    // Initialize media session (cached after first call)
+    const sessionOk = await ensureMediaSession()
+    if (!sessionOk) {
+      loadingVideo.value = false
+      return
+    }
+
+    // Search for recordings around the target timestamp
+    const targetTime = new Date(timestamp)
+    const searchStartTime = new Date(targetTime.getTime() - SEARCH_WINDOW_MS)
+    const searchEndTime = new Date(targetTime.getTime() + SEARCH_WINDOW_MS)
+
+    // Use 'main' type for video - HLS is typically only available for main feeds
+    const result = await listMedia({
+      deviceId,
+      type: 'main',
+      mediaType: 'video',
+      startTimestamp: formatTimestamp(searchStartTime.toISOString()),
+      endTimestamp: formatTimestamp(searchEndTime.toISOString()),
+      include: ['hlsUrl'],
+      pageSize: MAX_MEDIA_PAGE_SIZE
+    })
+
+    if (result.error) {
+      videoError.value = result.error.message
+      loadingVideo.value = false
+      return
+    }
+
+    const intervals = result.data?.results ?? []
+
+    // Validate target timestamp
+    const targetTimeMs = targetTime.getTime()
+    if (isNaN(targetTimeMs)) {
+      videoError.value = `Invalid timestamp format: ${timestamp}`
+      loadingVideo.value = false
+      return
+    }
+
+    // Find an interval that contains the target timestamp and has an HLS URL
+    const interval = intervals.find(i => {
+      if (!i.hlsUrl) return false
+      const intervalStart = new Date(i.startTimestamp).getTime()
+      const intervalEnd = new Date(i.endTimestamp).getTime()
+      // Skip intervals with invalid timestamps
+      if (isNaN(intervalStart) || isNaN(intervalEnd)) return false
+      return targetTimeMs >= intervalStart && targetTimeMs <= intervalEnd
+    })
+
+    if (!interval?.hlsUrl) {
+      // Provide detailed error message
+      if (intervals.length === 0) {
+        videoError.value = 'No recordings found for this time range'
+      } else if (!intervals.some(i => i.hlsUrl)) {
+        videoError.value = 'Recordings found but HLS not available'
+      } else {
+        videoError.value = `No recording contains timestamp ${timestamp}`
+      }
+      loadingVideo.value = false
+      return
+    }
+
+    // Set the HLS URL
+    videoUrl.value = interval.hlsUrl
+    loadingVideo.value = false
+
+    // Initialize HLS.js after the DOM has been updated
+    await nextTick()
+    initHls()
+  }
+
+  /**
+   * Reset all video state.
+   */
+  function resetVideo() {
+    destroyHls()
+    videoUrl.value = null
+    videoError.value = null
+    loadingVideo.value = false
+  }
+
+  // Cleanup on unmount
+  onUnmounted(() => {
+    destroyHls()
+  })
+
+  return {
+    // State
+    videoUrl,
+    videoError,
+    loadingVideo,
+    videoRef,
+
+    // Methods
+    loadVideo,
+    resetVideo,
+    destroyHls
+  }
+}
+
+/**
+ * Reset the media session cache.
+ * Call this when the user logs out or the session expires to ensure
+ * a fresh media session is initialized on next use.
+ *
+ * @remarks
+ * This delegates to the Pinia media session store's reset method.
+ * Must be called from within a Vue component context or after Pinia is installed.
+ */
+export function resetMediaSessionCache(): void {
+  const mediaSessionStore = useMediaSessionStore()
+  mediaSessionStore.reset()
+}

package/examples/vue-event-subscriptions/src/main.ts

@@ -0,0 +1,25 @@
+import { createApp } from 'vue'
+import { createPinia } from 'pinia'
+import { initEenToolkit } from 'een-api-toolkit'
+import App from './App.vue'
+import router from './router'
+
+const app = createApp(App)
+
+// Install Pinia (required before initEenToolkit)
+app.use(createPinia())
+
+// Initialize EEN API Toolkit with sessionStorage
+// Note: Using 'sessionStorage' means tokens persist within the browser tab session
+initEenToolkit({
+  proxyUrl: import.meta.env.VITE_PROXY_URL,
+  clientId: import.meta.env.VITE_EEN_CLIENT_ID,
+  redirectUri: import.meta.env.VITE_REDIRECT_URI,
+  storageStrategy: 'sessionStorage',
+  debug: import.meta.env.VITE_DEBUG === 'true'
+})
+
+// Install router
+app.use(router)
+
+app.mount('#app')

package/examples/vue-event-subscriptions/src/router/index.ts

@@ -0,0 +1,68 @@
+import { createRouter, createWebHistory } from 'vue-router'
+import { useAuthStore } from 'een-api-toolkit'
+import Home from '../views/Home.vue'
+import Login from '../views/Login.vue'
+import Callback from '../views/Callback.vue'
+import Subscriptions from '../views/Subscriptions.vue'
+import LiveEvents from '../views/LiveEvents.vue'
+import Logout from '../views/Logout.vue'
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    {
+      path: '/',
+      name: 'home',
+      component: Home,
+      // Handle OAuth callback on root path (EEN IDP redirects to http://127.0.0.1:3333)
+      beforeEnter: (to, _from, next) => {
+        // If URL has code and state params, it's an OAuth callback
+        if (to.query.code && to.query.state) {
+          next({ name: 'callback', query: to.query })
+        } else {
+          next()
+        }
+      }
+    },
+    {
+      path: '/login',
+      name: 'login',
+      component: Login
+    },
+    {
+      path: '/callback',
+      name: 'callback',
+      component: Callback
+    },
+    {
+      path: '/subscriptions',
+      name: 'subscriptions',
+      component: Subscriptions,
+      meta: { requiresAuth: true }
+    },
+    {
+      path: '/live',
+      name: 'live',
+      component: LiveEvents,
+      meta: { requiresAuth: true }
+    },
+    {
+      path: '/logout',
+      name: 'logout',
+      component: Logout
+    }
+  ]
+})
+
+// Navigation guard for protected routes
+router.beforeEach((to, _from, next) => {
+  const authStore = useAuthStore()
+
+  if (to.meta.requiresAuth && !authStore.isAuthenticated) {
+    next({ name: 'login' })
+  } else {
+    next()
+  }
+})
+
+export default router