@simpleapps-com/augur-api/API-DISCOVERY.md

TypeScript client library for Augur microservices API endpoints

# AI-Powered Discovery: Code That Almost Writes Itself

Transform API exploration from documentation hunting into natural language conversation with intelligent business context understanding.

## The Discovery Revolution

Never memorize endpoints again. Ask for business functionality and let the platform's intelligence find everything you need:

```typescript
import { AugurAPI } from '@simpleapps-com/augur-api';

const api = AugurAPI.fromContext(context);

// Business intent discovery - no technical knowledge required
const customerOps = await api.findEndpoint('customer lifecycle management');
const inventoryFlow = await api.findEndpoint('supply chain optimization');
const ecommerceJourney = await api.findEndpoint('online shopping experience');

// Platform reveals complete business workflows
const services = await api.discover();
console.log(`🚀 ${services.length} intelligent business services available`);
```

## Semantic Intelligence Engine

### Business Context Understanding

The discovery system doesn't just match keywords - it understands business processes:

```typescript
// Ask about business outcomes, not technical endpoints
const results = await api.findEndpoint('customer satisfaction analytics');
// Intelligently maps to:
// - api.customers.customer.get (customer profiles)
// - api.orders.oeHdr.lookup (purchase history) 
// - api.p21Pim.items.suggestWebDescription (product experience)

const qualityControl = await api.findEndpoint('inventory quality assurance');
// Discovers:
// - api.vmi.invProfileHdr.checkAvailability (stock validation)
// - api.vmi.warehouses.list (distribution quality)
// - api.nexus.binTransfers.list (movement tracking)
```

### Cross-Service Workflow Intelligence

The platform maps relationships across all 13 microservices:

```typescript
// Working with users? Platform suggests customer operations
const userWorkflow = await api.findEndpoint('user account management');
// Reveals connected workflow:
// 1. Authentication: api.joomla.users.verifyPassword
// 2. Profile creation: api.customers.customer.create  
// 3. Permission setup: api.joomla.userGroups.list
// 4. Order access: api.orders.oeHdrSalesrep.getOrders

// Inventory management reveals pricing connections
const inventoryOps = await api.findEndpoint('warehouse operations');
// Platform intelligence connects:
// 1. Stock levels: api.vmi.invProfileHdr.checkAvailability
// 2. Pricing context: api.pricing.getPrice
// 3. Product details: api.items.products.get
// 4. Replenishment: api.vmi.invProfileHdr.replenish
```

## Advanced Discovery Capabilities

### Multi-Dimensional Search

The discovery engine uses sophisticated scoring across multiple dimensions:

```typescript
// Natural language with business filters
const results = await api.findEndpoint('customer service optimization', {
  domain: 'customer-management',     // Business domain focus
  readOnly: true,                   // Query operations only  
  minScore: 0.3,                    // High relevance threshold
  maxResults: 8,                    // Focused result set
  service: 'customers'              // Optional service filter
});

// Rich result context for each match
results.forEach(result => {
  console.log(`🎯 ${result.endpoint.fullPath} (${result.score.toFixed(2)})`);
  console.log(`   Business value: ${result.endpoint.description}`);
  console.log(`   Match reason: ${result.matchReason}`);
  console.log(`   Related ops: ${result.endpoint.relatedEndpoints.slice(0,3).join(', ')}`);
  console.log(`   Workflow: ${result.endpoint.domain}`);
});
```

## Business Intelligence Queries

The platform understands complex business scenarios and suggests complete workflows:

| Business Intent | Platform Discovery | Workflow Intelligence |
|----------------|-------------------|---------------------|
| `'customer lifecycle management'` | User authentication, customer profiles, order history, payment setup | Cross-service customer journey mapping |
| `'supply chain optimization'` | Inventory levels, warehouse operations, distributor networks, pricing | End-to-end supply chain visibility |
| `'e-commerce automation'` | Product search, pricing, cart management, checkout, payments | Complete shopping experience workflow |
| `'content personalization'` | AI content generation, search optimization, user preferences | Intelligent content delivery |
| `'order fulfillment intelligence'` | Order processing, inventory allocation, payment processing, shipping | Automated fulfillment workflows |
| `'business analytics integration'` | Customer data, order patterns, inventory metrics, pricing trends | Cross-service business intelligence |

## Semantic Discovery Architecture

### Rich Metadata Integration

Every endpoint includes comprehensive semantic metadata for AI agents:

```typescript
/**
 * @fullPath api.vmi.invProfileHdr.checkAvailability
 * @service vmi
 * @domain inventory-management
 * @searchTerms ["inventory", "stock levels", "availability", "warehouse"]
 * @relatedEndpoints ["api.vmi.warehouses.list", "api.pricing.getPrice", "api.items.products.get"]
 * @workflow ["inventory-optimization", "supply-chain-management"]
 * @commonPatterns ["Check product availability", "Validate stock levels", "Inventory monitoring"]
 * @businessRules ["Requires valid warehouse access", "Customer-specific inventory visibility"]
 * @performance "Real-time inventory queries, supports bulk operations"
 */
```

