@aurabase/aurabase-js 0.3.0

package/packages/storage/README.md

@@ -0,0 +1,141 @@
+# @aurabase/storage
+
+Service de stockage objet du SDK Aurabase : buckets, upload/download, copie/déplacement intra-bucket et URLs signées.
+
+![npm](https://img.shields.io/npm/v/@aurabase/storage) ![license](https://img.shields.io/badge/license-MIT-blue)
+
+> Pre-release — pas encore publié sur npm.
+
+Fait partie du SDK **[aurabase](../aurabase)**. Installé automatiquement avec `aurabase` ; ce package est publié séparément pour un usage ciblé / tree-shaking.
+
+## Installation
+
+```bash
+npm i @aurabase/storage
+```
+
+> Dépend de `@aurabase/core`. Déjà inclus si vous utilisez le package `aurabase` — cette installation ciblée sert à composer votre propre client ou à limiter la taille du bundle.
+
+## Usage
+
+`StorageService` est exposé par le client principal sous `aura.storage`.
+
+```ts
+import { createClient } from 'aurabase'
+
+const aura = createClient('http://localhost:8080', 'my-project', 'aura_anon_xxx')
+```
+
+### Buckets
+
+```ts
+const buckets = await aura.storage.listBuckets()
+
+await aura.storage.createBucket('avatars', {
+  public: true,
+  fileSizeLimit: 5 * 1024 * 1024,
+  allowedMimeTypes: ['image/png', 'image/jpeg'],
+})
+
+const bucket = await aura.storage.getBucket('avatars')
+await aura.storage.deleteBucket('avatars')
+```
+
+### Upload, liste, métadonnées
+
+```ts
+declare const file: File
+
+// Le serveur génère la clé (`<uuid>.<ext>`) — réutilisez data.key directement pour download/remove/copy/move.
+const { data } = await aura.storage.upload('avatars', 'photo.png', file, {
+  contentType: 'image/png',
+  upsert: true,
+})
+
+const files = await aura.storage.list('avatars', { prefix: 'users/', limit: 100 })
+
+const metadata = await aura.storage.getMetadata('avatars', data!.key)
+```
+
+### Download — builder paresseux
+
+`download()` ne fait pas de requête tant qu'il n'est pas `await`é ; par défaut il résout un `Blob`. `.asStream()` bascule sur un `ReadableStream`.
+
+```ts
+// Déclenche le fetch et résout { data: Blob, error }
+const { data: blob } = await aura.storage.download('avatars', 'photo.png')
+
+// Variante flux : { data: ReadableStream<Uint8Array>, error }
+const { data: stream } = await aura.storage.download('avatars', 'photo.png').asStream()
+```
+
+### Copie, déplacement, suppression (intra-bucket)
+
+```ts
+await aura.storage.copy('avatars', 'photo.png', 'archive/photo.png')
+await aura.storage.move('avatars', 'archive/photo.png', 'photo.png')
+await aura.storage.remove('avatars', ['photo.png'])
+```
+
+### URLs signées et URL publique
+
+```ts
+const signedDownload = await aura.storage.createSignedUrl('avatars', 'photo.png', 600)
+const signedUpload = await aura.storage.createSignedUploadUrl('avatars', 'photo.png', 300)
+
+// Attention : cette URL EXIGE quand même une clé API — voir Limitations.
+const url = aura.storage.getPublicUrl('avatars', 'photo.png')
+```
+
+## Transformations d'image
+
+`getPublicUrl()`, `download()` et `createSignedUrl()` acceptent une option `{ transform: ImageTransform }` qui déclenche un rendu à la volée côté backend (redimensionnement, recadrage, ré-encodage) :
+
+```ts
+// Redimensionnement + recadrage (fit "cover").
+const thumbnail = aura.storage.getPublicUrl('avatars', 'photo.png', {
+  transform: { width: 200, resize: 'cover' },
+})
+
+// Download d'un dérivé redimensionné, qualité JPEG réduite.
+const { data: blob } = await aura.storage.download('avatars', 'photo.png', {
+  transform: { width: 800, height: 300, quality: 75 },
+})
+
+// URL signée pointant vers un dérivé WebP.
+const signed = await aura.storage.createSignedUrl('avatars', 'photo.png', 600, {
+  transform: { width: 200, format: 'webp' },
+})
+```
+
+`ImageTransform` (`@aurabase/core`) :
+
+```ts
+interface ImageTransform {
+  width?: number
+  height?: number
+  resize?: 'cover' | 'contain' | 'fill'
+  quality?: number
+  format?: 'origin' | 'jpeg' | 'png' | 'webp' | 'gif'
+}
+```
+
+À savoir avant d'activer les transforms en production :
+
+- **Flag projet** : le rendu est **activé par défaut** ; un projet peut le **désactiver** via le paramètre `img_transform_enabled`. Sur un projet où il est désactivé, toute requête avec `transform` échoue en `403` (`image_transform_disabled`).
+- **`quality` ne s'applique qu'au JPEG** : la bibliothèque de rendu backend actuelle ne propose pas d'encodeur WebP *lossy* paramétrable (le WebP produit est *lossless*) ; `quality` est silencieusement ignoré pour `webp`/`png`/`gif` (pas d'erreur).
+- **Borne de dimension** : `width`/`height` sont plafonnés à 2500px côté backend. Au-delà, la requête échoue en `400` (`image_transform_dimension_too_large`).
+- **Cache serveur des dérivés** : chaque combinaison `(fichier, params de transform)` est rendue une fois puis mise en cache côté serveur. La réponse porte un header `x-aura-cache: HIT` (dérivé servi depuis le cache) ou `MISS` (rendu effectué à cette requête) — présent uniquement sur les réponses avec `transform` (ou `Range`), pas sur un download brut sans transform.
+- **Invalidation = limite connue** : le cache des dérivés est purgé seulement lors d'une **suppression définitive** de l'original (purge permanente côté backend). Un **overwrite** (`upload(..., { upsert: true })`) sur la même clé ne purge PAS les dérivés déjà en cache : d'anciens dérivés peuvent continuer à être servis après un upsert tant qu'aucune suppression définitive n'a eu lieu entretemps.
+
+## Limitations
+
+- Pas d'upload résumable / protocole TUS ; `upload()` fait un envoi `multipart/form-data` unique.
+- Pas de `updateBucket()` ni de `emptyBucket()`.
+- `copy()`/`move()` sont **intra-bucket uniquement** (pas de copie/déplacement entre deux buckets différents).
+- Options d'upload limitées à `contentType` et `upsert` (pas de métadonnées personnalisées ni de cache-control).
+- **`getPublicUrl()` ne rend pas le fichier accessible sans authentification** : le gateway exige une clé API (`apikey`/`x-api-key`) sur toutes les routes storage, y compris pour un bucket créé avec `public: true`. Pour un accès partageable sans clé API, utilisez `createSignedUrl()`.
+
+## Documentation
+
+Référence complète du SDK (tous les services, types partagés, SSR) : [README racine](../../README.md).

