@semiont/api-client 0.2.1 → 0.2.2

package/dist/index.d.ts

@@ -1,3 +1,907 @@
+import { B as BaseUrl, A as AccessToken, R as ResourceUri, E as EntityType, a as AnnotationUri, c as components, b as Email, p as paths, d as RefreshToken, G as GoogleCredential, C as ContentFormat, S as SearchQuery, e as CloneToken, f as ResourceAnnotationUri, M as Motivation, U as UserDID, J as JobId } from './index-DHh0ToZB.js';
+export { $ as $defs, aq as AuthCode, X as EventMetadata, an as JWTTokenSchema, a9 as LOCALES, a8 as LocaleInfo, ar as MCPToken, a6 as ResourceCreationDetails, Y as ResourceEventType, i as Selector, W as StoredEvent, h as SvgSelector, T as TextPositionSelector, g as TextQuoteSelector, al as ValidationFailure, am as ValidationResult, ak as ValidationSuccess, av as accessToken, aF as annotationUri, at as authCode, aD as baseUrl, ay as cloneToken, as as email, aB as entityType, V as extractBoundingBox, a1 as formatEventType, ad as formatLocaleDisplay, a3 as formatRelativeTime, ae as getAllLocaleCodes, K as getAnnotationExactText, Z as getAnnotationUriFromEvent, j as getBodySource, k as getBodyType, ai as getChecksum, y as getCommentText, r as getEntityTypes, a4 as getEventDisplayContent, a2 as getEventEmoji, a5 as getEventEntityTypes, I as getExactText, aj as getLanguage, ac as getLocaleEnglishName, aa as getLocaleInfo, ab as getLocaleNativeName, ah as getPrimaryMediaType, ag as getPrimaryRepresentation, L as getPrimarySelector, a7 as getResourceCreationDetails, af as getResourceId, P as getSvgSelector, z as getTagCategory, D as getTagSchemaId, n as getTargetSelector, m as getTargetSource, N as getTextPositionSelector, O as getTextQuoteSelector, au as googleCredential, q as hasTargetSelector, u as isAssessment, l as isBodyResolved, v as isComment, _ as isEventRelatedToAnnotation, s as isHighlight, t as isReference, H as isResolvedReference, a0 as isResourceEvent, F as isStubReference, x as isTag, ap as isValidEmail, az as jobId, ax as mcpToken, o as operations, aw as refreshToken, aG as resourceAnnotationUri, aE as resourceUri, aC as searchQuery, aA as userDID, ao as validateData, Q as validateSvgMarkup, w as webhooks } from './index-DHh0ToZB.js';
+
+/**
+ * TypeScript types for Server-Sent Events (SSE) streaming
+ *
+ * These types match the event payloads sent by backend SSE endpoints.
+ * They are not validated (per SSE-VALIDATION-CONSIDERATIONS.md) but provide
+ * type safety for client code consuming the streams.
+ */
+/**
+ * Progress event for entity detection stream
+ *
+ * Sent by POST /resources/:id/detect-annotations-stream
+ *
+ * @example
+ * ```typescript
+ * stream.onProgress((progress: DetectionProgress) => {
+ *   if (progress.status === 'scanning') {
+ *     console.log(`Scanning for ${progress.currentEntityType}...`);
+ *     console.log(`Progress: ${progress.processedEntityTypes}/${progress.totalEntityTypes}`);
+ *   }
+ * });
+ * ```
+ */
+interface DetectionProgress {
+    /** Current status of detection operation */
+    status: 'started' | 'scanning' | 'complete' | 'error';
+    /** Resource ID being scanned */
+    resourceId: string;
+    /** Currently scanning for this entity type (only present during 'scanning') */
+    currentEntityType?: string;
+    /** Total number of entity types to scan */
+    totalEntityTypes: number;
+    /** Number of entity types processed so far */
+    processedEntityTypes: number;
+    /** Human-readable status message */
+    message?: string;
+    /** Total entities found (only present in 'complete') */
+    foundCount?: number;
+}
+/**
+ * Progress event for resource generation stream
+ *
+ * Sent by POST /resources/:resourceId/annotations/:annotationId/generate-resource-stream
+ *
+ * @example
+ * ```typescript
+ * stream.onProgress((progress: GenerationProgress) => {
+ *   console.log(`${progress.status}: ${progress.percentage}%`);
+ *   console.log(progress.message);
+ * });
+ * ```
+ */
+interface GenerationProgress {
+    /** Current stage of generation operation */
+    status: 'started' | 'fetching' | 'generating' | 'creating' | 'complete' | 'error';
+    /** Annotation ID being used as source */
+    referenceId: string;
+    /** Name of resource being generated */
+    resourceName?: string;
+    /** ID of generated resource (only present in 'complete') */
+    resourceId?: string;
+    /** ID of source resource */
+    sourceResourceId?: string;
+    /** Percentage complete (0-100) */
+    percentage: number;
+    /** Human-readable status message */
+    message?: string;
+}
+/**
+ * Progress event for highlight detection stream
+ *
+ * Sent by POST /resources/:id/detect-highlights-stream
+ *
+ * @example
+ * ```typescript
+ * stream.onProgress((progress: HighlightDetectionProgress) => {
+ *   if (progress.status === 'analyzing') {
+ *     console.log(`Analyzing: ${progress.percentage}%`);
+ *   }
+ * });
+ * ```
+ */
+interface HighlightDetectionProgress {
+    /** Current status of highlight detection operation */
+    status: 'started' | 'analyzing' | 'creating' | 'complete' | 'error';
+    /** Resource ID being analyzed */
+    resourceId: string;
+    /** Current stage of processing */
+    stage?: 'analyzing' | 'creating';
+    /** Percentage complete (0-100) */
+    percentage?: number;
+    /** Human-readable status message */
+    message?: string;
+    /** Total highlights found */
+    foundCount?: number;
+    /** Total highlights created */
+    createdCount?: number;
+}
+/**
+ * Progress event for assessment detection stream
+ *
+ * Sent by POST /resources/:id/detect-assessments-stream
+ *
+ * @example
+ * ```typescript
+ * stream.onProgress((progress: AssessmentDetectionProgress) => {
+ *   if (progress.status === 'analyzing') {
+ *     console.log(`Analyzing: ${progress.percentage}%`);
+ *   }
+ * });
+ * ```
+ */
+interface AssessmentDetectionProgress {
+    /** Current status of assessment detection operation */
+    status: 'started' | 'analyzing' | 'creating' | 'complete' | 'error';
+    /** Resource ID being analyzed */
+    resourceId: string;
+    /** Current stage of processing */
+    stage?: 'analyzing' | 'creating';
+    /** Percentage complete (0-100) */
+    percentage?: number;
+    /** Human-readable status message */
+    message?: string;
+    /** Total assessments found */
+    foundCount?: number;
+    /** Total assessments created */
+    createdCount?: number;
+}
+/**
+ * Progress event for comment detection stream
+ *
+ * Sent by POST /resources/:id/detect-comments-stream
+ *
+ * @example
+ * ```typescript
+ * stream.onProgress((progress: CommentDetectionProgress) => {
+ *   if (progress.status === 'analyzing') {
+ *     console.log(`Analyzing: ${progress.percentage}%`);
+ *   }
+ * });
+ * ```
+ */
+interface CommentDetectionProgress {
+    /** Current status of comment detection operation */
+    status: 'started' | 'analyzing' | 'creating' | 'complete' | 'error';
+    /** Resource ID being analyzed */
+    resourceId: string;
+    /** Current stage of processing */
+    stage?: 'analyzing' | 'creating';
+    /** Percentage complete (0-100) */
+    percentage?: number;
+    /** Human-readable status message */
+    message?: string;
+    /** Total comments found */
+    foundCount?: number;
+    /** Total comments created */
+    createdCount?: number;
+}
+/**
+ * Progress event for tag detection stream
+ *
+ * Sent by POST /resources/:id/detect-tags-stream
+ *
+ * @example
+ * ```typescript
+ * stream.onProgress((progress: TagDetectionProgress) => {
+ *   if (progress.status === 'analyzing') {
+ *     console.log(`Analyzing ${progress.currentCategory}: ${progress.percentage}%`);
+ *   }
+ * });
+ * ```
+ */
+interface TagDetectionProgress {
+    /** Current status of tag detection operation */
+    status: 'started' | 'analyzing' | 'creating' | 'complete' | 'error';
+    /** Resource ID being analyzed */
+    resourceId: string;
+    /** Current stage of processing */
+    stage?: 'analyzing' | 'creating';
+    /** Percentage complete (0-100) */
+    percentage?: number;
+    /** Currently processing this category */
+    currentCategory?: string;
+    /** Number of categories processed */
+    processedCategories?: number;
+    /** Total number of categories */
+    totalCategories?: number;
+    /** Human-readable status message */
+    message?: string;
+    /** Total tags found */
+    tagsFound?: number;
+    /** Total tags created */
+    tagsCreated?: number;
+    /** Tags found by category */
+    byCategory?: Record<string, number>;
+}
+/**
+ * Resource event from real-time event stream
+ *
+ * Sent by GET /resources/:id/events/stream
+ *
+ * This represents a single event from the event store, broadcast in real-time
+ * as it occurs. Used for real-time collaboration - multiple users see each
+ * other's changes as they happen.
+ *
+ * @example
+ * ```typescript
+ * stream.onEvent((event: ResourceEvent) => {
+ *   console.log(`Event: ${event.type}`);
+ *   console.log(`User: ${event.userId}`);
+ *   console.log(`Payload:`, event.payload);
+ *   console.log(`Sequence: ${event.metadata.sequenceNumber}`);
+ * });
+ * ```
+ */
+interface ResourceEvent {
+    /** Event ID (unique) */
+    id: string;
+    /** Event type (e.g., 'resource.created', 'annotation.created', etc.) */
+    type: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** User ID who triggered the event */
+    userId: string;
+    /** Resource ID this event relates to */
+    resourceId: string;
+    /** Event-specific payload (varies by event type) */
+    payload: any;
+    /** Event store metadata */
+    metadata: {
+        /** Monotonically increasing sequence number */
+        sequenceNumber: number;
+        /** SHA-256 hash of previous event (for integrity) */
+        prevEventHash: string;
+        /** SHA-256 checksum of this event */
+        checksum: string;
+    };
+}
+/**
+ * SSE stream controller interface
+ *
+ * Returned by all SSE methods. Provides callback registration and cleanup.
+ *
+ * @typeParam TProgress - Type of progress events
+ * @typeParam TComplete - Type of completion event
+ *
+ * @example
+ * ```typescript
+ * const stream: SSEStream<DetectionProgress, DetectionProgress> =
+ *   client.sse.detectAnnotations(resourceId, { entityTypes: ['Person'] });
+ *
+ * stream.onProgress((p) => console.log(p.message));
+ * stream.onComplete((r) => console.log(`Done! Found ${r.foundCount} entities`));
+ * stream.onError((e) => console.error('Failed:', e.message));
+ *
+ * // Cleanup when done
+ * stream.close();
+ * ```
+ */
+interface SSEStream<TProgress, TComplete> {
+    /**
+     * Register callback for progress events
+     *
+     * Called for each progress update (e.g., detection-started, detection-progress)
+     */
+    onProgress(callback: (progress: TProgress) => void): void;
+    /**
+     * Register callback for completion event
+     *
+     * Called once when operation completes successfully (e.g., detection-complete)
+     */
+    onComplete(callback: (result: TComplete) => void): void;
+    /**
+     * Register callback for error events
+     *
+     * Called if operation fails or stream encounters an error
+     */
+    onError(callback: (error: Error) => void): void;
+    /**
+     * Close the SSE stream and abort the connection
+     *
+     * Should be called to cleanup resources when stream is no longer needed.
+     * Safe to call multiple times.
+     *
+     * @example
+     * ```typescript
+     * // React cleanup
+     * useEffect(() => {
+     *   const stream = client.sse.detectAnnotations(...);
+     *   return () => stream.close();
+     * }, []);
+     * ```
+     */
+    close(): void;
+}
+
+/**
+ * SSE Client for Semiont Streaming Endpoints
+ *
+ * Provides type-safe methods for Server-Sent Events streaming.
+ * Does NOT use ky - uses native fetch() for SSE support.
+ */
+
+/**
+ * Request body for detection stream
+ */
+interface DetectAnnotationsStreamRequest {
+    entityTypes: EntityType[];
+}
+/**
+ * Request body for generation stream
+ * Uses generated type from OpenAPI schema
+ */
+type GenerateResourceStreamRequest = components['schemas']['GenerateResourceStreamRequest'];
+/**
+ * Request body for highlight detection stream
+ */
+interface DetectHighlightsStreamRequest {
+    instructions?: string;
+}
+/**
+ * Request body for assessment detection stream
+ */
+interface DetectAssessmentsStreamRequest {
+    instructions?: string;
+}
+/**
+ * Request body for comment detection stream
+ */
+interface DetectCommentsStreamRequest {
+    instructions?: string;
+    tone?: 'scholarly' | 'explanatory' | 'conversational' | 'technical';
+}
+/**
+ * Request body for tag detection stream
+ */
+interface DetectTagsStreamRequest {
+    schemaId: string;
+    categories: string[];
+}
+/**
+ * SSE Client configuration
+ */
+interface SSEClientConfig {
+    baseUrl: BaseUrl;
+    accessToken?: AccessToken;
+}
+/**
+ * SSE Client for real-time streaming operations
+ *
+ * Separate from the main HTTP client to clearly mark streaming endpoints.
+ * Uses native fetch() instead of ky for SSE support.
+ *
+ * @example
+ * ```typescript
+ * const sseClient = new SSEClient({
+ *   baseUrl: 'http://localhost:4000',
+ *   accessToken: 'your-token'
+ * });
+ *
+ * const stream = sseClient.detectAnnotations(
+ *   'http://localhost:4000/resources/doc-123',
+ *   { entityTypes: ['Person', 'Organization'] }
+ * );
+ *
+ * stream.onProgress((p) => console.log(p.message));
+ * stream.onComplete((r) => console.log(`Found ${r.foundCount} entities`));
+ * stream.onError((e) => console.error('Detection failed:', e));
+ * ```
+ */
+declare class SSEClient {
+    private baseUrl;
+    private accessToken;
+    constructor(config: SSEClientConfig);
+    /**
+     * Set the access token for authenticated requests
+     */
+    setAccessToken(token: AccessToken): void;
+    /**
+     * Clear the access token
+     */
+    clearAccessToken(): void;
+    /**
+     * 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)
+     *
+     * Streams entity detection progress via Server-Sent Events.
+     *
+     * @param resourceId - Resource URI or ID
+     * @param request - Detection configuration (entity types to detect)
+     * @returns SSE stream controller with progress/complete/error callbacks
+     *
+     * @example
+     * ```typescript
+     * const stream = sseClient.detectAnnotations(
+     *   'http://localhost:4000/resources/doc-123',
+     *   { entityTypes: ['Person', 'Organization'] }
+     * );
+     *
+     * stream.onProgress((progress) => {
+     *   console.log(`Scanning: ${progress.currentEntityType}`);
+     *   console.log(`Progress: ${progress.processedEntityTypes}/${progress.totalEntityTypes}`);
+     * });
+     *
+     * stream.onComplete((result) => {
+     *   console.log(`Detection complete! Found ${result.foundCount} entities`);
+     * });
+     *
+     * stream.onError((error) => {
+     *   console.error('Detection failed:', error.message);
+     * });
+     *
+     * // Cleanup when done
+     * stream.close();
+     * ```
+     */
+    detectAnnotations(resourceId: ResourceUri, request: DetectAnnotationsStreamRequest): SSEStream<DetectionProgress, DetectionProgress>;
+    /**
+     * Generate resource from annotation (streaming)
+     *
+     * Streams resource generation progress via Server-Sent Events.
+     *
+     * @param resourceId - Source resource URI or ID
+     * @param annotationId - Annotation URI or ID to use as generation source
+     * @param request - Generation options (title, prompt, language)
+     * @returns SSE stream controller with progress/complete/error callbacks
+     *
+     * @example
+     * ```typescript
+     * const stream = sseClient.generateResourceFromAnnotation(
+     *   'http://localhost:4000/resources/doc-123',
+     *   'http://localhost:4000/annotations/ann-456',
+     *   { language: 'es', title: 'Spanish Summary' }
+     * );
+     *
+     * stream.onProgress((progress) => {
+     *   console.log(`${progress.status}: ${progress.percentage}%`);
+     *   console.log(progress.message);
+     * });
+     *
+     * stream.onComplete((result) => {
+     *   console.log(`Generated resource: ${result.resourceId}`);
+     * });
+     *
+     * stream.onError((error) => {
+     *   console.error('Generation failed:', error.message);
+     * });
+     *
+     * // Cleanup when done
+     * stream.close();
+     * ```
+     */
+    generateResourceFromAnnotation(resourceId: ResourceUri, annotationId: AnnotationUri, request: GenerateResourceStreamRequest): SSEStream<GenerationProgress, GenerationProgress>;
+    /**
+     * Detect highlights in a resource (streaming)
+     *
+     * Streams highlight detection progress via Server-Sent Events.
+     *
+     * @param resourceId - Resource URI or ID
+     * @param request - Detection configuration (optional instructions)
+     * @returns SSE stream controller with progress/complete/error callbacks
+     *
+     * @example
+     * ```typescript
+     * const stream = sseClient.detectHighlights(
+     *   'http://localhost:4000/resources/doc-123',
+     *   { instructions: 'Focus on key technical points' }
+     * );
+     *
+     * stream.onProgress((progress) => {
+     *   console.log(`${progress.status}: ${progress.percentage}%`);
+     *   console.log(progress.message);
+     * });
+     *
+     * stream.onComplete((result) => {
+     *   console.log(`Detection complete! Created ${result.createdCount} highlights`);
+     * });
+     *
+     * stream.onError((error) => {
+     *   console.error('Detection failed:', error.message);
+     * });
+     *
+     * // Cleanup when done
+     * stream.close();
+     * ```
+     */
+    detectHighlights(resourceId: ResourceUri, request?: DetectHighlightsStreamRequest): SSEStream<HighlightDetectionProgress, HighlightDetectionProgress>;
+    /**
+     * Detect assessments in a resource (streaming)
+     *
+     * Streams assessment detection progress via Server-Sent Events.
+     *
+     * @param resourceId - Resource URI or ID
+     * @param request - Detection configuration (optional instructions)
+     * @returns SSE stream controller with progress/complete/error callbacks
+     *
+     * @example
+     * ```typescript
+     * const stream = sseClient.detectAssessments(
+     *   'http://localhost:4000/resources/doc-123',
+     *   { instructions: 'Evaluate claims for accuracy' }
+     * );
+     *
+     * stream.onProgress((progress) => {
+     *   console.log(`${progress.status}: ${progress.percentage}%`);
+     *   console.log(progress.message);
+     * });
+     *
+     * stream.onComplete((result) => {
+     *   console.log(`Detection complete! Created ${result.createdCount} assessments`);
+     * });
+     *
+     * stream.onError((error) => {
+     *   console.error('Detection failed:', error.message);
+     * });
+     *
+     * // Cleanup when done
+     * stream.close();
+     * ```
+     */
+    detectAssessments(resourceId: ResourceUri, request?: DetectAssessmentsStreamRequest): SSEStream<AssessmentDetectionProgress, AssessmentDetectionProgress>;
+    /**
+     * Detect comments in a resource (streaming)
+     *
+     * Streams comment detection progress via Server-Sent Events.
+     * Uses AI to identify passages that would benefit from explanatory comments
+     * and creates comment annotations with contextual information.
+     *
+     * @param resourceId - Resource URI or ID
+     * @param request - Detection configuration (optional instructions and tone)
+     * @returns SSE stream controller with progress/complete/error callbacks
+     *
+     * @example
+     * ```typescript
+     * const stream = sseClient.detectComments('http://localhost:4000/resources/doc-123', {
+     *   instructions: 'Focus on technical terminology',
+     *   tone: 'scholarly'
+     * });
+     *
+     * stream.onProgress((progress) => {
+     *   console.log(`${progress.status}: ${progress.percentage}%`);
+     * });
+     *
+     * stream.onComplete((result) => {
+     *   console.log(`Detection complete! Created ${result.createdCount} comments`);
+     * });
+     *
+     * stream.onError((error) => {
+     *   console.error('Detection failed:', error.message);
+     * });
+     *
+     * // Cleanup when done
+     * stream.close();
+     * ```
+     */
+    detectComments(resourceId: ResourceUri, request?: DetectCommentsStreamRequest): SSEStream<CommentDetectionProgress, CommentDetectionProgress>;
+    /**
+     * Detect tags in a resource (streaming)
+     *
+     * Streams tag detection progress via Server-Sent Events.
+     * Uses AI to identify passages serving specific structural roles
+     * (e.g., IRAC, IMRAD, Toulmin) and creates tag annotations with dual-body structure.
+     *
+     * @param resourceId - Resource URI or ID
+     * @param request - Detection configuration (schema and categories to detect)
+     * @returns SSE stream controller with progress/complete/error callbacks
+     *
+     * @example
+     * ```typescript
+     * const stream = sseClient.detectTags('http://localhost:4000/resources/doc-123', {
+     *   schemaId: 'legal-irac',
+     *   categories: ['Issue', 'Rule', 'Application', 'Conclusion']
+     * });
+     *
+     * stream.onProgress((progress) => {
+     *   console.log(`${progress.status}: ${progress.percentage}%`);
+     *   console.log(`Processing ${progress.currentCategory}...`);
+     * });
+     *
+     * stream.onComplete((result) => {
+     *   console.log(`Detection complete! Created ${result.tagsCreated} tags`);
+     * });
+     *
+     * stream.onError((error) => {
+     *   console.error('Detection failed:', error.message);
+     * });
+     *
+     * // Cleanup when done
+     * stream.close();
+     * ```
+     */
+    detectTags(resourceId: ResourceUri, request: DetectTagsStreamRequest): SSEStream<TagDetectionProgress, TagDetectionProgress>;
+    /**
+     * Subscribe to resource events (long-lived stream)
+     *
+     * Opens a long-lived SSE connection to receive real-time events for a resource.
+     * Used for collaborative editing - see events from other users as they happen.
+     *
+     * This stream does NOT have a complete event - it stays open until explicitly closed.
+     *
+     * @param resourceId - Resource URI or ID to subscribe to
+     * @returns SSE stream controller with event callback
+     *
+     * @example
+     * ```typescript
+     * const stream = sseClient.resourceEvents('http://localhost:4000/resources/doc-123');
+     *
+     * stream.onProgress((event) => {
+     *   console.log(`Event: ${event.type}`);
+     *   console.log(`User: ${event.userId}`);
+     *   console.log(`Sequence: ${event.metadata.sequenceNumber}`);
+     *   console.log(`Payload:`, event.payload);
+     * });
+     *
+     * stream.onError((error) => {
+     *   console.error('Stream error:', error.message);
+     * });
+     *
+     * // Close when no longer needed (e.g., component unmount)
+     * stream.close();
+     * ```
+     */
+    resourceEvents(resourceId: ResourceUri): SSEStream<ResourceEvent, never>;
+}
+
+/**
+ * Common API client for Semiont backend
+ *
+ * This client can be used by:
+ * - MCP server (Node.js)
+ * - Demo scripts (Node.js)
+ * - Frontend (Next.js/React - can wrap with hooks)
+ *
+ * Uses ky for HTTP requests with built-in retry, timeout, and error handling.
+ */
+
+type ResponseContent<T> = T extends {
+    responses: {
+        200: {
+            content: {
+                'application/json': infer R;
+            };
+        };
+    };
+} ? R : T extends {
+    responses: {
+        201: {
+            content: {
+                'application/json': infer R;
+            };
+        };
+    };
+} ? R : never;
+type RequestContent<T> = T extends {
+    requestBody?: {
+        content: {
+            'application/json': infer R;
+        };
+    };
+} ? R : never;
+declare class APIError extends Error {
+    status: number;
+    statusText: string;
+    details?: unknown | undefined;
+    constructor(message: string, status: number, statusText: string, details?: unknown | undefined);
+}
+interface SemiontApiClientConfig {
+    baseUrl: BaseUrl;
+    accessToken?: AccessToken;
+    timeout?: number;
+    retry?: number;
+}
+/**
+ * Semiont API Client
+ *
+ * Provides type-safe methods for all Semiont backend API endpoints.
+ */
+declare class SemiontApiClient {
+    private http;
+    private baseUrl;
+    private accessToken;
+    /**
+     * 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'] }
+     * );
+     *
+     * stream.onProgress((p) => console.log(p.message));
+     * stream.onComplete((r) => console.log(`Found ${r.foundCount} entities`));
+     * stream.close();
+     * ```
+     */
+    readonly sse: SSEClient;
+    constructor(config: SemiontApiClientConfig);
+    /**
+     * Set the access token for authenticated requests
+     */
+    setAccessToken(token: AccessToken): void;
+    /**
+     * Clear the access token
+     */
+    clearAccessToken(): void;
+    authenticatePassword(email: Email, password: string): Promise<ResponseContent<paths['/api/tokens/password']['post']>>;
+    refreshToken(token: RefreshToken): Promise<ResponseContent<paths['/api/tokens/refresh']['post']>>;
+    authenticateGoogle(credential: GoogleCredential): Promise<ResponseContent<paths['/api/tokens/google']['post']>>;
+    generateMCPToken(): Promise<ResponseContent<paths['/api/tokens/mcp-generate']['post']>>;
+    getMe(): Promise<ResponseContent<paths['/api/users/me']['get']>>;
+    acceptTerms(): Promise<ResponseContent<paths['/api/users/accept-terms']['post']>>;
+    logout(): Promise<ResponseContent<paths['/api/users/logout']['post']>>;
+    /**
+     * Create a new resource with binary content support
+     *
+     * @param data - Resource creation data
+     * @param data.name - Resource name
+     * @param data.file - File object or Buffer with binary content
+     * @param data.format - MIME type (e.g., 'text/markdown', 'image/png')
+     * @param data.entityTypes - Optional array of entity types
+     * @param data.language - Optional ISO 639-1 language code
+     * @param data.creationMethod - Optional creation method
+     * @param data.sourceAnnotationId - Optional source annotation ID
+     * @param data.sourceResourceId - Optional source resource ID
+     */
+    createResource(data: {
+        name: string;
+        file: File | Buffer;
+        format: string;
+        entityTypes?: string[];
+        language?: string;
+        creationMethod?: string;
+        sourceAnnotationId?: string;
+        sourceResourceId?: string;
+    }): Promise<ResponseContent<paths['/resources']['post']>>;
+    getResource(resourceUri: ResourceUri): Promise<ResponseContent<paths['/resources/{id}']['get']>>;
+    /**
+     * Get resource representation using W3C content negotiation
+     * Returns raw binary content (images, PDFs, text, etc.) with content type
+     *
+     * @param resourceUri - Full resource URI
+     * @param options - Options including Accept header for content negotiation
+     * @returns Object with data (ArrayBuffer) and contentType (string)
+     *
+     * @example
+     * ```typescript
+     * // Get markdown representation
+     * const { data, contentType } = await client.getResourceRepresentation(rUri, { accept: 'text/markdown' });
+     * const markdown = new TextDecoder().decode(data);
+     *
+     * // Get image representation
+     * const { data, contentType } = await client.getResourceRepresentation(rUri, { accept: 'image/png' });
+     * const blob = new Blob([data], { type: contentType });
+     *
+     * // Get PDF representation
+     * const { data, contentType } = await client.getResourceRepresentation(rUri, { accept: 'application/pdf' });
+     * ```
+     */
+    getResourceRepresentation(resourceUri: ResourceUri, options?: {
+        accept?: ContentFormat;
+    }): Promise<{
+        data: ArrayBuffer;
+        contentType: string;
+    }>;
+    /**
+     * Get resource representation as a stream using W3C content negotiation
+     * Returns streaming binary content (for large files: videos, large PDFs, etc.)
+     *
+     * Use this for large files to avoid loading entire content into memory.
+     * The stream is consumed incrementally and the backend connection stays open
+     * until the stream is fully consumed or closed.
+     *
+     * @param resourceUri - Full resource URI
+     * @param options - Options including Accept header for content negotiation
+     * @returns Object with stream (ReadableStream) and contentType (string)
+     *
+     * @example
+     * ```typescript
+     * // Stream large file
+     * const { stream, contentType } = await client.getResourceRepresentationStream(rUri, {
+     *   accept: 'video/mp4'
+     * });
+     *
+     * // Consume stream chunk by chunk (never loads entire file into memory)
+     * for await (const chunk of stream) {
+     *   // Process chunk
+     *   console.log(`Received ${chunk.length} bytes`);
+     * }
+     *
+     * // Or pipe to a file in Node.js
+     * const fileStream = fs.createWriteStream('output.mp4');
+     * const reader = stream.getReader();
+     * while (true) {
+     *   const { done, value } = await reader.read();
+     *   if (done) break;
+     *   fileStream.write(value);
+     * }
+     * ```
+     */
+    getResourceRepresentationStream(resourceUri: ResourceUri, options?: {
+        accept?: ContentFormat;
+    }): Promise<{
+        stream: ReadableStream<Uint8Array>;
+        contentType: string;
+    }>;
+    listResources(limit?: number, archived?: boolean, query?: SearchQuery): Promise<ResponseContent<paths['/resources']['get']>>;
+    updateResource(resourceUri: ResourceUri, data: RequestContent<paths['/resources/{id}']['patch']>): Promise<ResponseContent<paths['/resources/{id}']['patch']>>;
+    getResourceEvents(resourceUri: ResourceUri): Promise<{
+        events: any[];
+    }>;
+    getResourceAnnotations(resourceUri: ResourceUri): Promise<ResponseContent<paths['/resources/{id}/annotations']['get']>>;
+    getAnnotationLLMContext(resourceUri: ResourceUri, annotationId: string, options?: {
+        contextWindow?: number;
+    }): Promise<ResponseContent<paths['/resources/{resourceId}/annotations/{annotationId}/llm-context']['get']>>;
+    getResourceReferencedBy(resourceUri: ResourceUri): Promise<{
+        referencedBy: any[];
+    }>;
+    generateCloneToken(resourceUri: ResourceUri): Promise<ResponseContent<paths['/resources/{id}/clone-with-token']['post']>>;
+    getResourceByToken(token: CloneToken): Promise<ResponseContent<paths['/api/resources/token/{token}']['get']>>;
+    createResourceFromToken(data: RequestContent<paths['/api/resources/create-from-token']['post']>): Promise<ResponseContent<paths['/api/resources/create-from-token']['post']>>;
+    createAnnotation(resourceUri: ResourceUri, data: RequestContent<paths['/resources/{id}/annotations']['post']>): Promise<ResponseContent<paths['/resources/{id}/annotations']['post']>>;
+    getAnnotation(annotationUri: AnnotationUri): Promise<ResponseContent<paths['/annotations/{id}']['get']>>;
+    getResourceAnnotation(annotationUri: ResourceAnnotationUri): Promise<ResponseContent<paths['/resources/{resourceId}/annotations/{annotationId}']['get']>>;
+    listAnnotations(resourceUri: ResourceUri, motivation?: Motivation): Promise<ResponseContent<paths['/resources/{id}/annotations']['get']>>;
+    deleteAnnotation(annotationUri: ResourceAnnotationUri): Promise<void>;
+    updateAnnotationBody(annotationUri: ResourceAnnotationUri, data: RequestContent<paths['/resources/{resourceId}/annotations/{annotationId}/body']['put']>): Promise<ResponseContent<paths['/resources/{resourceId}/annotations/{annotationId}/body']['put']>>;
+    getAnnotationHistory(annotationUri: ResourceAnnotationUri): Promise<ResponseContent<paths['/resources/{resourceId}/annotations/{annotationId}/history']['get']>>;
+    addEntityType(type: EntityType): Promise<ResponseContent<paths['/api/entity-types']['post']>>;
+    addEntityTypesBulk(types: EntityType[]): Promise<ResponseContent<paths['/api/entity-types/bulk']['post']>>;
+    listEntityTypes(): Promise<ResponseContent<paths['/api/entity-types']['get']>>;
+    listUsers(): Promise<ResponseContent<paths['/api/admin/users']['get']>>;
+    getUserStats(): Promise<ResponseContent<paths['/api/admin/users/stats']['get']>>;
+    /**
+     * Update a user by ID
+     * Note: Users use DID identifiers (did:web:domain:users:id), not HTTP URIs.
+     */
+    updateUser(id: UserDID, data: RequestContent<paths['/api/admin/users/{id}']['patch']>): Promise<ResponseContent<paths['/api/admin/users/{id}']['patch']>>;
+    getOAuthConfig(): Promise<ResponseContent<paths['/api/admin/oauth/config']['get']>>;
+    getJobStatus(id: JobId): Promise<ResponseContent<paths['/api/jobs/{id}']['get']>>;
+    /**
+     * Poll a job until it completes or fails
+     * @param id - The job ID to poll
+     * @param options - Polling options
+     * @returns The final job status
+     */
+    pollJobUntilComplete(id: JobId, options?: {
+        interval?: number;
+        timeout?: number;
+        onProgress?: (status: ResponseContent<paths['/api/jobs/{id}']['get']>) => void;
+    }): Promise<ResponseContent<paths['/api/jobs/{id}']['get']>>;
+    getResourceLLMContext(resourceUri: ResourceUri, options?: {
+        depth?: number;
+        maxResources?: number;
+        includeContent?: boolean;
+        includeSummary?: boolean;
+    }): Promise<ResponseContent<paths['/resources/{id}/llm-context']['get']>>;
+    healthCheck(): Promise<ResponseContent<paths['/api/health']['get']>>;
+    getStatus(): Promise<ResponseContent<paths['/api/status']['get']>>;
+}
+
+/**
+ * MIME type utilities for Semiont
+ *
+ * Initial support for:
+ * - text/plain
+ * - text/markdown
+ * - image/png
+ * - image/jpeg
+ */
+/**
+ * Map MIME type to file extension
+ */
+declare function getExtensionForMimeType(mimeType: string): string;
+/**
+ * Detect if MIME type is an image (png or jpeg only for now)
+ */
+declare function isImageMimeType(mimeType: string): boolean;
+/**
+ * Detect if MIME type is text-based (plain or markdown only for now)
+ */
+declare function isTextMimeType(mimeType: string): boolean;
+/**
+ * Get category for MIME type (for routing to appropriate viewer)
+ */
+type MimeCategory = 'text' | 'image' | 'unsupported';
+declare function getMimeCategory(mimeType: string): MimeCategory;
+
 /**
  * @semiont/api-client
  *
@@ -28,16 +932,8 @@
  * }
  * ```
  */
