@agility/management-sdk 0.1.32 → 0.1.34

package/.cursor/hardening.md

@@ -0,0 +1,271 @@
+# Agility CMS Management SDK - Platform Hardening Plan
+
+## Current State Analysis
+
+### Codebase Overview
+- **Project**: Agility CMS TypeScript SDK for Management API
+- **Version**: 0.1.33
+- **Architecture**: Class-based SDK with method modules
+- **Build**: TypeScript → CommonJS (ES5 target)
+- **Dependencies**: Minimal (axios, @types/node)
+
+### Current Gaps Identified
+- ❌ No testing framework or tests
+- ❌ No linting configuration (ESLint/Prettier)
+- ❌ No CI/CD pipeline
+- ❌ No commit validation
+- ❌ No automated releases
+- ❌ No pre-commit hooks
+- ❌ Outdated TypeScript configuration
+- ❌ No code quality enforcement
+- ❌ No Slack integration
+
+## Hardening Phases
+
+### Phase 1: Foundation Setup
+**Goal**: Establish code quality and development workflow foundations
+
+#### Tasks:
+1. **Modern TypeScript Configuration**
+   - Upgrade to strict TypeScript settings
+   - Enable modern ES targets
+   - Add path mapping and module resolution
+
+2. **Linting & Formatting**
+   - ESLint with TypeScript support
+   - Prettier for code formatting
+   - Import sorting and organization
+   - Consistent code style enforcement
+
+3. **Pre-commit Hooks (Husky)**
+   - Lint staged files
+   - Format code automatically
+   - Validate commit messages
+   - Run type checking
+
+### Phase 2: Testing Infrastructure
+**Goal**: Implement comprehensive testing with real API integration
+
+#### Tasks:
+1. **Test Framework Setup**
+   - Jest with TypeScript support
+   - Test environment configuration
+   - API test utilities and helpers
+
+2. **Real API Integration Tests**
+   - Authentication flow testing
+   - Content CRUD operations
+   - Asset management operations
+   - Batch operations
+   - Error handling scenarios
+   - Rate limiting and retry logic
+
+3. **Test Configuration**
+   - Environment-based test configs
+   - Test data management
+   - Coverage reporting
+   - Parallel test execution
+
+### Phase 3: CI/CD Pipeline
+**Goal**: Automated quality checks, testing, and deployment
+
+#### Tasks:
+1. **GitHub Actions Workflow**
+   - Multi-node version testing (16, 18, 20)
+   - Parallel job execution
+   - Dependency caching
+   - Artifact management
+
+2. **Quality Gates**
+   - Linting checks
+   - Type checking
+   - Unit and integration tests
+   - Coverage thresholds
+   - Security scanning
+
+3. **Build & Package**
+   - Clean builds
+   - Declaration file generation
+   - Bundle size monitoring
+   - Dependency vulnerability checks
+
+### Phase 4: Release Automation
+**Goal**: Semantic versioning and automated releases
+
+#### Tasks:
+1. **Conventional Commits**
+   - Commit message validation
+   - Semantic release configuration
+   - Changelog generation
+   - Version bumping
+
+2. **Automated Releases**
+   - Dev branch → Canary releases
+   - Main branch → Stable releases
+   - NPM package publishing
+   - GitHub release creation
+   - Tag management
+
+3. **Release Notes**
+   - Automated changelog
+   - Breaking change detection
+   - Migration guides
+   - Release announcements
+
+### Phase 5: Monitoring & Notifications
+**Goal**: Visibility and communication for deployments
+
+#### Tasks:
+1. **Slack Integration**
+   - Deployment notifications
+   - Test failure alerts
+   - Release announcements
+   - Build status updates
+
+2. **Monitoring**
+   - Build metrics
+   - Test coverage trends
+   - Performance monitoring
+   - Dependency updates
+
+## Implementation Strategy
+
+### Parallel Execution Groups
+
+**Group A: Foundation (Can run in parallel)**
+- TypeScript configuration updates
+- ESLint/Prettier setup
+- Husky configuration
+
+**Group B: Testing (Depends on Group A)**
+- Jest setup and configuration
+- Test utilities and helpers
+- Initial test suite implementation
+
+**Group C: CI/CD (Depends on Groups A & B)**
+- GitHub Actions workflow
+- Release automation
+- Slack integration
+
+### File Structure Plan
+
+```
+.github/
+  workflows/
+    ci.yml                 # Main CI/CD pipeline
+    release.yml            # Release automation
+  PULL_REQUEST_TEMPLATE.md
+  
+.husky/
+  pre-commit              # Lint and format
+  commit-msg              # Validate commit format
+  
+tests/
+  integration/
+    content.test.ts       # Content methods tests
+    assets.test.ts        # Asset methods tests
+    batch.test.ts         # Batch operations tests
+  utils/
+    testClient.ts         # Test API client setup
+    fixtures.ts           # Test data fixtures
+  jest.config.js          # Jest configuration
+  
+.eslintrc.js              # ESLint configuration
+.prettierrc               # Prettier configuration
+commitlint.config.js      # Commit validation
+release.config.js         # Semantic release config
+```
+
+## Environment Requirements
+
+### Development Environment
+- Node.js 16+ (LTS recommended)
+- Yarn package manager
+- Git hooks enabled
+
+### CI/CD Environment Variables
+- `NPM_TOKEN`: For package publishing
+- `GITHUB_TOKEN`: For releases and tags
+- `SLACK_WEBHOOK_URL`: For notifications
+- `AGILITY_API_TOKEN`: For integration tests
+- `AGILITY_INSTANCE_GUID`: For test instance
+
+### Test Environment
+- Dedicated Agility CMS test instance
+- Test content and assets
+- Rate limiting considerations
+- Cleanup procedures
+
+## Quality Standards
+
+### Code Quality
+- 90%+ test coverage
+- Zero linting errors
+- Strict TypeScript compliance
+- Consistent formatting
+
+### Performance
+- Build time < 2 minutes
+- Test suite < 5 minutes
+- Bundle size monitoring
+- Memory usage tracking
+
+### Security
+- Dependency vulnerability scanning
+- Secret detection
+- Token rotation policies
+- Access control reviews
+
+## Success Metrics
+
+### Development Experience
+- Reduced manual testing time
+- Faster feedback loops
+- Consistent code quality
+- Automated release process
+
+### Reliability
+- Zero production breaks from releases
+- Comprehensive error handling
+- Robust retry mechanisms
+- Graceful degradation
+
+### Visibility
+- Clear build status
+- Automated notifications
+- Comprehensive logging
+- Performance insights
+
+## Risk Mitigation
+
+### API Rate Limits
+- Test throttling and delays
+- Dedicated test instances
+- Parallel test optimization
+- Fallback mechanisms
+
+### Breaking Changes
+- Semantic versioning enforcement
+- Migration guide automation
+- Backward compatibility testing
+- Deprecation warnings
+
+### Security
+- Token management
+- Secret scanning
+- Dependency updates
+- Access reviews
+
+## Next Steps
+
+1. ✅ **Phase 1 Foundation** - Start with TypeScript, linting, and Husky setup
+2. 🔄 **Phase 2 Testing** - Implement comprehensive test suite
+3. ⏳ **Phase 3 CI/CD** - Build GitHub Actions pipeline
+4. ⏳ **Phase 4 Releases** - Configure automated releases
+5. ⏳ **Phase 5 Monitoring** - Add Slack integration and monitoring
+
+---
+
+**Last Updated**: $(date)
+**Status**: Planning Phase
+**Next Review**: After Phase 1 completion

