een-api-toolkit 0.3.16 → 0.3.20

package/docs/AI-CONTEXT.md

@@ -1,6 +1,6 @@
 # EEN API Toolkit - AI Reference
 
-> **Version:** 0.3.16
+> **Version:** 0.3.20
 >
 > This file is optimized for AI assistants. It contains all API signatures,
 > types, and usage patterns in a single, parseable document.
@@ -214,6 +214,7 @@ Complete Vue 3 applications demonstrating toolkit features:
 | [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` |
+| [vue-event-subscriptions](../examples/vue-event-subscriptions/) | Real-time event streaming with SSE | `src/views/Subscriptions.vue`, `LiveEvents.vue` |
 
 ### Configuration
 
@@ -293,6 +294,16 @@ Complete Vue 3 applications demonstrating toolkit features:
 | `listNotifications(params?)` | List notifications with filters | `Result<PaginatedResult<Notification>>` |
 | `getNotification(id)` | Get a specific notification by ID | `Result<Notification>` |
 
+### EventSubscriptions Functions
+
+| Function | Purpose | Returns |
+|----------|---------|---------|
+| `listEventSubscriptions(params?)` | List all event subscriptions | `Result<PaginatedResult<EventSubscription>>` |
+| `getEventSubscription(id)` | Get a specific subscription by ID | `Result<EventSubscription>` |
+| `createEventSubscription(params)` | Create a new event subscription | `Result<EventSubscription>` |
+| `deleteEventSubscription(id)` | Delete an event subscription | `Result<void>` |
+| `connectToEventSubscription(sseUrl, options)` | Connect to SSE stream for real-time events | `Result<SSEConnection>` |
+
 ### Utility Functions
 
 | Function | Purpose | Returns |

package/examples/vue-event-subscriptions/.env.example

@@ -0,0 +1,15 @@
+# EEN API Toolkit Configuration
+# Copy this file to .env and fill in your values
+
+# OAuth Proxy URL (required)
+VITE_PROXY_URL=http://localhost:8787
+
+# EEN OAuth Client ID (required)
+VITE_EEN_CLIENT_ID=your_client_id_here
+
+# OAuth Redirect URI (required)
+# Must match the redirect URI configured in your EEN OAuth client
+VITE_REDIRECT_URI=http://127.0.0.1:3333
+
+# Enable debug logging (optional)
+VITE_DEBUG=true

package/examples/vue-event-subscriptions/README.md

@@ -0,0 +1,103 @@
+# Event Subscriptions Example
+
+This example demonstrates how to use the Event Subscriptions API from the EEN API Toolkit to create SSE subscriptions and receive real-time events from cameras.
+
+## Features
+
+- Create and delete event subscriptions with SSE delivery
+- View active subscriptions with pagination
+- Select cameras and event types for filtering
+- Connect to SSE streams for live events
+- Real-time event display with auto-scrolling
+
+## Prerequisites
+
+1. Node.js 20 LTS or later
+2. EEN OAuth credentials (client ID and secret)
+3. Running OAuth proxy server (from `../een-oauth-proxy`)
+
+## Setup
+
+1. Copy the environment file:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Edit `.env` with your configuration:
+   - `VITE_PROXY_URL`: URL of your OAuth proxy server
+   - `VITE_EEN_CLIENT_ID`: Your EEN OAuth client ID
+   - `VITE_REDIRECT_URI`: OAuth redirect URI (default: http://127.0.0.1:3333)
+   - `VITE_DEBUG`: Enable debug logging (optional)
+
+3. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+4. Start the OAuth proxy (in a separate terminal):
+   ```bash
+   cd ../een-oauth-proxy
+   npm run dev
+   ```
+
+5. Start the example app:
+   ```bash
+   npm run dev
+   ```
+
+6. Open http://127.0.0.1:3333 in your browser
+
+## Usage
+
+### Creating a Subscription
+
+1. Log in with your Eagle Eye Networks account
+2. Go to "Subscriptions" page
+3. Select one or more cameras from the dropdown
+4. Select one or more event types
+5. Click "Create Subscription"
+
+### Viewing Live Events
+
+1. Go to "Live Events" page
+2. Select a subscription from the dropdown
+3. Click "Connect"
+4. Events will appear in real-time as they occur
+5. Click "Disconnect" to stop receiving events
+
+## API Functions Used
+
+- `listEventSubscriptions()` - List all subscriptions
+- `getEventSubscription(id)` - Get a specific subscription
+- `createEventSubscription(params)` - Create a new subscription
+- `deleteEventSubscription(id)` - Delete a subscription
+- `connectToEventSubscription(sseUrl, options)` - Connect to SSE stream
+- `getCameras()` - List cameras for filter selection
+- `listEventTypes()` - List event types for filter selection
+
+## Event Subscription Lifecycle
+
+SSE subscriptions are **temporary** by default:
+- Automatically created with a time-to-live (TTL)
+- Deleted when no client is connected after TTL expires
+- Can be manually deleted at any time
+
+## Troubleshooting
+
+### No events appearing
+
+- Ensure the camera has activity (motion, etc.)
+- Check that the subscription has the correct event types
+- Verify the SSE connection status shows "connected"
+
+### Connection errors
+
+- Verify the OAuth proxy is running
+- Check that your token is valid (re-login if needed)
+- Ensure the subscription still exists (may have expired)
+
+### Cannot create subscription
+
+- Ensure you have cameras in your account
+- Check that event types are loaded
+- Verify your account has permission to create subscriptions

package/examples/vue-event-subscriptions/e2e/app.spec.ts

@@ -0,0 +1,71 @@
+import { test, expect } from '@playwright/test'
+
+test.describe('Event Subscriptions Example - App', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/')
+  })
+
+  test('app loads with correct title', async ({ page }) => {
+    await expect(page).toHaveTitle(/Event Subscriptions/)
+  })
+
+  test('header displays app name', async ({ page }) => {
+    await expect(page.locator('[data-testid="app-title"]')).toHaveText('EEN Event Subscriptions')
+  })
+
+  test('navigation shows Home and Login links when not authenticated', async ({ page }) => {
+    // Home link should be visible
+    await expect(page.locator('[data-testid="nav-home"]')).toBeVisible()
+
+    // Login link should be visible (not authenticated)
+    await expect(page.locator('[data-testid="nav-login"]')).toBeVisible()
+
+    // Subscriptions, Live, and Logout should NOT be visible (requires auth)
+    await expect(page.locator('[data-testid="nav-subscriptions"]')).not.toBeVisible()
+    await expect(page.locator('[data-testid="nav-live"]')).not.toBeVisible()
+    await expect(page.locator('[data-testid="nav-logout"]')).not.toBeVisible()
+  })
+
+  test('home page shows not logged in message', async ({ page }) => {
+    await expect(page.locator('[data-testid="not-authenticated"]')).toBeVisible()
+    await expect(page.locator('[data-testid="not-authenticated-message"]')).toBeVisible()
+    await expect(page.locator('[data-testid="login-button"]')).toBeVisible()
+  })
+
+  test('login page displays login button', async ({ page }) => {
+    await page.goto('/login')
+
+    await expect(page.locator('[data-testid="login-title"]')).toHaveText('Login')
+    await expect(page.locator('[data-testid="login-button"]')).toBeVisible()
+  })
+
+  test('protected route (subscriptions) redirects to login', async ({ page }) => {
+    await page.goto('/subscriptions')
+
+    // Should be redirected to login page
+    await page.waitForURL('/login')
+    await expect(page).toHaveURL('/login')
+    await expect(page.locator('[data-testid="login-title"]')).toHaveText('Login')
+  })
+
+  test('protected route (live) redirects to login', async ({ page }) => {
+    await page.goto('/live')
+
+    // Should be redirected to login page
+    await page.waitForURL('/login')
+    await expect(page).toHaveURL('/login')
+    await expect(page.locator('[data-testid="login-title"]')).toHaveText('Login')
+  })
+
+  test('navigation between pages works', async ({ page }) => {
+    // Click Login link
+    await page.click('[data-testid="nav-login"]')
+    await page.waitForURL('/login')
+    await expect(page).toHaveURL('/login')
+
+    // Click Home link
+    await page.click('[data-testid="nav-home"]')
+    await page.waitForURL('/')
+    await expect(page).toHaveURL('/')
+  })
+})

package/examples/vue-event-subscriptions/e2e/auth.spec.ts

@@ -0,0 +1,290 @@
+import { test, expect, Page } from '@playwright/test'
+import { baseURL } from '../playwright.config'
+
+/**
+ * E2E tests for the Event Subscriptions Example
+ *
+ * Tests the OAuth login flow and event subscription functionality:
+ * 1. Click login button in the example app
+ * 2. Enter credentials on EEN OAuth page
+ * 3. Complete the OAuth callback
+ * 4. Verify authenticated state
+ * 5. Test event subscription CRUD operations
+ * 6. Test SSE connection for live events
+ *
+ * Required environment variables:
+ * - VITE_PROXY_URL: OAuth proxy URL (e.g., http://127.0.0.1:8787)
+ * - VITE_EEN_CLIENT_ID: EEN OAuth client ID
+ * - TEST_USER: Test user email
+ * - TEST_PASSWORD: Test user password
+ */
+
+// Timeout constants for consistent behavior
+const TIMEOUTS = {
+  OAUTH_REDIRECT: 30000,   // OAuth redirects can be slow on first load
+  ELEMENT_VISIBLE: 15000,  // Wait for OAuth page elements to render
+  PASSWORD_VISIBLE: 10000, // Password field appears after email validation
+  AUTH_COMPLETE: 30000,    // Full OAuth flow completion
+  UI_UPDATE: 10000,        // UI state updates after auth changes
+  PROXY_CHECK: 5000,       // Quick check if proxy is running
+  SSE_CONNECTION: 15000,   // SSE connection establishment
+  DATA_LOAD: 15000         // Data loading (cameras, event types, subscriptions)
+} as const
+
+const TEST_USER = process.env.TEST_USER
+const TEST_PASSWORD = process.env.TEST_PASSWORD
+const PROXY_URL = process.env.VITE_PROXY_URL
+
+/**
+ * Checks if the OAuth proxy is accessible.
+ */
+async function isProxyAccessible(): Promise<boolean> {
+  if (!PROXY_URL) return false
+  const controller = new AbortController()
+  const timeoutId = setTimeout(() => controller.abort(), TIMEOUTS.PROXY_CHECK)
+
+  try {
+    const response = await fetch(PROXY_URL, {
+      method: 'HEAD',
+      signal: controller.signal
+    })
+    return response.ok || response.status === 404
+  } catch {
+    return false
+  } finally {
+    clearTimeout(timeoutId)
+  }
+}
+
+/**
+ * Performs OAuth login flow through the UI.
+ */
+async function performLogin(page: Page, username: string, password: string): Promise<void> {
+  await page.goto('/')
+
+  // Click login button and wait for OAuth redirect
+  await Promise.all([
+    page.waitForURL(/.*eagleeyenetworks.com.*/, { timeout: TIMEOUTS.OAUTH_REDIRECT }),
+    page.click('[data-testid="login-button"]')
+  ])
+
+  // Fill email
+  const emailInput = page.locator('#authentication--input__email')
+  await emailInput.waitFor({ state: 'visible', timeout: TIMEOUTS.ELEMENT_VISIBLE })
+  await emailInput.fill(username)
+
+  // Click next
+  await page.getByRole('button', { name: 'Next' }).click()
+
+  // Fill password
+  const passwordInput = page.locator('#authentication--input__password')
+  await passwordInput.waitFor({ state: 'visible', timeout: TIMEOUTS.PASSWORD_VISIBLE })
+  await passwordInput.fill(password)
+
+  // Click sign in
+  await page.locator('#next, button:has-text("Sign in")').first().click()
+
+  // Wait for redirect back to the app
+  const baseURLPattern = new RegExp(baseURL.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+  await page.waitForURL(baseURLPattern, { timeout: TIMEOUTS.AUTH_COMPLETE })
+}
+
+/**
+ * Clears browser storage to reset auth state.
+ */
+async function clearAuthState(page: Page): Promise<void> {
+  try {
+    const url = page.url()
+    if (url && url.startsWith('http')) {
+      await page.evaluate(() => {
+        try {
+          localStorage.clear()
+          sessionStorage.clear()
+        } catch {
+          // Ignore errors
+        }
+      })
+    }
+  } catch {
+    // Ignore errors
+  }
+}
+
+test.describe('Event Subscriptions Example', () => {
+  let proxyAccessible = false
+
+  function skipIfNoProxy() {
+    test.skip(!proxyAccessible, 'OAuth proxy not accessible')
+  }
+
+  function skipIfNoCredentials() {
+    test.skip(!TEST_USER || !TEST_PASSWORD, 'Test credentials not available')
+  }
+
+  test.beforeAll(async () => {
+    proxyAccessible = await isProxyAccessible()
+    if (!proxyAccessible) {
+      console.log('OAuth proxy not accessible - OAuth tests will be skipped')
+    }
+  })
+
+  test.afterEach(async ({ page }) => {
+    await clearAuthState(page)
+  })
+
+  test('shows login button when not authenticated', async ({ page }) => {
+    await page.goto('/')
+    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()
+  })
+
+  test('login button redirects to OAuth page', async ({ page }) => {
+    skipIfNoProxy()
+    skipIfNoCredentials()
+
+    await page.goto('/')
+    await expect(page.locator('[data-testid="login-button"]')).toBeVisible()
+    await expect(page.locator('[data-testid="login-button"]')).toBeEnabled()
+
+    // Click login and verify redirect to OAuth page
+    await Promise.all([
+      page.waitForURL(/.*eagleeyenetworks.com.*/, { timeout: TIMEOUTS.OAUTH_REDIRECT }),
+      page.click('[data-testid="login-button"]')
+    ])
+
+    // Verify we're on the OAuth page
+    const emailInput = page.locator('#authentication--input__email')
+    await expect(emailInput).toBeVisible({ timeout: TIMEOUTS.ELEMENT_VISIBLE })
+  })
+
+  test('complete OAuth login flow', async ({ page }) => {
+    skipIfNoProxy()
+    skipIfNoCredentials()
+
+    // Verify initially not authenticated
+    await page.goto('/')
+    await expect(page.locator('[data-testid="not-authenticated"]')).toBeVisible()
+
+    // Perform login
+    await performLogin(page, TEST_USER!, TEST_PASSWORD!)
+
+    // Verify authenticated state
+    await expect(page.locator('[data-testid="not-authenticated"]')).not.toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+    await expect(page.locator('[data-testid="nav-subscriptions"]')).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+    await expect(page.locator('[data-testid="nav-live"]')).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+    await expect(page.locator('[data-testid="nav-logout"]')).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+    await expect(page.locator('[data-testid="nav-login"]')).not.toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+  })
+
+  test('can view subscriptions page after login', async ({ page }) => {
+    skipIfNoProxy()
+    skipIfNoCredentials()
+
+    await performLogin(page, TEST_USER!, TEST_PASSWORD!)
+    await expect(page.locator('[data-testid="nav-subscriptions"]')).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+
+    // Navigate to subscriptions page
+    await page.click('[data-testid="nav-subscriptions"]')
+    await page.waitForURL('/subscriptions')
+
+    // Should see the create form and subscriptions table (or no-data message)
+    await expect(page.locator('[data-testid="camera-select"]')).toBeVisible({ timeout: TIMEOUTS.DATA_LOAD })
+    await expect(page.locator('[data-testid="event-type-select"]')).toBeVisible({ timeout: TIMEOUTS.DATA_LOAD })
+  })
+
+  test('can view live events page after login', async ({ page }) => {
+    skipIfNoProxy()
+    skipIfNoCredentials()
+
+    await performLogin(page, TEST_USER!, TEST_PASSWORD!)
+    await expect(page.locator('[data-testid="nav-live"]')).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+
+    // Navigate to live events page
+    await page.click('[data-testid="nav-live"]')
+    await page.waitForURL('/live')
+
+    // Should see the subscription selector and connect button
+    await expect(page.locator('[data-testid="subscription-select"]')).toBeVisible({ timeout: TIMEOUTS.DATA_LOAD })
+    await expect(page.locator('[data-testid="connect-button"]')).toBeVisible()
+    await expect(page.locator('[data-testid="connection-status"]')).toHaveText('disconnected')
+  })
+
+  test('can create and delete subscription', async ({ page }) => {
+    skipIfNoProxy()
+    skipIfNoCredentials()
+
+    await performLogin(page, TEST_USER!, TEST_PASSWORD!)
+
+    // Navigate to subscriptions page
+    await page.click('[data-testid="nav-subscriptions"]')
+    await page.waitForURL('/subscriptions')
+
+    // Wait for cameras and event types to load
+    await expect(page.locator('[data-testid="camera-select"] option')).not.toHaveCount(0, { timeout: TIMEOUTS.DATA_LOAD })
+    await expect(page.locator('[data-testid="event-type-select"] option')).not.toHaveCount(0, { timeout: TIMEOUTS.DATA_LOAD })
+
+    // Select a camera (first one)
+    const cameraSelect = page.locator('[data-testid="camera-select"]')
+    const cameraOptions = await cameraSelect.locator('option').all()
+    if (cameraOptions.length > 0) {
+      await cameraSelect.selectOption({ index: 0 })
+    }
+
+    // Select an event type (first one, typically motion detection)
+    const eventTypeSelect = page.locator('[data-testid="event-type-select"]')
+    const eventTypeOptions = await eventTypeSelect.locator('option').all()
+    if (eventTypeOptions.length > 0) {
+      await eventTypeSelect.selectOption({ index: 0 })
+    }
+
+    // Create subscription
+    const createButton = page.locator('[data-testid="create-subscription-button"]')
+    await expect(createButton).toBeEnabled()
+    await createButton.click()
+
+    // Wait for success message
+    await expect(page.locator('.success')).toBeVisible({ timeout: TIMEOUTS.DATA_LOAD })
+
+    // Verify subscription appears in table
+    await expect(page.locator('[data-testid="subscriptions-table"]')).toBeVisible({ timeout: TIMEOUTS.DATA_LOAD })
+
+    // Delete the first subscription
+    const deleteButton = page.locator('button.danger.small').first()
+    await expect(deleteButton).toBeVisible()
+
+    // Count subscriptions before deletion
+    const initialRowCount = await page.locator('[data-testid="subscriptions-table"] tbody tr').count()
+
+    // Accept the confirmation dialog
+    page.on('dialog', dialog => dialog.accept())
+    await deleteButton.click()
+
+    // Wait for deletion to complete by checking the row count decreases or delete button is no longer visible
+    // This is more reliable than a fixed timeout
+    if (initialRowCount > 1) {
+      // Wait for row count to decrease
+      await expect(page.locator('[data-testid="subscriptions-table"] tbody tr')).toHaveCount(initialRowCount - 1, { timeout: TIMEOUTS.DATA_LOAD })
+    } else {
+      // If only one subscription, wait for the table or empty state to appear
+      await expect(deleteButton).not.toBeVisible({ timeout: TIMEOUTS.DATA_LOAD })
+    }
+  })
+
+  test('can logout after login', async ({ page }) => {
+    skipIfNoProxy()
+    skipIfNoCredentials()
+
+    await performLogin(page, TEST_USER!, TEST_PASSWORD!)
+    await expect(page.locator('[data-testid="nav-logout"]')).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+
+    // Click logout
+    await page.click('[data-testid="nav-logout"]')
+
+    // Should show not authenticated - wait for redirect to app baseURL
+    const baseURLPattern = new RegExp(baseURL.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    await page.waitForURL(baseURLPattern)
+    await expect(page.locator('[data-testid="not-authenticated"]')).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+    await expect(page.locator('[data-testid="nav-login"]')).toBeVisible()
+  })
+})

package/examples/vue-event-subscriptions/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>EEN Event Subscriptions Example</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>