een-api-toolkit 0.0.8 → 0.0.13

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

@@ -0,0 +1,12 @@
+# EEN OAuth Client ID (required)
+VITE_EEN_CLIENT_ID=your-een-client-id
+
+# OAuth Proxy URL (required)
+VITE_PROXY_URL=http://localhost:8787
+
+# OAuth Redirect URI (MUST be http://127.0.0.1:3333 - EEN IDP requirement)
+# Do not change this value - the EEN Identity Provider only permits this URL
+VITE_REDIRECT_URI=http://127.0.0.1:3333
+
+# Enable debug logging (optional)
+VITE_DEBUG=true

package/examples/vue-basic/README.md

@@ -0,0 +1,146 @@
+# EEN API Toolkit - Vue 3 Example
+
+A complete example showing how to use the een-api-toolkit in a Vue 3 application.
+
+## Features Demonstrated
+
+- OAuth authentication flow (login, callback, logout)
+- Protected routes with navigation guards
+- useCurrentUser composable for current user profile
+- useUsers composable with pagination
+- Error handling
+- Reactive authentication state
+
+## 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-basic/`):
+
+2. Copy the environment file:
+   ```bash
+   # From examples/vue-basic/
+   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-basic/
+   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.
+
+## 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
+    ├── Users.vue    # User list with pagination
+    └── 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,
+  debug: true
+})
+```
+
+### OAuth Login (Login.vue)
+
+```typescript
+import { getAuthUrl } from 'een-api-toolkit'
+
+function login() {
+  window.location.href = getAuthUrl()
+}
+```
+
+### OAuth Callback (Callback.vue)
+
+```typescript
+import { handleAuthCallback } from 'een-api-toolkit'
+
+const url = new URL(window.location.href)
+const code = url.searchParams.get('code')
+const state = url.searchParams.get('state')
+
+const { error } = await handleAuthCallback(code, state)
+if (error) {
+  // Handle error
+} else {
+  router.push('/dashboard')
+}
+```
+
+### Using Composables (Users.vue)
+
+```vue
+<script setup>
+import { useUsers } from 'een-api-toolkit'
+
+const { users, loading, error, hasNextPage, fetchNextPage } = useUsers({ pageSize: 10 })
+</script>
+
+<template>
+  <ul v-for="user in users" :key="user.id">
+    <li>{{ user.email }}</li>
+  </ul>
+  <button v-if="hasNextPage" @click="fetchNextPage">Load More</button>
+</template>
+```
+
+### 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-basic/e2e/app.spec.ts

@@ -0,0 +1,61 @@
+import { test, expect } from '@playwright/test'
+
+test.describe('Vue Basic Example - App', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/')
+  })
+
+  test('app loads with correct title', async ({ page }) => {
+    await expect(page).toHaveTitle(/EEN API Toolkit/)
+  })
+
+  test('header displays app name', async ({ page }) => {
+    await expect(page.locator('[data-testid="app-title"]')).toHaveText('EEN API Toolkit 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()
+
+    // Users and Logout should NOT be visible (requires auth)
+    await expect(page.locator('[data-testid="nav-users"]')).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 redirects to login', async ({ page }) => {
+    await page.goto('/users')
+
+    // 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('/')
+  })
+})

package/examples/vue-basic/e2e/auth.spec.ts

