@decentrl/sdk 0.0.1

package/src/sync-manager.test.ts

@@ -0,0 +1,414 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { SyncManager } from './sync-manager.js';
+import {
+	createMockContractManager,
+	createMockEventProcessor,
+	createMockIdentityManager,
+	createMockTransport,
+} from './test-helpers.js';
+import type { EventEnvelope } from './types.js';
+
+describe('SyncManager', () => {
+	let syncManager: SyncManager<any, any>;
+	let transport: ReturnType<typeof createMockTransport>;
+	let eventProcessor: ReturnType<typeof createMockEventProcessor>;
+	let contractManager: ReturnType<typeof createMockContractManager>;
+	let identityManager: ReturnType<typeof createMockIdentityManager>;
+
+	beforeEach(() => {
+		vi.useFakeTimers();
+		transport = createMockTransport();
+		eventProcessor = createMockEventProcessor();
+		contractManager = createMockContractManager();
+		identityManager = createMockIdentityManager();
+
+		syncManager = new SyncManager(
+			eventProcessor,
+			contractManager as any,
+			identityManager as any,
+			transport,
+		);
+	});
+
+	afterEach(() => {
+		syncManager.stop();
+		vi.useRealTimers();
+	});
+
+	describe('tick', () => {
+		it('processes pending events and refreshes contracts', async () => {
+			const events: EventEnvelope[] = [
+				{
+					type: 'test.event',
+					data: { foo: 'bar' },
+					meta: { senderDid: 'did:a', timestamp: 1, eventId: 'e1' },
+				},
+			];
+			(transport.processPendingEvents as any).mockResolvedValue(events);
+
+			await syncManager.tick();
+
+			expect(transport.processPendingEvents as any).toHaveBeenCalled();
+			expect(eventProcessor.processBatch).toHaveBeenCalledWith(events);
+			expect(contractManager.refresh).toHaveBeenCalled();
+		});
+
+		it('calls processAutoRenewals when autoRenew is enabled', async () => {
+			syncManager.start({
+				autoRenew: { enabled: true, threshold: 0.3 },
+				websocket: false,
+			});
+
+			// Flush the initial tick (microtask queue) without advancing timers infinitely
+			await vi.advanceTimersByTimeAsync(0);
+
+			expect(contractManager.processAutoRenewals).toHaveBeenCalledWith(0.3);
+		});
+
+		it('skips processAutoRenewals when autoRenew is disabled', async () => {
+			await syncManager.tick();
+
+			expect(contractManager.processAutoRenewals).not.toHaveBeenCalled();
+		});
+
+		it('always calls processContractCleanup', async () => {
+			await syncManager.tick();
+
+			expect(contractManager.processContractCleanup).toHaveBeenCalled();
+		});
+
+		it('isolates cleanup errors from the sync loop', async () => {
+			(contractManager.processContractCleanup as any).mockRejectedValue(new Error('cleanup boom'));
+
+			const onError = vi.fn();
+			await syncManager.tick(onError);
+
+			// The error should NOT propagate to onError — it's caught internally
+			expect(onError).not.toHaveBeenCalled();
+			expect(contractManager.processContractCleanup).toHaveBeenCalled();
+		});
+
+		it('calls onError when event processing fails', async () => {
+			(transport.processPendingEvents as any).mockRejectedValue(new Error('network error'));
+
+			const onError = vi.fn();
+			await syncManager.tick(onError);
+
+			expect(onError).toHaveBeenCalledWith(expect.any(Error));
+		});
+
+		it('prevents concurrent ticks', async () => {
+			let resolveFirst: () => void;
+			const blockingPromise = new Promise<EventEnvelope[]>((resolve) => {
+				resolveFirst = () => resolve([]);
+			});
+			(transport.processPendingEvents as any).mockReturnValue(blockingPromise);
+
+			const tick1 = syncManager.tick();
+			const tick2 = syncManager.tick();
+
+			resolveFirst!();
+			await tick1;
+			await tick2;
+
+			// Should only have been called once due to isSyncing guard
+			expect(transport.processPendingEvents as any).toHaveBeenCalledTimes(1);
+		});
+	});
+
+	describe('start / stop', () => {
+		it('starts polling and stops cleanly', async () => {
+			syncManager.start({ intervalMs: 1000, websocket: false });
+
+			expect(syncManager.isRunning).toBe(true);
+
+			syncManager.stop();
+
+			expect(syncManager.isRunning).toBe(false);
+		});
+	});
+
+	describe('transport mode', () => {
+		it('uses transport for event processing', async () => {
+			const transportEvents: EventEnvelope[] = [
+				{
+					type: 'transport.event',
+					data: {},
+					meta: { senderDid: 'did:b', timestamp: 2, eventId: 'e2' },
+				},
+			];
+
+			(transport.processPendingEvents as any).mockResolvedValue(transportEvents);
+
+			await syncManager.tick();
+
+			expect(transport.processPendingEvents).toHaveBeenCalled();
+			expect(eventProcessor.processBatch).toHaveBeenCalledWith(transportEvents);
+		});
+	});
+
+	describe('processUntaggedEvents', () => {
+		const withTransport = (mockTransport: any) =>
+			new SyncManager(
+				eventProcessor,
+				contractManager as any,
+				identityManager as any,
+				mockTransport,
+			);
+
+		it('enriches unprocessed events with tags via transport on tick', async () => {
+			const untaggedEvents: EventEnvelope[] = [
+				{
+					type: 'chat.message',
+					data: { chatId: 'c1' },
+					meta: { senderDid: 'did:b', timestamp: 1, eventId: 'e1' },
+				},
+			];
+
+			const mockTransport = {
+				processPendingEvents: vi.fn(async () => [
+					{
+						type: 'chat.message',
+						data: { chatId: 'c1' },
+						meta: { senderDid: 'did:b', timestamp: 1, eventId: 'e1' },
+					},
+				]),
+				queryUnprocessedEvents: vi.fn(async () => ({
+					data: untaggedEvents.map((e) => ({ ...e, _mediatorEventId: 'med-1' })),
+					pagination: { page: 0, pageSize: 50, total: 1 },
+				})),
+				updateEventTags: vi.fn(async () => {}),
+			};
+			const sm = withTransport(mockTransport);
+
+			await sm.tick();
+
+			expect(mockTransport.queryUnprocessedEvents).toHaveBeenCalled();
+			expect(mockTransport.updateEventTags).toHaveBeenCalledWith([
+				{ eventId: 'med-1', tags: ['tag:chat.message'] },
+			]);
+			sm.stop();
+		});
+
+		it('skips tag update when no events are processed', async () => {
+			const mockTransport = {
+				processPendingEvents: vi.fn(async () => []),
+				queryUnprocessedEvents: vi.fn(async () => ({
+					data: [],
+					pagination: { page: 0, pageSize: 50, total: 0 },
+				})),
+				updateEventTags: vi.fn(async () => {}),
+			};
+			const sm = withTransport(mockTransport);
+
+			await sm.tick();
+
+			// No events processed → processUntaggedEvents not called
+			expect(mockTransport.queryUnprocessedEvents).not.toHaveBeenCalled();
+			sm.stop();
+		});
+
+		it('uses _mediatorEventId when available, falls back to meta.eventId', async () => {
+			const mockTransport = {
+				processPendingEvents: vi.fn(async () => [
+					{ type: 'a', data: {}, meta: { senderDid: 'did:b', timestamp: 1, eventId: 'e1' } },
+				]),
+				queryUnprocessedEvents: vi.fn(async () => ({
+					data: [
+						// Event with _mediatorEventId
+						{
+							type: 'a',
+							data: {},
+							meta: { senderDid: 'did:b', timestamp: 1, eventId: 'client-uuid' },
+							_mediatorEventId: 'mediator-cuid',
+						},
+						// Event without _mediatorEventId
+						{
+							type: 'b',
+							data: {},
+							meta: { senderDid: 'did:c', timestamp: 2, eventId: 'client-uuid-2' },
+						},
+					],
+					pagination: { page: 0, pageSize: 50, total: 2 },
+				})),
+				updateEventTags: vi.fn(async () => {}),
+			};
+			const sm = withTransport(mockTransport);
+
+			await sm.tick();
+
+			expect(mockTransport.updateEventTags).toHaveBeenCalledWith([
+				{ eventId: 'mediator-cuid', tags: ['tag:a'] },
+				{ eventId: 'client-uuid-2', tags: ['tag:b'] },
+			]);
+			sm.stop();
+		});
+
+		it('skips ephemeral events for tag updates', async () => {
+			const mockTransport = {
+				processPendingEvents: vi.fn(async () => [
+					{ type: 'a', data: {}, meta: { senderDid: 'did:b', timestamp: 1, eventId: 'e1' } },
+				]),
+				queryUnprocessedEvents: vi.fn(async () => ({
+					data: [
+						{
+							type: 'a',
+							data: {},
+							meta: { senderDid: 'did:b', timestamp: 1, eventId: 'e1', ephemeral: true },
+							_mediatorEventId: 'med-1',
+						},
+					],
+					pagination: { page: 0, pageSize: 50, total: 1 },
+				})),
+				updateEventTags: vi.fn(async () => {}),
+			};
+			const sm = withTransport(mockTransport);
+
+			await sm.tick();
+
+			// Ephemeral events are filtered out — no tag updates
+			expect(mockTransport.updateEventTags).not.toHaveBeenCalled();
+			sm.stop();
+		});
+
+		it('paginates through unprocessed events', async () => {
+			const page0Events = Array.from({ length: 50 }, (_, i) => ({
+				type: 'a',
+				data: {},
+				meta: { senderDid: 'did:b', timestamp: i, eventId: `e${i}` },
+				_mediatorEventId: `med-${i}`,
+			}));
+
+			const page1Events = [
+				{
+					type: 'a',
+					data: {},
+					meta: { senderDid: 'did:b', timestamp: 50, eventId: 'e50' },
+					_mediatorEventId: 'med-50',
+				},
+			];
+
+			const mockTransport = {
+				processPendingEvents: vi.fn(async () => [
+					{ type: 'a', data: {}, meta: { senderDid: 'did:b', timestamp: 1, eventId: 'trigger' } },
+				]),
+				queryUnprocessedEvents: vi
+					.fn()
+					.mockResolvedValueOnce({
+						data: page0Events,
+						pagination: { page: 0, pageSize: 50, total: 51 },
+					})
+					.mockResolvedValueOnce({
+						data: page1Events,
+						pagination: { page: 1, pageSize: 50, total: 51 },
+					}),
+				updateEventTags: vi.fn(async () => {}),
+			};
+			const sm = withTransport(mockTransport);
+
+			await sm.tick();
+
+			expect(mockTransport.queryUnprocessedEvents).toHaveBeenCalledTimes(2);
+			expect(mockTransport.updateEventTags).toHaveBeenCalledTimes(2);
+			sm.stop();
+		});
+	});
+
+	describe('push handler', () => {
+		const withTransport = (mockTransport: any) =>
+			new SyncManager(
+				eventProcessor,
+				contractManager as any,
+				identityManager as any,
+				mockTransport,
+			);
+
+		it('triggers processUntaggedEvents for non-ephemeral pushed events', async () => {
+			let pushCallback: (events: EventEnvelope[]) => void;
+
+			const mockTransport = {
+				onEvents: vi.fn((cb: (events: EventEnvelope[]) => void) => {
+					pushCallback = cb;
+
+					return () => {};
+				}),
+				queryUnprocessedEvents: vi.fn(async () => ({
+					data: [
+						{
+							type: 'chat.message',
+							data: {},
+							meta: { senderDid: 'did:b', timestamp: 1, eventId: 'e1' },
+							_mediatorEventId: 'med-1',
+						},
+					],
+					pagination: { page: 0, pageSize: 50, total: 1 },
+				})),
+				updateEventTags: vi.fn(async () => {}),
+				processPendingEvents: vi.fn(async () => []),
+			};
+			const sm = withTransport(mockTransport);
+
+			sm.start({ websocket: false });
+
+			// Wait for initial tick
+			await vi.advanceTimersByTimeAsync(0);
+
+			// Reset to isolate push handler behavior
+			mockTransport.queryUnprocessedEvents.mockClear();
+			mockTransport.updateEventTags.mockClear();
+
+			// Simulate push
+			pushCallback!([
+				{
+					type: 'chat.message',
+					data: {},
+					meta: { senderDid: 'did:b', timestamp: 2, eventId: 'e2' },
+				},
+			]);
+
+			// processUntaggedEvents is async, give it a tick
+			await vi.advanceTimersByTimeAsync(0);
+
+			expect(mockTransport.queryUnprocessedEvents).toHaveBeenCalled();
+			sm.stop();
+		});
+
+		it('does NOT trigger processUntaggedEvents for ephemeral-only pushes', async () => {
+			let pushCallback: (events: EventEnvelope[]) => void;
+
+			const mockTransport = {
+				onEvents: vi.fn((cb: (events: EventEnvelope[]) => void) => {
+					pushCallback = cb;
+
+					return () => {};
+				}),
+				queryUnprocessedEvents: vi.fn(async () => ({
+					data: [],
+					pagination: { page: 0, pageSize: 50, total: 0 },
+				})),
+				updateEventTags: vi.fn(async () => {}),
+				processPendingEvents: vi.fn(async () => []),
+			};
+			const sm = withTransport(mockTransport);
+
+			sm.start({ websocket: false });
+			await vi.advanceTimersByTimeAsync(0);
+
+			mockTransport.queryUnprocessedEvents.mockClear();
+
+			// Push ephemeral-only events
+			pushCallback!([
+				{
+					type: 'typing',
+					data: {},
+					meta: { senderDid: 'did:b', timestamp: 2, eventId: 'e2', ephemeral: true },
+				},
+			]);
+
+			await vi.advanceTimersByTimeAsync(0);
+
+			expect(mockTransport.queryUnprocessedEvents).not.toHaveBeenCalled();
+			sm.stop();
+		});
+	});
+});

