@semiont/http-transport 0.5.6

package/dist/index.js

@@ -0,0 +1,948 @@
+import ky, { HTTPError } from 'ky';
+import { Subject, BehaviorSubject, Observable } from 'rxjs';
+import { RESOURCE_BROADCAST_TYPES, PERSISTED_EVENT_TYPES, SemiontError, BRIDGED_CHANNELS, busLog } from '@semiont/core';
+import { getActiveTraceparent, recordBusEmit, withSpan, SpanKind, extractTraceparent, withTraceparent } from '@semiont/observability';
+import { share, filter, map } from 'rxjs/operators';
+
+// src/transport/http-transport.ts
+var DEGRADED_THRESHOLD_MS = 3e3;
+var ALLOWED_TRANSITIONS = {
+  initial: ["connecting", "closed"],
+  connecting: ["open", "reconnecting", "closed"],
+  open: ["reconnecting", "closed"],
+  reconnecting: ["connecting", "degraded", "closed"],
+  // `degraded → reconnecting` is a legitimate recovery edge: a channel-set
+  // change (`addChannels`/`removeChannels`) schedules a reconnect that can
+  // fire while the connection is degraded. Omitting it made `reconnect()`
+  // throw a fatal, uncaught exception from the reconnect timer (#844).
+  degraded: ["connecting", "reconnecting", "closed"],
+  closed: []
+};
+function createActorStateUnit(options) {
+  const { baseUrl, token: tokenOrGetter, channels: initialChannels, scope: initialScope, reconnectMs = 5e3 } = options;
+  const getToken = typeof tokenOrGetter === "function" ? tokenOrGetter : () => tokenOrGetter;
+  const globalChannels = new Set(initialChannels);
+  const scopedChannels = /* @__PURE__ */ new Set();
+  let activeScope = initialScope;
+  const events$ = new Subject();
+  const state$ = new BehaviorSubject("initial");
+  let currentState = "initial";
+  let degradedTimer = null;
+  const transition = (next) => {
+    if (currentState === next) return;
+    const allowed = ALLOWED_TRANSITIONS[currentState];
+    if (!allowed.includes(next)) {
+      console.warn(`[actor] ignoring invalid connection state transition: ${currentState} \u2192 ${next}`);
+      return;
+    }
+    const prev = currentState;
+    currentState = next;
+    if (next === "reconnecting" && prev !== "reconnecting") {
+      if (degradedTimer) clearTimeout(degradedTimer);
+      degradedTimer = setTimeout(() => {
+        if (currentState === "reconnecting") transition("degraded");
+      }, DEGRADED_THRESHOLD_MS);
+    }
+    if (prev === "reconnecting" && next !== "reconnecting") {
+      if (degradedTimer) {
+        clearTimeout(degradedTimer);
+        degradedTimer = null;
+      }
+    }
+    state$.next(next);
+  };
+  let running = false;
+  const inflightControllers = /* @__PURE__ */ new Set();
+  let reconnectTimer = null;
+  let lastEventId = null;
+  const seenEventIds = /* @__PURE__ */ new Set();
+  const SEEN_EVENT_IDS_MAX = 512;
+  const rememberEventId = (id) => {
+    seenEventIds.add(id);
+    if (seenEventIds.size > SEEN_EVENT_IDS_MAX) {
+      const oldest = seenEventIds.values().next().value;
+      if (oldest !== void 0) seenEventIds.delete(oldest);
+    }
+  };
+  const shared$ = events$.pipe(share());
+  const disconnect = () => {
+    for (const c of inflightControllers) {
+      try {
+        c.abort();
+      } catch {
+      }
+    }
+    inflightControllers.clear();
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+  };
+  const connect = async (keepPrevious = false) => {
+    transition("connecting");
+    const previous = [...inflightControllers];
+    if (!keepPrevious) {
+      for (const c of previous) {
+        try {
+          c.abort();
+        } catch {
+        }
+      }
+      inflightControllers.clear();
+    }
+    const params = new URLSearchParams();
+    for (const ch of globalChannels) {
+      params.append("channel", ch);
+    }
+    if (activeScope && scopedChannels.size > 0) {
+      params.append("scope", activeScope);
+      for (const ch of scopedChannels) {
+        params.append("scoped", ch);
+      }
+    }
+    const url = `${baseUrl}/bus/subscribe?${params.toString()}`;
+    const controller = new AbortController();
+    inflightControllers.add(controller);
+    try {
+      const headers = { Authorization: `Bearer ${getToken()}` };
+      if (lastEventId) headers["Last-Event-ID"] = lastEventId;
+      const response = await fetch(url, { headers, signal: controller.signal });
+      if (!response.ok || !response.body) {
+        throw new Error(`SSE connect failed: ${response.status}`);
+      }
+      if (!running) return;
+      if (keepPrevious) {
+        for (const c of previous) {
+          try {
+            c.abort();
+          } catch {
+          }
+          inflightControllers.delete(c);
+        }
+      }
+      transition("open");
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      let currentEvent = "";
+      let currentData = "";
+      let currentId;
+      while (running && inflightControllers.has(controller)) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          if (line.startsWith("event: ")) {
+            currentEvent = line.slice(7);
+          } else if (line.startsWith("data: ")) {
+            currentData = line.slice(6);
+          } else if (line.startsWith("id: ")) {
+            currentId = line.slice(4);
+          } else if (line === "") {
+            const isDuplicate = currentId !== void 0 && seenEventIds.has(currentId);
+            if (currentEvent === "bus-event" && currentData && !isDuplicate) {
+              if (currentId !== void 0) {
+                lastEventId = currentId;
+                rememberEventId(currentId);
+              }
+              const parsed = JSON.parse(currentData);
+              busLog("RECV", parsed.channel, parsed.payload, parsed.scope);
+              const carrier = extractTraceparent(
+                parsed.payload
+              );
+              await withTraceparent(
+                carrier,
+                () => withSpan(
+                  `bus.recv:${parsed.channel}`,
+                  () => {
+                    events$.next(parsed);
+                  },
+                  {
+                    kind: SpanKind.CONSUMER,
+                    attrs: {
+                      "bus.channel": parsed.channel,
+                      ...parsed.scope ? { "bus.scope": parsed.scope } : {}
+                    }
+                  }
+                )
+              );
+            }
+            currentEvent = "";
+            currentData = "";
+            currentId = void 0;
+          }
+        }
+      }
+    } catch (err) {
+      if (err.name === "AbortError") return;
+    } finally {
+      inflightControllers.delete(controller);
+    }
+    if (running) {
+      transition("reconnecting");
+      reconnectTimer = setTimeout(() => {
+        if (running) connect();
+      }, reconnectMs);
+    }
+  };
+  const reconnect = () => {
+    if (!running) return;
+    if (currentState === "open" || currentState === "connecting" || currentState === "degraded") {
+      transition("reconnecting");
+    }
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+    connect(true);
+  };
+  let reconnectTimer2 = null;
+  const RECONNECT_DEBOUNCE_MS = 100;
+  const scheduleReconnect = () => {
+    if (reconnectTimer2) clearTimeout(reconnectTimer2);
+    reconnectTimer2 = setTimeout(() => {
+      reconnectTimer2 = null;
+      reconnect();
+    }, RECONNECT_DEBOUNCE_MS);
+  };
+  return {
+    on$(channel) {
+      return shared$.pipe(
+        filter((e) => e.channel === channel),
+        map((e) => e.payload)
+      );
+    },
+    emit: async (channel, payload, emitScope) => {
+      const body = { channel, payload };
+      if (emitScope) body.scope = emitScope;
+      const headers = {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${getToken()}`
+      };
+      const trace = getActiveTraceparent();
+      if (trace) {
+        headers["traceparent"] = trace.traceparent;
+        if (trace.tracestate) headers["tracestate"] = trace.tracestate;
+      }
+      await fetch(`${baseUrl}/bus/emit`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body)
+      });
+    },
+    state$: state$.asObservable(),
+    addChannels: (channels, scope) => {
+      let changed = false;
+      if (scope !== void 0) {
+        for (const ch of channels) {
+          if (!scopedChannels.has(ch)) {
+            scopedChannels.add(ch);
+            changed = true;
+          }
+        }
+        if (scope !== activeScope) {
+          activeScope = scope;
+          changed = true;
+        }
+      } else {
+        for (const ch of channels) {
+          if (!globalChannels.has(ch)) {
+            globalChannels.add(ch);
+            changed = true;
+          }
+        }
+      }
+      if (changed) scheduleReconnect();
+    },
+    removeChannels: (channels) => {
+      let changed = false;
+      for (const ch of channels) {
+        if (scopedChannels.delete(ch)) changed = true;
+        if (globalChannels.delete(ch)) changed = true;
+      }
+      if (scopedChannels.size === 0) activeScope = void 0;
+      if (changed) scheduleReconnect();
+    },
+    start: () => {
+      if (running) return;
+      running = true;
+      connect();
+    },
+    stop: () => {
+      running = false;
+      if (currentState !== "closed") transition("closed");
+      if (reconnectTimer2) {
+        clearTimeout(reconnectTimer2);
+        reconnectTimer2 = null;
+      }
+      if (degradedTimer) {
+        clearTimeout(degradedTimer);
+        degradedTimer = null;
+      }
+      disconnect();
+    },
+    dispose: () => {
+      running = false;
+      if (currentState !== "closed") transition("closed");
+      if (reconnectTimer2) {
+        clearTimeout(reconnectTimer2);
+        reconnectTimer2 = null;
+      }
+      if (degradedTimer) {
+        clearTimeout(degradedTimer);
+        degradedTimer = null;
+      }
+      disconnect();
+      events$.complete();
+      state$.complete();
+    }
+  };
+}
+var RESOURCE_SCOPED_CHANNELS = [
+  ...PERSISTED_EVENT_TYPES.filter((t) => t !== "frame:entity-type-added"),
+  ...RESOURCE_BROADCAST_TYPES
+];
+function responseToDownload(response) {
+  const contentType = response.headers.get("Content-Type") ?? "application/octet-stream";
+  const contentDisposition = response.headers.get("Content-Disposition");
+  const filename = contentDisposition?.match(/filename="(.+?)"/)?.[1];
+  return {
+    stream: response.body,
+    contentType,
+    ...filename ? { filename } : {}
+  };
+}
+function classifyApiCode(status) {
+  if (status === 400) return "bad-request";
+  if (status === 401) return "unauthorized";
+  if (status === 403) return "forbidden";
+  if (status === 404) return "not-found";
+  if (status === 409) return "conflict";
+  if (status >= 500) return "unavailable";
+  return "error";
+}
+var APIError = class extends SemiontError {
+  status;
+  statusText;
+  constructor(message, status, statusText, body) {
+    super(message, classifyApiCode(status), { status, statusText, body });
+    this.name = "APIError";
+    this.status = status;
+    this.statusText = statusText;
+  }
+};
+var HttpTransport = class {
+  baseUrl;
+  http;
+  token$;
+  logger;
+  errorsSubject = new Subject();
+  /**
+   * 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`.
+   */
+  errors$ = this.errorsSubject.asObservable();
+  _actor = null;
+  _actorStarted = false;
+  disposed = false;
+  activeResource = null;
+  /** Buses we've been asked to bridge wire events into. */
+  bridges = [];
+  constructor(config) {
+    const { baseUrl, timeout = 3e4, retry = 2, logger, tokenRefresher } = config;
+    this.baseUrl = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+    this.token$ = config.token$ ?? new BehaviorSubject(null);
+    this.logger = logger;
+    const retryConfig = tokenRefresher ? {
+      limit: 1,
+      methods: ["get", "post", "put", "patch", "delete", "head", "options"],
+      statusCodes: [401, 408, 413, 429, 500, 502, 503, 504]
+    } : retry;
+    this.http = ky.create({
+      timeout,
+      retry: retryConfig,
+      credentials: "include",
+      hooks: {
+        beforeRequest: [
+          ({ request }) => {
+            if (this.logger) {
+              this.logger.debug("HTTP Request", {
+                type: "http_request",
+                url: request.url,
+                method: request.method,
+                timestamp: Date.now(),
+                hasAuth: request.headers.has("Authorization")
+              });
+            }
+          }
+        ],
+        beforeRetry: tokenRefresher ? [
+          async ({ request, error }) => {
+            if (!(error instanceof HTTPError) || error.response.status !== 401) {
+              return void 0;
+            }
+            try {
+              const newToken = await tokenRefresher();
+              if (!newToken) return ky.stop;
+              request.headers.set("Authorization", `Bearer ${newToken}`);
+              return void 0;
+            } catch {
+              return ky.stop;
+            }
+          }
+        ] : [],
+        afterResponse: [
+          ({ request, response }) => {
+            if (this.logger) {
+              this.logger.debug("HTTP Response", {
+                type: "http_response",
+                url: request.url,
+                method: request.method,
+                status: response.status,
+                statusText: response.statusText
+              });
+            }
+            return response;
+          }
+        ],
+        beforeError: [
+          async ({ request, error }) => {
+            const response = error instanceof HTTPError ? error.response : void 0;
+            if (response) {
+              const body = await response.json().catch(() => ({}));
+              if (this.logger) {
+                this.logger.error("HTTP Request Failed", {
+                  type: "http_error",
+                  url: request.url,
+                  method: request.method,
+                  status: response.status,
+                  statusText: response.statusText,
+                  error: body.message || `HTTP ${response.status}: ${response.statusText}`
+                });
+              }
+              const apiError = new APIError(
+                body.message || `HTTP ${response.status}: ${response.statusText}`,
+                response.status,
+                response.statusText,
+                body
+              );
+              this.errorsSubject.next(apiError);
+              throw apiError;
+            }
+            return error;
+          }
+        ]
+      }
+    });
+    this.token$.subscribe((token) => {
+      if (token && !this._actorStarted && !this.disposed) {
+        this._actorStarted = true;
+        this.actor.start();
+      }
+    });
+  }
+  // ── Lazy actor construction + per-channel fan-in to bridges ───────────
+  //
+  // `actor` is exposed so the legacy `SemiontClient` can keep `.actor`
+  // pointing at the same ActorStateUnit during the transport-abstraction
+  // migration. Once SemiontClient is removed, this should be made
+  // private again — external callers should use emit/on/stream/state$.
+  get actor() {
+    if (!this._actor) {
+      this._actor = createActorStateUnit({
+        baseUrl: this.baseUrl,
+        token: () => this.token$.getValue() ?? "",
+        channels: [...BRIDGED_CHANNELS]
+      });
+      for (const channel of BRIDGED_CHANNELS) {
+        this._actor.on$(channel).subscribe((payload) => {
+          for (const bus of this.bridges) {
+            bus.get(channel).next(payload);
+          }
+        });
+      }
+    }
+    return this._actor;
+  }
+  // ── ITransport — bus primitives ───────────────────────────────────────
+  async emit(channel, payload, resourceScope) {
+    busLog("EMIT", channel, payload, resourceScope);
+    recordBusEmit(channel, resourceScope);
+    await withSpan(
+      `bus.emit:${channel}`,
+      async () => {
+        if (resourceScope !== void 0) {
+          await this.actor.emit(
+            channel,
+            payload,
+            resourceScope
+          );
+        } else {
+          await this.actor.emit(
+            channel,
+            payload
+          );
+        }
+      },
+      {
+        kind: SpanKind.PRODUCER,
+        attrs: {
+          "bus.channel": channel,
+          ...resourceScope ? { "bus.scope": resourceScope } : {}
+        }
+      }
+    );
+  }
+  on(channel, handler) {
+    const sub = this.actor.on$(channel).subscribe(handler);
+    return () => sub.unsubscribe();
+  }
+  stream(channel) {
+    return this.actor.on$(channel);
+  }
+  /**
+   * 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) {
+    this.bridges.push(bus);
+  }
+  subscribeToResource(resourceId) {
+    if (this.activeResource) {
+      if (this.activeResource.resourceId !== resourceId) {
+        throw new Error(
+          `HttpTransport already subscribed to resource ${this.activeResource.resourceId}; call the unsubscribe returned from the previous subscribeToResource before subscribing to ${resourceId}.`
+        );
+      }
+      this.activeResource.refCount++;
+      return this.makeUnsubscriber();
+    }
+    this.actor.addChannels([...RESOURCE_SCOPED_CHANNELS], resourceId);
+    const bridgeSubs = [];
+    for (const channel of RESOURCE_SCOPED_CHANNELS) {
+      bridgeSubs.push(
+        this.actor.on$(channel).subscribe((payload) => {
+          for (const bus of this.bridges) {
+            bus.get(channel).next(payload);
+          }
+        })
+      );
+    }
+    this.activeResource = { resourceId, refCount: 1, bridgeSubs };
+    return this.makeUnsubscriber();
+  }
+  makeUnsubscriber() {
+    let called = false;
+    return () => {
+      if (called) return;
+      called = true;
+      if (!this.activeResource) return;
+      this.activeResource.refCount--;
+      if (this.activeResource.refCount > 0) return;
+      for (const sub of this.activeResource.bridgeSubs) sub.unsubscribe();
+      this.actor.removeChannels([...RESOURCE_SCOPED_CHANNELS]);
+      this.activeResource = null;
+    };
+  }
+  get state$() {
+    return this.actor.state$;
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    if (this.activeResource) {
+      for (const sub of this.activeResource.bridgeSubs) sub.unsubscribe();
+      this.activeResource = null;
+    }
+    if (this._actor) {
+      this._actor.dispose();
+      this._actor = null;
+    }
+    this.errorsSubject.complete();
+  }
+  /**
+   * 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) {
+    if (this.disposed) return;
+    this.errorsSubject.next(error);
+  }
+  // ── Auth ──────────────────────────────────────────────────────────────
+  authHeaders() {
+    const token = this.token$.getValue() ?? void 0;
+    return token ? { Authorization: `Bearer ${token}` } : {};
+  }
+  async authenticatePassword(email, password) {
+    return this.http.post(`${this.baseUrl}/api/tokens/password`, {
+      json: { email, password },
+      headers: this.authHeaders()
+    }).json();
+  }
+  async authenticateGoogle(credential) {
+    return this.http.post(`${this.baseUrl}/api/tokens/google`, {
+      json: { credential },
+      headers: this.authHeaders()
+    }).json();
+  }
+  async refreshAccessToken(token) {
+    return this.http.post(`${this.baseUrl}/api/tokens/refresh`, {
+      json: { refreshToken: token },
+      headers: this.authHeaders()
+    }).json();
+  }
+  async logout() {
+    await this.http.post(`${this.baseUrl}/api/users/logout`, {
+      headers: this.authHeaders()
+    }).json();
+  }
+  async acceptTerms() {
+    await this.http.post(`${this.baseUrl}/api/users/accept-terms`, {
+      headers: this.authHeaders()
+    }).json();
+  }
+  async getCurrentUser() {
+    return this.http.get(`${this.baseUrl}/api/users/me`, {
+      headers: this.authHeaders()
+    }).json();
+  }
+  async generateMcpToken() {
+    return this.http.post(`${this.baseUrl}/api/tokens/mcp-generate`, {
+      headers: this.authHeaders()
+    }).json();
+  }
+  async getMediaToken(resourceId) {
+    return this.http.post(`${this.baseUrl}/api/tokens/media`, {
+      json: { resourceId },
+      headers: this.authHeaders()
+    }).json();
+  }
+  // ── Admin ─────────────────────────────────────────────────────────────
+  async listUsers() {
+    return this.http.get(`${this.baseUrl}/api/admin/users`, {
+      headers: this.authHeaders()
+    }).json();
+  }
+  async getUserStats() {
+    return this.http.get(`${this.baseUrl}/api/admin/users/stats`, {
+      headers: this.authHeaders()
+    }).json();
+  }
+  async updateUser(id, data) {
+    return this.http.patch(`${this.baseUrl}/api/admin/users/${id}`, {
+      json: data,
+      headers: this.authHeaders()
+    }).json();
+  }
+  async getOAuthConfig() {
+    return this.http.get(`${this.baseUrl}/api/admin/oauth/config`, {
+      headers: this.authHeaders()
+    }).json();
+  }
+  // ── Exchange (backup/restore/export/import) ───────────────────────────
+  async backupKnowledgeBase() {
+    const response = await this.http.post(`${this.baseUrl}/api/admin/exchange/backup`, {
+      headers: this.authHeaders()
+    });
+    return responseToDownload(response);
+  }
+  restoreKnowledgeBase(file) {
+    return this.sseProgressStream(`${this.baseUrl}/api/admin/exchange/restore`, file);
+  }
+  async exportKnowledgeBase(params) {
+    const searchParams = params?.includeArchived ? new URLSearchParams({ includeArchived: "true" }) : void 0;
+    const response = await this.http.post(`${this.baseUrl}/api/moderate/exchange/export`, {
+      headers: this.authHeaders(),
+      ...searchParams ? { searchParams } : {}
+    });
+    return responseToDownload(response);
+  }
+  importKnowledgeBase(file) {
+    return this.sseProgressStream(`${this.baseUrl}/api/moderate/exchange/import`, file);
+  }
+  /**
+   * 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.
+   */
+  sseProgressStream(url, file) {
+    return new Observable((subscriber) => {
+      const ctrl = new AbortController();
+      const formData = new FormData();
+      formData.append("file", file);
+      (async () => {
+        try {
+          const response = await this.http.post(url, {
+            body: formData,
+            headers: this.authHeaders(),
+            signal: ctrl.signal
+          });
+          const reader = response.body.getReader();
+          const decoder = new TextDecoder();
+          let buffer = "";
+          while (!subscriber.closed) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split("\n");
+            buffer = lines.pop();
+            for (const line of lines) {
+              if (line.startsWith("data: ")) {
+                const event = JSON.parse(line.slice(6));
+                subscriber.next(event);
+              }
+            }
+          }
+          subscriber.complete();
+        } catch (err) {
+          if (!subscriber.closed) subscriber.error(err);
+        }
+      })();
+      return () => ctrl.abort();
+    });
+  }
+  // ── System status ─────────────────────────────────────────────────────
+  async healthCheck() {
+    return this.http.get(`${this.baseUrl}/api/health`, {
+      headers: this.authHeaders()
+    }).json();
+  }
+  async getStatus() {
+    return this.http.get(`${this.baseUrl}/api/status`, {
+      headers: this.authHeaders()
+    }).json();
+  }
+  // ── Internal: ky accessor for legacy passthroughs (temporary) ─────────
+  /**
+   * 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() {
+    return this.http;
+  }
+  /**
+   * 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() {
+    return this.token$.getValue() ?? void 0;
+  }
+};
+var HttpContentTransport = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  async putBinary(request, options) {
+    const sizeBytes = request.file instanceof File ? request.file.size : request.file.length;
+    busLog("PUT", "content", {
+      name: request.name,
+      format: request.format,
+      storageUri: request.storageUri,
+      sizeBytes
+    });
+    return withSpan(
+      "content.put",
+      async () => {
+        const formData = buildFormData(request);
+        const headers = this.requestHeaders(options?.auth);
+        const xhrAvailable = typeof XMLHttpRequest !== "undefined";
+        if (xhrAvailable && (options?.onProgress || options?.signal)) {
+          return uploadViaXhr({
+            url: `${this.transport.baseUrl}/resources`,
+            formData,
+            headers,
+            onProgress: options.onProgress,
+            signal: options.signal,
+            onApiError: (err) => this.transport.pushError(err)
+          });
+        }
+        const result = await this.transport.rawHttp.post(`${this.transport.baseUrl}/resources`, {
+          body: formData,
+          headers
+        }).json();
+        return { resourceId: result.resourceId };
+      },
+      {
+        kind: SpanKind.CLIENT,
+        attrs: {
+          "content.format": request.format,
+          "content.size_bytes": sizeBytes
+        }
+      }
+    );
+  }
+  async getBinary(resourceId, options) {
+    busLog("GET", "content", { resourceId });
+    return withSpan(
+      "content.get",
+      async () => {
+        const response = await this.transport.rawHttp.get(`${this.transport.baseUrl}/resources/${resourceId}`, {
+          headers: this.requestHeaders(options?.auth)
+        });
+        const contentType = response.headers.get("content-type") || "application/octet-stream";
+        const data = await response.arrayBuffer();
+        return { data, contentType };
+      },
+      { kind: SpanKind.CLIENT, attrs: { "resource.id": resourceId } }
+    );
+  }
+  async getBinaryStream(resourceId, options) {
+    busLog("GET", "content", { resourceId, stream: true });
+    return withSpan(
+      "content.get",
+      async () => {
+        const response = await this.transport.rawHttp.get(`${this.transport.baseUrl}/resources/${resourceId}`, {
+          headers: this.requestHeaders(options?.auth)
+        });
+        const contentType = response.headers.get("content-type") || "application/octet-stream";
+        if (!response.body) {
+          throw new Error("Response body is null - cannot create stream");
+        }
+        return { stream: response.body, contentType };
+      },
+      {
+        kind: SpanKind.CLIENT,
+        attrs: { "resource.id": resourceId, "content.stream": true }
+      }
+    );
+  }
+  /**
+   * 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).
+   */
+  async getResourceGraph(resourceId, options) {
+    busLog("GET", "content", { resourceId, graph: true });
+    return withSpan(
+      "content.get_graph",
+      () => this.transport.rawHttp.get(`${this.transport.baseUrl}/resources/${resourceId}/jsonld`, {
+        headers: this.requestHeaders(options?.auth)
+      }).json(),
+      { kind: SpanKind.CLIENT, attrs: { "resource.id": resourceId, "content.graph": true } }
+    );
+  }
+  dispose() {
+  }
+  /** Auth header + W3C trace propagation for the active span. */
+  requestHeaders(override) {
+    const token = override ?? this.transport.getToken();
+    const headers = token ? { Authorization: `Bearer ${token}` } : {};
+    const trace = getActiveTraceparent();
+    if (trace) {
+      headers["traceparent"] = trace.traceparent;
+      if (trace.tracestate) headers["tracestate"] = trace.tracestate;
+    }
+    return headers;
+  }
+};
+function buildFormData(request) {
+  const formData = new FormData();
+  formData.append("name", request.name);
+  formData.append("format", request.format);
+  formData.append("storageUri", request.storageUri);
+  if (request.file instanceof File) {
+    formData.append("file", request.file);
+  } else if (typeof Buffer !== "undefined" && Buffer.isBuffer(request.file)) {
+    const blob = new Blob([new Uint8Array(request.file)], { type: request.format });
+    formData.append("file", blob, request.name);
+  } else {
+    throw new Error("file must be a File or Buffer");
+  }
+  if (request.entityTypes && request.entityTypes.length > 0) {
+    formData.append("entityTypes", JSON.stringify(request.entityTypes));
+  }
+  if (request.language) formData.append("language", request.language);
+  if (request.sourceAnnotationId) formData.append("sourceAnnotationId", String(request.sourceAnnotationId));
+  if (request.sourceResourceId) formData.append("sourceResourceId", String(request.sourceResourceId));
+  if (request.generationPrompt) formData.append("generationPrompt", request.generationPrompt);
+  if (request.generator) formData.append("generator", JSON.stringify(request.generator));
+  if (request.isDraft !== void 0) formData.append("isDraft", String(request.isDraft));
+  return formData;
+}
+function uploadViaXhr(opts) {
+  const { url, formData, headers, onProgress, signal, onApiError } = opts;
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    if (signal?.aborted) {
+      const err = new APIError("Upload aborted", 0, "aborted");
+      onApiError(err);
+      reject(err);
+      return;
+    }
+    xhr.open("POST", url);
+    for (const [name, value] of Object.entries(headers)) {
+      xhr.setRequestHeader(name, value);
+    }
+    if (onProgress) {
+      xhr.upload.onprogress = (e) => {
+        const totalBytes = e.lengthComputable ? e.total : 0;
+        onProgress({ bytesUploaded: e.loaded, totalBytes });
+      };
+    }
+    xhr.onload = () => {
+      if (xhr.status >= 200 && xhr.status < 300) {
+        try {
+          const body2 = JSON.parse(xhr.responseText);
+          resolve({ resourceId: body2.resourceId });
+        } catch (parseErr) {
+          const err2 = new APIError(
+            `Upload succeeded but response was not valid JSON: ${parseErr.message}`,
+            xhr.status,
+            xhr.statusText,
+            xhr.responseText
+          );
+          onApiError(err2);
+          reject(err2);
+        }
+        return;
+      }
+      let body = xhr.responseText;
+      try {
+        body = JSON.parse(xhr.responseText);
+      } catch {
+      }
+      const message = body && typeof body === "object" && "message" in body && typeof body.message === "string" ? body.message : `HTTP ${xhr.status}: ${xhr.statusText}`;
+      const err = new APIError(message, xhr.status, xhr.statusText, body);
+      onApiError(err);
+      reject(err);
+    };
+    xhr.onerror = () => {
+      const err = new APIError("Network error during upload", 0, "network-error");
+      onApiError(err);
+      reject(err);
+    };
+    xhr.ontimeout = () => {
+      const err = new APIError("Upload timed out", 0, "timeout");
+      onApiError(err);
+      reject(err);
+    };
+    xhr.onabort = () => {
+      const err = new APIError("Upload aborted", 0, "aborted");
+      onApiError(err);
+      reject(err);
+    };
+    if (signal) {
+      const onAbort = () => xhr.abort();
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+    xhr.send(formData);
+  });
+}
+
+export { APIError, DEGRADED_THRESHOLD_MS, HttpContentTransport, HttpTransport, createActorStateUnit };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map