@simpleapps-com/augur-api 0.2.7 → 0.2.9

package/QUICKSTART.md

@@ -1,205 +1,302 @@
-# Quick Start Guide
+# Experience the Magic: Zero to Production in 30 Seconds
 
-Get up and running with the Augur API Client in under 5 minutes.
+Transform enterprise API complexity into pure business intent with intelligent discovery and context-aware client generation.
 
-## What is This?
+## The Magic Revealed
 
-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.
+Watch enterprise API chaos become elegant business logic:
 
-## Installation
+```typescript
+import { AugurAPI } from '@simpleapps-com/augur-api';
 
-```bash
-npm install @simpleapps-com/augur-api
+// Instead of this enterprise nightmare (35+ lines)
+const userJwt = await getToken({ req: request });
+if (!userJwt?.jwtToken) {
+  throw new Error('Authentication failed');
+}
+const apiConfig = {
+  siteId: context.siteId,
+  bearerToken: userJwt.jwtToken,
+  timeout: 30000,
+  retries: 3,
+  headers: { 'x-site-id': context.siteId }
+};
+const api = new AugurAPI(apiConfig);
+
+// Pure business intent ✨
+const api = AugurAPI.fromContext(context);
+
+// Ask for anything - the system finds it
+const userOps = await api.findEndpoint('user management');
+const inventory = await api.findEndpoint('stock levels');
+const pricing = await api.findEndpoint('product pricing');
+
+// Code that reads like business requirements
+const users = await api.joomla.users.list({ limit: 10, edgeCache: 2 });
+const availability = await api.vmi.inventory.checkAvailability(warehouse);
+const price = await api.pricing.getPrice({ customerId, itemId, quantity });
 ```
 
-## Your First API Call
-
-### Step 1: Get Your Credentials
+## Installation - One Command
 
-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...`)
+```bash
+npm install @simpleapps-com/augur-api
+```
 
-Ask your system administrator or check your project's environment variables.
+## First Contact: The 30-Second Demo
 
-### Step 2: Make Your First Call
+### Instant Context Recognition
 
 ```typescript
-import { AugurAPI } from '@simpleapps-com/augur-api';
+// Your context object (middleware, tool handlers, etc.)
+const context = {
+  siteId: 'my-site-123',
+  jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
+  userId: 456
+};
 
-// 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
-});
+// Magic happens here - zero configuration
+const api = AugurAPI.fromContext(context);
 
-// 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);
-}
+// Verify the magic worked
+const services = await api.discover();
+console.log(`🚀 Connected to ${services.length} business services`);
+console.log('Available capabilities:');
+services.forEach(s => console.log(`  ${s.serviceName}: ${s.endpointCount} operations`));
 ```
 
-### Step 3: Verify It Works
-
-If you see output like this, you're ready to go:
+**Expected output:**
 ```
-Success! Found users: 5
-First user: John Smith
+🚀 Connected to 13 business services
+Available capabilities:
+  joomla: 24 operations
+  commerce: 18 operations  
+  pricing: 12 operations
+  vmi: 31 operations
+  ...
 ```
 
-## Common First Steps
-
-### Health Check (No Authentication Required)
-Test your connection without needing authentication:
+### Natural Language Discovery
 
 ```typescript
-const api = new AugurAPI({
-  siteId: 'your-site-id'
-  // No bearerToken needed for health checks
+// Never memorize endpoints again
+const userStuff = await api.findEndpoint('user management');
+console.log('User operations found:');
+userStuff.forEach(result => {
+  console.log(`  ${result.endpoint.fullPath} (${result.score.toFixed(2)})`);
 });
 
-const health = await api.joomla.getHealthCheck();
-console.log('Service is:', health.data.status); // Should show "OK"
+// Find inventory operations
+const inventoryOps = await api.findEndpoint('stock management');
+console.log('Inventory operations found:');
+inventoryOps.forEach(result => {
+  console.log(`  ${result.endpoint.fullPath} - ${result.matchReason}`);
+});
 ```
 
-### Environment Variables Setup
-Create a `.env` file in your project:
+## Business Domain Intelligence
 
