@wix/realtime 1.0.33 → 1.0.35

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

@@ -1,32 +1,41 @@
 import { publish as publicPublish } from './publisher.public.js';
 import type { BuildRESTFunction, MaybeContext } from '@wix/sdk-types';
 /**
- * Publishes a message to a realtime channel.
+ * Publishes a message to a channel or resource.
  *
- * Requires a service identity (server-side only). The caller must have
- * app-level permissions to publish messages.
+ * The method publishes a message to all subscriptions on the specified channel or resource. Channels and resources are isolated, so subscribers to a channel don't receive messages published to a resource. Similarly, subscribers to a resource don't receive messages published to the parent channel.
  *
- * @example Manual client (self-hosted / explicit auth)
+ * > **Authentication**
+ * >
+ * > This method may require higher-level permissions than the caller has, based on their [identity](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities) and [roles and permissions](https://support.wix.com/en/article/roles-permissions-overview). In these cases, you can ensure the method is called with the required level of authorization by using [elevated permissions](https://dev.wix.com/docs/api-reference/articles/authentication/about-elevated-permissions).
+ *
+ * <!-- TODO: Check whether this API is relevant for headless projects. -->
+ *
+ * @example Publish a message to the specified channel
  * ```ts
  * import { publisher } from '@wix/realtime';
- * import { createClient, AppStrategy } from '@wix/sdk';
+ * import { elevate } from '@wix/sdk/context';
  *
- * const client = createClient({
- *   modules: { publisher },
- *   auth: AppStrategy({ appId, appSecret, instanceId }),
- * });
- * await client.publisher.publish({ name: 'my-channel' }, { message: 'hello' });
+ * await elevate(publisher.publish)({ name: 'my-channel' }, { message: 'hello' });
  * ```
  *
- * @example Contextual client (Wix-hosted)
+ * @example Publish a message to the specified channel: Self-hosted
  * ```ts
  * import { publisher } from '@wix/realtime';
- * import { elevate } from '@wix/sdk/context';
+ * import { createClient } from '@wix/sdk';
  *
- * await elevate(publisher.publish)({ name: 'my-channel' }, { message: 'hello' });
+ * // Import the auth strategy for the relevant access type
+ * // Import the relevant host module if needed
+ *
+ * const client = createClient({
+ *   modules: { publisher },
+ *   // Include the auth strategy and host as relevant
+ * });
+ *
+ * await client.publisher.publish({ name: 'my-channel' }, { message: 'hello' });
  * ```
  *
- * @param channel - The channel, and optionally the resource, to publish to.
- * @param payload - Message payload. Max: 10kb
+ * @param channel - Channel or resource to publish to.
+ * @param payload - Message payload. Max: 10 KB.
  */
 export declare const publish: MaybeContext<BuildRESTFunction<typeof publicPublish> & typeof publicPublish>;

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

@@ -4,32 +4,41 @@ 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.
+ * Publishes a message to a channel or resource.
  *
- * Requires a service identity (server-side only). The caller must have
- * app-level permissions to publish messages.
+ * The method publishes a message to all subscriptions on the specified channel or resource. Channels and resources are isolated, so subscribers to a channel don't receive messages published to a resource. Similarly, subscribers to a resource don't receive messages published to the parent channel.
  *
