0
# Client Management
1

2
Core Pusher client functionality for establishing connections, managing global events, and controlling the overall WebSocket connection lifecycle.
3

4
## Capabilities
5

6
### Pusher Client Class
7

8
Main client class for managing connections to Pusher Channels.
9

10
```typescript { .api }
11
/**
12
 * Main Pusher client class for real-time communication
13
 * @param app_key - Your Pusher application key
14
 * @param options - Configuration options for the client
15
 */
16
class Pusher {
17
  constructor(app_key: string, options: Options);
18
  
19
  // Connection Management
20
  connect(): void;
21
  disconnect(): void;
22
  
23
  // Event Binding
24
  bind(event_name: string, callback: Function, context?: any): Pusher;
25
  unbind(event_name?: string, callback?: Function, context?: any): Pusher;
26
  bind_global(callback: Function): Pusher;
27
  unbind_global(callback?: Function): Pusher;
28
  unbind_all(callback?: Function): Pusher;
29
  
30
  // Channel Management
31
  subscribe(channel_name: string): Channel;
32
  unsubscribe(channel_name: string): void;
33
  subscribeAll(): void;
34
  channel(name: string): Channel;
35
  allChannels(): Channel[];
36
  
37
  // Client Events
38
  send_event(event_name: string, data: any, channel?: string): boolean;
39
  
40
  // User Authentication
41
  signin(): void;
42
  
43
  // Utilities
44
  shouldUseTLS(): boolean;
45
  
46
  // Static Properties
47
  static instances: Pusher[];
48
  static isReady: boolean;
49
  static logToConsole: boolean;
50
  static Runtime: AbstractRuntime;
51
  static ScriptReceivers: any;
52
  static DependenciesReceivers: any;
53
  static auth_callbacks: any;
54
  
55
  // Static Methods
56
  static ready(): void;
57
  static log: (message: any) => void;
58
  
59
  // Instance Properties
60
  key: string;
61
  channels: Channels;
62
  global_emitter: EventsDispatcher;
63
  connection: ConnectionManager;
64
  user: UserFacade;
65
  sessionID: number;
66
  timeline: Timeline;
67
  timelineSender: TimelineSender;
68
  timelineSenderTimer: PeriodicTimer;
69
}
70
```
71

72
**Usage Examples:**
73

74
```typescript
75
import Pusher from "pusher-js";
76

77
// Basic initialization
78
const pusher = new Pusher("your-app-key", {
79
  cluster: "us2"
80
});
81

82
// Advanced configuration
83
const pusher = new Pusher("your-app-key", {
84
  cluster: "us2",
85
  forceTLS: true,
86
  enableStats: true,
87
  activityTimeout: 120000,
88
  pongTimeout: 30000,
89
  channelAuthorization: {
90
    endpoint: "/pusher/auth",
91
    transport: "ajax"
92
  }
93
});
94

95
// Manual connection control
96
pusher.connect();
97
pusher.disconnect();
98
```
99

100
### Configuration Options
101

102
Complete configuration interface for Pusher client initialization.
103

104
```typescript { .api }
105
interface Options {
106
  // Required
107
  cluster: string;
108
  
109
  // Authentication
110
  authEndpoint?: string;
111
  authTransport?: 'ajax' | 'jsonp';
112
  channelAuthorization?: ChannelAuthorizationOptions;
113
  userAuthentication?: UserAuthenticationOptions;
114
  authorizer?: ChannelAuthorizerGenerator;
115
  auth?: DeprecatedAuthOptions;
116
  
117
  // Connection
118
  forceTLS?: boolean;
119
  wsHost?: string;
120
  wsPort?: number;
121
  wssPort?: number;
122
  httpHost?: string;
123
  httpPort?: number;
124
  httpsPort?: number;
125
  httpPath?: string;
126
  wsPath?: string;
127
  
128
  // Transport Control
129
  disabledTransports?: Transport[];
130
  enabledTransports?: Transport[];
131
  
132
  // Timeouts (in milliseconds)
133
  activityTimeout?: number;
134
  pongTimeout?: number;
135
  unavailableTimeout?: number;
136
  
137
  // Features
138
  enableStats?: boolean;
139
  disableStats?: boolean;
140
  ignoreNullOrigin?: boolean;
141
  
142
  // Advanced
143
  statsHost?: string;
144
  timelineParams?: any;
145
  nacl?: any;
146
}
147
```
148

149
**Configuration Examples:**
150

151
```typescript
152
// Minimal configuration
153
const pusher = new Pusher("app-key", { cluster: "us2" });
154

155
// Production configuration with authentication
156
const pusher = new Pusher("app-key", {
157
  cluster: "eu",
158
  forceTLS: true,
159
  channelAuthorization: {
160
    endpoint: "/pusher/auth",
161
    headers: {
162
      "X-CSRF-Token": "csrf-token"
163
    }
164
  },
165
  activityTimeout: 30000,
166
  pongTimeout: 6000
167
});
168

169
// Custom transport configuration
170
const pusher = new Pusher("app-key", {
171
  cluster: "us2",
172
  enabledTransports: ["ws", "wss"],
173
  disabledTransports: ["sockjs", "xhr_polling"]
174
});
175
```
176

