@dialstack/sdk-native 0.1.0 → 0.2.0

package/README.md

@@ -8,28 +8,10 @@ pieces (`<DialPad>` / `<IncomingCall>` / `<OngoingCall>`).
 import { Softphone, SoftphoneProvider } from '@dialstack/sdk-native';
 ```
 
-## Why a separate package (not `@dialstack/sdk/native`)
-
-This is a distinct package from `@dialstack/sdk` **on purpose**: it declares the
-React Native peer dependencies. Keeping them here means the web SDK's dependency
-graph is _structurally_ free of anything React Native — a web app that installs
-`@dialstack/sdk` can never pull `react-native-webrtc`/`-svg`/`-incall-manager`.
-
-`@dialstack/sdk-native` is self-contained: it inlines its own compiled copy of
-the shared headless calling core and call-state hooks at build time, so it has
-**no runtime dependency on `@dialstack/sdk`** (the core is authored once in that
-package and shared at build time only). The core is written to the standard
-browser WebRTC surface (`RTCPeerConnection`, `MediaStream`, `navigator.mediaDevices`);
-call `registerGlobals()` from your WebRTC package at your app's entry point so
-that surface exists on React Native before the SDK runs. The two RN-only gaps —
-outbound ringback audio and E911 persistence — are supplied by the softphone
-provider (an InCallManager-backed ringback and your `storage` adapter).
-
-```js
-// index.js — before anything imports the SDK
-import { registerGlobals } from 'react-native-webrtc';
-registerGlobals();
-```
+React components for the web live in
+[`@dialstack/sdk-react`](https://www.npmjs.com/package/@dialstack/sdk-react).
+This package is self-contained: install it alone, and nothing from the web SDK
+comes with it.
 
 ## Install
 
@@ -52,8 +34,99 @@ globals `registerGlobals()` installs, so any spec-compliant build works. The
 `react-native-webrtc` peer is **optional** precisely so a differently-named
 package can satisfy it without npm installing a second copy alongside.
 
-See the example apps under `../mobile/` for a runnable Expo app and a bare React
-Native app.
+> **Installing our fork from GitHub:** its entry points are generated by its
+> `prepare` script at install time. If your npm or CI blocks install scripts,
+> the package installs without them and the failure surfaces later as
+> `Cannot find module`, not as an install error — allow install scripts for
+> that dependency.
+
+### Install the WebRTC globals
+
+The SDK core is written to the standard browser WebRTC surface
+(`RTCPeerConnection`, `MediaStream`, `navigator.mediaDevices`), so call
+`registerGlobals()` from your WebRTC package at your app's entry point, before
+anything imports the SDK:
+
+```js
+// index.js
+import { registerGlobals } from 'react-native-webrtc';
+registerGlobals();
+```
+
+Two RN-only gaps — outbound ringback audio and E911 persistence — are supplied
+by the softphone provider (an InCallManager-backed ringback and your `storage`
+adapter).
+
+## Permissions (required)
+
+**Without microphone permission a call fails with `Call failed` and no other
+symptom** — `getUserMedia` never runs, so there is nothing else to see. Declare
+these before your first call.
+
+### Expo
+
+```json
+{
+  "expo": {
+    "plugins": ["@config-plugins/react-native-webrtc"],
+    "android": {
+      "permissions": [
+        "android.permission.RECORD_AUDIO",
+        "android.permission.MODIFY_AUDIO_SETTINGS",
+        "android.permission.INTERNET",
+        "android.permission.ACCESS_NETWORK_STATE",
+        "android.permission.VIBRATE"
+      ]
+    },
+    "ios": {
+      "infoPlist": {
+        "NSMicrophoneUsageDescription": "… needs the microphone to place and receive calls.",
+        "UIBackgroundModes": ["audio", "voip"]
+      }
+    }
+  }
+}
+```
+
+`react-native-webrtc` is a native module, so it needs a **development build** —
+it cannot run in Expo Go. Re-run `expo prebuild` after changing any of the above.
+
+The config plugin also injects permissions of its own that this SDK does not use
+— including `CAMERA`, `SYSTEM_ALERT_WINDOW` and `BLUETOOTH` — and writes a
+default camera-usage string. If a store listing or privacy review asks about
+them, drop the ones you don't need with Expo's
+[`android.blockedPermissions`](https://docs.expo.dev/versions/latest/config/app/#blockedpermissions).
+
+### Bare React Native
+
+`android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<uses-permission android:name="android.permission.INTERNET" />
+<uses-permission android:name="android.permission.RECORD_AUDIO" />
+<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
+<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+<uses-permission android:name="android.permission.WAKE_LOCK" />
+<uses-permission android:name="android.permission.VIBRATE" />
+```
+
+`VIBRATE` is what gives the incoming call its haptic buzz: Android enforces it
+by throwing rather than no-op'ing, so without it the call still rings but never
+vibrates. The SDK catches that throw, so omitting the permission degrades
+gracefully — it does not break the call. Neither `react-native` nor
+`react-native-incall-manager` declares it, so your app must.
+
+`ios/<YourApp>/Info.plist`:
+
+```xml
+<key>NSMicrophoneUsageDescription</key>
+<string>… needs the microphone to place and receive calls.</string>
+<key>UIBackgroundModes</key>
+<array>
+  <string>audio</string>
+  <string>voip</string>
+</array>
+```
 
 ## DTMF
 
@@ -68,7 +141,7 @@ npm install 'github:dialstack/react-native-webrtc#7e9a0eb55e068b2ba452f22e02e4b7
 With any other WebRTC package — including LiveKit's and Stream's forks, neither
 of which exposes `RTCRtpSender.dtmf` — `Call.canSendDtmf` is `false`, the in-call
 keypad stays hidden, `Call.sendDtmf()` throws `call_failed`, and the SDK logs
-`[dialstack] DTMF is unavailable …` on the first call. Calls are otherwise
+`[dialstack] DTMF is unavailable …` once per app process. Calls are otherwise
 unaffected, but there is no way to navigate an IVR or phone tree. That is the
 tradeoff to weigh if another library forces a particular WebRTC package on you.
 
@@ -96,20 +169,77 @@ const storage: PlatformStorage = {
 </SoftphoneProvider>;
 ```
 
