@dialstack/sdk-native 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -41,7 +41,7 @@ interface PaginatedList<P extends Page<unknown>> extends Promise<P> {
  * rather than depending on the ambient `lib.dom.d.ts` names directly.
  */
 type RTCPeerConnection = globalThis.RTCPeerConnection;
-type MediaStream = globalThis.MediaStream;
+type MediaStream$1 = globalThis.MediaStream;
 type RTCIceServer$1 = globalThis.RTCIceServer;
 type RTCSessionDescriptionInit = globalThis.RTCSessionDescriptionInit;
 /**
@@ -81,7 +81,7 @@ interface Ringback {
     setSinkId?(deviceId: string | null): void;
 }
 
-type PhoneErrorCode = 'auth_failed' | 'auth_expired' | 'invalid_message' | 'call_failed' | 'call_not_found' | 'emergency_address_required' | 'session_limit' | 'session_replaced' | 'session_revoked' | 'rate_limited' | 'presence_unavailable' | 'reachability_unavailable' | 'internal_error' | 'going_away' | 'idle_timeout' | 'slow_consumer' | 'transport_closed' | 'ice_fetch_failed' | 'mic_permission_denied' | 'audio_device_unavailable' | 'audio_device_in_use';
+type PhoneErrorCode = 'auth_failed' | 'auth_expired' | 'invalid_message' | 'call_failed' | 'call_not_found' | 'emergency_address_required' | 'session_limit' | 'session_replaced' | 'session_revoked' | 'rate_limited' | 'call_limit' | 'presence_unavailable' | 'reachability_unavailable' | 'internal_error' | 'going_away' | 'idle_timeout' | 'slow_consumer' | 'transport_closed' | 'ice_fetch_failed' | 'token_refresh_failed' | 'mic_permission_denied' | 'audio_device_unavailable' | 'audio_device_in_use';
 declare class PhoneError extends Error {
     readonly code: PhoneErrorCode;
     readonly callId: string | null;
@@ -161,6 +161,17 @@ interface PhoneOptions {
      * processed the socket's close), reconnecting if it's dead.
      */
     onAppResume?: AppResumeSubscribe;
+    /**
+     * Acquire an inbound call's microphone when it is ANSWERED rather than when it
+     * arrives. Set by platforms whose OS owns the call audio session: CallKit and
+     * Telecom activate it only on answer, and capturing before then fails — on
+     * Android the device is still in `MODE_RINGTONE`, where WebRTC cannot start its
+     * recorder, so it releases it and the answered call has no mic at all.
+     *
+     * Off by default: a browser can capture during ringing, and doing so surfaces a
+     * microphone problem while the user can still see it.
+     */
+    deferInboundCapture?: boolean;
     /**
      * Microphone `deviceId` for new calls; omitted means the OS default. Held for the
      * phone's lifetime and NOT persisted — remembering a device is the host's call, so
@@ -299,25 +310,32 @@ type ClientMessage = {
     sdp: string;
 } | {
     type: 'call.answer';
+    req_id?: string;
     call_id: string;
 } | {
     type: 'call.reject';
+    req_id?: string;
     call_id: string;
     reason?: RejectReason;
 } | {
     type: 'call.hangup';
+    req_id?: string;
     call_id: string;
 } | {
     type: 'call.hold';
+    req_id?: string;
     call_id: string;
 } | {
     type: 'call.resume';
+    req_id?: string;
     call_id: string;
 } | {
     type: 'call.mute';
+    req_id?: string;
     call_id: string;
 } | {
     type: 'call.transfer';
+    req_id?: string;
     call_id: string;
     destination: string;
 } | {
@@ -329,6 +347,7 @@ type ClientMessage = {
     sdp?: string;
 } | {
     type: 'call.unmute';
+    req_id?: string;
     call_id: string;
 } | {
     type: 'sdp.offer';
@@ -476,6 +495,7 @@ type TransportEvents = {
         error?: PhoneError;
     }) => void;
     reconnecting: (attempt: number, delayMs: number) => void;
+    wake: () => void;
 };
 declare class Transport {
     private ws;
@@ -507,6 +527,11 @@ declare class Transport {
      */
     trySend(msg: ClientMessage): void;
     close(): void;
+    /**
+     * Abandon the current socket without ending the transport: its close runs the
+     * normal backoff reconnect. For an attempt that must not authenticate.
+     */
+    dropSocket(): void;
     private openSocket;
     private scheduleReconnect;
     private onWake;
@@ -525,6 +550,16 @@ type CallEventMap = {
     audioInputLost: () => void;
 };
 type Listener$1<K extends keyof CallEventMap> = CallEventMap[K];
+/**
+ * The slice of a local conference a merged `Call` needs. Declared structurally
+ * here (rather than importing `LocalConference`) so the core has no dependency
+ * on the mixer — `conference.ts` imports `Call`, and the reverse import would
+ * make that a cycle.
+ */
+interface ConferenceSink {
+    /** Apply mute across the merged legs' mixed uplinks. */
+    setMuted(muted: boolean): void;
+}
 interface CallInit {
     id: string;
     direction: CallDirection;
@@ -538,6 +573,8 @@ interface CallInit {
     ringback?: Ringback;
     audioInputDeviceId?: string;
     audioOutputDeviceId?: string;
+    deferInboundCapture?: boolean;
+    nextReqId: () => string;
 }
 declare class Call {
     id: string;
@@ -571,6 +608,9 @@ declare class Call {
      */
     get canSendDtmf(): boolean;
     private transport;
+    private readonly nextReqId;
+    private readonly issuedReqIds;
+    private readonly hangupReqIds;
     private readonly startConsult;
     private localStream;
     private remoteStream;
@@ -580,6 +620,7 @@ declare class Call {
     private listeners;
     private endedSettled;
     private pendingAnswerSdp;
+    private buildingAnswer;
     private answerSent;
     private wantsAnswer;
     private localMediaReady;
@@ -589,8 +630,25 @@ declare class Call {
     private readonly ringback;
     private remoteAudioFlowing;
     private audioInputDeviceId_;
+    private deferredAudioInput;
+    private conference;
     private switchChain;
+    private captureDeferred;
     constructor(init: CallInit);
+    /**
+     * Take the mic this call deliberately skipped on arrival, then produce the
+     * answer SDP from it.
+     *
+     * `buildAnswer` is what needs the track: setRemoteDescription created a
+     * track-less sender per m-line, and answering without attaching a real track
+     * yields `a=recvonly` — the far end hears nothing, which is the failure this
+     * whole path exists to avoid. It runs only once the offer has been set;
+     * otherwise prepareAnswerForOffer does it when the offer lands.
+     */
+    private acquireDeferredCapture;
+    /** Set by the owner to surface a late mic failure, since `Call` has no error event. */
+    private reportCaptureFailure;
+    onCaptureFailure(report: (e: unknown) => void): void;
     whenLocalMediaReady(): Promise<void>;
     private acquireLocalMedia;
     /** The selected mic, or null for the OS default. */
@@ -607,6 +665,7 @@ declare class Call {
     setAudioOutputDevice(deviceId: string | null): void;
     private watchCaptureTrack;
     private get isFinished();
+    private issueReqId;
     on<K extends keyof CallEventMap>(event: K, handler: Listener$1<K>): void;
     off<K extends keyof CallEventMap>(event: K, handler?: Listener$1<K>): void;
     answer(): void;
@@ -614,9 +673,40 @@ declare class Call {
     reject(reason?: RejectReason): void;
     hangup(): void;
     hold(): void;
+    /**
+     * Hold or resume this leg as part of holding the whole conference.
+     *
+     * `hold()` refuses while merged because holding ONE party silences it to the
+     * other. Holding every leg together is the coherent version, so the caller
+     * that does that reaches the frames through here.
+     */
+    setConferenceHold(held: boolean): void;
+    /**
+     * Re-hold a call `resume()` ran on in this same tick. `hold()`'s
+     * `state !== 'active'` guard would swallow it, since the state only flips on
+     * the server echo. Only for that unwind; use `hold()` everywhere else.
+     */
+    holdAfterResume(): void;
     resume(): void;
     mute(): void;
     unmute(): void;
+    /**
+     * Mute has two layers, and a merged call needs both handled differently.
+     *
+     * Normally: flip the mic track (instant local feedback) AND send `call.mute`,
+     * which the server turns into a re-INVITE narrowing the leg's SDP direction to
+     * `recvonly` — defence in depth against a peer that ignores the local disable.
+     *
+     * While MERGED neither of those works:
+     * - the wire carries the conference's mixed track, not this call's mic track,
+     *   so toggling `localStream` no longer reaches the far end (the mic is an
+     *   input to the mixer now). The conference toggles the mixed uplinks instead.
+     * - the server frame must be withheld: `recvonly` would stop this leg's
+     *   upstream media at the far end regardless of what the graph does, which is
+     *   silent one-way audio for the other conference parties. Muting a merged
+     *   call is a purely local mix decision.
+     */
+    private setMuted;
     sendDtmf(digits: string, duration?: number, interToneGap?: number): void;
     /**
      * Blind transfer: immediately redirect the remote party to `destination`.
@@ -640,10 +730,25 @@ declare class Call {
      */
     completeTransfer(): void;
     private assertTransferable;
-    get remoteMediaStream(): MediaStream;
+    get remoteMediaStream(): MediaStream$1;
+    /**
+     * The local capture (mic) stream. A local conference mixes against this rather
+     * than opening a second `getUserMedia`, so every merged leg shares the one
+     * capture the call already owns.
+     */
+    get localMediaStream(): MediaStream$1;
+    /**
+     * Attach (or detach, with null) the local conference this call is merged into.
+     *
+     * While attached, the wire carries the conference's MIXED track rather than
+     * this call's mic track, which changes what mute has to do — see `mute()`.
+     * Set by the conference owner (the softphone's merge action), not by the core.
+     */
+    attachConference(conference: ConferenceSink | null): void;
     startOutbound(): Promise<RTCSessionDescriptionInit>;
     prepareAnswerForOffer(sdp: string): Promise<void>;
     private buildAnswer;
+    private buildAnswerOnce;
     acceptRemoteProvisionalAnswer(sdp: string): Promise<boolean>;
     acceptRemoteAnswer(sdp: string): Promise<void>;
     addRemoteCandidate(candidate: string, sdpMid: string | null, sdpMLineIndex: number | null): Promise<void>;
@@ -680,6 +785,11 @@ type Listener<K extends keyof PhoneEventMap> = PhoneEventMap[K];
 declare class DialStackPhone {
     isConnected: boolean;
     readonly activeCalls: Call[];
+    /**
+     * A `connect()` is in flight but not yet connected. Consult alongside
+     * `isConnected`; a concurrent `connect()` joins the one in flight.
+     */
+    get isConnecting(): boolean;
     private token;
     private apiBaseUrl;
     private signalingUrl;
@@ -689,8 +799,12 @@ declare class DialStackPhone {
     private ringback;
     private createSignalingSocket;
     private onAppResume;
+    private deferInboundCapture;
     private transport;
     private readonly handshake;
+    private connectInFlight;
+    private tokenMint;
+    private tokenMintedAt;
     private iceServers;
     private listeners;
     private pendingOutbound;
@@ -749,6 +863,14 @@ declare class DialStackPhone {
      */
     private syncDeviceChangeSubscription;
     connect(): Promise<void>;
+    private openSession;
+    private tokenNeedsRefresh;
+    private tokenMsLeft;
+    private freshToken;
+    private mintToken;
+    private authenticateAfterMint;
+    private sendAuthenticate;
+    private awaitReconnect;
     disconnect(): void;
     /**
      * Tear down and reconnect, re-running the `authenticate` handshake. The new
@@ -768,6 +890,8 @@ declare class DialStackPhone {
     call(destination: string): Promise<Call>;
     private startConsult;
     private placeOutbound;
+    private endCallsOfLostSession;
+    private track;
     getCall(callId: string): Call | undefined;
     /**
      * Subscribe to presence (BLF) for an explicit, bounded set of users. The
@@ -847,6 +971,15 @@ declare class DialStackPhone {
      */
     clearEmergencyAddressRegisteredIp(id: string): Promise<void>;
     private nextReqId;
+    /**
+     * Replace the token for the NEXT connect, off the connected path — for a host
+     * that mints its own tokens and must (re)connect with a fresh one (boot,
+     * push-wake), which `onTokenExpiring` (live-session only) can't cover. Refuses
+     * while connected/connecting: swapping there would desync the local token from
+     * the one the server enforces and the session would die silently at expiry — to
+     * swap a live session's token, `disconnect()` then `setToken()` before `connect()`.
+     */
+    setToken(token: string): void;
     private adoptToken;
     private scheduleTokenRefresh;
     private fireTokenRefresh;
@@ -1095,37 +1228,19 @@ interface AppearanceOptions$1 {
  * the `appearance` prop flows through identically on both platforms.
  */
 
-/** Flat color set the Softphone paints from, after appearance is resolved. */
 interface SoftphonePalette {
-    /** Component background. */
     background: string;
-    /** Dial-pad key / control surface fill. */
     surface: string;
-    /** Surface fill while pressed/active. */
     surfaceActive: string;
-    /** Primary text (digits, destination, peer name). */
     text: string;
-    /** Secondary text (letter sub-labels, call state, hints). */
     textSecondary: string;
-    /** Hairline borders/dividers. */
     border: string;
-    /** Accent (links, focus ring, keypad/secondary control highlight). */
     accent: string;
-    /** Call / Answer (green) action color. */
     success: string;
-    /** Hang up / Decline (red) action color. */
     danger: string;
-    /** Warning / caution (amber) — used by the E911 banner. */
     warning: string;
-    /** Foreground used on top of accent/success/danger fills. */
     onAccent: string;
 }
-/**
- * Resolve the final palette from appearance: theme picks the base set, then any
- * `appearance.variables` overrides (the same keys other SDK components honor)
- * are layered on top. Unrecognized/absent variables fall back to the theme
- * default, so a bare `{ theme: 'dark' }` and a fully-specified palette both work.
- */
 declare function resolveSoftphonePalette(appearance?: AppearanceOptions$1): SoftphonePalette;
 
 /**
@@ -1180,6 +1295,9 @@ declare const en: {
         addCall: string;
         addCallPlaceholder: string;
         addCallSend: string;
+        merge: string;
+        split: string;
+        conferenceLabel: string;
         cancel: string;
         stateTrying: string;
         stateRinging: string;
@@ -2031,6 +2149,7 @@ declare const en: {
             perUser: string;
             perPhoneNumber: string;
             perVoiceAiLocation: string;
+            voiceAiPerLocationNote: string;
             perMonth: string;
             rateNotSet: string;
             pendingRate: string;
@@ -2179,6 +2298,19 @@ interface SoftphoneContextBase {
     completeAttendedTransfer: () => void;
     cancelAttendedTransfer: () => void;
     placeCall: (destination: string) => Promise<void>;
+    /** The calls bridged into a local three-way conference (empty when not merged). */
+    mergedCalls: Call[];
+    isMerged: boolean;
+    /** While merged, every remote party mixed — what the local user hears. */
+    conferenceAudio: MediaStream | null;
+    /** Whether merging is possible: two connected calls, no transfer, WebAudio present. */
+    canMerge: boolean;
+    mergeCalls: () => void;
+    splitMerge: () => void;
+    /** Hang up every leg of the conference (the merged UI shows one Hang up). */
+    hangupConference: () => void;
+    /** Hold or resume every leg of the conference together. */
+    holdConference: (held: boolean) => void;
     emergency: UseEmergencyBinding;
     emergencyManagedByHost: boolean;
     lastError: {
@@ -2193,52 +2325,476 @@ interface SoftphoneContextBase {
 }
 
 /**
- * SoftphoneProvider (React Native), same API as the web provider. Shared wiring
- * lives in SoftphoneProviderBase (from `@dialstack/sdk-react/core`); this
- * file adds only the native bits: the required `storage` adapter,
- * `locationProvider`, `appearance`/`defaultCountry`, and the InCallManager audio
- * session + ringtone.
+ * Its own module so `createPhone()` can use it without importing the provider
+ * (and React with it): a push-woken headless runtime has no renderer, yet it
+ * needs the same header or the ingress 403s its handshake.
+ */
+declare const nativeSignalingSocket: SignalingSocketFactory;
+
+type AudioOutputKind = 'earpiece' | 'speaker' | 'wired' | 'bluetooth' | 'car' | 'airplay' | 'other';
+interface AudioOutput {
+    id: string;
+    kind: AudioOutputKind;
+    name: string;
+}
+/**
+ * Call-audio routing, implemented by a host that owns call audio
+ * (`callAudio="host"`) over whatever its OS integration exposes.
+ *
+ * `current()` must be what the OS reports, never what was last requested: the
+ * route also changes from the CallKit/Telecom UI, a headset, or a car, and the
+ * softphone shows only this. It must return the same object until the route
+ * changes.
+ */
+interface AudioOutputController {
+    current(): AudioOutput | null;
+    onChange(listener: (output: AudioOutput | null) => void): () => void;
+    setSpeaker(on: boolean): Promise<void>;
+}
+interface UseAudioOutput {
+    supported: boolean;
+    current: AudioOutput | null;
+    speakerOn: boolean;
+    toggleSpeaker: () => void;
+}
+
+type CallAudioOwner = 'sdk' | 'host';
+
+/**
+ * The OS call surface (CallKit on iOS, Telecom on Android) as the bridge needs
+ * it — shaped by the bridge, not by any library. See the contract suite for
+ * what an adapter must guarantee.
+ */
+/** OS-side call identity: the UUID CallKit/Telecom track the call under. */
+type OsSessionId = string;
+interface OsIncomingCall {
+    callId: string;
+    /** Caller handle as the OS should display/dial it. */
+    from: string;
+    displayName?: string | null;
+}
+interface OsOutgoingCall {
+    /** The recipient handle the OS should display/dial. */
+    to: string;
+    displayName?: string | null;
+}
+/**
+ * Why the call ended, in the OS's vocabulary. `answeredElsewhere` /
+ * `declinedElsewhere` make the OS dismiss the ring silently instead of logging
+ * a missed call.
+ */
+type OsEndReason = 'remoteEnded' | 'unanswered' | 'answeredElsewhere' | 'declinedElsewhere' | 'failed' | 'unknown';
+/** Where the OS thinks a session is. `connecting` is answered but not yet reported connected. */
+type OsSessionStatus = 'ringing' | 'connecting' | 'connected' | 'ended';
+interface OsActiveSession {
+    sessionId: OsSessionId;
+    callId: string | null;
+    /**
+     * The OS's own view, for reconciling against the SDK call. Optional: an
+     * adapter that can't read it leaves it out and the bridge doesn't reconcile
+     * that field.
+     */
+    status?: OsSessionStatus;
+    held?: boolean;
+}
+interface OsCallEvents {
+    /**
+     * A call was reported to the OS — by native code before JS existed, or by
+     * `reportIncoming`. `callId` is the call_id the session was created with (a
+     * wake push's, or the one passed to `reportIncoming`): the bridge pairs the
+     * session with its call by it, and ends a session that has none.
+     */
+    incomingReported: (e: OsActiveSession) => void;
+    /** The OS wants to PLACE a call — the user dialled from the platform's own UI
+     *  (Recents, Siri, dialer intent), not from the app. */
+    callIntent: (e: {
+        handle: string;
+    }) => void;
+    answer: (e: {
+        sessionId: OsSessionId;
+    }) => void;
+    end: (e: {
+        sessionId: OsSessionId;
+    }) => void;
+    setHeld: (e: {
+        sessionId: OsSessionId;
+        held: boolean;
+    }) => void;
+    setMuted: (e: {
+        sessionId: OsSessionId;
+        muted: boolean;
+    }) => void;
+    dtmf: (e: {
+        sessionId: OsSessionId;
+        digits: string;
+    }) => void;
+    /** iOS only in practice: CallKit gates audio, so WebRTC audio starts here. */
+    audioSessionActivated: (e: {
+        sessionId: OsSessionId | null;
+    }) => void;
+}
+type OsCallEventName = keyof OsCallEvents;
+interface OsCallAdapter {
+    /** Resolves to the OS-assigned session id (the OS assigns, never the caller). */
+    reportIncoming(call: OsIncomingCall): Promise<OsSessionId>;
+    /**
+     * Report an outbound call so the OS holds a live session — on Android that
+     * starts the foreground service keeping the process and call alive when
+     * backgrounded, which an outbound call otherwise lacks.
+     */
+    reportOutgoing(call: OsOutgoingCall): Promise<OsSessionId>;
+    /** The call the OS is showing as incoming/dialling is now connected. */
+    reportConnected(sessionId: OsSessionId): Promise<void>;
+    /** Must not re-emit `end` — the bridge is telling the OS, not the other way round. */
+    reportEnded(sessionId: OsSessionId, reason: OsEndReason): Promise<void>;
+    /** Remote-initiated state only; the OS already knows about its own actions. */
+    setHeld(sessionId: OsSessionId, held: boolean): Promise<void>;
+    setMuted(sessionId: OsSessionId, muted: boolean): Promise<void>;
+    /** The session the OS currently treats as active, if any. */
+    getActiveSession(): Promise<OsActiveSession | null>;
+    /**
+     * The app's own Answer/End buttons go through the OS too, so every answer —
+     * lock screen, notification, car, watch, in-app — arrives as the same
+     * `answer`/`end` event and there is one code path, not two.
+     */
+    answer(sessionId: OsSessionId): Promise<void>;
+    end(sessionId: OsSessionId): Promise<void>;
+    on<K extends OsCallEventName>(event: K, listener: OsCallEvents[K]): () => void;
+}
+
+/**
+ * Where the bridge schedules its deadlines and retries. The JS timers are the
+ * default, but React Native on Android pauses them in an app that is
+ * backgrounded without being killed, even while a headless task runs. A wake
+ * whose call never arrives (answered or cancelled before the app re-registered)
+ * then waits on a deadline that never fires, and the OS keeps ringing. An
+ * integration that can schedule natively passes timers here.
+ */
+interface BridgeTimers {
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+
+/**
+ * "Keep this JS runtime alive" as a promise the platform can await.
+ *
+ * Android's HeadlessJsTaskService tears the runtime down the moment the task
+ * promise settles, so a wake holds this from the instant the task starts until
+ * live calls hit zero. What the hold actually covers is the gap before the call
+ * library's foreground service exists — once that is up it holds the process,
+ * and a ceiling reached mid-call ends only this task, not the call (measured: a
+ * 60s ring survived the then-45s ceiling untouched).
+ *
+ * So the ceiling is a bound on a wake that never delivers, not a correctness
+ * guarantee. It is set to the same 300s as the max park/ring, the service's task
+ * timeout, the OS answer deadline and the library's incoming-call timeout purely
+ * so the numbers don't contradict each other; keep them aligned.
  */
+declare class RuntimeHold {
+    private readonly ceilingMs;
+    private readonly timers;
+    private release;
+    private waiting;
+    constructor(ceilingMs?: number, timers?: BridgeTimers);
+    acquire(): Promise<void>;
+    releaseNow(): void;
+    /** Non-null while a hold is in flight — the reliable "a wake is mid-flight" signal. */
+    pending(): Promise<void> | null;
+    private settle;
+}
+
+/**
+ * What the bridge needs from a call. Overloads rather than a generic `on`: a
+ * generic over a narrower event map is not assignable from the SDK's wider one.
+ */
+interface BridgeCall {
+    readonly id: string;
+    readonly from: string;
+    readonly fromName: string | null;
+    readonly state: CallState;
+    readonly isMuted: boolean;
+    answer(): void;
+    reject(reason?: 'busy' | 'decline'): void;
+    hangup(): void;
+    hold(): void;
+    resume(): void;
+    mute(): void;
+    unmute(): void;
+    sendDtmf(digits: string): void;
+    on(event: 'answered' | 'resumed', handler: () => void): void;
+    on(event: 'held', handler: (by: HeldBy) => void): void;
+    on(event: 'ended', handler: (reason: CallEndReason) => void): void;
+    off(event: 'held' | 'resumed' | 'ended', handler: (...args: never[]) => void): void;
+}
+interface BridgePhoneError {
+    code?: string;
+    message?: string;
+    fatal?: boolean;
+    callId?: string | null;
+}
+/** What the bridge needs from the phone — `DialStackPhone` satisfies it. */
+interface BridgePhone {
+    readonly isConnected: boolean;
+    connect(): Promise<void>;
+    disconnect(): void;
+    setToken(token: string): void;
+    /** Place an outbound call. The bridge reports it to the OS around this. */
+    call(destination: string): Promise<BridgeCall>;
+    on(event: 'connected' | 'reconnected', handler: () => void): void;
+    on(event: 'disconnected', handler: (error?: unknown) => void): void;
+    on(event: 'reconnecting', handler: (attempt: number, delayMs: number) => void): void;
+    on(event: 'incoming', handler: (call: BridgeCall) => void): void;
+    on(event: 'error', handler: (err: BridgePhoneError) => void): void;
+}
+type AppLifecycleState = 'active' | 'background' | 'inactive' | 'unknown' | 'extension';
+/** Foreground/background as a port so the bridge has no react-native import. */
+interface AppLifecycle {
+    onChange(listener: (state: AppLifecycleState) => void): () => void;
+}
+interface NativeCallBridgeOptions {
+    phone: BridgePhone;
+    os: OsCallAdapter;
+    lifecycle?: AppLifecycle;
+    hold?: RuntimeHold;
+    log?: (message: string) => void;
+    /** From the OS report until `connect()` resolves: a socket that never comes up. */
+    registrationDeadlineMs?: number;
+    /**
+     * From `connect()` resolving until `incoming`. The proxy resumes a parked INVITE
+     * on REGISTER or within its 1s poll, so after this nothing is coming.
+     */
+    deliveryDeadlineMs?: number;
+    /** An OS answer held for a call that has not arrived yet is stale past this. */
+    answerTtlMs?: number;
+    /**
+     * How many calls the integration puts on the OS call screen at once (default 1).
+     * A second concurrent call past the cap is NOT reported to the OS but still
+     * rings and is answerable in-app; it just gets no OS session. Calls pair with
+     * sessions by call_id, so any value is safe; raising it is a product choice
+     * (OS call-waiting) and needs an adapter whose library holds several sessions.
+     */
+    maxOsCalls?: number;
+    /** Defaults to the JS timers; see `BridgeTimers` for when to pass native ones. */
+    timers?: BridgeTimers;
+    now?: () => number;
+}
+declare function toOsEndReason(reason: CallEndReason): OsEndReason;
+/**
+ * The bidirectional bridge between the OS call surface and the SDK (OS↔SDK
+ * answer/end/mute/hold/DTMF and lifecycle), and the only thing that subscribes to
+ * either. Works with no renderer: a push-woken headless runtime starts it like
+ * the app window does.
+ *
+ * ## Pairing a session with a call
+ *
+ * A call has one `call_id` everywhere: on the socket, in the wake webhook and on
+ * the INVITE a wake resumes. The OS mints its own session id at setup, and the
+ * bridge links it to that `call_id` (`ids`) the moment it knows both: when it
+ * reports a call itself, when an outbound call is placed, and when the OS
+ * reports a wake push's session (`incomingReported`, carrying the `call_id` the
+ * push delivered). Every lookup goes through that link; none guesses by
+ * position. A second session for a `call_id` already linked is the same call
+ * shown twice, and is ended.
+ *
+ * The contract this puts on the integrator: the wake push carries the
+ * webhook's `call_id`, and the OS adapter reports it on `incomingReported`.
+ */
+declare class NativeCallBridge {
+    readonly hold: RuntimeHold;
+    private readonly timers;
+    private readonly phone;
+    private readonly os;
+    private readonly lifecycle;
+    private readonly log;
+    private readonly registrationDeadlineMs;
+    private readonly deliveryDeadlineMs;
+    private readonly answerTtlMs;
+    private readonly maxOsCalls;
+    private readonly now;
+    private started;
+    private appState;
+    private reconnecting;
+    private readonly ids;
+    private readonly calls;
+    private readonly callErrorWaiters;
+    private readonly ending;
+    private readonly changingHold;
+    private reconcileTimer;
+    /** Outbound calls still being placed, so not yet in `calls`. */
+    private placingOutbound;
+    /** Calls this app placed. For these `answered` means the far end picked up. */
+    private readonly outboundCalls;
+    /** OS sessions created by a native wake report, before their call arrives on the socket. */
+    private readonly wakeSessions;
+    private readonly reportedToOs;
+    private readonly connectedReported;
+    /**
+     * An OS answer/decline that landed before the SDK had the call. On a wake the
+     * user taps within ~200ms while connect() takes seconds, so it's applied on arrival.
+     */
+    private readonly pendingAnswer;
+    private readonly pendingDecline;
+    private readonly answerDeadlines;
+    private readonly suppressHoldEcho;
+    private readonly wakeDeadlines;
+    private readonly reportingCalls;
+    private readonly traceLines;
+    private traceSnapshot;
+    private readonly traceListeners;
+    constructor(options: NativeCallBridgeOptions);
+    /** Idempotent. Call from the app entry on every path (window and headless). */
+    start(): void;
+    /**
+     * Resolving means the SIP AOR is REGISTERed, so a parked INVITE can reach us.
+     * The phone joins a connect already in flight, so this never starts a second
+     * one. Never `reconnect()` here — that disposes live calls.
+     *
+     * `forWake` is the corpse-proofing path: when the OS freezes a backgrounded app
+     * it can kill the WebSocket with no close frame reaching JS, so no `disconnected`
+     * fires and `isConnected` still reads "connected" over a dead socket. Trusting them never re-REGISTERs the AOR and the parked call is never
+     * re-forked. So a wake with NO live call sheds whatever socket state we hold and
+     * reconnects for real. A wake WITH a live call skips this: that call proves the
+     * socket and a teardown would drop it. A connect still in flight is joined, not
+     * shed: it has no stale socket to distrust, and its own timeouts bound it.
+     */
+    ensureConnected(forWake?: boolean): Promise<void>;
+    /** In-app Answer, routed through the OS so it converges on the one answer path. */
+    answer(callId: string): void;
+    /** In-app End/Decline, via the same convergence. */
+    end(callId: string): void;
+    /**
+     * Place an outbound call, reported to the OS FIRST so on Android the foreground
+     * service starts and the call survives backgrounding mid-dial (otherwise the OS
+     * reaps the process and drops the call). If placement fails we end the session
+     * we opened; from then on it rides the same `watchCall` lifecycle.
+     *
+     * An OS-initiated dial (`callIntent`) comes through here too, so both
+     * directions converge on one path.
+     */
+    call(destination: string, displayName?: string | null): Promise<BridgeCall>;
+    /** Ring buffer for a debug view; one-way, `useSyncExternalStore`-shaped. */
+    getTrace(): readonly string[];
+    subscribeTrace(listener: () => void): () => void;
+    private subscribePhone;
+    private onIncoming;
+    private applyHeld;
+    private reportIncoming;
+    private endDuplicateSession;
+    /**
+     * An OS answer we could not act on yet. The OS holds its answer request open
+     * meanwhile — CallKit keeps the incoming UI up, Telecom leaves the call in
+     * CONNECTING — so if no call ever arrives to consume it, say so rather than
+     * leaving the phone ringing until the adapter's own far longer deadline.
+     *
+     * Handle-stored and cleared by `forgetSession`, like the wake deadlines. It
+     * has to be: session ids are recycled, so a timer left armed past its own
+     * session fires against a LATER tap on the same id and reports a live call
+     * failed. `armedAt` is the second half of that — it pins the timer to the one
+     * tap it was armed for even if the map was refilled meanwhile.
+     */
+    private armAnswerDeadline;
+    private dropHeldAnswer;
+    private answerCall;
+    private reportConnectedReliably;
+    private watchCall;
+    private reportHold;
+    /**
+     * Hang up, and make sure the call ends. The SDK sends one frame; this retries
+     * one the server never answers and, once the attempts run out, ends the call
+     * here so the OS and the app don't keep a call nothing can reach.
+     *
+     * An error reply means the server has no such call, and the SDK ends it. A
+     * closed socket ends it too, through the lost session.
+     */
+    private endCall;
+    /**
+     * Hold or resume, confirmed. Resolves once the call's held/resumed arrives.
+     *
+     * The far end refusing on state (`invalid_message`) or a closed socket rejects
+     * at once and leaves the call alone. A failure on the server's side (far end
+     * unreachable) or no reply is retried; once the attempts run out the in-dialog
+     * route is dead and every other action would fail the same way, so the call is
+     * ended and the promise rejects.
+     */
+    private changeHold;
+    private confirmHold;
+    private attempt;
+    /** The pause after a failed attempt; none after the last, which has nothing to wait for. */
+    private backoffAfter;
+    private abandonCall;
+    private teardownCall;
+    private reportEndedReliably;
+    private subscribeOs;
+    private onIncomingReported;
+    private armWakeDeadline;
+    private forgetSession;
+    private wakeInFlight;
+    /** How many OS-reported calls are still live — the OS's session count. */
+    private liveOsCallCount;
+    private linkOsSession;
+    /**
+     * Check, shortly after a change, that the OS shows what the call is.
+     *
+     * Every OS report above is retried when it fails, but a report the OS takes
+     * and then doesn't act on goes unseen: iOS accepts a connected report for an
+     * incoming call and keeps it ringing. So compare what the OS says it shows
+     * with the call, and correct the OS; the call's state is the server's, and
+     * the OS follows it.
+     *
+     * Only the session the OS calls active is read, since that is all the port
+     * offers. It is the one on screen, and with the default of one OS call it is
+     * every session there is.
+     */
+    private scheduleReconcile;
+    private reconcile;
+    private reconcileConnected;
+    private reconcileHeld;
+    private callForSession;
+    private subscribeLifecycle;
+    private dropRegistrationIfIdle;
+    private trace;
+}
+
+/** SoftphoneProvider (React Native), same API as the web provider. */
 
 type AppearanceOptions = Parameters<typeof resolveSoftphonePalette>[0];
 type ConnectionState = SoftphoneConnectionState;
 interface SoftphoneProviderProps {
+    /**
+     * Adopt an existing phone instead of constructing one from `token`, for a
+     * native call surface where a call can exist before any phone does. Neither
+     * connected nor disconnected by the provider.
+     */
+    existingPhone?: DialStackPhone | null;
     /** WebRTC user session token. */
     token: string;
     /**
-     * Persistence for the selected E911 address id, so it survives app restarts.
-     * REQUIRED on React Native: the SDK takes no persistence dependency of its own
-     * (react-native-mmkv and AsyncStorage vary by version/architecture and can't be
-     * defaulted safely), so the host supplies a small `PlatformStorage` adapter —
-     * typically MMKV- or AsyncStorage-backed. See the example apps for reference
-     * adapters; a synchronous in-memory adapter is also valid if you don't need
-     * persistence. It only stores the E911 id, nothing sensitive.
+     * Persistence for the selected E911 address id. REQUIRED on RN: the SDK takes
+     * no persistence dependency of its own. A synchronous in-memory adapter is
+     * valid if you don't need persistence.
      */
     storage: PlatformStorage;
     /** API base URL (defaults to the SDK's production endpoint). */
     apiBaseUrl?: string;
     /**
-     * Called shortly before the session token expires (about 60 seconds ahead).
-     * Return a fresh token minted by your backend; the SDK delivers it in-band over
-     * the existing connection — no reconnect and no call disruption. If it rejects,
-     * the SDK keeps the (still-valid) connection open and surfaces an `error`.
+     * Called shortly before the session token expires. Return a fresh token; the
+     * SDK delivers it in-band with no reconnect. On reject the SDK keeps the
+     * still-valid connection and surfaces an `error`.
      */
     onTokenExpiring?: () => Promise<string>;
-    /** Emergency (E911) address id to present on connect; when supplied the host
-     *  manages E911 and the built-in prompt is disabled. */
+    /** E911 address id to present on connect; when supplied the host manages E911
+     *  and the built-in prompt is disabled. */
     emergencyAddressId?: string;
     /**
-     * Optional device-location source for the E911 form. When provided, the
-     * built-in emergency-address form shows a "Use my current location" action
-     * that calls this to prefill the address fields; the host owns the location
-     * permission prompt, geolocation, and reverse-geocoding. Omit for manual entry.
+     * Device-location source for the E911 form's "Use my current location" action;
+     * the host owns the permission prompt, geolocation, and reverse-geocoding.
      */
     locationProvider?: () => Promise<EmergencyAddressInput>;
     /** Connect automatically once mounted (default: true). */
     autoConnect?: boolean;
-    /** Theming — the shared appearance surface (same as the web softphone). */
+    /** Theming — the shared appearance surface. */
     appearance?: AppearanceOptions;
-    /** Locale for UI strings (defaults to English), same surface as the web softphone. */
+    /** Locale for UI strings (defaults to English). */
     locale?: Locale;
     /** Default country for number formatting. */
     defaultCountry?: CountryCode;
@@ -2246,6 +2802,9 @@ interface SoftphoneProviderProps {
         state: ConnectionState;
     }) => void;
     onIncomingCall?: (event: {
+        /** Handle for `callActionsFor()` / `answerCall()`, and what a host bridging
+         *  to a native call UI binds its OS session to. */
+        callId: string;
         from: string;
         fromName: string | null;
     }) => void;
@@ -2260,17 +2819,39 @@ interface SoftphoneProviderProps {
         code: string;
         message: string;
     }) => void;
+    /**
+     * The call bridge, when this app reports calls to the OS. Outbound placement
+     * then goes through it, so the OS learns about the call BEFORE it is dialled —
+     * on Android that report is what starts the foreground service, without which
+     * backgrounding mid-dial lets the OS reap the process and drop the call.
+     * Answering in-app goes through it too, so the OS answers before the call
+     * starts media (on iOS that is what gives the call its audio).
+     */
+    bridge?: Pick<NativeCallBridge, 'call' | 'answer'>;
+    /**
+     * Who owns call audio: ringing, outbound ringback, the audio session and the
+     * proximity sensor. `'sdk'` (the default): the provider does all of it.
+     * `'host'`: the provider does none of it, for an app that reports calls to
+     * CallKit/Telecom itself, which ring the phone and own the session. Doing any
+     * of it on top of the OS breaks capture. Always `'host'` with a `bridge`.
+     */
+    callAudio?: CallAudioOwner;
+    /**
+     * The output route, for a host that owns call audio: without it the in-call
+     * speaker button is disabled, since only the OS integration can move the
+     * route. Ignored unless call audio is `'host'`.
+     */
+    audioOutput?: AudioOutputController;
     children: React.ReactNode;
 }
-/**
- * The native softphone context: the shared base plus the native-only
- * `locationProvider`. (`palette` is on the base — computed identically to web.)
- */
+/** The native softphone context: the shared base plus the native-only
+ *  `locationProvider`. */
 interface SoftphoneContextValue extends SoftphoneContextBase {
     /** Host-supplied device-location source for the E911 form, or undefined. */
     locationProvider: (() => Promise<EmergencyAddressInput>) | undefined;
+    audio: UseAudioOutput;
 }
-declare function SoftphoneProvider({ token, storage, apiBaseUrl, onTokenExpiring, emergencyAddressId, locationProvider, autoConnect, appearance, locale, defaultCountry, onConnectionStateChange, onIncomingCall, onCallStarted, onCallEnded, onError, children, }: SoftphoneProviderProps): React.JSX.Element;
+declare function SoftphoneProvider({ existingPhone, token, storage, apiBaseUrl, onTokenExpiring, emergencyAddressId, locationProvider, autoConnect, appearance, locale, defaultCountry, onConnectionStateChange, onIncomingCall, onCallStarted, onCallEnded, onError, bridge, callAudio: requestedCallAudio, audioOutput, children, }: SoftphoneProviderProps): React.JSX.Element;
 /** Access the full softphone context. Throws when used outside the provider. */
 declare function useSoftphone(): SoftphoneContextValue;
 /** The active foreground call + its actions (build-your-own convenience). */
@@ -2278,6 +2859,8 @@ declare function useActiveCall(): {
     activeCall: Call | null;
     actions: UseCallActions;
 };
+/** The call-audio output route and the speaker toggle. */
+declare function useAudioOutput(): UseAudioOutput;
 /** The currently-ringing inbound call, or null. */
 declare function useIncomingCall(): Call | null;
 
@@ -2317,10 +2900,10 @@ declare function Softphone({ autoFocusDestination }: SoftphoneProps): React.JSX.
  */
 
 interface DialPadProps {
-    /** Autofocus the destination field on mount. */
     autoFocusDestination?: boolean;
+    compact?: boolean;
 }
-declare function DialPad({ autoFocusDestination }: DialPadProps): React.JSX.Element;
+declare function DialPad({ autoFocusDestination, compact, }: DialPadProps): React.JSX.Element;
 
 /**
  * IncomingCall / IncomingStack (RN) — the ringing inbound UI.
@@ -2363,5 +2946,38 @@ declare function OngoingCall(): React.JSX.Element | null;
 
 declare function EmergencyBanner(): React.JSX.Element | null;
 
-export { Call, DialPad, EmergencyBanner, IncomingCall, OngoingCall, Softphone, SoftphoneProvider, useActiveCall, useIncomingCall, useSoftphone };
-export type { CallEndReason, CallState, ConnectionState, DialPadProps, EmergencyAddressInput, PlatformStorage, SoftphoneContextValue, SoftphoneProps, SoftphoneProviderProps, UseCallActions };
+type CreatePhoneOptions = Omit<PhoneOptions, 'createSignalingSocket' | 'deferInboundCapture'>;
+/**
+ * The process's one phone.
+ *
+ * Module scope is the correct scope, not a shortcut: a push wake and the UI run
+ * in the same JS runtime but enter from different places (a headless task, the
+ * app window), so this is a plain shared reference. Two phones would register
+ * the same SIP AOR twice and the call would go to whichever registered last
+ * while the UI watched the other — a silent failure, so a second construction
+ * fails loudly instead. Construct eagerly at app entry: `new DialStackPhone()`
+ * does no I/O (only `connect()` does).
+ */
+declare function createPhone(options: CreatePhoneOptions): DialStackPhone;
+declare function getPhone(): DialStackPhone | null;
+/** For consumers that must not be the one to create it (the UI). */
+declare function requirePhone(): DialStackPhone;
+
+declare const appLifecycle: AppLifecycle;
+declare const DEFAULT_WAKE_TASK = "DialStackWake";
+/**
+ * Android's wake: the adapter's native push service reports the call to Telecom
+ * with no JS, and something must then start a runtime so the SDK can
+ * re-REGISTER and receive the parked INVITE. That is this headless task; the
+ * app's HeadlessJsTaskService names it (`taskName`).
+ *
+ * iOS has no equivalent — PushKit launches the process and React Native starts
+ * normally, so the app entry's `bridge.start()` is the whole wake path.
+ *
+ * A single file with a runtime branch rather than `.android.ts`/`.ios.ts`: the
+ * package ships as one bundle, so Metro's platform extensions cannot apply.
+ */
+declare function registerWakeTask(bridge: NativeCallBridge, taskName?: string): void;
+
+export { Call, DEFAULT_WAKE_TASK, DialPad, EmergencyBanner, IncomingCall, NativeCallBridge, OngoingCall, RuntimeHold, Softphone, SoftphoneProvider, appLifecycle, createPhone, getPhone, nativeSignalingSocket, registerWakeTask, requirePhone, toOsEndReason, useActiveCall, useAudioOutput, useIncomingCall, useSoftphone };
+export type { AppLifecycle, AppLifecycleState, AudioOutput, AudioOutputController, AudioOutputKind, BridgeCall, BridgePhone, BridgePhoneError, BridgeTimers, CallEndReason, CallState, ConnectionState, CreatePhoneOptions, DialPadProps, EmergencyAddressInput, NativeCallBridgeOptions, OsActiveSession, OsCallAdapter, OsCallEventName, OsCallEvents, OsEndReason, OsIncomingCall, OsOutgoingCall, OsSessionId, OsSessionStatus, PlatformStorage, SoftphoneContextValue, SoftphoneProps, SoftphoneProviderProps, UseAudioOutput, UseCallActions };