177
### Global Event Binding
178

179
Bind to connection-level events that occur across all channels.
180

181
```typescript { .api }
182
/**
183
 * Bind to a global event
184
 * @param event_name - Name of the event to bind to
185
 * @param callback - Function to call when event occurs
186
 * @param context - Optional context for the callback
187
 * @returns The Pusher instance for chaining
188
 */
189
bind(event_name: string, callback: Function, context?: any): Pusher;
190

191
/**
192
 * Unbind from a global event
193
 * @param event_name - Optional event name (unbinds all if omitted)
194
 * @param callback - Optional specific callback to unbind
195
 * @param context - Optional context to match
196
 * @returns The Pusher instance for chaining
197
 */
198
unbind(event_name?: string, callback?: Function, context?: any): Pusher;
199

200
/**
201
 * Bind to all global events
202
 * @param callback - Function called for every global event
203
 * @returns The Pusher instance for chaining
204
 */
205
bind_global(callback: Function): Pusher;
206

207
/**
208
 * Unbind from all global events
209
 * @param callback - Optional specific callback to unbind
210
 * @returns The Pusher instance for chaining
211
 */
212
unbind_global(callback?: Function): Pusher;
213

214
/**
215
 * Unbind all global event handlers
216
 * @param callback - Optional callback (currently unused)
217
 * @returns The Pusher instance for chaining
218
 */
219
unbind_all(callback?: Function): Pusher;
220
```
221

222
**Event Binding Examples:**
223

224
```typescript
225
// Connection events
226
pusher.bind("connecting", () => {
227
  console.log("Connecting to Pusher...");
228
});
229

230
pusher.bind("connected", () => {
231
  console.log("Connected to Pusher");
232
});
233

234
pusher.bind("disconnected", () => {
235
  console.log("Disconnected from Pusher");
236
});
237

238
pusher.bind("error", (error) => {
239
  console.error("Pusher error:", error);
240
});
241

242
// Global event listener
243
pusher.bind_global((event_name, data) => {
244
  console.log(`Global event: ${event_name}`, data);
245
});
246

247
// Unbinding
248
pusher.unbind("connected", connectionHandler);
249
pusher.unbind_all(); // Remove all global bindings
250
```
251

252
### Client Events
253

254
Send client-triggered events through the connection.
255

256
```typescript { .api }
257
/**
258
 * Send a client event
259
 * @param event_name - Name of the event to send
260
 * @param data - Data to send with the event
261
 * @param channel - Optional channel to send event on
262
 * @returns true if event was sent successfully
263
 */
264
send_event(event_name: string, data: any, channel?: string): boolean;
265
```
266

267
**Client Event Examples:**
268

269
```typescript
270
// Send global client event
271
pusher.send_event("client-message", {
272
  message: "Hello from client"
273
});
274

275
// Send client event on specific channel
276
pusher.send_event("client-typing", {
277
  user: "alice",
278
  typing: true
279
}, "chat-room-1");
280
```
281

282
### User Authentication
283

284
Manage user authentication for presence channels.
285

286
```typescript { .api }
287
/**
288
 * Initiate user sign-in for presence channels
289
 */
290
signin(): void;
291

292
/**
293
 * Check if the connection should use TLS
294
 * @returns true if TLS should be used
295
 */
296
shouldUseTLS(): boolean;
297
```
298

299
### Static Methods
300

301
Class-level utilities and instance management.
302

303
```typescript { .api }
304
/**
305
 * Mark Pusher as ready and connect all instances
306
 */
307
static ready(): void;
308

309
/**
310
 * Logging function for Pusher messages
311
 */
312
static log: (message: any) => void;
313

314
// Static properties
315
static instances: Pusher[];      // All Pusher instances
316
static isReady: boolean;         // Global ready state
317
static logToConsole: boolean;    // Console logging flag
318
```
319

320
**Static Usage Examples:**
321

322
```typescript
323
// Enable console logging
324
Pusher.logToConsole = true;
325

326
// Custom logging
327
Pusher.log = (message) => {
328
  console.log("[Pusher]", message);
329
};
330

331
// Manual ready trigger (usually automatic)
332
Pusher.ready();
333

334
// Access all instances
335
console.log(`${Pusher.instances.length} Pusher instances`);
336
```
337

338
## Built-in Events
339

340
### Connection Events
341

342
- `connecting` - Connection attempt started
343
- `connected` - Successfully connected to Pusher
344
- `disconnected` - Disconnected from Pusher  
345
- `error` - Connection or protocol error occurred
346
- `unavailable` - Pusher service is unavailable
347
- `failed` - Connection failed permanently
348

349
### State Management Events
350

351
- `state_change` - Connection state changed
352
- `reconnecting` - Attempting to reconnect
353
- `reconnected` - Successfully reconnected