@stream-io/react-native-callingx 0.1.0-beta.0

package/src/types.ts

@@ -0,0 +1,323 @@
+import type { EventListener } from './EventManager';
+import type { ManagableTask } from './utils/headlessTask';
+import type { PermissionsResult } from './utils/permissions';
+
+export interface ICallingxModule {
+  get isNotificationsAllowed(): boolean;
+  get isOngoingCallsEnabled(): boolean;
+  get isSetup(): boolean;
+
+  /**
+   * Setup the module. This method must be called before any other method.
+   * For iOS, the module will setup CallKit parameters.
+   *    See: {@link InternalIOSOptions}
+   * For Android, the module will create notification channels.
+   *    See: {@link InternalAndroidOptions}
+   * @param options - The options to setup the callingx module. See {@link CallingExpOptions}
+   */
+  setup(options: CallingExpOptions): void;
+  /**
+   * Set whether to reject calls when the user is busy.
+   * The value is used in iOS native module to prevent calls registration in CallKit when the user is busy.
+   * @param shouldReject - Whether to reject calls when the user is busy.
+   */
+  setShouldRejectCallWhenBusy(shouldReject: boolean): void;
+  /**
+   * Check the permissions.
+   * @returns The permissions result.
+   */
+  checkPermissions(): Promise<PermissionsResult>;
+
+  requestPermissions(): Promise<PermissionsResult>;
+  /**
+   * Get the initial events. This method is used to get the initial events from the app launch.
+   * The events are queued and can be retrieved after the module is setup.
+   * IMPORTANT: After the events are retrieved, new events will be sent to the event listeners.
+   * @returns The initial events.
+   */
+  getInitialEvents(): EventData[];
+
+  /**
+   * Get the initial voip events. This method is used to get the initial voip events from the app launch.
+   * The events are queued and can be retrieved after the module is setup.
+   * IMPORTANT: After the events are retrieved, new events will be sent to the event listeners.
+   * @returns The initial voip events.
+   */
+  getInitialVoipEvents(): VoipEventData[];
+
+  displayIncomingCall(
+    callId: string,
+    phoneNumber: string,
+    callerName: string,
+    hasVideo: boolean,
+  ): Promise<void>;
+  answerIncomingCall(callId: string): Promise<void>;
+
+  startCall(
+    callId: string,
+    phoneNumber: string,
+    callerName: string,
+    hasVideo: boolean,
+  ): Promise<void>;
+
+  /**
+   * Set the current call active. This method is used to set the current call active.
+   * This method is used to activate the call that was registered with {@link startCall}.
+   * @param callId - The call id.
+   * @returns The promise.
+   */
+  setCurrentCallActive(callId: string): Promise<void>;
+
+  updateDisplay(
+    callId: string,
+    phoneNumber: string,
+    callerName: string,
+  ): Promise<void>;
+
+  /**
+   * Check if the call is registered in CallKit/Telecom.
+   * @param callId - The call id.
+   * @returns The boolean value.
+   */
+  isCallRegistered(callId: string): boolean;
+
+  /**
+   * Check if there is a registered call.
+   * @returns The boolean value.
+   */
+  hasRegisteredCall(): boolean;
+
+  /**
+   * End the call with a reason. This method is used to end the call with a reason.
+   * Note: In general invoking this method will trigger the call end event.
+   * But, in case of iOS, when the call is ended with the reason 'local', the call end event will not be triggered.
+   * @param callId - The call id.
+   * @param reason - The reason.
+   * @returns The promise.
+   */
+  endCallWithReason(callId: string, reason: EndCallReason): Promise<void>;
+
+  setMutedCall(callId: string, isMuted: boolean): Promise<void>;
+
+  setOnHoldCall(callId: string, isOnHold: boolean): Promise<void>;
+
+  /**
+   * Register a background task provider. This method only registers the task and does not start it.
+   * The task will be automatically started when the service starts (via displayIncomingCall or startCall)
+   * if it has been registered.
+   * @param taskProvider - The task provider function that will be executed when the background task starts.
+   */
+  registerBackgroundTask(taskProvider: ManagableTask): void;
+
+  /**
+   * Start the background task. This method will only start the task if:
+   * 1. A background task has been registered via registerBackgroundTask
+   * 2. The service is currently started
+   * @param taskProvider - The task provider function. If not provided, uses the previously registered task.
+   * @returns Promise that resolves when the task is started, or rejects if conditions are not met.
+   */
+  startBackgroundTask(taskProvider?: ManagableTask): Promise<void>;
+
+  stopBackgroundTask(taskName: string): Promise<void>;
+
+  registerVoipToken(): void;
+
+  /**
+   * Single entry point for adding event listeners.
+   * Automatically routes to the appropriate manager based on event type.
+   *
+   * @param eventName - The event name (EventName or VoipEventName)
+   * @param callback - The callback function that receives the event parameters
+   * @returns An object with a remove method to unsubscribe from the event
+   */
+  addEventListener<T extends EventName | VoipEventName>(
+    eventName: T,
+    callback: EventListener<
+      T extends EventName
+        ? EventParams[T]
+        : T extends VoipEventName
+          ? VoipEventParams[T]
+          : never
+    >,
+  ): { remove: () => void };
+
+  log(message: string, level: 'debug' | 'info' | 'warn' | 'error'): void;
+}
+
+export type InternalIOSOptions = {
+  supportsVideo?: boolean;
+  maximumCallsPerCallGroup?: number;
+  maximumCallGroups?: number;
+  handleType?: 'generic' | 'number' | 'phone' | 'email';
+  /**
+   * Sound to play when an incoming call is received. Must be a valid sound resource name in the project.
+   * @default '' (no sound)
+   */
+  sound?: string;
+  /**
+   * Image to display when an incoming call is received. Must be a valid image resource name in the project.
+   * @default '' (no image)
+   */
+  imageName?: string;
+  /**
+   * Enable calls history. When enabled, the call will be added to the calls history.
+   * @default false
+   */
+  callsHistory?: boolean;
+  /**
+   * Timeout to display an incoming call. When the call is displayed for more than the timeout, the call will be rejected.
+   * @default 60000 (1 minute)
+   */
+  displayCallTimeout?: number;
+};
+type iOSOptions = Omit<
+  InternalIOSOptions,
+  | 'maximumCallsPerCallGroup'
+  | 'maximumCallGroups'
+  | 'handleType'
+  | 'setupAudioSession'
+>;
+
+export type InternalAndroidOptions = {
+  /**
+   * Incoming channel configuration.
+   * @default { id: 'incoming_calls_channel', name: 'Incoming calls', sound: '', vibration: false }
+   */
+  incomingChannel?: {
+    id?: string;
+    name?: string;
+    sound?: string;
+    vibration?: boolean;
+  };
+  /**
+   * Ongoing channel configuration.
+   * @default { id: 'ongoing_calls_channel', name: 'Ongoing calls' }
+   */
+  ongoingChannel?: {
+    id?: string;
+    name?: string;
+  };
+};
+type AndroidOptions = InternalAndroidOptions & NotificationTransformers;
+
+export type TextTransformer = (text: string, incoming: boolean) => string;
+export type NotificationTransformers = {
+  titleTransformer?: TextTransformer;
+  subtitleTransformer?: TextTransformer;
+};
+
+export type CallingExpOptions = {
+  ios?: iOSOptions;
+  android?: AndroidOptions;
+  /**
+   * Whether to enable ongoing calls.
+   * @default false
+   */
+  enableOngoingCalls?: boolean;
+  /**
+   * Whether to reject calls when the user is busy.
+   * @default false
+   */
+  shouldRejectCallWhenBusy?: boolean;
+};
+
+export type InfoDisplayOptions = {
+  displayTitle?: string;
+  displaySubtitle?: string;
+};
+
+export type EventData = {
+  eventName: EventName;
+  params: EventParams[EventName];
+};
+
+export type VoipEventData = {
+  eventName: VoipEventName;
+  params: VoipEventParams[VoipEventName];
+};
+
+export type EventName =
+  | 'answerCall'
+  | 'endCall'
+  | 'didDisplayIncomingCall'
+  | 'didToggleHoldCallAction'
+  | 'didChangeAudioRoute'
+  | 'didReceiveStartCallAction'
+  | 'didPerformSetMutedCallAction'
+  | 'didActivateAudioSession'
+  | 'didDeactivateAudioSession';
+
+export type EventParams = {
+  answerCall: {
+    callId: string;
+    source: 'app' | 'sys';
+  };
+  endCall: {
+    callId: string;
+    cause: string;
+    source: 'app' | 'sys';
+  };
+  didDisplayIncomingCall: {
+    callId: string;
+  };
+  didToggleHoldCallAction: {
+    callId: string;
+    hold: boolean;
+  };
+  didPerformSetMutedCallAction: {
+    callId: string;
+    muted: boolean;
+  };
+  didChangeAudioRoute: {
+    callId: string;
+    output: string;
+  };
+  didReceiveStartCallAction: {
+    callId: string;
+  };
+  didActivateAudioSession: undefined;
+  didDeactivateAudioSession: undefined;
+};
+
+export type VoipEventName =
+  | 'voipNotificationsRegistered'
+  | 'voipNotificationReceived';
+
+export type VoipEventParams = {
+  voipNotificationsRegistered: {
+    token: string;
+  };
+  voipNotificationReceived: {
+    aps: {
+      'thread-id': string;
+      'mutable-content': number;
+      alert: {
+        title: string;
+      };
+      category: string;
+      sound: string;
+    };
+    stream: {
+      sender: string;
+      created_by_id: string;
+      body: string;
+      title: string;
+      call_display_name: string;
+      created_by_display_name: string;
+      version: string;
+      type: string;
+      receiver_id: string;
+      call_cid: string;
+      video: string;
+    };
+  };
+};
+
+export type EndCallReason =
+  | 'local' // when call is ended by the user
+  | 'remote'
+  | 'rejected'
+  | 'busy'
+  | 'answeredElsewhere'
+  | 'missed'
+  | 'error';

