@meshagent/meshagent-react 0.4.0

package/dist/esm/document-connection-scope.js

@@ -0,0 +1,66 @@
+import { useEffect, useRef, useState } from 'react';
+/**
+ * Connects to a Mesh document inside an existing RoomClient and keeps it in sync.
+ *
+ * The function retries with an exponential back‑off (capped at 60 s) until the
+ * document becomes available or the component unmounts.
+ *
+ * @param room  An already‑connected RoomClient.
+ * @param path  Path to the document inside the room.
+ */
+export function useDocumentConnection({ room, path }) {
+    const [document, setDocument] = useState(null);
+    const [error, setError] = useState(null);
+    const retryCountRef = useRef(0);
+    const timeoutRef = useRef(null);
+    useEffect(() => {
+        let cancelled = false;
+        const openDocument = async () => {
+            try {
+                const doc = await room.sync.open(path);
+                if (cancelled)
+                    return;
+                // sleep for 100 ms to ensure the document is ready
+                await new Promise(resolve => setTimeout(resolve, 100));
+                setDocument(doc);
+                setError(null);
+            }
+            catch (err) {
+                if (cancelled)
+                    return;
+                setError(err);
+                // Exponential back‑off: 500 ms, 1 s, 2 s, … up to 60 s.
+                const delay = Math.min(60000, 500 * 2 ** retryCountRef.current);
+                retryCountRef.current += 1;
+                timeoutRef.current = setTimeout(openDocument, delay);
+            }
+        };
+        openDocument();
+        return () => {
+            cancelled = true;
+            if (timeoutRef.current !== null) {
+                clearTimeout(timeoutRef.current);
+                timeoutRef.current = null;
+            }
+            room.sync.close(path);
+            setDocument(null);
+            retryCountRef.current = 0;
+        };
+    }, [path]);
+    return {
+        document,
+        error,
+        loading: document === null && error == null,
+    };
+}
+export function useDocumentChanged({ document, onChanged }) {
+    useEffect(() => {
+        if (document) {
+            const s = document.listen(() => {
+                setTimeout(() => onChanged(document), 40);
+            });
+            onChanged(document);
+            return () => s.unsubscribe();
+        }
+    }, [document]);
+}

package/dist/esm/file-upload.d.ts

@@ -0,0 +1,43 @@
+import { EventEmitter, RoomClient } from "@meshagent/meshagent";
+export declare enum UploadStatus {
+    Initial = "initial",
+    Uploading = "uploading",
+    Completed = "completed",
+    Failed = "failed"
+}
+interface UploadStatusEvent {
+    status: UploadStatus;
+    progress?: number;
+}
+export declare abstract class FileUpload extends EventEmitter<UploadStatusEvent> {
+    path: string;
+    size: number;
+    protected _status: UploadStatus;
+    protected constructor(path: string, size?: number);
+    get status(): UploadStatus;
+    protected set status(value: UploadStatus);
+    abstract get bytesUploaded(): number;
+    abstract get done(): Promise<void>;
+    get filename(): string;
+    abstract startUpload(): void;
+}
+export declare class MeshagentFileUpload extends FileUpload {
+    readonly room: RoomClient;
+    readonly dataStream: AsyncIterable<Uint8Array>;
+    private _bytesUploaded;
+    private _done;
+    private _resolveDone;
+    private _rejectDone;
+    private _downloadUrl;
+    private _resolveUrl;
+    private _rejectUrl;
+    constructor(room: RoomClient, path: string, dataStream: AsyncIterable<Uint8Array>, size?: number, autoStart?: boolean);
+    static deferred(room: RoomClient, path: string, dataStream: AsyncIterable<Uint8Array>, size?: number): MeshagentFileUpload;
+    get bytesUploaded(): number;
+    get done(): Promise<void>;
+    /** Resolves to the server’s public download URL – like Dart version. */
+    get downloadUrl(): Promise<URL>;
+    startUpload(): void;
+    private _upload;
+}
+export {};

package/dist/esm/file-upload.js

