### Query All Task Versions and Print Details

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Fetch all versions of tasks within a date range and print their effective start date and whether they are the latest version.

```swift
import SpeziScheduler

// Fetch all versions of a task
let allVersions = try scheduler.queryTasks(for: Date.distantPast...Date.distantFuture)
let questionnaireVersions = allVersions.filter { $0.id == "daily-questionnaire" }
for version in questionnaireVersions {
    print("Effective from \(version.effectiveFrom), latest: \(version.isLatestVersion)")
}
```

--------------------------------

### Create and Update Tasks with SpeziScheduler

Source: https://github.com/stanfordspezi/spezischeduler/blob/main/Sources/SpeziScheduler/SpeziScheduler.docc/SpeziScheduler.md

Implement a custom `Module` to manage tasks using the `Scheduler`. This example demonstrates how to create a daily task with a specific schedule and handles potential errors during task creation.

```swift
import Spezi
import SpeziScheduler

class MySchedulerModule: Module {
    @Dependency(Scheduler.self)
    private var scheduler

    init() {}

    func configure() {
        do {
            try scheduler.createOrUpdateTask(
                id: "my-daily-task",
                title: "Daily Questionnaire",
                instructions: "Please fill out the Questionnaire every day.",
                category: Task.Category("Questionnaire", systemName: "list.clipboard.fill"),
                schedule: .daily(hour: 9, minute: 0, startingAt: .today)
            )
        } catch {
            // handle error (e.g., visualize in your UI)
        }
    }
}
```

--------------------------------

### Create or Update Task with Custom Metadata

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Example of creating or updating a weekly task, including scheduling notifications and attaching custom metadata to the Task.Context using the @Property macro.

```swift
import SpeziScheduler

// Create a weekly task, every Monday at 8am, starting this week
do {
    let (task, didChange) = try scheduler.createOrUpdateTask(
        id: "weekly-weight-check",
        title: "Weight Measurement",
        instructions: "Perform a new weight measurement with your Bluetooth scale.",
        category: Task.Category("Measurement", systemName: "scalemass.fill"),
        schedule: .weekly(weekday: .monday, hour: 8, minute: 0, startingAt: .today),
        completionPolicy: .afterStart,
        scheduleNotifications: true,
        notificationThread: .task,
        tags: ["measurement"]
    ) { context in
        // Attach custom metadata to the Task.Context via @Property
        context.measurementType = .weight
    }
    print("Task created or updated: \(didChange), id: \(task.id)")
} catch Scheduler.DataError.shadowingPreviousOutcomes {
    print("Cannot update: would shadow existing outcomes.")
} catch {
    print("Unexpected error: \(error)")
}
```

--------------------------------

### Configure Scheduler Persistence Backends

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Shows how to initialize the Scheduler with different persistence options: default on-disk, custom on-disk directory, and in-memory for testing.

```swift
// Default on-disk storage (recommended for production)
let scheduler = Scheduler()

// Custom on-disk storage directory
let customURL = URL.applicationSupportDirectory.appending(component: "MyApp/Scheduler")
let schedulerCustom = Scheduler(persistence: .onDisk(directory: customURL))

// In-memory storage for unit tests
let schedulerInMemory = Scheduler(persistence: .inMemory)
```

--------------------------------

### Scheduler Initialization

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Explains the different persistence options for initializing the `Scheduler`, including default on-disk storage, custom on-disk directories, and in-memory storage for testing.

```APIDOC
## `Scheduler.init(persistence:)` — Configure storage backend

`Scheduler` can be initialized with `.onDisk` (default, stores in `~/Documents/SpeziScheduler`), `.onDisk(directory:)` for a custom path, or `.inMemory` for ephemeral (testing) storage. In a macOS app that uses `.onDisk`, sandboxing must be enabled.

```swift
// Default on-disk storage (recommended for production)
let scheduler = Scheduler()

