een-api-toolkit 0.3.82 → 0.3.91

package/docs/AI-CONTEXT.md

@@ -1,6 +1,6 @@
 # EEN API Toolkit - AI Reference
 
-> **Version:** 0.3.82
+> **Version:** 0.3.91
 >
 > This documentation is optimized for AI assistants. It provides focused, domain-specific
 > references to help you understand and use the een-api-toolkit efficiently.
@@ -22,6 +22,7 @@
 | Events, alerts, metrics, SSE | [AI-EVENTS.md](./ai-reference/AI-EVENTS.md) | ~3.5K |
 | Automation rules, alert actions | [AI-AUTOMATIONS.md](./ai-reference/AI-AUTOMATIONS.md) | ~4K |
 | Jobs, exports, files, downloads | [AI-JOBS.md](./ai-reference/AI-JOBS.md) | ~3.5K |
+| PTZ camera controls, presets | [AI-PTZ.md](./ai-reference/AI-PTZ.md) | ~2K |
 
 ## Specialized Agents
 
@@ -38,6 +39,7 @@ Specialized agents are available in `.claude/agents/` for domain-specific tasks:
 | `een-events-agent` | Events, alerts, metrics, real-time SSE subscriptions |
 | `een-automations-agent` | Automation rules, alert condition rules, alert actions |
 | `een-jobs-agent` | Jobs, exports, files, downloads, video export workflows |
+| `een-ptz-agent` | PTZ camera controls, presets, click-to-center |
 
 **How to Use Agents:**
 

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

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

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

@@ -1,6 +1,6 @@
 # Automations API - EEN API Toolkit
 
-> **Version:** 0.3.82
+> **Version:** 0.3.91
 >
 > Complete reference for automation rules and alert actions.
 > Load this document when working with automated alert workflows.

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

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

package/docs/ai-reference/AI-EVENT-DATA-SCHEMAS.md

@@ -1,6 +1,6 @@
 # Event Type to Data Schemas Mapping - EEN API Toolkit
 
-> **Version:** 0.3.82
+> **Version:** 0.3.91
 >
 > Complete reference for event type to data schema mappings.
 > Load this document when building dynamic event queries with the `include` parameter.

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

@@ -1,6 +1,6 @@
 # Events, Alerts & Real-Time Streaming - EEN API Toolkit
 
-> **Version:** 0.3.82
+> **Version:** 0.3.91
 >
 > Complete reference for events, alerts, metrics, and SSE subscriptions.
 > Load this document when implementing event-driven features.

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

@@ -1,6 +1,6 @@
 # Layouts API - EEN API Toolkit
 
-> **Version:** 0.3.82
+> **Version:** 0.3.91
 >
 > Complete reference for layout management (camera grouping).
 > Load this document when working with layouts.

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

@@ -1,6 +1,6 @@
 # Jobs, Exports, Files & Downloads - EEN API Toolkit
 
-> **Version:** 0.3.82
+> **Version:** 0.3.91
 >
 > Complete reference for async jobs, video exports, and file management.
 > Load this document when implementing export workflows or file downloads.

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

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

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