package/src/utils/constants.ts

@@ -0,0 +1,55 @@
+import type {
+  InternalAndroidOptions,
+  InternalIOSOptions,
+  EndCallReason,
+  TextTransformer,
+} from '../types';
+import type { DeepRequired } from './types';
+
+export const defaultTextTransformer: TextTransformer = (text: string) => text;
+
+export const defaultiOSOptions: Required<InternalIOSOptions> = {
+  supportsVideo: true,
+  maximumCallsPerCallGroup: 1,
+  maximumCallGroups: 1,
+  handleType: 'generic',
+  sound: '',
+  imageName: '',
+  callsHistory: false,
+  displayCallTimeout: 60000, // 1 minute
+};
+
+export const defaultAndroidOptions: DeepRequired<InternalAndroidOptions> = {
+  incomingChannel: {
+    id: 'stream_incoming_calls_channel',
+    name: 'Incoming calls',
+    sound: '',
+    vibration: false,
+  },
+  ongoingChannel: {
+    id: 'stream_ongoing_calls_channel',
+    name: 'Ongoing calls',
+  },
+};
+
+// See ios/Callingx.mm for native iOS logic and constants mapping.
+export const iosEndCallReasonMap: Record<EndCallReason, number> = {
+  local: -1,
+  remote: 1,
+  rejected: 4,
+  busy: 2,
+  answeredElsewhere: 3,
+  missed: 2,
+  error: 0,
+};
+
+// https://developer.android.com/reference/android/telecom/DisconnectCause
+export const androidEndCallReasonMap: Record<EndCallReason, number> = {
+  local: 2,
+  remote: 3,
+  rejected: 6,
+  busy: 7,
+  answeredElsewhere: 11,
+  missed: 5,
+  error: 1,
+};

