@elevasis/core 0.1.0

package/src/execution/scheduler/api-schemas.ts

@@ -0,0 +1,296 @@
+import { z } from 'zod'
+import { ResourceTypeSchema, OriginResourceTypeSchema } from '../../platform/utils/validation'
+import { TaskScheduleConfigSchema } from './schemas'
+
+/**
+ * API validation schemas for task scheduler endpoints.
+ * Separate from domain schemas (schemas.ts) to enforce validation at API boundary.
+ *
+ * Note: Domain schemas in schemas.ts define business logic validation.
+ * API schemas add transport-layer concerns (query params, path params, response validation).
+ *
+ * Schedule config schemas (TaskScheduleConfigSchema, RecurringScheduleConfigSchema, etc.)
+ * are defined in schemas.ts and exported from there. This file only defines API-specific
+ * request/response schemas.
+ */
+
+// ============================================================================
+// REQUEST SCHEMAS (NEW UNIFIED SYSTEM)
+// ============================================================================
+
+/**
+ * POST /api/task-scheduler/schedules - Create a new schedule
+ *
+ * Security:
+ * - organizationId extracted from JWT auth context (not in request body)
+ * - Strict mode prevents unknown fields (prevents mass assignment)
+ * - UUID validation on optional origin fields
+ * - Name/description length limited to prevent abuse
+ */
+export const CreateScheduleRequestSchema = z.object({
+  name: z.string().min(1, 'Name is required').max(255),
+  description: z.string().max(1000).optional(),
+
+  target: z.object({
+    resourceType: ResourceTypeSchema,
+    resourceId: z.string().min(1, 'Resource ID is required').max(255)
+  }),
+
+  scheduleConfig: TaskScheduleConfigSchema,
+
+  maxRetries: z.number().int().min(0).max(10).optional(),
+  idempotencyKey: z.string().max(255).optional(),
+
+  // Origin tracking (optional)
+  originExecutionId: z.string().uuid().optional(),
+  originResourceType: OriginResourceTypeSchema.optional(),
+  originResourceId: z.string().max(255).optional()
+})
+
+/**
+ * GET /api/task-scheduler/schedules - List schedules with filters
+ *
+ * Security:
+ * - Enum validation restricts to valid status/resource type values
+ * - z.coerce handles string query params from URL
+ * - Limit capped at 100 to prevent memory exhaustion
+ */
+export const ListSchedulesQuerySchema = z.object({
+  status: z.enum(['active', 'paused', 'completed', 'cancelled']).optional(),
+  targetResourceType: ResourceTypeSchema.optional(),
+  targetResourceId: z.string().optional(),
+  limit: z.coerce.number().int().min(1).max(100).optional().default(50),
+  offset: z.coerce.number().int().min(0).optional().default(0)
+})
+
+/**
+ * GET /api/task-scheduler/schedules/:id - Get single schedule
+ *
+ * Security:
+ * - UUID validation prevents SQL injection via path params
+ */
+export const GetScheduleParamsSchema = z.object({
+  id: z.string().uuid('Invalid schedule ID')
+})
+
+/**
+ * PATCH /api/task-scheduler/schedules/:id/anchor - Update anchor for relative schedules
+ *
+ * Security:
+ * - Datetime validation ensures valid ISO 8601 format
+ * - Only applicable to relative schedules (checked at service layer)
+ */
+export const UpdateAnchorRequestSchema = z.object({
+  anchorAt: z.string().datetime({ message: 'Invalid anchor datetime format' })
+})
+
+/**
+ * PATCH /api/task-scheduler/schedules/:id - Update schedule fields
+ *
+ * Security:
+ * - Strict mode prevents unknown fields (no mass assignment)
+ * - At least one field must be provided
+ * - Schedule config re-validated with discriminated union
+ * - Only active/paused schedules can be updated (checked at service layer)
+ */
+export const UpdateScheduleRequestSchema = z
+  .object({
+    name: z.string().min(1, 'Name cannot be empty').max(255).optional(),
+    description: z.string().max(1000).nullable().optional(),
+    scheduleConfig: TaskScheduleConfigSchema.optional(),
+    maxRetries: z.number().int().min(0).max(10).optional()
+  })
+  .strict()
+  .refine(
+    (data) =>
+      data.name !== undefined ||
+      data.description !== undefined ||
+      data.scheduleConfig !== undefined ||
+      data.maxRetries !== undefined,
+    { message: 'At least one field (name, description, scheduleConfig, maxRetries) must be provided' }
+  )
+
+/**
+ * POST /api/task-scheduler/process-batch - Internal webhook from pg_cron
+ * Note: This endpoint is called by the database, not by users
+ *
+ * Security:
+ * - No authentication (internal database trigger only, not exposed externally)
+ * - Validates database row structure (snake_case columns)
+ * - Batch size limited to 1-100 schedules
+ * - UUID validation on ID fields
+ */
+export const ProcessSchedulesBatchRequestSchema = z.object({
+  schedules: z
+    .array(
+      z.object({
+        // Required identifiers
+        id: z.string().uuid(),
+        organization_id: z.string().uuid(),
+        name: z.string(),
+
+        // Target
+        target_resource_type: z.string(),
+        target_resource_id: z.string(),
+
+        // Schedule definition
+        schedule_config: z.record(z.string(), z.unknown()), // JSONB from database
+        current_step: z.number().int(),
+        status: z.string(),
+
+        // Scheduling state
+        next_run_at: z.string().nullable(),
+        last_run_at: z.string().nullable(),
+        last_execution_id: z.string().uuid().nullable(),
+
+        // Config
+        max_retries: z.number().int(),
+        retry_count: z.number().int(),
+        idempotency_key: z.string().nullable(),
+        description: z.string().nullable(),
+
+        // Origin tracking
+        origin_execution_id: z.string().uuid().nullable(),
+        origin_resource_type: z.string().nullable(),
+        origin_resource_id: z.string().nullable(),
+
+        // Timestamps (PostgreSQL format with microseconds)
+        created_at: z.string(),
+        updated_at: z.string()
+      })
+    )
+    .min(1)
+    .max(100)
+})
+
+/**
+ * GET /api/task-scheduler/schedules/:id/executions - Get execution history
+ *
+ * Security:
+ * - UUID validation on schedule ID path param
+ */
+export const GetExecutionHistoryParamsSchema = z.object({
+  id: z.string().uuid('Invalid schedule ID')
+})
+
+/**
+ * Query parameters for execution history pagination
+ */
+export const GetExecutionHistoryQuerySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(100).optional().default(20),
+  offset: z.coerce.number().int().min(0).optional().default(0)
+})
+
+// ============================================================================
+// RESPONSE SCHEMAS (NEW UNIFIED SYSTEM)
+// ============================================================================
+
+/**
+ * Single schedule response.
+ * Returned by GET /schedules/:id and POST /schedules
+ */
+export const ScheduleResponseSchema = z.object({
+  id: z.string().uuid(),
+  organizationId: z.string().uuid(),
+  name: z.string(),
+  description: z.string().nullable(),
+
+  target: z.object({
+    resourceType: ResourceTypeSchema,
+    resourceId: z.string()
+  }),
+
+  scheduleConfig: TaskScheduleConfigSchema,
+
+  nextRunAt: z.string().datetime().nullable(),
+  currentStep: z.number().int(),
+  status: z.enum(['active', 'paused', 'completed', 'cancelled']),
+
+  lastRunAt: z.string().datetime().nullable(),
+  lastExecutionId: z.string().uuid().nullable(),
+
+  maxRetries: z.number().int(),
+  idempotencyKey: z.string().nullable(),
+
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime()
+})
+
+/**
+ * List schedules response.
+ * Returned by GET /schedules with pagination metadata.
+ */
+export const ListSchedulesResponseSchema = z.object({
+  schedules: z.array(ScheduleResponseSchema),
+  total: z.number().int(),
+  limit: z.number().int(),
+  offset: z.number().int()
+})
+
+/**
+ * Execution history item.
+ * Represents a single execution triggered by a schedule.
+ */
+export const ExecutionHistoryItemSchema = z.object({
+  id: z.string().uuid(),
+  createdAt: z.string().datetime(),
+  status: z.enum(['running', 'completed', 'failed', 'cancelled']),
+  step: z.number().int().nullable(),
+  itemLabel: z.string().nullable(),
+  duration: z.number().nullable(), // milliseconds
+  error: z.string().nullable()
+})
+
+/**
+ * Execution history response.
+ * Returned by GET /schedules/:id/executions with pagination.
+ */
+export const ExecutionHistoryResponseSchema = z.object({
+  executions: z.array(ExecutionHistoryItemSchema),
+  total: z.number().int(),
+  limit: z.number().int(),
+  offset: z.number().int()
+})
+
+/**
+ * Process batch response (internal).
+ * Returned by POST /process-batch for monitoring/debugging.
+ */
+export const ProcessBatchResponseSchema = z.object({
+  processed: z.number().int(),
+  succeeded: z.number().int(),
+  failed: z.number().int(),
+  errors: z
+    .array(
+      z.object({
+        scheduleId: z.string().uuid(),
+        error: z.string()
+      })
+    )
+    .optional()
+})
+
+// ============================================================================
+// TYPE EXPORTS (NEW UNIFIED SYSTEM)
+// ============================================================================
+
+// Note: Schedule config types (RecurringScheduleConfig, RelativeScheduleConfig,
+// AbsoluteScheduleConfig, TaskScheduleConfig, RelativeScheduleItem, AbsoluteScheduleItem)
+// are defined in types.ts. Import them from there or from the package index.
+
+// Request types
+export type CreateScheduleRequest = z.infer<typeof CreateScheduleRequestSchema>
+export type ListSchedulesQuery = z.infer<typeof ListSchedulesQuerySchema>
+export type GetScheduleParams = z.infer<typeof GetScheduleParamsSchema>
+export type UpdateAnchorRequest = z.infer<typeof UpdateAnchorRequestSchema>
+export type UpdateScheduleRequest = z.infer<typeof UpdateScheduleRequestSchema>
+export type ProcessSchedulesBatchRequest = z.infer<typeof ProcessSchedulesBatchRequestSchema>
+export type GetExecutionHistoryParams = z.infer<typeof GetExecutionHistoryParamsSchema>
+export type GetExecutionHistoryQuery = z.infer<typeof GetExecutionHistoryQuerySchema>
+
+// Response types
+export type ScheduleResponse = z.infer<typeof ScheduleResponseSchema>
+export type ListSchedulesResponse = z.infer<typeof ListSchedulesResponseSchema>
+export type ExecutionHistoryItem = z.infer<typeof ExecutionHistoryItemSchema>
+export type ExecutionHistoryResponse = z.infer<typeof ExecutionHistoryResponseSchema>
+export type ProcessBatchResponse = z.infer<typeof ProcessBatchResponseSchema>

