# Verhalenboek Een verhalenboek: elke kalenderdag heeft een titel en precies drie verhalen. Lezers zien wat ze al gelezen hebben. Een beheerder vult het boek, met de hand of via een API-sleutel. Inloggen gaat via [auth.timfalken.com](https://auth.timfalken.com). De applicatie staat in [`web/`](web/). Lokaal: ```sh php -S 127.0.0.1:8080 -t web web/router.php ``` Open http://127.0.0.1:8080. Je bent automatisch `test_user_1` en daarmee beheerder. Onder Instellingen wissel je naar `test_user_2`, een gewone lezer. ## Publieke URL Microchess staat op `https://projects.timfalken.com/microchess` omdat die map de FTP-map onder de site `projects.timfalken.com` is. Hier is de CI-variabele `projectftp` gelijk aan `$timftproot/verhaaltjesboek`. Dezelfde afleiding geeft: **https://projects.timfalken.com/verhaaltjesboek** ## Wat Tim moet instellen Deploy naar `master` zet de code op de server, maar raakt `data/` niet aan. Daarin blijven de database, sessies en het geheim staan. Bij de eerste paginabezoek maakt de app `data/config.php` aan als dat bestand er nog niet is. Een bestaand bestand wordt nooit overschreven. 1. Zet de code op `master` (de pipeline test eerst, en uploadt daarna alleen bij een groene `master`). 2. Open eenmaal https://projects.timfalken.com/verhaaltjesboek zodat `data/config.php` ontstaat. Het bestand staat op de server in de FTP-map `verhaaltjesboek/data/config.php` (`projectftp` + `/data/config.php`). 3. Registreer bij https://auth.timfalken.com/admin het callback-pad op het domein `projects.timfalken.com`: - **client_id:** `projects.timfalken.com` (het domein van de publieke URL, hetzelfde domein als microchess) - **callback-pad:** `/verhaaltjesboek/callback.php` - Voeg alleen dat pad toe. Genereer het clientgeheim niet opnieuw als microchess hetzelfde domein al gebruikt: een nieuw geheim maakt de andere site stuk. Kopieer het bestaande geheim. 4. Vul op de server `data/config.php` in. Dit bestand wordt niet gecommit en niet geüpload. Laat `key_secret` staan: die maakt de app zelf aan (64 hexadecimale tekens) en versleutelt daarmee API-sleutels, zodat een beheerder ze later opnieuw kan tonen. Ontbreekt hij, dan vult de app hem één keer aan zonder de andere velden te wissen. ```php 'https://projects.timfalken.com/verhaaltjesboek', 'client_id' => 'projects.timfalken.com', 'client_secret' => 'het-geheim-uit-admin', 'key_secret' => 'blijft-de-gegenereerde-waarde', ]; ``` Lege velden voor URL en client vallen terug op `VERHALENBOEK_BASE_URL`, `VERHALENBOEK_CLIENT_ID` en `VERHALENBOEK_CLIENT_SECRET`. Een ingevuld veld wint van de omgeving. `base_url` mag een submap bevatten en heeft geen slash aan het eind. `key_secret` komt niet uit de omgeving. 5. Log als eerste zelf in. Die eerste gebruiker wordt beheerder. Iedereen daarna is lezer. Het account-id en de gebruikersnaam komen uit `/api/me`. E-mail wordt niet gelezen en niet opgeslagen. Onder **Beheer** zie je alle gebruikers. Daar maak je iemand anders beheerder, of haal je die rol weer weg. Je kunt je eigen beheerdersrol niet uitzetten, zodat er altijd minstens één beheerder blijft. 6. Maak onderaan **Beheer** een API-sleutel voor de schrijver-agent. De volledige sleutel (`vb_…`) verschijnt meteen, en daarna opnieuw als je op die sleutel tikt. Alleen een ingelogde beheerder ziet dat; de lijst en de export tonen alleen het voorvoegsel. Een oud adres `#/sleutels` komt op diezelfde Beheer-pagina uit. De OAuth-flow is dezelfde als bij microchess: `state`, code wisselen op de server via `POST /oauth/token`, daarna `GET /api/me`, verlengen via `POST /api/session/extend`, en afmelden via `POST /api/logout`. Het bearer-token van het account blijft in de PHP-sessie en komt niet in JavaScript. ## Leesstatus Een dag wordt gelezen zodra de dagpagina opent, niet pas onderaan. Korte verhalen passen vaak op één scherm, dus "onderaan" is dan hetzelfde als openen, of het gebeurt juist nooit. Opnieuw openen houdt de dag gelezen. Per ongeluk geopend? Houd de dag in het overzicht ingedrukt (telefoon) of klik met de rechtermuisknop (desktop) en kies ongelezen. Het standaardmenu en tekstselectie blijven tijdens die handeling uit. **Verderlezen** opent de vroegste ongelezen dag van het hele boek, ook als die buiten de week valt die je nu ziet. Het aantal ongelezen dagen is hetzelfde totaal, zodat het klopt met die knop. Standaard volgen kleuren het systeem; het lettertype is een serif. Licht, donker, serif, schreefloos en rond worden per gebruiker op de server bewaard. ## Weekoverzicht Het overzicht toont één kalenderweek, maandag tot en met zondag. Dagen zonder verhaal blijven weg. Zonder `#/week/JJJJ-MM-DD` — ook bij het openen zonder hash, en bij de geïnstalleerde app waarvan `start_url` `/verhaaltjesboek/` is — opent het overzicht de week waarin de vroegste ongelezen dag valt. Dat is de vroegste datum met een dagrecord en zonder rij in `reads` voor deze lezer; een dagrecord zonder verhalen telt mee. Zijn alle dagen gelezen, dan blijft het de week van de laatst gelezen dag. Zonder dagen is het de huidige kalenderweek. Een gekozen `#/week/JJJJ-MM-DD` of een dagpagina blijft die route. **Vorige week** en **Volgende week** staan boven de lijst, met het bereik erbij, bijvoorbeeld `5–11 oktober 2026`. Een knop staat er alleen als die aangrenzende kalenderweek minstens één dagrecord heeft, ook als die dag onvolledig is. Een lege week ertussen verbergt de knop; hij springt niet naar een latere week met dagen. Via `#/week/JJJJ-MM-DD` blijft een lege week wel bereikbaar. Op de dagpagina blijven **Vorige dag** en **Volgende dag** de aangrenzende geschreven dagen. Die knoppen springen niet naar een andere week. Rechtsonder op een dagkaart staan tot vijf kleine rondjes: vrienden die díe dag gelezen hebben. De lijst komt uit `GET /api/friends` op auth.timfalken.com (`id`, `username`, `avatar_url`). De app haalt die lijst server-side op met het bearer-token uit de sessie, dezelfde weg als `/api/me`. Het token komt niet in JavaScript. De browser toont alleen de foto; `avatar_url` mag een pad `/avatar/{id}?v=…` zijn of de absolute URL op `https://auth.timfalken.com`. Een ander adres wordt genegeerd. Zonder foto komt de eerste letter van de naam in een neutraal rondje. Een vriend telt voor een dag als het account `auth:{id}` een rij in `reads` heeft voor die dag. Iemand die dit boek nog nooit opende, heeft geen rij en blijft weg. De eigen lezer staat er niet bij. Meer dan vijf vrienden: de vijf met de recentste leeshandeling (`read_at`), en bij een gelijk moment op naam en daarna op id. Lukt de vriendenlijst niet, dan blijven de kaarten gewoon staan, gelezen of ongelezen. Lokaal is er geen auth-lijst; elk ander account in deze database telt dan als vriend, zonder foto. ## API Schrijven kan met een Bearer-sleutel of, in de browser, als beheerder. Een volledige dag heeft precies drie verhalen, elk met een titel en minstens één alinea. De volgorde in de lijst is plek 1, 2 en 3. `GET /api.php/days/latest` is de nieuwste datum die nog een dagrecord heeft, ook als daar een verhaal uit verwijderd is (`complete` is dan `false`). Ontbreekt er nog niets, dan is het antwoord 404. `GET /api.php/days/gaps` geeft, tussen de eerste en de laatste dag: - `missing`: kalenderdagen zonder dagrecord (verwijderd of nooit geschreven) - `incomplete`: dagen die bestaan maar geen drie verhalen meer hebben, met `missingPositions` Een onvolledige dag staat niet óók in `missing`. Staat een datum in `missing`, maak hem met POST. Staat hij in `incomplete`, vul de plek of vervang de dag met PUT en precies drie verhalen. ```sh curl -sS -X POST \ -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{"date":"2026-10-05","title":"De herfstwind","stories":[ {"title":"Ochtend","paragraphs":["De wind stond al vroeg aan de deur."]}, {"title":"Middag","paragraphs":["Op het plein joeg een krant zichzelf achterna."]}, {"title":"Avond","paragraphs":["Het licht in de keuken bleef aan."]} ]}' \ 'https://projects.timfalken.com/verhaaltjesboek/api.php/days' curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \ 'https://projects.timfalken.com/verhaaltjesboek/api.php/days/latest' curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \ 'https://projects.timfalken.com/verhaaltjesboek/api.php/days/gaps' ``` | Methode | Pad | Betekenis | | --- | --- | --- | | GET | `/days` | Dagen, oudste eerst. Een ingelogde lezer ziet ook `read`. Daarnaast `lastRead`, `week` (maandag–zondag, met `previous`, `next`, `label`, `hasPrevious` en `hasNext`) en `weekDays`. `previous` en `next` blijven de maandag van de buurweek. `hasPrevious` en `hasNext` zijn waar als die buurweek minstens één dagrecord heeft. `?week=JJJJ-MM-DD` kiest een week. Zonder die parameter is het, voor een ingelogde lezer, de week van de vroegste ongelezen dag; zijn alle dagen gelezen, dan de week van `lastRead`; zonder dagen de week van `?today=` of vandaag. Een API-sleutel heeft geen leesstatus: dan de week van de nieuwste dag, anders van `?today=` of vandaag. | | GET | `/days/latest` | Nieuwste geschreven datum. | | GET | `/days/gaps` | Gaten en onvolledige dagen. | | GET | `/days/JJJJ-MM-DD` | Dag, verhalen, `previous` en `next`. | | POST | `/days` | Nieuwe dag met precies drie verhalen. 201, of 409 als de datum bezet is. | | PUT | `/days/JJJJ-MM-DD` | Titel en/of vervanging door precies drie verhalen. | | DELETE | `/days/JJJJ-MM-DD` | Dag weg. | | POST | `/days/JJJJ-MM-DD/stories` | Verhaal erbij zolang er minder dan drie zijn. | | PUT | `/days/JJJJ-MM-DD/stories/1` | Plek 1, 2 of 3 bijwerken. | | DELETE | `/days/JJJJ-MM-DD/stories/2` | Eén verhaal weg; de andere plekken blijven. | | POST / DELETE | `/days/JJJJ-MM-DD/read` | Alleen een ingelogde lezer. | | GET | `/friend-reads` | Alleen een ingelogde lezer, niet met een API-sleutel. Per datum tot vijf vrienden die die dag lazen: `id`, `name`, `avatar_url`. Recentste leeshandeling eerst. | | PUT | `/me/settings` | `theme`: `system`, `light` of `dark`. `font`: `serif`, `sans` of `rounded`. | | GET | `/me/export` | Eigen gegevens als JSON. | Fouten zijn `{"error":"…"}`. Validatie die de drie-verhalenregel raakt geeft 422. De menselijke uitleg met dezelfde voorbeelden staat op `docs.php`. Een 401 (geen header, verkeerd formaat, of een onbekende/ingetrokken sleutel) zet `WWW-Authenticate: Bearer` en voegt `how_to_authenticate` toe, met dezelfde tekst in `hint`. Die tekst noemt het geval, de header `Authorization: Bearer vb_…`, Beheer op `{base_url}/#/beheer`, en een link naar `docs.php`. Een 403 omdat een lezer iets doet dat een sleutel of beheerder vereist, heeft die uitleg ook, zonder `WWW-Authenticate`. Sleutels zelf beheren kan alleen in de beheerderssessie, onderaan Beheer. Een 403 door een ongeldige CSRF-header blijft alleen `{"error":"…"}`. ```sh curl -sS -D - -o - \ 'https://projects.timfalken.com/verhaaltjesboek/api.php/days/latest' ``` `GET /api.php/keys/{id}` geeft de volledige sleutel terug aan een ingelogde beheerder. Opzoeken bij een verzoek blijft een hash op `token_hash`. ## Deploy `.gitlab-ci.yml` is die van microchess: PHP-syntax, domeintests, API-tests, een JavaScript-syntaxcheck, en een echte FTP-fixture. Alleen `master` uploadt, en nooit tegelijk met een andere productie-deploy. [`ci/deploy.py`](ci/deploy.py) spiegelt `web/` met lftp en slaat `data/` (database, WAL, `config.php`, sessies) over, zowel bij upload als bij verwijderen. `data/.htaccess` wordt apart gezet. `tests/`, `router.php` en `README.md` gaan niet mee. Benodigde CI-variabelen, al aanwezig in dit project: `timftphost`, `timftpuser`, `timftppassword`, `timftproot`, `projectftp` (`$timftproot/verhaaltjesboek`). ## Tests ```sh find web -name '*.php' -not -path '*/artifacts/*' -print0 | xargs -0 -n1 php -l php web/tests/storybook.php python3 web/tests/startup.py python3 web/tests/integration.py node --check web/assets/app.js python3 ci/test_deploy.py ``` De API-tests draaien een kopie onder `web/tests/artifacts/` en laten de echte database met rust.