### AI Assistant Integration Excellence

When you ask an AI assistant for help, the platform provides complete context:

```typescript
// AI Assistant: "Help me optimize inventory management"
// Platform provides:
const inventoryWorkflow = await api.findEndpoint('inventory optimization');

// AI receives complete workflow context:
// 1. Business intent: Supply chain optimization
// 2. Primary operations: Stock checking, replenishment, distribution
// 3. Related services: Pricing, product catalog, warehouse management
// 4. Workflow patterns: Check → Calculate → Order → Track
// 5. Performance considerations: Real-time vs batch operations
```

## Advanced Business Domain Intelligence

### Multi-Service Business Processes

The platform maps complete business processes across service boundaries:

```typescript
// E-commerce customer acquisition workflow
const customerAcquisition = await api.findEndpoint('new customer onboarding');
// Platform intelligence suggests:
// Phase 1: Account Creation
//   - api.joomla.users.create (authentication)
//   - api.customers.customer.create (profile)
//   - api.joomla.userGroups.createMapping (permissions)
// Phase 2: Shopping Setup  
//   - api.commerce.cartHeaders.create (shopping cart)
//   - api.payments.unified.transactionSetup (payment method)
// Phase 3: Product Discovery
//   - api.opensearch.itemSearch.search (product exploration)
//   - api.pricing.getPrice (personalized pricing)

// Supply chain workflow intelligence
const supplyChain = await api.findEndpoint('inventory replenishment automation');
// Cross-service workflow mapping:
// Monitor: api.vmi.invProfileHdr.checkAvailability
// Calculate: api.pricing.getPrice (reorder costs)
// Execute: api.vmi.invProfileHdr.replenish
// Track: api.nexus.binTransfers.list
// Verify: api.vmi.warehouses.list (distribution status)
```

### Intelligent Search Filtering

Advanced filtering that understands business context:

```typescript
// Domain-specific operations
const customerService = await api.findEndpoint('customer support operations', {
  domain: 'customer-data',      // Business domain focus
  readOnly: true,               // Query operations only
  minScore: 0.4,               // High relevance threshold
  maxResults: 6                // Focused results
});

// Service-specific functionality 
const inventoryMgmt = await api.findEndpoint('warehouse management', {
  service: 'vmi',              // VMI service only
  domain: 'inventory-management', // Inventory domain
  minScore: 0.2,               // Include broader matches
  maxResults: 12               // Comprehensive results
});

// Workflow-specific operations
const ecommerceOps = await api.findEndpoint('online shopping', {
  domain: 'e-commerce',        // E-commerce domain
  readOnly: false,             // Include all operations
  minScore: 0.1,               // Cast wide net
  maxResults: 15               // Complete workflow
});
```

## Platform Discovery Mastery

### Complete Service Topology

```typescript
// Comprehensive platform exploration
const services = await api.discover();

// Platform intelligence reveals:
services.forEach(service => {
  console.log(`🏢 Service: ${service.serviceName}`);
  console.log(`   Business domain: ${service.description}`);
  console.log(`   Operations available: ${service.endpointCount}`);
  console.log(`   Base architecture: ${service.baseUrl}`);
  
  // Sample high-value operations
  const topOps = service.endpoints
    .filter(ep => ep.discoverable)
    .slice(0, 3);
    
  topOps.forEach(op => {
    console.log(`   🎯 ${op.fullPath}: ${op.description}`);
  });
});
```

### Business Workflow Discovery

```typescript
// Discover complete business workflows
const workflows = await Promise.all([
  api.findEndpoint('customer lifecycle'),
  api.findEndpoint('inventory optimization'), 
  api.findEndpoint('order fulfillment'),
  api.findEndpoint('content management'),
  api.findEndpoint('financial operations')
]);

// Platform reveals interconnected business processes
workflows.forEach((workflow, index) => {
  const domains = ['Customer', 'Inventory', 'Orders', 'Content', 'Finance'];
  console.log(`\n${domains[index]} Workflow (${workflow.length} operations):`);
  
  workflow.forEach(result => {
    console.log(`  📋 ${result.endpoint.fullPath}`);
    console.log(`     Business value: ${result.endpoint.description}`);
    console.log(`     Connects to: ${result.endpoint.relatedEndpoints.slice(0,2).join(', ')}`);
  });
});
```

The discovery system transforms API exploration into business conversation. Describe your business intent, and the platform's intelligence reveals complete workflows across all 13 microservices. No documentation hunting, no endpoint memorization - just natural language business queries that unlock enterprise capability.