@bunbase-ae/js 1.0.0

package/src/auth.ts

@@ -0,0 +1,338 @@
+// Auth client — register, login, refresh, logout, me.
+//
+// Tokens are stored in HttpClient (the shared token store). AuthClient only
+// handles the API calls and wires the results back into HttpClient.
+
+import type { HttpClient } from "./http";
+import type { ApiKey, AuthResult, AuthUser, LoginResult, TotpChallenge, TotpSetup } from "./types";
+
+// Reactive snapshot of auth state. Consumed by useAuth() via useSyncExternalStore.
+export interface AuthSnapshot {
+  user: AuthUser | null;
+  loading: boolean;
+  error: Error | null;
+}
+
+export class AuthClient {
+  // Cached user — set on every successful login/register/me/verifyTotp call.
+  // Cleared on logout. Lets useAuth() initialize synchronously without a network round-trip.
+  private cachedUser: AuthUser | null = null;
+
+  // External store for useSyncExternalStore — holds user/loading/error as a snapshot.
+  private _snap: AuthSnapshot = { user: null, loading: false, error: null };
+  private _snapSubs = new Set<() => void>();
+
+  constructor(private readonly http: HttpClient) {
+    // When tokens are cleared from ANY path (logout, logoutAll, deleteAccount,
+    // or server-pushed revocation via RealtimeClient), keep cachedUser and the
+    // reactive snapshot in sync automatically.
+    this.http.onTokenChange(({ accessToken }) => {
+      if (!accessToken && this.cachedUser !== null) {
+        this.cachedUser = null;
+        this.patchSnapshot({ user: null });
+      }
+    });
+  }
+
+  /** Current snapshot — stable reference until something changes. */
+  getSnapshot(): AuthSnapshot {
+    return this._snap;
+  }
+
+  /** Subscribe to snapshot changes. Returns unsubscribe fn. */
+  subscribeSnapshot(listener: () => void): () => void {
+    this._snapSubs.add(listener);
+    return () => {
+      this._snapSubs.delete(listener);
+    };
+  }
+
+  /** Merge patch into the snapshot and notify subscribers only if something actually changed. */
+  patchSnapshot(patch: Partial<AuthSnapshot>): void {
+    let changed = false;
+    for (const key of Object.keys(patch) as (keyof AuthSnapshot)[]) {
+      if (this._snap[key] !== patch[key]) {
+        changed = true;
+        break;
+      }
+    }
+    if (!changed) return;
+    this._snap = { ...this._snap, ...patch };
+    for (const fn of this._snapSubs) fn();
+  }
+
+  /** Returns the last known user synchronously, or null if not yet loaded. */
+  getCachedUser(): AuthUser | null {
+    return this.cachedUser;
+  }
+
+  async register(credentials: { email: string; password: string }): Promise<AuthResult> {
+    const result = await this.http.request<AuthResult>("POST", "/api/v1/auth/register", {
+      body: credentials,
+      skipAuth: true,
+    });
+    this.cachedUser = result.user;
+    this.patchSnapshot({ user: result.user });
+    this.http.setTokens(result.access_token, result.refresh_token);
+    return result;
+  }
+
+  // Returns AuthResult on success, or TotpChallenge when 2FA is enabled.
+  // On TotpChallenge, call verifyTotp(result.totp_token, code) to complete sign-in.
+  async login(credentials: { email: string; password: string }): Promise<LoginResult> {
+    const result = await this.http.request<LoginResult>("POST", "/api/v1/auth/login", {
+      body: credentials,
+      skipAuth: true,
+    });
+    if ("totp_required" in result) return result as TotpChallenge;
+    this.cachedUser = (result as AuthResult).user;
+    this.patchSnapshot({ user: (result as AuthResult).user });
+    this.http.setTokens(result.access_token, result.refresh_token);
+    return result;
+  }
+
+  // Complete 2FA login. totpToken comes from the TotpChallenge returned by login().
+  async verifyTotp(totpToken: string, code: string): Promise<AuthResult> {
+    const result = await this.http.request<AuthResult>("POST", "/api/v1/auth/2fa/verify", {
+      body: { totp_token: totpToken, code },
+      skipAuth: true,
+    });
+    this.cachedUser = result.user;
+    this.patchSnapshot({ user: result.user });
+    this.http.setTokens(result.access_token, result.refresh_token);
+    return result;
+  }
+
+  // Send a magic-link login email. The link routes to your app with ?token=...
+  // Pass the token to verifyMagicLink() to complete sign-in.
+  async requestMagicLink(email: string): Promise<void> {
+    await this.http.request<{ ok: boolean }>("POST", "/api/v1/auth/magic-link", {
+      body: { email },
+      skipAuth: true,
+    });
+  }
+
+  // Complete magic-link sign-in using the token from the email URL.
+  async verifyMagicLink(token: string): Promise<AuthResult> {
+    const result = await this.http.request<AuthResult>("POST", "/api/v1/auth/magic-link/verify", {
+      body: { token },
+      skipAuth: true,
+    });
+    this.cachedUser = result.user;
+    this.patchSnapshot({ user: result.user });
+    this.http.setTokens(result.access_token, result.refresh_token);
+    return result;
+  }
+
+  async refresh(): Promise<AuthResult> {
+    const refreshToken = this.http.getRefreshToken();
+    if (!refreshToken) throw new Error("No refresh token stored. Call login() first.");
+    const result = await this.http.request<AuthResult>("POST", "/api/v1/auth/refresh", {
+      body: { refresh_token: refreshToken },
+      skipAuth: true,
+    });
+    this.cachedUser = result.user;
+    this.patchSnapshot({ user: result.user });
+    this.http.setTokens(result.access_token, result.refresh_token);
+    return result;
+  }
+
+  async logout(): Promise<void> {
+    const refreshToken = this.http.getRefreshToken();
+    try {
+      if (refreshToken) {
+        await this.http.request<void>("POST", "/api/v1/auth/logout", {
+          body: { refresh_token: refreshToken },
+          skipAuth: true,
+        });
+      }
+    } finally {
+      this.cachedUser = null;
+      this.patchSnapshot({ user: null });
+      this.http.clearTokens();
+    }
+  }
+
+  // Revoke all active sessions for the current user.
+  async logoutAll(): Promise<{ sessions_revoked: number }> {
+    const result = await this.http.request<{ ok: boolean; sessions_revoked: number }>(
+      "POST",
+      "/api/v1/auth/logout-all",
+    );
+    this.cachedUser = null;
+    this.patchSnapshot({ user: null });
+    this.http.clearTokens();
+    return { sessions_revoked: result.sessions_revoked };
+  }
+
+  async me(): Promise<AuthUser> {
+    const user = await this.http.request<AuthUser>("GET", "/api/v1/auth/me");
+    this.cachedUser = user;
+    this.patchSnapshot({ user });
+    return user;
+  }
+
+  // Update the authenticated user's metadata.
+  // Full replace — spread the current value if you only want to change one field:
+  //   const me = await client.auth.me();
+  //   await client.auth.updateMe({ ...me.metadata, bio: "Updated." });
+  async updateMe(metadata: Record<string, unknown>): Promise<AuthUser> {
+    const user = await this.http.request<AuthUser>("PATCH", "/api/v1/auth/me", {
+      body: { metadata },
+    });
+    this.cachedUser = user;
+    this.patchSnapshot({ user });
+    return user;
+  }
+
+  // Permanently delete the authenticated account (requires password confirmation).
+  async deleteAccount(password: string): Promise<void> {
+    await this.http.request<{ ok: boolean }>("DELETE", "/api/v1/auth/me", {
+      body: { password },
+    });
+    this.cachedUser = null;
+    this.patchSnapshot({ user: null });
+    this.http.clearTokens();
+  }
+
+  // Send a password-reset email. Always resolves successfully (server never reveals
+  // whether the address is registered).
+  async forgotPassword(email: string): Promise<void> {
+    await this.http.request<{ ok: boolean }>("POST", "/api/v1/auth/forgot-password", {
+      body: { email },
+      skipAuth: true,
+    });
+  }
+
+  // Complete the password-reset flow using the token from the email link.
+  async resetPassword(token: string, password: string): Promise<void> {
+    await this.http.request<{ ok: boolean }>("POST", "/api/v1/auth/reset-password", {
+      body: { token, password },
+      skipAuth: true,
+    });
+  }
+
+  // Verify an email address using the token from the verification link.
+  async verifyEmail(token: string): Promise<void> {
+    await this.http.request<{ ok: boolean }>("POST", "/api/v1/auth/verify-email", {
+      body: { token },
+      skipAuth: true,
+    });
+  }
+
+  // Re-send the verification email to the currently authenticated user.
+  async resendVerification(): Promise<void> {
+    await this.http.request<{ ok: boolean }>("POST", "/api/v1/auth/resend-verification");
+  }
+
+  // Returns true if an access token is currently held (does not validate expiry).
+  isAuthenticated(): boolean {
+    return this.http.getAccessToken() !== null;
+  }
+
+  // Restore a previously persisted session (e.g. from localStorage or Keychain).
+  // Pass the stored user object to pre-populate getCachedUser() so that useAuth()
+  // can initialize synchronously without a network round-trip.
+  restoreSession(accessToken: string, refreshToken: string, user?: AuthUser): void {
+    if (user) {
+      this.cachedUser = user;
+      this.patchSnapshot({ user });
+    }
+    this.http.setTokens(accessToken, refreshToken);
+  }
+
+  // ─── TOTP / 2FA management ───────────────────────────────────────────────────
+
+  // Get the current 2FA status for the authenticated user.
+  async getTotpStatus(): Promise<{ enabled: boolean }> {
+    return this.http.request<{ enabled: boolean }>("GET", "/api/v1/auth/2fa/status");
+  }
+
+  // Generate (or regenerate) a TOTP secret. Display the secret or otpauth_url
+  // to the user, then call enableTotp() with a code from their app.
+  async setupTotp(): Promise<TotpSetup> {
+    return this.http.request<TotpSetup>("POST", "/api/v1/auth/2fa/setup");
+  }
+
+  // Confirm TOTP setup and enable 2FA. code must be the current 6-digit code
+  // from the authenticator app loaded with the secret from setupTotp().
+  async enableTotp(code: string): Promise<void> {
+    await this.http.request<{ ok: boolean }>("POST", "/api/v1/auth/2fa/enable", {
+      body: { code },
+    });
+  }
+
+  // Disable 2FA. Requires a valid TOTP code to confirm the user has access.
+  async disableTotp(code: string): Promise<void> {
+    await this.http.request<{ ok: boolean }>("DELETE", "/api/v1/auth/2fa/disable", {
+      body: { code },
+    });
+  }
+
+  // ─── API keys ────────────────────────────────────────────────────────────────
+
+  // List the current user's API keys (key hashes are never returned).
+  async listApiKeys(): Promise<ApiKey[]> {
+    const result = await this.http.request<{ items: ApiKey[]; total: number }>(
+      "GET",
+      "/api/v1/auth/api-keys",
+    );
+    return result.items;
+  }
+
+  // Create a new API key. The raw key (bb_...) is returned once — store it immediately.
+  async createApiKey(name: string): Promise<ApiKey & { key: string }> {
+    return this.http.request<ApiKey & { key: string }>("POST", "/api/v1/auth/api-keys", {
+      body: { name },
+    });
+  }
+
+  // Revoke an API key by ID.
+  async revokeApiKey(id: string): Promise<void> {
+    await this.http.request<{ ok: boolean }>("DELETE", `/api/v1/auth/api-keys/${id}`);
+  }
+
+  // ─── Auth change listener ─────────────────────────────────────────────────
+
+  // Register a listener that fires when tokens change (login, refresh, logout).
+  // Returns an unsubscribe function.
+  onAuthChange(
+    listener: (session: { accessToken: string; refreshToken: string } | null) => void,
+  ): () => void {
+    return this.http.onTokenChange(({ accessToken, refreshToken }) => {
+      if (accessToken && refreshToken) {
+        listener({ accessToken, refreshToken });
+      } else {
+        listener(null);
+      }
+    });
+  }
+
+  // Periodically validate the active session so admin revocations are detected.
+  //
+  // FALLBACK: If the app uses RealtimeClient, auth events (session_revoked,
+  // account_deleted, sessions_purged, password_changed) are pushed instantly
+  // over the WebSocket and handled automatically by RealtimeClient — no polling
+  // needed. startSessionWatch is a fallback for environments without a WebSocket
+  // connection (e.g. server-side rendering, API-only clients).
+  //
+  // Calls me() on the given interval (default 30 s). When the session is no
+  // longer valid (access token expires and refresh is rejected because the
+  // session was revoked), HttpClient.clearTokens() fires automatically, which
+  // triggers onAuthChange(null) for all registered listeners.
+  //
+  // Returns a cleanup function — call it when the user signs out or the app
+  // unmounts to cancel the interval.
+  startSessionWatch(intervalMs = 30_000): () => void {
+    const id = setInterval(async () => {
+      if (!this.isAuthenticated()) return;
+      try {
+        await this.me();
+      } catch {
+        // If the session was revoked, refresh fails → clearTokens() is called
+        // by HttpClient → onAuthChange(null) fires. Nothing extra needed here.
+      }
+    }, intervalMs);
+    return () => clearInterval(id);
+  }
+}