package/src/utils/headlessTask.ts

@@ -0,0 +1,52 @@
+import { AppRegistry } from 'react-native';
+
+export const HEADLESS_TASK_NAME = 'HandleCallBackgroundState';
+
+export type ManagableTask = (
+  taskData: any,
+  stopTask: () => void,
+) => Promise<void>;
+
+type HeadlessTask = (taskData: any) => Promise<void>;
+
+export const defaultBackgroundTask: ManagableTask = (
+  taskData: any,
+  stopTask: () => void,
+) => {
+  return new Promise<void>((resolve) => {
+    console.log('Default background task data', taskData);
+    let i = 0;
+    const totalIterations = 5;
+
+    function loop() {
+      if (i < totalIterations) {
+        setTimeout(() => {
+          console.log(`Iteration: ${i + 1}`);
+          i++;
+          loop();
+        }, 1000);
+      } else {
+        console.log('Default background task finished');
+        resolve(undefined);
+        stopTask();
+      }
+    }
+
+    loop();
+  });
+};
+
+let headlessTask: HeadlessTask = (taskData: any) =>
+  defaultBackgroundTask(taskData, () => {
+    console.log('Cancel callback called');
+  });
+
+export const setHeadlessTask = (task: HeadlessTask) => {
+  headlessTask = task;
+};
+
+export const registerHeadlessTask = () => {
+  AppRegistry.registerHeadlessTask(HEADLESS_TASK_NAME, () => {
+    return headlessTask;
+  });
+};

