mpb-localkit 1.4.16 → 1.4.18

package/dist/core/index.d.ts

@@ -1,21 +1,130 @@
-import { ZodRawShape, ZodObject } from 'zod';
+import { ZodRawShape, ZodObject, ZodTypeAny } from 'zod';
 export { z } from 'zod';
-import { e as CollectionOptions, b as CollectionDescriptor, f as StorageAdapter, D as Doc, F as Filter, g as Change, d as SyncEngine, c as SyncConfig, h as SyncTransport, P as PushPayload, i as PullPayload, A as AuthAdapter, a as Credentials, U as User, j as SocialAuthAdapter, k as SocialProvider, O as ObservableCollection } from '../collection-CBG-_MiM.js';
-export { C as Collection, l as OfflineSession, Q as QueryOptions, m as SyncResult, S as SyncStatus, T as TransportType, n as WhereClause, W as WithMeta } from '../collection-CBG-_MiM.js';
-import { E as ErrorConfig, a as ErrorEntry, b as ErrorType, c as ErrorContext, S as SyncAPI, d as ErrorTrackingConfig, A as AuthConfig } from '../types-BlqxG_-6.js';
-export { e as AppConfig, f as ErrorSnapshot } from '../types-BlqxG_-6.js';
-import { A as AuthStore, S as SyncStore } from '../events-hGI5qde5.js';
-export { c as collectionQueryOptions, l as localkitKeys, s as subscribeToCollection } from '../query-D2jbktTG.js';
+
+/** Metadata fields automatically added to every document */
+interface Doc {
+    _id: string;
+    _collection: string;
+    _updatedAt: number;
+    _deleted: boolean;
+    _schemaVersion?: number;
+    [key: string]: unknown;
+}
+/** User document merged with metadata fields */
+type WithMeta<T> = T & Doc;
+interface CollectionOptions {
+    version?: number;
+    migrate?: (doc: Record<string, unknown>) => Record<string, unknown>;
+}
+/**
+ * Descriptor produced by collection() — stores the Zod schema and collection name.
+ *
+ * TShape is the Zod raw shape; the inferred user-data type is CollectionDescriptor<TShape>['_inferredType'].
+ * The phantom `_inferredType` field drives downstream generic inference without a runtime value.
+ */
+interface CollectionDescriptor<TShape extends ZodRawShape = ZodRawShape> {
+    schema: ZodObject<TShape>;
+    collectionName: string;
+    version?: number;
+    migrate?: (doc: Record<string, unknown>) => Record<string, unknown>;
+    /** Phantom type — never set at runtime; carries z.infer<ZodObject<TShape>> for downstream generics */
+    readonly _inferredType: ZodObject<TShape>['_output'];
+}
 
 /**
  * Wraps a Zod schema to create a typed collection descriptor.
  * TypeScript infers the document type from the schema automatically.
  *
+ * Compatible with both Zod v3 and Zod v4.
+ *
  * @example
  * const brews = collection(z.object({ style: z.string(), og: z.number() }))
  * // brews._inferredType is { style: string; og: number }
  */
