@aurabase/aurabase-js 0.3.0

package/packages/storage/node_modules/.bin/vitest

@@ -0,0 +1,22 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/Users/affanedaylami/aurabase/aurabase-js/node_modules/.pnpm/vitest@4.1.9_@types+node@20.14.15_vite@8.1.3_@types+node@20.14.15_esbuild@0.27.7_/node_modules/vitest/node_modules:/Users/affanedaylami/aurabase/aurabase-js/node_modules/.pnpm/vitest@4.1.9_@types+node@20.14.15_vite@8.1.3_@types+node@20.14.15_esbuild@0.27.7_/node_modules:/Users/affanedaylami/aurabase/aurabase-js/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/Users/affanedaylami/aurabase/aurabase-js/node_modules/.pnpm/vitest@4.1.9_@types+node@20.14.15_vite@8.1.3_@types+node@20.14.15_esbuild@0.27.7_/node_modules/vitest/node_modules:/Users/affanedaylami/aurabase/aurabase-js/node_modules/.pnpm/vitest@4.1.9_@types+node@20.14.15_vite@8.1.3_@types+node@20.14.15_esbuild@0.27.7_/node_modules:/Users/affanedaylami/aurabase/aurabase-js/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../vitest/vitest.mjs" "$@"
+else
+  exec node  "$basedir/../vitest/vitest.mjs" "$@"
+fi
+# cmd-shim-target=/Users/affanedaylami/aurabase/aurabase-js/packages/storage/node_modules/vitest/vitest.mjs

package/packages/storage/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -0,0 +1 @@
+{"version":"4.1.9","results":[[":tests/download.test.ts",{"duration":383.5393750000003,"failed":false}],[":tests/path.test.ts",{"duration":285.0919170000002,"failed":false}],[":tests/transform.test.ts",{"duration":522.0009580000005,"failed":false}],[":tests/parity.test.ts",{"duration":719.0756669999996,"failed":false}]]}

package/packages/storage/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@aurabase/storage",
+  "version": "0.3.0",
+  "description": "Service de stockage objet du SDK Aurabase (buckets, upload/download, URLs signées)",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "MIT",
+  "author": "Aurabase",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daylami555/aurabase.git",
+    "directory": "aurabase-js/packages/storage"
+  },
+  "homepage": "https://github.com/daylami555/aurabase/tree/main/aurabase-js/packages/storage#readme",
+  "bugs": {
+    "url": "https://github.com/daylami555/aurabase/issues"
+  },
+  "keywords": [
+    "aurabase",
+    "baas",
+    "sdk",
+    "storage"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@aurabase/core": "workspace:*"
+  },
+  "devDependencies": {
+    "tsup": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}

package/packages/storage/src/DownloadBuilder.ts

@@ -0,0 +1,60 @@
+import { AuraError } from '@aurabase/core'
+import type { AuraResponse } from '@aurabase/core'
+
+type DownloadFn = () => Promise<Response>
+
+async function runDownload<T>(fn: DownloadFn, extract: (r: Response) => T | Promise<T>): Promise<AuraResponse<T>> {
+  let res: Response
+  try {
+    res = await fn()
+  } catch (err) {
+    return {
+      data: null,
+      error: new AuraError(0, { error: { code: 'network_error', message: err instanceof Error ? err.message : 'Download failed' } }),
+    }
+  }
+  if (!res.ok) return { data: null, error: new AuraError(res.status) }
+  return { data: await extract(res), error: null }
+}
+
+/** Download paresseux (Blob par défaut). La requête ne part qu'à l'await ; résultat mémoïsé. */
+export class BlobDownloadBuilder implements PromiseLike<AuraResponse<Blob>> {
+  private _promise: Promise<AuraResponse<Blob>> | null = null
+  constructor(private readonly _fn: DownloadFn) {}
+
+  asStream(): StreamDownloadBuilder {
+    return new StreamDownloadBuilder(this._fn)
+  }
+
+  private _run(): Promise<AuraResponse<Blob>> {
+    if (!this._promise) this._promise = runDownload(this._fn, (r) => r.blob())
+    return this._promise
+  }
+
+  then<TR1 = AuraResponse<Blob>, TR2 = never>(
+    onfulfilled?: ((v: AuraResponse<Blob>) => TR1 | PromiseLike<TR1>) | null,
+    onrejected?: ((e: unknown) => TR2 | PromiseLike<TR2>) | null,
+  ): Promise<TR1 | TR2> {
+    return this._run().then(onfulfilled, onrejected)
+  }
+}
+
+/** Variante flux — `res.body` (ReadableStream). */
+export class StreamDownloadBuilder implements PromiseLike<AuraResponse<ReadableStream<Uint8Array>>> {
+  private _promise: Promise<AuraResponse<ReadableStream<Uint8Array>>> | null = null
+  constructor(private readonly _fn: DownloadFn) {}
+
+  private _run(): Promise<AuraResponse<ReadableStream<Uint8Array>>> {
+    if (!this._promise) {
+      this._promise = runDownload(this._fn, (r) => r.body as ReadableStream<Uint8Array>)
+    }
+    return this._promise
+  }
+
+  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> {
+    return this._run().then(onfulfilled, onrejected)
+  }
+}

