@owlmeans/api-config-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OwlMeans Common — Fullstack typescript framework
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,313 @@
+# @owlmeans/api-config-client
+
+The **@owlmeans/api-config-client** package provides client-side functionality for fetching and applying API configuration from OwlMeans Common Libraries servers, designed for fullstack microservices and microclients development with focus on security and proper authentication and authorization.
+
+## Purpose
+
+This package serves as the client-side component of the OwlMeans configuration system that:
+
+- **Fetches configuration from servers** using the API config module system
+- **Applies configuration dynamically** to client contexts during initialization
+- **Integrates with client modules** for seamless API communication
+- **Supports multi-service architecture** with configurable primary hosts
+- **Provides middleware integration** for automatic configuration loading
+
+## Core Concepts
+
+### API Configuration Module
+The package elevates the common API config module to a client module, enabling it to make HTTP requests to fetch configuration from servers.
+
+### Configuration Middleware
+Provides middleware that automatically fetches and merges server configuration during client context initialization, ensuring the client has the latest configuration before becoming operational.
+
+### Primary Host Configuration
+Supports configuration of primary hosts and ports for API communication, allowing clients to know where to fetch their configuration from.
+
+## API Reference
+
+### Modules
+
+#### `modules`
+
+Exported client modules array containing the elevated API config module.
+
+```typescript
+import { modules } from '@owlmeans/api-config-client'
+
+// Register all client API config modules
+context.registerModules(modules)
+```
+
+### Middleware
+
+#### `apiConfigMiddleware`
+
+Middleware that fetches configuration from the API config endpoint during context loading.
+
+```typescript
+import { apiConfigMiddleware } from '@owlmeans/api-config-client'
+
+context.registerMiddleware(apiConfigMiddleware)
+```
+
+**Properties:**
+- `type`: `MiddlewareType.Context`
+- `stage`: `MiddlewareStage.Loading`
+
+**Behavior:**
+- Executes during the Loading stage of context initialization
+- Checks if `primaryHost` is configured in the client config
+- Fetches configuration from the API config module endpoint
+- Merges received configuration with the existing client configuration
+- Handles errors gracefully by logging them without breaking initialization
+
+### Dependencies
+
+The package depends on several OwlMeans Common packages:
+- `@owlmeans/api-config` - Common API config module definitions
+- `@owlmeans/client-context` - Client-side context management
+- `@owlmeans/client-module` - Client-side module system
+- `@owlmeans/context` - Core context functionality
+
+## Usage Examples
+
+### Basic Integration
+
+```typescript
+import { makeClientContext, makeClientConfig } from '@owlmeans/client-context'
+import { modules, apiConfigMiddleware } from '@owlmeans/api-config-client'
+import { AppType } from '@owlmeans/context'
+
+// Create client configuration with primary host
+const config = makeClientConfig(AppType.Frontend, 'web-client', {
+  primaryHost: 'api.myapp.com',
+  primaryPort: 443
+})
+
+// Create and configure context
+const context = makeClientContext(config)
+
+// Register API config middleware
+context.registerMiddleware(apiConfigMiddleware)
+
+// Register API config modules
+context.registerModules(modules)
+
+// Configure and initialize - configuration will be fetched automatically
+context.configure()
+await context.init()
+
+// Context now has merged configuration from server
+console.log('Final config:', await context.config)
+```
+
+### Manual Configuration Fetching
+
+```typescript
+import { modules } from '@owlmeans/api-config-client'
+import { API_CONFIG } from '@owlmeans/api-config'
+
+// Get the API config module
+const configModule = context.module(API_CONFIG)
+
+// Manually fetch configuration
+try {
+  const [serverConfig] = await configModule.call()
+  console.log('Server configuration:', serverConfig)
+} catch (error) {
+  console.error('Failed to fetch configuration:', error)
+}
+```
+
+### Advanced Configuration
+
+```typescript
+import { makeClientContext, makeClientConfig } from '@owlmeans/client-context'
+import { modules, apiConfigMiddleware } from '@owlmeans/api-config-client'
+import { AppType } from '@owlmeans/context'
+
+const config = makeClientConfig(AppType.Frontend, 'mobile-client', {
+  primaryHost: 'api.example.com',
+  primaryPort: 8080,
+  // Additional client configuration
+  debug: { all: true },
+  services: {
+    'user-service': {
+      host: 'users.example.com',
+      port: 8081
+    }
+  }
+})
+
+const context = makeClientContext(config)
+
+// Register middleware first
+context.registerMiddleware(apiConfigMiddleware)
+
+// Register modules
+context.registerModules(modules)
+
+// Add custom middleware to run after config is loaded
+context.registerMiddleware({
+  type: MiddlewareType.Context,
+  stage: MiddlewareStage.Ready,
+  apply: async (ctx) => {
+    console.log('Configuration loaded and merged')
+    const finalConfig = await ctx.config
+    console.log('Available services:', Object.keys(finalConfig.services || {}))
+  }
+})
+
+await context.configure().init()
+```
+
+### Error Handling
+
+```typescript
+import { modules, apiConfigMiddleware } from '@owlmeans/api-config-client'
+
+// The middleware handles errors gracefully
+context.registerMiddleware(apiConfigMiddleware)
+
+// You can also add custom error handling
+context.registerMiddleware({
+  type: MiddlewareType.Context,
+  stage: MiddlewareStage.Loading,
+  apply: async (ctx) => {
+    const clientCtx = ctx as ClientContext
+    if (clientCtx.cfg.primaryHost) {
+      try {
+        const configModule = clientCtx.module(API_CONFIG)
+        const [config] = await configModule.call()
+        console.log('Successfully fetched config')
+      } catch (error) {
+        console.warn('Config fetch failed, using defaults:', error.message)
+        // Implement fallback configuration logic
+      }
+    }
+  }
+})
+```
+
+### Multiple Service Configuration
+
+```typescript
+// Client can fetch configuration that includes multiple service endpoints
+const config = makeClientConfig(AppType.Frontend, 'dashboard-client', {
+  primaryHost: 'config.myapp.com'
+})
+
+const context = makeClientContext(config)
+context.registerMiddleware(apiConfigMiddleware)
+context.registerModules(modules)
+
+await context.configure().init()
+
+// After initialization, context will have configuration for all services
+const finalConfig = await context.config
+console.log('Auth service:', finalConfig.services?.auth)
+console.log('User service:', finalConfig.services?.users)
+console.log('Payment service:', finalConfig.services?.payments)
+```
+
+## Integration Patterns
+
+### With React Applications
+
+```typescript
+import React from 'react'
+import { ClientContext } from '@owlmeans/client-context'
+import { modules, apiConfigMiddleware } from '@owlmeans/api-config-client'
+
+const initializeApp = async () => {
+  const config = makeClientConfig(AppType.Frontend, 'react-app', {
+    primaryHost: process.env.REACT_APP_API_HOST
+  })
+  
+  const context = makeClientContext(config)
+  context.registerMiddleware(apiConfigMiddleware)
+  context.registerModules(modules)
+  
+  await context.configure().init()
+  return context
+}
+
+const App: React.FC = () => {
+  const [context, setContext] = useState<ClientContext | null>(null)
+  
+  useEffect(() => {
+    initializeApp().then(setContext)
+  }, [])
+  
+  if (!context) return <div>Loading configuration...</div>
+  
+  return (
+    <ClientContext.Provider value={context}>
+      {/* Your app components */}
+    </ClientContext.Provider>
+  )
+}
+```
+
+### With Service Workers
+
+```typescript
+// In service worker or background process
+import { modules, apiConfigMiddleware } from '@owlmeans/api-config-client'
+
+const setupBackgroundSync = async () => {
+  const config = makeClientConfig(AppType.Frontend, 'sw-client', {
+    primaryHost: self.registration.scope + 'api'
+  })
+  
+  const context = makeClientContext(config)
+  context.registerMiddleware(apiConfigMiddleware)
+  context.registerModules(modules)
+  
+  await context.configure().init()
+  
+  // Now context has all service configurations for background operations
+  return context
+}
+```
+
+## Configuration Flow
+
+1. **Context Creation** - Create client context with `primaryHost` configuration
+2. **Middleware Registration** - Register `apiConfigMiddleware` to handle automatic config fetching
+3. **Module Registration** - Register API config modules for communication
+4. **Context Initialization** - During `init()`, middleware fetches server configuration
+5. **Configuration Merge** - Server configuration is merged with local client configuration
+6. **Ready State** - Context becomes ready with complete configuration
+
+## Error Handling
+
+The package handles various error scenarios:
+
+- **Network failures** - Logged but don't prevent initialization
+- **Invalid responses** - Gracefully handled with fallback to existing configuration
+- **Missing primary host** - Middleware skips execution if no primary host configured
+- **Module call failures** - Errors are caught and logged without breaking the initialization flow
+
+## Best Practices
+
+1. **Set primary host early** - Configure `primaryHost` in your client configuration
+2. **Register middleware first** - Ensure middleware is registered before modules
+3. **Handle initialization** - Always await context initialization before use
+4. **Monitor errors** - Log and monitor configuration fetch failures
+5. **Implement fallbacks** - Have default configurations ready for offline scenarios
+6. **Secure communication** - Use HTTPS for production API config endpoints
+
+## Security Considerations
+
+- **Validate endpoints** - Ensure primary host is a trusted server
+- **Handle secrets carefully** - Configuration may contain sensitive service information
+- **Monitor traffic** - Log configuration requests for security auditing
+- **Use authentication** - Combine with auth modules for secured configuration access
+
+## Related Packages
+
+- [`@owlmeans/api-config`](../api-config) - Common API config module definitions
+- [`@owlmeans/api-config-server`](../api-config-server) - Server-side API config implementation
+- [`@owlmeans/client-context`](../client-context) - Client-side context management
+- [`@owlmeans/client-module`](../client-module) - Client-side module system

