@decentrl/sdk 0.0.1

package/src/tag-templates.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest';
+import { evaluateTagTemplates } from './tag-templates.js';
+
+describe('evaluateTagTemplates', () => {
+	it('resolves simple property', () => {
+		expect(evaluateTagTemplates(['chat.${id}'], { id: 'abc' })).toEqual(['chat.abc']);
+	});
+
+	it('resolves array index via dot notation', () => {
+		const data = { participants: ['alice', 'bob'] };
+		expect(evaluateTagTemplates(['participant.${participants.1}'], data)).toEqual([
+			'participant.bob',
+		]);
+		expect(evaluateTagTemplates(['participant.${participants.0}'], data)).toEqual([
+			'participant.alice',
+		]);
+	});
+
+	it('resolves nested object property', () => {
+		expect(evaluateTagTemplates(['${x.y.z}'], { x: { y: { z: 'deep' } } })).toEqual(['deep']);
+	});
+
+	it('returns empty string for missing property', () => {
+		expect(evaluateTagTemplates(['tag.${nonexistent}'], { id: 'abc' })).toEqual(['tag.']);
+	});
+
+	it('returns static templates unchanged', () => {
+		expect(evaluateTagTemplates(['chat', 'readmarker'], {})).toEqual(['chat', 'readmarker']);
+	});
+
+	it('returns empty array for empty templates', () => {
+		expect(evaluateTagTemplates([], {})).toEqual([]);
+	});
+
+	it('handles multiple placeholders in one template', () => {
+		expect(evaluateTagTemplates(['${a}.${b}'], { a: 'foo', b: 'bar' })).toEqual(['foo.bar']);
+	});
+
+	it('blocks prototype pollution paths', () => {
+		expect(evaluateTagTemplates(['${__proto__}'], {})).toEqual(['']);
+		expect(evaluateTagTemplates(['${constructor}'], {})).toEqual(['']);
+		expect(evaluateTagTemplates(['${prototype}'], {})).toEqual(['']);
+		expect(evaluateTagTemplates(['${x.__proto__}'], { x: {} })).toEqual(['']);
+	});
+
+	it('handles null/undefined data gracefully', () => {
+		expect(evaluateTagTemplates(['${id}'], null)).toEqual(['']);
+		expect(evaluateTagTemplates(['${id}'], undefined)).toEqual(['']);
+	});
+
+	it('handles numeric values', () => {
+		expect(evaluateTagTemplates(['ts.${timestamp}'], { timestamp: 123 })).toEqual(['ts.123']);
+	});
+
+	it('handles boolean values', () => {
+		expect(evaluateTagTemplates(['active.${flag}'], { flag: true })).toEqual(['active.true']);
+	});
+
+	describe('chat app tag templates', () => {
+		it('chat.create tags', () => {
+			const data = {
+				id: 'chat-1',
+				participants: ['did:decentrl:alice', 'did:decentrl:bob'],
+				communicationContractId: 'contract-1',
+				createdBy: 'did:decentrl:alice',
+				createdAt: 1000,
+			};
+			const templates = ['chat', 'chat.${id}', 'participant.${participants.1}'];
+			expect(evaluateTagTemplates(templates, data)).toEqual([
+				'chat',
+				'chat.chat-1',
+				'participant.did:decentrl:bob',
+			]);
+		});
+
+		it('chat.message tags', () => {
+			const data = {
+				id: 'msg-1',
+				chatId: 'chat-1',
+				content: 'Hello',
+				sender: 'did:decentrl:alice',
+				timestamp: 1000,
+			};
+			expect(evaluateTagTemplates(['chat.${chatId}'], data)).toEqual(['chat.chat-1']);
+		});
+
+		it('chat.react tags', () => {
+			const data = {
+				id: 'react-1',
+				messageId: 'msg-1',
+				chatId: 'chat-1',
+				emoji: '👍',
+				sender: 'did:decentrl:alice',
+				timestamp: 1000,
+			};
+			expect(evaluateTagTemplates(['chat.${chatId}'], data)).toEqual(['chat.chat-1']);
+		});
+
+		it('chat.read tags', () => {
+			const data = { chatId: 'chat-1', timestamp: 1000 };
+			expect(evaluateTagTemplates(['readmarker', 'readmarker.${chatId}'], data)).toEqual([
+				'readmarker',
+				'readmarker.chat-1',
+			]);
+		});
+
+		it('chat.presence tags (empty)', () => {
+			expect(evaluateTagTemplates([], { timestamp: 1000 })).toEqual([]);
+		});
+	});
+});

