arvo-core 1.2.2 → 2.0.1

package/dist/ArvoContract/index.js

@@ -11,9 +11,9 @@ var __assign = (this && this.__assign) || function () {
     return __assign.apply(this, arguments);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-var validators_1 = require("./validators");
 var zod_to_json_schema_1 = require("zod-to-json-schema");
 var schema_1 = require("../schema");
+var utils_1 = require("../utils");
 /**
  * ArvoContract class represents a contract with defined input and output schemas.
  * It provides methods for validating inputs and outputs based on the contract's specifications.
@@ -22,8 +22,7 @@ var schema_1 = require("../schema");
  *
  * @template TUri - The URI of the contract
  * @template TType - The accept type, defaults to string.
- * @template TAcceptSchema - The of the data which the contract bound can accept
- * @template TEmits - The type of records the contract bound handler emits.
+ * @template TVersion - The contract versions
  */
 var ArvoContract = /** @class */ (function () {
     /**
@@ -32,9 +31,9 @@ var ArvoContract = /** @class */ (function () {
      */
     function ArvoContract(params) {
         var _a;
-        this._uri = validators_1.ArvoContractValidators.contract.uri.parse(params.uri);
-        this._accepts = this._validateAccepts(params.accepts);
-        this._emits = this._validateEmits(params.emits);
+        this._uri = params.uri;
+        this._type = params.type;
+        this._versions = params.versions;
         this.description = (_a = params.description) !== null && _a !== void 0 ? _a : null;
     }
     Object.defineProperty(ArvoContract.prototype, "uri", {
@@ -47,32 +46,60 @@ var ArvoContract = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
-    Object.defineProperty(ArvoContract.prototype, "accepts", {
+    Object.defineProperty(ArvoContract.prototype, "type", {
         /**
-         * Gets the type and schema of the event that the contact
-         * bound handler listens to.
+         * Get the type of the event the handler
+         * bound to the contract accepts
          */
         get: function () {
-            return this._accepts;
+            return this._type;
         },
         enumerable: false,
         configurable: true
     });
-    Object.defineProperty(ArvoContract.prototype, "emits", {
+    Object.defineProperty(ArvoContract.prototype, "versions", {
         /**
-         * Gets all event types and schemas that can be emitted by the
-         * contract bound handler.
+         * Gets the version of the contract
          */
         get: function () {
-            return __assign({}, this._emits);
+            return this._versions;
         },
         enumerable: false,
         configurable: true
     });
+    Object.defineProperty(ArvoContract.prototype, "latestVersion", {
+        /**
+         * Get the latest version of the contract
+         */
+        get: function () {
+            return Object.keys(this._versions).sort(function (a, b) {
+                return (0, utils_1.compareSemanticVersions)(b, a);
+            })[0];
+        },
+        enumerable: false,
+        configurable: true
+    });
+    /**
+     * Gets the type and schema of the event that the contact
+     * bound handler listens to.
+     */
+    ArvoContract.prototype.accepts = function (version) {
+        return {
+            type: this._type,
+            schema: this._versions[version].accepts,
+        };
+    };
+    /**
+     * Gets all event types and schemas that can be emitted by the
+     * contract bound handler.
+     */
+    ArvoContract.prototype.emits = function (version) {
+        return __assign({}, this._versions[version].emits);
+    };
     Object.defineProperty(ArvoContract.prototype, "systemError", {
         get: function () {
             return {
-                type: "sys.".concat(this._accepts.type, ".error"),
+                type: "sys.".concat(this._type, ".error"),
                 schema: schema_1.ArvoErrorSchema,
             };
         },
@@ -83,16 +110,18 @@ var ArvoContract = /** @class */ (function () {
      * Validates the contract bound handler's input/ accept event against the
      * contract's accept schema.
      * @template U - The type of the input to validate.
+     * @template V - The version to use
+     * @param version - The version to use
      * @param type - The type of the input event.
      * @param input - The input data to validate.
      * @returns The validation result.
      * @throws If the accept type is not found in the contract.
      */
-    ArvoContract.prototype.validateAccepts = function (type, input) {
-        if (type !== this._accepts.type) {
-            throw new Error("Accept type \"".concat(type, "\" not found in contract"));
+    ArvoContract.prototype.validateAccepts = function (version, type, input) {
+        if (type !== this._type) {
+            throw new Error("Accept type \"".concat(type, "\" for version \"").concat(version, "\" not found in contract \"").concat(this._uri, "\""));
         }
-        return this._accepts.schema.safeParse(input);
+        return this._versions[version].accepts.safeParse(input);
     };
     /**
      * Validates the contract bound handler's output/ emits against the
@@ -103,38 +132,14 @@ var ArvoContract = /** @class */ (function () {
      * @returns The validation result.
      * @throws If the emit type is not found in the contract.
      */
-    ArvoContract.prototype.validateEmits = function (type, output) {
-        var emit = this.emits[type];
+    ArvoContract.prototype.validateEmits = function (version, type, output) {
+        var _a, _b, _c;
+        var emit = (_c = (_b = (_a = this._versions) === null || _a === void 0 ? void 0 : _a[version]) === null || _b === void 0 ? void 0 : _b.emits) === null || _c === void 0 ? void 0 : _c[type];
         if (!emit) {
-            throw new Error("Emit type \"".concat(type.toString(), "\" not found in contract"));
+            throw new Error("Emit type \"".concat(type.toString(), "\" for version \"").concat(version, "\" not found in contract \"").concat(this._uri, "\""));
         }
         return emit.safeParse(output);
     };
-    /**
-     * Validates the accepts record.
-     * @param accepts - The accepts record to validate.
-     * @returns The validated accepts record.
-     * @private
-     */
-    ArvoContract.prototype._validateAccepts = function (accepts) {
-        return {
-            type: validators_1.ArvoContractValidators.record.type.parse(accepts.type),
-            schema: accepts.schema,
-        };
-    };
-    /**
-     * Validates the emits records.
-     * @param emits - The emits records to validate.
-     * @returns The validated emits records.
-     * @private
-     */
-    ArvoContract.prototype._validateEmits = function (emits) {
-        Object.entries(emits).forEach(function (_a) {
-            var key = _a[0];
-            return validators_1.ArvoContractValidators.record.type.parse(key);
-        });
-        return emits;
-    };
     /**
      * Exports the ArvoContract instance as a plain object conforming to the IArvoContract interface.
      * This method can be used to serialize the contract or to create a new instance with the same parameters.
@@ -144,12 +149,9 @@ var ArvoContract = /** @class */ (function () {
     ArvoContract.prototype.export = function () {
         return {
             uri: this._uri,
+            type: this._type,
             description: this.description,
-            accepts: {
-                type: this._accepts.type,
-                schema: this._accepts.schema,
-            },
-            emits: __assign({}, this._emits),
+            versions: this._versions,
         };
     };
     /**
@@ -164,18 +166,25 @@ var ArvoContract = /** @class */ (function () {
      *   - emits: An array of objects, each containing an emitted event type and its JSON Schema representation
      */
     ArvoContract.prototype.toJsonSchema = function () {
+        var _this = this;
         return {
             uri: this._uri,
             description: this.description,
-            accepts: {
-                type: this._accepts.type,
-                schema: (0, zod_to_json_schema_1.zodToJsonSchema)(this._accepts.schema),
-            },
-            emits: Object.entries(this._emits).map(function (_a) {
-                var key = _a[0], value = _a[1];
+            versions: Object.entries(this._versions).map(function (_a) {
+                var version = _a[0], contract = _a[1];
                 return ({
-                    type: key,
-                    schema: (0, zod_to_json_schema_1.zodToJsonSchema)(value),
+                    version: version,
+                    accepts: {
+                        type: _this._type,
+                        schema: (0, zod_to_json_schema_1.zodToJsonSchema)(contract.accepts),
+                    },
+                    emits: Object.entries(contract.emits).map(function (_a) {
+                        var key = _a[0], value = _a[1];
+                        return ({
+                            type: key,
+                            schema: (0, zod_to_json_schema_1.zodToJsonSchema)(value),
+                        });
+                    }),
                 });
             }),
         };

package/dist/ArvoContract/types.d.ts

@@ -1,59 +1,73 @@
 import { z } from 'zod';
 import zodToJsonSchema from 'zod-to-json-schema';
+import { ArvoSemanticVersion } from '../types';
 /**
- * Represents a record in an Arvo contract.
- * @template TType - The type of the record, defaults to string.
- * @template TSchema - The Zod schema for the record, defaults to any Zod type.
+ * Represents a record in an Arvo contract, containing a type identifier and its validation schema.
+ *
+ * @template TType - The type identifier for the record, must be a string type
+ * @template TSchema - The Zod schema used for validation, must be a Zod type
  */
 export type ArvoContractRecord<TType extends string = string, TSchema extends z.ZodTypeAny = z.ZodTypeAny> = {
-    /** The type identifier for the record */
+    /** The type identifier for this record */
     type: TType;
-    /** The Zod schema used for validating the record */
+    /** The Zod schema used for validating data associated with this record */
     schema: TSchema;
 };
 /**
- * Interface for an Arvo contract.
+ * Defines the structure of an Arvo contract, including its identifier, type, and versioned schemas.
  *
- * @template TUri - The URI of the contract
- * @template TType - The accept type, defaults to string.
- * @template TAcceptSchema - The of the data which the contract bound can accept
- * @template TEmits - The type of records the contract bound handler emits.
+ * @template TUri - The unique URI identifier for the contract
+ * @template TType - The event type that the contract's handler accepts
+ * @template TVersions - A record of versioned schemas, mapping semantic versions to their accept/emit schemas
  */
-export interface IArvoContract<TUri extends string = string, TType extends string = string, TAcceptSchema extends z.ZodTypeAny = z.ZodTypeAny, TEmits extends Record<string, z.ZodTypeAny> = Record<string, z.ZodTypeAny>> {
-    /** The unique identifier for the contract */
+export interface IArvoContract<TUri extends string = string, TType extends string = string, TVersions extends Record<ArvoSemanticVersion, {
+    accepts: z.ZodTypeAny;
+    emits: Record<string, z.ZodTypeAny>;
+}> = Record<ArvoSemanticVersion, {
+    accepts: z.ZodTypeAny;
+    emits: Record<string, z.ZodTypeAny>;
+}>> {
+    /** The unique URI identifier for this contract */
     uri: TUri;
-    /** The record type that the contract accepts */
-    accepts: ArvoContractRecord<TType, TAcceptSchema>;
-    /** An array of record types that the contract can emit */
-    emits: TEmits;
-    /** (Optional) The description of the contract or its handler */
+    /** The event type that this contract's handler accepts */
+    type: TType;
+    /** Optional description providing context about the contract or its handler */
     description?: string | null;
+    /** A record mapping semantic versions to their corresponding schemas */
+    versions: TVersions;
 }
 /**
- * Resolves the inferred type of an ArvoContractRecord's schema.
- * @template T - The ArvoContractRecord to resolve.
+ * Utility type that resolves the inferred TypeScript type from an ArvoContractRecord's schema.
+ *
+ * @template T - The ArvoContractRecord whose schema type should be inferred
  */
 export type ResolveArvoContractRecord<T extends ArvoContractRecord> = z.infer<T['schema']>;
 /**
- * Represents the JSON Schema representation of an ArvoContract.
+ * Represents the JSON Schema representation of an ArvoContract, used for serialization
+ * and documentation purposes. This structure follows the JSON Schema specification.
  */
 export type ArvoContractJSONSchema = {
-    /** The unique identifier (URI) of the contract */
+    /** The unique URI identifier for the contract */
     uri: string;
-    /** The description of the contract (null if not provided) */
+    /** The human-readable description of the contract */
     description: string | null;
-    /** The accepted input schema for the contract */
-    accepts: {
-        /** The type identifier for the accepted input */
-        type: string;
-        /** The JSON Schema representation of the accepted input schema */
-        schema: ReturnType<typeof zodToJsonSchema>;
-    };
-    /** An array of emitted event schemas for the contract */
-    emits: {
-        /** The type identifier for the emitted event */
-        type: string;
-        /** The JSON Schema representation of the emitted event schema */
-        schema: ReturnType<typeof zodToJsonSchema>;
+    /** Array of versioned schemas for this contract */
+    versions: {
+        /** The semantic version identifier for this schema version */
+        version: ArvoSemanticVersion;
+        /** The schema for accepted inputs in this version */
+        accepts: {
+            /** The type identifier for accepted inputs */
+            type: string;
+            /** JSON Schema representation of the input validation schema */
+            schema: ReturnType<typeof zodToJsonSchema>;
+        };
+        /** Array of schemas for events that can be emitted in this version */
+        emits: {
+            /** The type identifier for the emitted event */
+            type: string;
+            /** JSON Schema representation of the event validation schema */
+            schema: ReturnType<typeof zodToJsonSchema>;
+        }[];
     }[];
 };

package/dist/ArvoEvent/schema.d.ts

@@ -19,20 +19,20 @@ export declare const CloudEventContextSchema: z.ZodObject<{
     datacontenttype: z.ZodDefault<z.ZodEffects<z.ZodString, string, string>>;
     dataschema: z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>;
 }, "strip", z.ZodTypeAny, {
+    type: string;
     id: string;
     time: string;
     source: string;
     specversion: "1.0";
-    type: string;
     subject: string;
     datacontenttype: string;
     dataschema: string | null;
 }, {
+    type: string;
     id: string;
     time: string;
     source: string;
     specversion: string;
-    type: string;
     subject: string;
     dataschema: string | null;
     datacontenttype?: string | undefined;

package/dist/ArvoEventFactory/helpers.d.ts

@@ -1,15 +1,45 @@
 import ArvoEventFactory from '.';
 import ArvoContract from '../ArvoContract';
-import { z } from 'zod';
+import { ArvoSemanticVersion } from '../types';
+import ArvoEvent from '../ArvoEvent';
 /**
- * Creates a ArvoEventFactory instance based on the provided contract.
+ * Creates an ArvoEventFactory instance for a given contract.
+ * This is the recommended way to instantiate an ArvoEventFactory.
  *
- * @template TUri - The URI of the contract
- * @template TType - The accept type, defaults to string.
- * @template TAcceptSchema - The type of the data which the contract bound can accept
- * @template TEmits - The type of records the contract bound handler emits.
+ * @template TContract - The type of ArvoContract to create a factory for
  *
- * @param contract - The ArvoContract to base the events on.
- * @returns An instance of ContractualArvoEventFactory.
+ * @param contract - The ArvoContract instance to base the factory on
+ * @returns A new ArvoEventFactory instance bound to the provided contract
+ *
+ * @example
+ * ```typescript
+ * const contract = createArvoContract({...});
+ * const factory = createArvoEventFactory(contract);
+ * ```
+ */
+export declare const createArvoEventFactory: <TContract extends ArvoContract>(contract: TContract) => ArvoEventFactory<TContract>;
+/**
+ * Parses an event data schema string or ArvoEvent object to extract the URI and version.
+ * The schema is expected to be in the format "uri/version" where version follows semantic versioning.
+ *
+ * @param data - The input to parse, either a string containing the schema or an ArvoEvent object
+ *               If an ArvoEvent is provided, its dataschema property will be used
+ *
+ * @returns An object containing the parsed URI and semantic version, or null if parsing fails
+ *          The URI is everything before the last "/" and the version is everything after
+ *
+ * @example
+ * // String input
+ * parseEventDataSchema("com.example/schema/1.0.0")
+ * // Returns: { uri: "com.example/schema", version: "1.0.0" }
+ *
+ * // ArvoEvent input
+ * parseEventDataSchema({ dataschema: "com.example/schema/1.0.0" })
+ * // Returns: { uri: "com.example/schema", version: "1.0.0" }
+ *
+ * @throws Will not throw errors directly, but converts any parsing errors to spans
  */
-export declare const createArvoEventFactory: <TUri extends string = string, TType extends string = string, TAcceptSchema extends z.ZodTypeAny = z.ZodTypeAny, TEmits extends Record<string, z.ZodTypeAny> = Record<string, z.ZodTypeAny>>(contract: ArvoContract<TUri, TType, TAcceptSchema, TEmits>) => ArvoEventFactory<TUri, TType, TAcceptSchema, TEmits>;
+export declare const parseEventDataSchema: (data: string | ArvoEvent) => {
+    uri: string;
+    version: ArvoSemanticVersion;
+} | null;

package/dist/ArvoEventFactory/helpers.js

@@ -3,18 +3,60 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createArvoEventFactory = void 0;
+exports.parseEventDataSchema = exports.createArvoEventFactory = void 0;
 var _1 = __importDefault(require("."));
+var OpenTelemetry_1 = require("../OpenTelemetry");
+var schema_1 = require("../schema");
 /**
- * Creates a ArvoEventFactory instance based on the provided contract.
+ * Creates an ArvoEventFactory instance for a given contract.
+ * This is the recommended way to instantiate an ArvoEventFactory.
  *
- * @template TUri - The URI of the contract
- * @template TType - The accept type, defaults to string.
- * @template TAcceptSchema - The type of the data which the contract bound can accept
- * @template TEmits - The type of records the contract bound handler emits.
+ * @template TContract - The type of ArvoContract to create a factory for
  *
- * @param contract - The ArvoContract to base the events on.
- * @returns An instance of ContractualArvoEventFactory.
+ * @param contract - The ArvoContract instance to base the factory on
+ * @returns A new ArvoEventFactory instance bound to the provided contract
+ *
+ * @example
+ * ```typescript
+ * const contract = createArvoContract({...});
+ * const factory = createArvoEventFactory(contract);
+ * ```
  */
 var createArvoEventFactory = function (contract) { return new _1.default(contract); };
 exports.createArvoEventFactory = createArvoEventFactory;
+/**
+ * Parses an event data schema string or ArvoEvent object to extract the URI and version.
+ * The schema is expected to be in the format "uri/version" where version follows semantic versioning.
+ *
+ * @param data - The input to parse, either a string containing the schema or an ArvoEvent object
+ *               If an ArvoEvent is provided, its dataschema property will be used
+ *
+ * @returns An object containing the parsed URI and semantic version, or null if parsing fails
+ *          The URI is everything before the last "/" and the version is everything after
+ *
+ * @example
+ * // String input
+ * parseEventDataSchema("com.example/schema/1.0.0")
+ * // Returns: { uri: "com.example/schema", version: "1.0.0" }
+ *
+ * // ArvoEvent input
+ * parseEventDataSchema({ dataschema: "com.example/schema/1.0.0" })
+ * // Returns: { uri: "com.example/schema", version: "1.0.0" }
+ *
+ * @throws Will not throw errors directly, but converts any parsing errors to spans
+ */
+var parseEventDataSchema = function (data) {
+    var _a;
+    try {
+        var dataschema = typeof data === 'string' ? data : ((_a = data.dataschema) !== null && _a !== void 0 ? _a : '');
+        var items = dataschema.split('/');
+        var version = schema_1.ArvoSemanticVersionSchema.parse(items.pop());
+        var uri = items.join('/');
+        return { uri: uri, version: version };
+    }
+    catch (e) {
+        (0, OpenTelemetry_1.exceptionToSpan)(e);
+        return null;
+    }
+};
+exports.parseEventDataSchema = parseEventDataSchema;

package/dist/ArvoEventFactory/index.d.ts

@@ -2,53 +2,80 @@ import ArvoContract from '../ArvoContract';
 import { z } from 'zod';
 import { CreateArvoEvent } from '../ArvoEvent/types';
 import { ExecutionOpenTelemetryConfiguration } from '../OpenTelemetry/types';
+import { ArvoSemanticVersion } from '../types';
 /**
- * A factory class for creating contractual ArvoEvents based on a given ArvoContract.
+ * Factory class for creating contractual ArvoEvents based on a given ArvoContract.
+ * This class handles the creation and validation of events according to contract specifications.
  *
- * @template TUri - The URI of the contract
- * @template TType - The accept type, defaults to string.
- * @template TAcceptSchema - The type of the data which the contract bound can accept
- * @template TEmits - The type of records the contract bound handler emits.
+ * @template TContract - The type of ArvoContract this factory is bound to
  */
-export default class ArvoEventFactory<TUri extends string = string, TType extends string = string, TAcceptSchema extends z.ZodTypeAny = z.ZodTypeAny, TEmits extends Record<string, z.ZodTypeAny> = Record<string, z.ZodTypeAny>> {
+export default class ArvoEventFactory<TContract extends ArvoContract> {
     private readonly contract;
     /**
      * Creates an instance of ArvoEventFactory.
      *
      * @param contract - The ArvoContract to base the events on.
      */
-    constructor(contract: ArvoContract<TUri, TType, TAcceptSchema, TEmits>);
+    constructor(contract: TContract);
     /**
-     * Creates an ArvoEvent as per the accept record of the contract.
-     *
-     * @template TExtension - The type of extensions to add to the event.
-     * @param event - The event to create. The field 'type' is automatically infered
-     * @param [extensions] - Optional extensions to add to the event.
-     * @param [opentelemetry] - Optional opentelemetry configuration object
-     * @returns The created ArvoEvent as per the accept record of the contract.
-     * @throws If the event data fails validation against the contract.
+     * Creates a validated ArvoEvent that matches the contract's accept specifications.
+     * This method ensures the created event conforms to the contract's input schema.
+     *
+     * @template V - The semantic version of the contract to use
+     * @template TExtension - Additional custom properties to include in the event
+     *
+     * @param event - The event configuration object
+     * @param event.version - The semantic version of the contract to use
+     * @param event.data - The event payload that must conform to the contract's accept schema
+     * @param [extensions] - Optional additional properties to include in the event
+     * @param [opentelemetry] - Optional OpenTelemetry configuration for tracing
+     *
+     * @returns A validated ArvoEvent instance conforming to the contract's accept specifications
+     *
+     * @throws {Error} If event data validation fails against the contract schema
+     * @throws {Error} If OpenTelemetry operations fail
      */
-    accepts<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<z.input<TAcceptSchema>, TType>, 'type' | 'datacontenttype' | 'dataschema'>, extensions?: TExtension, opentelemetry?: ExecutionOpenTelemetryConfiguration): import("..").ArvoEvent<z.TypeOf<TAcceptSchema>, TExtension, TType>;
+    accepts<V extends ArvoSemanticVersion & keyof TContract['versions'], TExtension extends Record<string, any>>(event: {
+        version: V;
+    } & Omit<CreateArvoEvent<z.input<TContract['versions'][V]['accepts']>, TContract['type']>, 'type' | 'datacontenttype' | 'dataschema'>, extensions?: TExtension, opentelemetry?: ExecutionOpenTelemetryConfiguration): import("..").ArvoEvent<z.TypeOf<TContract["versions"][V]["accepts"]>, TExtension, TContract["type"]>;
     /**
-     * Creates an ArvoEvent as per one of the emits record in the contract.
-     *
-     * @template U - The specific event type from TEmits.
-     * @template TExtension - The type of extensions to add to the event.
-     * @param event - The event to create.
-     * @param [extensions] - Optional extensions to add to the event.
-     * @param [opentelemetry] - Optional opentelemetry configuration object
-     * @returns The created ArvoEvent as per one of the emits records of the contract.
-     * @throws If the event data fails validation against the contract.
+     * Creates a validated ArvoEvent that matches one of the contract's emit specifications.
+     * This method ensures the created event conforms to the contract's output schema.
+     *
+     * @template V - The semantic version of the contract to use
+     * @template U - The specific emit event type from the contract
+     * @template TExtension - Additional custom properties to include in the event
+     *
+     * @param event - The event configuration object
+     * @param event.version - The semantic version of the contract to use
+     * @param event.type - The type of emit event to create
+     * @param event.data - The event payload that must conform to the contract's emit schema
+     * @param [extensions] - Optional additional properties to include in the event
+     * @param [opentelemetry] - Optional OpenTelemetry configuration for tracing
+     *
+     * @returns A validated ArvoEvent instance conforming to the contract's emit specifications
+     *
+     * @throws {Error} If event data validation fails against the contract schema
+     * @throws {Error} If the specified emit type doesn't exist in the contract
+     * @throws {Error} If OpenTelemetry operations fail
      */
-    emits<U extends keyof TEmits & string, TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<z.input<TEmits[U]>, U>, 'datacontenttype' | 'dataschema'>, extensions?: TExtension, opentelemetry?: ExecutionOpenTelemetryConfiguration): import("..").ArvoEvent<z.TypeOf<TEmits[U]>, TExtension, U>;
+    emits<V extends ArvoSemanticVersion & keyof TContract['versions'], U extends string & keyof TContract['versions'][V]['emits'], TExtension extends Record<string, any>>(event: {
+        version: V;
+    } & Omit<CreateArvoEvent<z.input<TContract['versions'][V]['emits'][U]>, U>, 'datacontenttype' | 'dataschema'>, extensions?: TExtension, opentelemetry?: ExecutionOpenTelemetryConfiguration): import("..").ArvoEvent<z.TypeOf<TContract["versions"][V]["emits"][U]>, TExtension, U>;
     /**
-     * Creates a system error ArvoEvent.
+     * Creates a system error ArvoEvent for handling and reporting errors within the system.
+     *
+     * @template TExtension - Additional custom properties to include in the error event
+     *
+     * @param event - The error event configuration object
+     * @param event.error - The Error instance to be converted into an event
+     * @param [extensions] - Optional additional properties to include in the event
+     * @param [opentelemetry] - Optional OpenTelemetry configuration for tracing
+     *
+     * @returns A system error ArvoEvent containing the error details
      *
-     * @template TExtension - The type of extensions to add to the event.
-     * @param event - The event to create, including the error.
-     * @param [extensions] - Optional extensions to add to the event.
-     * @param [opentelemetry] - Optional opentelemtry configuration object
-     * @returns The created system error ArvoEvent.
+     * @throws {Error} If event creation fails
+     * @throws {Error} If OpenTelemetry operations fail
      */
     systemError<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<any, any>, 'data' | 'type' | 'datacontenttype' | 'dataschema'> & {
         error: Error;
@@ -56,5 +83,5 @@ export default class ArvoEventFactory<TUri extends string = string, TType extend
         errorMessage: string;
         errorName: string;
         errorStack: string | null;
-    }, TExtension, `sys.${TType}.error`>;
+    }, TExtension, `sys.${TContract["type"]}.error`>;
 }