een-api-toolkit 0.3.30 → 0.3.38

package/docs/AI-CONTEXT.md

@@ -1,6 +1,6 @@
 # EEN API Toolkit - AI Reference
 
-> **Version:** 0.3.30
+> **Version:** 0.3.38
 >
 > This documentation is optimized for AI assistants. It provides focused, domain-specific
 > references to help you understand and use the een-api-toolkit efficiently.
@@ -17,6 +17,7 @@
 | Implementing OAuth login | [AI-AUTH.md](./ai-reference/AI-AUTH.md) | ~2K |
 | Working with users | [AI-USERS.md](./ai-reference/AI-USERS.md) | ~1.5K |
 | Working with cameras or bridges | [AI-DEVICES.md](./ai-reference/AI-DEVICES.md) | ~3K |
+| Working with layouts | [AI-GROUPING.md](./ai-reference/AI-GROUPING.md) | ~3K |
 | Live video, images, HLS playback | [AI-MEDIA.md](./ai-reference/AI-MEDIA.md) | ~4K |
 | Events, alerts, metrics, SSE | [AI-EVENTS.md](./ai-reference/AI-EVENTS.md) | ~3.5K |
 
@@ -30,6 +31,7 @@ Specialized agents are available in `.claude/agents/` for domain-specific tasks:
 | `een-auth-agent` | Implementing login/logout, auth callbacks, route guards, token refresh |
 | `een-users-agent` | Listing users, user profiles, user management features |
 | `een-devices-agent` | Working with cameras or bridges, filtering by status/tags |
+| `een-grouping-agent` | Layouts CRUD, camera pane management, layout settings |
 | `een-media-agent` | Live video, camera previews, HLS playback, recorded images |
 | `een-events-agent` | Events, alerts, metrics, real-time SSE subscriptions |
 
@@ -65,6 +67,7 @@ Then follow the context files and instructions specified within.
 | [vue-users](../examples/vue-users/) | User management with pagination | `src/views/Users.vue` |
 | [vue-cameras](../examples/vue-cameras/) | Camera listing with status filters | `src/views/Cameras.vue` |
 | [vue-bridges](../examples/vue-bridges/) | Bridge listing with device info | `src/views/Bridges.vue` |
+| [vue-layouts](../examples/vue-layouts/) | Layout CRUD with camera panes | `src/views/Layouts.vue` |
 | [vue-media](../examples/vue-media/) | Live and recorded image viewing | `src/views/LiveCamera.vue` |
 | [vue-feeds](../examples/vue-feeds/) | Live video streaming | `src/views/Feeds.vue` |
 | [vue-events](../examples/vue-events/) | Events with bounding boxes | `src/components/EventsModal.vue` |
@@ -107,6 +110,15 @@ Then follow the context files and instructions specified within.
 | `getBridges(params?)` | List all bridges (paginated) |
 | `getBridge(bridgeId, params?)` | Get a specific bridge |
 
+### Layouts
+| Function | Purpose |
+|----------|---------|
+| `getLayouts(params?)` | List all layouts (paginated) |
+| `getLayout(layoutId, params?)` | Get a specific layout |
+| `createLayout(params)` | Create a new layout |
+| `updateLayout(layoutId, params)` | Update a layout |
+| `deleteLayout(layoutId)` | Delete a layout |
+
 ### Media
 | Function | Purpose |
 |----------|---------|

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

@@ -1,6 +1,6 @@
 # Authentication - EEN API Toolkit
 
-> **Version:** 0.3.30
+> **Version:** 0.3.38
 >
 > OAuth flow implementation, token management, and session handling.
 > Load this document when implementing login, logout, or auth guards.

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

@@ -1,6 +1,6 @@
 # Cameras & Bridges API - EEN API Toolkit
 
-> **Version:** 0.3.30
+> **Version:** 0.3.38
 >
 > 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.30
