# API des awrad de la Tidjaniya

Les trois oraisons de la voie tijane, servies en JSON statique versionne :
le **Wird Lazim**, la **Wazifa** et le **Hadaratoul Jouma**.

Pas de serveur, pas d'authentification, pas de parametre de requete : un
arbre de fichiers pre-rendus, deploye par GitLab Pages. Le consommateur
vise est l'application Tidjaniya, via le paquet partage `tariqa_features`.

- **Base** : `https://nexus-tijaniyya-awrad-api-4401f3.gitlab.io/v1`
- **Catalogue** : `https://nexus-tijaniyya-awrad-api-4401f3.gitlab.io/v1/index.json`
- **Description** : [`openapi.yaml`](openapi.yaml) · **Couverture** :
  [`docs/COVERAGE.md`](docs/COVERAGE.md) · **Sources** :
  [`data/sources.json`](data/sources.json)

> Un domaine dedie `awrad.nexusprogramming.dev` est prevu, sur le modele de
> `wird.nexusprogramming.dev`. Il n'est **pas encore en service** : il
> demande un enregistrement DNS (un CNAME en « DNS only », non proxifie,
> sans quoi ni la verification GitLab ni Let's Encrypt n'aboutissent).
> Jusque-la, utilisez l'URL Pages ci-dessus. Resolvez toujours les chemins
> relativement au catalogue : le jour ou le domaine entre en service,
> aucun client n'aura a changer.

| URL | Comportement |
|---|---|
| `https://nexus-tijaniyya-awrad-api-4401f3.gitlab.io/v1/...` | GitLab Pages, repond 200 |
| `https://nexus-programming.gitlab.io/nexus-tidjaniya-awrad-api/v1/...` | redirection 308 vers la ligne ci-dessus |
| `https://awrad.nexusprogramming.dev/v1/...` | prevu, pas encore en service |

Le domaine Pages a ete attribue avant que le depot soit renomme : il garde
l'ancienne graphie `tijaniyya`. C'est l'URL qui sert reellement, elle n'est
pas corrigible depuis le depot, et il ne faut pas la « reparer ». La forme
avec redirection echoue sur un client qui refuse de suivre les 308, le
`urllib` de la bibliotheque standard de Python compris.

---

## Les points d'entree

| Methode | Chemin | Ce qu'il donne |
|---|---|---|
| GET | `/v1/index.json` | Le catalogue : revision, capacites requises, les trois formes |
| GET | `/v1/forms/lazim.json` | Le Wird Lazim, autonome |
| GET | `/v1/forms/wazifa.json` | La Wazifa, autonome, substitut compris |
| GET | `/v1/forms/hadaratoul-jouma.json` | Le Hadaratoul Jouma, ses sept modalites comprises |
| GET | `/v1/passages/index.json` | Le catalogue des passages partages |
| GET | `/v1/passages/{passageId}.json` | Un passage isole, avec ses variantes d'edition |
| GET | `/v1/guide.json` | Le materiel introductif |
| GET | `/v1/sources.json` | Les editions, leurs divergences, ce qui reste non resolu |

Toutes les reponses portent l'enveloppe Nexus :

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

**Resoudre les chemins relativement.** Le catalogue donne `forms/lazim.json`,
pas une URL absolue. Resolvez-le contre l'URL du document qui le contient,
jamais en assemblant une chaine a partir d'un identifiant : l'API reste
libre de ranger ses fichiers autrement, et le meme catalogue doit
fonctionner sous le domaine dedie comme sous le sous-chemin de projet
`https://nexus-programming.gitlab.io/nexus-tidjaniya-awrad-api/`, qui redirige (308) vers l'URL de base.

---

## Les trois pratiques

| Pratique | Arabe | Quand | Cadre | Parcours |
|---|---|---|---|---|
| Wird Lazim | الورد اللازم | Deux fois par jour, matin et soir | Seul, a voix basse | 1 |
| Wazifa | الوظيفة | Une a deux fois par jour | En groupe, a voix haute | 2 |
| Hadaratoul Jouma | حضرة الجمعة | Le vendredi, entre l'Asr et le Maghrib | En groupe, a voix haute | 7 |

