@decentrl/sdk 0.0.7 → 0.0.8

package/src/event-processor.ts

@@ -2,13 +2,22 @@ import { DecentrlSDKError } from './errors.js';
 import type { StateStore } from './state-store.js';
 import { evaluateTagTemplates } from './tag-templates.js';
 import type {
+	ChannelDefinitions,
 	EventDefinitions,
 	EventEnvelope,
 	EventMeta,
 	InferState,
+	PublicEventDefinitions,
+	PublicEventEnvelope,
+	PublicEventMeta,
 	StateDefinitions,
 } from './types.js';
 
+// Dynamic reducer lookup type — TS can't statically verify runtime event type dispatch,
+// so we use this explicit type for the cast instead of `any`.
+type DynamicReducer<TMeta> = ((state: unknown, data: unknown, meta: TMeta) => unknown) | undefined;
+type ReducerMap = Record<string, DynamicReducer<EventMeta | PublicEventMeta>>;
+
 const MAX_DEDUP_SIZE = 10_000;
 
 export class EventProcessor<
@@ -17,11 +26,14 @@ export class EventProcessor<
 > {
 	private processedEventIds = new Set<string>();
 	private eventListeners = new Set<(envelope: EventEnvelope) => void>();
+	private publicEventListeners = new Set<(envelope: PublicEventEnvelope) => void>();
 
 	constructor(
 		private eventDefinitions: TEvents,
 		private stateDefinitions: TState,
 		private stateStore: StateStore<InferState<TState>>,
+		private publicEventDefinitions?: PublicEventDefinitions,
+		private channelDefinitions?: ChannelDefinitions,
 	) {}
 
 	onEvent(listener: (envelope: EventEnvelope) => void): () => void {
@@ -30,6 +42,12 @@ export class EventProcessor<
 		return () => this.eventListeners.delete(listener);
 	}
 
+	onPublicEvent(listener: (envelope: PublicEventEnvelope) => void): () => void {
+		this.publicEventListeners.add(listener);
+
+		return () => this.publicEventListeners.delete(listener);
+	}
+
 	validate(eventType: string, data: unknown): void {
 		const definition = this.eventDefinitions[eventType];
 
@@ -50,6 +68,26 @@ export class EventProcessor<
 		}
 	}
 
