@semiont/core 0.1.0

package/README.md

@@ -0,0 +1,265 @@
+# @semiont/core
+
+Backend domain logic for the Semiont semantic knowledge platform. This package provides **internal backend utilities** for event sourcing, cryptography, DID generation, and type guards.
+
+> ⚠️ **Not for External Use**: If you're building applications that consume the Semiont API, use [`@semiont/api-client`](../api-client/README.md) instead. This package is for **backend internal use only**.
+
+## Who Should Use This
+
+- ✅ **Backend** (`apps/backend`) - Server implementation with event sourcing
+- ✅ **Internal Services** - System components requiring domain logic
+- ✅ **CLI Tools** - Command-line utilities with full system access
+
+## Who Should NOT Use This
+
+- ❌ **External Applications** - Use [`@semiont/api-client`](../api-client/README.md)
+- ❌ **Frontend** - Use [`@semiont/api-client`](../api-client/README.md)
+- ❌ **MCP Servers** - Use [`@semiont/api-client`](../api-client/README.md)
+- ❌ **Demo Scripts** - Use [`@semiont/api-client`](../api-client/README.md)
+
+## Installation
+
+```bash
+npm install @semiont/core
+```
+
+## What's Included
+
+### Event Sourcing Types
+
+Event types for the event-sourced architecture:
+
+```typescript
+import type {
+  DocumentEvent,
+  DocumentCreatedEvent,
+  DocumentArchivedEvent,
+  DocumentUnarchivedEvent,
+  AnnotationAddedEvent,
+  AnnotationRemovedEvent,
+  AnnotationBodyUpdatedEvent,
+  EntityTagAddedEvent,
+  EntityTagRemovedEvent,
+  StoredEvent,
+  EventMetadata,
+  DocumentAnnotations,
+  BodyOperation,
+} from '@semiont/core';
+```
+
+### DID Utilities
+
+Generate W3C Decentralized Identifiers for annotations:
+
+```typescript
+import { userToDid, userToAgent, didToAgent } from '@semiont/core';
+
+// Convert user to DID:WEB
+const did = userToDid(user);
+// => 'did:web:localhost%3A4000:users:user-id'
+
+// Convert user to W3C Agent
+const agent = userToAgent(user);
+// => { id: 'did:web:...', type: 'Person', name: 'User Name' }
+```
+
+### Cryptographic Utilities
+
+Content-addressing and checksums:
+
+```typescript
+import {
+  generateId,
+  generateToken,
+  generateUuid,
+  calculateChecksum,
+  verifyChecksum,
+} from '@semiont/core';
+
+// Generate unique IDs
+const id = generateId();
+const token = generateToken();
+const uuid = generateUuid();
+
+// Content checksums for verification
+const checksum = calculateChecksum(content);
+const isValid = verifyChecksum(content, checksum);
+```
+
+### Type Guards
+
+Runtime type checking:
+
+```typescript
+import {
+  isString,
+  isNumber,
+  isBoolean,
+  isObject,
+  isArray,
+  isNonEmptyArray,
+  isDefined,
+} from '@semiont/core';
+
+if (isNonEmptyArray(value)) {
+  // TypeScript knows value is T[] with length > 0
+}
+```
+
+### Error Classes
+
+Backend error types:
+
+```typescript
+import {
+  SemiontError,
+  APIError,
+  NotFoundError,
+  ConflictError,
+  ValidationError,
+  UnauthorizedError,
+} from '@semiont/core';
+
+throw new NotFoundError('Document not found');
+throw new ValidationError('Invalid annotation format');
+```
+
+### HTTP Client Utilities
+
+Backend HTTP utilities (internal use):
+
+```typescript
+import { fetchAPI, createFetchAPI } from '@semiont/core';
+
+const response = await fetchAPI(url, { method: 'POST', body: data });
+```
+
+### Backend-Specific Annotation Utilities
+
+Utilities that work with internal backend types:
+
+```typescript
+import { bodyItemsMatch, findBodyItem } from '@semiont/core';
+
+// Find specific body item in annotation
+const item = findBodyItem(annotation.body, (item) => item.purpose === 'tagging');
+
+// Check if two body items match
+if (bodyItemsMatch(item1, item2)) {
+  // ...
+}
+```
+
+### Backend Internal Types
+
+Types not in the OpenAPI spec:
+
+```typescript
+import type {
+  UpdateDocumentInput,
+  ResourceFilter,
+  CreateAnnotationInternal,
+  AnnotationCategory,
+  GoogleAuthRequest,
+  GraphConnection,
+  GraphPath,
+  EntityTypeStats,
+} from '@semiont/core';
+```
+
+### Constants
+
+Backend-specific constants:
+
+```typescript
+import { CREATION_METHODS } from '@semiont/core';
+
+CREATION_METHODS.API          // 'api'
+CREATION_METHODS.PASTE        // 'paste'
+CREATION_METHODS.FILE_UPLOAD  // 'file-upload'
+CREATION_METHODS.REFERENCE    // 'reference'
+CREATION_METHODS.IMPORT       // 'import'
+```
+
+## What's NOT Included
+
+The following utilities have been **moved to @semiont/api-client** (as of 2025-10-24):
+
+### ❌ Selector Utilities
+
+**Use `@semiont/api-client` instead:**
+
+```typescript
+// OLD (removed from @semiont/core):
+import { getExactText, getTextPositionSelector } from '@semiont/core';
+
+// NEW (use @semiont/api-client):
+import { getExactText, getTextPositionSelector } from '@semiont/api-client';
+```
+
+### ❌ Locale Utilities
+
+**Use `@semiont/api-client` instead:**
+
+```typescript
+// OLD (removed from @semiont/core):
+import { LOCALES, formatLocaleDisplay, getLocaleInfo } from '@semiont/core';
+
+// NEW (use @semiont/api-client):
+import { LOCALES, formatLocaleDisplay, getLocaleInfo } from '@semiont/api-client';
+```
+
+### ❌ Annotation Utilities (Public API)
+
+**Use `@semiont/api-client` instead:**
+
+```typescript
+// OLD (removed from @semiont/core):
+import { compareAnnotationIds, getEntityTypes, getBodySource } from '@semiont/core';
+
+// NEW (use @semiont/api-client):
+import { compareAnnotationIds, getEntityTypes, getBodySource } from '@semiont/api-client';
+```
+
+## Architecture: Spec-First
+
+Semiont follows a **spec-first architecture**:
+
+1. **OpenAPI Specification** ([specs/src/](../../specs/src/)) is the source of truth
+2. **@semiont/api-client** generates types from OpenAPI and provides utilities
+3. **@semiont/core** provides backend-specific domain logic not in the API
+
+**Principle**:
+- API contract & data utilities → `@semiont/api-client`
+- Backend internal implementation → `@semiont/core`
+
+**Deduplication (2025-10-24)**: Selector utilities, locale utilities, and public annotation utilities were moved from this package to `@semiont/api-client` as part of the spec-first architecture migration.
+
+## Development
+
+```bash
+# Build the package
+npm run build
+
+# Type check
+npm run typecheck
+
+# Clean build artifacts
+npm run clean
+```
+
+## License
+
+Apache-2.0
+
+## Related Packages
+
+- [`@semiont/api-client`](../api-client/) - Primary TypeScript SDK (use this for most cases)
+- [`@semiont/backend`](../../apps/backend/) - Backend API server
+- [`@semiont/frontend`](../../apps/frontend/) - Web application
+
+## Learn More
+
+- [W3C Web Annotation Model](https://www.w3.org/TR/annotation-model/) - Annotation standard
+- [DID:WEB Specification](https://w3c-ccg.github.io/did-method-web/) - Decentralized identifiers
+- [W3C Selectors](../../specs/docs/W3C-SELECTORS.md) - Selector implementation details

package/dist/annotation-history-utils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Utility functions for AnnotationHistory component
+ * Extracted to reduce component complexity and improve testability
+ *
+ * NOTE: This file contains UI-specific logic and should eventually move to the frontend package.
+ * It has been updated to work with unified annotation events (annotation.added/removed/body.updated)
+ * instead of separate highlight/reference/assessment events.
+ */
+import type { StoredEvent, ResourceEventType } from './events';
+import type { CreationMethod } from './creation-methods';
+import type { components } from '@semiont/api-client';
+import type { AnnotationId } from './identifiers';
+type Annotation = components['schemas']['Annotation'];
+type TranslateFn = (key: string, params?: Record<string, string | number>) => string;
+export declare function formatEventType(type: ResourceEventType, t: TranslateFn): string;
+export declare function getEventEmoji(type: ResourceEventType, event?: StoredEvent): string;
+export declare function formatRelativeTime(timestamp: string, t: TranslateFn): string;
+export declare function getEventDisplayContent(event: StoredEvent, _references: Annotation[], // underscore prefix to indicate intentionally unused for now
+_highlights: Annotation[], // underscore prefix to indicate intentionally unused for now
+allEvents: StoredEvent[]): {
+    exact: string;
+    isQuoted: boolean;
+    isTag: boolean;
+} | null;
+export declare function getEventEntityTypes(event: StoredEvent): string[];
+type ResourceCreatedDetails = {
+    type: 'created';
+    userId: string;
+    method: CreationMethod;
+};
+type ResourceClonedDetails = {
+    type: 'cloned';
+    userId: string;
+    method: CreationMethod;
+    sourceDocId: string;
+};
+export type ResourceCreationDetails = ResourceCreatedDetails | ResourceClonedDetails;
+export declare function getResourceCreationDetails(event: StoredEvent): ResourceCreationDetails | null;
+export declare function getAnnotationIdFromEvent(event: StoredEvent): string | null;
+export declare function isEventRelatedToAnnotation(event: StoredEvent, annotationId: AnnotationId): boolean;
+export {};
+//# sourceMappingURL=annotation-history-utils.d.ts.map

package/dist/annotation-history-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation-history-utils.d.ts","sourceRoot":"","sources":["../src/annotation-history-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EAQlB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD,KAAK,UAAU,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,YAAY,CAAC,CAAC;AAGtD,KAAK,WAAW,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,MAAM,CAAC;AAGrF,wBAAgB,eAAe,CAAC,IAAI,EAAE,iBAAiB,EAAE,CAAC,EAAE,WAAW,GAAG,MAAM,CAoC/E;AAuBD,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,MAAM,CAoClF;AAGD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,GAAG,MAAM,CAc5E;AASD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,WAAW,EAClB,WAAW,EAAE,UAAU,EAAE,EAAE,6DAA6D;AACxF,WAAW,EAAE,UAAU,EAAE,EAAE,6DAA6D;AACxF,SAAS,EAAE,WAAW,EAAE,GACvB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAyD7D;AAGD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,EAAE,CAUhE;AAwBD,KAAK,sBAAsB,GAAG;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,cAAc,CAAC;CACxB,CAAC;AAEF,KAAK,qBAAqB,GAAG;IAC3B,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,cAAc,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,sBAAsB,GAAG,qBAAqB,CAAC;AAGrF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,WAAW,GAAG,uBAAuB,GAAG,IAAI,CAyB7F;AAGD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAiB1E;AAGD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,GAAG,OAAO,CAGlG"}

package/dist/annotation-history-utils.js

@@ -0,0 +1,258 @@
+"use strict";
+/**
+ * Utility functions for AnnotationHistory component
+ * Extracted to reduce component complexity and improve testability
+ *
+ * NOTE: This file contains UI-specific logic and should eventually move to the frontend package.
+ * It has been updated to work with unified annotation events (annotation.added/removed/body.updated)
+ * instead of separate highlight/reference/assessment events.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatEventType = formatEventType;
+exports.getEventEmoji = getEventEmoji;
+exports.formatRelativeTime = formatRelativeTime;
+exports.getEventDisplayContent = getEventDisplayContent;
+exports.getEventEntityTypes = getEventEntityTypes;
+exports.getResourceCreationDetails = getResourceCreationDetails;
+exports.getAnnotationIdFromEvent = getAnnotationIdFromEvent;
+exports.isEventRelatedToAnnotation = isEventRelatedToAnnotation;
+const api_client_1 = require("@semiont/api-client");
+// Format event type for display
+function formatEventType(type, t) {
+    // Using a switch for exhaustive checking - TypeScript will error if we miss a case
+    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':
+            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.started':
+            return t('jobStarted');
+        case 'job.progress':
+            return t('jobProgress');
+        case 'job.completed':
+            return t('jobCompleted');
+        case 'job.failed':
+            return t('jobFailed');
+        default:
+            // Exhaustive check: if we get here, we missed a case
+            const _exhaustiveCheck = type;
+            return _exhaustiveCheck;
+    }
+}
+// Get emoji for annotation based on motivation
+function getMotivationEmoji(motivation) {
+    switch (motivation) {
+        case 'highlighting':
+            return '🟡';
+        case 'linking':
+            return '🔵';
+        case 'assessing':
+            return '🔴';
+        case 'bookmarking':
+            return '🔖';
+        case 'commenting':
+            return '💬';
+        case 'tagging':
+            return '🏷️';
+        default:
+            return '📝';
+    }
+}
+// Get emoji for event type
+function getEventEmoji(type, event) {
+    // Using a switch for exhaustive checking - TypeScript will error if we miss a case
+    switch (type) {
+        case 'resource.created':
+        case 'resource.cloned':
+        case 'resource.archived':
+        case 'resource.unarchived':
+            return '📄';
+        case 'annotation.added':
+            if (event) {
+                const payload = event.event.payload;
+                return getMotivationEmoji(payload.annotation.motivation);
+            }
+            return '📝';
+        case 'annotation.removed':
+            return '🗑️';
+        case 'annotation.body.updated':
+            return '✏️';
+        case 'entitytag.added':
+        case 'entitytag.removed':
+            return '🏷️';
+        case 'entitytype.added':
+            return '🏷️'; // Same emoji as entitytag (global entity type collection)
+        case 'job.started':
+            return '▶️';
+        case 'job.progress':
+            return '⏳';
+        case 'job.completed':
+            return '✅';
+        case 'job.failed':
+            return '❌';
+        default:
+            // Exhaustive check: if we get here, we missed a case
+            const _exhaustiveCheck = type;
+            return _exhaustiveCheck;
+    }
+}
+// Format relative time
+function formatRelativeTime(timestamp, t) {
+    const date = new Date(timestamp);
+    const now = new Date();
+    const diffMs = now.getTime() - date.getTime();
+    const diffMins = Math.floor(diffMs / 60000);
+    const diffHours = Math.floor(diffMs / 3600000);
+    const diffDays = Math.floor(diffMs / 86400000);
+    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();
+}
+// Helper to truncate text for display
+function truncateText(text, maxLength = 50) {
+    const trimmed = text.trim();
+    return trimmed.length > maxLength ? trimmed.substring(0, maxLength) + '...' : trimmed;
+}
+// Extract display content from event payload
+function getEventDisplayContent(event, _references, // underscore prefix to indicate intentionally unused for now
+_highlights, // underscore prefix to indicate intentionally unused for now
+allEvents) {
+    const eventData = event.event;
+    // Use type discriminators instead of runtime typeof checks
+    switch (eventData.type) {
+        case 'resource.created':
+        case 'resource.cloned': {
+            const payload = eventData.payload;
+            return { exact: payload.name, isQuoted: false, isTag: false };
+        }
+        case 'annotation.body.updated': {
+            const payload = eventData.payload;
+            // Find the original annotation.added event to get the text
+            const addedEvent = allEvents.find(e => e.event.type === 'annotation.added' &&
+                e.event.payload.annotation.id === payload.annotationId);
+            if (addedEvent) {
+                const addedPayload = addedEvent.event.payload;
+                return { exact: truncateText((0, api_client_1.getAnnotationExactText)(addedPayload.annotation)), isQuoted: true, isTag: false };
+            }
+            return null;
+        }
+        case 'annotation.removed': {
+            const payload = eventData.payload;
+            // Find the original annotation.added event
+            const addedEvent = allEvents.find(e => e.event.type === 'annotation.added' &&
+                e.event.payload.annotation.id === payload.annotationId);
+            if (addedEvent) {
+                const addedPayload = addedEvent.event.payload;
+                return { exact: truncateText((0, api_client_1.getAnnotationExactText)(addedPayload.annotation)), isQuoted: true, isTag: false };
+            }
+            return null;
+        }
+        case 'annotation.added': {
+            const payload = eventData.payload;
+            return { exact: truncateText((0, api_client_1.getAnnotationExactText)(payload.annotation)), isQuoted: true, isTag: false };
+        }
+        case 'entitytag.added':
+        case 'entitytag.removed': {
+            const payload = eventData.payload;
+            return { exact: payload.entityType, isQuoted: false, isTag: true };
+        }
+        default:
+            return null;
+    }
+}
+// Extract entity types from event payload
+function getEventEntityTypes(event) {
+    const eventData = event.event;
+    if (eventData.type === 'annotation.added') {
+        const payload = eventData.payload;
+        // Extract entity types from W3C annotation
+        return (0, api_client_1.getEntityTypes)(payload.annotation);
+    }
+    return [];
+}
+// Format user ID for display
+function formatUserId(userId) {
+    // If it's a DID format (did:web:org.com:users:alice), format as alice@org.com
+    if (userId.startsWith('did:web:')) {
+        const parts = userId.split(':');
+        // Format: did:web:org.com:users:alice
+        // parts: ['did', 'web', 'org.com', 'users', 'alice']
+        if (parts.length >= 5) {
+            const domain = parts[2]; // org.com
+            const username = parts[parts.length - 1]; // alice
+            return `${username}@${domain}`;
+        }
+        // Fallback if format is unexpected
+        const username = parts[parts.length - 1];
+        return username || userId.substring(0, 8);
+    }
+    // Otherwise show first 8 characters of UUID
+    return userId.substring(0, 8);
+}
+// Extract additional metadata for resource creation events
+function getResourceCreationDetails(event) {
+    const eventData = event.event;
+    if (eventData.type === 'resource.created') {
+        const payload = eventData.payload;
+        return {
+            type: 'created',
+            userId: formatUserId(eventData.userId),
+            method: payload.creationMethod,
+        };
+    }
+    if (eventData.type === 'resource.cloned') {
+        const payload = eventData.payload;
+        return {
+            type: 'cloned',
+            userId: formatUserId(eventData.userId),
+            method: payload.creationMethod,
+            sourceDocId: payload.parentResourceId,
+        };
+    }
+    return null;
+}
+// Extract annotation ID from event payload
+function getAnnotationIdFromEvent(event) {
+    const eventData = event.event;
+    switch (eventData.type) {
+        case 'annotation.added': {
+            const payload = eventData.payload;
+            return payload.annotation.id;
+        }
+        case 'annotation.removed':
+        case 'annotation.body.updated': {
+            const payload = eventData.payload;
+            return payload.annotationId;
+        }
+        default:
+            return null;
+    }
+}
+// Check if event relates to the hovered annotation
+function isEventRelatedToAnnotation(event, annotationId) {
+    const eventAnnotationId = getAnnotationIdFromEvent(event);
+    return eventAnnotationId === annotationId;
+}
+//# sourceMappingURL=annotation-history-utils.js.map

package/dist/annotation-history-utils.js.map

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

package/dist/annotation-types.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Annotation types
+ */
+import type { components } from '@semiont/api-client';
+type Annotation = components['schemas']['Annotation'];
+export type AnnotationCategory = 'highlight' | 'reference';
+export interface CreateAnnotationInternal {
+    id: string;
+    motivation: Annotation['motivation'];
+    target: Annotation['target'];
+    body: Annotation['body'];
+    creator: components['schemas']['Agent'];
+}
+export {};
+//# sourceMappingURL=annotation-types.d.ts.map

package/dist/annotation-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation-types.d.ts","sourceRoot":"","sources":["../src/annotation-types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,KAAK,UAAU,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,YAAY,CAAC,CAAC;AAEtD,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC;IACrC,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC7B,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IACzB,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC;CACzC"}

package/dist/annotation-types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Annotation types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=annotation-types.js.map

package/dist/annotation-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation-types.js","sourceRoot":"","sources":["../src/annotation-types.ts"],"names":[],"mappings":";AAAA;;GAEG"}

package/dist/annotation-utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Backend-specific annotation utility functions
+ */
+import type { components } from '@semiont/api-client';
+import type { BodyItem } from './events';
+type Annotation = components['schemas']['Annotation'];
+/**
+ * Check if two body items match (for remove/replace operations)
+ * Matches by type, value/source, and purpose fields
+ */
+export declare function bodyItemsMatch(item1: BodyItem, item2: BodyItem): boolean;
+/**
+ * Find a body item in an array
+ * Returns the index of the first matching item, or -1 if not found
+ */
+export declare function findBodyItem(body: Annotation['body'], targetItem: BodyItem): number;
+export {};
+//# sourceMappingURL=annotation-utils.d.ts.map

package/dist/annotation-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation-utils.d.ts","sourceRoot":"","sources":["../src/annotation-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,KAAK,UAAU,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,YAAY,CAAC,CAAC;AAEtD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAsBxE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,QAAQ,GAAG,MAAM,CA0CnF"}