@ethora/chat-component-rn 26.5.20 → 26.6.10

package/src/components/styled/SendInput.tsx

@@ -13,12 +13,21 @@ import { KeyboardAvoidingView, Platform, View, Text, TouchableOpacity, Alert, Li
 import AttachSheet from '../Modals/AttachSheet/AttachSheet';
 import { MediaFilePreview } from './MediaFilePreview';
 import { getIconColor } from '../../helpers/getIconColor';
+import { getElementFont } from '../../helpers/getElementFont';
+import { useT } from '../../i18n/useT';
 import * as ImagePicker from 'expo-image-picker';
 import * as DocumentPicker from 'expo-document-picker';
 import * as ImageManipulator from 'expo-image-manipulator';
-// `Audio` namespace gives us permissions, audio mode, presets, and the
-// Recording class — same pattern AudioMessage uses for Audio.Sound.
-import { Audio } from 'expo-av';
+// expo-audio replaces the discontinued expo-av: `useAudioRecorder` owns a
+// single reusable recorder for this input's lifetime (prepare → record →
+// stop → prepare again), and the module-level helpers cover permissions
+// and the iOS audio session.
+import {
+  useAudioRecorder,
+  setAudioModeAsync,
+  requestRecordingPermissionsAsync,
+  RecordingPresets,
+} from 'expo-audio';
 
 // iOS photos default to HEIC; many web backends (incl. ours) 500 on
 // HEIC uploads because they can't decode it. Convert to JPEG before
@@ -87,6 +96,7 @@ const SendInput: React.FC<SendInputProps> = ({
   isLoading,
   isMessageProcessing,
 }) => {
+  const t = useT();
   const [message, setMessage] = useState('');
   const [isRecording, setIsRecording] = useState(false);
   // Live counter (seconds) for the recording overlay. Updated by a
@@ -96,14 +106,20 @@ const SendInput: React.FC<SendInputProps> = ({
   const [filePreviews, setFilePreviews] = useState<MediaFile[]>([]);
   const [showMediaMenu, setShowMediaMenu] = useState(false);
 
-  // expo-av's Audio.Recording instance for the in-progress recording.
-  // Kept in a ref (not state) because handlers fire synchronously and we
-  // need the latest instance without waiting for a re-render.
-  // Typed via InstanceType<typeof Audio.Recording> because direct
-  // `Audio.Recording` as a type-position lookup fails under bundler
-  // resolution even though the class is in the Audio namespace at
-  // runtime. InstanceType resolves through the typeof of the value.
-  const recordingRef = useRef<InstanceType<typeof Audio.Recording> | null>(null);
+  // expo-audio's recorder is a long-lived native object owned by the hook
+  // (released automatically on unmount) and reused across recordings, so
+  // unlike expo-av's one-shot `Audio.Recording` there is no per-recording
+  // instance to hold. The hook has to run unconditionally, but the
+  // constructor is inert on both platforms — iOS allocates a bare
+  // AVAudioRecorder (no file), Android leaves its MediaRecorder null.
+  // Nothing claims the mic, writes a file, or switches the iOS session to
+  // playAndRecord until `prepareToRecordAsync`, so consumers with
+  // `enableAudio` off carry an idle object and nothing more.
+  const audioRecorder = useAudioRecorder(RecordingPresets.HIGH_QUALITY);
+  // Tracks whether a recording is actually in flight, so cancel/stop and
+  // the unmount teardown can tell "never started" from "needs stopping"
+  // without reading native state.
+  const isRecordingRef = useRef(false);
   const recordingTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
 
   // Refs shadow `message` and `filePreviews` so handleSendClick can:
@@ -120,6 +136,13 @@ const SendInput: React.FC<SendInputProps> = ({
   // (versus duplicating the send with stale closure state).
   const sendingRef = useRef(false);
 
+  // Re-entry guard for the document picker. expo-document-picker keeps a
+  // single native `pickingContext`; invoking getDocumentAsync again while a
+  // pick is still in flight throws "Different document picking in progress"
+  // (iOS, bug #4). A double-fire happens on a fast double-tap of the
+  // "Document" row or a dev-mode double-run of the sheet's close callback.
+  const pickingDocRef = useRef(false);
+
   const handleFileSelect = (files: MediaFile[]) => {
     // Enforce the upload size cap before anything reaches the network.
     // The backend rejects oversized bodies with HTTP 413; catching it
@@ -237,7 +260,21 @@ const SendInput: React.FC<SendInputProps> = ({
   };
 
   const handleFileSelection = async () => {
+    // Drop overlapping invocations — a second getDocumentAsync while the
+    // first is still presented throws PickingInProgressException on iOS.
+    if (pickingDocRef.current) {return;}
+    pickingDocRef.current = true;
     try {
+      // Let the attach-sheet's modal finish its NATIVE dismissal before we
+      // present the picker. The sheet fires this handler right after its
+      // slide-out animation, but the underlying RN Modal view-controller
+      // dismissal is async — presenting the document picker over a still-
+      // dismissing modal makes iOS tear it down without a cancel callback,
+      // which strands expo-document-picker's pickingContext and makes every
+      // subsequent open throw "Different document picking in progress".
+      if (Platform.OS === 'ios') {
+        await new Promise((resolve) => setTimeout(resolve, 350));
+      }
       const result = await DocumentPicker.getDocumentAsync({
         type: '*/*',
         multiple: false,
@@ -255,6 +292,8 @@ const SendInput: React.FC<SendInputProps> = ({
       ]);
     } catch (err) {
       console.error('DocumentPicker error:', err);
+    } finally {
+      pickingDocRef.current = false;
     }
   };
 
@@ -266,7 +305,7 @@ const SendInput: React.FC<SendInputProps> = ({
   //
   // Mirrors the web experience: tap mic → start recording → either tap
   // X to discard, or tap send to stop + immediately upload + post the
-  // voice message. Uses expo-av's Audio.Recording (already a peer dep
+  // voice message. Uses expo-audio's AudioRecorder (already a peer dep
   // for AudioMessage playback). Filename is `voice-<timestamp>.m4a` with
   // mimetype `audio/m4a` so the receiver routes through the audio
   // branch in MediaMessage directly, no octet-stream sniffing needed.
@@ -282,9 +321,9 @@ const SendInput: React.FC<SendInputProps> = ({
   // playback elsewhere in the app isn't routed to the earpiece.
   const restoreAudioMode = async () => {
     try {
-      await Audio.setAudioModeAsync({
-        allowsRecordingIOS: false,
-        playsInSilentModeIOS: true,
+      await setAudioModeAsync({
+        allowsRecording: false,
+        playsInSilentMode: true,
       });
     } catch {
       /* non-fatal */
@@ -292,27 +331,30 @@ const SendInput: React.FC<SendInputProps> = ({
   };
 
   const handleStartRecording = async () => {
-    if (isRecording || recordingRef.current) {return;}
+    if (isRecording || isRecordingRef.current) {return;}
     try {
-      const perm = await Audio.requestPermissionsAsync();
+      const perm = await requestRecordingPermissionsAsync();
       if (!perm.granted) {
         promptOpenSettings(
           'Microphone permission is needed to record voice messages.'
         );
         return;
       }
-      // iOS: recording requires `allowsRecordingIOS:true`; we'll
-      // flip it back in restoreAudioMode after stop/cancel.
-      await Audio.setAudioModeAsync({
-        allowsRecordingIOS: true,
-        playsInSilentModeIOS: true,
+      // `allowsRecording` is not just an iOS session flag: expo-audio's
+      // recorder throws RecordingDisabledException from record() when the
+      // audio mode has it off. Flipped back in restoreAudioMode after
+      // stop/cancel so playback elsewhere isn't stuck on the earpiece.
+      await setAudioModeAsync({
+        allowsRecording: true,
+        playsInSilentMode: true,
       });
-      const rec = new Audio.Recording();
-      await rec.prepareToRecordAsync(
-        Audio.RecordingOptionsPresets.HIGH_QUALITY
-      );
-      await rec.startAsync();
-      recordingRef.current = rec;
+      // Passing the preset (rather than preparing bare) makes the native
+      // side allocate a FRESH output file for this take. Without it the
+      // recorder reuses the previous URL, so a second voice message would
+      // overwrite the first while its upload is still in flight.
+      await audioRecorder.prepareToRecordAsync(RecordingPresets.HIGH_QUALITY);
+      audioRecorder.record();
+      isRecordingRef.current = true;
       setIsRecording(true);
       setRecordingDuration(0);
       const startedAt = Date.now();
@@ -322,7 +364,7 @@ const SendInput: React.FC<SendInputProps> = ({
       }, 250);
     } catch (err) {
       console.warn('startRecording failed', err);
-      recordingRef.current = null;
+      isRecordingRef.current = false;
       setIsRecording(false);
       setRecordingDuration(0);
       await restoreAudioMode();
@@ -331,15 +373,15 @@ const SendInput: React.FC<SendInputProps> = ({
 
   const handleCancelRecording = async () => {
     stopRecordingTimer();
-    const rec = recordingRef.current;
-    recordingRef.current = null;
+    const wasRecording = isRecordingRef.current;
+    isRecordingRef.current = false;
     setIsRecording(false);
     setRecordingDuration(0);
-    if (rec) {
+    if (wasRecording) {
       try {
-        await rec.stopAndUnloadAsync();
+        await audioRecorder.stop();
       } catch {
-        /* already stopped / unloaded — fine */
+        /* already stopped — fine */
       }
     }
     await restoreAudioMode();
@@ -347,12 +389,12 @@ const SendInput: React.FC<SendInputProps> = ({
 
   const handleStopAndSendRecording = async () => {
     stopRecordingTimer();
-    const rec = recordingRef.current;
-    recordingRef.current = null;
+    const wasRecording = isRecordingRef.current;
+    isRecordingRef.current = false;
     setIsRecording(false);
     const seconds = recordingDuration;
     setRecordingDuration(0);
-    if (!rec) {
+    if (!wasRecording) {
       await restoreAudioMode();
       return;
     }
@@ -360,18 +402,20 @@ const SendInput: React.FC<SendInputProps> = ({
     // within the same tick there's nothing audible to send.
     if (seconds < 1) {
       try {
-        await rec.stopAndUnloadAsync();
+        await audioRecorder.stop();
       } catch {}
       await restoreAudioMode();
       return;
     }
     try {
-      await rec.stopAndUnloadAsync();
+      await audioRecorder.stop();
     } catch (err) {
-      console.warn('stopAndUnloadAsync failed', err);
+      console.warn('recorder.stop failed', err);
     }
+    // Read the URI while it still points at THIS take — the next
+    // prepareToRecordAsync() swaps in a new output file.
+    const uri = audioRecorder.uri;
     await restoreAudioMode();
-    const uri = rec.getURI();
     if (!uri) {return;}
     // HIGH_QUALITY preset writes AAC in an M4A container on both iOS
     // and Android, so a single mimetype works. `voice-<ts>.m4a`
@@ -395,14 +439,16 @@ const SendInput: React.FC<SendInputProps> = ({
   useEffect(() => {
     return () => {
       stopRecordingTimer();
-      const rec = recordingRef.current;
-      recordingRef.current = null;
-      if (rec) {
-        rec.stopAndUnloadAsync().catch(() => {});
+      if (isRecordingRef.current) {
+        isRecordingRef.current = false;
+        audioRecorder.stop().catch(() => {});
       }
       restoreAudioMode();
     };
-  }, []);
+    // The hook's recorder identity is stable (its options never change),
+    // so this teardown runs on unmount only.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [audioRecorder]);
 
   const handleRemoveImage = (index: number) => {
     const next = filePreviewsRef.current.filter((_, i) => i !== index);
@@ -463,6 +509,24 @@ const SendInput: React.FC<SendInputProps> = ({
     setMessage(next);
   }, [editMessage]);
 
+  // iOS's multiline TextInput always top-aligns its content (UITextView
+  // has no vertical-centering API RN can hook into — `textAlignVertical`
+  // is Android-only), so a `minHeight` taller than one text line leaves
+  // the placeholder/cursor pinned near the top instead of centered. Fix:
+  // derive vertical padding from the actual line height so the box's
+  // resting height already equals its content height — nothing is left
+  // to look top-aligned.
+  const inputFontSize =
+    config?.typography?.input?.fontSize ??
+    config?.typography?.elements?.inputText?.fontSize ??
+    16;
+  const inputMinHeight = config?.typography?.input?.minHeight ?? 40;
+  const estimatedLineHeight = inputFontSize * 1.2;
+  const inputVerticalPadding = Math.max(
+    4,
+    (inputMinHeight - estimatedLineHeight) / 2
+  );
+
   return (
     <InputContainer isText={!!message}>
         {filePreviews.length > 0 && (
@@ -497,7 +561,7 @@ const SendInput: React.FC<SendInputProps> = ({
                 color={config?.colors?.primary}
                 fontSize={config?.typography?.input?.fontSize}
                 fontWeight={config?.typography?.input?.fontWeight as any}
-                placeholder="Type message"
+                placeholder={t('input.placeholder')}
                 placeholderTextColor="#999"
                 value={message}
                 onChangeText={(text) => {
@@ -517,14 +581,20 @@ const SendInput: React.FC<SendInputProps> = ({
                 // No fixed height: a multiline TextInput auto-grows to fit
                 // its content between min/max. Locking `height` made iOS
                 // top-align the text inside the taller box (it looked like
-                // the text had dropped). minHeight keeps the 40px tap
-                // target; the row's align-items:center vertically centres
-                // the content-sized input.
-                style={{
-                  minHeight: config?.typography?.input?.minHeight ?? 40,
-                  maxHeight: config?.typography?.input?.maxHeight ?? 120,
-                  flex: 1,
-                }}
+                // the text had dropped). paddingVertical (computed above)
+                // makes the resting box height equal minHeight without
+                // leaving slack above the text, which is what actually
+                // centers it on iOS.
+                style={[
+                  {
+                    minHeight: inputMinHeight,
+                    maxHeight: config?.typography?.input?.maxHeight ?? 120,
+                    paddingTop: inputVerticalPadding,
+                    paddingBottom: inputVerticalPadding,
+                    flex: 1,
+                  },
+                  getElementFont(config, 'inputText'),
+                ]}
               />
             </>
           )}

package/src/components/styled/StyledComponents.ts

@@ -40,12 +40,15 @@ export const CenterContainer = styled.View<{
 }>`
   align-items: center;
   justify-content: center;
-  width: ${({ rightSpace, leftSpace }) =>
-    rightSpace && !leftSpace
-      ? '100%'
-      : rightSpace || !leftSpace
-        ? '90%'
-        : '70%'};
+  /* flex:1 so the title fills the space BETWEEN the left (back/avatar) and
+   * right (globe / call / menu) clusters and shrinks to make room for them.
+   * The previous fixed 90% width overflowed the row (15% left + 90% center
+   * + 25% right = 130%), pushing the right cluster — the translate globe,
+   * call and room-menu icons — off-screen where it rendered but was clipped
+   * by the device edge. min-width:0 lets the title ellipsize instead of
+   * forcing the row wider. Mirrors the web header's flexbox layout. */
+  flex: 1;
+  min-width: 0;
   padding-right: ${({ rightSpace }) => (rightSpace ? '16' : '0')}px;
   padding-left: ${({ leftSpace }) => (leftSpace ? '16' : '0')}px;
 `;

package/src/components/styled/StyledInputComponents/Composing.tsx

@@ -51,7 +51,13 @@ const Composing: FC<ComposingProps> = ({ usersTyping = ['User'], style }) => {
   return (
     <View style={[styles.wrapper, style]}>
       {typingText ? (
-        <Text style={styles.typingText}>{typingText}</Text>
+        <Text
+          style={styles.typingText}
+          numberOfLines={1}
+          ellipsizeMode="tail"
+        >
+          {typingText}
+        </Text>
       ) : (
         <View />
       )}

package/src/context/xmppProvider.tsx

@@ -10,6 +10,7 @@ import React, {
 } from 'react';
 import { AppState, DeviceEventEmitter } from 'react-native';
 import NetInfo from '@react-native-community/netinfo';
+import { VideoCallOverlay } from '../components/VideoCalls/VideoCallOverlay';
 import XmppClient, {
   XmppCredentialsProvider,
 } from '../networking/xmppClient';
@@ -506,7 +507,13 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
   useEffect(() => {
     if (!client) {return;}
     const id = setInterval(() => {
-      if (AppState.currentState !== 'active') {return;}
+      // Only skip while genuinely backgrounded. iOS also reports 'inactive'
+      // for transient states the user still sees the chat through (control
+      // centre, an incoming-call banner, app-switcher preview, and — on the
+      // simulator — whenever the window is not focused). Gating on
+      // `!== 'active'` meant the watchdog silently stopped running in all of
+      // those, so a socket that dropped during one never got revived.
+      if (AppState.currentState === 'background') {return;}
       if (client.suppressReconnect) {return;}
       if (client.status !== 'online') {
         devPushLog('rn', `watchdog: client ${client.status} → forceReconnect`);
@@ -770,6 +777,12 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
       }}
     >
       {children}
+      {/* Lives here, not inside <Chat>: an incoming call-token can arrive
+          (and must still ring) while the user is on a different screen of
+          the host app, as long as the socket is up. VideoCallOverlay reads
+          config and call state from Redux itself, so it needs nothing
+          passed in, and renders null whenever no call is in flight. */}
+      <VideoCallOverlay />
     </XmppContext.Provider>
   );
 };

package/src/helpers/callLogMessage.ts

@@ -0,0 +1,174 @@
+import { IMessage } from '../types/types';
+
+// A server "call-state" stanza is emitted into the room when a call session
+// concludes (someone leaves the LiveKit room). It carries:
+//   type="call-state" callId="..." durationMs="<ms>"
+//   callerXmppUsername="<who started the call>" isSystemMessage="true"
+// We turn it into a friendly chat-log entry, Telegram/WhatsApp style:
+//   - durationMs > 0  -> "Outgoing call · 12 sec" / "Incoming call · 1 min"
+//   - durationMs == 0 -> "No answer" (we called)  / "Missed call" (they called)
+// Direction is derived from callerXmppUsername vs the logged-in user.
+
+export interface CallLogMeta {
+  callId: string;
+  direction: 'outgoing' | 'incoming';
+  durationMs: number;
+  missed: boolean;
+  kind: 'audio' | 'video';
+}
+
+export const isCallLogMessage = (message: unknown): boolean => {
+  const type = String((message as any)?.type || '').toLowerCase();
+  return type === 'call-state';
+};
+
+// Only a call-state that actually carries log metadata (a caller and/or a
+// duration) is worth rendering. Bare client-side signaling frames
+// (state=cancelled/declined/ended with no caller/duration) must NOT become
+// chat entries, they're real-time teardown only.
+export const callStateHasLogData = (attrs: Record<string, any>): boolean => {
+  if (!attrs) {return false;}
+  const hasCaller = !!String(attrs.callerXmppUsername || '').trim();
+  const hasDuration =
+    attrs.durationMs !== undefined &&
+    attrs.durationMs !== null &&
+    attrs.durationMs !== '';
+  return hasCaller || hasDuration;
+};
+
+export const formatCallDuration = (ms: number): string => {
+  const totalSeconds = Math.max(0, Math.round(ms / 1000));
+  if (totalSeconds < 60) {return `${totalSeconds} sec`;}
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  if (seconds === 0) {return `${minutes} min`;}
+  return `${minutes} min ${seconds} sec`;
+};
+
+export const transformCallLogMessage = (
+  message: IMessage,
+  selfXmppUsername: string
+): IMessage => {
+  if (!isCallLogMessage(message)) {return message;}
+
+  const raw = message as any;
+  const callerLocal = String(raw.callerXmppUsername || '')
+    .split('@')[0]
+    .trim();
+  const selfLocal = String(selfXmppUsername || '').split('@')[0].trim();
+  // When we know the caller, "outgoing" means we started it. With no
+  // caller info, default to incoming (safer label than claiming we dialed).
+  const isOutgoing = !!callerLocal && callerLocal === selfLocal;
+  const durationMs = Number(raw.durationMs || 0);
+  const kind: 'audio' | 'video' =
+    String(raw.kind || '').toLowerCase() === 'audio' ? 'audio' : 'video';
+
+  let body: string;
+  if (durationMs > 0) {
+    body = `${isOutgoing ? 'Outgoing' : 'Incoming'} call · ${formatCallDuration(durationMs)}`;
+  } else {
+    body = isOutgoing ? 'No answer' : 'Missed call';
+  }
+
+  const callLog: CallLogMeta = {
+    callId: String(raw.callId || raw.callid || '').trim(),
+    direction: isOutgoing ? 'outgoing' : 'incoming',
+    durationMs,
+    missed: durationMs === 0,
+    kind,
+  };
+
+  return {
+    ...message,
+    body,
+    // Render through the existing centered SystemMessage pipeline.
+    isSystemMessage: 'true',
+    callLog,
+  } as IMessage;
+};
+
+// Build a "call ended" log entry locally (client-side) when a call finishes.
+// The authoritative entry is a SERVER `call-state` broadcast, but that isn't
+// guaranteed to arrive (see header comment). This fallback keeps the chat log
+// working regardless. It's deduplicated against any server copy in
+// `addRoomMessage` by `callLog.callId` (the entry with the largest duration
+// wins), so if the server does broadcast, the two collapse into one.
+export const buildLocalCallLogMessage = (params: {
+  callId: string;
+  direction: 'outgoing' | 'incoming';
+  durationMs: number;
+  kind: 'audio' | 'video';
+  selfXmppUsername: string;
+}): IMessage => {
+  const { callId, direction, durationMs, kind, selfXmppUsername } = params;
+  const isOutgoing = direction === 'outgoing';
+  const safeDuration = Math.max(0, Math.round(durationMs || 0));
+
+  let body: string;
+  if (safeDuration > 0) {
+    body = `${isOutgoing ? 'Outgoing' : 'Incoming'} call · ${formatCallDuration(safeDuration)}`;
+  } else {
+    body = isOutgoing ? 'No answer' : 'Missed call';
+  }
+
+  const callLog: CallLogMeta = {
+    callId,
+    direction,
+    durationMs: safeDuration,
+    missed: safeDuration === 0,
+    kind,
+  };
+
+  return {
+    // Deterministic id so a re-fire for the same call collapses in place.
+    id: callId ? `calllog-${callId}` : `calllog-${Date.now()}`,
+    body,
+    date: new Date().toISOString(),
+    isSystemMessage: 'true',
+    type: 'call-state',
+    callLog,
+    user: { id: selfXmppUsername },
+  } as unknown as IMessage;
+};
+
+/**
+ * The label for a call-log entry, built at RENDER time from the callLog
+ * meta rather than read off `message.body`.
+ *
+ * transformCallLogMessage bakes an English sentence into `body` the moment
+ * the stanza arrives, which freezes the language: switch to French and
+ * every call log you already received stays English forever, because the
+ * text is data by then, not a rendering. The meta (direction/duration/
+ * missed) is the actual fact, the sentence is a view of it, so it belongs
+ * where the view is. `body` stays as the fallback for entries received
+ * before this existed, and for the notification/room-list preview paths
+ * that only have the raw message.
+ */
+export const formatCallLogLabel = (
+  callLog: CallLogMeta | undefined,
+  t: (key: string, vars?: Record<string, string | number>) => string,
+  fallbackBody = ''
+): string => {
+  if (!callLog) {return fallbackBody;}
+
+  if (!callLog.durationMs || callLog.durationMs <= 0) {
+    return callLog.direction === 'outgoing'
+      ? t('call.noAnswer')
+      : t('call.missed');
+  }
+
+  const totalSeconds = Math.max(0, Math.round(callLog.durationMs / 1000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  const duration =
+    totalSeconds < 60
+      ? t('call.durationSec', { n: totalSeconds })
+      : seconds === 0
+        ? t('call.durationMin', { n: minutes })
+        : t('call.durationMinSec', { m: minutes, s: seconds });
+
+  const direction =
+    callLog.direction === 'outgoing' ? t('call.outgoing') : t('call.incoming');
+
+  return `${direction} · ${duration}`;
+};

package/src/helpers/callPush.ts

@@ -0,0 +1,90 @@
+// Recognise and parse an *incoming call* push notification.
+//
+// Calls normally ring via a live XMPP `call-token` stanza, which only arrives
+// while the socket is connected. On mobile the socket is dead whenever the OS
+// backgrounds or kills the app, so the backend also delivers the call over
+// push, in the same `data`-payload format as message pushes. This helper lets
+// the push layer tell a call push apart from a chat push and pull the call
+// fields out, tolerating the field-name variations backends tend to use.
+
+export interface ParsedCallPush {
+  callId: string | null;
+  /** LiveKit token, if the push carried one (lets us ring + accept offline). */
+  token: string | null;
+  kind: 'audio' | 'video';
+  /** Bare room name (JID localpart) the call belongs to. */
+  roomBareName: string | null;
+  /** Raw room reference from the payload (full JID or bare name). */
+  roomRef: string | null;
+  /** Display name for the ring screen (caller). */
+  callerName: string | null;
+  /** Caller's xmpp localpart, when provided. */
+  callerXmppUsername: string | null;
+}
+
+const pick = (data: Record<string, any>, keys: string[]): string => {
+  for (const k of keys) {
+    const v = data?.[k];
+    if (v !== undefined && v !== null && String(v).trim() !== '') {
+      return String(v).trim();
+    }
+  }
+  return '';
+};
+
+/**
+ * True when a push `data` payload represents an incoming call. Matches on an
+ * explicit call marker (`type`/`pushType`/`category`/`event` === "call"-ish)
+ * or on a callId paired with a call-specific field, so a normal message push
+ * is never misread as a call.
+ */
+export const isCallPush = (
+  data: Record<string, any> | null | undefined
+): boolean => {
+  if (!data) {return false;}
+  const marker = pick(data, [
+    'type',
+    'pushType',
+    'category',
+    'messageType',
+    'event',
+  ]).toLowerCase();
+  if (
+    marker === 'call' ||
+    marker === 'incoming-call' ||
+    marker === 'call-token' ||
+    marker === 'call-invite'
+  ) {
+    return true;
+  }
+  const callId = pick(data, ['callId', 'callid', 'callID']);
+  const hasCallField =
+    !!pick(data, ['callToken', 'livekitToken']) ||
+    !!pick(data, ['callKind']) ||
+    pick(data, ['kind']).toLowerCase() === 'audio' ||
+    pick(data, ['kind']).toLowerCase() === 'video';
+  return !!callId && hasCallField;
+};
+
+export const parseCallPush = (
+  data: Record<string, any> | null | undefined
+): ParsedCallPush => {
+  const d = data || {};
+  const roomRef =
+    pick(d, ['callRoom', 'room', 'roomJid', 'jid', 'chatId']) || null;
+  const roomBareName = roomRef ? roomRef.split('@')[0] || roomRef : null;
+  const kindRaw = pick(d, ['callKind', 'kind']).toLowerCase();
+  return {
+    callId: pick(d, ['callId', 'callid', 'callID']) || null,
+    token: pick(d, ['callToken', 'livekitToken', 'token']) || null,
+    kind: kindRaw === 'audio' ? 'audio' : 'video',
+    roomBareName,
+    roomRef,
+    callerName:
+      pick(d, ['callerName', 'callerDisplayName', 'senderName', 'title']) ||
+      null,
+    callerXmppUsername:
+      pick(d, ['callerXmppUsername', 'callerUsername', 'userJid', 'senderJid'])
+        .split('@')[0] || null,
+  };
+};