package/build/index.d.ts

@@ -0,0 +1,3 @@
+export * from './middleware.js';
+export * from './modules.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA"}

package/build/index.js

@@ -0,0 +1,3 @@
+export * from './middleware.js';
+export * from './modules.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA"}

package/build/middleware.d.ts

@@ -0,0 +1,3 @@
+import type { Middleware } from '@owlmeans/context';
+export declare const apiConfigMiddleware: Middleware;
+//# sourceMappingURL=middleware.d.ts.map

package/build/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AASnD,eAAO,MAAM,mBAAmB,EAAE,UAsBjC,CAAA"}

package/build/middleware.js

@@ -0,0 +1,26 @@
+import { MiddlewareType, MiddlewareStage, assertContext } from '@owlmeans/context';
+import { API_CONFIG } from '@owlmeans/api-config';
+import { mergeConfig } from '@owlmeans/config';
+export const apiConfigMiddleware = {
+    type: MiddlewareType.Context,
+    stage: MiddlewareStage.Loading,
+    apply: async (ctx) => {
+        const context = assertContext(ctx, 'api-config-middleware');
+        const module = context.module(API_CONFIG);
+        if (context.cfg.primaryHost != null) {
+            module.route.route.host = context.cfg.primaryHost;
+            if (context.cfg.primaryPort != null) {
+                module.route.route.port = context.cfg.primaryPort;
+            }
+            try {
+                const [config] = await module.call();
+                const target = context.cfg;
+                mergeConfig(target, config);
+            }
+            catch (e) {
+                console.error(e);
+            }
+        }
+    }
+};
+//# sourceMappingURL=middleware.js.map