-declare function collection<TShape extends ZodRawShape>(schema: ZodObject<TShape>, options?: CollectionOptions): CollectionDescriptor<TShape>;
+declare function collection<TShape extends ZodRawShape>(schema: ZodObject<TShape> | ZodTypeAny, options?: CollectionOptions): CollectionDescriptor<TShape>;
+
+interface QueryOptions<T> {
+    where?: WhereClause<T>;
+    sort?: Partial<Record<keyof T, 'asc' | 'desc'>>;
+    limit?: number;
+    offset?: number;
+}
+type WhereClause<T> = {
+    [K in keyof T]?: T[K] | {
+        $gt?: T[K];
+        $lt?: T[K];
+        $gte?: T[K];
+        $lte?: T[K];
+        $in?: T[K][];
+    };
+};
+
+/** Key-value filter used by {@link StorageAdapter.getMany} to narrow results. */
+type Filter = Record<string, unknown>;
+/** Represents a single document change, used by sync to track modifications. */
+interface Change {
+    /** Unique document identifier. */
+    id: string;
+    /** Name of the collection this change belongs to. */
+    collection: string;
+    /** The full document snapshot at the time of the change. */
+    doc: Doc;
+    /** Epoch timestamp (ms) when the document was last modified. */
+    updatedAt: number;
+    /** Whether this change represents a deletion. */
+    deleted: boolean;
+}
+interface StorageAdapter {
+    /**
+     * Retrieve a single document by ID.
+     * Returns `null` if the document is not found or has been soft-deleted.
+     *
+     * @param collection - The collection name.
+     * @param id - The document ID.
+     * @returns The document, or `null` if not found / deleted.
+     */
+    get(collection: string, id: string): Promise<Doc | null>;
+    /**
+     * Return a document even if soft-deleted.
+     * Used by SyncEngine for conflict detection so it can compare local
+     * and remote versions of deleted documents.
+     *
+     * @param collection - The collection name.
+     * @param id - The document ID.
+     * @returns The document (including soft-deleted ones), or `null` if not found.
+     */
+    getRaw?(collection: string, id: string): Promise<Doc | null>;
+    /**
+     * Retrieve all non-deleted documents in a collection, optionally filtered.
+     *
+     * @param collection - The collection name.
+     * @param filter - Optional key-value filter to narrow results.
+     * @returns An array of matching documents.
+     */
+    getMany(collection: string, filter?: Filter): Promise<Doc[]>;
+    /**
+     * Insert or update a document.
+     *
+     * @param collection - The collection name.
+     * @param id - The document ID.
+     * @param doc - The full document to store.
+     */
+    put(collection: string, id: string, doc: Doc): Promise<void>;
+    /**
+     * Soft-delete a document (sets `_deleted: true`).
+     *
+     * @param collection - The collection name.
+     * @param id - The document ID.
+     */
+    delete(collection: string, id: string): Promise<void>;
+    /**
+     * Return all documents modified after the given timestamp, for sync.
+     *
+     * @param timestamp - Epoch timestamp (ms). Only changes after this time are returned.
+     * @returns An array of changes since the given timestamp.
+     */
+    getChangesSince(timestamp: number): Promise<Change[]>;
+}
 
 declare class IndexedDBAdapter implements StorageAdapter {
     private dbName;
@@ -144,6 +253,120 @@ interface MigrationResult {
  */
 declare function migrateToEncrypted(storage: StorageAdapter, encryptedStorage: EncryptedStorageAdapter): Promise<MigrationResult>;
 
+type ConflictResolver = (local: Doc, remote: Doc) => Doc;
+interface SyncTransport {
+    push(payload: PushPayload): Promise<number>;
+    pull(payload: PullPayload): Promise<Doc[]>;
+    setToken?(token: string | null): void;
+    destroy(): void;
+}
+type TransportType = 'http' | 'websocket' | 'auto';
+interface SyncConfig {
+    endpoint: string;
+    interval: number;
+    enabled: boolean;
+    conflictResolver?: ConflictResolver;
+    transport?: SyncTransport | TransportType;
+}
+type SyncStatus = 'idle' | 'syncing' | 'error' | 'offline';
+interface SyncResult {
+    pushed: number;
+    pulled: number;
+    conflicts: number;
+    error?: Error;
+}
+interface PushPayload {
+    changes: Change[];
+    lastSyncAt: number;
+}
+interface PullPayload {
+    since: number;
+}
+
+interface SyncEventMap {
+    'sync:start': () => void;
+    'sync:complete': (result: SyncResult) => void;
+    'sync:error': (error: unknown) => void;
+}
+type SyncEventType = keyof SyncEventMap;
+declare class SyncEngine {
+    private readonly storage;
+    private readonly config;
+    private status;
+    private lastSyncAt;
+    private lastSyncAtInitialized;
+    /** Typed listener map: values are SyncEventMap[E][] per event key. */
+    private readonly listenerMap;
+    private transport;
+    private readonly lastSyncKey;
+    constructor(storage: StorageAdapter, config: SyncConfig);
+    /**
+     * Return the current sync status.
+     *
+     * @returns The current {@link SyncStatus} (`'idle'`, `'syncing'`, `'error'`, or `'offline'`).
+     */
+    getStatus(): SyncStatus;
+    /**
+     * Return the timestamp of the last successful sync.
+     *
+     * @returns Epoch timestamp (ms), or `0` if no sync has completed yet.
+     */
+    getLastSyncAt(): number;
+    /**
+     * Set the bearer token used by the transport for authenticated requests.
+     *
+     * @param token - The bearer token string, or `null` to clear it.
+     */
+    setToken(token: string | null): void;
+    /**
+     * Register a listener for sync events.
+     *
+     * @param event - The event type to listen for.
+     * @param listener - The callback to invoke when the event fires.
+     */
+    on<E extends SyncEventType>(event: E, listener: SyncEventMap[E]): void;
+    /**
+     * Remove a previously registered sync event listener.
+     *
+     * @param event - The event type.
+     * @param listener - The callback to remove.
+     */
+    off<E extends SyncEventType>(event: E, listener: SyncEventMap[E]): void;
+    /**
+     * Push local changes to the server.
+     *
+     * @returns The number of documents pushed.
+     */
+    push(): Promise<number>;
+    /**
+     * Pull remote changes from the server. Applies conflict resolution for
+     * documents that exist both locally and remotely.
+     *
+     * @returns An object with `pulled` (total remote docs received) and `conflicts` (local-wins count).
+     */
+    pull(): Promise<{
+        pulled: number;
+        conflicts: number;
+    }>;
+    /**
+     * Run a full push+pull sync cycle. Pushes local changes first, then pulls
+     * remote changes. Updates the last-sync timestamp on success.
+     *
+     * @returns A {@link SyncResult} with pushed, pulled, and conflicts counts.
+     */
+    sync(): Promise<SyncResult>;
+    /**
+     * Clean up the transport (close WebSocket connections, etc.).
+     * Call this when the sync engine is no longer needed.
+     */
+    destroy(): void;
+    private resolveTransport;
+    private setStatus;
+    private emit;
+    private loadLastSyncAt;
+    private saveLastSyncAt;
+}
+
 /**
  * Last-Write-Wins conflict resolver.
  * Compares _updatedAt timestamps; highest wins.
@@ -215,6 +438,35 @@ declare class AutoTransport implements SyncTransport {
     destroy(): void;
 }
 
+interface User {
+    id: string;
+    email: string;
+}
+interface Credentials {
+    email: string;
+    password: string;
+    name?: string;
+}
+interface AuthAdapter {
+    signUp(credentials: Credentials): Promise<User>;
+    signIn(credentials: Credentials): Promise<User>;
+    signOut(): Promise<void>;
+    currentUser(): User | null;
+    getToken(): string | null;
+    /** Revalidate a cached session against the server. Returns null if invalid. */
+    revalidateSession?(): Promise<User | null>;
+}
+type SocialProvider = 'google' | 'github' | 'apple' | 'microsoft';
+interface SocialAuthAdapter extends AuthAdapter {
+    signInWithSocial(provider: SocialProvider): Promise<User>;
+}
+interface OfflineSession {
+    user: User;
+    token: string;
+    expiresAt: number;
+    provider?: SocialProvider | 'email';
+}
+
 interface EmailPasswordAuthConfig {
     endpoint: string;
 }
@@ -344,6 +596,36 @@ declare class OfflineSessionAdapter implements AuthAdapter {
     getToken(): string | null;
 }
 
+interface ErrorContext {
+    route?: string;
+    action?: string;
+    collection?: string;
+    online: boolean;
+    userAgent?: string;
+}
+interface ErrorSnapshot {
+    localStorageSize?: number;
+    pendingSyncCount?: number;
+    lastSyncAt?: number;
+}
+type ErrorType = 'unhandled_exception' | 'network_error' | 'sync_error' | 'validation_error' | 'runtime';
+interface ErrorConfig {
+    enabled: boolean;
+    snapshot: boolean;
+    maxLocalErrors: number;
+    onError?: (error: ErrorEntry) => void;
+    webhookUrl?: string;
+}
+interface ErrorEntry extends Doc {
+    _collection: '_errors';
+    timestamp: number;
+    type: ErrorType;
+    message: string;
+    stack?: string;
+    context: ErrorContext;
+    snapshot?: ErrorSnapshot;
+}
+
 /**
  * Low-level error tracker that persists errors to a StorageAdapter.
  * Supports snapshot capture, webhook delivery with retry, and automatic pruning.
@@ -408,6 +690,168 @@ declare class ErrorManager {
     getTracker(): ErrorTracker;
 }
 
+type AuthConfig = AuthAdapter | {
+    type: 'email-password';
+    endpoint: string;
+} | {
+    type: 'better-auth';
+    /** Base URL of the Better Auth server (e.g. "https://api.example.com") */
+    baseURL: string;
+};
+interface SyncAPI {
+    push(): Promise<number>;
+    pull(): Promise<{
+        pulled: number;
+        conflicts: number;
+    }>;
+    start(): void;
+    stop(): void;
+    readonly status: SyncStatus;
+}
+interface ErrorTrackingConfig {
+    enabled?: boolean;
+    snapshot?: boolean;
+    maxLocalErrors?: number;
+    onError?: (error: ErrorEntry) => void;
+}
+interface AppConfig {
+    collections: Record<string, CollectionDescriptor<ZodRawShape>>;
+    sync?: Partial<SyncConfig>;
+    errorTracking?: ErrorTrackingConfig;
+}
+
+/**
+ * A collection that supports reactive subscriptions.
+ * Compatible with React's `useSyncExternalStore` via `subscribe` + `getSnapshot`.
+ */
+interface ObservableCollection<T> extends Collection<T> {
+    /**
+     * Subscribe to collection changes. The listener is called whenever the
+     * in-memory snapshot is refreshed (after any mutation).
+     * Compatible with `useSyncExternalStore`.
+     *
+     * @param listener - Callback invoked on every snapshot change.
+     * @returns An unsubscribe function.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Get the current in-memory snapshot of all documents.
+     *
+     * @returns A read-only array of all non-deleted documents.
+     */
+    getSnapshot(): ReadonlyArray<WithMeta<T>>;
+}
+interface Collection<T> {
+    /** The name of this collection. */
+    readonly name: string;
+    /**
+     * Create a new document, auto-generating `_id` and metadata fields
+     * (`_collection`, `_updatedAt`, `_deleted`).
+     *
+     * @param data - The user-defined fields for the document.
+     * @returns The created document with all metadata fields populated.
+     *
+     * @example
+     * ```ts
+     * const todo = await todos.create({ title: 'Buy milk', done: false })
+     * console.log(todo._id) // auto-generated
+     * ```
+     */
+    create(data: T): Promise<WithMeta<T>>;
+    /**
+     * Query documents with optional where, sort, limit, and offset filters.
+     *
+     * @param options - Optional query options (where, sort, limit, offset).
+     * @returns An array of matching documents.
+     *
+     * @example
+     * ```ts
+     * const active = await todos.findMany({
+     *   where: { done: { $eq: false } },
+     *   sort: { field: 'title', direction: 'asc' },
+     *   limit: 10,
+     * })
+     * ```
+     */
+    findMany(options?: QueryOptions<T>): Promise<WithMeta<T>[]>;
+    /**
+     * Find a single document by ID. Returns `null` if not found.
+     *
+     * @param id - The document ID.
+     * @returns The document, or `null` if not found or deleted.
+     */
+    findOne(id: string): Promise<WithMeta<T> | null>;
+    /**
+     * Partially update a document. Validates the merged result against the schema.
+     *
+     * @param id - The document ID.
+     * @param data - Partial fields to merge into the existing document.
+     * @returns The updated document.
+     * @throws If the document is not found or deleted.
+     */
+    update(id: string, data: Partial<T>): Promise<WithMeta<T>>;
+    /**
+     * Soft-delete a document (sets `_deleted: true`).
+     *
+     * @param id - The document ID.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Count documents matching an optional query.
+     *
+     * @param options - Optional query options (where, sort, limit, offset).
+     * @returns The number of matching documents.
+     */
+    count(options?: QueryOptions<T>): Promise<number>;
+    /**
+     * Check if a non-deleted document with the given ID exists.
+     *
+     * @param id - The document ID.
+     * @returns `true` if the document exists and is not deleted.
+     */
+    exists(id: string): Promise<boolean>;
+}
+
+interface AuthState {
+    user: User | null;
+    token: string | null;
+    isLoading: boolean;
+}
+interface SyncState {
+    status: SyncStatus;
+    lastSyncAt: number | null;
+}
+/** Observable auth wrapper — delegates to AuthAdapter and notifies React subscribers on state changes. */
+declare class AuthStore implements AuthAdapter {
+    private readonly adapter;
+    private state;
+    private listeners;
+    constructor(adapter: AuthAdapter);
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): AuthState;
+    private notify;
+    signUp(credentials: Credentials): Promise<User>;
+    signIn(credentials: Credentials): Promise<User>;
+    signOut(): Promise<void>;
+    currentUser(): User | null;
+    getToken(): string | null;
+    /**
+     * Revalidate a cached session against the server.
+     * Delegates to the inner adapter's `revalidateSession` if it supports it.
+     *
+     * @returns The revalidated user, or `null` if the session is invalid or the adapter does not support revalidation.
+     */
+    revalidateSession(): Promise<User | null>;
+}
+/** Observable sync state — updated by the sync engine and read by useSync. */
+declare class SyncStore {
+    private state;
+    private listeners;
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): SyncState;
+    setStatus(status: SyncStatus, lastSyncAt?: number): void;
+}
+
 type ObservableInferredCollections<C extends Record<string, CollectionDescriptor<ZodRawShape>>> = {
     [K in keyof C]: ObservableCollection<C[K]['_inferredType']>;
 };
