@gxp-dev/laravel-claim-check

Laravel Echo client interceptor for gramercytech/laravel-claim-check.

When the server-side wrapper detects an oversized broadcast payload, it stores the full payload in a cache and sends a small stub over Pusher instead. This package transparently fetches the full payload on receipt and forwards it to your registered listener — so application code never has to know.

Install

npm install @gxp-dev/laravel-claim-check
# or
pnpm add @gxp-dev/laravel-claim-check

Usage

Wrap your Echo instance once during bootstrap, after it's been constructed:

import Echo from "laravel-echo";
import Pusher from "pusher-js";
import { installClaimCheckInterceptor } from "@gxp-dev/laravel-claim-check";

window.Pusher = Pusher;

const echo = new Echo({
    broadcaster: "pusher",
    key: import.meta.env.VITE_PUSHER_APP_KEY,
    cluster: import.meta.env.VITE_PUSHER_APP_CLUSTER,
    forceTLS: true,
});

installClaimCheckInterceptor(echo);

// Use Echo normally — claim-checked payloads are fetched transparently.
echo.private(`user.${userId}`)
    .listen(".message.created", (payload) => {
        console.log(payload); // full payload, even if it was oversized
    });

Options

installClaimCheckInterceptor(echo, {
    // Custom fetch implementation (defaults to globalThis.fetch).
    fetch: customFetch,

    // CSRF token getter (defaults to <meta name="csrf-token">).
    csrfToken: () => myCsrfToken,

    // Force all fetches to a specific URL, ignoring the URL embedded in
    // the stub. Useful when running behind a custom domain or API gateway.
    fetchUrl: "https://api.example.com/broadcast-claim-check",

    // Custom logger.
    logger: { warn: console.warn, error: console.error },

    // Swallow errors thrown by listeners (logged instead). Defaults to false.
    swallowListenerErrors: false,
});

How it works

1. The server-side wrapper measures every outgoing broadcast.
2. If the payload exceeds the configured threshold (default 8KB), it's stored in the cache and a small stub { _cc: 1, u, id, e } is sent in its place.
3. This interceptor wraps echo.channel(), echo.private(), echo.encryptedPrivate(), and echo.join() so that every .listen() call gets a transparent unwrapper.
4. When a stub arrives, the interceptor POSTs { id, channel } to the server's fetch endpoint, which re-runs channel authorization before returning the original payload. The fetched payload is then forwarded to your listener as if it had been delivered directly.

Compatibility

• Laravel Echo ^1.15.0 and ^2.0.0
• Any broadcaster connector that delivers JSON payloads to listeners (Pusher, Reverb, Soketi, Ably)

License

MIT