@@ -0,0 +1,158 @@
+# PTZ Camera Controls
+
+> **Version:** 0.3.91
+>
+> Pan/Tilt/Zoom camera control: position, movement, presets, and automation.
+
+---
+
+## API Endpoints
+
+| Function | Method | Endpoint | Returns |
+|----------|--------|----------|---------|
+| `getPtzPosition(cameraId)` | GET | `/cameras/{cameraId}/ptz/position` | `Result<PtzPosition>` |
+| `movePtz(cameraId, move)` | PUT | `/cameras/{cameraId}/ptz/position` | `Result<void>` |
+| `getPtzSettings(cameraId)` | GET | `/cameras/{cameraId}/ptz/settings` | `Result<PtzSettings>` |
+| `updatePtzSettings(cameraId, settings)` | PATCH | `/cameras/{cameraId}/ptz/settings` | `Result<void>` |
+
+## Types
+
+### PtzPosition
+```typescript
+interface PtzPosition {
+  x?: number  // Pan (horizontal)
+  y?: number  // Tilt (vertical)
+  z?: number  // Zoom level
+}
+```
+
+### PtzMove (discriminated union)
+```typescript
+type PtzMove = PtzPositionMove | PtzDirectionMove | PtzCenterOnMove
+
+// Absolute position
+interface PtzPositionMove {
+  moveType: 'position'
+  x?: number; y?: number; z?: number
+}
+
+// Relative direction
+interface PtzDirectionMove {
+  moveType: 'direction'
+  direction: PtzDirection[]  // 'up' | 'down' | 'left' | 'right' | 'in' | 'out'
+  stepSize?: PtzStepSize     // 'small' | 'medium' | 'large'
+}
+
+// Center on point in frame
+interface PtzCenterOnMove {
+  moveType: 'centerOn'
+  relativeX: number  // 0.0 (left) to 1.0 (right)
+  relativeY: number  // 0.0 (top) to 1.0 (bottom)
+}
+```
+
+### PtzSettings & PtzSettingsUpdate
+```typescript
+interface PtzSettings {
+  presets: PtzPreset[]
+  homePreset: string | null
+  mode: PtzMode           // 'homeReturn' | 'tour' | 'manualOnly'
+  autoStartDelay: number  // seconds
+}
+
+interface PtzPreset {
+  name: string
+  position: PtzPosition
+  timeAtPreset: number    // seconds at preset during tour
+}
+
+interface PtzSettingsUpdate {
+  presets?: PtzPreset[]
+  homePreset?: string | null
+  mode?: PtzMode
+  autoStartDelay?: number
+}
+```
+
+## Usage Examples
+
+### Get Position
+```typescript
+import { getPtzPosition } from 'een-api-toolkit'
+
+const { data, error } = await getPtzPosition('camera-123')
+if (data) {
+  console.log(`Pan: ${data.x}, Tilt: ${data.y}, Zoom: ${data.z}`)
+}
+```
+
+### Move Camera
+```typescript
+import { movePtz } from 'een-api-toolkit'
+
+// Absolute position
+await movePtz('camera-123', { moveType: 'position', x: 0.5, y: -0.3, z: 2.0 })
+
+// Direction with step size
+await movePtz('camera-123', {
+  moveType: 'direction', direction: ['up', 'left'], stepSize: 'medium'
+})
+
+// Click-to-center on video frame
+await movePtz('camera-123', { moveType: 'centerOn', relativeX: 0.75, relativeY: 0.5 })
+```
+
+### Manage Presets
+```typescript
+import { getPtzSettings, updatePtzSettings, getPtzPosition } from 'een-api-toolkit'
+
+// Read presets
+const { data: settings } = await getPtzSettings('camera-123')
+
+// Save current position as preset
+const { data: pos } = await getPtzPosition('camera-123')
+if (pos && settings) {
+  await updatePtzSettings('camera-123', {
+    presets: [...settings.presets, { name: 'Gate', position: pos, timeAtPreset: 10 }],
+    homePreset: 'Gate'
+  })
+}
+
+// Change mode
+await updatePtzSettings('camera-123', { mode: 'tour', autoStartDelay: 30 })
+```
+
+### Click-to-Center Pattern
+```typescript
+function handleVideoClick(event: MouseEvent) {
+  const video = event.currentTarget as HTMLVideoElement
+  const rect = video.getBoundingClientRect()
+  const relativeX = (event.clientX - rect.left) / rect.width
+  const relativeY = (event.clientY - rect.top) / rect.height
+  movePtz(cameraId, { moveType: 'centerOn', relativeX, relativeY })
+}
+```
+
+## Error Handling
+
+| Error Code | Meaning | Action |
+|------------|---------|--------|
+| AUTH_REQUIRED | Not authenticated | Redirect to login |
+| NOT_FOUND | Camera not found or no PTZ | Show message |
+| FORBIDDEN | No permission | Show access denied |
+| VALIDATION_ERROR | Empty camera ID | Fix input |
+
+---
+
+## Reference Examples
+
+- `examples/vue-ptz/` - Complete PTZ control app with live video
+
+
+## See Also
+
+- [AI-AUTH.md](./AI-AUTH.md)
+- [AI-DEVICES.md](./AI-DEVICES.md)
+- [AI-MEDIA.md](./AI-MEDIA.md)
+
+

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

@@ -1,6 +1,6 @@
 # Vue 3 Application Setup - EEN API Toolkit
 
-> **Version:** 0.3.82
+> **Version:** 0.3.91
 >
 > 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.82
+> **Version:** 0.3.91
 >
 > Complete reference for user management.
 > Load this document when working with user data.

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

@@ -0,0 +1,4 @@
+VITE_PROXY_URL=http://127.0.0.1:8787
+VITE_EEN_CLIENT_ID=your-client-id
+VITE_REDIRECT_URI=http://127.0.0.1:3333
+VITE_DEBUG=true

package/examples/vue-ptz/README.md

