@picobase_app/client 0.1.0 → 0.1.2

package/README.md

@@ -145,6 +145,39 @@ const unsub = await pb.realtime.subscribe('posts', (event) => {
 await pb.realtime.disconnectAll()
 ```
 
+## RPC (Remote Procedure Calls)
+
+Call custom server-side functions using the `.rpc()` method. This is especially useful for Supabase migrations.
+
+```typescript
+// Simple RPC call
+const result = await pb.rpc('calculate_cart_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
+})
+// stats.posts, stats.comments, stats.followers are typed!
+
+// Common patterns
+await pb.rpc('increment_views', { post_id: '123' })
+const results = await pb.rpc('search_products', {
+  query: 'laptop',
+  min_price: 500,
+  category: 'electronics'
+})
+```
+
+RPC calls are mapped to custom PocketBase endpoints at `/api/rpc/{functionName}`. You'll need to implement these routes in your PocketBase instance. See the [PocketBase routing docs](https://pocketbase.io/docs/js-routing/) for details.
+
 ## File Storage
 
 PocketBase stores files as fields on records. Use the storage module to get URLs.
@@ -197,20 +230,54 @@ const pb = createClient('https://myapp.picobase.com', 'pbk_...', {
 
 ### Error handling
 
+Every SDK error includes a `code` and `fix` property with actionable suggestions:
+
 ```typescript
-import { PicoBaseError, InstanceUnavailableError, AuthorizationError } from '@picobase_app/client'
+import {
+  PicoBaseError,
+  AuthorizationError,
+  InstanceUnavailableError,
+  CollectionNotFoundError,
+  RecordNotFoundError,
+  ConfigurationError,
+  RpcError,
+} from '@picobase_app/client'
 
 try {
   await pb.collection('posts').getList()
 } catch (err) {
-  if (err instanceof AuthorizationError) {
-    // Invalid API key
-  } else if (err instanceof InstanceUnavailableError) {
-    // Instance not available after retries
+  if (err instanceof PicoBaseError) {
+    console.log(err.message)  // "Collection 'posts' not found."
+    console.log(err.code)     // "COLLECTION_NOT_FOUND"
+    console.log(err.fix)      // "Make sure the collection 'posts' exists..."
   }
 }
 ```
 
+**Error types:**
+
+| Error | Code | When |
+|---|---|---|
+| `ConfigurationError` | `CONFIGURATION_ERROR` | Missing URL, API key, or bad config |
+| `AuthorizationError` | `UNAUTHORIZED` | Invalid or missing API key |
+| `CollectionNotFoundError` | `COLLECTION_NOT_FOUND` | Collection doesn't exist |
+| `RecordNotFoundError` | `RECORD_NOT_FOUND` | Record ID not found |
+| `InstanceUnavailableError` | `INSTANCE_UNAVAILABLE` | Instance down after retries |
+| `RpcError` | `RPC_ERROR` | RPC function call failed (includes endpoint-specific fix hints) |
+| `RequestError` | `REQUEST_FAILED` | Generic HTTP error (includes status-specific fix hints) |
+
+### Typed collections with `picobase typegen`
+
+Run `picobase typegen` to generate types from your schema. The generated file includes a typed client:
+
+```typescript
+import { pb } from './src/types/picobase'
+
+// Collection names autocomplete, record fields are typed
+const result = await pb.collection('posts').getList(1, 20)
+result.items[0].title  // string — fully typed!
+```
+
 ## API Reference
 
 ### `createClient(url, apiKey, options?)`

package/dist/index.d.mts

@@ -410,6 +410,33 @@ declare class PicoBaseClient {
      * Proxies to PocketBase's send() method.
      */
     send<T = unknown>(path: string, options?: SendOptions): Promise<T>;
+    /**
+     * Call a remote procedure (RPC) - a convenience method for calling 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
+     *
+     * @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
+     */
+    rpc<T = unknown>(functionName: string, params?: Record<string, unknown>): Promise<T>;
     /**
      * Get the current auth token (if signed in), or empty string.
      */
@@ -462,12 +489,21 @@ declare function createClient(url: string, apiKey: string, options?: PicoBaseCli
 
 /**
  * Base error class for all PicoBase SDK errors.
+ *
+ * Every error includes a `code` for programmatic handling and a `fix`
+ * suggestion so developers can resolve issues without digging through docs.
  */
 declare class PicoBaseError extends Error {
     readonly code: string;
     readonly status?: number | undefined;
     readonly details?: unknown | undefined;
-    constructor(message: string, code: string, status?: number | undefined, details?: unknown | undefined);
+    /** Actionable suggestion for how to fix this error. */
+    readonly fix?: string | undefined;
+    constructor(message: string, code: string, status?: number | undefined, details?: unknown | undefined, 
+    /** Actionable suggestion for how to fix this error. */
+    fix?: string | undefined);
+    /** Formatted error string including fix suggestion. */
+    toString(): string;
 }
 /**
  * Thrown when the instance is not running and cold-start retries are exhausted.
@@ -481,11 +517,35 @@ declare class InstanceUnavailableError extends PicoBaseError {
 declare class AuthorizationError extends PicoBaseError {
     constructor(message?: string);
 }
+/**
+ * Thrown when a collection is not found.
+ */
+declare class CollectionNotFoundError extends PicoBaseError {
+    constructor(collectionName: string);
+}
+/**
+ * Thrown when a record is not found.
+ */
+declare class RecordNotFoundError extends PicoBaseError {
+    constructor(collectionName: string, recordId: string);
+}
 /**
  * Thrown when a PocketBase API request fails.
  */
 declare class RequestError extends PicoBaseError {
     constructor(message: string, status: number, details?: unknown);
 }
+/**
+ * Thrown when the SDK is misconfigured (bad URL, missing params, etc.).
+ */
+declare class ConfigurationError extends PicoBaseError {
+    constructor(message: string, fix: string);
+}
+/**
+ * Thrown when an RPC (remote procedure call) fails.
+ */
+declare class RpcError extends PicoBaseError {
+    constructor(functionName: string, status: number, details?: unknown);
+}
 
-export { type AuthEvent, type AuthResponse, type AuthStateChange, type AuthStateChangeCallback, AuthorizationError, type FileOptions, InstanceUnavailableError, type ListOptions, type OAuthSignInOptions, PicoBaseAuth, PicoBaseClient, type PicoBaseClientOptions, PicoBaseCollection, PicoBaseError, PicoBaseRealtime, PicoBaseStorage, type RealtimeAction, type RealtimeCallback, type RecordQueryOptions, RequestError, type SignInOptions, type SignUpOptions, type UnsubscribeFunc, createClient };
+export { type AuthEvent, type AuthResponse, type AuthStateChange, type AuthStateChangeCallback, AuthorizationError, CollectionNotFoundError, ConfigurationError, type FileOptions, InstanceUnavailableError, type ListOptions, type OAuthSignInOptions, PicoBaseAuth, PicoBaseClient, type PicoBaseClientOptions, PicoBaseCollection, PicoBaseError, PicoBaseRealtime, PicoBaseStorage, type RealtimeAction, type RealtimeCallback, RecordNotFoundError, type RecordQueryOptions, RequestError, RpcError, type SignInOptions, type SignUpOptions, type UnsubscribeFunc, createClient };

package/dist/index.d.ts

@@ -410,6 +410,33 @@ declare class PicoBaseClient {
      * Proxies to PocketBase's send() method.
      */
     send<T = unknown>(path: string, options?: SendOptions): Promise<T>;
+    /**
+     * Call a remote procedure (RPC) - a convenience method for calling 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
+     *
+     * @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
+     */
+    rpc<T = unknown>(functionName: string, params?: Record<string, unknown>): Promise<T>;
     /**
      * Get the current auth token (if signed in), or empty string.
      */
@@ -462,12 +489,21 @@ declare function createClient(url: string, apiKey: string, options?: PicoBaseCli
 
 /**
  * Base error class for all PicoBase SDK errors.
+ *
+ * Every error includes a `code` for programmatic handling and a `fix`
+ * suggestion so developers can resolve issues without digging through docs.
  */
 declare class PicoBaseError extends Error {
     readonly code: string;
     readonly status?: number | undefined;
     readonly details?: unknown | undefined;
-    constructor(message: string, code: string, status?: number | undefined, details?: unknown | undefined);
+    /** Actionable suggestion for how to fix this error. */
+    readonly fix?: string | undefined;
+    constructor(message: string, code: string, status?: number | undefined, details?: unknown | undefined, 
+    /** Actionable suggestion for how to fix this error. */
+    fix?: string | undefined);
+    /** Formatted error string including fix suggestion. */
+    toString(): string;
 }
 /**
  * Thrown when the instance is not running and cold-start retries are exhausted.
@@ -481,11 +517,35 @@ declare class InstanceUnavailableError extends PicoBaseError {
 declare class AuthorizationError extends PicoBaseError {
     constructor(message?: string);
 }
+/**
+ * Thrown when a collection is not found.
+ */
+declare class CollectionNotFoundError extends PicoBaseError {
+    constructor(collectionName: string);
+}
+/**
+ * Thrown when a record is not found.
+ */
+declare class RecordNotFoundError extends PicoBaseError {
+    constructor(collectionName: string, recordId: string);
+}
 /**
  * Thrown when a PocketBase API request fails.
  */
 declare class RequestError extends PicoBaseError {
     constructor(message: string, status: number, details?: unknown);
 }
+/**
+ * Thrown when the SDK is misconfigured (bad URL, missing params, etc.).
+ */
+declare class ConfigurationError extends PicoBaseError {
+    constructor(message: string, fix: string);
+}
+/**
+ * Thrown when an RPC (remote procedure call) fails.
+ */
+declare class RpcError extends PicoBaseError {
+    constructor(functionName: string, status: number, details?: unknown);
+}
 
-export { type AuthEvent, type AuthResponse, type AuthStateChange, type AuthStateChangeCallback, AuthorizationError, type FileOptions, InstanceUnavailableError, type ListOptions, type OAuthSignInOptions, PicoBaseAuth, PicoBaseClient, type PicoBaseClientOptions, PicoBaseCollection, PicoBaseError, PicoBaseRealtime, PicoBaseStorage, type RealtimeAction, type RealtimeCallback, type RecordQueryOptions, RequestError, type SignInOptions, type SignUpOptions, type UnsubscribeFunc, createClient };
+export { type AuthEvent, type AuthResponse, type AuthStateChange, type AuthStateChangeCallback, AuthorizationError, CollectionNotFoundError, ConfigurationError, type FileOptions, InstanceUnavailableError, type ListOptions, type OAuthSignInOptions, PicoBaseAuth, PicoBaseClient, type PicoBaseClientOptions, PicoBaseCollection, PicoBaseError, PicoBaseRealtime, PicoBaseStorage, type RealtimeAction, type RealtimeCallback, RecordNotFoundError, type RecordQueryOptions, RequestError, RpcError, type SignInOptions, type SignUpOptions, type UnsubscribeFunc, createClient };

package/dist/index.js

@@ -31,6 +31,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AuthorizationError: () => AuthorizationError,
+  CollectionNotFoundError: () => CollectionNotFoundError,
+  ConfigurationError: () => ConfigurationError,
   InstanceUnavailableError: () => InstanceUnavailableError,
   PicoBaseAuth: () => PicoBaseAuth,
   PicoBaseClient: () => PicoBaseClient,
@@ -38,7 +40,9 @@ __export(index_exports, {
   PicoBaseError: () => PicoBaseError,
   PicoBaseRealtime: () => PicoBaseRealtime,
   PicoBaseStorage: () => PicoBaseStorage,
+  RecordNotFoundError: () => RecordNotFoundError,
   RequestError: () => RequestError,
+  RpcError: () => RpcError,
   createClient: () => createClient
 });
 module.exports = __toCommonJS(index_exports);
@@ -380,32 +384,126 @@ var PicoBaseStorage = class {
 
 // src/errors.ts
 var PicoBaseError = class extends Error {
-  constructor(message, code, status, details) {
+  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);
+    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);
+    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) {
-    super(message, "REQUEST_FAILED", 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 = {
@@ -415,6 +513,24 @@ var DEFAULT_OPTIONS = {
 };
 var PicoBaseClient = class {
   constructor(url, apiKey, options = {}) {
+    if (!url) {
+      throw new ConfigurationError(
+        "PicoBase URL is required.",
+        'Pass the URL as the first argument: createClient("https://myapp.picobase.com", "pbk_...") or set PICOBASE_URL in your .env file.'
+      );
+    }
+    if (!apiKey) {
+      throw new ConfigurationError(
+        "PicoBase API key is required.",
+        'Pass the API key as the second argument: createClient("https://...", "pbk_your_key") or set PICOBASE_API_KEY in your .env file. Get a key from your dashboard.'
+      );
+    }
+    if (!url.startsWith("http://") && !url.startsWith("https://")) {
+      throw new ConfigurationError(
+        `Invalid URL: "${url}". Must start with http:// or https://.`,
+        `Use the full URL: createClient("https://${url}", "...")`
+      );
+    }
     this.apiKey = apiKey;
     this.options = { ...DEFAULT_OPTIONS, ...options };
     const baseUrl = url.replace(/\/+$/, "");
