@semiont/core 0.2.31 → 0.2.32-build.69

package/dist/index.d.ts

@@ -105,13 +105,13 @@ declare function uriToAnnotationId(uri: string): AnnotationId;
  */
 
 type ResourceDescriptor = components['schemas']['ResourceDescriptor'];
-type Annotation$4 = components['schemas']['Annotation'];
+type Annotation$3 = components['schemas']['Annotation'];
 /**
  * Represents a connection between resources through annotations
  */
 interface GraphConnection {
     targetResource: ResourceDescriptor;
-    annotations: Annotation$4[];
+    annotations: Annotation$3[];
     relationshipType?: string;
     bidirectional: boolean;
 }
@@ -120,7 +120,7 @@ interface GraphConnection {
  */
 interface GraphPath {
     resources: ResourceDescriptor[];
-    annotations: Annotation$4[];
+    annotations: Annotation$3[];
 }
 /**
  * Statistics about entity types in the graph
@@ -143,7 +143,7 @@ interface EntityTypeStats {
  * - Optional signatures for cross-org verification
  */
 
-type Annotation$3 = components['schemas']['Annotation'];
+type Annotation$2 = components['schemas']['Annotation'];
 type ContentFormat = components['schemas']['ContentFormat'];
 type Motivation = components['schemas']['Motivation'];
 interface BaseEvent {
@@ -221,7 +221,7 @@ interface RepresentationRemovedEvent extends BaseEvent {
 interface AnnotationAddedEvent extends BaseEvent {
     type: 'annotation.added';
     payload: {
-        annotation: Omit<Annotation$3, 'creator' | 'created'>;
+        annotation: Omit<Annotation$2, 'creator' | 'created'>;
     };
 }
 interface AnnotationRemovedEvent extends BaseEvent {
@@ -373,7 +373,7 @@ interface EventQuery {
 }
 interface ResourceAnnotations {
     resourceId: ResourceId;
-    annotations: Annotation$3[];
+    annotations: Annotation$2[];
     version: number;
     updatedAt: string;
 }
@@ -382,7 +382,7 @@ interface ResourceAnnotations {
  * Backend-specific annotation utility functions
  */
 
-type Annotation$2 = components['schemas']['Annotation'];
+type Annotation$1 = components['schemas']['Annotation'];
 /**
  * Check if two body items match (for remove/replace operations)
  * Matches by type, value/source, and purpose fields
@@ -392,7 +392,7 @@ 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
  */
-declare function findBodyItem(body: Annotation$2['body'], targetItem: BodyItem): number;
+declare function findBodyItem(body: Annotation$1['body'], targetItem: BodyItem): number;
 
 /**
  * Resource input/output types
@@ -413,13 +413,13 @@ interface ResourceFilter {
  * Annotation types
  */
 
-type Annotation$1 = components['schemas']['Annotation'];
+type Annotation = components['schemas']['Annotation'];
 type AnnotationCategory = 'highlight' | 'reference';
 interface CreateAnnotationInternal {
     id: string;
-    motivation: Annotation$1['motivation'];
-    target: Annotation$1['target'];
-    body: Annotation$1['body'];
+    motivation: Annotation['motivation'];
+    target: Annotation['target'];
+    body: Annotation['body'];
     creator: components['schemas']['Agent'];
 }
 
@@ -558,76 +558,6 @@ declare class APIError extends Error {
     constructor(status: number, data: any, message?: string);
 }
 
-/**
- * HTTP Client Utilities
- *
- * Reusable fetch wrapper for making authenticated HTTP requests.
- * Used by both frontend (via TanStack Query) and backend (direct calls).
- */
-/**
- * Configuration for HTTP client
- */
-interface HttpClientConfig {
-    baseUrl: string;
-    token?: string;
-}
-/**
- * Fetch helper with authentication and error handling
- *
- * @param endpoint - API endpoint (e.g., '/api/resources')
- * @param options - Standard fetch options
- * @param token - Optional authentication token
- * @returns Typed response data
- * @throws APIError on HTTP errors
- */
-declare function fetchAPI<T>(endpoint: string, options?: RequestInit, token?: string, baseUrl?: string): Promise<T>;
-/**
- * Create a configured fetch function with a base URL
- * Useful for creating client-specific fetch instances
- *
- * @param baseUrl - Base URL for all requests (e.g., 'http://localhost:4000')
- * @returns Configured fetch function
- */
-declare function createFetchAPI(baseUrl: string): <T>(endpoint: string, options?: RequestInit, token?: string) => Promise<T>;
-
-/**
- * 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.
- */
-
-type Annotation = components['schemas']['Annotation'];
-type TranslateFn = (key: string, params?: Record<string, string | number>) => string;
-declare function formatEventType(type: ResourceEventType, t: TranslateFn): string;
-declare function getEventEmoji(type: ResourceEventType, event?: StoredEvent): string;
-declare function formatRelativeTime(timestamp: string, t: TranslateFn): string;
-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;
-declare function getEventEntityTypes(event: StoredEvent): string[];
-type ResourceCreatedDetails = {
-    type: 'created';
-    userId: string;
-    method: CreationMethod;
-};
-type ResourceClonedDetails = {
-    type: 'cloned';
-    userId: string;
-    method: CreationMethod;
-    sourceDocId: string;
-};
-type ResourceCreationDetails = ResourceCreatedDetails | ResourceClonedDetails;
-declare function getResourceCreationDetails(event: StoredEvent): ResourceCreationDetails | null;
-declare function getAnnotationIdFromEvent(event: StoredEvent): string | null;
-declare function isEventRelatedToAnnotation(event: StoredEvent, annotationId: AnnotationId): boolean;
-
 /**
  * DID (Decentralized Identifier) and W3C Agent utilities
  *
@@ -1357,15 +1287,33 @@ interface AWSConfig {
     };
 }
 /**
- * Load environment configuration
- * Merges semiont.json with environment-specific config
+ * Deep merge utility for configuration objects
+ * Pure function - no side effects
+ */
+declare function deepMerge(target: any, ...sources: any[]): any;
+/**
+ * Recursively resolve environment variable placeholders in configuration
+ * Replaces ${VAR_NAME} with the value from the provided env object
+ * Pure function - accepts env as parameter instead of using process.env
  *
- * @param projectRoot - Absolute path to project directory containing semiont.json
- * @param environment - Environment name (must match a file in environments/)
- * @returns Merged environment configuration
- * @throws ConfigurationError if files are missing or invalid
+ * @param obj - Configuration object to process
+ * @param env - Environment variables object
+ * @returns Configuration with resolved environment variables
  */
-declare function loadEnvironmentConfig(projectRoot: string, environment: string): EnvironmentConfig;
+declare function resolveEnvVars(obj: any, env: Record<string, string | undefined>): any;
+/**
+ * Parse and merge configuration files
+ * Pure function - accepts file contents as strings instead of reading from filesystem
+ *
+ * @param baseContent - Contents of semiont.json (null if file doesn't exist)
+ * @param envContent - Contents of environment-specific JSON file
+ * @param env - Environment variables object
+ * @param environment - Environment name
+ * @param projectRoot - Project root path (for metadata only)
+ * @returns Merged and validated environment configuration
+ * @throws ConfigurationError if parsing or validation fails
+ */
+declare function parseAndMergeConfigs(baseContent: string | null, envContent: string, env: Record<string, string | undefined>, environment: string, projectRoot: string): EnvironmentConfig;
 /**
  * Get NODE_ENV value from environment config
  *
@@ -1373,21 +1321,70 @@ declare function loadEnvironmentConfig(projectRoot: string, environment: string)
  * @returns NODE_ENV value (defaults to 'development' if not specified)
  */
 declare function getNodeEnvForEnvironment(config: EnvironmentConfig): 'development' | 'production' | 'test';
+/**
+ * List environment names from filenames
+ * Pure function - accepts array of filenames instead of reading from filesystem
+ *
+ * @param files - Array of filenames from environments directory
+ * @returns Sorted array of environment names
+ */
+declare function listEnvironmentNames(files: string[]): string[];
+/**
+ * Type guard to check if config has AWS settings
+ *
+ * @param config - Environment configuration
+ * @returns True if AWS configuration is present
+ */
+declare function hasAWSConfig(config: EnvironmentConfig): config is EnvironmentConfig & {
+    aws: AWSConfig;
+};
+/**
+ * Display configuration for debugging
+ *
+ * @param config - Configuration to display
+ */
+declare function displayConfiguration(config: EnvironmentConfig): void;
+
+/**
+ * Filesystem-based wrapper for environment loading
+ *
+ * This module provides convenient filesystem-based wrappers around the pure
+ * configuration functions. These are intended for application code that needs
+ * to load config from disk.
+ *
+ * The pure functions (parseAndMergeConfigs, etc.) remain testable without
+ * filesystem mocking.
+ */
+
+/**
+ * Load environment configuration from filesystem
+ * Convenience wrapper around parseAndMergeConfigs for application code
+ *
+ * @param projectRoot - Absolute path to project directory containing semiont.json
+ * @param environment - Environment name (must match a file in environments/)
+ * @returns Merged environment configuration
+ * @throws ConfigurationError if files are missing or invalid
+ */
+declare function loadEnvironmentConfig(projectRoot: string, environment: string): EnvironmentConfig;
 /**
  * Get available environments by scanning environments directory
+ * Convenience wrapper around listEnvironmentNames for application code
  *
  * @returns Array of environment names
  */
 declare function getAvailableEnvironments(): string[];
+/**
+ * Check if an environment exists
+ *
+ * @param environment - Environment name to check
+ * @returns True if environment exists
+ */
+declare function isValidEnvironment(environment: string): boolean;
 
 /**
  * Environment validation utilities
  */
 type Environment = string;
-/**
- * Type guard to check if a string is a valid Environment
- */
-declare function isValidEnvironment(value: string | undefined): value is Environment;
 /**
  * Parse environment string to Environment type
  * @param value - The environment string to parse
@@ -1402,6 +1399,35 @@ declare function parseEnvironment(value: string | undefined): Environment;
  */
 declare function validateEnvironment(value: string | undefined): Environment;
 
+/**
+ * Config Schema Validator
+ *
+ * Validates configuration data against JSON Schema using Ajv (JSON Schema validator).
+ * Provides runtime validation for semiont.json and environment config files.
+ */
+
+interface ValidationResult {
+    valid: boolean;
+    errors: ErrorObject[] | null;
+    errorMessage?: string;
+}
+/**
+ * Validate semiont.json config
+ */
+declare function validateSemiontConfig(data: unknown): ValidationResult;
+/**
+ * Validate environment config (environments/*.json)
+ */
+declare function validateEnvironmentConfig(data: unknown): ValidationResult;
+/**
+ * Validate site config
+ */
+declare function validateSiteConfig(data: unknown): ValidationResult;
+/**
+ * Format validation errors into human-readable message
+ */
+declare function formatErrors(errors: ErrorObject[]): string;
+
 /**
  * Configuration Error Class
  *
@@ -1454,31 +1480,6 @@ declare function getEnvironmentsPath(projectRoot?: string): string;
  */
 declare function getSemiontConfigPath(projectRoot?: string): string;
 
-/**
- * Config Schema Validator
- *
- * Validates configuration data against JSON Schema using Ajv (JSON Schema validator).
- * Provides runtime validation for semiont.json and environment config files.
- */
-
-interface ValidationResult {
-    valid: boolean;
-    errors: ErrorObject[] | null;
-    errorMessage?: string;
-}
-/**
- * Validate semiont.json config
- */
-declare function validateSemiontConfig(data: unknown): ValidationResult;
-/**
- * Validate environment config (environments/*.json)
- */
-declare function validateEnvironmentConfig(data: unknown): ValidationResult;
-/**
- * Validate site config
- */
-declare function validateSiteConfig(data: unknown): ValidationResult;
-
 /**
  * @semiont/core
  *
@@ -1489,4 +1490,4 @@ declare function validateSiteConfig(data: unknown): ValidationResult;
 declare const CORE_TYPES_VERSION = "0.1.0";
 declare const SDK_VERSION = "0.1.0";
 
-export { APIError, type AWSConfig, type AnnotationAddedEvent, type AnnotationBodyUpdatedEvent, type AnnotationCategory, type AnnotationId, type AnnotationRemovedEvent, type AppConfig, type BackendServiceConfig, type BaseEvent, type BodyItem, type BodyOperation, CORE_TYPES_VERSION, CREATION_METHODS, ConfigurationError, ConflictError, type CreateAnnotationInternal, type CreationMethod, type DatabaseServiceConfig, type EntityTagAddedEvent, type EntityTagRemovedEvent, type EntityTypeStats, type Environment, type EnvironmentConfig, type EventMetadata, type EventQuery, type EventSignature, type FilesystemServiceConfig, type FrontendServiceConfig, type GoogleAuthRequest, type GraphConnection, type GraphDatabaseType, type GraphPath, type GraphServiceConfig, type HttpClientConfig, type InferenceServiceConfig, type JobCompletedEvent, type JobFailedEvent, type JobProgressEvent, type JobStartedEvent, type McpServiceConfig, NotFoundError, type PlatformType, type ProxyServiceConfig, type RepresentationAddedEvent, type RepresentationRemovedEvent, type ResourceAnnotations, type ResourceArchivedEvent, type ResourceClonedEvent, type ResourceCreatedEvent, type ResourceCreationDetails, type ResourceEvent, type ResourceEventType, type ResourceFilter, type ResourceId, type ResourceScopedEvent, type ResourceUnarchivedEvent, SDK_VERSION, ScriptError, type SemiontConfig, SemiontError, type ServiceConfig, type ServicePlatformConfig, type ServicesConfig, type SiteConfig, type StoredEvent, type SystemEvent, UnauthorizedError, type UpdateResourceInput, type UserId, ValidationError, type ValidationResult, annotationId, annotationIdToURI, bodyItemsMatch, calculateChecksum, createFetchAPI, didToAgent, fetchAPI, findBodyItem, findProjectRoot, formatEventType, formatRelativeTime, generateId, generateToken, generateUuid, getAllPlatformTypes, getAnnotationIdFromEvent, getAvailableEnvironments, getEnvironmentsPath, getEventDisplayContent, getEventEmoji, getEventEntityTypes, getEventType, getNodeEnvForEnvironment, getResourceCreationDetails, getSemiontConfigPath, isAnnotationId, isArray, isBoolean, isDefined, isEventRelatedToAnnotation, isFunction, isNull, isNullish, isNumber, isObject, isProjectRoot, isResourceEvent, isResourceId, isResourceScopedEvent, isString, isSystemEvent, isUndefined, isValidEnvironment, isValidPlatformType, loadEnvironmentConfig, parseEnvironment, resourceId, resourceIdToURI, uriToAnnotationId, uriToResourceId, userId, userToAgent, userToDid, validateEnvironment, validateEnvironmentConfig, validateSemiontConfig, validateSiteConfig, verifyChecksum };
+export { APIError, type AWSConfig, type AnnotationAddedEvent, type AnnotationBodyUpdatedEvent, type AnnotationCategory, type AnnotationId, type AnnotationRemovedEvent, type AppConfig, type BackendServiceConfig, type BaseEvent, type BodyItem, type BodyOperation, CORE_TYPES_VERSION, CREATION_METHODS, ConfigurationError, ConflictError, type CreateAnnotationInternal, type CreationMethod, type DatabaseServiceConfig, type EntityTagAddedEvent, type EntityTagRemovedEvent, type EntityTypeStats, type Environment, type EnvironmentConfig, type EventMetadata, type EventQuery, type EventSignature, type FilesystemServiceConfig, type FrontendServiceConfig, type GoogleAuthRequest, type GraphConnection, type GraphDatabaseType, type GraphPath, type GraphServiceConfig, type InferenceServiceConfig, type JobCompletedEvent, type JobFailedEvent, type JobProgressEvent, type JobStartedEvent, type McpServiceConfig, NotFoundError, type PlatformType, type ProxyServiceConfig, type RepresentationAddedEvent, type RepresentationRemovedEvent, type ResourceAnnotations, type ResourceArchivedEvent, type ResourceClonedEvent, type ResourceCreatedEvent, type ResourceEvent, type ResourceEventType, type ResourceFilter, type ResourceId, type ResourceScopedEvent, type ResourceUnarchivedEvent, SDK_VERSION, ScriptError, type SemiontConfig, SemiontError, type ServiceConfig, type ServicePlatformConfig, type ServicesConfig, type SiteConfig, type StoredEvent, type SystemEvent, UnauthorizedError, type UpdateResourceInput, type UserId, ValidationError, type ValidationResult, annotationId, annotationIdToURI, bodyItemsMatch, calculateChecksum, deepMerge, didToAgent, displayConfiguration, findBodyItem, findProjectRoot, formatErrors, generateId, generateToken, generateUuid, getAllPlatformTypes, getAvailableEnvironments, getEnvironmentsPath, getEventType, getNodeEnvForEnvironment, getSemiontConfigPath, hasAWSConfig, isAnnotationId, isArray, isBoolean, isDefined, isFunction, isNull, isNullish, isNumber, isObject, isProjectRoot, isResourceEvent, isResourceId, isResourceScopedEvent, isString, isSystemEvent, isUndefined, isValidEnvironment, isValidPlatformType, listEnvironmentNames, loadEnvironmentConfig, parseAndMergeConfigs, parseEnvironment, resolveEnvVars, resourceId, resourceIdToURI, uriToAnnotationId, uriToResourceId, userId, userToAgent, userToDid, validateEnvironment, validateEnvironmentConfig, validateSemiontConfig, validateSiteConfig, verifyChecksum };