npm package: @inputdev/sdk
Description: Backend de formulaires sans code - SDK JavaScript
Author: InputDev
Latest version: 1.0.4

# InputDev SDK Documentation �

> **Le backend de formulaires le plus simple et professionnel pour les développeurs modernes.**

[![Version](https://img.shields.io/badge/version-1.0.0-059669.svg?style=flat-square)](https://inputdev.dev)
[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
[![Documentation](https://img.shields.io/badge/docs-latest-059669.svg?style=flat-square)](https://inputdev.pages.dev/documentation)

---

## 📖 Table des matières

- [Introduction](#-introduction)
- [Quick Start](#-quick-start-démarrage-rapide)
- [Comment ça fonctionne](#-comment-ça-fonctionne)
- [Installation](#-installation)
- [Utilisation JavaScript](#-utilisation-javascript-pour-frameworks)
- [SDK JavaScript Avancé](#-sdk-javascript-avancé)
- [Validation Email](#-validation-email)
- [Événements](#-événements)
- [Codes d'erreur](#-codes-derreur)
- [Sécurité](#-sécurité)
- [Mode Silence](#-mode-silence)
- [Limites](#-limites)
- [Bonnes pratiques](#-bonnes-pratiques)
- [Exemple complet](#-exemple-complet-réel)

---

## 🚀 Introduction

InputDev permet de transformer un simple formulaire en système de collecte de données sécurisé et professionnel.

### ✨ Avantages principaux

- **Aucune configuration serveur nécessaire** - Déployez en minutes
- **Aucune dépendance externe** - SDK ultra-léger et autonome  
- **Installation en moins de 1 minute** - Intégration instantanée
- **Validation automatique** - Emails et champs intégrés
- **Sécurité de niveau entreprise** - HTTPS, CORS, anti-spam
- **Filtrage intelligent des champs** - Ignore automatiquement les éléments non-pertinents
- **Retour visuel immédiat** - Boutons verts/rouges selon succès/erreur
- **Deux versions disponibles** - Minifiée (8.3KB) et complète (10.3KB)

---

## ⚡ Quick Start (Démarrage rapide)

### Étape 1 — Ajouter le script

#### Via CDN (recommandé)

```html
<script src="https://unpkg.com/@inputdev/sdk@latest/inputdev-sdk.prod.js"></script>
```

> ⚡ **Note importante** : Utilisez la version `.prod.js` qui est la seule version fonctionnelle actuellement

#### Via NPM

```bash
npm install @inputdev/sdk
import InputDev from "@inputdev/sdk";
```

### Étape 2 — Ajouter votre clé API

```html
<form data-inputdev="grts_VotreCleApiDeCeSite">
  <input type="text" name="name" required />
  <input type="email" name="email" required />
  <button type="submit">Envoyer</button>
</form>
```

> 🎉 **C'est terminé !** Le formulaire est maintenant connecté à InputDev.

---

## 🔧 Comment ça fonctionne

1. **Navigateur** - L'utilisateur soumet le formulaire
2. **InputDev API** - Les données sont validées et envoyées en HTTPS  
3. **Stockage sécurisé** - Elles sont enregistrées dans votre tableau de bord

---

## 📦 Installation

### Via CDN (recommandé pour production)

> **Deux versions disponibles :**
> - **Version minifiée (8.3KB)** : Pour production - chargement ultra-rapide
> - **Version complète (10.3KB)** : Pour développement - avec commentaires

#### Version Minifiée (Production)
```html
<script src="https://unpkg.com/@inputdev/sdk@latest/inputdev-sdk.min.js"></script>
```

#### Version Complète (Développement)
```html
<script src="https://unpkg.com/@inputdev/sdk@latest/inputdev-sdk.prod.js"></script>
```

#### CDN Alternative (JSDelivr)
```html
<script src="https://cdn.jsdelivr.net/npm/@inputdev/sdk@latest/inputdev-sdk.min.js"></script>
```

### Via NPM

```bash
npm install @inputdev/sdk
import InputDev from "@inputdev/sdk";
```

---

## 💻 Utilisation JavaScript (Pour Frameworks)

Idéal pour les frameworks JavaScript (React, Vue, Angular, etc.) où vous contrôlez déjà les données du formulaire :

```javascript
const sdk = new InputDev();

await sdk.submit("grts_VotreCleApiDeCeSite", {
  name: "John",
  email: "john@email.com", 
  plan: "premium"
});
```

### Paramètres

| Paramètre | Type | Obligatoire | Description |
|-----------|------|-------------|-------------|
| `apiKey` | string | Oui | Clé publique fournie par InputDev |
| `data` | object | Oui | Données à envoyer |

---

## 🚀 SDK JavaScript Avancé

Pour le HTML classique avec un contrôle total des champs et une gestion personnalisée :

```html
<form id="contact-form">
  <!-- ... vos champs ici ... -->
  <button type="button" onclick="submitFormulaire()">Envoyer</button>
</form>

<script src="https://unpkg.com/@inputdev/sdk@latest/inputdev-sdk.prod.js"></script>
<script>
  // Fonction réutilisable, contrôle total des champs
  function submitFormulaire() {
    const dev = new InputDevSDK();
    const data = {
      email: "exemple@test.com",
      message: "Message par défaut",
      telephone: "+22990000000",
      plan: "free"
    };
    dev.submit("grts_VotreCleApiDeCeSite", data); // SDK gère erreurs et succès automatiquement
  }
</script>
```

### Avantages du SDK avancé

- **Contrôle total des données** - Gérez chaque champ manuellement
- **Validation personnalisée** - Appliquez vos règles métier
- **Gestion d'erreurs avancée** - Messages d'erreur sur mesure
- **Performance optimisée** - Envoi asynchrone et optimisé

---

## 📧 Validation Email

InputDev valide automatiquement les adresses email pour garantir la qualité des données collectées. La validation fonctionne en deux temps : affichage des messages et blocage de la soumission si nécessaire.

### Comment ça fonctionne ?

Le SDK détecte automatiquement les champs email de deux manières :
1. **Type d'input** : Tous les `<input type="email">` sont validés
2. **Nom du champ** : Tous les champs dont le nom contient "email" (insensible à la casse)

> ⚠️ **Important** : Les **names** sont très importants ! Ils déterminent quels champs seront validés et comment les données seront stockées.

#### Messages dans la console (pour le débogage)

```
📧 VALIDATION EMAIL
⚠️ Erreurs trouvées:
• L'email "email" est invalide: test@invalid
💡 Corrigez les emails avant de soumettre à nouveau
```

#### Messages sous le formulaire (pour l'expérience utilisateur)

```html
<div class="inputdev-email-error-message" data-inputdev-error-for="email">
  <span style="text-decoration: underline; font-weight: bold;">InputDev SDK</span> : 
  <span style="font-weight: bold;">Veuillez entrer une adresse email valide</span>
</div>
```

### Processus de validation

1. **Détection** : Le SDK identifie les champs avec "email" dans le nom (insensible à la casse)
2. **Validation en temps réel** : Vérification lors de la perte de focus (blur event)  
3. **Feedback visuel** : Bordure rouge et message d'erreur sous le champ
4. **Blocage de soumission** : Empêche l'envoi si un email est invalide
5. **Nettoyage automatique** : Supprime l'erreur quand l'utilisateur corrige

### Exemple de validation

```html
<form data-inputdev="grts_VotreCleApiDeCeSite">
  <input type="text" name="name" placeholder="Nom" required>
  
  <!-- ✅ Sera validé (type="email") -->
  <input type="email" name="contact" placeholder="Contact" required>
  
  <!-- ✅ Aussi validé (type="email" + name contient "email") -->
  <input type="email" name="email" placeholder="Email" required>
  
  <!-- ✅ Validé (name contient "email") -->
  <input type="text" name="user_email" placeholder="Email utilisateur">
  
  <!-- ❌ Non validé (ni type="email", ni name avec "email") -->
  <input type="text" name="phone" placeholder="Téléphone">
  
  <button type="submit">Envoyer</button>
</form>
```

### Types de validation

#### ✅ Champs qui seront validés
- `<input type="email" name="quelconque">` (peu importe le name)
- `<input type="text" name="email">` (name contient "email")
- `<input type="text" name="user_email">` (name contient "email")
- `<input type="email" name="EMAIL_ADDRESS">` (les deux conditions)

#### ❌ Champs qui ne seront PAS validés
- `<input type="text" name="contact">` (ni type email, ni name avec "email")
- `<input type="tel" name="phone">` (ni type email, ni name avec "email")
- `<input type="text" name="message">` (ni type email, ni name avec "email")

### Types de validation

#### ✅ Emails valides
- user@domain.com
- test.email+tag@example.co.uk  
- user123@sub.domain.org

#### ❌ Emails invalides
- email@
- user.domain.com
- user@domain

### Importance des names (noms de champs)

Les **names** sont cruciaux pour le fonctionnement d'InputDev :

1. **Validation** : Les names déterminent quels champs sont validés automatiquement
2. **Stockage** : Les names deviennent les clés dans votre base de données
3. **Identification** : Les names permettent d'identifier chaque champ de manière unique

#### Bonnes pratiques pour les names
- ✅ Utilisez des names descriptifs : `name="email_utilisateur"` 
- ✅ Utilisez des names simples : `name="telephone"`
- ✅ Soyez cohérent : `name="email"` et `name="confirmation_email"`
- ❌ Évitez les names vides ou manquants
- ❌ Évitez les caractères spéciaux : `name="email-utilisateur"` (préférer `_`)

### Styles appliqués automatiquement

```css
.inputdev-email-error {
    border: 2px solid #ef4444 !important;
    box-shadow: 0 0 0 3px rgba(239, 68, 68, 0.1) !important;
    outline: none !important;
}

.inputdev-email-error-message {
    color: #ef4444;
    font-size: 12px;
    margin-top: 4px;
    display: block;
}
```

> ⚠️ **Important** : Si un email est invalide, la soumission du formulaire est complètement bloquée. L'utilisateur doit corriger l'email avant de pouvoir envoyer le formulaire.

> 💡 **Astuce** : La validation fonctionne en mode normal et en mode silence. En mode silence, seul le message sous le formulaire s'affiche (pas de logs console).

---

## 📡 Événements

Vous pouvez écouter les événements globaux pour personnaliser l'expérience utilisateur :

```javascript
document.addEventListener("inputdev:success", (event) => {
  console.log("Succès :", event.detail);
  // Rediriger, afficher un message, etc.
});

document.addEventListener("inputdev:error", (event) => {
  console.error("Erreur :", event.detail);
  // Afficher une notification, logger l'erreur, etc.
});
```

---

## 🔄 Comportement de Soumission (Important)

### ⚠️ **Le SDK bloque temporairement le rechargement de la page**

Le SDK InputDev utilise un comportement moderne de type SPA (Single Page Application) pour garantir une meilleure expérience utilisateur :

#### 📋 **Ce qui se passe lors de la soumission**

1. **`e.preventDefault()`** : Le rechargement automatique de la page est bloqué
2. **Bouton désactivé** : Le bouton submit est désactivé pendant 3 secondes pour éviter les double-soumissions
3. **Texte changé** : Le bouton affiche "Envoi en cours..." pendant le traitement
4. **Requête asynchrone** : L'envoi se fait en AJAX sans rechargement
5. **Gestion des résultats** : Succès ou erreur sont gérés via les événements

#### ✅ **Avantages de ce comportement**

- 🔄 **Évite les soumissions multiples** - Protection contre les doubles clics
- 📱 **Meilleure UX** - Pas de rechargement brutal de la page
- 🔧 **Gestion d'erreur améliorée** - Messages d'erreur sans perdre le formulaire
- 📊 **Feedback visuel** - Indicateur de chargement clair
- 🎯 **Compatible SPA** - Fonctionne parfaitement avec React, Vue, Angular

> 💡 **Note** : Ce comportement est **intentionnel** et **professionnel**. Il garantit que vos utilisateurs ne perdent jamais leurs données et offre une expérience moderne et fluide.

---

## � Codes d'erreur

| Code | Signification | Solution |
|------|---------------|----------|
| `API_001` | Clé API invalide | Vérifiez votre clé |
| `DOM_001` | Domaine non autorisé | Ajoutez le domaine autorisé |
| `QUO_001` | Quota dépassé | Passez à un plan supérieur |
| `NET_001` | Erreur réseau | Vérifiez la connexion |
| `VAL_001` | Validation échouée | Vérifiez les champs |

---

## 🔐 Sécurité

- **Requêtes envoyées en HTTPS** - Chiffrement de bout en bout
- **Validation côté client et serveur** - Double couche de sécurité
- **Domaine autorisé configurable** - Protection contre l'usage non autorisé
- **Anti-spam intégré** - Protection automatique

> ℹ️ **Sécurité** : La clé API est publique et conçue pour rester dans le frontend. Elle est sécurisée par validation de domaine et quotas automatiques.

---

## � Mode Silence

Pour désactiver les logs en production :

```html
<form data-inputdev-silence="grts_VotreCleApiDeCeSite">
```

---

## 📊 Limites

- **Nombre de soumissions par mois** - Dépend du plan choisi
- **Nombre maximum de formulaires** - Variable selon le plan  
- **Nombre de sites/clés actives** - Une clé, un site
- **SSL obligatoire** - HTTPS requis pour la sécurité
- **Domaines autorisés** - Configurable par clé

---

## ⭐ Bonnes pratiques

- ✅ Toujours utiliser HTTPS
- ✅ Toujours définir des champs name
- ✅ Toujours gérer les événements erreur
- ✅ Surveiller votre quota
- ✅ Tester en environnement de développement

---

## 📋 Exemple complet réel

```html
<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/@inputdev/sdk@latest/inputdev-sdk.prod.js"></script>
</head>
<body>

<form data-inputdev="grts_VotreCleApiDeCeSite">
  <div class="form-group">
    <label for="name">Nom complet</label>
    <input type="text" id="name" name="name" required>
  </div>
  
  <div class="form-group">
    <label for="email">Email</label>
    <input type="email" id="email" name="email" required>
  </div>
  
  <div class="form-group">
    <label for="message">Message</label>
    <textarea id="message" name="message" required></textarea>
  </div>
  
  <button type="submit">Envoyer</button>
</form>

<script>
  // Écouter les événements pour une meilleure UX
  document.addEventListener('inputdev:success', (event) => {
    alert('Message envoyé avec succès !');
    // Réinitialiser le formulaire
    document.querySelector('form').reset();
  });
  
  document.addEventListener('inputdev:error', (event) => {
    console.error('Erreur lors de l\'envoi :', event.detail);
    alert('Une erreur est survenue. Veuillez réessayer.');
  });
</script>

</body>
</html>
```

---

## � Support & Liens

- 📖 **Documentation Complète** : [docs.inputdev.dev](https://inputdev.pages.dev/documentation)
- 💬 **Discord** : [Rejoindre la communauté]
- 🐛 **Issues** : [Signaler un bug]


---

## 📄 Licence

MIT License - voir le fichier [LICENSE](LICENSE) pour plus de détails.

---

<p align="center">Made with ❤️ by <b>InputDev Team</b></p>