een-api-toolkit 0.3.30 → 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
@@ -141,7 +144,7 @@ async function fetchCameras() {
 async function fetchOnlineCameras() {
   const result = await getCameras({
     include: ['status'],  // Required to display status in UI
-    status__in: ['online', 'streaming', 'recording'],
+    status__in: ['online', 'streaming', 'registered'],
     pageSize: 100
   })
 
@@ -249,7 +252,7 @@ import { getCameras, type Camera, type CameraStatus, type ListCamerasParams } fr
 
 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 {

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.