@fluxy-chat/sdk 0.1.0

package/dist/message-stream.d.ts

@@ -0,0 +1,34 @@
+import type { FluxyChatRoomConnection } from "./room-connection";
+export interface FluxyMessageStreamOptions {
+    /** Min interval between delta frames (default 120ms). */
+    flushIntervalMs?: number;
+    parentId?: number | null;
+}
+/**
+ * Streams text into a single persisted room message (Worker `type: "stream"`).
+ * Throttles DB writes; clients receive `message` + `edit` events with `streaming: true|false`.
+ */
+export declare class FluxyMessageStream {
+    private readonly connection;
+    private readonly agentId;
+    private readonly flushIntervalMs;
+    private readonly parentId;
+    private buffer;
+    private messageId;
+    private closed;
+    private started;
+    private flushTimer;
+    private lastFlushMs;
+    private captureBound;
+    constructor(connection: FluxyChatRoomConnection, agentId: string, options?: FluxyMessageStreamOptions);
+    get activeMessageId(): number | null;
+    push(chunk: string): void;
+    end(): void;
+    abort(): void;
+    private bindCapture;
+    private scheduleFlush;
+    private flush;
+    private resolveMessageId;
+    private clearFlushTimer;
+    private assertOpen;
+}

package/dist/message-stream.js

@@ -0,0 +1,150 @@
+import { FluxySendError } from "./errors";
+const DEFAULT_FLUSH_MS = 120;
+/**
+ * Streams text into a single persisted room message (Worker `type: "stream"`).
+ * Throttles DB writes; clients receive `message` + `edit` events with `streaming: true|false`.
+ */
+export class FluxyMessageStream {
+    constructor(connection, agentId, options = {}) {
+        this.buffer = "";
+        this.messageId = null;
+        this.closed = false;
+        this.started = false;
+        this.flushTimer = null;
+        this.lastFlushMs = 0;
+        this.captureBound = false;
+        this.connection = connection;
+        this.agentId = agentId;
+        this.flushIntervalMs = options.flushIntervalMs ?? DEFAULT_FLUSH_MS;
+        this.parentId = options.parentId ?? null;
+    }
+    get activeMessageId() {
+        return this.messageId;
+    }
+    push(chunk) {
+        this.assertOpen("push");
+        if (!chunk)
+            return;
+        this.bindCapture();
+        this.buffer += chunk;
+        if (!this.started) {
+            this.started = true;
+            this.connection.sendJson({
+                type: "stream",
+                op: "start",
+                userId: this.agentId,
+                content: this.buffer,
+                parentId: this.parentId,
+            });
+        }
+        this.scheduleFlush();
+    }
+    end() {
+        this.assertOpen("end");
+        this.closed = true;
+        this.clearFlushTimer();
+        if (!this.started)
+            return;
+        void this.flush(true);
+    }
+    abort() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.clearFlushTimer();
+        if (!this.messageId)
+            return;
+        try {
+            this.connection.sendJson({
+                type: "stream",
+                op: "abort",
+                userId: this.agentId,
+                messageId: this.messageId,
+            });
+        }
+        catch {
+            /* socket closed */
+        }
+        this.messageId = null;
+        this.buffer = "";
+    }
+    bindCapture() {
+        if (this.captureBound)
+            return;
+        this.captureBound = true;
+        this.connection.addEventListener("message", (event) => {
+            if (this.messageId)
+                return;
+            if (event.type === "stream" && event.op === "started") {
+                this.messageId = event.id;
+                return;
+            }
+            if (event.type === "message" &&
+                event.streaming &&
+                event.userId === this.agentId &&
+                Number.isFinite(event.id)) {
+                this.messageId = event.id;
+            }
+        });
+    }
+    scheduleFlush() {
+        if (this.closed)
+            return;
+        const elapsed = Date.now() - this.lastFlushMs;
+        if (elapsed >= this.flushIntervalMs) {
+            void this.flush(false);
+            return;
+        }
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            void this.flush(false);
+        }, this.flushIntervalMs - elapsed);
+    }
+    async flush(isFinal) {
+        if (!this.started)
+            return;
+        const id = await this.resolveMessageId(isFinal);
+        if (!id)
+            return;
+        try {
+            this.connection.sendJson({
+                type: "stream",
+                op: isFinal ? "end" : "delta",
+                userId: this.agentId,
+                messageId: id,
+                content: this.buffer,
+            });
+            this.lastFlushMs = Date.now();
+        }
+        catch {
+            /* socket closed */
+        }
+        if (isFinal) {
+            this.buffer = "";
+            this.messageId = null;
+            this.started = false;
+        }
+    }
+    async resolveMessageId(isFinal) {
+        if (this.messageId)
+            return this.messageId;
+        const deadline = Date.now() + (isFinal ? 3000 : 500);
+        while (!this.messageId && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, 20));
+        }
+        return this.messageId;
+    }
+    clearFlushTimer() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+    assertOpen(op) {
+        if (this.closed) {
+            throw new FluxySendError(`Cannot call ${op}() on a closed FluxyMessageStream.`);
+        }
+    }
+}

