een-api-toolkit 0.3.14 → 0.3.16

package/docs/AI-CONTEXT.md

@@ -1,6 +1,6 @@
 # EEN API Toolkit - AI Reference
 
-> **Version:** 0.3.14
+> **Version:** 0.3.16
 >
 > This file is optimized for AI assistants. It contains all API signatures,
 > types, and usage patterns in a single, parseable document.
@@ -10,9 +10,10 @@
 
 > **Working Examples:** The installed package includes complete Vue 3 example applications
 > at `./node_modules/een-api-toolkit/examples/`. These demonstrate OAuth authentication,
-> user management, camera listing, live/recorded media, video feeds, and events.
+> user management, camera listing, live/recorded media, video feeds, events, and metrics.
 > For Live Main Video streaming, see `vue-feeds/src/views/Feeds.vue`.
 > For Events API with thumbnails, see `vue-events/src/components/EventsModal.vue`.
+> For Event Metrics with Chart.js visualization, see `vue-alerts-metrics/src/components/MetricsChart.vue`.
 
 ---
 
@@ -212,6 +213,7 @@ Complete Vue 3 applications demonstrating toolkit features:
 | [vue-media](../examples/vue-media/) | Live and recorded image viewing | `src/views/LiveCamera.vue`, `RecordedImage.vue`, `HLS.vue` |
 | [vue-feeds](../examples/vue-feeds/) | Live video streaming (preview and main) | `src/views/Feeds.vue` |
 | [vue-events](../examples/vue-events/) | Events with bounding box overlays | `src/components/EventsModal.vue` |
+| [vue-alerts-metrics](../examples/vue-alerts-metrics/) | Event metrics, alerts, and notifications | `src/components/MetricsChart.vue`, `AlertsList.vue` |
 
 ### Configuration
 
@@ -270,6 +272,33 @@ Complete Vue 3 applications demonstrating toolkit features:
 | `listEventTypes(params?)` | List all available event types | `Result<PaginatedResult<EventType>>` |
 | `listEventFieldValues(params)` | Get available event types for a device | `Result<EventFieldValues>` |
 
+### Event Metrics Functions
+
+| Function | Purpose | Returns |
+|----------|---------|---------|
+| `getEventMetrics(params)` | Get event count metrics over time | `Result<EventMetric[]>` |
+
+### Alerts Functions
+
+| Function | Purpose | Returns |
+|----------|---------|---------|
+| `listAlerts(params?)` | List alerts with filters | `Result<PaginatedResult<Alert>>` |
+| `getAlert(id, params?)` | Get a specific alert by ID | `Result<Alert>` |
+| `listAlertTypes(params?)` | List all available alert types | `Result<PaginatedResult<AlertType>>` |
+
+### Notifications Functions
+
+| Function | Purpose | Returns |
+|----------|---------|---------|
+| `listNotifications(params?)` | List notifications with filters | `Result<PaginatedResult<Notification>>` |
+| `getNotification(id)` | Get a specific notification by ID | `Result<Notification>` |
+
+### Utility Functions
+
+| Function | Purpose | Returns |
+|----------|---------|---------|
+| `formatTimestamp(timestamp)` | Convert ISO timestamp from Z to +00:00 format (required by EEN API) | `string` |
+
 ---
 
 ## Core Types
