@reqvet-sdk/sdk 2.2.1 → 2.2.2

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

@@ -51,6 +51,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 +60,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
@@ -125,7 +143,8 @@ export async function POST(req: NextRequest) {
 
 | 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 |

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,21 +552,21 @@ 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                             |
 
 ---
 

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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqvet-sdk/sdk",
-  "version": "2.2.1",
+  "version": "2.2.2",
   "description": "Official JavaScript SDK for the ReqVet veterinary report generation API.",
   "type": "module",
   "main": "./src/index.js",
@@ -18,7 +18,13 @@
     },
     "./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

@@ -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';
@@ -201,7 +208,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 */

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}>}