@poolse/react-native-calls 0.1.3 → 0.3.0

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":["requireOptionalNativeModule"],"mappings":";;;;;AAqEA,IAAM,MAAA,GAASA,4CAA+C,aAAa,CAAA;AAGpE,IAAM,uBAAuB,MAAA,IAAU;AAG9C,eAAsB,SAAA,CAAU,YAAoB,OAAA,EAA2C;AAC7F,EAAA,MAAM,MAAA,EAAQ,SAAA,CAAU,UAAA,EAAY,OAAA,IAAW,IAAI,CAAA;AACrD;AAGO,SAAS,YAAA,GAAgC;AAC9C,EAAA,OAAO,MAAA,EAAQ,YAAA,EAAa,CAAE,QAAA,IAAY,IAAA;AAC5C;AAKO,SAAS,YAAY,EAAA,EAAsD;AAChF,EAAA,IAAI,CAAC,MAAA,EAAQ,OAAO,MAAM,MAAA;AAC1B,EAAA,MAAM,GAAA,GAAM,OAAO,WAAA,CAAY,aAAA,EAAe,CAAC,OAAA,KAAY,EAAA,CAAG,OAAA,CAAQ,QAAQ,CAAC,CAAA;AAC/E,EAAA,OAAO,MAAM,IAAI,MAAA,EAAO;AAC1B;AAEO,SAAS,KAAA,CAAM,gBAAwB,OAAA,EAAsC;AAClF,EAAA,OAAO,MAAA,EAAQ,MAAM,cAAA,EAAgB,OAAA,CAAQ,OAAO,OAAA,CAAQ,YAAY,CAAA,IAAK,OAAA,CAAQ,OAAA,EAAQ;AAC/F;AAEO,SAAS,IAAA,CACd,MAAA,EACA,cAAA,EACA,YAAA,EACe;AACf,EAAA,OAAO,QAAQ,IAAA,CAAK,MAAA,EAAQ,gBAAgB,YAAY,CAAA,IAAK,QAAQ,OAAA,EAAQ;AAC/E;AAEO,IAAM,MAAA,GAAS,MAAY,MAAA,EAAQ,MAAA;AACnC,IAAM,OAAA,GAAU,MAAY,MAAA,EAAQ,OAAA;AACpC,IAAM,MAAA,GAAS,MAAY,MAAA,EAAQ,MAAA;AACnC,IAAM,QAAA,GAAW,CAAC,KAAA,KAAyB,MAAA,EAAQ,SAAS,KAAK;AACjE,IAAM,SAAA,GAAY,CAAC,EAAA,KAAsB,MAAA,EAAQ,UAAU,EAAE;AAC7D,IAAM,YAAA,GAAe,MAAY,MAAA,EAAQ,YAAA","file":"index.cjs","sourcesContent":["// @poolse/react-native-calls — the React Native face of the native\n// call core (CONTRACT.md §8). A thin, typed surface over the native\n// module: commands in, one snapshot event out. All call logic lives in\n// the native cores; nothing here decides anything about a call.\n//\n// On a platform or build without the native module (Expo Go, web,\n// unlinked), every command is a safe no-op and the state stays idle —\n// so a host can render against this unconditionally.\nimport { requireOptionalNativeModule } from 'expo-modules-core';\n\n/** A call's complete state. `null` means idle — no call. */\nexport interface Snapshot {\n  cv: 1;\n  callId: string;\n  conversationId: string;\n  conversationName: string | null;\n  direction: 'incoming' | 'outgoing' | 'joined';\n  media: 'audio' | 'video';\n  phase: 'ringing_in' | 'ringing_out' | 'connecting' | 'active' | 'reconnecting' | 'ended';\n  reason?:\n    | 'left'\n    | 'finished'\n    | 'declined_all'\n    | 'busy_all'\n    | 'no_answer'\n    | 'cancelled'\n    | 'connection_lost'\n    | 'failed';\n  participants: Array<{\n    userId: string;\n    externalId: string;\n    speaking: boolean;\n    muted: boolean;\n    cameraOn: boolean;\n  }>;\n  audioRoute: 'earpiece' | 'speaker' | 'bluetooth' | 'headset';\n  mutedSelf: boolean;\n  cameraOn: boolean;\n}\n\nexport interface ConfigureOptions {\n  /** Drawable resource NAME for the call notification's small icon. */\n  smallIcon?: string;\n  /** Raw resource NAME of the ringback tone (Android). */\n  ringback?: string;\n}\n\nexport interface PlaceOptions {\n  media: 'audio' | 'video';\n  /** The user's session token — authorizes placing/joining (CONTRACT.md §3.2). */\n  sessionToken: string;\n}\n\ntype NativeSnapshot = { snapshot: Snapshot | null };\n\ninterface PoolseCallsNative {\n  configure(apiBaseUrl: string, options: ConfigureOptions | null): Promise<void>;\n  getCallState(): NativeSnapshot;\n  place(conversationId: string, media: string, sessionToken: string): Promise<void>;\n  join(callId: string, conversationId: string | null, sessionToken: string): Promise<void>;\n  answer(): void;\n  decline(): void;\n  hangUp(): void;\n  setMuted(muted: boolean): void;\n  setCamera(on: boolean): void;\n  switchCamera(): void;\n  addListener(event: 'onCallState', cb: (payload: NativeSnapshot) => void): { remove(): void };\n}\n\nconst native = requireOptionalNativeModule<PoolseCallsNative>('PoolseCalls');\n\n/** True when the native call core is present in this build. */\nexport const nativeCallsAvailable = native != null;\n\n/** Configure once, before any call can arrive. No secrets — just the API origin. */\nexport async function configure(apiBaseUrl: string, options?: ConfigureOptions): Promise<void> {\n  await native?.configure(apiBaseUrl, options ?? null);\n}\n\n/** The current snapshot — safe to read at any moment, including cold answer. */\nexport function getCallState(): Snapshot | null {\n  return native?.getCallState().snapshot ?? null;\n}\n\nexport type Unsubscribe = () => void;\n\n/** Subscribe to call state. Fires a full snapshot on every change. */\nexport function onCallState(cb: (snapshot: Snapshot | null) => void): Unsubscribe {\n  if (!native) return () => undefined;\n  const sub = native.addListener('onCallState', (payload) => cb(payload.snapshot));\n  return () => sub.remove();\n}\n\nexport function place(conversationId: string, options: PlaceOptions): Promise<void> {\n  return native?.place(conversationId, options.media, options.sessionToken) ?? Promise.resolve();\n}\n\nexport function join(\n  callId: string,\n  conversationId: string | null,\n  sessionToken: string,\n): Promise<void> {\n  return native?.join(callId, conversationId, sessionToken) ?? Promise.resolve();\n}\n\nexport const answer = (): void => native?.answer();\nexport const decline = (): void => native?.decline();\nexport const hangUp = (): void => native?.hangUp();\nexport const setMuted = (muted: boolean): void => native?.setMuted(muted);\nexport const setCamera = (on: boolean): void => native?.setCamera(on);\nexport const switchCamera = (): void => native?.switchCamera();\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":["requireOptionalNativeModule","requireNativeViewManager","createElement","View"],"mappings":";;;;;;;AAqFA,IAAM,MAAA,GAASA,4CAA+C,aAAa,CAAA;AAGpE,IAAM,uBAAuB,MAAA,IAAU;AAG9C,eAAsB,SAAA,CAAU,YAAoB,OAAA,EAA2C;AAC7F,EAAA,MAAM,MAAA,EAAQ,SAAA,CAAU,UAAA,EAAY,OAAA,IAAW,IAAI,CAAA;AACrD;AAGO,SAAS,YAAA,GAAgC;AAC9C,EAAA,OAAO,MAAA,EAAQ,YAAA,EAAa,CAAE,QAAA,IAAY,IAAA;AAC5C;AAKO,SAAS,YAAY,EAAA,EAAsD;AAChF,EAAA,IAAI,CAAC,MAAA,EAAQ,OAAO,MAAM,MAAA;AAC1B,EAAA,MAAM,GAAA,GAAM,OAAO,WAAA,CAAY,aAAA,EAAe,CAAC,OAAA,KAAY,EAAA,CAAG,OAAA,CAAQ,QAAQ,CAAC,CAAA;AAC/E,EAAA,OAAO,MAAM,IAAI,MAAA,EAAO;AAC1B;AAEO,SAAS,KAAA,CAAM,gBAAwB,OAAA,EAAsC;AAClF,EAAA,OAAO,MAAA,EAAQ,MAAM,cAAA,EAAgB,OAAA,CAAQ,OAAO,OAAA,CAAQ,YAAY,CAAA,IAAK,OAAA,CAAQ,OAAA,EAAQ;AAC/F;AAEO,SAAS,IAAA,CACd,MAAA,EACA,cAAA,EACA,YAAA,EACe;AACf,EAAA,OAAO,QAAQ,IAAA,CAAK,MAAA,EAAQ,gBAAgB,YAAY,CAAA,IAAK,QAAQ,OAAA,EAAQ;AAC/E;AAEO,IAAM,MAAA,GAAS,MAAY,MAAA,EAAQ,MAAA;AACnC,IAAM,OAAA,GAAU,MAAY,MAAA,EAAQ,OAAA;AACpC,IAAM,MAAA,GAAS,MAAY,MAAA,EAAQ,MAAA;AACnC,IAAM,QAAA,GAAW,CAAC,KAAA,KAAyB,MAAA,EAAQ,SAAS,KAAK;AACjE,IAAM,SAAA,GAAY,CAAC,EAAA,KAAsB,MAAA,EAAQ,UAAU,EAAE;AAC7D,IAAM,YAAA,GAAe,MAAY,MAAA,EAAQ,YAAA;AAEzC,IAAM,UAAA,GAAa,CAAC,EAAA,KAAsB,MAAA,EAAQ,WAAW,EAAE;AAM/D,IAAM,cAAc,CAAC,MAAA,EAAgB,WAC1C,MAAA,EAAQ,WAAA,CAAY,QAAQ,MAAM;AAQ7B,IAAM,cAAA,GAAiB,CAAC,MAAA,EAAgB,MAAA,KAC7C,QAAQ,cAAA,CAAe,MAAA,EAAQ,UAAU,IAAI;AAMxC,IAAM,sBAAA,GAAyB,MAAe,MAAA,EAAQ,sBAAA,EAAuB,IAAK;AAGlF,IAAM,4BAAA,GAA+B,MAAY,MAAA,EAAQ,4BAAA;AAgBhE,IAAI,WAAA;AAGJ,SAAS,eAAA,GAA0D;AACjE,EAAA,IAAI,WAAA,KAAgB,QAAW,OAAO,WAAA;AACtC,EAAA,WAAA,GAAc,IAAA;AACd,EAAA,IAAI,MAAA,EAAQ;AACV,IAAA,IAAI;AACF,MAAA,WAAA,GAAcC,wCAAA,CAA2C,eAAe,iBAAiB,CAAA;AAAA,IAC3F,CAAA,CAAA,MAAQ;AACN,MAAA,WAAA,GAAc,IAAA;AAAA,IAChB;AAAA,EACF;AACA,EAAA,OAAO,WAAA;AACT;AAQO,SAAS,cAAc,KAAA,EAAgD;AAC5E,EAAA,MAAM,SAAS,eAAA,EAAgB;AAC/B,EAAA,IAAI,CAAC,MAAA,EAAQ;AACX,IAAA,MAAM,EAAE,aAAA,EAAe,EAAA,EAAI,KAAA,EAAO,EAAA,EAAI,MAAA,EAAQ,EAAA,EAAI,GAAA,EAAK,EAAA,EAAI,GAAG,IAAA,EAAK,GAAI,KAAA;AACvE,IAAA,OAAOC,mBAAA,CAAcC,kBAAM,IAAI,CAAA;AAAA,EACjC;AACA,EAAA,OAAOD,mBAAA,CAAc,QAAQ,KAAK,CAAA;AACpC","file":"index.cjs","sourcesContent":["// @poolse/react-native-calls — the React Native face of the native\n// call core (CONTRACT.md §8). A thin, typed surface over the native\n// module: commands in, one snapshot event out. All call logic lives in\n// the native cores; nothing here decides anything about a call.\n//\n// On a platform or build without the native module (Expo Go, web,\n// unlinked), every command is a safe no-op and the state stays idle —\n// so a host can render against this unconditionally.\nimport { createElement, type ComponentType, type ReactElement } from 'react';\nimport { View, type ViewProps } from 'react-native';\nimport { requireNativeViewManager, requireOptionalNativeModule } from 'expo-modules-core';\n\n/**\n * A call's complete state. `null` means idle — no call. After a call\n * ends the snapshot stays `phase: 'ended'` (with `reason`) for ~2.5 s,\n * then becomes `null`.\n */\nexport interface Snapshot {\n  cv: 1;\n  callId: string;\n  conversationId: string;\n  conversationName: string | null;\n  direction: 'incoming' | 'outgoing' | 'joined';\n  media: 'audio' | 'video';\n  phase: 'ringing_in' | 'ringing_out' | 'connecting' | 'active' | 'reconnecting' | 'ended';\n  reason?:\n    | 'left'\n    | 'finished'\n    | 'declined_all'\n    | 'busy_all'\n    | 'no_answer'\n    | 'cancelled'\n    | 'connection_lost'\n    | 'failed';\n  /** REMOTE participants only; `userId` is the LiveKit identity. */\n  participants: Array<{\n    userId: string;\n    externalId: string;\n    speaking: boolean;\n    muted: boolean;\n    /** True only with a published, subscribed, unmuted camera track (show video, not avatar). */\n    cameraOn: boolean;\n  }>;\n  audioRoute: 'earpiece' | 'speaker' | 'bluetooth' | 'headset';\n  mutedSelf: boolean;\n  /** True only while the local camera track is actually published and enabled. */\n  cameraOn: boolean;\n  /** Facing of the published local camera; absent when the camera is off. */\n  cameraFacing?: 'front' | 'back';\n}\n\nexport interface ConfigureOptions {\n  /** Drawable resource NAME for the call notification's small icon. */\n  smallIcon?: string;\n  /** Raw resource NAME of the ringback tone (Android). */\n  ringback?: string;\n}\n\nexport interface PlaceOptions {\n  media: 'audio' | 'video';\n  /** The user's session token — authorizes placing/joining (CONTRACT.md §3.2). */\n  sessionToken: string;\n}\n\ntype NativeSnapshot = { snapshot: Snapshot | null };\n\ninterface PoolseCallsNative {\n  configure(apiBaseUrl: string, options: ConfigureOptions | null): Promise<void>;\n  getCallState(): NativeSnapshot;\n  place(conversationId: string, media: string, sessionToken: string): Promise<void>;\n  join(callId: string, conversationId: string | null, sessionToken: string): Promise<void>;\n  answer(): void;\n  decline(): void;\n  hangUp(): void;\n  setMuted(muted: boolean): void;\n  setCamera(on: boolean): void;\n  switchCamera(): void;\n  setSpeaker(on: boolean): void;\n  onRingEnded(callId: string, reason: string): void;\n  onCallFinished(callId: string, reason: string | null): void;\n  canUseFullScreenIntent(): boolean;\n  openFullScreenIntentSettings(): void;\n  addListener(event: 'onCallState', cb: (payload: NativeSnapshot) => void): { remove(): void };\n}\n\nconst native = requireOptionalNativeModule<PoolseCallsNative>('PoolseCalls');\n\n/** True when the native call core is present in this build. */\nexport const nativeCallsAvailable = native != null;\n\n/** Configure once, before any call can arrive. No secrets — just the API origin. */\nexport async function configure(apiBaseUrl: string, options?: ConfigureOptions): Promise<void> {\n  await native?.configure(apiBaseUrl, options ?? null);\n}\n\n/** The current snapshot — safe to read at any moment, including cold answer and before configure. */\nexport function getCallState(): Snapshot | null {\n  return native?.getCallState().snapshot ?? null;\n}\n\nexport type Unsubscribe = () => void;\n\n/** Subscribe to call state. Fires a full snapshot on every change. */\nexport function onCallState(cb: (snapshot: Snapshot | null) => void): Unsubscribe {\n  if (!native) return () => undefined;\n  const sub = native.addListener('onCallState', (payload) => cb(payload.snapshot));\n  return () => sub.remove();\n}\n\nexport function place(conversationId: string, options: PlaceOptions): Promise<void> {\n  return native?.place(conversationId, options.media, options.sessionToken) ?? Promise.resolve();\n}\n\nexport function join(\n  callId: string,\n  conversationId: string | null,\n  sessionToken: string,\n): Promise<void> {\n  return native?.join(callId, conversationId, sessionToken) ?? Promise.resolve();\n}\n\nexport const answer = (): void => native?.answer();\nexport const decline = (): void => native?.decline();\nexport const hangUp = (): void => native?.hangUp();\nexport const setMuted = (muted: boolean): void => native?.setMuted(muted);\nexport const setCamera = (on: boolean): void => native?.setCamera(on);\nexport const switchCamera = (): void => native?.switchCamera();\n/** Route call audio to the loudspeaker (`true`) or back to earpiece / headset (`false`). */\nexport const setSpeaker = (on: boolean): void => native?.setSpeaker(on);\n\n/**\n * Socket forwarding for an open app: a `call:ring_ended` seen on the\n * socket. Idempotent with the push path — the core dedupes.\n */\nexport const onRingEnded = (callId: string, reason: string): void =>\n  native?.onRingEnded(callId, reason);\n\n/**\n * Socket forwarding: `call:finished`. Pass the payload's `reason`\n * (`finished` | `declined_all` | `no_answer` | `cancelled`) so an\n * unanswered caller sees \"Declined\"/\"No answer\", not \"Call ended\".\n * Idempotent with the `finished` push.\n */\nexport const onCallFinished = (callId: string, reason?: string): void =>\n  native?.onCallFinished(callId, reason ?? null);\n\n/**\n * Android 14+: whether the app may show the full-screen ring over the\n * lock screen. `true` on older Android and where the module is absent.\n */\nexport const canUseFullScreenIntent = (): boolean => native?.canUseFullScreenIntent() ?? true;\n\n/** Open the system screen where the user grants full-screen intents (falls back to notification settings). */\nexport const openFullScreenIntentSettings = (): void => native?.openFullScreenIntentSettings();\n\n// ── video ─────────────────────────────────────────────────────────────\n\nexport interface CallVideoViewProps extends ViewProps {\n  /** Remote participant's userId (LiveKit identity). Omit with local=true for self view. */\n  participantId?: string;\n  local?: boolean;\n  /** default: true for local front camera, false otherwise */\n  mirror?: boolean;\n  /** default 'cover' */\n  fit?: 'cover' | 'contain';\n}\n\ntype NativeVideoProps = CallVideoViewProps;\n\nlet nativeVideo: ComponentType<NativeVideoProps> | null | undefined;\n\n/** Resolved lazily (first render) and only when the native module exists. */\nfunction nativeVideoView(): ComponentType<NativeVideoProps> | null {\n  if (nativeVideo !== undefined) return nativeVideo;\n  nativeVideo = null;\n  if (native) {\n    try {\n      nativeVideo = requireNativeViewManager<NativeVideoProps>('PoolseCalls', 'PoolseCallVideo');\n    } catch {\n      nativeVideo = null; // an older native build without the view\n    }\n  }\n  return nativeVideo;\n}\n\n/**\n * A participant's camera (or, with `local`, your own), rendered natively\n * by the call core. Shows nothing (stays transparent) while that camera\n * is off — draw the avatar from the snapshot's `cameraOn` underneath.\n * Without the native module it renders an empty View.\n */\nexport function CallVideoView(props: CallVideoViewProps): ReactElement | null {\n  const Native = nativeVideoView();\n  if (!Native) {\n    const { participantId: _p, local: _l, mirror: _m, fit: _f, ...rest } = props;\n    return createElement(View, rest);\n  }\n  return createElement(Native, props);\n}\n"]}