package/src/execution/scheduler/index.ts

@@ -0,0 +1,50 @@
+// Export all types from types.ts (domain interfaces)
+// These are the canonical TypeScript interfaces for schedule config types
+export * from './types'
+
+// Export schemas from schemas.ts (domain-level Zod schemas)
+// Note: Type aliases from schemas.ts (e.g., RecurringScheduleConfigInput) are suffixed
+// with "Input" to distinguish from the interface types in types.ts
+export * from './schemas'
+
+// Export API schemas from api-schemas.ts
+// Only export schemas and types that are unique to api-schemas.ts
+// Schedule config schemas are re-exported from schemas.ts, so we skip those
+export {
+  // Request schemas
+  CreateScheduleRequestSchema,
+  ListSchedulesQuerySchema,
+  GetScheduleParamsSchema,
+  UpdateAnchorRequestSchema,
+  UpdateScheduleRequestSchema,
+  ProcessSchedulesBatchRequestSchema,
+  GetExecutionHistoryParamsSchema,
+  GetExecutionHistoryQuerySchema,
+
+  // Response schemas
+  ScheduleResponseSchema,
+  ListSchedulesResponseSchema,
+  ExecutionHistoryItemSchema,
+  ExecutionHistoryResponseSchema,
+  ProcessBatchResponseSchema,
+
+  // Request types
+  type CreateScheduleRequest,
+  type ListSchedulesQuery,
+  type GetScheduleParams,
+  type UpdateAnchorRequest,
+  type UpdateScheduleRequest,
+  type ProcessSchedulesBatchRequest,
+  type GetExecutionHistoryParams,
+  type GetExecutionHistoryQuery,
+
+  // Response types
+  type ScheduleResponse,
+  type ListSchedulesResponse,
+  type ExecutionHistoryItem,
+  type ExecutionHistoryResponse,
+  type ProcessBatchResponse
+} from './api-schemas'
+
+// Export utilities
+export * from './utils'

