> ## Documentation Index
> Fetch the complete documentation index at: https://chronotab.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Scheduler

## Functions

### registerAlarms() ⇒ `void`

Registers all alarms for current schedules stored in `chrome.storage.sync`.

This function performs the following steps:

<ol>
  * Retrieves all schedules from `chrome.storage.sync`.

  * Updates the `calculatedWhen` property for any "once" schedules based on their specified time.
    If a "once" schedule's time is in the past, `calculatedWhen` is removed.
    For non-"once" schedules, `calculatedWhen` is always removed.

  * Clears all existing Chrome alarms.

  * Creates new alarms based on the processed schedules:
    For "once" schedules, a single alarm is set at `calculatedWhen` if it's valid and in the future,
    and if the schedule hasn't already run (checked against `lastRun`).

  * For "daily" schedules, a repeating alarm is set for the next occurrence of `schedule.time` with a 24-hour period.

  * For "weekly" schedules, a repeating alarm is set for each specified `dayOfWeek` at `schedule.time` with a 7-day period.
    Unique alarm names are generated for each day of a weekly schedule (e.g., `schedule.id + &quot;-&quot; + dow`).
</ol>

If `calculatedWhen` was added, modified, or removed for any schedule, the updated schedules are saved back to `chrome.storage.sync`.
Errors during saving are logged to the console.

### getNextOccurrence(timeStr) ⇒ `number` | `null`

Calculates the next occurrence timestamp (in milliseconds since epoch) for a given time string.
The time string can be in "HH:mm" format or an ISO string (e.g., "YYYY-MM-DDTHH:mm"), from which "HH:mm" is extracted.
If the calculated time for today has already passed, it returns the timestamp for that time tomorrow.

### getNextWeeklyOccurrence(timeStr, dayOfWeek) ⇒ `number` | `null`

Calculates the next occurrence timestamp (in milliseconds since epoch) for a weekly schedule.
It considers the provided time string and the target day of the week.
The time string can be in "HH:mm" format or an ISO string (e.g., "YYYY-MM-DDTHH:mm"), from which "HH:mm" is extracted.
If the target day is today but the time has passed, it schedules for the same day next week.

### exportScheduleById(scheduleId) ⇒ `Promise.<(string|null)>`

Exports a single schedule as a JSON string.

### importSchedule(scheduleJson) ⇒ `Promise.<(Schedule|null)>`

Imports a single schedule from a JSON string.
Assigns a new unique ID to the imported schedule and removes any existing `lastRun` or `calculatedWhen` properties.
The imported schedule is added to the existing list of schedules in `chrome.storage.sync`.
After successfully saving, it re-registers all alarms.

### exportAllSchedules() ⇒ `Promise.<string>`

Exports all schedules as a JSON string.

### importAllSchedules(schedulesJson) ⇒ `Promise.<(Array.<Schedule>|null)>`

Imports multiple schedules from a JSON string, replacing all existing schedules in `chrome.storage.sync`.
Assigns new unique IDs to all imported schedules and removes any existing `lastRun` or `calculatedWhen` properties.
Basic validation is performed on each schedule; invalid schedules are skipped with a warning.
After successfully saving, it re-registers all alarms.

### onSchedulesChanged() ⇒ `void`

A utility function that calls registerAlarms.
This is intended to be used as a callback or event handler when schedules are changed,
ensuring that Chrome alarms are updated accordingly.

### runSchedule(schedule) ⇒ `void`

Opens all URLs specified in a given schedule object in new Chrome tabs.
If the schedule object is invalid, or if it contains no URLs, a warning is logged to the console.

## Typedefs

### Schedule : `object`

Represents a scheduling configuration for opening URLs.

<a name="registerAlarms" />

## registerAlarms() ⇒ `void`

Registers all alarms for current schedules stored in `chrome.storage.sync`.

This function performs the following steps:

1. Retrieves all schedules from `chrome.storage.sync`.
2. Updates the `calculatedWhen` property for any "once" schedules based on their specified time.
   If a "once" schedule's time is in the past, `calculatedWhen` is removed.
   For non-"once" schedules, `calculatedWhen` is always removed.
3. Clears all existing Chrome alarms.
4. Creates new alarms based on the processed schedules:
   * For "once" schedules, a single alarm is set at `calculatedWhen` if it's valid and in the future,
     and if the schedule hasn't already run (checked against `lastRun`).
   * For "daily" schedules, a repeating alarm is set for the next occurrence of `schedule.time` with a 24-hour period.
   * For "weekly" schedules, a repeating alarm is set for each specified `dayOfWeek` at `schedule.time` with a 7-day period.
     Unique alarm names are generated for each day of a weekly schedule (e.g., `schedule.id + "-" + dow`).

If `calculatedWhen` was added, modified, or removed for any schedule, the updated schedules are saved back to `chrome.storage.sync`.
Errors during saving are logged to the console.

**Kind**: global function\
**Returns**: `void` - This function does not return a value directly but operates via side effects on Chrome alarms and storage.

<a name="getNextOccurrence" />

## getNextOccurrence(timeStr) ⇒ `number` | `null`

Calculates the next occurrence timestamp (in milliseconds since epoch) for a given time string.
The time string can be in "HH:mm" format or an ISO string (e.g., "YYYY-MM-DDTHH:mm"), from which "HH:mm" is extracted.
If the calculated time for today has already passed, it returns the timestamp for that time tomorrow.

