@aurabase/functions 0.4.1 → 0.5.0

package/README.md

@@ -23,12 +23,12 @@ Dans l'usage courant, `FunctionsService` n'est jamais instancié directement : i
 ```ts
 import { createClient } from '@aurabase/aurabase-js'
 
-const aura = createClient('http://localhost:8080', 'my-project', 'aura_anon_xxx')
+const aura = createClient('https://mon-projet.aurabase.cloud', 'aura_anon_xxx')
 ```
 
 ### Invocation
 
-`invoke<T>()` enveloppe la requête (`{ method, path, headers, body }`) et dé-wrap la réponse JSON du backend — tout est bufferisé, pas de streaming (voir Limitations).
+`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).
 
 ```ts
 const { data, error } = await aura.functions.invoke<{ ok: boolean }>('hello-world', {
@@ -42,7 +42,7 @@ if (!data) throw new Error('réponse vide')
 console.log(data.ok)
 ```
 
-Options complètes : `method`, `path` (sous-route à l'intérieur de la fonction), `headers` (transmis à la fonction elle-même, pas des headers de transport), `signal`, `timeout`.
+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`.
 
 ```ts
 const controller = new AbortController()
@@ -61,11 +61,84 @@ if (error?.code === 'timeout') {
 }
 ```
 
+#### Ce que la fonction reçoit
+
+`method`, `path`, `headers` et `body` décrivent la requête **vue par votre fonction** — pas le transport HTTP vers Aurabase :
+
+```ts
+await aura.functions.invoke('items', {
+  method: 'PUT',
+  path: '/items/1',
+  headers: { 'x-request-source': 'sdk' },
+  body: { qty: 2 },
+})
+```
+
+```ts
+// items.ts (runtime Deno)
+Deno.serve(async (req) => {
+  req.method                            // 'PUT'
+  new URL(req.url).pathname             // '/items/1'
+  req.headers.get('x-request-source')   // 'sdk'
+  await req.json()                      // { qty: 2 }  ← le corps, PAS une enveloppe
+  return new Response('ok')
+})
+```
+
+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.
+
+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.
+
+Les en-têtes de cadrage/transport (`content-length`, `transfer-encoding`, `connection`, `keep-alive`, `upgrade`, `host`…) passés dans `headers` sont ignorés : ils décrivent le message, pas la requête applicative, et un `content-length` forgé désynchroniserait la lecture du corps.
+
+> **Changement de comportement (correctif C20).** Jusqu'à ce correctif, une fonction Deno recevait invariablement un `POST /invoke/{project_id}/{name}` dont le corps était l'enveloppe `{ method, path, headers, body }`. Une fonction écrite contre cet ancien comportement (`const { body } = await req.json()`) doit être ajustée : lisez désormais `await req.json()` directement. Les modèles de fonctions du Studio et les exemples de ce README étaient déjà écrits selon le contrat correct — ils ne fonctionnaient donc pas avant ce correctif.
+
+#### 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 :
+
+```ts
+const { data: csv } = await aura.functions.invoke<string>('export', { responseType: 'text' })
+const { data: png } = await aura.functions.invoke<Blob>('render', { responseType: 'blob' })
+const { data: buf } = await aura.functions.invoke<ArrayBuffer>('pdf', { responseType: 'arrayBuffer' })
+```
+
+#### Erreurs typées
+
+Parité `@supabase/functions-js`. Les deux classes sous-classent `AuraError` (donc `isAuraError()`, `status`, `code` restent valides) :
+
+| 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 |
+
+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.
+
+```ts
+import { FunctionsHttpError, FunctionsRelayError, isRelayStatus } from '@aurabase/functions'
+
+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
+} 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.
+
 ### Fonctions (métadonnées)
 
+`get()` accepte le **nom** ou l'**identifiant** (B10) — en cas d'homonymie, le nom l'emporte :
+
 ```ts
 const { data: fns } = await aura.functions.list()
-const { data: fn } = await aura.functions.get(fns![0]!.id)
+const { data: parId } = await aura.functions.get(fns![0]!.id)
+const { data: parNom } = await aura.functions.get('hello-world')
 ```
 
 ### Jobs asynchrones (extra vs `@supabase/functions-js`)
@@ -88,11 +161,12 @@ await aura.functions.deleteCronJob('nightly-cleanup')
 
 ## Limitations
 
-- Pas de streaming de réponse : `invoke()` bufferise toujours l'intégralité du corps JSON avant de résoudre (pas de lecture incrémentale, pas de réponse SSE/chunked exploitable).
-- Pas de `responseType` (`json`/`text`/`blob`) : la réponse est toujours parsée comme JSON puis dé-wrappée (`{data}` → contenu).
+- 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 tel quel à 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`, `Content-Type`).
-- Pas de `getCronJob()` ni `updateCronJob()` : seuls `listCronJobs`, `createCronJob` et `deleteCronJob` sont exposés.
+- `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.
 
 ## Documentation
 

package/dist/index.cjs

@@ -2,7 +2,7 @@
 
 var core = require('@aurabase/core');
 
-// src/FunctionsService.ts
+// src/errors.ts
 var RELAY_STATUSES = /* @__PURE__ */ new Set([502, 503, 504]);
 function isRelayStatus(status) {
   return status === 0 || RELAY_STATUSES.has(status);
@@ -29,19 +29,36 @@ 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);
 }
-
-// src/FunctionsService.ts
 var FunctionsService = class extends core.BaseService {
   constructor(client) {
     super(client);
   }
+  /**
+   * Préfixe des routes de ce service. Aucun identifiant de projet : il est injecté par
+   * la passerelle depuis le sous-domaine du projet (`inject_project_id`,
+   * `services/aura-gateway/src/middleware/project_subdomain.rs`).
+   */
   get prefix() {
-    return `/v1/functions/${this.client.projectId}`;
+    return "/v1/functions";
   }
   // -- Function invocation ----------------------------------------------------
   /**
    * Invoque une edge function.
    *
+   * Ce que la fonction REÇOIT (C20) : la requête vue par votre code est celle que vous
+   * décrivez ici — `method` (défaut `POST`), `path` (défaut `/`), `headers` et `body`
+   * APPLICATIF. Sur le runtime Deno :
+   *
+   * ```ts
+   * // invoke('x', { method: 'PUT', path: '/items/1', headers: { 'x-src': 'sdk' }, body: { a: 1 } })
+   * Deno.serve(async (req) => {
+   *   req.method                  // 'PUT'
+   *   new URL(req.url).pathname   // '/items/1'
+   *   req.headers.get('x-src')    // 'sdk'
+   *   await req.json()            // { a: 1 }   ← le corps, PAS l'enveloppe
+   * })
+   * ```
+   *
    * `responseType` (parité `@supabase/functions-js`, défaut `'json'`) :
    *  - `'json'` : chemin PIPELINE inchangé (refresh proactif centralisé, injection
    *    apikey/Authorization, dé-wrapping `{data,meta}`, retryConfig). Non-régression.
@@ -52,8 +69,9 @@ var FunctionsService = class extends core.BaseService {
    *
    * Erreurs typées (parité) : une réponse HTTP non-2xx → `FunctionsHttpError`, une
    * panne de relais/infra (réseau, 502/503/504) → `FunctionsRelayError` ; les deux
-   * sous-classent `AuraError` (rétrocompat `isAuraError`/champ `error`). `timeout`/
-   * `signal` continuent de produire le code `timeout`.
+   * sous-classent `AuraError`, ce qui est l'invariant du typage d'erreur du SDK :
+   * `isAuraError` reste vrai et le champ `error` reste lisible sur les deux. `timeout`/
+   * `signal` produisent le code `timeout`.
    */
   async invoke(slug, options) {
     const controller = new AbortController();
@@ -69,7 +87,12 @@ var FunctionsService = class extends core.BaseService {
       if (timeoutId) clearTimeout(timeoutId);
       if (userSignal) userSignal.removeEventListener("abort", onAbort);
     };
-    const envelope = { method: options?.method, path: options?.path, headers: options?.headers, body: options?.body };
+    const envelope = {
+      method: options?.method,
+      path: options?.path,
+      headers: options?.headers,
+      body: options?.body
+    };
     const responseType = options?.responseType ?? "json";
     const timeoutError = () => ({
       data: null,
@@ -126,7 +149,10 @@ var FunctionsService = class extends core.BaseService {
       return {
         data: null,
         error: new FunctionsRelayError(0, {
-          error: { code: "network_error", message: err instanceof Error ? err.message : "Function relay error" }
+          error: {
+            code: "network_error",
+            message: err instanceof Error ? err.message : "Function relay error"
+          }
         })
       };
     } finally {
@@ -137,8 +163,15 @@ var FunctionsService = class extends core.BaseService {
   async list() {
     return this.request("GET", `${this.prefix}`);
   }
-  async get(id) {
-    return this.request("GET", `${this.prefix}/${id}`);
+  /**
+   * Lit une fonction par son **nom** ou par son **identifiant** (B10).
+   *
+   * Les deux clés sont acceptées : `list()` renvoie `{ id, name, … }` et les deux sont des
+   * points d'entrée naturels. En cas d'homonymie (une fonction PEUT s'appeler comme un UUID),
+   * 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}`);
   }
   // -- Jobs -------------------------------------------------------------------
   async listJobs(options) {

package/dist/index.d.cts

@@ -1,14 +1,66 @@
-import { BaseService, AuraClientLike, AuraResponse, FunctionDef, Job, CronJob, AuraError } from '@aurabase/core';
+import { AuraError, BaseService, AuraClientLike, AuraResponse, FunctionDef, Job, CronJob } from '@aurabase/core';
 export { AuraResponse, CronJob, FunctionDef, Job } from '@aurabase/core';
 
+declare function isRelayStatus(status: number): boolean;
+/**
+ * Erreur HTTP APPLICATIVE renvoyée par l'invocation d'une edge function
+ * (réponse HTTP non-2xx). Parité `FunctionsHttpError` de `@supabase/functions-js`.
+ * Sous-classe `AuraError` → `isAuraError()` reste vrai, `status` porte le code HTTP.
+ * `context` conserve le corps déjà lu (JSON/texte) pour inspection.
+ */
+declare class FunctionsHttpError extends AuraError {
+    readonly context: unknown;
+    constructor(status: number, body?: {
+        error?: {
+            code?: string;
+            message?: string;
+        };
+        message?: string;
+    } | null, context?: unknown);
+}
+/**
+ * Erreur de RELAIS/infra : fonction injoignable (échec réseau), 502/503/504 de la
+ * passerelle, cold start échoué, corps non exploitable. Parité `FunctionsRelayError`
+ * de `@supabase/functions-js`. Sous-classe `AuraError`.
+ */
+declare class FunctionsRelayError extends AuraError {
+    readonly context: unknown;
+    constructor(status: number, body?: {
+        error?: {
+            code?: string;
+            message?: string;
+        };
+        message?: string;
+    } | null, context?: unknown);
+}
+
 /** Type de réponse attendu de l'invocation (parité `@supabase/functions-js`). */
 type FunctionsResponseType = 'json' | 'text' | 'blob' | 'arrayBuffer';
 declare class FunctionsService extends BaseService {
     constructor(client: AuraClientLike);
+    /**
+     * Préfixe des routes de ce service. Aucun identifiant de projet : il est injecté par
+     * la passerelle depuis le sous-domaine du projet (`inject_project_id`,
+     * `services/aura-gateway/src/middleware/project_subdomain.rs`).
+     */
     private get prefix();
     /**
      * Invoque une edge function.
      *
+     * Ce que la fonction REÇOIT (C20) : la requête vue par votre code est celle que vous
+     * décrivez ici — `method` (défaut `POST`), `path` (défaut `/`), `headers` et `body`
+     * APPLICATIF. Sur le runtime Deno :
+     *
+     * ```ts
+     * // invoke('x', { method: 'PUT', path: '/items/1', headers: { 'x-src': 'sdk' }, body: { a: 1 } })
+     * Deno.serve(async (req) => {
+     *   req.method                  // 'PUT'
+     *   new URL(req.url).pathname   // '/items/1'
+     *   req.headers.get('x-src')    // 'sdk'
+     *   await req.json()            // { a: 1 }   ← le corps, PAS l'enveloppe
+     * })
+     * ```
+     *
      * `responseType` (parité `@supabase/functions-js`, défaut `'json'`) :
      *  - `'json'` : chemin PIPELINE inchangé (refresh proactif centralisé, injection
      *    apikey/Authorization, dé-wrapping `{data,meta}`, retryConfig). Non-régression.
@@ -19,8 +71,9 @@ declare class FunctionsService extends BaseService {
      *
      * Erreurs typées (parité) : une réponse HTTP non-2xx → `FunctionsHttpError`, une
      * panne de relais/infra (réseau, 502/503/504) → `FunctionsRelayError` ; les deux
-     * sous-classent `AuraError` (rétrocompat `isAuraError`/champ `error`). `timeout`/
-     * `signal` continuent de produire le code `timeout`.
+     * sous-classent `AuraError`, ce qui est l'invariant du typage d'erreur du SDK :
+     * `isAuraError` reste vrai et le champ `error` reste lisible sur les deux. `timeout`/
+     * `signal` produisent le code `timeout`.
      */
     invoke<T = unknown>(slug: string, options?: {
         body?: unknown;
@@ -32,7 +85,14 @@ declare class FunctionsService extends BaseService {
         responseType?: FunctionsResponseType;
     }): Promise<AuraResponse<T>>;
     list(): Promise<AuraResponse<FunctionDef[]>>;
-    get(id: string): Promise<AuraResponse<FunctionDef>>;
+    /**
+     * Lit une fonction par son **nom** ou par son **identifiant** (B10).
+     *
+     * Les deux clés sont acceptées : `list()` renvoie `{ id, name, … }` et les deux sont des
+     * points d'entrée naturels. En cas d'homonymie (une fonction PEUT s'appeler comme un UUID),
+     * 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>>;
     listJobs(options?: {
         status?: string;
         limit?: number;
@@ -45,37 +105,4 @@ declare class FunctionsService extends BaseService {
     deleteCronJob(name: string): Promise<AuraResponse<null>>;
 }
 
-declare function isRelayStatus(status: number): boolean;
-/**
- * Erreur HTTP APPLICATIVE renvoyée par l'invocation d'une edge function
- * (réponse HTTP non-2xx). Parité `FunctionsHttpError` de `@supabase/functions-js`.
- * Sous-classe `AuraError` → `isAuraError()` reste vrai, `status` porte le code HTTP.
- * `context` conserve le corps déjà lu (JSON/texte) pour inspection.
- */
-declare class FunctionsHttpError extends AuraError {
-    readonly context: unknown;
-    constructor(status: number, body?: {
-        error?: {
-            code?: string;
-            message?: string;
-        };
-        message?: string;
-    } | null, context?: unknown);
-}
-/**
- * Erreur de RELAIS/infra : fonction injoignable (échec réseau), 502/503/504 de la
- * passerelle, cold start échoué, corps non exploitable. Parité `FunctionsRelayError`
- * de `@supabase/functions-js`. Sous-classe `AuraError`.
- */
-declare class FunctionsRelayError extends AuraError {
-    readonly context: unknown;
-    constructor(status: number, body?: {
-        error?: {
-            code?: string;
-            message?: string;
-        };
-        message?: string;
-    } | null, context?: unknown);
-}
-
 export { FunctionsHttpError, FunctionsRelayError, type FunctionsResponseType, FunctionsService, isRelayStatus };

package/dist/index.d.ts

@@ -1,14 +1,66 @@
-import { BaseService, AuraClientLike, AuraResponse, FunctionDef, Job, CronJob, AuraError } from '@aurabase/core';
+import { AuraError, BaseService, AuraClientLike, AuraResponse, FunctionDef, Job, CronJob } from '@aurabase/core';
 export { AuraResponse, CronJob, FunctionDef, Job } from '@aurabase/core';
 
+declare function isRelayStatus(status: number): boolean;
+/**
+ * Erreur HTTP APPLICATIVE renvoyée par l'invocation d'une edge function
+ * (réponse HTTP non-2xx). Parité `FunctionsHttpError` de `@supabase/functions-js`.
+ * Sous-classe `AuraError` → `isAuraError()` reste vrai, `status` porte le code HTTP.
+ * `context` conserve le corps déjà lu (JSON/texte) pour inspection.
+ */
+declare class FunctionsHttpError extends AuraError {
+    readonly context: unknown;
+    constructor(status: number, body?: {
+        error?: {
+            code?: string;
+            message?: string;
+        };
+        message?: string;
+    } | null, context?: unknown);
+}
+/**
+ * Erreur de RELAIS/infra : fonction injoignable (échec réseau), 502/503/504 de la
+ * passerelle, cold start échoué, corps non exploitable. Parité `FunctionsRelayError`
+ * de `@supabase/functions-js`. Sous-classe `AuraError`.
+ */
+declare class FunctionsRelayError extends AuraError {
+    readonly context: unknown;
+    constructor(status: number, body?: {
+        error?: {
+            code?: string;
+            message?: string;
+        };
+        message?: string;
+    } | null, context?: unknown);
+}
+
 /** Type de réponse attendu de l'invocation (parité `@supabase/functions-js`). */
 type FunctionsResponseType = 'json' | 'text' | 'blob' | 'arrayBuffer';
 declare class FunctionsService extends BaseService {
     constructor(client: AuraClientLike);
+    /**
+     * Préfixe des routes de ce service. Aucun identifiant de projet : il est injecté par
+     * la passerelle depuis le sous-domaine du projet (`inject_project_id`,
+     * `services/aura-gateway/src/middleware/project_subdomain.rs`).
+     */
     private get prefix();
     /**
      * Invoque une edge function.
      *
+     * Ce que la fonction REÇOIT (C20) : la requête vue par votre code est celle que vous
+     * décrivez ici — `method` (défaut `POST`), `path` (défaut `/`), `headers` et `body`
+     * APPLICATIF. Sur le runtime Deno :
+     *
+     * ```ts
+     * // invoke('x', { method: 'PUT', path: '/items/1', headers: { 'x-src': 'sdk' }, body: { a: 1 } })
+     * Deno.serve(async (req) => {
+     *   req.method                  // 'PUT'
+     *   new URL(req.url).pathname   // '/items/1'
+     *   req.headers.get('x-src')    // 'sdk'
+     *   await req.json()            // { a: 1 }   ← le corps, PAS l'enveloppe
+     * })
+     * ```
+     *
      * `responseType` (parité `@supabase/functions-js`, défaut `'json'`) :
      *  - `'json'` : chemin PIPELINE inchangé (refresh proactif centralisé, injection
      *    apikey/Authorization, dé-wrapping `{data,meta}`, retryConfig). Non-régression.
@@ -19,8 +71,9 @@ declare class FunctionsService extends BaseService {
      *
      * Erreurs typées (parité) : une réponse HTTP non-2xx → `FunctionsHttpError`, une
      * panne de relais/infra (réseau, 502/503/504) → `FunctionsRelayError` ; les deux
-     * sous-classent `AuraError` (rétrocompat `isAuraError`/champ `error`). `timeout`/
-     * `signal` continuent de produire le code `timeout`.
+     * sous-classent `AuraError`, ce qui est l'invariant du typage d'erreur du SDK :
+     * `isAuraError` reste vrai et le champ `error` reste lisible sur les deux. `timeout`/
+     * `signal` produisent le code `timeout`.
      */
     invoke<T = unknown>(slug: string, options?: {
         body?: unknown;
@@ -32,7 +85,14 @@ declare class FunctionsService extends BaseService {
         responseType?: FunctionsResponseType;
     }): Promise<AuraResponse<T>>;
     list(): Promise<AuraResponse<FunctionDef[]>>;
-    get(id: string): Promise<AuraResponse<FunctionDef>>;
+    /**
+     * Lit une fonction par son **nom** ou par son **identifiant** (B10).
+     *
+     * Les deux clés sont acceptées : `list()` renvoie `{ id, name, … }` et les deux sont des
+     * points d'entrée naturels. En cas d'homonymie (une fonction PEUT s'appeler comme un UUID),
+     * 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>>;
     listJobs(options?: {
         status?: string;
         limit?: number;
@@ -45,37 +105,4 @@ declare class FunctionsService extends BaseService {
     deleteCronJob(name: string): Promise<AuraResponse<null>>;
 }
 
-declare function isRelayStatus(status: number): boolean;
-/**
- * Erreur HTTP APPLICATIVE renvoyée par l'invocation d'une edge function
- * (réponse HTTP non-2xx). Parité `FunctionsHttpError` de `@supabase/functions-js`.
- * Sous-classe `AuraError` → `isAuraError()` reste vrai, `status` porte le code HTTP.
- * `context` conserve le corps déjà lu (JSON/texte) pour inspection.
- */
-declare class FunctionsHttpError extends AuraError {
-    readonly context: unknown;
-    constructor(status: number, body?: {
-        error?: {
-            code?: string;
-            message?: string;
-        };
-        message?: string;
-    } | null, context?: unknown);
-}
-/**
- * Erreur de RELAIS/infra : fonction injoignable (échec réseau), 502/503/504 de la
- * passerelle, cold start échoué, corps non exploitable. Parité `FunctionsRelayError`
- * de `@supabase/functions-js`. Sous-classe `AuraError`.
- */
-declare class FunctionsRelayError extends AuraError {
-    readonly context: unknown;
-    constructor(status: number, body?: {
-        error?: {
-            code?: string;
-            message?: string;
-        };
-        message?: string;
-    } | null, context?: unknown);
-}
-
 export { FunctionsHttpError, FunctionsRelayError, type FunctionsResponseType, FunctionsService, isRelayStatus };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { AuraError, BaseService, isTokenExpired, refreshOnce, isAbortError } from '@aurabase/core';
 
-// src/FunctionsService.ts
+// src/errors.ts
 var RELAY_STATUSES = /* @__PURE__ */ new Set([502, 503, 504]);
 function isRelayStatus(status) {
   return status === 0 || RELAY_STATUSES.has(status);
@@ -27,19 +27,36 @@ 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);
 }
-
-// src/FunctionsService.ts
 var FunctionsService = class extends BaseService {
   constructor(client) {
     super(client);
   }
+  /**
+   * Préfixe des routes de ce service. Aucun identifiant de projet : il est injecté par
+   * la passerelle depuis le sous-domaine du projet (`inject_project_id`,
+   * `services/aura-gateway/src/middleware/project_subdomain.rs`).
+   */
   get prefix() {
-    return `/v1/functions/${this.client.projectId}`;
+    return "/v1/functions";
   }
   // -- Function invocation ----------------------------------------------------
   /**
    * Invoque une edge function.
    *
+   * Ce que la fonction REÇOIT (C20) : la requête vue par votre code est celle que vous
+   * décrivez ici — `method` (défaut `POST`), `path` (défaut `/`), `headers` et `body`
+   * APPLICATIF. Sur le runtime Deno :
+   *
+   * ```ts
+   * // invoke('x', { method: 'PUT', path: '/items/1', headers: { 'x-src': 'sdk' }, body: { a: 1 } })
+   * Deno.serve(async (req) => {
+   *   req.method                  // 'PUT'
+   *   new URL(req.url).pathname   // '/items/1'
+   *   req.headers.get('x-src')    // 'sdk'
+   *   await req.json()            // { a: 1 }   ← le corps, PAS l'enveloppe
+   * })
+   * ```
+   *
    * `responseType` (parité `@supabase/functions-js`, défaut `'json'`) :
    *  - `'json'` : chemin PIPELINE inchangé (refresh proactif centralisé, injection
    *    apikey/Authorization, dé-wrapping `{data,meta}`, retryConfig). Non-régression.
@@ -50,8 +67,9 @@ var FunctionsService = class extends BaseService {
    *
    * Erreurs typées (parité) : une réponse HTTP non-2xx → `FunctionsHttpError`, une
    * panne de relais/infra (réseau, 502/503/504) → `FunctionsRelayError` ; les deux
-   * sous-classent `AuraError` (rétrocompat `isAuraError`/champ `error`). `timeout`/
-   * `signal` continuent de produire le code `timeout`.
+   * sous-classent `AuraError`, ce qui est l'invariant du typage d'erreur du SDK :
+   * `isAuraError` reste vrai et le champ `error` reste lisible sur les deux. `timeout`/
+   * `signal` produisent le code `timeout`.
    */
   async invoke(slug, options) {
     const controller = new AbortController();
@@ -67,7 +85,12 @@ var FunctionsService = class extends BaseService {
       if (timeoutId) clearTimeout(timeoutId);
       if (userSignal) userSignal.removeEventListener("abort", onAbort);
     };
-    const envelope = { method: options?.method, path: options?.path, headers: options?.headers, body: options?.body };
+    const envelope = {
+      method: options?.method,
+      path: options?.path,
+      headers: options?.headers,
+      body: options?.body
+    };
     const responseType = options?.responseType ?? "json";
     const timeoutError = () => ({
       data: null,
@@ -124,7 +147,10 @@ var FunctionsService = class extends BaseService {
       return {
         data: null,
         error: new FunctionsRelayError(0, {
-          error: { code: "network_error", message: err instanceof Error ? err.message : "Function relay error" }
+          error: {
+            code: "network_error",
+            message: err instanceof Error ? err.message : "Function relay error"
+          }
         })
       };
     } finally {
@@ -135,8 +161,15 @@ var FunctionsService = class extends BaseService {
   async list() {
     return this.request("GET", `${this.prefix}`);
   }
-  async get(id) {
-    return this.request("GET", `${this.prefix}/${id}`);
+  /**
+   * Lit une fonction par son **nom** ou par son **identifiant** (B10).
+   *
+   * Les deux clés sont acceptées : `list()` renvoie `{ id, name, … }` et les deux sont des
+   * points d'entrée naturels. En cas d'homonymie (une fonction PEUT s'appeler comme un UUID),
+   * 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}`);
   }
   // -- Jobs -------------------------------------------------------------------
   async listJobs(options) {

package/package.json

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