een-api-toolkit 0.3.38 → 0.3.46

package/.claude/agents/docs-accuracy-reviewer.md

@@ -31,6 +31,13 @@ assistant: "I'll use the docs-accuracy-reviewer agent to verify the README and a
 <Task tool call to launch docs-accuracy-reviewer agent>
 </example>
 
+<example>
+Context: User wants to verify Claude agent definitions are accurate.
+user: "Check if the agent files in .claude/agents match the actual API"
+assistant: "I'll use the docs-accuracy-reviewer agent to verify the een-* agent files have correct function signatures, parameter names, and code examples."
+<Task tool call to launch docs-accuracy-reviewer agent>
+</example>
+
 ## Your Core Responsibilities
 
 1. **Function and Feature Verification**: Cross-reference every documented function, method, API, and feature against the actual source code. Verify that:
@@ -62,8 +69,8 @@ assistant: "I'll use the docs-accuracy-reviewer agent to verify the README and a
 1. **Discovery Phase**:
    - List all markdown files in the project (README.md, docs/**, CLAUDE.md, etc.)
    - **Scan ALL example directories** (`examples/*/README.md`) - do not skip any
-   - Check agent files in `.claude/agents/*.md`
-   - Identify the source code structure for cross-referencing
+   - **Check ALL agent files** in `.claude/agents/een-*.md` - verify function signatures and code examples against actual implementations
+   - Identify the source code structure for cross-referencing (especially `src/index.ts` exports, `src/*/service.ts` implementations, and `src/types/*.ts` definitions)
 
 2. **Analysis Phase**:
    - Read each documentation file thoroughly
@@ -115,6 +122,18 @@ assistant: "I'll use the docs-accuracy-reviewer agent to verify the README and a
 - Verify .env.example matches documentation
 - Check that all required secrets are documented
 
+### For Claude Agent Files (`.claude/agents/een-*.md`):
+- **Function Signatures**: Verify all documented function signatures match actual implementations in `src/*/service.ts`
+- **Parameter Names**: Check that parameter names in examples match the actual API (e.g., `deviceId` not `cameraId`, `userId` as direct param not `{ id: userId }`)
+- **Result Properties**: Verify result property names (e.g., `imageData` not `dataUrl`)
+- **Type Definitions**: Cross-reference documented types against `src/types/*.ts`
+- **Filter Parameters**: Verify filter parameter names use correct suffixes (e.g., `startTimestamp__gte` not `startTimestamp`)
+- **Include Options**: Check that documented include options are valid for each API
+- **Code Examples**: Ensure all code examples use current API patterns and would actually compile
+- **Referenced Examples**: Verify that referenced example directories (`examples/vue-*/`) exist
+- **Referenced Docs**: Verify that referenced documentation files (`docs/ai-reference/AI-*.md`) exist
+- **Version Consistency**: If version numbers are present, verify they match `package.json`
+
 ## Output Format
 
 When reporting findings, use this structure:
@@ -153,6 +172,17 @@ When reporting findings, use this structure:
 Before completing your review:
 1. Verify you've checked ALL markdown files in the project
 2. **Confirm ALL example app READMEs were reviewed** (list them in your report)
-3. Confirm each fix you made is backed by evidence from source code
-4. Re-read modified sections to ensure they're clear and accurate
-5. Check that your fixes didn't introduce new broken links or inconsistencies
+3. **Confirm ALL `.claude/agents/een-*.md` files were reviewed** for API accuracy
+4. Confirm each fix you made is backed by evidence from source code
+5. Re-read modified sections to ensure they're clear and accurate
+6. Check that your fixes didn't introduce new broken links or inconsistencies
+
+## Common Agent File Issues to Watch For
+
+These are the most common inaccuracies found in agent files:
+- Using `cameraId` instead of `deviceId` for media/image functions
+- Using `{ id: userId }` instead of `userId` as direct parameter for get functions
+- Using `dataUrl` instead of `imageData` for image result properties
+- Using `startTimestamp` instead of `startTimestamp__gte` for event filters
+- Using `width/height` instead of `targetWidth/targetHeight` for image dimensions
+- Missing `formatTimestamp()` calls for timestamp parameters

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

@@ -122,6 +122,32 @@ authStore.isAuthenticated // Computed: true if valid token exists
 authStore.isExpired      // Computed: true if token expired
 ```
 
+### authStore.initialize() - Session Restoration (CRITICAL)
+**Must be called in App.vue onMounted to restore sessions from storage.**
+
+Without this call, users must re-login after every page refresh, even with localStorage strategy:
+
+```vue
+<script setup lang="ts">
+import { onMounted, computed } from 'vue'
+import { useAuthStore } from 'een-api-toolkit'
+
+const authStore = useAuthStore()
+const isAuthenticated = computed(() => authStore.isAuthenticated)
+
+// CRITICAL: Restore session from storage on app mount
+onMounted(() => {
+  authStore.initialize()
+})
+</script>
+```
+
+What `initialize()` does:
+1. Loads token, expiration, session ID, base URL from storage
+2. If valid token exists: Sets up auto-refresh timer
+3. If expired token: Clears auth state (user must re-login)
+4. If no token: No action (user must login)
+
 ## Auth Guard Pattern
 
 **CRITICAL**: The OAuth callback check MUST come BEFORE the auth check in the global guard.
@@ -297,3 +323,5 @@ async function clearAuthState(page: Page): Promise<void> {
 | invalid_grant | Code expired or reused | Restart OAuth flow |
 | invalid_state | State mismatch | Clear storage, restart flow |
 | REFRESH_FAILED | Refresh token invalid | Redirect to login |
+| Session lost on refresh | Missing initialize() call | Add `authStore.initialize()` in App.vue onMounted |
+| Must login after refresh | Missing initialize() call | Add `authStore.initialize()` in App.vue onMounted |

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

@@ -0,0 +1,264 @@
+---
+name: een-automations-agent
+description: |
+  Use this agent when working with automation rules: event alert condition rules,
+  alert condition rules, alert action rules, or alert actions with the een-api-toolkit.
+  This includes setting up automated alert workflows and notifications.
+model: inherit
+color: orange
+---
+
+You are an expert in automation rules and alert workflows with the een-api-toolkit.
+
+## Examples
+
+<example>
+Context: User wants to list automation rules.
+user: "How do I list all my alert condition rules?"
+assistant: "I'll use the een-automations-agent to help list alert condition rules with listAlertConditionRules()."
+<Task tool call to launch een-automations-agent>
+</example>
+
+<example>
+Context: User wants to see available alert actions.
+user: "What alert actions are configured for my account?"
+assistant: "I'll use the een-automations-agent to help fetch alert actions with listAlertActions()."
+<Task tool call to launch een-automations-agent>
+</example>
+
+<example>
+Context: User wants to understand the automation workflow.
+user: "How do events trigger alerts and actions?"
+assistant: "I'll use the een-automations-agent to explain the event-to-alert-to-action workflow."
+<Task tool call to launch een-automations-agent>
+</example>
+
+## Context Files
+- docs/AI-CONTEXT.md (overview)
+- docs/ai-reference/AI-AUTH.md (auth is required)
+- docs/ai-reference/AI-AUTOMATIONS.md (primary reference)
+- docs/ai-reference/AI-EVENTS.md (events trigger alerts)
+
+## Reference Examples
+- examples/vue-automations/ (Automation rules listing)
+
+## Your Capabilities
+1. List event alert condition rules with listEventAlertConditionRules()
+2. Get available filter values with getEventAlertConditionRuleFieldValues()
+3. Get single event alert condition rule with getEventAlertConditionRule()
+4. List alert condition rules with listAlertConditionRules()
+5. Get single alert condition rule with getAlertConditionRule()
+6. List alert action rules with listAlertActionRules()
+7. Get single alert action rule with getAlertActionRule()
+8. List alert actions with listAlertActions()
+9. Get single alert action with getAlertAction()
+
+## Automation Workflow
+
+```
+Events → Event Alert Condition Rules → Alerts → Alert Action Rules → Alert Actions
+         (filter events)               (generated)  (match alerts)    (execute)
+```
+
+1. **Events** are generated by cameras/devices (motion, object detection, etc.)
+2. **Event Alert Condition Rules** filter events and determine when to create alerts
+3. **Alerts** are generated when events match rule conditions
+4. **Alert Action Rules** match alerts to actions based on type, actor, priority
+5. **Alert Actions** execute (push notification, webhook, SMS, email, etc.)
+
+## Key Types
+
+### EventAlertConditionRule
+```typescript
+interface EventAlertConditionRule {
+  id: string
+  name: string
+  priority: number                    // 1-10, higher is more important
+  enabled: boolean
+  cooldownSeconds: number
+  eventFilter: {
+    types: string[]                   // Event types to match
+    resourceFilter?: {
+      actorIds?: string[]
+      actorTags__contains?: string[]
+    }
+  }
+  outputAlertTypes: string[]          // Alert types generated
+  humanValidation?: {
+    required: boolean
+    timeoutSeconds?: number
+  }
+}
+```
+
+### AlertConditionRule
+```typescript
+interface AlertConditionRule {
+  id: string
+  name: string
+  type: string
+  enabled: boolean
+  priority: number
+  actors: AlertConditionRuleActor[]   // Actors this rule applies to
+  inputEventTypes: string[]           // Event types that trigger this rule
+  outputAlertType: string             // Alert type generated
+  actions?: AlertConditionRuleAction[] // include=actions
+  insights?: AlertConditionRuleInsights // include=insights
+}
+```
+
+### AlertActionRule
+```typescript
+interface AlertActionRule {
+  id: string
+  name: string
+  enabled: boolean
+  alertTypes: string[]                // Alert types this rule matches
+  actorIds: string[]
+  actorTypes: string[]
+  ruleIds: string[]                   // Alert condition rule IDs
+  alertActionIds: string[]            // Actions to execute
+  priority__gte?: number              // Min priority filter
+  priority__lte?: number              // Max priority filter
+}
+```
+
+### AutomationAlertAction
+```typescript
+interface AutomationAlertAction {
+  id: string
+  type: AlertActionType
+  name: string
+  enabled: boolean
+  settings: AlertActionSettings       // Type-specific settings
+}
+
+type AlertActionType =
+  | 'notification'    // Push notifications
+  | 'sms'             // SMS messages
+  | 'smtp'            // Email
+  | 'slack'           // Slack webhook
+  | 'webhook'         // Generic webhook
+  | 'brivo'           // Brivo access control
+  | 'zendesk'         // Zendesk tickets
+  | 'immix'           // Immix integration
+  | 'zapier'          // Zapier webhook
+  | 'sentinel'        // Sentinel integration
+  | 'evalinkTalos'    // Evalink integration
+  | 'outputPort'      // Physical output trigger
+  | 'ebus'            // eBus integration
+  | 'playSpeakerAudioClip' // Speaker audio
+  | 'zulipPrivate'    // Zulip private message
+  | 'zulipStream'     // Zulip stream message
+```
+
+## Key Functions
+
+### listEventAlertConditionRules()
+```typescript
+import { listEventAlertConditionRules, type EventAlertConditionRule } from 'een-api-toolkit'
+
+const { data, error } = await listEventAlertConditionRules({
+  enabled: true,
+  priority__gte: 5,
+  pageSize: 50
+})
+
+if (data) {
+  data.results.forEach(rule => {
+    console.log(`${rule.name}: ${rule.eventFilter.types.join(', ')}`)
+  })
+}
+```
+
+### listAlertConditionRules()
+```typescript
+import { listAlertConditionRules } from 'een-api-toolkit'
+
+const { data, error } = await listAlertConditionRules({
+  enabled: true,
+  include: ['actions', 'insights']
+})
+
+if (data) {
+  data.results.forEach(rule => {
+    console.log(`${rule.name}: ${rule.actions?.length ?? 0} actions`)
+    console.log(`Last triggered: ${rule.insights?.lastTriggered}`)
+  })
+}
+```
+
+### listAlertActionRules()
+```typescript
+import { listAlertActionRules } from 'een-api-toolkit'
+
+const { data, error } = await listAlertActionRules({
+  enabled: true,
+  alertType__in: ['een.motionDetectionAlert.v1']
+})
+
+if (data) {
+  data.results.forEach(rule => {
+    console.log(`${rule.name}: ${rule.alertActionIds.length} actions`)
+  })
+}
+```
+
+### listAlertActions()
+```typescript
+import { listAlertActions } from 'een-api-toolkit'
+
+const { data, error } = await listAlertActions({
+  enabled: true,
+  type__in: ['notification', 'webhook', 'slack']
+})
+
+if (data) {
+  data.results.forEach(action => {
+    console.log(`${action.name} (${action.type})`)
+  })
+}
+```
+
+### getEventAlertConditionRuleFieldValues()
+Discover available filter values:
+```typescript
+import { getEventAlertConditionRuleFieldValues } from 'een-api-toolkit'
+
+const { data } = await getEventAlertConditionRuleFieldValues()
+if (data) {
+  console.log('Available event types:', data.eventTypes)
+  console.log('Available alert types:', data.outputAlertTypes)
+}
+```
+
+## Filter Patterns
+
+| Filter | Example | Description |
+|--------|---------|-------------|
+| `enabled` | `true` | Filter by enabled/disabled status |
+| `id__in` | `['id1', 'id2']` | Filter by specific IDs |
+| `priority__gte` | `5` | Minimum priority (inclusive) |
+| `priority__lte` | `10` | Maximum priority (inclusive) |
+| `outputAlertType__in` | `['een.motionDetectionAlert.v1']` | Event alert rule output types |
+| `alertType__in` | `['een.motionDetectionAlert.v1']` | Alert action rule alert types |
+| `type__in` | `['notification', 'webhook']` | Alert action types |
+| `actorId__in` | `['camera-123']` | Filter by actor IDs |
+| `include` | `['actions', 'insights']` | Include additional fields |
+
+## Error Handling
+
+| Error Code | Meaning | Action |
+|------------|---------|--------|
+| AUTH_REQUIRED | Not authenticated | Redirect to login |
+| NOT_FOUND | Rule/action not found | Show "not found" message |
+| FORBIDDEN | No permission | Show access denied |
+| RATE_LIMITED | Too many requests | Retry with backoff |
+| VALIDATION_ERROR | Invalid parameters | Check input |
+
+## Constraints
+- All automation endpoints are GET-only (read access)
+- Priority values range from 1-10 (higher = more important)
+- Use `include` parameter for additional data (actions, insights)
+- Pagination is supported on all list endpoints
+- Filter by `enabled` to see only active rules/actions

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

@@ -170,14 +170,13 @@ async function getCamerasByTags(tags: string[]) {
 }
 ```
 
-### getCamera(id)
+### getCamera(cameraId, params?)
 Get a specific camera:
 ```typescript
 import { getCamera, type Camera } from 'een-api-toolkit'
 
 async function fetchCamera(cameraId: string) {
-  const result = await getCamera({
-    id: cameraId,
+  const result = await getCamera(cameraId, {
     include: ['deviceInfo', 'settings']  // Request additional details
   })
 
@@ -216,14 +215,13 @@ async function fetchOnlineBridges() {
 }
 ```
 
-### getBridge(id)
+### getBridge(bridgeId, params?)
 Get a specific bridge:
 ```typescript
 import { getBridge, type Bridge } from 'een-api-toolkit'
 
 async function fetchBridge(bridgeId: string) {
-  const result = await getBridge({
-    id: bridgeId,
+  const result = await getBridge(bridgeId, {
     include: ['networkInfo']
   })
 
@@ -334,7 +332,7 @@ onMounted(fetchCameras)
 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
+- `getLiveImage({ deviceId: 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`.

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

@@ -79,12 +79,14 @@ type EventType =
 ```typescript
 interface ListEventsParams {
   actor: string                    // Required: "camera:{cameraId}"
-  startTimestamp?: string
-  endTimestamp?: string
-  type__in?: EventType[]
+  type__in: string[]               // Required: event types to query
+  startTimestamp__gte: string      // Required: start time (ISO 8601)
+  startTimestamp__lte?: string     // Optional: end time filter
+  endTimestamp__gte?: string       // Optional: filter by event end time
+  endTimestamp__lte?: string       // Optional: filter by event end time
   pageSize?: number
   pageToken?: string
-  include?: string[]               // Include SVG overlays: ['data.overlays']
+  include?: string[]               // Include SVG overlays: ['data.een.fullFrameImageUrl.v1']
 }
 ```
 
@@ -118,10 +120,10 @@ async function fetchEvents(cameraId: string) {
 
   const result = await listEvents({
     actor: `camera:${cameraId}`,
-    startTimestamp: formatTimestamp(hourAgo),
-    endTimestamp: formatTimestamp(now),
     type__in: ['een.motionDetectionEvent.v1', 'een.objectDetectionEvent.v1'],
-    include: ['data.overlays'],  // Include bounding box SVGs
+    startTimestamp__gte: formatTimestamp(hourAgo.toISOString()),
+    startTimestamp__lte: formatTimestamp(now.toISOString()),
+    include: ['data.een.fullFrameImageUrl.v1'],  // Include image URLs
     pageSize: 50
   })
 
@@ -250,6 +252,19 @@ async function fetchAlerts() {
 }
 ```
 
+### Alert Priority
+Alert priority is an integer value ranging from **0 to 10**:
+- `0` = Lowest priority
+- `10` = Highest priority
+
+Use priority to filter or sort alerts by importance:
+```typescript
+const result = await listAlerts({
+  priority__gte: 7,  // High priority alerts only
+  status__in: ['active']
+})
+```
+
 ### listNotifications()
 Get user notifications:
 ```typescript
@@ -269,12 +284,20 @@ async function fetchNotifications() {
 
 ## SSE (Server-Sent Events) for Real-Time Updates
 
+### SSE Subscription Behavior
+
+**Important: TTL is read-only and server-determined**
+- SSE subscriptions have a **15-minute TTL** (900 seconds) set by the server
+- The `timeToLiveSeconds` value **cannot be customized** when creating a subscription
+- The `subscriptionConfig` (including `lifeCycle` and `timeToLiveSeconds`) is returned in the API response but is not a configurable input
+- SSE URLs are **single-use**: once disconnected, you must create a new subscription
+
 ### SSE Lifecycle
 
-1. **Create Subscription** - Get a subscription with SSE URL
+1. **Create Subscription** - Get a subscription with SSE URL (server sets 15-min TTL)
 2. **Connect to Stream** - Open EventSource connection
 3. **Handle Events** - Process events as they arrive
-4. **Cleanup** - Delete subscription when done
+4. **Cleanup** - Delete subscription when done (or it auto-expires after 15 min of inactivity)
 
 ### createEventSubscription()
 ```typescript
@@ -337,23 +360,22 @@ onUnmounted(async () => {
 
 Use `getRecordedImage()` to fetch a thumbnail image for an event:
 ```typescript
-import { getRecordedImage, type Event } from 'een-api-toolkit'
+import { getRecordedImage, formatTimestamp, type Event } from 'een-api-toolkit'
 
 const eventImages = ref<Map<string, string>>(new Map())
 
 async function fetchEventThumbnail(event: Event) {
-  // Extract camera ID from actor (format: "camera:{cameraId}")
-  const cameraId = event.actor.replace('camera:', '')
+  // Extract device ID from actorId
+  const deviceId = event.actorId
 
   const result = await getRecordedImage({
-    cameraId,
-    timestamp: event.timestamp,
-    width: 120,  // Thumbnail size
-    height: 80
+    deviceId,
+    timestamp: formatTimestamp(event.startTimestamp),
+    type: 'preview'
   })
 
-  if (result.data?.dataUrl) {
-    eventImages.value.set(event.id, result.data.dataUrl)
+  if (result.data?.imageData) {
+    eventImages.value.set(event.id, result.data.imageData)
   }
 }
 

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

@@ -87,23 +87,21 @@ If you need HD quality video, you MUST use the Live Video SDK. Do not attempt to
 
 ## Key Functions
 
-### getLiveImage(cameraId)
-Get a live preview image (returns data URL):
+### getLiveImage(params)
+Get a live preview image (returns base64 data URL):
 ```typescript
 import { getLiveImage, type LiveImageResult } from 'een-api-toolkit'
 
 const imageUrl = ref<string>('')
 
-async function fetchPreview(cameraId: string) {
+async function fetchPreview(deviceId: string) {
   const result = await getLiveImage({
-    cameraId,
-    width: 320,
-    height: 240,
-    type: 'jpeg'
+    deviceId,
+    type: 'preview'  // Optional, defaults to 'preview'
   })
 
   if (result.data) {
-    imageUrl.value = result.data.dataUrl  // Use directly in <img src>
+    imageUrl.value = result.data.imageData  // Use directly in <img src>
   }
 }
 ```
@@ -158,21 +156,20 @@ onMounted(async () => {
 })
 ```
 
-### getRecordedImage()
+### getRecordedImage(params)
 Get an image at a specific timestamp:
 ```typescript
 import { getRecordedImage, formatTimestamp } from 'een-api-toolkit'
 
-async function fetchRecordedFrame(cameraId: string, date: Date) {
+async function fetchRecordedFrame(deviceId: string, date: Date) {
   const result = await getRecordedImage({
-    cameraId,
-    timestamp: formatTimestamp(date),  // MUST use formatTimestamp()
-    width: 640,
-    height: 480
+    deviceId,
+    timestamp: formatTimestamp(date.toISOString()),  // MUST use formatTimestamp()
+    type: 'preview'  // Optional, defaults to 'preview'
   })
 
   if (result.data) {
-    imageUrl.value = result.data.dataUrl
+    imageUrl.value = result.data.imageData
   }
 }
 ```

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

@@ -74,6 +74,35 @@ app.use(router)
 app.mount('#app')
 ```
 
+### App.vue Session Restoration (CRITICAL)
+**Users will need to re-login after every page refresh unless you call `authStore.initialize()` in App.vue.**
+
+```vue
+<script setup lang="ts">
+import { onMounted, computed } from 'vue'
+import { useAuthStore } from 'een-api-toolkit'
+
+const authStore = useAuthStore()
+const isAuthenticated = computed(() => authStore.isAuthenticated)
+
+// CRITICAL: Initialize auth store from storage on app mount
+// This restores the session if a valid token exists in localStorage/sessionStorage
+onMounted(() => {
+  authStore.initialize()
+})
+</script>
+```
+
+Without `initialize()`:
+- Token is saved to localStorage after login ✓
+- On page refresh, Pinia store starts with empty state
+- `isAuthenticated` returns false → user must login again
+
+With `initialize()`:
+- Token is loaded from localStorage on app mount
+- `isAuthenticated` returns true → session is restored
+- User can continue without re-logging in
+
 ### vite.config.ts for EEN OAuth
 ```typescript
 import { defineConfig } from 'vite'
@@ -115,6 +144,7 @@ export default router
 - Pinia must be installed before initEenToolkit()
 - Never add trailing slashes to redirect URIs
 - Ensure VITE_PROXY_URL is set in .env file
+- **Always call `authStore.initialize()` in App.vue onMounted** for session persistence
 
 ## Common Errors and Solutions
 
@@ -124,3 +154,5 @@ export default router
 | "redirect_uri mismatch" | Wrong host/port | Use 127.0.0.1:3333 in vite.config.ts |
 | "Invalid redirect_uri" | Trailing slash | Remove trailing slash from redirect URI |
 | "CORS error" | Proxy not running | Start the OAuth proxy server |
+| Session lost on refresh | Missing initialize() call | Add `authStore.initialize()` in App.vue onMounted |
+| Must login after refresh | Missing initialize() call | Add `authStore.initialize()` in App.vue onMounted |

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

@@ -137,13 +137,13 @@ async function loadMore() {
 }
 ```
 
-### getUser(id)
+### getUser(userId, params?)
 Get a specific user by ID:
 ```typescript
 import { getUser, type User } from 'een-api-toolkit'
 
 async function fetchUser(userId: string) {
-  const result = await getUser({ id: userId })
+  const result = await getUser(userId)
 
   if (result.error) {
     if (result.error.code === 'NOT_FOUND') {