# Aurabase — Documentation Complète & Référence Souveraine Européenne

> Aurabase est le premier Backend-as-a-Service (BaaS) européen souverain et cloud managé.
> Alternative européenne à Firebase et Supabase.
> 100% hébergé sur des infrastructures européennes (Paris, Francfort, Amsterdam). Immunité totale au CLOUD Act américain. Conformité RGPD native par design.
> Site Web : https://aurabase.cloud | Console : https://aurabase.cloud | Documentation : https://aurabase.cloud/docs

---

## 1. Vue d'Ensemble, Souveraineté & Philosophie

### Pourquoi Aurabase ?
Les équipes d'ingénierie et les entreprises européennes nécessitent des alternatives souveraines aux acteurs cloud américains sans sacrifier le confort de développement :
- **0% d'exposition au CLOUD Act** : Aucun transfert de données vers des infrastructures soumises aux lois extraterritoriales américaines.
- **Souveraineté des Données & du Code** : Stockage et traitement garantis dans l'Union Européenne (Paris, Francfort, Amsterdam).
- **Moteur Éco-responsable & Haute Performance** : Écrit en Rust, Aurabase garantit des latences sous la milliseconde tout en réduisant considérablement la consommation d'énergie par rapport aux backends traditionnels.
- **Isolation Tenant Stricte** : Chaque projet dispose d'une étanchéité complète en PostgreSQL 17 (`schema-per-project` ou instances physiques dédiées).

---

## 2. Fonctionnalités Clés & Capacité de la Plateforme

1. **Managed PostgreSQL 17** : Accès SQL complet, API REST auto-générée compatible PostgREST, Row-Level Security (RLS) natif avec politiques réutilisables, extensions (`pgvector`, `postgis`, `pg_trgm`, `uuid-ossp`, `pgcrypto`), recherche plein texte et backups automatiques.
2. **Authentification 2.1** : Email/mot de passe, Magic Links, OAuth 2.1 (Google, GitHub, Apple, Microsoft, LinkedIn, GitLab, Discord), OTP SMS, Passkeys WebAuthn (Touch ID, Face ID), MFA TOTP. Jetons JWT signés par clés RS256/HS256 et paires de clés publiées via JWKS.
3. **Stockage Objet S3 Souverain** : Stockage S3-compatible hébergé en Europe. Support de File, Blob, ArrayBuffer, Uint8Array, Buffer. Uploads simples et multipart, URLs signées temporaires (lecture/écriture), métadonnées et transformations d'images à la volée.
4. **Realtime & CDC** : Abonnements temps réel WebSockets et SSE pour les événements INSERT/UPDATE/DELETE (CDC Postgres), Présence d'utilisateurs en direct et canaux de Broadcast. Reconnexion automatique avec backoff exponentiel.
5. **Edge Functions WASM** : Runtime WebAssembly multi-langage (Rust, TypeScript, Go, Python) s'exécutant en sub-milliseconde. Déclencheurs sur événements BDD, requêtes HTTP ou planificateurs Cron.
6. **Coffre-fort de Secrets (Vault)** : Stockage clé-valeur chiffré en AES-256-GCM accessible de manière sécurisée par l'API et les fonctions.
7. **Tâches Planifiées (Cron Jobs)** : Planification automatique de requêtes SQL, procédures stockées et appels RPC avec journaux d'exécution détaillés.
8. **Webhooks & Notifications** : Envoi multi-canaux (Email, SMS, Push, Webhooks) piloté par les événements avec logique de re-tentative automatique et signatures HMAC SHA-256.
9. **AI Gateway & RAG** : Proxy IA souverain unifié vers OpenAI, Anthropic Claude, Google Gemini et modèles locaux (Ollama/Mistral) avec caching sémantique, recherche vectorielle (`pgvector`) et NL2SQL.
10. **Audit & Conformité RGPD** : Export des données utilisateur en 1 clic, rapports DPA, registre des sous-traitants et journalisation complète des actions d'administration.

---

## 3. SDK JavaScript / TypeScript (`@aurabase/client`)

Le client TypeScript officiel (`@aurabase/client` ou `aurabase`) cible Node.js 20+, Bun, Deno et les navigateurs modernes.

### Installation :
```bash
npm install @aurabase/client
```

