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.
De applicatie staat in web/. Lokaal:
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
return [
'base_url' => '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.
RSS-feed
Lezers kunnen de verhalen volgen in een feedlezer (Atom). De feed staat standaard uit. Een beheerder zet hem aan onder Beheer → RSS-feed. Zolang hij uit staat, ziet niemand de feed-instelling, staat er geen autodiscovery-link in de pagina en geeft elk feed-adres 404.
Staat hij aan, dan maakt elke lezer onder Instellingen → RSS-feed een eigen geheim adres: https://projects.timfalken.com/verhaaltjesboek/feed.php?token=vbf_…. Er is één adres per lezer. Vernieuwen maakt een nieuw adres en maakt het oude ongeldig; Intrekken zet het uit. Het adres staat versleuteld in de database (net als API-sleutels), zodat de lezer het opnieuw kan kopiëren. De ingelogde eigenaar krijgt ook een <link rel="alternate" type="application/atom+xml"> in de HTML-head.
- Eén item per dag, nieuwste eerst, de laatste 60 dagen tot en met vandaag (Europe/Amsterdam). Toekomstige dagen komen pas op hun datum in de feed.
- Het item bevat de dagtitel en alle verhalen van die dag als HTML (titel per verhaal, alinea's), en linkt naar
#/dag/JJJJ-MM-DD. - De wiki zit nooit in de feed. Een feed lezen zet geen dag op gelezen en maakt geen sessie.
- Headers:
Content-Type: application/atom+xml,Cache-Control: private, no-cache,X-Robots-Tag: noindex, nofollow,Referrer-Policy: no-referrer, en eenETag(304 bijIf-None-Match). Een onbekende, ingetrokken of vernieuwde sleutel, of een uitgezette feed, geeft 404. - De service worker cachet
feed.phpnooit.
API (ingelogde sessie): GET/POST/DELETE /api.php/me/feed (tonen, maken of vernieuwen, intrekken; 404 als de feed uit staat), en voor een beheerder GET/PUT /api.php/settings/feed met {"enabled": true}. API-sleutels (Bearer) kunnen de feed niet aan- of uitzetten.
De tabellen app_settings en feed_tokens ontstaan vanzelf bij de eerste request (CREATE TABLE IF NOT EXISTS); bestaande data blijft staan.
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, metmissingPositions
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.
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":"…"}.
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
De code staat op BlueGit: https://git.timfalken.com/projects-timfalken-com/verhalenboek (publiek). GitLab (Timfa/Verhalenboek) is alleen nog een backup en deployt niet meer.
blue-ci-cd.yml draait PHP-syntax, domeintests, API-tests, een JavaScript-syntaxcheck en een echte FTP-fixture. ftp_upload wacht via needs op alle drie testjobs: faalt er één, dan is er geen deploy. Alleen een push naar master uploadt (geen MR-pipelines), en nooit tegelijk met een andere productie-deploy. ci/deploy.py spiegelt web/ met lftp en slaat data/ (database, WAL, config.php, sessies, API-sleutels) over, zowel bij upload als bij verwijderen. data/.htaccess wordt apart gezet. tests/, router.php en README.md gaan niet mee.
Geheimen
| Naam | Waar | Beschermd |
|---|---|---|
timftphost, timftpuser, timftppassword, timftproot | groep projects.timfalken.com (gedeeld door alle projecten op die site) | ja |
projectftp | deze repository ($timftproot/verhaaltjesboek) | ja |
Beschermde geheimen komen alleen mee op de beschermde branch master. MR-pipelines krijgen ze niet. Waarden van acht tekens of meer worden in joblogs vervangen door [MASKED].
Deploy-guard
ci/deploy_guard.py laat de deploy hard falen (DEPLOY GEBLOKKEERD: …) als projectftp niet gezet of leeg is, naar / of . wijst, gelijk is aan timftproot, .. bevat of buiten timftproot ligt. Zo kan een mirror --delete nooit de hele website overschrijven. $timftproot in projectftp wordt door de guard zelf ingevuld, want BlueGit-geheimen verwijzen niet naar elkaar. Zie docs/deploy-guard.md om de guard in een ander project te gebruiken.
Tests
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
python3 web/tests/pwa.py
python3 web/tests/feed.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.
Source
| 1 | # Verhalenboek |
| 2 | |
| 3 | 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). |
| 4 | |
| 5 | De applicatie staat in [`web/`](web/). Lokaal: |
| 6 | |
| 7 | ```sh |
| 8 | php -S 127.0.0.1:8080 -t web web/router.php |
| 9 | ``` |
| 10 | |
| 11 | 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. |
| 12 | |
| 13 | ## Publieke URL |
| 14 | |
| 15 | 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: |
| 16 | |
| 17 | **https://projects.timfalken.com/verhaaltjesboek** |
| 18 | |
| 19 | ## Wat Tim moet instellen |
| 20 | |
| 21 | 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. |
| 22 | |
| 23 | 1. Zet de code op `master` (de pipeline test eerst, en uploadt daarna alleen bij een groene `master`). |
| 24 | 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`). |
| 25 | 3. Registreer bij https://auth.timfalken.com/admin het callback-pad op het domein `projects.timfalken.com`: |
| 26 | - **client_id:** `projects.timfalken.com` (het domein van de publieke URL, hetzelfde domein als microchess) |
| 27 | - **callback-pad:** `/verhaaltjesboek/callback.php` |
| 28 | - 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. |
| 29 | 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. |
| 30 | |
| 31 | ```php |
| 32 | <?php |
| 33 | return [ |
| 34 | 'base_url' => 'https://projects.timfalken.com/verhaaltjesboek', |
| 35 | 'client_id' => 'projects.timfalken.com', |
| 36 | 'client_secret' => 'het-geheim-uit-admin', |
| 37 | 'key_secret' => 'blijft-de-gegenereerde-waarde', |
| 38 | ]; |
| 39 | ``` |
| 40 | |
| 41 | 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. |
| 42 | |
| 43 | 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. |
| 44 | 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. |
| 45 | |
| 46 | 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. |
| 47 | |
| 48 | ## Leesstatus |
| 49 | |
| 50 | 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. |
| 51 | |
| 52 | **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. |
| 53 | |
| 54 | ## RSS-feed |
| 55 | |
| 56 | Lezers kunnen de verhalen volgen in een feedlezer (Atom). De feed staat standaard **uit**. Een beheerder zet hem aan onder **Beheer → RSS-feed**. Zolang hij uit staat, ziet niemand de feed-instelling, staat er geen autodiscovery-link in de pagina en geeft elk feed-adres 404. |
| 57 | |
| 58 | Staat hij aan, dan maakt elke lezer onder **Instellingen → RSS-feed** een eigen geheim adres: `https://projects.timfalken.com/verhaaltjesboek/feed.php?token=vbf_…`. Er is één adres per lezer. **Vernieuwen** maakt een nieuw adres en maakt het oude ongeldig; **Intrekken** zet het uit. Het adres staat versleuteld in de database (net als API-sleutels), zodat de lezer het opnieuw kan kopiëren. De ingelogde eigenaar krijgt ook een `<link rel="alternate" type="application/atom+xml">` in de HTML-head. |
| 59 | |
| 60 | - Eén item per dag, nieuwste eerst, de laatste 60 dagen tot en met vandaag (Europe/Amsterdam). Toekomstige dagen komen pas op hun datum in de feed. |
| 61 | - Het item bevat de dagtitel en alle verhalen van die dag als HTML (titel per verhaal, alinea's), en linkt naar `#/dag/JJJJ-MM-DD`. |
| 62 | - De wiki zit nooit in de feed. Een feed lezen zet geen dag op gelezen en maakt geen sessie. |
| 63 | - Headers: `Content-Type: application/atom+xml`, `Cache-Control: private, no-cache`, `X-Robots-Tag: noindex, nofollow`, `Referrer-Policy: no-referrer`, en een `ETag` (304 bij `If-None-Match`). Een onbekende, ingetrokken of vernieuwde sleutel, of een uitgezette feed, geeft 404. |
| 64 | - De service worker cachet `feed.php` nooit. |
| 65 | |
| 66 | API (ingelogde sessie): `GET/POST/DELETE /api.php/me/feed` (tonen, maken of vernieuwen, intrekken; 404 als de feed uit staat), en voor een beheerder `GET/PUT /api.php/settings/feed` met `{"enabled": true}`. API-sleutels (Bearer) kunnen de feed niet aan- of uitzetten. |
| 67 | |
| 68 | De tabellen `app_settings` en `feed_tokens` ontstaan vanzelf bij de eerste request (`CREATE TABLE IF NOT EXISTS`); bestaande data blijft staan. |
| 69 | |
| 70 | ## Weekoverzicht |
| 71 | |
| 72 | 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. |
| 73 | |
| 74 | Op de dagpagina blijven **Vorige dag** en **Volgende dag** de aangrenzende geschreven dagen. Die knoppen springen niet naar een andere week. |
| 75 | |
| 76 | 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. |
| 77 | |
| 78 | 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. |
| 79 | |
| 80 | ## API |
| 81 | |
| 82 | 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. |
| 83 | |
| 84 | `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. |
| 85 | |
| 86 | `GET /api.php/days/gaps` geeft, tussen de eerste en de laatste dag: |
| 87 | |
| 88 | - `missing`: kalenderdagen zonder dagrecord (verwijderd of nooit geschreven) |
| 89 | - `incomplete`: dagen die bestaan maar geen drie verhalen meer hebben, met `missingPositions` |
| 90 | |
| 91 | 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. |
| 92 | |
| 93 | ```sh |
| 94 | curl -sS -X POST \ |
| 95 | -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \ |
| 96 | -H 'Accept: application/json' \ |
| 97 | -H 'Content-Type: application/json' \ |
| 98 | -d '{"date":"2026-10-05","title":"De herfstwind","stories":[ |
| 99 | {"title":"Ochtend","paragraphs":["De wind stond al vroeg aan de deur."]}, |
| 100 | {"title":"Middag","paragraphs":["Op het plein joeg een krant zichzelf achterna."]}, |
| 101 | {"title":"Avond","paragraphs":["Het licht in de keuken bleef aan."]} |
| 102 | ]}' \ |
| 103 | 'https://projects.timfalken.com/verhaaltjesboek/api.php/days' |
| 104 | |
| 105 | curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \ |
| 106 | 'https://projects.timfalken.com/verhaaltjesboek/api.php/days/latest' |
| 107 | |
| 108 | curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \ |
| 109 | 'https://projects.timfalken.com/verhaaltjesboek/api.php/days/gaps' |
| 110 | ``` |
| 111 | |
| 112 | | Methode | Pad | Betekenis | |
| 113 | | --- | --- | --- | |
| 114 | | 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. | |
| 115 | | GET | `/days/latest` | Nieuwste geschreven datum. | |
| 116 | | GET | `/days/gaps` | Gaten en onvolledige dagen. | |
| 117 | | GET | `/days/JJJJ-MM-DD` | Dag, verhalen, `previous` en `next`. | |
| 118 | | POST | `/days` | Nieuwe dag met precies drie verhalen. 201, of 409 als de datum bezet is. | |
| 119 | | PUT | `/days/JJJJ-MM-DD` | Titel en/of vervanging door precies drie verhalen. | |
| 120 | | DELETE | `/days/JJJJ-MM-DD` | Dag weg. | |
| 121 | | POST | `/days/JJJJ-MM-DD/stories` | Verhaal erbij zolang er minder dan drie zijn. | |
| 122 | | PUT | `/days/JJJJ-MM-DD/stories/1` | Plek 1, 2 of 3 bijwerken. | |
| 123 | | DELETE | `/days/JJJJ-MM-DD/stories/2` | Eén verhaal weg; de andere plekken blijven. | |
| 124 | | POST / DELETE | `/days/JJJJ-MM-DD/read` | Alleen een ingelogde lezer. | |
| 125 | | 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. | |
| 126 | | PUT | `/me/settings` | `theme`: `system`, `light` of `dark`. `font`: `serif`, `sans` of `rounded`. | |
| 127 | | GET | `/me/export` | Eigen gegevens als JSON. | |
| 128 | |
| 129 | Fouten zijn `{"error":"…"}`. Validatie die de drie-verhalenregel raakt geeft 422. De menselijke uitleg met dezelfde voorbeelden staat op `docs.php`. |
| 130 | |
| 131 | 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":"…"}`. |
| 132 | |
| 133 | ```sh |
| 134 | curl -sS -D - -o - \ |
| 135 | 'https://projects.timfalken.com/verhaaltjesboek/api.php/days/latest' |
| 136 | ``` |
| 137 | |
| 138 | `GET /api.php/keys/{id}` geeft de volledige sleutel terug aan een ingelogde beheerder. Opzoeken bij een verzoek blijft een hash op `token_hash`. |
| 139 | |
| 140 | ## Deploy |
| 141 | |
| 142 | De code staat op BlueGit: https://git.timfalken.com/projects-timfalken-com/verhalenboek (publiek). GitLab (`Timfa/Verhalenboek`) is alleen nog een backup en deployt niet meer. |
| 143 | |
| 144 | [`blue-ci-cd.yml`](blue-ci-cd.yml) draait PHP-syntax, domeintests, API-tests, een JavaScript-syntaxcheck en een echte FTP-fixture. `ftp_upload` wacht via `needs` op alle drie testjobs: faalt er één, dan is er geen deploy. Alleen een push naar `master` uploadt (geen MR-pipelines), 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, API-sleutels) over, zowel bij upload als bij verwijderen. `data/.htaccess` wordt apart gezet. `tests/`, `router.php` en `README.md` gaan niet mee. |
| 145 | |
| 146 | ### Geheimen |
| 147 | |
| 148 | | Naam | Waar | Beschermd | |
| 149 | |---|---|---| |
| 150 | | `timftphost`, `timftpuser`, `timftppassword`, `timftproot` | groep `projects.timfalken.com` (gedeeld door alle projecten op die site) | ja | |
| 151 | | `projectftp` | deze repository (`$timftproot/verhaaltjesboek`) | ja | |
| 152 | |
| 153 | Beschermde geheimen komen alleen mee op de beschermde branch `master`. MR-pipelines krijgen ze niet. Waarden van acht tekens of meer worden in joblogs vervangen door `[MASKED]`. |
| 154 | |
| 155 | ### Deploy-guard |
| 156 | |
| 157 | [`ci/deploy_guard.py`](ci/deploy_guard.py) laat de deploy hard falen (`DEPLOY GEBLOKKEERD: …`) als `projectftp` niet gezet of leeg is, naar `/` of `.` wijst, gelijk is aan `timftproot`, `..` bevat of buiten `timftproot` ligt. Zo kan een `mirror --delete` nooit de hele website overschrijven. `$timftproot` in `projectftp` wordt door de guard zelf ingevuld, want BlueGit-geheimen verwijzen niet naar elkaar. Zie [docs/deploy-guard.md](docs/deploy-guard.md) om de guard in een ander project te gebruiken. |
| 158 | |
| 159 | ## Tests |
| 160 | |
| 161 | ```sh |
| 162 | find web -name '*.php' -not -path '*/artifacts/*' -print0 | xargs -0 -n1 php -l |
| 163 | php web/tests/storybook.php |
| 164 | python3 web/tests/startup.py |
| 165 | python3 web/tests/integration.py |
| 166 | python3 web/tests/pwa.py |
| 167 | python3 web/tests/feed.py |
| 168 | node --check web/assets/app.js |
| 169 | python3 ci/test_deploy.py |
| 170 | ``` |
| 171 | |
| 172 | De API-tests draaien een kopie onder `web/tests/artifacts/` en laten de echte database met rust. |