// Custom on-disk storage directory
let customURL = URL.applicationSupportDirectory.appending(component: "MyApp/Scheduler")
let schedulerCustom = Scheduler(persistence: .onDisk(directory: customURL))

// In-memory storage for unit tests
let schedulerInMemory = Scheduler(persistence: .inMemory)
```
```

--------------------------------

### Configure and Create Task with Scheduler Module

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Demonstrates how to declare the Scheduler as a dependency in a custom Spezi Module and configure a daily task. Handles potential data errors during task creation.

```swift
import Spezi
import SpeziScheduler

// 1. Declare the Scheduler as a dependency in your own Module
class MySchedulerModule: Module {
    @Dependency(Scheduler.self)
    private var scheduler

    init() {}

    func configure() {
        do {
            // Creates the task if new, or creates a new version if properties changed
            try scheduler.createOrUpdateTask(
                id: "daily-questionnaire",
                title: "Daily Questionnaire",
                instructions: "Please fill out the questionnaire every day.",
                category: Task.Category("Questionnaire", systemName: "list.clipboard.fill"),
                schedule: .daily(hour: 9, minute: 0, startingAt: .today),
                completionPolicy: .sameDay,
                scheduleNotifications: true,
                tags: ["health", "survey"]
            )
        } catch { 
            // Handle Scheduler.DataError cases:
            // .invalidContainer, .shadowingPreviousOutcomes, .nextVersionAlreadyPresent
            print("Failed to configure task: \(error.localizedDescription)")
        }
    }
}

// 2. Register the module in your SpeziAppDelegate
class AppDelegate: SpeziAppDelegate {
    override var configuration: Configuration {
        Configuration {
            MySchedulerModule()
        }
    }
}
```

--------------------------------

### Scheduler Module Integration

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Demonstrates how to integrate the `Scheduler` module into a Spezi application by declaring it as a dependency in a custom module and registering it in the SpeziAppDelegate.

```APIDOC
## `Scheduler` — Core module for managing tasks and events

`Scheduler` is a Spezi `Module` and the central entry point for all scheduling operations. It manages a versioned, append-only SwiftData store of `Task` objects and provides APIs to create, update, query, and delete tasks and their events. It must be declared as a dependency in a Spezi app delegate or another module.

```swift
import Spezi
import SpeziScheduler

// 1. Declare the Scheduler as a dependency in your own Module
class MySchedulerModule: Module {
    @Dependency(Scheduler.self)
    private var scheduler

    init() {}

    func configure() {
        do {
            // Creates the task if new, or creates a new version if properties changed
            try scheduler.createOrUpdateTask(
                id: "daily-questionnaire",
                title: "Daily Questionnaire",
                instructions: "Please fill out the questionnaire every day.",
                category: Task.Category("Questionnaire", systemName: "list.clipboard.fill"),
                schedule: .daily(hour: 9, minute: 0, startingAt: .today),
                completionPolicy: .sameDay,
                scheduleNotifications: true,
                tags: ["health", "survey"]
            )
        } catch {
            // Handle Scheduler.DataError cases:
            // .invalidContainer, .shadowingPreviousOutcomes, .nextVersionAlreadyPresent
            print("Failed to configure task: \(error.localizedDescription)")
        }
    }
}

// 2. Register the module in your SpeziAppDelegate
class AppDelegate: SpeziAppDelegate {
    override var configuration: Configuration {
        Configuration {
            MySchedulerModule()
        }
    }
}
```
```

--------------------------------

### Display Event Details with InstructionsTile

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Use InstructionsTile to display event information. It supports basic display, action buttons, custom alignment, and custom headers/footers.

```swift
InstructionsTile(event)
```

```swift
InstructionsTile(event) {
    try? event.complete()
}
```

```swift
InstructionsTile(event, alignment: .center) {
    try? event.complete()
} more: {
    VStack(alignment: .leading, spacing: 12) {
        Text("Step-by-step instructions")
            .font(.headline)
        Text("1. Open the app\n2. Follow the on-screen prompts\n3. Submit your response.")
    }
    .padding()
}
```

