een-api-toolkit 0.3.16 → 0.3.22

package/docs/ai-reference/AI-SETUP.md

@@ -0,0 +1,267 @@
+# Vue 3 Application Setup - EEN API Toolkit
+
+> **Version:** 0.3.22
+>
+> Complete guide for setting up a Vue 3 application with the een-api-toolkit.
+> Load this document when creating a new project or troubleshooting setup issues.
+
+---
+
+## Prerequisites
+
+| Requirement | Details |
+|-------------|---------|
+| **Node.js** | Version 20 LTS or later |
+| **Vue 3.x** | The toolkit is built for Vue 3 Composition API |
+| **Pinia** | Required peer dependency for state management |
+| **Vite** | Recommended build tool |
+| **OAuth Proxy** | Required for secure token management |
+
+---
+
+## Quick Start
+
+### 1. Create Vue 3 Project
+
+```bash
+npm create vue@latest my-een-app
+cd my-een-app
+```
+
+### 2. Install Dependencies
+
+```bash
+npm install een-api-toolkit pinia
+```
+
+### 3. Configure main.ts
+
+> **⚠️ CRITICAL:** Pinia MUST be installed on the Vue app BEFORE calling
+> `initEenToolkit()` or using `useAuthStore()`.
+
+```typescript
+import { createApp } from 'vue'
+import { createPinia } from 'pinia'
+import { initEenToolkit } from 'een-api-toolkit'
+import App from './App.vue'
+import router from './router'
+
+const app = createApp(App)
+
+// Install Pinia (required before initEenToolkit)
+app.use(createPinia())
+
+// Initialize EEN API Toolkit with memory storage for maximum security
+// Note: Using 'memory' storage means tokens are lost on page refresh
+initEenToolkit({
+  proxyUrl: import.meta.env.VITE_PROXY_URL,
+  clientId: import.meta.env.VITE_EEN_CLIENT_ID,
+  redirectUri: import.meta.env.VITE_REDIRECT_URI,
+  storageStrategy: 'memory',
+  debug: import.meta.env.VITE_DEBUG === 'true'
+})
+
+// Install router
+app.use(router)
+
+app.mount('#app')
+
+```
+
+### 4. Configure vite.config.ts
+
+> **⚠️ IMPORTANT:** Must use `127.0.0.1:3333` for EEN OAuth callback.
+
+```typescript
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  plugins: [vue()],
+  server: {
+    // IMPORTANT: Must use 127.0.0.1:3333 for EEN OAuth callback
+    // The EEN Identity Provider only permits this specific redirect URI
+    host: '127.0.0.1',
+    port: 3333
+  }
+})
+
+```
+
+### 5. Configure Environment Variables
+
+Create `.env` file:
+
+```env
+VITE_PROXY_URL=http://localhost:8787
+VITE_EEN_CLIENT_ID=your-een-client-id
+VITE_REDIRECT_URI=http://127.0.0.1:3333
+VITE_DEBUG=true
+```
+
+---
+
+## Router Setup
+
+The router must handle OAuth callbacks on the root path and protect authenticated routes.
+
+```typescript
+import { createRouter, createWebHistory } from 'vue-router'
+import { useAuthStore } from 'een-api-toolkit'
+import Home from '../views/Home.vue'
+import Login from '../views/Login.vue'
+import Callback from '../views/Callback.vue'
+import Users from '../views/Users.vue'
+import Logout from '../views/Logout.vue'
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    {
+      path: '/',
+      name: 'home',
+      component: Home,
+      // Handle OAuth callback on root path (EEN IDP redirects to http://127.0.0.1:3333)
+      beforeEnter: (to, _from, next) => {
+        // If URL has code and state params, it's an OAuth callback
+        if (to.query.code && to.query.state) {
+          next({ name: 'callback', query: to.query })
+        } else {
+          next()
+        }
+      }
+    },
+    {
+      path: '/login',
+      name: 'login',
+      component: Login
+    },
+    {
+      path: '/callback',
+      name: 'callback',
+      component: Callback
+    },
+    {
+      path: '/users',
+      name: 'users',
+      component: Users,
+      meta: { requiresAuth: true }
+    },
+    {
+      path: '/logout',
+      name: 'logout',
+      component: Logout
+    }
+  ]
+})
+
+// Navigation guard for protected routes
+router.beforeEach((to, _from, next) => {
+  const authStore = useAuthStore()
+
+  if (to.meta.requiresAuth && !authStore.isAuthenticated) {
+    next({ name: 'login' })
+  } else {
+    next()
+  }
+})
+
+export default router
+
+```
+
+---
+
+## Project Structure
+
+```
+my-een-app/
+├── src/
+│   ├── main.ts              # Pinia + toolkit initialization
+│   ├── App.vue              # Root component
+│   ├── router/
+│   │   └── index.ts         # Routes with auth guards
+│   └── views/
+│       ├── Home.vue         # Landing page
+│       ├── Login.vue        # OAuth login trigger
+│       ├── Logout.vue       # Token revocation
+│       └── Callback.vue     # OAuth callback handler
+├── .env                     # Environment variables
+└── vite.config.ts           # Vite configuration
+```
+
+---
+
+## Common Setup Errors
+
+### "getActivePinia() was called but there was no active Pinia"
+
+**Cause:** Pinia was not installed before `initEenToolkit()` was called.
+
+**Solution:** Ensure `app.use(pinia)` is called BEFORE `initEenToolkit()`:
+
+```typescript
+const app = createApp(App)
+app.use(createPinia())      // ✅ First
+initEenToolkit({...})       // ✅ Second
+app.mount('#app')           // ✅ Last
+```
+
+### "Redirect URI mismatch"
+
+**Cause:** OAuth redirect URI doesn't exactly match `http://127.0.0.1:3333`.
+
+**Solution:**
+- Use `127.0.0.1` not `localhost`
+- Use port `3333` exactly
+- No trailing slash
+- No path (not `/callback`)
+- Register at [EEN Developer Portal](https://developer.eagleeyenetworks.com/page/my-application)
+
+### Port 3333 already in use
+
+**Solution:** Kill existing process:
+
+```bash
+kill $(lsof -ti :3333) 2>/dev/null || true
+npm run dev
+```
+
+---
+
+## Configuration Options
+
+```typescript
+interface EenToolkitConfig {
+  proxyUrl?: string           // OAuth proxy URL (required)
+  clientId?: string           // EEN OAuth client ID (required)
+  redirectUri?: string        // OAuth redirect URI (default: http://127.0.0.1:3333)
+  storageStrategy?: StorageStrategy  // Token storage strategy
+  debug?: boolean             // Enable debug logging
+}
+
+type StorageStrategy = 'localStorage' | 'sessionStorage' | 'memory'
+```
+
+### Storage Strategies
+
+| Strategy | Persistence | Use Case |
+|----------|-------------|----------|
+| `localStorage` | Survives browser restart | Default, good for most apps |
+| `sessionStorage` | Per-tab, cleared on close | Multi-account scenarios |
+| `memory` | Lost on page refresh | Maximum security |
+
+---
+
+## Next Steps
+
+After setup, proceed to:
+- [AI-AUTH.md](./AI-AUTH.md) - Implement login/logout flows
+- [AI-USERS.md](./AI-USERS.md) - Work with user data
+- [AI-DEVICES.md](./AI-DEVICES.md) - Work with cameras and bridges
+
+---
+
+## Reference Example
+
+See `examples/vue-users/` for a complete working example.

package/docs/ai-reference/AI-USERS.md

@@ -0,0 +1,255 @@
+# Users API - EEN API Toolkit
+
+> **Version:** 0.3.22
+>
+> Complete reference for user management.
+> Load this document when working with user data.
+
+---
+
+## Types
+
+### User
+
+```typescript
+interface User {
+  id: string
+  email: string
+  firstName: string
+  lastName: string
+  accountId?: string
+  timeZone?: string       // IANA timezone (e.g., "America/Los_Angeles")
+  language?: string       // ISO 639-1 code (e.g., "en")
+  phone?: string
+  mobilePhone?: string
+  permissions?: string[]  // Requires include: ['permissions']
+  lastLogin?: string      // ISO 8601 timestamp
+  isActive?: boolean
+  createdAt?: string
+  updatedAt?: string
+}
+```
+
+### UserProfile
+
+```typescript
+interface UserProfile {
+  id: string
+  email: string
+  firstName: string
+  lastName: string
+  accountId?: string
+  timeZone?: string
+  language?: string
+}
+```
+
+### Parameters
+
+```typescript
+interface ListUsersParams {
+  pageSize?: number    // Results per page (default: 100, max: 1000)
+  pageToken?: string   // Pagination token
+  include?: string[]   // Additional fields (e.g., ['permissions'])
+}
+
+interface GetUserParams {
+  include?: string[]   // Additional fields to include
+}
+```
+
+---
+
+## Functions
+
+### getCurrentUser()
+
+Get the current authenticated user's profile.
+
+```typescript
+import { getCurrentUser } from 'een-api-toolkit'
+
+const { data, error } = await getCurrentUser()
+
+if (error) {
+  if (error.code === 'AUTH_REQUIRED') {
+    router.push('/login')
+  }
+  return
+}
+
+console.log(`Welcome, ${data.firstName} ${data.lastName}`)
+```
+
+### getUsers(params?)
+
+List users with optional pagination.
+
+```typescript
+import { getUsers } from 'een-api-toolkit'
+
+// Basic usage
+const { data, error } = await getUsers()
+
+// With pagination
+const { data } = await getUsers({ pageSize: 50 })
+
+// With include
+const { data } = await getUsers({ include: ['permissions'] })
+```
+
+### getUser(userId, params?)
+
+Get a specific user by ID.
+
+```typescript
+import { getUser } from 'een-api-toolkit'
+
+const { data, error } = await getUser('user-id-123')
+
+if (error?.code === 'NOT_FOUND') {
+  console.log('User not found')
+  return
+}
+
+// With permissions
+const { data: userWithPerms } = await getUser('user-id-123', {
+  include: ['permissions']
+})
+```
+
+---
+
+## Pagination Example
+
+```typescript
+async function fetchAllUsers(): Promise<User[]> {
+  const allUsers: User[] = []
+  let pageToken: string | undefined
+
+  do {
+    const { data, error } = await getUsers({ pageSize: 100, pageToken })
+    if (error) break
+    allUsers.push(...data.results)
+    pageToken = data.nextPageToken
+  } while (pageToken)
+
+  return allUsers
+}
+```
+
+---
+
+## Complete Vue Component
+
+```vue
+<script setup lang="ts">
+import { ref, computed, onMounted } from 'vue'
+import { getUsers, type User, type EenError, type ListUsersParams } from 'een-api-toolkit'
+
+// Reactive state
+const users = ref<User[]>([])
+const loading = ref(false)
+const error = ref<EenError | null>(null)
+const nextPageToken = ref<string | undefined>(undefined)
+
+const hasNextPage = computed(() => !!nextPageToken.value)
+
+const params = ref<ListUsersParams>({ pageSize: 10 })
+
+async function fetchUsers(fetchParams?: ListUsersParams, append = false) {
+  loading.value = true
+  error.value = null
+
+  const mergedParams = { ...params.value, ...fetchParams }
+  const result = await getUsers(mergedParams)
+
+  if (result.error) {
+    error.value = result.error
+    if (!append) {
+      users.value = []
+    }
+    nextPageToken.value = undefined
+  } else {
+    if (append) {
+      users.value = [...users.value, ...result.data.results]
+    } else {
+      users.value = result.data.results
+    }
+    nextPageToken.value = result.data.nextPageToken
+  }
+
+  loading.value = false
+  return result
+}
+
+function refresh() {
+  return fetchUsers()
+}
+
+async function fetchNextPage() {
+  if (!nextPageToken.value) return
+  return fetchUsers({ ...params.value, pageToken: nextPageToken.value }, true)
+}
+
+onMounted(() => {
+  fetchUsers()
+})
+</script>
+
+<template>
+  <div class="users">
+    <div class="header">
+      <h2>Users</h2>
+      <button @click="refresh" :disabled="loading">
+        {{ loading ? 'Loading...' : 'Refresh' }}
+      </button>
+    </div>
+
+    <div v-if="loading && users.length === 0" class="loading">
+      Loading users...
+    </div>
+
+    <div v-else-if="error" class="error">
+      Error: {{ error.message }}
+    </div>
+
+    <div v-else>
+      <table v-if="users.length > 0">
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Email</th>
+            <th>Status</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr v-for="user in users" :key="user.id">
+            <td>{{ user.firstName }} {{ user.lastName }}</td>
+            <td>{{ user.email }}</td>
+            <td>
+              <span :class="user.isActive ? 'active' : 'inactive'">
+                {{ user.isActive ? 'Active' : 'Inactive' }}
+              </span>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+
+      <p v-else>No users found.</p>
+
+      <div v-if="hasNextPage" class="pagination">
+        <button @click="fetchNextPage" :disabled="loading">
+          {{ loading ? 'Loading...' : 'Load More' }}
+        </button>
+      </div>
+    </div>
+  </div>
+</template>
+```
+
+---
+
+## Reference Example
+
+See `examples/vue-users/src/views/Users.vue`

package/examples/vue-event-subscriptions/.env.example

@@ -0,0 +1,15 @@
+# EEN API Toolkit Configuration
+# Copy this file to .env and fill in your values
+
+# OAuth Proxy URL (required)
+VITE_PROXY_URL=http://localhost:8787
+
+# EEN OAuth Client ID (required)
+VITE_EEN_CLIENT_ID=your_client_id_here
+
+# OAuth Redirect URI (required)
+# Must match the redirect URI configured in your EEN OAuth client
+VITE_REDIRECT_URI=http://127.0.0.1:3333
+
+# Enable debug logging (optional)
+VITE_DEBUG=true

package/examples/vue-event-subscriptions/README.md

@@ -0,0 +1,103 @@
+# Event Subscriptions Example
+
+This example demonstrates how to use the Event Subscriptions API from the EEN API Toolkit to create SSE subscriptions and receive real-time events from cameras.
+
+## Features
+
+- Create and delete event subscriptions with SSE delivery
+- View active subscriptions with pagination
+- Select cameras and event types for filtering
+- Connect to SSE streams for live events
+- Real-time event display with auto-scrolling
+
+## Prerequisites
+
+1. Node.js 20 LTS or later
+2. EEN OAuth credentials (client ID and secret)
+3. Running OAuth proxy server (from `../een-oauth-proxy`)
+
+## Setup
+
+1. Copy the environment file:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Edit `.env` with your configuration:
+   - `VITE_PROXY_URL`: URL of your OAuth proxy server
+   - `VITE_EEN_CLIENT_ID`: Your EEN OAuth client ID
+   - `VITE_REDIRECT_URI`: OAuth redirect URI (default: http://127.0.0.1:3333)
+   - `VITE_DEBUG`: Enable debug logging (optional)
+
+3. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+4. Start the OAuth proxy (in a separate terminal):
+   ```bash
+   cd ../een-oauth-proxy
+   npm run dev
+   ```
+
+5. Start the example app:
+   ```bash
+   npm run dev
+   ```
+
+6. Open http://127.0.0.1:3333 in your browser
+
+## Usage
+
+### Creating a Subscription
+
+1. Log in with your Eagle Eye Networks account
+2. Go to "Subscriptions" page
+3. Select one or more cameras from the dropdown
+4. Select one or more event types
+5. Click "Create Subscription"
+
+### Viewing Live Events
+
+1. Go to "Live Events" page
+2. Select a subscription from the dropdown
+3. Click "Connect"
+4. Events will appear in real-time as they occur
+5. Click "Disconnect" to stop receiving events
+
+## API Functions Used
+
+- `listEventSubscriptions()` - List all subscriptions
+- `getEventSubscription(id)` - Get a specific subscription
+- `createEventSubscription(params)` - Create a new subscription
+- `deleteEventSubscription(id)` - Delete a subscription
+- `connectToEventSubscription(sseUrl, options)` - Connect to SSE stream
+- `getCameras()` - List cameras for filter selection
+- `listEventTypes()` - List event types for filter selection
+
+## Event Subscription Lifecycle
+
+SSE subscriptions are **temporary** by default:
+- Automatically created with a time-to-live (TTL)
+- Deleted when no client is connected after TTL expires
+- Can be manually deleted at any time
+
+## Troubleshooting
+
+### No events appearing
+
+- Ensure the camera has activity (motion, etc.)
+- Check that the subscription has the correct event types
+- Verify the SSE connection status shows "connected"
+
+### Connection errors
+
+- Verify the OAuth proxy is running
+- Check that your token is valid (re-login if needed)
+- Ensure the subscription still exists (may have expired)
+
+### Cannot create subscription
+
+- Ensure you have cameras in your account
+- Check that event types are loaded
+- Verify your account has permission to create subscriptions

package/examples/vue-event-subscriptions/e2e/app.spec.ts

@@ -0,0 +1,71 @@
+import { test, expect } from '@playwright/test'
+
+test.describe('Event Subscriptions Example - App', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/')
+  })
+
+  test('app loads with correct title', async ({ page }) => {
+    await expect(page).toHaveTitle(/Event Subscriptions/)
+  })
+
+  test('header displays app name', async ({ page }) => {
+    await expect(page.locator('[data-testid="app-title"]')).toHaveText('EEN Event Subscriptions')
+  })
+
+  test('navigation shows Home and Login links when not authenticated', async ({ page }) => {
+    // Home link should be visible
+    await expect(page.locator('[data-testid="nav-home"]')).toBeVisible()
+
+    // Login link should be visible (not authenticated)
+    await expect(page.locator('[data-testid="nav-login"]')).toBeVisible()
+
+    // Subscriptions, Live, and Logout should NOT be visible (requires auth)
+    await expect(page.locator('[data-testid="nav-subscriptions"]')).not.toBeVisible()
+    await expect(page.locator('[data-testid="nav-live"]')).not.toBeVisible()
+    await expect(page.locator('[data-testid="nav-logout"]')).not.toBeVisible()
+  })
+
+  test('home page shows not logged in message', async ({ page }) => {
+    await expect(page.locator('[data-testid="not-authenticated"]')).toBeVisible()
+    await expect(page.locator('[data-testid="not-authenticated-message"]')).toBeVisible()
+    await expect(page.locator('[data-testid="login-button"]')).toBeVisible()
+  })
+
+  test('login page displays login button', async ({ page }) => {
+    await page.goto('/login')
+
+    await expect(page.locator('[data-testid="login-title"]')).toHaveText('Login')
+    await expect(page.locator('[data-testid="login-button"]')).toBeVisible()
+  })
+
+  test('protected route (subscriptions) redirects to login', async ({ page }) => {
+    await page.goto('/subscriptions')
+
+    // Should be redirected to login page
+    await page.waitForURL('/login')
+    await expect(page).toHaveURL('/login')
+    await expect(page.locator('[data-testid="login-title"]')).toHaveText('Login')
+  })
+
+  test('protected route (live) redirects to login', async ({ page }) => {
+    await page.goto('/live')
+
+    // Should be redirected to login page
+    await page.waitForURL('/login')
+    await expect(page).toHaveURL('/login')
+    await expect(page.locator('[data-testid="login-title"]')).toHaveText('Login')
+  })
+
+  test('navigation between pages works', async ({ page }) => {
+    // Click Login link
+    await page.click('[data-testid="nav-login"]')
+    await page.waitForURL('/login')
+    await expect(page).toHaveURL('/login')
+
+    // Click Home link
+    await page.click('[data-testid="nav-home"]')
+    await page.waitForURL('/')
+    await expect(page).toHaveURL('/')
+  })
+})