package/src/sync-manager.ts

@@ -0,0 +1,308 @@
+import type { ContractManager } from './contract-manager.js';
+import type { EventProcessor } from './event-processor.js';
+import type { IdentityManager } from './identity-manager.js';
+import type { DecentrlTransport } from './transport.js';
+import type { EventDefinitions, EventEnvelope, StateDefinitions, SyncOptions } from './types.js';
+import { type ConnectionStatus, deriveWsUrl, WebSocketTransport } from './websocket-transport.js';
+
+type StatusListener = (status: ConnectionStatus) => void;
+
+export class SyncManager<
+	TEvents extends EventDefinitions,
+	TState extends StateDefinitions<TEvents>,
+> {
+	private intervalId: ReturnType<typeof setInterval> | null = null;
+	private isSyncing = false;
+	private wsTransport: WebSocketTransport | null = null;
+	private connectionStatus: ConnectionStatus = 'disconnected';
+	private statusListeners = new Set<StatusListener>();
+	private unsubscribePush: (() => void) | null = null;
+	private unsubscribeContractsPush: (() => void) | null = null;
+	private currentOptions: SyncOptions = {};
+
+	constructor(
+		private eventProcessor: EventProcessor<TEvents, TState>,
+		private contractManager: ContractManager,
+		private identityManager: IdentityManager,
+		private transport: DecentrlTransport,
+	) {}
+
+	start(options: SyncOptions = {}): void {
+		this.stop();
+		this.currentOptions = options;
+
+		// If transport supports push-based events, subscribe
+		if (this.transport.onEvents) {
+			this.unsubscribePush = this.transport.onEvents((events) => {
+				try {
+					this.eventProcessor.processBatch(events);
+				} catch (err) {
+					console.error('[Decentrl] Failed to process pushed events:', err);
+				}
+
+				// Tag enrichment for non-ephemeral pushed events
+				if (events.some((e) => !e.meta.ephemeral)) {
+					this.processUntaggedEvents().catch((err) =>
+						console.debug('[Decentrl] Failed to process untagged events:', err),
+					);
+				}
+			});
+
+			if (this.transport.onContractsChanged) {
+				this.unsubscribeContractsPush = this.transport.onContractsChanged(() => {
+					this.contractManager.refresh();
+				});
+			}
+
+			// Still do an initial sync tick + slower polling for contracts
+			this.tick(options.onError);
+			const intervalMs = options.fallbackIntervalMs ?? 30_000;
+			this.intervalId = setInterval(() => {
+				this.tick(options.onError);
+			}, intervalMs);
+
+			// Load stored events from mediator to catch up on offline period
+			this.loadStoredEvents().catch((err) =>
+				console.debug('[Decentrl] loadStoredEvents() failed:', err),
+			);
+			// Process any events that haven't been tagged by the app yet
+			this.processUntaggedEvents().catch((err) =>
+				console.debug('[Decentrl] processUntaggedEvents() failed:', err),
+			);
+
+			return;
+		}
+
+		const intervalMs = options.intervalMs ?? 3000;
+
+		// Run immediately
+		this.tick(options.onError);
+
+		this.intervalId = setInterval(() => {
+			this.tick(options.onError);
+		}, intervalMs);
+
+		// Start WebSocket if available and enabled
+		const useWebSocket = options.websocket !== false;
+
+		if (useWebSocket && typeof globalThis.WebSocket !== 'undefined') {
+			this.startWebSocket(options);
+		}
+	}
+
+	stop(): void {
+		if (this.intervalId !== null) {
+			clearInterval(this.intervalId);
+			this.intervalId = null;
+		}
+
+		if (this.wsTransport) {
+			this.wsTransport.disconnect();
+			this.wsTransport = null;
+		}
+
+		if (this.unsubscribePush) {
+			this.unsubscribePush();
+			this.unsubscribePush = null;
+		}
+
+		if (this.unsubscribeContractsPush) {
+			this.unsubscribeContractsPush();
+			this.unsubscribeContractsPush = null;
+		}
+	}
+
+	async tick(onError?: (error: unknown) => void): Promise<void> {
+		if (this.isSyncing) {
+			return;
+		}
+
+		this.isSyncing = true;
+
+		try {
+			const processedEvents = await this.transport.processPendingEvents();
+			this.eventProcessor.processBatch(processedEvents);
+
+			// Enrich any unprocessed events with app-computed tags
+			if (processedEvents.length > 0) {
+				await this.processUntaggedEvents();
+			}
+
+			// Refresh contracts
+			await this.contractManager.refresh();
+
+			// Auto-renew expiring contracts
+			const autoRenew = this.currentOptions.autoRenew;
+
+			if (autoRenew?.enabled) {
+				await this.contractManager.processAutoRenewals(autoRenew.threshold);
+			}
+
+			// Clean up old superseded contracts
+			try {
+				await this.contractManager.processContractCleanup();
+			} catch (err) {
+				console.error('[Decentrl] Contract cleanup failed:', err);
+			}
+		} catch (error) {
+			if (onError) {
+				onError(error);
+			}
+		} finally {
+			this.isSyncing = false;
+		}
+	}
+
+	getConnectionStatus = (): ConnectionStatus => {
+		return this.connectionStatus;
+	};
+
+	onConnectionStatusChange = (listener: StatusListener): (() => void) => {
+		this.statusListeners.add(listener);
+
+		return () => {
+			this.statusListeners.delete(listener);
+		};
+	};
+
+	get isRunning(): boolean {
+		return this.intervalId !== null;
+	}
+
+	private async loadStoredEvents(): Promise<void> {
+		if (!this.transport.queryEvents) {
+			return;
+		}
+
+		try {
+			let page = 0;
+			const pageSize = 50;
+
+			while (true) {
+				const result = await this.transport.queryEvents({
+					pagination: { page, pageSize },
+				});
+
+				if (result.data.length > 0) {
+					this.eventProcessor.processBatch(result.data as EventEnvelope[]);
+				}
+
+				if ((page + 1) * pageSize >= result.pagination.total) {
+					break;
+				}
+
+				page++;
+			}
+		} catch (err) {
+			console.debug('[Decentrl] loadStoredEvents() failed:', err);
+		}
+	}
+
+	private async processUntaggedEvents(): Promise<void> {
+		if (!this.transport.queryUnprocessedEvents) {
+			return;
+		}
+
+		if (!this.transport.updateEventTags) {
+			return;
+		}
+
+		try {
+			let page = 0;
+			const pageSize = 50;
+
+			while (true) {
+				const result = await this.transport.queryUnprocessedEvents({ page, pageSize });
+
+				if (result.data.length === 0) {
+					break;
+				}
+
+				this.eventProcessor.processBatch(result.data as EventEnvelope[]);
+
+				const tagUpdates = result.data
+					.filter((e) => !e.meta.ephemeral)
+					.map((e) => ({
+						eventId: e._mediatorEventId ?? e.meta.eventId,
+						tags: this.eventProcessor.computeTagsSafe(e.type, e.data),
+					}));
+
+				if (tagUpdates.length > 0) {
+					await this.transport.updateEventTags(tagUpdates);
+				}
+
+				if ((page + 1) * pageSize >= result.pagination.total) {
+					break;
+				}
+
+				page++;
+			}
+		} catch (err) {
+			console.debug('[Decentrl] processUntaggedEvents failed:', err);
+		}
+	}
+
+	private startWebSocket(options: SyncOptions): void {
+		const identity = this.identityManager.getIdentity();
+
+		if (!identity) {
+			return;
+		}
+
+		const wsUrl = deriveWsUrl(identity.mediatorEndpoint);
+
+		this.wsTransport = new WebSocketTransport(
+			() => {
+				const id = this.identityManager.getIdentity();
+
+				return id ? { did: id.did, keys: id.keys } : null;
+			},
+			() => wsUrl,
+			{
+				onPendingEvents: async (events) => {
+					try {
+						if (this.transport.processPreFetchedPendingEvents) {
+							const processed = await this.transport.processPreFetchedPendingEvents(events);
+							this.eventProcessor.processBatch(processed);
+						}
+					} catch (error) {
+						options.onError?.(error);
+					}
+				},
+				onContractsUpdated: async () => {
+					try {
+						await this.contractManager.refresh();
+					} catch (error) {
+						options.onError?.(error);
+					}
+				},
+				onStatusChange: (status) => {
+					this.connectionStatus = status;
+
+					// Adjust polling interval based on WS connection
+					if (this.intervalId !== null) {
+						clearInterval(this.intervalId);
+						const intervalMs =
+							status === 'connected'
+								? (options.fallbackIntervalMs ?? 30_000)
+								: (options.intervalMs ?? 3000);
+						this.intervalId = setInterval(() => {
+							this.tick(options.onError);
+						}, intervalMs);
+
+						// Trigger immediate catch-up tick when WS connects
+						if (status === 'connected') {
+							this.tick(options.onError);
+						}
+					}
+
+					for (const listener of this.statusListeners) {
+						listener(status);
+					}
+				},
+			},
+		);
+
+		this.wsTransport.connect();
+	}
+}