een-api-toolkit 0.3.30 → 0.3.38

package/examples/vue-layouts/README.md

@@ -0,0 +1,320 @@
+# EEN API Toolkit - Vue Layouts Example
+
+A complete example showing how to use the Layouts API with een-api-toolkit in a Vue 3 application.
+
+![Layouts Screenshot](layouts-screenshot.png)
+
+## 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
+- `getLayouts()` function with pagination
+- `createLayout()` function for creating new layouts
+- `updateLayout()` function for modifying layouts
+- `deleteLayout()` function for removing layouts
+- Layout modal for create/edit operations
+- Camera pane management within layouts
+- Error handling with Result pattern
+- Reactive authentication state
+
+## APIs Used
+
+- `getLayouts()` - List layouts with pagination and filtering
+- `getLayout()` - Get a specific layout by ID
+- `createLayout()` - Create a new layout
+- `updateLayout()` - Update an existing layout
+- `deleteLayout()` - Delete a layout
+- `getCameras()` - Get cameras for pane selection
+- `getCurrentUser()` - Get current user profile
+- `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-layouts/`):
+
+2. Copy the environment file:
+   ```bash
+   # From examples/vue-layouts/
+   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-layouts/
+   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
+│   ├── Layouts.vue      # Layout list with CRUD operations
+│   └── Logout.vue       # Logout handler
+└── components/
+    └── LayoutModal.vue  # Modal for create/edit layouts
+```
+
+## 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
+})
+```
+
+### Fetching Layouts with Pagination (Layouts.vue)
+
+```typescript
+import { ref } from 'vue'
+import { getLayouts, type Layout } from 'een-api-toolkit'
+
+const layouts = ref<Layout[]>([])
+const nextPageToken = ref<string | undefined>(undefined)
+const loading = ref(false)
+
+async function fetchLayouts() {
+  loading.value = true
+  const result = await getLayouts({
+    pageSize: 20,
+    include: ['effectivePermissions', 'resourceCounts']
+  })
+
+  if (result.error) {
+    console.error('Failed to fetch layouts:', result.error.message)
+  } else {
+    layouts.value = result.data.results
+    nextPageToken.value = result.data.nextPageToken
+  }
+  loading.value = false
+}
+```
+
+### Creating a Layout
+
+```typescript
+import { createLayout, type CreateLayoutParams } from 'een-api-toolkit'
+
+async function handleCreate(params: CreateLayoutParams) {
+  const result = await createLayout({
+    name: 'My New Layout',
+    settings: {
+      paneColumns: 2,
+      cameraAspectRatio: '16x9',
+      showCameraBorder: true,
+      showCameraName: true
+    },
+    panes: []
+  })
+
+  if (result.error) {
+    console.error('Failed to create layout:', result.error.message)
+  } else {
+    console.log('Created layout:', result.data.id)
+    await fetchLayouts() // Refresh the list
+  }
+}
+```
+
+### Updating a Layout
+
+```typescript
+import { updateLayout, type UpdateLayoutParams } from 'een-api-toolkit'
+
+async function handleUpdate(layoutId: string, params: UpdateLayoutParams) {
+  const result = await updateLayout(layoutId, {
+    name: 'Updated Layout Name',
+    settings: {
+      paneColumns: 3
+    }
+  })
+
+  if (result.error) {
+    console.error('Failed to update layout:', result.error.message)
+  } else {
+    await fetchLayouts() // Refresh the list
+  }
+}
+```
+
+### Deleting a Layout
+
+```typescript
+import { deleteLayout } from 'een-api-toolkit'
+
+async function handleDelete(layoutId: string) {
+  if (!confirm('Are you sure you want to delete this layout?')) return
+
+  const result = await deleteLayout(layoutId)
+
+  if (result.error) {
+    console.error('Failed to delete layout:', result.error.message)
+  } else {
+    await fetchLayouts() // Refresh the list
+  }
+}
+```
+
+### Layout Modal Component (LayoutModal.vue)
+
+```typescript
+import { ref, watch } from 'vue'
+import { getCameras, type Layout, type Camera, type LayoutPane } from 'een-api-toolkit'
+
+const props = defineProps<{
+  layout?: Layout | null
+  isOpen: boolean
+}>()
+
+const emit = defineEmits<{
+  save: [params: { name: string; settings: LayoutSettings; panes: LayoutPane[] }]
+  delete: [layoutId: string]
+  close: []
+}>()
+
+const cameras = ref<Camera[]>([])
+const name = ref('')
+const paneColumns = ref(2)
+const panes = ref<LayoutPane[]>([])
+
+// Fetch cameras for pane selection
+async function fetchCameras() {
+  const result = await getCameras({ pageSize: 100, include: ['status'] })
+  if (!result.error) {
+    cameras.value = result.data.results
+  }
+}
+
+// Add a new pane
+function addPane() {
+  panes.value.push({
+    id: panes.value.length,
+    name: `Pane ${panes.value.length + 1}`,
+    type: 'preview',
+    size: 1,
+    cameraId: ''
+  })
+}
+```
+
+### Auth Guard (router/index.ts)
+
+```typescript
+router.beforeEach((to, from, next) => {
+  const authStore = useAuthStore()
+
+  if (to.meta.requiresAuth && !authStore.isAuthenticated) {
+    next('/login')
+  } else {
+    next()
+  }
+})
+```
+
+## Layout Types
+
+```typescript
+interface Layout {
+  id: string
+  name: string
+  accountId: string
+  panes: LayoutPane[]
+  settings: LayoutSettings
+  effectivePermissions?: LayoutPermissions
+  resourceCounts?: { cameras?: number }
+}
+
+interface LayoutPane {
+  id: number
+  name: string
+  type: 'preview' | 'compositePreview'
+  size: 1 | 2 | 3
+  cameraId: string
+}
+
+interface LayoutSettings {
+  showCameraBorder: boolean
+  showCameraName: boolean
+  cameraAspectRatio: '16x9' | '4x3'
+  paneColumns: number  // 1-6
+}
+```
+
+## Running E2E Tests
+
+The example includes Playwright E2E tests:
+
+```bash
+# Run all E2E tests
+npm run test:e2e
+
+# Run with UI for debugging
+npm run test:e2e:ui
+```
+
+Tests cover:
+- App loads correctly
+- Navigation between pages
+- Authentication flow
+- Protected route redirection
+- OAuth login flow (when proxy is available)
+- Layouts page after authentication

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

@@ -0,0 +1,76 @@
+import { test, expect } from '@playwright/test'
+
+test.describe('Vue Layouts Example - App', () => {
+  test.beforeEach(async ({ page }) => {
+    // Capture console errors
+    page.on('console', msg => {
+      if (msg.type() === 'error') {
+        console.log('Browser console error:', msg.text())
+      }
+    })
+    page.on('pageerror', err => {
+      console.log('Page error:', err.message)
+    })
+
+    await page.goto('/')
+    // Wait for Vue app header AND router-view content to render
+    // The header renders first, then router-view resolves the route
+    await page.waitForSelector('[data-testid="app-title"]', { timeout: 10000 })
+    // Wait for router-view content (either authenticated or not-authenticated state)
+    await page.waitForSelector('.home, .login, .layouts', { timeout: 10000 })
+  })
+
+  test('app loads with correct title', async ({ page }) => {
+    await expect(page).toHaveTitle(/EEN Layouts/)
+  })
+
+  test('header displays app name', async ({ page }) => {
+    await expect(page.locator('[data-testid="app-title"]')).toHaveText('EEN Layouts 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()
+
+    // Layouts and Logout should NOT be visible (requires auth)
+    await expect(page.locator('[data-testid="nav-layouts"]')).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 redirects to login', async ({ page }) => {
+    await page.goto('/layouts')
+
+    // 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-layouts/e2e/auth.spec.ts

@@ -0,0 +1,264 @@
+import { test, expect, Page } from '@playwright/test'
+import { baseURL } from '../playwright.config'
+
+/**
+ * E2E tests for the Vue Layouts Example
+ *
+ * Tests the OAuth login flow through the UI:
+ * 1. Click login button in the example app
+ * 2. Enter credentials on EEN OAuth page
+ * 3. Complete the OAuth callback
+ * 4. Verify authenticated state
+ *
+ * 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
+// Values chosen based on OAuth flow timing requirements
+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
+} 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.
+ * Returns true if proxy responds (even with 404), false if unreachable.
+ */
+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
+    })
+    // 404 is ok - means proxy is running but endpoint doesn't exist
+    return response.ok || response.status === 404
+  } catch {
+    return false
+  } finally {
+    clearTimeout(timeoutId)
+  }
+}
+
+/**
+ * Performs OAuth login flow through the UI.
+ * Starts from home page and completes full OAuth authentication.
+ */
+async function performLogin(page: Page, username: string, password: string): Promise<void> {
+  // Start at home page
+  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 - use OR selector for robustness
+  await page.locator('#next, button:has-text("Sign in")').first().click()
+
+  // Wait for redirect back to the app using configured baseURL
+  const baseURLPattern = new RegExp(baseURL.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+  await page.waitForURL(baseURLPattern, { timeout: TIMEOUTS.AUTH_COMPLETE })
+}
+
+/**
+ * Clears browser storage to reset auth state.
+ * Handles cases where localStorage isn't accessible (e.g., about:blank, cross-origin).
+ */
+async function clearAuthState(page: Page): Promise<void> {
+  try {
+    // Only try to clear storage if we're on a page that allows it
+    const url = page.url()
+    if (url && url.startsWith('http')) {
+      await page.evaluate(() => {
+        try {
+          localStorage.clear()
+          sessionStorage.clear()
+        } catch {
+          // Ignore errors - storage may not be accessible
+        }
+      })
+    }
+  } catch {
+    // Ignore errors - page may be closed or in an inaccessible state
+  }
+}
+
+test.describe('Vue Layouts Example', () => {
+  // Check proxy accessibility once before all tests
+  let proxyAccessible = false
+
+  // Helper functions to skip tests when prerequisites aren't met
+  function skipIfNoProxy() {
+    test.skip(!proxyAccessible, 'OAuth proxy not accessible')
+  }
+
+  function skipIfNoCredentials() {
+    test.skip(!TEST_USER || !TEST_PASSWORD, 'Test credentials not available')
+  }
+
+  function skipIfNoUser() {
+    test.skip(!TEST_USER, 'Test user 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 }) => {
+    // Clear auth state after each test to prevent state pollution
+    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('layouts page shows not-authenticated state without login', async ({ page }) => {
+    await page.goto('/layouts')
+    await expect(
+      page.locator('[data-testid="not-authenticated"], [data-testid="nav-login"], .error, .auth-required').first()
+    ).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+  })
+
+  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-layouts"]')).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 layouts list after login', async ({ page }) => {
+    skipIfNoProxy()
+    skipIfNoCredentials()
+
+    await performLogin(page, TEST_USER!, TEST_PASSWORD!)
+    await expect(page.locator('[data-testid="nav-layouts"]')).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+
+    // Navigate to layouts page
+    await page.click('[data-testid="nav-layouts"]')
+    await page.waitForURL('/layouts')
+
+    // Should see layouts header and create button (not error state)
+    await expect(page.locator('.layouts .header h2')).toHaveText('Layouts')
+    await expect(page.getByRole('button', { name: 'Create Layout' })).toBeVisible()
+    await expect(page.locator('.error')).not.toBeVisible()
+  })
+
+  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()
+  })
+
+  test('invalid password shows error on OAuth page', async ({ page }) => {
+    skipIfNoProxy()
+    skipIfNoUser()
+
+    await page.goto('/')
+
+    // Click login and wait for OAuth redirect
+    await Promise.all([
+      page.waitForURL(/.*eagleeyenetworks.com.*/, { timeout: TIMEOUTS.OAUTH_REDIRECT }),
+      page.click('[data-testid="login-button"]')
+    ])
+
+    // Fill valid email
+    const emailInput = page.locator('#authentication--input__email')
+    await emailInput.waitFor({ state: 'visible', timeout: TIMEOUTS.ELEMENT_VISIBLE })
+    await emailInput.fill(TEST_USER!)
+    await page.getByRole('button', { name: 'Next' }).click()
+
+    // Fill invalid password
+    const passwordInput = page.locator('#authentication--input__password')
+    await passwordInput.waitFor({ state: 'visible', timeout: TIMEOUTS.PASSWORD_VISIBLE })
+    await passwordInput.fill('invalid-password-12345!')
+
+    // Click sign in
+    await page.locator('#next, button:has-text("Sign in")').first().click()
+
+    // Should show error message on OAuth page
+    await expect(
+      page.locator('.error, [class*="error"], [data-testid*="error"], #error, .alert-danger').first()
+    ).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+
+    // Should still be on OAuth page
+    await expect(page).toHaveURL(/eagleeyenetworks\.com/)
+  })
+})

package/examples/vue-layouts/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 Layouts Example</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>