@@ -452,6 +568,44 @@ var PicoBaseClient = class {
   async send(path, options) {
     return this.pb.send(path, options ?? {});
   }
+  /**
+   * Call a remote procedure (RPC) - a convenience method for calling 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
+   *
+   * @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 {
+      return await this.send(`/api/rpc/${functionName}`, {
+        method: "POST",
+        body: params ?? {}
+      });
+    } catch (err) {
+      const status = err?.status ?? 500;
+      const details = err?.data;
+      throw new RpcError(functionName, status, details);
+    }
+  }
   /**
    * Get the current auth token (if signed in), or empty string.
    */
@@ -493,6 +647,13 @@ var PicoBaseClient = class {
               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;
         }
       }
@@ -508,8 +669,13 @@ function createClient(urlOrOptions, apiKeyOrUndefined, options) {
     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."
+      const missing = [
+        !url && "PICOBASE_URL (or NEXT_PUBLIC_PICOBASE_URL)",
+        !apiKey && "PICOBASE_API_KEY (or NEXT_PUBLIC_PICOBASE_API_KEY)"
+      ].filter(Boolean).join(" and ");
+      throw new ConfigurationError(
+        `Missing environment variable${!url && !apiKey ? "s" : ""}: ${missing}`,
+        "Add them to your .env.local file:\n\n  PICOBASE_URL=https://your-app.picobase.com\n  PICOBASE_API_KEY=pbk_your_key_here\n\nOr for Next.js (client-side access), prefix with NEXT_PUBLIC_:\n\n  NEXT_PUBLIC_PICOBASE_URL=https://your-app.picobase.com\n  NEXT_PUBLIC_PICOBASE_API_KEY=pbk_your_key_here\n\nGet your URL and API key from: https://picobase.com/dashboard\nOr run: picobase init"
       );
     }
     return new PicoBaseClient(url, apiKey, urlOrOptions);
