@simpleapps-com/augur-api 0.2.9 → 0.2.10

package/README.md

@@ -404,6 +404,218 @@ const auth = await api.joomla.users.verifyPassword({
 });
 ```
 
+## Power Features (Hidden Gems)
+
+**Unlock the full potential** of the Augur API with these advanced features that dramatically improve your development experience:
+
+### Data Methods Pattern ⭐ NEW!
+
+Every endpoint provides both complete responses AND streamlined data-only access:
+
+```typescript
+// Standard pattern - full response with metadata
+const response = await api.joomla.users.list({ limit: 10 });
+console.log(`Found ${response.data.length} users`);
+console.log(`Total available: ${response.totalResults}`);
+console.log(`Response status: ${response.status}`);
+
+// Data-only pattern - direct access to the data array ⚡
+const users = await api.joomla.users.listData({ limit: 10 });
+console.log(users); // Direct User[] array, no wrapper
+
+// Single item data access
+const user = await api.joomla.users.getData('123');
+console.log(user); // Direct User object, no response wrapper
+
+// Works across ALL services
+const products = await api.opensearch.itemSearch.searchData({
+  q: 'electrical wire',
+  searchType: 'query',
+  size: 20
+}); // Direct item array
+
+const pricing = await api.pricing.getPriceData({
+  customerId: 12345,
+  itemId: 'WIRE-123',
+  quantity: 10
+}); // Direct pricing object
+```
+
+**Benefits:**
+- **50% less code** for data extraction
+- **Cleaner business logic** without response unwrapping
+- **Same caching and validation** as standard methods
+- **Consistent pattern** across all 13 microservices
+
+### Advanced Discovery Filtering
+
+Go beyond basic search with sophisticated filtering options:
+
+```typescript
+// Precision search with advanced filtering
+const endpoints = await api.findEndpoint('user management', {
+  // Relevance threshold (0.0 to 1.0)
+  minScore: 0.7,          // Only highly relevant matches
+  
+  // Limit results
+  maxResults: 5,          // Top 5 matches only
+  
+  // Service-specific filtering
+  service: 'joomla',      // Only Joomla service endpoints
+  
+  // Business domain filtering
+  domain: 'user-management', // Only user management domain
+  
+  // Operation type filtering
+  readOnly: true,         // Only read operations (GET requests)
+  writeOnly: false,       // Exclude write operations
+  
+  // Response format preferences
+  includeMetadata: true,  // Include match reasoning and scores
+  sortBy: 'relevance'     // Sort by relevance score (default: 'relevance' | 'alphabetical')
+});
+
+// Rich result information
+endpoints.forEach(result => {
+  console.log(`🔍 ${result.endpoint.fullPath}`);
+  console.log(`   Score: ${result.score} | Reason: ${result.matchReason}`);
+  console.log(`   Domain: ${result.endpoint.domain} | Service: ${result.endpoint.service}`);
+  console.log(`   Method: ${result.endpoint.method} | Read-only: ${result.endpoint.readOnly}`);
+});
+
+// Cross-service workflow discovery
+const ecommerceFlow = await api.findEndpoint('complete customer order', {
+  domain: ['commerce', 'pricing', 'inventory'], // Multiple domains
+  includeWorkflow: true,                         // Include workflow relationships
+  minScore: 0.5
+});
+
+// Results include cross-service relationships
+ecommerceFlow.forEach(result => {
+  console.log(`${result.endpoint.fullPath} → Related: ${result.relatedEndpoints?.join(', ')}`);
+});
+```
+
+### Debug Utilities and Troubleshooting
+
+Built-in debugging tools help you understand what's happening under the hood:
+
+```typescript
+// Create detailed debug information for any request
+const debugInfo = api.joomla.users.createDebugInfo(
+  { limit: 10, offset: 0 },  // Your parameters
+  { edgeCache: 2 }           // Request config
+);
+
+console.log('🔧 Debug Information:');
+console.log('Expected Parameters:', debugInfo.expectedParams);
+console.log('Provided Parameters:', debugInfo.providedParams);
+console.log('Validation Results:', debugInfo.validation);
+console.log('Cache Strategy:', debugInfo.cacheInfo);
+console.log('Generated URL:', debugInfo.finalURL);
+
+// Validate parameters before making requests
+const validation = api.pricing.validatePriceParams({
+  customerId: 12345,
+  itemId: 'INVALID',  // This might fail validation
+  quantity: -5        // Negative quantity should fail
+});
+
+if (!validation.isValid) {
+  console.log('❌ Parameter Validation Failed:');
+  validation.errors.forEach(error => {
+    console.log(`   Field: ${error.field} | Issue: ${error.message}`);
+    console.log(`   Expected: ${error.expected} | Received: ${error.received}`);
+  });
+}
+
+// Request tracing for performance analysis
+api.enableRequestTracing(true);
+
+const users = await api.joomla.users.list({ limit: 10 });
+
+// Get trace information
+const trace = api.getLastRequestTrace();
+console.log('🚀 Performance Trace:');
+console.log(`   Total Time: ${trace.totalTime}ms`);
+console.log(`   Network Time: ${trace.networkTime}ms`);
+console.log(`   Validation Time: ${trace.validationTime}ms`);
+console.log(`   Cache Status: ${trace.cacheStatus}`);
+console.log(`   Request ID: ${trace.requestId}`);
+```
+
+### Automatic Parameter Extraction
+
+The system intelligently maps URL templates to method parameters:
+
+```typescript
+// URL template: /bin-transfer/{binTransferHdrUid}
+// Automatically creates: (id) => { binTransferHdrUid: id }
+const binTransfer = await api.nexus.binTransfers.get(12345);
+// Internally maps: 12345 → { binTransferHdrUid: 12345 }
+
+// URL template: /customer/{customerId}/orders/{orderId}
+// Automatically creates: (customerId, orderId) => { customerId, orderId }
+const order = await api.customers.customer.orders.get(123, 456);
+// Internally maps: (123, 456) → { customerId: 123, orderId: 456 }
+
+// Complex URL templates with multiple parameters
+// URL template: /pricing/job/{jobPriceHdrUid}/lines/{jobPriceLineUid}
+const jobPriceLine = await api.pricing.jobPriceLines.get(123, 456);
+// Internally maps: (123, 456) → { jobPriceHdrUid: 123, jobPriceLineUid: 456 }
+
+// See the mapping for any endpoint
+const mapping = api.nexus.binTransfers.getParameterMapping();
+console.log('URL Template:', mapping.urlTemplate);
+console.log('Parameter Map:', mapping.parameterMap);
+console.log('Required Params:', mapping.requiredParams);
+console.log('Optional Params:', mapping.optionalParams);
+
+// Validate parameter mapping before calling
+const isValid = api.nexus.binTransfers.validateParameterMapping(12345);
+if (!isValid.valid) {
+  console.log('Parameter mapping issues:', isValid.errors);
+}
+```
+
+### Smart Request Building
+
+Advanced request construction with intelligent defaults:
+
+```typescript
+// Smart parameter inference
+const smartRequest = api.commerce.cartHeaders.buildRequest({
+  userId: 123,
+  // System automatically infers common parameters:
+  // - siteId from API configuration
+  // - timestamp for cache busting
+  // - request ID for tracing
+});
+
+console.log('Generated request:', smartRequest);
+// {
+//   userId: 123,
+//   siteId: 'your-site-id',
+//   _timestamp: 1693934400000,
+//   _requestId: 'req_abc123',
+//   _cacheKey: 'cart_headers_123_your-site-id'
+// }
+
+// Request templating for repeated operations
+const userTemplate = api.joomla.users.createRequestTemplate({
+  limit: 50,
+  orderBy: 'username|ASC'
+});
+
+// Reuse template with variations
+const activeUsers = await userTemplate.execute({ q: 'active' });
+const adminUsers = await userTemplate.execute({ groupId: 1 });
+const recentUsers = await userTemplate.execute({ 
+  createdSince: '2024-01-01',
+  limit: 20  // Override template default
+});
+```
+
 ## Platform Capabilities Matrix
 
 | Capability | Impact | Technical Implementation |
@@ -2280,269 +2492,944 @@ managedAPI.updateConfig({
 
 ## Performance Optimization
 
-### Caching Strategies
+> 📋 **[Complete Performance Guide](./PERFORMANCE.md)** - Comprehensive strategies for edge caching, batch operations, pagination optimization, and performance monitoring.
+
+**Quick Performance Tips:**
 
 ```typescript
