@stream-io/video-react-bindings 0.0.1-alpha.100

package/src/contexts/StreamCallContext.tsx

@@ -0,0 +1,43 @@
+import { createContext, PropsWithChildren, useContext } from 'react';
+import { Call } from '@stream-io/video-client';
+
+const StreamCallContext = createContext<Call | undefined>(undefined);
+
+/**
+ *
+ * We don't expose types in our docs site but we should still add doc comments
+ * @internal
+ */
+export interface StreamCallProviderProps {
+  call?: Call;
+}
+
+/**
+ *
+ * @param props
+ * @returns
+ *
+ * @category Call State
+ *
+ * @react If you're using the React SDK we recommend using the `StreamCall` component that wraps the `StreamCallProvider`. You only need to use the `StreamCallProvider` for advanced use-cases.
+ */
+export const StreamCallProvider = (
+  props: PropsWithChildren<StreamCallProviderProps>,
+) => {
+  const { call, children } = props;
+  return (
+    <StreamCallContext.Provider value={call}>
+      {children}
+    </StreamCallContext.Provider>
+  );
+};
+
+/**
+ *
+ * @returns
+ *
+ * @category Call State
+ */
+export const useCall = () => {
+  return useContext(StreamCallContext);
+};

package/src/contexts/StreamI18nContext.tsx

@@ -0,0 +1,70 @@
+import {
+  createContext,
+  PropsWithChildren,
+  useContext,
+  useEffect,
+  useState,
+} from 'react';
+import {
+  defaultTranslationFunction,
+  StreamI18n,
+  TranslationsMap,
+} from '@stream-io/i18n';
+
+type StreamI18nContextValue = {
+  t: StreamI18n['t'];
+  i18n?: StreamI18n;
+};
+
+const StreamI18nContext = createContext<StreamI18nContextValue>({
+  t: defaultTranslationFunction,
+});
+
+export type StreamI18nProviderProps = CreateI18nParams;
+
+export const StreamI18nProvider = ({
+  children,
+  ...createI18nParams
+}: PropsWithChildren<StreamI18nProviderProps>) => {
+  const { i18n, t } = useCreateI18n(createI18nParams);
+
+  return (
+    <StreamI18nContext.Provider value={{ t, i18n }}>
+      {children}
+    </StreamI18nContext.Provider>
+  );
+};
+
+type CreateI18nParams = {
+  i18nInstance?: StreamI18n;
+  language?: string;
+  translationsOverrides?: TranslationsMap;
+};
+
+export const useCreateI18n = ({
+  i18nInstance,
+  language,
+  translationsOverrides,
+}: CreateI18nParams) => {
+  const [i18n] = useState<StreamI18n>(
+    () =>
+      i18nInstance ||
+      new StreamI18n({ currentLanguage: language, translationsOverrides }),
+  );
+  const [t, setTranslationFn] = useState<StreamI18n['t']>(
+    () => defaultTranslationFunction,
+  );
+
+  useEffect(() => {
+    if (i18n.isInitialized && language && i18n?.currentLanguage !== language) {
+      i18n.changeLanguage(language);
+    } else if (!i18n.isInitialized) {
+      if (!language) i18n.changeLanguage();
+      i18n.init().then((_i18n) => setTranslationFn(() => _i18n.i18nInstance.t));
+    }
+  }, [i18n, i18nInstance, language, translationsOverrides]);
+
+  return { i18n, t };
+};
+
+export const useI18n = () => useContext(StreamI18nContext);

package/src/contexts/StreamVideoContext.tsx

