@aurabase/aurabase-js 0.3.0 → 0.4.0

package/packages/storage/README.md

@@ -1,141 +0,0 @@
-# @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

@@ -1,333 +0,0 @@
-'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

@@ -1,185 +0,0 @@
-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 };