een-api-toolkit 0.3.7 → 0.3.8

package/CHANGELOG.md

@@ -2,57 +2,26 @@
 
 All notable changes to this project will be documented in this file.
 
-## [0.3.7] - 2026-01-06
+## [0.3.8] - 2026-01-09
 
 ### Release Summary
 
-#### PR #46: feat: Add configurable storage strategy for token persistence
-## Summary
-
-- Add `storageStrategy` option to `initEenToolkit()` allowing apps to choose how authentication tokens are persisted
-- Three storage options with different security/UX tradeoffs:
-  - `localStorage` (default): Persists across sessions, backwards compatible
-  - `sessionStorage`: Per-tab isolation, cleared on tab close  
-  - `memory`: Maximum security, tokens never written to disk
-- Addresses security finding about JWT tokens in localStorage being vulnerable to XSS
-
-## Changes
-
-- Add `StorageAdapter` abstraction with localStorage/sessionStorage/memory implementations
-- Add `storageStrategy` config option (default: `localStorage` for backwards compatibility)
-- Export `StorageStrategy` type and `getStorageStrategy()` function
-- Update auth store to use configurable storage adapter
-- Add 24 unit tests for storage functionality
-- Document security vs UX tradeoffs in USER-GUIDE.md
-
-## Additional fixes
-
-- Update EEN API docs link from `/reference/listusers` to `/reference/getusers`
-- Replace "~1 hour" token validity references with accurate configurable range (15min-7days)
-
-## Test plan
-
-- [x] All 188 unit tests pass
-- [x] Build succeeds
-- [x] Lint passes
-- [ ] Verify backwards compatibility (existing apps work without changes)
-- [ ] Test each storage strategy manually
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
+No PR descriptions available for this release.
 
 ### Detailed Changes
 
 #### Features
-- feat: Add configurable storage strategy for token persistence
+- feat: Enhance sync-secrets.sh to sync .env to example apps
 
 #### Bug Fixes