package/packages/storage/dist/index.cjs

@@ -0,0 +1,333 @@
+'use strict';
+
+var core = require('@aurabase/core');
+
+// src/StorageService.ts
+async function runDownload(fn, extract) {
+  let res;
+  try {
+    res = await fn();
+  } catch (err) {
+    return {
+      data: null,
+      error: new core.AuraError(0, { error: { code: "network_error", message: err instanceof Error ? err.message : "Download failed" } })
+    };
+  }
+  if (!res.ok) return { data: null, error: new core.AuraError(res.status) };
+  return { data: await extract(res), error: null };
+}
+var BlobDownloadBuilder = class {
+  constructor(_fn) {
+    this._fn = _fn;
+  }
+  _fn;
+  _promise = null;
+  asStream() {
+    return new StreamDownloadBuilder(this._fn);
+  }
+  _run() {
+    if (!this._promise) this._promise = runDownload(this._fn, (r) => r.blob());
+    return this._promise;
+  }
+  then(onfulfilled, onrejected) {
+    return this._run().then(onfulfilled, onrejected);
+  }
+};
+var StreamDownloadBuilder = class {
+  constructor(_fn) {
+    this._fn = _fn;
+  }
+  _fn;
+  _promise = null;
+  _run() {
+    if (!this._promise) {
+      this._promise = runDownload(this._fn, (r) => r.body);
+    }
+    return this._promise;
+  }
+  then(onfulfilled, onrejected) {
+    return this._run().then(onfulfilled, onrejected);
+  }
+};
+function encodeObjectPath(path) {
+  const trimmed = path.replace(/^\/+/, "");
+  const segments = trimmed.split("/");
+  for (const seg of segments) {
+    if (seg === "..") {
+      throw new core.AuraError(0, {
+        error: {
+          code: "invalid_path",
+          message: 'Path traversal ("..") is not allowed in storage object paths'
+        }
+      });
+    }
+  }
+  return segments.map((s) => encodeURIComponent(s)).join("/");
+}
+
+// src/transform.ts
+function renderTransformParams(t) {
+  const p = new URLSearchParams();
+  if (Number.isFinite(t.width)) p.set("width", String(Math.max(1, Math.floor(t.width))));
+  if (Number.isFinite(t.height)) p.set("height", String(Math.max(1, Math.floor(t.height))));
+  if (t.resize) p.set("fit", t.resize);
+  if (Number.isFinite(t.quality)) p.set("quality", String(Math.min(100, Math.max(20, Math.floor(t.quality)))));
+  if (t.format && t.format !== "origin") p.set("format", t.format);
+  return p;
+}
+
+// src/StorageService.ts
+var StorageService = class extends core.BaseService {
+  constructor(client) {
+    super(client);
+  }
+  get prefix() {
+    return `/v1/storage/${this.client.projectId}`;
+  }
+  // -- Buckets ----------------------------------------------------------------
+  async listBuckets() {
+    return this.request("GET", `${this.prefix}/buckets`);
+  }
+  async getBucket(id) {
+    return this.request("GET", `${this.prefix}/buckets/${id}`);
+  }
+  async createBucket(name, options) {
+    return this.request("POST", `${this.prefix}/buckets`, {
+      name,
+      public: options?.public ?? false,
+      file_size_limit: options?.fileSizeLimit,
+      allowed_mime_types: options?.allowedMimeTypes
+    });
+  }
+  /**
+   * Met à jour un bucket existant (mise à jour PARTIELLE : seuls les champs
+   * fournis sont envoyés). Mapping identique à `createBucket`
+   * (`public`/`file_size_limit`/`allowed_mime_types`).
+   *
+   * Backend route: PATCH /v1/storage/{project_id}/buckets/{id}
+   */
+  async updateBucket(id, options) {
+    const body = {};
+    if (options?.public !== void 0) body.public = options.public;
+    if (options?.fileSizeLimit !== void 0) body.file_size_limit = options.fileSizeLimit;
+    if (options?.allowedMimeTypes !== void 0) body.allowed_mime_types = options.allowedMimeTypes;
+    return this.request("PATCH", `${this.prefix}/buckets/${id}`, body);
+  }
+  async deleteBucket(id) {
+    return this.request("DELETE", `${this.prefix}/buckets/${id}`);
+  }
+  // -- Objects ----------------------------------------------------------------
+  /**
+   * Upload a file to a bucket.
+   *
+   * Le serveur génère une clé unique `<uuid>.<ext>` (relative au bucket).
+   * Réutilisez directement `data.key` pour download(), remove(), copy(), etc.
+   *
+   * @example
+   * const { data } = await client.storage.upload('avatars', 'photo.png', file)
+   * await client.storage.download('avatars', data!.key)  // fonctionne directement
+   *
+   * Backend route: POST /v1/storage/{project_id}/{bucket}
+   */
+  async upload(bucketId, path, file, options) {
+    const formData = new FormData();
+    const blob = file instanceof Blob ? file : new Blob([file], { type: options?.contentType ?? "application/octet-stream" });
+    formData.append("file", blob, path);
+    if (options?.upsert) formData.append("upsert", "true");
+    if (options?.metadata) {
+      for (const [k, v] of Object.entries(options.metadata)) formData.append(k, v);
+    }
+    return this.request("POST", `${this.prefix}/${bucketId}`, formData);
+  }
+  /**
+   * Download paresseux d'un fichier. Renvoie un builder (Blob par défaut, `.asStream()` pour
+   * le flux) ; la requête part à l'`await`. Refresh proactif du token avant la requête.
+   * `options?.transform` (image) : appende `renderTransformParams(...)` à l'URL — figée à
+   * l'appel, le builder reste inchangé.
+   * Backend route: GET /v1/storage/{project_id}/{bucket}/{*key}
+   */
+  download(bucketId, path, options) {
+    let url = this.url(`${this.prefix}/${encodeURIComponent(bucketId)}/${encodeObjectPath(path)}`);
+    if (options?.transform) {
+      const qs = renderTransformParams(options.transform).toString();
+      if (qs) url = `${url}?${qs}`;
+    }
+    const client = this.client;
+    const downloadFn = async () => {
+      const store = client.authStore;
+      if (store.token && store.refreshToken && core.isTokenExpired(store.token, 30)) {
+        await core.refreshOnce(client);
+      }
+      const headers = {};
+      if (store.token) headers["Authorization"] = `Bearer ${store.token}`;
+      if (client.apiKey) headers["apikey"] = client.apiKey;
+      return client.fetchFn(url, { headers });
+    };
+    return new BlobDownloadBuilder(downloadFn);
+  }
+  /**
+   * List files in a bucket.
+   *
+   * ⚠️ `offset` n'est PAS supporté par le backend (`ListQuery` ne connaît que
+   * `prefix`+`limit`) : le paramètre est accepté pour compatibilité ascendante
+   * mais IGNORÉ (jamais envoyé au serveur). Pour restreindre les résultats,
+   * utilisez `prefix`. La vraie pagination (continuation token) relève du backend.
+   *
+   * Backend route: GET /v1/storage/{project_id}/{bucket}
+   */
+  async list(bucketId, options) {
+    const params = new URLSearchParams();
+    if (options?.prefix) params.set("prefix", options.prefix);
+    if (options?.limit !== void 0) params.set("limit", String(options.limit));
+    const qs = params.toString();
+    const sep = qs ? "?" : "";
+    return this.request("GET", `${this.prefix}/${bucketId}${sep}${qs}`);
+  }
+  /**
+   * Delete one or more files from a bucket.
+   * Backend route: DELETE /v1/storage/{project_id}/{bucket}/{*key}
+   * Note: for single file deletion, paths[0] is used. Multi-delete is done in sequence.
+   */
+  async remove(bucketId, paths) {
+    let keys;
+    try {
+      keys = paths.map((p) => encodeObjectPath(p));
+    } catch (e) {
+      return { data: null, error: e };
+    }
+    const b = encodeURIComponent(bucketId);
+    if (keys.length === 1) {
+      return this.request("DELETE", `${this.prefix}/${b}/${keys[0]}`);
+    }
+    const results = await Promise.all(
+      keys.map((k) => this.request("DELETE", `${this.prefix}/${b}/${k}`))
+    );
+    const failed = results.find((r) => r.error);
+    if (failed) return failed;
+    return { data: null, error: null };
+  }
+  /**
+   * Copy a file within a bucket.
+   *
+   * `fromPath`/`toPath` sont relatifs au bucket (cohérent avec `download`/
+   * `remove`/`upload`) — le SDK les préfixe par `bucketId` pour produire les
+   * clés MinIO complètes attendues par le backend.
+   *
+   * Backend route: POST /v1/storage/{project_id}/{bucket}/copy
+   */
+  async copy(bucketId, fromPath, toPath) {
+    return this.request("POST", `${this.prefix}/${bucketId}/copy`, {
+      src_key: `${bucketId}/${fromPath}`,
+      dst_key: `${bucketId}/${toPath}`
+    });
+  }
+  /**
+   * Move/rename a file within a bucket.
+   *
+   * `fromPath`/`toPath` sont relatifs au bucket (cohérent avec `download`/
+   * `remove`/`upload`) — le SDK les préfixe par `bucketId` pour produire les
+   * clés MinIO complètes attendues par le backend.
+   *
+   * Backend route: POST /v1/storage/{project_id}/{bucket}/move
+   */
+  async move(bucketId, fromPath, toPath) {
+    return this.request("POST", `${this.prefix}/${bucketId}/move`, {
+      src_key: `${bucketId}/${fromPath}`,
+      dst_key: `${bucketId}/${toPath}`
+    });
+  }
+  /**
+   * Get file metadata.
+   * Backend route: GET /v1/storage/{project_id}/{bucket}/meta/{*key}
+   */
+  async getMetadata(bucketId, path) {
+    let key;
+    try {
+      key = encodeObjectPath(path);
+    } catch (e) {
+      return { data: null, error: e };
+    }
+    return this.request("GET", `${this.prefix}/${encodeURIComponent(bucketId)}/meta/${key}`);
+  }
+  /**
+   * Generate a signed (temporary) download URL.
+   *
+   * `options?.transform` (image) : dérisqué en réel (stack live) — les params transform
+   * sont HORS HMAC (le backend ne les couvre pas dans la signature), donc on les appende
+   * à l'URL signée APRÈS réception de `{ url, expires_in }`, sans toucher à la requête
+   * `signed-url` elle-même.
+   * Backend route: GET /v1/storage/{project_id}/{bucket}/signed-url?key=...&ttl_secs=...
+   */
+  async createSignedUrl(bucketId, path, expiresInSeconds = 3600, options) {
+    const params = new URLSearchParams({ key: path, ttl_secs: String(expiresInSeconds) });
+    const res = await this.request(
+      "GET",
+      `${this.prefix}/${bucketId}/signed-url?${params.toString()}`
+    );
+    if (res.data && options?.transform) {
+      const qs = renderTransformParams(options.transform).toString();
+      if (qs) {
+        const sep = res.data.url.includes("?") ? "&" : "?";
+        res.data = { ...res.data, url: `${res.data.url}${sep}${qs}` };
+      }
+    }
+    return res;
+  }
+  /**
+   * Génère plusieurs URLs signées en une passe (batch).
+   *
+   * Il n'existe pas d'endpoint batch côté backend : l'implémentation fait un
+   * fan-out `Promise.all` sur `createSignedUrl` (même patron que `remove()`),
+   * RÉSILIENT PAR-ITEM — chaque entrée est soit `{ path, url, expires_in }`
+   * (succès), soit `{ path, error }` (échec), sans faire échouer les autres.
+   *
+   * @example
+   * const { data } = await client.storage.createSignedUrls('avatars', ['a.png', 'b.png'])
+   * data?.forEach((r) => 'url' in r ? use(r.url) : console.warn(r.path, r.error))
+   */
+  async createSignedUrls(bucketId, paths, expiresInSeconds = 3600, options) {
+    const results = await Promise.all(
+      paths.map(async (path) => {
+        const res = await this.createSignedUrl(bucketId, path, expiresInSeconds, options);
+        if (res.error || !res.data) {
+          return { path, error: res.error ?? new core.AuraError(0, { error: { code: "unknown", message: "No data" } }) };
+        }
+        return { path, url: res.data.url, expires_in: res.data.expires_in };
+      })
+    );
+    return { data: results, error: null };
+  }
+  /**
+   * Generate a signed upload URL (presigned POST/PUT).
+   * Backend route: GET /v1/storage/{project_id}/{bucket}/upload-url?key=...&ttl_secs=...
+   */
+  async createSignedUploadUrl(bucketId, path, expiresInSeconds = 3600) {
+    const params = new URLSearchParams({ key: path, ttl_secs: String(expiresInSeconds) });
+    return this.request("GET", `${this.prefix}/${bucketId}/upload-url?${params.toString()}`);
+  }
+  /**
+   * Construit une URL vers un fichier d'un bucket.
+   *
+   * ⚠️ Cette URL N'EST PAS accessible sans authentification : le gateway exige
+   * une clé API (`apikey`/`x-api-key`) sur toutes les routes storage, y compris
+   * pour les buckets créés avec `public: true` (ce flag n'est actuellement pas
+   * vérifié côté gateway — une requête non authentifiée renvoie 401). Pour
+   * partager un fichier sans authentification, utilisez `createSignedUrl()`,
+   * qui génère une URL signée HMAC vérifiée côté serveur sans clé API.
+   *
+   * `options?.transform` (image) : appende `renderTransformParams(...)` en query string.
+   * Backend route: GET /v1/storage/{project_id}/{bucket}/{*key} (clé API requise)
+   */
+  getPublicUrl(bucketId, path, options) {
+    const base = this.url(`${this.prefix}/${encodeURIComponent(bucketId)}/${encodeObjectPath(path)}`);
+    if (options?.transform) {
+      const qs = renderTransformParams(options.transform).toString();
+      if (qs) return `${base}?${qs}`;
+    }
+    return base;
+  }
+};
+
+exports.BlobDownloadBuilder = BlobDownloadBuilder;
+exports.StorageService = StorageService;
+exports.StreamDownloadBuilder = StreamDownloadBuilder;

