lazypock 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,520 @@
+/** Shape of a record returned from any collection. */
+interface ApiRecord {
+    id: string;
+    collectionId: string;
+    collectionName: string;
+    created: string;
+    updated: string;
+    [key: string]: unknown;
+}
+/** Paginated list response matching PocketBase format. */
+interface ListResult<T = ApiRecord> {
+    items: T[];
+    page: number;
+    perPage: number;
+    totalItems: number;
+    totalPages: number;
+}
+/** HTTP method supported by the client. */
+type Method = "GET" | "POST" | "PATCH" | "DELETE";
+interface RequestOptions {
+    /** Search/filter params */
+    params?: Record<string, string>;
+    /** Raw request headers to merge */
+    headers?: Record<string, string>;
+    /** Abort signal */
+    signal?: AbortSignal;
+    /** Custom fetch implementation (for RN or test mocking) */
+    fetch?: typeof globalThis.fetch;
+}
+declare class ApiError extends Error {
+    readonly data: unknown;
+    readonly status: number;
+    constructor(message: string, data: unknown, status: number);
+}
+
+/**
+ * Interface for pluggable persistence backends.
+ * Swap for `AsyncStorage` on React Native, `localStorage` on web, etc.
+ */
+interface StorageAdapter {
+    /** Retrieve a stored value by key. */
+    get(key: string): string | null | Promise<string | null>;
+    /** Persist a key-value pair. */
+    set(key: string, value: string): void | Promise<void>;
+    /** Remove a stored value by key. */
+    remove(key: string): void | Promise<void>;
+}
+/** Shape of an authenticated user record (from auth collections). */
+interface AuthModel {
+    id: string;
+    [key: string]: unknown;
+}
+/** Callback signature for auth state changes. */
+type AuthListener = (model: AuthModel | null, token: string) => void;
+declare class AuthStore {
+    private _token;
+    private _model;
+    private _tokenExpiresAt;
+    private _collectionName;
+    private listeners;
+    private storage;
+    /**
+     * Create an AuthStore with optional custom storage adapter.
+     * @param storage Persistence backend. Defaults to `memoryStorage` (localStorage fallback).
+     */
+    constructor(storage?: StorageAdapter);
+    /** The current JWT token string, or empty string if not authenticated. */
+    get token(): string;
+    /** The current authenticated user record, or null. */
+    get model(): AuthModel | null;
+    /** Whether a token exists (does not check expiry). */
+    get isValid(): boolean;
+    /**
+     * Whether the current token has expired (with a 30-second buffer).
+     * Returns false when no expiry has been recorded (e.g. superuser tokens).
+     */
+    get isExpired(): boolean;
+    /** The auth collection name used for automatic token refresh. */
+    get collectionName(): string | null;
+    /**
+     * Set the auth collection name (used internally by auto-refresh).
+     * @param name The collection name, or null for superuser tokens.
+     */
+    setCollectionName(name: string | null): void;
+    /**
+     * Load persisted auth state from storage.
+     * Should be called once at application startup.
+     */
+    init(): Promise<void>;
+    /**
+     * Update the current auth token and model, persist to storage, and notify listeners.
+     * @param token The JWT token string.
+     * @param model The authenticated user record, or null for superusers.
+     */
+    set(token: string, model: AuthModel | null): void;
+    /**
+     * Clear all auth state (token, model, expiry) and notify listeners.
+     */
+    clear(): void;
+    /**
+     * Register a listener for auth state changes.
+     * @param fn Callback invoked with (model, token) on every change.
+     * @returns An unsubscribe function.
+     */
+    onChange(fn: AuthListener): () => void;
+    private notify;
+}
+
+/**
+ * Low-level HTTP client wrapping `fetch` with automatic auth token injection.
+ * Only relies on `globalThis.fetch` — works in browser, React Native, and Node 18+.
+ */
+declare class HttpClient {
+    private baseUrl;
+    private authStore;
+    private defaultFetch;
+    /**
+     * @param baseUrl The API base URL (e.g. `http://localhost:4000/api`). Trailing slash stripped.
+     * @param authStore The auth store providing the token for Authorization headers.
+     */
+    constructor(baseUrl: string, authStore: AuthStore);
+    private refreshAuth;
+    /**
+     * Make an HTTP request with automatic auth token injection and optional auto-refresh.
+     *
+     * @param method HTTP method.
+     * @param path URL path (appended to baseUrl).
+     * @param body JSON-serializable body, or FormData for file uploads.
+     * @param options Optional request options.
+     * @returns Parsed JSON response, or null for 204 No Content.
+     * @throws {ApiError} On non-2xx responses.
+     */
+    request<T = unknown>(method: Method, path: string, body?: unknown, options?: RequestOptions): Promise<T | null>;
+    /**
+     * HTTP GET.
+     * @param path URL path.
+     * @param options Optional request options.
+     */
+    get<T = unknown>(path: string, options?: RequestOptions): Promise<T | null>;
+    /**
+     * HTTP POST.
+     * @param path URL path.
+     * @param body Optional request body.
+     * @param options Optional request options.
+     */
+    post<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T | null>;
+    /**
+     * HTTP PATCH.
+     * @param path URL path.
+     * @param body Optional request body.
+     * @param options Optional request options.
+     */
+    patch<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T | null>;
+    /**
+     * HTTP DELETE.
+     * @param path URL path.
+     * @param options Optional request options.
+     */
+    delete<T = unknown>(path: string, options?: RequestOptions): Promise<T | null>;
+}
+
+/**
+ * Typed CRUD service for a single dynamic collection.
+ * Get an instance via {@link LazypockClient.collection}.
+ */
+declare class CollectionService {
+    private http;
+    private collectionName;
+    private authStore?;
+    /** @internal */
+    constructor(http: HttpClient, collectionName: string, authStore?: AuthStore);
+    private encodeId;
+    /**
+     * List records with optional filter/sort/pagination.
+     * @param params Query parameters including `filter`, `sort`, `page`, `perPage`, `expand`.
+     * @param options Optional request options.
+     */
+    list<T = ApiRecord>(params?: Record<string, string>, options?: RequestOptions): Promise<ListResult<T> | null>;
+    /**
+     * Get a single record by ID.
+     * @param id Record ID.
+     * @param options Optional request options.
+     */
+    getOne<T = ApiRecord>(id: string, options?: RequestOptions): Promise<T | null>;
+    /**
+     * Create a new record.
+     * @param data Record fields.
+     * @param options Optional request options.
+     */
+    create<T = ApiRecord>(data: Record<string, unknown>, options?: RequestOptions): Promise<T | null>;
+    /**
+     * Update a record by ID.
+     * @param id Record ID.
+     * @param data Updated record fields.
+     * @param options Optional request options.
+     */
+    update<T = ApiRecord>(id: string, data: Record<string, unknown>, options?: RequestOptions): Promise<T | null>;
+    /**
+     * Delete a record by ID.
+     * @param id Record ID.
+     * @param options Optional request options.
+     */
+    delete(id: string, options?: RequestOptions): Promise<null>;
+    /**
+     * Get a list of expandable (relation) fields for this collection.
+     * Useful for constructing `expand` query parameters.
+     */
+    expandFields(options?: RequestOptions): Promise<{
+        field: string;
+        targetCollection: string;
+    }[] | null>;
+    /**
+     * Authenticate with email/password against this auth collection.
+     * Stores the returned token and user model in the auth store.
+     */
+    authWithPassword(identity: string, password: string, options?: RequestOptions): Promise<({
+        token: string;
+        record: ApiRecord;
+    } & Record<string, unknown>) | null>;
+    /**
+     * Refresh the auth token for the currently authenticated user.
+     * Updates the stored token and user model.
+     */
+    authRefresh(options?: RequestOptions): Promise<({
+        token: string;
+        record: ApiRecord;
+    } & Record<string, unknown>) | null>;
+    /**
+     * Get available auth methods for this collection.
+     */
+    authMethods(options?: RequestOptions): Promise<Record<string, unknown> | null>;
+}
+
+interface RealtimeEvent {
+    event: string;
+    topic: string;
+    payload: Record<string, unknown>;
+}
+type RealtimeConnectOpts = {
+    /** WebSocket URL (e.g. ws://localhost:4000/socket/websocket) */
+    url: string;
+    /** Auth token to pass as query param */
+    token?: string;
+};
+/**
+ * Derive a WebSocket URL from an HTTP base URL.
+ * http://localhost:4000/api → ws://localhost:4000/socket/websocket
+ */
+declare function wsUrlFromBaseUrl(baseUrl: string): string;
+/**
+ * Phoenix Channel client for real-time collection subscriptions.
+ *
+ * Connects via WebSocket and subscribes to collection topics.
+ * Includes automatic reconnection with exponential backoff.
+ *
+ * @example
+ * ```ts
+ * const rt = new RealtimeService();
+ * rt.connect({ url: wsUrlFromBaseUrl('http://localhost:4000/api') });
+ * rt.subscribe('collection:posts', (e) => console.log(e));
+ * ```
+ */
+declare class RealtimeService {
+    private ws;
+    private refCounter;
+    private subscriptions;
+    private reconnectTimer;
+    private reconnectAttempt;
+    private maxReconnectDelay;
+    onReconnect?: () => void;
+    onDisconnect?: () => void;
+    onError?: (err: Event) => void;
+    private url;
+    private token;
+    connect(opts: RealtimeConnectOpts): void;
+    disconnect(): void;
+    /**
+     * Subscribe to a topic (e.g. "collection:posts" or "collection:posts:*").
+     * The backend Channel authorizes via listRule on join.
+     */
+    subscribe(topic: string, callback: (e: RealtimeEvent) => void): void;
+    /**
+     * Unsubscribe a specific callback from a topic.
+     */
+    unsubscribe(topic: string, callback?: (e: RealtimeEvent) => void): void;
+    private resubscribeAll;
+    private doConnect;
+    private handleMessage;
+    private joinTopic;
+    private nextRef;
+    private heartbeatInterval;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+}
+
+/** Response shape from the server file endpoints */
+interface FileRecord {
+    id: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+    url: string;
+    [key: string]: unknown;
+}
+/**
+ * Construct a file URL from the API base URL and file ID.
+ */
+declare function getFileUrl(baseUrl: string, fileId: string): string;
+/**
+ * Service for file upload, retrieval, and deletion.
+ * Access via {@link LazypockClient.files}.
+ */
+declare class FilesService {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Upload a file or blob.
+     *
+     * @param file The File or Blob to upload.
+     * @param filename Optional filename (required if `file` is a Blob without a name).
+     * @param options Optional request options (signal, custom fetch).
+     * @param meta Optional metadata: collectionName, recordId, fieldName for ownership tracking.
+     */
+    upload(file: File | Blob, filename?: string, options?: RequestOptions, meta?: {
+        collectionName?: string;
+        recordId?: string;
+        fieldName?: string;
+    }): Promise<FileRecord | null>;
+    /**
+     * Fetch file metadata including URL.
+     * @param fileId The file ID.
+     */
+    getUrl(fileId: string): Promise<string | null>;
+    /**
+     * Delete a file by ID.
+     * @param fileId The file ID.
+     * @param options Optional request options.
+     */
+    delete(fileId: string, options?: RequestOptions): Promise<null>;
+}
+
+/** Options for constructing a {@link LazypockClient}. */
+interface LazypockClientOptions {
+    /** API base URL (e.g. 'http://localhost:4000/api') */
+    baseUrl: string;
+    /** Custom storage adapter (default: localStorage fallback) */
+    storage?: StorageAdapter;
+    /** Explicit auth store instance (for sharing across modules) */
+    authStore?: AuthStore;
+    /** Real-time service for Phoenix Channel WebSocket subscriptions */
+    realtime?: RealtimeService;
+}
+/**
+ * Lazypock API client.
+ *
+ * Provides methods for authentication, CRUD operations on dynamic collections,
+ * file management, and real-time subscriptions.
+ *
+ * @example
+ * ```ts
+ * const client = new LazypockClient({ baseUrl: 'http://localhost:4000/api' });
+ * await client.login('admin@example.com', 'password');
+ * const posts = await client.collection('posts').list();
+ * ```
+ */
+declare class LazypockClient {
+    readonly http: HttpClient;
+    readonly authStore: AuthStore;
+    readonly realtime: RealtimeService;
+    readonly files: FilesService;
+    private collectionCache;
+    /**
+     * Create a new Lazypock client.
+     * @param options Configuration options.
+     */
+    constructor(options: LazypockClientOptions);
+    /**
+     * Get or create a typed service for the given collection.
+     * Services are cached after first access.
+     *
+     * @param name The collection name.
+     * @returns A {@link CollectionService} instance.
+     */
+    collection(name: string): CollectionService;
+    /** Check whether any superuser exists (for login vs setup screen routing). */
+    checkSuperuser(): Promise<{
+        has_superuser: boolean;
+    } | null>;
+    /**
+     * Create the initial superuser account.
+     * Only works when no superuser exists yet.
+     * Stores the returned token in the auth store.
+     * @param email Superuser email.
+     * @param password Superuser password (min 8 chars).
+     */
+    setup(email: string, password: string): Promise<({
+        token: string;
+    } & Record<string, unknown>) | null>;
+    /**
+     * Authenticate as a superuser or auth collection user.
+     *
+     * When `collection` is provided, authenticates against
+     * `/{collection}/auth-with-password`. Otherwise logs in as superuser.
+     * Stores the returned token in the auth store.
+     *
+     * @param email User email or identity.
+     * @param password User password.
+     * @param collection Optional auth collection name.
+     */
+    login(email: string, password: string, collection?: string): Promise<({
+        token: string;
+    } & Record<string, unknown>) | null>;
+    /** Fetch the current superuser profile and refresh the auth model. */
+    me<T = ApiRecord>(options?: RequestOptions): Promise<T | null>;
+    /**
+     * Authenticate against an auth collection with email/password.
+     * Stores the returned token and user record in the auth store.
+     *
+     * @param collection The auth collection name.
+     * @param identity Email or username.
+     * @param password Password.
+     * @param options Optional request options.
+     */
+    authWithPassword(collection: string, identity: string, password: string, options?: RequestOptions): Promise<({
+        token: string;
+        record: ApiRecord;
+    } & Record<string, unknown>) | null>;
+    /**
+     * Refresh an auth collection token.
+     * Uses the currently stored auth token.
+     *
+     * @param collection The auth collection name.
+     * @param options Optional request options.
+     */
+    authRefresh(collection: string, options?: RequestOptions): Promise<({
+        token: string;
+        record: ApiRecord;
+    } & Record<string, unknown>) | null>;
+    /** Clear the current auth state and remove persisted tokens. */
+    logout(): void;
+    /** Ping the API health endpoint. */
+    health(options?: RequestOptions): Promise<Record<string, unknown> | null>;
+    /**
+     * List all collections (admin).
+     * @param q URL query string (e.g. `page=1&perPage=200`).
+     * @param options Optional request options.
+     */
+    listCollections(q?: string, options?: RequestOptions): Promise<ListResult<ApiRecord> | null>;
+    /**
+     * Get a single collection by ID or name.
+     * @param id Collection ID or name.
+     * @param options Optional request options.
+     */
+    getCollection(id: string, options?: RequestOptions): Promise<ApiRecord | null>;
+    /**
+     * Create a new collection (admin).
+     * @param data Collection definition (name, type, fields, options, rules, etc.).
+     * @param options Optional request options.
+     */
+    createCollection(data: Record<string, unknown>, options?: RequestOptions): Promise<ApiRecord | null>;
+    /**
+     * Update an existing collection (admin).
+     * @param id Collection ID or name.
+     * @param data Updated collection fields.
+     * @param options Optional request options.
+     */
+    updateCollection(id: string, data: Record<string, unknown>, options?: RequestOptions): Promise<ApiRecord | null>;
+    /**
+     * Delete a collection (admin).
+     * @param id Collection ID or name.
+     * @param options Optional request options.
+     */
+    deleteCollection(id: string, options?: RequestOptions): Promise<null>;
+    /**
+     * List records from a dynamic collection with optional filter/sort/pagination.
+     *
+     * @param coll Collection name.
+     * @param params Query parameters including:
+     *   - `filter` — PocketBase filter syntax (e.g. `title~'hello' && published=true`)
+     *   - `sort` — Comma-separated, `-` prefix for DESC (e.g. `-created,title`)
+     *   - `page` — Page number (default: 1)
+     *   - `perPage` — Items per page (default: 30, max: 200)
+     *   - `expand` — Comma-separated relation fields (e.g. `author,category`)
+     * @param options Optional request options.
+     */
+    listRecords(coll: string, params?: Record<string, string>, options?: RequestOptions): Promise<ListResult<ApiRecord> | null>;
+    /**
+     * Get a single record by ID.
+     * @param coll Collection name.
+     * @param id Record ID.
+     * @param options Optional request options.
+     */
+    getRecord(coll: string, id: string, options?: RequestOptions): Promise<ApiRecord | null>;
+    /**
+     * Create a record in a dynamic collection.
+     * @param coll Collection name.
+     * @param data Record fields.
+     * @param options Optional request options.
+     */
+    createRecord(coll: string, data: Record<string, unknown>, options?: RequestOptions): Promise<ApiRecord | null>;
+    /**
+     * Update a record in a dynamic collection.
+     * @param coll Collection name.
+     * @param id Record ID.
+     * @param data Updated record fields.
+     * @param options Optional request options.
+     */
+    updateRecord(coll: string, id: string, data: Record<string, unknown>, options?: RequestOptions): Promise<ApiRecord | null>;
+    /**
+     * Delete a record from a dynamic collection.
+     * @param coll Collection name.
+     * @param id Record ID.
+     * @param options Optional request options.
+     */
+    deleteRecord(coll: string, id: string, options?: RequestOptions): Promise<null>;
+}
+
+export { ApiError, type ApiRecord, type AuthModel, AuthStore, type FileRecord, FilesService, LazypockClient, type LazypockClientOptions, type ListResult, RealtimeService, type RequestOptions, type StorageAdapter, getFileUrl, wsUrlFromBaseUrl };