@fluxy-chat/sdk 0.1.0 → 0.2.1

package/README.md

@@ -36,6 +36,8 @@ Use the returned `token` in the browser.
 
 ## Quick start (React)
 
+### Option A — explicit client
+
 ```tsx
 import { FluxyChatClient, useChat } from "@fluxy-chat/sdk";
 
@@ -46,11 +48,46 @@ const client = new FluxyChatClient({
 });
 
 function Room({ roomId }: { roomId: string }) {
-  const { messages, sendMessage, connectionStatus } = useChat({ roomId, client });
-  // render messages…
+  const { messages, sendMessage, connectionStatus, loadMore, hasMore, isLoadingMore } =
+    useChat({ roomId, client });
+  // render messages; call loadMore() when the user scrolls to the top
+}
+```
+
+### Option B — `FluxyRealtimeProvider` (hosted Next.js or custom mint)
+
+Wrap your app (or chat layout) once. The provider refreshes the member JWT before expiry and on auth errors.
+
+```tsx
+import { FluxyRealtimeProvider, useChat } from "@fluxy-chat/sdk";
+
+export function ChatLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <FluxyRealtimeProvider
+      workerUrl={process.env.NEXT_PUBLIC_FLUXYCHAT_WORKER_URL!}
+      connectUrl="/api/fluxy/connect"
+    >
+      {children}
+    </FluxyRealtimeProvider>
+  );
+}
+
+function Room({ roomId }: { roomId: string }) {
+  const { messages, sendMessage, loadMore, hasMore } = useChat({ roomId });
+  // …
 }
 ```
 
