Profiles·Public

pusher

semver^5.0.0postconditions6functions6last verified2026-04-11

Postconditions — what we check

trigger · api-error
error
WhenAny API or network failure: authentication error (401/403), rate limit (429), invalid app configuration (400), server error (5xx), network timeout, or connection failure
ThrowsPusher.RequestError with properties: status (HTTP code or undefined for network), error (underlying Error for network failures), body (API response text), url (request URL). Common cases: 403 for bad credentials, 429 for rate limit, 5xx for Pusher outage.
Required handlingCaller MUST wrap in try-catch. pusher.trigger() rejects on all API and network failures — there is no auto-retry. Unhandled rejections crash Node.js workers or produce silent data loss in async route handlers. Minimum handling: try { await pusher.trigger(channel, event, data); } catch (err) { if (err instanceof Pusher.RequestError) { console.error('Pusher trigger failed:', err.status, err.body); } throw err; } For fire-and-forget patterns (where trigger is a side effect), at minimum log the error rather than silently dropping it: pusher.trigger(channel, event, data).catch(err => console.error('Pusher failed:', err));
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[1]
triggerBatch · api-error
error
WhenAny API or network failure, including rate limit (429), auth error, server error, or network failure. Batch max of 10 events — exceeding it throws before any network call.
ThrowsPusher.RequestError (same as trigger) for API/network failures. Plain Error for exceeding batch size limit or invalid event structure.
Required handlingCaller MUST wrap in try-catch. A batch failure means ALL events in the batch were not delivered — callers should handle this atomically. try { await pusher.triggerBatch(events); } catch (err) { if (err instanceof Pusher.RequestError) { // All events failed — consider retry or fallback } throw err; }
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[2]
sendToUser · api-error
error
WhenAny API or network failure: invalid user ID format, auth error, server error, network failure, or rate limit
ThrowsPusher.RequestError for API/network failures. Plain Error for invalid userId (empty string, non-string value).
Required handlingCaller MUST wrap in try-catch. User notification failures should be handled gracefully — the primary action (DB write) may have succeeded even if the real-time notification fails. try { await pusher.sendToUser(userId, event, data); } catch (err) { if (err instanceof Pusher.RequestError) { console.error('Failed to notify user:', userId, err.status); } // Don't re-throw if notification failure should not abort the operation }
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[3]
terminateUserConnections · terminate-api-error
error
WhenAny API or network failure: authentication error (401/403 from Pusher API), server error (5xx), network timeout, or connection failure. Also throws synchronous plain Error for empty or non-string userId before any HTTP call.
ThrowsPusher.RequestError for API/network failures (status, body, url properties). Plain Error ("Invalid user id: '...'") for empty string or non-string userId — thrown synchronously before any network request.
Required handlingCaller MUST wrap in try-catch. terminateUserConnections() is typically called in ban/kick flows after a DB write. If the call fails (Pusher outage, auth error), the user may remain connected despite being banned in the database — a security gap. try { await pusher.terminateUserConnections(userId); } catch (err) { if (err instanceof Pusher.RequestError) { // Log and consider queuing for retry — user may still be connected console.error('Failed to terminate connections for', userId, err.status); await scheduleRetry(userId); } throw err; } Important: terminateUserConnections() disconnects existing sessions but does NOT prevent reconnection. Pair with blocking the user's authentication endpoint.
costhighin prodimmediate exceptionusers seesecurity breachvisibilitysilent
Sources[4][5]
get · get-api-error
error
WhenAny API or network failure: authentication error (401), forbidden (403, app disabled or quota exceeded), bad request (400, e.g. requesting user_count on non-presence channel), server error (5xx), or network failure/timeout.
ThrowsPusher.RequestError with status (HTTP code), body (API error text), url (request URL). Plain Error thrown synchronously if reserved param keys (auth_key, auth_timestamp, auth_version, auth_signature, body_md5) are included in params — throws before any network request.
Required handlingCaller MUST wrap in try-catch. get() is typically used to fetch presence channel data or verify channel state before performing an action. A 400 from requesting user_count on a non-presence channel is a programming error; 401/403 indicate misconfigured credentials. try { const response = await pusher.get({ path: '/channels', params: { filter_by_prefix: 'presence-', info: 'user_count' } }); if (response.status === 200) { const body = await response.json(); // use body.channels } } catch (err) { if (err instanceof Pusher.RequestError) { if (err.status === 400) { // Invalid params — likely programming error (e.g., user_count on public channel) } console.error('Pusher GET failed:', err.status, err.body); } throw err; }
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[6][7]
post · post-api-error
warning
WhenAny API or network failure: authentication error (401/403), bad request (400), payload too large (413, event data exceeds 10KB limit), server error (5xx), or network failure. Throws synchronously for reserved param keys in params.
ThrowsPusher.RequestError for all HTTP 4xx/5xx responses and network errors. Plain Error synchronously for reserved params (auth_key, auth_timestamp, etc.) before any network call. Note: HTTP 413 is returned when event data exceeds the 10KB Pusher payload limit — relevant when posting custom event payloads.
Required handlingCaller MUST wrap in try-catch. post() is most commonly called indirectly via terminateUserConnections() — see that function's error handling guidance. If calling post() directly, validate path correctness and payload size first. try { const response = await pusher.post({ path: '/events', body: JSON.stringify(payload) }); } catch (err) { if (err instanceof Pusher.RequestError) { if (err.status === 413) { // Payload too large — split or compress } console.error('Pusher POST failed:', err.status, err.body); } throw err; }
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[8][7]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

Need a different package?

Request a profile