@@ -426,4 +870,21 @@ interface CreateAppConfig<C extends Record<string, CollectionDescriptor<ZodRawSh
 }
 declare function createApp<C extends Record<string, CollectionDescriptor<ZodRawShape>>>(config: CreateAppConfig<C>): App<C>;
 
-export { type App, AuthAdapter, AuthConfig, AutoTransport, type AutoTransportConfig, BetterAuthAdapter, type BetterAuthAdapterConfig, type BetterAuthClient, Change, CollectionDescriptor, type CreateAppConfig, Credentials, Doc, EmailPasswordAuth, type EmailPasswordAuthConfig, EncryptedStorageAdapter, type EncryptionConfig, ErrorContext, ErrorEntry, ErrorTrackingConfig, ErrorType, Filter, HttpTransport, IndexedDBAdapter, type KeySpec, type KeychainConfig, MemoryAdapter, type MigrationResult, OfflineSessionAdapter, PullPayload, PushPayload, type ReEncryptResult, SocialAuthAdapter, SocialProvider, StorageAdapter, SyncConfig, SyncEngine, SyncTransport, User, WebSocketTransport, type WebSocketTransportConfig, type WrapConfig, collection, createApp, encrypted, generateId, hashPassword, migrateToEncrypted, reEncryptAll, resolveConflict, rewrapKey, setupFocusTrigger, setupIntervalTrigger, setupReconnectTrigger };
+/** Minimal QueryClient interface — avoids a hard dep on @tanstack/query-core */
+interface MinimalQueryClient {
+    invalidateQueries(opts: {
+        queryKey: readonly unknown[];
+    }): Promise<void>;
+}
+declare const localkitKeys: {
+    all: readonly ["offlinekit"];
+    collection: (name: string) => readonly ["offlinekit", string];
+    collectionQuery: (name: string, opts: unknown) => readonly ["offlinekit", string, string];
+};
+declare function collectionQueryOptions<T>(collection: Collection<T>, queryOptions?: QueryOptions<T>): {
+    queryKey: readonly unknown[];
+    queryFn: () => Promise<WithMeta<T>[]>;
+};
+declare function subscribeToCollection<T>(collection: Collection<T>, queryClient: MinimalQueryClient): () => void;
+
+export { type App, type AppConfig, type AuthAdapter, type AuthConfig, AutoTransport, type AutoTransportConfig, BetterAuthAdapter, type BetterAuthAdapterConfig, type BetterAuthClient, type Change, type Collection, type CollectionDescriptor, type CreateAppConfig, type Credentials, type Doc, EmailPasswordAuth, type EmailPasswordAuthConfig, EncryptedStorageAdapter, type EncryptionConfig, type ErrorContext, type ErrorEntry, type ErrorSnapshot, type ErrorTrackingConfig, type ErrorType, type Filter, HttpTransport, IndexedDBAdapter, type KeySpec, type KeychainConfig, MemoryAdapter, type MigrationResult, type OfflineSession, OfflineSessionAdapter, type PullPayload, type PushPayload, type QueryOptions, type ReEncryptResult, type SocialAuthAdapter, type SocialProvider, type StorageAdapter, type SyncConfig, SyncEngine, type SyncResult, type SyncStatus, type SyncTransport, type TransportType, type User, WebSocketTransport, type WebSocketTransportConfig, type WhereClause, type WithMeta, type WrapConfig, collection, collectionQueryOptions, createApp, encrypted, generateId, hashPassword, localkitKeys, migrateToEncrypted, reEncryptAll, resolveConflict, rewrapKey, setupFocusTrigger, setupIntervalTrigger, setupReconnectTrigger, subscribeToCollection };

package/dist/core/index.js

@@ -1184,7 +1184,13 @@ var BetterAuthAdapter = class {
     return this.session?.user ?? null;
   }
   getToken() {
-    return this.session?.token ?? null;
+    const token = this.session?.token ?? null;
+    if (!token && this.session?.user) {
+      console.warn(
+        "[mpb-localkit] BetterAuthAdapter.getToken() returned null. Ensure the bearer plugin is enabled on your Better Auth server."
+      );
+    }
+    return token;
   }
 };