@semiont/api-client 0.2.46 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _semiont_core from '@semiont/core';
-import { EntityType, BaseUrl, Logger, ResourceUri, AccessToken, AnnotationUri, components, Email, paths, RefreshToken, GoogleCredential, ContentFormat, SearchQuery, CloneToken, ResourceAnnotationUri, Motivation, UserDID, JobId, EventBus, ResourceId, AnnotationId, UserId } from '@semiont/core';
+import { EntityType, GatheredContext, BaseUrl, Logger, ResourceId, AccessToken, AnnotationId, components, Email, paths, RefreshToken, GoogleCredential, ContentFormat, SearchQuery, CloneToken, Motivation, UserDID, JobId, EventBus, UserId } from '@semiont/core';
 export { Logger, Selector, getFragmentSelector, getSvgSelector, getTextPositionSelector, validateSvgMarkup } from '@semiont/core';
 export { BoundingBox, ContentCache, FragmentSelector, JWTTokenSchema, LOCALES, LocaleInfo, MatchQuality, Point, SvgSelector, TextPosition, TextPositionSelector, TextQuoteSelector, ValidatedAnnotation, ValidationFailure, ValidationResult, ValidationSuccess, buildContentCache, createCircleSvg, createPolygonSvg, createRectangleSvg, decodeRepresentation, decodeWithCharset, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findTextWithContext, formatLocaleDisplay, getAllLocaleCodes, getAnnotationExactText, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getNodeEncoding, getPrimaryMediaType, getPrimaryRepresentation, getPrimarySelector, getResourceEntityTypes, getResourceId, getStorageUri, getTargetSelector, getTargetSource, getTextQuoteSelector, hasTargetSelector, isArchived, isAssessment, isBodyResolved, isComment, isDraft, isHighlight, isReference, isResolvedReference, isStubReference, isTag, isValidEmail, normalizeCoordinates, normalizeText, parseSvgSelector, scaleSvgToNative, validateAndCorrectOffsets, validateData, verifyPosition } from './utils/index.js';
 
@@ -185,6 +185,15 @@ interface AnnotateTagsStreamRequest {
     schemaId: string;
     categories: string[];
 }
+/**
+ * Request body for bind search stream
+ */
+interface BindSearchStreamRequest {
+    referenceId: string;
+    context: GatheredContext;
+    limit?: number;
+    useSemanticScoring?: boolean;
+}
 /**
  * SSE Client configuration
  */
