@bunbase-ae/js 1.0.0

package/src/http.ts

@@ -0,0 +1,217 @@
+// HTTP client — handles auth headers, 401 interception, and token refresh.
+//
+// Token refresh strategy:
+//   - On 401: call /auth/refresh once. If multiple requests fail concurrently,
+//     they all wait on the same in-flight refresh promise (not N parallel calls).
+//   - After a successful refresh: retry the original request with new token.
+//   - After a failed refresh: clear tokens, re-throw so the caller can redirect
+//     to login.
+
+import { BunBaseError } from "./types";
+
+interface TokenStore {
+  accessToken: string | null;
+  refreshToken: string | null;
+}
+
+export type TokenChangeListener = (tokens: TokenStore) => void;
+
+export class HttpClient {
+  private tokens: TokenStore = { accessToken: null, refreshToken: null };
+  private refreshPromise: Promise<void> | null = null;
+  private tokenListeners: TokenChangeListener[] = [];
+
+  baseUrl: string;
+  private readonly apiKey?: string;
+  private adminSecret: string | null;
+
+  constructor(baseUrl: string, apiKey?: string, adminSecret?: string) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+    this.adminSecret = adminSecret ?? null;
+  }
+
+  setAdminSecret(secret: string | null): void {
+    this.adminSecret = secret;
+  }
+
+  // ─── Token management ───────────────────────────────────────────────────────
+
+  setTokens(accessToken: string, refreshToken: string): void {
+    this.tokens = { accessToken, refreshToken };
+    this.notifyTokenListeners();
+  }
+
+  clearTokens(): void {
+    this.tokens = { accessToken: null, refreshToken: null };
+    this.notifyTokenListeners();
+  }
+
+  getAccessToken(): string | null {
+    return this.tokens.accessToken;
+  }
+
+  getRefreshToken(): string | null {
+    return this.tokens.refreshToken;
+  }
+
+  onTokenChange(listener: TokenChangeListener): () => void {
+    this.tokenListeners.push(listener);
+    return () => {
+      this.tokenListeners = this.tokenListeners.filter((l) => l !== listener);
+    };
+  }
+
+  private notifyTokenListeners(): void {
+    for (const l of this.tokenListeners) l(this.tokens);
+  }
+
+  // Returns the auth headers this client would attach to a request.
+  // Used by StorageClient for XHR-based uploads with progress tracking.
+  getAuthHeaders(): Record<string, string> {
+    if (this.adminSecret) return { Authorization: `Bearer ${this.adminSecret}` };
+    if (this.apiKey) return { "X-Api-Key": this.apiKey };
+    if (this.tokens.accessToken) return { Authorization: `Bearer ${this.tokens.accessToken}` };
+    return {};
+  }
+
+  // ─── Request ───────────────────────────────────────────────────────────────
+
+  async request<T>(
+    method: string,
+    path: string,
+    options: {
+      body?: unknown;
+      formData?: FormData;
+      query?: Record<string, string>;
+      skipAuth?: boolean;
+    } = {},
+  ): Promise<T> {
+    const res = await this.send(method, path, options);
+
+    // Static credentials (adminSecret, apiKey) don't use refresh tokens — skip the 401 retry flow.
+    if (
+      res.status === 401 &&
+      !options.skipAuth &&
+      !this.adminSecret &&
+      !this.apiKey &&
+      this.tokens.refreshToken
+    ) {
+      try {
+        await this.doRefresh();
+      } catch {
+        // Refresh failed — tokens are already cleared in doRefresh.
+        throw new BunBaseError("Session expired. Please log in again.", 401, null);
+      }
+      const retried = await this.send(method, path, options);
+      return this.parse<T>(retried);
+    }
+
+    return this.parse<T>(res);
+  }
+
+  // Returns the raw Response without parsing — for file downloads / blobs.
+  async requestRaw(method: string, path: string): Promise<Response> {
+    const res = await this.send(method, path, {});
+    if (!res.ok) {
+      let message = res.statusText;
+      try {
+        const data = (await res.clone().json()) as { error?: string };
+        if (data.error) message = data.error;
+      } catch {
+        // ignore
+      }
+      throw new Error(message);
+    }
+    return res;
+  }
+
+  // ─── Internal ──────────────────────────────────────────────────────────────
+
+  private async send(
+    method: string,
+    path: string,
+    options: {
+      body?: unknown;
+      formData?: FormData;
+      query?: Record<string, string>;
+      skipAuth?: boolean;
+    },
+  ): Promise<Response> {
+    let url = `${this.baseUrl}${path}`;
+    if (options.query && Object.keys(options.query).length > 0) {
+      url += `?${new URLSearchParams(options.query).toString()}`;
+    }
+
+    const headers: Record<string, string> = {};
+
+    if (!options.skipAuth) {
+      if (this.adminSecret) {
+        headers.Authorization = `Bearer ${this.adminSecret}`;
+      } else if (this.apiKey) {
+        headers["X-Api-Key"] = this.apiKey;
+      } else if (this.tokens.accessToken) {
+        headers.Authorization = `Bearer ${this.tokens.accessToken}`;
+      }
+    }
+
+    let body: string | FormData | null = null;
+    if (options.formData) {
+      body = options.formData;
+      // Do not set Content-Type — let the browser/runtime set the multipart boundary.
+    } else if (options.body !== undefined) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(options.body);
+    }
+
+    return fetch(url, { method, headers, body });
+  }
+
+  private async parse<T>(res: Response): Promise<T> {
+    const contentType = res.headers.get("content-type") ?? "";
+    const isJson = contentType.includes("application/json");
+    const data = isJson ? await res.json() : await res.text();
+
+    if (!res.ok) {
+      const body =
+        typeof data === "object" && data !== null ? (data as Record<string, unknown>) : {};
+      const message =
+        "error" in body ? String(body.error) : `Request failed with status ${res.status}`;
+      const code = "code" in body ? String(body.code) : undefined;
+      const field = "field" in body ? String(body.field) : undefined;
+      throw new BunBaseError(message, res.status, data, code, field);
+    }
+
+    return data as T;
+  }
+
+  // Deduplicated token refresh — multiple concurrent callers share one in-flight request.
+  private doRefresh(): Promise<void> {
+    if (this.refreshPromise) return this.refreshPromise;
+    this.refreshPromise = this.executeRefresh().finally(() => {
+      this.refreshPromise = null;
+    });
+    return this.refreshPromise;
+  }
+
+  private async executeRefresh(): Promise<void> {
+    const refreshToken = this.tokens.refreshToken;
+    if (!refreshToken) {
+      this.clearTokens();
+      throw new Error("No refresh token available.");
+    }
+
+    const res = await this.send("POST", "/api/v1/auth/refresh", {
+      body: { refresh_token: refreshToken },
+      skipAuth: true,
+    });
+
+    if (!res.ok) {
+      this.clearTokens();
+      throw new Error("Token refresh failed.");
+    }
+
+    const data = (await res.json()) as { access_token: string; refresh_token: string };
+    this.setTokens(data.access_token, data.refresh_token);
+  }
+}