package/build/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAGlF,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAI9C,MAAM,CAAC,MAAM,mBAAmB,GAAe;IAC7C,IAAI,EAAE,cAAc,CAAC,OAAO;IAC5B,KAAK,EAAE,eAAe,CAAC,OAAO;IAC9B,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;QACnB,MAAM,OAAO,GAAG,aAAa,CAC3B,GAAU,EAAE,uBAAuB,CACpC,CAAA;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAA0B,UAAU,CAAC,CAAA;QAClE,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,IAAI,EAAE,CAAC;YACpC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAA;YACjD,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,IAAI,EAAE,CAAC;gBACpC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAA;YACnD,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;gBACpC,MAAM,MAAM,GAAiB,OAAO,CAAC,GAA8B,CAAA;gBACnE,WAAW,CAAC,MAAM,EAAE,MAAsB,CAAC,CAAA;YAC7C,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;YAClB,CAAC;QACH,CAAC;IACH,CAAC;CACF,CAAA"}

package/build/modules.d.ts

@@ -0,0 +1,2 @@
+export declare const modules: import("@owlmeans/module").CommonModule[];
+//# sourceMappingURL=modules.d.ts.map

package/build/modules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modules.d.ts","sourceRoot":"","sources":["../src/modules.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,OAAO,2CAAS,CAAA"}

