een-api-toolkit 0.0.8 → 0.0.13

package/CHANGELOG.md

@@ -2,222 +2,333 @@
 
 All notable changes to this project will be documented in this file.
 
-## [0.0.8] - 2025-12-27
+## [0.0.13] - 2025-12-29
 
-### 📋 Release Summary
+### Release Summary
 
-#### PR #9: Release v0.0.8: Dependency upgrades and release notes enhancement
+#### PR #15: feat: Launch OAuth proxy in CI for e2e tests
 ## Summary
+- Add proxy setup steps to test-release.yml workflow to run OAuth e2e tests in CI
+- Clone, install, and start OAuth proxy on port 8787 during CI
+- Create .dev.vars with required secrets for local proxy operation
+- Fix Slack release notes link to point to GitHub Release page instead of .md download
+- Add CLIENT_SECRET to secrets sync script and documentation
 
-This release upgrades development dependencies to resolve security vulnerabilities and enhances the release workflow with auto-generated release notes from PR descriptions.
-
-### Dependency Upgrades
-| Package | From | To |
-|---------|------|-----|
-| @types/node | ^20.10.0 | ^22.0.0 |
-| @vitejs/plugin-vue | ^5.0.0 | ^6.0.0 |
-| typescript | ^5.3.0 | ~5.8.0 |
-| vite | ^5.0.0 | ^7.3.0 |
-| vite-plugin-dts | ^3.7.0 | ^4.5.4 |
-| vitest | ^1.2.0 | ^4.0.16 |
-| vue-tsc | ^1.8.0 | ^3.2.1 |
-
-### Build Warning Fixes
-- Reorder package.json exports (`types` before `import`/`require`)
-- Pin TypeScript to ~5.8.0 for API Extractor compatibility
-- Suppress dynamic/static import warning (not applicable to single-file library)
-- Make lazy-loader concurrency-safe by caching promise
-
-### Release Notes Enhancement
-- Auto-generate release summary from merged PR descriptions
-- Include `RELEASE-NOTES-vX.X.X.md` as GitHub release asset
-- Add direct link to release notes in Slack success notification
+## Changes
+- `.github/workflows/test-release.yml`: Add steps to clone proxy, install deps, create secrets file, and start proxy
+- `.github/workflows/npm-publish.yml`: Fix Slack release notes link to avoid .md download
+- `scripts/sync-secrets.sh`: Add CLIENT_SECRET to sync list
+- `CLAUDE.md`: Document CLIENT_SECRET requirement
 
 ## Test plan