Chaque forme porte ses alias regionaux, pour que la recherche aboutisse
quel que soit le nom employe : `ouird`, `laazim`, `wadhifa`, `haylala`,
`heilala`, `asrou`, `hadra du vendredi`, `takoussane`…

---

## Ce qu'un consommateur doit comprendre

Chaque forme, et le catalogue, declarent `requiredCapabilities`. **Lisez-les
avant de commencer une seance.** Un lecteur qui ne connait pas l'une d'elles
doit refuser la forme avant le premier grain, jamais au milieu.

### `choice` — des alternatives exclusives

Exactement une option est retenue, et son identifiant est enregistre dans la
session.

```jsonc
{
  "id": "jawhara-ou-substitut",
  "type": "choice",
  "selection": "exactlyOne",
  "options": [
    { "id": "jawhara", "when": "Toutes les conditions …",
      "conditions": ["Etre en etat d'ablution faite avec de l'eau", "…"],
      "steps": [ { "passage": "jawharat-al-kamal",
                   "repetition": {"times": 12, "printed": true} } ] },
    { "id": "substitut-salat-al-fatih", "when": "L'une au moins … n'est pas reunie.",
      "steps": [ { "passage": "salat-al-fatih",
                   "repetition": {"times": 20, "printed": true} } ] }
  ]
}
```

### `until-event` — une recitation sans cible

Le vendredi, l'assemblee recite sans nombre fixe jusqu'au coucher du soleil.
Cette etape **ne porte pas de champ `times`**, et il ne faut pas en
fabriquer un : afficher un compte a rebours inventerait une regle que les
sources ne donnent pas.

```jsonc
{
  "repetition": {
    "mode": "untilEvent",
    "event": "sunset",
    "printed": false,
    "printedAs": "بلا حد"
  }
}
```

Le catalogue l'annonce avec `hasOpenEndedPath`, avant tout telechargement.

### `session-contexts` — matin et soir

Le Lazim se recite dans deux contextes qui partagent exactement les memes
passages et les memes nombres, et ne different que par la fenetre horaire.
Une session sauvegardee doit retenir lequel.

### `group` — un bloc repete comme un tout

`(A, B) x 3` vaut `A, B, A, B, A, B`, jamais `A, A, A, B, B, B` : ce sont
deux prieres differentes. Aucune forme publiee aujourd'hui n'en utilise, mais
le modele et le validateur le prevoient.

### Ce qu'une session doit retenir

La forme, la revision de contenu, le contexte (matin/soir) le cas echeant,
l'option retenue pour chaque choix, l'occurrence courante et l'avancement
des repetitions. Les identifiants sont stables et independants de la
position : une etape inseree ailleurs ne deplace pas la votre.

---

## Le texte, les langues et leurs limites

Les champs sont distincts et ne se remplacent jamais l'un l'autre :

- `content.ar` — le texte de recitation, en arabe ;
- `content.transliterations[]` — transcriptions latines, `language: "ar-Latn"` :
  elles rendent les **sons**, pas le sens, et ne comptent jamais comme une
  traduction ;
- `content.translations[]` — traductions du **sens**, une par langue, chacune
  avec sa source, son `status` et son traducteur.

`status` vaut `published` (deja publiee par son editeur), `editorial` (rendu
propre a ce depot, non revu) ou `human-reviewed` (relu par un humain
competent). **Toutes les traductions publiees ici sont `published`** : ce
depot n'a produit aucun rendu editorial de son cru.

**La couverture est partielle, et c'est dit.** Deux passages sur treize
portent une traduction. Salat al-Fatih est traduite en anglais, wolof,
haoussa et indonesien ; Jawharat al-Kamal en francais et en anglais. Les
onze autres n'en portent aucune : les editions consultees impriment leur
arabe et leur transcription sans vis-a-vis traduit. **Aucune case vide n'est
comblee par une autre langue** — une traduction wolof manquante reste
manquante, elle n'est jamais remplacee par du francais.

Le detail par passage figure dans [`docs/COVERAGE.md`](docs/COVERAGE.md).

### Vocalisation

Douze passages sur treize sont publies **non vocalises**, parce que
l'edition de base ne porte pas les harakat. Seule Jawharat al-Kamal l'est,
parce que son edition de texte l'est. Chaque passage porte un booleen
`vocalised`. Aucune voyelle n'est ajoutee a une source qui n'en porte pas :
vocaliser, c'est trancher une lecture.

