fluxychat_sdk

Add in-app chat, AI agents, and multi-platform messaging with real-time WebSocket rooms, REST API, and full state management.

Installation

Add to your pubspec.yaml:

dependencies:
  fluxychat_sdk: ^1.0.0

Or from source:

dependencies:
  fluxychat_sdk:
    git:
      url: https://github.com/AlessandroFare/fluxychat.git
      path: packages/flutter-sdk

Quick Start

import 'package:fluxychat_sdk/fluxychat_sdk.dart';

final client = FluxyChatClient(
  config: FluxyChatConfig(
    apiUrl: 'https://your-worker.workers.dev',
    wsUrl: 'wss://your-worker.workers.dev',
    projectId: 'your-project-id',
    token: 'your-jwt-token',
  ),
);

// Connect to a room
await client.connect('room_123');

// Listen for messages
client.on('message', (event) {
  final message = event.data as Message;
  print('New message: ${message.content}');
});

// Send a message
await client.sendMessage(
  'room_123',
  content: 'Hello from Flutter!',
);

// Load message history
final messages = await client.loadMessages('room_123');

// Invoke an AI agent
final response = await client.invokeAgent(
  'room_123',
  agentId: 'support-bot',
  message: 'What are your hours?',
);

Features

• REST API — Rooms, messages, members, reactions, search
• WebSocket — Real-time messaging with auto-reconnect (exponential backoff)
• Typing indicators — Broadcast and receive typing status
• Presence — Online/offline tracking per room
• Read receipts — Track message delivery and read status
• Message reactions — Emoji reactions on messages
• AI agents — Invoke agents with streaming responses
• Message search — Full-text search across rooms
• Optimistic delivery — Instant UI updates with server confirmation
• E2E encryption — Client-side encryption support (TLS + Double Ratchet roadmap)
• Polls — Create and vote in polls
• File uploads — Multipart file upload support
• Push notifications — Web push and mobile device registration
• Custom domains — Domain management API
• Webhook management — Register and manage webhooks
• Scheduled messages — Schedule messages for future delivery
• Message templates — Template rendering with variable substitution
• Voice messages — Voice message sending support

API

FluxyChatClient

final client = FluxyChatClient(
  config: FluxyChatConfig(
    apiUrl: 'https://api.example.com',
    wsUrl: 'wss://api.example.com',
    projectId: 'proj_123',
    token: 'jwt_token',
    debug: false,
  ),
);

Connection

• connect(roomId) — Connect to a room via WebSocket
• disconnect() — Disconnect from current room
• connectionStatus — Stream of connection state changes
• connectUser() — Connect to user channel for personal events

Rooms

• listRooms() — List all accessible rooms
• getRoom(roomId) — Get room details
• createRoom(name, \{type\}) — Create a new room
• updateRoom(roomId, data) — Update room metadata
• deleteRoom(roomId) — Delete a room

Messages

• sendMessage(roomId, content, \{kind, metadata, parentId\}) — Send a message
• sendOptimisticMessage(roomId, content) — Send with optimistic UI update
• loadMessages(roomId, \{limit, before\}) — Load message history
• editMessage(roomId, messageId, content) — Edit a message
• deleteMessage(roomId, messageId) — Delete a message
• sendTyping(roomId, isTyping) — Send typing indicator
• addReaction(roomId, messageId, emoji) — Add emoji reaction
• removeReaction(roomId, messageId, emoji) — Remove reaction
• sendReadReceipt(roomId, messageId) — Mark message as read

AI Agents

• invokeAgent(roomId, agentId, message) — Invoke an AI agent
• listAgents() — List available agents
• getAgent(agentId) — Get agent details

Events

• on(event, handler) — Subscribe to events
• off(event, handler) — Unsubscribe from events
• onStatusChange(handler) — Connection status changes

Available events: message, message_edit, message_delete, typing, presence, reaction, read, member_joined, member_left, agentTyping, agentRun, stream, error

Protocol

The SDK implements the FluxyChat wire protocol (v1.0.0) with 30 inbound and 11 outbound event types. Protocol parity is validated against packages/protocol/protocol-events.json.

Testing

flutter test

Requirements

• Dart SDK >=3.2.0
• Flutter >=3.16.0

License

MIT — see LICENSE for details.