@frenchbaas/js 0.2.2 → 0.2.4

package/README.md

@@ -14,56 +14,136 @@ npm install @frenchbaas/js
 import { FrenchBaas } from '@frenchbaas/js'
 
 const client = new FrenchBaas({
-  url:    'https://app.frenchbaas.com',
-  apiKey: 'votre-clé-api',
+  url:    'https://api.frenchbaas.fr',
+  apiKey: 'votre-clé-api',         // trouvée dans Dashboard → Projet
 })
 ```
 
+---
+
 ## Auth
 
 ```js
 // Inscription
-const { user } = await client.auth.signUp({ email: 'a@b.com', password: 'secret' })
+const { user, access_token } = await client.auth.signUp({ email: 'a@b.com', password: 'secret' })
 
 // Connexion
-const { user } = await client.auth.login({ email: 'a@b.com', password: 'secret' })
+const { user, access_token } = await client.auth.login({ email: 'a@b.com', password: 'secret' })
 
 // Déconnexion
 await client.auth.logout()
 
-// État
+// État de la session
 client.auth.getUser()     // { id, email } | null
 client.auth.isLoggedIn()  // boolean
 ```
 
-## Collections (documents)
+---
+
+## Collections & documents
 
 ```js
-const col = client.collection('collection-uuid')
+const col = client.collection('uuid-de-la-collection')
 
-// Lire (paginé)
+// Lister (paginé, max 100 par page)
 const { data, meta } = await col.get({ page: 1, perPage: 20 })
+// meta → { total, page, per_page, total_pages }
 
-// Récupérer un document par son ID
-const doc = await col.getById('doc-id')
+// Récupérer un document par ID
+const doc = await col.getById('doc-uuid')
+// doc → { id, data, created_at, updated_at }
 
-// Créer
+// Créer un document
 const doc = await col.create({ title: 'Hello', published: true })
 
-// Mettre à jour
-const doc = await col.update('doc-id', { title: 'Modifié' })
+// Mettre à jour (merge partiel — seuls les champs fournis changent)
+const doc = await col.update('doc-uuid', { title: 'Modifié' })
 
 // Supprimer
