@semiont/api-client 0.1.0

package/dist/utils/annotations.js

@@ -0,0 +1,404 @@
+"use strict";
+/**
+ * Annotation and Selector Utilities
+ *
+ * Pure TypeScript utilities for working with W3C Web Annotations.
+ * No React dependencies - safe to use in any JavaScript environment.
+ *
+ * Body is either empty array (stub) or single SpecificResource (resolved)
+ * Body can be array of TextualBody (tagging) + SpecificResource (linking)
+ * Target can be simple string IRI or object with source and optional selector
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBodySource = getBodySource;
+exports.getBodyType = getBodyType;
+exports.isBodyResolved = isBodyResolved;
+exports.getTargetSource = getTargetSource;
+exports.getTargetSelector = getTargetSelector;
+exports.hasTargetSelector = hasTargetSelector;
+exports.getEntityTypes = getEntityTypes;
+exports.isHighlight = isHighlight;
+exports.isReference = isReference;
+exports.isAssessment = isAssessment;
+exports.isComment = isComment;
+exports.isTag = isTag;
+exports.getCommentText = getCommentText;
+exports.getTagCategory = getTagCategory;
+exports.getTagSchemaId = getTagSchemaId;
+exports.isStubReference = isStubReference;
+exports.isResolvedReference = isResolvedReference;
+exports.getExactText = getExactText;
+exports.getAnnotationExactText = getAnnotationExactText;
+exports.getPrimarySelector = getPrimarySelector;
+exports.getTextPositionSelector = getTextPositionSelector;
+exports.getTextQuoteSelector = getTextQuoteSelector;
+exports.getSvgSelector = getSvgSelector;
+exports.validateSvgMarkup = validateSvgMarkup;
+exports.extractBoundingBox = extractBoundingBox;
+const branded_types_1 = require("../branded-types");
+/**
+ * Get the source from an annotation body (null if stub)
+ * Search for SpecificResource in body array
+ */
+function getBodySource(body) {
+    if (Array.isArray(body)) {
+        // Search for SpecificResource with source
+        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 (0, branded_types_1.resourceUri)(itemSource);
+                }
+            }
+        }
+        return null; // No SpecificResource found = stub
+    }
+    // Single body object (SpecificResource)
+    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 (0, branded_types_1.resourceUri)(bodySource);
+        }
+    }
+    return null;
+}
+/**
+ * Get the type from an annotation body (returns first body type in array)
+ */
+function getBodyType(body) {
+    if (Array.isArray(body)) {
+        if (body.length === 0) {
+            return null;
+        }
+        // Return type of first body item
+        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;
+    }
+    // Single body object
+    if (typeof body === 'object' && body !== null && 'type' in body) {
+        const bodyType = body.type;
+        if (bodyType === 'TextualBody' || bodyType === 'SpecificResource') {
+            return bodyType;
+        }
+    }
+    return null;
+}
+/**
+ * Check if body is resolved (has a source)
+ * Check for SpecificResource in body array
+ */
+function isBodyResolved(body) {
+    return getBodySource(body) !== null;
+}
+/**
+ * Get the source IRI from target (handles both string and object forms)
+ */
+function getTargetSource(target) {
+    if (typeof target === 'string') {
+        return (0, branded_types_1.resourceUri)(target);
+    }
+    return (0, branded_types_1.resourceUri)(target.source);
+}
+/**
+ * Get the selector from target (undefined if string or no selector)
+ */
+function getTargetSelector(target) {
+    if (typeof target === 'string') {
+        return undefined;
+    }
+    return target.selector;
+}
+/**
+ * Check if target has a selector
+ */
+function hasTargetSelector(target) {
+    return typeof target !== 'string' && target.selector !== undefined;
+}
+/**
+ * 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']
+ */
+function getEntityTypes(annotation) {
+    // Extract from TextualBody bodies with purpose: "tagging"
+    if (Array.isArray(annotation.body)) {
+        const entityTags = [];
+        for (const item of annotation.body) {
+            // Runtime check for TextualBody with tagging purpose
+            // TypeScript incorrectly narrows the union type here, so we use runtime checks only
+            if (typeof item === 'object' &&
+                item !== null &&
+                'type' in item &&
+                'value' in item &&
+                'purpose' in item) {
+                // Access properties as unknown first to avoid TypeScript narrowing issues
+                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 [];
+}
+/**
+ * Type guard to check if an annotation is a highlight
+ */
+function isHighlight(annotation) {
+    return annotation.motivation === 'highlighting';
+}
+/**
+ * Type guard to check if an annotation is a reference (linking)
+ */
+function isReference(annotation) {
+    return annotation.motivation === 'linking';
+}
+/**
+ * Type guard to check if an annotation is an assessment
+ */
+function isAssessment(annotation) {
+    return annotation.motivation === 'assessing';
+}
+/**
+ * Type guard to check if an annotation is a comment
+ */
+function isComment(annotation) {
+    return annotation.motivation === 'commenting';
+}
+/**
+ * Type guard to check if an annotation is a tag
+ */
+function isTag(annotation) {
+    return annotation.motivation === 'tagging';
+}
+/**
+ * Extract comment text from a comment annotation's body
+ * @param annotation - The annotation to extract comment text from
+ * @returns The comment text, or undefined if not a comment or no text found
+ */
+function getCommentText(annotation) {
+    if (!isComment(annotation))
+        return undefined;
+    const body = Array.isArray(annotation.body) ? annotation.body[0] : annotation.body;
+    if (body && 'value' in body) {
+        return body.value;
+    }
+    return 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
+ */
+function getTagCategory(annotation) {
+    if (!isTag(annotation))
+        return undefined;
+    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 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
+ */
+function getTagSchemaId(annotation) {
+    if (!isTag(annotation))
+        return undefined;
+    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 undefined;
+}
+/**
+ * Type guard to check if a reference annotation is a stub (unresolved)
+ * Stub if no SpecificResource in body array
+ */
+function isStubReference(annotation) {
+    return isReference(annotation) && !isBodyResolved(annotation.body);
+}
+/**
+ * Type guard to check if a reference annotation is resolved
+ * Resolved if SpecificResource exists in body array
+ */
+function isResolvedReference(annotation) {
+    return isReference(annotation) && isBodyResolved(annotation.body);
+}
+// =============================================================================
+// SELECTOR UTILITIES
+// =============================================================================
+/**
+ * Get the exact text from a selector (single or array)
+ *
+ * When selector is an array, tries to find a TextQuoteSelector (which has exact text).
+ * TextPositionSelector does not have exact text, only character offsets.
+ * Handles undefined selector (when target is a string IRI with no selector)
+ */
+function getExactText(selector) {
+    if (!selector) {
+        return ''; // No selector means entire resource
+    }
+    const selectors = Array.isArray(selector) ? selector : [selector];
+    // Try to find TextQuoteSelector (has exact text)
+    const quoteSelector = selectors.find(s => s.type === 'TextQuoteSelector');
+    if (quoteSelector) {
+        return quoteSelector.exact;
+    }
+    // No TextQuoteSelector found
+    return '';
+}
+/**
+ * Get the exact text from an annotation's target selector
+ * Uses getTargetSelector helper to safely get selector
+ */
+function getAnnotationExactText(annotation) {
+    const selector = getTargetSelector(annotation.target);
+    return getExactText(selector);
+}
+/**
+ * Get the primary selector from a selector (single or array)
+ *
+ * When selector is an array, returns the first selector.
+ * When selector is a single object, returns it as-is.
+ */
+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;
+}
+/**
+ * Get TextPositionSelector from a selector (single or array)
+ *
+ * Returns the first TextPositionSelector found, or null if none exists.
+ * Handles undefined selector (when target is a string IRI with no selector)
+ */
+function getTextPositionSelector(selector) {
+    if (!selector)
+        return null; // No selector means entire resource
+    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;
+}
+/**
+ * Get TextQuoteSelector from a selector (single or array)
+ *
+ * Returns the first TextQuoteSelector found, or null if none exists.
+ */
+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;
+}
+/**
+ * Get SvgSelector from a selector (single or array)
+ *
+ * Returns the first SvgSelector found, or null if none exists.
+ */
+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;
+}
+/**
+ * Validate SVG markup for W3C compliance
+ *
+ * Checks that:
+ * - SVG contains xmlns attribute
+ * - SVG is well-formed XML
+ * - SVG contains at least one shape element
+ *
+ * @returns null if valid, error message if invalid
+ */
+function validateSvgMarkup(svg) {
+    // Check for xmlns attribute (required by W3C spec)
+    if (!svg.includes('xmlns="http://www.w3.org/2000/svg"')) {
+        return 'SVG must include xmlns="http://www.w3.org/2000/svg" attribute';
+    }
+    // Check for basic SVG tag structure
+    if (!svg.includes('<svg') || !svg.includes('</svg>')) {
+        return 'SVG must have opening and closing tags';
+    }
+    // Check for at least one shape element
+    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; // Valid
+}
+/**
+ * Extract bounding box from SVG markup
+ *
+ * Attempts to extract x, y, width, height from the SVG viewBox or root element.
+ * Returns null if bounding box cannot be determined.
+ */
+function extractBoundingBox(svg) {
+    // Try to extract viewBox attribute from SVG element
+    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]
+            };
+        }
+    }
+    // Try to extract width/height attributes from SVG element (assume x=0, y=0)
+    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;
+}
+//# sourceMappingURL=annotations.js.map