```swift
InstructionsTile(
    event,
    footerVisibility: .showAlways,
    header: {
        HStack {
            Image(systemName: "heart.fill").foregroundStyle(.red)
            Text(event.task.title).font(.headline)
        }
    },
    footer: {
        Button("Complete") { try? event.complete() }
            .buttonStyle(.borderedProminent)
    }
)
```

--------------------------------

### Create Task with Specific Completion Policy

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Creates or updates a task with a defined completion policy, controlling when the event can be marked as complete. Also demonstrates how to check when completion becomes allowed based on a policy.

```swift
import SpeziScheduler

// .sameDay    — allowed any time on the day the event occurs
// .afterStart — allowed after the event's start time, forever
// .sameDayAfterStart — allowed after start time, but only on the same day
// .duringEvent — allowed only while the event is currently occurring
// .anytime    — always allowed

try scheduler.createOrUpdateTask(
    id: "medication-reminder",
    title: "Take Medication",
    instructions: "Take your evening medication.",
    schedule: .daily(hour: 20, minute: 0, startingAt: .today),
    completionPolicy: .duringEvent  // must complete within the event window
)

// Check when completion becomes allowed / disallowed
let policy = AllowedCompletionPolicy.afterStart
if let allowedAt = policy.dateOnceCompletionIsAllowed(for: event) {
    print("Completion allowed from: \(allowedAt)")
}
```

--------------------------------

### Navigate Task Version Chain

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Find the latest version of a task and navigate to its first version and previous version, printing their effective dates.

```swift
// Navigate the version chain
if let latest = questionnaireVersions.first(where: { $0.isLatestVersion }) {
    let first = latest.firstVersion
    print("First version effective from: \(first.effectiveFrom)")
    print("Current version effective from: \(latest.effectiveFrom)")
    if let prev = latest.previousVersion {
        print("Previous version: \(prev.effectiveFrom)")
    }
}
```

--------------------------------

### Create Task with Notifications Enabled

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Create or update a task with a daily schedule and enable notifications. Notifications are grouped by task in Notification Center and have a specified display time.

```swift
// Create a task with notifications enabled
try scheduler.createOrUpdateTask(
    id: "med-reminder",
    title: "Evening Medication",
    instructions: "Take your medication.",
    schedule: .daily(hour: 21, minute: 0, startingAt: .today),
    scheduleNotifications: true,
    notificationThread: .task,            // group by task in Notification Center
    notificationTime: NotificationTime(hour: 21, minute: 0)
)
```

--------------------------------

### Scheduler.queryTasks(for:predicate:sortBy:fetchLimit:prefetchOutcomes:)

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Retrieves all versions of tasks that are effective within a given date range. This method accounts for task versioning and can filter, sort, and limit the results.

```APIDOC
## `Scheduler.queryTasks(for:predicate:sortBy:fetchLimit:prefetchOutcomes:)` — Query task versions

Returns all `Task` versions effective within the given date range. Since tasks are versioned, a single logical task may appear multiple times if it was updated during the range. Supports both `Range<Date>` and `ClosedRange<Date>`.

### Method
`queryTasks(for:predicate:sortBy:fetchLimit:prefetchOutcomes:)`

### Parameters
- **for** (`Range<Date>` or `ClosedRange<Date>`): The date range for which tasks should be effective.
- **predicate** (`Predicate<Task>`, optional): An optional predicate to filter tasks.
- **sortBy** (`[SortDescriptor<Task>]`, optional): An array of sort descriptors to order the results.
- **fetchLimit** (`Int`, optional): The maximum number of tasks to return.
- **prefetchOutcomes** (`Bool`, optional): Whether to prefetch task outcomes.

### Request Example
```swift
import SpeziScheduler
import Foundation

