intelwatch 1.3.0 → 1.5.0

package/src/providers/annuaire-entreprises.js

@@ -0,0 +1,83 @@
+/**
+ * Annuaire Entreprises Provider — France only, 100% free, no API key.
+ *
+ * Wraps the src/scrapers/annuaire-entreprises.js into the provider interface.
+ * This is the zero-cost fallback when Pappers is unavailable or returns 401.
+ *
+ * Data available:
+ *   ✓ SIREN, SIRET, nom, NAF, nature juridique, adresse, effectifs
+ *   ✓ Dirigeants (nom, prénom, qualité)
+ *   ✓ Finances (CA, résultat net par année)
+ *   ✓ Catégorie entreprise (PME/ETI/GE)
+ *   ✗ UBO, BODACC, procédures collectives, mandats croisés, finances consolidées
+ */
+
+import {
+  annuaireSearchByName,
+  annuaireGetBySiren,
+  annuaireGetFullDossier,
+  annuaireLookup,
+} from '../scrapers/annuaire-entreprises.js';
+
+const annuaireEntreprisesProvider = {
+  name: 'annuaire-entreprises',
+  country: 'FR',
+  description: 'Annuaire Entreprises (data.gouv.fr) — French company registry, 100% free, no API key required',
+
+  /**
+   * Always available — this is a free, public API with no authentication.
+   */
+  isAvailable() {
+    return true;
+  },
+
+  /**
+   * Search companies by name.
+   * @param {string} query
+   * @param {{ count?: number }} options
+   * @returns {Promise<{ results: Array, error: string|null }>}
+   */
+  async search(query, options = {}) {
+    return annuaireSearchByName(query, options);
+  },
+
+  /**
+   * Get company profile by SIREN.
+   * @param {string} siren
+   * @param {{ preview?: boolean }} options
+   * @returns {Promise<{ data: object|null, error: string|null, fromCache?: boolean }>}
+   */
+  async getProfile(siren, options = {}) {
+    if (options.preview) {
+      return annuaireGetBySiren(siren);
+    }
+    // Full dossier
+    return annuaireGetFullDossier(siren);
+  },
+
+  /**
+   * Get subsidiaries — not available from Annuaire Entreprises.
+   * Returns empty with a descriptive note.
+   * @param {string} parentName
+   * @param {string} parentSiren
+   * @param {object} options
+   * @returns {Promise<{ subsidiaries: Array, error: string|null }>}
+   */
+  async getSubsidiaries(parentName, parentSiren, options = {}) {
+    return {
+      subsidiaries: [],
+      error: 'La recherche de filiales n\'est pas disponible via l\'Annuaire Entreprises. Utilisez Pappers pour cette fonctionnalité.',
+    };
+  },
+
+  /**
+   * Quick lookup for competitor tracker (name → basic company info).
+   * @param {string} companyName
+   * @returns {Promise<object|null>}
+   */
+  async lookup(companyName) {
+    return annuaireLookup(companyName);
+  },
+};
+
+export default annuaireEntreprisesProvider;

package/src/providers/index.js

@@ -10,11 +10,13 @@
 
 import { registerProvider } from './registry.js';
 import pappersProvider from './pappers.js';
+import annuaireEntreprisesProvider from './annuaire-entreprises.js';
 import opencorporatesProvider from './opencorporates.js';
 import clearbitProvider from './clearbit.js';
 import apolloProvider from './apollo.js';
 
 registerProvider('pappers', pappersProvider);
+registerProvider('annuaire-entreprises', annuaireEntreprisesProvider);
 registerProvider('opencorporates', opencorporatesProvider);
 registerProvider('clearbit', clearbitProvider);
 registerProvider('apollo', apolloProvider);

package/src/providers/registry.js

@@ -20,6 +20,7 @@
 import { isPro, requirePro, getLimits, gatePro } from '../license.js';
 
 // Providers that require Pro license for any API call
+// Note: 'pappers' is Pro-only, but 'annuaire-entreprises' is free — used as FR fallback
 const PRO_ONLY_PROVIDERS = new Set(['pappers', 'apollo', 'clearbit']);
 
 // ── TLD → Country mapping ────────────────────────────────────────────────────
