ffbb-data-client 2.1.0__tar.gz → 2.3.0__tar.gz

ffbb_data_client-2.3.0/.agents/rules/antigravity-rtk-rules.md

@@ -0,0 +1,32 @@
+# RTK - Rust Token Killer (Google Antigravity)
+
+**Usage**: Token-optimized CLI proxy for shell commands.
+
+## Rule
+
+Always prefix shell commands with `rtk` to minimize token consumption.
+
+Examples:
+
+```bash
+rtk git status
+rtk cargo test
+rtk ls src/
+rtk grep "pattern" src/
+rtk find "*.rs" .
+rtk docker ps
+rtk gh pr list
+```
+
+## Meta Commands
+
+```bash
+rtk gain              # Show token savings
+rtk gain --history    # Command history with savings
+rtk discover          # Find missed RTK opportunities
+rtk proxy <cmd>       # Run raw (no filtering, for debugging)
+```
+
+## Why
+
+RTK filters and compresses command output before it reaches the LLM context, saving 60-90% tokens on common operations. Always use `rtk <cmd>` instead of raw commands.

{ffbb_data_client-2.1.0 → ffbb_data_client-2.3.0}/.github/scripts/check_wrapper_parity.py

@@ -62,13 +62,25 @@ def write_summary(text: str) -> None:
 def main() -> int:
     api_methods = get_public_methods(CLIENTS / "api_ffbb_app_client.py")
     ms_methods = get_public_methods(CLIENTS / "meilisearch_ffbb_client.py")
-    wrapper_methods = get_public_methods(CLIENTS / "ffbb_data_client.py")
+
+    # Collect wrapper methods from the main file AND any facade files.
+    # After the v2.1.0 refactor, methods live in _rest_facade.py and
+    # _search_facade.py; the thin ffbb_data_client.py delegates via setattr.
+    wrapper_files = [
+        CLIENTS / "ffbb_data_client.py",
+        CLIENTS / "_rest_facade.py",
+        CLIENTS / "_search_facade.py",
+    ]
+    wrapper_methods: set[str] = set()
+    for wf in wrapper_files:
+        if wf.exists():
+            wrapper_methods |= get_public_methods(wf)
 
     all_inner = api_methods | ms_methods
     missing = sorted(all_inner - wrapper_methods)
 
     if not missing:
-        msg = "## ✅ Wrapper parity OK\n\nAll public methods from inner clients are exposed in `FFBBDataClient`."
+        msg = "## ✅ Wrapper parity OK\n\nAll public methods from inner clients are exposed in `FFBBDataClient` (including facade files)."
         print(msg)
         write_summary(msg)
         return 0
@@ -77,13 +89,14 @@ def main() -> int:
     missing_detail = " ".join(
         [
             "The following methods exist in inner clients but are **not exposed**",
-            "in `FFBBDataClient`:",
+            "in `FFBBDataClient` or its facade files:",
         ]
     )
     fix_detail = " ".join(
         [
             "Add the missing method(s) to",
-            "`src/ffbb_data_client/clients/ffbb_data_client.py`",
+            "`src/ffbb_data_client/clients/ffbb_data_client.py` or one of its",
+            "facade files (`_rest_facade.py`, `_search_facade.py`)",
             "so they delegate to the appropriate inner client.",
         ]
     )

{ffbb_data_client-2.1.0 → ffbb_data_client-2.3.0}/.github/workflows/update-ffbb-api-discovery.yml

@@ -35,7 +35,7 @@ jobs:
       - name: Detect structural discovery changes
         id: changes
         run: |
-          if grep -Eq '^- (Added|Removed): \[' data/api_update_summary.md; then
+          if grep -Eq '^- (Added|Removed): \[' data/api_update_summary.md || grep -q 'drift' data/api_update_summary.md; then
             echo "changed=true" >> "$GITHUB_OUTPUT"
           else
             echo "changed=false" >> "$GITHUB_OUTPUT"

ffbb_data_client-2.3.0/AGENTS.md

