arvo-core 2.0.3 → 2.0.5

package/dist/ArvoContract/VersionedArvoContract.d.ts

@@ -0,0 +1,39 @@
+import ArvoContract from '.';
+import { ArvoErrorSchema } from '../schema';
+import { ArvoSemanticVersion } from '../types';
+/**
+ * Represents a version-specific view of an ArvoContract, providing a structured way to access
+ * all contract specifications for a particular semantic version. This type ensures type-safe
+ * access to version-specific schemas and event types.
+ *
+ * @template TContract - The base ArvoContract type to extract version-specific information from
+ * @template TVersion - The specific semantic version of the contract to extract
+ *
+ * @property uri - The URI identifying the contract
+ * @property version - The specific semantic version being represented
+ * @property description - Optional description of the contract version
+ * @property accepts - Specification for accepted events in this version
+ * @property accepts.type - The event type this version accepts
+ * @property accepts.schema - Zod schema for validating accepted events
+ * @property systemError - System error event specification
+ * @property systemError.type - System error event type (sys.[type].error)
+ * @property systemError.schema - Zod schema for system error events
+ * @property emits - Record of emittable event types and their Zod schemas
+ *
+ * @see {@link ArvoContract} for the base contract class
+ * @see {@link ArvoContract.version} for the method to create a versioned view
+ */
+export type VersionedArvoContract<TContract extends ArvoContract, TVersion extends ArvoSemanticVersion & keyof TContract['versions']> = {
+    uri: TContract['uri'];
+    version: TVersion;
+    description: string | null;
+    accepts: {
+        type: TContract['type'];
+        schema: TContract['versions'][TVersion]['accepts'];
+    };
+    systemError: {
+        type: `sys.${TContract['type']}.error`;
+        schema: typeof ArvoErrorSchema;
+    };
+    emits: TContract['versions'][TVersion]['emits'];
+};

package/dist/ArvoContract/VersionedArvoContract.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/ArvoContract/index.d.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { ArvoContractJSONSchema, ArvoContractRecord, IArvoContract } from './types';
 import { ArvoErrorSchema } from '../schema';
 import { ArvoSemanticVersion } from '../types';
+import { VersionedArvoContract } from './VersionedArvoContract';
 /**
  * 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.
@@ -32,6 +33,21 @@ export default class ArvoContract<TUri extends string = string, TType extends st
      * Gets the URI of the contract.
      */
     get uri(): TUri;
+    /**
+     * Creates a version-specific view of the contract, providing easy access to all
+     * schemas and specifications for a particular semantic version.
+     *
+     * @template V - The semantic version to create a view for, must be a valid version in the contract
+     *
+     * @param ver - The semantic version string (e.g., "1.0.0")
+     * @returns A VersionedArvoContract instance containing all specifications for the requested version
+     *
+     * The returned object provides a simpler, flatter structure compared to
+     * accessing version-specific information through the main contract methods.
+     *
+     * @see {@link VersionedArvoContract} for the structure of the returned object
+     */
+    version<V extends ArvoSemanticVersion & keyof TVersions>(ver: V): VersionedArvoContract<typeof this, V>;
     /**
      * Get the type of the event the handler
      * bound to the contract accepts
@@ -55,6 +71,25 @@ export default class ArvoContract<TUri extends string = string, TType extends st
      * contract bound handler.
      */
     emits<V extends ArvoSemanticVersion & keyof TVersions>(version: V): TVersions[V]['emits'];
+    /**
+     * Gets the system error event specification for this contract.
+     * System errors follow a standardized format to handle exceptional conditions
+     * and failures in a consistent way across all contracts.
+     *
+     * The error schema includes:
+     *   - errorName: The name/type of the error
+     *   - errorMessage: A descriptive message about what went wrong
+     *   - errorStack: Optional stack trace information (null if not available)
+     *
+     * System errors are special events that:
+     * - Are automatically prefixed with 'sys.' and suffixed with '.error'
+     * - Use a standardized schema across all contracts
+     * - Can capture error details, messages, and stack traces
+     * - Are version-independent (work the same across all contract versions)
+     *
+     * @see {@link ArvoErrorSchema} for the detailed error schema definition
+     * @see {@link ArvoContractRecord} for the structure of the returned record
+     */
     get systemError(): ArvoContractRecord<`sys.${TType}.error`, typeof ArvoErrorSchema>;
     /**
      * Validates the contract bound handler's input/ accept event against the
@@ -90,11 +125,7 @@ export default class ArvoContract<TUri extends string = string, TType extends st
      * This method provides a way to represent the contract's structure and validation rules
      * in a format that conforms to the JSON Schema specification.
      *
-     * @returns An object representing the contract in JSON Schema format, including:
-     *   - uri: The contract's URI
-     *   - description: The contract's description (if available)
-     *   - accepts: An object containing the accepted input type and its JSON Schema representation
-     *   - emits: An array of objects, each containing an emitted event type and its JSON Schema representation
+     * @returns An object representing the contract in JSON Schema format:
      */
     toJsonSchema(): ArvoContractJSONSchema;
 }

