@statezero/core 0.1.67 → 0.1.68

package/dist/core/eventReceivers.d.ts

@@ -69,11 +69,17 @@ export class PusherEventReceiver {
      */
     constructor(options: PusherReceiverOptions, configKey: string);
     configKey: string;
+    connectionTimeoutId: NodeJS.Timeout;
     pusherClient: Pusher;
     formatChannelName: (ns: string) => string;
     namespaceResolver: (modelName: string) => string;
     channels: Map<any, any>;
     eventHandlers: Set<any>;
+    /**
+     * @private
+     * @param {string} reason
+     */
+    private _logConnectionError;
     /**
      * Set the namespace resolver function.
      * @param {NamespaceResolver} resolver
@@ -176,4 +182,4 @@ export type PusherReceiverOptions = {
      */
     namespaceResolver?: NamespaceResolver | undefined;
 };
-import Pusher from 'pusher-js';
+import Pusher from "pusher-js";

package/dist/core/eventReceivers.js

@@ -1,4 +1,4 @@
-import Pusher from 'pusher-js';
+import Pusher from "pusher-js";
 /**
  * Structure of events received from the server.
  * @typedef {Object} ModelEvent
@@ -19,11 +19,11 @@ import Pusher from 'pusher-js';
  * @enum {string}
  */
 export const EventType = {
-    CREATE: 'create',
-    UPDATE: 'update',
-    DELETE: 'delete',
-    BULK_UPDATE: 'bulk_update',
-    BULK_DELETE: 'bulk_delete'
+    CREATE: "create",
+    UPDATE: "update",
+    DELETE: "delete",
+    BULK_UPDATE: "bulk_update",
+    BULK_DELETE: "bulk_delete",
 };
 /**
  * Callback for handling model events.
@@ -62,18 +62,67 @@ export class PusherEventReceiver {
      */
     constructor(options, configKey) {
         const { clientOptions, formatChannelName, namespaceResolver } = options;
+        const CONNECTION_TIMEOUT = 10000; // 10 seconds
         this.configKey = configKey;
+        this.connectionTimeoutId = null;
+        if (clientOptions.appKey &&
+            /^\d+$/.test(clientOptions.appKey) &&
+            clientOptions.appKey.length < 15) {
+            console.warn(`%c[Pusher Warning] The provided appKey ("${clientOptions.appKey}") looks like a numeric app_id. Pusher requires the alphanumeric key, not the ID. Please verify your configuration for backend: "${this.configKey}".`, "color: orange; font-weight: bold; font-size: 14px;");
+        }
         this.pusherClient = new Pusher(clientOptions.appKey, {
             cluster: clientOptions.cluster,
             forceTLS: clientOptions.forceTLS ?? true,
             authEndpoint: clientOptions.authEndpoint,
-            auth: { headers: clientOptions.getAuthHeaders?.() || {} }
+            auth: { headers: clientOptions.getAuthHeaders?.() || {} },
         });
-        this.formatChannelName = formatChannelName ?? (ns => `private-${ns}`);
-        this.namespaceResolver = namespaceResolver ?? (modelName => modelName);
+        this.pusherClient.connection.bind("connected", () => {
+            console.log(`Pusher client connected successfully for backend: ${this.configKey}.`);
+            if (this.connectionTimeoutId) {
+                clearTimeout(this.connectionTimeoutId);
+                this.connectionTimeoutId = null;
+            }
+        });
+        this.pusherClient.connection.bind("failed", () => {
+            this._logConnectionError("Pusher connection explicitly failed.");
+            if (this.connectionTimeoutId) {
+                clearTimeout(this.connectionTimeoutId);
+                this.connectionTimeoutId = null;
+            }
+        });
+        this.connectionTimeoutId = setTimeout(() => {
+            if (this.pusherClient.connection.state !== "connected") {
+                this._logConnectionError(`Pusher connection timed out after ${CONNECTION_TIMEOUT / 1000} seconds.`);
+            }
+        }, CONNECTION_TIMEOUT);
+        this.formatChannelName = formatChannelName ?? ((ns) => `private-${ns}`);
+        this.namespaceResolver = namespaceResolver ?? ((modelName) => modelName);
         this.channels = new Map();
         this.eventHandlers = new Set();
     }