package/packages/storage/src/StorageService.ts

@@ -0,0 +1,323 @@
+import { BaseService } from '@aurabase/core'
+import { isTokenExpired, refreshOnce, AuraError } from '@aurabase/core'
+import type {
+  AuraResponse,
+  FileEntry,
+  ImageTransform,
+  ObjectMeta,
+  StorageBucket,
+  UploadResult,
+} from '@aurabase/core'
+import type { AuraClientLike } from '@aurabase/core'
+import { BlobDownloadBuilder } from './DownloadBuilder'
+import { encodeObjectPath } from './path'
+import { renderTransformParams } from './transform'
+
+export class StorageService extends BaseService {
+  constructor(client: AuraClientLike) {
+    super(client)
+  }
+
+  private get prefix(): string {
+    return `/v1/storage/${this.client.projectId}`
+  }
+
+  // -- Buckets ----------------------------------------------------------------
+
+  async listBuckets(): Promise<AuraResponse<StorageBucket[]>> {
+    return this.request('GET', `${this.prefix}/buckets`)
+  }
+
+  async getBucket(id: string): Promise<AuraResponse<StorageBucket>> {
+    return this.request('GET', `${this.prefix}/buckets/${id}`)
+  }
+
+  async createBucket(
+    name: string,
+    options?: { public?: boolean; fileSizeLimit?: number; allowedMimeTypes?: string[] },
+  ): Promise<AuraResponse<StorageBucket>> {
+    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: string,
+    options?: { public?: boolean; fileSizeLimit?: number; allowedMimeTypes?: string[] },
+  ): Promise<AuraResponse<StorageBucket>> {
+    const body: Record<string, unknown> = {}
+    if (options?.public !== undefined) body.public = options.public
+    if (options?.fileSizeLimit !== undefined) body.file_size_limit = options.fileSizeLimit
+    if (options?.allowedMimeTypes !== undefined) body.allowed_mime_types = options.allowedMimeTypes
+    return this.request('PATCH', `${this.prefix}/buckets/${id}`, body)
+  }
+
+  async deleteBucket(id: string): Promise<AuraResponse<null>> {
+    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: string,
+    path: string,
+    file: Blob | File | ArrayBuffer,
+    options?: { contentType?: string; upsert?: boolean; metadata?: Record<string, string> },
+  ): Promise<AuraResponse<UploadResult>> {
+    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')
+    // Métadonnées objet : tout champ multipart ≠ `file`/`upsert` est rangé par le
+    // backend dans `custom_meta` → métadonnées S3 relues par `getMetadata`.
+    if (options?.metadata) {
+      for (const [k, v] of Object.entries(options.metadata)) formData.append(k, v)
+    }
+
+    return this.request('POST', `${this.prefix}/${bucketId}`, formData as unknown)
+  }
+
+  /**
+   * 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 {
+    // Encodage anti-traversal + neutralisation des caractères d'URL. Lève
+    // synchroniquement (AuraError) sur un segment `..`.
+    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 (): Promise<Response> => {
+      const store = client.authStore
+      if (store.token && store.refreshToken && isTokenExpired(store.token, 30)) {
+        await refreshOnce(client)
+      }
+      const headers: Record<string, string> = {}
+      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: string, options?: { prefix?: string; limit?: number; offset?: number }): Promise<AuraResponse<FileEntry[]>> {
+    const params = new URLSearchParams()
+    if (options?.prefix) params.set('prefix', options.prefix)
+    if (options?.limit !== undefined) params.set('limit', String(options.limit))
+    // `offset` volontairement NON transmis : ignoré par le backend (cf. JSDoc).
+    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: string, paths: string[]): Promise<AuraResponse<null>> {
+    // Encodage anti-traversal de chaque clé (never-throw : on renvoie l'erreur).
+    let keys: string[]
+    try {
+      keys = paths.map((p) => encodeObjectPath(p))
+    } catch (e) {
+      return { data: null, error: e as AuraError }
+    }
+    const b = encodeURIComponent(bucketId)
+    // Backend supports single file deletion per request
+    // For multiple files, call sequentially
+    if (keys.length === 1) {
+      return this.request('DELETE', `${this.prefix}/${b}/${keys[0]}`)
+    }
+    // Multi-delete: fire all in parallel, return success if all succeed
+    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 as AuraResponse<null>
+    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: string, fromPath: string, toPath: string): Promise<AuraResponse<{ key: string }>> {
+    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: string, fromPath: string, toPath: string): Promise<AuraResponse<{ key: string }>> {
+    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: string, path: string): Promise<AuraResponse<ObjectMeta>> {
+    let key: string
+    try {
+      key = encodeObjectPath(path)
+    } catch (e) {
+      return { data: null, error: e as AuraError }
+    }
+    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: string,
+    path: string,
+    expiresInSeconds = 3600,
+    options?: { transform?: ImageTransform },
+  ): Promise<AuraResponse<{ url: string; expires_in: number }>> {
+    const params = new URLSearchParams({ key: path, ttl_secs: String(expiresInSeconds) })
+    const res = await this.request<{ url: string; expires_in: number }>(
+      '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: string,
+    paths: string[],
+    expiresInSeconds = 3600,
+    options?: { transform?: ImageTransform },
+  ): Promise<AuraResponse<Array<{ path: string; url: string; expires_in: number } | { path: string; error: AuraError }>>> {
+    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 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: string,
+    path: string,
+    expiresInSeconds = 3600,
+  ): Promise<AuraResponse<{ url: string; expires_in: number }>> {
+    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: string, path: string, options?: { transform?: ImageTransform }): string {
+    // Lève synchroniquement (AuraError) sur un segment `..`.
+    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
+  }
+}

package/packages/storage/src/index.ts

@@ -0,0 +1,2 @@
+export { StorageService } from './StorageService'
+export { BlobDownloadBuilder, StreamDownloadBuilder } from './DownloadBuilder'

package/packages/storage/src/path.ts

@@ -0,0 +1,35 @@
+import { AuraError } from '@aurabase/core'
+
+/**
+ * Encode un chemin d'objet storage pour interpolation SÛRE dans un path d'URL.
+ *
+ * Deux protections :
+ *  1. **Anti-traversal** — rejette tout segment `..`. Sans ça, un `../` non
+ *     neutralisé serait normalisé par `fetch`/le navigateur AVANT l'envoi
+ *     (`/storage/proj/bucketA/../../bucketB/x` → `/storage/proj/bucketB/x`),
+ *     permettant un accès cross-bucket. Le backend traite les clés S3 de façon
+ *     littérale et ne filtre pas `..` : la défense doit donc être ici aussi.
+ *  2. **Encodage per-segment** — `encodeURIComponent` sur chaque segment
+ *     (les `/` séparateurs sont préservés pour garder la structure de dossiers).
+ *     Neutralise `?`, `#`, `%`, espaces… qui casseraient l'URL ou injecteraient
+ *     une query string. Le double-décodage est évité (`%2E%2E` reste littéral).
+ *
+ * @throws {AuraError} code `invalid_path` si un segment `..` est présent.
+ */
+export function encodeObjectPath(path: string): string {
+  // Retire les slashes de tête : le préfixe bucket est ajouté séparément, et un
+  // path absolu (`/x`) ne doit pas produire `bucket//x`.
+  const trimmed = path.replace(/^\/+/, '')
+  const segments = trimmed.split('/')
+  for (const seg of segments) {
+    if (seg === '..') {
+      throw new AuraError(0, {
+        error: {
+          code: 'invalid_path',
+          message: 'Path traversal ("..") is not allowed in storage object paths',
+        },
+      })
+    }
+  }
+  return segments.map((s) => encodeURIComponent(s)).join('/')
+}

package/packages/storage/src/transform.ts

@@ -0,0 +1,15 @@
+import type { ImageTransform } from '@aurabase/core'
+
+/** Mappe une ImageTransform (vocabulaire Supabase) vers les query params du backend
+ *  de rendu Aurabase (`fit`, `format`, `quality`, `width`, `height`). */
+export function renderTransformParams(t: ImageTransform): URLSearchParams {
+  const p = new URLSearchParams()
+  // Garde `Number.isFinite` : un NaN/Infinity (calcul amont non vérifié) est de type
+  // 'number' mais produirait `width=NaN` → 400 backend ; on l'ignore silencieusement.
+  if (Number.isFinite(t.width)) p.set('width', String(Math.max(1, Math.floor(t.width as number))))
+  if (Number.isFinite(t.height)) p.set('height', String(Math.max(1, Math.floor(t.height as number))))
+  if (t.resize) p.set('fit', t.resize) // cover/contain/fill : mêmes valeurs backend
+  if (Number.isFinite(t.quality)) p.set('quality', String(Math.min(100, Math.max(20, Math.floor(t.quality as number)))))
+  if (t.format && t.format !== 'origin') p.set('format', t.format)
+  return p
+}

package/packages/storage/tests/download.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest'
+import { StorageService } from '../src/StorageService'
+import { BaseAuthStore } from '@aurabase/core'
+import type { AuraClientLike } from '@aurabase/core'
+
+function b64url(o: unknown) { return btoa(JSON.stringify(o)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '') }
+function expiredJwt() { return `${b64url({ alg: 'HS256' })}.${b64url({ exp: Math.floor(Date.now() / 1000) - 60 })}.s` }
+function validJwt() { return `${b64url({ alg: 'HS256' })}.${b64url({ exp: Math.floor(Date.now() / 1000) + 3600 })}.s` }
+function fakeUser() { return { id: 'u', email: null, role: 'authenticated', email_verified: true, is_banned: false, is_anonymous: false, mfa_enabled: false, user_metadata: {}, app_metadata: {}, created_at: '2025-01-01T00:00:00Z' } }
+
+function make(responder: (url: string) => Response, store = new BaseAuthStore()) {
+  const calls: string[] = []
+  const client: AuraClientLike = {
+    baseUrl: 'http://x', projectId: 'p', apiKey: 'k', authStore: store,
+    fetchFn: (async (url: string) => { calls.push(String(url)); return responder(String(url)) }) as unknown as typeof globalThis.fetch,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    auth: { refreshSession: async () => ({ data: null, error: null }) as any },
+  }
+  return { storage: new StorageService(client), calls }
+}
+
+describe('storage.download — builder paresseux', () => {
+  it('Blob par défaut', async () => {
+    const { storage } = make(() => new Response(new Blob(['hello']), { status: 200 }))
+    const { data, error } = await storage.download('b', 'k.png')
+    expect(error).toBeNull()
+    expect(data).toBeInstanceOf(Blob)
+  })
+
+  it('mémoïsé : une seule requête même sur double await', async () => {
+    const { storage, calls } = make(() => new Response(new Blob(['x']), { status: 200 }))
+    const dl = storage.download('b', 'k.png')
+    await dl
+    await dl
+    expect(calls.length).toBe(1)
+  })
+
+  it('.asStream() → ReadableStream', async () => {
+    const { storage } = make(() => new Response(new Blob(['x']), { status: 200 }))
+    const { data } = await storage.download('b', 'k.png').asStream()
+    expect(data).toBeInstanceOf(ReadableStream)
+  })
+
+  it('!ok → erreur status', async () => {
+    const { storage } = make(() => new Response(null, { status: 404 }))
+    const { data, error } = await storage.download('b', 'missing')
+    expect(data).toBeNull()
+    expect(error?.status).toBe(404)
+  })
+
+  it('refresh proactif si token expiré (refresh AVANT download)', async () => {
+    const store = new BaseAuthStore()
+    store.save(expiredJwt(), 'rt', fakeUser())
+    const { storage, calls } = make((url) => {
+      if (url.includes('/v1/auth/')) {
+        return new Response(JSON.stringify({ access_token: validJwt(), refresh_token: 'rt2', token_type: 'bearer', expires_in: 3600, user: fakeUser() }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+      }
+      return new Response(new Blob(['x']), { status: 200 })
+    }, store)
+    await storage.download('b', 'k.png')
+    expect(calls[0]).toContain('/v1/auth/p/refresh')
+    expect(calls[1]).toContain('/b/k.png')
+  })
+})