een-api-toolkit 0.0.8 → 0.0.13

package/README.md

@@ -1,30 +1,56 @@
 # een-api-toolkit
 
-A TypeScript library implementing the [Eagle Eye Networks (EEN)](https://een.com/) Video platform API v3.0 for Vue 3 Composition API applications. See also the [EEN Developer Portal](https://developer.eagleeyenetworks.com). 
+A TypeScript library for the [Eagle Eye Networks](https://een.com/) Video API v3.0, designed for Vue 3 applications.
 
-This repository is provided as-is without any warranty, functionality guarantee, or assurance of availability. This repository uses EEN services, but it is not associated with EEN.
+## Purpose
+
+This toolkit aims to **simplify and accelerate web application development** for the EEN Video Platform. By providing ready-to-use composables, type-safe APIs, and secure authentication patterns, developers can focus on building features rather than wrestling with API integration details.
+
+The project is also designed to **enable AI-assisted software development**. With comprehensive documentation, clear code patterns, and an AI-optimized context file (`docs/AI-CONTEXT.md`), AI coding assistants can effectively help developers build, extend, and maintain applications using this toolkit.
 
 > **Note:** Work in progress - do not use in production yet.
 
-## Installation
+## Key Features
+
+- **Vue 3 Composables** - Reactive state with `useCurrentUser()`, `useUsers()`, `useUser()`
+- **Plain Functions** - Framework-agnostic `getCurrentUser()`, `getUsers()`, `getUser()`
+- **Secure OAuth** - Token management via proxy (refresh tokens never exposed to client)
+- **Type-Safe** - Full TypeScript types from OpenAPI spec
+- **Predictable Errors** - Always returns `{data, error}`, no exceptions thrown
+
+## OAuth Proxy Requirement
+
+This toolkit's authentication is designed to work with [een-oauth-proxy](https://github.com/klaushofrichter/een-oauth-proxy), a secure OAuth proxy implementation that:
+
+- Keeps refresh tokens server-side (never exposed to the browser)
+- Handles token exchange and refresh automatically
+- Provides session management via secure cookies
+
+**Using a different proxy?** While other OAuth proxy implementations can be used, you may need to adapt the authentication flow. The toolkit expects specific proxy endpoints (`/proxy/getAccessToken`, `/proxy/refreshAccessToken`, `/proxy/revoke`).
+
+## Quick Start
+
+### 1. Install
 
 ```bash
 npm install een-api-toolkit
 ```
 
-**Development (from source):**
+### 2. Set Up OAuth Proxy
+
+The toolkit requires an OAuth proxy to securely handle authentication. See [een-oauth-proxy](https://github.com/klaushofrichter/een-oauth-proxy) for a Cloudflare Worker implementation.
+
 ```bash
-git clone https://github.com/klaushofrichter/een-api-toolkit.git
-cd een-api-toolkit
+# Clone and start the proxy
+git clone https://github.com/klaushofrichter/een-oauth-proxy.git
+cd een-oauth-proxy/proxy
 npm install
-npm run build
-npm link
-
-# In your project:
-npm link een-api-toolkit
+npm run dev  # Runs at http://localhost:8787
 ```
 
-## Setup
+> **Important:** Your app must run on `http://127.0.0.1:3333` (not `localhost`) and handle OAuth callbacks on the root path `/`. The EEN Identity Provider requires an exact URI match. See [Troubleshooting](./docs/USER-GUIDE.md#oauth-redirect-uri-requirements-critical) for details.
+
+### 3. Initialize in Your App
 
 ```typescript
 // main.ts
@@ -36,286 +62,138 @@ import App from './App.vue'
 const app = createApp(App)
 app.use(createPinia())
 
-// Initialize toolkit with proxy URL from environment
 initEenToolkit({
-  proxyUrl: import.meta.env.VITE_PROXY_URL
+  proxyUrl: import.meta.env.VITE_PROXY_URL,  // http://localhost:8787
+  clientId: import.meta.env.VITE_EEN_CLIENT_ID
 })
 
 app.mount('#app')
 ```
 
-## Authentication
-
-The toolkit uses OAuth via a proxy server. Your app handles the redirect flow:
+### 4. Add Authentication
 
 ```typescript
-// Login.vue
 import { getAuthUrl, handleAuthCallback } from 'een-api-toolkit'
 
-// Redirect user to EEN login
+// Redirect to EEN login
 const login = () => {
   window.location.href = getAuthUrl()
 }
 
-// Handle OAuth callback (after redirect back)
+// Handle callback (after EEN redirects back)
 const onCallback = async (code: string, state: string) => {
-  const { data, error } = await handleAuthCallback(code, state)
+  const { error } = await handleAuthCallback(code, state)
   if (error) {
     console.error('Auth failed:', error.message)
     return
   }
-  // User is now authenticated, token stored in Pinia
+  // User is authenticated, token stored in Pinia
   router.push('/dashboard')
 }
 ```
 
-## Usage
+### 5. Use the API
 
-### Vue 3 Composables (Reactive)
+**Vue Composables (reactive):**
 
 ```vue
 <script setup>
 import { useCurrentUser, useUsers } from 'een-api-toolkit'
 
-// Get current authenticated user
-const { user, loading, error, refresh } = useCurrentUser()
-
-// List all users with pagination
-const { users, loading: usersLoading, hasNextPage, fetchNextPage } = useUsers()
+const { user, loading, error } = useCurrentUser()
+const { users, hasNextPage, fetchNextPage } = useUsers({ pageSize: 10 })
 </script>
 
 <template>
   <div v-if="loading">Loading...</div>
-  <div v-else-if="error">Error: {{ error.message }}</div>
+  <div v-else-if="error">{{ error.message }}</div>
   <div v-else>
     <h1>Welcome, {{ user.firstName }}</h1>
-    <h2>All Users:</h2>
     <ul>
       <li v-for="u in users" :key="u.id">{{ u.email }}</li>
     </ul>
     <button v-if="hasNextPage" @click="fetchNextPage">Load More</button>
-    <button @click="refresh">Refresh</button>
   </div>
 </template>
 ```
 
-### Plain Functions (Framework-Agnostic)
+**Plain Functions (framework-agnostic):**
 
 ```typescript
-import { getUsers, getCameras, getBridges } from 'een-api-toolkit'
+import { getUsers, getCurrentUser } from 'een-api-toolkit'
 
-const fetchData = async () => {
-  const { data: users, error } = await getUsers()
-  if (error) {
-    console.error(error.code, error.message)
-    return
-  }
-  console.log('Users:', users)
+// Get current authenticated user
+const { data: currentUser, error: userError } = await getCurrentUser()
+if (userError) {
+  console.error(userError.code, userError.message)
+} else {
+  console.log('Current user:', currentUser.email)
 }
 
-// With pagination
-const { data, error } = await getCameras({
-  pageSize: 50,
-  pageToken: 'next-page-token'
-})
-```
-
-## Error Handling
-
-All functions return `{data, error}` objects - they never throw exceptions:
-
-```typescript
-const { data, error } = await getCameras()
-
+// Get list of users
+const { data: users, error } = await getUsers()
 if (error) {
-  switch (error.code) {
-    case 'AUTH_REQUIRED':
-      router.push('/login')
-      break
-    case 'API_ERROR':
-      showNotification(`API Error: ${error.message}`)
-      break
-    case 'NETWORK_ERROR':
-      showNotification('Network unavailable')
-      break
-  }
-  return
+  console.error(error.code, error.message)
+} else {
+  console.log('Users:', users.results)
 }
-
-// Safe to use data here
-console.log(data)
-```
-
-## Configuration
-
-### Environment Variables
-
-Copy `.env.example` to `.env` and configure:
-
-```env
-# EEN OAuth Client ID (required for authentication)
-VITE_EEN_CLIENT_ID=your-een-client-id
-
-# Test credentials for Playwright E2E tests
-TEST_USER=your-test-email@example.com
-TEST_PASSWORD=your-test-password
-
-# OAuth proxy URL (required for API calls)
-# Use local proxy for development to avoid Cloudflare rate limits
-VITE_PROXY_URL=http://localhost:8787
-
-# npm access token for publishing (Automation type from npmjs.com)
-NPM_TOKEN=npm_xxxxxxxxxxxx
-
-# Slack webhook for notifications
-SLACK_WEBHOOK=https://hooks.slack.com/services/xxx/xxx/xxx
-
-# Anthropic API key for Claude code review
-ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx
-```
-
-### GitHub Secrets
-
-GitHub Actions workflows require these secrets. Sync them from your `.env` file:
-
-```bash
-# Preview what will be synced
-./scripts/sync-secrets.sh --dry-run
-
-# Sync secrets to GitHub
-./scripts/sync-secrets.sh
-```
-
-Required secrets:
-| Secret | Purpose |
-|--------|---------|
-| `VITE_EEN_CLIENT_ID` | EEN OAuth client ID |
-| `TEST_USER` | E2E test user email |
-| `TEST_PASSWORD` | E2E test user password |
-| `VITE_PROXY_URL` | OAuth proxy URL |
-| `NPM_TOKEN` | npm publish token |
-| `SLACK_WEBHOOK` | Slack notifications |
-| `ANTHROPIC_API_KEY` | Claude code review |
-
-### Local Proxy Server
-
-For development, run the local OAuth proxy to avoid Cloudflare rate limits:
-
-```bash
-cd ../een-oauth-proxy/proxy
-npm run dev
-```
-
-This starts the proxy at `http://localhost:8787`. The proxy must be running for authentication and API calls to work.
-
-### Running E2E Tests
-
-E2E tests use Playwright to authenticate with EEN and test actual API calls.
-
-**Prerequisites:**
-1. Ensure the OAuth proxy is running:
-   ```bash
-   ./scripts/restart-proxy.sh
-   ```
-
-2. Set test credentials in `.env`:
-   ```env
-   TEST_USER=your-test-email@example.com
-   TEST_PASSWORD=your-test-password
-   VITE_EEN_CLIENT_ID=your-client-id
-   VITE_PROXY_URL=http://localhost:8787
-   ```
-
-**Run tests:**
-```bash
-npm run test:e2e        # Run all E2E tests
-npm run test:e2e:ui     # Run with Playwright UI
-```
-
-**Token caching:** Auth tokens are cached in `e2e/.auth-state.json` (with 5-minute expiry buffer) to speed up repeated test runs. Delete this file to force re-authentication.
-
-**Security note:** The cached access token is stored in plaintext. This is acceptable for development/testing because:
-- The token is short-lived (~1 hour)
-- The file has restricted permissions (owner read/write only)
-- The file is excluded from git
-
-**Cleanup after tests:**
-```bash
-./scripts/cleanup-auth.sh   # Revokes token and removes cache file
 ```
 
 ## Architecture
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│                   Developer's Vue 3 App                 │
-│  ┌─────────────────────────────────────────────────┐   │
-│  │              import from 'een-api-toolkit'       │   │
-│  │  ┌──────────────┐    ┌────────────────────┐     │   │
-│  │  │ Composables  │    │  Plain Functions   │     │   │
-│  │  │ useUsers()   │    │  getUsers()        │     │   │
-│  │  │ useCameras() │    │  getCameras()      │     │   │
-│  │  └──────────────┘    └────────────────────┘     │   │
-│  └─────────────────────────────────────────────────┘   │
-│                          │                              │
-│                          ▼                              │
-│              ┌─────────────────────┐                   │
-│              │   Pinia Auth Store  │                   │
-│              │   (token, baseUrl)  │                   │
-│              └─────────────────────┘                   │
-└─────────────────────────────────────────────────────────┘
-                           │
-                           ▼
-              ┌─────────────────────┐
-              │    OAuth Proxy      │
-              │ (Cloudflare Worker) │
-              └─────────────────────┘
-                           │
-                           ▼
-              ┌─────────────────────┐
-              │     EEN API v3.0    │
-              └─────────────────────┘
-```
-
-## Key Features
-
-- **No direct API credentials** - OAuth handled via proxy
-- **Reactive or plain** - Choose composables for Vue reactivity, plain functions for flexibility
-- **Predictable errors** - Always `{data, error}`, no try/catch needed
-- **Auto token refresh** - Handled internally by the toolkit
-- **Type-safe** - Full TypeScript types from OpenAPI spec
-
-## Publishing (for maintainers)
-
-The package is published to npm automatically when changes are merged to the `production` branch.
-
-### Version Management
-- Patch version auto-increments on each commit (via Husky pre-commit hook)
-- Minor/major versions updated manually in `package.json`
-
-### Release Flow
-```
-feature branch → develop → production → npm publish
-```
-
-### Manual Publish
-```bash
-npm login
-npm run build
-npm publish
+┌──────────────────────────────────────────────────────────────────────┐
+│                         Your Vue 3 App                                │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │                   import from 'een-api-toolkit'                 │  │
+│  │  ┌──────────────┐    ┌────────────────────┐                    │  │
+│  │  │ Composables  │    │  Plain Functions   │                    │  │
+│  │  │ useUsers()   │    │  getUsers()        │                    │  │
+│  │  │ useUser()    │    │  getUser()         │                    │  │
+│  │  └──────────────┘    └────────────────────┘                    │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+│                    │                              │                   │
+│                    ▼                              ▼                   │
+│       ┌─────────────────────┐        ┌─────────────────────┐         │
+│       │   Pinia Auth Store  │        │   API Calls with    │         │
+│       │   (token, baseUrl)  │        │   Bearer Token      │         │
+│       └─────────────────────┘        └─────────────────────┘         │
+└────────────────────│─────────────────────────────│───────────────────┘
+                     │                             │
+        Auth calls   │                             │  API calls
+     (login/refresh) │                             │  (data)
+                     ▼                             ▼
+        ┌─────────────────────┐       ┌─────────────────────┐
+        │    OAuth Proxy      │       │     EEN API v3.0    │
+        │  (local or cloud)   │       │                     │
+        └─────────────────────┘       └─────────────────────┘
+                     │
+                     ▼
+        ┌─────────────────────┐
+        │    EEN OAuth        │
+        └─────────────────────┘
 ```
 
 ## Documentation
 
-- [AI-CONTEXT.md](./docs/AI-CONTEXT.md) - Comprehensive single-file reference for AI assistants
-- [API Reference](./docs/api/) - Auto-generated TypeDoc documentation
-- [Example App](./examples/vue-basic/) - Complete Vue 3 example application
+| Document | Description |
+|----------|-------------|
+| **[User Guide](./docs/USER-GUIDE.md)** | Installation, proxy setup, configuration, building apps |
+| **[Developer Guide](./docs/DEVELOPER-GUIDE.md)** | Architecture, testing, CI/CD, contributing |
+| **[API Reference](./docs/api/)** | Auto-generated TypeDoc documentation |
+| **[Example App](./examples/vue-basic/)** | Complete Vue 3 example with OAuth flow |
+| **[AI Context](./docs/AI-CONTEXT.md)** | Single-file reference for AI assistants |
 
-## API Reference
+## External Resources
 
-- [EEN API 3.0 Documentation](https://developer.eagleeyenetworks.com/reference/using-the-api)
-- [EEN API 3.0 Spec](https://github.com/EENCloud/api-v3-documentation/tree/development/api/3.0)
+- [EEN Developer Portal](https://developer.eagleeyenetworks.com/)
+- [EEN API v3.0 Documentation](https://developer.eagleeyenetworks.com/reference/using-the-api)
+- [een-oauth-proxy](https://github.com/klaushofrichter/een-oauth-proxy) - OAuth proxy server
 
 ## License
 
 MIT
+
+---
+
+This repository is provided as-is without warranty. It uses EEN services but is not affiliated with Eagle Eye Networks.