@@ -0,0 +1,54 @@
+import { createContext, PropsWithChildren, useContext } from 'react';
+import { StreamVideoClient } from '@stream-io/video-client';
+import {
+  StreamI18nProvider,
+  StreamI18nProviderProps,
+} from './StreamI18nContext';
+
+const StreamVideoContext = createContext<StreamVideoClient | undefined>(
+  undefined,
+);
+
+/**
+ * Exclude types from documentaiton site, but we should still add doc comments
+ * @internal
+ */
+export type StreamVideoProps = StreamI18nProviderProps & {
+  client: StreamVideoClient;
+};
+
+/**
+ * StreamVideo is a provider component which should be used to wrap the entire application.
+ * It provides the client object to all children components and initializes the i18n instance.
+ *  @param PropsWithChildren<StreamVideoProps>
+ *  @category Client State
+ */
+export const StreamVideo = ({
+  children,
+  client,
+  i18nInstance,
+  language,
+  translationsOverrides,
+}: PropsWithChildren<StreamVideoProps>) => {
+  return (
+    <StreamVideoContext.Provider value={client}>
+      <StreamI18nProvider
+        i18nInstance={i18nInstance}
+        language={language}
+        translationsOverrides={translationsOverrides}
+      >
+        {children}
+      </StreamI18nProvider>
+    </StreamVideoContext.Provider>
+  );
+};
+
+/**
+ *
+ * @returns
+ *
+ * @category Client State
+ */
+export const useStreamVideoClient = () => {
+  return useContext(StreamVideoContext);
+};

package/src/contexts/index.ts

@@ -0,0 +1,3 @@
+export * from './StreamCallContext';
+export * from './StreamI18nContext';
+export * from './StreamVideoContext';

package/src/hooks/call.ts

@@ -0,0 +1,157 @@
+import { useObservableValue } from './helpers/useObservableValue';
+import { useCallState, useStore } from './store';
+
+/**
+ * Utility hook which provides information whether the current call is being recorded.
+ *
+ * @category Call State
+ */
+export const useIsCallRecordingInProgress = () => {
+  const metadata = useCallMetadata();
+  return !!metadata?.recording;
+};
+
+/**
+ * Utility hook which provides information whether the current call is broadcasting.
+ *
+ * @category Call State
+ */
+export const useIsCallBroadcastingInProgress = () => {
+  const metadata = useCallMetadata();
+  return !!metadata?.broadcasting;
+};
+
+/**
+ * Utility hook which provides information whether the current call is live.
+ *
+ * @category Call State
+ */
+export const useIsCallLive = () => {
+  const metadata = useCallMetadata();
+  return !metadata?.backstage;
+};
+
+/**
+ * Utility hook which provides a boolean indicating whether there is
+ * a participant in the current call which shares their screen.
+ *
+ * @category Call State
+ */
+export const useHasOngoingScreenShare = () => {
+  const { hasOngoingScreenShare$ } = useCallState();
+  return useObservableValue(hasOngoingScreenShare$);
+};
+
+/**
+ * Utility hook which provides the latest stats report of the current call.
+ *
+ * The latest stats report of the current call.
+ * When stats gathering is enabled, this observable will emit a new value
+ * at a regular (configurable) interval.
+ *
+ * Consumers of this observable can implement their own batching logic
+ * in case they want to show historical stats data.
+ *
+ * @category Call State
+ */
+export const useCallStatsReport = () => {
+  const { callStatsReport$ } = useCallState();
+  return useObservableValue(callStatsReport$);
+};
+
+/**
+ * Utility hook which provides the dominant speaker of the current call.
+ *
+ * @category Call State
+ */
+export const useDominantSpeaker = () => {
+  const { dominantSpeaker$ } = useCallState();
+  return useObservableValue(dominantSpeaker$);
+};
+
+/**
+ * Utility hook which provides a list of all notifications about created calls.
+ * In the ring call settings, these calls can be outgoing (I have called somebody)
+ * or incoming (somebody has called me).
+ *
+ * @category Client State
+ */
+export const useCalls = () => {
+  const { calls$ } = useStore();
+  return useObservableValue(calls$);
+};
+
+/**
+ * Utility hook which provides a list of all incoming ring calls (somebody calls me).
+ *
+ * @deprecated derive from useCalls()/useCall() instead.
+ * @internal
+ * @category Client State
+ */
+export const useIncomingCalls = () => {
+  const { incomingCalls$ } = useStore();
+  return useObservableValue(incomingCalls$);
+};
+
+/**
+ * Utility hook which provides a list of all outgoing ring calls (I call somebody).
+ *
+ * @deprecated derive from useCalls()/useCall() instead.
+ * @internal
+ * @category Client State
+ */
+export const useOutgoingCalls = () => {
+  const { outgoingCalls$ } = useStore();
+  return useObservableValue(outgoingCalls$);
+};
+
+/**
+ * Utility hook which provides call metadata (such as blocked users and own capabilities).
+ *
+ * @category Call State
+ */
+export const useCallMetadata = () => {
+  const { metadata$ } = useCallState();
+  return useObservableValue(metadata$);
+};
+
+/**
+ * Utility hook which provides a list of call members.
+ *
+ * @category Call State
+ */
+export const useCallMembers = () => {
+  const { members$ } = useCallState();
+  return useObservableValue(members$);
+};
+
+/**
+ * Utility hook providing the latest list of recordings performed during the active call
+ *
+ * @category Call State
+ */
+export const useCallRecordings = () => {
+  const { callRecordingList$ } = useCallState();
+  return useObservableValue(callRecordingList$);
+};
+
+/**
+ * Utility hook providing the current calling state of the call.
+ *
+ * @category Call State
+ */
+export const useCallCallingState = () => {
+  const { callingState$ } = useCallState();
+  return useObservableValue(callingState$);
+};
+
+/**
+ * Utility hook providing the actual start time of the call.
+ * Useful for calculating the call duration.
+ *
+ * @category Call State
+ */
+export const useCallStartedAt = () => {
+  const { startedAt$ } = useCallState();
+  return useObservableValue(startedAt$);
+};

