arvo-core 2.0.4 → 2.0.5

package/dist/ArvoContract/index.js

@@ -222,7 +222,7 @@ var ArvoContract = /** @class */ (function () {
                     },
                     systemError: {
                         type: _this.systemError.type,
-                        schema: (0, zod_to_json_schema_1.zodToJsonSchema)(_this.systemError.schema)
+                        schema: (0, zod_to_json_schema_1.zodToJsonSchema)(_this.systemError.schema),
                     },
                     emits: Object.entries(contract.emits).map(function (_a) {
                         var key = _a[0], value = _a[1];

package/dist/ArvoEventFactory/helpers.d.ts

@@ -2,22 +2,23 @@ import ArvoEventFactory from '.';
 import ArvoContract from '../ArvoContract';
 import { ArvoSemanticVersion } from '../types';
 import ArvoEvent from '../ArvoEvent';
+import { VersionedArvoContract } from '../ArvoContract/VersionedArvoContract';
 /**
- * Creates an ArvoEventFactory instance for a given contract.
- * This is the recommended way to instantiate an ArvoEventFactory.
+ * Creates an ArvoEventFactory for a specific version of a contract.
  *
- * @template TContract - The type of ArvoContract to create a factory for
+ * @template TContract - The versioned contract type
  *
- * @param contract - The ArvoContract instance to base the factory on
- * @returns A new ArvoEventFactory instance bound to the provided contract
+ * @param contract - The versioned contract to create a factory for
+ * @returns An ArvoEventFactory instance for the specified contract version
  *
  * @example
  * ```typescript
  * const contract = createArvoContract({...});
- * const factory = createArvoEventFactory(contract);
+ * const v1Contract = contract.version('1.0.0');
+ * const factory = createArvoEventFactory(v1Contract);
  * ```
  */
-export declare const createArvoEventFactory: <TContract extends ArvoContract>(contract: TContract) => ArvoEventFactory<TContract>;
+export declare const createArvoEventFactory: <TContract extends VersionedArvoContract<ArvoContract, ArvoSemanticVersion>>(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.

package/dist/ArvoEventFactory/helpers.js

@@ -8,18 +8,18 @@ var _1 = __importDefault(require("."));
 var OpenTelemetry_1 = require("../OpenTelemetry");
 var schema_1 = require("../schema");
 /**
- * Creates an ArvoEventFactory instance for a given contract.
- * This is the recommended way to instantiate an ArvoEventFactory.
+ * Creates an ArvoEventFactory for a specific version of a contract.
  *
- * @template TContract - The type of ArvoContract to create a factory for
+ * @template TContract - The versioned contract type
  *
- * @param contract - The ArvoContract instance to base the factory on
- * @returns A new ArvoEventFactory instance bound to the provided contract
+ * @param contract - The versioned contract to create a factory for
+ * @returns An ArvoEventFactory instance for the specified contract version
  *
  * @example
  * ```typescript
  * const contract = createArvoContract({...});
- * const factory = createArvoEventFactory(contract);
+ * const v1Contract = contract.version('1.0.0');
+ * const factory = createArvoEventFactory(v1Contract);
  * ```
  */
 var createArvoEventFactory = function (contract) { return new _1.default(contract); };

package/dist/ArvoEventFactory/index.d.ts

@@ -3,79 +3,100 @@ import { z } from 'zod';
 import { CreateArvoEvent } from '../ArvoEvent/types';
 import { ExecutionOpenTelemetryConfiguration } from '../OpenTelemetry/types';
 import { ArvoSemanticVersion } from '../types';
+import { VersionedArvoContract } from '../ArvoContract/VersionedArvoContract';
 /**
- * Factory class for creating contractual ArvoEvents based on a given ArvoContract.
- * This class handles the creation and validation of events according to contract specifications.
+ * Factory class for creating and validating events based on a versioned Arvo contract.
+ * Handles event creation, validation, and OpenTelemetry integration for a specific
+ * contract version.
  *
- * @template TContract - The type of ArvoContract this factory is bound to
+ * @template TContract - The versioned contract type this factory is bound to
+ *
+ * @example
+ * ```typescript
+ * const contract = createArvoContract({
+ *   uri: 'example/api',
+ *   type: 'user.create',
+ *   versions: { '1.0.0': { ... } }
+ * });
+ *
+ * const factory = createArvoEventFactory(contract.version('1.0.0'));
+ * ```
  */
-export default class ArvoEventFactory<TContract extends ArvoContract> {
+export default class ArvoEventFactory<TContract extends VersionedArvoContract<ArvoContract, ArvoSemanticVersion>> {
     private readonly contract;
     /**
-     * Creates an instance of ArvoEventFactory.
+     * Creates an ArvoEventFactory instance for a specific version of a contract.
      *
-     * @param contract - The ArvoContract to base the events on.
+     * @param contract - The versioned contract to use for event creation and validation
      */
     constructor(contract: TContract);
     /**
-     * Creates a validated ArvoEvent that matches the contract's accept specifications.
-     * This method ensures the created event conforms to the contract's input schema.
+     * Creates and validates an event matching the contract's accept specification.
      *
-     * @template V - The semantic version of the contract to use
-     * @template TExtension - Additional custom properties to include in the event
+     * @template TExtension - Additional 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
+     * @param [extensions] - Optional additional properties for the event
+     * @param [opentelemetry] - Optional OpenTelemetry configuration
+     *
+     * @returns A validated ArvoEvent matching the contract's accept specification
      *
-     * @returns A validated ArvoEvent instance conforming to the contract's accept specifications
+     * @throws {Error} If validation fails or OpenTelemetry operations fail
      *
-     * @throws {Error} If event data validation fails against the contract schema
-     * @throws {Error} If OpenTelemetry operations fail
+     * @example
+     * ```typescript
+     * const event = factory.accepts({
+     *   source: 'api/users',
+     *   data: { name: 'John', email: 'john@example.com' }
+     * });
+     * ```
      */
-    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"]>;
+    accepts<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<z.input<TContract['accepts']['schema']>, TContract['accepts']['type']>, 'type' | 'datacontenttype' | 'dataschema'>, extensions?: TExtension, opentelemetry?: ExecutionOpenTelemetryConfiguration): import("..").ArvoEvent<z.TypeOf<TContract["accepts"]["schema"]>, TExtension, TContract["accepts"]["type"]>;
     /**
-     * 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.
+     * Creates and validates an event matching one of the contract's emit specifications.
      *
-     * @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
+     * @template TExtension - Additional 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
+     * @param [extensions] - Optional additional properties for the event
+     * @param [opentelemetry] - Optional OpenTelemetry configuration
      *
-     * @returns A validated ArvoEvent instance conforming to the contract's emit specifications
+     * @returns A validated ArvoEvent matching the specified emit type
      *
-     * @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
+     * @throws {Error} If validation fails, emit type doesn't exist, or OpenTelemetry operations fail
+     *
+     * @example
+     * ```typescript
+     * const event = factory.emits({
+     *   type: 'user.created',
+     *   source: 'api/users',
+     *   data: { id: '123', timestamp: new Date() }
+     * });
+     * ```
      */
-    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>;
+    emits<U extends string & keyof TContract['emits'], TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<z.input<TContract['emits'][U]>, U>, 'datacontenttype' | 'dataschema'>, extensions?: TExtension, opentelemetry?: ExecutionOpenTelemetryConfiguration): import("..").ArvoEvent<z.TypeOf<TContract["emits"][U]>, TExtension, U>;
     /**
-     * Creates a system error ArvoEvent for handling and reporting errors within the system.
+     * Creates a system error event for error reporting and handling.
+     *
+     * @template TExtension - Additional properties to include in the error event
      *
-     * @template TExtension - Additional custom properties to include in the error event
+     * @param event - The error event configuration
+     * @param event.error - The Error instance to convert to an event
+     * @param [extensions] - Optional additional properties for the event
+     * @param [opentelemetry] - Optional OpenTelemetry configuration
      *
-     * @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
      *
-     * @returns A system error ArvoEvent containing the error details
+     * @throws {Error} If event creation or OpenTelemetry operations fail
      *
-     * @throws {Error} If event creation fails
-     * @throws {Error} If OpenTelemetry operations fail
+     * @example
+     * ```typescript
+     * const errorEvent = factory.systemError({
+     *   error: new Error('Validation failed'),
+     *   source: 'api/validation'
+     * });
+     * ```
      */
     systemError<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<any, any>, 'data' | 'type' | 'datacontenttype' | 'dataschema'> & {
         error: Error;
@@ -83,5 +104,5 @@ export default class ArvoEventFactory<TContract extends ArvoContract> {
         errorMessage: string;
         errorName: string;
         errorStack: string | null;
-    }, TExtension, `sys.${TContract["type"]}.error`>;
+    }, TExtension, TContract["systemError"]["type"]>;
 }

package/dist/ArvoEventFactory/index.js

@@ -31,54 +31,69 @@ var OpenTelemetry_1 = require("../OpenTelemetry");
 var api_1 = require("@opentelemetry/api");
 var ArvoOrchestrationSubject_1 = __importDefault(require("../ArvoOrchestrationSubject"));
 /**
- * Factory class for creating contractual ArvoEvents based on a given ArvoContract.
- * This class handles the creation and validation of events according to contract specifications.
+ * Factory class for creating and validating events based on a versioned Arvo contract.
+ * Handles event creation, validation, and OpenTelemetry integration for a specific
+ * contract version.
  *
- * @template TContract - The type of ArvoContract this factory is bound to
+ * @template TContract - The versioned contract type this factory is bound to
+ *
+ * @example
+ * ```typescript
+ * const contract = createArvoContract({
+ *   uri: 'example/api',
+ *   type: 'user.create',
+ *   versions: { '1.0.0': { ... } }
+ * });
+ *
+ * const factory = createArvoEventFactory(contract.version('1.0.0'));
+ * ```
  */
 var ArvoEventFactory = /** @class */ (function () {
     /**
-     * Creates an instance of ArvoEventFactory.
+     * Creates an ArvoEventFactory instance for a specific version of a contract.
      *
-     * @param contract - The ArvoContract to base the events on.
+     * @param contract - The versioned contract to use for event creation and validation
      */
     function ArvoEventFactory(contract) {
         this.contract = 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.
+     * Creates and validates an event matching the contract's accept specification.
      *
-     * @template V - The semantic version of the contract to use
-     * @template TExtension - Additional custom properties to include in the event
+     * @template TExtension - Additional 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
+     * @param [extensions] - Optional additional properties for the event
+     * @param [opentelemetry] - Optional OpenTelemetry configuration
      *
-     * @returns A validated ArvoEvent instance conforming to the contract's accept specifications
+     * @returns A validated ArvoEvent matching the contract's accept specification
      *
-     * @throws {Error} If event data validation fails against the contract schema
-     * @throws {Error} If OpenTelemetry operations fail
+     * @throws {Error} If validation fails or OpenTelemetry operations fail
+     *
+     * @example
+     * ```typescript
+     * const event = factory.accepts({
+     *   source: 'api/users',
+     *   data: { name: 'John', email: 'john@example.com' }
+     * });
+     * ```
      */
     ArvoEventFactory.prototype.accepts = function (event, extensions, opentelemetry) {
         var _this = this;
         opentelemetry = opentelemetry !== null && opentelemetry !== void 0 ? opentelemetry : {
             tracer: (0, OpenTelemetry_1.fetchOpenTelemetryTracer)(),
         };
-        var span = opentelemetry.tracer.startSpan("ArvoEventFactory<".concat(this.contract.uri, "/").concat(event.version, ">.accepts"));
+        var span = opentelemetry.tracer.startSpan("ArvoEventFactory<".concat(this.contract.uri, "/").concat(this.contract.version, ">.accepts"));
         return api_1.context.with(api_1.trace.setSpan(api_1.context.active(), span), function () {
             var _a, _b, _c, _d;
             span.setStatus({ code: api_1.SpanStatusCode.OK });
             var otelHeaders = (0, OpenTelemetry_1.currentOpenTelemetryHeaders)();
             try {
-                var validationResult = _this.contract.validateAccepts(event.version, _this.contract.type, event.data);
+                var validationResult = _this.contract.accepts.schema.safeParse(event.data);
                 if (!validationResult.success) {
                     throw new Error("Accept Event data validation failed: ".concat(validationResult.error.message));
                 }
-                return (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { traceparent: (_b = (_a = event.traceparent) !== null && _a !== void 0 ? _a : otelHeaders.traceparent) !== null && _b !== void 0 ? _b : undefined, tracestate: (_d = (_c = event.tracestate) !== null && _c !== void 0 ? _c : otelHeaders.tracestate) !== null && _d !== void 0 ? _d : undefined, type: _this.contract.type, datacontenttype: schema_1.ArvoDataContentType, dataschema: "".concat(_this.contract.uri, "/").concat(event.version), data: validationResult.data }), extensions, opentelemetry);
+                return (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { traceparent: (_b = (_a = event.traceparent) !== null && _a !== void 0 ? _a : otelHeaders.traceparent) !== null && _b !== void 0 ? _b : undefined, tracestate: (_d = (_c = event.tracestate) !== null && _c !== void 0 ? _c : otelHeaders.tracestate) !== null && _d !== void 0 ? _d : undefined, type: _this.contract.accepts.type, datacontenttype: schema_1.ArvoDataContentType, dataschema: "".concat(_this.contract.uri, "/").concat(_this.contract.version), data: validationResult.data }), extensions, opentelemetry);
             }
             catch (error) {
                 (0, OpenTelemetry_1.exceptionToSpan)(error);
@@ -94,42 +109,44 @@ var ArvoEventFactory = /** @class */ (function () {
         });
     };
     /**
-     * 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.
+     * Creates and validates an event matching one of the contract's emit specifications.
      *
-     * @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
+     * @template TExtension - Additional 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
+     * @param [extensions] - Optional additional properties for the event
+     * @param [opentelemetry] - Optional OpenTelemetry configuration
+     *
+     * @returns A validated ArvoEvent matching the specified emit type
      *
-     * @returns A validated ArvoEvent instance conforming to the contract's emit specifications
+     * @throws {Error} If validation fails, emit type doesn't exist, or OpenTelemetry operations fail
      *
-     * @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
+     * @example
+     * ```typescript
+     * const event = factory.emits({
+     *   type: 'user.created',
+     *   source: 'api/users',
+     *   data: { id: '123', timestamp: new Date() }
+     * });
+     * ```
      */
     ArvoEventFactory.prototype.emits = function (event, extensions, opentelemetry) {
         var _this = this;
         opentelemetry = opentelemetry !== null && opentelemetry !== void 0 ? opentelemetry : {
             tracer: (0, OpenTelemetry_1.fetchOpenTelemetryTracer)(),
         };
-        var span = opentelemetry.tracer.startSpan("ArvoEventFactory<".concat(this.contract.uri, "/").concat(event.version, ">.emits<").concat(event.type, ">"));
+        var span = opentelemetry.tracer.startSpan("ArvoEventFactory<".concat(this.contract.uri, "/").concat(this.contract.version, ">.emits<").concat(event.type, ">"));
         return api_1.context.with(api_1.trace.setSpan(api_1.context.active(), span), function () {
-            var _a, _b, _c, _d;
+            var _a, _b, _c, _d, _e, _f, _g, _h;
             span.setStatus({ code: api_1.SpanStatusCode.OK });
             var otelHeaders = (0, OpenTelemetry_1.currentOpenTelemetryHeaders)();
             try {
-                var validationResult = _this.contract.validateEmits(event.version, event.type, event.data);
-                if (!validationResult.success) {
-                    throw new Error("Emit Event data validation failed: ".concat(validationResult.error.message));
+                var validationResult = (_b = (_a = _this.contract.emits) === null || _a === void 0 ? void 0 : _a[event.type]) === null || _b === void 0 ? void 0 : _b.safeParse(event.data);
+                if (!(validationResult === null || validationResult === void 0 ? void 0 : validationResult.success)) {
+                    throw new Error("Emit Event data validation failed: ".concat((_d = (_c = validationResult === null || validationResult === void 0 ? void 0 : validationResult.error) === null || _c === void 0 ? void 0 : _c.message) !== null && _d !== void 0 ? _d : "No contract available for ".concat(event.type)));
                 }
-                return (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { traceparent: (_b = (_a = event.traceparent) !== null && _a !== void 0 ? _a : otelHeaders.traceparent) !== null && _b !== void 0 ? _b : undefined, tracestate: (_d = (_c = event.tracestate) !== null && _c !== void 0 ? _c : otelHeaders.tracestate) !== null && _d !== void 0 ? _d : undefined, datacontenttype: schema_1.ArvoDataContentType, dataschema: "".concat(_this.contract.uri, "/").concat(event.version), data: validationResult.data }), extensions, opentelemetry);
+                return (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { traceparent: (_f = (_e = event.traceparent) !== null && _e !== void 0 ? _e : otelHeaders.traceparent) !== null && _f !== void 0 ? _f : undefined, tracestate: (_h = (_g = event.tracestate) !== null && _g !== void 0 ? _g : otelHeaders.tracestate) !== null && _h !== void 0 ? _h : undefined, datacontenttype: schema_1.ArvoDataContentType, dataschema: "".concat(_this.contract.uri, "/").concat(_this.contract.version), data: validationResult.data }), extensions, opentelemetry);
             }
             catch (error) {
                 (0, OpenTelemetry_1.exceptionToSpan)(error);
@@ -145,19 +162,26 @@ var ArvoEventFactory = /** @class */ (function () {
         });
     };
     /**
-     * Creates a system error ArvoEvent for handling and reporting errors within the system.
+     * Creates a system error event for error reporting and handling.
+     *
+     * @template TExtension - Additional properties to include in the error event
      *
-     * @template TExtension - Additional custom properties to include in the error event
+     * @param event - The error event configuration
+     * @param event.error - The Error instance to convert to an event
+     * @param [extensions] - Optional additional properties for the event
+     * @param [opentelemetry] - Optional OpenTelemetry configuration
      *
-     * @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
      *
-     * @returns A system error ArvoEvent containing the error details
+     * @throws {Error} If event creation or OpenTelemetry operations fail
      *
-     * @throws {Error} If event creation fails
-     * @throws {Error} If OpenTelemetry operations fail
+     * @example
+     * ```typescript
+     * const errorEvent = factory.systemError({
+     *   error: new Error('Validation failed'),
+     *   source: 'api/validation'
+     * });
+     * ```
      */
     ArvoEventFactory.prototype.systemError = function (event, extensions, opentelemetry) {
         var _this = this;
@@ -171,7 +195,7 @@ var ArvoEventFactory = /** @class */ (function () {
             var otelHeaders = (0, OpenTelemetry_1.currentOpenTelemetryHeaders)();
             try {
                 var error = event.error, _event = __rest(event, ["error"]);
-                return (0, helpers_1.createArvoEvent)(__assign(__assign({}, _event), { traceparent: (_b = (_a = event.traceparent) !== null && _a !== void 0 ? _a : otelHeaders.traceparent) !== null && _b !== void 0 ? _b : undefined, tracestate: (_d = (_c = event.tracestate) !== null && _c !== void 0 ? _c : otelHeaders.tracestate) !== null && _d !== void 0 ? _d : undefined, type: "sys.".concat(_this.contract.type, ".error"), data: {
+                return (0, helpers_1.createArvoEvent)(__assign(__assign({}, _event), { traceparent: (_b = (_a = event.traceparent) !== null && _a !== void 0 ? _a : otelHeaders.traceparent) !== null && _b !== void 0 ? _b : undefined, tracestate: (_d = (_c = event.tracestate) !== null && _c !== void 0 ? _c : otelHeaders.tracestate) !== null && _d !== void 0 ? _d : undefined, type: _this.contract.systemError.type, data: {
                         errorName: error.name,
                         errorMessage: error.message,
                         errorStack: (_e = error.stack) !== null && _e !== void 0 ? _e : null,

package/dist/types.d.ts

@@ -152,7 +152,55 @@ export type InferArvoContract<T extends ArvoContract<string, string, Record<Arvo
     };
     systemError: InferArvoEvent<ArvoEvent<InferZodSchema<T['systemError']['schema']>, {}, T['systemError']['type']>>;
 } : never;
+/**
+ * Represents the structure of an Arvo system error.
+ * This type is inferred from the ArvoErrorSchema and provides
+ * the standard error format used across all Arvo contracts.
+ *
+ * @property errorName - The classification or type of the error
+ * @property errorMessage - A human-readable description of what went wrong
+ * @property errorStack - Optional stack trace for debugging (null if not available)
+ *
+ * @example
+ * ```typescript
+ * const error: ArvoErrorType = {
+ *   errorName: 'ValidationError',
+ *   errorMessage: 'Invalid input format',
+ *   errorStack: 'Error: Invalid input format\n    at validate (/app.js:10)'
+ * };
+ * ```
+ *
+ * @see {@link ArvoErrorSchema} for the underlying Zod schema definition
+ */
 export type ArvoErrorType = z.infer<typeof ArvoErrorSchema>;
+/**
+ * A type utility that infers the complete event structure from a versioned Arvo contract.
+ * This type extracts and transforms all event types, schemas, and error definitions
+ * from a specific version of a contract into their fully resolved event forms.
+ *
+ * @template TVersion - The versioned contract to infer from, must extend VersionedArvoContract
+ *
+ * @property accepts - The fully resolved accept event type for this version
+ * @property systemError - The fully resolved system error event type
+ * @property emits - Record of all fully resolved emit event types
+ *
+ * This type utility:
+ * - Transforms Zod schemas into their inferred TypeScript types
+ * - Wraps all event types in the full ArvoEvent structure
+ * - Preserves all event type relationships and constraints
+ * - Includes OpenTelemetry and Arvo extensions
+ * - Maintains type safety across all transformations
+ *
+ * Common use cases:
+ * - Type-safe event handling in version-specific contexts
+ * - Generating TypeScript interfaces for API documentation
+ * - Validating event payload types at compile time
+ * - Creating type-safe event factories
+ *
+ * @see {@link VersionedArvoContract} for the input contract structure
+ * @see {@link InferArvoEvent} for the event inference utility
+ * @see {@link ArvoEvent} for the base event structure
+ */
 export type InferVersionedArvoContract<TVersion extends VersionedArvoContract<ArvoContract, ArvoSemanticVersion>> = {
     accepts: InferArvoEvent<ArvoEvent<InferZodSchema<TVersion['accepts']['schema']>, {}, TVersion['accepts']['type']>>;
     systemError: InferArvoEvent<ArvoEvent<InferZodSchema<TVersion['systemError']['schema']>, {}, TVersion['systemError']['type']>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arvo-core",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "This core package contains all the core classes and components of the Arvo Event Driven System",
   "main": "dist/index.js",
   "scripts": {