@decentrl/sdk 0.0.1

package/src/errors.ts

@@ -0,0 +1,23 @@
+export type DecentrlSDKErrorCode =
+	| 'IDENTITY_NOT_INITIALIZED'
+	| 'IDENTITY_ALREADY_EXISTS'
+	| 'CONTRACT_NOT_FOUND'
+	| 'SCHEMA_VALIDATION_FAILED'
+	| 'UNKNOWN_EVENT_TYPE'
+	| 'SYNC_FAILED'
+	| 'PUBLISH_FAILED'
+	| 'QUERY_FAILED'
+	| 'QUERY_NOT_SUPPORTED'
+	| 'MEDIATOR_ERROR'
+	| 'NO_TRANSPORT';
+
+export class DecentrlSDKError extends Error {
+	constructor(
+		message: string,
+		public code: DecentrlSDKErrorCode,
+		public details?: unknown,
+	) {
+		super(message);
+		this.name = 'DecentrlSDKError';
+	}
+}

package/src/event-processor.ts

@@ -0,0 +1,133 @@
+import { DecentrlSDKError } from './errors.js';
+import type { StateStore } from './state-store.js';
+import { evaluateTagTemplates } from './tag-templates.js';
+import type {
+	EventDefinitions,
+	EventEnvelope,
+	EventMeta,
+	InferState,
+	StateDefinitions,
+} from './types.js';
+
+const MAX_DEDUP_SIZE = 10_000;
+
+export class EventProcessor<
+	TEvents extends EventDefinitions,
+	TState extends StateDefinitions<TEvents>,
+> {
+	private processedEventIds = new Set<string>();
+	private eventListeners = new Set<(envelope: EventEnvelope) => void>();
+
+	constructor(
+		private eventDefinitions: TEvents,
+		private stateDefinitions: TState,
+		private stateStore: StateStore<InferState<TState>>,
+	) {}
+
+	onEvent(listener: (envelope: EventEnvelope) => void): () => void {
+		this.eventListeners.add(listener);
+
+		return () => this.eventListeners.delete(listener);
+	}
+
+	validate(eventType: string, data: unknown): void {
+		const definition = this.eventDefinitions[eventType];
+
+		if (!definition) {
+			throw new DecentrlSDKError(`Unknown event type: ${eventType}`, 'UNKNOWN_EVENT_TYPE', {
+				eventType,
+			});
+		}
+
+		const result = definition.schema.safeParse(data);
+
+		if (!result.success) {
+			throw new DecentrlSDKError(
+				`Schema validation failed for event type "${eventType}": ${result.error.message}`,
+				'SCHEMA_VALIDATION_FAILED',
+				{ eventType, errors: result.error.issues },
+			);
+		}
+	}
+
+	computeTags(eventType: string, data: unknown): string[] {
+		const definition = this.eventDefinitions[eventType];
+
+		if (!definition) {
+			throw new DecentrlSDKError(`Unknown event type: ${eventType}`, 'UNKNOWN_EVENT_TYPE', {
+				eventType,
+			});
+		}
+
+		return evaluateTagTemplates(definition.tags, data);
+	}
+
+	computeTagsSafe(eventType: string, data: unknown): string[] {
+		try {
+			return this.computeTags(eventType, data);
+		} catch {
+			return [];
+		}
+	}
+
+	buildEnvelope(eventType: string, data: unknown, meta: EventMeta): EventEnvelope {
+		return { type: eventType, data, meta };
+	}
+
+	processEvent(envelope: EventEnvelope): boolean {
+		const isEphemeral = envelope.meta.ephemeral === true;
+
+		if (!isEphemeral) {
+			if (this.processedEventIds.has(envelope.meta.eventId)) {
+				return false;
+			}
+
+			if (this.processedEventIds.size >= MAX_DEDUP_SIZE) {
+				// Set iterates in insertion order — first value is the oldest
+				const oldest = this.processedEventIds.values().next().value!;
+				this.processedEventIds.delete(oldest);
+			}
+
+			this.processedEventIds.add(envelope.meta.eventId);
+		}
+
+		const currentState = this.stateStore.getState();
+
+		for (const sliceKey of Object.keys(this.stateDefinitions)) {
+			const sliceDef = this.stateDefinitions[sliceKey];
+			// Dynamic reducer lookup — TS can't prove type safety for runtime event type dispatch
+			const reducer = sliceDef.reduce[envelope.type] as
+				| ((state: any, data: any, meta: EventMeta) => any)
+				| undefined;
+
+			if (reducer) {
+				const currentSlice = currentState[sliceKey as keyof InferState<TState>];
+				const newSlice = reducer(currentSlice, envelope.data, envelope.meta);
+				this.stateStore.setSlice(sliceKey as keyof InferState<TState>, newSlice);
+			}
+		}
+
+		for (const listener of this.eventListeners) {
+			listener(envelope);
+		}
+
+		return true;
+	}
+
+	processBatch(envelopes: EventEnvelope[]): number {
+		let newCount = 0;
+
+		for (const envelope of envelopes) {
+			if (this.processEvent(envelope)) {
+				newCount++;
+			}
+		}
+
+		return newCount;
+	}
+
+	reset(): void {
+		this.processedEventIds.clear();
+		this.eventListeners.clear();
+	}
+}