@@ -0,0 +1,260 @@
+import { test, expect, Page } from '@playwright/test'
+
+/**
+ * E2E tests for the Vue Basic Example
+ *
+ * Tests the OAuth login flow through the UI:
+ * 1. Click login button in the example app
+ * 2. Enter credentials on EEN OAuth page
+ * 3. Complete the OAuth callback
+ * 4. Verify authenticated state
+ *
+ * Required environment variables:
+ * - VITE_PROXY_URL: OAuth proxy URL (e.g., http://127.0.0.1:8787)
+ * - VITE_EEN_CLIENT_ID: EEN OAuth client ID
+ * - TEST_USER: Test user email
+ * - TEST_PASSWORD: Test user password
+ */
+
+// Timeout constants for consistent behavior
+// Values chosen based on OAuth flow timing requirements
+const TIMEOUTS = {
+  OAUTH_REDIRECT: 30000,   // OAuth redirects can be slow on first load
+  ELEMENT_VISIBLE: 15000,  // Wait for OAuth page elements to render
+  PASSWORD_VISIBLE: 10000, // Password field appears after email validation
+  AUTH_COMPLETE: 30000,    // Full OAuth flow completion
+  UI_UPDATE: 10000,        // UI state updates after auth changes
+  PROXY_CHECK: 5000        // Quick check if proxy is running
+} as const
+
+const TEST_USER = process.env.TEST_USER
+const TEST_PASSWORD = process.env.TEST_PASSWORD
+const PROXY_URL = process.env.VITE_PROXY_URL
+
+/**
+ * Checks if the OAuth proxy is accessible.
+ * Returns true if proxy responds (even with 404), false if unreachable.
+ */
+async function isProxyAccessible(): Promise<boolean> {
+  if (!PROXY_URL) return false
+  const controller = new AbortController()
+  const timeoutId = setTimeout(() => controller.abort(), TIMEOUTS.PROXY_CHECK)
+
+  try {
+    const response = await fetch(PROXY_URL, {
+      method: 'HEAD',
+      signal: controller.signal
+    })
+    // 404 is ok - means proxy is running but endpoint doesn't exist
+    return response.ok || response.status === 404
+  } catch {
+    return false
+  } finally {
+    clearTimeout(timeoutId)
+  }
+}
+
+/**
+ * Performs OAuth login flow through the UI.
+ * Starts from home page and completes full OAuth authentication.
+ */
+async function performLogin(page: Page, username: string, password: string): Promise<void> {
+  // Start at home page
+  await page.goto('/')
+
+  // Click login button and wait for OAuth redirect
+  await Promise.all([
+    page.waitForURL(/.*eagleeyenetworks.com.*/, { timeout: TIMEOUTS.OAUTH_REDIRECT }),
+    page.click('[data-testid="login-button"]')
+  ])
+
+  // Fill email
+  const emailInput = page.locator('#authentication--input__email')
+  await emailInput.waitFor({ state: 'visible', timeout: TIMEOUTS.ELEMENT_VISIBLE })
+  await emailInput.fill(username)
+
+  // Click next
+  await page.getByRole('button', { name: 'Next' }).click()
+
+  // Fill password
+  const passwordInput = page.locator('#authentication--input__password')
+  await passwordInput.waitFor({ state: 'visible', timeout: TIMEOUTS.PASSWORD_VISIBLE })
+  await passwordInput.fill(password)
+
+  // Click sign in - use OR selector for robustness
+  await page.locator('#next, button:has-text("Sign in")').first().click()
+
+  // Wait for auth to complete and redirect to app
+  await page.waitForURL('**/', { timeout: TIMEOUTS.AUTH_COMPLETE })
+}
+
+/**
+ * Clears browser storage to reset auth state.
+ * Handles cases where localStorage isn't accessible (e.g., about:blank, cross-origin).
+ */
+async function clearAuthState(page: Page): Promise<void> {
+  try {
+    // Only try to clear storage if we're on a page that allows it
+    const url = page.url()
+    if (url && url.startsWith('http')) {
+      await page.evaluate(() => {
+        try {
+          localStorage.clear()
+          sessionStorage.clear()
+        } catch {
+          // Ignore errors - storage may not be accessible
+        }
+      })
+    }
+  } catch {
+    // Ignore errors - page may be closed or in an inaccessible state
+  }
+}
+
+test.describe('Vue Basic Example', () => {
+  // Check proxy accessibility once before all tests
+  let proxyAccessible = false
+
+  // Helper functions to skip tests when prerequisites aren't met
+  function skipIfNoProxy() {
+    test.skip(!proxyAccessible, 'OAuth proxy not accessible')
+  }
+
+  function skipIfNoCredentials() {
+    test.skip(!TEST_USER || !TEST_PASSWORD, 'Test credentials not available')
+  }
+
+  function skipIfNoUser() {
+    test.skip(!TEST_USER, 'Test user not available')
+  }
+
+  test.beforeAll(async () => {
+    proxyAccessible = await isProxyAccessible()
+    if (!proxyAccessible) {
+      console.log('OAuth proxy not accessible - OAuth tests will be skipped')
+    }
+  })
+
+  test.afterEach(async ({ page }) => {
+    // Clear auth state after each test to prevent state pollution
+    await clearAuthState(page)
+  })
+
+  test('shows login button when not authenticated', async ({ page }) => {
+    await page.goto('/')
+    await expect(page.locator('[data-testid="not-authenticated"]')).toBeVisible()
+    await expect(page.locator('[data-testid="nav-login"]')).toBeVisible()
+    await expect(page.locator('[data-testid="nav-logout"]')).not.toBeVisible()
+  })
+
+  test('users page shows not-authenticated state without login', async ({ page }) => {
+    await page.goto('/users')
+    await expect(
+      page.locator('[data-testid="not-authenticated"], [data-testid="nav-login"], .error, .auth-required').first()
+    ).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+  })
+
+  test('login button redirects to OAuth page', async ({ page }) => {
+    skipIfNoProxy()
+    skipIfNoCredentials()
+
+    await page.goto('/')
+    await expect(page.locator('[data-testid="login-button"]')).toBeVisible()
+    await expect(page.locator('[data-testid="login-button"]')).toBeEnabled()
+
+    // Click login and verify redirect to OAuth page
+    await Promise.all([
+      page.waitForURL(/.*eagleeyenetworks.com.*/, { timeout: TIMEOUTS.OAUTH_REDIRECT }),
+      page.click('[data-testid="login-button"]')
+    ])
+
+    // Verify we're on the OAuth page
+    const emailInput = page.locator('#authentication--input__email')
+    await expect(emailInput).toBeVisible({ timeout: TIMEOUTS.ELEMENT_VISIBLE })
+  })
+
+  test('complete OAuth login flow', async ({ page }) => {
+    skipIfNoProxy()
+    skipIfNoCredentials()
+
+    // Verify initially not authenticated
+    await page.goto('/')
+    await expect(page.locator('[data-testid="not-authenticated"]')).toBeVisible()
+
+    // Perform login
+    await performLogin(page, TEST_USER!, TEST_PASSWORD!)
+
+    // Verify authenticated state
+    await expect(page.locator('[data-testid="not-authenticated"]')).not.toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+    await expect(page.locator('[data-testid="nav-users"]')).toBeVisible()
+    await expect(page.locator('[data-testid="nav-logout"]')).toBeVisible()
+    await expect(page.locator('[data-testid="nav-login"]')).not.toBeVisible()
+  })
+
+  test('can view users list after login', async ({ page }) => {
+    skipIfNoProxy()
+    skipIfNoCredentials()
+
+    await performLogin(page, TEST_USER!, TEST_PASSWORD!)
+    await expect(page.locator('[data-testid="nav-users"]')).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+
+    // Navigate to users page
+    await page.click('[data-testid="nav-users"]')
+    await page.waitForURL('/users')
+
+    // Should see users table (not error state)
+    await expect(page.locator('.users table')).toBeVisible({ timeout: TIMEOUTS.ELEMENT_VISIBLE })
+    await expect(page.locator('.error')).not.toBeVisible()
+  })
+
+  test('can logout after login', async ({ page }) => {
+    skipIfNoProxy()
+    skipIfNoCredentials()
+
+    await performLogin(page, TEST_USER!, TEST_PASSWORD!)
+    await expect(page.locator('[data-testid="nav-logout"]')).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+
+    // Click logout
+    await page.click('[data-testid="nav-logout"]')
+
+    // Should show not authenticated
+    await page.waitForURL('**/')
+    await expect(page.locator('[data-testid="not-authenticated"]')).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+    await expect(page.locator('[data-testid="nav-login"]')).toBeVisible()
+  })
+
+  test('invalid password shows error on OAuth page', async ({ page }) => {
+    skipIfNoProxy()
+    skipIfNoUser()
+
+    await page.goto('/')
+
+    // Click login and wait for OAuth redirect
+    await Promise.all([
+      page.waitForURL(/.*eagleeyenetworks.com.*/, { timeout: TIMEOUTS.OAUTH_REDIRECT }),
+      page.click('[data-testid="login-button"]')
+    ])
+
+    // Fill valid email
+    const emailInput = page.locator('#authentication--input__email')
+    await emailInput.waitFor({ state: 'visible', timeout: TIMEOUTS.ELEMENT_VISIBLE })
+    await emailInput.fill(TEST_USER!)
+    await page.getByRole('button', { name: 'Next' }).click()
+
+    // Fill invalid password
+    const passwordInput = page.locator('#authentication--input__password')
+    await passwordInput.waitFor({ state: 'visible', timeout: TIMEOUTS.PASSWORD_VISIBLE })
+    await passwordInput.fill('invalid-password-12345!')
+
+    // Click sign in
+    await page.locator('#next, button:has-text("Sign in")').first().click()
+
+    // Should show error message on OAuth page
+    await expect(
+      page.locator('.error, [class*="error"], [data-testid*="error"], #error, .alert-danger').first()
+    ).toBeVisible({ timeout: TIMEOUTS.UI_UPDATE })
+
+    // Should still be on OAuth page
+    await expect(page).toHaveURL(/eagleeyenetworks\.com/)
+  })
+})

package/examples/vue-basic/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>EEN API Toolkit Example</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>