arvo-core/dist/ArvoEvent/schema.js

The core Arvo package which provides application tier core primitives and contract system for building production-grade event-driven application. Provides ArvoEvent (CloudEvents-compliant), ArvoContract for type-safe service interfaces, event factories, O

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.OpenTelemetryExtensionSchema = exports.ArvoExtensionSchema = exports.ArvoDataSchema = exports.CloudEventExtensionSchema = exports.CloudEventContextSchema = exports.ArvoDataContentType = void 0;
var zod_1 = require("zod");
var utils_1 = require("../utils");
var utils_2 = require("./utils");
/**
 * The content type for Arvo data in CloudEvents.
 * This is the recommended content type for Arvo events.
 */
exports.ArvoDataContentType = 'application/cloudevents+json;charset=UTF-8;profile=arvo';
/**
 * Zod schema for validating the core properties of a CloudEvent.
 * This schema defines the structure and validation rules for the mandatory
 * and optional attributes of a CloudEvent as per the CloudEvents specification.
 */
exports.CloudEventContextSchema = zod_1.z
    .object({
    id: zod_1.z.string().min(1, 'ID must be a non-empty string').describe('Unique identifier of the event.'),
    time: zod_1.z
        .string()
        .datetime({ offset: true })
        .describe('Timestamp of when the occurrence happened. If the time of the occurrence cannot be determined then this attribute MAY be set to some other time (such as the current time) by the CloudEvents producer, however all producers for the same source MUST be consistent in this respect. In other words, either they all use the actual time of the occurrence or they all use the same algorithm to determine the value used.'),
    source: zod_1.z
        .string()
        .min(1, 'Source must be a non-empty reference of the producer of the event')
        .refine(utils_1.validateURI, 'The source must be a properly encoded URI')
        .describe((0, utils_1.cleanString)("\n      Identifies the context in which an event happened.\n      It must be a valid URI that represents the event producer.\n    ")),
    specversion: zod_1.z
        .string()
        .min(1, 'Spec version must be a non-empty string')
        .refine(function (val) { return val === '1.0'; }, "Spec version must be '1.0' for this version of the specification")
        .describe((0, utils_1.cleanString)("\n      The version of the CloudEvents specification which the event uses.\n      Must be '1.0' for this version of the specification.\n    ")),
    type: zod_1.z
        .string()
        .min(1, 'Type must be a non-empty string')
        .regex(/^[a-z0-9]+(\.[a-z0-9]+)+\.[a-z0-9]+$/, 'Type should be prefixed with a reverse-DNS name')
        .describe((0, utils_1.cleanString)("\n      Describes the type of event related to the originating occurrence.\n      Should be prefixed with a reverse-DNS name.\n    ")),
    subject: zod_1.z
        .string()
        .min(1)
        .describe((0, utils_1.cleanString)("\n      Identifies the subject of the event in the context of the event producer. \n      In case of Arvo, this MUST be Process Id.\n    "))
        .refine(utils_1.validateURI, 'The subject must be a properly encoded URI'),
    datacontenttype: zod_1.z
        .string()
        .min(1, 'Data content type must be a non-empty string')
        .refine(function (val) { return Boolean(val === null || val === void 0 ? void 0 : val.includes('application/cloudevents+json')) || Boolean(val === null || val === void 0 ? void 0 : val.includes('application/json')); }, (0, utils_1.cleanString)("\n          The content type must be a valid JSON e.g. it must contain \n          'application/cloudevents+json' or 'application/json'. \n          Arvo recommends using '".concat(exports.ArvoDataContentType, "'\n        ")))
        .default(exports.ArvoDataContentType)
        .describe('Content type of the data value. Must adhere to RFC 2046 format if present.'),
    dataschema: zod_1.z
        .string()
        .min(1, 'Must be a non-empty string if present.')
        .refine(utils_1.validateURI, 'The dataschema must be a properly encoded URI')
        .nullable()
        .describe('Identifies the schema that data adheres to'),
})
    .describe((0, utils_1.cleanString)("\n    Defines the structure and validation rules \n    for the core properties of a CloudEvent.\n  "));
/**
 * Zod schema for validating custom CloudEvent extensions.
 * This schema allows for additional custom fields in the CloudEvent,
 * following the CloudEvents specification for extension attributes.
 */
exports.CloudEventExtensionSchema = zod_1.z
    .record(zod_1.z.string().regex(/^[a-z0-9]+$/, (0, utils_1.cleanString)("\n          In compliance with CloudEvent specs, the extension keys must contain only \n          lowercase letters and numbers, with no spaces or other characters  \n        ")), zod_1.z
    .union([zod_1.z.string(), zod_1.z.boolean(), zod_1.z.number(), zod_1.z.null()])
    .describe('The CloudEvent extension can only contain a number, boolean, string or null'))
    .describe('Schema for custom CloudEvent extensions. Allows for additional custom fields in the CloudEvent.');
/**
 * Zod schema for validating the data payload of an Arvo event.
 * The data must be a JSON serializable object.
 */
exports.ArvoDataSchema = zod_1.z
    .record(zod_1.z.string(), zod_1.z.any())
    .refine(utils_2.isJSONSerializable, 'The Arvo data object must be a JSON serializable object')
    .describe('A JSON serialisable object as ArvoEvent payload data');
