@fluxy-chat/agent 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+import { FluxyChatClient, FluxyMessageStream, type FluxyChatMessage, type FluxyRoomConnectionOptions, type FluxyWaitForOptions } from "@fluxy-chat/sdk";
+export { FluxyAuthError, FluxyConnectionError, FluxySendError, FluxyTimeoutError, } from "@fluxy-chat/sdk";
+export { mintWorkerToken, type MintTokenInput, type MintTokenResult } from "./mint";
+export interface FluxyAgentConfig {
+    /** Agent id — used as JWT `sub` / message `userId` (must match a row in `agents` for invoke). */
+    id: string;
+    name: string;
+    /** Project API key (`fc_…`) from the Worker / console. */
+    apiKey: string;
+    baseUrl?: string;
+    /** JWT roles (default `["member"]`). Use `["admin"]` only for bootstrap helpers. */
+    roles?: string[];
+    tokenTtlSeconds?: number;
+}
+export interface FluxyAgentJoinOptions {
+    /** POST /rooms/:id/members with a short-lived admin token if the agent is not in the room yet. */
+    ensureMembership?: boolean;
+    connection?: FluxyRoomConnectionOptions;
+}
+export declare class FluxyRoom {
+    readonly id: string;
+    constructor(roomId: string);
+}
+type RoomListener = (message: FluxyChatMessage) => void;
+export declare class FluxyAgent {
+    readonly id: string;
+    readonly name: string;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly roles;
+    private readonly tokenTtlSeconds;
+    private token;
+    private client;
+    private readonly connections;
+    private readonly roomListeners;
+    constructor(config: FluxyAgentConfig);
+    /** Mint JWT via Worker `POST /auth/token` and prepare REST/WS client. */
+    init(): Promise<this>;
+    getClient(): FluxyChatClient;
+    room(roomId: string): FluxyRoom;
+    join(room: FluxyRoom | string, options?: FluxyAgentJoinOptions): Promise<void>;
+    leave(room: FluxyRoom | string): void;
+    disconnect(): void;
+    on(room: FluxyRoom | string, callback: RoomListener): void;
+    off(room: FluxyRoom | string, callback: RoomListener): void;
+    send(room: FluxyRoom | string, content: string, replyTo?: number | null): void;
+    createStream(room: FluxyRoom | string, options?: {
+        parentId?: number | null;
+        flushIntervalMs?: number;
+    }): FluxyMessageStream;
+    waitFor(room: FluxyRoom | string, predicate: (message: FluxyChatMessage) => boolean, options?: FluxyWaitForOptions): Promise<FluxyChatMessage>;
+    invoke(room: FluxyRoom | string, content: string, options?: {
+        replyTo?: number | null;
+    }): Promise<Awaited<ReturnType<FluxyChatClient["invokeAgentRest"]>>>;
+    private getConnection;
+    private ensureRoomMembership;
+}
+export declare function createFluxyAgent(config: FluxyAgentConfig): Promise<FluxyAgent>;
+export type { FluxyChatMessage, FluxyMessageStream, FluxyWaitForOptions };

package/dist/index.js