package/src/client.ts

@@ -0,0 +1,61 @@
+// BunBaseClient — main entry point for the SDK.
+//
+// Usage:
+//   const client = new BunBaseClient({ url: "https://my.bunbase.server" });
+//   await client.auth.login({ email, password });
+//   const posts = client.collection<Post>("posts");
+//   const list = await posts.list({ sort: "-_created_at", limit: 20 });
+//   const unsub = client.realtime.subscribe("collection:posts", handler);
+
+import { AdminClient } from "./admin";
+import { AuthClient } from "./auth";
+import { CollectionClient } from "./collection";
+import { HttpClient } from "./http";
+import { RealtimeClient } from "./realtime";
+import { StorageClient } from "./storage";
+import type { BunBaseClientOptions } from "./types";
+
+export class BunBaseClient {
+  readonly auth: AuthClient;
+  readonly storage: StorageClient;
+  readonly realtime: RealtimeClient;
+  readonly admin: AdminClient;
+
+  private readonly http: HttpClient;
+
+  constructor(options: BunBaseClientOptions) {
+    const url = options.url.replace(/\/$/, ""); // strip trailing slash
+
+    // WebSocket URL: replace http(s) scheme with ws(s).
+    const wsUrl = url.replace(/^http/, "ws");
+
+    this.http = new HttpClient(url, options.apiKey, options.adminSecret);
+    this.auth = new AuthClient(this.http);
+    this.storage = new StorageClient(this.http);
+    this.realtime = new RealtimeClient(wsUrl, this.http);
+    this.admin = new AdminClient(this.http);
+  }
+
+  get baseUrl(): string {
+    return this.http.baseUrl;
+  }
+
+  // Update the admin secret (and optionally the server URL) without
+  // recreating the client. Call this after login or to clear on logout.
+  configure(opts: { url?: string; adminSecret?: string | null }): void {
+    if (opts.url !== undefined) {
+      this.http.baseUrl = opts.url.replace(/\/$/, "");
+      this.realtime.setWsUrl(this.http.baseUrl.replace(/^http/, "ws"));
+    }
+    if (opts.adminSecret !== undefined) {
+      this.http.setAdminSecret(opts.adminSecret);
+    }
+  }
+
+  // Returns a typed collection client for the given collection name.
+  collection<T extends Record<string, unknown> = Record<string, unknown>>(
+    name: string,
+  ): CollectionClient<T> {
+    return new CollectionClient<T>(this.http, name);
+  }
+}

