@amazon-devices/kepler-epg-sync-scheduler

The @amazon-devices/kepler-epg-sync-scheduler package provides APIs for scheduling Electronic Program Guide (EPG) synchronization tasks in KeplerScript applications. It offers flexible scheduling options with both interval-based and time-window-based execution.

Overview

The Kepler EPG Sync Scheduler allows you to:

• Schedule periodic EPG sync tasks at regular intervals
• Schedule EPG sync tasks within specific time windows (e.g., between 2AM-4AM UTC)
• Cancel existing scheduled tasks

Public APIs

Main Scheduler

EpgSyncTaskScheduler

The main scheduler instance that implements the IEpgSyncTaskScheduler interface.

import {EpgSyncTaskScheduler} from '@amazon-devices/kepler-epg-sync-scheduler';

Interfaces

IEpgSyncTaskScheduler

The main interface exposing EPG sync task scheduling functions.

Methods:

scheduleTask(componentId: string, interval: number): Promise<void>

Schedules an EPG sync task to run at regular intervals.

• Parameters:
  • componentId: The component ID for the JS background task to be scheduled
  • interval: Time interval in minutes (must be between 5 and 1440 minutes inclusive)
• Behavior:
  • Runs the task immediately upon scheduling
  • Then schedules recurring execution at the specified interval
  • Only one EPG sync task can be scheduled at a time
  • Persists across device reboots
• Throws: InternalError if scheduling fails
• Returns: Promise that resolves when scheduling is complete

scheduleTaskWithExecutionWindow(componentId: string, timeProperties: ITimeProperties): Promise<void>

Schedules an EPG sync task to run daily within a specific time window.

• Parameters:
  • componentId: The component ID for the JS background task to be scheduled
  • timeProperties: Time constraints for task execution (created using UtcTimePropertiesBuilder)
• Behavior:
  • Runs the task immediately upon scheduling
  • Then schedules daily execution within the specified UTC time window
  • Only one EPG sync task can be scheduled at a time
  • Persists across device reboots
• Throws: InternalError if scheduling fails
• Returns: Promise that resolves when scheduling is complete

cancelScheduledTasks(): Promise<void>

Cancels all existing scheduled EPG sync tasks.

• Behavior:
  • Cancels tasks scheduled by either scheduleTask() or scheduleTaskWithExecutionWindow()
  • Succeeds even if no tasks are currently scheduled
• Throws: InternalError if cancellation fails
• Returns: Promise that resolves when cancellation is complete

Time Properties

ITimeProperties

Interface describing time constraints for task execution. Use UtcTimePropertiesBuilder to create instances.

UtcTimePropertiesBuilder

Builder class for creating UTC-based time properties with execution windows.

Methods:

startHour(hour: number): UtcTimePropertiesBuilder

Sets the start hour (0-23) for the execution window.

• Required field
• Throws: InvalidArgumentError if hour is not between 0-23
• Throws: IllegalStateError if builder has already been used

startMinute(minute: number): UtcTimePropertiesBuilder

Sets the start minute (0-59) for the execution window.

• Required field
• Throws: InvalidArgumentError if minute is not between 0-59
• Throws: IllegalStateError if builder has already been used

startSecond(second: number): UtcTimePropertiesBuilder

Sets the start second (0-59) for the execution window.

• Required field
• Throws: InvalidArgumentError if second is not between 0-59
• Throws: IllegalStateError if builder has already been used

executionWindowInMinutes(window: number): UtcTimePropertiesBuilder

Sets the length of the execution window in minutes.

• Optional field (defaults to 60 minutes)
• Throws: InvalidArgumentError if window is less than 60 minutes
• Throws: IllegalStateError if builder has already been used

build(): ITimeProperties

Builds the final TimeProperties object.

• Throws: InvalidArgumentError if required fields are missing
• Throws: IllegalStateError if builder has already been used
• Note: Builder instances can only be used once

Error Types

InternalError

Custom error indicating something went wrong when scheduling the EPG sync task.

InvalidArgumentError

Exception thrown when there is a failure in creating a new object due to invalid arguments.

IllegalStateError

Exception thrown when builder functions are called after the builder has already been used to build an object.

Important Notes

• Only one EPG sync task can be scheduled at any point in time
• The most recent scheduling call will override any previous scheduling
• Scheduled tasks persist across device reboots
• All time-based scheduling uses UTC time
• Builder instances can only be used once and cannot be reused after calling build()
• Interval scheduling accepts values between 5 and 1440 minutes (1 day)
• Execution window scheduling requires a minimum window of 60 minutes (1 hour)

Error Handling

All scheduling operations are asynchronous and may throw InternalError exceptions. Always wrap scheduling calls in try-catch blocks or handle Promise rejections appropriately.

The builder pattern used for time properties may throw InvalidArgumentError for invalid parameters or IllegalStateError if attempting to reuse a builder instance.

Developer Guide

For detailed integration steps, see https://developer.amazon.com/docs/kepler-tv/overview-of-epg-integration.html

Modules

• index
• turbo-modules/Builder
• turbo-modules/Builder
• turbo-modules/EpgSyncTaskScheduler
• turbo-modules/EpgSyncTaskScheduler
• turbo-modules/Error
• turbo-modules/Error
• turbo-modules/NativeEpgSyncTaskScheduler
• turbo-modules/NativeEpgSyncTaskScheduler
• turbo-modules/TimeProperties
• turbo-modules/TimeProperties

Last updated: Oct 02, 2025