package/dist/ArvoContract/index.js

@@ -46,6 +46,33 @@ var ArvoContract = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
+    /**
+     * Creates a version-specific view of the contract, providing easy access to all
+     * schemas and specifications for a particular semantic version.
+     *
+     * @template V - The semantic version to create a view for, must be a valid version in the contract
+     *
+     * @param ver - The semantic version string (e.g., "1.0.0")
+     * @returns A VersionedArvoContract instance containing all specifications for the requested version
+     *
+     * The returned object provides a simpler, flatter structure compared to
+     * accessing version-specific information through the main contract methods.
+     *
+     * @see {@link VersionedArvoContract} for the structure of the returned object
+     */
+    ArvoContract.prototype.version = function (ver) {
+        return {
+            uri: this._uri,
+            description: this.description,
+            version: ver,
+            accepts: {
+                type: this._type,
+                schema: this._versions[ver].accepts,
+            },
+            systemError: this.systemError,
+            emits: this._versions[ver].emits,
+        };
+    };
     Object.defineProperty(ArvoContract.prototype, "type", {
         /**
          * Get the type of the event the handler
@@ -97,6 +124,25 @@ var ArvoContract = /** @class */ (function () {
         return __assign({}, this._versions[version].emits);
     };
     Object.defineProperty(ArvoContract.prototype, "systemError", {
+        /**
+         * Gets the system error event specification for this contract.
+         * System errors follow a standardized format to handle exceptional conditions
+         * and failures in a consistent way across all contracts.
+         *
+         * The error schema includes:
+         *   - errorName: The name/type of the error
+         *   - errorMessage: A descriptive message about what went wrong
+         *   - errorStack: Optional stack trace information (null if not available)
+         *
+         * System errors are special events that:
+         * - Are automatically prefixed with 'sys.' and suffixed with '.error'
+         * - Use a standardized schema across all contracts
+         * - Can capture error details, messages, and stack traces
+         * - Are version-independent (work the same across all contract versions)
+         *
+         * @see {@link ArvoErrorSchema} for the detailed error schema definition
+         * @see {@link ArvoContractRecord} for the structure of the returned record
+         */
         get: function () {
             return {
                 type: "sys.".concat(this._type, ".error"),
@@ -159,11 +205,7 @@ var ArvoContract = /** @class */ (function () {
      * This method provides a way to represent the contract's structure and validation rules
      * in a format that conforms to the JSON Schema specification.
      *
-     * @returns An object representing the contract in JSON Schema format, including:
-     *   - uri: The contract's URI
-     *   - description: The contract's description (if available)
-     *   - accepts: An object containing the accepted input type and its JSON Schema representation
-     *   - emits: An array of objects, each containing an emitted event type and its JSON Schema representation
+     * @returns An object representing the contract in JSON Schema format:
      */
     ArvoContract.prototype.toJsonSchema = function () {
         var _this = this;
@@ -178,6 +220,10 @@ var ArvoContract = /** @class */ (function () {
                         type: _this._type,
                         schema: (0, zod_to_json_schema_1.zodToJsonSchema)(contract.accepts),
                     },
+                    systemError: {
+                        type: _this.systemError.type,
+                        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];
                         return ({

package/dist/ArvoContract/types.d.ts

@@ -62,6 +62,13 @@ export type ArvoContractJSONSchema = {
             /** JSON Schema representation of the input validation schema */
             schema: ReturnType<typeof zodToJsonSchema>;
         };
+        /** The system error event */
+        systemError: {
+            /** The type of the event */
+            type: string;
+            /** The schema of the error */
+            schema: ReturnType<typeof zodToJsonSchema>;
+        };
         /** Array of schemas for events that can be emitted in this version */
         emits: {
             /** The type identifier for the emitted event */

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/index.d.ts

@@ -21,10 +21,11 @@ import { ArvoOrchestrationSubjectContentSchema } from './ArvoOrchestrationSubjec
 import { ArvoOrchestrationSubjectContent } from './ArvoOrchestrationSubject/type';
 import ArvoEventHttp from './ArvoEventHttp';
 import { ArvoEventHttpConfig } from './ArvoEventHttp/types';
-import { InferArvoContract, InferArvoEvent, ArvoSemanticVersion, ArvoErrorType } from './types';
+import { InferArvoContract, InferArvoEvent, ArvoSemanticVersion, ArvoErrorType, InferVersionedArvoContract } from './types';
 import { createArvoOrchestratorContract } from './ArvoOrchestratorContract';
 import { ICreateArvoOrchestratorContract, ArvoOrchestratorContract } from './ArvoOrchestratorContract/types';
 import { ArvoOrchestratorEventTypeGen } from './ArvoOrchestratorContract/typegen';
+import { VersionedArvoContract } from './ArvoContract/VersionedArvoContract';
 /**
  * Collection of Zod schemas for validating various aspects of Arvo events.
  * @property {z.ZodObject} CloudEventContextSchema - Schema for core CloudEvent properties.
@@ -99,4 +100,4 @@ declare const ArvoEventSchema: {
         parentSubject$$: string | null;
     }>;
 };
-export { ArvoEventHttpConfig, ArvoEventHttp, ArvoEvent, createArvoEvent, ArvoDataContentType, ArvoEventData, CloudEventExtension, ArvoEventSchema, CloudEventContext, ArvoExtension, OpenTelemetryExtension, CreateArvoEvent, exceptionToSpan, logToSpan, OpenTelemetryHeaders, TelemetryLogLevel, OTelNull, validateURI, cleanString, ArvoContract, createArvoContract, ArvoContractValidators, ArvoContractRecord, IArvoContract, ResolveArvoContractRecord, ArvoEventFactory, createArvoEventFactory, currentOpenTelemetryHeaders, OpenInference, OpenInferenceSpanKind, ArvoExecution, ArvoExecutionSpanKind, ArvoContractJSONSchema, ArvoOrchestrationSubject, ArvoOrchestrationSubjectContent, ArvoSemanticVersion, InferArvoEvent, InferArvoContract, createArvoOrchestratorContract, ICreateArvoOrchestratorContract, ArvoOrchestratorEventTypeGen, ExecutionOpenTelemetryConfiguration, parseEventDataSchema, ArvoOrchestrationSubjectContentSchema, ArvoSemanticVersionSchema, ArvoErrorSchema, ArvoErrorType, compareSemanticVersions, parseSemanticVersion, createSimpleArvoContract, ArvoOrchestratorContract, };
+export { ArvoEventHttpConfig, ArvoEventHttp, ArvoEvent, createArvoEvent, ArvoDataContentType, ArvoEventData, CloudEventExtension, ArvoEventSchema, CloudEventContext, ArvoExtension, OpenTelemetryExtension, CreateArvoEvent, exceptionToSpan, logToSpan, OpenTelemetryHeaders, TelemetryLogLevel, OTelNull, validateURI, cleanString, ArvoContract, createArvoContract, ArvoContractValidators, ArvoContractRecord, IArvoContract, ResolveArvoContractRecord, ArvoEventFactory, createArvoEventFactory, currentOpenTelemetryHeaders, OpenInference, OpenInferenceSpanKind, ArvoExecution, ArvoExecutionSpanKind, ArvoContractJSONSchema, ArvoOrchestrationSubject, ArvoOrchestrationSubjectContent, ArvoSemanticVersion, InferArvoEvent, InferArvoContract, createArvoOrchestratorContract, ICreateArvoOrchestratorContract, ArvoOrchestratorEventTypeGen, ExecutionOpenTelemetryConfiguration, parseEventDataSchema, ArvoOrchestrationSubjectContentSchema, ArvoSemanticVersionSchema, ArvoErrorSchema, ArvoErrorType, compareSemanticVersions, parseSemanticVersion, createSimpleArvoContract, ArvoOrchestratorContract, VersionedArvoContract, InferVersionedArvoContract, };

package/dist/types.d.ts

@@ -3,6 +3,7 @@ import ArvoContract from './ArvoContract';
 import ArvoEvent from './ArvoEvent';
 import { ArvoExtension, OpenTelemetryExtension } from './ArvoEvent/types';
 import { ArvoErrorSchema } from './schema';
+import { VersionedArvoContract } from './ArvoContract/VersionedArvoContract';
 /**
  * Represents the version of Arvo components following Semantic Versioning (SemVer).
  *
@@ -151,5 +152,60 @@ 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']>>;
+    emits: {
+        [K in string & keyof TVersion['emits']]: InferArvoEvent<ArvoEvent<InferZodSchema<TVersion['emits'][K]>, {}, K>>;
+    };
+};
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arvo-core",
-  "version": "2.0.3",
+  "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": {