een-api-toolkit 0.3.16 → 0.3.22

package/examples/vue-events/src/components/EventsModal.vue

@@ -10,6 +10,11 @@ import {
   type EventType,
   type EenError
 } from 'een-api-toolkit'
+import { useHlsPlayer } from '../composables/useHlsPlayer'
+
+// Initialize HLS player composable
+const hlsPlayer = useHlsPlayer()
+const { videoUrl, videoError, loadingVideo, loadVideo, resetVideo } = hlsPlayer
 
 /**
  * Bounding box from object detection data.
@@ -82,6 +87,13 @@ const imageLoadingIds = ref<Set<string>>(new Set()) // Track which images are cu
 const boundingBoxCache = ref<Map<string, BoundingBox[]>>(new Map()) // Cache bounding boxes per event
 const enlargedEventId = ref<string | null>(null)
 
+// Lightbox media state
+const showVideo = ref(false)
+const hdImageUrl = ref<string | null>(null)
+const loadingHdImage = ref(false)
+const hdImageError = ref<string | null>(null)
+const currentMediaType = ref<'preview' | 'hd' | 'video'>('preview')
+
 // Computed
 const hasNextPage = computed(() => !!nextPageToken.value)
 const hasNoEvents = computed(() => !loading.value && events.value.length === 0 && !error.value)
@@ -382,11 +394,68 @@ function toggleAllEventTypes() {
 // Open enlarged image view
 function openEnlargedImage(eventId: string) {
   enlargedEventId.value = eventId
+  currentMediaType.value = 'preview'
+  showVideo.value = false
+  hdImageUrl.value = null
+  hdImageError.value = null
+  resetVideo()
 }
 
 // Close enlarged image view
 function closeEnlargedImage() {
   enlargedEventId.value = null
+  showVideo.value = false
+  hdImageUrl.value = null
+  hdImageError.value = null
+  currentMediaType.value = 'preview'
+  resetVideo()
+}
+
+// Switch to preview mode
+function showPreview() {
+  currentMediaType.value = 'preview'
+  showVideo.value = false
+  resetVideo()
+}
+
+// Load and show HD image
+async function showHdImage() {
+  if (!enlargedEvent.value) return
+
+  currentMediaType.value = 'hd'
+  showVideo.value = false
+  loadingHdImage.value = true
+  hdImageError.value = null
+  hdImageUrl.value = null
+  resetVideo()
+
+  const result = await getRecordedImage({
+    deviceId: enlargedEvent.value.actorId,
+    type: 'main',
+    timestamp__gte: enlargedEvent.value.startTimestamp
+  })
+
+  if (result.error) {
+    hdImageError.value = result.error.message
+  } else if (result.data?.imageData) {
+    hdImageUrl.value = result.data.imageData
+  } else {
+    hdImageError.value = 'No image data returned'
+  }
+
+  loadingHdImage.value = false
+}
+
+// Load and show video
+async function showVideoPlayer() {
+  if (!enlargedEvent.value) return
+
+  currentMediaType.value = 'video'
+  showVideo.value = true
+  hdImageUrl.value = null
+  hdImageError.value = null
+
+  await loadVideo(enlargedEvent.value.actorId, enlargedEvent.value.startTimestamp)
 }
 
 // Handle keyboard events for accessibility
@@ -546,56 +615,147 @@ watch([timeRange, selectedEventTypes], () => {
 
       <!-- Enlarged image lightbox -->
       <div
-        v-if="enlargedEventId && enlargedImage"
+        v-if="enlargedEventId && (enlargedImage || showVideo)"
         class="lightbox-overlay"
         @click.self="closeEnlargedImage"
         data-testid="lightbox-overlay"
       >
         <div class="lightbox-content">
-          <button
-            class="lightbox-close"
-            @click="closeEnlargedImage"
-            aria-label="Close enlarged image"
-            data-testid="lightbox-close"
-          >&times;</button>
-          <div class="lightbox-image-container">
-            <img :src="enlargedImage" :alt="enlargedEvent?.type || 'Event image'" class="lightbox-image" />
-            <!-- Bounding box overlay -->
-            <svg
-              v-if="enlargedBoundingBoxes.length > 0"
-              class="bounding-box-overlay"
-              viewBox="0 0 100 100"
-              preserveAspectRatio="none"
-              data-testid="bounding-box-overlay"
-            >
-              <rect
-                v-for="(box, index) in enlargedBoundingBoxes"
-                :key="index"
-                :x="box.x * NORMALIZED_TO_PERCENT"
-                :y="box.y * NORMALIZED_TO_PERCENT"
-                :width="box.width * NORMALIZED_TO_PERCENT"
-                :height="box.height * NORMALIZED_TO_PERCENT"
-                class="bounding-box"
-                data-testid="bounding-box"
-              />
-            </svg>
-            <!-- Bounding box labels -->
-            <div
-              v-for="(box, index) in enlargedBoundingBoxes"
-              :key="'label-' + index"
-              class="bounding-box-label"
-              :style="{
-                left: (box.x * NORMALIZED_TO_PERCENT) + '%',
-                top: (box.y * NORMALIZED_TO_PERCENT) + '%'
-              }"
-              data-testid="bounding-box-label"
-            >
-              {{ box.label || 'Object' }}
-              <span v-if="box.confidence" class="confidence">
-                {{ Math.round(box.confidence * 100) }}%
-              </span>
+          <!-- Header with buttons -->
+          <div class="lightbox-header">
+            <div class="lightbox-buttons">
+              <button
+                class="media-button"
+                :class="{ active: currentMediaType === 'preview' }"
+                @click="showPreview"
+              >
+                Preview
+              </button>
+              <button
+                class="media-button media-button-hd"
+                :class="{ active: currentMediaType === 'hd' }"
+                @click="showHdImage"
+              >
+                HD Image
+              </button>
+              <button
+                class="media-button media-button-video"
+                :class="{ active: currentMediaType === 'video' }"
+                @click="showVideoPlayer"
+              >
+                Video
+              </button>
             </div>
+            <button
+              class="lightbox-close"
+              @click="closeEnlargedImage"
+              aria-label="Close enlarged image"
+              data-testid="lightbox-close"
+            >&times;</button>
           </div>
+
+          <!-- Video mode -->
+          <template v-if="showVideo">
+            <div v-if="loadingVideo" class="lightbox-loading">Loading video...</div>
+            <div v-else-if="videoError" class="lightbox-error">{{ videoError }}</div>
+            <video
+              v-else-if="videoUrl"
+              :ref="(el) => hlsPlayer.videoRef.value = el as HTMLVideoElement | null"
+              class="lightbox-video"
+              controls
+              autoplay
+              muted
+              playsinline
+            />
+          </template>
+
+          <!-- HD Image mode -->
+          <template v-else-if="currentMediaType === 'hd'">
+            <div v-if="loadingHdImage" class="lightbox-loading">Loading HD image...</div>
+            <div v-else-if="hdImageError" class="lightbox-error">{{ hdImageError }}</div>
+            <div v-else-if="hdImageUrl" class="lightbox-image-container">
+              <img :src="hdImageUrl" :alt="enlargedEvent?.type || 'Event image'" class="lightbox-image" />
+              <!-- Bounding box overlay for HD -->
+              <svg
+                v-if="enlargedBoundingBoxes.length > 0"
+                class="bounding-box-overlay"
+                viewBox="0 0 100 100"
+                preserveAspectRatio="none"
+                data-testid="bounding-box-overlay"
+              >
+                <rect
+                  v-for="(box, index) in enlargedBoundingBoxes"
+                  :key="index"
+                  :x="box.x * NORMALIZED_TO_PERCENT"
+                  :y="box.y * NORMALIZED_TO_PERCENT"
+                  :width="box.width * NORMALIZED_TO_PERCENT"
+                  :height="box.height * NORMALIZED_TO_PERCENT"
+                  class="bounding-box"
+                  data-testid="bounding-box"
+                />
+              </svg>
+              <!-- Bounding box labels for HD -->
+              <div
+                v-for="(box, index) in enlargedBoundingBoxes"
+                :key="'label-' + index"
+                class="bounding-box-label"
+                :style="{
+                  left: (box.x * NORMALIZED_TO_PERCENT) + '%',
+                  top: (box.y * NORMALIZED_TO_PERCENT) + '%'
+                }"
+                data-testid="bounding-box-label"
+              >
+                {{ box.label || 'Object' }}
+                <span v-if="box.confidence" class="confidence">
+                  {{ Math.round(box.confidence * 100) }}%
+                </span>
+              </div>
+            </div>
+          </template>
+
+          <!-- Preview mode (default) -->
+          <template v-else>
+            <div v-if="!enlargedImage" class="lightbox-loading">Loading preview...</div>
+            <div v-else class="lightbox-image-container">
+              <img :src="enlargedImage" :alt="enlargedEvent?.type || 'Event image'" class="lightbox-image" />
+              <!-- Bounding box overlay -->
+              <svg
+                v-if="enlargedBoundingBoxes.length > 0"
+                class="bounding-box-overlay"
+                viewBox="0 0 100 100"
+                preserveAspectRatio="none"
+                data-testid="bounding-box-overlay"
+              >
+                <rect
+                  v-for="(box, index) in enlargedBoundingBoxes"
+                  :key="index"
+                  :x="box.x * NORMALIZED_TO_PERCENT"
+                  :y="box.y * NORMALIZED_TO_PERCENT"
+                  :width="box.width * NORMALIZED_TO_PERCENT"
+                  :height="box.height * NORMALIZED_TO_PERCENT"
+                  class="bounding-box"
+                  data-testid="bounding-box"
+                />
+              </svg>
+              <!-- Bounding box labels -->
+              <div
+                v-for="(box, index) in enlargedBoundingBoxes"
+                :key="'label-' + index"
+                class="bounding-box-label"
+                :style="{
+                  left: (box.x * NORMALIZED_TO_PERCENT) + '%',
+                  top: (box.y * NORMALIZED_TO_PERCENT) + '%'
+                }"
+                data-testid="bounding-box-label"
+              >
+                {{ box.label || 'Object' }}
+                <span v-if="box.confidence" class="confidence">
+                  {{ Math.round(box.confidence * 100) }}%
+                </span>
+              </div>
+            </div>
+          </template>
+
           <div v-if="enlargedEvent" class="lightbox-info">
             <div class="lightbox-event-line">
               <span class="lightbox-camera-info">{{ camera.name }} ({{ camera.id }})</span>
@@ -887,10 +1047,50 @@ watch([timeRange, selectedEventTypes], () => {
   align-items: center;
 }
 
+.lightbox-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  width: 100%;
+  margin-bottom: 15px;
+}
+
+.lightbox-buttons {
+  display: flex;
+  gap: 10px;
+}
+
+.media-button {
+  padding: 8px 16px;
+  background: #42b883;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 0.9rem;
+  font-weight: 500;
+  opacity: 0.7;
+  transition: opacity 0.2s, background 0.2s;
+}
+
+.media-button:hover {
+  opacity: 1;
+}
+
+.media-button.active {
+  opacity: 1;
+  box-shadow: 0 0 0 2px white;
+}
+
+.media-button-hd {
+  background: #3b82f6;
+}
+
+.media-button-video {
+  background: #9b59b6;
+}
+
 .lightbox-close {
-  position: absolute;
-  top: -40px;
-  right: -10px;
   background: none;
   border: none;
   color: white;
@@ -898,13 +1098,35 @@ watch([timeRange, selectedEventTypes], () => {
   cursor: pointer;
   padding: 5px 10px;
   line-height: 1;
-  z-index: 2001;
 }
 
 .lightbox-close:hover {
   color: #ccc;
 }
 
+.lightbox-loading,
+.lightbox-error {
+  color: white;
+  font-size: 1.1rem;
+  padding: 40px;
+  min-height: 200px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.lightbox-error {
+  color: #ff6b6b;
+}
+
+.lightbox-video {
+  max-width: 90vw;
+  max-height: 70vh;
+  width: 100%;
+  background: #000;
+  border-radius: 4px;
+}
+
 .lightbox-info {
   margin-top: 15px;
   text-align: center;

package/examples/vue-events/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()
+}