@vertesia/common 0.24.0-dev.202601221707

package/src/email.ts

@@ -0,0 +1,80 @@
+/**
+ * Email-related types for agent communication and routing.
+ */
+
+// ================= User Communication Channels ====================
+
+/**
+ * Email channel configuration with threading support.
+ * Used for email-based agent communication.
+ */
+export interface EmailChannel {
+    type: "email";
+    /** Email address to send agent messages to */
+    to_email: string;
+    /** Subject for the email thread (without "Re:" prefix) */
+    thread_subject?: string;
+    /** Message ID for In-Reply-To header (most recent message) */
+    in_reply_to?: string;
+    /** Chain of message IDs for References header */
+    references?: string[];
+    /** Short routing key for reply emails (8-char alphanumeric, stored in Redis) */
+    route_key?: string;
+}
+
+/**
+ * Interactive (UI chat) channel configuration.
+ * Used for real-time chat interface communication.
+ */
+export interface InteractiveChannel {
+    type: "interactive";
+}
+
+/**
+ * Union of all supported user communication channel types.
+ */
+export type UserChannel = EmailChannel | InteractiveChannel;
+
+/**
+ * Type guard for email channels
+ */
+export function isEmailChannel(channel: UserChannel): channel is EmailChannel {
+    return channel.type === "email";
+}
+
+/**
+ * Type guard for interactive channels
+ */
+export function isInteractiveChannel(channel: UserChannel): channel is InteractiveChannel {
+    return channel.type === "interactive";
+}
+
+// ================= Email Routing ====================
+
+/**
+ * Data stored in Redis for email route keys.
+ * Used to map short route keys (8-char) to workflow context for email replies.
+ *
+ * Short keys are used instead of full UUIDs in reply email addresses to avoid
+ * Gmail flagging emails as unsafe due to long random-looking strings.
+ *
+ * Pattern: r+{routeKey}@{domain} instead of r+{32-char-uuid}@{domain}
+ */
+export interface EmailRouteData {
+    /** The workflow run ID */
+    runId: string;
+    /** Account ID for quick project lookup */
+    accountId: string;
+    /** Project ID for quick config lookup */
+    projectId: string;
+    /** Email thread subject (without "Re:" prefix) */
+    threadSubject?: string;
+    /** Message ID for In-Reply-To header (last message in thread) */
+    inReplyTo?: string;
+    /** Chain of message IDs for References header */
+    references?: string[];
+    /** User's email address (recipient of agent emails, sender of replies) */
+    userEmail: string;
+    /** Inbound domain for filtering (e.g., inbound.vertesia.io) */
+    inboundDomain: string;
+}

package/src/environment.ts

