@semiont/http-transport 0.5.6

package/README.md

@@ -0,0 +1,74 @@
+# @semiont/http-transport
+
+[![Tests](https://github.com/The-AI-Alliance/semiont/actions/workflows/package-tests.yml/badge.svg)](https://github.com/The-AI-Alliance/semiont/actions/workflows/package-tests.yml?query=branch%3Amain+is%3Asuccess+job%3A%22Test+http-transport%22)
+[![codecov](https://codecov.io/gh/The-AI-Alliance/semiont/graph/badge.svg?flag=http-transport)](https://codecov.io/gh/The-AI-Alliance/semiont?flag=http-transport)
+[![npm version](https://img.shields.io/npm/v/@semiont/http-transport.svg)](https://www.npmjs.com/package/@semiont/http-transport)
+[![npm downloads](https://img.shields.io/npm/dm/@semiont/http-transport.svg)](https://www.npmjs.com/package/@semiont/http-transport)
+[![License](https://img.shields.io/npm/l/@semiont/http-transport.svg)](https://github.com/The-AI-Alliance/semiont/blob/main/LICENSE)
+
+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/).
+
+Most application code does **not** import this package directly. The sdk
+re-exports the HTTP adapters for convenience, so a typical consumer writes:
+
+```ts
+import { SemiontClient, HttpTransport, HttpContentTransport } from '@semiont/sdk';
+import { baseUrl } from '@semiont/core';
+
+const transport = new HttpTransport({ baseUrl: baseUrl('https://kb.example/') });
+// HttpTransport implements both ITransport and IBackendOperations; passing it
+// third enables the `auth` / `admin` namespaces.
+const client = new SemiontClient(transport, new HttpContentTransport(transport), transport);
+```
+
+Direct imports from `@semiont/http-transport` 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:
+  createActorStateUnit,
+  type ActorStateUnit,
+  type BusEvent,
+  type ActorStateUnitOptions,
+  DEGRADED_THRESHOLD_MS,
+} from '@semiont/http-transport';
+```
+
+That's the entire surface. Everything else moved out:
+
+- **`ITransport`, `IContentTransport`, `BRIDGED_CHANNELS`, `ConnectionState`,
+  response/progress types** live in [`@semiont/core`](../core/).
+- **`SemiontClient`, namespaces, `SemiontSession`, `SemiontBrowser`,
+  state units, `bus-request`, `cache`** live in [`@semiont/sdk`](../sdk/).
+
+## Behavioral contract
+
+The guarantees every `ITransport` implementation must honor — including
+`HttpTransport` — are documented in
+[`docs/protocol/TRANSPORT-CONTRACT.md`](../../docs/protocol/TRANSPORT-CONTRACT.md).
+HTTP-specific guarantees (the `/bus/emit` gateway, SSE reconnect, `Last-Event-ID`
+replay, etc.) live in
+[`docs/protocol/TRANSPORT-HTTP.md`](../../docs/protocol/TRANSPORT-HTTP.md).
+
+## Writing a new transport
+
+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 — see [LICENSE](../../LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,233 @@
+import { KyInstance } from 'ky';
+import { Observable, BehaviorSubject } from 'rxjs';
+import { ConnectionState, SemiontError, TransportErrorCode, ITransport, IBackendOperations, BaseUrl, AccessToken, Logger, EventMap, ResourceId, EventBus, Email, components, GoogleCredential, RefreshToken, UserResponse, ListUsersResponse, UserDID, UpdateUserRequest, UpdateUserResponse, BackendDownload, ProgressEvent, HealthCheckResponse, StatusResponse, IContentTransport, PutBinaryRequest, PutBinaryOptions } from '@semiont/core';
+
+/** Minimal StateUnit surface — anything with a `dispose()` method. */
+interface StateUnit {
+    dispose(): void;
+}
+
+interface BusEvent {
+    channel: string;
+    payload: Record<string, unknown>;
+    scope?: string;
+}
+interface ActorStateUnitOptions {
+    baseUrl: string;
+    token: string | (() => string);
+    channels: string[];
+    scope?: string;
+    reconnectMs?: number;
+}
+/** Time in the `reconnecting` state before transitioning to `degraded`. */
+declare const DEGRADED_THRESHOLD_MS = 3000;
+interface ActorStateUnit extends StateUnit {
+    on$<T = Record<string, unknown>>(channel: string): Observable<T>;
+    emit(channel: string, payload: Record<string, unknown>, emitScope?: string): Promise<void>;
+    state$: Observable<ConnectionState>;
+    addChannels(channels: string[], scope?: string): void;
+    removeChannels(channels: string[]): void;
+    start(): void;
+    stop(): void;
+}
+declare function createActorStateUnit(options: ActorStateUnitOptions): ActorStateUnit;
+
+/**
+ * HttpTransport — the HTTP/SSE implementation of ITransport.
+ *
+ * Phase 1 of TRANSPORT-ABSTRACTION. Owns everything that crosses the wire
+ * in remote mode: the bus actor (SSE + POST /bus/emit), auth/admin/exchange/
+ * system HTTP endpoints, and connection-state plumbing.
+ *
+ * Does NOT own the local coordination bus — that lives on `SemiontClient`.
+ * `bridgeInto(bus)` wires SSE-received events into the caller-supplied bus
+ * once at construction.
+ */
+
+type AuthResponse = components['schemas']['AuthResponse'];
+type TokenRefreshResponse = components['schemas']['TokenRefreshResponse'];
+type AdminUserStatsResponse = components['schemas']['AdminUserStatsResponse'];
+type OAuthConfigResponse = components['schemas']['OAuthConfigResponse'];
+declare class APIError extends SemiontError {
+    code: TransportErrorCode;
+    readonly status: number;
+    readonly statusText: string;
+    constructor(message: string, status: number, statusText: string, body?: unknown);
+}
+type TokenRefresher = () => Promise<string | null>;
+interface HttpTransportConfig {
+    baseUrl: BaseUrl;
+    /** Observable token source; headers read the current value. */
+    token$?: BehaviorSubject<AccessToken | null>;
+    timeout?: number;
+    retry?: number;
+    logger?: Logger;
+    /** Optional 401-recovery hook. See {@link TokenRefresher}. */
+    tokenRefresher?: TokenRefresher;
+}
+declare class HttpTransport implements ITransport, IBackendOperations {
+    readonly baseUrl: BaseUrl;
+    private readonly http;
+    private readonly token$;
+    private readonly logger?;
+    private readonly errorsSubject;
+    /**
+     * Stream of `APIError` instances surfaced from any HTTP request just
+     * before the transport throws to the caller. Satisfies the `ITransport`
+     * `errors$` contract — see `@semiont/core/transport.ts`.
+     */
+    readonly errors$: Observable<SemiontError>;
+    private _actor;
+    private _actorStarted;
+    private disposed;
+    private activeResource;
+    /** Buses we've been asked to bridge wire events into. */
+    private readonly bridges;
+    constructor(config: HttpTransportConfig);
+    get actor(): ActorStateUnit;
+    emit<K extends keyof EventMap>(channel: K, payload: EventMap[K], resourceScope?: ResourceId): Promise<void>;
+    on<K extends keyof EventMap>(channel: K, handler: (payload: EventMap[K]) => void): () => void;
+    stream<K extends keyof EventMap>(channel: K): Observable<EventMap[K]>;
+    /**
+     * Wire this transport's SSE fan-in into the given bus. Every channel
+     * in `BRIDGED_CHANNELS` (and subsequently per-resource scoped channels
+     * opened by `subscribeToResource`) is published on the bus. Safe to
+     * call multiple times — each bus is added to the fan-out list.
+     */
+    bridgeInto(bus: EventBus): void;
+    subscribeToResource(resourceId: ResourceId): () => void;
+    private makeUnsubscriber;
+    get state$(): Observable<ConnectionState>;
+    dispose(): void;
+    /**
+     * Route a transport-level error onto `errors$`. Used by sibling adapters
+     * (e.g. `HttpContentTransport`'s XHR upload path) that don't go through
+     * the `ky` `beforeError` hook and need to surface failures on the same
+     * stream the rest of the transport publishes to.
+     */
+    pushError(error: SemiontError): void;
+    private authHeaders;
+    authenticatePassword(email: Email, password: string): Promise<AuthResponse>;
+    authenticateGoogle(credential: GoogleCredential): Promise<AuthResponse>;
+    refreshAccessToken(token: RefreshToken): Promise<TokenRefreshResponse>;
+    logout(): Promise<void>;
+    acceptTerms(): Promise<void>;
+    getCurrentUser(): Promise<UserResponse>;
+    generateMcpToken(): Promise<{
+        token: string;
+    }>;
+    getMediaToken(resourceId: ResourceId): Promise<{
+        token: string;
+    }>;
+    listUsers(): Promise<ListUsersResponse>;
+    getUserStats(): Promise<AdminUserStatsResponse>;
+    updateUser(id: UserDID, data: UpdateUserRequest): Promise<UpdateUserResponse>;
+    getOAuthConfig(): Promise<OAuthConfigResponse>;
+    backupKnowledgeBase(): Promise<BackendDownload>;
+    restoreKnowledgeBase(file: File): Observable<ProgressEvent>;
+    exportKnowledgeBase(params?: {
+        includeArchived?: boolean;
+    }): Promise<BackendDownload>;
+    importKnowledgeBase(file: File): Observable<ProgressEvent>;
+    /**
+     * POST a file to a server-sent-events endpoint and surface each `data:`
+     * frame as an Observable emission. Completes when the stream closes;
+     * errors if the request itself fails or the SSE stream is aborted.
+     * The returned Observable is cold — the POST happens on subscribe and
+     * is aborted via `AbortController` on unsubscribe.
+     */
+    private sseProgressStream;
+    healthCheck(): Promise<HealthCheckResponse>;
+    getStatus(): Promise<StatusResponse>;
+    /**
+     * Temporary escape hatch for the ongoing transport migration: namespaces
+     * that still need to issue ad-hoc HTTP calls (e.g. legacy browse/mark
+     * HTTP fallbacks) can borrow the configured `ky` instance here. Will be
+     * deleted once all namespaces route through bus channels or through
+     * typed methods on this transport.
+     */
+    get rawHttp(): KyInstance;
+    /**
+     * Current access token (synchronously read from the BehaviorSubject).
+     * Used by content-transport and legacy namespace HTTP fallbacks that
+     * need to pass `auth: token` through some code paths.
+     */
+    getToken(): AccessToken | undefined;
+}
+
+/**
+ * HttpContentTransport — binary I/O over HTTP.
+ *
+ * Phase 1 of TRANSPORT-ABSTRACTION. Narrow by design because binary has
+ * different backpressure and streaming characteristics than typed command
+ * payloads. Uses the HttpTransport's underlying ky instance + token, so
+ * retries, logging, and auth behave identically to the rest of the wire.
+ *
+ * Two `putBinary` paths live side by side, selected by runtime
+ * environment + caller intent:
+ *   - **ky path (default + Node)** — the original `ky.post(...)` path.
+ *     Keeps retry-with-refresh, beforeError → APIError, observability
+ *     spans intact. Hits when no `onProgress`/`signal` is passed, OR
+ *     when `XMLHttpRequest` isn't available in the runtime (Node
+ *     workers, the CLI). On Node-side `signal`-aborts: the in-flight
+ *     `fetch` continues in the background and the `cancelled` flag in
+ *     `yield.resource` suppresses the resolve/reject callbacks.
+ *   - **XHR path (browsers with `onProgress` or `signal`)** — hand-rolled
+ *     because `ky` wraps `fetch` which can't observe upload byte-
+ *     progress today (`Request({ duplex: 'half' })` is the long-term
+ *     direction; not yet widely available across the webviews this
+ *     codepath needs to run in). Threads auth + traceparent headers,
+ *     emits `onProgress` from `xhr.upload.onprogress`, supports
+ *     cancellation via the `signal` option (calling `xhr.abort()`),
+ *     and routes failures onto the same `transport.errors$` stream
+ *     the ky path uses.
+ *
+ * The runtime check on `XMLHttpRequest` is the load-bearing seam: a
+ * Node worker calling `client.yield.resource(...)` (which always passes
+ * a `signal` for unsubscribe-aborts) must NOT take the XHR path —
+ * `XMLHttpRequest` is undefined and the upload throws synchronously.
+ * Browsers always have it; Node does not.
+ *
+ * v1 limitation: the XHR path does NOT auto-refresh on 401. Mitigation:
+ * the session's proactive refresh fires before token expiry, so an
+ * upload that *starts* with a fresh token usually completes. An upload
+ * spanning the narrow window between expiry and proactive-refresh would
+ * fail; the existing `errors$` → modal path surfaces it as session-
+ * expired. If retry-with-refresh on the upload path becomes a real
+ * complaint, wire a manual retry loop here that reads `token$` afresh.
+ */
+
+type GetResourceResponse = components['schemas']['GetResourceResponse'];
+declare class HttpContentTransport implements IContentTransport {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    putBinary(request: PutBinaryRequest, options?: PutBinaryOptions): Promise<{
+        resourceId: ResourceId;
+    }>;
+    getBinary(resourceId: ResourceId, options?: {
+        auth?: AccessToken;
+    }): Promise<{
+        data: ArrayBuffer;
+        contentType: string;
+    }>;
+    getBinaryStream(resourceId: ResourceId, options?: {
+        auth?: AccessToken;
+    }): Promise<{
+        stream: ReadableStream<Uint8Array>;
+        contentType: string;
+    }>;
+    /**
+     * Dereference the resource's JSON-LD graph over HTTP — the LD face an
+     * external linked-data client sees. Deliberately HTTP, not the bus
+     * (SIMPLER-JSON-LD.md §5).
+     */
+    getResourceGraph(resourceId: ResourceId, options?: {
+        auth?: AccessToken;
+    }): Promise<GetResourceResponse>;
+    dispose(): void;
+    /** Auth header + W3C trace propagation for the active span. */
+    private requestHeaders;
+}
+
+export { APIError, DEGRADED_THRESHOLD_MS, HttpContentTransport, HttpTransport, createActorStateUnit };
+export type { ActorStateUnit, ActorStateUnitOptions, BusEvent, HttpTransportConfig, TokenRefresher };