@agility/management-sdk 0.1.2 → 0.1.4-beta.1

package/.cursor/manifest.md

@@ -0,0 +1,153 @@
+# Agility CMS Management SDK TypeScript - Authentication Implementation Manifest
+
+## Current State Analysis
+
+### Existing Implementation Issues
+1. **Security**: Currently using localStorage for token storage (insecure)
+2. **API Exposure**: Exposing internal auth methods like `client.authMethods.generateAuthUrl`
+3. **Incomplete Token Management**: Only handling access tokens, not refresh tokens
+4. **Complex API**: Requiring users to interact with `authMethods` directly
+5. **Backwards Compatibility**: Need to ensure existing manual token approach still works
+
+### Current Todo Items
+- ✅ Remove createAuthenticatedClient method from AuthMethods
+- ✅ Modify AuthMethods to use shared Options instance  
+- 🔄 Add authenticate() convenience method to ApiClient (needs refactoring)
+- ⏳ Update all authentication examples in documentation
+- ⏳ Add automatic token refresh to ClientInstance
+
+## Target Architecture
+
+### 1. Secure Token Storage with Keytar
+- Replace localStorage with `keytar` for secure credential storage
+- Store both access and refresh tokens securely
+- Handle token encryption/decryption automatically
+
+### 2. Simplified Public API
+```typescript
+// Existing manual pattern (unchanged)
+let options = new mgmtApi.Options();
+options.token = access_token; // User obtained token
+let apiClient = new mgmtApi.ApiClient(options);
+
+// New OAuth pattern - Simple and clean
+let apiClient = new mgmtApi.ApiClient(); // or new mgmtApi.ApiClient(options)
+await apiClient.auth(); // Handles OAuth flow internally
+// Now all methods work with authenticated client
+```
+
+### 3. Internal Authentication Architecture
+- AuthMethods becomes internal-only (not exposed in public API)
+- **Only public method**: `apiClient.auth()` - handles OAuth flow internally
+- Automatic token refresh handled transparently
+- Existing manual token pattern continues to work unchanged
+
+### 4. Dual Authentication Support
+- **New approach**: `apiClient.auth()` - handles OAuth flow internally, no parameters
+- **Existing approach**: `options.token = token` - continues to work unchanged
+
+## Implementation Plan
+
+### Phase 1: Core Security Infrastructure
+1. **Add keytar dependency** 
+   - Update package.json with keytar dependency
+   - Create secure token storage abstraction
+
+2. **Enhance token management**
+   - Create TokenStorage class using keytar
+   - Support both access and refresh tokens with expiration tracking
+   - Add token encryption/decryption
+   - Automatic expiration validation
+
+3. **Refactor AuthMethods to be internal-only**
+   - Keep all OAuth methods but make them internal
+   - Remove public exposure from ApiClient
+   - Focus on internal token management
+
+### Phase 2: ApiClient Authentication Interface
+1. **Implement simple auth() method**
+   - `apiClient.auth()` - launches OAuth flow internally (no parameters)
+   - Internal handling of token storage and refresh
+   - Automatic expiration checking and refresh
+
+2. **Maintain backwards compatibility**
+   - Keep existing options.token support
+   - Priority: manual tokens > stored tokens > OAuth flow
+
+3. **Enhanced ClientInstance integration**
+   - Automatic token refresh on 401 responses
+   - Seamless token management across all API methods
+
+### Phase 3: Documentation and Examples
+1. **Update all examples to use simple API**
+   - Replace `client.authMethods.x` with `client.auth()`
+   - Show both new and legacy approaches
+   - Emphasize security benefits
+
+2. **Add keytar setup instructions**
+   - Installation requirements
+   - Platform-specific considerations
+   - Fallback strategies
+
+## Detailed Implementation Tasks
+
+### Task 1: Secure Token Storage (keytar)
+- [ ] Add keytar to package.json dependencies
+- [ ] Create TokenStorage class
+- [ ] Implement secure get/set/delete methods
+- [ ] Add platform compatibility checks
+- [ ] Create fallback for unsupported platforms
+
+### Task 2: Refactor AuthMethods Architecture
+- [ ] Make AuthMethods internal-only
+- [ ] Remove public authMethods exposure from ApiClient
+- [ ] Enhance token management to handle both access/refresh with expiration
+- [ ] Add automatic token refresh logic with expiration validation
+
+### Task 3: Implement Clean ApiClient.auth() API
+- [ ] Create simple auth() method with OAuth flow (no parameters)
+- [ ] Internal token storage and refresh handling
+- [ ] Automatic expiration checking and token refresh
+- [ ] Add helper methods: isAuthenticated(), clearAuth()
+
+### Task 4: ClientInstance Integration
+- [ ] Automatic token refresh on 401 responses
+- [ ] Seamless token propagation to all method classes
+- [ ] Error handling for expired/invalid tokens
+
+### Task 5: Documentation Updates
+- [ ] Update auth.md with new simple API examples
+- [ ] Update README.md with keytar setup instructions
+- [ ] Update all method documentation files
+- [ ] Add migration guide for existing users
+
+## Security Considerations
+- **Token encryption**: All tokens encrypted at rest using keytar
+- **No localStorage**: Eliminate insecure browser storage
+- **Automatic cleanup**: Tokens removed on logout/error
+- **Platform native**: Use OS-level secure storage (Keychain on macOS, etc.)
+
+## Backwards Compatibility Strategy
+1. **Options.token support**: Keep existing manual token approach
+2. **Priority order**: Manual tokens > stored tokens > OAuth flow
+3. **Graceful degradation**: Fallback if keytar unavailable
+4. **Migration path**: Clear documentation for transition
+
+## Testing Strategy
+- Unit tests for TokenStorage class
+- Integration tests for auth() method
+- Cross-platform testing (macOS, Windows, Linux)
+- Backwards compatibility verification
+
+## Performance Considerations
+- Lazy loading of keytar dependency
+- Efficient token refresh logic
+- Minimal overhead for manual token users
+- Optimized OAuth flow handling
+
+## Next Steps
+1. Implement TokenStorage with keytar
+2. Refactor AuthMethods to be internal-only
+3. Create clean ApiClient.auth() interface
+4. Update documentation and examples
+5. Add comprehensive testing

