@alia.onl/sdk 13.1.0 → 15.2.1

package/src/hooks/useDictation.ts

@@ -0,0 +1,295 @@
+/**
+ * The composer's microphone: record a clip, then transcribe it with a Kaana
+ * transcription model through Alia (`POST /v1/audio/transcriptions`, ADR 0017
+ * §7). Free on every plan, five minutes per clip at most.
+ *
+ *   idle → requesting-permission → recording → transcribing → idle (text)
+ *                                                           ↘ error { code }
+ *
+ * - `recording` is entered only once the recorder reports it started; the
+ *   level meter is the real recorder's.
+ * - The text arrives after the person stops — `onText` — and never partially:
+ *   a failed transcription inserts nothing and keeps the clip for ONE `retry()`.
+ * - At five minutes the recording stops by itself and is transcribed; the
+ *   remaining time is exposed for the last 30 seconds.
+ *
+ * Nothing is recognized on the device.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { create } from 'zustand';
+import { useOxy } from '@oxy.so/services/ui/client';
+import {
+  dictationFailureCode,
+  MAX_DICTATION_MS,
+  requestTranscription,
+  type DictationClip,
+} from '../lib/dictation';
+import { DictationRecorderError, useDictationRecorder } from '../lib/dictation-recorder';
+import { defaultSpeechLanguage } from '../lib/speech-language';
+import { VOICE_ERROR_MESSAGES, type VoiceErrorCode } from '../lib/speech-messages';
+
+const API_URL = process.env.EXPO_PUBLIC_ALIA_API_URL ?? 'https://api.alia.onl';
+
+/** The remaining time is shown from here on. */
+const COUNTDOWN_FROM_MS = 30_000;
+const CLOCK_MS = 250;
+
+export type DictationState =
+  | 'idle'
+  | 'requesting-permission'
+  | 'recording'
+  | 'transcribing'
+  | 'error';
+
+export interface UseDictationOptions {
+  apiUrl?: string;
+  /** Bearer; defaults to the surrounding Oxy session's. */
+  accessToken?: string;
+  /** Language spoken (BCP-47); defaults to the platform's. The Alia app passes its own. */
+  lang?: string;
+  /** The transcribed text, once — after a stop, the five-minute stop, or a retry. */
+  onText?: (text: string) => void;
+}
+
+interface DictationStoreState {
+  isRecording: boolean;
+  metering: number;
+  setRecording: (isRecording: boolean) => void;
+  setMetering: (metering: number) => void;
+}
+
+/**
+ * Whether the composer is recording, and its level: what the ambient field and
+ * the app's turn actions read without holding the hook.
+ */
+export const useDictationStore = create<DictationStoreState>((set) => ({
+  isRecording: false,
+  metering: 0,
+  setRecording: (isRecording) => set({ isRecording }),
+  setMetering: (metering) => set({ metering }),
+}));
+
+export function useDictation(options: UseDictationOptions = {}) {
+  const { oxyServices } = useOxy();
+  const recorder = useDictationRecorder();
+  const [state, setStateValue] = useState<DictationState>('idle');
+  const [errorCode, setErrorCode] = useState<VoiceErrorCode | null>(null);
+  const [elapsedMs, setElapsedMs] = useState(0);
+  const [canRetry, setCanRetry] = useState(false);
+
+  const stateRef = useRef<DictationState>('idle');
+  const mountedRef = useRef(true);
+  const startedAtRef = useRef(0);
+  const clockRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const capRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const failedClipRef = useRef<DictationClip | null>(null);
+  const abortRef = useRef<AbortController | null>(null);
+  const lastMeteringRef = useRef(0);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  const setState = useCallback((next: DictationState) => {
+    stateRef.current = next;
+    if (mountedRef.current) setStateValue(next);
+  }, []);
+
+  const report = useCallback(
+    (code: VoiceErrorCode | null) => {
+      if (mountedRef.current) setErrorCode(code);
+      if (code !== null) setState('error');
+    },
+    [setState],
+  );
+
+  useEffect(() => {
+    const store = useDictationStore.getState();
+    store.setRecording(state === 'recording');
+    if (state !== 'recording') {
+      lastMeteringRef.current = 0;
+      store.setMetering(0);
+    }
+  }, [state]);
+
+  const clearClock = useCallback((): void => {
+    if (clockRef.current !== null) clearInterval(clockRef.current);
+    if (capRef.current !== null) clearTimeout(capRef.current);
+    clockRef.current = null;
+    capRef.current = null;
+  }, []);
+
+  const transcribe = useCallback(
+    async (clip: DictationClip): Promise<string | null> => {
+      const token = optionsRef.current.accessToken || oxyServices.session.accessToken || '';
+      if (token === '') {
+        failedClipRef.current = null;
+        if (mountedRef.current) setCanRetry(false);
+        report('not-authenticated');
+        return null;
+      }
+      setState('transcribing');
+      const controller = new AbortController();
+      abortRef.current = controller;
+      try {
+        const result = await requestTranscription({
+          apiUrl: optionsRef.current.apiUrl || API_URL,
+          token,
+          clip,
+          language: optionsRef.current.lang ?? defaultSpeechLanguage(),
+          signal: controller.signal,
+        });
+        if (controller.signal.aborted) return null;
+        failedClipRef.current = null;
+        if (mountedRef.current) setCanRetry(false);
+        setState('idle');
+        const text = result.text.trim();
+        if (text === '') return null;
+        optionsRef.current.onText?.(text);
+        return text;
+      } catch (caught: unknown) {
+        if (controller.signal.aborted) return null;
+        const code = dictationFailureCode(caught);
+        // Kept for one retry, unless retrying cannot change the answer.
+        const keep = code !== 'too-long' && code !== 'not-authenticated';
+        failedClipRef.current = keep ? clip : null;
+        if (mountedRef.current) setCanRetry(keep);
+        report(code);
+        return null;
+      } finally {
+        if (abortRef.current === controller) abortRef.current = null;
+      }
+    },
+    [oxyServices, report, setState],
+  );
+
+  const stop = useCallback(async (): Promise<string | null> => {
+    if (stateRef.current !== 'recording') return null;
+    clearClock();
+    setState('transcribing');
+    let clip: DictationClip | null;
+    try {
+      clip = await recorder.stop();
+    } catch {
+      report('mic-unavailable');
+      return null;
+    }
+    if (clip === null) {
+      setState('idle');
+      return null;
+    }
+    if (clip.durationMs > MAX_DICTATION_MS + 1_000) {
+      report('too-long');
+      return null;
+    }
+    return transcribe(clip);
+  }, [clearClock, recorder, report, setState, transcribe]);
+
+  const stopRef = useRef(stop);
+  stopRef.current = stop;
+
+  const start = useCallback(async (): Promise<void> => {
+    if (stateRef.current !== 'idle' && stateRef.current !== 'error') return;
+    if (mountedRef.current) {
+      setErrorCode(null);
+      setCanRetry(false);
+      setElapsedMs(0);
+    }
+    failedClipRef.current = null;
+    setState('requesting-permission');
+    try {
+      await recorder.start((level) => {
+        if (stateRef.current !== 'recording') return;
+        // Quiet should not thrash the store's subscribers.
+        if (Math.abs(level - lastMeteringRef.current) < 0.02) return;
+        lastMeteringRef.current = level;
+        useDictationStore.getState().setMetering(level);
+      });
+    } catch (caught: unknown) {
+      if ((stateRef.current as DictationState) !== 'requesting-permission') return;
+      report(caught instanceof DictationRecorderError ? caught.code : 'mic-unavailable');
+      return;
+    }
+    if ((stateRef.current as DictationState) !== 'requesting-permission') {
+      // Cancelled while the permission was asked.
+      recorder.cancel();
+      return;
+    }
+    startedAtRef.current = Date.now();
+    setState('recording');
+    clockRef.current = setInterval(() => {
+      if (mountedRef.current) setElapsedMs(Date.now() - startedAtRef.current);
+    }, CLOCK_MS);
+    capRef.current = setTimeout(() => {
+      void stopRef.current();
+    }, MAX_DICTATION_MS);
+  }, [recorder, report, setState]);
+
+  const retry = useCallback(async (): Promise<string | null> => {
+    const clip = failedClipRef.current;
+    if (clip === null || stateRef.current === 'recording' || stateRef.current === 'transcribing')
+      return null;
+    // One retry: whatever it answers, the clip is not kept for another.
+    failedClipRef.current = null;
+    if (mountedRef.current) {
+      setCanRetry(false);
+      setErrorCode(null);
+    }
+    const text = await transcribe(clip);
+    failedClipRef.current = null;
+    if (mountedRef.current) setCanRetry(false);
+    return text;
+  }, [transcribe]);
+
+  const cancel = useCallback(() => {
+    clearClock();
+    abortRef.current?.abort();
+    abortRef.current = null;
+    if (stateRef.current === 'recording' || stateRef.current === 'requesting-permission')
+      recorder.cancel();
+    failedClipRef.current = null;
+    if (mountedRef.current) {
+      setErrorCode(null);
+      setCanRetry(false);
+    }
+    setState('idle');
+  }, [clearClock, recorder, setState]);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      clearClock();
+      abortRef.current?.abort();
+      const wasRecording =
+        stateRef.current === 'recording' || stateRef.current === 'requesting-permission';
+      stateRef.current = 'idle';
+      if (wasRecording) recorder.cancel();
+      // The store outlives this hook: a composer unmounted mid-dictation (the
+      // call bar replacing it) must not leave the field reading "recording".
+      useDictationStore.getState().setRecording(false);
+      useDictationStore.getState().setMetering(0);
+    };
+  }, [clearClock, recorder]);
+
+  const remaining = MAX_DICTATION_MS - elapsedMs;
+  return {
+    state,
+    /** What went wrong, in English. */
+    error: errorCode === null ? null : VOICE_ERROR_MESSAGES[errorCode],
+    /** The same, as a code an app can translate. */
+    errorCode,
+    /** Since the recording started. */
+    elapsedMs,
+    /** Left before the five-minute stop, in the last 30 seconds; else `null`. */
+    remainingMs:
+      state === 'recording' && remaining <= COUNTDOWN_FROM_MS ? Math.max(0, remaining) : null,
+    /** A failed transcription kept its clip for one more try. */
+    canRetry,
+    start,
+    stop,
+    retry,
+    cancel,
+    isRecording: state === 'recording',
+    isTranscribing: state === 'transcribing',
+  };
+}