@@ -0,0 +1,260 @@
+# FFBB Data Client SDK
+
+> ⚠️ **Fichier auto-généré** par `tools/update_agents_md.py` — ne pas modifier manuellement.
+> Dernière mise à jour : ffbb-data-client | SDK total : ~18767 lignes de code
+> (clients: 6259, models: 9878, utils: 1840, helpers: 790)
+
+## Langue
+Tous les documents de travail (walkthrough.md, implementation_plan.md) DOIVENT être en français.
+
+## Persona
+Expert en basketball français et intégration technique.
+Accès au SDK Python de bas niveau `ffbb-data-client` connecté à l'API et au Meilisearch officiel de la FFBB.
+
+## Méthodes REST du Client (Exemples importants)
+Le SDK expose les méthodes directes de récupération de données suivantes via `FFBBDataClient` :
+- `get_organisme_for_search` : Version allégée de get_organisme() pour les contextes de recherche
+- `get_organisme_for_search_async` : Version async allégée de get_organisme() pour les contextes de recherche
+- `get_configuration` : Retrieves the API configuration including bearer tokens
+- `get_configuration_async` : Retrieves the API configuration including bearer tokens asynchronously
+- `get_competition` : Retrieves detailed information about a competition
+- `get_competition_async` : Retrieves detailed information about a competition asynchronously
+- `list_competitions` : Lists competitions with optional field selection
+- `list_competitions_async` : Lists competitions asynchronously
+- `get_lives` : Retrieves a list of live events
+- `get_lives_async` : Retrieves a list of live events asynchronously
+- `get_organisme` : Retrieves detailed information about an organisme
+- `get_organisme_async` : Retrieves detailed information about an organisme asynchronously
+- `get_club_contacts` : Return club contact information (club-level + membres) for an organisme
+- `get_poule` : Retrieves detailed information about a poule
+- `get_poule_async` : Retrieves detailed information about a poule asynchronously
+- `get_saisons` : Retrieves list of seasons with comprehensive input validation
+- `get_saisons_async` : Retrieves list of seasons asynchronously with input validation
+- `get_classement` : Retrieves ONLY the ranking (classement) for a specific poule
+- `get_classement_async` : Retrieves ONLY the ranking (classement) for a specific poule asynchronously
+- `get_equipes` : Retrieves ONLY the team commitments (engagements) for a specific club
+- `get_equipes_async` : Retrieves ONLY the team commitments (engagements) for a specific club asynchronously
+- `get_rencontre` : Retrieves detailed information about a rencontre
+- `get_rencontre_async` : Asynchronously retrieves detailed information about a rencontre
+- `get_engagement` : Retrieves detailed information about an engagement
+- `get_engagement_async` : Asynchronously retrieves detailed information about an engagement
+- `get_engagement_contacts` : Return compact contact information for an engagement
+- `get_formation` : Retrieves detailed information about a formation
+- `get_formation_async` : Asynchronously retrieves detailed information about a formation
+- `get_entraineur` : Retrieves detailed information about an entraineur
+- `get_entraineur_async` : Asynchronously retrieves detailed information about an entraineur
+- `get_commune` : Retrieves detailed information about a commune
+- `get_commune_async` : Asynchronously retrieves detailed information about a commune
+- `get_officiel` : Retrieves detailed information about an officiel
+- `get_officiel_async` : Asynchronously retrieves detailed information about an officiel
+- `get_salle` : Retrieves detailed information about a salle
+- `get_salle_async` : Asynchronously retrieves detailed information about a salle
+- `get_terrain` : Retrieves detailed information about a terrain
+- `get_terrain_async` : Asynchronously retrieves detailed information about a terrain
+- `get_tournoi` : Retrieves detailed information about a tournoi
+- `get_tournoi_async` : Asynchronously retrieves detailed information about a tournoi
+- `get_pratique` : Retrieves detailed information about a pratique
+- `get_pratique_async` : Asynchronously retrieves detailed information about a pratique
+- `get_openapi_spec` : Retrieves the current Directus OpenAPI specification
+- `get_openapi_spec_async` : Asynchronously retrieves the current Directus OpenAPI specification
+- `get_session` : Retrieves detailed information about a formation session
+- `get_session_async` : Asynchronously retrieves detailed information about a formation session
+- `list_sessions` : Lists formation sessions
+- `list_sessions_async` : Asynchronously lists formation sessions
+- `get_genius_sport_match` : Retrieves detailed Genius Sports match statistics
+- `get_genius_sport_match_async` : Asynchronously retrieves detailed Genius Sports match statistics
+- `list_genius_sport_matches` : Lists Genius Sports match statistics
+- `list_genius_sport_matches_async` : Asynchronously lists Genius Sports match statistics
+- `list_genius_sports_live_logs` : Lists Genius Sports live logs
+- `list_genius_sports_live_logs_async` : Asynchronously lists Genius Sports live logs
+- `get_rematch_video` : Retrieves a Rematch video linked to FFBB data
+- `get_rematch_video_async` : Asynchronously retrieves a Rematch video linked to FFBB data
+- `list_rematch_videos` : Lists Rematch videos linked to FFBB data
+- `list_rematch_videos_async` : Asynchronously lists Rematch videos linked to FFBB data
+- `get_edf_match` : Retrieves an Equipe de France match
+- `get_edf_match_async` : Asynchronously retrieves an Equipe de France match
+- `list_edf_matches` : Lists Equipe de France matches
+- `list_edf_matches_async` : Asynchronously lists Equipe de France matches
+- `get_edf_player` : Retrieves an Equipe de France player
+- `get_edf_player_async` : Asynchronously retrieves an Equipe de France player
+- `list_edf_players` : Lists Equipe de France players
+- `list_edf_players_async` : Asynchronously lists Equipe de France players
+- `list_edf_teams` : Lists Equipe de France teams
+- `list_edf_teams_async` : Asynchronously lists Equipe de France teams
+- `list_edf_rosters` : Lists Equipe de France rosters
+- `list_edf_rosters_async` : Asynchronously lists Equipe de France rosters
+- `list_rencontres` :
+- `list_rencontres_async` :
+- `list_salles` :
+- `list_salles_async` :
+- `list_terrains` :
+- `list_terrains_async` :
+- `list_tournois` :
+- `list_tournois_async` :
+- `list_engagements` :
+- `list_engagements_async` :
+- `list_formations` :
+- `list_formations_async` :
+- `list_entraineurs` :
+- `list_entraineurs_async` :
+- `list_communes` :
+- `list_communes_async` :
+- `list_officiels` :
+- `list_officiels_async` :
+- `list_pratiques` :
+- `list_pratiques_async` :
+- `list_all_rencontres` :
+- `list_all_rencontres_async` :
+- `list_all_salles` :
+- `list_all_salles_async` :
+- `list_all_terrains` :
+- `list_all_terrains_async` :
+- `list_all_tournois` :
+- `list_all_tournois_async` :
+- `list_all_engagements` :
+- `list_all_engagements_async` :
+- `list_all_formations` :
+- `list_all_formations_async` :
+- `list_all_entraineurs` :
+- `list_all_entraineurs_async` :
+- `list_all_communes` :
+- `list_all_communes_async` :
+- `list_all_officiels` :
+- `list_all_officiels_async` :
+- `list_all_pratiques` :
+- `list_all_pratiques_async` :
+- `list_engagements_by_ids` :
+- `list_engagements_by_poule` :
+- `list_engagements_by_poules` :
+- `list_rencontres_by_poule` :
+- `list_rencontres_by_poules` :
+- `list_entraineurs_by_ids` :
+
+## Méthodes de Recherche Meilisearch (Exemples importants)
+Le SDK expose également des méthodes de recherche optimisées avec facettes, géolocalisation et filtres via Meilisearch :
+- `multi_search` : Perform multi-search across all resource types with input validation
+- `multi_search_async` : Performs a smart multi-search asynchronously
+- `search_competitions` :
+- `search_multiple_competitions` :
+- `search_competitions_async` : Search for competitions asynchronously
+- `search_multiple_competitions_async` : Search for multiple competitions asynchronously
+- `search_organismes` :
+- `search_organismes_by_geo` :
+- `search_organismes_by_city` :
+- `search_multiple_organismes` :
+- `search_organismes_async` : Search for organismes asynchronously
+- `search_multiple_organismes_async` : Search for multiple organismes asynchronously
+- `search_pratiques` :
+- `search_multiple_pratiques` :
+- `search_pratiques_async` : Search for pratiques asynchronously
+- `search_multiple_pratiques_async` : Search for multiple pratiques asynchronously
+- `search_rencontres` :
+- `search_multiple_rencontres` :
+- `search_rencontres_async` : Search for rencontres asynchronously
+- `search_multiple_rencontres_async` : Search for multiple rencontres asynchronously
+- `search_salles` :
+- `search_salles_by_geo` :
+- `search_multiple_salles` :
+- `search_salles_async` : Search for salles asynchronously
+- `search_multiple_salles_async` : Search for multiple salles asynchronously
+- `search_terrains` :
+- `search_multiple_terrains` :
+- `search_terrains_async` : Search for terrains asynchronously
+- `search_multiple_terrains_async` : Search for multiple terrains asynchronously
+- `search_tournois` :
+- `search_multiple_tournois` :
+- `search_tournois_async` : Search for tournois asynchronously
+- `search_multiple_tournois_async` : Search for multiple tournois asynchronously
+- `search_engagements` :
+- `search_engagements_by_geo` :
+- `search_engagements_filtered` :
+- `search_multiple_engagements` :
+- `search_engagements_async` : Search for engagements asynchronously
+- `search_multiple_engagements_async` : Search for multiple engagements asynchronously
+- `search_formations` :
+- `search_multiple_formations` :
+- `search_formations_async` : Search for formations asynchronously
+- `search_multiple_formations_async` : Search for multiple formations asynchronously
+- `search_news` :
+- `search_multiple_news` :
+- `search_youtube_videos` :
+- `search_multiple_youtube_videos` :
+- `search_rss` :
+- `search_multiple_rss` :
+- `search_galeries` :
+- `search_multiple_galeries` :
+
+## Variables d'environnement
+Le SDK résout automatiquement les jetons de sécurité via les variables d'environnement suivantes
+ou interroge l'API publique en cache en cas d'absence :
+
+| Variable | Défaut | Usage |
+|----------|--------|-------|
+| `API_FFBB_APP_BEARER_TOKEN` | — | Jeton Bearer de sécurité pour requêter directement l'API FFBB (api.ffbb.app) |
+| `MEILISEARCH_BEARER_TOKEN` | — | Jeton Bearer de sécurité pour interroger le moteur Meilisearch (meilisearch-prod.ffbb.app) |
+
+## Règles de comportement des agents
+- **RTK OBLIGATOIRE** : Utilisez TOUJOURS le préfixe `rtk` pour toutes les commandes terminal
+  exécutées sur la machine de l'utilisateur (ex: `rtk pytest`, `rtk tox`, etc.).
+- **Tox & Pytest** : Privilégiez l'exécution des tests via `pytest` local ou `tox` pour valider
+  les évolutions du SDK sur les différentes versions de Python prises en charge.
+- **Modèles typés** : Respectez scrupuleusement la déclaration des types Pydantic de `ffbb_data_client.models`.
+  Tout nouveau modèle ou modification de champ doit correspondre aux spécifications de l'API FFBB.
+- **Réponses en français** : Communiquez et expliquez toujours vos changements ou vos analyses en langue française.
+
+## Karpathy Guidelines (Règles de développement)
+Ces directives inspirées d'Andrej Karpathy visent à éliminer les erreurs de codage courantes en privilégiant la simplicité et la rigueur :
+
+### 1. Penser avant de coder (Think Before Coding)
+- **Ne pas assumer, ne pas cacher la confusion, expliciter les compromis.**
+- Avant d'implémenter :
+  - Déclarez vos hypothèses de manière explicite. En cas d'incertitude, demandez.
+  - S'il existe plusieurs interprétations, présentez-les — ne choisissez pas en silence.
+  - Si une approche plus simple existe, proposez-la. Argumentez contre la complexité inutile si nécessaire.
+  - Si quelque chose n'est pas clair, arrêtez-vous. Nommez ce qui vous perturbe et demandez confirmation.
+
+### 2. La simplicité d'abord (Simplicity First)
+- **Le minimum de code nécessaire pour résoudre le problème. Rien de spéculatif.**
+- Pas de fonctionnalités au-delà de ce qui est explicitement demandé.
+- Pas d'abstractions pour du code à usage unique.
+- Pas de "flexibilité" ou de "configurabilité" non requise.
+- Pas de gestion d'erreurs pour des scénarios impossibles.
+- Si vous écrivez 200 lignes alors que 50 suffiraient, réécrivez-le.
+- Posez-vous toujours la question : "Est-ce qu'un développeur senior validerait cette implémentation comme simple et directe ?"
+
+## Architecture du SDK
+```
+src/ffbb_data_client/
+├── __init__.py            # Point d'entrée du SDK, expose FFBBDataClient et FFBBTokens
+├── clients/               # Clients d'API (REST et Meilisearch) et façades (≈6259 lignes)
+├── config.py              # Configuration centralisée (URLs, Headers, Endpoints, Facettes)
+├── data/                  # Ressources et données statiques
+├── helpers/               # Méthodes utilitaires pour requêtes HTTP et mapping (≈790 lignes)
+├── models/                # Modèles de données Pydantic type-safe (≈9878 lignes)
+├── py.typed               # Marqueur pour la compatibilité avec mypy
+└── utils/                 # Gestionnaires transversaux (cache, jetons de sécurité, validation) (≈1840 lignes)
+```
+
+## Conventions de code
+- **Modèles Pydantic** : Tous les modèles héritent de `pydantic.BaseModel` et fournissent une validation stricte.
+- **Async/Sync en parallèle** : Le SDK implémente systématiquement la double interface synchrone (`get_x`)
+  et asynchrone (`get_x_async`) pour un maximum de flexibilité d'intégration.
+- **Cache HTTP** : Utilisation d'`hishel` pour le cache de requêtes HTTP asynchrones et d'un cache local
+  configurable pour optimiser les appels et respecter les quotas FFBB.
+- **Validation** : Les paramètres passés à `FFBBDataClient.create` sont strictement validés
+  via les utilitaires de validation robustes de `utils/input_validation.py`.
+
+## Commandes courantes
+- Lancer les tests locaux : `rtk pytest`
+- Lancer la suite d'intégration Tox : `rtk tox`
+- Vérifier les types : `rtk mypy src`
+- Formater et vérifier le style : `rtk ruff format . && rtk ruff check .`
+
+## Push / Tag / Release Gate
+⚠️ OBLIGATION STRICTE : Toutes ces commandes DOIVENT être préfixées par 'rtk' dans le terminal
+(ex: 'rtk pytest'). Ne jamais exécuter de commande nue sans 'rtk'.
+Avant push/tag/release :
+1. `rtk ruff format --check .`
+2. `rtk ruff check .`
+3. `rtk mypy src`
+4. `rtk pytest`

