feat(calendar): Implement Calendar Event Trigger Node

* Stub out basic calendar output node

* WIP Update UI with draft fields from last attempt

* Stuff it, these are the fields I will use

* WIP implement event to queue calendar events

* WIP implement calendar item timer queue

* WIP queue item events

* WIP trigger calendar event messages

* Add some todos

* WIP Refactor EventsCalendarController class

* linter fixes

* html delint

* Allow for mild overdue queuing

* Include a check for filter text

* Bug-fix: use offset when querying the API

* Implement custom outputs

* bit of an improvement to status messages

* Localise status messages

* Bug-fix: prevent queue time drift by basing next queue time on the end of the interval

* Include Expose As for the Events Calendar editor

* Remove Unnecessary constraint interface definition

* Refactor CalendarItem file structure

* Remove output count

---------

Co-authored-by: Nathan Brittain <git@enjibby.dev>

docs/.vuepress/config.ts

@@ -121,6 +121,7 @@ export default defineUserConfig({
                         'current-state',
                         'device',
                         'events-all',
+                        'events-calendar',
                         'events-state',
                         'fire-event',
                         'get-entities',

docs/node/events-calendar.md

@@ -0,0 +1,46 @@
+# Events: calendar
+
+Outputs calendar item events similar to the calendar automation in Home Assistant
+
+## Configuration:
+
+### Entity ID <Badge text="required"/>
+
+- Type: `string`
+
+The entity_id for the calendar that contains triggerable calendar items.
+
+### Relative To <Badge text="required"/>
+
+- Type: `start | end`
+- Default: `start`
+
+Whether to trigger an event at the start or end of each matching calendar item.
+
+### Offset <Badge text="required"/>
+
+- Type: `number`
+- Default: 0 seconds
+
+A negative or positive amount of time to allow the event to be triggered before or after the calendar item's start/end time.
+
+### Conditions
+
+This node has two default outputs "allowed" and "blocked". If all the
+conditions are true the calendar item will be sent to the output.
+
+**See Also:**
+
+- [Conditionals](/guide/conditionals.md)
+
+### Expose to Home Assistant
+
+- Type: `boolean`
+
+Creates a switch within Home Assistant to enable/disable this node. This feature requires [Node-RED custom integration](https://github.com/zachowj/hass-node-red) to be installed in Home Assistant
+
+## Outputs
+
+Value types:
+
+- `calendar item`: the calendar item object as provided by the Home Assistant API

gulpfile.js

@@ -73,6 +73,7 @@ const nodeMap = {
     entity: { doc: 'entity', type: 'ha-entity' },
     'entity-config': { doc: 'entity-config', type: 'ha-entity-config' },
     'events-all': { doc: 'events-all', type: 'server-events' },
+    'events-calendar': { doc: 'events-calendar', type: 'ha-events-calendar' },
     'events-state': {
         doc: 'events-state',
         type: 'server-state-changed',

src/common/services/TypedInputService.ts

@@ -90,6 +90,7 @@ export default class TypedInputService {
             case TypedInputTypes.Results:
             case TypedInputTypes.TriggerId:
             case TypedInputTypes.Value:
+            case TypedInputTypes.CalendarItem:
                 val = props[valueType];
                 break;
             default:

src/const.ts

@@ -74,6 +74,7 @@ export enum NodeType {
     Device = 'ha-device',
     Entity = 'ha-entity',
     EventsAll = 'server-events',
+    EventsCalendar = 'ha-events-calendar',
     EventsState = 'server-state-changed',
     FireEvent = 'ha-fire-event',
     GetEntities = 'ha-get-entities',
@@ -133,6 +134,7 @@ export enum TypedInputTypes {
     Regex = 're',
     Value = 'value',
     PreviousValue = 'previousValue',
+    CalendarItem = 'calendarItem',
 }
 
 export enum TimeUnit {

src/editor.ts

@@ -30,6 +30,7 @@ import DeviceConfigEditor from './nodes/device-config/editor';
 import EntityEditor from './nodes/entity/editor';
 import EntityConfigEditor from './nodes/entity-config/editor/editor';
 import EventsAllEditor from './nodes/events-all/editor';
+import EventsCalendarEditor from './nodes/events-calendar/editor';
 import EventsStateEditor from './nodes/events-state/editor';
 import FireEventEditor from './nodes/fire-event/editor';
 import GetEntitiesEditor from './nodes/get-entities/editor';
@@ -80,6 +81,7 @@ RED.nodes.registerType(NodeType.CurrentState, CurrentStateEditor);
 RED.nodes.registerType(NodeType.Device, DeviceEditor);
 RED.nodes.registerType(NodeType.Entity, EntityEditor);
 RED.nodes.registerType(NodeType.EventsAll, EventsAllEditor);
+RED.nodes.registerType(NodeType.EventsCalendar, EventsCalendarEditor);
 RED.nodes.registerType(NodeType.EventsState, EventsStateEditor);
 RED.nodes.registerType(NodeType.FireEvent, FireEventEditor);
 RED.nodes.registerType(NodeType.GetEntities, GetEntitiesEditor);

src/editor/components/output-properties.ts

@@ -42,6 +42,11 @@ const customTypes: { [key: string]: EditorWidgetTypedInputTypeDefinition } = {
     },
     triggerId: { value: 'triggerId', label: 'trigger id', hasValue: false },
     value: { value: 'value', label: 'value', hasValue: false },
+    calendarItem: {
+        value: 'calendarItem',
+        label: 'calendar item',
+        hasValue: false,
+    },
 };
 const defaultTypes: HATypedInputTypeOptions = [
     customTypes.config,

src/editor/data.ts

@@ -66,7 +66,12 @@ export function getAutocomplete(serverId: string, type: any) {
     return list;
 }
 
-export type AutocompleteType = 'entities' | 'properties' | 'trackers' | 'zones';
+export type AutocompleteType =
+    | 'entities'
+    | 'properties'
+    | 'trackers'
+    | 'zones'
+    | 'calendars';
 export function getAutocompleteData(serverId: string, type: AutocompleteType) {
     let list: { value: any; label: any }[] = [];
     switch (type) {
@@ -127,6 +132,20 @@ export function getAutocompleteData(serverId: string, type: AutocompleteType) {
                 .sort(sortFriendlyName);
             break;
         }
+        case 'calendars': {
+            if (!(serverId in entities)) return [];
+            const path = 'attributes.friendly_name';
+            list = Object.values(entities[serverId])
+                .filter((item) => item.entity_id.startsWith('calendar.'))
+                .map((item) => {
+                    return {
+                        value: item.entity_id,
+                        label: deepFind(path, item) || item.entity_id,
+                    };
+                })
+                .sort(sortFriendlyName);
+            break;
+        }
     }
 
     return list;

src/editor/exposenode.ts

@@ -94,6 +94,7 @@ export function init(n: HassNodeProperties) {
                 }
                 break;
             case NodeType.EventsAll:
+            case NodeType.EventsCalendar:
             case NodeType.EventsState:
             case NodeType.PollState:
             case NodeType.Tag:
@@ -131,6 +132,7 @@ function render() {
             }
             break;
         case NodeType.EventsAll:
+        case NodeType.EventsCalendar:
         case NodeType.EventsState:
         case NodeType.PollState:
         case NodeType.Tag:

src/helpers/migrate.ts

@@ -9,6 +9,7 @@ import deviceConfig from '../nodes/device-config/migrations';
 import entity from '../nodes/entity/migrations';
 import entityConfig from '../nodes/entity-config/migrations';
 import eventsAll from '../nodes/events-all/migrations';
+import eventsCalendar from '../nodes/events-calendar/migrations';
 import eventsState from '../nodes/events-state/migrations';
 import fireEvent from '../nodes/fire-event/migrations';
 import getEntities from '../nodes/get-entities/migrations';
@@ -44,6 +45,7 @@ const nodeTypeTranslation: Partial<Record<NodeType, Migration[]>> = {
     [NodeType.Entity]: entity,
     [NodeType.EntityConfig]: entityConfig,
     [NodeType.EventsAll]: eventsAll,
+    [NodeType.EventsCalendar]: eventsCalendar,
     [NodeType.EventsState]: eventsState,
     [NodeType.FireEvent]: fireEvent,
     [NodeType.GetEntities]: getEntities,

src/index.ts

@@ -15,6 +15,7 @@ import deviceConfigNode from './nodes/device-config';
 import entityNode from './nodes/entity';
 import entityConfigNode from './nodes/entity-config';
 import eventsAllNode from './nodes/events-all';
+import eventsCalendarNode from './nodes/events-calendar';
 import eventsStateNode from './nodes/events-state';
 import fireEventNode from './nodes/fire-event';
 import getEntitiesNode from './nodes/get-entities';
@@ -44,6 +45,7 @@ const nodes: Record<NodeType, any> = {
     [NodeType.Device]: deviceNode,
     [NodeType.Entity]: entityNode,
     [NodeType.EventsAll]: eventsAllNode,
+    [NodeType.EventsCalendar]: eventsCalendarNode,
     [NodeType.EventsState]: eventsStateNode,
     [NodeType.FireEvent]: fireEventNode,
     [NodeType.GetEntities]: getEntitiesNode,

src/nodes/events-calendar/CalendarItem.ts

@@ -0,0 +1,41 @@
+import { DateOrDateTime, toDate } from './helpers';
+
+export interface ICalendarItem {
+    start: DateOrDateTime;
+    end: DateOrDateTime;
+    summary: string;
+    description: string;
+    location?: string | null;
+    uid: string;
+    recurrence_id?: string | null;
+    rrule?: string | null;
+    queueIndex(): string;
+    date(eventType: string): Date;
+}
+
+export class CalendarItem implements ICalendarItem {
+    start!: DateOrDateTime;
+    end!: DateOrDateTime;
+    summary!: string;
+    description!: string;
+    location?: string | null;
+    uid!: string;
+    recurrence_id?: string | null;
+    rrule?: string | null;
+
+    constructor(data: ICalendarItem) {
+        Object.assign(this, data);
+    }
+
+    queueIndex() {
+        return `${this.uid}${this.recurrence_id || ''}`;
+    }
+
+    date(eventType: string): Date {
+        return eventType === 'start' ? toDate(this.start) : toDate(this.end);
+    }
+}
+
+export function createCalendarItem(data: ICalendarItem): CalendarItem {
+    return new CalendarItem(data);
+}