@bunbase-ae/js 1.0.1-next.7.bc3dec2 → 1.2.0

package/README.md

@@ -0,0 +1,104 @@
+# @bunbase-ae/js
+
+TypeScript/JavaScript SDK for [BunBase](https://docs-bunbase.palmcode.ae).
+
+## Installation
+
+```sh
+bun add @bunbase-ae/js
+# or
+npm install @bunbase-ae/js
+```
+
+## Quick start
+
+```ts
+import { BunBaseClient } from "@bunbase-ae/js";
+
+const client = new BunBaseClient({ url: "https://your-bunbase-instance.example.com" });
+```
+
+## API
+
+### `BunBaseClient`
+
+The root client. All sub-clients are accessed from here.
+
+```ts
+const client = new BunBaseClient({ url: "https://..." });
+
+client.collection("posts")   // CollectionClient
+client.auth                  // AuthClient
+client.realtime              // RealtimeClient
+client.storage               // StorageClient
+client.admin                 // AdminClient
+```
+
+### Collections
+
+```ts
+const posts = client.collection("posts");
+
+// List records
+const { items, total } = await posts.list({ sort: "-_created_at", limit: 20 });
+
+// Get one record
+const post = await posts.get("record-id");
+
+// Create
+const created = await posts.create({ title: "Hello", body: "..." });
+
+// Update
+await posts.update("record-id", { title: "Updated" });
+
+// Delete
+await posts.delete("record-id");
+```
+
+### Auth
+
+```ts
+// Register
+await client.auth.register({ email: "user@example.com", password: "secret" });
+
+// Login
+await client.auth.login({ email: "user@example.com", password: "secret" });
+
+// Logout
+await client.auth.logout();
+
+// Subscribe to token changes (login, refresh, logout)
+// session is { accessToken, refreshToken } when authenticated, or null when logged out
+client.auth.onAuthChange((session) => {
+  if (session) {
+    console.log(session.accessToken, session.refreshToken);
+  } else {
+    console.log("logged out");
+  }
+});
+```
+
+### Realtime
+
+```ts
+const unsub = client.realtime.subscribe("posts", (event) => {
+  console.log(event.type, event.record);
+});
+
+// Later:
+unsub();
+```
+
+### Storage
+
+```ts
+// Upload a file
+const result = await client.storage.upload("avatars", file);
+
+// Get a public URL
+const url = client.storage.url("avatars", "filename.png");
+```
+
+## Documentation
+
+Full API reference and guides: [https://docs-bunbase.palmcode.ae](https://docs-bunbase.palmcode.ae)

package/package.json

@@ -1,11 +1,30 @@
 {
   "name": "@bunbase-ae/js",
-  "version": "1.0.1-next.7.bc3dec2",
+  "version": "1.2.0",
   "type": "module",
   "description": "TypeScript/JavaScript SDK for BunBase",
-  "homepage": "https://docs-bunbase.palmcode.ae/sdk/javascript",
+  "license": "UNLICENSED",
+  "homepage": "https://docs-bunbase.palmcode.ae",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/palmcode-ae/bunbase.git",
+    "directory": "sdk/js"
+  },
+  "bugs": {
+    "url": "https://github.com/palmcode-ae/bunbase/issues"
+  },
+  "keywords": [
+    "bunbase",
+    "sdk",
+    "typescript",
+    "database",
+    "realtime",
+    "auth",
+    "storage"
+  ],
   "files": [
-    "src"
+    "src",
+    "README.md"
   ],
   "main": "./src/index.ts",
   "exports": {

package/src/admin.ts

@@ -374,6 +374,14 @@ class AdminUsersClient {
     return res.items;
   }
 
+  async createApiKeyFor(userId: string, name: string): Promise<AdminApiKey & { key: string }> {
+    return this.http.request<AdminApiKey & { key: string }>(
+      "POST",
+      `/api/v1/admin/users/${userId}/api-keys`,
+      { body: { name } },
+    );
+  }
+
   async revokeApiKey(userId: string, keyId: string): Promise<void> {
     await this.http.request<{ ok: boolean }>(
       "DELETE",
@@ -520,11 +528,7 @@ class AdminCollectionsClient {
     if (opts.sort) params.sort = opts.sort;
     if (opts.includeDeleted) params.include_deleted = "true";
     if (opts.search) params.search = opts.search;
-    if (opts.filter) {
-      for (const [field, value] of Object.entries(opts.filter)) {
-        params[`filter[${field}]`] = value;
-      }
-    }
+    if (opts.filter) Object.assign(params, opts.filter);
     return this.http.request<AdminListResult<AdminRecord>>(
       "GET",
       `/api/v1/admin/collections/${collection}/records`,

package/src/auth.ts

@@ -4,7 +4,15 @@
 // 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";
+import type {
+  ApiKey,
+  AuthResult,
+  AuthUser,
+  LoginResult,
+  PersistSessionOptions,
+  TotpChallenge,
+  TotpSetup,
+} from "./types";
 
 // Reactive snapshot of auth state. Consumed by useAuth() via useSyncExternalStore.
 export interface AuthSnapshot {
@@ -13,6 +21,10 @@ export interface AuthSnapshot {
   error: Error | null;
 }
 
+// Represents the active session passed to onAuthChange listeners.
+// Token-based sessions carry access/refresh tokens; API-key sessions carry the key.
+export type AuthSession = { accessToken: string; refreshToken: string } | { apiKey: string };
+
 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.
@@ -150,6 +162,7 @@ export class AuthClient {
       this.cachedUser = null;
       this.patchSnapshot({ user: null });
       this.http.clearTokens();
+      this.http.setApiKey(null);
     }
   }
 
@@ -162,6 +175,7 @@ export class AuthClient {
     this.cachedUser = null;
     this.patchSnapshot({ user: null });
     this.http.clearTokens();
+    this.http.setApiKey(null);
     return { sessions_revoked: result.sessions_revoked };
   }
 
@@ -225,9 +239,28 @@ export class AuthClient {
     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).
+  // Returns true if an access token or API key is currently held (does not validate expiry).
   isAuthenticated(): boolean {
-    return this.http.getAccessToken() !== null;
+    return this.http.getAccessToken() !== null || this.http.getApiKey() !== null;
+  }
+
+  // Log in using a long-lived API key (e.g. for RFID / hardware-token login flows).
+  //
+  // Sets the API key on the HTTP layer, fetches /auth/me with it to verify
+  // the key is valid and retrieve the user, then updates the auth snapshot so
+  // that useAuth() and getCachedUser() reflect the authenticated state.
+  //
+  // On error (invalid or revoked key) the API key is cleared and the error is
+  // re-thrown. Call auth.logout() to sign out — it clears the API key too.
+  async loginWithApiKey(apiKey: string): Promise<AuthUser> {
+    this.http.setApiKey(apiKey);
+    try {
+      const user = await this.me(); // me() already updates cachedUser and snapshot
+      return user;
+    } catch (err) {
+      this.http.setApiKey(null);
+      throw err;
+    }
   }
 
   // Restore a previously persisted session (e.g. from localStorage or Keychain).
@@ -292,9 +325,12 @@ export class AuthClient {
     await this.http.request<{ ok: boolean }>("DELETE", `/api/v1/auth/api-keys/${id}`);
   }
 
-  // ─── Auth change listener ─────────────────────────────────────────────────
+  // ─── Auth change listeners ────────────────────────────────────────────────
 
-  // Register a listener that fires when tokens change (login, refresh, logout).
+  // Register a listener for token-based auth transitions: fires with
+  // { accessToken, refreshToken } on login/refresh, and null on logout.
+  // API-key sessions do not trigger this listener — use onApiKeyChange for those.
+  //
   // Returns an unsubscribe function.
   onAuthChange(
     listener: (session: { accessToken: string; refreshToken: string } | null) => void,
@@ -308,6 +344,81 @@ export class AuthClient {
     });
   }
 
+  // Register a listener for API-key auth transitions: fires with the key string
+  // on loginWithApiKey, and null when the key is cleared (e.g. after logout).
+  // Token-based sessions do not trigger this listener — use onAuthChange for those.
+  //
+  // Returns an unsubscribe function.
+  onApiKeyChange(listener: (apiKey: string | null) => void): () => void {
+    return this.http.onApiKeyChange(listener);
+  }
+
+  // Wire automatic session persistence against a StorageAdapter.
+  //
+  // Called by BunBaseClient when `persistSession` is set. Sets loading=true
+  // on the snapshot while the async read is in flight, then restores the
+  // session (if tokens are found) and sets loading=false. Also registers an
+  // onAuthChange listener that writes tokens to storage on login/refresh and
+  // clears them on logout.
+  //
+  // The method is intentionally synchronous — the async work is fire-and-forget
+  // so the constructor can call it without awaiting.
+  initPersistence(opts: PersistSessionOptions): void {
+    const { storage, prefix } = opts;
+    const atKey = `${prefix}_bb_at`;
+    const rtKey = `${prefix}_bb_rt`;
+    const userKey = `${prefix}_bb_user`;
+
+    this.patchSnapshot({ loading: true });
+
+    void (async () => {
+      try {
+        const [at, rt, userStr] = await Promise.all([
+          storage.getItem(atKey),
+          storage.getItem(rtKey),
+          storage.getItem(userKey),
+        ]);
+        if (at && rt) {
+          let user: AuthUser | undefined;
+          if (userStr) {
+            try {
+              user = JSON.parse(userStr) as AuthUser;
+            } catch {
+              // Corrupt cached user — ignore and proceed without it.
+            }
+          }
+          this.restoreSession(at, rt, user);
+        }
+      } finally {
+        this.patchSnapshot({ loading: false });
+      }
+    })();
+
+    // Wrap every storage call so that both synchronous throws (e.g. localStorage
+    // quota / security errors) and async rejections are absorbed silently and
+    // never propagate as unhandled rejections into the login/logout/refresh flow.
+    const safeWrite = (fn: () => unknown): void => {
+      try {
+        Promise.resolve(fn()).catch(() => {});
+      } catch {
+        // absorb synchronous throws
+      }
+    };
+
+    this.onAuthChange((session) => {
+      if (session) {
+        safeWrite(() => storage.setItem(atKey, session.accessToken));
+        safeWrite(() => storage.setItem(rtKey, session.refreshToken));
+        const user = this.getCachedUser();
+        if (user) safeWrite(() => storage.setItem(userKey, JSON.stringify(user)));
+      } else {
+        safeWrite(() => storage.removeItem(atKey));
+        safeWrite(() => storage.removeItem(rtKey));
+        safeWrite(() => storage.removeItem(userKey));
+      }
+    });
+  }
+
   // Periodically validate the active session so admin revocations are detected.
   //
   // FALLBACK: If the app uses RealtimeClient, auth events (session_revoked,

package/src/client.ts

@@ -34,6 +34,10 @@ export class BunBaseClient {
     this.storage = new StorageClient(this.http);
     this.realtime = new RealtimeClient(wsUrl, this.http);
     this.admin = new AdminClient(this.http);
+
+    if (options.persistSession) {
+      this.auth.initPersistence(options.persistSession);
+    }
   }
 
   get baseUrl(): string {

package/src/http.ts

@@ -15,22 +15,41 @@ interface TokenStore {
 }
 
 export type TokenChangeListener = (tokens: TokenStore) => void;
+export type ApiKeyChangeListener = (apiKey: string | null) => void;
 
 export class HttpClient {
   private tokens: TokenStore = { accessToken: null, refreshToken: null };
   private refreshPromise: Promise<void> | null = null;
   private tokenListeners: TokenChangeListener[] = [];
+  private apiKeyListeners: ApiKeyChangeListener[] = [];
 
   baseUrl: string;
-  private readonly apiKey?: string;
+  private _apiKey: string | null;
   private adminSecret: string | null;
 
   constructor(baseUrl: string, apiKey?: string, adminSecret?: string) {
     this.baseUrl = baseUrl;
-    this.apiKey = apiKey;
+    this._apiKey = apiKey ?? null;
     this.adminSecret = adminSecret ?? null;
   }
 
+  setApiKey(key: string | null): void {
+    if (this._apiKey === key) return;
+    this._apiKey = key;
+    this.notifyApiKeyListeners();
+  }
+
+  getApiKey(): string | null {
+    return this._apiKey;
+  }
+
+  onApiKeyChange(listener: ApiKeyChangeListener): () => void {
+    this.apiKeyListeners.push(listener);
+    return () => {
+      this.apiKeyListeners = this.apiKeyListeners.filter((l) => l !== listener);
+    };
+  }
+
   setAdminSecret(secret: string | null): void {
     this.adminSecret = secret;
   }
@@ -66,11 +85,15 @@ export class HttpClient {
     for (const l of this.tokenListeners) l(this.tokens);
   }
 
+  private notifyApiKeyListeners(): void {
+    for (const l of this.apiKeyListeners) l(this._apiKey);
+  }
+
   // 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._apiKey) return { "X-Api-Key": this._apiKey };
     if (this.tokens.accessToken) return { Authorization: `Bearer ${this.tokens.accessToken}` };
     return {};
   }
@@ -85,6 +108,8 @@ export class HttpClient {
       formData?: FormData;
       query?: Record<string, string>;
       skipAuth?: boolean;
+      signal?: AbortSignal;
+      keepalive?: boolean;
     } = {},
   ): Promise<T> {
     const res = await this.send(method, path, options);
@@ -94,7 +119,7 @@ export class HttpClient {
       res.status === 401 &&
       !options.skipAuth &&
       !this.adminSecret &&
-      !this.apiKey &&
+      !this._apiKey &&
       this.tokens.refreshToken
     ) {
       try {
@@ -136,6 +161,8 @@ export class HttpClient {
       formData?: FormData;
       query?: Record<string, string>;
       skipAuth?: boolean;
+      signal?: AbortSignal;
+      keepalive?: boolean;
     },
   ): Promise<Response> {
     let url = `${this.baseUrl}${path}`;
@@ -148,8 +175,8 @@ export class HttpClient {
     if (!options.skipAuth) {
       if (this.adminSecret) {
         headers.Authorization = `Bearer ${this.adminSecret}`;
-      } else if (this.apiKey) {
-        headers["X-Api-Key"] = this.apiKey;
+      } else if (this._apiKey) {
+        headers["X-Api-Key"] = this._apiKey;
       } else if (this.tokens.accessToken) {
         headers.Authorization = `Bearer ${this.tokens.accessToken}`;
       }
@@ -164,7 +191,13 @@ export class HttpClient {
       body = JSON.stringify(options.body);
     }
 
-    return fetch(url, { method, headers, body });
+    return fetch(url, {
+      method,
+      headers,
+      body,
+      signal: options.signal,
+      keepalive: options.keepalive,
+    });
   }
 
   private async parse<T>(res: Response): Promise<T> {

package/src/index.ts

@@ -38,14 +38,7 @@ export { AuthClient, type AuthSnapshot } from "./auth";
 export { BunBaseClient } from "./client";
 export { CollectionClient } from "./collection";
 export { RealtimeClient, type SubscribeOptions } from "./realtime";
-export {
-  type ImageTransformFit,
-  type ImageTransformFormat,
-  type ImageTransformOptions,
-  type SignedUploadResult,
-  StorageClient,
-  type UploadOptions,
-} from "./storage";
+export { type SignedUploadResult, StorageClient, type UploadOptions } from "./storage";
 export {
   type AggregateFunction,
   type AggregateResult,
@@ -73,9 +66,11 @@ export {
   type ListQuery,
   type ListResult,
   type LoginResult,
+  type PersistSessionOptions,
   type RealtimeCallback,
   type RealtimeEvent,
   type RealtimeEventType,
+  type StorageAdapter,
   type TotpChallenge,
   type TotpSetup,
   type UnsubscribeFn,

package/src/storage.ts

@@ -4,22 +4,6 @@ import type { HttpClient } from "./http";
 import type { FileRecord } from "./types";
 import { BunBaseError } from "./types";
 
-export type ImageTransformFit = "cover" | "contain" | "inside";
-export type ImageTransformFormat = "webp" | "jpeg" | "png";
-
-export interface ImageTransformOptions {
-  /** Output width in pixels (1–4096). */
-  width?: number;
-  /** Output height in pixels (1–4096). */
-  height?: number;
-  /** How to fit the image into the given dimensions. Default: "inside". */
-  fit?: ImageTransformFit;
-  /** Convert to this output format. Omit to keep the original format. */
-  format?: ImageTransformFormat;
-  /** Quality for JPEG/WebP, 1–100. Default: 85. */
-  quality?: number;
-}
-
 export interface UploadOptions {
   // Target storage bucket. Defaults to "default" if omitted.
   bucket?: string;
@@ -206,21 +190,10 @@ export class StorageClient {
   // Do NOT use this for private files — the browser cannot send the
   // Authorization header via <img src>. For private files, call signedUrl()
   // to get a time-limited signed URL instead.
-  downloadUrl(id: string, filename?: string | null, transform?: ImageTransformOptions): string {
+  downloadUrl(id: string, filename?: string | null): string {
     if (id.startsWith("http")) return id;
     const base = `${this.http.baseUrl}/api/v1/storage/${encodeURIComponent(id)}`;
-    let url = filename ? `${base}/${encodeURIComponent(filename)}` : base;
-    if (transform) {
-      const params = new URLSearchParams();
-      if (transform.width != null) params.set("w", String(transform.width));
-      if (transform.height != null) params.set("h", String(transform.height));
-      if (transform.fit) params.set("fit", transform.fit);
-      if (transform.format) params.set("format", transform.format);
-      if (transform.quality != null) params.set("q", String(transform.quality));
-      const qs = params.toString();
-      if (qs) url = `${url}?${qs}`;
-    }
-    return url;
+    return filename ? `${base}/${encodeURIComponent(filename)}` : base;
   }
 
   async list(): Promise<FileRecord[]> {

package/src/types.ts

@@ -237,6 +237,25 @@ export interface ApiKey {
   created_at: number;
 }
 
+// Minimal storage interface — deliberately async-compatible so the same API
+// works with synchronous Web Storage (localStorage, sessionStorage) and
+// Promise-based stores such as React Native's AsyncStorage or any custom
+// adapter (SecureStore, IndexedDB wrappers, etc.).
+export interface StorageAdapter {
+  getItem(key: string): string | null | Promise<string | null>;
+  setItem(key: string, value: string): void | Promise<void>;
+  removeItem(key: string): void | Promise<void>;
+}
+
+export interface PersistSessionOptions {
+  // Storage backend. Pass `localStorage`, `sessionStorage`, AsyncStorage, or
+  // any object that satisfies the StorageAdapter interface.
+  storage: StorageAdapter;
+  // Key prefix — isolates tokens per app so concurrent tabs don't clobber
+  // each other. Keys written: `{prefix}_bb_at`, `{prefix}_bb_rt`, `{prefix}_bb_user`.
+  prefix: string;
+}
+
 export interface BunBaseClientOptions {
   // Base URL of the BunBase server — no trailing slash.
   url: string;
@@ -248,6 +267,10 @@ export interface BunBaseClientOptions {
   // the token refresh flow. Use for server-to-server admin calls or Studio.
   // Alternatively, authenticate as a user with the "admin" role via login().
   adminSecret?: string;
+  // When set, the SDK automatically restores the session on construction and
+  // persists it on every auth change (login, refresh, logout). The loading
+  // field on AuthSnapshot is true while the async restore is in flight.
+  persistSession?: PersistSessionOptions;
 }
 
 export class BunBaseError extends Error {