BlueGit

projects-timfalken-com verhalenboek

Files

verhalenboek
README.md

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 onder Sleutels 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.

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.

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'
MethodePadBetekenis
GET/daysDagen, 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/latestNieuwste geschreven datum.
GET/days/gapsGaten en onvolledige dagen.
GET/days/JJJJ-MM-DDDag, verhalen, previous en next.
POST/daysNieuwe dag met precies drie verhalen. 201, of 409 als de datum bezet is.
PUT/days/JJJJ-MM-DDTitel en/of vervanging door precies drie verhalen.
DELETE/days/JJJJ-MM-DDDag weg.
POST/days/JJJJ-MM-DD/storiesVerhaal erbij zolang er minder dan drie zijn.
PUT/days/JJJJ-MM-DD/stories/1Plek 1, 2 of 3 bijwerken.
DELETE/days/JJJJ-MM-DD/stories/2Eén verhaal weg; de andere plekken blijven.
POST / DELETE/days/JJJJ-MM-DD/readAlleen een ingelogde lezer.
GET/friend-readsAlleen 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/settingstheme: system, light of dark. font: serif, sans of rounded.
GET/me/exportEigen 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_…, Sleutels op {base_url}/#/sleutels, 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. 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

.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 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

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.