@@ -0,0 +1,183 @@
+import { FluxyChatClient, FluxyMessageStream, buildAgentOutboundWsPayload, } from "@fluxy-chat/sdk";
+import { mintWorkerToken } from "./mint";
+export { FluxyAuthError, FluxyConnectionError, FluxySendError, FluxyTimeoutError, } from "@fluxy-chat/sdk";
+export { mintWorkerToken } from "./mint";
+const DEFAULT_BASE_URL = "http://127.0.0.1:8787";
+function trimTrailingSlashes(url) {
+    let out = url;
+    while (out.endsWith("/"))
+        out = out.slice(0, -1);
+    return out;
+}
+export class FluxyRoom {
+    constructor(roomId) {
+        this.id = roomId;
+    }
+}
+export class FluxyAgent {
+    constructor(config) {
+        this.token = null;
+        this.client = null;
+        this.connections = new Map();
+        this.roomListeners = new Map();
+        if (!config.id?.trim())
+            throw new Error("FluxyAgent requires id");
+        if (!config.apiKey?.trim())
+            throw new Error("FluxyAgent requires apiKey");
+        this.id = config.id.trim();
+        this.name = config.name?.trim() || this.id;
+        this.apiKey = config.apiKey.trim();
+        this.baseUrl = trimTrailingSlashes(config.baseUrl ?? DEFAULT_BASE_URL);
+        this.roles = config.roles?.length ? config.roles : ["member"];
+        this.tokenTtlSeconds = config.tokenTtlSeconds ?? 3600;
+    }
+    /** Mint JWT via Worker `POST /auth/token` and prepare REST/WS client. */
+    async init() {
+        const minted = await mintWorkerToken({
+            baseUrl: this.baseUrl,
+            apiKey: this.apiKey,
+            userId: this.id,
+            roles: this.roles,
+            ttlSeconds: this.tokenTtlSeconds,
+        });
+        this.token = minted.token;
+        this.client = new FluxyChatClient({
+            baseUrl: this.baseUrl,
+            userId: this.id,
+            token: this.token,
+            apiKey: this.apiKey,
+        });
+        return this;
+    }
+    getClient() {
+        if (!this.client || !this.token) {
+            throw new Error("Call init() before using the agent client.");
+        }
+        return this.client;
+    }
+    room(roomId) {
+        return new FluxyRoom(roomId);
+    }
+    async join(room, options = {}) {
+        const roomId = typeof room === "string" ? room : room.id;
+        if (this.connections.has(roomId))
+            return;
+        if (options.ensureMembership) {
+            await this.ensureRoomMembership(roomId);
+        }
+        const client = this.getClient();
+        const connection = client.connectRoom(roomId, options.connection);
+        connection.addEventListener("message", (event) => {
+            if (event.type !== "message")
+                return;
+            const listeners = this.roomListeners.get(roomId);
+            if (!listeners)
+                return;
+            for (const cb of listeners) {
+                try {
+                    cb(event);
+                }
+                catch {
+                    /* ignore listener errors */
+                }
+            }
+        });
+        this.connections.set(roomId, connection);
+        connection.connect();
+    }
+    leave(room) {
+        const roomId = typeof room === "string" ? room : room.id;
+        const connection = this.connections.get(roomId);
+        if (!connection)
+            return;
+        connection.close();
+        this.connections.delete(roomId);
+        this.roomListeners.delete(roomId);
+    }
+    disconnect() {
+        for (const connection of this.connections.values()) {
+            connection.close();
+        }
+        this.connections.clear();
+        this.roomListeners.clear();
+    }
+    on(room, callback) {
+        const roomId = typeof room === "string" ? room : room.id;
+        const set = this.roomListeners.get(roomId) ?? new Set();
+        set.add(callback);
+        this.roomListeners.set(roomId, set);
+    }
+    off(room, callback) {
+        const roomId = typeof room === "string" ? room : room.id;
+        const set = this.roomListeners.get(roomId);
+        if (!set)
+            return;
+        set.delete(callback);
+        if (set.size === 0)
+            this.roomListeners.delete(roomId);
+    }
+    send(room, content, replyTo) {
+        const roomId = typeof room === "string" ? room : room.id;
+        const connection = this.getConnection(roomId, "send");
+        connection.sendJson(buildAgentOutboundWsPayload({
+            userId: this.id,
+            content,
+            parentId: replyTo ?? null,
+            attachments: [],
+        }));
+    }
+    createStream(room, options) {
+        const roomId = typeof room === "string" ? room : room.id;
+        const connection = this.getConnection(roomId, "createStream");
+        return new FluxyMessageStream(connection, this.id, {
+            parentId: options?.parentId ?? null,
+            flushIntervalMs: options?.flushIntervalMs,
+        });
+    }
+    waitFor(room, predicate, options) {
+        const roomId = typeof room === "string" ? room : room.id;
+        const connection = this.getConnection(roomId, "waitFor");
+        return connection.waitFor((event) => event.type === "message" && predicate(event), options);
+    }
+    async invoke(room, content, options) {
+        const roomId = typeof room === "string" ? room : room.id;
+        return this.getClient().invokeAgentRest(this.id, roomId, content, {
+            replyTo: options?.replyTo,
+        });
+    }
+    getConnection(roomId, op) {
+        const connection = this.connections.get(roomId);
+        if (!connection) {
+            throw new Error(`Agent "${this.id}" has not joined room "${roomId}". Call join() before ${op}().`);
+        }
+        return connection;
+    }
+    async ensureRoomMembership(roomId) {
+        const admin = await mintWorkerToken({
+            baseUrl: this.baseUrl,
+            apiKey: this.apiKey,
+            userId: this.id,
+            roles: ["admin"],
+            ttlSeconds: 120,
+        });
+        const adminClient = new FluxyChatClient({
+            baseUrl: this.baseUrl,
+            userId: this.id,
+            token: admin.token,
+        });
+        try {
+            await adminClient.addRoomMember(roomId, this.id, "member");
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (!message.includes("409") && !message.toLowerCase().includes("already")) {
+                throw err;
+            }
+        }
+    }
+}
+export async function createFluxyAgent(config) {
+    const agent = new FluxyAgent(config);
+    await agent.init();
+    return agent;
+}

