# Calendar Admin Services

This directory contains services related to calendar functionality that are intended to be used exclusively in a server-side (admin) environment. These services may contain sensitive logic, such as OAuth handling and direct API interactions with external providers like Google Calendar.

## Services

### `calendar.admin.service.ts` — CalendarAdminService

Manages calendar events for practitioners, patients, and clinics. Used by the `AppointmentAggregationService` to update calendar event statuses and times during the appointment lifecycle.

**Key methods:**
- `updateAppointmentCalendarEventStatus(appointment, newStatus)` — Updates the status of all calendar events for an appointment
- `updateAppointmentCalendarEventTime(appointment, newEventTime)` — Updates the time range of calendar events (on reschedule)
- `deleteAppointmentCalendarEvents(appointment)` — Deletes all calendar events for a deleted appointment

---

### `resource-calendar.admin.ts` — ResourceCalendarAdminService

Manages calendar events on **resource instances** throughout the appointment lifecycle. This service is part of the [Clinic Resources System](../../../../docs/RESOURCE_SYSTEM.md).

**Constructor:**
```typescript
constructor(firestore?: admin.firestore.Firestore)
```

**Methods:**

#### `updateResourceBookingEventsStatus(appointment, newStatus)`
Updates the status of all resource calendar events for an appointment. Iterates through `appointment.resourceBookings` and updates each event's `status` and `updatedAt`.

**Firestore path:** `clinics/{clinicBranchId}/resources/{resourceId}/instances/{instanceId}/calendar/{calendarEventId}`

#### `updateResourceBookingEventsTime(appointment, newEventTime)`
Updates the time range of all resource calendar events (used during reschedule). Updates `eventTime.start`, `eventTime.end`, and `updatedAt`.

#### `deleteResourceBookingEvents(appointment)`
Deletes all resource calendar events for a deleted appointment. Uses a Firestore batch to delete all events atomically.

**Lifecycle integration:** Called by `AppointmentAggregationService` during appointment transitions:

| Transition | Action |
|---|---|
| PENDING → CONFIRMED | `updateResourceBookingEventsStatus(after, CONFIRMED)` |
| RESCHEDULED → CONFIRMED | `updateResourceBookingEventsStatus(after, CONFIRMED)` |
| Any → CANCELLED / NO_SHOW | `updateResourceBookingEventsStatus(after, CANCELLED)` |
| Any → COMPLETED | `updateResourceBookingEventsStatus(after, COMPLETED)` |
| RESCHEDULED_BY_CLINIC | `updateResourceBookingEventsTime()` + `updateResourceBookingEventsStatus(after, PENDING)` |
| Time change (same status) | `updateResourceBookingEventsTime()` |
| Appointment deleted | `deleteResourceBookingEvents()` |

**Safety:** All methods check for `appointment.resourceBookings` before proceeding. If no resource bookings exist (backward-compatible appointments), the methods return early.

---

### `synced-calendars.service.ts`

Manages the synchronization of calendars with external providers. It should not be used on the client side.

## Export

`index.ts` exports `CalendarAdminService` and `ResourceCalendarAdminService`.
