@semiont/api-client 0.2.2-build.15 → 0.2.2

package/dist/index.js

@@ -1,62 +1,1600 @@
-"use strict";
-/**
- * @semiont/api-client
- *
- * Complete SDK for Semiont - types, client, and utilities
- *
- * This package provides:
- * - TypeScript types generated from the OpenAPI specification
- * - A SemiontApiClient class for making API requests
- * - Utilities for working with annotations, events, and text
- *
- * Example:
- * ```typescript
- * import { SemiontApiClient, isReference, getExactText } from '@semiont/api-client';
- *
- * const client = new SemiontApiClient({ baseUrl: 'http://localhost:4000' });
- * await client.authenticateLocal('user@example.com', '123456');
- *
- * const doc = await client.createResource({
- *   name: 'My Resource',
- *   content: 'Hello World',
- *   format: 'text/plain',
- *   entityTypes: ['example']
- * });
- *
- * // Use utilities
- * if (isReference(annotation)) {
- *   const text = getExactText(annotation.target.selector);
- * }
- * ```
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+import ky from 'ky';
+
+// src/client.ts
+
+// src/sse/stream.ts
+function createSSEStream(url, fetchOptions, config) {
+  const abortController = new AbortController();
+  let progressCallback = null;
+  let completeCallback = null;
+  let errorCallback = null;
+  const customHandlers = /* @__PURE__ */ new Map();
+  let closed = false;
+  const connect = async () => {
+    try {
+      const response = await fetch(url, {
+        ...fetchOptions,
+        signal: abortController.signal,
+        headers: {
+          ...fetchOptions.headers,
+          "Accept": "text/event-stream"
+        }
+      });
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw new Error(errorData.message || `HTTP ${response.status}: ${response.statusText}`);
+      }
+      if (!response.body) {
+        throw new Error("Response body is null - server did not return a stream");
+      }
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      let eventType = "";
+      let eventData = "";
+      let eventId = "";
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done || closed) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+          if (line.startsWith("event:")) {
+            eventType = line.slice(6).trim();
+          } else if (line.startsWith("data:")) {
+            eventData = line.slice(5).trim();
+          } else if (line.startsWith("id:")) {
+            eventId = line.slice(3).trim();
+          } else if (line === "") {
+            if (eventData && !closed) {
+              handleEvent(eventType, eventData, eventId);
+              if (closed) break;
+              eventType = "";
+              eventData = "";
+              eventId = "";
+            }
+          }
+        }
+        if (closed) break;
+      }
+    } catch (error) {
+      if (error instanceof Error && error.name !== "AbortError") {
+        errorCallback?.(error);
+      }
+    }
+  };
+  const handleEvent = (eventType, data, _id) => {
+    if (data.startsWith(":")) {
+      return;
+    }
+    try {
+      const parsed = JSON.parse(data);
+      if (config.customEventHandler) {
+        const handler = customHandlers.get(eventType);
+        if (handler) {
+          handler(parsed);
+          return;
+        }
+        progressCallback?.(parsed);
+        return;
+      }
+      if (config.progressEvents.includes(eventType)) {
+        progressCallback?.(parsed);
+      }
+      if (config.completeEvent && eventType === config.completeEvent) {
+        completeCallback?.(parsed);
+        closed = true;
+        abortController.abort();
+      }
+      if (config.errorEvent && eventType === config.errorEvent) {
+        errorCallback?.(new Error(parsed.message || "Stream error"));
+        closed = true;
+        abortController.abort();
+      }
+    } catch (error) {
+      console.error("[SSE] Failed to parse event data:", error);
+      console.error("[SSE] Event type:", eventType);
+      console.error("[SSE] Data:", data);
+    }
+  };
+  connect();
+  return {
+    onProgress(callback) {
+      progressCallback = callback;
+    },
+    onComplete(callback) {
+      completeCallback = callback;
+    },
+    onError(callback) {
+      errorCallback = callback;
+    },
+    close() {
+      abortController.abort();
+    },
+    // Internal method for custom event handlers (used by resourceEvents)
+    on(event, callback) {
+      customHandlers.set(event, callback);
+    }
+  };
+}
+
+// src/sse/index.ts
+var SSEClient = class {
+  baseUrl;
+  accessToken = null;
+  constructor(config) {
+    this.baseUrl = config.baseUrl.endsWith("/") ? config.baseUrl.slice(0, -1) : config.baseUrl;
+    this.accessToken = config.accessToken || null;
+  }
+  /**
+   * Set the access token for authenticated requests
+   */
+  setAccessToken(token) {
+    this.accessToken = token;
+  }
+  /**
+   * Clear the access token
+   */
+  clearAccessToken() {
+    this.accessToken = null;
+  }
+  /**
+   * Get common headers for SSE requests
+   */
+  getHeaders() {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.accessToken) {
+      headers["Authorization"] = `Bearer ${this.accessToken}`;
+    }
+    return headers;
+  }
+  /**
+   * Extract resource ID from URI
+   *
+   * Handles both full URIs and plain IDs:
+   * - 'http://localhost:4000/resources/doc-123' -> 'doc-123'
+   * - 'doc-123' -> 'doc-123'
+   */
+  extractId(uri) {
+    const parts = uri.split("/");
+    return parts[parts.length - 1];
+  }
+  /**
+   * 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, request) {
+    const id = this.extractId(resourceId);
+    const url = `${this.baseUrl}/resources/${id}/detect-annotations-stream`;
+    return createSSEStream(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(request)
+      },
+      {
+        progressEvents: ["detection-started", "detection-progress"],
+        completeEvent: "detection-complete",
+        errorEvent: "detection-error"
+      }
+    );
+  }
+  /**
+   * 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, annotationId, request) {
+    const resId = this.extractId(resourceId);
+    const annId = this.extractId(annotationId);
+    const url = `${this.baseUrl}/resources/${resId}/annotations/${annId}/generate-resource-stream`;
+    return createSSEStream(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(request)
+      },
+      {
+        progressEvents: ["generation-started", "generation-progress"],
+        completeEvent: "generation-complete",
+        errorEvent: "generation-error"
+      }
+    );
+  }
+  /**
+   * 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, request = {}) {
+    const id = this.extractId(resourceId);
+    const url = `${this.baseUrl}/resources/${id}/detect-highlights-stream`;
+    return createSSEStream(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(request)
+      },
+      {
+        progressEvents: ["highlight-detection-started", "highlight-detection-progress"],
+        completeEvent: "highlight-detection-complete",
+        errorEvent: "highlight-detection-error"
+      }
+    );
+  }
+  /**
+   * 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, request = {}) {
+    const id = this.extractId(resourceId);
+    const url = `${this.baseUrl}/resources/${id}/detect-assessments-stream`;
+    return createSSEStream(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(request)
+      },
+      {
+        progressEvents: ["assessment-detection-started", "assessment-detection-progress"],
+        completeEvent: "assessment-detection-complete",
+        errorEvent: "assessment-detection-error"
+      }
+    );
+  }
+  /**
+   * 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, request = {}) {
+    const id = this.extractId(resourceId);
+    const url = `${this.baseUrl}/resources/${id}/detect-comments-stream`;
+    return createSSEStream(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(request)
+      },
+      {
+        progressEvents: ["comment-detection-started", "comment-detection-progress"],
+        completeEvent: "comment-detection-complete",
+        errorEvent: "comment-detection-error"
+      }
+    );
+  }
+  /**
+   * 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, request) {
+    const id = this.extractId(resourceId);
+    const url = `${this.baseUrl}/resources/${id}/detect-tags-stream`;
+    return createSSEStream(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(request)
+      },
+      {
+        progressEvents: ["tag-detection-started", "tag-detection-progress"],
+        completeEvent: "tag-detection-complete",
+        errorEvent: "tag-detection-error"
+      }
+    );
+  }
+  /**
+   * 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) {
+    const id = this.extractId(resourceId);
+    const url = `${this.baseUrl}/resources/${id}/events/stream`;
+    return createSSEStream(
+      url,
+      {
+        method: "GET",
+        headers: this.getHeaders()
+      },
+      {
+        progressEvents: ["*"],
+        // Accept all event types
+        completeEvent: null,
+        // Long-lived stream - no completion
+        errorEvent: "error",
+        // Generic error event
+        customEventHandler: true
+        // Use custom event handling
+      }
+    );
+  }
+};
+
+// src/client.ts
+var APIError = class extends Error {
+  constructor(message, status, statusText, details) {
+    super(message);
+    this.status = status;
+    this.statusText = statusText;
+    this.details = details;
+    this.name = "APIError";
+  }
+};
+var SemiontApiClient = class {
+  http;
+  baseUrl;
+  accessToken = null;
+  /**
+   * 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();
+   * ```
+   */
+  sse;
+  constructor(config) {
+    const { baseUrl: baseUrl2, accessToken: accessToken2, timeout = 3e4, retry = 2 } = config;
+    this.baseUrl = baseUrl2.endsWith("/") ? baseUrl2.slice(0, -1) : baseUrl2;
+    this.http = ky.create({
+      timeout,
+      retry,
+      hooks: {
+        beforeRequest: [
+          (request) => {
+            if (this.accessToken) {
+              request.headers.set("Authorization", `Bearer ${this.accessToken}`);
+            }
+          }
+        ],
+        beforeError: [
+          async (error) => {
+            const { response } = error;
+            if (response) {
+              const body = await response.json().catch(() => ({}));
+              throw new APIError(
+                body.message || `HTTP ${response.status}: ${response.statusText}`,
+                response.status,
+                response.statusText,
+                body
+              );
+            }
+            return error;
+          }
+        ]
+      }
+    });
+    if (accessToken2) {
+      this.accessToken = accessToken2;
+    }
+    this.sse = new SSEClient({
+      baseUrl: this.baseUrl,
+      accessToken: this.accessToken || void 0
+    });
+  }
+  /**
+   * Set the access token for authenticated requests
+   */
+  setAccessToken(token) {
+    this.accessToken = token;
+    this.sse.setAccessToken(token);
+  }
+  /**
+   * Clear the access token
+   */
+  clearAccessToken() {
+    this.accessToken = null;
+    this.sse.clearAccessToken();
+  }
+  // ============================================================================
+  // AUTHENTICATION
+  // ============================================================================
+  async authenticatePassword(email2, password) {
+    const response = await this.http.post(`${this.baseUrl}/api/tokens/password`, { json: { email: email2, password } }).json();
+    if (response.token) {
+      this.setAccessToken(response.token);
+    }
+    return response;
+  }
+  async refreshToken(token) {
+    const response = await this.http.post(`${this.baseUrl}/api/tokens/refresh`, { json: { refreshToken: token } }).json();
+    if (response.access_token) {
+      this.setAccessToken(response.access_token);
+    }
+    return response;
+  }
+  async authenticateGoogle(credential) {
+    const response = await this.http.post(`${this.baseUrl}/api/tokens/google`, { json: { credential } }).json();
+    if (response.token) {
+      this.setAccessToken(response.token);
+    }
+    return response;
+  }
+  async generateMCPToken() {
+    return this.http.post(`${this.baseUrl}/api/tokens/mcp-generate`).json();
+  }
+  // ============================================================================
+  // USERS
+  // ============================================================================
+  async getMe() {
+    return this.http.get(`${this.baseUrl}/api/users/me`).json();
+  }
+  async acceptTerms() {
+    return this.http.post(`${this.baseUrl}/api/users/accept-terms`).json();
+  }
+  async logout() {
+    return this.http.post(`${this.baseUrl}/api/users/logout`).json();
+  }
+  // ============================================================================
+  // RESOURCES
+  // ============================================================================
+  /**
+   * 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
+   */
+  async createResource(data) {
+    const formData = new FormData();
+    formData.append("name", data.name);
+    formData.append("format", data.format);
+    if (data.file instanceof File) {
+      formData.append("file", data.file);
+    } else if (Buffer.isBuffer(data.file)) {
+      const blob = new Blob([data.file], { type: data.format });
+      formData.append("file", blob, data.name);
+    } else {
+      throw new Error("file must be a File or Buffer");
+    }
+    if (data.entityTypes && data.entityTypes.length > 0) {
+      formData.append("entityTypes", JSON.stringify(data.entityTypes));
+    }
+    if (data.language) {
+      formData.append("language", data.language);
+    }
+    if (data.creationMethod) {
+      formData.append("creationMethod", data.creationMethod);
+    }
+    if (data.sourceAnnotationId) {
+      formData.append("sourceAnnotationId", data.sourceAnnotationId);
+    }
+    if (data.sourceResourceId) {
+      formData.append("sourceResourceId", data.sourceResourceId);
+    }
+    return this.http.post(`${this.baseUrl}/resources`, { body: formData }).json();
+  }
+  async getResource(resourceUri2) {
+    return this.http.get(resourceUri2).json();
+  }
+  /**
+   * 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' });
+   * ```
+   */
+  async getResourceRepresentation(resourceUri2, options) {
+    const response = await this.http.get(resourceUri2, {
+      headers: {
+        Accept: options?.accept || "text/plain"
+      }
+    });
+    const contentType = response.headers.get("content-type") || "application/octet-stream";
+    const data = await response.arrayBuffer();
+    return { data, contentType };
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async getResourceRepresentationStream(resourceUri2, options) {
+    const response = await this.http.get(resourceUri2, {
+      headers: {
+        Accept: options?.accept || "text/plain"
+      }
+    });
+    const contentType = response.headers.get("content-type") || "application/octet-stream";
+    if (!response.body) {
+      throw new Error("Response body is null - cannot create stream");
+    }
+    return { stream: response.body, contentType };
+  }
+  async listResources(limit, archived, query) {
+    const searchParams = new URLSearchParams();
+    if (limit) searchParams.append("limit", limit.toString());
+    if (archived !== void 0) searchParams.append("archived", archived.toString());
+    if (query) searchParams.append("q", query);
+    return this.http.get(`${this.baseUrl}/resources`, { searchParams }).json();
+  }
+  async updateResource(resourceUri2, data) {
+    return this.http.patch(resourceUri2, { json: data }).json();
+  }
+  async getResourceEvents(resourceUri2) {
+    return this.http.get(`${resourceUri2}/events`).json();
+  }
+  async getResourceAnnotations(resourceUri2) {
+    return this.http.get(`${resourceUri2}/annotations`).json();
+  }
+  async getAnnotationLLMContext(resourceUri2, annotationId, options) {
+    const searchParams = new URLSearchParams();
+    if (options?.contextWindow) {
+      searchParams.append("contextWindow", options.contextWindow.toString());
+    }
+    return this.http.get(
+      `${resourceUri2}/annotations/${annotationId}/llm-context`,
+      { searchParams }
+    ).json();
+  }
+  async getResourceReferencedBy(resourceUri2) {
+    return this.http.get(`${resourceUri2}/referenced-by`).json();
+  }
+  async generateCloneToken(resourceUri2) {
+    return this.http.post(`${resourceUri2}/clone-with-token`).json();
+  }
+  async getResourceByToken(token) {
+    return this.http.get(`${this.baseUrl}/api/resources/token/${token}`).json();
+  }
+  async createResourceFromToken(data) {
+    return this.http.post(`${this.baseUrl}/api/resources/create-from-token`, { json: data }).json();
+  }
+  // ============================================================================
+  // ANNOTATIONS
+  // ============================================================================
+  async createAnnotation(resourceUri2, data) {
+    return this.http.post(`${resourceUri2}/annotations`, { json: data }).json();
+  }
+  async getAnnotation(annotationUri2) {
+    return this.http.get(annotationUri2).json();
+  }
+  async getResourceAnnotation(annotationUri2) {
+    return this.http.get(annotationUri2).json();
+  }
+  async listAnnotations(resourceUri2, motivation) {
+    const searchParams = new URLSearchParams();
+    if (motivation) searchParams.append("motivation", motivation);
+    return this.http.get(`${resourceUri2}/annotations`, { searchParams }).json();
+  }
+  async deleteAnnotation(annotationUri2) {
+    await this.http.delete(annotationUri2);
+  }
+  async updateAnnotationBody(annotationUri2, data) {
+    return this.http.put(`${annotationUri2}/body`, {
+      json: data
+    }).json();
+  }
+  async getAnnotationHistory(annotationUri2) {
+    return this.http.get(`${annotationUri2}/history`).json();
+  }
+  // ============================================================================
+  // ENTITY TYPES
+  // ============================================================================
+  async addEntityType(type) {
+    return this.http.post(`${this.baseUrl}/api/entity-types`, { json: { type } }).json();
+  }
+  async addEntityTypesBulk(types) {
+    return this.http.post(`${this.baseUrl}/api/entity-types/bulk`, { json: { tags: types } }).json();
+  }
+  async listEntityTypes() {
+    return this.http.get(`${this.baseUrl}/api/entity-types`).json();
+  }
+  // ============================================================================
+  // ADMIN
+  // ============================================================================
+  async listUsers() {
+    return this.http.get(`${this.baseUrl}/api/admin/users`).json();
+  }
+  async getUserStats() {
+    return this.http.get(`${this.baseUrl}/api/admin/users/stats`).json();
+  }
+  /**
+   * Update a user by ID
+   * Note: Users use DID identifiers (did:web:domain:users:id), not HTTP URIs.
+   */
+  async updateUser(id, data) {
+    return this.http.patch(`${this.baseUrl}/api/admin/users/${id}`, { json: data }).json();
+  }
+  async getOAuthConfig() {
+    return this.http.get(`${this.baseUrl}/api/admin/oauth/config`).json();
+  }
+  // ============================================================================
+  // JOB STATUS
+  // ============================================================================
+  async getJobStatus(id) {
+    return this.http.get(`${this.baseUrl}/api/jobs/${id}`).json();
+  }
+  /**
+   * Poll a job until it completes or fails
+   * @param id - The job ID to poll
+   * @param options - Polling options
+   * @returns The final job status
+   */
+  async pollJobUntilComplete(id, options) {
+    const interval = options?.interval ?? 1e3;
+    const timeout = options?.timeout ?? 6e4;
+    const startTime = Date.now();
+    while (true) {
+      const status = await this.getJobStatus(id);
+      if (options?.onProgress) {
+        options.onProgress(status);
+      }
+      if (status.status === "complete" || status.status === "failed" || status.status === "cancelled") {
+        return status;
+      }
+      if (Date.now() - startTime > timeout) {
+        throw new Error(`Job polling timeout after ${timeout}ms`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+  }
+  // ============================================================================
+  // LLM CONTEXT
+  // ============================================================================
+  async getResourceLLMContext(resourceUri2, options) {
+    const searchParams = new URLSearchParams();
+    if (options?.depth !== void 0) searchParams.append("depth", options.depth.toString());
+    if (options?.maxResources !== void 0) searchParams.append("maxResources", options.maxResources.toString());
+    if (options?.includeContent !== void 0) searchParams.append("includeContent", options.includeContent.toString());
+    if (options?.includeSummary !== void 0) searchParams.append("includeSummary", options.includeSummary.toString());
+    return this.http.get(`${resourceUri2}/llm-context`, { searchParams }).json();
+  }
+  // ============================================================================
+  // SYSTEM STATUS
+  // ============================================================================
+  async healthCheck() {
+    return this.http.get(`${this.baseUrl}/api/health`).json();
+  }
+  async getStatus() {
+    return this.http.get(`${this.baseUrl}/api/status`).json();
+  }
+};
+
+// src/branded-types.ts
+function email(value) {
+  return value;
+}
+function authCode(value) {
+  return value;
+}
+function googleCredential(value) {
+  return value;
+}
+function accessToken(value) {
+  return value;
+}
+function refreshToken(value) {
+  return value;
+}
+function mcpToken(value) {
+  return value;
+}
+function cloneToken(value) {
+  return value;
+}
+function jobId(value) {
+  return value;
+}
+function userDID(value) {
+  return value;
+}
+function entityType(value) {
+  return value;
+}
+function searchQuery(value) {
+  return value;
+}
+function baseUrl(value) {
+  return value;
+}
+function resourceUri(uri) {
+  if (!uri.startsWith("http://") && !uri.startsWith("https://")) {
+    throw new TypeError(`Expected ResourceUri, got: ${uri}`);
+  }
+  return uri;
+}
+function annotationUri(uri) {
+  if (!uri.startsWith("http://") && !uri.startsWith("https://")) {
+    throw new TypeError(`Expected AnnotationUri, got: ${uri}`);
+  }
+  return uri;
+}
+function resourceAnnotationUri(uri) {
+  if (!uri.startsWith("http://") && !uri.startsWith("https://")) {
+    throw new TypeError(`Expected ResourceAnnotationUri, got: ${uri}`);
+  }
+  if (!uri.includes("/resources/") || !uri.includes("/annotations/")) {
+    throw new TypeError(`Expected nested ResourceAnnotationUri format, got: ${uri}`);
+  }
+  return uri;
+}
+
+// src/utils/annotations.ts
+function getBodySource(body) {
+  if (Array.isArray(body)) {
+    for (const item of body) {
+      if (typeof item === "object" && item !== null && "type" in item && "source" in item) {
+        const itemType = item.type;
+        const itemSource = item.source;
+        if (itemType === "SpecificResource" && typeof itemSource === "string") {
+          return resourceUri(itemSource);
+        }
+      }
+    }
+    return null;
+  }
+  if (typeof body === "object" && body !== null && "type" in body && "source" in body) {
+    const bodyType = body.type;
+    const bodySource = body.source;
+    if (bodyType === "SpecificResource" && typeof bodySource === "string") {
+      return resourceUri(bodySource);
+    }
+  }
+  return null;
+}
+function getBodyType(body) {
+  if (Array.isArray(body)) {
+    if (body.length === 0) {
+      return null;
+    }
+    if (typeof body[0] === "object" && body[0] !== null && "type" in body[0]) {
+      const firstType = body[0].type;
+      if (firstType === "TextualBody" || firstType === "SpecificResource") {
+        return firstType;
+      }
+    }
+    return null;
+  }
+  if (typeof body === "object" && body !== null && "type" in body) {
+    const bodyType = body.type;
+    if (bodyType === "TextualBody" || bodyType === "SpecificResource") {
+      return bodyType;
+    }
+  }
+  return null;
+}
+function isBodyResolved(body) {
+  return getBodySource(body) !== null;
+}
+function getTargetSource(target) {
+  if (typeof target === "string") {
+    return resourceUri(target);
+  }
+  return resourceUri(target.source);
+}
+function getTargetSelector(target) {
+  if (typeof target === "string") {
+    return void 0;
+  }
+  return target.selector;
+}
+function hasTargetSelector(target) {
+  return typeof target !== "string" && target.selector !== void 0;
+}
+function getEntityTypes(annotation) {
+  if (Array.isArray(annotation.body)) {
+    const entityTags = [];
+    for (const item of annotation.body) {
+      if (typeof item === "object" && item !== null && "type" in item && "value" in item && "purpose" in item) {
+        const itemType = item.type;
+        const itemValue = item.value;
+        const itemPurpose = item.purpose;
+        if (itemType === "TextualBody" && itemPurpose === "tagging" && typeof itemValue === "string" && itemValue.length > 0) {
+          entityTags.push(itemValue);
+        }
+      }
+    }
+    return entityTags;
+  }
+  return [];
+}
+function isHighlight(annotation) {
+  return annotation.motivation === "highlighting";
+}
+function isReference(annotation) {
+  return annotation.motivation === "linking";
+}
+function isAssessment(annotation) {
+  return annotation.motivation === "assessing";
+}
+function isComment(annotation) {
+  return annotation.motivation === "commenting";
+}
+function isTag(annotation) {
+  return annotation.motivation === "tagging";
+}
+function getCommentText(annotation) {
+  if (!isComment(annotation)) return void 0;
+  const body = Array.isArray(annotation.body) ? annotation.body[0] : annotation.body;
+  if (body && "value" in body) {
+    return body.value;
+  }
+  return void 0;
+}
+function getTagCategory(annotation) {
+  if (!isTag(annotation)) return void 0;
+  const bodies = Array.isArray(annotation.body) ? annotation.body : [annotation.body];
+  const taggingBody = bodies.find((b) => b && "purpose" in b && b.purpose === "tagging");
+  if (taggingBody && "value" in taggingBody) {
+    return taggingBody.value;
+  }
+  return void 0;
+}
+function getTagSchemaId(annotation) {
+  if (!isTag(annotation)) return void 0;
+  const bodies = Array.isArray(annotation.body) ? annotation.body : [annotation.body];
+  const classifyingBody = bodies.find((b) => b && "purpose" in b && b.purpose === "classifying");
+  if (classifyingBody && "value" in classifyingBody) {
+    return classifyingBody.value;
+  }
+  return void 0;
+}
+function isStubReference(annotation) {
+  return isReference(annotation) && !isBodyResolved(annotation.body);
+}
+function isResolvedReference(annotation) {
+  return isReference(annotation) && isBodyResolved(annotation.body);
+}
+function getExactText(selector) {
+  if (!selector) {
+    return "";
+  }
+  const selectors = Array.isArray(selector) ? selector : [selector];
+  const quoteSelector = selectors.find((s) => s.type === "TextQuoteSelector");
+  if (quoteSelector) {
+    return quoteSelector.exact;
+  }
+  return "";
+}
+function getAnnotationExactText(annotation) {
+  const selector = getTargetSelector(annotation.target);
+  return getExactText(selector);
+}
+function getPrimarySelector(selector) {
+  if (Array.isArray(selector)) {
+    if (selector.length === 0) {
+      throw new Error("Empty selector array");
+    }
+    const first = selector[0];
+    if (!first) {
+      throw new Error("Invalid selector array");
+    }
+    return first;
+  }
+  return selector;
+}
+function getTextPositionSelector(selector) {
+  if (!selector) return null;
+  const selectors = Array.isArray(selector) ? selector : [selector];
+  const found = selectors.find((s) => s.type === "TextPositionSelector");
+  if (!found) return null;
+  return found.type === "TextPositionSelector" ? found : null;
+}
+function getTextQuoteSelector(selector) {
+  const selectors = Array.isArray(selector) ? selector : [selector];
+  const found = selectors.find((s) => s.type === "TextQuoteSelector");
+  if (!found) return null;
+  return found.type === "TextQuoteSelector" ? found : null;
+}
+function getSvgSelector(selector) {
+  if (!selector) return null;
+  const selectors = Array.isArray(selector) ? selector : [selector];
+  const found = selectors.find((s) => s.type === "SvgSelector");
+  if (!found) return null;
+  return found.type === "SvgSelector" ? found : null;
+}
+function validateSvgMarkup(svg) {
+  if (!svg.includes('xmlns="http://www.w3.org/2000/svg"')) {
+    return 'SVG must include xmlns="http://www.w3.org/2000/svg" attribute';
+  }
+  if (!svg.includes("<svg") || !svg.includes("</svg>")) {
+    return "SVG must have opening and closing tags";
+  }
+  const shapeElements = ["rect", "circle", "ellipse", "polygon", "polyline", "path", "line"];
+  const hasShape = shapeElements.some(
+    (shape) => svg.includes(`<${shape}`) || svg.includes(`<${shape} `)
+  );
+  if (!hasShape) {
+    return "SVG must contain at least one shape element (rect, circle, ellipse, polygon, polyline, path, or line)";
+  }
+  return null;
+}
+function extractBoundingBox(svg) {
+  const viewBoxMatch = svg.match(/<svg[^>]*viewBox="([^"]+)"/);
+  if (viewBoxMatch) {
+    const values = viewBoxMatch[1].split(/\s+/).map(parseFloat);
+    if (values.length === 4 && values.every((v) => !isNaN(v))) {
+      return {
+        x: values[0],
+        y: values[1],
+        width: values[2],
+        height: values[3]
+      };
+    }
+  }
+  const svgTagMatch = svg.match(/<svg[^>]*>/);
+  if (svgTagMatch) {
+    const svgTag = svgTagMatch[0];
+    const widthMatch = svgTag.match(/width="([^"]+)"/);
+    const heightMatch = svgTag.match(/height="([^"]+)"/);
+    if (widthMatch && heightMatch) {
+      const width = parseFloat(widthMatch[1]);
+      const height = parseFloat(heightMatch[1]);
+      if (!isNaN(width) && !isNaN(height)) {
+        return { x: 0, y: 0, width, height };
+      }
+    }
+  }
+  return null;
+}
+
+// src/utils/events.ts
+function getAnnotationUriFromEvent(event) {
+  const eventData = event.event;
+  const payload = eventData.payload;
+  if (!payload) {
+    return null;
+  }
+  switch (eventData.type) {
+    case "annotation.added":
+      return payload.annotation?.id || null;
+    case "annotation.removed":
+    case "annotation.body.updated":
+      if (payload.annotationId && eventData.resourceId) {
+        try {
+          const resourceUri2 = eventData.resourceId;
+          const baseUrl2 = resourceUri2.substring(0, resourceUri2.lastIndexOf("/resources/"));
+          return `${baseUrl2}/annotations/${payload.annotationId}`;
+        } catch (e) {
+          return null;
+        }
+      }
+      return null;
+    default:
+      return null;
+  }
+}
+function isEventRelatedToAnnotation(event, annotationUri2) {
+  const eventAnnotationUri = getAnnotationUriFromEvent(event);
+  return eventAnnotationUri === annotationUri2;
+}
+function isResourceEvent(event) {
+  return event && typeof event.event === "object" && typeof event.event.id === "string" && typeof event.event.timestamp === "string" && typeof event.event.resourceId === "string" && typeof event.event.type === "string" && typeof event.metadata === "object" && typeof event.metadata.sequenceNumber === "number";
+}
+function formatEventType(type, t, payload) {
+  switch (type) {
+    case "resource.created":
+      return t("resourceCreated");
+    case "resource.cloned":
+      return t("resourceCloned");
+    case "resource.archived":
+      return t("resourceArchived");
+    case "resource.unarchived":
+      return t("resourceUnarchived");
+    case "annotation.added": {
+      const motivation = payload?.annotation?.motivation;
+      if (motivation === "highlighting") return t("highlightAdded");
+      if (motivation === "linking") return t("referenceCreated");
+      if (motivation === "assessing") return t("assessmentAdded");
+      return t("annotationAdded");
+    }
+    case "annotation.removed": {
+      return t("annotationRemoved");
+    }
+    case "annotation.body.updated": {
+      return t("annotationBodyUpdated");
+    }
+    case "entitytag.added":
+      return t("entitytagAdded");
+    case "entitytag.removed":
+      return t("entitytagRemoved");
+    case "entitytype.added":
+      return t("entitytypeAdded");
+    case "job.completed":
+    case "job.started":
+    case "job.progress":
+    case "job.failed":
+      return t("jobEvent");
+    default:
+      const _exhaustiveCheck = type;
+      return _exhaustiveCheck;
+  }
+}
+function getEventEmoji(type, payload) {
+  switch (type) {
+    case "resource.created":
+    case "resource.cloned":
+    case "resource.archived":
+    case "resource.unarchived":
+      return "\u{1F4C4}";
+    case "annotation.added": {
+      const motivation = payload?.annotation?.motivation;
+      if (motivation === "highlighting") return "\u{1F7E1}";
+      if (motivation === "linking") return "\u{1F535}";
+      if (motivation === "assessing") return "\u{1F534}";
+      return "\u{1F4DD}";
+    }
+    case "annotation.removed": {
+      return "\u{1F5D1}\uFE0F";
+    }
+    case "annotation.body.updated": {
+      return "\u270F\uFE0F";
+    }
+    case "entitytag.added":
+    case "entitytag.removed":
+      return "\u{1F3F7}\uFE0F";
+    case "entitytype.added":
+      return "\u{1F3F7}\uFE0F";
+    // Same emoji as entitytag (global entity type collection)
+    case "job.completed":
+      return "\u{1F517}";
+    // Link emoji for linked document creation
+    case "job.started":
+    case "job.progress":
+      return "\u2699\uFE0F";
+    // Gear for job processing
+    case "job.failed":
+      return "\u274C";
+    // X mark for failed jobs
+    default:
+      const _exhaustiveCheck = type;
+      return _exhaustiveCheck;
+  }
+}
+function formatRelativeTime(timestamp, t) {
+  const date = new Date(timestamp);
+  const now = /* @__PURE__ */ new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffMins = Math.floor(diffMs / 6e4);
+  const diffHours = Math.floor(diffMs / 36e5);
+  const diffDays = Math.floor(diffMs / 864e5);
+  if (diffMins < 1) return t("justNow");
+  if (diffMins < 60) return t("minutesAgo", { count: diffMins });
+  if (diffHours < 24) return t("hoursAgo", { count: diffHours });
+  if (diffDays < 7) return t("daysAgo", { count: diffDays });
+  return date.toLocaleDateString();
+}
+function truncateText(text, maxLength = 50) {
+  const trimmed = text.trim();
+  return trimmed.length > maxLength ? trimmed.substring(0, maxLength) + "..." : trimmed;
+}
+function getEventDisplayContent(event, annotations, allEvents) {
+  const eventData = event.event;
+  const payload = eventData.payload;
+  switch (eventData.type) {
+    case "resource.created":
+    case "resource.cloned": {
+      return { exact: payload.name, isQuoted: false, isTag: false };
+    }
+    // Unified annotation events
+    case "annotation.body.updated": {
+      const annotation = annotations.find(
+        (a) => a.id.endsWith(`/annotations/${payload.annotationId}`)
+      );
+      if (annotation?.target) {
+        try {
+          const targetSelector = getTargetSelector(annotation.target);
+          const exact = getExactText(targetSelector);
+          if (exact) {
+            return { exact: truncateText(exact), isQuoted: true, isTag: false };
+          }
+        } catch {
+        }
+      }
+      return null;
+    }
+    case "annotation.removed": {
+      const addedEvent = allEvents.find(
+        (e) => e.event.type === "annotation.added" && e.event.payload.annotation?.id?.endsWith(`/annotations/${payload.annotationId}`)
+      );
+      if (addedEvent) {
+        const addedPayload = addedEvent.event.payload;
+        try {
+          const exact = getExactText(addedPayload.annotation.target.selector);
+          if (exact) {
+            return { exact: truncateText(exact), isQuoted: true, isTag: false };
+          }
+        } catch {
+        }
+      }
+      return null;
+    }
+    case "annotation.added": {
+      try {
+        const exact = getExactText(payload.annotation.target.selector);
+        if (exact) {
+          return { exact: truncateText(exact), isQuoted: true, isTag: false };
+        }
+      } catch {
+      }
+      return null;
+    }
+    case "entitytag.added":
+    case "entitytag.removed": {
+      return { exact: payload.entityType, isQuoted: false, isTag: true };
+    }
+    case "job.completed": {
+      if (payload.annotationUri) {
+        const annotation = annotations.find(
+          (a) => a.id === payload.annotationUri
+        );
+        if (annotation?.target) {
+          try {
+            const targetSelector = getTargetSelector(annotation.target);
+            const exact = getExactText(targetSelector);
+            if (exact) {
+              return { exact: truncateText(exact), isQuoted: true, isTag: false };
+            }
+          } catch {
+          }
+        }
+      }
+      return null;
+    }
+    default:
+      return null;
+  }
+}
+function getEventEntityTypes(event) {
+  const eventData = event.event;
+  if (eventData.type === "annotation.added") {
+    const payload = eventData.payload;
+    const motivation = payload?.annotation?.motivation;
+    if (motivation === "linking") {
+      return payload.annotation?.body?.entityTypes ?? [];
+    }
+  }
+  return [];
+}
+function getResourceCreationDetails(event) {
+  const eventData = event.event;
+  const payload = eventData.payload;
+  if (eventData.type === "resource.created") {
+    return {
+      type: "created",
+      method: payload.creationMethod || "unknown",
+      userId: eventData.userId,
+      metadata: payload.metadata
+    };
+  }
+  if (eventData.type === "resource.cloned") {
+    return {
+      type: "cloned",
+      method: payload.creationMethod || "clone",
+      userId: eventData.userId,
+      sourceDocId: payload.parentResourceId,
+      parentResourceId: payload.parentResourceId,
+      metadata: payload.metadata
+    };
+  }
+  return null;
+}
+
+// src/utils/locales.ts
+var LOCALES = [
+  { code: "ar", nativeName: "\u0627\u0644\u0639\u0631\u0628\u064A\u0629", englishName: "Arabic" },
+  { code: "bn", nativeName: "\u09AC\u09BE\u0982\u09B2\u09BE", englishName: "Bengali" },
+  { code: "cs", nativeName: "\u010Ce\u0161tina", englishName: "Czech" },
+  { code: "da", nativeName: "Dansk", englishName: "Danish" },
+  { code: "de", nativeName: "Deutsch", englishName: "German" },
+  { code: "el", nativeName: "\u0395\u03BB\u03BB\u03B7\u03BD\u03B9\u03BA\u03AC", englishName: "Greek" },
+  { code: "en", nativeName: "English", englishName: "English" },
+  { code: "es", nativeName: "Espa\xF1ol", englishName: "Spanish" },
+  { code: "fa", nativeName: "\u0641\u0627\u0631\u0633\u06CC", englishName: "Persian" },
+  { code: "fi", nativeName: "Suomi", englishName: "Finnish" },
+  { code: "fr", nativeName: "Fran\xE7ais", englishName: "French" },
+  { code: "he", nativeName: "\u05E2\u05D1\u05E8\u05D9\u05EA", englishName: "Hebrew" },
+  { code: "hi", nativeName: "\u0939\u093F\u0928\u094D\u0926\u0940", englishName: "Hindi" },
+  { code: "id", nativeName: "Bahasa Indonesia", englishName: "Indonesian" },
+  { code: "it", nativeName: "Italiano", englishName: "Italian" },
+  { code: "ja", nativeName: "\u65E5\u672C\u8A9E", englishName: "Japanese" },
+  { code: "ko", nativeName: "\uD55C\uAD6D\uC5B4", englishName: "Korean" },
+  { code: "ms", nativeName: "Bahasa Melayu", englishName: "Malay" },
+  { code: "nl", nativeName: "Nederlands", englishName: "Dutch" },
+  { code: "no", nativeName: "Norsk", englishName: "Norwegian" },
+  { code: "pl", nativeName: "Polski", englishName: "Polish" },
+  { code: "pt", nativeName: "Portugu\xEAs", englishName: "Portuguese" },
+  { code: "ro", nativeName: "Rom\xE2n\u0103", englishName: "Romanian" },
+  { code: "sv", nativeName: "Svenska", englishName: "Swedish" },
+  { code: "th", nativeName: "\u0E44\u0E17\u0E22", englishName: "Thai" },
+  { code: "tr", nativeName: "T\xFCrk\xE7e", englishName: "Turkish" },
+  { code: "uk", nativeName: "\u0423\u043A\u0440\u0430\u0457\u043D\u0441\u044C\u043A\u0430", englishName: "Ukrainian" },
+  { code: "vi", nativeName: "Ti\u1EBFng Vi\u1EC7t", englishName: "Vietnamese" },
+  { code: "zh", nativeName: "\u4E2D\u6587", englishName: "Chinese" }
+];
+var localeByCode = new Map(
+  LOCALES.map((locale) => [locale.code.toLowerCase(), locale])
+);
+function getLocaleInfo(code) {
+  if (!code) return void 0;
+  return localeByCode.get(code.toLowerCase());
+}
+function getLocaleNativeName(code) {
+  return getLocaleInfo(code)?.nativeName;
+}
+function getLocaleEnglishName(code) {
+  return getLocaleInfo(code)?.englishName;
+}
+function formatLocaleDisplay(code) {
+  if (!code) return void 0;
+  const info = getLocaleInfo(code);
+  if (!info) return code;
+  return `${info.nativeName} (${code.toLowerCase()})`;
+}
+function getAllLocaleCodes() {
+  return LOCALES.map((l) => l.code);
+}
+
+// src/utils/resources.ts
+function getResourceId(resource) {
+  if (!resource) return void 0;
+  const fullId = resource["@id"];
+  if (fullId.includes("/resources/")) {
+    const parts = fullId.split("/resources/");
+    const lastPart = parts[parts.length - 1];
+    return lastPart || void 0;
+  }
+  return void 0;
+}
+function getPrimaryRepresentation(resource) {
+  if (!resource?.representations) return void 0;
+  const reps = Array.isArray(resource.representations) ? resource.representations : [resource.representations];
+  return reps[0];
+}
+function getPrimaryMediaType(resource) {
+  return getPrimaryRepresentation(resource)?.mediaType;
+}
+function getChecksum(resource) {
+  return getPrimaryRepresentation(resource)?.checksum;
+}
+function getLanguage(resource) {
+  return getPrimaryRepresentation(resource)?.language;
+}
+
+// src/utils/validation.ts
+var JWTTokenSchema = {
+  parse(token) {
+    if (typeof token !== "string") {
+      throw new Error("Token must be a string");
+    }
+    if (!token || token.length === 0) {
+      throw new Error("Token is required");
+    }
+    const jwtRegex = /^[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]*$/;
+    if (!jwtRegex.test(token)) {
+      throw new Error("Invalid JWT token format");
+    }
+    return token;
+  },
+  safeParse(token) {
+    try {
+      const validated = this.parse(token);
+      return { success: true, data: validated };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : "Invalid JWT token"
+      };
+    }
+  }
 };
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getMimeCategory = exports.isTextMimeType = exports.isImageMimeType = exports.getExtensionForMimeType = exports.SSEClient = void 0;
-// Generated OpenAPI types and client
-__exportStar(require("./types"), exports);
-__exportStar(require("./client"), exports);
-var sse_1 = require("./sse");
-Object.defineProperty(exports, "SSEClient", { enumerable: true, get: function () { return sse_1.SSEClient; } });
-// Handwritten utilities
-__exportStar(require("./utils"), exports);
-var mime_utils_1 = require("./mime-utils");
-Object.defineProperty(exports, "getExtensionForMimeType", { enumerable: true, get: function () { return mime_utils_1.getExtensionForMimeType; } });
-Object.defineProperty(exports, "isImageMimeType", { enumerable: true, get: function () { return mime_utils_1.isImageMimeType; } });
-Object.defineProperty(exports, "isTextMimeType", { enumerable: true, get: function () { return mime_utils_1.isTextMimeType; } });
-Object.defineProperty(exports, "getMimeCategory", { enumerable: true, get: function () { return mime_utils_1.getMimeCategory; } });
-// All branded types (URIs, tokens, identifiers, etc.)
-__exportStar(require("./branded-types"), exports);
+function validateData(schema, data) {
+  try {
+    const validated = schema.parse(data);
+    return { success: true, data: validated };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Validation failed"
+    };
+  }
+}
+function isValidEmail(email2) {
+  if (email2.length < 1 || email2.length > 255) {
+    return false;
+  }
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return emailRegex.test(email2);
+}
+
+// src/mime-utils.ts
+function getExtensionForMimeType(mimeType) {
+  const map = {
+    "text/plain": "txt",
+    "text/markdown": "md",
+    "image/png": "png",
+    "image/jpeg": "jpg"
+  };
+  return map[mimeType] || "dat";
+}
+function isImageMimeType(mimeType) {
+  return mimeType === "image/png" || mimeType === "image/jpeg";
+}
+function isTextMimeType(mimeType) {
+  return mimeType === "text/plain" || mimeType === "text/markdown";
+}
+function getMimeCategory(mimeType) {
+  if (isTextMimeType(mimeType)) {
+    return "text";
+  }
+  if (isImageMimeType(mimeType)) {
+    return "image";
+  }
+  return "unsupported";
+}
+
+export { APIError, JWTTokenSchema, LOCALES, SSEClient, SemiontApiClient, accessToken, annotationUri, authCode, baseUrl, cloneToken, email, entityType, extractBoundingBox, formatEventType, formatLocaleDisplay, formatRelativeTime, getAllLocaleCodes, getAnnotationExactText, getAnnotationUriFromEvent, getBodySource, getBodyType, getChecksum, getCommentText, getEntityTypes, getEventDisplayContent, getEventEmoji, getEventEntityTypes, getExactText, getExtensionForMimeType, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getMimeCategory, getPrimaryMediaType, getPrimaryRepresentation, getPrimarySelector, getResourceCreationDetails, getResourceId, getSvgSelector, getTagCategory, getTagSchemaId, getTargetSelector, getTargetSource, getTextPositionSelector, getTextQuoteSelector, googleCredential, hasTargetSelector, isAssessment, isBodyResolved, isComment, isEventRelatedToAnnotation, isHighlight, isImageMimeType, isReference, isResolvedReference, isResourceEvent, isStubReference, isTag, isTextMimeType, isValidEmail, jobId, mcpToken, refreshToken, resourceAnnotationUri, resourceUri, searchQuery, userDID, validateData, validateSvgMarkup };
+//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map