pusher_client_ego 1.0.0+6

A lightweight Flutter client for Pusher Channels, supporting public, private, and presence channels with real-time event binding and client event triggering — inspired by the official pusher-js library.

📡 PusherClient

A lightweight Flutter package that brings Pusher Channels real-time functionality to Flutter apps, inspired by the official pusher-js library.

---

🚀 Features

• ✅ Connect to Pusher via WebSocket
• 📢 Subscribe to public, private, and presence channels
• 📬 Bind to custom and system events
• 🔀 Bind to multiple events on the same channel
• 🎯 Bind to all events using null event name
• ❌ Unbind events to remove specific or all callbacks
• 🔐 Support for authenticated channels
• 🔄 Auto-handles pusher:connection_established, subscription_succeeded, etc.
• 🔄 Trigger client events on private channels (e.g., client-typing)
• 🧑‍🤝‍🧑 Presence channels with user tracking
• 🚪 Proper cleanup with close() method for channels

---

📦 Installation

dependencies:
pusher_client:
  git:
    url: https://github.com/yourusername/pusher_client.git

---

🛠️ Getting Started

1. Import and initialize

import 'package:pusher_client/pusher_client_ego.dart';

final pusher = PusherClient(
key: 'YOUR_PUSHER_KEY',
cluster: 'YOUR_CLUSTER',
authEndpoint: 'https://yourserver.com/pusher/auth', // Optional
headers: {
'Authorization': 'Bearer YOUR_TOKEN', // Optional
},
);

await pusher.connect();

---

2. Subscribe to a channel and bind to events

final channel = pusher.subscribe('public-chat');

// Bind to specific event
channel.bind(
  eventName: 'new-message',
  success: (event) {
    print('📩 Message: ${event.data}');
  },
  error: (error) {
    print('❌ Error: $error');
  },
);

// Bind to multiple events
channel.bind(
  eventName: 'user-joined',
  success: (event) => print('👋 User joined'),
);

channel.bind(
  eventName: 'user-left',
  success: (event) => print('👋 User left'),
);

// Bind to ALL events (eventName: null)
channel.bind(
  eventName: null,
  success: (event) => print('Any event: ${event['event']}'),
);

---

3. Unbind events

// Store callback reference if you need to remove it later
void myCallback(event) => print('Message: ${event.data}');

channel.bind(eventName: 'new-message', success: myCallback);

// Remove specific callback
channel.unbind(eventName: 'new-message', callback: myCallback);

// Remove ALL callbacks for an event
channel.unbind(eventName: 'new-message');

// Remove ALL callbacks for all events
channel.unbind(eventName: null);

4. Trigger a client event (private channels only)

final privateChannel = pusher.subscribe('private-room');

privateChannel.trigger('client-typing', {'user': 'Alice', 'isTyping': true});

5. Close a channel

// Properly unsubscribe and cleanup
channel.close();

---

🔐 Auth for Private & Presence Channels

Your backend must return a JSON object like this:

For Private Channels:

{
  "auth": "your_app_key:signature"
}

For Presence Channels:

{
  "auth": "your_app_key:signature",
  "channel_data": "{\"user_id\": \"123\", \"user_info\": {\"name\": \"Alice\"}}"
}

Use Pusher's official server SDKs to generate these responses:

• Node.js
• PHP
• Python

---

🧪 Example main.dart

void main() async {
final pusher = PusherClient(
key: 'APP_KEY',
cluster: 'APP_CLUSTER',
authEndpoint: 'https://your-auth-endpoint',
);

await pusher.connect();

final channel = pusher.subscribe('public-chat');

channel.bind(
  eventName: 'new-message',
  success: (event) => print('Received: ${event.data}'),
);

// Listen to all events
channel.bind(
  eventName: null,
  success: (event) => print('Event: ${event['event']}'),
);

await Future.delayed(Duration(days: 365)); // Keep alive

// Cleanup
channel.close();
await pusher.disconnect();
}

---

📚 API Reference

PusherClient

Method	Description
connect()	Establishes the WebSocket connection
subscribe(channel)	Subscribes to a channel and returns PusherChannel
disconnect()	Closes connection and clears all channels

PusherChannel

Method	Description
bind({eventName, success, error})	Binds callback to event (null = all events)
unbind({eventName, callback})	Removes specific or all callbacks
trigger(event, data)	Sends client event (private channels only)
close()	Unsubscribes and cleans up the channel

---

⚠️ Limitations

• This is a simplified version and doesn't include encryption or full presence features like member lists yet.
• Ensure your auth server signs correctly for private/presence channels.

---

📃 License

MIT © Omar Aly

---

🙌 Acknowledgments

Inspired by the official pusher-js and pusher-http libraries.