@100mslive/react-native-hms 2.0.0-alpha.0 → 2.0.0-alpha.1

package/src/classes/HMSVideoTrackSettings.ts

@@ -1,11 +1,33 @@
+import type { ImageURISource, ImageRequireSource } from 'react-native';
 import type { HMSSimulcastLayerSettings } from './HMSSimulcastLayerSettings';
 import type { HMSCameraFacing } from './HMSCameraFacing';
 import type { HMSTrackSettingsInitState } from './HMSTrackSettingsInitState';
 
+export declare class HMSVirtualBackgroundPlugin {
+  static NAME: string;
+  constructor();
+  enable(): Promise<boolean>;
+  disable(): Promise<boolean>;
+  setBlur(blurRadius: number): Promise<boolean>;
+  setBackground(
+    backgroundImage: ImageURISource | ImageRequireSource
+  ): Promise<boolean>;
+}
+
 /**
- * Customize local peer's Video track settings before Joining the Room.
+ * Represents the settings for a video track in a HMS (100ms) application.
+ *
+ * This class encapsulates the configurations for video tracks that can be used
+ * in a HMS session.
+ *
+ * @property {HMSSimulcastLayerSettings[]} simulcastSettings - Optional simulcast settings.
+ * @property {HMSTrackSettingsInitState} initialState - Optional initial state for the track.
+ * @property {HMSCameraFacing} cameraFacing - Optional camera facing for the track.
+ * @property {boolean} forceSoftwareDecoder - Optional flag to force software decoder.
+ * @property {boolean} disableAutoResize - Optional flag to disable auto resize.
+ * @property {HMSVirtualBackgroundPlugin} videoPlugin - Optional video plugin settings.
  *
- * Checkout Track Settings docs for more details {@link https://www.100ms.live/docs/react-native/v2/how-to-guides/interact-with-room/track/track-settings}
+ * @see https://www.100ms.live/docs/react-native/v2/how-to-guides/interact-with-room/track/track-settings
  */
 export class HMSVideoTrackSettings {
   readonly simulcastSettings?: HMSSimulcastLayerSettings[];
@@ -13,6 +35,7 @@ export class HMSVideoTrackSettings {
   cameraFacing?: HMSCameraFacing;
   forceSoftwareDecoder?: boolean; // android only
   disableAutoResize?: boolean; // android only
+  videoPlugin?: HMSVirtualBackgroundPlugin;
 
   constructor(params: {
     simulcastSettings?: HMSSimulcastLayerSettings[];
@@ -20,11 +43,13 @@ export class HMSVideoTrackSettings {
     cameraFacing?: HMSCameraFacing;
     forceSoftwareDecoder?: boolean;
     disableAutoResize?: boolean;
+    videoPlugin?: HMSVirtualBackgroundPlugin;
   }) {
     this.simulcastSettings = params.simulcastSettings;
     this.initialState = params.initialState;
     this.cameraFacing = params.cameraFacing;
     this.forceSoftwareDecoder = params.forceSoftwareDecoder;
     this.disableAutoResize = params.disableAutoResize;
+    this.videoPlugin = params.videoPlugin;
   }
 }

package/src/classes/HmsView.tsx

@@ -1,34 +1,38 @@
-import React, { useState, useImperativeHandle, useRef } from 'react';
-import {
-  findNodeHandle,
-  requireNativeComponent,
-  StyleSheet,
-  UIManager,
-  Platform,
-} from 'react-native';
-import type { ViewStyle } from 'react-native';
+import React, {
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { StyleSheet, Platform } from 'react-native';
+import type { NativeSyntheticEvent, ViewStyle } from 'react-native';
+import HmsView, { Commands } from '../specs/HMSViewNativeComponent';
 import { HMSConstants } from './HMSConstants';
 import { HMSVideoViewMode } from './HMSVideoViewMode';
+import { setHmsViewsResolutionsState } from '../hooks/hmsviews';
 
-interface HmsViewProps {
-  data: {
-    trackId: string;
-    id: string;
-    mirror: boolean;
-    scaleType: HMSVideoViewMode;
-  };
-  autoSimulcast: boolean;
-  setZOrderMediaOverlay: boolean;
-  scaleType: HMSVideoViewMode;
-  style: ViewStyle;
-  onChange: Function;
-  onDataReturned: Function;
-}
-
-const HmsView = requireNativeComponent<HmsViewProps>('HMSView');
-let _nextRequestId = 1;
-let _requestMap = new Map();
+type CapturePromiseMethods = {
+  resolve: (value: unknown) => void;
+  reject: (reason?: unknown) => void;
+};
 
+/**
+ * Defines the properties for the `HmsViewComponent`.
+ *
+ * This interface outlines the props that can be passed to the `HmsViewComponent` to configure its behavior and appearance.
+ *
+ * @interface HmsComponentProps
+ * @property {string} trackId - The unique identifier for the track to be displayed.
+ * @property {ViewStyle} [style] - Optional. Custom styles to apply to the view.
+ * @property {boolean} [mirror] - Optional. If true, the video will be mirrored. This is commonly used for local video tracks.
+ * @property {boolean} [autoSimulcast] - Optional. Enables automatic simulcast layer switching based on network conditions, if supported.
+ * @property {HMSVideoViewMode} [scaleType] - Optional. Determines how the video fits within the bounds of the view (e.g., aspect fill, aspect fit).
+ * @property {boolean} [setZOrderMediaOverlay] - Optional. When true, the video view will be rendered above the regular view hierarchy.
+ * @property {string} id - The identifier for the `HmsViewComponent` instance.
+ *
+ * @see {https://www.100ms.live/docs/react-native/v2/how-to-guides/set-up-video-conferencing/render-video/overview}
+ */
 export interface HmsComponentProps {
   trackId: string;
   style?: ViewStyle;
@@ -53,18 +57,44 @@ export const HmsViewComponent = React.forwardRef<any, HmsComponentProps>(
 
     const hmsViewRef: any = useRef();
     const [applyStyles_ANDROID, setApplyStyles_ANDROID] = useState(false);
-    const data = {
-      trackId,
-      id,
-      mirror,
-      scaleType,
-    };
+    // Memoized so the object reference is stable across renders unless one
+    // of the inputs actually changes. Fabric diffs view props by reference
+    // before doing a deep compare — a fresh `{...}` on every render would
+    // trigger redundant native prop updates.
+    const data = useMemo(
+      () => ({ trackId, id, mirror, scaleType }),
+      [trackId, id, mirror, scaleType]
+    );
+
+    // Per-instance request/response state for the `capture` imperative.
+    // Each `<HmsView />` gets its own counter + pending-promise map so:
+    //   - requestIds can't collide across multiple HmsView instances
+    //   - pending promises are scoped to this view and cleaned up when
+    //     it unmounts (see the useEffect below)
+    const nextRequestId = useRef(1);
+    const requestMap = useMemo(
+      () => new Map<number, CapturePromiseMethods>(),
+      []
+    );
 
     /**
      * This method is passed to `onChange` prop of `HmsView` Native Component.
      * It is invoked when `HmsView` emits 'topChange' event.
      */
-    const onChange = () => setApplyStyles_ANDROID(true);
+    const onChange = ({
+      nativeEvent,
+    }: NativeSyntheticEvent<{
+      data: { height: number; width: number };
+      event: 'ON_RESOLUTION_CHANGE_EVENT';
+    }>) => {
+      const { event, data } = nativeEvent;
+
+      setApplyStyles_ANDROID(true);
+
+      if (event === 'ON_RESOLUTION_CHANGE_EVENT') {
+        setHmsViewsResolutionsState(trackId, data);
+      }
+    };
 
     /**
      * This method is passed to `onDataReturned` prop of `HmsView` Native Component.
@@ -73,38 +103,30 @@ export const HmsViewComponent = React.forwardRef<any, HmsComponentProps>(
     const _onDataReturned = (event: {
       nativeEvent: { requestId: any; result: any; error: any };
     }) => {
-      // We grab the relevant data out of our event.
-      let { requestId, result, error } = event.nativeEvent;
-      // Then we get the promise we saved earlier for the given request ID.
-      let promise = _requestMap.get(requestId);
+      const { requestId, result, error } = event.nativeEvent;
+      const promise = requestMap.get(requestId);
+      if (!promise) {
+        // No pending request — typically a late event after unmount/cleanup
+        // rejected it, or a stale requestId from a previous mount.
+        return;
+      }
       if (result) {
-        // If it was successful, we resolve the promise.
         promise.resolve(result);
       } else {
-        // Otherwise, we reject it.
         promise.reject(error);
       }
-      // Finally, we clean up our request map.
-      _requestMap.delete(requestId);
+      requestMap.delete(requestId);
     };
 
     const capture = async () => {
-      const viewManagerConfig = UIManager.getViewManagerConfig('HMSView');
-
-      let requestId = _nextRequestId++;
-      let requestMap = _requestMap;
-
-      // We create a promise here that will be resolved once `_onRequestDone` is
-      // called.
-      let promise = new Promise(function (resolve, reject) {
+      const requestId = nextRequestId.current++;
+      const promise = new Promise((resolve, reject) => {
         requestMap.set(requestId, { resolve, reject });
       });
 
-      UIManager.dispatchViewManagerCommand(
-        findNodeHandle(hmsViewRef.current),
-        viewManagerConfig.Commands.capture,
-        [requestId]
-      );
+      if (hmsViewRef.current) {
+        Commands.capture(hmsViewRef.current, requestId);
+      }
       return promise;
     };
 
@@ -114,10 +136,23 @@ export const HmsViewComponent = React.forwardRef<any, HmsComponentProps>(
       };
     });
 
+    // Reject any in-flight capture promises on unmount. Under bridgeless
+    // mode the native side may not be able to deliver the captureFrame
+    // event back (event dispatcher returns null when the React tag is
+    // gone), which would leave promises hanging in the map forever.
+    useEffect(() => {
+      return () => {
+        requestMap.forEach(({ reject }) => {
+          reject(new Error('HmsView unmounted before capture completed'));
+        });
+        requestMap.clear();
+      };
+    }, [requestMap]);
+
     return (
       <HmsView
         ref={hmsViewRef}
-        onChange={onChange}
+        onResolutionChange={onChange as any}
         data={data}
         style={
           Platform.OS === 'android' ? (applyStyles_ANDROID ? style : {}) : style
@@ -125,7 +160,7 @@ export const HmsViewComponent = React.forwardRef<any, HmsComponentProps>(
         autoSimulcast={autoSimulcast}
         scaleType={scaleType}
         setZOrderMediaOverlay={setZOrderMediaOverlay}
-        onDataReturned={_onDataReturned}
+        onDataReturned={_onDataReturned as any}
       />
     );
   }

package/src/classes/polls/DecodedPollLeaderboardResponse.ts

@@ -0,0 +1,43 @@
+import type { HMSPollLeaderboardEntry } from './HMSPollLeaderboardEntry';
+import type { HMSPollLeaderboardSummary } from './HMSPollLeaderboardSummary';
+import type { PollLeaderboardResponse } from './PollLeaderboardResponse';
+
+type NumberString = string;
+
+export interface DecodedPollLeaderboardResponse
+  extends Pick<PollLeaderboardResponse, 'hasNext'> {
+  entries?: DecodedHMSPollLeaderboardEntry[];
+  summary?: DecodedHMSPollLeaderboardSummary;
+}
+
+export interface DecodedHMSPollLeaderboardEntry
+  extends Pick<HMSPollLeaderboardEntry, 'peer'> {
+  /**
+   * convert this value to number
+   */
+  duration?: NumberString | number;
+  /**
+   * convert this value to number
+   */
+  totalResponses?: NumberString | number;
+  /**
+   * convert this value to number
+   */
+  correctResponses?: NumberString | number;
+  /**
+   * convert this value to number
+   */
+  position?: NumberString | number;
+  /**
+   * convert this value to number
+   */
+  score?: NumberString | number;
+}
+
+export interface DecodedHMSPollLeaderboardSummary
+  extends Omit<HMSPollLeaderboardSummary, 'averageTime'> {
+  /**
+   * convert this value to number
+   */
+  averageTime?: NumberString | number;
+}

package/src/classes/polls/HMSPoll.ts

@@ -0,0 +1,99 @@
+import type { HMSPollState } from './HMSPollState';
+import type { HMSPollQuestion } from './HMSPollQuestion';
+import type { HMSPollResult } from './HMSPollResult';
+import type { HMSRole } from '../HMSRole';
+import type { HMSPollUserTrackingMode } from './HMSPollUserTrackingMode';
+import type { HMSPollType } from './HMSPollType';
+import type { HMSPeer } from '../HMSPeer';
+
+export interface HMSPoll {
+  /**
+   The unique identifier of the poll.
+   */
+  pollId: string;
+
+  /**
+   The title of the poll.
+   */
+  title: string;
+
+  /**
+   The duration of the poll in seconds.
+   */
+  duration?: number;
+
+  /**
+   A flag indicating whether the poll is anonymous or not.
+   */
+  anonymous?: boolean;
+
+  /**
+   The tracking mode for user participation in the poll.
+   */
+  mode?: HMSPollUserTrackingMode;
+
+  /**
+   The roles that can vote in the poll.
+   */
+  rolesThatCanVote?: HMSRole[];
+
+  /**
+   The roles that can view the poll responses.
+   */
+  rolesThatCanViewResponses?: HMSRole[];
+
+  /**
+   The peer who started the poll.
+   */
+  startedBy?: HMSPeer;
+
+  /**
+   The peer who stopped the poll.
+   */
+  stoppedBy?: HMSPeer;
+
+  /**
+   The peer who created the poll.
+   */
+  createdBy?: HMSPeer;
+
+  /**
+   The date and time when the poll was started.
+   */
+  startedAt?: Date;
+
+  /**
+   The date and time when the poll was stopped.
+   */
+  stoppedAt?: Date;
+
+  /**
+   The type of the poll.
+   */
+  type: HMSPollType;
+
+  /**
+   The current state of the poll.
+   */
+  state?: HMSPollState;
+
+  /**
+   The list of questions in the poll.
+   */
+  questions?: HMSPollQuestion[];
+
+  /**
+   The result of the poll.
+   */
+  result?: HMSPollResult;
+
+  // /**
+  //  The visiblity of the poll. (Not available on iOS)
+  //  */
+  // visibility?: boolean;
+
+  // /**
+  //  * Is poll locked currently? (Not available on iOS)
+  //  */
+  // locked?: boolean;
+}

package/src/classes/polls/HMSPollCategory.ts

@@ -0,0 +1,11 @@
+export enum HMSPollCategory {
+  /**
+   The poll is a standard poll.
+   */
+  poll,
+
+  /**
+   The poll is a quiz.
+   */
+  quiz,
+}

package/src/classes/polls/HMSPollCreateParams.ts

@@ -0,0 +1,19 @@
+import type { HMSPoll } from './HMSPoll';
+import type { HMSPollQuestionCreateParams } from './HMSPollQuestionCreateParams';
+
+export interface HMSPollCreateParams
+  extends Pick<
+    HMSPoll,
+    | 'title'
+    | 'type'
+    | 'duration'
+    | 'anonymous'
+    // | 'visibility'
+    // | 'locked'
+    | 'mode'
+    | 'rolesThatCanVote'
+    | 'rolesThatCanViewResponses'
+  > {
+  pollId?: HMSPoll['pollId'];
+  questions?: HMSPollQuestionCreateParams[];
+}

package/src/classes/polls/HMSPollLeaderboardEntry.ts

@@ -0,0 +1,10 @@
+import type { HMSPollResponsePeerInfo } from './HMSPollResponsePeerInfo';
+
+export interface HMSPollLeaderboardEntry {
+  duration?: number;
+  totalResponses?: number;
+  correctResponses?: number;
+  position?: number;
+  score?: number;
+  peer?: HMSPollResponsePeerInfo;
+}

package/src/classes/polls/HMSPollLeaderboardSummary.ts

@@ -0,0 +1,7 @@
+export interface HMSPollLeaderboardSummary {
+  averageScore?: number;
+  averageTime?: number;
+  respondedCorrectlyPeersCount?: number;
+  respondedPeersCount?: number;
+  totalPeersCount?: number;
+}

package/src/classes/polls/HMSPollQuestion.ts

@@ -0,0 +1,92 @@
+import type { HMSPollQuestionAnswer } from './HMSPollQuestionAnswer';
+import type { HMSPollQuestionOption } from './HMSPollQuestionOption';
+import type { HMSPollQuestionResponse } from './HMSPollQuestionResponse';
+import type { HMSPollQuestionType } from './HMSPollQuestionType';
+
+/**
+ Represents a question in a poll.
+ */
+export interface HMSPollQuestion {
+  /**
+   The index of the question within the poll.
+   */
+  index: number;
+
+  /**
+   The text of the question.
+   */
+  text: string;
+
+  /**
+   A flag indicating whether the question is skippable or not.
+   */
+  skippable: boolean;
+
+  /**
+   The duration hint of the question in seconds. Can be used for setting a timeframe withing which a question can be responded to. Not enforced by the server.
+   */
+  duration: number;
+
+  /**
+   A flag indicating whether the question can be answered only once.
+   */
+  once: boolean;
+
+  /**
+   The weight of the question in scoring.
+   */
+  weight: number;
+
+  /**
+   The minimum length of the answer (if applicable).
+   */
+  answerMinLen?: number;
+
+  /**
+   The maximum length of the answer (if applicable).
+   */
+  answerMaxLen?: number;
+
+  /**
+   The type of the question.
+   */
+  type: HMSPollQuestionType;
+
+  /**
+   The list of options for the question (if applicable).
+   */
+  options?: HMSPollQuestionOption[];
+
+  /**
+   The answer for the question (if it is a quiz).
+   */
+  answer?: HMSPollQuestionAnswer;
+
+  /**
+   The list of responses for the question.
+   */
+  responses?: HMSPollQuestionResponse[];
+
+  /**
+   The responses provided by the current user for the question.
+   */
+  myResponses: HMSPollQuestionResponse[];
+}
+
+// Web Inteface -
+// export interface HMSPollQuestion {
+//   index: number;
+//   text: string;
+//   type: HMSPollQuestionType;
+//   skippable?: boolean;
+//   duration?: number;
+//   once?: boolean;
+//   weight?: number;
+//   negative?: boolean;
+//   answerMinLen?: number;
+//   answerMaxLen?: number;
+//   options?: HMSPollQuestionOption[];
+//   answer?: HMSPollQuestionAnswer;
+//   responses?: HMSPollQuestionResponse[];
+//   result?: HMSPollQuestionResult;
+// }

package/src/classes/polls/HMSPollQuestionAnswer.ts

@@ -0,0 +1,29 @@
+/**
+ Provides the correct answer for a quiz question to check users' responses against.
+ */
+export interface HMSPollQuestionAnswer {
+  /**
+   A flag indicating whether the answer should be hidden or not.
+   */
+  hidden: boolean;
+
+  /**
+   The index of the selected option (in case of single choice question).
+   */
+  option?: number;
+
+  /**
+   The list of indexes of selected options (in case of multiple choice question).
+   */
+  options?: number[];
+}
+
+// Web Inteface -
+// export interface HMSPollQuestionAnswer {
+//   hidden: boolean; // if true answer will not be returned when poll is running
+//   option?: number; // option index for correct answer, in case of single choice
+//   options?: number[]; // list of options that shoould be in answer
+//   text?: string; // answer text for answer.
+//   case?: boolean; // if false case is ignored when comparing.
+//   trim?: boolean; // if true, empty space is trimmer from start and end of asnwer.
+// }

package/src/classes/polls/HMSPollQuestionCreateParams.ts

@@ -0,0 +1,36 @@
+import type { HMSPollQuestion } from './HMSPollQuestion';
+import type { HMSPollQuestionOptionCreateParams } from './HMSPollQuestionOptionCreateParams';
+import type { HMSPollQuestionQuizOptionCreateParams } from './HMSPollQuestionQuizOptionCreateParams';
+
+export interface HMSPollQuestionCreateParams
+  extends Pick<
+    HMSPollQuestion,
+    'text' | 'skippable' | 'type' | 'answerMinLen' | 'answerMaxLen'
+  > {
+  /**
+   * A flag indicating whether the question can be answered only once.
+   */
+  once?: HMSPollQuestion['once'];
+
+  /**
+   * The duration hint of the question in seconds. Can be used for setting a timeframe withing which a question can be responded to. Not enforced by the server.
+   */
+  duration?: HMSPollQuestion['duration'];
+
+  /**
+   * The index of the question within the poll.
+   */
+  index?: HMSPollQuestion['index'];
+
+  /**
+   * The options of the question.
+   */
+  options?:
+    | HMSPollQuestionOptionCreateParams[]
+    | HMSPollQuestionQuizOptionCreateParams[];
+
+  /**
+   * The weight of the question in scoring.
+   */
+  weight?: number;
+}

package/src/classes/polls/HMSPollQuestionOption.ts

@@ -0,0 +1,24 @@
+/**
+ Represents an option for a poll question.
+ */
+export interface HMSPollQuestionOption {
+  /**
+   The index of the option within the question.
+   */
+  index: number;
+
+  /**
+   The text of the option.
+   */
+  text: string;
+
+  /**
+   The weight of the option in scoring.
+   */
+  weight: number; // (optional on web)
+
+  /**
+   The count of votes received for the option. `0` is the default value.
+   */
+  voteCount: number; // (optional on web)
+}

package/src/classes/polls/HMSPollQuestionOptionCreateParams.ts

@@ -0,0 +1,8 @@
+import type { HMSPollQuestionOption } from './HMSPollQuestionOption';
+
+export interface HMSPollQuestionOptionCreateParams
+  extends Pick<
+    HMSPollQuestionOption,
+    'text'
+    // | 'weight' // `weight` field is not required as of now
+  > {}

package/src/classes/polls/HMSPollQuestionQuizOptionCreateParams.ts

@@ -0,0 +1,6 @@
+import type { HMSPollQuestionOptionCreateParams } from './HMSPollQuestionOptionCreateParams';
+
+export interface HMSPollQuestionQuizOptionCreateParams
+  extends HMSPollQuestionOptionCreateParams {
+  isCorrectAnswer: boolean;
+}