@wix/realtime 1.0.14 → 1.0.16

package/cjs/build/constants.d.ts

@@ -0,0 +1 @@
+export declare const DUPLEXER_HOST_URL = "duplexer.wix.com";

package/cjs/build/constants.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DUPLEXER_HOST_URL = void 0;
+exports.DUPLEXER_HOST_URL = 'duplexer.wix.com';

package/cjs/build/index.d.ts

@@ -0,0 +1,3 @@
+export * as site from '@wix/sdk_realtime_site';
+export * as publisher from './publisher/publisher.context.js';
+export * as subscriber from './subscriber/subscriber.context.js';

package/{build/cjs → cjs/build}/index.js

@@ -33,5 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.site = void 0;
+exports.subscriber = exports.publisher = exports.site = void 0;
 exports.site = __importStar(require("@wix/sdk_realtime_site"));
+exports.publisher = __importStar(require("./publisher/publisher.context.js"));
+exports.subscriber = __importStar(require("./subscriber/subscriber.context.js"));

package/cjs/build/publisher/publisher.context.d.ts

@@ -0,0 +1,37 @@
+import { publish as publicPublish } from './publisher.public.js';
+import type { BuildRESTFunction, MaybeContext } from '@wix/sdk-types';
+/**
+ * Publishes a message to a realtime channel.
+ *
+ * Must be called from a backend function (server-to-server) as it requires
+ * app-level permissions to publish messages via the Duplexer API.
+ *
+ * There are two ways to use this function depending on the Wix client type:
+ *
+ * **Manual client (self-hosted / explicit auth) — no elevation needed:**
+ * The client's own credentials (instanceId, metaSiteId) are used directly.
+ * This ensures messages are scoped to the correct site.
+ *
+ * ```ts
+ * import { publisher } from '@wix/realtime';
+ * import { createClient, AppStrategy } from '@wix/sdk';
+ *
+ * const client = createClient({
+ *   modules: { publisher },
+ *   auth: AppStrategy({ appId, appSecret, instanceId }),
+ * });
+ * await client.publisher.publish({ name: 'my-channel' }, { message: 'hello' });
+ * ```
+ *
+ * **Contextual client (Wix-hosted) — elevation needed:**
+ * The contextual httpClient may not have sufficient permissions on its own.
+ * Wrap the call with `elevate()` to obtain the host's backend credentials.
+ *
+ * ```ts
+ * import { publisher } from '@wix/realtime';
+ * import { elevate } from '@wix/sdk/context';
+ *
+ * await elevate(publisher.publish)({ name: 'my-channel' }, { message: 'hello' });
+ * ```
+ */
+export declare const publish: MaybeContext<BuildRESTFunction<typeof publicPublish> & typeof publicPublish>;

package/cjs/build/publisher/publisher.context.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publish = void 0;
+const publisher_public_js_1 = require("./publisher.public.js");
+const rest_modules_1 = require("@wix/sdk-runtime/rest-modules");
+/**
+ * Publishes a message to a realtime channel.
+ *
+ * Must be called from a backend function (server-to-server) as it requires
+ * app-level permissions to publish messages via the Duplexer API.
+ *
+ * There are two ways to use this function depending on the Wix client type:
+ *
+ * **Manual client (self-hosted / explicit auth) — no elevation needed:**
+ * The client's own credentials (instanceId, metaSiteId) are used directly.
+ * This ensures messages are scoped to the correct site.
+ *
+ * ```ts
+ * import { publisher } from '@wix/realtime';
+ * import { createClient, AppStrategy } from '@wix/sdk';
+ *
+ * const client = createClient({
+ *   modules: { publisher },
+ *   auth: AppStrategy({ appId, appSecret, instanceId }),
+ * });
+ * await client.publisher.publish({ name: 'my-channel' }, { message: 'hello' });
+ * ```
+ *
+ * **Contextual client (Wix-hosted) — elevation needed:**
+ * The contextual httpClient may not have sufficient permissions on its own.
+ * Wrap the call with `elevate()` to obtain the host's backend credentials.
+ *
+ * ```ts
+ * import { publisher } from '@wix/realtime';
+ * import { elevate } from '@wix/sdk/context';
+ *
+ * await elevate(publisher.publish)({ name: 'my-channel' }, { message: 'hello' });
+ * ```
+ */
+exports.publish = (0, rest_modules_1.createRESTModule)(publisher_public_js_1.publish);

