arvo-core 1.1.6 → 1.1.8

package/CHANGELOG.md

@@ -60,3 +60,7 @@
 
 - Added support for ArvoEvent http formats and made ArvoEvent extensions more specific
 
+## [1.1.8] - 2024-09-26
+
+- Added Arvo Orchestrator Contract primitive
+

package/dist/ArvoContract/helpers.js

@@ -5,6 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createArvoContract = void 0;
 var _1 = __importDefault(require("."));
+var typegen_1 = require("../ArvoOrchestratorContract/typegen");
+var utils_1 = require("../utils");
 /**
  * Creates an ArvoContract instance from the given contract specification.
  *
@@ -32,6 +34,17 @@ var _1 = __importDefault(require("."));
  * });
  */
 var createArvoContract = function (contract) {
+    var createErrorMessage = function (source, type) { return (0, utils_1.cleanString)("\n    In contract (uri=".concat(contract.uri, "), the '").concat(source, "' event (type=").concat(type, ") must not start \n    with '").concat(typegen_1.ArvoOrchestratorEventTypeGen.__prefix, "' becuase this a reserved pattern \n    for Arvo orchestrators.\n  ")); };
+    var validator = function (value) { return value.startsWith(typegen_1.ArvoOrchestratorEventTypeGen.__prefix); };
+    if (validator(contract.accepts.type)) {
+        throw new Error(createErrorMessage('accepts', contract.accepts.type));
+    }
+    for (var _i = 0, _a = Object.keys(contract.emits); _i < _a.length; _i++) {
+        var item = _a[_i];
+        if (validator(item)) {
+            throw new Error(createErrorMessage('emits', item));
+        }
+    }
     return new _1.default(contract);
 };
 exports.createArvoContract = createArvoContract;

package/dist/ArvoEventFactory/index.d.ts

@@ -26,9 +26,7 @@ export default class ArvoEventFactory<TUri extends string = string, TType extend
      * @returns The created ArvoEvent as per the accept record of the contract.
      * @throws If the event data fails validation against the contract.
      */
-    accepts<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<z.infer<TAcceptSchema>, TType>, 'type'> & {
-        to: string;
-    }, extensions?: TExtension): import("..").ArvoEvent<z.TypeOf<TAcceptSchema>, TExtension, TType>;
+    accepts<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<z.infer<TAcceptSchema>, TType>, 'type' | 'datacontenttype' | 'dataschema'>, extensions?: TExtension): import("..").ArvoEvent<z.TypeOf<TAcceptSchema>, TExtension, TType>;
     /**
      * Creates an ArvoEvent as per one of the emits record in the contract.
      *
@@ -39,9 +37,7 @@ export default class ArvoEventFactory<TUri extends string = string, TType extend
      * @returns The created ArvoEvent as per one of the emits records of the contract.
      * @throws If the event data fails validation against the contract.
      */
-    emits<U extends keyof TEmits & string, TExtension extends Record<string, any>>(event: CreateArvoEvent<z.infer<TEmits[U]>, U> & {
-        to: string;
-    }, extensions?: TExtension): import("..").ArvoEvent<z.TypeOf<TEmits[U]>, TExtension, U>;
+    emits<U extends keyof TEmits & string, TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<z.infer<TEmits[U]>, U>, 'datacontenttype' | 'dataschema'>, extensions?: TExtension): import("..").ArvoEvent<z.TypeOf<TEmits[U]>, TExtension, U>;
     /**
      * Creates a system error ArvoEvent.
      *
@@ -50,9 +46,8 @@ export default class ArvoEventFactory<TUri extends string = string, TType extend
      * @param [extensions] - Optional extensions to add to the event.
      * @returns The created system error ArvoEvent.
      */
