@videosdk.live/js-sdk/pubSub.d.ts

<h1 align="center"> <img src="https://cdn.videosdk.live/docs/images/javascript/api_ref/js_api_ref.png"/><br/> </h1>

import { RealtimeOverflow } from "./constants";

export class pubSub {
  /**
   * - This method can be used to publish a message to a specified topic within the meeting.
   *
   * @param topic The topic to which the message will be published.
   * @param message The message content to be published. This value must be a string.
   * @param options
   * @param options.persist When set to `true`, the message is stored for the entire session and is available to newly joined participants.
   * @param options.sendOnly An array of `participantId` that should receive the message. If not provided, the message is broadcast to all participants.
   * @param payload Additional data to be sent along with the message.
   *
   * @throws
   * - {@link Errors.ERROR_ACTION_PERFORMED_BEFORE_MEETING_JOINED} — called before meeting is joined
   * - {@link Errors.ERROR_MEETING_RECONNECTING} — meeting is reconnecting
   * - {@link Errors.ERROR_INVALID_PARAMETER} — `message` is not a string or `payload` is not an object
   * - {@link Errors.PUBSUB_PUBLISH_FAILED} — the publish request times out or the server returns an error
   *
   * @example
   * ```ts
   * const topic = "CHAT";
   *
   * const sendMessage = async (message) => {
   *   try {
   *     await meeting?.pubSub.publish(topic, message, { persist: true });
   *   } catch (error) {
   *     console.error("Error while sending message:", error);
   *   }
   * };
   *
   * sendMessage("Hello world!");
   * ```
   * @returns
   */
  publish(
    topic: string,
    message: string,
    options?: {
      persist?: boolean;
      sendOnly?: Array<string>;
    },
    payload?: object
  ): Promise<void>;

  /**
   * - This method can be used to subscribe to a specific topic and receive messages published under that topic.
   *
   * - The provided `listeners` exposes multiple callbacks so you can handle realtime messages, batched realtime messages, old messages, and message-drop events independently.
   *
   * @param topic The topic to subscribe to.
   * @param listeners An object of callbacks that handle incoming messages for the subscribed topic.
   * @param listeners.onMessageReceived Fires once per realtime message as it arrives.
   * @param listeners.onBatchReceived Fires with an array of realtime messages — the same set surfaced one-by-one through `onMessageReceived`, grouped for bulk handling.
   * @param listeners.onOldMessagesReceived Called with old messages when message persistence was enabled for the topic. Receives `(messages, { isLast })` — `isLast` is `true` on the final batch of old messages.
   * @param listeners.onMessageDrop Called when messages are dropped because your internet is slow or your device (CPU) can't keep up with the incoming rate. Receives an `info` object describing how many messages were dropped.
   * @param options
   * @param options.oldMessageLimit How many old messages to receive. Pass `0` to receive none. If omitted, all old messages are delivered. Default: all.
   * @param options.realtimeOverflow Behavior when your internet is slow or your device can't keep up with the incoming rate. {@link RealtimeOverflow.QUEUE} (default) queues the remaining messages so you receive them once you catch up; {@link RealtimeOverflow.DROP} drops them instead.
   * @param options.maxQueue Maximum number of message batches to queue when your internet is slow or your device can't keep up with the incoming rate. Increase this value to retain more messages and catch up after recovering. Default: `70`. Max: `200`.
   * @param options.newMessageLimit Maximum number of realtime messages to receive per 500 ms.
   *
   * @throws
   * - {@link Errors.ERROR_ACTION_PERFORMED_BEFORE_MEETING_JOINED} — called before meeting is joined
   * - {@link Errors.ERROR_MEETING_RECONNECTING} — meeting is reconnecting
   * - {@link Errors.ERROR_INVALID_PARAMETER} — any provided `listeners` callback (`onMessageReceived`, `onBatchReceived`, `onOldMessagesReceived`, `onMessageDrop`) is not a function, `maxQueue` was provided while `realtimeOverflow` is {@link RealtimeOverflow.DROP}, or `newMessageLimit` is not greater than `0` / `oldMessageLimit` is less than `0`
   * - {@link Errors.PUBSUB_SUBSCRIBE_FAILED} — the subscribe request times out or the server returns an error
   *
   * @example
   * ```ts
   * const topic = "CHAT";
   *
   * const listeners = {
   *   onMessageReceived: (message) => {
   *     console.log("realtime message:", message);
   *   },
   *   onBatchReceived: (messages) => {
   *     console.log("realtime batch:", messages);
   *   },
   *   onOldMessagesReceived: (messages, { isLast }) => {
   *     console.log("old messages:", messages, "isLast:", isLast);
   *   },
   *   onMessageDrop: (info) => {
   *     console.log("dropped messages:", info);
   *   },
   * };
   *
   * const options = {
   *   oldMessageLimit: 50,
   *   realtimeOverflow: RealtimeOverflow.QUEUE,
   *   maxQueue: 100,
   *   newMessageLimit: 20,
   * };
   *
   * const subscribe = async () => {
   *   try {
   *     await meeting.pubSub.subscribe(topic, listeners, options);
   *   } catch (err) {
   *     console.log("Error in subscribe", err);
   *   }
   * };
   * ```
   */
  subscribe(
    topic: string,
    listeners: {
      onMessageReceived?: (message: message) => void;
      onBatchReceived?: (messages: message[]) => void;
      onOldMessagesReceived?: (
        messages: message[],
        info: { isLast: boolean }
      ) => void;
      onMessageDrop?: (info: { droppedCount: number }) => void;
    },
    options?: {
      oldMessageLimit?: number;
      realtimeOverflow?: "queue" | "drop";
      maxQueue?: number;
      newMessageLimit?: number;
    }
  ): Promise<void>;

