@blokjs/runner 0.2.0

package/dist/integrations/CloudWatchIntegration.js

@@ -0,0 +1,293 @@
+/**
+ * AWS CloudWatch Integration for Blok
+ *
+ * Sends metrics to CloudWatch Metrics and logs to CloudWatch Logs.
+ * Traces are exported via OTLP to the AWS Distro for OpenTelemetry (ADOT)
+ * Collector, which forwards them to AWS X-Ray.
+ *
+ * Uses lazy dynamic imports so AWS SDK packages are optional peer
+ * dependencies.  If the SDK is not installed the integration silently
+ * degrades (init returns false).
+ *
+ * Supported transports:
+ * - **Metrics** – CloudWatch PutMetricData (via @aws-sdk/client-cloudwatch)
+ * - **Logs**    – CloudWatch Logs PutLogEvents (via @aws-sdk/client-cloudwatch-logs)
+ * - **Traces**  – OTLP → ADOT Collector → X-Ray (reuses TracingBootstrap)
+ *
+ * @example
+ * ```typescript
+ * import { CloudWatchIntegration } from "@blokjs/runner";
+ *
+ * const cw = new CloudWatchIntegration({
+ *   region: "us-east-1",
+ *   serviceName: "blok-http",
+ *   logGroupName: "/blok/workflows",
+ *   namespace: "Blok",
+ * });
+ *
+ * await cw.init();
+ *
+ * // Send a custom metric
+ * await cw.putMetric("WorkflowDuration", 42, "Milliseconds");
+ *
+ * // Send a structured log entry
+ * await cw.putLog({ level: "info", message: "workflow completed", workflowName: "get-user" });
+ *
+ * // Enable OTLP traces via ADOT Collector
+ * const cw = new CloudWatchIntegration({
+ *   region: "us-east-1",
+ *   serviceName: "blok-http",
+ *   enableTracing: true,
+ *   adotEndpoint: "http://localhost:4318/v1/traces",
+ * });
+ * ```
+ */
+export class CloudWatchIntegration {
+    config;
+    cwClient = null;
+    cwLogsClient = null;
+    initialized = false;
+    tracingInitialized = false;
+    tracingShutdown = null;
+    sequenceToken;
+    // SDK constructors (loaded lazily)
+    PutMetricDataCommand = null;
+    PutLogEventsCommand = null;
+    CreateLogGroupCommand = null;
+    CreateLogStreamCommand = null;
+    // stats
+    metricsPublished = 0;
+    logsPublished = 0;
+    metricErrors = 0;
+    logErrors = 0;
+    constructor(config) {
+        this.config = {
+            region: process.env.AWS_REGION || "us-east-1",
+            serviceVersion: "0.0.1",
+            environment: process.env.NODE_ENV || "development",
+            logGroupName: "/blok/workflows",
+            namespace: "Blok",
+            enableTracing: false,
+            adotEndpoint: "http://localhost:4318/v1/traces",
+            samplingRatio: 1.0,
+            debug: false,
+            ...config,
+        };
+    }
+    /**
+     * Initialize CloudWatch clients.
+     * Returns false if AWS SDK packages are not installed.
+     */
+    async init() {
+        if (this.initialized)
+            return true;
+        try {
+            // Dynamically load AWS SDK v3 packages
+            // @ts-expect-error: optional peer dependency
+            const cwMod = await import("@aws-sdk/client-cloudwatch");
+            // @ts-expect-error: optional peer dependency
+            const cwLogsMod = await import("@aws-sdk/client-cloudwatch-logs");
+            const regionConfig = { region: this.config.region };
+            this.cwClient = new cwMod.CloudWatchClient(regionConfig);
+            this.cwLogsClient = new cwLogsMod.CloudWatchLogsClient(regionConfig);
+            this.PutMetricDataCommand = cwMod.PutMetricDataCommand;
+            this.PutLogEventsCommand = cwLogsMod.PutLogEventsCommand;
+            this.CreateLogGroupCommand = cwLogsMod.CreateLogGroupCommand;
+            this.CreateLogStreamCommand = cwLogsMod.CreateLogStreamCommand;
+            // Ensure log group & stream exist
+            await this.ensureLogDestination();
+            this.initialized = true;
+            // Optionally bootstrap OTLP tracing for X-Ray via ADOT
+            if (this.config.enableTracing) {
+                await this.initTracing();
+            }
+            return true;
+        }
+        catch {
+            // AWS SDK packages not installed — degrade gracefully
+            return false;
+        }
+    }
+    /* ------------------------------------------------------------------ */
+    /*  Metrics                                                           */
+    /* ------------------------------------------------------------------ */
+    /**
+     * Publish a custom metric to CloudWatch.
+     */
+    async putMetric(metricName, value, unit = "None", dimensions) {
+        if (!this.cwClient || !this.PutMetricDataCommand)
+            return false;
+        try {
+            const dims = {
+                Service: this.config.serviceName,
+                Environment: this.config.environment || "development",
+                ...dimensions,
+            };
+            const command = new this.PutMetricDataCommand({
+                Namespace: this.config.namespace,
+                MetricData: [
+                    {
+                        MetricName: metricName,
+                        Value: value,
+                        Unit: unit,
+                        Timestamp: new Date(),
+                        Dimensions: Object.entries(dims).map(([Name, Value]) => ({
+                            Name,
+                            Value,
+                        })),
+                    },
+                ],
+            });
+            await this.cwClient.send(command);
+            this.metricsPublished++;
+            return true;
+        }
+        catch {
+            this.metricErrors++;
+            return false;
+        }
+    }
+    /**
+     * Publish workflow execution metrics (duration + error count).
+     */
+    async recordWorkflowExecution(workflowName, durationMs, success) {
+        await this.putMetric("WorkflowDuration", durationMs, "Milliseconds", {
+            Workflow: workflowName,
+        });
+        if (!success) {
+            await this.putMetric("WorkflowErrors", 1, "Count", {
+                Workflow: workflowName,
+            });
+        }
+    }
+    /* ------------------------------------------------------------------ */
+    /*  Logs                                                              */
+    /* ------------------------------------------------------------------ */
+    /**
+     * Send a structured log entry to CloudWatch Logs.
+     */
+    async putLog(entry) {
+        if (!this.cwLogsClient || !this.PutLogEventsCommand)
+            return false;
+        try {
+            const event = {
+                timestamp: Date.now(),
+                message: JSON.stringify({
+                    ...entry,
+                    service: this.config.serviceName,
+                    version: this.config.serviceVersion,
+                    environment: this.config.environment,
+                }),
+            };
+            const command = new this.PutLogEventsCommand({
+                logGroupName: this.config.logGroupName,
+                logStreamName: this.getLogStreamName(),
+                logEvents: [event],
+                sequenceToken: this.sequenceToken,
+            });
+            const result = await this.cwLogsClient.send(command);
+            this.sequenceToken = result?.nextSequenceToken;
+            this.logsPublished++;
+            return true;
+        }
+        catch {
+            this.logErrors++;
+            return false;
+        }
+    }
+    /**
+     * Log a workflow error to CloudWatch Logs.
+     */
+    async logWorkflowError(error, context) {
+        return this.putLog({
+            level: "error",
+            message: error.message,
+            errorName: error.name,
+            stack: error.stack,
+            ...context,
+        });
+    }
+    /* ------------------------------------------------------------------ */
+    /*  Tracing (OTLP → ADOT → X-Ray)                                    */
+    /* ------------------------------------------------------------------ */
+    async initTracing() {
+        try {
+            const { bootstrapTracing } = await import("../monitoring/TracingBootstrap");
+            const result = await bootstrapTracing({
+                serviceName: this.config.serviceName,
+                serviceVersion: this.config.serviceVersion,
+                exporter: "otlp",
+                endpoint: this.config.adotEndpoint || "http://localhost:4318/v1/traces",
+                headers: {},
+                samplingRatio: this.config.samplingRatio,
+            });
+            if (!result)
+                return false;
+            this.tracingShutdown = result.shutdown;
+            this.tracingInitialized = true;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /* ------------------------------------------------------------------ */
+    /*  Lifecycle                                                         */
+    /* ------------------------------------------------------------------ */
+    isInitialized() {
+        return this.initialized;
+    }
+    isTracingEnabled() {
+        return this.tracingInitialized;
+    }
+    getStats() {
+        return {
+            initialized: this.initialized,
+            metricsPublished: this.metricsPublished,
+            logsPublished: this.logsPublished,
+            metricErrors: this.metricErrors,
+            logErrors: this.logErrors,
+            tracingEnabled: this.tracingInitialized,
+        };
+    }
+    async shutdown() {
+        if (this.tracingShutdown) {
+            await this.tracingShutdown();
+        }
+        this.initialized = false;
+        this.tracingInitialized = false;
+    }
+    async flush() {
+        // CloudWatch SDK calls are fire-and-forget; nothing buffered to flush.
+        // Tracing flush is handled by TracingBootstrap.
+    }
+    /* ------------------------------------------------------------------ */
+    /*  Internal helpers                                                  */
+    /* ------------------------------------------------------------------ */
+    getLogStreamName() {
+        if (this.config.logStreamName)
+            return this.config.logStreamName;
+        const date = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+        return `${this.config.serviceName}-${date}`;
+    }
+    async ensureLogDestination() {
+        if (!this.cwLogsClient || !this.CreateLogGroupCommand || !this.CreateLogStreamCommand)
+            return;
+        try {
+            await this.cwLogsClient.send(new this.CreateLogGroupCommand({ logGroupName: this.config.logGroupName }));
+        }
+        catch {
+            // ResourceAlreadyExistsException is expected
+        }
+        try {
+            await this.cwLogsClient.send(new this.CreateLogStreamCommand({
+                logGroupName: this.config.logGroupName,
+                logStreamName: this.getLogStreamName(),
+            }));
+        }
+        catch {
+            // ResourceAlreadyExistsException is expected
+        }
+    }
+}
+//# sourceMappingURL=CloudWatchIntegration.js.map

package/dist/integrations/CloudWatchIntegration.js.map

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

package/dist/integrations/SentryIntegration.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Sentry Error Tracking Integration for Blok
+ *
+ * Provides error tracking and performance monitoring via Sentry.
+ * Captures workflow execution errors, node failures, and trigger issues
+ * with full context (workflow name, node, request ID, etc.).
+ *
+ * Uses a lightweight adapter pattern so Sentry SDK is loaded lazily
+ * and the framework doesn't hard-depend on @sentry/node.
+ *
+ * @example
+ * ```typescript
+ * import { SentryIntegration } from "@blokjs/runner";
+ *
+ * const sentry = new SentryIntegration({
+ *   dsn: process.env.SENTRY_DSN!,
+ *   environment: process.env.NODE_ENV || "development",
+ *   release: "blok@1.0.0",
+ *   tracesSampleRate: 0.1,
+ * });
+ *
+ * await sentry.init();
+ *
+ * // In error handler
+ * sentry.captureWorkflowError(error, {
+ *   workflowName: "get-user",
+ *   workflowPath: "/users/:id",
+ *   requestId: ctx.id,
+ * });
+ * ```
+ */
+export interface SentryConfig {
+    /** Sentry DSN (Data Source Name) */
+    dsn: string;
+    /** Environment (e.g., "production", "staging", "development") */
+    environment?: string;
+    /** Release version */
+    release?: string;
+    /** Server name */
+    serverName?: string;
+    /** Sample rate for error events (0.0 to 1.0, default: 1.0) */
+    sampleRate?: number;
+    /** Sample rate for performance/transaction traces (0.0 to 1.0, default: 0.1) */
+    tracesSampleRate?: number;
+    /** Tags to add to all events */
+    tags?: Record<string, string>;
+    /** Enable debug mode */
+    debug?: boolean;
+}
+export interface WorkflowErrorContext {
+    workflowName: string;
+    workflowPath: string;
+    workflowVersion?: string;
+    requestId?: string;
+    nodeName?: string;
+    nodeType?: string;
+    triggerType?: string;
+    durationMs?: number;
+    userId?: string;
+}
+export interface SentryClient {
+    captureException(error: Error, context?: Record<string, unknown>): string;
+    captureMessage(message: string, level: "info" | "warning" | "error" | "fatal"): string;
+    setTag(key: string, value: string): void;
+    setUser(user: {
+        id: string;
+        email?: string;
+        username?: string;
+    } | null): void;
+    startTransaction(context: {
+        name: string;
+        op: string;
+    }): SentryTransaction;
+    flush(timeout: number): Promise<boolean>;
+}
+export interface SentryTransaction {
+    setTag(key: string, value: string): void;
+    setData(key: string, value: unknown): void;
+    finish(): void;
+    startChild(context: {
+        op: string;
+        description: string;
+    }): SentrySpan;
+}
+export interface SentrySpan {
+    setTag(key: string, value: string): void;
+    setData(key: string, value: unknown): void;
+    setStatus(status: string): void;
+    finish(): void;
+}
+export declare class SentryIntegration {
+    private config;
+    private client;
+    private initialized;
+    private eventCount;
+    private errorCount;
+    constructor(config: SentryConfig);
+    /**
+     * Initialize Sentry SDK (lazy-loads @sentry/node)
+     */
+    init(): Promise<boolean>;
+    /**
+     * Set a custom Sentry client (useful for testing)
+     */
+    setClient(client: SentryClient): void;
+    /**
+     * Capture a workflow execution error
+     */
+    captureWorkflowError(error: Error, context: WorkflowErrorContext): string | null;
+    /**
+     * Capture a node execution error
+     */
+    captureNodeError(error: Error, nodeName: string, nodeType: string, context?: {
+        workflowName?: string;
+        requestId?: string;
+    }): string | null;
+    /**
+     * Capture a trigger error
+     */
+    captureTriggerError(error: Error, triggerType: string, context?: Record<string, unknown>): string | null;
+    /**
+     * Capture a warning message
+     */
+    captureWarning(message: string, context?: Record<string, unknown>): string | null;
+    /**
+     * Set current user context
+     */
+    setUser(user: {
+        id: string;
+        email?: string;
+        username?: string;
+    } | null): void;
+    /**
+     * Add a tag to all future events
+     */
+    setTag(key: string, value: string): void;
+    /**
+     * Flush pending events to Sentry
+     */
+    flush(timeoutMs?: number): Promise<boolean>;
+    /**
+     * Check if Sentry is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Get stats about captured events
+     */
+    getStats(): {
+        initialized: boolean;
+        eventCount: number;
+        errorCount: number;
+    };
+}

package/dist/integrations/SentryIntegration.js

@@ -0,0 +1,200 @@
+/**
+ * Sentry Error Tracking Integration for Blok
+ *
+ * Provides error tracking and performance monitoring via Sentry.
+ * Captures workflow execution errors, node failures, and trigger issues
+ * with full context (workflow name, node, request ID, etc.).
+ *
+ * Uses a lightweight adapter pattern so Sentry SDK is loaded lazily
+ * and the framework doesn't hard-depend on @sentry/node.
+ *
+ * @example
+ * ```typescript
+ * import { SentryIntegration } from "@blokjs/runner";
+ *
+ * const sentry = new SentryIntegration({
+ *   dsn: process.env.SENTRY_DSN!,
+ *   environment: process.env.NODE_ENV || "development",
+ *   release: "blok@1.0.0",
+ *   tracesSampleRate: 0.1,
+ * });
+ *
+ * await sentry.init();
+ *
+ * // In error handler
+ * sentry.captureWorkflowError(error, {
+ *   workflowName: "get-user",
+ *   workflowPath: "/users/:id",
+ *   requestId: ctx.id,
+ * });
+ * ```
+ */
+export class SentryIntegration {
+    config;
+    client = null;
+    initialized = false;
+    eventCount = 0;
+    errorCount = 0;
+    constructor(config) {
+        this.config = {
+            environment: process.env.NODE_ENV || "development",
+            sampleRate: 1.0,
+            tracesSampleRate: 0.1,
+            debug: false,
+            ...config,
+        };
+    }
+    /**
+     * Initialize Sentry SDK (lazy-loads @sentry/node)
+     */
+    async init() {
+        if (this.initialized)
+            return true;
+        try {
+            // Dynamic import to avoid hard dependency — @sentry/node is optional
+            // @ts-expect-error: @sentry/node types not installed; loaded lazily at runtime
+            const Sentry = await import("@sentry/node");
+            Sentry.init({
+                dsn: this.config.dsn,
+                environment: this.config.environment,
+                release: this.config.release,
+                serverName: this.config.serverName,
+                sampleRate: this.config.sampleRate,
+                tracesSampleRate: this.config.tracesSampleRate,
+                debug: this.config.debug,
+            });
+            // Set global tags
+            if (this.config.tags) {
+                for (const [key, value] of Object.entries(this.config.tags)) {
+                    Sentry.setTag(key, value);
+                }
+            }
+            Sentry.setTag("framework", "blok");
+            // Create adapter
+            this.client = {
+                captureException: (error, context) => {
+                    return Sentry.captureException(error, {
+                        extra: context,
+                    });
+                },
+                captureMessage: (message, level) => {
+                    return Sentry.captureMessage(message, level);
+                },
+                setTag: (key, value) => Sentry.setTag(key, value),
+                setUser: (user) => Sentry.setUser(user),
+                startTransaction: (context) => {
+                    return Sentry.startSpan(context, (span) => span);
+                },
+                flush: (timeout) => Sentry.flush(timeout),
+            };
+            this.initialized = true;
+            return true;
+        }
+        catch {
+            // @sentry/node not installed - that's OK, fail silently
+            this.initialized = false;
+            return false;
+        }
+    }
+    /**
+     * Set a custom Sentry client (useful for testing)
+     */
+    setClient(client) {
+        this.client = client;
+        this.initialized = true;
+    }
+    /**
+     * Capture a workflow execution error
+     */
+    captureWorkflowError(error, context) {
+        if (!this.client)
+            return null;
+        this.errorCount++;
+        this.eventCount++;
+        const eventId = this.client.captureException(error, {
+            workflow_name: context.workflowName,
+            workflow_path: context.workflowPath,
+            workflow_version: context.workflowVersion,
+            request_id: context.requestId,
+            node_name: context.nodeName,
+            node_type: context.nodeType,
+            trigger_type: context.triggerType,
+            duration_ms: context.durationMs,
+        });
+        return eventId;
+    }
+    /**
+     * Capture a node execution error
+     */
+    captureNodeError(error, nodeName, nodeType, context) {
+        if (!this.client)
+            return null;
+        this.errorCount++;
+        this.eventCount++;
+        return this.client.captureException(error, {
+            node_name: nodeName,
+            node_type: nodeType,
+            workflow_name: context?.workflowName,
+            request_id: context?.requestId,
+        });
+    }
+    /**
+     * Capture a trigger error
+     */
+    captureTriggerError(error, triggerType, context) {
+        if (!this.client)
+            return null;
+        this.errorCount++;
+        this.eventCount++;
+        return this.client.captureException(error, {
+            trigger_type: triggerType,
+            ...context,
+        });
+    }
+    /**
+     * Capture a warning message
+     */
+    captureWarning(message, context) {
+        if (!this.client)
+            return null;
+        this.eventCount++;
+        return this.client.captureMessage(context ? `${message} | ${JSON.stringify(context)}` : message, "warning");
+    }
+    /**
+     * Set current user context
+     */
+    setUser(user) {
+        this.client?.setUser(user);
+    }
+    /**
+     * Add a tag to all future events
+     */
+    setTag(key, value) {
+        this.client?.setTag(key, value);
+    }
+    /**
+     * Flush pending events to Sentry
+     */
+    async flush(timeoutMs = 2000) {
+        if (!this.client)
+            return true;
+        return this.client.flush(timeoutMs);
+    }
+    /**
+     * Check if Sentry is initialized
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * Get stats about captured events
+     */
+    getStats() {
+        return {
+            initialized: this.initialized,
+            eventCount: this.eventCount,
+            errorCount: this.errorCount,
+        };
+    }
+}
+//# sourceMappingURL=SentryIntegration.js.map

package/dist/integrations/SentryIntegration.js.map

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

package/dist/integrations/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * External Integrations for Blok Framework
+ *
+ * Provides integrations with third-party services:
+ * - Sentry: Error tracking and performance monitoring
+ * - APM: DataDog, New Relic, and generic OTLP backends
+ * - CloudWatch: AWS CloudWatch metrics, logs, and traces (via ADOT → X-Ray)
+ * - Azure Monitor: Azure Application Insights traces, metrics, and events
+ *
+ * All integrations use lazy-loading to avoid hard dependencies.
+ */
+export { SentryIntegration } from "./SentryIntegration";
+export type { SentryConfig, WorkflowErrorContext, SentryClient, SentryTransaction, SentrySpan, } from "./SentryIntegration";
+export { APMIntegration } from "./APMIntegration";
+export type { APMVendor, APMConfig, APMBootstrapResult, } from "./APMIntegration";
+export { CloudWatchIntegration } from "./CloudWatchIntegration";
+export type { CloudWatchConfig, CloudWatchUnit, CloudWatchLogEntry, CloudWatchStats, } from "./CloudWatchIntegration";
+export { AzureMonitorIntegration } from "./AzureMonitorIntegration";
+export type { AzureMonitorConfig, AzureMonitorStats, } from "./AzureMonitorIntegration";