@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 scheduledinterval
: 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 scheduledtimeProperties
: Time constraints for task execution (created usingUtcTimePropertiesBuilder
)
- 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()
orscheduleTaskWithExecutionWindow()
- Succeeds even if no tasks are currently scheduled
- Cancels tasks scheduled by either
- 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