@reqvet-sdk/sdk 2.2.3 → 2.2.4

package/README.md

@@ -186,43 +186,107 @@ Voir [SDK_REFERENCE.md §6](./SDK_REFERENCE.md#6-webhook-events) pour la structu
 
 ## Intégration revendeur (multi-tenant)
 
-Si vous êtes un éditeur logiciel intégrant ReqVet pour vos clients (cliniques), utilisez une clé API revendeur pour provisionner et gérer les organisations de manière programmatique.
+Si vous êtes un éditeur logiciel intégrant ReqVet pour vos clients (cliniques), vous disposez de **deux types de clés** :
+
+| Clé | Variable | Usage |
+|-----|----------|-------|
+| Clé revendeur | `REQVET_RESELLER_KEY` | Provisionner et administrer les cliniques — **jamais** pour générer des jobs |
+| Clé clinique | stockée dans votre DB | Faire les appels de génération pour cette clinique spécifique |
+
+### 1 — Onboarding : provisionner une clinique
+
+Appelez `createOrganization` à chaque fois qu'une nouvelle clinique souscrit à votre service. Utilisez votre identifiant interne comme `externalId` — c'est le pont entre vos deux systèmes.
 
 ```ts
 import ReqVet from '@reqvet-sdk/sdk';
 
-// Instancier avec la clé revendeur (role='reseller')
 const reseller = new ReqVet(process.env.REQVET_RESELLER_KEY!);
 
-// Provisionner une clinique à l'onboarding
 const result = await reseller.createOrganization({
   name: 'Clinique du Parc',
   contactEmail: 'contact@clinique-du-parc.fr',
-  externalId: 'votre_id_interne_4892', // votre ID — garantit l'idempotence
+  externalId: String(clinic.id),  // votre ID interne → idempotence garantie
   monthlyQuota: 500,
   webhookUrl: 'https://votre-app.com/webhooks/reqvet',
 });
 
-// ⚠️ Stocker immédiatement ces valeurs — elles ne sont retournées qu'une seule fois
-await db.saveClinicCredentials({
-  clinicId: result.organization.id,
-  apiKey: result.api_key,           // rqv_live_...
-  webhookSecret: result.webhook_secret, // whsec_...
-});
+if (result.api_key) {
+  // Première création — stocker immédiatement, chiffré au repos
+  // api_key et webhook_secret ne sont retournés qu'une seule fois
+  await db.clinics.update(clinic.id, {
+    reqvet_org_id:    result.organization.id,
+    reqvet_api_key:   encrypt(result.api_key),      // rqv_live_...
+    reqvet_wh_secret: encrypt(result.webhook_secret), // whsec_...
+  });
+}
+// Si !result.api_key → clinique déjà provisionnée (idempotent), clé déjà en base
+```
 
-// La clinique utilise ensuite son propre client ReqVet avec sa clé
-const clinic = new ReqVet(result.api_key);
-const { system } = await clinic.listTemplates();
-const job = await clinic.createJob({ audioFile, animalName, templateId: system[0].id });
+### 2 — Runtime : appeler ReqVet pour le bon utilisateur
 
+À chaque consultation, récupérez la clé de **la clinique de l'utilisateur connecté** et faites l'appel côté serveur. La clé ne sort jamais du backend.
+
+```ts
+// Handler server-side — appelé quand un vétérinaire lance une transcription
+async function transcribe(userId: string, audioBuffer: Buffer) {
+  // Identifier la clinique de l'utilisateur dans VOTRE système
+  const clinic = await db.getClinicByUser(userId);
+
+  // Déchiffrer la clé de cette clinique — côté serveur uniquement
+  const reqvet = new ReqVet(decrypt(clinic.reqvet_api_key));
+
+  // Upload direct Supabase (pas de limite de taille)
+  const { uploadUrl, path } = await reqvet.getSignedUploadUrl('consultation.webm', 'audio/webm');
+  await fetch(uploadUrl, { method: 'PUT', body: audioBuffer });
+
+  // Injecter clinicId dans metadata → permet de router les webhooks entrants
+  return reqvet.createJob({
+    audioFile: path,
+    animalName: consultation.animalName,
+    templateId: clinic.reqvet_template_id,
+    callbackUrl: 'https://votre-app.com/webhooks/reqvet',
+    metadata: { clinicId: clinic.id, userId },
+  });
+}
+```
+
+### 3 — Webhooks entrants : router vers la bonne clinique
+
+Vos webhooks arrivent sur un seul endpoint. Utilisez `metadata.clinicId` (injecté au `createJob`) pour identifier la clinique et vérifier la signature avec son propre secret.
+
+```ts
+export async function POST(req: NextRequest) {
+  const rawBody = await req.text();
+  const event = JSON.parse(rawBody);
+
+  const clinic = await db.getClinic(event.metadata?.clinicId);
+
+  const { ok } = verifyWebhookSignature({
+    secret: decrypt(clinic.reqvet_wh_secret), // secret de CETTE clinique
+    rawBody,
+    signature: req.headers.get('x-reqvet-signature') ?? '',
+    timestamp: req.headers.get('x-reqvet-timestamp') ?? '',
+  });
+
+  if (!ok) return new Response('Unauthorized', { status: 401 });
+
+  if (event.event === 'job.completed') {
+    await db.saveReport(clinic.id, event.job_id, event.html, event.fields);
+  }
+}
+```
+
+### 4 — Administration : quotas, suspension, monitoring
+
+```ts
 // Lister toutes les cliniques avec leur usage du mois
 const { organizations } = await reseller.listOrganizations();
 // [{ id, name, is_active, monthly_quota, usage: { jobs_this_month, quota_remaining } }]
 
-// Modifier le quota d'une clinique
+// Modifier le quota (ex. changement de plan)
 await reseller.updateOrganization(orgId, { monthlyQuota: 1000 });
 
-// Suspendre une clinique (révoque aussi ses clés API)
+// Suspendre une clinique — révoque ses clés API en cascade
 await reseller.updateOrganization(orgId, { isActive: false });
 
 // Réactiver
@@ -232,7 +296,7 @@ await reseller.updateOrganization(orgId, { isActive: true });
 await reseller.deactivateOrganization(orgId);
 ```
 
-> **Idempotence** : si `createOrganization` est appelé plusieurs fois avec le même `externalId`, l'organisation existante est retournée sans créer de doublon. Utile pour rendre votre processus d'onboarding sûr en cas de retry.
+> Voir [SDK_REFERENCE.md §9](./SDK_REFERENCE.md#pattern--gestion-des-clés-par-clinique) pour le schéma DB complet, les règles impératives et les cas limites (rotation de clé, etc.).
 
 ## TypeScript
 

package/SDK_REFERENCE.md

@@ -578,6 +578,123 @@ Ces méthodes sont réservées aux revendeurs (éditeurs logiciels) qui provisio
 
 ---
 
+### Pattern : gestion des clés par clinique
+
+Chaque clinique provisionnée reçoit sa propre clé API `rqv_live_...`. Avec 100 cliniques, il faut un mécanisme pour associer la bonne clé au bon utilisateur authentifié au moment de l'appel.
+
+**Le principe** : vous stockez les clés dans votre propre base de données, liées à vos enregistrements cliniques. Vos appels vers ReqVet se font **server-side** — la clé ne passe jamais dans le navigateur.
+
+#### Schéma recommandé (côté revendeur)
+
+```sql
+-- Dans votre base de données
+ALTER TABLE clinics ADD COLUMN reqvet_org_id     TEXT;         -- UUID ReqVet
+ALTER TABLE clinics ADD COLUMN reqvet_api_key    TEXT;         -- rqv_live_... chiffré
+ALTER TABLE clinics ADD COLUMN reqvet_wh_secret  TEXT;         -- whsec_... chiffré
+```
+
+> Chiffrez `reqvet_api_key` et `reqvet_wh_secret` au repos (AES-256 ou équivalent). Ces valeurs sont des secrets d'accès — traitez-les comme des mots de passe.
+
+#### Flux d'onboarding d'une clinique
+
+```ts
+// Appelé quand vous créez une nouvelle clinique dans votre système
+async function onboardClinic(clinicId: string, clinicData: ClinicInput) {
+  const reseller = new ReqVet(process.env.REQVET_RESELLER_KEY!);
+
+  // externalId = votre ID interne → garantit l'idempotence en cas de retry
+  const result = await reseller.createOrganization({
+    name: clinicData.name,
+    contactEmail: clinicData.email,
+    externalId: clinicId,       // ← votre identifiant interne comme pont
+    monthlyQuota: 200,
+    webhookUrl: `https://votre-app.com/webhooks/reqvet`,
+  });
+
+  if (result.api_key) {
+    // Première création : stocker la clé chiffrée
+    await db.clinics.update(clinicId, {
+      reqvet_org_id:    result.organization.id,
+      reqvet_api_key:   encrypt(result.api_key),
+      reqvet_wh_secret: encrypt(result.webhook_secret),
+    });
+  }
+  // Si !result.api_key → organisation déjà existante (idempotent), clé déjà en base
+}
+```
+
+#### Flux d'appel au moment de la consultation
+
+```ts
+// Appelé quand un vétérinaire authentifié lance une transcription
+async function transcribe(userId: string, audioBuffer: Buffer) {
+  // 1. Identifier la clinique de l'utilisateur dans VOTRE système
+  const clinic = await db.getClinicByUser(userId);
+
+  // 2. Récupérer et déchiffrer la clé ReqVet — côté serveur uniquement
+  const reqvetKey = decrypt(clinic.reqvet_api_key);
+
+  // 3. Instancier le client avec la clé de CETTE clinique
+  const reqvet = new ReqVet(reqvetKey);
+
+  // 4. Appel ReqVet — la clé ne sort jamais du serveur
+  const { uploadUrl, path } = await reqvet.getSignedUploadUrl('consultation.webm', 'audio/webm');
+  await fetch(uploadUrl, { method: 'PUT', body: audioBuffer });
+
+  const job = await reqvet.createJob({
+    audioFile: path,
+    animalName: consultation.animalName,
+    templateId: clinic.reqvet_template_id,
+    callbackUrl: `https://votre-app.com/webhooks/reqvet`,
+    metadata: { clinicId: clinic.id, userId },
+  });
+
+  return job;
+}
+```
+
+#### Réception du webhook
+
+Le webhook ReqVet arrive sur votre endpoint. Pour l'associer à la bonne clinique, utilisez le `metadata.clinicId` que vous avez injecté lors du `createJob` :
+
+```ts
+export async function POST(req: NextRequest) {
+  const rawBody = await req.text();
+  const event = JSON.parse(rawBody);
+
+  // Retrouver la clinique via les metadata passthrough
+  const clinicId = event.metadata?.clinicId;
+  const clinic = await db.getClinic(clinicId);
+
+  // Vérifier la signature avec le secret de CETTE clinique
+  const { ok } = verifyWebhookSignature({
+    secret: decrypt(clinic.reqvet_wh_secret),
+    rawBody,
+    signature: req.headers.get('x-reqvet-signature') ?? '',
+    timestamp: req.headers.get('x-reqvet-timestamp') ?? '',
+  });
+
+  if (!ok) return new Response('Unauthorized', { status: 401 });
+
+  // Traiter l'événement
+  if (event.event === 'job.completed') {
+    await db.saveReport(clinicId, event.job_id, event.html, event.fields);
+  }
+}
+```
+
+#### Règles impératives
+
+| Règle | Détail |
+|-------|--------|
+| **Server-side uniquement** | La clé clinique ne doit jamais être envoyée au navigateur, ni apparaître dans les réponses API de votre frontend |
+| **Chiffrement au repos** | `reqvet_api_key` et `reqvet_wh_secret` chiffrés en base — pas en clair |
+| **`externalId` = votre ID** | Utilisez systématiquement votre identifiant interne comme `externalId` — c'est le pont entre vos deux systèmes et le garde-fou anti-doublon |
+| **Une clé par clinique** | Ne réutilisez jamais la clé d'une clinique pour une autre — l'isolation des données ReqVet est par `org_id` |
+| **Rotation** | Si une clé est compromise, désactivez la clinique (`isActive: false`), puis réactivez — les nouvelles clés devront être provisionnées manuellement via `createOrganization` |
+
+---
+
 ### `listOrganizations()`
 
 Lister toutes les organisations (cliniques) provisionnées par le revendeur, enrichies de l'usage du mois courant.
@@ -804,7 +921,11 @@ await reseller.deactivateOrganization(orgId);
 **Intégration revendeur (multi-tenant)**
 
 - [ ] Clé revendeur (`REQVET_RESELLER_KEY`) distincte et stockée séparément des clés cliniques
-- [ ] `externalId` systématiquement fourni à `createOrganization` pour garantir l'idempotence des onboardings
-- [ ] `api_key` et `webhook_secret` retournés par `createOrganization` stockés immédiatement et de façon sécurisée — ils ne sont affichés qu'une seule fois
+- [ ] `externalId` systématiquement fourni à `createOrganization` — valeur = votre ID interne de clinique
+- [ ] `api_key` et `webhook_secret` retournés par `createOrganization` stockés immédiatement, **chiffrés au repos** — ils ne sont affichés qu'une seule fois
+- [ ] Clés cliniques appelées **server-side uniquement** — jamais exposées au navigateur ni aux réponses frontend
+- [ ] Un client `ReqVet` instancié avec la clé de **la clinique concernée** à chaque appel — jamais avec la clé revendeur pour les jobs
+- [ ] `metadata` enrichi de `clinicId` (et `userId` si pertinent) sur chaque `createJob` — permet de router les webhooks entrants vers la bonne clinique
+- [ ] Signature webhook vérifiée avec le secret de **la clinique destinataire** (et non le secret revendeur)
 - [ ] Suspension de clinique gérée via `updateOrganization(orgId, { isActive: false })` (et non `deactivateOrganization` qui est irréversible)
 - [ ] Usage mensuel (`usage.jobs_this_month`, `usage.quota_remaining`) consulté via `listOrganizations()` ou `getOrganization()` pour le monitoring et la facturation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqvet-sdk/sdk",
-  "version": "2.2.3",
+  "version": "2.2.4",
   "description": "Official JavaScript SDK for the ReqVet veterinary report generation API.",
   "type": "module",
   "main": "./src/index.js",