# Wird Ma'houz API

API statique, ouverte et gratuite pour le **Wird Ma'houz** (الورد المأخوذ), la
litanie quotidienne de la voie mouride attribuee a Cheikh Ahmadou Bamba : les
deux formes, le texte arabe vocalise, la transcription latine, les nombres de
repetitions et les sources, servis en JSON sur HTTPS.

Aucun serveur a appeler, aucune cle a enregistrer. Chaque reponse est un
fichier JSON genere depuis ce depot et publie sur GitLab Pages : c'est rapide,
cacheable, ouvert en CORS, et utilisable depuis une application mobile, une
page web ou un script — sans jeton GitLab embarque dans l'application.

**URL de base**

```
https://wird.nexusprogramming.dev/v1
```

## Demarrage rapide

```bash
# le catalogue : les deux formes, leurs langues, leur etat de completude
curl -s https://wird.nexusprogramming.dev/v1/index.json

# une forme complete, telechargeable d'un bloc et lisible hors ligne
curl -s https://wird.nexusprogramming.dev/v1/forms/khafif.json
curl -s https://wird.nexusprogramming.dev/v1/forms/kamil.json
```

```dart
final base = Uri.parse('https://wird.nexusprogramming.dev/v1/');
final index = jsonDecode(
  utf8.decode((await http.get(base.resolve('index.json'))).bodyBytes),
)['data'] as Map<String, dynamic>;

// les chemins du catalogue sont relatifs : on les resout contre l'URL de base
final khafif = base.resolve(index['forms'][0]['path'] as String);
```

Le telephone recupere le catalogue, telecharge **une** forme, et a tout ce
qu'il faut pour la reciter jusqu'au bout hors connexion : pas de requete par
etape, pas de PDF a decouper, pas de base de donnees a l'execution.

## Points d'entree

| Point d'entree | Contenu |
|---|---|
| `/v1/index.json` | Catalogue : version d'API, revision de contenu, formes, langues, ecritures, completude, chemins relatifs |
| `/v1/forms/khafif.json` | La forme allegee, complete et autonome |
| `/v1/forms/kamil.json` | La forme complete, complete et autonome |
| `/v1/sources.json` | Editions, credits, URLs, empreintes, conditions de rediffusion, collation |
| `/v1/guide.json` | Materiel introductif source, commun aux deux formes |

Toutes les reponses partagent la meme enveloppe, comme les autres API statiques
Nexus — le client ne deballe jamais que `data` :

```json
{ "code": 200, "status": "OK", "data": { "...": "..." } }
```

Une forme ou une ressource absente est un 404 HTTP de Pages, pas une enveloppe
porteuse d'un code d'erreur.

## Les deux formes

| Id | Titre imprime | Alias | Sections | Etapes | Recitations | Arabe | Translitteration | Traduction |
|---|---|---|---:|---:|---:|---|---|---|
| `khafif` | الورد المأخوذ الخفيف | al khafif, Hafiif, Xafiif | 3 | 23 | 326 | 23/23 | 16/23 | 0/23 |
| `kamil` | الورد المأخوذ الكامل | **al akmal**, Kamiil, Kaamil | 3 | 29 | 592 | 29/29 | 26/29 | 0/29 |

Les 23 et 29 etapes comptent l'invocation d'ouverture et celle de cloture ;
les corps de recitation font respectivement 21 et 27 etapes.

> **`al akmal` et `al kamil` sont la meme forme.** L'edition de reference de
> 2013 intitule la seconde forme **al akmal** (الأكمل, « le plus complet ») :
> au sommaire page 3, et page 31 « هذا هو الورد المأخوذ الأكمل من الله تبارك
> وتعالى بواسطة رسوله ». Les editions xassaid ecrivent **al kamil** (الكامل,
> « le complet »). Meme incipit, meme position — la seconde, apres al-khafif —,
> meme sequence et memes nombres de repetitions ; le fichier de l'editeur
> lui-meme s'intitule « Wird Mahuz Hafiif **& Kamiil**.pdf ». L'identifiant
> d'API est `kamil`, et `al akmal` figure dans `aliases`.

## Le modele de donnees

Une forme porte son titre, ses alias, sa revision, puis des **sections
ordonnees** contenant des **etapes ordonnees**. L'ordre de lecture est l'ordre
des tableaux.

