@aurabase/core 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aurabase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# @aurabase/core
+
+Cœur d'infrastructure du SDK Aurabase : type de réponse (`AuraResponse`), erreurs structurées (`AuraError`), stores d'authentification, couche fetch résiliente et le contrat `AuraClientLike`/`BaseService` pour composer un service ou un client alternatif.
+
+![npm](https://img.shields.io/npm/v/@aurabase/core) ![license](https://img.shields.io/badge/license-MIT-blue)
+
+> Pre-release — pas encore publié sur npm.
+
+Fait partie du SDK **[aurabase](../aurabase)**. Installé automatiquement comme dépendance transitive de tous les autres packages `@aurabase/*` ; ce package n'est utile en installation directe que pour écrire une extension ou un client alternatif (voir Usage).
+
+Ce README s'adresse aux **auteurs d'extensions** (service additionnel, client SSR maison) — pas aux utilisateurs finaux d'une application, qui doivent passer par le méta-package [`aurabase`](../aurabase).
+
+## Installation
+
+```bash
+npm i @aurabase/core
+```
+
+> `@aurabase/core` n'a aucune dépendance runtime Aurabase — c'est la fondation. Si vous utilisez `aurabase` ou n'importe quel package `@aurabase/*` (auth, db, storage, realtime, functions, ai, notifications), il est déjà présent en tant que dépendance transitive.
+
+## Usage
+
+### `AuraResponse` / `AuraError`
+
+Toutes les méthodes de service renvoient une `Promise<AuraResponse<T>>` — jamais un throw sur une erreur métier/HTTP.
+
+```ts
+import type { AuraResponse } from '@aurabase/core'
+
+interface Widget {
+  id: string
+  name: string
+}
+
+function handle(res: AuraResponse<Widget>) {
+  if (res.error) {
+    if (res.error.isNotFound) console.warn('introuvable')
+    else if (res.error.isRateLimited) console.warn('rate limited')
+    else console.error(res.error.status, res.error.code, res.error.message)
+    return
+  }
+  // `data` peut être `null` même en succès (204 / corps vide) : tester `data`
+  // plutôt que `error` évite l'assertion `data!`, et TypeScript réduit alors
+  // `res.data` à `Widget`.
+  if (res.data === null) {
+    console.log('succès sans contenu')
+    return
+  }
+  console.log(res.data.name)
+}
+```
+
+#### `AuraResponse` est une union à trois membres
+
+```ts
+type AuraResponse<T> =
+  | AuraSuccess<T>   // { data: T,    error: null,      meta?: Meta }
+  | AuraNoContent    // { data: null, error: null,      meta?: Meta }
+  | AuraFailure      // { data: null, error: AuraError, meta?: Meta }
+```
+
+Conséquences utiles :
+
+- la combinaison **impossible** `{ data: T, error: AuraError }` n'est plus
+  constructible — aucun producteur du SDK ne la produit ;
+- `data` non nul ⇒ TypeScript sait que `error` est `null` ;
+- `error` non nul ⇒ TypeScript sait que `data` est `null`.
+
+Le membre `AuraNoContent` n'est pas un ornement : `fetchWithAuth` le renvoie sur
+un **204** et sur tout **2xx à corps vide**, pour n'importe quel `T`. Le cas
+emblématique est `db.from('t').delete().eq(...)` **sans** `.select()`, typé
+`Row[]` mais auquel PostgREST répond 204. Le fondre dans le membre succès
+rendrait le type menteur : c'est pourquoi `if (error) return` ne réduit
+volontairement **pas** `data` à `T`.
+
+#### Corps de réponse invalide (`invalid_response`)
+
+Un **2xx dont le corps n'est pas du JSON** (page HTML d'un proxy mal configuré,
+réponse tronquée, corps illisible) produit un `AuraError` structuré de code
+`invalid_response` et de `status: 0` (erreur détectée côté client, comme
+`network_error` et `timeout`). Le statut HTTP réel, le content-type annoncé et
+la taille du corps figurent dans le `message` ; le corps lui-même n'est jamais
+recopié. Un 2xx **vide** reste au contraire un succès sans contenu.
+
+`isAuraError()` détecte une instance `AuraError` même à travers une frontière de bundle/realm différente (deux copies de `@aurabase/core` chargées séparément) :
+
+```ts
+import { isAuraError } from '@aurabase/core'
+
+function report(err: unknown) {
+  if (isAuraError(err)) {
+    console.error(err.code, err.status)
+  }
+}
+```
+
+### Construire un service (`BaseService` + `AuraClientLike`)
+
+`BaseService` est la classe de base utilisée par tous les services officiels (`AuthService`, `DatabaseService`, `FunctionsService`, ...). `AuraClientLike` est un contrat structurel : n'importe quel objet qui le satisfait (le `AuraClient` concret du méta-package, ou un client maison) peut être passé à un service.
+
+```ts
+import { BaseService } from '@aurabase/core'
+import type { AuraClientLike, AuraResponse } from '@aurabase/core'
+
+interface Widget {
+  id: string
+  name: string
+}
+
+class WidgetsService extends BaseService {
+  constructor(client: AuraClientLike) {
+    super(client)
+  }
+
+  private get prefix(): string {
+    return `/v1/widgets/${this.client.projectId}`
+  }
+
+  async list(): Promise<AuraResponse<Widget[]>> {
+    return this.request('GET', this.prefix)
+  }
+
+  async get(id: string): Promise<AuraResponse<Widget>> {
+    return this.request('GET', `${this.prefix}/${id}`)
+  }
+}
+```
+
+`this.request(method, path, body?, options?)` délègue à la couche fetch partagée (`fetchWithAuth`) : injection `apikey`/`Authorization`, refresh proactif du token, retry transitoire et dé-wrapping `{data, meta}` — un service maison en bénéficie gratuitement sans en réimplémenter la logique.
+
+### Stores d'authentification (dont SSR)
+
+`BaseAuthStore` est en mémoire (event-emitter `onChange`, stockage clé/valeur générique pour le PKCE `code_verifier`). `LocalAuthStore` l'étend avec persistance `localStorage` et des helpers cookie pour le rendu serveur.
+
+```ts
+import { LocalAuthStore } from '@aurabase/core'
+
+function hydrateFromCookieHeader(cookieHeader: string) {
+  const store = new LocalAuthStore('aurabase_auth')
+  store.loadFromCookie(cookieHeader) // hydrate depuis l'en-tête Cookie de la requête entrante
+  return store
+}
+
+const store = hydrateFromCookieHeader('aurabase_auth=%7B%22token%22%3Anull%7D')
+
+// Après une mutation de session, sérialiser l'état courant en Set-Cookie.
+const setCookieValue = store.exportToCookie({ path: '/', secure: true, sameSite: 'Lax', httpOnly: true })
+```
+
+`store.persistent` indique si le store survit à un redirect pleine page (`false` pour `BaseAuthStore`, `true` pour `LocalAuthStore`) — c'est ce flag que le flux OAuth PKCE utilise pour décider s'il peut stocker un `code_verifier` de façon fiable.
+
+### Résilience de la couche fetch (interne, consommée automatiquement)
+
+`BaseService.request()` passe par un pipeline de fetch partagé qui gère, sans configuration de votre part :
+
+- retry transitoire (full-jitter) sur `GET`/`HEAD` pour les statuts `408/429/502/503/504`, avec respect d'un `Retry-After` plafonné ;
+- timeout par tentative (chaque rejeu repart avec un budget neuf) ;
+- refresh de token single-flight (une seule requête de refresh en vol par client, dédupliquée) avec un commit-guard anti-race si une déconnexion/reconnexion s'intercale pendant l'attente.
+
+Cette couche (`fetchWithAuth`, `refreshOnce`) est exportée mais reste un détail d'implémentation consommé par `BaseService` : son usage direct n'est pas le chemin recommandé et son contrat n'est pas garanti stable entre versions mineures.
+
+## Limitations
+
+- Package d'infrastructure : pas d'API « produit ». Pour construire une application, utilisez le méta-package [`aurabase`](../aurabase), qui assemble tous les services derrière un seul client.
+- `BaseAuthStore` est en mémoire — l'état est perdu au reload ; `LocalAuthStore` nécessite un `localStorage` disponible (sinon retombe silencieusement sur le comportement en mémoire, sauf via les helpers cookie explicites).
+- `AuraClientLike` est un contrat minimal (`baseUrl`, `projectId`, `apiKey`, `fetchFn`, `authStore`, `auth.refreshSession`, `retryConfig?`, `requestTimeoutMs?`) : un client maison doit l'implémenter intégralement pour rester compatible avec `BaseService`.
+- La couche fetch bas niveau (`fetchWithAuth`/`refreshOnce`) est un détail d'implémentation interne, pas une API publique stabilisée.
+
+## Documentation
+
+Référence complète du SDK (tous les services, types partagés, SSR) : [README racine](../../README.md).