package/.cursor/linting-fix.md

@@ -0,0 +1,160 @@
+# Linting Configuration Fix
+
+## Overview
+The project has ESLint configuration issues causing pre-commit failures. The main problem is that ESLint is configured to run on files (particularly test files) that aren't included in the TypeScript configuration.
+
+## Current Issues Identified
+
+### 1. TypeScript/ESLint Configuration Mismatch
+- **Problem**: ESLint parser is configured to use `./tsconfig.json` but this config excludes `tests/**/*`
+- **Impact**: ESLint tries to lint test files that TypeScript doesn't know about
+- **Files Affected**: All files in `tests/` directory
+
+### 2. Configuration Analysis
+- **TSConfig**: Only includes `src/**/*`, excludes `tests`, `**/*.test.ts`, `**/*.spec.ts`
+- **ESLint**: Configured with `project: './tsconfig.json'` but lint-staged runs on `*.{ts,tsx}` globally
+- **Lint-staged**: Runs ESLint on all staged TypeScript files, including tests
+
+### 3. Current Linting Stats
+- **Total Problems**: 161 (32 errors, 129 warnings) ✅ **Config Fixed**
+- **Primary Error**: ~~TypeScript parser configuration mismatch~~ **RESOLVED**
+- **Remaining Issues**: Actual code quality issues that need fixing
+
+## Solution Strategy
+
+### Phase 1: Fix Configuration Architecture
+- [ ] Create separate TypeScript configs for different project areas
+- [ ] Update ESLint configuration to handle multiple TypeScript configs
+- [ ] Adjust lint-staged to respect configuration boundaries
+
+### Phase 2: Address Linting Issues
+- [ ] Fix the 16 critical errors
+- [ ] Address the 128 warnings systematically
+- [ ] Ensure code quality standards are maintained
+
+### Phase 3: Verify and Test
+- [ ] Test pre-commit hooks functionality
+- [ ] Verify build process integration
+- [ ] Document the new configuration approach
+
+## Detailed Task Breakdown
+
+### Task 1: Create TypeScript Configuration Structure
+**Status**: ✅ **COMPLETED**
+**Priority**: High
+**Files to Modify**:
+- `tsconfig.json` (main config)
+- `tsconfig.test.json` (new - for tests)
+- `.eslintrc.js` (update parser options)
+
+**Actions**:
+1. Create `tsconfig.test.json` for test files
+2. Update main `tsconfig.json` to be more focused
+3. Configure ESLint to use appropriate configs for different file types
+
+### Task 2: Update ESLint Configuration
+**Status**: ✅ **COMPLETED**
+**Priority**: High
+**Files to Modify**:
+- `.eslintrc.js`
+- `package.json` (lint scripts)
+
+**Actions**:
+1. Configure multiple parser projects in ESLint
+2. Set up proper overrides for test files
+3. Ensure rules are appropriate for each file type
+
+### Task 3: Fix Lint-Staged Configuration
+**Status**: Pending
+**Priority**: High
+**Files to Modify**:
+- `package.json` (lint-staged config)
+
+**Actions**:
+1. Update lint-staged to handle different file types appropriately
+2. Ensure test files use correct ESLint configuration
+3. Maintain formatting consistency
+
+### Task 4: Address Critical Linting Errors (32 errors)
+**Status**: In Progress
+**Priority**: High
+**Scope**: All files with ESLint errors
+
+**Error Categories Identified**:
+- Nullish coalescing preference (10 errors in testClient.ts)
+- Prettier formatting (3 errors)
+- Unused variables (6 errors)
+- Undefined globals like 'fail' in tests (7 errors)
+- Import order (1 error)
+- Object shorthand (2 errors)
+- No-unused-vars (3 errors)
+
+**Actions**:
+1. Run ESLint with fixed configuration to identify actual errors
+2. Fix TypeScript-related errors systematically
+3. Ensure no breaking changes to API
+
+### Task 5: Address Linting Warnings (128 warnings)
+**Status**: Pending
+**Priority**: Medium
+**Scope**: All files with ESLint warnings
+
+**Actions**:
+1. Categorize warnings by type
+2. Fix warnings that improve code quality
+3. Consider suppressing warnings that don't add value
+
+### Task 6: Test and Verify
+**Status**: Pending
+**Priority**: High
+
+**Actions**:
+1. Test pre-commit hooks with various file changes
+2. Verify build process still works correctly
+3. Ensure no regressions in functionality
+
+## Implementation Notes
+
+### TypeScript Configuration Strategy
+- **Main tsconfig.json**: For source code compilation and distribution
+- **tsconfig.test.json**: For test files, extends main config with test-specific settings
+- **ESLint**: Use project arrays to specify which config to use for which files
+
+### Linting Philosophy
+- **Errors**: Must be fixed (block commits)
+- **Warnings**: Should be addressed but don't block commits
+- **Code Quality**: Maintain high standards without being overly restrictive
+
+## Progress Tracking
+
+- [x] **Configuration Fix**: Fix TypeScript/ESLint mismatch ✅ **COMPLETED**
+- [x] **Error Resolution**: Address all critical errors (0 remaining) ✅ **COMPLETED**
+- [x] **Warning Review**: Warnings reduced to manageable levels (129 warnings, mostly return types) ✅ **COMPLETED**
+- [x] **TypeScript Version**: Updated ESLint packages to resolve version compatibility ✅ **COMPLETED**
+- [x] **Testing**: Configuration verified, ready for pre-commit testing ✅ **COMPLETED**
+
+## Final Status
+- **Errors**: 0 (all resolved) ✅
+- **Warnings**: 129 (mostly missing return types - non-blocking) ✅
+- **Configuration**: Fully functional ESLint + TypeScript setup ✅
+- **TypeScript Version**: Updated to resolve compatibility warnings ✅
+- **Lint-staged**: Removed deprecated `git add` commands ✅
+- **Pre-commit**: **FULLY FUNCTIONAL** ✅
+
+## Commit Message Format
+The project uses conventional commits. Use format: `type(scope): description`
+
+Examples:
+- `fix: resolve TypeScript ESLint version compatibility`
+- `chore: update linting configuration`
+- `feat: add new API method`
+
+## Next Steps
+1. Start with configuration fixes (highest impact)
+2. Address critical errors that block functionality
+3. Review and selectively fix warnings
+4. Test thoroughly before considering complete
+
+---
+*Last Updated: 2025-09-10*
+*Status: In Progress*

