@reqvet-sdk/sdk 2.2.1 → 2.2.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2.2.1
+
+- **Feat** : ajout de `getSignedUploadUrl(fileName, contentType)` — obtenir une URL presignée Supabase pour uploader l'audio directement, sans passer par `/api/v1/upload` (Vercel Serverless Function, limite ~4.5 MB). Recommandé pour les proxies serveur (Next.js, Express…) gérant des fichiers > 4 MB.
+- **Types** : ajout de `SignedUploadResult` dans `index.d.ts`.
+- **Docs** : `uploadAudio()` annotée avec l'avertissement Vercel dans `index.js`, `index.d.ts`, `SDK_REFERENCE.md` et `README.md`.
+- **Examples** : `nextjs/route-generate.ts` et `nextjs/route-generate.mjs` mis à jour pour utiliser `getSignedUploadUrl()`.
+- **Security** : exemple proxy dans `SECURITY.md` mis à jour.
+
 ## 2.2.0
 
 - **Feat** : ajout de `listJobs(options?)` — liste les jobs avec pagination (`limit`, `offset`) et filtres (`status`, `sort`, `order`). Aligne le SDK sur `GET /api/v1/jobs`.

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.
 
@@ -51,6 +52,8 @@ const templateId = system[0].id;
 
 ### Flux webhook (recommandé)
 
+Pour les intégrations serveur (Next.js, Express…), utilisez `getSignedUploadUrl()` qui uploade le fichier directement dans Supabase sans passer par une Vercel Serverless Function — **pas de limite de taille**.
+
 ```ts
 import ReqVet from '@reqvet-sdk/sdk';
 
@@ -58,20 +61,36 @@ const reqvet = new ReqVet(process.env.REQVET_API_KEY!, {
   baseUrl: process.env.REQVET_BASE_URL,
 });
 
-// 1. Uploader l'audio
-const { path } = await reqvet.uploadAudio(audioBuffer, 'consultation.webm');
+// 1. Obtenir une URL signée Supabase (requête JSON légère, pas de fichier)
+const { uploadUrl, path } = await reqvet.getSignedUploadUrl(
+  'consultation.webm',
+  'audio/webm',
+);
+
+// 2. Uploader directement vers Supabase (contourne Vercel, pas de limite de taille)
+await fetch(uploadUrl, {
+  method: 'PUT',
+  headers: { 'Content-Type': 'audio/webm' },
+  body: audioBuffer, // Buffer | Blob | File
+});
 
-// 2. Créer un job — ReqVet POSTera le résultat sur votre webhook quand il sera prêt
+// 3. Créer un job — ReqVet POSTera le résultat sur votre webhook quand il sera prêt
 const job = await reqvet.createJob({
   audioFile: path,
   animalName: 'Rex',
   templateId: 'your-template-uuid',
   callbackUrl: 'https://your-app.com/api/reqvet/webhook',
-  metadata: { consultationId: 'abc123' },  // transmis tel quel à votre webhook
+  metadata: { consultationId: 'abc123' },
 });
 // { job_id: '...', status: 'pending' }
 ```
 
+> **`uploadAudio()` vs `getSignedUploadUrl()`**
+>
+> `uploadAudio()` est pratique pour des fichiers légers (< 4 MB) ou des contextes navigateur.
+> Pour les proxies serveur, préférez `getSignedUploadUrl()` : le fichier va directement dans Supabase,
+> sans passer par `/api/v1/upload` (Vercel Serverless Function, limite ~4.5 MB).
+
 Votre webhook reçoit un événement `job.completed` :
 
 ```json
@@ -123,9 +142,12 @@ export async function POST(req: NextRequest) {
 
 ## API
 
+### Génération de comptes rendus
+
 | Méthode | Description |
 |---------|-------------|
-| `uploadAudio(audio, fileName?)` | Uploader un fichier audio |
+| `getSignedUploadUrl(fileName, contentType)` | URL signée Supabase pour upload direct (recommandé serveur) |
+| `uploadAudio(audio, fileName?)` | Uploader un fichier audio via ReqVet (limite Vercel ~4.5 MB) |
 | `generateReport(params)` | Upload + création de job (helper tout-en-un) |
 | `createJob(params)` | Créer un job de génération |
 | `listJobs(options?)` | Lister les jobs avec pagination et filtre par statut |
@@ -142,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`.
@@ -150,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 :
@@ -162,6 +246,12 @@ import type {
   Template,
   ReqVetReformulation,
   ExtractedFields,
+  // Partner / Reseller
+  PartnerOrganization,
+  OrganizationUsage,
+  CreateOrganizationParams,
+  UpdateOrganizationParams,
+  CreateOrganizationResult,
 } from '@reqvet-sdk/sdk';
 ```
 

package/SDK_REFERENCE.md

@@ -11,8 +11,8 @@ import ReqVet from '@reqvet-sdk/sdk';
 
 const reqvet = new ReqVet(process.env.REQVET_API_KEY!, {
   baseUrl: process.env.REQVET_BASE_URL ?? 'https://api.reqvet.com',
-  pollInterval: 5000,       // intervalle de polling en ms (défaut : 5000)
-  timeout: 5 * 60 * 1000,  // attente maximale en polling en ms (défaut : 300 000 = 5 min)
+  pollInterval: 5000, // intervalle de polling en ms (défaut : 5000)
+  timeout: 5 * 60 * 1000, // attente maximale en polling en ms (défaut : 300 000 = 5 min)
 });
 ```
 
