arvo-event-handler 2.0.3 → 2.1.0

package/dist/ArvoEventRouter/index.d.ts

@@ -1,110 +1,68 @@
-import { ArvoContract, ArvoEvent, ArvoExecutionSpanKind, OpenInferenceSpanKind } from 'arvo-core';
+import { ArvoContract, ArvoEvent } from 'arvo-core';
 import ArvoEventHandler from '../ArvoEventHandler';
 import { IArvoEventRouter } from './types';
-import { SpanKind } from '@opentelemetry/api';
+import { SpanOptions } from '@opentelemetry/api';
 import AbstractArvoEventHandler from '../AbstractArvoEventHandler';
-import { OpenTelemetryConfig } from '../OpenTelemetry/types';
+import { ArvoEventHandlerOpenTelemetryOptions } from '../types';
 /**
- * ArvoEventRouter class handles routing of ArvoEvents to appropriate event handlers.
+ * ArvoEventRouter manages event routing and execution within the Arvo event system. It directs
+ * incoming events to appropriate handlers based on event type while maintaining telemetry
+ * and error handling.
+ *
+ * The router enforces contract validation, manages execution costs, and provides comprehensive
+ * telemetry via OpenTelemetry integration. It handles event lifecycle management from initial
+ * receipt through processing and response generation.
+ *
+ * @example
+ * ```typescript
+ * const router = createArvoEventRouter({
+ *   source: "payment.service",
+ *   executionunits: 1,
+ *   handlers: [paymentProcessedHandler, paymentFailedHandler]
+ * });
+ *
+ * // Route an incoming event
+ * const results = await router.execute(incomingEvent);
+ * ```
  */
 export declare class ArvoEventRouter extends AbstractArvoEventHandler {
-    private readonly _handlerDefaultSource;
-    private readonly _source;
-    /**
-     * The source name of the router.
-     *
-     * @remarks
-     * The router attempts to match the `event.to` field with this value.
-     * If the source is 'arvo.event.router', the `event.to` is not matched and any event is allowed.
-     * 'arvo.event.router' is the default source which is set automatically in case a source
-     * is not explicitly provided
-     */
-    get source(): string;
-    /**
-     * A list of all available event handlers to be used by the router.
-     */
-    readonly handlers: ArvoEventHandler<ArvoContract>[];
+    /** Source identifier for the router used in event routing */
+    readonly source: string;
+    /** Registry mapping event types to their handlers */
+    readonly handlersMap: Record<string, ArvoEventHandler<ArvoContract>>;
     /**
-     * The default execution cost of the function.
-     * This can represent a dollar value or some other number with a rate card.
+     * Computational cost metric for router operations.
+     * Used for resource tracking and billing calculations.
      */
     readonly executionunits: number;
     /**
-     * A map of all the available event handlers
+     * The OpenTelemetry span options
      */
-    readonly handlersMap: Record<string, ArvoEventHandler<ArvoContract>>;
-    readonly openInferenceSpanKind: OpenInferenceSpanKind;
-    readonly arvoExecutionSpanKind: ArvoExecutionSpanKind;
-    readonly openTelemetrySpanKind: SpanKind;
+    readonly spanOptions: SpanOptions;
     /**
-     * Creates an instance of ArvoEventRouter.
-     * @param param - The parameters for initializing the router
-     * @throws {Error} If there are duplicate handlers for the same event type or the
-     *                 source in an invalid string
+     * Creates an ArvoEventRouter instance with specified configuration.
+     *
+     * @param param - Router configuration containing source, handlers, and execution parameters
+     *
+     * @throws {Error} When source contains invalid characters (non-alphanumeric)
+     * @throws {Error} When multiple handlers are registered for the same event type
      */
     constructor(param: IArvoEventRouter);
     /**
-     * Executes the routing process for a given ArvoEvent.
-     *
-     * @param event - The ArvoEvent to be processed and routed.
-     * @param opentelemetry - Configuration for OpenTelemetry integration, including tracing options
-     *                        and context inheritance settings. Default is inherit from event and internal tracer
-     * @returns A Promise that resolves to an array of ArvoEvents.
-     *
-     * @remarks
-     * This function performs the following steps:
-     * 1. Initializes OpenTelemetry span for tracing and monitoring.
-     * 2. Validates the event's destination ('to' field) against the router's source.
-     * 3. Finds the appropriate handler for the event based on its type.
-     * 4. Executes the handler and processes the results.
-     * 5. Handles any errors that occur during the process.
-     *
-     * @throws Error event if the event's 'to' field doesn't match the router's source.
-     * @throws Error event if no valid handler is found for the event type.
-     *
-     * **Telemetry**
+     * Routes and executes an event through its appropriate handler. Creates a telemetry span,
+     * validates the event destination, finds a matching handler, and processes the event.
+     * Handles routing errors, missing handlers, and execution failures by returning error
+     * events with telemetry context. Tracks performance through execution units and span
+     * propagation.
      *
-     * - Creates an OpenTelemetry span for the entire execution process.
-     * - Sets span attributes for OpenInference and ArvoExecution.
-     * - Propagates trace context from the input event if available.
-     * - Records any errors in the span and sets the span status accordingly.
-     * - Adds event attributes to the span for both input and output events.
-     *
-     * **Routing**
-     *
-     * The routing process involves:
-     * 1. Matching the event's 'to' field with the router's source (if specified).
-     * 2. Finding a handler that accepts the event's type.
-     * 3. Executing the matched handler with the event.
-     * 4. Processing the handler's results and creating new events.
-     *
-     * **Error Handling**
-     *
-     * If an error occurs during execution:
-     * 1. The error is recorded in the OpenTelemetry span.
-     * 2. A new error event is created and returned.
-     * 3. The error event is sent back to the original event's source.
-     *
-     * **Performance**
-     *
-     * - Execution units are tracked for both successful executions and errors.
-     * - The router's default execution units are used for error events.
+     * @param event The event to be routed and processed
+     * @param opentelemetry Configuration for telemetry context inheritance
+     * @returns Promise resolving to resulting events or error events
      */
-    execute(event: ArvoEvent, opentelemetry?: OpenTelemetryConfig): Promise<ArvoEvent[]>;
+    execute(event: ArvoEvent, opentelemetry?: ArvoEventHandlerOpenTelemetryOptions): Promise<ArvoEvent[]>;
     /**
-     * Provides the schema for system error events.
-     *
-     * @returns An object containing the error event type and schema.
-     *
-     * @remarks
-     * This getter defines the structure for system error events that may be emitted
-     * when an unexpected error occurs during event handling. The error event type
-     * is prefixed with 'sys.' followed by the handler's source and '.error'.
-     * The schema used for these error events is the standard ArvoErrorSchema.
-     *
-     * @example
-     * // If the handler's source is 'user.service'
-     * // The system error event type would be 'sys.user.service.error'
+     * System error schema configuration.
+     * Error events follow format: sys.<handler-source>.error
      */
     get systemErrorSchema(): {
         type: string;
@@ -113,12 +71,12 @@ export declare class ArvoEventRouter extends AbstractArvoEventHandler {
             errorMessage: import("zod").ZodString;
             errorStack: import("zod").ZodNullable<import("zod").ZodString>;
         }, "strip", import("zod").ZodTypeAny, {
-            errorMessage: string;
             errorName: string;
+            errorMessage: string;
             errorStack: string | null;
         }, {
-            errorMessage: string;
             errorName: string;
+            errorMessage: string;
             errorStack: string | null;
         }>;
     };

package/dist/ArvoEventRouter/index.js

@@ -14,6 +14,17 @@ var __extends = (this && this.__extends) || (function () {
         d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
     };
 })();
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -60,209 +71,181 @@ var utils_1 = require("../utils");
 var api_1 = require("@opentelemetry/api");
 var utils_2 = require("./utils");
 var AbstractArvoEventHandler_1 = __importDefault(require("../AbstractArvoEventHandler"));