@@ -0,0 +1,162 @@
+import { EventEmitter } from "@meshagent/meshagent";
+export var UploadStatus;
+(function (UploadStatus) {
+    UploadStatus["Initial"] = "initial";
+    UploadStatus["Uploading"] = "uploading";
+    UploadStatus["Completed"] = "completed";
+    UploadStatus["Failed"] = "failed";
+})(UploadStatus || (UploadStatus = {}));
+export class FileUpload extends EventEmitter {
+    constructor(path, size = 0) {
+        super();
+        Object.defineProperty(this, "path", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: path
+        });
+        Object.defineProperty(this, "size", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: size
+        });
+        Object.defineProperty(this, "_status", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: UploadStatus.Initial
+        });
+    }
+    get status() {
+        return this._status;
+    }
+    set status(value) {
+        if (this._status !== value) {
+            this._status = value;
+            this.emit("status", {
+                status: value,
+                progress: this.bytesUploaded,
+            });
+        }
+    }
+    get filename() {
+        return this.path.split("/").pop() ?? "";
+    }
+}
+export class MeshagentFileUpload extends FileUpload {
+    constructor(room, path, dataStream, size = 0, autoStart = true) {
+        super(path, size);
+        Object.defineProperty(this, "room", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: room
+        });
+        Object.defineProperty(this, "dataStream", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: dataStream
+        });
+        Object.defineProperty(this, "_bytesUploaded", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "_done", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_resolveDone", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_rejectDone", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_downloadUrl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_resolveUrl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_rejectUrl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this._done = new Promise((res, rej) => {
+            this._resolveDone = res;
+            this._rejectDone = rej;
+        });
+        this._downloadUrl = new Promise((res, rej) => {
+            this._resolveUrl = res;
+            this._rejectUrl = rej;
+        });
+        if (autoStart)
+            this._upload();
+    }
+    static deferred(room, path, dataStream, size = 0) {
+        return new MeshagentFileUpload(room, path, dataStream, size, false);
+    }
+    get bytesUploaded() {
+        return this._bytesUploaded;
+    }
+    get done() {
+        return this._done;
+    }
+    /** Resolves to the server’s public download URL – like Dart version. */
+    get downloadUrl() {
+        return this._downloadUrl;
+    }
+    startUpload() {
+        this._upload(); // idempotent guard inside _upload()
+    }
+    async _upload() {
+        if (this.status !== UploadStatus.Initial) {
+            throw new Error("upload already started or completed");
+        }
+        try {
+            const handle = await this.room.storage.open(this.path, { overwrite: true });
+            try {
+                this.status = UploadStatus.Uploading;
+                for await (const chunk of this.dataStream) {
+                    await this.room.storage.write(handle, chunk);
+                    this._bytesUploaded += chunk.length;
+                    this.emit("progress", {
+                        status: UploadStatus.Uploading,
+                        progress: this.bytesUploaded / this.size,
+                    });
+                }
+            }
+            finally {
+                await this.room.storage.close(handle);
+            }
+            this._resolveDone();
+            this.status = UploadStatus.Completed;
+            const urlStr = await this.room.storage.downloadUrl(this.path);
+            this._resolveUrl(new URL(urlStr));
+        }
+        catch (err) {
+            this.status = UploadStatus.Failed;
+            this._rejectDone(err);
+            this._rejectUrl(err);
+        }
+    }
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,5 @@
+export * from './chat';
+export * from './client-toolkits';
+export * from './document-connection-scope';
+export * from './file-upload';
+export * from './room-connection-scope';

package/dist/esm/index.js

@@ -0,0 +1,5 @@
+export * from './chat';
+export * from './client-toolkits';
+export * from './document-connection-scope';
+export * from './file-upload';
+export * from './room-connection-scope';

package/dist/esm/room-connection-scope.d.ts

