From c926eeae3ac78ef5fe6bba8fe30f79a55af6b601 Mon Sep 17 00:00:00 2001
From: "Yermie Cohen, MD" <yermie@users.noreply.github.com>
Date: Mon, 6 Oct 2025 16:06:49 -0700
Subject: [PATCH 1/2] feat: add react native package

---
 README.md                                     |  29 ++-
 docs/react-native/getting-started.md          | 120 ++++++++++++
 packages/chatkit-react-native/README.md       | 122 +++++++++++++
 packages/chatkit-react-native/package.json    |  73 ++++++++
 packages/chatkit-react-native/src/index.ts    |  28 +++
 .../src/networking/streaming.ts               | 132 ++++++++++++++
 .../src/polyfills/index.ts                    |  39 ++++
 .../src/realtime/webrtc.ts                    | 147 +++++++++++++++
 .../src/realtime/websocket.ts                 |  63 +++++++
 .../chatkit-react-native/src/types/expo.d.ts  |  39 ++++
 .../chatkit-react-native/src/types/shims.d.ts |  84 +++++++++
 .../src/ui/ChatComposer.tsx                   | 149 +++++++++++++++
 .../chatkit-react-native/src/ui/ChatList.tsx  | 171 ++++++++++++++++++
 .../src/utils/EventEmitter.ts                 |  47 +++++
 .../src/voice/useVoiceSession.ts              | 137 ++++++++++++++
 packages/chatkit-react-native/tsconfig.json   |  18 ++
 16 files changed, 1395 insertions(+), 3 deletions(-)
 create mode 100644 docs/react-native/getting-started.md
 create mode 100644 packages/chatkit-react-native/README.md
 create mode 100644 packages/chatkit-react-native/package.json
 create mode 100644 packages/chatkit-react-native/src/index.ts
 create mode 100644 packages/chatkit-react-native/src/networking/streaming.ts
 create mode 100644 packages/chatkit-react-native/src/polyfills/index.ts
 create mode 100644 packages/chatkit-react-native/src/realtime/webrtc.ts
 create mode 100644 packages/chatkit-react-native/src/realtime/websocket.ts
 create mode 100644 packages/chatkit-react-native/src/types/expo.d.ts
 create mode 100644 packages/chatkit-react-native/src/types/shims.d.ts
 create mode 100644 packages/chatkit-react-native/src/ui/ChatComposer.tsx
 create mode 100644 packages/chatkit-react-native/src/ui/ChatList.tsx
 create mode 100644 packages/chatkit-react-native/src/utils/EventEmitter.ts
 create mode 100644 packages/chatkit-react-native/src/voice/useVoiceSession.ts
 create mode 100644 packages/chatkit-react-native/tsconfig.json

diff --git a/README.md b/README.md
index e657665..10c871a 100644
--- a/README.md
+++ b/README.md
@@ -79,9 +79,32 @@ Just add the ChatKit component, give it a client token, and customize the chat e
        },
      });
 
-     return <ChatKit control={control} className="h-[600px] w-[320px]" />;
-   }
-   ```
+   return <ChatKit control={control} className="h-[600px] w-[320px]" />;
+  }
+  ```
+
+### React Native (Expo) preview
+
+Experimental support for Expo and bare React Native apps lives in the `@openai/chatkit-react-native` package. The library ships
+streaming HTTP helpers, WebRTC wrappers, voice primitives, and opinionated UI building blocks (`ChatList`, `ChatComposer`).
+
+- Install the package alongside the recommended polyfills:
+
+  ```bash
+  pnpm add @openai/chatkit-react-native react-native-polyfill-globals react-native-url-polyfill react-native-get-random-values base-64
+  ```
+
+- Import the polyfills at the top of your app entry point before rendering any ChatKit component:
+
+  ```ts
+  import 'react-native-polyfill-globals/auto';
+  import 'react-native-url-polyfill/auto';
+  import 'react-native-get-random-values';
+  import 'base-64';
+  ```
+
+Read the [React Native getting started guide](docs/react-native/getting-started.md) for details on Expo networking, WebRTC
+signalling, voice support, and testing recommendations.
 
 ## License
 