let startOfWeek = Calendar.current.date(from: Calendar.current.dateComponents([.yearForWeekOfYear, .weekOfYear], from: .now))!
let endOfWeek = Calendar.current.date(byAdding: .day, value: 7, to: startOfWeek)!

do {
    let tasks = try scheduler.queryTasks(
        for: startOfWeek..<endOfWeek,
        predicate: #Predicate { task in task.tags.contains("health") },
        sortBy: [SortDescriptor(\.effectiveFrom, order: .forward)],
        prefetchOutcomes: true
    )
    for task in tasks {
        print("\(task.id) — effective from \(task.effectiveFrom), outcomes: \(task.outcomes.count)")
    }
} catch {
    print("Query failed: \(error)")
}
```

### Response
- **Success Response**: Returns an array of `Task` versions.
```

--------------------------------

### Scheduler.deleteTasks(_:) and Scheduler.deleteAllVersions(of:)

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Provides methods to permanently delete task versions. `deleteTasks(_:)` removes a specific task version and all its future versions, while `deleteAllVersions(of:)` removes all versions of a given logical task.

```APIDOC
## `Scheduler.deleteTasks(_:)` and `Scheduler.deleteAllVersions(of:)` — Delete tasks

`deleteTasks(_:)` permanently deletes the given task version(s) and all future versions plus their outcomes. `deleteAllVersions(of:)` removes every version of a logical task. To stop a recurring task without deleting history, prefer creating a new version with a schedule that produces no future occurrences.

### Methods
- `deleteTasks(_: Task)`
- `deleteTasks(_: [Task])`
- `deleteAllVersions(ofTask: String)`

### Parameters
- **tasks** (`Task` or `[Task]`): The task version(s) to delete.
- **taskId** (`String`): The ID of the logical task for which to delete all versions.

### Request Example
```swift
import SpeziScheduler

// Fetch the latest version of a task and delete it (and all future versions)
do {
    let tasks = try scheduler.queryTasks(for: Date.now...Date.now)
    if let taskToDelete = tasks.first(where: { $0.id == "old-task" && $0.isLatestVersion }) {
        try scheduler.deleteTasks(taskToDelete)
    }
} catch {
    print("Delete failed: \(error)")
}

// Remove all versions of a task by its string ID
do {
    try scheduler.deleteAllVersions(ofTask: "weekly-weight-check")
    print("All versions deleted.")
} catch {
    print("Delete all versions failed: \(error)")
}
```

### Response
- **Success Response**: Indicates successful deletion.
- **Error Response**: Throws an error if deletion fails.
```

--------------------------------

### Displaying Events with EventScheduleList

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Provides a pre-built SwiftUI view, EventScheduleList, for rendering a titled and sectioned list of events for a given date. Includes built-in states for empty lists and errors, and supports custom event views.

```swift
import SpeziSchedulerUI
import SwiftUI

struct ScheduleTab: View {
    @State private var selectedDate: Date = .today

    var body: some View {
        NavigationStack {
            // Today's events (default)
            EventScheduleList {
                InstructionsTile(event) {
                    try? event.complete()
                } more: {
                    // Presented as a sheet when user taps the info button
                    VStack {
                        Text("About this task")
                        Text(event.task.instructions)
                    }
                    .padding()
                }
            }
            .navigationTitle("My Schedule")

            // Events for a custom date range
            EventScheduleList(date: selectedDate) {
                InstructionsTile(event) {
                    try? event.complete()
                }
            }
        }
    }
}
```

--------------------------------

### Configure SchedulerNotifications in AppDelegate

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Configure SchedulerNotifications with custom settings for notification limits, scheduling intervals, and presentation options. Set automaticallyRequestProvisionalAuthorization to false if manual authorization is preferred.

