@frenchbaas/js 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# @frenchbaas/js
+
+SDK JavaScript officiel pour [FrenchBaas](https://frenchbaas.fr) — le BaaS français.
+
+## Installation
+
+```bash
+npm install @frenchbaas/js
+```
+
+## Démarrage rapide
+
+```js
+import { FrenchBaas } from '@frenchbaas/js'
+
+const client = new FrenchBaas({
+  url:    'https://api.frenchbaas.fr',
+  apiKey: 'votre-clé-api',
+})
+```
+
+## Auth
+
+```js
+// Inscription
+const { user } = await client.auth.signUp({ email: 'a@b.com', password: 'secret' })
+
+// Connexion
+const { user } = await client.auth.login({ email: 'a@b.com', password: 'secret' })
+
+// Déconnexion
+await client.auth.logout()
+
+// État
+client.auth.getUser()     // { id, email } | null
+client.auth.isLoggedIn()  // boolean
+```
+
+## Collections (documents)
+
+```js
+const col = client.collection('collection-uuid')
+
+// Lire (paginé)
+const { data, meta } = await col.get({ page: 1, perPage: 20 })
+
+// Créer
+const doc = await col.create({ title: 'Hello', published: true })
+
+// Mettre à jour
+const doc = await col.update('doc-id', { title: 'Modifié' })
+
+// Supprimer
+await col.delete('doc-id')
+
+// Schéma de la collection
+const schema = await col.schema()
+```
+
+## Gestion des erreurs
+
+```js
+import { AuthError, ValidationError, NotFoundError, QuotaError, NetworkError } from '@frenchbaas/js'
+
+try {
+  await client.collection('col-id').create({ title: 'Test' })
+} catch (e) {
+  if (e instanceof AuthError)            console.error('Non connecté')
+  if (e instanceof ValidationError)      console.error('Données invalides', e.errors)
+  if (e instanceof NotFoundError)        console.error('Introuvable')
+  if (e instanceof QuotaError)           console.error('Quota dépassé')
+  if (e instanceof NetworkError)         console.error('Hors ligne')
+}
+```
+
+## Options
+
+```js
+// Persister la session dans localStorage (rechargement de page)
+const client = new FrenchBaas({
+  url:     'https://api.frenchbaas.fr',
+  apiKey:  'votre-clé-api',
+  storage: 'localStorage', // défaut : 'memory'
+})
+```
+
+## Fonctionnalités automatiques
+
+- **Refresh token transparent** — access token rafraîchi automatiquement avant expiration
+- **Retry sur 401** — relance la requête après refresh sans intervention du développeur
+- **Déduplication** — plusieurs requêtes simultanées ne déclenchent qu'un seul refresh
+- **Erreurs typées** — chaque erreur HTTP a sa classe TypeScript dédiée
+- **Zero dépendance** — aucune dépendance runtime
+- **TypeScript** — types inclus
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,541 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthError: () => AuthError,
+  FrenchBaas: () => FrenchBaasClient,
+  FrenchBaasError: () => FrenchBaasError,
+  NetworkError: () => NetworkError,
+  NotFoundError: () => NotFoundError,
+  QuotaError: () => QuotaError,
+  RateLimitError: () => RateLimitError,
+  ServerError: () => ServerError,
+  ValidationError: () => ValidationError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var FrenchBaasError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "FrenchBaasError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AuthError = class extends FrenchBaasError {
+  constructor(message, status) {
+    super(message, status);
+    this.name = "AuthError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var NetworkError = class extends FrenchBaasError {
+  constructor(message = "Impossible de joindre le serveur FrenchBaas.") {
+    super(message);
+    this.name = "NetworkError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var ValidationError = class extends FrenchBaasError {
+  constructor(message, errors = []) {
+    super(message, 422);
+    this.errors = errors;
+    this.name = "ValidationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var NotFoundError = class extends FrenchBaasError {
+  constructor(message = "Ressource introuvable.") {
+    super(message, 404);
+    this.name = "NotFoundError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var QuotaError = class extends FrenchBaasError {
+  constructor(message) {
+    super(message, 403);
+    this.name = "QuotaError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var RateLimitError = class extends FrenchBaasError {
+  constructor(message = "Trop de requ\xEAtes. Veuillez r\xE9essayer dans quelques instants.") {
+    super(message, 429);
+    this.name = "RateLimitError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var ServerError = class extends FrenchBaasError {
+  constructor(message = "Erreur interne du serveur.", status) {
+    super(message, status);
+    this.name = "ServerError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/auth.ts
+var AuthModule = class {
+  constructor(_http, _tokenStore, _baseUrl, _apiKey) {
+    this._http = _http;
+    this._tokenStore = _tokenStore;
+    this._baseUrl = _baseUrl;
+    this._apiKey = _apiKey;
+    this._http.setRefreshFn(() => this._refresh());
+  }
+  /**
+   * Inscrit un nouvel utilisateur final.
+   * Stocke automatiquement les tokens après inscription réussie.
+   */
+  async signUp(params) {
+    const res = await this._http.post("/sdk/auth/signup", params);
+    return this._storeAndReturn(res);
+  }
+  /**
+   * Connecte un utilisateur existant.
+   * Stocke automatiquement les tokens après connexion réussie.
+   */
+  async login(params) {
+    const res = await this._http.post("/sdk/auth/login", params);
+    return this._storeAndReturn(res);
+  }
+  /**
+   * Déconnecte l'utilisateur et efface tous les tokens stockés.
+   * L'appel API est best-effort (stateless côté serveur).
+   */
+  async logout() {
+    try {
+      await this._http.post("/sdk/auth/logout");
+    } finally {
+      this._tokenStore.clear();
+    }
+  }
+  /**
+   * Retourne l'utilisateur courant depuis la mémoire (synchrone).
+   * Retourne null si non connecté ou si la page a été rechargée
+   * avec la stratégie 'memory'.
+   */
+  getUser() {
+    return this._tokenStore.user;
+  }
+  /**
+   * Indique si l'utilisateur a une session active (refresh token valide).
+   */
+  isLoggedIn() {
+    return this._tokenStore.refreshToken !== null && !this._tokenStore.isRefreshTokenExpired();
+  }
+  /**
+   * Refresh interne — appelé automatiquement par HttpClient.
+   * Utilise un fetch direct pour éviter la récursion infinie.
+   * Le refresh token expiré → logout propre + AuthError.
+   */
+  async _refresh() {
+    const refreshToken = this._tokenStore.refreshToken;
+    if (!refreshToken || this._tokenStore.isRefreshTokenExpired()) {
+      this._tokenStore.clear();
+      throw new AuthError("Session expir\xE9e. Veuillez vous reconnecter.", 401);
+    }
+    let response;
+    try {
+      response = await fetch(`${this._baseUrl}/sdk/auth/refresh`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Accept": "application/json",
+          "X-Api-Key": this._apiKey
+        },
+        body: JSON.stringify({ refresh_token: refreshToken })
+      });
+    } catch {
+      throw new NetworkError();
+    }
+    if (!response.ok) {
+      this._tokenStore.clear();
+      let msg = "Session expir\xE9e. Veuillez vous reconnecter.";
+      try {
+        const body2 = await response.json();
+        if (body2.error) msg = body2.error;
+      } catch {
+      }
+      throw new AuthError(msg, 401);
+    }
+    const body = await response.json();
+    this._tokenStore.updateTokens(
+      body.data.access_token,
+      body.data.refresh_token
+    );
+  }
+  _storeAndReturn(res) {
+    const { access_token, refresh_token, user } = res.data;
+    if (!user) throw new AuthError("R\xE9ponse serveur invalide : utilisateur manquant.");
+    this._tokenStore.set({ accessToken: access_token, refreshToken: refresh_token, user });
+    return { user, access_token, refresh_token };
+  }
+};
+
+// src/collection.ts
+var CollectionClient = class {
+  constructor(_collectionId, _http) {
+    this._collectionId = _collectionId;
+    this._http = _http;
+  }
+  /**
+   * Liste les documents de la collection avec pagination.
+   * La visibilité (public/authenticated/private) est gérée côté serveur.
+   *
+   * @param options.page    Numéro de page (défaut: 1)
+   * @param options.perPage Documents par page, max 100 (défaut: 50)
+   */
+  async get(options = {}) {
+    const params = {
+      page: options.page,
+      per_page: options.perPage
+    };
+    const res = await this._http.get(
+      `/sdk/collections/${this._collectionId}/documents`,
+      params
+    );
+    return { data: res.data, meta: res.meta };
+  }
+  /**
+   * Crée un nouveau document dans la collection.
+   * Les champs sont validés contre le schéma côté serveur.
+   *
+   * @param data Données du document (doit respecter le schéma de la collection)
+   */
+  async create(data) {
+    const res = await this._http.post(
+      `/sdk/collections/${this._collectionId}/documents`,
+      { data }
+    );
+    return res.data;
+  }
+  /**
+   * Met à jour partiellement un document (merge).
+   * Seuls les champs fournis sont mis à jour, les autres restent inchangés.
+   *
+   * - Collection private : seul le créateur peut modifier.
+   * - Collection authenticated/public : tout utilisateur authentifié peut modifier.
+   *
+   * @param documentId UUID du document à modifier
+   * @param data       Champs à mettre à jour
+   */
+  async update(documentId, data) {
+    const res = await this._http.patch(
+      `/sdk/documents/${documentId}`,
+      { data }
+    );
+    return res.data;
+  }
+  /**
+   * Supprime un document.
+   *
+   * - Collection private : seul le créateur peut supprimer.
+   * - Collection authenticated/public : tout utilisateur authentifié peut supprimer.
+   *
+   * @param documentId UUID du document à supprimer
+   */
+  async delete(documentId) {
+    await this._http.delete(`/sdk/documents/${documentId}`);
+  }
+  /**
+   * Retourne le schéma de la collection (nom des champs, types, visibilité).
+   * Utile pour construire des formulaires dynamiques.
+   */
+  async schema() {
+    const res = await this._http.get(
+      `/sdk/collections/${this._collectionId}/schema`
+    );
+    return res.data;
+  }
+};
+
+// src/http.ts
+var HttpClient = class {
+  constructor(_baseUrl, _apiKey, _tokenStore) {
+    this._baseUrl = _baseUrl;
+    this._apiKey = _apiKey;
+    this._tokenStore = _tokenStore;
+    this._refreshFn = null;
+    this._refreshing = null;
+  }
+  /** Enregistre la fonction de refresh (injectée par AuthModule). */
+  setRefreshFn(fn) {
+    this._refreshFn = fn;
+  }
+  async get(path, params) {
+    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));
+      }
+    }
+    return this._request("GET", url.toString(), void 0, true);
+  }
+  async post(path, body) {
+    return this._request("POST", this._baseUrl + path, body, true);
+  }
+  async patch(path, body) {
+    return this._request("PATCH", this._baseUrl + path, body, true);
+  }
+  async delete(path) {
+    return this._request("DELETE", this._baseUrl + path, void 0, true);
+  }
+  async _request(method, url, body, canRetry) {
+    if (canRetry && this._tokenStore.accessToken && this._tokenStore.isAccessTokenExpired()) {
+      await this._triggerRefresh();
+    }
+    const response = await this._fetch(method, url, body);
+    if (response.status === 401 && canRetry && this._refreshFn && !this._tokenStore.isRefreshTokenExpired()) {
+      try {
+        await this._triggerRefresh();
+        return this._request(method, url, body, false);
+      } catch {
+        throw new AuthError("Session expir\xE9e. Veuillez vous reconnecter.", 401);
+      }
+    }
+    return this._parseResponse(response);
+  }
+  async _fetch(method, url, body) {
+    const headers = {
+      "Content-Type": "application/json",
+      "Accept": "application/json",
+      "X-Api-Key": this._apiKey
+    };
+    const token = this._tokenStore.accessToken;
+    if (token) headers["Authorization"] = `Bearer ${token}`;
+    try {
+      return await fetch(url, {
+        method,
+        headers,
+        body: body !== void 0 ? JSON.stringify(body) : void 0
+      });
+    } catch {
+      throw new NetworkError();
+    }
+  }
+  /**
+   * Déclenche le refresh en s'assurant qu'un seul refresh tourne à la fois
+   * même si plusieurs requêtes l'appellent simultanément.
+   */
+  _triggerRefresh() {
+    if (!this._refreshFn) return Promise.resolve();
+    if (this._refreshing) return this._refreshing;
+    this._refreshing = this._refreshFn().finally(() => {
+      this._refreshing = null;
+    });
+    return this._refreshing;
+  }
+  async _parseResponse(response) {
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      if (!response.ok) {
+        throw new ServerError(`Erreur serveur (${response.status})`, response.status);
+      }
+      throw new ServerError("R\xE9ponse invalide du serveur.");
+    }
+    if (response.ok) return body;
+    const err = body;
+    const msg = err.error ?? "Une erreur est survenue.";
+    switch (response.status) {
+      case 400:
+        throw new ValidationError(msg);
+      case 401:
+        throw new AuthError(msg, 401);
+      case 403:
+        if (err.quota || /quota|limit|dépass/i.test(msg)) {
+          throw new QuotaError(msg);
+        }
+        throw new AuthError(msg, 403);
+      case 404:
+        throw new NotFoundError(msg);
+      case 413:
+        throw new ValidationError(msg);
+      case 422: {
+        const details = err.errors ?? [];
+        throw new ValidationError(details.length ? details.join(", ") : msg, details);
+      }
+      case 429:
+        throw new RateLimitError();
+      default:
+        if (response.status >= 500) throw new ServerError(msg, response.status);
+        throw new ServerError(msg, response.status);
+    }
+  }
+};
+
+// src/token.ts
+var KEYS = {
+  access: "frenchbaas_access_token",
+  refresh: "frenchbaas_refresh_token",
+  user: "frenchbaas_user"
+};
+var TokenStore = class {
+  constructor(strategy = "memory") {
+    this._state = { accessToken: null, refreshToken: null, user: null };
+    this._strategy = strategy;
+    if (strategy === "localStorage") {
+      this._loadFromStorage();
+    }
+  }
+  get accessToken() {
+    return this._state.accessToken;
+  }
+  get refreshToken() {
+    return this._state.refreshToken;
+  }
+  get user() {
+    return this._state.user;
+  }
+  /** Stocke access token, refresh token et optionnellement l'utilisateur. */
+  set(tokens) {
+    this._state.accessToken = tokens.accessToken;
+    this._state.refreshToken = tokens.refreshToken;
+    if (tokens.user !== void 0) this._state.user = tokens.user;
+    if (this._strategy === "localStorage") this._persist();
+  }
+  /** Met à jour uniquement les tokens (appelé après un refresh — sans user). */
+  updateTokens(accessToken, refreshToken) {
+    this._state.accessToken = accessToken;
+    this._state.refreshToken = refreshToken;
+    if (this._strategy === "localStorage") this._persist();
+  }
+  /** Efface tous les tokens et l'utilisateur (appelé lors du logout). */
+  clear() {
+    this._state = { accessToken: null, refreshToken: null, user: null };
+    if (this._strategy === "localStorage") {
+      try {
+        localStorage.removeItem(KEYS.access);
+        localStorage.removeItem(KEYS.refresh);
+        localStorage.removeItem(KEYS.user);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Vérifie si l'access token est expiré ou expire dans moins de 30 secondes.
+   * Retourne true si absent ou invalide.
+   */
+  isAccessTokenExpired() {
+    return this._isExpired(this._state.accessToken, 3e4);
+  }
+  /**
+   * Vérifie si le refresh token est expiré.
+   * Retourne true si absent ou invalide.
+   */
+  isRefreshTokenExpired() {
+    return this._isExpired(this._state.refreshToken, 0);
+  }
+  _isExpired(token, bufferMs) {
+    if (!token) return true;
+    try {
+      const payload = decodeJwtPayload(token);
+      return payload.exp * 1e3 < Date.now() + bufferMs;
+    } catch {
+      return true;
+    }
+  }
+  _persist() {
+    try {
+      if (this._state.accessToken) localStorage.setItem(KEYS.access, this._state.accessToken);
+      if (this._state.refreshToken) localStorage.setItem(KEYS.refresh, this._state.refreshToken);
+      if (this._state.user) localStorage.setItem(KEYS.user, JSON.stringify(this._state.user));
+    } catch {
+    }
+  }
+  _loadFromStorage() {
+    try {
+      this._state.accessToken = localStorage.getItem(KEYS.access);
+      this._state.refreshToken = localStorage.getItem(KEYS.refresh);
+      const raw = localStorage.getItem(KEYS.user);
+      this._state.user = raw ? JSON.parse(raw) : null;
+    } catch {
+    }
+  }
+};
+function decodeJwtPayload(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) throw new Error("JWT invalide : format incorrect");
+  const base64 = (parts[1] ?? "").replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+  let json;
+  if (typeof atob !== "undefined") {
+    json = atob(padded);
+  } else {
+    json = globalThis.Buffer.from(padded, "base64").toString("utf-8");
+  }
+  const payload = JSON.parse(json);
+  if (typeof payload.exp !== "number") throw new Error("JWT invalide : champ exp manquant");
+  return payload;
+}
+
+// src/client.ts
+var FrenchBaasClient = class {
+  constructor(config) {
+    if (!config.url) throw new Error('[FrenchBaas] La propri\xE9t\xE9 "url" est requise.');
+    if (!config.apiKey) throw new Error('[FrenchBaas] La propri\xE9t\xE9 "apiKey" est requise.');
+    const baseUrl = config.url.replace(/\/$/, "");
+    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);
+  }
+  /**
+   * Retourne un client pour une collection spécifique.
+   *
+   * Le type générique T permet de typer les données des documents :
+   * ```ts
+   * const posts = client.collection<{ title: string; published: boolean }>('uuid')
+   * const doc = await posts.create({ title: 'Hello', published: true })
+   * // doc.data.title est typé string ✓
+   * ```
+   *
+   * @param collectionId UUID de la collection (visible dans le Dashboard)
+   */
+  collection(collectionId) {
+    if (!collectionId || typeof collectionId !== "string") {
+      throw new Error("[FrenchBaas] collection() requiert un UUID de collection valide.");
+    }
+    return new CollectionClient(collectionId, this._http);
+  }
+  /**
+   * Retourne la spécification OpenAPI du projet.
+   * Contient toutes les collections, leurs schémas et les endpoints disponibles.
+   * Utile pour de la génération de code ou de la documentation dynamique.
+   */
+  async getOpenApiSpec() {
+    return this._http.get("/sdk/openapi");
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthError,
+  FrenchBaas,
+  FrenchBaasError,
+  NetworkError,
+  NotFoundError,
+  QuotaError,
+  RateLimitError,
+  ServerError,
+  ValidationError
+});
+//# sourceMappingURL=index.cjs.map