package/dist/room-connection.d.ts

@@ -0,0 +1,63 @@
+import type { FluxyChatClient, FluxyChatEvent, FluxyChatMessage } from "./index";
+import { FluxyAuthError } from "./errors";
+export type FluxyRoomConnectionStatus = "idle" | "connecting" | "connected" | "reconnecting" | "disconnected";
+export interface FluxyRoomConnectionOptions {
+    /** Max reconnect tries before staying disconnected (default 8). */
+    maxReconnectAttempts?: number;
+    /** First backoff step in ms (default 500). */
+    baseBackoffMs?: number;
+    /** Backoff cap in ms (default 20_000). */
+    maxBackoffMs?: number;
+    /** Refetch REST history after each successful reconnect (default true). */
+    replayHistoryOnReconnect?: boolean;
+    historyLimit?: number;
+    onAuthError?: (error: FluxyAuthError) => void;
+    onConnectionError?: (error: Error) => void;
+    onStatusChange?: (status: FluxyRoomConnectionStatus) => void;
+    /** Called when max reconnect attempts are exhausted (not on auth failure). */
+    onReconnectFailed?: () => void;
+}
+type MessageListener = (event: FluxyChatEvent) => void;
+export interface FluxyWaitForOptions {
+    timeout?: number;
+}
+export declare class FluxyChatRoomConnection {
+    private readonly client;
+    private readonly roomId;
+    private readonly options;
+    private ws;
+    private status;
+    private reconnectAttempt;
+    private reconnectTimer;
+    private intentionallyClosed;
+    private hasConnectedOnce;
+    private pendingHistoryReplay;
+    private lastError;
+    private listeners;
+    private waitForEntries;
+    private seenIds;
+    private seenIdsSet;
+    constructor(client: FluxyChatClient, roomId: string, options?: FluxyRoomConnectionOptions);
+    get connectionStatus(): FluxyRoomConnectionStatus;
+    get reconnectAttempts(): number;
+    getLastError(): Error | null;
+    get readyState(): number;
+    addEventListener(_type: "message", listener: MessageListener): void;
+    removeEventListener(_type: "message", listener: MessageListener): void;
+    connect(): void;
+    close(code?: number): void;
+    sendJson(payload: Record<string, unknown>): void;
+    /**
+     * Resolves when an incoming event matches `predicate` (typically a `message` event).
+     */
+    waitFor(predicate: (event: FluxyChatEvent) => boolean, options?: FluxyWaitForOptions): Promise<FluxyChatMessage>;
+    private rejectAllWaitFor;
+    private setStatus;
+    private clearReconnectTimer;
+    private openSocket;
+    private scheduleReconnect;
+    private replayHistory;
+    private trackMessageId;
+    private deliver;
+}
+export {};

package/dist/room-connection.js

