@semiont/api-client 0.4.20 → 0.4.21

package/README.md

@@ -17,7 +17,7 @@ The API is organized by the domain's verbs — the same verbs that organize the
 ```typescript
 import { SemiontApiClient } from '@semiont/api-client';
 
-const semiont = new SemiontApiClient({ baseUrl, eventBus, getToken });
+const semiont = new SemiontApiClient({ baseUrl, eventBus, token$ });
 
 // Browse — reads from materialized views
 const resource = semiont.browse.resource(resourceId);       // Observable
@@ -50,7 +50,7 @@ semiont.beckon.attention(annotationId, resourceId);           // void (ephemeral
 
 ## Return Type Conventions
 
-- **Browse live queries** → `Observable` (events-stream driven, cached in BehaviorSubject)
+- **Browse live queries** → `Observable` (bus-gateway driven, cached in BehaviorSubject)
 - **Browse one-shot reads** → `Promise` (fetch once, no cache)
 - **Commands** (mark, bind, yield.resource) → `Promise` (fire-and-forget)
 - **Long-running ops** (gather, match, yield.fromAnnotation, mark.assist) → `Observable` (progress + result)
@@ -58,22 +58,34 @@ semiont.beckon.attention(annotationId, resourceId);           // void (ephemeral
 
 ## Auth is Internal
 
-The client takes a `getToken` function at construction. No per-call auth:
+The client takes an observable `token$` at construction. All namespace
+calls and the bus SSE connection read the current value. Update by
+calling `.next(newToken)` on the BehaviorSubject — the client auto-starts
+the bus actor the first time the token transitions from null to a real
+value, and the actor reconnects with the new token after refresh.
 
 ```typescript
+import { BehaviorSubject } from 'rxjs';
+
+const token$ = new BehaviorSubject<AccessToken | null>(accessToken(token));
+
 const semiont = new SemiontApiClient({
   baseUrl: baseUrl('http://localhost:4000'),
   eventBus: new EventBus(),
-  getToken: () => accessToken(token),
+  token$,
 });
 
 // No auth on individual calls
 const annotations = semiont.browse.annotations(resourceId);
 await semiont.mark.annotation(resourceId, input);
 await semiont.bind.body(resourceId, annotationId, operations);
+
+// Token rotation — e.g. after refresh
+token$.next(accessToken(newToken));
 ```
 
-Update the token getter at any time via `semiont.setTokenGetter(getter)`.
+Omit `token$` entirely for unauthenticated usage (public endpoints only).
+The bus actor will not connect until a non-null token is available.
 
 ## Installation
 
@@ -94,7 +106,7 @@ npm install @semiont/api-client
 
 - **Verb-oriented** — 7 domain namespaces mirror `@semiont/make-meaning`'s actor model
 - **Type-safe** — OpenAPI types from `@semiont/core`, branded identifiers
-- **Observable reads** — live-updating views via EventBus + events-stream SSE
+- **Observable reads** — live-updating views via the bus gateway (single SSE connection)
 - **Framework-agnostic** — pure TypeScript + RxJS, no React dependency
 
 ## License