# 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 (standard JSON Schema format)
parameters:
  type: object
  properties:
    fire_at:
      type: string
      description: "ISO 8601 timestamp when the timer should fire (e.g., '2024-12-31T23:59:59Z')"
    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"
  required:
    - fire_at

# Payload schema - data emitted when trigger fires
output:
  type: object
  properties:
    type:
      type: string
      const: one_shot
      description: "Trigger type identifier"
    fire_at:
      type: string
      format: date-time
      description: "Scheduled fire time"
    fired_at:
      type: string
      format: date-time
      description: "Actual fire time"
    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"
  required:
    - type
    - fire_at
    - fired_at

# 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