-- [x] Unit tests pass (7/7)
-- [x] Lint passes (0 errors)
-- [x] TypeScript type checking passes
-- [x] Build succeeds with no warnings
-- [x] Package verification passes
+- [ ] Verify test-release workflow runs and proxy starts successfully
+- [ ] Verify e2e OAuth tests execute against the local proxy
+- [ ] Verify Slack notification links to GitHub Release page (not .md download)
 
 🤖 Generated with [Claude Code](https://claude.com/claude-code)
 
-#### PR #7: Release v0.0.6
+#### PR #16: fix: Strip leading whitespace from .dev.vars heredoc
 ## Summary
-Release v0.0.6 with workflow reliability improvements.
+- Fix heredoc indentation issue in test-release.yml that caused proxy env vars to not be parsed
 
-## Changes
+## Problem
+The `.dev.vars` heredoc content was indented for YAML readability, but those leading spaces became part of the file content:
+```
+          CLIENT_ID=xxx
+          ALLOWED_ORIGINS=http://127.0.0.1:3333
+```
 
-### Version
-- Bump: 0.0.5 → 0.0.6
+This caused wrangler to not recognize the environment variables, so `ALLOWED_ORIGINS` was empty and the proxy rejected OAuth callback requests with "Invalid redirect_uri: domain not allowed".
 
-### Workflow Improvements
-- Add version check to skip publish if version already exists on npm
-- Skip GitHub Release and Slack notification if already published
-- Add repository link to success Slack notification
-- Enhance failure Slack notification with:
-  - Repository link
-  - Direct link to failed workflow run
+## Fix
+Added `sed -i 's/^[[:space:]]*//'` to strip leading whitespace after creating the file.
 
-## Why
-PR #6 merge triggered the publish workflow, but version 0.0.5 was already published, causing failure. The new version check prevents this.
+## Test plan
+- [ ] Verify test-release workflow passes
+- [ ] Verify OAuth e2e tests complete successfully
 
 🤖 Generated with [Claude Code](https://claude.com/claude-code)
 
-#### PR #6: feat: Enhanced release notifications and GitHub Releases
+#### PR #17: fix: Use printf with quoted values for .dev.vars
 ## Summary
-- Add GitHub Release creation alongside npm publish
-- Enhance Slack notifications with more details and links
+Fix special character handling in `.dev.vars` secrets file creation.
 
-## Changes
+## Problem
+The `CLIENT_SECRET` contains special characters (like `#`) that were being interpreted as comment markers when written to `.dev.vars` without proper quoting, causing the value to be truncated.
 
-### GitHub Release (`npm-publish.yml`)
-- Creates GitHub Release with version tag (e.g., `v0.0.6`)
-- Attaches npm tarball to the release
-- Generates release notes with:
-  - Installation command
-  - Package details (npm link, version, size, release time in CST)
-  - Links to npm, documentation, and changelog
+## Solution
+Use `printf` with double-quoted values, matching the pattern from `een-oauth-proxy/test-demo1-pr.yml`:
 
-### Enhanced Slack Notification
-- Clickable link to npm package
-- Clickable link to GitHub Release
-- Package size
-- Release timestamp in America/Chicago timezone
+```bash
+printf 'CLIENT_ID="%s"\n' "$CLIENT_ID" > .dev.vars
+printf 'CLIENT_SECRET="%s"\n' "$CLIENT_SECRET" >> .dev.vars
+```
 
-### Documentation
-- Updated CLAUDE.md to document GitHub Release functionality
+This properly escapes special characters in secret values.
 
 ## Test plan
-- [ ] Merge PR and verify GitHub Release is created
-- [ ] Verify Slack notification includes all new fields
-- [ ] Verify release notes are properly formatted
+- [ ] Verify test-release workflow passes
+- [ ] Verify OAuth e2e tests complete successfully
 
 🤖 Generated with [Claude Code](https://claude.com/claude-code)
 
-#### PR #5: ci: Add npm publish workflow
+#### PR #18: docs: Restructure documentation and add CI validation
 ## Summary
-- Add automated npm publish workflow triggered when PRs merge to production
-- Include manual trigger option with dry run mode for testing
-- Slack notifications for publish success/failure
+
+- Restructure README.md into a concise overview with quick start guide
+- Create separate User Guide (docs/USER-GUIDE.md) for app developers
+- Create separate Developer Guide (docs/DEVELOPER-GUIDE.md) for contributors
+- Regenerate TypeDoc API reference for version 0.0.11
+- Fix broken EENCloud GitHub link in CLAUDE.md
+- Add documentation validation step to test-release workflow
 
 ## Changes
-- New `.github/workflows/npm-publish.yml` workflow
 
-## Test plan
-- [ ] Verify workflow syntax is valid
-- [ ] After merge, manually trigger with dry_run=true to test
-- [ ] Manually trigger without dry_run to publish v0.0.5 to npm
+### Documentation Restructure
+- **README.md**: Simplified with key features first, quick start guide, architecture diagram
+- **docs/USER-GUIDE.md**: New comprehensive guide covering installation, proxy setup, auth flow, API usage, troubleshooting
+- **docs/DEVELOPER-GUIDE.md**: New guide for contributors covering architecture, testing, CI/CD, publishing
+- **docs/README.md**: Updated as documentation index with audience descriptions
+
+### CI/CD
+- Added "Verify documentation is current" step to test-release.yml
+- Fails build if docs are stale, ensuring release docs always match code
 
+### Fixes
+- Updated broken link to EENCloud/api-v3-documentation (404) → VMS-Developer-Portal (200)
+- Regenerated all TypeDoc files with version 0.0.11
+
+## Test Results
+- Lint: Passed (1 warning)
+- Unit tests: 7/7 passed
+- Build: Success
+
+## Version
+`0.0.11`
+
+---
 🤖 Generated with [Claude Code](https://claude.com/claude-code)
 
-#### PR #4: Release v0.0.5: Documentation system and example app
+#### PR #19: Release v0.0.11: Documentation restructure and OAuth requirements
 ## Summary
 
-- Add comprehensive documentation system with TypeDoc and AI-CONTEXT.md
-- Create complete Vue 3 example application
-- Add disclaimer to README
+This release focuses on comprehensive documentation improvements:
 
-## Changes
+- **Documentation restructure**: Split README into user-focused and developer-focused sections
+  - `docs/USER-GUIDE.md` - For application developers using the toolkit
+  - `docs/DEVELOPER-GUIDE.md` - For contributors to the toolkit
+- **OAuth redirect URI requirements**: Added critical documentation based on user testing feedback
+  - EEN IDP requires exact string match: `http://127.0.0.1:3333` (not localhost, no /callback path)
+  - Added router pattern examples for handling OAuth on root path
+  - Added link to EEN Developer Portal for redirect URI configuration
+- **Architecture diagram fixes**: Corrected to show auth calls vs API calls use different paths
+- **CI documentation validation**: Added step to test-release workflow to fail if docs are stale
+- **AI-CONTEXT.md improvements**: Critical Requirements section now auto-generated
 
-### Documentation System
-- **TypeDoc integration** - Auto-generates API docs from JSDoc comments
-- **AI-CONTEXT.md** - Single-file comprehensive reference for AI assistants (~700 lines)
-- **Enhanced JSDoc** - All exports documented with examples, @param, @returns, @category
-- **npm scripts** - `docs`, `docs:api`, `docs:ai-context`
+### Key Changes
 
-### Example Application
-- Complete Vue 3 app in `examples/vue-basic/`
-- OAuth flow (login, callback, logout)
-- User list with pagination using composables
-- Auth guards for protected routes
-- Configured for EEN IDP requirement (http://127.0.0.1:3333)
+- Restructured documentation for better discoverability
+- Added comprehensive OAuth troubleshooting guidance
+- Fixed architecture diagrams to accurately show auth flow
+- Updated PR-and-check skill to support develop→production PRs
+- Added Purpose section to README explaining toolkit goals
 
-### README Updates
-- Added disclaimer (no warranty, not associated with EEN)
-- Added Documentation section with links
+### Version
 
-## New Exports
-- `getRedirectUri()` - Config function for OAuth redirect URI
-- `TokenResponse` - Type for OAuth token response
-- `UseCurrentUserOptions`, `UseUsersOptions`, `UseUserOptions` - Composable option types
+**Package version:** 0.0.11
 
-## Test plan
-- [x] `npm run build` passes
-- [x] `npm run lint` passes
-- [x] `npm run docs` generates successfully
-- [ ] Code review passes
+### Test Results
+
+- ✅ Linting passed (1 warning - max-len in test file)
+- ✅ Unit tests: 7/7 passed
+- ✅ Build: successful
 
 🤖 Generated with [Claude Code](https://claude.com/claude-code)
 
-#### PR #3: Release v0.0.2: E2E tests and security documentation
+#### PR #20: docs: Add Pinia prerequisite requirements to documentation
 ## Summary
 
-This PR adds comprehensive E2E testing infrastructure and security documentation to the toolkit.
+This PR adds comprehensive documentation about Pinia prerequisites to help users avoid the common "getActivePinia() was called but there was no active Pinia" error.
 
-### Changes
+## Changes
 
-**E2E Testing with Playwright**
-- Added `auth-helper.ts` for OAuth login with token caching
-- Added `auth.spec.ts` to validate auth helper functionality  
-- Added `users.spec.ts` with 5 tests for Users API endpoints
-- Configured Playwright for Chromium-only testing with single worker
-- Added `test:e2e` and `test:e2e:ui` npm scripts
+- **AI-CONTEXT.md**: Added "Prerequisites (IMPORTANT)" section with Pinia installation requirements and error message
+- **USER-GUIDE.md**: Enhanced toolkit initialization section and added troubleshooting entry for the Pinia error
+- **DEVELOPER-GUIDE.md**: Added Pinia as a key design decision explaining the dependency requirement
+- **generate-ai-context.ts**: Updated generation script to include Pinia prerequisites
 
-**Documentation**
-- Added security model section to CLAUDE.md (refresh token isolation)
-- Added security/robustness priorities statement
+## New Commits
 
-**Bug Fixes**
-- Excluded e2e folder from Vitest to prevent test conflicts
+- `9308498` fix: Update AI-CONTEXT generator to include Pinia prerequisites
+- `f62490b` docs: Add Pinia prerequisite requirements to documentation
 
-### Test Results
-- Unit tests: 7 passed
-- E2E tests: 6 passed (auth helper + 5 Users API tests)
-- Lint: 1 warning (intentional console in debug.ts)
-- Build: Success
+## Test Results
 
-### Version
-`0.0.2`
+- ✅ Lint: Passed (1 expected warning)
+- ✅ Unit tests: 7/7 passed
+- ✅ Build: Successful
+
+## Version
+
+`0.0.11`
 
 🤖 Generated with [Claude Code](https://claude.com/claude-code)
 
-#### PR #2: Initial project setup and planning documentation
+#### PR #21: docs: Add In-Place Login pattern for single-page OAuth callbacks
 ## Summary
 
-- Add comprehensive project planning documentation (CLAUDE.md, README.md)
-- Set up development tooling (scripts, skills, .env configuration)
-- Configure local proxy URL for development
-- Add GitHub secrets sync script
+This PR adds documentation for the "In-Place Login" pattern - handling OAuth callbacks on the same page that displays user data without navigation.
 
 ## Changes
 
-### Documentation
-- **CLAUDE.md**: Technical guidance for Claude Code including architecture, patterns, API specs, workflows
-- **README.md**: Developer usage documentation with examples, setup instructions, configuration
+- **AI-CONTEXT.md**: Added "In-Place Login (Single Page Callback)" to Common Patterns section
+- **USER-GUIDE.md**: Added same pattern to Authentication Flow section with expanded explanation
+- **generate-ai-context.ts**: Updated script to include the pattern in future regenerations
+
+## Problem Addressed
+
+Developers implementing single-page OAuth flows were encountering issues where `useCurrentUser()` didn't update after successful login. The documentation now explains:
+- Why `refresh()` must be called after `handleAuthCallback()` when staying on the same page
+- That composables don't auto-refresh when auth state changes
+- Complete working example with login button and callback handling
+
+## New Commits
 
-### Configuration
-- **.env.example**: Environment variable template
-- **scripts/sync-secrets.sh**: Sync .env to GitHub repository secrets
+- `3b7b6a0` docs: Add In-Place Login pattern for single-page OAuth callbacks
 
-### Skills
-- **.claude/skills/PR-and-check/**: PR workflow skill for feature branches
+## Test Results
 
-## Test Plan
-- [ ] Review documentation for accuracy
-- [ ] Verify sync-secrets.sh works with `--dry-run`
+- ✅ Lint: Passed (1 expected warning)
+- ✅ Unit tests: 7/7 passed
+- ✅ Build: Successful
 
-🤖 Generated with [Claude Code](https://claude.ai/code)
+## Version
 
+`0.0.11`
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+#### PR #22: fix: Correct proxy endpoints and API references in README
+## Summary
 
-### 📝 Detailed Changes
+- Fix incorrect proxy endpoints documentation (`/oauth/authorize`, `/oauth/token` → `/proxy/getAccessToken`)
+- Update Key Features to reflect actual implemented APIs (Users only, not Cameras/Bridges)
+- Fix code examples to use existing functions (`getCurrentUser`, `getUsers`, `getUser`)
+- Update architecture diagram to show implemented APIs
+
+## Commits
+
+- `ff85054` fix: Correct proxy endpoints and API references in README
+
+## Test Results
+
+- ✅ Lint: passed (1 warning - expected console in debug.ts)
+- ✅ Unit tests: 7 passed
+- ✅ Build: successful
+
+## Version
+
+`0.0.11`
+
+---
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+#### PR #23: feat: Include AI-CONTEXT.md in npm package and trigger releases on changes
+## Summary
+
+This PR adds `docs/AI-CONTEXT.md` to the npm package distribution and ensures that updates to this file trigger new releases.
+
+### Changes
+
+- **package.json**: Added `docs/AI-CONTEXT.md` to the `files` array so it's included in the npm package
+- **.husky/pre-commit**: Modified to trigger version bump when `docs/AI-CONTEXT.md` changes
+- **CLAUDE.md**: Updated documentation to reflect the new behavior
+- **docs/DEVELOPER-GUIDE.md**: Updated documentation with explanation of why AI-CONTEXT.md triggers releases
+
+### Rationale
+
+The README positions AI-assisted development as a key value proposition of this toolkit. Including `AI-CONTEXT.md` in the npm package makes it immediately accessible to consumers using AI assistants without requiring them to clone the repo or navigate to GitHub.
+
+### Commits
+
+- `3505d9d` feat: Include AI-CONTEXT.md in npm package and trigger releases on changes
+
+### Test Results
+
+- ✅ Linting passed (1 warning - expected console statement in debug.ts)
+- ✅ Unit tests passed (7/7)
+- ✅ Build successful
+
+### Version
+
+`0.0.11`
+
+#### PR #24: chore: Release v0.0.13
+## Summary
+
+Version bump to 0.0.13 for new release including:
+- AI-CONTEXT.md included in npm package
+- README.md changes now trigger version bumps
+- Updated Husky pre-commit hook configuration
+- **Fix:** Removed AI-CONTEXT.md from version bump triggers to prevent circular versioning
+
+### Version
 
-#### 📦 Other Changes
-- Merge pull request #9 from klaushofrichter/develop
+`0.0.13`
+
+### Previous Release
+
+v0.0.11 was published via PR #23
+
+### Version Fix
+
+This release fixes a circular dependency issue where updating AI-CONTEXT.md 
+(a generated file) would trigger another version bump. AI-CONTEXT.md now 
+correctly reflects the version without causing additional bumps.
+
+
+### Detailed Changes
+
+#### Features
+- feat: Add README.md to version bump triggers
+- feat: Include AI-CONTEXT.md in npm package and trigger releases on changes
+- feat: Launch OAuth proxy in CI for e2e tests
+
+#### Bug Fixes
+- fix: Remove AI-CONTEXT.md from version bump triggers
+- fix: Correct proxy endpoints and API references in README
+- fix: Address code review feedback for In-Place Login pattern
+- fix: Add redirectUri and debug to initEenToolkit examples
+- fix: Address code review feedback
+- fix: Update AI-CONTEXT generator to include Pinia prerequisites
+- fix: Update router example to handle OAuth on root path
+- fix: Address PR #17 review feedback
+- fix: Use printf with quoted values for .dev.vars
+- fix: Address PR #16 review feedback
+- fix: Strip leading whitespace from .dev.vars heredoc
+- fix: Address PR #15 review feedback
+
+#### Other Changes
+- docs: Regenerate API documentation for v0.0.13
+- docs: Update AI-CONTEXT.md version to 0.0.12
+- chore: Bump version to 0.0.12 for release
+- docs: Fix glob patterns to show deep matching (src/**/*)
+- docs: Add getCurrentUser example to README
+- docs: Fix API references in USER-GUIDE and DEVELOPER-GUIDE
+- docs: Add In-Place Login pattern for single-page OAuth callbacks
+- docs: Add Pinia prerequisite requirements to documentation
+- docs: Add OAuth requirements and update doc generation script
+- docs: Add OAuth requirements, proxy info, and EEN portal links
+- docs: Add purpose section and update PR-and-check skill
+- docs: Fix architecture diagrams and error handling example
+- ci: Add documentation validation to test-release workflow
+- docs: Regenerate docs for v0.0.11 and fix broken link
+- docs: Restructure documentation for users and developers
 
 ### Links
 - [npm package](https://www.npmjs.com/package/een-api-toolkit)
-- [Full Changelog](https://github.com/klaushofrichter/een-api-toolkit/commits/v0.0.8)
+- [Full Changelog](https://github.com/klaushofrichter/een-api-toolkit/compare/v0.0.11...v0.0.13)
 
 ---
-*Released: 2025-12-27 10:23:46 CST*
+*Released: 2025-12-29 14:15:09 CST*