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

package/docs/auth.md

@@ -0,0 +1,594 @@
+# Agility CMS & Management API TypeScript SDK
+
+## Authentication & Setup
+
+This guide covers how to authenticate with the Agility CMS Management API and initialize the SDK for making API requests.
+
+**🚀 NEW: Simplified Authentication**
+We now provide a streamlined authentication experience with secure token storage and automatic token refresh. The new `ApiClient.auth()` method handles the entire OAuth flow internally.
+
+### Prerequisites
+1. Valid Agility CMS credentials
+2. A configured OAuth application in your Agility CMS instance
+3. A valid redirect URI for OAuth flow
+4. **Node.js**: For secure token storage, keytar is required (`npm install keytar`)
+
+### Setup Instructions
+
+#### Install keytar for Secure Token Storage
+```bash
+npm install keytar
+```
+
+**Platform Requirements:**
+- **macOS**: Uses Keychain (built-in)
+- **Windows**: Uses Windows Credential Store (built-in)
+- **Linux**: Requires `libsecret` development package
+  ```bash
+  # Ubuntu/Debian
+  sudo apt-get install libsecret-1-dev
+  
+  # Red Hat/CentOS
+  sudo yum install libsecret-devel
+  ```
+
+### Authentication Approaches
+
+You have two options for authentication:
+
+#### 1. **Recommended: Simple OAuth Flow**
+Use the new `ApiClient.auth()` method for streamlined authentication:
+
+```typescript
+import * as mgmtApi from '@agility/management-sdk';
+
+// Simple OAuth authentication
+const apiClient = new mgmtApi.ApiClient();
+await apiClient.auth();
+
+// Client is now authenticated - make API calls directly
+const guid = "your-website-guid";
+const locale = "en-us";
+const contentItem = await apiClient.contentMethods.getContentItem(22, guid, locale);
+```
+
+The `auth()` method:
+- Generates OAuth authorization URL
+- Handles token exchange automatically
+- Stores tokens securely using keytar
+- Provides automatic token refresh
+
+#### 2. **Manual Token Management (Existing Pattern)**
+For applications that need to handle tokens manually, the traditional approach is still fully supported:
+
+```typescript
+import * as mgmtApi from "@agility/management-sdk";
+
+// Manual token approach (still supported)
+const options = new mgmtApi.Options();
+options.token = "your-access-token";
+const apiClient = new mgmtApi.ApiClient(options);
+
+const guid = "your-website-guid";
+const locale = "en-us";
+
+const contentItem = await apiClient.contentMethods.getContentItem(22, guid, locale);
+console.log(JSON.stringify(contentItem));
+```
+
+For custom OAuth implementations, you can handle the OAuth flow manually:
+
+Before using the SDK, you must authenticate against the Agility Management API to obtain a valid access token. This token is required for all subsequent API requests.
+
+The authentication process uses OAuth 2.0 and requires multiple steps:
+
+#### Step 1: Initiate Authorization Flow
+
+First, initiate the authorization flow by making a GET request to the authorization endpoint:
+
+```javascript
+const authUrl = 'https://mgmt.aglty.io/oauth/authorize';
+
+//if you wish to implement offline access using refresh tokens, use this URL (enables refresh tokens)
+//const authUrl = 'https://mgmt.aglty.io/oauth/authorize?scope=offline-access '; 
+
+const params = new URLSearchParams({
+  response_type: 'code',
+  redirect_uri: 'YOUR_REDIRECT_URI',
+  state: 'YOUR_STATE',
+  scope: 'openid profile email offline_access'
+});
+
+// Redirect the user to the authorization URL
+window.location.href = `${authUrl}?${params.toString()}`;
+```
+
+#### Step 2: Exchange Authorization Code for Access Token
+
+After successful authentication, you'll receive an authorization code at your redirect URI. Use this code to obtain an access token:
+
+```javascript
+const response = await fetch('https://mgmt.aglty.io/oauth/token', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/x-www-form-urlencoded'
+  },
+  body: new URLSearchParams({
+    code: 'YOUR_AUTHORIZATION_CODE'
+  })
+});
+
+const { access_token, refresh_token, expires_in } = await response.json();
+```
+
+#### Step 3: Initialize the SDK
+
+Use the obtained token to initialize the SDK:
+
+```javascript
+import * as mgmtApi from "@agility/management-sdk";
+
+// Initialize the Options Class with your authentication token
+let options = new mgmtApi.Options();
+options.token = access_token; // Use the token obtained from authentication
+
+// Initialize the APIClient Class
+let apiClient = new mgmtApi.ApiClient(options);
+
+let guid = "<<Provide the Guid of the Website>>";
+let locale = "<<Provide the locale of the Website>>"; // Example: en-us
+
+// Now you can make authenticated requests
+var contentItem = await apiClient.contentMethods.getContentItem(22, guid, locale);
+console.log(JSON.stringify(contentItem));
+```
+
+#### Step 4: Refresh Access Tokens
+
+When the access token expires, use the refresh token to obtain a new access token:
+
+```javascript
+const response = await fetch('https://mgmt.aglty.io/oauth/refresh', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    refresh_token: 'YOUR_REFRESH_TOKEN'
+  })
+});
+
+const { access_token, refresh_token, expires_in } = await response.json();
+```
+
+### Important Authentication Notes
+
+- **Token Lifetime**: The access token has a limited lifetime (typically 1 hour)
+- **Refresh Tokens**: The refresh token can be used to obtain new access tokens
+- **Security**: Store refresh tokens securely and never expose them in client-side code
+- **Error Handling**: Implement proper error handling for authentication failures
+
+### Making API Requests
+
+Once authenticated, you can make requests using the SDK:
+
+#### Using New Simple Authentication (Recommended)
+```typescript
+import * as mgmtApi from '@agility/management-sdk';
+
+// Simple OAuth authentication
+const apiClient = new mgmtApi.ApiClient();
+await apiClient.auth();
+
+// Client is now authenticated and handles token refresh automatically
+const guid = "your-website-guid";
+const locale = "en-us";
+const contentItem = await apiClient.contentMethods.getContentItem(22, guid, locale);
+console.log(JSON.stringify(contentItem));
+```
+
+#### Manual Client Creation (Existing Pattern)
+```javascript
+import * as mgmtApi from "@agility/management-sdk";
+
+//initialize the Options Class
+let options = new mgmtApi.Options();
+
+options.token = "<<Provide Auth Token>>"
+//Initialize the APIClient Class
+let apiClient = new mgmtApi.ApiClient(options);
+
+let guid = "<<Provide the Guid of the Website>>";
+let locale = "<<Provide the locale of the Website>>"; //Example: en-us
+
+//make the request: get a content item with the ID '22'
+var contentItem = await apiClient.contentMethods.getContentItem(22,guid, locale);
+
+//To log the response of the contentItem object in console.
+console.log(JSON.stringify(contentItem));
+```
+
+### OAuth Flow Examples
+
+#### For Web Applications
+
+```javascript
+// Redirect user to authorization URL
+function initiateAuth() {
+    const authUrl = 'https://mgmt.aglty.io/oauth/authorize';
+    const params = new URLSearchParams({
+        response_type: 'code',
+        redirect_uri: window.location.origin + '/auth/callback',
+        state: generateRandomState(),
+        scope: 'openid profile email offline_access'
+    });
+    
+    window.location.href = `${authUrl}?${params.toString()}`;
+}
+
+// Handle callback in your redirect URI endpoint
+async function handleAuthCallback(code) {
+    try {
+        const response = await fetch('https://mgmt.aglty.io/oauth/token', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded'
+            },
+            body: new URLSearchParams({
+                code: code
+            })
+        });
+        
+        const tokens = await response.json();
+        
+        // Store tokens securely
+        localStorage.setItem('access_token', tokens.access_token);
+        localStorage.setItem('refresh_token', tokens.refresh_token);
+        
+        return tokens;
+    } catch (error) {
+        console.error('Authentication failed:', error);
+        throw error;
+    }
+}
+```
+
+#### For Server-Side Applications
+
+```javascript
+// Express.js example
+app.get('/auth/agility', (req, res) => {
+    const authUrl = 'https://mgmt.aglty.io/oauth/authorize';
+    const params = new URLSearchParams({
+        response_type: 'code',
+        redirect_uri: 'https://yourapp.com/auth/callback',
+        state: req.session.state,
+        scope: 'openid profile email offline_access'
+    });
+    
+    res.redirect(`${authUrl}?${params.toString()}`);
+});
+
+app.get('/auth/callback', async (req, res) => {
+    const { code, state } = req.query;
+    
+    // Verify state parameter
+    if (state !== req.session.state) {
+        return res.status(400).send('Invalid state parameter');
+    }
+    
+    try {
+        const response = await fetch('https://mgmt.aglty.io/oauth/token', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded'
+            },
+            body: new URLSearchParams({
+                code: code
+            })
+        });
+        
+        const tokens = await response.json();
+        
+        // Store tokens in session or database
+        req.session.tokens = tokens;
+        
+        res.redirect('/dashboard');
+    } catch (error) {
+        res.status(500).send('Authentication failed');
+    }
+});
+```
+
+### Token Management
+
+#### Automatic Token Refresh
+
+```javascript
+class AgilityTokenManager {
+    constructor(refreshToken) {
+        this.refreshToken = refreshToken;
+        this.accessToken = null;
+        this.expiresAt = null;
+    }
+    
+    async getValidToken() {
+        if (!this.accessToken || Date.now() >= this.expiresAt) {
+            await this.refreshAccessToken();
+        }
+        return this.accessToken;
+    }
+    
+    async refreshAccessToken() {
+        try {
+            const response = await fetch('https://mgmt.aglty.io/oauth/refresh', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    refresh_token: this.refreshToken
+                })
+            });
+            
+            const tokens = await response.json();
+            
+            this.accessToken = tokens.access_token;
+            this.refreshToken = tokens.refresh_token; // Update refresh token if provided
+            this.expiresAt = Date.now() + (tokens.expires_in * 1000);
+            
+            return tokens;
+        } catch (error) {
+            console.error('Token refresh failed:', error);
+            throw error;
+        }
+    }
+}
+
+// Usage
+const tokenManager = new AgilityTokenManager('your-refresh-token');
+const token = await tokenManager.getValidToken();
+
+const options = new mgmtApi.Options();
+options.token = token;
+const apiClient = new mgmtApi.ApiClient(options);
+```
+
+### Error Handling
+
+#### Common Authentication Errors
+
+```javascript
+async function makeAuthenticatedRequest() {
+    try {
+        const apiClient = new mgmtApi.ApiClient({ token: accessToken });
+        const result = await apiClient.contentMethods.getContentItem(123, guid, locale);
+        return result;
+    } catch (error) {
+        if (error.response?.status === 401) {
+            // Token expired or invalid
+            console.log('Authentication failed - refreshing token');
+            await refreshAccessToken();
+            
+            // Retry the request
+            const apiClient = new mgmtApi.ApiClient({ token: newAccessToken });
+            return await apiClient.contentMethods.getContentItem(123, guid, locale);
+        } else if (error.response?.status === 403) {
+            // Insufficient permissions
+            console.error('Access denied - insufficient permissions');
+            throw new Error('User does not have permission for this operation');
+        } else {
+            // Other errors
+            console.error('API request failed:', error.message);
+            throw error;
+        }
+    }
+}
+```
+
+### Migration Guide
+
+#### Migrating from Manual OAuth to Simple Authentication
+
+**Before (Manual OAuth):**
+```typescript
+// Old approach - manual OAuth handling
+import * as mgmtApi from '@agility/management-sdk';
+
+const options = new mgmtApi.Options();
+options.token = 'manually-obtained-token';
+const apiClient = new mgmtApi.ApiClient(options);
+
+// Manual token refresh required
+const contentItem = await apiClient.contentMethods.getContentItem(22, guid, locale);
+```
+
+**After (Simple Authentication):**
+```typescript
+// New approach - automatic OAuth handling
+import * as mgmtApi from '@agility/management-sdk';
+
+const apiClient = new mgmtApi.ApiClient();
+await apiClient.auth();
+
+// Automatic token refresh handled internally
+const contentItem = await apiClient.contentMethods.getContentItem(22, guid, locale);
+```
+
+#### Migrating from AuthMethods Class
+
+**Before (AuthMethods Class):**
+```typescript
+import { AuthMethods } from '@agility/management-sdk';
+
+const auth = new AuthMethods();
+const client = auth.createAuthenticatedClient('token');
+```
+
+**After (Simple Authentication):**
+```typescript
+import * as mgmtApi from '@agility/management-sdk';
+
+const apiClient = new mgmtApi.ApiClient();
+await apiClient.auth();
+```
+
+### Advanced Features
+
+#### Secure Token Storage
+The new authentication system uses OS-level secure storage:
+
+- **macOS**: Keychain Access
+- **Windows**: Windows Credential Store  
+- **Linux**: libsecret (GNOME Keyring)
+
+Tokens are encrypted and stored securely, with automatic cleanup on logout.
+
+#### Automatic Token Refresh
+The SDK now handles token refresh automatically:
+
+```typescript
+const apiClient = new mgmtApi.ApiClient();
+await apiClient.auth();
+
+// Token refresh happens automatically on 401 errors
+const contentItem = await apiClient.contentMethods.getContentItem(22, guid, locale);
+// If token was expired, it gets refreshed transparently
+```
+
+#### Custom OAuth Configuration
+You can customize the OAuth flow:
+
+```typescript
+const apiClient = new mgmtApi.ApiClient();
+await apiClient.auth({
+    redirectUri: 'https://yourapp.com/custom-callback',
+    scope: 'openid profile email offline_access',
+    region: 'us' // or 'ca', 'eu', 'au', 'dev'
+});
+```
+
+#### Manual Token Exchange
+For custom OAuth implementations:
+
+```typescript
+const apiClient = new mgmtApi.ApiClient();
+
+// Exchange authorization code for tokens
+const tokens = await apiClient.exchangeCodeForToken({
+    code: 'authorization_code_from_callback',
+    redirectUri: 'https://yourapp.com/auth/callback'
+});
+
+// Tokens are automatically stored and used
+```
+
+### Best Practices
+
+#### Security Considerations
+
+1. **Use secure token storage (automatic with new auth)**
+   ```typescript
+   // ✅ Recommended - automatic secure storage
+   const apiClient = new mgmtApi.ApiClient();
+   await apiClient.auth(); // Tokens stored securely in OS keychain
+   
+   // ✅ CI/CD - manual token (for automated environments)
+   const options = new mgmtApi.Options();
+   options.token = process.env.AGILITY_ACCESS_TOKEN;
+   const apiClient = new mgmtApi.ApiClient(options);
+   
+   // ❌ Bad - hardcoded tokens
+   options.token = 'your-secret-token'; // Never do this
+   ```
+
+2. **Leverage automatic token refresh**
+   ```typescript
+   // ✅ Automatic token refresh (new approach)
+   const apiClient = new mgmtApi.ApiClient();
+   await apiClient.auth();
+   
+   // Token refresh happens automatically on 401 errors
+   const contentItem = await apiClient.contentMethods.getContentItem(22, guid, locale);
+   ```
+
+3. **Handle authentication errors gracefully**
+   ```typescript
+   const apiClient = new mgmtApi.ApiClient();
+   
+   try {
+       await apiClient.auth();
+       const contentItem = await apiClient.contentMethods.getContentItem(22, guid, locale);
+   } catch (error) {
+       if (error.message.includes('OAuth flow requires manual implementation')) {
+           // Handle OAuth flow manually
+           console.log('Visit the OAuth URL to authenticate');
+       } else {
+           // Handle other auth errors
+           console.error('Authentication failed:', error);
+       }
+   }
+   ```
+
+4. **Clear tokens on logout**
+   ```typescript
+   const apiClient = new mgmtApi.ApiClient();
+   await apiClient.auth();
+   
+   // ... use API client ...
+   
+   // Clear tokens securely on logout
+   await apiClient.clearToken();
+   ```
+
+#### Performance Optimization
+
+1. **Reuse API client instances**
+   ```javascript
+   // ✅ Good - single instance
+   const apiClient = new mgmtApi.ApiClient(options);
+   
+   // Use the same instance for multiple requests
+   const content1 = await apiClient.contentMethods.getContentItem(1, guid, locale);
+   const content2 = await apiClient.contentMethods.getContentItem(2, guid, locale);
+   ```
+
+2. **Implement request caching**
+   ```javascript
+   class CachedAgilityClient {
+       constructor(options) {
+           this.client = new mgmtApi.ApiClient(options);
+           this.cache = new Map();
+       }
+       
+       async getContentItem(id, guid, locale) {
+           const cacheKey = `content-${id}-${guid}-${locale}`;
+           
+           if (this.cache.has(cacheKey)) {
+               return this.cache.get(cacheKey);
+           }
+           
+           const result = await this.client.contentMethods.getContentItem(id, guid, locale);
+           this.cache.set(cacheKey, result);
+           
+           return result;
+       }
+   }
+   ```
+
+---
+
+## Navigation
+- [← Back to Main Documentation](../README.md)
+- [CI/CD & Automated Environments](./cicd.md)
+- [AssetMethods](./asset-methods.md)
+- [BatchMethods](./batch-methods.md)
+- [ContentMethods](./content-methods.md)
+- [ContainerMethods](./container-methods.md)
+- [InstanceMethods](./instance-methods.md)
+- [InstanceUserMethods](./instance-user-methods.md)
+- [ModelMethods](./model-methods.md)
+- [PageMethods](./page-methods.md)
+- [ServerUserMethods](./server-user-methods.md)
+- [WebhookMethods](./webhook-methods.md)
+- [Multi-Instance Operations](./multi-instance-operations.md)