@amazon-devices/kepler-epg-sync-scheduler 1.2.94 → 1.2.124

package/README.md

@@ -0,0 +1,136 @@
+# Kepler EPG Sync Scheduler API Documentation
+
+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.
+
+```typescript
+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