een-api-toolkit 0.3.38 → 0.3.46

package/docs/ai-reference/AI-DEVICES.md

@@ -1,6 +1,6 @@
 # Cameras & Bridges API - EEN API Toolkit
 
-> **Version:** 0.3.38
+> **Version:** 0.3.46
 >
 > Complete reference for camera and bridge management.
 > Load this document when working with devices.

package/docs/ai-reference/AI-EVENTS.md

@@ -1,6 +1,6 @@
 # Events, Alerts & Real-Time Streaming - EEN API Toolkit
 
-> **Version:** 0.3.38
+> **Version:** 0.3.46
 >
 > Complete reference for events, alerts, metrics, and SSE subscriptions.
 > Load this document when implementing event-driven features.
@@ -1632,7 +1632,7 @@ watch(selectedSubscriptionId, (newId) => {
       <ul class="warning-list">
         <li>SSE URLs are single-use. Once disconnected, the subscription cannot be reconnected.</li>
         <li>To receive events again after disconnecting, create a new subscription.</li>
-        <li>Subscriptions have a 15-minute TTL and expire if not connected.</li>
+        <li>SSE subscriptions have a server-determined 15-minute TTL (not configurable) and expire if not connected.</li>
       </ul>
     </div>
 

package/docs/ai-reference/AI-GROUPING.md

@@ -1,6 +1,6 @@
 # Layouts API - EEN API Toolkit
 
-> **Version:** 0.3.30
+> **Version:** 0.3.46
 >
 > Complete reference for layout management (camera grouping).
 > Load this document when working with layouts.
@@ -241,16 +241,29 @@ if (error) {
 
 ---
 
-## Vue Components
+## Vue Component Example
 
-### Layouts.vue
-
-```vue
-<script setup lang="ts">
+```typescript
 import { ref, computed, onMounted } from 'vue'
-import { getLayouts, createLayout, updateLayout, deleteLayout, type Layout, type EenError, type ListLayoutsParams, type LayoutSettings } from 'een-api-toolkit'
-
+import {
+  getLayouts,
+  getCameras,
+  createLayout,
+  updateLayout,
+  deleteLayout,
+  type Layout,
+  type Camera,
+  type EenError,
+  type ListLayoutsParams,
+  type CreateLayoutParams,
+  type UpdateLayoutParams,
+  type LayoutSettings
+} from 'een-api-toolkit'
+import LayoutModal from '../components/LayoutModal.vue'
+
+// Reactive state
 const layouts = ref<Layout[]>([])
+const cameras = ref<Camera[]>([])
 const loading = ref(false)
 const error = ref<EenError | null>(null)
 const nextPageToken = ref<string | undefined>(undefined)
@@ -262,6 +275,20 @@ const params = ref<ListLayoutsParams>({
   include: ['resourceCounts', 'effectivePermissions']
 })
 
+// Modal state
+const showModal = ref(false)
+const selectedLayout = ref<Layout | null>(null)
+const modalLoading = ref(false)
+const modalError = ref<string | null>(null)
+
+// Default settings for new layouts
+const defaultSettings: LayoutSettings = {
+  showCameraBorder: true,
+  showCameraName: true,
+  cameraAspectRatio: '16x9',
+  paneColumns: 3
+}
+
 async function fetchLayouts(fetchParams?: ListLayoutsParams, append = false) {
   loading.value = true
   error.value = null
@@ -271,7 +298,9 @@ async function fetchLayouts(fetchParams?: ListLayoutsParams, append = false) {
 
   if (result.error) {
     error.value = result.error
-    if (!append) layouts.value = []
+    if (!append) {
+      layouts.value = []
+    }
     nextPageToken.value = undefined
   } else {
     if (append) {
@@ -283,80 +312,113 @@ async function fetchLayouts(fetchParams?: ListLayoutsParams, append = false) {
   }
 
   loading.value = false
+  return result
+}
+
+async function fetchCameras() {
+  const result = await getCameras({ pageSize: 100, include: ['status'] })
+  if (result.data) {
+    cameras.value = result.data.results
+  }
+}
+
+function refresh() {
+  return fetchLayouts()
 }
 
 async function fetchNextPage() {
   if (!nextPageToken.value) return
-  return fetchLayouts({ ...params.value, pageToken: nextPageToken.value }, true)
+  // Destructure to explicitly exclude any existing pageToken from params
+  const { pageToken: _existingToken, ...restParams } = params.value
+  return fetchLayouts({ ...restParams, pageToken: nextPageToken.value }, true)
 }
 
-async function handleCreate(name: string, settings: LayoutSettings) {
-  const result = await createLayout({ name, settings })
-  if (result.data) {
-    await fetchLayouts()
-  }
-  return result
+function openCreateModal() {
+  selectedLayout.value = null
+  modalError.value = null
+  showModal.value = true
+}
+
+function openEditModal(layout: Layout) {
+  selectedLayout.value = layout
+  modalError.value = null
+  showModal.value = true
+}
+
+function closeModal() {
+  showModal.value = false
+  selectedLayout.value = null
+  modalError.value = null
 }
 
-async function handleUpdate(layoutId: string, name: string, settings: Partial<LayoutSettings>) {
-  const result = await updateLayout(layoutId, { name, settings })
-  if (!result.error) {
+async function handleSave(data: { name: string; settings: LayoutSettings; panes: Layout['panes'] }) {
+  modalLoading.value = true
+  modalError.value = null
+
+  try {
+    if (selectedLayout.value) {
+      // Update existing layout
+      const updateParams: UpdateLayoutParams = {
+        name: data.name,
+        settings: data.settings,
+        panes: data.panes
+      }
+
+      const result = await updateLayout(selectedLayout.value.id, updateParams)
+      if (result.error) {
+        modalError.value = result.error.message
+        return
+      }
+    } else {
+      // Create new layout
+      const createParams: CreateLayoutParams = {
+        name: data.name,
+        settings: data.settings,
+        panes: data.panes
+      }
+
+      const result = await createLayout(createParams)
+      if (result.error) {
+        modalError.value = result.error.message
+        return
+      }
+    }
+
+    closeModal()
     await fetchLayouts()
+  } catch (err) {
+    // Handle unexpected errors (network failures, state mutations, etc.)
+    modalError.value = err instanceof Error ? err.message : 'An unexpected error occurred'
+    console.error('handleSave error:', err)
+  } finally {
+    modalLoading.value = false
   }
-  return result
 }
 
 async function handleDelete(layoutId: string) {
+  if (!confirm('Are you sure you want to delete this layout?')) {
+    return
+  }
+
+  modalLoading.value = true
+  modalError.value = null
+
   const result = await deleteLayout(layoutId)
-  if (!result.error) {
-    await fetchLayouts()
+
+  if (result.error) {
+    modalError.value = result.error.message
+    modalLoading.value = false
+    return
   }
-  return result
+
+  closeModal()
+  await fetchLayouts()
+  modalLoading.value = false
 }
 
-onMounted(() => fetchLayouts())
-</script>
-
-<template>
-  <div class="layouts">
-    <div class="header">
-      <h2>Layouts</h2>
-      <button @click="fetchLayouts" :disabled="loading">
-        {{ loading ? 'Loading...' : 'Refresh' }}
-      </button>
-    </div>
-
-    <div v-if="loading && layouts.length === 0" class="loading">
-      Loading layouts...
-    </div>
-
-    <div v-else-if="error" class="error">
-      Error: {{ error.message }}
-    </div>
-
-    <div v-else>
-      <div v-if="layouts.length > 0" class="layout-grid">
-        <div v-for="layout in layouts" :key="layout.id" class="layout-card">
-          <h3>{{ layout.name }}</h3>
-          <p>Panes: {{ layout.panes.length }}</p>
-          <p>Columns: {{ layout.settings.paneColumns }}</p>
-          <div v-if="layout.effectivePermissions">
-            <span v-if="layout.effectivePermissions.edit">Can Edit</span>
-            <span v-if="layout.effectivePermissions.delete">Can Delete</span>
-          </div>
-        </div>
-      </div>
-
-      <p v-else>No layouts found.</p>
-
-      <div v-if="hasNextPage" class="pagination">
-        <button @click="fetchNextPage" :disabled="loading">
-          {{ loading ? 'Loading...' : 'Load More' }}
-        </button>
-      </div>
-    </div>
-  </div>
-</template>
+onMounted(async () => {
+  await Promise.all([fetchLayouts(), fetchCameras()])
+})
 ```
 
 ---

package/docs/ai-reference/AI-MEDIA.md

@@ -1,6 +1,6 @@
 # Media & Live Video - EEN API Toolkit
 
-> **Version:** 0.3.38
+> **Version:** 0.3.46
 >
 > Complete reference for media retrieval, live streaming, and video playback.
 > Load this document when implementing video features.

package/docs/ai-reference/AI-SETUP.md

@@ -1,6 +1,6 @@
 # Vue 3 Application Setup - EEN API Toolkit
 
-> **Version:** 0.3.38
+> **Version:** 0.3.46
 >
 > Complete guide for setting up a Vue 3 application with the een-api-toolkit.
 > Load this document when creating a new project or troubleshooting setup issues.

package/docs/ai-reference/AI-USERS.md

@@ -1,6 +1,6 @@
 # Users API - EEN API Toolkit
 
-> **Version:** 0.3.38
+> **Version:** 0.3.46
 >
 > Complete reference for user management.
 > Load this document when working with user data.

package/examples/vue-alerts-metrics/src/App.vue

@@ -1,9 +1,15 @@
 <script setup lang="ts">
+import { onMounted, computed } from 'vue'
 import { useAuthStore } from 'een-api-toolkit'
-import { computed } from 'vue'
 
 const authStore = useAuthStore()
 const isAuthenticated = computed(() => authStore.isAuthenticated)
+
+// Initialize auth store from storage on app mount
+// This restores the session if a valid token exists in localStorage/sessionStorage
+onMounted(() => {
+  authStore.initialize()
+})
 </script>
 
 <template>

package/examples/vue-automations/.env.example

@@ -0,0 +1,11 @@
+# EEN OAuth proxy URL
+VITE_PROXY_URL=http://localhost:8787
+
+# EEN OAuth client ID
+VITE_EEN_CLIENT_ID=your-client-id-here
+
+# OAuth redirect URI (must be exactly this for EEN IDP)
+VITE_REDIRECT_URI=http://127.0.0.1:3333
+
+# Enable debug logging
+VITE_DEBUG=true

package/examples/vue-automations/README.md

@@ -0,0 +1,205 @@
+# EEN API Toolkit - Vue Automations Example
+
+A complete example showing how to use the een-api-toolkit automation functions in a Vue 3 application.
+
+## Storage Strategy: Memory
+
+This example uses the `memory` storage strategy for maximum security. This means:
+
+- **Tokens are never written to disk** - immune to localStorage/sessionStorage XSS attacks
+- **Page refresh requires re-authentication** - tokens exist only in memory
+- **Each tab is independent** - opening a new tab requires separate login
+
+This is the recommended strategy for high-security deployments where protecting against XSS token theft is critical.
+
+## Features Demonstrated
+
+- OAuth authentication flow (login, callback, logout)
+- Protected routes with navigation guards
+- List event alert condition rules
+- List alert condition rules with actions and insights
+- List alert action rules
+- List alert actions (notifications, webhooks, etc.)
+- Filter by enabled status
+- Pagination support
+
+## APIs Used
+
+- `listEventAlertConditionRules()` - List event alert condition rules
+- `listAlertConditionRules()` - List alert condition rules with optional includes
+- `listAlertActionRules()` - List alert action rules
+- `listAlertActions()` - List alert actions
+- `useAuthStore()` - Authentication state management
+- `getAuthUrl()` - Generate OAuth login URL
+- `handleAuthCallback()` - Process OAuth callback
+- `initEenToolkit()` - Toolkit initialization
+
+## Setup
+
+### Prerequisites
+
+1. **Start the OAuth proxy** (required for authentication):
+
+   The OAuth proxy is a separate project that handles token management securely.
+   Clone and run it from: https://github.com/klaushofrichter/een-oauth-proxy
+
+   ```bash
+   # In a separate terminal, from the een-oauth-proxy directory
+   npm install
+   npm run dev
+   ```
+
+   The proxy should be running at `http://localhost:8787`.
+
+### Example Setup
+
+All commands below should be run from this example directory (`examples/vue-automations/`):
+
+2. Copy the environment file:
+   ```bash
+   # From examples/vue-automations/
+   cp .env.example .env
+   ```
+
+3. Edit `.env` with your EEN credentials:
+   ```env
+   VITE_EEN_CLIENT_ID=your-client-id
+   VITE_PROXY_URL=http://localhost:8787
+   # DO NOT change the redirect URI - EEN IDP only permits this URL
+   VITE_REDIRECT_URI=http://127.0.0.1:3333
+   ```
+
+4. Install dependencies and start:
+   ```bash
+   # From examples/vue-automations/
+   npm install
+   npm run dev
+   ```
+
+5. Open http://127.0.0.1:3333 in your browser.
+
+**Important:** The EEN Identity Provider only permits `http://127.0.0.1:3333` as the OAuth redirect URI. Do not use `localhost` or other ports.
+
+**Note:** Development and testing was done on macOS. The `npm run stop` command uses `lsof`, which is not available on Windows. Windows users should manually stop any process on port 3333 or use `npx kill-port 3333` instead.
+
+## Project Structure
+
+```
+src/
+├── main.ts          # App entry, toolkit initialization
+├── App.vue          # Root component with navigation
+├── router/
+│   └── index.ts     # Vue Router with auth guards
+└── views/
+    ├── Home.vue        # Home page with user profile
+    ├── Login.vue       # OAuth login redirect
+    ├── Callback.vue    # OAuth callback handler
+    ├── Automations.vue # Automation rules display
+    └── Logout.vue      # Logout handler
+```
+
+## Key Code Examples
+
+### Initializing the Toolkit (main.ts)
+
+```typescript
+import { initEenToolkit } from 'een-api-toolkit'
+
+initEenToolkit({
+  proxyUrl: import.meta.env.VITE_PROXY_URL,
+  clientId: import.meta.env.VITE_EEN_CLIENT_ID,
+  storageStrategy: 'memory',  // Maximum security - tokens lost on refresh
+  debug: true
+})
+```
+
+### Listing Event Alert Condition Rules
+
+```typescript
+import { listEventAlertConditionRules, type EventAlertConditionRule } from 'een-api-toolkit'
+
+const rules = ref<EventAlertConditionRule[]>([])
+
+async function fetchRules() {
+  const result = await listEventAlertConditionRules({
+    pageSize: 10,
+    enabled: true  // Only enabled rules
+  })
+
+  if (result.error) {
+    // Handle error
+  } else {
+    rules.value = result.data.results
+  }
+}
+```
+
+### Listing Alert Condition Rules with Includes
+
+```typescript
+import { listAlertConditionRules, type AlertConditionRule } from 'een-api-toolkit'
+
+const rules = ref<AlertConditionRule[]>([])
+
+async function fetchRules() {
+  const result = await listAlertConditionRules({
+    pageSize: 10,
+    include: ['actions', 'insights']  // Include related data
+  })
+
+  if (result.error) {
+    // Handle error
+  } else {
+    rules.value = result.data.results
+    // Each rule now has rule.actions and rule.insights populated
+  }
+}
+```
+
+### Listing Alert Actions
+
+```typescript
+import { listAlertActions, type AutomationAlertAction } from 'een-api-toolkit'
+
+const actions = ref<AutomationAlertAction[]>([])
+
+async function fetchActions() {
+  const result = await listAlertActions({
+    pageSize: 10,
+    type__in: ['notification', 'webhook', 'slack']  // Filter by action type
+  })
+
+  if (result.error) {
+    // Handle error
+  } else {
+    actions.value = result.data.results
+  }
+}
+```
+
+### Auth Guard (router/index.ts)
+
+```typescript
+router.beforeEach((to, from, next) => {
+  const authStore = useAuthStore()
+
+  if (to.meta.requiresAuth && !authStore.isAuthenticated) {
+    next('/login')
+  } else {
+    next()
+  }
+})
+```
+
+## Running E2E Tests
+
+```bash
+# Install Playwright browsers (first time only)
+npx playwright install
+
+# Run E2E tests
+npm run test:e2e
+
+# Run with UI
+npm run test:e2e:ui
+```

package/examples/vue-automations/e2e/app.spec.ts

@@ -0,0 +1,83 @@
+import { test, expect } from '@playwright/test'
+
+test.describe('Vue Automations Example - App', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/')
+  })
+
+  test('app loads with correct title', async ({ page }) => {
+    await expect(page).toHaveTitle(/EEN Automations/)
+  })
+
+  test('header displays app name', async ({ page }) => {
+    await expect(page.locator('[data-testid="app-title"]')).toHaveText('EEN Automations Example')
+  })
+
+  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()
+
+    // Automations and Logout should NOT be visible (requires auth)
+    await expect(page.locator('[data-testid="nav-automations"]')).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="login-button"]')).toBeVisible()
+  })
+
+  test('home page displays storage strategy', async ({ page }) => {
+    await expect(page.locator('[data-testid="storage-strategy"]')).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 redirects to login', async ({ page }) => {
+    await page.goto('/automations')
+
+    // 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('/')
+  })
+
+  test('home page shows features list', async ({ page }) => {
+    // Check that the features section is visible
+    const description = page.locator('.description')
+    await expect(description).toBeVisible()
+
+    // Check for features list items (6 features + 4 functions = 10 total)
+    await expect(description.locator('li')).toHaveCount(10)
+  })
+
+  test('home page shows functions used', async ({ page }) => {
+    // Check that the functions used section mentions the automation functions
+    const description = page.locator('.description')
+    await expect(description.locator('code')).toHaveCount(4)
+    await expect(description.locator('text=listEventAlertConditionRules')).toBeVisible()
+    await expect(description.locator('text=listAlertConditionRules')).toBeVisible()
+    await expect(description.locator('text=listAlertActionRules')).toBeVisible()
+    await expect(description.locator('text=listAlertActions')).toBeVisible()
+  })
+})