@reqvet-sdk/sdk 2.2.2 → 2.2.3

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,56 @@ 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), utilisez une clé API revendeur pour provisionner et gérer les organisations de manière programmatique.
+
+```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
+  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_...
+});
+
+// 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 });
+
+// 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
+await reseller.updateOrganization(orgId, { monthlyQuota: 1000 });
+
+// Suspendre une clinique (révoque aussi ses clés API)
+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);
+```
+
+> **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.
+
 ## TypeScript
 
 Définitions TypeScript complètes incluses :
@@ -181,6 +246,12 @@ import type {
   Template,
   ReqVetReformulation,
   ExtractedFields,
+  // Partner / Reseller
+  PartnerOrganization,
+  OrganizationUsage,
+  CreateOrganizationParams,
+  UpdateOrganizationParams,
+  CreateOrganizationResult,
 } from '@reqvet-sdk/sdk';
 ```
 

package/SDK_REFERENCE.md

@@ -570,7 +570,227 @@ 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.
+
+---
+
+### `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 +800,11 @@ 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` 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
+- [ ] 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.3",
   "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 ────────────────────────────────────────────────
 
   /**