diff --git a/docs/react-native/getting-started.md b/docs/react-native/getting-started.md
new file mode 100644
index 0000000..7e01eca
--- /dev/null
+++ b/docs/react-native/getting-started.md
@@ -0,0 +1,120 @@
+# React Native (Expo) Support
+
+This guide captures the minimum setup for adopting `@openai/chatkit-react-native` inside a new or existing React Native project. The instructions assume you are using [Expo](https://docs.expo.dev) with the development build workflow, but also call out fallbacks for bare React Native.
+
+## 1. Install dependencies
+
+```bash
+pnpm add @openai/chatkit-react-native
+pnpm add react-native-polyfill-globals react-native-url-polyfill react-native-get-random-values base-64
+pnpm add expo expo-dev-client expo-av expo-speech expo-file-system expo-document-picker
+pnpm add react-native-webrtc
+# For bare React Native (non-Expo) projects
+pnpm add react-native-fetch-api
+```
+
+## 2. Configure polyfills
+
+Add the following imports at the top of your app entry (for example `app/index.tsx` when using Expo Router or `index.js` for bare projects):
+
+```ts
+import 'react-native-polyfill-globals/auto';
+import 'react-native-url-polyfill/auto';
+import 'react-native-get-random-values';
+import 'base-64';
+```
+
+Polyfills must run before any ChatKit code executes to ensure `TextEncoder`, `TextDecoder`, `ReadableStream`, `URL`, `crypto.getRandomValues`, `atob` and `btoa` are defined.
+
+## 3. Streaming HTTP helpers
+
+`createStreamingFetcher` wraps Expo's `fetch` implementation and falls back to `react-native-fetch-api` for apps not running inside the Expo runtime. It exposes lifecycle hooks that map cleanly onto ChatKit's expectations.
+
+```ts
+import { createStreamingFetcher } from '@openai/chatkit-react-native';
+
+const streamingFetch = createStreamingFetcher();
+
+const { response } = await streamingFetch(
+  'https://api.openai.com/v1/responses',
+  {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${process.env.EXPO_PUBLIC_OPENAI_API_KEY}`,
+    },
+    body: JSON.stringify({
+      model: 'gpt-4.1-mini',
+      input: [{ role: 'user', content: 'Hello!' }],
+    }),
+  },
+  {
+    onResponseStart: () => console.log('stream started'),
+    onChunk: (chunk) => console.log('chunk', chunk),
+    onResponseEnd: () => console.log('stream ended'),
+  },
+);
+```
+
+## 4. Realtime via WebRTC
+
+`createWebRTCSession` bridges [`react-native-webrtc`](https://github.com/react-native-webrtc/react-native-webrtc) with ChatKit's realtime API. Provide a signalling adapter that exchanges offers/answers with your backend. The backend should authenticate with OpenAI and create a WebRTC session on behalf of the device.
+
+```ts
+const session = await createWebRTCSession({
+  signalling: {
+    negotiate: async (offer) => {
+      const response = await fetch('https://your-server.example.com/negotiate', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ offer }),
+      });
+      if (!response.ok) throw new Error('Failed to negotiate');
+      return response.json();
+    },
+  },
+  onResponseChunk: (chunk) => console.log('Realtime chunk', chunk),
+});
+
+await session.start();
+```
+
+For server-to-server integrations or for environments where WebRTC is not available, `createWebSocketSession` provides a lightweight wrapper over the standard `WebSocket` implementation.
+
+## 5. Voice mode
+
+The `useVoiceSession` hook layers [`expo-av`](https://docs.expo.dev/versions/latest/sdk/av/) for microphone capture with [`expo-speech`](https://docs.expo.dev/versions/latest/sdk/speech/) for text-to-speech output.
+
+```tsx
+const voice = useVoiceSession();
+
+return (
+  <View>
+    <Button title={voice.isRecording ? 'Stop' : 'Record'} onPress={voice.isRecording ? voice.stopRecording : voice.startRecording} />
+    <Button title="Play response" onPress={() => voice.speak('Processing request…')} />
+  </View>
+);
+```
+
+## 6. UI primitives
+
+`ChatList` and `ChatComposer` are unstyled building blocks that work with [`FlatList`](https://reactnative.dev/docs/flatlist) and React Native primitives. They intentionally avoid taking a dependency on any specific design system so you can wrap them with [Gluestack UI](https://gluestack.io/), [React Native Paper](https://callstack.github.io/react-native-paper/) or your own component library.
+
+## 7. Testing & CI
+
+- Use [Expo Application Services (EAS) Build](https://docs.expo.dev/build/introduction/) to produce reproducible binaries with the required native modules.
+- Add simulator coverage for both iOS and Android in CI (e.g. GitHub Actions with `react-native-testing-library`).
+- Include integration smoke tests that call the streaming HTTP helper and WebRTC wrapper to catch regressions in networking polyfills.
+
+## 8. Versioning strategy
+
+Mirror the version numbers from the web ChatKit packages. Introduce RN-specific fixes as patch releases and plan for a weekly merge from upstream to stay in sync with API additions.
+
+## 9. Example apps
+
+Two example apps complement this package:
+
+- `examples/expo-chat`: Expo Router, streaming completions, voice capture.
+- `examples/react-native-chat`: bare React Native CLI project focusing on WebRTC.
+
+The examples intentionally live outside of the npm package to keep installs lean while still providing real-world references.
diff --git a/packages/chatkit-react-native/README.md b/packages/chatkit-react-native/README.md
new file mode 100644
index 0000000..00215bd
--- /dev/null
+++ b/packages/chatkit-react-native/README.md
@@ -0,0 +1,122 @@
+# @openai/chatkit-react-native
+
+React Native bindings and opinionated UI utilities for [OpenAI ChatKit](https://github.com/openai/chatkit).
+
+> **Status:** experimental. The API surface will track the web ChatKit package but may contain additional React Native specific helpers. Expect breaking changes while the package matures.
+
+## Installation
+
+```bash
+pnpm add @openai/chatkit-react-native
+# required peer dependencies
+pnpm add react react-native
+# recommended polyfills
+pnpm add react-native-polyfill-globals react-native-url-polyfill react-native-get-random-values base-64
+# optional Expo integrations
+pnpm add expo expo-av expo-speech expo-file-system expo-document-picker
+# optional non-Expo fallback
+pnpm add react-native-fetch-api
+# realtime
+pnpm add react-native-webrtc
+```
+
+Enable the auto-polyfill entry point as early as possible in your app (e.g. `index.js`). This ensures `TextEncoder`, `TextDecoder`, `ReadableStream`, `URL`, `crypto.getRandomValues`, and `atob`/`btoa` are available before ChatKit is used.
+
+```ts
+import 'react-native-polyfill-globals/auto';
+import 'react-native-url-polyfill/auto';
+import 'react-native-get-random-values';
+import 'base-64';
+```
+
+Expo users should also install [`expo-dev-client`](https://docs.expo.dev/develop/development-builds/introduction/) to exercise native modules locally.
+
+## Quick start
+
+```tsx
+import { ChatComposer, ChatList, createStreamingFetcher } from '@openai/chatkit-react-native';
+
+const fetcher = createStreamingFetcher();
+
+function ConversationScreen() {
+  const [messages, setMessages] = React.useState([]);
+
+  const handleSend = async (content: string) => {
+    const controller = new AbortController();
+    const { stream } = await fetcher(
+      'https://api.openai.com/v1/responses',
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${process.env.EXPO_PUBLIC_OPENAI_API_KEY}`,
+        },
+        body: JSON.stringify({
+          model: 'gpt-4.1-mini',
+          input: [{ role: 'user', content }],
+        }),
+        signal: controller.signal,
+      },
+      {
+        onResponseStart: () => console.log('response started'),
+        onChunk: (chunk) => console.log('chunk', chunk),
+        onResponseEnd: () => console.log('response ended'),
+      },
+    );
+
+    return () => controller.abort();
+  };
+
+  return (
+    <>
+      <ChatList messages={messages} />
+      <ChatComposer onSend={handleSend} />
+    </>
+  );
+}
+```
+
+## Features
+
+- **Streaming HTTP helpers** with fallbacks for Expo (`expo/fetch`) and bare React Native (`react-native-fetch-api`).
+- **Realtime helpers** built on top of `react-native-webrtc` with WebSocket fallback for server-side usage.
+- **UI primitives** (`ChatList`, `ChatComposer`) that work with [`FlatList`](https://reactnative.dev/docs/flatlist) and provide opinionated defaults for avatars, timestamps and assistant badges.
+- **Voice helpers** to capture microphone input via `expo-av` and synthesize responses using `expo-speech`.
+
+## Realtime signalling
+
+`createWebRTCSession` expects a signalling adapter that exchanges SDP offers/answers with your server. The server can in turn call OpenAI's Realtime API. See `src/realtime` for a reference implementation you can adapt for your backend stack.
+
+```ts
+const signalling = {
+  negotiate: async (offer: RTCSessionDescriptionInit) => {
+    const response = await fetch('https://example.com/realtime/negotiate', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ offer }),
+    });
+    if (!response.ok) throw new Error('Failed to negotiate');
+    return response.json();
+  },
+};
+
+const session = await createWebRTCSession({
+  signalling,
+  onResponseChunk: (chunk) => console.log(chunk),
+});
+```
+
+## Example apps
+
+- `examples/expo-chat`: Expo Router sample using `expo-dev-client` and `expo-av` for voice capture.
+- `examples/react-native-chat`: bare React Native CLI sample featuring WebRTC and WebSocket fallbacks.
+
+> Example apps are tracked separately to keep this package lightweight.
+
+## Development
+
+The package uses [tsup](https://tsup.egoist.dev/) to emit both ESM and CJS bundles that Metro can consume. Run `pnpm --filter @openai/chatkit-react-native build` to produce distributable artifacts.
+
+## License
+
+MIT
diff --git a/packages/chatkit-react-native/package.json b/packages/chatkit-react-native/package.json
new file mode 100644
index 0000000..0d7767b
--- /dev/null
+++ b/packages/chatkit-react-native/package.json
@@ -0,0 +1,73 @@
+{
+  "name": "@openai/chatkit-react-native",
+  "version": "0.0.0",
+  "description": "React Native bindings and utilities for OpenAI ChatKit.",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    },
+    "./polyfills": {
+      "types": "./dist/polyfills/index.d.ts",
+      "import": "./dist/polyfills/index.js",
+      "require": "./dist/polyfills/index.cjs",
+      "default": "./dist/polyfills/index.js"
+    }
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.74",
+    "expo": ">=50",
+    "expo-av": "*",
+    "expo-speech": "*",
+    "react-native-fetch-api": "^3.0.0",
+    "react-native-webrtc": ">=1.108.0"
+  },
+  "peerDependenciesMeta": {
+    "expo": {
+      "optional": true
+    },
+    "expo-av": {
+      "optional": true
+    },
+    "expo-speech": {
+      "optional": true
+    },
+    "react-native-fetch-api": {
+      "optional": true
+    },
+    "react-native-webrtc": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@openai/chatkit": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "@types/react-native": "^0.73.0",
+    "rimraf": "^5.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/polyfills/index.ts --format esm,cjs --dts --clean --external expo-av --external expo-speech --external expo/fetch --external react-native-fetch-api",
+    "clean": "rimraf dist"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "license": "MIT"
+}
diff --git a/packages/chatkit-react-native/src/index.ts b/packages/chatkit-react-native/src/index.ts
new file mode 100644
index 0000000..f2e06b5
--- /dev/null
+++ b/packages/chatkit-react-native/src/index.ts
@@ -0,0 +1,28 @@
+export type * from '@openai/chatkit';
+
+export { ensureReactNativePolyfills } from './polyfills/index';
+export { createStreamingFetcher } from './networking/streaming';
+export type {
+  StreamingFetcher,
+  StreamingFetcherHooks,
+  StreamingFetcherOptions,
+} from './networking/streaming';
+
+export { createWebRTCSession } from './realtime/webrtc';
+export type { WebRTCSession, WebRTCSessionOptions, WebRTCSignalling } from './realtime/webrtc';
+
+export { createWebSocketSession } from './realtime/websocket';
+export type {
+  WebSocketSession,
+  WebSocketSessionOptions,
+  WebSocketOptions,
+} from './realtime/websocket';
+
+export { ChatComposer } from './ui/ChatComposer';
+export type { ChatComposerProps } from './ui/ChatComposer';
+
+export { ChatList } from './ui/ChatList';
+export type { ChatListProps, ChatMessage } from './ui/ChatList';
+
+export { useVoiceSession } from './voice/useVoiceSession';
+export type { VoiceSessionOptions, VoiceSession } from './voice/useVoiceSession';
diff --git a/packages/chatkit-react-native/src/networking/streaming.ts b/packages/chatkit-react-native/src/networking/streaming.ts
new file mode 100644
index 0000000..3923508
--- /dev/null
+++ b/packages/chatkit-react-native/src/networking/streaming.ts
@@ -0,0 +1,132 @@
+declare const require: any;
+
+type FetchImpl = typeof fetch;
+
+export interface StreamingFetcherHooks {
+  onResponseStart?: (response: Response) => void;
+  onChunk?: (chunk: string) => void;
+  onResponseEnd?: () => void;
+}
+
+export interface StreamingFetcherOptions {
+  /**
+   * Provide a custom fetch implementation. Defaults to Expo's fetch, then the React Native Fetch API polyfill.
+   */
+  fetchImplementation?: FetchImpl;
+  /**
+   * Force using the React Native Fetch API polyfill even when Expo is available.
+   */
+  forceReactNativeFetch?: boolean;
+}
+
+export interface StreamingResult {
+  response: Response;
+  stream: ReadableStream<Uint8Array> | null;
+}
+
+export type StreamingFetcher = (
+  input: RequestInfo | URL,
+  init?: RequestInit,
+  hooks?: StreamingFetcherHooks,
+) => Promise<StreamingResult>;
+
+/**
+ * Attempt to resolve a fetch implementation suitable for the current runtime.
+ */
+async function resolveFetch(options?: StreamingFetcherOptions): Promise<FetchImpl> {
+  if (options?.fetchImplementation) {
+    return options.fetchImplementation;
+  }
+
+  if (!options?.forceReactNativeFetch) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const expoModule = require('expo/fetch');
+      const expoFetch: FetchImpl = expoModule.fetch ?? expoModule.default ?? expoModule;
+      if (typeof expoFetch === 'function') {
+        return expoFetch;
+      }
+    } catch (error) {
+      // Expo is optional; ignore resolution failures.
+      if (process.env.NODE_ENV !== 'production') {
+        console.debug('[chatkit-react-native] expo/fetch unavailable', error);
+      }
+    }
+  }
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const rnFetchModule = require('react-native-fetch-api');
+    const rnFetch: FetchImpl = rnFetchModule.fetch ?? rnFetchModule.default ?? rnFetchModule;
+    if (typeof rnFetch === 'function') {
+      return ((input: RequestInfo | URL, init?: RequestInit) => {
+        const config = {
+          ...(init as any),
+          reactNative: {
+            textStreaming: true,
+            ...((init as any)?.reactNative ?? {}),
+          },
+        };
+        return rnFetch(input, config as RequestInit);
+      }) as FetchImpl;
+    }
+  } catch (error) {
+    if (process.env.NODE_ENV !== 'production') {
+      console.debug('[chatkit-react-native] react-native-fetch-api unavailable', error);
+    }
+  }
+
+  if (typeof fetch !== 'undefined') {
+    return fetch;
+  }
+
+  throw new Error(
+    'No fetch implementation found. Provide `fetchImplementation` or install `expo/fetch` or `react-native-fetch-api`.',
+  );
+}
+
+export function createStreamingFetcher(options?: StreamingFetcherOptions): StreamingFetcher {
+  return async (input, init, hooks) => {
+    const fetchImpl = await resolveFetch(options);
+    const response = await fetchImpl(input, init as any);
+
+    hooks?.onResponseStart?.(response);
+
+    const stream = response.body;
+    if (!stream) {
+      const text = await response.text();
+      if (text && hooks?.onChunk) {
+        hooks.onChunk(text);
+      }
+      hooks?.onResponseEnd?.();
+      return { response, stream: null };
+    }
+
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+
+    async function pump(): Promise<void> {
+      const { done, value } = await reader.read();
+      if (done) {
+        hooks?.onResponseEnd?.();
+        return;
+      }
+      if (value) {
+        const chunk = decoder.decode(value, { stream: true });
+        if (chunk && hooks?.onChunk) {
+          hooks.onChunk(chunk);
+        }
+      }
+      await pump();
+    }
+
+    pump().catch((error) => {
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn('[chatkit-react-native] streaming error', error);
+      }
+      hooks?.onResponseEnd?.();
+    });
+
+    return { response, stream };
+  };
+}
diff --git a/packages/chatkit-react-native/src/polyfills/index.ts b/packages/chatkit-react-native/src/polyfills/index.ts
new file mode 100644
index 0000000..69ff195
--- /dev/null
+++ b/packages/chatkit-react-native/src/polyfills/index.ts
@@ -0,0 +1,39 @@
+/**
+ * Ensures a handful of browser-like globals exist before ChatKit runs inside React Native.
+ *
+ * The function performs runtime checks so it is safe to call multiple times.
+ */
+export function ensureReactNativePolyfills() {
+  if (typeof globalThis.TextEncoder === 'undefined') {
+    throw new Error(
+      'TextEncoder is not available. Install `react-native-polyfill-globals` and import the auto polyfill entry first.',
+    );
+  }
+  if (typeof globalThis.TextDecoder === 'undefined') {
+    throw new Error(
+      'TextDecoder is not available. Install `react-native-polyfill-globals` and import the auto polyfill entry first.',
+    );
+  }
+  if (typeof globalThis.ReadableStream === 'undefined') {
+    throw new Error(
+      'ReadableStream is not available. Install `react-native-polyfill-globals` and import the auto polyfill entry first.',
+    );
+  }
+  if (typeof globalThis.URL === 'undefined') {
+    throw new Error(
+      'URL is not available. Install `react-native-url-polyfill` or supply your own implementation.',
+    );
+  }
+  if (typeof globalThis.crypto?.getRandomValues !== 'function') {
+    throw new Error(
+      'crypto.getRandomValues is not available. Install `react-native-get-random-values` to polyfill Web Crypto APIs.',
+    );
+  }
+  if (typeof globalThis.atob !== 'function' || typeof globalThis.btoa !== 'function') {
+    throw new Error(
+      'Base64 helpers are missing. Install the `base-64` package and import it once at startup.',
+    );
+  }
+}
+
+export default ensureReactNativePolyfills;
diff --git a/packages/chatkit-react-native/src/realtime/webrtc.ts b/packages/chatkit-react-native/src/realtime/webrtc.ts
new file mode 100644
index 0000000..deaa443
--- /dev/null
+++ b/packages/chatkit-react-native/src/realtime/webrtc.ts
@@ -0,0 +1,147 @@
+import { EventEmitter } from '../utils/EventEmitter';
+
+type MaybePromise<T> = T | Promise<T>;
+
+export interface WebRTCSignalling {
+  negotiate(offer: RTCSessionDescriptionInit): MaybePromise<{
+    answer: RTCSessionDescriptionInit;
+    iceServers?: RTCIceServer[];
+    iceCandidates?: RTCIceCandidateInit[];
+  }>;
+  sendIceCandidate?: (candidate: RTCIceCandidateInit) => MaybePromise<void>;
+}
+
+export interface WebRTCSessionOptions {
+  signalling: WebRTCSignalling;
+  peerConnection?: RTCPeerConnection;
+  channelLabel?: string;
+  onResponseStart?: () => void;
+  onResponseChunk?: (chunk: string) => void;
+  onResponseEnd?: () => void;
+  onError?: (error: unknown) => void;
+}
+
+export interface WebRTCSession {
+  connection: RTCPeerConnection;
+  channel: RTCDataChannel | null;
+  start: () => Promise<void>;
+  close: () => void;
+  send: (data: string | ArrayBuffer | ArrayBufferView) => void;
+  events: EventEmitter;
+}
+
+export async function createWebRTCSession(options: WebRTCSessionOptions): Promise<WebRTCSession> {
+  const {
+    signalling,
+    peerConnection = new RTCPeerConnection(),
+    channelLabel = 'openai-chatkit',
+    onResponseChunk,
+    onResponseEnd,
+    onResponseStart,
+    onError,
+  } = options;
+
+  const events = new EventEmitter();
+  const channel = peerConnection.createDataChannel(channelLabel);
+
+  channel.binaryType = 'arraybuffer';
+
+  channel.onmessage = (event) => {
+    const value = typeof event.data === 'string' ? event.data : new TextDecoder().decode(event.data);
+    events.emit('message', value);
+    onResponseChunk?.(value);
+  };
+
+  channel.onopen = () => {
+    events.emit('open');
+    onResponseStart?.();
+  };
+
+  channel.onclose = () => {
+    events.emit('close');
+    onResponseEnd?.();
+  };
+
+  channel.onerror = (error) => {
+    events.emit('error', error);
+    onError?.(error);
+  };
+
+  peerConnection.onicecandidate = async (event) => {
+    const candidate = event.candidate?.toJSON();
+    if (!candidate) return;
+    try {
+      if (signalling.sendIceCandidate) {
+        await signalling.sendIceCandidate(candidate);
+      }
+      events.emit('icecandidate', candidate);
+    } catch (error) {
+      events.emit('error', error);
+      onError?.(error);
+    }
+  };
+
+  peerConnection.ondatachannel = (event) => {
+    // Remote peers may create their own channel; wire up the same handlers.
+    const remoteChannel = event.channel;
+    remoteChannel.onmessage = channel.onmessage;
+    remoteChannel.onopen = channel.onopen;
+    remoteChannel.onclose = channel.onclose;
+    remoteChannel.onerror = channel.onerror;
+  };
+
+  async function start() {
+    try {
+      const offer = await peerConnection.createOffer({ offerToReceiveAudio: true });
+      await peerConnection.setLocalDescription(offer);
+
+      const { answer, iceServers, iceCandidates } = await signalling.negotiate(offer);
+
+      if (iceServers?.length) {
+        const configuration = peerConnection.getConfiguration();
+        peerConnection.setConfiguration({ ...configuration, iceServers });
+      }
+
+      await peerConnection.setRemoteDescription(answer);
+
+      if (iceCandidates?.length) {
+        for (const candidate of iceCandidates) {
+          await peerConnection.addIceCandidate(candidate);
+        }
+      }
+    } catch (error) {
+      events.emit('error', error);
+      onError?.(error);
+      throw error;
+    }
+  }
+
+  function close() {
+    try {
+      if (channel.readyState === 'open' || channel.readyState === 'connecting') {
+        channel.close();
+      }
+    } catch (error) {
+      events.emit('error', error);
+      onError?.(error);
+    }
+    peerConnection.close();
+    onResponseEnd?.();
+  }
+
+  function send(data: string | ArrayBuffer | ArrayBufferView) {
+    if (channel.readyState !== 'open') {
+      throw new Error('RTCDataChannel is not open. Wait for `onopen` before sending messages.');
+    }
+    channel.send(data as any);
+  }
+
+  return {
+    connection: peerConnection,
+    channel,
+    start,
+    close,
+    send,
+    events,
+  };
+}
diff --git a/packages/chatkit-react-native/src/realtime/websocket.ts b/packages/chatkit-react-native/src/realtime/websocket.ts
new file mode 100644
index 0000000..030fd75
--- /dev/null
+++ b/packages/chatkit-react-native/src/realtime/websocket.ts
@@ -0,0 +1,63 @@
+import { EventEmitter } from '../utils/EventEmitter';
+
+export interface WebSocketOptions {
+  headers?: Record<string, string>;
+}
+
+export interface WebSocketSessionOptions {
+  url: string;
+  protocols?: string | string[];
+  init?: WebSocketOptions;
+  onResponseStart?: () => void;
+  onResponseChunk?: (chunk: string) => void;
+  onResponseEnd?: () => void;
+  onError?: (error: unknown) => void;
+}
+
+export interface WebSocketSession {
+  socket: WebSocket;
+  events: EventEmitter;
+  send: (data: string | ArrayBufferLike | Blob) => void;
+  close: (code?: number, reason?: string) => void;
+}
+
+export function createWebSocketSession(options: WebSocketSessionOptions): WebSocketSession {
+  const { url, protocols, init, onResponseChunk, onResponseEnd, onResponseStart, onError } = options;
+
+  const socket: WebSocket = new (WebSocket as any)(url, protocols, init);
+  const events = new EventEmitter();
+
+  socket.onopen = () => {
+    events.emit('open');
+    onResponseStart?.();
+  };
+
+  socket.onmessage = (event) => {
+    const data = typeof event.data === 'string' ? event.data : String(event.data);
+    events.emit('message', data);
+    onResponseChunk?.(data);
+  };
+
+  socket.onerror = (event) => {
+    events.emit('error', event);
+    onError?.(event);
+  };
+
+  socket.onclose = (event) => {
+    events.emit('close', event);
+    onResponseEnd?.();
+  };
+
+  function send(data: string | ArrayBufferLike | Blob) {
+    if (socket.readyState !== WebSocket.OPEN) {
+      throw new Error('WebSocket is not open. Wait for the connection to open before sending messages.');
+    }
+    socket.send(data);
+  }
+
+  function close(code?: number, reason?: string) {
+    socket.close(code, reason);
+  }
+
+  return { socket, events, send, close };
+}
diff --git a/packages/chatkit-react-native/src/types/expo.d.ts b/packages/chatkit-react-native/src/types/expo.d.ts
new file mode 100644
index 0000000..b886cdd
--- /dev/null
+++ b/packages/chatkit-react-native/src/types/expo.d.ts
@@ -0,0 +1,39 @@
+declare module 'expo/fetch' {
+  export const fetch: typeof globalThis.fetch;
+  export default fetch;
+}
+
+declare module 'expo-av' {
+  export namespace Audio {
+    interface RecordingOptions {
+      [key: string]: unknown;
+    }
+    class Recording {
+      startAsync(): Promise<void>;
+      stopAndUnloadAsync(): Promise<void>;
+      getURI(): string | null;
+    }
+    function requestPermissionsAsync(): Promise<{ status: 'granted' | 'denied' }>;
+    namespace Recording {
+      function createAsync(options?: RecordingOptions): Promise<{ recording: Recording }>;
+    }
+  }
+}
+
+declare module 'expo-speech' {
+  export interface SpeechOptions {
+    language?: string;
+    pitch?: number;
+    rate?: number;
+    voice?: string;
+    onDone?: (...args: any[]) => void;
+    onStopped?: (...args: any[]) => void;
+    onError?: (...args: any[]) => void;
+  }
+  export function speak(text: string, options?: SpeechOptions): void;
+}
+
+declare module 'react-native-fetch-api' {
+  export const fetch: typeof globalThis.fetch;
+  export default fetch;
+}
diff --git a/packages/chatkit-react-native/src/types/shims.d.ts b/packages/chatkit-react-native/src/types/shims.d.ts
new file mode 100644
index 0000000..8e52bb7
--- /dev/null
+++ b/packages/chatkit-react-native/src/types/shims.d.ts
@@ -0,0 +1,84 @@
+declare namespace React {
+  type ReactNode = any;
+  type ReactElement = any;
+  interface ComponentProps<T> extends Record<string, any> {}
+}
+
+declare module 'react' {
+  const React: {
+    useState: <T>(value: T | (() => T)) => [T, (update: T | ((prev: T) => T)) => void];
+    useRef: <T>(value: T | null) => { current: T | null };
+    useCallback: <T extends (...args: any[]) => any>(fn: T, deps: any[]) => T;
+    useLayoutEffect: (effect: () => void | (() => void), deps?: any[]) => void;
+    forwardRef: <T, P = any>(render: (props: P, ref: any) => any) => (props: P & { ref?: any }) => any;
+  };
+  export = React;
+  export type ReactNode = any;
+  export type ReactElement = any;
+  export type FC<P = {}> = (props: P) => ReactElement | null;
+  export type ComponentProps<T> = any;
+  export type HTMLAttributes<T> = Record<string, any>;
+  export type DetailedHTMLProps<P, T> = P & { ref?: any };
+}
+
+declare module 'react-native' {
+  export const Platform: {
+    OS: 'ios' | 'android' | 'macos' | 'windows' | 'web' | string;
+    select: <T>(spec: { ios?: T; android?: T; default?: T }) => T | undefined;
+  };
+
+  export interface ViewProps {
+    style?: any;
+    [key: string]: any;
+  }
+
+  export interface TextProps {
+    children?: React.ReactNode;
+    style?: any;
+  }
+
+  export interface TextInputProps {
+    value?: string;
+    onChangeText?: (text: string) => void;
+    editable?: boolean;
+    multiline?: boolean;
+    placeholder?: string;
+    placeholderTextColor?: string;
+    onSubmitEditing?: (event: any) => void;
+    blurOnSubmit?: boolean;
+    style?: any;
+    autoFocus?: boolean;
+  }
+
+  export interface FlatListProps<ItemT> {
+    data?: readonly ItemT[] | null;
+    renderItem?: (info: { item: ItemT; index: number }) => React.ReactElement | null;
+    keyExtractor?: (item: ItemT, index: number) => string;
+    contentContainerStyle?: any;
+    [key: string]: any;
+  }
+
+  export class FlatList<ItemT> {
+    constructor(props: FlatListProps<ItemT>);
+  }
+
+  export const StyleSheet: {
+    create<T extends { [key: string]: any }>(styles: T): T;
+    hairlineWidth: number;
+  };
+
+  export const View: (props: ViewProps & { children?: React.ReactNode }) => React.ReactElement;
+  export const Text: (props: TextProps) => React.ReactElement;
+  export const Image: (props: { source: { uri: string }; style?: any }) => React.ReactElement;
+  export const TextInput: (props: TextInputProps) => React.ReactElement;
+  export const TouchableOpacity: (props: any) => React.ReactElement;
+  export const KeyboardAvoidingView: (props: any) => React.ReactElement;
+}
+
+declare module '@openai/chatkit' {
+  export type ChatKitOptions = Record<string, any>;
+}
+
+declare const process: {
+  env: Record<string, string | undefined>;
+};
diff --git a/packages/chatkit-react-native/src/ui/ChatComposer.tsx b/packages/chatkit-react-native/src/ui/ChatComposer.tsx
new file mode 100644
index 0000000..729241c
--- /dev/null
+++ b/packages/chatkit-react-native/src/ui/ChatComposer.tsx
@@ -0,0 +1,149 @@
+import * as React from 'react';
+import {
+  KeyboardAvoidingView,
+  Platform,
+  StyleSheet,
+  TextInput,
+  TouchableOpacity,
+  View,
+  Text,
+} from 'react-native';
+
+export interface ChatComposerProps {
+  onSend: (message: string) => void | Promise<void>;
+  onAttachPress?: () => void;
+  onVoicePress?: () => void;
+  placeholder?: string;
+  sendLabel?: string;
+  disabled?: boolean;
+  autoFocus?: boolean;
+  style?: React.ComponentProps<typeof View>['style'];
+}
+
+export function ChatComposer({
+  onSend,
+  onAttachPress,
+  onVoicePress,
+  placeholder = 'Message Assistant…',
+  sendLabel = 'Send',
+  disabled = false,
+  autoFocus = false,
+  style,
+}: ChatComposerProps) {
+  const [value, setValue] = React.useState('');
+  const [isSending, setIsSending] = React.useState(false);
+
+  const handleSend = React.useCallback(async () => {
+    if (!value.trim() || disabled || isSending) return;
+    setIsSending(true);
+    try {
+      await onSend(value.trim());
+      setValue('');
+    } finally {
+      setIsSending(false);
+    }
+  }, [disabled, isSending, onSend, value]);
+
+  return (
+    <KeyboardAvoidingView
+      style={[styles.container, style]}
+      behavior={Platform.select({ ios: 'padding', default: undefined })}
+      keyboardVerticalOffset={Platform.OS === 'ios' ? 72 : 0}
+    >
+      <View style={styles.inner}>
+        <TouchableOpacity
+          accessibilityLabel="Attach"
+          accessibilityRole="button"
+          onPress={onAttachPress}
+          style={styles.iconButton}
+          disabled={disabled || isSending}
+        >
+          <Text style={styles.iconLabel}>＋</Text>
+        </TouchableOpacity>
+        <TextInput
+          style={styles.input}
+          multiline
+          value={value}
+          autoFocus={autoFocus}
+          editable={!disabled && !isSending}
+          onChangeText={setValue}
+          placeholder={placeholder}
+          placeholderTextColor="#9CA3AF"
+          onSubmitEditing={handleSend}
+          blurOnSubmit={false}
+        />
+        <TouchableOpacity
+          accessibilityLabel="Voice"
+          accessibilityRole="button"
+          onPress={onVoicePress}
+          style={styles.iconButton}
+          disabled={disabled || isSending}
+        >
+          <Text style={styles.iconLabel}>🎤</Text>
+        </TouchableOpacity>
+        <TouchableOpacity
+          accessibilityRole="button"
+          accessibilityLabel="Send message"
+          onPress={handleSend}
+          style={[styles.sendButton, (disabled || isSending || !value.trim()) && styles.sendButtonDisabled]}
+          disabled={disabled || isSending || !value.trim()}
+        >
+          <Text style={styles.sendLabel}>{isSending ? '…' : sendLabel}</Text>
+        </TouchableOpacity>
+      </View>
+    </KeyboardAvoidingView>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    paddingHorizontal: 16,
+    paddingVertical: 12,
+    backgroundColor: '#FFFFFF',
+    borderTopWidth: StyleSheet.hairlineWidth,
+    borderTopColor: '#E5E7EB',
+  },
+  inner: {
+    flexDirection: 'row',
+    alignItems: 'flex-end',
+    gap: 8,
+  },
+  iconButton: {
+    width: 40,
+    height: 40,
+    borderRadius: 20,
+    alignItems: 'center',
+    justifyContent: 'center',
+    backgroundColor: '#F3F4F6',
+  },
+  iconLabel: {
+    fontSize: 20,
+    color: '#4B5563',
+  },
+  input: {
+    flex: 1,
+    maxHeight: 160,
+    minHeight: 40,
+    paddingHorizontal: 12,
+    paddingVertical: 10,
+    borderRadius: 18,
+    backgroundColor: '#F9FAFB',
+    fontSize: 16,
+    lineHeight: 22,
+    color: '#111827',
+  },
+  sendButton: {
+    borderRadius: 20,
+    paddingHorizontal: 16,
+    paddingVertical: 10,
+    backgroundColor: '#111827',
+  },
+  sendButtonDisabled: {
+    backgroundColor: '#D1D5DB',
+  },
+  sendLabel: {
+    color: '#FFFFFF',
+    fontSize: 14,
+    fontWeight: '600',
+  },
+});
diff --git a/packages/chatkit-react-native/src/ui/ChatList.tsx b/packages/chatkit-react-native/src/ui/ChatList.tsx
new file mode 100644
index 0000000..5b670ad
--- /dev/null
+++ b/packages/chatkit-react-native/src/ui/ChatList.tsx
@@ -0,0 +1,171 @@
+import * as React from 'react';
+import { FlatList, StyleSheet, Text, View, type FlatListProps, Image } from 'react-native';
+
+export interface ChatMessage {
+  id: string;
+  role: 'user' | 'assistant' | 'system' | string;
+  content: string;
+  createdAt?: Date | string | number;
+  avatarUri?: string;
+  isStreaming?: boolean;
+}
+
+export interface ChatListProps extends Partial<FlatListProps<ChatMessage>> {
+  messages: ChatMessage[];
+  showTimestamps?: boolean;
+  showAssistantBadge?: boolean;
+  renderMessage?: (item: ChatMessage) => React.ReactElement | null;
+  assistantBadgeLabel?: string;
+}
+
+const DEFAULT_BADGE_LABEL = 'Assistant';
+
+function formatTimestamp(value?: Date | string | number): string | undefined {
+  if (!value) return undefined;
+  const date = value instanceof Date ? value : new Date(value);
+  return date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+}
+
+function Bubble({ message, showTimestamps, showAssistantBadge, assistantBadgeLabel }: {
+  message: ChatMessage;
+  showTimestamps?: boolean;
+  showAssistantBadge?: boolean;
+  assistantBadgeLabel?: string;
+}) {
+  const isAssistant = message.role === 'assistant';
+  const timestamp = showTimestamps ? formatTimestamp(message.createdAt) : undefined;
+
+  return (
+    <View style={[styles.row, isAssistant ? styles.rowAssistant : styles.rowUser]}>
+      {message.avatarUri ? (
+        <Image source={{ uri: message.avatarUri }} style={styles.avatar} />
+      ) : (
+        <View style={styles.avatarPlaceholder} />
+      )}
+      <View style={[styles.bubble, isAssistant ? styles.bubbleAssistant : styles.bubbleUser]}>
+        {showAssistantBadge && isAssistant ? (
+          <View style={styles.badge}>
+            <Text style={styles.badgeLabel}>{assistantBadgeLabel ?? DEFAULT_BADGE_LABEL}</Text>
+          </View>
+        ) : null}
+        <Text style={styles.content}>{message.content}</Text>
+        {message.isStreaming ? <View style={styles.typingIndicator} /> : null}
+        {timestamp ? <Text style={styles.timestamp}>{timestamp}</Text> : null}
+      </View>
+    </View>
+  );
+}
+
+export function ChatList({
+  messages,
+  showAssistantBadge = true,
+  showTimestamps = true,
+  assistantBadgeLabel = DEFAULT_BADGE_LABEL,
+  renderMessage,
+  ...flatListProps
+}: ChatListProps) {
+  const renderItem = React.useCallback<NonNullable<FlatListProps<ChatMessage>['renderItem']>>(
+    ({ item }) => {
+      if (renderMessage) {
+        return renderMessage(item);
+      }
+      return (
+        <Bubble
+          message={item}
+          showAssistantBadge={showAssistantBadge}
+          showTimestamps={showTimestamps}
+          assistantBadgeLabel={assistantBadgeLabel}
+        />
+      );
+    },
+    [assistantBadgeLabel, renderMessage, showAssistantBadge, showTimestamps],
+  );
+
+  const keyExtractor = React.useCallback((item: ChatMessage) => item.id, []);
+
+  return (
+    <FlatList
+      accessibilityRole="list"
+      data={messages}
+      keyExtractor={keyExtractor}
+      renderItem={renderItem}
+      contentContainerStyle={[styles.container, flatListProps.contentContainerStyle]}
+      {...flatListProps}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    paddingHorizontal: 16,
+    paddingVertical: 24,
+    gap: 16,
+  },
+  row: {
+    flexDirection: 'row',
+    alignItems: 'flex-start',
+    gap: 12,
+  },
+  rowAssistant: {
+    justifyContent: 'flex-start',
+  },
+  rowUser: {
+    justifyContent: 'flex-end',
+  },
+  avatar: {
+    width: 36,
+    height: 36,
+    borderRadius: 18,
+  },
+  avatarPlaceholder: {
+    width: 36,
+    height: 36,
+    borderRadius: 18,
+    backgroundColor: '#E1E4E8',
+  },
+  bubble: {
+    flex: 1,
+    paddingHorizontal: 12,
+    paddingVertical: 10,
+    borderRadius: 16,
+    backgroundColor: '#F0F0F0',
+    gap: 6,
+  },
+  bubbleAssistant: {
+    backgroundColor: '#EEF2FF',
+  },
+  bubbleUser: {
+    backgroundColor: '#D1FAE5',
+  },
+  content: {
+    fontSize: 16,
+    lineHeight: 22,
+    color: '#1F2937',
+  },
+  typingIndicator: {
+    width: 40,
+    height: 4,
+    borderRadius: 999,
+    backgroundColor: '#A5B4FC',
+    alignSelf: 'flex-start',
+  },
+  timestamp: {
+    fontSize: 12,
+    color: '#6B7280',
+    alignSelf: 'flex-end',
+  },
+  badge: {
+    alignSelf: 'flex-start',
+    paddingHorizontal: 6,
+    paddingVertical: 2,
+    borderRadius: 999,
+    backgroundColor: '#6366F1',
+  },
+  badgeLabel: {
+    fontSize: 10,
+    fontWeight: '600',
+    color: '#FFFFFF',
+    letterSpacing: 0.5,
+    textTransform: 'uppercase',
+  },
+});
diff --git a/packages/chatkit-react-native/src/utils/EventEmitter.ts b/packages/chatkit-react-native/src/utils/EventEmitter.ts
new file mode 100644
index 0000000..832ab75
--- /dev/null
+++ b/packages/chatkit-react-native/src/utils/EventEmitter.ts
@@ -0,0 +1,47 @@
+export type Listener<T extends any[] = any[]> = (...args: T) => void;
+
+export class EventEmitter {
+  private listeners = new Map<string, Set<Listener>>();
+
+  on<T extends any[]>(event: string, listener: Listener<T>) {
+    const set = this.listeners.get(event) ?? new Set();
+    set.add(listener as Listener);
+    this.listeners.set(event, set);
+    return this;
+  }
+
+  off<T extends any[]>(event: string, listener: Listener<T>) {
+    const set = this.listeners.get(event);
+    if (!set) return this;
+    set.delete(listener as Listener);
+    if (set.size === 0) {
+      this.listeners.delete(event);
+    }
+    return this;
+  }
+
+  once<T extends any[]>(event: string, listener: Listener<T>) {
+    const wrapper: Listener<T> = ((...args: T) => {
+      this.off(event, wrapper);
+      listener(...args);
+    }) as Listener<T>;
+    return this.on(event, wrapper);
+  }
+
+  emit<T extends any[]>(event: string, ...args: T) {
+    const set = this.listeners.get(event);
+    if (!set) return false;
+    for (const listener of Array.from(set)) {
+      listener(...args);
+    }
+    return true;
+  }
+
+  removeAllListeners(event?: string) {
+    if (typeof event === 'string') {
+      this.listeners.delete(event);
+    } else {
+      this.listeners.clear();
+    }
+  }
+}
diff --git a/packages/chatkit-react-native/src/voice/useVoiceSession.ts b/packages/chatkit-react-native/src/voice/useVoiceSession.ts
new file mode 100644
index 0000000..d088287
--- /dev/null
+++ b/packages/chatkit-react-native/src/voice/useVoiceSession.ts
@@ -0,0 +1,137 @@
+import * as React from 'react';
+
+type RecordingOptions = import('expo-av').Audio.RecordingOptions;
+type SpeechOptions = import('expo-speech').SpeechOptions;
+
+export interface VoiceSessionOptions {
+  recordingOptions?: RecordingOptions;
+  speechOptions?: SpeechOptions;
+}
+
+export interface VoiceSession {
+  isRecording: boolean;
+  isSpeaking: boolean;
+  transcript: string | null;
+  startRecording: () => Promise<void>;
+  stopRecording: () => Promise<string | null>;
+  speak: (text: string) => Promise<void>;
+  resetTranscript: () => void;
+}
+
+let expoAudio: typeof import('expo-av');
+let expoSpeech: typeof import('expo-speech');
+
+async function ensureModules() {
+  if (!expoAudio) {
+    try {
+      expoAudio = await import('expo-av');
+    } catch (error) {
+      throw new Error(
+        'expo-av is required for voice capture. Install it with `expo install expo-av` or `pnpm add expo-av`.',
+        { cause: error },
+      );
+    }
+  }
+  if (!expoSpeech) {
+    try {
+      expoSpeech = await import('expo-speech');
+    } catch (error) {
+      throw new Error(
+        'expo-speech is required for text-to-speech playback. Install it with `expo install expo-speech` or `pnpm add expo-speech`.',
+        { cause: error },
+      );
+    }
+  }
+}
+
+async function startRecording(options?: RecordingOptions) {
+  await expoAudio.Audio.requestPermissionsAsync();
+  const { recording } = await expoAudio.Audio.Recording.createAsync(options);
+  await recording.startAsync();
+  return recording;
+}
+
+async function stopRecordingInstance(recording: import('expo-av').Audio.Recording | null) {
+  if (!recording) return null;
+  try {
+    await recording.stopAndUnloadAsync();
+    const uri = recording.getURI();
+    return uri ?? null;
+  } finally {
+  }
+}
+
+async function speak(text: string, options?: SpeechOptions) {
+  await new Promise<void>((resolve) => {
+    expoSpeech.speak(text, {
+      ...(options ?? {}),
+      onDone: (...args) => {
+        options?.onDone?.(...args);
+        resolve();
+      },
+      onStopped: (...args) => {
+        options?.onStopped?.(...args);
+        resolve();
+      },
+      onError: (...args) => {
+        options?.onError?.(...args);
+        resolve();
+      },
+    });
+  });
+}
+
+export function useVoiceSession(options: VoiceSessionOptions = {}): VoiceSession {
+  const recordingRef = React.useRef<import('expo-av').Audio.Recording | null>(null);
+  const [isRecording, setIsRecording] = React.useState(false);
+  const [isSpeaking, setIsSpeaking] = React.useState(false);
+  const [transcript, setTranscript] = React.useState<string | null>(null);
+
+  const start = React.useCallback(async () => {
+    await ensureModules();
+    if (isRecording) return;
+    setIsRecording(true);
+    try {
+      const recording = await startRecording(options.recordingOptions);
+      recordingRef.current = recording;
+    } catch (error) {
+      setIsRecording(false);
+      throw error;
+    }
+  }, [isRecording, options.recordingOptions]);
+
+  const stop = React.useCallback(async () => {
+    await ensureModules();
+    const uri = await stopRecordingInstance(recordingRef.current);
+    recordingRef.current = null;
+    setIsRecording(false);
+    setTranscript(uri);
+    return uri;
+  }, []);
+
+  const play = React.useCallback(
+    async (text: string) => {
+      await ensureModules();
+      if (!text) return;
+      setIsSpeaking(true);
+      try {
+        await speak(text, options.speechOptions);
+      } finally {
+        setIsSpeaking(false);
+      }
+    },
+    [options.speechOptions],
+  );
+
+  const resetTranscript = React.useCallback(() => setTranscript(null), []);
+
+  return {
+    isRecording,
+    isSpeaking,
+    transcript,
+    startRecording: start,
+    stopRecording: stop,
+    speak: play,
+    resetTranscript,
+  };
+}
diff --git a/packages/chatkit-react-native/tsconfig.json b/packages/chatkit-react-native/tsconfig.json
new file mode 100644
index 0000000..8ab3ffa
--- /dev/null
+++ b/packages/chatkit-react-native/tsconfig.json
@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "jsx": "react-native",
+    "outDir": "dist",
+    "rootDir": "src",
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "verbatimModuleSyntax": true,
+    "baseUrl": "."
+  },
+  "include": ["src"]
+}

