@decentrl/sdk 0.0.1

package/src/client.ts

@@ -0,0 +1,277 @@
+import { ContractManager } from './contract-manager.js';
+import { DirectTransport } from './direct-transport.js';
+import { DecentrlSDKError } from './errors.js';
+import { EventProcessor } from './event-processor.js';
+import { IdentityManager } from './identity-manager.js';
+import {
+	clearPersisted,
+	loadPersistedIdentity,
+	loadPersistedState,
+	persistIdentity,
+	persistState,
+} from './persistence.js';
+import { StateStore } from './state-store.js';
+import { SyncManager } from './sync-manager.js';
+import type { DecentrlTransport } from './transport.js';
+import type {
+	DecentrlAppConfig,
+	DecentrlClientConfig,
+	EventDefinitions,
+	EventEnvelope,
+	EventMeta,
+	InferState,
+	PaginatedResult,
+	PublishOptions,
+	QueryOptions,
+	StateDefinitions,
+	StateListener,
+	SyncOptions,
+} from './types.js';
+import type { ConnectionStatus } from './websocket-transport.js';
+
+export class DecentrlClient<
+	TEvents extends EventDefinitions,
+	TState extends StateDefinitions<TEvents>,
+> {
+	private stateStore: StateStore<InferState<TState>>;
+	private eventProcessor: EventProcessor<TEvents, TState>;
+	private syncManager: SyncManager<TEvents, TState>;
+	private transport: DecentrlTransport;
+	private unsubscribePersistState: (() => void) | null = null;
+	private unsubscribePersistIdentity: (() => void) | null = null;
+
+	readonly identity: IdentityManager;
+	readonly contracts: ContractManager;
+
+	constructor(
+		private appConfig: DecentrlAppConfig<TEvents, TState>,
+		private clientConfig: DecentrlClientConfig,
+	) {
+		// Build initial state from slice definitions
+		const initialState = {} as InferState<TState>;
+
+		for (const key of Object.keys(appConfig.state)) {
+			// TS can't statically index InferState<TState> during construction
+			(initialState as any)[key] = appConfig.state[key].initial;
+		}
+
+		// Restore persisted state if available
+		const persistOpts = clientConfig.persist;
+		let restoredState = initialState;
+
+		if (persistOpts) {
+			const saved = loadPersistedState<InferState<TState>>(persistOpts);
+
+			if (saved) {
+				// Merge: use saved values for slices that exist, fall back to initial for new slices
+				restoredState = { ...initialState, ...saved };
+			}
+		}
+
+		this.stateStore = new StateStore(restoredState);
+		this.identity = new IdentityManager();
+		this.contracts = new ContractManager();
+
+		// Set up transport (auto-create DirectTransport if none provided)
+		this.transport = clientConfig.transport ?? new DirectTransport();
+		this.identity.setTransport(this.transport);
+		this.contracts.setTransport(this.transport);
+
+		// Seed identity from transport (e.g. extension already has it after connect)
+		const transportIdentity = this.transport.getIdentity();
+
+		if (transportIdentity) {
+			try {
+				this.identity.load(transportIdentity);
+			} catch (err) {
+				console.debug('[Decentrl] Failed to seed identity from transport:', err);
+			}
+		}
+
+		this.eventProcessor = new EventProcessor(appConfig.events, appConfig.state, this.stateStore);
+
+		this.syncManager = new SyncManager(
+			this.eventProcessor,
+			this.contracts,
+			this.identity,
+			this.transport,
+		);
+
+		// Restore persisted identity
+		if (persistOpts) {
+			const savedIdentity = loadPersistedIdentity(persistOpts);
+
+			if (savedIdentity) {
+				try {
+					this.identity.load(savedIdentity);
+				} catch {
+					// Corrupted identity data — clear it
+					persistIdentity(persistOpts, null);
+				}
+			}
+
+			this.setupPersistence();
+		}
+	}
+
+	private setupPersistence(): void {
+		const persistOpts = this.clientConfig.persist;
+
+		if (!persistOpts) {
+			return;
+		}
+
+		// Auto-persist identity on changes
+		this.unsubscribePersistIdentity = this.identity.onChange((identity) => {
+			if (identity) {
+				persistIdentity(persistOpts, this.identity.serialize());
+			} else {
+				persistIdentity(persistOpts, null);
+			}
+		});
+
+		// Auto-persist state on changes (debounced)
+		let persistTimeout: ReturnType<typeof setTimeout> | null = null;
+		this.unsubscribePersistState = this.stateStore.subscribe((state) => {
+			if (persistTimeout) {
+				clearTimeout(persistTimeout);
+			}
+
+			persistTimeout = setTimeout(() => persistState(persistOpts, state), 100);
+		});
+	}
+
+	async publish<K extends string & keyof TEvents>(
+		eventType: K,
+		data: TEvents[K] extends { schema: infer S extends import('zod').ZodType }
+			? import('zod').infer<S>
+			: never,
+		options?: PublishOptions,
+	): Promise<void> {
+		// 1. Validate data against schema
+		this.eventProcessor.validate(eventType, data);
+
+		// 2. Build envelope
+		const meta: EventMeta = {
+			senderDid: this.identity.requireIdentity().did,
+			timestamp: Date.now(),
+			eventId: crypto.randomUUID(),
+			...(options?.ephemeral ? { ephemeral: true } : {}),
+		};
+		const envelope = this.eventProcessor.buildEnvelope(eventType, data, meta);
+
+		// 3. Compute tags
+		const tags = this.eventProcessor.computeTags(eventType, data);
+
+		try {
+			// 4. Publish via transport
+			await this.transport.publishEvent(envelope, {
+				tags,
+				recipient: options?.recipient,
+				ephemeral: options?.ephemeral,
+			});
+
+			// 5. Optimistic local state update
+			this.eventProcessor.processEvent(envelope);
+		} catch (error) {
+			throw new DecentrlSDKError(
+				`Failed to publish event "${eventType}": ${error instanceof Error ? error.message : String(error)}`,
+				'PUBLISH_FAILED',
+				{ eventType, data, error },
+			);
+		}
+	}
+
+	async query(options?: QueryOptions): Promise<PaginatedResult<EventEnvelope>> {
+		if (!this.transport.queryEvents) {
+			throw new DecentrlSDKError('Transport does not support queryEvents', 'QUERY_NOT_SUPPORTED');
+		}
+
+		try {
+			return await this.transport.queryEvents(options);
+		} catch (error) {
+			if (error instanceof DecentrlSDKError) {
+				throw error;
+			}
+
+			throw new DecentrlSDKError(
+				`Failed to query events: ${error instanceof Error ? error.message : String(error)}`,
+				'QUERY_FAILED',
+				{ options, error },
+			);
+		}
+	}
+
+	onEvent(listener: (envelope: EventEnvelope) => void): () => void {
+		return this.eventProcessor.onEvent(listener);
+	}
+
+	async queryAndProcess(options?: QueryOptions): Promise<{ processed: number; total: number }> {
+		const result = await this.query(options);
+		const processed = this.eventProcessor.processBatch(result.data);
+
+		return { processed, total: result.pagination.total };
+	}
+
+	getState = (): InferState<TState> => {
+		return this.stateStore.getState();
+	};
+
+	subscribe = (listener: StateListener<InferState<TState>>): (() => void) => {
+		return this.stateStore.subscribe(listener);
+	};
+
+	startSync(options?: SyncOptions): void {
+		this.syncManager.start(options);
+	}
+
+	stopSync(): void {
+		this.syncManager.stop();
+	}
+
+	async sync(): Promise<void> {
+		await this.syncManager.tick();
+	}
+
+	getConnectionStatus = (): ConnectionStatus => {
+		return this.syncManager.getConnectionStatus();
+	};
+
+	onConnectionStatusChange = (listener: (status: ConnectionStatus) => void): (() => void) => {
+		return this.syncManager.onConnectionStatusChange(listener);
+	};
+
+	reset(): void {
+		this.syncManager.stop();
+		this.identity.reset();
+		this.contracts.reset();
+		this.eventProcessor.reset();
+
+		if (this.unsubscribePersistState) {
+			this.unsubscribePersistState();
+			this.unsubscribePersistState = null;
+		}
+
+		if (this.unsubscribePersistIdentity) {
+			this.unsubscribePersistIdentity();
+			this.unsubscribePersistIdentity = null;
+		}
+
+		// Rebuild initial state
+		const initialState = {} as InferState<TState>;
+
+		for (const key of Object.keys(this.appConfig.state)) {
+			(initialState as any)[key] = this.appConfig.state[key].initial;
+		}
+
+		this.stateStore.reset(initialState);
+
+		// Clear persisted data
+		if (this.clientConfig.persist) {
+			clearPersisted(this.clientConfig.persist);
+		}
+
+		// Re-subscribe persistence listeners
+		this.setupPersistence();
+	}
+}

