@aurabase/functions 0.5.4 → 0.6.1

package/README.md

@@ -26,6 +26,10 @@ import { createClient } from '@aurabase/aurabase-js'
 const aura = createClient('https://mon-projet.aurabase.cloud', 'aura_anon_xxx')
 ```
 
+### Qui peut appeler quoi
+
+Seule l'**invocation** (`invoke`) est ouverte à la clé publique `anon` et aux JWT utilisateur. Tout le reste (`list`, `get`, `listJobs`, `getJob`, `enqueueJob`, `listCronJobs`, `createCronJob`, `deleteCronJob`) exige une clé `service_role` et s'utilise **côté serveur** : une `FunctionDef` contient le code source et les variables d'environnement de la fonction, donc ces appels répondent `403` à une clé publique. `createClient` refuse d'ailleurs une clé `service_role` dans un navigateur.
+
 ### Invocation
 
 `invoke<T>()` décrit la requête que votre fonction doit recevoir (`{ method, path, headers, body }`) et dé-wrap la réponse JSON du backend — tout est bufferisé, pas de streaming (voir Limitations).
@@ -44,6 +48,8 @@ console.log(data.ok)
 
 Options complètes : `body`, `method`, `path` (sous-route à l'intérieur de la fonction), `headers` (transmis à la fonction elle-même, pas des headers de transport), `signal`, `timeout`, `responseType`.
 
+Le `body` doit être sérialisable en JSON (objet, tableau, chaîne, nombre, booléen). Un `Blob`, un `ArrayBuffer`, un tableau typé, un `FormData`, un `URLSearchParams` ou un `ReadableStream` est refusé avant tout appel réseau avec le code `invalid_body` : le runtime ne reçoit que du JSON, et ces objets seraient transmis vides ou déformés. Encodez-les (par exemple en base64) ou passez par Storage.
+
 ```ts
 const controller = new AbortController()
 
@@ -85,7 +91,7 @@ Deno.serve(async (req) => {
 })
 ```
 
-Défauts si vous ne précisez rien : `POST` sur `/`. `GET` et `HEAD` sont envoyés sans corps (la spec Fetch l'interdit) ; un `body` non-chaîne est sérialisé en JSON et `content-type: application/json` est posé si vous n'en fixez pas un.
+Défauts si vous ne précisez rien : `POST` sur `/`. `GET` et `HEAD` sont envoyés sans corps (la spec Fetch l'interdit) ; un `body` non-chaîne est sérialisé en JSON ; `content-type: application/json` est posé si vous n'en fixez pas un — y compris pour une chaîne, que la fonction reçoit alors telle quelle : lisez-la avec `await req.text()` plutôt que `req.json()`.
 
 Sans `body`, la fonction reçoit une requête **sans corps** (parité `@supabase/functions-js`) : un `await req.json()` inconditionnel y échoue. Écrivez `await req.json().catch(() => ({}))` si l'appel peut être fait sans charge utile.
 
@@ -95,7 +101,7 @@ Les en-têtes de cadrage/transport (`content-length`, `transfer-encoding`, `conn
 
 #### Type de réponse (`responseType`)
 
-Défaut `'json'` : le corps est parsé et dé-wrappé (`{data}` → contenu). Les autres valeurs renvoient le corps brut de la fonction, sans dé-wrapping, et `error.status` porte alors le **vrai** statut HTTP de la fonction :
+Défaut `'json'` : le corps est parsé et dé-wrappé (`{data}` → contenu). Une réponse texte (`text/plain`…) arrive telle quelle, en chaîne. Un contenu **binaire** (image, PDF…) ne peut pas passer par ce mode : le SDK renvoie `invalid_response` en vous orientant vers `responseType`. Les autres valeurs renvoient le corps brut de la fonction, sans dé-wrapping, et `error.status` porte alors le **vrai** statut HTTP de la fonction :
 
 ```ts
 const { data: csv } = await aura.functions.invoke<string>('export', { responseType: 'text' })
@@ -109,27 +115,31 @@ Parité `@supabase/functions-js`. Les deux classes sous-classent `AuraError` (do
 
 | Classe | Quand | Statuts |
 |---|---|---|
-| `FunctionsHttpError` | **votre fonction** a répondu en erreur | tout non-2xx hors relais (400, 404, 500…) |
-| `FunctionsRelayError` | la réponse de votre fonction n'est jamais arrivée | 0 (réseau), 502, 503, 504 |
+| `FunctionsHttpError` | **votre fonction** a répondu en erreur, ou une route de gestion a échoué | tout non-2xx venant de la fonction (400, 404, 500, **y compris 502/503/504 qu'elle renvoie elle-même**) |
+| `FunctionsRelayError` | la **plateforme** a échoué : la réponse de votre fonction n'est jamais arrivée | 0 (réseau), 502, 503, 504 produits par la passerelle ou le runtime |
+
+Le message d'une `FunctionsHttpError` est celui que votre fonction a renvoyé : texte brut, `{ "message": "…" }`, `{ "error": "…" }` ou `{ "error": { "message": "…" } }`. `error.context` conserve le corps d'origine (objet JSON ou texte). Une fonction qui répond 500 sans corps donne « Function returned HTTP 500 ».
 
 Deux statuts de relais à ne pas confondre — ils ne se rejouent pas de la même façon :
 
 - **503 `SERVICE_UNAVAILABLE`** : l'edge-runtime est injoignable, votre fonction **n'a pas** été exécutée → réessayer est sûr ;
-- **504 `TIMEOUT`** : votre fonction a dépassé son budget (`permissions.timeout_secs` + marge). Elle **a été lancée** et a pu produire ses effets de bord ; seule la réponse manque → ne rejouez pas une opération non idempotente à l'aveugle.
+- **504 `TIMEOUT`** : l'attente a dépassé le budget de la fonction (`permissions.timeout_secs` + marge). La fonction **a été lancée** et a pu produire ses effets de bord ; seule la réponse manque → ne rejouez pas une opération non idempotente à l'aveugle.
 
 ```ts