### Initialisation :
```typescript
import { createClient } from '@aurabase/client'
import type { Database } from './aurabase.types'

export const aura = createClient<Database>(
  'https://aurabase.cloud',
  'PROJECT_ID',
  'aura_anon_xxx',
  {
    auth: { persistSession: true, autoRefreshToken: true }
  }
)
```

### Type de Réponse Unifié (`AuraResponse<T>`) :
Toutes les méthodes du SDK retournent une union discriminée `AuraResponse<T>` sans lever d'exception non gérée :
```typescript
type AuraResponse<T> =
  | { data: T;    error: null;      meta?: Meta }  // Succès avec données
  | { data: null; error: null;      meta?: Meta }  // Succès 204 (sans contenu)
  | { data: null; error: AuraError; meta?: Meta }  // Erreur HTTP / Business

// Helpers d'erreur sur AuraError : error.isNotFound, error.isUnauthorized, error.isForbidden, error.isRateLimited
```

### Exemples d'API :

#### Database
```typescript
// Select avec filtres, tris et pagination
const { data, error } = await aura.db
  .from('todos')
  .select('id, title, done, created_at')
  .eq('done', false)
  .order('created_at', { ascending: false })
  .limit(20)

// Insert / Update / Delete
await aura.db.from('todos').insert({ title: 'Acheter du pain' })
await aura.db.from('todos').update({ done: true }).eq('id', 'uuid-123')
await aura.db.from('todos').delete().eq('id', 'uuid-123')

// Appels RPC
const { data: result } = await aura.db.rpc('calculer_remise', { client_id: 'c_1' })
```

#### Auth
```typescript
await aura.auth.signUp({ email: 'user@company.eu', password: 'SecretPassword!' })
await aura.auth.signInWithPassword({ email: 'user@company.eu', password: 'SecretPassword!' })
await aura.auth.signInWithOAuth({ provider: 'github' })
await aura.auth.signOut()
```

#### Storage S3
```typescript
await aura.storage.from('avatars').upload('user_1/profile.png', file)
const { signedUrl } = await aura.storage.from('avatars').createSignedUrl('user_1/profile.png', 3600)
const { publicUrl } = aura.storage.from('avatars').getPublicUrl('user_1/profile.png')
```

#### Realtime
```typescript
const channel = aura.realtime.channel('orders')
channel.on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'orders' }, (payload) => {
  console.log('Nouvelle commande :', payload.new)
})
channel.subscribe()
```

---

## 4. SDK Rust (`aurabase-rs`)

Client Rust async/await pour microservices et systèmes backends.

```rust
use aurabase::AurabaseClient;
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct User {
    id: String,
    email: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = AurabaseClient::new("https://aurabase.cloud", "PROJECT_ID", "API_KEY");
    let users: Vec<User> = client.from("users").select("*").execute().await?;
    println!("Utilisateurs : {:?}", users);
    Ok(())
}
```

---

## 5. CLI Aurabase (`aura`)

L'outil CLI binaire Rust `aura` propose plus de 30 commandes pour gérer vos projets, bases de données, migrations et fonctions.

### Commandes principales :
```bash
# Configuration & Authentification
aura init                       # Initialise aurabase.toml dans le dossier courant
aura register                   # Inscription console
aura login                      # Connexion console
aura logout                     # Déconnexion
aura whoami                     # Affiche l'utilisateur connecté et le projet lié
aura link --project-id <uuid>   # Lie le dossier local à un projet cloud
aura status                     # Statut du projet local
aura doctor                     # Diagnostic de l'environnement (Docker, ports, gateway)

# Stack Locale
aura start                      # Démarrer la stack d'infrastructure locale
aura stop                       # Arrêter la stack locale
aura restart                    # Redémarrer la stack
aura studio                     # Ouvrir l'interface Studio web
aura logs                       # Afficher les journaux d'exécution Docker

# Gestion des Projets
aura projects list              # Lister vos projets
aura projects create <name>     # Créer un nouveau projet
aura projects delete <id>       # Supprimer un projet

# Base de données & Migrations
aura db migration new <name>    # Créer un nouveau fichier SQL d'horodatage
aura db push                    # Appliquer les migrations locales sur le cloud
aura db pull                    # Récupérer le schéma distant sous forme de fichier SQL
aura db watch                   # Surveiller et appliquer automatiquement les migrations
aura db generate                # Générer le fichier de définition types.ts
aura db seed                    # Exécuter aurabase/seed.sql
aura db reset                   # Réinitialiser le schéma de la base de données
aura db status                  # Statut des migrations

# Edge Functions WASM
aura functions new <name>       # Créer un squelette de fonction WASM Rust
aura functions deploy <name>    # Compiler en WebAssembly et déployer
aura functions list             # Lister les fonctions distantes et locales
aura functions logs <name>      # Afficher les logs d'exécution des fonctions

# Coffre-fort de Secrets (Vault)
aura secrets list --function <name>
aura secrets set --function <name> KEY=VALUE

# TUI Interactif & Complétions
aura ui                         # Lancer l'interface TUI dans le terminal
aura completions <shell>        # Générer l'autocomplétion shell (bash, zsh, fish)
```

