een-api-toolkit 0.3.28 → 0.3.35

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

@@ -61,6 +61,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
 
 2. **Analysis Phase**:
@@ -82,6 +84,15 @@ assistant: "I'll use the docs-accuracy-reviewer agent to verify the README and a
 
 ## Specific Checks to Perform
 
+### For Example Application Documentation:
+- **Check ALL example apps** in `examples/*/README.md` (not just one)
+- Verify screenshot references exist and filenames match actual files
+- Confirm all listed API functions are exported from `src/index.ts`
+- Check that `.env.example` files exist when referenced in setup instructions
+- Validate project structure sections match actual directory contents
+- Ensure port numbers are correct (should be `127.0.0.1:3333`)
+- Verify code examples use current API signatures
+
 ### For API Documentation:
 - Compare documented function signatures with `src/index.ts` exports
 - Verify type definitions match `src/types/` directory
@@ -141,6 +152,7 @@ When reporting findings, use this structure:
 
 Before completing your review:
 1. Verify you've checked ALL markdown files in the project
-2. Confirm each fix you made is backed by evidence from source code
-3. Re-read modified sections to ensure they're clear and accurate
-4. Check that your fixes didn't introduce new broken links or inconsistencies
+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

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

@@ -123,10 +123,22 @@ authStore.isExpired      // Computed: true if token expired
 ```
 
 ## Auth Guard Pattern
+
+**CRITICAL**: The OAuth callback check MUST come BEFORE the auth check in the global guard.
+The EEN IDP redirects to the root path (`/`) with `code` and `state` query parameters.
+If you check authentication first, the user will be redirected to login before the callback is processed.
+
 ```typescript
 import { useAuthStore } from 'een-api-toolkit'
 
 router.beforeEach((to, from, next) => {
+  // IMPORTANT: Check for OAuth callback FIRST, before auth check
+  // EEN IDP redirects to root path with code and state params
+  if (to.path === '/' && to.query.code && to.query.state) {
+    next({ name: 'callback', query: to.query })
+    return
+  }
+
   const authStore = useAuthStore()
 
   if (to.meta.requiresAuth && !authStore.isAuthenticated) {
@@ -137,6 +149,10 @@ router.beforeEach((to, from, next) => {
 })
 ```
 
+**WARNING**: Do NOT use route-specific `beforeEnter` guards for OAuth callback detection.
+Global `beforeEach` guards run BEFORE route-specific guards, so the auth check will
+block the callback before `beforeEnter` can redirect to the callback handler.
+
 ## Token Lifecycle
 
 1. **Login**: User redirects to EEN OAuth → Returns with code → Exchange for tokens
@@ -151,6 +167,38 @@ router.beforeEach((to, from, next) => {
 - **Session ID**: Client receives session ID to identify refresh session
 - **Token only**: Client stores only short-lived access token
 
+## Environment Variables
+
+Required environment variables for OAuth:
+
+```
+VITE_PROXY_URL=https://your-oauth-proxy.workers.dev  # OAuth proxy URL
+VITE_EEN_CLIENT_ID=YOUR-CLIENT-ID                     # EEN OAuth client ID
+TEST_USER=user@example.com                            # For Playwright tests
+TEST_PASSWORD=password                                # For Playwright tests
+```
+
+## localStorage Keys
+
+The toolkit stores auth state in localStorage with these keys:
+
+| Key | Description |
+|-----|-------------|
+| `een_token` | JWT access token |
+| `een_tokenExpiration` | Token expiration timestamp (ms) |
+| `een_sessionId` | Session ID for token refresh (proxy-side) |
+| `een_hostname` | EEN API hostname (region-specific, e.g., `api.c021.eagleeyenetworks.com`) |
+| `een_userProfile` | Cached user profile JSON |
+| `een_refreshTokenMarker` | Indicates refresh token exists server-side (`"present"`) |
+
+Useful for debugging:
+```typescript
+// Check auth state in browser console
+console.log('Token:', localStorage.getItem('een_token')?.substring(0, 50) + '...')
+console.log('Expires:', new Date(parseInt(localStorage.getItem('een_tokenExpiration') || '0')))
+console.log('Hostname:', localStorage.getItem('een_hostname'))
+```
+
 ## Constraints
 - Never expose refresh tokens to client code
 - Handle AUTH_REQUIRED errors by redirecting to login
@@ -158,6 +206,89 @@ router.beforeEach((to, from, next) => {
 - Always validate state parameter in callback
 - Clear auth state completely on logout
 
+## Vite Server Configuration
+
+The Vite dev server MUST bind to `127.0.0.1` (not `localhost`) to match the redirect URI:
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  server: {
+    host: '127.0.0.1',  // REQUIRED: Must match redirect URI
+    port: 3333,
+    strictPort: true
+  }
+})
+```
+
+## EEN Login Page (Two-Step Process)
+
+The EEN OAuth login page uses a **two-step authentication flow**:
+
+1. **Step 1 - Email**: User enters email address and clicks "Next"
+2. **Step 2 - Password**: Password field appears, user enters password and clicks "Sign in"
+
+This is important for Playwright tests - you cannot fill both fields at once:
+
+```typescript
+// Playwright test example for EEN two-step login
+// Step 1: Enter email and click Next
+const emailInput = page.locator('input[type="email"], input[type="text"]').first()
+await emailInput.fill(TEST_USER)
+await page.getByRole('button', { name: /next/i }).click()
+
+// Step 2: Wait for password field and fill it
+const passwordInput = page.locator('input[type="password"]')
+await passwordInput.waitFor({ state: 'visible', timeout: 10000 })
+await passwordInput.fill(TEST_PASSWORD)
+await page.getByRole('button', { name: /sign in/i }).click()
+```
+
+## Playwright E2E Test Patterns
+
+**Reference examples in:** `node_modules/een-api-toolkit/examples/*/e2e/auth.spec.ts`
+
+Best practices for auth testing:
+1. **Fresh login per test**: Perform login for each test that needs auth (don't rely on state persistence)
+2. **Clear state after each test**: Use `afterEach` to clear localStorage/sessionStorage
+3. **Check proxy accessibility**: Skip OAuth tests if proxy is not reachable
+4. **Use EEN-specific selectors**: The EEN login page has specific IDs like `#authentication--input__email`
+
+```typescript
+// Complete performLogin helper function
+async function performLogin(page: Page, username: string, password: string): Promise<void> {
+  await page.goto('/login')
+  await page.click('button:has-text("Login with Eagle Eye Networks")')
+
+  // Wait for EEN OAuth page
+  await page.waitForURL(/.*eagleeyenetworks.com.*/, { timeout: 30000 })
+
+  // Step 1: Email
+  const emailInput = page.locator('#authentication--input__email, input[type="email"]').first()
+  await emailInput.waitFor({ state: 'visible', timeout: 15000 })
+  await emailInput.fill(username)
+  await page.getByRole('button', { name: 'Next' }).click()
+
+  // Step 2: Password
+  const passwordInput = page.locator('#authentication--input__password, input[type="password"]')
+  await passwordInput.waitFor({ state: 'visible', timeout: 10000 })
+  await passwordInput.fill(password)
+  await page.locator('#next, button:has-text("Sign in")').first().click()
+
+  // Wait for redirect back to app
+  await page.waitForURL(/127\.0\.0\.1:3333/, { timeout: 60000 })
+  await page.waitForURL('**/', { timeout: 60000 })
+}
+
+// Clear auth state helper
+async function clearAuthState(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    localStorage.clear()
+    sessionStorage.clear()
+  })
+}
+```
+
 ## Common Errors
 
 | Error | Cause | Solution |

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

@@ -69,14 +69,14 @@ interface Camera {
 type CameraStatus =
   | 'online'
   | 'offline'
-  | 'streaming'
-  | 'recording'
-  | 'registered'
   | 'deviceOffline'
   | 'bridgeOffline'
   | 'invalidCredentials'
   | 'error'
-  | 'unknown'
+  | 'streaming'
+  | 'registered'
+  | 'attaching'
+  | 'initializing'
 
 // Status can also be nested in an object:
 // camera.status?.connectionStatus
@@ -97,7 +97,10 @@ type BridgeStatus =
   | 'online'
   | 'offline'
   | 'error'
-  | 'unknown'
+  | 'idle'
+  | 'registered'
+  | 'attaching'
+  | 'initializing'
 ```
 
 ### ListCamerasParams
@@ -119,16 +122,29 @@ 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({
-    status__in: ['online', 'streaming', 'recording'],
+    include: ['status'],  // Required to display status in UI
+    status__in: ['online', 'streaming', 'registered'],
     pageSize: 100
   })
 
@@ -231,17 +247,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'])
+const statusFilter = ref<string[]>(['online', 'streaming', 'registered'])
+
+// 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
   }
 
@@ -275,10 +307,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>

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

@@ -141,6 +141,77 @@ const actor = `camera:${cameraId}`
 const actor = `account:${accountId}`
 ```
 
+### listEventFieldValues()
+Discover available event types for a specific camera:
+```typescript
+import { listEventFieldValues } from 'een-api-toolkit'
+
+async function getAvailableEventTypes(cameraId: string) {
+  const result = await listEventFieldValues({
+    actor: `camera:${cameraId}`
+  })
+
+  if (result.data) {
+    // result.data.type is an array of event type strings available for this camera
+    const availableTypes = result.data.type || []
+    // e.g., ['een.motionDetectionEvent.v1', 'een.tamperDetectionEvent.v1']
+    return availableTypes
+  }
+  return []
+}
+```
+
+### listEventTypes()
+Get human-readable names for event types:
+```typescript
+import { listEventTypes } from 'een-api-toolkit'
+
+async function fetchEventTypeNames() {
+  const result = await listEventTypes({ pageSize: 100 })
+
+  if (result.data) {
+    // Build a map of type -> name for display
+    const nameMap = new Map<string, string>()
+    for (const et of result.data.results) {
+      nameMap.set(et.type, et.name)
+      // e.g., 'een.motionDetectionEvent.v1' -> 'Motion Detection'
+    }
+    return nameMap
+  }
+  return new Map()
+}
+
+// Fallback: Parse event type string if API name not available
+function parseEventTypeName(type: string): string {
+  const match = type.match(/een\.(\w+)Event\.v\d+/)
+  if (match) {
+    return match[1]
+      .replace(/([A-Z])/g, ' $1')  // Add space before capitals
+      .replace(/^./, str => str.toUpperCase())
+      .trim()
+  }
+  return type
+}
+```
+
+### Motion Detection Preselection Pattern
+When implementing event type toggles, preselect motion detection by default:
+```typescript
+const MOTION_DETECTION_EVENT = 'een.motionDetectionEvent.v1'
+
+function preselectEventTypes(availableTypes: string[]): string[] {
+  // Preselect motion detection if available
+  if (availableTypes.includes(MOTION_DETECTION_EVENT)) {
+    return [MOTION_DETECTION_EVENT]
+  }
+  // Otherwise select the first available type
+  if (availableTypes.length > 0) {
+    return [availableTypes[0]]
+  }
+  return []
+}
+```
+
 ### getEventMetrics()
 Get aggregated event counts:
 ```typescript
@@ -262,6 +333,33 @@ onUnmounted(async () => {
 })
 ```
 
+## Getting Event Thumbnails
+
+Use `getRecordedImage()` to fetch a thumbnail image for an event:
+```typescript
+import { getRecordedImage, 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:', '')
+
+  const result = await getRecordedImage({
+    cameraId,
+    timestamp: event.timestamp,
+    width: 120,  // Thumbnail size
+    height: 80
+  })
+
+  if (result.data?.dataUrl) {
+    eventImages.value.set(event.id, result.data.dataUrl)
+  }
+}
+
+// In template: <img :src="eventImages.get(event.id)" />
+```
+
 ## Displaying Event Bounding Boxes
 
 Events can include SVG overlays showing where motion/objects were detected.