@picobase_app/client 0.5.2 → 1.0.2

package/dist/index.mjs

@@ -1,130 +1,462 @@
-import PocketBase from 'pocketbase';
+// src/errors.ts
+var PicoBaseError = class extends Error {
+  constructor(message, code, status, details, fix) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    this.fix = fix;
+    this.name = "PicoBaseError";
+  }
+  /** Formatted error string including fix suggestion. */
+  toString() {
+    let s = `${this.name} [${this.code}]: ${this.message}`;
+    if (this.fix) s += `
+  Fix: ${this.fix}`;
+    return s;
+  }
+};
+var InstanceUnavailableError = class extends PicoBaseError {
+  constructor(message = "Instance is not available. It may be stopped or starting up.") {
+    super(
+      message,
+      "INSTANCE_UNAVAILABLE",
+      503,
+      void 0,
+      "Check your instance status in the PicoBase dashboard, or wait a few seconds and retry. If this persists, your instance may have been stopped \u2014 restart it with `picobase status`."
+    );
+    this.name = "InstanceUnavailableError";
+  }
+};
+var AuthorizationError = class extends PicoBaseError {
+  constructor(message = "Invalid or missing API key.") {
+    super(
+      message,
+      "UNAUTHORIZED",
+      401,
+      void 0,
+      'Make sure PICOBASE_API_KEY is set in your .env file and matches a valid key from your dashboard. Keys start with "pbk_". You can generate a new key at https://picobase.com/dashboard.'
+    );
+    this.name = "AuthorizationError";
+  }
+};
+var CollectionNotFoundError = class extends PicoBaseError {
+  constructor(collectionName) {
+    super(
+      `Collection "${collectionName}" not found.`,
+      "COLLECTION_NOT_FOUND",
+      404,
+      { collection: collectionName },
+      `Make sure the collection "${collectionName}" exists in your PicoBase instance. Collections are auto-created when you first write data, or you can create them manually in the PicoBase dashboard under Collections.`
+    );
+    this.name = "CollectionNotFoundError";
+  }
+};
+var RecordNotFoundError = class extends PicoBaseError {
+  constructor(collectionName, recordId) {
+    super(
+      `Record "${recordId}" not found in collection "${collectionName}".`,
+      "RECORD_NOT_FOUND",
+      404,
+      { collection: collectionName, recordId },
+      'Check that the record ID is correct. IDs are 15-character alphanumeric strings (e.g., "abc123def456789").'
+    );
+    this.name = "RecordNotFoundError";
+  }
+};
+var RequestError = class extends PicoBaseError {
+  constructor(message, status, details) {
+    const fix = requestErrorFix(status, message);
+    super(message, "REQUEST_FAILED", status, details, fix);
+    this.name = "RequestError";
+  }
+};
+var ConfigurationError = class extends PicoBaseError {
+  constructor(message, fix) {
+    super(message, "CONFIGURATION_ERROR", void 0, void 0, fix);
+    this.name = "ConfigurationError";
+  }
+};
+var RpcError = class extends PicoBaseError {
+  constructor(functionName, status, details) {
+    const fix = rpcErrorFix(functionName, status);
+    super(
+      `RPC function "${functionName}" failed.`,
+      "RPC_ERROR",
+      status,
+      details,
+      fix
+    );
+    this.name = "RpcError";
+  }
+};
+function rpcErrorFix(functionName, status) {
+  if (status === 404) {
+    return `The RPC endpoint "/api/rpc/${functionName}" does not exist. Create a custom route in your PocketBase instance to handle this RPC call. See: https://pocketbase.io/docs/js-routing/`;
+  }
+  if (status === 400) {
+    return "Check the parameters you are passing to this RPC function. The function may be expecting different parameters or types.";
+  }
+  if (status === 403) {
+    return "You don't have permission to call this RPC function. Check the authentication requirements for this endpoint in your PocketBase routes.";
+  }
+  return "Check your PicoBase instance logs for details about this RPC error. Ensure the custom route is correctly implemented in your PocketBase setup.";
+}
+function requestErrorFix(status, message) {
+  switch (status) {
+    case 400:
+      return "Check the data you are sending \u2014 a required field may be missing or have the wrong type. Run `picobase typegen` to regenerate types and check your field names.";
+    case 403:
+      return "You don't have permission for this action. Check your collection API rules in the dashboard. By default, only authenticated users can read/write records.";
+    case 404:
+      if (message.toLowerCase().includes("collection"))
+        return "This collection does not exist yet. Write a record to auto-create it, or create it in the dashboard.";
+      return "The requested resource was not found. Double-check IDs and collection names.";
+    case 413:
+      return "The request payload is too large. Check file upload size limits in your instance settings.";
+    case 429:
+      return "Too many requests. Add a short delay between requests or implement client-side caching.";
+    default:
+      return "If this error persists, check your PicoBase dashboard for instance health and logs.";
+  }
+}
 