-// Cache strategy based on data volatility
-class CacheStrategy {
-  static getDuration(dataType: string, context?: Record<string, any>): number | undefined {
-    const strategies = {
-      // Static reference data - cache for 8 hours
-      reference: 8,
-      categories: 8,
-      tags: 6,
-      distributors: 8,
-      
-      // Moderate volatility - cache for 2-4 hours
-      users: context?.isLargeOrg ? 4 : 2,
-      products: 6,
-      warehouses: 4,
-      recommendations: 4,
-      
-      // High volatility - cache for 1-2 hours
-      pricing: context?.isStandardItem ? 3 : 1,
-      inventory: context?.isHighVolume ? 1 : 2,
-      cart: 1,
-      
-      // Real-time data - no caching
-      authentication: undefined,
-      validation: undefined,
-      checkout: undefined,
-    };
-    
-    return strategies[dataType as keyof typeof strategies];
-  }
-}
+// ⚡ Edge caching with Cloudflare CDN
+const categories = await api.items.categories.list({ edgeCache: 8 }); // Static data: 8 hours
+const pricing = await api.pricing.getPrice({ customerId: 123, edgeCache: 3 }); // Dynamic: 3 hours
+const inventory = await api.vmi.inventory.checkAvailability(123, { edgeCache: 1 }); // Volatile: 1 hour
 
