@simpleapps-com/augur-api 0.2.6 → 0.2.7

package/API-DISCOVERY.md

@@ -0,0 +1,132 @@
+# API Discovery Guide
+
+Find any functionality across 13 microservices using natural language search.
+
+## Quick Reference
+
+```typescript
+import { AugurAPI } from '@simpleapps-com/augur-api';
+
+const api = new AugurAPI({ siteId: 'your-site', bearerToken: 'token' });
+
+// Discover all services
+const services = await api.discover();
+
+// Find specific functionality  
+const results = await api.findEndpoint('user management');
+const inventory = await api.findEndpoint('stock levels');
+const pricing = await api.findEndpoint('product pricing');
+```
+
+## Core Methods
+
+### `api.discover()`
+Returns complete service map with all available endpoints.
+
+```typescript
+const services = await api.discover();
+services.forEach(service => {
+  console.log(`${service.serviceName}: ${service.endpointCount} endpoints`);
+});
+```
+
+### `api.findEndpoint(searchTerm, options?)`
+Search across all services for matching functionality.
+
+```typescript
+// Basic search
+const results = await api.findEndpoint('users');
+
+// Advanced search with filters
+const results = await api.findEndpoint('settings', {
+  service: 'agrSite',           // Filter by service
+  domain: 'content-management', // Filter by domain
+  readOnly: true,               // Only GET endpoints
+  maxResults: 5                 // Limit results
+});
+```
+
+## Common Searches
+
+| Search Term | Returns |
+|-------------|---------|
+| `'user management'` | User CRUD, authentication, groups |
+| `'inventory'` | Stock levels, warehouse operations |
+| `'product search'` | OpenSearch, product catalogs |
+| `'site settings'` | Configuration, notifications |
+| `'pricing'` | Price engine, job pricing |
+| `'orders'` | Order management, invoicing |
+
+## Search Filters
+
+```typescript
+interface SearchOptions {
+  service?: string;        // 'joomla', 'vmi', 'commerce', etc.
+  domain?: string;         // 'user-management', 'inventory-management'
+  readOnly?: boolean;      // true = GET only, false = all methods
+  minScore?: number;       // 0.0 to 1.0 relevance threshold
+  maxResults?: number;     // Limit number of results
+}
+```
+
+## Business Domains
+
+- **user-management** - Users, authentication, permissions
+- **content-management** - Articles, site settings, notifications  
+- **e-commerce** - Shopping carts, checkout, recommendations
+- **inventory-management** - Warehouses, stock levels, transfers
+- **product-catalog** - Products, categories, search
+- **customer-data** - Customer profiles, orders, addresses
+- **order-processing** - Orders, invoicing, payments
+
+## AI Assistant Integration
+
+Every method includes semantic tags for AI assistants:
+
+```typescript
+/**
+ * @searchTerms ["users", "user management", "authentication"]
+ * @relatedEndpoints ["api.joomla.users.get", "api.joomla.users.create"] 
+ * @commonPatterns ["List all users", "Get user directory"]
+ */
+```
+
+When you ask an AI assistant "help me manage users", it can:
+1. Find `api.joomla.users.list()` through searchTerms
+2. Suggest related operations from relatedEndpoints  
+3. Provide examples using commonPatterns
+4. Show complete workflows across services
+
+## Example Workflows
+
+### User Management
+```typescript
+const userOps = await api.findEndpoint('user management');
+// Returns: api.joomla.users.list, api.joomla.users.get, api.joomla.users.create
+
+const users = await api.joomla.users.list({ limit: 10 });
+const user = await api.joomla.users.get('123');
+```
+
+### Inventory Operations  
+```typescript
+const inventory = await api.findEndpoint('inventory levels');
+// Returns: api.vmi.inventory.checkAvailability, api.vmi.warehouses.list
+
+const availability = await api.vmi.inventory.checkAvailability(warehouseId);
+const warehouses = await api.vmi.warehouses.list({ customerId: 12345 });
+```
+
+### Product Search
+```typescript
+const search = await api.findEndpoint('product search');
+// Returns: api.opensearch.itemSearch.search, api.items.products.list
+
+const results = await api.opensearch.itemSearch.search({
+  q: 'electrical wire',
+  searchType: 'query',
+  size: 20
+});
+```
+
+The discovery system eliminates the need to memorize 13 different microservice APIs. Just describe what you want to accomplish, and find the right endpoints instantly.

