@fluxy-chat/sdk 0.1.0 → 0.2.1

package/dist/index.js

@@ -1,21 +1,47 @@
 export { FluxyAuthError, FluxyConnectionError, FluxySendError, FluxyTimeoutError, FLUXY_WS_CLOSE_NORMAL, FLUXY_WS_CLOSE_POLICY, computeReconnectBackoffMs, mapWebSocketCloseToError, } from "./errors";
 export { FluxyChatRoomConnection, } from "./room-connection";
 export { FluxyMessageStream } from "./message-stream";
+export { clampHistoryLimit, mergeMessagesChronological, sortMessagesChronological, MAX_HISTORY_LIMIT, } from "./message-history";
+export { decodeFluxyJwtPayload, jwtRefreshDelayMs } from "./jwt-utils";
+export { FLUXY_MAX_MESSAGE_LENGTH, normalizeRoomMember, normalizeRoomMembers, } from "./room-rest";
+export { validateAgentOutboundMessage, buildAgentOutboundWsPayload, } from "./agent-outbound";
+export { FluxyRealtimeProvider, } from "./realtime-provider";
+export { useFluxyChat, useFluxyChatOptional } from "./use-fluxy-chat";
+export { useChat } from "./use-chat";
+export { useRooms } from "./use-rooms";
 import { FluxyChatRoomConnection } from "./room-connection";
-import { FluxyAuthError, FluxySendError } from "./errors";
+import { clampHistoryLimit, sortMessagesChronological } from "./message-history";
+import { normalizeRoomMembers } from "./room-rest";
+import { trimTrailingSlashes } from "./url-utils";
+const AUDIO_FILE_SUFFIXES = [".webm", ".m4a", ".mp3", ".wav", ".ogg"];
+function fileNameLooksLikeAudio(fileName) {
+    const lower = fileName.toLowerCase();
+    for (const ext of AUDIO_FILE_SUFFIXES) {
+        if (lower.endsWith(ext))
+            return true;
+    }
+    return false;
+}
 function inferAttachmentKind(contentType, fileName) {
     const ct = (contentType || "").toLowerCase();
     if (ct.startsWith("image/"))
         return "image";
     if (ct.startsWith("audio/"))
         return "audio";
-    if (/\.(webm|m4a|mp3|wav|ogg)$/i.test(fileName))
+    if (fileNameLooksLikeAudio(fileName))
         return "audio";
     return "file";
 }