```jsonc
{
  "id": "kamil",
  "contentRevision": "a185857f…",
  "sections": [
    {
      "id": "ouverture",
      "instruction": { "ar": "يُقرأ هذا الدعاءُ قبل الورد:", "fr": "…",
                       "source": { "edition": "xassaid-kamil-2023", "page": 1 } },
      "steps": [ { "id": "dua-avant-wird", "…": "…" } ]
    },
    { "id": "recitation", "steps": [ /* 27 etapes */ ] },
    { "id": "cloture",    "steps": [ /* 1 etape */ ] }
  ]
}
```

Une etape :

```jsonc
{
  "id": "salat-al-fatih",          // identifiant stable, voir plus bas
  "type": "passage",
  "kind": "salat",                 // quran | dhikr | dua | salat
  "title": "Salat al-Fatih",
  "titleAr": "صلاة الفاتح",
  "content": {
    "ar": "اللَّهُمَّ صَلِّ عَلَى سَيِّدِنَا مُحَمَّدٍ الْفَاتِحِ …",
    "transliterations": [],        // vide = indisponible, jamais invente
    "translations": []
  },
  "repetition": { "times": 100, "printed": true, "printedAs": "100 مرة" },
  "availability": { "ar": true, "transliteration": false, "translation": false },
  "sources": { "ar": [ { "edition": "xassaid-kamil-2023", "page": 4 } ] },
  "emphasis": "core"
}
```

### Identifiants stables

Les identifiants de forme, de section et d'etape sont des slugs semantiques.
**Ils ne dependent ni de la position dans le tableau, ni du numero de page, ni
d'un titre traduit.** Une correction de contenu peut inserer, deplacer ou
reecrire une etape : `salat-al-fatih` reste `salat-al-fatih`. L'application
peut donc enregistrer `(formId, stepId)` et reprendre la lecture au bon
endroit apres une mise a jour du jeu de donnees.

### Repetitions

`repetition.times` est le nombre de recitations. `repetition.printed`
distingue un **nombre explicitement imprime** par la source (`true`, avec
`printedAs` qui donne la graphie, par exemple `3 مرات`) d'un **passage non
marque** (`false`), qui se recite une fois — c'est le cas des deux invocations
encadrantes. Le schema interdit a un passage non marque de porter un nombre
autre que 1.

Une etape peut aussi etre un **groupe**, et le groupe entier est alors repete :

```jsonc
{ "id": "exemple", "type": "group", "repetition": { "times": 3, … },
  "steps": [ { "id": "a", … }, { "id": "b", … } ] }
```

se recite **(A, B) × 3** — et non A×3 puis B×3, ce qui changerait l'ordre de
lecture. La structure est portee par le schema et verifiee par la CI. Les deux
formes publiees aujourd'hui n'utilisent aucun groupe a `times > 1` : aucune des
editions consultees n'en prescrit, et la structure n'a pas ete employee pour
decorer le jeu de donnees.

### Provenance

Chaque etape porte ses references de source, et **le texte arabe, la
transcription et la traduction peuvent venir d'editions differentes** —
`sources.ar`, `sources.transliteration`, `sources.translations`. Une reference
identifie toujours une edition et une page. C'est utilise pour de vrai :
la transcription de `salat-saada`, etape du khafif, provient de l'edition
kamil, ou elle est imprimee au mauvais endroit.

### Ce qui est indisponible est vide

`content.translations` et `content.transliterations` sont des tableaux vides
quand la source ne porte rien, et `availability` le dit explicitement. Rien
n'est comble par defaut : ni formulation, ni diacritique, ni traduction, ni
nombre de repetitions, ni consigne rituelle.

> **Aucune traduction n'est disponible, dans aucune langue.** L'edition de 2013
> contient un abondant appareil francais — sommaire, avant-propos, charte,
> lexique — mais ce sont des textes de presentation : elle ne traduit a aucun
> moment les invocations, dont les pages 20 a 44 sont un fac-simile arabe sans
> vis-a-vis francais. Un commentaire francais n'etablit pas qu'une traduction
> francaise existe. Les champs restent donc vides. Voir
> [CONTRIBUTING.md](CONTRIBUTING.md) si vous pouvez aider.