package/src/hooks/useFocusWhenPresented.ts

@@ -0,0 +1,41 @@
+import { useCallback, useRef } from 'react';
+import {
+  runOnJS,
+  type SharedValue,
+  useAnimatedReaction,
+  useSharedValue,
+} from 'react-native-reanimated';
+
+/** Bloom's sheet reports `1` once fully presented; a hair under it absorbs float rounding. */
+const PRESENTED = 0.999;
+
+/**
+ * Calls `focus` once each time a sheet finishes presenting.
+ *
+ * `progress` is the `animatedProgress` of Bloom's `BottomSheet`: `0` closed, `1` fully
+ * presented, every value between while it animates or is dragged. The sheet is armed while it
+ * is closed and fires on reaching `1`, so dragging it part-way and letting go does not take the
+ * focus again; only a new `present()` does. Reduced motion settles immediately, which is the
+ * same crossing. Omitted, nothing happens — the surface is not a sheet.
+ */
+export function useFocusWhenPresented(
+  progress: SharedValue<number> | undefined,
+  focus: () => void,
+): void {
+  const latest = useRef(focus);
+  latest.current = focus;
+  const run = useCallback(() => latest.current(), []);
+  const armed = useSharedValue(true);
+  useAnimatedReaction(
+    () => progress?.value ?? 0,
+    (value) => {
+      if (value <= 0) {
+        armed.value = true;
+      } else if (value >= PRESENTED && armed.value) {
+        armed.value = false;
+        runOnJS(run)();
+      }
+    },
+    [progress, run],
+  );
+}

