@eide/sync-client 0.1.0

package/dist/react.d.ts

@@ -0,0 +1,541 @@
+import * as y_protocols_awareness from 'y-protocols/awareness';
+import * as yjs from 'yjs';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Core types for the sync engine.
+ *
+ * These mirror the server-side GraphQL schema but are
+ * framework-agnostic and use native JS types (no BigInt transport concerns).
+ */
+interface SyncableRecord {
+    /** Server-assigned ID (empty string for locally-created records not yet synced) */
+    id: string;
+    /** Client-assigned temporary ID */
+    clientId: string;
+    modelKey: string;
+    naturalKey: string | null;
+    data: Record<string, unknown>;
+    metadata: Record<string, unknown> | null;
+    /** Monotonically increasing version from server. "0" for local-only records. */
+    syncVersion: string;
+    updatedAt: string;
+    deleted: boolean;
+    /** True if this record has local changes not yet pushed to server */
+    pending: boolean;
+}
+interface SyncClientConfig {
+    /** GraphQL endpoint URL (e.g. https://api.example.com/graphql) */
+    graphqlUrl: string;
+    /** WebSocket URL for subscriptions (e.g. wss://api.example.com/graphql) */
+    wsUrl?: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** Bearer token for authentication */
+    token?: string;
+    /** Model keys to sync (subscribes to changes for each) */
+    modelKeys: string[];
+    /** Polling interval in ms when WebSocket is unavailable (default: 5000) */
+    pollInterval?: number;
+    /** Max items per pull request (default: 100) */
+    pullLimit?: number;
+    /** Max items per push batch (default: 50) */
+    pushBatchSize?: number;
+    /** Conflict resolution strategy (default: 'server-wins') */
+    conflictStrategy?: ConflictStrategy;
+    /** Custom conflict resolver (used when strategy is 'custom') */
+    customResolver?: CustomConflictResolver;
+    /** Whether to enable debug logging (default: false) */
+    debug?: boolean;
+}
+interface QueryOptions {
+    /** Filter by naturalKey */
+    naturalKey?: string;
+    /** Filter function applied client-side */
+    filter?: (record: SyncableRecord) => boolean;
+    /** Sort function */
+    sort?: (a: SyncableRecord, b: SyncableRecord) => number;
+    /** Limit results */
+    limit?: number;
+    /** Skip N results */
+    offset?: number;
+}
+interface SyncResult {
+    pulled: number;
+    pushed: number;
+    conflicts: number;
+    errors: number;
+}
+type ConflictStrategy = 'field-lww' | 'server-wins' | 'client-wins' | 'custom';
+type CustomConflictResolver = (local: Record<string, unknown>, server: Record<string, unknown>) => {
+    resolved: Record<string, unknown>;
+    conflictedFields: string[];
+};
+interface ConflictEvent {
+    recordId: string;
+    modelKey: string;
+    localData: Record<string, unknown>;
+    serverData: Record<string, unknown>;
+    resolvedData: Record<string, unknown>;
+    conflictedFields: string[];
+    strategy: ConflictStrategy;
+}
+type SyncEngineEvent = {
+    type: 'sync-start';
+} | {
+    type: 'sync-complete';
+    result: SyncResult;
+} | {
+    type: 'sync-error';
+    error: Error;
+} | {
+    type: 'conflict';
+    event: ConflictEvent;
+} | {
+    type: 'connected';
+} | {
+    type: 'disconnected';
+} | {
+    type: 'records-changed';
+    modelKey: string;
+    recordIds: string[];
+} | {
+    type: 'pending-changed';
+    count: number;
+};
+type SyncEngineEventHandler = (event: SyncEngineEvent) => void;
+
+/**
+ * Storage Adapter — Abstract interface for local persistence.
+ *
+ * Implementations: IndexedDB (web), Memory (tests/SSR).
+ * Each "store" is a named key-value namespace.
+ */
+interface StorageAdapter {
+    /** Get a single value by key from a store */
+    get<T>(store: string, key: string): Promise<T | undefined>;
+    /** Put a value by key into a store */
+    put<T>(store: string, key: string, value: T): Promise<void>;
+    /** Delete a value by key from a store */
+    delete(store: string, key: string): Promise<void>;
+    /** Get all values from a store */
+    getAll<T>(store: string): Promise<T[]>;
+    /** Clear all values from a store */
+    clear(store: string): Promise<void>;
+    /** Get a metadata value (separate namespace from record stores) */
+    getMeta(key: string): Promise<string | undefined>;
+    /** Set a metadata value */
+    setMeta(key: string, value: string): Promise<void>;
+}
+
+/**
+ * SyncEngine — Layer 1 orchestrator for local-first data sync.
+ *
+ * Provides:
+ * - Instant local reads/writes via StorageAdapter
+ * - Background pull/push sync loop with the server
+ * - Real-time subscription for live updates (WebSocket, falls back to polling)
+ * - Offline queue with retry and conflict resolution
+ */
+
+declare class SyncEngine {
+    private config;
+    private storage;
+    private queue;
+    private listeners;
+    private syncTimer;
+    private wsCleanup;
+    private running;
+    private syncing;
+    constructor(config: SyncClientConfig, storage: StorageAdapter);
+    on(handler: SyncEngineEventHandler): () => void;
+    private emit;
+    private log;
+    /**
+     * Start background sync loop and subscriptions.
+     */
+    start(): void;
+    /**
+     * Stop sync engine, close connections.
+     */
+    stop(): void;
+    /**
+     * Force an immediate sync cycle.
+     */
+    sync(): Promise<SyncResult>;
+    /**
+     * Query records from local storage.
+     */
+    query(modelKey: string, opts?: QueryOptions): Promise<SyncableRecord[]>;
+    /**
+     * Get a single record by server ID.
+     */
+    get(modelKey: string, id: string): Promise<SyncableRecord | null>;
+    /**
+     * Get a record by natural key.
+     */
+    getByKey(modelKey: string, naturalKey: string): Promise<SyncableRecord | null>;
+    /**
+     * Create a record locally and queue for push.
+     */
+    create(modelKey: string, data: Record<string, unknown>, naturalKey?: string): Promise<SyncableRecord>;
+    /**
+     * Update a record locally and queue for push.
+     */
+    update(modelKey: string, id: string, data: Record<string, unknown>): Promise<SyncableRecord | null>;
+    /**
+     * Delete a record locally and queue for push.
+     */
+    delete(modelKey: string, id: string): Promise<void>;
+    /**
+     * Get count of pending mutations.
+     */
+    getPendingCount(): Promise<number>;
+    private pullModel;
+    private pushPending;
+    private connectSubscriptions;
+    private setupWebSocket;
+    private handleSubscriptionEvent;
+    private graphqlQuery;
+    private storeKey;
+}
+
+/**
+ * Memory Storage Adapter — In-memory implementation for tests and SSR.
+ *
+ * All data is lost when the adapter is garbage collected.
+ */
+
+declare class MemoryAdapter implements StorageAdapter {
+    private stores;
+    private meta;
+    private getStore;
+    get<T>(store: string, key: string): Promise<T | undefined>;
+    put<T>(store: string, key: string, value: T): Promise<void>;
+    delete(store: string, key: string): Promise<void>;
+    getAll<T>(store: string): Promise<T[]>;
+    clear(store: string): Promise<void>;
+    getMeta(key: string): Promise<string | undefined>;
+    setMeta(key: string, value: string): Promise<void>;
+}
+
+/**
+ * IndexedDB Storage Adapter — Persistent browser storage via the `idb` library.
+ *
+ * Uses a single IndexedDB database with one object store per "store" name.
+ * Store names are created lazily on first access via version upgrades.
+ */
+
+declare class IndexedDBAdapter implements StorageAdapter {
+    private dbName;
+    private db;
+    private knownStores;
+    private version;
+    constructor(dbName?: string);
+    private ensureStore;
+    get<T>(store: string, key: string): Promise<T | undefined>;
+    put<T>(store: string, key: string, value: T): Promise<void>;
+    delete(store: string, key: string): Promise<void>;
+    getAll<T>(store: string): Promise<T[]>;
+    clear(store: string): Promise<void>;
+    getMeta(key: string): Promise<string | undefined>;
+    setMeta(key: string, value: string): Promise<void>;
+}
+
+/**
+ * Collaborative Editing Types — Layer 2.
+ */
+interface SessionUser {
+    userId: string;
+    userName: string;
+    color: string;
+    joinedAt?: string;
+}
+interface SessionChange {
+    id: string;
+    fieldPath: string;
+    fieldValue: unknown;
+    previousValue?: unknown;
+    userId: string;
+    userName?: string;
+    createdAt: string;
+    sessionId?: string;
+    appliedToVersion?: boolean;
+}
+interface CollabSessionOptions {
+    /** WebSocket URL for Yjs (e.g. ws://localhost:4000/yjs) */
+    wsUrl: string;
+    /** Room name (format: entityType:entityId:variantId) */
+    room: string;
+    /** User info for presence */
+    user?: {
+        id: string;
+        name: string;
+        color?: string;
+    };
+    /** API base URL for clear-session REST call (optional, for admin compat) */
+    apiUrl?: string;
+    /** Authentication mode */
+    auth?: {
+        /** Session cookie name (admin mode — cookies sent automatically) */
+        sessionCookie?: boolean;
+        /** API key (public mode — sent as query param) */
+        apiKey?: string;
+        /** Bearer token (public mode — sent as query param) */
+        token?: string;
+    };
+}
+interface CollabFieldUpdateEvent {
+    path: string;
+    value: unknown;
+    origin: string;
+}
+interface CollabUndoStateEvent {
+    canUndo: boolean;
+    canRedo: boolean;
+}
+
+type YDoc = yjs.Doc;
+type YMap = yjs.Map<unknown>;
+type YArray = yjs.Array<SessionChange>;
+type YUndoManager = yjs.UndoManager;
+type Awareness = y_protocols_awareness.Awareness;
+type EventMap = {
+    'field-updated': CollabFieldUpdateEvent;
+    'changelog-changed': SessionChange[];
+    'presence-changed': SessionUser[];
+    'can-undo-changed': CollabUndoStateEvent;
+    connected: void;
+    synced: void;
+    disconnected: void;
+};
+type EventHandler<T> = (data: T) => void;
+declare class CollabSession {
+    private _ydoc;
+    private _content;
+    private _changesLog;
+    private _undoManager;
+    private _awareness;
+    private provider;
+    private options;
+    private _connected;
+    private _synced;
+    private _activeUsers;
+    private _sessionChanges;
+    private _canUndo;
+    private _canRedo;
+    private fieldSessions;
+    private listeners;
+    private cleanupFns;
+    constructor(options: CollabSessionOptions);
+    get ydoc(): YDoc | null;
+    get content(): YMap | null;
+    get changesLog(): YArray | null;
+    get undoManager(): YUndoManager | null;
+    get awareness(): Awareness | null;
+    get connected(): boolean;
+    get synced(): boolean;
+    get activeUsers(): SessionUser[];
+    get sessionChanges(): SessionChange[];
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    get room(): string;
+    on<K extends keyof EventMap>(event: K, handler: EventHandler<EventMap[K]>): () => void;
+    private emit;
+    connect(): Promise<void>;
+    disconnect(): void;
+    private setupPresence;
+    setUser(user: {
+        id: string;
+        name: string;
+        color?: string;
+    }): void;
+    private setupContentObservation;
+    updateField(fieldPath: string, value: unknown): void;
+    initializeContent(values: Record<string, unknown>, versionId?: string): void;
+    getContent(): Record<string, unknown>;
+    getContentStatus(): {
+        hasContent: boolean;
+        versionId: string | null;
+    };
+    loadContentIntoForm(): boolean;
+    undo(): void;
+    redo(): void;
+    revertField(fieldPath: string, previousValue: unknown, changeId?: string): void;
+    revertAll(): void;
+    clearSession(): Promise<void>;
+    /**
+     * Suppress changes for a duration (ms). Used to prevent phantom
+     * change entries after save/clear.
+     */
+    suppressChanges(durationMs: number): void;
+    clearContent(): void;
+}
+
+/**
+ * Presence helpers — user colors and awareness utilities.
+ */
+/**
+ * Generate a consistent color for a user based on their ID.
+ */
+declare function getUserColor(userId: string): string;
+
+interface SyncContextValue {
+    engine: SyncEngine;
+    connected: boolean;
+    pendingCount: number;
+    lastSyncError: Error | null;
+}
+interface SyncProviderProps {
+    config: SyncClientConfig;
+    storage: StorageAdapter;
+    children: ReactNode;
+    /** If false, engine is created but not started (default: true) */
+    autoStart?: boolean;
+}
+declare function SyncProvider({ config, storage, children, autoStart, }: SyncProviderProps): react_jsx_runtime.JSX.Element;
+declare function useSyncContext(): SyncContextValue;
+
+/**
+ * useSyncQuery — Read from local store (reactive).
+ *
+ * Subscribes to SyncEngine events and re-queries local storage
+ * when records change for the specified model key.
+ */
+
+interface UseSyncQueryResult {
+    data: SyncableRecord[];
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+declare function useSyncQuery(modelKey: string, options?: QueryOptions): UseSyncQueryResult;
+/**
+ * useSyncRecord — Get a single record by ID (reactive).
+ */
+declare function useSyncRecord(modelKey: string, id: string | null): {
+    data: SyncableRecord | null;
+    loading: boolean;
+};
+
+/**
+ * useSyncMutation — Write locally + queue sync.
+ *
+ * Optimistic: writes to local storage immediately, pushes in background.
+ * Returns the pending count and sync status.
+ */
+
+interface UseSyncMutationResult {
+    create: (modelKey: string, data: Record<string, unknown>, naturalKey?: string) => Promise<SyncableRecord>;
+    update: (modelKey: string, id: string, data: Record<string, unknown>) => Promise<SyncableRecord | null>;
+    remove: (modelKey: string, id: string) => Promise<void>;
+    sync: () => Promise<void>;
+    pendingCount: number;
+}
+declare function useSyncMutation(): UseSyncMutationResult;
+
+/**
+ * useCollaborativeSession — React hook wrapping CollabSession.
+ *
+ * Creates a CollabSession on mount, connects/disconnects with lifecycle,
+ * and maps events to React state.
+ */
+
+interface UseCollaborativeSessionResult {
+    /** The underlying CollabSession instance */
+    session: CollabSession | null;
+    /** Whether connected to WebSocket server */
+    connected: boolean;
+    /** Whether the Y.Doc is synced */
+    synced: boolean;
+    /** Active remote users in the session */
+    activeUsers: SessionUser[];
+    /** Changelog entries */
+    changelog: SessionChange[];
+    /** Whether undo is available */
+    canUndo: boolean;
+    /** Whether redo is available */
+    canRedo: boolean;
+    /** Update a field value */
+    updateField: (fieldPath: string, value: unknown) => void;
+    /** Undo last change */
+    undo: () => void;
+    /** Redo last undone change */
+    redo: () => void;
+    /** Revert a specific field */
+    revertField: (fieldPath: string, previousValue: unknown, changeId?: string) => void;
+    /** Revert all changes */
+    revertAll: () => void;
+    /** Get current content values */
+    getContent: () => Record<string, unknown>;
+    /** Check content status without loading */
+    getContentStatus: () => {
+        hasContent: boolean;
+        versionId: string | null;
+    };
+    /** Initialize content (first user to join) */
+    initializeContent: (values: Record<string, unknown>, versionId?: string) => void;
+    /** Load content into form via field-updated events */
+    loadContentIntoForm: () => boolean;
+    /** Clear session (after version save) */
+    clearSession: () => Promise<void>;
+    /** Clear stale content */
+    clearContent: () => void;
+}
+interface UseCollaborativeSessionOptions extends CollabSessionOptions {
+    /** Enable/disable the session (default: true) */
+    enabled?: boolean;
+    /** Callback when a remote user updates a field */
+    onFieldUpdate?: (path: string, value: unknown, origin: string) => void;
+}
+declare function useCollaborativeSession(options: UseCollaborativeSessionOptions): UseCollaborativeSessionResult;
+
+/**
+ * SyncBridge — Bidirectional coordination between Layer 1 (sync) and Layer 2 (collab).
+ *
+ * Responsibilities:
+ * 1. Auto-save: CollabSession field edits → SyncEngine.update() → push to server
+ * 2. Remote changes: SyncEngine subscription → CollabSession Y.Doc update
+ * 3. Loop prevention: Origin tracking prevents infinite push/pull cycles
+ */
+
+interface SyncBridgeOptions {
+    /** The record ID being collaboratively edited */
+    recordId: string;
+    /** The model key for the record */
+    modelKey: string;
+    /** Enable auto-save mode (default: true) */
+    autoSave?: boolean;
+}
+declare class SyncBridge {
+    private engine;
+    private session;
+    private options;
+    private cleanupFns;
+    private autoSaveTimer;
+    /** Tracks our own writes to prevent re-applying them from subscription */
+    private selfWriteVersions;
+    constructor(engine: SyncEngine, session: CollabSession, options: SyncBridgeOptions);
+    private setup;
+    /**
+     * Auto-save: read content from CollabSession Y.Doc, push via SyncEngine.
+     */
+    private autoSave;
+    /**
+     * Apply remote changes from SyncEngine to CollabSession Y.Doc.
+     * Uses 'remote-sync' origin to prevent re-pushing.
+     */
+    private applyRemoteChanges;
+    /**
+     * Manual save: used for "version save" mode (admin clicks Save button).
+     * Reads content from CollabSession, pushes immediately, then clears session.
+     */
+    saveVersion(): Promise<Record<string, unknown>>;
+    /**
+     * Destroy the bridge and clean up all subscriptions.
+     */
+    destroy(): void;
+}
+
+export { type CollabFieldUpdateEvent, CollabSession, type CollabSessionOptions, type CollabUndoStateEvent, type ConflictEvent, type ConflictStrategy, IndexedDBAdapter, MemoryAdapter, type QueryOptions, type SessionChange, type SessionUser, type StorageAdapter, SyncBridge, type SyncBridgeOptions, type SyncClientConfig, type SyncContextValue, SyncEngine, type SyncEngineEvent, SyncProvider, type SyncProviderProps, type SyncResult, type SyncableRecord, type UseCollaborativeSessionOptions, type UseCollaborativeSessionResult, type UseSyncMutationResult, type UseSyncQueryResult, getUserColor, useCollaborativeSession, useSyncContext, useSyncMutation, useSyncQuery, useSyncRecord };