-// Usage
-const duration = CacheStrategy.getDuration('pricing', { isStandardItem: true });
-const pricing = await api.pricing.getPrice({
-  customerId: 12345,
-  itemId: 'STANDARD-ITEM',
-  quantity: 10,
-  edgeCache: duration  // Will be 3 hours
-});
-```
-
-### Request Batching
-
-```typescript
-// Batch related requests for better performance
-async function loadDashboardData() {
-  // Execute all requests in parallel
-  const [users, products, inventory, pricing] = await Promise.allSettled([
-    api.joomla.users.list({ limit: 10, edgeCache: 2 }),
-    api.opensearch.itemSearch.search({ 
-      q: 'featured', 
-      searchType: 'query', 
-      size: 5, 
-      edgeCache: 4 
-    }),
-    api.vmi.warehouses.list({ 
-      customerId: 12345, 
-      limit: 5, 
-      edgeCache: 4 
-    }),
-    api.pricing.jobPriceHeaders.list({ 
-      limit: 5, 
-      edgeCache: 6 
-    })
-  ]);
-
-  // Handle results
-  return {
-    users: users.status === 'fulfilled' ? users.value : null,
-    products: products.status === 'fulfilled' ? products.value : null,
-    inventory: inventory.status === 'fulfilled' ? inventory.value : null,
-    pricing: pricing.status === 'fulfilled' ? pricing.value : null,
-  };
+// 🚀 Batch operations for multiple requests
+const [users, groups, content] = await Promise.allSettled([
+  api.joomla.users.list({ limit: 50, edgeCache: 2 }),
+  api.joomla.userGroups.list({ edgeCache: 8 }),
+  api.joomla.content.list({ categoryIdList: '1,2,3', edgeCache: 6 })
+]);
+
+// 📄 Smart pagination with prefetching
+class SmartPagination {
+  async loadPage(fetcher, page, pageSize = 50) {
+    // Automatic prefetching and caching
+    return this.loadWithPrefetch(fetcher, page, pageSize);
+  }
 }
 ```
 
-### Connection Pooling
+**Key Performance Features:**
+- **Edge Cache Decision Tree** - Choose optimal cache duration by data volatility
+- **Service-Specific Batching** - Parallel operations tailored to each microservice  
+- **Advanced Pagination** - Prefetching, infinite scroll, and streaming patterns
+- **Performance Analytics** - Monitor cache hit rates, response times, and optimization opportunities
+
+For complete implementation details, see [Performance Optimization Guide](./PERFORMANCE.md).
+
+## Enterprise Integration Patterns
+
+**Scale your enterprise applications** with proven patterns for multi-tenant architectures, cross-site authentication, and production deployment.
+
+### Cross-Site Authentication Architecture
+
+> 📋 **[Complete Authentication Guide](./AUTHENTICATION.md)** - Detailed implementation patterns, security considerations, and troubleshooting.
+
+**Enterprise Authentication Flow:**
 
 ```typescript
-// Configure HTTP client for optimal performance
-const api = new AugurAPI({
-  siteId: 'your-site-id',
-  bearerToken: 'your-token',
-  
-  // Optimize for high-throughput scenarios
-  timeout: 15000,  // Shorter timeout for better user experience
-  retries: 2,      // Fewer retries for faster failure detection
-  
-  onRequest: (config) => {
-    // Add keep-alive headers for connection reuse
-    config.headers['Connection'] = 'keep-alive';
-    config.headers['Keep-Alive'] = 'timeout=5, max=1000';
-    return config;
+/**
+ * 🏢 ENTERPRISE MULTI-TENANT AUTHENTICATION
+ * 
+ * Supports authenticating users across multiple tenant sites
+ * from a centralized application or admin dashboard.
+ */
+
+import { createCrossSiteAuthenticator, authenticateUserForSite } from '@simpleapps-com/augur-api';
+
+// 🎯 Option 1: Single Authentication (Recommended for most cases)
+const authResult = await authenticateUserForSite({
+  targetSiteId: 'tenant_site_alpha',
+  username: 'user@tenant.com', 
+  password: 'user_password',
+  augurInfoToken: process.env.AUGUR_ADMIN_TOKEN! // Admin token with augur_info privileges
+});
+
+if (authResult.success) {
+  // Ready-to-use API client for the tenant
+  const tenantAPI = authResult.targetSiteAPI!;
+  const userData = await tenantAPI.joomla.users.get(authResult.userId!);
+  console.log(`✅ Authenticated: ${authResult.username} on ${targetSiteId}`);
+}
+
+// 🎯 Option 2: Reusable Authenticator (For multiple sites)
+const crossSiteAuth = createCrossSiteAuthenticator(process.env.AUGUR_ADMIN_TOKEN!);
+
+const tenantResults = await Promise.allSettled([
+  crossSiteAuth('tenant_alpha', 'user@alpha.com', 'pass1'),
+  crossSiteAuth('tenant_beta', 'user@beta.com', 'pass2'),
+  crossSiteAuth('tenant_gamma', 'user@gamma.com', 'pass3')
+]);
+
+// Process results for each tenant
+tenantResults.forEach((result, index) => {
+  const tenantId = ['tenant_alpha', 'tenant_beta', 'tenant_gamma'][index];
+  if (result.status === 'fulfilled' && result.value.success) {
+    console.log(`✅ ${tenantId}: User authenticated`);
   }
 });
 ```
 
-### Memory Management
+**Authentication Flow Diagram:**
+```
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│   Your App  │───▶│ augur_info  │───▶│ Target Site │───▶│ User Token  │
+│             │    │   (Admin)   │    │   (Tenant)  │    │  (Scoped)   │
+└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
+      │                    │                    │                    │
+   Admin JWT        Verify User         Check Password        Return Scoped
+   Token            Credentials         Against Site          JWT for Site
+```
+
+### Multi-Tenant Setup Patterns
+
+**Configure your application** for enterprise multi-tenancy with these proven patterns:
 
 ```typescript
-// Efficient memory usage patterns
-class EfficientAugurUsage {
-  private api: AugurAPI;
-  private cache = new Map<string, { data: any; timestamp: number; ttl: number }>();
+/**
+ * 🏗️ MULTI-TENANT ARCHITECTURE PATTERNS
+ * 
+ * Choose the pattern that best fits your enterprise requirements:
+ * - Shared Infrastructure, Isolated Data
+ * - Complete Tenant Isolation  
+ * - Hybrid Multi-Tenant Model
+ */
 
-  constructor(config: AugurAPIConfig) {
-    this.api = new AugurAPI(config);
+// 🏢 Pattern 1: Tenant Context Manager (Recommended)
+class TenantContextManager {
+  private tenantAPIs = new Map<string, AugurAPI>();
+  private currentTenant: string | null = null;
+
+  async initializeTenant(
+    tenantId: string,
+    userCredentials: { username: string; password: string },
+    adminToken: string
+  ): Promise<boolean> {
+    try {
+      const authResult = await authenticateUserForSite({
+        targetSiteId: tenantId,
+        username: userCredentials.username,
+        password: userCredentials.password,
+        augurInfoToken: adminToken
+      });
+
+      if (authResult.success) {
+        // Store authenticated API client for tenant
+        this.tenantAPIs.set(tenantId, authResult.targetSiteAPI!);
+        this.currentTenant = tenantId;
+        
+        console.log(`✅ Tenant ${tenantId} initialized successfully`);
+        return true;
+      }
+      
+      console.error(`❌ Failed to initialize tenant ${tenantId}: ${authResult.error}`);
+      return false;
+    } catch (error) {
+      console.error(`❌ Tenant initialization error:`, error);
+      return false;
+    }
+  }
+
+  // Switch between tenants seamlessly
+  switchTenant(tenantId: string): AugurAPI | null {
+    if (this.tenantAPIs.has(tenantId)) {
+      this.currentTenant = tenantId;
+      return this.tenantAPIs.get(tenantId)!;
+    }
     
-    // Clean up expired cache entries every 5 minutes
-    setInterval(() => this.cleanupCache(), 5 * 60 * 1000);
+    console.warn(`⚠️ Tenant ${tenantId} not initialized`);
+    return null;
   }
 
-  async getCachedData<T>(
-    key: string,
-    fetcher: () => Promise<T>,
-    ttlSeconds = 300
-  ): Promise<T> {
-    const cached = this.cache.get(key);
-    const now = Date.now();
+  // Get current tenant's API client
+  getCurrentAPI(): AugurAPI | null {
+    return this.currentTenant ? this.tenantAPIs.get(this.currentTenant) || null : null;
+  }
 
-    if (cached && (now - cached.timestamp) < (cached.ttl * 1000)) {
-      return cached.data;
+  // Bulk operations across all tenants
+  async executeAcrossAllTenants<T>(
+    operation: (api: AugurAPI, tenantId: string) => Promise<T>
+  ): Promise<Array<{ tenantId: string; result: T; success: boolean; error?: string }>> {
+    const results: Array<{ tenantId: string; result: T; success: boolean; error?: string }> = [];
+    
+    for (const [tenantId, api] of this.tenantAPIs.entries()) {
+      try {
+        const result = await operation(api, tenantId);
+        results.push({ tenantId, result, success: true });
+      } catch (error) {
+        results.push({ 
+          tenantId, 
+          result: null as any, 
+          success: false, 
+          error: error instanceof Error ? error.message : 'Unknown error'
+        });
+      }
     }
+    
+    return results;
+  }
+}
 
-    const data = await fetcher();
-    this.cache.set(key, {
-      data,
-      timestamp: now,
-      ttl: ttlSeconds
+// 🏢 Pattern 2: Tenant Factory (For dynamic tenant creation)
+class TenantAPIFactory {
+  constructor(private adminToken: string) {}
+
+  async createTenantAPI(
+    tenantId: string,
+    userCredentials: { username: string; password: string }
+  ): Promise<AugurAPI | null> {
+    const authResult = await authenticateUserForSite({
+      targetSiteId: tenantId,
+      username: userCredentials.username,
+      password: userCredentials.password,
+      augurInfoToken: this.adminToken
     });
 
-    return data;
+    return authResult.success ? authResult.targetSiteAPI! : null;
   }
 
-  private cleanupCache(): void {
-    const now = Date.now();
-    for (const [key, entry] of this.cache.entries()) {
-      if ((now - entry.timestamp) >= (entry.ttl * 1000)) {
-        this.cache.delete(key);
+  // Create multiple tenant APIs in parallel
+  async createMultipleTenantAPIs(
+    tenantConfigs: Array<{
+      tenantId: string;
+      credentials: { username: string; password: string };
+    }>
+  ): Promise<Map<string, AugurAPI>> {
+    const results = await Promise.allSettled(
+      tenantConfigs.map(async ({ tenantId, credentials }) => ({
+        tenantId,
+        api: await this.createTenantAPI(tenantId, credentials)
+      }))
+    );
+
+    const tenantAPIs = new Map<string, AugurAPI>();
+    
+    results.forEach((result, index) => {
+      if (result.status === 'fulfilled' && result.value.api) {
+        tenantAPIs.set(result.value.tenantId, result.value.api);
+      } else {
+        const tenantId = tenantConfigs[index].tenantId;
+        console.error(`❌ Failed to create API for tenant: ${tenantId}`);
       }
-    }
+    });
+
+    return tenantAPIs;
   }
+}
 
-  async getUsers(useCache = true): Promise<any> {
-    if (!useCache) {
-      return this.api.joomla.users.list({ limit: 50 });
-    }
+// 🏢 Pattern 3: Multi-Tenant Dashboard Implementation
+class MultiTenantDashboard {
+  private tenantManager = new TenantContextManager();
+  private tenantFactory: TenantAPIFactory;
 
-    return this.getCachedData(
-      'users-list',
-      () => this.api.joomla.users.list({ limit: 50, edgeCache: 2 }),
-      600 // 10 minutes local cache
+  constructor(adminToken: string) {
+    this.tenantFactory = new TenantAPIFactory(adminToken);
+  }
+
+  async initializeDashboard(
+    userCredentials: { username: string; password: string },
+    tenantIds: string[]
+  ): Promise<void> {
+    console.log(`🚀 Initializing dashboard for ${tenantIds.length} tenants...`);
+    
+    // Initialize all tenants in parallel
+    const initResults = await Promise.allSettled(
+      tenantIds.map(tenantId => 
+        this.tenantManager.initializeTenant(
+          tenantId, 
+          userCredentials, 
+          process.env.AUGUR_ADMIN_TOKEN!
+        )
+      )
     );
+
+    const successCount = initResults.filter(r => 
+      r.status === 'fulfilled' && r.value === true
+    ).length;
+
+    console.log(`✅ Dashboard initialized: ${successCount}/${tenantIds.length} tenants ready`);
   }
 
-  destroy(): void {
-    this.cache.clear();
+  // Get aggregated data across all tenants
+  async getAggregatedUserData(): Promise<Record<string, any[]>> {
+    const results = await this.tenantManager.executeAcrossAllTenants(
+      async (api, tenantId) => {
+        const users = await api.joomla.users.listData({ limit: 100 });
+        return { tenantId, userCount: users.length, users };
+      }
+    );
+
+    const aggregatedData: Record<string, any[]> = {};
+    results.forEach(({ tenantId, result, success }) => {
+      if (success) {
+        aggregatedData[tenantId] = result.users;
+      }
+    });
+
+    return aggregatedData;
+  }
+
+  // Bulk operations example
+  async bulkUpdateAcrossTenants(updates: Record<string, any>): Promise<void> {
+    const results = await this.tenantManager.executeAcrossAllTenants(
+      async (api, tenantId) => {
+        // Example: Update site settings across all tenants
+        return await api.agrsite.settings.update(updates);
+      }
+    );
+
+    const successCount = results.filter(r => r.success).length;
+    console.log(`✅ Bulk update completed: ${successCount}/${results.length} tenants updated`);
   }
 }
+
+// 🎮 USAGE EXAMPLES
+
+// Initialize multi-tenant dashboard
+const dashboard = new MultiTenantDashboard(process.env.AUGUR_ADMIN_TOKEN!);
+
+await dashboard.initializeDashboard(
+  { username: 'admin@company.com', password: 'admin_password' },
+  ['tenant_alpha', 'tenant_beta', 'tenant_gamma']
+);
+
+// Get aggregated data from all tenants
+const userData = await dashboard.getAggregatedUserData();
+console.log('User data across all tenants:', userData);
+
+// Execute bulk operations
+await dashboard.bulkUpdateAcrossTenants({
+  maintenanceMode: false,
+  themeColor: '#2563eb'
+});
 ```
 
-### Performance Monitoring
+### Security Configuration Best Practices
+
+**Secure your enterprise deployment** with comprehensive security measures:
 
 ```typescript
-// Monitor API performance
-class PerformanceMonitor {
-  private metrics = {
-    requests: 0,
-    errors: 0,
-    totalTime: 0,
-    cacheHits: 0,
-    cacheMisses: 0
+/**
+ * 🔒 ENTERPRISE SECURITY CONFIGURATION
+ * 
+ * Implement defense-in-depth security practices for production
+ * environments with comprehensive monitoring and access control.
+ */
+
+// 🛡️ Secure Configuration Manager
+class SecureConfigManager {
+  private static readonly SECURITY_CONFIG = {
+    // Token rotation intervals (in milliseconds)
+    TOKEN_ROTATION_INTERVAL: 4 * 60 * 60 * 1000, // 4 hours
+    ADMIN_TOKEN_ROTATION_INTERVAL: 2 * 60 * 60 * 1000, // 2 hours
+    
+    // Rate limiting
+    MAX_REQUESTS_PER_MINUTE: 100,
+    MAX_CROSS_SITE_AUTH_PER_HOUR: 50,
+    
+    // Session management
+    SESSION_TIMEOUT: 30 * 60 * 1000, // 30 minutes
+    MAX_CONCURRENT_SESSIONS: 5,
+    
+    // Network security
+    ALLOWED_ORIGINS: process.env.ALLOWED_ORIGINS?.split(',') || [],
+    REQUIRE_HTTPS: process.env.NODE_ENV === 'production',
   };
 
-  createMonitoredAPI(config: AugurAPIConfig): AugurAPI {
+  // 🔑 Secure token management
+  static createSecureAPIClient(config: {
+    siteId: string;
+    tokenProvider: () => Promise<string>;
+    onTokenRefresh?: (newToken: string) => void;
+    securityLogger?: (event: string, details: any) => void;
+  }): AugurAPI {
+    
+    let currentToken: string | null = null;
+    let lastTokenRefresh = 0;
+
     return new AugurAPI({
-      ...config,
+      siteId: config.siteId,
       
-      onRequest: (config) => {
-        // Track request start time
-        (config as any).startTime = Date.now();
-        this.metrics.requests++;
-        return config;
+      // Dynamic token provider with automatic rotation
+      get bearerToken() {
+        return currentToken;
       },
-      
-      onResponse: (response) => {
-        // Calculate request duration
-        const startTime = (response.config as any)?.startTime;
-        if (startTime) {
-          const duration = Date.now() - startTime;
-          this.metrics.totalTime += duration;
-        }
 
-        // Track cache performance
-        const cacheStatus = response.headers?.['cf-cache-status'];
-        if (cacheStatus === 'HIT') {
-          this.metrics.cacheHits++;
-        } else if (cacheStatus === 'MISS') {
-          this.metrics.cacheMisses++;
+      // Request interceptor for security
+      onRequest: async (requestConfig) => {
+        const now = Date.now();
+        
+        // Auto-refresh token if needed
+        if (!currentToken || (now - lastTokenRefresh) > SecureConfigManager.SECURITY_CONFIG.TOKEN_ROTATION_INTERVAL) {
+          try {
+            currentToken = await config.tokenProvider();
+            lastTokenRefresh = now;
+            config.onTokenRefresh?.(currentToken);
+            
+            config.securityLogger?.('token_refreshed', {
+              siteId: config.siteId,
+              timestamp: new Date().toISOString()
+            });
+          } catch (error) {
+            config.securityLogger?.('token_refresh_failed', {
+              siteId: config.siteId,
+              error: error instanceof Error ? error.message : 'Unknown error'
+            });
+            throw new Error('Token refresh failed');
+          }
         }
 
+        // Add security headers
+        requestConfig.headers = {
+          ...requestConfig.headers,
+          'X-Request-ID': crypto.randomUUID(),
+          'X-Timestamp': new Date().toISOString(),
+          'User-Agent': `AugurAPI-Client/1.0 (Enterprise; ${process.env.NODE_ENV || 'development'})`
+        };
+
+        // Log security events
+        config.securityLogger?.('api_request', {
+          siteId: config.siteId,
+          url: requestConfig.url,
+          method: requestConfig.method,
+          requestId: requestConfig.headers['X-Request-ID']
+        });
+
+        return requestConfig;
+      },
+
+      // Response interceptor for security monitoring
+      onResponse: (response) => {
+        config.securityLogger?.('api_response', {
+          siteId: config.siteId,
+          status: response.status,
+          requestId: response.config.headers?.['X-Request-ID'],
+          responseTime: Date.now() - (response.config as any)?.startTime
+        });
+
         return response;
       },
-      
+
+      // Error interceptor for security logging
       onError: (error) => {
-        this.metrics.errors++;
-        console.error('API Error metrics:', this.getMetrics());
+        config.securityLogger?.('api_error', {
+          siteId: config.siteId,
+          error: error.message,
+          status: error.response?.status,
+          requestId: error.config?.headers?.['X-Request-ID']
+        });
+
+        // Don't expose sensitive errors in production
+        if (process.env.NODE_ENV === 'production') {
+          throw new Error('API request failed');
+        }
+        
         throw error;
       }
     });
   }
 
-  getMetrics() {
-    const avgResponseTime = this.metrics.requests > 0 
-      ? this.metrics.totalTime / this.metrics.requests 
-      : 0;
-    
-    const errorRate = this.metrics.requests > 0 
-      ? (this.metrics.errors / this.metrics.requests) * 100 
-      : 0;
-    
-    const cacheHitRate = (this.metrics.cacheHits + this.metrics.cacheMisses) > 0
-      ? (this.metrics.cacheHits / (this.metrics.cacheHits + this.metrics.cacheMisses)) * 100
-      : 0;
+  // 🔐 Cross-site authentication with security controls
+  static createSecureCrossSiteAuthenticator(config: {
+    adminTokenProvider: () => Promise<string>;
+    auditLogger: (event: string, details: any) => void;
+    rateLimiter?: (key: string) => Promise<boolean>;
+  }) {
+    return async (
+      targetSiteId: string, 
+      username: string, 
+      password: string
+    ): Promise<CrossSiteAuthResult> => {
+      const startTime = Date.now();
+      const requestId = crypto.randomUUID();
 
-    return {
-      totalRequests: this.metrics.requests,
-      totalErrors: this.metrics.errors,
-      errorRate: errorRate.toFixed(2) + '%',
-      avgResponseTime: avgResponseTime.toFixed(2) + 'ms',
-      cacheHitRate: cacheHitRate.toFixed(2) + '%',
-      totalCacheHits: this.metrics.cacheHits,
-      totalCacheMisses: this.metrics.cacheMisses
+      try {
+        // Rate limiting check
+        if (config.rateLimiter) {
+          const rateLimitKey = `cross_site_auth:${username}:${targetSiteId}`;
+          const allowed = await config.rateLimiter(rateLimitKey);
+          if (!allowed) {
+            config.auditLogger('cross_site_auth_rate_limited', {
+              username,
+              targetSiteId,
+              requestId,
+              timestamp: new Date().toISOString()
+            });
+            return { success: false, error: 'Rate limit exceeded' };
+          }
+        }
+
+        // Get fresh admin token
+        const adminToken = await config.adminTokenProvider();
+
+        // Perform authentication with audit logging
+        config.auditLogger('cross_site_auth_attempt', {
+          username,
+          targetSiteId,
+          requestId,
+          timestamp: new Date().toISOString()
+        });
+
+        const result = await authenticateUserForSite({
+          targetSiteId,
+          username,
+          password,
+          augurInfoToken: adminToken
+        });
+
+        // Log result
+        config.auditLogger('cross_site_auth_result', {
+          username,
+          targetSiteId,
+          requestId,
+          success: result.success,
+          error: result.error,
+          duration: Date.now() - startTime,
+          timestamp: new Date().toISOString()
+        });
+
+        return result;
+
+      } catch (error) {
+        config.auditLogger('cross_site_auth_error', {
+          username,
+          targetSiteId,
+          requestId,
+          error: error instanceof Error ? error.message : 'Unknown error',
+          duration: Date.now() - startTime,
+          timestamp: new Date().toISOString()
+        });
+
+        return { 
+          success: false, 
+          error: 'Authentication service unavailable' 
+        };
+      }
     };
   }
+}
 
-  reset(): void {
-    this.metrics = {
-      requests: 0,
-      errors: 0,
-      totalTime: 0,
-      cacheHits: 0,
-      cacheMisses: 0
+// 📊 Security monitoring and alerting
+class SecurityMonitor {
+  private suspiciousActivity = new Map<string, number>();
+  private readonly MAX_FAILED_ATTEMPTS = 5;
+  private readonly MONITORING_WINDOW = 60 * 60 * 1000; // 1 hour
+
+  logSecurityEvent(event: string, details: any): void {
+    const timestamp = new Date().toISOString();
+    const logEntry = {
+      timestamp,
+      event,
+      ...details,
+      severity: this.getEventSeverity(event)
     };
+
+    // Log to security system (console for example)
+    console.log('🔒 SECURITY EVENT:', JSON.stringify(logEntry));
+
+    // Check for suspicious patterns
+    this.detectSuspiciousActivity(event, details);
+
+    // Alert on high-severity events
+    if (logEntry.severity === 'HIGH') {
+      this.triggerSecurityAlert(logEntry);
+    }
+  }
+
+  private getEventSeverity(event: string): 'LOW' | 'MEDIUM' | 'HIGH' {
+    const highSeverityEvents = [
+      'cross_site_auth_rate_limited',
+      'token_refresh_failed',
+      'multiple_failed_attempts'
+    ];
+    
+    const mediumSeverityEvents = [
+      'cross_site_auth_result',
+      'api_error'
+    ];
+
+    if (highSeverityEvents.includes(event)) return 'HIGH';
+    if (mediumSeverityEvents.includes(event)) return 'MEDIUM';
+    return 'LOW';
+  }
+
+  private detectSuspiciousActivity(event: string, details: any): void {
+    if (event === 'cross_site_auth_result' && !details.success) {
+      const key = `failed_auth:${details.username}:${details.targetSiteId}`;
+      const count = (this.suspiciousActivity.get(key) || 0) + 1;
+      this.suspiciousActivity.set(key, count);
+
+      if (count >= this.MAX_FAILED_ATTEMPTS) {
+        this.logSecurityEvent('multiple_failed_attempts', {
+          username: details.username,
+          targetSiteId: details.targetSiteId,
+          attemptCount: count,
+          windowStart: new Date(Date.now() - this.MONITORING_WINDOW).toISOString()
+        });
+      }
+    }
+  }
+
+  private triggerSecurityAlert(logEntry: any): void {
+    // Implement your alerting system here
+    console.warn('🚨 SECURITY ALERT:', logEntry);
+    
+    // Example integrations:
+    // - Send to SIEM system
+    // - Slack/Teams notification
+    // - Email security team
+    // - Trigger automated response
   }
 }
 
-// Usage
-const monitor = new PerformanceMonitor();
-const api = monitor.createMonitoredAPI({
-  siteId: 'your-site-id',
-  bearerToken: 'your-token'
+// 🎮 USAGE EXAMPLE
+const securityMonitor = new SecurityMonitor();
+
+// Create secure API client with monitoring
+const secureAPI = SecureConfigManager.createSecureAPIClient({
+  siteId: 'production-site',
+  tokenProvider: async () => {
+    // Your secure token provider implementation
+    return await getTokenFromSecureVault();
+  },
+  onTokenRefresh: (newToken) => {
+    // Store token securely
+    storeTokenInSecureVault(newToken);
+  },
+  securityLogger: (event, details) => {
+    securityMonitor.logSecurityEvent(event, details);
+  }
 });
 
-// After some API calls, check performance
-setTimeout(() => {
-  console.log('Performance metrics:', monitor.getMetrics());
-}, 60000);
+// Create secure cross-site authenticator
+const secureCrossSiteAuth = SecureConfigManager.createSecureCrossSiteAuthenticator({
+  adminTokenProvider: async () => await getAdminTokenFromVault(),
+  auditLogger: (event, details) => securityMonitor.logSecurityEvent(event, details),
+  rateLimiter: async (key) => {
+    // Implement rate limiting logic
+    return await checkRateLimit(key);
+  }
+});
 ```
 
+### Production Deployment Guidelines
+
+**Deploy with confidence** using enterprise-grade deployment practices:
+
+```typescript
+/**
+ * 🚀 PRODUCTION DEPLOYMENT CHECKLIST
+ * 
+ * Complete guide for deploying Augur API clients in enterprise
+ * production environments with monitoring and reliability.
+ */
+
+// 🏗️ Production Configuration Template
+class ProductionConfig {
+  static readonly ENVIRONMENT_CONFIG = {
+    development: {
+      logLevel: 'debug',
+      requestTimeout: 30000,
+      retryAttempts: 2,
+      enableDetailedErrors: true,
+      cacheEnabled: false
+    },
+    staging: {
+      logLevel: 'info', 
+      requestTimeout: 15000,
+      retryAttempts: 3,
+      enableDetailedErrors: true,
+      cacheEnabled: true
+    },
+    production: {
+      logLevel: 'warn',
+      requestTimeout: 10000,
+      retryAttempts: 5,
+      enableDetailedErrors: false,
+      cacheEnabled: true
+    }
+  };
+
+  static createProductionAPI(environment: 'development' | 'staging' | 'production'): AugurAPI {
+    const config = ProductionConfig.ENVIRONMENT_CONFIG[environment];
+    
+    return new AugurAPI({
+      siteId: process.env.AUGUR_SITE_ID!,
+      bearerToken: process.env.AUGUR_JWT_TOKEN!,
+      
+      // Production timeouts and retries
+      timeout: config.requestTimeout,
+      retries: config.retryAttempts,
+      
+      // Environment-specific request handling
+      onRequest: (requestConfig) => {
+        // Add request ID for tracing
+        requestConfig.headers = {
+          ...requestConfig.headers,
+          'X-Environment': environment,
+          'X-Request-ID': crypto.randomUUID(),
+          'X-Deployment-Version': process.env.DEPLOYMENT_VERSION || 'unknown'
+        };
+
+        if (config.logLevel === 'debug') {
+          console.log(`🔍 API Request: ${requestConfig.method?.toUpperCase()} ${requestConfig.url}`);
+        }
+
+        return requestConfig;
+      },
+
+      onResponse: (response) => {
+        if (config.logLevel === 'debug') {
+          console.log(`✅ API Response: ${response.status} for ${response.config.url}`);
+        }
+        return response;
+      },
+
+      onError: (error) => {
+        // Production error handling
+        const sanitizedError = config.enableDetailedErrors 
+          ? error 
+          : new Error('API request failed - check logs for details');
+
+        // Log error details for debugging (always log internally)
+        console.error('❌ API Error:', {
+          url: error.config?.url,
+          method: error.config?.method,
+          status: error.response?.status,
+          message: error.message,
+          requestId: error.config?.headers?.['X-Request-ID'],
+          environment
+        });
+
+        throw sanitizedError;
+      }
+    });
+  }
+}
+
+// 📊 Health Check & Monitoring System
+class ProductionHealthMonitor {
+  private healthCheckInterval: NodeJS.Timer | null = null;
+  private lastHealthCheck: Record<string, any> = {};
+
+  async initializeHealthChecks(apis: Map<string, AugurAPI>): Promise<void> {
+    console.log('🏥 Initializing health monitoring...');
+
+    // Initial health check
+    await this.performHealthChecks(apis);
+
+    // Periodic health checks (every 5 minutes)
+    this.healthCheckInterval = setInterval(async () => {
+      await this.performHealthChecks(apis);
+    }, 5 * 60 * 1000);
+
+    console.log('✅ Health monitoring initialized');
+  }
+
+  private async performHealthChecks(apis: Map<string, AugurAPI>): Promise<void> {
+    const timestamp = new Date().toISOString();
+    const healthResults: Record<string, any> = {};
+
+    for (const [siteId, api] of apis.entries()) {
+      try {
+        const startTime = Date.now();
+        
+        // Test core services
+        const [joomlaHealth, pricingHealth, vmiHealth] = await Promise.allSettled([
+          api.joomla.getHealthCheck(),
+          api.pricing.getHealthCheck(),
+          api.vmi.health.ping()
+        ]);
+
+        const responseTime = Date.now() - startTime;
+
+        healthResults[siteId] = {
+          status: 'healthy',
+          responseTime,
+          services: {
+            joomla: joomlaHealth.status === 'fulfilled' ? 'healthy' : 'unhealthy',
+            pricing: pricingHealth.status === 'fulfilled' ? 'healthy' : 'unhealthy',
+            vmi: vmiHealth.status === 'fulfilled' ? 'healthy' : 'unhealthy'
+          },
+          timestamp
+        };
+
+        console.log(`✅ Health check passed for ${siteId} (${responseTime}ms)`);
+
+      } catch (error) {
+        healthResults[siteId] = {
+          status: 'unhealthy',
+          error: error instanceof Error ? error.message : 'Unknown error',
+          timestamp
+        };
+
+        console.error(`❌ Health check failed for ${siteId}:`, error);
+        
+        // Trigger alert for unhealthy sites
+        await this.alertUnhealthySite(siteId, error);
+      }
+    }
+
+    this.lastHealthCheck = healthResults;
+  }
+
+  private async alertUnhealthySite(siteId: string, error: any): Promise<void> {
+    // Implement your alerting system
+    console.warn(`🚨 HEALTH ALERT: Site ${siteId} is unhealthy`, error);
+    
+    // Example integrations:
+    // - PagerDuty incident
+    // - Slack notification
+    // - Email alert
+    // - Automated failover
+  }
+
+  getHealthStatus(): Record<string, any> {
+    return this.lastHealthCheck;
+  }
+
+  destroy(): void {
+    if (this.healthCheckInterval) {
+      clearInterval(this.healthCheckInterval);
+      this.healthCheckInterval = null;
+    }
+  }
+}
+
+// 🔄 Graceful Shutdown Manager
+class GracefulShutdownManager {
+  private isShuttingDown = false;
+  private activeRequests = new Set<Promise<any>>();
+
+  initialize(): void {
+    // Handle shutdown signals
+    process.on('SIGTERM', () => this.handleShutdown('SIGTERM'));
+    process.on('SIGINT', () => this.handleShutdown('SIGINT'));
+    process.on('SIGHUP', () => this.handleShutdown('SIGHUP'));
+
+    console.log('🛡️ Graceful shutdown handler initialized');
+  }
+
+  private async handleShutdown(signal: string): Promise<void> {
+    if (this.isShuttingDown) return;
+    
+    console.log(`🛑 Received ${signal}, starting graceful shutdown...`);
+    this.isShuttingDown = true;
+
+    try {
+      // Wait for active requests to complete (with timeout)
+      const shutdownTimeout = 30000; // 30 seconds
+      const shutdownPromise = Promise.all(this.activeRequests);
+      
+      await Promise.race([
+        shutdownPromise,
+        new Promise(resolve => setTimeout(resolve, shutdownTimeout))
+      ]);
+
+      console.log('✅ Graceful shutdown completed');
+      process.exit(0);
+
+    } catch (error) {
+      console.error('❌ Error during shutdown:', error);
+      process.exit(1);
+    }
+  }
+
+  trackRequest<T>(request: Promise<T>): Promise<T> {
+    if (this.isShuttingDown) {
+      throw new Error('Service is shutting down');
+    }
+
+    this.activeRequests.add(request);
+    
+    return request.finally(() => {
+      this.activeRequests.delete(request);
+    });
+  }
+
+  isShutdown(): boolean {
+    return this.isShuttingDown;
+  }
+}
+
+// 🎮 PRODUCTION DEPLOYMENT EXAMPLE
+async function deployProductionApplication() {
+  console.log('🚀 Starting production application...');
+
+  // 1. Initialize graceful shutdown
+  const shutdownManager = new GracefulShutdownManager();
+  shutdownManager.initialize();
+
+  // 2. Create production API clients
+  const environment = process.env.NODE_ENV as 'development' | 'staging' | 'production' || 'production';
+  const apis = new Map<string, AugurAPI>();
+  
+  // Multiple tenant sites
+  const tenantSites = process.env.TENANT_SITES?.split(',') || ['main-site'];
+  
+  for (const siteId of tenantSites) {
+    const api = ProductionConfig.createProductionAPI(environment);
+    apis.set(siteId, api);
+  }
+
+  // 3. Initialize health monitoring
+  const healthMonitor = new ProductionHealthMonitor();
+  await healthMonitor.initializeHealthChecks(apis);
+
+  // 4. Start application logic
+  console.log(`✅ Production application started with ${apis.size} tenant site(s)`);
+
+  // 5. Cleanup on shutdown
+  process.on('exit', () => {
+    healthMonitor.destroy();
+    console.log('🧹 Cleanup completed');
+  });
+
+  return { apis, healthMonitor, shutdownManager };
+}
+
+// Environment Variables Checklist for Production:
+/*
+REQUIRED ENVIRONMENT VARIABLES:
+- AUGUR_SITE_ID: Primary site identifier
+- AUGUR_JWT_TOKEN: Authentication token
+- AUGUR_ADMIN_TOKEN: Admin token for cross-site operations
+- NODE_ENV: production|staging|development
+- TENANT_SITES: Comma-separated list of tenant site IDs
+- DEPLOYMENT_VERSION: Current deployment version
+- ALLOWED_ORIGINS: Comma-separated list of allowed origins
+
+OPTIONAL ENVIRONMENT VARIABLES:
+- LOG_LEVEL: error|warn|info|debug
+- REQUEST_TIMEOUT: Request timeout in milliseconds
+- MAX_RETRIES: Maximum retry attempts
+- HEALTH_CHECK_INTERVAL: Health check interval in minutes
+*/
+```
+
+**Production Deployment Checklist:**
+
+- ✅ **Environment Variables**: All required variables set and verified
+- ✅ **Security Configuration**: Tokens secured, HTTPS enforced, rate limiting enabled
+- ✅ **Health Monitoring**: Health checks configured with alerting
+- ✅ **Error Handling**: Production error handling with proper logging
+- ✅ **Graceful Shutdown**: Proper cleanup on application termination
+- ✅ **Multi-Tenant Support**: Tenant isolation and cross-site authentication
+- ✅ **Performance Optimization**: Edge caching and batch operations configured
+- ✅ **Monitoring & Alerting**: Security events, API performance, and health status tracking
+
+For detailed authentication patterns, see [Authentication Guide](./AUTHENTICATION.md).
+For performance optimization strategies, see [Performance Guide](./PERFORMANCE.md).
+
 ## Development
 
 ### Building from Source