package/src/execution/scheduler/schemas.ts

@@ -0,0 +1,264 @@
+import { z } from 'zod'
+import { ExecutionTargetSchema, OriginTrackingSchema } from '../core/api-schemas'
+import {
+  UuidSchema,
+  NonEmptyStringSchema,
+  ResourceTypeSchema,
+  OriginResourceTypeSchema
+} from '../../platform/utils/validation'
+
+// Note: ExecutionTargetSchema and OriginTrackingSchema are now imported from api-schemas.ts
+// This ensures consistent validation across all execution endpoints
+
+// Re-export for backward compatibility
+export { ExecutionTargetSchema, OriginTrackingSchema }
+
+// ============================================================================
+// SCHEDULE ITEM SCHEMAS
+// Note: These are canonical domain schemas. API-level schemas with additional
+// validation constraints are in api-schemas.ts
+// ============================================================================
+
+/**
+ * Relative schedule item validation
+ * Used for schedule items with offsets from an anchor date
+ *
+ * Offset format: [+/-][number][unit]
+ * - Units: d (days), h (hours), m (minutes)
+ * - Examples: '-7d', '+3d', '-2h', '+30m'
+ *
+ * @example
+ * ```typescript
+ * {
+ *   offset: '-7d',  // 7 days before anchor
+ *   payload: { reminder: 'one week before' },
+ *   label: 'Week before reminder'
+ * }
+ * ```
+ */
+export const RelativeScheduleItemSchema = z.object({
+  offset: z.string().regex(/^[+-]\d+[dhm]$/, 'Invalid offset format. Use +3d, -2h, +30m, etc.'),
+  payload: z.record(z.string(), z.unknown()),
+  label: z.string().optional()
+})
+
+/**
+ * Absolute schedule item validation
+ * Used for schedule items with fixed datetime
+ *
+ * @example
+ * ```typescript
+ * {
+ *   runAt: '2025-03-15T09:00:00Z',
+ *   payload: { event: 'launch' },
+ *   label: 'Product launch notification'
+ * }
+ * ```
+ */
+export const AbsoluteScheduleItemSchema = z.object({
+  runAt: z.string().datetime({ message: 'Invalid datetime format' }),
+  payload: z.record(z.string(), z.unknown()),
+  label: z.string().optional()
+})
+
+// ============================================================================
+// SCHEDULE CONFIG SCHEMAS (DISCRIMINATED UNION)
+// ============================================================================
+
+/**
+ * Recurring schedule configuration
+ * Supports cron expressions or predefined intervals with timezone
+ *
+ * Security:
+ * - timezone validated as string (IANA timezone validation at service layer)
+ * - endAt prevents infinite schedules
+ *
+ * @example
+ * ```typescript
+ * // Cron-based (every Monday at 9am)
+ * {
+ *   type: 'recurring',
+ *   cron: '0 9 * * 1',
+ *   timezone: 'America/New_York',
+ *   payload: { report: 'weekly' }
+ * }
+ *
+ * // Interval-based (daily at 10:30)
+ * {
+ *   type: 'recurring',
+ *   interval: 'daily',
+ *   time: '10:30',
+ *   timezone: 'Europe/London',
+ *   payload: { check: 'daily' }
+ * }
+ * ```
+ */
+export const RecurringScheduleConfigSchema = z
+  .object({
+    type: z.literal('recurring'),
+    cron: z.string().optional(),
+    interval: z.enum(['daily', 'weekly', 'monthly']).optional(),
+    time: z
+      .string()
+      .regex(/^\d{2}:\d{2}$/, 'Time must be in HH:MM format')
+      .optional(),
+    timezone: z.string().min(1, 'Timezone is required'),
+    payload: z.record(z.string(), z.unknown()),
+    endAt: z.string().datetime().nullable().optional(),
+    overduePolicy: z.enum(['skip', 'execute']).optional()
+  })
+  .refine((data) => data.cron || data.interval, { message: 'Either cron or interval must be provided' })
+
+/**
+ * Relative schedule configuration
+ * Schedule items relative to an anchor date (e.g., event countdown)
+ *
+ * @example
+ * ```typescript
+ * {
+ *   type: 'relative',
+ *   anchorAt: '2025-06-01T00:00:00Z',
+ *   anchorLabel: 'Product Launch',
+ *   items: [
+ *     { offset: '-30d', payload: { reminder: '30 days out' } },
+ *     { offset: '-7d', payload: { reminder: '1 week out' } },
+ *     { offset: '-1d', payload: { reminder: 'tomorrow' } }
+ *   ]
+ * }
+ * ```
+ */
+export const RelativeScheduleConfigSchema = z.object({
+  type: z.literal('relative'),
+  anchorAt: z.string().datetime({ message: 'Invalid anchor datetime' }),
+  anchorLabel: z.string().optional(),
+  items: z.array(RelativeScheduleItemSchema).min(1, 'At least one item required'),
+  overduePolicy: z.enum(['skip', 'execute']).optional()
+})
+
+/**
+ * Absolute schedule configuration
+ * Schedule items at specific fixed datetimes
+ *
+ * @example
+ * ```typescript
+ * {
+ *   type: 'absolute',
+ *   items: [
+ *     { runAt: '2025-01-15T10:00:00Z', payload: { event: 'first' } },
+ *     { runAt: '2025-02-15T10:00:00Z', payload: { event: 'second' } }
+ *   ]
+ * }
+ * ```
+ */
+export const AbsoluteScheduleConfigSchema = z.object({
+  type: z.literal('absolute'),
+  items: z.array(AbsoluteScheduleItemSchema).min(1, 'At least one item required'),
+  overduePolicy: z.enum(['skip', 'execute']).optional()
+})
+
+/**
+ * Task schedule configuration discriminated union
+ * Efficiently validates one of three schedule types based on 'type' field
+ *
+ * Uses Zod's discriminatedUnion for optimal parsing performance
+ */
+export const TaskScheduleConfigSchema = z.discriminatedUnion('type', [
+  RecurringScheduleConfigSchema,
+  RelativeScheduleConfigSchema,
+  AbsoluteScheduleConfigSchema
+])
+
+// ============================================================================
+// CREATE SCHEDULE INPUT SCHEMA
+// ============================================================================
+
+/**
+ * Target schema for schedule creation
+ * Simplified version without payload (payload is in schedule config)
+ */
+const ScheduleTargetSchema = z.object({
+  resourceType: ResourceTypeSchema,
+  resourceId: NonEmptyStringSchema.max(255)
+})
+
+/**
+ * Optional origin tracking for schedule creation
+ * All fields are optional for schedules created via API
+ */
+const OptionalOriginTrackingSchema = z.object({
+  originExecutionId: UuidSchema.optional(),
+  originResourceType: OriginResourceTypeSchema.optional(),
+  originResourceId: z.string().max(100).optional()
+})
+
+/**
+ * Create schedule input validation
+ * Complete input schema for creating a new task schedule
+ *
+ * Security Features:
+ * - organizationId validated as UUID (multi-tenancy)
+ * - name length limited (prevents DoS)
+ * - target validated with resource type enum
+ * - schedule config validated with discriminated union
+ * - maxRetries bounded (0-10)
+ *
+ * @example
+ * ```typescript
+ * {
+ *   organizationId: '550e8400-e29b-41d4-a716-446655440000',
+ *   name: 'Weekly Report Schedule',
+ *   description: 'Sends weekly analytics report',
+ *   target: {
+ *     resourceType: 'workflow',
+ *     resourceId: 'weekly-report-workflow'
+ *   },
+ *   scheduleConfig: {
+ *     type: 'recurring',
+ *     interval: 'weekly',
+ *     time: '09:00',
+ *     timezone: 'America/New_York',
+ *     payload: { reportType: 'analytics' }
+ *   },
+ *   maxRetries: 3
+ * }
+ * ```
+ */
+export const CreateScheduleInputSchema = z
+  .object({
+    organizationId: UuidSchema,
+    name: NonEmptyStringSchema.max(255),
+    description: z.string().max(1000).optional(),
+
+    target: ScheduleTargetSchema,
+    scheduleConfig: TaskScheduleConfigSchema,
+
+    maxRetries: z.number().int().min(0).max(10).optional().default(3),
+    idempotencyKey: z.string().max(255).optional(),
+    metadata: z.record(z.string(), z.unknown()).optional()
+  })
+  .merge(OptionalOriginTrackingSchema)
+
+// ============================================================================
+// INFERRED TYPES
+// ============================================================================
+
+/** Validated relative schedule item input */
+export type RelativeScheduleItemInput = z.infer<typeof RelativeScheduleItemSchema>
+
+/** Validated absolute schedule item input */
+export type AbsoluteScheduleItemInput = z.infer<typeof AbsoluteScheduleItemSchema>
+
+/** Validated recurring schedule config input */
+export type RecurringScheduleConfigInput = z.infer<typeof RecurringScheduleConfigSchema>
+
+/** Validated relative schedule config input */
+export type RelativeScheduleConfigInput = z.infer<typeof RelativeScheduleConfigSchema>
+
+/** Validated absolute schedule config input */
+export type AbsoluteScheduleConfigInput = z.infer<typeof AbsoluteScheduleConfigSchema>
+
+/** Validated task schedule config (union of all config types) */
+export type TaskScheduleConfigInput = z.infer<typeof TaskScheduleConfigSchema>
+
+/** Validated create schedule input */
+export type CreateScheduleInputValidated = z.infer<typeof CreateScheduleInputSchema>