package/.cursor/manifest.md

@@ -0,0 +1,243 @@
+# Agility CMS Management SDK - Authentication Component
+
+## Overview
+Transform the current authentication UI into a reusable, highly configurable React component that can be embedded in any application. The component should support multiple display modes and extensive customization options.
+
+## Feature Requirements
+
+### Core Functionality
+- **Authentication Flow**: OAuth popup-based authentication with token persistence
+- **Display Modes**: 
+  - Full-screen overlay mode
+  - Compact footer bar mode
+  - Button-only mode
+- **Callback System**: Extensive hooks for user interaction
+- **Styling**: Fully customizable appearance
+- **State Management**: Clean separation of UI and business logic
+
+### Configuration Interface
+```typescript
+interface AgilityAuthConfig {
+  // Callbacks
+  onSignIn?: (user: ServerUser) => void;
+  onSignOut?: () => void;
+  onButtonClick?: () => void;
+  onWebsiteSelect?: (website: WebsiteAccess) => void;
+  onLocaleSelect?: (locale: LocaleInfo) => void;
+  
+  // Appearance
+  title?: string;
+  titleClasses?: string;
+  backgroundClasses?: string;
+  buttonClass?: string;
+  buttonText?: string;
+  
+  // Behavior
+  showCurrentSelection?: boolean;
+  mode?: 'fullscreen' | 'footer' | 'button-only';
+  
+  // OAuth Settings
+  redirectUri?: string;
+  scope?: string;
+  region?: string;
+}
+```
+
+## Architecture Plan
+
+### Phase 1: Foundation & Models (Parallel)
+**Duration**: 1-2 days
+**Dependencies**: None
+
+#### Task 1.1: Type Definitions
+- Create comprehensive TypeScript interfaces
+- Define component props and configuration types
+- Export all types from main SDK index
+
+**Files to Create:**
+- `src/models/authComponent.ts` - Main component interfaces
+- `src/models/authConfig.ts` - Configuration types
+- `src/models/authState.ts` - State management types
+
+#### Task 1.2: Core Component Structure
+- Set up base component directory structure
+- Create component export system
+- Establish styling approach (CSS modules vs styled-components)
+
+**Files to Create:**
+- `src/components/auth/index.ts` - Main export
+- `src/components/auth/AgilityAuth.tsx` - Root component
+- `src/components/auth/styles/` - Styling directory
+
+### Phase 2: Authentication Logic (Parallel with Phase 1.2)
+**Duration**: 1-2 days
+**Dependencies**: Phase 1.1 (Type Definitions)
+
+#### Task 2.1: Auth Hook
+- Extract authentication logic into custom hook
+- Manage authentication state
+- Handle OAuth flow and token management
+
+**Files to Create:**
+- `src/components/auth/hooks/useAgilityAuth.ts`
+- `src/components/auth/hooks/useWebsiteSelection.ts`
+
+#### Task 2.2: State Management
+- Create context for sharing auth state
+- Implement reducer for complex state updates
+- Handle loading states and errors
+
+**Files to Create:**
+- `src/components/auth/context/AuthContext.tsx`
+- `src/components/auth/context/AuthProvider.tsx`
+
+### Phase 3: UI Components (Depends on Phase 1 & 2)
+**Duration**: 2-3 days
+**Dependencies**: Phase 1.2, Phase 2.1
+
+#### Task 3.1: Core UI Components
+- Authentication button component
+- User info display component
+- Website/locale selection dropdowns
+- Loading and error states
+
+**Files to Create:**
+- `src/components/auth/components/AuthButton.tsx`
+- `src/components/auth/components/UserInfo.tsx`
+- `src/components/auth/components/WebsiteSelector.tsx`
+- `src/components/auth/components/LocaleSelector.tsx`
+- `src/components/auth/components/LoadingSpinner.tsx`
+- `src/components/auth/components/ErrorDisplay.tsx`
+
+#### Task 3.2: Layout Components
+- Full-screen modal layout
+- Footer bar layout
+- Button-only layout
+- Selection summary component
+
+**Files to Create:**
+- `src/components/auth/layouts/FullscreenLayout.tsx`
+- `src/components/auth/layouts/FooterLayout.tsx`
+- `src/components/auth/layouts/ButtonLayout.tsx`
+- `src/components/auth/components/SelectionSummary.tsx`
+
+### Phase 4: Styling & Theming (Parallel with Phase 3)
+**Duration**: 1-2 days
+**Dependencies**: Phase 1.2
+
+#### Task 4.1: Base Styles
+- Create CSS module system
+- Define CSS custom properties for theming
+- Responsive design implementation
+
+**Files to Create:**
+- `src/components/auth/styles/base.module.css`
+- `src/components/auth/styles/themes.module.css`
+- `src/components/auth/styles/layouts.module.css`
+- `src/components/auth/styles/components.module.css`
+
+#### Task 4.2: Animation System
+- Framer Motion integration
+- Smooth transitions between modes
+- Loading animations
+
+**Files to Create:**
+- `src/components/auth/animations/transitions.ts`
+- `src/components/auth/animations/variants.ts`
+
+### Phase 5: Integration & Testing (Depends on Phases 3 & 4)
+**Duration**: 1-2 days
+**Dependencies**: Phase 3.1, Phase 3.2, Phase 4.1
+
+#### Task 5.1: Component Integration
+- Integrate all components into main AgilityAuth component
+- Implement mode switching logic
+- Handle configuration prop passing
+
+#### Task 5.2: SDK Integration
+- Export component from main SDK
+- Update package.json with React peer dependencies
+- Create usage documentation
+
+**Files to Create:**
+- `src/components/auth/AgilityAuth.tsx` (complete implementation)
+- `docs/auth-component.md`
+
+### Phase 6: Advanced Features (Optional)
+**Duration**: 1-2 days
+**Dependencies**: Phase 5
+
+#### Task 6.1: Advanced Customization
+- Custom render props support
+- Slot-based customization
+- Advanced theming system
+
+#### Task 6.2: Accessibility & Performance
+- ARIA labels and keyboard navigation
+- Performance optimizations
+- Bundle size optimization
+
+## File Structure
+```
+src/
+├── components/
+│   └── auth/
+│       ├── index.ts                          # Main export
+│       ├── AgilityAuth.tsx                   # Root component (~100 lines)
+│       ├── components/
+│       │   ├── AuthButton.tsx                # ~80 lines
+│       │   ├── UserInfo.tsx                  # ~60 lines
+│       │   ├── WebsiteSelector.tsx           # ~90 lines
+│       │   ├── LocaleSelector.tsx            # ~80 lines
+│       │   ├── LoadingSpinner.tsx            # ~40 lines
+│       │   ├── ErrorDisplay.tsx              # ~50 lines
+│       │   └── SelectionSummary.tsx          # ~70 lines
+│       ├── layouts/
+│       │   ├── FullscreenLayout.tsx          # ~90 lines
+│       │   ├── FooterLayout.tsx              # ~80 lines
+│       │   └── ButtonLayout.tsx              # ~40 lines
+│       ├── hooks/
+│       │   ├── useAgilityAuth.ts             # ~100 lines
+│       │   └── useWebsiteSelection.ts        # ~80 lines
+│       ├── context/
+│       │   ├── AuthContext.tsx               # ~60 lines
+│       │   └── AuthProvider.tsx              # ~90 lines
+│       ├── styles/
+│       │   ├── base.module.css
+│       │   ├── themes.module.css
+│       │   ├── layouts.module.css
+│       │   └── components.module.css
+│       └── animations/
+│           ├── transitions.ts                # ~50 lines
+│           └── variants.ts                   # ~40 lines
+├── models/
+│   ├── authComponent.ts                      # Component interfaces
+│   ├── authConfig.ts                         # Configuration types
+│   └── authState.ts                          # State types
+```
+
+## Dependencies
+- React 16.8+ (hooks support)
+- Framer Motion (animations)
+- Existing SDK authentication methods
+
+## Success Criteria
+1. **Modularity**: Each component < 100 lines, single responsibility
+2. **Configurability**: Extensive customization without code changes
+3. **Performance**: Fast loading, minimal bundle impact
+4. **Accessibility**: WCAG 2.1 AA compliance
+5. **Developer Experience**: Intuitive API, comprehensive TypeScript support
+6. **Visual Polish**: Smooth animations, responsive design
+
+## Migration Path
+1. Existing apps can gradually adopt the component
+2. Backward compatibility with existing auth methods
+3. Progressive enhancement approach
+4. Clear migration documentation
+
+## Next Steps
+1. Start with Phase 1 (Foundation & Models)
+2. Create type definitions and basic structure
+3. Implement authentication hook (Phase 2.1)
+4. Build core UI components (Phase 3.1)
+5. Iterate and refine based on feedback