@picobase_app/client 0.1.0 → 0.2.0

package/README.md

@@ -8,6 +8,8 @@ TypeScript SDK for PicoBase — add auth, database, realtime, and file storage t
 npm install @picobase_app/client
 ```
 
+> ⚠️ **Important:** Install `@picobase_app/client`, **NOT** `pocketbase` directly. PicoBase wraps PocketBase with managed hosting features. If you accidentally installed `pocketbase`, remove it from your dependencies.
+
 ## Quickstart
 
 ```typescript
@@ -145,6 +147,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 +232,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 };