-// src/client.ts
+// src/http.ts
+var PicoBaseHttpClient = class {
+  constructor(baseUrl, apiKey, options = {}) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+    this.timeout = options.timeout ?? 3e4;
+    this.maxColdStartRetries = options.maxColdStartRetries ?? 3;
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    this.getToken = options.getToken;
+  }
+  async send(path, init = {}) {
+    const { query, body: rawBody, ...restInit } = init;
+    let url = `${this.baseUrl}${path}`;
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== void 0 && v !== null) params.append(k, String(v));
+      }
+      const qs = params.toString();
+      if (qs) url += `?${qs}`;
+    }
+    const headers = {
+      ...restInit.headers ?? {}
+    };
+    headers["X-PicoBase-Key"] = this.apiKey;
+    const token = this.getToken?.();
+    if (token) headers["Authorization"] = `Bearer ${token}`;
+    let body;
+    if (rawBody instanceof FormData) {
+      body = rawBody;
+    } else if (rawBody !== void 0 && rawBody !== null) {
+      headers["Content-Type"] = "application/json";
+      body = typeof rawBody === "string" ? rawBody : JSON.stringify(rawBody);
+    }
+    let lastError = new Error("Unknown error");
+    for (let attempt = 0; attempt <= this.maxColdStartRetries; attempt++) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      let response;
+      try {
+        response = await this.fetchImpl(url, {
+          ...restInit,
+          headers,
+          body,
+          signal: controller.signal
+        });
+      } catch (fetchErr) {
+        clearTimeout(timeoutId);
+        const msg = fetchErr instanceof Error ? fetchErr.message : String(fetchErr);
+        throw new RequestError(msg, 0, fetchErr);
+      }
+      clearTimeout(timeoutId);
+      if (response.ok) {
+        if (response.status === 204) return void 0;
+        return await response.json();
+      }
+      let errorData = null;
+      try {
+        errorData = await response.json();
+      } catch {
+      }
+      const message = errorData?.message ?? errorData?.error ?? response.statusText;
+      const status = response.status;
+      if (status === 503) {
+        lastError = new RequestError(message, status, errorData);
+        if (attempt < this.maxColdStartRetries) {
+          const delay = Math.pow(2, attempt + 1) * 1e3;
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          continue;
+        }
+        break;
+      }
+      if (status === 401) {
+        const code = errorData?.code;
+        if (!code || code === "INVALID_API_KEY") throw new AuthorizationError();
+        throw new AuthorizationError(message);
+      }
+      if (status === 404) {
+        const lower = message.toLowerCase();
+        if (lower.includes("collection") && (lower.includes("not found") || lower.includes("missing"))) {
+          const match = message.match(/["']([^"']+)["']/);
+          throw new CollectionNotFoundError(match?.[1] ?? "unknown");
+        }
+      }
+      throw new RequestError(message, status, errorData);
+    }
+    throw new InstanceUnavailableError(
+      `Instance unavailable after ${this.maxColdStartRetries} retries. Original error: ${lastError.message}`
+    );
+  }
+};
+
+// src/auth-store.ts
+var STORAGE_KEY_TOKEN = "picobase_token";
+var STORAGE_KEY_RECORD = "picobase_record";
+var AuthStore = class {
+  constructor() {
+    this._token = "";
+    this._record = null;
+    this._listeners = /* @__PURE__ */ new Set();
+    this._loadFromStorage();
+  }
+  /** Current JWT, or empty string if not signed in. */
+  get token() {
+    return this._token;
+  }
+  /** Currently signed-in user record, or null. */
+  get record() {
+    return this._record;
+  }
+  /**
+   * Returns true if a token is present and not yet expired.
+   * Checks JWT `exp` claim — no signature verification (the server does that).
+   */
+  get isValid() {
+    if (!this._token) return false;
+    try {
+      const parts = this._token.split(".");
+      if (parts.length !== 3) return false;
+      const padded = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+      const json = typeof atob !== "undefined" ? atob(padded) : Buffer.from(padded, "base64").toString("utf8");
+      const payload = JSON.parse(json);
+      return typeof payload.exp === "number" && payload.exp * 1e3 > Date.now();
+    } catch {
+      return false;
+    }
+  }
+  /** Save a token (and optionally the user record). Persists to localStorage. */
+  save(token, record = null) {
+    this._token = token;
+    this._record = record;
+    try {
+      if (typeof localStorage !== "undefined") {
+        localStorage.setItem(STORAGE_KEY_TOKEN, token);
+        if (record) {
+          localStorage.setItem(STORAGE_KEY_RECORD, JSON.stringify(record));
+        } else {
+          localStorage.removeItem(STORAGE_KEY_RECORD);
+        }
+      }
+    } catch {
+    }
+    this._notify();
+  }
+  /** Clear the token and user record. Removes from localStorage. */
+  clear() {
+    this._token = "";
+    this._record = null;
+    try {
+      if (typeof localStorage !== "undefined") {
+        localStorage.removeItem(STORAGE_KEY_TOKEN);
+        localStorage.removeItem(STORAGE_KEY_RECORD);
+      }
+    } catch {
+    }
+    this._notify();
+  }
+  /**
+   * Register a listener for auth state changes.
+   * @returns Unsubscribe function.
+   */
+  onChange(callback) {
+    this._listeners.add(callback);
+    return () => {
+      this._listeners.delete(callback);
+    };
+  }
+  // ── Private ───────────────────────────────────────────────────────────────
+  _loadFromStorage() {
+    try {
+      if (typeof localStorage !== "undefined") {
+        const token = localStorage.getItem(STORAGE_KEY_TOKEN);
+        if (token) {
+          this._token = token;
+          const raw = localStorage.getItem(STORAGE_KEY_RECORD);
+          if (raw) {
+            try {
+              this._record = JSON.parse(raw);
+            } catch {
+            }
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  _notify() {
+    for (const cb of this._listeners) {
+      try {
+        cb(this._token, this._record);
+      } catch {
+      }
+    }
+  }
+};
 
 // src/auth.ts
 var PicoBaseAuth = class {
-  constructor(pb) {
+  constructor(http, authStore) {
     this.listeners = /* @__PURE__ */ new Set();
-    this._collection = "users";
-    this.pb = pb;
-    this.pb.authStore.onChange((token) => {
-      const record = this.pb.authStore.record ?? null;
+    this._collection = "_auth_users";
+    this.http = http;
+    this.authStore = authStore;
+    this.authStore.onChange((token) => {
+      const record = this.authStore.record;
       const event = token ? "SIGNED_IN" : "SIGNED_OUT";
       this._notify(event, record);
     });
   }
   /**
    * Set which collection to authenticate against.
-   * Defaults to 'users'. Use this if you have a custom auth collection.
+   * Defaults to '_auth_users'. Use this if you have a custom auth collection.
    */
   setCollection(name) {
     this._collection = name;
     return this;
   }
   /**
-   * Create a new user account.
+   * Create a new user account. Automatically signs the user in after creation.
    */
   async signUp(options) {
     const { email, password, passwordConfirm, ...rest } = options;
-    await this.pb.collection(this._collection).create({
-      email,
-      password,
-      passwordConfirm: passwordConfirm ?? password,
-      ...rest
+    await this.http.send("/api/db/collections/_auth_users/records", {
+      method: "POST",
+      body: {
+        email,
+        password,
+        passwordConfirm: passwordConfirm ?? password,
+        ...rest
+      }
     });
-    const authResult = await this.pb.collection(this._collection).authWithPassword(email, password);
-    return {
-      token: authResult.token,
-      record: authResult.record
-    };
+    return this.signIn({ email, password });
   }
   /**
    * Sign in with email and password.
    */
   async signIn(options) {
-    const result = await this.pb.collection(this._collection).authWithPassword(options.email, options.password);
-    return {
-      token: result.token,
-      record: result.record
-    };
+    const result = await this.http.send(
+      `/api/db/collections/${this._collection}/auth-with-password`,
+      {
+        method: "POST",
+        body: { identity: options.email, password: options.password }
+      }
+    );
+    this.authStore.save(result.token, result.record);
+    return { token: result.token, record: result.record };
   }
   /**
    * Sign in with an OAuth2 provider (Google, GitHub, etc.).
-   *
-   * In browser environments this opens a popup/redirect to the provider.
-   * Configure providers in your PicoBase dashboard.
    */
   async signInWithOAuth(options) {
-    const result = await this.pb.collection(this._collection).authWithOAuth2({
-      provider: options.provider,
-      scopes: options.scopes,
-      createData: options.createData,
-      urlCallback: options.urlCallback
-    });
-    return {
-      token: result.token,
-      record: result.record
-    };
+    const result = await this.http.send(
+      `/api/db/collections/${this._collection}/auth-with-oauth2`,
+      {
+        method: "POST",
+        body: {
+          provider: options.provider,
+          scopes: options.scopes,
+          createData: options.createData
+        }
+      }
+    );
+    this.authStore.save(result.token, result.record);
+    return { token: result.token, record: result.record };
   }
   /**
    * Refresh the current auth token.
    */
   async refreshToken() {
-    const result = await this.pb.collection(this._collection).authRefresh();
+    const result = await this.http.send(
+      `/api/db/collections/${this._collection}/auth-refresh`,
+      { method: "POST" }
+    );
+    this.authStore.save(result.token, result.record);
     this._notify("TOKEN_REFRESHED", result.record);
-    return {
-      token: result.token,
-      record: result.record
-    };
+    return { token: result.token, record: result.record };
   }
   /**
    * Send a password reset email.
    */
   async requestPasswordReset(email) {
-    await this.pb.collection(this._collection).requestPasswordReset(email);
+    await this.http.send(
+      `/api/db/collections/${this._collection}/request-password-reset`,
+      { method: "POST", body: { email } }
+    );
   }
   /**
    * Confirm a password reset with the token from the reset email.
    */
   async confirmPasswordReset(token, password, passwordConfirm) {
-    await this.pb.collection(this._collection).confirmPasswordReset(token, password, passwordConfirm ?? password);
+    await this.http.send(
+      `/api/db/collections/${this._collection}/confirm-password-reset`,
+      { method: "POST", body: { token, password, passwordConfirm: passwordConfirm ?? password } }
+    );
   }
   /**
    * Send an email verification email.
    */
   async requestVerification(email) {
-    await this.pb.collection(this._collection).requestVerification(email);
+    await this.http.send(
+      `/api/db/collections/${this._collection}/request-verification`,
+      { method: "POST", body: { email } }
+    );
   }
   /**
    * Confirm email verification with the token from the verification email.
    */
   async confirmVerification(token) {
-    await this.pb.collection(this._collection).confirmVerification(token);
+    await this.http.send(
+      `/api/db/collections/${this._collection}/confirm-verification`,
+      { method: "POST", body: { token } }
+    );
   }
   /**
    * Sign out the current user. Clears the local auth store.
    */
   signOut() {
-    this.pb.authStore.clear();
+    this.authStore.clear();
   }
   /**
    * Get the currently authenticated user record, or `null` if not signed in.
    */
   get user() {
-    return this.pb.authStore.record;
+    return this.authStore.record;
   }
   /**
    * Get the current auth token, or empty string if not signed in.
    */
   get token() {
-    return this.pb.authStore.token;
+    return this.authStore.token;
   }
   /**
    * Check if the current auth session is valid (token exists and not expired).
    */
   get isValid() {
-    return this.pb.authStore.isValid;
+    return this.authStore.isValid;
   }
   /**
    * Listen to auth state changes. Returns an unsubscribe function.
@@ -132,9 +464,7 @@ var PicoBaseAuth = class {
    * @example
    * ```ts
    * const unsubscribe = pb.auth.onStateChange((event, record) => {
-   *   if (event === 'SIGNED_IN') {
-   *     console.log('Welcome', record.email)
-   *   }
+   *   if (event === 'SIGNED_IN') console.log('Welcome', record.email)
    * })
    *
    * // Later:
@@ -159,9 +489,10 @@ var PicoBaseAuth = class {
 
 // src/collection.ts
 var PicoBaseCollection = class {
-  constructor(pb, name) {
-    this.pb = pb;
+  constructor(http, name, realtime) {
+    this.http = http;
     this.name = name;
+    this.rt = realtime;
   }
   /**
    * Fetch a paginated list of records.
@@ -171,7 +502,17 @@ var PicoBaseCollection = class {
    * @param options - Filter, sort, expand, fields.
    */
   async getList(page = 1, perPage = 30, options = {}) {
-    return this.pb.collection(this.name).getList(page, perPage, options);
+    const { sort, filter, expand, fields, skipTotal, ...rest } = options;
+    const query = { page, perPage, ...rest };
+    if (sort) query.sort = sort;
+    if (filter) query.filter = filter;
+    if (expand) query.expand = expand;
+    if (fields) query.fields = fields;
+    if (skipTotal) query.skipTotal = "1";
+    return this.http.send(
+      `/api/db/collections/${this.name}/records`,
+      { method: "GET", query }
+    );
   }
   /**
    * Fetch all records matching the filter (auto-paginates).
@@ -179,13 +520,28 @@ var PicoBaseCollection = class {
    * **Warning:** Use with caution on large collections. Prefer `getList()` with pagination.
    */
   async getFullList(options = {}) {
-    return this.pb.collection(this.name).getFullList(options);
+    const all = [];
+    let page = 1;
+    const perPage = 200;
+    while (true) {
+      const result = await this.getList(page, perPage, options);
+      all.push(...result.items);
+      if (page >= result.totalPages) break;
+      page++;
+    }
+    return all;
   }
   /**
    * Fetch a single record by ID.
    */
   async getOne(id, options = {}) {
-    return this.pb.collection(this.name).getOne(id, options);
+    const query = {};
+    if (options.expand) query.expand = options.expand;
+    if (options.fields) query.fields = options.fields;
+    return this.http.send(
+      `/api/db/collections/${this.name}/records/${id}`,
+      { method: "GET", query: Object.keys(query).length ? query : void 0 }
+    );
   }
   /**
    * Fetch the first record matching a filter.
@@ -196,7 +552,11 @@ var PicoBaseCollection = class {
    * ```
    */
   async getFirstListItem(filter, options = {}) {
-    return this.pb.collection(this.name).getFirstListItem(filter, options);
+    const result = await this.getList(1, 1, { filter, ...options });
+    if (!result.items.length) {
+      throw new RecordNotFoundError(this.name, filter);
+    }
+    return result.items[0];
   }
   /**
    * Create a new record.
@@ -204,7 +564,17 @@ var PicoBaseCollection = class {
    * @param data - Record data. Can be a plain object or `FormData` (for file uploads).
    */
   async create(data, options = {}) {
-    return this.pb.collection(this.name).create(data, options);
+    const query = {};
+    if (options.expand) query.expand = options.expand;
+    if (options.fields) query.fields = options.fields;
+    return this.http.send(
+      `/api/db/collections/${this.name}/records`,
+      {
+        method: "POST",
+        body: data,
+        query: Object.keys(query).length ? query : void 0
+      }
+    );
   }
   /**
    * Update an existing record.
@@ -213,19 +583,33 @@ var PicoBaseCollection = class {
    * @param data - Fields to update. Can be a plain object or `FormData`.
    */
   async update(id, data, options = {}) {
-    return this.pb.collection(this.name).update(id, data, options);
+    const query = {};
+    if (options.expand) query.expand = options.expand;
+    if (options.fields) query.fields = options.fields;
+    return this.http.send(
+      `/api/db/collections/${this.name}/records/${id}`,
+      {
+        method: "PATCH",
+        body: data,
+        query: Object.keys(query).length ? query : void 0
+      }
+    );
   }
   /**
    * Delete a record by ID.
    */
   async delete(id) {
-    return this.pb.collection(this.name).delete(id);
+    await this.http.send(
+      `/api/db/collections/${this.name}/records/${id}`,
+      { method: "DELETE" }
+    );
+    return true;
   }
   /**
    * Subscribe to realtime changes on this collection.
    *
    * @param callback - Called on every create/update/delete event.
-   * @param filter - Optional: only receive events matching this filter.
+   * @param filter - Optional: only receive events matching this filter (client-side).
    * @returns Unsubscribe function.
    *
    * @example
@@ -239,9 +623,7 @@ var PicoBaseCollection = class {
    * ```
    */
   async subscribe(callback, filter) {
-    const topic = "*";
-    await this.pb.collection(this.name).subscribe(topic, callback, filter ? { filter } : void 0);
-    return () => this.pb.collection(this.name).unsubscribe(topic);
+    return this.rt.subscribe(this.name, callback);
   }
   /**
    * Subscribe to changes on a specific record.
@@ -251,15 +633,20 @@ var PicoBaseCollection = class {
    * @returns Unsubscribe function.
    */
   async subscribeOne(id, callback) {
-    await this.pb.collection(this.name).subscribe(id, callback);
-    return () => this.pb.collection(this.name).unsubscribe(id);
+    return this.rt.subscribeRecord(this.name, id, callback);
   }
 };
 
 // src/realtime.ts
 var PicoBaseRealtime = class {
-  constructor(pb) {
-    this.pb = pb;
+  constructor(baseUrl, apiKey, getToken) {
+    this.eventSource = null;
+    // key = collection or collection/recordId
+    this.subs = /* @__PURE__ */ new Map();
+    this.counter = 0;
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+    this.getToken = getToken;
   }
   /**
    * Subscribe to realtime events on a collection.
@@ -269,8 +656,11 @@ var PicoBaseRealtime = class {
    * @returns Unsubscribe function.
    */
   async subscribe(collection, callback) {
-    await this.pb.collection(collection).subscribe("*", callback);
-    return () => this.pb.collection(collection).unsubscribe("*");
+    const id = this._addSub({ collection, callback });
+    this._ensureConnection();
+    return async () => {
+      this._removeSub(id);
+    };
   }
   /**
    * Subscribe to realtime events on a specific record.
@@ -281,242 +671,217 @@ var PicoBaseRealtime = class {
    * @returns Unsubscribe function.
    */
   async subscribeRecord(collection, recordId, callback) {
-    await this.pb.collection(collection).subscribe(recordId, callback);
-    return () => this.pb.collection(collection).unsubscribe(recordId);
+    const id = this._addSub({ collection, recordId, callback });
+    this._ensureConnection();
+    return async () => {
+      this._removeSub(id);
+    };
   }
   /**
    * Unsubscribe from all realtime events on a collection.
    */
   async unsubscribe(collection) {
-    await this.pb.collection(collection).unsubscribe();
+    this.subs.delete(collection);
+    this._pruneIfEmpty();
   }
   /**
-   * Unsubscribe from ALL realtime events. The SSE connection will be
-   * automatically closed when there are no remaining subscriptions.
+   * Unsubscribe from ALL realtime events and close the SSE connection.
    */
   async disconnectAll() {
-    await this.pb.realtime.unsubscribe();
+    this.subs.clear();
+    this._closeConnection();
+  }
+  // ── Private ───────────────────────────────────────────────────────────────
+  _addSub(sub) {
+    const id = `sub_${++this.counter}`;
+    const key = sub.recordId ? `${sub.collection}/${sub.recordId}` : sub.collection;
+    if (!this.subs.has(key)) this.subs.set(key, /* @__PURE__ */ new Set());
+    this.subs.get(key).add({ ...sub, _id: id });
+    return id;
+  }
+  _removeSub(id) {
+    for (const [key, set] of this.subs) {
+      for (const sub of set) {
+        if (sub._id === id) {
+          set.delete(sub);
+          if (set.size === 0) this.subs.delete(key);
+          break;
+        }
+      }
+    }
+    this._pruneIfEmpty();
+  }
+  _pruneIfEmpty() {
+    if (this.subs.size === 0) this._closeConnection();
+  }
+  /**
+   * Open SSE connection to `/api/db/realtime`.
+   * No-ops in environments where EventSource is unavailable (SSR / Node).
+   */
+  _ensureConnection() {
+    if (this.eventSource) return;
+    if (typeof EventSource === "undefined") return;
+    const url = new URL(`${this.baseUrl}/api/db/realtime`);
+    url.searchParams.set("apiKey", this.apiKey);
+    const token = this.getToken();
+    if (token) url.searchParams.set("token", token);
+    const es = new EventSource(url.toString());
+    this.eventSource = es;
+    es.onmessage = (event) => {
+      try {
+        const data = JSON.parse(event.data);
+        this._dispatch(data);
+      } catch {
+      }
+    };
+    for (const action of ["create", "update", "delete"]) {
+      es.addEventListener(action, (event) => {
+        try {
+          const data = JSON.parse(event.data);
+          this._dispatch(data);
+        } catch {
+        }
+      });
+    }
+    es.onerror = () => {
+      if (this.subs.size === 0) this._closeConnection();
+    };
+  }
+  _closeConnection() {
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+  }
+  _dispatch(event) {
+    const payload = {
+      action: event.action,
+      record: event.record
+    };
+    const collSubs = this.subs.get(event.collection);
+    if (collSubs) {
+      for (const sub of collSubs) {
+        try {
+          sub.callback(payload);
+        } catch {
+        }
+      }
+    }
+    const recordKey = `${event.collection}/${event.record?.id}`;
+    const recSubs = this.subs.get(recordKey);
+    if (recSubs) {
+      for (const sub of recSubs) {
+        try {
+          sub.callback(payload);
+        } catch {
+        }
+      }
+    }
   }
 };
 
 // src/storage.ts
 var PicoBaseStorage = class {
-  constructor(pb) {
-    this.pb = pb;
+  constructor(baseUrl, http) {
+    this.baseUrl = baseUrl;
+    this.http = http;
   }
   /**
-   * Get the public URL for a file attached to a record.
+   * Get the URL for a file attached to a record.
    *
-   * @param record - The record that owns the file.
+   * @param record - The record that owns the file. Must have `collectionName` and `id`.
    * @param filename - The filename (as stored in the record's file field).
    * @param options - Optional: thumb size, token for protected files, download flag.
    */
   getFileUrl(record, filename, options = {}) {
-    const queryParams = {};
-    if (options.thumb) {
-      queryParams["thumb"] = options.thumb;
-    }
-    if (options.token) {
-      queryParams["token"] = options.token;
-    }
-    if (options.download) {
-      queryParams["download"] = "1";
-    }
-    return this.pb.files.getURL(record, filename, queryParams);
+    const collection = record.collectionName ?? "";
+    const recordId = record.id;
+    let url = `${this.baseUrl}/api/db/files/${collection}/${recordId}/${filename}`;
+    const params = new URLSearchParams();
+    if (options.thumb) params.set("thumb", options.thumb);
+    if (options.token) params.set("token", options.token);
+    if (options.download) params.set("download", "1");
+    const qs = params.toString();
+    if (qs) url += `?${qs}`;
+    return url;
   }
   /**
-   * Generate a temporary file access token.
-   *
-   * Use this for accessing protected files. Tokens are short-lived.
+   * Generate a temporary file access token for protected files.
+   * Tokens are short-lived. Available after Phase 7 ships.
    */
   async getFileToken() {
-    return this.pb.files.getToken();
+    const result = await this.http.send(
+      "/api/db/files/token",
+      { method: "POST" }
+    );
+    return result.token;
   }
 };
 
 // src/admin.ts
 var PicoBaseAdmin = class {
-  constructor(pb) {
-    this.pb = pb;
+  constructor(http) {
+    this.http = http;
   }
   /**
    * Fetch a list of all collections.
    */
   async listCollections() {
-    const result = await this.pb.send("/api/collections", {
-      method: "GET"
-    });
-    return result.items || [];
+    const result = await this.http.send(
+      "/api/db/collections",
+      { method: "GET" }
+    );
+    return result.items ?? [];
   }
   /**
    * Fetch a single collection by ID or name.
    */
   async getCollection(idOrName) {
-    return this.pb.send(`/api/collections/${idOrName}`, {
-      method: "GET"
-    });
+    return this.http.send(
+      `/api/db/collections/${idOrName}`,
+      { method: "GET" }
+    );
   }
   /**
    * Create a new collection.
+   *
+   * @param data.type - `"flexible"` (JSONB, schema-free) or `"strict"` (typed SQL columns).
    */
   async createCollection(data) {
-    return this.pb.send("/api/collections", {
-      method: "POST",
-      body: data
-    });
+    return this.http.send(
+      "/api/db/collections",
+      { method: "POST", body: data }
+    );
   }
   /**
    * Update an existing collection.
    */
   async updateCollection(idOrName, data) {
-    return this.pb.send(`/api/collections/${idOrName}`, {
-      method: "PATCH",
-      body: data
-    });
+    return this.http.send(
+      `/api/db/collections/${idOrName}`,
+      { method: "PATCH", body: data }
+    );
   }
   /**
    * Delete a collection.
    */
   async deleteCollection(idOrName) {
     try {
-      await this.pb.send(`/api/collections/${idOrName}`, {
-        method: "DELETE"
-      });
+      await this.http.send(
+        `/api/db/collections/${idOrName}`,
+        { method: "DELETE" }
+      );
       return true;
-    } catch (e) {
+    } catch {
       return false;
     }
   }
 };
 
-// src/errors.ts
-var PicoBaseError = class extends Error {
-  constructor(message, code, status, details, fix) {
-    super(message);
-    this.code = code;
-    this.status = status;
-    this.details = details;
-    this.fix = fix;
-    this.name = "PicoBaseError";
-  }
-  /** Formatted error string including fix suggestion. */
-  toString() {
-    let s = `${this.name} [${this.code}]: ${this.message}`;
-    if (this.fix) s += `
-  Fix: ${this.fix}`;
-    return s;
-  }
-};
-var InstanceUnavailableError = class extends PicoBaseError {
-  constructor(message = "Instance is not available. It may be stopped or starting up.") {
-    super(
-      message,
-      "INSTANCE_UNAVAILABLE",
-      503,
-      void 0,
-      "Check your instance status in the PicoBase dashboard, or wait a few seconds and retry. If this persists, your instance may have been stopped \u2014 restart it with `picobase status`."
-    );
-    this.name = "InstanceUnavailableError";
-  }
-};
-var AuthorizationError = class extends PicoBaseError {
-  constructor(message = "Invalid or missing API key.") {
-    super(
-      message,
-      "UNAUTHORIZED",
-      401,
-      void 0,
-      'Make sure PICOBASE_API_KEY is set in your .env file and matches a valid key from your dashboard. Keys start with "pbk_". You can generate a new key at https://picobase.com/dashboard.'
-    );
-    this.name = "AuthorizationError";
-  }
-};
-var CollectionNotFoundError = class extends PicoBaseError {
-  constructor(collectionName) {
-    super(
-      `Collection "${collectionName}" not found.`,
-      "COLLECTION_NOT_FOUND",
-      404,
-      { collection: collectionName },
-      `Make sure the collection "${collectionName}" exists in your PicoBase instance. Collections are auto-created when you first write data, or you can create them manually in the PicoBase dashboard under Collections.`
-    );
-    this.name = "CollectionNotFoundError";
-  }
-};
-var RecordNotFoundError = class extends PicoBaseError {
-  constructor(collectionName, recordId) {
-    super(
-      `Record "${recordId}" not found in collection "${collectionName}".`,
-      "RECORD_NOT_FOUND",
-      404,
-      { collection: collectionName, recordId },
-      'Check that the record ID is correct. IDs are 15-character alphanumeric strings (e.g., "abc123def456789").'
-    );
-    this.name = "RecordNotFoundError";
-  }
-};
-var RequestError = class extends PicoBaseError {
-  constructor(message, status, details) {
-    const fix = requestErrorFix(status, message);
-    super(message, "REQUEST_FAILED", status, details, fix);
-    this.name = "RequestError";
-  }
-};
-var ConfigurationError = class extends PicoBaseError {
-  constructor(message, fix) {
-    super(message, "CONFIGURATION_ERROR", void 0, void 0, fix);
-    this.name = "ConfigurationError";
-  }
-};
-var RpcError = class extends PicoBaseError {
-  constructor(functionName, status, details) {
-    const fix = rpcErrorFix(functionName, status);
-    super(
-      `RPC function "${functionName}" failed.`,
-      "RPC_ERROR",
-      status,
-      details,
-      fix
-    );
-    this.name = "RpcError";
-  }
-};
-function rpcErrorFix(functionName, status) {
-  if (status === 404) {
-    return `The RPC endpoint "/api/rpc/${functionName}" does not exist. Create a custom route in your PocketBase instance to handle this RPC call. See: https://pocketbase.io/docs/js-routing/`;
-  }
-  if (status === 400) {
-    return "Check the parameters you are passing to this RPC function. The function may be expecting different parameters or types.";
-  }
-  if (status === 403) {
-    return "You don't have permission to call this RPC function. Check the authentication requirements for this endpoint in your PocketBase routes.";
-  }
-  return "Check your PicoBase instance logs for details about this RPC error. Ensure the custom route is correctly implemented in your PocketBase setup.";
-}
-function requestErrorFix(status, message) {
-  switch (status) {
-    case 400:
-      return "Check the data you are sending \u2014 a required field may be missing or have the wrong type. Run `picobase typegen` to regenerate types and check your field names.";
-    case 403:
-      return "You don't have permission for this action. Check your collection API rules in the dashboard. By default, only authenticated users can read/write records.";
-    case 404:
-      if (message.toLowerCase().includes("collection"))
-        return "This collection does not exist yet. Write a record to auto-create it, or create it in the dashboard.";
-      return "The requested resource was not found. Double-check IDs and collection names.";
-    case 413:
-      return "The request payload is too large. Check file upload size limits in your instance settings.";
-    case 429:
-      return "Too many requests. Add a short delay between requests or implement client-side caching.";
-    default:
-      return "If this error persists, check your PicoBase dashboard for instance health and logs.";
-  }
-}
-
 // src/client.ts
 var DEFAULT_OPTIONS = {
   timeout: 3e4,
-  maxColdStartRetries: 3,
-  lang: "en-US"
+  maxColdStartRetries: 3
 };
 var PicoBaseClient = class {
   constructor(url, apiKey, options = {}) {
@@ -538,25 +903,19 @@ var PicoBaseClient = class {
         `Use the full URL: createClient("https://${url}", "...")`
       );
     }
-    this.apiKey = apiKey;
-    this.options = { ...DEFAULT_OPTIONS, ...options };
-    const baseUrl = url.replace(/\/+$/, "");
-    this.pb = new PocketBase(baseUrl);
-    this.pb.autoCancellation(false);
-    if (this.options.lang) {
-      this.pb.lang = this.options.lang;
-    }
-    this.pb.beforeSend = (url2, reqInit) => {
-      const headers = reqInit.headers ?? {};
-      headers["X-PicoBase-Key"] = this.apiKey;
-      reqInit.headers = headers;
-      return { url: url2, options: reqInit };
-    };
-    this._wrapSendWithRetry();
-    this.auth = new PicoBaseAuth(this.pb);
-    this.realtime = new PicoBaseRealtime(this.pb);
-    this.storage = new PicoBaseStorage(this.pb);
-    this.admin = new PicoBaseAdmin(this.pb);
+    const mergedOptions = { ...DEFAULT_OPTIONS, ...options };
+    this.baseUrl = url.replace(/\/+$/, "");
+    this._authStore = new AuthStore();
+    this._http = new PicoBaseHttpClient(this.baseUrl, apiKey, {
+      timeout: mergedOptions.timeout,
+      maxColdStartRetries: mergedOptions.maxColdStartRetries,
+      fetch: options.fetch,
+      getToken: () => this._authStore.token
+    });
+    this.auth = new PicoBaseAuth(this._http, this._authStore);
+    this.realtime = new PicoBaseRealtime(this.baseUrl, apiKey, () => this._authStore.token);
+    this.storage = new PicoBaseStorage(this.baseUrl, this._http);
+    this.admin = new PicoBaseAdmin(this._http);
   }
   /**
    * Access a collection for CRUD operations.
@@ -567,40 +926,23 @@ var PicoBaseClient = class {
    * ```
    */
   collection(name) {
-    return new PicoBaseCollection(this.pb, name);
+    return new PicoBaseCollection(this._http, name, this.realtime);
   }
   /**
-   * Call a server-side function (PocketBase custom API endpoint).
-   * Proxies to PocketBase's send() method.
+   * Send a raw HTTP request to the PicoBase API.
    */
   async send(path, options) {
-    return this.pb.send(path, options ?? {});
+    return this._http.send(path, options);
   }
   /**
-   * Call a remote procedure (RPC) - a convenience method for calling custom API endpoints.
+   * Call a remote procedure (RPC) — convenience wrapper for custom API endpoints.
    *
-   * Maps Supabase-style RPC calls to PicoBase custom endpoints:
-   * - `pb.rpc('my_function', params)` → `POST /api/rpc/my_function` with params as body
+   * Maps Supabase-style RPC calls: `pb.rpc('my_fn', params)` → `POST /api/rpc/my_fn`
    *
    * @example
    * ```ts
-   * // Simple RPC call
    * const result = await pb.rpc('calculate_total', { cart_id: '123' })
-   *
-   * // Complex RPC with typed response
-   * interface DashboardStats {
-   *   posts: number
-   *   comments: number
-   *   followers: number
-   * }
-   * const stats = await pb.rpc<DashboardStats>('get_dashboard_stats', {
-   *   user_id: currentUser.id
-   * })
    * ```
-   *
-   * @param functionName The name of the RPC function to call
-   * @param params Optional parameters to pass to the function
-   * @returns The function result
    */
   async rpc(functionName, params) {
     try {
@@ -610,29 +952,19 @@ var PicoBaseClient = class {
       });
     } catch (err) {
       const status = err?.status ?? 500;
-      const details = err?.data;
+      const details = err?.details;
       throw new RpcError(functionName, status, details);
     }
   }
   /**
-   * Proactively wake up the instance if it's sleeping and wait for it to be ready.
-   * Useful to call when a user navigates to a login page or before critical operations,
-   * to absorb the cold-start latency upfront.
-   * 
-   * This method guarantees that the instance is fully running and able to serve requests
-   * when the promise resolves.
-   * 
-   * @example
-   * ```ts
-   * // In a useEffect on your login page:
-   * useEffect(() => {
-   *   pb.wake().catch(console.error)
-   * }, [])
-   * ```
+   * Proactively warm up the Neon connection after scale-to-zero.
+   *
+   * Useful to call when a user navigates to a login page or before critical
+   * operations, to absorb cold-start latency upfront.
    */
   async wake() {
     try {
-      await this.send("/api/health", { method: "GET" });
+      await this.send("/api/db/health", { method: "GET" });
       return true;
     } catch (err) {
       console.warn("Failed to wake instance:", err);
@@ -643,57 +975,13 @@ var PicoBaseClient = class {
    * Get the current auth token (if signed in), or empty string.
    */
   get token() {
-    return this.pb.authStore.token;
+    return this._authStore.token;
   }
   /**
    * Check if a user is currently authenticated.
    */
   get isAuthenticated() {
-    return this.pb.authStore.isValid;
-  }
-  /**
-   * Monkey-patch pb.send to retry on 503 (cold start).
-   *
-   * When an instance is stopped or starting, the proxy returns 503.
-   * The SDK automatically retries with exponential backoff so the developer
-   * doesn't have to handle cold-start logic.
-   */
-  _wrapSendWithRetry() {
-    const originalSend = this.pb.send.bind(this.pb);
-    const maxRetries = this.options.maxColdStartRetries;
-    this.pb.send = async (path, options) => {
-      let lastError;
-      for (let attempt = 0; attempt <= maxRetries; attempt++) {
-        try {
-          return await originalSend(path, options);
-        } catch (err) {
-          lastError = err;
-          const status = err?.status;
-          if (status === 503 && attempt < maxRetries) {
-            const delay = Math.pow(2, attempt + 1) * 1e3;
-            await new Promise((resolve) => setTimeout(resolve, delay));
-            continue;
-          }
-          if (status === 401) {
-            const data = err?.data;
-            if (data?.code === "INVALID_API_KEY") {
-              throw new AuthorizationError();
-            }
-          }
-          if (status === 404) {
-            const msg = err?.message ?? "";
-            if (msg.toLowerCase().includes("missing collection") || msg.toLowerCase().includes("not found collection")) {
-              const match = msg.match(/["']([^"']+)["']/);
-              throw new CollectionNotFoundError(match?.[1] ?? "unknown");
-            }
-          }
-          throw err;
-        }
-      }
-      throw new InstanceUnavailableError(
-        `Instance unavailable after ${maxRetries} retries. Original error: ${lastError instanceof Error ? lastError.message : String(lastError)}`
-      );
-    };
+    return this._authStore.isValid;
   }
 };
 function createClient(urlOrOptions, apiKeyOrUndefined, options) {