package/src/tag-templates.ts

@@ -0,0 +1,30 @@
+export function evaluateTagTemplates(templates: string[], data: unknown): string[] {
+	return templates.map((t) => evaluateTemplate(t, data));
+}
+
+function evaluateTemplate(template: string, data: unknown): string {
+	return template.replace(/\$\{([^}]+)\}/g, (_, path) => {
+		return String(resolveProperty(data, path) ?? '');
+	});
+}
+
+const BLOCKED_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+function resolveProperty(obj: unknown, path: string): unknown {
+	const parts = path.split(/[.[\]]+/).filter(Boolean);
+	let value: unknown = obj;
+
+	for (const part of parts) {
+		if (BLOCKED_KEYS.has(part)) {
+			return undefined;
+		}
+
+		if (value == null || typeof value !== 'object') {
+			return undefined;
+		}
+
+		value = (value as Record<string, unknown>)[part];
+	}
+
+	return value;
+}

package/src/test-helpers.ts

@@ -0,0 +1,88 @@
+import { vi } from 'vitest';
+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, StateDefinitions, StoredSignedContract } from './types.js';
+
+export const makeContract = (
+	overrides: Partial<StoredSignedContract> & {
+		participantDid: string;
+		expiresAt: number;
+		timestamp: number;
+	},
+): StoredSignedContract => ({
+	id: overrides.id ?? `contract-${Math.random().toString(36).slice(2)}`,
+	participantDid: overrides.participantDid,
+	signedCommunicationContract: {
+		communication_contract: {
+			requestor_did:
+				overrides.signedCommunicationContract?.communication_contract?.requestor_did ??
+				'did:decentrl:alice',
+			recipient_did: overrides.participantDid,
+			requestor_signing_key_id: 'did:decentrl:alice#signing',
+			recipient_signing_key_id: `${overrides.participantDid}#signing`,
+			requestor_encryption_public_key: 'key-a',
+			recipient_encryption_public_key: 'key-b',
+			expires_at: overrides.expiresAt,
+			timestamp: overrides.timestamp,
+		},
+		requestor_signature: 'sig-a',
+		recipient_signature: 'sig-b',
+	},
+	rootSecret: overrides.rootSecret ?? 'c2VjcmV0',
+	createdAt: overrides.createdAt ?? Date.now(),
+	status: overrides.status ?? 'active',
+});
+
+export const createMockIdentityManager = (
+	overrides: Partial<Record<keyof IdentityManager, unknown>> = {},
+) =>
+	({
+		requireIdentity: vi.fn(() => ({
+			did: 'did:decentrl:alice',
+			mediatorDid: 'did:web:mediator',
+			mediatorEndpoint: 'http://mediator',
+			keys: {
+				signing: {
+					privateKey: new Uint8Array(32),
+					publicKey: new Uint8Array(32),
+				},
+				encryption: {
+					privateKey: new Uint8Array(32),
+					publicKey: new Uint8Array(32),
+				},
+				storageKey: new Uint8Array(32),
+			},
+		})),
+		getIdentity: vi.fn(() => null),
+		...overrides,
+	}) as unknown as IdentityManager;
+
+export const createMockTransport = (overrides: Partial<DecentrlTransport> = {}) =>
+	({
+		refreshContracts: vi.fn(async () => []),
+		processAutoRenewals: vi.fn(async () => {}),
+		processContractCleanup: vi.fn(async () => {}),
+		requestContract: vi.fn(async () => {}),
+		getPendingContracts: vi.fn(async () => []),
+		acceptContract: vi.fn(async () => {}),
+		getActiveContracts: vi.fn(() => []),
+		processPendingEvents: vi.fn(async () => []),
+		...overrides,
+	}) as unknown as DecentrlTransport;
+
+export const createMockEventProcessor = (overrides: Partial<Record<string, unknown>> = {}) =>
+	({
+		processBatch: vi.fn(() => 0),
+		computeTagsSafe: vi.fn((type: string) => [`tag:${type}`]),
+		...overrides,
+	}) as unknown as EventProcessor<EventDefinitions, StateDefinitions<EventDefinitions>>;
+
+export const createMockContractManager = (overrides: Partial<Record<string, unknown>> = {}) =>
+	({
+		refresh: vi.fn(async () => {}),
+		processAutoRenewals: vi.fn(async () => {}),
+		processContractCleanup: vi.fn(async () => {}),
+		...overrides,
+	}) as unknown as ContractManager;

