@agility/management-sdk 0.1.38 → 0.1.39

package/docs/cicd.md

@@ -1,607 +1,607 @@
-# CI/CD & Automated Environments
-
-This guide covers using the Agility CMS Management SDK in automated environments such as CI/CD pipelines, serverless functions, and other programmatic scenarios where the OAuth flow isn't practical.
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Token-Based Authentication](#token-based-authentication)
-- [Environment Configuration](#environment-configuration)
-- [CI/CD Pipeline Examples](#cicd-pipeline-examples)
-- [Serverless Functions](#serverless-functions)
-- [Token Management](#token-management)
-- [Security Best Practices](#security-best-practices)
-
----
-
-## Overview
-
-In automated environments, the interactive OAuth flow isn't practical. Instead, you'll use **access tokens** directly. This approach is ideal for:
-
-- **CI/CD Pipelines** - Automated content deployment
-- **Serverless Functions** - Event-triggered content operations
-- **Scheduled Jobs** - Content synchronization, backups, etc.
-- **Build Processes** - Static site generation with fresh content
-- **Automated Testing** - Integration tests requiring content operations
-
----
-
-## Token-Based Authentication
-
-### Using Options Constructor
-
-```typescript
-import * as mgmtApi from '@agility/management-sdk';
-
-// Set token via Options constructor
-const options = new mgmtApi.Options();
-options.token = process.env.AGILITY_API_TOKEN;
-
-const apiClient = new mgmtApi.ApiClient(options);
-// Token is automatically stored in keytar for consistency
-
-// Ready to use immediately
-const guid = process.env.AGILITY_GUID;
-const locale = 'en-us';
-
-const contentItem = await apiClient.contentMethods.getContentItem(22, guid, locale);
-console.log('Content retrieved:', contentItem.fields.title);
-```
-
-### Using setToken Method
-
-```typescript
-import * as mgmtApi from '@agility/management-sdk';
-
-// Initialize without token
-const apiClient = new mgmtApi.ApiClient();
-
-// Set token programmatically
-await apiClient.setToken(process.env.AGILITY_API_TOKEN);
-
-// Ready to use
-const content = await apiClient.contentMethods.getContentList(guid, locale);
-```
-
----
-
-## Environment Configuration
-
-### Environment Variables
-
-Set up your environment variables for secure token management:
-
-```bash
-# .env file
-AGILITY_API_TOKEN=your_access_token_here
-AGILITY_GUID=your_website_guid
-AGILITY_LOCALE=en-us
-AGILITY_REGION=us  # Optional: us, ca, eu, aus, dev
-```
-
-### Loading Configuration
-
-```typescript
-import * as mgmtApi from '@agility/management-sdk';
-import dotenv from 'dotenv';
-
-// Load environment variables
-dotenv.config();
-
-// Validate required environment variables
-const requiredEnvVars = ['AGILITY_API_TOKEN', 'AGILITY_GUID'];
-for (const envVar of requiredEnvVars) {
-    if (!process.env[envVar]) {
-        throw new Error(`Missing required environment variable: ${envVar}`);
-    }
-}
-
-// Initialize client with environment configuration
-const options = new mgmtApi.Options();
-options.token = process.env.AGILITY_API_TOKEN;
-
-const apiClient = new mgmtApi.ApiClient(options);
-
-// Global configuration
-const config = {
-    guid: process.env.AGILITY_GUID!,
-    locale: process.env.AGILITY_LOCALE || 'en-us',
-    region: process.env.AGILITY_REGION || 'us'
-};
-
-export { apiClient, config };
-```
-
----
-
-## CI/CD Pipeline Examples
-
-### GitHub Actions
-
-```yaml
-# .github/workflows/content-deploy.yml
-name: Deploy Content
-
-on:
-  push:
-    branches: [main]
-  workflow_dispatch:
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    
-    steps:
-    - uses: actions/checkout@v3
-    
-    - name: Setup Node.js
-      uses: actions/setup-node@v3
-      with:
-        node-version: '18'
-    
-    - name: Install dependencies
-      run: npm ci
-    
-    - name: Deploy Content
-      env:
-        AGILITY_API_TOKEN: ${{ secrets.AGILITY_API_TOKEN }}
-        AGILITY_GUID: ${{ secrets.AGILITY_GUID }}
-        AGILITY_LOCALE: 'en-us'
-      run: node deploy-content.js
-```
-
-```javascript
-// deploy-content.js
-const mgmtApi = require('@agility/management-sdk');
-
-async function deployContent() {
-    // Initialize with token from environment
-    const options = new mgmtApi.Options();
-    options.token = process.env.AGILITY_API_TOKEN;
-    
-    const apiClient = new mgmtApi.ApiClient(options);
-    
-    const guid = process.env.AGILITY_GUID;
-    const locale = process.env.AGILITY_LOCALE;
-    
-    try {
-        // Deploy content items
-        const contentItems = [
-            {
-                properties: {
-                    referenceName: 'deployment-notice',
-                    definitionName: 'Announcement',
-                    state: 2
-                },
-                fields: {
-                    title: `Deployment ${new Date().toISOString()}`,
-                    content: 'Application deployed successfully',
-                    publishDate: new Date().toISOString()
-                }
-            }
-        ];
-        
-        for (const item of contentItems) {
-            const contentId = await apiClient.contentMethods.saveContentItem(
-                item, 
-                guid, 
-                locale
-            );
-            console.log(`✅ Content created: ${contentId}`);
-        }
-        
-        console.log('🚀 Content deployment completed successfully');
-        
-    } catch (error) {
-        console.error('❌ Deployment failed:', error.message);
-        process.exit(1);
-    }
-}
-
-deployContent();
-```
-
-### GitLab CI
-
-```yaml
-# .gitlab-ci.yml
-stages:
-  - deploy
-
-deploy_content:
-  stage: deploy
-  image: node:18
-  script:
-    - npm ci
-    - node deploy-content.js
-  variables:
-    AGILITY_GUID: $AGILITY_GUID
-    AGILITY_LOCALE: "en-us"
-  environment: production
-  only:
-    - main
-```
-
-### Jenkins Pipeline
-
-```groovy
-pipeline {
-    agent any
-    
-    environment {
-        AGILITY_API_TOKEN = credentials('agility-api-token')
-        AGILITY_GUID = credentials('agility-guid')
-        AGILITY_LOCALE = 'en-us'
-    }
-    
-    stages {
-        stage('Deploy Content') {
-            steps {
-                sh 'npm ci'
-                sh 'node deploy-content.js'
-            }
-        }
-    }
-}
-```
-
----
-
-## Serverless Functions
-
-### AWS Lambda
-
-```typescript
-import * as mgmtApi from '@agility/management-sdk';
-
-// Initialize outside handler for connection reuse
-const options = new mgmtApi.Options();
-options.token = process.env.AGILITY_API_TOKEN;
-const apiClient = new mgmtApi.ApiClient(options);
-
-const config = {
-    guid: process.env.AGILITY_GUID!,
-    locale: process.env.AGILITY_LOCALE || 'en-us'
-};
-
-export const handler = async (event: any, context: any) => {
-    try {
-        // Process event data
-        const { title, content, category } = JSON.parse(event.body);
-        
-        // Create content item
-        const contentItem = {
-            properties: {
-                referenceName: 'api-content',
-                definitionName: 'Article',
-                state: 2
-            },
-            fields: {
-                title: title,
-                content: content,
-                category: category,
-                publishDate: new Date().toISOString()
-            }
-        };
-        
-        const contentId = await apiClient.contentMethods.saveContentItem(
-            contentItem,
-            config.guid,
-            config.locale
-        );
-        
-        return {
-            statusCode: 200,
-            body: JSON.stringify({
-                success: true,
-                contentId: contentId,
-                message: 'Content created successfully'
-            })
-        };
-        
-    } catch (error) {
-        console.error('Lambda error:', error);
-        
-        return {
-            statusCode: 500,
-            body: JSON.stringify({
-                success: false,
-                error: error.message
-            })
-        };
-    }
-};
-```
-
-### Vercel Functions
-
-```typescript
-// api/create-content.ts
-import type { VercelRequest, VercelResponse } from '@vercel/node';
-import * as mgmtApi from '@agility/management-sdk';
-
-export default async function handler(req: VercelRequest, res: VercelResponse) {
-    if (req.method !== 'POST') {
-        return res.status(405).json({ error: 'Method not allowed' });
-    }
-    
-    try {
-        // Initialize API client
-        const options = new mgmtApi.Options();
-        options.token = process.env.AGILITY_API_TOKEN;
-        const apiClient = new mgmtApi.ApiClient(options);
-        
-        // Process request
-        const { title, content } = req.body;
-        
-        const contentItem = {
-            properties: {
-                referenceName: 'vercel-content',
-                definitionName: 'BlogPost',
-                state: 2
-            },
-            fields: {
-                title: title,
-                content: content,
-                publishDate: new Date().toISOString()
-            }
-        };
-        
-        const contentId = await apiClient.contentMethods.saveContentItem(
-            contentItem,
-            process.env.AGILITY_GUID!,
-            'en-us'
-        );
-        
-        res.status(200).json({
-            success: true,
-            contentId: contentId
-        });
-        
-    } catch (error) {
-        console.error('Vercel function error:', error);
-        res.status(500).json({
-            success: false,
-            error: error.message
-        });
-    }
-}
-```
-
----
-
-## Token Management
-
-### Token Validation
-
-```typescript
-import * as mgmtApi from '@agility/management-sdk';
-
-async function validateToken(token: string): Promise<boolean> {
-    try {
-        const options = new mgmtApi.Options();
-        options.token = token;
-        const apiClient = new mgmtApi.ApiClient(options);
-        
-        // Test token by making a simple API call
-        const locales = await apiClient.instanceMethods.getLocales(
-            process.env.AGILITY_GUID!
-        );
-        
-        return locales.length > 0;
-        
-    } catch (error) {
-        console.error('Token validation failed:', error.message);
-        return false;
-    }
-}
-
-// Usage in CI/CD
-if (!(await validateToken(process.env.AGILITY_API_TOKEN!))) {
-    console.error('❌ Invalid API token');
-    process.exit(1);
-}
-```
-
-### Token Rotation
-
-```typescript
-// token-rotation.js
-const mgmtApi = require('@agility/management-sdk');
-
-class TokenRotationService {
-    constructor() {
-        this.currentToken = process.env.AGILITY_API_TOKEN;
-        this.backupToken = process.env.AGILITY_API_TOKEN_BACKUP;
-    }
-    
-    async getWorkingToken() {
-        // Try current token first
-        if (await this.validateToken(this.currentToken)) {
-            return this.currentToken;
-        }
-        
-        // Fallback to backup token
-        if (await this.validateToken(this.backupToken)) {
-            console.warn('⚠️  Using backup token - main token may be expired');
-            return this.backupToken;
-        }
-        
-        throw new Error('No valid tokens available');
-    }
-    
-    async validateToken(token) {
-        try {
-            const options = new mgmtApi.Options();
-            options.token = token;
-            const apiClient = new mgmtApi.ApiClient(options);
-            
-            await apiClient.instanceMethods.getLocales(process.env.AGILITY_GUID);
-            return true;
-        } catch {
-            return false;
-        }
-    }
-}
-
-module.exports = TokenRotationService;
-```
-
----
-
-## Security Best Practices
-
-### Environment Variable Security
-
-```typescript
-// security-config.ts
-export class SecurityConfig {
-    private static validateToken(token: string): boolean {
-        // Basic token format validation
-        if (!token || typeof token !== 'string') {
-            return false;
-        }
-        
-        // Check minimum length
-        if (token.length < 20) {
-            return false;
-        }
-        
-        // Check for placeholder values
-        const placeholders = ['your_token', 'replace_me', 'token_here'];
-        return !placeholders.some(placeholder => 
-            token.toLowerCase().includes(placeholder)
-        );
-    }
-    
-    static getSecureToken(): string {
-        const token = process.env.AGILITY_API_TOKEN;
-        
-        if (!token) {
-            throw new Error('AGILITY_API_TOKEN environment variable is required');
-        }
-        
-        if (!this.validateToken(token)) {
-            throw new Error('Invalid token format detected');
-        }
-        
-        return token;
-    }
-    
-    static getSecureConfig() {
-        return {
-            token: this.getSecureToken(),
-            guid: process.env.AGILITY_GUID || (() => {
-                throw new Error('AGILITY_GUID environment variable is required');
-            })(),
-            locale: process.env.AGILITY_LOCALE || 'en-us'
-        };
-    }
-}
-```
-
-### Error Handling
-
-```typescript
-// error-handling.ts
-import * as mgmtApi from '@agility/management-sdk';
-
-export class CICDErrorHandler {
-    static async executeWithRetry<T>(
-        operation: () => Promise<T>,
-        maxRetries: number = 3,
-        delay: number = 1000
-    ): Promise<T> {
-        for (let attempt = 1; attempt <= maxRetries; attempt++) {
-            try {
-                return await operation();
-            } catch (error) {
-                console.error(`Attempt ${attempt} failed:`, error.message);
-                
-                if (attempt === maxRetries) {
-                    throw error;
-                }
-                
-                // Exponential backoff
-                const waitTime = delay * Math.pow(2, attempt - 1);
-                console.log(`⏳ Retrying in ${waitTime}ms...`);
-                await new Promise(resolve => setTimeout(resolve, waitTime));
-            }
-        }
-        
-        throw new Error('All retry attempts failed');
-    }
-    
-    static handleCICDError(error: any, context: string): never {
-        console.error(`❌ CICD Error in ${context}:`, error.message);
-        
-        // Log additional context for debugging
-        if (error.response) {
-            console.error('Response status:', error.response.status);
-            console.error('Response data:', error.response.data);
-        }
-        
-        // Exit with error code for CI/CD pipeline
-        process.exit(1);
-    }
-}
-
-// Usage example
-try {
-    const result = await CICDErrorHandler.executeWithRetry(async () => {
-        return await apiClient.contentMethods.saveContentItem(contentData, guid, locale);
-    });
-    
-    console.log('✅ Content saved successfully:', result);
-} catch (error) {
-    CICDErrorHandler.handleCICDError(error, 'content creation');
-}
-```
-
-### Logging and Monitoring
-
-```typescript
-// cicd-logger.ts
-export class CICDLogger {
-    private static logLevel = process.env.LOG_LEVEL || 'INFO';
-    
-    static info(message: string, data?: any) {
-        const timestamp = new Date().toISOString();
-        console.log(`[${timestamp}] INFO: ${message}`, data || '');
-    }
-    
-    static error(message: string, error?: any) {
-        const timestamp = new Date().toISOString();
-        console.error(`[${timestamp}] ERROR: ${message}`, error || '');
-    }
-    
-    static logOperation(operation: string, guid: string, locale: string) {
-        this.info(`Starting operation: ${operation}`, { guid, locale });
-    }
-    
-    static logSuccess(operation: string, result: any) {
-        this.info(`Operation completed: ${operation}`, { result });
-    }
-    
-    static logFailure(operation: string, error: any) {
-        this.error(`Operation failed: ${operation}`, error);
-    }
-}
-```
-
----
-
-## Navigation
-- [← Back to Main Documentation](../README.md)
-- [Authentication & Setup](./auth.md)
-- [AssetMethods](./asset-methods.md)
-- [BatchMethods](./batch-methods.md)
-- [ContainerMethods](./container-methods.md)
-- [ContentMethods](./content-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)
+# CI/CD & Automated Environments
+
+This guide covers using the Agility CMS Management SDK in automated environments such as CI/CD pipelines, serverless functions, and other programmatic scenarios where the OAuth flow isn't practical.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Token-Based Authentication](#token-based-authentication)
+- [Environment Configuration](#environment-configuration)
+- [CI/CD Pipeline Examples](#cicd-pipeline-examples)
+- [Serverless Functions](#serverless-functions)
+- [Token Management](#token-management)
+- [Security Best Practices](#security-best-practices)
+
+---
+
+## Overview
+
+In automated environments, the interactive OAuth flow isn't practical. Instead, you'll use **access tokens** directly. This approach is ideal for:
+
+- **CI/CD Pipelines** - Automated content deployment
+- **Serverless Functions** - Event-triggered content operations
+- **Scheduled Jobs** - Content synchronization, backups, etc.
+- **Build Processes** - Static site generation with fresh content
+- **Automated Testing** - Integration tests requiring content operations
+
+---
+
+## Token-Based Authentication
+
+### Using Options Constructor
+
+```typescript
+import * as mgmtApi from '@agility/management-sdk';
+
+// Set token via Options constructor
+const options = new mgmtApi.Options();
+options.token = process.env.AGILITY_API_TOKEN;
+
+const apiClient = new mgmtApi.ApiClient(options);
+// Token is automatically stored in keytar for consistency
+
+// Ready to use immediately
+const guid = process.env.AGILITY_GUID;
+const locale = 'en-us';
+
+const contentItem = await apiClient.contentMethods.getContentItem(22, guid, locale);
+console.log('Content retrieved:', contentItem.fields.title);
+```
+
+### Using setToken Method
+
+```typescript
+import * as mgmtApi from '@agility/management-sdk';
+
+// Initialize without token
+const apiClient = new mgmtApi.ApiClient();
+
+// Set token programmatically
+await apiClient.setToken(process.env.AGILITY_API_TOKEN);
+
+// Ready to use
+const content = await apiClient.contentMethods.getContentList(guid, locale);
+```
+
+---
+
+## Environment Configuration
+
+### Environment Variables
+
+Set up your environment variables for secure token management:
+
+```bash
+# .env file
+AGILITY_API_TOKEN=your_access_token_here
+AGILITY_GUID=your_website_guid
+AGILITY_LOCALE=en-us
+AGILITY_REGION=us  # Optional: us, ca, eu, aus, dev
+```
+
+### Loading Configuration
+
+```typescript
+import * as mgmtApi from '@agility/management-sdk';
+import dotenv from 'dotenv';
+
+// Load environment variables
+dotenv.config();
+
+// Validate required environment variables
+const requiredEnvVars = ['AGILITY_API_TOKEN', 'AGILITY_GUID'];
+for (const envVar of requiredEnvVars) {
+    if (!process.env[envVar]) {
+        throw new Error(`Missing required environment variable: ${envVar}`);
+    }
+}
+
+// Initialize client with environment configuration
+const options = new mgmtApi.Options();
+options.token = process.env.AGILITY_API_TOKEN;
+
+const apiClient = new mgmtApi.ApiClient(options);
+
+// Global configuration
+const config = {
+    guid: process.env.AGILITY_GUID!,
+    locale: process.env.AGILITY_LOCALE || 'en-us',
+    region: process.env.AGILITY_REGION || 'us'
+};
+
+export { apiClient, config };
+```
+
+---
+
+## CI/CD Pipeline Examples
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/content-deploy.yml
+name: Deploy Content
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v3
+    
+    - name: Setup Node.js
+      uses: actions/setup-node@v3
+      with:
+        node-version: '18'
+    
+    - name: Install dependencies
+      run: npm ci
+    
+    - name: Deploy Content
+      env:
+        AGILITY_API_TOKEN: ${{ secrets.AGILITY_API_TOKEN }}
+        AGILITY_GUID: ${{ secrets.AGILITY_GUID }}
+        AGILITY_LOCALE: 'en-us'
+      run: node deploy-content.js
+```
+
+```javascript
+// deploy-content.js
+const mgmtApi = require('@agility/management-sdk');
+
+async function deployContent() {
+    // Initialize with token from environment
+    const options = new mgmtApi.Options();
+    options.token = process.env.AGILITY_API_TOKEN;
+    
+    const apiClient = new mgmtApi.ApiClient(options);
+    
+    const guid = process.env.AGILITY_GUID;
+    const locale = process.env.AGILITY_LOCALE;
+    
+    try {
+        // Deploy content items
+        const contentItems = [
+            {
+                properties: {
+                    referenceName: 'deployment-notice',
+                    definitionName: 'Announcement',
+                    state: 2
+                },
+                fields: {
+                    title: `Deployment ${new Date().toISOString()}`,
+                    content: 'Application deployed successfully',
+                    publishDate: new Date().toISOString()
+                }
+            }
+        ];
+        
+        for (const item of contentItems) {
+            const contentId = await apiClient.contentMethods.saveContentItem(
+                item, 
+                guid, 
+                locale
+            );
+            console.log(`✅ Content created: ${contentId}`);
+        }
+        
+        console.log('🚀 Content deployment completed successfully');
+        
+    } catch (error) {
+        console.error('❌ Deployment failed:', error.message);
+        process.exit(1);
+    }
+}
+
+deployContent();
+```
+
+### GitLab CI
+
+```yaml
+# .gitlab-ci.yml
+stages:
+  - deploy
+
+deploy_content:
+  stage: deploy
+  image: node:18
+  script:
+    - npm ci
+    - node deploy-content.js
+  variables:
+    AGILITY_GUID: $AGILITY_GUID
+    AGILITY_LOCALE: "en-us"
+  environment: production
+  only:
+    - main
+```
+
+### Jenkins Pipeline
+
+```groovy
+pipeline {
+    agent any
+    
+    environment {
+        AGILITY_API_TOKEN = credentials('agility-api-token')
+        AGILITY_GUID = credentials('agility-guid')
+        AGILITY_LOCALE = 'en-us'
+    }
+    
+    stages {
+        stage('Deploy Content') {
+            steps {
+                sh 'npm ci'
+                sh 'node deploy-content.js'
+            }
+        }
+    }
+}
+```
+
+---
+
+## Serverless Functions
+
+### AWS Lambda
+
+```typescript
+import * as mgmtApi from '@agility/management-sdk';
+
+// Initialize outside handler for connection reuse
+const options = new mgmtApi.Options();
+options.token = process.env.AGILITY_API_TOKEN;
+const apiClient = new mgmtApi.ApiClient(options);
+
+const config = {
+    guid: process.env.AGILITY_GUID!,
+    locale: process.env.AGILITY_LOCALE || 'en-us'
+};
+
+export const handler = async (event: any, context: any) => {
+    try {
+        // Process event data
+        const { title, content, category } = JSON.parse(event.body);
+        
+        // Create content item
+        const contentItem = {
+            properties: {
+                referenceName: 'api-content',
+                definitionName: 'Article',
+                state: 2
+            },
+            fields: {
+                title: title,
+                content: content,
+                category: category,
+                publishDate: new Date().toISOString()
+            }
+        };
+        
+        const contentId = await apiClient.contentMethods.saveContentItem(
+            contentItem,
+            config.guid,
+            config.locale
+        );
+        
+        return {
+            statusCode: 200,
+            body: JSON.stringify({
+                success: true,
+                contentId: contentId,
+                message: 'Content created successfully'
+            })
+        };
+        
+    } catch (error) {
+        console.error('Lambda error:', error);
+        
+        return {
+            statusCode: 500,
+            body: JSON.stringify({
+                success: false,
+                error: error.message
+            })
+        };
+    }
+};
+```
+
+### Vercel Functions
+
+```typescript
+// api/create-content.ts
+import type { VercelRequest, VercelResponse } from '@vercel/node';
+import * as mgmtApi from '@agility/management-sdk';
+
+export default async function handler(req: VercelRequest, res: VercelResponse) {
+    if (req.method !== 'POST') {
+        return res.status(405).json({ error: 'Method not allowed' });
+    }
+    
+    try {
+        // Initialize API client
+        const options = new mgmtApi.Options();
+        options.token = process.env.AGILITY_API_TOKEN;
+        const apiClient = new mgmtApi.ApiClient(options);
+        
+        // Process request
+        const { title, content } = req.body;
+        
+        const contentItem = {
+            properties: {
+                referenceName: 'vercel-content',
+                definitionName: 'BlogPost',
+                state: 2
+            },
+            fields: {
+                title: title,
+                content: content,
+                publishDate: new Date().toISOString()
+            }
+        };
+        
+        const contentId = await apiClient.contentMethods.saveContentItem(
+            contentItem,
+            process.env.AGILITY_GUID!,
+            'en-us'
+        );
+        
+        res.status(200).json({
+            success: true,
+            contentId: contentId
+        });
+        
+    } catch (error) {
+        console.error('Vercel function error:', error);
+        res.status(500).json({
+            success: false,
+            error: error.message
+        });
+    }
+}
+```
+
+---
+
+## Token Management
+
+### Token Validation
+
+```typescript
+import * as mgmtApi from '@agility/management-sdk';
+
+async function validateToken(token: string): Promise<boolean> {
+    try {
+        const options = new mgmtApi.Options();
+        options.token = token;
+        const apiClient = new mgmtApi.ApiClient(options);
+        
+        // Test token by making a simple API call
+        const locales = await apiClient.instanceMethods.getLocales(
+            process.env.AGILITY_GUID!
+        );
+        
+        return locales.length > 0;
+        
+    } catch (error) {
+        console.error('Token validation failed:', error.message);
+        return false;
+    }
+}
+
+// Usage in CI/CD
+if (!(await validateToken(process.env.AGILITY_API_TOKEN!))) {
+    console.error('❌ Invalid API token');
+    process.exit(1);
+}
+```
+
+### Token Rotation
+
+```typescript
+// token-rotation.js
+const mgmtApi = require('@agility/management-sdk');
+
+class TokenRotationService {
+    constructor() {
+        this.currentToken = process.env.AGILITY_API_TOKEN;
+        this.backupToken = process.env.AGILITY_API_TOKEN_BACKUP;
+    }
+    
+    async getWorkingToken() {
+        // Try current token first
+        if (await this.validateToken(this.currentToken)) {
+            return this.currentToken;
+        }
+        
+        // Fallback to backup token
+        if (await this.validateToken(this.backupToken)) {
+            console.warn('⚠️  Using backup token - main token may be expired');
+            return this.backupToken;
+        }
+        
+        throw new Error('No valid tokens available');
+    }
+    
+    async validateToken(token) {
+        try {
+            const options = new mgmtApi.Options();
+            options.token = token;
+            const apiClient = new mgmtApi.ApiClient(options);
+            
+            await apiClient.instanceMethods.getLocales(process.env.AGILITY_GUID);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+}
+
+module.exports = TokenRotationService;
+```
+
+---
+
+## Security Best Practices
+
+### Environment Variable Security
+
+```typescript
+// security-config.ts
+export class SecurityConfig {
+    private static validateToken(token: string): boolean {
+        // Basic token format validation
+        if (!token || typeof token !== 'string') {
+            return false;
+        }
+        
+        // Check minimum length
+        if (token.length < 20) {
+            return false;
+        }
+        
+        // Check for placeholder values
+        const placeholders = ['your_token', 'replace_me', 'token_here'];
+        return !placeholders.some(placeholder => 
+            token.toLowerCase().includes(placeholder)
+        );
+    }
+    
+    static getSecureToken(): string {
+        const token = process.env.AGILITY_API_TOKEN;
+        
+        if (!token) {
+            throw new Error('AGILITY_API_TOKEN environment variable is required');
+        }
+        
+        if (!this.validateToken(token)) {
+            throw new Error('Invalid token format detected');
+        }
+        
+        return token;
+    }
+    
+    static getSecureConfig() {
+        return {
+            token: this.getSecureToken(),
+            guid: process.env.AGILITY_GUID || (() => {
+                throw new Error('AGILITY_GUID environment variable is required');
+            })(),
+            locale: process.env.AGILITY_LOCALE || 'en-us'
+        };
+    }
+}
+```
+
+### Error Handling
+
+```typescript
+// error-handling.ts
+import * as mgmtApi from '@agility/management-sdk';
+
+export class CICDErrorHandler {
+    static async executeWithRetry<T>(
+        operation: () => Promise<T>,
+        maxRetries: number = 3,
+        delay: number = 1000
+    ): Promise<T> {
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            try {
+                return await operation();
+            } catch (error) {
+                console.error(`Attempt ${attempt} failed:`, error.message);
+                
+                if (attempt === maxRetries) {
+                    throw error;
+                }
+                
+                // Exponential backoff
+                const waitTime = delay * Math.pow(2, attempt - 1);
+                console.log(`⏳ Retrying in ${waitTime}ms...`);
+                await new Promise(resolve => setTimeout(resolve, waitTime));
+            }
+        }
+        
+        throw new Error('All retry attempts failed');
+    }
+    
+    static handleCICDError(error: any, context: string): never {
+        console.error(`❌ CICD Error in ${context}:`, error.message);
+        
+        // Log additional context for debugging
+        if (error.response) {
+            console.error('Response status:', error.response.status);
+            console.error('Response data:', error.response.data);
+        }
+        
+        // Exit with error code for CI/CD pipeline
+        process.exit(1);
+    }
+}
+
+// Usage example
+try {
+    const result = await CICDErrorHandler.executeWithRetry(async () => {
+        return await apiClient.contentMethods.saveContentItem(contentData, guid, locale);
+    });
+    
+    console.log('✅ Content saved successfully:', result);
+} catch (error) {
+    CICDErrorHandler.handleCICDError(error, 'content creation');
+}
+```
+
+### Logging and Monitoring
+
+```typescript
+// cicd-logger.ts
+export class CICDLogger {
+    private static logLevel = process.env.LOG_LEVEL || 'INFO';
+    
+    static info(message: string, data?: any) {
+        const timestamp = new Date().toISOString();
+        console.log(`[${timestamp}] INFO: ${message}`, data || '');
+    }
+    
+    static error(message: string, error?: any) {
+        const timestamp = new Date().toISOString();
+        console.error(`[${timestamp}] ERROR: ${message}`, error || '');
+    }
+    
+    static logOperation(operation: string, guid: string, locale: string) {
+        this.info(`Starting operation: ${operation}`, { guid, locale });
+    }
+    
+    static logSuccess(operation: string, result: any) {
+        this.info(`Operation completed: ${operation}`, { result });
+    }
+    
+    static logFailure(operation: string, error: any) {
+        this.error(`Operation failed: ${operation}`, error);
+    }
+}
+```
+
+---
+
+## Navigation
+- [← Back to Main Documentation](../README.md)
+- [Authentication & Setup](./auth.md)
+- [AssetMethods](./asset-methods.md)
+- [BatchMethods](./batch-methods.md)
+- [ContainerMethods](./container-methods.md)
+- [ContentMethods](./content-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)