@semiont/api-client 0.4.7 → 0.4.10

package/dist/index.js

@@ -1,7 +1,8 @@
 import ky from 'ky';
-import { merge, firstValueFrom } from 'rxjs';
-import { filter, map, take, timeout } from 'rxjs/operators';
+import { Subscription, BehaviorSubject, merge, firstValueFrom } from 'rxjs';
+import { resourceId, annotationId } from '@semiont/core';
 export { getFragmentSelector, getSvgSelector, getTextPositionSelector, validateSvgMarkup } from '@semiont/core';
+import { map, distinctUntilChanged, filter, take, timeout } from 'rxjs/operators';
 
 // src/client.ts
 
@@ -133,9 +134,7 @@ function createSSEStream(url, fetchOptions, config, logger) {
         abortController.abort();
       }
     } catch (error) {
-      console.error("[SSE] Failed to parse event data:", error);
-      console.error("[SSE] Event type:", eventType);
-      console.error("[SSE] Data:", data);
+      logger?.error("SSE Failed to parse event data", { error, eventType, data });
     }
   };
   connect();
@@ -602,8 +601,8 @@ var SSEClient = class {
    * @param options - Request options (auth token, eventBus)
    * @returns SSE stream controller
    */
-  bindSearch(resourceId, request, options) {
-    const url = `${this.baseUrl}/resources/${resourceId}/bind-search-stream`;
+  matchSearch(resourceId, request, options) {
+    const url = `${this.baseUrl}/resources/${resourceId}/match-search-stream`;
     return createSSEStream(
       url,
       {
@@ -766,6 +765,499 @@ var SSEClient = class {
     return stream;
   }
 };
+var FlowEngine = class {
+  constructor(eventBus, sse, http) {
+    this.eventBus = eventBus;
+    this.sse = sse;
+    this.http = http;
+  }
+  // ─── bind flow ─────────────────────────────────────────────────────────────
+  /**
+   * Activate the bind flow for a resource.
+   *
+   * @subscribes bind:update-body  — calls SSE bindAnnotation
+   * @subscribes match:search-requested — calls SSE bindSearch
+   * @emits bind:body-updated, bind:body-update-failed
+   */
+  bind(rUri, getToken) {
+    const sub = new Subscription();
+    sub.add(
+      this.eventBus.get("bind:update-body").subscribe((event) => {
+        const annotationId = event.annotationId;
+        const finishedSub = this.eventBus.get("bind:finished").subscribe((finishedEvent) => {
+          if (finishedEvent.annotationId !== annotationId) return;
+          finishedSub.unsubscribe();
+          failedSub.unsubscribe();
+          this.eventBus.get("bind:body-updated").next({ annotationId });
+        });
+        const failedSub = this.eventBus.get("bind:failed").subscribe(() => {
+          finishedSub.unsubscribe();
+          failedSub.unsubscribe();
+          this.eventBus.get("bind:body-update-failed").next({ error: new Error("Bind failed") });
+        });
+        this.sse.bindAnnotation(
+          rUri,
+          annotationId,
+          { resourceId: event.resourceId, operations: event.operations },
+          { auth: getToken(), eventBus: this.eventBus }
+        );
+      })
+    );
+    sub.add(
+      this.eventBus.get("match:search-requested").subscribe((event) => {
+        this.sse.matchSearch(rUri, {
+          correlationId: event.correlationId,
+          referenceId: event.referenceId,
+          context: event.context,
+          limit: event.limit,
+          useSemanticScoring: event.useSemanticScoring
+        }, { auth: getToken(), eventBus: this.eventBus });
+      })
+    );
+    return sub;
+  }
+  // ─── yield flow ────────────────────────────────────────────────────────────
+  /**
+   * Activate the yield (generation) flow for a resource.
+   *
+   * @subscribes yield:request — calls SSE yieldResource
+   * @subscribes yield:finished — links generated resource back to the reference annotation via bind:update-body
+   * @subscribes job:cancel-requested (generation) — aborts in-flight stream
+   */
+  yield(_rUri, getToken) {
+    const sub = new Subscription();
+    let abortController = null;
+    sub.add(
+      this.eventBus.get("yield:request").subscribe((event) => {
+        abortController?.abort();
+        abortController = new AbortController();
+        this.sse.yieldResource(
+          event.resourceId,
+          event.annotationId,
+          event.options,
+          { auth: getToken(), eventBus: this.eventBus }
+        );
+      })
+    );
+    sub.add(
+      this.eventBus.get("yield:finished").subscribe((event) => {
+        if (!event.resourceId || !event.referenceId || !event.sourceResourceId) return;
+        this.eventBus.get("bind:update-body").next({
+          annotationId: annotationId(event.referenceId),
+          resourceId: resourceId(event.sourceResourceId),
+          operations: [{ op: "add", item: { type: "SpecificResource", source: event.resourceId } }]
+        });
+      })
+    );
+    sub.add(
+      this.eventBus.get("job:cancel-requested").subscribe((event) => {
+        if (event.jobType === "generation") {
+          abortController?.abort();
+          abortController = null;
+        }
+      })
+    );
+    sub.add(new Subscription(() => {
+      abortController?.abort();
+    }));
+    return sub;
+  }
+  // ─── mark flow ─────────────────────────────────────────────────────────────
+  /**
+   * Activate the mark (annotation CRUD + assist) flow for a resource.
+   *
+   * @subscribes mark:submit — HTTP markAnnotation
+   * @subscribes mark:delete — HTTP deleteAnnotation
+   * @subscribes mark:assist-request — SSE mark* (by motivation)
+   * @subscribes job:cancel-requested (annotation) — aborts in-flight assist
+   * @emits mark:created, mark:create-failed, mark:deleted, mark:delete-failed
+   */
+  mark(rUri, getToken) {
+    const sub = new Subscription();
+    let assistAbort = null;
+    sub.add(
+      this.eventBus.get("mark:submit").subscribe(async (event) => {
+        try {
+          const result = await this.http.markAnnotation(rUri, {
+            motivation: event.motivation,
+            target: { source: rUri, selector: event.selector },
+            body: event.body
+          }, { auth: getToken() });
+          this.eventBus.get("mark:created").next({ annotationId: annotationId(result.annotationId) });
+        } catch (error) {
+          this.eventBus.get("mark:create-failed").next({ error });
+        }
+      })
+    );
+    sub.add(
+      this.eventBus.get("mark:delete").subscribe(async (event) => {
+        try {
+          await this.http.deleteAnnotation(rUri, event.annotationId, { auth: getToken() });
+          this.eventBus.get("mark:deleted").next({ annotationId: event.annotationId });
+        } catch (error) {
+          this.eventBus.get("mark:delete-failed").next({ error });
+        }
+      })
+    );
+    sub.add(
+      this.eventBus.get("mark:assist-request").subscribe(async (event) => {
+        assistAbort?.abort();
+        assistAbort = new AbortController();
+        const opts = { auth: getToken(), eventBus: this.eventBus };
+        const { motivation, options } = event;
+        try {
+          if (motivation === "tagging") {
+            const { schemaId, categories } = options;
+            if (!schemaId || !categories?.length) throw new Error("Tag assist requires schemaId and categories");
+            this.sse.markTags(rUri, { schemaId, categories }, opts);
+          } else if (motivation === "linking") {
+            const { entityTypes, includeDescriptiveReferences } = options;
+            if (!entityTypes?.length) throw new Error("Reference assist requires entityTypes");
+            this.sse.markReferences(rUri, {
+              entityTypes,
+              includeDescriptiveReferences: includeDescriptiveReferences ?? false
+            }, opts);
+          } else if (motivation === "highlighting") {
+            this.sse.markHighlights(rUri, { instructions: options.instructions, density: options.density }, opts);
+          } else if (motivation === "assessing") {
+            this.sse.markAssessments(rUri, {
+              instructions: options.instructions,
+              tone: options.tone,
+              density: options.density,
+              language: options.language
+            }, opts);
+          } else if (motivation === "commenting") {
+            this.sse.markComments(rUri, {
+              instructions: options.instructions,
+              tone: options.tone,
+              density: options.density,
+              language: options.language
+            }, opts);
+          }
+        } catch (error) {
+          if (error instanceof Error && error.name === "AbortError") {
+            this.eventBus.get("mark:assist-cancelled").next(void 0);
+          }
+        }
+      })
+    );
+    sub.add(
+      this.eventBus.get("job:cancel-requested").subscribe((event) => {
+        if (event.jobType === "annotation") {
+          assistAbort?.abort();
+          assistAbort = null;
+        }
+      })
+    );
+    sub.add(new Subscription(() => {
+      assistAbort?.abort();
+    }));
+    return sub;
+  }
+  // ─── gatherContext flow ─────────────────────────────────────────────────────
+  /**
+   * Activate the gather-context flow for a resource.
+   *
+   * @subscribes gather:requested — calls SSE gatherAnnotation, threads correlationId
+   * @emits gather:complete (re-emitted from SSE gather:annotation-finished)
+   */
+  gatherContext(rUri, getToken) {
+    return this.eventBus.get("gather:requested").subscribe((event) => {
+      const { correlationId } = event;
+      const contextWindow = event.options?.contextWindow ?? 2e3;
+      const finishedSub = this.eventBus.get("gather:annotation-finished").subscribe((finishedEvent) => {
+        if (finishedEvent.correlationId !== correlationId) return;
+        finishedSub.unsubscribe();
+        failedSub.unsubscribe();
+        this.eventBus.get("gather:complete").next({
+          correlationId,
+          annotationId: finishedEvent.annotationId,
+          response: finishedEvent.response
+        });
+      });
+      const failedSub = this.eventBus.get("gather:failed").subscribe((failedEvent) => {
+        if (failedEvent.correlationId !== correlationId) return;
+        finishedSub.unsubscribe();
+        failedSub.unsubscribe();
+      });
+      this.sse.gatherAnnotation(
+        rUri,
+        event.annotationId,
+        { contextWindow, correlationId },
+        { auth: getToken(), eventBus: this.eventBus }
+      );
+    });
+  }
+  // ─── resourceEvents flow ───────────────────────────────────────────────────
+  /**
+   * Open the long-lived resource-events SSE stream.
+   * Returns a Subscription whose teardown closes the stream.
+   */
+  resourceEvents(rUri, getToken) {
+    const stream = this.sse.resourceEvents(rUri, {
+      auth: getToken(),
+      eventBus: this.eventBus
+    });
+    return new Subscription(() => stream.close());
+  }
+  // ─── attentionStream flow ──────────────────────────────────────────────────
+  /**
+   * Open the long-lived participant attention SSE stream.
+   * Returns a Subscription whose teardown closes the stream.
+   */
+  attentionStream(getToken) {
+    const stream = this.sse.attentionStream({
+      auth: getToken(),
+      eventBus: this.eventBus
+    });
+    return new Subscription(() => stream.close());
+  }
+};
+var ResourceStore = class {
+  constructor(http, eventBus) {
+    this.http = http;
+    eventBus.get("yield:created").subscribe((event) => {
+      this.fetchDetail(event.resourceId);
+      this.invalidateLists();
+    });
+    eventBus.get("yield:updated").subscribe((event) => {
+      this.invalidateDetail(event.resourceId);
+      this.invalidateLists();
+    });
+    eventBus.get("mark:archived").subscribe((event) => {
+      if (event.resourceId) {
+        this.invalidateDetail(event.resourceId);
+        this.invalidateLists();
+      }
+    });
+    eventBus.get("mark:unarchived").subscribe((event) => {
+      if (event.resourceId) {
+        this.invalidateDetail(event.resourceId);
+        this.invalidateLists();
+      }
+    });
+    eventBus.get("mark:entity-tag-added").subscribe((event) => {
+      if (event.resourceId) {
+        this.invalidateDetail(event.resourceId);
+      }
+    });
+    eventBus.get("mark:entity-tag-removed").subscribe((event) => {
+      if (event.resourceId) {
+        this.invalidateDetail(event.resourceId);
+      }
+    });
+  }
+  /** Cache of individual resource details, keyed by ResourceId */
+  detail$ = new BehaviorSubject(/* @__PURE__ */ new Map());
+  /** Cache of list responses, keyed by a serialized options string */
+  list$ = new BehaviorSubject(/* @__PURE__ */ new Map());
+  /** Track in-flight fetches to avoid duplicate requests */
+  fetchingDetail = /* @__PURE__ */ new Set();
+  fetchingList = /* @__PURE__ */ new Set();
+  /** Memoized Observables — same instance returned for the same key */
+  detailObs$ = /* @__PURE__ */ new Map();
+  listObs$ = /* @__PURE__ */ new Map();
+  /** Mutable token getter — updated from the React layer when auth changes */
+  getToken = () => void 0;
+  /** Update the token getter (called from React when auth token changes) */
+  setTokenGetter(getter) {
+    this.getToken = getter;
+  }
+  /**
+   * Get a single resource by ID as an Observable.
+   * Triggers a fetch if not cached.
+   */
+  get(id) {
+    if (!this.detail$.value.has(id) && !this.fetchingDetail.has(id)) {
+      this.fetchDetail(id);
+    }
+    let obs = this.detailObs$.get(id);
+    if (!obs) {
+      obs = this.detail$.pipe(map((m) => m.get(id)), distinctUntilChanged());
+      this.detailObs$.set(id, obs);
+    }
+    return obs;
+  }
+  /**
+   * List resources as an Observable.
+   * Triggers a fetch if not cached.
+   */
+  list(options) {
+    const key = JSON.stringify(options ?? {});
+    if (!this.list$.value.has(key) && !this.fetchingList.has(key)) {
+      this.fetchList(key, options);
+    }
+    let obs = this.listObs$.get(key);
+    if (!obs) {
+      obs = this.list$.pipe(map((m) => m.get(key)), distinctUntilChanged());
+      this.listObs$.set(key, obs);
+    }
+    return obs;
+  }
+  /** Invalidate and re-fetch a specific resource detail */
+  invalidateDetail(id) {
+    const next = new Map(this.detail$.value);
+    next.delete(id);
+    this.detail$.next(next);
+    this.fetchDetail(id);
+  }
+  /** Remove all list caches (triggers re-fetch on next subscribe) */
+  invalidateLists() {
+    this.list$.next(/* @__PURE__ */ new Map());
+  }
+  async fetchDetail(id) {
+    if (this.fetchingDetail.has(id)) return;
+    this.fetchingDetail.add(id);
+    try {
+      const resource = await this.http.browseResource(id, { auth: this.getToken() });
+      const next = new Map(this.detail$.value);
+      next.set(id, resource);
+      this.detail$.next(next);
+    } catch {
+    } finally {
+      this.fetchingDetail.delete(id);
+    }
+  }
+  async fetchList(key, options) {
+    if (this.fetchingList.has(key)) return;
+    this.fetchingList.add(key);
+    try {
+      const result = await this.http.browseResources(options?.limit, options?.archived, void 0, { auth: this.getToken() });
+      const next = new Map(this.list$.value);
+      next.set(key, result);
+      this.list$.next(next);
+    } catch {
+    } finally {
+      this.fetchingList.delete(key);
+    }
+  }
+};
+var AnnotationStore = class {
+  constructor(http, eventBus) {
+    this.http = http;
+    eventBus.get("mark:deleted").subscribe((event) => {
+      this.removeFromDetailCache(event.annotationId);
+    });
+    eventBus.get("mark:added").subscribe((event) => {
+      if (event.resourceId) {
+        this.invalidateList(event.resourceId);
+      }
+    });
+    eventBus.get("mark:removed").subscribe((event) => {
+      if (event.resourceId) {
+        this.invalidateList(event.resourceId);
+      }
+      this.invalidateDetail(event.payload.annotationId);
+    });
+    eventBus.get("mark:body-updated").subscribe((event) => {
+      if (event.resourceId) {
+        this.invalidateList(event.resourceId);
+      }
+      this.invalidateDetail(event.payload.annotationId);
+    });
+    eventBus.get("mark:entity-tag-added").subscribe((event) => {
+      if (event.resourceId) {
+        this.invalidateList(event.resourceId);
+      }
+    });
+    eventBus.get("mark:entity-tag-removed").subscribe((event) => {
+      if (event.resourceId) {
+        this.invalidateList(event.resourceId);
+      }
+    });
+  }
+  /** Annotation list responses keyed by ResourceId */
+  list$ = new BehaviorSubject(/* @__PURE__ */ new Map());
+  /** Individual annotation details keyed by AnnotationId */
+  detail$ = new BehaviorSubject(/* @__PURE__ */ new Map());
+  /** Track in-flight fetches */
+  fetchingList = /* @__PURE__ */ new Set();
+  fetchingDetail = /* @__PURE__ */ new Set();
+  /** Memoized Observables — same instance returned for the same key */
+  listObs$ = /* @__PURE__ */ new Map();
+  detailObs$ = /* @__PURE__ */ new Map();
+  /** Mutable token getter — updated from the React layer when auth changes */
+  getToken = () => void 0;
+  /** Update the token getter (called from React when auth token changes) */
+  setTokenGetter(getter) {
+    this.getToken = getter;
+  }
+  /**
+   * Get annotations for a resource as an Observable.
+   * Triggers a fetch if not cached.
+   */
+  listForResource(resourceId) {
+    if (!this.list$.value.has(resourceId) && !this.fetchingList.has(resourceId)) {
+      this.fetchList(resourceId);
+    }
+    let obs = this.listObs$.get(resourceId);
+    if (!obs) {
+      obs = this.list$.pipe(map((m) => m.get(resourceId)), distinctUntilChanged());
+      this.listObs$.set(resourceId, obs);
+    }
+    return obs;
+  }
+  /**
+   * Get a single annotation detail as an Observable.
+   * Triggers a fetch if not cached.
+   */
+  get(resourceId, annotationId) {
+    if (!this.detail$.value.has(annotationId) && !this.fetchingDetail.has(annotationId)) {
+      this.fetchDetail(resourceId, annotationId);
+    }
+    let obs = this.detailObs$.get(annotationId);
+    if (!obs) {
+      obs = this.detail$.pipe(map((m) => m.get(annotationId)), distinctUntilChanged());
+      this.detailObs$.set(annotationId, obs);
+    }
+    return obs;
+  }
+  /** Invalidate and re-fetch a resource's annotation list */
+  invalidateList(resourceId) {
+    const next = new Map(this.list$.value);
+    next.delete(resourceId);
+    this.list$.next(next);
+    this.fetchList(resourceId);
+  }
+  /** Invalidate a single annotation detail (re-fetched on next subscribe) */
+  invalidateDetail(annotationId) {
+    const next = new Map(this.detail$.value);
+    next.delete(annotationId);
+    this.detail$.next(next);
+  }
+  /** Remove an annotation from the detail cache without re-fetching */
+  removeFromDetailCache(annotationId) {
+    const next = new Map(this.detail$.value);
+    next.delete(annotationId);
+    this.detail$.next(next);
+  }
+  async fetchList(resourceId) {
+    if (this.fetchingList.has(resourceId)) return;
+    this.fetchingList.add(resourceId);
+    try {
+      const result = await this.http.browseAnnotations(resourceId, void 0, { auth: this.getToken() });
+      const next = new Map(this.list$.value);
+      next.set(resourceId, result);
+      this.list$.next(next);
+    } catch {
+    } finally {
+      this.fetchingList.delete(resourceId);
+    }
+  }
+  async fetchDetail(resourceId, annotationId) {
+    if (this.fetchingDetail.has(annotationId)) return;
+    this.fetchingDetail.add(annotationId);
+    try {
+      const result = await this.http.browseAnnotation(resourceId, annotationId, { auth: this.getToken() });
+      const next = new Map(this.detail$.value);
+      next.set(annotationId, result);
+      this.detail$.next(next);
+    } catch {
+    } finally {
+      this.fetchingDetail.delete(annotationId);
+    }
+  }
+};
 
 // src/client.ts
 var APIError = class extends Error {
@@ -780,29 +1272,30 @@ var APIError = class extends Error {
 var SemiontApiClient = class {
   http;
   baseUrl;
+  /** The workspace-scoped EventBus this client was constructed with. */
+  eventBus;
   logger;
   /**
    * SSE streaming client for real-time operations
    *
    * Separate from the main HTTP client to clearly mark streaming endpoints.
    * Uses native fetch() instead of ky for SSE support.
-   *
-   * @example
-   * ```typescript
-   * const stream = client.sse.detectAnnotations(
-   *   resourceId,
-   *   { entityTypes: ['Person', 'Organization'] },
-   *   { auth: accessToken }
-   * );
-   *
-   * stream.onProgress((p) => console.log(p.message));
-   * stream.onComplete((r) => console.log(`Found ${r.foundCount} entities`));
-   * stream.close();
-   * ```
    */
   sse;
+  /**
+   * Framework-agnostic flow orchestration.
+   * Each method returns a Subscription; call .unsubscribe() to tear down.
+   */
+  flows;
+  /**
+   * Per-workspace observable stores for entity data.
+   * Call stores.resources.setTokenGetter() / stores.annotations.setTokenGetter()
+   * from the React layer when the auth token changes.
+   */
+  stores;
   constructor(config) {
-    const { baseUrl, timeout: timeout2 = 3e4, retry = 2, logger } = config;
+    const { baseUrl, eventBus, timeout: timeout2 = 3e4, retry = 2, logger } = config;
+    this.eventBus = eventBus;
     this.logger = logger;
     this.baseUrl = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
     this.http = ky.create({
@@ -811,18 +1304,14 @@ var SemiontApiClient = class {
       credentials: "include",
       hooks: {
         beforeRequest: [
-          (request, options) => {
-            const auth = options.auth;
-            if (auth) {
-              request.headers.set("Authorization", `Bearer ${auth}`);
-            }
+          (request) => {
             if (this.logger) {
               this.logger.debug("HTTP Request", {
                 type: "http_request",
                 url: request.url,
                 method: request.method,
                 timestamp: Date.now(),
-                hasAuth: !!auth
+                hasAuth: request.headers.has("Authorization")
               });
             }
           }
@@ -872,6 +1361,14 @@ var SemiontApiClient = class {
       baseUrl: this.baseUrl,
       logger: this.logger
     });
+    this.flows = new FlowEngine(this.eventBus, this.sse, this);
+    this.stores = {
+      resources: new ResourceStore(this, this.eventBus),
+      annotations: new AnnotationStore(this, this.eventBus)
+    };
+  }
+  authHeaders(options) {
+    return options?.auth ? { Authorization: `Bearer ${options.auth}` } : {};
   }
   // ============================================================================
   // AUTHENTICATION
@@ -879,28 +1376,30 @@ var SemiontApiClient = class {
   async authenticatePassword(email, password, options) {
     return this.http.post(`${this.baseUrl}/api/tokens/password`, {
       json: { email, password },
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   async refreshToken(token, options) {
     return this.http.post(`${this.baseUrl}/api/tokens/refresh`, {
       json: { refreshToken: token },
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   async authenticateGoogle(credential, options) {
     return this.http.post(`${this.baseUrl}/api/tokens/google`, {
       json: { credential },
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   async generateMCPToken(options) {
     return this.http.post(`${this.baseUrl}/api/tokens/mcp-generate`, {
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
+    }).json();
+  }
+  async getMediaToken(resourceId, options) {
+    return this.http.post(`${this.baseUrl}/api/tokens/media`, {
+      json: { resourceId },
+      headers: this.authHeaders(options)
     }).json();
   }
   // ============================================================================
@@ -908,21 +1407,18 @@ var SemiontApiClient = class {
   // ============================================================================
   async getMe(options) {
     return this.http.get(`${this.baseUrl}/api/users/me`, {
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   async acceptTerms(options) {
     return this.http.post(`${this.baseUrl}/api/users/accept-terms`, {
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   async logout(options) {
-    if (options) {
-      return this.http.post(`${this.baseUrl}/api/users/logout`, options).json();
-    }
-    return this.http.post(`${this.baseUrl}/api/users/logout`).json();
+    return this.http.post(`${this.baseUrl}/api/users/logout`, {
+      headers: this.authHeaders(options)
+    }).json();
   }
   // ============================================================================
   // RESOURCES
@@ -971,14 +1467,12 @@ var SemiontApiClient = class {
     }
     return this.http.post(`${this.baseUrl}/resources`, {
       body: formData,
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   async browseResource(id, options) {
     return this.http.get(`${this.baseUrl}/resources/${id}`, {
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   /**
@@ -1006,9 +1500,9 @@ var SemiontApiClient = class {
   async getResourceRepresentation(id, options) {
     const response = await this.http.get(`${this.baseUrl}/resources/${id}`, {
       headers: {
-        Accept: options?.accept || "text/plain"
-      },
-      auth: options?.auth
+        Accept: options?.accept || "text/plain",
+        ...this.authHeaders(options)
+      }
     });
     const contentType = response.headers.get("content-type") || "application/octet-stream";
     const data = await response.arrayBuffer();
@@ -1053,9 +1547,9 @@ var SemiontApiClient = class {
   async getResourceRepresentationStream(id, options) {
     const response = await this.http.get(`${this.baseUrl}/resources/${id}`, {
       headers: {
-        Accept: options?.accept || "text/plain"
-      },
-      auth: options?.auth
+        Accept: options?.accept || "text/plain",
+        ...this.authHeaders(options)
+      }
     });
     const contentType = response.headers.get("content-type") || "application/octet-stream";
     if (!response.body) {
@@ -1070,46 +1564,39 @@ var SemiontApiClient = class {
     if (query) searchParams.append("q", query);
     return this.http.get(`${this.baseUrl}/resources`, {
       searchParams,
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   async updateResource(id, data, options) {
     await this.http.patch(`${this.baseUrl}/resources/${id}`, {
       json: data,
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).text();
   }
   async getResourceEvents(id, options) {
     return this.http.get(`${this.baseUrl}/resources/${id}/events`, {
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   async browseReferences(id, options) {
     return this.http.get(`${this.baseUrl}/resources/${id}/referenced-by`, {
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   async generateCloneToken(id, options) {
     return this.http.post(`${this.baseUrl}/resources/${id}/clone-with-token`, {
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   async getResourceByToken(token, options) {
     return this.http.get(`${this.baseUrl}/api/clone-tokens/${token}`, {
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   async createResourceFromToken(data, options) {
     return this.http.post(`${this.baseUrl}/api/clone-tokens/create-resource`, {
       json: data,
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   // ============================================================================
@@ -1118,20 +1605,17 @@ var SemiontApiClient = class {
   async markAnnotation(id, data, options) {
     return this.http.post(`${this.baseUrl}/resources/${id}/annotations`, {
       json: data,
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   async getAnnotation(id, options) {
     return this.http.get(`${this.baseUrl}/annotations/${id}`, {
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   async browseAnnotation(resourceId, annotationId, options) {
     return this.http.get(`${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}`, {
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   async browseAnnotations(id, motivation, options) {
@@ -1139,29 +1623,24 @@ var SemiontApiClient = class {
     if (motivation) searchParams.append("motivation", motivation);
     return this.http.get(`${this.baseUrl}/resources/${id}/annotations`, {
       searchParams,
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   async deleteAnnotation(resourceId, annotationId, options) {
     await this.http.delete(`${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}`, {
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     });
   }
   async bindAnnotation(resourceId, annotationId, data, options) {
     await this.http.put(`${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}/body`, {
       json: data,
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     });
   }
   async getAnnotationHistory(resourceId, annotationId, options) {
-    const url = `${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}/history`;
-    if (options) {
-      return this.http.get(url, options).json();
-    }
-    return this.http.get(url).json();
+    return this.http.get(`${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}/history`, {
+      headers: this.authHeaders(options)
+    }).json();
   }
   // ============================================================================
   // ENTITY TYPES
@@ -1169,21 +1648,18 @@ var SemiontApiClient = class {
   async addEntityType(type, options) {
     await this.http.post(`${this.baseUrl}/api/entity-types`, {
       json: { tag: type },
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     });
   }
   async addEntityTypesBulk(types, options) {
     await this.http.post(`${this.baseUrl}/api/entity-types/bulk`, {
       json: { tags: types },
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     });
   }
   async listEntityTypes(options) {
     return this.http.get(`${this.baseUrl}/api/entity-types`, {
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   // ============================================================================
@@ -1192,8 +1668,7 @@ var SemiontApiClient = class {
   async beckonAttention(participantId, data, options) {
     return this.http.post(`${this.baseUrl}/api/participants/${participantId}/attention`, {
       json: data,
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   // ============================================================================
@@ -1201,14 +1676,12 @@ var SemiontApiClient = class {
   // ============================================================================
   async listUsers(options) {
     return this.http.get(`${this.baseUrl}/api/admin/users`, {
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   async getUserStats(options) {
     return this.http.get(`${this.baseUrl}/api/admin/users/stats`, {
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   /**
@@ -1218,14 +1691,12 @@ var SemiontApiClient = class {
   async updateUser(id, data, options) {
     return this.http.patch(`${this.baseUrl}/api/admin/users/${id}`, {
       json: data,
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   async getOAuthConfig(options) {
     return this.http.get(`${this.baseUrl}/api/admin/oauth/config`, {
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   // ============================================================================
@@ -1236,12 +1707,8 @@ var SemiontApiClient = class {
    * Caller should use response.blob() to trigger a file download.
    */
   async backupKnowledgeBase(options) {
-    return fetch(`${this.baseUrl}/api/admin/exchange/backup`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        ...options?.auth ? { Authorization: `Bearer ${options.auth}` } : {}
-      }
+    return this.http.post(`${this.baseUrl}/api/admin/exchange/backup`, {
+      headers: this.authHeaders(options)
     });
   }
   /**
@@ -1251,35 +1718,11 @@ var SemiontApiClient = class {
   async restoreKnowledgeBase(file, options) {
     const formData = new FormData();
     formData.append("file", file);
-    const response = await fetch(`${this.baseUrl}/api/admin/exchange/restore`, {
-      method: "POST",
-      headers: {
-        ...options?.auth ? { Authorization: `Bearer ${options.auth}` } : {}
-      },
-      body: formData
+    const response = await this.http.post(`${this.baseUrl}/api/admin/exchange/restore`, {
+      body: formData,
+      headers: this.authHeaders(options)
     });
-    if (!response.ok) {
-      throw new Error(`Restore failed: ${response.status} ${response.statusText}`);
-    }
-    const reader = response.body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = "";
-    let finalResult = { phase: "unknown" };
-    while (true) {
-      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));
-          options?.onProgress?.(event);
-          finalResult = event;
-        }
-      }
-    }
-    return finalResult;
+    return this.parseSSEStream(response, options?.onProgress);
   }
   // ============================================================================
   // ADMIN — EXCHANGE (Linked Data Export/Import)
@@ -1289,13 +1732,10 @@ var SemiontApiClient = class {
    * Caller should use response.blob() to trigger a file download.
    */
   async exportKnowledgeBase(params, options) {
-    const query = params?.includeArchived ? "?includeArchived=true" : "";
-    return fetch(`${this.baseUrl}/api/moderate/exchange/export${query}`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        ...options?.auth ? { Authorization: `Bearer ${options.auth}` } : {}
-      }
+    const searchParams = params?.includeArchived ? new URLSearchParams({ includeArchived: "true" }) : void 0;
+    return this.http.post(`${this.baseUrl}/api/moderate/exchange/export`, {
+      headers: this.authHeaders(options),
+      ...searchParams ? { searchParams } : {}
     });
   }
   /**
@@ -1305,16 +1745,13 @@ var SemiontApiClient = class {
   async importKnowledgeBase(file, options) {
     const formData = new FormData();
     formData.append("file", file);
-    const response = await fetch(`${this.baseUrl}/api/moderate/exchange/import`, {
-      method: "POST",
-      headers: {
-        ...options?.auth ? { Authorization: `Bearer ${options.auth}` } : {}
-      },
-      body: formData
+    const response = await this.http.post(`${this.baseUrl}/api/moderate/exchange/import`, {
+      body: formData,
+      headers: this.authHeaders(options)
     });
-    if (!response.ok) {
-      throw new Error(`Import failed: ${response.status} ${response.statusText}`);
-    }
+    return this.parseSSEStream(response, options?.onProgress);
+  }
+  async parseSSEStream(response, onProgress) {
     const reader = response.body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
@@ -1328,7 +1765,7 @@ var SemiontApiClient = class {
       for (const line of lines) {
         if (line.startsWith("data: ")) {
           const event = JSON.parse(line.slice(6));
-          options?.onProgress?.(event);
+          onProgress?.(event);
           finalResult = event;
         }
       }
@@ -1339,10 +1776,9 @@ var SemiontApiClient = class {
   // JOB STATUS
   // ============================================================================
   async getJobStatus(id, options) {
-    if (options) {
-      return this.http.get(`${this.baseUrl}/api/jobs/${id}`, options).json();
-    }
-    return this.http.get(`${this.baseUrl}/api/jobs/${id}`).json();
+    return this.http.get(`${this.baseUrl}/api/jobs/${id}`, {
+      headers: this.authHeaders(options)
+    }).json();
   }
   /**
    * Poll a job until it completes or fails
@@ -1373,15 +1809,13 @@ var SemiontApiClient = class {
   // ============================================================================
   async healthCheck(options) {
     return this.http.get(`${this.baseUrl}/api/health`, {
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
   async getStatus(options) {
-    if (options) {
-      return this.http.get(`${this.baseUrl}/api/status`, options).json();
-    }
-    return this.http.get(`${this.baseUrl}/api/status`).json();
+    return this.http.get(`${this.baseUrl}/api/status`, {
+      headers: this.authHeaders(options)
+    }).json();
   }
   async browseFiles(dirPath, sort, options) {
     const searchParams = new URLSearchParams();
@@ -1389,13 +1823,12 @@ var SemiontApiClient = class {
     if (sort) searchParams.append("sort", sort);
     return this.http.get(`${this.baseUrl}/api/browse/files`, {
       searchParams,
-      ...options,
-      auth: options?.auth
+      headers: this.authHeaders(options)
     }).json();
   }
 };
 async function eventBusRequest(eventBus, requestEvent, payload, successEvent, failureEvent, timeoutMs = 3e4) {
-  const correlationId = payload.correlationId;
+  const { correlationId } = payload;
   const result$ = merge(
     eventBus.get(successEvent).pipe(
       filter((e) => e.correlationId === correlationId),
@@ -1596,7 +2029,7 @@ var EventBusClient = class {
     const result$ = merge(
       this.eventBus.get("gather:resource-complete").pipe(
         filter((e) => e.correlationId === correlationId),
-        map((e) => ({ ok: true, response: e.context }))
+        map((e) => ({ ok: true, response: e.response }))
       ),
       this.eventBus.get("gather:resource-failed").pipe(
         filter((e) => e.correlationId === correlationId),
@@ -1624,11 +2057,11 @@ var EventBusClient = class {
     const result$ = merge(
       this.eventBus.get("match:search-results").pipe(
         filter((e) => e.correlationId === correlationId),
-        map((e) => ({ ok: true, results: e.results }))
+        map((e) => ({ ok: true, response: e.response }))
       ),
       this.eventBus.get("match:search-failed").pipe(
         filter((e) => e.correlationId === correlationId),
-        map((e) => ({ ok: false, error: e.error }))
+        map((e) => ({ ok: false, error: new Error(e.error) }))
       )
     ).pipe(take(1), timeout(this.timeoutMs));
     const resultPromise = firstValueFrom(result$);
@@ -1658,7 +2091,7 @@ var EventBusClient = class {
     if (!result.ok) {
       throw result.error;
     }
-    return result.results;
+    return result.response;
   }
 };
 function getBodySource(body) {
@@ -2303,14 +2736,14 @@ function isValidEmail(email) {
 
 // src/mime-utils.ts
 function getExtensionForMimeType(mimeType) {
-  const map2 = {
+  const map4 = {
     "text/plain": "txt",
     "text/markdown": "md",
     "image/png": "png",
     "image/jpeg": "jpg",
     "application/pdf": "pdf"
   };
-  return map2[mimeType] || "dat";
+  return map4[mimeType] || "dat";
 }
 function isImageMimeType(mimeType) {
   return mimeType === "image/png" || mimeType === "image/jpeg";
@@ -2331,6 +2764,6 @@ function getMimeCategory(mimeType) {
   return "unsupported";
 }
 
-export { APIError, EventBusClient, JWTTokenSchema, LOCALES, SSEClient, SSE_STREAM_CONNECTED, SemiontApiClient, buildContentCache, createCircleSvg, createPolygonSvg, createRectangleSvg, decodeRepresentation, decodeWithCharset, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findTextWithContext, formatLocaleDisplay, getAllLocaleCodes, getAnnotationExactText, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getExtensionForMimeType, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getMimeCategory, getNodeEncoding, getPrimaryMediaType, getPrimaryRepresentation, getPrimarySelector, getResourceEntityTypes, getResourceId, getStorageUri, getTargetSelector, getTargetSource, getTextQuoteSelector, hasTargetSelector, isArchived, isAssessment, isBodyResolved, isComment, isDraft, isHighlight, isImageMimeType, isPdfMimeType, isReference, isResolvedReference, isStubReference, isTag, isTextMimeType, isValidEmail, normalizeCoordinates, normalizeText, parseSvgSelector, scaleSvgToNative, validateAndCorrectOffsets, validateData, verifyPosition };
+export { APIError, AnnotationStore, EventBusClient, FlowEngine, JWTTokenSchema, LOCALES, ResourceStore, SSEClient, SSE_STREAM_CONNECTED, SemiontApiClient, buildContentCache, createCircleSvg, createPolygonSvg, createRectangleSvg, decodeRepresentation, decodeWithCharset, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findTextWithContext, formatLocaleDisplay, getAllLocaleCodes, getAnnotationExactText, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getExtensionForMimeType, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getMimeCategory, getNodeEncoding, getPrimaryMediaType, getPrimaryRepresentation, getPrimarySelector, getResourceEntityTypes, getResourceId, getStorageUri, getTargetSelector, getTargetSource, getTextQuoteSelector, hasTargetSelector, isArchived, isAssessment, isBodyResolved, isComment, isDraft, isHighlight, isImageMimeType, isPdfMimeType, isReference, isResolvedReference, isStubReference, isTag, isTextMimeType, isValidEmail, normalizeCoordinates, normalizeText, parseSvgSelector, scaleSvgToNative, validateAndCorrectOffsets, validateData, verifyPosition };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map