@hearthlog/runtime 0.0.0-stage → 0.1.0

package/src/ledger/config.ts

@@ -0,0 +1,117 @@
+/**
+ * Configuration for the Ledger Service client
+ */
+
+export interface RetryPolicy {
+  maxRetries: number;
+  initialDelayMs: number;
+  maxDelayMs: number;
+  backoffMultiplier: number;
+}
+
+export interface LedgerConfig {
+  baseUrl: string;
+  authToken?: string;
+  timeout: number;
+  retryPolicy: RetryPolicy;
+  enableRealtime: boolean;
+}
+
+/**
+ * Default retry policy with exponential backoff
+ */
+export const DEFAULT_RETRY_POLICY: RetryPolicy = {
+  maxRetries: 3,
+  initialDelayMs: 1000,
+  maxDelayMs: 10000,
+  backoffMultiplier: 2
+};
+
+/**
+ * Validation error thrown when configuration is invalid
+ */
+export class ConfigValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ConfigValidationError';
+  }
+}
+
+/**
+ * Validates the Ledger Service configuration
+ * @throws {ConfigValidationError} if configuration is invalid
+ */
+function validateConfig(config: Partial<LedgerConfig>): void {
+  if (!config.baseUrl) {
+    throw new ConfigValidationError('LEDGER_SERVICE_URL is required');
+  }
+
+  const isRelative =
+    config.baseUrl.startsWith('/') && !config.baseUrl.startsWith('//');
+  let isAbsoluteHttp = false;
+  if (!isRelative) {
+    try {
+      const parsed = new URL(config.baseUrl);
+      isAbsoluteHttp = parsed.protocol === 'http:' || parsed.protocol === 'https:';
+    } catch {
+      isAbsoluteHttp = false;
+    }
+  }
+  if (!isRelative && !isAbsoluteHttp) {
+    throw new ConfigValidationError(`Invalid LEDGER_SERVICE_URL: ${config.baseUrl}`);
+  }
+
+  if (config.timeout !== undefined && (config.timeout <= 0 || !Number.isFinite(config.timeout))) {
+    throw new ConfigValidationError(`Invalid timeout value: ${config.timeout}`);
+  }
+
+  if (config.retryPolicy) {
+    const { maxRetries, initialDelayMs, maxDelayMs, backoffMultiplier } = config.retryPolicy;
+    
+    if (maxRetries < 0 || !Number.isInteger(maxRetries)) {
+      throw new ConfigValidationError(`Invalid maxRetries: ${maxRetries}`);
+    }
+    
+    if (initialDelayMs <= 0 || !Number.isFinite(initialDelayMs)) {
+      throw new ConfigValidationError(`Invalid initialDelayMs: ${initialDelayMs}`);
+    }
+    
+    if (maxDelayMs <= 0 || !Number.isFinite(maxDelayMs)) {
+      throw new ConfigValidationError(`Invalid maxDelayMs: ${maxDelayMs}`);
+    }
+    
+    if (backoffMultiplier <= 1 || !Number.isFinite(backoffMultiplier)) {
+      throw new ConfigValidationError(`Invalid backoffMultiplier: ${backoffMultiplier}`);
+    }
+  }
+}
+
+/**
+ * Loads and validates Ledger Service configuration from environment variables
+ * @returns {LedgerConfig} Validated configuration object
+ * @throws {ConfigValidationError} if configuration is invalid or missing required values
+ */
+export function loadLedgerConfig(): LedgerConfig {
+  const baseUrl = import.meta.env.VITE_LEDGER_SERVICE_URL;
+  const authToken = import.meta.env.VITE_LEDGER_AUTH_TOKEN;
+  const timeoutStr = import.meta.env.VITE_LEDGER_TIMEOUT_MS;
+  const maxRetriesStr = import.meta.env.VITE_LEDGER_MAX_RETRIES;
+  const enableRealtimeStr = import.meta.env.VITE_LEDGER_ENABLE_REALTIME;
+
+  const config: LedgerConfig = {
+    baseUrl: baseUrl || (import.meta.env.DEV ? 'http://127.0.0.1:8787' : '/api/ledger'),
+    authToken: authToken || undefined,
+    timeout: timeoutStr ? parseInt(timeoutStr, 10) : 5000,
+    retryPolicy: {
+      maxRetries: maxRetriesStr ? parseInt(maxRetriesStr, 10) : DEFAULT_RETRY_POLICY.maxRetries,
+      initialDelayMs: DEFAULT_RETRY_POLICY.initialDelayMs,
+      maxDelayMs: DEFAULT_RETRY_POLICY.maxDelayMs,
+      backoffMultiplier: DEFAULT_RETRY_POLICY.backoffMultiplier
+    },
+    enableRealtime: enableRealtimeStr !== 'false'
+  };
+
+  validateConfig(config);
+
+  return config;
+}

