@aurabase/aurabase-js 0.3.0

package/packages/notifications/src/NotificationsService.ts

@@ -0,0 +1,230 @@
+import { BaseService } from '@aurabase/core'
+import type {
+  AuraResponse,
+  BatchSendResponse,
+  Notification,
+  NotificationAttempt,
+  NotificationDeadLetter,
+  NotificationEvent,
+  NotificationProviderLog,
+  NotificationQueueStats,
+  NotificationRule,
+  NotificationSettings,
+  NotificationStats,
+  NotificationTemplate,
+  NotificationTemplatePreview,
+  SendNotificationRequest,
+} from '@aurabase/core'
+import type { AuraClientLike } from '@aurabase/core'
+
+type NotificationChannel = 'email' | 'sms' | 'push' | 'webhook'
+type NotificationStatus = 'queued' | 'processing' | 'sent' | 'failed' | 'delivered' | 'expired' | 'dead_lettered'
+type CreateNotificationRuleRequest = {
+  name: string
+  trigger_type: string
+  condition?: Record<string, unknown>
+  template_id?: string | null
+  channel: NotificationChannel
+  recipient_expr: string
+  delay_seconds?: number
+}
+
+export class NotificationsService extends BaseService {
+  readonly admin: NotificationsAdminService
+
+  constructor(client: AuraClientLike) {
+    super(client)
+    this.admin = new NotificationsAdminService(client)
+  }
+
+  private get prefix(): string {
+    return `/v1/notifications/${this.client.projectId}`
+  }
+
+  // -- Send -------------------------------------------------------------------
+
+  async send(
+    channel: NotificationChannel,
+    recipient: string,
+    body: string,
+    options?: {
+      subject?: string
+      templateId?: string
+      variables?: Record<string, unknown>
+      metadata?: Record<string, unknown>
+      idempotencyKey?: string
+    },
+  ): Promise<AuraResponse<Notification>> {
+    return this.request('POST', `${this.prefix}/send`, {
+      channel,
+      recipient,
+      body,
+      subject: options?.subject,
+      template_id: options?.templateId,
+      variables: options?.variables,
+      metadata: options?.metadata,
+      idempotency_key: options?.idempotencyKey,
+    })
+  }
+
+  async sendBatch(items: SendNotificationRequest[]): Promise<AuraResponse<BatchSendResponse>> {
+    return this.request('POST', `${this.prefix}/send/batch`, { items })
+  }
+
+  // -- Notification history ---------------------------------------------------
+
+  async list(options?: {
+    channel?: NotificationChannel
+    status?: NotificationStatus
+    search?: string
+    sort?: 'created_at' | 'updated_at' | 'status'
+    order?: 'asc' | 'desc'
+    limit?: number
+    offset?: number
+  }): Promise<AuraResponse<Notification[]>> {
+    const params = new URLSearchParams()
+    if (options?.channel !== undefined) params.set('channel', options.channel)
+    if (options?.status !== undefined) params.set('status', options.status)
+    if (options?.search !== undefined) params.set('search', options.search)
+    if (options?.sort !== undefined) params.set('sort', options.sort)
+    if (options?.order !== undefined) params.set('order', options.order)
+    if (options?.limit !== undefined) params.set('limit', String(options.limit))
+    if (options?.offset !== undefined) params.set('offset', String(options.offset))
+    const qs = params.toString()
+    const sep = qs ? '?' : ''
+    return this.request('GET', `${this.prefix}${sep}${qs}`)
+  }
+
+  async get(id: string): Promise<AuraResponse<Notification>> {
+    return this.request('GET', `${this.prefix}/${id}`)
+  }
+
+  // -- Templates --------------------------------------------------------------
+
+  async listTemplates(): Promise<AuraResponse<NotificationTemplate[]>> {
+    return this.request('GET', `${this.prefix}/templates`)
+  }
+
+  async getTemplate(id: string): Promise<AuraResponse<NotificationTemplate>> {
+    return this.request('GET', `${this.prefix}/templates/${id}`)
+  }
+
+  async createTemplate(
+    template: Omit<NotificationTemplate, 'id' | 'created_at' | 'updated_at'>,
+  ): Promise<AuraResponse<NotificationTemplate>> {
+    return this.request('POST', `${this.prefix}/templates`, template)
+  }
+
+  async updateTemplate(
+    id: string,
+    updates: Partial<Omit<NotificationTemplate, 'id' | 'created_at' | 'updated_at'>>,
+  ): Promise<AuraResponse<NotificationTemplate>> {
+    return this.request('PATCH', `${this.prefix}/templates/${id}`, updates)
+  }
+
+  async deleteTemplate(id: string): Promise<AuraResponse<null>> {
+    return this.request('DELETE', `${this.prefix}/templates/${id}`)
+  }
+}
+
+export class NotificationsAdminService extends BaseService {
+  constructor(client: AuraClientLike) {
+    super(client)
+  }
+
+  private get prefix(): string {
+    return `/v1/notifications/${this.client.projectId}`
+  }
+
+  private query(options?: Record<string, string | number | boolean | null | undefined>): string {
+    const params = new URLSearchParams()
+    for (const [key, value] of Object.entries(options ?? {})) {
+      if (value !== undefined && value !== null && value !== '') params.set(key, String(value))
+    }
+    const qs = params.toString()
+    return qs ? `?${qs}` : ''
+  }
+
+  async getSettings(): Promise<AuraResponse<NotificationSettings>> {
+    return this.request('GET', `${this.prefix}/settings`)
+  }
+
+  async updateSettings(settings: Partial<NotificationSettings>): Promise<AuraResponse<NotificationSettings>> {
+    return this.request('PATCH', `${this.prefix}/settings`, settings)
+  }
+
+  async getStats(options?: {
+    window?: string
+    channel?: NotificationChannel
+  }): Promise<AuraResponse<NotificationStats>> {
+    return this.request('GET', `${this.prefix}/stats${this.query(options)}`)
+  }
+
+  async getQueue(): Promise<AuraResponse<NotificationQueueStats>> {
+    return this.request('GET', `${this.prefix}/queue`)
+  }
+
+  async listAttempts(notificationId: string): Promise<AuraResponse<NotificationAttempt[]>> {
+    return this.request('GET', `${this.prefix}/${notificationId}/attempts`)
+  }
+
+  async listDeadLetters(options?: {
+    channel?: NotificationChannel
+    search?: string
+    limit?: number
+    offset?: number
+  }): Promise<AuraResponse<NotificationDeadLetter[]>> {
+    return this.request('GET', `${this.prefix}/dead-letters${this.query(options)}`)
+  }
+
+  async retryDeadLetter(id: string): Promise<AuraResponse<Notification>> {
+    return this.request('POST', `${this.prefix}/dead-letters/${id}/retry`)
+  }
+
+  async listEvents(options?: {
+    status?: 'received' | 'matched' | 'ignored' | 'failed' | 'enqueued'
+    limit?: number
+    offset?: number
+  }): Promise<AuraResponse<NotificationEvent[]>> {
+    return this.request('GET', `${this.prefix}/events${this.query(options)}`)
+  }
+
+  async listProviderLogs(options?: {
+    channel?: NotificationChannel
+    status?: string
+    limit?: number
+    offset?: number
+  }): Promise<AuraResponse<NotificationProviderLog[]>> {
+    return this.request('GET', `${this.prefix}/providers/logs${this.query(options)}`)
+  }
+
+  async previewTemplate(
+    id: string,
+    variables: Record<string, unknown>,
+  ): Promise<AuraResponse<NotificationTemplatePreview>> {
+    return this.request('POST', `${this.prefix}/templates/${id}/preview`, variables)
+  }
+
+  async listRules(): Promise<AuraResponse<NotificationRule[]>> {
+    return this.request('GET', `${this.prefix}/rules`)
+  }
+
+  async createRule(rule: CreateNotificationRuleRequest): Promise<AuraResponse<NotificationRule>> {
+    return this.request('POST', `${this.prefix}/rules`, rule)
+  }
+
+  async getRule(id: string): Promise<AuraResponse<NotificationRule>> {
+    return this.request('GET', `${this.prefix}/rules/${id}`)
+  }
+
+  async updateRule(
+    id: string,
+    updates: Partial<Omit<NotificationRule, 'id' | 'project_id' | 'created_at' | 'updated_at'>>,
+  ): Promise<AuraResponse<NotificationRule>> {
+    return this.request('PATCH', `${this.prefix}/rules/${id}`, updates)
+  }
+
+  async deleteRule(id: string): Promise<AuraResponse<null>> {
+    return this.request('DELETE', `${this.prefix}/rules/${id}`)
+  }
+}

