@semiont/api-client 0.4.7 → 0.4.10

package/README.md

@@ -143,6 +143,8 @@ const client = new SemiontApiClient({
 
 🛠️ **[Utilities Guide](./docs/Utilities.md)** - Text encoding, fuzzy anchoring, SVG utilities
 
+🗄️ **[Observable Stores](./docs/STORES.md)** - Reactive resource and annotation caches, EventBus-driven invalidation, React integration
+
 ## Key Features
 
 - **Two clients** - HTTP (`SemiontApiClient`) and EventBus (`EventBusClient`) for the same operations

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import * as _semiont_core 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';
+import { EntityType, BaseUrl, Logger, ResourceId, AccessToken, AnnotationId, components, EventBus, paths, Email, RefreshToken, GoogleCredential, ContentFormat, SearchQuery, CloneToken, Motivation, UserDID, JobId, UserId } from '@semiont/core';
 export { Logger, Selector, getFragmentSelector, getSvgSelector, getTextPositionSelector, validateSvgMarkup } from '@semiont/core';
+import { Subscription, Observable } from 'rxjs';
 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';
 
 /**
@@ -203,14 +204,9 @@ type GatherAnnotationStreamRequest = components['schemas']['GatherAnnotationStre
  */
 type BindAnnotationStreamRequest = components['schemas']['BindAnnotationStreamRequest'];
 /**
- * Request body for bind search stream
+ * Request body for match search stream
  */
-interface BindSearchStreamRequest {
-    referenceId: string;
-    context: GatheredContext;
-    limit?: number;
-    useSemanticScoring?: boolean;
-}
+type MatchSearchStreamRequest = components['schemas']['MatchSearchStreamRequest'];
 /**
  * SSE Client configuration
  */
@@ -532,7 +528,7 @@ declare class SSEClient {
      * @param options - Request options (auth token, eventBus)
      * @returns SSE stream controller
      */
-    bindSearch(resourceId: ResourceId, request: BindSearchStreamRequest, options: SSERequestOptions): SSEStream;
+    matchSearch(resourceId: ResourceId, request: MatchSearchStreamRequest, options: SSERequestOptions): SSEStream;
     /**
      * Subscribe to resource events (long-lived stream)
      *
@@ -614,6 +610,208 @@ declare class SSEClient {
     }): SSEStream;
 }
 
+/**
+ * FlowEngine — framework-agnostic flow orchestration
+ *
+ * Owns the subscription/SSE-bridge logic that was previously scattered across
+ * React hooks (useBindFlow, useYieldFlow, useMarkFlow, useContextGatherFlow,
+ * useResourceEvents, useAttentionStream).
+ *
+ * Each method accepts a `getToken` function called at event-handling time so
+ * the token is always fresh (the client is stateless; tokens rotate).
+ *
+ * Each method returns an RxJS Subscription. The caller is responsible for
+ * calling .unsubscribe() when the flow is no longer needed (e.g. in a
+ * React useEffect cleanup or on workspace teardown).
+ *
+ * No React imports. No DOM imports. Pure RxJS + EventBus.
+ */
+
+type TokenGetter$2 = () => AccessToken | undefined;
+declare class FlowEngine {
+    private readonly eventBus;
+    private readonly sse;
+    private readonly http;
+    constructor(eventBus: EventBus, sse: SSEClient, http: SemiontApiClient);
+    /**
+     * 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: ResourceId, getToken: TokenGetter$2): Subscription;
+    /**
+     * 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: ResourceId, getToken: TokenGetter$2): Subscription;
+    /**
+     * 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: ResourceId, getToken: TokenGetter$2): Subscription;
+    /**
+     * 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: ResourceId, getToken: TokenGetter$2): Subscription;
+    /**
+     * Open the long-lived resource-events SSE stream.
+     * Returns a Subscription whose teardown closes the stream.
+     */
+    resourceEvents(rUri: ResourceId, getToken: TokenGetter$2): Subscription;
+    /**
+     * Open the long-lived participant attention SSE stream.
+     * Returns a Subscription whose teardown closes the stream.
+     */
+    attentionStream(getToken: TokenGetter$2): Subscription;
+}
+
+/**
+ * ResourceStore — per-workspace observable resource cache
+ *
+ * BehaviorSubject-backed store that:
+ * - Populates lazily on first subscribe (no up-front fetch)
+ * - Updates reactively when EventBus events arrive (no manual invalidation)
+ * - Is readable from outside React
+ *
+ * EventBus events handled:
+ * - yield:created       → fetch new resource into map, invalidate lists
+ * - mark:archived       → invalidate resource detail + lists
+ * - mark:unarchived     → invalidate resource detail + lists
+ * - mark:entity-tag-added / mark:entity-tag-removed → invalidate resource detail
+ *
+ * Token: mutable — call setTokenGetter() from the React layer when auth changes.
+ */
+
+type ResponseContent$2<T> = T extends {
+    responses: {
+        200: {
+            content: {
+                'application/json': infer R;
+            };
+        };
+    };
+} ? R : never;
+type ResourceDetail = ResponseContent$2<paths['/resources/{id}']['get']>;
+type ResourceListResponse = ResponseContent$2<paths['/resources']['get']>;
+type TokenGetter$1 = () => AccessToken | undefined;
+declare class ResourceStore {
+    private readonly http;
+    /** Cache of individual resource details, keyed by ResourceId */
+    private readonly detail$;
+    /** Cache of list responses, keyed by a serialized options string */
+    private readonly list$;
+    /** Track in-flight fetches to avoid duplicate requests */
+    private readonly fetchingDetail;
+    private readonly fetchingList;
+    /** Memoized Observables — same instance returned for the same key */
+    private readonly detailObs$;
+    private readonly listObs$;
+    /** Mutable token getter — updated from the React layer when auth changes */
+    private getToken;
+    /** Update the token getter (called from React when auth token changes) */
+    setTokenGetter(getter: TokenGetter$1): void;
+    constructor(http: SemiontApiClient, eventBus: EventBus);
+    /**
+     * Get a single resource by ID as an Observable.
+     * Triggers a fetch if not cached.
+     */
+    get(id: ResourceId): Observable<ResourceDetail | undefined>;
+    /**
+     * List resources as an Observable.
+     * Triggers a fetch if not cached.
+     */
+    list(options?: {
+        limit?: number;
+        archived?: boolean;
+    }): Observable<ResourceListResponse | undefined>;
+    /** Invalidate and re-fetch a specific resource detail */
+    invalidateDetail(id: ResourceId): void;
+    /** Remove all list caches (triggers re-fetch on next subscribe) */
+    invalidateLists(): void;
+    private fetchDetail;
+    private fetchList;
+}
+
+/**
+ * AnnotationStore — per-workspace observable annotation cache
+ *
+ * BehaviorSubject-backed store that:
+ * - Populates lazily on first subscribe (no up-front fetch)
+ * - Updates reactively when EventBus events arrive (no manual invalidation)
+ * - Is readable from outside React
+ *
+ * EventBus events handled:
+ * - mark:deleted      → remove from detail cache
+ * - mark:added        → invalidate annotation list (SSE domain event; resourceId on BaseEvent)
+ * - mark:removed      → invalidate annotation list + detail (SSE domain event)
+ * - mark:body-updated → invalidate annotation list + detail (SSE domain event)
+ * - mark:entity-tag-added / mark:entity-tag-removed → invalidate list for resource
+ *
+ * Token: mutable — call setTokenGetter() from the React layer when auth changes.
+ */
+
+type ResponseContent$1<T> = T extends {
+    responses: {
+        200: {
+            content: {
+                'application/json': infer R;
+            };
+        };
+    };
+} ? R : never;
+type AnnotationsListResponse = ResponseContent$1<paths['/resources/{id}/annotations']['get']>;
+type AnnotationDetail = ResponseContent$1<paths['/resources/{resourceId}/annotations/{annotationId}']['get']>;
+type TokenGetter = () => AccessToken | undefined;
+declare class AnnotationStore {
+    private readonly http;
+    /** Annotation list responses keyed by ResourceId */
+    private readonly list$;
+    /** Individual annotation details keyed by AnnotationId */
+    private readonly detail$;
+    /** Track in-flight fetches */
+    private readonly fetchingList;
+    private readonly fetchingDetail;
+    /** Memoized Observables — same instance returned for the same key */
+    private readonly listObs$;
+    private readonly detailObs$;
+    /** Mutable token getter — updated from the React layer when auth changes */
+    private getToken;
+    /** Update the token getter (called from React when auth token changes) */
+    setTokenGetter(getter: TokenGetter): void;
+    constructor(http: SemiontApiClient, eventBus: EventBus);
+    /**
+     * Get annotations for a resource as an Observable.
+     * Triggers a fetch if not cached.
+     */
+    listForResource(resourceId: ResourceId): Observable<AnnotationsListResponse | undefined>;
+    /**
+     * Get a single annotation detail as an Observable.
+     * Triggers a fetch if not cached.
+     */
+    get(resourceId: ResourceId, annotationId: AnnotationId): Observable<AnnotationDetail | undefined>;
+    /** Invalidate and re-fetch a resource's annotation list */
+    invalidateList(resourceId: ResourceId): void;
+    /** Invalidate a single annotation detail (re-fetched on next subscribe) */
+    invalidateDetail(annotationId: AnnotationId): void;
+    /** Remove an annotation from the detail cache without re-fetching */
+    private removeFromDetailCache;
+    private fetchList;
+    private fetchDetail;
+}
+
 /**
  * Common API client for Semiont backend
  *
@@ -657,6 +855,8 @@ declare class APIError extends Error {
 }
 interface SemiontApiClientConfig {
     baseUrl: BaseUrl;
+    /** Per-workspace EventBus. Required — one bus per workspace, constructed externally. */
+    eventBus: EventBus;
     timeout?: number;
     retry?: number;
     logger?: Logger;
@@ -676,33 +876,40 @@ interface RequestOptions {
  */
 declare class SemiontApiClient {
     private http;
-    private baseUrl;
+    readonly baseUrl: BaseUrl;
+    /** The workspace-scoped EventBus this client was constructed with. */
+    readonly eventBus: EventBus;
     private 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();
-     * ```
      */
     readonly sse: SSEClient;
+    /**
+     * Framework-agnostic flow orchestration.
+     * Each method returns a Subscription; call .unsubscribe() to tear down.
+     */
+    readonly flows: FlowEngine;
+    /**
+     * Per-workspace observable stores for entity data.
+     * Call stores.resources.setTokenGetter() / stores.annotations.setTokenGetter()
+     * from the React layer when the auth token changes.
+     */
+    readonly stores: {
+        resources: ResourceStore;
+        annotations: AnnotationStore;
+    };
     constructor(config: SemiontApiClientConfig);
+    private authHeaders;
     authenticatePassword(email: Email, password: string, options?: RequestOptions): Promise<ResponseContent<paths['/api/tokens/password']['post']>>;
     refreshToken(token: RefreshToken, options?: RequestOptions): Promise<ResponseContent<paths['/api/tokens/refresh']['post']>>;
     authenticateGoogle(credential: GoogleCredential, options?: RequestOptions): Promise<ResponseContent<paths['/api/tokens/google']['post']>>;
     generateMCPToken(options?: RequestOptions): Promise<ResponseContent<paths['/api/tokens/mcp-generate']['post']>>;
+    getMediaToken(resourceId: ResourceId, options?: RequestOptions): Promise<{
+        token: string;
+    }>;
     getMe(options?: RequestOptions): Promise<ResponseContent<paths['/api/users/me']['get']>>;
     acceptTerms(options?: RequestOptions): Promise<ResponseContent<paths['/api/users/accept-terms']['post']>>;
     logout(options?: RequestOptions): Promise<ResponseContent<paths['/api/users/logout']['post']>>;
@@ -808,12 +1015,8 @@ declare class SemiontApiClient {
     }>;
     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[];
-    }>;
-    browseReferences(id: ResourceId, options?: RequestOptions): Promise<{
-        referencedBy: any[];
-    }>;
+    getResourceEvents(id: ResourceId, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}/events']['get']>>;
+    browseReferences(id: ResourceId, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}/referenced-by']['get']>>;
     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<{
@@ -882,6 +1085,7 @@ declare class SemiontApiClient {
         message?: string;
         result?: Record<string, unknown>;
     }>;
+    private parseSSEStream;
     getJobStatus(id: JobId, options?: RequestOptions): Promise<ResponseContent<paths['/api/jobs/{id}']['get']>>;
     /**
      * Poll a job until it completes or fails
@@ -1009,4 +1213,4 @@ declare function isPdfMimeType(mimeType: string): boolean;
 type MimeCategory = 'text' | 'image' | 'unsupported';
 declare function getMimeCategory(mimeType: string): MimeCategory;
 
-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 };
+export { APIError, type AnnotateReferencesStreamRequest, type AnnotationDetail, AnnotationStore, type AnnotationsListResponse, EventBusClient, FlowEngine, type MatchSearchStreamRequest, type MimeCategory, type ReferenceDetectionProgress, type RequestOptions, type ResourceDetail, type ResourceListResponse, ResourceStore, SSEClient, type SSEClientConfig, type SSEStream, type SSEStreamConnected, SSE_STREAM_CONNECTED, SemiontApiClient, type SemiontApiClientConfig, type YieldProgress, type YieldResourceStreamRequest, getExtensionForMimeType, getMimeCategory, isImageMimeType, isPdfMimeType, isTextMimeType };