@fluxy-chat/sdk

npm install @fluxy-chat/sdk zustand
# React apps also need:
npm install @fluxy-chat/react react
# or
pnpm add @fluxy-chat/sdk @fluxy-chat/react zustand

pnpm run first-message

import { getConnectionStatusLabel } from "@fluxy-chat/sdk";

const label = getConnectionStatusLabel(connectionState.status, {
  includeTransport: true,
  nextRetryAt: connectionState.nextRetryAt,
});

import { createFluxyRoomSession } from "@fluxy-chat/sdk";

const { store, stop } = createFluxyRoomSession({
  roomId: "my-room",
  client,
});

const unsub = store.subscribe((state) => {
  console.log(state.messages, state.connectionState);
});

store.getState().sendMessage("hello");
store.getState().sendMessage("", null, undefined, {
  templateId: "tpl_…",
  templateVars: { name: "Ada" },
});

// cleanup: unsub(); stop();

curl -X POST "$WORKER_URL/auth/token" \
  -H "Content-Type: application/json" \
  -H "X-Fluxy-Api-Key: fc_your_project_key" \
  -d '{"userId":"alice","roles":["member"],"ttlSeconds":3600}'

# Set these in your shell or .env.local first.
export WORKER_URL=https://your-worker.example.workers.dev
export JWT=eyJ...                              # member JWT from /auth/token
export ROOM_ID=general

# 1. Send a message
curl -sS -X POST "$WORKER_URL/messages" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d "{\"roomId\":\"$ROOM_ID\",\"content\":\"hello from the smoke test\"}"

# 2. Read it back
curl -sS "$WORKER_URL/api/messages?roomId=$ROOM_ID&limit=1" \
  -H "Authorization: Bearer $JWT"
# Verified against @fluxy-chat/sdk@0.5.0

import { FluxyChatClient } from "@fluxy-chat/sdk";
import { useChat } from "@fluxy-chat/react";

const client = new FluxyChatClient({
  baseUrl: process.env.NEXT_PUBLIC_FLUXYCHAT_WORKER_URL!,
  userId: "alice",
  token: memberJwtFromYourBackend,
});

function Room({ roomId }: { roomId: string }) {
  const {
    messages,
    sendMessage,
    connectionState,
    retryMessage,
    loadMore,
    hasMore,
    isLoadingMore,
  } = useChat({ roomId, client, markReadLatest: true });
  // connectionState.nextRetryAt → "Reconnecting in 3s…"
  // messages[].deliveryStatus → pending | sent | failed
  // render messages; call loadMore() when the user scrolls to the top
}
// Verified against @fluxy-chat/sdk@0.4.2  2026-06-26

const catchUp = await client.getRoomCatchUp(roomId);
// { unreadCount, lastReadMessageId, firstUnreadMessageId }

await client.putRoomDraft(roomId, { content: "…", replyToId: null });
const draft = await client.getRoomDraft(roomId);

// Ephemeral message (1 hour TTL)
await client.createMessage(roomId, "self-destructs", null, undefined, undefined, {
  expiresInSeconds: 3600,
});

const rooms = await client.listRooms(); // may include unreadCount per room
const notes = await client.listNotifications({ unreadOnly: true });
await client.markNotificationRead(notes[0].id);
// useNotifications(client) — React hook for in-app notification inbox

import { FluxyRealtimeProvider, useChat } from "@fluxy-chat/react";

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 });
  // …
}

const live = await client.getRoomLive("lobby");
// { occupied, online, subscriptionCount, userCount, users[], members: [{ userId, userInfo }], socketIds[] }

// Just the participants slice
const participants = await client.getRoomParticipants("lobby");

// React hook exposes a live snapshot in the store
const { live, loadLive } = useChat({ roomId: "lobby" });
await loadLive(); // refresh on demand

const conn = client.connectRoom(roomId, {
  heartbeatIntervalMs: 25_000,
  onOutboundQueueDrop: (n) => console.warn("dropped", n),
});

// Match the Fluxy-style curve (1s base, 8s cap)
const conn = client.connectRoom(roomId, {
  baseBackoffMs: 1_000,
  maxBackoffMs: 8_000,
});

const { messages, loadHistory, historyLoaded } = useChat({
  roomId,
  replay: "request", // skip REST + WS history on connect
});
// later: await loadHistory();

import { FluxyChatClient, FluxyMessageStream } from "@fluxy-chat/sdk";

const connection = client.connectRoom(roomId);
// connectRoom() auto-connects  no .connect() needed
const stream = new FluxyMessageStream(connection, agentUserId, { parentId: null });
stream.push("Hello ");
stream.end();
// Verified against @fluxy-chat/sdk@0.4.2  2026-06-26

// signIn() mints a member JWT using the apiKey configured on the client
const signed = await client.signIn({ userId: "alice", roles: ["member"], ttlSeconds: 3600 });
// For React: prefer the `useUserChannel` hook  it wraps the WS lifecycle.
// For non-React: use `client.connectUser()` directly (returns a raw WebSocket).
const userWs = client.connectUser(signed.userId);
userWs.onmessage = (event) => console.log("user-channel:", event.data);

await client.triggerEvents({
  roomIds: ["lobby", "scores"],
  name: "leaderboard",
  data: { top: 3 },
});

// onAnyEvent lives on the room connection, not the client
const conn = client.connectRoom("lobby");
conn.onAnyEvent((type, payload) => {
  if (type.startsWith("client-")) return;
});
// Verified against @fluxy-chat/sdk@0.4.2  2026-06-26

import { useUserChannel } from "@fluxy-chat/sdk";

function Inbox({ userId }: { userId: string }) {
  const { events, connectionState } = useUserChannel({ userId });
  // …
}

const guest = await FluxyChatClient.joinPublicRoomAsGuest(workerUrl, "lobby");
const guestClient = new FluxyChatClient({
  baseUrl: workerUrl,
  userId: guest.userId,
  token: guest.token,
});
const channelAuth = await client.authorizeChannel(socketId, "private-room-lobby");
await client.translateMessage(messageId, "it");
await client.markMessageDelivered(messageId);
await client.registerPushDevice("fcm", fcmToken);

// Multi-platform adapter example
import { getAdapter, dispatchThreadEvent, dispatchMessageEvent } from "@fluxy-chat/sdk";

const adapter = getAdapter("web");
const threadId = adapter.encodeThreadId({ userId, roomId }); // "web:{userId}:{roomId}"

// Streaming markdown
import { StreamingMarkdownRenderer } from "@fluxy-chat/sdk";
const renderer = new StreamingMarkdownRenderer();
renderer.push("**bold** and `code`");
const html = renderer.getHtml(); // renders incrementally

// Card builder
import { Card, Text, Button, cardToMarkdown } from "@fluxy-chat/sdk";
const card = Card(Text("Hello"), Button("Click me", "https://example.com"));
const markdown = cardToMarkdown(card);