@bunbase-ae/js 1.0.0

package/src/storage.ts

@@ -0,0 +1,206 @@
+// Storage client — upload, download URL, signed URL, list, delete.
+
+import type { HttpClient } from "./http";
+import type { FileRecord } from "./types";
+import { BunBaseError } from "./types";
+
+export interface UploadOptions {
+  // Target storage bucket. Defaults to "default" if omitted.
+  bucket?: string;
+  // Associate the file with a collection record.
+  collection?: string;
+  recordId?: string;
+  // Make the file publicly accessible without auth.
+  isPublic?: boolean;
+  // Upload progress callback (0–1). Uses XMLHttpRequest internally.
+  // Only available in browser and React Native environments.
+  onProgress?: (progress: number) => void;
+}
+
+export interface SignedUploadResult {
+  // Pre-signed PUT URL to upload directly to the storage backend.
+  // For local provider: points at BunBase — PUT registers metadata automatically.
+  // For S3 provider: points at S3 — call confirmUpload() after PUT to register metadata.
+  url: string;
+  key: string;
+  expires_in: number;
+}
+
+export class StorageClient {
+  constructor(private readonly http: HttpClient) {}
+
+  // Upload a file through BunBase (works for local storage; also works for S3
+  // but large files are better served with signedUpload()).
+  // Pass onProgress to track upload progress (browser/React Native only).
+  async upload(file: File | Blob, options: UploadOptions = {}): Promise<FileRecord> {
+    const form = new FormData();
+    form.append("file", file);
+    if (options.bucket) form.append("bucket", options.bucket);
+    if (options.collection) form.append("collection", options.collection);
+    if (options.recordId) form.append("record_id", options.recordId);
+    if (options.isPublic) form.append("is_public", "true");
+
+    if (options.onProgress) {
+      return this.uploadWithProgress(form, options.onProgress);
+    }
+
+    return this.http.request<FileRecord>("POST", "/api/v1/storage/upload", {
+      formData: form,
+    });
+  }
+
+  private uploadWithProgress(
+    form: FormData,
+    onProgress: (progress: number) => void,
+  ): Promise<FileRecord> {
+    return new Promise((resolve, reject) => {
+      const xhr = new XMLHttpRequest();
+      xhr.open("POST", `${this.http.baseUrl}/api/v1/storage/upload`);
+
+      for (const [key, value] of Object.entries(this.http.getAuthHeaders())) {
+        xhr.setRequestHeader(key, value);
+      }
+
+      xhr.upload.onprogress = (e) => {
+        if (e.lengthComputable) onProgress(e.loaded / e.total);
+      };
+
+      xhr.onload = () => {
+        if (xhr.status >= 200 && xhr.status < 300) {
+          try {
+            resolve(JSON.parse(xhr.responseText) as FileRecord);
+          } catch {
+            reject(new BunBaseError("Invalid response from server.", xhr.status, null));
+          }
+        } else {
+          let message = `Upload failed with status ${xhr.status}`;
+          let code: string | undefined;
+          let field: string | undefined;
+          try {
+            const body = JSON.parse(xhr.responseText) as Record<string, unknown>;
+            if (body.error) message = String(body.error);
+            if (body.code) code = String(body.code);
+            if (body.field) field = String(body.field);
+          } catch {
+            // ignore parse errors
+          }
+          reject(new BunBaseError(message, xhr.status, null, code, field));
+        }
+      };
+
+      xhr.onerror = () => reject(new BunBaseError("Upload failed: network error.", 0, null));
+      xhr.onabort = () => reject(new BunBaseError("Upload aborted.", 0, null));
+      xhr.send(form);
+    });
+  }
+
+  // Get a pre-signed PUT URL for direct upload.
+  // Local provider: PUT the file to the URL — metadata is registered automatically.
+  // S3 provider:   PUT the file to the URL, then call confirmUpload() to register metadata.
+  async signedUpload(
+    filename: string,
+    options: UploadOptions & { expiresIn?: number; contentType?: string } = {},
+  ): Promise<SignedUploadResult> {
+    return this.http.request<SignedUploadResult>("POST", "/api/v1/storage/sign", {
+      body: {
+        filename,
+        bucket: options.bucket,
+        is_public: options.isPublic,
+        content_type: options.contentType,
+        expires_in: options.expiresIn,
+      },
+    });
+  }
+
+  // Perform the full signed-upload flow in one call:
+  //   1. Get the pre-signed PUT URL from BunBase.
+  //   2. PUT the file directly to the storage backend.
+  //   3. For S3: call confirmUpload() to register metadata. Local handles this in step 2.
+  async signedUploadFile(
+    file: File | Blob,
+    options: UploadOptions & { expiresIn?: number } = {},
+  ): Promise<FileRecord> {
+    const filename = file instanceof File ? file.name : `upload-${Date.now()}`;
+    const { url, key } = await this.signedUpload(filename, {
+      ...options,
+      contentType: file.type || "application/octet-stream",
+    });
+
+    const putRes = await fetch(url, {
+      method: "PUT",
+      body: file,
+      headers: { "Content-Type": file.type || "application/octet-stream" },
+    });
+
+    // Local provider PUT returns FileRecord directly (201).
+    if (putRes.status === 201) {
+      return putRes.json() as Promise<FileRecord>;
+    }
+
+    if (!putRes.ok) {
+      throw new BunBaseError(
+        `Storage PUT failed with status ${putRes.status}.`,
+        putRes.status,
+        null,
+      );
+    }
+
+    // S3 provider: PUT succeeded (200/204) — register metadata with BunBase.
+    return this.confirmUpload({
+      key,
+      bucket: options.bucket,
+      filename,
+      collection: options.collection,
+      recordId: options.recordId,
+      isPublic: options.isPublic,
+      mimeType: file.type || "application/octet-stream",
+      size: file.size,
+    });
+  }
+
+  // Confirm an S3 presigned upload by registering the file metadata in BunBase.
+  // Not needed for local provider (the PUT handler registers metadata automatically).
+  async confirmUpload(options: {
+    key: string;
+    bucket?: string;
+    filename?: string;
+    collection?: string;
+    recordId?: string;
+    isPublic?: boolean;
+    mimeType?: string;
+    size?: number;
+  }): Promise<FileRecord> {
+    return this.http.request<FileRecord>("POST", "/api/v1/storage/confirm", {
+      body: {
+        key: options.key,
+        bucket: options.bucket,
+        filename: options.filename,
+        collection: options.collection,
+        record_id: options.recordId,
+        is_public: options.isPublic,
+        mime_type: options.mimeType,
+        size: options.size,
+      },
+    });
+  }
+
+  // Returns the direct download URL for a public file.
+  // Pass filename (from FileRecord.filename) to include the original file
+  // extension in the URL — helps browsers and CDNs identify the file type.
+  // 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): string {
+    if (id.startsWith("http")) return id;
+    const base = `${this.http.baseUrl}/api/v1/storage/${encodeURIComponent(id)}`;
+    return filename ? `${base}/${encodeURIComponent(filename)}` : base;
+  }
+
+  async list(): Promise<FileRecord[]> {
+    return this.http.request<FileRecord[]>("GET", "/api/v1/storage");
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.http.request<{ deleted: boolean }>("DELETE", `/api/v1/storage/${id}`);
+  }
+}