package/src/index.ts

@@ -0,0 +1,76 @@
+export {
+  type AccessRule,
+  type AdminApiKey,
+  AdminClient,
+  type AdminFieldRule,
+  type AdminListResult,
+  type AdminRecord,
+  type AdminSession,
+  type AdminStoredFile,
+  type AdminUser,
+  type BackupFile,
+  type BucketAccessRule,
+  type CollectionIntrospection,
+  type CollectionMeta,
+  type CollectionRules,
+  type CollectionStats,
+  type ColumnInfo,
+  type ConfigResponse,
+  type CreateRelationParams,
+  type EmailTemplate,
+  type HealthResponse,
+  type ImpersonationResult,
+  type IndexInfo,
+  type MigrationStatus,
+  type MinuteBucket,
+  type Relation,
+  type RelationOnDelete,
+  type RelationType,
+  type ServerSettings,
+  type SettingsAuditEntry,
+  type StatsResponse,
+  type StorageBucket,
+  type TemplateName,
+  type UpdateUserParams,
+  type WebhookLogRow,
+} from "./admin";
+export { AuthClient, type AuthSnapshot } from "./auth";
+export { BunBaseClient } from "./client";
+export { CollectionClient } from "./collection";
+export { RealtimeClient, type SubscribeOptions } from "./realtime";
+export { type SignedUploadResult, StorageClient, type UploadOptions } from "./storage";
+export {
+  type AggregateFunction,
+  type AggregateResult,
+  type ApiKey,
+  type AuthResult,
+  type AuthUser,
+  type BatchCreate,
+  type BatchDelete,
+  type BatchOperation,
+  type BatchResult,
+  type BatchResultCreate,
+  type BatchResultDelete,
+  type BatchResultUpdate,
+  type BatchUpdate,
+  type BunBaseClientOptions,
+  BunBaseError,
+  type BunBaseRecord,
+  type FieldFilter,
+  type FieldRule,
+  type FileRecord,
+  type Filter,
+  type FilterOperator,
+  type FilterValue,
+  type GetQuery,
+  type ListQuery,
+  type ListResult,
+  type LoginResult,
+  type RealtimeCallback,
+  type RealtimeEvent,
+  type RealtimeEventType,
+  type TotpChallenge,
+  type TotpSetup,
+  type UnsubscribeFn,
+  type WithExpand,
+} from "./types";

