Starter d'intégration

Ne partez pas d'une page blanche. Le starter d'intégration ShopiMind est un squelette Node.js minimal et sécurisé qui câble déjà tout le socle d'une intégration :

• réception et vérification HMAC de tous les webhooks de cycle de vie ;
• le flux OAuth Type B de bout en bout ;
• un store local (SQLite) qui suit les installations et les clés API par boutique ;
• un adaptateur vers le SDK ShopiMind pour rappeler l'API ;
• une plomberie optionnelle de synchronisation planifiée (scheduler quotidien, provisioning idempotent, chiffrement des identifiants au repos).

Philosophie : remplacez la logique de démo par votre vrai produit, mais gardez les primitives de sécurité intactes (vérification HMAC, contrat de réponse, gestion de la clé).

Récupérer le starter

Dépôt GitHub

Le starter sera publié sur GitHub. Lien à venir — il sera ajouté ici.

Démarrer

cp .env.example .env
# Renseignez WEBHOOK_SECRET (communiqué par ShopiMind)
yarn install
yarn start    # ou: yarn dev (rechargement à chaud)

Le serveur démarre sur http://localhost:8082. Routes exposées :

Méthode	Chemin	Rôle
GET	/health	Sonde de disponibilité
POST	/webhook/receive	Tous les événements de cycle de vie
POST	/webhook/test-connection	Test de connexion depuis l'UI ShopiMind
POST	/webhook/remote-data/{resource}	Options dynamiques d'un select
GET	/oauth/authorize	Étape 2 d'OAuth Type B (consentement)
POST	/oauth/consent	Étape 4 d'OAuth Type B (redirection)

Variables d'environnement

Variable	Rôle	Défaut
WEBHOOK_SECRET	Secret HMAC (communiqué par ShopiMind)	— (requis)
SHOPIMIND_API_URL	Base de l'API ShopiMind, sans /v1	http://localhost:5500
PORT	Port HTTP	8082
SIGNATURE_TOLERANCE_SECONDS	Fenêtre anti-rejeu	300
DATABASE_PATH	Fichier SQLite	./data/shopimind.sqlite
CREDENTIALS_KEY	Clé AES-256-GCM (chiffrement des identifiants au repos) — optionnel	—

Structure

src/
├── server.js          ← bootstrap du serveur
├── config.js          ← chargement de l'env
├── db.js              ← store SQLite (installs + journal des webhooks)
├── lib/
│   ├── signature.js   ← vérification HMAC
│   ├── shopimind.js   ← adaptateur SDK (le seul fichier qui touche le SDK)
│   ├── provisioning.js← ensureDataSource / …Definition / …Event (idempotent)
│   ├── crypto.js      ← chiffrement des identifiants au repos (optionnel)
│   ├── scheduler.js   ← job quotidien sans dépendance (optionnel)
│   └── sync-engine.js ← historique de run + curseurs (sync planifiée, optionnel)
└── routes/
    ├── health.js
    ├── lifecycle.js   ← tous les webhooks + test-connection + remote-data
    ├── oauth.js       ← OAuth Type B
    └── widgets.js     ← référence du contrat widget (n'expose aucune route)

Personnaliser

• Logique métier des webhooks → src/routes/lifecycle.js (handlers install, activate, …).
• UI de consentement OAuth → remplacez le formulaire de démo de src/routes/oauth.js.
• Nouvel appel API → un helper d'une ligne dans src/lib/shopimind.js, ou la classe SDK directement (require('@shopimind/sdk-shopimind')).
• Synchronisation planifiée → composez scheduler + sync-engine + provisioning.

Pour aller plus loin

• Cycle de vie & webhooks — le contrat entrant en détail.
• Configuration — déclarer votre schéma de config.
• Appeler l'API ShopiMind — pousser vos données.
• SDK JavaScript — la référence du SDK utilisé par le starter.