From 1954c2ba428df503e9c4dd6ea64012f2aee3601f Mon Sep 17 00:00:00 2001
From: "Yermie Cohen, MD" <yermie@users.noreply.github.com>
Date: Mon, 6 Oct 2025 16:12:26 -0700
Subject: [PATCH 2/2] docs: add testing instructions for react native package

---
 README.md                               | 11 +++++++++++
 docs/react-native/getting-started.md    |  2 ++
 packages/chatkit-react-native/README.md |  8 ++++++++
 3 files changed, 21 insertions(+)

diff --git a/README.md b/README.md
index 10c871a..34946f4 100644
--- a/README.md
+++ b/README.md
@@ -106,6 +106,17 @@ streaming HTTP helpers, WebRTC wrappers, voice primitives, and opinionated UI bu
 Read the [React Native getting started guide](docs/react-native/getting-started.md) for details on Expo networking, WebRTC
 signalling, voice support, and testing recommendations.
 
+### Testing the React Native package
+
+Run the package build to ensure the TypeScript sources compile before publishing:
+
+```bash
+pnpm --filter @openai/chatkit-react-native build
+```
+
+The command bundles the entry points with `tsup` and validates the generated type declarations. If you are iterating on the
+package locally, you can append `--watch` to rebuild on file changes.
+
 ## License
 
 This project is licensed under the [Apache License 2.0](LICENSE).