## Les editions sources

| Id | Role | Edition | Rediffusion |
|---|---|---|---|
| `serignesam-2013` | ordre de recitation | *Ma'houz, Le wird mouride*, 46 p., serignesam.com | **Tous droits reserves — rien n'en est republie** |
| `xassaid-khafif-2021` | texte arabe du khafif | riwaya de Maska al-Ya'qubi, 3 p. | aucune mention |
| `xassaid-kamil-2023` | texte arabe + transcription du kamil | d'apres *Ighna' al-'Adim*, 5 p. | aucune mention |

L'edition de 2013 est la **reference de collation** : son texte arabe est un
fac-simile manuscrit, sans couche de texte exploitable, et elle abrege les
passages que le recitant connait par coeur — Ayat al-Kursi y est notee
« الحي القيوم **إلى** العلي العظيم » (p. 24), et dans le kamil la Fatiha,
al-Falaq et an-Nas sont designees par leur nom au lieu d'etre imprimees
(p. 34, 37, 38). Le texte publie ici vient donc des editions typographiees,
qui donnent les passages en entier — ce dont l'application a precisement
besoin pour une lecture hors ligne.

L'ordre des deux formes a ete collationne page par page sur l'edition de 2013
(khafif p. 21-28, kamil p. 31-38) : **il concorde d'un bout a l'autre**. Les
divergences relevees sont textuelles, jamais sequentielles, et sont toutes
consignees dans `sources.json`, section `collation` — presence de
`inna-waliyyi-allah`, « سيدنا » dans le tahlil, forme courte ou longue de
`tahlil-wahdahu`, variantes de la litanie des noms divins.

Details complets, empreintes SHA-256 et credits : [NOTICE.md](NOTICE.md) et
`/v1/sources.json`.

## Travailler sur le jeu de donnees

Python 3.9+ suffit ; la generation n'a aucune dependance.

```bash
python3 scripts/build_api.py           # valide data/ et regenere v1/ + docs/COVERAGE.md
python3 scripts/build_api.py --check   # ce que fait la CI : echoue si v1/ est perime
python3 scripts/consumer_contract.py   # sert v1/ en local et rejoue le parcours de l'app
pip install jsonschema && python3 scripts/validate_schema.py   # data/ contre schema/
```

Une verification supplementaire, manuelle, recoupe le texte publie avec la
couche de texte des PDF sources — deux canaux independants, puisque le texte
de `data/` a ete transcrit en lisant les pages **rendues** :

```bash
pip install pymupdf
python3 scripts/verify_against_sources.py \
    --khafif "Wird Mahuz- Al hafif.pdf" \
    --kamil  "Wirdul maaxuz kaamil avec transcription.pdf"
```

Elle ne tourne pas en CI : les PDF sont des fichiers tiers que ce depot ne
rediffuse pas. Leurs URL et leurs empreintes SHA-256 sont dans
`data/sources.json`. 35 des 37 textes sont confirmes par les deux canaux ; les
deux restants sont des defauts averés de la couche de texte des PDF — un `ه`
perdu dans `لِلَّهِ` et un `ذي` inverse en `يذ` —, documentes dans le script.

### Mettre a jour le contenu

`data/` s'edite, `v1/` se genere — **ne jamais editer `v1/` a la main.**

```text
data/
  passages.json     source unique de verite pour le texte : chaque passage une seule fois
  forms/*.json      l'ordre de recitation et les nombres, par references d'identifiants
  sources.json      les editions, leurs conditions, la collation
  guide.json        le materiel introductif commun
```

1. Corriger un texte ou en ajouter un : `data/passages.json`. Un passage porte
   son `ar`, sa provenance obligatoire, et eventuellement `arByEdition` quand
   deux editions le vocalisent differemment.
2. Changer un ordre ou un nombre : `data/forms/<forme>.json`.
3. `python3 scripts/build_api.py`, puis committer `data/`, `v1/` **et**
   `docs/COVERAGE.md` ensemble.

La validation refuse un identifiant duplique, une reference de passage qui ne
resout pas, un passage sans source, une page manquante, une edition inconnue,
un `times` inferieur a 1, un nombre imprime sans sa graphie, un passage non
marque portant un nombre autre que 1, un passage defini mais utilise par
aucune forme, et une structure de groupe mal formee.