@@ -0,0 +1,221 @@
+# EEN API Toolkit - Vue PTZ Example
+
+A Vue 3 example demonstrating PTZ (Pan/Tilt/Zoom) camera control using the een-api-toolkit, including live video streaming, directional movement, click-to-center, absolute positioning, and preset management.
+
+![PTZ Screenshot](screenshot-ptz.png)
+
+## Storage Strategy: sessionStorage
+
+This example uses the `sessionStorage` storage strategy for balanced security. This means:
+
+- **Per-tab isolation** - each browser tab has its own session
+- **Page refresh preserves session** - tokens survive refresh within the same tab
+- **Tab close clears session** - closing the tab removes tokens
+- **New tabs require login** - opening a new tab requires separate authentication
+
+This is a good balance between security (limiting XSS blast radius) and user experience (page refresh doesn't require re-login).
+
+## Features Demonstrated
+
+- OAuth authentication flow (login, callback, logout)
+- Protected routes with navigation guards
+- PTZ camera discovery (filters cameras by PTZ capability)
+- Live video streaming via `@een/live-video-web-sdk`
+- Click-to-center on the live video feed
+- Direction pad with pan/tilt/zoom controls
+- Absolute position input (pan, tilt, zoom, field of view)
+- Current position display with auto-refresh
+- Preset management (list, recall, create, delete, set home)
+- Real-time API call logging
+
+## Pages Overview
+
+### Home Page
+The landing page that displays a welcome message and login prompt when not authenticated. Shows the available toolkit functions and their descriptions.
+
+### PTZ Control
+The main control page with a two-column layout: live video on the left and PTZ controls on the right.
+
+**Components:**
+
+- **CameraSelector** - Discovers PTZ-capable cameras by checking each camera's capabilities and auto-selects the first one
+- **LiveVideoPlayer** - Streams live video using the EEN Live Video Web SDK with click-to-center support
+- **PositionDisplay** - Shows the current pan/tilt/zoom/field-of-view values with auto-refresh
+- **DirectionPad** - Provides directional movement buttons (up/down/left/right, zoom in/out) and a home button
+- **PositionInput** - Allows entering absolute pan/tilt/zoom/FOV values to move the camera
+- **PresetManager** - Lists, recalls, creates, and deletes PTZ presets; designates a home preset
+- **ApiLog** - Displays a real-time log of API calls made by the toolkit
+
+## APIs Used Summary
+
+| API Function | Component | Purpose |
+|--------------|-----------|---------|
+| `getCameras()` | CameraSelector | List available cameras |
+| `getCamera()` | CameraSelector | Check PTZ capability per camera |
+| `getPtzPosition()` | PositionDisplay | Read current camera position |
+| `movePtz()` | DirectionPad, PositionInput, LiveVideoPlayer, PresetManager | Move camera (direction, position, centerOn) |
+| `getPtzSettings()` | PresetManager | Retrieve presets and automation settings |
+| `updatePtzSettings()` | PresetManager | Create/delete presets, set home preset |
+| `getCurrentUser()` | App.vue | Fetch logged-in user profile for header display |
+| `useAuthStore()` | Multiple | Authentication state management |
+| `getAuthUrl()` | Login | Generate OAuth login URL |
+| `handleAuthCallback()` | Callback | Process OAuth callback |
+| `revokeToken()` | Logout | Revoke authentication token on logout |
+| `initEenToolkit()` | App initialization | Configure toolkit settings |
+| `getStorageStrategy()` | Home | Get the current storage strategy |
+| `STORAGE_STRATEGY_DESCRIPTIONS` | Home | Human-readable storage strategy descriptions |
+
+## 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-ptz/`):
+
+2. Copy the environment file:
+   ```bash
+   # From examples/vue-ptz/
+   cp .env.example .env
+   ```
+
+3. Edit `.env` with your EEN credentials:
+   ```env
+   VITE_EEN_CLIENT_ID=your-client-id
+   VITE_PROXY_URL=http://127.0.0.1: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-ptz/
+   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 and user info
+├── router/
+│   └── index.ts         # Vue Router with auth guards
+├── composables/
+│   └── useApiLog.ts     # Shared API call log state
+├── components/
+│   ├── CameraSelector.vue    # PTZ camera discovery and selection
+│   ├── LiveVideoPlayer.vue   # Live video stream with click-to-center
+│   ├── DirectionPad.vue      # Directional movement controls
+│   ├── PositionDisplay.vue   # Current position readout
+│   ├── PositionInput.vue     # Absolute position input form
+│   ├── PresetManager.vue     # Preset CRUD and home preset
+│   └── ApiLog.vue            # Real-time API call log
+└── views/
+    ├── Home.vue         # Home page with login prompt
+    ├── Login.vue        # OAuth login redirect
+    ├── Callback.vue     # OAuth callback handler
+    ├── PtzControl.vue   # Main PTZ control page
+    └── Logout.vue       # Logout handler
+```
+
+## Key Code Examples
+
+### Moving a PTZ Camera (DirectionPad.vue)
+
+```typescript
+import { movePtz } from 'een-api-toolkit'
+
+// Move camera using relative direction
+await movePtz(cameraId, {
+  moveType: 'direction',
+  direction: ['right'],
+  stepSize: 'medium'
+})
+
+// Move camera to absolute position
+await movePtz(cameraId, {
+  moveType: 'position',
+  x: 0.5, y: -0.3, z: 2.0
+})
+```
+
+### Click-to-Center (LiveVideoPlayer.vue)
+
+```typescript
+import { movePtz } from 'een-api-toolkit'
+
+// Click coordinates on the video trigger centerOn move (0.0 to 1.0)
+const relativeX = (event.clientX - rect.left) / rect.width
+const relativeY = (event.clientY - rect.top) / rect.height
+await movePtz(cameraId, { moveType: 'centerOn', relativeX, relativeY })
+```
+
+### Managing Presets (PresetManager.vue)
+
+```typescript
+import { getPtzSettings, updatePtzSettings, getPtzPosition } from 'een-api-toolkit'
+
+// List presets
+const result = await getPtzSettings(cameraId)
+const presets = result.data?.presets || []
+
+// Recall a preset (move to its saved position)
+await movePtz(cameraId, { moveType: 'position', x: preset.position.x, y: preset.position.y, z: preset.position.z })
+
+// Save current position as a new preset (fetch existing presets first to avoid overwriting)
+const { data: pos } = await getPtzPosition(cameraId)
+if (pos && result.data) {
+  await updatePtzSettings(cameraId, {
+    presets: [...result.data.presets, { name: 'New Preset', position: pos, timeAtPreset: 10 }]
+  })
+}
+```
+
+### Reading Camera Position (PositionDisplay.vue)
+
+```typescript
+import { getPtzPosition } from 'een-api-toolkit'
+
+const result = await getPtzPosition(cameraId)
+if (result.data) {
+  const { x, y, z } = result.data  // pan, tilt, zoom
+}
+```
+
+### PTZ Camera Discovery (CameraSelector.vue)
+
+```typescript
+import { getCameras } from 'een-api-toolkit'
+
+// Fetch all cameras with capabilities in a single paginated request
+const ptzCameras = []
+let pageToken: string | undefined
+do {
+  const result = await getCameras({ pageSize: 100, include: ['capabilities'], pageToken })
+  for (const cam of result.data?.results || []) {
+    if (cam.capabilities?.ptz?.capable) ptzCameras.push(cam)
+  }
+  pageToken = result.data?.nextPageToken ?? undefined
+} while (pageToken)
+```

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

@@ -0,0 +1,58 @@
+import { test, expect } from '@playwright/test'
+
+test.describe('vue-ptz example app', () => {
+  test('home page shows login button when not authenticated', async ({ page }) => {
+    await page.goto('/')
+
+    // Should show the home page
+    await expect(page.getByRole('heading', { name: 'Welcome to the EEN PTZ Control Example' })).toBeVisible()
+
+    // Should show "not authenticated" state with login button
+    await expect(page.getByTestId('not-authenticated')).toBeVisible()
+    await expect(page.getByTestId('login-button')).toBeVisible()
+    await expect(page.getByText('Please log in to control PTZ cameras')).toBeVisible()
+  })
+
+  test('login button navigates to login page', async ({ page }) => {
+    await page.goto('/')
+
+    await page.getByTestId('login-button').click()
+
+    await expect(page).toHaveURL('/login')
+    await expect(page.getByRole('heading', { name: 'Login' })).toBeVisible()
+    await expect(page.getByText('Click the button below to authenticate with Eagle Eye Networks')).toBeVisible()
+  })
+
+  test('ptz route redirects to login when not authenticated', async ({ page }) => {
+    await page.goto('/ptz')
+
+    // Should redirect to login page (auth guard)
+    await expect(page).toHaveURL('/login')
+  })
+
+  test('navigation links work correctly', async ({ page }) => {
+    await page.goto('/')
+
+    // Check navigation is present
+    await expect(page.getByRole('navigation')).toBeVisible()
+
+    // Navigate to login via nav link (use testid to be specific)
+    await page.getByTestId('nav-login').click()
+    await expect(page).toHaveURL('/login')
+
+    // Navigate back home
+    await page.getByRole('link', { name: 'Home' }).click()
+    await expect(page).toHaveURL('/')
+  })
+
+  test('about section displays toolkit function list', async ({ page }) => {
+    await page.goto('/')
+
+    // Check for the function descriptions
+    await expect(page.getByText('getCameras()')).toBeVisible()
+    await expect(page.getByText('getPtzPosition()')).toBeVisible()
+    await expect(page.getByText('movePtz()')).toBeVisible()
+    await expect(page.getByText('getPtzSettings()')).toBeVisible()
+    await expect(page.getByText('updatePtzSettings()')).toBeVisible()
+  })
+})