package/cjs/build/publisher/publisher.public.d.ts

@@ -0,0 +1,12 @@
+import type { Channel } from '@wix/realtime-common/types';
+import type { HttpClient } from '@wix/sdk-types';
+interface PublishSignature {
+    (channel: Channel, payload: Record<string, any>): Promise<void>;
+}
+/**
+ * Publish a message to a channel.
+ * @param channel - The channel, and optionally the resource, to publish to.
+ * @param payload - Message payload. Max: 10kb
+ */
+export declare function publish(httpClient: HttpClient): PublishSignature;
+export {};

package/cjs/build/publisher/publisher.public.js

@@ -0,0 +1,74 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publish = publish;
+const auto_sdk_duplexer_publisher_1 = require("@wix/auto_sdk_duplexer_publisher");
+const realtime_common_1 = require("@wix/realtime-common");
+const site = __importStar(require("@wix/sdk_realtime_site"));
+const errors_js_1 = require("../subscriber/errors.js");
+/**
+ * Publish a message to a channel.
+ * @param channel - The channel, and optionally the resource, to publish to.
+ * @param payload - Message payload. Max: 10kb
+ */
+function publish(httpClient) {
+    // autoSdkPublish is the auto-generated Duplexer publish module, wrapped by
+    // createRESTModule(descriptor). The raw descriptor has the signature:
+    //   (httpClient) => (message, options) => Promise<void>
+    //
+    // We call it directly with our httpClient to bind the publish function to
+    // this client's auth credentials. This ensures the correct instanceId and
+    // metaSiteId are used in the publish request — critical for site-level
+    // message isolation in multi-site scenarios.
+    //
+    // Without this binding, the auto-generated module would resolve its own
+    // httpClient via the global Wix context, which always returns the host
+    // site's credentials — ignoring any manual client auth provided via
+    // createClient({ auth: AppStrategy({...}) }).
+    //
+    // For contextual usage (no explicit auth), the caller should wrap this
+    // function with elevate() to obtain the host's backend credentials:
+    //   elevate(realtimePublisher.publish)(channel, payload)
+    const boundPublish = auto_sdk_duplexer_publisher_1.publish(httpClient);
+    return (channel, payload) => {
+        (0, errors_js_1.validateChannel)(channel);
+        if ((0, realtime_common_1.isVeloEnvironment)()) {
+            return Promise.resolve(site.publish(channel, payload));
+        }
+        return boundPublish({ eventName: realtime_common_1.MESSAGE_EVENT_NAME, payload }, { channels: [channel.name], resourceId: channel.resourceId }).catch((error) => {
+            throw new Error(`Failed to publish: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        });
+    };
+}

package/cjs/build/subscriber/errors.d.ts

@@ -0,0 +1,16 @@
+import { RealtimeError, type Channel } from '@wix/realtime-common/types';
+export declare function missingChannelOrSubscriptionId(): RealtimeError;
+export declare function channelMismatch(): RealtimeError;
+export declare function invalidChannel(channel: Channel): RealtimeError;
+export declare function validateChannel(channel: Channel): void;
+export declare function disconnectedError(recoverable?: boolean, message?: string): RealtimeError;
+export declare function connectError(recoverable?: boolean, message?: string): RealtimeError;
+export declare function subscribeFailed(channel: Channel, payload?: {
+    status?: number;
+    message?: string;
+}): RealtimeError;
+export declare function resubscribeFailed(channel: Channel, payload?: {
+    status?: number;
+    message?: string;
+}): RealtimeError;
+export declare function subscribeError(error: unknown, channel: Channel): RealtimeError;

package/cjs/build/subscriber/errors.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.missingChannelOrSubscriptionId = missingChannelOrSubscriptionId;
+exports.channelMismatch = channelMismatch;
+exports.invalidChannel = invalidChannel;
+exports.validateChannel = validateChannel;
+exports.disconnectedError = disconnectedError;
+exports.connectError = connectError;
+exports.subscribeFailed = subscribeFailed;
+exports.resubscribeFailed = resubscribeFailed;
+exports.subscribeError = subscribeError;
+const types_1 = require("@wix/realtime-common/types");
+function missingChannelOrSubscriptionId() {
+    return new types_1.RealtimeError(types_1.RealtimeErrorCode.BadInput, 'channel or subscriptionId is required');
+}
+function channelMismatch() {
+    return new types_1.RealtimeError(types_1.RealtimeErrorCode.BadInput, 'channel does not match subscriptionId');
+}
+const realtime_common_1 = require("@wix/realtime-common");
+function invalidChannel(channel) {
+    const { name, resourceId } = channel;
+    const reasons = [];
+    if (!name) {
+        reasons.push('name must not be empty');
+    }
+    else {
+        if (!realtime_common_1.CHANNEL_NAME_PATTERN.test(name)) {
+            reasons.push('name must contain only alphanumeric characters, hyphens, or underscores');
+        }
+    }
+    const combinedLength = (name?.length ?? 0) + (resourceId?.length ?? 0);
+    if (combinedLength > realtime_common_1.CHANNEL_NAME_MAX_LENGTH) {
+        reasons.push(`combined channel name and resourceId length is ${combinedLength} characters (max ${realtime_common_1.CHANNEL_NAME_MAX_LENGTH})`);
+    }
+    return new types_1.RealtimeError(types_1.RealtimeErrorCode.BadInput, `Invalid channel "${name}": ${reasons.join('; ')}.`);
+}
+function validateChannel(channel) {
+    const { name, resourceId } = channel;
+    const combinedLength = (name?.length ?? 0) + (resourceId?.length ?? 0);
+    if (!name ||
+        !realtime_common_1.CHANNEL_NAME_PATTERN.test(name) ||
+        combinedLength > realtime_common_1.CHANNEL_NAME_MAX_LENGTH) {
+        throw invalidChannel(channel);
+    }
+}
+function disconnectedError(recoverable, message) {
+    return new types_1.RealtimeError(types_1.RealtimeErrorCode.Disconnected, message || 'disconnected', { recoverable });
+}
+function connectError(recoverable, message) {
+    return new types_1.RealtimeError(types_1.RealtimeErrorCode.ConnectionError, message || 'connection error', { recoverable });
+}
+function subscriptionFailed(prefix, channel, payload) {
+    const msg = payload?.message
+        ? `${prefix} failed: ${payload.message} (status ${payload.status})`
+        : `${prefix} failed`;
+    return new types_1.RealtimeError(types_1.RealtimeErrorCode.SubscriptionFailed, msg, {
+        channel,
+        recoverable: false,
+        status: payload?.status,
+    });
+}
+function subscribeFailed(channel, payload) {
+    return subscriptionFailed('subscribe', channel, payload);
+}
+function resubscribeFailed(channel, payload) {
+    return subscriptionFailed('resubscribe', channel, payload);
+}
+function subscribeError(error, channel) {
+    return new types_1.RealtimeError(types_1.RealtimeErrorCode.SubscriptionFailed, error instanceof Error ? error.message : 'subscribe failed', { channel, recoverable: false });
+}

package/cjs/build/subscriber/subscriber.context.d.ts

@@ -0,0 +1,4 @@
+import { subscribe as publicSubscribe, unsubscribe as publicUnsubscribe } from './subscriber.public.js';
+import type { BuildRESTFunction, MaybeContext } from '@wix/sdk-types';
+export declare const subscribe: MaybeContext<BuildRESTFunction<typeof publicSubscribe> & typeof publicSubscribe>;
+export declare const unsubscribe: MaybeContext<BuildRESTFunction<typeof publicUnsubscribe> & typeof publicUnsubscribe>;

package/cjs/build/subscriber/subscriber.context.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unsubscribe = exports.subscribe = void 0;
+const subscriber_public_js_1 = require("./subscriber.public.js");
+const rest_modules_1 = require("@wix/sdk-runtime/rest-modules");
+exports.subscribe = (0, rest_modules_1.createRESTModule)(subscriber_public_js_1.subscribe);
+exports.unsubscribe = (0, rest_modules_1.createRESTModule)(subscriber_public_js_1.unsubscribe);

package/cjs/build/subscriber/subscriber.public.d.ts

@@ -0,0 +1,21 @@
+import { type Channel, type MessageHandler, type SubscriptionOptions, type UnsubscribeOptions } from '@wix/realtime-common/types';
+import type { HttpClient } from '@wix/sdk-types';
+interface SubscribeSignature {
+    (channel: Channel, messageHandler: MessageHandler, options?: SubscriptionOptions): string;
+}
+/**
+ * Subscribe to a channel. Returns a subscriptionId immediately; the
+ * actual connection is established asynchronously in the background. Use the
+ * optional `options` parameter to handle subscription lifecycle events.
+ */
+export declare function subscribe(httpClient: HttpClient): SubscribeSignature;
+interface UnsubscribeSignature {
+    (options: UnsubscribeOptions): void;
+}
+/**
+ * Unsubscribe from a subscription by its ID, by channel, or both.
+ */
+export declare function unsubscribe(_: HttpClient): UnsubscribeSignature;
+/** @internal Resets all module-level state. Only for use in tests. */
+export declare function _resetForTesting(): void;
+export {};

package/cjs/build/subscriber/subscriber.public.js

@@ -0,0 +1,234 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.subscribe = subscribe;
+exports.unsubscribe = unsubscribe;
+exports._resetForTesting = _resetForTesting;
+const duplexer_js_1 = require("@wix/duplexer-js");
+const realtime_common_1 = require("@wix/realtime-common");
+const uuid_1 = require("uuid");
+const constants_js_1 = require("../constants.js");
+const errors_js_1 = require("./errors.js");
+const subscription_manager_js_1 = require("./subscription-manager.js");
+const instanceConnections = new Map();
+const subscriptionManager = new subscription_manager_js_1.SubscriptionManager();
+/**
+ * Subscribe to a channel. Returns a subscriptionId immediately; the
+ * actual connection is established asynchronously in the background. Use the
+ * optional `options` parameter to handle subscription lifecycle events.
+ */
+function subscribe(httpClient) {
+    return (channel, messageHandler, options) => {
+        (0, errors_js_1.validateChannel)(channel);
+        const subscriptionId = `sub_${(0, uuid_1.v4)()}`;
+        subscriptionManager.set(subscriptionId, {
+            channelName: channel.name,
+            channelResourceId: channel.resourceId,
+            removeListeners: () => { },
+            onSubscribed: options?.onSubscribed,
+            onSubscriptionError: options?.onSubscriptionError,
+        });
+        void setupSubscription(httpClient, subscriptionId, channel, messageHandler);
+        return subscriptionId;
+    };
+}
+/**
+ * Unsubscribe from a subscription by its ID, by channel, or both.
+ */
+function unsubscribe(_) {
+    return ({ channel, subscriptionId }) => {
+        if (!channel && !subscriptionId) {
+            throw (0, errors_js_1.missingChannelOrSubscriptionId)();
+        }
+        if (subscriptionId) {
+            unsubscribeById(subscriptionId, channel);
+        }
+        else if (channel) {
+            unsubscribeByChannel(channel);
+        }
+    };
+}
+/** @internal Resets all module-level state. Only for use in tests. */
+function _resetForTesting() {
+    subscriptionManager.removeAll();
+    for (const { socket, duplexer } of instanceConnections.values()) {
+        socket.disconnect();
+        duplexer.close();
+    }
+    instanceConnections.clear();
+    realtime_common_1.tokenToAppInfoCache.clear();
+}
+function unsubscribeById(subscriptionId, channel) {
+    const subscription = subscriptionManager.get(subscriptionId);
+    if (!subscription) {
+        return;
+    }
+    if (channel &&
+        (channel.name !== subscription.channelName ||
+            channel.resourceId !== subscription.channelResourceId)) {
+        throw (0, errors_js_1.channelMismatch)();
+    }
+    subscription.removeListeners();
+    const { channelName, channelResourceId, instanceId, channelEmitter } = subscription;
+    // If subscription is still pending (no channelEmitter/instanceId), mark
+    // cancelled so the in-flight setupSubscription knows to bail out.
+    if (!channelEmitter || !instanceId) {
+        subscription.cancelled = true;
+        subscriptionManager.delete(subscriptionId);
+        if (instanceId) {
+            cleanupConnectionIfIdle(instanceId);
+        }
+        return;
+    }
+    // If no other subscriptions remain on this channel, fire-and-forget
+    // the duplexer unsubscribe.
+    const hasOtherSubscriptionsOnChannel = subscriptionManager.deleteAndStillHasRemainingOnChannel(instanceId, subscriptionId, channelName, channelResourceId);
+    if (!hasOtherSubscriptionsOnChannel) {
+        const conn = instanceConnections.get(instanceId);
+        if (conn) {
+            conn.socket.unsubscribe(channelName, channelResourceId);
+        }
+    }
+    cleanupConnectionIfIdle(instanceId);
+}
+function unsubscribeByChannel(channel) {
+    const entriesToRemove = subscriptionManager.findByChannel(channel.name, channel.resourceId);
+    for (const [id] of entriesToRemove) {
+        unsubscribeById(id);
+    }
+}
+function closeConnection(instanceId) {
+    const conn = instanceConnections.get(instanceId);
+    if (conn) {
+        conn.socket.removeAllListeners();
+        conn.socket.disconnect();
+        conn.duplexer.close();
+        instanceConnections.delete(instanceId);
+    }
+}
+/** Clean up the connection for an instanceId if it has no remaining subscriptions. */
+function cleanupConnectionIfIdle(instanceId) {
+    if (!subscriptionManager.hasSubscriptionsForInstanceId(instanceId)) {
+        closeConnection(instanceId);
+    }
+}
+function getOrCreateConnection(httpClient, appId, instanceId) {
+    const existing = instanceConnections.get(instanceId);
+    if (existing) {
+        return existing;
+    }
+    const duplexer = new duplexer_js_1.Duplexer(constants_js_1.DUPLEXER_HOST_URL, {
+        instanceUpdater: {
+            getInstance: realtime_common_1.getAuthToken.bind(null, httpClient),
+        },
+    });
+    const socket = duplexer.connect({
+        appDefId: appId,
+    });
+    const notifySubscriptionError = (realtimeError) => {
+        for (const subId of subscriptionManager.getSubscriptionIdsByInstanceId(instanceId)) {
+            subscriptionManager
+                .get(subId)
+                ?.onSubscriptionError?.(realtimeError, subId);
+        }
+    };
+    socket.on(realtime_common_1.DUPLEXER_EVENTS.disconnected, (error) => {
+        notifySubscriptionError((0, errors_js_1.disconnectedError)(error?.recoverable, error?.message));
+    });
+    socket.on(realtime_common_1.DUPLEXER_EVENTS.connectError, (error) => {
+        notifySubscriptionError((0, errors_js_1.connectError)(error?.recoverable, error?.message));
+    });
+    const connection = { duplexer, socket };
+    instanceConnections.set(instanceId, connection);
+    return connection;
+}
+async function setupSubscription(httpClient, subscriptionId, channel, messageHandler) {
+    try {
+        const { appId, instanceId } = await (0, realtime_common_1.getAppInfoFromAuthToken)(httpClient);
+        const subscriptionEntry = subscriptionManager.get(subscriptionId);
+        // Entry was already deleted (e.g., unsubscribe called during the await)
+        // or explicitly cancelled — bail out.
+        if (!subscriptionEntry || subscriptionEntry.cancelled) {
+            subscriptionManager.delete(subscriptionId);
+            return;
+        }
+        // Index the subscription by instanceId now so cleanupConnectionIfIdle
+        // correctly counts it while the duplexer subscription is being set up.
+        subscriptionManager.set(subscriptionId, {
+            ...subscriptionEntry,
+            instanceId,
+        });
+        const { socket } = getOrCreateConnection(httpClient, appId, instanceId);
+        const onMessageCallback = (payload, { publisher }) => {
+            messageHandler({
+                payload,
+                publisher: publisher?.uid ? { id: publisher.uid } : undefined,
+            }, channel);
+        };
+        // --- callback definitions (hoisted above subscribe for #6 race fix) ---
+        function onSubscribeSucceeded(payload) {
+            subscribedChannel.off(realtime_common_1.DUPLEXER_EVENTS.subscriptionFailed, onSubscribeFailed);
+            // If the subscription was removed (via unsubscribe) while waiting for
+            // the duplexer to confirm, clean up the duplexer channel to avoid a
+            // server-side subscription leak.
+            if (!subscriptionManager.get(subscriptionId)) {
+                socket.unsubscribe(channel.name, channel.resourceId);
+                cleanupConnectionIfIdle(instanceId);
+                return;
+            }
+            subscribedChannel.on(realtime_common_1.MESSAGE_EVENT_NAME, onMessageCallback);
+            // Fire onSubscribed for the initial subscription — re-read from the
+            // manager to avoid using a stale closure reference.
+            subscriptionManager
+                .get(subscriptionId)
+                ?.onSubscribed?.(subscriptionId, payload?.isSynced ?? false);
+            // Listen for resubscription succeeded (fires after reconnection)
+            const onResubscribeSucceeded = (payload) => {
+                if (subscriptionManager.get(subscriptionId)) {
+                    subscriptionManager
+                        .get(subscriptionId)
+                        ?.onSubscribed?.(subscriptionId, payload?.isSynced ?? false);
+                }
+            };
+            subscribedChannel.on(realtime_common_1.DUPLEXER_EVENTS.subscriptionSucceeded, onResubscribeSucceeded);
+            const onResubscribeFailed = (payload) => {
+                subscriptionManager
+                    .get(subscriptionId)
+                    ?.onSubscriptionError?.((0, errors_js_1.resubscribeFailed)(channel, payload), subscriptionId);
+            };
+            subscribedChannel.on(realtime_common_1.DUPLEXER_EVENTS.subscriptionFailed, onResubscribeFailed);
+            const currentEntry = subscriptionManager.get(subscriptionId);
+            subscriptionManager.set(subscriptionId, {
+                channelName: channel.name,
+                channelResourceId: channel.resourceId,
+                instanceId,
+                channelEmitter: subscribedChannel,
+                onSubscribed: currentEntry?.onSubscribed,
+                onSubscriptionError: currentEntry?.onSubscriptionError,
+                removeListeners: () => {
+                    subscribedChannel.off(realtime_common_1.MESSAGE_EVENT_NAME, onMessageCallback);
+                    subscribedChannel.off(realtime_common_1.DUPLEXER_EVENTS.subscriptionSucceeded, onResubscribeSucceeded);
+                    subscribedChannel.off(realtime_common_1.DUPLEXER_EVENTS.subscriptionFailed, onResubscribeFailed);
+                },
+            });
+        }
+        function onSubscribeFailed(payload) {
+            subscribedChannel.off(realtime_common_1.DUPLEXER_EVENTS.subscriptionSucceeded, onSubscribeSucceeded);
+            const failedEntry = subscriptionManager.get(subscriptionId);
+            subscriptionManager.delete(subscriptionId);
+            failedEntry?.onSubscriptionError?.((0, errors_js_1.subscribeFailed)(channel, payload), subscriptionId);
+            cleanupConnectionIfIdle(instanceId);
+        }
+        // Subscribe to the duplexer channel and register lifecycle listeners
+        // in the same synchronous block so no events can be missed.
+        const subscribedChannel = socket.subscribe(channel.name, {
+            resourceId: channel.resourceId,
+        });
+        subscribedChannel.once(realtime_common_1.DUPLEXER_EVENTS.subscriptionSucceeded, onSubscribeSucceeded);
+        subscribedChannel.once(realtime_common_1.DUPLEXER_EVENTS.subscriptionFailed, onSubscribeFailed);
+    }
+    catch (error) {
+        const sub = subscriptionManager.get(subscriptionId);
+        subscriptionManager.delete(subscriptionId);
+        sub?.onSubscriptionError?.((0, errors_js_1.subscribeError)(error, channel), subscriptionId);
+    }
+}

package/cjs/build/subscriber/subscription-manager.d.ts

@@ -0,0 +1,26 @@
+import type { Duplexer } from '@wix/duplexer-js';
+import type { SubscriptionHandler, SubscriptionErrorHandler } from '@wix/realtime-common/types';
+export interface SubscriptionEntry {
+    channelName: string;
+    channelResourceId?: string;
+    instanceId?: string;
+    channelEmitter?: ReturnType<ReturnType<Duplexer['connect']>['subscribe']>;
+    removeListeners: () => void;
+    cancelled?: boolean;
+    onSubscribed?: SubscriptionHandler;
+    onSubscriptionError?: SubscriptionErrorHandler;
+}
+export declare class SubscriptionManager {
+    private subscriptionsBySubId;
+    private instanceIdToSubscriptionIds;
+    set(id: string, entry: SubscriptionEntry): void;
+    get(id: string): SubscriptionEntry | undefined;
+    delete(id: string): void;
+    findByChannel(channelName: string, channelResourceId?: string): [string, SubscriptionEntry][];
+    deleteAndStillHasRemainingOnChannel(instanceId: string, subscriptionIdToDelete: string, channelName: string, resourceId?: string): boolean;
+    hasSubscriptionsForInstanceId(instanceId: string): boolean;
+    getSubscriptionIdsByInstanceId(instanceId: string): string[];
+    removeAll(): void;
+    private addToInstanceIndex;
+    private removeFromInstanceIndex;
+}

package/cjs/build/subscriber/subscription-manager.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubscriptionManager = void 0;
+class SubscriptionManager {
+    subscriptionsBySubId = new Map();
+    instanceIdToSubscriptionIds = new Map();
+    set(id, entry) {
+        this.subscriptionsBySubId.set(id, entry);
+        if (entry.instanceId) {
+            this.addToInstanceIndex(entry.instanceId, id);
+        }
+    }
+    get(id) {
+        return this.subscriptionsBySubId.get(id);
+    }
+    delete(id) {
+        const entry = this.subscriptionsBySubId.get(id);
+        if (entry?.instanceId) {
+            this.removeFromInstanceIndex(entry.instanceId, id);
+        }
+        this.subscriptionsBySubId.delete(id);
+    }
+    findByChannel(channelName, channelResourceId) {
+        return [...this.subscriptionsBySubId.entries()].filter(([, sub]) => sub.channelName === channelName &&
+            sub.channelResourceId === channelResourceId);
+    }
+    deleteAndStillHasRemainingOnChannel(instanceId, subscriptionIdToDelete, channelName, resourceId) {
+        this.delete(subscriptionIdToDelete);
+        const candidateIds = this.instanceIdToSubscriptionIds.get(instanceId);
+        if (!candidateIds)
+            return false;
+        for (const id of candidateIds) {
+            const sub = this.subscriptionsBySubId.get(id);
+            if (sub &&
+                sub.channelName === channelName &&
+                sub.channelResourceId === resourceId) {
+                return true;
+            }
+        }
+        return false;
+    }
+    hasSubscriptionsForInstanceId(instanceId) {
+        const ids = this.instanceIdToSubscriptionIds.get(instanceId);
+        return !!ids && ids.size > 0;
+    }
+    getSubscriptionIdsByInstanceId(instanceId) {
+        const ids = this.instanceIdToSubscriptionIds.get(instanceId);
+        return ids ? [...ids] : [];
+    }
+    removeAll() {
+        for (const [, sub] of this.subscriptionsBySubId) {
+            sub.removeListeners();
+        }
+        this.subscriptionsBySubId.clear();
+        this.instanceIdToSubscriptionIds.clear();
+    }
+    addToInstanceIndex(instanceId, id) {
+        let ids = this.instanceIdToSubscriptionIds.get(instanceId);
+        if (!ids) {
+            ids = new Set();
+            this.instanceIdToSubscriptionIds.set(instanceId, ids);
+        }
+        ids.add(id);
+    }
+    removeFromInstanceIndex(instanceId, id) {
+        const ids = this.instanceIdToSubscriptionIds.get(instanceId);
+        if (ids) {
+            ids.delete(id);
+            if (ids.size === 0) {
+                this.instanceIdToSubscriptionIds.delete(instanceId);
+            }
+        }
+    }
+}
+exports.SubscriptionManager = SubscriptionManager;

package/cjs/build/types.d.ts

@@ -0,0 +1 @@
+export { RealtimeErrorCode, RealtimeError, type Channel, type Publisher, type Message, type MessageHandler, type SubscriptionHandler, type SubscriptionErrorHandler, type SubscriptionOptions, } from '@wix/realtime-common/types';

package/cjs/build/types.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RealtimeError = exports.RealtimeErrorCode = void 0;
+var types_1 = require("@wix/realtime-common/types");
+Object.defineProperty(exports, "RealtimeErrorCode", { enumerable: true, get: function () { return types_1.RealtimeErrorCode; } });
+Object.defineProperty(exports, "RealtimeError", { enumerable: true, get: function () { return types_1.RealtimeError; } });