-import { FunctionsHttpError, FunctionsRelayError, isRelayStatus } from '@aurabase/functions'
+import { FunctionsHttpError, FunctionsRelayError, isRelayStatus } from '@aurabase/aurabase-js'
 
 const { error } = await aura.functions.invoke('checkout', { responseType: 'text' })
 if (error instanceof FunctionsRelayError) {
-  // rien n'a été exécuté côté fonction → réessayer est sûr
+  // panne de plateforme : 503 → rien n'a été exécuté, 504 → peut-être exécuté, vérifiez avant de rejouer
 } else if (error instanceof FunctionsHttpError) {
   // la fonction a bien tourné et a répondu en erreur → déboguer VOTRE code
 }
 isRelayStatus(error?.status ?? 0) // même décision, sans instanceof
 ```
 
-Une annulation (`timeout`/`signal`) reste une `AuraError` de code `timeout`, jamais une de ces deux classes.
+Une annulation (`timeout`/`signal`) reste une `AuraError` de code `timeout`, jamais une de ces deux classes. Sans `timeout` ni `signal`, le délai par défaut du client (`requestTimeoutMs`, 30 s) s'applique à tous les modes, `responseType` compris.
+
+Les segments passés à `invoke`, `get`, `getJob` et `deleteCronJob` sont encodés (`encodeURIComponent`) : un nom contenant `/`, `?` ou `#` ne peut pas sortir de sa position dans l'URL.
 
 ### Fonctions (métadonnées)
 
@@ -170,7 +180,7 @@ await aura.functions.deleteCronJob('nightly-cleanup')
 ## Contrat d'invocation et comportement des erreurs
 
 - **Déballage transparent :** En mode `responseType: 'json'` (défaut), `data` contient directement le type attendu `T` renvoyé par votre fonction. Pour préserver la compatibilité avec le code existant lisant l'enveloppe, les propriétés `status` et `body` restent accessibles sur l'objet retourné.
-- **Propagation des erreurs HTTP applicatives :** Si votre fonction répond avec un statut HTTP $\ge 400$, le SDK lève désormais une `FunctionsHttpError` avec le statut réel de votre fonction (`error.status`) et son message d'erreur, même lorsque le transport réseau sous-jacent utilise une enveloppe.
+- **Propagation des erreurs HTTP applicatives :** Si votre fonction répond avec un statut HTTP supérieur ou égal à 400, le SDK renvoie une `FunctionsHttpError` avec le statut réel de votre fonction (`error.status`) et son message d'erreur, même lorsque le transport réseau sous-jacent utilise une enveloppe.
 - **Relais et disponibilité :** En cas d'indisponibilité du runtime ou de coupure réseau, une `FunctionsRelayError` est renvoyée.
 - **Propagation d'identité sécurisée :** Les en-têtes d'autorisation (`Authorization: Bearer <token>`, `apikey`) sont validés par la passerelle Aurabase et propagés de façon étanche vers le worker de la fonction (`x-aura-user-id`, `x-aura-role`), protégeant votre backend contre toute falsification client.
 

package/dist/index.cjs

