@semiont/api-client 0.4.2 → 0.4.4

package/dist/index.d.ts

@@ -168,6 +168,8 @@ interface AnnotateAssessmentsStreamRequest {
     tone?: 'analytical' | 'critical' | 'balanced' | 'constructive';
     /** Desired number of assessments per 2000 words (1-10) */
     density?: number;
+    /** BCP 47 language tag for generated text (e.g. 'en', 'fr') */
+    language?: string;
 }
 /**
  * Request body for comment annotation stream
@@ -177,6 +179,8 @@ interface AnnotateCommentsStreamRequest {
     tone?: 'scholarly' | 'explanatory' | 'conversational' | 'technical';
     /** Desired number of comments per 2000 words (2-12) */
     density?: number;
+    /** BCP 47 language tag for generated text (e.g. 'en', 'fr') */
+    language?: string;
 }
 /**
  * Request body for tag annotation stream
@@ -185,6 +189,19 @@ interface AnnotateTagsStreamRequest {
     schemaId: string;
     categories: string[];
 }
+/**
+ * Request body for resource gather stream
+ */
+type GatherResourceStreamRequest = components['schemas']['GatherResourceStreamRequest'];
+/**
+ * Request body for annotation gather stream
+ */
+type GatherAnnotationStreamRequest = components['schemas']['GatherAnnotationStreamRequest'];
+/**
+ * Request body for bind annotation stream
+ * Uses generated type from OpenAPI schema
+ */
+type BindAnnotationStreamRequest = components['schemas']['BindAnnotationStreamRequest'];
 /**
  * Request body for bind search stream
  */
@@ -223,7 +240,7 @@ interface SSERequestOptions {
  *   baseUrl: 'http://localhost:4000'
  * });
  *
