# Cron Timer Trigger
# Fires based on cron schedule expressions

ref: core.crontimer
label: "Cron Timer"
description: "Fires based on a cron schedule expression (e.g., '0 0 * * * *' for every hour)"
enabled: true

# Trigger type
type: cron

# Parameter schema - configuration for the trigger instance (StackStorm-style with inline required/secret)
parameters:
  expression:
    type: string
    description: "Cron expression in standard format (second minute hour day month weekday)"
    required: true
  timezone:
    type: string
    description: "Timezone for cron schedule (e.g., 'UTC', 'America/New_York')"
    default: "UTC"
  description:
    type: string
    description: "Human-readable description of the schedule"

# Payload schema - data emitted when trigger fires
output:
  type:
    type: string
    const: cron
    description: "Trigger type identifier"
    required: true
  fired_at:
    type: string
    format: date-time
    description: "Timestamp when the trigger fired"
    required: true
  scheduled_at:
    type: string
    format: date-time
    description: "Timestamp when the trigger was scheduled to fire"
    required: true
  expression:
    type: string
    description: "The cron expression that triggered this event"
    required: true
  timezone:
    type: string
    description: "Timezone used for scheduling"
  next_fire_at:
    type: string
    format: date-time
    description: "Timestamp when the trigger will fire next"
  execution_count:
    type: integer
    description: "Number of times this trigger has fired"
  sensor_ref:
    type: string
    description: "Reference to the sensor that generated this event"

# Tags for categorization
tags:
  - timer
  - cron
  - scheduler
  - periodic

# Documentation
examples:
  - description: "Fire every hour at the top of the hour"
    parameters:
      expression: "0 0 * * * *"
      description: "Hourly"

  - description: "Fire every day at midnight UTC"
    parameters:
      expression: "0 0 0 * * *"
      description: "Daily at midnight"

  - description: "Fire every Monday at 9:00 AM"
    parameters:
      expression: "0 0 9 * * 1"
      description: "Weekly on Monday morning"

  - description: "Fire every 15 minutes"
    parameters:
      expression: "0 */15 * * * *"
      description: "Every 15 minutes"

  - description: "Fire at 8:30 AM on weekdays"
    parameters:
      expression: "0 30 8 * * 1-5"
      description: "Weekday morning"
      timezone: "America/New_York"

# Cron format reference
# Field         Allowed values    Special characters
# second        0-59              * , - /
# minute        0-59              * , - /
# hour          0-23              * , - /
# day of month  1-31              * , - / ?
# month         1-12 or JAN-DEC   * , - /
# day of week   0-6 or SUN-SAT    * , - / ?