@@ -741,6 +770,163 @@ interface ListEventFieldValuesParams {
 }
 ```
 
+### Event Metrics Types
+
+```typescript
+type MetricActorType = 'bridge' | 'camera' | 'speaker' | 'account' | 'user' | 'layout' | 'job'
+
+// Data point: [timestamp_ms, value]
+type MetricDataPoint = [number, number]
+
+interface EventMetric {
+  eventType: string
+  actorId: string
+  actorType: MetricActorType
+  target: string                 // e.g., 'count'
+  dataPoints: MetricDataPoint[]
+  [key: string]: unknown         // Additional properties
+}
+
+interface GetEventMetricsParams {
+  actor: string                  // Required: 'camera:{id}' format
+  eventType: string              // Required: e.g., 'een.motionDetectionEvent.v1'
+  timestamp__gte?: string        // Optional: defaults to 7 days ago
+  timestamp__lte?: string        // Optional: defaults to now
+  aggregateByMinutes?: number    // Optional: default 60, minimum 60
+}
+```
+
+### Alert Types
+
+```typescript
+interface AlertAction {
+  name: string
+  type: string
+  success: boolean
+  timestamp: string
+  status?: 'fired' | 'success' | 'partialSuccess' | 'silenced' | 'failed' | 'internalError'
+}
+
+interface Alert {
+  id: string
+  timestamp: string
+  createTimestamp: string
+  creatorId: string
+  alertType: string
+  alertName?: string
+  category?: string
+  serviceRuleId?: string
+  eventType?: string
+  actorId: string
+  actorType: string
+  actorAccountId: string
+  actorName?: string
+  ruleId?: string
+  eventId?: string
+  locationId?: string
+  locationName?: string
+  priority?: number              // 0-20
+  dataSchemas?: string[]
+  data?: Record<string, unknown>
+  actions?: Record<string, AlertAction>
+  description?: string
+}
+
+interface AlertType {
+  type: string
+  description: string
+}
+
+type AlertInclude = 'data' | 'actions' | 'dataSchemas' | 'description'
+type AlertSort = '+timestamp' | '-timestamp'
+type AlertActionStatus = 'fired' | 'success' | 'partialSuccess' | 'silenced' | 'failed' | 'internalError'
+
+interface ListAlertsParams {
+  pageSize?: number
+  pageToken?: string
+  timestamp__lte?: string
+  timestamp__gte?: string
+  creatorId?: string
+  alertType__in?: string[]
+  actorId__in?: string[]
+  actorType__in?: string[]
+  actorAccountId?: string
+  ruleId?: string
+  ruleId__in?: string[]
+  eventId?: string
+  locationId__in?: string[]
+  priority__gte?: number
+  priority__lte?: number
+  showInvalidAlerts?: boolean
+  alertActionId__in?: string[]
+  alertActionStatus__in?: AlertActionStatus[]
+  include?: AlertInclude[]
+  sort?: AlertSort[]
+  language?: string
+}
+
+interface GetAlertParams {
+  include?: AlertInclude[]
+}
+
+interface ListAlertTypesParams {
+  pageSize?: number
+  pageToken?: string
+}
+```
+
+### Notification Types
+
+```typescript
+type NotificationCategory = 'health' | 'video' | 'operational' | 'audit' | 'job' | 'security' | 'sharing'
+
+type NotificationStatus =
+  | 'pending' | 'bounced' | 'dropped' | 'deferred' | 'delivered' | 'sent'
+  | 'outsideUsersSchedule' | 'notificationsDisabled' | 'noNotificationActions'
+  | 'sendingFailed' | 'throttled' | 'unableToGetSettings'
+
+interface Notification {
+  id: string
+  timestamp: string
+  createTimestamp: string
+  sentTimestamp?: string
+  alertId?: string | null
+  alertType?: string
+  actorId: string
+  actorName?: string
+  actorType: string
+  actorAccountId: string
+  userId: string
+  accountId: string
+  read: boolean
+  status: NotificationStatus
+  category: NotificationCategory
+  description?: string
+  notificationActions: string[]
+  dataSchemas: string[]
+  data: Record<string, unknown>
+}
+
+interface ListNotificationsParams {
+  pageSize?: number
+  pageToken?: string
+  timestamp__lte?: string
+  timestamp__gte?: string
+  alertId?: string
+  alertType?: string
+  actorId?: string
+  actorType?: string
+  actorAccountId?: string
+  category?: NotificationCategory
+  userId?: string
+  read?: boolean
+  status?: NotificationStatus
+  includeV1Notifications?: boolean
+  sort?: ('+timestamp' | '-timestamp')[]
+  language?: string
+}
+```
+
 ---
 
 ## API Reference
@@ -1095,6 +1281,40 @@ console.log('Session URL:', data.url)
 
 ---
 
+## Utilities
+
+### formatTimestamp
+
+Converts ISO 8601 timestamps from `Z` (Zulu/UTC) format to `+00:00` format, as required by the EEN API.
+
+**Why this is needed:** JavaScript's `Date.toISOString()` returns timestamps with a `Z` suffix (e.g., `2025-01-15T22:30:00.000Z`), but the EEN API requires the `+00:00` format (e.g., `2025-01-15T22:30:00.000+00:00`).
+
+```typescript
+import { formatTimestamp } from 'een-api-toolkit'
+
+// Convert Z format to +00:00 format
+formatTimestamp('2025-01-15T22:30:00.000Z')
+// Returns: '2025-01-15T22:30:00.000+00:00'
+
+// Already in +00:00 format - returns unchanged
+formatTimestamp('2025-01-15T22:30:00.000+00:00')
+// Returns: '2025-01-15T22:30:00.000+00:00'
+
+// Common usage with Date objects
+const now = new Date()
+const apiTimestamp = formatTimestamp(now.toISOString())
+// Returns timestamp in EEN API format
+```
+
+**When to use:**
+- When displaying timestamps that match the exact format used in API calls (e.g., for debugging)
+- When making direct API calls outside of the toolkit
+- When building custom timestamp display components
+
+**Note:** The toolkit's API functions (`listAlerts`, `getEventMetrics`, `listNotifications`, `listEvents`, etc.) automatically apply `formatTimestamp` internally, so you don't need to pre-format timestamps when using these functions.
+
+---
+
 ## Live Video Streaming
 
 The EEN API Toolkit supports two methods for displaying live video from cameras:
@@ -1345,6 +1565,98 @@ video {
 
 ---
 
+## HLS Video Playback Troubleshooting
+
+For detailed troubleshooting, see the [HLS Video Troubleshooting Guide](./guides/HLS-VIDEO-TROUBLESHOOTING.md).
+
+### Overview
+
+HLS video playback from the EEN API requires:
+
+1. **Initialize media session** - `initMediaSession()`
+2. **Find recording intervals** - `listMedia()` with `include: ['hlsUrl']`
+3. **Extract HLS URL** - From interval containing target timestamp
+4. **Configure HLS.js with auth** - Bearer token in Authorization header
+
+### Key Requirements
+
+| Requirement | Details |
+|-------------|---------|
+| Feed Type | HLS only available for `main` feeds, not `preview` |
+| Timestamp Format | Use `formatTimestamp()` to convert `Z` to `+00:00` |
+| Authentication | HLS.js requires `xhr.setRequestHeader('Authorization', `Bearer ${token}`)` |
+| Recording Coverage | Target timestamp must fall within a recording interval |
+
+### Common Issues
+
+#### 401 Unauthorized
+
+**Cause:** Using `withCredentials: true` instead of Authorization header.
+
+```typescript
+// WRONG
+const hls = new Hls({
+  xhrSetup: (xhr) => { xhr.withCredentials = true }
+})
+
+// CORRECT
+import { useAuthStore } from 'een-api-toolkit'
+const authStore = useAuthStore()
+
+const hls = new Hls({
+  xhrSetup: (xhr) => {
+    xhr.setRequestHeader('Authorization', `Bearer ${authStore.token}`)
+  }
+})
+```
+
+#### No Video Available for Timestamp
+
+**Cause:** Search range too narrow or using wrong feed type.
+
+```typescript
+import { listMedia, formatTimestamp } from 'een-api-toolkit'
+
+const targetTime = new Date(alertTimestamp)
+const searchStart = new Date(targetTime.getTime() - 60 * 60 * 1000) // 1 hour before
+const searchEnd = new Date(targetTime.getTime() + 60 * 60 * 1000)   // 1 hour after
+
+const result = await listMedia({
+  deviceId: cameraId,
+  type: 'main',              // MUST be 'main' for HLS
+  mediaType: 'video',
+  startTimestamp: formatTimestamp(searchStart.toISOString()),
+  endTimestamp: formatTimestamp(searchEnd.toISOString()),
+  include: ['hlsUrl']        // MUST include 'hlsUrl'
+})
+
+// Find interval containing target timestamp
+const intervals = result.data?.results ?? []
+const targetTimeMs = targetTime.getTime()
+
+const matchingInterval = intervals.find(i => {
+  if (!i.hlsUrl) return false
+  const start = new Date(i.startTimestamp).getTime()
+  const end = new Date(i.endTimestamp).getTime()
+  return targetTimeMs >= start && targetTimeMs <= end
+})
+```
+
+#### Timestamp Format Error
+
+**Cause:** Using `Z` suffix instead of `+00:00`.
+
+```typescript
+// WRONG
+const timestamp = new Date().toISOString()  // "2025-01-15T22:30:00.000Z"
+
+// CORRECT
+import { formatTimestamp } from 'een-api-toolkit'
+const timestamp = formatTimestamp(new Date().toISOString())  // "2025-01-15T22:30:00.000+00:00"
+```
+
+---
+
 ## Common Patterns
 
 ### Error Handling

package/examples/vue-alerts-metrics/README.md

@@ -0,0 +1,136 @@
+# vue-alerts-metrics
+
+A Vue 3 example application demonstrating the Event Metrics, Alerts, and Notifications APIs from the `een-api-toolkit`.
+
+## Status
+
+| Feature | Status |
+|---------|--------|
+| Event Metrics | Supported |
+| Alerts | Work in Progress |
+| Notifications | Work in Progress |
+
+> **Note:** The Event Metrics feature is fully functional. Alerts and Notifications UI components are present but the underlying API integration may have limitations.
+
+## Features
+
+- **OAuth Authentication** - Secure login via Eagle Eye Networks
+- **Camera Selection** - Browse and select cameras from your account
+- **Time Range Selection** - View data for 1h, 6h, 24h, or 7 days
+- **Event Metrics Chart** - Line chart visualization of event counts over time
+- **Event Type Selection** - Filter metrics by specific event types
+- **Alert Type Filtering** - Filter alerts by type (work in progress)
+- **Notifications List** - View notifications for selected camera (work in progress)
+
+## Prerequisites
+
+1. **OAuth Proxy** - Running instance of [een-oauth-proxy](https://github.com/klaushofrichter/een-oauth-proxy)
+2. **EEN Account** - Valid Eagle Eye Networks account with API access
+3. **Node.js** - Version 20 or higher
+
+## Setup
+
+1. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+2. Create a `.env` file (or copy from parent):
+   ```bash
+   VITE_PROXY_URL=http://127.0.0.1:8787
+   VITE_EEN_CLIENT_ID=your-client-id
+   VITE_REDIRECT_URI=http://127.0.0.1:3333
+   ```
+
+3. Start the development server:
+   ```bash
+   npm run dev
+   ```
+
+4. Open http://127.0.0.1:3333 in your browser
+
+## Usage
+
+1. Click **Login** to authenticate with Eagle Eye Networks
+2. After login, you'll be redirected to the Dashboard
+3. Select a **Camera** from the dropdown
+4. Select an **Event Type** to view metrics in the chart
+5. Use the **Time Range** buttons to change the data window
+6. View Alerts and Notifications in the panels below (work in progress)
+
+## Project Structure
+
+```
+vue-alerts-metrics/
+├── src/
+│   ├── components/
+│   │   ├── AlertsList.vue         # Alerts display with type filter
+│   │   ├── CameraSelector.vue     # Camera dropdown
+│   │   ├── MetricsChart.vue       # Chart.js line chart
+│   │   ├── NotificationsList.vue  # Notifications display
+│   │   └── TimeRangeSelector.vue  # Time range buttons
+│   ├── views/
+│   │   ├── Callback.vue           # OAuth callback handler
+│   │   ├── Dashboard.vue          # Main dashboard view
+│   │   ├── Home.vue               # Landing page
+│   │   ├── Login.vue              # Login page
+│   │   └── Logout.vue             # Logout handler
+│   ├── router/
+│   │   └── index.ts               # Vue Router config
+│   ├── App.vue                    # Root component
+│   └── main.ts                    # App entry point
+├── e2e/
+│   ├── app.spec.ts                # Basic navigation tests
+│   └── auth.spec.ts               # OAuth flow tests
+├── playwright.config.ts           # Playwright configuration
+└── package.json
+```
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start development server |
+| `npm run build` | Build for production |
+| `npm run preview` | Preview production build |
+| `npm run test:e2e` | Run Playwright E2E tests |
+
+## E2E Testing
+
+The example includes Playwright E2E tests that verify:
+- Basic navigation and page rendering
+- OAuth login flow
+- Dashboard functionality
+- Camera and event type selection
+- Alerts and notifications loading
+
+To run E2E tests:
+```bash
+# Ensure OAuth proxy is running
+npm run test:e2e
+```
+
+Required environment variables for E2E tests:
+- `TEST_USER` - Test account email
+- `TEST_PASSWORD` - Test account password
+
+## API Functions Used
+
+This example demonstrates the following `een-api-toolkit` functions:
+
+- `initEenToolkit()` - Initialize the toolkit
+- `getAuthUrl()` - Get OAuth authorization URL
+- `handleAuthCallback()` - Handle OAuth callback
+- `useAuthStore()` - Access authentication state
+- `getCameras()` - List available cameras
+- `listEventFieldValues()` - Get available event types for a camera
+- `getEventMetrics()` - Fetch event metrics time-series data
+- `listAlertTypes()` - Get available alert types
+- `listAlerts()` - Fetch alerts for a camera
+- `listNotifications()` - Fetch notifications for a camera
+
+## Known Limitations
+
+- **Event Metrics aggregation** - The EEN API requires a minimum 60-minute aggregation period. Shorter time ranges (1h, 6h) will have fewer data points.
+- **Alerts API** - Alert type filtering is functional, but some alert types may not have data.
+- **Notifications API** - Notification display is implemented but may have limited data depending on account configuration.

package/examples/vue-alerts-metrics/e2e/app.spec.ts

@@ -0,0 +1,74 @@
+import { test, expect } from '@playwright/test'
+
+test.describe('Alerts & Metrics Example App', () => {
+  test('should display the home page', async ({ page }) => {
+    await page.goto('/')
+
+    // Check title
+    await expect(page).toHaveTitle('EEN Alerts & Metrics Example')
+
+    // Check header
+    await expect(page.locator('h1')).toContainText('EEN Alerts & Metrics Example')
+
+    // Check navigation links
+    await expect(page.locator('nav')).toContainText('Home')
+    await expect(page.locator('nav')).toContainText('Login')
+  })
+
+  test('should show welcome message on home page', async ({ page }) => {
+    await page.goto('/')
+
+    await expect(page.locator('h2')).toContainText('Welcome to the EEN Alerts & Metrics Example')
+  })
+
+  test('should display login prompt when not authenticated', async ({ page }) => {
+    await page.goto('/')
+
+    // Should show login prompt
+    await expect(page.locator('.login-prompt')).toBeVisible()
+    await expect(page.locator('.login-prompt')).toContainText('Please log in to view alerts, notifications, and metrics')
+  })
+
+  test('should navigate to login page', async ({ page }) => {
+    await page.goto('/')
+
+    // Click login in nav
+    await page.locator('nav a:has-text("Login")').click()
+
+    // Should be on login page
+    await expect(page.locator('h2')).toContainText('Login')
+    await expect(page.locator('button')).toContainText('Login with Eagle Eye Networks')
+  })
+
+  test('should redirect to login when accessing dashboard without auth', async ({ page }) => {
+    // Try to access dashboard directly
+    await page.goto('/dashboard')
+
+    // Should be redirected to login
+    await expect(page.locator('h2')).toContainText('Login')
+  })
+
+  test('should show about section on home page', async ({ page }) => {
+    await page.goto('/')
+
+    // Check the about section
+    await expect(page.locator('.description h3')).toContainText('About This Example')
+    await expect(page.locator('.description')).toContainText('getEventMetrics')
+    await expect(page.locator('.description')).toContainText('listAlerts')
+    await expect(page.locator('.description')).toContainText('listNotifications')
+  })
+
+  test('should have correct navigation structure', async ({ page }) => {
+    await page.goto('/')
+
+    // Check all expected nav links for unauthenticated state
+    const navLinks = page.locator('nav a')
+    await expect(navLinks).toHaveCount(2) // Home, Login
+
+    // Verify Home link
+    await expect(navLinks.nth(0)).toHaveAttribute('href', '/')
+
+    // Verify Login link
+    await expect(navLinks.nth(1)).toHaveAttribute('href', '/login')
+  })
+})