@edryslabs/genericprovider 1.0.1

package/dist/providers/matrix/index.d.ts

@@ -0,0 +1,109 @@
+import type { Transport, ConnectionConfig } from '../../transport';
+/**
+ * Matrix transport configuration
+ */
+export interface MatrixConfig extends ConnectionConfig {
+    /** Matrix homeserver URL (required) e.g., 'https://matrix.org' */
+    homeserverUrl: string;
+    /** Access token (optional - if not provided, will register as guest) */
+    accessToken?: string;
+    /** User ID (optional - required if accessToken is provided) */
+    userId?: string;
+    /** Device ID (optional) */
+    deviceId?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Matrix Transport for Yjs
+ *
+ * Provides real-time synchronization using Matrix protocol.
+ *
+ * Features:
+ * - Decentralized federation
+ * - Guest access (no login required)
+ * - End-to-end encryption support
+ * - Persistent message history
+ * - Room-based collaboration
+ *
+ * @example
+ * ```ts
+ * import * as Y from 'yjs'
+ * import { GenericProvider } from 'y-generic'
+ * import { MatrixTransport } from 'y-generic/providers/matrix'
+ *
+ * const doc = new Y.Doc()
+ * const transport = new MatrixTransport()
+ *
+ * const provider = new GenericProvider(doc, transport)
+ * await provider.connect({
+ *   homeserverUrl: 'https://matrix.org',
+ *   room: '#my-room:matrix.org'
+ * })
+ * ```
+ */
+export declare class MatrixTransport implements Transport {
+    private config;
+    private messageCallback?;
+    private _isConnected;
+    private debug;
+    private accessToken;
+    private userId;
+    private roomId;
+    private syncToken;
+    private syncRunning;
+    private intentionalDisconnect;
+    private txnId;
+    private messageQueue;
+    private receivedBuffer;
+    get isConnected(): boolean;
+    /**
+     * Connect to Matrix homeserver and join room
+     */
+    connect(config: MatrixConfig): Promise<void>;
+    /**
+     * Register as guest on the homeserver
+     */
+    private registerAsGuest;
+    /**
+     * Join a Matrix room
+     */
+    private joinRoom;
+    /**
+     * Start Matrix sync loop
+     */
+    private startSync;
+    /**
+     * Perform one sync request
+     */
+    private syncOnce;
+    /**
+     * Disconnect from Matrix
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Send Yjs update to Matrix room
+     */
+    send(data: Uint8Array): void;
+    /**
+     * Register message callback
+     */
+    onMessage(callback: (data: Uint8Array) => void): () => void;
+    /**
+     * Flush queued messages
+     */
+    private flushMessageQueue;
+    /**
+     * Convert Uint8Array to base64 string
+     */
+    private uint8ToBase64;
+    /**
+     * Convert base64 string to Uint8Array
+     */
+    private base64ToUint8;
+    /**
+     * Log debug messages
+     */
+    private log;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/providers/matrix/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/matrix/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAElE;;GAEG;AACH,MAAM,WAAW,YAAa,SAAQ,gBAAgB;IACpD,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAA;IACrB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,eAAgB,YAAW,SAAS;IAC/C,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,eAAe,CAAC,CAA4B;IACpD,OAAO,CAAC,YAAY,CAAiB;IACrC,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,qBAAqB,CAAiB;IAC9C,OAAO,CAAC,KAAK,CAAY;IAGzB,OAAO,CAAC,YAAY,CAAmB;IACvC,OAAO,CAAC,cAAc,CAAmB;IAEzC,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;OAEG;IACG,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IA0ClD;;OAEG;YACW,eAAe;IA6C7B;;OAEG;YACW,QAAQ;IA+BtB;;OAEG;YACW,SAAS;IAiBvB;;OAEG;YACW,QAAQ;IAsDtB;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAWjC;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAuC5B;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI;IAiB3D;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAYzB;;OAEG;IACH,OAAO,CAAC,aAAa;IASrB;;OAEG;IACH,OAAO,CAAC,aAAa;IASrB;;OAEG;IACH,OAAO,CAAC,GAAG;CAKZ"}

package/dist/providers/matrix/index.js

@@ -0,0 +1,329 @@
+/**
+ * Matrix Transport for Yjs
+ *
+ * Provides real-time synchronization using Matrix protocol.
+ *
+ * Features:
+ * - Decentralized federation
+ * - Guest access (no login required)
+ * - End-to-end encryption support
+ * - Persistent message history
+ * - Room-based collaboration
+ *
+ * @example
+ * ```ts
+ * import * as Y from 'yjs'
+ * import { GenericProvider } from 'y-generic'
+ * import { MatrixTransport } from 'y-generic/providers/matrix'
+ *
+ * const doc = new Y.Doc()
+ * const transport = new MatrixTransport()
+ *
+ * const provider = new GenericProvider(doc, transport)
+ * await provider.connect({
+ *   homeserverUrl: 'https://matrix.org',
+ *   room: '#my-room:matrix.org'
+ * })
+ * ```
+ */
+export class MatrixTransport {
+    constructor() {
+        this.config = null;
+        this._isConnected = false;
+        this.debug = false;
+        this.accessToken = null;
+        this.userId = null;
+        this.roomId = null;
+        this.syncToken = null;
+        this.syncRunning = false;
+        this.intentionalDisconnect = false;
+        this.txnId = 0;
+        // Message buffering
+        this.messageQueue = [];
+        this.receivedBuffer = [];
+    }
+    get isConnected() {
+        return this._isConnected;
+    }
+    /**
+     * Connect to Matrix homeserver and join room
+     */
+    async connect(config) {
+        this.config = config;
+        this.debug = config.debug ?? false;
+        this.intentionalDisconnect = false;
+        if (!config.homeserverUrl) {
+            throw new Error('Matrix homeserverUrl is required');
+        }
+        if (!config.room) {
+            throw new Error('Room identifier is required');
+        }
+        this.log(`🔌 Connecting to Matrix homeserver: ${config.homeserverUrl}`);
+        try {
+            // Get access token (guest registration or provided token)
+            if (config.accessToken && config.userId) {
+                this.accessToken = config.accessToken;
+                this.userId = config.userId;
+                this.log(`✅ Using provided credentials: ${this.userId}`);
+            }
+            else {
+                await this.registerAsGuest();
+            }
+            // Join or create room
+            await this.joinRoom(config.room);
+            // Start sync loop
+            this._isConnected = true;
+            this.startSync();
+            // Flush any queued messages
+            this.flushMessageQueue();
+            this.log(`✅ Connected to Matrix room: ${config.room}`);
+        }
+        catch (error) {
+            this.log(`❌ Connection failed:`, error);
+            throw error;
+        }
+    }
+    /**
+     * Register as guest on the homeserver
+     */
+    async registerAsGuest() {
+        if (!this.config)
+            throw new Error('Config not set');
+        this.log('👤 Registering as guest...');
+        const response = await fetch(`${this.config.homeserverUrl}/_matrix/client/v3/register?kind=guest`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({}),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            let errorData;
+            try {
+                errorData = JSON.parse(errorText);
+            }
+            catch {
+                errorData = { error: errorText };
+            }
+            // Provide helpful error messages
+            if (errorData.errcode === 'M_FORBIDDEN' || response.status === 403) {
+                throw new Error(`Guest registration is disabled on this homeserver.\n\n` +
+                    `Solutions:\n` +
+                    `1. Use a Matrix account: Provide accessToken and userId\n` +
+                    `2. Try a different homeserver that supports guest access\n` +
+                    `3. Run your own Matrix homeserver with guest access enabled\n\n` +
+                    `Many public homeservers have disabled guest access due to spam.`);
+            }
+            throw new Error(`Guest registration failed: ${errorText}`);
+        }
+        const data = await response.json();
+        this.accessToken = data.access_token;
+        this.userId = data.user_id;
+        this.log(`✅ Registered as guest: ${this.userId}`);
+    }
+    /**
+     * Join a Matrix room
+     */
+    async joinRoom(roomIdentifier) {
+        if (!this.accessToken)
+            throw new Error('Not authenticated');
+        this.log(`🚪 Joining room: ${roomIdentifier}`);
+        // Encode room identifier for URL
+        const encodedRoom = encodeURIComponent(roomIdentifier);
+        const response = await fetch(`${this.config.homeserverUrl}/_matrix/client/v3/join/${encodedRoom}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.accessToken}`,
+            },
+            body: JSON.stringify({}),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Failed to join room: ${error}`);
+        }
+        const data = await response.json();
+        this.roomId = data.room_id;
+        this.log(`✅ Joined room: ${this.roomId}`);
+    }
+    /**
+     * Start Matrix sync loop
+     */
+    async startSync() {
+        if (this.syncRunning)
+            return;
+        this.syncRunning = true;
+        this.log('🔄 Starting sync loop...');
+        while (this.syncRunning && !this.intentionalDisconnect) {
+            try {
+                await this.syncOnce();
+            }
+            catch (error) {
+                this.log('❌ Sync error:', error);
+                // Wait before retrying
+                await new Promise((resolve) => setTimeout(resolve, 5000));
+            }
+        }
+    }
+    /**
+     * Perform one sync request
+     */
+    async syncOnce() {
+        if (!this.accessToken)
+            return;
+        // Build sync URL with optional since token for long-polling
+        let url = `${this.config.homeserverUrl}/_matrix/client/v3/sync?timeout=30000`;
+        if (this.syncToken) {
+            url += `&since=${this.syncToken}`;
+        }
+        const response = await fetch(url, {
+            headers: {
+                Authorization: `Bearer ${this.accessToken}`,
+            },
+        });
+        if (!response.ok) {
+            throw new Error(`Sync failed: ${response.statusText}`);
+        }
+        const data = await response.json();
+        this.syncToken = data.next_batch;
+        // Process room events
+        if (data.rooms?.join?.[this.roomId]?.timeline?.events) {
+            const events = data.rooms.join[this.roomId].timeline.events;
+            for (const event of events) {
+                if (event.type === 'm.room.message' &&
+                    event.content?.msgtype === 'y.update') {
+                    // Ignore our own messages
+                    if (event.sender === this.userId)
+                        continue;
+                    // Decode the Yjs update from base64
+                    try {
+                        const updateBase64 = event.content.body;
+                        const update = this.base64ToUint8(updateBase64);
+                        this.log(`📨 Received ${update.length} bytes from ${event.sender}`);
+                        if (this.messageCallback) {
+                            this.messageCallback(update);
+                        }
+                        else {
+                            this.receivedBuffer.push(update);
+                        }
+                    }
+                    catch (error) {
+                        this.log('❌ Error decoding message:', error);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Disconnect from Matrix
+     */
+    async disconnect() {
+        this.log('🔌 Disconnecting from Matrix...');
+        this.intentionalDisconnect = true;
+        this.syncRunning = false;
+        this._isConnected = false;
+        this.accessToken = null;
+        this.userId = null;
+        this.roomId = null;
+        this.syncToken = null;
+    }
+    /**
+     * Send Yjs update to Matrix room
+     */
+    send(data) {
+        if (!this._isConnected || !this.roomId || !this.accessToken) {
+            // Queue message if not connected
+            this.messageQueue.push(data);
+            this.log(`⏳ Queued ${data.length} bytes (not connected)`);
+            return;
+        }
+        try {
+            // Encode update as base64 for JSON transport
+            const base64Data = this.uint8ToBase64(data);
+            // Send as custom message type
+            const txnId = `y${this.txnId++}_${Date.now()}`;
+            const url = `${this.config.homeserverUrl}/_matrix/client/v3/rooms/${encodeURIComponent(this.roomId)}/send/m.room.message/${txnId}`;
+            // Send asynchronously (don't await)
+            fetch(url, {
+                method: 'PUT',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.accessToken}`,
+                },
+                body: JSON.stringify({
+                    msgtype: 'y.update',
+                    body: base64Data,
+                }),
+            }).then((response) => {
+                if (response.ok) {
+                    this.log(`📤 Sent ${data.length} bytes`);
+                }
+                else {
+                    this.log(`❌ Send failed: ${response.statusText}`);
+                }
+            });
+        }
+        catch (error) {
+            this.log('❌ Send error:', error);
+        }
+    }
+    /**
+     * Register message callback
+     */
+    onMessage(callback) {
+        this.messageCallback = callback;
+        // Flush buffered messages
+        if (this.receivedBuffer.length > 0) {
+            this.log(`📦 Flushing ${this.receivedBuffer.length} buffered messages`);
+            for (const data of this.receivedBuffer) {
+                callback(data);
+            }
+            this.receivedBuffer = [];
+        }
+        return () => {
+            this.messageCallback = undefined;
+        };
+    }
+    /**
+     * Flush queued messages
+     */
+    flushMessageQueue() {
+        if (this.messageQueue.length === 0)
+            return;
+        this.log(`📦 Flushing ${this.messageQueue.length} queued messages`);
+        for (const data of this.messageQueue) {
+            this.send(data);
+        }
+        this.messageQueue = [];
+    }
+    /**
+     * Convert Uint8Array to base64 string
+     */
+    uint8ToBase64(bytes) {
+        let binary = '';
+        const len = bytes.length;
+        for (let i = 0; i < len; i++) {
+            binary += String.fromCharCode(bytes[i]);
+        }
+        return btoa(binary);
+    }
+    /**
+     * Convert base64 string to Uint8Array
+     */
+    base64ToUint8(base64) {
+        const binary = atob(base64);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        return bytes;
+    }
+    /**
+     * Log debug messages
+     */
+    log(...args) {
+        if (this.debug) {
+            console.log('[MatrixTransport]', ...args);
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/providers/matrix/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/providers/matrix/index.ts"],"names":[],"mappings":"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"}

package/dist/providers/nostr/index.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Nostr Transport Provider
+ *
+ * Serverless, decentralised synchronisation using the Nostr protocol.
+ * Binary Yjs updates are base64-encoded and published as signed Nostr events
+ * to one or more relays. Every connected client subscribes to the same room tag,
+ * so updates fan out through all configured relays automatically.
+ *
+ * Features:
+ * - No server setup required (uses public relays or your own)
+ * - Multi-relay fan-out for redundancy
+ * - Ephemeral or persistent identity (bring-your-own key pair)
+ * - Optional password to obfuscate the room tag (SHA-256)
+ * - Configurable history window to catch up on missed updates
+ * - Automatic deduplication (events from self are ignored)
+ *
+ * @example
+ * ```typescript
+ * import * as Y from 'yjs'
+ * import { GenericProvider } from 'y-generic'
+ * import { NostrTransport } from 'y-generic/providers/nostr'
+ * import { finalizeEvent, getPublicKey, SimplePool } from 'nostr-tools'
+ *
+ * const doc = new Y.Doc()
+ * const transport = new NostrTransport({ finalizeEvent, getPublicKey, SimplePool })
+ *
+ * const provider = new GenericProvider(doc, transport)
+ * await provider.connect({
+ *   room: 'my-doc',
+ *   relays: ['wss://relay.damus.io', 'wss://nos.lol'],
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With a persistent identity and password-protected room
+ * import { generateSecretKey } from 'nostr-tools/pure'
+ *
+ * const secretKey = generateSecretKey()  // persist this to keep identity
+ * const transport = new NostrTransport({ finalizeEvent, getPublicKey, SimplePool, secretKey })
+ *
+ * await provider.connect({
+ *   room: 'my-doc',
+ *   password: 'secret',
+ *   relays: ['wss://relay.damus.io'],
+ *   historyWindowSecs: 3600,  // fetch last hour of updates on connect
+ * })
+ * ```
+ */
+import type { Transport, ConnectionConfig } from '../../transport';
+/** Shape of a signed Nostr event returned by finalizeEvent. */
+interface NostrEvent {
+    id: string;
+    pubkey: string;
+    created_at: number;
+    kind: number;
+    tags: string[][];
+    content: string;
+    sig: string;
+}
+/** Shape of an unsigned event template passed to finalizeEvent. */
+interface EventTemplate {
+    kind: number;
+    created_at: number;
+    tags: string[][];
+    content: string;
+}
+/**
+ * Constructor options for NostrTransport.
+ *
+ * The three nostr-tools functions are injected so the transport doesn't bundle
+ * them as a hard dependency. Import them from `nostr-tools` or `nostr-tools/pure`.
+ */
+export interface NostrTransportOptions {
+    /**
+     * `finalizeEvent` from nostr-tools.
+     * Signs an event template with the given secret key.
+     * @example import { finalizeEvent } from 'nostr-tools/pure'
+     */
+    finalizeEvent: (template: EventTemplate, secretKey: Uint8Array) => NostrEvent;
+    /**
+     * `getPublicKey` from nostr-tools.
+     * Derives the hex public key from a secret key.
+     * @example import { getPublicKey } from 'nostr-tools/pure'
+     */
+    getPublicKey: (secretKey: Uint8Array) => string;
+    /**
+     * `SimplePool` class from nostr-tools.
+     * Manages WebSocket connections to multiple Nostr relays.
+     * @example import { SimplePool } from 'nostr-tools'
+     */
+    SimplePool: new () => {
+        subscribeMany(relays: string[], filters: object[], handlers: {
+            onevent?: (event: NostrEvent) => void;
+            oneose?: () => void;
+        }): {
+            close(): void;
+        };
+        publish(relays: string[], event: NostrEvent): Promise<string>[];
+        close(relays: string[]): void;
+    };
+    /**
+     * Secret key for signing events (32-byte Uint8Array).
+     * If omitted a random ephemeral key is generated on first connect — the
+     * identity changes on page reload, which is fine for anonymous editing.
+     * Persist this value (e.g. in localStorage) to maintain a stable identity.
+     * @example import { generateSecretKey } from 'nostr-tools/pure'
+     */
+    secretKey?: Uint8Array;
+    /**
+     * Custom Nostr event kind to use for Yjs update events.
+     * @default 27370
+     */
+    eventKind?: number;
+    /** Enable debug logging. @default false */
+    debug?: boolean;
+}
+/**
+ * Connection configuration for NostrTransport.
+ */
+export interface NostrConfig extends ConnectionConfig {
+    /** Room/document identifier. Mapped to the `r` tag on events. */
+    room: string;
+    /**
+     * Nostr relay WebSocket URLs to connect to.
+     * @default ['wss://relay.damus.io', 'wss://nos.lol', 'wss://relay.nostr.band']
+     */
+    relays?: string[];
+    /**
+     * Optional password. When provided, a SHA-256 hash of the password is
+     * appended to the room tag so the channel is only discoverable by peers
+     * that know the password. This is NOT encryption — use NIP-44 for that.
+     */
+    password?: string;
+    /**
+     * How many seconds of stored relay events to fetch on connect.
+     * Set to 0 to receive only real-time events (no catch-up).
+     * Increase for longer-lived documents that should survive peer restarts.
+     * @default 86400 (24 hours)
+     */
+    historyWindowSecs?: number;
+    /** Enable debug logging (overrides constructor option). */
+    debug?: boolean;
+}
+/**
+ * Nostr transport for y-generic.
+ *
+ * Publishes Yjs binary updates as base64-encoded Nostr events and subscribes
+ * to matching events from peers. Works in both browser and Node.js environments.
+ */
+export declare class NostrTransport implements Transport {
+    private readonly opts;
+    private _connected;
+    private _callback?;
+    private _buffer;
+    private pool;
+    private sub;
+    private relays;
+    private secretKey;
+    private pubkey;
+    private roomTag;
+    private readonly eventKind;
+    constructor(opts: NostrTransportOptions);
+    get isConnected(): boolean;
+    connect(config: NostrConfig): Promise<void>;
+    disconnect(): void;
+    send(data: Uint8Array): Promise<void>;
+    onMessage(callback: (data: Uint8Array) => void): () => void;
+    private _deliver;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/providers/nostr/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/nostr/index.ts"],"names":[],"mappings":"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"}