-    systemError<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<any, any>, 'data' | 'type'> & {
+    systemError<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<any, any>, 'data' | 'type' | 'datacontenttype' | 'dataschema'> & {
         error: Error;
-        to: string;
     }, extensions?: TExtension): import("..").ArvoEvent<{
         errorMessage: string;
         errorName: string;

package/dist/ArvoEventFactory/index.js

@@ -127,8 +127,8 @@ var ArvoEventFactory = /** @class */ (function () {
             var _a;
             span.setStatus({ code: api_1.SpanStatusCode.OK });
             try {
-                var error = event.error, _events = __rest(event, ["error"]);
-                return (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { type: "sys.".concat(_this.contract.accepts.type, ".error"), data: {
+                var error = event.error, _event = __rest(event, ["error"]);
+                return (0, helpers_1.createArvoEvent)(__assign(__assign({}, _event), { type: "sys.".concat(_this.contract.accepts.type, ".error"), data: {
                         errorName: error.name,
                         errorMessage: error.message,
                         errorStack: (_a = error.stack) !== null && _a !== void 0 ? _a : null,

package/dist/ArvoEventHttp/index.js

@@ -88,7 +88,7 @@ var ArvoEventHttp = /** @class */ (function () {
      */
     ArvoEventHttp.importFromBinary = function (config) {
         var _a, _b;
-        this.validateContentType((_b = (_a = config.headers['content-type']) === null || _a === void 0 ? void 0 : _a.toString()) !== null && _b !== void 0 ? _b : "", 'application/json');
+        this.validateContentType((_b = (_a = config.headers['content-type']) === null || _a === void 0 ? void 0 : _a.toString()) !== null && _b !== void 0 ? _b : '', 'application/json');
         var event = this.extractEventFieldsFromHeaders(config.headers);
         this.validateRequiredFields(event, true);
         var extensions = this.extractExtensions(config.headers);
@@ -102,7 +102,7 @@ var ArvoEventHttp = /** @class */ (function () {
      */
     ArvoEventHttp.importFromStructured = function (config) {
         var _a, _b;
-        this.validateContentType((_b = (_a = config.headers['content-type']) === null || _a === void 0 ? void 0 : _a.toString()) !== null && _b !== void 0 ? _b : "", schema_1.ArvoDataContentType);
+        this.validateContentType((_b = (_a = config.headers['content-type']) === null || _a === void 0 ? void 0 : _a.toString()) !== null && _b !== void 0 ? _b : '', schema_1.ArvoDataContentType);
         var eventData = config.data;
         this.validateRequiredFields(eventData, false);
         return this.createArvoEventFromStructured(eventData);
@@ -124,7 +124,22 @@ var ArvoEventHttp = /** @class */ (function () {
      * @returns An object with extracted event fields.
      */
     ArvoEventHttp.extractEventFieldsFromHeaders = function (headers) {
-        var eventFields = ['id', 'type', 'accesscontrol', 'executionunits', 'traceparent', 'tracestate', 'datacontenttype', 'specversion', 'time', 'source', 'subject', 'to', 'redirectto', 'dataschema'];
+        var eventFields = [
+            'id',
+            'type',
+            'accesscontrol',
+            'executionunits',
+            'traceparent',
+            'tracestate',
+            'datacontenttype',
+            'specversion',
+            'time',
+            'source',
+            'subject',
+            'to',
+            'redirectto',
+            'dataschema',
+        ];
         return Object.fromEntries(eventFields
             .map(function (field) { return ["ce-".concat(field), headers["ce-".concat(field)]]; })
             .filter(function (_a) {
@@ -167,7 +182,22 @@ var ArvoEventHttp = /** @class */ (function () {
      * @returns An object with extracted extension fields.
      */
     ArvoEventHttp.extractExtensions = function (headers) {
-        var eventFields = ['id', 'type', 'accesscontrol', 'executionunits', 'traceparent', 'tracestate', 'datacontenttype', 'specversion', 'time', 'source', 'subject', 'to', 'redirectto', 'dataschema'];
+        var eventFields = [
+            'id',
+            'type',
+            'accesscontrol',
+            'executionunits',
+            'traceparent',
+            'tracestate',
+            'datacontenttype',
+            'specversion',
+            'time',
+            'source',
+            'subject',
+            'to',
+            'redirectto',
+            'dataschema',
+        ];
         return Object.fromEntries(Object.entries(headers)
             .filter(function (_a) {
             var key = _a[0];
@@ -191,7 +221,9 @@ var ArvoEventHttp = /** @class */ (function () {
             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: event.executionunits ? Number(event.executionunits) : null,
+            executionunits: event.executionunits
+                ? Number(event.executionunits)
+                : null,
             traceparent: (_c = event.traceparent) !== null && _c !== void 0 ? _c : null,
             tracestate: (_d = event.tracestate) !== null && _d !== void 0 ? _d : null,
             datacontenttype: (_e = event.datacontenttype) !== null && _e !== void 0 ? _e : schema_1.ArvoDataContentType,

package/dist/ArvoOrchestratorContract/helpers.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { ICreateArvoOrchestratorContract } from "./types";
+import ArvoOrchestratorContract from ".";
+/**
+ * Creates an ArvoOrchestratorContract with specified parameters.
+ *
+ * The ArvoOrchestratorContract is a specialized contract class designed to manage the lifecycle
+ * of orchestration processes within the Arvo framework. It extends the base ArvoContract class
+ * to provide specific functionality for orchestration scenarios.
+ *
+ * Key features:
+ * 1. Initialization: Defines the structure and validation for the initial event that starts the orchestration.
+ * 2. Completion: Specifies the event type and data emitted when the orchestration process concludes.
+ * 3. Type Safety: Utilizes TypeScript generics to ensure type consistency across the contract definition.
+ * 4. Runtime Validation: Employs Zod schemas for robust runtime type checking and data validation.
+ *
+ * This contract serves as a crucial component in maintaining consistency and type safety
+ * throughout the orchestration process, from initiation to completion.
+ *
+ * @param param - The configuration object for creating the contract.
+ * @param param.uri - The URI for the contract.
+ * @param param.name - The name of the contract (must be alphanumeric).
+ * @param param.schema - The schema object containing init and complete Zod schemas.
+ * @param param.schema.init - The Zod schema for initialization.
+ * @param param.schema.complete - The Zod schema for completion.
+ *
+ * @throws {Error} Throws an error if the name is not alphanumeric.
+ *
+ * @returns Returns a new ArvoOrchestratorContract instance with the specified parameters.
+ */
+export declare const createArvoOrchestratorContract: <TUri extends string, TName extends string, TInit extends z.ZodTypeAny, TComplete extends z.ZodTypeAny>(param: ICreateArvoOrchestratorContract<TUri, TName, TInit, TComplete>) => ArvoOrchestratorContract<TUri, `arvo.orc.${TName}`, TInit, `arvo.orc.${TName}.done`, TComplete>;

package/dist/ArvoOrchestratorContract/helpers.js

@@ -0,0 +1,69 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createArvoOrchestratorContract = void 0;
+var _1 = __importDefault(require("."));
+var typegen_1 = require("./typegen");
+/**
+ * Validates if a string contains only uppercase or lowercase alphanumeric characters.
+ *
+ * This function checks if the input string consists solely of:
+ * - Lowercase letters (a-z)
+ * - Numbers (0-9)
+ * - Dot (.)
+ *
+ * It does not allow any special characters, spaces, or other non-alphanumeric characters.
+ *
+ * @param input - The string to be validated.
+ * @returns True if the string contains only alphanumeric characters, false otherwise.
+ */
+function isLowerAlphanumeric(input) {
+    var alphanumericRegex = /^[a-z0-9.]+$/;
+    return alphanumericRegex.test(input);
+}
+/**
+ * Creates an ArvoOrchestratorContract with specified parameters.
+ *
+ * The ArvoOrchestratorContract is a specialized contract class designed to manage the lifecycle
+ * of orchestration processes within the Arvo framework. It extends the base ArvoContract class
+ * to provide specific functionality for orchestration scenarios.
+ *
+ * Key features:
+ * 1. Initialization: Defines the structure and validation for the initial event that starts the orchestration.
+ * 2. Completion: Specifies the event type and data emitted when the orchestration process concludes.
+ * 3. Type Safety: Utilizes TypeScript generics to ensure type consistency across the contract definition.
+ * 4. Runtime Validation: Employs Zod schemas for robust runtime type checking and data validation.
+ *
+ * This contract serves as a crucial component in maintaining consistency and type safety
+ * throughout the orchestration process, from initiation to completion.
+ *
+ * @param param - The configuration object for creating the contract.
+ * @param param.uri - The URI for the contract.
+ * @param param.name - The name of the contract (must be alphanumeric).
+ * @param param.schema - The schema object containing init and complete Zod schemas.
+ * @param param.schema.init - The Zod schema for initialization.
+ * @param param.schema.complete - The Zod schema for completion.
+ *
+ * @throws {Error} Throws an error if the name is not alphanumeric.
+ *
+ * @returns Returns a new ArvoOrchestratorContract instance with the specified parameters.
+ */
+var createArvoOrchestratorContract = function (param) {
+    if (!isLowerAlphanumeric(param.name)) {
+        throw new Error("Invalid 'name' = '".concat(param.name, "'. The 'name' must only contain alphanumeric characters."));
+    }
+    return new _1.default({
+        uri: param.uri,
+        init: {
+            type: typegen_1.ArvoOrchestratorEventTypeGen.init(param.name),
+            schema: param.schema.init,
+        },
+        complete: {
+            type: typegen_1.ArvoOrchestratorEventTypeGen.complete(param.name),
+            schema: param.schema.complete,
+        }
+    });
+};
+exports.createArvoOrchestratorContract = createArvoOrchestratorContract;

package/dist/ArvoOrchestratorContract/index.d.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import ArvoContract from '../ArvoContract';
+import { IArvoOrchestratorContract } from './types';
+/**
+ * Defines the contract for the Arvo Orchestrator, specifying accepted events and emitted events.
+ *
+ * The ArvoOrchestratorContract is a specialized contract class designed to manage the lifecycle
+ * of orchestration processes within the Arvo framework. It extends the base ArvoContract class
+ * to provide specific functionality for orchestration scenarios.
+ *
+ * Key features:
+ * 1. Initialization: Defines the structure and validation for the initial event that starts the orchestration.
+ * 2. Completion: Specifies the event type and data emitted when the orchestration process concludes.
+ * 3. Type Safety: Utilizes TypeScript generics to ensure type consistency across the contract definition.
+ * 4. Runtime Validation: Employs Zod schemas for robust runtime type checking and data validation.
+ *
+ * This contract serves as a crucial component in maintaining consistency and type safety
+ * throughout the orchestration process, from initiation to completion.
+ *
+ * @example
+ * ```typescript
+ * import { createArvoOrchestratorContract } from 'arvo-core'
+ * import { z } from 'zod'
+ *
+ * const contract = createArvoOrchestratorContract({
+ *  uri: '#/example/contract',
+ *  name: 'rag',
+ *  schema: {
+ *    init: z.object({
+ *      request: z.string()
+ *      vectorStore: z.string(),
+ *      llm: z.string()
+ *    }),
+ *    complete: z.object({
+ *      response: z.string()
+ *    })
+ *  }
+ * })
+ * ```
+ */
+export default class ArvoOrchestratorContract<TUri extends string = string, TInitType extends string = string, TInit extends z.ZodTypeAny = z.ZodTypeAny, TCompleteType extends string = string, TComplete extends z.ZodTypeAny = z.ZodTypeAny> extends ArvoContract<TUri, TInitType, TInit, {
+    [K in TCompleteType]: TComplete;
+}> {
+    /**
+     * Constructs a new ArvoOrchestratorContract instance.
+     *
+     * @param param - The configuration object for the contract.
+     */
+    constructor(param: IArvoOrchestratorContract<TUri, TInitType, TInit, TCompleteType, TComplete>);
+    /**
+     * Gets the initialization event configuration.
+     *
+     * @returns An object containing the type and schema for the initialization event.
+     */
+    get init(): {
+        type: TInitType;
+        schema: TInit;
+    };
+    /**
+     * Gets the completion event configuration.
+     *
+     * @returns An object containing the type and schema for the completion event.
+     */
+    get complete(): {
+        type: TCompleteType;
+        schema: TComplete;
+    };
+}

package/dist/ArvoOrchestratorContract/index.js

@@ -0,0 +1,107 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var ArvoContract_1 = __importDefault(require("../ArvoContract"));
+/**
+ * Defines the contract for the Arvo Orchestrator, specifying accepted events and emitted events.
+ *
+ * The ArvoOrchestratorContract is a specialized contract class designed to manage the lifecycle
+ * of orchestration processes within the Arvo framework. It extends the base ArvoContract class
+ * to provide specific functionality for orchestration scenarios.
+ *
+ * Key features:
+ * 1. Initialization: Defines the structure and validation for the initial event that starts the orchestration.
+ * 2. Completion: Specifies the event type and data emitted when the orchestration process concludes.
+ * 3. Type Safety: Utilizes TypeScript generics to ensure type consistency across the contract definition.
+ * 4. Runtime Validation: Employs Zod schemas for robust runtime type checking and data validation.
+ *
+ * This contract serves as a crucial component in maintaining consistency and type safety
+ * throughout the orchestration process, from initiation to completion.
+ *
+ * @example
+ * ```typescript
+ * import { createArvoOrchestratorContract } from 'arvo-core'
+ * import { z } from 'zod'
+ *
+ * const contract = createArvoOrchestratorContract({
+ *  uri: '#/example/contract',
+ *  name: 'rag',
+ *  schema: {
+ *    init: z.object({
+ *      request: z.string()
+ *      vectorStore: z.string(),
+ *      llm: z.string()
+ *    }),
+ *    complete: z.object({
+ *      response: z.string()
+ *    })
+ *  }
+ * })
+ * ```
+ */
+var ArvoOrchestratorContract = /** @class */ (function (_super) {
+    __extends(ArvoOrchestratorContract, _super);
+    /**
+     * Constructs a new ArvoOrchestratorContract instance.
+     *
+     * @param param - The configuration object for the contract.
+     */
+    function ArvoOrchestratorContract(param) {
+        var _a;
+        return _super.call(this, {
+            uri: param.uri,
+            accepts: param.init,
+            // @ts-ignore
+            emits: (_a = {},
+                _a[param.complete.type] = param.complete.schema,
+                _a),
+        }) || this;
+    }
+    Object.defineProperty(ArvoOrchestratorContract.prototype, "init", {
+        /**
+         * Gets the initialization event configuration.
+         *
+         * @returns An object containing the type and schema for the initialization event.
+         */
+        get: function () {
+            return this.accepts;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(ArvoOrchestratorContract.prototype, "complete", {
+        /**
+         * Gets the completion event configuration.
+         *
+         * @returns An object containing the type and schema for the completion event.
+         */
+        get: function () {
+            var _a = Object.entries(this.emits)[0], type = _a[0], schema = _a[1];
+            return {
+                type: type,
+                schema: schema,
+            };
+        },
+        enumerable: false,
+        configurable: true
+    });
+    return ArvoOrchestratorContract;
+}(ArvoContract_1.default));
+exports.default = ArvoOrchestratorContract;

package/dist/ArvoOrchestratorContract/typegen.d.ts

@@ -0,0 +1,6 @@
+export declare const ArvoOrchestratorEventTypeGen: {
+    __prefix: `arvo.orc`;
+    init: <T extends string>(name: T) => `${typeof ArvoOrchestratorEventTypeGen.__prefix}.${T}`;
+    complete: <T extends string>(name: T) => `${ReturnType<typeof ArvoOrchestratorEventTypeGen.init<T>>}.done`;
+    systemError: <T extends string>(name: T) => `sys.${ReturnType<typeof ArvoOrchestratorEventTypeGen.init<T>>}.error`;
+};

package/dist/ArvoOrchestratorContract/typegen.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArvoOrchestratorEventTypeGen = void 0;
+exports.ArvoOrchestratorEventTypeGen = {
+    __prefix: "arvo.orc",
+    init: function (name) { return "".concat(exports.ArvoOrchestratorEventTypeGen.__prefix, ".").concat(name); },
+    complete: function (name) { return "".concat(exports.ArvoOrchestratorEventTypeGen.init(name), ".done"); },
+    systemError: function (name) { return "sys.".concat(exports.ArvoOrchestratorEventTypeGen.init(name), ".error"); }
+};

package/dist/ArvoOrchestratorContract/types.d.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+/**
+ * Represents the configuration interface for an Arvo Orchestrator Contract.
+ *
+ * This interface defines the structure of the configuration object used to initialize
+ * an ArvoOrchestratorContract. It specifies the types and schemas for both the
+ * initialization event and the completion event of the orchestration process.
+ *
+ * @template TUri - The type for the URI string that uniquely identifies the contract.
+ * @template TInitType - The literal type for the initialization event type.
+ * @template TInit - The Zod schema type for validating the initialization event data.
+ * @template TCompleteType - The literal type for the completion event type.
+ * @template TComplete - The Zod schema type for validating the completion event data.
+ */
+export interface IArvoOrchestratorContract<TUri extends string, TInitType extends string, TInit extends z.ZodTypeAny, TCompleteType extends string, TComplete extends z.ZodTypeAny> {
+    /**
+     * The unique identifier for the contract.
+     */
+    uri: TUri;
+    /**
+     * Configuration for the initialization event.
+     */
+    init: {
+        /**
+         * The type identifier for the initialization event.
+         */
+        type: TInitType;
+        /**
+         * The Zod schema used to validate the initialization event data.
+         */
+        schema: TInit;
+    };
+    /**
+     * Configuration for the completion event.
+     */
+    complete: {
+        /**
+         * The type identifier for the completion event.
+         */
+        type: TCompleteType;
+        /**
+         * The Zod schema used to validate the completion event data.
+         */
+        schema: TComplete;
+    };
+}
+/**
+ * Interface for creating an Arvo Orchestrator Contract.
+ *
+ * This interface defines the structure of the configuration object used to create
+ * an ArvoOrchestratorContract. It specifies the URI, name, and schemas for both
+ * the initialization and completion events of the orchestration process.
+ *
+ * @template TUri - The type for the URI string that uniquely identifies the contract.
+ * @template TName - The type for the name of the contract.
+ * @template TInit - The Zod schema type for validating the initialization event data.
+ * @template TComplete - The Zod schema type for validating the completion event data.
+ */
+export interface ICreateArvoOrchestratorContract<TUri extends string, TName extends string, TInit extends z.ZodTypeAny, TComplete extends z.ZodTypeAny> {
+    /**
+     * The unique identifier for the contract.
+     * This URI should be used to reference the contract within the system.
+     */
+    uri: TUri;
+    /**
+     * The name of the contract.
+     * This can be used for display purposes or for easier identification of the contract.
+     */
+    name: TName;
+    /**
+     * The schema definitions for the contract events.
+     */
+    schema: {
+        /**
+         * The Zod schema used to validate the initialization event data.
+         * This schema defines the structure and types of the data required to start the orchestration process.
+         */
+        init: TInit;
+        /**
+         * The Zod schema used to validate the completion event data.
+         * This schema defines the structure and types of the data emitted when the orchestration process completes.
+         */
+        complete: TComplete;
+    };
+}

package/dist/ArvoOrchestratorContract/types.js

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

package/dist/index.d.ts

@@ -23,7 +23,11 @@ import { ArvoOrchestrationSubjectContentSchema, ArvoOchestratorVersionSchema } f
 import { ArvoOrchestrationSubjectContent, ArvoOchestratorVersion } from './ArvoOrchestrationSubject/type';
 import ArvoEventHttp from './ArvoEventHttp';
 import { ArvoEventHttpConfig } from './ArvoEventHttp/types';
-import { InferArvoContract, InferArvoEvent } from './types';
+import { InferArvoContract, InferArvoEvent, InferArvoOrchestratorContract } from './types';
+import { createArvoOrchestratorContract } from './ArvoOrchestratorContract/helpers';
+import ArvoOrchestratorContract from './ArvoOrchestratorContract';
+import { ICreateArvoOrchestratorContract, IArvoOrchestratorContract } from './ArvoOrchestratorContract/types';
+import { ArvoOrchestratorEventTypeGen } from './ArvoOrchestratorContract/typegen';
 /**
  * Collection of Zod schemas for validating various aspects of Arvo events.
  * @property {z.ZodObject} CloudEventContextSchema - Schema for core CloudEvent properties.
@@ -90,4 +94,4 @@ declare const ArvoEventSchemas: {
         tracestate: string | null;
     }>;
 };
-export { ArvoEventHttpConfig, ArvoEventHttp, ArvoEvent, createArvoEvent, ArvoDataContentType, ArvoEventData, CloudEventExtension, ArvoEventSchemas, CloudEventContext, ArvoExtension, OpenTelemetryExtension, CreateArvoEvent, exceptionToSpan, logToSpan, OpenTelemetryHeaders, TelemetryLogLevel, OTelNull, validateURI, cleanString, ArvoContract, createArvoContract, ArvoContractValidators, ArvoContractRecord, IArvoContract, ResolveArvoContractRecord, ArvoContractLibrary, createArvoContractLibrary, ArvoEventFactory, createArvoEventFactory, ArvoErrorSchema, currentOpenTelemetryHeaders, OpenInference, OpenInferenceSpanKind, ArvoExecution, ArvoExecutionSpanKind, ArvoContractJSONSchema, ArvoOrchestrationSubject, ArvoOrchestrationSubjectContentSchema, ArvoOchestratorVersionSchema, ArvoOrchestrationSubjectContent, ArvoOchestratorVersion, InferArvoEvent, InferArvoContract, InferArvoContractType, };
+export { ArvoEventHttpConfig, ArvoEventHttp, ArvoEvent, createArvoEvent, ArvoDataContentType, ArvoEventData, CloudEventExtension, ArvoEventSchemas, CloudEventContext, ArvoExtension, OpenTelemetryExtension, CreateArvoEvent, exceptionToSpan, logToSpan, OpenTelemetryHeaders, TelemetryLogLevel, OTelNull, validateURI, cleanString, ArvoContract, createArvoContract, ArvoContractValidators, ArvoContractRecord, IArvoContract, ResolveArvoContractRecord, ArvoContractLibrary, createArvoContractLibrary, ArvoEventFactory, createArvoEventFactory, ArvoErrorSchema, currentOpenTelemetryHeaders, OpenInference, OpenInferenceSpanKind, ArvoExecution, ArvoExecutionSpanKind, ArvoContractJSONSchema, ArvoOrchestrationSubject, ArvoOrchestrationSubjectContentSchema, ArvoOchestratorVersionSchema, ArvoOrchestrationSubjectContent, ArvoOchestratorVersion, InferArvoEvent, InferArvoContract, InferArvoContractType, createArvoOrchestratorContract, ArvoOrchestratorContract, ICreateArvoOrchestratorContract, IArvoOrchestratorContract, InferArvoOrchestratorContract, ArvoOrchestratorEventTypeGen };

package/dist/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ArvoOchestratorVersionSchema = exports.ArvoOrchestrationSubjectContentSchema = exports.ArvoOrchestrationSubject = exports.ArvoExecutionSpanKind = exports.ArvoExecution = exports.OpenInferenceSpanKind = exports.OpenInference = exports.currentOpenTelemetryHeaders = exports.ArvoErrorSchema = exports.createArvoEventFactory = exports.ArvoEventFactory = exports.createArvoContractLibrary = exports.ArvoContractLibrary = exports.ArvoContractValidators = exports.createArvoContract = exports.ArvoContract = exports.cleanString = exports.validateURI = exports.OTelNull = exports.logToSpan = exports.exceptionToSpan = exports.ArvoEventSchemas = exports.ArvoDataContentType = exports.createArvoEvent = exports.ArvoEvent = exports.ArvoEventHttp = void 0;
+exports.ArvoOrchestratorEventTypeGen = exports.ArvoOrchestratorContract = exports.createArvoOrchestratorContract = exports.ArvoOchestratorVersionSchema = exports.ArvoOrchestrationSubjectContentSchema = exports.ArvoOrchestrationSubject = exports.ArvoExecutionSpanKind = exports.ArvoExecution = exports.OpenInferenceSpanKind = exports.OpenInference = exports.currentOpenTelemetryHeaders = exports.ArvoErrorSchema = exports.createArvoEventFactory = exports.ArvoEventFactory = exports.createArvoContractLibrary = exports.ArvoContractLibrary = exports.ArvoContractValidators = exports.createArvoContract = exports.ArvoContract = exports.cleanString = exports.validateURI = exports.OTelNull = exports.logToSpan = exports.exceptionToSpan = exports.ArvoEventSchemas = exports.ArvoDataContentType = exports.createArvoEvent = exports.ArvoEvent = exports.ArvoEventHttp = void 0;
 var ArvoEvent_1 = __importDefault(require("./ArvoEvent"));
 exports.ArvoEvent = ArvoEvent_1.default;
 var schema_1 = require("./ArvoEvent/schema");
@@ -49,6 +49,12 @@ Object.defineProperty(exports, "ArvoOrchestrationSubjectContentSchema", { enumer
 Object.defineProperty(exports, "ArvoOchestratorVersionSchema", { enumerable: true, get: function () { return schema_3.ArvoOchestratorVersionSchema; } });
 var ArvoEventHttp_1 = __importDefault(require("./ArvoEventHttp"));
 exports.ArvoEventHttp = ArvoEventHttp_1.default;
+var helpers_5 = require("./ArvoOrchestratorContract/helpers");
+Object.defineProperty(exports, "createArvoOrchestratorContract", { enumerable: true, get: function () { return helpers_5.createArvoOrchestratorContract; } });
+var ArvoOrchestratorContract_1 = __importDefault(require("./ArvoOrchestratorContract"));
+exports.ArvoOrchestratorContract = ArvoOrchestratorContract_1.default;
+var typegen_1 = require("./ArvoOrchestratorContract/typegen");
+Object.defineProperty(exports, "ArvoOrchestratorEventTypeGen", { enumerable: true, get: function () { return typegen_1.ArvoOrchestratorEventTypeGen; } });
 /**
  * Collection of Zod schemas for validating various aspects of Arvo events.
  * @property {z.ZodObject} CloudEventContextSchema - Schema for core CloudEvent properties.

package/dist/types.d.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import ArvoContract from './ArvoContract';
 import ArvoEvent from './ArvoEvent';
 import { ArvoExtension, OpenTelemetryExtension } from './ArvoEvent/types';
+import ArvoOrchestratorContract from './ArvoOrchestratorContract';
 /**
  * A type utility that infers the structure of an ArvoEvent.
  *
@@ -79,4 +80,47 @@ export type InferArvoContract<T extends ArvoContract<string, string, z.ZodTypeAn
         [K in `sys.${TType}.error`]: InferArvoEvent<ArvoEvent<InferZodSchema<T['systemError']['schema']>, {}, T['systemError']['type']>>;
     })[keyof TEmits | `sys.${TType}.error`];
 } : never;
+/**
+ * A type utility that infers the structure of an ArvoOrchestratorContract.
+ *
+ * @template T - The type to infer from, expected to be an ArvoOrchestratorContract.
+ *
+ * @returns An object type that includes the URI, accepted event type (init),
+ * emitted event type (complete), system error event type, and other properties
+ * of the orchestrator contract.
+ *
+ * @example
+ * const myOrchestratorContract = new ArvoOrchestratorContract({
+ *   uri: 'my-orchestrator',
+ *   init: { type: 'init', schema: z.object({ input: z.string() }) },
+ *   complete: { type: 'complete', schema: z.object({ result: z.number() }) }
+ * });
+ * type MyOrchestratorContractType = InferArvoOrchestratorContract<typeof myOrchestratorContract>;
+ * // MyOrchestratorContractType will have properties uri, accepts, emits, systemError, etc.
+ */
+export type InferArvoOrchestratorContract<T extends ArvoOrchestratorContract<string, string, z.ZodTypeAny, string, z.ZodTypeAny>> = T extends ArvoOrchestratorContract<infer TUri, infer TInitType, infer TInit, infer TCompleteType, infer TComplete> ? {
+    /** The URI of the orchestrator contract */
+    uri: TUri;
+    /** The event type that this orchestrator contract accepts to initiate the process */
+    accepts: InferArvoEvent<ArvoEvent<InferZodSchema<TInit>, {}, TInitType>>;
+    /** The event type that this orchestrator contract emits upon completion */
+    emits: {
+        [K in TCompleteType]: InferArvoEvent<ArvoEvent<InferZodSchema<TComplete>, {}, K>>;
+    };
+    /** The system error event type for this orchestrator contract */
+    systemError: InferArvoEvent<ArvoEvent<InferZodSchema<T['systemError']['schema']>, {}, T['systemError']['type']>>;
+    /**
+     * Union type of all emittable events, including the completion event and system error.
+     * This can be used to represent all possible outcomes of the orchestration process.
+     */
+    emittableEvents: ({
+        [K in TCompleteType]: InferArvoEvent<ArvoEvent<InferZodSchema<TComplete>, {}, K>>;
+    } & {
+        [K in `sys.${TInitType}.error`]: InferArvoEvent<ArvoEvent<InferZodSchema<T['systemError']['schema']>, {}, T['systemError']['type']>>;
+    })[TCompleteType | `sys.${TInitType}.error`];
+    /** The initial event type and schema that starts the orchestration process */
+    init: InferArvoEvent<ArvoEvent<InferZodSchema<TInit>, {}, TInitType>>;
+    /** The completion event type and schema that signifies the end of the orchestration process */
+    complete: InferArvoEvent<ArvoEvent<InferZodSchema<TComplete>, {}, TCompleteType>>;
+} : never;
 export {};

package/package.json

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