@picobase_app/client 0.1.0

package/dist/index.js

@@ -0,0 +1,531 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthorizationError: () => AuthorizationError,
+  InstanceUnavailableError: () => InstanceUnavailableError,
+  PicoBaseAuth: () => PicoBaseAuth,
+  PicoBaseClient: () => PicoBaseClient,
+  PicoBaseCollection: () => PicoBaseCollection,
+  PicoBaseError: () => PicoBaseError,
+  PicoBaseRealtime: () => PicoBaseRealtime,
+  PicoBaseStorage: () => PicoBaseStorage,
+  RequestError: () => RequestError,
+  createClient: () => createClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_pocketbase = __toESM(require("pocketbase"));
+
+// src/auth.ts
+var PicoBaseAuth = class {
+  constructor(pb) {
+    this.listeners = /* @__PURE__ */ new Set();
+    this._collection = "users";
+    this.pb = pb;
+    this.pb.authStore.onChange((token) => {
+      const record = this.pb.authStore.record ?? null;
+      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.
+   */
+  setCollection(name) {
+    this._collection = name;
+    return this;
+  }
+  /**
+   * Create a new user account.
+   */
+  async signUp(options) {
+    const { email, password, passwordConfirm, ...rest } = options;
+    const record = await this.pb.collection(this._collection).create({
+      email,
+      password,
+      passwordConfirm: passwordConfirm ?? password,
+      ...rest
+    });
+    const authResult = await this.pb.collection(this._collection).authWithPassword(email, password);
+    return {
+      token: authResult.token,
+      record: authResult.record
+    };
+  }
+  /**
+   * 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
+    };
+  }
+  /**
+   * 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
+    };
+  }
+  /**
+   * Refresh the current auth token.
+   */
+  async refreshToken() {
+    const result = await this.pb.collection(this._collection).authRefresh();
+    this._notify("TOKEN_REFRESHED", 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);
+  }
+  /**
+   * 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);
+  }
+  /**
+   * Send an email verification email.
+   */
+  async requestVerification(email) {
+    await this.pb.collection(this._collection).requestVerification(email);
+  }
+  /**
+   * Confirm email verification with the token from the verification email.
+   */
+  async confirmVerification(token) {
+    await this.pb.collection(this._collection).confirmVerification(token);
+  }
+  /**
+   * Sign out the current user. Clears the local auth store.
+   */
+  signOut() {
+    this.pb.authStore.clear();
+  }
+  /**
+   * Get the currently authenticated user record, or `null` if not signed in.
+   */
+  get user() {
+    return this.pb.authStore.record;
+  }
+  /**
+   * Get the current auth token, or empty string if not signed in.
+   */
+  get token() {
+    return this.pb.authStore.token;
+  }
+  /**
+   * Check if the current auth session is valid (token exists and not expired).
+   */
+  get isValid() {
+    return this.pb.authStore.isValid;
+  }
+  /**
+   * Listen to auth state changes. Returns an unsubscribe function.
+   *
+   * @example
+   * ```ts
+   * const unsubscribe = pb.auth.onStateChange((event, record) => {
+   *   if (event === 'SIGNED_IN') {
+   *     console.log('Welcome', record.email)
+   *   }
+   * })
+   *
+   * // Later:
+   * unsubscribe()
+   * ```
+   */
+  onStateChange(callback) {
+    this.listeners.add(callback);
+    return () => {
+      this.listeners.delete(callback);
+    };
+  }
+  _notify(event, record) {
+    for (const cb of this.listeners) {
+      try {
+        cb(event, record);
+      } catch {
+      }
+    }
+  }
+};
+
+// src/collection.ts
+var PicoBaseCollection = class {
+  constructor(pb, name) {
+    this.pb = pb;
+    this.name = name;
+  }
+  /**
+   * Fetch a paginated list of records.
+   *
+   * @param page - Page number (1-indexed). Default: 1.
+   * @param perPage - Records per page. Default: 30.
+   * @param options - Filter, sort, expand, fields.
+   */
+  async getList(page = 1, perPage = 30, options = {}) {
+    return this.pb.collection(this.name).getList(page, perPage, options);
+  }
+  /**
+   * Fetch all records matching the filter (auto-paginates).
+   *
+   * **Warning:** Use with caution on large collections. Prefer `getList()` with pagination.
+   */
+  async getFullList(options = {}) {
+    return this.pb.collection(this.name).getFullList(options);
+  }
+  /**
+   * Fetch a single record by ID.
+   */
+  async getOne(id, options = {}) {
+    return this.pb.collection(this.name).getOne(id, options);
+  }
+  /**
+   * Fetch the first record matching a filter.
+   *
+   * @example
+   * ```ts
+   * const admin = await pb.collection('users').getFirstListItem('role = "admin"')
+   * ```
+   */
+  async getFirstListItem(filter, options = {}) {
+    return this.pb.collection(this.name).getFirstListItem(filter, options);
+  }
+  /**
+   * Create a new record.
+   *
+   * @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);
+  }
+  /**
+   * Update an existing record.
+   *
+   * @param id - Record ID.
+   * @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);
+  }
+  /**
+   * Delete a record by ID.
+   */
+  async delete(id) {
+    return this.pb.collection(this.name).delete(id);
+  }
+  /**
+   * 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.
+   * @returns Unsubscribe function.
+   *
+   * @example
+   * ```ts
+   * const unsubscribe = await pb.collection('posts').subscribe((e) => {
+   *   console.log(e.action, e.record)
+   * })
+   *
+   * // Later:
+   * await unsubscribe()
+   * ```
+   */
+  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);
+  }
+  /**
+   * Subscribe to changes on a specific record.
+   *
+   * @param id - Record ID.
+   * @param callback - Called on update/delete events.
+   * @returns Unsubscribe function.
+   */
+  async subscribeOne(id, callback) {
+    await this.pb.collection(this.name).subscribe(id, callback);
+    return () => this.pb.collection(this.name).unsubscribe(id);
+  }
+};
+
+// src/realtime.ts
+var PicoBaseRealtime = class {
+  constructor(pb) {
+    this.pb = pb;
+  }
+  /**
+   * Subscribe to realtime events on a collection.
+   *
+   * @param collection - Collection name (e.g. 'posts').
+   * @param callback - Called on every create/update/delete event.
+   * @returns Unsubscribe function.
+   */
+  async subscribe(collection, callback) {
+    await this.pb.collection(collection).subscribe("*", callback);
+    return () => this.pb.collection(collection).unsubscribe("*");
+  }
+  /**
+   * Subscribe to realtime events on a specific record.
+   *
+   * @param collection - Collection name.
+   * @param recordId - Record ID.
+   * @param callback - Called on update/delete events.
+   * @returns Unsubscribe function.
+   */
+  async subscribeRecord(collection, recordId, callback) {
+    await this.pb.collection(collection).subscribe(recordId, callback);
+    return () => this.pb.collection(collection).unsubscribe(recordId);
+  }
+  /**
+   * Unsubscribe from all realtime events on a collection.
+   */
+  async unsubscribe(collection) {
+    await this.pb.collection(collection).unsubscribe();
+  }
+  /**
+   * Unsubscribe from ALL realtime events. The SSE connection will be
+   * automatically closed when there are no remaining subscriptions.
+   */
+  async disconnectAll() {
+    await this.pb.realtime.unsubscribe();
+  }
+};
+
+// src/storage.ts
+var PicoBaseStorage = class {
+  constructor(pb) {
+    this.pb = pb;
+  }
+  /**
+   * Get the public URL for a file attached to a record.
+   *
+   * @param record - The record that owns the file.
+   * @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);
+  }
+  /**
+   * Generate a temporary file access token.
+   *
+   * Use this for accessing protected files. Tokens are short-lived.
+   */
+  async getFileToken() {
+    return this.pb.files.getToken();
+  }
+};
+
+// src/errors.ts
+var PicoBaseError = class extends Error {
+  constructor(message, code, status, details) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    this.name = "PicoBaseError";
+  }
+};
+var InstanceUnavailableError = class extends PicoBaseError {
+  constructor(message = "Instance is not available. It may be stopped or starting up.") {
+    super(message, "INSTANCE_UNAVAILABLE", 503);
+    this.name = "InstanceUnavailableError";
+  }
+};
+var AuthorizationError = class extends PicoBaseError {
+  constructor(message = "Invalid or missing API key.") {
+    super(message, "UNAUTHORIZED", 401);
+    this.name = "AuthorizationError";
+  }
+};
+var RequestError = class extends PicoBaseError {
+  constructor(message, status, details) {
+    super(message, "REQUEST_FAILED", status, details);
+    this.name = "RequestError";
+  }
+};
+
+// src/client.ts
+var DEFAULT_OPTIONS = {
+  timeout: 3e4,
+  maxColdStartRetries: 3,
+  lang: "en-US"
+};
+var PicoBaseClient = class {
+  constructor(url, apiKey, options = {}) {
+    this.apiKey = apiKey;
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+    const baseUrl = url.replace(/\/+$/, "");
+    this.pb = new import_pocketbase.default(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);
+  }
+  /**
+   * Access a collection for CRUD operations.
+   *
+   * @example
+   * ```ts
+   * const posts = await pb.collection('posts').getList(1, 20)
+   * ```
+   */
+  collection(name) {
+    return new PicoBaseCollection(this.pb, name);
+  }
+  /**
+   * Call a server-side function (PocketBase custom API endpoint).
+   * Proxies to PocketBase's send() method.
+   */
+  async send(path, options) {
+    return this.pb.send(path, options ?? {});
+  }
+  /**
+   * Get the current auth token (if signed in), or empty string.
+   */
+  get token() {
+    return this.pb.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();
+            }
+          }
+          throw err;
+        }
+      }
+      throw new InstanceUnavailableError(
+        `Instance unavailable after ${maxRetries} retries. Original error: ${lastError instanceof Error ? lastError.message : String(lastError)}`
+      );
+    };
+  }
+};
+function createClient(urlOrOptions, apiKeyOrUndefined, options) {
+  if (typeof urlOrOptions !== "string") {
+    const env = typeof process !== "undefined" ? process.env : {};
+    const url = env.PICOBASE_URL || env.NEXT_PUBLIC_PICOBASE_URL;
+    const apiKey = env.PICOBASE_API_KEY || env.NEXT_PUBLIC_PICOBASE_API_KEY;
+    if (!url || !apiKey) {
+      throw new Error(
+        "createClient() called without arguments, but PICOBASE_URL and PICOBASE_API_KEY environment variables are not set. Either pass them explicitly or add them to your .env file."
+      );
+    }
+    return new PicoBaseClient(url, apiKey, urlOrOptions);
+  }
+  return new PicoBaseClient(urlOrOptions, apiKeyOrUndefined, options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthorizationError,
+  InstanceUnavailableError,
+  PicoBaseAuth,
+  PicoBaseClient,
+  PicoBaseCollection,
+  PicoBaseError,
+  PicoBaseRealtime,
+  PicoBaseStorage,
+  RequestError,
+  createClient
+});