package/packages/notifications/src/index.ts

@@ -0,0 +1,19 @@
+export { NotificationsService, NotificationsAdminService } from './NotificationsService'
+
+// Types publics (utilisables en consommant `@aurabase/notifications` seul).
+export type {
+  AuraResponse,
+  Notification,
+  NotificationTemplate,
+  SendNotificationRequest,
+  BatchSendResponse,
+  NotificationAttempt,
+  NotificationDeadLetter,
+  NotificationEvent,
+  NotificationProviderLog,
+  NotificationQueueStats,
+  NotificationRule,
+  NotificationSettings,
+  NotificationStats,
+  NotificationTemplatePreview,
+} from '@aurabase/core'

package/packages/notifications/tsconfig.json

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

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

@@ -0,0 +1,183 @@
+# @aurabase/realtime
+
+Service temps réel du SDK Aurabase : une connexion WebSocket multiplexée sur des channels (`postgres_changes`, `broadcast`, `presence`).
+
+![npm](https://img.shields.io/npm/v/@aurabase/realtime) ![license](https://img.shields.io/badge/license-MIT-blue)
+
+> Pre-release — pas encore publié sur npm.
+
+Fait partie du SDK **[aurabase](../aurabase)**. Installé automatiquement avec `aurabase` ; ce package est publié séparément pour un usage ciblé / tree-shaking.
+
+## Installation
+
+```bash
+npm i @aurabase/realtime
+```
+
+> Dépend de `@aurabase/core`. Déjà inclus si vous utilisez le package `aurabase` — cette installation ciblée sert à composer votre propre client ou à limiter la taille du bundle. Nécessite un runtime avec `WebSocket` global (navigateur, ou Node avec un polyfill).
+
+## Usage
+
+`RealtimeService` est exposé par le client principal sous `aura.realtime`, et `aura.channel(name)` est un raccourci pour `aura.realtime.channel(name)`.
+
+```ts
+import { createClient } from 'aurabase'
+
+const aura = createClient('http://localhost:8080', 'my-project', 'aura_anon_xxx')
+```
+
+### Connexion
+
+```ts
+const unsubscribe = aura.realtime.onStateChange((state) => {
+  console.log('realtime state:', state) // 'disconnected' | 'connecting' | 'connected' | 'reconnecting'
+})
+
+aura.realtime.connect()
+console.log(aura.realtime.connectionState)
+
+// Désactive la reconnexion auto (backoff + jitter), ou borne le nombre de tentatives.
+aura.realtime.setAutoReconnect(true, 5)
+
+// Pousse un nouveau token sur la connexion existante (sans reconnexion).
+aura.realtime.refreshToken('new-access-token')
+```
+
+Un heartbeat applicatif (`ping`) est envoyé toutes les **25 secondes** via un Worker dédié, pour éviter le throttling des timers par les navigateurs en arrière-plan. La reconnexion automatique utilise un backoff exponentiel avec jitter.
+
+### `postgres_changes`
+
+```ts
+const channel = aura.channel('db:public.posts')
+  .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'posts' }, (payload) => {
+    console.log('insert:', payload)
+  })
+  .subscribe((status, err) => {
+    console.log(status, err) // 'SUBSCRIBED' | 'CLOSED' | 'CHANNEL_ERROR' | 'TIMED_OUT'
+  })
+```
+
+## Filtres de colonne (`postgres_changes`)
+
+`postgres_changes` accepte un champ `filter` (syntaxe PostgREST/Supabase : `"column=operator.value"`) pour ne recevoir que les events dont la ligne matche la condition :
+
+```ts
+aura.channel('room')
+  .on('postgres_changes', {
+    event: 'INSERT',
+    schema: 'public',
+    table: 'messages',
+    filter: 'room_id=eq.42',
+  }, (e) => console.log(e))
+  .subscribe()
+```
+
+Opérateurs supportés : `eq, neq, lt, lte, gt, gte, in, like, ilike, is, match, imatch, isdistinct`.
+
+```ts
+// Comparaison numérique.
+{ event: '*', schema: 'public', table: 'items', filter: 'qty=gt.5' }
+
+// Appartenance à un ensemble — les virgules internes à `in.(...)` ne
+// séparent PAS des conditions AND (voir plus bas).
+{ event: '*', schema: 'public', table: 'orders', filter: 'status=in.(open,pending)' }
+
+// Motif SQL LIKE (% / _).
+{ event: '*', schema: 'public', table: 'users', filter: 'name=like.jo%' }
+
+// Négation — préfixe `not.` devant l'opérateur.
+{ event: '*', schema: 'public', table: 'orders', filter: 'status=not.eq.done' }
+
+// AND par virgules — chaque condition séparée par `,` (hors `in.(...)`).
+{ event: '*', schema: 'public', table: 'items', filter: 'room_id=eq.42,qty=gt.5' }
+```
+
+À savoir :
+
+- **Le serveur `aura-realtime` est autoritaire** : il applique déjà le filtre avant d'envoyer l'event sur le socket. Le client réapplique la même logique en second rideau (defense-in-depth) — il ne peut que sur-filtrer, jamais laisser passer un event que le serveur aurait dû exclure.
+- **Fail-closed** : une condition non parsable (syntaxe invalide, opérateur inconnu, trop de valeurs `in`, pattern `match`/`imatch` trop long) exclut l'event plutôt que de le laisser passer.
+- **DELETE** : le filtre est évalué sur **l'ancienne ligne** (`old_record`), pas sur la nouvelle (qui n'existe plus). Les colonnes disponibles dans `old_record` dépendent du `REPLICA IDENTITY` de la table (`DEFAULT` : seule la clé primaire ; `FULL` : toutes les colonnes) — un filtre sur une colonne absente de `old_record` échoue à matcher (résultat non évaluable ⇒ exclusion, jamais inversée par `not.`), **sauf `is.null` et `isdistinct`** qui traitent une colonne absente comme `NULL` et peuvent donc matcher même si la colonne n'est pas présente dans `old_record`.
+- `schema` (et `table`) doivent correspondre exactement au schéma/table réels tels qu'envoyés par le serveur dans l'event — un `schema` incorrect exclut silencieusement tous les events de ce channel.
+
+### Broadcast
+
+```ts
+const room = aura.realtime.channel('room-1', { broadcast: { ack: true, self: true } })
+
+room
+  .on('broadcast', { event: 'cursor-pos' }, (payload) => {
+    console.log(payload)
+  })
+  .subscribe()
+
+// 'ok' | 'timeout' | 'error' — résout à l'ACK serveur si broadcast.ack est activé sur le channel.
+const status = await room.send({ type: 'broadcast', event: 'cursor-pos', payload: { x: 100, y: 200 } })
+```
+
+#### Broadcast HTTP (sans WebSocket)
+
+Émet un broadcast via REST, sans connexion WebSocket ouverte — utile côté serveur/edge.
+
+```ts
+// POST /v1/realtime/{projectId}/broadcast — pas besoin de connect().
+const { error } = await aura.realtime.httpBroadcast('room-1', 'cursor-pos', { x: 10, y: 20 })
+if (error) console.error(error) // 4xx / rate-limit surfacés proprement
+```
+
+Le nom de canal est préfixé par le projet automatiquement s'il ne l'est pas déjà.
+
+### Canaux privés (`setAuth`)
+
+Les canaux privés (`{ private: true }`) sont autorisés par les policies RLS côté serveur à
+partir du JWT courant. Fixez/rafraîchissez ce token via `setAuth()` **avant** de vous abonner :
+
+```ts
+// Utilise le token fourni (ou, sans argument, reprend client.authStore.token).
+aura.realtime.setAuth(session.access_token)
+
+const secret = aura.realtime
+  .channel('secret-room', { private: true })
+  .on('broadcast', { event: 'msg' }, console.log)
+  .subscribe((status, err) => {
+    if (status === 'CHANNEL_ERROR') console.error('Refusé par la policy RLS', err)
+  })
+```
+
+`setAuth()` propage `{ type: 'access_token' }` sur une connexion ouverte (dédupliqué, sans
+reconnexion). Un token non autorisé par la policy provoque un `CHANNEL_ERROR` à la souscription.
+
+### Presence
+
+```ts
+const lobby = aura.channel('room-1', { config: { presence: { key: 'user-1' } } })
+
+lobby
+  .on('presence', { event: 'sync' }, () => {
+    console.log(lobby.presenceState())
+  })
+  .on('presence', { event: 'join' }, console.log)
+  .on('presence', { event: 'leave' }, console.log)
+  .subscribe()
+
+await lobby.track({ online_at: new Date().toISOString() })
+await lobby.untrack()
+```
+
+### Nettoyage
+
+```ts
+aura.realtime.getChannels()
+aura.realtime.removeChannel('room-1')
+aura.realtime.removeAllChannels()
+aura.realtime.disconnect()
+unsubscribe()
+```
+
+## Limitations
+
+- Pas de limitation de débit configurable (`eventsPerSecond`) sur le broadcast (côté client).
+- La reconnexion réabonne les channels existants mais ne garantit pas la livraison des événements manqués pendant la coupure (au-delà du rejeu par `since_id` quand le serveur le supporte).
+
+## Documentation
+
+Référence complète du SDK (tous les services, types partagés, SSR) : [README racine](../../README.md).