+function httpUrlToWebSocketBase(url) {
+    if (url.startsWith("https://"))
+        return `wss://${url.slice("https://".length)}`;
+    if (url.startsWith("http://"))
+        return `ws://${url.slice("http://".length)}`;
+    return url;
+}
 export class FluxyChatClient {
     constructor(options) {
-        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.baseUrl = trimTrailingSlashes(options.baseUrl);
         this.userId = options.userId;
         this.apiKey = options.apiKey;
         this.token = options.token;
@@ -37,7 +63,7 @@ export class FluxyChatClient {
         return undefined;
     }
     connect(roomId) {
-        const wsBase = this.baseUrl.replace(/^http/, "ws");
+        const wsBase = httpUrlToWebSocketBase(this.baseUrl);
         const url = new URL(`/ws/room/${encodeURIComponent(roomId)}`, wsBase.endsWith("/") ? wsBase : `${wsBase}/`);
         if (this.apiKey) {
             url.searchParams.set("apiKey", this.apiKey);
@@ -64,20 +90,42 @@ export class FluxyChatClient {
         url.searchParams.set("userId", this.userId);
         return new EventSource(url.toString());
     }
-    async fetchMessages(roomId, limit = 50) {
+    async fetchMessages(roomId, limitOrOptions = 50) {
         const trimmedRoomId = roomId.trim();
         if (!trimmedRoomId)
             return [];
+        const options = typeof limitOrOptions === "number" ? { limit: limitOrOptions } : limitOrOptions;
+        const limit = clampHistoryLimit(options.limit);
         const url = new URL("/api/messages", this.baseUrl);
         url.searchParams.set("roomId", trimmedRoomId);
         url.searchParams.set("limit", String(limit));
+        if (options.before?.trim()) {
+            url.searchParams.set("before", options.before.trim());
+        }
         const res = await fetch(url.toString(), {
             headers: this.authHeaders(),
         });
         if (!res.ok)
             throw new Error(`Failed to fetch messages: ${res.status}`);
         const body = await res.json();
-        return body.messages ?? [];
+        return sortMessagesChronological((body.messages ?? []));
+    }
+    async fetchRoomMembers(roomId) {
+        const trimmedRoomId = roomId.trim();
+        if (!trimmedRoomId)
+            return [];
+        const url = new URL(`/rooms/${encodeURIComponent(trimmedRoomId)}/members`, this.baseUrl);
+        const res = await fetch(url.toString(), {
+            headers: this.authHeaders(),
+        });
+        if (!res.ok)
+            throw new Error(`Failed to fetch room members: ${res.status}`);
+        const body = await res.json();
+        return normalizeRoomMembers(body.members ?? []);
+    }
+    /** Alias for {@link fetchMessages} — chronological room history via REST. */
+    fetchRoomHistory(roomId, options) {
+        return this.fetchMessages(roomId, options ?? {});
     }
     async listRooms(type) {
         const url = new URL("/rooms", this.baseUrl);
@@ -399,445 +447,3 @@ export class FluxyChatClient {
             throw new Error(`Failed to delete webhook: ${res.status}`);
     }
 }
-// React hook convenience API
-import { useEffect, useRef, useState } from "react";
-export function useChat({ roomId, client, agentId }) {
-    const [messages, setMessages] = useState([]);
-    const [online, setOnline] = useState(0);
-    const [typingUsers, setTypingUsers] = useState({});
-    const [seenBy, setSeenBy] = useState({});
-    const [onlineUsers, setOnlineUsers] = useState([]);
-    const [connected, setConnected] = useState(false);
-    const [connectionStatus, setConnectionStatus] = useState("connecting");
-    const [reconnectAttempt, setReconnectAttempt] = useState(0);
-    const [connectionError, setConnectionError] = useState(null);
-    const [agentTyping, setAgentTyping] = useState(false);
-    const [wsTypingAgentId, setWsTypingAgentId] = useState(null);
-    const [invokeTypingAgentId, setInvokeTypingAgentId] = useState(null);
-    const [reactions, setReactions] = useState({});
-    const connectionRef = useRef(null);
-    const sseRef = useRef(null);
-    const pollTimerRef = useRef(null);
-    useEffect(() => {
-        let active = true;
-        const trimmedRoomId = roomId.trim();
-        const MAX_WS_RECONNECT_ATTEMPTS = 6;
-        const POLL_INTERVAL_MS = 4000;
-        const stopPollingFallback = () => {
-            if (pollTimerRef.current) {
-                clearInterval(pollTimerRef.current);
-                pollTimerRef.current = null;
-            }
-        };
-        const stopSSEFallback = () => {
-            if (sseRef.current) {
-                sseRef.current.close();
-                sseRef.current = null;
-            }
-        };
-        const startPollingFallback = () => {
-            stopPollingFallback();
-            stopSSEFallback();
-            const tick = async () => {
-                if (!active)
-                    return;
-                try {
-                    const next = await client.fetchMessages(trimmedRoomId);
-                    if (active)
-                        setMessages(next);
-                }
-                catch {
-                    /* ignore transient poll errors */
-                }
-            };
-            void tick();
-            pollTimerRef.current = setInterval(tick, POLL_INTERVAL_MS);
-        };
-        const startSSEFallback = () => {
-            stopPollingFallback();
-            stopSSEFallback();
-            const es = client.connectSSE(trimmedRoomId);
-            if (!es) {
-                startPollingFallback();
-                return;
-            }
-            sseRef.current = es;
-            setConnectionStatus("sse");
-            es.addEventListener("message", (event) => {
-                if (!active)
-                    return;
-                try {
-                    const data = JSON.parse(event.data);
-                    handleEvent(data);
-                }
-                catch {
-                    /* ignore malformed SSE events */
-                }
-            });
-            es.addEventListener("error", () => {
-                if (!active)
-                    return;
-                stopSSEFallback();
-                startPollingFallback();
-                setConnectionStatus("polling");
-            });
-        };
-        const handleEvent = (data) => {
-            if (data.type === "history") {
-                setMessages(data.messages);
-            }
-            else if (data.type === "message") {
-                setMessages((prev) => {
-                    const idx = prev.findIndex((m) => m.id === data.id);
-                    if (idx >= 0) {
-                        const next = [...prev];
-                        next[idx] = { ...next[idx], ...data };
-                        return next;
-                    }
-                    return [...prev, data];
-                });
-            }
-            else if (data.type === "presence") {
-                setOnline(data.online);
-                if (data.users)
-                    setOnlineUsers(data.users);
-            }
-            else if (data.type === "typing") {
-                setTypingUsers((prev) => ({
-                    ...prev,
-                    [data.userId]: data.isTyping,
-                }));
-            }
-            else if (data.type === "agentTyping") {
-                setAgentTyping(data.isTyping);
-                setWsTypingAgentId(data.isTyping ? data.agentId : null);
-            }
-            else if (data.type === "edit") {
-                setMessages((prev) => prev.map((m) => m.id === data.id
-                    ? {
-                        ...m,
-                        content: data.content,
-                        editedAt: data.editedAt,
-                        streaming: data.streaming ?? false,
-                    }
-                    : m));
-            }
-            else if (data.type === "reaction") {
-                setReactions((prev) => {
-                    const byMessage = { ...prev };
-                    const current = { ...(byMessage[data.messageId] || {}) };
-                    const existingCount = current[data.emoji] || 0;
-                    if (data.op === "remove") {
-                        const nextCount = Math.max(existingCount - 1, 0);
-                        if (nextCount === 0) {
-                            delete current[data.emoji];
-                        }
-                        else {
-                            current[data.emoji] = nextCount;
-                        }
-                    }
-                    else {
-                        current[data.emoji] = existingCount + 1;
-                    }
-                    if (Object.keys(current).length === 0) {
-                        delete byMessage[data.messageId];
-                    }
-                    else {
-                        byMessage[data.messageId] = current;
-                    }
-                    return byMessage;
-                });
-            }
-            else if (data.type === "read") {
-                setSeenBy((prev) => {
-                    const existing = prev[data.messageId] || [];
-                    if (existing.includes(data.userId))
-                        return prev;
-                    return {
-                        ...prev,
-                        [data.messageId]: [...existing, data.userId],
-                    };
-                });
-            }
-            else if (data.type === "delete") {
-                if (data.hard) {
-                    setMessages((prev) => prev.filter((m) => m.id !== data.id));
-                }
-                else {
-                    setMessages((prev) => prev.map((m) => m.id === data.id
-                        ? { ...m, content: "[deleted]", deletedAt: data.deletedAt }
-                        : m));
-                }
-            }
-        };
-        if (!trimmedRoomId || !client.isAuthenticated()) {
-            setMessages([]);
-            setConnected(false);
-            setConnectionStatus("disconnected");
-            return () => {
-                active = false;
-                stopPollingFallback();
-                stopSSEFallback();
-                connectionRef.current?.close();
-                connectionRef.current = null;
-            };
-        }
-        client.fetchMessages(trimmedRoomId).then((initial) => {
-            if (!active)
-                return;
-            setMessages(initial);
-        }).catch(() => {
-            /* history load is best-effort until member JWT + room are ready */
-        });
-        const connection = client.connectRoom(trimmedRoomId, {
-            maxReconnectAttempts: MAX_WS_RECONNECT_ATTEMPTS,
-            onStatusChange: (status) => {
-                if (!active)
-                    return;
-                if (status === "connected") {
-                    setConnected(true);
-                    setConnectionStatus("connected");
-                    setReconnectAttempt(0);
-                    setConnectionError(null);
-                    stopPollingFallback();
-                    stopSSEFallback();
-                }
-                else if (status === "connecting") {
-                    setConnectionStatus("connecting");
-                    setConnected(false);
-                }
-                else if (status === "reconnecting") {
-                    setConnectionStatus("reconnecting");
-                    setConnected(false);
-                    setReconnectAttempt(connection.reconnectAttempts);
-                }
-                else if (status === "disconnected") {
-                    setConnected(false);
-                    setConnectionStatus("disconnected");
-                }
-            },
-            onAuthError: (err) => {
-                if (!active)
-                    return;
-                setConnectionError(err);
-                setConnected(false);
-                setConnectionStatus("disconnected");
-            },
-            onConnectionError: (err) => {
-                if (!active)
-                    return;
-                if (!(err instanceof FluxyAuthError)) {
-                    setConnectionError(err);
-                }
-            },
-            onReconnectFailed: () => {
-                if (!active)
-                    return;
-                setReconnectAttempt(connection.reconnectAttempts);
-                if (client.isAuthenticated()) {
-                    startSSEFallback();
-                }
-                else {
-                    startPollingFallback();
-                }
-            },
-        });
-        connection.addEventListener("message", (data) => {
-            if (!active)
-                return;
-            handleEvent(data);
-        });
-        connectionRef.current = connection;
-        connection.connect();
-        return () => {
-            active = false;
-            stopPollingFallback();
-            stopSSEFallback();
-            connection.close();
-            connectionRef.current = null;
-            setConnected(false);
-            setConnectionStatus("disconnected");
-        };
-    }, [roomId, client]);
-    const sendMessage = (content, replyTo, attachments) => {
-        if (client.isAuthenticated()) {
-            void client
-                .createMessage(roomId, content, replyTo, attachments)
-                .catch((err) => 
-            // eslint-disable-next-line no-console
-            console.error("[fluxychat] REST sendMessage failed, falling back to WS:", err));
-            return;
-        }
-        try {
-            connectionRef.current?.sendJson({
-                type: "message",
-                userId: client.userId,
-                content,
-                parentId: replyTo ?? null,
-                attachments: attachments ?? [],
-            });
-        }
-        catch (err) {
-            if (err instanceof FluxySendError)
-                return;
-            throw err;
-        }
-    };
-    const setTyping = (isTyping) => {
-        try {
-            connectionRef.current?.sendJson({
-                type: "typing",
-                userId: client.userId,
-                isTyping,
-            });
-        }
-        catch {
-            /* socket not open */
-        }
-    };
-    const editMessage = (messageId, content) => {
-        const tryWsEdit = () => {
-            try {
-                connectionRef.current?.sendJson({
-                    type: "edit",
-                    userId: client.userId,
-                    messageId,
-                    content,
-                });
-            }
-            catch {
-                /* socket not open */
-            }
-        };
-        if (client.isAuthenticated()) {
-            void client.editMessageRest(messageId, content).catch((err) => {
-                // eslint-disable-next-line no-console
-                console.error("[fluxychat] REST editMessage failed, falling back to WS:", err);
-                tryWsEdit();
-            });
-            return;
-        }
-        tryWsEdit();
-    };
-    const sendReaction = (messageId, emoji, op = "add") => {
-        if (client.isAuthenticated()) {
-            void client
-                .sendReactionRest(messageId, emoji, op)
-                .catch((err) => 
-            // eslint-disable-next-line no-console
-            console.error("[fluxychat] REST sendReaction failed, falling back to WS:", err));
-            return;
-        }
-        try {
-            connectionRef.current?.sendJson({
-                type: "reaction",
-                userId: client.userId,
-                messageId,
-                emoji,
-                op,
-            });
-        }
-        catch {
-            /* socket not open */
-        }
-    };
-    const sendReadReceipt = (messageId) => {
-        if (client.isAuthenticated()) {
-            void client
-                .markReadRest(roomId, messageId)
-                .catch((err) => 
-            // eslint-disable-next-line no-console
-            console.error("[fluxychat] REST sendReadReceipt failed, falling back to WS:", err));
-            return;
-        }
-        try {
-            connectionRef.current?.sendJson({
-                type: "read",
-                userId: client.userId,
-                messageId,
-            });
-        }
-        catch {
-            /* socket not open */
-        }
-    };
-    const deleteMessage = (messageId) => {
-        const tryWsDelete = () => {
-            try {
-                connectionRef.current?.sendJson({ type: "delete", messageId });
-            }
-            catch {
-                /* socket not open */
-            }
-        };
-        if (client.isAuthenticated()) {
-            void client.deleteMessageRest(messageId).catch((err) => {
-                // eslint-disable-next-line no-console
-                console.error("[fluxychat] REST deleteMessage failed, falling back to WS:", err);
-                tryWsDelete();
-            });
-            return;
-        }
-        tryWsDelete();
-    };
-    const invokeAgent = async (content, options) => {
-        const targetAgentId = options?.agentId || agentId;
-        if (!targetAgentId) {
-            throw new Error("invokeAgent requires an agentId in hook options or call options");
-        }
-        setAgentTyping(true);
-        try {
-            const result = await client.invokeAgentRest(targetAgentId, roomId, content, {
-                replyTo: options?.replyTo,
-            });
-            return result;
-        }
-        finally {
-            setAgentTyping(false);
-        }
-    };
-    return {
-        messages,
-        online,
-        typingUsers,
-        seenBy,
-        onlineUsers,
-        connected,
-        connectionStatus,
-        reconnectAttempt,
-        connectionError,
-        agentTyping,
-        typingAgentId: wsTypingAgentId ?? invokeTypingAgentId,
-        reactions,
-        sendMessage,
-        setTyping,
-        editMessage,
-        sendReaction,
-        sendReadReceipt,
-        deleteMessage,
-        invokeAgent,
-    };
-}
-export function useRooms(client) {
-    const [rooms, setRooms] = useState([]);
-    const [loading, setLoading] = useState(false);
-    const [error, setError] = useState(null);
-    const load = async () => {
-        setLoading(true);
-        setError(null);
-        try {
-            const next = await client.listRooms();
-            setRooms(next);
-        }
-        catch (e) {
-            setError(e instanceof Error ? e.message : String(e));
-        }
-        finally {
-            setLoading(false);
-        }
-    };
-    useEffect(() => {
-        void load();
-    }, [client]);
-    return { rooms, loading, error, reload: load };
-}

package/dist/jwt-utils.d.ts

@@ -0,0 +1,8 @@
+export interface DecodedFluxyJwt {
+    exp?: number;
+    sub?: string;
+    tid?: string;
+}
+/** Decode payload from a JWT (no signature verification). */
+export declare function decodeFluxyJwtPayload(token: string): DecodedFluxyJwt;
+export declare function jwtRefreshDelayMs(expSeconds: number, bufferMs?: number): number;

package/dist/jwt-utils.js

@@ -0,0 +1,19 @@
+/** Decode payload from a JWT (no signature verification). */
+export function decodeFluxyJwtPayload(token) {
+    try {
+        const part = token.split(".")[1];
+        if (!part)
+            return {};
+        const normalized = part.replace(/-/g, "+").replace(/_/g, "/");
+        const json = typeof atob === "function"
+            ? atob(normalized)
+            : Buffer.from(normalized, "base64").toString("utf8");
+        return JSON.parse(json);
+    }
+    catch {
+        return {};
+    }
+}
+export function jwtRefreshDelayMs(expSeconds, bufferMs = 5 * 60 * 1000) {
+    return Math.max(expSeconds * 1000 - Date.now() - bufferMs, 0);
+}

package/dist/message-history.d.ts

@@ -0,0 +1,23 @@
+/** Minimal fields required for history merge/sort. */
+export interface HistoryMessage {
+    id: number;
+    createdAt: string;
+    roomId?: string;
+    userId?: string;
+    content?: string;
+    senderId?: string;
+    parentId?: number | null;
+    editedAt?: string | null;
+    deletedAt?: string | null;
+    mentions?: string[];
+    streaming?: boolean;
+    attachments?: {
+        kind: string;
+        url: string;
+        name: string;
+    }[];
+}
+export declare const MAX_HISTORY_LIMIT = 500;
+export declare function sortMessagesChronological<T extends HistoryMessage>(messages: T[]): T[];
+export declare function mergeMessagesChronological<T extends HistoryMessage>(existing: T[], incoming: T[]): T[];
+export declare function clampHistoryLimit(limit?: number): number;

package/dist/message-history.js

@@ -0,0 +1,21 @@
+const DEFAULT_HISTORY_LIMIT = 50;
+export const MAX_HISTORY_LIMIT = 500;
+export function sortMessagesChronological(messages) {
+    return [...messages].sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
+}
+export function mergeMessagesChronological(existing, incoming) {
+    const byId = new Map();
+    for (const msg of [...incoming, ...existing]) {
+        if (!Number.isFinite(msg.id))
+            continue;
+        const prev = byId.get(msg.id);
+        byId.set(msg.id, prev ? { ...prev, ...msg } : msg);
+    }
+    return sortMessagesChronological([...byId.values()]);
+}
+export function clampHistoryLimit(limit) {
+    const n = limit ?? DEFAULT_HISTORY_LIMIT;
+    if (!Number.isFinite(n) || n < 1)
+        return DEFAULT_HISTORY_LIMIT;
+    return Math.min(Math.floor(n), MAX_HISTORY_LIMIT);
+}

package/dist/realtime-provider.d.ts

@@ -0,0 +1,27 @@
+import React from "react";
+export interface FluxyAuthTokenResult {
+    token: string;
+    userId?: string;
+}
+export interface FluxyRealtimeProviderProps {
+    children: React.ReactNode;
+    /** Worker HTTP base URL (e.g. https://api.example.com). */
+    workerUrl: string;
+    /**
+     * Pre-minted member JWT, or a callback that returns one.
+     * Use with your backend `POST /auth/token` flow.
+     */
+    authTokenProvider?: string | (() => Promise<string | FluxyAuthTokenResult>);
+    /**
+     * Hosted dashboard style: POST to obtain `memberJwt` (default body `{}`).
+     * Example: `/api/fluxy/connect` on the Next.js app.
+     */
+    connectUrl?: string;
+    connectRequestInit?: Omit<RequestInit, "method" | "body">;
+    /** Fallback user id when the JWT has no `sub` claim. */
+    userId?: string;
+    /** Refresh this many ms before JWT expiry (default 5 minutes). */
+    refreshBufferMs?: number;
+    onSessionError?: (error: Error) => void;
+}
+export declare function FluxyRealtimeProvider({ children, workerUrl, authTokenProvider, connectUrl, connectRequestInit, userId: userIdProp, refreshBufferMs, onSessionError, }: FluxyRealtimeProviderProps): import("react/jsx-runtime").JSX.Element;