-export * from './types';
-export * from './client';
-export type { components } from './types';
-import type { components } from './types';
-export type GenerationContext = components['schemas']['GenerationContext'];
-export type AnnotationLLMContextResponse = components['schemas']['AnnotationLLMContextResponse'];
-export type { DetectionProgress, GenerationProgress, ResourceEvent, SSEStream } from './sse/types';
-export { SSEClient } from './sse';
-export type { DetectAnnotationsStreamRequest, GenerateResourceStreamRequest, SSEClientConfig } from './sse';
-export * from './utils';
-export { getExtensionForMimeType, isImageMimeType, isTextMimeType, getMimeCategory, type MimeCategory } from './mime-utils';
-export * from './branded-types';
-//# sourceMappingURL=index.d.ts.map
+
+type GenerationContext = components['schemas']['GenerationContext'];
+type AnnotationLLMContextResponse = components['schemas']['AnnotationLLMContextResponse'];
+
+export { APIError, AccessToken, type AnnotationLLMContextResponse, AnnotationUri, BaseUrl, CloneToken, ContentFormat, type DetectAnnotationsStreamRequest, type DetectionProgress, Email, EntityType, type GenerateResourceStreamRequest, type GenerationContext, type GenerationProgress, GoogleCredential, JobId, type MimeCategory, Motivation, RefreshToken, ResourceAnnotationUri, type ResourceEvent, ResourceUri, SSEClient, type SSEClientConfig, type SSEStream, SearchQuery, SemiontApiClient, type SemiontApiClientConfig, UserDID, components, getExtensionForMimeType, getMimeCategory, isImageMimeType, isTextMimeType, paths };