@semiont/api-client 0.4.2 → 0.4.4

package/dist/index.js

@@ -179,7 +179,7 @@ var SSEClient = class {
    *
    * @example
    * ```typescript
-   * const stream = sseClient.annotateReferences(
+   * const stream = sseClient.markReferences(
    *   'http://localhost:4000/resources/doc-123',
    *   { entityTypes: ['Person', 'Organization'] },
    *   { auth: 'your-token' }
@@ -202,7 +202,7 @@ var SSEClient = class {
    * stream.close();
    * ```
    */
-  annotateReferences(resourceId, request, options) {
+  markReferences(resourceId, request, options) {
     const url = `${this.baseUrl}/resources/${resourceId}/annotate-references-stream`;
     return createSSEStream(
       url,
@@ -234,7 +234,7 @@ var SSEClient = class {
    *
    * @example
    * ```typescript
-   * const stream = sseClient.yieldResourceFromAnnotation(
+   * const stream = sseClient.yieldResource(
    *   'http://localhost:4000/resources/doc-123',
    *   'http://localhost:4000/annotations/ann-456',
    *   { language: 'es', title: 'Spanish Summary' },
@@ -258,7 +258,7 @@ var SSEClient = class {
    * stream.close();
    * ```
    */
-  yieldResourceFromAnnotation(resourceId, annotationId, request, options) {
+  yieldResource(resourceId, annotationId, request, options) {
     const url = `${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}/yield-resource-stream`;
     return createSSEStream(
       url,
@@ -289,7 +289,7 @@ var SSEClient = class {
    *
    * @example
    * ```typescript
-   * const stream = sseClient.annotateHighlights(
+   * const stream = sseClient.markHighlights(
    *   'http://localhost:4000/resources/doc-123',
    *   { instructions: 'Focus on key technical points' },
    *   { auth: 'your-token' }
@@ -312,7 +312,7 @@ var SSEClient = class {
    * stream.close();
    * ```
    */
-  annotateHighlights(resourceId, request = {}, options) {
+  markHighlights(resourceId, request = {}, options) {
     const url = `${this.baseUrl}/resources/${resourceId}/annotate-highlights-stream`;
     return createSSEStream(
       url,
@@ -343,7 +343,7 @@ var SSEClient = class {
    *
    * @example
    * ```typescript
-   * const stream = sseClient.annotateAssessments(
+   * const stream = sseClient.markAssessments(
    *   'http://localhost:4000/resources/doc-123',
    *   { instructions: 'Evaluate claims for accuracy' },
    *   { auth: 'your-token' }
@@ -366,7 +366,7 @@ var SSEClient = class {
    * stream.close();
    * ```
    */
-  annotateAssessments(resourceId, request = {}, options) {
+  markAssessments(resourceId, request = {}, options) {
     const url = `${this.baseUrl}/resources/${resourceId}/annotate-assessments-stream`;
     return createSSEStream(
       url,
@@ -399,7 +399,7 @@ var SSEClient = class {
    *
    * @example
    * ```typescript
-   * const stream = sseClient.annotateComments(
+   * const stream = sseClient.markComments(
    *   'http://localhost:4000/resources/doc-123',
    *   {
    *     instructions: 'Focus on technical terminology',
@@ -424,7 +424,7 @@ var SSEClient = class {
    * stream.close();
    * ```
    */
-  annotateComments(resourceId, request = {}, options) {
+  markComments(resourceId, request = {}, options) {
     const url = `${this.baseUrl}/resources/${resourceId}/annotate-comments-stream`;
     return createSSEStream(
       url,
@@ -457,7 +457,7 @@ var SSEClient = class {
    *
    * @example
    * ```typescript
-   * const stream = sseClient.annotateTags(
+   * const stream = sseClient.markTags(
    *   'http://localhost:4000/resources/doc-123',
    *   {
    *     schemaId: 'legal-irac',
@@ -483,7 +483,7 @@ var SSEClient = class {
    * stream.close();
    * ```
    */
-  annotateTags(resourceId, request, options) {
+  markTags(resourceId, request, options) {
     const url = `${this.baseUrl}/resources/${resourceId}/annotate-tags-stream`;
     return createSSEStream(
       url,
@@ -502,11 +502,100 @@ var SSEClient = class {
       this.logger
     );
   }
+  /**
+   * Gather LLM context for a resource (streaming)
+   *
+   * Streams resource LLM context gathering progress via Server-Sent Events.
+   *
+   * @param resourceId - Resource URI or ID
+   * @param request - Gather configuration (depth, maxResources, includeContent, includeSummary)
+   * @param options - Request options (auth token, eventBus)
+   * @returns SSE stream controller with progress/complete/error callbacks
+   */
+  gatherResource(resourceId, request, options) {
+    const url = `${this.baseUrl}/resources/${resourceId}/gather-resource-stream`;
+    return createSSEStream(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(options.auth),
+        body: JSON.stringify(request)
+      },
+      {
+        progressEvents: ["gather:progress"],
+        completeEvent: "gather:finished",
+        errorEvent: "gather:failed",
+        eventBus: options.eventBus,
+        eventPrefix: void 0
+      },
+      this.logger
+    );
+  }
+  /**
+   * Gather LLM context for an annotation (streaming)
+   *
+   * Streams annotation LLM context gathering progress via Server-Sent Events.
+   *
+   * @param resourceId - Resource URI or ID
+   * @param annotationId - Annotation URI or ID
+   * @param request - Gather configuration (contextWindow)
+   * @param options - Request options (auth token, eventBus)
+   * @returns SSE stream controller with progress/complete/error callbacks
+   */
+  gatherAnnotation(resourceId, annotationId, request, options) {
+    const url = `${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}/gather-annotation-stream`;
+    return createSSEStream(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(options.auth),
+        body: JSON.stringify(request)
+      },
+      {
+        progressEvents: ["gather:annotation-progress"],
+        completeEvent: "gather:annotation-finished",
+        errorEvent: "gather:failed",
+        eventBus: options.eventBus,
+        eventPrefix: void 0
+      },
+      this.logger
+    );
+  }
+  /**
+   * Bind annotation body (streaming)
+   *
+   * Applies annotation body operations and streams completion via Server-Sent Events.
+   *
+   * @param resourceId - Resource URI or ID
+   * @param annotationId - Annotation URI or ID
+   * @param request - Bind operations (resourceId + operations array)
+   * @param options - Request options (auth token, eventBus)
+   * @returns SSE stream controller with complete/error callbacks
+   */
+  bindAnnotation(resourceId, annotationId, request, options) {
+    const url = `${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}/bind-stream`;
+    return createSSEStream(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(options.auth),
+        body: JSON.stringify(request)
+      },
+      {
+        progressEvents: [],
+        completeEvent: "bind:finished",
+        errorEvent: "bind:failed",
+        eventBus: options.eventBus,
+        eventPrefix: void 0
+      },
+      this.logger
+    );
+  }
   /**
    * Search for binding candidates (streaming)
    *
-   * Bridges bind:search-requested to the backend Matcher actor via SSE.
-   * Results emit as bind:search-results on the browser EventBus.
+   * Bridges match:search-requested to the backend Matcher actor via SSE.
+   * Results emit as match:search-results on the browser EventBus.
    *
    * @param resourceId - Resource the annotation belongs to
    * @param request - Search configuration (referenceId, context, limit)
@@ -524,8 +613,8 @@ var SSEClient = class {
       },
       {
         progressEvents: [],
-        completeEvent: "bind:search-results",
-        errorEvent: "bind:search-failed",
+        completeEvent: "match:search-results",
+        errorEvent: "match:search-failed",
         eventBus: options.eventBus
       },
       this.logger
@@ -640,6 +729,42 @@ var SSEClient = class {
     }
     return stream;
   }
+  /**
+   * Subscribe to participant attention stream (long-lived stream)
+   *
+   * Opens a participant-scoped SSE connection to receive cross-participant
+   * beckon signals. Signals are delivered as 'beckon:focus' events routed
+   * to the EventBus — the existing scroll/highlight machinery handles them.
+   *
+   * Signals are ephemeral — delivered if connected, dropped if not.
+   *
+   * @param options - Request options (auth token, eventBus)
+   * @returns SSE stream controller
+   */
+  attentionStream(options) {
+    const url = `${this.baseUrl}/api/participants/me/attention-stream`;
+    const stream = createSSEStream(
+      url,
+      {
+        method: "GET",
+        headers: this.getHeaders(options.auth)
+      },
+      {
+        progressEvents: ["*"],
+        completeEvent: null,
+        errorEvent: null,
+        eventBus: options.eventBus
+      },
+      this.logger
+    );
+    if (options.onConnected) {
+      const sub = options.eventBus.get(SSE_STREAM_CONNECTED).subscribe(() => {
+        options.onConnected();
+        sub.unsubscribe();
+      });
+    }
+    return stream;
+  }
 };
 
 // src/client.ts
@@ -815,7 +940,7 @@ var SemiontApiClient = class {
    * @param data.sourceResourceId - Optional source resource ID
    * @param options - Request options including auth
    */
-  async createResource(data, options) {
+  async yieldResource(data, options) {
     const formData = new FormData();
     formData.append("name", data.name);
     formData.append("format", data.format);
@@ -849,7 +974,7 @@ var SemiontApiClient = class {
       auth: options?.auth
     }).json();
   }
-  async getResource(id, options) {
+  async browseResource(id, options) {
     return this.http.get(`${this.baseUrl}/resources/${id}`, {
       ...options,
       auth: options?.auth
@@ -937,7 +1062,7 @@ var SemiontApiClient = class {
     }
     return { stream: response.body, contentType };
   }
-  async listResources(limit, archived, query, options) {
+  async browseResources(limit, archived, query, options) {
     const searchParams = new URLSearchParams();
     if (limit) searchParams.append("limit", limit.toString());
     if (archived !== void 0) searchParams.append("archived", archived.toString());
@@ -961,26 +1086,7 @@ var SemiontApiClient = class {
       auth: options?.auth
     }).json();
   }
-  async getResourceAnnotations(id, options) {
-    return this.http.get(`${this.baseUrl}/resources/${id}/annotations`, {
-      ...options,
-      auth: options?.auth
-    }).json();
-  }
-  async getAnnotationLLMContext(resourceId, annotationId, options) {
-    const searchParams = new URLSearchParams();
-    if (options?.contextWindow) {
-      searchParams.append("contextWindow", options.contextWindow.toString());
-    }
-    return this.http.get(
-      `${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}/llm-context`,
-      {
-        searchParams,
-        auth: options?.auth
-      }
-    ).json();
-  }
-  async getResourceReferencedBy(id, options) {
+  async browseReferences(id, options) {
     return this.http.get(`${this.baseUrl}/resources/${id}/referenced-by`, {
       ...options,
       auth: options?.auth
@@ -1008,7 +1114,7 @@ var SemiontApiClient = class {
   // ============================================================================
   // ANNOTATIONS
   // ============================================================================
-  async createAnnotation(id, data, options) {
+  async markAnnotation(id, data, options) {
     return this.http.post(`${this.baseUrl}/resources/${id}/annotations`, {
       json: data,
       ...options,
@@ -1021,13 +1127,13 @@ var SemiontApiClient = class {
       auth: options?.auth
     }).json();
   }
-  async getResourceAnnotation(resourceId, annotationId, options) {
+  async browseAnnotation(resourceId, annotationId, options) {
     return this.http.get(`${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}`, {
       ...options,
       auth: options?.auth
     }).json();
   }
-  async listAnnotations(id, motivation, options) {
+  async browseAnnotations(id, motivation, options) {
     const searchParams = new URLSearchParams();
     if (motivation) searchParams.append("motivation", motivation);
     return this.http.get(`${this.baseUrl}/resources/${id}/annotations`, {
@@ -1042,7 +1148,7 @@ var SemiontApiClient = class {
       auth: options?.auth
     });
   }
-  async updateAnnotationBody(resourceId, annotationId, data, options) {
+  async bindAnnotation(resourceId, annotationId, data, options) {
     await this.http.put(`${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}/body`, {
       json: data,
       ...options,
@@ -1080,6 +1186,16 @@ var SemiontApiClient = class {
     }).json();
   }
   // ============================================================================
+  // PARTICIPANTS
+  // ============================================================================
+  async beckonAttention(participantId, data, options) {
+    return this.http.post(`${this.baseUrl}/api/participants/${participantId}/attention`, {
+      json: data,
+      ...options,
+      auth: options?.auth
+    }).json();
+  }
+  // ============================================================================
   // ADMIN
   // ============================================================================
   async listUsers(options) {
@@ -1252,20 +1368,6 @@ var SemiontApiClient = class {
     }
   }
   // ============================================================================
-  // LLM CONTEXT
-  // ============================================================================
-  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(`${this.baseUrl}/resources/${id}/llm-context`, {
-      searchParams,
-      auth: options?.auth
-    }).json();
-  }
-  // ============================================================================
   // SYSTEM STATUS
   // ============================================================================
   async healthCheck(options) {
@@ -1280,6 +1382,16 @@ var SemiontApiClient = class {
     }
     return this.http.get(`${this.baseUrl}/api/status`).json();
   }
+  async browseFiles(dirPath, sort, options) {
+    const searchParams = new URLSearchParams();
+    if (dirPath) searchParams.append("path", dirPath);
+    if (sort) searchParams.append("sort", sort);
+    return this.http.get(`${this.baseUrl}/api/browse/files`, {
+      searchParams,
+      ...options,
+      auth: options?.auth
+    }).json();
+  }
 };
 async function eventBusRequest(eventBus, requestEvent, payload, successEvent, failureEvent, timeoutMs = 3e4) {
   const correlationId = payload.correlationId;
@@ -1309,7 +1421,7 @@ var EventBusClient = class {
   // ========================================================================
   // Browse Flow — Resource reads
   // ========================================================================
-  async getResource(resourceId) {
+  async browseResource(resourceId) {
     return eventBusRequest(
       this.eventBus,
       "browse:resource-requested",
@@ -1319,7 +1431,7 @@ var EventBusClient = class {
       this.timeoutMs
     );
   }
-  async listResources(options) {
+  async browseResources(options) {
     return eventBusRequest(
       this.eventBus,
       "browse:resources-requested",
@@ -1381,10 +1493,10 @@ var EventBusClient = class {
   async getReferencedBy(resourceId, motivation) {
     return eventBusRequest(
       this.eventBus,
-      "bind:referenced-by-requested",
+      "browse:referenced-by-requested",
       { correlationId: crypto.randomUUID(), resourceId, motivation },
-      "bind:referenced-by-result",
-      "bind:referenced-by-failed",
+      "browse:referenced-by-result",
+      "browse:referenced-by-failed",
       this.timeoutMs
     );
   }
@@ -1394,10 +1506,10 @@ var EventBusClient = class {
   async listEntityTypes() {
     return eventBusRequest(
       this.eventBus,
-      "mark:entity-types-requested",
+      "browse:entity-types-requested",
       { correlationId: crypto.randomUUID() },
-      "mark:entity-types-result",
-      "mark:entity-types-failed",
+      "browse:entity-types-result",
+      "browse:entity-types-failed",
       this.timeoutMs
     );
   }
@@ -1453,7 +1565,7 @@ var EventBusClient = class {
   // ========================================================================
   // Gather Flow — LLM context
   // ========================================================================
-  async getAnnotationLLMContext(annotationId, resourceId, options) {
+  async gatherAnnotation(annotationId, resourceId, options) {
     const correlationId = crypto.randomUUID();
     const result$ = merge(
       this.eventBus.get("gather:complete").pipe(
@@ -1478,7 +1590,7 @@ var EventBusClient = class {
     }
     return result.response;
   }
-  async getResourceLLMContext(resourceId, options) {
+  async gatherResource(resourceId, options) {
     const correlationId = crypto.randomUUID();
     const result$ = merge(
       this.eventBus.get("gather:resource-complete").pipe(
@@ -1509,17 +1621,17 @@ var EventBusClient = class {
     const correlationId = crypto.randomUUID();
     const referenceId = correlationId;
     const result$ = merge(
-      this.eventBus.get("bind:search-results").pipe(
+      this.eventBus.get("match:search-results").pipe(
         filter((e) => e.correlationId === correlationId),
         map((e) => ({ ok: true, results: e.results }))
       ),
-      this.eventBus.get("bind:search-failed").pipe(
+      this.eventBus.get("match:search-failed").pipe(
         filter((e) => e.correlationId === correlationId),
         map((e) => ({ ok: false, error: e.error }))
       )
     ).pipe(take(1), timeout(this.timeoutMs));
     const resultPromise = firstValueFrom(result$);
-    this.eventBus.get("bind:search-requested").next({
+    this.eventBus.get("match:search-requested").next({
       correlationId,
       referenceId,
       context: {