package/src/transport.ts

@@ -0,0 +1,65 @@
+import type {
+	EventEnvelope,
+	PendingContractRequest,
+	SerializedIdentity,
+	StoredSignedContract,
+} from './types.js';
+
+export interface DecentrlTransport {
+	// Identity
+	createIdentity(options: { alias: string; mediatorDid: string }): Promise<SerializedIdentity>;
+	getIdentity(): SerializedIdentity | null;
+	loadIdentity?(serialized: SerializedIdentity): void;
+
+	// Events
+	publishEvent(
+		envelope: EventEnvelope,
+		options: { tags: string[]; recipient?: string; ephemeral?: boolean },
+	): Promise<void>;
+	processPendingEvents(): Promise<EventEnvelope[]>;
+	processPreFetchedPendingEvents?(
+		rawEvents: Array<{ id: string; sender_did: string; payload: string }>,
+	): Promise<EventEnvelope[]>;
+
+	// Contracts
+	requestContract(recipientDid: string, expiresIn?: number): Promise<void>;
+	getPendingContracts(): Promise<PendingContractRequest[]>;
+	acceptContract(
+		pendingId: string,
+		encryptedPayload: string,
+		requestorEphemeralPublicKey: string,
+	): Promise<void>;
+	refreshContracts(): Promise<StoredSignedContract[]>;
+	getActiveContracts(): StoredSignedContract[];
+
+	// Optional: auto-renew expiring contracts
+	processAutoRenewals?(threshold: number): Promise<void>;
+
+	// Optional: clean up old superseded contracts
+	processContractCleanup?(): Promise<void>;
+
+	// Optional: query archived contract history
+	getContractHistory?(): Promise<import('./types.js').ArchivedContract[]>;
+
+	// Optional: query stored events (extension proxy mode)
+	queryEvents?(
+		options?: import('./types.js').QueryOptions,
+	): Promise<import('./types.js').PaginatedResult<EventEnvelope>>;
+
+	// Optional: push-based event delivery (extension mode)
+	onEvents?(listener: (events: EventEnvelope[]) => void): () => void;
+
+	// Optional: push-based contract change notification (extension mode)
+	onContractsChanged?(listener: () => void): () => void;
+
+	// Optional: update event tags on mediator (app-side tag enrichment)
+	updateEventTags?(events: Array<{ eventId: string; tags: string[] }>): Promise<void>;
+
+	// Optional: query events not yet processed by the app
+	queryUnprocessedEvents?(pagination?: {
+		page: number;
+		pageSize: number;
+	}): Promise<import('./types.js').PaginatedResult<EventEnvelope>>;
+
+	dispose(): void;
+}

package/src/types.ts