**Kind**: global function\
**Returns**: `number` | `null` - The timestamp in milliseconds for the next occurrence, or null if the time string is invalid.

| Param   | Type     | Description                                            |
| ------- | -------- | ------------------------------------------------------ |
| timeStr | `string` | The time string (e.g., "14:30" or "2023-10-26T14:30"). |

<a name="getNextWeeklyOccurrence" />

## getNextWeeklyOccurrence(timeStr, dayOfWeek) ⇒ `number` | `null`

Calculates the next occurrence timestamp (in milliseconds since epoch) for a weekly schedule.
It considers the provided time string and the target day of the week.
The time string can be in "HH:mm" format or an ISO string (e.g., "YYYY-MM-DDTHH:mm"), from which "HH:mm" is extracted.
If the target day is today but the time has passed, it schedules for the same day next week.

**Kind**: global function\
**Returns**: `number` | `null` - The timestamp in milliseconds for the next weekly occurrence, or null if inputs are invalid.

| Param     | Type     | Description                                                                   |
| --------- | -------- | ----------------------------------------------------------------------------- |
| timeStr   | `string` | The time string (e.g., "09:00" or "2023-10-26T09:00").                        |
| dayOfWeek | `number` | The target day of the week (0 for Sunday, 1 for Monday, ..., 6 for Saturday). |

<a name="exportScheduleById" />

## exportScheduleById(scheduleId) ⇒ `Promise.<(string\|null)>`

Exports a single schedule as a JSON string.

**Kind**: global function\
**Returns**: `Promise.<(string\|null)>` - A promise that resolves with the JSON string of the schedule, or null if not found.

| Param      | Type     | Description                       |
| ---------- | -------- | --------------------------------- |
| scheduleId | `string` | The ID of the schedule to export. |

<a name="importSchedule" />

## importSchedule(scheduleJson) ⇒ `Promise.<(Schedule\|null)>`

Imports a single schedule from a JSON string.
Assigns a new unique ID to the imported schedule and removes any existing `lastRun` or `calculatedWhen` properties.
The imported schedule is added to the existing list of schedules in `chrome.storage.sync`.
After successfully saving, it re-registers all alarms.

**Kind**: global function\
**Returns**: `Promise.<(Schedule\|null)>` - A promise that resolves with the imported schedule object (with new ID and cleaned properties)
if successful, or null if parsing or validation fails. Rejects on storage error.

| Param        | Type     | Description                                |
| ------------ | -------- | ------------------------------------------ |
| scheduleJson | `string` | The JSON string of the schedule to import. |

<a name="exportAllSchedules" />

## exportAllSchedules() ⇒ `Promise.<string>`

Exports all schedules as a JSON string.

**Kind**: global function\
**Returns**: `Promise.<string>` - A promise that resolves with the JSON string of all schedules.

<a name="importAllSchedules" />

## importAllSchedules(schedulesJson) ⇒ `Promise.<(Array.<Schedule>\|null)>`

Imports multiple schedules from a JSON string, replacing all existing schedules in `chrome.storage.sync`.
Assigns new unique IDs to all imported schedules and removes any existing `lastRun` or `calculatedWhen` properties.
Basic validation is performed on each schedule; invalid schedules are skipped with a warning.
After successfully saving, it re-registers all alarms.

**Kind**: global function\
**Returns**: `Promise.<(Array.<Schedule>\|null)>` - A promise that resolves with the array of successfully validated and imported schedule objects
if successful, or null if the input is not an array or parsing fails. Rejects on storage error.

| Param         | Type     | Description                                       |
| ------------- | -------- | ------------------------------------------------- |
| schedulesJson | `string` | The JSON string of the schedules array to import. |

<a name="onSchedulesChanged" />

## onSchedulesChanged() ⇒ `void`

A utility function that calls [registerAlarms](#registerAlarms).
This is intended to be used as a callback or event handler when schedules are changed,
ensuring that Chrome alarms are updated accordingly.

**Kind**: global function

<a name="runSchedule" />

## runSchedule(schedule) ⇒ `void`

Opens all URLs specified in a given schedule object in new Chrome tabs.
If the schedule object is invalid, or if it contains no URLs, a warning is logged to the console.

**Kind**: global function

| Param    | Type                    | Description                                              |
| -------- | ----------------------- | -------------------------------------------------------- |
| schedule | [`Schedule`](#Schedule) | The schedule object containing an array of URLs to open. |

<a name="Schedule" />

## Schedule : `object`

Represents a scheduling configuration for opening URLs.

**Kind**: global typedef\
**Properties**

| Name              | Type             | Description                                                                           |
| ----------------- | ---------------- | ------------------------------------------------------------------------------------- |
| id                | `string`         | Unique identifier for the schedule.                                                   |
| name              | `string`         | User-defined name for the schedule.                                                   |
| urls              | `Array.<string>` | List of URLs to open when the schedule runs.                                          |
| time              | `string`         | Time for the schedule to run. Can be HH:mm or ISO string YYYY-MM-DDTHH:mm.            |
| repeat            | `string`         | How often the schedule repeats ("once", "daily", "weekly").                           |
| \[dayOfWeek]      | `Array.<number>` | Days of the week for weekly schedules (0=Sun, 6=Sat). Required if repeat is 'weekly'. |
| \[lastRun]        | `number`         | Timestamp (ms since epoch) of when the schedule last ran.                             |
| \[calculatedWhen] | `number`         | Timestamp (ms since epoch) calculated for the next run of a "once" schedule.          |