package/dist/mint.d.ts

@@ -0,0 +1,17 @@
+export interface MintTokenInput {
+    baseUrl: string;
+    apiKey: string;
+    userId: string;
+    roles?: string[];
+    ttlSeconds?: number;
+}
+export interface MintTokenResult {
+    token: string;
+    expiresIn: number;
+    claims: {
+        sub: string;
+        tid: string;
+        roles: string[];
+    };
+}
+export declare function mintWorkerToken(input: MintTokenInput): Promise<MintTokenResult>;

package/dist/mint.js

@@ -0,0 +1,29 @@
+function trimTrailingSlashes(url) {
+    let out = url;
+    while (out.endsWith("/"))
+        out = out.slice(0, -1);
+    return out;
+}
+export async function mintWorkerToken(input) {
+    const base = trimTrailingSlashes(input.baseUrl);
+    const res = await fetch(`${base}/auth/token`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "X-Fluxy-Api-Key": input.apiKey,
+        },
+        body: JSON.stringify({
+            userId: input.userId,
+            roles: input.roles ?? ["member"],
+            ttlSeconds: input.ttlSeconds ?? 3600,
+        }),
+    });
+    const json = (await res.json().catch(() => ({})));
+    if (!res.ok) {
+        throw new Error(json.error || `Mint token failed (${res.status})`);
+    }
+    if (!json.token) {
+        throw new Error("Worker did not return a token");
+    }
+    return json;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,56 @@
+import { FluxyChatClient, FluxyMessageStream, type FluxyChatAgentRun, type FluxyChatMessage, type FluxyRoomConnectionOptions, type FluxyWaitForOptions } from "@fluxychat/sdk";
+export { FluxyAuthError, FluxyConnectionError, FluxySendError, FluxyTimeoutError, } from "@fluxychat/sdk";
+export { mintWorkerToken, type MintTokenInput, type MintTokenResult } from "./mint";
+export interface FluxyAgentConfig {
+    /** Agent id  used as JWT `sub` / message `userId` (must match a row in `agents` for invoke). */
+    id: string;
+    name: string;
+    /** Project API key (`fc_…`) from the Worker / console. */
+    apiKey: string;
+    baseUrl?: string;
+    /** JWT roles (default `["member"]`). Use `["admin"]` only for bootstrap helpers. */
+    roles?: string[];
+    tokenTtlSeconds?: number;
+}
+export interface FluxyAgentJoinOptions {
+    /** POST /rooms/:id/members with a short-lived admin token if the agent is not in the room yet. */
+    ensureMembership?: boolean;
+    connection?: FluxyRoomConnectionOptions;
+}
+export declare class FluxyRoom {
+    readonly id: string;
+    constructor(roomId: string);
+}
+type RoomListener = (message: FluxyChatMessage) => void;
+export declare class FluxyAgent {
+    readonly id: string;
+    readonly name: string;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly roles;
+    private readonly tokenTtlSeconds;
+    private token;
+    private client;
+    private readonly connections;
+    private readonly roomListeners;
+    constructor(config: FluxyAgentConfig);
+    /** Mint JWT via Worker `POST /auth/token` and prepare REST/WS client. */
+    init(): Promise<this>;
+    getClient(): FluxyChatClient;
+    room(roomId: string): FluxyRoom;
+    join(room: FluxyRoom | string, options?: FluxyAgentJoinOptions): Promise<void>;
+    leave(room: FluxyRoom | string): void;
+    disconnect(): void;
+    on(room: FluxyRoom | string, callback: RoomListener): void;
+    off(room: FluxyRoom | string, callback: RoomListener): void;
+    send(room: FluxyRoom | string, content: string, replyTo?: number | null): void;
+    createStream(room: FluxyRoom | string): FluxyMessageStream;
+    waitFor(room: FluxyRoom | string, predicate: (message: FluxyChatMessage) => boolean, options?: FluxyWaitForOptions): Promise<FluxyChatMessage>;
+    invoke(room: FluxyRoom | string, content: string, options?: {
+        replyTo?: number | null;
+    }): Promise<FluxyChatAgentRun>;
+    private getConnection;
+    private ensureRoomMembership;
+}
+export declare function createFluxyAgent(config: FluxyAgentConfig): Promise<FluxyAgent>;
+export type { FluxyChatMessage, FluxyChatAgentRun, FluxyMessageStream, FluxyWaitForOptions };

