@nativetalkcommunications/react-native-call-sdk 0.1.0

package/src/helpers.ts

@@ -0,0 +1,179 @@
+/**
+ * Pure helpers used by the provider and UI components.
+ *
+ * Kept here (not in `native.ts` or `CallProvider.tsx`) so they can be
+ * unit-tested without touching React or native modules.
+ */
+import type { CallState, RegistrationState } from './types';
+
+/**
+ * Strips `http(s)://` and trailing `/` from a tenant domain.
+ *
+ * Multi-tenant backends often hand the SDK an HTTP URL ("https://t1.example.com/")
+ * when what we need is a bare SIP host ("t1.example.com"). Doing this once
+ * here is friendlier than failing the registration with a cryptic error.
+ */
+export function formatTenantDomain(domain: string | undefined | null): string {
+  if (!domain) return '';
+  return domain.replace(/^https?:\/\//, '').replace(/\/$/, '');
+}
+
+/**
+ * Extract the user-part of `sip:user@domain` (or returns the input unchanged).
+ *
+ * The regex stops at `@`, `;` (URI params like `;transport=tcp`), and `>`
+ * (display-name angle brackets) so it handles all three common SIP URI
+ * formats without separate parsers.
+ */
+export function parseSipUser(sipUri: string = ''): string {
+  const m = /sip:([^@;>]+)/i.exec(sipUri);
+  return m?.[1] ?? sipUri.replace(/^sip:/i, '');
+}
+
+// Allowlist anything dialable: digits plus the three special SIP keys.
+// Notably DROPS letters — PSTN gateways reject them, and the dial-pad
+// converts letters via the standard ABC/DEF mapping before getting here.
+export function sanitizeDial(input: string = ''): string {
+  return input.replace(/[^\d+#*]/g, '');
+}
+
+/** Format seconds as `M:SS` or `H:MM:SS`. */
+export function formatDuration(totalSeconds: number): string {
+  const s = Math.max(0, Math.floor(totalSeconds));
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  const sec = s % 60;
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return h ? `${h}:${pad(m)}:${pad(sec)}` : `${m}:${pad(sec)}`;
+}
+
+/** Convert two-character initials for avatar placeholders. */
+export function initialsFrom(name: string | undefined | null): string {
+  return (name || '??').slice(0, 2).toUpperCase();
+}
+
+/**
+ * Linphone numeric-state → string-state mapping.
+ *
+ * The SDK's current native modules emit states as strings ("Connected"),
+ * but older Linphone bindings — and any third party that wires up the
+ * native module directly — may still send the raw enum ordinals. Keeping
+ * this map means a Linphone upgrade or a different binding doesn't break
+ * existing apps.
+ */
+const CALL_STATE_BY_INT: Record<number, CallState> = {
+  0: 'Idle',
+  1: 'IncomingReceived',
+  2: 'PushIncomingReceived',
+  3: 'OutgoingInit',
+  4: 'OutgoingProgress',
+  5: 'OutgoingRinging',
+  6: 'OutgoingEarlyMedia',
+  7: 'Connected',
+  8: 'StreamsRunning',
+  9: 'Pausing',
+  10: 'Paused',
+  11: 'Resuming',
+  12: 'Referred',
+  13: 'Error',
+  14: 'End',
+  15: 'PausedByRemote',
+  16: 'UpdatedByRemote',
+  17: 'IncomingEarlyMedia',
+  18: 'Updating',
+  19: 'Released',
+  20: 'EarlyUpdatedByRemote',
+  21: 'EarlyUpdating',
+};
+
+const REG_STATE_BY_INT: Record<number, RegistrationState> = {
+  0: 'none',
+  1: 'progress',
+  2: 'ok',
+  3: 'cleared',
+  4: 'failed',
+};
+
+/** Normalise a raw call-state value (string or int) to its canonical string form. */
+export function callStateName(raw: unknown): CallState {
+  if (typeof raw === 'number') return CALL_STATE_BY_INT[raw] ?? String(raw);
+  return String(raw ?? '') as CallState;
+}
+
+/** Normalise a raw registration-state value (string or int) to canonical lowercase string. */
+export function regStateName(raw: unknown): RegistrationState {
+  if (typeof raw === 'number') {
+    return REG_STATE_BY_INT[raw] ?? 'unknown';
+  }
+  const s = String(raw ?? '').toLowerCase();
+  if (
+    s === 'none' ||
+    s === 'progress' ||
+    s === 'ok' ||
+    s === 'cleared' ||
+    s === 'failed'
+  ) {
+    return s as RegistrationState;
+  }
+  return 'unknown';
+}
+
+/**
+ * Map a raw call status to a user-friendly UI label.
+ *
+ * You typically don't need to call this directly — `useCall().callStatus`
+ * already returns the canonical state name, and the bundled
+ * `<OutgoingCallView>` does its own mapping. Use this when building a custom UI.
+ */
+export function callStatusLabel(status: CallState): string {
+  switch (status) {
+    case 'OutgoingInit':
+    case 'OutgoingProgress':
+    case 'OutgoingEarlyMedia':
+      return 'Calling…';
+    case 'OutgoingRinging':
+      return 'Ringing…';
+    case 'Connected':
+    case 'StreamsRunning':
+      return 'In progress';
+    case 'Pausing':
+      return 'Pausing…';
+    case 'Paused':
+    case 'PausedByRemote':
+      return 'On hold';
+    case 'Resuming':
+      return 'Resuming…';
+    case 'End':
+    case 'Released':
+      return 'Call ended';
+    case 'Error':
+      return 'Call failed';
+    case 'IncomingReceived':
+    case 'PushIncomingReceived':
+    case 'IncomingEarlyMedia':
+      return 'Incoming call';
+    default:
+      return status || 'Idle';
+  }
+}
+
+/**
+ * Resolve a destination string to a SIP URI.
+ *
+ * Three-case dispatch in order of "most explicit wins":
+ *   1. `sip:100@gw.com`     → already a URI, pass through unchanged.
+ *   2. `100@gw.com`         → caller specified the gateway, just prefix `sip:`.
+ *   3. `100` (bare)         → fill in the configured domain.
+ *
+ * This lets apps mix internal-extension dialling with PSTN gateway URIs
+ * without needing a separate API.
+ */
+export function destinationToSipUri(
+  destination: string,
+  domain: string
+): string {
+  if (!destination) return '';
+  if (destination.startsWith('sip:')) return destination;
+  if (destination.includes('@')) return `sip:${destination}`;
+  return `sip:${destination}@${formatTenantDomain(domain)}`;
+}

package/src/index.ts

@@ -0,0 +1,84 @@
+/**
+ * Public entry point for `@nativetalkcommunications/react-native-call-sdk`.
+ *
+ * Most apps only need:
+ *
+ * ```tsx
+ * import { CallProvider, useCall } from '@nativetalkcommunications/react-native-call-sdk';
+ * ```
+ *
+ * Optional UI components are exported from the `/ui` sub-path:
+ *
+ * ```tsx
+ * import { Dialer, IncomingCallView, OutgoingCallView } from '@nativetalkcommunications/react-native-call-sdk/ui';
+ * ```
+ *
+ * Power-users can reach the raw native bridge:
+ *
+ * ```ts
+ * import { CallEngine } from '@nativetalkcommunications/react-native-call-sdk';
+ * CallEngine.call('sip:100@sip.example.com');
+ * ```
+ */
+
+export { CallProvider, useCall, useCallSafe } from './CallProvider';
+export type {
+  CallApi,
+  CallLogEntry,
+  CallProviderEvents,
+  CallProviderProps,
+  CallState,
+  DeclineReason,
+  IncomingCallInfo,
+  RegistrationEvent,
+  RegistrationState,
+  SipConfig,
+  SipTransport,
+} from './types';
+export {
+  callStateName,
+  callStatusLabel,
+  destinationToSipUri,
+  formatDuration,
+  formatTenantDomain,
+  initialsFrom,
+  parseSipUser,
+  regStateName,
+  sanitizeDial,
+} from './helpers';
+
+import * as Native from './native';
+
+/**
+ * Direct access to the native bridge.
+ *
+ * This is escape-hatch territory — prefer `useCall()` whenever possible. Use
+ * `CallEngine` only when you need to drive the SDK from outside React (e.g.
+ * a headless task) or to wire iOS VoIP push tokens.
+ */
+export const CallEngine = {
+  init: Native.init,
+  register: Native.register,
+  call: Native.call,
+  answer: Native.answer,
+  end: Native.end,
+  hangup: Native.end,
+  decline: Native.decline,
+  mute: Native.mute,
+  speaker: Native.speaker,
+  hold: Native.hold,
+  resume: Native.resume,
+  sendDtmf: Native.sendDtmf,
+  playKeyTone: Native.playKeyTone,
+  refreshRegisters: Native.refreshRegisters,
+  setRegisterEnabled: Native.setRegisterEnabled,
+  getRegistrationStatus: Native.getRegistrationStatus,
+  getCallLogs: Native.getCallLogs,
+  startNativeServices: Native.startNativeServices,
+  stopNativeServices: Native.stopNativeServices,
+  registerVoipToken: Native.registerVoipToken,
+  ensureMicPermission: Native.ensureMicPermission,
+  on: Native.on,
+};
+
+export { callEvents } from './native';

package/src/native.ts

@@ -0,0 +1,185 @@
+/**
+ * Thin bridge to the native `NativetalkCallSdk` module.
+ *
+ * This file is the only place that talks to `NativeModules` and the event
+ * emitter. Everything else in the SDK uses these exports so the JS layer
+ * stays testable.
+ *
+ * If you see "TurboModuleRegistry … was not found" at runtime, the native
+ * library isn't linked. See `docs/installation.md`.
+ */
+import {
+  NativeEventEmitter,
+  NativeModules,
+  PermissionsAndroid,
+  Platform,
+} from 'react-native';
+import type { CallLogEntry, RegistrationEvent, SipTransport } from './types';
+
+const LINKING_ERROR =
+  `The package '@nativetalkcommunications/react-native-call-sdk' doesn't seem to be linked. Make sure:\n\n` +
+  `- you rebuilt the app after installing the package\n` +
+  `- you are not using Expo Go (use a dev client or bare workflow)\n` +
+  `- (iOS) you ran 'pod install' inside the ios/ directory\n`;
+
+// Proxy fallback: if autolinking failed, every method access throws a helpful
+// error instead of a cryptic "undefined is not a function". This means a
+// misconfigured app crashes EARLY with a clear message, not deep inside JS.
+const NativetalkCallSdk =
+  NativeModules.NativetalkCallSdk ??
+  new Proxy(
+    {},
+    {
+      get() {
+        throw new Error(LINKING_ERROR);
+      },
+    }
+  );
+
+// Single shared emitter — re-creating it per subscription wastes native
+// handlers and can drop events during the swap.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const callEvents = new NativeEventEmitter(NativetalkCallSdk as any);
+
+/** Request microphone permission on Android. Returns true if granted (or platform is iOS). */
+export async function ensureMicPermission(): Promise<boolean> {
+  if (Platform.OS !== 'android') return true;
+  const granted = await PermissionsAndroid.request(
+    PermissionsAndroid.PERMISSIONS.RECORD_AUDIO,
+    {
+      title: 'Microphone Permission',
+      message: 'Microphone access is required to make and receive calls.',
+      buttonPositive: 'OK',
+    }
+  );
+  return granted === PermissionsAndroid.RESULTS.GRANTED;
+}
+
+// --- Core lifecycle ---
+
+// Idempotent on the native side, safe to call multiple times.
+export function init(cfg?: Record<string, unknown>): Promise<void> {
+  return NativetalkCallSdk.init(cfg ?? {});
+}
+
+// Android-only: iOS uses CallKit + VoIP push instead of a background
+// service. Guarding here keeps the JS API symmetric across platforms.
+export function startNativeServices(): void {
+  if (Platform.OS !== 'android') return;
+  NativetalkCallSdk.startNativeServices();
+}
+
+export function stopNativeServices(logout = false): void {
+  if (Platform.OS !== 'android') return;
+  NativetalkCallSdk.stopNativeServices(logout);
+}
+
+// --- Registration ---
+
+export interface RegisterArgs {
+  username: string;
+  password: string;
+  domain: string;
+  transport?: SipTransport;
+}
+
+export function register(account: RegisterArgs): void {
+  NativetalkCallSdk.register(account);
+}
+
+// Optional-chained: older native builds may not export this method, and
+// we'd rather no-op than crash on a non-critical refresh.
+export function refreshRegisters(): void {
+  NativetalkCallSdk.refreshRegisters?.();
+}
+
+export function setRegisterEnabled(enabled: boolean): void {
+  NativetalkCallSdk.setRegisterEnabled(enabled);
+}
+
+export function getRegistrationStatus(): Promise<RegistrationEvent> {
+  return NativetalkCallSdk.getRegistrationStatus();
+}
+
+// --- Call control ---
+
+export function call(sipUri: string): void {
+  NativetalkCallSdk.call(sipUri);
+}
+
+export function answer(): void {
+  NativetalkCallSdk.answer();
+}
+
+export function end(): void {
+  NativetalkCallSdk.end();
+}
+
+export function decline(reason: string = 'declined'): void {
+  NativetalkCallSdk.decline?.(reason);
+}
+
+export function mute(on: boolean): void {
+  NativetalkCallSdk.mute(on);
+}
+
+export function speaker(on: boolean): void {
+  NativetalkCallSdk.speaker(on);
+}
+
+export function hold(): void {
+  NativetalkCallSdk.hold();
+}
+
+export function resume(): void {
+  NativetalkCallSdk.resume();
+}
+
+export function sendDtmf(digit: string): void {
+  NativetalkCallSdk.sendDtmf(digit);
+}
+
+export function playKeyTone(digit: string): void {
+  NativetalkCallSdk.playKeyTone(digit);
+}
+
+// --- Call logs ---
+
+export function getCallLogs(): Promise<CallLogEntry[]> {
+  return NativetalkCallSdk.getCallLogs();
+}
+
+// --- iOS push token (advanced; only used if you wire VoIP push manually) ---
+
+// Call from the host AppDelegate's PushKit `didUpdate` handler so the token
+// gets attached to the SIP account params. Android FCM uses a different flow.
+export function registerVoipToken(hex: string): void {
+  if (Platform.OS !== 'ios') return;
+  NativetalkCallSdk.registerVoipToken?.(hex);
+}
+
+// --- Event subscriptions ---
+//
+// Typed wrappers around `callEvents.addListener` — using string-typed event
+// names directly would lose autocomplete and let typos slip through. The
+// `Sub` return shape mirrors NativeEventEmitter's so consumers can call
+// `.remove()` without importing RN types.
+type Listener<T> = (event: T) => void;
+type Sub = { remove: () => void };
+
+export const on = {
+  RegistrationChanged: (cb: Listener<any>): Sub =>
+    callEvents.addListener('RegistrationChanged', cb),
+  CallIncoming: (cb: Listener<any>): Sub =>
+    callEvents.addListener('CallIncoming', cb),
+  CallState: (cb: Listener<any>): Sub =>
+    callEvents.addListener('CallState', cb),
+  CallEnded: (cb: Listener<any>): Sub =>
+    callEvents.addListener('CallEnded', cb),
+  // The TM* events are Android-only (telephony observer for native GSM
+  // calls). They never fire on iOS but the subscription is harmless.
+  TMPhoneCallState: (cb: Listener<any>): Sub =>
+    callEvents.addListener('TMPhoneCallState', cb),
+  TMPhoneCallInfo: (cb: Listener<any>): Sub =>
+    callEvents.addListener('TMPhoneCallInfo', cb),
+};

package/src/types.ts

@@ -0,0 +1,202 @@
+/**
+ * Public types for the Nativetalk Call SDK.
+ *
+ * These describe the SIP account configuration, registration state, call
+ * lifecycle events, and the shape of `useCall()` and `<CallProvider>`.
+ */
+
+/** Transport used for SIP signalling. Most providers support `tcp`; use `tls` for encrypted signalling. */
+export type SipTransport = 'udp' | 'tcp' | 'tls';
+
+/**
+ * SIP account credentials.
+ *
+ * `domain` should be the SIP server hostname (and optionally `:port`). Do NOT
+ * include `sip:` or `http(s)://` — the SDK strips those automatically, but it's
+ * cleaner not to send them.
+ */
+export interface SipConfig {
+  username: string;
+  password: string;
+  domain: string;
+  transport?: SipTransport;
+}
+
+/** Registration lifecycle states reported by the underlying SIP stack. */
+export type RegistrationState =
+  | 'none'
+  | 'progress'
+  | 'ok'
+  | 'cleared'
+  | 'failed'
+  | 'unknown';
+
+/** Registration state event payload. */
+export interface RegistrationEvent {
+  state: RegistrationState;
+  message?: string;
+  username?: string;
+  domain?: string;
+  displayName?: string;
+  /** Human-readable form of `state` (e.g. `"Ok"`, `"Failed"`). */
+  pretty?: string;
+}
+
+/**
+ * Linphone-derived call lifecycle states. Use the string forms in your UI.
+ *
+ * The numeric mapping is preserved internally for backwards compatibility with
+ * raw Linphone state values, but `useCall().callStatus` always returns the
+ * string form.
+ */
+export type CallState =
+  | 'Idle'
+  | 'IncomingReceived'
+  | 'PushIncomingReceived'
+  | 'OutgoingInit'
+  | 'OutgoingProgress'
+  | 'OutgoingRinging'
+  | 'OutgoingEarlyMedia'
+  | 'Connected'
+  | 'StreamsRunning'
+  | 'Pausing'
+  | 'Paused'
+  | 'Resuming'
+  | 'Referred'
+  | 'Error'
+  | 'End'
+  | 'PausedByRemote'
+  | 'UpdatedByRemote'
+  | 'IncomingEarlyMedia'
+  | 'Updating'
+  | 'Released'
+  | 'EarlyUpdatedByRemote'
+  | 'EarlyUpdating'
+  | string;
+
+/** Reason passed to `decline()`. Maps to standard SIP response codes. */
+export type DeclineReason =
+  | 'declined'
+  | 'busy'
+  | 'notacceptable'
+  | 'temporarilyunavailable';
+
+/** Information about an incoming call, surfaced via `useCall().incomingInfo`. */
+export interface IncomingCallInfo {
+  /** Best-effort display name: display-name → username → SIP user-part → `"Unknown"`. */
+  name: string;
+  /** Phone number or SIP identifier the call came from. */
+  phone: string;
+  /** Two-character initials for avatar placeholders. */
+  initials: string;
+  /** SIP call ID. May be missing on push-initiated calls before media flows. */
+  callId?: string;
+  /** Raw SIP URI of the remote party (`sip:user@domain`). */
+  uri?: string;
+}
+
+/** A single call history entry, normalised across platforms. */
+export interface CallLogEntry {
+  id: number;
+  /** ISO-8601 timestamp (UTC). */
+  call_start: string;
+  call_type: 'LOCAL' | 'DID' | 'STANDARD' | string;
+  caller_id: string;
+  call_direction: 'inbound' | 'outbound' | string;
+  called_number: string;
+  /** Platform-specific shape — Android returns `{ text, code }`, iOS returns a string. */
+  disposition:
+    | { text: string; code: number }
+    | string;
+  debit: string;
+  /** `MM:SS` or `HH:MM:SS`. */
+  duration: string;
+  destination: string;
+  sip_user: string;
+  created_at: string;
+  updated_at: string;
+}
+
+/** Optional callbacks the host app can supply to `<CallProvider>`. */
+export interface CallProviderEvents {
+  /** Fired when a new incoming call arrives. Use this to navigate to your incoming-call screen. */
+  onIncomingCall?: (info: IncomingCallInfo) => void;
+  /** Fired when an outgoing call has been initiated via `dial()`. */
+  onOutgoingCall?: (info: { phone: string; initials: string }) => void;
+  /** Fired when the active call ends (any reason). */
+  onCallEnded?: () => void;
+  /** Fired on every call state transition. */
+  onCallStateChanged?: (state: CallState) => void;
+  /** Fired on every registration state transition. */
+  onRegistrationStateChanged?: (event: RegistrationEvent) => void;
+  /** Fired when an error occurs (e.g. registration failure). */
+  onError?: (error: { code: string; message: string }) => void;
+}
+
+/** Props for `<CallProvider>`. */
+export interface CallProviderProps extends CallProviderEvents {
+  children: React.ReactNode;
+  /**
+   * SIP credentials. Pass `null` or omit while you load them from your backend —
+   * the SDK will idle until a valid config arrives.
+   */
+  config?: SipConfig | null;
+  /**
+   * If true (default), the SDK calls `register()` automatically whenever
+   * `config` changes. Set to false if you want manual control via the
+   * `register()` action.
+   */
+  autoRegister?: boolean;
+  /**
+   * If true (default on Android), the SDK starts the background/foreground
+   * service so calls can still arrive when the app is backgrounded. Has no
+   * effect on iOS — there CallKit + VoIP push handles backgrounding.
+   */
+  enableNativeServices?: boolean;
+  /**
+   * If true, the SDK requests `RECORD_AUDIO` permission on Android during
+   * provider mount. Default true. Disable if you handle permissions yourself.
+   */
+  requestMicPermission?: boolean;
+}
+
+/** Public API returned by `useCall()`. */
+export interface CallApi {
+  // --- Config ---
+  config: SipConfig | null;
+
+  // --- State ---
+  registration: RegistrationEvent | null;
+  callStatus: CallState;
+  durationSec: number;
+  formattedDuration: string;
+  incoming: boolean;
+  incomingInfo: IncomingCallInfo | null;
+  isMuted: boolean;
+  isSpeaker: boolean;
+  isHeld: boolean;
+
+  // --- Controls ---
+  dial: (destination: string) => Promise<void>;
+  answer: () => Promise<void>;
+  hangup: () => Promise<void>;
+  decline: (reason?: DeclineReason) => Promise<void>;
+  toggleMute: () => void;
+  toggleSpeaker: () => void;
+  toggleHold: () => void;
+  sendDtmf: (digit: string) => void;
+  playKeyTone: (digit: string) => void;
+
+  // --- Registration management ---
+  register: (config?: SipConfig) => Promise<void>;
+  refreshRegistration: () => Promise<void>;
+  unregister: () => Promise<void>;
+
+  // --- Call history ---
+  getCallLogs: () => Promise<CallLogEntry[]>;
+  getRegistrationStatus: () => Promise<RegistrationEvent>;
+
+  // --- Lifecycle (Android only — no-ops on iOS) ---
+  startNativeServices: () => void;
+  stopNativeServices: (logout?: boolean) => void;
+}

package/src/ui/Avatar.tsx

@@ -0,0 +1,46 @@
+import React from 'react';
+import { Text, View, StyleSheet, ViewStyle, TextStyle } from 'react-native';
+
+interface AvatarProps {
+  initials: string;
+  size?: number;
+  background?: string;
+  color?: string;
+  style?: ViewStyle;
+  textStyle?: TextStyle;
+}
+
+/** Tiny initials-circle used by the bundled call screens. */
+export function Avatar({
+  initials,
+  size = 80,
+  background = '#EEF2FF',
+  color = '#2D6BFF',
+  style,
+  textStyle,
+}: AvatarProps) {
+  return (
+    <View
+      style={[
+        styles.base,
+        { width: size, height: size, borderRadius: size / 2, backgroundColor: background },
+        style,
+      ]}
+    >
+      <Text
+        style={[
+          styles.text,
+          { color, fontSize: Math.floor(size * 0.4) },
+          textStyle,
+        ]}
+      >
+        {(initials || '??').slice(0, 2).toUpperCase()}
+      </Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  base: { alignItems: 'center', justifyContent: 'center' },
+  text: { fontWeight: '700' },
+});