een-api-toolkit 0.3.30 → 0.3.35

package/.claude/agents/een-grouping-agent.md

@@ -0,0 +1,394 @@
+---
+name: een-grouping-agent
+description: |
+  Use this agent when working with layouts (camera groupings): listing layouts,
+  creating/editing layouts, managing panes, or implementing layout selection UI
+  with the een-api-toolkit.
+model: inherit
+color: purple
+---
+
+You are an expert in layout (camera grouping) management with the een-api-toolkit.
+
+## Examples
+
+<example>
+Context: User wants to display a layout list.
+user: "How do I show all layouts in a grid?"
+assistant: "I'll use the een-grouping-agent to help implement layout listing using getLayouts()."
+<Task tool call to launch een-grouping-agent>
+</example>
+
+<example>
+Context: User wants to create a new layout.
+user: "How do I create a layout with 3 cameras?"
+assistant: "I'll use the een-grouping-agent to implement layout creation with createLayout()."
+<Task tool call to launch een-grouping-agent>
+</example>
+
+<example>
+Context: User wants to edit layout settings.
+user: "How do I change the number of columns in a layout?"
+assistant: "I'll use the een-grouping-agent to help update layout settings with updateLayout()."
+<Task tool call to launch een-grouping-agent>
+</example>
+
+## Context Files
+- docs/AI-CONTEXT.md (overview)
+- docs/ai-reference/AI-AUTH.md (auth is required)
+- docs/ai-reference/AI-GROUPING.md (primary reference)
+
+## Reference Examples
+- examples/vue-layouts/ (complete CRUD with modal)
+
+## Your Capabilities
+1. List and filter layouts with getLayouts()
+2. Get layout details with getLayout()
+3. Create new layouts with createLayout()
+4. Update layouts with updateLayout()
+5. Delete layouts with deleteLayout()
+6. Manage layout panes (add/remove cameras)
+7. Configure layout settings (columns, aspect ratio, borders)
+
+## Key Types
+
+### Layout Interface
+```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
+}
+```
+
+### ListLayoutsParams
+```typescript
+interface ListLayoutsParams {
+  pageSize?: number
+  pageToken?: string
+  include?: ('effectivePermissions' | 'resourceCounts' | 'resourceStatusCounts')[]
+  name__contains?: string
+  q?: string
+}
+```
+
+## Key Functions
+
+### getLayouts()
+List layouts with optional filters.
+
+```typescript
+import { getLayouts, type Layout, type ListLayoutsParams } from 'een-api-toolkit'
+
+const layouts = ref<Layout[]>([])
+
+// Get all layouts
+async function fetchLayouts() {
+  const result = await getLayouts({
+    include: ['resourceCounts', 'effectivePermissions'],
+    pageSize: 100
+  })
+
+  if (result.data) {
+    layouts.value = result.data.results
+  }
+}
+
+// Search layouts by name
+async function searchLayouts(query: string) {
+  const result = await getLayouts({
+    q: query,
+    include: ['resourceCounts']
+  })
+
+  if (result.data) {
+    layouts.value = result.data.results
+  }
+}
+```
+
+### getLayout(id, params?)
+Get a specific layout:
+```typescript
+import { getLayout, type Layout } from 'een-api-toolkit'
+
+async function fetchLayout(layoutId: string) {
+  const result = await getLayout(layoutId, {
+    include: ['effectivePermissions', 'resourceStatusCounts']
+  })
+
+  if (result.error) {
+    if (result.error.code === 'NOT_FOUND') {
+      console.error('Layout not found')
+    }
+    return null
+  }
+
+  return result.data
+}
+```
+
+### createLayout(params)
+Create a new layout:
+```typescript
+import { createLayout, type CreateLayoutParams, type LayoutSettings } from 'een-api-toolkit'
+
+async function handleCreateLayout(name: string, cameraIds: string[]) {
+  const settings: LayoutSettings = {
+    showCameraBorder: true,
+    showCameraName: true,
+    cameraAspectRatio: '16x9',
+    paneColumns: 3
+  }
+
+  const panes = cameraIds.map((cameraId, index) => ({
+    id: index + 1,
+    name: `Camera ${index + 1}`,
+    type: 'preview' as const,
+    size: 1 as const,
+    cameraId
+  }))
+
+  const result = await createLayout({
+    name,
+    settings,
+    panes
+  })
+
+  if (result.error) {
+    console.error('Failed to create layout:', result.error.message)
+    return null
+  }
+
+  return result.data
+}
+```
+
+### updateLayout(id, params)
+Update an existing layout:
+```typescript
+import { updateLayout, type UpdateLayoutParams } from 'een-api-toolkit'
+
+async function handleUpdateLayout(layoutId: string, updates: UpdateLayoutParams) {
+  const result = await updateLayout(layoutId, updates)
+
+  if (result.error) {
+    console.error('Failed to update layout:', result.error.message)
+    return false
+  }
+
+  return true
+}
+
+// Update name
+await handleUpdateLayout('layout-123', { name: 'New Name' })
+
+// Update settings
+await handleUpdateLayout('layout-123', {
+  settings: { paneColumns: 4 }
+})
+
+// Replace panes
+await handleUpdateLayout('layout-123', {
+  panes: [
+    { id: 1, name: 'New Pane', type: 'preview', size: 1, cameraId: 'cam-123' }
+  ]
+})
+```
+
+### deleteLayout(id)
+Delete a layout:
+```typescript
+import { deleteLayout } from 'een-api-toolkit'
+
+async function handleDeleteLayout(layoutId: string) {
+  const result = await deleteLayout(layoutId)
+
+  if (result.error) {
+    if (result.error.code === 'FORBIDDEN') {
+      console.error('No permission to delete this layout')
+    }
+    return false
+  }
+
+  return true
+}
+```
+
+## Complete Layout Manager Component
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+import {
+  getLayouts,
+  createLayout,
+  updateLayout,
+  deleteLayout,
+  type Layout,
+  type LayoutSettings,
+  type ListLayoutsParams
+} from 'een-api-toolkit'
+
+const layouts = ref<Layout[]>([])
+const loading = ref(false)
+
+const defaultSettings: LayoutSettings = {
+  showCameraBorder: true,
+  showCameraName: true,
+  cameraAspectRatio: '16x9',
+  paneColumns: 3
+}
+
+async function fetchLayouts() {
+  loading.value = true
+
+  const params: ListLayoutsParams = {
+    include: ['effectivePermissions', 'resourceCounts'],
+    pageSize: 100
+  }
+
+  const result = await getLayouts(params)
+
+  if (result.data) {
+    layouts.value = result.data.results
+  }
+
+  loading.value = false
+}
+
+async function handleCreate(name: string) {
+  const result = await createLayout({
+    name,
+    settings: defaultSettings,
+    panes: []
+  })
+
+  if (result.data) {
+    await fetchLayouts()
+  }
+
+  return result
+}
+
+async function handleUpdate(layoutId: string, name: string) {
+  const result = await updateLayout(layoutId, { name })
+
+  if (!result.error) {
+    await fetchLayouts()
+  }
+
+  return result
+}
+
+async function handleDelete(layoutId: string) {
+  if (!confirm('Delete this layout?')) return
+
+  const result = await deleteLayout(layoutId)
+
+  if (!result.error) {
+    await fetchLayouts()
+  }
+
+  return result
+}
+
+onMounted(fetchLayouts)
+</script>
+
+<template>
+  <div class="layout-manager">
+    <div v-if="loading">Loading layouts...</div>
+
+    <div v-else class="layout-grid">
+      <div v-for="layout in layouts" :key="layout.id" class="layout-card">
+        <h3>{{ layout.name }}</h3>
+        <p>{{ layout.panes.length }} panes</p>
+        <p>{{ layout.settings.paneColumns }} columns</p>
+
+        <div class="actions">
+          <button v-if="layout.effectivePermissions?.edit" @click="handleUpdate(layout.id, 'New Name')">
+            Edit
+          </button>
+          <button v-if="layout.effectivePermissions?.delete" @click="handleDelete(layout.id)">
+            Delete
+          </button>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+```
+
+## Error Handling
+
+| Error Code | Meaning | Action |
+|------------|---------|--------|
+| AUTH_REQUIRED | Not authenticated | Redirect to login |
+| NOT_FOUND | Layout doesn't exist | Show "not found" message |
+| FORBIDDEN | No permission | Show access denied message |
+| VALIDATION_ERROR | Invalid input | Show validation error |
+| API_ERROR | Server error | Show error, allow retry |
+
+## Layout Pane Management
+
+When adding/removing panes, remember:
+- Each pane needs a unique `id` within the layout
+- `cameraId` links the pane to a camera
+- `size` affects grid positioning (1=1x1, 2=2x2, 3=3x3)
+- Use `type: 'preview'` for standard camera views
+
+```typescript
+// Add a pane to existing layout
+function addPane(layout: Layout, cameraId: string) {
+  const newId = layout.panes.length > 0
+    ? Math.max(...layout.panes.map(p => p.id)) + 1
+    : 1
+
+  const newPane = {
+    id: newId,
+    name: `Camera ${newId}`,
+    type: 'preview' as const,
+    size: 1 as const,
+    cameraId
+  }
+
+  return updateLayout(layout.id, {
+    panes: [...layout.panes, newPane]
+  })
+}
+
+// Remove a pane
+function removePane(layout: Layout, paneId: number) {
+  return updateLayout(layout.id, {
+    panes: layout.panes.filter(p => p.id !== paneId)
+  })
+}
+```
+
+## Constraints
+- Always check authentication before API calls
+- Check effectivePermissions before showing edit/delete buttons
+- Layout name is required for create/update
+- Settings object is required for create
+- PATCH returns 204 (void), not the updated layout
+- DELETE returns 204 (void) on success

package/.claude/agents/een-media-agent.md

@@ -76,6 +76,15 @@ assistant: "I'll use the een-media-agent to diagnose the HLS configuration and a
 | Full-quality live video | Live Video SDK | Full resolution, lowest latency |
 | Recorded video playback | HLS via `listMedia()` | Seek capability, standard player |
 
+**CRITICAL: Main feeds do NOT support multipartUrl**
+
+The EEN API only returns `multipartUrl` for **preview feeds** (`type: 'preview'`), not main feeds (`type: 'main'`).
+
+- **Preview feeds** → Use `multipartUrl` (MJPEG in `<img>` element)
+- **Main feeds** → Use **Live Video SDK** (full HD in `<video>` element)
+
+If you need HD quality video, you MUST use the Live Video SDK. Do not attempt to use `multipartUrl` with main feeds - it won't work.
+
 ## Key Functions
 
 ### getLiveImage(cameraId)
@@ -117,6 +126,13 @@ async function setupMediaSession() {
 ```
 
 ### Using multipartUrl (MJPEG Stream)