package/dist/src/index.js

@@ -0,0 +1,175 @@
+import { FluxyChatClient, FluxyMessageStream, } from "@fluxychat/sdk";
+import { mintWorkerToken } from "./mint";
+export { FluxyAuthError, FluxyConnectionError, FluxySendError, FluxyTimeoutError, } from "@fluxychat/sdk";
+export { mintWorkerToken } from "./mint";
+const DEFAULT_BASE_URL = "http://127.0.0.1:8787";
+export class FluxyRoom {
+    constructor(roomId) {
+        this.id = roomId;
+    }
+}
+export class FluxyAgent {
+    constructor(config) {
+        this.token = null;
+        this.client = null;
+        this.connections = new Map();
+        this.roomListeners = new Map();
+        if (!config.id?.trim())
+            throw new Error("FluxyAgent requires id");
+        if (!config.apiKey?.trim())
+            throw new Error("FluxyAgent requires apiKey");
+        this.id = config.id.trim();
+        this.name = config.name?.trim() || this.id;
+        this.apiKey = config.apiKey.trim();
+        this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.roles = config.roles?.length ? config.roles : ["member"];
+        this.tokenTtlSeconds = config.tokenTtlSeconds ?? 3600;
+    }
+    /** Mint JWT via Worker `POST /auth/token` and prepare REST/WS client. */
+    async init() {
+        const minted = await mintWorkerToken({
+            baseUrl: this.baseUrl,
+            apiKey: this.apiKey,
+            userId: this.id,
+            roles: this.roles,
+            ttlSeconds: this.tokenTtlSeconds,
+        });
+        this.token = minted.token;
+        this.client = new FluxyChatClient({
+            baseUrl: this.baseUrl,
+            userId: this.id,
+            token: this.token,
+            apiKey: this.apiKey,
+        });
+        return this;
+    }
+    getClient() {
+        if (!this.client || !this.token) {
+            throw new Error("Call init() before using the agent client.");
+        }
+        return this.client;
+    }
+    room(roomId) {
+        return new FluxyRoom(roomId);
+    }
+    async join(room, options = {}) {
+        const roomId = typeof room === "string" ? room : room.id;
+        if (this.connections.has(roomId))
+            return;
+        if (options.ensureMembership) {
+            await this.ensureRoomMembership(roomId);
+        }
+        const client = this.getClient();
+        const connection = client.connectRoom(roomId, options.connection);
+        connection.addEventListener("message", (event) => {
+            if (event.type !== "message")
+                return;
+            const listeners = this.roomListeners.get(roomId);
+            if (!listeners)
+                return;
+            for (const cb of listeners) {
+                try {
+                    cb(event);
+                }
+                catch {
+                    /* ignore listener errors */
+                }
+            }
+        });
+        this.connections.set(roomId, connection);
+        connection.connect();
+    }
+    leave(room) {
+        const roomId = typeof room === "string" ? room : room.id;
+        const connection = this.connections.get(roomId);
+        if (!connection)
+            return;
+        connection.close();
+        this.connections.delete(roomId);
+        this.roomListeners.delete(roomId);
+    }
+    disconnect() {
+        for (const connection of this.connections.values()) {
+            connection.close();
+        }
+        this.connections.clear();
+        this.roomListeners.clear();
+    }
+    on(room, callback) {
+        const roomId = typeof room === "string" ? room : room.id;
+        const set = this.roomListeners.get(roomId) ?? new Set();
+        set.add(callback);
+        this.roomListeners.set(roomId, set);
+    }
+    off(room, callback) {
+        const roomId = typeof room === "string" ? room : room.id;
+        const set = this.roomListeners.get(roomId);
+        if (!set)
+            return;
+        set.delete(callback);
+        if (set.size === 0)
+            this.roomListeners.delete(roomId);
+    }
+    send(room, content, replyTo) {
+        const roomId = typeof room === "string" ? room : room.id;
+        const connection = this.getConnection(roomId, "send");
+        connection.sendJson({
+            type: "message",
+            userId: this.id,
+            content,
+            parentId: replyTo ?? null,
+            attachments: [],
+        });
+    }
+    createStream(room) {
+        const roomId = typeof room === "string" ? room : room.id;
+        const connection = this.getConnection(roomId, "createStream");
+        return new FluxyMessageStream(connection, this.id);
+    }
+    waitFor(room, predicate, options) {
+        const roomId = typeof room === "string" ? room : room.id;
+        const connection = this.getConnection(roomId, "waitFor");
+        return connection.waitFor((event) => event.type === "message" && predicate(event), options);
+    }
+    async invoke(room, content, options) {
+        const roomId = typeof room === "string" ? room : room.id;
+        return this.getClient().invokeAgentRest(this.id, roomId, content, {
+            replyTo: options?.replyTo,
+        });
+    }
+    getConnection(roomId, op) {
+        const connection = this.connections.get(roomId);
+        if (!connection) {
+            throw new Error(`Agent "${this.id}" has not joined room "${roomId}". Call join() before ${op}().`);
+        }
+        return connection;
+    }
+    async ensureRoomMembership(roomId) {
+        const admin = await mintWorkerToken({
+            baseUrl: this.baseUrl,
+            apiKey: this.apiKey,
+            userId: this.id,
+            roles: ["admin"],
+            ttlSeconds: 120,
+        });
+        const adminClient = new FluxyChatClient({
+            baseUrl: this.baseUrl,
+            userId: this.id,
+            token: admin.token,
+        });
+        try {
+            await adminClient.addRoomMember(roomId, this.id, "member");
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (!message.includes("409") && !message.toLowerCase().includes("already")) {
+                throw err;
+            }
+        }
+    }
+}
+export async function createFluxyAgent(config) {
+    const agent = new FluxyAgent(config);
+    await agent.init();
+    return agent;
+}

