@aurabase/aurabase-js 0.3.0

package/packages/auth/tests/verify-otp.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect, afterEach, vi } from 'vitest'
+import { AuthService } from '../src/AuthService'
+import { BaseAuthStore } from '@aurabase/core'
+import type { AuraClientLike, TokenPair, User, AuthEvent } from '@aurabase/core'
+
+function fakeUser(id = 'u1'): User {
+  return { id, email: 't@e.com', phone: 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 tokenPair(): TokenPair {
+  return { access_token: 'AT', refresh_token: 'RT', token_type: 'bearer', expires_in: 3600, user: fakeUser() }
+}
+
+afterEach(() => { vi.restoreAllMocks() })
+
+function make() {
+  const seen: Array<{ url: string; method: string; body: unknown }> = []
+  const responders: Record<string, (body: unknown) => Response> = {}
+  const client: AuraClientLike = {
+    baseUrl: 'http://x', projectId: 'p', apiKey: 'k', authStore: new BaseAuthStore(),
+    fetchFn: (async (url: string, init: RequestInit) => {
+      const u = String(url)
+      let body: unknown = undefined
+      try { body = init.body ? JSON.parse(String(init.body)) : undefined } catch { /* FormData etc. */ }
+      seen.push({ url: u, method: String(init.method), body })
+      const key = Object.keys(responders).find((k) => u.includes(k))
+      if (key) return responders[key]!(body)
+      return new Response(JSON.stringify({ data: tokenPair() }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+    }) as unknown as typeof globalThis.fetch,
+    auth: null as unknown as AuraClientLike['auth'],
+  }
+  const svc = new AuthService(client, { autoRefresh: false, persistSession: false })
+  ;(client as { auth: unknown }).auth = svc
+  const events: AuthEvent[] = []
+  svc.onAuthStateChange((p) => events.push(p.event))
+  return { svc, client, seen, responders, events }
+}
+const okUser = () => new Response(JSON.stringify({ data: fakeUser() }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+
+describe('auth.verifyOtp — façade unifiée', () => {
+  it('signup → POST /verify-email {token}, save session + SIGNED_IN', async () => {
+    const { svc, seen, client, events } = make()
+    const { data } = await svc.verifyOtp({ type: 'signup', token: 'TK' })
+    expect((data as TokenPair).access_token).toBe('AT')
+    const c = seen.find((s) => s.url.includes('/verify-email'))!
+    expect(c.method).toBe('POST')
+    expect(c.body).toEqual({ token: 'TK' })
+    expect(client.authStore.token).toBe('AT')
+    expect(events).toContain('SIGNED_IN')
+  })
+
+  it('magiclink → POST /magic-link/verify {token}', async () => {
+    const { svc, seen } = make()
+    await svc.verifyOtp({ type: 'magiclink', token: 'ML' })
+    const c = seen.find((s) => s.url.includes('/magic-link/verify'))!
+    expect(c.body).toEqual({ token: 'ML' })
+  })
+
+  it('email → POST /email-otp/verify {email, code}', async () => {
+    const { svc, seen } = make()
+    await svc.verifyOtp({ type: 'email', email: 'a@b.c', token: '123456' })
+    const c = seen.find((s) => s.url.includes('/email-otp/verify'))!
+    expect(c.body).toEqual({ email: 'a@b.c', code: '123456' })
+  })
+
+  it('sms → POST /sms/verify {phone, code}', async () => {
+    const { svc, seen } = make()
+    await svc.verifyOtp({ type: 'sms', phone: '+33600', token: '999' })
+    const c = seen.find((s) => s.url.includes('/sms/verify'))!
+    expect(c.body).toEqual({ phone: '+33600', code: '999' })
+  })
+
+  it('recovery → POST /reset-password {token, password}, SIGNED_IN', async () => {
+    const { svc, seen, events } = make()
+    await svc.verifyOtp({ type: 'recovery', token: 'RCV', password: 'newpass' })
+    const c = seen.find((s) => s.url.includes('/reset-password'))!
+    expect(c.body).toEqual({ token: 'RCV', password: 'newpass' })
+    expect(events).toContain('SIGNED_IN')
+  })
+
+  it('email_change → POST /user/confirm-email-change {token}, émet USER_UPDATED', async () => {
+    const { svc, seen, responders, events } = make()
+    responders['/user/confirm-email-change'] = okUser
+    const { data } = await svc.verifyOtp({ type: 'email_change', token: 'EC' })
+    expect((data as User).id).toBe('u1')
+    const c = seen.find((s) => s.url.includes('/user/confirm-email-change'))!
+    expect(c.body).toEqual({ token: 'EC' })
+    expect(events).toContain('USER_UPDATED')
+    expect(events).not.toContain('SIGNED_IN')
+  })
+
+  it('recovery sans password → missing_password SANS appel réseau', async () => {
+    const { svc, seen } = make()
+    // Cast : on simule un appelant JS qui omet le password (le type l'exige).
+    const { error } = await svc.verifyOtp({ type: 'recovery', token: 'RCV' } as unknown as { type: 'recovery'; token: string; password: string })
+    expect(error?.code).toBe('missing_password')
+    expect(seen.length).toBe(0)
+  })
+
+  it('invite → otp_type_unsupported SANS appel réseau', async () => {
+    const { svc, seen } = make()
+    const { error } = await svc.verifyOtp({ type: 'invite', token: 'X' })
+    expect(error?.code).toBe('otp_type_unsupported')
+    expect(seen.length).toBe(0)
+  })
+
+  it('phone_change → otp_type_unsupported SANS appel réseau', async () => {
+    const { svc, seen } = make()
+    const { error } = await svc.verifyOtp({ type: 'phone_change', phone: '+1', token: 'X' })
+    expect(error?.code).toBe('otp_type_unsupported')
+    expect(seen.length).toBe(0)
+  })
+})
+
+describe('auth — rétrocompat des méthodes historiques (délégation à verifyOtp)', () => {
+  it('verifyEmail(token) → POST /verify-email {token} (inchangé)', async () => {
+    const { svc, seen } = make()
+    await svc.verifyEmail('TK')
+    const c = seen.find((s) => s.url.includes('/verify-email'))!
+    expect(c.method).toBe('POST')
+    expect(c.body).toEqual({ token: 'TK' })
+  })
+  it('verifyEmailOtp(email, code) → POST /email-otp/verify {email, code}', async () => {
+    const { svc, seen } = make()
+    await svc.verifyEmailOtp('a@b.c', '111')
+    const c = seen.find((s) => s.url.includes('/email-otp/verify'))!
+    expect(c.body).toEqual({ email: 'a@b.c', code: '111' })
+  })
+  it('verifySmsOtp(phone, code) → POST /sms/verify {phone, code}', async () => {
+    const { svc, seen } = make()
+    await svc.verifySmsOtp('+33', '222')
+    const c = seen.find((s) => s.url.includes('/sms/verify'))!
+    expect(c.body).toEqual({ phone: '+33', code: '222' })
+  })
+  it('verifyMagicLink(token) → POST /magic-link/verify {token}', async () => {
+    const { svc, seen } = make()
+    await svc.verifyMagicLink('ML')
+    const c = seen.find((s) => s.url.includes('/magic-link/verify'))!
+    expect(c.body).toEqual({ token: 'ML' })
+  })
+  it('resetPassword(token, pass) → POST /reset-password {token, password}', async () => {
+    const { svc, seen } = make()
+    await svc.resetPassword('RCV', 'np')
+    const c = seen.find((s) => s.url.includes('/reset-password'))!
+    expect(c.body).toEqual({ token: 'RCV', password: 'np' })
+  })
+  it('confirmEmailChange(token) → POST /user/confirm-email-change {token}', async () => {
+    const { svc, seen, responders } = make()
+    responders['/user/confirm-email-change'] = okUser
+    await svc.confirmEmailChange('EC')
+    const c = seen.find((s) => s.url.includes('/user/confirm-email-change'))!
+    expect(c.body).toEqual({ token: 'EC' })
+  })
+})

package/packages/auth/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src"]
+}

package/packages/auth/tsup.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['cjs', 'esm'],
+  dts: true,
+  splitting: false,
+  clean: true,
+  treeshake: true,
+  minify: false,
+})

package/packages/core/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/packages/core/README.md

@@ -0,0 +1,132 @@
+# @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
+  }
+  console.log(res.data!.name)
+}
+```
+
+`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).