@fjell/client-api 4.4.6 → 4.4.9

package/examples/README.md

@@ -0,0 +1,387 @@
+# Fjell-Client-API Examples
+
+This directory contains examples demonstrating how to use fjell-client-api for HTTP-based data operations and client-side API management with different patterns and complexity levels.
+
+## Examples
+
+### 1. `simple-example.ts` ⭐ **Start Here!**
+**Perfect for beginners!** Demonstrates the simplest way to use fjell-client-api for HTTP data operations:
+- **Basic CRUD operations** - Create, Read, Update, Delete through HTTP endpoints
+- **Primary and Contained APIs** - PItemApi for independent entities, CItemApi for hierarchical data
+- **Client API configuration** - HTTP endpoints, authentication, and error handling
+- **Actions and facets** - Business logic execution and analytics retrieval
+
+Great for understanding the fundamentals of fjell-client-api HTTP operations.
+
+### 2. `multi-level-keys.ts`
+**Advanced hierarchical data models!** Demonstrates complex data structures with multi-level contained items:
+- **Hierarchical models**: Organization → Department → Employee
+- **Multi-level location keys**: Complex organizational structure management
+- **Nested API routing**: `/organizations/{orgId}/departments/{deptId}/employees/{empId}`
+- **Cross-hierarchy operations**: Complex queries spanning multiple organizational levels
+- **Location-based analytics**: Department and employee-specific metrics and operations
+
+Shows how fjell-client-api handles enterprise organizational data patterns with deep hierarchies.
+
+### 3. `enterprise-example.ts` 🏗️ **Full Business Application**
+**Complete enterprise e-commerce system!** Demonstrates advanced business application patterns:
+- **Multiple interconnected entities**: Customer, Product, Order, OrderItem, SupportTicket, ProductReview
+- **Business workflow automation**: Order fulfillment, support ticket resolution, inventory management
+- **Advanced analytics facets**: Customer analytics, product performance, order metrics
+- **Enterprise features**: Multi-tenant configuration, complex business logic, predictive analytics
+- **Real business scenarios**: Complete e-commerce platform with customer lifecycle management
+
+Perfect for understanding how to build complete enterprise applications with fjell-client-api.
+
+## Key Concepts Demonstrated
+
+### Basic Client API Operations (simple-example.ts)
+```typescript
+// Import fjell-client-api functionality
+import { createPItemApi, createCItemApi } from '@fjell/client-api';
+
+// Configure API endpoints
+const apiConfig = {
+  baseUrl: 'http://localhost:3000/api',
+  headers: { 'Authorization': 'Bearer token' }
+};
+
+// Create Primary Item API (independent entities)
+const userApi = createPItemApi<User, 'user'>('user', ['users'], apiConfig);
+
+// Create Contained Item API (hierarchical entities)
+const taskApi = createCItemApi<Task, 'task', 'user'>('task', ['users', 'tasks'], apiConfig);
+
+// Basic operations
+const users = await userApi.all(query);
+const user = await userApi.create(userData);
+const tasks = await taskApi.all(query, [userId]); // Location-based query
+```
+
+### Hierarchical Data Management (multi-level-keys.ts)
+```typescript
+// Multi-level organizational structure
+// Organization (Level 0) → Department (Level 1) → Employee (Level 2)
+
+// Organization API (Primary Items)
+const orgApi = createPItemApi<Organization, 'organization'>('organization', ['organizations'], config);
+
+// Department API (Contained in Organization)
+const deptApi = createCItemApi<Department, 'department', 'organization'>(
+  'department',
+  ['organizations', 'departments'],
+  config
+);
+
+// Employee API (Contained in Department within Organization)
+const empApi = createCItemApi<Employee, 'employee', 'organization', 'department'>(
+  'employee',
+  ['organizations', 'departments', 'employees'],
+  config
+);
+
+// Multi-level operations
+const orgLocation = [organizationId];
+const deptLocation = [organizationId, departmentId];
+
+await deptApi.all(query, orgLocation);           // All departments in org
+await empApi.all(query, deptLocation);          // All employees in dept
+```
+
+### Enterprise Business Workflows (enterprise-example.ts)
+```typescript
+// Customer lifecycle management
+const customerApi = createPItemApi<Customer, 'customer'>('customer', ['customers'], config);
+const supportApi = createCItemApi<SupportTicket, 'supportTicket', 'customer'>(
+  'supportTicket',
+  ['customers', 'tickets'],
+  config
+);
+
+// Business workflow example
+// 1. Create customer
+const customer = await customerApi.create(customerData);
+
+// 2. Create support ticket for customer
+const ticket = await supportApi.create(ticketData, [customer.id]);
+
+// 3. Execute business actions
+await supportApi.action(ticketKey, 'escalate-ticket', { reason: 'complex issue' });
+await supportApi.action(ticketKey, 'resolve-ticket', { resolution: 'provided solution' });
+
+// 4. Get business analytics
+const customerMetrics = await customerApi.facet(customerKey, 'loyalty-metrics');
+const supportAnalytics = await supportApi.allFacet('resolution-metrics', {}, [customer.id]);
+```
+
+## API Types and Patterns
+
+### Primary Item API (PItemApi)
+Used for independent entities that exist at the top level:
+- **Endpoints**: `/entities/{id}`
+- **Use cases**: Customers, Products, Orders, Organizations
+- **Operations**: Standard CRUD + actions + facets
+- **No location context required**
+
+```typescript
+interface PItemApi<V, S> {
+  all(query: ItemQuery): Promise<V[]>;
+  create(item: Partial<Item<S>>): Promise<V>;
+  get(key: PriKey<S>): Promise<V>;
+  update(key: PriKey<S>, updates: Partial<Item<S>>): Promise<V>;
+  remove(key: PriKey<S>): Promise<boolean>;
+  action(key: PriKey<S>, action: string, body?: any): Promise<any>;
+  find(finder: string, params?: any): Promise<V[]>;
+  facet(key: PriKey<S>, facet: string, params?: any): Promise<any>;
+  allAction(action: string, body?: any): Promise<V[]>;
+  allFacet(facet: string, params?: any): Promise<any>;
+}
+```
+
+### Contained Item API (CItemApi)
+Used for hierarchical entities that belong to parent locations:
+- **Endpoints**: `/parents/{parentId}/entities/{id}`
+- **Use cases**: Tasks (in Users), OrderItems (in Orders), Employees (in Departments)
+- **Operations**: CRUD + actions + facets with location context
+- **Requires location arrays for context**
+
+```typescript
+interface CItemApi<V, S, L1, L2, L3, L4, L5> extends ClientApi<V, S, L1, L2, L3, L4, L5> {
+  all(query: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5>): Promise<V[]>;
+  create(item: Partial<Item<S>>, locations?: LocKeyArray<L1, L2, L3, L4, L5>): Promise<V>;
+  find(finder: string, params?: any, locations?: LocKeyArray<L1, L2, L3, L4, L5>): Promise<V[]>;
+  allAction(action: string, body?: any, locations?: LocKeyArray<L1, L2, L3, L4, L5>): Promise<V[]>;
+  allFacet(facet: string, params?: any, locations?: LocKeyArray<L1, L2, L3, L4, L5>): Promise<any>;
+}
+```
+
+## Business Logic Patterns
+
+### Actions - Business Logic Execution
+Actions execute business logic on entities or collections:
+
+```typescript
+// Single entity actions
+await userApi.action(userKey, 'activate', { reason: 'manual activation' });
+await orderApi.action(orderKey, 'fulfill-order', { warehouse: 'main' });
+await ticketApi.action(ticketKey, 'escalate', { priority: 'urgent' });
+
+// Batch actions on collections
+await userApi.allAction('updatePreferences', { newsletter: true });
+await productApi.allAction('applyDiscount', { percent: 10 });
+await orderApi.allAction('expediteShipping', { method: 'express' });
+```
+
+### Facets - Analytics and Data Retrieval
+Facets retrieve analytics, computed data, and business insights:
+
+```typescript
+// Entity-specific analytics
+const userStats = await userApi.facet(userKey, 'purchase-history');
+const productMetrics = await productApi.facet(productKey, 'performance-metrics');
+const orderStatus = await orderApi.facet(orderKey, 'fulfillment-status');
+
+// Aggregated analytics
+const customerAnalytics = await customerApi.allFacet('revenue-analytics', { period: 'quarterly' });
+const inventoryReport = await productApi.allFacet('inventory-analytics', { lowStock: true });
+const salesMetrics = await orderApi.allFacet('sales-metrics', { region: 'north-america' });
+```
+
+## Configuration Patterns
+
+### Basic Configuration
+```typescript
+const apiConfig = {
+  baseUrl: 'https://api.example.com',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': 'Bearer your-api-token'
+  },
+  timeout: 5000
+};
+```
+
+### Enterprise Configuration
+```typescript
+const enterpriseConfig = {
+  baseUrl: 'https://api.enterprise.com/v1',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': 'Bearer enterprise-token',
+    'X-Tenant-ID': 'tenant-001',
+    'X-Environment': 'production'
+  },
+  timeout: 10000,
+  retries: 3,
+  readAuthenticated: true,
+  writeAuthenticated: true
+};
+```
+
+## Error Handling Patterns
+
+### Basic Error Handling
+```typescript
+try {
+  const user = await userApi.get(userKey);
+  if (!user) {
+    console.log('User not found');
+    return;
+  }
+  // Process user...
+} catch (error) {
+  console.error('API error:', error);
+  // Handle specific error types
+  if (error.status === 404) {
+    // Handle not found
+  } else if (error.status === 401) {
+    // Handle authentication error
+  }
+}
+```
+
+### Enterprise Error Handling
+```typescript
+try {
+  const result = await customerApi.action(customerKey, 'process-order', orderData);
+  return result;
+} catch (error) {
+  // Log error with context
+  console.error('Order processing failed:', {
+    customerId: customerKey.id,
+    error: error.message,
+    timestamp: new Date()
+  });
+
+  // Implement retry logic for transient errors
+  if (error.isRetryable) {
+    return await retryOperation(() =>
+      customerApi.action(customerKey, 'process-order', orderData)
+    );
+  }
+
+  throw error;
+}
+```
+
+## Testing Patterns
+
+The examples include comprehensive integration tests in `tests/examples/` that demonstrate:
+
+- **API operation testing** - Verifying CRUD operations work correctly
+- **Business workflow testing** - Testing complete business processes
+- **Error scenario testing** - Handling various error conditions
+- **Performance testing** - Measuring API response times
+- **Mock API testing** - Testing with mock backend services
+
+### Running Tests
+```bash
+# Run all example tests
+npm test -- tests/examples
+
+# Run specific example tests
+npm test -- tests/examples/simple-example.integration.test.ts
+npm test -- tests/examples/multi-level-keys.integration.test.ts
+npm test -- tests/examples/enterprise-example.integration.test.ts
+
+# Run with coverage
+npm run test:coverage -- tests/examples
+```
+
+## Real-World Usage
+
+### When to Use PItemApi
+- **Independent entities**: Users, Products, Orders, Organizations
+- **Top-level resources**: Resources that don't belong to other entities
+- **Simple CRUD needs**: Basic create, read, update, delete operations
+- **Global operations**: Operations that span across the entire system
+
+### When to Use CItemApi
+- **Hierarchical data**: Tasks in Projects, OrderItems in Orders, Comments in Posts
+- **Location-based operations**: Operations within specific parent contexts
+- **Multi-tenant scenarios**: Data that belongs to specific tenants or organizations
+- **Nested resources**: Resources that logically belong to parent resources
+
+### Enterprise Considerations
+- **Authentication**: Use proper bearer tokens or API keys
+- **Rate limiting**: Implement client-side rate limiting for high-volume operations
+- **Caching**: Cache frequently accessed data to reduce API calls
+- **Monitoring**: Log API calls and performance metrics
+- **Error recovery**: Implement retry logic and circuit breakers
+- **Data validation**: Validate data before sending to API
+
+## Running the Examples
+
+### Prerequisites
+```bash
+# Install dependencies
+npm install
+
+# Ensure TypeScript is available
+npm install -g tsx
+```
+
+### Run Individual Examples
+```bash
+# Simple example (start here)
+npx tsx examples/simple-example.ts
+
+# Multi-level keys example
+npx tsx examples/multi-level-keys.ts
+
+# Enterprise example (most comprehensive)
+npx tsx examples/enterprise-example.ts
+```
+
+### Run All Examples
+```bash
+# Run all examples in sequence
+npx tsx -e "
+import { runSimpleExample } from './examples/simple-example.js';
+import { runMultiLevelKeysExample } from './examples/multi-level-keys.js';
+import { runEnterpriseExample } from './examples/enterprise-example.js';
+
+console.log('🚀 Running All Fjell-Client-API Examples\\n');
+
+await runSimpleExample();
+console.log('\\n' + '='.repeat(50) + '\\n');
+
+await runMultiLevelKeysExample();
+console.log('\\n' + '='.repeat(50) + '\\n');
+
+await runEnterpriseExample();
+
+console.log('\\n✅ All examples completed successfully!');
+"
+```
+
+## Next Steps
+
+After exploring these examples:
+
+1. **Read the API Documentation** - Understand the full fjell-client-api specification
+2. **Set up your HTTP backend** - Implement corresponding server endpoints
+3. **Configure authentication** - Set up proper API authentication for your application
+4. **Implement error handling** - Add comprehensive error handling for production use
+5. **Add monitoring** - Implement logging and monitoring for API operations
+6. **Write tests** - Create tests for your specific API usage patterns
+7. **Optimize performance** - Add caching, pagination, and other performance optimizations
+
+## Contributing
+
+To add new examples or improve existing ones:
+
+1. Create your example file in `examples/`
+2. Add corresponding integration tests in `tests/examples/`
+3. Update this README with documentation
+4. Ensure examples follow the established patterns
+5. Test thoroughly with both success and error scenarios
+
+## Support
+
+For questions about these examples or fjell-client-api usage:
+
+- Check the main fjell-client-api documentation
+- Review the integration tests for detailed usage patterns
+- Look at the enterprise example for complex workflow patterns
+- Examine the source code for specific API method signatures