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

TypeScript client library for Augur microservices API endpoints

# API Services Reference

Complete reference for all 20+ available API services in the Augur Platform. Each service provides specialized business functionality with consistent authentication, validation, and discovery patterns.

> **🚀 NEW in v0.4.0**: All services now implement OpenAPI Path Mirroring Pattern with dual API access (standard + data methods), comprehensive schema organization, and enhanced AI-powered discovery.

## Core Business Services

### Content & User Management

| Service | Description | OpenAPI Spec | Postman Collection |
|---------|-------------|--------------|-------------------|
| **joomla** | Content management system integration with user authentication, content publishing, and permission management | [OpenAPI](https://joomla.augur-api.com/openapi.json) | [Postman](https://joomla.augur-api.com/postman.json) |

### E-commerce & Shopping

| Service | Description | OpenAPI Spec | Postman Collection |
|---------|-------------|--------------|-------------------|
| **commerce** | E-commerce operations including shopping cart management, checkout processing, and product recommendations | [OpenAPI](https://commerce.augur-api.com/openapi.json) | [Postman](https://commerce.augur-api.com/postman.json) |

### Product Catalog & Search

| Service | Description | OpenAPI Spec | Postman Collection |
|---------|-------------|--------------|-------------------|
| **items** | Product catalog management with categories, attributes, variants, and inventory master data | [OpenAPI](https://items.augur-api.com/openapi.json) | [Postman](https://items.augur-api.com/postman.json) |
| **openSearch** | Advanced product search with faceted navigation, filters, and search analytics | [OpenAPI](https://open-search.augur-api.com/openapi.json) | [Postman](https://open-search.augur-api.com/postman.json) |

### Customer & Order Management

| Service | Description | OpenAPI Spec | Postman Collection |
|---------|-------------|--------------|-------------------|
| **customers** | Customer relationship management with profiles, contacts, addresses, and purchase history | [OpenAPI](https://customers.augur-api.com/openapi.json) | [Postman](https://customers.augur-api.com/postman.json) |
| **orders** | Order processing and management including invoices, purchase orders, and sales representative operations | [OpenAPI](https://orders.augur-api.com/openapi.json) | [Postman](https://orders.augur-api.com/postman.json) |

### Pricing & Financial

| Service | Description | OpenAPI Spec | Postman Collection |
|---------|-------------|--------------|-------------------|
| **pricing** | Dynamic pricing engine with job pricing, quantity breaks, and customer-specific pricing rules | [OpenAPI](https://pricing.augur-api.com/openapi.json) | [Postman](https://pricing.augur-api.com/postman.json) |
| **payments** | Payment processing with multiple gateways, unified payment methods, and transaction management | [OpenAPI](https://payments.augur-api.com/openapi.json) | [Postman](https://payments.augur-api.com/postman.json) |

### Inventory & Warehouse

| Service | Description | OpenAPI Spec | Postman Collection |
|---------|-------------|--------------|-------------------|
| **vmi** | Vendor Managed Inventory with warehouse operations, stock profiles, and automated replenishment | [OpenAPI](https://vmi.augur-api.com/openapi.json) | [Postman](https://vmi.augur-api.com/postman.json) |
| **nexus** | Warehouse management system with bin transfers, receiving operations, and shipping coordination | [OpenAPI](https://nexus.augur-api.com/openapi.json) | [Postman](https://nexus.augur-api.com/postman.json) |

### Product Information & Data

| Service | Description | OpenAPI Spec | Postman Collection |
|---------|-------------|--------------|-------------------|
| **p21Pim** | Product Information Management with AI-powered suggestions and enhanced product data | [OpenAPI](https://p21-pim.augur-api.com/openapi.json) | [Postman](https://p21-pim.augur-api.com/postman.json) |

### AGR Platform Services

| Service | Description | OpenAPI Spec | Postman Collection |
|---------|-------------|--------------|-------------------|
| **agrSite** | AGR-specific site operations including transcripts, notifications, and platform settings | [OpenAPI](https://agr-site.augur-api.com/openapi.json) | [Postman](https://agr-site.augur-api.com/postman.json) |

### Legacy Integration

| Service | Description | OpenAPI Spec | Postman Collection |
|---------|-------------|--------------|-------------------|
| **legacy** | Legacy system integration providing backward compatibility for existing data and workflows | [OpenAPI](https://legacy.augur-api.com/openapi.json) | [Postman](https://legacy.augur-api.com/postman.json) |

## Integration & Specialized Services

### AGR Business Intelligence

| Service | Description | OpenAPI Spec | Postman Collection |
|---------|-------------|--------------|-------------------|
| **agrInfo** | AGR business intelligence and reporting services with analytics and data insights | [OpenAPI](https://agr-info.augur-api.com/openapi.json) | [Postman](https://agr-info.augur-api.com/postman.json) |
| **agrWork** | AGR workflow automation and task management for business process optimization | [OpenAPI](https://agr-work.augur-api.com/openapi.json) | [Postman](https://agr-work.augur-api.com/postman.json) |

### Tax & Compliance

| Service | Description | OpenAPI Spec | Postman Collection |
|---------|-------------|--------------|-------------------|
| **Avalara** | Tax calculation and compliance services with automated tax determination and reporting | [OpenAPI](https://avalara.augur-api.com/openapi.json) | [Postman](https://avalara.augur-api.com/postman.json) |

### Brand & Marketing

| Service | Description | OpenAPI Spec | Postman Collection |
|---------|-------------|--------------|-------------------|
| **brandFolder** | Digital asset management for brand materials, marketing content, and media resources | [OpenAPI](https://brand-folder.augur-api.com/openapi.json) | [Postman](https://brand-folder.augur-api.com/postman.json) |

### Third-Party Integrations

| Service | Description | OpenAPI Spec | Postman Collection |
|---------|-------------|--------------|-------------------|
| **gregorovich** | AI-powered document management and conversational AI with ChatGPT and Ollama integration | [OpenAPI](https://gregorovich.augur-api.com/openapi.json) | [Postman](https://gregorovich.augur-api.com/postman.json) |

### Logistics & Shipping

| Service | Description | OpenAPI Spec | Postman Collection |
|---------|-------------|--------------|-------------------|
| **logistics** | Advanced logistics and supply chain optimization with route planning and delivery coordination | [OpenAPI](https://logistics.augur-api.com/openapi.json) | [Postman](https://logistics.augur-api.com/postman.json) |
| **shipping** | Shipping services with rate calculation, label generation, and tracking integration | [OpenAPI](https://shipping.augur-api.com/openapi.json) | [Postman](https://shipping.augur-api.com/postman.json) |

### Address & Location Services

| Service | Description | OpenAPI Spec | Postman Collection |
|---------|-------------|--------------|-------------------|
| **smartyStreets** | Address validation, verification, and standardization services for accurate shipping and billing | [OpenAPI](https://smarty-streets.augur-api.com/openapi.json) | [Postman](https://smarty-streets.augur-api.com/postman.json) |

### Carrier Integration

| Service | Description | OpenAPI Spec | Postman Collection |
|---------|-------------|--------------|-------------------|
| **ups** | UPS shipping integration with rate calculation, label printing, and package tracking | [OpenAPI](https://ups.augur-api.com/openapi.json) | [Postman](https://ups.augur-api.com/postman.json) |

### Communication & Collaboration

| Service | Description | OpenAPI Spec | Postman Collection |
|---------|-------------|--------------|-------------------|
| **slack** | Slack integration for team notifications, workflow alerts, and business process communication | [OpenAPI](https://slack.augur-api.com/openapi.json) | [Postman](https://slack.augur-api.com/postman.json) |

## Prophet 21 ERP Integration

### Direct System Access

| Service | Description | OpenAPI Spec | Postman Collection |
|---------|-------------|--------------|-------------------|
| **p21Apis** | Direct Prophet 21 API integration providing access to core ERP functionality and data | [OpenAPI](https://p21-apis.augur-api.com/openapi.json) | [Postman](https://p21-apis.augur-api.com/postman.json) |
| **p21Core** | Prophet 21 core business objects including master data, transactions, and system configuration | [OpenAPI](https://p21-core.augur-api.com/openapi.json) | [Postman](https://p21-core.augur-api.com/postman.json) |

### System Integration & Synchronization

| Service | Description | OpenAPI Spec | Postman Collection |
|---------|-------------|--------------|-------------------|
| **p21Sism** | Prophet 21 System Integration and Synchronization Management for data consistency and workflow automation | [OpenAPI](https://p21-sism.augur-api.com/openapi.json) | [Postman](https://p21-sism.augur-api.com/postman.json) |

## v0.4.0 OpenAPI Path Mirroring Examples

### Path-to-Client Structure Mapping
**Every OpenAPI path maps directly to client structure:**

```typescript
// AI and Document Services (Gregorovich)
await api.gregorovich.chatGpt.ask.get({ question: "How do I optimize inventory?" });
await api.gregorovich.documents.list();
await api.gregorovich.ollama.generate.create({ prompt: "Generate description" });

// Advanced Search (OpenSearch)
await api.openSearch.ping.get();
await api.openSearch.healthCheck.get();
await api.openSearch.itemSearch.list({ query: "tools" });
await api.openSearch.itemSearch.attributes.list({ category: "power" });
await api.openSearch.items.refresh.update({ force: true });
await api.openSearch.items.get(invMastUid);

// Vendor Managed Inventory (VMI)
await api.vmi.warehouses.list({ customerId: 123 });
await api.vmi.invProfileHdr.list({ warehouseId: 456 });
await api.vmi.distributors.list({ active: true });
```

### Dual API Pattern (All Services)
**Standard + Data methods for every endpoint:**

```typescript
// Standard method - complete BaseResponse
const response = await api.gregorovich.chatGpt.ask.get({ question: "What is AI?" });
console.log(response.data.answer);     // AI response
console.log(response.status);          // HTTP 200
console.log(response.message);         // Success message

// Data method - direct access to data
const aiData = await api.gregorovich.chatGpt.ask.getData({ question: "What is AI?" });
console.log(aiData.answer);           // Direct access to answer
```

## Quick Usage Reference

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

// Initialize with context (recommended)
const api = AugurAPI.fromContext(context);

// Or initialize manually
const api = new AugurAPI({
  siteId: 'your-site-id',
  bearerToken: 'your-jwt-token'
});
```

### Service Discovery
```typescript
// Discover all available services
const services = await api.discover();
console.log(`${services.length} services available`);

// Find specific functionality
const results = await api.findEndpoint('inventory management');
```

### Common Access Patterns
```typescript
// Access any service
const users = await api.joomla.users.list();
const products = await api.items.products.search({ q: 'widgets' });
const orders = await api.commerce.cartHeaders.lookup({ userId: 123 });

// Use data-only methods for cleaner code
const userData = await api.joomla.users.listData();
const productData = await api.items.products.searchData({ q: 'widgets' });
```

## Authentication Requirements

- **All Services**: Require Bearer JWT token and x-site-id header
- **Health Checks**: No authentication required
- **Cross-Site Operations**: Some services support multi-site operations with appropriate permissions

## Support Resources

- **Complete Documentation**: See [README.md](./README.md)
- **Quick Start Guide**: See [QUICKSTART.md](./QUICKSTART.md)  
- **AI Discovery Guide**: See [API-DISCOVERY.md](./API-DISCOVERY.md)
- **Development Standards**: See [CLAUDE.md](./CLAUDE.md)

---

*This document is automatically maintained and reflects the current state of all available API services.*