@owlmeans/api-config-client 0.1.1 → 0.1.3

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 OwlMeans Common — Fullstack typescript framework
+Copyright (c) 2026 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

package/README.md

@@ -1,48 +1,22 @@
 # @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.
+Client-side middleware that fetches server config from `GET /assets/config.json` and merges it into the client context.
 
-## Purpose
+## Overview
 
-This package serves as the client-side component of the OwlMeans configuration system that:
+- `apiConfigMiddleware` — context middleware that calls the config endpoint on startup
+- Elevates `@owlmeans/api-config` modules into the client module system
+- Merges the server `ApiConfig` into the client's `CommonConfig` at initialization time
 
-- **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
+## Installation
 
-## 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)
+```bash
+bun add @owlmeans/api-config-client
 ```
 
-### Middleware
+## Usage
 
-#### `apiConfigMiddleware`
-
-Middleware that fetches configuration from the API config endpoint during context loading.
+Register the middleware in your client context setup:
 
 ```typescript
 import { apiConfigMiddleware } from '@owlmeans/api-config-client'
@@ -50,264 +24,15 @@ 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
+On initialization, the middleware calls the `API_CONFIG` module and merges the response into the context config.
 
-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
+## API
 
-## Security Considerations
+### `apiConfigMiddleware: Middleware`
 
-- **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
+A context initialization middleware. Calls `API_CONFIG` module, receives `ApiConfig`, and applies it to the context via `mergeConfig`.
 
 ## 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
+- [`@owlmeans/api-config`](../api-config) — `API_CONFIG` alias and `ApiConfig` type
+- [`@owlmeans/api-config-server`](../api-config-server) — server that serves the config endpoint

package/build/middleware.js

@@ -6,7 +6,7 @@ export const apiConfigMiddleware = {
     stage: MiddlewareStage.Loading,
     apply: async (ctx) => {
         const context = assertContext(ctx, 'api-config-middleware');
-        const module = context.module(API_CONFIG);
+        const module = context.entrypoint(API_CONFIG);
         if (context.cfg.primaryHost != null) {
             module.route.route.host = context.cfg.primaryHost;
             if (context.cfg.primaryPort != null) {

package/build/middleware.js.map

@@ -1 +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"}
+{"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,UAAU,CAA8B,UAAU,CAAC,CAAA;QAC1E,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

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

package/build/modules.d.ts.map

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

package/build/modules.js

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

package/build/modules.js.map

@@ -1 +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"}
+{"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,6BAA6B,CAAA;AAErD,OAAO,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;AAE3B,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAA"}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@owlmeans/api-config-client",
-  "version": "0.1.1",
+  "version": "0.1.3",
+  "license": "MIT",
   "type": "module",
   "scripts": {
     "build": "tsc -b",
@@ -20,14 +21,15 @@
     }
   },
   "dependencies": {
-    "@owlmeans/api-config": "^0.1.1",
-    "@owlmeans/client-context": "^0.1.1",
-    "@owlmeans/client-module": "^0.1.1",
-    "@owlmeans/context": "^0.1.1"
+    "@owlmeans/api-config": "^0.1.3",
+    "@owlmeans/client-context": "^0.1.3",
+    "@owlmeans/client-entrypoint": "^0.1.3",
+    "@owlmeans/context": "^0.1.3"
   },
   "devDependencies": {
+    "@owlmeans/dep-config": "workspace:*",
     "nodemon": "^3.1.11",
-    "typescript": "^5.8.3"
+    "typescript": "^6.0.2"
   },
   "publishConfig": {
     "access": "public"

package/src/middleware.ts

@@ -1,6 +1,6 @@
 import type { Middleware } from '@owlmeans/context'
 import { MiddlewareType, MiddlewareStage, assertContext } from '@owlmeans/context'
-import type { ClientModule } from '@owlmeans/client-module'
+import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
 import type { ApiConfig } from '@owlmeans/api-config'
 import { API_CONFIG } from '@owlmeans/api-config'
 import { mergeConfig } from '@owlmeans/config'
@@ -14,7 +14,7 @@ export const apiConfigMiddleware: Middleware = {
     const context = assertContext<ClientConfig, ClientContext<ClientConfig>>(
       ctx as any, 'api-config-middleware'
     )
-    const module = context.module<ClientModule<ApiConfig>>(API_CONFIG)
+    const module = context.entrypoint<ClientEntrypoint<ApiConfig>>(API_CONFIG)
     if (context.cfg.primaryHost != null) {
       module.route.route.host = context.cfg.primaryHost
       if (context.cfg.primaryPort != null) {

package/src/modules.ts

@@ -1,6 +1,6 @@
 
 import { modules as config, API_CONFIG } from '@owlmeans/api-config'
-import { elevate } from '@owlmeans/client-module'
+import { elevate } from '@owlmeans/client-entrypoint'
 
 elevate(config, API_CONFIG)
 

package/tsconfig.json

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