### Table de couverture

[`docs/COVERAGE.md`](docs/COVERAGE.md) est genere a chaque build : chaque etape
y est reliee a sa forme, sa section, son identifiant stable et la page de
l'edition dont elle provient. La couverture arabe y est comptee separement de
la transcription et de la traduction. C'est ce qui permet d'attraper une
ouverture oubliee, une priere de cloture manquante, une etape dupliquee ou un
contenu classe dans la mauvaise forme.

## CI et deploiement

Chaque push et chaque merge request passent par :

| Job | Ce qu'il prouve |
|---|---|
| `dataset` | `data/` est valide et `v1/` + `docs/COVERAGE.md` sont a jour |
| `schema` | `data/` est conforme aux JSON Schema de `schema/` |
| `deterministic` | deux generations successives donnent les memes octets |
| `contract` | le parcours exact de l'application passe, servi en local sur HTTP |
| `openapi` | `openapi.yaml` reste analysable |

La branche par defaut est ensuite publiee sur GitLab Pages par le job `pages`,
puis `smoke` attend que l'URL publiee serve bien la `contentRevision` qui
vient d'etre construite et **rejoue le contrat consommateur contre l'URL
publiee**.

## Cache et epinglage

Pages envoie `Cache-Control: max-age=600`. Le contenu est stable en pratique —
la litanie d'un auteur mort en 1927 ne bouge pas — : cachez franchement du
cote client et rafraichissez quand `contentRevision` change dans
`/v1/index.json`. Une copie hors ligne complete, c'est trois requetes : le
catalogue et les deux formes.

Pour une version qui ne bougera jamais sous vos pieds, les releases sont
taguees et servies par le CDN Statically :

```
https://cdn.statically.io/gl/nexus-programming/nexus-wird-mahouz-api@v1.0.0/v1/index.json
```

La forme sans `@` (`.../nexus-wird-mahouz-api/v1.0.0/v1/...`) repond un 301
vers celle-ci : utilisable, mais seulement par un client qui suit les
redirections — ce que le `urllib` de la bibliotheque standard de Python ne
fait pas pour tous les codes. Preferez la forme `@tag`.

Statically limite les requetes sur un chemin qu'il n'a pas encore en cache :
le tout premier appel a une URL donnee peut repondre `429 Rate limit
exceeded`, puis servir normalement une fois le fichier recupere. Si vous
epinglez une release, prevoyez un reessai sur le premier appel — ou restez
sur `wird.nexusprogramming.dev`, qui n'a pas cette limite.

### Autres noms d'hote

Les memes fichiers sont aussi servis par GitLab directement, ce qui est utile
pour une URL qui ne depend pas du DNS de ce projet :

| URL | Comportement |
|---|---|
| `https://wird.nexusprogramming.dev/v1/...` | canonique, repond 200 |
| `https://nexus-wird-mahouz-api-51ac4a.gitlab.io/v1/...` | GitLab Pages, repond 200 |
| `https://nexus-programming.gitlab.io/nexus-wird-mahouz-api/v1/...` | redirection 308 vers la ligne ci-dessus |

Aucun domaine primaire n'est impose : les deux premieres URL repondent 200
toutes les deux. La forme avec redirection echoue sur un client qui refuse de
les suivre, le `urllib` de la bibliotheque standard de Python compris.

## Integration Flutter

Voir [`docs/integration_flutter.md`](docs/integration_flutter.md) : l'exemple
Dart complet, aligne sur `tariqa_features` — clean architecture, Riverpod,
Freezed —, la resolution des chemins relatifs du catalogue, le telechargement
hors ligne et la reprise de lecture par `(formId, stepId)`.

## Contribuer

Les corrections de texte et les traductions sourcees sont les bienvenues :
[CONTRIBUTING.md](CONTRIBUTING.md).

## Licence et provenance

MIT pour l'outillage et la compilation. Le wird lui-meme est attribue a Cheikh
Ahmadou Bamba Mbacke (1853-1927) et releve du domaine public ; les editions
citees ont chacune leur situation propre, consignee dans
[NOTICE.md](NOTICE.md) et dans `/v1/sources.json`.
