@aurabase/functions 0.5.2 → 0.5.4

package/README.md

@@ -144,6 +144,14 @@ const { data: parNom } = await aura.functions.get('hello-world')
 ### Jobs asynchrones (extra vs `@supabase/functions-js`)
 
 ```ts
+// Enfiler un nouveau job d'exécution en arrière-plan
+const { data: jobInfo, error } = await aura.functions.enqueueJob('generate-report', {
+  payload: { month: '2026-10', sendEmail: true },
+  maxAttempts: 3,
+  delaySecs: 60, // exécuter dans 60 secondes
+})
+
+// Consulter les jobs
 const { data: jobs } = await aura.functions.listJobs({ status: 'pending', limit: 20 })
 const { data: job } = await aura.functions.getJob(jobs![0]!.id)
 ```
@@ -159,14 +167,19 @@ const { data: crons } = await aura.functions.listCronJobs()
 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.
+- **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.
+
 ## Limitations
 
-- Pas de streaming de réponse : `invoke()` bufferise toujours l'intégralité du corps avant de résoudre (pas de lecture incrémentale, pas de réponse SSE/chunked exploitable). `responseType` change le DÉCODAGE du corps bufferisé, pas ce point.
-- Pas de sélection de région d'exécution.
-- `headers` est transmis à la fonction invoquée — ce ne sont pas des headers de transport HTTP (pas de contrôle sur ceux injectés par le pipeline : `apikey`, `Authorization`). La fonction ne voit QUE les en-têtes que vous passez (plus le `content-type` par défaut) : les en-têtes internes du transport ne lui sont pas exposés.
-- Le statut réel de la fonction n'est visible qu'avec un `responseType` autre que `'json'` : en mode `'json'` la réponse est enveloppée et le transport rend toujours HTTP 200 (le statut de la fonction est alors dans `data.status`).
-- Pas de `getCronJob()` ni `updateCronJob()` : seuls `listCronJobs`, `createCronJob` et `deleteCronJob` sont exposés. Pas de `deploy()` / `delete()` de fonction depuis le SDK : le déploiement passe par l'API HTTP, la CLI `aura functions deploy` ou le Studio.
-- `deleteCronJob(name)` et les routes `PATCH`/`DELETE`/`invoke` d'une fonction attendent un **nom** ; seul `get()` accepte aussi l'identifiant.
+- Pas de streaming de réponse : `invoke()` bufferise l'intégralité du corps avant de résoudre. `responseType` configure le décodage du corps (`json`, `text`, `blob`, `arrayBuffer`).
+- Pas de sélection de région d'exécution (exécution sur le cluster Edge actif).
+- Les en-têtes de cadrage de transport (`content-length`, `connection`, `host`, etc.) ne sont pas transmissibles à la fonction.
+- Pas de `getCronJob()` ni `updateCronJob()` : seuls `listCronJobs`, `createCronJob` et `deleteCronJob` sont exposés. Le déploiement s'effectue via le CLI `aura functions deploy` ou Aurabase Studio.
 
 ## Documentation
 

package/dist/index.cjs

@@ -27,7 +27,7 @@ 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, err.details) : new FunctionsHttpError(err.status, body, err.details);
+  return isRelayStatus(err.status) ? new FunctionsRelayError(err.status, body, context ?? err.details) : new FunctionsHttpError(err.status, body, context ?? err.details);
 }
 var FunctionsService = class extends core.BaseService {
   constructor(client) {
@@ -108,6 +108,47 @@ var FunctionsService = class extends core.BaseService {
         });
         if (res2.error && controller.signal.aborted) return timeoutError();
         if (res2.error) return { data: null, error: toFunctionsError(res2.error) };
+        const rawData = res2.data;
+        if (rawData && typeof rawData === "object" && "body" in rawData && "status" in rawData) {
+          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 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,
+              message: errorMsg,
+              error: {
+                code: typeof errPayload.code === "string" ? errPayload.code : `http_${invokeStatus}`,
+                message: errorMsg
+              }
+            };
+            return {
+              data: null,
+              error: toFunctionsError(new core.AuraError(invokeStatus, normalizedBody), invokeBody)
+            };
+          }
+          let unwrappedData = invokeBody;
+          if (unwrappedData !== null && typeof unwrappedData === "object") {
+            if (!("body" in unwrappedData)) {
+              Object.defineProperty(unwrappedData, "body", {
+                value: unwrappedData,
+                enumerable: false,
+                writable: true,
+                configurable: true
+              });
+            }
+            if (!("status" in unwrappedData)) {
+              Object.defineProperty(unwrappedData, "status", {
+                value: invokeStatus,
+                enumerable: false,
+                writable: true,
+                configurable: true
+              });
+            }
+          }
+          return { data: unwrappedData, error: null, meta: res2.meta };
+        }
         return res2;
       }
       const client = this.client;