- * @example Manual client (self-hosted / explicit auth)
+ * > **Authentication**
+ * >
+ * > This method may require higher-level permissions than the caller has, based on their [identity](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities) and [roles and permissions](https://support.wix.com/en/article/roles-permissions-overview). In these cases, you can ensure the method is called with the required level of authorization by using [elevated permissions](https://dev.wix.com/docs/api-reference/articles/authentication/about-elevated-permissions).
+ *
+ * <!-- TODO: Check whether this API is relevant for headless projects. -->
+ *
+ * @example Publish a message to the specified channel
  * ```ts
  * import { publisher } from '@wix/realtime';
- * import { createClient, AppStrategy } from '@wix/sdk';
+ * import { elevate } from '@wix/sdk/context';
  *
- * const client = createClient({
- *   modules: { publisher },
- *   auth: AppStrategy({ appId, appSecret, instanceId }),
- * });
- * await client.publisher.publish({ name: 'my-channel' }, { message: 'hello' });
+ * await elevate(publisher.publish)({ name: 'my-channel' }, { message: 'hello' });
  * ```
  *
- * @example Contextual client (Wix-hosted)
+ * @example Publish a message to the specified channel: Self-hosted
  * ```ts
  * import { publisher } from '@wix/realtime';
- * import { elevate } from '@wix/sdk/context';
+ * import { createClient } from '@wix/sdk';
  *
- * await elevate(publisher.publish)({ name: 'my-channel' }, { message: 'hello' });
+ * // Import the auth strategy for the relevant access type
+ * // Import the relevant host module if needed
+ *
+ * const client = createClient({
+ *   modules: { publisher },
+ *   // Include the auth strategy and host as relevant
+ * });
+ *
+ * await client.publisher.publish({ name: 'my-channel' }, { message: 'hello' });
  * ```
  *
- * @param channel - The channel, and optionally the resource, to publish to.
- * @param payload - Message payload. Max: 10kb
+ * @param channel - Channel or resource to publish to.
+ * @param payload - Message payload. Max: 10 KB.
  */
 exports.publish = (0, rest_modules_1.createRESTModule)(publisher_public_js_1.publish);

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

@@ -1,81 +1,92 @@
 import { subscribe as publicSubscribe, unsubscribe as publicUnsubscribe } from './subscriber.public.js';
 import type { BuildRESTFunction, MaybeContext } from '@wix/sdk-types';
 /**
- * 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.
+ * Subscribes to a channel or resource.
  *
- * @example Manual client (self-hosted / explicit auth)
+ * The method attempts to establish a subscription to the specified channel or resource. While the subscription is attempted asynchronously, the method returns the subscription ID immediately.
+ *
+ * Use the `options` parameter to register handlers that run whenever the subscription succeeds or generates an error. For some errors, the subscription is re-attempted automatically. The `onSubscribed()` handler runs on every successful re-subscription.
+ *
+ * @example Subscribe to a channel
  * ```ts
  * import { subscriber } from '@wix/realtime';
- * import { createClient, AppStrategy } from '@wix/sdk';
- *
- * const client = createClient({
- *   modules: { subscriber },
- *   auth: AppStrategy({ appId, appSecret, instanceId }),
- * });
  *
- * const subscriptionId = client.subscriber.subscribe(
+ * const subscriptionId = subscriber.subscribe(
  *   { name: 'my-channel' },
  *   (message, channel) => {
  *     console.log('Received:', message.payload);
  *   },
- *   {
- *     onSubscribed: (id, isSynced) => console.log('Subscribed', id),
- *     onSubscriptionError: (error, id) => console.error('Error', error),
- *   },
  * );
  * ```
  *
- * @example Contextual client (Wix-hosted)
+ * @example Subscribe to a channel: Self-hosted
  * ```ts
+ * import { createClient } from '@wix/sdk';
  * import { subscriber } from '@wix/realtime';
  *
- * const subscriptionId = subscriber.subscribe(
+ * // Import the auth strategy for the relevant access type
+ * // Import the relevant host module if needed
+ *
+ * const client = createClient({
+ *   modules: { subscriber },
+ *   // Include the auth strategy and host as relevant
+ * });
+ *
+ * const subscriptionId = client.subscriber.subscribe(
  *   { name: 'my-channel' },
  *   (message, channel) => {
  *     console.log('Received:', message.payload);
  *   },
+ *   {
+ *     onSubscribed: (id, isSynced) => console.log('Subscribed', id),
+ *     onSubscriptionError: (error, id) => console.error('Error', error),
+ *   },
  * );
  * ```
  *
- * @param channel - The channel, and optionally the resource, to subscribe to.
- * @param messageHandler - Callback invoked whenever a message is published to the channel.
- * @param options - Optional lifecycle handlers for subscription events.
+ * @param channel - Channel, and optionally resource, to subscribe to.
+ * @param messageHandler - Callback that runs whenever a message is published to the channel.
+ * @param options - Lifecycle handlers for subscription events.
  */
 export declare const subscribe: MaybeContext<BuildRESTFunction<typeof publicSubscribe> & typeof publicSubscribe>;
 /**
- * Unsubscribe from a subscription by its ID, by channel, or both.
+ * Removes 1 or more subscriptions.
+ *
+ * You can unsubscribe in 3 ways:
+ * - By `subscriptionId`: removes a single subscription.
+ * - By `channel`: removes all subscriptions to that channel or resource.
+ * - By both: removes the specific subscription, verifying it matches the channel.
+ *
+ * When the last subscription on a connection is removed, the connection
+ * closes automatically.
+ *
+ * @example Remove the specified subscription.
+ * ```ts
+ * import { subscriber } from '@wix/realtime';
  *
- * You can unsubscribe in three ways:
- * - By `subscriptionId` — removes a single subscription.
- * - By `channel` — removes all subscriptions to that channel.
- * - By both — removes the specific subscription, verifying it matches the channel.
+ * subscriber.unsubscribe({ subscriptionId });
+ * ```
  *
- * @example Manual client (self-hosted / explicit auth)
+ * @example Remove the specified subscription: Self-hosted
  * ```ts
  * import { subscriber } from '@wix/realtime';
- * import { createClient, AppStrategy } from '@wix/sdk';
+ * import { createClient } from '@wix/sdk';
+ *
+ * // Import the auth strategy for the relevant access type
+ * // Import the relevant host module if needed
  *
  * const client = createClient({
  *   modules: { subscriber },
- *   auth: AppStrategy({ appId, appSecret, instanceId }),
+ *   // Include the auth strategy and host as relevant
  * });
  *
- * // Unsubscribe by subscription ID
+ * // Remove the specified subscription
  * client.subscriber.unsubscribe({ subscriptionId });
  *
- * // Unsubscribe from all subscriptions to a channel
+ * // Remove all subscriptions from the specified channel
  * client.subscriber.unsubscribe({ channel: { name: 'my-channel' } });
  * ```
  *
- * @example Contextual client (Wix-hosted)
- * ```ts
- * import { subscriber } from '@wix/realtime';
- *
- * subscriber.unsubscribe({ subscriptionId });
- * ```
- *
- * @param options - Identifies what to unsubscribe from — by subscription ID, channel, or both.
+ * @param options - Unsubscribe information. You must specify `channel`, `subscriptionId`, or both.
  */
 export declare const unsubscribe: MaybeContext<BuildRESTFunction<typeof publicUnsubscribe> & typeof publicUnsubscribe>;

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

@@ -4,81 +4,92 @@ 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");
 /**
- * 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.
+ * Subscribes to a channel or resource.
  *
- * @example Manual client (self-hosted / explicit auth)
+ * The method attempts to establish a subscription to the specified channel or resource. While the subscription is attempted asynchronously, the method returns the subscription ID immediately.
+ *
+ * Use the `options` parameter to register handlers that run whenever the subscription succeeds or generates an error. For some errors, the subscription is re-attempted automatically. The `onSubscribed()` handler runs on every successful re-subscription.
+ *
+ * @example Subscribe to a channel
  * ```ts
  * import { subscriber } from '@wix/realtime';
- * import { createClient, AppStrategy } from '@wix/sdk';
- *
- * const client = createClient({
- *   modules: { subscriber },
- *   auth: AppStrategy({ appId, appSecret, instanceId }),
- * });
  *
- * const subscriptionId = client.subscriber.subscribe(
+ * const subscriptionId = subscriber.subscribe(
  *   { name: 'my-channel' },
  *   (message, channel) => {
  *     console.log('Received:', message.payload);
  *   },
- *   {
- *     onSubscribed: (id, isSynced) => console.log('Subscribed', id),
- *     onSubscriptionError: (error, id) => console.error('Error', error),
- *   },
  * );
  * ```
  *
- * @example Contextual client (Wix-hosted)
+ * @example Subscribe to a channel: Self-hosted
  * ```ts
+ * import { createClient } from '@wix/sdk';
  * import { subscriber } from '@wix/realtime';
  *
- * const subscriptionId = subscriber.subscribe(
+ * // Import the auth strategy for the relevant access type
+ * // Import the relevant host module if needed
+ *
+ * const client = createClient({
+ *   modules: { subscriber },
+ *   // Include the auth strategy and host as relevant
+ * });
+ *
+ * const subscriptionId = client.subscriber.subscribe(
  *   { name: 'my-channel' },
  *   (message, channel) => {
  *     console.log('Received:', message.payload);
  *   },
+ *   {
+ *     onSubscribed: (id, isSynced) => console.log('Subscribed', id),
+ *     onSubscriptionError: (error, id) => console.error('Error', error),
+ *   },
  * );
  * ```
  *
- * @param channel - The channel, and optionally the resource, to subscribe to.
- * @param messageHandler - Callback invoked whenever a message is published to the channel.
- * @param options - Optional lifecycle handlers for subscription events.
+ * @param channel - Channel, and optionally resource, to subscribe to.
+ * @param messageHandler - Callback that runs whenever a message is published to the channel.
+ * @param options - Lifecycle handlers for subscription events.
  */
 exports.subscribe = (0, rest_modules_1.createRESTModule)(subscriber_public_js_1.subscribe);
 /**
- * Unsubscribe from a subscription by its ID, by channel, or both.
+ * Removes 1 or more subscriptions.
+ *
+ * You can unsubscribe in 3 ways:
+ * - By `subscriptionId`: removes a single subscription.
+ * - By `channel`: removes all subscriptions to that channel or resource.
+ * - By both: removes the specific subscription, verifying it matches the channel.
+ *
+ * When the last subscription on a connection is removed, the connection
+ * closes automatically.
+ *
+ * @example Remove the specified subscription.
+ * ```ts
+ * import { subscriber } from '@wix/realtime';
  *
- * You can unsubscribe in three ways:
- * - By `subscriptionId` — removes a single subscription.
- * - By `channel` — removes all subscriptions to that channel.
- * - By both — removes the specific subscription, verifying it matches the channel.
+ * subscriber.unsubscribe({ subscriptionId });
+ * ```
  *
- * @example Manual client (self-hosted / explicit auth)
+ * @example Remove the specified subscription: Self-hosted
  * ```ts
  * import { subscriber } from '@wix/realtime';
- * import { createClient, AppStrategy } from '@wix/sdk';
+ * import { createClient } from '@wix/sdk';
+ *
+ * // Import the auth strategy for the relevant access type
+ * // Import the relevant host module if needed
  *
  * const client = createClient({
  *   modules: { subscriber },
- *   auth: AppStrategy({ appId, appSecret, instanceId }),
+ *   // Include the auth strategy and host as relevant
  * });
  *
- * // Unsubscribe by subscription ID
+ * // Remove the specified subscription
  * client.subscriber.unsubscribe({ subscriptionId });
  *
- * // Unsubscribe from all subscriptions to a channel
+ * // Remove all subscriptions from the specified channel
  * client.subscriber.unsubscribe({ channel: { name: 'my-channel' } });
  * ```
  *
- * @example Contextual client (Wix-hosted)
- * ```ts
- * import { subscriber } from '@wix/realtime';
- *
- * subscriber.unsubscribe({ subscriptionId });
- * ```
- *
- * @param options - Identifies what to unsubscribe from — by subscription ID, channel, or both.
+ * @param options - Unsubscribe information. You must specify `channel`, `subscriptionId`, or both.
  */
 exports.unsubscribe = (0, rest_modules_1.createRESTModule)(subscriber_public_js_1.unsubscribe);