@@ -0,0 +1,137 @@
+import type { AIModel, ProviderParams, TextFallbackOptions } from "@llumiverse/common";
+import { ProviderList, Providers } from "@llumiverse/common";
+
+// Virtual providers from studio
+export enum CustomProviders {
+    virtual_lb = 'virtual_lb',
+    virtual_mediator = 'virtual_mediator',
+    test = 'test'
+}
+
+export type SupportedProviders = Providers | CustomProviders;
+
+export const SupportedProviders = {
+    ...Providers,
+    ...CustomProviders
+} as const;
+
+export interface SupportedProviderParams extends Omit<ProviderParams, 'id'> {
+    id: SupportedProviders;
+}
+
+export const CustomProvidersList: Record<CustomProviders, SupportedProviderParams> = {
+    virtual_lb:
+    {
+        id: CustomProviders.virtual_lb,
+        name: "Virtual - Load Balancer",
+        requiresApiKey: false,
+        requiresEndpointUrl: false,
+        supportSearch: false,
+    },
+    virtual_mediator:
+    {
+        id: CustomProviders.virtual_mediator,
+        name: "Virtual - Mediator",
+        requiresApiKey: false,
+        requiresEndpointUrl: false,
+        supportSearch: false,
+    },
+    test: {
+        id: CustomProviders.test,
+        name: "Test LLM",
+        requiresApiKey: false,
+        requiresEndpointUrl: false,
+        supportSearch: false,
+    },
+};
+
+export const SupportedProvidersList: Record<SupportedProviders, SupportedProviderParams> = {
+    ...ProviderList,
+    ...CustomProvidersList
+} as const;
+
+
+export interface VirtualEnvEntry {
+    model: string;
+}
+
+/**
+ * Custom configuration for virtual environments
+ **/
+export interface LoadBalancingEnvConfig {
+    entries?: LoadBalancingEnvEntryConfig[];
+    balance_if_failed?: boolean;
+}
+
+export interface LoadBalancingEnvEntryConfig extends VirtualEnvEntry {
+    weight: number;
+}
+
+export interface MediatorEnvConfig {
+    entries?: VirtualEnvEntry[];
+    max_concurrent_requests?: number;
+    // the model used to evaluate the responses. If not specified all entries will mediates the response
+    // and the best response will be picked
+    mediators?: VirtualEnvEntry[];
+    model_options?: TextFallbackOptions;
+}
+
+export interface ExecutionEnvironment {
+    id: string;
+    name: string;
+    provider: SupportedProviders;
+    description?: string;
+    endpoint_url?: string;
+    default_model?: string;
+    enabled_models?: AIModel[];
+    apiKey?: string;
+    config?: any;
+    account: string;
+    allowed_projects?: string[];
+    created_by: string,
+    updated_by: string,
+    created_at: string;
+    updated_at: string;
+}
+
+export interface ExecutionEnvironmentRef {
+    id: string;
+    name: string;
+    provider: SupportedProviders;
+    enabled_models?: AIModel[];
+    default_model?: string;
+    endpoint_url?: string;
+    allowed_projects?: string[];
+    account: string;
+    created_by: string;
+    updated_by: string;
+    created_at: string;
+    updated_at: string;
+}
+
+export const ExecutionEnvironmentRefPopulate = "id name provider enabled_models default_model endpoint_url allowed_projects account created_at updated_at";
+
+export interface ExecutionEnvironmentCreatePayload extends Omit<ExecutionEnvironment, 'id' | 'account' | 'created_at' | 'updated_at' | 'created_by' | 'updated_by' | 'project'> { }
+export interface ExecutionEnvironmentUpdatePayload extends Partial<Omit<ExecutionEnvironment, 'id' | 'account' | 'created_at' | 'updated_at' | 'created_by' | 'updated_by'>> { }
+
+export interface MigrateInteractionsPayload {
+    /**
+     * The new environment ID to set in the Interactions
+     */
+    new_env_id: string;
+    /**
+     * The new model ID to set in the Interactions
+     */
+    new_model_id: string;
+    /**
+     * The list of Interaction IDs to update.
+     *
+     * The Interactions must be in draft status.
+     */
+    interaction_ids: string[];
+}
+
+export interface MigrateInteractionsResult {
+    matched_count: number;
+    modified_count: number;
+}

package/src/facets.ts

@@ -0,0 +1,44 @@
+
+// this is the mongo definition of a facet. see https://www.mongodb.com/docs/atlas/atlas-search/facet/
+export interface StringFacet {
+    type: "string",
+    path: string,
+    numBuckets?: number,
+}
+
+export interface NumericFacet {
+    type: "number",
+    path: string,
+    boundaries: number[],
+    default?: string
+}
+
+export interface DateFacet<T extends (Date | string) = string> {
+    type: "date",
+    path: string,
+    boundaries: T[], // array of dates
+    default?: string
+}
+
+export type Facet<DateT extends (Date | string) = string> = StringFacet | NumericFacet | DateFacet<DateT>;
+
+
+export interface FacetSpec {
+    name: string;
+    field: string;
+}
+
+export interface FacetBucket {
+    _id: string,
+    count: number,
+}
+
+export interface FacetNameBucket {
+    name: string,
+    _id: string,
+    count: number,
+}
+
+export interface FacetResult {
+    buckets: FacetBucket[]
+}

package/src/group.ts