```swift
import Spezi
import SpeziScheduler

// Default configuration (30 notifications, 4-week window, provisional auth)
class AppDelegate: SpeziAppDelegate {
    override var configuration: Configuration {
        Configuration {
            // SchedulerNotifications is auto-configured by Scheduler.
            // Override only when customization is needed:
            SchedulerNotifications(
                notificationLimit: 50,
                schedulingInterval: .weeks(6),
                allDayNotificationTime: NotificationTime(hour: 8, minute: 30),
                notificationPresentation: [.banner, .sound, .badge],
                automaticallyRequestProvisionalAuthorization: false
            )
            Scheduler()
            MySchedulerModule()
        }
    }
}
```

--------------------------------

### Query Task Versions with Predicate and Sorting

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Query task versions effective within a date range, with optional predicate, sorting, and prefetching of outcomes. Supports Range and ClosedRange.

```swift
import SpeziScheduler
import Foundation

let startOfWeek = Calendar.current.date(from: Calendar.current.dateComponents([.yearForWeekOfYear, .weekOfYear], from: .now))!
let endOfWeek = Calendar.current.date(byAdding: .day, value: 7, to: startOfWeek)!

do {
    let tasks = try scheduler.queryTasks(
        for: startOfWeek..<endOfWeek,
        predicate: #Predicate { task in task.tags.contains("health") },
        sortBy: [SortDescriptor(\.effectiveFrom, order: .forward)],
        prefetchOutcomes: true
    )
    for task in tasks {
        print("\(task.id) — effective from \(task.effectiveFrom), outcomes: \(task.outcomes.count)")
    }
} catch {
    print("Query failed: \(error)")
}
```

--------------------------------

### Scheduler.queryEvents(for:predicate:)

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Queries a sorted list of events within a specified date range, optionally filtering by a task predicate. This method returns events along with their completion status.

```APIDOC
## `Scheduler.queryEvents(for:predicate:)` — Query events in a date range

Returns a sorted `[Event]` list of all events (including their completion status) that fall within the given `Range<Date>`. An optional `Predicate<Task>` allows pre-filtering which tasks are considered.

### Method
`queryEvents(for:predicate:)`

### Parameters
- **for** (`Range<Date>`): The date range to query events within.
- **predicate** (`Predicate<Task>`, optional): An optional predicate to filter tasks.

### Request Example
```swift
import SpeziScheduler
import Foundation

let today = Calendar.current.startOfDay(for: .now)
let tomorrow = Calendar.current.date(byAdding: .day, value: 1, to: today)!

do {
    let events = try scheduler.queryEvents(for: today..<tomorrow)
    for event in events {
        let status = event.isCompleted ? "✅ completed" : "⏳ pending"
        print("\(event.task.title) at \(event.occurrence.start) — \(status)")
    }
} catch {
    print("Failed to query events: \(error)")
}

// Query events for a specific task only
do {
    let taskEvents = try scheduler.queryEvents(
        for: today..<tomorrow,
        predicate: #Predicate { task in task.id == "daily-questionnaire" }
    )
    print("Questionnaire events today: \(taskEvents.count)")
} catch {
    print("Query failed: \(error)")
}
```

### Response
- **Success Response**: Returns a sorted `[Event]` array.
- **Error Response**: Throws an error if the query fails.
```

--------------------------------

### Create or Update Task

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Details the `createOrUpdateTask` function, which creates a new task or updates an existing one if parameters have changed. It also describes the potential `Scheduler.DataError.shadowingPreviousOutcomes` error.

```APIDOC
## `Scheduler.createOrUpdateTask(...)` — Create or update a task

Creates a new `Task` if no task with the given `id` exists, or creates a new version of the existing task if any of the provided parameters differ. Returns a `(task: Task, didChange: Bool)` tuple. Throws `Scheduler.DataError.shadowingPreviousOutcomes` if the new `effectiveFrom` date would shadow already-recorded outcomes and `shadowedOutcomesHandling` is `.throwError`.

```swift
import SpeziScheduler