-```bash
-# .env file
-AUGUR_SITE_ID=your-site-id-here
-AUGUR_JWT_TOKEN=your-jwt-token-here
+The platform understands your business context and connects related operations:
+
+### E-commerce Workflow Discovery
+
+```typescript
+// Search by business process, not technical implementation
+const ecommerce = await api.findEndpoint('customer shopping experience');
+
+// Platform suggests complete workflow:
+// 1. Product discovery: api.opensearch.itemSearch.search()
+// 2. Pricing calculation: api.pricing.getPrice() 
+// 3. Cart management: api.commerce.cartHeaders.lookup()
+// 4. Checkout process: api.commerce.checkout.get()
+// 5. Payment processing: api.payments.unified.transactionSetup()
+
+// Execute the workflow
+const products = await api.opensearch.itemSearch.search({
+  q: 'electrical wire 12 AWG',
+  searchType: 'query',
+  size: 20,
+  edgeCache: 4  // Intelligent caching
+});
+
+const pricing = await api.pricing.getPrice({
+  customerId: 12345,
+  itemId: products.data.items[0].item_id,
+  quantity: 100,
+  edgeCache: 3  // Business-aware TTL
+});
 ```
 
-Then use them in your code:
+### Inventory Management Intelligence
 
 ```typescript
