@semiont/api-client 0.2.45 → 0.2.46

package/README.md

@@ -8,7 +8,12 @@
 
 TypeScript SDK for [Semiont](https://github.com/The-AI-Alliance/semiont) - a knowledge management system for semantic annotations, AI-powered annotation detection, and collaborative document analysis.
 
-This package provides the HTTP client, SSE streams, and utilities for working with the Semiont API. OpenAPI types are re-exported from [`@semiont/core`](../core/README.md) (the source of truth).
+This package provides two clients, SSE streams, and utilities for working with Semiont:
+
+- **`SemiontApiClient`** — HTTP client for the Semiont REST API
+- **`EventBusClient`** — Direct EventBus client (no HTTP needed)
+
+OpenAPI types are re-exported from [`@semiont/core`](../core/README.md) (the source of truth).
 
 ## What is Semiont?
 
@@ -74,6 +79,34 @@ const annotations = await client.getResourceAnnotations(resourceUri(resource['@i
 console.log('Annotations:', annotations.annotations.length);
 ```
 
+## EventBus Client (No HTTP)
+
+The `EventBusClient` communicates directly via the RxJS EventBus — no HTTP server needed. It covers all knowledge-domain operations (resource reads, annotations, entity types, search, LLM context, clone tokens, job status).
+
+```typescript
+import { EventBusClient } from '@semiont/api-client';
+import { EventBus, resourceId } from '@semiont/core';
+import { startMakeMeaning } from '@semiont/make-meaning';
+
+// Start the knowledge system
+const eventBus = new EventBus();
+const makeMeaning = await startMakeMeaning(config, eventBus, logger);
+
+// Use EventBusClient instead of SemiontApiClient
+const client = new EventBusClient(eventBus);
+
+// Same operations, no HTTP
+const resources = await client.listResources({ limit: 10 });
+const resource = await client.getResource(resourceId('doc-123'));
+const annotations = await client.getAnnotations(resourceId('doc-123'));
+const entityTypes = await client.listEntityTypes();
+const results = await client.searchResources('quantum computing');
+```
+
+**What's covered**: All browse, bind, mark, gather, yield (clone), and job operations.
+
+**What's NOT covered** (HTTP-only): Auth, admin, health/status, binary content upload/download, SSE streaming.
+
 ## Logging
 
 Enable logging to debug requests and monitor API usage:
@@ -112,6 +145,7 @@ const client = new SemiontApiClient({
 
 ## Key Features
 
+- **Two clients** - HTTP (`SemiontApiClient`) and EventBus (`EventBusClient`) for the same operations
 - **Type-safe** - Re-exports OpenAPI types from `@semiont/core` with branded types
 - **W3C compliant** - Web Annotation standard with fuzzy text matching
 - **Real-time** - SSE streaming for long operations
@@ -122,12 +156,16 @@ const client = new SemiontApiClient({
 
 ## Use Cases
 
-- ✅ MCP servers and AI integrations
-- ✅ Frontend applications (wrap with React hooks)
-- ✅ CLI tools and automation scripts
-- ✅ Third-party integrations
+**SemiontApiClient (HTTP)**:
+- MCP servers and AI integrations
+- Frontend applications (wrap with React hooks)
+- CLI tools and automation scripts
+- Third-party integrations
 
-❌ **Not for backend internal code** - Use [`@semiont/core`](../core/) instead
+**EventBusClient (direct)**:
+- Scripts that run alongside make-meaning (no HTTP server)
+- Testing without HTTP overhead
+- Embedded scenarios where EventBus is available directly
 
 ## License
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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 } from '@semiont/core';
-export { Logger } from '@semiont/core';
-export { BoundingBox, ContentCache, FragmentSelector, JWTTokenSchema, LOCALES, LocaleInfo, MatchQuality, Point, Selector, 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, getFragmentSelector, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getNodeEncoding, getPrimaryMediaType, getPrimaryRepresentation, getPrimarySelector, getResourceEntityTypes, getResourceId, getStorageUri, getSvgSelector, getTargetSelector, getTargetSource, getTextPositionSelector, getTextQuoteSelector, hasTargetSelector, isArchived, isAssessment, isBodyResolved, isComment, isDraft, isHighlight, isReference, isResolvedReference, isStubReference, isTag, isValidEmail, normalizeCoordinates, normalizeText, parseSvgSelector, scaleSvgToNative, validateAndCorrectOffsets, validateData, validateSvgMarkup, verifyPosition } from './utils/index.js';
+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';
+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';
 
 /**
  * TypeScript types for Server-Sent Events (SSE) streaming
@@ -505,6 +505,33 @@ declare class SSEClient {
     resourceEvents(resourceId: ResourceUri, options: SSERequestOptions & {
         onConnected?: () => void;
     }): SSEStream;
+    /**
+     * Subscribe to global system events (long-lived stream)
+     *
+     * Opens a long-lived SSE connection to receive system-level domain events
+     * (entity type additions, etc.) that are not scoped to a specific resource.
+     *
+     * @param options - Request options (auth token, eventBus)
+     * @returns SSE stream controller
+     *
+     * @example
+     * ```typescript
+     * const stream = sseClient.globalEvents({ auth: 'your-token', eventBus });
+     *
+     * // Events auto-emit to EventBus — subscribe there
+     * eventBus.get('make-meaning:event').subscribe((event) => {
+     *   if (event.type === 'entitytype.added') {
+     *     // Invalidate entity types query
+     *   }
+     * });
+     *
+     * // Close when no longer needed
+     * stream.close();
+     * ```
+     */
+    globalEvents(options: SSERequestOptions & {
+        onConnected?: () => void;
+    }): SSEStream;
 }
 
 /**
@@ -622,7 +649,9 @@ declare class SemiontApiClient {
         creationMethod?: string;
         sourceAnnotationId?: string;
         sourceResourceId?: string;
-    }, options?: RequestOptions): Promise<ResponseContent<paths['/resources']['post']>>;
+    }, options?: RequestOptions): Promise<{
+        resourceId: string;
+    }>;
     getResource(resourceUri: ResourceUri, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}']['get']>>;
     /**
      * Get resource representation using W3C content negotiation
@@ -697,7 +726,7 @@ 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<ResponseContent<paths['/resources/{id}']['patch']>>;
+    updateResource(resourceUri: ResourceUri, data: RequestContent<paths['/resources/{id}']['patch']>, options?: RequestOptions): Promise<void>;
     getResourceEvents(resourceUri: ResourceUri, options?: RequestOptions): Promise<{
         events: any[];
     }>;
@@ -711,16 +740,20 @@ declare class SemiontApiClient {
     }>;
     generateCloneToken(resourceUri: ResourceUri, 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<ResponseContent<paths['/api/clone-tokens/create-resource']['post']>>;
-    createAnnotation(resourceUri: ResourceUri, data: RequestContent<paths['/resources/{id}/annotations']['post']>, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}/annotations']['post']>>;
+    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<{
+        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<ResponseContent<paths['/resources/{resourceId}/annotations/{annotationId}/body']['put']>>;
+    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']>>;
-    addEntityType(type: EntityType, options?: RequestOptions): Promise<ResponseContent<paths['/api/entity-types']['post']>>;
-    addEntityTypesBulk(types: EntityType[], options?: RequestOptions): Promise<ResponseContent<paths['/api/entity-types/bulk']['post']>>;
+    addEntityType(type: EntityType, options?: RequestOptions): Promise<void>;
+    addEntityTypesBulk(types: EntityType[], options?: RequestOptions): Promise<void>;
     listEntityTypes(options?: RequestOptions): Promise<ResponseContent<paths['/api/entity-types']['get']>>;
     listUsers(options?: RequestOptions): Promise<ResponseContent<paths['/api/admin/users']['get']>>;
     getUserStats(options?: RequestOptions): Promise<ResponseContent<paths['/api/admin/users/stats']['get']>>;
@@ -754,6 +787,77 @@ declare class SemiontApiClient {
     getStatus(options?: RequestOptions): Promise<ResponseContent<paths['/api/status']['get']>>;
 }
 
+/**
+ * EventBus-Only Client
+ *
+ * Implements the same knowledge-domain operations as SemiontApiClient
+ * but communicates directly via EventBus instead of HTTP.
+ *
+ * This proves the EventBus is a complete interface for all knowledge-domain
+ * operations. Binary content transfer and auth/admin stay HTTP-only.
+ *
+ * Usage:
+ * ```typescript
+ * import { EventBus } from '@semiont/core';
+ * import { EventBusClient } from '@semiont/api-client';
+ *
+ * const eventBus = new EventBus();
+ * const client = new EventBusClient(eventBus);
+ *
+ * const resources = await client.listResources({ limit: 10 });
+ * const resource = await client.getResource(resourceId('doc-123'));
+ * ```
+ */
+
+declare class EventBusClient {
+    private eventBus;
+    private timeoutMs;
+    constructor(eventBus: EventBus, timeoutMs?: number);
+    getResource(resourceId: ResourceId): Promise<components['schemas']['GetResourceResponse']>;
+    listResources(options?: {
+        search?: string;
+        archived?: boolean;
+        entityType?: string;
+        offset?: number;
+        limit?: number;
+    }): Promise<components['schemas']['ListResourcesResponse']>;
+    getAnnotations(resourceId: ResourceId): Promise<components['schemas']['GetAnnotationsResponse']>;
+    getAnnotation(resourceId: ResourceId, annotationId: AnnotationId): Promise<components['schemas']['GetAnnotationResponse']>;
+    getEvents(resourceId: ResourceId, options?: {
+        type?: string;
+        userId?: string;
+        limit?: number;
+    }): Promise<components['schemas']['GetEventsResponse']>;
+    getAnnotationHistory(resourceId: ResourceId, annotationId: AnnotationId): Promise<components['schemas']['GetAnnotationHistoryResponse']>;
+    getReferencedBy(resourceId: ResourceId, motivation?: string): Promise<components['schemas']['GetReferencedByResponse']>;
+    listEntityTypes(): Promise<components['schemas']['GetEntityTypesResponse']>;
+    addEntityType(tag: string, userId: UserId): void;
+    generateCloneToken(resourceId: ResourceId): Promise<components['schemas']['CloneResourceWithTokenResponse']>;
+    getResourceByToken(token: string): Promise<components['schemas']['GetResourceByTokenResponse']>;
+    createResourceFromToken(options: {
+        token: string;
+        name: string;
+        content: string;
+        userId: UserId;
+        archiveOriginal?: boolean;
+    }): Promise<{
+        resourceId: ResourceId;
+    }>;
+    getJobStatus(jobId: JobId): Promise<components['schemas']['JobStatusResponse']>;
+    getAnnotationLLMContext(annotationUri: string, resourceUri: string, options?: {
+        includeSourceContext?: boolean;
+        includeTargetContext?: boolean;
+        contextWindow?: number;
+    }): Promise<components['schemas']['AnnotationLLMContextResponse']>;
+    getResourceLLMContext(resourceUri: string, options: {
+        depth: number;
+        maxResources: number;
+        includeContent: boolean;
+        includeSummary: boolean;
+    }): Promise<components['schemas']['ResourceLLMContextResponse']>;
+    searchResources(searchTerm: string): Promise<components['schemas']['ResourceDescriptor'][]>;
+}
+
 /**
  * MIME type utilities for Semiont
  *
@@ -792,4 +896,4 @@ declare function isPdfMimeType(mimeType: string): boolean;
 type MimeCategory = 'text' | 'image' | 'unsupported';
 declare function getMimeCategory(mimeType: string): MimeCategory;
 
-export { APIError, type AnnotateReferencesStreamRequest, 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, 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 };