een-api-toolkit 0.3.15 → 0.3.20

package/examples/vue-alerts-metrics/src/components/TimeRangeSelector.vue

@@ -1,36 +1,157 @@
 <script setup lang="ts">
-defineProps<{
+import { ref, computed } from 'vue'
+import { formatTimestamp } from 'een-api-toolkit'
+
+const props = defineProps<{
   selected: string
 }>()
 
 const emit = defineEmits<{
   change: [range: string]
+  'update:aggregateMinutes': [minutes: number | undefined]
 }>()
 
 const ranges = [
+  { value: 'none', label: 'None' },
   { value: '1h', label: '1 Hour' },
   { value: '6h', label: '6 Hours' },
   { value: '24h', label: '24 Hours' },
   { value: '7d', label: '7 Days' }
 ]
 
+const aggregateOptions = [
+  { value: '', label: 'None', minutes: undefined },
+  { value: '60', label: '60 min', minutes: 60 },
+  { value: '360', label: '6h', minutes: 360 },
+  { value: '1440', label: '24h', minutes: 1440 }
+]
+
+const selectedAggregate = ref('')
+const showApiFormat = ref(false)
+const startCopied = ref(false)
+const endCopied = ref(false)
+
+function getTimeRangeMs(range: string): number {
+  switch (range) {
+    case '1h': return 60 * 60 * 1000
+    case '6h': return 6 * 60 * 60 * 1000
+    case '24h': return 24 * 60 * 60 * 1000
+    case '7d': return 7 * 24 * 60 * 60 * 1000
+    default: return 24 * 60 * 60 * 1000
+  }
+}
+
+const timeRange = computed(() => {
+  const now = new Date()
+  const rangeMs = getTimeRangeMs(props.selected)
+  const startTime = new Date(now.getTime() - rangeMs)
+  return { start: startTime, end: now }
+})
+
+// Always compute API format timestamps for copying
+const apiStartTimestamp = computed(() => {
+  return formatTimestamp(timeRange.value.start.toISOString())
+})
+
+const apiEndTimestamp = computed(() => {
+  return formatTimestamp(timeRange.value.end.toISOString())
+})
+
+const formattedStart = computed(() => {
+  if (showApiFormat.value) {
+    return apiStartTimestamp.value
+  }
+  return timeRange.value.start.toLocaleString()
+})
+
+const formattedEnd = computed(() => {
+  if (showApiFormat.value) {
+    return apiEndTimestamp.value
+  }
+  return timeRange.value.end.toLocaleString()
+})
+
 function handleClick(range: string) {
   emit('change', range)
 }
+
+function toggleFormat() {
+  showApiFormat.value = !showApiFormat.value
+}
+
+function handleAggregateChange() {
+  const option = aggregateOptions.find(o => o.value === selectedAggregate.value)
+  emit('update:aggregateMinutes', option?.minutes)
+}
+
+async function copyStartTimestamp() {
+  await navigator.clipboard.writeText(apiStartTimestamp.value)
+  startCopied.value = true
+  setTimeout(() => {
+    startCopied.value = false
+  }, 500)
+}
+
+async function copyEndTimestamp() {
+  await navigator.clipboard.writeText(apiEndTimestamp.value)
+  endCopied.value = true
+  setTimeout(() => {
+    endCopied.value = false
+  }, 500)
+}
 </script>
 
 <template>
   <div class="time-range-selector">
-    <span class="label">Time Range:</span>
-    <div class="buttons">
+    <div class="selector-row">
+      <span class="label">Time Range:</span>
+      <div class="buttons">
+        <button
+          v-for="range in ranges"
+          :key="range.value"
+          :class="{ active: selected === range.value }"
+          @click="handleClick(range.value)"
+          :data-testid="`time-range-${range.value}`"
+        >
+          {{ range.label }}
+        </button>
+      </div>
+      <span class="label aggregate-label">Aggregate:</span>
+      <div class="buttons">
+        <button
+          v-for="option in aggregateOptions"
+          :key="option.value"
+          :class="{ active: selectedAggregate === option.value }"
+          @click="selectedAggregate = option.value; handleAggregateChange()"
+          :data-testid="`aggregate-${option.value || 'none'}`"
+        >
+          {{ option.label }}
+        </button>
+      </div>
+    </div>
+    <div v-if="selected !== 'none'" class="time-display">
+      <div class="timestamps">
+        <span class="time-label">From:</span>
+        <code
+          :class="{ copied: startCopied }"
+          @click="copyStartTimestamp"
+          data-testid="time-start"
+          title="Click to copy API format timestamp"
+        >{{ formattedStart }}</code>
+        <span class="time-label">To:</span>
+        <code
+          :class="{ copied: endCopied }"
+          @click="copyEndTimestamp"
+          data-testid="time-end"
+          title="Click to copy API format timestamp"
+        >{{ formattedEnd }}</code>
+      </div>
       <button
-        v-for="range in ranges"
-        :key="range.value"
-        :class="{ active: selected === range.value }"
-        @click="handleClick(range.value)"
-        :data-testid="`time-range-${range.value}`"
+        class="format-toggle"
+        @click="toggleFormat"
+        data-testid="format-toggle"
       >
-        {{ range.label }}
+        {{ showApiFormat ? 'Local Time' : 'API Format' }}
       </button>
     </div>
   </div>
@@ -38,6 +159,12 @@ function handleClick(range: string) {
 
 <style scoped>
 .time-range-selector {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.selector-row {
   display: flex;
   align-items: center;
   gap: 10px;
@@ -47,12 +174,16 @@ function handleClick(range: string) {
   font-weight: 500;
 }
 
+.aggregate-label {
+  margin-left: 20px;
+}
+
 .buttons {
   display: flex;
   gap: 5px;
 }
 
-button {
+.buttons button {
   padding: 8px 16px;
   border: 1px solid #ddd;
   background: #fff;
@@ -62,13 +193,67 @@ button {
   color: #333;
 }
 
-button:hover {
+.buttons button:hover {
   background: #f5f5f5;
 }
 
-button.active {
+.buttons button.active {
   background: #42b883;
   color: white;
   border-color: #42b883;
 }
+
+.time-display {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+
+.timestamps {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 0.85rem;
+  color: #666;
+}
+
+.time-label {
+  font-weight: 500;
+}
+
+.timestamps code {
+  background: #f5f5f5;
+  padding: 2px 6px;
+  border-radius: 3px;
+  font-family: monospace;
+  font-size: 0.8rem;
+  color: #333;
+  cursor: pointer;
+  transition: background-color 0.15s ease;
+}
+
+.timestamps code:hover {
+  background: #e0e0e0;
+}
+
+.timestamps code.copied {
+  background: #42b883;
+  color: white;
+}
+
+.format-toggle {
+  padding: 4px 10px;
+  border: 1px solid #ccc;
+  background: #fff;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 0.8rem;
+  color: #666;
+}
+
+.format-toggle:hover {
+  background: #f0f0f0;
+  border-color: #999;
+}
 </style>

package/examples/vue-alerts-metrics/src/composables/useHlsPlayer.ts

@@ -0,0 +1,285 @@
+import { ref, nextTick, onUnmounted, type Ref } from 'vue'
+import { listMedia, initMediaSession, formatTimestamp, useAuthStore } from 'een-api-toolkit'
+import Hls from 'hls.js'
+
+// 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)
+  }
+}
+
+// Cache media session to avoid redundant initialization calls
+let mediaSessionInitialized = false
+let mediaSessionPromise: Promise<boolean> | null = null
+
+/** 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.
+ */
+export function useHlsPlayer(): HlsPlayerReturn {
+  const authStore = useAuthStore()
+
+  // 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.
+   * Only calls the API once per session, subsequent calls return cached result.
+   */
+  async function ensureMediaSession(): Promise<boolean> {
+    // Return cached result if already initialized
+    if (mediaSessionInitialized) {
+      return true
+    }
+
+    // If initialization is in progress, wait for it
+    if (mediaSessionPromise) {
+      return mediaSessionPromise
+    }
+
+    // Start new initialization
+    mediaSessionPromise = (async () => {
+      const result = await initMediaSession()
+      if (result.error) {
+        videoError.value = `Media session error: ${result.error.message}`
+        mediaSessionPromise = null
+        return false
+      }
+      mediaSessionInitialized = true
+      return true
+    })()
+
+    return mediaSessionPromise
+  }
+
+  /**
+   * 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, () => {
+      videoRef.value?.play().catch(() => {
+        // Autoplay may be blocked, user can manually play
+      })
+    })
+
+    // Reset retry counter on successful load
+    networkRetryCount = 0
+
+    // 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
+
+    // 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: 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.
+ */
+export function resetMediaSessionCache() {
+  mediaSessionInitialized = false
+  mediaSessionPromise = null
+}

package/examples/vue-alerts-metrics/src/views/Dashboard.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { ref, watch } from 'vue'
+import { ref, watch, computed } from 'vue'
 import type { Camera } from 'een-api-toolkit'
 import CameraSelector from '../components/CameraSelector.vue'
 import TimeRangeSelector from '../components/TimeRangeSelector.vue'
@@ -8,16 +8,26 @@ import AlertsList from '../components/AlertsList.vue'
 import NotificationsList from '../components/NotificationsList.vue'
 
 const selectedCamera = ref<Camera | null>(null)
-const selectedTimeRange = ref('24h')
+const selectedTimeRange = ref('none')
+const selectedAggregateMinutes = ref<number | undefined>(undefined)
+const cameraListLoaded = ref(false)
 
-function handleCameraSelect(camera: Camera) {
+// Track if a specific camera is selected (not "All Cameras")
+const hasSpecificCamera = computed(() => selectedCamera.value !== null)
+
+function handleCameraSelect(camera: Camera | null) {
   selectedCamera.value = camera
+  cameraListLoaded.value = true
 }
 
 function handleTimeRangeChange(range: string) {
   selectedTimeRange.value = range
 }
 
+function handleAggregateChange(minutes: number | undefined) {
+  selectedAggregateMinutes.value = minutes
+}
+
 // Reset lists when camera changes
 watch(selectedCamera, () => {
   // Lists will reset automatically through their props
@@ -36,20 +46,26 @@ watch(selectedCamera, () => {
       <TimeRangeSelector
         :selected="selectedTimeRange"
         @change="handleTimeRangeChange"
+        @update:aggregate-minutes="handleAggregateChange"
         data-testid="time-range-selector"
       />
     </div>
 
-    <div v-if="!selectedCamera" class="no-camera-selected">
-      <p>Select a camera to view its metrics, alerts, and notifications.</p>
+    <div v-if="!cameraListLoaded" class="no-camera-selected">
+      <p>Loading cameras...</p>
     </div>
 
     <div v-else class="dashboard-content">
       <section class="metrics-section">
         <h3>Event Metrics</h3>
+        <div v-if="!hasSpecificCamera" class="select-camera-message">
+          <p>Select a specific camera to view event metrics.</p>
+        </div>
         <MetricsChart
-          :camera="selectedCamera"
+          v-else
+          :camera="selectedCamera!"
           :time-range="selectedTimeRange"
+          :aggregate-minutes="selectedAggregateMinutes"
         />
       </section>
 
@@ -86,10 +102,9 @@ h2 {
 
 .controls {
   display: flex;
-  gap: 20px;
+  flex-direction: column;
+  gap: 15px;
   margin-bottom: 20px;
-  align-items: flex-start;
-  flex-wrap: wrap;
 }
 
 .no-camera-selected {
@@ -118,6 +133,13 @@ h2 {
   color: #333;
 }
 
+.select-camera-message {
+  text-align: center;
+  padding: 40px;
+  color: #666;
+  font-style: italic;
+}
+
 .lists-container {
   display: grid;
   grid-template-columns: 1fr 1fr;