@frenchbaas/js 0.3.0 → 0.4.0

package/README.md

@@ -24,11 +24,11 @@ const client = new FrenchBaas({
 ## Auth
 
 ```js
-// Inscription
-const { user, access_token } = await client.auth.signUp({ email: 'a@b.com', password: 'secret' })
+// Inscription (mot de passe : 8 caractères minimum)
+const { user, access_token } = await client.auth.signUp({ email: 'a@b.com', password: 'monMotDePasse' })
 
 // Connexion
-const { user, access_token } = await client.auth.login({ email: 'a@b.com', password: 'secret' })
+const { user, access_token } = await client.auth.login({ email: 'a@b.com', password: 'monMotDePasse' })
 
 // Déconnexion
 await client.auth.logout()
@@ -49,12 +49,23 @@ const col = client.collection('uuid-de-la-collection')
 const { data, meta } = await col.get({ page: 1, perPage: 20 })
 // meta → { total, page, per_page, total_pages }
 
-// Filtrer par champ (string, number, boolean)
+// Filtrer par champ — valeur unique
 const { data: pending } = await col.get({ filter: { status: 'pending' } })
 
-// Filtrer par champ references (tableau d'UUIDs — contient l'UUID)
+// Filtrer OR — plusieurs valeurs (status pending OU delivered)
+const { data: multi } = await col.get({ filter: { status: ['pending', 'delivered'] } })
+
+// Filtrer par references — valeur unique (contient l'UUID)
 const { data: products } = await col.get({ filter: { category_ids: 'uuid-categorie' } })
 
+// Filtrer references OR — catégorie A OU B
+const { data: orProducts } = await col.get({ filter: { category_ids: ['uuid-cat-a', 'uuid-cat-b'] } })
+
+// Filtrer references AND — dans catégorie A ET B (uniquement pour references/array)
+const { data: andProducts } = await col.get({ filter: { category_ids: { and: ['uuid-cat-a', 'uuid-cat-b'] } } })
+
+// ⚠ Maximum 20 valeurs par filtre (OR ou AND)
+
 // Récupérer un document par ID
 const doc = await col.getById('doc-uuid')
 // doc → { id, data, created_at, updated_at }
@@ -108,6 +119,61 @@ Ces permissions se configurent dans le Dashboard → collection → schéma →
 
 ---
 
+## Storage
+
+```js
+// Lister les buckets du projet (X-Api-Key uniquement, pas de Bearer)
+const buckets = await client.storage.listBuckets()
+// → [{ id, name, visibility, public, created_at }, ...]
+
+// Obtenir un client bucket
+const bucket = client.storage.bucket('uuid-bucket')
+
+// Lister les fichiers (paginé, filtre préfixe optionnel)
+const { data, meta } = await bucket.listObjects({ page: 1, perPage: 20, prefix: 'users/123/' })
+// → data: [{ id, name, content_type, size, created_by, created_at, url? }, ...]
+// → meta: { total, page, per_page, pages }
+
+// Upload un fichier (3 étapes gérées automatiquement : présignature → PUT OVH → confirmation)
+// Bearer requis.
+const file = document.querySelector('input[type=file]').files[0]
+const obj = await bucket.upload(file, 'photo.jpg', {
+  onProgress: pct => console.log(`${pct}%`), // progression optionnelle (navigateur uniquement)
+})
+// → { id, name, content_type, size, created_by, created_at, url? }
+
+// Récupérer l'URL d'un fichier
+const { url, expires_in } = await bucket.getUrl(obj.id)
+// Bucket public  → url permanente, expires_in absent
+// Bucket privé   → url signée (TTL 3600 s), créateur uniquement
+
+// Supprimer un fichier (Bearer requis, créateur uniquement)
+await bucket.delete(obj.id)
+```
+
+### Visibilité des buckets
+
+| Visibilité | listObjects | upload / delete | getUrl |
+|------------|-------------|-----------------|--------|
+| `public` | Sans Bearer | Bearer requis | Sans Bearer (URL permanente) |
+| `private` | Bearer requis (ses fichiers) | Bearer requis | Bearer requis (URL signée 1h) |
+
+### Erreurs Storage
+
+```ts
+import { ConflictError, ValidationError, QuotaError } from '@frenchbaas/js'
+
+try {
+  await bucket.upload(file, 'photo.jpg')
+} catch (e) {
+  if (e instanceof ConflictError)   console.error('Nom déjà pris par un autre utilisateur')
+  if (e instanceof ValidationError) console.error('Fichier trop grand ou type non autorisé')
+  if (e instanceof QuotaError)      console.error('Quota storage dépassé')
+}
+```
+
+---
+
 ## Webhooks
 
 Si une collection a un `before_create_url` ou `before_update_url` configuré,
@@ -151,6 +217,7 @@ try {
 import {
   FrenchBaasError,
   AuthError,
+  ConflictError,
   ValidationError,
   NotFoundError,
   QuotaError,
@@ -169,6 +236,7 @@ try {
     console.error(e.message, e.errors)
   }
   else if (e instanceof AuthError)      console.error('Non connecté ou session expirée')
+  else if (e instanceof ConflictError)  console.error('Conflit : ressource déjà existante')
   else if (e instanceof NotFoundError)  console.error('Document ou collection introuvable')
   else if (e instanceof QuotaError)     console.error('Quota dépassé :', e.message)
   else if (e instanceof RateLimitError) console.error('Trop de requêtes, réessayez dans quelques instants')
@@ -206,6 +274,10 @@ const client = new FrenchBaas({
 Utilisez `localStorage` pour que la session survive au rechargement de page
 (applications web). Utilisez `memory` pour les environnements serveur (Node.js).
 
+> **Sécurité** : l'option `localStorage` expose les tokens à toute attaque XSS sur votre page.
+> Assurez-vous que votre application ne charge pas de scripts tiers non maîtrisés
+> et qu'elle applique une politique CSP stricte si vous utilisez ce mode.
+
 ---
 
 ## Fonctionnalités automatiques

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AuthError: () => AuthError,
+  ConflictError: () => ConflictError,
   FrenchBaas: () => FrenchBaasClient,
   FrenchBaasError: () => FrenchBaasError,
   NetworkError: () => NetworkError,
@@ -91,6 +92,13 @@ var ServerError = class extends FrenchBaasError {
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
+var ConflictError = class extends FrenchBaasError {
+  constructor(message = "Conflit : la ressource existe d\xE9j\xE0.") {
+    super(message, 409);
+    this.name = "ConflictError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
 
 // src/auth.ts
 var AuthModule = class {
@@ -211,7 +219,14 @@ var CollectionClient = class {
     };
     if (options.filter) {
       for (const [key, val] of Object.entries(options.filter)) {
-        if (val !== void 0) params[`filter[${key}]`] = val;
+        if (val === void 0) continue;
+        if (typeof val === "string") {
+          params[`filter[${key}]`] = val;
+        } else if (Array.isArray(val)) {
+          params[`filter[${key}][]`] = val;
+        } else {
+          params[`filter[${key}][and][]`] = val.and;
+        }
       }
     }
     const res = await this._http.get(
@@ -314,7 +329,12 @@ var HttpClient = class {
     const url = new URL(this._baseUrl + path);
     if (params) {
       for (const [k, v] of Object.entries(params)) {
-        if (v !== void 0) url.searchParams.set(k, String(v));
+        if (v === void 0) continue;
+        if (Array.isArray(v)) {
+          for (const item of v) url.searchParams.append(k, item);
+        } else {
+          url.searchParams.set(k, String(v));
+        }
       }
     }
     return this._request("GET", url.toString(), void 0, true);
@@ -404,6 +424,8 @@ var HttpClient = class {
         const details = err.errors ?? [];
         throw new ValidationError(details.length ? details.join(", ") : msg, details);
       }
+      case 409:
+        throw new ConflictError(msg);
       case 429:
         throw new RateLimitError();
       default:
@@ -413,6 +435,139 @@ var HttpClient = class {
   }
 };
 
+// src/storage.ts
+var StorageModule = class {
+  constructor(_http) {
+    this._http = _http;
+  }
+  /**
+   * Liste tous les buckets du projet.
+   *
+   * Authentification par API key uniquement — pas de Bearer requis.
+   * Usage principal : découverte des IDs pendant la construction de l'app.
+   */
+  async listBuckets() {
+    const res = await this._http.get(
+      "/sdk/storage/buckets"
+    );
+    return res.data;
+  }
+  /**
+   * Retourne un client pour opérer sur un bucket spécifique.
+   *
+   * @param bucketId UUID du bucket (visible dans Dashboard → Storage)
+   */
+  bucket(bucketId) {
+    if (!bucketId || typeof bucketId !== "string") {
+      throw new Error("[FrenchBaas] storage.bucket() requiert un UUID de bucket valide.");
+    }
+    return new StorageBucketClient(bucketId, this._http);
+  }
+};
+var StorageBucketClient = class {
+  constructor(_bucketId, _http) {
+    this._bucketId = _bucketId;
+    this._http = _http;
+  }
+  /**
+   * Liste les fichiers du bucket avec pagination et filtre préfixe.
+   *
+   * - Bucket **public** : Bearer non requis — retourne tous les fichiers.
+   * - Bucket **privé**  : Bearer requis — retourne uniquement les fichiers du user connecté.
+   *
+   * @example
+   * const { data, meta } = await bucket.listObjects({ prefix: 'users/123/', perPage: 20 })
+   */
+  async listObjects(options = {}) {
+    const params = {};
+    if (options.page !== void 0) params["page"] = options.page;
+    if (options.perPage !== void 0) params["per_page"] = options.perPage;
+    if (options.prefix) params["prefix"] = options.prefix;
+    return this._http.get(
+      `/sdk/storage/buckets/${this._bucketId}/objects`,
+      params
+    );
+  }
+  /**
+   * Upload un fichier en 3 étapes : présignature → PUT direct vers OVH → confirmation.
+   *
+   * Bearer requis. La progression PUT (0–100 %) peut être suivie via `options.onProgress`.
+   *
+   * @param file     Fichier ou Blob à uploader
+   * @param name     Nom dans le bucket (ex: "photo.jpg", "users/123/avatar.jpg")
+   * @param options  contentType (override), onProgress
+   *
+   * @example
+   * const obj = await bucket.upload(file, 'avatar.jpg', {
+   *   onProgress: pct => console.log(`${pct}%`)
+   * })
+   */
+  async upload(file, name, options = {}) {
+    const contentType = options.contentType ?? ((file instanceof File ? file.type : "") || "application/octet-stream");
+    const presign = await this._http.post(`/sdk/storage/buckets/${this._bucketId}/upload`, {
+      name,
+      content_type: contentType,
+      size: file.size
+    });
+    await this._putToOvh(presign.upload_url, file, contentType, options.onProgress);
+    const confirm = await this._http.post(
+      `/sdk/storage/buckets/${this._bucketId}/confirm`,
+      { name, key: presign.key, content_type: contentType }
+    );
+    return confirm.data;
+  }
+  /**
+   * Retourne l'URL d'accès à un fichier.
+   *
+   * - Bucket **public**  : URL publique permanente, Bearer non requis.
+   * - Bucket **privé**   : URL signée (TTL 3600 s), Bearer requis, créateur uniquement.
+   */
+  async getUrl(objectId) {
+    return this._http.get(
+      `/sdk/storage/buckets/${this._bucketId}/objects/${objectId}/url`
+    );
+  }
+  /**
+   * Supprime un fichier du bucket.
+   * Bearer requis. Seul le créateur du fichier peut le supprimer.
+   */
+  async delete(objectId) {
+    await this._http.delete(`/sdk/storage/buckets/${this._bucketId}/objects/${objectId}`);
+  }
+  // ── Private ──────────────────────────────────────────────────────────────
+  /**
+   * PUT direct vers l'URL présignée OVH.
+   * Utilise XHR (si disponible) pour le suivi de progression, sinon fetch.
+   */
+  async _putToOvh(url, file, contentType, onProgress) {
+    if (typeof onProgress === "function" && typeof XMLHttpRequest !== "undefined") {
+      return new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
+        xhr.open("PUT", url);
+        xhr.setRequestHeader("Content-Type", contentType);
+        xhr.upload.addEventListener("progress", (e) => {
+          if (e.lengthComputable) onProgress(Math.round(e.loaded / e.total * 100));
+        });
+        xhr.addEventListener("load", () => {
+          if (xhr.status >= 200 && xhr.status < 300) resolve();
+          else reject(new NetworkError(`Upload OVH \xE9chou\xE9 (${xhr.status})`));
+        });
+        xhr.addEventListener(
+          "error",
+          () => reject(new NetworkError("Erreur r\xE9seau lors de l'upload OVH."))
+        );
+        xhr.send(file);
+      });
+    }
+    const res = await fetch(url, {
+      method: "PUT",
+      headers: { "Content-Type": contentType },
+      body: file
+    });
+    if (!res.ok) throw new NetworkError(`Upload OVH \xE9chou\xE9 (${res.status})`);
+  }
+};
+
 // src/token.ts
 var KEYS = {
   access: "frenchbaas_access_token",
@@ -527,6 +682,7 @@ var FrenchBaasClient = class {
     this._tokenStore = new TokenStore(config.storage ?? "memory");
     this._http = new HttpClient(baseUrl, config.apiKey, this._tokenStore);
     this.auth = new AuthModule(this._http, this._tokenStore, baseUrl, config.apiKey);
+    this.storage = new StorageModule(this._http);
   }
   /**
    * Retourne un client pour une collection spécifique.
@@ -558,6 +714,7 @@ var FrenchBaasClient = class {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthError,
+  ConflictError,
   FrenchBaas,
   FrenchBaasError,
   NetworkError,

package/dist/index.d.mts

@@ -49,13 +49,20 @@ interface GetOptions {
     perPage?: number;
     /**
      * Filtres sur les champs du document.
-     * - Champ string/number/boolean : égalité exacte
-     * - Champ references : l'UUID doit être présent dans le tableau
      *
-     * @example { status: 'pending' }
-     * @example { category_ids: '3e0a5843-...' }
+     * - Valeur unique (string)   → égalité exacte ou contient (references/array)
+     * - Tableau string[]         → OR  : field = v1 OU v2 / contient v1 OU v2
+     * - { and: string[] }        → AND : uniquement pour references/array — contient tous les éléments
+     *
+     * @example { status: 'active' }
+     * @example { status: ['active', 'pending'] }
+     * @example { category_ids: 'uuid1' }
+     * @example { category_ids: ['uuid1', 'uuid2'] }
+     * @example { category_ids: { and: ['uuid1', 'uuid2'] } }
      */
-    filter?: Record<string, string>;
+    filter?: Record<string, string | string[] | {
+        and: string[];
+    }>;
 }
 type FieldType = 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'object' | 'datetime';
 interface SchemaField {
@@ -70,6 +77,44 @@ interface CollectionSchema {
     visibility: 'public' | 'authenticated' | 'private';
     schema: SchemaField[];
 }
+interface StorageBucket {
+    id: string;
+    name: string;
+    visibility: 'public' | 'private';
+    public: boolean;
+    created_at: string;
+}
+interface StorageObject {
+    id: string;
+    name: string;
+    content_type: string;
+    size: number;
+    created_by: string | null;
+    created_at: string;
+    /** URL publique — présente uniquement si le bucket est public */
+    url?: string;
+}
+interface StorageListOptions {
+    /** Numéro de page (défaut: 1) */
+    page?: number;
+    /** Fichiers par page — max 100 (défaut: 50) */
+    perPage?: number;
+    /** Filtre les fichiers dont le nom commence par ce préfixe */
+    prefix?: string;
+}
+interface StorageListResult {
+    data: StorageObject[];
+    meta: PaginationMeta;
+}
+interface StorageUploadOptions {
+    /** Force le Content-Type (sinon déduit de file.type) */
+    contentType?: string;
+    /**
+     * Callback appelé pendant le PUT vers OVH (0–100).
+     * Nécessite XMLHttpRequest (navigateur). Ignoré côté Node/SSR.
+     */
+    onProgress?: (pct: number) => void;
+}
 interface OpenApiSpec {
     openapi: string;
     info: Record<string, unknown>;
@@ -134,7 +179,7 @@ declare class HttpClient {
     constructor(_baseUrl: string, _apiKey: string, _tokenStore: TokenStore);
     /** Enregistre la fonction de refresh (injectée par AuthModule). */
     setRefreshFn(fn: RefreshFn): void;
-    get<T>(path: string, params?: Record<string, string | number | undefined>): Promise<T>;
+    get<T>(path: string, params?: Record<string, string | number | string[] | undefined>): Promise<T>;
     post<T>(path: string, body?: unknown): Promise<T>;
     patch<T>(path: string, body?: unknown): Promise<T>;
     delete<T>(path: string): Promise<T>;
@@ -276,6 +321,93 @@ declare class CollectionClient<T = Record<string, unknown>> {
     schema(): Promise<CollectionSchema>;
 }
 
+/**
+ * Module storage — découverte des buckets et accès aux opérations par bucket.
+ *
+ * @example
+ * ```ts
+ * // Lister les buckets (pas de Bearer requis)
+ * const buckets = await client.storage.listBuckets()
+ *
+ * // Opérations sur un bucket spécifique
+ * const bucket = client.storage.bucket('bucket-uuid')
+ * const obj    = await bucket.upload(file, 'photo.jpg')
+ * const list   = await bucket.listObjects({ prefix: 'users/123/' })
+ * const { url } = await bucket.getUrl(obj.id)
+ * await bucket.delete(obj.id)
+ * ```
+ */
+declare class StorageModule {
+    private readonly _http;
+    constructor(_http: HttpClient);
+    /**
+     * Liste tous les buckets du projet.
+     *
+     * Authentification par API key uniquement — pas de Bearer requis.
+     * Usage principal : découverte des IDs pendant la construction de l'app.
+     */
+    listBuckets(): Promise<StorageBucket[]>;
+    /**
+     * Retourne un client pour opérer sur un bucket spécifique.
+     *
+     * @param bucketId UUID du bucket (visible dans Dashboard → Storage)
+     */
+    bucket(bucketId: string): StorageBucketClient;
+}
+/**
+ * Client pour les opérations sur un bucket spécifique.
+ */
+declare class StorageBucketClient {
+    private readonly _bucketId;
+    private readonly _http;
+    constructor(_bucketId: string, _http: HttpClient);
+    /**
+     * Liste les fichiers du bucket avec pagination et filtre préfixe.
+     *
+     * - Bucket **public** : Bearer non requis — retourne tous les fichiers.
+     * - Bucket **privé**  : Bearer requis — retourne uniquement les fichiers du user connecté.
+     *
+     * @example
+     * const { data, meta } = await bucket.listObjects({ prefix: 'users/123/', perPage: 20 })
+     */
+    listObjects(options?: StorageListOptions): Promise<StorageListResult>;
+    /**
+     * Upload un fichier en 3 étapes : présignature → PUT direct vers OVH → confirmation.
+     *
+     * Bearer requis. La progression PUT (0–100 %) peut être suivie via `options.onProgress`.
+     *
+     * @param file     Fichier ou Blob à uploader
+     * @param name     Nom dans le bucket (ex: "photo.jpg", "users/123/avatar.jpg")
+     * @param options  contentType (override), onProgress
+     *
+     * @example
+     * const obj = await bucket.upload(file, 'avatar.jpg', {
+     *   onProgress: pct => console.log(`${pct}%`)
+     * })
+     */
+    upload(file: File | Blob, name: string, options?: StorageUploadOptions): Promise<StorageObject>;
+    /**
+     * Retourne l'URL d'accès à un fichier.
+     *
+     * - Bucket **public**  : URL publique permanente, Bearer non requis.
+     * - Bucket **privé**   : URL signée (TTL 3600 s), Bearer requis, créateur uniquement.
+     */
+    getUrl(objectId: string): Promise<{
+        url: string;
+        expires_in?: number;
+    }>;
+    /**
+     * Supprime un fichier du bucket.
+     * Bearer requis. Seul le créateur du fichier peut le supprimer.
+     */
+    delete(objectId: string): Promise<void>;
+    /**
+     * PUT direct vers l'URL présignée OVH.
+     * Utilise XHR (si disponible) pour le suivi de progression, sinon fetch.
+     */
+    private _putToOvh;
+}
+
 /**
  * Client principal FrenchBaas.
  *
@@ -296,6 +428,8 @@ declare class CollectionClient<T = Record<string, unknown>> {
 declare class FrenchBaasClient {
     /** Module d'authentification — signUp, login, logout, getUser */
     readonly auth: AuthModule;
+    /** Module storage — listBuckets, bucket(id).upload / listObjects / getUrl / delete */
+    readonly storage: StorageModule;
     private readonly _http;
     private readonly _tokenStore;
     constructor(config: FrenchBaasConfig);
@@ -383,5 +517,13 @@ declare class RateLimitError extends FrenchBaasError {
 declare class ServerError extends FrenchBaasError {
     constructor(message?: string, status?: number);
 }
+/**
+ * Conflit de ressource — 409.
+ * Levée sur storage : un fichier avec ce nom existe déjà dans le bucket,
+ * déposé par un autre utilisateur.
+ */
+declare class ConflictError extends FrenchBaasError {
+    constructor(message?: string);
+}
 
-export { AuthError, type AuthResult, type CollectionSchema, type Document, type DocumentsPage, type FieldType, FrenchBaasClient as FrenchBaas, type FrenchBaasConfig, FrenchBaasError, type GetOptions, NetworkError, NotFoundError, type OpenApiSpec, type PaginationMeta, QuotaError, RateLimitError, type RefreshResult, type SchemaField, ServerError, type User, ValidationError };
+export { AuthError, type AuthResult, type CollectionSchema, ConflictError, type Document, type DocumentsPage, type FieldType, FrenchBaasClient as FrenchBaas, type FrenchBaasConfig, FrenchBaasError, type GetOptions, NetworkError, NotFoundError, type OpenApiSpec, type PaginationMeta, QuotaError, RateLimitError, type RefreshResult, type SchemaField, ServerError, type StorageBucket, type StorageListOptions, type StorageListResult, type StorageObject, type StorageUploadOptions, type User, ValidationError };

package/dist/index.d.ts

@@ -49,13 +49,20 @@ interface GetOptions {
     perPage?: number;
     /**
      * Filtres sur les champs du document.
-     * - Champ string/number/boolean : égalité exacte
-     * - Champ references : l'UUID doit être présent dans le tableau
      *
-     * @example { status: 'pending' }
-     * @example { category_ids: '3e0a5843-...' }
+     * - Valeur unique (string)   → égalité exacte ou contient (references/array)
+     * - Tableau string[]         → OR  : field = v1 OU v2 / contient v1 OU v2
+     * - { and: string[] }        → AND : uniquement pour references/array — contient tous les éléments
+     *
+     * @example { status: 'active' }
+     * @example { status: ['active', 'pending'] }
+     * @example { category_ids: 'uuid1' }
+     * @example { category_ids: ['uuid1', 'uuid2'] }
+     * @example { category_ids: { and: ['uuid1', 'uuid2'] } }
      */
-    filter?: Record<string, string>;
+    filter?: Record<string, string | string[] | {
+        and: string[];
+    }>;
 }
 type FieldType = 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'object' | 'datetime';
 interface SchemaField {
@@ -70,6 +77,44 @@ interface CollectionSchema {
     visibility: 'public' | 'authenticated' | 'private';
     schema: SchemaField[];
 }
+interface StorageBucket {
+    id: string;
+    name: string;
+    visibility: 'public' | 'private';
+    public: boolean;
+    created_at: string;
+}
+interface StorageObject {
+    id: string;
+    name: string;
+    content_type: string;
+    size: number;
+    created_by: string | null;
+    created_at: string;
+    /** URL publique — présente uniquement si le bucket est public */
+    url?: string;
+}
+interface StorageListOptions {
+    /** Numéro de page (défaut: 1) */
+    page?: number;
+    /** Fichiers par page — max 100 (défaut: 50) */
+    perPage?: number;
+    /** Filtre les fichiers dont le nom commence par ce préfixe */
+    prefix?: string;
+}
+interface StorageListResult {
+    data: StorageObject[];
+    meta: PaginationMeta;
+}
+interface StorageUploadOptions {
+    /** Force le Content-Type (sinon déduit de file.type) */
+    contentType?: string;
+    /**
+     * Callback appelé pendant le PUT vers OVH (0–100).
+     * Nécessite XMLHttpRequest (navigateur). Ignoré côté Node/SSR.
+     */
+    onProgress?: (pct: number) => void;
+}
 interface OpenApiSpec {
     openapi: string;
     info: Record<string, unknown>;
@@ -134,7 +179,7 @@ declare class HttpClient {
     constructor(_baseUrl: string, _apiKey: string, _tokenStore: TokenStore);
     /** Enregistre la fonction de refresh (injectée par AuthModule). */
     setRefreshFn(fn: RefreshFn): void;
-    get<T>(path: string, params?: Record<string, string | number | undefined>): Promise<T>;
+    get<T>(path: string, params?: Record<string, string | number | string[] | undefined>): Promise<T>;
     post<T>(path: string, body?: unknown): Promise<T>;
     patch<T>(path: string, body?: unknown): Promise<T>;
     delete<T>(path: string): Promise<T>;
@@ -276,6 +321,93 @@ declare class CollectionClient<T = Record<string, unknown>> {
     schema(): Promise<CollectionSchema>;
 }
 
+/**
+ * Module storage — découverte des buckets et accès aux opérations par bucket.
+ *
+ * @example
+ * ```ts
+ * // Lister les buckets (pas de Bearer requis)
+ * const buckets = await client.storage.listBuckets()
+ *
+ * // Opérations sur un bucket spécifique
+ * const bucket = client.storage.bucket('bucket-uuid')
+ * const obj    = await bucket.upload(file, 'photo.jpg')
+ * const list   = await bucket.listObjects({ prefix: 'users/123/' })
+ * const { url } = await bucket.getUrl(obj.id)
+ * await bucket.delete(obj.id)
+ * ```
+ */
+declare class StorageModule {
+    private readonly _http;
+    constructor(_http: HttpClient);
+    /**
+     * Liste tous les buckets du projet.
+     *
+     * Authentification par API key uniquement — pas de Bearer requis.
+     * Usage principal : découverte des IDs pendant la construction de l'app.
+     */
+    listBuckets(): Promise<StorageBucket[]>;
+    /**
+     * Retourne un client pour opérer sur un bucket spécifique.
+     *
+     * @param bucketId UUID du bucket (visible dans Dashboard → Storage)
+     */
+    bucket(bucketId: string): StorageBucketClient;
+}
+/**
+ * Client pour les opérations sur un bucket spécifique.
+ */
+declare class StorageBucketClient {
+    private readonly _bucketId;
+    private readonly _http;
+    constructor(_bucketId: string, _http: HttpClient);
+    /**
+     * Liste les fichiers du bucket avec pagination et filtre préfixe.
+     *
+     * - Bucket **public** : Bearer non requis — retourne tous les fichiers.
+     * - Bucket **privé**  : Bearer requis — retourne uniquement les fichiers du user connecté.
+     *
+     * @example
+     * const { data, meta } = await bucket.listObjects({ prefix: 'users/123/', perPage: 20 })
+     */
+    listObjects(options?: StorageListOptions): Promise<StorageListResult>;
+    /**
+     * Upload un fichier en 3 étapes : présignature → PUT direct vers OVH → confirmation.
+     *
+     * Bearer requis. La progression PUT (0–100 %) peut être suivie via `options.onProgress`.
+     *
+     * @param file     Fichier ou Blob à uploader
+     * @param name     Nom dans le bucket (ex: "photo.jpg", "users/123/avatar.jpg")
+     * @param options  contentType (override), onProgress
+     *
+     * @example
+     * const obj = await bucket.upload(file, 'avatar.jpg', {
+     *   onProgress: pct => console.log(`${pct}%`)
+     * })
+     */
+    upload(file: File | Blob, name: string, options?: StorageUploadOptions): Promise<StorageObject>;
+    /**
+     * Retourne l'URL d'accès à un fichier.
+     *
+     * - Bucket **public**  : URL publique permanente, Bearer non requis.
+     * - Bucket **privé**   : URL signée (TTL 3600 s), Bearer requis, créateur uniquement.
+     */
+    getUrl(objectId: string): Promise<{
+        url: string;
+        expires_in?: number;
+    }>;
+    /**
+     * Supprime un fichier du bucket.
+     * Bearer requis. Seul le créateur du fichier peut le supprimer.
+     */
+    delete(objectId: string): Promise<void>;
+    /**
+     * PUT direct vers l'URL présignée OVH.
+     * Utilise XHR (si disponible) pour le suivi de progression, sinon fetch.
+     */
+    private _putToOvh;
+}
+
 /**
  * Client principal FrenchBaas.
  *
@@ -296,6 +428,8 @@ declare class CollectionClient<T = Record<string, unknown>> {
 declare class FrenchBaasClient {
     /** Module d'authentification — signUp, login, logout, getUser */
     readonly auth: AuthModule;
+    /** Module storage — listBuckets, bucket(id).upload / listObjects / getUrl / delete */
+    readonly storage: StorageModule;
     private readonly _http;
     private readonly _tokenStore;
     constructor(config: FrenchBaasConfig);
@@ -383,5 +517,13 @@ declare class RateLimitError extends FrenchBaasError {
 declare class ServerError extends FrenchBaasError {
     constructor(message?: string, status?: number);
 }
+/**
+ * Conflit de ressource — 409.
+ * Levée sur storage : un fichier avec ce nom existe déjà dans le bucket,
+ * déposé par un autre utilisateur.
+ */
+declare class ConflictError extends FrenchBaasError {
+    constructor(message?: string);
+}
 
-export { AuthError, type AuthResult, type CollectionSchema, type Document, type DocumentsPage, type FieldType, FrenchBaasClient as FrenchBaas, type FrenchBaasConfig, FrenchBaasError, type GetOptions, NetworkError, NotFoundError, type OpenApiSpec, type PaginationMeta, QuotaError, RateLimitError, type RefreshResult, type SchemaField, ServerError, type User, ValidationError };
+export { AuthError, type AuthResult, type CollectionSchema, ConflictError, type Document, type DocumentsPage, type FieldType, FrenchBaasClient as FrenchBaas, type FrenchBaasConfig, FrenchBaasError, type GetOptions, NetworkError, NotFoundError, type OpenApiSpec, type PaginationMeta, QuotaError, RateLimitError, type RefreshResult, type SchemaField, ServerError, type StorageBucket, type StorageListOptions, type StorageListResult, type StorageObject, type StorageUploadOptions, type User, ValidationError };

package/dist/index.js

@@ -57,6 +57,13 @@ var ServerError = class extends FrenchBaasError {
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
+var ConflictError = class extends FrenchBaasError {
+  constructor(message = "Conflit : la ressource existe d\xE9j\xE0.") {
+    super(message, 409);
+    this.name = "ConflictError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
 
 // src/auth.ts
 var AuthModule = class {
@@ -177,7 +184,14 @@ var CollectionClient = class {
     };
     if (options.filter) {
       for (const [key, val] of Object.entries(options.filter)) {
-        if (val !== void 0) params[`filter[${key}]`] = val;
+        if (val === void 0) continue;
+        if (typeof val === "string") {
+          params[`filter[${key}]`] = val;
+        } else if (Array.isArray(val)) {
+          params[`filter[${key}][]`] = val;
+        } else {
+          params[`filter[${key}][and][]`] = val.and;
+        }
       }
     }
     const res = await this._http.get(
@@ -280,7 +294,12 @@ var HttpClient = class {
     const url = new URL(this._baseUrl + path);
     if (params) {
       for (const [k, v] of Object.entries(params)) {
-        if (v !== void 0) url.searchParams.set(k, String(v));
+        if (v === void 0) continue;
+        if (Array.isArray(v)) {
+          for (const item of v) url.searchParams.append(k, item);
+        } else {
+          url.searchParams.set(k, String(v));
+        }
       }
     }
     return this._request("GET", url.toString(), void 0, true);
@@ -370,6 +389,8 @@ var HttpClient = class {
         const details = err.errors ?? [];
         throw new ValidationError(details.length ? details.join(", ") : msg, details);
       }
+      case 409:
+        throw new ConflictError(msg);
       case 429:
         throw new RateLimitError();
       default:
@@ -379,6 +400,139 @@ var HttpClient = class {
   }
 };
 
+// src/storage.ts
+var StorageModule = class {
+  constructor(_http) {
+    this._http = _http;
+  }
+  /**
+   * Liste tous les buckets du projet.
+   *
+   * Authentification par API key uniquement — pas de Bearer requis.
+   * Usage principal : découverte des IDs pendant la construction de l'app.
+   */
+  async listBuckets() {
+    const res = await this._http.get(
+      "/sdk/storage/buckets"
+    );
+    return res.data;
+  }
+  /**
+   * Retourne un client pour opérer sur un bucket spécifique.
+   *
+   * @param bucketId UUID du bucket (visible dans Dashboard → Storage)
+   */
+  bucket(bucketId) {
+    if (!bucketId || typeof bucketId !== "string") {
+      throw new Error("[FrenchBaas] storage.bucket() requiert un UUID de bucket valide.");
+    }
+    return new StorageBucketClient(bucketId, this._http);
+  }
+};
+var StorageBucketClient = class {
+  constructor(_bucketId, _http) {
+    this._bucketId = _bucketId;
+    this._http = _http;
+  }
+  /**
+   * Liste les fichiers du bucket avec pagination et filtre préfixe.
+   *
+   * - Bucket **public** : Bearer non requis — retourne tous les fichiers.
+   * - Bucket **privé**  : Bearer requis — retourne uniquement les fichiers du user connecté.
+   *
+   * @example
+   * const { data, meta } = await bucket.listObjects({ prefix: 'users/123/', perPage: 20 })
+   */
+  async listObjects(options = {}) {
+    const params = {};
+    if (options.page !== void 0) params["page"] = options.page;
+    if (options.perPage !== void 0) params["per_page"] = options.perPage;
+    if (options.prefix) params["prefix"] = options.prefix;
+    return this._http.get(
+      `/sdk/storage/buckets/${this._bucketId}/objects`,
+      params
+    );
+  }
+  /**
+   * Upload un fichier en 3 étapes : présignature → PUT direct vers OVH → confirmation.
+   *
+   * Bearer requis. La progression PUT (0–100 %) peut être suivie via `options.onProgress`.
+   *
+   * @param file     Fichier ou Blob à uploader
+   * @param name     Nom dans le bucket (ex: "photo.jpg", "users/123/avatar.jpg")
+   * @param options  contentType (override), onProgress
+   *
+   * @example
+   * const obj = await bucket.upload(file, 'avatar.jpg', {
+   *   onProgress: pct => console.log(`${pct}%`)
+   * })
+   */
+  async upload(file, name, options = {}) {
+    const contentType = options.contentType ?? ((file instanceof File ? file.type : "") || "application/octet-stream");
+    const presign = await this._http.post(`/sdk/storage/buckets/${this._bucketId}/upload`, {
+      name,
+      content_type: contentType,
+      size: file.size
+    });
+    await this._putToOvh(presign.upload_url, file, contentType, options.onProgress);
+    const confirm = await this._http.post(
+      `/sdk/storage/buckets/${this._bucketId}/confirm`,
+      { name, key: presign.key, content_type: contentType }
+    );
+    return confirm.data;
+  }
+  /**
+   * Retourne l'URL d'accès à un fichier.
+   *
+   * - Bucket **public**  : URL publique permanente, Bearer non requis.
+   * - Bucket **privé**   : URL signée (TTL 3600 s), Bearer requis, créateur uniquement.
+   */
+  async getUrl(objectId) {
+    return this._http.get(
+      `/sdk/storage/buckets/${this._bucketId}/objects/${objectId}/url`
+    );
+  }
+  /**
+   * Supprime un fichier du bucket.
+   * Bearer requis. Seul le créateur du fichier peut le supprimer.
+   */
+  async delete(objectId) {
+    await this._http.delete(`/sdk/storage/buckets/${this._bucketId}/objects/${objectId}`);
+  }
+  // ── Private ──────────────────────────────────────────────────────────────
+  /**
+   * PUT direct vers l'URL présignée OVH.
+   * Utilise XHR (si disponible) pour le suivi de progression, sinon fetch.
+   */
+  async _putToOvh(url, file, contentType, onProgress) {
+    if (typeof onProgress === "function" && typeof XMLHttpRequest !== "undefined") {
+      return new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
+        xhr.open("PUT", url);
+        xhr.setRequestHeader("Content-Type", contentType);
+        xhr.upload.addEventListener("progress", (e) => {
+          if (e.lengthComputable) onProgress(Math.round(e.loaded / e.total * 100));
+        });
+        xhr.addEventListener("load", () => {
+          if (xhr.status >= 200 && xhr.status < 300) resolve();
+          else reject(new NetworkError(`Upload OVH \xE9chou\xE9 (${xhr.status})`));
+        });
+        xhr.addEventListener(
+          "error",
+          () => reject(new NetworkError("Erreur r\xE9seau lors de l'upload OVH."))
+        );
+        xhr.send(file);
+      });
+    }
+    const res = await fetch(url, {
+      method: "PUT",
+      headers: { "Content-Type": contentType },
+      body: file
+    });
+    if (!res.ok) throw new NetworkError(`Upload OVH \xE9chou\xE9 (${res.status})`);
+  }
+};
+
 // src/token.ts
 var KEYS = {
   access: "frenchbaas_access_token",
@@ -493,6 +647,7 @@ var FrenchBaasClient = class {
     this._tokenStore = new TokenStore(config.storage ?? "memory");
     this._http = new HttpClient(baseUrl, config.apiKey, this._tokenStore);
     this.auth = new AuthModule(this._http, this._tokenStore, baseUrl, config.apiKey);
+    this.storage = new StorageModule(this._http);
   }
   /**
    * Retourne un client pour une collection spécifique.
@@ -523,6 +678,7 @@ var FrenchBaasClient = class {
 };
 export {
   AuthError,
+  ConflictError,
   FrenchBaasClient as FrenchBaas,
   FrenchBaasError,
   NetworkError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frenchbaas/js",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "SDK JavaScript officiel pour FrenchBaas",
   "author": "FrenchBaas",
   "license": "MIT",