-The Expo `../examples/mobile/expo` app ships this MMKV adapter; the bare
-`../examples/mobile/bare` app ships an AsyncStorage one. Either works —
 `storage` just needs `getItem`/`setItem`/`removeItem`.
 
+## Call audio
+
+By default `<SoftphoneProvider>` owns call audio through
+`react-native-incall-manager`: it rings inbound calls, plays the outbound
+ringback, and holds the audio session (which also turns on the proximity sensor)
+while a call is connected. The ringback goes only to a phone the provider creates
+from `token`: a phone passed as `existingPhone` keeps the `ringback` it was
+created with, so pass one to `createPhone({ ringback })` yourself.
+
+When the operating system owns the call instead, because you report calls to
+CallKit or Telecom, the provider must stay out of it: the OS rings the phone and
+activates the session itself, and ringing on top of it costs the answered call
+its microphone. Set `callAudio="host"` and the provider does none of the above.
+With a `bridge` it is always `"host"`. Anything you still want, such as the proximity
+sensor, is then yours to drive (`InCallManager.startProximitySensor()` does not
+touch the audio session).
+
+The output route is yours too. Without an `audioOutput` controller the in-call
+speaker button is disabled. To enable it, pass one built over your OS integration:
+
+```tsx
+const audioOutput: AudioOutputController = {
+  current: () => lastReportedRoute, // what the OS reports, same object until it changes
+  onChange: (listener) => subscribeToRouteChanges(listener),
+  setSpeaker: (on) => requestSpeaker(on),
+};
+
+<SoftphoneProvider bridge={bridge} audioOutput={audioOutput}>
+  …
+</SoftphoneProvider>;
+```
+
+The button shows only the route the OS reports. A switch made from the CallKit
+or Telecom UI, a headset, or a car therefore shows up in-app as well.
+`useAudioOutput()` exposes the same state if you build your own UI.
+
+## Example apps
+
+Three runnable apps, all wired with the permissions and plugin above:
+
+- [Expo](https://github.com/dialstack/dialstack-sdk/tree/main/examples/mobile/expo)
+  — ships the MMKV storage adapter
+- [Bare React Native](https://github.com/dialstack/dialstack-sdk/tree/main/examples/mobile/bare)
+  — ships an AsyncStorage adapter
+- [OS integration](https://github.com/dialstack/dialstack-sdk/tree/main/examples/mobile/os-integration)
+  — the worked example for the OS call surface: calls on a locked or killed
+  phone via push wake, `OsCallAdapter` over expo-callkit-telecom. Built and
+  verified on both Android (FCM + Telecom) and iOS (PushKit + CallKit).
+
 ## Scope
 
-This package provides the in-app calling surface: the provider, the call state,
-and the React Native UI. The operating system's own call experience — the
-full-screen incoming call, ringing on a locked screen, and waking the app from a
-push — is the integrator's to wire, using the platform frameworks directly (iOS
-PushKit + CallKit, Android FCM + Telecom/ConnectionService).
+This package provides the in-app calling surface — the provider, the call state,
+and the React Native UI — plus the bridge between the SDK and the operating
+system's own call experience.
+
+Binding the two remains the integrator's work, but not from scratch:
+`NativeCallBridge` keeps an OS call session and an SDK `Call` in step in both
+directions, and `OsCallAdapter` is the interface it drives, so the part you write
+is one adapter over your chosen call library rather than the whole state machine.
+A contract suite in `@dialstack/sdk-native/testing` exercises an adapter against
+the behaviours the bridge depends on.
+
+What the package does not ship is the platform wiring itself: the native call
+library (iOS PushKit + CallKit, Android FCM + Telecom/ConnectionService) and the
+push delivery. DialStack stores no device tokens — arranging the push that wakes
+your app is yours. The OS-integration example above is a complete worked wiring
+of both on Android.
 
-The seams for that are public. `useSoftphone()` exposes `calls`,
+The lower-level seams stay public too: `useSoftphone()` exposes `calls`,
 `incomingCalls`, `activeCall` and `actions.callActionsFor(call)`, and every
-`Call` carries a stable `id` and `state`, so a native call session can be
-created, kept in step, and torn down alongside the SDK's own. DialStack stores
-no device tokens — delivering the push that wakes your app is yours to arrange.
+`Call` carries a stable `id` and `state`, so an integrator who wants to drive the
+OS session directly can still do so.