package/src/hooks/client.ts

@@ -0,0 +1,77 @@
+import {
+  StreamClientOptions,
+  StreamVideoClient,
+  TokenOrProvider,
+  User,
+} from '@stream-io/video-client';
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * Exclude types from documentation site, but we should still add doc comments
+ * @internal
+ */
+export type StreamVideoClientInit = {
+  /**
+   * The Stream API key.
+   */
+  apiKey: string;
+  /**
+   * The token or token provider.
+   */
+  tokenOrProvider: TokenOrProvider;
+  /**
+   * The client options.
+   */
+  options?: StreamClientOptions;
+  /**
+   * The user to connect.
+   */
+  user: User;
+  /**
+   * Whether the user is anonymous. Defaults to `false`.
+   */
+  isAnonymous?: boolean;
+};
+
+/**
+ * Creates a new `StreamVideoClient` instance and connects the given user.
+ *
+ * @category Client State
+ */
+export const useCreateStreamVideoClient = ({
+  apiKey,
+  tokenOrProvider,
+  user,
+  options,
+  isAnonymous = false,
+}: StreamVideoClientInit) => {
+  const [client] = useState(() => new StreamVideoClient(apiKey, options));
+
+  const disconnectRef = useRef(Promise.resolve());
+  useEffect(() => {
+    const connectionPromise = disconnectRef.current.then(() => {
+      if (isAnonymous) {
+        return client
+          .connectAnonymousUser(user, tokenOrProvider)
+          .catch((err) => {
+            console.error(`Failed to establish connection`, err);
+          });
+      }
+      return client.connectUser(user, tokenOrProvider).catch((err) => {
+        console.error(`Failed to establish connection`, err);
+      });
+    });
+
+    return () => {
+      disconnectRef.current = connectionPromise
+        .then(() => client.disconnectUser())
+        .catch((err) => {
+          console.error(`Failed to disconnect`, err);
+        });
+    };
+    // we want to re-run this effect only in some special cases
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [apiKey, tokenOrProvider, client, isAnonymous, user?.id]);
+
+  return client;
+};

package/src/hooks/helpers/useObservableValue.ts

@@ -0,0 +1,21 @@
+import type { Observable } from 'rxjs';
+import { useEffect, useState } from 'react';
+import { RxUtils } from '@stream-io/video-client';
+
+/**
+ *
+ * @internal
+ */
+export const useObservableValue = <T>(observable$: Observable<T>) => {
+  const [value, setValue] = useState<T>(() =>
+    RxUtils.getCurrentValue(observable$),
+  );
+  useEffect(() => {
+    const subscription = observable$.subscribe(setValue);
+    return () => {
+      subscription.unsubscribe();
+    };
+  }, [observable$]);
+
+  return value;
+};

package/src/hooks/index.ts

@@ -0,0 +1,6 @@
+export * from './call';
+export * from './client';
+export * from './participants';
+export * from './permissions';
+export * from './store';
+export * from './user';

package/src/hooks/participants.ts

@@ -0,0 +1,79 @@
+import { useObservableValue } from './helpers/useObservableValue';
+import { useCallState } from './store';
+import type {
+  Comparator,
+  StreamVideoParticipant,
+} from '@stream-io/video-client';
+import { useMemo } from 'react';
+
+/**
+ * A hook which provides a list of all participants that have joined an active call.
+ *
+ * @category Call State
+ *
+ * @param options.sortBy - A comparator function to sort the participants by.
+ * Make sure to memoize output of the `combineComparators` function
+ * (or keep it out of component's scope if possible) before passing it down to this property.
+ */
+export const useParticipants = ({
+  sortBy,
+}: {
+  /**
+   * Make sure to memoize output of the `combineComparators` function
+   * (or keep it out of component's scope if possible) before passing it down to this property.
+   */
+  sortBy?: Comparator<StreamVideoParticipant>;
+} = {}) => {
+  const { participants$ } = useCallState();
+  const participants = useObservableValue(participants$);
+
+  return useMemo(() => {
+    if (sortBy) {
+      return [...participants].sort(sortBy);
+    }
+    return participants;
+  }, [participants, sortBy]);
+};
+
+/**
+ * A hook which provides a StreamVideoLocalParticipant object.
+ * It signals that I have joined a call.
+ *
+ * @category Call State
+ */
+export const useLocalParticipant = () => {
+  const { localParticipant$ } = useCallState();
+  return useObservableValue(localParticipant$);
+};
+
+/**
+ * A hook which provides a list of all other participants than me that have joined an active call.
+ *
+ * @category Call State
+ */
+export const useRemoteParticipants = () => {
+  const { remoteParticipants$ } = useCallState();
+  return useObservableValue(remoteParticipants$);
+};
+
+/**
+ * Returns the approximate participant count of the active call.
+ * This includes the anonymous users as well, and it is computed on the server.
+ *
+ * @category Call State
+ */
+export const useParticipantCount = () => {
+  const { participantCount$ } = useCallState();
+  return useObservableValue(participantCount$);
+};
+
+/**
+ * Returns the approximate anonymous participant count of the active call.
+ * The regular participants are not included in this count. It is computed on the server.
+ *
+ * @category Call State
+ */
+export const useAnonymousParticipantCount = () => {
+  const { anonymousParticipantCount$ } = useCallState();
+  return useObservableValue(anonymousParticipantCount$);
+};

package/src/hooks/permissions.ts

@@ -0,0 +1,37 @@
+import { OwnCapability, PermissionRequestEvent } from '@stream-io/video-client';
+import { useCallState } from './store';
+import { useObservableValue } from './helpers/useObservableValue';
+
+/**
+ * Hook that returns true if the current user has all the given permissions.
+ *
+ * @param permissions the permissions to check.
+ *
+ * @category Call State
+ */
+export const useHasPermissions = (...permissions: OwnCapability[]): boolean => {
+  const capabilities = useOwnCapabilities();
+  return permissions.every((permission) => capabilities.includes(permission));
+};
+
+/**
+ * A hook which returns the current user's own capabilities.
+ *
+ * @category Call State
+ */
+export const useOwnCapabilities = (): OwnCapability[] => {
+  const { ownCapabilities$ } = useCallState();
+  return useObservableValue(ownCapabilities$);
+};
+
+/**
+ * A hook which returns the latest call permission request.
+ *
+ * @category Call State
+ */
+export const useCallPermissionRequest = ():
+  | PermissionRequestEvent
+  | undefined => {
+  const { callPermissionRequest$ } = useCallState();
+  return useObservableValue(callPermissionRequest$);
+};

package/src/hooks/store.ts

@@ -0,0 +1,34 @@
+import { CallState } from '@stream-io/video-client';
+import { useCall, useStreamVideoClient } from '../contexts';
+
+/**
+ * Utility hook which provides access to client's state store.
+ */
+export const useStore = () => {
+  const client = useStreamVideoClient();
+  if (!client) {
+    throw new Error(
+      `StreamVideoClient isn't initialized or this hook is called outside of <StreamVideo> context.`,
+    );
+  }
+  return client.readOnlyStateStore;
+};
+
+/**
+ * Utility hook which provides the current call's state.
+ *
+ * @category Call State
+ */
+export const useCallState = () => {
+  const call = useCall();
+  // return an empty and unlinked CallState object if there is no call in the provider
+  // this ensures that the hooks always return a value and many null checks can be avoided
+  if (!call) {
+    const message =
+      'You are using useCallState() outside a Call context. ' +
+      'Please wrap your component in <StreamCallProvider /> and provide a non-null "call" instance.';
+    console.warn(message);
+    return new CallState();
+  }
+  return call.state;
+};

package/src/hooks/user.ts

@@ -0,0 +1,13 @@
+import { useStore } from './store';
+import { useObservableValue } from './helpers/useObservableValue';
+
+/**
+ *
+ * @returns
+ *
+ * @category Client State
+ */
+export const useConnectedUser = () => {
+  const { connectedUser$ } = useStore();
+  return useObservableValue(connectedUser$);
+};

package/src/wrappers/Restricted.tsx

@@ -0,0 +1,40 @@
+import { OwnCapability } from '@stream-io/video-client';
+
+import { PropsWithChildren } from 'react';
+import { useCall } from '../contexts';
+import { useOwnCapabilities } from '../hooks';
+
+type RestrictedProps = PropsWithChildren<{
+  /**
+   * OwnCapabilities of the participant - grants they have available
+   */
+  availableGrants?: OwnCapability[];
+  /**
+   * Required grants for the component to be able to render supplied children elements
+   */
+  requiredGrants: OwnCapability[];
+  /**
+   * Require all grants specified in `requiredGrants` to be available in the `availableGrants`,
+   * component by default requires only one grant to appear in both arrays to render its children
+   */
+  requireAll?: boolean;
+}>;
+
+export const Restricted = ({
+  availableGrants: availableGrantsFromProps,
+  requiredGrants,
+  requireAll = true,
+  children,
+}: RestrictedProps) => {
+  const call = useCall();
+  const ownCapabilities = useOwnCapabilities();
+  const availableGrants = availableGrantsFromProps ?? ownCapabilities;
+  const hasPermissions = requiredGrants[requireAll ? 'every' : 'some'](
+    (capability) => availableGrants.includes(capability),
+  );
+  const canRequest = requiredGrants.some(
+    (capability) => !!call && call.permissionsContext.canRequest(capability),
+  );
+  if (hasPermissions || canRequest) return <>{children}</>;
+  return null;
+};

package/src/wrappers/index.ts

@@ -0,0 +1 @@
+export * from './Restricted';