@@ -0,0 +1,244 @@
+import { FluxyAuthError, FluxyConnectionError, FluxySendError, FluxyTimeoutError, FLUXY_WS_CLOSE_NORMAL, computeReconnectBackoffMs, mapWebSocketCloseToError, } from "./errors";
+const SEEN_IDS_MAX = 10000;
+const DEFAULT_WAIT_TIMEOUT_MS = 30000;
+export class FluxyChatRoomConnection {
+    constructor(client, roomId, options = {}) {
+        this.ws = null;
+        this.status = "idle";
+        this.reconnectAttempt = 0;
+        this.reconnectTimer = null;
+        this.intentionallyClosed = false;
+        this.hasConnectedOnce = false;
+        this.pendingHistoryReplay = false;
+        this.lastError = null;
+        this.listeners = [];
+        this.waitForEntries = [];
+        this.seenIds = [];
+        this.seenIdsSet = new Set();
+        this.client = client;
+        this.roomId = roomId;
+        this.options = {
+            maxReconnectAttempts: options.maxReconnectAttempts ?? 8,
+            baseBackoffMs: options.baseBackoffMs ?? 500,
+            maxBackoffMs: options.maxBackoffMs ?? 20000,
+            replayHistoryOnReconnect: options.replayHistoryOnReconnect ?? true,
+            historyLimit: options.historyLimit ?? 50,
+            ...options,
+        };
+    }
+    get connectionStatus() {
+        return this.status;
+    }
+    get reconnectAttempts() {
+        return this.reconnectAttempt;
+    }
+    getLastError() {
+        return this.lastError;
+    }
+    get readyState() {
+        return this.ws?.readyState ?? WebSocket.CLOSED;
+    }
+    addEventListener(_type, listener) {
+        this.listeners.push(listener);
+    }
+    removeEventListener(_type, listener) {
+        this.listeners = this.listeners.filter((cb) => cb !== listener);
+    }
+    connect() {
+        this.intentionallyClosed = false;
+        this.openSocket();
+    }
+    close(code = FLUXY_WS_CLOSE_NORMAL) {
+        this.intentionallyClosed = true;
+        this.rejectAllWaitFor(new FluxySendError("Connection closed."));
+        this.clearReconnectTimer();
+        if (this.ws) {
+            try {
+                this.ws.close(code);
+            }
+            catch {
+                /* ignore */
+            }
+            this.ws = null;
+        }
+        this.setStatus("disconnected");
+    }
+    sendJson(payload) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new FluxySendError();
+        }
+        this.ws.send(JSON.stringify(payload));
+    }
+    /**
+     * Resolves when an incoming event matches `predicate` (typically a `message` event).
+     */
+    waitFor(predicate, options = {}) {
+        const timeoutMs = options.timeout ?? DEFAULT_WAIT_TIMEOUT_MS;
+        if (this.status !== "connected") {
+            return Promise.reject(new FluxySendError("waitFor requires an open connection. Call connect() and wait until connected."));
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.waitForEntries = this.waitForEntries.filter((entry) => entry.timer !== timer);
+                reject(new FluxyTimeoutError(timeoutMs));
+            }, timeoutMs);
+            this.waitForEntries.push({
+                predicate,
+                resolve,
+                reject,
+                timer,
+            });
+        });
+    }
+    rejectAllWaitFor(error) {
+        const entries = [...this.waitForEntries];
+        this.waitForEntries = [];
+        for (const entry of entries) {
+            clearTimeout(entry.timer);
+            entry.reject(error);
+        }
+    }
+    setStatus(next) {
+        if (this.status === next)
+            return;
+        this.status = next;
+        this.options.onStatusChange?.(next);
+    }
+    clearReconnectTimer() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    openSocket() {
+        this.clearReconnectTimer();
+        this.setStatus(this.hasConnectedOnce && this.reconnectAttempt > 0 ? "reconnecting" : "connecting");
+        const ws = this.client.connect(this.roomId);
+        this.ws = ws;
+        ws.addEventListener("open", () => {
+            this.hasConnectedOnce = true;
+            this.reconnectAttempt = 0;
+            this.lastError = null;
+            this.setStatus("connected");
+            if (this.pendingHistoryReplay && this.options.replayHistoryOnReconnect) {
+                void this.replayHistory();
+            }
+            this.pendingHistoryReplay = false;
+        });
+        ws.addEventListener("message", (event) => {
+            let data;
+            try {
+                data = JSON.parse(String(event.data));
+            }
+            catch {
+                return;
+            }
+            if (data.type === "error") {
+                // eslint-disable-next-line no-console
+                console.error("[fluxychat] worker error:", data.message);
+            }
+            this.deliver(data);
+        });
+        ws.addEventListener("close", (event) => {
+            this.ws = null;
+            if (this.intentionallyClosed) {
+                this.setStatus("disconnected");
+                return;
+            }
+            const mapped = mapWebSocketCloseToError(event.code, event.reason || "");
+            if (mapped instanceof FluxyAuthError) {
+                this.lastError = mapped;
+                this.options.onAuthError?.(mapped);
+                this.options.onConnectionError?.(mapped);
+                this.rejectAllWaitFor(mapped);
+                this.setStatus("disconnected");
+                return;
+            }
+            if (mapped) {
+                this.lastError = mapped;
+                this.options.onConnectionError?.(mapped);
+            }
+            this.scheduleReconnect();
+        });
+    }
+    scheduleReconnect() {
+        this.pendingHistoryReplay = true;
+        this.reconnectAttempt += 1;
+        if (this.reconnectAttempt > this.options.maxReconnectAttempts) {
+            this.setStatus("disconnected");
+            this.rejectAllWaitFor(new FluxyConnectionError(0, "reconnect_failed", "WebSocket reconnect attempts exhausted."));
+            this.options.onReconnectFailed?.();
+            return;
+        }
+        this.setStatus("reconnecting");
+        const delay = computeReconnectBackoffMs(this.reconnectAttempt, this.options.baseBackoffMs, this.options.maxBackoffMs);
+        this.clearReconnectTimer();
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            if (!this.intentionallyClosed) {
+                this.openSocket();
+            }
+        }, delay);
+    }
+    async replayHistory() {
+        try {
+            const messages = await this.client.fetchMessages(this.roomId, this.options.historyLimit);
+            this.deliver({ type: "history", messages });
+        }
+        catch {
+            /* history replay is best-effort */
+        }
+    }
+    trackMessageId(id) {
+        if (!Number.isFinite(id) || this.seenIdsSet.has(id))
+            return;
+        if (this.seenIds.length >= SEEN_IDS_MAX) {
+            const evicted = this.seenIds.shift();
+            if (evicted !== undefined)
+                this.seenIdsSet.delete(evicted);
+        }
+        this.seenIds.push(id);
+        this.seenIdsSet.add(id);
+    }
+    deliver(event) {
+        if (event.type === "history") {
+            this.seenIds = [];
+            this.seenIdsSet.clear();
+            for (const msg of event.messages) {
+                if (Number.isFinite(msg.id))
+                    this.trackMessageId(msg.id);
+            }
+        }
+        else if (event.type === "message" && Number.isFinite(event.id)) {
+            if (this.seenIdsSet.has(event.id) && !event.streaming)
+                return;
+            this.trackMessageId(event.id);
+        }
+        const satisfied = [];
+        for (const entry of this.waitForEntries) {
+            if (entry.predicate(event)) {
+                satisfied.push(entry);
+            }
+        }
+        if (satisfied.length > 0) {
+            this.waitForEntries = this.waitForEntries.filter((entry) => !satisfied.includes(entry));
+            for (const entry of satisfied) {
+                clearTimeout(entry.timer);
+                if (event.type === "message") {
+                    entry.resolve(event);
+                }
+                else {
+                    entry.reject(new Error(`waitFor matched non-message event type "${event.type}"`));
+                }
+            }
+        }
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                /* listener errors must not break the connection */
+            }
+        }
+    }
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@fluxy-chat/sdk",
+  "version": "0.1.0",
+  "description": "Fluxychat JavaScript/TypeScript SDK — WebSocket rooms, REST messages, useChat hook",
+  "license": "MIT",
+  "author": "Fluxychat",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlessandroFare/fluxychat.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/AlessandroFare/fluxychat/tree/main/packages/sdk#readme",
+  "bugs": {
+    "url": "https://github.com/AlessandroFare/fluxychat/issues"
+  },
+  "keywords": [
+    "chat",
+    "websocket",
+    "realtime",
+    "cloudflare",
+    "fluxychat"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "dist/room-connection.js",
+    "dist/room-connection.d.ts",
+    "dist/errors.js",
+    "dist/errors.d.ts",
+    "dist/message-stream.js",
+    "dist/message-stream.d.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node node_modules/typescript/bin/tsc -p tsconfig.json",
+    "prepublishOnly": "pnpm run build",
+    "dev": "tsc -w -p tsconfig.json",
+    "lint": "eslint src --ext .ts,.tsx",
+    "test": "pnpm exec vitest run"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "@types/react": "^19.2.14",
+    "typescript": "latest",
+    "vitest": "^4.1.5"
+  }
+}