{ffbb_data_client-2.1.0 → ffbb_data_client-2.3.0}/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0] - 2026-05-24
+
+### Added
+- **API Schema Drift Detection**: Automated detection of changes inside Directus OpenAPI schemas (added/removed/modified properties, nested types, and nullability changes)
+- **Meilisearch Attributes Drift Detection**: Automated detection of changes inside Meilisearch index schemas (`sampleKeys`) with robust sampling over 20 hits
+- **CI/CD Pull Request Automation**: Pre-commit hooks and GitHub Actions workflow automatically open a Pull Request when any API property or index drift is detected
+- Detailed Schema Drift reporting in `data/api_update_summary.md` and `report["drift"]` payload
+
+### Fixed
+- Robust Meilisearch sampling: index keys are now aggregated across 20 hits instead of 1, preventing false positives on optional null fields
+- Pre-commit & flake8 E501 line too long violations in `tools/update_agents_md.py`
+- Formatted `AGENTS.md` spacing and line wrapping for flawless agent ingestion
+
+## [2.2.0] - 2026-05-17
+
+### Changed
+- **REFACTOR**: `FFBBDataClient` (2865 → 272 lines) split into modular facades — `_RestFacade` (1592 lines) and `_SearchFacade` (1020 lines)
+- Public API remains 100% backward-compatible — all 167 methods accessible directly on `FFBBDataClient`
+- `check_wrapper_parity.py` updated to scan facade files in addition to the main client
+
+### Added
+- `pytest_asyncio_mode = "auto"` in `pyproject.toml` for pytest-asyncio compatibility
+- `isolated_build = True` in `tox.ini` for proper PEP 517 builds
+
+### Fixed
+- `CacheManager` docstring corrected — Redis backend marked as "planned" (not implemented)
+- `readme_renderer[md]` moved from `install_requires` to `testing` extras (build-time only dependency)
+
+### Removed
+- Orphaned `src/ffbb_api_client_v3/` directory (residual from v2.1.0 cleanup)
+- Orphaned `.coverage` file at project root
+- `benchmark_search_organisme.py` moved from root to `scripts/`
+
 ## [2.1.0] - 2026-05-17
 
 ### Changed

