@simpleapps-com/augur-api 0.6.0 → 0.7.1

package/API-SERVICES.md

@@ -1,227 +0,0 @@
-# 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.*

package/AUTHENTICATION.md

@@ -1,371 +0,0 @@
-# Authentication Guide
-
-Complete guide to authentication patterns in the Augur API Client.
-
-## Standard Authentication (Most Common)
-
-The standard authentication pattern works for 95% of use cases.
-
-### Dual Authentication System
-
-Every API request requires two pieces of authentication:
-
-1. **Site ID** (`x-site-id` header) - Identifies which site/tenant you're working with
-2. **Bearer Token** (JWT) - Proves you're authorized to access that site
-
-```typescript
-const api = new AugurAPI({
-  siteId: 'your-site-id',        // Always required
-  bearerToken: 'your-jwt-token', // Required except for health checks
-});
-```
-
-### How to Get Your Credentials
-
-**Site ID**: Usually provided by your system administrator or found in your project configuration.
-
-**Bearer Token**: Obtained through your application's login process. This is typically a JWT token that looks like:
-`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
-
-### Health Checks (No Authentication Required)
-
-Health checks are the only endpoints that don't require a bearer token:
-
-```typescript
-// Health checks work without bearer token
-const api = new AugurAPI({
-  siteId: 'your-site-id',
-  // No bearerToken needed
-});
-
-const health = await api.joomla.getHealthCheck();
-const pricingHealth = await api.pricing.getHealthCheck();
-const vmiPing = await api.vmi.health.ping();
-```
-
-### Dynamic Authentication Updates
-
-Update credentials at runtime when needed:
-
-```typescript
-// Update token after login/refresh
-api.setAuthToken('new-jwt-token');
-
-// Switch to different site
-api.setSiteId('different-site-id');
-
-// Example: Token refresh scenario
-async function refreshTokenIfNeeded() {
-  try {
-    await api.joomla.users.list({ limit: 1 });
-  } catch (error) {
-    if (error instanceof AuthenticationError) {
-      const newToken = await refreshJWTToken();
-      api.setAuthToken(newToken);
-    }
-  }
-}
-```
-
-### Environment Variables Setup
-
-Store credentials securely in environment variables:
-
-```bash
-# .env file
-AUGUR_SITE_ID=your-site-id
-AUGUR_JWT_TOKEN=your-jwt-token
-```
-
-```typescript
-const api = new AugurAPI({
-  siteId: process.env.AUGUR_SITE_ID!,
-  bearerToken: process.env.AUGUR_JWT_TOKEN!,
-});
-```
-
-### Security Best Practices
-
-1. **Environment Variables**: Never hardcode credentials
-2. **Token Rotation**: Implement regular token rotation in production
-3. **HTTPS Only**: All API requests use HTTPS in production
-4. **Secure Storage**: Never store tokens in localStorage for web apps
-5. **Minimal Permissions**: Use tokens with minimal required permissions
-
-```typescript
-// ✅ Good: Environment-based configuration
-const api = new AugurAPI({
-  siteId: process.env.AUGUR_SITE_ID!,
-  bearerToken: getSecurelyStoredToken(), // From secure storage
-});
-
-// ❌ Bad: Hardcoded credentials
-const api = new AugurAPI({
-  siteId: 'hardcoded-site-id',
-  bearerToken: 'hardcoded-token', // Never do this!
-});
-```
-
----
-
-## Advanced: Cross-Site Authentication
-
-**⚠️ Advanced Feature**: Only needed for multi-tenant applications where you need to authenticate users across different sites.
-
-### When You Need Cross-Site Auth
-
-Cross-site authentication is needed when:
-- You're building a multi-tenant application
-- You need to authenticate a user from one site against a different site
-- You're managing multiple client sites from a central application
-
-### Prerequisites
-
-- Access to the special `augur_info` site
-- Admin-level JWT token with `augur_info` privileges
-- Target site ID where you want to authenticate the user
-
-### Option 1: Streamlined Utility Function (Recommended)
-
-```typescript
-import { authenticateUserForSite } from '@simpleapps-com/augur-api';
-
-const result = await authenticateUserForSite({
-  targetSiteId: 'tenant_site_1',
-  username: 'user@tenant.com',
-  password: 'user-password',
-  augurInfoToken: 'admin-jwt-token'  // JWT with augur_info admin privileges
-});
-
-if (result.success) {
-  // Ready-to-use API client for the target site
-  const userData = await result.targetSiteAPI!.joomla.users.get(result.userId!);
-  console.log('User authenticated:', result.username);
-  console.log('User data:', userData);
-} else {
-  console.error('Authentication failed:', result.error);
-}
-```
-
-### Option 2: Reusable Authenticator
-
-```typescript
-import { createCrossSiteAuthenticator } from '@simpleapps-com/augur-api';
-
-// Create reusable authenticator
-const crossSiteAuth = createCrossSiteAuthenticator('admin-jwt-token');
-
-// Use for multiple sites
-const result1 = await crossSiteAuth('tenant_site_1', 'user1@tenant.com', 'pass1');
-const result2 = await crossSiteAuth('tenant_site_2', 'user2@tenant.com', 'pass2');
-
-if (result1.success) {
-  const tenantData = await result1.targetSiteAPI!.joomla.content.list({ limit: 10 });
-}
-```
-
-### Option 3: Manual Approach
-
-```typescript
-// Manual approach using the API client directly
-const crossSiteAPI = new AugurAPI({
-  siteId: 'augur_info',           // Special site for cross-site operations
-  bearerToken: 'admin-jwt-token', // JWT token with augur_info admin privileges
-});
-
-// Authenticate user against a different site
-const authResult = await crossSiteAPI.joomla.users.verifyPassword({
-  username: 'user@tenant.com',
-  password: 'user-password',
-  siteId: 'tenant_site_1'        // Target site for authentication
-});
-
-if (authResult.data.isVerified) {
-  // Create API instance for the target site
-  const tenantAPI = new AugurAPI({
-    siteId: 'tenant_site_1',
-    bearerToken: authResult.data.token, // Token scoped to tenant site
-  });
-  
-  const userData = await tenantAPI.joomla.users.get(authResult.data.id);
-}
-```
-
-### Cross-Site Auth Flow Diagram
-
-```
-[Your App] → [augur_info API] → [Target Site] → [User Validated] → [Target Site API Client]
-     ↓              ↓                ↓               ↓                      ↓
-Admin Token → Verify User → Check Password → Return User Token → Ready for API calls
-```
-
-### Common Cross-Site Patterns
-
-#### Multi-Tenant Dashboard
-```typescript
-// Authenticate users across multiple tenant sites
-const authenticator = createCrossSiteAuthenticator(adminToken);
-
-const tenants = ['site1', 'site2', 'site3'];
-const userCredentials = { username: 'user@example.com', password: 'pass' };
-
-const results = await Promise.all(
-  tenants.map(siteId => 
-    authenticator(siteId, userCredentials.username, userCredentials.password)
-  )
-);
-
-// Process results for each tenant
-results.forEach((result, index) => {
-  if (result.success) {
-    console.log(`${tenants[index]}: User authenticated as ${result.username}`);
-  } else {
-    console.log(`${tenants[index]}: Authentication failed - ${result.error}`);
-  }
-});
-```
-
-#### Site Switching
-```typescript
-// Allow users to switch between sites they have access to
-async function switchUserToSite(username: string, password: string, targetSiteId: string) {
-  const result = await authenticateUserForSite({
-    targetSiteId,
-    username,
-    password,
-    augurInfoToken: process.env.AUGUR_INFO_ADMIN_TOKEN!
-  });
-
-  if (result.success) {
-    // Store the new site's API client
-    global.userAPI = result.targetSiteAPI;
-    global.currentSiteId = targetSiteId;
-    return { success: true, siteId: targetSiteId };
-  }
-
-  return { success: false, error: result.error };
-}
-```
-
-### Cross-Site Error Handling
-
-```typescript
-try {
-  const result = await authenticateUserForSite({
-    targetSiteId: 'tenant-site',
-    username: 'user@tenant.com',
-    password: 'user-pass',
-    augurInfoToken: adminToken
-  });
-
-  if (!result.success) {
-    switch (result.error) {
-      case 'Invalid username or password':
-        // Handle wrong username/password
-        break;
-      case 'Site not found':
-        // Handle invalid target site (from API error)
-        break;
-      case 'Authentication failed':
-        // Handle general auth failures or network issues
-        break;
-      default:
-        // Handle other errors
-        break;
-    }
-  }
-} catch (error) {
-  console.error('Cross-site auth failed:', error.message);
-}
-```
-
-### Security Considerations for Cross-Site Auth
-
-1. **Admin Token Security**: The `augur_info` admin token is very powerful - store it extremely securely
-2. **Audit Logging**: Log all cross-site authentication attempts for security monitoring
-3. **Rate Limiting**: Implement rate limiting to prevent brute force attacks
-4. **Token Scoping**: Returned tokens are scoped to the target site only
-5. **Session Management**: Properly manage and clean up cross-site sessions
-
-### When NOT to Use Cross-Site Auth
-
-Don't use cross-site authentication if:
-- You're working with a single site (use standard auth)
-- You don't have admin-level access to `augur_info`
-- You're building a simple application without multi-tenancy
-- Security requirements prohibit cross-site token exchange
-
----
-
-## Troubleshooting Authentication
-
-### Common Issues
-
-**"Authentication failed" (401 Error)**
-- Check your `bearerToken` is correct and not expired
-- Verify your `siteId` matches your environment
-- For cross-site auth, ensure your admin token has `augur_info` privileges
-
-**"Forbidden" (403 Error)**
-- Your token is valid but doesn't have permission for this operation
-- Check if you need admin-level permissions
-- Verify the site ID matches the token's scope
-
-**"Site not found" (Cross-site auth)**
-- Verify the target site ID exists and is accessible
-- Check that the target site is properly configured
-- Ensure your admin token has access to the target site
-
-**Token Expiration**
-- Implement token refresh logic
-- Monitor token expiration times
-- Have fallback authentication flow
-
-### Authentication Testing
-
-```typescript
-// Test standard authentication
-async function testAuth() {
-  try {
-    const api = new AugurAPI({
-      siteId: 'your-site-id',
-      bearerToken: 'your-token'
-    });
-
-    // Simple test call
-    const health = await api.joomla.getHealthCheck();
-    console.log('✅ Authentication working:', health.data.status);
-
-    // Test authenticated call
-    const users = await api.joomla.users.list({ limit: 1 });
-    console.log('✅ Authenticated API calls working');
-
-  } catch (error) {
-    console.error('❌ Authentication failed:', error.message);
-  }
-}
-
-// Test cross-site authentication
-async function testCrossSiteAuth() {
-  try {
-    const result = await authenticateUserForSite({
-      targetSiteId: 'test-site',
-      username: 'test-user',
-      password: 'test-pass',
-      augurInfoToken: 'admin-token'
-    });
-
-    if (result.success) {
-      console.log('✅ Cross-site auth working');
-      const testCall = await result.targetSiteAPI!.joomla.getHealthCheck();
-      console.log('✅ Target site API working:', testCall.data.status);
-    } else {
-      console.error('❌ Cross-site auth failed:', result.error);
-    }
-  } catch (error) {
-    console.error('❌ Cross-site auth error:', error.message);
-  }
-}
-```
-
-For most applications, stick with standard authentication. Only implement cross-site authentication if you specifically need multi-tenant capabilities.