package/src/realtime.ts

@@ -0,0 +1,374 @@
+// Realtime client — WebSocket subscriptions with auto-reconnect.
+//
+// Connection lifecycle:
+//   1. connect() opens the WebSocket lazily on first subscribe.
+//   2. After open: send auth token if available, then re-send all pending subs.
+//   3. On message: dispatch change events to per-channel callbacks.
+//   4. On close (unexpected): reconnect with exponential backoff (max 30s).
+//   5. On explicit disconnect(): close cleanly, clear pending reconnects.
+//
+// Channel format:
+//   "collection:{name}"        — all changes to a collection
+//   "collection:{name}:mine"   — changes scoped to the authenticated user (server resolves)
+//   "record:{collection}:{id}" — changes to a specific record
+//   "records:{collection}"     — multi-record: pass ids in the subscribe options
+
+import type { HttpClient } from "./http";
+import type { BunBaseRecord, RealtimeCallback, RealtimeEvent, UnsubscribeFn } from "./types";
+
+const INITIAL_RECONNECT_MS = 500;
+const MAX_RECONNECT_MS = 30_000;
+
+// Internal message shapes from the server.
+interface ServerChangeMessage<T = BunBaseRecord> {
+  type: "change";
+  channel: string;
+  event: "create" | "update" | "delete";
+  record: T & BunBaseRecord;
+  collection: string;
+}
+
+interface ServerSubscriptionsMessage {
+  type: "subscriptions";
+  channels: string[];
+}
+
+interface ServerPresenceMessage {
+  type: "presence";
+  channel: string;
+  users: string[];
+}
+
+interface ServerAuthMessage {
+  type: "auth";
+  event: "session_revoked" | "password_changed" | "account_deleted" | "sessions_purged";
+}
+
+type ServerMessage<T = BunBaseRecord> =
+  | ServerChangeMessage<T>
+  | ServerSubscriptionsMessage
+  | ServerPresenceMessage
+  | ServerAuthMessage
+  | { type: string };
+
+// Options accepted by subscribe().
+export interface SubscribeOptions {
+  // Only deliver events of these types. Omit for all types.
+  events?: ("create" | "update" | "delete")[];
+  // Only deliver events where the record matches all key=value pairs.
+  // Applies to create/update events; delete events always pass.
+  filter?: Record<string, unknown>;
+  // For "records:{collection}" channels: list of record IDs to subscribe to.
+  ids?: string[];
+}
+
+// Internal subscription state — tracks what was sent to the server so
+// re-subscribe on reconnect sends the same options.
+interface ChannelState {
+  callbacks: Set<RealtimeCallback>;
+  options: SubscribeOptions;
+}
+
+export class RealtimeClient {
+  private ws: WebSocket | null = null;
+  // Map from channel key → { callbacks, options }
+  private channels = new Map<string, ChannelState>();
+  private connected = false;
+  private intentionalClose = false;
+  private reconnectDelay = INITIAL_RECONNECT_MS;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private connectListeners = new Set<() => void>();
+  private pongListeners = new Set<() => void>();
+  private subscriptionsListeners = new Set<(channels: string[]) => void>();
+  private presenceListeners = new Set<(channel: string, users: string[]) => void>();
+
+  // Called when the server pushes an auth event indicating session state change.
+  // Receives null to indicate the session is no longer valid.
+  onAuthChange?: (user: null) => void;
+
+  // Called when a presence response arrives: (channel, userIds[]).
+  onPresence?: (channel: string, users: string[]) => void;
+
+  constructor(
+    private wsUrl: string,
+    private readonly http: HttpClient,
+  ) {
+    // Re-authenticate over an open WebSocket whenever tokens change.
+    // Covers: login while connected, silent token refresh, logout.
+    // On logout (accessToken = null) no explicit unauth is needed — the
+    // server rejects further subscription events for the revoked session.
+    this.http.onTokenChange(({ accessToken }) => {
+      if (this.connected && accessToken) {
+        this.send({ type: "auth", token: accessToken });
+      }
+    });
+  }
+
+  setWsUrl(url: string): void {
+    this.wsUrl = url;
+  }
+
+  // ─── Public API ────────────────────────────────────────────────────────────
+
+  subscribe<T extends Record<string, unknown> = Record<string, unknown>>(
+    channel: string,
+    callback: RealtimeCallback<T>,
+    options: SubscribeOptions = {},
+  ): UnsubscribeFn {
+    const existing = this.channels.get(channel);
+
+    if (!existing) {
+      this.channels.set(channel, {
+        callbacks: new Set(),
+        options,
+      });
+    }
+
+    // Wrap the typed callback so the internal map holds a consistent RealtimeCallback type.
+    const wrapped: RealtimeCallback = ({ event: evtType, collection, record }) => {
+      callback({ event: evtType, collection, record: record as T & BunBaseRecord });
+    };
+    this.channels.get(channel)?.callbacks.add(wrapped);
+
+    // Send subscribe message if already connected.
+    if (this.connected) {
+      this.sendSubscribe(channel, this.channels.get(channel)?.options ?? {});
+    } else {
+      this.connect();
+    }
+
+    return () => this.unsubscribe(channel, wrapped);
+  }
+
+  // Register a callback that fires once when the WebSocket connection opens
+  // (or immediately if already connected). Returns an unsubscribe function.
+  onConnect(callback: () => void): () => void {
+    if (this.connected) {
+      callback();
+      return () => {};
+    }
+    this.connectListeners.add(callback);
+    return () => this.connectListeners.delete(callback);
+  }
+
+  // Send a ping to the server. Returns a Promise that resolves when pong is received.
+  // Useful for detecting stale connections on mobile.
+  ping(timeoutMs = 5000): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (!this.connected) {
+        reject(new Error("Not connected"));
+        return;
+      }
+      const timer = setTimeout(() => {
+        this.pongListeners.delete(onPong);
+        reject(new Error("Ping timeout"));
+      }, timeoutMs);
+      const onPong = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+      this.pongListeners.add(onPong);
+      this.send({ type: "ping" });
+    });
+  }
+
+  // Request the list of active subscriptions from the server.
+  // Resolves with the resolved topic names — useful for reconnect state recovery.
+  getSubscriptions(timeoutMs = 5000): Promise<string[]> {
+    return new Promise((resolve, reject) => {
+      if (!this.connected) {
+        reject(new Error("Not connected"));
+        return;
+      }
+      const timer = setTimeout(() => {
+        this.subscriptionsListeners.delete(onSubs);
+        reject(new Error("Subscriptions query timeout"));
+      }, timeoutMs);
+      const onSubs = (channels: string[]) => {
+        clearTimeout(timer);
+        resolve(channels);
+      };
+      this.subscriptionsListeners.add(onSubs);
+      this.send({ type: "subscriptions" });
+    });
+  }
+
+  // Query which users are currently subscribed to a channel on this server worker.
+  // Response is delivered via the onPresence callback.
+  // Returns a Promise that resolves with the user ID list (using a one-shot listener).
+  presence(channel: string, timeoutMs = 5000): Promise<string[]> {
+    return new Promise((resolve, reject) => {
+      if (!this.connected) {
+        reject(new Error("Not connected"));
+        return;
+      }
+      const timer = setTimeout(() => {
+        this.presenceListeners.delete(onPresence);
+        reject(new Error("Presence query timeout"));
+      }, timeoutMs);
+      const onPresence = (ch: string, users: string[]) => {
+        if (ch === channel) {
+          clearTimeout(timer);
+          this.presenceListeners.delete(onPresence);
+          resolve(users);
+        }
+      };
+      this.presenceListeners.add(onPresence);
+      this.send({ type: "presence", channel });
+    });
+  }
+
+  disconnect(): void {
+    this.intentionalClose = true;
+    if (this.reconnectTimer !== null) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.ws?.close();
+    this.ws = null;
+    this.connected = false;
+  }
+
+  // ─── Internal ──────────────────────────────────────────────────────────────
+
+  private unsubscribe(channel: string, callback: RealtimeCallback): void {
+    const state = this.channels.get(channel);
+    if (!state) return;
+    state.callbacks.delete(callback);
+    if (state.callbacks.size === 0) {
+      this.channels.delete(channel);
+      if (this.connected) this.send({ type: "unsubscribe", channel });
+    }
+  }
+
+  private sendSubscribe(channel: string, options: SubscribeOptions): void {
+    const msg: Record<string, unknown> = { type: "subscribe", channel };
+    if (options.events && options.events.length > 0) msg.events = options.events;
+    if (options.filter && Object.keys(options.filter).length > 0) msg.filter = options.filter;
+    if (options.ids && options.ids.length > 0) msg.ids = options.ids;
+    this.send(msg);
+  }
+
+  // Eagerly open the WebSocket. Safe to call multiple times — no-ops if already open.
+  // Called automatically on first subscribe(); exposed publicly so BunBaseProvider
+  // can keep the connection alive for auth event delivery even with no active subscriptions.
+  connect(): void {
+    if (
+      this.ws &&
+      (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING)
+    ) {
+      return;
+    }
+
+    this.intentionalClose = false;
+    this.ws = new WebSocket(`${this.wsUrl}/realtime`);
+
+    this.ws.onopen = () => {
+      this.connected = true;
+      this.reconnectDelay = INITIAL_RECONNECT_MS;
+
+      // Notify connection listeners and clear them (one-shot per connect).
+      for (const cb of this.connectListeners) cb();
+      this.connectListeners.clear();
+
+      // Authenticate if token available.
+      const token = this.http.getAccessToken();
+      if (token) this.send({ type: "auth", token });
+
+      // Re-subscribe all active channels (handles reconnect case).
+      for (const [channel, state] of this.channels) {
+        this.sendSubscribe(channel, state.options);
+      }
+    };
+
+    this.ws.onmessage = (event: MessageEvent) => {
+      let msg: ServerMessage;
+      try {
+        msg = JSON.parse(event.data as string) as ServerMessage;
+      } catch {
+        return;
+      }
+
+      if (msg.type === "pong") {
+        for (const cb of this.pongListeners) cb();
+        this.pongListeners.clear();
+        return;
+      }
+
+      if (msg.type === "subscriptions") {
+        const { channels } = msg as ServerSubscriptionsMessage;
+        for (const cb of this.subscriptionsListeners) cb(channels);
+        this.subscriptionsListeners.clear();
+        return;
+      }
+
+      if (msg.type === "presence") {
+        const presenceMsg = msg as ServerPresenceMessage;
+        // Notify one-shot Promise listeners.
+        for (const cb of this.presenceListeners) cb(presenceMsg.channel, presenceMsg.users);
+        // Notify global onPresence callback if set.
+        this.onPresence?.(presenceMsg.channel, presenceMsg.users);
+        return;
+      }
+
+      if (msg.type === "auth") {
+        const authMsg = msg as ServerAuthMessage;
+        if (
+          authMsg.event === "session_revoked" ||
+          authMsg.event === "account_deleted" ||
+          authMsg.event === "sessions_purged"
+        ) {
+          // Session is definitively invalidated — notify and close.
+          this.onAuthChange?.(null);
+          this.http.clearTokens();
+          this.disconnect();
+        } else if (authMsg.event === "password_changed") {
+          // Notify that credentials may have changed but don't force disconnect.
+          this.onAuthChange?.(null);
+          this.http.clearTokens();
+        }
+        return;
+      }
+
+      if (msg.type !== "change") return;
+
+      const changeMsg = msg as ServerChangeMessage;
+      const state = this.channels.get(changeMsg.channel);
+      if (!state) return;
+
+      const realtimeEvent: RealtimeEvent = {
+        event: changeMsg.event,
+        collection: changeMsg.collection,
+        record: changeMsg.record,
+      };
+
+      for (const cb of state.callbacks) cb(realtimeEvent);
+    };
+
+    this.ws.onclose = () => {
+      this.connected = false;
+      this.ws = null;
+      if (!this.intentionalClose && this.channels.size > 0) {
+        this.scheduleReconnect();
+      }
+    };
+
+    this.ws.onerror = () => {
+      // onclose fires after onerror, so reconnect is handled there.
+    };
+  }
+
+  private scheduleReconnect(): void {
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.reconnectDelay = Math.min(this.reconnectDelay * 2, MAX_RECONNECT_MS);
+      this.connect();
+    }, this.reconnectDelay);
+  }
+
+  private send(message: object): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(message));
+    }
+  }
+}