een-api-toolkit 0.3.22 → 0.3.30

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

@@ -71,8 +71,15 @@ type CameraStatus =
   | 'offline'
   | 'streaming'
   | 'recording'
+  | 'registered'
+  | 'deviceOffline'
+  | 'bridgeOffline'
+  | 'invalidCredentials'
   | 'error'
   | 'unknown'
+
+// Status can also be nested in an object:
+// camera.status?.connectionStatus
 ```
 
 ### Bridge Interface
@@ -112,15 +119,28 @@ interface ListCamerasParams {
 ## Key Functions
 
 ### getCameras()
-List cameras with optional filters:
+List cameras with optional filters.
+
+**IMPORTANT:** The `status` field is NOT included by default. You must use `include: ['status']` to receive it:
+
 ```typescript
 import { getCameras, type Camera, type ListCamerasParams } from 'een-api-toolkit'
 
 const cameras = ref<Camera[]>([])
 
-// Get all online cameras
+// Get all cameras WITH status - include: ['status'] is required!
+async function fetchCameras() {
+  const result = await getCameras({
+    include: ['status'],  // Required to get camera.status
+    pageSize: 100
+  })
+  // Now camera.status will be populated
+}
+
+// Get all online cameras (still need include for display)
 async function fetchOnlineCameras() {
   const result = await getCameras({
+    include: ['status'],  // Required to display status in UI
     status__in: ['online', 'streaming', 'recording'],
     pageSize: 100
   })
@@ -224,17 +244,33 @@ async function fetchBridge(bridgeId: string) {
 
 ```vue
 <script setup lang="ts">
-import { ref, onMounted } from 'vue'
-import { getCameras, type Camera, type ListCamerasParams } from 'een-api-toolkit'
+import { ref, onMounted, computed } from 'vue'
+import { getCameras, type Camera, type CameraStatus, type ListCamerasParams } from 'een-api-toolkit'
 
 const cameras = ref<Camera[]>([])
 const loading = ref(false)
 const statusFilter = ref<string[]>(['online', 'streaming', 'recording'])
 
+// Helper: status can be a string OR an object with connectionStatus
+function getStatusString(status?: CameraStatus | { connectionStatus?: CameraStatus }): string | undefined {
+  if (!status) return undefined
+  if (typeof status === 'string') return status
+  return status.connectionStatus
+}
+
+// Computed property to pre-process cameras with status string (avoids calling helper multiple times in template)
+const camerasWithStatus = computed(() =>
+  cameras.value.map(camera => ({
+    ...camera,
+    statusString: getStatusString(camera.status),
+  }))
+)
+
 async function fetchCameras() {
   loading.value = true
 
   const params: ListCamerasParams = {
+    include: ['status'],  // Required to receive status field
     pageSize: 100
   }
 
@@ -268,10 +304,13 @@ onMounted(fetchCameras)
 
     <div v-if="loading">Loading cameras...</div>
 
+    <!-- Use computed property for better performance (status string computed once per camera) -->
     <div class="camera-grid" v-else>
-      <div v-for="camera in cameras" :key="camera.id" class="camera-card">
+      <div v-for="camera in camerasWithStatus" :key="camera.id" class="camera-card">
         <h3>{{ camera.name }}</h3>
-        <span :class="camera.status">{{ camera.status }}</span>
+        <span :class="camera.statusString">
+          {{ camera.statusString || 'unknown' }}
+        </span>
       </div>
     </div>
   </div>
@@ -287,8 +326,38 @@ onMounted(fetchCameras)
 | FORBIDDEN | No permission | Show access denied message |
 | API_ERROR | Server error | Show error, allow retry |
 
+## Camera ID Usage
+
+The `camera.id` property is used consistently across all toolkit functions:
+- `getCameras()` returns cameras with `id` property
+- `listFeeds({ deviceId: camera.id })` for feeds
+- `getLiveImage({ cameraId: camera.id })` for images
+- LivePlayer SDK: `{ cameraId: camera.id }` for live video
+
+**Note:** Some legacy EEN documentation may refer to "ESN" (Electronic Serial Number). This is outdated terminology - the current API uses `id`. In the toolkit, always use `camera.id`.
+
+## Checking Camera Status for Previews
+
+Before loading previews or video, check if the camera is in a viewable state:
+
+```typescript
+function isCameraOnline(status?: CameraStatus | { connectionStatus?: CameraStatus }): boolean {
+  // Handle both string status and nested object status
+  const statusStr = typeof status === 'string' ? status : status?.connectionStatus
+  return statusStr === 'online' || statusStr === 'streaming' || statusStr === 'registered'
+}
+
+// Usage
+if (isCameraOnline(camera.status)) {
+  // Safe to load preview or video
+} else {
+  // Show "Camera offline" message
+}
+```
+
 ## Constraints
 - Always check authentication before API calls
 - Use appropriate status filters to reduce payload
 - Handle pagination for accounts with many devices
 - Use include[] to request only needed fields
+- Check camera status before loading previews (offline cameras won't have streams)

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

@@ -58,12 +58,14 @@ assistant: "I'll use the een-media-agent to diagnose the HLS configuration and a
 - Modify multipartUrl with query parameters
 - Use multipartUrl without initMediaSession() first
 - Assume timestamps are ISO 8601 (they use +00:00 format)
+- Pass ANY arguments to LivePlayer constructor - it MUST be called as `new LivePlayer()` with no arguments
 
 **ALWAYS:**
 - Use getLiveImage() for simple thumbnails
 - Use initMediaSession() before multipartUrl
 - Use formatTimestamp() for EEN API timestamps
 - Check authentication before media operations
+- Pass config to LivePlayer's `start()` method, NOT the constructor
 
 ## Choosing the Right Preview Method
 
@@ -213,28 +215,82 @@ function setupHlsPlayer(videoElement: HTMLVideoElement, hlsUrl: string) {
 
 ## Live Video SDK Integration
 
-For full-quality live video, use the EEN Live Video SDK:
+For full-quality live video, use the EEN Live Video Web SDK:
 
 ```typescript
-// Install: npm install @eencloud/live-video-sdk
+// Install: npm install @een/live-video-web-sdk
 
-import { EENLiveVideo } from '@eencloud/live-video-sdk'
+import LivePlayer from '@een/live-video-web-sdk'
 import { useAuthStore } from 'een-api-toolkit'
 
-function setupLiveVideo(container: HTMLElement, cameraId: string) {
+// Store player instance for cleanup
+let livePlayer: LivePlayer | null = null
+
+async function setupLiveVideo(videoElement: HTMLVideoElement, cameraId: string) {
   const authStore = useAuthStore()
 
-  const player = new EENLiveVideo({
-    container,
-    cameraId,
-    accessToken: authStore.token,
-    baseUrl: authStore.baseUrl
+  // CRITICAL: Create LivePlayer WITHOUT arguments
+  livePlayer = new LivePlayer()
+
+  // CRITICAL: Pass config to start(), NOT to constructor
+  await livePlayer.start({
+    videoElement,      // HTML video element (required)
+    cameraId,          // Camera device ID (required)
+    baseUrl: authStore.baseUrl,  // EEN API base URL (required)
+    jwt: authStore.token         // Auth token (required)
   })
 
-  player.play()
+  return livePlayer
+}
+
+// Clean up when done
+function stopLiveVideo() {
+  if (livePlayer) {
+    livePlayer.stop()
+    livePlayer = null
+  }
+}
+```
+
+### IMPORTANT: LivePlayer Usage Pattern
+
+**CORRECT pattern:**
+```typescript
+const player = new LivePlayer()        // No arguments to constructor
+await player.start(config)             // Config passed to start()
+```
+
+**WRONG pattern (will cause "Video Stream is done" errors):**
+```typescript
+const player = new LivePlayer(config)  // DON'T pass config here
+await player.start()                   // This won't work correctly
+```
+
+### IMPORTANT: Video Element Must Be in DOM
+
+The video element MUST be rendered in the DOM before calling `player.start()`.
+
+**Problem:** Using `v-if` to conditionally show the video element means it doesn't exist during loading:
+```vue
+<!-- WRONG: Video element doesn't exist when loading=true -->
+<div v-if="loading">Loading...</div>
+<video v-else ref="videoRef" />  <!-- Not in DOM during loading! -->
+```
 
-  return player
+**Solution:** Always render the video element, use CSS to hide it:
+```vue
+<!-- CORRECT: Video element always exists in DOM -->
+<div v-if="loading" class="loading-overlay">Loading...</div>
+<div class="video-container" :class="{ hidden: loading }">
+  <video ref="videoRef" />  <!-- Always in DOM -->
+</div>
+
+<style>
+.video-container.hidden {
+  visibility: hidden;
+  position: absolute;
 }
+</style>
 ```
 
 ## Error Handling
@@ -253,4 +309,7 @@ function setupLiveVideo(container: HTMLElement, cameraId: string) {
 | Image not loading | Auth not in cookies | Call initMediaSession() first |
 | Timestamp errors | Wrong format | Use formatTimestamp() |
 | CORS errors | Direct API access | Use toolkit functions, not direct fetch |
-| Black video | HLS auth missing | Configure xhrSetup with token |
+| Black video (HLS) | HLS auth missing | Configure xhrSetup with token |
+| "Video Stream is done" immediately | Config passed to LivePlayer constructor | MUST use `new LivePlayer()` with no args, then `player.start(config)` |
+| "Video element not found" | Video element not in DOM | Ensure video element is rendered (not hidden by v-if) before SDK init |
+| Black video, no errors (LivePlayer) | Video element hidden by v-if | Use CSS visibility/opacity instead of v-if for conditional video display |

package/CHANGELOG.md

@@ -2,170 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
-## [0.3.22] - 2026-01-22
+## [0.3.30] - 2026-01-23
 
 ### Release Summary
 
-#### PR #64: Release v0.3.20: Add media buttons to event modal lightboxes
-## Summary
-
-- Added Preview, HD Image, and Video buttons to event modal lightboxes in vue-events and vue-event-subscriptions example apps
-- Implemented proper authentication for media fetching using `getRecordedImage` and HLS player with Authorization headers
-- Created `useHlsPlayer` composable for both apps following vue-alerts-metrics pattern
-
-## Changes
-
-- **vue-events**: Updated EventsModal.vue with media buttons and HLS video support
-- **vue-event-subscriptions**: Updated LiveEvents.vue with media buttons and HLS video support
-- Added hls.js dependency to both example apps
-- Created composables/useHlsPlayer.ts in both apps
-
-## Test Plan
-
-- [x] Unit tests: 341 passed
-- [x] Build: successful
-- [x] E2E tests for all 8 example apps passed (123 total):
-  - vue-users: 14 passed
-  - vue-cameras: 13 passed
-  - vue-bridges: 13 passed
-  - vue-events: 16 passed
-  - vue-feeds: 12 passed
-  - vue-media: 20 passed
-  - vue-alerts-metrics: 20 passed
-  - vue-event-subscriptions: 15 passed
-
-## Version
-
-v0.3.20
-
-## Commits
-
-- 8f11b04 feat: Add media buttons to event modal lightboxes in vue-events and vue-event-subscriptions
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-#### PR #65: feat: Restructure AI documentation with specialized agents
-## Summary
-
-Restructures the AI documentation from a single monolithic file into domain-specific documents with specialized Claude agents for context-efficient AI assistance.
-
-### Changes
-
-**Documentation Split (7 files):**
-- `AI-CONTEXT.md` - Overview and navigation (entry point)
-- `AI-SETUP.md` - Vue 3 scaffolding, Pinia, Vite configuration
-- `AI-AUTH.md` - OAuth flow, tokens, route guards
-- `AI-USERS.md` - User management API
-- `AI-DEVICES.md` - Cameras & Bridges API
-- `AI-MEDIA.md` - Media, Feeds, Live Video, HLS
-- `AI-EVENTS.md` - Events, Alerts, Metrics, SSE subscriptions
-
-**Specialized Agents (6 new agents):**
-- `een-setup-agent` - Vue 3 project setup assistance
-- `een-auth-agent` - OAuth authentication help
-- `een-users-agent` - User management features
-- `een-devices-agent` - Camera and bridge operations
-- `een-media-agent` - Video and media troubleshooting
-- `een-events-agent` - Events and real-time streaming
-
-**CLI Tool:**
-- Added `npx een-setup-agents` command for easy agent installation
-- Copies agents to `.claude/agents/` for automatic discovery
-
-**Generation Script:**
-- Refactored to generate split files by default
-- `--single` flag for legacy monolithic output
-- Extracts examples from actual Vue components
-
-### Benefits
-
-| Metric | Before | After (typical task) |
-|--------|--------|---------------------|
-| Tokens per task | ~15-18K | ~5-8K |
-| Context preserved | Limited | Substantial |
-| Agent specialization | None | 6 domain agents |
-
-## Test Results
-
-- **Lint:** ✅ Passed (1 pre-existing warning)
-- **Unit Tests:** ✅ 341 passed
-- **Build:** ✅ Successful
-- **E2E Tests:** ✅ 70 passed across 8 example apps
-
-## Version
-
-`0.3.20`
-
-## Commits
-
-- `8e1cc78` feat: Restructure AI documentation into domain-specific files with specialized agents
-
----
-
-🤖 Generated with [Claude Code](https://claude.ai/code)
-
-#### PR #66: Release v0.3.20: AI Documentation Restructure
-## Summary
-
-This release restructures the AI documentation for improved context efficiency:
-
-- **Split AI-CONTEXT.md** into 7 domain-specific documents (~2-4K tokens each vs 15K+ monolithic)
-- **Added 6 specialized Claude agents** for domain-specific assistance
-- **New CLI tool**: `npx een-setup-agents` for easy agent installation in consumer projects
-- **Code quality fixes** addressing Gemini code review feedback
-
-## Changes
-
-### New Files
-- `.claude/agents/` - 6 specialized agents (auth, users, devices, media, events, setup)
-- `docs/ai-reference/` - 6 domain-specific AI reference documents
-- `scripts/setup-agents.ts` - CLI tool for agent installation
-
-### Modified
-- `docs/AI-CONTEXT.md` - Now serves as overview with navigation
-- `scripts/generate-ai-context.ts` - Rewritten to support split file generation
-- `package.json` - Added bin entry and updated files array
-- `CLAUDE.md` - Added agent documentation section
-
-### Commits
-- `8e1cc78` feat: Restructure AI documentation into domain-specific files with specialized agents
-- `407db5f` fix: Address Gemini code review feedback
-- `ecd6cfd` Merge pull request #65
-
-## Test Results
-
-- **Lint**: ✅ Passed (1 pre-existing warning)
-- **Unit Tests**: ✅ 341 passed
-- **Build**: ✅ Successful
-- **E2E Tests**: ✅ 70 passed across 8 example apps
-
-## Version
-
-`0.3.20`
-
----
-
-🤖 Generated with [Claude Code](https://claude.ai/code)
-
+No PR descriptions available for this release.
 
 ### Detailed Changes
 
-#### Features
-- feat: Restructure AI documentation into domain-specific files with specialized agents
-- feat: Add media buttons to event modal lightboxes in vue-events and vue-event-subscriptions
-
-#### Bug Fixes
-- fix: Add XSS protection for SVG overlays in events agent
-- fix: Address Gemini code review feedback
-- fix: Address code review feedback from PR #64
-
 #### Other Changes
-- chore: Bump version to 0.3.21 and update Husky triggers
-- refactor: Move media session state from module-level to Pinia store
+- refactor: Use computed property for camera status in devices agent
+- docs: Document status field requirements in devices agent
 
 ### Links
 - [npm package](https://www.npmjs.com/package/een-api-toolkit)
-- [Full Changelog](https://github.com/klaushofrichter/een-api-toolkit/compare/v0.3.20...v0.3.22)
+- [Full Changelog](https://github.com/klaushofrichter/een-api-toolkit/compare/v0.3.28...v0.3.30)
 
 ---
-*Released: 2026-01-22 19:45:17 CST*
+*Released: 2026-01-23 17:42:54 CST*

package/README.md

@@ -176,6 +176,29 @@ if (!cameraError) {
 | **[AI Context](./docs/AI-CONTEXT.md)** | Single-file reference for AI assistants (also in npm package) |
 | **[AI Prompts](./docs/Prompts.md)** | Example prompts for generating apps with AI |
 
+## Claude Code Agents
+
+The toolkit includes specialized [Claude Code](https://docs.anthropic.com/en/docs/claude-code) agents for AI-assisted development. These agents have deep knowledge of the EEN API and toolkit patterns.
+
+> **Note:** These agents use Claude Code's specific format. To use with other AI assistants (Gemini CLI, Copilot, etc.), the agent specs would need conversion.
+
+**Available agents:**
+- `een-setup-agent` - Project scaffolding, Pinia setup, Vite configuration
+- `een-auth-agent` - OAuth flows, route guards, token management
+- `een-users-agent` - User listing and profile APIs
+- `een-devices-agent` - Camera and bridge management
+- `een-media-agent` - Live video, previews, HLS playback
+- `een-events-agent` - Events, alerts, metrics, SSE subscriptions
+
+**Installation:**
+```bash
+npx een-setup-agents
+```
+
+> **Important:** After running the setup script, **restart Claude Code** for the agents to become available.
+
+See the [User Guide](./docs/USER-GUIDE.md#claude-code-agents) for detailed agent documentation.
+
 ## Example Applications
 
 The `examples/` directory contains complete Vue 3 applications demonstrating toolkit features: