expo-callkit-telecom 0.1.0

package/plugin/src/constants.ts

@@ -0,0 +1,4 @@
+// Default timeout values in seconds
+export const DEFAULT_INCOMING_CALL_TIMEOUT = 45;
+export const DEFAULT_OUTGOING_CALL_TIMEOUT = 60;
+export const DEFAULT_FULFILL_ANSWER_CALL_TIMEOUT = 30;

package/plugin/src/withExpoCallKitTelecom.ts

@@ -0,0 +1,83 @@
+import { type ConfigPlugin, createRunOncePlugin } from "expo/config-plugins";
+
+import pkg from "../../package.json";
+import { withExpoCallKitTelecomAndroid } from "./withExpoCallKitTelecomAndroid";
+import { withExpoCallKitTelecomIos } from "./withExpoCallKitTelecomIos";
+
+export type ExpoCallKitTelecomPluginProps = {
+  /**
+   * Custom message for microphone permission prompt. Set to false to skip.
+   * @platform ios
+   */
+  microphonePermission?: string | false;
+  /**
+   * Custom message for camera permission prompt. Set to false to skip.
+   * @platform ios
+   */
+  cameraPermission?: string | false;
+  /**
+   * Timeout in seconds for incoming calls before they are marked as unanswered.
+   * @default 45
+   * @platform ios
+   * @platform android
+   */
+  incomingCallTimeout?: number;
+  /**
+   * Timeout in seconds for outgoing calls to connect before they are marked as unanswered.
+   * @default 60
+   * @platform ios
+   * @platform android
+   */
+  outgoingCallTimeout?: number;
+  /**
+   * Timeout in seconds for waiting for the call to connect after answering.
+   * @default 30
+   * @platform ios
+   * @platform android
+   */
+  fulfillAnswerCallTimeout?: number;
+  /**
+   * Array of sound file paths (relative to project root) to include in the app.
+   * These files will be copied into the iOS bundle and Android raw resources.
+   * Supported formats: .caf, .aiff, .wav (max 30 seconds for CallKit ringtones).
+   * @platform ios
+   * @platform android
+   */
+  sounds?: string[];
+  /**
+   * The default ringtone for incoming calls on iOS (CallKit).
+   * Can be the filename (with extension) of one of the provided sounds,
+   * or 'default' to use the system ringtone.
+   * @default 'default'
+   * @platform ios
+   */
+  defaultRingtoneIos?: string;
+  /**
+   * The default ringtone for incoming calls on Android (notification channel).
+   * Can be the filename (with extension) of one of the provided sounds,
+   * or 'default' to use the system ringtone.
+   * @default 'default'
+   * @platform android
+   */
+  defaultRingtoneAndroid?: string;
+  /**
+   * The default dialtone to play during outgoing calls while connecting.
+   * Must be the filename (with extension) of one of the provided sounds.
+   * @platform ios
+   * @platform android
+   */
+  defaultDialtone?: string;
+};
+
+const withExpoCallKitTelecom: ConfigPlugin<ExpoCallKitTelecomPluginProps | void> = (
+  config,
+  props,
+) => {
+  const opts: ExpoCallKitTelecomPluginProps = props ?? {};
+  config = withExpoCallKitTelecomAndroid(config, opts);
+  config = withExpoCallKitTelecomIos(config, opts);
+
+  return config;
+};
+
+export default createRunOncePlugin(withExpoCallKitTelecom, pkg.name, pkg.version);

package/plugin/src/withExpoCallKitTelecomAndroid.ts