  /**
   * - This method can be used to unsubscribe from a previously subscribed topic and stop receiving messages for that topic.
   *
   * @param topic The topic from which to unsubscribe.
   * @param listeners The same `listeners` object that was provided when subscribing to the topic.
   *
   * @throws
   * - {@link Errors.ERROR_INVALID_PARAMETER} — any provided `listeners` callback (`onMessageReceived`, `onBatchReceived`, `onOldMessagesReceived`, `onMessageDrop`) is not a function
   * - {@link Errors.PUBSUB_UNSUBSCRIBE_FAILED} — the unsubscribe request times out or the server returns an error
   *
   * @example
   * ```ts
   * const listeners = {
   *   onMessageReceived: (message) => {
   *     console.log(message);
   *   },
   *   onBatchReceived: (messages) => {
   *     console.log(messages);
   *   },
   *   onOldMessagesReceived: (messages, { isLast }) => {
   *     console.log(messages, isLast);
   *   },
   *   onMessageDrop: (info) => {
   *     console.log(info);
   *   },
   * };
   *
   * try {
   *   await meeting.pubSub.unsubscribe("CHAT", listeners);
   * } catch (err) {
   *   console.log("Error in unsubscribe", err);
   * }
   * ```
   */
  unsubscribe(
    topic: string,
    listeners: {
      onMessageReceived?: (message: message) => void;
      onBatchReceived?: (messages: message[]) => void;
      onOldMessagesReceived?: (
        messages: message[],
        info: { isLast: boolean }
      ) => void;
      onMessageDrop?: (info: { droppedCount: number }) => void;
    }
  ): Promise<void>;
}

export class message {
  /**
   * Unique identifier for the message.
   */
  id: string;

  /**
   * The message content.
   */
  message: string;

  /**
   * The ID of the participant who sent the message.
   */
  senderId: string;

  /**
   * The display name of the participant who sent the message.
   */
  senderName: string;

  /**
   * Timestamp indicating when the message was published.
   */
  timestamp: string;

  /**
   * The topic under which the message was published.
   */
  topic: string;

  /**
   * Optional additional data sent along with the message.
   */
  payload?: object;
}