+    /**
+     * @private
+     * @param {string} reason
+     */
+    _logConnectionError(reason) {
+        console.error(`%c
+████████████████████████████████████████████████████████████████
+█                                                              █
+█   PUSHER CONNECTION FAILED for backend: "${this.configKey}"  █
+█                                                              █
+████████████████████████████████████████████████████████████████
+%c
+Reason: ${reason}
+
+CRITICAL: Real-time updates from the server will NOT be received.
+This application will not reflect remote changes propagated via Pusher.
+
+Common causes:
+1. Incorrect 'appKey' or 'cluster' in the configuration.
+2. The 'authEndpoint' is unreachable or returning an error (check network tab).
+3. Network connectivity issues (firewall, offline).
+4. Using an 'app_id' instead of the 'appKey'.`, "background-color: red; color: white; font-weight: bold; font-size: 16px; padding: 10px;", "color: red; font-size: 12px;");
+    }
     /**
      * Set the namespace resolver function.
      * @param {NamespaceResolver} resolver
@@ -92,27 +141,29 @@ export class PusherEventReceiver {
     subscribe(namespace) {
         if (this.channels.has(namespace))
             return;
-        const channelName = namespace.startsWith('private-')
+        const channelName = namespace.startsWith("private-")
             ? namespace
             : this.formatChannelName(namespace);
         console.log(`Subscribing to channel: ${channelName} for backend: ${this.configKey}`);
         const channel = this.pusherClient.subscribe(channelName);
-        channel.bind('pusher:subscription_succeeded', () => {
+        channel.bind("pusher:subscription_succeeded", () => {
             console.log(`Subscription succeeded for channel: ${channelName}`);
         });
-        channel.bind('pusher:subscription_error', status => {
+        channel.bind("pusher:subscription_error", (status) => {
             console.error(`Subscription error for channel: ${channelName}. Status:`, status);
+            if (status.status === 401 || status.status === 403) {
+                console.error(`%cAuthentication failed for channel ${channelName}. Check your authEndpoint and server-side permissions.`, "color: orange; font-weight: bold;");
+            }
         });
-        // Listen for CRUD events
-        Object.values(EventType).forEach(eventType => {
-            channel.bind(eventType, data => {
+        Object.values(EventType).forEach((eventType) => {
+            channel.bind(eventType, (data) => {
                 const event = {
                     ...data,
                     type: data.event || eventType,
                     namespace,
-                    configKey: this.configKey
+                    configKey: this.configKey,
                 };
-                this.eventHandlers.forEach(handler => handler(event));
+                this.eventHandlers.forEach((handler) => handler(event));
             });
         });
         this.channels.set(namespace, channel);
@@ -121,10 +172,10 @@ export class PusherEventReceiver {
         const channel = this.channels.get(namespace);
         if (!channel)
             return;
-        Object.values(EventType).forEach(eventType => {
+        Object.values(EventType).forEach((eventType) => {
             channel.unbind(eventType);
         });
-        const channelName = namespace.startsWith('private-')
+        const channelName = namespace.startsWith("private-")
             ? namespace
             : this.formatChannelName(namespace);
         this.pusherClient.unsubscribe(channelName);
@@ -134,7 +185,11 @@ export class PusherEventReceiver {
      * Disconnect from Pusher.
      */
     disconnect() {
-        [...this.channels.keys()].forEach(ns => this.unsubscribe(ns));
+        if (this.connectionTimeoutId) {
+            clearTimeout(this.connectionTimeoutId);
+            this.connectionTimeoutId = null;
+        }
+        [...this.channels.keys()].forEach((ns) => this.unsubscribe(ns));
         this.pusherClient.disconnect();
     }
     /**
@@ -187,7 +242,7 @@ export function setEventReceiver(configKey, receiver) {
  * @param {string} configKey - The backend configuration key
  * @returns {EventReceiver|null}
  */
-export function getEventReceiver(configKey = 'default') {
+export function getEventReceiver(configKey = "default") {
     return eventReceivers.get(configKey);
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statezero/core",
-  "version": "0.1.67",
+  "version": "0.1.68",
   "type": "module",
   "module": "ESNext",
   "description": "The type-safe frontend client for StateZero - connect directly to your backend models with zero boilerplate",