package/packages/storage/dist/index.d.cts

@@ -0,0 +1,185 @@
+import { AuraResponse, BaseService, AuraClientLike, StorageBucket, UploadResult, ImageTransform, FileEntry, ObjectMeta, AuraError } from '@aurabase/core';
+
+type DownloadFn = () => Promise<Response>;
+/** Download paresseux (Blob par défaut). La requête ne part qu'à l'await ; résultat mémoïsé. */
+declare class BlobDownloadBuilder implements PromiseLike<AuraResponse<Blob>> {
+    private readonly _fn;
+    private _promise;
+    constructor(_fn: DownloadFn);
+    asStream(): StreamDownloadBuilder;
+    private _run;
+    then<TR1 = AuraResponse<Blob>, TR2 = never>(onfulfilled?: ((v: AuraResponse<Blob>) => TR1 | PromiseLike<TR1>) | null, onrejected?: ((e: unknown) => TR2 | PromiseLike<TR2>) | null): Promise<TR1 | TR2>;
+}
+/** Variante flux — `res.body` (ReadableStream). */
+declare class StreamDownloadBuilder implements PromiseLike<AuraResponse<ReadableStream<Uint8Array>>> {
+    private readonly _fn;
+    private _promise;
+    constructor(_fn: DownloadFn);
+    private _run;
+    then<TR1 = AuraResponse<ReadableStream<Uint8Array>>, TR2 = never>(onfulfilled?: ((v: AuraResponse<ReadableStream<Uint8Array>>) => TR1 | PromiseLike<TR1>) | null, onrejected?: ((e: unknown) => TR2 | PromiseLike<TR2>) | null): Promise<TR1 | TR2>;
+}
+
+declare class StorageService extends BaseService {
+    constructor(client: AuraClientLike);
+    private get prefix();
+    listBuckets(): Promise<AuraResponse<StorageBucket[]>>;
+    getBucket(id: string): Promise<AuraResponse<StorageBucket>>;
+    createBucket(name: string, options?: {
+        public?: boolean;
+        fileSizeLimit?: number;
+        allowedMimeTypes?: string[];
+    }): Promise<AuraResponse<StorageBucket>>;
+    /**
+     * Met à jour un bucket existant (mise à jour PARTIELLE : seuls les champs
+     * fournis sont envoyés). Mapping identique à `createBucket`
+     * (`public`/`file_size_limit`/`allowed_mime_types`).
+     *
+     * Backend route: PATCH /v1/storage/{project_id}/buckets/{id}
+     */
+    updateBucket(id: string, options?: {
+        public?: boolean;
+        fileSizeLimit?: number;
+        allowedMimeTypes?: string[];
+    }): Promise<AuraResponse<StorageBucket>>;
+    deleteBucket(id: string): Promise<AuraResponse<null>>;
+    /**
+     * Upload a file to a bucket.
+     *
+     * Le serveur génère une clé unique `<uuid>.<ext>` (relative au bucket).
+     * Réutilisez directement `data.key` pour download(), remove(), copy(), etc.
+     *
+     * @example
+     * const { data } = await client.storage.upload('avatars', 'photo.png', file)
+     * await client.storage.download('avatars', data!.key)  // fonctionne directement
+     *
+     * Backend route: POST /v1/storage/{project_id}/{bucket}
+     */
+    upload(bucketId: string, path: string, file: Blob | File | ArrayBuffer, options?: {
+        contentType?: string;
+        upsert?: boolean;
+        metadata?: Record<string, string>;
+    }): Promise<AuraResponse<UploadResult>>;
+    /**
+     * Download paresseux d'un fichier. Renvoie un builder (Blob par défaut, `.asStream()` pour
+     * le flux) ; la requête part à l'`await`. Refresh proactif du token avant la requête.
+     * `options?.transform` (image) : appende `renderTransformParams(...)` à l'URL — figée à
+     * l'appel, le builder reste inchangé.
+     * Backend route: GET /v1/storage/{project_id}/{bucket}/{*key}
+     */
+    download(bucketId: string, path: string, options?: {
+        transform?: ImageTransform;
+    }): BlobDownloadBuilder;
+    /**
+     * List files in a bucket.
+     *
+     * ⚠️ `offset` n'est PAS supporté par le backend (`ListQuery` ne connaît que
+     * `prefix`+`limit`) : le paramètre est accepté pour compatibilité ascendante
+     * mais IGNORÉ (jamais envoyé au serveur). Pour restreindre les résultats,
+     * utilisez `prefix`. La vraie pagination (continuation token) relève du backend.
+     *
+     * Backend route: GET /v1/storage/{project_id}/{bucket}
+     */
+    list(bucketId: string, options?: {
+        prefix?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<AuraResponse<FileEntry[]>>;
+    /**
+     * Delete one or more files from a bucket.
+     * Backend route: DELETE /v1/storage/{project_id}/{bucket}/{*key}
+     * Note: for single file deletion, paths[0] is used. Multi-delete is done in sequence.
+     */
+    remove(bucketId: string, paths: string[]): Promise<AuraResponse<null>>;
+    /**
+     * Copy a file within a bucket.
+     *
+     * `fromPath`/`toPath` sont relatifs au bucket (cohérent avec `download`/
+     * `remove`/`upload`) — le SDK les préfixe par `bucketId` pour produire les
+     * clés MinIO complètes attendues par le backend.
+     *
+     * Backend route: POST /v1/storage/{project_id}/{bucket}/copy
+     */
+    copy(bucketId: string, fromPath: string, toPath: string): Promise<AuraResponse<{
+        key: string;
+    }>>;
+    /**
+     * Move/rename a file within a bucket.
+     *
+     * `fromPath`/`toPath` sont relatifs au bucket (cohérent avec `download`/
+     * `remove`/`upload`) — le SDK les préfixe par `bucketId` pour produire les
+     * clés MinIO complètes attendues par le backend.
+     *
+     * Backend route: POST /v1/storage/{project_id}/{bucket}/move
+     */
+    move(bucketId: string, fromPath: string, toPath: string): Promise<AuraResponse<{
+        key: string;
+    }>>;
+    /**
+     * Get file metadata.
+     * Backend route: GET /v1/storage/{project_id}/{bucket}/meta/{*key}
+     */
+    getMetadata(bucketId: string, path: string): Promise<AuraResponse<ObjectMeta>>;
+    /**
+     * Generate a signed (temporary) download URL.
+     *
+     * `options?.transform` (image) : dérisqué en réel (stack live) — les params transform
+     * sont HORS HMAC (le backend ne les couvre pas dans la signature), donc on les appende
+     * à l'URL signée APRÈS réception de `{ url, expires_in }`, sans toucher à la requête
+     * `signed-url` elle-même.
+     * Backend route: GET /v1/storage/{project_id}/{bucket}/signed-url?key=...&ttl_secs=...
+     */
+    createSignedUrl(bucketId: string, path: string, expiresInSeconds?: number, options?: {
+        transform?: ImageTransform;
+    }): Promise<AuraResponse<{
+        url: string;
+        expires_in: number;
+    }>>;
+    /**
+     * Génère plusieurs URLs signées en une passe (batch).
+     *
+     * Il n'existe pas d'endpoint batch côté backend : l'implémentation fait un
+     * fan-out `Promise.all` sur `createSignedUrl` (même patron que `remove()`),
+     * RÉSILIENT PAR-ITEM — chaque entrée est soit `{ path, url, expires_in }`
+     * (succès), soit `{ path, error }` (échec), sans faire échouer les autres.
+     *
+     * @example
+     * const { data } = await client.storage.createSignedUrls('avatars', ['a.png', 'b.png'])
+     * data?.forEach((r) => 'url' in r ? use(r.url) : console.warn(r.path, r.error))
+     */
+    createSignedUrls(bucketId: string, paths: string[], expiresInSeconds?: number, options?: {
+        transform?: ImageTransform;
+    }): Promise<AuraResponse<Array<{
+        path: string;
+        url: string;
+        expires_in: number;
+    } | {
+        path: string;
+        error: AuraError;
+    }>>>;
+    /**
+     * Generate a signed upload URL (presigned POST/PUT).
+     * Backend route: GET /v1/storage/{project_id}/{bucket}/upload-url?key=...&ttl_secs=...
+     */
+    createSignedUploadUrl(bucketId: string, path: string, expiresInSeconds?: number): Promise<AuraResponse<{
+        url: string;
+        expires_in: number;
+    }>>;
+    /**
+     * Construit une URL vers un fichier d'un bucket.
+     *
+     * ⚠️ Cette URL N'EST PAS accessible sans authentification : le gateway exige
+     * une clé API (`apikey`/`x-api-key`) sur toutes les routes storage, y compris
+     * pour les buckets créés avec `public: true` (ce flag n'est actuellement pas
+     * vérifié côté gateway — une requête non authentifiée renvoie 401). Pour
+     * partager un fichier sans authentification, utilisez `createSignedUrl()`,
+     * qui génère une URL signée HMAC vérifiée côté serveur sans clé API.
+     *
+     * `options?.transform` (image) : appende `renderTransformParams(...)` en query string.
+     * Backend route: GET /v1/storage/{project_id}/{bucket}/{*key} (clé API requise)
+     */
+    getPublicUrl(bucketId: string, path: string, options?: {
+        transform?: ImageTransform;
+    }): string;
+}
+
+export { BlobDownloadBuilder, StorageService, StreamDownloadBuilder };