package/src/utils/permissions.ts

@@ -0,0 +1,111 @@
+import { Platform, PermissionsAndroid } from 'react-native';
+import type { Permission } from 'react-native';
+
+export interface PermissionsResult {
+  recordAudio: boolean;
+  postNotifications: boolean;
+}
+
+const allowedPostNotifications =
+  Platform.OS === 'android' && Platform.Version < 33;
+
+export const requestCallPermissions = async (): Promise<PermissionsResult> => {
+  if (Platform.OS !== 'android') {
+    return { recordAudio: true, postNotifications: true }; // iOS handles permissions differently
+  }
+
+  const permissions: string[] = [PermissionsAndroid.PERMISSIONS.RECORD_AUDIO];
+
+  // Add POST_NOTIFICATIONS for Android 13+
+  if (Platform.Version >= 33) {
+    permissions.push(PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS);
+  }
+
+  // Add WRITE_CALL_LOG for call history (required for Android 6.0+)
+  // Note: PermissionsAndroid doesn't have a constant for this, so we use the string directly
+  // permissions.push('android.permission.WRITE_CALL_LOG');
+
+  try {
+    const results = await PermissionsAndroid.requestMultiple(
+      permissions as Permission[],
+    );
+
+    // Check if all permissions are granted
+    const allGranted = Object.values(results).every(
+      (status) => status === PermissionsAndroid.RESULTS.GRANTED,
+    );
+
+    if (!allGranted) {
+      const deniedPermissions = Object.entries(results)
+        .filter(([, status]) => status !== PermissionsAndroid.RESULTS.GRANTED)
+        .map(([permission]) => permission);
+
+      console.warn('Denied permissions:', deniedPermissions);
+    }
+
+    return {
+      recordAudio:
+        results[PermissionsAndroid.PERMISSIONS.RECORD_AUDIO] ===
+        PermissionsAndroid.RESULTS.GRANTED,
+      postNotifications:
+        results[PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS] ===
+          PermissionsAndroid.RESULTS.GRANTED || allowedPostNotifications,
+    };
+  } catch (err) {
+    console.warn('Error requesting permissions:', err);
+    return { recordAudio: false, postNotifications: false };
+  }
+};
+
+export const checkCallPermissions = async (): Promise<PermissionsResult> => {
+  if (Platform.OS !== 'android') {
+    return { recordAudio: true, postNotifications: true };
+  }
+
+  const permissions: string[] = [PermissionsAndroid.PERMISSIONS.RECORD_AUDIO];
+
+  if (Platform.Version >= 33) {
+    permissions.push(PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS);
+  }
+
+  try {
+    const results = await Promise.all(
+      permissions.map(async (permission) => ({
+        permission,
+        granted: await PermissionsAndroid.check(permission as Permission),
+      })),
+    );
+
+    const resultsObject = results.reduce(
+      (acc, { permission, granted }) => {
+        acc[permission as Permission] = granted;
+        return acc;
+      },
+      {} as { [key in Permission]: boolean },
+    );
+
+    return {
+      recordAudio: resultsObject[PermissionsAndroid.PERMISSIONS.RECORD_AUDIO],
+      postNotifications:
+        resultsObject[PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS] ||
+        allowedPostNotifications,
+    };
+  } catch (err) {
+    console.warn('Error checking permissions:', err);
+    return { recordAudio: false, postNotifications: false };
+  }
+};
+
+export const requestPostNotificationPermissions =
+  async (): Promise<boolean> => {
+    if (Platform.OS !== 'android') {
+      return true;
+    }
+
+    const results = await PermissionsAndroid.request(
+      PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS,
+    );
+    return (
+      results === PermissionsAndroid.RESULTS.GRANTED || allowedPostNotifications
+    );
+  };

package/src/utils/types.ts

@@ -0,0 +1,5 @@
+export type DeepRequired<T> = {
+  [K in keyof T]-?: NonNullable<T[K]> extends object
+    ? DeepRequired<NonNullable<T[K]>>
+    : NonNullable<T[K]>;
+};

package/src/utils/utils.ts

@@ -0,0 +1,6 @@
+export const isVoipEvent = (eventName: string) => {
+  return (
+    eventName === 'voipNotificationsRegistered' ||
+    eventName === 'voipNotificationReceived'
+  );
+};