{ffbb_data_client-2.1.0 → ffbb_data_client-2.3.0}/CONTRIBUTING.rst

@@ -1,28 +1,3 @@
-.. todo:: THIS IS SUPPOSED TO BE AN EXAMPLE. MODIFY IT ACCORDING TO YOUR NEEDS!
-
-   The document assumes you are using a source repository service that promotes a
-   contribution model similar to `GitHub's fork and pull request workflow`_.
-   While this is true for the majority of services (like GitHub, GitLab,
-   BitBucket), it might not be the case for private repositories (e.g., when
-   using Gerrit).
-
-   Also notice that the code examples might refer to GitHub URLs or the text
-   might use GitHub specific terminology (e.g., *Pull Request* instead of *Merge
-   Request*).
-
-   Please make sure to check the document having these assumptions in mind
-   and update things accordingly.
-
-.. todo:: Provide the correct links/replacements at the bottom of the document.
-
-.. todo:: You might want to have a look on `PyScaffold's contributor's guide`_,
-
-   especially if your project is open source. The text should be very similar to
-   this template, but there are a few extra contents that you might decide to
-   also include, like mentioning labels of your issue tracker or automated
-   releases.
-
-
 ============
 Contributing
 ============

{ffbb_data_client-2.1.0/src/ffbb_data_client.egg-info → ffbb_data_client-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ffbb-data-client
-Version: 2.1.0
+Version: 2.3.0
 Summary: FFBB Data Client — SDK Python asynchrone pour les Statistiques de Basket France. Type-safe Pydantic models, async/sync, Meilisearch.
 Home-page: https://github.com/nickdesi/ffbb-data-client
 Author: nickdesi
@@ -33,7 +33,6 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown; charset=UTF-8
 License-File: LICENSE.txt
 Requires-Dist: python-dotenv>=1.2.2
-Requires-Dist: readme_renderer[md]>=44.0
 Requires-Dist: python-dateutil>=2.9.0.post0
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: hishel[async]>=1.2.1
@@ -46,6 +45,7 @@ Requires-Dist: pytest-xdist>=3.8.0; extra == "testing"
 Requires-Dist: pytest-cov>=7.1.0; extra == "testing"
 Requires-Dist: respx>=0.23.1; extra == "testing"
 Requires-Dist: pytest-asyncio>=1.3.0; extra == "testing"
+Requires-Dist: readme_renderer[md]>=44.0; extra == "testing"
 Provides-Extra: typing
 Requires-Dist: types-python-dateutil>=2.9.0.20260408; extra == "typing"
 Dynamic: license-file
@@ -85,18 +85,17 @@ Dynamic: license-file
 - du cache HTTP configurable via `hishel` ;
 - des helpers prêts pour l'intégration MCP / agents IA.
 
-> La V3 remplace l’approche V2 basée sur des dictionnaires bruts et une configuration manuelle. Elle privilégie le typage, la robustesse réseau et les appels batchés.
-
 ---
 
-## 🚀 Version v2.1.0 — Mai 2026
+## 🚀 Version v2.2.0 — Mai 2026
 
 Principales évolutions récentes :
 
-- **unification sync/async** : les méthodes synchrones délèguent désormais à leurs homologues asynchrones via `_run_async()`, éliminant ~604 lignes de duplication ;
+- **refactor architecture** : `FFBBDataClient` (2865 → 272 lignes) découpé en `_RestFacade` + `_SearchFacade` — API publique 100% compatible ;
+- **unification sync/async** : les méthodes synchrones délèguent à leurs homologues asynchrones via `_run_async()`, éliminant ~604 lignes de duplication ;
 - **nouvelles entités** : EDF (matches, joueurs, rosters, équipes), Genius Sport (matches, live logs), Rematch Videos ;
 - **cache SQLite concurrency-safe** : fichiers séparés pour sync (`http_cache.db`) et async (`http_cache_async.db`) ;
-- **CI renforcée** : mypy + pyright + CodeQL + Dependabot + hook pre-push ;
+- **CI renforcée** : mypy + pyright + CodeQL + Dependabot + hook pre-push + wrapper parity check ;
 - **nettoyage** : suppression du shim `ffbb_api_client_v3`, scripts morts et code mort (`invalidate_pattern`).
 
 Voir aussi : [`CHANGELOG.md`](CHANGELOG.md) et [`RELEASE_NOTES.md`](RELEASE_NOTES.md).
@@ -272,7 +271,9 @@ Il est donc possible de laisser le client résoudre les tokens automatiquement o
 ```text
 src/ffbb_data_client/
 ├── clients/
-│   ├── ffbb_data_client.py       # Façade publique (sync → async delegation)
+│   ├── ffbb_data_client.py       # Façade publique (272 lignes, delegation)
+│   ├── _rest_facade.py           # Façade REST API (Directus)
+│   ├── _search_facade.py         # Façade recherche Meilisearch
 │   ├── api_ffbb_app_client.py    # Client REST FFBB (async source of truth)
 │   └── meilisearch_ffbb_client.py # Client recherche Meilisearch
 ├── helpers/                       # Requêtes HTTP, multi-search, conversions
@@ -282,6 +283,8 @@ src/ffbb_data_client/
 ```
 
 > **Architecture sync/async** : Depuis v2.1.0, les méthodes asynchrones sont la source de vérité. Les méthodes synchrones délèguent via `_run_async()`, un helper qui gère les event loops imbriqués avec `ThreadPoolExecutor`.
+>
+> **Architecture facades** : Depuis v2.2.0, `FFBBDataClient` est une fine coquille qui compose `_RestFacade` et `_SearchFacade`. L'API publique reste identique — `client.get_organisme(123)` fonctionne comme avant.
 
 ---
 
@@ -313,6 +316,28 @@ Documentation complémentaire :
 
 ---
 
+## 🛠️ Découverte d'API et Détection de Drift (Schema Drift)
+
+Le projet intègre un système robuste de surveillance quotidienne de l'API de production de la FFBB (Directus & Meilisearch) afin de détecter immédiatement l'apparition de nouvelles ressources, de nouveaux champs ou de changements de types.
+
+### 1. Fonctionnement
+* **Script de découverte** : `scripts/discover_endpoints.py` interroge dynamiquement l'OpenAPI spec Directus de la FFBB, extrait toutes les collections, sonde les index Meilisearch (via un échantillonnage agrégé sur 20 hits) et calcule les différences structurelles avec les fichiers locaux.
+* **Détection de dérive** : Le script compare les structures internes de chaque modèle (propriétés ajoutées, supprimées ou types modifiés) ainsi que les attributs Meilisearch, et génère un rapport consolidé dans `data/api_update_summary.md`.
+
+### 2. Automatisation CI/CD
+Un workflow quotidien (`update-ffbb-api-discovery.yml`) s'exécute chaque matin à 5h17 UTC pour :
+1. Télécharger l'OpenAPI spec et sonder Meilisearch en production.
+2. Analyser les dérives structurelles.
+3. Si un changement structurel est détecté (ajout de collection, de propriétés ou d'index), le workflow ouvre automatiquement une **Pull Request** sur GitHub contenant un résumé des modifications pour permettre aux développeurs de mettre à jour les modèles Pydantic.
+
+### 3. Exécution locale
+Pour lancer manuellement la découverte d'API et mettre à jour les fichiers de schémas locaux :
+```bash
+python scripts/discover_endpoints.py
+```
+
+---
+
 ## 🤖 Intégration IA / MCP
 
 Le client sert de base au serveur MCP FFBB et expose une API stable pour construire des outils agent-friendly : recherche de clubs, récupération de poules, classements, lives, calendriers et détails de rencontres.

{ffbb_data_client-2.1.0 → ffbb_data_client-2.3.0}/README.md

@@ -33,18 +33,17 @@
 - du cache HTTP configurable via `hishel` ;
 - des helpers prêts pour l'intégration MCP / agents IA.
 
-> La V3 remplace l’approche V2 basée sur des dictionnaires bruts et une configuration manuelle. Elle privilégie le typage, la robustesse réseau et les appels batchés.
-
 ---
 
-## 🚀 Version v2.1.0 — Mai 2026
+## 🚀 Version v2.2.0 — Mai 2026
 
 Principales évolutions récentes :
 
-- **unification sync/async** : les méthodes synchrones délèguent désormais à leurs homologues asynchrones via `_run_async()`, éliminant ~604 lignes de duplication ;
+- **refactor architecture** : `FFBBDataClient` (2865 → 272 lignes) découpé en `_RestFacade` + `_SearchFacade` — API publique 100% compatible ;
+- **unification sync/async** : les méthodes synchrones délèguent à leurs homologues asynchrones via `_run_async()`, éliminant ~604 lignes de duplication ;
 - **nouvelles entités** : EDF (matches, joueurs, rosters, équipes), Genius Sport (matches, live logs), Rematch Videos ;
 - **cache SQLite concurrency-safe** : fichiers séparés pour sync (`http_cache.db`) et async (`http_cache_async.db`) ;
-- **CI renforcée** : mypy + pyright + CodeQL + Dependabot + hook pre-push ;
+- **CI renforcée** : mypy + pyright + CodeQL + Dependabot + hook pre-push + wrapper parity check ;
 - **nettoyage** : suppression du shim `ffbb_api_client_v3`, scripts morts et code mort (`invalidate_pattern`).
 
 Voir aussi : [`CHANGELOG.md`](CHANGELOG.md) et [`RELEASE_NOTES.md`](RELEASE_NOTES.md).
@@ -220,7 +219,9 @@ Il est donc possible de laisser le client résoudre les tokens automatiquement o
 ```text
 src/ffbb_data_client/
 ├── clients/
-│   ├── ffbb_data_client.py       # Façade publique (sync → async delegation)
+│   ├── ffbb_data_client.py       # Façade publique (272 lignes, delegation)
+│   ├── _rest_facade.py           # Façade REST API (Directus)
+│   ├── _search_facade.py         # Façade recherche Meilisearch
 │   ├── api_ffbb_app_client.py    # Client REST FFBB (async source of truth)
 │   └── meilisearch_ffbb_client.py # Client recherche Meilisearch
 ├── helpers/                       # Requêtes HTTP, multi-search, conversions
@@ -230,6 +231,8 @@ src/ffbb_data_client/
 ```
 
 > **Architecture sync/async** : Depuis v2.1.0, les méthodes asynchrones sont la source de vérité. Les méthodes synchrones délèguent via `_run_async()`, un helper qui gère les event loops imbriqués avec `ThreadPoolExecutor`.
+>
+> **Architecture facades** : Depuis v2.2.0, `FFBBDataClient` est une fine coquille qui compose `_RestFacade` et `_SearchFacade`. L'API publique reste identique — `client.get_organisme(123)` fonctionne comme avant.
 
 ---
 
@@ -261,6 +264,28 @@ Documentation complémentaire :
 
 ---
 
+## 🛠️ Découverte d'API et Détection de Drift (Schema Drift)
+
+Le projet intègre un système robuste de surveillance quotidienne de l'API de production de la FFBB (Directus & Meilisearch) afin de détecter immédiatement l'apparition de nouvelles ressources, de nouveaux champs ou de changements de types.
+
+### 1. Fonctionnement
+* **Script de découverte** : `scripts/discover_endpoints.py` interroge dynamiquement l'OpenAPI spec Directus de la FFBB, extrait toutes les collections, sonde les index Meilisearch (via un échantillonnage agrégé sur 20 hits) et calcule les différences structurelles avec les fichiers locaux.
+* **Détection de dérive** : Le script compare les structures internes de chaque modèle (propriétés ajoutées, supprimées ou types modifiés) ainsi que les attributs Meilisearch, et génère un rapport consolidé dans `data/api_update_summary.md`.
+
+### 2. Automatisation CI/CD
+Un workflow quotidien (`update-ffbb-api-discovery.yml`) s'exécute chaque matin à 5h17 UTC pour :
+1. Télécharger l'OpenAPI spec et sonder Meilisearch en production.
+2. Analyser les dérives structurelles.
+3. Si un changement structurel est détecté (ajout de collection, de propriétés ou d'index), le workflow ouvre automatiquement une **Pull Request** sur GitHub contenant un résumé des modifications pour permettre aux développeurs de mettre à jour les modèles Pydantic.
+
+### 3. Exécution locale
+Pour lancer manuellement la découverte d'API et mettre à jour les fichiers de schémas locaux :
+```bash
+python scripts/discover_endpoints.py
+```
+
+---
+
 ## 🤖 Intégration IA / MCP
 
 Le client sert de base au serveur MCP FFBB et expose une API stable pour construire des outils agent-friendly : recherche de clubs, récupération de poules, classements, lives, calendriers et détails de rencontres.

{ffbb_data_client-2.1.0 → ffbb_data_client-2.3.0}/RELEASE_NOTES.md

@@ -1,6 +1,31 @@
 # Release Notes - FFBB API Client V2
 
-## Version 1.5.0 (Latest Release)
+## Version 2.2.0 (Latest Release)
+
+### 🏗 Architecture Refactor
+
+#### **Facade Pattern — FFBBDataClient Modularization**
+- **REFACTOR**: `FFBBDataClient` split from a monolithic 2865-line file into three focused modules:
+  - `ffbb_data_client.py` (272 lines) — thin public facade with factory and delegation
+  - `_rest_facade.py` (1592 lines) — all REST API (Directus) methods
+  - `_search_facade.py` (1020 lines) — all Meilisearch search methods
+- **BACKWARD-COMPATIBLE**: All 167 public methods remain accessible directly on `FFBBDataClient` instances — zero breaking changes
+- Methods delegated via `setattr` at construction time — no performance impact
+
+#### **CI & Build Improvements**
+- `pytest_asyncio_mode = "auto"` — prevents pytest-asyncio breaking changes across versions
+- `isolated_build = True` in tox — proper PEP 517 builds with setuptools_scm
+- `check_wrapper_parity.py` updated to scan facade files alongside the main client
+
+### 🐛 Bug Fixes & Cleanup
+- `CacheManager` docstring corrected — Redis backend documented as "planned"
+- `readme_renderer[md]` moved to dev extras (was incorrectly in runtime dependencies)
+- Orphaned `src/ffbb_api_client_v3/` directory removed
+- `benchmark_search_organisme.py` moved to `scripts/`
+
+---
+
+## Version 2.1.0 (Previous Release)
 
 ### 🚀 Major Features & Improvements
 

ffbb_data_client-2.3.0/data/api_update_summary.md

@@ -0,0 +1,30 @@
+# FFBB API update summary
+
+- Timestamp: `2026-05-24T11:03:57.203628+00:00`
+- API base URL: `https://api.ffbb.app/`
+- Meilisearch base URL: `https://meilisearch-prod.ffbb.app/`
+- OpenAPI version: `9be33d74bfb480282da91c53c8dfa29804914c96`
+- OpenAPI SHA256: `d63e8450719e2580e1ab6c4960d6de978c1e2ab457f5e9d71cc3e872ed272641`
+
+## Directus collections
+- Total: `164`
+- Added: None
+- Removed: None
+
+## Directus item paths
+- Total: `331`
+- Added: None
+- Removed: None
+
+## Meilisearch indexes
+- Available total: `13`
+- Added: None
+- Removed: None
+
+## Directus schema properties drift
+- **ItemsFfbbsiteBlockJobs** :
+  - Added properties: `code`, `subscription_form`, `type_filter`
+- **ItemsFfbbsiteJobs** :
+  - Added properties: `category`, `date_published`, `degree`, `postal_code`, `structure`, `structure_linked`, `terms_contact`, `type`
+
+Generated by `python scripts/discover_endpoints.py`.