package/src/hooks/usePendingQuestions.ts

@@ -0,0 +1,19 @@
+import { useCallback, useMemo, useState } from 'react';
+import { type AskedQuestion, pendingQuestions } from '../lib/questions';
+import type { ChatMessage } from '../types';
+
+/**
+ * What Alia asked in her last turn and the person has not answered: asked above the composer,
+ * not in the thread. Any later message, typed or sent from the card, is the answer; `dismiss`
+ * puts the card away until she asks again.
+ */
+export function usePendingQuestions(
+  messages: readonly Pick<ChatMessage, 'id' | 'role' | 'toolInvocations'>[],
+  isStreaming: boolean,
+): { questions: AskedQuestion[]; dismiss: () => void } {
+  const asked = useMemo(() => pendingQuestions(messages, isStreaming), [messages, isStreaming]);
+  const lastMessageId = messages.at(-1)?.id ?? null;
+  const [dismissedOf, setDismissedOf] = useState<string | null>(null);
+  const dismiss = useCallback(() => setDismissedOf(lastMessageId), [lastMessageId]);
+  return { questions: dismissedOf === lastMessageId ? [] : asked, dismiss };
+}

package/src/hooks/useTTS.ts

@@ -136,18 +136,9 @@ export function useTTS(options: UseTTSOptions = {}) {
     reset();
   }, [reset, releasePlayer]);
 
