@eide/sync-client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,542 @@
+import * as y_protocols_awareness from 'y-protocols/awareness';
+import * as yjs from 'yjs';
+
+/**
+ * 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>;
+}
+
+/**
+ * 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 PendingMutation {
+    /** Auto-generated queue ID */
+    queueId: string;
+    /** Client-assigned temporary ID or server ID */
+    clientId: string;
+    op: 'create' | 'update' | 'delete';
+    modelKey: string;
+    naturalKey?: string;
+    data?: Record<string, unknown>;
+    /** The syncVersion the client expects (for optimistic locking) */
+    expectedSyncVersion?: string;
+    /** ISO timestamp when the mutation was created */
+    createdAt: string;
+    /** Number of times this mutation has been attempted */
+    retryCount: number;
+}
+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;
+interface GqlSyncDeltaItem {
+    id: string;
+    modelKey: string;
+    naturalKey: string | null;
+    data: Record<string, unknown> | null;
+    metadata: Record<string, unknown> | null;
+    syncVersion: string;
+    updatedAt: string;
+    deleted: boolean;
+}
+interface GqlSyncDeltaResult {
+    items: GqlSyncDeltaItem[];
+    cursor: string;
+    hasMore: boolean;
+}
+interface GqlSyncPushResultItem {
+    clientId: string;
+    serverId: string;
+    syncVersion: string;
+    status: 'applied' | 'conflict' | 'error';
+    serverData?: Record<string, unknown> | null;
+    serverSyncVersion?: string;
+    error?: string;
+}
+interface GqlRecordChangedEvent {
+    type: 'created' | 'updated' | 'deleted';
+    recordId: string;
+    modelKey: string;
+    naturalKey: string | null;
+    syncVersion: string;
+    data: Record<string, unknown> | null;
+    updatedBy: string | null;
+    timestamp: string;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Conflict Resolution — Field-level LWW merge and configurable strategies.
+ *
+ * When the server rejects a push with status='conflict', the client must
+ * reconcile local and server state before retrying.
+ */
+
+interface ConflictResolution {
+    resolved: Record<string, unknown>;
+    conflictedFields: string[];
+}
+/**
+ * Resolve conflicts between local and server data.
+ */
+declare function resolveConflict(local: Record<string, unknown>, server: Record<string, unknown>, strategy: ConflictStrategy, customResolver?: CustomConflictResolver): ConflictResolution;
+
+/**
+ * Offline Queue — Manages pending mutations that haven't been pushed to the server.
+ *
+ * Mutations are stored in the storage adapter and replayed in order
+ * when the sync engine pushes. Supports deduplication (latest update wins).
+ */
+
+declare class OfflineQueue {
+    private storeName;
+    private storage;
+    constructor(storage: StorageAdapter);
+    /**
+     * Enqueue a new mutation. Deduplicates by clientId —
+     * if a pending mutation already exists for the same clientId with the same op,
+     * the newer one replaces it (for updates).
+     */
+    enqueue(mutation: Omit<PendingMutation, 'queueId' | 'createdAt' | 'retryCount'>): Promise<PendingMutation>;
+    /**
+     * Get all pending mutations in creation order.
+     */
+    getAll(): Promise<PendingMutation[]>;
+    /**
+     * Get a batch of mutations for pushing.
+     */
+    getBatch(limit: number): Promise<PendingMutation[]>;
+    /**
+     * Remove a mutation after successful push.
+     */
+    remove(queueId: string): Promise<void>;
+    /**
+     * Remove multiple mutations.
+     */
+    removeBatch(queueIds: string[]): Promise<void>;
+    /**
+     * Increment retry count for a failed mutation.
+     */
+    incrementRetry(queueId: string): Promise<void>;
+    /**
+     * Get count of pending mutations.
+     */
+    count(): Promise<number>;
+    /**
+     * Clear all pending mutations.
+     */
+    clear(): Promise<void>;
+}
+
+/**
+ * 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;
+
+/**
+ * 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, type CustomConflictResolver, type GqlRecordChangedEvent, type GqlSyncDeltaItem, type GqlSyncDeltaResult, type GqlSyncPushResultItem, IndexedDBAdapter, MemoryAdapter, OfflineQueue, type PendingMutation, type QueryOptions, type SessionChange, type SessionUser, type StorageAdapter, SyncBridge, type SyncBridgeOptions, type SyncClientConfig, SyncEngine, type SyncEngineEvent, type SyncEngineEventHandler, type SyncResult, type SyncableRecord, getUserColor, resolveConflict };