@semiont/api-client 0.2.46 → 0.3.0

package/dist/index.js

@@ -1,7 +1,6 @@
 import ky from 'ky';
 import { merge, firstValueFrom } from 'rxjs';
 import { filter, map, take, timeout } from 'rxjs/operators';
-import { resourceUri } from '@semiont/core';
 export { getFragmentSelector, getSvgSelector, getTextPositionSelector, validateSvgMarkup } from '@semiont/core';
 
 // src/client.ts
@@ -168,17 +167,6 @@ var SSEClient = class {
     }
     return headers;
   }
-  /**
-   * Extract resource ID from URI
-   *
-   * Handles both full URIs and plain IDs:
-   * - 'http://localhost:4000/resources/doc-123' -> 'doc-123'
-   * - 'doc-123' -> 'doc-123'
-   */
-  extractId(uri) {
-    const parts = uri.split("/");
-    return parts[parts.length - 1];
-  }
   /**
    * Detect annotations in a resource (streaming)
    *
@@ -215,8 +203,7 @@ var SSEClient = class {
    * ```
    */
   annotateReferences(resourceId, request, options) {
-    const id = this.extractId(resourceId);
-    const url = `${this.baseUrl}/resources/${id}/annotate-references-stream`;
+    const url = `${this.baseUrl}/resources/${resourceId}/annotate-references-stream`;
     return createSSEStream(
       url,
       {
@@ -272,9 +259,7 @@ var SSEClient = class {
    * ```
    */
   yieldResourceFromAnnotation(resourceId, annotationId, request, options) {
-    const resId = this.extractId(resourceId);
-    const annId = this.extractId(annotationId);
-    const url = `${this.baseUrl}/resources/${resId}/annotations/${annId}/yield-resource-stream`;
+    const url = `${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}/yield-resource-stream`;
     return createSSEStream(
       url,
       {
@@ -328,8 +313,7 @@ var SSEClient = class {
    * ```
    */
   annotateHighlights(resourceId, request = {}, options) {
-    const id = this.extractId(resourceId);
-    const url = `${this.baseUrl}/resources/${id}/annotate-highlights-stream`;
+    const url = `${this.baseUrl}/resources/${resourceId}/annotate-highlights-stream`;
     return createSSEStream(
       url,
       {
@@ -383,8 +367,7 @@ var SSEClient = class {
    * ```
    */
   annotateAssessments(resourceId, request = {}, options) {
-    const id = this.extractId(resourceId);
-    const url = `${this.baseUrl}/resources/${id}/annotate-assessments-stream`;
+    const url = `${this.baseUrl}/resources/${resourceId}/annotate-assessments-stream`;
     return createSSEStream(
       url,
       {
@@ -442,8 +425,7 @@ var SSEClient = class {
    * ```
    */
   annotateComments(resourceId, request = {}, options) {
-    const id = this.extractId(resourceId);
-    const url = `${this.baseUrl}/resources/${id}/annotate-comments-stream`;
+    const url = `${this.baseUrl}/resources/${resourceId}/annotate-comments-stream`;
     return createSSEStream(
       url,
       {
@@ -502,8 +484,7 @@ var SSEClient = class {
    * ```
    */
   annotateTags(resourceId, request, options) {
-    const id = this.extractId(resourceId);
-    const url = `${this.baseUrl}/resources/${id}/annotate-tags-stream`;
+    const url = `${this.baseUrl}/resources/${resourceId}/annotate-tags-stream`;
     return createSSEStream(
       url,
       {
@@ -521,6 +502,35 @@ var SSEClient = class {
       this.logger
     );
   }
+  /**
+   * Search for binding candidates (streaming)
+   *
+   * Bridges bind:search-requested to the backend Binder actor via SSE.
+   * Results emit as bind:search-results on the browser EventBus.
+   *
+   * @param resourceId - Resource the annotation belongs to
+   * @param request - Search configuration (referenceId, context, limit)
+   * @param options - Request options (auth token, eventBus)
+   * @returns SSE stream controller
+   */
+  bindSearch(resourceId, request, options) {
+    const url = `${this.baseUrl}/resources/${resourceId}/bind-search-stream`;
+    return createSSEStream(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(options.auth),
+        body: JSON.stringify(request)
+      },
+      {
+        progressEvents: [],
+        completeEvent: "bind:search-results",
+        errorEvent: "bind:search-failed",
+        eventBus: options.eventBus
+      },
+      this.logger
+    );
+  }
   /**
    * Subscribe to resource events (long-lived stream)
    *
@@ -556,8 +566,7 @@ var SSEClient = class {
    * ```
    */
   resourceEvents(resourceId, options) {
-    const id = this.extractId(resourceId);
-    const url = `${this.baseUrl}/resources/${id}/events/stream`;
+    const url = `${this.baseUrl}/resources/${resourceId}/events/stream`;
     const stream = createSSEStream(
       url,
       {
@@ -839,8 +848,8 @@ var SemiontApiClient = class {
       auth: options?.auth
     }).json();
   }
-  async getResource(resourceUri2, options) {
-    return this.http.get(resourceUri2, {
+  async getResource(id, options) {
+    return this.http.get(`${this.baseUrl}/resources/${id}`, {
       ...options,
       auth: options?.auth
     }).json();
@@ -867,8 +876,8 @@ var SemiontApiClient = class {
    * const { data, contentType } = await client.getResourceRepresentation(rUri, { accept: 'application/pdf', auth: token });
    * ```
    */
-  async getResourceRepresentation(resourceUri2, options) {
-    const response = await this.http.get(resourceUri2, {
+  async getResourceRepresentation(id, options) {
+    const response = await this.http.get(`${this.baseUrl}/resources/${id}`, {
       headers: {
         Accept: options?.accept || "text/plain"
       },
@@ -914,8 +923,8 @@ var SemiontApiClient = class {
    * }
    * ```
    */
-  async getResourceRepresentationStream(resourceUri2, options) {
-    const response = await this.http.get(resourceUri2, {
+  async getResourceRepresentationStream(id, options) {
+    const response = await this.http.get(`${this.baseUrl}/resources/${id}`, {
       headers: {
         Accept: options?.accept || "text/plain"
       },
@@ -938,46 +947,45 @@ var SemiontApiClient = class {
       auth: options?.auth
     }).json();
   }
-  async updateResource(resourceUri2, data, options) {
-    await this.http.patch(resourceUri2, {
+  async updateResource(id, data, options) {
+    await this.http.patch(`${this.baseUrl}/resources/${id}`, {
       json: data,
       ...options,
       auth: options?.auth
     }).text();
   }
-  async getResourceEvents(resourceUri2, options) {
-    return this.http.get(`${resourceUri2}/events`, {
+  async getResourceEvents(id, options) {
+    return this.http.get(`${this.baseUrl}/resources/${id}/events`, {
       ...options,
       auth: options?.auth
     }).json();
   }
-  async getResourceAnnotations(resourceUri2, options) {
-    return this.http.get(`${resourceUri2}/annotations`, {
+  async getResourceAnnotations(id, options) {
+    return this.http.get(`${this.baseUrl}/resources/${id}/annotations`, {
       ...options,
       auth: options?.auth
     }).json();
   }
-  async getAnnotationLLMContext(resourceUri2, annotationId, options) {
+  async getAnnotationLLMContext(resourceId, annotationId, options) {
     const searchParams = new URLSearchParams();
     if (options?.contextWindow) {
       searchParams.append("contextWindow", options.contextWindow.toString());
     }
     return this.http.get(
-      `${resourceUri2}/annotations/${annotationId}/llm-context`,
+      `${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}/llm-context`,
       {
         searchParams,
         auth: options?.auth
       }
     ).json();
   }
-  async getResourceReferencedBy(resourceUri2, options) {
-    return this.http.get(`${resourceUri2}/referenced-by`, {
+  async getResourceReferencedBy(id, options) {
+    return this.http.get(`${this.baseUrl}/resources/${id}/referenced-by`, {
       ...options,
       auth: options?.auth
     }).json();
   }
-  async generateCloneToken(resourceUri2, options) {
-    const id = resourceUri2.split("/").pop();
+  async generateCloneToken(id, options) {
     return this.http.post(`${this.baseUrl}/resources/${id}/clone-with-token`, {
       ...options,
       auth: options?.auth
@@ -999,52 +1007,53 @@ var SemiontApiClient = class {
   // ============================================================================
   // ANNOTATIONS
   // ============================================================================
-  async createAnnotation(resourceUri2, data, options) {
-    return this.http.post(`${resourceUri2}/annotations`, {
+  async createAnnotation(id, data, options) {
+    return this.http.post(`${this.baseUrl}/resources/${id}/annotations`, {
       json: data,
       ...options,
       auth: options?.auth
     }).json();
   }
-  async getAnnotation(annotationUri, options) {
-    return this.http.get(annotationUri, {
+  async getAnnotation(id, options) {
+    return this.http.get(`${this.baseUrl}/annotations/${id}`, {
       ...options,
       auth: options?.auth
     }).json();
   }
-  async getResourceAnnotation(annotationUri, options) {
-    return this.http.get(annotationUri, {
+  async getResourceAnnotation(resourceId, annotationId, options) {
+    return this.http.get(`${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}`, {
       ...options,
       auth: options?.auth
     }).json();
   }
-  async listAnnotations(resourceUri2, motivation, options) {
+  async listAnnotations(id, motivation, options) {
     const searchParams = new URLSearchParams();
     if (motivation) searchParams.append("motivation", motivation);
-    return this.http.get(`${resourceUri2}/annotations`, {
+    return this.http.get(`${this.baseUrl}/resources/${id}/annotations`, {
       searchParams,
       ...options,
       auth: options?.auth
     }).json();
   }
-  async deleteAnnotation(annotationUri, options) {
-    await this.http.delete(annotationUri, {
+  async deleteAnnotation(resourceId, annotationId, options) {
+    await this.http.delete(`${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}`, {
       ...options,
       auth: options?.auth
     });
   }
-  async updateAnnotationBody(annotationUri, data, options) {
-    await this.http.put(`${annotationUri}/body`, {
+  async updateAnnotationBody(resourceId, annotationId, data, options) {
+    await this.http.put(`${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}/body`, {
       json: data,
       ...options,
       auth: options?.auth
     });
   }
-  async getAnnotationHistory(annotationUri, options) {
+  async getAnnotationHistory(resourceId, annotationId, options) {
+    const url = `${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}/history`;
     if (options) {
-      return this.http.get(`${annotationUri}/history`, options).json();
+      return this.http.get(url, options).json();
     }
-    return this.http.get(`${annotationUri}/history`).json();
+    return this.http.get(url).json();
   }
   // ============================================================================
   // ENTITY TYPES
@@ -1102,6 +1111,113 @@ var SemiontApiClient = class {
     }).json();
   }
   // ============================================================================
+  // ADMIN — EXCHANGE (Backup/Restore)
+  // ============================================================================
+  /**
+   * Create a backup of the knowledge base. Returns raw Response for streaming download.
+   * 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}` } : {}
+      }
+    });
+  }
+  /**
+   * Restore knowledge base from a backup file. Parses SSE progress events and calls onProgress.
+   * Returns the final SSE event (phase: 'complete' or 'error').
+   */
+  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
+    });
+    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;
+  }
+  // ============================================================================
+  // ADMIN — EXCHANGE (Linked Data Export/Import)
+  // ============================================================================
+  /**
+   * Export the knowledge base as a JSON-LD Linked Data archive. Returns raw Response for streaming download.
+   * 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}` } : {}
+      }
+    });
+  }
+  /**
+   * Import a JSON-LD Linked Data archive into the knowledge base. Parses SSE progress events and calls onProgress.
+   * Returns the final SSE event (phase: 'complete' or 'error').
+   */
+  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
+    });
+    if (!response.ok) {
+      throw new Error(`Import 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;
+  }
+  // ============================================================================
   // JOB STATUS
   // ============================================================================
   async getJobStatus(id, options) {
@@ -1137,13 +1253,13 @@ var SemiontApiClient = class {
   // ============================================================================
   // LLM CONTEXT
   // ============================================================================
-  async getResourceLLMContext(resourceUri2, options) {
+  async getResourceLLMContext(id, options) {
     const searchParams = new URLSearchParams();
     if (options?.depth !== void 0) searchParams.append("depth", options.depth.toString());
     if (options?.maxResources !== void 0) searchParams.append("maxResources", options.maxResources.toString());
     if (options?.includeContent !== void 0) searchParams.append("includeContent", options.includeContent.toString());
     if (options?.includeSummary !== void 0) searchParams.append("includeSummary", options.includeSummary.toString());
-    return this.http.get(`${resourceUri2}/llm-context`, {
+    return this.http.get(`${this.baseUrl}/resources/${id}/llm-context`, {
       searchParams,
       auth: options?.auth
     }).json();
@@ -1336,7 +1452,7 @@ var EventBusClient = class {
   // ========================================================================
   // Gather Flow — LLM context
   // ========================================================================
-  async getAnnotationLLMContext(annotationUri, resourceUri2, options) {
+  async getAnnotationLLMContext(annotationId, resourceId, options) {
     const correlationId = crypto.randomUUID();
     const result$ = merge(
       this.eventBus.get("gather:complete").pipe(
@@ -1351,8 +1467,8 @@ var EventBusClient = class {
     const resultPromise = firstValueFrom(result$);
     this.eventBus.get("gather:requested").next({
       correlationId,
-      annotationUri,
-      resourceUri: resourceUri2,
+      annotationId,
+      resourceId,
       options
     });
     const result = await resultPromise;
@@ -1361,7 +1477,7 @@ var EventBusClient = class {
     }
     return result.response;
   }
-  async getResourceLLMContext(resourceUri2, options) {
+  async getResourceLLMContext(resourceId, options) {
     const correlationId = crypto.randomUUID();
     const result$ = merge(
       this.eventBus.get("gather:resource-complete").pipe(
@@ -1376,7 +1492,7 @@ var EventBusClient = class {
     const resultPromise = firstValueFrom(result$);
     this.eventBus.get("gather:resource-requested").next({
       correlationId,
-      resourceUri: resourceUri2,
+      resourceId,
       options
     });
     const result = await resultPromise;
@@ -1405,7 +1521,24 @@ var EventBusClient = class {
     this.eventBus.get("bind:search-requested").next({
       correlationId,
       referenceId,
-      searchTerm
+      context: {
+        annotation: {
+          "@context": "http://www.w3.org/ns/anno.jsonld",
+          type: "Annotation",
+          id: referenceId,
+          motivation: "linking",
+          target: referenceId,
+          body: []
+        },
+        sourceResource: {
+          "@context": "https://schema.org",
+          "@id": referenceId,
+          name: searchTerm,
+          format: "text/plain",
+          representations: []
+        },
+        sourceContext: { selected: searchTerm }
+      }
     });
     const result = await resultPromise;
     if (!result.ok) {
@@ -1421,7 +1554,7 @@ function getBodySource(body) {
         const itemType = item.type;
         const itemSource = item.source;
         if (itemType === "SpecificResource" && typeof itemSource === "string") {
-          return resourceUri(itemSource);
+          return itemSource;
         }
       }
     }
@@ -1431,7 +1564,7 @@ function getBodySource(body) {
     const bodyType = body.type;
     const bodySource = body.source;
     if (bodyType === "SpecificResource" && typeof bodySource === "string") {
-      return resourceUri(bodySource);
+      return bodySource;
     }
   }
   return null;
@@ -1462,9 +1595,9 @@ function isBodyResolved(body) {
 }
 function getTargetSource(target) {
   if (typeof target === "string") {
-    return resourceUri(target);
+    return target;
   }
-  return resourceUri(target.source);
+  return target.source;
 }
 function getTargetSelector(target) {
   if (typeof target === "string") {
@@ -1771,13 +1904,7 @@ function getAllLocaleCodes() {
 // src/utils/resources.ts
 function getResourceId(resource) {
   if (!resource) return void 0;
-  const fullId = resource["@id"];
-  if (fullId.includes("/resources/")) {
-    const parts = fullId.split("/resources/");
-    const lastPart = parts[parts.length - 1];
-    return lastPart || void 0;
-  }
-  return void 0;
+  return resource["@id"] || void 0;
 }
 function getPrimaryRepresentation(resource) {
   if (!resource?.representations) return void 0;