-const api = new AugurAPI({
-  siteId: process.env.AUGUR_SITE_ID!,
-  bearerToken: process.env.AUGUR_JWT_TOKEN!
+// Natural language reveals complex operations
+const inventory = await api.findEndpoint('warehouse stock management');
+
+// Platform maps the complete inventory ecosystem:
+const warehouses = await api.vmi.warehouses.list({
+  customerId: 12345,
+  edgeCache: 4  // Reference data cached longer
+});
+
+const availability = await api.vmi.inventory.checkAvailability(warehouses.data[0].warehouse_uid, {
+  q: 'electrical'  // Smart search within inventory
+});
+
+// Context-aware replenishment
+await api.vmi.inventory.replenish(warehouse.warehouse_uid, {
+  distributor_uid: 789,
+  restock_items: [
+    { inv_mast_uid: 456, qty_to_order: 100.0 }
+  ]
 });
 ```
 
-## Understanding the Response Format
+## Context Patterns That Just Work
 
-All API calls return data in the same format:
+### Framework Integration Magic
 
 ```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
+// Express.js middleware
+app.use((req, res, next) => {
+  req.api = AugurAPI.fromContext({
+    siteId: req.headers['x-site-id'],
+    jwt: req.headers.authorization?.replace('Bearer ', ''),
+    userId: req.user?.id
+  });
+  next();
+});
+
+// Next.js API routes
+export default async function handler(req, res) {
+  const api = AugurAPI.fromContext({
+    siteId: process.env.NEXT_PUBLIC_SITE_ID,
+    jwt: req.session.accessToken
+  });
+  
+  const users = await api.joomla.users.list();
+  res.json(users);
+}
+
+// React components with hooks
+function useAugurAPI() {
+  const { session } = useAuth();
+  return useMemo(() => AugurAPI.fromContext({
+    siteId: process.env.REACT_APP_SITE_ID,
+    jwt: session?.token
+  }), [session]);
+}
 ```
 
-## Two Ways to Get Data
+### Dual Access Pattern Innovation
 
-Every API call has two versions:
+Every endpoint provides two access patterns for maximum developer productivity:
 
 ```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
+// Metadata-rich response (when you need context)
+const response = await api.joomla.users.list({ limit: 10 });
+console.log(`Found ${response.data.length} of ${response.totalResults} users`);
+console.log(`Request status: ${response.message}`);
+console.log(`Response metadata:`, response.params);
+
+// Pure data access (when you just want the data)
+const users = await api.joomla.users.listData({ limit: 10 });
+console.log(users); // Direct array - no wrapper object
+
+// Both methods support the same parameters and caching
+const cachedUsers = await api.joomla.users.listData({ 
+  limit: 10, 
+  edgeCache: 2  // Cache for 2 hours
+});
 ```
 
-## What Can You Do?
+## Business Capability Explorer
 
-The API gives you access to:
+The platform connects you to comprehensive business operations across 13 microservices:
 
-| 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()` |
+| Business Domain | Platform Services | Intelligence Level |
+|-----------------|-------------------|-------------------|
+| **User & Identity** | `joomla.users`, `customers.customer` | Cross-service user correlation |
+| **E-commerce** | `commerce.cartHeaders`, `opensearch.itemSearch`, `pricing.getPrice` | Complete shopping workflows |
+| **Inventory** | `vmi.warehouses`, `vmi.inventory`, `items.products` | Supply chain intelligence |
+| **Orders & Fulfillment** | `orders.orders`, `payments.unified`, `nexus.binTransfers` | End-to-end order processing |
+| **Content & AI** | `agrSite.settings`, `p21Pim.items.suggestWebDescription` | AI-enhanced content management |
 
-## Common Patterns
+## Intelligent Caching Architecture
+
+Business-aware caching that understands data volatility:
 
-### List Things with Limits
 ```typescript
-// Get first 10 users
-const users = await api.joomla.users.list({ limit: 10 });
+// Reference data - cache aggressively (8 hours)
+const categories = await api.items.categories.list({ edgeCache: 8 });
+const distributors = await api.vmi.distributors.list({ edgeCache: 8 });
 
-// Get first 20 products
-const products = await api.items.products.list({ limit: 20 });
-```
+// Operational data - moderate caching (2-4 hours)  
+const users = await api.joomla.users.list({ limit: 50, edgeCache: 2 });
+const warehouses = await api.vmi.warehouses.list({ customerId: 12345, edgeCache: 4 });
 
-### Get Single Items
-```typescript
-// Get specific user by ID
-const user = await api.joomla.users.get('123');
+// Transactional data - short caching (1 hour)
+const cart = await api.commerce.cartHeaders.list({ userId: 123, edgeCache: 1 });
+const pricing = await api.pricing.getPrice({ customerId, itemId, quantity, edgeCache: 1 });
 
-// Get specific product by ID  
-const product = await api.items.products.get(456);
+// Real-time operations - never cached
+const auth = await api.joomla.users.verifyPassword({ username, password });
+const checkout = await api.commerce.checkout.get(checkoutUid);
 ```
 
-### Search for Things
+## Pattern Recognition & Workflows
+
+### Business Process Discovery
+
 ```typescript
-// Search for products
-const results = await api.opensearch.itemSearch.search({
-  q: 'wire',           // Search term
-  size: 10             // Number of results
-});
-```
+// The platform understands business processes
+const customerJourney = await api.findEndpoint('customer lifecycle management');
+// Suggests: user creation → customer profile → order history → payment setup
 
-## Performance Tip: Caching
+const inventoryWorkflow = await api.findEndpoint('inventory optimization');  
+// Suggests: availability check → replenishment calculation → distributor ordering
 
-Add caching to make your app faster:
+const contentWorkflow = await api.findEndpoint('AI content generation');
+// Suggests: content analysis → AI enhancement → search optimization
+```
+
+### Advanced Search Intelligence
 
 ```typescript
-// Cache user list for 2 hours
-const users = await api.joomla.users.list({ 
-  limit: 10,
-  edgeCache: 2  // Cache for 2 hours
+// Multi-criteria business search
+const results = await api.findEndpoint('customer service operations', {
+  domain: 'customer-management',  // Business domain filter
+  readOnly: true,                // Only query operations
+  minScore: 0.3,                 // High relevance threshold
+  maxResults: 5                  // Focused results
 });
 
-// Cache product search for 4 hours
-const products = await api.opensearch.itemSearch.search({
-  q: 'electrical',
-  size: 20,
-  edgeCache: 4  // Cache for 4 hours
+// Each result includes business context
+results.forEach(result => {
+  console.log(`Operation: ${result.endpoint.fullPath}`);
+  console.log(`Business value: ${result.endpoint.description}`);
+  console.log(`Workflow stage: ${result.endpoint.domain}`);
+  console.log(`Related ops: ${result.endpoint.relatedEndpoints.join(', ')}`);
 });
 ```
 
-**Cache Options:** 1, 2, 3, 4, 5, or 8 hours only.
+## Next Steps: Explore the Platform
 
-## Don't Know What's Available?
+- **[Complete Platform Guide](./README.md)** - Discover all advanced capabilities
+- **[AI Discovery System](./API-DISCOVERY.md)** - Master natural language API navigation  
+- **[Integration Patterns](./README.md#platform-integration)** - React, Next.js, Node.js examples
+- **[Performance Optimization](./README.md#performance--caching)** - Advanced caching strategies
 
-Use the discovery system to explore:
+## You're Now Ready for Production
 
-```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');
-```
+You've experienced the magic:
+- ✅ Context-aware client creation eliminates boilerplate
+- ✅ Natural language discovery replaces documentation hunting
+- ✅ Business-aware caching optimizes performance automatically
+- ✅ Cross-service intelligence reveals complete workflows
+- ✅ Dual access patterns maximize developer productivity
 
-Learn more in the [API Discovery Guide](./API-DISCOVERY.md).
+The platform transforms enterprise API complexity into elegant business logic. Start building!
 
 ## Error Handling