package/AUTHENTICATION.md

@@ -0,0 +1,371 @@
+# Authentication Guide
+
+Complete guide to authentication patterns in the Augur API Client.
+
+## Standard Authentication (Most Common)
+
+The standard authentication pattern works for 95% of use cases.
+
+### Dual Authentication System
+
+Every API request requires two pieces of authentication:
+
+1. **Site ID** (`x-site-id` header) - Identifies which site/tenant you're working with
+2. **Bearer Token** (JWT) - Proves you're authorized to access that site
+
+```typescript
+const api = new AugurAPI({
+  siteId: 'your-site-id',        // Always required
+  bearerToken: 'your-jwt-token', // Required except for health checks
+});
+```
+
+### How to Get Your Credentials
+
+**Site ID**: Usually provided by your system administrator or found in your project configuration.
+
+**Bearer Token**: Obtained through your application's login process. This is typically a JWT token that looks like:
+`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
+
+### Health Checks (No Authentication Required)
+
+Health checks are the only endpoints that don't require a bearer token:
+
+```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 pricingHealth = await api.pricing.getHealthCheck();
+const vmiPing = await api.vmi.health.ping();
+```
+
+### Dynamic Authentication Updates
+
+Update credentials at runtime when needed:
+
+```typescript
+// Update token after login/refresh
+api.setAuthToken('new-jwt-token');
+
+// Switch to different site
+api.setSiteId('different-site-id');
+
+// Example: Token refresh scenario
+async function refreshTokenIfNeeded() {
+  try {
+    await api.joomla.users.list({ limit: 1 });
+  } catch (error) {
+    if (error instanceof AuthenticationError) {
+      const newToken = await refreshJWTToken();
+      api.setAuthToken(newToken);
+    }
+  }
+}
+```
+
+### Environment Variables Setup
+
+Store credentials securely in environment variables:
+
+```bash
+# .env file
+AUGUR_SITE_ID=your-site-id
+AUGUR_JWT_TOKEN=your-jwt-token
+```
+
+```typescript
+const api = new AugurAPI({
+  siteId: process.env.AUGUR_SITE_ID!,
+  bearerToken: process.env.AUGUR_JWT_TOKEN!,
+});
+```
+
+### Security Best Practices
+
+1. **Environment Variables**: Never hardcode credentials
+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
+
+```typescript
+// ✅ Good: Environment-based configuration
+const api = new AugurAPI({
+  siteId: process.env.AUGUR_SITE_ID!,
+  bearerToken: getSecurelyStoredToken(), // From secure storage
+});
+
+// ❌ Bad: Hardcoded credentials
+const api = new AugurAPI({
+  siteId: 'hardcoded-site-id',
+  bearerToken: 'hardcoded-token', // Never do this!
+});
+```
+
+---
+
+## Advanced: Cross-Site Authentication
+
+**⚠️ Advanced Feature**: Only needed for multi-tenant applications where you need to authenticate users across different sites.
+
+### When You Need Cross-Site Auth
+
+Cross-site authentication is needed when:
+- You're building a multi-tenant application
+- You need to authenticate a user from one site against a different site
+- You're managing multiple client sites from a central application
+
+### Prerequisites
+
+- Access to the special `augur_info` site
+- Admin-level JWT token with `augur_info` privileges
+- Target site ID where you want to authenticate the user
+
+### Option 1: Streamlined Utility Function (Recommended)
+
+```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'  // 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);
+}
+```
+
+### 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');
+
+if (result1.success) {
+  const tenantData = await result1.targetSiteAPI!.joomla.content.list({ limit: 10 });
+}
+```
+
+### Option 3: Manual Approach
+
+```typescript
+// 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: 'user-password',
+  siteId: 'tenant_site_1'        // Target site for authentication
+});
+
+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);
+}
+```
+
+### Cross-Site Auth Flow Diagram
+
+```
+[Your App] → [augur_info API] → [Target Site] → [User Validated] → [Target Site API Client]
+     ↓              ↓                ↓               ↓                      ↓
+Admin Token → Verify User → Check Password → Return User Token → Ready for API calls
+```
+
+### Common Cross-Site Patterns
+
+#### Multi-Tenant Dashboard
+```typescript
+// Authenticate users across multiple tenant sites
+const authenticator = createCrossSiteAuthenticator(adminToken);
+
+const tenants = ['site1', 'site2', 'site3'];
+const userCredentials = { username: 'user@example.com', password: 'pass' };
+
+const results = await Promise.all(
+  tenants.map(siteId => 
+    authenticator(siteId, userCredentials.username, userCredentials.password)
+  )
+);
+
+// Process results for each tenant
+results.forEach((result, index) => {
+  if (result.success) {
+    console.log(`${tenants[index]}: User authenticated as ${result.username}`);
+  } else {
+    console.log(`${tenants[index]}: Authentication failed - ${result.error}`);
+  }
+});
+```
+
+#### Site Switching
+```typescript
+// Allow users to switch between sites they have access to
+async function switchUserToSite(username: string, password: string, targetSiteId: string) {
+  const result = await authenticateUserForSite({
+    targetSiteId,
+    username,
+    password,
+    augurInfoToken: process.env.AUGUR_INFO_ADMIN_TOKEN!
+  });
+
+  if (result.success) {
+    // Store the new site's API client
+    global.userAPI = result.targetSiteAPI;
+    global.currentSiteId = targetSiteId;
+    return { success: true, siteId: targetSiteId };
+  }
+
+  return { success: false, error: result.error };
+}
+```
+
+### Cross-Site Error Handling
+
+```typescript
+try {
+  const result = await authenticateUserForSite({
+    targetSiteId: 'tenant-site',
+    username: 'user@tenant.com',
+    password: 'user-pass',
+    augurInfoToken: adminToken
+  });
+
+  if (!result.success) {
+    switch (result.error) {
+      case 'Invalid username or password':
+        // Handle wrong username/password
+        break;
+      case 'Site not found':
+        // Handle invalid target site (from API error)
+        break;
+      case 'Authentication failed':
+        // Handle general auth failures or network issues
+        break;
+      default:
+        // Handle other errors
+        break;
+    }
+  }
+} catch (error) {
+  console.error('Cross-site auth failed:', error.message);
+}
+```
+
+### Security Considerations for Cross-Site Auth
+
+1. **Admin Token Security**: The `augur_info` admin token is very powerful - store it extremely securely
+2. **Audit Logging**: Log all cross-site authentication attempts for security monitoring
+3. **Rate Limiting**: Implement rate limiting to prevent brute force attacks
+4. **Token Scoping**: Returned tokens are scoped to the target site only
+5. **Session Management**: Properly manage and clean up cross-site sessions
+
+### When NOT to Use Cross-Site Auth
+
+Don't use cross-site authentication if:
+- You're working with a single site (use standard auth)
+- You don't have admin-level access to `augur_info`
+- You're building a simple application without multi-tenancy
+- Security requirements prohibit cross-site token exchange
+
+---
+
+## Troubleshooting Authentication
+
+### Common Issues
+
+**"Authentication failed" (401 Error)**
+- Check your `bearerToken` is correct and not expired
+- Verify your `siteId` matches your environment
+- For cross-site auth, ensure your admin token has `augur_info` privileges
+
+**"Forbidden" (403 Error)**
+- Your token is valid but doesn't have permission for this operation
+- Check if you need admin-level permissions
+- Verify the site ID matches the token's scope
+
+**"Site not found" (Cross-site auth)**
+- Verify the target site ID exists and is accessible
+- Check that the target site is properly configured
+- Ensure your admin token has access to the target site
+
+**Token Expiration**
+- Implement token refresh logic
+- Monitor token expiration times
+- Have fallback authentication flow
+
+### Authentication Testing
+
+```typescript
+// Test standard authentication
+async function testAuth() {
+  try {
+    const api = new AugurAPI({
+      siteId: 'your-site-id',
+      bearerToken: 'your-token'
+    });
+
+    // Simple test call
+    const health = await api.joomla.getHealthCheck();
+    console.log('✅ Authentication working:', health.data.status);
+
+    // Test authenticated call
+    const users = await api.joomla.users.list({ limit: 1 });
+    console.log('✅ Authenticated API calls working');
+
+  } catch (error) {
+    console.error('❌ Authentication failed:', error.message);
+  }
+}
+
+// Test cross-site authentication
+async function testCrossSiteAuth() {
+  try {
+    const result = await authenticateUserForSite({
+      targetSiteId: 'test-site',
+      username: 'test-user',
+      password: 'test-pass',
+      augurInfoToken: 'admin-token'
+    });
+
+    if (result.success) {
+      console.log('✅ Cross-site auth working');
+      const testCall = await result.targetSiteAPI!.joomla.getHealthCheck();
+      console.log('✅ Target site API working:', testCall.data.status);
+    } else {
+      console.error('❌ Cross-site auth failed:', result.error);
+    }
+  } catch (error) {
+    console.error('❌ Cross-site auth error:', error.message);
+  }
+}
+```
+
+For most applications, stick with standard authentication. Only implement cross-site authentication if you specifically need multi-tenant capabilities.