+> **Version:** 0.3.38
 >
 > Complete reference for events, alerts, metrics, and SSE subscriptions.
 > Load this document when implementing event-driven features.

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

@@ -0,0 +1,411 @@
+# Layouts API - EEN API Toolkit
+
+> **Version:** 0.3.30
+>
+> Complete reference for layout management (camera grouping).
+> Load this document when working with layouts.
+
+---
+
+## Overview
+
+Layouts organize multiple camera views into a grid for monitoring. Each layout contains:
+- **Name** - Display name for the layout
+- **Settings** - Display configuration (columns, aspect ratio, borders)
+- **Panes** - Array of camera positions in the grid
+
+---
+
+## Layout Types
+
+### Layout
+
+```typescript
+interface Layout {
+  id: string
+  name: string
+  accountId: string
+  panes: LayoutPane[]
+  settings: LayoutSettings
+  effectivePermissions?: LayoutPermissions
+  resourceCounts?: { cameras?: number }
+  resourceStatusCounts?: { cameras?: CameraStatusCounts }
+  qRelevance?: number
+}
+
+interface LayoutPane {
+  id: number              // Unique pane ID within layout
+  name: string            // Display name
+  type: 'preview' | 'compositePreview'
+  size: 1 | 2 | 3        // Grid size (1=small, 2=medium, 3=large)
+  cameraId: string       // Camera to display
+  compositeId?: string | null
+}
+
+interface LayoutSettings {
+  showCameraBorder: boolean
+  showCameraName: boolean
+  cameraAspectRatio: '16x9' | '4x3'
+  paneColumns: number    // 1-6 columns
+}
+
+interface LayoutPermissions {
+  read?: boolean
+  edit?: boolean
+  delete?: boolean
+}
+```
+
+### Parameters
+
+```typescript
+interface ListLayoutsParams {
+  pageSize?: number              // Results per page
+  pageToken?: string             // Pagination token
+  include?: ListLayoutsInclude[] // Additional fields
+  sort?: ListLayoutsSort[]       // Sort order
+  name?: string                  // Exact name match
+  name__in?: string[]            // Names (any match)
+  name__contains?: string        // Partial name match
+  id__in?: string[]              // Filter by IDs
+  q?: string                     // Full-text search
+  qRelevance__gte?: number       // Min relevance (0.0-1.0)
+}
+
+type ListLayoutsInclude =
+  | 'effectivePermissions'
+  | 'resourceCounts'
+  | 'resourceStatusCounts'
+  | 'qRelevance'
+
+type ListLayoutsSort =
+  | '+name' | '-name'
+  | '+rotationOrder'
+  | '+qRelevance' | '-qRelevance'
+
+interface CreateLayoutParams {
+  name: string           // Required
+  settings: LayoutSettings  // Required
+  panes?: LayoutPane[]   // Optional initial panes
+}
+
+interface UpdateLayoutParams {
+  name?: string
+  settings?: Partial<LayoutSettings>
+  panes?: LayoutPane[]   // Replaces existing panes
+}
+```
+
+---
+
+## Layout Functions
+
+### getLayouts(params?)
+
+```typescript
+import { getLayouts } from 'een-api-toolkit'
+
+// Basic usage
+const { data, error } = await getLayouts()
+
+// With pagination and includes
+const { data } = await getLayouts({
+  pageSize: 50,
+  include: ['resourceCounts', 'effectivePermissions']
+})
+
+// Search layouts
+const { data } = await getLayouts({
+  q: 'lobby',
+  qRelevance__gte: 0.5
+})
+
+// Filter by name
+const { data } = await getLayouts({
+  name__contains: 'entrance'
+})
+```
+
+### getLayout(layoutId, params?)
+
+```typescript
+import { getLayout } from 'een-api-toolkit'
+
+const { data, error } = await getLayout('layout-123')
+
+// With additional fields
+const { data: detailed } = await getLayout('layout-123', {
+  include: ['effectivePermissions', 'resourceStatusCounts']
+})
+
+if (data) {
+  console.log(`Layout: ${data.name}`)
+  console.log(`Panes: ${data.panes.length}`)
+  console.log(`Columns: ${data.settings.paneColumns}`)
+}
+```
+
+### createLayout(params)
+
+```typescript
+import { createLayout, type LayoutSettings } from 'een-api-toolkit'
+
+const settings: LayoutSettings = {
+  showCameraBorder: true,
+  showCameraName: true,
+  cameraAspectRatio: '16x9',
+  paneColumns: 3
+}
+
+// Create empty layout
+const { data, error } = await createLayout({
+  name: 'Main Lobby View',
+  settings
+})
+
+// Create with panes
+const { data } = await createLayout({
+  name: 'Entrance Cameras',
+  settings,
+  panes: [
+    { id: 1, name: 'Front Door', type: 'preview', size: 2, cameraId: 'cam-123' },
+    { id: 2, name: 'Side Gate', type: 'preview', size: 1, cameraId: 'cam-456' }
+  ]
+})
+
+if (data) {
+  console.log(`Created layout: ${data.id}`)
+}
+```
+
+### updateLayout(layoutId, params)
+
+```typescript
+import { updateLayout } from 'een-api-toolkit'
+
+// Update name
+const { error } = await updateLayout('layout-123', {
+  name: 'Updated Layout Name'
+})
+
+// Update settings (partial)
+const { error } = await updateLayout('layout-123', {
+  settings: {
+    paneColumns: 4,
+    showCameraName: false
+  }
+})
+
+// Replace panes
+const { error } = await updateLayout('layout-123', {
+  panes: [
+    { id: 1, name: 'New Pane', type: 'preview', size: 1, cameraId: 'cam-789' }
+  ]
+})
+
+if (!error) {
+  console.log('Layout updated successfully')
+}
+```
+
+### deleteLayout(layoutId)
+
+```typescript
+import { deleteLayout } from 'een-api-toolkit'
+
+const { error } = await deleteLayout('layout-123')
+
+if (error) {
+  if (error.code === 'NOT_FOUND') {
+    console.log('Layout already deleted')
+  } else if (error.code === 'FORBIDDEN') {
+    console.log('No permission to delete')
+  }
+} else {
+  console.log('Layout deleted successfully')
+}
+```
+
+---
+
+## Filter Patterns
+
+| Filter | Example | Description |
+|--------|---------|-------------|
+| `name` | `'Main Lobby'` | Exact name match |
+| `name__in` | `['Lobby', 'Entrance']` | Any name matches |
+| `name__contains` | `'lobby'` | Partial name match |
+| `id__in` | `['id1', 'id2']` | Filter by IDs |
+| `q` | `'front door'` | Full-text search |
+| `qRelevance__gte` | `0.5` | Min search relevance |
+
+---
+
+## Vue Components
+
+### Layouts.vue
+
+```vue
+<script setup lang="ts">
+import { ref, computed, onMounted } from 'vue'
+import { getLayouts, createLayout, updateLayout, deleteLayout, type Layout, type EenError, type ListLayoutsParams, type LayoutSettings } from 'een-api-toolkit'
+
+const layouts = ref<Layout[]>([])
+const loading = ref(false)
+const error = ref<EenError | null>(null)
+const nextPageToken = ref<string | undefined>(undefined)
+
+const hasNextPage = computed(() => !!nextPageToken.value)
+
+const params = ref<ListLayoutsParams>({
+  pageSize: 20,
+  include: ['resourceCounts', 'effectivePermissions']
+})
+
+async function fetchLayouts(fetchParams?: ListLayoutsParams, append = false) {
+  loading.value = true
+  error.value = null
+
+  const mergedParams = { ...params.value, ...fetchParams }
+  const result = await getLayouts(mergedParams)
+
+  if (result.error) {
+    error.value = result.error
+    if (!append) layouts.value = []
+    nextPageToken.value = undefined
+  } else {
+    if (append) {
+      layouts.value = [...layouts.value, ...result.data.results]
+    } else {
+      layouts.value = result.data.results
+    }
+    nextPageToken.value = result.data.nextPageToken
+  }
+
+  loading.value = false
+}
+
+async function fetchNextPage() {
+  if (!nextPageToken.value) return
+  return fetchLayouts({ ...params.value, pageToken: nextPageToken.value }, true)
+}
+
+async function handleCreate(name: string, settings: LayoutSettings) {
+  const result = await createLayout({ name, settings })
+  if (result.data) {
+    await fetchLayouts()
+  }
+  return result
+}
+
+async function handleUpdate(layoutId: string, name: string, settings: Partial<LayoutSettings>) {
+  const result = await updateLayout(layoutId, { name, settings })
+  if (!result.error) {
+    await fetchLayouts()
+  }
+  return result
+}
+
+async function handleDelete(layoutId: string) {
+  const result = await deleteLayout(layoutId)
+  if (!result.error) {
+    await fetchLayouts()
+  }
+  return result
+}
+
+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>
+```
+
+---
+
+## Error Handling
+
+| Error Code | HTTP Status | Meaning | Action |
+|------------|-------------|---------|--------|
+| AUTH_REQUIRED | 401 | Not authenticated | Redirect to login |
+| FORBIDDEN | 403 | No permission | Show access denied |
+| NOT_FOUND | 404 | Layout doesn't exist | Show "not found" |
+| VALIDATION_ERROR | 400 | Invalid request | Show validation error |
+| RATE_LIMITED | 429 | Too many requests | Retry with backoff |
+| API_ERROR | 5xx | Server error | Show error, allow retry |
+
+---
+
+## Best Practices
+
+1. **Check permissions before edit/delete**
+   ```typescript
+   if (layout.effectivePermissions?.edit) {
+     // Show edit button
+   }
+   ```
+
+2. **Use includes sparingly** - Only request fields you need
+   ```typescript
+   // Only include what you'll display
+   const { data } = await getLayouts({
+     include: ['resourceCounts']  // Skip permissions if not needed
+   })
+   ```
+
+3. **Handle empty panes array**
+   ```typescript
+   // Layout can have empty panes array
+   const paneCount = layout.panes?.length || 0
+   ```
+
+4. **Validate panes before save**
+   ```typescript
+   // Remove panes without cameras
+   const validPanes = panes.filter(p => p.cameraId)
+   await updateLayout(layoutId, { panes: validPanes })
+   ```
+
+---
+
+## Reference Examples
+
+- `examples/vue-layouts/` - Complete CRUD example with modal

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

