# Aurabase JavaScript / TypeScript SDK Reference (@aurabase/client)

> Package NPM : @aurabase/client
> Documentation : https://aurabase.cloud/docs/sdk-js
> BaaS Souverain Européen — 100% Infra UE, hors CLOUD Act.

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

## Quickstart & Initialisation
```typescript
import { createClient, createAdminClient } 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 } }
)

// Admin Client (Backend uniquement avec service_role key)
export const admin = createAdminClient<Database>(
  'https://aurabase.cloud',
  'PROJECT_ID',
  process.env.AURA_SERVICE_ROLE_KEY!
)
```

## Response Shape (`AuraResponse<T>`)
```typescript
type AuraResponse<T> =
  | { data: T;    error: null;      meta?: Meta }  // Succès avec données
  | { data: null; error: null;      meta?: Meta }  // Succès 204 (body vide)
  | { data: null; error: AuraError; meta?: Meta }  // Erreur HTTP / Business

// AuraError helpers : error.isNotFound, error.isUnauthorized, error.isForbidden, error.isRateLimited
```

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

// Filtres : eq, neq, gt, gte, lt, lte, like, ilike, is, in, or
// Operations : insert({ ... }), update('id', { ... }), delete('id'), upsert({ ... }, { onConflict: 'id' })
// RPC : await aura.db.rpc('nom_fonction', { arg1: 'valeur' })
// Option throwOnError : aura.db.from('posts').single().throwOnError()
```

## Auth API
```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', redirectTo: 'https://myapp.com/callback' })
await aura.auth.signOut()

// OTP & Magic Links
await aura.auth.signInWithMagicLink({ email: 'user@company.eu' })
await aura.auth.signInWithEmailOtp('user@company.eu')
await aura.auth.verifyEmailOtp('user@company.eu', '123456')
await aura.auth.signInWithSmsOtp('+33612345678')
await aura.auth.verifySmsOtp('+33612345678', '123456')
await aura.auth.signInAnonymously()

// MFA
const enrollment = await aura.auth.mfaEnroll()
await aura.auth.mfaVerifySetup('123456')
await aura.auth.mfaVerify({ mfa_token: 'token', code: '123456' })
```

## Storage S3 API
```typescript
await aura.storage.upload('avatars', 'users/1.png', file, { contentType: 'image/png', upsert: true })
const { signedUrl } = await aura.storage.createSignedUrl('avatars', 'users/1.png', 3600)
const { publicUrl } = aura.storage.getPublicUrl('avatars', 'users/1.png', {
  transform: { width: 200, resize: 'cover', format: 'webp' }
})
const files = await aura.storage.list('avatars', { prefix: 'users/' })
await aura.storage.remove('avatars', ['users/1.png'])
```

## Realtime API
```typescript
const channel = aura.realtime.channel('room-1')
channel.on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'posts', filter: 'status=eq.active' }, (payload) => console.log(payload.new))
channel.on('broadcast', { event: 'cursor' }, (payload) => console.log(payload))
channel.on('presence', { event: 'sync' }, () => console.log(channel.presenceState()))
channel.subscribe()
await channel.track({ online_at: new Date().toISOString() })
await channel.send({ type: 'broadcast', event: 'cursor', payload: { x: 10, y: 20 } })
```

## Edge Functions API
```typescript
const { data, error } = await aura.functions.invoke('hello', {
  method: 'POST',
  path: '/welcome',
  body: { name: 'Ada' }
})
```

## AI Gateway API
```typescript
const chat = await aura.ai.chat([{ role: 'user', content: 'Hello' }], { system: 'Réponds brièvement.' })
await aura.ai.embed({ text: 'Texte à vectoriser', namespace: 'docs' })
await aura.ai.semanticSearch('recherche', 'docs', { top_k: 5, threshold: 0.7 })
await aura.ai.rag({ namespace: 'docs', question: 'Comment ça marche ?' })
await aura.ai.nl2sql('Combien d'utilisateurs ?', undefined, { limit: 50 })
```

## Notifications API (Admin Only)
```typescript
await admin.notifications.send('email', 'user@company.eu', 'Bienvenue', { subject: 'Bienvenue', variables: { name: 'Ada' } })
await admin.notifications.createTemplate({ name: 'welcome', channel: 'email', subject: 'Bienvenue', body: 'Bonjour {{ name }}' })
```