package/src/identity-manager.ts

@@ -0,0 +1,91 @@
+import { DecentrlSDKError } from './errors.js';
+import { deserializeKeys, serializeIdentity } from './identity-serialization.js';
+import type { DecentrlTransport } from './transport.js';
+import type { IdentityState, SerializedIdentity } from './types.js';
+
+type IdentityChangeListener = (identity: IdentityState | null) => void;
+
+export class IdentityManager {
+	private identity: IdentityState | null = null;
+	private listeners = new Set<IdentityChangeListener>();
+	private transport: DecentrlTransport | null = null;
+
+	setTransport(transport: DecentrlTransport): void {
+		this.transport = transport;
+	}
+
+	getIdentity(): IdentityState | null {
+		return this.identity;
+	}
+
+	requireIdentity(): IdentityState {
+		if (!this.identity) {
+			throw new DecentrlSDKError(
+				'Identity not initialized. Call create() or load() first.',
+				'IDENTITY_NOT_INITIALIZED',
+			);
+		}
+
+		return this.identity;
+	}
+
+	async create(options: { alias: string; mediatorDid: string }): Promise<IdentityState> {
+		if (this.identity) {
+			throw new DecentrlSDKError(
+				'Identity already exists. Call reset() first to create a new one.',
+				'IDENTITY_ALREADY_EXISTS',
+			);
+		}
+
+		if (!this.transport) {
+			throw new DecentrlSDKError('Transport not set', 'NO_TRANSPORT');
+		}
+
+		const serialized = await this.transport.createIdentity(options);
+
+		return this.load(serialized);
+	}
+
+	load(serialized: SerializedIdentity): IdentityState {
+		this.identity = {
+			did: serialized.did,
+			alias: serialized.alias,
+			mediatorDid: serialized.mediatorDid,
+			mediatorEndpoint: serialized.mediatorEndpoint,
+			keys: deserializeKeys(serialized),
+			mediatorContract: serialized.mediatorContract,
+		};
+
+		// Sync with transport
+		this.transport?.loadIdentity?.(serialized);
+
+		this.notify();
+
+		return this.identity;
+	}
+
+	serialize(): SerializedIdentity {
+		const identity = this.requireIdentity();
+
+		return serializeIdentity(identity);
+	}
+
+	reset(): void {
+		this.identity = null;
+		this.notify();
+	}
+
+	onChange(listener: IdentityChangeListener): () => void {
+		this.listeners.add(listener);
+
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+
+	private notify(): void {
+		for (const listener of this.listeners) {
+			listener(this.identity);
+		}
+	}
+}

package/src/identity-serialization.ts

@@ -0,0 +1,33 @@
+import { base64Decode, base64Encode, type DecentrlIdentityKeys } from '@decentrl/crypto';
+import type { IdentityState, SerializedIdentity } from './types.js';
+
+export const serializeIdentity = (identity: IdentityState): SerializedIdentity => ({
+	did: identity.did,
+	alias: identity.alias,
+	mediatorDid: identity.mediatorDid,
+	mediatorEndpoint: identity.mediatorEndpoint,
+	keys: {
+		signing: {
+			privateKey: base64Encode(identity.keys.signing.privateKey),
+			publicKey: base64Encode(identity.keys.signing.publicKey),
+		},
+		encryption: {
+			privateKey: base64Encode(identity.keys.encryption.privateKey),
+			publicKey: base64Encode(identity.keys.encryption.publicKey),
+		},
+		storageKey: base64Encode(identity.keys.storageKey),
+	},
+	mediatorContract: identity.mediatorContract,
+});
+
+export const deserializeKeys = (serialized: SerializedIdentity): DecentrlIdentityKeys => ({
+	signing: {
+		privateKey: base64Decode(serialized.keys.signing.privateKey),
+		publicKey: base64Decode(serialized.keys.signing.publicKey),
+	},
+	encryption: {
+		privateKey: base64Decode(serialized.keys.encryption.privateKey),
+		publicKey: base64Decode(serialized.keys.encryption.publicKey),
+	},
+	storageKey: base64Decode(serialized.keys.storageKey),
+});

package/src/index.ts

@@ -0,0 +1,43 @@
+export { DecentrlClient } from './client.js';
+export { ContractManager } from './contract-manager.js';
+export type { DecentrlApp } from './define-app.js';
+export { defineDecentrlApp } from './define-app.js';
+export type { DirectTransportOptions, HttpPost } from './direct-transport.js';
+export { DirectTransport } from './direct-transport.js';
+export type { DecentrlSDKErrorCode } from './errors.js';
+export { DecentrlSDKError } from './errors.js';
+export { EventProcessor } from './event-processor.js';
+export { IdentityManager } from './identity-manager.js';
+export type { PersistOptions } from './persistence.js';
+export { StateStore } from './state-store.js';
+export { SyncManager } from './sync-manager.js';
+export type { DecentrlTransport } from './transport.js';
+export type {
+	ArchivedContract,
+	DecentrlAppConfig,
+	DecentrlClientConfig,
+	EventDefinition,
+	EventDefinitions,
+	EventEnvelope,
+	EventMeta,
+	IdentityState,
+	InferState,
+	PaginatedResult,
+	PaginationMeta,
+	PendingContractRequest,
+	PublishOptions,
+	QueryOptions,
+	SerializedIdentity,
+	SerializedKeyPair,
+	StateDefinitions,
+	StateListener,
+	StateSliceDefinition,
+	StoredSignedContract,
+	SyncOptions,
+} from './types.js';
+export type {
+	ConnectionStatus,
+	WebSocketTransportCallbacks,
+	WebSocketTransportIdentity,
+} from './websocket-transport.js';
+export { deriveWsUrl, WebSocketTransport } from './websocket-transport.js';

package/src/persistence.ts

@@ -0,0 +1,103 @@
+import type { SerializedIdentity } from './types.js';
+
+export interface PersistOptions {
+	/** localStorage key prefix. Identity stored at `${key}:identity`, state at `${key}:state` */
+	key: string;
+}
+
+function getStorage(): Storage | null {
+	try {
+		return typeof localStorage !== 'undefined' ? localStorage : null;
+	} catch {
+		return null;
+	}
+}
+
+export function loadPersistedIdentity(opts: PersistOptions): SerializedIdentity | null {
+	const storage = getStorage();
+
+	if (!storage) {
+		return null;
+	}
+
+	try {
+		const raw = storage.getItem(`${opts.key}:identity`);
+
+		if (!raw) {
+			return null;
+		}
+
+		return JSON.parse(raw) as SerializedIdentity;
+	} catch {
+		return null;
+	}
+}
+
+export function persistIdentity(opts: PersistOptions, identity: SerializedIdentity | null): void {
+	const storage = getStorage();
+
+	if (!storage) {
+		return;
+	}
+
+	try {
+		if (identity) {
+			storage.setItem(`${opts.key}:identity`, JSON.stringify(identity));
+		} else {
+			storage.removeItem(`${opts.key}:identity`);
+		}
+	} catch {
+		// Silently fail (quota exceeded, etc.)
+	}
+}
+
+export function loadPersistedState<T extends Record<string, unknown>>(
+	opts: PersistOptions,
+): T | null {
+	const storage = getStorage();
+
+	if (!storage) {
+		return null;
+	}
+
+	try {
+		const raw = storage.getItem(`${opts.key}:state`);
+
+		if (!raw) {
+			return null;
+		}
+
+		return JSON.parse(raw) as T;
+	} catch {
+		return null;
+	}
+}
+
+export function persistState(opts: PersistOptions, state: Record<string, unknown>): void {
+	const storage = getStorage();
+
+	if (!storage) {
+		return;
+	}
+
+	try {
+		storage.setItem(`${opts.key}:state`, JSON.stringify(state));
+	} catch {
+		// Silently fail
+	}
+}
+
+export function clearPersisted(opts: PersistOptions): void {
+	const storage = getStorage();
+
+	if (!storage) {
+		return;
+	}
+
+	try {
+		storage.removeItem(`${opts.key}:identity`);
+		storage.removeItem(`${opts.key}:state`);
+	} catch {
+		// Silently fail
+	}
+}