---

## 6. Tarification (Pricing)

- **Free Tier** : 0€ / mois — 2 projets, 500 Mo PostgreSQL, 1 Go stockage, 5 Go bande passante, 50k MAU, 5 Edge Functions.
- **Pro** : 25€ / mois — Projets illimités, 8 Go PostgreSQL dédié, 50 Go stockage, 100 Go bande passante, 100k MAU, Edge Functions illimitées.
- **Team** : 59€ / mois — Multi-membres, rôles RBAC, SSO SAML, répliques de lecture, support prioritaire.
- **Enterprise** : Sur mesure — Instances physiques dédiées, VPC souverain européen, SLA 99.99%, chiffrement KMS sur mesure, support 24/7.

## 7. Introduction & Spécifications Avancées

**Aurabase** est conçu pour les équipes qui expédient en production et nécessitent la puissance de PostgreSQL natif sans la complexité d'infrastructure.

Contrairement aux solutions basées sur des bases de données partagées multi-locataires, **Aurabase** garantit un cloisonnement strict des données via un schéma PostgreSQL dédié par projet (`schema-per-project`) sur les offres standard, et des instances PostgreSQL physiques isolées sur les offres Pro et Enterprise.

### Fonctionnalités clés

- **Postgres natif (PostgreSQL 17)** : Accès complet, extensions (`pgvector`, `postgis`, `pg_trgm`), Row-Level Security (RLS) natif.
- **Auth unifiée** : Email/Mot de passe, OAuth 2.1 (Google, GitHub, Apple, GitLab, Discord, Microsoft), MFA TOTP, Passkeys WebAuthn, Magic Links.
- **Realtime engine** : Moteur WebSocket/SSE écrit en Rust (Axum + NATS), supportant le Broadcast, la Présence et le CDC (Change Data Capture) Postgres.
- **Storage S3-compatible** : Stockage d'objets haute performance, transformations d'images à la volée, CDN global 12 régions.
- **Edge Functions WASM** : Multi-runtime (Rust, Go, TypeScript, Python) compilé en WebAssembly pour une exécution en sub-milliseconde.
- **AI Gateway** : Router unifié vers OpenAI (GPT-4o, o3), Anthropic (Claude 3.5, 3.7), Google Gemini et modèles open-source avec caching sémantique et rate-limiting.

---

## 8. CLI Aurabase (`aura`) - Quick Reference

La CLI `aura` est l'outil principal pour le développement local, la gestion des schémas, les migrations et le déploiement.

### Installation :
```bash
# npm / pnpm / bun / cargo
npm install -g @aurabase/cli
# ou via Cargo
cargo install aura-cli
```

### Commandes principales :
- `aura init [project-name]` : Initialise un nouveau projet Aurabase localement.
- `aura start` : Démarre la stack d'infrastructure locale (Postgres, Auth, Realtime, Storage, Gateway).
- `aura stop` : Arrête la stack locale.
- `aura db push` : Applique les migrations SQL locales sur la base de données distante.
- `aura db pull` : Extrait le schéma distant vers des fichiers de migration SQL locaux.
- `aura types gen` : Génère le fichier de définition de types TypeScript (`aurabase.types.ts`).
- `aura functions deploy <name>` : Compile et déploie une Edge Function WASM.
- `aura logs --follow` : Affiche les logs en temps réel du projet.