@fjell/client-api 4.4.12 → 4.4.13

package/docs/docs.config.ts

@@ -0,0 +1,77 @@
+interface DocsConfig {
+  projectName: string;
+  basePath: string;
+  port: number;
+  branding: {
+    theme: string;
+    tagline: string;
+    logo?: string;
+    backgroundImage?: string;
+    primaryColor?: string;
+    accentColor?: string;
+    github?: string;
+    npm?: string;
+  };
+  sections: Array<{
+    id: string;
+    title: string;
+    subtitle: string;
+    file: string;
+  }>;
+  filesToCopy: Array<{
+    source: string;
+    destination: string;
+  }>;
+  plugins?: any[];
+  version: {
+    source: string;
+  };
+  customContent?: {
+    [key: string]: (content: string) => string;
+  };
+}
+
+const config: DocsConfig = {
+  projectName: 'Fjell Client API',
+  basePath: '/client-api/',
+  port: 3002,
+  branding: {
+    theme: 'client-api',
+    tagline: 'HTTP Client Library for Fjell',
+    backgroundImage: '/pano.png',
+    github: 'https://github.com/getfjell/client-api',
+    npm: 'https://www.npmjs.com/package/@fjell/client-api'
+  },
+  sections: [
+    {
+      id: 'overview',
+      title: 'Foundation',
+      subtitle: 'Core concepts & HTTP client capabilities',
+      file: '/client-api/README.md'
+    },
+    {
+      id: 'api-reference',
+      title: 'API Reference',
+      subtitle: 'Complete method documentation',
+      file: '/client-api/api-reference.md'
+    },
+    {
+      id: 'examples',
+      title: 'Examples',
+      subtitle: 'Code examples & usage patterns',
+      file: '/client-api/examples-README.md'
+    }
+  ],
+  filesToCopy: [
+    {
+      source: '../examples/README.md',
+      destination: 'public/examples-README.md'
+    }
+  ],
+  plugins: [],
+  version: {
+    source: 'package.json'
+  }
+}
+
+export default config

package/docs/package.json

@@ -4,18 +4,17 @@
   "version": "0.0.0",
   "type": "module",
   "scripts": {
-    "dev": "vite",
-    "build": "tsc && vite build",
+    "copy-docs": "node node_modules/@fjell/docs-template/scripts/copy-docs.js",
+    "dev": "pnpm run copy-docs && vite",
+    "build": "pnpm run copy-docs && tsc && vite build",
     "preview": "vite preview",
     "test": "vitest run --coverage",
     "test:watch": "vitest --watch"
   },
   "dependencies": {
+    "@fjell/docs-template": "1.0.5",
     "react": "^19.1.0",
-    "react-dom": "^19.1.0",
-    "react-markdown": "^10.1.0",
-    "react-syntax-highlighter": "^15.6.1",
-    "remark-gfm": "^4.0.1"
+    "react-dom": "^19.1.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",

package/docs/public/examples-README.md

@@ -114,6 +114,202 @@ 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
@@ -137,6 +333,28 @@ npx tsx examples/multi-level-keys.ts
 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:
@@ -148,3 +366,22 @@ After exploring these examples:
 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

package/docs/src/main.tsx

@@ -1,10 +1,12 @@
 import React from 'react'
 import ReactDOM from 'react-dom/client'
-import App from './App.tsx'
+import { DocsApp } from '@fjell/docs-template'
+import '@fjell/docs-template/dist/index.css'
+import config from '../docs.config'
 import './index.css'
 
 ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <App />
-  </React.StrictMode>,
+    <React.StrictMode>
+        <DocsApp config={config} />
+    </React.StrictMode>,
 )

package/docs/src/types.d.ts

@@ -0,0 +1,44 @@
+// Types are provided by the @fjell/docs-template package
+
+declare module '@fjell/docs-template' {
+  export interface DocsConfig {
+    projectName: string;
+    basePath: string;
+    port: number;
+    branding: {
+      theme: string;
+      tagline: string;
+      logo?: string;
+      backgroundImage?: string;
+      primaryColor?: string;
+      accentColor?: string;
+      github?: string;
+      npm?: string;
+    };
+    sections: Array<{
+      id: string;
+      title: string;
+      subtitle: string;
+      file: string;
+    }>;
+    plugins?: any[];
+    version: {
+      source: string;
+    };
+    customContent?: {
+      [key: string]: (content: string) => string;
+    };
+  }
+
+  export interface DocsAppProps {
+    config: DocsConfig;
+  }
+
+  export const DocsApp: React.ComponentType<DocsAppProps>;
+}
+
+declare module '../docs.config.ts' {
+  import type { DocsConfig } from '@fjell/docs-template'
+  const config: DocsConfig
+  export default config
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fjell/client-api",
   "description": "Client API for Fjell",
-  "version": "4.4.12",
+  "version": "4.4.13",
   "keywords": [
     "client",
     "api",
@@ -18,16 +18,16 @@
   },
   "dependencies": {
     "@fjell/core": "^4.4.13",
-    "@fjell/http-api": "^4.4.15",
-    "@fjell/logging": "^4.4.13",
-    "@fjell/registry": "^4.4.11",
+    "@fjell/http-api": "^4.4.16",
+    "@fjell/logging": "^4.4.17",
+    "@fjell/registry": "^4.4.16",
     "deepmerge": "^4.3.1"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.31.0",
     "@fjell/eslint-config": "^1.0.5",
-    "@swc/core": "^1.13.1",
+    "@swc/core": "^1.13.2",
     "@tsconfig/recommended": "^1.0.10",
     "@typescript-eslint/eslint-plugin": "^8.38.0",
     "@typescript-eslint/parser": "^8.38.0",
@@ -53,6 +53,10 @@
     "lint": "eslint . --ext .ts --fix",
     "clean": "rimraf dist",
     "test": "vitest run --coverage",
-    "test:ui": "vitest --ui"
+    "test:ui": "vitest --ui",
+    "docs:dev": "cd docs && pnpm run dev",
+    "docs:build": "cd docs && pnpm run build",
+    "docs:preview": "cd docs && pnpm run preview",
+    "docs:test": "cd docs && pnpm run test"
   }
 }