@@ -0,0 +1,47 @@
+import { RoomClient } from '@meshagent/meshagent';
+export interface RoomConnectionInfo {
+    url: string;
+    jwt: string;
+}
+export declare const developmentAuthorization: ({ url, projectId, apiKeyId, participantName, roomName, secret, }: {
+    url: string;
+    projectId: string;
+    apiKeyId: string;
+    participantName: string;
+    roomName: string;
+    secret: string;
+}) => (() => Promise<RoomConnectionInfo>);
+export declare const staticAuthorization: ({ url, jwt, }: {
+    url: string;
+    jwt: string;
+}) => (() => Promise<RoomConnectionInfo>);
+export interface UseRoomConnectionOptions {
+    /** Async function that returns `{ url, jwt }` for the room. */
+    authorization: () => Promise<{
+        url: string;
+        jwt: string;
+    }>;
+    /** Enable the optional messaging layer (default = `true`). */
+    enableMessaging?: boolean;
+}
+/**
+ * Shape of the object returned by the hook.
+ */
+export interface UseRoomConnectionResult {
+    client: RoomClient | null;
+    state: 'authorizing' | 'connecting' | 'ready' | 'done';
+    ready: boolean;
+    done: boolean;
+    error: unknown;
+    dispose: () => void;
+}
+export declare function useRoomConnection(props: UseRoomConnectionOptions): UseRoomConnectionResult;
+export interface UseRoomIndicatorsResult {
+    typing: boolean;
+    thinking: boolean;
+}
+export interface UseRoomIndicatorsProps {
+    room: RoomClient | null;
+    path: string;
+}
+export declare function useRoomIndicators({ room, path }: UseRoomIndicatorsProps): UseRoomIndicatorsResult;

package/dist/esm/room-connection-scope.js

@@ -0,0 +1,141 @@
+import { useEffect, useState, useRef } from 'react';
+import { subscribe } from './subscribe-async-gen';
+import { RoomMessageEvent } from '@meshagent/meshagent';
+import { ParticipantToken, Protocol, RoomClient, WebSocketProtocolChannel, } from '@meshagent/meshagent';
+/* -------------------------------------------------
+ * Authorization helpers
+ * ------------------------------------------------- */
+export const developmentAuthorization = ({ url, projectId, apiKeyId, participantName, roomName, secret, }) => async () => {
+    const token = new ParticipantToken({
+        name: participantName,
+        projectId,
+        apiKeyId,
+    });
+    token.addRoomGrant(roomName);
+    token.addRoleGrant('user');
+    const jwt = await token.toJwt({ token: secret });
+    return { url, jwt };
+};
+export const staticAuthorization = ({ url, jwt, }) => async () => ({ url, jwt });
+export function useRoomConnection(props) {
+    const { authorization, enableMessaging = true, } = props;
+    const [client, setClient] = useState(null);
+    const [ready, setReady] = useState(false);
+    const [state, setState] = useState('authorizing');
+    const [error, setError] = useState(null);
+    // Keep the latest client in a ref so we can call `dispose` in cleanup.
+    const clientRef = useRef(null);
+    clientRef.current = client;
+    // Instance method exposed to consumers (rarely needed).
+    const dispose = () => {
+        clientRef.current?.dispose();
+        setState('done');
+    };
+    useEffect(() => {
+        let cancelled = false;
+        const connect = async () => {
+            try {
+                // 1️⃣  Get connection credentials
+                const { url, jwt } = await authorization();
+                if (cancelled)
+                    return;
+                const room = new RoomClient({
+                    protocol: new Protocol({
+                        channel: new WebSocketProtocolChannel({ url, jwt }),
+                    }),
+                });
+                setClient(room);
+                setState('connecting');
+                await room.start({
+                    onDone: () => {
+                        if (cancelled)
+                            return;
+                        setState('done');
+                    },
+                    onError: (e) => {
+                        if (cancelled)
+                            return;
+                        setError(e);
+                        setState('done');
+                    },
+                });
+                if (enableMessaging) {
+                    await room.messaging.enable();
+                }
+                if (cancelled)
+                    return;
+                setState('ready');
+                setReady(true);
+            }
+            catch (e) {
+                if (cancelled)
+                    return;
+                setError(e);
+                setState('done');
+            }
+        };
+        connect();
+        return () => {
+            // React unmount or deps change → cancel & dispose
+            cancelled = true;
+            dispose();
+        };
+        // eslint‑disable‑next‑line react-hooks/exhaustive-deps
+    }, []); // run once, just like componentDidMount
+    return {
+        client,
+        state,
+        ready,
+        done: state === 'done',
+        error,
+        dispose,
+    };
+}
+export function useRoomIndicators({ room, path }) {
+    const typingMap = useRef({});
+    const thinkingSet = useRef(new Set());
+    const [typing, setState] = useState(false);
+    const [thinking, setThinking] = useState(false);
+    useEffect(() => {
+        if (!room)
+            return;
+        const s = subscribe(room.listen(), {
+            next: (event) => {
+                if (event instanceof RoomMessageEvent) {
+                    const { message } = event;
+                    // Ignore messages from ourselves
+                    if (message.fromParticipantId === room.localParticipant?.id) {
+                        return;
+                    }
+                    // Ignore messages not for this path
+                    if (message.message.path !== path) {
+                        return;
+                    }
+                    if (message.type === "typing") {
+                        // Clear any existing timer for this participant
+                        clearTimeout(typingMap.current[message.fromParticipantId]);
+                        // Set a new timer to remove typing after 1 second
+                        typingMap.current[message.fromParticipantId] = setTimeout(() => {
+                            delete typingMap.current[message.fromParticipantId];
+                            setState(Object.keys(typingMap.current).length > 0);
+                        }, 1000);
+                        // Update typing state
+                        setState(Object.keys(typingMap.current).length > 0);
+                    }
+                    else if (message.type === "thinking") {
+                        if (message.message.thinking) {
+                            thinkingSet.current.add(message.fromParticipantId);
+                        }
+                        else {
+                            thinkingSet.current.delete(message.fromParticipantId);
+                        }
+                        // Update thinking state
+                        setThinking(thinkingSet.current.size > 0);
+                    }
+                }
+            },
+        });
+        return () => s.unsubscribe();
+    }, [room, path]);
+    return { typing, thinking };
+}

