arvo-core 2.0.7 → 2.0.9

package/dist/ArvoContract/index.d.ts

@@ -4,14 +4,29 @@ 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.
- * An event handler can be bound to it so the this contract may impose the types
- * on inputs and outputs of it
+ * Represents a contract with defined input and output schemas for event-driven architectures.
+ * The ArvoContract class provides type-safe validation and versioning capabilities for event handling,
+ * ensuring consistency in message passing between different parts of the system.
  *
- * @template TUri - The URI of the contract
- * @template TType - The accept type, defaults to string.
- * @template TVersion - The contract versions
+ * @template TUri - The URI identifier for the contract, must be a string type
+ * @template TType - The accept type for the contract, must be a string type
+ * @template TVersions - Record of versioned schemas defining contract structure per version
+ *
+ * @example
+ * ```typescript
+ * const contract = createArvoContract({
+ *   uri: '#/my/service/data',
+ *   type: 'com.process.data',
+ *   versions: {
+ *     '1.0.0': {
+ *       accepts: z.object({ data: z.string() }),
+ *       emits: {
+ *         'data.processed': z.object({ result: z.string() })
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
  */
 export default class ArvoContract<TUri extends string = string, TType extends string = string, TVersions extends Record<ArvoSemanticVersion, {
     accepts: z.ZodTypeAny;
@@ -24,30 +39,11 @@ export default class ArvoContract<TUri extends string = string, TType extends st
     private readonly _type;
     private readonly _versions;
     readonly description: string | null;
-    /**
-     * Creates an instance of ArvoContract.
-     * @param params - The contract parameters.
-     */
     constructor(params: IArvoContract<TUri, TType, TVersions>);
     /**
      * 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
@@ -57,20 +53,6 @@ export default class ArvoContract<TUri extends string = string, TType extends st
      * Gets the version of the contract
      */
     get versions(): TVersions;
-    /**
-     * Get the latest version of the contract
-     */
-    get latestVersion(): ArvoSemanticVersion;
-    /**
-     * Gets the type and schema of the event that the contact
-     * bound handler listens to.
-     */
-    accepts<V extends ArvoSemanticVersion & keyof TVersions>(version: V): ArvoContractRecord<TType, TVersions[V]['accepts']>;
-    /**
-     * Gets all event types and schemas that can be emitted by the
-     * 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
@@ -86,33 +68,34 @@ export default class ArvoContract<TUri extends string = string, TType extends st
      * - 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
-     * 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.
+     * Retrieves a specific version of the contract or resolves special version identifiers.
+     *
+     * @template V - Type parameter constrained to valid semantic versions in TVersions
+     * @template S - Type parameter for special version identifiers
+     *
+     * @param option - Version identifier or special version string
+     * - Specific version (e.g., "1.0.0")
+     * - "latest" or "any" for the most recent version
+     * - "oldest" for the first version
+     *
+     * @returns A versioned contract instance with type-safe schemas
+     *
+     * @throws {Error} When an invalid or non-existent version is requested
      */
-    validateAccepts<V extends ArvoSemanticVersion & keyof TVersions, U>(version: V, type: TType, input: U): z.SafeParseReturnType<any, any>;
+    version<V extends ArvoSemanticVersion & keyof TVersions, S extends 'any' | 'latest' | 'oldest'>(option: V | S): V extends ArvoSemanticVersion ? VersionedArvoContract<typeof this, V> : VersionedArvoContract<typeof this, ArvoSemanticVersion & keyof TVersions>;
     /**
-     * Validates the contract bound handler's output/ emits against the
-     * contract's emit schema.
-     * @template U - The type of the output to validate.
-     * @param type - The type of the output event.
-     * @param output - The output data to validate.
-     * @returns The validation result.
-     * @throws If the emit type is not found in the contract.
+     * Retrieves version numbers in sorted order based on semantic versioning rules.
+     *
+     * @param ordering - Sort direction for versions
+     * - 'ASC' - Ascending order (oldest to newest)
+     * - 'DESC' - Descending order (newest to oldest)
+     *
+     * @returns Array of semantic versions sorted according to specified ordering
      */
-    validateEmits<V extends ArvoSemanticVersion & keyof TVersions, E extends string & keyof TVersions[V]['emits'], U>(version: V, type: E, output: U): z.SafeParseReturnType<any, any>;
+    getSortedVersionNumbers(ordering: 'ASC' | 'DESC'): `${number}.${number}.${number}`[];
     /**
      * 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.

package/dist/ArvoContract/index.js

@@ -1,34 +1,34 @@
 "use strict";
-var __assign = (this && this.__assign) || function () {
-    __assign = Object.assign || function(t) {
-        for (var s, i = 1, n = arguments.length; i < n; i++) {
-            s = arguments[i];
-            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
-                t[p] = s[p];
-        }
-        return t;
-    };
-    return __assign.apply(this, arguments);
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 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.
- * An event handler can be bound to it so the this contract may impose the types
- * on inputs and outputs of it
+ * Represents a contract with defined input and output schemas for event-driven architectures.
+ * The ArvoContract class provides type-safe validation and versioning capabilities for event handling,
+ * ensuring consistency in message passing between different parts of the system.
  *
- * @template TUri - The URI of the contract
- * @template TType - The accept type, defaults to string.
- * @template TVersion - The contract versions
+ * @template TUri - The URI identifier for the contract, must be a string type
+ * @template TType - The accept type for the contract, must be a string type
+ * @template TVersions - Record of versioned schemas defining contract structure per version
+ *
+ * @example
+ * ```typescript
+ * const contract = createArvoContract({
+ *   uri: '#/my/service/data',
+ *   type: 'com.process.data',
+ *   versions: {
+ *     '1.0.0': {
+ *       accepts: z.object({ data: z.string() }),
+ *       emits: {
+ *         'data.processed': z.object({ result: z.string() })
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
  */
 var ArvoContract = /** @class */ (function () {
-    /**
-     * Creates an instance of ArvoContract.
-     * @param params - The contract parameters.
-     */
     function ArvoContract(params) {
         var _a;
         this._uri = params.uri;
@@ -36,7 +36,7 @@ var ArvoContract = /** @class */ (function () {
         this._versions = params.versions;
         this.description = (_a = params.description) !== null && _a !== void 0 ? _a : null;
         if (!Object.keys(this._versions).length) {
-            throw new Error("A contract must have at least one version");
+            throw new Error("An ArvoContract (uri=".concat(this._uri, ") must have at least one version"));
         }
     }
     Object.defineProperty(ArvoContract.prototype, "uri", {
@@ -49,33 +49,6 @@ 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,35 +70,6 @@ var ArvoContract = /** @class */ (function () {
         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", {
         /**
          * Gets the system error event specification for this contract.
@@ -142,9 +86,6 @@ var ArvoContract = /** @class */ (function () {
          * - 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 {
@@ -156,38 +97,58 @@ var ArvoContract = /** @class */ (function () {
         configurable: true
     });
     /**
-     * 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.
+     * Retrieves a specific version of the contract or resolves special version identifiers.
+     *
+     * @template V - Type parameter constrained to valid semantic versions in TVersions
+     * @template S - Type parameter for special version identifiers
+     *
+     * @param option - Version identifier or special version string
+     * - Specific version (e.g., "1.0.0")
+     * - "latest" or "any" for the most recent version
+     * - "oldest" for the first version
+     *
+     * @returns A versioned contract instance with type-safe schemas
+     *
+     * @throws {Error} When an invalid or non-existent version is requested
      */
-    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, "\""));
+    ArvoContract.prototype.version = function (option) {
+        var resolvedVersion;
+        if (option === 'any' || option === 'latest') {
+            resolvedVersion = this.getSortedVersionNumbers('DESC')[0];
         }
-        return this._versions[version].accepts.safeParse(input);
+        else if (option === 'oldest') {
+            resolvedVersion = this.getSortedVersionNumbers('ASC')[0];
+        }
+        else if (!this._versions[option]) {
+            throw new Error("The contract (uri=".concat(this._uri, ") does not have version=").concat(option));
+        }
+        else {
+            resolvedVersion = option;
+        }
+        return {
+            uri: this._uri,
+            description: this.description,
+            version: resolvedVersion,
+            accepts: {
+                type: this._type,
+                schema: this._versions[resolvedVersion].accepts,
+            },
+            systemError: this.systemError,
+            emits: this._versions[resolvedVersion].emits,
+        }; // needed due to TypeScript limitations with conditional types
     };
     /**
-     * Validates the contract bound handler's output/ emits against the
-     * contract's emit schema.
-     * @template U - The type of the output to validate.
-     * @param type - The type of the output event.
-     * @param output - The output data to validate.
-     * @returns The validation result.
-     * @throws If the emit type is not found in the contract.
+     * Retrieves version numbers in sorted order based on semantic versioning rules.
+     *
+     * @param ordering - Sort direction for versions
+     * - 'ASC' - Ascending order (oldest to newest)
+     * - 'DESC' - Descending order (newest to oldest)
+     *
+     * @returns Array of semantic versions sorted according to specified ordering
      */
-    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(), "\" for version \"").concat(version, "\" not found in contract \"").concat(this._uri, "\""));
-        }
-        return emit.safeParse(output);
+    ArvoContract.prototype.getSortedVersionNumbers = function (ordering) {
+        var sorted = Object.keys(this._versions).sort(function (a, b) { return (0, utils_1.compareSemanticVersions)(b, a); });
+        return ordering === 'DESC' ? sorted : sorted.reverse();
     };
     /**
      * Exports the ArvoContract instance as a plain object conforming to the IArvoContract interface.

package/dist/ArvoEvent/helpers.d.ts

@@ -2,39 +2,86 @@ import ArvoEvent from '.';
 import { ArvoEventData, CloudEventExtension, CreateArvoEvent } from './types';
 import { ExecutionOpenTelemetryConfiguration } from '../OpenTelemetry/types';
 /**
- * Creates an ArvoEvent with the provided data and extensions.
+ * Creates a strongly-typed ArvoEvent with configurable telemetry options.
  *
- * This function creates a new ArvoEvent instance using the provided event data and optional extensions.
+ * @template TData - Event data type extending ArvoEventData
+ * @template TExtension - Cloud event extension type
+ * @template TType - String literal type for event type
  *
- * @template TData - The type of the event data, extending ArvoEventData.
- * @template TExtension - The type of the cloud event extension, extending CloudEventExtension.
- * @template TType - The type name of the event
+ * @param event - Event configuration and data
+ * @param [extensions] - Optional cloud event extensions
+ * @param [opentelemetry] - OpenTelemetry configuration with options:
+ *   - disable - Completely disables telemetry if true
+ *   - tracer - Custom OpenTelemetry tracer instance
  *
- * @param {CreateArvoEvent<TData>} event - The event data and metadata to create the ArvoEvent.
- * @param {TExtension} [extensions] - Optional cloud event extensions.
- * @param {ExecutionOpenTelemetryConfiguration} [opentelemetry] - Optional opentelemetry configuration object
+ * @returns ArvoEvent instance
  *
- * @returns {ArvoEvent<TData, TExtension>} The created ArvoEvent instance.
- *
- * @throws {Error} If there's an error during the creation process.
+ * @example
+ * ```typescript
+ * // With default telemetry
+ * const event = createArvoEvent({
+ *   type: 'order.created',
+ *   source: '/orders',
+ *   subject: 'order-123',
+ *   data: orderData
+ * });
  *
- * @remarks
- * - If no `id` is provided in the event object, a UUID v4 will be generated.
- * - If no `time` is provided, the current timestamp will be used.
- * - If no `datacontenttype` is provided, it defaults to `application/cloudevents+json;charset=UTF-8;profile=arvo`.
- * - If a non-compatible `datacontenttype` is provided, a warning will be logged to the span.
- * - The `source`, `subject`, `to`, `redirectto`, and `dataschema` fields are URI-encoded.
- * - If no `to` (null, undefined or empty string) is provided, then the `type` value is used by default
+ * // With disabled telemetry
+ * const event = createArvoEvent(
+ *   {
+ *     type: 'order.created',
+ *     source: '/orders',
+ *     subject: 'order-123',
+ *     data: orderData
+ *   },
+ *   undefined,
+ *   { disable: true }
+ * );
  *
- * @example
+ * // With custom tracer
  * const event = createArvoEvent(
  *   {
- *     type: 'com.example.event',
- *     source: '/example/source',
- *     subject: 'example-subject',
- *     data: { key: 'value' }
+ *     type: 'order.created',
+ *     source: '/orders',
+ *     subject: 'order-123',
+ *     data: orderData
  *   },
- *   { customextension: 'value' },
+ *   undefined,
+ *   { tracer: customTracer }
  * );
+ * ```
+ *
+ * @remarks
+ * This function provides several key features:
+ *
+ * 1. **Type Safety**:
+ *    - Ensures event data matches specified type
+ *    - Validates extension structure
+ *    - Provides type-safe event type strings
+ *
+ * 2. **Default Handling**:
+ *    - Generates UUID if no ID provided
+ *    - Sets current timestamp if no time provided
+ *    - Uses default ArvoDataContentType if none specified
+ *
+ * 3. **URI Handling**:
+ *    - Automatically encodes URI components (source, subject, to, redirectto, dataschema)
+ *    - Validates URI format
+ *
+ * 4. **OpenTelemetry Integration**:
+ *    - Creates spans for event creation
+ *    - Tracks errors and warnings
+ *    - Propagates trace context
+ *
+ * 5. **Validation**:
+ *    - Checks data content type compatibility
+ *    - Validates required fields
+ *    - Ensures URI format correctness
+ *
+ * @see {@link ArvoEvent} For the structure of the created event
+ * @see {@link ArvoDataContentType} For supported content types
+ * @see {@link CloudEventExtension} For extension structure
  */
-export declare const createArvoEvent: <TData extends ArvoEventData, TExtension extends CloudEventExtension, TType extends string>(event: CreateArvoEvent<TData, TType>, extensions?: TExtension, opentelemetry?: ExecutionOpenTelemetryConfiguration) => ArvoEvent<TData, TExtension, TType>;
+export declare const createArvoEvent: <TData extends ArvoEventData, TExtension extends CloudEventExtension, TType extends string>(event: CreateArvoEvent<TData, TType>, extensions?: TExtension, opentelemetry?: Partial<ExecutionOpenTelemetryConfiguration & {
+    disable: boolean;
+}>) => ArvoEvent<TData, TExtension, TType>;

package/dist/ArvoEvent/helpers.js

@@ -11,75 +11,144 @@ var utils_1 = require("../utils");
 var schema_1 = require("./schema");
 var uuid_1 = require("uuid");
 /**
- * Creates an ArvoEvent with the provided data and extensions.
+ * Internal generator function for creating ArvoEvent instances.
  *
- * This function creates a new ArvoEvent instance using the provided event data and optional extensions.
+ * @template TData - Type of the event data
+ * @template TExtension - Type of cloud event extensions
+ * @param {CreateArvoEvent<any, any>} event - The event configuration and data
+ * @param {any} extensions - Cloud event extensions
+ * @param {ReturnType<typeof currentOpenTelemetryHeaders>} otelHeaders - OpenTelemetry headers
+ * @returns {ArvoEvent<any, any, any>} A new ArvoEvent instance
  *
- * @template TData - The type of the event data, extending ArvoEventData.
- * @template TExtension - The type of the cloud event extension, extending CloudEventExtension.
- * @template TType - The type name of the event
- *
- * @param {CreateArvoEvent<TData>} event - The event data and metadata to create the ArvoEvent.
- * @param {TExtension} [extensions] - Optional cloud event extensions.
- * @param {ExecutionOpenTelemetryConfiguration} [opentelemetry] - Optional opentelemetry configuration object
+ * @remarks
+ * This function handles the actual creation of the ArvoEvent instance, including:
+ * - Generation of default values for optional fields
+ * - URI encoding of relevant fields
+ * - Validation of data content type
+ * - Integration with OpenTelemetry headers
+ * ```
+ */
+var generator = function (event, extensions, otelHeaders) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    if (event.datacontenttype && event.datacontenttype !== schema_1.ArvoDataContentType) {
+        var warning = (0, utils_1.cleanString)("\n    Warning! The provided datacontenttype(=".concat(event.datacontenttype, ")\n    is not ArvoEvent compatible (=").concat(schema_1.ArvoDataContentType, "). There may \n    be some limited functionality.\n  "));
+        (0, OpenTelemetry_1.logToSpan)({
+            level: 'WARNING',
+            message: warning,
+        });
+    }
+    return new _1.default({
+        id: (_a = event.id) !== null && _a !== void 0 ? _a : (0, uuid_1.v4)(),
+        type: event.type,
+        accesscontrol: (_b = event.accesscontrol) !== null && _b !== void 0 ? _b : null,
+        executionunits: (_c = event.executionunits) !== null && _c !== void 0 ? _c : null,
+        traceparent: (_e = (_d = event.traceparent) !== null && _d !== void 0 ? _d : otelHeaders.traceparent) !== null && _e !== void 0 ? _e : null,
+        tracestate: (_g = (_f = event.tracestate) !== null && _f !== void 0 ? _f : otelHeaders.tracestate) !== null && _g !== void 0 ? _g : null,
+        datacontenttype: (_h = event.datacontenttype) !== null && _h !== void 0 ? _h : schema_1.ArvoDataContentType,
+        specversion: (_j = event.specversion) !== null && _j !== void 0 ? _j : '1.0',
+        time: (_k = event.time) !== null && _k !== void 0 ? _k : (0, utils_1.createTimestamp)(),
+        source: encodeURI(event.source),
+        subject: encodeURI(event.subject),
+        to: event.to ? encodeURI(event.to) : encodeURI(event.type),
+        redirectto: event.redirectto ? encodeURI(event.redirectto) : null,
+        dataschema: event.dataschema ? encodeURI(event.dataschema) : null,
+    }, event.data, extensions);
+};
+/**
+ * Creates a strongly-typed ArvoEvent with configurable telemetry options.
  *
- * @returns {ArvoEvent<TData, TExtension>} The created ArvoEvent instance.
+ * @template TData - Event data type extending ArvoEventData
+ * @template TExtension - Cloud event extension type
+ * @template TType - String literal type for event type
  *
- * @throws {Error} If there's an error during the creation process.
+ * @param event - Event configuration and data
+ * @param [extensions] - Optional cloud event extensions
+ * @param [opentelemetry] - OpenTelemetry configuration with options:
+ *   - disable - Completely disables telemetry if true
+ *   - tracer - Custom OpenTelemetry tracer instance
  *
- * @remarks
- * - If no `id` is provided in the event object, a UUID v4 will be generated.
- * - If no `time` is provided, the current timestamp will be used.
- * - If no `datacontenttype` is provided, it defaults to `application/cloudevents+json;charset=UTF-8;profile=arvo`.
- * - If a non-compatible `datacontenttype` is provided, a warning will be logged to the span.
- * - The `source`, `subject`, `to`, `redirectto`, and `dataschema` fields are URI-encoded.
- * - If no `to` (null, undefined or empty string) is provided, then the `type` value is used by default
+ * @returns ArvoEvent instance
  *
  * @example
+ * ```typescript
+ * // With default telemetry
+ * const event = createArvoEvent({
+ *   type: 'order.created',
+ *   source: '/orders',
+ *   subject: 'order-123',
+ *   data: orderData
+ * });
+ *
+ * // With disabled telemetry
+ * const event = createArvoEvent(
+ *   {
+ *     type: 'order.created',
+ *     source: '/orders',
+ *     subject: 'order-123',
+ *     data: orderData
+ *   },
+ *   undefined,
+ *   { disable: true }
+ * );
+ *
+ * // With custom tracer
  * const event = createArvoEvent(
  *   {
- *     type: 'com.example.event',
- *     source: '/example/source',
- *     subject: 'example-subject',
- *     data: { key: 'value' }
+ *     type: 'order.created',
+ *     source: '/orders',
+ *     subject: 'order-123',
+ *     data: orderData
  *   },
- *   { customextension: 'value' },
+ *   undefined,
+ *   { tracer: customTracer }
  * );
+ * ```
+ *
+ * @remarks
+ * This function provides several key features:
+ *
+ * 1. **Type Safety**:
+ *    - Ensures event data matches specified type
+ *    - Validates extension structure
+ *    - Provides type-safe event type strings
+ *
+ * 2. **Default Handling**:
+ *    - Generates UUID if no ID provided
+ *    - Sets current timestamp if no time provided
+ *    - Uses default ArvoDataContentType if none specified
+ *
+ * 3. **URI Handling**:
+ *    - Automatically encodes URI components (source, subject, to, redirectto, dataschema)
+ *    - Validates URI format
+ *
+ * 4. **OpenTelemetry Integration**:
+ *    - Creates spans for event creation
+ *    - Tracks errors and warnings
+ *    - Propagates trace context
+ *
+ * 5. **Validation**:
+ *    - Checks data content type compatibility
+ *    - Validates required fields
+ *    - Ensures URI format correctness
+ *
+ * @see {@link ArvoEvent} For the structure of the created event
+ * @see {@link ArvoDataContentType} For supported content types
+ * @see {@link CloudEventExtension} For extension structure
  */
 var createArvoEvent = function (event, extensions, opentelemetry) {
-    opentelemetry = opentelemetry !== null && opentelemetry !== void 0 ? opentelemetry : {
-        tracer: (0, OpenTelemetry_1.fetchOpenTelemetryTracer)(),
-    };
-    var span = opentelemetry.tracer.startSpan("createArvoEvent<".concat(event.type, ">"), {});
+    var _a;
+    if (!(opentelemetry === null || opentelemetry === void 0 ? void 0 : opentelemetry.disable)) {
+        return generator(event, extensions, {
+            traceparent: null,
+            tracestate: null,
+        });
+    }
+    var tracer = (_a = opentelemetry === null || opentelemetry === void 0 ? void 0 : opentelemetry.tracer) !== null && _a !== void 0 ? _a : (0, OpenTelemetry_1.fetchOpenTelemetryTracer)();
+    var span = tracer.startSpan("createArvoEvent<".concat(event.type, ">"), {});
     return api_1.context.with(api_1.trace.setSpan(api_1.context.active(), span), function () {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
         span.setStatus({ code: api_1.SpanStatusCode.OK });
-        var otelHeaders = (0, OpenTelemetry_1.currentOpenTelemetryHeaders)();
         try {
-            if (event.datacontenttype &&
-                event.datacontenttype !== schema_1.ArvoDataContentType) {
-                var warning = (0, utils_1.cleanString)("\n        Warning! The provided datacontenttype(=".concat(event.datacontenttype, ")\n        is not ArvoEvent compatible (=").concat(schema_1.ArvoDataContentType, "). There may \n        be some limited functionality.\n      "));
-                (0, OpenTelemetry_1.logToSpan)({
-                    level: 'WARNING',
-                    message: warning,
-                });
-            }
-            return new _1.default({
-                id: (_a = event.id) !== null && _a !== void 0 ? _a : (0, uuid_1.v4)(),
-                type: event.type,
-                accesscontrol: (_b = event.accesscontrol) !== null && _b !== void 0 ? _b : null,
-                executionunits: (_c = event.executionunits) !== null && _c !== void 0 ? _c : null,
-                traceparent: (_e = (_d = event.traceparent) !== null && _d !== void 0 ? _d : otelHeaders.traceparent) !== null && _e !== void 0 ? _e : null,
-                tracestate: (_g = (_f = event.tracestate) !== null && _f !== void 0 ? _f : otelHeaders.tracestate) !== null && _g !== void 0 ? _g : null,
-                datacontenttype: (_h = event.datacontenttype) !== null && _h !== void 0 ? _h : schema_1.ArvoDataContentType,
-                specversion: (_j = event.specversion) !== null && _j !== void 0 ? _j : '1.0',
-                time: (_k = event.time) !== null && _k !== void 0 ? _k : (0, utils_1.createTimestamp)(),
-                source: encodeURI(event.source),
-                subject: encodeURI(event.subject),
-                to: event.to ? encodeURI(event.to) : encodeURI(event.type),
-                redirectto: event.redirectto ? encodeURI(event.redirectto) : null,
-                dataschema: event.dataschema ? encodeURI(event.dataschema) : null,
-            }, event.data, extensions);
+            return generator(event, extensions, (0, OpenTelemetry_1.currentOpenTelemetryHeaders)());
         }
         catch (error) {
             (0, OpenTelemetry_1.exceptionToSpan)(error);

package/dist/ArvoEventFactory/index.js

@@ -93,7 +93,7 @@ var ArvoEventFactory = /** @class */ (function () {
                 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.accepts.type, datacontenttype: schema_1.ArvoDataContentType, dataschema: "".concat(_this.contract.uri, "/").concat(_this.contract.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, { disable: true });
             }
             catch (error) {
                 (0, OpenTelemetry_1.exceptionToSpan)(error);
@@ -147,7 +147,7 @@ var ArvoEventFactory = /** @class */ (function () {
                     var msg = (_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);
                     throw new Error("Emit Event data validation failed: ".concat(msg));
                 }
-                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);
+                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, { disable: true });
             }
             catch (error) {
                 (0, OpenTelemetry_1.exceptionToSpan)(error);
@@ -200,7 +200,7 @@ var ArvoEventFactory = /** @class */ (function () {
                         errorName: error.name,
                         errorMessage: error.message,
                         errorStack: (_e = error.stack) !== null && _e !== void 0 ? _e : null,
-                    }, datacontenttype: schema_1.ArvoDataContentType, dataschema: "".concat(_this.contract.uri, "/").concat(ArvoOrchestrationSubject_1.default.WildCardMachineVersion) }), extensions, opentelemetry);
+                    }, datacontenttype: schema_1.ArvoDataContentType, dataschema: "".concat(_this.contract.uri, "/").concat(ArvoOrchestrationSubject_1.default.WildCardMachineVersion) }), extensions, { disable: true });
             }
             catch (error) {
                 (0, OpenTelemetry_1.exceptionToSpan)(error);

package/dist/types.d.ts

@@ -129,12 +129,6 @@ type InferZodSchema<T> = T extends z.ZodTypeAny ? z.infer<T> : never;
  * //   systemError: { ... inferred system error event type ... };
  * // }
  * ```
- *
- * @remarks
- * - All version keys must be valid {@link ArvoSemanticVersion} strings
- * - The contract must define at least one version
- * - Each version must specify both accepted and emitted event schemas
- * - System error handling is automatically included for all contracts
  */
 export type InferArvoContract<T extends ArvoContract<string, string, Record<ArvoSemanticVersion, {
     accepts: z.ZodTypeAny;
@@ -184,19 +178,6 @@ export type ArvoErrorType = z.infer<typeof ArvoErrorSchema>;
  * @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

package/package.json

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