@vertesia/common 0.81.1 → 1.0.0-dev.20260203.130115Z

package/src/store/schedule.ts

@@ -0,0 +1,238 @@
+/**
+ * Agent Schedule Types
+ *
+ * Defines types for scheduling agents to run on a recurring basis using cron expressions.
+ * Schedules are stored in MongoDB with execution handled by Temporal.
+ */
+
+/**
+ * Represents a scheduled agent execution configuration.
+ */
+export interface AgentSchedule {
+    /** Unique identifier for the schedule */
+    id: string;
+
+    /** Human-readable name for the schedule */
+    name: string;
+
+    /** Optional description of what the schedule does */
+    description?: string;
+
+    /** Project ID this schedule belongs to */
+    project: string;
+
+    /** Account ID this schedule belongs to */
+    account: string;
+
+    /** Interaction ID or endpoint name to execute (e.g., "MyAgent" or ObjectId) */
+    interaction: string;
+
+    /** Cached interaction name for display purposes */
+    interaction_name?: string;
+
+    /**
+     * Cron expression defining when to run.
+     * Standard 5-field format: minute hour day-of-month month day-of-week
+     * Examples:
+     * - "0 0 * * MON" - Every Monday at midnight
+     * - "0 9 * * *" - Daily at 9am
+     * - "0 * * * *" - Every hour
+     */
+    cron_expression: string;
+
+    /** Timezone for the cron expression (defaults to "UTC") */
+    timezone?: string;
+
+    /** Variables to pass to the agent workflow */
+    vars?: Record<string, any>;
+
+    /** Optional task queue override for the workflow */
+    task_queue?: string;
+
+    /** Whether the schedule is enabled (can be paused/resumed) */
+    enabled: boolean;
+
+    /** Temporal schedule ID once created (format: schedule:{accountId}:{projectId}:{scheduleId}) */
+    temporal_schedule_id?: string;
+
+    /** User or service that created this schedule */
+    created_by: string;
+
+    /** User or service that last updated this schedule */
+    updated_by?: string;
+
+    /** Timestamp when the schedule was created */
+    created_at: Date;
+
+    /** Timestamp when the schedule was last updated */
+    updated_at: Date;
+
+    /** Timestamp of the last successful execution */
+    last_run_at?: Date;
+
+    /** Timestamp of the next scheduled execution */
+    next_run_at?: Date;
+
+    /** Total number of times this schedule has executed */
+    run_count?: number;
+}
+
+/**
+ * Payload for creating a new schedule.
+ */
+export interface CreateSchedulePayload {
+    /** Human-readable name for the schedule */
+    name: string;
+
+    /** Optional description of what the schedule does */
+    description?: string;
+
+    /** Interaction ID or endpoint name to execute */
+    interaction: string;
+
+    /**
+     * Cron expression defining when to run.
+     * Standard 5-field format: minute hour day-of-month month day-of-week
+     */
+    cron_expression: string;
+
+    /** Timezone for the cron expression (defaults to "UTC") */
+    timezone?: string;
+
+    /** Variables to pass to the agent workflow */
+    vars?: Record<string, any>;
+
+    /** Optional task queue override */
+    task_queue?: string;
+
+    /** Whether the schedule should be enabled immediately (defaults to true) */
+    enabled?: boolean;
+}
+
+/**
+ * Payload for updating an existing schedule.
+ */
+export interface UpdateSchedulePayload {
+    /** Updated name */
+    name?: string;
+
+    /** Updated description */
+    description?: string;
+
+    /** Updated cron expression */
+    cron_expression?: string;
+
+    /** Updated timezone */
+    timezone?: string;
+
+    /** Updated variables */
+    vars?: Record<string, any>;
+
+    /** Updated task queue */
+    task_queue?: string;
+
+    /** Enable or disable the schedule */
+    enabled?: boolean;
+}
+
+/**
+ * Summary information for listing schedules.
+ */
+export interface ScheduleListItem {
+    id: string;
+    name: string;
+    description?: string;
+    interaction: string;
+    interaction_name?: string;
+    cron_expression: string;
+    timezone?: string;
+    enabled: boolean;
+    last_run_at?: Date;
+    next_run_at?: Date;
+    run_count?: number;
+    created_by: string;
+    updated_at: Date;
+}
+
+/**
+ * Information about a schedule's recent and upcoming runs.
+ */
+export interface ScheduleRunInfo {
+    /** The schedule ID */
+    schedule_id: string;
+
+    /** Recent workflow executions from this schedule */
+    recent_runs: Array<{
+        workflow_id: string;
+        run_id: string;
+        started_at: Date;
+        status: string;
+    }>;
+
+    /** Upcoming scheduled execution times */
+    upcoming_runs: Date[];
+}
+
+/**
+ * Extended schedule information including Temporal execution details.
+ */
+export interface AgentScheduleWithTemporalInfo extends AgentSchedule {
+    /** Information from Temporal about the schedule execution */
+    temporal_info?: {
+        /** Number of actions (workflow starts) executed */
+        num_actions_taken: number;
+
+        /** Number of actions missed due to catchup window */
+        num_actions_missed: number;
+
+        /** Number of actions skipped due to overlap policy */
+        num_actions_skipped: number;
+
+        /** Currently running workflows started by this schedule */
+        running_actions: Array<{
+            workflow_id: string;
+            run_id: string;
+        }>;
+
+        /** Recent actions taken by the schedule */
+        recent_actions: Array<{
+            scheduled_at: Date;
+            taken_at: Date;
+            workflow_id: string;
+            run_id: string;
+        }>;
+
+        /** Next scheduled action times */
+        next_action_times: Date[];
+
+        /** Whether the schedule is currently paused in Temporal */
+        paused: boolean;
+
+        /** Optional note about why the schedule is paused */
+        pause_note?: string;
+    };
+}
+
+/**
+ * Common cron expression presets for UI convenience.
+ */
+export const CRON_PRESETS = {
+    EVERY_HOUR: '0 * * * *',
+    EVERY_DAY_MIDNIGHT: '0 0 * * *',
+    EVERY_DAY_9AM: '0 9 * * *',
+    EVERY_MONDAY_MIDNIGHT: '0 0 * * MON',
+    EVERY_WEEKDAY_9AM: '0 9 * * MON-FRI',
+    FIRST_OF_MONTH: '0 0 1 * *',
+} as const;
+
+/**
+ * Human-readable descriptions for cron presets.
+ */
+export const CRON_PRESET_LABELS: Record<keyof typeof CRON_PRESETS, string> = {
+    EVERY_HOUR: 'Every hour',
+    EVERY_DAY_MIDNIGHT: 'Daily at midnight',
+    EVERY_DAY_9AM: 'Daily at 9:00 AM',
+    EVERY_MONDAY_MIDNIGHT: 'Every Monday at midnight',
+    EVERY_WEEKDAY_9AM: 'Weekdays at 9:00 AM',
+    FIRST_OF_MONTH: 'First day of month at midnight',
+};

