room-booking/README.md

Room Booking
---

This application allows you to 

1. create an event in a room booking calendar via a REST API. 
2. delete an event in a room booking calendar via a REST API. 
3. clear overlapping and canceled events in a room booking calendar via a REST
   API.

## Setup

If you see this page, the application is already running.

You will have to create users, API keys and calendars
via [admin interface](/admin).

## Usage

A full documentation of the API is available at [`/api/docs/`](/api/docs).

Authentication is done via a Bearer token in the `Authorization` header.

### Create an event

To create an event, you need to send a POST request to `/api/{calendar}/events/`
with the following JSON payload:

```json
{
  "name": "Event Title",
  "start": "2025-01-02T12:00:00",
  "end": "2025-01-02T13:00:00"
}
```

Curl example:
```bash
 curl -s \
   -H "Authorization: Bearer secrettoken" \
   -H "Content-Type: application/json" \
   -d "{\"name\": \"Test-Event\", \"start\": \"$(date --iso-8601=minutes)\", \"end\": \"$(date --iso-8601=minutes -d '+2 hours')\"}" \
   localhost:8000/api/test-kalender/event
```

The response will contain the event ID:

```json
{"id": "4zx3QAFzoxV3vaZSKGaH2S"}
```

### Delete an event

To delete an event, you need to send a DELETE request to `/api/{calendar}/events/{event_id}`.

Curl example:
```bash
curl -s -X DELETE \
  -H "Authorization: Bearer secrettoken" \
  -H "Content-Type: application/json" \
  localhost:8000/api/test-kalender/event/4zx3QAFzoxV3vaZSKGaH2S
```

The response will be empty but the status code will be `204`.

### Clear overlapping and canceled events

To clear overlapping and canceled events, you need to send a DELETE request to
`/api/clear-bookings`.

The following parameters can be passed as query parameters:

- `calendar`: The calendar to clear overlapping events from. If not specified,
  all calendars of the user will be cleared.
- `test`: If set to `1` or `ok`, the API will not delete any events but only
  return what would be deleted.

Curl example:
```bash
curl -s -X DELETE \
  -H "Authorization: Bearer secrettoken" \
  localhost:8000/api/clear-bookings?calendar=meeting-room-1&test=on" | jq "."
```

The response will contain a list of events that would be deleted:

```json
{
  "deleted_cancelled_events": [],
  "deleted_overlapping_events": [
    {
      "event": {
        "uid": "abeda082-2a4b-48a7-a92a-ba24575622ae",
        "name": "Fundraising Weekly",
        "start": "2025-07-14T00:00:00+02:00",
        "end": "2025-07-19T00:00:00+02:00",
        "created": "2025-07-09T15:11:19+02:00",
        "organizer": "head-of-fundraising@my-awesome.org"
      },
      "overlaps_with": {
        "uid": "2051008d-6ce2-4489-b7d9-38d164c5e66e",
        "name": "Finance Monthly",
        "start": "2025-07-15T10:00:00+02:00",
        "end": "2025-07-15T12:00:00+02:00",
        "created": "2025-01-14T08:33:20+01:00",
        "organizer": "head-of-finance@my-awesome.org"
      },
      "calendar": "meeting-room-1"
    }
  ],
  "cancelled_overlapping_recurring_events": [
    {
      "event": {
        "uid": "be6d2d42-513b-45ca-bb43-663e2a10a1d7",
        "name": "Job Interviews",
        "start": "2025-07-14T14:00:00+02:00",
        "end": "2025-07-14T15:00:00+02:00",
        "created": "2025-06-30T12:04:14+02:00",
        "organizer": "head-of-hr@my-awesome.org"
      },
      "overlaps_with": {
        "uid": "f2b7b703-dfba-4ae7-a0e9-bf0e7637c7e4",
        "name": "Workers Council Meeting",
        "start": "2025-07-14T14:00:00+02:00",
        "end": "2025-07-14T15:00:00+02:00",
        "created": "2025-02-10T12:33:39+01:00",
        "organizer": "workers-council@my-awesome.org"
      },
      "calendar": "meeting-room-2"
    }
  ],
  "ignored_overlapping_events": [],
  "test_mode": true
}
```

#### Email Notifications

The organizer of the events will be notified via email about the deletion of
their event if an email template is configured for the calendar.

The following environment variables can be set to configure the application:

- `SMTP_EMAIL` - The email address to use as the sender for notification emails.
- `SMTP_PASSWORD` - The password for the SMTP email account.
- `SMTP_SERVER` - The SMTP server to use for sending emails.
- `SMTP_USER_NAME` - The username for the SMTP email account. If not set, the
  `SMTP_EMAIL` will be used as the username.
- `SMTP_SENDER_NAME` - The name to use as the sender for notification emails.
- `SMTP_BCC` - A comma-separated list of email addresses to BCC on notification
  emails.
- `SMTP_STARTTLS` - Whether to use STARTTLS for the SMTP connection. Defaults to
  `False`, so SSL is used instead.
- `SMTP_PORT` - The port to use for the SMTP connection. Defaults to `465` for
  SSL and
  `587` for STARTTLS.

Email templates can be configured in the Django Admin interface. Jinja2 syntax
is used for the templates. The following variables are available in the
templates:

- `name` - The name of the event
- `start` - The start time (datetime) of the event
- `end` - The end time (datetime) of the event
- `created` - The datetime the event was created
- `is_deleted` - Whether the event was deleted
- `is_cancelled` - Whether the event was cancelled
- `is_recurring` - Whether the event is recurring
- `is_priorized` - Whether the event is prioritized
- `is_deprioritized` - Whether the event is deprioritized in favor of another
  event
- `organizer` - The organizer of the event
- `overlap_events` - A list of overlap events, each containing:
  - `name` - The name of the overlap event
  - `start` - The start time (datetime) of the overlap event
  - `end` - The end time (datetime) of the overlap event
  - `created` - The datetime the overlap event was created
  - `organizer` - The organizer of the overlap event
  - `is_priorized` - Whether the overlap event is prioritized
- `calendar_name` - The name of the calendar