package/QUICKSTART.md

@@ -0,0 +1,255 @@
+# Quick Start Guide
+
+Get up and running with the Augur API Client in under 5 minutes.
+
+## What is This?
+
+The Augur API Client connects your application to 13 different business services (like user management, inventory, pricing) through a single, easy-to-use interface. Instead of learning 13 different APIs, you learn one.
+
+## Installation
+
+```bash
+npm install @simpleapps-com/augur-api
+```
+
+## Your First API Call
+
+### Step 1: Get Your Credentials
+
+You need two pieces of information:
+- **Site ID**: Identifies which site/tenant you're working with (e.g., `my-company-site`)
+- **Bearer Token**: Your authentication JWT token (looks like `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`)
+
+Ask your system administrator or check your project's environment variables.
+
+### Step 2: Make Your First Call
+
+```typescript
+import { AugurAPI } from '@simpleapps-com/augur-api';
+
+// Create the API client
+const api = new AugurAPI({
+  siteId: 'your-site-id',        // Replace with your actual site ID
+  bearerToken: 'your-jwt-token'  // Replace with your actual token
+});
+
+// Make your first API call - list users
+try {
+  const users = await api.joomla.users.list({ limit: 5 });
+  console.log('Success! Found users:', users.data.length);
+  console.log('First user:', users.data[0]?.name);
+} catch (error) {
+  console.error('Something went wrong:', error.message);
+}
+```
+
+### Step 3: Verify It Works
+
+If you see output like this, you're ready to go:
+```
+Success! Found users: 5
+First user: John Smith
+```
+
+## Common First Steps
+
+### Health Check (No Authentication Required)
+Test your connection without needing authentication:
+
+```typescript
+const api = new AugurAPI({
+  siteId: 'your-site-id'
+  // No bearerToken needed for health checks
+});
+
+const health = await api.joomla.getHealthCheck();
+console.log('Service is:', health.data.status); // Should show "OK"
+```
+
+### Environment Variables Setup
+Create a `.env` file in your project:
+
+```bash
+# .env file
+AUGUR_SITE_ID=your-site-id-here
+AUGUR_JWT_TOKEN=your-jwt-token-here
+```
+
+Then use them in your code:
+
+```typescript
+const api = new AugurAPI({
+  siteId: process.env.AUGUR_SITE_ID!,
+  bearerToken: process.env.AUGUR_JWT_TOKEN!
+});
+```
+
+## Understanding the Response Format
+
+All API calls return data in the same format:
+
+```typescript
+const response = await api.joomla.users.list();
+
+// Response structure:
+// {
+//   status: 200,           // HTTP status code
+//   message: "Ok",         // Status message  
+//   data: [...],           // The actual data you want
+//   totalResults: 150      // Total count (for lists)
+// }
+
+// Access the actual data:
+const users = response.data;           // Array of users
+const totalCount = response.totalResults; // Total number of users
+```
+
+## Two Ways to Get Data
+
+Every API call has two versions:
+
+```typescript
+// 1. Full response (includes metadata)
+const response = await api.joomla.users.list();
+console.log('Users:', response.data);
+console.log('Total:', response.totalResults);
+
+// 2. Data only (just the data you want)
+const users = await api.joomla.users.listData();
+console.log('Users:', users); // Direct array access
+```
+
+## What Can You Do?
+
+The API gives you access to:
+
+| Service | What It Does | Example |
+|---------|--------------|---------|
+| **joomla** | Users, content, site management | `api.joomla.users.list()` |
+| **commerce** | Shopping carts, checkout | `api.commerce.cartHeaders.list()` |
+| **pricing** | Product pricing, calculations | `api.pricing.getPrice()` |
+| **vmi** | Inventory, warehouses | `api.vmi.warehouses.list()` |
+| **opensearch** | Product search | `api.opensearch.itemSearch.search()` |
+| **items** | Product catalog | `api.items.categories.list()` |
+| **customers** | Customer data | `api.customers.customer.list()` |
+
+## Common Patterns
+
+### List Things with Limits
+```typescript
+// Get first 10 users
+const users = await api.joomla.users.list({ limit: 10 });
+
+// Get first 20 products
+const products = await api.items.products.list({ limit: 20 });
+```
+
+### Get Single Items
+```typescript
+// Get specific user by ID
+const user = await api.joomla.users.get('123');
+
+// Get specific product by ID  
+const product = await api.items.products.get(456);
+```
+
+### Search for Things
+```typescript
+// Search for products
+const results = await api.opensearch.itemSearch.search({
+  q: 'wire',           // Search term
+  size: 10             // Number of results
+});
+```
+
+## Performance Tip: Caching
+
+Add caching to make your app faster:
+
+```typescript
+// Cache user list for 2 hours
+const users = await api.joomla.users.list({ 
+  limit: 10,
+  edgeCache: 2  // Cache for 2 hours
+});
+
+// Cache product search for 4 hours
+const products = await api.opensearch.itemSearch.search({
+  q: 'electrical',
+  size: 20,
+  edgeCache: 4  // Cache for 4 hours
+});
+```
+
+**Cache Options:** 1, 2, 3, 4, 5, or 8 hours only.
+
+## Don't Know What's Available?
+
+Use the discovery system to explore:
+
+```typescript
+// See all available services
+const services = await api.discover();
+services.forEach(service => {
+  console.log(`${service.serviceName}: ${service.description}`);
+});
+
+// Find specific functionality
+const userStuff = await api.findEndpoint('user management');
+const inventoryStuff = await api.findEndpoint('inventory');
+```
+
+Learn more in the [API Discovery Guide](./API-DISCOVERY.md).
+
+## Error Handling
+
+Wrap your API calls in try/catch:
+
+```typescript
+try {
+  const users = await api.joomla.users.list();
+  console.log('Got users:', users.data.length);
+} catch (error) {
+  if (error.message.includes('401')) {
+    console.error('Authentication failed - check your token');
+  } else if (error.message.includes('404')) {
+    console.error('Endpoint not found - check your URL');
+  } else {
+    console.error('Something else went wrong:', error.message);
+  }
+}
+```
+
+## Troubleshooting
+
+**"Authentication failed"**
+- Check your `bearerToken` is correct and not expired
+- Verify your `siteId` matches your environment
+
+**"Cannot find endpoint"**
+- Try a health check first: `api.joomla.getHealthCheck()`
+- Verify you're using the right service name
+
+**"Network error"**
+- Check your internet connection
+- Verify the API endpoints are accessible from your network
+
+**"Validation error"**
+- Check the parameter names and types match the examples
+- Look at the error message for specific field issues
+
+## Next Steps
+
+1. **Read the main [README](./README.md)** for comprehensive documentation
+2. **Explore the [API Discovery Guide](./API-DISCOVERY.md)** to find functionality
+3. **Check the Integration Guides** in the README for React, Node.js, etc.
+4. **Look at Error Handling** section for production-ready error management
+
+## Need Help?
+
+- Check the comprehensive [README](./README.md) for detailed examples
+- Use `api.discover()` to explore available functionality
+- Look at the error messages - they usually tell you what's wrong
+- Ask your team lead or system administrator for credentials
+
+You're ready to build! Start with simple calls like listing users or checking health, then gradually explore more functionality as you need it.

