@semiont/api-client 0.2.28-build.37 → 0.2.28-build.40

package/README.md

@@ -1,5 +1,6 @@
 # @semiont/api-client
 
+[![Tests](https://github.com/The-AI-Alliance/semiont/actions/workflows/package-tests.yml/badge.svg)](https://github.com/The-AI-Alliance/semiont/actions/workflows/package-tests.yml?query=branch%3Amain+is%3Asuccess+job%3A%22Test+api-client%22)
 [![npm version](https://img.shields.io/npm/v/@semiont/api-client.svg)](https://www.npmjs.com/package/@semiont/api-client)
 [![npm downloads](https://img.shields.io/npm/dm/@semiont/api-client.svg)](https://www.npmjs.com/package/@semiont/api-client)
 [![License](https://img.shields.io/npm/l/@semiont/api-client.svg)](https://github.com/The-AI-Alliance/semiont/blob/main/LICENSE)
@@ -104,12 +105,15 @@ const client = new SemiontApiClient({
 
 📖 **[API Reference](./docs/API-Reference.md)** - Complete method documentation
 
+🛠️ **[Utilities Guide](./docs/Utilities.md)** - Text encoding, fuzzy anchoring, SVG utilities
+
 ## Key Features
 
 - **Type-safe** - Generated from OpenAPI spec with branded types
-- **W3C compliant** - Web Annotation standard
+- **W3C compliant** - Web Annotation standard with fuzzy text matching
 - **Real-time** - SSE streaming for long operations
-- **Framework-agnostic** - Works everywhere JavaScript runs
+- **Framework-agnostic** - Pure TypeScript utilities work everywhere
+- **Character encoding** - Proper UTF-8, ISO-8859-1, Windows-1252 support
 
 ## Use Cases
 

package/dist/{index-DHh0ToZB.d.ts → index--2zlsZdR.d.ts}

@@ -3314,14 +3314,6 @@ declare function getTargetSelector(target: Annotation$1['target']): {
  * Check if target has a selector
  */
 declare function hasTargetSelector(target: Annotation$1['target']): boolean;
-/**
- * Extract entity types from annotation bodies
- * Entity types are stored as TextualBody with purpose: "tagging"
- * Accepts any object with a body property matching Annotation['body']
- */
-declare function getEntityTypes(annotation: {
-    body: Annotation$1['body'];
-}): string[];
 /**
  * Type guard to check if an annotation is a highlight
  */
@@ -3348,20 +3340,6 @@ declare function isTag(annotation: Annotation$1): annotation is Annotation$1;
  * @returns The comment text, or undefined if not a comment or no text found
  */
 declare function getCommentText(annotation: Annotation$1): string | undefined;
-/**
- * Extract tag category from a tag annotation's body
- * Tags use dual-body structure: first body has purpose: "tagging" with category value
- * @param annotation - The annotation to extract category from
- * @returns The tag category (e.g., "Issue", "Rule"), or undefined if not a tag or no category found
- */
-declare function getTagCategory(annotation: Annotation$1): string | undefined;
-/**
- * Extract tag schema ID from a tag annotation's body
- * Tags use dual-body structure: second body has purpose: "classifying" with schema ID
- * @param annotation - The annotation to extract schema ID from
- * @returns The schema ID (e.g., "legal-irac"), or undefined if not a tag or no schema found
- */
-declare function getTagSchemaId(annotation: Annotation$1): string | undefined;
 /**
  * Type guard to check if a reference annotation is a stub (unresolved)
  * Stub if no SpecificResource in body array
@@ -3507,6 +3485,45 @@ interface ResourceCreationDetails {
  */
 declare function getResourceCreationDetails(event: StoredEvent): ResourceCreationDetails | null;
 
+/**
+ * Fuzzy Anchoring for W3C Web Annotation TextQuoteSelector
+ *
+ * Uses prefix/suffix context to disambiguate when the same text appears multiple times.
+ * Implements fuzzy matching as specified in the W3C Web Annotation Data Model.
+ *
+ * @see https://www.w3.org/TR/annotation-model/#text-quote-selector
+ */
+interface TextPosition {
+    start: number;
+    end: number;
+}
+/**
+ * Find text using exact match with optional prefix/suffix context
+ *
+ * When the exact text appears multiple times in the content, prefix and suffix
+ * are used to disambiguate and find the correct occurrence.
+ *
+ * @param content - Full text content to search within
+ * @param exact - The exact text to find
+ * @param prefix - Optional text that should appear immediately before the match
+ * @param suffix - Optional text that should appear immediately after the match
+ * @returns Position of the matched text, or null if not found
+ *
+ * @example
+ * ```typescript
+ * const content = "The cat sat. The cat ran.";
+ * // Find second "The cat" occurrence
+ * const pos = findTextWithContext(content, "The cat", "sat. ", " ran");
+ * // Returns { start: 13, end: 20 }
+ * ```
+ */
+declare function findTextWithContext(content: string, exact: string, prefix?: string, suffix?: string): TextPosition | null;
+/**
+ * Verify that a position correctly points to the exact text
+ * Useful for debugging and validation
+ */
+declare function verifyPosition(content: string, position: TextPosition, expectedExact: string): boolean;
+
 /**
  * Locale information
  * Copied from SDK for frontend use
@@ -3570,6 +3587,235 @@ declare function getChecksum(resource: ResourceDescriptor | undefined): string |
  * Get the language from the primary representation
  */
 declare function getLanguage(resource: ResourceDescriptor | undefined): string | undefined;
+/**
+ * Get storage URI from primary representation
+ *
+ * @param resource - ResourceDescriptor
+ * @returns Storage URI or undefined
+ */
+declare function getStorageUri(resource: ResourceDescriptor | undefined): string | undefined;
+/**
+ * Get creator agent from wasAttributedTo
+ * Handles both single agent and array of agents
+ *
+ * @param resource - ResourceDescriptor
+ * @returns First agent or undefined
+ */
+declare function getCreator(resource: ResourceDescriptor | undefined): components['schemas']['Agent'] | undefined;
+/**
+ * Get derived-from URI
+ * Handles both single URI and array of URIs
+ *
+ * @param resource - ResourceDescriptor
+ * @returns First derivation URI or undefined
+ */
+declare function getDerivedFrom(resource: ResourceDescriptor | undefined): string | undefined;
+/**
+ * Check if resource is archived (application-specific field)
+ *
+ * @param resource - ResourceDescriptor
+ * @returns True if archived, false otherwise
+ */
+declare function isArchived(resource: ResourceDescriptor | undefined): boolean;
+/**
+ * Get entity types from resource (application-specific field)
+ *
+ * @param resource - ResourceDescriptor
+ * @returns Array of entity types, empty if not set
+ */
+declare function getResourceEntityTypes(resource: ResourceDescriptor | undefined): string[];
+/**
+ * Check if resource is a draft (application-specific field)
+ *
+ * @param resource - ResourceDescriptor
+ * @returns True if draft, false otherwise
+ */
+declare function isDraft(resource: ResourceDescriptor | undefined): boolean;
+/**
+ * Map charset names to Node.js Buffer encoding names
+ * Node.js Buffer.toString() supports: 'utf8', 'utf16le', 'latin1', 'base64', 'hex', 'ascii', 'binary', 'ucs2'
+ *
+ * @param charset - Charset name (e.g., "UTF-8", "ISO-8859-1", "Windows-1252")
+ * @returns Node.js BufferEncoding
+ */
+declare function getNodeEncoding(charset: string): BufferEncoding;
+/**
+ * Decode a representation buffer to string using the correct charset
+ * Extracts charset from media type and uses appropriate encoding
+ *
+ * @param buffer - The raw representation data
+ * @param mediaType - Media type with optional charset (e.g., "text/plain; charset=iso-8859-1")
+ * @returns Decoded string
+ *
+ * @example
+ * ```typescript
+ * const content = decodeRepresentation(buffer, "text/plain; charset=utf-8");
+ * const legacy = decodeRepresentation(buffer, "text/plain; charset=windows-1252");
+ * ```
+ */
+declare function decodeRepresentation(buffer: Buffer, mediaType: string): string;
+
+/**
+ * SVG Utility Functions
+ *
+ * Utilities for creating, parsing, and manipulating W3C-compliant SVG selectors
+ * for image annotation.
+ */
+interface Point {
+    x: number;
+    y: number;
+}
+interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Create W3C-compliant SVG rectangle selector
+ */
+declare function createRectangleSvg(start: Point, end: Point): string;
+/**
+ * Create W3C-compliant SVG polygon selector
+ */
+declare function createPolygonSvg(points: Point[]): string;
+/**
+ * Create W3C-compliant SVG circle selector
+ */
+declare function createCircleSvg(center: Point, radius: number): string;
+/**
+ * Parse SVG selector to extract shape type and data
+ */
+declare function parseSvgSelector(svg: string): {
+    type: 'rect' | 'polygon' | 'circle' | 'path';
+    data: any;
+} | null;
+/**
+ * Normalize coordinates from display space to image native resolution
+ */
+declare function normalizeCoordinates(point: Point, displayWidth: number, displayHeight: number, imageWidth: number, imageHeight: number): Point;
+/**
+ * Scale entire SVG selector from display space to image native resolution
+ */
+declare function scaleSvgToNative(svg: string, displayWidth: number, displayHeight: number, imageWidth: number, imageHeight: number): string;
+
+/**
+ * Text context extraction utilities for W3C Web Annotation TextQuoteSelector
+ *
+ * Provides robust prefix/suffix context extraction with word boundary detection
+ * to ensure fuzzy anchoring works correctly when the same text appears multiple times.
+ *
+ * Also provides AI offset validation and correction for handling AI-generated annotations
+ * where the model may return slightly incorrect character offsets.
+ *
+ * @see https://www.w3.org/TR/annotation-model/#text-quote-selector
+ */
+/**
+ * Extract prefix and suffix context for TextQuoteSelector
+ *
+ * Extracts up to 64 characters before and after the selected text,
+ * extending to word boundaries to avoid cutting words in half.
+ * This ensures prefix/suffix are meaningful context for fuzzy anchoring.
+ *
+ * @param content - Full text content
+ * @param start - Start offset of selection
+ * @param end - End offset of selection
+ * @returns Object with prefix and suffix (undefined if at boundaries)
+ *
+ * @example
+ * ```typescript
+ * const content = "The United States Congress...";
+ * const context = extractContext(content, 4, 17); // "United States"
+ * // Returns: { prefix: "The ", suffix: " Congress..." }
+ * // NOT: { prefix: "nited ", suffix: "gress..." }
+ * ```
+ */
+declare function extractContext(content: string, start: number, end: number): {
+    prefix?: string;
+    suffix?: string;
+};
+/**
+ * Result of validating and correcting AI-provided annotation offsets
+ */
+interface ValidatedAnnotation {
+    start: number;
+    end: number;
+    exact: string;
+    prefix?: string;
+    suffix?: string;
+    corrected: boolean;
+    fuzzyMatched?: boolean;
+    matchQuality?: 'exact' | 'case-insensitive' | 'fuzzy';
+}
+/**
+ * Validate and correct AI-provided annotation offsets with fuzzy matching tolerance
+ *
+ * AI models sometimes return offsets that don't match the actual text position,
+ * or provide text with minor variations (case differences, whitespace, typos).
+ *
+ * This function uses a multi-strategy approach:
+ * 1. Check if AI's offsets are exactly correct
+ * 2. Try exact case-sensitive search
+ * 3. Try case-insensitive search
+ * 4. Try fuzzy matching with Levenshtein distance (5% tolerance)
+ *
+ * This ensures we're maximally tolerant of AI errors while still maintaining
+ * annotation quality and logging what corrections were made.
+ *
+ * @param content - Full text content
+ * @param aiStart - Start offset from AI
+ * @param aiEnd - End offset from AI
+ * @param exact - The exact text that should be at this position (from AI)
+ * @returns Validated annotation with corrected offsets and context
+ * @throws Error if no acceptable match can be found
+ *
+ * @example
+ * ```typescript
+ * // AI said start=1143, but actual text is at 1161
+ * const result = validateAndCorrectOffsets(
+ *   content,
+ *   1143,
+ *   1289,
+ *   "the question \"whether..."
+ * );
+ * // Returns: { start: 1161, end: 1303, exact: "...", corrected: true, matchQuality: 'exact', ... }
+ * ```
+ */
+declare function validateAndCorrectOffsets(content: string, aiStart: number, aiEnd: number, exact: string): ValidatedAnnotation;
+
+/**
+ * Text encoding utilities for consistent charset handling
+ *
+ * Ensures frontend decoding matches backend decoding by respecting
+ * charset parameters in mediaType (e.g., "text/plain; charset=iso-8859-1")
+ */
+/**
+ * Extract charset from mediaType parameter
+ *
+ * @param mediaType - Media type with optional charset (e.g., "text/plain; charset=utf-8")
+ * @returns Charset name in lowercase (defaults to "utf-8")
+ *
+ * @example
+ * extractCharset("text/plain; charset=iso-8859-1") // "iso-8859-1"
+ * extractCharset("text/plain") // "utf-8"
+ */
+declare function extractCharset(mediaType: string): string;
+/**
+ * Decode ArrayBuffer to string using charset from mediaType
+ *
+ * Uses TextDecoder with the charset extracted from mediaType parameter.
+ * This ensures the same character space is used for both annotation creation
+ * (backend) and rendering (frontend).
+ *
+ * @param buffer - Binary data to decode
+ * @param mediaType - Media type with optional charset parameter
+ * @returns Decoded string in the original character space
+ *
+ * @example
+ * const buffer = new Uint8Array([...]);
+ * const text = decodeWithCharset(buffer, "text/plain; charset=iso-8859-1");
+ */
+declare function decodeWithCharset(buffer: ArrayBuffer, mediaType: string): string;
 
 /**
  * Generic validation utilities for @semiont/api-client
@@ -3628,4 +3874,4 @@ declare function validateData<T>(schema: {
  */
 declare function isValidEmail(email: string): boolean;
 
-export { type $defs as $, type AccessToken as A, type BaseUrl as B, type ContentFormat as C, getTagSchemaId as D, type EntityType as E, isStubReference as F, type GoogleCredential as G, isResolvedReference as H, getExactText as I, type JobId as J, getAnnotationExactText as K, getPrimarySelector as L, type Motivation as M, getTextPositionSelector as N, getTextQuoteSelector as O, getSvgSelector as P, validateSvgMarkup as Q, type ResourceUri as R, type SearchQuery as S, type TextPositionSelector as T, type UserDID as U, extractBoundingBox as V, type StoredEvent as W, type EventMetadata as X, type ResourceEventType as Y, getAnnotationUriFromEvent as Z, isEventRelatedToAnnotation as _, type AnnotationUri as a, isResourceEvent as a0, formatEventType as a1, getEventEmoji as a2, formatRelativeTime as a3, getEventDisplayContent as a4, getEventEntityTypes as a5, type ResourceCreationDetails as a6, getResourceCreationDetails as a7, type LocaleInfo as a8, LOCALES as a9, userDID as aA, entityType as aB, searchQuery as aC, baseUrl as aD, resourceUri as aE, annotationUri as aF, resourceAnnotationUri as aG, type ResourceEvent as aH, getLocaleInfo as aa, getLocaleNativeName as ab, getLocaleEnglishName as ac, formatLocaleDisplay as ad, getAllLocaleCodes as ae, getResourceId as af, getPrimaryRepresentation as ag, getPrimaryMediaType as ah, getChecksum as ai, getLanguage as aj, type ValidationSuccess as ak, type ValidationFailure as al, type ValidationResult as am, JWTTokenSchema as an, validateData as ao, isValidEmail as ap, type AuthCode as aq, type MCPToken as ar, email as as, authCode as at, googleCredential as au, accessToken as av, refreshToken as aw, mcpToken as ax, cloneToken as ay, jobId as az, type Email as b, type components as c, type RefreshToken as d, type CloneToken as e, type ResourceAnnotationUri as f, type TextQuoteSelector as g, type SvgSelector as h, type Selector as i, getBodySource as j, getBodyType as k, isBodyResolved as l, getTargetSource as m, getTargetSelector as n, type operations as o, type paths as p, hasTargetSelector as q, getEntityTypes as r, isHighlight as s, isReference as t, isAssessment as u, isComment as v, type webhooks as w, isTag as x, getCommentText as y, getTagCategory as z };
+export { type $defs as $, type AccessToken as A, type BaseUrl as B, type ContentFormat as C, getExactText as D, type EntityType as E, getAnnotationExactText as F, type GoogleCredential as G, getPrimarySelector as H, getTextPositionSelector as I, type JobId as J, getTextQuoteSelector as K, getSvgSelector as L, type Motivation as M, validateSvgMarkup as N, extractBoundingBox as O, type StoredEvent as P, type EventMetadata as Q, type ResourceUri as R, type SearchQuery as S, type TextPositionSelector as T, type UserDID as U, type ResourceEventType as V, getAnnotationUriFromEvent as W, isEventRelatedToAnnotation as X, isResourceEvent as Y, formatEventType as Z, getEventEmoji as _, type AnnotationUri as a, resourceAnnotationUri as a$, formatRelativeTime as a0, getEventDisplayContent as a1, getEventEntityTypes as a2, type ResourceCreationDetails as a3, getResourceCreationDetails as a4, type TextPosition as a5, findTextWithContext as a6, verifyPosition as a7, type LocaleInfo as a8, LOCALES as a9, extractContext as aA, type ValidatedAnnotation as aB, validateAndCorrectOffsets as aC, extractCharset as aD, decodeWithCharset as aE, type ValidationSuccess as aF, type ValidationFailure as aG, type ValidationResult as aH, JWTTokenSchema as aI, validateData as aJ, isValidEmail as aK, type AuthCode as aL, type MCPToken as aM, email as aN, authCode as aO, googleCredential as aP, accessToken as aQ, refreshToken as aR, mcpToken as aS, cloneToken as aT, jobId as aU, userDID as aV, entityType as aW, searchQuery as aX, baseUrl as aY, resourceUri as aZ, annotationUri as a_, getLocaleInfo as aa, getLocaleNativeName as ab, getLocaleEnglishName as ac, formatLocaleDisplay as ad, getAllLocaleCodes as ae, getResourceId as af, getPrimaryRepresentation as ag, getPrimaryMediaType as ah, getChecksum as ai, getLanguage as aj, getStorageUri as ak, getCreator as al, getDerivedFrom as am, isArchived as an, getResourceEntityTypes as ao, isDraft as ap, getNodeEncoding as aq, decodeRepresentation as ar, type Point as as, type BoundingBox as at, createRectangleSvg as au, createPolygonSvg as av, createCircleSvg as aw, parseSvgSelector as ax, normalizeCoordinates as ay, scaleSvgToNative as az, type Email as b, type ResourceEvent as b0, type components as c, type RefreshToken as d, type CloneToken as e, type ResourceAnnotationUri as f, type TextQuoteSelector as g, type SvgSelector as h, type Selector as i, getBodySource as j, getBodyType as k, isBodyResolved as l, getTargetSource as m, getTargetSelector as n, type operations as o, type paths as p, hasTargetSelector as q, isHighlight as r, isReference as s, isAssessment as t, isComment as u, isTag as v, type webhooks as w, getCommentText as x, isStubReference as y, isResolvedReference as z };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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';
+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--2zlsZdR.js';
+export { $ as $defs, aL as AuthCode, at as BoundingBox, Q as EventMetadata, aI as JWTTokenSchema, a9 as LOCALES, a8 as LocaleInfo, aM as MCPToken, as as Point, a3 as ResourceCreationDetails, V as ResourceEventType, i as Selector, P as StoredEvent, h as SvgSelector, a5 as TextPosition, T as TextPositionSelector, g as TextQuoteSelector, aB as ValidatedAnnotation, aG as ValidationFailure, aH as ValidationResult, aF as ValidationSuccess, aQ as accessToken, a_ as annotationUri, aO as authCode, aY as baseUrl, aT as cloneToken, aw as createCircleSvg, av as createPolygonSvg, au as createRectangleSvg, ar as decodeRepresentation, aE as decodeWithCharset, aN as email, aW as entityType, O as extractBoundingBox, aD as extractCharset, aA as extractContext, a6 as findTextWithContext, Z as formatEventType, ad as formatLocaleDisplay, a0 as formatRelativeTime, ae as getAllLocaleCodes, F as getAnnotationExactText, W as getAnnotationUriFromEvent, j as getBodySource, k as getBodyType, ai as getChecksum, x as getCommentText, al as getCreator, am as getDerivedFrom, a1 as getEventDisplayContent, _ as getEventEmoji, a2 as getEventEntityTypes, D as getExactText, aj as getLanguage, ac as getLocaleEnglishName, aa as getLocaleInfo, ab as getLocaleNativeName, aq as getNodeEncoding, ah as getPrimaryMediaType, ag as getPrimaryRepresentation, H as getPrimarySelector, a4 as getResourceCreationDetails, ao as getResourceEntityTypes, af as getResourceId, ak as getStorageUri, L as getSvgSelector, n as getTargetSelector, m as getTargetSource, I as getTextPositionSelector, K as getTextQuoteSelector, aP as googleCredential, q as hasTargetSelector, an as isArchived, t as isAssessment, l as isBodyResolved, u as isComment, ap as isDraft, X as isEventRelatedToAnnotation, r as isHighlight, s as isReference, z as isResolvedReference, Y as isResourceEvent, y as isStubReference, v as isTag, aK as isValidEmail, aU as jobId, aS as mcpToken, ay as normalizeCoordinates, o as operations, ax as parseSvgSelector, aR as refreshToken, a$ as resourceAnnotationUri, aZ as resourceUri, az as scaleSvgToNative, aX as searchQuery, aV as userDID, aC as validateAndCorrectOffsets, aJ as validateData, N as validateSvgMarkup, a7 as verifyPosition, w as webhooks } from './index--2zlsZdR.js';
 
 /**
  * TypeScript types for Server-Sent Events (SSE) streaming