@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 26 active 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 26 active microservices. No documentation hunting, no endpoint memorization - just natural language business queries that unlock enterprise capability.