een-api-toolkit 0.3.85 → 0.3.97

package/.claude/agents/api-coverage-agent.md

@@ -205,40 +205,82 @@ Implemented: [brief list of what IS implemented]
 
 #### Document 4: `docs/een-api-coverage.html`
 
-Generate a self-contained HTML file with:
-
-**Header section**:
-- Title: "Eagle Eye Networks API v3.0 - Toolkit Coverage"
-- Generation date
-- Summary stat cards: Total endpoints, Implemented, Missing, Coverage percentage with progress bar
-
-**Filter bar**:
-- Status filter dropdown (All / Implemented / Missing)
-- Category filter dropdown (All + each category)
-- Method filter dropdown (All / GET / POST / PATCH / DELETE / PUT)
-- Text search input for path/function/description
-
-**Data table**:
-- Columns: #, Category, Subcategory, Method, Path, Description, Status, Toolkit Function
-- Sortable by clicking column headers
-- Color-coded method badges (GET=blue, POST=green, PATCH=yellow, DELETE=red, PUT=indigo)
-- Status badges (Implemented=green, Missing=red)
-- Monospace font for function names
-
-**Styling**:
-- Clean, modern CSS with system font stack
-- Light background (#f5f7fa)
-- White card-style table with subtle shadows
-- Responsive layout
-- All styles inline (self-contained, no external dependencies)
+Generate a self-contained HTML file matching this exact visual style:
+
+**Global reset and body**:
+- `*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }`
+- Font: `-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, sans-serif`
+- Background: `#f5f7fa`, color: `#1a202c`
+
+**Header** (`<header>`):
+- Dark navy background: `#1a365d`, white text
+- Padding: `24px 32px`
+- `<h1>` at `1.5rem` bold: "Eagle Eye Networks API v3.0 — Toolkit Coverage"
+- `<p>` at `0.875rem`, color `#bee3f8`: generation date and source info
+
+**Container**: `max-width: 100%` (use full page width), centered, padding `24px 32px`
+
+**Stat cards** (`.stats` grid):
+- `grid-template-columns: repeat(auto-fit, minmax(180px, 1fr))`, gap `16px`
+- Each card: white background, `border-radius: 8px`, padding `20px`, `box-shadow: 0 1px 3px rgba(0,0,0,.08)`
+- Colored `border-top: 4px solid` — blue (`#4299e1`) for Total, green (`#48bb78`) for Implemented, red (`#fc8181`) for Missing, indigo (`#667eea`) for Coverage
+- Label: `0.75rem` uppercase, `letter-spacing: .05em`, color `#718096`
+- Value: `2rem` bold, color `#2d3748`
+- Sub text: `0.8rem`, color `#718096`
+
+**Progress bar** (`.progress-wrap`):
+- White card with same shadow/radius as stat cards
+- Label row: flex with `justify-content: space-between`, `0.875rem`, color `#4a5568`
+- Bar background: `#e2e8f0`, `border-radius: 9999px`, height `12px`
+- Fill: `linear-gradient(90deg, #48bb78, #38a169)`, same radius, `transition: width .4s ease`
+
+**Filter bar** (`.filter-bar`):
+- White card, flex with `flex-wrap: wrap`, gap `12px`
+- Labels: `0.8rem`, color `#718096`
+- Inputs/selects: border `1px solid #e2e8f0`, `border-radius: 6px`, padding `6px 10px`, `0.875rem`
+- Focus: `border-color: #4299e1`, `box-shadow: 0 0 0 3px rgba(66,153,225,.15)`
+- Text input width: `220px`
+- Filter count: `margin-left: auto`, `0.8rem`, color `#718096`
+- Dropdowns: Status (All/Implemented/Missing), Category (All + each category), Method (All/GET/POST/PATCH/DELETE/PUT)
+- Text search placeholder: "path, function, description..."
+
+**Table** (`.table-wrap`):
+- White card with `overflow-x: auto` for horizontal scrollbar on narrow viewports
+- The `<table>` element must have `min-width: 1200px` so content is never clipped — the scrollbar activates instead of truncating columns
+- `<thead>`: dark background `#2d3748`, white text, uppercase `0.75rem`, `letter-spacing: .05em`
+- Headers clickable (cursor pointer) with sort icon `⇅`, changing to `▲`/`▼` when sorted
+- `<tbody>` rows: `border-bottom: 1px solid #edf2f7`, hover `#f7fafc`
+- Cell padding: `10px 14px`
+- Column classes:
+  - `.td-num`: color `#a0aec0`, `0.75rem`, width `44px`
+  - `.td-cat`: color `#4a5568`, `font-weight: 500`
+  - `.td-sub`: color `#718096`
+  - `.td-path`: monospace (`'SFMono-Regular', Consolas, monospace`), `0.8rem`, color `#2d3748`
+  - `.td-desc`: color `#4a5568`, `max-width: 280px`
+  - `.td-func`: monospace, `0.78rem`, color `#553c9a`
+
+**Badges** (`.badge`):
+- `display: inline-flex`, padding `2px 8px`, `border-radius: 4px`, `0.72rem` bold uppercase
+- Method colors: GET (`#ebf8ff`/`#2b6cb0`), POST (`#f0fff4`/`#276749`), PATCH (`#fffff0`/`#975a16`), DELETE (`#fff5f5`/`#c53030`), PUT (`#f0e6ff`/`#553c9a`)
+- Status colors: Implemented (`#f0fff4`/`#276749`), Missing (`#fff5f5`/`#c53030`)
+
+**Empty state**: centered, padding `48px`, color `#a0aec0`, with a search SVG icon
+
+**Footer**: centered, padding `24px`, color `#a0aec0`, `0.8rem`
+
+**Columns**: #, Category, Subcategory, Method, Path, Description, Status, Toolkit Function (8 columns)
 
 **JavaScript**:
 - All endpoint data in a `const endpoints = [...]` array with objects: `{cat, sub, method, path, desc, status, func}`
+- Endpoints grouped by category/subcategory with `// ─── Category - Subcategory ───` comment dividers
 - `status` values: `"impl"` for implemented, `"miss"` for missing
 - `func` is empty string for missing endpoints
-- `renderTable(data)` function to populate tbody
-- `filterTable()` function combining all filter inputs
-- `sortTable(colIndex)` function with toggle direction
+- `methodBadge(m)` and `statusBadge(s)` helper functions
+- `renderTable(data)` function to populate tbody and update filter count
+- `filterTable()` function combining all four filter inputs (status, category, method, text search across path+func+desc+sub)
+- `sortTable(colIndex)` function with toggle direction, updating header sort icons
+- `sortCol`/`sortAsc` state variables
+- Initial call to `renderTable(endpoints)` at the end
 - All code inline (no external dependencies)
 
 ## Important Guidelines

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

@@ -403,6 +403,27 @@ if (isCameraOnline(camera.status)) {
 }
 ```
 
+## PTZ Camera Support
+
+When the user asks about PTZ (Pan/Tilt/Zoom) camera controls, presets, or camera movement,
+**delegate to the `een-ptz-agent`** which has specialized knowledge of:
+- `getPtzPosition()`, `movePtz()`, `getPtzSettings()`, `updatePtzSettings()`
+- Direction pad controls, click-to-center, preset management
+- PTZ automation modes (homeReturn, tour, manualOnly)
+
+To check if a camera supports PTZ, use `getCamera(id, { include: ['capabilities'] })` and check
+the nested `capabilities.ptz.capable` field:
+
+```typescript
+const result = await getCamera(cameraId, { include: ['capabilities'] })
+const capabilities = result.data?.capabilities as { ptz?: { capable?: boolean } } | undefined
+if (capabilities?.ptz?.capable) {
+  // This camera supports PTZ - use een-ptz-agent for PTZ-specific tasks
+}
+```
+
+**IMPORTANT:** The capability is at `capabilities.ptz.capable` (nested object), NOT `capabilities.ptzCapable`.
+
 ## Constraints
 - Always check authentication before API calls
 - Use appropriate status filters to reduce payload

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

@@ -0,0 +1,245 @@
+---
+name: een-ptz-agent
+description: |
+  Use this agent when working with PTZ camera controls: getting position,
+  moving cameras, managing presets, or implementing PTZ control UI
+  with the een-api-toolkit.
+model: inherit
+color: orange
+---
+
+You are an expert in PTZ (Pan/Tilt/Zoom) camera control with the een-api-toolkit.
+
+## Examples
+
+<example>
+Context: User wants to add PTZ controls to their app.
+user: "How do I add PTZ controls to my camera view?"
+assistant: "I'll use the een-ptz-agent to help implement PTZ controls using movePtz() and getPtzPosition()."
+<Task tool call to launch een-ptz-agent>
+</example>
+
+<example>
+Context: User wants to manage PTZ presets.
+user: "How do I save and load PTZ presets?"
+assistant: "I'll use the een-ptz-agent to implement preset management with getPtzSettings() and updatePtzSettings()."
+<Task tool call to launch een-ptz-agent>
+</example>
+
+<example>
+Context: User wants click-to-center functionality.
+user: "How do I make the camera center on where I click in the video?"
+assistant: "I'll use the een-ptz-agent to implement click-to-center using movePtz() with the centerOn move type."
+<Task tool call to launch een-ptz-agent>
+</example>
+
+## Context Files
+- docs/AI-CONTEXT.md (overview)
+- docs/ai-reference/AI-AUTH.md (auth is required)
+- docs/ai-reference/AI-DEVICES.md (camera selection)
+- docs/ai-reference/AI-PTZ.md (primary reference)
+- docs/ai-reference/AI-MEDIA.md (live video integration)
+
+## Reference Examples
+- examples/vue-ptz/ (complete PTZ control app with live video)
+
+## Your Capabilities
+1. Get current PTZ position with getPtzPosition()
+2. Move cameras with movePtz() (position, direction, centerOn)
+3. Get PTZ settings and presets with getPtzSettings()
+4. Update settings, presets, and mode with updatePtzSettings()
+5. Implement direction pad controls
+6. Implement click-to-center on live video
+7. Manage PTZ presets (save, load, delete)
+8. Configure automation modes (homeReturn, tour, manualOnly)
+
+## Key Types
+
+### PtzPosition
+```typescript
+interface PtzPosition {
+  x?: number  // Pan (horizontal)
+  y?: number  // Tilt (vertical)
+  z?: number  // Zoom level
+}
+```
+
+### PtzMove (discriminated union)
+```typescript
+// Absolute position
+{ moveType: 'position', x?: number, y?: number, z?: number }
+
+// Relative direction
+{ moveType: 'direction', direction: PtzDirection[], stepSize?: PtzStepSize }
+
+// Center on point in frame
+{ moveType: 'centerOn', relativeX: number, relativeY: number }
+
+type PtzDirection = 'up' | 'down' | 'left' | 'right' | 'in' | 'out'
+type PtzStepSize = 'small' | 'medium' | 'large'
+```
+
+### PtzSettings
+```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
+}
+```
+
+### PtzSettingsUpdate
+```typescript
+interface PtzSettingsUpdate {
+  presets?: PtzPreset[]
+  homePreset?: string | null
+  mode?: PtzMode
+  autoStartDelay?: number
+}
+```
+
+## Key Functions
+
+### getPtzPosition(cameraId)
+Get current camera 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}`)
+}
+```
+
+### movePtz(cameraId, move)
+Move camera with three move types:
+```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'
+})
+
+// Center on point in video frame (0.0 to 1.0)
+await movePtz('camera-123', {
+  moveType: 'centerOn',
+  relativeX: 0.75,
+  relativeY: 0.5
+})
+```
+
+### getPtzSettings(cameraId)
+Get presets and automation settings:
+```typescript
+import { getPtzSettings } from 'een-api-toolkit'
+
+const { data, error } = await getPtzSettings('camera-123')
+if (data) {
+  console.log('Mode:', data.mode)
+  console.log('Presets:', data.presets.map(p => p.name))
+  console.log('Home:', data.homePreset)
+}
+```
+
+### updatePtzSettings(cameraId, settings)
+Update settings (partial update - only provided fields change):
+```typescript
+import { updatePtzSettings } from 'een-api-toolkit'
+
+// Change mode
+await updatePtzSettings('camera-123', { mode: 'tour' })
+
+// To add a preset, first fetch existing presets and append the new one
+const { data: settings } = await getPtzSettings('camera-123')
+const newPreset = { name: 'Entrance', position: { x: 0, y: 0, z: 1 }, timeAtPreset: 10 }
+await updatePtzSettings('camera-123', {
+  presets: [...(settings?.presets ?? []), newPreset],
+  homePreset: 'Entrance'
+})
+```
+
+## 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 support | Show "not found" message |
+| FORBIDDEN | No permission | Show access denied message |
+| VALIDATION_ERROR | Empty camera ID | Fix input |
+| API_ERROR | Server error | Show error, allow retry |
+
+## Detecting PTZ-Capable Cameras
+
+To check if a camera supports PTZ, fetch it with `include: ['capabilities']` and check the
+nested `capabilities.ptz.capable` field. The structure is:
+
+```typescript
+// Response from getCamera(id, { include: ['capabilities'] })
+{
+  capabilities: {
+    ptz: {
+      capable: true,       // Camera supports PTZ
+      panTilt: true,       // Supports pan/tilt
+      zoom: true,          // Supports zoom
+      positionMove: true,  // Supports absolute position moves
+      directionMove: true, // Supports directional moves
+      centerOnMove: true,  // Supports center-on moves
+      fisheye: false       // Whether camera is fisheye
+    }
+  }
+}
+```
+
+**IMPORTANT:** The PTZ capability is at `capabilities.ptz.capable` (nested under a `ptz` object),
+NOT at `capabilities.ptzCapable` (flat). Fisheye cameras report `capabilities.ptz.capable: true`
+but are NOT true PTZ cameras — always exclude them. Use this pattern:
+
+```typescript
+import { computed } from 'vue'
+
+const isPtzCapable = computed(() => {
+  const ptz = camera.value?.capabilities?.ptz
+  return ptz?.capable === true && ptz?.fisheye !== true
+})
+```
+
+Also check `effectivePermissions.controlPTZ` to verify the user has permission to move the camera,
+and `effectivePermissions.editPTZStations` for managing presets.
+
+## Constraints
+- Always check authentication before API calls
+- Verify camera has PTZ capability (`capabilities.ptz.capable`) and is not fisheye (`capabilities.ptz.fisheye !== true`) before showing controls
+- Check user permissions (`effectivePermissions.controlPTZ`) before enabling movement
+- Poll position periodically (every 5s) for position display
+- Handle 204 responses for PUT/PATCH (no response body)
+- Use encodeURIComponent for camera IDs in URLs

package/CHANGELOG.md

@@ -2,72 +2,92 @@
 
 All notable changes to this project will be documented in this file.
 
-## [0.3.85] - 2026-02-17
+## [0.3.97] - 2026-02-22
 
 ### Release Summary
 
-#### PR #113: fix: address three security review findings
+#### PR #128: Release v0.3.89: PTZ camera control API and vue-ptz example
 ## Summary
-- **HIGH**: Validate hostname before persisting OAuth token — `setBaseUrl()` now returns boolean; `handleAuthCallback()` checks it before calling `setToken()`, preventing token persistence when hostname is rejected
-- **MEDIUM**: Pin external proxy repo clone in CI workflows (`validate-pr`, `test-release`) to commit SHA `4e8f45f` to prevent supply chain attacks
-- **LOW**: Remove unnecessary `id-token: write` permission from `claude-code-review` workflow
 
-## Test plan
-- [x] 644/644 unit tests pass
-- [x] 225/225 E2E tests pass across all 11 example apps
-- [x] Lint clean, build succeeds
-- [ ] Validate-PR workflow passes on this PR
+This release adds PTZ (Pan/Tilt/Zoom) camera control support to the toolkit:
 
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-#### PR #118: Release v0.3.85 - API coverage docs and workflow security fix
-## Summary
+- **PTZ API functions**: `getPtzPosition()`, `movePtz()`, `getPtzSettings()`, `updatePtzSettings()` with full TypeScript types
+- **PTZ types**: `PtzPosition`, `PtzMove` (discriminated union: position/direction/centerOn), `PtzSettings`, `PtzPreset`, `PtzSettingsUpdate`
+- **vue-ptz example app**: Complete PTZ control application with live video, direction pad, click-to-center, position display, preset management, and API call logging
+- **Camera capabilities**: Added `capabilities` field to `Camera` type for PTZ detection via `include: ['capabilities']`
+- **Documentation**: AI-PTZ.md reference doc, een-ptz-agent, updated AI-CONTEXT.md and CLAUDE.md
+- **E2E tests**: Conditional PTZ API tests that exercise position read, direction move, and preset loading when a PTZ camera is available
 
-- Add EEN API v3.0 coverage documentation (4 documents comparing 211 API endpoints against 51 implemented, 24.2% coverage)
-- Add `api-coverage-agent` for on-demand regeneration of coverage docs
-- Update README with agent list and coverage section
-- Fix workflow_dispatch restriction to production branch (security)
+### Additional changes
+- Dependabot: CodeQL action bump to 4.32.3
+- CI: Use floating v1 tag for claude-code-action instead of SHA pin
 
 ## Commits
 
-- `baa7e1b` feat: add EEN API coverage documentation and agent
-- `eea17e8` docs: add missing agents to README agent list
-- `bb47cc2` docs: rename een-api-coverage-agent to api-coverage-agent
-- `c794fba` fix: restrict workflow_dispatch to production branch to prevent supply chain attack
-- `6e782e2` fix: restrict npm-publish workflow_dispatch to production branch
+- `c552fd0` feat: add PTZ camera control API and vue-ptz example app
+- `6a12649` fix: use single getCameras call with include and pagination for PTZ discovery
+- `2b04b26` fix: address review findings in vue-ptz example app
+- `92a18e4` fix: address remaining review findings
+- `4d01c2c` fix: use floating v1 tag for claude-code-action instead of SHA pin
+- `3f197ba` chore(deps): bump github/codeql-action from 4.32.2 to 4.32.3
+
+## Test Results
+
+| Check | Result |
+|-------|--------|
+| Lint | Pass (0 errors) |
+| Unit tests | 681 passed (24 suites) |
+| Build | Pass |
+| E2E (12 apps) | All passed |
+| Security review | No vulnerabilities found |
+| Confidential data scan | Clean |
 
-## Test Results (from PR #117)
+**Version**: 0.3.89
 
-- **Lint**: Passed
-- **Unit tests**: 644 passed
-- **Build**: Succeeded
-- **E2E tests**: 236 passed across all 11 example apps
-- **Security review**: No vulnerabilities
-- **Code review**: Approved by Claude Sonnet 4.5
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+#### PR #130: Release v0.3.96: PTZ fisheye exclusion and API coverage docs
+## Summary
+- Add fisheye camera exclusion to PTZ type definitions, agent docs, AI reference docs, and vue-ptz example
+- Add PTZ sub-capability fields (`fisheye`, `panTilt`, `zoom`, `positionMove`, `directionMove`, `centerOnMove`) to `Camera.capabilities.ptz` type
+- Regenerate API coverage docs with full-width layout and scrollbar fix
 
 ## Version
+v0.3.96
 
-v0.3.85
+## Commits
+- `1d9da62` docs: regenerate API coverage docs with full-width layout and scrollbar fix
+- `044c9ae` docs: add fisheye camera exclusion guidance to PTZ agent
+- `f65ff2e` fix: add PTZ sub-capability fields to Camera type and update docs
+- `6ecf253` fix: address review findings for PTZ fisheye guidance
+- `97cf632` fix: exclude fisheye cameras from PTZ selector in vue-ptz example
+
+## Test Results
+- Lint: passed (1 pre-existing warning)
+- Unit tests: 683/683 passed
+- Build: passed
+- E2E: 12/12 example apps passed
+- Security: no vulnerabilities (type/docs changes only)
+- Confidential data scan: clean across 280 changed .md files
 
 🤖 Generated with [Claude Code](https://claude.com/claude-code)
 
 
 ### Detailed Changes
 
-#### Features
-- feat: add EEN API coverage documentation and agent
-
 #### Bug Fixes
-- fix: restrict npm-publish workflow_dispatch to production branch
-- fix: restrict workflow_dispatch to production branch to prevent supply chain attack
+- fix: fix sorting bug in coverage table and add undefined fisheye test
+- fix: exclude fisheye cameras from PTZ selector in vue-ptz example
+- fix: address review findings for PTZ fisheye guidance
+- fix: add PTZ sub-capability fields to Camera type and update docs
 
 #### Other Changes
-- docs: rename een-api-coverage-agent to api-coverage-agent
-- docs: add missing agents to README agent list
+- docs: add fisheye camera exclusion guidance to PTZ agent
+- docs: regenerate API coverage docs with full-width layout and scrollbar fix
 
 ### Links
 - [npm package](https://www.npmjs.com/package/een-api-toolkit)
-- [Full Changelog](https://github.com/klaushofrichter/een-api-toolkit/compare/v0.3.82...v0.3.85)
+- [Full Changelog](https://github.com/klaushofrichter/een-api-toolkit/compare/v0.3.91...v0.3.97)
 
 ---
-*Released: 2026-02-17 11:45:53 CST*
+*Released: 2026-02-22 19:53:20 CST*