dev-trace

Que fait dev-trace ?

Transforme une adresse email en un profil public structuré en exécutant une cascade fixe de sources publiques, chaque niveau étant activé par la présence de sa clé API. Données publiques uniquement — en dessous du seuil de confiance, elle retourne des candidats plutôt que de deviner. Zéro dépendance (Node 18+) ; apportez vos propres clés API.

Comment exécuter

node scripts/dev-trace.mjs <email> [--pretty] [--json <path>] [--max-depth N] [--deep] [--tier low|medium|high] [--no-bio] [--bio-mode fast|balanced|deep|max]

• --pretty — JSON lisible (utilisez ceci pour afficher à l'utilisateur).
• --json <path> — écrit l'objet brut dans un fichier au lieu de stdout.
• --max-depth N — arrête après la profondeur N (0–4) pour les couches rapides. Défaut 4.
• --deep — exécute également la profondeur 5 (SixtyFour). Lent (minutes) et coûteux ; nécessite SIXTYFOUR_API_KEY.
• --tier low|medium|high — profondeur de recherche SixtyFour (défaut low). Plus élevé = plus approfondi, plus lent, plus de crédits.
• --no-bio — ignore l'étape de biographie /research de Tabstack (activée par défaut lorsqu'un nom est résolu et que TABSTACK_API_KEY est définie).
• --bio-mode fast|balanced|deep|max — profondeur de recherche pour la biographie (défaut fast).

La cascade

Profondeur	Couche	Source	Clé	S'exécute
0	valider	syntaxe + MX + jetable	aucune	toujours, gratuit
1	surface	Gravatar + récupération de domaine	aucune	toujours, gratuit
1	vérifier	Vérification d'email Hunter	HUNTER_API_KEY	si clé
2	profil	Identité GitHub + bases ICP	GITHUB_TOKEN (recommandé)	toujours, gratuit
3	enrichi	Tabstack web/entreprise	TABSTACK_API_KEY	si clé
4	profond	Enrichissement de personne Hunter	HUNTER_API_KEY	si clé
5	très profond	Intelligence de personne SixtyFour (recherche LinkedIn)	SIXTYFOUR_API_KEY	uniquement avec --deep

HUNTER_API_KEY déverrouille à la fois la vérification (profondeur 1, 0,5 crédit/appel) et l'enrichissement de personne (profondeur 4, 0,2 crédit/appel) — notez que la vérification coûte plus que l'enrichissement. La profondeur 5 (SixtyFour) est l'exploration approfondie optionnelle : elle s'exécute uniquement avec --deep, prend des minutes (recherche web asynchrone) et s'ancre sur l'email lui-même ainsi que sur tout nom/entreprise/LinkedIn trouvé en amont. Elle ignore uniquement les emails jetables ou non délivrables (journalisés dans meta).

Clés

Copiez .env.example dans .env dans ce répertoire de compétence et ajoutez les clés que vous possédez (le moteur lit .env depuis la racine de la compétence ou scripts/). Toutes sont optionnelles ; les couches de validation, surface et GitHub s'exécutent sans aucune. Une couche dont la clé est absente est silencieusement ignorée. Les clés ne sont jamais incluses dans la compétence (.env est dans .gitignore).

Politique de coût et d'utilisation (pour l'agent)

La compétence est conçue pour que vous obteniez un profil utile gratuitement, et chaque fournisseur payant est optionnel — dépensez uniquement lorsqu'un prospect en vaut la peine.

Niveaux de coût, du moins cher au plus cher :

• 🟢 Gratuit, sans compte — validation, surface (Gravatar + domaine), identité GitHub. Exécutez sans aucune clé.
• 🟢 Clé gratuite, optionnelle — GITHUB_TOKEN (gratuit à générer) améliore simplement la limite de débit et la fiabilité de GitHub.
• 🟢 Compte gratuit, va loin — Tabstack (TABSTACK_API_KEY) : enrichissement d'entreprise (profondeur 3) + la biographie /research sourcée. Un compte Tabstack gratuit couvre beaucoup avant de payer.
• 🟡 Crédits mesurés, niveau gratuit puis payant — Hunter (HUNTER_API_KEY) : vérification d'email (0,5 crédit) + enrichissement de personne (0,2 crédit).
• 🔴 Premium, vraiment $$$ — SixtyFour (SIXTYFOUR_API_KEY, --deep) : recherche approfondie de personne + LinkedIn. La couche de rupture pour les cibles de grande valeur.

Détail par couche :

Couche	Coût	S'exécute
1 vérifier (Hunter)	0,5 crédit Hunter	si HUNTER_API_KEY présente
3 Tabstack entreprise	Crédits Tabstack	si TABSTACK_API_KEY présente
4 Hunter personne	0,2 crédit Hunter	si HUNTER_API_KEY présente
biographie (Tabstack /research)	Crédits Tabstack (fast le moins cher)	si un nom a été résolu
5 SixtyFour	coûteux — voir ci-dessous	uniquement avec --deep

Politique : par défaut, utilisez les couches gratuites et peu coûteuses. Pour une recherche rapide gratuite, --max-depth 2 exécute uniquement les couches sans coût.

SixtyFour (--deep) est coûteuse et limitée en débit. Le coût exact dépend de votre plan SixtyFour ; sur le plan d'entrée (~100 crédits/mois, 0,24 $/crédit), un tirage de medium d'intelligence de personne mesurait ~20 crédits (~4,80 $, ~2,5 min), soit environ 5 tirages/mois. Traitez chaque exécution --deep comme une ressource rare :

• N'exécutez jamais --deep pour « être complet ». Uniquement sur une cible vraiment de grande valeur.
• Uniquement après que les couches moins chères (enrichissement de personne Hunter, biographie /research) aient échoué.
• Confirmez avec l'utilisateur avant de dépenser un tirage SixtyFour, et utilisez par défaut --tier low — n'augmentez jamais le niveau sans y être invité.
• Imposé, pas seulement conseillé : --deep refuse de s'exécuter à moins qu'un humain n'ait accepté le coût, via DEV_TRACE_ALLOW_DEEP=1 dans l'environnement ou une confirmation interactive. Il ne peut pas se déclencher de manière autonome. DEV_TRACE_MAX_DEPTH=N plafonne la profondeur pour une utilisation sans tête. Voir le README