@@ -27,7 +27,31 @@ var FunctionsRelayError = class _FunctionsRelayError extends core.AuraError {
 };
 function toFunctionsError(err, context) {
   const body = err.details != null ? err.details : { error: { code: err.code, message: err.message } };
-  return isRelayStatus(err.status) ? new FunctionsRelayError(err.status, body, context ?? err.details) : new FunctionsHttpError(err.status, body, context ?? err.details);
+  return isRelayStatus(err.status) ? new FunctionsRelayError(err.status, body, err.details) : new FunctionsHttpError(err.status, body, err.details);
+}
+var INVOKE_ORIGIN_HEADER = "x-aurabase-invoke-origin";
+var seg = encodeURIComponent;
+function unserializableBodyKind(body) {
+  if (body === null || typeof body !== "object") return null;
+  const g = globalThis;
+  for (const name of ["Blob", "FormData", "URLSearchParams", "ReadableStream"]) {
+    const ctor = g[name];
+    if (typeof ctor === "function" && body instanceof ctor) return name;
+  }
+  if (body instanceof ArrayBuffer) return "ArrayBuffer";
+  if (ArrayBuffer.isView(body)) return body.constructor.name;
+  return null;
+}
+function envelopeContentType(headers) {
+  if (headers === null || typeof headers !== "object") return void 0;
+  for (const [k, v] of Object.entries(headers)) {
+    if (k.toLowerCase() === "content-type" && typeof v === "string") return v.toLowerCase();
+  }
+  return void 0;
+}
+function isTextual(contentType) {
+  if (!contentType) return true;
+  return contentType.includes("json") || contentType.startsWith("text/") || contentType.includes("xml");
 }
 var FunctionsService = class extends core.BaseService {
   constructor(client) {
@@ -74,11 +98,26 @@ var FunctionsService = class extends core.BaseService {
    * `signal` produisent le code `timeout`.
    */
   async invoke(slug, options) {
+    const badBody = unserializableBodyKind(options?.body);
+    if (badBody) {
+      return {
+        data: null,
+        error: new core.AuraError(0, {
+          error: {
+            code: "invalid_body",
+            message: `Le corps d'invocation doit \xEAtre s\xE9rialisable en JSON (objet, tableau, cha\xEEne, nombre, bool\xE9en) : un ${badBody} serait transmis vide ou d\xE9form\xE9. Encodez-le (par exemple en base64) ou passez par Storage.`
+          }
+        })
+      };
+    }
+    const responseType = options?.responseType ?? "json";
     const controller = new AbortController();
     let timeoutId;
     const userSignal = options?.signal;
     const onAbort = () => controller.abort();
-    if (options?.timeout) timeoutId = setTimeout(() => controller.abort(), options.timeout);
+    const clientTimeout = this.client.requestTimeoutMs ?? core.DEFAULT_REQUEST_TIMEOUT_MS;
+    const timeoutMs = options?.timeout || (responseType !== "json" && userSignal === void 0 && clientTimeout > 0 ? clientTimeout : 0);
+    if (timeoutMs) timeoutId = setTimeout(() => controller.abort(), timeoutMs);
     if (userSignal) {
       if (userSignal.aborted) controller.abort();
       else userSignal.addEventListener("abort", onAbort, { once: true });
@@ -93,7 +132,6 @@ var FunctionsService = class extends core.BaseService {
       headers: options?.headers,
       body: options?.body
     };
-    const responseType = options?.responseType ?? "json";
     const timeoutError = () => ({
       data: null,
       error: new core.AuraError(0, {
@@ -103,7 +141,7 @@ var FunctionsService = class extends core.BaseService {
     try {
       if (responseType === "json") {
         const hasCanceller = options?.timeout !== void 0 || userSignal !== void 0;
-        const res2 = await this.request("POST", `${this.prefix}/${slug}/invoke`, envelope, {
+        const res2 = await this.request("POST", `${this.prefix}/${seg(slug)}/invoke`, envelope, {
           ...hasCanceller ? { signal: controller.signal } : {}
         });
         if (res2.error && controller.signal.aborted) return timeoutError();
@@ -113,7 +151,7 @@ var FunctionsService = class extends core.BaseService {
           const invokeStatus = rawData.status;
           const invokeBody = rawData.body;
           if (typeof invokeStatus === "number" && invokeStatus >= 400) {
-            const errPayload = typeof invokeBody === "object" && invokeBody !== null ? invokeBody : { message: String(invokeBody) };
+            const errPayload = typeof invokeBody === "object" && invokeBody !== null ? invokeBody : invokeBody === null || invokeBody === void 0 || invokeBody === "" ? {} : { message: typeof invokeBody === "string" ? invokeBody : JSON.stringify(invokeBody) };
             const errorMsg = typeof errPayload.message === "string" ? errPayload.message : typeof errPayload.error === "string" ? errPayload.error : typeof errPayload.error?.message === "string" ? String(errPayload.error.message) : `Function returned HTTP ${invokeStatus}`;
             const normalizedBody = {
               ...errPayload,
@@ -125,10 +163,21 @@ var FunctionsService = class extends core.BaseService {
             };
             return {
               data: null,
-              error: toFunctionsError(new core.AuraError(invokeStatus, normalizedBody), invokeBody)
+              error: new FunctionsHttpError(invokeStatus, normalizedBody, invokeBody)
             };
           }
-          let unwrappedData = invokeBody;
+          if (invokeBody === null && invokeStatus !== 204 && !isTextual(envelopeContentType(rawData.headers))) {
+            return {
+              data: null,
+              error: new core.AuraError(0, {
+                error: {
+                  code: "invalid_response",
+                  message: `La fonction a r\xE9pondu un contenu binaire (HTTP ${invokeStatus}) que le mode JSON ne peut pas transmettre : utilisez responseType 'blob' ou 'arrayBuffer'.`
+                }
+              })
+            };
+          }
+          const unwrappedData = invokeBody;
           if (unwrappedData !== null && typeof unwrappedData === "object") {
             if (!("body" in unwrappedData)) {
               Object.defineProperty(unwrappedData, "body", {
@@ -166,19 +215,34 @@ var FunctionsService = class extends core.BaseService {
       };
       if (store.token) headers["Authorization"] = `Bearer ${store.token}`;
       if (client.apiKey) headers["apikey"] = client.apiKey;
-      const res = await client.fetchFn(this.url(`${this.prefix}/${slug}/invoke`), {
+      const res = await client.fetchFn(this.url(`${this.prefix}/${seg(slug)}/invoke`), {
         method: "POST",
         headers,
         body: JSON.stringify(envelope),
         signal: controller.signal
       });
       if (!res.ok) {
+        let text = "";
+        try {
+          text = await res.text();
+        } catch (e) {
+          if (controller.signal.aborted || core.isAbortError(e)) throw e;
+        }
         let parsed = null;
         try {
-          parsed = await res.json();
+          parsed = text.trim() ? JSON.parse(text) : null;
         } catch {
         }
-        return { data: null, error: toFunctionsError(new core.AuraError(res.status, parsed)) };
+        const isObject = parsed !== null && typeof parsed === "object";
+        const stringError = isObject && typeof parsed.error === "string" ? parsed.error : void 0;
+        const body = isObject ? stringError !== void 0 && typeof parsed.message !== "string" ? { ...parsed, message: stringError } : parsed : text.trim() ? { message: text } : null;
+        if (res.headers.get(INVOKE_ORIGIN_HEADER) === "function") {
+          return {
+            data: null,
+            error: new FunctionsHttpError(res.status, body, isObject ? parsed : text || null)
+          };
+        }
+        return { data: null, error: toFunctionsError(new core.AuraError(res.status, body, res.headers)) };
       }
       let data;
       if (responseType === "text") data = await res.text();
@@ -201,6 +265,10 @@ var FunctionsService = class extends core.BaseService {
     }
   }
   // -- Function CRUD ----------------------------------------------------------
+  /**
+   * Liste les fonctions déployées du projet, avec leur code source et leurs variables.
+   * Exige une clé `service_role` : une clé publique reçoit `403`.
+   */
   async list() {
     return this.request("GET", `${this.prefix}`);
   }
@@ -212,9 +280,13 @@ var FunctionsService = class extends core.BaseService {
    * le NOM l'emporte. Une valeur qui n'est ni l'un ni l'autre produit un 404 qui le dit.
    */
   async get(nameOrId) {
-    return this.request("GET", `${this.prefix}/${nameOrId}`);
+    return this.request("GET", `${this.prefix}/${seg(nameOrId)}`);
   }
   // -- Jobs -------------------------------------------------------------------
+  /**
+   * Liste les jobs asynchrones du projet, filtrés par `status` (`pending`, `running`, `completed`,
+   * `failed`, `dead`). `limit` va de 1 à 500 (50 par défaut). Exige une clé `service_role`.
+   */
   async listJobs(options) {
     const params = new URLSearchParams();
     if (options?.status) params.set("status", options.status);
@@ -222,8 +294,9 @@ var FunctionsService = class extends core.BaseService {
     const qs = params.toString() ? `?${params.toString()}` : "";
     return this.request("GET", `${this.prefix}/jobs${qs}`);
   }
+  /** Lit un job par son identifiant. Exige une clé `service_role`. */
   async getJob(jobId) {
-    return this.request("GET", `${this.prefix}/jobs/${jobId}`);
+    return this.request("GET", `${this.prefix}/jobs/${seg(jobId)}`);
   }
   /**
    * Enfile un job d'exécution asynchrone en arrière-plan pour une fonction.
@@ -249,9 +322,15 @@ var FunctionsService = class extends core.BaseService {
     });
   }
   // -- Cron -------------------------------------------------------------------
+  /** Liste les tâches cron du projet. Exige une clé `service_role`. */
   async listCronJobs() {
     return this.request("GET", `${this.prefix}/cron`);
   }
+  /**
+   * Crée une tâche cron : à chaque échéance, un job est mis en file pour `functionName`.
+   * `schedule` compte 5 champs (`min heure jour mois jour-semaine`) ou 6 (avec les secondes), en UTC ;
+   * les alias comme `@daily` sont refusés. Le `payload` est figé à la création. Exige une clé `service_role`.
+   */
   async createCronJob(name, schedule, functionName, options) {
     return this.request("POST", `${this.prefix}/cron`, {
       name,
@@ -260,8 +339,12 @@ var FunctionsService = class extends core.BaseService {
       payload: options?.payload
     });
   }
+  /**
+   * Supprime une tâche cron par son NOM (et non son identifiant) ; un nom inconnu renvoie 404.
+   * La tâche cesse aussi de se déclencher. Exige une clé `service_role`.
+   */
   async deleteCronJob(name) {
-    return this.request("DELETE", `${this.prefix}/cron/${name}`);
+    return this.request("DELETE", `${this.prefix}/cron/${seg(name)}`);
   }
 };
 

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { AuraError, BaseService, AuraClientLike, AuraResponse, FunctionDef, Job, CronJob } from '@aurabase/core';
-export { AuraResponse, CronJob, FunctionDef, Job } from '@aurabase/core';
+export { AuraResponse, CronJob, FunctionDef, FunctionPermissions, Job } from '@aurabase/core';
 
 declare function isRelayStatus(status: number): boolean;
 /**
@@ -84,6 +84,10 @@ declare class FunctionsService extends BaseService {
         timeout?: number;
         responseType?: FunctionsResponseType;
     }): Promise<AuraResponse<T>>;
+    /**
+     * Liste les fonctions déployées du projet, avec leur code source et leurs variables.
+     * Exige une clé `service_role` : une clé publique reçoit `403`.
+     */
     list(): Promise<AuraResponse<FunctionDef[]>>;
     /**
      * Lit une fonction par son **nom** ou par son **identifiant** (B10).
@@ -93,10 +97,15 @@ declare class FunctionsService extends BaseService {
      * le NOM l'emporte. Une valeur qui n'est ni l'un ni l'autre produit un 404 qui le dit.
      */
     get(nameOrId: string): Promise<AuraResponse<FunctionDef>>;
+    /**
+     * Liste les jobs asynchrones du projet, filtrés par `status` (`pending`, `running`, `completed`,
+     * `failed`, `dead`). `limit` va de 1 à 500 (50 par défaut). Exige une clé `service_role`.
+     */
     listJobs(options?: {
         status?: string;
         limit?: number;
     }): Promise<AuraResponse<Job[]>>;
+    /** Lit un job par son identifiant. Exige une clé `service_role`. */
     getJob(jobId: string): Promise<AuraResponse<Job>>;
     /**
      * Enfile un job d'exécution asynchrone en arrière-plan pour une fonction.
@@ -110,10 +119,20 @@ declare class FunctionsService extends BaseService {
         delaySecs?: number;
         maxAttempts?: number;
     }): Promise<AuraResponse<Job>>;
+    /** Liste les tâches cron du projet. Exige une clé `service_role`. */
     listCronJobs(): Promise<AuraResponse<CronJob[]>>;
+    /**
+     * Crée une tâche cron : à chaque échéance, un job est mis en file pour `functionName`.
+     * `schedule` compte 5 champs (`min heure jour mois jour-semaine`) ou 6 (avec les secondes), en UTC ;
+     * les alias comme `@daily` sont refusés. Le `payload` est figé à la création. Exige une clé `service_role`.
+     */
     createCronJob(name: string, schedule: string, functionName: string, options?: {
         payload?: unknown;
     }): Promise<AuraResponse<CronJob>>;
+    /**
+     * Supprime une tâche cron par son NOM (et non son identifiant) ; un nom inconnu renvoie 404.
+     * La tâche cesse aussi de se déclencher. Exige une clé `service_role`.
+     */
     deleteCronJob(name: string): Promise<AuraResponse<null>>;
 }
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { AuraError, BaseService, AuraClientLike, AuraResponse, FunctionDef, Job, CronJob } from '@aurabase/core';
-export { AuraResponse, CronJob, FunctionDef, Job } from '@aurabase/core';
+export { AuraResponse, CronJob, FunctionDef, FunctionPermissions, Job } from '@aurabase/core';
 
 declare function isRelayStatus(status: number): boolean;
 /**
@@ -84,6 +84,10 @@ declare class FunctionsService extends BaseService {
         timeout?: number;
         responseType?: FunctionsResponseType;
     }): Promise<AuraResponse<T>>;
+    /**
+     * Liste les fonctions déployées du projet, avec leur code source et leurs variables.
+     * Exige une clé `service_role` : une clé publique reçoit `403`.
+     */
     list(): Promise<AuraResponse<FunctionDef[]>>;
     /**
      * Lit une fonction par son **nom** ou par son **identifiant** (B10).
@@ -93,10 +97,15 @@ declare class FunctionsService extends BaseService {
      * le NOM l'emporte. Une valeur qui n'est ni l'un ni l'autre produit un 404 qui le dit.
      */
     get(nameOrId: string): Promise<AuraResponse<FunctionDef>>;
+    /**
+     * Liste les jobs asynchrones du projet, filtrés par `status` (`pending`, `running`, `completed`,
+     * `failed`, `dead`). `limit` va de 1 à 500 (50 par défaut). Exige une clé `service_role`.
+     */
     listJobs(options?: {
         status?: string;
         limit?: number;
     }): Promise<AuraResponse<Job[]>>;
+    /** Lit un job par son identifiant. Exige une clé `service_role`. */
     getJob(jobId: string): Promise<AuraResponse<Job>>;
     /**
      * Enfile un job d'exécution asynchrone en arrière-plan pour une fonction.
@@ -110,10 +119,20 @@ declare class FunctionsService extends BaseService {
         delaySecs?: number;
         maxAttempts?: number;
     }): Promise<AuraResponse<Job>>;
+    /** Liste les tâches cron du projet. Exige une clé `service_role`. */
     listCronJobs(): Promise<AuraResponse<CronJob[]>>;
+    /**
+     * Crée une tâche cron : à chaque échéance, un job est mis en file pour `functionName`.
+     * `schedule` compte 5 champs (`min heure jour mois jour-semaine`) ou 6 (avec les secondes), en UTC ;
+     * les alias comme `@daily` sont refusés. Le `payload` est figé à la création. Exige une clé `service_role`.
+     */
     createCronJob(name: string, schedule: string, functionName: string, options?: {
         payload?: unknown;
     }): Promise<AuraResponse<CronJob>>;
+    /**
+     * Supprime une tâche cron par son NOM (et non son identifiant) ; un nom inconnu renvoie 404.
+     * La tâche cesse aussi de se déclencher. Exige une clé `service_role`.
+     */
     deleteCronJob(name: string): Promise<AuraResponse<null>>;
 }
 

package/dist/index.js

@@ -1,4 +1,4 @@
-import { AuraError, BaseService, isTokenExpired, refreshOnce, isAbortError } from '@aurabase/core';
+import { AuraError, BaseService, DEFAULT_REQUEST_TIMEOUT_MS, isTokenExpired, refreshOnce, isAbortError } from '@aurabase/core';
 
 // src/errors.ts
 var RELAY_STATUSES = /* @__PURE__ */ new Set([502, 503, 504]);
@@ -25,7 +25,31 @@ var FunctionsRelayError = class _FunctionsRelayError extends AuraError {
 };
 function toFunctionsError(err, context) {
   const body = err.details != null ? err.details : { error: { code: err.code, message: err.message } };
-  return isRelayStatus(err.status) ? new FunctionsRelayError(err.status, body, context ?? err.details) : new FunctionsHttpError(err.status, body, context ?? err.details);
+  return isRelayStatus(err.status) ? new FunctionsRelayError(err.status, body, err.details) : new FunctionsHttpError(err.status, body, err.details);
+}
+var INVOKE_ORIGIN_HEADER = "x-aurabase-invoke-origin";
+var seg = encodeURIComponent;
+function unserializableBodyKind(body) {
+  if (body === null || typeof body !== "object") return null;
+  const g = globalThis;
+  for (const name of ["Blob", "FormData", "URLSearchParams", "ReadableStream"]) {
+    const ctor = g[name];
+    if (typeof ctor === "function" && body instanceof ctor) return name;
+  }
+  if (body instanceof ArrayBuffer) return "ArrayBuffer";
+  if (ArrayBuffer.isView(body)) return body.constructor.name;
+  return null;
+}
+function envelopeContentType(headers) {
+  if (headers === null || typeof headers !== "object") return void 0;
+  for (const [k, v] of Object.entries(headers)) {
+    if (k.toLowerCase() === "content-type" && typeof v === "string") return v.toLowerCase();
+  }
+  return void 0;
+}
+function isTextual(contentType) {
+  if (!contentType) return true;
+  return contentType.includes("json") || contentType.startsWith("text/") || contentType.includes("xml");
 }
 var FunctionsService = class extends BaseService {
   constructor(client) {
@@ -72,11 +96,26 @@ var FunctionsService = class extends BaseService {
    * `signal` produisent le code `timeout`.
    */
   async invoke(slug, options) {
+    const badBody = unserializableBodyKind(options?.body);
+    if (badBody) {
+      return {
+        data: null,
+        error: new AuraError(0, {
+          error: {
+            code: "invalid_body",
+            message: `Le corps d'invocation doit \xEAtre s\xE9rialisable en JSON (objet, tableau, cha\xEEne, nombre, bool\xE9en) : un ${badBody} serait transmis vide ou d\xE9form\xE9. Encodez-le (par exemple en base64) ou passez par Storage.`
+          }
+        })
+      };
+    }
+    const responseType = options?.responseType ?? "json";
     const controller = new AbortController();
     let timeoutId;
     const userSignal = options?.signal;
     const onAbort = () => controller.abort();
-    if (options?.timeout) timeoutId = setTimeout(() => controller.abort(), options.timeout);
+    const clientTimeout = this.client.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const timeoutMs = options?.timeout || (responseType !== "json" && userSignal === void 0 && clientTimeout > 0 ? clientTimeout : 0);
+    if (timeoutMs) timeoutId = setTimeout(() => controller.abort(), timeoutMs);
     if (userSignal) {
       if (userSignal.aborted) controller.abort();
       else userSignal.addEventListener("abort", onAbort, { once: true });
@@ -91,7 +130,6 @@ var FunctionsService = class extends BaseService {
       headers: options?.headers,
       body: options?.body
     };
-    const responseType = options?.responseType ?? "json";
     const timeoutError = () => ({
       data: null,
       error: new AuraError(0, {
@@ -101,7 +139,7 @@ var FunctionsService = class extends BaseService {
     try {
       if (responseType === "json") {
         const hasCanceller = options?.timeout !== void 0 || userSignal !== void 0;
-        const res2 = await this.request("POST", `${this.prefix}/${slug}/invoke`, envelope, {
+        const res2 = await this.request("POST", `${this.prefix}/${seg(slug)}/invoke`, envelope, {
           ...hasCanceller ? { signal: controller.signal } : {}
         });
         if (res2.error && controller.signal.aborted) return timeoutError();
@@ -111,7 +149,7 @@ var FunctionsService = class extends BaseService {
           const invokeStatus = rawData.status;
           const invokeBody = rawData.body;
           if (typeof invokeStatus === "number" && invokeStatus >= 400) {
-            const errPayload = typeof invokeBody === "object" && invokeBody !== null ? invokeBody : { message: String(invokeBody) };
+            const errPayload = typeof invokeBody === "object" && invokeBody !== null ? invokeBody : invokeBody === null || invokeBody === void 0 || invokeBody === "" ? {} : { message: typeof invokeBody === "string" ? invokeBody : JSON.stringify(invokeBody) };
             const errorMsg = typeof errPayload.message === "string" ? errPayload.message : typeof errPayload.error === "string" ? errPayload.error : typeof errPayload.error?.message === "string" ? String(errPayload.error.message) : `Function returned HTTP ${invokeStatus}`;
             const normalizedBody = {
               ...errPayload,
@@ -123,10 +161,21 @@ var FunctionsService = class extends BaseService {
             };
             return {
               data: null,
-              error: toFunctionsError(new AuraError(invokeStatus, normalizedBody), invokeBody)
+              error: new FunctionsHttpError(invokeStatus, normalizedBody, invokeBody)
             };
           }
-          let unwrappedData = invokeBody;
+          if (invokeBody === null && invokeStatus !== 204 && !isTextual(envelopeContentType(rawData.headers))) {
+            return {
+              data: null,
+              error: new AuraError(0, {
+                error: {
+                  code: "invalid_response",
+                  message: `La fonction a r\xE9pondu un contenu binaire (HTTP ${invokeStatus}) que le mode JSON ne peut pas transmettre : utilisez responseType 'blob' ou 'arrayBuffer'.`
+                }
+              })
+            };
+          }
+          const unwrappedData = invokeBody;
           if (unwrappedData !== null && typeof unwrappedData === "object") {
             if (!("body" in unwrappedData)) {
               Object.defineProperty(unwrappedData, "body", {
@@ -164,19 +213,34 @@ var FunctionsService = class extends BaseService {
       };
       if (store.token) headers["Authorization"] = `Bearer ${store.token}`;
       if (client.apiKey) headers["apikey"] = client.apiKey;
-      const res = await client.fetchFn(this.url(`${this.prefix}/${slug}/invoke`), {
+      const res = await client.fetchFn(this.url(`${this.prefix}/${seg(slug)}/invoke`), {
         method: "POST",
         headers,
         body: JSON.stringify(envelope),
         signal: controller.signal
       });
       if (!res.ok) {
+        let text = "";
+        try {
+          text = await res.text();
+        } catch (e) {
+          if (controller.signal.aborted || isAbortError(e)) throw e;
+        }
         let parsed = null;
         try {
-          parsed = await res.json();
+          parsed = text.trim() ? JSON.parse(text) : null;
         } catch {
         }
-        return { data: null, error: toFunctionsError(new AuraError(res.status, parsed)) };
+        const isObject = parsed !== null && typeof parsed === "object";
+        const stringError = isObject && typeof parsed.error === "string" ? parsed.error : void 0;
+        const body = isObject ? stringError !== void 0 && typeof parsed.message !== "string" ? { ...parsed, message: stringError } : parsed : text.trim() ? { message: text } : null;
+        if (res.headers.get(INVOKE_ORIGIN_HEADER) === "function") {
+          return {
+            data: null,
+            error: new FunctionsHttpError(res.status, body, isObject ? parsed : text || null)
+          };
+        }
+        return { data: null, error: toFunctionsError(new AuraError(res.status, body, res.headers)) };
       }
       let data;
       if (responseType === "text") data = await res.text();
@@ -199,6 +263,10 @@ var FunctionsService = class extends BaseService {
     }
   }
   // -- Function CRUD ----------------------------------------------------------
+  /**
+   * Liste les fonctions déployées du projet, avec leur code source et leurs variables.
+   * Exige une clé `service_role` : une clé publique reçoit `403`.
+   */
   async list() {
     return this.request("GET", `${this.prefix}`);
   }
@@ -210,9 +278,13 @@ var FunctionsService = class extends BaseService {
    * le NOM l'emporte. Une valeur qui n'est ni l'un ni l'autre produit un 404 qui le dit.
    */
   async get(nameOrId) {
-    return this.request("GET", `${this.prefix}/${nameOrId}`);
+    return this.request("GET", `${this.prefix}/${seg(nameOrId)}`);
   }
   // -- Jobs -------------------------------------------------------------------
+  /**
+   * Liste les jobs asynchrones du projet, filtrés par `status` (`pending`, `running`, `completed`,
+   * `failed`, `dead`). `limit` va de 1 à 500 (50 par défaut). Exige une clé `service_role`.
+   */
   async listJobs(options) {
     const params = new URLSearchParams();
     if (options?.status) params.set("status", options.status);
@@ -220,8 +292,9 @@ var FunctionsService = class extends BaseService {
     const qs = params.toString() ? `?${params.toString()}` : "";
     return this.request("GET", `${this.prefix}/jobs${qs}`);
   }
+  /** Lit un job par son identifiant. Exige une clé `service_role`. */
   async getJob(jobId) {
-    return this.request("GET", `${this.prefix}/jobs/${jobId}`);
+    return this.request("GET", `${this.prefix}/jobs/${seg(jobId)}`);
   }
   /**
    * Enfile un job d'exécution asynchrone en arrière-plan pour une fonction.
@@ -247,9 +320,15 @@ var FunctionsService = class extends BaseService {
     });
   }
   // -- Cron -------------------------------------------------------------------
+  /** Liste les tâches cron du projet. Exige une clé `service_role`. */
   async listCronJobs() {
     return this.request("GET", `${this.prefix}/cron`);
   }
+  /**
+   * Crée une tâche cron : à chaque échéance, un job est mis en file pour `functionName`.
+   * `schedule` compte 5 champs (`min heure jour mois jour-semaine`) ou 6 (avec les secondes), en UTC ;
+   * les alias comme `@daily` sont refusés. Le `payload` est figé à la création. Exige une clé `service_role`.
+   */
   async createCronJob(name, schedule, functionName, options) {
     return this.request("POST", `${this.prefix}/cron`, {
       name,
@@ -258,8 +337,12 @@ var FunctionsService = class extends BaseService {
       payload: options?.payload
     });
   }
+  /**
+   * Supprime une tâche cron par son NOM (et non son identifiant) ; un nom inconnu renvoie 404.
+   * La tâche cesse aussi de se déclencher. Exige une clé `service_role`.
+   */
   async deleteCronJob(name) {
-    return this.request("DELETE", `${this.prefix}/cron/${name}`);
+    return this.request("DELETE", `${this.prefix}/cron/${seg(name)}`);
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aurabase/functions",
-  "version": "0.5.4",
+  "version": "0.6.1",
   "description": "Service edge functions du SDK Aurabase (invoke, jobs asynchrones, cron)",
   "type": "module",
   "main": "dist/index.cjs",
@@ -45,7 +45,7 @@
     "functions"
   ],
   "dependencies": {
-    "@aurabase/core": "0.5.4"
+    "@aurabase/core": "0.6.1"
   },
   "devDependencies": {
     "@types/node": "20.14.15",