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

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

@@ -2,8 +2,7 @@
  * This file was auto-generated by openapi-typescript.
  * Do not make direct changes to the file.
  */
-
-export interface paths {
+interface paths {
     "/resources/{id}": {
         parameters: {
             query?: never;
@@ -2287,8 +2286,8 @@ export interface paths {
         trace?: never;
     };
 }
-export type webhooks = Record<string, never>;
-export interface components {
+type webhooks = Record<string, never>;
+interface components {
     schemas: {
         AcceptTermsResponse: {
             success: boolean;
@@ -3173,5 +3172,460 @@ export interface components {
     headers: never;
     pathItems: never;
 }
-export type $defs = Record<string, never>;
-export type operations = Record<string, never>;
+type $defs = Record<string, never>;
+type operations = Record<string, never>;
+
+/**
+ * Branded string types for compile-time type safety
+ *
+ * These types are zero-cost at runtime but prevent mixing
+ * different string types at compile time.
+ */
+
+type Motivation = components['schemas']['Motivation'];
+type ContentFormat = components['schemas']['ContentFormat'];
+type Email = string & {
+    readonly __brand: 'Email';
+};
+type AuthCode = string & {
+    readonly __brand: 'AuthCode';
+};
+type GoogleCredential = string & {
+    readonly __brand: 'GoogleCredential';
+};
+type AccessToken = string & {
+    readonly __brand: 'AccessToken';
+};
+type RefreshToken = string & {
+    readonly __brand: 'RefreshToken';
+};
+type MCPToken = string & {
+    readonly __brand: 'MCPToken';
+};
+type CloneToken = string & {
+    readonly __brand: 'CloneToken';
+};
+type JobId = string & {
+    readonly __brand: 'JobId';
+};
+type UserDID = string & {
+    readonly __brand: 'UserDID';
+};
+type EntityType = string & {
+    readonly __brand: 'EntityType';
+};
+type SearchQuery = string & {
+    readonly __brand: 'SearchQuery';
+};
+type BaseUrl = string & {
+    readonly __brand: 'BaseUrl';
+};
+declare function email(value: string): Email;
+declare function authCode(value: string): AuthCode;
+declare function googleCredential(value: string): GoogleCredential;
+declare function accessToken(value: string): AccessToken;
+declare function refreshToken(value: string): RefreshToken;
+declare function mcpToken(value: string): MCPToken;
+declare function cloneToken(value: string): CloneToken;
+declare function jobId(value: string): JobId;
+declare function userDID(value: string): UserDID;
+declare function entityType(value: string): EntityType;
+declare function searchQuery(value: string): SearchQuery;
+declare function baseUrl(value: string): BaseUrl;
+type ResourceUri = string & {
+    readonly __brand: 'ResourceUri';
+};
+type AnnotationUri = string & {
+    readonly __brand: 'AnnotationUri';
+};
+type ResourceAnnotationUri = string & {
+    readonly __brand: 'ResourceAnnotationUri';
+};
+declare function resourceUri(uri: string): ResourceUri;
+declare function annotationUri(uri: string): AnnotationUri;
+declare function resourceAnnotationUri(uri: string): ResourceAnnotationUri;
+
+/**
+ * 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
+ */
+
+type Annotation$1 = components['schemas']['Annotation'];
+type HighlightAnnotation = Annotation$1;
+type ReferenceAnnotation = Annotation$1;
+type TextPositionSelector = components['schemas']['TextPositionSelector'];
+type TextQuoteSelector = components['schemas']['TextQuoteSelector'];
+type SvgSelector = components['schemas']['SvgSelector'];
+type Selector = TextPositionSelector | TextQuoteSelector | SvgSelector;
+
+/**
+ * Get the source from an annotation body (null if stub)
+ * Search for SpecificResource in body array
+ */
+declare function getBodySource(body: Annotation$1['body']): ResourceUri | null;
+/**
+ * Get the type from an annotation body (returns first body type in array)
+ */
+declare function getBodyType(body: Annotation$1['body']): 'TextualBody' | 'SpecificResource' | null;
+/**
+ * Check if body is resolved (has a source)
+ * Check for SpecificResource in body array
+ */
+declare function isBodyResolved(body: Annotation$1['body']): boolean;
+/**
+ * Get the source IRI from target (handles both string and object forms)
+ */
+declare function getTargetSource(target: Annotation$1['target']): ResourceUri;
+/**
+ * Get the selector from target (undefined if string or no selector)
+ */
+declare function getTargetSelector(target: Annotation$1['target']): {
+    type: "TextPositionSelector";
+    start: number;
+    end: number;
+} | {
+    type: "TextQuoteSelector";
+    exact: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: "SvgSelector";
+    value: string;
+} | ({
+    type: "TextPositionSelector";
+    start: number;
+    end: number;
+} | {
+    type: "TextQuoteSelector";
+    exact: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: "SvgSelector";
+    value: string;
+})[] | undefined;
+/**
+ * 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
+ */
+declare function isHighlight(annotation: Annotation$1): annotation is HighlightAnnotation;
+/**
+ * Type guard to check if an annotation is a reference (linking)
+ */
+declare function isReference(annotation: Annotation$1): annotation is ReferenceAnnotation;
+/**
+ * Type guard to check if an annotation is an assessment
+ */
+declare function isAssessment(annotation: Annotation$1): annotation is Annotation$1;
+/**
+ * Type guard to check if an annotation is a comment
+ */
+declare function isComment(annotation: Annotation$1): annotation is Annotation$1;
+/**
+ * Type guard to check if an annotation is a tag
+ */
+declare function isTag(annotation: Annotation$1): annotation is Annotation$1;
+/**
+ * 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
+ */
+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
+ */
+declare function isStubReference(annotation: Annotation$1): boolean;
+/**
+ * Type guard to check if a reference annotation is resolved
+ * Resolved if SpecificResource exists in body array
+ */
+declare function isResolvedReference(annotation: Annotation$1): annotation is ReferenceAnnotation;
+/**
+ * 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)
+ */
+declare function getExactText(selector: Selector | Selector[] | undefined): string;
+/**
+ * Get the exact text from an annotation's target selector
+ * Uses getTargetSelector helper to safely get selector
+ */
+declare function getAnnotationExactText(annotation: Annotation$1): string;
+/**
+ * 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.
+ */
+declare function getPrimarySelector(selector: Selector | Selector[]): 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)
+ */
+declare function getTextPositionSelector(selector: Selector | Selector[] | undefined): TextPositionSelector | null;
+/**
+ * Get TextQuoteSelector from a selector (single or array)
+ *
+ * Returns the first TextQuoteSelector found, or null if none exists.
+ */
+declare function getTextQuoteSelector(selector: Selector | Selector[]): TextQuoteSelector | null;
+/**
+ * Get SvgSelector from a selector (single or array)
+ *
+ * Returns the first SvgSelector found, or null if none exists.
+ */
+declare function getSvgSelector(selector: Selector | Selector[] | undefined): SvgSelector | 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
+ */
+declare function validateSvgMarkup(svg: string): string | null;
+/**
+ * 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.
+ */
+declare function extractBoundingBox(svg: string): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+
+/**
+ * Event Utilities
+ *
+ * Pure TypeScript utilities for working with resource events.
+ * No React dependencies - safe to use in any JavaScript environment.
+ */
+
+type EventsResponse = paths['/resources/{id}/events']['get']['responses'][200]['content']['application/json'];
+type StoredEvent = EventsResponse['events'][number];
+type ResourceEvent = StoredEvent['event'];
+type EventMetadata = StoredEvent['metadata'];
+type Annotation = components['schemas']['Annotation'];
+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
+ */
+declare function getAnnotationUriFromEvent(event: StoredEvent): AnnotationUri | null;
+/**
+ * Check if an event is related to a specific annotation
+ */
+declare function isEventRelatedToAnnotation(event: StoredEvent, annotationUri: AnnotationUri): boolean;
+/**
+ * Type guard to check if event is a resource event
+ */
+declare function isResourceEvent(event: any): event is StoredEvent;
+/**
+ * Format event type for display with i18n support
+ */
+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
+ */
+declare function getEventEmoji(type: ResourceEventType, payload?: any): string;
+/**
+ * Format timestamp as relative time with i18n support
+ */
+declare function formatRelativeTime(timestamp: string, t: TranslateFn): string;
+/**
+ * Get display content from event payload - complete implementation
+ */
+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
+ */
+declare function getEventEntityTypes(event: StoredEvent): string[];
+/**
+ * Resource creation details
+ */
+interface ResourceCreationDetails {
+    type: 'created' | 'cloned';
+    method: string;
+    userId?: string;
+    sourceDocId?: string;
+    parentResourceId?: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * Get resource creation details from event
+ */
+declare function getResourceCreationDetails(event: StoredEvent): ResourceCreationDetails | null;
+
+/**
+ * Locale information
+ * Copied from SDK for frontend use
+ */
+interface LocaleInfo {
+    code: string;
+    nativeName: string;
+    englishName: string;
+}
+declare const LOCALES: readonly LocaleInfo[];
+/**
+ * Get locale information by code
+ */
+declare function getLocaleInfo(code: string | undefined): LocaleInfo | undefined;
+/**
+ * Get the native name of a language by its locale code
+ */
+declare function getLocaleNativeName(code: string | undefined): string | undefined;
+/**
+ * Get the English name of a language by its locale code
+ */
+declare function getLocaleEnglishName(code: string | undefined): string | undefined;
+/**
+ * Format locale code for display as "Native Name (code)"
+ */
+declare function formatLocaleDisplay(code: string | undefined): string | undefined;
+/**
+ * Get all supported locale codes
+ */
+declare function getAllLocaleCodes(): readonly string[];
+
+/**
+ * Helper functions for working with W3C ResourceDescriptor
+ */
+
+type ResourceDescriptor = components['schemas']['ResourceDescriptor'];
+type Representation = components['schemas']['Representation'];
+/**
+ * Get the resource ID from @id property
+ *
+ * For internal resources: extracts UUID from "http://localhost:4000/resources/{uuid}"
+ * For external resources: returns undefined
+ *
+ * This is used for routing - the frontend URL should contain only the resource ID,
+ * not the full HTTP URI.
+ */
+declare function getResourceId(resource: ResourceDescriptor | undefined): string | undefined;
+/**
+ * Get the primary representation (first or only representation)
+ */
+declare function getPrimaryRepresentation(resource: ResourceDescriptor | undefined): Representation | undefined;
+/**
+ * Get the media type from the primary representation
+ */
+declare function getPrimaryMediaType(resource: ResourceDescriptor | undefined): string | undefined;
+/**
+ * Get the checksum from the primary representation
+ */
+declare function getChecksum(resource: ResourceDescriptor | undefined): string | undefined;
+/**
+ * Get the language from the primary representation
+ */
+declare function getLanguage(resource: ResourceDescriptor | undefined): string | undefined;
+
+/**
+ * Generic validation utilities for @semiont/api-client
+ *
+ * Pure TypeScript validation with no external dependencies.
+ * Safe to use in any JavaScript environment (Node.js, browser, Deno, etc.)
+ */
+/**
+ * Validation result types
+ */
+type ValidationSuccess<T> = {
+    success: true;
+    data: T;
+};
+type ValidationFailure = {
+    success: false;
+    error: string;
+    details?: string[];
+};
+type ValidationResult<T> = ValidationSuccess<T> | ValidationFailure;
+/**
+ * JWT Token validation
+ *
+ * Validates JWT token format (header.payload.signature).
+ * Does not verify signature - use for format validation only.
+ */
+declare const JWTTokenSchema: {
+    parse(token: unknown): string;
+    safeParse(token: unknown): ValidationResult<string>;
+};
+/**
+ * Generic validation helper with error formatting
+ *
+ * Wraps any schema's parse method with try/catch and returns ValidationResult.
+ *
+ * @example
+ * ```typescript
+ * const result = validateData(JWTTokenSchema, 'eyJ...');
+ * if (result.success) {
+ *   console.log('Valid token:', result.data);
+ * } else {
+ *   console.error('Invalid:', result.error);
+ * }
+ * ```
+ */
+declare function validateData<T>(schema: {
+    parse(data: unknown): T;
+}, data: unknown): ValidationResult<T>;
+/**
+ * Email validation helper
+ *
+ * Validates email format using RFC 5322 simplified regex.
+ *
+ * @param email - Email address to validate
+ * @returns true if valid email format
+ */
+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 };