@simpleapps-com/augur-api 0.1.0

package/README.md

@@ -0,0 +1,750 @@
+# Augur API Client Library
+
+A TypeScript client library for accessing Augur microservices with type safety, runtime validation, and excellent developer experience.
+
+## Features
+
+- 🚀 **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
+- 📝 **Great DX** - Helpful error messages and JSDoc documentation
+
+## Installation
+
+```bash
+npm install @augur/api-client
+# or
+yarn add @augur/api-client
+```
+
+## Quick Start
+
+```typescript
+import { AugurAPI } from '@augur/api-client';
+
+// Initialize the client
+const api = new AugurAPI({
+  siteId: 'your-site-id',
+  bearerToken: 'your-jwt-token',
+});
+
+// Make API calls
+const users = await api.joomla.users.list();
+const user = await api.joomla.users.get('user-123');
+```
+
+## Authentication
+
+The client handles two types of authentication:
+
+1. **Site ID** (required for all endpoints): Set via `x-site-id` header
+2. **Bearer Token** (required for all endpoints except `/health-check`): JWT token in Authorization header
+
+```typescript
+const api = new AugurAPI({
+  siteId: 'required-site-id',
+  bearerToken: 'optional-for-health-check',
+});
+
+// Health check works without bearer token
+const health = await api.joomla.getHealthCheck();
+
+// All other endpoints require bearer token
+const users = await api.joomla.users.list(); // Requires auth
+```
+
+## Edge Caching
+
+The client provides built-in edge caching support through Cloudflare integration:
+
+### Basic Usage
+
+Use the `edgeCache` parameter to control cache duration (in hours):
+
+```typescript
+// Cache for 4 hours
+const users = await api.joomla.users.list({ 
+  edgeCache: 4,
+  limit: 20 
+});
+
+// Cache single user for 1 hour
+const user = await api.joomla.users.get('user-123', { 
+  edgeCache: 1 
+});
+
+// Cache content for 8 hours
+const content = await api.joomla.content.list({ 
+  edgeCache: 8,
+  categoryIdList: '1,2,3' 
+});
+```
+
+### Supported Cache Durations
+
+Only specific cache durations are supported (validated by Zod):
+
+- `1` - 1 hour cache
+- `2` - 2 hour cache  
+- `3` - 3 hour cache
+- `4` - 4 hour cache
+- `5` - 5 hour cache
+- `8` - 8 hour cache
+
+```typescript
+// ✅ Valid cache durations
+{ edgeCache: 1 }  // 1 hour
+{ edgeCache: 4 }  // 4 hours  
+{ edgeCache: 8 }  // 8 hours
+
+// ❌ Invalid values (will throw ValidationError)
+{ edgeCache: 7 }   // Not supported
+{ edgeCache: 24 }  // Not supported
+```
+
+### How It Works
+
+1. **Automatic Parameter Mapping**: `edgeCache` values are automatically mapped to Cloudflare cache rule parameters:
+   - `edgeCache: 1` → `cacheSiteId1=your-site-id`
+   - `edgeCache: 4` → `cacheSiteId4=your-site-id`
+   - `edgeCache: 8` → `cacheSiteId8=your-site-id`
+
+2. **Site Isolation**: Each site's cache is automatically isolated using your site ID
+
+3. **Zero Configuration**: No setup required - just add the `edgeCache` parameter
+
+### When to Use Caching
+
+- **Frequently accessed data** that doesn't change often
+- **List endpoints** with consistent results
+- **Reference data** like tags, categories, user groups
+- **Performance-critical** operations
+
+### When NOT to Use Caching
+
+- **Real-time data** that changes frequently
+- **User-specific data** that must be current
+- **Create/Update operations** (POST/PUT endpoints don't support caching)
+- **Sensitive operations** requiring fresh data
+
+> **📖 For comprehensive caching guidance, see the [Edge Caching Guide](./docs/caching-guide.md)**
+
+## Available Services
+
+### Joomla Service
+
+Content management and user administration:
+
+#### Content Management
+```typescript
+// List content with filtering
+const contents = await api.joomla.content.list({
+  categoryIdList: '1,2,3',
+  limit: 20,
+  offset: 0,
+  orderBy: 'created|DESC',
+  q: 'search term',
+  tagsList: 'tag1,tag2'
+});
+
+// List content with 4-hour edge caching
+const cachedContents = await api.joomla.content.list({
+  categoryIdList: '1,2,3',
+  edgeCache: 4,  // Cache for 4 hours
+  limit: 20
+});
+
+// Get single content
+const content = await api.joomla.content.get('content-id', {
+  alias: 'optional-alias',
+  catid: 5
+});
+
+// Get single content with 1-hour caching
+const cachedContent = await api.joomla.content.get('content-id', {
+  edgeCache: 1  // Cache for 1 hour
+});
+
+// Get content documentation
+const doc = await api.joomla.content.getDoc('content-id');
+```
+
+#### User Management
+```typescript
+// List users
+const users = await api.joomla.users.list({
+  limit: 20,
+  offset: 0,
+  orderBy: 'username|ASC',
+  q: 'search'
+});
+
+// List users with 2-hour caching (good for user directories)
+const cachedUsers = await api.joomla.users.list({
+  edgeCache: 2,  // Cache for 2 hours
+  limit: 20,
+  orderBy: 'username|ASC'
+});
+
+// Get user details
+const user = await api.joomla.users.get('user-id');
+
+// Get user details with 1-hour caching
+const cachedUser = await api.joomla.users.get('user-id', {
+  edgeCache: 1  // Cache for 1 hour
+});
+
+// Get user's groups
+const groups = await api.joomla.users.groups.list('user-id');
+
+// Get user's groups with caching
+const cachedGroups = await api.joomla.users.groups.list('user-id', {
+  edgeCache: 4  // Cache for 4 hours (groups don't change often)
+});
+```
+
+#### Other Endpoints
+```typescript
+// User groups (great for caching - rarely change)
+const groups = await api.joomla.userGroups.list();
+
+// User groups with 8-hour caching
+const cachedGroups = await api.joomla.userGroups.list({
+  edgeCache: 8  // Cache for 8 hours - group structures rarely change
+});
+
+// Tags
+const tags = await api.joomla.tags.list({
+  q: 'search',
+  limit: 50
+});
+
+// Tags with caching (ideal for reference data)
+const cachedTags = await api.joomla.tags.list({
+  edgeCache: 5,  // Cache for 5 hours
+  q: 'search',
+  limit: 50
+});
+
+// Menu documentation
+const menuDoc = await api.joomla.menu.getDoc('menu-id');
+
+// Health check (no caching - always want fresh status)
+const health = await api.joomla.getHealthCheck();
+```
+
+### Commerce Service
+
+E-commerce cart and checkout operations:
+
+#### Cart Management
+```typescript
+// List user's carts
+const carts = await api.commerce.cartHeaders.list({ 
+  userId: 123,
+  edgeCache: 1  // 1-hour cache (cart data changes frequently)
+});
+
+// Lookup or create cart
+const cart = await api.commerce.cartHeaders.lookup({
+  userId: 123,
+  customerId: 456,
+  contactId: 789
+});
+
+// Get cart lines
+const cartLines = await api.commerce.cartLines.get(cartHdrUid);
+```
+
+#### Checkout Operations
+```typescript
+// Get checkout details with caching
+const checkout = await api.commerce.checkout.get(checkoutUid, {
+  edgeCache: 2  // 2-hour cache for checkout data
+});
+
+// Get checkout documentation
+const checkoutDoc = await api.commerce.checkout.getDoc(checkoutUid, {
+  cartHdrUid: 123,
+  edgeCache: 4  // 4-hour cache for documentation
+});
+
+// Health check
+const health = await api.commerce.getHealthCheck();
+```
+
+### Pricing Service
+
+Product pricing and job price management:
+
+#### Price Engine
+```typescript
+// Get product pricing with caching
+const pricing = await api.pricing.getPrice({
+  customerId: 123,
+  itemId: 'ITEM-001',
+  quantity: 10,
+  edgeCache: 3  // 3-hour cache (prices don't change frequently)
+});
+
+// Pricing with specific parameters
+const customPricing = await api.pricing.getPrice({
+  customerId: 123,
+  itemId: 'ITEM-002',
+  quantity: 5,
+  shipToId: 456,
+  unitOfMeasure: 'EA',
+  edgeCache: 2
+});
+```
+
+#### Job Price Management
+```typescript
+// List job price headers with caching
+const jobPrices = await api.pricing.jobPriceHeaders.list({
+  limit: 20,
+  orderBy: 'job_price_hdr_uid|DESC',
+  edgeCache: 4  // 4-hour cache for job listings
+});
+
+// Get specific job price header
+const jobPrice = await api.pricing.jobPriceHeaders.get(jobPriceHdrUid);
+
+// Get job price lines
+const priceLines = await api.pricing.jobPriceLines.list(jobPriceHdrUid, {
+  limit: 50,
+  edgeCache: 4  // 4-hour cache
+});
+
+// Service health checks
+const pingResponse = await api.pricing.ping();
+const health = await api.pricing.getHealthCheck();
+```
+
+### VMI (Vendor Managed Inventory) Service
+
+Warehouse and inventory management operations:
+
+#### Warehouse Management
+```typescript
+// List warehouses with filtering
+const warehouses = await api.vmi.warehouses.list({
+  customerId: 12345,
+  limit: 10,
+  q: 'distribution',
+  usersId: 456  // Filter by user access
+});
+
+// Get specific warehouse
+const warehouse = await api.vmi.warehouses.get(123);
+
+// Create new warehouse
+const newWarehouse = await api.vmi.warehouses.create({
+  warehouse_name: 'New Distribution Center',
+  warehouse_desc: 'Primary warehouse for west coast operations',
+  customer_id: 12345,
+  inv_profile_hdr_uid: 1
+});
+
+// Update warehouse
+const updatedWarehouse = await api.vmi.warehouses.update(123, {
+  warehouse_name: 'Updated Warehouse Name',
+  warehouse_desc: 'Updated description'
+});
+
+// Enable/disable warehouse
+await api.vmi.warehouses.enable(123, { status_cd: 705 }); // Disable
+await api.vmi.warehouses.enable(123, { status_cd: 704 }); // Enable
+```
+
+#### Inventory Operations
+```typescript
+// Check inventory availability
+const inventory = await api.vmi.inventory.checkAvailability(123, {
+  q: 'wire'  // Search for items containing 'wire'
+});
+
+// Adjust inventory quantities (sets absolute values)
+await api.vmi.inventory.adjust(123, {
+  adjustments: [
+    {
+      inv_mast_uid: 456,
+      qty_on_hand: 200.0,
+      reason: 'Physical count adjustment'
+    }
+  ]
+});
+
+// Receive inventory
+await api.vmi.inventory.receive(123, {
+  receipts: [
+    {
+      inv_mast_uid: 456,
+      qty_received: 50.0,
+      po_number: 'PO-2024-001',
+      lot_number: 'LOT-456'
+    }
+  ]
+});
+
+// Get replenishment information
+const replenishment = await api.vmi.inventory.getReplenishmentInfo(123, {
+  distributorsUid: 789  // Optional distributor filter
+});
+
+// Execute replenishment
+await api.vmi.inventory.replenish(123, {
+  distributor_uid: 789,
+  restock_items: [
+    { inv_mast_uid: 456, qty_to_order: 100.0 }
+  ]
+});
+
+// Transfer inventory between warehouses
+await api.vmi.inventory.transfer(123, {
+  to_warehouse_uid: 124,
+  transfers: [
+    {
+      inv_mast_uid: 456,
+      qty_to_transfer: 25.0,
+      reason: 'Stock balancing'
+    }
+  ]
+});
+
+// Record inventory usage (with warranty tracking)
+await api.vmi.inventory.recordUsage(123, {
+  job_description: 'Office Renovation - Building A',
+  department: 'Facilities',
+  usage_items: [
+    {
+      inv_mast_uid: 456,
+      inv_profile_line_type: 'prophet21',
+      qty_used: 5.0
+    },
+    {
+      inv_mast_uid: 789,
+      inv_profile_line_type: 'products',
+      qty_used: 2.0,
+      warranty: {
+        model_no: 'MDL-123',
+        serial_no: 'SN-456789',
+        warranty_type: 'Standard',
+        notes: 'Installed in conference room'
+      }
+    }
+  ]
+});
+```
+
+#### Distributor Management
+```typescript
+// List distributors
+const distributors = await api.vmi.distributors.list({
+  customerId: 12345,
+  statusCd: 704  // Active distributors only
+});
+
+// Create new distributor
+const newDistributor = await api.vmi.distributors.create({
+  distributor_name: 'ABC Supply Co',
+  distributor_desc: 'Primary electrical supplier',
+  customer_id: 12345,
+  contact_email: 'orders@abcsupply.com',
+  contact_phone: '555-1234'
+});
+
+// Update distributor
+const updatedDistributor = await api.vmi.distributors.update(789, {
+  contact_email: 'newemail@abcsupply.com'
+});
+
+// Enable/disable distributor
+await api.vmi.distributors.enable(789, { status_cd: 705 }); // Disable
+```
+
+#### Product Management
+```typescript
+// Find products and items across both VMI and Prophet 21
+const items = await api.vmi.products.find({
+  customerId: 12345,
+  prefix: 'WIRE'  // Search by item ID prefix
+});
+
+// List products for a distributor
+const products = await api.vmi.products.list({
+  customerId: 12345,
+  distributorsUid: 789,
+  prefix: 'WIRE',
+  limit: 20
+});
+
+// Create product for distributor
+const newProduct = await api.vmi.products.createForDistributor(789, {
+  product_id: 'PROD-001',
+  product_name: 'Custom Wire Product',
+  product_desc: 'Specialized wire for industrial use',
+  distributors_uid: 789,
+  customer_id: 12345
+});
+```
+
+#### Inventory Profile Management
+```typescript
+// List inventory profile headers
+const profileHeaders = await api.vmi.inventoryProfiles.headers.list({
+  customerId: 12345
+});
+
+// Create inventory profile header
+const profileHeader = await api.vmi.inventoryProfiles.headers.create({
+  inv_profile_hdr_desc: 'Standard Office Setup Profile',
+  customer_id: 12345
+});
+
+// List profile lines for a header
+const profileLines = await api.vmi.inventoryProfiles.lines.list(1, {
+  limit: 20
+});
+
+// Create inventory profile line (defines min/max/reorder quantities)
+const profileLine = await api.vmi.inventoryProfiles.lines.create(1, {
+  inv_mast_uid: 456,
+  inv_profile_line_type: 'prophet21',
+  min_qty: 50.0,
+  max_qty: 200.0,
+  reorder_qty: 100.0
+});
+```
+
+#### Health Monitoring
+```typescript
+// Simple ping (no authentication required)
+const pong = await api.vmi.health.ping();
+
+// Comprehensive health check
+const health = await api.vmi.health.check();
+```
+
+### OpenSearch Service
+
+Advanced product search and discovery operations:
+
+#### Item Search
+```typescript
+// Basic product search
+const searchResults = await api.opensearch.itemSearch.search({
+  q: 'electrical wire',
+  searchType: 'query',
+  size: 20
+});
+
+// Advanced search with filtering
+const filteredSearch = await api.opensearch.itemSearch.search({
+  q: 'power tools',
+  searchType: 'query',
+  size: 50,
+  operator: 'AND',
+  itemCategoryUidList: '123,456,789',
+  filters: JSON.stringify([{attributeUid: 123, attributeValueUid: 456}]),
+  edgeCache: 2  // 2 hours - search results change as inventory updates
+});
+
+// Similarity search for recommendations
+const similarItems = await api.opensearch.itemSearch.search({
+  q: 'CAT5e network cable 100ft blue',
+  searchType: 'similarity',
+  size: 15,
+  edgeCache: 4  // 4 hours - similarity results are more stable
+});
+
+// Get search facets for filtering
+const attributes = await api.opensearch.itemSearch.getAttributes({
+  q: 'LED bulbs',
+  searchType: 'query',
+  edgeCache: 6  // 6 hours - facet structure changes less frequently
+});
+```
+
+#### Items Management
+```typescript
+// List items from search index
+const items = await api.opensearch.items.list({
+  itemId: 'WIRE',  // Prefix filter
+  online: 'Y',     // Only online items
+  statusCd: 704,   // Active items only
+  limit: 100,
+  offset: 0,
+  edgeCache: 3     // 3 hours - item data is relatively stable
+});
+
+// Get detailed item information
+const itemDetail = await api.opensearch.items.get(123456);
+
+// Refresh item from source database
+const refreshResult = await api.opensearch.items.refresh(123456);
+
+// Update item in search index
+const updateResult = await api.opensearch.items.update(123456);
+
+// Batch refresh all items
+const batchRefresh = await api.opensearch.items.refreshAll();
+```
+
+#### Health Monitoring
+```typescript
+// Simple ping
+const pong = await api.opensearch.health.ping();
+
+// Comprehensive health check
+const health = await api.opensearch.health.check();
+```
+
+## Error Handling
+
+The client provides typed errors with helpful information:
+
+```typescript
+try {
+  const user = await api.joomla.users.get('user-id');
+} catch (error) {
+  if (error instanceof AugurAPIError) {
+    console.error(`API Error ${error.code}: ${error.message}`);
+    
+    switch (error.code) {
+      case 'AUTHENTICATION_ERROR':
+        // Handle auth error - refresh token
+        break;
+      case 'NOT_FOUND':
+        // Handle not found
+        break;
+      case 'VALIDATION_ERROR':
+        // Handle validation errors
+        console.error('Validation errors:', error.validationErrors);
+        break;
+      case 'RATE_LIMIT_EXCEEDED':
+        // Handle rate limiting
+        break;
+    }
+  }
+}
+```
+
+## Configuration
+
+```typescript
+const api = new AugurAPI({
+  // Required
+  siteId: 'your-site-id',
+  
+  // Authentication
+  bearerToken: 'your-jwt-token',
+  apiKey: 'alternative-auth-method',
+  
+  // Optional settings
+  timeout: 30000,        // Request timeout in ms (default: 30000)
+  retries: 3,           // Number of retries (default: 3)
+  retryDelay: 1000,     // Delay between retries in ms (default: 1000)
+  
+  // Interceptors
+  onRequest: (config) => {
+    console.log('Request:', config);
+    return config;
+  },
+  onResponse: (response) => {
+    console.log('Response:', response);
+    return response;
+  },
+  onError: (error) => {
+    console.error('Error:', error);
+    throw error;
+  }
+});
+```
+
+## Dynamic Configuration
+
+Update authentication credentials at runtime:
+
+```typescript
+// Update bearer token
+api.setAuthToken('new-token');
+
+// Update site ID
+api.setSiteId('new-site-id');
+```
+
+## TypeScript Support
+
+All responses are fully typed with TypeScript interfaces generated from Zod schemas:
+
+```typescript
+import type { User, Content, Tag } from '@augur/api-client';
+
+const user: User = await api.joomla.users.get('123');
+// TypeScript knows all properties of user
+
+const contents: ContentListResponse = await api.joomla.content.list();
+// Full type safety for paginated responses
+```
+
+## Implementation Status
+
+- ✅ Core HTTP client with authentication
+- ✅ Error handling with typed errors
+- ✅ Joomla service (full implementation)
+- ✅ Commerce service (full implementation)
+- ✅ Pricing service (full implementation)
+- ✅ VMI service (full implementation)
+- ✅ OpenSearch service (full implementation)
+- ✅ Zod validation for all requests/responses
+- ✅ TypeScript types with full inference
+- ✅ Edge caching with Cloudflare integration
+- ⏳ POST/PUT/DELETE endpoints (coming soon)
+- ⏳ Offline support for React Native
+
+## Development
+
+This library follows the specifications in the PRD and API documentation. Key principles:
+
+1. **Method Naming**: Based on HTTP method and path
+   - GET `/users` → `listUsers()`
+   - GET `/user/:id` → `getUser()`
+   - POST `/user` → `createUser()` (coming soon)
+   - PUT `/user/:id` → `updateUser()` (coming soon)
+   - DELETE `/user/:id` → `deleteUser()` (coming soon)
+
+2. **ID Conventions**:
+   - Fields ending with `Uid` are numbers
+   - Fields ending with `Id` are strings
+
+3. **Validation**: All inputs and outputs validated with Zod schemas
+
+## Documentation
+
+### 📚 User Documentation
+
+For comprehensive guides, examples, and best practices:
+
+**[📖 User Documentation →](../../docs/packages/augur-api/user/README.md)**
+
+- **Service Guides**: Detailed documentation for each service (Joomla, Commerce, Pricing, VMI)
+- **Cross-Service Guides**: Authentication, error handling, and caching strategies
+- **Integration Examples**: React Native, Next.js, Node.js, and more
+- **Best Practices**: Performance optimization and real-world usage patterns
+
+### 🔧 Developer Documentation
+
+For contributing and extending the library:
+
+**[🔧 Developer Documentation →](../../docs/packages/augur-api/dev/README.md)**
+
+- **API Specifications**: Complete endpoint documentation
+- **Implementation Plans**: Development roadmaps and architecture
+- **AI Guidelines**: Documentation standards and patterns
+
+## Contributing
+
+See the project documentation for contribution guidelines.