+	validatePublicEvent(eventType: string, data: unknown): void {
+		const definition = this.publicEventDefinitions?.[eventType];
+
+		if (!definition) {
+			throw new DecentrlSDKError(`Unknown public event type: ${eventType}`, 'UNKNOWN_EVENT_TYPE', {
+				eventType,
+			});
+		}
+
+		const result = definition.schema.safeParse(data);
+
+		if (!result.success) {
+			throw new DecentrlSDKError(
+				`Schema validation failed for public 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];
 
@@ -62,6 +100,30 @@ export class EventProcessor<
 		return evaluateTagTemplates(definition.tags, data);
 	}
 
+	computePublicTags(eventType: string, data: unknown): string[] {
+		const definition = this.publicEventDefinitions?.[eventType];
+
+		if (!definition) {
+			throw new DecentrlSDKError(`Unknown public event type: ${eventType}`, 'UNKNOWN_EVENT_TYPE', {
+				eventType,
+			});
+		}
+
+		return evaluateTagTemplates(definition.tags, data);
+	}
+
+	getPublicChannelId(eventType: string): string {
+		const definition = this.publicEventDefinitions?.[eventType];
+
+		if (!definition) {
+			throw new DecentrlSDKError(`Unknown public event type: ${eventType}`, 'UNKNOWN_EVENT_TYPE', {
+				eventType,
+			});
+		}
+
+		return definition.channelId;
+	}
+
 	computeTagsSafe(eventType: string, data: unknown): string[] {
 		try {
 			return this.computeTags(eventType, data);
@@ -83,7 +145,6 @@ export class EventProcessor<
 			}
 
 			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);
 			}
@@ -95,10 +156,7 @@ export class EventProcessor<
 
 		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;
+			const reducer = (sliceDef.reduce as ReducerMap)[envelope.type];
 
 			if (reducer) {
 				const currentSlice = currentState[sliceKey as keyof InferState<TState>];
@@ -114,6 +172,86 @@ export class EventProcessor<
 		return true;
 	}
 
+	processPublicEvent(envelope: PublicEventEnvelope): boolean {
+		const dedupKey = `public:${envelope.meta.eventId}`;
+
+		if (this.processedEventIds.has(dedupKey)) {
+			return false;
+		}
+
+		if (this.processedEventIds.size >= MAX_DEDUP_SIZE) {
+			const oldest = this.processedEventIds.values().next().value!;
+			this.processedEventIds.delete(oldest);
+		}
+
+		this.processedEventIds.add(dedupKey);
+
+		const reducerKey = `public:${envelope.type}`;
+		const currentState = this.stateStore.getState();
+
+		for (const sliceKey of Object.keys(this.stateDefinitions)) {
+			const sliceDef = this.stateDefinitions[sliceKey];
+			const reducer = (sliceDef.reduce as ReducerMap)[reducerKey];
+
+			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.publicEventListeners) {
+			listener(envelope);
+		}
+
+		return true;
+	}
+
+	processChannelEvent(envelope: PublicEventEnvelope): boolean {
+		const dedupKey = `channel:${envelope.meta.eventId}`;
+
+		if (this.processedEventIds.has(dedupKey)) {
+			return false;
+		}
+
+		if (this.processedEventIds.size >= MAX_DEDUP_SIZE) {
+			const oldest = this.processedEventIds.values().next().value!;
+			this.processedEventIds.delete(oldest);
+		}
+
+		this.processedEventIds.add(dedupKey);
+
+		const reducerKey = `channel:${envelope.type}`;
+		const currentState = this.stateStore.getState();
+
+		for (const sliceKey of Object.keys(this.stateDefinitions)) {
+			const sliceDef = this.stateDefinitions[sliceKey];
+			const reducer = (sliceDef.reduce as ReducerMap)[reducerKey];
+
+			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.publicEventListeners) {
+			listener(envelope);
+		}
+
+		return true;
+	}
+
+	validateChannelEvent(eventType: string, data: unknown): boolean {
+		const definition = this.channelDefinitions?.[eventType];
+
+		if (!definition) {
+			return false;
+		}
+
+		return definition.schema.safeParse(data).success;
+	}
+
 	processBatch(envelopes: EventEnvelope[]): number {
 		let newCount = 0;
 
@@ -129,5 +267,6 @@ export class EventProcessor<
 	reset(): void {
 		this.processedEventIds.clear();
 		this.eventListeners.clear();
+		this.publicEventListeners.clear();
 	}
 }

package/src/index.ts

@@ -9,11 +9,16 @@ export { DecentrlSDKError } from './errors.js';
 export { EventProcessor } from './event-processor.js';
 export { IdentityManager } from './identity-manager.js';
 export type { PersistOptions } from './persistence.js';
+export { PublicChannelReader } from './public-channel-reader.js';
 export { StateStore } from './state-store.js';
 export { SyncManager } from './sync-manager.js';
 export type { DecentrlTransport } from './transport.js';
 export type {
 	ArchivedContract,
+	ChannelDefinition,
+	ChannelDefinitions,
+	ChannelFetchOptions,
+	ChannelSubscriptionConfig,
 	DecentrlAppConfig,
 	DecentrlClientConfig,
 	EventDefinition,
@@ -25,6 +30,12 @@ export type {
 	PaginatedResult,
 	PaginationMeta,
 	PendingContractRequest,
+	PublicEventDefinition,
+	PublicEventDefinitions,
+	PublicEventEnvelope,
+	PublicEventMeta,
+	PublicEventResult,
+	PublicQueryOptions,
 	PublishOptions,
 	QueryOptions,
 	SerializedIdentity,

package/src/public-channel-reader.ts

@@ -0,0 +1,239 @@
+import { multibaseDecode, verifyJsonSignature } from '@decentrl/crypto';
+import { resolveMediatorServiceEndpoint } from '@decentrl/identity/mediator/mediator.resolver';
+import type { EventProcessor } from './event-processor.js';
+import type { DecentrlTransport } from './transport.js';
+import type {
+	ChannelDefinitions,
+	ChannelFetchOptions,
+	ChannelSubscriptionConfig,
+	EventDefinitions,
+	PaginatedResult,
+	PublicEventEnvelope,
+	PublicEventResult,
+	StateDefinitions,
+} from './types.js';
+
+interface ActiveSubscription {
+	intervalId: ReturnType<typeof setInterval>;
+}
+
+export class PublicChannelReader<
+	TEvents extends EventDefinitions,
+	TState extends StateDefinitions<TEvents>,
+> {
+	private subscriptions = new Map<string, ActiveSubscription>();
+	private mediatorEndpointCache = new Map<string, string>();
+	private signingKeyCache = new Map<string, Uint8Array>();
+
+	constructor(
+		private transport: DecentrlTransport,
+		private eventProcessor: EventProcessor<TEvents, TState>,
+		private channelDefinitions?: ChannelDefinitions,
+	) {}
+
+	subscribe(config: ChannelSubscriptionConfig): { unsubscribe: () => void } {
+		const subId = crypto.randomUUID();
+		const pollIntervalMs = config.pollIntervalMs ?? 10_000;
+
+		let afterTimestamp = Math.floor(Date.now() / 1000);
+
+		const poll = async () => {
+			try {
+				const mediatorEndpoint = await this.resolveMediatorEndpoint(config.did);
+
+				if (!this.transport.fetchPublicEvents) {
+					return;
+				}
+
+				const result = await this.transport.fetchPublicEvents({
+					mediatorEndpoint,
+					publisherDid: config.did,
+					channelId: config.channelId,
+					tags: config.tags,
+					afterTimestamp,
+				});
+
+				for (const event of result.events) {
+					const parsed = await this.parseAndVerifyPublicEvent(event, config.did);
+
+					if (parsed) {
+						this.eventProcessor.processChannelEvent(parsed);
+					}
+				}
+
+				if (result.events.length > 0) {
+					const maxTimestamp = Math.max(...result.events.map((e) => e.timestamp));
+					afterTimestamp = maxTimestamp;
+				}
+			} catch (err) {
+				console.warn('[Decentrl] Public channel poll failed:', err);
+			}
+		};
+
+		poll();
+
+		const intervalId = setInterval(poll, pollIntervalMs);
+		this.subscriptions.set(subId, { intervalId });
+
+		return {
+			unsubscribe: () => {
+				const sub = this.subscriptions.get(subId);
+
+				if (sub) {
+					clearInterval(sub.intervalId);
+					this.subscriptions.delete(subId);
+				}
+			},
+		};
+	}
+
+	async fetch(options: ChannelFetchOptions): Promise<PaginatedResult<PublicEventResult>> {
+		const mediatorEndpoint =
+			options.mediatorEndpoint ?? (await this.resolveMediatorEndpoint(options.did));
+
+		if (!this.transport.fetchPublicEvents) {
+			return { data: [], pagination: { page: 0, pageSize: 20, total: 0 } };
+		}
+
+		const result = await this.transport.fetchPublicEvents({
+			mediatorEndpoint,
+			publisherDid: options.did,
+			channelId: options.channelId,
+			tags: options.tags,
+			afterTimestamp: options.afterTimestamp,
+			beforeTimestamp: options.beforeTimestamp,
+			page: options.pagination?.page,
+			pageSize: options.pagination?.pageSize,
+		});
+
+		return {
+			data: result.events,
+			pagination: result.pagination,
+		};
+	}
+
+	dispose(): void {
+		for (const sub of this.subscriptions.values()) {
+			clearInterval(sub.intervalId);
+		}
+
+		this.subscriptions.clear();
+	}
+
+	private async parseAndVerifyPublicEvent(
+		raw: {
+			id: string;
+			channelId: string;
+			event: string;
+			tags: string[];
+			timestamp: number;
+			eventSignature: string;
+		},
+		publisherDid: string,
+	): Promise<PublicEventEnvelope | null> {
+		try {
+			// Verify signature over { channel_id, event, tags, timestamp }
+			const signingKey = this.resolveSigningKeyFromDid(publisherDid);
+
+			if (signingKey) {
+				const signedData = {
+					channel_id: raw.channelId,
+					event: raw.event,
+					tags: raw.tags,
+					timestamp: raw.timestamp,
+				};
+
+				const isValid = verifyJsonSignature(signedData, raw.eventSignature, signingKey);
+
+				if (!isValid) {
+					console.warn(`[Decentrl] Invalid signature on public event ${raw.id}, skipping`);
+
+					return null;
+				}
+			}
+
+			const parsed = JSON.parse(raw.event);
+			const eventType = parsed.type;
+
+			if (!eventType || typeof eventType !== 'string') {
+				return null;
+			}
+
+			if (
+				this.channelDefinitions &&
+				!this.eventProcessor.validateChannelEvent(eventType, parsed.data)
+			) {
+				return null;
+			}
+
+			return {
+				type: eventType,
+				data: parsed.data,
+				meta: {
+					publisherDid,
+					timestamp: raw.timestamp,
+					eventId: raw.id,
+					channelId: raw.channelId,
+				},
+				tags: raw.tags,
+			};
+		} catch {
+			return null;
+		}
+	}
+
+	private resolveSigningKeyFromDid(did: string): Uint8Array | null {
+		const cached = this.signingKeyCache.get(did);
+
+		if (cached) {
+			return cached;
+		}
+
+		// did:decentrl:alias:signingKey:encKey:mediatorHost
+		if (!did.startsWith('did:decentrl:')) {
+			return null;
+		}
+
+		const parts = did.replace('did:decentrl:', '').split(':');
+
+		if (parts.length < 2) {
+			return null;
+		}
+
+		try {
+			const key = multibaseDecode(parts[1]);
+			this.signingKeyCache.set(did, key);
+
+			return key;
+		} catch {
+			return null;
+		}
+	}
+
+	private async resolveMediatorEndpoint(did: string): Promise<string> {
+		const cached = this.mediatorEndpointCache.get(did);
+
+		if (cached) {
+			return cached;
+		}
+
+		const parts = did.replace('did:decentrl:', '').split(':');
+
+		if (parts.length >= 4) {
+			const mediatorDid = `did:web:${parts[3]}`;
+			const endpoint = await resolveMediatorServiceEndpoint(mediatorDid);
+			this.mediatorEndpointCache.set(did, endpoint);
+
+			return endpoint;
+		}
+
+		if (did.startsWith('did:web:')) {
+			const endpoint = await resolveMediatorServiceEndpoint(did);
+			this.mediatorEndpointCache.set(did, endpoint);
+
+			return endpoint;
+		}
+
+		throw new Error(`Cannot resolve mediator endpoint for DID: ${did}`);
+	}
+}

package/src/sdk.e2e.test.ts

@@ -364,4 +364,169 @@ describe('SDK E2E', () => {
 			expect(client.identity.getIdentity()).toBeNull();
 		});
 	});
+
+	// ------- Public Events -------
+
+	describe('Public Events', () => {
+		const blogApp = defineDecentrlApp({
+			events: {},
+			state: {
+				posts: {
+					initial: [] as Array<{ id: string; title: string; publisherDid: string }>,
+					reduce: {
+						'public:blog.post': (
+							posts,
+							data: { title: string; body: string },
+							meta: { eventId: string; publisherDid: string },
+						) => [
+							...posts,
+							{ id: meta.eventId, title: data.title, publisherDid: meta.publisherDid },
+						],
+					},
+				},
+			},
+			publicEvents: {
+				'blog.post': {
+					schema: z.object({
+						title: z.string(),
+						body: z.string(),
+					}),
+					tags: ['blog', 'post:${title}'],
+					channelId: 'blog',
+				},
+			},
+		});
+
+		let publisher: ReturnType<typeof blogApp.createClient>;
+
+		beforeAll(async () => {
+			publisher = blogApp.createClient({ mediatorDid: MEDIATOR_DID });
+			await publisher.identity.create({ alias: 'publisher', mediatorDid: MEDIATOR_DID });
+		});
+
+		afterAll(() => {
+			publisher.reset();
+		});
+
+		it('should publish a public event', async () => {
+			const result = await publisher.publishPublic('blog.post', {
+				title: 'Hello World',
+				body: 'This is my first post',
+			});
+
+			expect(result.publicEventId).toBeDefined();
+			expect(typeof result.publicEventId).toBe('string');
+		});
+
+		it('should reject invalid public event data', async () => {
+			await expect(publisher.publishPublic('blog.post', { title: 123 } as any)).rejects.toThrow(
+				'Schema validation failed',
+			);
+		});
+
+		it('should reject unknown public event type', async () => {
+			await expect(publisher.publishPublic('blog.unknown', { foo: 'bar' })).rejects.toThrow(
+				'Unknown public event type',
+			);
+		});
+
+		it('should update local state via public: reducer', async () => {
+			const state = publisher.getState();
+			expect(state.posts.length).toBeGreaterThanOrEqual(1);
+			expect(state.posts[0].title).toBe('Hello World');
+		});
+
+		it('should query public events via GET endpoint', async () => {
+			const publisherDid = publisher.identity.getIdentity()!.did;
+			const result = await publisher.queryPublicEvents({
+				publisherDid,
+				channelId: 'blog',
+			});
+
+			expect(result.data.length).toBeGreaterThanOrEqual(1);
+			expect(result.data[0].channelId).toBe('blog');
+			expect(result.pagination.total).toBeGreaterThanOrEqual(1);
+
+			// Verify the event content is parseable
+			const parsed = JSON.parse(result.data[0].event);
+			expect(parsed.type).toBe('blog.post');
+			expect(parsed.data.title).toBe('Hello World');
+		});
+
+		it('should filter by tags', async () => {
+			const publisherDid = publisher.identity.getIdentity()!.did;
+			const result = await publisher.queryPublicEvents({
+				publisherDid,
+				tags: ['blog'],
+			});
+
+			expect(result.data.length).toBeGreaterThanOrEqual(1);
+		});
+
+		it('should return 404 for unregistered publisher', async () => {
+			await expect(
+				publisher.queryPublicEvents({
+					publisherDid: 'did:decentrl:nonexistent:key:key:localhost',
+				}),
+			).rejects.toThrow();
+		});
+
+		it('should publish multiple and paginate', async () => {
+			await publisher.publishPublic('blog.post', {
+				title: 'Second Post',
+				body: 'More content',
+			});
+			await publisher.publishPublic('blog.post', {
+				title: 'Third Post',
+				body: 'Even more content',
+			});
+
+			const publisherDid = publisher.identity.getIdentity()!.did;
+			const page1 = await publisher.queryPublicEvents({
+				publisherDid,
+				channelId: 'blog',
+				pagination: { page: 0, pageSize: 2 },
+			});
+
+			expect(page1.data.length).toBe(2);
+			expect(page1.pagination.total).toBeGreaterThanOrEqual(3);
+		});
+
+		it('should delete a public event', async () => {
+			const publisherDid = publisher.identity.getIdentity()!.did;
+
+			// Get events
+			const before = await publisher.queryPublicEvents({
+				publisherDid,
+				channelId: 'blog',
+			});
+
+			const eventToDelete = before.data[0];
+			await publisher.deletePublicEvent(eventToDelete.id);
+
+			const after = await publisher.queryPublicEvents({
+				publisherDid,
+				channelId: 'blog',
+			});
+
+			expect(after.pagination.total).toBe(before.pagination.total - 1);
+			expect(after.data.find((e) => e.id === eventToDelete.id)).toBeUndefined();
+		});
+
+		it('should include event_signature that can be verified', async () => {
+			const publisherDid = publisher.identity.getIdentity()!.did;
+			const result = await publisher.queryPublicEvents({
+				publisherDid,
+				channelId: 'blog',
+			});
+
+			expect(result.data.length).toBeGreaterThanOrEqual(1);
+
+			for (const event of result.data) {
+				expect(event.eventSignature).toBeDefined();
+				expect(typeof event.eventSignature).toBe('string');
+				expect(event.eventSignature.length).toBeGreaterThan(0);
+			}
+		});
+	});
 });

package/src/transport.ts

@@ -61,5 +61,37 @@ export interface DecentrlTransport {
 		pageSize: number;
 	}): Promise<import('./types.js').PaginatedResult<EventEnvelope>>;
 
+	// Optional: publish public events (requires identity)
+	publishPublicEvent?(options: {
+		channelId: string;
+		event: string;
+		tags: string[];
+	}): Promise<{ publicEventId: string }>;
+
+	// Optional: delete public events (requires identity)
+	deletePublicEvent?(publicEventId: string, eventType?: string): Promise<void>;
+
+	// Optional: fetch public events (no identity needed)
+	fetchPublicEvents?(options: {
+		mediatorEndpoint: string;
+		publisherDid: string;
+		channelId?: string;
+		tags?: string[];
+		afterTimestamp?: number;
+		beforeTimestamp?: number;
+		page?: number;
+		pageSize?: number;
+	}): Promise<{
+		events: Array<{
+			id: string;
+			channelId: string;
+			event: string;
+			tags: string[];
+			timestamp: number;
+			eventSignature: string;
+		}>;
+		pagination: { page: number; pageSize: number; total: number };
+	}>;
+
 	dispose(): void;
 }