Pusher-js Batch Authentication Plugin

Common errors

• Pusher: Auth channel failed for private-channel (403)

  cause The server-side authentication endpoint did not provide a valid batched response for one or more channels, or explicitly rejected authentication for a specific channel (e.g., with a 403 HTTP status).
  fix Verify your server-side authentication endpoint's logic. Ensure it correctly parses the batched channel names from the request and returns a JSON object with valid authentication data or appropriate error statuses for each requested channel, following the `pusher-js-auth` expected output format.

• TypeError: PusherBatchAuthorizer is not a constructor

  cause The `PusherBatchAuthorizer` symbol was not correctly imported or loaded before being passed to the `Pusher` client constructor, or it's being used with an incompatible `pusher-js` version.
  fix Ensure `pusher-js-auth` is correctly installed (`npm install pusher-js-auth`) and imported (`import { PusherBatchAuthorizer } from 'pusher-js-auth';` or `const { PusherBatchAuthorizer } = require('pusher-js-auth');`). Additionally, confirm that your `pusher-js` version is 7 or higher if you are using `pusher-js-auth` v4+.

Warnings

• breaking Pusher-js-auth v4.x is explicitly incompatible with `pusher-js` versions 6.0 and older. Using this version of the plugin with an older `pusher-js` client will lead to authentication failures.
  Fix: If using `pusher-js` v6 or older, downgrade this plugin to `pusher-js-auth` v3.x (`npm install pusher-js-auth@3`). For `pusher-js` v7+, ensure `pusher-js-auth` v4+ is used.
• gotcha Your server-side authentication endpoint must be designed to handle batched authentication requests. It expects an array of `channel_name` parameters and should return a batched JSON response.
  Fix: Implement or update your auth endpoint to parse `channel_name[0]`, `channel_name[1]`, etc., from incoming POST data. The endpoint must return a JSON object where keys are channel names and values are their respective authentication data or error statuses (e.g., `{'private-a': { 'auth': '...' }, 'private-c': { 'status': 403 }}`).
• gotcha The `authDelay` option (defaulting to 0 milliseconds) allows fine-tuning when authentication requests are sent. While it can be as low as 0, the very first authentication request is always internally postponed until the connection to Pusher is successfully established, regardless of this setting.
  Fix: Consider experimenting with `authDelay` if you observe unexpected authentication timing or wish to further optimize batching for extremely rapid channel subscriptions. For subscriptions within the same event loop, a value of 0 is typically sufficient.

Install

• npm install pusher-js-auth npm
• yarn add pusher-js-auth yarn
• pnpm add pusher-js-auth pnpm

Imports

• PusherBatchAuthorizer
  wrong:

  import PusherBatchAuthorizer from 'pusher-js-auth';

  correct:

  import { PusherBatchAuthorizer } from 'pusher-js-auth';

  The `PusherBatchAuthorizer` function is provided as a named export for ES Module environments. It is also available as a global variable (PusherBatchAuthorizer) when loaded via a script tag in browsers.
• PusherBatchAuthorizer
  wrong:

  const PusherBatchAuthorizer = require('pusher-js-auth');

  correct:

  const { PusherBatchAuthorizer } = require('pusher-js-auth');

  In CommonJS environments, `PusherBatchAuthorizer` is accessed via named property destructuring from the module export.

Quickstart

This quickstart demonstrates how to initialize the Pusher client with the `PusherBatchAuthorizer` and subscribe to multiple channels, showcasing how the plugin automatically batches authentication requests.

import Pusher from 'pusher-js'; // Assuming 'pusher-js' is installed
import { PusherBatchAuthorizer } from 'pusher-js-auth';

// Your Pusher app key (replace with environment variable in production)
const PUSHER_APP_KEY = process.env.PUSHER_APP_KEY ?? 'YOUR_APP_KEY';
// Your Pusher cluster (e.g., 'us2', 'eu')
const PUSHER_APP_CLUSTER = process.env.PUSHER_APP_CLUSTER ?? 'YOUR_CLUSTER';
// The endpoint on your server that handles batch authentication
const AUTH_ENDPOINT = process.env.PUSHER_AUTH_ENDPOINT ?? '/pusher/batch-auth';

// Initialize Pusher client with the batch authorizer
const pusher = new Pusher(PUSHER_APP_KEY, {
    cluster: PUSHER_APP_CLUSTER,
    authorizer: PusherBatchAuthorizer,
    authDelay: 200, // Optional: delay in milliseconds before executing auth request
    authEndpoint: AUTH_ENDPOINT // Ensure this points to your server-side batch auth handler
});

// Subscribe to multiple private and presence channels
// The PusherBatchAuthorizer will automatically batch authentication requests for these
// into a single HTTP call to the authEndpoint.
const privateChannel1 = pusher.subscribe('private-chat-1');
const privateChannel2 = pusher.subscribe('private-messages-user-abc');
const presenceChannel = pusher.subscribe('presence-online-users');

// Example of binding to an event on a channel
privateChannel1.bind('client-message', (data: any) => {
    console.log('Received message on private-chat-1:', data);
});

presenceChannel.bind('pusher:member_added', (member: any) => {
    console.log(`Member added to presence-online-users: ${member.id}`);
});

console.log('Pusher client initialized and channels subscribed. Authentication requests will be batched.');