@poolse/react-native 2.6.0 → 2.7.0

package/dist/index.d.cts

@@ -1095,6 +1095,16 @@ interface CallScreenProps {
      * {@link VoiceRoomBarProps.onStatusChange}.
      */
     onStatusChange?: (status: VoiceStatus) => void;
+    /**
+     * Hide this screen while a call is merely ringing in.
+     *
+     * Set it when `useVoipCalls` is wired: CallKit already shows the
+     * system call UI on the lock screen and in the Dynamic Island, and a
+     * second in-app sheet on top of it means one tap of Call produces two
+     * competing rings. The screen still appears once the call connects, to
+     * carry the in-call controls.
+     */
+    nativeIncomingUi?: boolean;
 }
 /**
  * WhatsApp-style call UI: a full-screen sheet that covers the app while
@@ -1111,58 +1121,58 @@ interface CallScreenProps {
  * to whatever button your UI wants. Pass the same instance in via
  * `calls` so both halves share one state machine.
  */
-declare function CallScreen({ userId, labelFor, calls: external, webrtc, onStatusChange, }: CallScreenProps): react_jsx_runtime.JSX.Element;
+declare function CallScreen({ userId, labelFor, calls: external, webrtc, onStatusChange, nativeIncomingUi, }: CallScreenProps): react_jsx_runtime.JSX.Element;
 
 /**
- * Bridges iOS PushKit + CallKit to poolse calls, so a call rings a
- * backgrounded or closed app.
+ * Bridges iOS PushKit + CallKit to poolse calls, and owns the incoming
+ * call UI end to end.
+ *
+ * ## Why this coordinates rather than just forwards
  *
- * ## Why this is needed at all
+ * A call arrives by two routes: `call:incoming` over the WebSocket when
+ * the app is foregrounded, and a VoIP push when it isn't. The server
+ * fires both, always — deciding server-side whether a socket is really
+ * alive is a race it would lose.
  *
- * `call:incoming` travels over the WebSocket, which only exists while
- * the app is foregrounded — iOS suspends sockets on background and
- * drops them on close. Reaching a sleeping phone requires the OS to wake
- * the app, which means a VoIP push against a PushKit token.
+ * Reconciling them is therefore the client's job, and doing it badly is
+ * very visible: forward each route to its own UI and one tap of Call
+ * shows the callee two rings, an in-app sheet fighting a system call
+ * screen.
+ *
+ * So this hook is the single place a call becomes visible. Both routes
+ * feed one map keyed by `callId`, CallKit is the only ring UI, and the
+ * native call is torn down whenever the call reaches a terminal state —
+ * declined, cancelled, timed out, answered. Pass the same `calls` object
+ * to `<CallScreen>` and it stays out of the way while a ring is up.
  *
  * ## The rule Apple enforces
  *
  * Every delivered VoIP push MUST report an incoming call to CallKit,
  * essentially immediately. Miss it and iOS terminates the app; do it
- * repeatedly and the system stops delivering VoIP pushes to you at all.
- * `reportCall` below is not optional politeness — it is the contract.
+ * repeatedly and the system stops delivering VoIP pushes at all.
  *
  * ## Dependencies
  *
  * `react-native-voip-push-notification` and `react-native-callkeep`,
- * both native, both requiring a development build. Like
- * `react-native-webrtc`, Metro only bundles what it can see statically,
- * so YOUR APP imports them and passes them in:
- *
- *     import VoipPushNotification from 'react-native-voip-push-notification';
- *     import RNCallKeep from 'react-native-callkeep';
+ * both native and both requiring a development build. Metro only bundles
+ * what it can see statically, so YOUR APP imports them and passes them
+ * in. The iOS AppDelegate also needs PushKit delegate methods, which
+ * Expo does not generate — see the sample's `plugins/withVoipPush.js`.
  *
  *     useVoipCalls({
  *       voipPush: VoipPushNotification,
  *       callKeep: RNCallKeep,
- *       onAnswer: (call) => { ... },
+ *       calls,                       // the same useCalls() the UI uses
+ *       apnsEnvironment: 'sandbox',
  *     });
  */