// Create a weekly task, every Monday at 8am, starting this week
do {
    let (task, didChange) = try scheduler.createOrUpdateTask(
        id: "weekly-weight-check",
        title: "Weight Measurement",
        instructions: "Perform a new weight measurement with your Bluetooth scale.",
        category: Task.Category("Measurement", systemName: "scalemass.fill"),
        schedule: .weekly(weekday: .monday, hour: 8, minute: 0, startingAt: .today),
        completionPolicy: .afterStart,
        scheduleNotifications: true,
        notificationThread: .task,
        tags: ["measurement"]
    ) {
        // Attach custom metadata to the Task.Context via @Property
        context in
        context.measurementType = .weight
    }
    print("Task created or updated: \(didChange), id: \(task.id)")
} catch Scheduler.DataError.shadowingPreviousOutcomes {
    print("Cannot update: would shadow existing outcomes.")
} catch {
    print("Unexpected error: \(error)")
}
```
```

--------------------------------

### Update Task and Handle Shadowed Outcomes

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Update an existing task, which creates a new version effective from the current time. Specify how to handle outcomes that would be shadowed by the update.

```swift
// Update a task (creates a new version effective from now)
do {
    try scheduler.createOrUpdateTask(
        id: "daily-questionnaire",
        title: "Daily Questionnaire",
        instructions: "Updated: Please fill out the questionnaire twice daily.",
        schedule: .daily(hour: 9, minute: 0, startingAt: .today),  // unchanged
        shadowedOutcomesHandling: .delete  // remove outcomes that would be shadowed
    )
} catch {
    print("Update error: \(error)")
}
```

--------------------------------

### Extend Task.Context and Outcome with @Property Macro

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

The @Property macro simplifies adding custom, Codable-backed metadata to Task.Context and Outcome. Use it to store custom data without subclassing.

```swift
extension Task.Context {
    @Property var measurementType: MeasurementType?
    @Property var priority: Int = 1
}
```

```swift
extension Outcome {
    @Property(coding: .json) var measurement: WeightMeasurement?
    @Property var notes: String?
}
```

```swift
try scheduler.createOrUpdateTask(
    id: "weight-task",
    title: "Weight Check",
    instructions: "Record your weight.",
    schedule: .weekly(weekday: .monday, hour: 8, minute: 0, startingAt: .today)
) { context in
    context.measurementType = .weight
    context.priority = 2
}
```

```swift
let tasks = try scheduler.queryTasks(for: Date.now...Date.now)
if let task = tasks.first {
    let type = task.measurementType  // Task supports @dynamicMemberLookup for Context
    print("Measurement type: \(String(describing: type))")
}
```

```swift
let outcome = try event.complete {
    outcome.measurement = WeightMeasurement(value: 72.4, unit: .kilograms)
    outcome.notes = "Measured after breakfast"
}
```

--------------------------------

### Query Events in Date Range with Predicate

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Query events within a specified date range. An optional predicate can filter tasks.

```swift
import SpeziScheduler
import Foundation

// Query all events for today
let today = Calendar.current.startOfDay(for: .now)
let tomorrow = Calendar.current.date(byAdding: .day, value: 1, to: today)!

do {
    let events = try scheduler.queryEvents(for: today..<tomorrow)
    for event in events {
        let status = event.isCompleted ? "✅ completed" : "⏳ pending"
        print("\(event.task.title) at \(event.occurrence.start) — \(status)")
    }
} catch {
    print("Failed to query events: \(error)")
}

// Query events for a specific task only
do {
    let taskEvents = try scheduler.queryEvents(
        for: today..<tomorrow,
        predicate: #Predicate { task in task.id == "daily-questionnaire" }
    )
    print("Questionnaire events today: \(taskEvents.count)")
} catch {
    print("Query failed: \(error)")
}
```

--------------------------------

### Complete an Event with Outcome Metadata

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Completes an event, persisting an Outcome with optional custom metadata. Handles potential errors if the task's completion policy prevents immediate completion.