@@ -1,6 +1,6 @@
 # Media & Live Video - EEN API Toolkit
 
-> **Version:** 0.3.30
+> **Version:** 0.3.38
 >
 > 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.30
+> **Version:** 0.3.38
 >
 > 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.30
+> **Version:** 0.3.38
 >
 > Complete reference for user management.
 > Load this document when working with user data.

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

@@ -2,6 +2,8 @@
 
 A Vue 3 example application demonstrating the Event Metrics, Alerts, and Notifications APIs from the `een-api-toolkit`.
 
+![Alerts Metrics Screenshot](alert-metrics-screenshot.png)
+
 ## Status
 
 | Feature | Status |

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

@@ -20,7 +20,7 @@ const TIMEOUTS = {
   OAUTH_REDIRECT: 30000,
   ELEMENT_VISIBLE: 15000,
   PASSWORD_VISIBLE: 10000,
-  AUTH_COMPLETE: 30000,
+  AUTH_COMPLETE: 45000,  // Increased for CI stability (OAuth callback can be slow)
   UI_UPDATE: 10000,
   PROXY_CHECK: 5000
 } as const

package/examples/vue-alerts-metrics/package-lock.json

@@ -17,7 +17,7 @@
         "vue-router": "^4.2.0"
       },
       "devDependencies": {
-        "@playwright/test": "^1.57.0",
+        "@playwright/test": "1.58.0",
         "@vitejs/plugin-vue": "^6.0.0",
         "dotenv": "^17.2.3",
         "typescript": "~5.8.0",
@@ -26,12 +26,15 @@
       }
     },
     "../..": {
-      "version": "0.3.15",
+      "version": "0.3.34",
       "license": "MIT",
+      "bin": {
+        "een-setup-agents": "scripts/setup-agents.ts"
+      },
       "devDependencies": {
         "@eslint/js": "^9.39.2",
         "@marp-team/marp-cli": "^4.2.3",
-        "@playwright/test": "^1.57.0",
+        "@playwright/test": "1.58.0",
         "@types/node": "^25.0.3",
         "@typescript-eslint/eslint-plugin": "^8.51.0",
         "@typescript-eslint/parser": "^8.51.0",
@@ -564,13 +567,13 @@
       "license": "MIT"
     },
     "node_modules/@playwright/test": {
-      "version": "1.57.0",
-      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.57.0.tgz",
-      "integrity": "sha512-6TyEnHgd6SArQO8UO2OMTxshln3QMWBtPGrOCgs3wVEmQmwyuNtB10IZMfmYDE0riwNR1cu4q+pPcxMVtaG3TA==",
+      "version": "1.58.0",
+      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.58.0.tgz",
+      "integrity": "sha512-fWza+Lpbj6SkQKCrU6si4iu+fD2dD3gxNHFhUPxsfXBPhnv3rRSQVd0NtBUT9Z/RhF/boCBcuUaMUSTRTopjZg==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
-        "playwright": "1.57.0"
+        "playwright": "1.58.0"
       },
       "bin": {
         "playwright": "cli.js"
@@ -1415,13 +1418,13 @@
       }
     },
     "node_modules/playwright": {
-      "version": "1.57.0",
-      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.57.0.tgz",
-      "integrity": "sha512-ilYQj1s8sr2ppEJ2YVadYBN0Mb3mdo9J0wQ+UuDhzYqURwSoW4n1Xs5vs7ORwgDGmyEh33tRMeS8KhdkMoLXQw==",
+      "version": "1.58.0",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.58.0.tgz",
+      "integrity": "sha512-2SVA0sbPktiIY/MCOPX8e86ehA/e+tDNq+e5Y8qjKYti2Z/JG7xnronT/TXTIkKbYGWlCbuucZ6dziEgkoEjQQ==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
-        "playwright-core": "1.57.0"
+        "playwright-core": "1.58.0"
       },
       "bin": {
         "playwright": "cli.js"
@@ -1434,9 +1437,9 @@
       }
     },
     "node_modules/playwright-core": {
-      "version": "1.57.0",
-      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.57.0.tgz",
-      "integrity": "sha512-agTcKlMw/mjBWOnD6kFZttAAGHgi/Nw0CZ2o6JqWSbMlI219lAFLZZCyqByTsvVAJq5XA5H8cA6PrvBRpBWEuQ==",
+      "version": "1.58.0",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.58.0.tgz",
+      "integrity": "sha512-aaoB1RWrdNi3//rOeKuMiS65UCcgOVljU46At6eFcOFPFHWtd2weHRRow6z/n+Lec0Lvu0k9ZPKJSjPugikirw==",
       "dev": true,
       "license": "Apache-2.0",
       "bin": {

package/examples/vue-alerts-metrics/package.json

@@ -21,7 +21,7 @@
     "vue-router": "^4.2.0"
   },
   "devDependencies": {
-    "@playwright/test": "^1.57.0",
+    "@playwright/test": "1.58.0",
     "@vitejs/plugin-vue": "^6.0.0",
     "dotenv": "^17.2.3",
     "typescript": "~5.8.0",