@simpleapps-com/augur-api 0.2.7 → 0.2.8

package/README.md

@@ -1,150 +1,421 @@
-# Augur API Client Library
+# The Augur Platform: Code That Almost Writes Itself
 
-A comprehensive TypeScript client library for accessing Augur microservices with type safety, runtime validation, edge caching, and excellent developer experience.
+Transform enterprise API chaos into developer flow with intelligent client generation, context-aware discovery, and AI-powered development acceleration.
+
+## Experience the Magic in 30 Seconds
+
+```typescript
+// Before: 35+ lines of authentication boilerplate
+const userJwt = await getToken({ req: request });
+if (!userJwt?.jwtToken) throw new Error('Authentication failed');
+const api = new AugurAPI({ siteId: context.siteId, bearerToken: userJwt.jwtToken });
+
+// After: Pure business intent ✨
+const api = AugurAPI.fromContext(context);
+
+// Ask for anything and find it instantly
+const userOps = await api.findEndpoint('user management');
+const inventory = await api.findEndpoint('stock levels'); 
+const pricing = await api.findEndpoint('product pricing');
+
+// Code that understands your business domain
+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 });
+```
 
 ## 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) | [📋 Complete Auth Guide](./AUTHENTICATION.md)
-- [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)
+- [🚀 Quick Start Guide](./QUICKSTART.md) - **Experience the magic in under 5 minutes**
+- [The Five Ideals in Action](#the-five-ideals-in-action)
+- [🎯 AI-Powered Discovery System](#-ai-powered-discovery-system)
+- [📖 API Discovery Guide](./API-DISCOVERY.md) - Natural language API navigation
+- [Developer Experience Revolution](#developer-experience-revolution)
+- [Context-Aware Architecture](#context-aware-architecture)
+- [Installation & First Steps](#installation--first-steps)
+- [Intelligent Discovery Examples](#intelligent-discovery-examples)
+- [Cross-Service Intelligence](#cross-service-intelligence)
+- [Advanced Capabilities](#advanced-capabilities)
+- [Platform Integration](#platform-integration)
+- [Performance & Caching](#performance--caching)
+- [Troubleshooting & Support](#troubleshooting--support)
 
-## Overview
+## The Five Ideals in Action
 
-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.
+This platform embodies the Five Ideals from The Unicorn Project, transforming how developers interact with enterprise APIs:
 
-### Key Capabilities
+### Locality and Simplicity ✨
+**No more coordination across 13 different APIs.** One unified interface eliminates architectural complexity.
 
-- **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
+```typescript
+// Instead of learning 13 different authentication patterns
+await joomlaAPI.authenticate(token);
+await commerceAPI.setAuth(bearer);
+await pricingAPI.login(credentials);
+
+// One pattern rules them all
+const api = AugurAPI.fromContext(context);
+```
 
-## IDE Support & AI Assistant Integration
+### Focus, Flow, and Joy 🎯
+**Zero context switching.** Intelligent discovery means never leaving your flow state.
 
-This client library is designed to work seamlessly with modern IDEs and AI coding assistants through comprehensive semantic documentation.
+```typescript
+// No documentation hunting, no API reference browsing
+const results = await api.findEndpoint('inventory management');
+// Instantly find: api.vmi.warehouses.list, api.vmi.inventory.checkAvailability
 
-### IntelliSense & Auto-completion
+// Your IDE becomes clairvoyant with comprehensive semantic JSDoc
+api.vmi.inventory. // ← Auto-complete shows exactly what you need
+```
 
-Every method includes detailed JSDoc with:
-- **Parameter descriptions** and types
-- **Usage examples** with real code
-- **Related methods** and cross-service connections
-- **Business context** and workflow information
+### Improvement of Daily Work 🔄
+**The platform learns your patterns** and suggests related operations across services.
 
 ```typescript
-client.agrSite.settings. // ← IDE shows all available methods with descriptions
+// When you work with users, it suggests related customer operations
+const user = await api.joomla.users.get('123');
+// Related suggestions: api.customers.customer.get, api.orders.salesRep.getOrders
 ```
 
-### AI Assistant Features
+### Psychological Safety 🛡️
+**Fail fast with clear, actionable errors.** No more guessing what went wrong.
 
-The semantic JSDoc tags help AI assistants understand:
+```typescript
+try {
+  const api = AugurAPI.fromContext(context);
+} catch (error) {
+  // Clear guidance: "Context missing siteId - check your context.siteId property"
+  // No blame, just solutions
+}
+```
+
+### Customer Focus 📊
+**Business context embedded** in every endpoint. Search by business intent, not technical implementation.
+
+```typescript
+// Search by what you're trying to accomplish
+await api.findEndpoint('customer order history');
+await api.findEndpoint('product recommendations');
+await api.findEndpoint('inventory replenishment');
+```
+
+## AI-Powered Discovery System
+
+**Never memorize API endpoints again.** The discovery system understands business context and finds functionality through natural language.
+
+### Semantic Intelligence
+
+Every endpoint includes AI-readable metadata:
 
 ```typescript
 /**
- * @searchTerms ["settings", "configuration", "site config"]
- * @relatedEndpoints ["api.agrSite.settings.get", "api.agrSite.settings.update"]
- * @workflow ["settings-management", "site-configuration"]
- * @commonPatterns ["Get all settings", "List site configuration"]
+ * @searchTerms ["users", "authentication", "user management", "login"]
+ * @relatedEndpoints ["api.customers.customer.get", "api.joomla.userGroups.list"]
+ * @workflow ["user-onboarding", "authentication-flow", "user-administration"]
+ * @commonPatterns ["Get user profile", "List active users", "Create new account"]
  */
 ```
 
-This means when you ask an AI assistant to "help me manage site settings", it can:
-1. Find the right service (`agrSite.settings`)
-2. Suggest the correct method (`list`, `get`, `create`, etc.)
-3. Show related operations you might need
-4. Provide complete workflow examples
+### Cross-Service Awareness
+
+The system maps relationships between all 13 microservices:
+
+```typescript
+// Working with users? It knows you might need customers too
+const userEndpoints = await api.findEndpoint('user management');
+// Suggests: joomla.users.list, customers.customer.get, orders.salesRep.getOrders
+
+// Working with inventory? It connects you to pricing
+const inventoryOps = await api.findEndpoint('stock management'); 
+// Suggests: vmi.warehouses.list, pricing.getPrice, items.products.get
+```
 
-### Dual API Pattern
+## Developer Experience Revolution
 
-Each service provides two ways to call methods:
+### Context-Aware Creation
+Eliminate 70% of setup boilerplate with intelligent context extraction:
 
 ```typescript
-// Standard method - returns full response with metadata
-const response = await client.agrSite.settings.list();
-console.log(response.data, response.total, response.message);
+// Traditional enterprise pattern (35+ lines)
+const authentication = await authenticateUser(request);
+if (!authentication.success) {
+  return handleAuthFailure(authentication.error);
+}
+const siteContext = await resolveSiteContext(authentication.user);
+const apiConfig = {
+  siteId: siteContext.siteId,
+  bearerToken: authentication.jwtToken,
+  timeout: getConfiguredTimeout(),
+  retries: getRetryPolicy()
+};
+const api = new AugurAPI(apiConfig);
 
-// Data method - returns only the data portion
-const settings = await client.agrSite.settings.listData();
-console.log(settings); // Direct array access
+// Context-aware magic (1 line)
+const api = AugurAPI.fromContext(context);
 ```
 
-### API Discovery Functions
+### Intelligent Method Discovery
+Every method includes rich semantic metadata for AI assistants:
 
-The client provides discovery functions for exploring available services and endpoints:
+```typescript
+// Ask your AI assistant: "Help me manage warehouse inventory"
+// It instantly finds and suggests:
+await api.vmi.warehouses.list({ customerId: 12345 });
+await api.vmi.inventory.checkAvailability(warehouseId);
+await api.vmi.inventory.replenish(warehouseId, { items });
+```
 
-#### `discover()` - Service Map
+### Factory Pattern Excellence
+Sophisticated factory patterns create consistent, discoverable APIs:
 
-Get an overview of available services and their discoverable endpoints:
+```typescript
+// Auto-generated from OpenAPI specs with semantic enhancement
+export class VMIClient extends BaseServiceClient {
+  get warehouses() { return this.createWarehouseOperations(); }
+  get inventory() { return this.createInventoryOperations(); }
+  get distributors() { return this.createDistributorOperations(); }
+}
+```
+
+## Installation & First Steps
+
+```bash
+npm install @simpleapps-com/augur-api
+```
+
+### Immediate Value Demo
 
 ```typescript
-const api = new AugurAPI({ siteId: 'my-site', bearerToken: 'token' });
+import { AugurAPI } from '@simpleapps-com/augur-api';
+
+// Create from context (eliminates boilerplate)
+const api = AugurAPI.fromContext(context);
+
+// Discover capabilities (no documentation needed)
 const services = await api.discover();
+console.log(`Connected to ${services.length} business services`);
 
-// Returns ServiceMap[] with:
-// - serviceName: string
-// - description: string  
-// - baseUrl: string
-// - endpointCount: number
-// - endpoints: DiscoveryEndpoint[]
+// Find what you need (natural language)
+const userStuff = await api.findEndpoint('user management');
+const inventoryStuff = await api.findEndpoint('stock levels');
 
-services.forEach(service => {
-  console.log(`${service.serviceName}: ${service.endpointCount} endpoints`);
+// Work with intelligent caching (sub-100ms responses)
+const users = await api.joomla.users.list({ 
+  limit: 10,
+  edgeCache: 2  // Cloudflare edge caching
 });
 ```
 
-#### `findEndpoint()` - Endpoint Search
+## Intelligent Discovery Examples
+
+### Business Context Understanding
 
-Search across services for endpoints matching a search term:
+The platform knows your business domain and connects related operations:
 
 ```typescript
-// Basic search
-const results = await api.findEndpoint('users');
+// Search by business intent, not technical endpoints
+const userOps = await api.findEndpoint('customer account management');
+// Returns: 
+// - api.joomla.users.list (user authentication)
+// - api.customers.customer.get (customer profiles) 
+// - api.orders.salesRep.getOrders (order history)
+
+const inventoryOps = await api.findEndpoint('stock replenishment');
+// Returns:
+// - api.vmi.inventory.checkAvailability (current levels)
+// - api.vmi.inventory.replenish (automated ordering)
+// - api.pricing.getPrice (cost calculations)
+```
+
+### Workflow-Aware Suggestions
 
-// With options
-const results = await api.findEndpoint('settings', {
-  minScore: 0.1,         // Minimum relevance score (default: 0.1)
-  maxResults: 10,        // Max results (default: 10)
-  service: 'agrSite',    // Filter by service
-  domain: 'site-content-management', // Filter by domain
-  readOnly: true         // Only GET endpoints
+Working on one task? The system suggests the next logical steps:
+
+```typescript
+// Create a user account
+const newUser = await api.joomla.users.create({
+  username: 'john.doe',
+  email: 'john@company.com'
 });
 
-// Returns EndpointSearchResult[] with:
-// - endpoint: DiscoveryEndpoint (with fullPath, service, domain, etc.)
-// - score: number (0-1 relevance)
-// - matchReason: string
+// System knows you might need to:
+// 1. Set up customer profile: api.customers.customer.create()
+// 2. Assign user groups: api.joomla.userGroups.createMapping() 
+// 3. Check permissions: api.joomla.users.groups.list()
+```
+
+### Cross-Service Intelligence
+
+The discovery system maps business workflows across all 13 microservices:
+
+```typescript
+// E-commerce workflow discovery
+const ecommerceFlow = await api.findEndpoint('online shopping');
+// Suggests complete customer journey:
+// - Product search: api.opensearch.itemSearch.search()
+// - Pricing: api.pricing.getPrice()
+// - Cart management: api.commerce.cartHeaders.lookup()
+// - Checkout: api.commerce.checkout.get()
+// - Payment: api.payments.unified.transactionSetup()
 ```
 
-## Features
+## Context-Aware Architecture
+
+### Intelligent Context Extraction
+
+The `fromContext()` method understands various context patterns:
+
+```typescript
+// Middleware context
+const api = AugurAPI.fromContext({
+  siteId: req.headers['x-site-id'],
+  jwt: req.headers.authorization?.replace('Bearer ', ''),
+  userId: req.user.id
+});
+
+// Tool handler context
+const api = AugurAPI.fromContext({
+  siteId: context.siteId,
+  bearerToken: context.authentication.token,
+  parameters: context.requestParams
+});
+
+// Next.js context
+const api = AugurAPI.fromContext({
+  siteId: process.env.NEXT_PUBLIC_SITE_ID,
+  jwt: session.accessToken
+});
+```
+
+### Factory Pattern Excellence
+
+Each service client is lazily instantiated with sophisticated caching:
+
+```typescript
+// Clients are created on-demand and cached
+const joomla1 = api.joomla;  // Creates new instance
+const joomla2 = api.joomla;  // Returns cached instance
+console.log(joomla1 === joomla2); // true
+
+// Token changes invalidate all clients automatically
+api.setAuthToken('new-token');
+const joomla3 = api.joomla;  // Creates fresh instance with new token
+console.log(joomla1 === joomla3); // false
+```
+
+### Semantic Method Generation
+
+Every endpoint includes rich semantic metadata for AI discovery:
+
+```typescript
+/**
+ * List site settings with intelligent filtering and caching
+ * @fullPath api.agrSite.settings.list
+ * @service agr-site
+ * @domain site-content-management
+ * @searchTerms ["settings", "configuration", "site management", "admin"]
+ * @relatedEndpoints ["api.agrSite.settings.get", "api.agrSite.settings.update"]
+ * @workflow ["site-administration", "configuration-management"]
+ * @commonPatterns ["Get all settings", "Filter by service", "Cache configuration"]
+ * @discoverable true
+ */
+async list(params?: SettingListParams): Promise<SettingListResponse> {
+  // Implementation uses sophisticated base class patterns
+}
+```
+
+## Advanced Capabilities
+
+### Intelligent Service Discovery
+
+The discovery system provides both exploration and targeted search:
+
+```typescript
+// Comprehensive service topology
+const services = await api.discover();
+console.log(`Platform connected to ${services.length} business services`);
+
+// Each service reveals its capabilities
+services.forEach(service => {
+  console.log(`${service.serviceName}: ${service.endpointCount} operations available`);
+  console.log(`Business domain: ${service.description}`);
+});
+
+// Targeted functionality search with intelligent scoring
+const results = await api.findEndpoint('inventory management', {
+  minScore: 0.1,    // Relevance threshold
+  maxResults: 10,   // Limit results
+  service: 'vmi',   // Optional service filter
+  domain: 'inventory-management', // Business domain filter
+  readOnly: true    // Only read operations
+});
+
+// Results include relevance scores and match reasoning
+results.forEach(result => {
+  console.log(`${result.endpoint.fullPath} (score: ${result.score})`);
+  console.log(`Match reason: ${result.matchReason}`);
+});
+```
+
+### Multi-Method Pattern Innovation
+
+Every endpoint offers dual access patterns for maximum flexibility:
+
+```typescript
+// Full response with metadata (standard pattern)
+const response = await api.joomla.users.list({ limit: 10 });
+console.log(`Found ${response.data.length} users`);
+console.log(`Total available: ${response.totalResults}`);
+console.log(`Status: ${response.message}`);
+
+// Data-only access (streamlined pattern)  
+const users = await api.joomla.users.listData({ limit: 10 });
+console.log(users); // Direct array access, no wrapper
+```
+
+### Sophisticated Caching Architecture
+
+Intelligent edge caching with business-aware TTL policies:
+
+```typescript
+// Cache strategy varies by data volatility
+const categories = await api.items.categories.list({
+  edgeCache: 8  // Static reference data - 8 hours
+});
+
+const pricing = await api.pricing.getPrice({
+  customerId: 12345,
+  itemId: 'STANDARD-ITEM', 
+  quantity: 10,
+  edgeCache: 3  // Standard pricing - 3 hours
+});
+
+const cart = await api.commerce.cartHeaders.list({
+  userId: 123,
+  edgeCache: 1  // Volatile user data - 1 hour only
+});
+
+// Real-time operations never cached
+const auth = await api.joomla.users.verifyPassword({
+  username: 'user',
+  password: 'pass'
+  // No edgeCache - authentication must be real-time
+});
+```
 
-✅ **Context-Aware Magic** - Eliminate 70% of setup boilerplate with `fromContext()` ⭐ NEW!  
-✅ **AI-Powered Discovery** - Natural language search finds any functionality instantly  
-✅ **Semantic Intelligence** - Understands business context and suggests workflows  
-✅ **Cross-Service Awareness** - Maps relationships between all microservices  
-✅ **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  
+## Platform Capabilities Matrix
+
+| Capability | Impact | Technical Implementation |
+|------------|--------|-------------------------|
+| **Context-Aware Creation** | 70% boilerplate reduction | `AugurAPI.fromContext()` with intelligent field extraction |
+| **Natural Language Discovery** | Zero API documentation hunting | Semantic JSDoc parsing with cross-service mapping |
+| **Intelligent Caching** | Sub-100ms response times | Cloudflare edge integration with business-aware TTL |
+| **Factory Pattern Excellence** | Consistent developer experience | Lazy instantiation with automatic cache invalidation |
+| **Cross-Service Intelligence** | Business workflow awareness | Relationship mapping across 13 microservices |
+| **AI Assistant Integration** | Code that almost writes itself | Rich semantic metadata in every endpoint |
+| **Type Safety** | Runtime validation guarantee | Zod schema validation on all requests/responses |
+| **Multi-Platform Support** | Universal JavaScript compatibility | React, React Native, Next.js, Node.js, Electron |  
 
 ## Installation
 

package/dist/cjs/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.2.7";
+export declare const VERSION = "0.2.8";
 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.7';
+exports.VERSION = '0.2.8';
 // Main client
 var client_1 = require("./client");
 Object.defineProperty(exports, "AugurAPI", { enumerable: true, get: function () { return client_1.AugurAPI; } });