france-data-mcp 0.7.2

package/dist/sante/index.d.ts

@@ -0,0 +1,1053 @@
+import { C as Coordinates, L as LookupResult } from '../types-6cvLQmuz.js';
+
+/**
+ * DINUM Recherche Entreprises — annuaire des entreprises françaises (SIRENE + RNE).
+ *
+ * URL : https://recherche-entreprises.api.gouv.fr/search
+ * Doc : https://recherche-entreprises.api.gouv.fr/docs/
+ *
+ * Rate limit documenté : 7 req/s. Observé en pratique : ~1 req/s effectif après le
+ * premier 429 (header retry-after: 4 systématique). Le helper fetchJson respecte
+ * retry-after, mais ne pas dépasser 1 req/s en burst pour éviter les 429 répétés.
+ *
+ * Sans clé API, sans authentification, CORS autorisé.
+ *
+ * Données utiles côté santé : le filtre `activite_principale` (NAF) permet de
+ * cibler labos (8690B), pharmacies (4773Z), maisons médicales (8621Z), SSR
+ * (8610Z), EHPAD (8710A), centres médico-sociaux, etc.
+ */
+
+type Etablissement = {
+    /** SIRET 14 chiffres */
+    siret: string;
+    /** Adresse complète */
+    adresse: string;
+    /** Code postal */
+    codePostal?: string;
+    /** Commune */
+    commune?: string;
+    /** Coordonnées GPS si l'adresse est géocodée */
+    point?: Coordinates;
+    /** Code NAF de l'établissement */
+    naf?: string;
+    /** Établissement actif administrativement (etat_administratif === "A") */
+    actif: boolean;
+    /** Tranche d'effectif salarié (codes INSEE 0..53) */
+    trancheEffectif?: string;
+    /** Date de création de l'établissement */
+    dateCreation?: string;
+};
+type Finance = {
+    annee: number;
+    ca?: number;
+    resultatNet?: number;
+    /**
+     * Signal de fiabilité du `ca`. `false` quand `ca===0` ET `resultatNet>0` :
+     * pattern observé à 100% sur les SELARL pharma (NAF 47.73Z) qui ne déclarent
+     * pas leur CA au RNE — il ne faut pas l'afficher comme un vrai 0. Vraie
+     * dormance (`resultatNet<=0` ou undefined) reste `caFiable: true`.
+     */
+    caFiable: boolean;
+};
+type Dirigeant = {
+    nom?: string;
+    prenoms?: string;
+    fonction?: string;
+    qualite?: string;
+};
+/**
+ * État de l'enrichissement de la liste `etablissements` :
+ *
+ * - `not_attempted` : monosite (ou data SIRENE manquante) — pas de second appel.
+ * - `success` : `etablissements.length === nombreEtablissements` (ou >=).
+ * - `partial` : second appel OK mais retourne moins que le total SIRENE
+ *   (cause typique : entreprise multi-département ou NAF secondaires).
+ * - `failed` : second appel a échoué (rate limit, panne API, parsing…).
+ *   `enrichmentWarning` contient le message d'erreur.
+ */
+type EnrichmentStatus = "not_attempted" | "success" | "partial" | "failed";
+/** Source d'origine du lookup d'une `Entreprise`. Voir champ `siren_source` ci-dessous. */
+type EntrepriseSirenSource = "dinum" | "insee_v3";
+type Entreprise = {
+    /** SIREN 9 chiffres */
+    siren: string;
+    /** SIRET du siège (14 chiffres) */
+    siretSiege?: string;
+    /** Nom complet (raison sociale ou nom + prénom pour entrepreneurs individuels) */
+    nomComplet: string;
+    /** Code NAF principal */
+    naf?: string;
+    /** Libellé NAF principal */
+    nafLibelle?: string;
+    /** Tranche d'effectif (CA / RN dans `finances`) */
+    trancheEffectif?: string;
+    /** Code juridique INSEE */
+    natureJuridique?: string;
+    /** Finances historiques par année (les plus récentes sont en premier) */
+    finances: Finance[];
+    /** Dirigeants déclarés au RNE */
+    dirigeants: Dirigeant[];
+    /**
+     * Établissements actifs et inactifs.
+     *
+     * ⚠️ Pour `searchEntreprises({ q })` ou `getEntrepriseBySiren()`, ce champ peut
+     * ne contenir que le siège — l'API DINUM ne retourne que les établissements
+     * « matchant » la requête. `getEntrepriseBySiren()` fait un second appel
+     * automatique pour récupérer les établissements du même NAF principal dans
+     * le département du siège.
+     *
+     * **Le caller doit lire `enrichmentStatus`** pour savoir si la liste est
+     * complète (`success`), tronquée (`partial`), ou si l'enrichissement a échoué
+     * (`failed`). Comparer aussi `etablissements.length` à `nombreEtablissements`.
+     */
+    etablissements: Etablissement[];
+    /** Nombre total d'établissements (actifs + fermés), source SIRENE */
+    nombreEtablissements?: number;
+    /** Nombre d'établissements actuellement ouverts, source SIRENE */
+    nombreEtablissementsOuverts?: number;
+    /**
+     * État de l'enrichissement multi-sites (cf. `EnrichmentStatus`).
+     * Toujours présent pour les retours de `getEntrepriseBySiren()`.
+     * Absent pour les `searchEntreprises()` (pas d'enrichissement tenté).
+     */
+    enrichmentStatus?: EnrichmentStatus;
+    /** Message d'aide quand `enrichmentStatus` ∈ {"partial", "failed"}. */
+    enrichmentWarning?: string;
+    /**
+     * Source effective du lookup. `"dinum"` (défaut implicite) = retour de l'API
+     * recherche-entreprises.api.gouv.fr. `"insee_v3"` = fallback SIRENE INSEE V3
+     * activé quand DINUM ne connaît pas le SIREN (cas diffusion partielle). En
+     * mode insee_v3, finances/dirigeants/etablissements sont vides — l'API
+     * /siren/{siren} ne les expose pas sans appels supplémentaires /siret.
+     */
+    siren_source?: EntrepriseSirenSource;
+    /** Statut administratif global */
+    actif: boolean;
+};
+type SearchEntreprisesOptions = {
+    /** Recherche textuelle (raison sociale, dirigeant…) */
+    q?: string;
+    /** Filtre exact sur le code NAF (ex: "8690B" pour labos d'analyses médicales) */
+    naf?: string;
+    /** Filtre par code postal */
+    codePostal?: string;
+    /** Filtre par département (code 2 ou 3 caractères) */
+    departement?: string;
+    /** Filtre par code commune INSEE */
+    codeCommune?: string;
+    /**
+     * Recherche géographique : centre + rayon (km, max 50). DOIT être combiné
+     * avec `q` (recherche textuelle) — l'API DINUM rejette `naf + lat/lon/radius`
+     * directement. Pour combiner NAF + zone géographique, utiliser le tool MCP
+     * `entreprises_in_radius` qui applique un fallback automatique
+     * (reverseGeocode → département → filtre Haversine).
+     */
+    center?: Coordinates;
+    /** Rayon en km (1-50). Requis si `center` est fourni. */
+    radiusKm?: number;
+    /** Limiter aux établissements administrativement actifs (défaut: true) */
+    onlyActive?: boolean;
+    /** Page de résultats (1-indexed, défaut 1) */
+    page?: number;
+    /** Résultats par page (1-25, défaut 10) */
+    perPage?: number;
+    signal?: AbortSignal;
+};
+type SearchEntreprisesResult = {
+    total: number;
+    page: number;
+    perPage: number;
+    totalPages: number;
+    entreprises: Entreprise[];
+};
+/**
+ * Recherche d'entreprises avec filtres NAF / géo / texte libre.
+ *
+ * @example Tous les labos de bio médicale dans 5 km autour d'un point
+ * ```ts
+ * const labos = await searchEntreprises({
+ *   naf: "8690B",
+ *   center: { lon: 4.7192, lat: 49.7672 },
+ *   radiusKm: 5,
+ * });
+ * ```
+ *
+ * @example Toutes les pharmacies du 08
+ * ```ts
+ * const pharma = await searchEntreprises({ naf: "4773Z", departement: "08" });
+ * ```
+ */
+declare function searchEntreprises(options: SearchEntreprisesOptions): Promise<SearchEntreprisesResult>;
+/**
+ * Récupère une entreprise par son SIREN (9 chiffres).
+ * Renvoie null si introuvable. Throw si l'API DINUM est en panne ou rate-limit dépassé.
+ *
+ * Implémentation :
+ * 1. `q=<siren>` (l'API DINUM matche le SIREN dans le full-text), filtrage côté
+ *    client sur l'égalité exacte du SIREN.
+ * 2. **Limitation API DINUM** : `q=<siren>` ne retourne que le siège dans
+ *    `matching_etablissements`. Pour récupérer les autres établissements, on
+ *    fait un second appel `activite_principale=<naf>&departement=<dept_siège>`
+ *    qui retourne tous les établissements de l'entreprise ayant le NAF
+ *    principal dans le département du siège (couvre la majorité des
+ *    multi-sites). Les `etablissements` du résultat fusionnent siège + ces
+ *    établissements supplémentaires (déduplication par SIRET).
+ * 3. `nombreEtablissements` / `nombreEtablissementsOuverts` reflètent toujours
+ *    le total réel SIRENE (non limité par l'API DINUM).
+ *
+ * **Limitation indexation DINUM** : certaines entreprises pourtant actives à
+ * l'INSEE/SIRENE ne sont PAS indexées par `recherche-entreprises.api.gouv.fr`
+ * (statut de diffusion partielle au sens INSEE — `statut_diffusion ∈ {P,N}` —
+ * ou exclusion sectorielle/légale). Ces SIREN reviennent `null` ici alors
+ * qu'ils existent réellement. L'audit post-v0.2.0 a vérifié ce comportement
+ * sur le SIREN 787120435 (Bio Ard'Aisne, SAS Rethel) : présent dans SIRENE
+ * via la "fabrique social.gouv" mais absent de l'API DINUM publique.
+ * Pour ce cas d'usage, fallback : interroger SIRENE INSEE directement (avec
+ * authentification API), ou utiliser `entreprises_in_radius` par zone géo.
+ */
+declare function getEntrepriseBySiren(siren: string, signal?: AbortSignal): Promise<LookupResult<Entreprise>>;
+
+/**
+ * INSEE SIRENE V3.11 — fallback authentifié pour les SIREN absents de DINUM.
+ *
+ * Pourquoi : `recherche-entreprises.api.gouv.fr` (DINUM) exclut les entreprises
+ * en diffusion partielle INSEE (`statut_diffusion ∈ {P,N}`). Cas connu : SIREN
+ * 787120435 (BIO ARD'AISNE) présent dans SIRENE mais absent de DINUM. Pour ces
+ * SIREN, on fallback sur l'API SIRENE INSEE directement (clé requise).
+ *
+ * Auth (vérifié 2026-05-09 sur portail-api.insee.fr V3.11) :
+ * - Header **`X-INSEE-Api-Key-Integration: <api-key>`** (UUID issu du portail).
+ *   Bearer / apikey / X-Gravitee-Api-Key tous renvoient 401 — c'est le custom
+ *   header Gravitee configuré côté gateway INSEE qui prime.
+ * - Endpoint : `GET https://api.insee.fr/api-sirene/3.11/siren/{siren}`
+ * - Rate limit : 30 req/min (header `x-rate-limit-limit: 30`).
+ *
+ * Payload V3.11 : les champs métier (denomination, nom, prénom, NAF, état
+ * administratif, catégorie juridique) sont dans
+ * `uniteLegale.periodesUniteLegale[0]` (la période la plus récente, ordre
+ * antéchronologique), PAS sur `uniteLegale` directement.
+ *
+ * No-op gracieux : si `INSEE_SIRENE_API_KEY` n'est pas configurée,
+ * `lookupSirenViaInsee` retourne null sans throw — la lib reste utilisable
+ * sans clé INSEE.
+ */
+
+/**
+ * Lit `INSEE_SIRENE_API_KEY` depuis l'env. Retourne `null` si absente ou vide
+ * (no-op gracieux : la lib reste utilisable sans clé INSEE).
+ *
+ * Strippe aussi les guillemets entourants — certains parsers `.env` (ou un
+ * copier-coller Vercel UI) les conservent, et l'API INSEE rejette alors
+ * silencieusement la clé en 401, ce qui ressemble à une clé révoquée.
+ */
+declare function getInseeApiKey(): string | null;
+/**
+ * Récupère une entreprise par SIREN via l'API SIRENE INSEE V3.11.
+ *
+ * Comportement :
+ * - Pas de clé configurée → `null` (no-op gracieux, pas de throw)
+ * - HTTP 404 → `null` (vraiment pas dans SIRENE)
+ * - HTTP 401/403 → `null` + `console.error` (clé invalide ou révoquée)
+ * - HTTP 5xx / timeout / erreur réseau → `null` + `console.error`
+ * - HTTP 200 → `Entreprise` mappée minimale (siren, nomComplet, naf, actif)
+ *
+ * ⚠️ Rate limit INSEE : 30 req/min. `fetchJson` retry sur 429 en respectant
+ * `retry-after`, mais en burst soutenu (>30 lookups/min) les retries se
+ * sérialisent et la latence p99 explose. Conçu comme fallback ponctuel sur
+ * SIREN diffusion partielle (cas rare ~1% des SIREN), pas comme source primaire.
+ */
+declare function lookupSirenViaInsee(siren: string): Promise<Entreprise | null>;
+
+/**
+ * Cache fichier local pour les dumps publics téléchargés (FINESS, Annuaire Ameli, INSEE…).
+ *
+ * Stratégie : un fichier de cache par dataset, refresh si plus vieux que `ttlMs`.
+ * Pas de coordination multi-process — si deux processus tentent de refresh en
+ * parallèle, le second écrase le premier (acceptable pour des dumps de référence
+ * publics).
+ *
+ * Localisation par défaut : `~/.cache/france-data-mcp/` (suit XDG-ish sur macOS/Linux).
+ */
+type CacheOptions = {
+    /** Dossier où stocker les caches (défaut : ~/.cache/france-data-mcp) */
+    cacheDir?: string;
+    /** Durée de vie en millisecondes avant refresh */
+    ttlMs?: number;
+    /** Forcer le refresh même si le cache est encore valide */
+    force?: boolean;
+    /** User-Agent à envoyer pour le téléchargement */
+    userAgent?: string;
+    signal?: AbortSignal;
+};
+
+/**
+ * FINESS — Fichier National des Établissements Sanitaires et Médico-Sociaux.
+ *
+ * Source : data.gouv.fr → dump CSV bimestriel ~35 Mo (`finess-extraction-du-fichier-des-etablissements`).
+ * Variante géolocalisée : Atlasanté `referentiel-finess-t-finess` (~232 Mo).
+ *
+ * ⚠️ Migration ANS été 2026 : tous les datasets data.gouv portent l'avertissement
+ * que la génération du flux actuel s'arrêtera. Surveiller le repo
+ * github.com/ansforge/finess pour le nouveau format (probablement FHIR-compatible).
+ *
+ * Cette fonction télécharge le CSV avec cache 7j puis charge en mémoire (~35 Mo
+ * → ~70 Mo de RAM résidente Node). Adapté à un usage CLI ou serveur node long.
+ * Pour un usage serverless (Vercel Edge), ne pas charger l'intégralité —
+ * préférer une DB externe (PostGIS, DuckDB).
+ */
+
+type EtablissementFiness = {
+    /** Numéro FINESS de l'entité géographique (ET) sur 9 chiffres */
+    finessEt: string;
+    /** Numéro FINESS de l'entité juridique (EJ) à laquelle l'ET est rattaché */
+    finessEj?: string;
+    /** Raison sociale (longue, plus complète que le nom court) */
+    raisonSociale: string;
+    /** Code de catégorie d'établissement (ex: "500" pour EHPAD) */
+    categorieCode?: string;
+    /** Libellé de la catégorie (mappé depuis FINESS_CATEGORIES si reconnu) */
+    categorieLibelle?: string;
+    /** Adresse ligne complète */
+    adresse?: string;
+    /** Code postal */
+    codePostal?: string;
+    /** Commune */
+    commune?: string;
+    /** Code INSEE de la commune (5 caractères) */
+    codeCommune?: string;
+    /** Code département (2 ou 3 caractères) */
+    departement?: string;
+    /** Coordonnées GPS (présentes dans le dump géolocalisé Atlasanté) */
+    point?: Coordinates;
+    /** Téléphone */
+    telephone?: string;
+    /** SIREN si renseigné */
+    siren?: string;
+};
+type LoadFinessOptions = CacheOptions & {
+    /**
+     * Chemin local d'un CSV déjà téléchargé (court-circuite le download).
+     *
+     * @security Cette option fait un `readFile` direct du chemin fourni. Ne
+     * JAMAIS la forwarder depuis une entrée non-trustée (requête HTTP, args MCP) :
+     * c'est un read fichier local non restreint. Strictement réservé à un usage
+     * Node.js trusted.
+     */
+    csvPath?: string;
+};
+type SearchFinessOptions = {
+    /** Filtre par codes de catégorie (ex: ["500"] pour EHPAD seuls) */
+    categories?: string[];
+    /** Filtre par code postal exact */
+    codePostal?: string;
+    /** Filtre par code département */
+    departement?: string;
+    /** Filtre par code commune INSEE */
+    codeCommune?: string;
+    /** Recherche géographique : centre + rayon en km (nécessite dump géolocalisé) */
+    center?: Coordinates;
+    /** Rayon en km */
+    radiusKm?: number;
+    /** Limite de résultats (défaut tous) */
+    limit?: number;
+};
+/**
+ * Charge l'index FINESS en mémoire. Télécharge le CSV si pas en cache.
+ * Le résultat est utilisable plusieurs fois sans re-charger.
+ */
+declare function loadFiness(options?: LoadFinessOptions): Promise<EtablissementFiness[]>;
+/**
+ * Recherche des établissements dans un index FINESS pré-chargé.
+ * Pour avoir l'index : `const index = await loadFiness();`
+ */
+declare function searchEtablissementsFiness(index: EtablissementFiness[], options: SearchFinessOptions): EtablissementFiness[];
+/**
+ * Distance Haversine entre deux points GPS, en mètres.
+ * Formule sphérique standard (suffisante pour les rayons < 100 km).
+ */
+declare function haversineDistance(a: Coordinates, b: Coordinates): number;
+
+/**
+ * Annuaire Santé Ameli — répertoire des professionnels de santé libéraux conventionnés.
+ *
+ * Source : data.gouv.fr `annuaire-sante-ameli` (CSV ~146 Mo, ~1,5M lignes).
+ * MAJ hebdomadaire (régénération chaque dimanche/lundi).
+ *
+ * ⚠️ Article L.1461-2 CSP : ces données contiennent des informations à
+ * caractère personnel. Leur réutilisation est soumise au respect de la
+ * réglementation relative à la protection de la vie privée. Toute application
+ * publique doit afficher la mention "Source : Annuaire santé Ameli, Assurance
+ * Maladie" et la date de la dernière sync.
+ *
+ * Volume : 146 Mo → trop pour charger en mémoire intégralement. Cette lib
+ * propose un parser **streaming** : on lit le CSV ligne par ligne et on filtre
+ * à la volée. Pour faire de la recherche par rayon géographique, il faut au
+ * préalable géocoder les adresses (à faire côté caller, pas géré ici).
+ */
+
+type ProfessionnelSante = {
+    /** Nom de famille (en exercice) */
+    nom: string;
+    /** Prénom(s) (en exercice) */
+    prenom: string;
+    /** Civilité (Dr, Mme, M.…) */
+    civilite?: string;
+    /** Raison sociale du lieu d'exercice si applicable */
+    raisonSociale?: string;
+    /** Code spécialité Ameli */
+    specialiteCode?: string;
+    /** Libellé de la spécialité (ex: "Médecin généraliste", "Cardiologue") */
+    specialiteLibelle?: string;
+    /** Code type de PS (médecin, IDE, sage-femme, pharmacien…) */
+    typePsCode?: string;
+    /** Libellé du type de PS */
+    typePsLibelle?: string;
+    /** Voie + numéro */
+    adresse?: string;
+    /** Complément d'adresse (étage, bâtiment…) */
+    complementAdresse?: string;
+    /** Code postal du lieu d'exercice */
+    codePostal?: string;
+    /** Commune du lieu d'exercice */
+    commune?: string;
+    /** Téléphone */
+    telephone?: string;
+    /** Secteur conventionnel (1, 2, 3, NC…) */
+    secteurConventionnel?: string;
+    /** Libellé du secteur conventionnel */
+    secteurConventionnelLibelle?: string;
+    /** Mode d'exercice (libéral, salarié, mixte…) */
+    natureExercice?: string;
+};
+type StreamAnnuaireOptions = CacheOptions & {
+    /**
+     * Chemin local d'un CSV déjà téléchargé (court-circuite le download).
+     *
+     * @security Cette option ouvre un `createReadStream` direct sur le chemin
+     * fourni. Ne JAMAIS la forwarder depuis une entrée non-trustée (requête
+     * HTTP, args MCP) : c'est une lecture fichier local non restreinte qui peut
+     * exposer des fichiers sensibles. Strictement réservé à un usage Node.js
+     * trusted (CLI, script, code applicatif).
+     */
+    csvPath?: string;
+};
+type FilterAnnuaireOptions = {
+    /** Filtre exact par code postal */
+    codePostal?: string;
+    /** Filtre par préfixe de code postal (ex: "08" pour tout le département 08) */
+    codePostalPrefix?: string;
+    /** Filtre par nom de commune (insensible à la casse) */
+    commune?: string;
+    /** Filtre par libellé de spécialité (insensible à la casse, contient) */
+    specialite?: string;
+    /** Filtre par code spécialité exact */
+    specialiteCode?: string;
+    /** Filtre par type de PS (Médecin, IDE, etc., insensible à la casse) */
+    typePs?: string;
+    /** Filtre par secteur conventionnel ("1", "2"…) */
+    secteurConventionnel?: string;
+    /** Limite (arrête le stream une fois atteinte) */
+    limit?: number;
+};
+/**
+ * S'assure que le CSV Annuaire Ameli est en cache local et renvoie son chemin.
+ * Télécharge si nécessaire (~146 Mo, ~30 secondes en bonne connexion).
+ */
+declare function ensureAnnuaireAmeli(options?: StreamAnnuaireOptions): Promise<string>;
+/**
+ * Stream les professionnels de santé un par un, avec filtres optionnels.
+ * Utilise un parser CSV streaming pour ne pas charger les 146 Mo en mémoire.
+ *
+ * @example Tous les MG du 08
+ * ```ts
+ * const out: string[] = [];
+ * for await (const ps of streamProfessionnels({ codePostalPrefix: "08", specialite: "généraliste" })) {
+ *   out.push(`${ps.nom} ${ps.prenom} - ${ps.commune}`);
+ * }
+ * ```
+ */
+declare function streamProfessionnels(options?: StreamAnnuaireOptions & FilterAnnuaireOptions): AsyncGenerator<ProfessionnelSante>;
+/**
+ * Charge un sous-ensemble filtré en mémoire (pratique pour les zones géographiques
+ * étroites — un département entier reste raisonnable).
+ */
+declare function loadProfessionnels(options?: StreamAnnuaireOptions & FilterAnnuaireOptions): Promise<ProfessionnelSante[]>;
+
+/**
+ * Mapping des codes NAF utiles pour l'analyse santé / médico-social.
+ *
+ * Source : nomenclature NAF rév.2 INSEE (2008).
+ * Liste non exhaustive — focus sur les activités santé pertinentes pour
+ * l'intelligence territoriale (implantation, prospection, audit).
+ */
+declare const NAF_SANTE: {
+    readonly "8610Z": "Activités hospitalières";
+    readonly "8621Z": "Activités de médecine générale";
+    readonly "8622A": "Activités de radiodiagnostic et de radiothérapie";
+    readonly "8622B": "Activités chirurgicales";
+    readonly "8622C": "Autres activités des médecins spécialistes";
+    readonly "8623Z": "Pratique dentaire";
+    readonly "8690A": "Ambulances";
+    readonly "8690B": "Laboratoires d'analyses médicales";
+    readonly "8690C": "Centres de collecte et banques d'organes";
+    readonly "8690D": "Activités des infirmiers et des sages-femmes";
+    readonly "8690E": "Activités des professionnels de la rééducation, de l'appareillage et des pédicures-podologues";
+    readonly "8690F": "Activités de santé humaine non classées ailleurs";
+    readonly "8710A": "Hébergement médicalisé pour personnes âgées";
+    readonly "8710B": "Hébergement médicalisé pour enfants handicapés";
+    readonly "8710C": "Hébergement médicalisé pour adultes handicapés et autre hébergement médicalisé";
+    readonly "8720A": "Hébergement social pour handicapés mentaux et malades mentaux";
+    readonly "8720B": "Hébergement social pour toxicomanes";
+    readonly "8730A": "Hébergement social pour personnes âgées";
+    readonly "8730B": "Hébergement social pour handicapés physiques";
+    readonly "8810A": "Aide à domicile";
+    readonly "8810B": "Accueil ou accompagnement sans hébergement d'adultes handicapés ou de personnes âgées";
+    readonly "8810C": "Aide par le travail";
+    readonly "8891A": "Accueil de jeunes enfants";
+    readonly "8891B": "Accueil ou accompagnement sans hébergement d'enfants handicapés";
+    readonly "8899A": "Autre accueil ou accompagnement sans hébergement d'enfants et d'adolescents";
+    readonly "8899B": "Action sociale sans hébergement n.c.a.";
+    readonly "4773Z": "Commerce de détail de produits pharmaceutiques en magasin spécialisé";
+    readonly "4774Z": "Commerce de détail d'articles médicaux et orthopédiques en magasin spécialisé";
+};
+type NafCodeSante = keyof typeof NAF_SANTE;
+/**
+ * Codes NAF correspondant aux laboratoires de biologie médicale et activités proches.
+ */
+declare const NAF_LABOS: readonly ["8690B"];
+/**
+ * Codes NAF correspondant aux pharmacies d'officine.
+ */
+declare const NAF_PHARMACIES: readonly ["4773Z"];
+/**
+ * Codes NAF correspondant aux EHPAD et hébergement médicalisé pour personnes âgées.
+ */
+declare const NAF_EHPAD: readonly ["8710A", "8730A"];
+/**
+ * Codes NAF correspondant à la médecine de ville (généralistes + spécialistes).
+ */
+declare const NAF_MEDECINE_VILLE: readonly ["8621Z", "8622A", "8622B", "8622C"];
+/**
+ * Renvoie le libellé d'un code NAF santé, ou undefined si non répertorié.
+ */
+declare function libelleNaf(code: string): string | undefined;
+
+/**
+ * FINESS DREES category nomenclature — codes + libellés.
+ *
+ * Catalogue ~50 codes représentant ~92% du volume FINESS (95K rows total).
+ * Le reliquat ~8% tombe en famille `autre` (codes très rares : thermal,
+ * lieux de vie expérimentaux, structures atypiques).
+ *
+ * Source: live FINESS extract on data.gouv.fr. Re-verify against the CSV
+ * when adding codes — DREES occasionally rotates labels (les libellés
+ * sont copiés à l'identique du CSV pour matcher exactement la nomenclature
+ * officielle).
+ */
+declare const FINESS_CATEGORIES: {
+    readonly "101": "Centre Hospitalier Régional (C.H.R.)";
+    readonly "106": "Centre hospitalier";
+    readonly "108": "Centre Hospitalier Universitaire (C.H.U.)";
+    readonly "114": "Hôpital des armées";
+    readonly "115": "Etablissement de Soins du Service de Santé des Armées";
+    readonly "128": "Etablissement de Soins Chirurgicaux";
+    readonly "129": "Etablissement de Soins Médicaux";
+    readonly "131": "Centre de Lutte Contre le Cancer (C.L.C.C.)";
+    readonly "355": "Centre Hospitalier (C.H.)";
+    readonly "365": "Etablissement de Soins Pluridisciplinaire";
+    readonly "109": "Etablissement de santé privé autorisé en SSR";
+    readonly "362": "Etablissement de Soins Longue Durée (USLD)";
+    readonly "127": "Hospitalisation à Domicile (HAD)";
+    readonly "141": "Centre de dialyse";
+    readonly "146": "Structure d'Alternative à la dialyse en centre";
+    readonly "292": "Centre Hospitalier Spécialisé lutte Maladies Mentales";
+    readonly "156": "Centre Médico-Psychologique (C.M.P.)";
+    readonly "161": "Maison de Santé pour Maladies Mentales";
+    readonly "425": "Centre d'Accueil Thérapeutique à temps partiel (C.A.T.T.P.)";
+    readonly "430": "Centre Postcure Malades Mentaux";
+    readonly "124": "Centre de Santé";
+    readonly "603": "Maison de santé (L.6223-3)";
+    readonly "604": "Communautés professionnelles territoriales de santé (CPTS)";
+    readonly "611": "Laboratoire de Biologie Médicale";
+    readonly "619": "Cabinet d'imagerie médicale";
+    readonly "620": "Pharmacie d'Officine";
+    readonly "627": "Propharmacie";
+    readonly "500": "Etablissement d'hébergement pour personnes âgées dépendantes (EHPAD)";
+    readonly "501": "EHPA percevant des crédits d'assurance maladie";
+    readonly "502": "EHPA ne percevant pas des crédits d'assurance maladie";
+    readonly "202": "Résidences autonomie";
+    readonly "207": "Centre de Jour pour Personnes Agées";
+    readonly "463": "Centres Locaux Information Coordination P.A. (C.L.I.C.)";
+    readonly "354": "Service de Soins Infirmiers à Domicile (S.S.I.A.D.)";
+    readonly "460": "Service d'Aide et d'Accompagnement à Domicile (S.A.A.D.)";
+    readonly "209": "Service Polyvalent Aide et Soins à Domicile (S.P.A.S.A.D.)";
+    readonly "182": "Service d'Éducation Spéciale et de Soins à Domicile (SESSAD)";
+    readonly "183": "Institut Médico-Éducatif (I.M.E.)";
+    readonly "186": "Institut Thérapeutique Éducatif et Pédagogique (I.T.E.P.)";
+    readonly "188": "Etablissement pour Enfants ou Adolescents Polyhandicapés";
+    readonly "189": "Centre Médico-Psycho-Pédagogique (C.M.P.P.)";
+    readonly "190": "Centre Action Médico-Sociale Précoce (C.A.M.S.P.)";
+    readonly "192": "Institut d'éducation motrice";
+    readonly "194": "Institut pour Déficients Visuels";
+    readonly "195": "Institut pour Déficients Auditifs";
+    readonly "196": "Institut d'Education Sensorielle Sourd/Aveugle";
+    readonly "246": "Etablissement et Service d'Aide par le Travail (E.S.A.T.)";
+    readonly "247": "Entreprise adaptée";
+    readonly "252": "Foyer Hébergement Adultes Handicapés";
+    readonly "255": "Maison d'Accueil Spécialisée (M.A.S.)";
+    readonly "382": "Foyer de Vie pour Adultes Handicapés";
+    readonly "437": "Foyer d'Accueil Médicalisé pour Adultes Handicapés (F.A.M.)";
+    readonly "445": "Service d'accompagnement médico-social adultes handicapés (SAMSAH)";
+    readonly "446": "Service d'Accompagnement à la Vie Sociale (S.A.V.S.)";
+    readonly "448": "Etab. Acc. Médicalisé en tout ou partie personnes handicapées";
+    readonly "449": "Etab. Accueil Non Médicalisé pour personnes handicapées";
+    readonly "600": "Foyer d'hébergement pour adultes handicapés";
+    readonly "165": "Appartement de Coordination Thérapeutique (A.C.T.)";
+    readonly "178": "Centre Accueil/Accomp. Réduc. Risq. Usag. Drogues (C.A.A.R.U.D.)";
+    readonly "180": "Lits Halte Soins Santé (L.H.S.S.)";
+    readonly "197": "Centre soins accompagnement prévention addictologie (C.S.A.P.A.)";
+    readonly "412": "Appartement Thérapeutique";
+    readonly "175": "Foyer de l'Enfance";
+    readonly "177": "Maison d'Enfants à Caractère Social (MECS)";
+    readonly "295": "Services AEMO et AED";
+    readonly "236": "Centre Placement Familial Socio-Educatif (C.P.F.S.E.)";
+    readonly "238": "Centre d'Accueil Familial Spécialisé";
+    readonly "241": "Foyer d'Action Educative (F.A.E.)";
+    readonly "440": "Service Investigation Orientation Educative (S.I.O.E.)";
+    readonly "441": "Centre d'Action Educative (C.A.E.)";
+    readonly "378": "Etablissement Expérimental Enfance Protégée";
+    readonly "223": "Protection Maternelle et Infantile (P.M.I.)";
+    readonly "228": "Centre Planification ou Education Familiale";
+    readonly "230": "Etablissement Consultation Protection Infantile";
+    readonly "268": "Centre Médico-Scolaire";
+    readonly "214": "Centre Hébergement & Réinsertion Sociale (C.H.R.S.)";
+    readonly "219": "Autre Centre d'Accueil";
+    readonly "256": "Foyer Travailleurs Migrants non transformé en Résidence Sociale";
+    readonly "257": "Foyer de Jeunes Travailleurs (résidence sociale ou non)";
+    readonly "258": "Maisons Relais - Pensions de Famille";
+    readonly "259": "Autre Résidence Sociale (hors Maison Relais)";
+    readonly "443": "Centre Accueil Demandeurs Asile (C.A.D.A.)";
+    readonly "442": "Centre Provisoire Hébergement (C.P.H.)";
+    readonly "462": "Lieux de vie";
+    readonly "166": "Etablissement d'Accueil Mère-Enfant";
+    readonly "132": "Etablissement de Transfusion Sanguine";
+    readonly "142": "Dispensaire Antituberculeux";
+    readonly "143": "Centre de Vaccination BCG";
+    readonly "266": "Dispensaire Antivénérien";
+    readonly "347": "Centre d'Examens de Santé";
+    readonly "636": "Centre de soins et de prévention";
+    readonly "696": "Groupement de coopération sanitaire de moyens";
+    readonly "697": "Groupement de coopération sanitaire — Etablissement de santé";
+    readonly "126": "Etablissement Thermal";
+    readonly "632": "Structure Dispensatrice à domicile d'Oxygène à usage médical";
+    readonly "698": "Autre Etablissement Loi Hospitalière";
+};
+type FinessCategorieCode = keyof typeof FINESS_CATEGORIES;
+declare function libelleCategorieFiness(code: string): string | undefined;
+/**
+ * FINESS family taxonomy. Drives the `familles` filter on the MCP tools.
+ *
+ * Each family is a precise, query-side tag — callers compose them via the
+ * `familles` array. Designed for prospection commerciale santé : labos
+ * ciblent MCO/EHPAD/CSI/MSP/CPTS/MAS/FAM/SLD/HAD, équipementiers ciblent
+ * EHPAD/résidences autonomie, services à domicile ciblent SAAD/SPASAD/SSIAD…
+ */
+type FinessFamille = "mco" | "ssr" | "sld" | "had" | "psychiatrie" | "dialyse" | "ambulatoire" | "labo" | "imagerie" | "pharmacie" | "msp_cpts" | "ehpad" | "residence_autonomie" | "senior_accompagnement" | "ssiad" | "aide_domicile" | "handicap_enfants" | "handicap_adultes" | "addictologie" | "enfance_protection" | "pmi" | "hebergement_social" | "prevention_sante" | "groupement" | "autre";
+/**
+ * Family classification of FINESS DREES category codes.
+ *
+ * `autre` is the catch-all : codes in FINESS_CATEGORIES that don't fit any
+ * specific family (ex. thermal). To get "everything else", omit the family
+ * filter and post-filter via `result.categorie.famille`.
+ *
+ * The `query` subtype excludes "autre" — the MCP tools accept this set for
+ * the `familles` parameter.
+ */
+type FinessFamilleQuery = Exclude<FinessFamille, "autre">;
+declare const FINESS_FAMILY_CODES: Record<FinessFamilleQuery, readonly string[]>;
+/**
+ * Classify a FINESS category code into a family for query-side filtering.
+ *
+ * Inputs are normalized first: `null`, `undefined`, empty string, and
+ * whitespace-only strings all resolve to "autre". Non-empty inputs are trimmed
+ * before matching, tolerating whitespace artefacts occasionally present in
+ * DREES dumps (e.g. `" 108 "` → "mco").
+ */
+declare function finessFamille(code: string | null | undefined): FinessFamille;
+/**
+ * All hospital-grade categories (MCO acute-care + SSR + SLD + HAD + psy).
+ * Use FINESS_FAMILY_CODES.mco for strict acute-care only.
+ */
+declare const FINESS_HOPITAUX: readonly string[];
+declare const FINESS_LABOS: readonly string[];
+declare const FINESS_PHARMACIES: readonly string[];
+declare const FINESS_EHPAD: readonly string[];
+declare const FINESS_MSP_CPTS: readonly string[];
+
+/**
+ * Métadonnées de requête exposées dans les réponses des tools de listing.
+ *
+ * Pourquoi : le caller MCP (Claude.ai, Cursor, agent LLM) ne peut pas deviner
+ * la nature du calcul de distance ni la précision géographique en lisant un
+ * `distance_km: 2.67`. Or les sources varient : FINESS expose des coords
+ * Lambert93 reprojetées en WGS84 (précision adresse), Ameli ne fournit que
+ * le centroïde commune (~3 km moyenne). Sans cette transparence, un caller
+ * peut prendre des décisions logistiques fausses (ex: "le LBM est à 2.67 km
+ * vol d'oiseau" — mais la distance routière fait facilement +20-30%).
+ *
+ * Pattern aligné sur le bloc `fallback` déjà présent dans
+ * `entreprises_in_radius` (cf. `api/tools.ts`) qui surface honnêtement la
+ * stratégie de fallback API DINUM.
+ */
+/**
+ * Précision géographique des coordonnées exposées dans les résultats.
+ *
+ * - `lambert93_natif_finess` : coords FINESS DREES (Lambert 93 reprojeté
+ *   WGS84 à l'ingestion). Précision adresse ~10 m côté DREES.
+ * - `centroide_commune_ameli` : coords Ameli (centroïde commune via
+ *   `geo.api.gouv.fr/communes`). Précision ~3 km moyenne — adapté à
+ *   l'analyse de densité, PAS au géocodage adresse.
+ */
+type GeoPrecision = "lambert93_natif_finess" | "centroide_commune_ameli" | "centroide_commune_ans" | "structure_finess";
+/**
+ * Méthode de calcul des distances exposées dans `distance_km`.
+ *
+ * - `haversine_postgis` : ST_Distance sur le type `geography` PostGIS.
+ *   Distance vol d'oiseau, pas routière. Pour la distance routière,
+ *   intégrer un service externe (OSRM, ORS) côté caller.
+ */
+type DistanceType = "haversine_postgis";
+interface QueryMetadata {
+    geo_precision: GeoPrecision;
+    /** Présent uniquement quand la requête expose `distance_km` (radius). */
+    distance_type?: DistanceType;
+    /** Notes actionnables pour le caller (précision attendue, cross-checks…). */
+    notes: string[];
+}
+
+interface FinessResult {
+    num_finess: string;
+    raison_sociale: string;
+    categorie: {
+        code: string | null;
+        libelle: string | null;
+        famille: FinessFamille;
+    };
+    adresse: {
+        voie: string | null;
+        code_postal: string | null;
+        ville: string | null;
+        code_departement: string | null;
+        code_insee: string;
+    };
+    coords: {
+        lat: number;
+        lon: number;
+    } | null;
+    distance_km: number | null;
+    telephone: string | null;
+    email: string | null;
+}
+interface InRadiusInput {
+    center: {
+        lat: number;
+        lon: number;
+    };
+    radiusKm: number;
+    familles?: FinessFamilleQuery[];
+    limit?: number;
+}
+interface ByCategorieInput {
+    famille: FinessFamilleQuery;
+    departement?: string;
+    code_insee?: string;
+    limit?: number;
+}
+interface FinessQueryResult {
+    count: number;
+    truncated: boolean;
+    results: FinessResult[];
+    /**
+     * Métadonnées sur la précision géo et le type de distance. Surface au
+     * caller MCP que les coords proviennent du Lambert93 DREES (~adresse) et
+     * que la distance est haversine (pas routière). Inclut un rappel sur la
+     * latence DREES (~1-2 mois) pour les structures émergentes.
+     *
+     * Optionnel : tous les RPCs de prod la peuplent (cf. `getFinessInRadius`/
+     * `getFinessByCategorie`) ; cas d'absence réservé aux mocks tests.
+     */
+    query_metadata?: QueryMetadata;
+}
+/**
+ * Find FINESS establishments within a geographic radius. Spatial query uses
+ * PostGIS ST_DWithin on the geography type for accurate kilometers.
+ *
+ * Implemented via a Postgres RPC (`finess_in_radius`, migration
+ * 20260508000004) because supabase-js cannot express ST_DWithin / ST_Distance
+ * through its query builder.
+ */
+declare function getFinessInRadius(input: InRadiusInput): Promise<FinessQueryResult>;
+/**
+ * Find FINESS establishments by family (and optional dept / commune filters).
+ * No spatial query — pure WHERE on category code list + optional location.
+ */
+declare function getFinessByCategorie(input: ByCategorieInput): Promise<FinessQueryResult>;
+/**
+ * Fetch a single FINESS establishment by its 9-digit FINESS number.
+ *
+ * Retourne un `LookupResult` discriminé par `found`. Si le numéro n'existe
+ * pas dans le dump FINESS DREES (numéro mal formé, fermeture récente non
+ * encore propagée, frais d'établissement émergent — la base DREES a 1-2 mois
+ * de retard sur le terrain), la fonction renvoie un objet `{ found: false,
+ * lookupStatus: "not_found", message }` au lieu d'un `null` silencieux.
+ * Pattern aligné sur `getEntrepriseBySiren` et `getCommuneByCode`
+ * (cf. `src/core/lookup-result.ts`).
+ */
+declare function getFinessByNumFiness(numFiness: string): Promise<LookupResult<FinessResult>>;
+
+/**
+ * Codes mode d'exercice ANS (extrait de la nomenclature canonique).
+ * Documenté ici pour clarté du caller MCP qui veut filtrer par statut.
+ *
+ * Source : nomenclature de structure ANS, fichier `nomenclature-mode-exercice`.
+ */
+declare const RPPS_MODE_EXERCICE: {
+    readonly LIBERAL: "L";
+    readonly SALARIE: "S";
+    readonly MIXTE: "M";
+    readonly REMPLACANT: "R";
+    readonly AUTRE: "A";
+    readonly BENEVOLE: "B";
+};
+/**
+ * URL de référence ANS pour les nomenclatures publiques. Mention obligatoire
+ * en CGU des datasets data.gouv : « Source : Annuaire Santé, ANS — Licence
+ * Ouverte v2.0 ».
+ */
+declare const RPPS_CGU_NOTICE = "Source : Annuaire Sant\u00E9, Agence du Num\u00E9rique en Sant\u00E9 (ANS) \u2014 Licence Ouverte v2.0";
+
+/**
+ * RPPS / Annuaire Santé ANS — wrappers typés autour des RPCs PostGIS.
+ *
+ * Source : data.gouv `annuaire-sante-extractions-...-rpps`, Licence Ouverte v2.0.
+ * La mention obligatoire (ANS / Licence Ouverte v2.0) est portée par les
+ * descriptions des tools MCP (`api/tools.ts`). Ce module est le boundary
+ * technique, pas le boundary public.
+ *
+ * Diffère d'Ameli sur 3 points :
+ * - couverture : libéraux + salariés + étudiants + agents publics
+ *   (vs Ameli libéraux conventionnés uniquement)
+ * - identifiant stable : `rpps_id` (IDNPS national) → lookup individuel + dédup
+ * - pivot structure : `num_finess` exposé en colonne → croisement avec FINESS
+ *
+ * IMPORTANT : la base ne contient QUE des PS actifs. L'ANS pré-filtre le
+ * fichier `PS_LibreAcces_Personne_activite` à la source : retraités, décédés,
+ * radiés et suspendus n'apparaissent jamais dans cette extraction (cf. DSFT
+ * v3.1 §5.1.2). Le filtre par `categorie_code` discrimine donc des **statuts
+ * juridiques d'enregistrement** (Civil / Étudiant / Agent public), pas des
+ * statuts d'activité.
+ */
+
+interface RppsResult {
+    id: number;
+    rpps_id: string;
+    identite: {
+        nom: string;
+        prenom: string;
+        civilite: string | null;
+    };
+    profession: {
+        code: string | null;
+        libelle: string | null;
+    };
+    /** Spécialité fine (DES/DESC). Plus riche que la spécialité Ameli simple. */
+    savoir_faire: {
+        code: string | null;
+        libelle: string | null;
+    };
+    mode_exercice: {
+        code: string | null;
+        libelle: string | null;
+    };
+    /** Catégorie professionnelle ANS (TRE_R09) — voir `CATEGORIE_CODE_*` / `buildCategorieCodes`. */
+    categorie: {
+        code: string | null;
+        libelle: string | null;
+    };
+    /** Pivot vers FINESS / SIRENE. Souvent rempli pour les salariés, plus rare en libéral pur. */
+    structure: {
+        num_finess: string | null;
+        num_finess_ej: string | null;
+        siret: string | null;
+        raison_sociale: string | null;
+    };
+    adresse: {
+        voie: string | null;
+        code_postal: string | null;
+        ville: string | null;
+        code_departement: string | null;
+        code_insee: string | null;
+    };
+    coords: {
+        lat: number;
+        lon: number;
+    } | null;
+    distance_km: number | null;
+    telephone: string | null;
+    /**
+     * Score de pertinence trigram (0..1) — présent uniquement pour les retours
+     * de `rpps_search_by_name`. Permet au caller de filtrer les homonymies
+     * partielles (typiquement `< 0.5`).
+     */
+    match_score?: number;
+}
+interface RppsLookupResult extends RppsResult {
+    /** Identifiant PP legacy (pré-IDNPS), conservé quand fourni par l'extract. */
+    identifiant_pp: string | null;
+    siren: string | null;
+    email: string | null;
+}
+interface RppsInRadiusInput {
+    center: {
+        lat: number;
+        lon: number;
+    };
+    radiusKm: number;
+    /** Codes profession ANS (ex: "10" Médecin, "60" Infirmier). */
+    professionCodes?: string[];
+    /** Codes savoir-faire (DES/DESC). Granularité fine. */
+    savoirFaireCodes?: string[];
+    /** Codes mode exercice (L libéral, S salarié, M mixte, R remplaçant…). */
+    modeExerciceCodes?: string[];
+    /**
+     * Codes catégorie professionnelle ANS (table TRE_R09). Vide ou omis →
+     * filtre default = `[CATEGORIE_CODE_CIVIL]` (cf. `buildCategorieCodes`).
+     * Sinon → filtre exact ANY (le helper SQL `rpps_categorie_match` ajoute
+     * `OR IS NULL` défensif pour ne pas exclure les rows à code absent).
+     */
+    categorieCodes?: string[];
+    limit?: number;
+}
+interface RppsParSpecialiteDeptInput {
+    departement: string;
+    professionCode?: string;
+    savoirFaireCode?: string;
+    modeExerciceCode?: string;
+    /** Voir `RppsInRadiusInput.categorieCodes`. */
+    categorieCodes?: string[];
+    limit?: number;
+    offset?: number;
+}
+interface RppsDansEtablissementInput {
+    /** Numéro FINESS (9 chiffres) du site d'exercice. */
+    numFiness: string;
+    /** Voir `RppsInRadiusInput.categorieCodes`. */
+    categorieCodes?: string[];
+    limit?: number;
+}
+interface RppsQueryResult {
+    count: number;
+    truncated: boolean;
+    results: RppsResult[];
+    query_metadata?: QueryMetadata;
+}
+declare function getRppsInRadius(input: RppsInRadiusInput): Promise<RppsQueryResult>;
+declare function getRppsParSpecialiteDept(input: RppsParSpecialiteDeptInput): Promise<RppsQueryResult>;
+/** "Qui travaille dans ce FINESS ?" — lit la colonne indexée `num_finess`. */
+declare function getRppsDansEtablissement(input: RppsDansEtablissementInput): Promise<RppsQueryResult>;
+/**
+ * Lookup individuel par RPPS ID. Renvoie N rows quand un PS multi-sites
+ * existe (1 ligne par site). Le caller MCP aplatit en `(rpps_id, sites[])`.
+ */
+declare function getRppsById(rppsId: string): Promise<RppsLookupResult[]>;
+
+/**
+ * Annuaire Santé ANS — fallback FHIR live (libre accès, depuis avril 2025).
+ *
+ * Pourquoi : la table `rpps` est ingérée mensuellement depuis le CSV
+ * data.gouv. Pour les SP qui ne sont pas encore dans le snapshot DB (récente
+ * inscription, mutation de structure non répercutée), on offre un fallback
+ * live via l'API FHIR ANS qui est rafraîchie quotidiennement côté ANS.
+ *
+ * Auth (vérifié 2026-05-09 sur portail.openfhir.annuaire.sante.fr) :
+ * - Header **`ESANTE-API-KEY: <api-key>`** (UUID issu d'une souscription
+ *   Gravitee gratuite sur portal.api.esante.gouv.fr).
+ * - Endpoint : `GET https://gateway.api.esante.gouv.fr/fhir/v2/Practitioner?identifier=...`
+ * - Pas de quota documenté pendant la bêta (publique depuis avril 2025) ;
+ *   limits annoncées « après fin 2025 ».
+ *
+ * Identifiants : l'API expose `Practitioner.identifier` typé `IDNPS`
+ * (système OID `urn:oid:1.2.250.1.71.4.2.1`). Le CSV legacy expose le
+ * même champ sous "Identification nationale PP" (11 ou 12 chars selon que
+ * le préfixe Type d'identifiant `81` est concaténé ou pas — IDNPS modernes
+ * = 12 chars, anciens = 11). On cherche par IDNPS qui matche le `rpps_id`
+ * que l'on stocke en DB.
+ *
+ * No-op gracieux : pas de clé → null sans throw — la lib reste utilisable
+ * sans clé ANS (la couverture DB suffit à la majorité des cas).
+ */
+declare function getAnsFhirApiKey(): string | null;
+/** Override optionnel (env de staging, mock test). Sinon endpoint officiel. */
+declare function getAnsFhirBaseUrl(): string;
+/**
+ * Résultat aplati d'un lookup ANS — surface minimaliste pour ne pas dupliquer
+ * la richesse FHIR. Le caller MCP (tool `professionnel_by_rpps`) injecte
+ * cette shape quand la DB ne trouve pas le PS.
+ */
+interface AnsFhirPractitioner {
+    /** ID interne ANS (format `003-NNNN-NNNN`). Distinct de l'IDNPS. */
+    ans_internal_id: string;
+    /** IDNPS / RPPS national (11 ou 12 chars selon génération). Identique à `rpps_id` côté DB. */
+    rpps_id: string;
+    civilite: string | null;
+    nom: string;
+    prenom: string;
+    active: boolean | null;
+    source: "ans_fhir";
+}
+/**
+ * Résultat discriminé d'un lookup ANS FHIR. **V0.7.0 breaking** — avant V0.7.0,
+ * la fonction retournait `null` indifféremment pour 4 cas (pas de clé, format
+ * invalide, PS absent, API down), masquant l'information critique au caller.
+ *
+ * - `found: true` → `practitioner` peuplé, source ANS live.
+ * - `status: "no_key"` → clé `ESANTE-API-KEY` non configurée côté serveur.
+ *   Fallback indisponible — le caller doit s'appuyer sur la DB locale.
+ * - `status: "invalid_format"` → `rpps_id` rejeté par la garde format
+ *   (11 ou 12 chiffres requis). Pas d'I/O réseau.
+ * - `status: "not_found"` → ANS a répondu, PS réellement absent (Bundle vide
+ *   ou 404). Retry inutile, PS pas inscrit à l'ANS.
+ * - `status: "api_error"` → ANS indisponible (5xx, timeout, 401, 403, network).
+ *   Retry justifié dans quelques minutes.
+ */
+type AnsFhirLookupResult = {
+    found: true;
+    practitioner: AnsFhirPractitioner;
+} | {
+    found: false;
+    status: "no_key" | "invalid_format" | "not_found" | "api_error";
+    message: string;
+};
+/**
+ * Lookup FHIR ANS par IDNPS / rpps_id. Utilisé en fallback du lookup DB.
+ * Latence p99 ~1-2s. Pas de cache local (ANS est rafraîchi quotidiennement).
+ *
+ * Retourne un `AnsFhirLookupResult` discriminé — voir le type pour les 5 cas
+ * possibles. **Aucun `null` silencieux** (V0.7.0 breaking, cf. JSDoc du type).
+ */
+declare function lookupPractitionerByRpps(rppsId: string): Promise<AnsFhirLookupResult>;
+
+/**
+ * Module sante — données françaises de santé publique.
+ *
+ * Sources :
+ *  - DINUM Recherche Entreprises → entreprises secteur santé (live API)
+ *  - FINESS (data.gouv) → établissements sanitaires et médico-sociaux (dump CSV bimestriel)
+ *  - Annuaire Santé Ameli (data.gouv/CNAM) → PS libéraux conventionnés (dump CSV hebdo)
+ *  - RPPS / Annuaire Santé ANS (data.gouv) → tous les PS (libéraux + salariés), ID stable, dump CSV mensuel
+ *  - FHIR ANS live → fallback fraîcheur quotidienne pour lookup individuel par RPPS ID
+ */
+
+declare const SANTE_VERSION = "0.5.1";
+
+export { type AnsFhirPractitioner, type ByCategorieInput, type Dirigeant, type Entreprise, type Etablissement, type EtablissementFiness, FINESS_CATEGORIES, FINESS_EHPAD, FINESS_FAMILY_CODES, FINESS_HOPITAUX, FINESS_LABOS, FINESS_MSP_CPTS, FINESS_PHARMACIES, type FilterAnnuaireOptions, type Finance, type FinessCategorieCode, type FinessFamille, type FinessFamilleQuery, type FinessQueryResult, type FinessResult, type InRadiusInput, type LoadFinessOptions, NAF_EHPAD, NAF_LABOS, NAF_MEDECINE_VILLE, NAF_PHARMACIES, NAF_SANTE, type NafCodeSante, type ProfessionnelSante, RPPS_CGU_NOTICE, RPPS_MODE_EXERCICE, type RppsDansEtablissementInput, type RppsInRadiusInput, type RppsLookupResult, type RppsParSpecialiteDeptInput, type RppsQueryResult, type RppsResult, SANTE_VERSION, type SearchEntreprisesOptions, type SearchEntreprisesResult, type SearchFinessOptions, type StreamAnnuaireOptions, ensureAnnuaireAmeli, finessFamille, getAnsFhirApiKey, getAnsFhirBaseUrl, getEntrepriseBySiren, getFinessByCategorie, getFinessByNumFiness, getFinessInRadius, getInseeApiKey, getRppsById, getRppsDansEtablissement, getRppsInRadius, getRppsParSpecialiteDept, haversineDistance, libelleCategorieFiness, libelleNaf, loadFiness, loadProfessionnels, lookupPractitionerByRpps, lookupSirenViaInsee, searchEntreprises, searchEtablissementsFiness, streamProfessionnels };