@@ -0,0 +1,191 @@
+import type { DecentrlIdentityKeys } from '@decentrl/crypto';
+import type { SignedCommunicationContract } from '@decentrl/identity/communication-contract/communication-contract.schema';
+import type { z } from 'zod';
+
+// --- Event Definition Types ---
+
+export interface EventDefinition<TSchema extends z.ZodType = z.ZodType> {
+	schema: TSchema;
+	tags: string[];
+}
+
+export type EventDefinitions = Record<
+	string,
+	{
+		schema: z.ZodType;
+		tags: string[];
+	}
+>;
+
+// --- State Slice Types ---
+
+export interface StateSliceDefinition<
+	TSlice = unknown,
+	TEvents extends EventDefinitions = EventDefinitions,
+> {
+	initial: TSlice;
+	reduce: {
+		[K in keyof TEvents]?: (
+			state: TSlice,
+			data: z.infer<TEvents[K]['schema']>,
+			meta: EventMeta,
+		) => TSlice;
+	};
+}
+
+export type StateDefinitions<TEvents extends EventDefinitions = EventDefinitions> = Record<
+	string,
+	StateSliceDefinition<any, TEvents>
+>;
+
+// --- Inferred State ---
+
+export type InferState<TState extends StateDefinitions> = {
+	[K in keyof TState]: TState[K]['initial'];
+};
+
+// --- Event Meta & Envelope ---
+
+export interface EventMeta {
+	senderDid: string;
+	timestamp: number;
+	eventId: string;
+	ephemeral?: boolean;
+}
+
+export interface EventEnvelope {
+	type: string;
+	data: unknown;
+	meta: EventMeta;
+	tags?: string[];
+	_mediatorEventId?: string;
+}
+
+// --- Client Config ---
+
+export interface DecentrlClientConfig {
+	mediatorDid: string;
+	/** Enable localStorage persistence. Pass a key prefix (e.g. "decentrl-myapp"). */
+	persist?: { key: string };
+	/** Optional transport layer. Defaults to DirectTransport (direct HTTP to mediator). */
+	transport?: import('./transport.js').DecentrlTransport;
+}
+
+// --- App Config ---
+
+export interface DecentrlAppConfig<
+	TEvents extends EventDefinitions = EventDefinitions,
+	TState extends StateDefinitions<TEvents> = StateDefinitions<TEvents>,
+> {
+	events: TEvents;
+	state: TState;
+}
+
+// --- Serialized Identity ---
+
+export interface SerializedKeyPair {
+	privateKey: string;
+	publicKey: string;
+}
+
+export interface SerializedIdentity {
+	did: string;
+	alias: string;
+	mediatorDid: string;
+	mediatorEndpoint: string;
+	keys: {
+		signing: SerializedKeyPair;
+		encryption: SerializedKeyPair;
+		storageKey: string;
+	};
+	mediatorContract: SignedCommunicationContract | null;
+}
+
+// --- Identity State ---
+
+export interface IdentityState {
+	did: string;
+	alias: string;
+	mediatorDid: string;
+	mediatorEndpoint: string;
+	keys: DecentrlIdentityKeys;
+	mediatorContract: SignedCommunicationContract | null;
+}
+
+// --- Contract Types ---
+
+export interface StoredSignedContract {
+	id: string;
+	participantDid: string;
+	participantAlias?: string;
+	signedCommunicationContract: SignedCommunicationContract;
+	rootSecret: string;
+	createdAt: number;
+	status: 'active' | 'expired' | 'superseded';
+}
+
+export interface ArchivedContract {
+	contractId: string;
+	participantDid: string;
+	participantAlias?: string;
+	timestamp: number; // contract creation (seconds)
+	expiresAt: number; // contract expiry (seconds)
+	supersededAt: number; // when it was archived (ms)
+	supersededBy: string; // the replacing contract ID
+}
+
+export interface PendingContractRequest {
+	id: string;
+	senderDid: string;
+	encryptedPayload: string;
+	requestorEphemeralPublicKey: string;
+}
+
+// --- Query Options ---
+
+export interface QueryOptions {
+	tags?: string[];
+	participantDid?: string;
+	afterTimestamp?: number;
+	beforeTimestamp?: number;
+	pagination?: { page: number; pageSize: number };
+}
+
+export interface PaginationMeta {
+	page: number;
+	pageSize: number;
+	total: number;
+}
+
+export interface PaginatedResult<T> {
+	data: T[];
+	pagination: PaginationMeta;
+}
+
+// --- Publish Options ---
+
+export interface PublishOptions {
+	recipient?: string;
+	ephemeral?: boolean;
+}
+
+// --- Sync Options ---
+
+export interface SyncOptions {
+	intervalMs?: number;
+	fallbackIntervalMs?: number;
+	onError?: (error: unknown) => void;
+	websocket?: boolean;
+	autoRenew?: {
+		enabled: boolean;
+		threshold?: number; // fraction of lifetime remaining before renewal, default 0.2
+	};
+}
+
+// --- Connection Status ---
+
+export type { ConnectionStatus } from './websocket-transport.js';
+
+// --- Listener ---
+
+export type StateListener<TState> = (state: TState) => void;