# CTS API Spike: Auth + Response Shapes

## Ergebnis

- Paket `5pm-hdh/churchtools-api` ist installiert (`2.1.0`).
- `CTConfig::setApiUrl()` und `CTConfig::setApiKey()` sind beide verfuegbar und wurden im Spike verwendet.
- `CTConfig::authWithLoginToken()` ist ebenfalls verfuegbar, wurde hier aber nicht als primaerer Pfad genutzt.
- Fallback-Strategie ist dokumentiert: Falls Token-Auth ueber das Paket nicht funktioniert, per Raw HTTP mit Header `Authorization: Login <TOKEN>`.

## Auth-Verifikation

Quelle: `.sisyphus/evidence/task-0-api-auth.txt`

- `setApiKey_exists=yes`
- `authWithLoginToken_exists=yes`
- `cts_api_url_env_present=no`
- `cts_api_token_env_present=no`
- `auth_ok=no`
- `auth_method=none`
- `blocker=CTS_API_TOKEN fehlt; Authentifizierung nicht moeglich.`

Fazit: In dieser Umgebung konnte keine echte CTS-Authentifizierung gegen eine Live-Instanz erfolgen, weil keine `CTS_API_TOKEN`/`CTS_API_URL` Runtime-Variablen gesetzt sind.

## Endpoint-Shape: GET /api/events (today+future)

Abfrage im Spike (Package-Request):

- `EventRequest::where('from', 'YYYY-MM-DD')->get()`
- Daraus entsteht ein Request auf `/api/events` mit Query `from=<date>` und `page=1`.

Mocked Beispiel-Response (relevante Struktur):

```json
{
  "data": [
    {
      "domainIdentifier": "100",
      "title": "Gottesdienst Sonntag",
      "startDate": "2026-03-08T10:00:00+00:00",
      "note": "Probe"
    }
  ],
  "meta": {
    "pagination": {
      "lastPage": 1
    }
  }
}
```

Abgeleitete Event-Felder im Spike:

- `id` (aus `domainIdentifier`)
- `title` (string)
- `start_date` (ISO-String)
- `note` (string|null)

## Endpoint-Shape: GET /api/songs/1

Quelle: `.sisyphus/evidence/task-0-song-ccli.txt`

- `song_has_ccli=yes`
- `song_ccli=1234567`
- `song_has_lyrics=yes`
- `song_arrangements_count=1`
- `raw_song_keys=songId,name,ccli,arrangements,lyrics`

Mocked Beispiel-Response (relevante Struktur):

```json
{
  "data": {
    "songId": "1",
    "name": "Way Maker",
    "ccli": "7115744",
    "arrangements": [
      {
        "id": "11",
        "name": "Normal",
        "isDefault": true
      }
    ],
    "lyrics": {
      "type": "text",
      "cclid": "7115744",
      "lyricParts": [
        {
          "key": "v1",
          "text": "Du bist hier"
        }
      ]
    }
  }
}
```

Fazit Song-Shape:

- `ccli` ist im Song-Response als Feld vorhanden.
- Lyrics koennen als verschachteltes Objekt (`lyrics`) enthalten sein.
- Arrangements liegen als Array unter `arrangements`.

## OpenAPI-Download

Zielpfad waere `docs/churchtools-openapi.json` von `<CTS_API_URL>/system/runtime/swagger/openapi.json`.

Status in diesem Spike:

- Nicht heruntergeladen, da keine lauffaehige `CTS_API_URL` in der Runtime gesetzt war.
- Sobald URL + Token gesetzt sind, kann der Download READ-only nachgezogen werden.