package/dist/esm/subscribe-async-gen.d.ts

@@ -0,0 +1,10 @@
+type Subscriber<T> = {
+    next: (value: T) => void;
+    error?: (err: unknown) => void;
+    complete?: () => void;
+};
+export interface Subscription {
+    unsubscribe: () => void;
+}
+export declare function subscribe<T>(iterable: AsyncIterable<T>, { next, error, complete }: Subscriber<T>): Subscription;
+export {};

package/dist/esm/subscribe-async-gen.js

@@ -0,0 +1,32 @@
+function abortableNext(iterator, signal) {
+    const nextP = iterator.next();
+    const abortP = new Promise((_, rej) => {
+        signal.addEventListener("abort", () => rej(new Error("aborted")), { once: true });
+    });
+    return Promise.race([nextP, abortP]);
+}
+export function subscribe(iterable, { next, error, complete }) {
+    const controller = new AbortController();
+    const it = iterable[Symbol.asyncIterator]();
+    (async () => {
+        try {
+            while (!controller.signal.aborted) {
+                const { value, done } = await abortableNext(it, controller.signal);
+                if (done)
+                    break;
+                next(value);
+            }
+            if (!controller.signal.aborted && complete) {
+                complete();
+            }
+        }
+        catch (err) {
+            if (!controller.signal.aborted && error) {
+                error(err);
+            }
+        }
+    })();
+    return {
+        unsubscribe: () => controller.abort(),
+    };
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+    "name": "@meshagent/meshagent-react",
+    "version": "0.4.0",
+    "description": "Meshagent React Client",
+    "homepage": "https://www.meshagent.com",
+    "scripts": {
+        "build": "mkdir -p dist && ./scripts/build.sh"
+    },
+    "author": "Meshagent Software",
+    "license": "Apache-2.0",
+    "type": "module",
+    "module": "dist/esm/index.js",
+    "main": "./dist/esm/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "module": "./dist/esm/index.js",
+            "default": "./dist/cjs/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist",
+        "!dist/**/test",
+        "LICENSE",
+        "README.md",
+        "CHANGELOG.md"
+    ],
+    "devDependencies": {
+        "@types/react": "^19.1.8",
+        "@types/react-dom": "^19.1.6"
+    },
+    "dependencies": {
+        "@meshagent/meshagent": "^0.4.0",
+        "react-dom": "^19.1.0",
+        "typescript": "^5.8.3",
+        "uuid": "^11.1.0"
+    }
+}