@picobase_app/client 0.5.2 → 1.0.2

package/dist/index.d.mts

@@ -1,5 +1,39 @@
-import PocketBase, { RecordModel, RecordSubscription, ListResult, SendOptions } from 'pocketbase';
-export { RecordModel } from 'pocketbase';
+/**
+ * Internal HTTP client for PicoBase SDK.
+ *
+ * Not exported. Used internally by all modules.
+ * Handles: URL building, header injection, timeout, error mapping, 503 retry.
+ */
+interface HttpSendOptions extends Omit<RequestInit, 'body'> {
+    /** Query parameters appended to the URL. */
+    query?: Record<string, unknown>;
+    /** Request body — plain object (serialized to JSON), FormData, or string. */
+    body?: Record<string, unknown> | FormData | string | null;
+}
+interface PicoBaseHttpClientOptions {
+    /** Timeout in ms for each request. Default: 30_000 */
+    timeout?: number;
+    /** Max retries on 503 (cold-start). Default: 3 */
+    maxColdStartRetries?: number;
+    /** Custom fetch implementation. */
+    fetch?: typeof globalThis.fetch;
+    /** Returns the current user JWT for Authorization header. */
+    getToken?: () => string;
+}
+/**
+ * Minimal fetch-based HTTP client.
+ * Injects X-PicoBase-Key and Authorization headers, handles cold-start retry.
+ */
+declare class PicoBaseHttpClient {
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly timeout;
+    private readonly maxColdStartRetries;
+    private readonly fetchImpl;
+    private readonly getToken?;
+    constructor(baseUrl: string, apiKey: string, options?: PicoBaseHttpClientOptions);
+    send<T>(path: string, init?: HttpSendOptions): Promise<T>;
+}
 
 interface PicoBaseClientOptions {
     /**
@@ -14,10 +48,28 @@ interface PicoBaseClientOptions {
      * 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 RecordModel {
+    id: string;
+    created: string;
+    updated: string;
+    collectionName?: string;
+    [key: string]: unknown;
+}
+interface ListResult<T = RecordModel> {
+    page: number;
+    perPage: number;
+    totalItems: number;
+    totalPages: number;
+    items: T[];
+}
+interface RecordSubscription<T = RecordModel> {
+    action: RealtimeAction;
+    record: T;
+}
+interface SendOptions extends Omit<RequestInit, 'body'> {
+    query?: Record<string, unknown>;
+    body?: Record<string, unknown> | FormData | string | null;
 }
 interface AuthResponse {
     token: string;
@@ -57,40 +109,62 @@ interface FileOptions {
     token?: string;
     download?: boolean;
 }
-type CollectionType = 'base' | 'auth' | 'view';
+/**
+ * Breaking change from v0: "base"|"auth"|"view" → "flexible"|"strict"
+ */
+type CollectionType = 'flexible' | 'strict';
+interface SchemaField {
+    name: string;
+    type: string;
+    required?: boolean;
+    default?: unknown;
+}
 interface CollectionModel {
     id: string;
     created: string;
     updated: string;
     name: string;
     type: CollectionType;
-    system: boolean;
     schema: SchemaField[];
-    indexes: string[];
-    listRule: string | null;
-    viewRule: string | null;
-    createRule: string | null;
-    updateRule: string | null;
-    deleteRule: string | null;
-    options: Record<string, unknown>;
 }
-interface SchemaField {
-    system: boolean;
-    id: string;
-    name: string;
-    type: string;
-    required: boolean;
-    presentable: boolean;
-    unique: boolean;
-    options: Record<string, unknown>;
+
+/**
+ * AuthStore — manages the end-user JWT and record in memory + localStorage.
+ *
+ * Not exported. Used by PicoBaseAuth and PicoBaseClient.
+ */
+
+type AuthChangeCallback = (token: string, record: RecordModel | null) => void;
+declare class AuthStore {
+    private _token;
+    private _record;
+    private _listeners;
+    constructor();
+    /** Current JWT, or empty string if not signed in. */
+    get token(): string;
+    /** Currently signed-in user record, or null. */
+    get record(): RecordModel | null;
+    /**
+     * Returns true if a token is present and not yet expired.
+     * Checks JWT `exp` claim — no signature verification (the server does that).
+     */
+    get isValid(): boolean;
+    /** Save a token (and optionally the user record). Persists to localStorage. */
+    save(token: string, record?: RecordModel | null): void;
+    /** Clear the token and user record. Removes from localStorage. */
+    clear(): void;
+    /**
+     * Register a listener for auth state changes.
+     * @returns Unsubscribe function.
+     */
+    onChange(callback: AuthChangeCallback): () => void;
+    private _loadFromStorage;
+    private _notify;
 }
 
 /**
  * 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
@@ -112,17 +186,18 @@ interface SchemaField {
  * ```
  */
 declare class PicoBaseAuth {
-    private pb;
+    private http;
+    private authStore;
     private listeners;
     private _collection;
-    constructor(pb: PocketBase);
+    constructor(http: PicoBaseHttpClient, authStore: AuthStore);
     /**
      * 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: string): this;
     /**
-     * Create a new user account.
+     * Create a new user account. Automatically signs the user in after creation.
      */
     signUp(options: SignUpOptions): Promise<AuthResponse>;
     /**
@@ -131,9 +206,6 @@ declare class PicoBaseAuth {
     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>;
     /**
@@ -178,9 +250,7 @@ declare class PicoBaseAuth {
      * @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:
@@ -191,6 +261,71 @@ declare class PicoBaseAuth {
     private _notify;
 }
 
+/**
+ * Realtime module — subscribe to record changes via Server-Sent Events (SSE).
+ *
+ * For collection-level subscriptions, prefer `pb.collection('name').subscribe()`.
+ * This module is for lower-level control.
+ *
+ * @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
+ * await pb.realtime.disconnectAll()
+ * ```
+ */
+declare class PicoBaseRealtime {
+    private baseUrl;
+    private apiKey;
+    private getToken;
+    private eventSource;
+    private subs;
+    private counter;
+    constructor(baseUrl: string, apiKey: string, getToken: () => string);
+    /**
+     * 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 and close the SSE connection.
+     */
+    disconnectAll(): Promise<void>;
+    private _addSub;
+    private _removeSub;
+    private _pruneIfEmpty;
+    /**
+     * Open SSE connection to `/api/db/realtime`.
+     * No-ops in environments where EventSource is unavailable (SSR / Node).
+     */
+    private _ensureConnection;
+    private _closeConnection;
+    private _dispatch;
+}
+
 /** Options for list queries. */
 interface ListOptions {
     sort?: string;
@@ -207,7 +342,7 @@ interface RecordQueryOptions {
     [key: string]: unknown;
 }
 /**
- * Collection module — CRUD operations on a PocketBase collection.
+ * Collection module — CRUD operations on a PicoBase collection.
  *
  * @example
  * ```ts
@@ -224,10 +359,7 @@ interface RecordQueryOptions {
  * const post = await posts.getOne('record_id')
  *
  * // Create a record
- * const newPost = await posts.create({
- *   title: 'Hello World',
- *   content: 'My first post',
- * })
+ * const newPost = await posts.create({ title: 'Hello World', content: 'My first post' })
  *
  * // Update a record
  * const updated = await posts.update('record_id', { title: 'Updated' })
@@ -237,9 +369,10 @@ interface RecordQueryOptions {
  * ```
  */
 declare class PicoBaseCollection<T = RecordModel> {
-    private pb;
+    private http;
     private name;
-    constructor(pb: PocketBase, name: string);
+    private rt;
+    constructor(http: PicoBaseHttpClient, name: string, realtime: PicoBaseRealtime);
     /**
      * Fetch a paginated list of records.
      *
@@ -288,7 +421,7 @@ declare class PicoBaseCollection<T = RecordModel> {
      * 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
@@ -319,61 +452,9 @@ declare class PicoBaseCollection<T = RecordModel> {
 }
 
 /**
- * Realtime module — manage global realtime subscriptions.
+ * Storage module — work with file fields on PicoBase records.
  *
- * 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.
+ * Files are served from `/api/db/files/:collection/:recordId/:filename`.
  *
  * @example
  * ```ts
@@ -383,9 +464,7 @@ declare class PicoBaseRealtime {
  * const avatarUrl = pb.storage.getFileUrl(user, 'avatar.jpg')
  *
  * // Get a thumbnail URL (100x100)
- * const thumbUrl = pb.storage.getFileUrl(user, 'avatar.jpg', {
- *   thumb: '100x100',
- * })
+ * const thumbUrl = pb.storage.getFileUrl(user, 'avatar.jpg', { thumb: '100x100' })
  *
  * // Get a temporary token for protected files
  * const token = await pb.storage.getFileToken()
@@ -393,27 +472,33 @@ declare class PicoBaseRealtime {
  * ```
  */
 declare class PicoBaseStorage {
-    private pb;
-    constructor(pb: PocketBase);
+    private http;
+    private baseUrl;
+    constructor(baseUrl: string, http: PicoBaseHttpClient);
     /**
-     * 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: RecordModel, filename: string, options?: FileOptions): string;
     /**
-     * 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.
      */
     getFileToken(): Promise<string>;
 }
 
+/**
+ * Admin module — programmatic collection management.
+ * Requires an admin API key.
+ *
+ * Breaking change from v0: `type` is now `"flexible" | "strict"` instead of `"base" | "auth" | "view"`.
+ */
 declare class PicoBaseAdmin {
-    private pb;
-    constructor(pb: PocketBase);
+    private http;
+    constructor(http: PicoBaseHttpClient);
     /**
      * Fetch a list of all collections.
      */
@@ -424,6 +509,8 @@ declare class PicoBaseAdmin {
     getCollection(idOrName: string): Promise<CollectionModel>;
     /**
      * Create a new collection.
+     *
+     * @param data.type - `"flexible"` (JSONB, schema-free) or `"strict"` (typed SQL columns).
      */
     createCollection(data: Partial<CollectionModel>): Promise<CollectionModel>;
     /**
@@ -437,8 +524,6 @@ declare class PicoBaseAdmin {
 }
 
 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. */
@@ -447,8 +532,12 @@ declare class PicoBaseClient {
     readonly storage: PicoBaseStorage;
     /** Admin module — manage collections (requires admin API key). */
     readonly admin: PicoBaseAdmin;
-    private readonly apiKey;
-    private readonly options;
+    /** Internal HTTP client. */
+    private readonly _http;
+    /** Internal auth store. */
+    private readonly _authStore;
+    /** Normalized base URL (no trailing slash). */
+    readonly baseUrl: string;
     constructor(url: string, apiKey: string, options?: PicoBaseClientOptions);
     /**
      * Access a collection for CRUD operations.
@@ -460,52 +549,25 @@ declare class PicoBaseClient {
      */
     collection<T = RecordModel>(name: string): PicoBaseCollection<T>;
     /**
-     * Call a server-side function (PocketBase custom API endpoint).
-     * Proxies to PocketBase's send() method.
+     * Send a raw HTTP request to the PicoBase API.
      */
     send<T = unknown>(path: string, options?: SendOptions): Promise<T>;
     /**
-     * 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
      */
     rpc<T = unknown>(functionName: string, params?: Record<string, unknown>): Promise<T>;
     /**
-     * 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.
+     * Proactively warm up the Neon connection after scale-to-zero.
      *
-     * 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)
-     * }, [])
-     * ```
+     * Useful to call when a user navigates to a login page or before critical
+     * operations, to absorb cold-start latency upfront.
      */
     wake(): Promise<boolean>;
     /**
@@ -516,14 +578,6 @@ declare class PicoBaseClient {
      * 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.
@@ -541,18 +595,6 @@ declare class PicoBaseClient {
  *
  * // 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;
@@ -619,4 +661,4 @@ declare class RpcError extends PicoBaseError {
     constructor(functionName: string, status: number, details?: unknown);
 }
 
-export { type AuthEvent, type AuthResponse, type AuthStateChange, type AuthStateChangeCallback, AuthorizationError, CollectionNotFoundError, ConfigurationError, type FileOptions, InstanceUnavailableError, type ListOptions, type OAuthSignInOptions, PicoBaseAdmin, PicoBaseAuth, PicoBaseClient, type PicoBaseClientOptions, PicoBaseCollection, PicoBaseError, PicoBaseRealtime, PicoBaseStorage, type RealtimeAction, type RealtimeCallback, RecordNotFoundError, type RecordQueryOptions, RequestError, RpcError, type SignInOptions, type SignUpOptions, type UnsubscribeFunc, createClient };
+export { type AuthEvent, type AuthResponse, type AuthStateChange, type AuthStateChangeCallback, AuthorizationError, type CollectionModel, CollectionNotFoundError, type CollectionType, ConfigurationError, type FileOptions, InstanceUnavailableError, type ListOptions, type ListResult, type OAuthSignInOptions, PicoBaseAdmin, PicoBaseAuth, PicoBaseClient, type PicoBaseClientOptions, PicoBaseCollection, PicoBaseError, PicoBaseRealtime, PicoBaseStorage, type RealtimeAction, type RealtimeCallback, type RecordModel, RecordNotFoundError, type RecordQueryOptions, type RecordSubscription, RequestError, RpcError, type SchemaField, type SendOptions, type SignInOptions, type SignUpOptions, type UnsubscribeFunc, createClient };