package/src/collection.ts

@@ -0,0 +1,185 @@
+// CollectionClient — typed CRUD and list operations for a single collection.
+//
+// Usage:
+//   const posts = client.collection<Post>("posts");
+//   const result = await posts.list({ sort: "-_created_at", limit: 20 });
+//   const post  = await posts.create({ title: "Hello" });
+
+import type { HttpClient } from "./http";
+import type {
+  AggregateFunction,
+  AggregateResult,
+  BatchOperation,
+  BatchResult,
+  BunBaseRecord,
+  Filter,
+  GetQuery,
+  ListQuery,
+  ListResult,
+  WithExpand,
+} from "./types";
+
+export class CollectionClient<T extends Record<string, unknown> = Record<string, unknown>> {
+  constructor(
+    private readonly http: HttpClient,
+    private readonly name: string,
+  ) {}
+
+  // ─── CRUD ──────────────────────────────────────────────────────────────────
+
+  async list<TExpand extends Record<string, unknown> = Record<string, never>>(
+    query: ListQuery<T> = {},
+  ): Promise<ListResult<WithExpand<T & BunBaseRecord, TExpand>>> {
+    const qs = buildQueryString(query);
+    return this.http.request<ListResult<WithExpand<T & BunBaseRecord, TExpand>>>(
+      "GET",
+      `/api/v1/${this.name}`,
+      { query: qs },
+    );
+  }
+
+  async get<TExpand extends Record<string, unknown> = Record<string, never>>(
+    id: string,
+    options: GetQuery = {},
+  ): Promise<WithExpand<T & BunBaseRecord, TExpand>> {
+    const qs: Record<string, string> = {};
+    if (options.expand?.length) qs.expand = options.expand.join(",");
+    return this.http.request<WithExpand<T & BunBaseRecord, TExpand>>(
+      "GET",
+      `/api/v1/${this.name}/${id}`,
+      { query: Object.keys(qs).length > 0 ? qs : undefined },
+    );
+  }
+
+  async create(data: Partial<T>): Promise<T & BunBaseRecord> {
+    return this.http.request<T & BunBaseRecord>("POST", `/api/v1/${this.name}`, { body: data });
+  }
+
+  // Create multiple records in a single request backed by a SQL transaction.
+  // All records are inserted atomically — if any insert fails, none are saved.
+  async createMany(items: Partial<T>[]): Promise<(T & BunBaseRecord)[]> {
+    if (items.length === 0) return [];
+    return this.http.request<(T & BunBaseRecord)[]>("POST", `/api/v1/${this.name}/bulk`, {
+      body: items,
+    });
+  }
+
+  async update(id: string, patch: Partial<T>): Promise<T & BunBaseRecord> {
+    return this.http.request<T & BunBaseRecord>("PATCH", `/api/v1/${this.name}/${id}`, {
+      body: patch,
+    });
+  }
+
+  /**
+   * Create or update a record by matching on one or more fields.
+   * Returns 201 on create, 200 on update, 409 if multiple records match.
+   */
+  async upsert(data: Partial<T>, match: Record<string, unknown>): Promise<T & BunBaseRecord> {
+    return this.http.request<T & BunBaseRecord>("POST", `/api/v1/${this.name}/upsert`, {
+      body: { data, match },
+    });
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.http.request<{ deleted: boolean }>("DELETE", `/api/v1/${this.name}/${id}`);
+  }
+
+  // Restore a soft-deleted record.
+  async restore(id: string): Promise<T & BunBaseRecord> {
+    return this.http.request<T & BunBaseRecord>("POST", `/api/v1/${this.name}/${id}/restore`);
+  }
+
+  // Compute an aggregate (sum, avg, min, max, count) over the collection.
+  async aggregate(
+    fn: AggregateFunction,
+    options: {
+      field?: string;
+      group_by?: string;
+      filter?: Filter<T>;
+      include_deleted?: boolean;
+    } = {},
+  ): Promise<AggregateResult> {
+    const qs: Record<string, string> = { fn };
+    if (options.field) qs.field = options.field;
+    if (options.group_by) qs.group_by = options.group_by;
+    if (options.include_deleted) qs.include_deleted = "true";
+    if (options.filter) {
+      const filterQs = buildQueryString({ filter: options.filter });
+      Object.assign(qs, filterQs);
+    }
+    return this.http.request<AggregateResult>("GET", `/api/v1/${this.name}/aggregate`, {
+      query: qs,
+    });
+  }
+
+  // Count records matching the query filters.
+  async count(query: Pick<ListQuery<T>, "filter" | "include_deleted"> = {}): Promise<number> {
+    const qs = buildQueryString(query);
+    const result = await this.http.request<{ total: number }>("GET", `/api/v1/${this.name}/count`, {
+      query: Object.keys(qs).length > 0 ? qs : undefined,
+    });
+    return result.total;
+  }
+
+  // ─── Batch operations ──────────────────────────────────────────────────────
+  //
+  // Run up to 100 create/update/delete operations atomically.
+  // All operations succeed or all are rolled back.
+  // Returns the results in the same order as the input operations.
+
+  async batch(operations: BatchOperation<T>[]): Promise<BatchResult<T>[]> {
+    const result = await this.http.request<{ results: BatchResult<T>[] }>(
+      "POST",
+      `/api/v1/${this.name}/batch`,
+      { body: { operations } },
+    );
+    return result.results;
+  }
+
+  // ─── Realtime shorthand ────────────────────────────────────────────────────
+
+  // Returns a channel string for use with RealtimeClient.subscribe().
+  get channel(): string {
+    return `collection:${this.name}`;
+  }
+
+  recordChannel(id: string): string {
+    return `record:${this.name}:${id}`;
+  }
+}
+
+// ─── Query string builder ──────────────────────────────────────────────────────
+
+export function buildQueryString<T>(query: ListQuery<T>): Record<string, string> {
+  const params: Record<string, string> = {};
+
+  if (query.filter) {
+    for (const [field, value] of Object.entries(query.filter)) {
+      if (value === undefined || value === null) continue;
+
+      if (typeof value === "object" && !Array.isArray(value)) {
+        // Operator filter: { age: { gte: 18 } } → filter[age][gte]=18
+        for (const [op, opVal] of Object.entries(value as Filter)) {
+          if (opVal !== undefined && opVal !== null) {
+            params[`filter[${field}][${op}]`] = String(opVal);
+          }
+        }
+      } else {
+        // Equality filter: { status: "published" } → filter[status]=published
+        params[`filter[${field}]`] = Array.isArray(value) ? value.join(",") : String(value);
+      }
+    }
+  }
+
+  if (query.sort) params.sort = query.sort;
+  if (query.page !== undefined) params.page = String(query.page);
+  if (query.limit !== undefined) params.limit = String(query.limit);
+  if (query.fields?.length) params.fields = query.fields.join(",");
+  if (query.expand?.length) params.expand = query.expand.join(",");
+  if (query.after) params.after = query.after;
+  if (query.include_deleted) params.include_deleted = "true";
+  if (query.search) params.search = query.search;
+  if (query.count) params.count = "true";
+
+  return params;
+}