een-api-toolkit 0.3.47 → 0.3.49

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

@@ -1,6 +1,6 @@
 # Media & Live Video - EEN API Toolkit
 
-> **Version:** 0.3.47
+> **Version:** 0.3.49
 >
 > Complete reference for media retrieval, live streaming, and video playback.
 > Load this document when implementing video features.

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

@@ -1,6 +1,6 @@
 # Vue 3 Application Setup - EEN API Toolkit
 
-> **Version:** 0.3.47
+> **Version:** 0.3.49
 >
 > 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.

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

@@ -1,6 +1,6 @@
 # Users API - EEN API Toolkit
 
-> **Version:** 0.3.47
+> **Version:** 0.3.49
 >
 > Complete reference for user management.
 > Load this document when working with user data.

package/examples/vue-jobs/.env.example

@@ -0,0 +1,11 @@
+# OAuth Proxy URL (required)
+VITE_PROXY_URL=http://localhost:8787
+
+# EEN OAuth Client ID (required)
+VITE_EEN_CLIENT_ID=your-client-id
+
+# OAuth Redirect URI (must match exactly)
+VITE_REDIRECT_URI=http://127.0.0.1:3333
+
+# Enable debug logging
+VITE_DEBUG=true

package/examples/vue-jobs/README.md

@@ -0,0 +1,245 @@
+# EEN API Toolkit - Vue Jobs Example
+
+A complete example showing how to use the Jobs, Files, and Exports APIs from the een-api-toolkit in a Vue 3 application.
+
+## Storage Strategy: Memory
+
+This example uses the `memory` storage strategy for maximum security. This means:
+
+- **Tokens are never written to disk** - immune to localStorage/sessionStorage XSS attacks
+- **Page refresh requires re-authentication** - tokens exist only in memory
+- **Each tab is independent** - opening a new tab requires separate login
+
+This is the recommended strategy for high-security deployments where protecting against XSS token theft is critical.
+
+## Features Demonstrated
+
+- OAuth authentication flow (login, callback, logout)
+- Protected routes with navigation guards
+- List jobs with state filtering (pending, started, success, failure)
+- View job details with real-time progress polling
+- Create video exports from cameras
+- List and download files
+- Error handling with Result pattern
+- Reactive authentication state
+
+## APIs Used
+
+- `listJobs()` - List jobs with filtering and pagination
+- `getJob()` - Get single job details
+- `createExportJob()` - Create video export job
+- `listFiles()` - List files with pagination
+- `downloadFile()` - Download file content
+- `getCameras()` - Get cameras for export selection
+- `useAuthStore()` - Authentication state management
+- `getAuthUrl()` - Generate OAuth login URL
+- `handleAuthCallback()` - Process OAuth callback
+- `initEenToolkit()` - Toolkit initialization
+
+## Setup
+
+### Prerequisites
+
+1. **Start the OAuth proxy** (required for authentication):
+
+   The OAuth proxy is a separate project that handles token management securely.
+   Clone and run it from: https://github.com/klaushofrichter/een-oauth-proxy
+
+   ```bash
+   # In a separate terminal, from the een-oauth-proxy directory
+   npm install
+   npm run dev
+   ```
+
+   The proxy should be running at `http://localhost:8787`.
+
+### Example Setup
+
+All commands below should be run from this example directory (`examples/vue-jobs/`):
+
+2. Copy the environment file:
+   ```bash
+   # From examples/vue-jobs/
+   cp .env.example .env
+   ```
+
+3. Edit `.env` with your EEN credentials:
+   ```env
+   VITE_EEN_CLIENT_ID=your-client-id
+   VITE_PROXY_URL=http://localhost:8787
+   # DO NOT change the redirect URI - EEN IDP only permits this URL
+   VITE_REDIRECT_URI=http://127.0.0.1:3333
+   ```
+
+4. Install dependencies and start:
+   ```bash
+   # From examples/vue-jobs/
+   npm install
+   npm run dev
+   ```
+
+5. Open http://127.0.0.1:3333 in your browser.
+
+**Important:** The EEN Identity Provider only permits `http://127.0.0.1:3333` as the OAuth redirect URI. Do not use `localhost` or other ports.
+
+**Note:** Development and testing was done on macOS. The `npm run stop` command uses `lsof`, which is not available on Windows. Windows users should manually stop any process on port 3333 or use `npx kill-port 3333` instead.
+
+## Project Structure
+
+```
+src/
+├── main.ts          # App entry, toolkit initialization
+├── App.vue          # Root component with navigation
+├── router/
+│   └── index.ts     # Vue Router with auth guards
+└── views/
+    ├── Home.vue       # Home page with user profile
+    ├── Login.vue      # OAuth login redirect
+    ├── Callback.vue   # OAuth callback handler
+    ├── Jobs.vue       # Job list with state filters
+    ├── JobDetail.vue  # Single job with progress polling
+    ├── Files.vue      # File browser with download
+    ├── CreateExport.vue # Export creation form
+    └── Logout.vue     # Logout handler
+```
+
+## Key Code Examples
+
+### Initializing the Toolkit (main.ts)
+
+```typescript
+import { initEenToolkit } from 'een-api-toolkit'
+
+initEenToolkit({
+  proxyUrl: import.meta.env.VITE_PROXY_URL,
+  clientId: import.meta.env.VITE_EEN_CLIENT_ID,
+  storageStrategy: 'memory',  // Maximum security - tokens lost on refresh
+  debug: true
+})
+```
+
+### Listing Jobs with State Filtering (Jobs.vue)
+
+```typescript
+import { ref } from 'vue'
+import { listJobs, type Job, type JobState, type ListJobsParams } from 'een-api-toolkit'
+
+const jobs = ref<Job[]>([])
+const selectedStates = ref<JobState[]>([])
+
+async function fetchJobs(params: ListJobsParams) {
+  const mergedParams: ListJobsParams = { ...params }
+  if (selectedStates.value.length > 0) {
+    mergedParams.state__in = selectedStates.value
+  }
+
+  const result = await listJobs(mergedParams)
+  if (result.error) {
+    // Handle error
+  } else {
+    jobs.value = result.data.results
+  }
+}
+```
+
+### Polling Job Progress (JobDetail.vue)
+
+```typescript
+import { ref, onMounted, onUnmounted } from 'vue'
+import { getJob, type Job } from 'een-api-toolkit'
+
+const job = ref<Job | null>(null)
+let pollInterval: ReturnType<typeof setInterval> | null = null
+
+async function fetchJob(jobId: string) {
+  const result = await getJob(jobId)
+  if (result.error) {
+    // Handle error
+  } else {
+    job.value = result.data
+
+    // Auto-start polling if job is in progress
+    if (['pending', 'started'].includes(result.data.state)) {
+      startPolling()
+    } else {
+      stopPolling()
+    }
+  }
+}
+
+function startPolling() {
+  if (pollInterval) return
+  pollInterval = setInterval(() => fetchJob(jobId), 3000)
+}
+
+function stopPolling() {
+  if (pollInterval) {
+    clearInterval(pollInterval)
+    pollInterval = null
+  }
+}
+
+onUnmounted(() => stopPolling())
+```
+
+### Creating an Export (CreateExport.vue)
+
+```typescript
+import { createExportJob, formatTimestamp, type ExportType } from 'een-api-toolkit'
+
+async function handleSubmit() {
+  const endTime = new Date()
+  const startTime = new Date(endTime.getTime() - duration.value * 60 * 1000)
+
+  const result = await createExportJob({
+    name: exportName.value || `Export - ${new Date().toLocaleString()}`,
+    type: exportType.value,
+    cameraId: selectedCamera.value,
+    startTimestamp: formatTimestamp(startTime.toISOString()),
+    endTimestamp: formatTimestamp(endTime.toISOString())
+  })
+
+  if (result.error) {
+    // Handle error
+  } else {
+    // Navigate to job detail page
+    router.push(`/jobs/${result.data.id}`)
+  }
+}
+```
+
+### Downloading Files (Files.vue)
+
+```typescript
+import { downloadFile, type EenFile } from 'een-api-toolkit'
+
+async function handleDownload(file: EenFile) {
+  const result = await downloadFile(file.id)
+
+  if (result.error) {
+    // Handle error
+  } else {
+    // Create download link
+    const url = URL.createObjectURL(result.data.blob)
+    const a = document.createElement('a')
+    a.href = url
+    a.download = result.data.filename || file.name
+    a.click()
+    URL.revokeObjectURL(url)
+  }
+}
+```
+
+### Auth Guard (router/index.ts)
+
+```typescript
+router.beforeEach((to, from, next) => {
+  const authStore = useAuthStore()
+
+  if (to.meta.requiresAuth && !authStore.isAuthenticated) {
+    next('/login')
+  } else {
+    next()
+  }
+})
+```