package/src/ledger/entity-id.ts

@@ -0,0 +1,115 @@
+/**
+ * Entity ID extraction utilities for mapping AppEvent types to entity identifiers.
+ * This module implements the entity ID extraction logic using the entity registry.
+ */
+
+import type { ExtendedAppEvent, TombstoneEvent } from '../event/types.js';
+import { isMetaEntityEvent } from '../event/types.js';
+import { entityRegistry } from '../event/registry.js';
+
+function inferEntityNameFromEventType(type: string): string | null {
+  const match = type.match(/^(.*)_(ADDED|UPDATED|REMOVED)$/);
+  return match ? match[1].toLowerCase() : null;
+}
+
+/**
+ * Extracts the entity identifier from an AppEvent.
+ * 
+ * Entity IDs are prefixed with their type to prevent collisions between different entity types
+ * and to make debugging easier with self-documenting IDs.
+ * 
+ * Uses the entity registry for dynamic dispatch - no changes needed when adding new entities.
+ * 
+ * Mapping rules:
+ * - Entity events: `{entityName}:{payload.id}` (e.g., `asset:123`, `transaction:456`)
+ * - Tombstone events: `tombstone:{payload.eventId}`
+ * 
+ * @param event - The AppEvent to extract the entity ID from
+ * @returns The entity identifier string
+ * 
+ * @example
+ * ```typescript
+ * const event: AddCalendarEventEvent = {
+ *   id: 'evt-123',
+ *   type: 'CALENDAR_EVENT_ADDED',
+ *   timestamp: Date.now(),
+ *   payload: { id: 'event-456', title: 'Dentist', eventDate: '2026-10-12', startTime: '', notes: '', pinned: false }
+ * };
+ * const entityId = extractEntityId(event); // Returns: 'asset:asset-456'
+ * ```
+ */
+export function extractEntityId(event: ExtendedAppEvent): string {
+  // Handle tombstone events specially
+  if (event.type === 'EVENT_TOMBSTONED') {
+    return `tombstone:${(event as TombstoneEvent).payload.eventId}`;
+  }
+
+  // Excision markers are their own entity so they never join an existing
+  // entity's version chain.
+  if (event.type === 'EVENTS_EXCISED') {
+    return `excision:${event.id}`;
+  }
+
+  if (isMetaEntityEvent(event)) {
+    return `entity_type:${event.payload.id}`;
+  }
+
+  // Match the most specific prefix: one entity's prefix can start another's
+  // (FOO_ and FOO_BAR_), and definition order must not change event ownership.
+  let match: { name: string; prefix: string } | null = null;
+  for (const [name, entry] of Object.entries(entityRegistry)) {
+    if (event.type.startsWith(entry.eventPrefix) && (!match || entry.eventPrefix.length > match.prefix.length)) {
+      match = { name, prefix: entry.eventPrefix };
+    }
+  }
+  if (match) return `${match.name}:${(event.payload as { id: string }).id}`;
+
+  const payloadId = (event.payload as { id?: string }).id;
+  const inferredEntityName = inferEntityNameFromEventType(event.type);
+  if (payloadId && inferredEntityName) {
+    return `${inferredEntityName}:${payloadId}`;
+  }
+
+  // Fallback for unknown event types
+  return `unknown:${event.id}`;
+}
+
+/**
+ * Extracts entity IDs from a batch of events.
+ * 
+ * @param events - Array of AppEvents
+ * @returns Array of entity identifier strings in the same order
+ */
+export function extractEntityIds(events: ExtendedAppEvent[]): string[] {
+  return events.map(extractEntityId);
+}
+
+/**
+ * Groups events by their entity ID.
+ * Useful for batch operations that need to process events per entity.
+ * 
+ * @param events - Array of AppEvents to group
+ * @returns Map of entity ID to array of events for that entity
+ * 
+ * @example
+ * ```typescript
+ * const events = [assetEvent1, transactionEvent1, assetEvent2];
+ * const grouped = groupEventsByEntity(events);
+ * // Returns: Map {
+ * //   'asset:123' => [assetEvent1, assetEvent2],
+ * //   'transaction:456' => [transactionEvent1]
+ * // }
+ * ```
+ */
+export function groupEventsByEntity(events: ExtendedAppEvent[]): Map<string, ExtendedAppEvent[]> {
+  const grouped = new Map<string, ExtendedAppEvent[]>();
+
+  for (const event of events) {
+    const entityId = extractEntityId(event);
+    const existing = grouped.get(entityId) || [];
+    existing.push(event);
+    grouped.set(entityId, existing);
+  }
+
+  return grouped;
+}