/**
 * Zod schema for validating Arvo-specific extensions to the CloudEvent.
 * This schema defines additional fields used by Arvo for event routing,
 * access control, and execution metrics.
 */
exports.ArvoExtensionSchema = zod_1.z
    .object({
    to: zod_1.z
        .string()
        .min(1, 'Must be a non empty string')
        .refine(utils_1.validateURI, "The 'to' must be a properly encoded URI")
        .nullable()
        .describe((0, utils_1.cleanString)("\n      This field defined the consumer machine of the event. It's value can\n      be the same as the type field or can be different. This is a metadata \n      field in event routing specifies initial recipients or topics. \n\n      For successful events, it should be determined \n      by handler definition, redirectto, or source. For errors, it should be \n      set to the error destination or event's source.\n    ")),
    accesscontrol: zod_1.z
        .string()
        .min(1, 'Must be a non empty string, if defined')
        .nullable()
        .describe((0, utils_1.cleanString)("\n      Defines the access controls for the event. This field may contain one of the following:\n      1. A UserID: A valid UUID representing a user who has access to the event.\n      2. An encrypted string: A base64-encoded encrypted string containing access control information.\n      3. Key-value pairs: A semicolon-separated list of key-value pairs, where each pair is separated by a colon.\n        Example: \"role:admin;department:finance;clearance:top-secret\"\n\n      This field is used to determine who or what can perform actions on or read the event.\n      It can be used for fine-grained access control, allowing different levels of access\n      based on user roles, departments, or other custom criteria.\n\n      If no access controls are needed, this field can be set to null.\n\n      Examples:\n      - \"123e4567-e89b-12d3-a456-426614174000\" (UserID)\n      - \"ZW5jcnlwdGVkX2FjY2Vzc19jb250cm9sX2RhdGE=\" (Encrypted string)\n      - \"role:editor;project:alpha;team:backend\" (Key-value pairs)\n    ")),
    redirectto: zod_1.z
        .string()
        .min(1, 'Must be a non empty string, if defined')
        .refine(utils_1.validateURI, "The 'redirectto' must be a properly encoded URI")
        .nullable()
        .describe((0, utils_1.cleanString)("\n      This is a metadata field for events, indicating alternative recipients \n      or destinations. It enables dynamic routing and complex workflows. \n\n      For successful events, it's set by handlers; for errors, it's \n      null to prevent automatic redirection.\n    ")),
    executionunits: zod_1.z
        .number()
        .nullable()
        .describe((0, utils_1.cleanString)("\n      This data field represents the cost associated with \n      generating this specific cloudevent. It serves as a metric \n      to track and measure the financial impact of event generation\n      within cloud-based systems or applications.\n    ")),
    parentid: zod_1.z
        .string()
        .min(1, 'ID must be a non-empty string')
        .nullable()
        .describe((0, utils_1.cleanString)("\n      The unique identifier of the event that directly triggered the creation \n      of this event within the Arvo ecosystem. When set, it establishes a \n      direct causal relationship for event lineage tracking and workflow \n      orchestration. When null, it indicates this is an initiating event \n      or was generated outside of direct event causation.\n      ")),
    domain: zod_1.z
        .string()
        .min(1, 'Domain must be non-empty string')
        .regex(/^[a-z0-9.]+$/, 'Domain must contain only lowercase letters, numbers, and dots')
        .nullable()
        .describe((0, utils_1.cleanString)("\n      Specifies the processing domain for event routing and workflow orchestration.\n      Events can be assigned to specific domains (e.g., 'external', 'analytics', 'priority')\n      to enable specialized processing flows such as human-in-the-loop operations,\n      third-party integrations, or custom handling pipelines. Each event can only\n      belong to one domain - if an event needs to be processed by multiple domains,\n      separate identical events (with different IDs) must be created for each respective\n      domain. Domain names must contain only lowercase letters, numbers, and dots.\n    ")),
})
    .describe('Schema for Arvo-specific extensions to the CloudEvent.');
/**
 * Zod schema for validating OpenTelemetry extensions to the CloudEvent.
 * This schema includes fields for distributed tracing as per the
 * OpenTelemetry specification.
 */
exports.OpenTelemetryExtensionSchema = zod_1.z
    .object({
    traceparent: zod_1.z
        .string()
        .min(1, 'Must be a non empty string, if defined')
        .nullable()
        .describe((0, utils_1.cleanString)("\n      The traceparent header is part of the OpenTelemetry specification. \n      It contains trace context information, including trace ID, parent \n      span ID, and trace flags, enabling distributed tracing across \n      services and systems.  \n    ")),
    tracestate: zod_1.z
        .string()
        .min(1, 'Must be a non empty string, if defined')
        .nullable()
        .describe((0, utils_1.cleanString)("\n      The tracestate header in OpenTelemetry is used to convey vendor-specific \n      trace information across service boundaries. It allows for custom \n      key-value pairs to be propagated alongside the traceparent header in \n      distributed tracing scenarios.  \n    ")),
})
    .describe((0, utils_1.cleanString)("\n    Distributed tracing extension as per\n    https://github.com/cloudevents/spec/blob/main/cloudevents/extensions/distributed-tracing.md  \n  "));