@callimacus/thamyr-react-native 4.3.4

package/README.md

@@ -0,0 +1,173 @@
+# @callimacus/thamyr-react-native
+
+The Thamyr SDK for React Native (Expo and bare). It wraps
+`@callimacus/thamyr-react`, so the hooks, store, and response types are the same
+ones the web SDK exposes — this package narrows them to what works on native and
+adds a native voice recorder.
+
+```bash
+npm install @callimacus/thamyr-react-native
+```
+
+Peer dependencies: `react >=18`, `react-native >=0.72`.
+
+## Getting started
+
+```tsx
+import {useInitThamyr, useThamyr, useConnection} from '@callimacus/thamyr-react-native';
+
+function App() {
+  useInitThamyr({clientId: 'cal-pk-…'});
+  return <Chat />;
+}
+
+function Chat() {
+  const {history, sendEvent} = useThamyr();
+  const {status} = useConnection();
+  // …
+}
+```
+
+## What differs from the web SDK
+
+Everything not listed here behaves identically, because it is literally the same
+code.
+
+### Voice recording returns bytes
+
+The web recorder hands you a `Blob`; this one hands you a `Uint8Array`. Audio
+travels as `inputEvent.data.file` over socket.io, and only typed arrays survive
+that trip on native: a React Native `Blob` is a handle into the native
+BlobModule whose bytes never exist in JS, so socket.io cannot read it, and
+`new File([...])` — what the web path uses — has no useful native equivalent.
+The server drops the filename and mime type either way (socket.io's binary
+framing strips them), so nothing is lost.
+
+The recorder needs an adapter, which you build from `expo-audio`:
+
+```tsx
+import {useMemo} from 'react';
+import * as ExpoAudio from 'expo-audio';
+import {
+  createExpoAudioAdapter,
+  useVoiceRecorder,
+  useThamyr,
+  SLInputEventType,
+  UserInteractionType,
+} from '@callimacus/thamyr-react-native';
+
+function VoiceButton() {
+  const {sendEvent} = useThamyr();
+  const adapter = useMemo(() => createExpoAudioAdapter(ExpoAudio), []);
+
+  const {state, audioLevels, startRecording, stopRecording, error} = useVoiceRecorder({
+    adapter,
+    onRecordingComplete(audio) {
+      sendEvent(UserInteractionType.CREATE_ROUND, {
+        inputEvent: {type: SLInputEventType.question, data: {value: '', file: audio}},
+      });
+    },
+  });
+  // …
+}
+```
+
+The adapter is passed in rather than defaulted on purpose. If this package
+imported `expo-audio` itself, Metro would resolve it statically for every
+consumer, so an app that never records audio would fail to bundle merely for not
+having installed it. Handing the module in also keeps `expo-audio` out of this
+package's dependency graph entirely, so it typechecks and tests without a native
+toolchain. For a recorder other than `expo-audio`, implement
+`VoiceRecorderAdapter` yourself — `start`/`stop`/`cancel` over any native module.
+
+Recording auto-stops after `silenceDuration` (default 1800 ms) below
+`silenceThreshold` (default −45 dBFS), and hard-stops at `maxDuration` (default
+30 s).
+
+### Hooks that are not re-exported
+
+| Not available | Why | Instead |
+|---|---|---|
+| `useTtsAudio` | Constructs an `HTMLAudioElement` (`new Audio(url)`) | Play the URL from `extractTtsAudio(block.data)` with an `expo-audio` player |
+| `uiObserver` config | Snapshots mean `querySelectorAll` + `getBoundingClientRect` | Not yet available on native (SOL-1084) |
+| `setConsent`, `setGeo`, `initIntent`, … | `@callimacus/intent`'s browser API | `@callimacus/intent/native` — see below |
+
+`extractTtsAudio` and the `TtsAudio` type *are* exported, so you can get the
+audio URL out of a response and play it however you like; only the web playback
+hook is missing.
+
+### Intent tracking
+
+The intent web build cannot be imported on native at all: it reads
+`localStorage` and `document` at module scope, which throws under Hermes before
+your app renders. On React Native the SDK therefore resolves
+`@callimacus/thamyr-core`'s `react-native` entry, where intent is absent — its
+functions are present as warn-once no-ops so shared code does not crash, but they
+do nothing.
+
+Intent has its own native entry with a different shape. Wire it up directly:
+
+```ts
+import * as RN from 'react-native';
+import {MMKV} from 'react-native-mmkv';
+import {createNativeAdapters, initIntentNative, mmkvStorage} from '@callimacus/intent/native';
+
+initIntentNative({
+  clientId: 'cal-pk-…',
+  consent: true,
+  adapters: createNativeAdapters(RN, {storage: mmkvStorage(new MMKV())}),
+});
+```
+
+## Transports, and why voice does not work yet
+
+Text chat works. **Sending audio does not**, and the cause is neither this package
+nor your app — it is a TLS mismatch that forces the connection onto a transport
+which cannot carry binary on React Native. The detail matters because the symptom
+is misleading.
+
+**React Native cannot open a WebSocket to `api.callimacus.ai`.** The host is
+TLS 1.3-only — it rejects a TLS 1.2 handshake outright with a
+`protocol_version` alert (verified with `openssl s_client -no_tls1_3`). React
+Native's WebSocket fails against it with close code 1006 and
+`OSStatus -9836`, which is Apple's `errSSLPeerProtocolVersion` ("bad protocol
+version"). React Native's *HTTP* stack is fine with the same host, since that
+goes through `NSURLSession`, which does negotiate TLS 1.3 — consistent with the
+WebSocket path using the older SecureTransport route that does not.
+
+The SDK therefore falls back to HTTP long-polling, and text works over it.
+
+**But binary cannot traverse polling on React Native.** engine.io's polling
+payload is text, so `encodePayload` encodes every packet with
+`supportsBinary: false` ("force base64 encoding for binary packets"), and in
+engine.io-parser's browser build that path does
+`encodeBlobAsBase64(new Blob([data]))` — while React Native refuses to construct
+a Blob from an `ArrayBuffer` at all ("Creating blobs from 'ArrayBuffer' and
+'ArrayBufferView' are not supported"). So the audio bytes are dropped with a
+console error. `forceBase64` cannot help: polling already forces it, and that is
+precisely the branch that builds the Blob.
+
+**The fix is to let React Native use the WebSocket transport, by enabling TLS 1.2
+on the API host** (nginx: keep `TLSv1.3` and add `TLSv1.2` with a matching cipher
+suite). Over WebSocket, `encodePacket` runs with `supportsBinary: true` and hands
+the typed array straight to `WebSocket.send()` — no Blob, no base64 — so audio
+works with no further SDK change, and text gets lower latency as a bonus.
+
+Until then, recording works and `onRecordingComplete` gives you correct bytes;
+only the send fails.
+
+## Things worth knowing
+
+- **UUIDs.** Hermes ships no global `crypto`. Core falls back to
+  `crypto.getRandomValues` and then `Math.random()`, so nothing throws, but
+  installing [`react-native-get-random-values`](https://github.com/LinusU/react-native-get-random-values)
+  at the top of your entry file gets you cryptographically random interaction ids.
+- **`gatherClientInfo()`** returns empty strings for `userAgent`, `language`, and
+  `screenResolution` on native — there is no `navigator.userAgent` or
+  `window.screen`. Read screen size from `Dimensions` if you need it.
+- **Microphone permissions.** Add `NSMicrophoneUsageDescription` (iOS) and
+  `RECORD_AUDIO` (Android). Under Expo, `expo-audio`'s config plugin does this.
+- **Socket auth** goes through socket.io's `auth` payload, not an
+  `Authorization` header — React Native's WebSocket transport ignores
+  `extraHeaders`, and the server reads `handshake.auth.token`. No action needed;
+  it is noted because the header being dropped looks alarming in logs.

package/dist/esm/index.js

@@ -0,0 +1,9 @@
+/*!
+ * Copyright © 2025–2026 Solomei AI SRL. All rights reserved.
+ *
+ * Proprietary software, licensed for use by Callimacus customers only.
+ * See LICENSE.md for the full terms.
+ *
+ */
+import{useInitThamyr as e}from"@callimacus/thamyr-react";export{CallimacusEvent,ChapterStatus,ClientEvents,GalleryMode,SLInputEventType,ServerEvents,ThamyrHttpError,ThamyrResponseType,UserInteractionType,callimacusService,extractTtsAudio,isSetProduct,logger,thamyrApi,transformImageUrl,useApi,useCallimacusStore,useCart,useConnection,useOnConnectionChange,useOnError,useOnResponse,useSitemap,useSkesis,useThamyr}from"@callimacus/thamyr-react";import{useState as r,useRef as t,useCallback as n,useEffect as o}from"react";function i(r){e(r)}async function s(e){return new Promise((r,t)=>{const n=new XMLHttpRequest;n.responseType="arraybuffer","arraybuffer"===n.responseType?(n.addEventListener("load",()=>{const o=n.response;o instanceof ArrayBuffer?0!==o.byteLength?r(new Uint8Array(o)):t(new Error(`The recording at ${e} is empty`)):t(new Error(`Reading the recording at ${e} produced ${typeof o}, expected an ArrayBuffer`))}),n.addEventListener("error",()=>{t(new Error(`Failed to read the recording at ${e}`))}),n.open("GET",e,!0),n.send(null)):t(new Error('This runtime does not support XMLHttpRequest responseType "arraybuffer", so the recording cannot be read. Pass a custom adapter that returns bytes.'))})}const a=-45,c=1800,u=3e4;function d(e){if(!Number.isFinite(e))return 0;const r=(e- -60)/60;return Math.min(1,Math.max(0,r))}function l({silenceThreshold:e=a,silenceDuration:i=c,maxDuration:l=u,onRecordingComplete:p,adapter:y}){const[m,f]=r("idle"),[g,h]=r([]),[w,v]=r(void 0),[E,T]=r(void 0),M=t(y);M.current=y;const R=t(void 0),A=t([]),S=t(0),b=t(void 0),C=t(!1),I=t(p);I.current=p;const L=n(()=>{void 0!==b.current&&(clearTimeout(b.current),b.current=void 0)},[]),x=n(()=>{A.current=[],S.current=0,h([])},[]),H=n(()=>{if(C.current)return;C.current=!0,L(),f("processing");(async()=>{const e=R.current;R.current=void 0;try{if(!e)throw new Error("No active recording to stop");const r=await e.stop();T(r.uri),I.current(await s(r.uri))}catch(e){v(e instanceof Error?e.message:"Failed to finish recording")}finally{C.current=!1,f("idle")}})()},[L]),P=n(r=>{if(C.current)return;const t=[...A.current,d(r)];t.length>32&&t.splice(0,t.length-32),A.current=t,h(t),r<e?0===S.current?S.current=Date.now():Date.now()-S.current>i&&H():S.current=0},[e,i,H]),U=n(async()=>{v(void 0),C.current=!1,x();const e=M.current;R.current=e;try{await e.start({onMetering:P}),f("recording"),b.current=setTimeout(()=>{H()},l)}catch(r){R.current=void 0,v(r instanceof Error?r.message:"Microphone access denied"),f("idle"),await e.cancel()}},[P,l,x,H]),D=n(()=>{f("idle"),v(void 0),x()},[x]);return o(()=>()=>{L();const e=R.current;R.current=void 0,e?.cancel()},[L]),{state:m,audioLevels:g,startRecording:U,stopRecording:H,reset:D,error:w,lastRecordingUri:E}}function p(e){let r,t;function n(){void 0!==t&&(clearInterval(t),t=void 0)}return{async start({onMetering:n}){if(!(await e.requestRecordingPermissionsAsync()).granted)throw new Error("Microphone permission denied");await e.setAudioModeAsync({allowsRecording:!0,playsInSilentMode:!0});const o=new e.AudioModule.AudioRecorder({...e.RecordingPresets.HIGH_QUALITY,isMeteringEnabled:!0});await o.prepareToRecordAsync(),o.record(),r=o,t=setInterval(()=>{const e=o.getStatus();"number"==typeof e.metering&&n?.(e.metering)},100)},async stop(){if(!r)throw new Error("No active recording to stop");n();const e=r;r=void 0,await e.stop();const{uri:t}=e;if(null===t||""===t)throw new Error("Recording finished without producing a file");return{uri:t,durationMillis:e.getStatus().durationMillis}},async cancel(){if(n(),!r)return;const e=r;r=void 0;try{await e.stop()}catch{}}}}export{p as createExpoAudioAdapter,s as readRecording,i as useInitThamyr,l as useVoiceRecorder};
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/callimacus/index.ts","../../../src/voice/read-recording.ts","../../../src/voice/use-voice-recorder.ts","../../../src/voice/adapters/expo-audio.ts"],"sourcesContent":[null,null,null,null],"names":["useInitThamyr","config","useInitThamyrWeb","async","readRecording","uri","Promise","resolve","reject","request","XMLHttpRequest","responseType","addEventListener","response","ArrayBuffer","byteLength","Uint8Array","Error","open","send","defaultOptions","normalizeMetering","db","Number","isFinite","level","Math","min","max","useVoiceRecorder","silenceThreshold","silenceDuration","maxDuration","onRecordingComplete","adapter","state","setState","useState","audioLevels","setAudioLevels","error","setError","undefined","lastRecordingUri","setLastRecordingUri","adapterRef","useRef","current","activeAdapterRef","levelsRef","silenceStartRef","maxDurationTimerRef","stoppingRef","onCompleteRef","clearMaxDurationTimer","useCallback","clearTimeout","resetWaveform","stopRecording","active","result","stop","error_","message","finish","handleMetering","next","length","splice","Date","now","startRecording","start","onMetering","setTimeout","cancel","reset","useEffect","createExpoAudioAdapter","expoAudio","recorder","meterTimer","stopMeterTimer","clearInterval","requestRecordingPermissionsAsync","granted","setAudioModeAsync","allowsRecording","playsInSilentMode","AudioModule","AudioRecorder","RecordingPresets","HIGH_QUALITY","isMeteringEnabled","prepareToRecordAsync","record","setInterval","status","getStatus","metering","durationMillis"],"mappings":"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"}

package/dist/esm/query.js

@@ -0,0 +1,9 @@
+/*!
+ * Copyright © 2025–2026 Solomei AI SRL. All rights reserved.
+ *
+ * Proprietary software, licensed for use by Callimacus customers only.
+ * See LICENSE.md for the full terms.
+ *
+ */
+export*from"@callimacus/thamyr-react/query";
+//# sourceMappingURL=query.js.map

package/dist/esm/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;"}

package/dist/types/index.d.ts

@@ -0,0 +1,277 @@
+/*!
+ * Copyright © 2025–2026 Solomei AI SRL. All rights reserved.
+ *
+ * Proprietary software, licensed for use by Callimacus customers only.
+ * See LICENSE.md for the full terms.
+ *
+ */
+export { Block, BoundingBox, CallimacusEvent, CartActions, Chapter, ChapterStatus, ClientEvents, ClientInfo, ConnectionStatus, ConnectionStatusCallback, ErrorCallback, ErrorMessage, Gallery, GalleryMode, Image, ImageEdits, ImageFormatEdit, ImageResizeEdit, InteractionContext, InteractionPayloadMap, LocalizedEPArtwork, LocalizedEPChapter, LogLevel, LoggerConfig, ProductMatch, SLDocument, SLDocumentSection, SLInputEvent, SLInputEventType, ServerEvents, ServerResponseCallback, SitemapActions, SkesisActions, Story, ThamyrHttpError, ThamyrResponse, ThamyrResponseType, Topic, TtsAudio, UiElement, UiSnapshot, UserInteraction, UserInteractionType, Video, WhisperPayload, callimacusService, extractTtsAudio, isSetProduct, logger, thamyrApi, transformImageUrl, useApi, useCallimacusStore, useCart, useConnection, useOnConnectionChange, useOnError, useOnResponse, useSitemap, useSkesis, useThamyr } from '@callimacus/thamyr-react';
+
+/**
+ Configuration for initializing the Thamyr SDK via `useInitThamyr` on React Native.
+
+ Intentionally narrower than the web (`@callimacus/thamyr-react`) config: the
+ `uiObserver` option is **omitted** because collecting a snapshot means
+ `querySelectorAll` + `getBoundingClientRect`, which have no React Native analog.
+ The `UiSnapshot` data contract itself is platform-neutral, so responses can still
+ carry that context; only the collection side is web-only. React Native
+ UI-snapshot support is its own feature (SOL-1084) and will need a different
+ design — explicit registration through viewability hooks / `measureInWindow`
+ rather than an autonomous observer.
+ */
+type CallimacusInitConfig = {
+    /**
+    Your Callimacus public client ID (`cal-pk-…`).
+    */
+    clientId?: string;
+    /**
+    Server endpoint URL. Uses the default Thamyr endpoint when omitted.
+    */
+    endpoint?: string;
+    /**
+    Maximum number of messages to retain in history. Set to `0` for unlimited. Defaults to `50`.
+    */
+    maxMessages?: number;
+};
+
+/**
+ Initialize the Thamyr SDK for React Native usage.
+
+ Thin wrapper over the shared initializer from `@callimacus/thamyr-react` that
+ narrows the config to the React Native surface (no `uiObserver`). Call this once
+ in your root component. When `clientId` or `endpoint` change, the SDK is torn
+ down and re-initialized.
+
+ @param config - SDK configuration (client ID, endpoint, max messages).
+
+ @example
+ ```tsx
+ function App() {
+   useInitThamyr({clientId: 'cal-pk-…'});
+   return <RootNavigator />;
+ }
+ ```
+ */
+declare function useInitThamyr(config: CallimacusInitConfig): void;
+
+type VoiceRecorderState = 'idle' | 'recording' | 'processing';
+type UseVoiceRecorderOptions = {
+    /**
+     Metering level (in dBFS, a negative value) below which audio is considered silence.
+     Defaults to `-45`.
+     */
+    silenceThreshold?: number;
+    /**
+    How long (ms) the level must stay below the threshold before auto-stopping. Defaults to `1800`.
+    */
+    silenceDuration?: number;
+    /**
+    Hard cap (ms) on a single recording. Defaults to `30_000`.
+    */
+    maxDuration?: number;
+    /**
+     Called once recording finishes, with the captured audio as raw bytes.
+
+     This is a `Uint8Array` rather than the web recorder's `Blob` on purpose.
+     Audio travels as `inputEvent.data.file` over socket.io, which serialises typed
+     arrays as binary attachments that arrive server-side as a Node `Buffer`. A
+     React Native `Blob` is a handle into the native BlobModule whose bytes never
+     exist in JS, so socket.io cannot read it; and `new File([...])` — what the web
+     path uses — has no useful React Native equivalent. The server discards the
+     filename and mime type anyway (socket.io's binary framing strips them), so
+     nothing is lost by sending bytes directly.
+
+     Pass it to `sendUserInteraction` rather than `sendAudio`, which is typed for
+     the web `Blob` — see {@link useVoiceRecorder} for the call.
+     */
+    onRecordingComplete: (audio: Uint8Array) => void;
+    /**
+     The recorder implementation. Build one from `expo-audio` with
+     `createExpoAudioAdapter(ExpoAudio)`, or supply your own for a different native
+     recorder in bare React Native.
+
+     Required, rather than defaulting to `expo-audio`: a default would mean this
+     package referencing `expo-audio` itself, which Metro resolves statically — so
+     apps that never record audio would fail to bundle without it installed. Pass a
+     memoized adapter so it keeps a stable identity across renders.
+     */
+    adapter: VoiceRecorderAdapter;
+};
+type UseVoiceRecorderReturn = {
+    state: VoiceRecorderState;
+    /**
+    Rolling, normalised (0..1) waveform of recent audio levels, length 32.
+    */
+    audioLevels: number[];
+    startRecording: () => Promise<void>;
+    stopRecording: () => void;
+    reset: () => void;
+    error: string | undefined;
+    /**
+    File URI of the most recent completed recording, if any.
+    */
+    lastRecordingUri: string | undefined;
+};
+/**
+Result of a completed native recording.
+*/
+type RecordingResult = {
+    /**
+    Local file URI of the recording (e.g. `file:///...`).
+    */
+    uri: string;
+    /**
+    Recording duration in milliseconds, when the adapter reports it.
+    */
+    durationMillis?: number;
+};
+/**
+ Abstraction over a native audio recorder so the hook stays independent of any
+ single library. The built-in adapter targets `expo-audio`; bare React Native apps
+ can implement this against `react-native-audio-recorder-player` or similar.
+ */
+type VoiceRecorderAdapter = {
+    /**
+     Begins recording. `onMetering` should be invoked periodically with the current
+     input level in dBFS (a negative number; `0` is loudest). It drives both the
+     waveform and silence detection.
+     */
+    start: (options: {
+        onMetering?: (db: number) => void;
+    }) => Promise<void>;
+    /**
+    Stops recording and resolves with the resulting file.
+    */
+    stop: () => Promise<RecordingResult>;
+    /**
+    Aborts recording and discards any output. Safe to call when not recording.
+    */
+    cancel: () => Promise<void>;
+};
+
+/**
+ React Native voice recorder hook. Mirrors the control surface of the web recorder
+ in `@callimacus/thamyr-react` (`state`, `audioLevels`, `startRecording`,
+ `stopRecording`, `reset`, `error`) so cross-platform call sites stay aligned.
+
+ It differs in one deliberate way: `onRecordingComplete` receives a `Uint8Array`
+ rather than a `Blob`, because that is what survives socket.io's binary framing on
+ native. See {@link UseVoiceRecorderOptions.onRecordingComplete}.
+
+ Recording is delegated to a {@link VoiceRecorderAdapter} — see
+ {@link UseVoiceRecorderOptions.adapter} for why it is passed in rather than
+ defaulted. Silence detection and the max-duration cap run in JS off the adapter's
+ metering stream.
+
+ @example
+ ```tsx
+ import * as ExpoAudio from 'expo-audio';
+
+ const {sendEvent} = useThamyr();
+ const adapter = useMemo(() => createExpoAudioAdapter(ExpoAudio), []);
+ const {state, startRecording, stopRecording} = useVoiceRecorder({
+   adapter,
+   onRecordingComplete(audio) {
+     sendEvent(UserInteractionType.CREATE_ROUND, {
+       inputEvent: {type: SLInputEventType.question, data: {value: '', file: audio}},
+     });
+   },
+ });
+ ```
+ */
+declare function useVoiceRecorder({ silenceThreshold, silenceDuration, maxDuration, onRecordingComplete, adapter, }: UseVoiceRecorderOptions): UseVoiceRecorderReturn;
+
+/**
+ The slice of a recorder instance this adapter drives.
+
+ Structural rather than `import type {AudioRecorder} from 'expo-audio'` so this
+ package neither depends on `expo-audio` nor leaks it into consumers' typechecks.
+ */
+type ExpoAudioRecorderLike = {
+    uri: string | null;
+    prepareToRecordAsync: () => Promise<unknown>;
+    record: () => void;
+    stop: () => Promise<unknown>;
+    getStatus: () => {
+        metering?: number;
+        durationMillis?: number;
+    };
+};
+/**
+ The slice of the `expo-audio` module this adapter uses. `import * as ExpoAudio
+ from 'expo-audio'` satisfies it.
+ */
+type ExpoAudioLike = {
+    AudioModule: {
+        AudioRecorder: new (options: Record<string, unknown>) => ExpoAudioRecorderLike;
+    };
+    RecordingPresets: Record<string, Record<string, unknown>>;
+    setAudioModeAsync: (mode: {
+        allowsRecording?: boolean;
+        playsInSilentMode?: boolean;
+    }) => Promise<unknown>;
+    requestRecordingPermissionsAsync: () => Promise<{
+        granted: boolean;
+    }>;
+};
+/**
+ {@link VoiceRecorderAdapter} backed by `expo-audio` — the current Expo audio
+ module, and the successor to `expo-av`, which Expo removed in SDK 54.
+
+ The module is **handed in rather than imported**, which is the whole point of the
+ signature:
+
+ - `require('expo-audio')` inside this package would make Metro resolve it
+   statically for every consumer, so an app that never records audio would fail to
+   bundle merely for not having installed it. An "optional peer dependency" that
+   breaks the build when absent is not optional.
+ - `await import('expo-audio')` is worse: Metro serves no async bundle splits at
+   runtime, so it fails with "Could not load bundle".
+ - Keeping `expo-audio` out of this package's dependency graph also means it
+   typechecks and tests with no native toolchain, against a plain object.
+
+ Metering is delivered by polling `recorder.getStatus().metering`, since
+ `expo-audio` exposes no push-based metering stream.
+
+ @param expoAudio - The `expo-audio` module namespace.
+
+ @example
+ ```tsx
+ import * as ExpoAudio from 'expo-audio';
+ import {createExpoAudioAdapter, useVoiceRecorder} from '@callimacus/thamyr-react-native';
+
+ const adapter = useMemo(() => createExpoAudioAdapter(ExpoAudio), []);
+ const recorder = useVoiceRecorder({adapter, onRecordingComplete: sendAudio});
+ ```
+ */
+declare function createExpoAudioAdapter(expoAudio: ExpoAudioLike): VoiceRecorderAdapter;
+
+/**
+ Reads a local recording file into raw bytes.
+
+ `XMLHttpRequest` with `responseType = 'arraybuffer'` is the route that actually
+ works on React Native, and the choice is worth recording because the two obvious
+ alternatives do not:
+
+ - `fetch(uri).then(r => r.arrayBuffer())` — React Native's fetch is the
+   whatwg-fetch polyfill, whose `arrayBuffer()` goes through
+   `FileReader.readAsArrayBuffer` on a Blob. That works on current React Native
+   but adds a Blob round-trip for no benefit.
+ - `new Blob([arrayBuffer])` — React Native forbids it outright ("Creating blobs
+   from 'ArrayBuffer' and 'ArrayBufferView' are not supported"), so any path that
+   tries to rebuild a Blob from bytes is a dead end.
+
+ React Native's XHR maps `responseType = 'arraybuffer'` onto a native base64
+ response and decodes it into a real `ArrayBuffer` (see
+ `react-native/Libraries/Network/XMLHttpRequest.js`), which is exactly the one
+ conversion needed here. `arraybuffer` support is itself conditional on
+ `global.ArrayBuffer` in that file, so it is feature-detected below rather than
+ assumed.
+
+ @param uri - A local file URI, as produced by the recorder adapter.
+ @returns The file's bytes.
+ */
+declare function readRecording(uri: string): Promise<Uint8Array>;
+
+export { createExpoAudioAdapter, readRecording, useInitThamyr, useVoiceRecorder };
+export type { CallimacusInitConfig, ExpoAudioLike, RecordingResult, UseVoiceRecorderOptions, UseVoiceRecorderReturn, VoiceRecorderAdapter, VoiceRecorderState };

package/dist/types/query.d.ts

@@ -0,0 +1,8 @@
+/*!
+ * Copyright © 2025–2026 Solomei AI SRL. All rights reserved.
+ *
+ * Proprietary software, licensed for use by Callimacus customers only.
+ * See LICENSE.md for the full terms.
+ *
+ */
+export * from '@callimacus/thamyr-react/query';

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@callimacus/thamyr-react-native",
+  "version": "4.3.4",
+  "private": false,
+  "description": "React Native package for Thamyr",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "homepage": "https://docs.callimacus.ai/thamyr-sdk/react-native/1-overview",
+  "main": "dist/esm/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "react-native": "dist/esm/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./query": {
+      "import": "./dist/esm/query.js",
+      "types": "./dist/types/query.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "CHANGELOG.core.md",
+    "MIGRATION.md"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "@callimacus:registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "prepack": "cp ../../MIGRATION.md ./MIGRATION.md && cp ../core/CHANGELOG.md ./CHANGELOG.core.md",
+    "build": "rollup -c",
+    "dev": "rollup -c -w",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "lint": "eslint src"
+  },
+  "dependencies": {
+    "@callimacus/thamyr-react": "^4.3.4"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.72",
+    "@tanstack/react-query": "^5"
+  },
+  "devDependencies": {
+    "@eslint-react/eslint-plugin": "^5.20.8",
+    "@testing-library/react": "^16.3.3",
+    "@types/react": "^19.3.0",
+    "eslint-config-xo": "^4.0.1",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "jsdom": "^30.1.1",
+    "react": "^19.3.0",
+    "react-native": "^0.87.1",
+    "vitest": "^5.0.2",
+    "@tanstack/react-query": "^5"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    }
+  }
+}