@dialstack/sdk-native 0.1.1 → 0.2.0

package/dist/testing.d.ts

@@ -0,0 +1,361 @@
+/**
+ * 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;
+}
+
+interface FakeOsCallAdapterOptions {
+    /** expo-callkit-telecom re-emits its own set* actions; default on so the bridge is tested against that. */
+    echoSetActions?: boolean;
+    /**
+     * Whether the OS library accepts more than one concurrent call session. Default
+     * false models the shipped expo-callkit-telecom / callkeep adapters, which
+     * reject a second reportIncoming ("one call at a time"). Set true to model a
+     * library that accepts call-waiting — used to test that the bridge itself stays
+     * agnostic and reports a second call rather than enforcing single-call.
+     */
+    multiCall?: boolean;
+}
+/**
+ * In-memory OS. The `os` side (`nativeReportIncoming`, `answer`, `end`, …)
+ * plays the platform: it is what a test drives, and what a real adapter's
+ * native code does on a device.
+ */
+declare class FakeOsCallAdapter implements OsCallAdapter {
+    private readonly listeners;
+    private readonly queued;
+    private readonly sessions;
+    private readonly echo;
+    private readonly multiCall;
+    private minted;
+    readonly log: string[];
+    private readonly injectedFailures;
+    private readonly ignored;
+    constructor(options?: FakeOsCallAdapterOptions);
+    reportIncoming(call: OsIncomingCall): Promise<OsSessionId>;
+    reportOutgoing(call: OsOutgoingCall): Promise<OsSessionId>;
+    reportConnected(sessionId: OsSessionId): Promise<void>;
+    reportEnded(sessionId: OsSessionId, reason: OsEndReason): Promise<void>;
+    setHeld(sessionId: OsSessionId, held: boolean): Promise<void>;
+    setMuted(sessionId: OsSessionId, muted: boolean): Promise<void>;
+    getActiveSession(): Promise<OsActiveSession | null>;
+    private view;
+    on<K extends OsCallEventName>(event: K, listener: OsCallEvents[K]): () => void;
+    /**
+     * Native reported the call before any JS existed (FCM service / PushKit handler).
+     *
+     * `callId` is the call_id the wake push carried, reported on
+     * `incomingReported` so the bridge can pair the session with its call. Pass
+     * `callId: null` for a push that carried none.
+     */
+    nativeReportIncoming(session: OsActiveSession): void;
+    /** The user dialled from the OS's own UI (Recents / Siri / dialer). */
+    nativeCallIntent(handle: string): void;
+    /**
+     * The user answered, from the OS surface or via the adapter's `answer`.
+     *
+     * Modelled as a REQUEST, which is what both platforms do: CallKit's
+     * CXAnswerCallAction and Telecom's answer leave the call alerting until the
+     * app reports it connected. Forgetting that report is invisible in a unit test
+     * that only checks the SDK call answered — but on a device it is a phone that
+     * never stops ringing, so the fake tracks it and `stillAlerting()` asserts it.
+     */
+    answer(sessionId: OsSessionId): Promise<void>;
+    /**
+     * Sessions the user answered that were never reported connected — the OS is
+     * still showing its incoming UI for each one.
+     */
+    stillAlerting(): OsSessionId[];
+    /** The user ended/declined from the OS surface. The session is gone from the OS's view. */
+    end(sessionId: OsSessionId): Promise<void>;
+    hold(sessionId: OsSessionId, held: boolean): void;
+    mute(sessionId: OsSessionId, muted: boolean): void;
+    dtmf(sessionId: OsSessionId, digits: string): void;
+    /**
+     * The OS dropped a report it accepted: the session stays where it was, as iOS
+     * leaves an incoming call ringing after a connected report.
+     */
+    ignoreNext(op: 'reportConnected' | 'setHeld', times?: number): void;
+    isConnected(sessionId: OsSessionId): boolean;
+    sessionCount(): number;
+    /** Make the next `times` calls to adapter method `op` reject, as a real OS layer can. */
+    failNext(op: keyof OsCallAdapter, times?: number): void;
+    private maybeFail;
+    private takeIgnored;
+    private require;
+    private emit;
+}
+
+/**
+ * The OS side of an adapter under test: what native code or the user does.
+ * For the fake this is the fake itself; for a real adapter it is whatever the
+ * integrator's test rig uses to drive the platform (a mocked native module, or
+ * a device).
+ */
+interface OsCallHarness {
+    nativeReportIncoming(session: OsActiveSession): void | Promise<void>;
+}
+interface OsCallAdapterFixture {
+    adapter: OsCallAdapter;
+    os: OsCallHarness;
+}
+/** The subset of jest/vitest the suite needs, injected so the SDK declares no test-runner types. */
+interface TestApi {
+    describe: (name: string, fn: () => void) => void;
+    it: (name: string, fn: () => Promise<void>) => void;
+    expect: (actual: unknown) => {
+        toBe(expected: unknown): void;
+        toEqual(expected: unknown): void;
+        toBeNull(): void;
+        toHaveLength(n: number): void;
+        toBeLessThanOrEqual(n: number): void;
+    };
+}
+/**
+ * What the bridge assumes of every adapter. An adapter that passes this can be
+ * dropped in for the shipped one; one that fails it will show up as the
+ * intermittent "answer does nothing" class of bug, so run it before a device.
+ */
+declare function runOsCallAdapterContract(name: string, t: TestApi, fixture: () => OsCallAdapterFixture | Promise<OsCallAdapterFixture>): void;
+
+type CallState = 'trying' | 'ringing' | 'active' | 'held' | 'ended';
+type CallEndReason = 'hangup' | 'no-answer' | 'busy' | 'failed' | 'transferred' | 'rejected';
+type HeldBy = 'local' | 'remote';
+
+/**
+ * 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;
+}
+
+declare class FakeCall implements BridgeCall {
+    readonly id: string;
+    readonly from: string;
+    state: CallState;
+    isMuted: boolean;
+    readonly fromName: string | null;
+    readonly actions: string[];
+    private readonly handlers;
+    constructor(id: string, from?: string);
+    /**
+     * Off: hold, resume and hangup only send, like the SDK's; the outcome comes
+     * later as an event or a phone error. On: they take effect at once.
+     */
+    autoConfirm: boolean;
+    /** Set to make answer() throw once, for the answer-failure path. */
+    failAnswer: boolean;
+    /** Make the next call to one of these fail the way the SDK's does. */
+    readonly failNext: Partial<Record<'reject' | 'hold' | 'resume' | 'mute' | 'unmute' | 'dtmf', Error>>;
+    private takeFailure;
+    answer(): void;
+    reject(reason?: 'busy' | 'decline'): void;
+    hangup(): void;
+    hold(): void;
+    resume(): void;
+    mute(): void;
+    unmute(): void;
+    sendDtmf(digits: string): void;
+    on(event: string, handler: (...args: never[]) => void): void;
+    off(event: string, handler: (...args: never[]) => void): void;
+    emitAnswered(): void;
+    emitHeld(by: HeldBy): void;
+    emitResumed(): void;
+    emitEnded(reason: CallEndReason): void;
+    private emit;
+}
+declare class FakePhone implements BridgePhone {
+    isConnected: boolean;
+    connectCalls: number;
+    disconnectCalls: number;
+    /** Set before connect() is called to make it fail. */
+    failConnectWith: Error | null;
+    /** Set to hold connect() open until `resolveConnect()`. */
+    manualConnect: boolean;
+    private resolvePending;
+    private pendingConnect;
+    private readonly handlers;
+    connect(): Promise<void>;
+    resolveConnect(): void;
+    tokens: string[];
+    setToken(token: string): void;
+    /** Set to make the next call() reject, for the placement-failure path. */
+    failCallWith: Error | null;
+    outboundCalls: string[];
+    callResult: FakeCall | null;
+    /** Set to hold call() open until `resolveCall()`. */
+    manualCall: boolean;
+    private resolvePendingCall;
+    call(destination: string): Promise<FakeCall>;
+    resolveCall(): void;
+    disconnect(): void;
+    /**
+     * The OS froze the backgrounded app and killed the socket with no close frame:
+     * the transport is dead but `isConnected` still reads true and NO 'disconnected'
+     * fires. Models the corpse the wake path must not trust.
+     */
+    killSocketSilently(): void;
+    /**
+     * The socket dropped and the transport is between automatic reconnect attempts:
+     * neither connected nor connecting, and no 'disconnected' fires.
+     */
+    startReconnecting(): void;
+    on(event: string, handler: (...args: never[]) => void): void;
+    emitIncoming(call: FakeCall): void;
+    /** A server error frame, which the SDK names a call on when it can. */
+    emitError(err: {
+        code?: string;
+        message?: string;
+        callId?: string | null;
+    }): void;
+    private emit;
+}
+declare class FakeLifecycle implements AppLifecycle {
+    private listeners;
+    onChange(listener: (state: AppLifecycleState) => void): () => void;
+    set(state: AppLifecycleState): void;
+}
+
+/** Test-only: the app never has a valid reason to forget its phone. */
+declare function resetPhoneForTests(): void;
+
+export { FakeCall, FakeLifecycle, FakeOsCallAdapter, FakePhone, resetPhoneForTests, runOsCallAdapterContract };
+export type { FakeOsCallAdapterOptions, OsCallAdapterFixture, OsCallHarness, TestApi };