-- fix: Propagate storage errors to auth/store for proper logging
-- fix: Address PR review feedback and demonstrate storage strategies
+- fix: Update AI-CONTEXT generator with missing documentation
+
+#### Other Changes
+- docs: Optimize AI-CONTEXT.md for LLM consumption
 
 ### Links
 - [npm package](https://www.npmjs.com/package/een-api-toolkit)
-- [Full Changelog](https://github.com/klaushofrichter/een-api-toolkit/compare/v0.3.4...v0.3.7)
+- [Full Changelog](https://github.com/klaushofrichter/een-api-toolkit/compare/v0.3.7...v0.3.8)
 
 ---
-*Released: 2026-01-06 12:25:59 CST*
+*Released: 2026-01-09 17:31:59 CST*

package/README.md

@@ -241,6 +241,46 @@ npm run test:e2e:ui
 
 > **Note:** All development and testing has been done on macOS. The `lsof` command used in scripts may behave differently on other platforms.
 
+## Scripts
+
+Utility scripts are located in the `scripts/` directory:
+
+| Script | Purpose |
+|--------|---------|
+| `sync-secrets.sh` | Sync secrets to GitHub and example apps |
+| `restart-proxy.sh` | Start/restart the local OAuth proxy |
+| `cleanup-auth.sh` | Revoke test tokens and clear auth cache |
+
+### Syncing Secrets
+
+The `sync-secrets.sh` script manages secrets from a single source (root `.env` file):
+
+```bash
+# Preview what will be synced (no changes made)
+./scripts/sync-secrets.sh --dry-run
+
+# Sync secrets to GitHub and example applications
+./scripts/sync-secrets.sh
+```
+
+**What it does:**
+
+1. **GitHub Repository Secrets** - Syncs these variables for CI/CD:
+   - `ANTHROPIC_API_KEY`, `CLIENT_SECRET`, `NPM_TOKEN`, `SLACK_WEBHOOK`
+   - `TEST_USER`, `TEST_PASSWORD`, `VITE_EEN_CLIENT_ID`, `VITE_PROXY_URL`
+
+2. **Example Applications** - Copies VITE_* variables to `examples/*/.env`:
+   - `VITE_PROXY_URL`, `VITE_EEN_CLIENT_ID`, `VITE_DEBUG`
+   - `VITE_REDIRECT_URI` (hardcoded to `http://127.0.0.1:3333`)
+
+**Setup:**
+
+1. Copy `.env.example` to `.env` in the project root
+2. Fill in your actual values
+3. Run `./scripts/sync-secrets.sh` to distribute secrets
+
+> **Note:** Example `.env` files are gitignored. Run `sync-secrets.sh` after cloning to set up local development.
+
 ## External Resources
 
 - [EEN Developer Portal](https://developer.eagleeyenetworks.com/)

package/docs/AI-CONTEXT.md

@@ -1,6 +1,6 @@
 # EEN API Toolkit - AI Reference
 
-> **Version:** 0.3.7
+> **Version:** 0.3.8
 >
 > This file is optimized for AI assistants. It contains all API signatures,
 > types, and usage patterns in a single, parseable document.
@@ -103,10 +103,98 @@ app.mount('#app')        // ✅ Last - mount app
 
 **Solution:**
 - Use `127.0.0.1` not `localhost`
-- Use port `3333`
-- No trailing slash, no path
+- Use port `3333` exactly
+- No trailing slash (not `http://127.0.0.1:3333/`)
+- No path (not `http://127.0.0.1:3333/callback`)
 - Register this exact URI at [EEN Developer Portal](https://developer.eagleeyenetworks.com/page/my-application)
 
+**Vite config:**
+```typescript
+// vite.config.ts
+server: { host: '127.0.0.1', port: 3333, strictPort: true }
+```
+
+**Router pattern:** Handle OAuth callback on root path, then redirect internally:
+```typescript
+// router/index.ts - root path must catch OAuth params
+{
+  path: '/',
+  beforeEnter: (to, _from, next) => {
+    if (to.query.code && to.query.state) {
+      next({ name: 'callback', query: to.query })
+    } else {
+      next()
+    }
+  }
+}
+```
+
+### Common Pitfalls - Preview Images
+
+Displaying live preview images requires careful attention to authentication. Here are common mistakes:
+
+#### DON'T: Construct API URLs directly for `<img>` tags
+
+```typescript
+// WRONG - browsers cannot send Authorization headers with <img src>
+const url = `${authStore.baseUrl}/api/v3.0/media/liveImage.jpeg?deviceId=${cameraId}`
+imgElement.src = url  // Results in 401 Unauthorized
+```
+
+**Why it fails:** The `<img>` element makes a simple GET request without custom headers. The JWT token cannot be sent, so the request is unauthorized.
+
+#### DON'T: Modify multipartUrl by adding query parameters
+
+```typescript
+// WRONG - adding parameters breaks the pre-signed URL
+const feedUrl = feed.multipartUrl
+imgElement.src = `${feedUrl}?timestamp=${Date.now()}`  // Results in 400 Bad Request
+imgElement.src = `${feedUrl}&cache=${Date.now()}`     // Also fails
+```
+
+**Why it fails:** The `multipartUrl` is a complete, pre-authenticated URL. Any modification (including cache-busting parameters) invalidates it.
+
+#### DO: Use `getLiveImage()` for preview thumbnails
+
+```typescript
+// CORRECT - returns base64 data URL that works directly in <img src>
+import { getLiveImage } from 'een-api-toolkit'
+
+const { data, error } = await getLiveImage({ deviceId: cameraId })
+if (data?.imageData) {
+  imgElement.src = data.imageData  // "data:image/jpeg;base64,..."
+}
+```
+
+**Why it works:** The toolkit handles authentication internally and returns a base64-encoded data URL that can be used directly without browser restrictions.
+
+### Choosing the Right Preview Method
+
+| Use Case | Method | Notes |
+|----------|--------|-------|
+| Grid of camera thumbnails | `getLiveImage()` | Best for multiple cameras, handles auth internally |
+| Periodic refresh (e.g., every 3s) | `getLiveImage()` | Call repeatedly in a timer |
+| Single continuous MJPEG stream | `multipartUrl` | Requires `initMediaSession()` first, use URL unmodified |
+| One-time snapshot | `getLiveImage()` | Simple and self-contained |
+| Full-quality live video | Live Video SDK | For modal/fullscreen video playback |
+
+**Quick Reference:**
+
+```typescript
+// For thumbnails and grids - USE THIS
+const { data } = await getLiveImage({ deviceId })
+img.src = data.imageData
+
+// For continuous MJPEG stream (single camera, unmodified URL only)
+await initMediaSession()
+const { data: feeds } = await listFeeds({ deviceId, include: ['multipartUrl'] })
+img.src = feeds.results.find(f => f.type === 'preview')?.multipartUrl
+
+// For HD live video - use @een/live-video-web-sdk
+const player = new LivePlayer()
+player.start({ videoElement, cameraId, baseUrl, jwt })
+```
+
 ---
 
 ## Quick Reference
@@ -153,6 +241,7 @@ app.mount('#app')        // ✅ Last - mount app
 | Function | Purpose | Returns |
 |----------|---------|---------|
 | `listMedia(params)` | List media intervals for a device | `Result<PaginatedResult<MediaInterval>>` |
+| `listFeeds(params)` | List available feeds for a device | `Result<ListFeedsResult>` |
 | `getLiveImage(params)` | Get live preview image from camera | `Result<LiveImageResult>` |
 | `getRecordedImage(params)` | Get recorded image from history | `Result<RecordedImageResult>` |
 | `getMediaSession()` | Get media session URL for cookies | `Result<MediaSessionResponse>` |
@@ -160,72 +249,6 @@ app.mount('#app')        // ✅ Last - mount app
 
 ---
 
-## Critical Requirements
-
-### OAuth Redirect URI (IMPORTANT)
-
-The EEN Identity Provider performs an **exact string match** on the redirect URI. Applications MUST follow these rules:
-
-| Requirement | Correct | Incorrect |
-|-------------|---------|-----------|
-| Host | `127.0.0.1` | `localhost` |
-| Path | None (root path only) | `/callback` |
-| Trailing slash | No | `http://127.0.0.1:3333/` |
-
-**The only valid redirect URI is: `http://127.0.0.1:3333`**
-
-**Configure at:** [EEN Developer Portal - My Application](https://developer.eagleeyenetworks.com/page/my-application)
-
-### Application Requirements
-
-1. **Handle OAuth callbacks on the root path (`/`)** - not `/callback`
-2. **Run dev server on `127.0.0.1`** - not `localhost`
-3. **Register exactly `http://127.0.0.1:3333` with EEN at the Developer Portal**
-
-### Router Pattern for OAuth Callbacks
-
-The root path must detect OAuth params and handle the callback:
-
-```typescript
-// router/index.ts
-{
-  path: '/',
-  name: 'home',
-  component: Home,
-  beforeEnter: (to, _from, next) => {
-    // If URL has OAuth params, redirect to callback handler
-    if (to.query.code && to.query.state) {
-      next({ name: 'callback', query: to.query })
-    } else {
-      next()
-    }
-  }
-}
-```
-
-### Vite Dev Server Configuration
-
-```typescript
-// vite.config.ts
-export default defineConfig({
-  server: {
-    host: '127.0.0.1',  // MUST use 127.0.0.1, not localhost
-    port: 3333,
-    strictPort: true
-  }
-})
-```
-
-### Common OAuth Errors
-
-| Error | Cause | Solution |
-|-------|-------|----------|
-| "Redirect URI mismatch" | URI doesn't match exactly | Use `http://127.0.0.1:3333` (no path, no trailing slash) |
-| Redirected back to login | Router guard blocks callback | Allow OAuth params through on root path |
-| Callback not processed | Wrong path or host | Handle callback on `/`, use `127.0.0.1` |
-
----
-
 ## Core Types
 
 ### Result<T>
@@ -245,16 +268,17 @@ interface EenError {
 }
 
 type ErrorCode =
-  | 'AUTH_REQUIRED'    // No valid token - redirect to login
-  | 'AUTH_FAILED'      // Authentication failed
-  | 'TOKEN_EXPIRED'    // Token expired - will auto-refresh
-  | 'API_ERROR'        // EEN API returned an error
-  | 'NETWORK_ERROR'    // Network request failed
-  | 'VALIDATION_ERROR' // Invalid parameters
-  | 'NOT_FOUND'        // Resource not found (404)
-  | 'FORBIDDEN'        // Access denied (403)
-  | 'RATE_LIMITED'     // Too many requests (429)
-  | 'UNKNOWN_ERROR'    // Unexpected error
+  | 'AUTH_REQUIRED'       // No valid token - redirect to login
+  | 'AUTH_FAILED'         // Authentication failed
+  | 'TOKEN_EXPIRED'       // Token expired - will auto-refresh
+  | 'API_ERROR'           // EEN API returned an error
+  | 'NETWORK_ERROR'       // Network request failed
+  | 'VALIDATION_ERROR'    // Invalid parameters
+  | 'NOT_FOUND'           // Resource not found (404)
+  | 'FORBIDDEN'           // Access denied (403)
+  | 'RATE_LIMITED'        // Too many requests (429)
+  | 'SERVICE_UNAVAILABLE' // Service unavailable (503)
+  | 'UNKNOWN_ERROR'       // Unexpected error
 ```
 
 ### Pagination Types
@@ -276,11 +300,14 @@ interface PaginatedResult<T> {
 ### Configuration Type
 
 ```typescript
+type StorageStrategy = 'localStorage' | 'sessionStorage' | 'memory'
+
 interface EenToolkitConfig {
-  proxyUrl?: string    // OAuth proxy URL (required for API calls)
-  clientId?: string    // EEN OAuth client ID
-  redirectUri?: string // OAuth redirect URI (default: http://127.0.0.1:3333)
-  debug?: boolean      // Enable debug logging
+  proxyUrl?: string           // OAuth proxy URL (required for API calls)
+  clientId?: string           // EEN OAuth client ID
+  redirectUri?: string        // OAuth redirect URI (default: http://127.0.0.1:3333)
+  storageStrategy?: StorageStrategy  // Token storage: 'localStorage' (default), 'sessionStorage', or 'memory'
+  debug?: boolean             // Enable debug logging
 }
 ```
 
@@ -582,6 +609,44 @@ interface MediaSessionResult {
 }
 ```
 
+### Feed Types
+
+```typescript
+type FeedStreamType = 'main' | 'preview' | 'talkdown'
+type FeedMediaType = 'video' | 'audio' | 'image' | 'halfDuplex' | 'fullDuplex'
+type FeedIncludeOption = 'flvUrl' | 'rtspUrl' | 'rtspsUrl' | 'localRtspUrl' | 'hlsUrl' | 'multipartUrl' | 'webRtcUrl' | 'audioPushHttpsUrl'
+
+interface Feed {
+  id: string                    // Feed identifier (typically deviceId-type)
+  type: FeedStreamType          // Stream type
+  deviceId: string              // Device generating this feed
+  mediaType: FeedMediaType      // Media type
+  flvUrl?: string | null        // Flash Video URL (if requested)
+  rtspUrl?: string | null       // RTSP URL (if requested)
+  rtspsUrl?: string | null      // RTSP over TLS (if requested)
+  localRtspUrl?: string | null  // Local RTSP to bridge (if requested)
+  hlsUrl?: string | null        // HLS URL (if requested)
+  multipartUrl?: string | null  // Multipart URL for raw frames (if requested)
+  webRtcUrl?: string | null     // WebRTC URL (if requested)
+  audioPushHttpsUrl?: string | null  // Audio push for speakers (if requested)
+}
+
+interface ListFeedsParams {
+  deviceId?: string             // Filter by single device ID
+  deviceId__in?: string[]       // Filter by multiple device IDs
+  type?: FeedStreamType         // Filter by stream type
+  include?: FeedIncludeOption[] // URL fields to include in response
+  pageSize?: number
+  pageToken?: string
+}
+
+interface ListFeedsResult {
+  results: Feed[]
+  nextPageToken?: string
+  totalSize?: number
+}
+```
+
 ---
 
 ## API Reference
@@ -1354,100 +1419,6 @@ console.log(data.email) // Safe
 
 ---
 
-## Additional Setup Details
-
-### OAuth Callback Route
-
-The `beforeEnter` guard shown in the "Critical Requirements" section redirects OAuth responses to a named route called 'callback'. Here is how to set up that route and its component:
-
-```typescript
-// router/index.ts
-{
-  path: '/callback',
-  name: 'callback',
-  component: () => import('./views/Callback.vue')
-}
-```
-
-```vue
-<!-- views/Callback.vue -->
-<script setup lang="ts">
-import { onMounted } from 'vue'
-import { useRouter } from 'vue-router'
-import { handleAuthCallback } from 'een-api-toolkit'
-
-const router = useRouter()
-
-onMounted(async () => {
-  const url = new URL(window.location.href)
-  const code = url.searchParams.get('code')
-  const state = url.searchParams.get('state')
-
-  if (!code || !state) {
-    router.push('/login?error=missing_params')
-    return
-  }
-
-  const { error } = await handleAuthCallback(code, state)
-
-  if (error) {
-    router.push(`/login?error=${error.code}`)
-    return
-  }
-
-  router.push('/dashboard')
-})
-</script>
-
-<template>
-  <div>Authenticating...</div>
-</template>
-```
-
-### Login Component
-
-```vue
-<!-- views/Login.vue -->
-<script setup>
-import { getAuthUrl } from 'een-api-toolkit'
-
-function login() {
-  window.location.href = getAuthUrl()
-}
-</script>
-
-<template>
-  <div>
-    <h1>Login</h1>
-    <button @click="login">Sign in with Eagle Eye Networks</button>
-  </div>
-</template>
-```
-
-### Logout Component
-
-```vue
-<!-- In a component, e.g., App.vue or a NavBar component -->
-<script setup lang="ts">
-import { revokeToken } from 'een-api-toolkit'
-import { useRouter } from 'vue-router'
-
-const router = useRouter()
-
-async function logout() {
-  await revokeToken()
-  // Redirect to login page after token is revoked
-  router.push('/login')
-}
-</script>
-
-<template>
-  <button @click="logout">Logout</button>
-</template>
-```
-
----
-
 ## External Resources
 
 - [Eagle Eye Networks Developer Portal](https://developer.eagleeyenetworks.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "een-api-toolkit",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "EEN Video platform API v3.0 library for Vue 3",
   "type": "module",
   "main": "./dist/index.cjs",