@simpleapps-com/augur-api 0.2.5 → 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.