+For your own backend mint flow, pass `authTokenProvider={() => fetch("/api/chat-token").then(r => r.json())}` instead of `connectUrl`.
+
+### Pagination
+
+`GET /api/messages` supports a `before` cursor (`createdAt` of the oldest visible message). The SDK sorts history chronologically and exposes:
+
+- `hasMore` — another page may exist
+- `isLoadingMore` — `loadMore()` in flight
+- `loadMore()` — prepends older messages
+
 ## Self-host vs hosted cloud
 
 - **Self-host:** deploy `apps/worker` from the [monorepo](https://github.com/AlessandroFare/fluxychat), run D1 migrations, set secrets. See `apps/worker/.dev.vars.example`.

package/dist/agent-outbound.d.ts

@@ -0,0 +1,14 @@
+export interface AgentOutboundMessageInput {
+    userId: string;
+    content: string;
+    parentId?: number | null;
+    attachments?: unknown[];
+}
+export interface AgentOutboundValidationResult {
+    valid: boolean;
+    error?: string;
+    content?: string;
+    parentId?: number | null;
+}
+export declare function validateAgentOutboundMessage(input: AgentOutboundMessageInput): AgentOutboundValidationResult;
+export declare function buildAgentOutboundWsPayload(input: AgentOutboundMessageInput): Record<string, unknown>;

package/dist/agent-outbound.js

@@ -0,0 +1,53 @@
+import { FLUXY_MAX_MESSAGE_LENGTH } from "./room-rest";
+export function validateAgentOutboundMessage(input) {
+    const userId = input.userId?.trim();
+    if (!userId) {
+        return { valid: false, error: "userId is required" };
+    }
+    if (userId.length > 128) {
+        return { valid: false, error: "userId exceeds maximum length" };
+    }
+    if (typeof input.content !== "string") {
+        return { valid: false, error: "content must be a string" };
+    }
+    const trimmed = input.content.trim();
+    if (!trimmed) {
+        return { valid: false, error: "content cannot be empty" };
+    }
+    if (trimmed.length > FLUXY_MAX_MESSAGE_LENGTH) {
+        return {
+            valid: false,
+            error: `content exceeds maximum length of ${FLUXY_MAX_MESSAGE_LENGTH} characters`,
+        };
+    }
+    let parentId = null;
+    if (input.parentId != null) {
+        if (!Number.isFinite(input.parentId) || input.parentId < 1) {
+            return { valid: false, error: "parentId must be a positive message id" };
+        }
+        parentId = Math.floor(input.parentId);
+    }
+    const attachments = input.attachments;
+    if (attachments != null) {
+        if (!Array.isArray(attachments)) {
+            return { valid: false, error: "attachments must be an array" };
+        }
+        if (attachments.length > 20) {
+            return { valid: false, error: "attachments cannot exceed 20 items" };
+        }
+    }
+    return { valid: true, content: trimmed, parentId };
+}
+export function buildAgentOutboundWsPayload(input) {
+    const validated = validateAgentOutboundMessage(input);
+    if (!validated.valid) {
+        throw new Error(validated.error ?? "Invalid agent outbound message");
+    }
+    return {
+        type: "message",
+        userId: input.userId.trim(),
+        content: validated.content,
+        parentId: validated.parentId ?? null,
+        attachments: Array.isArray(input.attachments) ? input.attachments : [],
+    };
+}

package/dist/index.d.ts

@@ -1,6 +1,14 @@
 export { FluxyAuthError, FluxyConnectionError, FluxySendError, FluxyTimeoutError, FLUXY_WS_CLOSE_NORMAL, FLUXY_WS_CLOSE_POLICY, computeReconnectBackoffMs, mapWebSocketCloseToError, } from "./errors";
 export { FluxyChatRoomConnection, type FluxyRoomConnectionOptions, type FluxyRoomConnectionStatus, type FluxyWaitForOptions, } from "./room-connection";
 export { FluxyMessageStream, type FluxyMessageStreamOptions } from "./message-stream";
+export { clampHistoryLimit, mergeMessagesChronological, sortMessagesChronological, MAX_HISTORY_LIMIT, type HistoryMessage, } from "./message-history";
+export { decodeFluxyJwtPayload, jwtRefreshDelayMs, type DecodedFluxyJwt } from "./jwt-utils";
+export { FLUXY_MAX_MESSAGE_LENGTH, normalizeRoomMember, normalizeRoomMembers, } from "./room-rest";
+export { validateAgentOutboundMessage, buildAgentOutboundWsPayload, type AgentOutboundMessageInput, type AgentOutboundValidationResult, } from "./agent-outbound";
+export { FluxyRealtimeProvider, type FluxyRealtimeProviderProps, type FluxyAuthTokenResult, } from "./realtime-provider";
+export { useFluxyChat, useFluxyChatOptional, type FluxyRealtimeContextValue } from "./use-fluxy-chat";
+export { useChat, type UseChatOptions } from "./use-chat";
+export { useRooms } from "./use-rooms";
 import { FluxyChatRoomConnection, type FluxyRoomConnectionOptions } from "./room-connection";
 export interface FluxyChatMessage {
     id: number;
@@ -37,6 +45,16 @@ export interface FluxyChatRoom {
     name: string;
     created_at: string;
 }
+export interface FluxyRoomMember {
+    userId: string;
+    role: string;
+    joined_at?: string;
+}
+export interface FetchMessagesOptions {
+    limit?: number;
+    /** ISO `createdAt` cursor — returns messages older than this timestamp. */
+    before?: string;
+}
 export interface FluxyChatToolDefinition {
     type: "function";
     function: {
@@ -159,7 +177,10 @@ export declare class FluxyChatClient {
      */
     connectRoom(roomId: string, options?: FluxyRoomConnectionOptions): FluxyChatRoomConnection;
     connectSSE(roomId: string): EventSource | null;
-    fetchMessages(roomId: string, limit?: number): Promise<FluxyChatMessage[]>;
+    fetchMessages(roomId: string, limitOrOptions?: number | FetchMessagesOptions): Promise<FluxyChatMessage[]>;
+    fetchRoomMembers(roomId: string): Promise<FluxyRoomMember[]>;
+    /** Alias for {@link fetchMessages} — chronological room history via REST. */
+    fetchRoomHistory(roomId: string, options?: FetchMessagesOptions): Promise<FluxyChatMessage[]>;
     listRooms(type?: string): Promise<FluxyChatRoom[]>;
     createMessage(roomId: string, content: string, replyTo?: number | null, attachments?: FluxyChatAttachment[]): Promise<FluxyChatMessage | null>;
     /**
@@ -241,53 +262,3 @@ export declare class FluxyChatClient {
     }): Promise<void>;
     deleteWebhook(webhookId: string): Promise<void>;
 }
-export interface UseChatOptions {
-    roomId: string;
-    client: FluxyChatClient;
-    agentId?: string;
-}
-export declare function useChat({ roomId, client, agentId }: UseChatOptions): {
-    messages: FluxyChatMessage[];
-    online: number;
-    typingUsers: Record<string, boolean>;
-    seenBy: Record<number, string[]>;
-    onlineUsers: string[];
-    connected: boolean;
-    connectionStatus: "connecting" | "connected" | "reconnecting" | "disconnected" | "polling" | "sse";
-    reconnectAttempt: number;
-    connectionError: Error | null;
-    agentTyping: boolean;
-    typingAgentId: string | null;
-    reactions: Record<number, Record<string, number>>;
-    sendMessage: (content: string, replyTo?: number | null, attachments?: FluxyChatAttachment[]) => void;
-    setTyping: (isTyping: boolean) => void;
-    editMessage: (messageId: number, content: string) => void;
-    sendReaction: (messageId: number, emoji: string, op?: "add" | "remove") => void;
-    sendReadReceipt: (messageId: number) => void;
-    deleteMessage: (messageId: number) => void;
-    invokeAgent: (content: string, options?: {
-        agentId?: string;
-        replyTo?: number | null;
-    }) => Promise<{
-        run: {
-            id: string;
-            status: string;
-            latencyMs?: number;
-            inputTokens?: number;
-            outputTokens?: number;
-            estimatedCost?: number;
-            iterations?: number;
-            toolCalls?: FluxyChatToolCall[];
-            createdAt: string;
-        };
-        message: FluxyChatMessage;
-    }>;
-};
-export declare function useRooms(client: FluxyChatClient): {
-    rooms: (FluxyChatRoom & {
-        unreadCount?: number;
-    })[];
-    loading: boolean;
-    error: string | null;
-    reload: () => Promise<void>;
-};