-await col.delete('doc-id')
+await col.delete('doc-uuid')
+
+// Schéma de la collection (noms de champs, types, visibilité)
+const { schema } = await col.schema()
+```
+
+### Visibilité des collections
+
+| Visibilité | Lecture | Écriture |
+|------------|---------|---------|
+| `public` | Sans token | Token requis |
+| `authenticated` | Token requis | Token requis |
+| `private` | Créateur uniquement | Créateur uniquement |
+
+### Permissions SDK sur les champs
+
+Le développeur peut configurer une permission sur chaque champ d'une collection.
+Ces règles sont appliquées **côté serveur**, de façon transparente pour le SDK.
+
+| Permission | Comportement à la création | Comportement à la mise à jour |
+|---|---|---|
+| `writable` | L'utilisateur écrit librement **(défaut)** | Modifiable |
+| `forced` | Remplacé par la valeur définie par le dev | Ignoré (non modifiable) |
+| `inject_user_id` | Injecté automatiquement avec l'ID de l'utilisateur | Ignoré |
+| `inject_user_email` | Injecté automatiquement avec l'email de l'utilisateur | Ignoré |
+| `inject_timestamp` | Injecté automatiquement avec la date/heure serveur | Ignoré |
+| `readonly` | Ignoré (seul le dev peut écrire ce champ) | Ignoré |
+
+```js
+// Même si vous envoyez role: 'admin', le serveur force 'client' si le champ est en mode forced
+await client.collection('users').create({ role: 'admin', email: 'x@x.com' })
+// → { role: 'client', email: 'x@x.com' }
+
+// Les champs inject_* n'ont pas besoin d'être envoyés
+await client.collection('orders').create({ total: 99.99 })
+// → { total: 99.99, created_by_email: 'user@example.com' }  ← injecté par le serveur
+```
+
+Ces permissions se configurent dans le Dashboard → collection → schéma → colonne **SDK permission**.
+
+---
+
+## Webhooks
+
+Si une collection a un `before_create_url` ou `before_update_url` configuré,
+FrenchBaas appelle votre endpoint **avant chaque écriture en base**.
+Votre serveur peut valider, enrichir ou rejeter les données.
+
+Un rejet lève automatiquement une `ValidationError` côté SDK avec le message
+renvoyé par votre webhook.
 
-// Schéma de la collection
-const schema = await col.schema()
+```js
+import { ValidationError } from '@frenchbaas/js'
+
+try {
+  await client.collection('col-uuid').create({ montant: 150 })
+} catch (e) {
+  if (e instanceof ValidationError) {
+    // e.message contient le message renvoyé par votre webhook
+    // ex : "Stock insuffisant", "Utilisateur banni", etc.
+    console.error('Rejeté par le webhook :', e.message)
+  }
+}
+
+// Même comportement pour update()
+try {
+  await client.collection('col-uuid').update('doc-uuid', { montant: 200 })
+} catch (e) {
+  if (e instanceof ValidationError) {
+    console.error('Mise à jour refusée :', e.message)
+  }
+}
 ```
 
+> La configuration des webhooks (URL, secret HMAC) se fait dans le Dashboard
+> ou via l'API REST. Voir la [documentation webhooks](https://frenchbaas.fr/documentation.html#webhooks).
+
+---
+
 ## Gestion des erreurs
 
 ```ts
 import {
+  FrenchBaasError,
   AuthError,
   ValidationError,
   NotFoundError,
@@ -74,29 +154,54 @@ import {
 } from '@frenchbaas/js'
 
 try {
-  await client.collection('col-id').create({ title: 'Test' })
+  await client.collection('col-uuid').create({ title: 'Test' })
 } catch (e) {
-  if (e instanceof AuthError)       console.error('Non connecté ou session expirée')
-  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 RateLimitError)  console.error('Trop de requêtes, réessayez dans quelques instants')
-  if (e instanceof NetworkError)    console.error('Hors ligne')
-  if (e instanceof ServerError)     console.error('Erreur interne du serveur')
+  if (e instanceof ValidationError) {
+    // Données invalides (schéma) OU rejet par webhook
+    // e.errors → string[] (erreurs de schéma)
+    // e.message → message du webhook si rejet webhook (e.errors sera vide)
+    console.error(e.message, e.errors)
+  }
+  else if (e instanceof AuthError)      console.error('Non connecté ou session expirée')
+  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')
+  else if (e instanceof NetworkError)   console.error('Impossible de joindre le serveur')
+  else if (e instanceof ServerError)    console.error('Erreur interne du serveur')
+  else if (e instanceof FrenchBaasError) console.error('Erreur FrenchBaas :', e.message)
 }
 ```
 
+Toutes les erreurs héritent de `FrenchBaasError` et exposent :
+- `e.message` — description lisible
+- `e.status` — code HTTP (401, 404, 422, 429, 5xx…)
+
+`ValidationError` expose en plus :
+- `e.errors` — tableau de messages de validation (vide si rejet webhook)
+
+---
+
 ## Options
 
 ```js
-// Persister la session dans localStorage (rechargement de page)
 const client = new FrenchBaas({
-  url:     'https://app.frenchbaas.com',
+  url:     'https://api.frenchbaas.fr',
   apiKey:  'votre-clé-api',
-  storage: 'localStorage', // défaut : 'memory'
+  storage: 'localStorage', // 'memory' (défaut) | 'localStorage'
 })
 ```
 
+| Option | Type | Défaut | Description |
+|--------|------|--------|-------------|
+| `url` | `string` | — | URL de votre instance FrenchBaas |
+| `apiKey` | `string` | — | Clé API du projet (Dashboard → Projet) |
+| `storage` | `'memory'` \| `'localStorage'` | `'memory'` | Persistance de la session |
+
+Utilisez `localStorage` pour que la session survive au rechargement de page
+(applications web). Utilisez `memory` pour les environnements serveur (Node.js).
+
+---
+
 ## Fonctionnalités automatiques
 
 - **Refresh token transparent** — access token rafraîchi automatiquement avant expiration
@@ -104,9 +209,10 @@ const client = new FrenchBaas({
 - **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
+- **TypeScript natif** — types `.d.ts` inclus, autocomplétion complète
+
+---
 
 ## License
 
 MIT
-# frenchbaas-js

package/package.json

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