@simpleapps-com/augur-api 0.2.6 → 0.2.8

package/QUICKSTART.md

@@ -0,0 +1,352 @@
+# Experience the Magic: Zero to Production in 30 Seconds
+
+Transform enterprise API complexity into pure business intent with intelligent discovery and context-aware client generation.
+
+## The Magic Revealed
+
+Watch enterprise API chaos become elegant business logic:
+
+```typescript
+import { AugurAPI } from '@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 });
+```
+
+## Installation - One Command
+
+```bash
+npm install @simpleapps-com/augur-api
+```
+
+## First Contact: The 30-Second Demo
+
+### Instant Context Recognition
+
+```typescript
+// Your context object (middleware, tool handlers, etc.)
+const context = {
+  siteId: 'my-site-123',
+  jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
+  userId: 456
+};
+
+// Magic happens here - zero configuration
+const api = AugurAPI.fromContext(context);
+
+// 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`));
+```
+
+**Expected output:**
+```
+🚀 Connected to 13 business services
+Available capabilities:
+  joomla: 24 operations
+  commerce: 18 operations  
+  pricing: 12 operations
+  vmi: 31 operations
+  ...
+```
+
+### Natural Language Discovery
+
+```typescript
+// 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)})`);
+});
+
+// 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}`);
+});
+```
+
+## Business Domain Intelligence
+
+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
+});
+```
+
+### Inventory Management Intelligence
+
+```typescript
+// 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 }
+  ]
+});
+```
+
+## Context Patterns That Just Work
+
+### Framework Integration Magic
+
+```typescript
+// 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]);
+}
+```
+
+### Dual Access Pattern Innovation
+
+Every endpoint provides two access patterns for maximum developer productivity:
+
+```typescript
+// 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
+});
+```
+
+## Business Capability Explorer
+
+The platform connects you to comprehensive business operations across 13 microservices:
+
+| 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 |
+
+## Intelligent Caching Architecture
+
+Business-aware caching that understands data volatility:
+
+```typescript
+// Reference data - cache aggressively (8 hours)
+const categories = await api.items.categories.list({ edgeCache: 8 });
+const distributors = await api.vmi.distributors.list({ edgeCache: 8 });
+
+// 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 });
+
+// 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 });
+
+// Real-time operations - never cached
+const auth = await api.joomla.users.verifyPassword({ username, password });
+const checkout = await api.commerce.checkout.get(checkoutUid);
+```
+
+## Pattern Recognition & Workflows
+
+### Business Process Discovery
+
+```typescript
+// The platform understands business processes
+const customerJourney = await api.findEndpoint('customer lifecycle management');
+// Suggests: user creation → customer profile → order history → payment setup
+
+const inventoryWorkflow = await api.findEndpoint('inventory optimization');  
+// Suggests: availability check → replenishment calculation → distributor ordering
+
+const contentWorkflow = await api.findEndpoint('AI content generation');
+// Suggests: content analysis → AI enhancement → search optimization
+```
+
+### Advanced Search Intelligence
+
+```typescript
+// 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
+});
+
+// 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(', ')}`);
+});
+```
+
+## Next Steps: Explore the Platform
+
+- **[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
+
+## You're Now Ready for Production
+
+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
+
+The platform transforms enterprise API complexity into elegant business logic. Start building!
+
+## 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.