@framers/sql-storage-adapter 0.4.2 → 0.5.1

package/dist/features/sync/devices/deviceManager.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Device Registry and Presence Management.
+ *
+ * Manages device registration, presence tracking, and peer discovery
+ * for cross-platform sync.
+ *
+ * @packageDocumentation
+ */
+import type { StorageAdapter } from '../../../core/contracts';
+import type { VectorClock } from '../protocol/vectorClock';
+/**
+ * Device types supported for sync.
+ */
+export type DeviceType = 'electron' | 'capacitor' | 'browser' | 'server' | 'unknown';
+/**
+ * Device presence status.
+ */
+export type PresenceStatus = 'online' | 'away' | 'offline' | 'syncing';
+/**
+ * Information about a registered device.
+ */
+export interface DeviceInfo {
+    /** Unique device identifier */
+    deviceId: string;
+    /** Device type/platform */
+    deviceType: DeviceType;
+    /** Human-readable device name */
+    deviceName: string;
+    /** Device's current vector clock */
+    vectorClock: VectorClock;
+    /** When the device was first registered */
+    createdAt: number;
+    /** When the device was last seen */
+    lastSeenAt: number;
+    /** Current presence status */
+    presence: PresenceStatus;
+    /** Device capabilities */
+    capabilities: DeviceCapabilities;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Capabilities a device supports.
+ */
+export interface DeviceCapabilities {
+    /** Supports real-time sync */
+    realTimeSync: boolean;
+    /** Supports background sync */
+    backgroundSync: boolean;
+    /** Supports push notifications */
+    pushNotifications: boolean;
+    /** Supports offline mode */
+    offlineMode: boolean;
+    /** Maximum batch size */
+    maxBatchSize: number;
+}
+/**
+ * Device registration options.
+ */
+export interface DeviceRegistrationOptions {
+    /** Device name (auto-generated if not provided) */
+    name?: string;
+    /** Device type (auto-detected if not provided) */
+    type?: DeviceType;
+    /** Device capabilities */
+    capabilities?: Partial<DeviceCapabilities>;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Device presence event.
+ */
+export interface PresenceEvent {
+    deviceId: string;
+    previousStatus: PresenceStatus;
+    currentStatus: PresenceStatus;
+    timestamp: number;
+}
+/**
+ * Device manager event types.
+ */
+export type DeviceManagerEventType = 'deviceRegistered' | 'deviceUpdated' | 'deviceRemoved' | 'presenceChanged' | 'peerDiscovered' | 'peerLost';
+/**
+ * Device manager event payloads.
+ */
+export interface DeviceManagerEvents {
+    deviceRegistered: DeviceInfo;
+    deviceUpdated: {
+        device: DeviceInfo;
+        changes: Partial<DeviceInfo>;
+    };
+    deviceRemoved: {
+        deviceId: string;
+        reason: string;
+    };
+    presenceChanged: PresenceEvent;
+    peerDiscovered: DeviceInfo;
+    peerLost: {
+        deviceId: string;
+        lastSeenAt: number;
+    };
+}
+/**
+ * Device manager configuration.
+ */
+export interface DeviceManagerOptions {
+    /** Storage adapter for persisting device registry */
+    adapter: StorageAdapter;
+    /** Presence timeout in milliseconds (default: 60000) */
+    presenceTimeout?: number;
+    /** Heartbeat interval in milliseconds (default: 30000) */
+    heartbeatInterval?: number;
+    /** Auto-detect device info */
+    autoDetect?: boolean;
+    /** Initial device name */
+    deviceName?: string;
+}
+/**
+ * Device registry and presence manager.
+ *
+ * Manages device registration, presence tracking, and peer discovery
+ * across all connected devices in a sync cluster.
+ *
+ * @example
+ * ```typescript
+ * const manager = new DeviceManager({
+ *   adapter: db,
+ *   deviceName: 'MacBook Pro',
+ * });
+ *
+ * await manager.initialize();
+ *
+ * // Get current device
+ * const thisDevice = manager.getCurrentDevice();
+ *
+ * // Get all known peers
+ * const peers = await manager.getPeers();
+ *
+ * // Listen for presence changes
+ * manager.on('presenceChanged', (event) => {
+ *   console.log(`${event.deviceId} is now ${event.currentStatus}`);
+ * });
+ * ```
+ */
+export declare class DeviceManager {
+    private _adapter;
+    private _options;
+    private _currentDevice;
+    private _peers;
+    private _heartbeatTimer;
+    private _listeners;
+    private _initialized;
+    constructor(options: DeviceManagerOptions);
+    /**
+     * Initialize the device manager.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get the current device.
+     */
+    getCurrentDevice(): DeviceInfo | null;
+    /**
+     * Get all known peer devices.
+     */
+    getPeers(): Promise<DeviceInfo[]>;
+    /**
+     * Get online peers only.
+     */
+    getOnlinePeers(): Promise<DeviceInfo[]>;
+    /**
+     * Get a specific device by ID.
+     */
+    getDevice(deviceId: string): Promise<DeviceInfo | null>;
+    /**
+     * Update the current device's presence.
+     */
+    updatePresence(status: PresenceStatus): Promise<void>;
+    /**
+     * Update the current device's vector clock.
+     */
+    updateVectorClock(clock: VectorClock): Promise<void>;
+    /**
+     * Register or update a peer device.
+     */
+    registerPeer(peerInfo: DeviceInfo): Promise<void>;
+    /**
+     * Remove a device from the registry.
+     */
+    removeDevice(deviceId: string, reason?: string): Promise<void>;
+    /**
+     * Check for stale peers and update their presence.
+     */
+    checkStaleDevices(): Promise<void>;
+    /**
+     * Listen for device manager events.
+     */
+    on<T extends DeviceManagerEventType>(event: T, listener: (data: DeviceManagerEvents[T]) => void): () => void;
+    /**
+     * Dispose of the device manager.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Emit an event to listeners.
+     */
+    private _emit;
+    /**
+     * Ensure device tables exist.
+     */
+    private _ensureTables;
+    /**
+     * Initialize the current device.
+     */
+    private _initializeCurrentDevice;
+    /**
+     * Load stored device ID.
+     */
+    private _loadStoredDeviceId;
+    /**
+     * Store device ID for persistence.
+     */
+    private _storeDeviceId;
+    /**
+     * Load a device from the database.
+     */
+    private _loadDevice;
+    /**
+     * Save a device to the database.
+     */
+    private _saveDevice;
+    /**
+     * Load all peer devices.
+     */
+    private _loadPeers;
+    /**
+     * Start heartbeat timer.
+     */
+    private _startHeartbeat;
+}
+/**
+ * Create a device manager instance.
+ */
+export declare const createDeviceManager: (options: DeviceManagerOptions) => DeviceManager;
+//# sourceMappingURL=deviceManager.d.ts.map

package/dist/features/sync/devices/deviceManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deviceManager.d.ts","sourceRoot":"","sources":["../../../../src/features/sync/devices/deviceManager.ts"],"names":[],"mappings":"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"}