- * const stream = sseClient.annotateReferences(
+ * const stream = sseClient.markReferences(
  *   'http://localhost:4000/resources/doc-123',
  *   { entityTypes: ['Person', 'Organization'] },
  *   { auth: 'your-token' }
@@ -254,7 +271,7 @@ declare class SSEClient {
      *
      * @example
      * ```typescript
-     * const stream = sseClient.annotateReferences(
+     * const stream = sseClient.markReferences(
      *   'http://localhost:4000/resources/doc-123',
      *   { entityTypes: ['Person', 'Organization'] },
      *   { auth: 'your-token' }
@@ -277,7 +294,7 @@ declare class SSEClient {
      * stream.close();
      * ```
      */
-    annotateReferences(resourceId: ResourceId, request: AnnotateReferencesStreamRequest, options: SSERequestOptions): SSEStream;
+    markReferences(resourceId: ResourceId, request: AnnotateReferencesStreamRequest, options: SSERequestOptions): SSEStream;
     /**
      * Generate resource from annotation (streaming)
      *
@@ -291,7 +308,7 @@ declare class SSEClient {
      *
      * @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' },
@@ -315,7 +332,7 @@ declare class SSEClient {
      * stream.close();
      * ```
      */
-    yieldResourceFromAnnotation(resourceId: ResourceId, annotationId: AnnotationId, request: YieldResourceStreamRequest, options: SSERequestOptions): SSEStream;
+    yieldResource(resourceId: ResourceId, annotationId: AnnotationId, request: YieldResourceStreamRequest, options: SSERequestOptions): SSEStream;
     /**
      * Detect highlights in a resource (streaming)
      *
@@ -328,7 +345,7 @@ declare class SSEClient {
      *
      * @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' }
@@ -351,7 +368,7 @@ declare class SSEClient {
      * stream.close();
      * ```
      */
-    annotateHighlights(resourceId: ResourceId, request: AnnotateHighlightsStreamRequest | undefined, options: SSERequestOptions): SSEStream;
+    markHighlights(resourceId: ResourceId, request: AnnotateHighlightsStreamRequest | undefined, options: SSERequestOptions): SSEStream;
     /**
      * Detect assessments in a resource (streaming)
      *
@@ -364,7 +381,7 @@ declare class SSEClient {
      *
      * @example
      * ```typescript
-     * const stream = sseClient.annotateAssessments(
+     * const stream = sseClient.markAssessments(
      *   'http://localhost:4000/resources/doc-123',
      *   { instructions: 'Evaluate claims for accuracy' },
      *   { auth: 'your-token' }
@@ -387,7 +404,7 @@ declare class SSEClient {
      * stream.close();
      * ```
      */
-    annotateAssessments(resourceId: ResourceId, request: AnnotateAssessmentsStreamRequest | undefined, options: SSERequestOptions): SSEStream;
+    markAssessments(resourceId: ResourceId, request: AnnotateAssessmentsStreamRequest | undefined, options: SSERequestOptions): SSEStream;
     /**
      * Detect comments in a resource (streaming)
      *
@@ -402,7 +419,7 @@ declare class SSEClient {
      *
      * @example
      * ```typescript
-     * const stream = sseClient.annotateComments(
+     * const stream = sseClient.markComments(
      *   'http://localhost:4000/resources/doc-123',
      *   {
      *     instructions: 'Focus on technical terminology',
@@ -427,7 +444,7 @@ declare class SSEClient {
      * stream.close();
      * ```
      */
-    annotateComments(resourceId: ResourceId, request: AnnotateCommentsStreamRequest | undefined, options: SSERequestOptions): SSEStream;
+    markComments(resourceId: ResourceId, request: AnnotateCommentsStreamRequest | undefined, options: SSERequestOptions): SSEStream;
     /**
      * Detect tags in a resource (streaming)
      *
@@ -442,7 +459,7 @@ declare class SSEClient {
      *
      * @example
      * ```typescript
-     * const stream = sseClient.annotateTags(
+     * const stream = sseClient.markTags(
      *   'http://localhost:4000/resources/doc-123',
      *   {
      *     schemaId: 'legal-irac',
@@ -468,12 +485,47 @@ declare class SSEClient {
      * stream.close();
      * ```
      */
-    annotateTags(resourceId: ResourceId, request: AnnotateTagsStreamRequest, options: SSERequestOptions): SSEStream;
+    markTags(resourceId: ResourceId, request: AnnotateTagsStreamRequest, options: SSERequestOptions): SSEStream;
+    /**
+     * 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: ResourceId, request: GatherResourceStreamRequest, options: SSERequestOptions): SSEStream;
+    /**
+     * 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: ResourceId, annotationId: AnnotationId, request: GatherAnnotationStreamRequest, options: SSERequestOptions): SSEStream;
+    /**
+     * 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: ResourceId, annotationId: AnnotationId, request: BindAnnotationStreamRequest, options: SSERequestOptions): SSEStream;
     /**
      * 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)
@@ -545,6 +597,21 @@ declare class SSEClient {
     globalEvents(options: SSERequestOptions & {
         onConnected?: () => void;
     }): SSEStream;
+    /**
+     * 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: SSERequestOptions & {
+        onConnected?: () => void;
+    }): SSEStream;
 }
 
 /**
@@ -653,7 +720,7 @@ declare class SemiontApiClient {
      * @param data.sourceResourceId - Optional source resource ID
      * @param options - Request options including auth
      */
-    createResource(data: {
+    yieldResource(data: {
         name: string;
         file: File | Buffer;
         format: string;
@@ -666,7 +733,7 @@ declare class SemiontApiClient {
     }, options?: RequestOptions): Promise<{
         resourceId: string;
     }>;
-    getResource(id: ResourceId, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}']['get']>>;
+    browseResource(id: ResourceId, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}']['get']>>;
     /**
      * Get resource representation using W3C content negotiation
      * Returns raw binary content (images, PDFs, text, etc.) with content type
@@ -739,17 +806,12 @@ declare class SemiontApiClient {
         stream: ReadableStream<Uint8Array>;
         contentType: string;
     }>;
-    listResources(limit?: number, archived?: boolean, query?: SearchQuery, options?: RequestOptions): Promise<ResponseContent<paths['/resources']['get']>>;
+    browseResources(limit?: number, archived?: boolean, query?: SearchQuery, options?: RequestOptions): Promise<ResponseContent<paths['/resources']['get']>>;
     updateResource(id: ResourceId, data: RequestContent<paths['/resources/{id}']['patch']>, options?: RequestOptions): Promise<void>;
     getResourceEvents(id: ResourceId, options?: RequestOptions): Promise<{
         events: any[];
     }>;
-    getResourceAnnotations(id: ResourceId, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}/annotations']['get']>>;
-    getAnnotationLLMContext(resourceId: ResourceId, annotationId: AnnotationId, options?: {
-        contextWindow?: number;
-        auth?: AccessToken;
-    }): Promise<ResponseContent<paths['/resources/{resourceId}/annotations/{annotationId}/llm-context']['get']>>;
-    getResourceReferencedBy(id: ResourceId, options?: RequestOptions): Promise<{
+    browseReferences(id: ResourceId, options?: RequestOptions): Promise<{
         referencedBy: any[];
     }>;
     generateCloneToken(id: ResourceId, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}/clone-with-token']['post']>>;
@@ -757,18 +819,19 @@ declare class SemiontApiClient {
     createResourceFromToken(data: RequestContent<paths['/api/clone-tokens/create-resource']['post']>, options?: RequestOptions): Promise<{
         resourceId: string;
     }>;
-    createAnnotation(id: ResourceId, data: RequestContent<paths['/resources/{id}/annotations']['post']>, options?: RequestOptions): Promise<{
+    markAnnotation(id: ResourceId, data: RequestContent<paths['/resources/{id}/annotations']['post']>, options?: RequestOptions): Promise<{
         annotationId: string;
     }>;
     getAnnotation(id: AnnotationId, options?: RequestOptions): Promise<ResponseContent<paths['/annotations/{id}']['get']>>;
-    getResourceAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{resourceId}/annotations/{annotationId}']['get']>>;
-    listAnnotations(id: ResourceId, motivation?: Motivation, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}/annotations']['get']>>;
+    browseAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{resourceId}/annotations/{annotationId}']['get']>>;
+    browseAnnotations(id: ResourceId, motivation?: Motivation, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}/annotations']['get']>>;
     deleteAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options?: RequestOptions): Promise<void>;
-    updateAnnotationBody(resourceId: ResourceId, annotationId: AnnotationId, data: RequestContent<paths['/resources/{resourceId}/annotations/{annotationId}/body']['put']>, options?: RequestOptions): Promise<void>;
+    bindAnnotation(resourceId: ResourceId, annotationId: AnnotationId, data: RequestContent<paths['/resources/{resourceId}/annotations/{annotationId}/body']['put']>, options?: RequestOptions): Promise<void>;
     getAnnotationHistory(resourceId: ResourceId, annotationId: AnnotationId, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{resourceId}/annotations/{annotationId}/history']['get']>>;
     addEntityType(type: EntityType, options?: RequestOptions): Promise<void>;
     addEntityTypesBulk(types: EntityType[], options?: RequestOptions): Promise<void>;
     listEntityTypes(options?: RequestOptions): Promise<ResponseContent<paths['/api/entity-types']['get']>>;
+    beckonAttention(participantId: string, data: RequestContent<paths['/api/participants/{id}/attention']['post']>, options?: RequestOptions): Promise<ResponseContent<paths['/api/participants/{id}/attention']['post']>>;
     listUsers(options?: RequestOptions): Promise<ResponseContent<paths['/api/admin/users']['get']>>;
     getUserStats(options?: RequestOptions): Promise<ResponseContent<paths['/api/admin/users/stats']['get']>>;
     /**
@@ -832,15 +895,9 @@ declare class SemiontApiClient {
         onProgress?: (status: ResponseContent<paths['/api/jobs/{id}']['get']>) => void;
         auth?: AccessToken;
     }): Promise<ResponseContent<paths['/api/jobs/{id}']['get']>>;
-    getResourceLLMContext(id: ResourceId, options?: {
-        depth?: number;
-        maxResources?: number;
-        includeContent?: boolean;
-        includeSummary?: boolean;
-        auth?: AccessToken;
-    }): Promise<ResponseContent<paths['/resources/{id}/llm-context']['get']>>;
     healthCheck(options?: RequestOptions): Promise<ResponseContent<paths['/api/health']['get']>>;
     getStatus(options?: RequestOptions): Promise<ResponseContent<paths['/api/status']['get']>>;
+    browseFiles(dirPath?: string, sort?: 'name' | 'mtime' | 'annotationCount', options?: RequestOptions): Promise<ResponseContent<paths['/api/browse/files']['get']>>;
 }
 
 /**
@@ -860,8 +917,8 @@ declare class SemiontApiClient {
  * const eventBus = new EventBus();
  * const client = new EventBusClient(eventBus);
  *
- * const resources = await client.listResources({ limit: 10 });
- * const resource = await client.getResource(resourceId('doc-123'));
+ * const resources = await client.browseResources({ limit: 10 });
+ * const resource = await client.browseResource(resourceId('doc-123'));
  * ```
  */
 
@@ -869,8 +926,8 @@ declare class EventBusClient {
     private eventBus;
     private timeoutMs;
     constructor(eventBus: EventBus, timeoutMs?: number);
-    getResource(resourceId: ResourceId): Promise<components['schemas']['GetResourceResponse']>;
-    listResources(options?: {
+    browseResource(resourceId: ResourceId): Promise<components['schemas']['GetResourceResponse']>;
+    browseResources(options?: {
         search?: string;
         archived?: boolean;
         entityType?: string;
@@ -900,12 +957,12 @@ declare class EventBusClient {
         resourceId: ResourceId;
     }>;
     getJobStatus(jobId: JobId): Promise<components['schemas']['JobStatusResponse']>;
-    getAnnotationLLMContext(annotationId: AnnotationId, resourceId: ResourceId, options?: {
+    gatherAnnotation(annotationId: AnnotationId, resourceId: ResourceId, options?: {
         includeSourceContext?: boolean;
         includeTargetContext?: boolean;
         contextWindow?: number;
     }): Promise<components['schemas']['AnnotationLLMContextResponse']>;
-    getResourceLLMContext(resourceId: ResourceId, options: {
+    gatherResource(resourceId: ResourceId, options: {
         depth: number;
         maxResources: number;
         includeContent: boolean;