-/**
- * The slice of `react-native-voip-push-notification` used here.
- *
- * Loose on purpose. The real module types `addEventListener` as a
- * generic whose handler payload varies per event, and pinning exact
- * signatures here makes `voipPush={VoipPushNotification}` fail to
- * compile — the prop becomes unusable, which is the whole point of it.
- * Method syntax (not property arrow syntax) keeps the check bivariant.
- */
+/** The slice of `react-native-voip-push-notification` used here. */
 interface VoipPushModule {
     addEventListener(event: string, handler: (payload: unknown) => void): void;
     removeEventListener(event: string): void;
     registerVoipToken(): void;
 }
-/** The slice of `react-native-callkeep` used here. Loose for the same
- *  reason — `setup` resolves to a boolean in the real module. */
+/** The slice of `react-native-callkeep` used here. */
 interface CallKeepModule {
     setup(options: unknown): Promise<unknown>;
     displayIncomingCall(uuid: string, handle: string, localizedCallerName?: string, handleType?: string, hasVideo?: boolean): unknown;
@@ -1181,12 +1191,15 @@ interface UseVoipCallsOptions {
     voipPush: VoipPushModule;
     callKeep: CallKeepModule;
     /**
-     * Fired when the user answers from the native call UI. Accept the
-     * call and join the room here — the app may have been launched cold,
-     * so don't assume any prior state.
+     * The `useCalls(...)` instance driving this screen. Supplying it lets
+     * the hook answer, decline and dismiss through the same state machine
+     * the UI uses, rather than two halves disagreeing about what is
+     * happening.
      */
+    calls?: UseCalls;
+    /** Called when the user answers from the native call UI. */
     onAnswer?: (call: VoipIncomingCall) => void;
-    /** Fired when the user declines from the native call UI. */
+    /** Called when the user declines from the native call UI. */
     onDecline?: (call: VoipIncomingCall) => void;
     /** CallKit display name for your app. Shown on the lock screen. */
     appName?: string;
@@ -1203,13 +1216,23 @@ interface UseVoipCallsOptions {
      * rings — with nothing in the app to suggest why.
      */
     apnsEnvironment?: 'production' | 'sandbox';
+    /**
+     * How old a pushed call may be before it is ignored, in ms. Defaults
+     * to 45s, matching `useCalls`' ring timeout — past that the caller has
+     * already given up, so there is nothing live to answer.
+     *
+     * PushKit holds a push that lands before the JS bundle is up and
+     * replays it on launch, so opening the app can ring you for a call the
+     * caller hung up on minutes ago — a ring with nothing live to accept.
+     */
+    staleAfterMs?: number;
 }
 /**
- * Registers this device for VoIP pushes and wires the native call UI.
+ * Registers this device for VoIP pushes and drives the native call UI.
  *
- * Safe to mount once at the app root. Does nothing on Android, which
- * needs a separate FCM + ConnectionService integration.
+ * Mount once, as high in the signed-in tree as possible. Does nothing on
+ * Android, which needs a separate FCM + ConnectionService integration.
  */
-declare function useVoipCalls({ voipPush, callKeep, onAnswer, onDecline, appName, apnsEnvironment, }: UseVoipCallsOptions): void;
+declare function useVoipCalls({ voipPush, callKeep, calls, onAnswer, onDecline, appName, apnsEnvironment, staleAfterMs, }: UseVoipCallsOptions): void;
 
 export { AttachmentPicker, type AttachmentPickerProps, AttachmentPreview, type AttachmentPreviewProps, Avatar, type AvatarProps, type CallKeepModule, CallScreen, type CallScreenProps, ChatHeader, type ChatHeaderProps, ConversationList, type ConversationListProps, ConversationView, type ConversationViewProps, DaySeparator, type DaySeparatorProps, GroupDetailsSheet, type GroupDetailsSheetProps, type IconName, ImageMosaic, type ImageMosaicProps, type InboxUser, MemberList, type MemberListProps, MentionInput, type MentionInputProps, MessageActions, type MessageActionsProps, MessageBubble, type MessageBubbleProps, MessageComposer, type MessageComposerProps, MessageList, type MessageListItem, type MessageListProps, MessageRow, type MessageRowProps, type NativeWebRtcModule, PoolseIcon, type PoolseIconProps, PoolseInbox, type PoolseInboxHandle, type PoolseInboxProps, PoolseLogo, type PoolseLogoProps, type PoolseLogoVariant, type PoolseRNTheme, type PoolseRNThemeOverrides, PoolseTheme, type PoolseThemeProps, primitives as Primitives, ReactionPicker, type ReactionPickerProps, ReactionStrip, type ReactionStripProps, type ThemeColors, type ThemeRadii, type ThemeShadows, type ThemeSpacing, type ThemeType, ThreadView, type ThreadViewProps, TypingIndicator, type TypingIndicatorProps, UploadQueueStrip, type UseVoipCallsOptions, UserName, type UserNameProps, VoiceRoomBar, type VoiceRoomBarProps, type VoipIncomingCall, type VoipPushModule, createNativeWebRtcAdapter, defaultDarkTheme, defaultLightTheme, isNativeWebRtcAvailable, useAppStateLifecycle, useDisplayName, usePoolseTheme, useVoipCalls };

package/dist/index.d.ts

@@ -1095,6 +1095,16 @@ interface CallScreenProps {
      * {@link VoiceRoomBarProps.onStatusChange}.
      */
     onStatusChange?: (status: VoiceStatus) => void;
+    /**
+     * Hide this screen while a call is merely ringing in.
+     *
+     * Set it when `useVoipCalls` is wired: CallKit already shows the
+     * system call UI on the lock screen and in the Dynamic Island, and a
+     * second in-app sheet on top of it means one tap of Call produces two
+     * competing rings. The screen still appears once the call connects, to
+     * carry the in-call controls.
+     */
+    nativeIncomingUi?: boolean;
 }
 /**
  * WhatsApp-style call UI: a full-screen sheet that covers the app while
@@ -1111,58 +1121,58 @@ interface CallScreenProps {
  * to whatever button your UI wants. Pass the same instance in via
  * `calls` so both halves share one state machine.
  */
-declare function CallScreen({ userId, labelFor, calls: external, webrtc, onStatusChange, }: CallScreenProps): react_jsx_runtime.JSX.Element;
+declare function CallScreen({ userId, labelFor, calls: external, webrtc, onStatusChange, nativeIncomingUi, }: CallScreenProps): react_jsx_runtime.JSX.Element;
 
 /**
- * Bridges iOS PushKit + CallKit to poolse calls, so a call rings a
- * backgrounded or closed app.
+ * Bridges iOS PushKit + CallKit to poolse calls, and owns the incoming
+ * call UI end to end.
+ *
+ * ## Why this coordinates rather than just forwards
  *
- * ## Why this is needed at all
+ * A call arrives by two routes: `call:incoming` over the WebSocket when
+ * the app is foregrounded, and a VoIP push when it isn't. The server
+ * fires both, always — deciding server-side whether a socket is really
+ * alive is a race it would lose.
  *
- * `call:incoming` travels over the WebSocket, which only exists while
- * the app is foregrounded — iOS suspends sockets on background and
- * drops them on close. Reaching a sleeping phone requires the OS to wake
- * the app, which means a VoIP push against a PushKit token.
+ * Reconciling them is therefore the client's job, and doing it badly is
+ * very visible: forward each route to its own UI and one tap of Call
+ * shows the callee two rings, an in-app sheet fighting a system call
+ * screen.
+ *
+ * So this hook is the single place a call becomes visible. Both routes
+ * feed one map keyed by `callId`, CallKit is the only ring UI, and the
+ * native call is torn down whenever the call reaches a terminal state —
+ * declined, cancelled, timed out, answered. Pass the same `calls` object
+ * to `<CallScreen>` and it stays out of the way while a ring is up.
  *
  * ## The rule Apple enforces
  *
  * Every delivered VoIP push MUST report an incoming call to CallKit,
  * essentially immediately. Miss it and iOS terminates the app; do it
- * repeatedly and the system stops delivering VoIP pushes to you at all.
- * `reportCall` below is not optional politeness — it is the contract.
+ * repeatedly and the system stops delivering VoIP pushes at all.
  *
  * ## Dependencies
  *
  * `react-native-voip-push-notification` and `react-native-callkeep`,
- * both native, both requiring a development build. Like
- * `react-native-webrtc`, Metro only bundles what it can see statically,
- * so YOUR APP imports them and passes them in:
- *
- *     import VoipPushNotification from 'react-native-voip-push-notification';
- *     import RNCallKeep from 'react-native-callkeep';
+ * both native and both requiring a development build. Metro only bundles
+ * what it can see statically, so YOUR APP imports them and passes them
+ * in. The iOS AppDelegate also needs PushKit delegate methods, which
+ * Expo does not generate — see the sample's `plugins/withVoipPush.js`.
  *
  *     useVoipCalls({
  *       voipPush: VoipPushNotification,
  *       callKeep: RNCallKeep,
- *       onAnswer: (call) => { ... },
+ *       calls,                       // the same useCalls() the UI uses
+ *       apnsEnvironment: 'sandbox',
  *     });
  */
-/**
- * The slice of `react-native-voip-push-notification` used here.
- *
- * Loose on purpose. The real module types `addEventListener` as a
- * generic whose handler payload varies per event, and pinning exact
- * signatures here makes `voipPush={VoipPushNotification}` fail to
- * compile — the prop becomes unusable, which is the whole point of it.
- * Method syntax (not property arrow syntax) keeps the check bivariant.
- */
+/** The slice of `react-native-voip-push-notification` used here. */
 interface VoipPushModule {
     addEventListener(event: string, handler: (payload: unknown) => void): void;
     removeEventListener(event: string): void;
     registerVoipToken(): void;
 }
-/** The slice of `react-native-callkeep` used here. Loose for the same
- *  reason — `setup` resolves to a boolean in the real module. */
+/** The slice of `react-native-callkeep` used here. */
 interface CallKeepModule {
     setup(options: unknown): Promise<unknown>;
     displayIncomingCall(uuid: string, handle: string, localizedCallerName?: string, handleType?: string, hasVideo?: boolean): unknown;
@@ -1181,12 +1191,15 @@ interface UseVoipCallsOptions {
     voipPush: VoipPushModule;
     callKeep: CallKeepModule;
     /**
-     * Fired when the user answers from the native call UI. Accept the
-     * call and join the room here — the app may have been launched cold,
-     * so don't assume any prior state.
+     * The `useCalls(...)` instance driving this screen. Supplying it lets
+     * the hook answer, decline and dismiss through the same state machine
+     * the UI uses, rather than two halves disagreeing about what is
+     * happening.
      */
+    calls?: UseCalls;
+    /** Called when the user answers from the native call UI. */
     onAnswer?: (call: VoipIncomingCall) => void;
-    /** Fired when the user declines from the native call UI. */
+    /** Called when the user declines from the native call UI. */
     onDecline?: (call: VoipIncomingCall) => void;
     /** CallKit display name for your app. Shown on the lock screen. */
     appName?: string;
@@ -1203,13 +1216,23 @@ interface UseVoipCallsOptions {
      * rings — with nothing in the app to suggest why.
      */
     apnsEnvironment?: 'production' | 'sandbox';
+    /**
+     * How old a pushed call may be before it is ignored, in ms. Defaults
+     * to 45s, matching `useCalls`' ring timeout — past that the caller has
+     * already given up, so there is nothing live to answer.
+     *
+     * PushKit holds a push that lands before the JS bundle is up and
+     * replays it on launch, so opening the app can ring you for a call the
+     * caller hung up on minutes ago — a ring with nothing live to accept.
+     */
+    staleAfterMs?: number;
 }
 /**
- * Registers this device for VoIP pushes and wires the native call UI.
+ * Registers this device for VoIP pushes and drives the native call UI.
  *
- * Safe to mount once at the app root. Does nothing on Android, which
- * needs a separate FCM + ConnectionService integration.
+ * Mount once, as high in the signed-in tree as possible. Does nothing on
+ * Android, which needs a separate FCM + ConnectionService integration.
  */
-declare function useVoipCalls({ voipPush, callKeep, onAnswer, onDecline, appName, apnsEnvironment, }: UseVoipCallsOptions): void;
+declare function useVoipCalls({ voipPush, callKeep, calls, onAnswer, onDecline, appName, apnsEnvironment, staleAfterMs, }: UseVoipCallsOptions): void;
 
 export { AttachmentPicker, type AttachmentPickerProps, AttachmentPreview, type AttachmentPreviewProps, Avatar, type AvatarProps, type CallKeepModule, CallScreen, type CallScreenProps, ChatHeader, type ChatHeaderProps, ConversationList, type ConversationListProps, ConversationView, type ConversationViewProps, DaySeparator, type DaySeparatorProps, GroupDetailsSheet, type GroupDetailsSheetProps, type IconName, ImageMosaic, type ImageMosaicProps, type InboxUser, MemberList, type MemberListProps, MentionInput, type MentionInputProps, MessageActions, type MessageActionsProps, MessageBubble, type MessageBubbleProps, MessageComposer, type MessageComposerProps, MessageList, type MessageListItem, type MessageListProps, MessageRow, type MessageRowProps, type NativeWebRtcModule, PoolseIcon, type PoolseIconProps, PoolseInbox, type PoolseInboxHandle, type PoolseInboxProps, PoolseLogo, type PoolseLogoProps, type PoolseLogoVariant, type PoolseRNTheme, type PoolseRNThemeOverrides, PoolseTheme, type PoolseThemeProps, primitives as Primitives, ReactionPicker, type ReactionPickerProps, ReactionStrip, type ReactionStripProps, type ThemeColors, type ThemeRadii, type ThemeShadows, type ThemeSpacing, type ThemeType, ThreadView, type ThreadViewProps, TypingIndicator, type TypingIndicatorProps, UploadQueueStrip, type UseVoipCallsOptions, UserName, type UserNameProps, VoiceRoomBar, type VoiceRoomBarProps, type VoipIncomingCall, type VoipPushModule, createNativeWebRtcAdapter, defaultDarkTheme, defaultLightTheme, isNativeWebRtcAvailable, useAppStateLifecycle, useDisplayName, usePoolseTheme, useVoipCalls };

package/dist/index.js

@@ -5088,7 +5088,8 @@ function CallScreen({
   labelFor,
   calls: external,
   webrtc,
-  onStatusChange
+  onStatusChange,
+  nativeIncomingUi = false
 }) {
   const theme = usePoolseTheme();
   const own = useCalls(external ? null : userId);
@@ -5109,7 +5110,8 @@ function CallScreen({
     onStatusChange?.(voice.status);
   }, [voice.status, onStatusChange]);
   const label = labelFor ?? ((id) => `User ${id.slice(0, 6)}`);
-  const visible = calls.phase !== "idle";
+  const ringingIn = calls.phase === "ringing-in";
+  const visible = calls.phase !== "idle" && !(nativeIncomingUi && ringingIn);
   const hangUp = () => {
     voice.leave();
     calls.reset();
@@ -5210,29 +5212,50 @@ var styles24 = StyleSheet.create({
 function useVoipCalls({
   voipPush,
   callKeep,
+  calls,
   onAnswer,
   onDecline,
   appName = "poolse",
-  apnsEnvironment
+  apnsEnvironment,
+  staleAfterMs = 45e3
 }) {
   const poolse = usePoolse();
-  const pending = useRef(/* @__PURE__ */ new Map());
-  const handlers = useRef({ onAnswer, onDecline });
-  handlers.current = { onAnswer, onDecline };
+  const shown = useRef(/* @__PURE__ */ new Map());
+  const seen = useRef(/* @__PURE__ */ new Set());
+  const handlers = useRef({ onAnswer, onDecline, calls });
+  handlers.current = { onAnswer, onDecline, calls };
+  const staleRef = useRef(staleAfterMs);
+  staleRef.current = staleAfterMs;
+  const dismiss = useRef((callId) => {
+    if (!shown.current.has(callId)) return;
+    shown.current.delete(callId);
+    try {
+      callKeep.endCall(callId);
+    } catch {
+    }
+  });
+  const present = useRef((call, sentAt) => {
+    if (seen.current.has(call.callId)) return;
+    if (typeof sentAt === "number" && Date.now() - sentAt > staleRef.current) return;
+    seen.current.add(call.callId);
+    shown.current.set(call.callId, call);
+    callKeep.displayIncomingCall(call.callId, call.callerUserId, call.callerName, "generic", false);
+  });
   useEffect(() => {
     let cancelled = false;
-    const reportCall = (payload) => {
+    const fromPush = (payload) => {
       const callId = payload.call_id;
       const conversationId = payload.conversation_id;
       if (!callId || !conversationId) return;
-      const call = {
-        callId,
-        conversationId,
-        callerUserId: payload.caller_user_id ?? "",
-        callerName: payload.caller_name ?? "Incoming call"
-      };
-      pending.current.set(callId, call);
-      callKeep.displayIncomingCall(callId, call.callerUserId, call.callerName, "generic", false);
+      present.current(
+        {
+          callId,
+          conversationId,
+          callerUserId: payload.caller_user_id ?? "",
+          callerName: payload.caller_name ?? "Incoming call"
+        },
+        payload.sent_at
+      );
     };
     void callKeep.setup({
       ios: { appName },
@@ -5255,23 +5278,36 @@ function useVoipCalls({
       });
     }));
     voipPush.addEventListener("notification", ((payload) => {
-      reportCall(payload);
+      fromPush(payload);
     }));
     voipPush.addEventListener("didLoadWithEvents", ((events) => {
       for (const event of events ?? []) {
         if (event.name === "RNVoipPushRemoteNotificationReceivedEvent") {
-          reportCall(event.data);
+          fromPush(event.data);
         }
       }
     }));
     callKeep.addEventListener("answerCall", (({ callUUID }) => {
-      const call = pending.current.get(callUUID);
-      if (call) handlers.current.onAnswer?.(call);
+      const call = shown.current.get(callUUID);
+      if (!call) return;
+      shown.current.delete(callUUID);
+      void handlers.current.calls?.accept({
+        callId: call.callId,
+        conversationId: call.conversationId,
+        callerUserId: call.callerUserId
+      });
+      handlers.current.onAnswer?.(call);
     }));
     callKeep.addEventListener("endCall", (({ callUUID }) => {
-      const call = pending.current.get(callUUID);
-      pending.current.delete(callUUID);
-      if (call) handlers.current.onDecline?.(call);
+      const call = shown.current.get(callUUID);
+      shown.current.delete(callUUID);
+      if (!call) return;
+      void handlers.current.calls?.decline({
+        callId: call.callId,
+        conversationId: call.conversationId,
+        callerUserId: call.callerUserId
+      });
+      handlers.current.onDecline?.(call);
     }));
     voipPush.registerVoipToken();
     return () => {
@@ -5283,6 +5319,22 @@ function useVoipCalls({
       callKeep.removeEventListener("endCall");
     };
   }, [poolse, voipPush, callKeep, appName, apnsEnvironment]);
+  const incoming = calls?.incoming ?? null;
+  const phase = calls?.phase;
+  useEffect(() => {
+    if (phase === "ringing-in" && incoming) {
+      present.current({
+        callId: incoming.callId,
+        conversationId: incoming.conversationId,
+        callerUserId: incoming.callerUserId,
+        callerName: incoming.callerUserId
+      });
+    }
+  }, [phase, incoming]);
+  useEffect(() => {
+    if (phase === "ringing-in" || phase === "ringing-out") return;
+    for (const callId of [...shown.current.keys()]) dismiss.current(callId);
+  }, [phase]);
 }
 function guessApnsEnvironment() {
   return __DEV__ ? "sandbox" : "production";