-var OpenTelemetry_1 = require("../OpenTelemetry");
-var utils_3 = require("../OpenTelemetry/utils");
 /**
- * ArvoEventRouter class handles routing of ArvoEvents to appropriate event handlers.
+ * ArvoEventRouter manages event routing and execution within the Arvo event system. It directs
+ * incoming events to appropriate handlers based on event type while maintaining telemetry
+ * and error handling.
+ *
+ * The router enforces contract validation, manages execution costs, and provides comprehensive
+ * telemetry via OpenTelemetry integration. It handles event lifecycle management from initial
+ * receipt through processing and response generation.
+ *
+ * @example
+ * ```typescript
+ * const router = createArvoEventRouter({
+ *   source: "payment.service",
+ *   executionunits: 1,
+ *   handlers: [paymentProcessedHandler, paymentFailedHandler]
+ * });
+ *
+ * // Route an incoming event
+ * const results = await router.execute(incomingEvent);
+ * ```
  */
 var ArvoEventRouter = /** @class */ (function (_super) {
     __extends(ArvoEventRouter, _super);
     /**
-     * Creates an instance of ArvoEventRouter.
-     * @param param - The parameters for initializing the router
-     * @throws {Error} If there are duplicate handlers for the same event type or the
-     *                 source in an invalid string
+     * Creates an ArvoEventRouter instance with specified configuration.
+     *
+     * @param param - Router configuration containing source, handlers, and execution parameters
+     *
+     * @throws {Error} When source contains invalid characters (non-alphanumeric)
+     * @throws {Error} When multiple handlers are registered for the same event type
      */
     function ArvoEventRouter(param) {
+        var _a;
+        var _b, _c;
         var _this = _super.call(this) || this;
-        _this._handlerDefaultSource = "arvo.event.router";
-        /**
-         * A map of all the available event handlers
-         */
+        /** Registry mapping event types to their handlers */
         _this.handlersMap = {};
-        _this.openInferenceSpanKind = arvo_core_1.OpenInferenceSpanKind.CHAIN;
-        _this.arvoExecutionSpanKind = arvo_core_1.ArvoExecutionSpanKind.EVENT_HANDLER;
-        _this.openTelemetrySpanKind = api_1.SpanKind.INTERNAL;
-        _this.handlers = param.handlers;
         if (param.source && !(0, utils_1.isLowerAlphanumeric)(param.source)) {
-            throw new Error("Invalid 'source' = '".concat(param.source, "'. The 'source' must only contain alphanumeric characters e.g. test.router"));
+            throw new Error("Invalid source identifier '".concat(param.source, "': Must contain only alphanumeric characters (example: payment.service)"));
         }
-        _this._source = (0, utils_1.isNullOrUndefined)(param.source) ? null : param.source;
+        _this.source = param.source;
         _this.executionunits = param.executionunits;
-        for (var _i = 0, _a = _this.handlers; _i < _a.length; _i++) {
-            var handler = _a[_i];
+        for (var _i = 0, _d = param.handlers; _i < _d.length; _i++) {
+            var handler = _d[_i];
             if (_this.handlersMap[handler.contract.type]) {
                 var existingHandler = _this.handlersMap[handler.contract.type];
-                throw new Error((0, arvo_core_1.cleanString)("\n          Duplicate handlers for event.type=".concat(handler.contract.type, " found. There are same 'contract.accept.types' in \n          contracts 'uri=").concat(existingHandler.contract.uri, "' and 'uri=").concat(handler.contract.uri, "'. This router does not support handlers\n          with the same 'contract.accept.type'.\n        ")));
+                throw new Error("Duplicate handler registration detected for event type '".concat(handler.contract.type, "'. ") +
+                    "Conflicts between contracts: ".concat(existingHandler.contract.uri, " and ").concat(handler.contract.uri));
             }
             _this.handlersMap[handler.contract.type] = handler;
         }
-        Object.freeze(_this.handlers);
-        Object.freeze(_this.handlersMap);
+        _this.spanOptions = __assign(__assign({ kind: api_1.SpanKind.CONSUMER }, param.spanOptions), { attributes: __assign(__assign((_a = {}, _a[arvo_core_1.ArvoExecution.ATTR_SPAN_KIND] = arvo_core_1.ArvoExecutionSpanKind.EVENT_HANDLER, _a[arvo_core_1.OpenInference.ATTR_SPAN_KIND] = arvo_core_1.OpenInferenceSpanKind.CHAIN, _a), ((_c = (_b = param.spanOptions) === null || _b === void 0 ? void 0 : _b.attributes) !== null && _c !== void 0 ? _c : {})), { 'arvo.handler.source': _this.source }) });
         return _this;
     }
-    Object.defineProperty(ArvoEventRouter.prototype, "source", {
-        /**
-         * The source name of the router.
-         *
-         * @remarks
-         * The router attempts to match the `event.to` field with this value.
-         * If the source is 'arvo.event.router', the `event.to` is not matched and any event is allowed.
-         * 'arvo.event.router' is the default source which is set automatically in case a source
-         * is not explicitly provided
-         */
-        get: function () {
-            var _a;
-            return (_a = this._source) !== null && _a !== void 0 ? _a : this._handlerDefaultSource;
-        },
-        enumerable: false,
-        configurable: true
-    });
     /**
-     * Executes the routing process for a given ArvoEvent.
-     *
-     * @param event - The ArvoEvent to be processed and routed.
-     * @param opentelemetry - Configuration for OpenTelemetry integration, including tracing options
-     *                        and context inheritance settings. Default is inherit from event and internal tracer
-     * @returns A Promise that resolves to an array of ArvoEvents.
-     *
-     * @remarks
-     * This function performs the following steps:
-     * 1. Initializes OpenTelemetry span for tracing and monitoring.
-     * 2. Validates the event's destination ('to' field) against the router's source.
-     * 3. Finds the appropriate handler for the event based on its type.
-     * 4. Executes the handler and processes the results.
-     * 5. Handles any errors that occur during the process.
-     *
-     * @throws Error event if the event's 'to' field doesn't match the router's source.
-     * @throws Error event if no valid handler is found for the event type.
-     *
-     * **Telemetry**
-     *
-     * - Creates an OpenTelemetry span for the entire execution process.
-     * - Sets span attributes for OpenInference and ArvoExecution.
-     * - Propagates trace context from the input event if available.
-     * - Records any errors in the span and sets the span status accordingly.
-     * - Adds event attributes to the span for both input and output events.
-     *
-     * **Routing**
+     * Routes and executes an event through its appropriate handler. Creates a telemetry span,
+     * validates the event destination, finds a matching handler, and processes the event.
+     * Handles routing errors, missing handlers, and execution failures by returning error
+     * events with telemetry context. Tracks performance through execution units and span
+     * propagation.
      *
-     * The routing process involves:
-     * 1. Matching the event's 'to' field with the router's source (if specified).
-     * 2. Finding a handler that accepts the event's type.
-     * 3. Executing the matched handler with the event.
-     * 4. Processing the handler's results and creating new events.
-     *
-     * **Error Handling**
-     *
-     * If an error occurs during execution:
-     * 1. The error is recorded in the OpenTelemetry span.
-     * 2. A new error event is created and returned.
-     * 3. The error event is sent back to the original event's source.
-     *
-     * **Performance**
-     *
-     * - Execution units are tracked for both successful executions and errors.
-     * - The router's default execution units are used for error events.
+     * @param event The event to be routed and processed
+     * @param opentelemetry Configuration for telemetry context inheritance
+     * @returns Promise resolving to resulting events or error events
      */
-    ArvoEventRouter.prototype.execute = function (event, opentelemetry) {
-        return __awaiter(this, void 0, void 0, function () {
-            var span;
+    ArvoEventRouter.prototype.execute = function (event_1) {
+        return __awaiter(this, arguments, void 0, function (event, opentelemetry) {
             var _this = this;
-            var _a;
-            return __generator(this, function (_b) {
-                switch (_b.label) {
-                    case 0:
-                        span = (0, utils_3.createOtelSpan)({
-                            spanName: "ArvoEventRouter.source<".concat((_a = this._source) !== null && _a !== void 0 ? _a : 'arvo.event.router', ">.execute<").concat(event.type, ">"),
-                            spanKinds: {
-                                kind: this.openTelemetrySpanKind,
-                                openInference: this.openInferenceSpanKind,
-                                arvoExecution: this.arvoExecutionSpanKind,
-                            },
-                            event: event,
-                            opentelemetryConfig: opentelemetry,
-                        });
-                        return [4 /*yield*/, api_1.context.with(api_1.trace.setSpan(api_1.context.active(), span), function () { return __awaiter(_this, void 0, void 0, function () {
-                                var otelSpanHeaders, newEvent, results, error_1;
+            if (opentelemetry === void 0) { opentelemetry = {
+                inheritFrom: 'EVENT',
+            }; }
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, arvo_core_1.ArvoOpenTelemetry.getInstance().startActiveSpan({
+                            name: 'ArvoEventRouter',
+                            spanOptions: this.spanOptions,
+                            disableSpanManagement: true,
+                            context: opentelemetry.inheritFrom === 'EVENT'
+                                ? {
+                                    inheritFrom: 'TRACE_HEADERS',
+                                    traceHeaders: {
+                                        traceparent: event.traceparent,
+                                        tracestate: event.tracestate,
+                                    },
+                                }
+                                : {
+                                    inheritFrom: 'CONTEXT',
+                                    context: api_1.context.active(),
+                                },
+                            fn: function (span) { return __awaiter(_this, void 0, void 0, function () {
+                                var otelSpanHeaders, newEvent, results, resultingEvents, error_1;
                                 var _this = this;
-                                var _a;
-                                return __generator(this, function (_b) {
-                                    switch (_b.label) {
+                                return __generator(this, function (_a) {
+                                    switch (_a.label) {
                                         case 0:
                                             otelSpanHeaders = (0, arvo_core_1.currentOpenTelemetryHeaders)();
                                             newEvent = (0, utils_2.deleteOtelHeaders)(event);
-                                            _b.label = 1;
+                                            _a.label = 1;
                                         case 1:
-                                            _b.trys.push([1, 3, 4, 5]);
+                                            _a.trys.push([1, 3, 4, 5]);
                                             span.setStatus({ code: api_1.SpanStatusCode.OK });
-                                            if (!(0, utils_1.isNullOrUndefined)(this._source) &&
-                                                newEvent.to !== this._source) {
-                                                throw new Error((0, arvo_core_1.cleanString)("\n            Invalid event. The 'event.to' is ".concat(newEvent.to, " while this handler \n            listens to only 'event.to' equal to ").concat(this._source, ". If this is a mistake,\n            please update the 'source' field of the handler\n          ")));
+                                            Object.entries(event.otelAttributes).forEach(function (_a) {
+                                                var key = _a[0], value = _a[1];
+                                                return span.setAttribute("to_process.0.".concat(key), value);
+                                            });
+                                            (0, arvo_core_1.logToSpan)({
+                                                level: 'INFO',
+                                                message: "Initiating event resolution - Type: ".concat(newEvent.type, ", Source: ").concat(newEvent.source, ", Destination: ").concat(newEvent.to),
+                                            });
+                                            if (newEvent.to !== this.source) {
+                                                throw new Error("Event destination mismatch: Received destination '".concat(newEvent.to, "', ") +
+                                                    "but router accepts only '".concat(this.source, "'"));
                                             }
                                             if (!this.handlersMap[newEvent.type]) {
-                                                throw new Error((0, arvo_core_1.cleanString)("\n            Invalid event (type=".concat(newEvent.type, "). No valid handler \n            <handler[*].contract.type> found in the router.\n          ")));
+                                                throw new Error("No registered handler found for event type '".concat(newEvent.type, "'"));
                                             }
+                                            (0, arvo_core_1.logToSpan)({
+                                                level: 'INFO',
+                                                message: "Handler found for event type '".concat(newEvent.type, "' - Beginning event processing"),
+                                            });
                                             return [4 /*yield*/, this.handlersMap[newEvent.type].execute(newEvent, {
-                                                    inheritFrom: 'execution',
-                                                    tracer: (_a = opentelemetry === null || opentelemetry === void 0 ? void 0 : opentelemetry.tracer) !== null && _a !== void 0 ? _a : (0, OpenTelemetry_1.fetchOpenTelemetryTracer)(),
+                                                    inheritFrom: 'CONTEXT',
                                                 })];
                                         case 2:
-                                            results = _b.sent();
-                                            return [2 /*return*/, results.map(function (event) {
-                                                    var _a;
-                                                    return new arvo_core_1.ArvoEvent({
-                                                        id: event.id,
-                                                        time: event.time,
-                                                        source: event.source,
-                                                        specversion: '1.0',
-                                                        type: event.type,
-                                                        subject: event.subject,
-                                                        datacontenttype: event.datacontenttype,
-                                                        dataschema: event.dataschema,
-                                                        to: event.to,
-                                                        accesscontrol: event.accesscontrol,
-                                                        redirectto: event.redirectto,
-                                                        executionunits: ((_a = event.executionunits) !== null && _a !== void 0 ? _a : 0) + _this.executionunits,
-                                                        traceparent: otelSpanHeaders.traceparent,
-                                                        tracestate: otelSpanHeaders.tracestate,
-                                                    }, event.data, event.cloudevent.extensions);
-                                                })];
+                                            results = _a.sent();
+                                            resultingEvents = results.map(function (event) {
+                                                var _a;
+                                                return new arvo_core_1.ArvoEvent({
+                                                    id: event.id,
+                                                    time: event.time,
+                                                    source: _this.source,
+                                                    specversion: '1.0',
+                                                    type: event.type,
+                                                    subject: event.subject,
+                                                    datacontenttype: event.datacontenttype,
+                                                    dataschema: event.dataschema,
+                                                    to: event.to,
+                                                    accesscontrol: event.accesscontrol,
+                                                    redirectto: event.redirectto,
+                                                    executionunits: ((_a = event.executionunits) !== null && _a !== void 0 ? _a : 0) + _this.executionunits,
+                                                    traceparent: otelSpanHeaders.traceparent,
+                                                    tracestate: otelSpanHeaders.tracestate,
+                                                }, event.data, event.cloudevent.extensions);
+                                            });
+                                            (0, arvo_core_1.logToSpan)({
+                                                level: 'INFO',
+                                                message: "Event processing completed successfully - Generated ".concat(resultingEvents.length, " new event(s)"),
+                                            });
+                                            resultingEvents.forEach(function (event, index) {
+                                                return Object.entries(event.otelAttributes).forEach(function (_a) {
+                                                    var key = _a[0], value = _a[1];
+                                                    return span.setAttribute("to_emit.".concat(index, ".").concat(key), value);
+                                                });
+                                            });
+                                            return [2 /*return*/, resultingEvents];
                                         case 3:
-                                            error_1 = _b.sent();
-                                            return [2 /*return*/, (0, utils_1.createHandlerErrorOutputEvent)(error_1, otelSpanHeaders, "sys.".concat(this.source, ".error"), this.source, event, this.executionunits, function (param, extension) {
-                                                    var _a;
-                                                    return (0, arvo_core_1.createArvoEvent)(param, extension, {
-                                                        tracer: (_a = opentelemetry === null || opentelemetry === void 0 ? void 0 : opentelemetry.tracer) !== null && _a !== void 0 ? _a : (0, OpenTelemetry_1.fetchOpenTelemetryTracer)(),
-                                                    });
-                                                })];
+                                            error_1 = _a.sent();
+                                            return [2 /*return*/, (0, utils_1.createHandlerErrorOutputEvent)(error_1, otelSpanHeaders, this.systemErrorSchema.type, this.source, event, this.executionunits, function (param, extensions) { return (0, arvo_core_1.createArvoEvent)(param, extensions); })];
                                         case 4:
                                             span.end();
                                             return [7 /*endfinally*/];
                                         case 5: return [2 /*return*/];
                                     }
                                 });
-                            }); })];
-                    case 1: return [2 /*return*/, _b.sent()];
+                            }); },
+                        })];
+                    case 1: return [2 /*return*/, _a.sent()];
                 }
             });
         });
     };
     Object.defineProperty(ArvoEventRouter.prototype, "systemErrorSchema", {
         /**
-         * Provides the schema for system error events.
-         *
-         * @returns An object containing the error event type and schema.
-         *
-         * @remarks
-         * This getter defines the structure for system error events that may be emitted
-         * when an unexpected error occurs during event handling. The error event type
-         * is prefixed with 'sys.' followed by the handler's source and '.error'.
-         * The schema used for these error events is the standard ArvoErrorSchema.
-         *
-         * @example
-         * // If the handler's source is 'user.service'
-         * // The system error event type would be 'sys.user.service.error'
+         * System error schema configuration.
+         * Error events follow format: sys.<handler-source>.error
          */
         get: function () {
             return {

package/dist/ArvoEventRouter/types.d.ts

@@ -1,28 +1,18 @@
-import { ArvoContract, ArvoExecutionSpanKind, OpenInferenceSpanKind } from 'arvo-core';
+import { ArvoContract } from 'arvo-core';
 import ArvoEventHandler from '../ArvoEventHandler';
-import { SpanKind } from '@opentelemetry/api';
+import { SpanOptions } from '@opentelemetry/api';
 /**
  * Interface for defining an Arvo Event Router.
- *
- * @interface IArvoEventRouter
  */
 export interface IArvoEventRouter {
     /**
      * Defines the source name of the router.
      *
-     * @property {string} [source]
-     *
      * @remarks
      * If this field is defined:
      * - The router will only listen to events with a `to` field matching this `source`.
      * - If an event's `to` field doesn't match, a system error event will be emitted.
      * - For all emitted events, the `source` field will be overridden by this value.
-     *
-     * If this field is not defined:
-     * - The router will listen to all events.
-     * - If no appropriate handler is found for an event, a system error event will be emitted.
-     * - The `source` field of emitted events will be set according to the configuration
-     *   in the relevant `ArvoEventHandler`.
      */
     source: string;
     /**
@@ -40,15 +30,7 @@ export interface IArvoEventRouter {
      */
     handlers: ArvoEventHandler<ArvoContract<any, any, any>>[];
     /**
-     * The OpenTelemetry span kind attributes for the handler
-     * executor.
-     * @param [openInference] - The OpenInference span kind. Default is "CHAIN"
-     * @param [arvoExecution] - The ArvoExecution span kind. Default is "EVENT_HANDLER"
-     * @param [openTelemetry] - The OpenTelemetry span kind. Default is "INTERNAL"
+     * The OpenTelemetry span options
      */
-    spanKind?: {
-        openInference?: OpenInferenceSpanKind;
-        arvoExecution?: ArvoExecutionSpanKind;
-        openTelemetry?: SpanKind;
-    };
+    spanOptions?: SpanOptions;
 }