package/dist/src/mint.d.ts

@@ -0,0 +1,17 @@
+export interface MintTokenInput {
+    baseUrl: string;
+    apiKey: string;
+    userId: string;
+    roles?: string[];
+    ttlSeconds?: number;
+}
+export interface MintTokenResult {
+    token: string;
+    expiresIn: number;
+    claims: {
+        sub: string;
+        tid: string;
+        roles: string[];
+    };
+}
+export declare function mintWorkerToken(input: MintTokenInput): Promise<MintTokenResult>;

package/dist/src/mint.js

@@ -0,0 +1,23 @@
+export async function mintWorkerToken(input) {
+    const base = input.baseUrl.replace(/\/+$/, "");
+    const res = await fetch(`${base}/auth/token`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "X-Fluxy-Api-Key": input.apiKey,
+        },
+        body: JSON.stringify({
+            userId: input.userId,
+            roles: input.roles ?? ["member"],
+            ttlSeconds: input.ttlSeconds ?? 3600,
+        }),
+    });
+    const json = (await res.json().catch(() => ({})));
+    if (!res.ok) {
+        throw new Error(json.error || `Mint token failed (${res.status})`);
+    }
+    if (!json.token) {
+        throw new Error("Worker did not return a token");
+    }
+    return json;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+    "name":  "@fluxy-chat/agent",
+    "version":  "0.1.0",
+    "description":  "Fluxychat server-side agent SDK (WebSocket bots, streaming, waitFor)",
+    "license":  "MIT",
+    "author":  "Fluxychat",
+    "repository":  {
+                       "type":  "git",
+                       "url":  "git+https://github.com/AlessandroFare/fluxychat.git",
+                       "directory":  "packages/agent"
+                   },
+    "homepage":  "https://github.com/AlessandroFare/fluxychat/tree/main/packages/agent#readme",
+    "bugs":  {
+                 "url":  "https://github.com/AlessandroFare/fluxychat/issues"
+             },
+    "keywords":  [
+                     "chat",
+                     "agent",
+                     "bot",
+                     "realtime",
+                     "cloudflare",
+                     "fluxychat"
+                 ],
+    "main":  "dist/index.js",
+    "types":  "dist/index.d.ts",
+    "sideEffects":  false,
+    "files":  [
+                  "dist/",
+                  "README.md",
+                  "LICENSE"
+              ],
+    "publishConfig":  {
+                          "access":  "public"
+                      },
+    "engines":  {
+                    "node":  "\u003e=18.0.0"
+                },
+    "scripts":  {
+                    "build":  "tsc -p tsconfig.json",
+                    "dev":  "tsc -w -p tsconfig.json",
+                    "prepublishOnly":  "pnpm run build",
+                    "test":  "pnpm exec vitest run"
+                },
+    "dependencies":  {
+                         "@fluxy-chat/sdk":  "workspace:*"
+                     },
+    "devDependencies":  {
+                            "@types/node":  "^24.3.0",
+                            "typescript":  "latest",
+                            "vite":  "^8.0.16",
+                            "vitest":  "^4.1.5"
+                        }
+}