package/dist/index.d.cts

@@ -1,4 +1,11 @@
-/** A call's complete state. `null` means idle — no call. */
+import { ReactElement } from 'react';
+import { ViewProps } from 'react-native';
+
+/**
+ * A call's complete state. `null` means idle — no call. After a call
+ * ends the snapshot stays `phase: 'ended'` (with `reason`) for ~2.5 s,
+ * then becomes `null`.
+ */
 interface Snapshot {
     cv: 1;
     callId: string;
@@ -8,16 +15,21 @@ interface Snapshot {
     media: 'audio' | 'video';
     phase: 'ringing_in' | 'ringing_out' | 'connecting' | 'active' | 'reconnecting' | 'ended';
     reason?: 'left' | 'finished' | 'declined_all' | 'busy_all' | 'no_answer' | 'cancelled' | 'connection_lost' | 'failed';
+    /** REMOTE participants only; `userId` is the LiveKit identity. */
     participants: Array<{
         userId: string;
         externalId: string;
         speaking: boolean;
         muted: boolean;
+        /** True only with a published, subscribed, unmuted camera track (show video, not avatar). */
         cameraOn: boolean;
     }>;
     audioRoute: 'earpiece' | 'speaker' | 'bluetooth' | 'headset';
     mutedSelf: boolean;
+    /** True only while the local camera track is actually published and enabled. */
     cameraOn: boolean;
+    /** Facing of the published local camera; absent when the camera is off. */
+    cameraFacing?: 'front' | 'back';
 }
 interface ConfigureOptions {
     /** Drawable resource NAME for the call notification's small icon. */
@@ -34,7 +46,7 @@ interface PlaceOptions {
 declare const nativeCallsAvailable: boolean;
 /** Configure once, before any call can arrive. No secrets — just the API origin. */
 declare function configure(apiBaseUrl: string, options?: ConfigureOptions): Promise<void>;
-/** The current snapshot — safe to read at any moment, including cold answer. */
+/** The current snapshot — safe to read at any moment, including cold answer and before configure. */
 declare function getCallState(): Snapshot | null;
 type Unsubscribe = () => void;
 /** Subscribe to call state. Fires a full snapshot on every change. */
@@ -47,5 +59,42 @@ declare const hangUp: () => void;
 declare const setMuted: (muted: boolean) => void;
 declare const setCamera: (on: boolean) => void;
 declare const switchCamera: () => void;
+/** Route call audio to the loudspeaker (`true`) or back to earpiece / headset (`false`). */
+declare const setSpeaker: (on: boolean) => void;
+/**
+ * Socket forwarding for an open app: a `call:ring_ended` seen on the
+ * socket. Idempotent with the push path — the core dedupes.
+ */
+declare const onRingEnded: (callId: string, reason: string) => void;
+/**
+ * Socket forwarding: `call:finished`. Pass the payload's `reason`
+ * (`finished` | `declined_all` | `no_answer` | `cancelled`) so an
+ * unanswered caller sees "Declined"/"No answer", not "Call ended".
+ * Idempotent with the `finished` push.
+ */
+declare const onCallFinished: (callId: string, reason?: string) => void;
+/**
+ * Android 14+: whether the app may show the full-screen ring over the
+ * lock screen. `true` on older Android and where the module is absent.
+ */
+declare const canUseFullScreenIntent: () => boolean;
+/** Open the system screen where the user grants full-screen intents (falls back to notification settings). */
+declare const openFullScreenIntentSettings: () => void;
+interface CallVideoViewProps extends ViewProps {
+    /** Remote participant's userId (LiveKit identity). Omit with local=true for self view. */
+    participantId?: string;
+    local?: boolean;
+    /** default: true for local front camera, false otherwise */
+    mirror?: boolean;
+    /** default 'cover' */
+    fit?: 'cover' | 'contain';
+}
+/**
+ * A participant's camera (or, with `local`, your own), rendered natively
+ * by the call core. Shows nothing (stays transparent) while that camera
+ * is off — draw the avatar from the snapshot's `cameraOn` underneath.
+ * Without the native module it renders an empty View.
+ */
+declare function CallVideoView(props: CallVideoViewProps): ReactElement | null;
 
-export { type ConfigureOptions, type PlaceOptions, type Snapshot, type Unsubscribe, answer, configure, decline, getCallState, hangUp, join, nativeCallsAvailable, onCallState, place, setCamera, setMuted, switchCamera };
+export { CallVideoView, type CallVideoViewProps, type ConfigureOptions, type PlaceOptions, type Snapshot, type Unsubscribe, answer, canUseFullScreenIntent, configure, decline, getCallState, hangUp, join, nativeCallsAvailable, onCallFinished, onCallState, onRingEnded, openFullScreenIntentSettings, place, setCamera, setMuted, setSpeaker, switchCamera };

package/dist/index.d.ts

@@ -1,4 +1,11 @@
-/** A call's complete state. `null` means idle — no call. */
+import { ReactElement } from 'react';
+import { ViewProps } from 'react-native';
+
+/**
+ * A call's complete state. `null` means idle — no call. After a call
+ * ends the snapshot stays `phase: 'ended'` (with `reason`) for ~2.5 s,
+ * then becomes `null`.
+ */
 interface Snapshot {
     cv: 1;
     callId: string;
@@ -8,16 +15,21 @@ interface Snapshot {
     media: 'audio' | 'video';
     phase: 'ringing_in' | 'ringing_out' | 'connecting' | 'active' | 'reconnecting' | 'ended';
     reason?: 'left' | 'finished' | 'declined_all' | 'busy_all' | 'no_answer' | 'cancelled' | 'connection_lost' | 'failed';
+    /** REMOTE participants only; `userId` is the LiveKit identity. */
     participants: Array<{
         userId: string;
         externalId: string;
         speaking: boolean;
         muted: boolean;
+        /** True only with a published, subscribed, unmuted camera track (show video, not avatar). */
         cameraOn: boolean;
     }>;
     audioRoute: 'earpiece' | 'speaker' | 'bluetooth' | 'headset';
     mutedSelf: boolean;
+    /** True only while the local camera track is actually published and enabled. */
     cameraOn: boolean;
+    /** Facing of the published local camera; absent when the camera is off. */
+    cameraFacing?: 'front' | 'back';
 }
 interface ConfigureOptions {
     /** Drawable resource NAME for the call notification's small icon. */
@@ -34,7 +46,7 @@ interface PlaceOptions {
 declare const nativeCallsAvailable: boolean;
 /** Configure once, before any call can arrive. No secrets — just the API origin. */
 declare function configure(apiBaseUrl: string, options?: ConfigureOptions): Promise<void>;
-/** The current snapshot — safe to read at any moment, including cold answer. */
+/** The current snapshot — safe to read at any moment, including cold answer and before configure. */
 declare function getCallState(): Snapshot | null;
 type Unsubscribe = () => void;
 /** Subscribe to call state. Fires a full snapshot on every change. */
@@ -47,5 +59,42 @@ declare const hangUp: () => void;
 declare const setMuted: (muted: boolean) => void;
 declare const setCamera: (on: boolean) => void;
 declare const switchCamera: () => void;
+/** Route call audio to the loudspeaker (`true`) or back to earpiece / headset (`false`). */
+declare const setSpeaker: (on: boolean) => void;
+/**
+ * Socket forwarding for an open app: a `call:ring_ended` seen on the
+ * socket. Idempotent with the push path — the core dedupes.
+ */
+declare const onRingEnded: (callId: string, reason: string) => void;
+/**
+ * Socket forwarding: `call:finished`. Pass the payload's `reason`
+ * (`finished` | `declined_all` | `no_answer` | `cancelled`) so an
+ * unanswered caller sees "Declined"/"No answer", not "Call ended".
+ * Idempotent with the `finished` push.
+ */
+declare const onCallFinished: (callId: string, reason?: string) => void;
+/**
+ * Android 14+: whether the app may show the full-screen ring over the
+ * lock screen. `true` on older Android and where the module is absent.
+ */
+declare const canUseFullScreenIntent: () => boolean;
+/** Open the system screen where the user grants full-screen intents (falls back to notification settings). */
+declare const openFullScreenIntentSettings: () => void;
+interface CallVideoViewProps extends ViewProps {
+    /** Remote participant's userId (LiveKit identity). Omit with local=true for self view. */
+    participantId?: string;
+    local?: boolean;
+    /** default: true for local front camera, false otherwise */
+    mirror?: boolean;
+    /** default 'cover' */
+    fit?: 'cover' | 'contain';
+}
+/**
+ * A participant's camera (or, with `local`, your own), rendered natively
+ * by the call core. Shows nothing (stays transparent) while that camera
+ * is off — draw the avatar from the snapshot's `cameraOn` underneath.
+ * Without the native module it renders an empty View.
+ */
+declare function CallVideoView(props: CallVideoViewProps): ReactElement | null;
 
-export { type ConfigureOptions, type PlaceOptions, type Snapshot, type Unsubscribe, answer, configure, decline, getCallState, hangUp, join, nativeCallsAvailable, onCallState, place, setCamera, setMuted, switchCamera };
+export { CallVideoView, type CallVideoViewProps, type ConfigureOptions, type PlaceOptions, type Snapshot, type Unsubscribe, answer, canUseFullScreenIntent, configure, decline, getCallState, hangUp, join, nativeCallsAvailable, onCallFinished, onCallState, onRingEnded, openFullScreenIntentSettings, place, setCamera, setMuted, setSpeaker, switchCamera };

package/dist/index.js

@@ -1,4 +1,6 @@
-import { requireOptionalNativeModule } from 'expo-modules-core';
+import { createElement } from 'react';
+import { View } from 'react-native';
+import { requireOptionalNativeModule, requireNativeViewManager } from 'expo-modules-core';
 
 // src/index.ts
 var native = requireOptionalNativeModule("PoolseCalls");
@@ -26,7 +28,33 @@ var hangUp = () => native?.hangUp();
 var setMuted = (muted) => native?.setMuted(muted);
 var setCamera = (on) => native?.setCamera(on);
 var switchCamera = () => native?.switchCamera();
+var setSpeaker = (on) => native?.setSpeaker(on);
+var onRingEnded = (callId, reason) => native?.onRingEnded(callId, reason);
+var onCallFinished = (callId, reason) => native?.onCallFinished(callId, reason ?? null);
+var canUseFullScreenIntent = () => native?.canUseFullScreenIntent() ?? true;
+var openFullScreenIntentSettings = () => native?.openFullScreenIntentSettings();
+var nativeVideo;
+function nativeVideoView() {
+  if (nativeVideo !== void 0) return nativeVideo;
+  nativeVideo = null;
+  if (native) {
+    try {
+      nativeVideo = requireNativeViewManager("PoolseCalls", "PoolseCallVideo");
+    } catch {
+      nativeVideo = null;
+    }
+  }
+  return nativeVideo;
+}
+function CallVideoView(props) {
+  const Native = nativeVideoView();
+  if (!Native) {
+    const { participantId: _p, local: _l, mirror: _m, fit: _f, ...rest } = props;
+    return createElement(View, rest);
+  }
+  return createElement(Native, props);
+}
 
-export { answer, configure, decline, getCallState, hangUp, join, nativeCallsAvailable, onCallState, place, setCamera, setMuted, switchCamera };
+export { CallVideoView, answer, canUseFullScreenIntent, configure, decline, getCallState, hangUp, join, nativeCallsAvailable, onCallFinished, onCallState, onRingEnded, openFullScreenIntentSettings, place, setCamera, setMuted, setSpeaker, switchCamera };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;AAqEA,IAAM,MAAA,GAAS,4BAA+C,aAAa,CAAA;AAGpE,IAAM,uBAAuB,MAAA,IAAU;AAG9C,eAAsB,SAAA,CAAU,YAAoB,OAAA,EAA2C;AAC7F,EAAA,MAAM,MAAA,EAAQ,SAAA,CAAU,UAAA,EAAY,OAAA,IAAW,IAAI,CAAA;AACrD;AAGO,SAAS,YAAA,GAAgC;AAC9C,EAAA,OAAO,MAAA,EAAQ,YAAA,EAAa,CAAE,QAAA,IAAY,IAAA;AAC5C;AAKO,SAAS,YAAY,EAAA,EAAsD;AAChF,EAAA,IAAI,CAAC,MAAA,EAAQ,OAAO,MAAM,MAAA;AAC1B,EAAA,MAAM,GAAA,GAAM,OAAO,WAAA,CAAY,aAAA,EAAe,CAAC,OAAA,KAAY,EAAA,CAAG,OAAA,CAAQ,QAAQ,CAAC,CAAA;AAC/E,EAAA,OAAO,MAAM,IAAI,MAAA,EAAO;AAC1B;AAEO,SAAS,KAAA,CAAM,gBAAwB,OAAA,EAAsC;AAClF,EAAA,OAAO,MAAA,EAAQ,MAAM,cAAA,EAAgB,OAAA,CAAQ,OAAO,OAAA,CAAQ,YAAY,CAAA,IAAK,OAAA,CAAQ,OAAA,EAAQ;AAC/F;AAEO,SAAS,IAAA,CACd,MAAA,EACA,cAAA,EACA,YAAA,EACe;AACf,EAAA,OAAO,QAAQ,IAAA,CAAK,MAAA,EAAQ,gBAAgB,YAAY,CAAA,IAAK,QAAQ,OAAA,EAAQ;AAC/E;AAEO,IAAM,MAAA,GAAS,MAAY,MAAA,EAAQ,MAAA;AACnC,IAAM,OAAA,GAAU,MAAY,MAAA,EAAQ,OAAA;AACpC,IAAM,MAAA,GAAS,MAAY,MAAA,EAAQ,MAAA;AACnC,IAAM,QAAA,GAAW,CAAC,KAAA,KAAyB,MAAA,EAAQ,SAAS,KAAK;AACjE,IAAM,SAAA,GAAY,CAAC,EAAA,KAAsB,MAAA,EAAQ,UAAU,EAAE;AAC7D,IAAM,YAAA,GAAe,MAAY,MAAA,EAAQ,YAAA","file":"index.js","sourcesContent":["// @poolse/react-native-calls — the React Native face of the native\n// call core (CONTRACT.md §8). A thin, typed surface over the native\n// module: commands in, one snapshot event out. All call logic lives in\n// the native cores; nothing here decides anything about a call.\n//\n// On a platform or build without the native module (Expo Go, web,\n// unlinked), every command is a safe no-op and the state stays idle —\n// so a host can render against this unconditionally.\nimport { requireOptionalNativeModule } from 'expo-modules-core';\n\n/** A call's complete state. `null` means idle — no call. */\nexport interface Snapshot {\n  cv: 1;\n  callId: string;\n  conversationId: string;\n  conversationName: string | null;\n  direction: 'incoming' | 'outgoing' | 'joined';\n  media: 'audio' | 'video';\n  phase: 'ringing_in' | 'ringing_out' | 'connecting' | 'active' | 'reconnecting' | 'ended';\n  reason?:\n    | 'left'\n    | 'finished'\n    | 'declined_all'\n    | 'busy_all'\n    | 'no_answer'\n    | 'cancelled'\n    | 'connection_lost'\n    | 'failed';\n  participants: Array<{\n    userId: string;\n    externalId: string;\n    speaking: boolean;\n    muted: boolean;\n    cameraOn: boolean;\n  }>;\n  audioRoute: 'earpiece' | 'speaker' | 'bluetooth' | 'headset';\n  mutedSelf: boolean;\n  cameraOn: boolean;\n}\n\nexport interface ConfigureOptions {\n  /** Drawable resource NAME for the call notification's small icon. */\n  smallIcon?: string;\n  /** Raw resource NAME of the ringback tone (Android). */\n  ringback?: string;\n}\n\nexport interface PlaceOptions {\n  media: 'audio' | 'video';\n  /** The user's session token — authorizes placing/joining (CONTRACT.md §3.2). */\n  sessionToken: string;\n}\n\ntype NativeSnapshot = { snapshot: Snapshot | null };\n\ninterface PoolseCallsNative {\n  configure(apiBaseUrl: string, options: ConfigureOptions | null): Promise<void>;\n  getCallState(): NativeSnapshot;\n  place(conversationId: string, media: string, sessionToken: string): Promise<void>;\n  join(callId: string, conversationId: string | null, sessionToken: string): Promise<void>;\n  answer(): void;\n  decline(): void;\n  hangUp(): void;\n  setMuted(muted: boolean): void;\n  setCamera(on: boolean): void;\n  switchCamera(): void;\n  addListener(event: 'onCallState', cb: (payload: NativeSnapshot) => void): { remove(): void };\n}\n\nconst native = requireOptionalNativeModule<PoolseCallsNative>('PoolseCalls');\n\n/** True when the native call core is present in this build. */\nexport const nativeCallsAvailable = native != null;\n\n/** Configure once, before any call can arrive. No secrets — just the API origin. */\nexport async function configure(apiBaseUrl: string, options?: ConfigureOptions): Promise<void> {\n  await native?.configure(apiBaseUrl, options ?? null);\n}\n\n/** The current snapshot — safe to read at any moment, including cold answer. */\nexport function getCallState(): Snapshot | null {\n  return native?.getCallState().snapshot ?? null;\n}\n\nexport type Unsubscribe = () => void;\n\n/** Subscribe to call state. Fires a full snapshot on every change. */\nexport function onCallState(cb: (snapshot: Snapshot | null) => void): Unsubscribe {\n  if (!native) return () => undefined;\n  const sub = native.addListener('onCallState', (payload) => cb(payload.snapshot));\n  return () => sub.remove();\n}\n\nexport function place(conversationId: string, options: PlaceOptions): Promise<void> {\n  return native?.place(conversationId, options.media, options.sessionToken) ?? Promise.resolve();\n}\n\nexport function join(\n  callId: string,\n  conversationId: string | null,\n  sessionToken: string,\n): Promise<void> {\n  return native?.join(callId, conversationId, sessionToken) ?? Promise.resolve();\n}\n\nexport const answer = (): void => native?.answer();\nexport const decline = (): void => native?.decline();\nexport const hangUp = (): void => native?.hangUp();\nexport const setMuted = (muted: boolean): void => native?.setMuted(muted);\nexport const setCamera = (on: boolean): void => native?.setCamera(on);\nexport const switchCamera = (): void => native?.switchCamera();\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;AAqFA,IAAM,MAAA,GAAS,4BAA+C,aAAa,CAAA;AAGpE,IAAM,uBAAuB,MAAA,IAAU;AAG9C,eAAsB,SAAA,CAAU,YAAoB,OAAA,EAA2C;AAC7F,EAAA,MAAM,MAAA,EAAQ,SAAA,CAAU,UAAA,EAAY,OAAA,IAAW,IAAI,CAAA;AACrD;AAGO,SAAS,YAAA,GAAgC;AAC9C,EAAA,OAAO,MAAA,EAAQ,YAAA,EAAa,CAAE,QAAA,IAAY,IAAA;AAC5C;AAKO,SAAS,YAAY,EAAA,EAAsD;AAChF,EAAA,IAAI,CAAC,MAAA,EAAQ,OAAO,MAAM,MAAA;AAC1B,EAAA,MAAM,GAAA,GAAM,OAAO,WAAA,CAAY,aAAA,EAAe,CAAC,OAAA,KAAY,EAAA,CAAG,OAAA,CAAQ,QAAQ,CAAC,CAAA;AAC/E,EAAA,OAAO,MAAM,IAAI,MAAA,EAAO;AAC1B;AAEO,SAAS,KAAA,CAAM,gBAAwB,OAAA,EAAsC;AAClF,EAAA,OAAO,MAAA,EAAQ,MAAM,cAAA,EAAgB,OAAA,CAAQ,OAAO,OAAA,CAAQ,YAAY,CAAA,IAAK,OAAA,CAAQ,OAAA,EAAQ;AAC/F;AAEO,SAAS,IAAA,CACd,MAAA,EACA,cAAA,EACA,YAAA,EACe;AACf,EAAA,OAAO,QAAQ,IAAA,CAAK,MAAA,EAAQ,gBAAgB,YAAY,CAAA,IAAK,QAAQ,OAAA,EAAQ;AAC/E;AAEO,IAAM,MAAA,GAAS,MAAY,MAAA,EAAQ,MAAA;AACnC,IAAM,OAAA,GAAU,MAAY,MAAA,EAAQ,OAAA;AACpC,IAAM,MAAA,GAAS,MAAY,MAAA,EAAQ,MAAA;AACnC,IAAM,QAAA,GAAW,CAAC,KAAA,KAAyB,MAAA,EAAQ,SAAS,KAAK;AACjE,IAAM,SAAA,GAAY,CAAC,EAAA,KAAsB,MAAA,EAAQ,UAAU,EAAE;AAC7D,IAAM,YAAA,GAAe,MAAY,MAAA,EAAQ,YAAA;AAEzC,IAAM,UAAA,GAAa,CAAC,EAAA,KAAsB,MAAA,EAAQ,WAAW,EAAE;AAM/D,IAAM,cAAc,CAAC,MAAA,EAAgB,WAC1C,MAAA,EAAQ,WAAA,CAAY,QAAQ,MAAM;AAQ7B,IAAM,cAAA,GAAiB,CAAC,MAAA,EAAgB,MAAA,KAC7C,QAAQ,cAAA,CAAe,MAAA,EAAQ,UAAU,IAAI;AAMxC,IAAM,sBAAA,GAAyB,MAAe,MAAA,EAAQ,sBAAA,EAAuB,IAAK;AAGlF,IAAM,4BAAA,GAA+B,MAAY,MAAA,EAAQ,4BAAA;AAgBhE,IAAI,WAAA;AAGJ,SAAS,eAAA,GAA0D;AACjE,EAAA,IAAI,WAAA,KAAgB,QAAW,OAAO,WAAA;AACtC,EAAA,WAAA,GAAc,IAAA;AACd,EAAA,IAAI,MAAA,EAAQ;AACV,IAAA,IAAI;AACF,MAAA,WAAA,GAAc,wBAAA,CAA2C,eAAe,iBAAiB,CAAA;AAAA,IAC3F,CAAA,CAAA,MAAQ;AACN,MAAA,WAAA,GAAc,IAAA;AAAA,IAChB;AAAA,EACF;AACA,EAAA,OAAO,WAAA;AACT;AAQO,SAAS,cAAc,KAAA,EAAgD;AAC5E,EAAA,MAAM,SAAS,eAAA,EAAgB;AAC/B,EAAA,IAAI,CAAC,MAAA,EAAQ;AACX,IAAA,MAAM,EAAE,aAAA,EAAe,EAAA,EAAI,KAAA,EAAO,EAAA,EAAI,MAAA,EAAQ,EAAA,EAAI,GAAA,EAAK,EAAA,EAAI,GAAG,IAAA,EAAK,GAAI,KAAA;AACvE,IAAA,OAAO,aAAA,CAAc,MAAM,IAAI,CAAA;AAAA,EACjC;AACA,EAAA,OAAO,aAAA,CAAc,QAAQ,KAAK,CAAA;AACpC","file":"index.js","sourcesContent":["// @poolse/react-native-calls — the React Native face of the native\n// call core (CONTRACT.md §8). A thin, typed surface over the native\n// module: commands in, one snapshot event out. All call logic lives in\n// the native cores; nothing here decides anything about a call.\n//\n// On a platform or build without the native module (Expo Go, web,\n// unlinked), every command is a safe no-op and the state stays idle —\n// so a host can render against this unconditionally.\nimport { createElement, type ComponentType, type ReactElement } from 'react';\nimport { View, type ViewProps } from 'react-native';\nimport { requireNativeViewManager, requireOptionalNativeModule } from 'expo-modules-core';\n\n/**\n * A call's complete state. `null` means idle — no call. After a call\n * ends the snapshot stays `phase: 'ended'` (with `reason`) for ~2.5 s,\n * then becomes `null`.\n */\nexport interface Snapshot {\n  cv: 1;\n  callId: string;\n  conversationId: string;\n  conversationName: string | null;\n  direction: 'incoming' | 'outgoing' | 'joined';\n  media: 'audio' | 'video';\n  phase: 'ringing_in' | 'ringing_out' | 'connecting' | 'active' | 'reconnecting' | 'ended';\n  reason?:\n    | 'left'\n    | 'finished'\n    | 'declined_all'\n    | 'busy_all'\n    | 'no_answer'\n    | 'cancelled'\n    | 'connection_lost'\n    | 'failed';\n  /** REMOTE participants only; `userId` is the LiveKit identity. */\n  participants: Array<{\n    userId: string;\n    externalId: string;\n    speaking: boolean;\n    muted: boolean;\n    /** True only with a published, subscribed, unmuted camera track (show video, not avatar). */\n    cameraOn: boolean;\n  }>;\n  audioRoute: 'earpiece' | 'speaker' | 'bluetooth' | 'headset';\n  mutedSelf: boolean;\n  /** True only while the local camera track is actually published and enabled. */\n  cameraOn: boolean;\n  /** Facing of the published local camera; absent when the camera is off. */\n  cameraFacing?: 'front' | 'back';\n}\n\nexport interface ConfigureOptions {\n  /** Drawable resource NAME for the call notification's small icon. */\n  smallIcon?: string;\n  /** Raw resource NAME of the ringback tone (Android). */\n  ringback?: string;\n}\n\nexport interface PlaceOptions {\n  media: 'audio' | 'video';\n  /** The user's session token — authorizes placing/joining (CONTRACT.md §3.2). */\n  sessionToken: string;\n}\n\ntype NativeSnapshot = { snapshot: Snapshot | null };\n\ninterface PoolseCallsNative {\n  configure(apiBaseUrl: string, options: ConfigureOptions | null): Promise<void>;\n  getCallState(): NativeSnapshot;\n  place(conversationId: string, media: string, sessionToken: string): Promise<void>;\n  join(callId: string, conversationId: string | null, sessionToken: string): Promise<void>;\n  answer(): void;\n  decline(): void;\n  hangUp(): void;\n  setMuted(muted: boolean): void;\n  setCamera(on: boolean): void;\n  switchCamera(): void;\n  setSpeaker(on: boolean): void;\n  onRingEnded(callId: string, reason: string): void;\n  onCallFinished(callId: string, reason: string | null): void;\n  canUseFullScreenIntent(): boolean;\n  openFullScreenIntentSettings(): void;\n  addListener(event: 'onCallState', cb: (payload: NativeSnapshot) => void): { remove(): void };\n}\n\nconst native = requireOptionalNativeModule<PoolseCallsNative>('PoolseCalls');\n\n/** True when the native call core is present in this build. */\nexport const nativeCallsAvailable = native != null;\n\n/** Configure once, before any call can arrive. No secrets — just the API origin. */\nexport async function configure(apiBaseUrl: string, options?: ConfigureOptions): Promise<void> {\n  await native?.configure(apiBaseUrl, options ?? null);\n}\n\n/** The current snapshot — safe to read at any moment, including cold answer and before configure. */\nexport function getCallState(): Snapshot | null {\n  return native?.getCallState().snapshot ?? null;\n}\n\nexport type Unsubscribe = () => void;\n\n/** Subscribe to call state. Fires a full snapshot on every change. */\nexport function onCallState(cb: (snapshot: Snapshot | null) => void): Unsubscribe {\n  if (!native) return () => undefined;\n  const sub = native.addListener('onCallState', (payload) => cb(payload.snapshot));\n  return () => sub.remove();\n}\n\nexport function place(conversationId: string, options: PlaceOptions): Promise<void> {\n  return native?.place(conversationId, options.media, options.sessionToken) ?? Promise.resolve();\n}\n\nexport function join(\n  callId: string,\n  conversationId: string | null,\n  sessionToken: string,\n): Promise<void> {\n  return native?.join(callId, conversationId, sessionToken) ?? Promise.resolve();\n}\n\nexport const answer = (): void => native?.answer();\nexport const decline = (): void => native?.decline();\nexport const hangUp = (): void => native?.hangUp();\nexport const setMuted = (muted: boolean): void => native?.setMuted(muted);\nexport const setCamera = (on: boolean): void => native?.setCamera(on);\nexport const switchCamera = (): void => native?.switchCamera();\n/** Route call audio to the loudspeaker (`true`) or back to earpiece / headset (`false`). */\nexport const setSpeaker = (on: boolean): void => native?.setSpeaker(on);\n\n/**\n * Socket forwarding for an open app: a `call:ring_ended` seen on the\n * socket. Idempotent with the push path — the core dedupes.\n */\nexport const onRingEnded = (callId: string, reason: string): void =>\n  native?.onRingEnded(callId, reason);\n\n/**\n * Socket forwarding: `call:finished`. Pass the payload's `reason`\n * (`finished` | `declined_all` | `no_answer` | `cancelled`) so an\n * unanswered caller sees \"Declined\"/\"No answer\", not \"Call ended\".\n * Idempotent with the `finished` push.\n */\nexport const onCallFinished = (callId: string, reason?: string): void =>\n  native?.onCallFinished(callId, reason ?? null);\n\n/**\n * Android 14+: whether the app may show the full-screen ring over the\n * lock screen. `true` on older Android and where the module is absent.\n */\nexport const canUseFullScreenIntent = (): boolean => native?.canUseFullScreenIntent() ?? true;\n\n/** Open the system screen where the user grants full-screen intents (falls back to notification settings). */\nexport const openFullScreenIntentSettings = (): void => native?.openFullScreenIntentSettings();\n\n// ── video ─────────────────────────────────────────────────────────────\n\nexport interface CallVideoViewProps extends ViewProps {\n  /** Remote participant's userId (LiveKit identity). Omit with local=true for self view. */\n  participantId?: string;\n  local?: boolean;\n  /** default: true for local front camera, false otherwise */\n  mirror?: boolean;\n  /** default 'cover' */\n  fit?: 'cover' | 'contain';\n}\n\ntype NativeVideoProps = CallVideoViewProps;\n\nlet nativeVideo: ComponentType<NativeVideoProps> | null | undefined;\n\n/** Resolved lazily (first render) and only when the native module exists. */\nfunction nativeVideoView(): ComponentType<NativeVideoProps> | null {\n  if (nativeVideo !== undefined) return nativeVideo;\n  nativeVideo = null;\n  if (native) {\n    try {\n      nativeVideo = requireNativeViewManager<NativeVideoProps>('PoolseCalls', 'PoolseCallVideo');\n    } catch {\n      nativeVideo = null; // an older native build without the view\n    }\n  }\n  return nativeVideo;\n}\n\n/**\n * A participant's camera (or, with `local`, your own), rendered natively\n * by the call core. Shows nothing (stays transparent) while that camera\n * is off — draw the avatar from the snapshot's `cameraOn` underneath.\n * Without the native module it renders an empty View.\n */\nexport function CallVideoView(props: CallVideoViewProps): ReactElement | null {\n  const Native = nativeVideoView();\n  if (!Native) {\n    const { participantId: _p, local: _l, mirror: _m, fit: _f, ...rest } = props;\n    return createElement(View, rest);\n  }\n  return createElement(Native, props);\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poolse/react-native-calls",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "description": "Native call core for poolse — Kotlin/Swift calling engine with a thin React Native bridge. Ring, answer and carry audio with the app killed and the phone locked.",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,7 @@
     "src",
     "dist",
     "android/build.gradle",
+    "android/consumer-rules.pro",
     "android/src",
     "expo-module.config.json",
     "README.md"

package/src/expo-modules-core.d.ts

@@ -8,4 +8,9 @@
 // cannot collide with the app's own copy of the types.
 declare module 'expo-modules-core' {
   export function requireOptionalNativeModule<T>(name: string): T | null;
+  /** A native view registered by an Expo module (`View(...)` + `Name(...)`). */
+  export function requireNativeViewManager<P>(
+    moduleName: string,
+    viewName?: string,
+  ): import('react').ComponentType<P>;
 }

package/src/index.ts

@@ -6,9 +6,15 @@
 // On a platform or build without the native module (Expo Go, web,
 // unlinked), every command is a safe no-op and the state stays idle —
 // so a host can render against this unconditionally.
-import { requireOptionalNativeModule } from 'expo-modules-core';
+import { createElement, type ComponentType, type ReactElement } from 'react';
+import { View, type ViewProps } from 'react-native';
+import { requireNativeViewManager, requireOptionalNativeModule } from 'expo-modules-core';
 
-/** A call's complete state. `null` means idle — no call. */
+/**
+ * A call's complete state. `null` means idle — no call. After a call
+ * ends the snapshot stays `phase: 'ended'` (with `reason`) for ~2.5 s,
+ * then becomes `null`.
+ */
 export interface Snapshot {
   cv: 1;
   callId: string;
@@ -26,16 +32,21 @@ export interface Snapshot {
     | 'cancelled'
     | 'connection_lost'
     | 'failed';
+  /** REMOTE participants only; `userId` is the LiveKit identity. */
   participants: Array<{
     userId: string;
     externalId: string;
     speaking: boolean;
     muted: boolean;
+    /** True only with a published, subscribed, unmuted camera track (show video, not avatar). */
     cameraOn: boolean;
   }>;
   audioRoute: 'earpiece' | 'speaker' | 'bluetooth' | 'headset';
   mutedSelf: boolean;
+  /** True only while the local camera track is actually published and enabled. */
   cameraOn: boolean;
+  /** Facing of the published local camera; absent when the camera is off. */
+  cameraFacing?: 'front' | 'back';
 }
 
 export interface ConfigureOptions {
@@ -64,6 +75,11 @@ interface PoolseCallsNative {
   setMuted(muted: boolean): void;
   setCamera(on: boolean): void;
   switchCamera(): void;
+  setSpeaker(on: boolean): void;
+  onRingEnded(callId: string, reason: string): void;
+  onCallFinished(callId: string, reason: string | null): void;
+  canUseFullScreenIntent(): boolean;
+  openFullScreenIntentSettings(): void;
   addListener(event: 'onCallState', cb: (payload: NativeSnapshot) => void): { remove(): void };
 }
 
@@ -77,7 +93,7 @@ export async function configure(apiBaseUrl: string, options?: ConfigureOptions):
   await native?.configure(apiBaseUrl, options ?? null);
 }
 
-/** The current snapshot — safe to read at any moment, including cold answer. */
+/** The current snapshot — safe to read at any moment, including cold answer and before configure. */
 export function getCallState(): Snapshot | null {
   return native?.getCallState().snapshot ?? null;
 }
@@ -109,3 +125,75 @@ export const hangUp = (): void => native?.hangUp();
 export const setMuted = (muted: boolean): void => native?.setMuted(muted);
 export const setCamera = (on: boolean): void => native?.setCamera(on);
 export const switchCamera = (): void => native?.switchCamera();
+/** Route call audio to the loudspeaker (`true`) or back to earpiece / headset (`false`). */
+export const setSpeaker = (on: boolean): void => native?.setSpeaker(on);
+
+/**
+ * Socket forwarding for an open app: a `call:ring_ended` seen on the
+ * socket. Idempotent with the push path — the core dedupes.
+ */
+export const onRingEnded = (callId: string, reason: string): void =>
+  native?.onRingEnded(callId, reason);
+
+/**
+ * Socket forwarding: `call:finished`. Pass the payload's `reason`
+ * (`finished` | `declined_all` | `no_answer` | `cancelled`) so an
+ * unanswered caller sees "Declined"/"No answer", not "Call ended".
+ * Idempotent with the `finished` push.
+ */
+export const onCallFinished = (callId: string, reason?: string): void =>
+  native?.onCallFinished(callId, reason ?? null);
+
+/**
+ * Android 14+: whether the app may show the full-screen ring over the
+ * lock screen. `true` on older Android and where the module is absent.
+ */
+export const canUseFullScreenIntent = (): boolean => native?.canUseFullScreenIntent() ?? true;
+
+/** Open the system screen where the user grants full-screen intents (falls back to notification settings). */
+export const openFullScreenIntentSettings = (): void => native?.openFullScreenIntentSettings();
+
+// ── video ─────────────────────────────────────────────────────────────
+
+export interface CallVideoViewProps extends ViewProps {
+  /** Remote participant's userId (LiveKit identity). Omit with local=true for self view. */
+  participantId?: string;
+  local?: boolean;
+  /** default: true for local front camera, false otherwise */
+  mirror?: boolean;
+  /** default 'cover' */
+  fit?: 'cover' | 'contain';
+}
+
+type NativeVideoProps = CallVideoViewProps;
+
+let nativeVideo: ComponentType<NativeVideoProps> | null | undefined;
+
+/** Resolved lazily (first render) and only when the native module exists. */
+function nativeVideoView(): ComponentType<NativeVideoProps> | null {
+  if (nativeVideo !== undefined) return nativeVideo;
+  nativeVideo = null;
+  if (native) {
+    try {
+      nativeVideo = requireNativeViewManager<NativeVideoProps>('PoolseCalls', 'PoolseCallVideo');
+    } catch {
+      nativeVideo = null; // an older native build without the view
+    }
+  }
+  return nativeVideo;
+}
+
+/**
+ * A participant's camera (or, with `local`, your own), rendered natively
+ * by the call core. Shows nothing (stays transparent) while that camera
+ * is off — draw the avatar from the snapshot's `cameraOn` underneath.
+ * Without the native module it renders an empty View.
+ */
+export function CallVideoView(props: CallVideoViewProps): ReactElement | null {
+  const Native = nativeVideoView();
+  if (!Native) {
+    const { participantId: _p, local: _l, mirror: _m, fit: _f, ...rest } = props;
+    return createElement(View, rest);
+  }
+  return createElement(Native, props);
+}

package/src/react-shims.d.ts

@@ -0,0 +1,22 @@
+// Minimal ambient declarations for the React / React Native surface this
+// package touches, so it type-checks without either installed in the
+// monorepo (the host app always supplies both). The emitted
+// `dist/index.d.ts` imports the REAL types by module name, so consumers
+// type-check against their own React Native — these shims never ship.
+declare module 'react' {
+  export interface ReactElement {
+    type: unknown;
+    props: unknown;
+    key: string | null;
+  }
+  export type ComponentType<P = object> = (props: P) => ReactElement | null;
+  export function createElement(type: unknown, props?: unknown, ...children: unknown[]): ReactElement;
+}
+
+declare module 'react-native' {
+  export interface ViewProps {
+    style?: unknown;
+    testID?: string;
+  }
+  export const View: unknown;
+}