@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.

npm install @callimacus/thamyr-react-native

Peer dependencies: react >=18, react-native >=0.72.

Getting started

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:

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

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:

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 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.