# Datetime Timer Trigger
# Fires once at a specific date and time

ref: core.datetimetimer
label: "DateTime Timer"
description: "Fires once at a specific date and time"
enabled: true

# Trigger type
type: one_shot

# Parameter schema - configuration for the trigger instance (StackStorm-style with inline required/secret)
parameters:
  fire_at:
    type: string
    description: "ISO 8601 timestamp when the timer should fire (e.g., '2024-12-31T23:59:59Z')"
    required: true
  timezone:
    type: string
    description: "Timezone for the datetime (e.g., 'UTC', 'America/New_York')"
    default: "UTC"
  description:
    type: string
    description: "Human-readable description of when this timer fires"

# Payload schema - data emitted when trigger fires
output:
  type:
    type: string
    const: one_shot
    description: "Trigger type identifier"
    required: true
  fire_at:
    type: string
    format: date-time
    description: "Scheduled fire time"
    required: true
  fired_at:
    type: string
    format: date-time
    description: "Actual fire time"
    required: true
  timezone:
    type: string
    description: "Timezone used for scheduling"
  delay_ms:
    type: integer
    description: "Delay in milliseconds between scheduled and actual fire time"
  sensor_ref:
    type: string
    description: "Reference to the sensor that generated this event"

# Tags for categorization
tags:
  - timer
  - datetime
  - one-shot
  - scheduler

# Documentation
examples:
  - description: "Fire at midnight on New Year's Eve 2024"
    parameters:
      fire_at: "2024-12-31T23:59:59Z"
      description: "New Year's countdown"

  - description: "Fire at 3:00 PM EST on a specific date"
    parameters:
      fire_at: "2024-06-15T15:00:00-05:00"
      timezone: "America/New_York"
      description: "Afternoon reminder"

  - description: "Fire in 1 hour from now (use ISO 8601)"
    parameters:
      fire_at: "2024-01-20T15:30:00Z"
      description: "One-hour reminder"

# Notes:
# - This trigger fires only once and is automatically disabled after firing
# - Use ISO 8601 format for the fire_at parameter
# - The sensor will remove the trigger instance after it fires
# - For recurring timers, use intervaltimer or crontimer instead
