@simpleapps-com/augur-api 0.4.6 → 0.4.8

package/README.md

@@ -1092,6 +1092,8 @@ if (result.success) {
 
 📋 **[Complete API Services Reference](./API-SERVICES.md)** - Detailed catalog of all 26 services with descriptions, OpenAPI specifications, and Postman collections.
 
+💡 **[Tips and Tricks Guide](./TIPS-AND-TRICKS.md)** - Advanced usage patterns, performance optimizations, and helpful techniques including the itemId → invMastUid lookup pattern.
+
 ### Complete Endpoint Reference
 
 #### Joomla Service
@@ -1477,6 +1479,65 @@ const ping = await api.opensearch.health.ping();
 const health = await api.opensearch.health.check();
 ```
 
+#### Items Service
+
+```typescript
+// Inventory Master Records
+const itemDetails = await api.items.invMast.get(invMastUid);
+
+// Document retrieval for invMast records
+const itemDoc = await api.items.invMast.doc.get(invMastUid, {
+  q: 'optional-query-pattern'  // Search pattern for document filtering
+});
+
+// Special lookup pattern: Find invMastUid by itemId
+// When you only have an itemId but need the invMastUid, use invMastUid = 0
+// and provide the itemId as the query pattern. This will look up the itemId
+// and return the full document including the correct invMastUid.
+const itemByItemId = await api.items.invMast.doc.get(0, {
+  q: 'YOUR-ITEM-ID'  // Replace with actual itemId (e.g., 'WIRE-12-AWG-250FT')
+});
+// Response includes the actual invMastUid for future direct lookups
+
+// Categories and attributes
+const categories = await api.items.categories.list({
+  limit: 50,
+  edgeCache: 8  // Categories rarely change
+});
+
+// Product locations and bins
+const locations = await api.items.invMast.locations.list(invMastUid);
+const bins = await api.items.invMast.locations.bins.list(invMastUid, locationId);
+
+// Alternate codes and variants
+const alternates = await api.items.invMast.alternateCode.list(invMastUid);
+const variants = await api.items.variants.list({
+  invMastUid: invMastUid,
+  edgeCache: 4  // Variants change occasionally
+});
+
+// Attributes and values
+const attributes = await api.items.attributes.list({
+  edgeCache: 6  // Attribute structure is relatively stable
+});
+
+const attributeValues = await api.items.attributes.values.list(attributeUid);
+
+// Brands and product links
+const brands = await api.items.brands.list({
+  edgeCache: 8  // Brand data is very stable
+});
+
+const productLinks = await api.items.productLinks.list({
+  invMastUid: invMastUid,
+  edgeCache: 2  // Product links may change
+});
+
+// Health Monitoring
+const ping = await api.items.ping();
+const health = await api.items.healthCheck.get();
+```
+
 ### Response Format
 
 All Augur microservices follow a unified response pattern:
@@ -1570,166 +1631,60 @@ try {
 
 ## Advanced Features
 
-### Edge Caching with Cloudflare
+💡 **[Complete Tips and Tricks Guide](./TIPS-AND-TRICKS.md)** - Comprehensive advanced patterns including edge caching, request cancellation, middleware integration, framework integrations, and error handling strategies.
 
-The client provides built-in edge caching that dramatically improves performance by serving cached responses from Cloudflare's global edge network.
+**Quick Advanced Features:**
+- **Edge Caching**: Built-in Cloudflare caching with configurable TTL (1-8 hours)
+- **Request Cancellation**: AbortController support for request timeout
+- **Custom Headers**: Per-request configuration and timeouts  
+- **Batch Operations**: Parallel request execution with Promise.all
+- **Middleware**: Global request/response/error interceptors
 
-#### Supported Cache Durations
+## Integration Guides
 
-Only specific cache durations are supported and validated:
+💡 **[Complete Framework Integration Examples](./TIPS-AND-TRICKS.md#-framework-integration-patterns)** - Detailed React, Next.js, React Native, and Node.js integration patterns with custom hooks, error handling, and best practices.
 
-| Value | Duration | Best For |
-|-------|----------|----------|
-| `1` | 1 hour | Frequently changing data, cart contents |
-| `2` | 2 hours | User lists, moderate volatility data |
-| `3` | 3 hours | Standard pricing, product information |
-| `4` | 4 hours | Recommendations, warehouse data |
-| `5` | 5 hours | Tags, categories, reference data |
-| `8` | 8 hours | Static content, distributor information |
+**Quick Integration Examples:**
+- **React**: Custom `useAugurAPI()` hook with context-aware API creation
+- **Next.js**: Server-side API routes with proper caching and error handling  
+- **React Native**: AsyncStorage integration for offline-first patterns
+- **Node.js**: Service layer integration with middleware and monitoring
 
-#### Cache Implementation
+## Framework-Specific Features
 
+### React/Next.js
 ```typescript
-// How it works internally:
-// edgeCache: 4 → adds URL parameter: cacheSiteId4=your-site-id
-// This triggers Cloudflare cache rules for 4-hour TTL
-
-const users = await api.joomla.users.list({
-  limit: 20,
-  edgeCache: 4  // Cached at edge for 4 hours
-});
-```
-
-#### Caching Best Practices
-
-```typescript
-// ✅ Good: Cache stable reference data
-const categories = await api.items.categories.list({
-  edgeCache: 8  // Categories rarely change
-});
-
-// ✅ Good: Cache with appropriate TTL
-const pricing = await api.pricing.getPrice({
-  customerId: 12345,
-  itemId: 'STANDARD-ITEM',
-  quantity: 10,
-  edgeCache: 3  // Standard pricing changes infrequently
-});
-
-// ✅ Good: Short cache for volatile data
-const cart = await api.commerce.cartHeaders.list({
-  userId: 123,
-  edgeCache: 1  // Cart data changes frequently
-});
-
-// ❌ Bad: Don't cache real-time operations
-const auth = await api.joomla.users.verifyPassword({
-  username: 'user',
-  password: 'pass'
-  // No edgeCache - authentication must be real-time
-});
+// Context-aware API creation
+const api = AugurAPI.fromContext(context);
 
-// ❌ Bad: Don't cache user-specific data too long
-const userSpecificData = await api.vmi.invProfileHdr.checkAvailability(warehouseId, {
-  q: 'search',
-  edgeCache: 8  // Too long for inventory data
-});
+// Custom hook pattern  
+const { api, isReady } = useAugurAPI();
 ```
 
-### Request Cancellation
-
+### Error Handling Integration
 ```typescript
-const controller = new AbortController();
-
-// Start a request
-const usersPromise = api.joomla.users.list(
-  { limit: 100 },
-  { signal: controller.signal }  // Pass abort signal
-);
-
-// Cancel the request if needed
-setTimeout(() => {
-  controller.abort();
-}, 5000);
-
+// Framework-agnostic error handling
 try {
-  const users = await usersPromise;
+  const result = await api.joomla.users.list({ limit: 10 });
 } catch (error) {
-  if (error.name === 'AbortError') {
-    console.log('Request was cancelled');
-  }
+  ErrorHandler.handle(error, 'UserList Component');
 }
 ```
 
-### Custom Headers and Timeouts
-
-```typescript
-// Per-request configuration
-const users = await api.joomla.users.list(
-  { limit: 20 },
-  {
-    timeout: 10000,  // 10 second timeout
-    headers: {
-      'X-Custom-Header': 'value',
-      'X-Request-ID': 'unique-id'
-    }
-  }
-);
-```
-
-### Batch Operations
-
-```typescript
-// Execute multiple operations in parallel
-const [users, articles, tags] = await Promise.all([
-  api.joomla.users.list({ limit: 10, edgeCache: 2 }),
-  api.joomla.content.list({ limit: 5, edgeCache: 6 }),
-  api.joomla.tags.list({ limit: 20, edgeCache: 8 })
-]);
-
-// Process results
-console.log(`Found ${users.data.length} users`);
-console.log(`Found ${articles.data.length} articles`);
-console.log(`Found ${tags.data.length} tags`);
-```
+## Error Handling
 
-### Middleware Integration
+💡 **[Complete Error Handling Guide](./TIPS-AND-TRICKS.md#️-advanced-error-handling)** - Comprehensive error handling patterns including retry logic, exponential backoff, global error handlers, and framework-specific error boundaries.
 
+**Quick Error Types:**
 ```typescript
-// Add global request/response interceptors
-const api = new AugurAPI({
-  siteId: 'your-site-id',
-  bearerToken: 'your-token',
-  
-  // Request interceptor
-  onRequest: (config) => {
-    console.log(`Making request to: ${config.url}`);
-    config.headers['X-Request-Timestamp'] = Date.now().toString();
-    return config;
-  },
-  
-  // Response interceptor
-  onResponse: (response) => {
-    console.log(`Response status: ${response.status}`);
-    return response;
-  },
-  
-  // Error interceptor
-  onError: (error) => {
-    console.error('API Error:', error.message);
-    // Custom error handling logic
-    throw error;
-  }
-});
-```
-
-## Integration Guides
-
-### React Integration
-
-```tsx
-import React, { useState, useEffect } from 'react';
-import { AugurAPI, User, AugurAPIError, type AugurContext } from '@simpleapps-com/augur-api';
+import { 
+  AugurAPIError,           // Base error class
+  AuthenticationError,     // 401 errors
+  ValidationError,         // Request validation failures
+  NotFoundError,          // 404 errors
+  RateLimitError,         // 429 errors
+  NetworkError            // Network/connectivity issues
+} from '@simpleapps-com/augur-api';
 
 // Custom hook for Augur API - Context-aware approach
 function useAugurAPI(context?: AugurContext) {