package/src/contract-manager.test.ts

@@ -0,0 +1,207 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { ContractManager } from './contract-manager.js';
+import { createMockTransport, makeContract } from './test-helpers.js';
+
+describe('ContractManager', () => {
+	let manager: ContractManager;
+
+	beforeEach(() => {
+		manager = new ContractManager();
+	});
+
+	describe('getContractByDid', () => {
+		it('returns undefined when no contracts exist', () => {
+			expect(manager.getContractByDid('did:decentrl:bob')).toBeUndefined();
+		});
+
+		it('returns the contract for a given DID', async () => {
+			const contract = makeContract({
+				participantDid: 'did:decentrl:bob',
+				expiresAt: Math.floor(Date.now() / 1000) + 3600,
+				timestamp: Math.floor(Date.now() / 1000),
+			});
+
+			const transport = createMockTransport({
+				refreshContracts: vi.fn(async () => [contract]),
+			});
+
+			manager.setTransport(transport);
+			await manager.refresh();
+
+			const result = manager.getContractByDid('did:decentrl:bob');
+			expect(result).toBeDefined();
+			expect(result!.participantDid).toBe('did:decentrl:bob');
+		});
+
+		it('prefers the contract with the latest expires_at', async () => {
+			const now = Math.floor(Date.now() / 1000);
+
+			const oldContract = makeContract({
+				id: 'old',
+				participantDid: 'did:decentrl:bob',
+				expiresAt: now + 3600,
+				timestamp: now,
+			});
+
+			const newContract = makeContract({
+				id: 'new',
+				participantDid: 'did:decentrl:bob',
+				expiresAt: now + 7200,
+				timestamp: now + 100,
+			});
+
+			const transport = createMockTransport({
+				refreshContracts: vi.fn(async () => [oldContract, newContract]),
+			});
+
+			manager.setTransport(transport);
+			await manager.refresh();
+
+			const result = manager.getContractByDid('did:decentrl:bob');
+			expect(result!.id).toBe('new');
+		});
+	});
+
+	describe('onChange', () => {
+		it('fires listener on refresh', async () => {
+			const listener = vi.fn();
+			manager.onChange(listener);
+
+			const transport = createMockTransport({
+				refreshContracts: vi.fn(async () => []),
+			});
+			manager.setTransport(transport);
+
+			await manager.refresh();
+
+			expect(listener).toHaveBeenCalled();
+		});
+
+		it('returns unsubscribe function', async () => {
+			const listener = vi.fn();
+			const unsub = manager.onChange(listener);
+			unsub();
+
+			const transport = createMockTransport({
+				refreshContracts: vi.fn(async () => []),
+			});
+			manager.setTransport(transport);
+
+			await manager.refresh();
+
+			expect(listener).not.toHaveBeenCalled();
+		});
+	});
+
+	describe('processAutoRenewals (with transport)', () => {
+		it('delegates to transport when available', async () => {
+			const transport = createMockTransport();
+			manager.setTransport(transport);
+
+			await manager.processAutoRenewals(0.3);
+
+			expect(transport.processAutoRenewals).toHaveBeenCalledWith(0.3);
+		});
+
+		it('calls refresh after transport auto-renewal', async () => {
+			const contract = makeContract({
+				participantDid: 'did:decentrl:bob',
+				expiresAt: Math.floor(Date.now() / 1000) + 3600,
+				timestamp: Math.floor(Date.now() / 1000),
+			});
+
+			const transport = createMockTransport({
+				refreshContracts: vi.fn(async () => [contract]),
+			});
+			manager.setTransport(transport);
+
+			await manager.processAutoRenewals();
+
+			expect(transport.refreshContracts).toHaveBeenCalled();
+		});
+	});
+
+	describe('processContractCleanup (with transport)', () => {
+		it('delegates to transport when available', async () => {
+			const transport = createMockTransport();
+			manager.setTransport(transport);
+
+			await manager.processContractCleanup();
+
+			expect(transport.processContractCleanup).toHaveBeenCalled();
+		});
+
+		it('calls refresh after transport cleanup', async () => {
+			const transport = createMockTransport();
+			manager.setTransport(transport);
+
+			await manager.processContractCleanup();
+
+			expect(transport.refreshContracts).toHaveBeenCalled();
+		});
+	});
+
+	describe('reset', () => {
+		it('clears all contracts and state', async () => {
+			const now = Math.floor(Date.now() / 1000);
+			const contract = makeContract({
+				participantDid: 'did:decentrl:bob',
+				expiresAt: now + 3600,
+				timestamp: now,
+			});
+
+			const transport = createMockTransport({
+				refreshContracts: vi.fn(async () => [contract]),
+			});
+			manager.setTransport(transport);
+			await manager.refresh();
+
+			expect(manager.getActiveContracts()).toHaveLength(1);
+
+			manager.reset();
+
+			expect(manager.getActiveContracts()).toHaveLength(0);
+		});
+
+		it('fires onChange listeners', () => {
+			const listener = vi.fn();
+			manager.onChange(listener);
+
+			manager.reset();
+
+			expect(listener).toHaveBeenCalled();
+		});
+	});
+
+	describe('getActiveContracts', () => {
+		it('returns only active contracts', async () => {
+			const now = Math.floor(Date.now() / 1000);
+
+			const active = makeContract({
+				id: 'active',
+				participantDid: 'did:decentrl:bob',
+				expiresAt: now + 3600,
+				timestamp: now,
+				status: 'active',
+			});
+
+			const expired = makeContract({
+				id: 'expired',
+				participantDid: 'did:decentrl:carol',
+				expiresAt: now - 100,
+				timestamp: now - 7200,
+				status: 'expired',
+			});
+
+			const transport = createMockTransport({
+				refreshContracts: vi.fn(async () => [active, expired]),
+			});
+			manager.setTransport(transport);
+			await manager.refresh();
+
+			const activeContracts = manager.getActiveContracts();
+			expect(activeContracts).toHaveLength(1);
+			expect(activeContracts[0].id).toBe('active');
+		});
+	});
+});