@@ -519,6 +685,8 @@ function createClient(urlOrOptions, apiKeyOrUndefined, options) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthorizationError,
+  CollectionNotFoundError,
+  ConfigurationError,
   InstanceUnavailableError,
   PicoBaseAuth,
   PicoBaseClient,
@@ -526,6 +694,8 @@ function createClient(urlOrOptions, apiKeyOrUndefined, options) {
   PicoBaseError,
   PicoBaseRealtime,
   PicoBaseStorage,
+  RecordNotFoundError,
   RequestError,
+  RpcError,
   createClient
 });

package/dist/index.mjs

@@ -335,32 +335,126 @@ var PicoBaseStorage = class {
 
 // src/errors.ts
 var PicoBaseError = class extends Error {
-  constructor(message, code, status, details) {
+  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);
+    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);
+    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) {
-    super(message, "REQUEST_FAILED", 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 = {
@@ -370,6 +464,24 @@ var DEFAULT_OPTIONS = {
 };
 var PicoBaseClient = class {
   constructor(url, apiKey, options = {}) {
+    if (!url) {
+      throw new ConfigurationError(
+        "PicoBase URL is required.",
+        'Pass the URL as the first argument: createClient("https://myapp.picobase.com", "pbk_...") or set PICOBASE_URL in your .env file.'
+      );
+    }
+    if (!apiKey) {
+      throw new ConfigurationError(
+        "PicoBase API key is required.",
+        'Pass the API key as the second argument: createClient("https://...", "pbk_your_key") or set PICOBASE_API_KEY in your .env file. Get a key from your dashboard.'
+      );
+    }
+    if (!url.startsWith("http://") && !url.startsWith("https://")) {
+      throw new ConfigurationError(
+        `Invalid URL: "${url}". Must start with http:// or https://.`,
+        `Use the full URL: createClient("https://${url}", "...")`
+      );
+    }
     this.apiKey = apiKey;
     this.options = { ...DEFAULT_OPTIONS, ...options };
     const baseUrl = url.replace(/\/+$/, "");
@@ -407,6 +519,44 @@ var PicoBaseClient = class {
   async send(path, options) {
     return this.pb.send(path, options ?? {});
   }
+  /**
+   * Call a remote procedure (RPC) - a convenience method for calling 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
+   *
+   * @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 {
+      return await this.send(`/api/rpc/${functionName}`, {
+        method: "POST",
+        body: params ?? {}
+      });
+    } catch (err) {
+      const status = err?.status ?? 500;
+      const details = err?.data;
+      throw new RpcError(functionName, status, details);
+    }
+  }
   /**
    * Get the current auth token (if signed in), or empty string.
    */
@@ -448,6 +598,13 @@ var PicoBaseClient = class {
               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;
         }
       }
@@ -463,8 +620,13 @@ function createClient(urlOrOptions, apiKeyOrUndefined, options) {
     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."
+      const missing = [
+        !url && "PICOBASE_URL (or NEXT_PUBLIC_PICOBASE_URL)",
+        !apiKey && "PICOBASE_API_KEY (or NEXT_PUBLIC_PICOBASE_API_KEY)"
+      ].filter(Boolean).join(" and ");
+      throw new ConfigurationError(
+        `Missing environment variable${!url && !apiKey ? "s" : ""}: ${missing}`,
+        "Add them to your .env.local file:\n\n  PICOBASE_URL=https://your-app.picobase.com\n  PICOBASE_API_KEY=pbk_your_key_here\n\nOr for Next.js (client-side access), prefix with NEXT_PUBLIC_:\n\n  NEXT_PUBLIC_PICOBASE_URL=https://your-app.picobase.com\n  NEXT_PUBLIC_PICOBASE_API_KEY=pbk_your_key_here\n\nGet your URL and API key from: https://picobase.com/dashboard\nOr run: picobase init"
       );
     }
     return new PicoBaseClient(url, apiKey, urlOrOptions);
@@ -473,6 +635,8 @@ function createClient(urlOrOptions, apiKeyOrUndefined, options) {
 }
 export {
   AuthorizationError,
+  CollectionNotFoundError,
+  ConfigurationError,
   InstanceUnavailableError,
   PicoBaseAuth,
   PicoBaseClient,
@@ -480,6 +644,8 @@ export {
   PicoBaseError,
   PicoBaseRealtime,
   PicoBaseStorage,
+  RecordNotFoundError,
   RequestError,
+  RpcError,
   createClient
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picobase_app/client",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "PicoBase client SDK — auth, database, storage, and realtime for your apps",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -18,15 +18,25 @@
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:ui": "vitest --ui",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "publish:dry": "npm publish --dry-run",
+    "release:patch": "npm version patch && npm publish",
+    "release:minor": "npm version minor && npm publish",
+    "release:major": "npm version major && npm publish"
   },
   "dependencies": {
     "pocketbase": "^0.25.2"
   },
   "devDependencies": {
+    "@types/node": "^25.2.3",
+    "@vitest/ui": "^2.1.8",
     "tsup": "^8.4.0",
-    "typescript": "^5.7.3"
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
   },
   "keywords": [
     "picobase",