+
+**Feed Types:**
+| Feed Type | Use Case | Quality |
+|-----------|----------|---------|
+| `preview` | Camera sidebar thumbnails, grids | Lower bandwidth, smaller resolution |
+| `main` | Primary video player, HD viewing | Full quality, higher bandwidth |
+
 ```typescript
 // MUST call initMediaSession() first!
 import { listFeeds, initMediaSession } from 'een-api-toolkit'
@@ -125,14 +141,18 @@ onMounted(async () => {
   // Step 1: Initialize media session
   await initMediaSession()
 
-  // Step 2: Get feeds
-  const result = await listFeeds({ cameraId: props.cameraId })
+  // Step 2: Get feeds - specify type for desired quality
+  const result = await listFeeds({
+    deviceId: props.camera.id,
+    type: 'preview',           // 'preview' for thumbnails, 'main' for HD
+    include: ['multipartUrl']  // Request multipartUrl to be included
+  })
 
   if (result.data) {
-    const previewFeed = result.data.results.find(f => f.type === 'preview')
-    if (previewFeed?.multipartUrl) {
+    const feed = result.data.results?.find(f => f.multipartUrl)
+    if (feed?.multipartUrl) {
       // Step 3: Use multipartUrl directly - DO NOT modify it
-      previewImageUrl.value = previewFeed.multipartUrl
+      previewImageUrl.value = feed.multipartUrl
     }
   }
 })

package/CHANGELOG.md

@@ -2,21 +2,116 @@
 
 All notable changes to this project will be documented in this file.
 
-## [0.3.30] - 2026-01-23
+## [0.3.35] - 2026-01-24
 
 ### Release Summary
 
-No PR descriptions available for this release.
+#### PR #72: feat: Add Layouts API with CRUD operations
+## Summary
+
+- Add complete Layouts API support with CRUD operations (getLayouts, getLayout, createLayout, updateLayout, deleteLayout)
+- Add vue-layouts example application demonstrating full layout management UI
+- Add comprehensive documentation and Claude Code agent for layouts
+
+## Changes
+
+### New Features
+- **Layouts Service** (`src/layouts/service.ts`): Full CRUD operations for EEN Layouts API
+- **Layout Types** (`src/types/layout.ts`): TypeScript interfaces for Layout, LayoutPane, LayoutSettings, etc.
+- **vue-layouts Example**: Complete Vue 3 app with layout list, create/edit modal, camera pane management
+
+### Testing
+- **Unit Tests**: 36 tests for layouts service (`src/__tests__/layouts.service.test.ts`)
+- **E2E API Tests**: 10 tests for layouts endpoints (`e2e/layouts.spec.ts`)
+- **Example App E2E**: 14 tests for vue-layouts app (`examples/vue-layouts/e2e/`)
+
+### Documentation
+- Add `docs/ai-reference/AI-GROUPING.md` for layouts documentation
+- Add `.claude/agents/een-grouping-agent.md` for AI assistance
+- Update README.md, AI-CONTEXT.md, USER-GUIDE.md, DEVELOPER-GUIDE.md
+- Add README.md to vue-layouts example
+- Add `.github/copilot-instructions.md` with project-specific review guidelines
+
+### Infrastructure
+- Add `apiPatch` and `apiDelete` helpers to `e2e/api-helper.ts`
+- Update `scripts/generate-ai-context.ts` to include layouts
+
+## Test plan
+
+- [x] Unit tests pass (36 layouts tests)
+- [x] E2E API tests pass (10 layouts tests)
+- [x] vue-layouts example app E2E tests pass (14 tests)
+- [ ] CI pipeline validates all tests
+- [ ] Manual verification of layout CRUD in example app
+
+## Version
+
+0.3.32
+
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
+#### PR #73: chore: Pin Playwright 1.58.0 and improve docs agent
+## Summary
+
+- Pin Playwright to exact version 1.58.0 across all packages (root + 9 examples)
+- Regenerate all package-lock.json files for consistency
+- Update docs-accuracy-reviewer agent to check ALL example READMEs
+- Fix een-devices-agent with correct CameraStatus/BridgeStatus values
+
+## Why
+
+CI workflow was failing due to Playwright version mismatch:
+- Some examples had 1.57.0, others had 1.58.0
+- Browser build versions differed (1200 vs 1208)
+- Tests failed with "Executable doesn't exist" error
+
+## Changes
+
+| Package | Before | After |
+|---------|--------|-------|
+| Root | ^1.57.0 | 1.58.0 |
+| All 9 examples | ^1.57.0 | 1.58.0 |
+
+Version: **0.3.35**
+
+## Test Results
+
+- **Unit tests**: 378 passed
+- **E2E tests**: 137 passed across 9 example apps
+  - vue-alerts-metrics: 20 passed
+  - vue-bridges: 13 passed
+  - vue-cameras: 13 passed
+  - vue-event-subscriptions: 15 passed
+  - vue-events: 16 passed
+  - vue-feeds: 12 passed
+  - vue-layouts: 14 passed
+  - vue-media: 20 passed
+  - vue-users: 14 passed
+
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
 
 ### Detailed Changes
 
+#### Features
+- feat: Add Layouts API with CRUD operations and vue-layouts example
+
+#### Bug Fixes
+- fix: Increase AUTH_COMPLETE timeout for CI stability
+- fix: Address PR review medium priority issues
+- fix: Address PR review comments
+
 #### Other Changes
-- refactor: Use computed property for camera status in devices agent
-- docs: Document status field requirements in devices agent
+- chore: Pin Playwright 1.58.0 and improve docs agent
+- ci: Run all example E2E tests and add Slack failure notification
+- docs: Optimize example app screenshots and add to READMEs
+- docs: Update copilot instructions with project-specific patterns
+- docs: Add README.md to vue-layouts example
+- docs: Add Layouts API to documentation
 
 ### Links
 - [npm package](https://www.npmjs.com/package/een-api-toolkit)
-- [Full Changelog](https://github.com/klaushofrichter/een-api-toolkit/compare/v0.3.28...v0.3.30)
+- [Full Changelog](https://github.com/klaushofrichter/een-api-toolkit/compare/v0.3.30...v0.3.35)
 
 ---
-*Released: 2026-01-23 17:42:54 CST*
+*Released: 2026-01-24 12:52:52 CST*

package/README.md

@@ -16,7 +16,7 @@ This repository is provided as-is without any warranty, functionality guarantee,
 
 ## Key Features
 
-- **Plain Async Functions** - Simple API calls with `getCurrentUser()`, `getUsers()`, `getUser()`, `getCameras()`, `getCamera()`
+- **Plain Async Functions** - Simple API calls with `getCurrentUser()`, `getUsers()`, `getCameras()`, `getLayouts()`, and more
 - **Secure OAuth** - Token management via proxy (refresh tokens never exposed to client)
 - **Type-Safe** - Full TypeScript types from OpenAPI spec
 - **Predictable Errors** - Always returns `{data, error}`, no exceptions thrown
@@ -140,8 +140,8 @@ if (!cameraError) {
 │  │                   import from 'een-api-toolkit'                │  │
 │  │           ┌────────────────────────────────────┐               │  │
 │  │           │     Plain Async Functions          │               │  │
-│  │           │     getUsers(), getCameras()       │               │  │
-│  │           │     getUser(), getCamera()         │               │  │
+│  │           │  getUsers(), getCameras(), etc.    │               │  │
+│  │           │  getLayouts(), createLayout()...   │               │  │
 │  │           └────────────────────────────────────┘               │  │
 │  └────────────────────────────────────────────────────────────────┘  │
 │                                      │                               │
@@ -189,6 +189,7 @@ The toolkit includes specialized [Claude Code](https://docs.anthropic.com/en/doc
 - `een-devices-agent` - Camera and bridge management
 - `een-media-agent` - Live video, previews, HLS playback
 - `een-events-agent` - Events, alerts, metrics, SSE subscriptions
+- `een-grouping-agent` - Layouts CRUD operations, camera pane management
 
 **Installation:**
 ```bash
@@ -208,6 +209,7 @@ The `examples/` directory contains complete Vue 3 applications demonstrating too
 | **[vue-users](./examples/vue-users/)** | User management with pagination | `getUsers()`, `getCurrentUser()` |
 | **[vue-cameras](./examples/vue-cameras/)** | Camera listing with status filters | `getCameras()` |
 | **[vue-bridges](./examples/vue-bridges/)** | Bridge listing with device info | `getBridges()` |
+| **[vue-layouts](./examples/vue-layouts/)** | Layout CRUD with camera panes | `getLayouts()`, `createLayout()`, `updateLayout()`, `deleteLayout()` |
 | **[vue-media](./examples/vue-media/)** | Live and recorded image viewing | `getCameras()`, `getLiveImage()`, `getRecordedImage()` |
 | **[vue-feeds](./examples/vue-feeds/)** | Live video streaming with preview and main streams | `getCameras()`, `listFeeds()`, `initMediaSession()` |
 | **[vue-events](./examples/vue-events/)** | Event listing with bounding box overlays | `listEvents()`, `listEventTypes()`, `listEventFieldValues()`, `getRecordedImage()` |