---

## Les editions suivies

L'edition de base est la presentation senegalaise de la **Cellule Zawiya
Tijaniyya** ([zawiya.sn](https://zawiya.sn/le-wird-tijane/)) : elle donne,
pour les trois pratiques, l'ordre complet, l'arabe, la transcription latine
et les nombres. Elle fournit le texte de douze des treize passages.

L'autorite de collation est le **Diwan d'El Hadji Malick Sy** (p. 115-116),
ou les trois oraisons sont exposees en vers par l'autorite senegalaise
elle-meme. Il confirme independamment chaque nombre, chaque fenetre
horaire, la regle de rattrapage, la recitation de l'assemblee sans nombre,
et l'ordre exact de la formule d'intention.

Les **regles** (conditions de Jawharat al-Kamal, fenetres horaires
detaillees, substitutions admises) viennent de
[tidjaniya.com](https://tidjaniya.com). Les **traductions** viennent de
kutubia.org (anglais), tidjaniya.com (francais), bayeniasserek.com (wolof),
islambestblog (haoussa) et NU Online (indonesien), chacune attribuee a son
traducteur.

Les douze editions, ce que chacune etablit, ses limites et son empreinte
SHA-256 sont dans [`data/sources.json`](data/sources.json).

### Ce qui diverge, et ce qui n'est pas tranche

Treize divergences sont enregistrees, avec pour chacune l'edition suivie et
l'alternative. **Aucun nombre n'est jamais moyenne.** Les plus notables :

- **1400 le vendredi** — la liste francaise de l'edition de base propose
  « 1000, ou 1200 ou 1400 ou 1600 ». Son propre texte arabe, a la ligne
  suivante, porte mille, mille deux cents, mille six cents, sans 1400, et
  tidjaniya.com dit de meme. **1400 est ecarte.**
- **Jawharat al-Kamal** — l'edition de base en porte cinq lectures que
  l'edition kutubia contredit, dont une substitution ز/ر que sa propre
  transcription latine dement. C'est le seul passage dont le texte publie
  ne vient pas de l'edition de base ; celui de l'edition de base reste
  expose sous `arByEdition`.
- **La formule d'intention** — l'edition de base l'imprime dans un tableau
  a deux colonnes dont l'aplatissement inverse les hemistiches. L'ordre du
  Diwan est retenu, confirme par la transcription de l'edition de base.
- **11 ou 12 Jawhara** — douze est publie ; onze est documente comme
  pratique d'une autre transmission, non comme une option.

Et ce qui reste **non resolu** est dit comme tel. Quand le Nom divin est
recite en plus du tahlil le vendredi, aucune source consultee ne precise si
le nombre imprime compte la paire `الله الله` ou chaque occurrence. Le
passage porte donc `countingUnit: "printedFormula"` — une pression du
compteur vaut une recitation de la formule telle qu'imprimee — et un
`countingNote` qui expose la question. **Affichez la note ; ne tranchez pas
a la place du fidele.**

---

## Travailler sur le depot

`data/` est la source de verite editable. `v1/` est **genere** : ne l'editez
jamais a la main.

```bash
python3 scripts/build_api.py              # valider data/, regenerer v1/ et la couverture
python3 scripts/build_api.py --check      # echouer si v1/ est perime (c'est ce que fait la CI)

pip install jsonschema
python3 scripts/validate_schema.py        # data/ contre schema/

python3 scripts/consumer_contract.py           # le contrat, servi en local sur HTTP
python3 scripts/consumer_contract.py --subpath # et rejoue sous un sous-chemin de projet Pages
python3 scripts/consumer_contract.py https://nexus-tijaniyya-awrad-api-4401f3.gitlab.io/v1

python3 -m http.server 8000 &             # l'exemple Dart contre l'API servie
dart run examples/dart/bin/consume.dart http://127.0.0.1:8000/v1/
```

Le contrat consommateur porte son inventaire **en dur**, collationne sur les
editions : un test qui tire ses attentes de ce qu'il teste ne prouve rien.
Changer un nombre dans `data/` sans le changer dans
`scripts/consumer_contract.py` fait echouer la CI, et c'est voulu.

### Ajouter une traduction

1. Ajoutez une entree dans `translations[]` du passage, avec `language`,
   `text`, `source`, `status` et `translator`.
2. Relancez `python3 scripts/build_api.py`.
3. Mettez a jour `EXPECTED_TRANSLATIONS` dans `scripts/consumer_contract.py`.
4. Ajoutez l'edition a `data/sources.json` si elle est nouvelle.

Une traduction sans source verifiable n'est pas acceptee. Voir
[`CONTRIBUTING.md`](CONTRIBUTING.md).

---

## Consommer depuis Flutter

```dart
import 'dart:convert';
import 'package:http/http.dart' as http;

const base = 'https://nexus-tijaniyya-awrad-api-4401f3.gitlab.io/v1/';

/// Les capacites que cette version du lecteur sait mener.
const supported = {'choice', 'until-event', 'group', 'session-contexts'};

Future<Map<String, dynamic>> _get(Uri url) async {
  final response = await http.get(url);
  if (response.statusCode != 200) {
    throw HttpException('${response.statusCode} sur $url');
  }
  // utf8.decode plutot que response.body : l'arabe ne pardonne pas un
  // decodage par defaut.
  final payload =
      jsonDecode(utf8.decode(response.bodyBytes)) as Map<String, dynamic>;
  if (payload['code'] != 200) throw const FormatException('enveloppe invalide');
  return payload['data'] as Map<String, dynamic>;
}

Future<Map<String, dynamic>?> loadForm(String id) async {
  final catalogueUrl = Uri.parse(base).resolve('index.json');
  final catalogue = await _get(catalogueUrl);

  final entry = (catalogue['forms'] as List)
      .cast<Map<String, dynamic>>()
      .firstWhere((f) => f['id'] == id);

  // Refuser AVANT de commencer, jamais au milieu d'une seance.
  final required = (entry['requiredCapabilities'] as List).cast<String>();
  if (required.any((c) => !supported.contains(c))) return null;

  // Chemin relatif, resolu contre l'URL du catalogue.
  final form = await _get(catalogueUrl.resolve(entry['path'] as String));

  // Lier la session a la revision : reprendre une seance sur un autre
  // contenu, c'est reprendre une seance qui n'a jamais existe.
  assert(form['contentRevision'] == catalogue['contentRevision']);
  return form;
}
```

Et pour une etape ouverte :

```dart
final rep = step['repetition'] as Map<String, dynamic>;
if (rep['mode'] == 'untilEvent') {
  // Pas de cible. Pas de barre de progression. L'assemblee s'arrete au
  // Maghrib, et c'est elle qui le decide.
  showUntilSunset(label: rep['printedAs'] as String?);
} else {
  showCounter(target: rep['times'] as int);
}
```

L'exemple complet et execute se trouve dans
[`examples/dart/bin/consume.dart`](examples/dart/bin/consume.dart), et la
CI le lance a chaque pipeline. Les notes d'integration pour
`tariqa_features`, y compris les ecarts actuels du lecteur Wird Ma'houz,
sont dans [`docs/integration_flutter.md`](docs/integration_flutter.md).

---

## Versions et compatibilite

`apiVersion` est `v1`. Tant qu'il ne change pas, aucun champ existant ne
disparait et aucun ne change de sens.

`contentRevision` est un SHA-256 deterministe de toutes les donnees : il
bouge a la moindre correction de texte. Liez-y une session en cours, et
proposez de recommencer plutot que de reprendre sur un contenu different.

Une **rupture de compatibilite** (un champ retire, un sens change, une
nouvelle capacite obligatoire) ouvre un `v2` : elle n'arrive jamais dans
`v1`. Une **correction de contenu** (une faute de frappe corrigee, une
traduction ajoutee) change seulement `contentRevision`. Les deux sont
distinguees dans [`CHANGELOG.md`](CHANGELOG.md).

---

## Licence

Outillage et compilation : MIT, voir [`LICENSE`](LICENSE).

Le texte des awrad remonte a Cheikh Ahmad at-Tijani (mort en 1815) et releve
du domaine public. Ce qui est susceptible de droits, ce sont les editions
modernes : mise en page, transcription latine, traduction, apparat critique.
Chaque transcription et chaque traduction porte son attribution et son
edition. Voir [`NOTICE.md`](NOTICE.md).
