@simpleapps-com/augur-api 0.1.4 → 0.1.6

package/README.md

@@ -1,346 +1,501 @@
 # Augur API Client Library
 
-A TypeScript client library for accessing Augur microservices with type safety, runtime validation, and excellent developer experience.
+A comprehensive TypeScript client library for accessing Augur microservices with type safety, runtime validation, edge caching, and excellent developer experience.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Features](#features)
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Authentication & Security](#authentication--security)
+- [API Documentation](#api-documentation)
+- [Advanced Features](#advanced-features)
+- [Integration Guides](#integration-guides)
+- [Error Handling](#error-handling)
+- [Configuration](#configuration)
+- [Performance Optimization](#performance-optimization)
+- [Development](#development)
+- [Contributing](#contributing)
+
+## Overview
+
+The Augur API Client Library provides a unified TypeScript SDK for accessing Augur's microservices ecosystem. Built with modern web development in mind, it offers seamless integration with React, React Native, Next.js, and Node.js applications.
+
+### Key Capabilities
+
+- **13 Microservice Clients**: Comprehensive coverage of Joomla, Commerce, Pricing, VMI, OpenSearch, Items, Legacy, Nexus, AGR Site, Customers, Orders, P21 PIM, and Payments services
+- **Type-Safe Operations**: Full TypeScript support with auto-generated types from Zod schemas
+- **Edge Caching**: Built-in Cloudflare integration for optimal performance
+- **Cross-Site Authentication**: Support for multi-tenant applications
+- **Runtime Validation**: Zod schemas validate all requests and responses
+- **Developer Experience**: Rich JSDoc documentation and IntelliSense support
 
 ## Features
 
-- 🚀 **Simple API** - Intuitive method names following REST conventions
-- 🔒 **Type Safe** - Full TypeScript support with auto-completion
-- ✅ **Runtime Validation** - Zod schemas validate all requests and responses
-- 🔄 **Automatic Retries** - Built-in retry logic for failed requests
-- 🎯 **Smart Authentication** - Handles JWT tokens and site IDs automatically
-- 📝 **Great DX** - Helpful error messages and JSDoc documentation
+✅ **Simple API** - Intuitive method names following REST conventions  
+✅ **Type Safe** - Full TypeScript support with auto-completion  
+✅ **Runtime Validation** - Zod schemas validate all requests and responses  
+✅ **Automatic Retries** - Built-in retry logic for failed requests  
+✅ **Smart Authentication** - Handles JWT tokens and site IDs automatically  
+✅ **Edge Caching** - Cloudflare integration for sub-100ms response times  
+✅ **Multi-Platform** - Works in React Native, React, Next.js, Node.js, and Electron  
+✅ **Great DX** - Helpful error messages and comprehensive JSDoc documentation  
+✅ **Cross-Site Auth** - Multi-tenant authentication support  
 
 ## Installation
 
 ```bash
-npm install @augur/api-client
+npm install @simpleapps-com/augur-api
 # or
-yarn add @augur/api-client
+yarn add @simpleapps-com/augur-api
+# or
+pnpm add @simpleapps-com/augur-api
 ```
 
-## Quick Start
+### System Requirements
+
+- Node.js >= 16.0.0
+- TypeScript >= 4.5.0 (for TypeScript projects)
+
+## Getting Started
+
+### Basic Setup
 
 ```typescript
-import { AugurAPI } from '@augur/api-client';
+import { AugurAPI } from '@simpleapps-com/augur-api';
 
 // Initialize the client
 const api = new AugurAPI({
-  siteId: 'your-site-id',
-  bearerToken: 'your-jwt-token',
+  siteId: 'your-site-id',        // Required for all endpoints
+  bearerToken: 'your-jwt-token', // Required except for health checks
 });
 
-// Make API calls
-const users = await api.joomla.users.list();
-const user = await api.joomla.users.get('user-123');
+// Make your first API call
+const users = await api.joomla.users.list({
+  limit: 10,
+  edgeCache: 2  // Cache for 2 hours
+});
+
+console.log(`Found ${users.data.length} users`);
 ```
 
-## Authentication
+### Environment Setup
+
+```typescript
+// .env file
+AUGUR_SITE_ID=your-site-id
+AUGUR_JWT_TOKEN=your-jwt-token
 
-The client handles two types of authentication:
+// app.ts
+const api = new AugurAPI({
+  siteId: process.env.AUGUR_SITE_ID!,
+  bearerToken: process.env.AUGUR_JWT_TOKEN!,
+});
+```
 
-1. **Site ID** (required for all endpoints): Set via `x-site-id` header
-2. **Bearer Token** (required for all endpoints except `/health-check`): JWT token in Authorization header
+### Quick Example: E-commerce Operations
 
 ```typescript
-const api = new AugurAPI({
-  siteId: 'required-site-id',
-  bearerToken: 'optional-for-health-check',
+// Get product recommendations
+const recommendations = await api.commerce.alsoBought.get({
+  itemId: 'WIRE-123',
+  customerId: 12345,
+  edgeCache: 4  // Cache recommendations for 4 hours
 });
 
-// Health check works without bearer token
-const health = await api.joomla.getHealthCheck();
+// 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
+});
 
-// All other endpoints require bearer token
-const users = await api.joomla.users.list(); // Requires auth
+// 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
+});
 ```
 
-## Edge Caching
+## Authentication & Security
 
-The client provides built-in edge caching support through Cloudflare integration:
+### Dual Authentication System
 
-### Basic Usage
+The Augur API uses a dual authentication system:
 
-Use the `edgeCache` parameter to control cache duration (in hours):
+1. **Site ID** (`x-site-id` header) - Required for ALL endpoints
+2. **Bearer Token** (JWT) - Required for all endpoints EXCEPT health checks
 
 ```typescript
-// Cache for 4 hours
-const users = await api.joomla.users.list({ 
-  edgeCache: 4,
-  limit: 20 
+const api = new AugurAPI({
+  siteId: 'your-site-id',        // Always required
+  bearerToken: 'your-jwt-token', // Required except for health checks
 });
+```
+
+### Health Checks (No Authentication Required)
 
-// Cache single user for 1 hour
-const user = await api.joomla.users.get('user-123', { 
-  edgeCache: 1 
+```typescript
+// Health checks work without bearer token
+const api = new AugurAPI({
+  siteId: 'your-site-id',
+  // No bearerToken needed
 });
 
-// Cache content for 8 hours
-const content = await api.joomla.content.list({ 
-  edgeCache: 8,
-  categoryIdList: '1,2,3' 
+const health = await api.joomla.getHealthCheck();
+const pricing = await api.pricing.getHealthCheck();
+const vmiPing = await api.vmi.health.ping();
+```
+
+### Cross-Site Authentication
+
+Enable multi-tenant authentication using the special `augur_info` site:
+
+#### Option 1: Streamlined Utility Function (Recommended)
+
+```typescript
+import { authenticateUserForSite } from '@simpleapps-com/augur-api';
+
+// Simple one-function approach
+const result = await authenticateUserForSite({
+  targetSiteId: 'tenant_site_1',
+  username: 'user@tenant.com',
+  password: 'userpassword',
+  augurInfoToken: 'admin-jwt-token'  // JWT with augur_info admin privileges
 });
+
+if (result.success) {
+  // Ready-to-use API client for the target site
+  const userData = await result.targetSiteAPI!.joomla.users.get(result.userId!);
+  console.log('User authenticated:', result.username);
+  console.log('User data:', userData);
+} else {
+  console.error('Authentication failed:', result.error);
+}
 ```
 
-### Supported Cache Durations
+#### Option 2: Reusable Authenticator
+
+```typescript
+import { createCrossSiteAuthenticator } from '@simpleapps-com/augur-api';
+
+// Create reusable authenticator
+const crossSiteAuth = createCrossSiteAuthenticator('admin-jwt-token');
+
+// Use for multiple sites
+const result1 = await crossSiteAuth('tenant_site_1', 'user1@tenant.com', 'pass1');
+const result2 = await crossSiteAuth('tenant_site_2', 'user2@tenant.com', 'pass2');
 
-Only specific cache durations are supported (validated by Zod):
+if (result1.success) {
+  const tenantData = await result1.targetSiteAPI!.joomla.content.list({ limit: 10 });
+}
+```
 
-- `1` - 1 hour cache
-- `2` - 2 hour cache  
-- `3` - 3 hour cache
-- `4` - 4 hour cache
-- `5` - 5 hour cache
-- `8` - 8 hour cache
+#### Option 3: Manual Approach
 
 ```typescript
-// ✅ Valid cache durations
-{ edgeCache: 1 }  // 1 hour
-{ edgeCache: 4 }  // 4 hours  
-{ edgeCache: 8 }  // 8 hours
+// Manual approach using the API client directly
+const crossSiteAPI = new AugurAPI({
+  siteId: 'augur_info',           // Special site for cross-site operations
+  bearerToken: 'admin-jwt-token', // JWT token with augur_info admin privileges
+});
+
+// Authenticate user against a different site
+const authResult = await crossSiteAPI.joomla.users.verifyPassword({
+  username: 'user@tenant.com',
+  password: 'userpassword',
+  siteId: 'tenant_site_1'        // Target site for authentication
+});
 
-// ❌ Invalid values (will throw ValidationError)
-{ edgeCache: 7 }   // Not supported
-{ edgeCache: 24 }  // Not supported
+if (authResult.data.isVerified) {
+  // Create API instance for the target site
+  const tenantAPI = new AugurAPI({
+    siteId: 'tenant_site_1',
+    bearerToken: authResult.data.token, // Token scoped to tenant site
+  });
+  
+  const userData = await tenantAPI.joomla.users.get(authResult.data.id);
+}
 ```
 
-### How It Works
+### Dynamic Authentication Updates
 
-1. **Automatic Parameter Mapping**: `edgeCache` values are automatically mapped to Cloudflare cache rule parameters:
-   - `edgeCache: 1` → `cacheSiteId1=your-site-id`
-   - `edgeCache: 4` → `cacheSiteId4=your-site-id`
-   - `edgeCache: 8` → `cacheSiteId8=your-site-id`
+```typescript
+// Update credentials at runtime
+api.setAuthToken('new-jwt-token');
+api.setSiteId('new-site-id');
 
-2. **Site Isolation**: Each site's cache is automatically isolated using your 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);
+    }
+  }
+}
+```
 
-3. **Zero Configuration**: No setup required - just add the `edgeCache` parameter
+### Security Best Practices
 
-### When to Use Caching
+1. **Environment Variables**: Store credentials in environment variables
+2. **Token Rotation**: Implement regular token rotation in production
+3. **HTTPS Only**: All API requests use HTTPS in production
+4. **Secure Storage**: Never store tokens in localStorage for web apps
+5. **Minimal Permissions**: Use tokens with minimal required permissions
 
-- **Frequently accessed data** that doesn't change often
-- **List endpoints** with consistent results
-- **Reference data** like tags, categories, user groups
-- **Performance-critical** operations
+```typescript
+// ✅ Good: Environment-based configuration
+const api = new AugurAPI({
+  siteId: process.env.AUGUR_SITE_ID!,
+  bearerToken: getSecurelyStoredToken(), // From secure storage
+});
 
-### When NOT to Use Caching
+// ❌ Bad: Hardcoded credentials
+const api = new AugurAPI({
+  siteId: 'hardcoded-site-id',
+  bearerToken: 'hardcoded-token', // Never do this!
+});
+```
 
-- **Real-time data** that changes frequently
-- **User-specific data** that must be current
-- **Create/Update operations** (POST/PUT endpoints don't support caching)
-- **Sensitive operations** requiring fresh data
+## API Documentation
 
-> **📖 For comprehensive caching guidance, see the [Edge Caching Guide](./docs/caching-guide.md)**
+### Service Overview
 
-## Available Services
+| 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 |
 
-### Joomla Service
+### Complete Endpoint Reference
 
-Content management and user administration:
+#### Joomla Service
 
-#### Content Management
 ```typescript
-// List content with filtering
-const contents = await api.joomla.content.list({
-  categoryIdList: '1,2,3',
+// Content Management
+const articles = await api.joomla.content.list({
+  categoryIdList: '1,2,3',  // Filter by categories
+  tagsList: 'featured,new', // Filter by tags
   limit: 20,
   offset: 0,
   orderBy: 'created|DESC',
   q: 'search term',
-  tagsList: 'tag1,tag2'
-});
-
-// List content with 4-hour edge caching
-const cachedContents = await api.joomla.content.list({
-  categoryIdList: '1,2,3',
-  edgeCache: 4,  // Cache for 4 hours
-  limit: 20
-});
-
-// Get single content
-const content = await api.joomla.content.get('content-id', {
-  alias: 'optional-alias',
-  catid: 5
+  edgeCache: 6  // Cache articles for 6 hours
 });
 
-// Get single content with 1-hour caching
-const cachedContent = await api.joomla.content.get('content-id', {
-  edgeCache: 1  // Cache for 1 hour
+const article = await api.joomla.content.get('123', {
+  alias: 'article-alias',
+  catid: 5,
+  edgeCache: 8  // Cache single articles for 8 hours
 });
 
-// Get content documentation
-const doc = await api.joomla.content.getDoc('content-id');
-```
+const articleDoc = await api.joomla.content.getDoc('123');
 
-#### User Management
-```typescript
-// List users
+// User Management
 const users = await api.joomla.users.list({
-  limit: 20,
+  limit: 50,
   offset: 0,
   orderBy: 'username|ASC',
-  q: 'search'
+  q: 'john',
+  edgeCache: 2  // Cache user lists for 2 hours
 });
 
-// List users with 2-hour caching (good for user directories)
-const cachedUsers = await api.joomla.users.list({
-  edgeCache: 2,  // Cache for 2 hours
-  limit: 20,
-  orderBy: 'username|ASC'
-});
+const user = await api.joomla.users.get('456');
+const userDoc = await api.joomla.users.getDoc('456');
 
-// Get user details
-const user = await api.joomla.users.get('user-id');
+// Create new user
+const newUser = await api.joomla.users.create({
+  username: 'newuser',
+  email: 'user@example.com',
+  name: 'New User',
+  password: 'securepassword'
+});
 
-// Get user details with 1-hour caching
-const cachedUser = await api.joomla.users.get('user-id', {
-  edgeCache: 1  // Cache for 1 hour
+// Update user
+const updatedUser = await api.joomla.users.update('456', {
+  email: 'newemail@example.com'
 });
 
-// Get user's groups
-const groups = await api.joomla.users.groups.list('user-id');
+// Block/unblock user
+await api.joomla.users.block('456');
 
-// Get user's groups with caching
-const cachedGroups = await api.joomla.users.groups.list('user-id', {
-  edgeCache: 4  // Cache for 4 hours (groups don't change often)
+// User Groups
+const userGroups = await api.joomla.users.groups.list('456', {
+  limit: 10,
+  edgeCache: 4  // Cache group memberships for 4 hours
 });
-```
 
-#### Other Endpoints
-```typescript
-// User groups (great for caching - rarely change)
-const groups = await api.joomla.userGroups.list();
+const groupMapping = await api.joomla.users.groups.createMapping('456', {
+  groupId: 789
+});
 
-// User groups with 8-hour caching
-const cachedGroups = await api.joomla.userGroups.list({
-  edgeCache: 8  // Cache for 8 hours - group structures rarely change
+// 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({
-  q: 'search',
-  limit: 50
+  categoryId: 1,
+  parentId: 0,
+  q: 'tech',
+  limit: 50,
+  edgeCache: 6  // Cache tags for 6 hours
 });
 
-// Tags with caching (ideal for reference data)
-const cachedTags = await api.joomla.tags.list({
-  edgeCache: 5,  // Cache for 5 hours
-  q: 'search',
-  limit: 50
+// 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
 });
 
-// Menu documentation
-const menuDoc = await api.joomla.menu.getDoc('menu-id');
+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 (no caching - always want fresh status)
+// Health Check
 const health = await api.joomla.getHealthCheck();
 ```
 
-### Commerce Service
-
-E-commerce cart and checkout operations:
+#### Commerce Service
 
-#### Cart Management
 ```typescript
-// List user's carts
-const carts = await api.commerce.cartHeaders.list({ 
+// Cart Management
+const carts = await api.commerce.cartHeaders.list({
   userId: 123,
-  edgeCache: 1  // 1-hour cache (cart data changes frequently)
+  edgeCache: 1  // Cache cart data for 1 hour max
 });
 
-// Lookup or create cart
 const cart = await api.commerce.cartHeaders.lookup({
   userId: 123,
   customerId: 456,
   contactId: 789
 });
 
-// Get cart lines
-const cartLines = await api.commerce.cartLines.get(cartHdrUid);
-```
+const cartLines = await api.commerce.cartLines.get(cart.data.cart_hdr_uid);
 
-#### Checkout Operations
-```typescript
-// Get checkout details with caching
+// 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  // 2-hour cache for checkout data
+  edgeCache: 2  // Cache checkout data for 2 hours
 });
 
-// Get checkout documentation
 const checkoutDoc = await api.commerce.checkout.getDoc(checkoutUid, {
-  cartHdrUid: 123,
-  edgeCache: 4  // 4-hour cache for documentation
+  cartHdrUid: cart.data.cart_hdr_uid,
+  edgeCache: 4  // Cache checkout documents for 4 hours
 });
 
-// Health check
+// Health Check
 const health = await api.commerce.getHealthCheck();
 ```
 
-### Pricing Service
-
-Product pricing and job price management:
+#### Pricing Service
 
-#### Price Engine
 ```typescript
-// Get product pricing with caching
+// Price Engine
 const pricing = await api.pricing.getPrice({
-  customerId: 123,
+  customerId: 12345,
   itemId: 'ITEM-001',
   quantity: 10,
-  edgeCache: 3  // 3-hour cache (prices don't change frequently)
-});
-
-// Pricing with specific parameters
-const customPricing = await api.pricing.getPrice({
-  customerId: 123,
-  itemId: 'ITEM-002',
-  quantity: 5,
-  shipToId: 456,
-  unitOfMeasure: 'EA',
-  edgeCache: 2
+  shipToId: 'SHIP-001',      // Optional
+  unitOfMeasure: 'EA',       // Optional
+  edgeCache: 3  // Cache standard pricing for 3 hours
 });
-```
 
-#### Job Price Management
-```typescript
-// List job price headers with caching
-const jobPrices = await api.pricing.jobPriceHeaders.list({
+// Job Price Management
+const jobPriceHeaders = await api.pricing.jobPriceHeaders.list({
   limit: 20,
   orderBy: 'job_price_hdr_uid|DESC',
-  edgeCache: 4  // 4-hour cache for job listings
+  edgeCache: 4  // Cache job listings for 4 hours
 });
 
-// Get specific job price header
-const jobPrice = await api.pricing.jobPriceHeaders.get(jobPriceHdrUid);
+const jobPriceHeader = await api.pricing.jobPriceHeaders.get(12345);
 
-// Get job price lines
-const priceLines = await api.pricing.jobPriceLines.list(jobPriceHdrUid, {
+const jobPriceLines = await api.pricing.jobPriceLines.list(12345, {
   limit: 50,
-  edgeCache: 4  // 4-hour cache
+  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
 });
 
-// Service health checks
-const pingResponse = await api.pricing.ping();
+// Health Checks
+const ping = await api.pricing.ping();
 const health = await api.pricing.getHealthCheck();
 ```
 
-### VMI (Vendor Managed Inventory) Service
+#### VMI (Vendor Managed Inventory) Service
 
-Warehouse and inventory management operations:
-
-#### Warehouse Management
 ```typescript
-// List warehouses with filtering
+// Warehouse Management
 const warehouses = await api.vmi.warehouses.list({
   customerId: 12345,
   limit: 10,
   q: 'distribution',
-  usersId: 456  // Filter by user access
+  usersId: 456,
+  edgeCache: 4  // Cache warehouse data for 4 hours
 });
 
-// Get specific warehouse
 const warehouse = await api.vmi.warehouses.get(123);
 
-// Create new warehouse
 const newWarehouse = await api.vmi.warehouses.create({
   warehouse_name: 'New Distribution Center',
   warehouse_desc: 'Primary warehouse for west coast operations',
@@ -348,25 +503,20 @@ const newWarehouse = await api.vmi.warehouses.create({
   inv_profile_hdr_uid: 1
 });
 
-// Update warehouse
 const updatedWarehouse = await api.vmi.warehouses.update(123, {
-  warehouse_name: 'Updated Warehouse Name',
-  warehouse_desc: 'Updated description'
+  warehouse_name: 'Updated Warehouse Name'
 });
 
 // Enable/disable warehouse
-await api.vmi.warehouses.enable(123, { status_cd: 705 }); // Disable
 await api.vmi.warehouses.enable(123, { status_cd: 704 }); // Enable
-```
+await api.vmi.warehouses.enable(123, { status_cd: 705 }); // Disable
 
-#### Inventory Operations
-```typescript
-// Check inventory availability
-const inventory = await api.vmi.inventory.checkAvailability(123, {
+// Inventory Operations
+const availability = await api.vmi.inventory.checkAvailability(123, {
   q: 'wire'  // Search for items containing 'wire'
 });
 
-// Adjust inventory quantities (sets absolute values)
+// Adjust inventory (sets absolute values)
 await api.vmi.inventory.adjust(123, {
   adjustments: [
     {
@@ -391,7 +541,8 @@ await api.vmi.inventory.receive(123, {
 
 // Get replenishment information
 const replenishment = await api.vmi.inventory.getReplenishmentInfo(123, {
-  distributorsUid: 789  // Optional distributor filter
+  distributorsUid: 789,
+  edgeCache: 2  // Cache replenishment info for 2 hours
 });
 
 // Execute replenishment
@@ -437,17 +588,16 @@ await api.vmi.inventory.recordUsage(123, {
     }
   ]
 });
-```
 
-#### Distributor Management
-```typescript
-// List distributors
+// Distributor Management
 const distributors = await api.vmi.distributors.list({
   customerId: 12345,
-  statusCd: 704  // Active distributors only
+  statusCd: 704,  // Active distributors only
+  edgeCache: 8  // Cache distributor data for 8 hours
 });
 
-// Create new distributor
+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',
@@ -456,100 +606,40 @@ const newDistributor = await api.vmi.distributors.create({
   contact_phone: '555-1234'
 });
 
-// Update distributor
-const updatedDistributor = await api.vmi.distributors.update(789, {
-  contact_email: 'newemail@abcsupply.com'
-});
-
-// Enable/disable distributor
-await api.vmi.distributors.enable(789, { status_cd: 705 }); // Disable
-```
-
-#### Product Management
-```typescript
-// Find products and items across both VMI and Prophet 21
-const items = await api.vmi.products.find({
+// Product Management
+const products = await api.vmi.products.find({
   customerId: 12345,
-  prefix: 'WIRE'  // Search by item ID prefix
+  prefix: 'WIRE',
+  edgeCache: 6  // Cache product catalogs for 6 hours
 });
 
-// List products for a distributor
-const products = await api.vmi.products.list({
+const productList = await api.vmi.products.list({
   customerId: 12345,
   distributorsUid: 789,
   prefix: 'WIRE',
-  limit: 20
-});
-
-// Create product for distributor
-const newProduct = await api.vmi.products.createForDistributor(789, {
-  product_id: 'PROD-001',
-  product_name: 'Custom Wire Product',
-  product_desc: 'Specialized wire for industrial use',
-  distributors_uid: 789,
-  customer_id: 12345
-});
-```
-
-#### Inventory Profile Management
-```typescript
-// List inventory profile headers
-const profileHeaders = await api.vmi.inventoryProfiles.headers.list({
-  customerId: 12345
-});
-
-// Create inventory profile header
-const profileHeader = await api.vmi.inventoryProfiles.headers.create({
-  inv_profile_hdr_desc: 'Standard Office Setup Profile',
-  customer_id: 12345
-});
-
-// List profile lines for a header
-const profileLines = await api.vmi.inventoryProfiles.lines.list(1, {
-  limit: 20
-});
-
-// Create inventory profile line (defines min/max/reorder quantities)
-const profileLine = await api.vmi.inventoryProfiles.lines.create(1, {
-  inv_mast_uid: 456,
-  inv_profile_line_type: 'prophet21',
-  min_qty: 50.0,
-  max_qty: 200.0,
-  reorder_qty: 100.0
+  limit: 20,
+  edgeCache: 6
 });
-```
-
-#### Health Monitoring
-```typescript
-// Simple ping (no authentication required)
-const pong = await api.vmi.health.ping();
 
-// Comprehensive health check
+// Health Monitoring
+const ping = await api.vmi.health.ping();
 const health = await api.vmi.health.check();
 ```
 
-### OpenSearch Service
-
-Advanced product search and discovery operations:
+#### OpenSearch Service
 
-#### Item Search
 ```typescript
-// Basic product search
+// Item Search
 const searchResults = await api.opensearch.itemSearch.search({
-  q: 'electrical wire',
-  searchType: 'query',
-  size: 20
-});
-
-// Advanced search with filtering
-const filteredSearch = await api.opensearch.itemSearch.search({
-  q: 'power tools',
-  searchType: 'query',
-  size: 50,
-  operator: 'AND',
+  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  // 2 hours - search results change as inventory updates
+  filters: JSON.stringify([
+    { attributeUid: 123, attributeValueUid: 456 }
+  ]),
+  edgeCache: 2  // Cache search results for 2 hours
 });
 
 // Similarity search for recommendations
@@ -557,194 +647,1703 @@ const similarItems = await api.opensearch.itemSearch.search({
   q: 'CAT5e network cable 100ft blue',
   searchType: 'similarity',
   size: 15,
-  edgeCache: 4  // 4 hours - similarity results are more stable
+  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  // 6 hours - facet structure changes less frequently
+  edgeCache: 6  // Cache facet structure for 6 hours
 });
-```
 
-#### Items Management
-```typescript
-// List items from search index
+// Items Management
 const items = await api.opensearch.items.list({
-  itemId: 'WIRE',  // Prefix filter
-  online: 'Y',     // Only online items
-  statusCd: 704,   // Active items only
+  itemId: 'WIRE',     // Prefix filter
+  online: 'Y',        // Only online items
+  statusCd: 704,      // Active items only
   limit: 100,
   offset: 0,
-  edgeCache: 3     // 3 hours - item data is relatively stable
+  edgeCache: 3  // Cache item data for 3 hours
 });
 
-// Get detailed item information
 const itemDetail = await api.opensearch.items.get(123456);
 
-// Refresh item from source database
+// Index management operations (no caching for real-time operations)
 const refreshResult = await api.opensearch.items.refresh(123456);
-
-// Update item in search index
 const updateResult = await api.opensearch.items.update(123456);
-
-// Batch refresh all items
 const batchRefresh = await api.opensearch.items.refreshAll();
+
+// Health Monitoring
+const ping = await api.opensearch.health.ping();
+const health = await api.opensearch.health.check();
 ```
 
-#### Health Monitoring
+### Response Format
+
+All Augur microservices follow a unified response pattern:
+
 ```typescript
-// Simple ping
-const pong = await api.opensearch.health.ping();
+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
+}
 
-// Comprehensive health check
-const health = await api.opensearch.health.check();
+// 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;
 ```
 
-## Error Handling
+### 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 |
 
-The client provides typed errors with helpful information:
+### 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 AugurAPIError) {
-    console.error(`API Error ${error.code}: ${error.message}`);
+  if (error instanceof AuthenticationError) {
+    console.error('Authentication failed:', error.message);
+    // Handle auth error - refresh token or redirect to login
     
-    switch (error.code) {
-      case 'AUTHENTICATION_ERROR':
-        // Handle auth error - refresh token
-        break;
-      case 'NOT_FOUND':
-        // Handle not found
-        break;
-      case 'VALIDATION_ERROR':
-        // Handle validation errors
-        console.error('Validation errors:', error.validationErrors);
-        break;
-      case 'RATE_LIMIT_EXCEEDED':
-        // Handle rate limiting
-        break;
-    }
+  } 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
   }
 }
 ```
 
-## Configuration
+## Advanced Features
+
+### Edge Caching with Cloudflare
+
+The client provides built-in edge caching that dramatically improves performance by serving cached responses from Cloudflare's global edge network.
+
+#### Supported Cache Durations
+
+Only specific cache durations are supported and validated:
+
+| Value | Duration | Best For |
+|-------|----------|----------|
+| `1` | 1 hour | Frequently changing data, cart contents |
+| `2` | 2 hours | User lists, moderate volatility data |
+| `3` | 3 hours | Standard pricing, product information |
+| `4` | 4 hours | Recommendations, warehouse data |
+| `5` | 5 hours | Tags, categories, reference data |
+| `8` | 8 hours | Static content, distributor information |
+
+#### Cache Implementation
+
+```typescript
+// How it works internally:
+// edgeCache: 4 → adds URL parameter: cacheSiteId4=your-site-id
+// This triggers Cloudflare cache rules for 4-hour TTL
+
+const users = await api.joomla.users.list({
+  limit: 20,
+  edgeCache: 4  // Cached at edge for 4 hours
+});
+```
+
+#### Caching Best Practices
+
+```typescript
+// ✅ Good: Cache stable reference data
+const categories = await api.items.categories.list({
+  edgeCache: 8  // Categories rarely change
+});
+
+// ✅ Good: Cache with appropriate TTL
+const pricing = await api.pricing.getPrice({
+  customerId: 12345,
+  itemId: 'STANDARD-ITEM',
+  quantity: 10,
+  edgeCache: 3  // Standard pricing changes infrequently
+});
+
+// ✅ Good: Short cache for volatile data
+const cart = await api.commerce.cartHeaders.list({
+  userId: 123,
+  edgeCache: 1  // Cart data changes frequently
+});
+
+// ❌ Bad: Don't cache real-time operations
+const auth = await api.joomla.users.verifyPassword({
+  username: 'user',
+  password: 'pass'
+  // No edgeCache - authentication must be real-time
+});
+
+// ❌ Bad: Don't cache user-specific data too long
+const userSpecificData = await api.vmi.inventory.checkAvailability(warehouseId, {
+  q: 'search',
+  edgeCache: 8  // Too long for inventory data
+});
+```
+
+### Request Cancellation
+
+```typescript
+const controller = new AbortController();
+
+// Start a request
+const usersPromise = api.joomla.users.list(
+  { limit: 100 },
+  { signal: controller.signal }  // Pass abort signal
+);
+
+// Cancel the request if needed
+setTimeout(() => {
+  controller.abort();
+}, 5000);
+
+try {
+  const users = await usersPromise;
+} catch (error) {
+  if (error.name === 'AbortError') {
+    console.log('Request was cancelled');
+  }
+}
+```
+
+### Custom Headers and Timeouts
+
+```typescript
+// Per-request configuration
+const users = await api.joomla.users.list(
+  { limit: 20 },
+  {
+    timeout: 10000,  // 10 second timeout
+    headers: {
+      'X-Custom-Header': 'value',
+      'X-Request-ID': 'unique-id'
+    }
+  }
+);
+```
+
+### Batch Operations
+
+```typescript
+// Execute multiple operations in parallel
+const [users, articles, tags] = await Promise.all([
+  api.joomla.users.list({ limit: 10, edgeCache: 2 }),
+  api.joomla.content.list({ limit: 5, edgeCache: 6 }),
+  api.joomla.tags.list({ limit: 20, edgeCache: 8 })
+]);
+
+// Process results
+console.log(`Found ${users.data.length} users`);
+console.log(`Found ${articles.data.length} articles`);
+console.log(`Found ${tags.data.length} tags`);
+```
+
+### Middleware Integration
 
 ```typescript
+// Add global request/response interceptors
 const api = new AugurAPI({
-  // Required
   siteId: 'your-site-id',
+  bearerToken: 'your-token',
   
-  // Authentication
-  bearerToken: 'your-jwt-token',
-  apiKey: 'alternative-auth-method',
-  
-  // Optional 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)
-  
-  // Interceptors
+  // Request interceptor
   onRequest: (config) => {
-    console.log('Request:', config);
+    console.log(`Making request to: ${config.url}`);
+    config.headers['X-Request-Timestamp'] = Date.now().toString();
     return config;
   },
+  
+  // Response interceptor
   onResponse: (response) => {
-    console.log('Response:', response);
+    console.log(`Response status: ${response.status}`);
     return response;
   },
+  
+  // Error interceptor
   onError: (error) => {
-    console.error('Error:', error);
+    console.error('API Error:', error.message);
+    // Custom error handling logic
     throw error;
   }
 });
 ```
 
-## Dynamic Configuration
+## Integration Guides
 
-Update authentication credentials at runtime:
+### React Integration
 
-```typescript
-// Update bearer token
-api.setAuthToken('new-token');
+```tsx
+import React, { useState, useEffect } from 'react';
+import { AugurAPI, User, AugurAPIError } from '@simpleapps-com/augur-api';
 
-// Update site ID
-api.setSiteId('new-site-id');
-```
+// Custom hook for Augur API
+function useAugurAPI() {
+  const [api] = useState(() => 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);
+      }
+    }
 
-## TypeScript Support
+    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;
+```
 
-All responses are fully typed with TypeScript interfaces generated from Zod schemas:
+### React Native Integration
 
 ```typescript
-import type { User, Content, Tag } from '@augur/api-client';
+import { AugurAPI } from '@simpleapps-com/augur-api';
+import AsyncStorage from '@react-native-async-storage/async-storage';
 
-const user: User = await api.joomla.users.get('123');
-// TypeScript knows all properties of user
+class AugurService {
+  private api: AugurAPI;
 
-const contents: ContentListResponse = await api.joomla.content.list();
-// Full type safety for paginated responses
-```
+  constructor() {
+    this.api = new AugurAPI({
+      siteId: 'your-site-id',
+      bearerToken: '', // Will be set after loading from storage
+    });
+    
+    this.loadCredentials();
+  }
 
-## Implementation Status
+  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);
+    }
+  }
 
-- ✅ Core HTTP client with authentication
-- ✅ Error handling with typed errors
-- ✅ Joomla service (full implementation)
-- ✅ Commerce service (full implementation)
-- ✅ Pricing service (full implementation)
-- ✅ VMI service (full implementation)
-- ✅ OpenSearch service (full implementation)
-- ✅ Zod validation for all requests/responses
-- ✅ TypeScript types with full inference
-- ✅ Edge caching with Cloudflare integration
-- ⏳ POST/PUT/DELETE endpoints (coming soon)
-- ⏳ Offline support for React Native
+  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;
+  }
 
-## Development
+  async getProducts(searchTerm: string) {
+    return this.api.opensearch.itemSearch.search({
+      q: searchTerm,
+      searchType: 'query',
+      size: 20,
+      edgeCache: 3  // Cache search results
+    });
+  }
 
-This library follows the specifications in the PRD and API documentation. Key principles:
+  async logout() {
+    await AsyncStorage.multiRemove(['augur_token', 'augur_site_id']);
+    this.api.setAuthToken('');
+  }
+}
 
-1. **Method Naming**: Based on HTTP method and path
-   - GET `/users` → `listUsers()`
-   - GET `/user/:id` → `getUser()`
-   - POST `/user` → `createUser()` (coming soon)
-   - PUT `/user/:id` → `updateUser()` (coming soon)
-   - DELETE `/user/:id` → `deleteUser()` (coming soon)
+export const augurService = new AugurService();
+```
 
-2. **ID Conventions**:
-   - Fields ending with `Uid` are numbers
-   - Fields ending with `Id` are strings
+### Next.js Integration
 
-3. **Validation**: All inputs and outputs validated with Zod schemas
+```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
+  });
+}
 
-## Documentation
+// 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
+  });
+}
 
-### 📚 User Documentation
+// pages/api/products/search.ts
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { createServerAPI } from '../../../lib/augur';
 
-For comprehensive guides, examples, and best practices:
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse
+) {
+  if (req.method !== 'GET') {
+    return res.status(405).json({ error: 'Method not allowed' });
+  }
 
-**[📖 User Documentation →](../../docs/packages/augur-api/user/README.md)**
+  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>
+  );
+}
 
-- **Service Guides**: Detailed documentation for each service (Joomla, Commerce, Pricing, VMI)
-- **Cross-Service Guides**: Authentication, error handling, and caching strategies
-- **Integration Examples**: React Native, Next.js, Node.js, and more
-- **Best Practices**: Performance optimization and real-world usage patterns
+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 },
+      },
+    };
+  }
+};
+```
 
-### 🔧 Developer Documentation
+### Node.js Service Integration
 
-For contributing and extending the library:
+```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);
+  }
 
-**[🔧 Developer Documentation →](../../docs/packages/augur-api/dev/README.md)**
+  // 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.inventory.checkAvailability(warehouseId, {
+      q: searchTerm
+    });
+  }
+
+  async replenishInventory(warehouseId: number, items: Array<{
+    inv_mast_uid: number;
+    qty_to_order: number;
+  }>) {
+    return this.api.vmi.inventory.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' 
+    });
+  }
+});
 
-- **API Specifications**: Complete endpoint documentation
-- **Implementation Plans**: Development roadmaps and architecture
-- **AI Guidelines**: Documentation standards and patterns
+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)
+  
+  // Response capture for debugging
+  captureResponses: true,   // Enable response capture (default: false)
+  capturePath: './captured-responses/', // Path for captured responses
+  
+  // 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;
+  captureResponses: boolean;
+}
+
+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
+    captureResponses: true, // Enable response capture in dev
+  },
+  
+  staging: {
+    siteId: process.env.AUGUR_STAGING_SITE_ID!,
+    bearerToken: process.env.AUGUR_STAGING_TOKEN,
+    timeout: 30000,
+    retries: 2,
+    captureResponses: false,
+  },
+  
+  production: {
+    siteId: process.env.AUGUR_PROD_SITE_ID!,
+    bearerToken: process.env.AUGUR_PROD_TOKEN,
+    timeout: 30000,
+    retries: 3,
+    captureResponses: false,
+  }
+} 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(),
+  captureResponses: z.boolean().optional(),
+  capturePath: z.string().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
+
+### Caching Strategies
+
+```typescript
+// Cache strategy based on data volatility
+class CacheStrategy {
+  static getDuration(dataType: string, context?: Record<string, any>): number | undefined {
+    const strategies = {
+      // Static reference data - cache for 8 hours
+      reference: 8,
+      categories: 8,
+      tags: 6,
+      distributors: 8,
+      
+      // Moderate volatility - cache for 2-4 hours
+      users: context?.isLargeOrg ? 4 : 2,
+      products: 6,
+      warehouses: 4,
+      recommendations: 4,
+      
+      // High volatility - cache for 1-2 hours
+      pricing: context?.isStandardItem ? 3 : 1,
+      inventory: context?.isHighVolume ? 1 : 2,
+      cart: 1,
+      
+      // Real-time data - no caching
+      authentication: undefined,
+      validation: undefined,
+      checkout: undefined,
+    };
+    
+    return strategies[dataType as keyof typeof strategies];
+  }
+}
+
+// Usage
+const duration = CacheStrategy.getDuration('pricing', { isStandardItem: true });
+const pricing = await api.pricing.getPrice({
+  customerId: 12345,
+  itemId: 'STANDARD-ITEM',
+  quantity: 10,
+  edgeCache: duration  // Will be 3 hours
+});
+```
+
+### Request Batching
+
+```typescript
+// Batch related requests for better performance
+async function loadDashboardData() {
+  // Execute all requests in parallel
+  const [users, products, inventory, pricing] = await Promise.allSettled([
+    api.joomla.users.list({ limit: 10, edgeCache: 2 }),
+    api.opensearch.itemSearch.search({ 
+      q: 'featured', 
+      searchType: 'query', 
+      size: 5, 
+      edgeCache: 4 
+    }),
+    api.vmi.warehouses.list({ 
+      customerId: 12345, 
+      limit: 5, 
+      edgeCache: 4 
+    }),
+    api.pricing.jobPriceHeaders.list({ 
+      limit: 5, 
+      edgeCache: 6 
+    })
+  ]);
+
+  // Handle results
+  return {
+    users: users.status === 'fulfilled' ? users.value : null,
+    products: products.status === 'fulfilled' ? products.value : null,
+    inventory: inventory.status === 'fulfilled' ? inventory.value : null,
+    pricing: pricing.status === 'fulfilled' ? pricing.value : null,
+  };
+}
+```
+
+### Connection Pooling
+
+```typescript
+// Configure HTTP client for optimal performance
+const api = new AugurAPI({
+  siteId: 'your-site-id',
+  bearerToken: 'your-token',
+  
+  // Optimize for high-throughput scenarios
+  timeout: 15000,  // Shorter timeout for better user experience
+  retries: 2,      // Fewer retries for faster failure detection
+  
+  onRequest: (config) => {
+    // Add keep-alive headers for connection reuse
+    config.headers['Connection'] = 'keep-alive';
+    config.headers['Keep-Alive'] = 'timeout=5, max=1000';
+    return config;
+  }
+});
+```
+
+### Memory Management
+
+```typescript
+// Efficient memory usage patterns
+class EfficientAugurUsage {
+  private api: AugurAPI;
+  private cache = new Map<string, { data: any; timestamp: number; ttl: number }>();
+
+  constructor(config: AugurAPIConfig) {
+    this.api = new AugurAPI(config);
+    
+    // Clean up expired cache entries every 5 minutes
+    setInterval(() => this.cleanupCache(), 5 * 60 * 1000);
+  }
+
+  async getCachedData<T>(
+    key: string,
+    fetcher: () => Promise<T>,
+    ttlSeconds = 300
+  ): Promise<T> {
+    const cached = this.cache.get(key);
+    const now = Date.now();
+
+    if (cached && (now - cached.timestamp) < (cached.ttl * 1000)) {
+      return cached.data;
+    }
+
+    const data = await fetcher();
+    this.cache.set(key, {
+      data,
+      timestamp: now,
+      ttl: ttlSeconds
+    });
+
+    return data;
+  }
+
+  private cleanupCache(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.cache.entries()) {
+      if ((now - entry.timestamp) >= (entry.ttl * 1000)) {
+        this.cache.delete(key);
+      }
+    }
+  }
+
+  async getUsers(useCache = true): Promise<any> {
+    if (!useCache) {
+      return this.api.joomla.users.list({ limit: 50 });
+    }
+
+    return this.getCachedData(
+      'users-list',
+      () => this.api.joomla.users.list({ limit: 50, edgeCache: 2 }),
+      600 // 10 minutes local cache
+    );
+  }
+
+  destroy(): void {
+    this.cache.clear();
+  }
+}
+```
+
+### Performance Monitoring
+
+```typescript
+// Monitor API performance
+class PerformanceMonitor {
+  private metrics = {
+    requests: 0,
+    errors: 0,
+    totalTime: 0,
+    cacheHits: 0,
+    cacheMisses: 0
+  };
+
+  createMonitoredAPI(config: AugurAPIConfig): AugurAPI {
+    return new AugurAPI({
+      ...config,
+      
+      onRequest: (config) => {
+        // Track request start time
+        (config as any).startTime = Date.now();
+        this.metrics.requests++;
+        return config;
+      },
+      
+      onResponse: (response) => {
+        // Calculate request duration
+        const startTime = (response.config as any)?.startTime;
+        if (startTime) {
+          const duration = Date.now() - startTime;
+          this.metrics.totalTime += duration;
+        }
+
+        // Track cache performance
+        const cacheStatus = response.headers?.['cf-cache-status'];
+        if (cacheStatus === 'HIT') {
+          this.metrics.cacheHits++;
+        } else if (cacheStatus === 'MISS') {
+          this.metrics.cacheMisses++;
+        }
+
+        return response;
+      },
+      
+      onError: (error) => {
+        this.metrics.errors++;
+        console.error('API Error metrics:', this.getMetrics());
+        throw error;
+      }
+    });
+  }
+
+  getMetrics() {
+    const avgResponseTime = this.metrics.requests > 0 
+      ? this.metrics.totalTime / this.metrics.requests 
+      : 0;
+    
+    const errorRate = this.metrics.requests > 0 
+      ? (this.metrics.errors / this.metrics.requests) * 100 
+      : 0;
+    
+    const cacheHitRate = (this.metrics.cacheHits + this.metrics.cacheMisses) > 0
+      ? (this.metrics.cacheHits / (this.metrics.cacheHits + this.metrics.cacheMisses)) * 100
+      : 0;
+
+    return {
+      totalRequests: this.metrics.requests,
+      totalErrors: this.metrics.errors,
+      errorRate: errorRate.toFixed(2) + '%',
+      avgResponseTime: avgResponseTime.toFixed(2) + 'ms',
+      cacheHitRate: cacheHitRate.toFixed(2) + '%',
+      totalCacheHits: this.metrics.cacheHits,
+      totalCacheMisses: this.metrics.cacheMisses
+    };
+  }
+
+  reset(): void {
+    this.metrics = {
+      requests: 0,
+      errors: 0,
+      totalTime: 0,
+      cacheHits: 0,
+      cacheMisses: 0
+    };
+  }
+}
+
+// Usage
+const monitor = new PerformanceMonitor();
+const api = monitor.createMonitoredAPI({
+  siteId: 'your-site-id',
+  bearerToken: 'your-token'
+});
+
+// After some API calls, check performance
+setTimeout(() => {
+  console.log('Performance metrics:', monitor.getMetrics());
+}, 60000);
+```
+
+## 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 >85% 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);
+  });
+});
+```
+
+### API Response Capture
+
+For debugging and development, enable response capture:
+
+```typescript
+const api = new AugurAPI({
+  siteId: 'your-site-id',
+  bearerToken: 'your-token',
+  captureResponses: true,
+  capturePath: './captured-responses/'
+});
+
+// Responses will be saved to files for inspection
+const users = await api.joomla.users.list();
+// Saved to: ./captured-responses/joomla-users-list-[timestamp].json
+```
+
+### 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 >85% 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
 
-See the project documentation for contribution guidelines.
+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
+```
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) file for details.
+
+## Support
+
+- **Documentation**: [User Guide](../../docs/packages/augur-api/user/README.md)
+- **Developer Docs**: [Developer Guide](../../docs/packages/augur-api/dev/README.md)
+- **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**