# Feature: Availability Management

## Overview
Instructors define date/time windows during which they are available for private lessons. Students book from these windows. Windows carry a lesson length and may be generated as a weekly-recurring series.

## Data Model — `{prefix}us_availability`

| Column             | Type             | Notes                                                        |
|--------------------|------------------|-------------------------------------------------------------|
| `id`               | BIGINT UNSIGNED  | Primary key                                                 |
| `instructor_id`    | BIGINT UNSIGNED  | WordPress user ID                                           |
| `offering_id`      | BIGINT UNSIGNED  | Nullable FK → `us_offerings.id` (private-lesson type)       |
| `start_dt`         | DATETIME         | Slot start — stored as `Y-m-d H:i:s`                        |
| `end_dt`           | DATETIME         | Slot end — stored as `Y-m-d H:i:s`                          |
| `duration_minutes` | SMALLINT         | Lesson length the window accommodates (e.g. 30, 60)         |
| `is_booked`        | TINYINT(1)       | 0 = available, 1 = booked                                  |
| `recurrence_group` | BIGINT UNSIGNED  | Nullable — weekly-recurring windows share one group id     |
| `created_at`       | DATETIME         | Insertion time                                             |

A window's `duration_minutes` is matched against the offering a student picks: a
30-minute private offering can only be booked into a window whose
`duration_minutes` accommodates it.

## Weekly-Recurring Windows
Instructors may generate a window weekly across a date range. Each occurrence is a
separate row sharing one `recurrence_group` id, so a recurring set can be added or
removed together while individual occurrences are still booked independently.

## Admin Interface
Instructors access **My Availability** in wp-admin (`?page=us-availability`).
- Add a slot: provide start/end datetime, duration, and (optionally) a linked private-lesson offering
- Add a weekly series: provide the weekday/time plus a date range
- Delete a slot: only allowed if `is_booked = 0`

## Public Calendar
The front-end booking shortcode renders a month/week calendar of open windows,
populated from `GET /availability`. Students can filter by instructor and by
offering/duration before selecting a slot to register for.

## REST API
| Method   | Endpoint                                      | Permission                         |
|----------|-----------------------------------------------|------------------------------------|
| `GET`    | `/wp-json/us-scheduler/v1/availability`       | `book_lesson`                      |
| `POST`   | `/wp-json/us-scheduler/v1/availability`       | `manage_availability`              |
| `DELETE` | `/wp-json/us-scheduler/v1/availability/{id}`  | `manage_availability` + slot owner |

`GET` supports query params: `instructor_id`, `offering_id`, `duration_minutes`, `from` (datetime), `to` (datetime).

## Implementation
- Repository: `Unsupervised\Schedular\Availability\AvailabilityRepository`
- Model: `Unsupervised\Schedular\Availability\AvailabilitySlot`
- Admin controller: `Unsupervised\Schedular\Availability\AvailabilityController`
- REST endpoint: `Unsupervised\Schedular\Availability\AvailabilityEndpoint`

## Tests
- `tests/Unit/Availability/AvailabilityRepositoryTest.php`
- `tests/Unit/Availability/AvailabilitySlotTest.php`