@reqvet-sdk/sdk 2.2.2 → 2.2.4

package/README.md

@@ -16,6 +16,7 @@ SDK JavaScript/TypeScript officiel pour l'API [ReqVet](https://reqvet.com) — g
 - **Reformuler** pour une audience spécifique — propriétaire, référé, spécialiste (`reformulateReport`)
 - **Gérer les templates** (`listTemplates`, `createTemplate`, `updateTemplate`, `deleteTemplate`)
 - **Vérifier les webhooks** avec HMAC (`@reqvet-sdk/sdk/webhooks`)
+- **Provisionner et gérer des cliniques** en mode revendeur multi-tenant (`createOrganization`, `listOrganizations`, `updateOrganization`, `deactivateOrganization`)
 
 > **Note** : ce SDK n'inclut pas d'enregistreur audio. Votre application gère l'enregistrement et passe un `File`, `Blob` ou `Buffer` au SDK.
 
@@ -141,6 +142,8 @@ export async function POST(req: NextRequest) {
 
 ## API
 
+### Génération de comptes rendus
+
 | Méthode | Description |
 |---------|-------------|
 | `getSignedUploadUrl(fileName, contentType)` | URL signée Supabase pour upload direct (recommandé serveur) |
@@ -161,6 +164,18 @@ export async function POST(req: NextRequest) {
 | `deleteTemplate(templateId)` | Supprimer un template |
 | `health()` | Vérification de l'état de l'API |
 
+### API Partenaire / Revendeur
+
+> Ces méthodes nécessitent une clé API revendeur (`rqv_live_...` avec `role='reseller'`), distincte de la clé d'une clinique standard. Contactez votre responsable de compte ReqVet pour obtenir une clé revendeur.
+
+| Méthode | Description |
+|---------|-------------|
+| `listOrganizations()` | Lister toutes les cliniques provisionnées par le revendeur |
+| `createOrganization(params)` | Provisionner une nouvelle clinique (génère sa clé API et son webhook secret) |
+| `getOrganization(orgId)` | Obtenir le détail et l'usage du mois d'une clinique |
+| `updateOrganization(orgId, updates)` | Modifier le quota, le statut ou le webhook d'une clinique |
+| `deactivateOrganization(orgId)` | Suspendre une clinique et révoquer ses clés API (soft delete) |
+
 ## Événements webhook
 
 ReqVet déclenche 5 types d'événements : `job.completed`, `job.failed`, `job.amended`, `job.amend_failed`, `job.regenerated`.
@@ -169,6 +184,120 @@ Les livraisons échouées sont retentées 3 fois (0s, 2s, 5s). Implémentez l'id
 
 Voir [SDK_REFERENCE.md §6](./SDK_REFERENCE.md#6-webhook-events) pour la structure complète des payloads de chaque événement.
 
+## Intégration revendeur (multi-tenant)
+
+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';
+
+const reseller = new ReqVet(process.env.REQVET_RESELLER_KEY!);
+
+const result = await reseller.createOrganization({
+  name: 'Clinique du Parc',
+  contactEmail: 'contact@clinique-du-parc.fr',
+  externalId: String(clinic.id),  // votre ID interne → idempotence garantie
+  monthlyQuota: 500,
+  webhookUrl: 'https://votre-app.com/webhooks/reqvet',
+});
+
+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
+```
+
+### 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 (ex. changement de plan)
+await reseller.updateOrganization(orgId, { monthlyQuota: 1000 });
+
+// Suspendre une clinique — révoque ses clés API en cascade
+await reseller.updateOrganization(orgId, { isActive: false });
+
+// Réactiver
+await reseller.updateOrganization(orgId, { isActive: true });
+
+// Désactiver définitivement (soft delete — données conservées pour le RGPD)
+await reseller.deactivateOrganization(orgId);
+```
+
+> 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
 
 Définitions TypeScript complètes incluses :
@@ -181,6 +310,12 @@ import type {
   Template,
   ReqVetReformulation,
   ExtractedFields,
+  // Partner / Reseller
+  PartnerOrganization,
+  OrganizationUsage,
+  CreateOrganizationParams,
+  UpdateOrganizationParams,
+  CreateOrganizationResult,
 } from '@reqvet-sdk/sdk';
 ```
 

package/SDK_REFERENCE.md

@@ -570,7 +570,344 @@ try {
 
 ---
 
-## 9) Checklist d'intégration
+## 9) API Partenaire / Revendeur
+
+Ces méthodes sont réservées aux revendeurs (éditeurs logiciels) qui provisionnent et administrent des cliniques clientes. Elles nécessitent une clé API avec `role='reseller'`, distincte des clés d'organisation standard.
+
+> **Isolation garantie** : un revendeur ne peut accéder qu'aux organisations qu'il a lui-même créées. La contrainte est appliquée en base de données (`parent_org_id = reseller.orgId`) — il n'est pas possible d'accéder aux données d'un autre revendeur, même avec un `orgId` connu.
+
+---
+
+### 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.
+
+**Réponse :**
+
+```ts
+{
+  organizations: Array<{
+    id: string;
+    name: string;
+    contact_email: string | null;
+    is_active: boolean;
+    monthly_quota: number | null;
+    external_id: string | null;
+    created_at: string;
+    usage: {
+      jobs_this_month: number;
+      quota_remaining: number | 'unlimited';
+    };
+  }>;
+}
+```
+
+**Exemple :**
+
+```ts
+const reseller = new ReqVet(process.env.REQVET_RESELLER_KEY!);
+
+const { organizations } = await reseller.listOrganizations();
+
+for (const org of organizations) {
+  console.log(`${org.name} — ${org.usage.jobs_this_month} jobs ce mois / quota ${org.monthly_quota}`);
+}
+```
+
+---
+
+### `createOrganization(params)`
+
+Provisionner une nouvelle organisation (clinique) sous le compte revendeur.
+
+Cette méthode crée automatiquement :
+- l'enregistrement de l'organisation dans ReqVet
+- une clé API `rqv_live_...` pour la clinique (stockée hashée côté serveur)
+- un secret de signature webhook `whsec_...`
+
+**Paramètres :**
+
+| Nom | Type | Requis | Description |
+|-----|------|--------|-------------|
+| `name` | `string` | ✅ | Nom de la clinique |
+| `contactEmail` | `string` | — | Email de contact |
+| `externalId` | `string` | — | Votre identifiant interne (active l'idempotence — voir ci-dessous) |
+| `monthlyQuota` | `number` | — | Nombre max de jobs par mois (défaut : 100, max : 10 000) |
+| `webhookUrl` | `string` | — | URL de webhook pour les événements de jobs de cette clinique |
+
+**Idempotence via `externalId`**
+
+Si `externalId` est fourni et qu'une organisation avec ce même identifiant existe déjà sous ce revendeur, la méthode retourne l'organisation existante sans créer de doublon. Le champ `message` est alors présent dans la réponse (`'Organization already exists (idempotent)'`), et `api_key` / `webhook_secret` sont absents (ils ne peuvent pas être récupérés après la création initiale).
+
+**Réponse (statut 201 — première création) :**
+
+```ts
+{
+  organization: {
+    id: string;
+    name: string;
+    monthly_quota: number;
+    external_id: string | null;
+  };
+  api_key: string;       // rqv_live_... — à stocker immédiatement, non récupérable ensuite
+  webhook_secret: string; // whsec_...  — à stocker immédiatement, non récupérable ensuite
+  warning: string;       // "Save api_key and webhook_secret now — they cannot be retrieved later!"
+}
+```
+
+**Réponse (statut 200 — idempotent, organisation déjà existante) :**
+
+```ts
+{
+  message: 'Organization already exists (idempotent)';
+  organization: { id, name, monthly_quota, external_id, is_active };
+  // api_key et webhook_secret absents
+}
+```
+
+**Exemple :**
+
+```ts
+const result = await reseller.createOrganization({
+  name: 'Clinique du Parc',
+  contactEmail: 'contact@clinique-du-parc.fr',
+  externalId: 'votre_id_interne_4892',
+  monthlyQuota: 500,
+  webhookUrl: 'https://votre-app.com/webhooks/reqvet',
+});
+
+if (!result.api_key) {
+  // Organisation déjà existante (idempotent) — récupérer la clé depuis votre propre stockage
+  const storedKey = await db.getApiKey(result.organization.id);
+} else {
+  // Première création — stocker la clé et le secret immédiatement
+  await db.saveClinicCredentials({
+    orgId: result.organization.id,
+    apiKey: result.api_key,
+    webhookSecret: result.webhook_secret,
+  });
+}
+```
+
+---
+
+### `getOrganization(orgId)`
+
+Obtenir les détails et l'usage du mois courant d'une organisation spécifique.
+
+**Paramètres :**
+
+| Nom | Type | Requis | Description |
+|-----|------|--------|-------------|
+| `orgId` | `string` | ✅ | UUID de l'organisation |
+
+**Réponse :** `PartnerOrganization` (même structure que les éléments de `listOrganizations`, avec `usage`)
+
+**Exemple :**
+
+```ts
+const org = await reseller.getOrganization('uuid-de-la-clinique');
+console.log(`Quota restant : ${org.usage.quota_remaining}`);
+```
+
+---
+
+### `updateOrganization(orgId, updates)`
+
+Modifier le quota mensuel, l'état d'activation, ou l'URL de webhook d'une organisation.
+
+Tous les champs sont optionnels — seuls les champs fournis sont mis à jour.
+
+**Paramètres :**
+
+| Nom | Type | Description |
+|-----|------|-------------|
+| `orgId` | `string` | UUID de l'organisation |
+| `updates.monthlyQuota` | `number` | Nouveau quota mensuel (1–10 000) |
+| `updates.isActive` | `boolean` | `false` pour suspendre la clinique (révoque aussi ses clés API) |
+| `updates.webhookUrl` | `string` | Nouvelle URL de webhook (`null` pour supprimer) |
+
+> **Suspension** : passer `isActive: false` désactive l'organisation **et** révoque toutes ses clés API en cascade. Les jobs déjà en cours ne sont pas interrompus. Pour réactiver, passer `isActive: true` — les clés API restent révoquées et doivent être régénérées manuellement si nécessaire.
+
+**Réponse :**
+
+```ts
+{
+  id: string;
+  name: string;
+  is_active: boolean;
+  monthly_quota: number;
+  external_id: string | null;
+}
+```
+
+**Exemples :**
+
+```ts
+// Augmenter le quota
+await reseller.updateOrganization(orgId, { monthlyQuota: 1000 });
+
+// Suspendre une clinique (non-paiement, etc.)
+await reseller.updateOrganization(orgId, { isActive: false });
+
+// Réactiver
+await reseller.updateOrganization(orgId, { isActive: true });
+
+// Mettre à jour le webhook
+await reseller.updateOrganization(orgId, {
+  webhookUrl: 'https://votre-app.com/webhooks/reqvet/v2',
+});
+```
+
+---
+
+### `deactivateOrganization(orgId)`
+
+Désactiver définitivement une organisation et révoquer toutes ses clés API.
+
+Il s'agit d'un **soft delete** : les données (jobs, transcriptions, comptes rendus) sont conservées en base pour respecter les obligations RGPD et permettre un audit trail. L'organisation ne peut plus créer de nouveaux jobs.
+
+**Paramètres :**
+
+| Nom | Type | Requis | Description |
+|-----|------|--------|-------------|
+| `orgId` | `string` | ✅ | UUID de l'organisation |
+
+**Réponse :**
+
+```ts
+{ success: true; message: 'Organization and API keys deactivated' }
+```
+
+**Exemple :**
+
+```ts
+await reseller.deactivateOrganization(orgId);
+// L'organisation est désormais inactive, ses clés API sont révoquées
+```
+
+---
+
+## 10) Checklist d'intégration
+
+**Intégration standard (clinique)**
 
 - [ ] SDK utilisé **côté serveur uniquement** — clé API jamais dans les bundles navigateur
 - [ ] `listTemplates()` appelé au démarrage pour découvrir les `templateId` disponibles
@@ -580,3 +917,15 @@ try {
 - [ ] Vérification anti-replay du timestamp activée (`maxSkewMs`)
 - [ ] Idempotence implémentée — dédoublonnage sur `job_id + event`
 - [ ] `REQVET_API_KEY` et `REQVET_WEBHOOK_SECRET` stockés dans des variables d'environnement, jamais en dur dans le code
+
+**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` — 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/SECURITY.md

@@ -117,6 +117,46 @@ await cache.set(key, true, { ttl: 86400 });
 // process...
 ```
 
+## Clés revendeur et credentials cliniques
+
+Les revendeurs manipulent deux types de secrets supplémentaires qui exigent une attention particulière.
+
+### Clé API revendeur
+
+La clé revendeur (`rqv_live_...` avec `role='reseller'`) donne accès à l'ensemble des cliniques que vous administrez. Elle est plus sensible qu'une clé clinique standard.
+
+```bash
+# Variable d'environnement dédiée, distincte de la clé clinique
+REQVET_RESELLER_KEY=rqv_live_...
+```
+
+**Ne jamais** utiliser la clé revendeur côté client ni la partager avec les cliniques.
+
+### `api_key` et `webhook_secret` retournés par `createOrganization`
+
+Ces deux valeurs sont **affichées une seule fois** au moment de la création. Après la réponse HTTP initiale, elles ne peuvent pas être récupérées (seul le hash SHA-256 de la clé est stocké côté serveur).
+
+```ts
+const result = await reseller.createOrganization({ name: 'Clinique du Parc', externalId: 'id_4892' });
+
+// ✅ Stocker immédiatement dans votre vault ou base chiffrée
+await secretsVault.store({
+  orgId: result.organization.id,
+  apiKey: result.api_key,           // non récupérable après cette réponse
+  webhookSecret: result.webhook_secret, // non récupérable après cette réponse
+});
+
+// ✅ Transmettre la clé à la clinique de manière sécurisée (canal chiffré, jamais par email)
+```
+
+Si une clé clinique est perdue ou compromise, le seul recours est de désactiver l'organisation via `deactivateOrganization()` et d'en créer une nouvelle.
+
+### Isolation entre revendeurs
+
+L'API Partner filtre toutes les requêtes sur `parent_org_id = reseller.orgId` côté base de données. Il n'est pas possible d'accéder aux cliniques d'un autre revendeur, même en connaissant un `orgId` valide. Ne pas tenter de contourner cette isolation.
+
+---
+
 ## API key rotation
 
 If a key is compromised:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqvet-sdk/sdk",
-  "version": "2.2.2",
+  "version": "2.2.4",
   "description": "Official JavaScript SDK for the ReqVet veterinary report generation API.",
   "type": "module",
   "main": "./src/index.js",
@@ -18,13 +18,7 @@
     },
     "./package.json": "./package.json"
   },
-  "files": [
-    "src/",
-    "README.md",
-    "SDK_REFERENCE.md",
-    "CHANGELOG.md",
-    "SECURITY.md"
-  ],
+  "files": ["src/", "README.md", "SDK_REFERENCE.md", "CHANGELOG.md", "SECURITY.md"],
   "keywords": [
     "reqvet",
     "veterinary",

package/src/index.d.ts

@@ -188,6 +188,52 @@ export interface ReqVetReformulation {
   created_at: string;
 }
 
+// ─── Partner / Reseller Types ────────────────────────────────
+
+export interface OrganizationUsage {
+  jobs_this_month: number;
+  quota_remaining: number | 'unlimited';
+}
+
+export interface PartnerOrganization {
+  id: string;
+  name: string;
+  contact_email: string | null;
+  is_active: boolean;
+  monthly_quota: number | null;
+  external_id: string | null;
+  created_at: string;
+  usage?: OrganizationUsage;
+}
+
+export interface CreateOrganizationParams {
+  name: string;
+  contactEmail?: string;
+  /** Your internal ID — enables idempotency (same externalId returns the existing org) */
+  externalId?: string;
+  /** Max jobs per month (default: 100, max: 10 000) */
+  monthlyQuota?: number;
+  webhookUrl?: string;
+}
+
+export interface UpdateOrganizationParams {
+  monthlyQuota?: number;
+  /** Set to false to suspend the clinic and revoke its API keys */
+  isActive?: boolean;
+  webhookUrl?: string;
+}
+
+export interface CreateOrganizationResult {
+  organization: Pick<PartnerOrganization, 'id' | 'name' | 'monthly_quota' | 'external_id'>;
+  /** The clinic's API key — returned only once, store it securely! */
+  api_key: string;
+  /** Webhook signing secret — returned only once, store it securely! */
+  webhook_secret: string;
+  warning: string;
+  /** Returned instead of api_key/webhook_secret when the org already exists (idempotent) */
+  message?: string;
+}
+
 // ─── Client ──────────────────────────────────────────────────
 
 export declare class ReqVetError extends Error {
@@ -272,6 +318,30 @@ export declare class ReqVet {
   /** Delete a template */
   deleteTemplate(templateId: string): Promise<{ success: boolean }>;
 
+  // ─── Partner / Reseller (requires role='reseller' API key) ──
+
+  /** List all organizations provisioned by the reseller */
+  listOrganizations(): Promise<{ organizations: PartnerOrganization[] }>;
+
+  /**
+   * Provision a new organization/clinic.
+   * Idempotent via externalId — returns existing org if already provisioned.
+   * ⚠️ api_key and webhook_secret are returned only once.
+   */
+  createOrganization(params: CreateOrganizationParams): Promise<CreateOrganizationResult>;
+
+  /** Get details and current month usage of a specific organization */
+  getOrganization(orgId: string): Promise<PartnerOrganization>;
+
+  /** Update an organization's quota, status, or webhook URL */
+  updateOrganization(
+    orgId: string,
+    updates: UpdateOrganizationParams,
+  ): Promise<Pick<PartnerOrganization, 'id' | 'name' | 'is_active' | 'monthly_quota' | 'external_id'>>;
+
+  /** Deactivate an organization and revoke all its API keys (soft delete) */
+  deactivateOrganization(orgId: string): Promise<{ success: boolean; message: string }>;
+
   /** Health check */
   health(): Promise<{ status: string; services: Record<string, string> }>;
 }

package/src/index.js

@@ -416,6 +416,87 @@ class ReqVet {
     return this._fetch('DELETE', `/api/v1/templates/${templateId}`);
   }
 
+  // ─── Partner / Reseller ────────────────────────────────────
+
+  /**
+   * List all organizations provisioned by the reseller.
+   * Requires a reseller API key (role='reseller').
+   *
+   * @returns {Promise<{organizations: Object[]}>}
+   */
+  async listOrganizations() {
+    return this._fetch('GET', '/api/v1/partner/orgs');
+  }
+
+  /**
+   * Provision a new organization (clinic) under the reseller account.
+   * Requires a reseller API key (role='reseller').
+   *
+   * Idempotent via externalId: if an org with the same externalId already
+   * exists under this reseller, the existing one is returned (no duplicate).
+   *
+   * ⚠️ The returned api_key and webhook_secret are shown only once — store them securely.
+   *
+   * @param {Object} params
+   * @param {string} params.name - Clinic name
+   * @param {string} [params.contactEmail]
+   * @param {string} [params.externalId] - Your internal ID (enables idempotency)
+   * @param {number} [params.monthlyQuota] - Job quota per month (default: 100, max: 10 000)
+   * @param {string} [params.webhookUrl] - Webhook URL for job results
+   * @returns {Promise<Object>}
+   */
+  async createOrganization({ name, contactEmail, externalId, monthlyQuota, webhookUrl }) {
+    return this._fetch('POST', '/api/v1/partner/orgs', {
+      name,
+      contact_email: contactEmail,
+      external_id: externalId,
+      monthly_quota: monthlyQuota,
+      webhook_url: webhookUrl,
+    });
+  }
+
+  /**
+   * Get details and current month usage of a specific organization.
+   * Requires a reseller API key (role='reseller').
+   *
+   * @param {string} orgId
+   * @returns {Promise<Object>}
+   */
+  async getOrganization(orgId) {
+    return this._fetch('GET', `/api/v1/partner/orgs/${orgId}`);
+  }
+
+  /**
+   * Update an organization's quota, status, or webhook URL.
+   * Requires a reseller API key (role='reseller').
+   *
+   * @param {string} orgId
+   * @param {Object} updates
+   * @param {number} [updates.monthlyQuota]
+   * @param {boolean} [updates.isActive] - Set to false to suspend the clinic
+   * @param {string} [updates.webhookUrl]
+   * @returns {Promise<Object>}
+   */
+  async updateOrganization(orgId, { monthlyQuota, isActive, webhookUrl } = {}) {
+    return this._fetch('PATCH', `/api/v1/partner/orgs/${orgId}`, {
+      monthly_quota: monthlyQuota,
+      is_active: isActive,
+      webhook_url: webhookUrl,
+    });
+  }
+
+  /**
+   * Deactivate an organization and revoke all its API keys.
+   * Soft delete — data is preserved for audit/GDPR purposes.
+   * Requires a reseller API key (role='reseller').
+   *
+   * @param {string} orgId
+   * @returns {Promise<{success: boolean, message: string}>}
+   */
+  async deactivateOrganization(orgId) {
+    return this._fetch('DELETE', `/api/v1/partner/orgs/${orgId}`);
+  }
+
   // ─── Health ────────────────────────────────────────────────
 
   /**