-  /**
-   * Play a stored clip.
-   *
-   * `onUnplayable` is how a caller says "I can make this again". Stored audio
-   * is not permanent — `tts/` objects age out — and a link to something that is
-   * gone fails in the player, not at the request, so the only place to notice
-   * is here. Without a fallback the failure is reported; with one, the caller
-   * gets to rebuild rather than the person getting an error about a button they
-   * pressed twice.
-   */
+  /** Play the clip the route answered with. A clip that will not play is a failure, reported. */
   const playFromUrl = useCallback(
-    (audioUrl: string, _messageId: string, signal: AbortSignal, onUnplayable?: () => void) => {
+    (audioUrl: string, signal: AbortSignal) => {
       releasePlayer();
 
       (async () => {
@@ -199,10 +190,6 @@ export function useTTS(options: UseTTSOptions = {}) {
             if (signal.aborted || playerRef.current !== player) return;
             if (status.error) {
               releasePlayer();
-              if (onUnplayable) {
-                onUnplayable();
-                return;
-              }
               setError(status.error);
               return;
             }
@@ -216,10 +203,6 @@ export function useTTS(options: UseTTSOptions = {}) {
           setPlaybackState('playing');
         } catch {
           if (signal.aborted) return;
-          if (onUnplayable) {
-            onUnplayable();
-            return;
-          }
           setError('Audio playback not available');
         }
       })();
@@ -228,7 +211,7 @@ export function useTTS(options: UseTTSOptions = {}) {
   );
 
   const readAloud = useCallback(
-    async (messageId: string, text: string, conversationId?: string, audioUrl?: string) => {
+    async (messageId: string, text: string, conversationId?: string) => {
       // Read volatile playback state at call time (not via closure) so this
       // callback's identity survives every playback transition. It is passed to
       // memoized message rows — an unstable identity re-renders all of them.
@@ -260,51 +243,29 @@ export function useTTS(options: UseTTSOptions = {}) {
         setPlaybackState('loading');
 
         /**
-         * Ask the server to make it, and play what comes back.
-         *
-         * Hoisted out of the cached branch below so a clip that has aged out of
-         * storage can fall back to it. `playFromUrl` is called WITHOUT a fallback
-         * here: a freshly made clip that will not play is a real failure, and
-         * retrying it would be a loop.
+         * Always ask the route: it answers a clip this person already had made —
+         * same text, voice, speed and model — from storage, without
+         * synthesizing it again, and makes it only when there is none. So a
+         * second press, here or after a reload, costs nothing and plays at once.
+         * `conversationId` (with the message id) files the clip under that
+         * conversation, so deleting the conversation deletes it.
          */
-        const synthesize = async () => {
-          const token = getToken();
-          if (!token) {
-            throw new Error('Not authenticated');
-          }
-
-          const audioUrl = await requestSpeechClip({
-            apiUrl,
-            token,
-            model: voiceModel,
-            input: text,
-            voice: getTTSVoice(),
-            speed: getTTSSpeed(),
-            conversationId,
-            messageId,
-            signal: controller.signal,
-          });
-          playFromUrl(audioUrl, messageId, controller.signal);
-        };
-
-        /**
-         * A stored clip plays straight away, and is remade if it has gone.
-         *
-         * The row keeps its key long after a `tts/` object ages out of storage,
-         * so the link is signed, valid, and points at nothing — a failure only
-         * the player ever sees. Remaking it is cheaper than keeping every clip
-         * forever, and the person notices nothing.
-         */
-        if (audioUrl) {
-          playFromUrl(audioUrl, messageId, controller.signal, () => {
-            void synthesize().catch((e: unknown) => {
-              if (!controller.signal.aborted) setError(errorMessage(e, 'Failed to read aloud'));
-            });
-          });
-          return;
+        const token = getToken();
+        if (!token) {
+          throw new Error('Not authenticated');
         }
-
-        await synthesize();
+        const audioUrl = await requestSpeechClip({
+          apiUrl,
+          token,
+          model: voiceModel,
+          input: text,
+          voice: getTTSVoice(),
+          speed: getTTSSpeed(),
+          conversationId,
+          messageId,
+          signal: controller.signal,
+        });
+        playFromUrl(audioUrl, controller.signal);
       } catch (e: unknown) {
         if (controller.signal.aborted) return;
         console.error('[TTS] Error:', e);