@@ -65,6 +66,9 @@ const PROVIDER_MAP = {
   // All others → apollo for enrichment (extensible: add 'GB': 'companieshouse', etc.)
 };
 
+// France-specific fallback chain: Pappers (deep, paid) → Annuaire Entreprises (basic, free)
+const FR_FALLBACK_CHAIN = ['pappers', 'annuaire-entreprises'];
+
 // Fallback chain for international domains (tried in order, first available wins)
 const INTL_FALLBACK_CHAIN = ['apollo', 'clearbit', 'opencorporates'];
 
@@ -176,46 +180,93 @@ async function attemptFranceHandoff(intlProfileData, options = {}) {
 
   // French company detected on international TLD — get deep data from Pappers
   const pappersProvider = providers['pappers'];
-  if (!pappersProvider || !pappersProvider.isAvailable()) {
-    return {
-      data: { ...intlProfileData, _handoff: 'pappers_unavailable' },
-      handoff: false,
-    };
+  if (pappersProvider && pappersProvider.isAvailable()) {
+    const companyName = extractCompanyName(intlProfileData);
+    if (!companyName) {
+      return {
+        data: { ...intlProfileData, _handoff: 'no_company_name' },
+        handoff: false,
+      };
+    }
+
+    try {
+      // Search Pappers by company name to find the SIREN
+      const searchResult = await pappersProvider.search(companyName, { count: 1 });
+      const topResult = searchResult?.results?.[0];
+
+      if (!topResult?.siren) {
+        return {
+          data: { ...intlProfileData, _handoff: 'pappers_no_match' },
+          handoff: false,
+        };
+      }
+
+      // Get full Pappers profile by SIREN
+      const isPreview = options.preview || false;
+      const pappersProfile = isPreview
+        ? await pappersProvider.getProfile(topResult.siren, { preview: true })
+        : await pappersProvider.getProfile(topResult.siren, { preview: false });
+
+      // Check for 401 → try Annuaire Entreprises fallback
+      if (pappersProfile.error && /401|unauthorized|forbidden|key/i.test(pappersProfile.error)) {
+        return await attemptAnnuaireFallback(intlProfileData, companyName);
+      }
+
+      const pappersData = pappersProfile?.data;
+      const merged = mergeWithPappers(intlProfileData, pappersData);
+      return { data: merged, handoff: true };
+    } catch {
+      return await attemptAnnuaireFallback(intlProfileData, extractCompanyName(intlProfileData));
+    }
   }
 
-  const companyName = extractCompanyName(intlProfileData);
-  if (!companyName) {
+  // Pappers unavailable → try Annuaire Entreprises fallback
+  return await attemptAnnuaireFallback(intlProfileData, extractCompanyName(intlProfileData));
+}
+
+/**
+ * Attempt France handoff via Annuaire Entreprises (free fallback).
+ * @param {object} intlProfileData
+ * @param {string|null} companyName
+ * @returns {Promise<{ data: object, handoff: boolean }>}
+ */
+async function attemptAnnuaireFallback(intlProfileData, companyName) {
+  const annuaireProvider = providers['annuaire-entreprises'];
+  if (!annuaireProvider || !companyName) {
     return {
-      data: { ...intlProfileData, _handoff: 'no_company_name' },
+      data: { ...intlProfileData, _handoff: companyName ? 'annuaire_unavailable' : 'no_company_name' },
       handoff: false,
     };
   }
 
   try {
-    // Search Pappers by company name to find the SIREN
-    const searchResult = await pappersProvider.search(companyName, { count: 1 });
+    const searchResult = await annuaireProvider.search(companyName, { count: 1 });
     const topResult = searchResult?.results?.[0];
 
     if (!topResult?.siren) {
       return {
-        data: { ...intlProfileData, _handoff: 'pappers_no_match' },
+        data: { ...intlProfileData, _handoff: 'annuaire_no_match' },
         handoff: false,
       };
     }
 
-    // Get full Pappers profile by SIREN
-    const isPreview = options.preview || false;
-    const pappersProfile = isPreview
-      ? await pappersProvider.getProfile(topResult.siren, { preview: true })
-      : await pappersProvider.getProfile(topResult.siren, { preview: false });
+    const annuaireProfile = await annuaireProvider.getProfile(topResult.siren, { preview: true });
+    const annuaireData = annuaireProfile?.data;
 
-    const pappersData = pappersProfile?.data;
-    const merged = mergeWithPappers(intlProfileData, pappersData);
+    if (!annuaireData) {
+      return {
+        data: { ...intlProfileData, _handoff: 'annuaire_no_data' },
+        handoff: false,
+      };
+    }
 
+    const merged = mergeWithPappers(intlProfileData, annuaireData);
+    merged.source = 'annuaire-entreprises+' + (intlProfileData.source || 'international');
+    merged._handoff = 'annuaire_fallback';
     return { data: merged, handoff: true };
   } catch {
     return {
-      data: { ...intlProfileData, _handoff: 'pappers_error' },
+      data: { ...intlProfileData, _handoff: 'annuaire_error' },
       handoff: false,
     };
   }
@@ -259,13 +310,28 @@ export function detectCountry(domainOrUrl) {
 
 /**
  * Get the best provider for a domain/country.
+ * For France: tries Pappers first, falls back to Annuaire Entreprises (free).
+ * For international: uses the INTL_FALLBACK_CHAIN.
  * @param {string} domainOrUrl
  * @returns {{ provider: object|null, providerName: string, country: string }}
  */
 export function resolveProvider(domainOrUrl) {
   const country = detectCountry(domainOrUrl);
-  const mapped = PROVIDER_MAP[country];
 
+  // France: try Pappers first, fallback to Annuaire Entreprises
+  if (country === 'FR') {
+    for (const name of FR_FALLBACK_CHAIN) {
+      const p = providers[name];
+      if (p && p.isAvailable()) {
+        return { provider: p, providerName: name, country };
+      }
+    }
+    // Last resort: annuaire-entreprises is always available, but be explicit
+    const fallback = providers['annuaire-entreprises'];
+    return { provider: fallback || null, providerName: 'annuaire-entreprises', country };
+  }
+
+  const mapped = PROVIDER_MAP[country];
   if (mapped && providers[mapped]) {
     return { provider: providers[mapped], providerName: mapped, country };
   }
@@ -291,33 +357,52 @@ export function resolveProvider(domainOrUrl) {
  * @param {object} options — { count, preview }
  */
 export async function searchCompany(query, domainOrUrl, options = {}) {
-  // ── SIREN/SIRET direct routing → Pappers immediately ──
+  // ── SIREN/SIRET direct routing → France (Pappers → Annuaire Entreprises fallback) ──
   if (isSirenOrSiret(query)) {
-    const pappersP = providers['pappers'];
-    const providerName = 'pappers';
     const country = 'FR';
 
-    if (!isPro()) {
+    // Try Pappers first (if Pro + key available)
+    const pappersP = providers['pappers'];
+    if (isPro() && pappersP && pappersP.isAvailable()) {
+      const results = await pappersP.search(query, options);
+      // Check for 401 or auth errors → fallback
+      if (results.error && /401|unauthorized|forbidden|key/i.test(results.error)) {
+        // Pappers 401 — fall through to Annuaire Entreprises
+      } else {
+        return { ...results, provider: 'pappers', country, _routing: 'siren_direct' };
+      }
+    }
+
+    // Fallback: Annuaire Entreprises (free, always available)
+    const annuaireP = providers['annuaire-entreprises'];
+    if (annuaireP) {
+      const results = await annuaireP.search(query, options);
       return {
-        results: [],
-        provider: providerName,
+        ...results,
+        provider: 'annuaire-entreprises',
         country,
-        error: `Business Data (${providerName}) requires an Intelwatch Pro license.`,
-        licenseRequired: true,
+        _routing: 'siren_direct_fallback',
+        _fallbackNote: 'Pappers non disponible, données issues de l\'Annuaire Entreprises (data.gouv.fr)',
       };
     }
 
-    if (!pappersP || !pappersP.isAvailable()) {
+    // Neither provider available
+    if (!isPro()) {
       return {
         results: [],
-        provider: providerName,
+        provider: 'pappers',
         country,
-        error: `${providerName} API key not configured.`,
+        error: `Business Data (pappers) requires an Intelwatch Pro license. Annuaire Entreprises fallback not registered.`,
+        licenseRequired: true,
       };
     }
 
-    const results = await pappersP.search(query, options);
-    return { ...results, provider: providerName, country, _routing: 'siren_direct' };
+    return {
+      results: [],
+      provider: 'pappers',
+      country,
+      error: `No France provider available. Pappers API key not configured and Annuaire Entreprises not registered.`,
+    };
   }
 
   const { provider, providerName, country } = resolveProvider(domainOrUrl);
@@ -363,45 +448,66 @@ export async function searchCompany(query, domainOrUrl, options = {}) {
  * @param {object} options — { preview }
  */
 export async function getCompanyProfile(identifier, domainOrUrl, options = {}) {
-  // ── SIREN/SIRET direct routing → Pappers immediately ──
+  // ── SIREN/SIRET direct routing → France (Pappers → Annuaire Entreprises fallback) ──
   if (isSirenOrSiret(identifier)) {
-    const pappersP = providers['pappers'];
-    const providerName = 'pappers';
     const country = 'FR';
     const tier = isPro() ? 'pro' : 'free';
     const isPreview = options.preview || !isPro();
 
-    if (!isPro()) {
+    // Try Pappers first (if Pro + key available)
+    const pappersP = providers['pappers'];
+    if (isPro() && pappersP && pappersP.isAvailable()) {
+      const profile = await pappersP.getProfile(identifier, { ...options, preview: isPreview });
+      // Check for 401 or auth errors → fallback
+      if (profile.error && /401|unauthorized|forbidden|key/i.test(profile.error)) {
+        // Pappers 401 — fall through to Annuaire Entreprises
+      } else {
+        return {
+          ...profile,
+          provider: 'pappers',
+          country,
+          tier,
+          isPreview,
+          _routing: 'siren_direct',
+        };
+      }
+    }
+
+    // Fallback: Annuaire Entreprises (free, no license required)
+    const annuaireP = providers['annuaire-entreprises'];
+    if (annuaireP) {
+      const profile = await annuaireP.getProfile(identifier, { ...options, preview: true });
       return {
-        data: null,
-        provider: providerName,
+        ...profile,
+        provider: 'annuaire-entreprises',
         country,
-        tier,
+        tier: 'free',
         isPreview: true,
-        error: `Business Data (${providerName}) requires an Intelwatch Pro license.`,
-        licenseRequired: true,
+        _routing: 'siren_direct_fallback',
+        _fallbackNote: profile.data?._fallbackNote || 'Pappers non disponible, profil issu de l\'Annuaire Entreprises (data.gouv.fr). Données financières limitées (CA, résultat net). UBO, BODACC et mandats croisés non disponibles.',
       };
     }
 
-    if (!pappersP || !pappersP.isAvailable()) {
+    // Neither provider available
+    if (!isPro()) {
       return {
         data: null,
-        provider: providerName,
+        provider: 'pappers',
         country,
         tier,
-        isPreview,
-        error: `${providerName} API key not configured.`,
+        isPreview: true,
+        error: `Business Data (pappers) requires an Intelwatch Pro license. Annuaire Entreprises fallback not registered.`,
+        licenseRequired: true,
       };
     }
 
-    const profile = await pappersP.getProfile(identifier, { ...options, preview: isPreview });
     return {
-      ...profile,
-      provider: providerName,
+      data: null,
+      provider: 'pappers',
       country,
       tier,
       isPreview,
-      _routing: 'siren_direct',
+      error: `No France provider available. Pappers API key not configured and Annuaire Entreprises not registered.`,
     };
   }