package/src/store/signals.ts

@@ -2,4 +2,24 @@ export interface UserInputSignal {
     message: string;
     metadata?: Record<string, any>;
     auth_token?: string;
+    /**
+     * Email attachments to be processed as store objects.
+     * These will be downloaded, uploaded to store, and processed for text extraction
+     * before the conversation continues.
+     */
+    attachments?: EmailAttachment[];
+}
+
+/**
+ * Email attachment metadata for processing in conversation workflows.
+ */
+export interface EmailAttachment {
+    /** Original filename */
+    filename: string;
+    /** MIME content type */
+    content_type: string;
+    /** Size in bytes */
+    size: number;
+    /** Resend download URL (temporary, expires) */
+    download_url: string;
 }

package/src/store/store.ts

@@ -8,6 +8,17 @@ export enum ContentObjectApiHeaders {
     PROCESSING_PRIORITY = 'x-processing-priority',
     CREATE_REVISION = 'x-create-revision',
     REVISION_LABEL = 'x-revision-label',
+    /** When set to 'true', prevents this update from triggering workflow rules */
+    SUPPRESS_WORKFLOWS = 'x-suppress-workflows',
+}
+
+/**
+ * Headers for Data Store API calls.
+ * Used for Cloud Run session affinity to route requests to the same instance.
+ */
+export enum DataStoreApiHeaders {
+    /** Data store ID for session affinity - routes requests for same store to same instance */
+    DATA_STORE_ID = 'x-data-store-id',
 }
 
 export enum ContentObjectStatus {
@@ -342,6 +353,7 @@ export interface ContentObjectTypeItem extends BaseObject {
      */
     strict_mode?: boolean;
 }
+export type InCodeTypeDefinition = Pick<ContentObjectTypeItem, 'name' | 'description' | 'tags' | 'object_schema' | 'table_layout' | 'is_chunkable' | 'strict_mode'>;
 
 export interface CreateContentObjectTypePayload
     extends Omit<
@@ -421,6 +433,118 @@ export interface GetRenditionResponse {
     workflow_run_id?: string;
 }
 
+// ============================================================================
+// Rendition Format Compatibility Utilities
+// ============================================================================
+
+export type RenditionFormat = ImageRenditionFormat | MarkdownRenditionFormat;
+
+/**
+ * Matrix of supported content type → format conversions.
+ * This is the authoritative source of truth for what renditions can be generated.
+ *
+ * Key patterns:
+ * - Exact MIME types (e.g., 'application/pdf')
+ * - Wildcard patterns (e.g., 'image/*', 'video/*')
+ */
+const RENDITION_COMPATIBILITY: Record<string, RenditionFormat[]> = {
+    // Image formats can generate: jpeg, png, webp
+    'image/*': [ImageRenditionFormat.jpeg, ImageRenditionFormat.png, ImageRenditionFormat.webp],
+    // Video formats can generate: jpeg, png (thumbnails)
+    'video/*': [ImageRenditionFormat.jpeg, ImageRenditionFormat.png],
+    // PDF can generate: jpeg, png, webp (page images)
+    'application/pdf': [ImageRenditionFormat.jpeg, ImageRenditionFormat.png, ImageRenditionFormat.webp],
+    // Markdown can generate: pdf, docx (NOT jpeg/png)
+    'text/markdown': [MarkdownRenditionFormat.pdf, MarkdownRenditionFormat.docx],
+    // Plain text can generate: docx
+    'text/plain': [MarkdownRenditionFormat.docx],
+    // Office documents can generate: pdf
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document': [MarkdownRenditionFormat.pdf],
+    'application/msword': [MarkdownRenditionFormat.pdf],
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation': [MarkdownRenditionFormat.pdf],
+    'application/vnd.ms-powerpoint': [MarkdownRenditionFormat.pdf],
+};
+
+/**
+ * Check if a specific rendition format can be generated from a content type.
+ *
+ * @param contentType - The MIME type of the source content (e.g., 'image/png', 'text/markdown')
+ * @param format - The desired rendition format (e.g., ImageRenditionFormat.jpeg)
+ * @returns true if the format can be generated from the content type
+ *
+ * @example
+ * canGenerateRendition('image/png', ImageRenditionFormat.jpeg) // true
+ * canGenerateRendition('text/markdown', ImageRenditionFormat.jpeg) // false
+ * canGenerateRendition('text/markdown', MarkdownRenditionFormat.pdf) // true
+ */
+export function canGenerateRendition(contentType: string | undefined, format: RenditionFormat | string): boolean {
+    if (!contentType) return false;
+
+    const formatStr = typeof format === 'string' ? format : format;
+
+    // Check exact match first
+    const exactMatch = RENDITION_COMPATIBILITY[contentType];
+    if (exactMatch && exactMatch.some(f => f === formatStr)) {
+        return true;
+    }
+
+    // Check wildcard patterns (e.g., 'image/*', 'video/*')
+    const [category] = contentType.split('/');
+    const wildcardKey = `${category}/*`;
+    const wildcardMatch = RENDITION_COMPATIBILITY[wildcardKey];
+    if (wildcardMatch && wildcardMatch.some(f => f === formatStr)) {
+        return true;
+    }
+
+    return false;
+}
+
+/**
+ * Get the list of rendition formats supported for a given content type.
+ *
+ * @param contentType - The MIME type of the source content
+ * @returns Array of supported rendition formats, or empty array if none
+ *
+ * @example
+ * getSupportedRenditionFormats('image/png') // [jpeg, png, webp]
+ * getSupportedRenditionFormats('text/markdown') // [pdf, docx]
+ * getSupportedRenditionFormats('text/html') // []
+ */
+export function getSupportedRenditionFormats(contentType: string | undefined): RenditionFormat[] {
+    if (!contentType) return [];
+
+    // Check exact match first
+    if (RENDITION_COMPATIBILITY[contentType]) {
+        return [...RENDITION_COMPATIBILITY[contentType]];
+    }
+
+    // Check wildcard patterns
+    const [category] = contentType.split('/');
+    const wildcardKey = `${category}/*`;
+    const wildcardMatch = RENDITION_COMPATIBILITY[wildcardKey];
+    if (wildcardMatch) {
+        return [...wildcardMatch];
+    }
+
+    return [];
+}
+
+/**
+ * Check if a content type supports visual (image) renditions.
+ * This is useful for determining if a document can have thumbnails/previews.
+ *
+ * @param contentType - The MIME type of the source content
+ * @returns true if the content type can generate JPEG renditions
+ *
+ * @example
+ * supportsVisualRendition('image/png') // true
+ * supportsVisualRendition('application/pdf') // true
+ * supportsVisualRendition('text/markdown') // false
+ */
+export function supportsVisualRendition(contentType: string | undefined): boolean {
+    return canGenerateRendition(contentType, ImageRenditionFormat.jpeg);
+}
+
 export interface GetUploadUrlPayload {
     name: string;
     id?: string;