@dialstack/sdk-native 0.1.1 → 0.2.0

package/README.md

@@ -171,25 +171,75 @@ const storage: PlatformStorage = {
 
 `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
 
-Two runnable apps, both wired with the permissions and plugin above:
+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.