feat: AI Assistant Integration - Allow AI agents to interact with LeadMiner via REST API

[baderdean]

Contexte / Context

LeadMiner doit être accessible aux assistants IA (ChatGPT, Claude, Gemini, etc.) via une interface REST API elegante. L'utilisateur doit pouvoir dire a un assistant IA :

"Salut Miner, envoie un email a mes contacts les plus actifs pour leur annoncer que j'ai lance un projet"

Et l'IA doit etre capable d'executer cette demande en utilisant les APIs de LeadMiner.

Objectif / Goal

Permettre aux assistants IA d'interagir avec LeadMiner pour :

• Extraire des contacts (mining)
• Rechercher des contacts (avec filtres)
• Enrichir des contacts
• Envoyer des campagnes email/SMS
• Consulter les resultats (stats ouverts, clicks, bounces)

Solution / Solution

Authentification

• Utiliser le Supabase Personal Access Token (PAT) par utilisateur
• L'utilisateur genere son PAT dans le dashboard Supabase
• L'IA utilise le header : Authorization: Bearer <pat>

APIs a exposer (3 sources)

Source	Endpoints	Usage
PostgREST	/rest/v1/contacts, /rest/v1/campaigns	Listes, lectures, stats, recherche avec filtres
Edge Functions	/functions/v1/email-campaigns, /functions/v1/fetch-mining-source	Creation campagne, mining
Express	/api/enrich/person, /api/enrich/person/bulk	Enrichissement contacts

Actions possibles

Action	API recommandee	Exemple filtre
Rechercher contacts	PostgREST /rest/v1/contacts	?occurrence=gte.10&order=occurrence.desc
Extraire contacts	Edge Function /functions/v1/fetch-mining-source	-
Enrichir un contact	Express POST /api/enrich/person	-
Enrichir en masse	Express POST /api/enrich/person/bulk	-
Lister campagnes	PostgREST /rest/v1/campaigns	-
Stats campagne	PostgREST /rest/v1/campaigns + relations	-
Creer campagne	Edge Function /functions/v1/email-campaigns	-
Envoyer SMS	Edge Function SMS	-

Recherche en langage naturel

L'IA construit elle-meme les filtres PostgREST :

• "contacts les plus actifs" -> ?order=occurrence.desc&limit=100
• "contacts derniers 30 jours" -> ?recency=gte.30&order=recency.asc
• "contacts a Paris" -> ?location=ilike.*Paris*
• "contacts chez Google" -> ?works_for=ilike.*Google*

Livrables / Deliverables

1. Documentation docs/api/ai-assistant-guide.md

   • Comment obtenir un PAT Supabase
   • Les 3 APIs avec endpoints
   • Exemples de requetes pour chaque action
   • Guide des filtres PostgREST pour la recherche

2. Optionnel - Schema OpenAPI pour GPTs Actions

Tests a ecrire / Tests to write

Tests avec Assistants IA

1. Test ChatGPT - Creer un GPT et tester les actions via Actions
2. Test Claude - Appeler les endpoints via API Claude
3. Test curl - Verifier que les PAT fonctionnent

Tests de validation

• Verifier que chaque endpoint est accessible avec un PAT
• Verifier que les filtres PostgREST fonctionnent
• Verifier que l'IA comprend les exemples de la doc

Tests OpenCode

• Ecrire un test qui utilise l'agent opencode pour executer un scenario via l'API

Approche 1 vs Approche 2

Approche 1: OpenAI GPTs Actions

• Schema OpenAPI pour GPTs avec OAuth
• Fonctionne uniquement avec ChatGPT

Approche 2: Documentation REST universelle (Recommandee)

• Documenter les endpoints existants
• L'IA construit elle-meme les requetes
• Fonctionne avec n'importe quel assistant IA

---

Priority: Medium
Labels: enhancement, ai-assistant, api