@@ -0,0 +1,26 @@
+import { UserRef } from "./user.js";
+
+
+export interface UserGroup {
+    id: string;
+    account: string;
+    name: string;
+    description?: string;
+    tags: string[];
+    created_at: Date;
+    updated_at: Date;
+    created_by?: string;
+    updated_by?: string;
+}
+
+export interface PopulatesUserGroup extends UserGroup {
+    members: UserRef[];
+}
+
+export interface UserGroupRef {
+    id: string;
+    name: string;
+    tags?: string[];
+}
+
+export const UserGroupRefPopulate = 'id name tags description';

package/src/index.ts

@@ -0,0 +1,40 @@
+export * from './access-control.js';
+export * from './analytics.js';
+export * from './apikey.js';
+export * from './apps.js';
+export * from './ask-user.js';
+export * from './channels.js';
+export * from './common.js';
+export * from './data-platform.js';
+export * from './environment.js';
+export * from "./facets.js";
+export * from './group.js';
+export * from './integrations.js';
+export * from './interaction.js';
+export * from './pending-asks.js';
+export * from './json-schema.js';
+export * from './json.js';
+export * from './meters.js';
+export * from './model_utility.js';
+export * from './payload.js';
+export * from "./Progress.js";
+export * from './project.js';
+export * from './prompt.js';
+export * from './query.js';
+export * from './rate-limiter.js';
+export * from './refs.js';
+export * from './runs.js';
+export * from './skill.js';
+export * from "./store/index.js";
+export * from './sts-token-types.js';
+export * from './tenant.js';
+export * from './tool-execution.js';
+export * from "./training.js";
+export * from './transient-tokens.js';
+export * from './user.js';
+export * from './utils/auth.js';
+export * from './utils/schemas.js';
+export type * from './utils/type-helpers.js';
+export * from './versions.js';
+export * from './workflow-analytics.js';
+

package/src/integrations.ts

@@ -0,0 +1,72 @@
+
+
+export interface IntegrationConfigurationBase {
+    enabled: boolean;
+}
+
+export interface GladiaConfiguration extends IntegrationConfigurationBase {
+    api_key: string;
+    url?: string;
+}
+
+
+export interface GithubConfiguration extends IntegrationConfigurationBase {
+    allowed_repositories: string[];
+}
+
+export interface AwsConfiguration extends IntegrationConfigurationBase {
+    s3_role_arn: string;
+}
+
+export interface MagicPdfConfiguration extends IntegrationConfigurationBase {
+    // No additional configuration
+    default_features?: string[];
+    default_zones?: string[];
+}
+
+export interface SerperConfiguration extends IntegrationConfigurationBase {
+    api_key: string;
+    url?: string;
+}
+
+export interface ResendConfiguration extends IntegrationConfigurationBase {
+    /** Resend API key for sending emails */
+    api_key: string;
+    /** Domain for email (both sending and receiving). Must be verified in Resend. */
+    email_domain: string;
+    /** Default display name for outgoing emails (e.g., "Vertesia - Project Name") */
+    default_from_name?: string;
+    /** Webhook secret for validating inbound email webhooks (required for receiving emails) */
+    webhook_secret: string;
+    /** Domains allowed to send emails TO start agents (for inbound validation) */
+    allowed_sender_domains?: string[];
+    /** Require sender to have project access to start agents via email (default: true) */
+    require_project_access?: boolean;
+    /** Require DKIM/SPF authentication to pass for inbound emails (default: true) */
+    require_email_auth?: boolean;
+}
+
+/**
+ * Configuration for ask_user webhook notifications.
+ * Sends webhooks when agents call ask_user and when users respond.
+ */
+export interface AskUserWebhookConfiguration extends IntegrationConfigurationBase {
+    /** Webhook URL to receive ask_user events */
+    webhook_url: string;
+    /** Secret for signing webhook payloads (HMAC-SHA256) */
+    webhook_secret?: string;
+    /** Which events to send: ['requested', 'resolved'] or subset (default: both) */
+    events?: ('requested' | 'resolved')[];
+    /** Custom headers to include in webhook requests */
+    custom_headers?: Record<string, string>;
+}
+
+export enum SupportedIntegrations {
+    gladia = "gladia",
+    github = "github",
+    aws = "aws",
+    magic_pdf = "magic_pdf",
+    serper = "serper",
+    resend = "resend",
+    ask_user_webhook = "ask_user_webhook",
+}