package/src/types.ts

@@ -0,0 +1,266 @@
+// Shared types for the BunBase TypeScript SDK.
+// These mirror the server's response shapes exactly.
+
+export interface BunBaseRecord {
+  _id: string;
+  _created_at: number;
+  _updated_at: number;
+  _owner_id: string | null;
+  _deleted_at?: number | null;
+}
+
+/**
+ * Resolves an expand shape to the concrete types returned by the server.
+ *
+ *   "one" relation:  { author_id: Profile }   → author_id is Profile & BunBaseRecord
+ *   "many" relation: { comments: Comment[] }  → comments is (Comment & BunBaseRecord)[]
+ */
+export type ExpandResult<TExpand extends Record<string, unknown>> = {
+  [K in keyof TExpand]: TExpand[K] extends (infer Item)[]
+    ? Item extends Record<string, unknown>
+      ? (Item & BunBaseRecord)[]
+      : Item[]
+    : TExpand[K] extends Record<string, unknown>
+      ? TExpand[K] & BunBaseRecord
+      : TExpand[K];
+};
+
+/**
+ * Adds a typed `expand` field to a record type.
+ *
+ * @example
+ * type Post = { title: string; author_id: string };
+ * type Profile = { display_name: string; avatar_url: string };
+ *
+ * // With CollectionClient:
+ * const posts = await client.collection<Post>("posts").list<{ author_id: Profile }>({ expand: ["author_id"] });
+ * posts.items[0].expand?.author_id // Profile & BunBaseRecord ✓
+ *
+ * // Or define the type upfront:
+ * type PostWithAuthor = WithExpand<Post, { author_id: Profile }>;
+ */
+export type WithExpand<T, TExpand extends Record<string, unknown> = Record<string, never>> = T & {
+  expand?: Partial<ExpandResult<TExpand>>;
+};
+
+export interface ListResult<T> {
+  items: T[];
+  /** Total count. Only present when `count: true` is passed in the list options. */
+  total?: number;
+  page: number;
+  limit: number;
+  /** Cursor for the next page. Pass as `after` in the next list call. */
+  next_cursor: string | null;
+}
+
+export interface AuthUser {
+  id: string;
+  email: string;
+  created_at: number;
+  updated_at: number;
+  is_verified: boolean;
+  role: string | null;
+  /** Freeform JSON object. Store display name, bio, avatar URL, etc. */
+  metadata: Record<string, unknown>;
+}
+
+export interface AuthResult {
+  access_token: string;
+  refresh_token: string;
+  expires_in: number;
+  user: AuthUser;
+}
+
+export interface FileRecord {
+  id: string;
+  key: string;
+  bucket: string;
+  filename: string | null;
+  collection: string | null;
+  record_id: string | null;
+  owner_id: string | null;
+  size: number;
+  mime_type: string;
+  is_public: boolean;
+  created_at: number;
+}
+
+// ─── Query types ──────────────────────────────────────────────────────────────
+
+export type FilterOperator = "eq" | "ne" | "gt" | "lt" | "gte" | "lte" | "like" | "in";
+
+export type FilterValue = string | number | boolean | string[] | number[];
+
+export interface FieldFilter {
+  [op: string]: FilterValue;
+}
+
+// Simple: { status: "published" }  → filter[status]=published
+// Operator: { age: { gte: 18 } }  → filter[age][gte]=18
+export type Filter<T = Record<string, unknown>> = {
+  [K in keyof T]?: T[K] | FieldFilter;
+} & {
+  [key: string]: FilterValue | FieldFilter | undefined;
+};
+
+export interface ListQuery<T = Record<string, unknown>> {
+  filter?: Filter<T>;
+  // Prefix field name with "-" for descending: "-_created_at"
+  sort?: string;
+  page?: number;
+  limit?: number;
+  // Return only these fields in each record
+  fields?: string[];
+  // Inline related records declared via the relations API.
+  // For "one" relations: pass the foreign key field name (e.g. "author_id").
+  // For "many" / "many_via" relations: pass from_field as declared.
+  expand?: string[];
+  // Cursor-based pagination: pass next_cursor from the previous list response.
+  // When set, page is ignored.
+  after?: string;
+  // Include soft-deleted records in the response. Default: false.
+  include_deleted?: boolean;
+  // Full-text search query. When set, results are filtered to matching records.
+  search?: string;
+  // Request total count. Default false — COUNT(*) is skipped for performance.
+  count?: boolean;
+}
+
+// ─── Batch operation types ────────────────────────────────────────────────────
+
+export interface BatchCreate<T = Record<string, unknown>> {
+  op: "create";
+  data: Partial<T>;
+}
+
+export interface BatchUpdate<T = Record<string, unknown>> {
+  op: "update";
+  id: string;
+  data: Partial<T>;
+}
+
+export interface BatchDelete {
+  op: "delete";
+  id: string;
+}
+
+export type BatchOperation<T = Record<string, unknown>> =
+  | BatchCreate<T>
+  | BatchUpdate<T>
+  | BatchDelete;
+
+export interface BatchResultCreate<T = Record<string, unknown>> {
+  op: "create";
+  record: T & BunBaseRecord;
+}
+
+export interface BatchResultUpdate<T = Record<string, unknown>> {
+  op: "update";
+  record: T & BunBaseRecord;
+}
+
+export interface BatchResultDelete {
+  op: "delete";
+  id: string;
+}
+
+export type BatchResult<T = Record<string, unknown>> =
+  | BatchResultCreate<T>
+  | BatchResultUpdate<T>
+  | BatchResultDelete;
+
+export interface GetQuery {
+  // Same expand semantics as ListQuery.
+  expand?: string[];
+}
+
+// ─── Field validation ─────────────────────────────────────────────────────────
+
+export interface FieldRule {
+  field: string;
+  required?: boolean;
+  /** Strings: min length. Numbers: min value. Arrays: min item count. */
+  min?: number;
+  /** Strings: max length. Numbers: max value. Arrays: max item count. */
+  max?: number;
+  /** Regex pattern — applied to string values only. */
+  regex?: string;
+  /** Allowed values — applied to any type. */
+  enum?: unknown[];
+}
+
+// ─── Aggregations ─────────────────────────────────────────────────────────────
+
+export type AggregateFunction = "sum" | "avg" | "min" | "max" | "count";
+
+export type AggregateResult =
+  | { value: number | null }
+  | { groups: Array<{ group: unknown; value: number | null }> };
+
+// ─── Realtime types ───────────────────────────────────────────────────────────
+
+export type RealtimeEventType = "create" | "update" | "delete";
+
+export interface RealtimeEvent<T = BunBaseRecord> {
+  event: RealtimeEventType;
+  collection: string;
+  record: T & BunBaseRecord;
+}
+
+export type RealtimeCallback<T = BunBaseRecord> = (event: RealtimeEvent<T>) => void;
+
+export type UnsubscribeFn = () => void;
+
+// ─── TOTP management ──────────────────────────────────────────────────────────
+
+// Returned by setupTotp(). Display the secret or otpauth_url to the user so
+// they can add the account to their authenticator app.
+export interface TotpSetup {
+  secret: string;
+  otpauth_url: string;
+}
+
+// ─── Client options ───────────────────────────────────────────────────────────
+
+// Returned by login() when the account has 2FA enabled.
+// Pass totp_token + a TOTP code to auth.verifyTotp() to complete sign-in.
+export interface TotpChallenge {
+  totp_required: true;
+  totp_token: string;
+}
+
+export type LoginResult = AuthResult | TotpChallenge;
+
+export interface ApiKey {
+  id: string;
+  name: string;
+  created_at: number;
+}
+
+export interface BunBaseClientOptions {
+  // Base URL of the BunBase server — no trailing slash.
+  url: string;
+  // Long-lived API key for server-to-server use. When set, the client sends
+  // X-Api-Key instead of Bearer tokens and skips the token refresh flow.
+  apiKey?: string;
+  // Admin secret — grants access to all /admin/* endpoints.
+  // When set, the client sends Authorization: Bearer <adminSecret> and skips
+  // 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;
+}
+
+export class BunBaseError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly body: unknown,
+    // Machine-readable error code from the server (e.g. "INVALID_CREDENTIALS").
+    public readonly code?: string,
+    // Field name that caused the error, for form validation UIs.
+    public readonly field?: string,
+  ) {
+    super(message);
+    this.name = "BunBaseError";
+  }
+}