@@ -0,0 +1,293 @@
+import {
+  AndroidConfig,
+  type ConfigPlugin,
+  withAndroidManifest,
+  withDangerousMod,
+} from "expo/config-plugins";
+import { copyFileSync, existsSync, mkdirSync } from "fs";
+import { basename, resolve } from "path";
+
+import {
+  DEFAULT_FULFILL_ANSWER_CALL_TIMEOUT,
+  DEFAULT_INCOMING_CALL_TIMEOUT,
+  DEFAULT_OUTGOING_CALL_TIMEOUT,
+} from "./constants";
+import type { ExpoCallKitTelecomPluginProps } from "./withExpoCallKitTelecom";
+
+const ERROR_MSG_PREFIX = "An error occurred while configuring Android calls. ";
+
+// biome-ignore lint/suspicious/noExplicitAny: Expo config plugin manifest types are untyped
+function setMetaDataValue(app: any, key: string, value: string): void {
+  const existing = app["meta-data"]?.find(
+    // biome-ignore lint/suspicious/noExplicitAny: manifest meta-data items are untyped
+    (item: any) => item.$["android:name"] === key,
+  );
+  if (existing) {
+    existing.$["android:value"] = value;
+    return;
+  }
+
+  if (!app["meta-data"]) {
+    app["meta-data"] = [];
+  }
+  app["meta-data"].push({
+    $: {
+      "android:name": key,
+      "android:value": value,
+    },
+  });
+}
+
+/**
+ * Sanitizes a filename for use as an Android raw resource name.
+ *
+ * Android raw resource names must be lowercase, alphanumeric + underscores,
+ * and cannot start with a digit.
+ */
+function toAndroidRawResourceName(filename: string): string {
+  const withoutExtension = filename.replace(/\.[^.]+$/, "");
+  const sanitized = withoutExtension.toLowerCase().replace(/[^a-z0-9_]/g, "_");
+  return /^\d/.test(sanitized) ? `_${sanitized}` : sanitized;
+}
+
+/**
+ * Configures call timeout values in AndroidManifest metadata.
+ */
+const withTimeouts: ConfigPlugin<{
+  incomingCallTimeout?: number;
+  outgoingCallTimeout?: number;
+  fulfillAnswerCallTimeout?: number;
+}> = (
+  config,
+  { incomingCallTimeout, outgoingCallTimeout, fulfillAnswerCallTimeout },
+) => {
+  return withAndroidManifest(config, (config) => {
+    const app = AndroidConfig.Manifest.getMainApplicationOrThrow(
+      config.modResults,
+    );
+
+    setMetaDataValue(
+      app,
+      "ExpoCallKitTelecomIncomingCallTimeout",
+      String(incomingCallTimeout ?? DEFAULT_INCOMING_CALL_TIMEOUT),
+    );
+
+    setMetaDataValue(
+      app,
+      "ExpoCallKitTelecomOutgoingCallTimeout",
+      String(outgoingCallTimeout ?? DEFAULT_OUTGOING_CALL_TIMEOUT),
+    );
+
+    setMetaDataValue(
+      app,
+      "ExpoCallKitTelecomFulfillAnswerCallTimeout",
+      String(fulfillAnswerCallTimeout ?? DEFAULT_FULFILL_ANSWER_CALL_TIMEOUT),
+    );
+
+    return config;
+  });
+};
+
+/**
+ * Copies sound files into the Android raw resources directory.
+ */
+const withSounds: ConfigPlugin<{ sounds?: string[] }> = (
+  config,
+  { sounds },
+) => {
+  if (!sounds || sounds.length === 0) {
+    return config;
+  }
+
+  return withDangerousMod(config, [
+    "android",
+    (config) => {
+      const projectRoot = config.modRequest.projectRoot;
+      const rawDir = resolve(
+        projectRoot,
+        "android",
+        "app",
+        "src",
+        "main",
+        "res",
+        "raw",
+      );
+
+      mkdirSync(rawDir, { recursive: true });
+
+      for (const soundPath of sounds) {
+        const filename = basename(soundPath);
+        const sourcePath = resolve(projectRoot, soundPath);
+
+        if (!existsSync(sourcePath)) {
+          throw new Error(
+            `${ERROR_MSG_PREFIX}Sound file not found: ${sourcePath}`,
+          );
+        }
+
+        const resourceName = toAndroidRawResourceName(filename);
+        const extension = filename.includes(".")
+          ? filename.substring(filename.lastIndexOf("."))
+          : "";
+        const destinationPath = resolve(rawDir, `${resourceName}${extension}`);
+
+        copyFileSync(sourcePath, destinationPath);
+      }
+
+      return config;
+    },
+  ]);
+};
+
+/**
+ * Configures the default dialtone for outgoing calls in AndroidManifest metadata.
+ */
+const withDefaultDialtone: ConfigPlugin<{
+  sounds?: string[];
+  defaultDialtone?: string;
+}> = (config, { sounds, defaultDialtone }) => {
+  if (!defaultDialtone) {
+    return config;
+  }
+
+  const soundFilenames = sounds?.map((s) => basename(s)) ?? [];
+
+  if (soundFilenames.length === 0) {
+    throw new Error(
+      `${ERROR_MSG_PREFIX}"defaultDialtone" was specified but no ` +
+        `sounds were provided.`,
+    );
+  }
+  if (!soundFilenames.includes(defaultDialtone)) {
+    throw new Error(
+      `${ERROR_MSG_PREFIX}"defaultDialtone" must be one of the provided ` +
+        `sounds (${soundFilenames.join(", ")}).`,
+    );
+  }
+
+  return withAndroidManifest(config, (config) => {
+    const app = AndroidConfig.Manifest.getMainApplicationOrThrow(
+      config.modResults,
+    );
+
+    setMetaDataValue(
+      app,
+      "ExpoCallKitTelecomDefaultDialtone",
+      toAndroidRawResourceName(defaultDialtone),
+    );
+
+    return config;
+  });
+};
+
+/**
+ * Configures the default ringtone for incoming calls in AndroidManifest metadata.
+ *
+ * Mirrors the iOS `withDefaultRingtone` plugin. The Kotlin side reads
+ * `ExpoCallKitTelecomDefaultRingtone` from manifest metadata and sets it as the
+ * notification channel sound.
+ */
+const withDefaultRingtone: ConfigPlugin<{
+  sounds?: string[];
+  defaultRingtone?: string;
+}> = (config, { sounds, defaultRingtone }) => {
+  if (!defaultRingtone || defaultRingtone === "default") {
+    return config;
+  }
+
+  const soundFilenames = sounds?.map((s) => basename(s)) ?? [];
+
+  if (soundFilenames.length === 0) {
+    throw new Error(
+      `${ERROR_MSG_PREFIX}"defaultRingtone" was specified but no ` +
+        `sounds were provided.`,
+    );
+  }
+  if (!soundFilenames.includes(defaultRingtone)) {
+    throw new Error(
+      `${ERROR_MSG_PREFIX}"defaultRingtone" must be one of the provided ` +
+        `sounds (${soundFilenames.join(", ")}) or "default" for ` +
+        `system ringtone.`,
+    );
+  }
+
+  return withAndroidManifest(config, (config) => {
+    const app = AndroidConfig.Manifest.getMainApplicationOrThrow(
+      config.modResults,
+    );
+
+    setMetaDataValue(
+      app,
+      "ExpoCallKitTelecomDefaultRingtone",
+      toAndroidRawResourceName(defaultRingtone),
+    );
+
+    return config;
+  });
+};
+
+/**
+ * Removes expo-notifications' ExpoFirebaseMessagingService from the manifest.
+ *
+ * Our ExpoCallKitTelecomMessagingService extends it and takes over as the sole
+ * MESSAGING_EVENT handler, delegating non-call messages via super.
+ * Having both services registered would cause undefined delivery behaviour.
+ *
+ * The service is declared in expo-notifications' library AndroidManifest.xml,
+ * so we must use `tools:node="remove"` to tell the manifest merger to strip it.
+ */
+const withFirebaseMessagingService: ConfigPlugin<ExpoCallKitTelecomPluginProps> = (
+  config,
+) => {
+  return withAndroidManifest(config, (config) => {
+    const manifest = config.modResults.manifest;
+
+    // Ensure the tools namespace is declared on the root <manifest> element.
+    if (!manifest.$["xmlns:tools"]) {
+      manifest.$["xmlns:tools"] = "http://schemas.android.com/tools";
+    }
+
+    const app = AndroidConfig.Manifest.getMainApplicationOrThrow(
+      config.modResults,
+    );
+
+    if (!app.service) {
+      app.service = [];
+    }
+
+    const notificationsService =
+      "expo.modules.notifications.service.ExpoFirebaseMessagingService";
+
+    // Remove any existing entry first (idempotent across repeated prebuilds).
+    app.service = app.service.filter(
+      (service) => service.$?.["android:name"] !== notificationsService,
+    );
+
+    // Add a tools:node="remove" marker so the manifest merger strips the
+    // library-declared service during the Gradle build.
+    const removeEntry = {
+      $: {
+        "android:name": notificationsService,
+        "tools:node": "remove",
+      },
+    };
+    app.service.push(removeEntry);
+
+    return config;
+  });
+};
+
+export const withExpoCallKitTelecomAndroid: ConfigPlugin<ExpoCallKitTelecomPluginProps> = (
+  config,
+  props,
+) => {
+  config = withTimeouts(config, props);
+  config = withSounds(config, props);
+  config = withDefaultRingtone(config, {
+    sounds: props.sounds,
+    defaultRingtone: props.defaultRingtoneAndroid,
+  });
+  config = withDefaultDialtone(config, props);
+  config = withFirebaseMessagingService(config, props);
+  return config;
+};