package/README.md

@@ -4,12 +4,14 @@ A comprehensive TypeScript client library for accessing Augur microservices with
 
 ## Table of Contents
 
+- [🚀 Quick Start Guide](./QUICKSTART.md) - **New to Augur API? Start here!**
 - [Overview](#overview)
 - [🎯 AI-Powered Discovery System - Where Code Writes Itself](#-ai-powered-discovery-system---where-code-writes-itself)
+- [📖 API Discovery Guide](./API-DISCOVERY.md) - Complete discovery system reference
 - [Features](#features)
 - [Installation](#installation)
 - [Getting Started](#getting-started)
-- [Authentication & Security](#authentication--security)
+- [Authentication & Security](#authentication--security) | [📋 Complete Auth Guide](./AUTHENTICATION.md)
 - [API Documentation](#api-documentation)
 - [Advanced Features](#advanced-features)
 - [Integration Guides](#integration-guides)
@@ -303,7 +305,9 @@ const searchResults = await api.opensearch.itemSearch.search({
 
 ## Authentication & Security
 
-### Dual Authentication System
+> 📋 **[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:
 
@@ -331,75 +335,18 @@ 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)
+### Environment Variables Setup
 
 ```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);
-}
-```
-
-#### 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');
-
-if (result1.success) {
-  const tenantData = await result1.targetSiteAPI!.joomla.content.list({ limit: 10 });
-}
-```
-
-#### Option 3: Manual Approach
-
-```typescript
-// 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
-});
+// .env file
+AUGUR_SITE_ID=your-site-id
+AUGUR_JWT_TOKEN=your-jwt-token
 
-// 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
+// app.ts
+const api = new AugurAPI({
+  siteId: process.env.AUGUR_SITE_ID!,
+  bearerToken: process.env.AUGUR_JWT_TOKEN!,
 });
-
-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);
-}
 ```
 
 ### Dynamic Authentication Updates
@@ -422,28 +369,27 @@ async function refreshTokenIfNeeded() {
 }
 ```
 
-### Security Best Practices
+### Advanced: Cross-Site Authentication
 
-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
+For multi-tenant applications that need to authenticate users across different sites:
 
 ```typescript
-// ✅ Good: Environment-based configuration
-const api = new AugurAPI({
-  siteId: process.env.AUGUR_SITE_ID!,
-  bearerToken: getSecurelyStoredToken(), // From secure storage
-});
+import { authenticateUserForSite } from '@simpleapps-com/augur-api';
 
-// ❌ Bad: Hardcoded credentials
-const api = new AugurAPI({
-  siteId: 'hardcoded-site-id',
-  bearerToken: 'hardcoded-token', // Never do this!
+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

package/dist/cjs/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.2.6";
+export declare const VERSION = "0.2.7";
 export { AugurAPI } from './client';
 export { authenticateUserForSite, createCrossSiteAuthenticator, type CrossSiteAuthParams, type CrossSiteAuthResult, } from './utils/cross-site-auth';
 export { AugurAPIConfig, RequestConfig, type AugurContext, ContextCreationError, } from './core/config';

package/dist/cjs/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PaymentsClient = exports.P21PimClient = exports.OrdersClient = exports.CustomersClient = exports.AgrSiteClient = exports.LegacyClient = exports.NexusClient = exports.ItemsClient = exports.OpenSearchClient = exports.VMIClient = exports.PricingClient = exports.CommerceClient = exports.JoomlaClient = exports.PaginationParamsSchema = exports.HealthCheckDataSchema = exports.BaseResponseSchema = exports.RateLimitError = exports.NotFoundError = exports.AuthenticationError = exports.ValidationError = exports.AugurError = exports.ContextCreationError = exports.createCrossSiteAuthenticator = exports.authenticateUserForSite = exports.AugurAPI = exports.VERSION = void 0;
-exports.VERSION = '0.2.6';
+exports.VERSION = '0.2.7';
 // Main client
 var client_1 = require("./client");
 Object.defineProperty(exports, "AugurAPI", { enumerable: true, get: function () { return client_1.AugurAPI; } });

package/dist/esm/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.2.6";
+export declare const VERSION = "0.2.7";
 export { AugurAPI } from './client';
 export { authenticateUserForSite, createCrossSiteAuthenticator, type CrossSiteAuthParams, type CrossSiteAuthResult, } from './utils/cross-site-auth';
 export { AugurAPIConfig, RequestConfig, type AugurContext, ContextCreationError, } from './core/config';

package/dist/esm/index.js

@@ -1,4 +1,4 @@
-export const VERSION = '0.2.6';
+export const VERSION = '0.2.7';
 // Main client
 export { AugurAPI } from './client';
 // Utilities

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.2.6";
+export declare const VERSION = "0.2.7";
 export { AugurAPI } from './client';
 export { authenticateUserForSite, createCrossSiteAuthenticator, type CrossSiteAuthParams, type CrossSiteAuthResult, } from './utils/cross-site-auth';
 export { AugurAPIConfig, RequestConfig, type AugurContext, ContextCreationError, } from './core/config';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpleapps-com/augur-api",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "TypeScript client library for Augur microservices API endpoints",
   "keywords": [
     "augur",
@@ -26,7 +26,10 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "QUICKSTART.md",
+    "API-DISCOVERY.md",
+    "AUTHENTICATION.md"
   ],
   "scripts": {
     "build": "npm run build:cjs && npm run build:esm && npm run build:types && npm run build:package-json",