@owlmeans/client-config 0.1.18-rc.2 → 0.1.18-rc.20

package/README.md

@@ -11,7 +11,7 @@ Client-side configuration helper for registering web service endpoints.
 ## Installation
 
 ```bash
-bun add @owlmeans/client-config
+bun add @owlmeans/client-config@^0.1.18-rc.11
 ```
 
 ## Usage
@@ -48,7 +48,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.20
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/client-config",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.517Z",
+  "version": "0.1.18-rc.20",
+  "generatedAt": "2026-09-12T14:21:25.470Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/client-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: client-config
-description: How to use @owlmeans/client-config — client-side config types and helpers (extends core Config). Auto-invoked when importing client config primitives.
+description: How to use @owlmeans/client-config — the BasicClientConfig shape every client config extends (webService, primaryHost, primaryPort, shortAlias) and addWebService() for naming which API client carries a call. Auto-invoked when typing a client config, wiring an app to its API service, or resolving which web service an entrypoint calls through.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,22 +8,73 @@ user-invocable: false
 # @owlmeans/client-config
 
 **Layer:** Client
-**Install:** `"@owlmeans/client-config": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/client-config": "^0.1.18-rc.20"` in `dependencies`
+
+The bottom of the client config stack: the few fields a client adds to `CommonConfig`, and the
+helper that fills the one field a client cannot work without. Nothing here knows about React or the
+browser.
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `ClientConfig` types | Client-side config interface (extends core) |
-| Constants | Default config aliases |
-| Helpers | Resolve client config |
+| `BasicClientConfig` | `CommonConfig` + `webService`, `primaryHost`, `primaryPort`, `shortAlias` |
+| `addWebService(service, alias?, cfg?)` | Point calls at an API client — globally, or per target service |
+| `DEFAULT_KEY` (`default`) | The key `webService` uses for the fallback API client |
+
+`ClientConfig` — the config a context is actually built from — is **not** here: it lives in
+`@owlmeans/client-context`, which adds `services` and `i18n` on top of `BasicClientConfig`.
+
+## The fields
+
+| Field | Meaning |
+|---|---|
+| `webService` | Which API client carries an outgoing call. A string names one for everything; a record maps the *target service* alias to an API client alias, with `DEFAULT_KEY` as the fallback |
+| `primaryHost` / `primaryPort` | The host the app is being served from. `@owlmeans/web-client` fills these from `window.location` while building the context — do not set them by hand |
+| `shortAlias` | An abbreviation of `service`, so a flow or a redirect can name this app in a query parameter without spelling the full alias |
 
-## Usage
+## Naming the API client
 
 ```typescript
-import type { ClientConfig } from '@owlmeans/client-config'
+import { addWebService } from '@owlmeans/client-config'
+
+addWebService(API_CLIENT, cfg)                  // one client for every call
+addWebService(BILLING_CLIENT, BILLING, cfg)     // ...and this one for calls to the billing service
 ```
 
+The **three-argument** form never drops what is already there, and what it writes depends on the
+state it finds:
+
+| `webService` before | After `addWebService(S, ALIAS, cfg)` |
+|---|---|
+| unset | `{ default: S, ALIAS: S }` — the first per-service call **also** becomes the global default |
+| the string `X` | `{ default: X, ALIAS: S }` — the general answer is demoted, not lost |
+| a record | that record with `ALIAS: S` added |
+
+So a first call meant as service-specific is not specific: name the general client first, or accept
+that this one answers for everything else too.
+
+The **two-argument** form sets the general answer: an unset or string `webService` becomes the plain
+string, and on a record it writes only `DEFAULT_KEY`. Called with no `cfg` at all it builds and returns a fresh partial config
+to spread. `@owlmeans/web-panel`, `@owlmeans/mui-panel` and `@owlmeans/server-app` re-export it, so
+an app configures through the package it already imports.
+
+A client entrypoint resolves its carrier from this field on every call, and refuses before anything
+else when the field is absent: `SyntaxError('No webService provided')` is "this config never named
+an API client", and it is thrown even for a call a registered transport would have carried. When
+the field is a record with neither the target service's alias nor `DEFAULT_KEY`, the failure is
+``SyntaxError("Can't cast web service alias for <alias> entrypoint")`` instead.
+
+`webService` has no `apiConfigPlugin()` allowlist registration, so
+`@owlmeans/api-config-server` never includes it in the `ApiConfig` it advertises.
+`@owlmeans/api-config-client` merges only what came back, so every client names its API client
+locally.
+
 ## Depends On
 
-- `@owlmeans/config`, `@owlmeans/auth`
+- `@owlmeans/config` — `CommonConfig`, which `BasicClientConfig` extends
+
+## Related
+
+- [[client-context]] — `ClientConfig` and the context factory built on this shape
+- [[client-entrypoint]] — the caller that reads `webService` to pick a carrier

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/client-config",
-  "version": "0.1.18-rc.2",
+  "version": "0.1.18-rc.20",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,7 +21,7 @@
     }
   },
   "dependencies": {
-    "@owlmeans/config": "^0.1.18-rc.2"
+    "@owlmeans/config": "^0.1.18-rc.20"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",