diff --git a/docs/react-native/getting-started.md b/docs/react-native/getting-started.md
index 7e01eca..f3a5bda 100644
--- a/docs/react-native/getting-started.md
+++ b/docs/react-native/getting-started.md
@@ -102,6 +102,8 @@ return (
 
 ## 7. Testing & CI
 
+- Run `pnpm --filter @openai/chatkit-react-native build` locally (or with `--watch` while iterating) to confirm the TypeScript
+  sources compile and the emitted declarations stay up to date.
 - Use [Expo Application Services (EAS) Build](https://docs.expo.dev/build/introduction/) to produce reproducible binaries with the required native modules.
 - Add simulator coverage for both iOS and Android in CI (e.g. GitHub Actions with `react-native-testing-library`).
 - Include integration smoke tests that call the streaming HTTP helper and WebRTC wrapper to catch regressions in networking polyfills.
diff --git a/packages/chatkit-react-native/README.md b/packages/chatkit-react-native/README.md
index 00215bd..80c4860 100644
--- a/packages/chatkit-react-native/README.md
+++ b/packages/chatkit-react-native/README.md
@@ -117,6 +117,14 @@ const session = await createWebRTCSession({
 
 The package uses [tsup](https://tsup.egoist.dev/) to emit both ESM and CJS bundles that Metro can consume. Run `pnpm --filter @openai/chatkit-react-native build` to produce distributable artifacts.
 
+To continuously recompile during local development, pass the `--watch` flag:
+
+```bash
+pnpm --filter @openai/chatkit-react-native build --watch
+```
+
+This keeps the generated output and type declarations in sync with your source edits.
+
 ## License
 
 MIT