@@ -184,6 +225,29 @@ var FunctionsService = class extends core.BaseService {
   async getJob(jobId) {
     return this.request("GET", `${this.prefix}/jobs/${jobId}`);
   }
+  /**
+   * Enfile un job d'exécution asynchrone en arrière-plan pour une fonction.
+   *
+   * @param functionName Nom de la fonction à exécuter.
+   * @param options Paramètres optionnels : charge utile (`payload`), délai avant exécution (`delaySecs`)
+   *                et nombre maximum de tentatives (`maxAttempts`).
+   */
+  async enqueueJob(functionName, options) {
+    if (!functionName || typeof functionName !== "string" || functionName.trim() === "") {
+      return {
+        data: null,
+        error: new core.AuraError(400, {
+          error: { code: "bad_request", message: "Function name is required to enqueue a job" }
+        })
+      };
+    }
+    return this.request("POST", `${this.prefix}/jobs`, {
+      function_name: functionName.trim(),
+      payload: options?.payload,
+      delay_secs: options?.delaySecs,
+      max_attempts: options?.maxAttempts
+    });
+  }
   // -- Cron -------------------------------------------------------------------
   async listCronJobs() {
     return this.request("GET", `${this.prefix}/cron`);

package/dist/index.d.cts

@@ -98,6 +98,18 @@ declare class FunctionsService extends BaseService {
         limit?: number;
     }): Promise<AuraResponse<Job[]>>;
     getJob(jobId: string): Promise<AuraResponse<Job>>;
+    /**
+     * Enfile un job d'exécution asynchrone en arrière-plan pour une fonction.
+     *
+     * @param functionName Nom de la fonction à exécuter.
+     * @param options Paramètres optionnels : charge utile (`payload`), délai avant exécution (`delaySecs`)
+     *                et nombre maximum de tentatives (`maxAttempts`).
+     */
+    enqueueJob(functionName: string, options?: {
+        payload?: unknown;
+        delaySecs?: number;
+        maxAttempts?: number;
+    }): Promise<AuraResponse<Job>>;
     listCronJobs(): Promise<AuraResponse<CronJob[]>>;
     createCronJob(name: string, schedule: string, functionName: string, options?: {
         payload?: unknown;

package/dist/index.d.ts

@@ -98,6 +98,18 @@ declare class FunctionsService extends BaseService {
         limit?: number;
     }): Promise<AuraResponse<Job[]>>;
     getJob(jobId: string): Promise<AuraResponse<Job>>;
+    /**
+     * Enfile un job d'exécution asynchrone en arrière-plan pour une fonction.
+     *
+     * @param functionName Nom de la fonction à exécuter.
+     * @param options Paramètres optionnels : charge utile (`payload`), délai avant exécution (`delaySecs`)
+     *                et nombre maximum de tentatives (`maxAttempts`).
+     */
+    enqueueJob(functionName: string, options?: {
+        payload?: unknown;
+        delaySecs?: number;
+        maxAttempts?: number;
+    }): Promise<AuraResponse<Job>>;
     listCronJobs(): Promise<AuraResponse<CronJob[]>>;
     createCronJob(name: string, schedule: string, functionName: string, options?: {
         payload?: unknown;

package/dist/index.js

@@ -25,7 +25,7 @@ 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, err.details) : new FunctionsHttpError(err.status, body, err.details);
+  return isRelayStatus(err.status) ? new FunctionsRelayError(err.status, body, context ?? err.details) : new FunctionsHttpError(err.status, body, context ?? err.details);
 }
 var FunctionsService = class extends BaseService {
   constructor(client) {
@@ -106,6 +106,47 @@ var FunctionsService = class extends BaseService {
         });
         if (res2.error && controller.signal.aborted) return timeoutError();
         if (res2.error) return { data: null, error: toFunctionsError(res2.error) };
+        const rawData = res2.data;
+        if (rawData && typeof rawData === "object" && "body" in rawData && "status" in rawData) {
+          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 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,
+              message: errorMsg,
+              error: {
+                code: typeof errPayload.code === "string" ? errPayload.code : `http_${invokeStatus}`,
+                message: errorMsg
+              }
+            };
+            return {
+              data: null,
+              error: toFunctionsError(new AuraError(invokeStatus, normalizedBody), invokeBody)
+            };
+          }
+          let unwrappedData = invokeBody;
+          if (unwrappedData !== null && typeof unwrappedData === "object") {
+            if (!("body" in unwrappedData)) {
+              Object.defineProperty(unwrappedData, "body", {
+                value: unwrappedData,
+                enumerable: false,
+                writable: true,
+                configurable: true
+              });
+            }
+            if (!("status" in unwrappedData)) {
+              Object.defineProperty(unwrappedData, "status", {
+                value: invokeStatus,
+                enumerable: false,
+                writable: true,
+                configurable: true
+              });
+            }
+          }
+          return { data: unwrappedData, error: null, meta: res2.meta };
+        }
         return res2;
       }
       const client = this.client;
@@ -182,6 +223,29 @@ var FunctionsService = class extends BaseService {
   async getJob(jobId) {
     return this.request("GET", `${this.prefix}/jobs/${jobId}`);
   }
+  /**
+   * Enfile un job d'exécution asynchrone en arrière-plan pour une fonction.
+   *
+   * @param functionName Nom de la fonction à exécuter.
+   * @param options Paramètres optionnels : charge utile (`payload`), délai avant exécution (`delaySecs`)
+   *                et nombre maximum de tentatives (`maxAttempts`).
+   */
+  async enqueueJob(functionName, options) {
+    if (!functionName || typeof functionName !== "string" || functionName.trim() === "") {
+      return {
+        data: null,
+        error: new AuraError(400, {
+          error: { code: "bad_request", message: "Function name is required to enqueue a job" }
+        })
+      };
+    }
+    return this.request("POST", `${this.prefix}/jobs`, {
+      function_name: functionName.trim(),
+      payload: options?.payload,
+      delay_secs: options?.delaySecs,
+      max_attempts: options?.maxAttempts
+    });
+  }
   // -- Cron -------------------------------------------------------------------
   async listCronJobs() {
     return this.request("GET", `${this.prefix}/cron`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aurabase/functions",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "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.2"
+    "@aurabase/core": "0.5.4"
   },
   "devDependencies": {
     "@types/node": "20.14.15",