Skip to content

Calendar Module API Explanation

The Calendar module merges and parses chronological events from Google Calendar and media release schedules.

API Execution Logic

This module acts as a concurrent aggregator that queries multiple calendar feeds in parallel using Promise.allSettled. Up to four calendar sources are supported: Google Calendar, Sonarr, Radarr, and Lidarr.

Sub-Fetcher Execution

1. Google Calendar (google)

  • Enforces presence of GOOGLE_CALENDAR_API_KEY.
  • Resolves the primary GOOGLE_CALENDAR_ID and any additional calendar IDs.
  • Calculates dates covering daysBack to daysForward and queries the Google Calendar API v3 endpoint (/calendar/v3/calendars/[CALENDAR_ID]/events).
  • Filters and sanitizes event descriptions (purging holiday observance footer notes).
  • Implements a local 1-hour cache (3600000ms) due to Google API quota limitations.

2. Sonarr Calendar (sonarr)

  • Enforces presence of the Sonarr API URL and SONARR_API_KEY.
  • Queries the Sonarr API (/api/v3/calendar) for episodes airing in the configured window.
  • Formats title strings with series name, season, episode numbers, and episode title.

3. Radarr Calendar (radarr)

  • Enforces presence of the Radarr API URL and RADARR_API_KEY.
  • Queries the Radarr API (/api/v3/calendar) for movies.
  • Maps the event date prioritizing cinema releases, physical releases, or digital releases.

4. Lidarr Calendar (lidarr)

  • Enforces presence of the Lidarr API URL and LIDARR_API_KEY.
  • Queries the Lidarr API (/api/v1/calendar) for upcoming music album releases.

Aggregation and Chronological Sorting

The module aggregates all fulfilled event arrays, assigns priority rankings to differentiate event sources, sorts them chronologically by start date, and strips internal priority tags prior to returning the JSON payload.