# 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 (standard JSON Schema format)
parameters:
  type: object
  properties:
    expression:
      type: string
      description: "Cron expression in standard format (second minute hour day month weekday)"
    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"
  required:
    - expression

# Payload schema - data emitted when trigger fires
output:
  type: object
  properties:
    type:
      type: string
      const: cron
      description: "Trigger type identifier"
    fired_at:
      type: string
      format: date-time
      description: "Timestamp when the trigger fired"
    scheduled_at:
      type: string
      format: date-time
      description: "Timestamp when the trigger was scheduled to fire"
    expression:
      type: string
      description: "The cron expression that triggered this event"
    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"
  required:
    - type
    - fired_at
    - scheduled_at
    - expression

# 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    * , - / ?