package/src/contract-manager.ts

@@ -0,0 +1,130 @@
+import { DecentrlSDKError } from './errors.js';
+import type { DecentrlTransport } from './transport.js';
+import type { PendingContractRequest, StoredSignedContract } from './types.js';
+
+type ContractChangeListener = () => void;
+
+export class ContractManager {
+	private contracts = new Map<string, StoredSignedContract>();
+	private listeners = new Set<ContractChangeListener>();
+	private cachedActiveContracts: StoredSignedContract[] = [];
+	private transport: DecentrlTransport | null = null;
+
+	setTransport(transport: DecentrlTransport): void {
+		this.transport = transport;
+	}
+
+	onChange(listener: ContractChangeListener): () => void {
+		this.listeners.add(listener);
+
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+
+	private notify(): void {
+		this.cachedActiveContracts = Array.from(this.contracts.values()).filter(
+			(c) => c.status === 'active',
+		);
+
+		for (const listener of this.listeners) {
+			listener();
+		}
+	}
+
+	async request(recipientDid: string, expiresIn = 3600 * 24): Promise<void> {
+		if (!this.transport) {
+			throw new DecentrlSDKError('Transport not set', 'NO_TRANSPORT');
+		}
+
+		await this.transport.requestContract(recipientDid, expiresIn);
+	}
+
+	async getPending(): Promise<PendingContractRequest[]> {
+		if (!this.transport) {
+			throw new DecentrlSDKError('Transport not set', 'NO_TRANSPORT');
+		}
+
+		return this.transport.getPendingContracts();
+	}
+
+	async accept(
+		pendingId: string,
+		encryptedPayload: string,
+		requestorEphemeralPublicKey: string,
+	): Promise<void> {
+		if (!this.transport) {
+			throw new DecentrlSDKError('Transport not set', 'NO_TRANSPORT');
+		}
+
+		await this.transport.acceptContract(pendingId, encryptedPayload, requestorEphemeralPublicKey);
+		await this.refresh();
+	}
+
+	async refresh(): Promise<void> {
+		if (!this.transport) {
+			throw new DecentrlSDKError('Transport not set', 'NO_TRANSPORT');
+		}
+
+		const contracts = await this.transport.refreshContracts();
+		this.contracts.clear();
+
+		for (const contract of contracts) {
+			this.contracts.set(contract.id, contract);
+		}
+
+		this.notify();
+	}
+
+	getActiveContracts(): StoredSignedContract[] {
+		return this.cachedActiveContracts;
+	}
+
+	getContractByDid(did: string): StoredSignedContract | undefined {
+		let best: StoredSignedContract | undefined;
+
+		for (const contract of this.contracts.values()) {
+			if (contract.participantDid !== did) {
+				continue;
+			}
+
+			if (!best) {
+				best = contract;
+				continue;
+			}
+
+			const bestExpiry = best.signedCommunicationContract?.communication_contract?.expires_at ?? 0;
+			const currExpiry =
+				contract.signedCommunicationContract?.communication_contract?.expires_at ?? 0;
+
+			if (currExpiry > bestExpiry) {
+				best = contract;
+			}
+		}
+
+		return best;
+	}
+
+	async processAutoRenewals(threshold = 0.2): Promise<void> {
+		if (!this.transport?.processAutoRenewals) {
+			return;
+		}
+
+		await this.transport.processAutoRenewals(threshold);
+		await this.refresh();
+	}
+
+	async processContractCleanup(): Promise<void> {
+		if (!this.transport?.processContractCleanup) {
+			return;
+		}
+
+		await this.transport.processContractCleanup();
+		await this.refresh();
+	}
+
+	reset(): void {
+		this.contracts.clear();
+		this.notify();
+	}
+}

package/src/define-app.ts

@@ -0,0 +1,25 @@
+import { DecentrlClient } from './client.js';
+import type {
+	DecentrlAppConfig,
+	DecentrlClientConfig,
+	EventDefinitions,
+	StateDefinitions,
+} from './types.js';
+
+export interface DecentrlApp<
+	TEvents extends EventDefinitions,
+	TState extends StateDefinitions<TEvents>,
+> {
+	config: DecentrlAppConfig<TEvents, TState>;
+	createClient(clientConfig: DecentrlClientConfig): DecentrlClient<TEvents, TState>;
+}
+
+export function defineDecentrlApp<
+	TEvents extends EventDefinitions,
+	TState extends StateDefinitions<TEvents>,
+>(config: DecentrlAppConfig<TEvents, TState>): DecentrlApp<TEvents, TState> {
+	return {
+		config,
+		createClient: (clientConfig: DecentrlClientConfig) => new DecentrlClient(config, clientConfig),
+	};
+}