@picobase_app/client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,491 @@
+import PocketBase, { RecordModel, RecordSubscription, ListResult, SendOptions } from 'pocketbase';
+export { RecordModel } from 'pocketbase';
+
+interface PicoBaseClientOptions {
+    /**
+     * Timeout in ms for individual requests. Default: 30_000 (30s).
+     */
+    timeout?: number;
+    /**
+     * Max automatic retries on 503 (instance cold-starting). Default: 3.
+     */
+    maxColdStartRetries?: number;
+    /**
+     * Custom fetch implementation (useful for testing or server-side usage).
+     */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Language code sent as Accept-Language header. Default: 'en-US'.
+     */
+    lang?: string;
+}
+interface AuthResponse {
+    token: string;
+    record: RecordModel;
+}
+type AuthEvent = 'SIGNED_IN' | 'SIGNED_OUT' | 'TOKEN_REFRESHED';
+interface AuthStateChange {
+    event: AuthEvent;
+    token: string;
+    record: RecordModel | null;
+}
+type AuthStateChangeCallback = (event: AuthEvent, record: RecordModel | null) => void;
+interface SignUpOptions {
+    email: string;
+    password: string;
+    passwordConfirm?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+interface SignInOptions {
+    email: string;
+    password: string;
+}
+interface OAuthSignInOptions {
+    provider: string;
+    scopes?: string[];
+    createData?: Record<string, unknown>;
+    urlCallback?: (url: string) => void | Promise<void>;
+}
+type RealtimeAction = 'create' | 'update' | 'delete';
+interface RealtimeCallback<T = RecordModel> {
+    (data: RecordSubscription<T>): void;
+}
+type UnsubscribeFunc = () => Promise<void>;
+interface FileOptions {
+    thumb?: string;
+    token?: string;
+    download?: boolean;
+}
+
+/**
+ * Auth module — handles user sign-up, sign-in, OAuth, and session management.
+ *
+ * PicoBase uses PocketBase's built-in `users` collection for auth. Each
+ * instance has its own isolated user pool.
+ *
+ * @example
+ * ```ts
+ * // Sign up
+ * const { token, record } = await pb.auth.signUp({
+ *   email: 'user@example.com',
+ *   password: 'securepassword',
+ * })
+ *
+ * // Sign in
+ * const { token, record } = await pb.auth.signIn({
+ *   email: 'user@example.com',
+ *   password: 'securepassword',
+ * })
+ *
+ * // Listen to auth changes
+ * pb.auth.onStateChange((event, record) => {
+ *   console.log(event, record)
+ * })
+ * ```
+ */
+declare class PicoBaseAuth {
+    private pb;
+    private listeners;
+    private _collection;
+    constructor(pb: PocketBase);
+    /**
+     * Set which collection to authenticate against.
+     * Defaults to 'users'. Use this if you have a custom auth collection.
+     */
+    setCollection(name: string): this;
+    /**
+     * Create a new user account.
+     */
+    signUp(options: SignUpOptions): Promise<AuthResponse>;
+    /**
+     * Sign in with email and password.
+     */
+    signIn(options: SignInOptions): Promise<AuthResponse>;
+    /**
+     * 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.
+     */
+    signInWithOAuth(options: OAuthSignInOptions): Promise<AuthResponse>;
+    /**
+     * Refresh the current auth token.
+     */
+    refreshToken(): Promise<AuthResponse>;
+    /**
+     * Send a password reset email.
+     */
+    requestPasswordReset(email: string): Promise<void>;
+    /**
+     * Confirm a password reset with the token from the reset email.
+     */
+    confirmPasswordReset(token: string, password: string, passwordConfirm?: string): Promise<void>;
+    /**
+     * Send an email verification email.
+     */
+    requestVerification(email: string): Promise<void>;
+    /**
+     * Confirm email verification with the token from the verification email.
+     */
+    confirmVerification(token: string): Promise<void>;
+    /**
+     * Sign out the current user. Clears the local auth store.
+     */
+    signOut(): void;
+    /**
+     * Get the currently authenticated user record, or `null` if not signed in.
+     */
+    get user(): RecordModel | null;
+    /**
+     * Get the current auth token, or empty string if not signed in.
+     */
+    get token(): string;
+    /**
+     * Check if the current auth session is valid (token exists and not expired).
+     */
+    get isValid(): boolean;
+    /**
+     * 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: AuthStateChangeCallback): () => void;
+    private _notify;
+}
+
+/** Options for list queries. */
+interface ListOptions {
+    sort?: string;
+    filter?: string;
+    expand?: string;
+    fields?: string;
+    skipTotal?: boolean;
+    [key: string]: unknown;
+}
+/** Options for single record queries. */
+interface RecordQueryOptions {
+    expand?: string;
+    fields?: string;
+    [key: string]: unknown;
+}
+/**
+ * Collection module — CRUD operations on a PocketBase collection.
+ *
+ * @example
+ * ```ts
+ * const posts = pb.collection('posts')
+ *
+ * // List with filtering, sorting, and pagination
+ * const result = await posts.getList(1, 20, {
+ *   filter: 'published = true',
+ *   sort: '-created',
+ *   expand: 'author',
+ * })
+ *
+ * // Get a single record
+ * const post = await posts.getOne('record_id')
+ *
+ * // Create a record
+ * const newPost = await posts.create({
+ *   title: 'Hello World',
+ *   content: 'My first post',
+ * })
+ *
+ * // Update a record
+ * const updated = await posts.update('record_id', { title: 'Updated' })
+ *
+ * // Delete a record
+ * await posts.delete('record_id')
+ * ```
+ */
+declare class PicoBaseCollection<T = RecordModel> {
+    private pb;
+    private name;
+    constructor(pb: PocketBase, name: string);
+    /**
+     * 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.
+     */
+    getList(page?: number, perPage?: number, options?: ListOptions): Promise<ListResult<T>>;
+    /**
+     * Fetch all records matching the filter (auto-paginates).
+     *
+     * **Warning:** Use with caution on large collections. Prefer `getList()` with pagination.
+     */
+    getFullList(options?: ListOptions): Promise<T[]>;
+    /**
+     * Fetch a single record by ID.
+     */
+    getOne(id: string, options?: RecordQueryOptions): Promise<T>;
+    /**
+     * Fetch the first record matching a filter.
+     *
+     * @example
+     * ```ts
+     * const admin = await pb.collection('users').getFirstListItem('role = "admin"')
+     * ```
+     */
+    getFirstListItem(filter: string, options?: RecordQueryOptions): Promise<T>;
+    /**
+     * Create a new record.
+     *
+     * @param data - Record data. Can be a plain object or `FormData` (for file uploads).
+     */
+    create(data: Record<string, unknown> | FormData, options?: RecordQueryOptions): Promise<T>;
+    /**
+     * Update an existing record.
+     *
+     * @param id - Record ID.
+     * @param data - Fields to update. Can be a plain object or `FormData`.
+     */
+    update(id: string, data: Record<string, unknown> | FormData, options?: RecordQueryOptions): Promise<T>;
+    /**
+     * Delete a record by ID.
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * 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()
+     * ```
+     */
+    subscribe(callback: (data: {
+        action: string;
+        record: T;
+    }) => void, filter?: string): Promise<() => Promise<void>>;
+    /**
+     * Subscribe to changes on a specific record.
+     *
+     * @param id - Record ID.
+     * @param callback - Called on update/delete events.
+     * @returns Unsubscribe function.
+     */
+    subscribeOne(id: string, callback: (data: {
+        action: string;
+        record: T;
+    }) => void): Promise<() => Promise<void>>;
+}
+
+/**
+ * Realtime module — manage global realtime subscriptions.
+ *
+ * For collection-level subscriptions, prefer `pb.collection('name').subscribe()`.
+ * This module is for lower-level control over the SSE connection.
+ *
+ * @example
+ * ```ts
+ * // Subscribe to all changes on a collection
+ * const unsub = await pb.realtime.subscribe('posts', (e) => {
+ *   console.log(e.action, e.record)
+ * })
+ *
+ * // Unsubscribe
+ * await unsub()
+ *
+ * // Disconnect all realtime connections
+ * pb.realtime.disconnect()
+ * ```
+ */
+declare class PicoBaseRealtime {
+    private pb;
+    constructor(pb: PocketBase);
+    /**
+     * 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.
+     */
+    subscribe<T = RecordModel>(collection: string, callback: (data: RecordSubscription<T>) => void): Promise<() => Promise<void>>;
+    /**
+     * 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.
+     */
+    subscribeRecord<T = RecordModel>(collection: string, recordId: string, callback: (data: RecordSubscription<T>) => void): Promise<() => Promise<void>>;
+    /**
+     * Unsubscribe from all realtime events on a collection.
+     */
+    unsubscribe(collection: string): Promise<void>;
+    /**
+     * Unsubscribe from ALL realtime events. The SSE connection will be
+     * automatically closed when there are no remaining subscriptions.
+     */
+    disconnectAll(): Promise<void>;
+}
+
+/**
+ * Storage module — work with file fields on PocketBase records.
+ *
+ * PocketBase stores files as record fields. This module provides helpers
+ * to get file URLs and generate access tokens for protected files.
+ *
+ * @example
+ * ```ts
+ * const user = await pb.collection('users').getOne('user_id')
+ *
+ * // Get the URL for the user's avatar
+ * const avatarUrl = pb.storage.getFileUrl(user, 'avatar.jpg')
+ *
+ * // Get a thumbnail URL (100x100)
+ * const thumbUrl = pb.storage.getFileUrl(user, 'avatar.jpg', {
+ *   thumb: '100x100',
+ * })
+ *
+ * // Get a temporary token for protected files
+ * const token = await pb.storage.getFileToken()
+ * const protectedUrl = pb.storage.getFileUrl(user, 'document.pdf', { token })
+ * ```
+ */
+declare class PicoBaseStorage {
+    private pb;
+    constructor(pb: PocketBase);
+    /**
+     * 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: RecordModel, filename: string, options?: FileOptions): string;
+    /**
+     * Generate a temporary file access token.
+     *
+     * Use this for accessing protected files. Tokens are short-lived.
+     */
+    getFileToken(): Promise<string>;
+}
+
+declare class PicoBaseClient {
+    /** The underlying PocketBase SDK instance. Exposed for advanced usage. */
+    readonly pb: PocketBase;
+    /** Auth module — sign up, sign in, OAuth, session management. */
+    readonly auth: PicoBaseAuth;
+    /** Realtime module — subscribe to record changes. */
+    readonly realtime: PicoBaseRealtime;
+    /** Storage module — get file URLs and tokens. */
+    readonly storage: PicoBaseStorage;
+    private readonly apiKey;
+    private readonly options;
+    constructor(url: string, apiKey: string, options?: PicoBaseClientOptions);
+    /**
+     * Access a collection for CRUD operations.
+     *
+     * @example
+     * ```ts
+     * const posts = await pb.collection('posts').getList(1, 20)
+     * ```
+     */
+    collection<T = RecordModel>(name: string): PicoBaseCollection<T>;
+    /**
+     * Call a server-side function (PocketBase custom API endpoint).
+     * Proxies to PocketBase's send() method.
+     */
+    send<T = unknown>(path: string, options?: SendOptions): Promise<T>;
+    /**
+     * Get the current auth token (if signed in), or empty string.
+     */
+    get token(): string;
+    /**
+     * Check if a user is currently authenticated.
+     */
+    get isAuthenticated(): boolean;
+    /**
+     * 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.
+     */
+    private _wrapSendWithRetry;
+}
+/**
+ * Create a new PicoBase client.
+ *
+ * Can be called with explicit URL and API key, or with zero arguments to
+ * auto-detect from environment variables (`PICOBASE_URL` / `NEXT_PUBLIC_PICOBASE_URL`
+ * and `PICOBASE_API_KEY` / `NEXT_PUBLIC_PICOBASE_API_KEY`).
+ *
+ * @example
+ * ```ts
+ * import { createClient } from '@picobase_app/client'
+ *
+ * // Zero-config — reads from env vars
+ * const pb = createClient()
+ *
+ * // Or explicit
+ * const pb = createClient('https://myapp.picobase.com', 'pbk_abc123_secret')
+ *
+ * // Sign up a user
+ * const user = await pb.auth.signUp({
+ *   email: 'user@example.com',
+ *   password: 'securepassword',
+ * })
+ *
+ * // Query records
+ * const posts = await pb.collection('posts').getList(1, 20, {
+ *   filter: 'published = true',
+ *   sort: '-created',
+ * })
+ * ```
+ */
+declare function createClient(options?: PicoBaseClientOptions): PicoBaseClient;
+declare function createClient(url: string, apiKey: string, options?: PicoBaseClientOptions): PicoBaseClient;
+
+/**
+ * Base error class for all PicoBase SDK errors.
+ */
+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);
+}
+/**
+ * Thrown when the instance is not running and cold-start retries are exhausted.
+ */
+declare class InstanceUnavailableError extends PicoBaseError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when an API key is invalid or missing.
+ */
+declare class AuthorizationError extends PicoBaseError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when a PocketBase API request fails.
+ */
+declare class RequestError extends PicoBaseError {
+    constructor(message: 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 };