```swift
import SpeziScheduler

// Completing an event (respects task.completionPolicy by default)
do {
    let events = try scheduler.queryEvents(for: Date.today..<Date.tomorrow)
    for event in events where !event.isCompleted {
        do {
            let outcome = try event.complete {
                // Store custom metadata on the outcome via @Property
                outcome.notes = "Completed via Bluetooth scale"
            }
            print("Outcome recorded at \(outcome.completionDate)")
        } catch Event.CompletionError.preventedByCompletionPolicy {
            print("Cannot complete \(event.task.title) yet — policy: \(event.task.completionPolicy)")
        }
    }
} catch {
    print("Query error: \(error)")
}

// Force-complete ignoring the completion policy
let _ = try? event.complete(ignoreCompletionPolicy: true)
```

--------------------------------

### Define Schedules for Events

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Define one-time or recurring events using the Schedule type, with various convenience constructors and custom recurrence rules. Supports different duration types and retrieving occurrences within a range.

```swift
import SpeziScheduler
import Foundation

// One-time event tomorrow at noon
let nextNoon = Calendar.current.date(bySettingHour: 12, minute: 0, second: 0, of: .tomorrow)!
let onceSchedule: Schedule = .once(at: nextNoon, duration: .duration(.seconds(3600)))

// Daily at 8:30 AM, indefinitely
let dailySchedule: Schedule = .daily(hour: 8, minute: 30, startingAt: .today)

// Every 2 weeks on Wednesday at 10 AM, stopping after 10 occurrences
let biweeklySchedule: Schedule = .weekly(
    interval: 2,
    weekday: .wednesday,
    hour: 10,
    minute: 0,
    startingAt: .today,
    end: .afterOccurrences(10)
)

// Monthly on the 1st at 9 AM
let monthlySchedule: Schedule = .monthly(day: 1, hour: 9, minute: 0, startingAt: .today)

// Yearly on July 4th at midnight
let yearlySchedule: Schedule = .yearly(month: 7, day: 4, hour: 0, minute: 0, startingAt: .today)

// Custom recurrence: first weekend day of each month
var customRule = Calendar.RecurrenceRule.monthly(calendar: .current, end: .afterOccurrences(6))
customRule.weekdays = [.nth(1, .saturday), .nth(1, .sunday)]
customRule.setPositions = [1]
let customSchedule = Schedule(startingAt: .today, recurrence: customRule)

// Retrieve occurrences in a range
let occurrences = dailySchedule.occurrences(in: Date.now..<Date.nextWeek)
for occ in occurrences {
    print("Occurrence: \(occ.start) – \(occ.end)")
}
```

--------------------------------

### Reactive Event List with @EventQuery

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Uses the @EventQuery property wrapper to fetch and display events reactively in a SwiftUI view. It automatically updates the view when tasks or outcomes change and provides access to fetch errors.

```swift
import SpeziScheduler
import SpeziSchedulerUI
import SwiftUI

struct ScheduleView: View {
    // Query all events for today
    @EventQuery(in: .today..<Date.tomorrow)
    private var events

    // Query events for a specific task category
    @EventQuery(
        in: .today..<Date.tomorrow,
        predicate: #Predicate { task in task.tags.contains("survey") }
    )
    private var surveyEvents

    var body: some View {
        Group {
            if let error = $events.fetchError {
                ContentUnavailableView("Error", systemImage: "exclamationmark.triangle") {
                    Text(error.localizedDescription)
                }
            } else {
                List(events) {
                    InstructionsTile(event) {
                        try? event.complete()
                    }
                }
            }
        }
    }
}
```

--------------------------------

### Schedule

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Defines the occurrence pattern for events, wrapping a `Calendar.RecurrenceRule`. It supports one-time or recurring events with various durations and recurrence rules.

