@nativetalkcommunications/react-native-call-sdk 0.1.0

package/lib/module/CallProvider.js

@@ -0,0 +1,573 @@
+/**
+ * <CallProvider> — the single React component the host app mounts to enable
+ * calling. It wires the native event stream into React state and exposes
+ * everything through `useCall()`.
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ *  Mental model
+ * ──────────────────────────────────────────────────────────────────────────
+ *
+ *   Linphone Core  ──events──►  Native module  ──RN bridge──►  CallProvider
+ *        ▲                                                          │
+ *        │                                                          ▼
+ *        └────── method calls (dial/answer/end) ────────────  useCall() hook
+ *
+ *  - The Linphone `Core` is the single source of truth for "what state is the
+ *    call in". CallProvider just mirrors that state into React.
+ *  - Provider → native flows via plain method calls. Native → provider flows
+ *    via NativeEventEmitter events (RegistrationChanged, CallIncoming, etc.).
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ *  Design rules
+ * ──────────────────────────────────────────────────────────────────────────
+ *  - No coupling to auth, navigation, or any specific HTTP client. SIP config
+ *    is passed in as a prop; lifecycle events (incoming, ended) are exposed as
+ *    callbacks so the host app decides how to navigate / display screens.
+ *  - Safe to mount with `config={null}` while you fetch credentials — the SDK
+ *    simply idles until a real config arrives, then auto-registers (unless
+ *    `autoRegister={false}`).
+ *  - All event callbacks are read through refs (see `*Ref` block) so the host
+ *    app can pass fresh closures on every render WITHOUT re-subscribing the
+ *    native events — that would drop in-flight calls during a re-render.
+ */
+import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
+import { Platform } from 'react-native';
+import { callStateName, callStatusLabel, destinationToSipUri, formatDuration, formatTenantDomain, initialsFrom, parseSipUser, regStateName, } from './helpers';
+import * as Native from './native';
+const CallContext = createContext(null);
+// ── State-group lookups for the call lifecycle FSM ────────────────────────
+//
+// Linphone exposes ~20 fine-grained call states. The UI only cares about a
+// handful of behavioural buckets, so we precompute them here and look them
+// up in O(1) inside the CallState event handler.
+//
+//   ACTIVE   → audio is flowing; start the duration timer
+//   TERMINAL → call is gone; freeze the timer & reset audio toggles
+//   HELD     → on hold (initiated by us OR by the remote peer)
+//   RESUMED  → coming out of hold OR media flowing again
+//
+// Note: `Connected` and `StreamsRunning` appear in BOTH active and resumed —
+// they're listed twice on purpose. "Active" treats them as "start timer";
+// "Resumed" treats them as "clear the held flag".
+const ACTIVE_STATES = ['Connected', 'StreamsRunning'];
+const TERMINAL_STATES = [
+    'End',
+    'Released',
+    'Error', // SIP error (busy, not-found, network drop, etc.)
+];
+const HELD_STATES = [
+    'Pausing',
+    'Paused',
+    'PausedByRemote', // peer put us on hold
+];
+const RESUMED_STATES = [
+    'Resuming',
+    'Connected',
+    'StreamsRunning',
+];
+export function CallProvider(props) {
+    const { children, config = null, autoRegister = true, enableNativeServices = true, requestMicPermission = true, onIncomingCall, onOutgoingCall, onCallEnded, onCallStateChanged, onRegistrationStateChanged, onError, } = props;
+    // ── Stable refs for the event callbacks ──────────────────────────────────
+    //
+    // The host app typically passes inline arrow functions:
+    //
+    //     <CallProvider onIncomingCall={(i) => navigation.navigate(…)} />
+    //
+    // Each render produces a NEW function identity. If we depended on these
+    // directly in the subscription useEffect, every render would tear down the
+    // native event subscriptions and re-create them — guaranteed to drop
+    // events that happen mid-render. So we mirror them into refs and let the
+    // event handlers read `.current` at fire time.
+    //
+    // The trailing `useEffect` (no deps array) runs after every commit, which
+    // keeps `current` aligned with the latest props.
+    const onIncomingCallRef = useRef(onIncomingCall);
+    const onOutgoingCallRef = useRef(onOutgoingCall);
+    const onCallEndedRef = useRef(onCallEnded);
+    const onCallStateChangedRef = useRef(onCallStateChanged);
+    const onRegistrationStateChangedRef = useRef(onRegistrationStateChanged);
+    const onErrorRef = useRef(onError);
+    useEffect(() => {
+        onIncomingCallRef.current = onIncomingCall;
+        onOutgoingCallRef.current = onOutgoingCall;
+        onCallEndedRef.current = onCallEnded;
+        onCallStateChangedRef.current = onCallStateChanged;
+        onRegistrationStateChangedRef.current = onRegistrationStateChanged;
+        onErrorRef.current = onError;
+    });
+    // ----- State -----
+    const [registration, setRegistration] = useState(null);
+    const [callStatus, setCallStatus] = useState('Idle');
+    const [incoming, setIncoming] = useState(false);
+    const [incomingInfo, setIncomingInfo] = useState(null);
+    const [muted, setMuted] = useState(false);
+    const [speakerOn, setSpeakerOn] = useState(false);
+    const [held, setHeld] = useState(false);
+    const [durationSec, setDurationSec] = useState(0);
+    const [ending, setEnding] = useState(false);
+    // ── Duration timer ────────────────────────────────────────────────────────
+    //
+    // We anchor the timer to a wall-clock timestamp (`startTsRef`) rather than
+    // incrementing a counter. Why? `setInterval` drifts when the device is
+    // backgrounded, the JS thread stalls, or the user switches apps. By
+    // re-computing `now - start` on every tick we always show the true elapsed
+    // time, even if 30 intervals were skipped while the screen was off.
+    //
+    // The 500ms tick is half a second of "lag" worst-case but spares the JS
+    // thread the overhead of a 30Hz refresh — UI just renders to second
+    // precision anyway.
+    const tickRef = useRef(null);
+    const startTsRef = useRef(null);
+    const clearTimer = useCallback(() => {
+        if (tickRef.current)
+            clearInterval(tickRef.current);
+        tickRef.current = null;
+    }, []);
+    // Called when a new call starts — wipes the previous duration so the UI
+    // doesn't briefly show the old call's timer.
+    const resetDuration = useCallback(() => {
+        clearTimer();
+        startTsRef.current = null;
+        setDurationSec(0);
+    }, [clearTimer]);
+    // Idempotent: calling startDuration() multiple times during the same call
+    // doesn't restart the clock. This matters because Linphone can fire
+    // `Connected` and `StreamsRunning` back-to-back, and we'd otherwise reset
+    // the start time on the second event.
+    const startDuration = useCallback(() => {
+        if (tickRef.current)
+            return;
+        startTsRef.current = Date.now();
+        tickRef.current = setInterval(() => {
+            if (startTsRef.current != null) {
+                setDurationSec((Date.now() - startTsRef.current) / 1000);
+            }
+        }, 500);
+    }, []);
+    // ── Initial boot sequence: native init → mic permission → services ──────
+    //
+    // Order matters:
+    //   1. Native.init() — boots the Linphone Core. Required before anything
+    //      else; safe to call multiple times (the native side is idempotent).
+    //   2. Mic permission — Linphone won't open the mic without it. We do this
+    //      eagerly so the user is prompted once on first launch rather than
+    //      mid-call. Set `requestMicPermission={false}` to skip and handle it
+    //      yourself.
+    //   3. Background service (Android only) — keeps the SIP socket alive when
+    //      the app is backgrounded. On iOS this is the host app's job via
+    //      VoIP push, so the call is a no-op.
+    //
+    // `cancelled` guards against the provider unmounting mid-await. Without
+    // it, a fast remount-then-unmount could fire `onError` callbacks against
+    // a stale provider instance.
+    useEffect(() => {
+        let cancelled = false;
+        (async () => {
+            try {
+                await Native.init();
+                if (cancelled)
+                    return;
+                if (requestMicPermission) {
+                    const granted = await Native.ensureMicPermission();
+                    if (!granted) {
+                        onErrorRef.current?.({
+                            code: 'MIC_PERMISSION_DENIED',
+                            message: 'Microphone permission denied. Calls cannot be made or received.',
+                        });
+                    }
+                }
+                if (enableNativeServices && Platform.OS === 'android') {
+                    Native.startNativeServices();
+                }
+            }
+            catch (e) {
+                onErrorRef.current?.({
+                    code: 'INIT_FAILED',
+                    message: e?.message ?? String(e),
+                });
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [enableNativeServices, requestMicPermission]);
+    // ── Native event subscriptions ───────────────────────────────────────────
+    //
+    // This effect runs once and never re-runs (its deps array contains only
+    // stable useCallback refs). All five events from the native module are
+    // bridged into React state here:
+    //
+    //   RegistrationChanged  → setRegistration + onRegistrationStateChanged
+    //   CallIncoming         → setIncoming(true) + onIncomingCall
+    //   CallState            → setCallStatus + timer/hold/cleanup based on FSM
+    //   CallEnded            → reset transient state + onCallEnded
+    //
+    // The cleanup function removes all subscriptions on unmount. Critically,
+    // we DO NOT call `Native.stopNativeServices()` here — that would kill the
+    // foreground service even on a transient unmount. Apps that want to fully
+    // shut down call functionality (e.g. on logout) should call
+    // `stopNativeServices(true)` explicitly via the hook.
+    useEffect(() => {
+        // Registration state changes — `progress`, `ok`, `failed`, etc.
+        // `regStateName()` normalises the raw value to a canonical lowercase
+        // string. We surface `failed` as a structured error so the host app can
+        // distinguish "user hasn't logged in yet" from "credentials are bad".
+        const subReg = Native.on.RegistrationChanged((e) => {
+            const pretty = regStateName(e?.state);
+            const event = { ...e, state: pretty, pretty };
+            setRegistration(event);
+            onRegistrationStateChangedRef.current?.(event);
+            if (pretty === 'failed') {
+                onErrorRef.current?.({
+                    code: 'REGISTRATION_FAILED',
+                    message: e?.message || 'SIP registration failed',
+                });
+            }
+        });
+        // Incoming call — pick the best display name we have. SIP can deliver
+        // any of: displayName ("Jane Doe"), username ("100"), or full URI
+        // ("sip:+234…@gateway"). Some servers send "anonymous" as the display
+        // name when caller-ID is suppressed; we treat that as missing and fall
+        // back to the username instead.
+        const subIncoming = Native.on.CallIncoming((e = {}) => {
+            const display = (e.displayName || '').trim();
+            const user = (e.username || '').trim();
+            const parsed = parseSipUser(e.uri || '');
+            const phone = display && display.toLowerCase() !== 'anonymous'
+                ? display
+                : user || parsed || 'Unknown';
+            const info = {
+                name: phone,
+                phone,
+                initials: initialsFrom(phone),
+                callId: e?.callId,
+                uri: e?.uri,
+            };
+            setIncoming(true);
+            setIncomingInfo(info);
+            setCallStatus('IncomingReceived');
+            onIncomingCallRef.current?.(info);
+        });
+        // Generic call state transitions — drives the FSM defined at the top of
+        // the file. The four set-membership checks below are mutually exclusive
+        // for any single event (e.g. a state can't be both ACTIVE and TERMINAL),
+        // so the if-chain is intentional, not a fall-through bug.
+        const subState = Native.on.CallState((e) => {
+            const pretty = callStateName(e?.state);
+            setCallStatus(pretty);
+            onCallStateChangedRef.current?.(pretty);
+            if (HELD_STATES.includes(pretty))
+                setHeld(true);
+            if (RESUMED_STATES.includes(pretty))
+                setHeld(false);
+            if (ACTIVE_STATES.includes(pretty)) {
+                // Media is flowing. If this was an incoming call, clear the
+                // "ringing" flag so the UI moves from incoming-screen → in-call.
+                setIncoming(false);
+                startDuration();
+            }
+            if (TERMINAL_STATES.includes(pretty)) {
+                // Freeze the duration (don't reset to 0) so the UI can show
+                // "Call ended · 2:34" for a moment before navigation pops the
+                // screen. Audio toggles reset because they don't persist across
+                // calls — mute is per-session.
+                clearTimer();
+                setIncoming(false);
+                setIncomingInfo(null);
+                setMuted(false);
+                setSpeakerOn(false);
+            }
+        });
+        // CallEnded fires AFTER the CallState transition to End/Released. It's
+        // a convenience event — listeners that only care about "call is gone"
+        // can subscribe to this without parsing every state transition.
+        const subEnd = Native.on.CallEnded(() => {
+            clearTimer();
+            setIncoming(false);
+            setIncomingInfo(null);
+            setMuted(false);
+            setSpeakerOn(false);
+            onCallEndedRef.current?.();
+        });
+        return () => {
+            subReg.remove();
+            subIncoming.remove();
+            subState.remove();
+            subEnd.remove();
+            clearTimer();
+        };
+    }, [clearTimer, startDuration]);
+    // ── Registration ─────────────────────────────────────────────────────────
+    //
+    // Three entry points into the SIP registration flow:
+    //
+    //   - Auto-register effect (below) — fires whenever `config` changes
+    //   - register(cfg?)             — host app forces a re-register
+    //   - refreshRegistration()      — light-touch refresh, skips full setup
+    //                                  when the existing session looks healthy
+    // Internal helper — strips `https://` and trailing `/` from the domain
+    // (a common user-input mistake) before handing the params to native.
+    // Native is permissive about transport, but defaults to TCP if unset
+    // because most production PBXs allow TCP and it's NAT-friendlier than UDP.
+    const registerWith = useCallback(async (cfg) => {
+        const domain = formatTenantDomain(cfg.domain);
+        // Strip port before domain check (e.g. "charles.nativetalk.io:5060")
+        const domainHost = domain.split(':')[0];
+        if (!domainHost.endsWith('.nativetalk.io') && domainHost !== 'nativetalk.io') {
+            onErrorRef.current?.({
+                code: 'INVALID_DOMAIN',
+                message: `Domain "${domainHost}" is not a valid Nativetalk domain. Only *.nativetalk.io domains are supported.`,
+            });
+            return;
+        }
+        const transport = cfg.transport ?? 'tcp';
+        Native.register({
+            username: cfg.username,
+            password: cfg.password,
+            domain,
+            transport,
+        });
+    }, []);
+    // Auto-register whenever `config` changes. Identity comparison only —
+    // passing the same SIP config object on every render is fine, but passing
+    // `{...sip}` will re-register every time, so don't do that.
+    useEffect(() => {
+        if (!autoRegister)
+            return;
+        if (!config || !config.username)
+            return;
+        registerWith(config).catch((e) => onErrorRef.current?.({
+            code: 'REGISTER_FAILED',
+            message: e?.message ?? String(e),
+        }));
+    }, [config, autoRegister, registerWith]);
+    // ── Public actions returned from useCall() ───────────────────────────────
+    // Force a re-register. Use this when:
+    //  - You disabled `autoRegister` and want to control timing yourself.
+    //  - You want to switch accounts at runtime — pass the new config as arg.
+    //  - The user toggled a "Reconnect" button after a network blip.
+    const register = useCallback(async (overrideCfg) => {
+        const next = overrideCfg ?? config ?? undefined;
+        if (!next || !next.username) {
+            onErrorRef.current?.({
+                code: 'NO_CONFIG',
+                message: 'No SIP config available — pass `config` to <CallProvider> or call register({...}).',
+            });
+            return;
+        }
+        await registerWith(next);
+    }, [config, registerWith]);
+    // Smart refresh — if registration was already in a working state, we use
+    // Linphone's lightweight `refreshRegisters()` (it just re-pings the
+    // server). If it was failed/cleared, we do a full re-register from
+    // scratch since the lightweight refresh won't recover from a 401 or DNS
+    // blackhole.
+    const refreshRegistration = useCallback(async () => {
+        const state = registration?.state;
+        if (!state || state === 'none' || state === 'cleared' || state === 'failed') {
+            if (config)
+                await registerWith(config);
+            return;
+        }
+        Native.refreshRegisters();
+    }, [registration, config, registerWith]);
+    const unregister = useCallback(async () => {
+        Native.setRegisterEnabled(false);
+    }, []);
+    // Place an outgoing call. Accepts either:
+    //   - a plain extension/number ("100" or "+2348012345678") — combined with
+    //     `config.domain` to form `sip:<dest>@<domain>`
+    //   - a fully-qualified SIP URI ("sip:user@gateway.example.com") — passed
+    //     through unchanged, useful when dialling external PSTN gateways
+    //
+    // We optimistically set status to OutgoingInit before the native call
+    // returns so the UI can render immediately — the real state will be
+    // confirmed by the next CallState event in ~50ms.
+    const dial = useCallback(async (destination) => {
+        if (!destination || destination.length < 1) {
+            onErrorRef.current?.({
+                code: 'INVALID_NUMBER',
+                message: 'Cannot dial an empty number.',
+            });
+            return;
+        }
+        if (!config?.domain) {
+            onErrorRef.current?.({
+                code: 'NO_CONFIG',
+                message: 'Cannot dial: no SIP domain configured.',
+            });
+            return;
+        }
+        resetDuration();
+        const uri = destinationToSipUri(destination, config.domain);
+        setCallStatus('OutgoingInit');
+        Native.call(uri);
+        onOutgoingCallRef.current?.({
+            phone: destination,
+            initials: initialsFrom(destination),
+        });
+    }, [config?.domain, resetDuration]);
+    const answer = useCallback(async () => {
+        setIncoming(false);
+        setCallStatus('Connected');
+        resetDuration();
+        Native.answer();
+    }, [resetDuration]);
+    // Hangup is debounced via the `ending` flag — Linphone takes ~500ms to
+    // settle, and tapping the end-call button twice in that window can put it
+    // into a weird state. The 600ms timer is empirical: long enough to swallow
+    // double-taps, short enough that the next call attempt isn't blocked.
+    const hangup = useCallback(async () => {
+        if (ending)
+            return;
+        setEnding(true);
+        try {
+            Native.end();
+        }
+        finally {
+            setTimeout(() => setEnding(false), 600);
+        }
+    }, [ending]);
+    // Decline an incoming call with a specific SIP response code. Default is
+    // "busy" (486) which is how voicemail systems usually decide to take a
+    // message; use "declined" if you don't want the caller routed to VM.
+    const decline = useCallback(async (reason = 'busy') => {
+        Native.decline(reason);
+    }, []);
+    // Toggle helpers use the functional setState form so concurrent taps don't
+    // race — without it, `next = !muted` could read stale state if React is
+    // batching renders.
+    const toggleMute = useCallback(() => {
+        setMuted((current) => {
+            const next = !current;
+            Native.mute(next);
+            return next;
+        });
+    }, []);
+    const toggleSpeaker = useCallback(() => {
+        setSpeakerOn((current) => {
+            const next = !current;
+            Native.speaker(next);
+            return next;
+        });
+    }, []);
+    // No optimistic update here — `held` is driven by HELD_STATES / RESUMED_STATES
+    // from the native CallState event, so we just kick off the action and let
+    // the event update React state.
+    const toggleHold = useCallback(() => {
+        if (held)
+            Native.resume();
+        else
+            Native.hold();
+    }, [held]);
+    // Send a DTMF (touch-tone) digit IN BAND on the active call — used for
+    // navigating IVRs ("Press 1 for support…"). Different from playKeyTone,
+    // which only plays a UI feedback tone locally.
+    const sendDtmf = useCallback((digit) => {
+        if (!digit)
+            return;
+        Native.sendDtmf(String(digit));
+    }, []);
+    // Local DTMF feedback tone — plays the standard touch-tone sound through
+    // the device speaker when the user taps a key on the dial-pad. Does NOT
+    // send anything over the SIP call; for that, use sendDtmf().
+    const playKeyTone = useCallback((digit) => {
+        if (!digit)
+            return;
+        Native.playKeyTone(String(digit));
+    }, []);
+    const getCallLogs = useCallback(async () => {
+        try {
+            return await Native.getCallLogs();
+        }
+        catch (e) {
+            onErrorRef.current?.({
+                code: 'GET_CALL_LOGS_FAILED',
+                message: e?.message ?? String(e),
+            });
+            return [];
+        }
+    }, []);
+    const getRegistrationStatus = useCallback(async () => {
+        const raw = await Native.getRegistrationStatus();
+        const pretty = regStateName(raw?.state);
+        return { ...raw, state: pretty, pretty };
+    }, []);
+    const startServices = useCallback(() => Native.startNativeServices(), []);
+    const stopServices = useCallback((logout = false) => Native.stopNativeServices(logout), []);
+    const formattedDuration = useMemo(() => formatDuration(durationSec), [durationSec]);
+    const value = useMemo(() => ({
+        config,
+        registration,
+        callStatus,
+        durationSec,
+        formattedDuration,
+        incoming,
+        incomingInfo,
+        isMuted: muted,
+        isSpeaker: speakerOn,
+        isHeld: held,
+        dial,
+        answer,
+        hangup,
+        decline,
+        toggleMute,
+        toggleSpeaker,
+        toggleHold,
+        sendDtmf,
+        playKeyTone,
+        register,
+        refreshRegistration,
+        unregister,
+        getCallLogs,
+        getRegistrationStatus,
+        startNativeServices: startServices,
+        stopNativeServices: stopServices,
+    }), [
+        config,
+        registration,
+        callStatus,
+        durationSec,
+        formattedDuration,
+        incoming,
+        incomingInfo,
+        muted,
+        speakerOn,
+        held,
+        dial,
+        answer,
+        hangup,
+        decline,
+        toggleMute,
+        toggleSpeaker,
+        toggleHold,
+        sendDtmf,
+        playKeyTone,
+        register,
+        refreshRegistration,
+        unregister,
+        getCallLogs,
+        getRegistrationStatus,
+        startServices,
+        stopServices,
+    ]);
+    return <CallContext.Provider value={value}>{children}</CallContext.Provider>;
+}
+/**
+ * Access the call API from any descendant of `<CallProvider>`.
+ *
+ * Throws if used outside the provider.
+ */
+export function useCall() {
+    const ctx = useContext(CallContext);
+    if (!ctx) {
+        throw new Error('`useCall()` must be used inside `<CallProvider>`. Mount the provider near the root of your app tree.');
+    }
+    return ctx;
+}
+/** Internal — exported for power users who want to read the context without throwing. */
+export function useCallSafe() {
+    return useContext(CallContext);
+}
+/** Re-export to allow `formatDuration`, `callStatusLabel`, etc. to be imported from the main entry too. */
+export { callStatusLabel, formatDuration };