@fluxy-chat/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fluxychat contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @fluxy-chat/sdk
+
+Client for a **Fluxychat Worker** (self-hosted or [Fluxychat Cloud](https://github.com/AlessandroFare/fluxychat)): rooms, messages, WebSockets, agents, and optional React `useChat`.
+
+The SDK talks to **your** Worker URL. It does **not** include LLM API keys — only your Fluxy **project API key** or **member JWT**.
+
+## Install
+
+```bash
+npm install @fluxy-chat/sdk
+# or
+pnpm add @fluxy-chat/sdk
+```
+
+Requires **React 18+** if you use `useChat` (peer dependency).
+
+## What you must configure
+
+| Piece | Who sets it | Notes |
+|--------|-------------|--------|
+| **Worker `baseUrl`** | You | e.g. `https://fluxychat-worker.<account>.workers.dev` or your custom domain |
+| **Project API key** (`fc_…`) | Worker / console | Mint JWTs via `POST /auth/token` with header `X-Fluxy-Api-Key` — **server-side only** |
+| **Member JWT** | Your backend or Fluxychat console | Passed to `FluxyChatClient` / `useChat` as `token` |
+| **LLM provider keys** | Worker secrets or console | For agents; never embed in the npm package |
+
+### Minimal backend (mint JWT)
+
+```bash
+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}'
+```
+
+Use the returned `token` in the browser.
+
+## Quick start (React)
+
+```tsx
+import { FluxyChatClient, useChat } from "@fluxy-chat/sdk";
+
+const client = new FluxyChatClient({
+  baseUrl: process.env.NEXT_PUBLIC_FLUXYCHAT_WORKER_URL!,
+  userId: "alice",
+  token: memberJwtFromYourBackend,
+});
+
+function Room({ roomId }: { roomId: string }) {
+  const { messages, sendMessage, connectionStatus } = useChat({ roomId, client });
+  // render 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`.
+- **Hosted cloud:** use the Fluxychat dashboard on Vercel; sign in with Clerk; project + API keys are provisioned for you.
+
+Full operator docs: [docs/dashboard-integration.md](https://github.com/AlessandroFare/fluxychat/blob/main/docs/dashboard-integration.md).
+
+## Agents
+
+Agent invokes run on the Worker (`POST /agents/:id/invoke`). Configure provider keys on the Worker or per-project in the console. The SDK exposes REST helpers only.
+
+## Support
+
+Questions: [fluxychat@outlook.com](mailto:fluxychat@outlook.com) · Issues: [github.com/AlessandroFare/fluxychat/issues](https://github.com/AlessandroFare/fluxychat/issues)
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+/** Worker closes unauthorized / forbidden WebSocket joins with 1008. */
+export declare const FLUXY_WS_CLOSE_POLICY = 1008;
+/** Normal client-initiated close. */
+export declare const FLUXY_WS_CLOSE_NORMAL = 1000;
+export declare class FluxyAuthError extends Error {
+    readonly code = 1008;
+    constructor(message?: string);
+}
+export declare class FluxyConnectionError extends Error {
+    readonly code: number;
+    readonly reason: string;
+    constructor(code: number, reason?: string, message?: string);
+}
+export declare class FluxySendError extends Error {
+    constructor(message?: string);
+}
+export declare class FluxyTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+export declare function mapWebSocketCloseToError(code: number, reason?: string): Error | null;
+export declare function computeReconnectBackoffMs(attempt: number, baseMs?: number, maxMs?: number): number;

package/dist/errors.js

@@ -0,0 +1,48 @@
+/** Worker closes unauthorized / forbidden WebSocket joins with 1008. */
+export const FLUXY_WS_CLOSE_POLICY = 1008;
+/** Normal client-initiated close. */
+export const FLUXY_WS_CLOSE_NORMAL = 1000;
+export class FluxyAuthError extends Error {
+    constructor(message = "Authentication or room access failed (WebSocket close 1008). Check your JWT, API key, and room membership.") {
+        super(message);
+        this.code = FLUXY_WS_CLOSE_POLICY;
+        this.name = "FluxyAuthError";
+    }
+}
+export class FluxyConnectionError extends Error {
+    constructor(code, reason = "", message) {
+        super(message ?? `WebSocket closed unexpectedly (code ${code}${reason ? `: ${reason}` : ""}).`);
+        this.name = "FluxyConnectionError";
+        this.code = code;
+        this.reason = reason;
+    }
+}
+export class FluxySendError extends Error {
+    constructor(message = "Cannot send: WebSocket is not open.") {
+        super(message);
+        this.name = "FluxySendError";
+    }
+}
+export class FluxyTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`Operation timed out after ${timeoutMs}ms`);
+        this.name = "FluxyTimeoutError";
+        this.timeoutMs = timeoutMs;
+    }
+}
+export function mapWebSocketCloseToError(code, reason = "") {
+    if (code === FLUXY_WS_CLOSE_NORMAL)
+        return null;
+    if (code === FLUXY_WS_CLOSE_POLICY) {
+        const text = reason.trim();
+        if (text.toLowerCase().includes("forbidden")) {
+            return new FluxyAuthError("You are not a member of this room (WebSocket close 1008 Forbidden). Join the room or use an admin JWT.");
+        }
+        return new FluxyAuthError();
+    }
+    return new FluxyConnectionError(code, reason);
+}
+export function computeReconnectBackoffMs(attempt, baseMs = 500, maxMs = 20000) {
+    const capped = Math.min(Math.max(attempt, 0), 6);
+    return Math.min(maxMs, baseMs * 2 ** capped);
+}

package/dist/index.d.ts

@@ -0,0 +1,293 @@
+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";
+import { FluxyChatRoomConnection, type FluxyRoomConnectionOptions } from "./room-connection";
+export interface FluxyChatMessage {
+    id: number;
+    roomId: string;
+    userId: string;
+    senderId?: string;
+    content: string;
+    createdAt: string;
+    parentId?: number | null;
+    editedAt?: string | null;
+    deletedAt?: string | null;
+    mentions?: string[];
+    preview?: {
+        url: string;
+        title?: string | null;
+        description?: string | null;
+        imageUrl?: string | null;
+    };
+    attachments?: FluxyChatAttachment[];
+    /** True while an agent (or user) is still streaming tokens into this message. */
+    streaming?: boolean;
+}
+export interface FluxyChatAttachment {
+    id?: number;
+    kind: string;
+    url: string;
+    name: string;
+    sizeBytes?: number;
+    contentType?: string;
+}
+export interface FluxyChatRoom {
+    id: string;
+    type: "dm" | "group" | "public";
+    name: string;
+    created_at: string;
+}
+export interface FluxyChatToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+export interface FluxyChatAgent {
+    id: string;
+    projectId: string;
+    name: string;
+    handle?: string | null;
+    provider?: string | null;
+    model?: string | null;
+    capabilities?: string[];
+    config?: Record<string, unknown> | null;
+    systemPrompt?: string | null;
+    contextFetchUrl?: string | null;
+    toolExecuteUrl?: string | null;
+    toolsSchema?: FluxyChatToolDefinition[] | null;
+    rateLimitRpm?: number | null;
+    createdAt?: string;
+}
+export interface FluxyChatToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+}
+export interface FluxyChatAgentRun {
+    id: string;
+    status: "queued" | "completed" | "failed";
+    latency_ms?: number;
+    input_tokens?: number;
+    output_tokens?: number;
+    estimated_cost?: number;
+    error?: string | null;
+    room_id?: string | null;
+    tool_calls?: FluxyChatToolCall[];
+    context_fetched?: boolean;
+    iterations?: number;
+    created_at: string;
+}
+export type FluxyChatEvent = {
+    type: "history";
+    messages: FluxyChatMessage[];
+} | ({
+    type: "message";
+} & FluxyChatMessage) | {
+    type: "edit";
+    id: number;
+    roomId: string;
+    userId: string;
+    content: string;
+    editedAt: string;
+    streaming?: boolean;
+} | {
+    type: "stream";
+    op: "started";
+    id: number;
+    roomId: string;
+} | {
+    type: "reaction";
+    roomId: string;
+    userId: string;
+    messageId: number;
+    emoji: string;
+    op: "add" | "remove";
+} | {
+    type: "read";
+    roomId: string;
+    userId: string;
+    messageId: number;
+    createdAt: string;
+} | {
+    type: "delete";
+    id: number;
+    roomId: string;
+    userId: string;
+    deletedAt: string;
+    hard?: boolean;
+} | {
+    type: "typing";
+    userId: string;
+    isTyping: boolean;
+} | {
+    type: "agentTyping";
+    agentId: string;
+    isTyping: boolean;
+} | {
+    type: "presence";
+    online: number;
+    users?: string[];
+} | {
+    type: "error";
+    message: string;
+};
+export interface FluxyChatClientOptions {
+    baseUrl: string;
+    userId: string;
+    apiKey?: string;
+    /**
+     * Optional JWT for authenticated REST calls (POST /messages, reactions, read, reports, etc).
+     * When provided, the SDK will prefer REST for writes and use WebSocket mainly for realtime updates.
+     */
+    token?: string;
+}
+export declare class FluxyChatClient {
+    private baseUrl;
+    readonly userId: string;
+    readonly apiKey?: string;
+    readonly token?: string;
+    constructor(options: FluxyChatClientOptions);
+    isAuthenticated(): boolean;
+    private authHeaders;
+    connect(roomId: string): WebSocket;
+    /**
+     * Resilient room WebSocket with typed errors, exponential backoff reconnect,
+     * and optional REST history replay after reconnect.
+     */
+    connectRoom(roomId: string, options?: FluxyRoomConnectionOptions): FluxyChatRoomConnection;
+    connectSSE(roomId: string): EventSource | null;
+    fetchMessages(roomId: string, limit?: number): Promise<FluxyChatMessage[]>;
+    listRooms(type?: string): Promise<FluxyChatRoom[]>;
+    createMessage(roomId: string, content: string, replyTo?: number | null, attachments?: FluxyChatAttachment[]): Promise<FluxyChatMessage | null>;
+    /**
+     * Upload to Worker `POST /upload` (requires JWT). Returns attachment fields for composing a message.
+     */
+    uploadFile(roomId: string, file: File): Promise<FluxyChatAttachment>;
+    editMessageRest(messageId: number, content: string): Promise<void>;
+    deleteMessageRest(messageId: number): Promise<void>;
+    sendReactionRest(messageId: number, emoji: string, op?: "add" | "remove"): Promise<void>;
+    markReadRest(roomId: string, messageId: number): Promise<void>;
+    listAgents(): Promise<FluxyChatAgent[]>;
+    invokeAgentRest(agentId: string, roomId: string, content: string, options?: {
+        replyTo?: number | null;
+        stream?: boolean;
+    }): Promise<{
+        run: {
+            id: string;
+            status: string;
+            latencyMs?: number;
+            inputTokens?: number;
+            outputTokens?: number;
+            estimatedCost?: number;
+            iterations?: number;
+            toolCalls?: FluxyChatToolCall[];
+            createdAt: string;
+        };
+        message: FluxyChatMessage;
+    }>;
+    getAgentRuns(agentId: string, limit?: number): Promise<FluxyChatAgentRun[]>;
+    getAgent(agentId: string): Promise<FluxyChatAgent | null>;
+    createAgent(body: {
+        name: string;
+        handle?: string;
+        provider?: string;
+        model?: string;
+        systemPrompt?: string;
+        contextFetchUrl?: string;
+        toolExecuteUrl?: string;
+        toolsSchema?: unknown[];
+        rateLimitRpm?: number;
+    }): Promise<FluxyChatAgent>;
+    updateAgent(agentId: string, body: Record<string, unknown>): Promise<FluxyChatAgent>;
+    deleteAgent(agentId: string): Promise<void>;
+    createRoom(body: {
+        name: string;
+        type: string;
+        id?: string;
+        members?: {
+            userId: string;
+            role: string;
+        }[];
+    }): Promise<{
+        id: string;
+        type: string;
+        name: string;
+        created_at: string;
+    }>;
+    updateRoom(roomId: string, body: {
+        name?: string;
+        type?: string;
+    }): Promise<void>;
+    deleteRoom(roomId: string): Promise<void>;
+    addRoomMember(roomId: string, userId: string, role?: string): Promise<void>;
+    removeRoomMember(roomId: string, userId: string): Promise<void>;
+    registerWebhook(body: {
+        url: string;
+        eventTypes: string[];
+        secret?: string;
+    }): Promise<{
+        id: string;
+        projectId: string;
+        url: string;
+        secret?: string;
+    }>;
+    updateWebhook(webhookId: string, body: {
+        url?: string;
+        eventTypes?: string[];
+        secret?: string;
+    }): 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>;
+};