@simpleapps-com/augur-api 0.4.7 → 0.4.9

package/TIPS-AND-TRICKS.md

@@ -0,0 +1,887 @@
+# Augur API Tips and Tricks
+
+This document contains advanced usage patterns, performance optimizations, and helpful techniques for working with the Augur API client library.
+
+## 🔍 Finding Items by ItemId
+
+### Problem: You have an itemId but need the invMastUid
+
+When you only have a Prophet 21 itemId (like `WIRE-12-AWG-250FT`) but need the internal `invMastUid` for database operations:
+
+```typescript
+// ✅ Use invMastUid = 0 with itemId as query pattern
+const itemLookup = await api.items.invMast.doc.get(0, {
+  q: 'WIRE-12-AWG-250FT'  // Your actual itemId
+});
+
+// Extract the invMastUid for future direct lookups
+const invMastUid = itemLookup.data.invMastUid;
+
+// Now use the invMastUid for efficient direct access
+const itemDetails = await api.items.invMast.get(invMastUid);
+const locations = await api.items.invMast.locations.list(invMastUid);
+```
+
+### Why this works
+- The Items service recognizes `invMastUid = 0` as a special lookup case
+- It searches the `item_id` field instead of using direct UID lookup
+- Returns the complete document including the actual `invMastUid`
+- This is the most efficient way to bridge itemId → invMastUid
+
+## 🚀 Performance Optimization
+
+### Smart Caching Strategies
+
+```typescript
+// ✅ Cache stable reference data with longer TTL
+const categories = await api.items.categories.list({
+  edgeCache: 8  // 8 hours - categories rarely change
+});
+
+const brands = await api.items.brands.list({
+  edgeCache: 12  // 12 hours - brand data is very stable  
+});
+
+// ✅ Shorter cache for semi-dynamic data
+const inventory = await api.items.invMast.get(invMastUid, {
+  edgeCache: 2  // 2 hours - inventory levels change regularly
+});
+
+// ✅ Very short cache for user-specific data
+const userCart = await api.commerce.cartHeaders.list({
+  userId: 123,
+  edgeCache: 0.5  // 30 minutes - cart changes frequently
+});
+
+// ❌ Don't cache authentication or real-time operations
+const authCheck = await api.joomla.users.verifyPassword({
+  username: 'user',
+  password: 'pass'
+  // No edgeCache - authentication must be real-time
+});
+```
+
+### Batch Operations for Better Performance
+
+```typescript
+// ✅ Get multiple items efficiently
+const itemPromises = invMastUids.map(uid => 
+  api.items.invMast.get(uid, { edgeCache: 2 })
+);
+const items = await Promise.all(itemPromises);
+
+// ✅ Use parallel requests for independent data
+const [categories, brands, attributes] = await Promise.all([
+  api.items.categories.list({ edgeCache: 8 }),
+  api.items.brands.list({ edgeCache: 8 }),
+  api.items.attributes.list({ edgeCache: 6 })
+]);
+```
+
+## 🔄 Cross-Service Data Patterns
+
+### Order → Item Details Workflow
+
+```typescript
+// Get order details
+const order = await api.orders.oeHdr.get(orderNo);
+const orderLines = await api.orders.oeHdr.lines.list(orderNo);
+
+// Extract item IDs from order lines and get detailed item info
+const itemDetailsPromises = orderLines.data.map(async (line) => {
+  // Use the itemId to invMastUid lookup pattern
+  const itemLookup = await api.items.invMast.doc.get(0, {
+    q: line.itemId
+  });
+  
+  return {
+    orderLine: line,
+    itemDetails: await api.items.invMast.get(itemLookup.data.invMastUid),
+    locations: await api.items.invMast.locations.list(itemLookup.data.invMastUid)
+  };
+});
+
+const enrichedOrderLines = await Promise.all(itemDetailsPromises);
+```
+
+### Customer → Purchased Items → Recommendations
+
+```typescript
+// Get customer's purchase history
+const customerId = 12345;
+const purchasedItems = await api.customers.customer.purchasedItems.list(customerId, {
+  limit: 50,
+  edgeCache: 1  // Recent purchases change frequently
+});
+
+// Find similar items for recommendations using OpenSearch
+const recommendationPromises = purchasedItems.data.slice(0, 5).map(async (item) => {
+  return api.openSearch.itemSearch.search({
+    q: item.itemId,
+    searchType: 'similarity',
+    size: 3,
+    edgeCache: 4  // Similarity results are relatively stable
+  });
+});
+
+const recommendations = await Promise.all(recommendationPromises);
+```
+
+## 🛠 Error Handling Patterns
+
+### Graceful Degradation
+
+```typescript
+async function getItemWithFallback(itemIdentifier: string | number) {
+  try {
+    // Try direct invMastUid lookup first
+    if (typeof itemIdentifier === 'number') {
+      return await api.items.invMast.get(itemIdentifier);
+    }
+    
+    // Fallback to itemId lookup
+    const itemLookup = await api.items.invMast.doc.get(0, {
+      q: itemIdentifier
+    });
+    
+    return await api.items.invMast.get(itemLookup.data.invMastUid);
+    
+  } catch (error) {
+    // Final fallback to search
+    console.warn(`Direct lookup failed for ${itemIdentifier}, trying search...`);
+    
+    const searchResults = await api.openSearch.itemSearch.search({
+      q: itemIdentifier.toString(),
+      searchType: 'query',
+      size: 1
+    });
+    
+    if (searchResults.data.length === 0) {
+      throw new Error(`Item not found: ${itemIdentifier}`);
+    }
+    
+    return searchResults.data[0];
+  }
+}
+```
+
+### Request Timeout Handling
+
+```typescript
+import { AbortController } from 'node-abort-controller';
+
+async function getItemWithTimeout(invMastUid: number, timeoutMs = 5000) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+  
+  try {
+    const result = await api.items.invMast.get(invMastUid, {}, {
+      signal: controller.signal
+    });
+    
+    clearTimeout(timeoutId);
+    return result;
+    
+  } catch (error) {
+    clearTimeout(timeoutId);
+    if (error.name === 'AbortError') {
+      throw new Error(`Request timed out after ${timeoutMs}ms`);
+    }
+    throw error;
+  }
+}
+```
+
+## 🔐 Authentication Patterns
+
+### Cross-Site Authentication
+
+```typescript
+// Set up cross-site authentication for multi-tenant scenarios
+const api = createAugurApiClient({
+  baseUrl: 'https://api.example.com',
+  authToken: 'your-jwt-token',
+  siteId: 'site-specific-id'  // For cross-site operations
+});
+
+// Use with services that support cross-site operations
+const siteSpecificUsers = await api.joomla.users.list({
+  limit: 50
+  // siteId is automatically included in headers
+});
+```
+
+### Token Refresh Pattern
+
+```typescript
+class ApiManager {
+  private client: AugurApiClient;
+  private refreshTokenIfNeeded: () => Promise<string>;
+  
+  constructor(refreshCallback: () => Promise<string>) {
+    this.refreshTokenIfNeeded = refreshCallback;
+    this.client = createAugurApiClient({
+      baseUrl: 'https://api.example.com'
+    });
+  }
+  
+  async makeAuthenticatedRequest<T>(
+    request: (client: AugurApiClient) => Promise<T>
+  ): Promise<T> {
+    try {
+      return await request(this.client);
+    } catch (error) {
+      if (error.response?.status === 401) {
+        // Token expired, refresh and retry
+        const newToken = await this.refreshTokenIfNeeded();
+        this.client.updateAuthToken(newToken);
+        return await request(this.client);
+      }
+      throw error;
+    }
+  }
+}
+```
+
+## 📊 Data Transformation Helpers
+
+### Prophet 21 to Application Models
+
+```typescript
+// Transform P21 data structures to application-friendly formats
+function transformInventoryItem(p21Item: any) {
+  return {
+    id: p21Item.invMastUid,
+    itemId: p21Item.itemId,
+    description: p21Item.itemDesc,
+    price: p21Item.listPrice,
+    availability: {
+      inStock: p21Item.qtyOnHand > 0,
+      quantity: p21Item.qtyOnHand,
+      locations: p21Item.locations?.map(loc => ({
+        warehouse: loc.locationId,
+        bin: loc.bin,
+        quantity: loc.qtyOnHand
+      })) || []
+    },
+    category: {
+      id: p21Item.itemCategoryUid,
+      name: p21Item.categoryName
+    }
+  };
+}
+
+// Use with API responses
+const rawItem = await api.items.invMast.get(invMastUid);
+const transformedItem = transformInventoryItem(rawItem.data);
+```
+
+## 🧪 Testing Patterns
+
+### Mock API Responses
+
+```typescript
+// Create mock client for testing
+const mockApi = {
+  items: {
+    invMast: {
+      get: jest.fn().mockResolvedValue({
+        status: 200,
+        data: { invMastUid: 123, itemId: 'TEST-ITEM' }
+      }),
+      doc: {
+        get: jest.fn().mockResolvedValue({
+          status: 200,
+          data: { invMastUid: 123, itemId: 'TEST-ITEM' }
+        })
+      }
+    }
+  }
+};
+
+// Test the itemId lookup pattern
+test('should find item by itemId', async () => {
+  const result = await getItemByItemId('TEST-ITEM');
+  expect(mockApi.items.invMast.doc.get).toHaveBeenCalledWith(0, {
+    q: 'TEST-ITEM'
+  });
+});
+```
+
+## 🎯 Common Use Cases
+
+### E-commerce Product Catalog
+
+```typescript
+// Build complete product catalog with all necessary data
+async function buildProductCatalog(categoryIds: number[]) {
+  const [categories, brands, attributes] = await Promise.all([
+    api.items.categories.list({ edgeCache: 8 }),
+    api.items.brands.list({ edgeCache: 8 }),
+    api.items.attributes.list({ edgeCache: 6 })
+  ]);
+  
+  const products = [];
+  
+  for (const categoryId of categoryIds) {
+    const categoryItems = await api.openSearch.itemSearch.search({
+      itemCategoryUidList: categoryId.toString(),
+      searchType: 'query',
+      size: 100,
+      edgeCache: 4
+    });
+    
+    const enrichedItems = await Promise.all(
+      categoryItems.data.map(async (item) => ({
+        ...item,
+        locations: await api.items.invMast.locations.list(item.invMastUid, {
+          edgeCache: 2
+        }),
+        alternates: await api.items.invMast.alternateCode.list(item.invMastUid, {
+          edgeCache: 4
+        })
+      }))
+    );
+    
+    products.push(...enrichedItems);
+  }
+  
+  return { products, categories: categories.data, brands: brands.data };
+}
+```
+
+### Inventory Management Dashboard
+
+```typescript
+// Real-time inventory status across multiple locations
+async function getInventoryDashboard(itemIds: string[]) {
+  const inventoryData = await Promise.all(
+    itemIds.map(async (itemId) => {
+      // Use the special lookup pattern
+      const itemLookup = await api.items.invMast.doc.get(0, { q: itemId });
+      const invMastUid = itemLookup.data.invMastUid;
+      
+      const [details, locations, movements] = await Promise.all([
+        api.items.invMast.get(invMastUid, { edgeCache: 1 }),
+        api.items.invMast.locations.list(invMastUid, { edgeCache: 0.5 }),
+        // Get recent activity (if available in your setup)
+        api.legacy.inventory.activity?.(itemId) || Promise.resolve({ data: [] })
+      ]);
+      
+      return {
+        itemId,
+        invMastUid,
+        details: details.data,
+        locations: locations.data,
+        totalQuantity: locations.data.reduce((sum, loc) => sum + loc.qtyOnHand, 0),
+        recentActivity: movements.data
+      };
+    })
+  );
+  
+  return inventoryData;
+}
+```
+
+## 🚀 Advanced Request Patterns
+
+### Request Cancellation
+
+```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);
+
+try {
+  const users = await usersPromise;
+} catch (error) {
+  if (error.name === 'AbortError') {
+    console.log('Request was cancelled');
+  }
+}
+```
+
+### 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'
+    }
+  }
+);
+```
+
+### Middleware Integration
+
+```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;
+  }
+});
+```
+
+## 🏗 Framework Integration Patterns
+
+### React Hook Pattern
+
+```tsx
+import React, { useState, useEffect } from 'react';
+import { AugurAPI, User, AugurAPIError, type AugurContext } from '@simpleapps-com/augur-api';
+
+// Custom hook for Augur API - Context-aware approach
+function useAugurAPI(context?: AugurContext) {
+  const [api] = useState(() => {
+    if (context) {
+      // Use context-aware creation (recommended)
+      return AugurAPI.fromContext(context);
+    }
+    
+    // Fallback to manual configuration
+    return new AugurAPI({
+      siteId: process.env.REACT_APP_AUGUR_SITE_ID!,
+      bearerToken: getStoredToken()
+    });
+  });
+  
+  return api;
+}
+
+// Component using the API
+const UserList: React.FC = () => {
+  const api = useAugurAPI();
+  const [users, setUsers] = useState<User[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    async function fetchUsers() {
+      try {
+        setLoading(true);
+        setError(null);
+        
+        const response = await api.joomla.users.list({ 
+          limit: 50,
+          edgeCache: 2  // Cache for 2 hours
+        });
+        
+        setUsers(response.data);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Unknown error');
+      } finally {
+        setLoading(false);
+      }
+    }
+
+    fetchUsers();
+  }, [api]);
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error}</div>;
+
+  return (
+    <ul>
+      {users.map(user => (
+        <li key={user.id}>{user.username}</li>
+      ))}
+    </ul>
+  );
+};
+```
+
+### Next.js API Route Integration
+
+```typescript
+// pages/api/users.ts
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { AugurAPI } from '@simpleapps-com/augur-api';
+
+const api = new AugurAPI({
+  siteId: process.env.AUGUR_SITE_ID!,
+  bearerToken: process.env.AUGUR_TOKEN!
+});
+
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse
+) {
+  try {
+    const { limit = 10, offset = 0 } = req.query;
+    
+    const users = await api.joomla.users.list({
+      limit: parseInt(limit as string),
+      offset: parseInt(offset as string),
+      edgeCache: 4  // 4 hours for server-side caching
+    });
+    
+    res.status(200).json(users);
+    
+  } catch (error) {
+    console.error('API Error:', error);
+    res.status(500).json({ error: 'Failed to fetch users' });
+  }
+}
+```
+
+### React Native Pattern
+
+```typescript
+// useAugurAPI.ts - React Native hook
+import { useState, useEffect } from 'react';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { AugurAPI } from '@simpleapps-com/augur-api';
+
+export function useAugurAPI() {
+  const [api, setApi] = useState<AugurAPI | null>(null);
+  const [isReady, setIsReady] = useState(false);
+
+  useEffect(() => {
+    async function initializeAPI() {
+      try {
+        const [siteId, token] = await Promise.all([
+          AsyncStorage.getItem('augur_site_id'),
+          AsyncStorage.getItem('augur_token')
+        ]);
+
+        if (siteId && token) {
+          const apiInstance = new AugurAPI({
+            siteId,
+            bearerToken: token
+          });
+          
+          setApi(apiInstance);
+        }
+      } catch (error) {
+        console.error('Failed to initialize API:', error);
+      } finally {
+        setIsReady(true);
+      }
+    }
+
+    initializeAPI();
+  }, []);
+
+  return { api, isReady };
+}
+```
+
+## 🛡️ Advanced Error Handling
+
+### Comprehensive Error Handling Pattern
+
+```typescript
+import { 
+  AugurAPIError,
+  AuthenticationError,
+  ValidationError,
+  NotFoundError,
+  RateLimitError,
+  NetworkError
+} from '@simpleapps-com/augur-api';
+
+async function handleAPICall() {
+  try {
+    const result = await api.joomla.users.list({ limit: 10 });
+    return result;
+    
+  } catch (error) {
+    // Handle specific error types
+    if (error instanceof AuthenticationError) {
+      console.error('Authentication failed:', error.message);
+      
+      switch (error.statusCode) {
+        case 401:
+          await refreshToken();
+          break;
+        default:
+          redirectToLogin();
+      }
+      
+    } else if (error instanceof ValidationError) {
+      console.error('Request validation failed:', error.validationErrors);
+      
+      error.validationErrors?.forEach(validationError => {
+        console.error(`Field ${validationError.path}: ${validationError.message}`);
+      });
+      
+    } else if (error instanceof NotFoundError) {
+      console.error('Resource not found:', error.message);
+      showNotFoundMessage(error.endpoint);
+      
+    } else if (error instanceof RateLimitError) {
+      console.error('Rate limit exceeded:', error.message);
+      
+      // Implement exponential backoff
+      await new Promise(resolve => setTimeout(resolve, 2000));
+      return handleAPICall(); // Retry
+      
+    } else if (error instanceof AugurAPIError) {
+      console.error('API error:', {
+        code: error.code,
+        message: error.message,
+        service: error.service,
+        endpoint: error.endpoint,
+        statusCode: error.statusCode,
+        requestId: error.requestId
+      });
+      
+      switch (error.statusCode) {
+        case 500:
+          showErrorMessage('Server error. Please try again later.');
+          break;
+        case 503:
+          showErrorMessage('Service temporarily unavailable.');
+          break;
+        default:
+          showErrorMessage(`API error: ${error.message}`);
+      }
+    }
+    
+    throw error; // Re-throw if needed
+  }
+}
+```
+
+### Retry Logic with Exponential Backoff
+
+```typescript
+async function apiCallWithRetry<T>(
+  operation: () => Promise<T>,
+  maxRetries = 3,
+  baseDelay = 1000
+): Promise<T> {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation();
+      
+    } catch (error) {
+      // Don't retry on authentication or validation errors
+      if (error instanceof AuthenticationError || 
+          error instanceof ValidationError) {
+        throw error;
+      }
+      
+      // Don't retry on final attempt
+      if (attempt === maxRetries) {
+        throw error;
+      }
+      
+      // Calculate delay with exponential backoff
+      const delay = baseDelay * Math.pow(2, attempt - 1);
+      console.log(`Attempt ${attempt} failed, retrying in ${delay}ms...`);
+      
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+  
+  throw new Error('All retry attempts exhausted');
+}
+
+// Usage
+const users = await apiCallWithRetry(() => 
+  api.joomla.users.list({ limit: 10 })
+);
+```
+
+### Global Error Handler
+
+```typescript
+class ErrorHandler {
+  static handle(error: unknown, context?: string): void {
+    const contextPrefix = context ? `[${context}] ` : '';
+    
+    if (error instanceof AuthenticationError) {
+      console.error(`${contextPrefix}Authentication failed:`, error.message);
+      this.handleAuthError(error);
+      
+    } else if (error instanceof ValidationError) {
+      console.error(`${contextPrefix}Validation failed:`, error.validationErrors);
+      this.handleValidationError(error);
+      
+    } else if (error instanceof AugurAPIError) {
+      console.error(`${contextPrefix}API error:`, {
+        service: error.service,
+        endpoint: error.endpoint,
+        status: error.statusCode,
+        message: error.message
+      });
+      
+      this.handleAPIError(error);
+      
+    } else {
+      console.error(`${contextPrefix}Unexpected error:`, error);
+    }
+  }
+  
+  private static handleAuthError(error: AuthenticationError) {
+    // Implement token refresh logic
+    if (typeof window !== 'undefined') {
+      window.location.href = '/login';
+    }
+  }
+  
+  private static handleValidationError(error: ValidationError) {
+    // Show user-friendly validation messages
+    if (error.validationErrors) {
+      error.validationErrors.forEach(err => {
+        showFieldError(err.path, err.message);
+      });
+    }
+  }
+  
+  private static handleAPIError(error: AugurAPIError) {
+    // Log to monitoring service
+    if (typeof window !== 'undefined' && window.analytics) {
+      window.analytics.track('API Error', {
+        service: error.service,
+        endpoint: error.endpoint,
+        statusCode: error.statusCode
+      });
+    }
+  }
+}
+```
+
+## 🏎️ Advanced Caching Strategies
+
+### Edge Cache Duration Guide
+
+| Value | Duration | Best For | Example Use Cases |
+|-------|----------|----------|-------------------|
+| `1` | 1 hour | Frequently changing data | Cart contents, user sessions, real-time pricing |
+| `2` | 2 hours | Moderate volatility | User lists, inventory levels, order status |
+| `3` | 3 hours | Standard business data | Standard pricing, product information, customer data |
+| `4` | 4 hours | Semi-static data | Recommendations, warehouse data, shipping rates |
+| `5` | 5 hours | Reference data | Tags, categories, attribute lists |
+| `8` | 8 hours | Static content | Brand information, distributor details, system configs |
+
+### Smart Cache Implementation
+
+```typescript
+// Cache strategy based on data volatility
+class CacheStrategy {
+  static getOptimalTTL(dataType: string, context?: any): number {
+    switch (dataType) {
+      case 'user_session':
+      case 'cart_contents':
+      case 'real_time_pricing':
+        return 1; // 1 hour
+        
+      case 'inventory_levels':
+      case 'order_status':
+      case 'user_profiles':
+        return 2; // 2 hours
+        
+      case 'product_catalog':
+      case 'standard_pricing':
+      case 'customer_data':
+        return 3; // 3 hours
+        
+      case 'recommendations':
+      case 'warehouse_locations':
+      case 'shipping_rates':
+        return 4; // 4 hours
+        
+      case 'categories':
+      case 'attributes':
+      case 'tags':
+        return 5; // 5 hours
+        
+      case 'brands':
+      case 'system_config':
+      case 'distributor_info':
+        return 8; // 8 hours
+        
+      default:
+        return 2; // Safe default
+    }
+  }
+}
+
+// Usage in API calls
+const categories = await api.items.categories.list({
+  edgeCache: CacheStrategy.getOptimalTTL('categories')
+});
+
+const userCart = await api.commerce.cartHeaders.list({
+  userId: 123,
+  edgeCache: CacheStrategy.getOptimalTTL('cart_contents')
+});
+```
+
+### Cache Invalidation Patterns
+
+```typescript
+// Cache warming for critical data
+async function warmCache() {
+  const criticalData = [
+    () => api.items.categories.list({ edgeCache: 8 }),
+    () => api.items.brands.list({ edgeCache: 8 }),
+    () => api.items.attributes.list({ edgeCache: 5 }),
+  ];
+  
+  // Warm cache in parallel
+  await Promise.all(criticalData.map(fn => fn()));
+}
+
+// Cache busting for updated data
+async function updateProductAndInvalidateCache(productId: number, updates: any) {
+  // Update the product
+  await api.items.invMast.update(productId, updates);
+  
+  // Force refresh cached data (edgeCache: 0 bypasses cache)
+  const freshData = await api.items.invMast.get(productId, { edgeCache: 0 });
+  
+  return freshData;
+}
+```
+
+---
+
+## 💡 Pro Tips
+
+1. **Always cache reference data** - Categories, brands, and attributes change infrequently
+2. **Use the itemId → invMastUid lookup** - It's the bridge between user-facing IDs and internal UIDs  
+3. **Batch related requests** - Use `Promise.all()` for independent parallel requests
+4. **Handle 404s gracefully** - Not all items exist in all systems
+5. **Monitor cache hit rates** - Adjust TTL values based on actual usage patterns
+6. **Use TypeScript** - The client provides full type safety for better development experience
+
+---
+
+*This document is part of the [Augur API Client Library](./README.md) package and is included in npm distributions for offline reference.*