package/examples/vue-jobs/e2e/app.spec.ts

@@ -0,0 +1,79 @@
+import { test, expect } from '@playwright/test'
+
+test.describe('Vue Jobs Example - App', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/')
+  })
+
+  test('app loads with correct title', async ({ page }) => {
+    await expect(page).toHaveTitle(/EEN Jobs/)
+  })
+
+  test('header displays app name', async ({ page }) => {
+    await expect(page.locator('[data-testid="app-title"]')).toHaveText('EEN Jobs Example')
+  })
+
+  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()
+
+    // Jobs, Files, Create Export, and Logout should NOT be visible (requires auth)
+    await expect(page.locator('[data-testid="nav-jobs"]')).not.toBeVisible()
+    await expect(page.locator('[data-testid="nav-files"]')).not.toBeVisible()
+    await expect(page.locator('[data-testid="nav-create-export"]')).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 /jobs redirects to login', async ({ page }) => {
+    await page.goto('/jobs')
+
+    // 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 /files redirects to login', async ({ page }) => {
+    await page.goto('/files')
+
+    // Should be redirected to login page
+    await page.waitForURL('/login')
+    await expect(page).toHaveURL('/login')
+  })
+
+  test('protected route /create-export redirects to login', async ({ page }) => {
+    await page.goto('/create-export')
+
+    // Should be redirected to login page
+    await page.waitForURL('/login')
+    await expect(page).toHaveURL('/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('/')
+  })
+})