```APIDOC
## `Schedule` — Define when events occur

`Schedule` wraps a `Calendar.RecurrenceRule` and a start `Date` to describe one-time or recurring events. Convenience static constructors cover the most common recurrence patterns. The `duration` property controls whether an event spans the entire day (`.allDay`), ends at the end of the day (`.tillEndOfDay`), or lasts a fixed time interval.

### Properties
- **startingAt** (`Date`): The start date of the schedule.
- **recurrence** (`Calendar.RecurrenceRule`): The recurrence rule for the schedule.
- **duration** (`Schedule.Duration`): The duration of the event.

### Static Constructors
- `.once(at: Date, duration: Schedule.Duration)`
- `.daily(hour: Int, minute: Int, startingAt: Date, end: Schedule.RecurrenceEnd?)
- `.weekly(interval: Int, weekday: Calendar.Weekday, hour: Int, minute: Int, startingAt: Date, end: Schedule.RecurrenceEnd?)
- `.monthly(day: Int, hour: Int, minute: Int, startingAt: Date, end: Schedule.RecurrenceEnd?)
- `.yearly(month: Int, day: Int, hour: Int, minute: Int, startingAt: Date, end: Schedule.RecurrenceEnd?)

### Methods
- `occurrences(in: Range<Date>) -> [Occurrence]`

### Request Example
```swift
import SpeziScheduler
import Foundation

// One-time event tomorrow at noon
let nextNoon = Calendar.current.date(bySettingHour: 12, minute: 0, second: 0, of: .tomorrow)!
let onceSchedule: Schedule = .once(at: nextNoon, duration: .duration(.seconds(3600)))

// Daily at 8:30 AM, indefinitely
let dailySchedule: Schedule = .daily(hour: 8, minute: 30, startingAt: .today)

// Every 2 weeks on Wednesday at 10 AM, stopping after 10 occurrences
let biweeklySchedule: Schedule = .weekly(
    interval: 2,
    weekday: .wednesday,
    hour: 10,
    minute: 0,
    startingAt: .today,
    end: .afterOccurrences(10)
)

// Monthly on the 1st at 9 AM
let monthlySchedule: Schedule = .monthly(day: 1, hour: 9, minute: 0, startingAt: .today)

// Yearly on July 4th at midnight
let yearlySchedule: Schedule = .yearly(month: 7, day: 4, hour: 0, minute: 0, startingAt: .today)

// Custom recurrence: first weekend day of each month
var customRule = Calendar.RecurrenceRule.monthly(calendar: .current, end: .afterOccurrences(6))
customRule.weekdays = [.nth(1, .saturday), .nth(1, .sunday)]
customRule.setPositions = [1]
let customSchedule = Schedule(startingAt: .today, recurrence: customRule)

// Retrieve occurrences in a range
let occurrences = dailySchedule.occurrences(in: Date.now..<Date.nextWeek)
for occ in occurrences {
    print("Occurrence: \(occ.start) – \(occ.end)")
}
```
```

--------------------------------

### Delete Task Versions

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Permanently delete a specific task version and all its future versions, or delete all versions of a logical task.

```swift
import SpeziScheduler

// Fetch the latest version of a task and delete it (and all future versions)
do {
    let tasks = try scheduler.queryTasks(for: Date.now...Date.now)
    if let taskToDelete = tasks.first(where: { $0.id == "old-task" && $0.isLatestVersion }) {
        try scheduler.deleteTasks(taskToDelete)
    }
} catch {
    print("Delete failed: \(error)")
}

// Remove all versions of a task by its string ID
do {
    try scheduler.deleteAllVersions(ofTask: "weekly-weight-check")
    print("All versions deleted.")
} catch {
    print("Delete all versions failed: \(error)")
}
```

--------------------------------

### Manually Schedule Notification Refresh

Source: https://context7.com/stanfordspezi/spezischeduler/llms.txt

Call this method after the user has granted notification permission when automaticallyRequestProvisionalAuthorization is set to false.

```swift
// If automaticallyRequestProvisionalAuthorization is false,
// call this after the user grants notification permission:
scheduler.manuallyScheduleNotificationRefresh()
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.