package/.env

@@ -0,0 +1,92 @@
+# Agility CMS SDK Configuration
+AGILITY_GUID=f3866b86-u
+AGILITY_API_KEY=defaultpreview.2672a9e1f5f8fade023029763b540c64eabfab48f92e693fa01081d845783dca
+AGILITY_LOCALES=en-us
+AGILITY_SITEMAP=website
+AGILITY_API_ISPREVIEW=true
+AGILITY_MANAGEMENT_API_BASE_URL=https://mgmt.aglty.io
+
+# Test Environment Selection (dev, prod, prod-aus, prod-ca, prod-eu, preprod-contentserver, preprod-fetchapi)
+# TEST_ENV=dev // passed in by CI/CD and packages script
+
+# Azure Storage Configuration (for token management)
+STORAGE_ACCOUNT=agilitydevstorage
+STORAGE_ACCOUNT_KEY=JrNwq93Zi9B0FJfqTToMQvArtyrNsGdgEVxaUgfMs/Uuv2+aatR5kRNRUeyuxTITJe7zw7n8mQTw+AStU9I1Bg==
+STORAGE_ACCOUNT_TABLE=TokenInfo
+
+# Dev Environment Configuration
+DEV_GUID=c741222b-1080-45f6-9a7f-982381c5a485
+DEV_API_KEY_FETCH=UnitTestsFetch.2ace650991363fbcffa6776d411d1b0d616b8e3424ce842b81cba7af0039197e
+DEV_API_KEY_PREVIEW=UnitTestsPreview.69e6bca345ced0b7ca5ab358b351ea5c870790a5945c25d749a865332906b124
+DEV_WEBSITE_NAME=Headless Integration Testing
+DEV_SECURITY_KEY=SABlAGEAZABsAGUAcwBzACAASQBuAHQAZQBnAHIAYQB0AGkAbwBuACAAVABlAHMAdABpAG4AZwAtAEEANwA5ADUANAAxAEMANQAtAEUAQgAzADIALQA0ADYAMwBCAC0AQgBBADYANgAtADkARQBDAEMANwBCADYAOAA3ADYANQBFAA==
+DEV_CONTENT_SERVER_BASE_URL=https://dev-contentserver.publishwithagility.com
+DEV_FETCH_API_BASE_URL=https://api-dev.aglty.io
+DEV_DIRECT_FETCH_API_BASE_URL=http://agility-fetch-api-dev.azurewebsites.net
+DEV_MANAGEMENT_API_BASE_URL=https://mgmt-dev.aglty.io
+
+# Production Environment Configuration
+PROD_GUID=9de2e54a-ff2f-426c-b424-08ff5f86fa89
+PROD_API_KEY_FETCH=defaultlive.b47f945a9af1a76e3f8f78d2f00b314e22bab26f23f3db6e1d22133be00243ac
+PROD_API_KEY_PREVIEW=defaultpreview.2d48ab74ab1337b444207510d89988aedf07300bbba33e6771ed0b5d825d47b5
+PROD_WEBSITE_NAME=Headless Integration Testing
+PROD_SECURITY_KEY=SABlAGEAZABsAGUAcwBzACAASQBuAHQAZQBnAHIAYQB0AGkAbwBuACAAVABlAHMAdABpAG4AZwAtAEEANwA5ADUANAAxAEMANQAtAEUAQgAzADIALQA0ADYAMwBCAC0AQgBBADYANgAtADkARQBDAEMANwBCADYAOAA3ADYANQBFAA==
+PROD_CONTENT_SERVER_BASE_URL=https://contentserver1503.agilitycms.com
+PROD_FETCH_API_BASE_URL=https://api.aglty.io
+PROD_DIRECT_FETCH_API_BASE_URL=https://agility-fetch-api-usa.azurewebsites.net
+PROD_MANAGEMENT_API_BASE_URL=https://mgmt.aglty.io
+
+# Production Australia Environment Configuration
+PROD_AUS_GUID=6155f68e-a
+PROD_AUS_API_KEY_FETCH=fetch.c89b614a7355f459fa849c1bb2e2fb7d389551317fd35a170c482ab1c52098a1
+PROD_AUS_API_KEY_PREVIEW=preview.8ad5baa258698b3faf9ce7f420b43d2ea6384b4d3cf610b8e280c7d5c1ba00be
+PROD_AUS_WEBSITE_NAME=Headless Integration Testing - AUS
+PROD_AUS_SECURITY_KEY=SABlAGEAZABsAGUAcwBzACAASQBuAHQAZQBnAHIAYQB0AGkAbwBuACAAVABlAHMAdABpAG4AZwAtAEEANwA5ADUANAAxAEMANQAtAEUAQgAzADIALQA0ADYAMwBCAC0AQgBBADYANgAtADkARQBDAEMANwBCADYAOAA3ADYANQBFAA==
+PROD_AUS_CONTENT_SERVER_BASE_URL=https://contentserver-aus.agilitycms.com
+PROD_AUS_FETCH_API_BASE_URL=https://api-aus.aglty.io
+PROD_AUS_DIRECT_FETCH_API_BASE_URL=https://agility-fetch-api-aus.azurewebsites.net/
+PROD_AUS_MANAGEMENT_API_BASE_URL=https://mgmt-aus.aglty.io
+
+# Production Canada Environment Configuration
+PROD_CA_GUID=9de2e54a-ff2f-426c-b424-190060970b9a
+PROD_CA_API_KEY_FETCH=Fetch.de1ff4693f4dd06cb2f350e901ac994fd9b2b1c692ff34ada13776b21be7abc2
+PROD_CA_API_KEY_PREVIEW=Preview.c7450fccf0089edc128fdd7954269b61ba363f63b409ece79c007596e722f205
+PROD_CA_WEBSITE_NAME=Headless Integration Testing - CA
+PROD_CA_SECURITY_KEY=SABlAGEAZABsAGUAcwBzACAASQBuAHQAZQBnAHIAYQB0AGkAbwBuACAAVABlAHMAdABpAG4AZwAtAEEANwA5ADUANAAxAEMANQAtAEUAQgAzADIALQA0ADYAMwBCAC0AQgBBADYANgAtADkARQBDAEMANwBCADYAOAA3ADYANQBFAA==
+PROD_CA_CONTENT_SERVER_BASE_URL=https://contentserver-ca.agilitycms.com
+PROD_CA_FETCH_API_BASE_URL=https://api-ca.aglty.io
+PROD_CA_DIRECT_FETCH_API_BASE_URL=https://agility-fetch-api-canada.azurewebsites.net
+PROD_CA_MANAGEMENT_API_BASE_URL=https://mgmt-ca.aglty.io
+
+# Production Europe Environment Configuration
+PROD_EU_GUID=9de2e54a-ff2f-426c-b424-201171a81cab
+PROD_EU_API_KEY_FETCH=Fetch.2c4e5d26008c0c964d2da5fe99714163b996696424c375c3c9ef44326405e702
+PROD_EU_API_KEY_PREVIEW=Preview.64254d904a0cc4011f4d582b4a93e5e56fd0f2f516f190477ada67c322ee8a17
+PROD_EU_WEBSITE_NAME=Headless Integration Testing - EU
+PROD_EU_SECURITY_KEY=SABlAGEAZABsAGUAcwBzACAASQBuAHQAZQBnAHIAYQB0AGkAbwBuACAAVABlAHMAdABpAG4AZwAtAEEANwA5ADUANAAxAEMANQAtAEUAQgAzADIALQA0ADYAMwBCAC0AQgBBADYANgAtADkARQBDAEMANwBCADYAOAA3ADYANQBFAA==
+PROD_EU_CONTENT_SERVER_BASE_URL=https://contentserver-eu.agilitycms.com
+PROD_EU_FETCH_API_BASE_URL=https://api-eu.aglty.io
+PROD_EU_DIRECT_FETCH_API_BASE_URL=https://agility-fetch-api-europe.azurewebsites.net
+PROD_EU_MANAGEMENT_API_BASE_URL=https://mgmt-eu.aglty.io
+
+# Preprod Content Server Environment Configuration
+PREPROD_CONTENTSERVER_GUID=9de2e54a-ff2f-426c-b424-08ff5f86fa89
+PREPROD_CONTENTSERVER_API_KEY_FETCH=defaultlive.b47f945a9af1a76e3f8f78d2f00b314e22bab26f23f3db6e1d22133be00243ac
+PREPROD_CONTENTSERVER_API_KEY_PREVIEW=defaultpreview.2d48ab74ab1337b444207510d89988aedf07300bbba33e6771ed0b5d825d47b5
+PREPROD_CONTENTSERVER_WEBSITE_NAME=Headless Integration Testing
+PREPROD_CONTENTSERVER_SECURITY_KEY=SABlAGEAZABsAGUAcwBzACAASQBuAHQAZQBnAHIAYQB0AGkAbwBuACAAVABlAHMAdABpAG4AZwAtAEEANwA5ADUANAAxAEMANQAtAEUAQgAzADIALQA0ADYAMwBCAC0AQgBBADYANgAtADkARQBDAEMANwBCADYAOAA3ADYANQBFAA==
+PREPROD_CONTENTSERVER_CONTENT_SERVER_BASE_URL=https://contentserver-usa-preprod.azurewebsites.net
+PREPROD_CONTENTSERVER_FETCH_API_BASE_URL=https://api.aglty.io
+PREPROD_CONTENTSERVER_DIRECT_FETCH_API_BASE_URL=https://agility-fetch-api-usa.azurewebsites.net
+PREPROD_CONTENTSERVER_MANAGEMENT_API_BASE_URL=https://mgmt.aglty.io
+
+# Preprod Fetch API Environment Configuration
+PREPROD_FETCHAPI_GUID=9de2e54a-ff2f-426c-b424-08ff5f86fa89
+PREPROD_FETCHAPI_API_KEY_FETCH=defaultlive.b47f945a9af1a76e3f8f78d2f00b314e22bab26f23f3db6e1d22133be00243ac
+PREPROD_FETCHAPI_API_KEY_PREVIEW=defaultpreview.2d48ab74ab1337b444207510d89988aedf07300bbba33e6771ed0b5d825d47b5
+PREPROD_FETCHAPI_WEBSITE_NAME=Headless Integration Testing
+PREPROD_FETCHAPI_SECURITY_KEY=SABlAGEAZABsAGUAcwBzACAASQBuAHQAZQBnAHIAYQB0AGkAbwBuACAAVABlAHMAdABpAG4AZwAtAEEANwA5ADUANAAxAEMANQAtAEUAQgAzADIALQA0ADYAMwBCAC0AQgBBADYANgAtADkARQBDAEMANwBCADYAOAA3ADYANQBFAA==
+PREPROD_FETCHAPI_CONTENT_SERVER_BASE_URL=https://contentserver1503.agilitycms.com
+PREPROD_FETCHAPI_FETCH_API_BASE_URL=https://api.aglty.io
+PREPROD_FETCHAPI_DIRECT_FETCH_API_BASE_URL=https://agility-fetch-api-usa-preprod.azurewebsites.net
+PREPROD_FETCHAPI_MANAGEMENT_API_BASE_URL=https://mgmt.aglty.io