package/build/modules.js

@@ -0,0 +1,5 @@
+import { modules as config, API_CONFIG } from '@owlmeans/api-config';
+import { elevate } from '@owlmeans/client-module';
+elevate(config, API_CONFIG);
+export const modules = config;
+//# sourceMappingURL=modules.js.map

package/build/modules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modules.js","sourceRoot":"","sources":["../src/modules.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACpE,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAA;AAEjD,OAAO,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;AAE3B,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAA"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@owlmeans/api-config-client",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 12 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@owlmeans/api-config": "^0.1.0",
+    "@owlmeans/client-context": "^0.1.0",
+    "@owlmeans/client-module": "^0.1.0",
+    "@owlmeans/context": "^0.1.0"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.7",
+    "typescript": "^5.6.3"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+
+export * from './middleware.js'
+export * from './modules.js'

package/src/middleware.ts

@@ -0,0 +1,32 @@
+import type { Middleware } from '@owlmeans/context'
+import { MiddlewareType, MiddlewareStage, assertContext } from '@owlmeans/context'
+import type { ClientModule } from '@owlmeans/client-module'
+import type { ApiConfig } from '@owlmeans/api-config'
+import { API_CONFIG } from '@owlmeans/api-config'
+import { mergeConfig } from '@owlmeans/config'
+import type { CommonConfig } from '@owlmeans/config'
+import type { ClientContext, ClientConfig } from '@owlmeans/client-context'
+
+export const apiConfigMiddleware: Middleware = {
+  type: MiddlewareType.Context,
+  stage: MiddlewareStage.Loading,
+  apply: async (ctx) => {
+    const context = assertContext<ClientConfig, ClientContext<ClientConfig>>(
+      ctx as any, 'api-config-middleware'
+    )
+    const module = context.module<ClientModule<ApiConfig>>(API_CONFIG)
+    if (context.cfg.primaryHost != null) {
+      module.route.route.host = context.cfg.primaryHost
+      if (context.cfg.primaryPort != null) {
+        module.route.route.port = context.cfg.primaryPort
+      }
+      try {
+        const [config] = await module.call()
+        const target: CommonConfig = context.cfg as unknown as CommonConfig
+        mergeConfig(target, config as CommonConfig)
+      } catch (e) { 
+        console.error(e)
+      }
+    }
+  }
+}

package/src/modules.ts

@@ -0,0 +1,7 @@
+
+import { modules as config, API_CONFIG } from '@owlmeans/api-config'
+import { elevate } from '@owlmeans/client-module'
+
+elevate(config, API_CONFIG)
+
+export const modules = config

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": [
+    "../tsconfig.default.json"
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/", /* Specify the root folder within your source files. */
+    "outDir": "./build/", /* Specify an output folder for all emitted files. */
+  },
+  "exclude": [
+    "./dist/**/*",
+    "./build/**/*",
+    "./*.ts"
+  ]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/index.ts","./src/middleware.ts","./src/modules.ts"],"version":"5.6.3"}