package/src/ledger/errors.ts

@@ -0,0 +1,144 @@
+/**
+ * Ledger Service Error Classes
+ *
+ * Custom error types for Ledger Service API operations with:
+ * - Proper stack trace capture
+ * - Type guard functions for safe narrowing
+ * - Error cause chaining support
+ * - Discriminator tags for reliable instanceof alternatives
+ */
+
+import type {
+    ConflictResponse,
+    EntityVersionChainErrorResponse,
+} from "./types.js";
+
+// ============================================================================
+// Base Error
+// ============================================================================
+
+export interface LedgerErrorOptions {
+    cause?: Error;
+}
+
+/**
+ * Base error class for all Ledger Service API errors
+ */
+export class LedgerServiceError extends Error {
+    readonly _tag: string = "LedgerServiceError";
+
+    constructor(
+        message: string,
+        public readonly statusCode?: number,
+        public readonly response?: unknown,
+        public readonly code?: string,
+        options?: LedgerErrorOptions,
+    ) {
+        super(message, options);
+        this.name = "LedgerServiceError";
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+}
+
+export function isLedgerServiceError(e: unknown): e is LedgerServiceError {
+    return (
+        e instanceof LedgerServiceError ||
+        (e as any)?._tag === "LedgerServiceError"
+    );
+}
+
+// ============================================================================
+// Version Conflict Error (HTTP 409)
+// ============================================================================
+
+/**
+ * Error thrown when a version conflict occurs (HTTP 409)
+ */
+export class VersionConflictError extends LedgerServiceError {
+    override readonly _tag = "VersionConflictError";
+
+    constructor(
+        message: string,
+        public readonly conflict: ConflictResponse,
+        options?: LedgerErrorOptions,
+    ) {
+        super(message, 409, conflict, conflict.code, options);
+        this.name = "VersionConflictError";
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+}
+
+export function isVersionConflictError(e: unknown): e is VersionConflictError {
+    return (
+        e instanceof VersionConflictError ||
+        (e as any)?._tag === "VersionConflictError"
+    );
+}
+
+// ============================================================================
+// Not Found Error (HTTP 404)
+// ============================================================================
+
+/**
+ * Error thrown when a resource is not found (HTTP 404)
+ */
+export class NotFoundError extends LedgerServiceError {
+    override readonly _tag = "NotFoundError";
+
+    constructor(message: string, code = "not_found", options?: LedgerErrorOptions) {
+        super(message, 404, undefined, code, options);
+        this.name = "NotFoundError";
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+}
+
+export function isNotFoundError(e: unknown): e is NotFoundError {
+    return e instanceof NotFoundError || (e as any)?._tag === "NotFoundError";
+}
+
+// ============================================================================
+// Authentication Error (HTTP 401/403)
+// ============================================================================
+
+/**
+ * Error thrown when authentication fails (HTTP 401/403)
+ */
+export class AuthenticationError extends LedgerServiceError {
+    override readonly _tag = "AuthenticationError";
+
+    constructor(
+        message: string,
+        statusCode: number,
+        code = "unauthorized",
+        options?: LedgerErrorOptions,
+    ) {
+        super(message, statusCode, undefined, code, options);
+        this.name = "AuthenticationError";
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+}
+
+export class EntityVersionChainError extends LedgerServiceError {
+    override readonly _tag = "EntityVersionChainError";
+
+    constructor(public readonly details: EntityVersionChainErrorResponse) {
+        super(details.message ?? "Invalid entity version chain", 409, details, details.code);
+        this.name = "EntityVersionChainError";
+    }
+}
+
+export class IdempotencyMismatchError extends LedgerServiceError {
+    override readonly _tag = "IdempotencyMismatchError";
+
+    constructor(response: unknown) {
+        super("Request ID was reused with different content", 409, response, "idempotency_mismatch");
+        this.name = "IdempotencyMismatchError";
+    }
+}
+
+export function isAuthenticationError(e: unknown): e is AuthenticationError {
+    return (
+        e instanceof AuthenticationError ||
+        (e as any)?._tag === "AuthenticationError"
+    );
+}