package/dist/utils/annotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../src/utils/annotations.ts"],"names":[],"mappings":"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"}

package/dist/utils/events.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Event Utilities
+ *
+ * Pure TypeScript utilities for working with resource events.
+ * No React dependencies - safe to use in any JavaScript environment.
+ */
+import type { paths, components } from '../types';
+import { AnnotationUri } from '../branded-types';
+type EventsResponse = paths['/resources/{id}/events']['get']['responses'][200]['content']['application/json'];
+export type StoredEvent = EventsResponse['events'][number];
+export type ResourceEvent = StoredEvent['event'];
+export type EventMetadata = StoredEvent['metadata'];
+type Annotation = components['schemas']['Annotation'];
+export type ResourceEventType = 'resource.created' | 'resource.cloned' | 'resource.archived' | 'resource.unarchived' | 'annotation.added' | 'annotation.removed' | 'annotation.body.updated' | 'entitytag.added' | 'entitytag.removed' | 'entitytype.added' | 'job.started' | 'job.progress' | 'job.completed' | 'job.failed';
+type TranslateFn = (key: string, params?: Record<string, string | number>) => string;
+/**
+ * Extract annotation ID from event payload
+ * Returns null if event is not annotation-related
+ *
+ * For annotation.added: extracts full URI from payload.annotation.id
+ * For annotation.removed/body.updated: constructs full URI from payload.annotationId (UUID) + resourceId
+ */
+export declare function getAnnotationUriFromEvent(event: StoredEvent): AnnotationUri | null;
+/**
+ * Check if an event is related to a specific annotation
+ */
+export declare function isEventRelatedToAnnotation(event: StoredEvent, annotationUri: AnnotationUri): boolean;
+/**
+ * Type guard to check if event is a resource event
+ */
+export declare function isResourceEvent(event: any): event is StoredEvent;
+/**
+ * Format event type for display with i18n support
+ */
+export declare function formatEventType(type: ResourceEventType, t: TranslateFn, payload?: any): string;
+/**
+ * Get emoji for event type
+ * For unified annotation events, pass the payload to determine motivation
+ */
+export declare function getEventEmoji(type: ResourceEventType, payload?: any): string;
+/**
+ * Format timestamp as relative time with i18n support
+ */
+export declare function formatRelativeTime(timestamp: string, t: TranslateFn): string;
+/**
+ * Get display content from event payload - complete implementation
+ */
+export declare function getEventDisplayContent(event: StoredEvent, annotations: Annotation[], // Unified annotations array (all types)
+allEvents: StoredEvent[]): {
+    exact: string;
+    isQuoted: boolean;
+    isTag: boolean;
+} | null;
+/**
+ * Get entity types from event payload
+ */
+export declare function getEventEntityTypes(event: StoredEvent): string[];
+/**
+ * Resource creation details
+ */
+export interface ResourceCreationDetails {
+    type: 'created' | 'cloned';
+    method: string;
+    userId?: string;
+    sourceDocId?: string;
+    parentResourceId?: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * Get resource creation details from event
+ */
+export declare function getResourceCreationDetails(event: StoredEvent): ResourceCreationDetails | null;
+export {};
+//# sourceMappingURL=events.d.ts.map

package/dist/utils/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/utils/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAIjD,KAAK,cAAc,GAAG,KAAK,CAAC,wBAAwB,CAAC,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,kBAAkB,CAAC,CAAC;AAC9G,MAAM,MAAM,WAAW,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAC3D,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;AACjD,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;AACpD,KAAK,UAAU,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,YAAY,CAAC,CAAC;AAGtD,MAAM,MAAM,iBAAiB,GACzB,kBAAkB,GAClB,iBAAiB,GACjB,mBAAmB,GACnB,qBAAqB,GACrB,kBAAkB,GAClB,oBAAoB,GACpB,yBAAyB,GACzB,iBAAiB,GACjB,mBAAmB,GACnB,kBAAkB,GAClB,aAAa,GACb,cAAc,GACd,eAAe,GACf,YAAY,CAAC;AAEjB,KAAK,WAAW,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,MAAM,CAAC;AAMrF;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,WAAW,GAAG,aAAa,GAAG,IAAI,CAgClF;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,GAAG,OAAO,CAGpG;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,GAAG,GAAG,KAAK,IAAI,WAAW,CAShE;AAMD;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,iBAAiB,EAAE,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,MAAM,CA0C9F;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,MAAM,CAwC5E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,GAAG,MAAM,CAc5E;AAUD;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,WAAW,EAClB,WAAW,EAAE,UAAU,EAAE,EAAE,wCAAwC;AACnE,SAAS,EAAE,WAAW,EAAE,GACvB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAiG7D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,EAAE,CAYhE;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,WAAW,GAAG,uBAAuB,GAAG,IAAI,CAyB7F"}