@simpleapps-com/augur-api 0.5.1 → 0.7.0

package/README.md

@@ -1,3776 +1,76 @@
-# The Augur Platform: Code That Almost Writes Itself
+# @simpleapps-com/augur-api
 
-Transform enterprise API chaos into developer flow with intelligent client generation, context-aware discovery, and AI-powered development acceleration.
+TypeScript client library for Augur microservices.
 
-> **🚀 NEW in v0.4.0**: Revolutionary OpenAPI Path Mirroring Pattern with comprehensive schema organization, dual API patterns, and enhanced AI-powered discovery across 20+ microservices.
-
-## Experience the Magic in 30 Seconds
-
-```typescript
-// Before: 35+ lines of authentication boilerplate
-const userJwt = await getToken({ req: request });
-if (!userJwt?.jwtToken) throw new Error('Authentication failed');
-const api = new AugurAPI({ siteId: context.siteId, bearerToken: userJwt.jwtToken });
-
-// After: Pure business intent ✨
-const api = AugurAPI.fromContext(context);
-
-// Ask for anything and find it instantly
-const userOps = await api.findEndpoint('user management');
-const inventory = await api.findEndpoint('stock levels'); 
-const pricing = await api.findEndpoint('product pricing');
-
-// Code that understands your business domain (v0.4.0 Path Mirroring)
-const users = await api.joomla.users.list({ limit: 10 });
-const content = await api.joomla.content.list({ categoryId: 1 });
-const userGroups = await api.joomla.userGroups.list();
-
-// NEW: OpenAPI path mirroring - exact path-to-client structure mapping
-const aiAnswer = await api.gregorovich.chatGpt.ask.get({ question: "What is AI?" });
-const searchResults = await api.openSearch.itemSearch.list({ query: "widgets" });
-const attributes = await api.openSearch.itemSearch.attributes.list({ category: "tools" });
-```
-
-## Table of Contents
-
-- [🚀 Quick Start Guide](./QUICKSTART.md) - **Experience the magic in under 5 minutes**
-- [🆕 OpenAPI Path Mirroring (v0.4.0)](#-openapi-path-mirroring-v040) - **Revolutionary client structure mapping**
-- [The Five Ideals in Action](#the-five-ideals-in-action)
-- [🎯 AI-Powered Discovery System](#-ai-powered-discovery-system)
-- [📖 API Discovery Guide](./API-DISCOVERY.md) - Natural language API navigation
-- [Developer Experience Revolution](#developer-experience-revolution)
-- [Context-Aware Architecture](#context-aware-architecture)
-- [Prophet 21 Data Source Integration](#prophet-21-data-source-integration) - **ERP naming conventions and business context**
-- [Service Architecture & Roadmap](#service-architecture--roadmap) - **Currently available and upcoming services**
-- [Installation & First Steps](#installation--first-steps)
-- [Intelligent Discovery Examples](#intelligent-discovery-examples)
-- [Cross-Service Intelligence](#cross-service-intelligence)
-- [Advanced Capabilities](#advanced-capabilities)
-- [Platform Integration](#platform-integration)
-- [Performance & Caching](#performance--caching)
-- [Troubleshooting & Support](#troubleshooting--support)
-
-## 🆕 OpenAPI Path Mirroring (v0.4.0)
-
-**Revolutionary client architecture**: Every OpenAPI path segment maps directly to client structure, making API navigation intuitive and predictable.
-
-### Path-to-Client Structure Magic ✨
-
-```typescript
-// OpenAPI Path → Client Structure (Exact Mapping)
-// /chat-gpt/ask → client.chatGpt.ask.get()
-// /documents → client.documents.list()
-// /item-search → client.itemSearch.list()
-// /item-search/attributes → client.itemSearch.attributes.list()
-// /items/{invMastUid}/refresh → client.items.refresh.get(invMastUid)
-
-const api = AugurAPI.fromContext(context);
-
-// AI and Document Management (Gregorovich Service)
-const aiResponse = await api.gregorovich.chatGpt.ask.get({ 
-  question: "How do I optimize inventory?" 
-});
-const documents = await api.gregorovich.documents.list();
-const ollamaResult = await api.gregorovich.ollama.generate.create({
-  prompt: "Generate product description"
-});
-
-// Advanced Search (OpenSearch Service)  
-const ping = await api.openSearch.ping.get();
-const health = await api.openSearch.healthCheck.get();
-const searchResults = await api.openSearch.itemSearch.list({ query: "tools" });
-const searchAttrs = await api.openSearch.itemSearch.attributes.list({ query: "power" });
-const refreshStatus = await api.openSearch.items.refresh.update({ force: true });
-
-// Specific item operations with path parameters
-const item = await api.openSearch.items.get(invMastUid);
-const itemRefresh = await api.openSearch.items.refresh.get(invMastUid);
-```
-
-### Dual API Pattern (Standard + Data Methods) 
-
-**Every endpoint provides two access patterns** for maximum flexibility:
-
-```typescript
-// Standard method - complete BaseResponse with metadata
-const response = await api.gregorovich.chatGpt.ask.get({ question: "What is AI?" });
-console.log(response.data.answer);    // AI answer
-console.log(response.status);         // HTTP status
-console.log(response.message);        // Response message
-
-// Data method - direct access to data only  
-const userData = await api.joomla.users.listData({ limit: 10 });
-console.log(userData);               // Direct access to users array
-```
-
-### Schema Organization Revolution
-
-**Path-based schema files** mirror the client structure:
-
-```
-services/gregorovich/schemas/
-├── index.ts              # Central exports with path-based aliases
-├── chatGptAsk.ts         # /chat-gpt/ask endpoint schemas
-├── documents.ts          # /documents endpoint schemas  
-├── healthCheck.ts        # /health-check endpoint schemas
-└── ollamaGenerate.ts     # /ollama/generate endpoint schemas
-```
-
-**Benefits:**
-- **Predictable Navigation**: OpenAPI paths = client structure
-- **AI-Friendly**: Rich semantic metadata for intelligent suggestions
-- **Type Safety**: Full TypeScript coverage with Zod validation
-- **Dual Access**: Choose between full response or data-only patterns
-- **Scalable Architecture**: Consistent patterns across 20+ microservices
-
-## The Five Ideals in Action
-
-This platform embodies the Five Ideals from The Unicorn Project, transforming how developers interact with enterprise APIs:
-
-### Locality and Simplicity ✨
-**No more coordination across 13 different APIs.** One unified interface eliminates architectural complexity.
-
-```typescript
-// Instead of learning 13 different authentication patterns
-await joomlaAPI.authenticate(token);
-await commerceAPI.setAuth(bearer);
-await pricingAPI.login(credentials);
-
-// One pattern rules them all
-const api = AugurAPI.fromContext(context);
-```
-
-### Focus, Flow, and Joy 🎯
-**Zero context switching.** Intelligent discovery means never leaving your flow state.
-
-```typescript
-// No documentation hunting, no API reference browsing
-const results = await api.findEndpoint('inventory management');
-// Instantly find: api.vmi.warehouses.list, api.vmi.invProfileHdr.checkAvailability
-
-// Your IDE becomes clairvoyant with comprehensive semantic JSDoc
-api.vmi.invProfileHdr. // ← Auto-complete shows exactly what you need
-```
-
-### Improvement of Daily Work 🔄
-**The platform learns your patterns** and suggests related operations across services.
-
-```typescript
-// When you work with users, it suggests related customer operations
-const user = await api.joomla.users.get('123');
-// Related suggestions: api.customers.customer.get, api.orders.salesRep.getOrders
-```
-
-### Psychological Safety 🛡️
-**Fail fast with clear, actionable errors.** No more guessing what went wrong.
-
-```typescript
-try {
-  const api = AugurAPI.fromContext(context);
-} catch (error) {
-  // Clear guidance: "Context missing siteId - check your context.siteId property"
-  // No blame, just solutions
-}
-```
-
-### Customer Focus 📊
-**Business context embedded** in every endpoint. Search by business intent, not technical implementation.
-
-```typescript
-// Search by what you're trying to accomplish
-await api.findEndpoint('customer order history');
-await api.findEndpoint('product recommendations');
-await api.findEndpoint('inventory replenishment');
-```
-
-## AI-Powered Discovery System
-
-**Never memorize API endpoints again.** The discovery system understands business context and finds functionality through natural language.
-
-### Semantic Intelligence
-
-Every endpoint includes AI-readable metadata:
-
-```typescript
-/**
- * @searchTerms ["users", "authentication", "user management", "login"]
- * @relatedEndpoints ["api.customers.customer.get", "api.joomla.userGroups.list"]
- * @workflow ["user-onboarding", "authentication-flow", "user-administration"]
- * @commonPatterns ["Get user profile", "List active users", "Create new account"]
- */
-```
-
-### Cross-Service Awareness
-
-The system maps relationships between all active microservices (13 currently available, 26 total in development):
-
-```typescript
-// Working with users? It knows you might need customers too
-const userEndpoints = await api.findEndpoint('user management');
-// Suggests: joomla.users.list, customers.customer.get, orders.salesRep.getOrders
-
-// Working with inventory? It connects you to pricing
-const inventoryOps = await api.findEndpoint('stock management'); 
-// Suggests: vmi.warehouses.list, pricing.getPrice, items.products.get
-```
-
-## Developer Experience Revolution
-
-### Context-Aware Creation
-Eliminate 70% of setup boilerplate with intelligent context extraction:
-
-```typescript
-// Traditional enterprise pattern (35+ lines)
-const authentication = await authenticateUser(request);
-if (!authentication.success) {
-  return handleAuthFailure(authentication.error);
-}
-const siteContext = await resolveSiteContext(authentication.user);
-const apiConfig = {
-  siteId: siteContext.siteId,
-  bearerToken: authentication.jwtToken,
-  timeout: getConfiguredTimeout(),
-  retries: getRetryPolicy()
-};
-const api = new AugurAPI(apiConfig);
-
-// Context-aware magic (1 line)
-const api = AugurAPI.fromContext(context);
-```
-
-### Intelligent Method Discovery
-Every method includes rich semantic metadata for AI assistants:
-
-```typescript
-// Ask your AI assistant: "Help me manage warehouse inventory"
-// It instantly finds and suggests:
-await api.vmi.warehouses.list({ customerId: 12345 });
-await api.vmi.invProfileHdr.checkAvailability(warehouseId);
-await api.vmi.invProfileHdr.replenish(warehouseId, { items });
-```
-
-### Factory Pattern Excellence
-Sophisticated factory patterns create consistent, discoverable APIs:
-
-```typescript
-// Auto-generated from OpenAPI specs with semantic enhancement
-export class VMIClient extends BaseServiceClient {
-  get warehouses() { return this.createWarehouseOperations(); }
-  get inventory() { return this.createInventoryOperations(); }
-  get distributors() { return this.createDistributorOperations(); }
-}
-```
-
-## Installation & First Steps
+## Installation
 
 ```bash
 npm install @simpleapps-com/augur-api
 ```
 
-### Immediate Value Demo
+## Quick Start
 
 ```typescript
 import { AugurAPI } from '@simpleapps-com/augur-api';
 
-// Create from context (eliminates boilerplate)
-const api = AugurAPI.fromContext(context);
-
-// Discover capabilities (no documentation needed)
-const services = await api.discover();
-console.log(`Connected to ${services.length} active business services`);
-
-// Find what you need (natural language)
-const userStuff = await api.findEndpoint('user management');
-const inventoryStuff = await api.findEndpoint('stock levels');
-
-// Work with the actual Joomla API
-const users = await api.joomla.users.list({ 
-  limit: 10
-});
-```
-
-## Intelligent Discovery Examples
-
-### Business Context Understanding
-
-The platform knows your business domain and connects related operations:
-
-```typescript
-// Search by business intent, not technical endpoints
-const userOps = await api.findEndpoint('customer account management');
-// Returns: 
-// - api.joomla.users.list (user authentication)
-// - api.customers.customer.get (customer profiles) 
-// - api.orders.salesRep.getOrders (order history)
-
-const inventoryOps = await api.findEndpoint('stock replenishment');
-// Returns:
-// - api.vmi.invProfileHdr.checkAvailability (current levels)
-// - api.vmi.invProfileHdr.replenish (automated ordering)
-// - api.pricing.getPrice (cost calculations)
-```
-
-### Workflow-Aware Suggestions
-
-Working on one task? The system suggests the next logical steps:
-
-```typescript
-// Create a user account
-const newUser = await api.joomla.users.create({
-  username: 'john.doe',
-  email: 'john@company.com'
-});
-
-// System knows you might need to:
-// 1. Set up customer profile: api.customers.customer.create()
-// 2. Assign user groups: api.joomla.userGroups.createMapping() 
-// 3. Check permissions: api.joomla.users.groups.list()
-```
-
-### Cross-Service Intelligence
-
-The discovery system maps business workflows across all active microservices:
-
-```typescript
-// E-commerce workflow discovery
-const ecommerceFlow = await api.findEndpoint('online shopping');
-// Suggests complete customer journey:
-// - Product search: api.opensearch.itemSearch.search()
-// - Pricing: api.pricing.getPrice()
-// - Cart management: api.commerce.cartHeaders.lookup()
-// - Checkout: api.commerce.checkout.get()
-// - Payment: api.payments.unified.transactionSetup()
-```
-
-## Context-Aware Architecture
-
-### Intelligent Context Extraction
-
-The `fromContext()` method understands various context patterns:
-
-```typescript
-// Middleware context
-const api = AugurAPI.fromContext({
-  siteId: req.headers['x-site-id'],
-  jwt: req.headers.authorization?.replace('Bearer ', ''),
-  userId: req.user.id
-});
-
-// Tool handler context
-const api = AugurAPI.fromContext({
-  siteId: context.siteId,
-  bearerToken: context.authentication.token,
-  parameters: context.requestParams
-});
-
-// Next.js context
-const api = AugurAPI.fromContext({
-  siteId: process.env.NEXT_PUBLIC_SITE_ID,
-  jwt: session.accessToken
-});
-```
-
-### Factory Pattern Excellence
-
-Each service client is lazily instantiated with sophisticated caching:
-
-```typescript
-// Clients are created on-demand and cached
-const joomla1 = api.joomla;  // Creates new instance
-const joomla2 = api.joomla;  // Returns cached instance
-console.log(joomla1 === joomla2); // true
-
-// Token changes invalidate all clients automatically
-api.setAuthToken('new-token');
-const joomla3 = api.joomla;  // Creates fresh instance with new token
-console.log(joomla1 === joomla3); // false
-```
-
-### Semantic Method Generation
-
-Every endpoint includes rich semantic metadata for AI discovery:
-
-```typescript
-/**
- * List site settings with intelligent filtering and caching
- * @fullPath api.agrSite.settings.list
- * @service agr-site
- * @domain site-content-management
- * @searchTerms ["settings", "configuration", "site management", "admin"]
- * @relatedEndpoints ["api.agrSite.settings.get", "api.agrSite.settings.update"]
- * @workflow ["site-administration", "configuration-management"]
- * @commonPatterns ["Get all settings", "Filter by service", "Cache configuration"]
- * @discoverable true
- */
-async list(params?: SettingListParams): Promise<SettingListResponse> {
-  // Implementation uses sophisticated base class patterns
-}
-```
-
-## Advanced Capabilities
-
-### Intelligent Service Discovery
-
-The discovery system provides both exploration and targeted search:
-
-```typescript
-// Comprehensive service topology
-const services = await api.discover();
-console.log(`Platform connected to ${services.length} active business services`);
-
-// Each service reveals its capabilities
-services.forEach(service => {
-  console.log(`${service.serviceName}: ${service.endpointCount} operations available`);
-  console.log(`Business domain: ${service.description}`);
-});
-
-// Targeted functionality search with intelligent scoring
-const results = await api.findEndpoint('inventory management', {
-  minScore: 0.1,    // Relevance threshold
-  maxResults: 10,   // Limit results
-  service: 'vmi',   // Optional service filter
-  domain: 'inventory-management', // Business domain filter
-  readOnly: true    // Only read operations
-});
-
-// Results include relevance scores and match reasoning
-results.forEach(result => {
-  console.log(`${result.endpoint.fullPath} (score: ${result.score})`);
-  console.log(`Match reason: ${result.matchReason}`);
-});
-```
-
-### Multi-Method Pattern Innovation
-
-Every endpoint offers dual access patterns for maximum flexibility:
-
-```typescript
-// Full response with metadata (standard pattern)
-const response = await api.joomla.users.list({ limit: 10 });
-console.log(`Found ${response.data.length} users`);
-console.log(`Total available: ${response.totalResults}`);
-console.log(`Status: ${response.message}`);
-
-// Data-only access (streamlined pattern)  
-const users = await api.joomla.users.listData({ limit: 10 });
-console.log(users); // Direct array access, no wrapper
-```
-
-## Prophet 21 Data Source Integration
-
-Many API endpoints reflect Prophet 21 ERP system naming conventions and table structures. This provides direct mapping from your business processes to API operations.
-
-### Understanding Prophet 21 Naming Patterns
-
-The Path-Function Alignment Pattern preserves Prophet 21 table naming for user recognition:
-
-```typescript
-// Prophet 21 Table → API Endpoint → Client Structure
-// inv_mast table → /inv-mast → api.items.invMast
-// oe_hdr table → /oe-hdr → api.orders.oeHdr  
-// job_price_hdr table → /job-price-hdr → api.pricing.jobPriceHdr
-// restock_hdr table → /restock-hdr → api.vmi.restockHdr
-// inv_profile_hdr table → /inv-profile-hdr → api.vmi.invProfileHdr
-
-// Examples with Prophet 21 context:
-const inventory = await api.items.invMast.get(12345);        // Inventory master record
-const order = await api.orders.oeHdr.get(67890);            // Order entry header  
-const pricing = await api.pricing.jobPriceHdr.get(111);     // Job pricing header
-const restock = await api.vmi.restockHdr.get(222);          // Restocking header
-const profile = await api.vmi.invProfileHdr.get(333);       // Inventory profile header
-```
-
-### Prophet 21 Business Context
-
-Understanding the ERP context helps predict API behavior:
-
-```typescript
-// Inventory Management (Prophet 21 inv_mast context)
-const itemDetails = await api.items.invMast.get(itemId);
-const locations = await api.items.invMast.locations.list(itemId);  // Physical locations
-const alternates = await api.items.invMast.alternateCode.list(itemId); // Alternate part numbers
-
-// Order Processing (Prophet 21 oe_hdr context) 
-const orderHeader = await api.orders.oeHdr.get(orderId);
-const salesRep = await api.orders.oeHdrSalesrep.get(orderId);      // Sales representative info
-const lineItems = await api.orders.oeHdr.lines.list(orderId);     // Order line details
-
-// VMI Operations (Prophet 21 inventory management context)
-const profileHeader = await api.vmi.invProfileHdr.get(profileId);  // VMI profile setup
-const restockInfo = await api.vmi.restockHdr.get(restockId);      // Restocking instructions
-const warehouseData = await api.vmi.warehouse.get(warehouseId);   // Warehouse details
-```
-
-### Migration from Legacy Naming
-
-If you're familiar with conceptual API naming, here's the Prophet 21 mapping:
-
-```typescript
-// Legacy Conceptual → Prophet 21 Aligned
-client.inventory        → client.invMast         // Inventory master
-client.categories       → client.itemCategory    // Item categories  
-client.orders          → client.oeHdr           // Order entry header
-client.salesRep        → client.oeHdrSalesrep   // Order header sales rep
-client.purchaseOrders  → client.poHdr           // Purchase order header
-client.invoices        → client.invoiceHdr      // Invoice header
-client.inventoryProfiles → client.invProfileHdr // Inventory profile header
-client.restocking      → client.restockHdr      // Restock header
-client.calculateTax    → client.taxEngine.calculate    // Tax calculation engine
-client.jobPriceHeaders → client.jobPriceHdr     // Job price header
-```
-
-This alignment ensures that developers familiar with Prophet 21 can immediately understand the API structure and predict endpoint behavior based on their ERP knowledge.
-
-### Sophisticated Caching Architecture
-
-Intelligent edge caching with business-aware TTL policies:
-
-```typescript
-// Cache strategy varies by data volatility
-const categories = await api.items.categories.list({
-  edgeCache: 8  // Static reference data - 8 hours
-});
-
-const pricing = await api.pricing.getPrice({
-  customerId: 12345,
-  itemId: 'STANDARD-ITEM', 
-  quantity: 10,
-  edgeCache: 3  // Standard pricing - 3 hours
-});
-
-const cart = await api.commerce.cartHeaders.list({
-  userId: 123,
-  edgeCache: 1  // Volatile user data - 1 hour only
-});
-
-// Real-time operations never cached
-const auth = await api.joomla.users.verifyPassword({
-  username: 'user',
-  password: 'pass'
-  // No edgeCache - authentication must be real-time
-});
-```
-
-## Service Architecture & Roadmap
-
-### Available Services (26 Active)
-
-The Augur Platform exposes 26 fully-integrated business services with comprehensive AI discovery and semantic documentation:
-
-| Service | Business Domain | Key Capabilities | Status |
-|---------|----------------|------------------|--------|
-| **joomla** | Content & User Management | User authentication, content management, permissions | ✅ Active |
-| **commerce** | E-commerce Operations | Shopping cart, checkout, recommendations | ✅ Active |
-| **pricing** | Price Calculations | Dynamic pricing, job pricing, tax calculations | ✅ Active |
-| **vmi** | Vendor Managed Inventory | Warehouse operations, inventory profiles, restocking | ✅ Active |
-| **opensearch** | Search & Discovery | Product search, faceted navigation, search analytics | ✅ Active |
-| **items** | Product Catalog | Product management, categories, attributes, variants | ✅ Active |
-| **legacy** | Legacy Integration | State lookups, order history, also-bought recommendations | ✅ Active |
-| **nexus** | Warehouse Management | Bin transfers, receiving, shipping operations | ✅ Active |
-| **agrSite** | AGR Site Operations | Transcripts, notifications, settings management | ✅ Active |
-| **customers** | Customer Management | Customer profiles, contacts, addresses, order history | ✅ Active |
-| **orders** | Order Processing | Order management, invoices, purchase orders, sales rep | ✅ Active |
-| **p21Pim** | Product Information | AI suggestions, inventory extensions, product data | ✅ Active |
-| **payments** | Payment Processing | Payment methods, unified payments, element integration | ✅ Active |
-
-### Additional Services (13 More Active)
-
-The platform also includes these specialized and integration services:
-
-| Service | Business Domain | Key Capabilities | Status |
-|---------|----------------|------------------|--------|
-| **agrInfo** | AGR Information Services | Business intelligence, reporting | ✅ Active |
-| **agrWork** | AGR Workflow Services | Workflow automation, task management | ✅ Active |
-| **avalara** | Tax Calculation | Advanced tax calculations, compliance | ✅ Active |
-| **brandFolder** | Brand Asset Management | Brand assets, marketing materials | ✅ Active |
-| **gregorovich** | Gregorovich Integration | Third-party system integration | ✅ Active |
-| **logistics** | Logistics & Shipping | Advanced shipping, logistics optimization | ✅ Active |
-| **p21Apis** | P21 API Integration | Direct P21 system integration | ✅ Active |
-| **p21Core** | P21 Core Services | Core P21 business objects | ✅ Active |
-| **p21Sism** | P21 SISM Integration | P21 system integration & synchronization | ✅ Active |
-| **shipping** | Shipping Services | Shipping calculations, carrier integration | ✅ Active |
-| **slack** | Slack Integration | Team notifications, workflow integration | ✅ Active |
-| **smartyStreets** | Address Validation | Address verification, standardization | ✅ Active |
-| **ups** | UPS Integration | UPS shipping, tracking, rate calculations | ✅ Active |
-
-### Architecture Benefits
-
-With all 26 services active, the platform provides:
-- **Complete Business Coverage**: From user management to shipping integration
-- **Unified API Surface**: Consistent patterns across all business domains  
-- **AI-Powered Discovery**: Natural language navigation across 26+ service endpoints
-- **Cross-Service Intelligence**: Business workflows that span multiple services
-
-## 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 active 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
+const api = new AugurAPI({
+  siteId: process.env.AUGUR_SITE_ID,
+  bearerToken: process.env.AUGUR_TOKEN,
 });
 
-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);
-}
+// Access any service via api.{serviceName}
+const items = await api.items.invMast.list({ limit: 10 });
+const customers = await api.customers.customer.list({ limit: 10 });
+const orders = await api.orders.orders.lookup({ limit: 10 });
 ```
 
-### Smart Request Building
+## Service Access Pattern
 
-Advanced request construction with intelligent defaults:
+All services are accessed through the unified `AugurAPI` client:
 
 ```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
-});
+api.items        // Items service
+api.customers    // Customers service
+api.orders       // Orders service
+api.pricing      // Pricing service
+api.commerce     // Commerce service
+// ... 27 services total
 ```
 
-## Platform Capabilities Matrix
+## Documentation
 
-| Capability | Impact | Technical Implementation |
-|------------|--------|-------------------------|
-| **Context-Aware Creation** | 70% boilerplate reduction | `AugurAPI.fromContext()` with intelligent field extraction |
-| **Natural Language Discovery** | Zero API documentation hunting | Semantic JSDoc parsing with cross-service mapping |
-| **Intelligent Caching** | Sub-100ms response times | Cloudflare edge integration with business-aware TTL |
-| **Factory Pattern Excellence** | Consistent developer experience | Lazy instantiation with automatic cache invalidation |
-| **Cross-Service Intelligence** | Business workflow awareness | Relationship mapping across all active microservices |
-| **AI Assistant Integration** | Code that almost writes itself | Rich semantic metadata in every endpoint |
-| **Type Safety** | Runtime validation guarantee | Zod schema validation on all requests/responses |
-| **Multi-Platform Support** | Universal JavaScript compatibility | React, React Native, Next.js, Node.js, Electron |  
-
-## Installation
+| Resource | URL |
+|----------|-----|
+| **Full API Reference** | https://augur-api.info |
+| **Endpoint Hints** | `https://{service}.augur-api.com/llms.txt` |
+| **Parameters** | `https://{service}.augur-api.com/endpoints.jsonl` |
+| **OpenAPI Spec** | `https://{service}.augur-api.com/openapi.json` |
 
-```bash
-npm install @simpleapps-com/augur-api
-# or
-yarn add @simpleapps-com/augur-api
-# or
-pnpm add @simpleapps-com/augur-api
-```
+### Example: Items Service
 
-### System Requirements
+- https://items.augur-api.com/llms.txt
+- https://items.augur-api.com/endpoints.jsonl
+- https://items.augur-api.com/openapi.json
 
-- Node.js >= 16.0.0
-- TypeScript >= 4.5.0 (for TypeScript projects)
+Each `llms.txt` lists all other available services for discovery.
 
-## Getting Started
+## Authentication
 
-### Basic Setup
+All endpoints require:
+- `siteId` - Site identifier
+- `bearerToken` - Bearer authentication token
 
 ```typescript
-import { AugurAPI } from '@simpleapps-com/augur-api';
-
-// Traditional approach - manual configuration
 const api = new AugurAPI({
-  siteId: 'your-site-id',        // Required for all endpoints
-  bearerToken: 'your-jwt-token', // Required except for health checks
-});
-
-// Context-aware approach (recommended) - eliminates boilerplate
-const api = AugurAPI.fromContext(context);
-
-// Make your first API call
-const users = await api.joomla.users.list({
-  limit: 10,
-  edgeCache: 2  // Cache for 2 hours
+  siteId: 'your-site-id',
+  bearerToken: 'your-bearer-token',
 });
-
-console.log(`Found ${users.data.length} users`);
 ```
 
-### Context-Aware Client Creation ⭐ NEW!
+## For AI Agents
 
-The `fromContext()` method dramatically simplifies API client initialization by automatically extracting authentication and site information from your context object:
-
-```typescript
-import { AugurAPI, type AugurContext } from '@simpleapps-com/augur-api';
-
-// Your context object (common in tool handlers, middleware, etc.)
-const context: AugurContext = {
-  siteId: 'my-site-123',
-  jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
-  parameters: { limit: 10 },
-  filters: { search: 'electrical' },
-  userId: 456
-};
-
-// Before: 35+ lines of boilerplate
-const userJwt = await getToken({ req: request });
-if (!userJwt?.jwtToken) {
-  throw new Error('Authentication failed');
-}
-const api = new AugurAPI({ 
-  siteId: context.siteId, 
-  bearerToken: userJwt.jwtToken 
-});
-
-// After: 1 line of business intent ✨
-const api = AugurAPI.fromContext(context);
-
-// Optional configuration overrides
-const api = AugurAPI.fromContext(context, {
-  timeout: 10000,
-  retries: 1
-});
-```
-
-#### Context Interface
-
-```typescript
-interface AugurContext {
-  siteId: string;                    // Required: Site identifier
-  jwt?: string;                      // JWT token (preferred)
-  bearerToken?: string;              // Alternative token field
-  parameters?: Record<string, unknown>; // Request parameters
-  filters?: Record<string, unknown>;    // Filter parameters  
-  userId?: string | number;             // User identifier
-}
-```
-
-#### Error Handling
-
-The `fromContext()` method provides clear, actionable error messages:
-
-```typescript
-import { ContextCreationError } from '@simpleapps-com/augur-api';
-
-try {
-  const api = AugurAPI.fromContext(context);
-} catch (error) {
-  if (error instanceof ContextCreationError) {
-    console.error(`Context validation failed: ${error.message}`);
-    console.error(`Problem field: ${error.field}`);
-    
-    // Handle specific issues
-    switch (error.field) {
-      case 'siteId':
-        // Handle missing site ID
-        break;
-      case 'bearerToken':
-        // Handle missing authentication
-        break;
-    }
-  }
-}
-```
-
-### Environment Setup
-
-```typescript
-// .env file
-AUGUR_SITE_ID=your-site-id
-AUGUR_JWT_TOKEN=your-jwt-token
-
-// app.ts
-const api = new AugurAPI({
-  siteId: process.env.AUGUR_SITE_ID!,
-  bearerToken: process.env.AUGUR_JWT_TOKEN!,
-});
-```
-
-### Quick Example: E-commerce Operations
-
-```typescript
-// Get product recommendations
-const recommendations = await api.commerce.alsoBought.get({
-  itemId: 'WIRE-123',
-  customerId: 12345,
-  edgeCache: 4  // Cache recommendations for 4 hours
-});
-
-// Get real-time pricing
-const pricing = await api.pricing.getPrice({
-  customerId: 12345,
-  itemId: 'WIRE-123',
-  quantity: 100,
-  edgeCache: 3  // Cache standard pricing for 3 hours
-});
-
-// Search for products
-const searchResults = await api.opensearch.itemSearch.search({
-  q: 'electrical wire 12 AWG',
-  searchType: 'query',
-  size: 20,
-  edgeCache: 2  // Cache search results for 2 hours
-});
-```
-
-## Authentication & Security
-
-> 📋 **[Complete Authentication Guide](./AUTHENTICATION.md)** - Comprehensive guide including cross-site authentication for multi-tenant applications.
-
-### Standard Authentication (Most Common)
-
-The Augur API uses a dual authentication system:
-
-1. **Site ID** (`x-site-id` header) - Required for ALL endpoints
-2. **Bearer Token** (JWT) - Required for all endpoints EXCEPT health checks
-
-```typescript
-const api = new AugurAPI({
-  siteId: 'your-site-id',        // Always required
-  bearerToken: 'your-jwt-token', // Required except for health checks
-});
-```
-
-### Health Checks (No Authentication Required)
-
-```typescript
-// Health checks work without bearer token
-const api = new AugurAPI({
-  siteId: 'your-site-id',
-  // No bearerToken needed
-});
-
-const health = await api.joomla.getHealthCheck();
-const pricing = await api.pricing.getHealthCheck();
-const vmiPing = await api.vmi.health.ping();
-```
-
-### Environment Variables Setup
-
-```typescript
-// .env file
-AUGUR_SITE_ID=your-site-id
-AUGUR_JWT_TOKEN=your-jwt-token
-
-// app.ts
-const api = new AugurAPI({
-  siteId: process.env.AUGUR_SITE_ID!,
-  bearerToken: process.env.AUGUR_JWT_TOKEN!,
-});
-```
-
-### Dynamic Authentication Updates
-
-```typescript
-// Update credentials at runtime
-api.setAuthToken('new-jwt-token');
-api.setSiteId('new-site-id');
-
-// Useful for token refresh scenarios
-async function refreshTokenIfNeeded() {
-  try {
-    await api.joomla.users.list({ limit: 1 });
-  } catch (error) {
-    if (error instanceof AuthenticationError) {
-      const newToken = await refreshJWTToken();
-      api.setAuthToken(newToken);
-    }
-  }
-}
-```
-
-### Advanced: Cross-Site Authentication
-
-For multi-tenant applications that need to authenticate users across different sites:
-
-```typescript
-import { authenticateUserForSite } from '@simpleapps-com/augur-api';
-
-const result = await authenticateUserForSite({
-  targetSiteId: 'tenant_site_1',
-  username: 'user@tenant.com',
-  password: 'user-password',
-  augurInfoToken: 'admin-jwt-token'
-});
-
-if (result.success) {
-  const userData = await result.targetSiteAPI!.joomla.users.get(result.userId!);
-}
-```
-
-> ⚠️ **Cross-site authentication is an advanced feature.** See the [Complete Authentication Guide](./AUTHENTICATION.md) for detailed implementation patterns, security considerations, and troubleshooting.
-
-## API Documentation
-
-### Service Overview
-
-| Service | Purpose | Key Features |
-|---------|---------|--------------|
-| **Joomla** | Content & User Management | Articles, users, groups, tags, menu items |
-| **Commerce** | E-commerce Operations | Cart management, checkout, recommendations |
-| **Pricing** | Dynamic Pricing | Price calculations, job pricing, tax engine |
-| **VMI** | Inventory Management | Warehouses, stock levels, replenishment |
-| **OpenSearch** | Product Search | Full-text search, faceting, similarity matching |
-| **Items** | Product Catalog | Products, categories, attributes, brands |
-| **Customers** | Customer Data | Customer profiles, contacts, addresses, orders |
-| **Orders** | Order Management | Order lookup, documents, purchase orders |
-| **Payments** | Payment Processing | Transaction setup, payment validation |
-| **Legacy** | Legacy Systems | State data, inventory lookups |
-| **Nexus** | Warehouse Operations | Bin transfers, receiving, shipping |
-| **P21 PIM** | Product Information | Product data management, AI suggestions |
-| **AGR Site** | Site Management | Settings, notifications, transcripts |
-
-📋 **[Complete API Services Reference](./API-SERVICES.md)** - Detailed catalog of all 26 services with descriptions, OpenAPI specifications, and Postman collections.
-
-💡 **[Tips and Tricks Guide](./TIPS-AND-TRICKS.md)** - Advanced usage patterns, performance optimizations, and helpful techniques including the itemId → invMastUid lookup pattern.
-
-### Complete Endpoint Reference
-
-#### Joomla Service
-
-```typescript
-// Content Management - OpenAPI Compliant  
-const articles = await api.joomla.content.list({
-  limit: 20
-});
-
-const article = await api.joomla.content.get('123');
-
-const articleDoc = await api.joomla.content.doc.get('123');
-
-// User Management
-const users = await api.joomla.users.list({
-  limit: 50,
-  offset: 0,
-  orderBy: 'username|ASC',
-  q: 'john',
-  edgeCache: 2  // Cache user lists for 2 hours
-});
-
-const user = await api.joomla.users.get('456');
-const userDoc = await api.joomla.users.getDoc('456');
-
-// Create new user
-const newUser = await api.joomla.users.create({
-  username: 'newuser',
-  email: 'user@example.com',
-  name: 'New User',
-  password: 'securepassword'
-});
-
-// Update user
-const updatedUser = await api.joomla.users.update('456', {
-  email: 'newemail@example.com'
-});
-
-// Block/unblock user
-await api.joomla.users.block('456');
-
-// User Groups
-const userGroups = await api.joomla.users.groups.list('456', {
-  limit: 10,
-  edgeCache: 4  // Cache group memberships for 4 hours
-});
-
-const groupMapping = await api.joomla.users.groups.createMapping('456', {
-  groupId: 789
-});
-
-// System Groups
-const allGroups = await api.joomla.userGroups.list({
-  orderBy: 'title|ASC',
-  parentIdList: '1,2',
-  edgeCache: 8  // Cache group hierarchy for 8 hours
-});
-
-const groupDetails = await api.joomla.userGroups.get('789');
-
-// Tags
-const tags = await api.joomla.tags.list({
-  categoryId: 1,
-  parentId: 0,
-  q: 'tech',
-  limit: 50,
-  edgeCache: 6  // Cache tags for 6 hours
-});
-
-// Authentication
-const authResult = await api.joomla.users.verifyPassword({
-  username: 'user@example.com',
-  password: 'userpassword',
-  siteId: 'optional-cross-site-id'  // For cross-site auth when using augur_info
-});
-
-if (authResult.data.isVerified) {
-  console.log('User authenticated:', authResult.data.username);
-  console.log('User ID:', authResult.data.id);
-  console.log('JWT Token:', authResult.data.token);
-}
-
-// Health Check
-const health = await api.joomla.getHealthCheck();
-```
-
-#### Commerce Service
-
-```typescript
-// Cart Management
-const carts = await api.commerce.cartHeaders.list({
-  userId: 123,
-  edgeCache: 1  // Cache cart data for 1 hour max
-});
-
-const cart = await api.commerce.cartHeaders.lookup({
-  userId: 123,
-  customerId: 456,
-  contactId: 789
-});
-
-const cartLines = await api.commerce.cartLines.get(cart.data.cart_hdr_uid);
-
-// Product Recommendations
-const alsoBought = await api.commerce.alsoBought.get({
-  itemId: 'WIRE-123',
-  customerId: 12345,
-  edgeCache: 6  // Cache recommendations for 6 hours
-});
-
-// Checkout Operations
-const checkout = await api.commerce.checkout.get(checkoutUid, {
-  edgeCache: 2  // Cache checkout data for 2 hours
-});
-
-const checkoutDoc = await api.commerce.checkout.getDoc(checkoutUid, {
-  cartHdrUid: cart.data.cart_hdr_uid,
-  edgeCache: 4  // Cache checkout documents for 4 hours
-});
-
-// Health Check
-const health = await api.commerce.getHealthCheck();
-```
-
-#### Pricing Service
-
-```typescript
-// Price Engine
-const pricing = await api.pricing.getPrice({
-  customerId: 12345,
-  itemId: 'ITEM-001',
-  quantity: 10,
-  shipToId: 'SHIP-001',      // Optional
-  unitOfMeasure: 'EA',       // Optional
-  edgeCache: 3  // Cache standard pricing for 3 hours
-});
-
-// Job Price Management
-const jobPriceHeaders = await api.pricing.jobPriceHeaders.list({
-  limit: 20,
-  orderBy: 'job_price_hdr_uid|DESC',
-  edgeCache: 4  // Cache job listings for 4 hours
-});
-
-const jobPriceHeader = await api.pricing.jobPriceHeaders.get(12345);
-
-const jobPriceLines = await api.pricing.jobPriceLines.list(12345, {
-  limit: 50,
-  edgeCache: 4  // Cache price lines for 4 hours
-});
-
-const jobPriceLine = await api.pricing.jobPriceLines.get(12345, 67890);
-
-// Tax Engine
-const taxCalculation = await api.pricing.calculateTax({
-  customer_id: 12345,
-  ship_to_id: 'SHIP-001',
-  items: [
-    {
-      item_id: 'ITEM-001',
-      quantity: 10,
-      unit_price: 25.50,
-      extended_price: 255.00
-    }
-  ],
-  addresses: {
-    origin: {
-      street: '123 Main St',
-      city: 'Anytown',
-      state: 'CA',
-      zip: '90210'
-    },
-    destination: {
-      street: '456 Oak Ave',
-      city: 'Other City',
-      state: 'NY',
-      zip: '10001'
-    }
-  },
-  edgeCache: 1  // Cache tax calculations for 1 hour
-});
-
-// Health Checks
-const ping = await api.pricing.ping();
-const health = await api.pricing.getHealthCheck();
-```
-
-#### VMI (Vendor Managed Inventory) Service
-
-```typescript
-// Warehouse Management
-const warehouses = await api.vmi.warehouses.list({
-  customerId: 12345,
-  limit: 10,
-  q: 'distribution',
-  usersId: 456,
-  edgeCache: 4  // Cache warehouse data for 4 hours
-});
-
-const warehouse = await api.vmi.warehouses.get(123);
-
-const newWarehouse = await api.vmi.warehouses.create({
-  warehouse_name: 'New Distribution Center',
-  warehouse_desc: 'Primary warehouse for west coast operations',
-  customer_id: 12345,
-  inv_profile_hdr_uid: 1
-});
-
-const updatedWarehouse = await api.vmi.warehouses.update(123, {
-  warehouse_name: 'Updated Warehouse Name'
-});
-
-// Enable/disable warehouse
-await api.vmi.warehouses.enable(123, { status_cd: 704 }); // Enable
-await api.vmi.warehouses.enable(123, { status_cd: 705 }); // Disable
-
-// Inventory Operations
-const availability = await api.vmi.invProfileHdr.checkAvailability(123, {
-  q: 'wire'  // Search for items containing 'wire'
-});
-
-// Adjust inventory (sets absolute values)
-await api.vmi.invProfileHdr.adjust(123, {
-  adjustments: [
-    {
-      inv_mast_uid: 456,
-      qty_on_hand: 200.0,
-      reason: 'Physical count adjustment'
-    }
-  ]
-});
-
-// Receive inventory
-await api.vmi.invProfileHdr.receive(123, {
-  receipts: [
-    {
-      inv_mast_uid: 456,
-      qty_received: 50.0,
-      po_number: 'PO-2024-001',
-      lot_number: 'LOT-456'
-    }
-  ]
-});
-
-// Get replenishment information
-const replenishment = await api.vmi.invProfileHdr.getReplenishmentInfo(123, {
-  distributorsUid: 789,
-  edgeCache: 2  // Cache replenishment info for 2 hours
-});
-
-// Execute replenishment
-await api.vmi.invProfileHdr.replenish(123, {
-  distributor_uid: 789,
-  restock_items: [
-    { inv_mast_uid: 456, qty_to_order: 100.0 }
-  ]
-});
-
-// Transfer inventory between warehouses
-await api.vmi.invProfileHdr.transfer(123, {
-  to_warehouse_uid: 124,
-  transfers: [
-    {
-      inv_mast_uid: 456,
-      qty_to_transfer: 25.0,
-      reason: 'Stock balancing'
-    }
-  ]
-});
-
-// Record inventory usage (with warranty tracking)
-await api.vmi.invProfileHdr.recordUsage(123, {
-  job_description: 'Office Renovation - Building A',
-  department: 'Facilities',
-  usage_items: [
-    {
-      inv_mast_uid: 456,
-      inv_profile_line_type: 'prophet21',
-      qty_used: 5.0
-    },
-    {
-      inv_mast_uid: 789,
-      inv_profile_line_type: 'products',
-      qty_used: 2.0,
-      warranty: {
-        model_no: 'MDL-123',
-        serial_no: 'SN-456789',
-        warranty_type: 'Standard',
-        notes: 'Installed in conference room'
-      }
-    }
-  ]
-});
-
-// Distributor Management
-const distributors = await api.vmi.distributors.list({
-  customerId: 12345,
-  statusCd: 704,  // Active distributors only
-  edgeCache: 8  // Cache distributor data for 8 hours
-});
-
-const distributor = await api.vmi.distributors.get(789);
-
-const newDistributor = await api.vmi.distributors.create({
-  distributor_name: 'ABC Supply Co',
-  distributor_desc: 'Primary electrical supplier',
-  customer_id: 12345,
-  contact_email: 'orders@abcsupply.com',
-  contact_phone: '555-1234'
-});
-
-// Product Management
-const products = await api.vmi.products.find({
-  customerId: 12345,
-  prefix: 'WIRE',
-  edgeCache: 6  // Cache product catalogs for 6 hours
-});
-
-const productList = await api.vmi.products.list({
-  customerId: 12345,
-  distributorsUid: 789,
-  prefix: 'WIRE',
-  limit: 20,
-  edgeCache: 6
-});
-
-// Health Monitoring
-const ping = await api.vmi.health.ping();
-const health = await api.vmi.health.check();
-```
-
-#### OpenSearch Service
-
-```typescript
-// Item Search
-const searchResults = await api.opensearch.itemSearch.search({
-  q: 'electrical wire 12 AWG',
-  searchType: 'query',          // 'query' | 'similarity'
-  size: 20,
-  operator: 'AND',              // 'AND' | 'OR'
-  itemCategoryUidList: '123,456,789',
-  filters: JSON.stringify([
-    { attributeUid: 123, attributeValueUid: 456 }
-  ]),
-  edgeCache: 2  // Cache search results for 2 hours
-});
-
-// Similarity search for recommendations
-const similarItems = await api.opensearch.itemSearch.search({
-  q: 'CAT5e network cable 100ft blue',
-  searchType: 'similarity',
-  size: 15,
-  edgeCache: 4  // Cache similarity results for 4 hours
-});
-
-// Get search facets for filtering
-const attributes = await api.opensearch.itemSearch.getAttributes({
-  q: 'LED bulbs',
-  searchType: 'query',
-  edgeCache: 6  // Cache facet structure for 6 hours
-});
-
-// Items Management
-const items = await api.opensearch.items.list({
-  itemId: 'WIRE',     // Prefix filter
-  online: 'Y',        // Only online items
-  statusCd: 704,      // Active items only
-  limit: 100,
-  offset: 0,
-  edgeCache: 3  // Cache item data for 3 hours
-});
-
-const itemDetail = await api.opensearch.items.get(123456);
-
-// Index management operations (no caching for real-time operations)
-const refreshResult = await api.opensearch.items.refresh(123456);
-const updateResult = await api.opensearch.items.update(123456);
-const batchRefresh = await api.opensearch.items.refreshAll();
-
-// Health Monitoring
-const ping = await api.opensearch.health.ping();
-const health = await api.opensearch.health.check();
-```
-
-#### Items Service
-
-```typescript
-// Inventory Master Records
-const itemDetails = await api.items.invMast.get(invMastUid);
-
-// Document retrieval for invMast records
-const itemDoc = await api.items.invMast.doc.get(invMastUid, {
-  q: 'optional-query-pattern'  // Search pattern for document filtering
-});
-
-// Special lookup pattern: Find invMastUid by itemId
-// When you only have an itemId but need the invMastUid, use invMastUid = 0
-// and provide the itemId as the query pattern. This will look up the itemId
-// and return the full document including the correct invMastUid.
-const itemByItemId = await api.items.invMast.doc.get(0, {
-  q: 'YOUR-ITEM-ID'  // Replace with actual itemId (e.g., 'WIRE-12-AWG-250FT')
-});
-// Response includes the actual invMastUid for future direct lookups
-
-// Categories and attributes
-const categories = await api.items.categories.list({
-  limit: 50,
-  edgeCache: 8  // Categories rarely change
-});
-
-// Product locations and bins
-const locations = await api.items.invMast.locations.list(invMastUid);
-const bins = await api.items.invMast.locations.bins.list(invMastUid, locationId);
-
-// Alternate codes and variants
-const alternates = await api.items.invMast.alternateCode.list(invMastUid);
-const variants = await api.items.variants.list({
-  invMastUid: invMastUid,
-  edgeCache: 4  // Variants change occasionally
-});
-
-// Attributes and values
-const attributes = await api.items.attributes.list({
-  edgeCache: 6  // Attribute structure is relatively stable
-});
-
-const attributeValues = await api.items.attributes.values.list(attributeUid);
-
-// Brands and product links
-const brands = await api.items.brands.list({
-  edgeCache: 8  // Brand data is very stable
-});
-
-const productLinks = await api.items.productLinks.list({
-  invMastUid: invMastUid,
-  edgeCache: 2  // Product links may change
-});
-
-// Health Monitoring
-const ping = await api.items.ping();
-const health = await api.items.healthCheck.get();
-```
-
-### Response Format
-
-All Augur microservices follow a unified response pattern:
-
-```typescript
-interface BaseResponse<T> {
-  status: number;           // HTTP status code (200 for success)
-  message?: string;         // Status message (optional - omitted in health checks)
-  data: T;                  // Response data of type T
-  totalResults?: number;    // Total count (optional - present in paginated responses)
-  count?: number;           // Item count (optional - present in some responses)
-  options?: Array<Record<string, unknown>>; // Optional array of key-value pairs
-}
-
-// Example response
-const usersResponse = await api.joomla.users.list({ limit: 10 });
-// usersResponse = {
-//   status: 200,
-//   message: "Ok", 
-//   data: [...users...],
-//   totalResults: 150
-// }
-
-// Access the actual data
-const users = usersResponse.data;
-const totalCount = usersResponse.totalResults;
-```
-
-#### Important: Query Parameter Handling
-
-HTTP query parameters are always transmitted as strings. The library uses Zod's coercion to automatically handle numeric parameters:
-
-```typescript
-// You pass numbers
-await api.customers.customer.orders.list(12345, {
-  limit: 10,    // number
-  offset: 0     // number
-});
-
-// They become strings in the URL: ?limit=10&offset=0
-// The API might echo them back as strings
-// But Zod coercion handles this automatically!
-```
-
-### HTTP Methods and URL Patterns
-
-| Method | Pattern | Client Method | Example |
-|--------|---------|---------------|---------|
-| GET | `/users` | `listUsers()` | List multiple resources |
-| GET | `/user/{id}` | `getUser()` | Get single resource |
-| POST | `/user` | `createUser()` | Create new resource |
-| PUT | `/user/{id}` | `updateUser()` | Update existing resource |
-| DELETE | `/user/{id}` | `deleteUser()` | Delete resource |
-
-### Error Handling
-
-```typescript
-import { 
-  AugurAPIError,
-  AuthenticationError, 
-  ValidationError,
-  NotFoundError,
-  RateLimitError 
-} from '@simpleapps-com/augur-api';
-
-try {
-  const user = await api.joomla.users.get('user-id');
-} catch (error) {
-  if (error instanceof AuthenticationError) {
-    console.error('Authentication failed:', error.message);
-    // Handle auth error - refresh token or redirect to login
-    
-  } else if (error instanceof ValidationError) {
-    console.error('Request validation failed:', error.validationErrors);
-    // Handle validation errors - check request parameters
-    
-  } else if (error instanceof NotFoundError) {
-    console.error('Resource not found:', error.message);
-    // Handle not found - show user-friendly message
-    
-  } else if (error instanceof RateLimitError) {
-    console.error('Rate limit exceeded:', error.message);
-    // Handle rate limiting - implement backoff strategy
-    
-  } else if (error instanceof AugurAPIError) {
-    console.error('API error:', error.code, error.message);
-    // Handle other API errors
-  }
-}
-```
-
-## Advanced Features
-
-💡 **[Complete Tips and Tricks Guide](./TIPS-AND-TRICKS.md)** - Comprehensive advanced patterns including edge caching, request cancellation, middleware integration, framework integrations, and error handling strategies.
-
-**Quick Advanced Features:**
-- **Edge Caching**: Built-in Cloudflare caching with configurable TTL (1-8 hours)
-- **Request Cancellation**: AbortController support for request timeout
-- **Custom Headers**: Per-request configuration and timeouts  
-- **Batch Operations**: Parallel request execution with Promise.all
-- **Middleware**: Global request/response/error interceptors
-
-## Integration Guides
-
-💡 **[Complete Framework Integration Examples](./TIPS-AND-TRICKS.md#-framework-integration-patterns)** - Detailed React, Next.js, React Native, and Node.js integration patterns with custom hooks, error handling, and best practices.
-
-**Quick Integration Examples:**
-- **React**: Custom `useAugurAPI()` hook with context-aware API creation
-- **Next.js**: Server-side API routes with proper caching and error handling  
-- **React Native**: AsyncStorage integration for offline-first patterns
-- **Node.js**: Service layer integration with middleware and monitoring
-
-## Framework-Specific Features
-
-### React/Next.js
-```typescript
-// Context-aware API creation
-const api = AugurAPI.fromContext(context);
-
-// Custom hook pattern  
-const { api, isReady } = useAugurAPI();
-```
-
-### Error Handling Integration
-```typescript
-// Framework-agnostic error handling
-try {
-  const result = await api.joomla.users.list({ limit: 10 });
-} catch (error) {
-  ErrorHandler.handle(error, 'UserList Component');
-}
-```
-
-## Error Handling
-
-💡 **[Complete Error Handling Guide](./TIPS-AND-TRICKS.md#️-advanced-error-handling)** - Comprehensive error handling patterns including retry logic, exponential backoff, global error handlers, and framework-specific error boundaries.
-
-**Quick Error Types:**
-```typescript
-import { 
-  AugurAPIError,           // Base error class
-  AuthenticationError,     // 401 errors
-  ValidationError,         // Request validation failures
-  NotFoundError,          // 404 errors
-  RateLimitError,         // 429 errors
-  NetworkError            // Network/connectivity issues
-} from '@simpleapps-com/augur-api';
-
-// Custom hook for Augur API - Context-aware approach
-function useAugurAPI(context?: AugurContext) {
-  const [api] = useState(() => {
-    if (context) {
-      // Use context-aware creation (recommended)
-      return AugurAPI.fromContext(context);
-    }
-    
-    // Fallback to manual configuration
-    return new AugurAPI({
-      siteId: process.env.REACT_APP_AUGUR_SITE_ID!,
-      bearerToken: getStoredToken()
-    });
-  });
-  
-  return api;
-}
-
-// Component using the API
-const UserList: React.FC = () => {
-  const api = useAugurAPI();
-  const [users, setUsers] = useState<User[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-
-  useEffect(() => {
-    async function fetchUsers() {
-      try {
-        setLoading(true);
-        setError(null);
-        
-        const response = await api.joomla.users.list({ 
-          limit: 50,
-          edgeCache: 2  // Cache for 2 hours
-        });
-        
-        setUsers(response.data);
-      } catch (err) {
-        if (err instanceof AugurAPIError) {
-          setError(`API Error: ${err.message}`);
-        } else {
-          setError('An unexpected error occurred');
-        }
-      } finally {
-        setLoading(false);
-      }
-    }
-
-    fetchUsers();
-  }, [api]);
-
-  if (loading) return <div>Loading users...</div>;
-  if (error) return <div>Error: {error}</div>;
-
-  return (
-    <div>
-      <h2>Users ({users.length})</h2>
-      <ul>
-        {users.map(user => (
-          <li key={user.id}>
-            {user.name} ({user.username}) - {user.email}
-          </li>
-        ))}
-      </ul>
-    </div>
-  );
-};
-
-export default UserList;
-```
-
-### React Native Integration
-
-```typescript
-import { AugurAPI } from '@simpleapps-com/augur-api';
-import AsyncStorage from '@react-native-async-storage/async-storage';
-
-class AugurService {
-  private api: AugurAPI;
-
-  constructor() {
-    this.api = new AugurAPI({
-      siteId: 'your-site-id',
-      bearerToken: '', // Will be set after loading from storage
-    });
-    
-    this.loadCredentials();
-  }
-
-  private async loadCredentials() {
-    try {
-      const token = await AsyncStorage.getItem('augur_token');
-      const siteId = await AsyncStorage.getItem('augur_site_id');
-      
-      if (token) this.api.setAuthToken(token);
-      if (siteId) this.api.setSiteId(siteId);
-    } catch (error) {
-      console.error('Failed to load credentials:', error);
-    }
-  }
-
-  async login(username: string, password: string): Promise<boolean> {
-    try {
-      const response = await this.api.joomla.users.verifyPassword({
-        username,
-        password
-      });
-
-      if (response.data.isVerified && response.data.token) {
-        await AsyncStorage.setItem('augur_token', response.data.token);
-        this.api.setAuthToken(response.data.token);
-        return true;
-      }
-    } catch (error) {
-      console.error('Login failed:', error);
-    }
-    
-    return false;
-  }
-
-  async getProducts(searchTerm: string) {
-    return this.api.opensearch.itemSearch.search({
-      q: searchTerm,
-      searchType: 'query',
-      size: 20,
-      edgeCache: 3  // Cache search results
-    });
-  }
-
-  async logout() {
-    await AsyncStorage.multiRemove(['augur_token', 'augur_site_id']);
-    this.api.setAuthToken('');
-  }
-}
-
-export const augurService = new AugurService();
-```
-
-### Next.js Integration
-
-```typescript
-// lib/augur.ts
-import { AugurAPI } from '@simpleapps-com/augur-api';
-
-// Server-side API instance
-export function createServerAPI() {
-  return new AugurAPI({
-    siteId: process.env.AUGUR_SITE_ID!,
-    bearerToken: process.env.AUGUR_SERVICE_TOKEN!, // Service token for server-side
-  });
-}
-
-// Client-side API instance
-export function createClientAPI(userToken: string) {
-  return new AugurAPI({
-    siteId: process.env.NEXT_PUBLIC_AUGUR_SITE_ID!,
-    bearerToken: userToken, // User token for client-side
-  });
-}
-
-// pages/api/products/search.ts
-import type { NextApiRequest, NextApiResponse } from 'next';
-import { createServerAPI } from '../../../lib/augur';
-
-export default async function handler(
-  req: NextApiRequest,
-  res: NextApiResponse
-) {
-  if (req.method !== 'GET') {
-    return res.status(405).json({ error: 'Method not allowed' });
-  }
-
-  const { q } = req.query;
-  if (!q || typeof q !== 'string') {
-    return res.status(400).json({ error: 'Search query required' });
-  }
-
-  try {
-    const api = createServerAPI();
-    const searchResults = await api.opensearch.itemSearch.search({
-      q,
-      searchType: 'query',
-      size: 20,
-      edgeCache: 4  // Cache search results for 4 hours
-    });
-
-    res.status(200).json(searchResults);
-  } catch (error) {
-    console.error('Search failed:', error);
-    res.status(500).json({ error: 'Search failed' });
-  }
-}
-
-// pages/products.tsx
-import { GetServerSideProps } from 'next';
-import { createServerAPI } from '../lib/augur';
-import type { ItemSearchResponse } from '@simpleapps-com/augur-api';
-
-interface ProductsPageProps {
-  initialProducts: ItemSearchResponse;
-}
-
-export default function ProductsPage({ initialProducts }: ProductsPageProps) {
-  return (
-    <div>
-      <h1>Products</h1>
-      <div>
-        {initialProducts.data.items.map(item => (
-          <div key={item.inv_mast_uid}>
-            {item.item_id} - {item.item_desc}
-          </div>
-        ))}
-      </div>
-    </div>
-  );
-}
-
-export const getServerSideProps: GetServerSideProps = async () => {
-  try {
-    const api = createServerAPI();
-    const products = await api.opensearch.itemSearch.search({
-      q: 'electrical',
-      searchType: 'query',
-      size: 20,
-      edgeCache: 6  // Cache for 6 hours
-    });
-
-    return {
-      props: {
-        initialProducts: products,
-      },
-    };
-  } catch (error) {
-    console.error('Failed to fetch products:', error);
-    return {
-      props: {
-        initialProducts: { data: { items: [] }, status: 500 },
-      },
-    };
-  }
-};
-```
-
-### Node.js Service Integration
-
-```typescript
-// services/AugurService.ts
-import { AugurAPI, AugurAPIError } from '@simpleapps-com/augur-api';
-
-export class AugurService {
-  private api: AugurAPI;
-
-  constructor() {
-    const siteId = process.env.AUGUR_SITE_ID;
-    const bearerToken = process.env.AUGUR_SERVICE_TOKEN;
-
-    if (!siteId || !bearerToken) {
-      throw new Error('Augur credentials not configured');
-    }
-
-    this.api = new AugurAPI({
-      siteId,
-      bearerToken,
-      timeout: 30000,
-      retries: 3,
-      retryDelay: 1000,
-      
-      // Add comprehensive logging
-      onRequest: (config) => {
-        console.log(`[Augur] ${config.method?.toUpperCase()} ${config.url}`, {
-          headers: config.headers,
-          params: config.params
-        });
-        return config;
-      },
-      
-      onResponse: (response) => {
-        console.log(`[Augur] Response ${response.status}`, {
-          url: response.config?.url,
-          cached: response.headers?.['cf-cache-status'] === 'HIT'
-        });
-        return response;
-      },
-      
-      onError: (error) => {
-        if (error instanceof AugurAPIError) {
-          console.error(`[Augur] API Error ${error.code}:`, {
-            message: error.message,
-            service: error.service,
-            endpoint: error.endpoint,
-            statusCode: error.statusCode
-          });
-        }
-        throw error;
-      }
-    });
-  }
-
-  // User management
-  async getUsers(limit = 50) {
-    return this.api.joomla.users.list({ 
-      limit,
-      edgeCache: 2 
-    });
-  }
-
-  async getUserById(id: string) {
-    return this.api.joomla.users.get(id);
-  }
-
-  // Product search
-  async searchProducts(query: string, size = 20) {
-    return this.api.opensearch.itemSearch.search({
-      q: query,
-      searchType: 'query',
-      size,
-      edgeCache: 3
-    });
-  }
-
-  // Inventory management
-  async getWarehouseInventory(warehouseId: number, searchTerm?: string) {
-    return this.api.vmi.invProfileHdr.checkAvailability(warehouseId, {
-      q: searchTerm
-    });
-  }
-
-  async replenishInventory(warehouseId: number, items: Array<{
-    inv_mast_uid: number;
-    qty_to_order: number;
-  }>) {
-    return this.api.vmi.invProfileHdr.replenish(warehouseId, {
-      distributor_uid: 1, // Default distributor
-      restock_items: items
-    });
-  }
-
-  // Pricing
-  async getProductPrice(customerId: number, itemId: string, quantity: number) {
-    return this.api.pricing.getPrice({
-      customerId,
-      itemId,
-      quantity,
-      edgeCache: 3  // Cache pricing for 3 hours
-    });
-  }
-
-  // Health monitoring
-  async checkAllServices() {
-    const services = [
-      'joomla', 'commerce', 'pricing', 'vmi', 'opensearch',
-      'items', 'customers', 'orders', 'payments'
-    ];
-
-    const healthChecks = await Promise.allSettled(
-      services.map(async (service) => {
-        try {
-          // Different services have different health check methods
-          let health;
-          if (service === 'vmi') {
-            health = await this.api.vmi.health.check();
-          } else if (service === 'opensearch') {
-            health = await this.api.opensearch.health.check();
-          } else {
-            health = await (this.api as any)[service].getHealthCheck();
-          }
-          
-          return { service, status: 'healthy', data: health };
-        } catch (error) {
-          return { 
-            service, 
-            status: 'unhealthy', 
-            error: error instanceof Error ? error.message : 'Unknown error' 
-          };
-        }
-      })
-    );
-
-    return healthChecks.map((result, index) => ({
-      service: services[index],
-      ...(result.status === 'fulfilled' ? result.value : result.reason)
-    }));
-  }
-}
-
-// Usage in Express.js app
-import express from 'express';
-import { AugurService } from './services/AugurService';
-
-const app = express();
-const augurService = new AugurService();
-
-// Get users endpoint
-app.get('/api/users', async (req, res) => {
-  try {
-    const users = await augurService.getUsers();
-    res.json(users);
-  } catch (error) {
-    console.error('Failed to fetch users:', error);
-    res.status(500).json({ error: 'Failed to fetch users' });
-  }
-});
-
-// Product search endpoint
-app.get('/api/products/search', async (req, res) => {
-  const { q } = req.query;
-  if (!q || typeof q !== 'string') {
-    return res.status(400).json({ error: 'Search query required' });
-  }
-
-  try {
-    const products = await augurService.searchProducts(q);
-    res.json(products);
-  } catch (error) {
-    console.error('Product search failed:', error);
-    res.status(500).json({ error: 'Product search failed' });
-  }
-});
-
-// Health check endpoint
-app.get('/api/health', async (req, res) => {
-  try {
-    const healthStatus = await augurService.checkAllServices();
-    const allHealthy = healthStatus.every(service => service.status === 'healthy');
-    
-    res.status(allHealthy ? 200 : 503).json({
-      status: allHealthy ? 'healthy' : 'degraded',
-      services: healthStatus,
-      timestamp: new Date().toISOString()
-    });
-  } catch (error) {
-    console.error('Health check failed:', error);
-    res.status(500).json({ 
-      status: 'error', 
-      error: 'Health check failed' 
-    });
-  }
-});
-
-app.listen(3000, () => {
-  console.log('Server running on port 3000');
-});
-```
-
-### Electron Integration
-
-```typescript
-// main/services/AugurService.ts
-import { AugurAPI } from '@simpleapps-com/augur-api';
-import { app } from 'electron';
-import path from 'path';
-import fs from 'fs';
-
-export class ElectronAugurService {
-  private api: AugurAPI;
-  private configPath: string;
-
-  constructor() {
-    this.configPath = path.join(app.getPath('userData'), 'augur-config.json');
-    this.api = this.initializeAPI();
-  }
-
-  private initializeAPI(): AugurAPI {
-    const config = this.loadConfig();
-    
-    return new AugurAPI({
-      siteId: config.siteId,
-      bearerToken: config.bearerToken,
-      
-      // Electron-specific configuration
-      timeout: 45000,  // Longer timeout for desktop app
-      
-      onRequest: (config) => {
-        console.log(`[Augur Desktop] ${config.method} ${config.url}`);
-        return config;
-      },
-      
-      onError: (error) => {
-        // Show desktop notification for errors
-        this.showErrorNotification(error.message);
-        throw error;
-      }
-    });
-  }
-
-  private loadConfig() {
-    try {
-      if (fs.existsSync(this.configPath)) {
-        return JSON.parse(fs.readFileSync(this.configPath, 'utf8'));
-      }
-    } catch (error) {
-      console.error('Failed to load config:', error);
-    }
-    
-    // Default configuration
-    return {
-      siteId: process.env.AUGUR_SITE_ID || '',
-      bearerToken: process.env.AUGUR_BEARER_TOKEN || ''
-    };
-  }
-
-  saveConfig(config: { siteId: string; bearerToken: string }) {
-    try {
-      fs.writeFileSync(this.configPath, JSON.stringify(config, null, 2));
-      this.api.setSiteId(config.siteId);
-      this.api.setAuthToken(config.bearerToken);
-    } catch (error) {
-      console.error('Failed to save config:', error);
-      throw error;
-    }
-  }
-
-  private showErrorNotification(message: string) {
-    // Implementation depends on your notification system
-    console.error('Augur API Error:', message);
-  }
-
-  // Exposed API methods
-  async getUsers() {
-    return this.api.joomla.users.list({ 
-      limit: 100,
-      edgeCache: 2 
-    });
-  }
-
-  async searchProducts(query: string) {
-    return this.api.opensearch.itemSearch.search({
-      q: query,
-      searchType: 'query',
-      size: 50,
-      edgeCache: 4
-    });
-  }
-
-  async getWarehouseData() {
-    return this.api.vmi.warehouses.list({
-      customerId: 12345,
-      edgeCache: 4
-    });
-  }
-}
-
-// renderer/hooks/useAugur.ts
-import { useEffect, useState } from 'react';
-
-export function useAugur() {
-  const [augurService, setAugurService] = useState(null);
-
-  useEffect(() => {
-    // Get service from main process via IPC
-    window.electronAPI.getAugurService().then(setAugurService);
-  }, []);
-
-  return augurService;
-}
-```
-
-## Error Handling
-
-### Error Types
-
-The library provides specific error types for different failure scenarios:
-
-```typescript
-import { 
-  AugurAPIError,           // Base error class
-  AuthenticationError,     // 401 errors
-  ValidationError,        // Request validation failures
-  NotFoundError,          // 404 errors
-  RateLimitError,         // 429 errors
-  NetworkError            // Network/connectivity issues
-} from '@simpleapps-com/augur-api';
-```
-
-### Comprehensive Error Handling
-
-```typescript
-async function handleAPICall() {
-  try {
-    const result = await api.joomla.users.list({ limit: 10 });
-    return result;
-    
-  } catch (error) {
-    // Handle specific error types
-    if (error instanceof AuthenticationError) {
-      console.error('Authentication failed:', error.message);
-      
-      // Specific auth error scenarios
-      switch (error.statusCode) {
-        case 401:
-          // Token expired or invalid
-          await refreshToken();
-          break;
-        default:
-          redirectToLogin();
-      }
-      
-    } else if (error instanceof ValidationError) {
-      console.error('Request validation failed:', error.validationErrors);
-      
-      // Handle field-specific validation errors
-      error.validationErrors?.forEach(validationError => {
-        console.error(`Field ${validationError.path}: ${validationError.message}`);
-      });
-      
-    } else if (error instanceof NotFoundError) {
-      console.error('Resource not found:', error.message);
-      
-      // Show user-friendly not found message
-      showNotFoundMessage(error.endpoint);
-      
-    } else if (error instanceof RateLimitError) {
-      console.error('Rate limit exceeded:', error.message);
-      
-      // Implement exponential backoff
-      await new Promise(resolve => setTimeout(resolve, 2000));
-      return handleAPICall(); // Retry
-      
-    } else if (error instanceof AugurAPIError) {
-      console.error('API error:', {
-        code: error.code,
-        message: error.message,
-        service: error.service,
-        endpoint: error.endpoint,
-        statusCode: error.statusCode,
-        requestId: error.requestId
-      });
-      
-      // Handle by status code
-      switch (error.statusCode) {
-        case 500:
-          showErrorMessage('Server error. Please try again later.');
-          break;
-        case 503:
-          showErrorMessage('Service temporarily unavailable.');
-          break;
-        default:
-          showErrorMessage(`API error: ${error.message}`);
-      }
-      
-    } else {
-      console.error('Unexpected error:', error);
-      showErrorMessage('An unexpected error occurred.');
-    }
-    
-    throw error; // Re-throw if needed
-  }
-}
-```
-
-### Retry Logic with Exponential Backoff
-
-```typescript
-async function apiCallWithRetry<T>(
-  operation: () => Promise<T>,
-  maxRetries = 3,
-  baseDelay = 1000
-): Promise<T> {
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    try {
-      return await operation();
-      
-    } catch (error) {
-      // Don't retry on authentication or validation errors
-      if (error instanceof AuthenticationError || 
-          error instanceof ValidationError) {
-        throw error;
-      }
-      
-      // Don't retry on final attempt
-      if (attempt === maxRetries) {
-        throw error;
-      }
-      
-      // Calculate delay with exponential backoff
-      const delay = baseDelay * Math.pow(2, attempt - 1);
-      console.log(`Attempt ${attempt} failed, retrying in ${delay}ms...`);
-      
-      await new Promise(resolve => setTimeout(resolve, delay));
-    }
-  }
-  
-  throw new Error('All retry attempts exhausted');
-}
-
-// Usage
-const users = await apiCallWithRetry(() => 
-  api.joomla.users.list({ limit: 10 })
-);
-```
-
-### Global Error Handler
-
-```typescript
-class ErrorHandler {
-  static handle(error: unknown, context?: string): void {
-    const contextPrefix = context ? `[${context}] ` : '';
-    
-    if (error instanceof AuthenticationError) {
-      console.error(`${contextPrefix}Authentication failed:`, error.message);
-      this.handleAuthError(error);
-      
-    } else if (error instanceof ValidationError) {
-      console.error(`${contextPrefix}Validation failed:`, error.validationErrors);
-      this.handleValidationError(error);
-      
-    } else if (error instanceof AugurAPIError) {
-      console.error(`${contextPrefix}API error:`, {
-        service: error.service,
-        endpoint: error.endpoint,
-        code: error.code,
-        message: error.message
-      });
-      this.handleAPIError(error);
-      
-    } else {
-      console.error(`${contextPrefix}Unexpected error:`, error);
-      this.handleUnknownError(error);
-    }
-  }
-
-  private static handleAuthError(error: AuthenticationError): void {
-    // Implement auth error handling
-    if (typeof window !== 'undefined') {
-      // Browser environment
-      localStorage.removeItem('authToken');
-      window.location.href = '/login';
-    } else {
-      // Node.js environment
-      process.exit(1);
-    }
-  }
-
-  private static handleValidationError(error: ValidationError): void {
-    // Show validation errors to user
-    console.error('Please check your input:', error.validationErrors);
-  }
-
-  private static handleAPIError(error: AugurAPIError): void {
-    // Handle different API error codes
-    switch (error.code) {
-      case 'RATE_LIMIT_EXCEEDED':
-        console.log('Please wait before making more requests');
-        break;
-      case 'SERVICE_UNAVAILABLE':
-        console.log('Service is temporarily unavailable');
-        break;
-      default:
-        console.log(`Service error: ${error.message}`);
-    }
-  }
-
-  private static handleUnknownError(error: unknown): void {
-    console.error('An unexpected error occurred:', error);
-  }
-}
-
-// Use in API calls
-try {
-  const result = await api.joomla.users.list();
-} catch (error) {
-  ErrorHandler.handle(error, 'UserList');
-}
-```
-
-## Configuration
-
-### Basic Configuration
-
-```typescript
-import { AugurAPI } from '@simpleapps-com/augur-api';
-
-const api = new AugurAPI({
-  // Required
-  siteId: 'your-site-id',
-  
-  // Authentication (required for most endpoints)
-  bearerToken: 'your-jwt-token',
-  
-  // Optional HTTP settings
-  timeout: 30000,           // Request timeout in ms (default: 30000)
-  retries: 3,              // Number of retries (default: 3)
-  retryDelay: 1000,        // Delay between retries in ms (default: 1000)
-  
-  
-  // Request/Response interceptors
-  onRequest: (config) => {
-    console.log('Making request:', config.url);
-    return config;
-  },
-  
-  onResponse: (response) => {
-    console.log('Received response:', response.status);
-    return response;
-  },
-  
-  onError: (error) => {
-    console.error('Request failed:', error.message);
-    throw error;
-  }
-});
-```
-
-### Environment-Based Configuration
-
-```typescript
-// config/augur.ts
-interface AugurConfig {
-  siteId: string;
-  bearerToken?: string;
-  timeout: number;
-  retries: number;
-}
-
-const environments = {
-  development: {
-    siteId: process.env.AUGUR_DEV_SITE_ID!,
-    bearerToken: process.env.AUGUR_DEV_TOKEN,
-    timeout: 45000,  // Longer timeout for dev
-    retries: 1,      // Fewer retries for faster feedback
-  },
-  
-  staging: {
-    siteId: process.env.AUGUR_STAGING_SITE_ID!,
-    bearerToken: process.env.AUGUR_STAGING_TOKEN,
-    timeout: 30000,
-    retries: 2,
-  },
-  
-  production: {
-    siteId: process.env.AUGUR_PROD_SITE_ID!,
-    bearerToken: process.env.AUGUR_PROD_TOKEN,
-    timeout: 30000,
-    retries: 3,
-  }
-} as const;
-
-export function getAugurConfig(): AugurConfig {
-  const env = process.env.NODE_ENV || 'development';
-  const config = environments[env as keyof typeof environments];
-  
-  if (!config) {
-    throw new Error(`No Augur configuration found for environment: ${env}`);
-  }
-  
-  if (!config.siteId) {
-    throw new Error(`Augur site ID not configured for environment: ${env}`);
-  }
-  
-  return config;
-}
-
-// Usage
-import { getAugurConfig } from './config/augur';
-
-const api = new AugurAPI(getAugurConfig());
-```
-
-### Configuration Validation
-
-```typescript
-import { z } from 'zod';
-
-const AugurConfigSchema = z.object({
-  siteId: z.string().min(1, 'Site ID is required'),
-  bearerToken: z.string().optional(),
-  timeout: z.number().positive().optional(),
-  retries: z.number().int().min(0).max(10).optional(),
-});
-
-export function createValidatedAugurAPI(config: unknown): AugurAPI {
-  const validatedConfig = AugurConfigSchema.parse(config);
-  return new AugurAPI(validatedConfig);
-}
-
-// Usage with validation
-try {
-  const api = createValidatedAugurAPI({
-    siteId: process.env.AUGUR_SITE_ID,
-    bearerToken: process.env.AUGUR_TOKEN,
-    timeout: 30000,
-    retries: 3
-  });
-} catch (error) {
-  if (error instanceof z.ZodError) {
-    console.error('Configuration validation failed:', error.errors);
-    process.exit(1);
-  }
-}
-```
-
-### Dynamic Configuration Updates
-
-```typescript
-class ManagedAugurAPI {
-  private api: AugurAPI;
-  private config: AugurConfig;
-
-  constructor(initialConfig: AugurConfig) {
-    this.config = initialConfig;
-    this.api = new AugurAPI(initialConfig);
-  }
-
-  updateConfig(newConfig: Partial<AugurConfig>): void {
-    this.config = { ...this.config, ...newConfig };
-    
-    // Update specific properties that can be changed at runtime
-    if (newConfig.bearerToken !== undefined) {
-      this.api.setAuthToken(newConfig.bearerToken);
-    }
-    
-    if (newConfig.siteId !== undefined) {
-      this.api.setSiteId(newConfig.siteId);
-    }
-    
-    // For other config changes, recreate the API instance
-    if (newConfig.timeout || newConfig.retries) {
-      this.api = new AugurAPI(this.config);
-    }
-  }
-
-  getAPI(): AugurAPI {
-    return this.api;
-  }
-
-  getCurrentConfig(): AugurConfig {
-    return { ...this.config };
-  }
-}
-
-// Usage
-const managedAPI = new ManagedAugurAPI({
-  siteId: 'initial-site',
-  bearerToken: 'initial-token'
-});
-
-// Update token after authentication
-managedAPI.updateConfig({
-  bearerToken: 'new-token-after-auth'
-});
-
-// Switch to different site
-managedAPI.updateConfig({
-  siteId: 'different-site',
-  bearerToken: 'site-specific-token'
-});
-```
-
-## Performance Optimization
-
-> 📋 **[Complete Performance Guide](./PERFORMANCE.md)** - Comprehensive strategies for edge caching, batch operations, pagination optimization, and performance monitoring.
-
-**Quick Performance Tips:**
-
-```typescript
-// ⚡ 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.invProfileHdr.checkAvailability(123, { edgeCache: 1 }); // Volatile: 1 hour
-
-// 🚀 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);
-  }
-}
-```
-
-**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
-/**
- * 🏢 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`);
-  }
-});
-```
-
-**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
-/**
- * 🏗️ MULTI-TENANT ARCHITECTURE PATTERNS
- * 
- * Choose the pattern that best fits your enterprise requirements:
- * - Shared Infrastructure, Isolated Data
- * - Complete Tenant Isolation  
- * - Hybrid Multi-Tenant Model
- */
-
-// 🏢 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)!;
-    }
-    
-    console.warn(`⚠️ Tenant ${tenantId} not initialized`);
-    return null;
-  }
-
-  // Get current tenant's API client
-  getCurrentAPI(): AugurAPI | null {
-    return this.currentTenant ? this.tenantAPIs.get(this.currentTenant) || null : null;
-  }
-
-  // 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;
-  }
-}
-
-// 🏢 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 authResult.success ? authResult.targetSiteAPI! : null;
-  }
-
-  // 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;
-  }
-}
-
-// 🏢 Pattern 3: Multi-Tenant Dashboard Implementation
-class MultiTenantDashboard {
-  private tenantManager = new TenantContextManager();
-  private tenantFactory: TenantAPIFactory;
-
-  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`);
-  }
-
-  // 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'
-});
-```
-
-### Security Configuration Best Practices
-
-**Secure your enterprise deployment** with comprehensive security measures:
-
-```typescript
-/**
- * 🔒 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',
-  };
-
-  // 🔑 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({
-      siteId: config.siteId,
-      
-      // Dynamic token provider with automatic rotation
-      get bearerToken() {
-        return currentToken;
-      },
-
-      // 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) => {
-        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;
-      }
-    });
-  }
-
-  // 🔐 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();
-
-      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' 
-        };
-      }
-    };
-  }
-}
-
-// 📊 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 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);
-  }
-});
-
-// 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
-
-```bash
-# Clone the repository
-git clone https://github.com/your-org/augur-api-client.git
-cd augur-api-client/packages/augur-api
-
-# Install dependencies
-npm install
-
-# Build the library
-npm run build
-
-# Run tests
-npm test
-
-# Run tests with coverage
-npm run test:coverage
-
-# Run E2E tests (requires API credentials)
-npm run test:e2e
-
-# Lint code
-npm run lint
-
-# Type check
-npm run typecheck
-```
-
-### Development Scripts
-
-```bash
-# Development workflow
-npm run dev          # Watch mode for development
-npm run test:watch   # Watch mode for tests
-npm run build:watch  # Watch mode for building
-
-# Code quality
-npm run lint:fix     # Auto-fix linting issues
-npm run format       # Format code with Prettier
-npm run format:check # Check code formatting
-
-# Release workflow
-npm run clean        # Clean build artifacts
-npm run prepublish   # Build and prepare for publishing
-```
-
-### Testing
-
-The library maintains 100% test coverage across all components:
-
-```typescript
-// Example test
-import { AugurAPI, AuthenticationError } from '../src';
-
-describe('AugurAPI', () => {
-  let api: AugurAPI;
-
-  beforeEach(() => {
-    api = new AugurAPI({
-      siteId: 'test-site',
-      bearerToken: 'test-token'
-    });
-  });
-
-  it('should create service clients lazily', () => {
-    // Service clients are created on first access
-    const joomla1 = api.joomla;
-    const joomla2 = api.joomla;
-    
-    expect(joomla1).toBe(joomla2); // Same instance
-  });
-
-  it('should reset clients when auth token changes', () => {
-    const joomla1 = api.joomla;
-    
-    api.setAuthToken('new-token');
-    
-    const joomla2 = api.joomla;
-    expect(joomla1).not.toBe(joomla2); // Different instances
-  });
-
-  it('should handle authentication errors', async () => {
-    // Mock failed authentication
-    mockAPI.joomla.users.list.mockRejectedValue(
-      new AuthenticationError({
-        message: 'Invalid token',
-        service: 'joomla',
-        endpoint: '/users'
-      })
-    );
-
-    await expect(api.joomla.users.list()).rejects.toThrow(AuthenticationError);
-  });
-});
-```
-
-
-### Code Generation
-
-The library uses code generation from Postman collections:
-
-```bash
-# Generate client code from Postman collections
-npm run generate:clients
-
-# Update schemas from API responses
-npm run generate:schemas
-
-# Generate TypeScript types
-npm run generate:types
-```
-
-### Contributing Guidelines
-
-1. **Follow TypeScript best practices**
-2. **Maintain 100% test coverage**
-3. **Add comprehensive JSDoc documentation**
-4. **Follow existing naming conventions**
-5. **Update documentation for new features**
-6. **Run all tests before submitting PRs**
-
-```typescript
-// Example contribution - adding a new method
-/**
- * Get user profile with additional details
- * @description Retrieves comprehensive user profile including preferences and settings
- * 
- * @param userId - The unique identifier for the user
- * @param options - Additional options for profile retrieval
- * @returns Promise resolving to user profile data
- * @throws AuthenticationError When user token is invalid
- * @throws NotFoundError When user does not exist
- * 
- * @example
- * ```typescript
- * const profile = await api.joomla.users.getProfile('user-123', {
- *   includePreferences: true,
- *   edgeCache: 2
- * });
- * 
- * console.log(profile.data.username);
- * console.log(profile.data.preferences);
- * ```
- */
-async getProfile(userId: string, options?: ProfileOptions): Promise<UserProfileResponse> {
-  const params = ProfileOptionsSchema.parse(options || {});
-  const response = await this.http.get(`/user/${userId}/profile`, params);
-  return UserProfileResponseSchema.parse(response);
-}
-```
-
-## Contributing
-
-We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.
-
-### Quick Contributing Steps
-
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/amazing-feature`
-3. Make your changes with tests
-4. Ensure all tests pass: `npm test`
-5. Commit changes: `git commit -m 'Add amazing feature'`
-6. Push to branch: `git push origin feature/amazing-feature`
-7. Submit a Pull Request
-
-### Development Setup
-
-```bash
-# Clone your fork
-git clone https://github.com/your-username/augur-api-client.git
-cd augur-api-client/packages/augur-api
-
-# Install dependencies
-npm install
-
-# Set up development credentials
-cp .env.example .env
-# Edit .env with your API credentials
-
-# Run tests to verify setup
-npm test
-```
+See [SKILL.md](./SKILL.md) for guidance on using this package with AI assistance.
 
 ## License
 
-MIT License - see [LICENSE](./LICENSE) file for details.
-
-## Support
-
-- **Documentation**: [User Guide](https://www.notion.so/2324fc202fd181c5880fe659f3ad2c3f)
-- **Developer Docs**: [Developer Guide](https://www.notion.so/2324fc202fd181a58e77e8ca876a1c6f)
-- **Issues**: [GitHub Issues](https://github.com/your-org/augur-api-client/issues)
-- **Discord**: [Community Chat](https://discord.gg/augur-api)
-
----
-
-**Built with ❤️ by the Augur team**
+MIT