package/plugin/src/withExpoCallKitTelecomIos.ts

@@ -0,0 +1,276 @@
+import {
+  type ConfigPlugin,
+  IOSConfig,
+  withEntitlementsPlist,
+  withInfoPlist,
+  withXcodeProject,
+} from "expo/config-plugins";
+import { copyFileSync, existsSync } from "fs";
+import { basename, resolve } from "path";
+
+import {
+  DEFAULT_FULFILL_ANSWER_CALL_TIMEOUT,
+  DEFAULT_INCOMING_CALL_TIMEOUT,
+  DEFAULT_OUTGOING_CALL_TIMEOUT,
+} from "./constants";
+import type { ExpoCallKitTelecomPluginProps } from "./withExpoCallKitTelecom";
+
+const ERROR_MSG_PREFIX = "An error occurred while configuring iOS calls. ";
+
+// Default permission messages
+const CAMERA_USAGE = "Allow $(PRODUCT_NAME) to access your camera";
+const MICROPHONE_USAGE = "Allow $(PRODUCT_NAME) to access your microphone";
+
+// Required background modes for CallKit and PushKit:
+// - voip: Receive VoIP push notifications to wake the app for incoming calls
+// - audio: Continue audio playback/recording during calls when app is backgrounded
+const BACKGROUND_MODES = ["voip", "audio"];
+
+// SiriKit intents for voice-activated calls
+// INStartCallIntent: Unified intent for iOS 13+ (recommended)
+// INStartAudioCallIntent/INStartVideoCallIntent: Deprecated in iOS 13, but still
+// sent by the system in some cases (e.g., redialing from call history)
+const SIRI_INTENTS = [
+  "INStartCallIntent",
+  "INStartAudioCallIntent",
+  "INStartVideoCallIntent",
+];
+
+/**
+ * Configures camera and microphone permissions for VoIP and video calls.
+ */
+const withPermissions: ConfigPlugin<{
+  cameraPermission?: string | false;
+  microphonePermission?: string | false;
+}> = (config, { cameraPermission, microphonePermission }) => {
+  return IOSConfig.Permissions.createPermissionsPlugin({
+    NSCameraUsageDescription: CAMERA_USAGE,
+    NSMicrophoneUsageDescription: MICROPHONE_USAGE,
+  })(config, {
+    NSCameraUsageDescription: cameraPermission,
+    NSMicrophoneUsageDescription: microphonePermission,
+  });
+};
+
+/**
+ * Configures push notification entitlement for PushKit VoIP notifications.
+ */
+const withPushNotificationEntitlement: ConfigPlugin = (config) => {
+  return withEntitlementsPlist(config, (config) => {
+    const key = "aps-environment";
+    // Only set if not already configured; production builds use provisioning profile value
+    if (!config.modResults[key]) {
+      config.modResults[key] = "development";
+    }
+    return config;
+  });
+};
+
+/**
+ * Configures UIBackgroundModes for VoIP call handling.
+ */
+const withBackgroundModes: ConfigPlugin = (config) => {
+  return withInfoPlist(config, (config) => {
+    const existingModes = config.modResults.UIBackgroundModes;
+    const modes = Array.isArray(existingModes)
+      ? (existingModes as string[])
+      : [];
+
+    const newModes = new Set([...modes, ...BACKGROUND_MODES]);
+    config.modResults.UIBackgroundModes = [...newModes];
+
+    return config;
+  });
+};
+
+/**
+ * Configures SiriKit intents for voice-activated audio/video calls.
+ */
+const withSiriIntents: ConfigPlugin = (config) => {
+  return withInfoPlist(config, (config) => {
+    const existingIntents = config.modResults.NSUserActivityTypes;
+    const intents = Array.isArray(existingIntents)
+      ? (existingIntents as string[])
+      : [];
+
+    const newIntents = new Set([...intents, ...SIRI_INTENTS]);
+    config.modResults.NSUserActivityTypes = [...newIntents];
+
+    return config;
+  });
+};
+
+/**
+ * Configures call timeout values in Info.plist.
+ */
+const withTimeouts: ConfigPlugin<{
+  incomingCallTimeout?: number;
+  outgoingCallTimeout?: number;
+  fulfillAnswerCallTimeout?: number;
+}> = (
+  config,
+  { incomingCallTimeout, outgoingCallTimeout, fulfillAnswerCallTimeout },
+) => {
+  return withInfoPlist(config, (config) => {
+    config.modResults.ExpoCallKitTelecomIncomingCallTimeout =
+      incomingCallTimeout ?? DEFAULT_INCOMING_CALL_TIMEOUT;
+    config.modResults.ExpoCallKitTelecomOutgoingCallTimeout =
+      outgoingCallTimeout ?? DEFAULT_OUTGOING_CALL_TIMEOUT;
+    config.modResults.ExpoCallKitTelecomFulfillAnswerCallTimeout =
+      fulfillAnswerCallTimeout ?? DEFAULT_FULFILL_ANSWER_CALL_TIMEOUT;
+    return config;
+  });
+};
+
+/**
+ * Copies sound files into the iOS project bundle.
+ */
+function setSoundFiles(
+  config: Parameters<Parameters<typeof withXcodeProject>[1]>[0],
+  sounds: string[],
+) {
+  const projectRoot = config.modRequest.projectRoot;
+  const projectName = config.modRequest.projectName;
+
+  if (!projectName) {
+    throw new Error(`${ERROR_MSG_PREFIX}Unable to find iOS project name.`);
+  }
+
+  const sourceRoot = resolve(projectRoot, "ios", projectName);
+
+  for (const soundPath of sounds) {
+    const filename = basename(soundPath);
+    const sourcePath = resolve(projectRoot, soundPath);
+    const destinationPath = resolve(sourceRoot, filename);
+
+    if (!existsSync(sourcePath)) {
+      throw new Error(`${ERROR_MSG_PREFIX}Sound file not found: ${sourcePath}`);
+    }
+
+    // Copy the file to the iOS project directory
+    copyFileSync(sourcePath, destinationPath);
+
+    // Add the file to the Xcode project if not already present
+    if (!config.modResults.hasFile(`${projectName}/${filename}`)) {
+      config.modResults = IOSConfig.XcodeUtils.addResourceFileToGroup({
+        filepath: `${projectName}/${filename}`,
+        groupName: projectName,
+        isBuildFile: true,
+        project: config.modResults,
+      });
+    }
+  }
+
+  return config;
+}
+
+/**
+ * Copies sound files into the iOS project bundle.
+ */
+const withSounds: ConfigPlugin<{ sounds?: string[] }> = (
+  config,
+  { sounds },
+) => {
+  if (sounds && sounds.length > 0) {
+    config = withXcodeProject(config, (config) => {
+      return setSoundFiles(config, sounds);
+    });
+  }
+  return config;
+};
+
+/**
+ * Configures the default ringtone for incoming calls in Info.plist.
+ */
+const withDefaultRingtone: ConfigPlugin<{
+  sounds?: string[];
+  defaultRingtone?: string;
+}> = (config, { sounds, defaultRingtone }) => {
+  const soundFilenames = sounds?.map((s) => basename(s)) ?? [];
+
+  // Validate defaultRingtone if specified and not 'default'
+  if (defaultRingtone && defaultRingtone !== "default") {
+    if (soundFilenames.length === 0) {
+      throw new Error(
+        `${ERROR_MSG_PREFIX}"defaultRingtone" was specified but no ` +
+          `sounds were provided.`,
+      );
+    }
+    if (!soundFilenames.includes(defaultRingtone)) {
+      throw new Error(
+        `${ERROR_MSG_PREFIX}"defaultRingtone" must be one of the provided ` +
+          `sounds (${soundFilenames.join(", ")}) or "default" for ` +
+          `system ringtone.`,
+      );
+    }
+  }
+
+  return withInfoPlist(config, (config) => {
+    config.modResults.ExpoCallKitTelecomDefaultRingtone = defaultRingtone || "default";
+    return config;
+  });
+};
+
+/**
+ * Configures the default dialtone for outgoing calls in Info.plist.
+ */
+const withDefaultDialtone: ConfigPlugin<{
+  sounds?: string[];
+  defaultDialtone?: string;
+}> = (config, { sounds, defaultDialtone }) => {
+  if (!defaultDialtone) {
+    return config;
+  }
+
+  const soundFilenames = sounds?.map((s) => basename(s)) ?? [];
+
+  if (soundFilenames.length === 0) {
+    throw new Error(
+      `${ERROR_MSG_PREFIX}"defaultDialtone" was specified but no ` +
+        `sounds were provided.`,
+    );
+  }
+  if (!soundFilenames.includes(defaultDialtone)) {
+    throw new Error(
+      `${ERROR_MSG_PREFIX}"defaultDialtone" must be one of the provided ` +
+        `sounds (${soundFilenames.join(", ")}).`,
+    );
+  }
+
+  return withInfoPlist(config, (config) => {
+    config.modResults.ExpoCallKitTelecomDefaultDialtone = defaultDialtone;
+    return config;
+  });
+};
+
+export const withExpoCallKitTelecomIos: ConfigPlugin<ExpoCallKitTelecomPluginProps> = (
+  config,
+  {
+    cameraPermission,
+    microphonePermission,
+    incomingCallTimeout,
+    outgoingCallTimeout,
+    fulfillAnswerCallTimeout,
+    sounds,
+    defaultRingtoneIos,
+    defaultDialtone,
+  },
+) => {
+  config = withPermissions(config, { cameraPermission, microphonePermission });
+  config = withPushNotificationEntitlement(config);
+  config = withBackgroundModes(config);
+  config = withSiriIntents(config);
+  config = withTimeouts(config, {
+    incomingCallTimeout,
+    outgoingCallTimeout,
+    fulfillAnswerCallTimeout,
+  });
+  config = withSounds(config, { sounds });
+  config = withDefaultRingtone(config, {
+    sounds,
+    defaultRingtone: defaultRingtoneIos,
+  });
+  config = withDefaultDialtone(config, { sounds, defaultDialtone });
+
+  return config;
+};