@semiont/api-client 0.4.21 → 0.4.22

package/README.md

@@ -6,109 +6,67 @@
 [![npm downloads](https://img.shields.io/npm/dm/@semiont/api-client.svg)](https://www.npmjs.com/package/@semiont/api-client)
 [![License](https://img.shields.io/npm/l/@semiont/api-client.svg)](https://github.com/The-AI-Alliance/semiont/blob/main/LICENSE)
 
-TypeScript SDK for [Semiont](https://github.com/The-AI-Alliance/semiont) — a knowledge management system for semantic annotations, AI-powered analysis, and collaborative document understanding.
+HTTP-specific transport adapters for the Semiont SDK. This is the wire-side
+implementation of the `ITransport` and `IContentTransport` contracts defined
+in [`@semiont/core`](../core/), consumed by [`@semiont/sdk`](../sdk/).
 
-The api-client is a transparent proxy to `@semiont/make-meaning`. The browser writes code as though it has direct access to the knowledge system. HTTP, auth, SSE, and caching are internal concerns.
+Most application code does **not** import this package directly. The sdk
+re-exports the HTTP adapters for convenience, so a typical consumer writes:
 
-## The 7 Verbs
+```ts
+import { SemiontClient, HttpTransport, HttpContentTransport } from '@semiont/sdk';
+import { baseUrl } from '@semiont/core';
 
-The API is organized by the domain's verbs — the same verbs that organize the EventBus protocol, the documentation, and the backend actors:
-
-```typescript
-import { SemiontApiClient } from '@semiont/api-client';
-
-const semiont = new SemiontApiClient({ baseUrl, eventBus, token$ });
-
-// Browse — reads from materialized views
-const resource = semiont.browse.resource(resourceId);       // Observable
-const annotations = semiont.browse.annotations(resourceId); // Observable
-const content = await semiont.browse.resourceContent(rid);   // Promise
-
-// Mark — annotation CRUD + AI assist
-await semiont.mark.annotation(resourceId, input);
-await semiont.mark.delete(resourceId, annotationId);
-semiont.mark.assist(resourceId, 'linking', options);         // Observable (progress)
-
-// Bind — reference linking
-await semiont.bind.body(resourceId, annotationId, operations);
-
-// Gather — LLM context assembly
-semiont.gather.annotation(annotationId, resourceId);         // Observable (progress → context)
-
-// Match — semantic search
-semiont.match.search(resourceId, referenceId, context);      // Observable (results)
-
-// Yield — resource creation + AI generation
-await semiont.yield.resource(data);
-semiont.yield.fromAnnotation(resourceId, annotationId, opts); // Observable (progress)
-
-// Beckon — attention coordination
-semiont.beckon.attention(annotationId, resourceId);           // void (ephemeral)
-
-// + Job, Auth, Admin namespaces
+const transport = new HttpTransport({ baseUrl: baseUrl('https://kb.example/') });
+const client = new SemiontClient(transport, new HttpContentTransport(transport));
 ```
 
-## Return Type Conventions
-
-- **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)
-- **Ephemeral signals** (beckon) → `void`
-
-## Auth is Internal
-
-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(),
-  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));
+Direct imports from `@semiont/api-client` are appropriate when constructing
+the transport stack by hand — e.g. CLI factories, MCP entrypoints, or worker
+pools that wire bespoke `tokenRefresher` / `BehaviorSubject` token sources.
+
+## Public surface
+
+```ts
+import {
+  HttpTransport,
+  HttpContentTransport,
+  type HttpTransportConfig,
+  type TokenRefresher,
+  APIError,
+  // SSE-actor machinery used by SDK adapters; not application code:
+  createActorVM,
+  type ActorVM,
+  type BusEvent,
+  type ActorVMOptions,
+  DEGRADED_THRESHOLD_MS,
+} from '@semiont/api-client';
 ```
 
-Omit `token$` entirely for unauthenticated usage (public endpoints only).
-The bus actor will not connect until a non-null token is available.
-
-## Installation
-
-```bash
-npm install @semiont/api-client
-```
+That's the entire surface. Everything else moved out:
 
-**Prerequisites**: Semiont backend running. See [Running the Backend](../../apps/backend/README.md#quick-start).
+- **`ITransport`, `IContentTransport`, `BRIDGED_CHANNELS`, `ConnectionState`,
+  response/progress types** live in [`@semiont/core`](../core/).
+- **`SemiontClient`, namespaces, `SemiontSession`, `SemiontBrowser`,
+  view-models, `bus-request`, `cache`** live in [`@semiont/sdk`](../sdk/).
 
-## Documentation
+## Behavioral contract
 
-- [Usage Guide](./docs/Usage.md) — authentication, resources, annotations, streaming
-- [API Reference](./docs/API-Reference.md) — complete method documentation
-- [Utilities Guide](./docs/Utilities.md) — text encoding, fuzzy anchoring, SVG utilities
-- [Logging Guide](./docs/LOGGING.md) — logger setup and troubleshooting
+The guarantees every `ITransport` implementation must honor — including
+`HttpTransport` — are documented in
+[`packages/core/docs/TRANSPORT-CONTRACT.md`](../core/docs/TRANSPORT-CONTRACT.md).
+HTTP-specific guarantees (the `/bus/emit` gateway, SSE reconnect, `Last-Event-ID`
+replay, etc.) live alongside the backend at
+[`apps/backend/docs/TRANSPORT.md`](../../apps/backend/docs/TRANSPORT.md).
 
-## Key Features
+## Writing a new transport
 
-- **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 the bus gateway (single SSE connection)
-- **Framework-agnostic** — pure TypeScript + RxJS, no React dependency
+If you need to add a non-HTTP transport (gRPC, WebSocket, IPC, …), implement
+`ITransport` + `IContentTransport` from `@semiont/core` and consume the
+contract from there. There's no inheritance from `HttpTransport`. For an
+in-process example, see `LocalTransport` in
+[`@semiont/make-meaning`](../make-meaning/).
 
 ## License
 
-Apache-2.0
+Apache-2.0 — see [LICENSE](./LICENSE).