@@ -233,14 +242,6 @@ declare class SSEClient {
      * Get common headers for SSE requests
      */
     private getHeaders;
-    /**
-     * Extract resource ID from URI
-     *
-     * Handles both full URIs and plain IDs:
-     * - 'http://localhost:4000/resources/doc-123' -> 'doc-123'
-     * - 'doc-123' -> 'doc-123'
-     */
-    private extractId;
     /**
      * Detect annotations in a resource (streaming)
      *
@@ -276,7 +277,7 @@ declare class SSEClient {
      * stream.close();
      * ```
      */
-    annotateReferences(resourceId: ResourceUri, request: AnnotateReferencesStreamRequest, options: SSERequestOptions): SSEStream;
+    annotateReferences(resourceId: ResourceId, request: AnnotateReferencesStreamRequest, options: SSERequestOptions): SSEStream;
     /**
      * Generate resource from annotation (streaming)
      *
@@ -314,7 +315,7 @@ declare class SSEClient {
      * stream.close();
      * ```
      */
-    yieldResourceFromAnnotation(resourceId: ResourceUri, annotationId: AnnotationUri, request: YieldResourceStreamRequest, options: SSERequestOptions): SSEStream;
+    yieldResourceFromAnnotation(resourceId: ResourceId, annotationId: AnnotationId, request: YieldResourceStreamRequest, options: SSERequestOptions): SSEStream;
     /**
      * Detect highlights in a resource (streaming)
      *
@@ -350,7 +351,7 @@ declare class SSEClient {
      * stream.close();
      * ```
      */
-    annotateHighlights(resourceId: ResourceUri, request: AnnotateHighlightsStreamRequest | undefined, options: SSERequestOptions): SSEStream;
+    annotateHighlights(resourceId: ResourceId, request: AnnotateHighlightsStreamRequest | undefined, options: SSERequestOptions): SSEStream;
     /**
      * Detect assessments in a resource (streaming)
      *
@@ -386,7 +387,7 @@ declare class SSEClient {
      * stream.close();
      * ```
      */
-    annotateAssessments(resourceId: ResourceUri, request: AnnotateAssessmentsStreamRequest | undefined, options: SSERequestOptions): SSEStream;
+    annotateAssessments(resourceId: ResourceId, request: AnnotateAssessmentsStreamRequest | undefined, options: SSERequestOptions): SSEStream;
     /**
      * Detect comments in a resource (streaming)
      *
@@ -426,7 +427,7 @@ declare class SSEClient {
      * stream.close();
      * ```
      */
-    annotateComments(resourceId: ResourceUri, request: AnnotateCommentsStreamRequest | undefined, options: SSERequestOptions): SSEStream;
+    annotateComments(resourceId: ResourceId, request: AnnotateCommentsStreamRequest | undefined, options: SSERequestOptions): SSEStream;
     /**
      * Detect tags in a resource (streaming)
      *
@@ -467,7 +468,19 @@ declare class SSEClient {
      * stream.close();
      * ```
      */
-    annotateTags(resourceId: ResourceUri, request: AnnotateTagsStreamRequest, options: SSERequestOptions): SSEStream;
+    annotateTags(resourceId: ResourceId, request: AnnotateTagsStreamRequest, options: SSERequestOptions): SSEStream;
+    /**
+     * 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: ResourceId, request: BindSearchStreamRequest, options: SSERequestOptions): SSEStream;
     /**
      * Subscribe to resource events (long-lived stream)
      *
@@ -502,7 +515,7 @@ declare class SSEClient {
      * stream.close();
      * ```
      */
-    resourceEvents(resourceId: ResourceUri, options: SSERequestOptions & {
+    resourceEvents(resourceId: ResourceId, options: SSERequestOptions & {
         onConnected?: () => void;
     }): SSEStream;
     /**
@@ -652,7 +665,7 @@ declare class SemiontApiClient {
     }, options?: RequestOptions): Promise<{
         resourceId: string;
     }>;
-    getResource(resourceUri: ResourceUri, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}']['get']>>;
+    getResource(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
@@ -675,7 +688,7 @@ declare class SemiontApiClient {
      * const { data, contentType } = await client.getResourceRepresentation(rUri, { accept: 'application/pdf', auth: token });
      * ```
      */
-    getResourceRepresentation(resourceUri: ResourceUri, options?: {
+    getResourceRepresentation(id: ResourceId, options?: {
         accept?: ContentFormat;
         auth?: AccessToken;
     }): Promise<{
@@ -718,7 +731,7 @@ declare class SemiontApiClient {
      * }
      * ```
      */
-    getResourceRepresentationStream(resourceUri: ResourceUri, options?: {
+    getResourceRepresentationStream(id: ResourceId, options?: {
         accept?: ContentFormat;
         auth?: AccessToken;
     }): Promise<{
@@ -726,32 +739,32 @@ declare class SemiontApiClient {
         contentType: string;
     }>;
     listResources(limit?: number, archived?: boolean, query?: SearchQuery, options?: RequestOptions): Promise<ResponseContent<paths['/resources']['get']>>;
-    updateResource(resourceUri: ResourceUri, data: RequestContent<paths['/resources/{id}']['patch']>, options?: RequestOptions): Promise<void>;
-    getResourceEvents(resourceUri: ResourceUri, options?: RequestOptions): Promise<{
+    updateResource(id: ResourceId, data: RequestContent<paths['/resources/{id}']['patch']>, options?: RequestOptions): Promise<void>;
+    getResourceEvents(id: ResourceId, options?: RequestOptions): Promise<{
         events: any[];
     }>;
-    getResourceAnnotations(resourceUri: ResourceUri, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}/annotations']['get']>>;
-    getAnnotationLLMContext(resourceUri: ResourceUri, annotationId: string, options?: {
+    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(resourceUri: ResourceUri, options?: RequestOptions): Promise<{
+    getResourceReferencedBy(id: ResourceId, options?: RequestOptions): Promise<{
         referencedBy: any[];
     }>;
-    generateCloneToken(resourceUri: ResourceUri, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}/clone-with-token']['post']>>;
+    generateCloneToken(id: ResourceId, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}/clone-with-token']['post']>>;
     getResourceByToken(token: CloneToken, options?: RequestOptions): Promise<ResponseContent<paths['/api/clone-tokens/{token}']['get']>>;
     createResourceFromToken(data: RequestContent<paths['/api/clone-tokens/create-resource']['post']>, options?: RequestOptions): Promise<{
         resourceId: string;
     }>;
-    createAnnotation(resourceUri: ResourceUri, data: RequestContent<paths['/resources/{id}/annotations']['post']>, options?: RequestOptions): Promise<{
+    createAnnotation(id: ResourceId, data: RequestContent<paths['/resources/{id}/annotations']['post']>, options?: RequestOptions): Promise<{
         annotationId: string;
     }>;
-    getAnnotation(annotationUri: AnnotationUri, options?: RequestOptions): Promise<ResponseContent<paths['/annotations/{id}']['get']>>;
-    getResourceAnnotation(annotationUri: ResourceAnnotationUri, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{resourceId}/annotations/{annotationId}']['get']>>;
-    listAnnotations(resourceUri: ResourceUri, motivation?: Motivation, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}/annotations']['get']>>;
-    deleteAnnotation(annotationUri: ResourceAnnotationUri, options?: RequestOptions): Promise<void>;
-    updateAnnotationBody(annotationUri: ResourceAnnotationUri, data: RequestContent<paths['/resources/{resourceId}/annotations/{annotationId}/body']['put']>, options?: RequestOptions): Promise<void>;
-    getAnnotationHistory(annotationUri: ResourceAnnotationUri, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{resourceId}/annotations/{annotationId}/history']['get']>>;
+    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']>>;
+    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>;
+    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']>>;
@@ -763,6 +776,48 @@ declare class SemiontApiClient {
      */
     updateUser(id: UserDID, data: RequestContent<paths['/api/admin/users/{id}']['patch']>, options?: RequestOptions): Promise<ResponseContent<paths['/api/admin/users/{id}']['patch']>>;
     getOAuthConfig(options?: RequestOptions): Promise<ResponseContent<paths['/api/admin/oauth/config']['get']>>;
+    /**
+     * Create a backup of the knowledge base. Returns raw Response for streaming download.
+     * Caller should use response.blob() to trigger a file download.
+     */
+    backupKnowledgeBase(options?: RequestOptions): Promise<Response>;
+    /**
+     * Restore knowledge base from a backup file. Parses SSE progress events and calls onProgress.
+     * Returns the final SSE event (phase: 'complete' or 'error').
+     */
+    restoreKnowledgeBase(file: File, options?: RequestOptions & {
+        onProgress?: (event: {
+            phase: string;
+            message?: string;
+            result?: Record<string, unknown>;
+        }) => void;
+    }): Promise<{
+        phase: string;
+        message?: string;
+        result?: Record<string, unknown>;
+    }>;
+    /**
+     * 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.
+     */
+    exportKnowledgeBase(params?: {
+        includeArchived?: boolean;
+    }, options?: RequestOptions): Promise<Response>;
+    /**
+     * 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').
+     */
+    importKnowledgeBase(file: File, options?: RequestOptions & {
+        onProgress?: (event: {
+            phase: string;
+            message?: string;
+            result?: Record<string, unknown>;
+        }) => void;
+    }): Promise<{
+        phase: string;
+        message?: string;
+        result?: Record<string, unknown>;
+    }>;
     getJobStatus(id: JobId, options?: RequestOptions): Promise<ResponseContent<paths['/api/jobs/{id}']['get']>>;
     /**
      * Poll a job until it completes or fails
@@ -776,7 +831,7 @@ declare class SemiontApiClient {
         onProgress?: (status: ResponseContent<paths['/api/jobs/{id}']['get']>) => void;
         auth?: AccessToken;
     }): Promise<ResponseContent<paths['/api/jobs/{id}']['get']>>;
-    getResourceLLMContext(resourceUri: ResourceUri, options?: {
+    getResourceLLMContext(id: ResourceId, options?: {
         depth?: number;
         maxResources?: number;
         includeContent?: boolean;
@@ -844,12 +899,12 @@ declare class EventBusClient {
         resourceId: ResourceId;
     }>;
     getJobStatus(jobId: JobId): Promise<components['schemas']['JobStatusResponse']>;
-    getAnnotationLLMContext(annotationUri: string, resourceUri: string, options?: {
+    getAnnotationLLMContext(annotationId: AnnotationId, resourceId: ResourceId, options?: {
         includeSourceContext?: boolean;
         includeTargetContext?: boolean;
         contextWindow?: number;
     }): Promise<components['schemas']['AnnotationLLMContextResponse']>;
-    getResourceLLMContext(resourceUri: string, options: {
+    getResourceLLMContext(resourceId: ResourceId, options: {
         depth: number;
         maxResources: number;
         includeContent: boolean;
@@ -896,4 +951,4 @@ declare function isPdfMimeType(mimeType: string): boolean;
 type MimeCategory = 'text' | 'image' | 'unsupported';
 declare function getMimeCategory(mimeType: string): MimeCategory;
 
-export { APIError, type AnnotateReferencesStreamRequest, EventBusClient, type MimeCategory, type ReferenceDetectionProgress, type RequestOptions, SSEClient, type SSEClientConfig, type SSEStream, type SSEStreamConnected, SSE_STREAM_CONNECTED, SemiontApiClient, type SemiontApiClientConfig, type YieldProgress, type YieldResourceStreamRequest, getExtensionForMimeType, getMimeCategory, isImageMimeType, isPdfMimeType, isTextMimeType };
+export { APIError, type AnnotateReferencesStreamRequest, type BindSearchStreamRequest, EventBusClient, type MimeCategory, type ReferenceDetectionProgress, type RequestOptions, SSEClient, type SSEClientConfig, type SSEStream, type SSEStreamConnected, SSE_STREAM_CONNECTED, SemiontApiClient, type SemiontApiClientConfig, type YieldProgress, type YieldResourceStreamRequest, getExtensionForMimeType, getMimeCategory, isImageMimeType, isPdfMimeType, isTextMimeType };