reqon-dsl 0.2.0 → 0.3.0

package/dist/observability/events.d.ts

@@ -0,0 +1,244 @@
+/**
+ * Observability Events - Typed events for mission execution
+ *
+ * Provides a comprehensive event system for tracking execution progress,
+ * performance metrics, and debugging information.
+ */
+/** Log levels for structured logging */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Base event structure for all observability events */
+export interface ObservabilityEvent<T = unknown> {
+    /** Event type identifier */
+    type: string;
+    /** Execution context ID */
+    executionId: string;
+    /** Mission name */
+    mission: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Duration in milliseconds (for completed events) */
+    duration?: number;
+    /** Event-specific payload */
+    payload: T;
+}
+export interface MissionStartPayload {
+    stageCount: number;
+    isResume: boolean;
+    resumeFromStage?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface MissionCompletePayload {
+    success: boolean;
+    stagesCompleted: number;
+    stagesFailed: number;
+    stagesSkipped: number;
+    errorCount: number;
+}
+export interface MissionFailedPayload {
+    error: string;
+    failedStage?: string;
+    stagesCompleted: number;
+}
+export interface StageStartPayload {
+    stageIndex: number;
+    stageName: string;
+    totalStages: number;
+    isParallel: boolean;
+    parallelActions?: string[];
+}
+export interface StageCompletePayload {
+    stageIndex: number;
+    stageName: string;
+    success: boolean;
+    error?: string;
+    itemsProcessed?: number;
+}
+export type StepType = 'fetch' | 'for' | 'map' | 'validate' | 'store' | 'match' | 'let' | 'webhook' | 'pause';
+export interface StepStartPayload {
+    actionName: string;
+    stepIndex: number;
+    stepType: StepType;
+}
+export interface StepCompletePayload {
+    actionName: string;
+    stepIndex: number;
+    stepType: StepType;
+    success: boolean;
+    error?: string;
+}
+export interface FetchStartPayload {
+    source: string;
+    method: string;
+    path: string;
+    isOAS: boolean;
+    operationId?: string;
+    hasPagination: boolean;
+    hasSince: boolean;
+}
+export interface FetchCompletePayload {
+    source: string;
+    method: string;
+    path: string;
+    statusCode: number;
+    recordCount: number;
+    pagesFetched?: number;
+    bytesReceived?: number;
+    fromCache?: boolean;
+}
+export interface FetchRetryPayload {
+    source: string;
+    path: string;
+    attempt: number;
+    maxAttempts: number;
+    reason: string;
+    waitMs: number;
+}
+export interface FetchErrorPayload {
+    source: string;
+    path: string;
+    statusCode?: number;
+    error: string;
+    retryable: boolean;
+}
+export interface FetchHeartbeatPayload {
+    source: string;
+    path: string;
+    pagesProcessed: number;
+    itemsFetched: number;
+    hasMore: boolean;
+}
+export interface DataTransformPayload {
+    targetSchema?: string;
+    inputCount: number;
+    outputCount: number;
+    fieldsMapping: number;
+}
+export interface DataValidatePayload {
+    target: string;
+    passed: boolean;
+    warningCount: number;
+    errorCount: number;
+    rules: string[];
+}
+export interface DataStorePayload {
+    storeName: string;
+    storeType: string;
+    operation: 'set' | 'update' | 'upsert' | 'append';
+    itemCount: number;
+    key?: string;
+}
+export interface LoopStartPayload {
+    variable: string;
+    collectionSize: number;
+    hasFilter: boolean;
+}
+export interface LoopIterationPayload {
+    variable: string;
+    itemIndex: number;
+    totalItems: number;
+}
+export interface LoopCompletePayload {
+    variable: string;
+    totalItems: number;
+    itemsProcessed: number;
+    itemsSkipped: number;
+    itemsFailed: number;
+}
+export interface LoopHeartbeatPayload {
+    variable: string;
+    current: number;
+    total: number;
+    processedCount: number;
+}
+export interface MatchAttemptPayload {
+    schemas: string[];
+    hasDefault: boolean;
+}
+export interface MatchResultPayload {
+    matchedSchema?: string;
+    isDefault: boolean;
+    flowDirective?: 'skip' | 'retry' | 'abort';
+}
+export interface WebhookRegisterPayload {
+    registrationId: string;
+    path: string;
+    webhookUrl: string;
+    timeout: number;
+    expectedEvents: number;
+}
+export interface WebhookEventPayload {
+    registrationId: string;
+    eventIndex: number;
+    totalExpected: number;
+    filtered: boolean;
+}
+export interface WebhookCompletePayload {
+    registrationId: string;
+    eventsReceived: number;
+    timedOut: boolean;
+    storedTo?: string;
+}
+export interface CheckpointSavePayload {
+    stageIndex: number;
+    stepIndex: number;
+    reason: 'manual' | 'webhook' | 'error' | 'pause';
+    variableCount: number;
+}
+export interface CheckpointResumePayload {
+    stageIndex: number;
+    stepIndex: number;
+    originalExecutionId: string;
+    stagesSkipped: number;
+}
+export interface SyncCheckpointPayload {
+    checkpointKey: string;
+    lastSyncTime: string;
+    recordsFetched: number;
+    isIncremental: boolean;
+}
+export interface RateLimitPayload {
+    source: string;
+    endpoint?: string;
+    waitSeconds: number;
+    strategy: string;
+}
+export interface CircuitBreakerPayload {
+    source: string;
+    endpoint?: string;
+    state: 'open' | 'half-open' | 'closed';
+    failures: number;
+    reason?: string;
+}
+export type EventType = 'mission.start' | 'mission.complete' | 'mission.failed' | 'mission.paused' | 'stage.start' | 'stage.complete' | 'step.start' | 'step.complete' | 'fetch.start' | 'fetch.complete' | 'fetch.retry' | 'fetch.error' | 'fetch.heartbeat' | 'data.transform' | 'data.validate' | 'data.store' | 'loop.start' | 'loop.iteration' | 'loop.complete' | 'loop.heartbeat' | 'match.attempt' | 'match.result' | 'webhook.register' | 'webhook.event' | 'webhook.complete' | 'checkpoint.save' | 'checkpoint.resume' | 'sync.checkpoint' | 'ratelimit.wait' | 'ratelimit.resume' | 'circuit.open' | 'circuit.halfopen' | 'circuit.close';
+export type EventHandler<T = unknown> = (event: ObservabilityEvent<T>) => void;
+export interface EventEmitter {
+    /** Emit an event */
+    emit<T>(type: EventType, payload: T): void;
+    /** Subscribe to a specific event type */
+    on<T>(type: EventType, handler: EventHandler<T>): () => void;
+    /** Subscribe to all events */
+    onAll(handler: EventHandler): () => void;
+    /** Remove all handlers */
+    clear(): void;
+}
+export declare class ObservabilityEmitter implements EventEmitter {
+    private executionId;
+    private mission;
+    private handlers;
+    private allHandlers;
+    private startTime;
+    private lastEventTime;
+    constructor(executionId: string, mission: string);
+    emit<T>(type: EventType, payload: T): void;
+    on<T>(type: EventType, handler: EventHandler<T>): () => void;
+    onAll(handler: EventHandler): () => void;
+    clear(): void;
+    /** Get total elapsed time since emitter creation */
+    getElapsedTime(): number;
+    /** Update execution context (for resume scenarios) */
+    setContext(executionId: string, mission: string): void;
+}
+/**
+ * Create a new observability emitter
+ */
+export declare function createEmitter(executionId: string, mission: string): ObservabilityEmitter;

package/dist/observability/events.js

@@ -0,0 +1,90 @@
+/**
+ * Observability Events - Typed events for mission execution
+ *
+ * Provides a comprehensive event system for tracking execution progress,
+ * performance metrics, and debugging information.
+ */
+// ============================================================================
+// Event Emitter Implementation
+// ============================================================================
+export class ObservabilityEmitter {
+    executionId;
+    mission;
+    handlers = new Map();
+    allHandlers = new Set();
+    startTime;
+    lastEventTime;
+    constructor(executionId, mission) {
+        this.executionId = executionId;
+        this.mission = mission;
+        this.startTime = Date.now();
+        this.lastEventTime = this.startTime;
+    }
+    emit(type, payload) {
+        const now = Date.now();
+        const event = {
+            type,
+            executionId: this.executionId,
+            mission: this.mission,
+            timestamp: new Date().toISOString(),
+            duration: now - this.lastEventTime,
+            payload,
+        };
+        this.lastEventTime = now;
+        // Notify specific handlers
+        const typeHandlers = this.handlers.get(type);
+        if (typeHandlers) {
+            for (const handler of typeHandlers) {
+                try {
+                    handler(event);
+                }
+                catch {
+                    // Swallow handler errors to prevent breaking execution
+                }
+            }
+        }
+        // Notify all-event handlers
+        for (const handler of this.allHandlers) {
+            try {
+                handler(event);
+            }
+            catch {
+                // Swallow handler errors
+            }
+        }
+    }
+    on(type, handler) {
+        if (!this.handlers.has(type)) {
+            this.handlers.set(type, new Set());
+        }
+        this.handlers.get(type).add(handler);
+        return () => {
+            this.handlers.get(type)?.delete(handler);
+        };
+    }
+    onAll(handler) {
+        this.allHandlers.add(handler);
+        return () => {
+            this.allHandlers.delete(handler);
+        };
+    }
+    clear() {
+        this.handlers.clear();
+        this.allHandlers.clear();
+    }
+    /** Get total elapsed time since emitter creation */
+    getElapsedTime() {
+        return Date.now() - this.startTime;
+    }
+    /** Update execution context (for resume scenarios) */
+    setContext(executionId, mission) {
+        this.executionId = executionId;
+        this.mission = mission;
+    }
+}
+/**
+ * Create a new observability emitter
+ */
+export function createEmitter(executionId, mission) {
+    return new ObservabilityEmitter(executionId, mission);
+}

package/dist/observability/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Observability Module - Mission execution monitoring
+ *
+ * Provides comprehensive observability for Reqon missions:
+ * - Structured event system
+ * - Enhanced logging with context
+ * - OpenTelemetry integration
+ * - Multiple output adapters
+ */
+export type { LogLevel, ObservabilityEvent, EventType, EventHandler, EventEmitter, MissionStartPayload, MissionCompletePayload, MissionFailedPayload, StageStartPayload, StageCompletePayload, StepType, StepStartPayload, StepCompletePayload, FetchStartPayload, FetchCompletePayload, FetchRetryPayload, FetchErrorPayload, FetchHeartbeatPayload, DataTransformPayload, DataValidatePayload, DataStorePayload, LoopStartPayload, LoopIterationPayload, LoopCompletePayload, LoopHeartbeatPayload, MatchAttemptPayload, MatchResultPayload, WebhookRegisterPayload, WebhookEventPayload, WebhookCompletePayload, CheckpointSavePayload, CheckpointResumePayload, SyncCheckpointPayload, RateLimitPayload, CircuitBreakerPayload, } from './events.js';
+export { ObservabilityEmitter, createEmitter } from './events.js';
+export type { LogEntry, Span, LogOutput, StructuredLogger, CreateLoggerOptions } from './logger.js';
+export { ConsoleOutput, JsonLinesOutput, BufferOutput, EventOutput, createStructuredLogger, } from './logger.js';
+export type { OTelSpan, OTelAttribute, OTelSpanEvent, TraceContext, OTLPExporterConfig, } from './otel.js';
+export { generateTraceId, generateSpanId, SpanBuilder, OTelEventAdapter, OTLPExporter, OTelLogOutput, createOTelListener, } from './otel.js';

package/dist/observability/index.js

@@ -0,0 +1,12 @@
+/**
+ * Observability Module - Mission execution monitoring
+ *
+ * Provides comprehensive observability for Reqon missions:
+ * - Structured event system
+ * - Enhanced logging with context
+ * - OpenTelemetry integration
+ * - Multiple output adapters
+ */
+export { ObservabilityEmitter, createEmitter } from './events.js';
+export { ConsoleOutput, JsonLinesOutput, BufferOutput, EventOutput, createStructuredLogger, } from './logger.js';
+export { generateTraceId, generateSpanId, SpanBuilder, OTelEventAdapter, OTLPExporter, OTelLogOutput, createOTelListener, } from './otel.js';

package/dist/observability/logger.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Structured Logger - Enhanced logging with context and spans
+ *
+ * Provides structured logging capabilities with:
+ * - Hierarchical context (child loggers)
+ * - Timing spans for operations
+ * - Multiple output formats
+ * - Integration with event emitter
+ */
+import type { LogLevel, EventEmitter } from './events.js';
+/** Log entry structure */
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    timestamp: string;
+    context: Record<string, unknown>;
+    spanId?: string;
+    parentSpanId?: string;
+    duration?: number;
+}
+/** Span for timing operations */
+export interface Span {
+    /** End the span and return duration in ms */
+    end(): number;
+    /** Add context to the span */
+    addContext(context: Record<string, unknown>): void;
+    /** Create a child span */
+    child(name: string): Span;
+    /** Get span ID */
+    readonly id: string;
+}
+/** Output handler interface */
+export interface LogOutput {
+    write(entry: LogEntry): void;
+}
+/** Structured logger interface */
+export interface StructuredLogger {
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+    /** Create a child logger with additional context */
+    child(context: Record<string, unknown>): StructuredLogger;
+    /** Create a timing span */
+    span(name: string): Span;
+    /** Set minimum log level */
+    setLevel(level: LogLevel): void;
+    /** Add an output handler */
+    addOutput(output: LogOutput): void;
+}
+/** Console output with human-readable formatting */
+export declare class ConsoleOutput implements LogOutput {
+    private prefix;
+    private colors;
+    constructor(options?: {
+        prefix?: string;
+        colors?: boolean;
+    });
+    write(entry: LogEntry): void;
+}
+/** JSON Lines output for log aggregation */
+export declare class JsonLinesOutput implements LogOutput {
+    private stream;
+    constructor(stream?: {
+        write: (line: string) => void;
+    });
+    write(entry: LogEntry): void;
+}
+/** Buffer output for testing */
+export declare class BufferOutput implements LogOutput {
+    readonly entries: LogEntry[];
+    write(entry: LogEntry): void;
+    clear(): void;
+    find(predicate: (entry: LogEntry) => boolean): LogEntry | undefined;
+    filter(predicate: (entry: LogEntry) => boolean): LogEntry[];
+}
+/** Event emitter output - bridges logs to events */
+export declare class EventOutput implements LogOutput {
+    private emitter;
+    constructor(emitter: EventEmitter);
+    write(entry: LogEntry): void;
+}
+export interface CreateLoggerOptions {
+    /** Logger prefix for console output */
+    prefix?: string;
+    /** Minimum log level */
+    level?: LogLevel;
+    /** Include console output */
+    console?: boolean;
+    /** Include JSON lines output */
+    jsonLines?: boolean;
+    /** Custom JSON lines stream */
+    jsonStream?: {
+        write: (line: string) => void;
+    };
+    /** Event emitter for bridging */
+    eventEmitter?: EventEmitter;
+    /** Initial context */
+    context?: Record<string, unknown>;
+    /** Silent mode (no outputs) */
+    silent?: boolean;
+}
+/**
+ * Create a structured logger with configured outputs
+ */
+export declare function createStructuredLogger(options?: CreateLoggerOptions): StructuredLogger;