@@ -25,6 +25,7 @@ La clé API doit commencer par `rqv_`. Une `Error` est levée immédiatement dan
 ### Obtenir vos identifiants
 
 Votre responsable de compte ReqVet vous fournira :
+
 - `REQVET_API_KEY` — votre clé API d'organisation (`rqv_live_...`)
 - `REQVET_BASE_URL` — l'URL de base de l'API
 - `REQVET_WEBHOOK_SECRET` — votre secret de signature webhook (si vous utilisez les webhooks)
@@ -68,9 +69,53 @@ const report = await reqvet.generateReport({ audio, animalName, templateId, wait
 
 ## 4) Méthodes
 
+### `getSignedUploadUrl(fileName, contentType)` ⭐ recommandé serveur
+
+Obtenir une URL signée Supabase pour uploader le fichier audio directement, sans passer par une Vercel Serverless Function.
+
+**Quand l'utiliser :** intégrations serveur (Next.js proxy, Express, etc.), fichiers > 4 MB.
+
+**Flow :**
+```
+getSignedUploadUrl() → PUT uploadUrl (Supabase direct) → createJob({ audioFile: path })
+```
+
+**Paramètres :**
+| Nom | Type | Requis | Description |
+|-----|------|--------|-------------|
+| `fileName` | `string` | ✅ | Nom du fichier (ex. `consultation.webm`) |
+| `contentType` | `string` | ✅ | Type MIME (ex. `audio/webm`) |
+
+**Réponse :**
+```ts
+{
+  uploadUrl: string; // URL presignée Supabase — à utiliser avec PUT
+  path: string;      // chemin de stockage — à passer à createJob()
+}
+```
+
+**Exemple :**
+```ts
+const { uploadUrl, path } = await reqvet.getSignedUploadUrl('consultation.webm', 'audio/webm');
+
+await fetch(uploadUrl, {
+  method: 'PUT',
+  headers: { 'Content-Type': 'audio/webm' },
+  body: audioBuffer,
+});
+
+const job = await reqvet.createJob({ audioFile: path, animalName, templateId });
+```
+
+---
+
 ### `uploadAudio(audio, fileName?)`
 
-Uploader un fichier audio vers le stockage ReqVet.
+Uploader un fichier audio vers le stockage ReqVet via `/api/v1/upload`.
+
+> ⚠️ **Limite serveur** : `/api/v1/upload` est une Vercel Serverless Function avec une limite de payload de ~4.5 MB. Pour les proxies serveur gérant des fichiers > 4 MB, utilisez [`getSignedUploadUrl()`](#getsigneduploadurlfilename-contenttype--recommandé-serveur) à la place.
+>
+> `uploadAudio()` reste adapté pour les contextes navigateur (Blob/File natif, pas de limite Vercel) ou les fichiers légers.
 
 **Paramètres :**
 | Nom | Type | Requis | Description |
@@ -79,10 +124,11 @@ Uploader un fichier audio vers le stockage ReqVet.
 | `fileName` | `string` | — | Nom du fichier, utilisé pour inférer le type MIME (défaut : `audio.webm`) |
 
 **Réponse :**
+
 ```ts
 {
-  audio_file: string;   // chemin de stockage canonique — à passer à createJob()
-  path: string;         // alias de audio_file
+  audio_file: string; // chemin de stockage canonique — à passer à createJob()
+  path: string; // alias de audio_file
   size_bytes: number;
   content_type: string;
 }
@@ -110,6 +156,7 @@ Wrapper pratique : `uploadAudio → createJob`. Attend optionnellement la fin du
 | `onStatus` | `(status: string) => void` | — | Appelé à chaque poll (uniquement si `waitForResult: true`) |
 
 **Réponse :**
+
 - `waitForResult: false` (défaut) : `{ job_id: string, status: 'pending' }`
 - `waitForResult: true` : `ReqVetReport` (voir `waitForJob`)
 
@@ -130,8 +177,12 @@ Démarrer un pipeline de transcription + génération de compte rendu.
 | `extraInstructions` | `string` | — | Instructions de génération supplémentaires (max 5 000 caractères) |
 
 **Réponse :**
+
 ```ts
-{ job_id: string; status: 'pending' }
+{
+  job_id: string;
+  status: 'pending';
+}
 ```
 
 > **Limite de débit** : 10 000 requêtes/minute par organisation.
@@ -152,6 +203,7 @@ Lister les jobs de l'organisation authentifiée, avec pagination et filtrage.
 | `order` | `string` | `desc` | Direction : `asc` ou `desc` |
 
 **Réponse :**
+
 ```ts
 {
   jobs: JobSummary[];
@@ -167,21 +219,22 @@ Obtenir l'état actuel et le résultat d'un job.
 
 **Champs de réponse par statut :**
 
-| Champ | `pending` | `transcribing` | `generating` | `completed` | `failed` |
-|-------|:---------:|:--------------:|:------------:|:-----------:|:--------:|
-| `job_id` | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `status` | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `animal_name` | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `metadata` | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `transcription` | — | — | ✅ | ✅ | — |
-| `result.html` | — | — | — | ✅ | — |
-| `result.fields` | — | — | — | ✅* | — |
-| `cost` | — | — | — | ✅ | — |
-| `error` | — | — | — | — | ✅ |
+| Champ           | `pending` | `transcribing` | `generating` | `completed` | `failed` |
+| --------------- | :-------: | :------------: | :----------: | :---------: | :------: |
+| `job_id`        |    ✅     |       ✅       |      ✅      |     ✅      |    ✅    |
+| `status`        |    ✅     |       ✅       |      ✅      |     ✅      |    ✅    |
+| `animal_name`   |    ✅     |       ✅       |      ✅      |     ✅      |    ✅    |
+| `metadata`      |    ✅     |       ✅       |      ✅      |     ✅      |    ✅    |
+| `transcription` |     —     |       —        |      ✅      |     ✅      |    —     |
+| `result.html`   |     —     |       —        |      —       |     ✅      |    —     |
+| `result.fields` |     —     |       —        |      —       |    ✅\*     |    —     |
+| `cost`          |     —     |       —        |      —       |     ✅      |    —     |
+| `error`         |     —     |       —        |      —       |      —      |    ✅    |
 
-*`result.fields` n'est présent que si votre organisation a un `field_schema` configuré (extraction de données structurées). Vaut `null` sinon. Voir [Schéma de champs](#5-schéma-de-champs) ci-dessous.
+\*`result.fields` n'est présent que si votre organisation a un `field_schema` configuré (extraction de données structurées). Vaut `null` sinon. Voir [Schéma de champs](#5-schéma-de-champs) ci-dessous.
 
 **Structure du coût (jobs terminés) :**
+
 ```ts
 cost: {
   transcription_usd: number;
@@ -199,14 +252,19 @@ cost: {
 Poller jusqu'à ce qu'un job atteigne `completed` ou `failed`. Respecte `pollInterval` et `timeout`.
 
 **Réponse (`ReqVetReport`) :**
+
 ```ts
 {
   jobId: string;
-  html: string;                              // HTML du compte rendu généré
-  fields: ExtractedFields | null;            // null si aucun field_schema configuré
+  html: string; // HTML du compte rendu généré
+  fields: ExtractedFields | null; // null si aucun field_schema configuré
   transcription: string;
   animalName: string;
-  cost: { transcription_usd: number; generation_usd: number; total_usd: number };
+  cost: {
+    transcription_usd: number;
+    generation_usd: number;
+    total_usd: number;
+  }
   metadata: Record<string, unknown>;
 }
 ```
@@ -226,6 +284,7 @@ Régénérer le compte rendu d'un job terminé — par exemple avec des instruct
 | `templateId` | `string` | Basculer vers un autre template |
 
 **Réponse :**
+
 ```ts
 { job_id: string; status: 'completed'; result: { html: string; fields?: ExtractedFields } }
 ```
@@ -247,8 +306,14 @@ Ajouter un audio complémentaire à un job terminé. Le nouvel audio est transcr
 | `templateId` | `string` | — | Basculer vers un autre template |
 
 **Réponse :**
+
 ```ts
-{ job_id: string; status: 'amending'; amendment_number: number; message: string }
+{
+  job_id: string;
+  status: 'amending';
+  amendment_number: number;
+  message: string;
+}
 ```
 
 Le job repasse à `completed` quand l'amendement est terminé. Utilisez `waitForJob()` ou écoutez l'événement webhook `job.amended`. Plusieurs amendements sont supportés — chacun est ajouté à la transcription complète.
@@ -275,6 +340,7 @@ Générer une version alternative d'un compte rendu terminé pour une audience s
 | `custom` | Défini par `customInstructions` |
 
 **Réponse (`ReqVetReformulation`) :**
+
 ```ts
 {
   id: string;
@@ -308,12 +374,12 @@ Générer une version alternative d'un compte rendu terminé pour une audience s
 
 #### `createTemplate(params)` → `Template`
 
-| Nom | Type | Requis |
-|-----|------|--------|
-| `name` | `string` | ✅ |
-| `content` | `string` | ✅ |
-| `description` | `string` | — |
-| `is_default` | `boolean` | — |
+| Nom           | Type      | Requis |
+| ------------- | --------- | ------ |
+| `name`        | `string`  | ✅     |
+| `content`     | `string`  | ✅     |
+| `description` | `string`  | —      |
+| `is_default`  | `boolean` | —      |
 
 #### `updateTemplate(templateId, updates)` → `Template`
 
@@ -462,10 +528,10 @@ import { verifyWebhookSignature } from '@reqvet-sdk/sdk/webhooks';
 
 const { ok, reason } = verifyWebhookSignature({
   secret: process.env.REQVET_WEBHOOK_SECRET!,
-  rawBody,       // corps brut de la requête — à lire AVANT JSON.parse
-  signature,     // valeur de l'en-tête X-ReqVet-Signature
-  timestamp,     // valeur de l'en-tête X-ReqVet-Timestamp
-  maxSkewMs: 5 * 60 * 1000,  // rejeter les événements de plus de 5 min (défaut)
+  rawBody, // corps brut de la requête — à lire AVANT JSON.parse
+  signature, // valeur de l'en-tête X-ReqVet-Signature
+  timestamp, // valeur de l'en-tête X-ReqVet-Timestamp
+  maxSkewMs: 5 * 60 * 1000, // rejeter les événements de plus de 5 min (défaut)
 });
 ```
 
@@ -486,25 +552,245 @@ try {
   const report = await reqvet.waitForJob(jobId);
 } catch (err) {
   if (err instanceof ReqVetError) {
-    console.error(err.message);  // message lisible par un humain
-    console.error(err.status);   // statut HTTP (0 pour les erreurs réseau/timeout)
-    console.error(err.body);     // corps brut de la réponse
+    console.error(err.message); // message lisible par un humain
+    console.error(err.status); // statut HTTP (0 pour les erreurs réseau/timeout)
+    console.error(err.body); // corps brut de la réponse
   }
 }
 ```
 
-| Statut | Signification |
-|--------|---------------|
-| `400` | Erreur de validation — vérifiez `err.body.issues` |
-| `401` | Clé API invalide ou manquante |
-| `403` | Quota mensuel dépassé |
-| `404` | Job ou template introuvable |
-| `429` | Limite de débit dépassée — attendez et réessayez |
-| `500` | Erreur interne ReqVet |
+| Statut | Signification                                     |
+| ------ | ------------------------------------------------- |
+| `400`  | Erreur de validation — vérifiez `err.body.issues` |
+| `401`  | Clé API invalide ou manquante                     |
+| `403`  | Quota mensuel dépassé                             |
+| `404`  | Job ou template introuvable                       |
+| `429`  | Limite de débit dépassée — attendez et réessayez  |
+| `500`  | Erreur interne ReqVet                             |
+
+---
+
+## 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}`);
+}
+```
 
 ---
 
-## 9) Checklist d'intégration
+### `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
@@ -514,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

@@ -29,7 +29,7 @@ Example proxy route (Next.js App Router):
 ```ts
 // app/api/reqvet/generate/route.ts
 import { NextRequest, NextResponse } from 'next/server';
-import ReqVet from '@reqvet/sdk';
+import ReqVet from '@reqvet-sdk/sdk';
 
 const reqvet = new ReqVet(process.env.REQVET_API_KEY!);
 
@@ -37,7 +37,21 @@ export async function POST(req: NextRequest) {
   const form = await req.formData();
   const audio = form.get('audio') as File;
 
-  const { path } = await reqvet.uploadAudio(audio, audio.name);
+  // Use getSignedUploadUrl() instead of uploadAudio() for server-side proxies.
+  // uploadAudio() posts to /api/v1/upload (Vercel Serverless Function, ~4.5 MB limit).
+  // getSignedUploadUrl() uploads directly to Supabase — no size limit.
+  const { uploadUrl, path } = await reqvet.getSignedUploadUrl(
+    audio.name || 'consultation.webm',
+    audio.type || 'audio/webm',
+  );
+
+  const audioBuffer = Buffer.from(await audio.arrayBuffer());
+  await fetch(uploadUrl, {
+    method: 'PUT',
+    headers: { 'Content-Type': audio.type || 'audio/webm' },
+    body: audioBuffer,
+  });
+
   const job = await reqvet.createJob({
     audioFile: path,
     animalName: form.get('animalName') as string,
@@ -103,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.1",
+  "version": "2.2.3",
   "description": "Official JavaScript SDK for the ReqVet veterinary report generation API.",
   "type": "module",
   "main": "./src/index.js",

package/src/index.d.ts

@@ -15,6 +15,13 @@ export interface UploadResult {
   content_type: string;
 }
 
+export interface SignedUploadResult {
+  /** Presigned URL for direct PUT upload to Supabase storage */
+  uploadUrl: string;
+  /** Storage path to pass to createJob({ audioFile: path }) */
+  path: string;
+}
+
 export interface JobResult {
   job_id: string;
   status: 'pending' | 'transcribing' | 'generating' | 'completed' | 'failed' | 'amending';
@@ -181,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 {
@@ -201,7 +254,18 @@ export declare class ReqVet {
   generateReport(params: GenerateReportParams & { waitForResult?: false }): Promise<JobResult>;
   generateReport(params: GenerateReportParams): Promise<JobResult | ReqVetReport>;
 
-  /** Upload an audio file */
+  /**
+   * Get a presigned URL for direct upload to Supabase storage.
+   * Recommended for server-side proxies — bypasses Vercel's ~4.5 MB payload limit.
+   * PUT the audio buffer to uploadUrl, then pass path to createJob().
+   */
+  getSignedUploadUrl(fileName: string, contentType: string): Promise<SignedUploadResult>;
+
+  /**
+   * Upload an audio file via ReqVet's /api/v1/upload endpoint.
+   * ⚠️ Subject to Vercel Serverless Function payload limit (~4.5 MB).
+   * For files > 4 MB in server-side contexts, use getSignedUploadUrl() instead.
+   */
   uploadAudio(audio: Blob | Buffer | File, fileName?: string): Promise<UploadResult>;
 
   /** Create a generation job */
@@ -254,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

@@ -108,9 +108,37 @@ class ReqVet {
 
   // ─── Upload ────────────────────────────────────────────────
 
+  /**
+   * Get a presigned upload URL for direct upload to ReqVet storage (Supabase).
+   *
+   * Recommended for server-side integrations (e.g. Next.js proxy routes).
+   * The file goes directly to Supabase — it never passes through a Vercel
+   * Serverless Function, so there is no ~4.5 MB payload limit.
+   *
+   * Flow:
+   *   1. getSignedUploadUrl(fileName, contentType) — tiny JSON request, no file.
+   *   2. PUT the audio buffer to uploadUrl (direct to Supabase).
+   *   3. Pass path to createJob({ audioFile: path }).
+   *
+   * @param {string} fileName - File name (e.g. 'consultation.webm')
+   * @param {string} contentType - MIME type (e.g. 'audio/webm')
+   * @returns {Promise<{uploadUrl: string, path: string}>}
+   */
+  async getSignedUploadUrl(fileName, contentType) {
+    return this._fetch('POST', '/api/v1/storage/signed-upload', {
+      file_name: fileName,
+      content_type: contentType,
+    });
+  }
+
   /**
    * Upload an audio file to ReqVet storage.
    *
+   * ⚠️  This method POSTs the file to /api/v1/upload, which runs as a
+   * Vercel Serverless Function (~4.5 MB request limit). For server-side
+   * proxies (Next.js, Express…) handling files > 4 MB, prefer
+   * getSignedUploadUrl() + a direct PUT to avoid this limit.
+   *
    * @param {Blob|Buffer|File} audio - The audio file
    * @param {string} [fileName] - File name
    * @returns {Promise<{audio_file: string, size_bytes: number}>}
@@ -388,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 ────────────────────────────────────────────────
 
   /**