@alia.onl/sdk 13.2.0 → 15.2.1

package/src/index.ts

@@ -6,6 +6,7 @@
 export type { AliaChatAgent, AliaChatState } from './components/AliaChatContent';
 export { AliaChatSheet } from './components/AliaChatSheet';
 export type { AliaChatSheetProps, AliaChatSheetRef } from './components/AliaChatSheet';
+export type { AliaTurn } from './components/AliaChatContent';
 export { AliaChatScreen } from './components/AliaChatScreen';
 export type { AliaChatScreenProps } from './components/AliaChatScreen';
 
@@ -19,6 +20,9 @@ export type { AmbientFieldProps } from './components/AmbientField';
 export { ALIA_AVATAR, AliaAvatar } from './components/AliaAvatar';
 export { DEFAULT_AGENT_CHARACTER, readAgentCharacter } from './lib/agent-character';
 export type { AliaAvatarProps, AliaAvatarState } from './components/AliaAvatar';
+export { AliaAvatarIcon } from './components/AliaAvatarIcon';
+export { useAliaActivity } from './hooks/useAliaActivity';
+export type { UseAliaActivityOptions } from './hooks/useAliaActivity';
 export { IdentityMark } from './components/IdentityMark';
 export type { IdentityMarkProps, IdentityMarkState } from './components/IdentityMark';
 export { AliaMarkdown } from './components/Markdown';
@@ -51,15 +55,17 @@ export type { UseAliaChatOptions, UseAliaChatReturn } from './hooks/useAliaChat'
 export { AliaChatStreamError } from './lib/chat-stream';
 export type { AliaChatFailure } from './lib/chat-stream';
 
-// ── Text-to-speech / speech-to-text (no livekit) ──
+// ── Read aloud and dictation (no call, no audio engine) ──
 export { useTTS } from './hooks/useTTS';
 export type { UseTTSOptions } from './hooks/useTTS';
-export { useSpeechToText, useSTTStore } from './hooks/useSpeechToText';
+export { useDictation, useDictationStore } from './hooks/useDictation';
+export type { UseDictationOptions, DictationState } from './hooks/useDictation';
+export { DictationError, requestTranscription } from './lib/dictation';
+export type { DictationErrorCode, TranscriptionResult } from './lib/dictation';
 export { VOICE_ERROR_MESSAGES } from './lib/speech-messages';
 export type { VoiceErrorCode } from './lib/speech-messages';
 export { SpeechClipError } from './lib/speech-synthesis';
 export type { SpeechClipErrorCode } from './lib/speech-synthesis';
-export type { UseSTTOptions } from './hooks/useSpeechToText';
 
 // ── Model catalogue (GET /catalogue) ──
 // Exported so a consumer building its own picker reads the real models the

package/src/lib/activity-socket.ts

@@ -0,0 +1,102 @@
+import { io, type Socket } from 'socket.io-client';
+import type { AliaAvatarState } from '../components/AliaAvatar';
+import { useAliaActivityStore } from './activity-store';
+
+/** A run that goes quiet this long is over: a crashed run never says `idle`. */
+export const ACTIVITY_QUIET_MS = 90_000;
+/** Between tries after the server refuses a handshake (socket.io does not retry those itself). */
+const RETRY_MS = 5_000;
+
+const STATES: ReadonlySet<string> = new Set<AliaAvatarState>([
+  'idle',
+  'thinking',
+  'working',
+  'writing',
+]);
+
+interface Connection {
+  socket: Socket;
+  refs: number;
+  quiet: Map<string, ReturnType<typeof setTimeout>>;
+  retry: ReturnType<typeof setTimeout> | null;
+}
+
+/** One connection per API origin, however many buttons ask for it. */
+const connections = new Map<string, Connection>();
+
+function open(url: string, getToken: () => string | null): Connection {
+  const socket = io(url, {
+    transports: ['websocket'],
+    // Read on every (re)connect, so a rotated access token is the one that goes out.
+    auth: (cb) => cb({ token: getToken() }),
+    reconnection: true,
+    reconnectionAttempts: Infinity,
+    reconnectionDelay: 1000,
+    reconnectionDelayMax: 10_000,
+  });
+  const connection: Connection = { socket, refs: 0, quiet: new Map(), retry: null };
+  const store = useAliaActivityStore.getState;
+
+  const reset = (): void => {
+    for (const timer of connection.quiet.values()) clearTimeout(timer);
+    connection.quiet.clear();
+    store().clearRemote();
+  };
+
+  socket.on('connect', () => socket.emit('subscribe-alia-activity'));
+  // What happened while disconnected is unknown; a stale "working" is worse than idle.
+  socket.on('disconnect', reset);
+  socket.on('connect_error', () => {
+    // A refused handshake (no token yet, an expired one) ends the socket's own retrying.
+    if (socket.active || connection.retry !== null) return;
+    connection.retry = setTimeout(() => {
+      connection.retry = null;
+      socket.connect();
+    }, RETRY_MS);
+  });
+  socket.on('alia:activity', (event: unknown) => {
+    if (typeof event !== 'object' || event === null) return;
+    const { state, sessionId } = event as { state?: unknown; sessionId?: unknown };
+    if (typeof sessionId !== 'string' || typeof state !== 'string' || !STATES.has(state)) return;
+    const pending = connection.quiet.get(sessionId);
+    if (pending !== undefined) clearTimeout(pending);
+    connection.quiet.delete(sessionId);
+    store().setRemote(sessionId, state as AliaAvatarState);
+    if (state !== 'idle') {
+      connection.quiet.set(
+        sessionId,
+        setTimeout(() => {
+          connection.quiet.delete(sessionId);
+          store().setRemote(sessionId, 'idle');
+        }, ACTIVITY_QUIET_MS),
+      );
+    }
+  });
+  return connection;
+}
+
+/**
+ * Listen for Alia's activity on the person's behalf. Every caller shares the one connection for
+ * `url`; the last to release closes it. Returns the release.
+ */
+export function acquireActivitySocket(url: string, getToken: () => string | null): () => void {
+  let held = connections.get(url);
+  if (!held) {
+    held = open(url, getToken);
+    connections.set(url, held);
+  }
+  const connection = held;
+  connection.refs++;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    if (--connection.refs > 0) return;
+    connections.delete(url);
+    if (connection.retry !== null) clearTimeout(connection.retry);
+    connection.socket.removeAllListeners();
+    connection.socket.disconnect();
+    for (const timer of connection.quiet.values()) clearTimeout(timer);
+    useAliaActivityStore.getState().clearRemote();
+  };
+}

package/src/lib/activity-store.ts

@@ -0,0 +1,53 @@
+import { create } from 'zustand';
+import type { AliaAvatarState } from '../components/AliaAvatar';
+
+type Sources = Readonly<Record<string, AliaAvatarState>>;
+
+/**
+ * What Alia is doing, from every place that can know. Two sources feed it and neither owns it:
+ *
+ * - `local`: the turns running in THIS app, one entry per `useAliaChat` instance (the sheet);
+ * - `remote`: runs the server reports for the person, one entry per agent session, so a button
+ *   reacts to work that is not in any open chat.
+ *
+ * An idle source holds no entry, so neither map grows with use.
+ */
+interface AliaActivityStore {
+  local: Sources;
+  remote: Sources;
+  setLocal(source: string, state: AliaAvatarState): void;
+  setRemote(session: string, state: AliaAvatarState): void;
+  clearRemote(): void;
+}
+
+function put(map: Sources, key: string, state: AliaAvatarState): Sources {
+  if (state === 'idle') {
+    if (!(key in map)) return map;
+    const { [key]: _gone, ...rest } = map;
+    return rest;
+  }
+  return map[key] === state ? map : { ...map, [key]: state };
+}
+
+export const useAliaActivityStore = create<AliaActivityStore>((set) => ({
+  local: {},
+  remote: {},
+  setLocal: (source, state) => set((s) => ({ local: put(s.local, source, state) })),
+  setRemote: (session, state) => set((s) => ({ remote: put(s.remote, session, state) })),
+  clearRemote: () => set((s) => (Object.keys(s.remote).length === 0 ? s : { remote: {} })),
+}));
+
+/** The most telling thing any source is doing: a tool call outranks thinking, thinking outranks writing. */
+const RANK: Record<AliaAvatarState, number> = { idle: 0, writing: 1, thinking: 2, working: 3 };
+
+export function busiest(...maps: ReadonlyArray<Sources>): AliaAvatarState {
+  let top: AliaAvatarState = 'idle';
+  for (const map of maps) {
+    for (const state of Object.values(map)) if (RANK[state] > RANK[top]) top = state;
+  }
+  return top;
+}
+
+/** A primitive, so a subscriber re-renders when the state changes and not when a session does. */
+export const selectAliaActivity = (s: AliaActivityStore): AliaAvatarState =>
+  busiest(s.local, s.remote);

package/src/lib/api-url.ts

@@ -0,0 +1,2 @@
+/** Where Alia's API is: `EXPO_PUBLIC_ALIA_API_URL`, then `https://api.alia.onl`. */
+export const ALIA_API_URL = process.env.EXPO_PUBLIC_ALIA_API_URL ?? 'https://api.alia.onl';

package/src/lib/audio-level.ts

@@ -3,8 +3,8 @@
  * time constants, for every source that drives it.
  *
  * Dictation got here first and is the reference: the microphone's level is
- * taken as dBFS (on web, from an analyser beside the recognizer —
- * `speech-recognition.ts`), normalised against a -60 floor, and `useAmbientWave`
+ * taken as dBFS (on web, from an analyser beside the recorder —
+ * `dictation-recorder.ts`), normalised against a -60 floor, and `useAmbientWave`
  * smooths it with a fast attack and a slow decay before it reaches
  * `AmbientField`. That is the behaviour people like, so it is the behaviour
  * everything else adopts rather than re-invents — including "read aloud", which

package/src/lib/dictation-recorder-types.ts

@@ -0,0 +1,37 @@
+import type { DictationClip } from './dictation';
+
+/** Why the microphone could not record. */
+export type DictationRecorderErrorCode = 'mic-denied' | 'mic-unavailable';
+
+export class DictationRecorderError extends Error {
+  readonly code: DictationRecorderErrorCode;
+
+  constructor(code: DictationRecorderErrorCode, message?: string) {
+    super(message ?? code);
+    this.name = 'DictationRecorderError';
+    this.code = code;
+  }
+}
+
+/**
+ * A clip recorder for the composer's microphone:
+ *
+ * - web (`dictation-recorder.ts`): `MediaRecorder`, `audio/webm;codecs=opus`
+ *   or `audio/mp4` (Safari), level from an `AnalyserNode` on the same stream;
+ * - iOS / Android (`dictation-recorder.native.ts`): the `expo-audio`
+ *   recorder, `RecordingPresets.HIGH_QUALITY` (m4a/AAC → `audio/mp4`) with
+ *   metering on.
+ *
+ * Levels are the real recorder's, 0..1 on the dictation meter's dBFS scale.
+ */
+export interface DictationRecorder {
+  /**
+   * Ask for the microphone and start recording; resolves once the recorder
+   * says it started. Rejects with a {@link DictationRecorderError}.
+   */
+  start(onLevel: (level: number) => void): Promise<void>;
+  /** Stop and hand over the clip, or `null` when nothing was recorded. */
+  stop(): Promise<DictationClip | null>;
+  /** Stop and throw the clip away. */
+  cancel(): void;
+}

package/src/lib/dictation-recorder.native.ts

@@ -0,0 +1,90 @@
+/**
+ * Dictation's iOS / Android recorder: the `expo-audio` recorder (already a
+ * peer of this SDK), `RecordingPresets.HIGH_QUALITY` in mono with metering on.
+ * The clip is m4a/AAC, sent as `audio/mp4`. No new native module: the call's
+ * engine (`react-native-audio-api`) is not needed to record a clip.
+ */
+
+import { useMemo } from 'react';
+import {
+  RecordingPresets,
+  requestRecordingPermissionsAsync,
+  setAudioModeAsync,
+  useAudioRecorder,
+} from 'expo-audio';
+import { levelFromDbfs } from './audio-level';
+import type { DictationClip } from './dictation';
+import { DictationRecorderError, type DictationRecorder } from './dictation-recorder-types';
+
+export * from './dictation-recorder-types';
+
+const LEVEL_POLL_MS = 100;
+
+const OPTIONS = { ...RecordingPresets.HIGH_QUALITY, numberOfChannels: 1, isMeteringEnabled: true };
+
+export function useDictationRecorder(): DictationRecorder {
+  const recorder = useAudioRecorder(OPTIONS);
+
+  return useMemo(() => {
+    let levelTimer: ReturnType<typeof setInterval> | null = null;
+    let lastDurationMs = 0;
+    let recording = false;
+
+    const stopLevels = (): void => {
+      if (levelTimer !== null) clearInterval(levelTimer);
+      levelTimer = null;
+    };
+    const releaseSession = (): void => {
+      void setAudioModeAsync({ allowsRecording: false }).catch(() => undefined);
+    };
+
+    return {
+      async start(onLevel) {
+        const permission = await requestRecordingPermissionsAsync().catch(() => null);
+        if (!permission?.granted) throw new DictationRecorderError('mic-denied');
+        try {
+          await setAudioModeAsync({ allowsRecording: true, playsInSilentMode: true });
+          await recorder.prepareToRecordAsync();
+          recorder.record();
+        } catch {
+          releaseSession();
+          throw new DictationRecorderError('mic-unavailable');
+        }
+        recording = true;
+        lastDurationMs = 0;
+        levelTimer = setInterval(() => {
+          const status = recorder.getStatus();
+          lastDurationMs = status.durationMillis;
+          onLevel(typeof status.metering === 'number' ? levelFromDbfs(status.metering) : 0);
+        }, LEVEL_POLL_MS);
+      },
+
+      async stop(): Promise<DictationClip | null> {
+        if (!recording) return null;
+        recording = false;
+        stopLevels();
+        const durationMs = recorder.getStatus().durationMillis || lastDurationMs;
+        try {
+          await recorder.stop();
+        } finally {
+          releaseSession();
+        }
+        const uri = recorder.uri;
+        if (!uri) return null;
+        return {
+          file: { uri, name: 'dictation.m4a', type: 'audio/mp4' },
+          mediaType: 'audio/mp4',
+          durationMs,
+        };
+      },
+
+      cancel(): void {
+        if (!recording) return;
+        recording = false;
+        stopLevels();
+        void recorder.stop().catch(() => undefined);
+        releaseSession();
+      },
+    };
+  }, [recorder]);
+}

package/src/lib/dictation-recorder.ts

@@ -0,0 +1,131 @@
+/**
+ * Dictation's web recorder: `MediaRecorder` over `getUserMedia`, with an
+ * `AnalyserNode` on the same stream for the level meter. See
+ * `dictation-recorder-types.ts`.
+ */
+
+import { useMemo } from 'react';
+import { levelFromFrames } from './audio-level';
+import { normalizeAudioMediaType, type DictationClip } from './dictation';
+import { DictationRecorderError, type DictationRecorder } from './dictation-recorder-types';
+
+export * from './dictation-recorder-types';
+
+const LEVEL_POLL_MS = 100;
+
+/** Opus in WebM where the browser records it (Chromium, Firefox), MP4/AAC on Safari. */
+function recordingMimeType(): string | null {
+  const Recorder = globalThis.MediaRecorder;
+  if (!Recorder) return null;
+  for (const type of ['audio/webm;codecs=opus', 'audio/webm', 'audio/mp4']) {
+    if (Recorder.isTypeSupported?.(type)) return type;
+  }
+  return null;
+}
+
+export function createWebDictationRecorder(): DictationRecorder {
+  let stream: MediaStream | null = null;
+  let recorder: MediaRecorder | null = null;
+  let context: AudioContext | null = null;
+  let levelTimer: ReturnType<typeof setInterval> | null = null;
+  let chunks: Blob[] = [];
+  let startedAt = 0;
+
+  const release = (): void => {
+    if (levelTimer !== null) clearInterval(levelTimer);
+    levelTimer = null;
+    for (const track of stream?.getTracks() ?? []) track.stop();
+    void context?.close().catch(() => undefined);
+    stream = null;
+    context = null;
+  };
+
+  return {
+    async start(onLevel) {
+      const mimeType = recordingMimeType();
+      const media = globalThis.navigator?.mediaDevices;
+      if (mimeType === null || !media?.getUserMedia)
+        throw new DictationRecorderError('mic-unavailable');
+      try {
+        stream = await media.getUserMedia({
+          audio: { noiseSuppression: true, echoCancellation: true, autoGainControl: true },
+        });
+      } catch (caught: unknown) {
+        const name = (caught as { name?: unknown } | null)?.name;
+        throw new DictationRecorderError(
+          name === 'NotAllowedError' || name === 'SecurityError' ? 'mic-denied' : 'mic-unavailable',
+        );
+      }
+
+      const AudioContextCtor = globalThis.AudioContext;
+      if (AudioContextCtor) {
+        context = new AudioContextCtor();
+        const analyser = context.createAnalyser();
+        analyser.fftSize = 1024;
+        context.createMediaStreamSource(stream).connect(analyser);
+        const frames = new Float32Array(analyser.fftSize);
+        levelTimer = setInterval(() => {
+          analyser.getFloatTimeDomainData(frames);
+          onLevel(levelFromFrames(Array.from(frames)));
+        }, LEVEL_POLL_MS);
+      }
+
+      chunks = [];
+      const active = new MediaRecorder(stream, { mimeType });
+      recorder = active;
+      active.ondataavailable = (event) => {
+        if (event.data.size > 0) chunks.push(event.data);
+      };
+      await new Promise<void>((resolve, reject) => {
+        active.onstart = () => {
+          startedAt = Date.now();
+          resolve();
+        };
+        active.onerror = () => reject(new DictationRecorderError('mic-unavailable'));
+        try {
+          active.start();
+        } catch {
+          reject(new DictationRecorderError('mic-unavailable'));
+        }
+      }).catch((error: unknown) => {
+        release();
+        throw error;
+      });
+    },
+
+    stop(): Promise<DictationClip | null> {
+      const active = recorder;
+      recorder = null;
+      if (active === null || active.state === 'inactive') {
+        release();
+        return Promise.resolve(null);
+      }
+      return new Promise((resolve) => {
+        active.onstop = () => {
+          const durationMs = Date.now() - startedAt;
+          const mediaType = normalizeAudioMediaType(active.mimeType || 'audio/webm');
+          const blob = new Blob(chunks, { type: mediaType });
+          chunks = [];
+          release();
+          resolve(blob.size === 0 ? null : { file: blob, mediaType, durationMs });
+        };
+        active.stop();
+      });
+    },
+
+    cancel(): void {
+      const active = recorder;
+      recorder = null;
+      chunks = [];
+      if (active !== null && active.state !== 'inactive') {
+        active.onstop = null;
+        active.stop();
+      }
+      release();
+    },
+  };
+}
+
+export function useDictationRecorder(): DictationRecorder {
+  return useMemo(() => createWebDictationRecorder(), []);
+}

package/src/lib/dictation.ts

@@ -0,0 +1,208 @@
+/**
+ * Dictation's network half: a recorded clip to `POST /v1/audio/transcriptions`
+ * (ADR 0017 §7), which Alia answers with a Kaana transcription model computed
+ * from the catalogue. Free on every plan; at most five minutes per clip.
+ *
+ * Batch, not streaming: the text arrives once the person stops. Nothing is
+ * recognized on the device.
+ */
+
+import type { VoiceErrorCode } from './speech-messages';
+
+/** The longest clip one dictation may be. */
+export const MAX_DICTATION_MS = 5 * 60_000;
+
+/** A clip as a recorder hands it over: a web `Blob`, or a React Native file. */
+export interface DictationClip {
+  readonly file: Blob | { readonly uri: string; readonly name: string; readonly type: string };
+  /** Without parameters: `audio/webm`, `audio/mp4`, … */
+  readonly mediaType: string;
+  /** Measured by the recorder. */
+  readonly durationMs: number;
+}
+
+export interface TranscriptionResult {
+  readonly text: string;
+  readonly language?: string;
+  readonly durationMs?: number;
+  /** The model that transcribed it (its name may be shown). */
+  readonly model?: string;
+}
+
+/** What the route answers a failure with, plus the two this side knows on its own. */
+export type DictationErrorCode =
+  | 'TRANSCRIPTION_UNAVAILABLE'
+  | 'TRANSCRIPTION_LIMITED'
+  | 'TRANSCRIPTION_REJECTED'
+  | 'TRANSCRIPTION_FAILED'
+  | 'CLIP_TOO_LONG'
+  | 'INVALID_REQUEST'
+  | 'NOT_AUTHENTICATED'
+  | 'CREDENTIAL_NOT_SUPPORTED';
+
+const SERVER_CODES: ReadonlySet<string> = new Set<DictationErrorCode>([
+  'TRANSCRIPTION_UNAVAILABLE',
+  'TRANSCRIPTION_LIMITED',
+  'TRANSCRIPTION_REJECTED',
+  'TRANSCRIPTION_FAILED',
+  'CLIP_TOO_LONG',
+  'INVALID_REQUEST',
+  'NOT_AUTHENTICATED',
+  'CREDENTIAL_NOT_SUPPORTED',
+]);
+
+export class DictationError extends Error {
+  /** `null` when no request was answered (network) or the code is unknown. */
+  readonly code: DictationErrorCode | null;
+  readonly status: number | null;
+  readonly retryable: boolean;
+
+  constructor(
+    message: string,
+    details: { code: DictationErrorCode | null; status: number | null; retryable?: boolean },
+  ) {
+    super(message);
+    this.name = 'DictationError';
+    this.code = details.code;
+    this.status = details.status;
+    this.retryable = details.retryable ?? false;
+  }
+}
+
+/** The `VoiceErrorCode` an app says a failed transcription with. */
+export function dictationFailureCode(error: unknown): VoiceErrorCode {
+  if (!(error instanceof DictationError)) return 'transcription-failed';
+  switch (error.code) {
+    case 'TRANSCRIPTION_UNAVAILABLE':
+      return 'transcription-unavailable';
+    case 'TRANSCRIPTION_LIMITED':
+      return 'transcription-limited';
+    case 'TRANSCRIPTION_REJECTED':
+    case 'INVALID_REQUEST':
+      return 'transcription-rejected';
+    case 'CLIP_TOO_LONG':
+      return 'too-long';
+    case 'NOT_AUTHENTICATED':
+      return 'not-authenticated';
+    case 'CREDENTIAL_NOT_SUPPORTED':
+      return 'credential-not-supported';
+    case 'TRANSCRIPTION_FAILED':
+    case null:
+      return 'transcription-failed';
+  }
+}
+
+/** `audio/webm;codecs=opus` → `audio/webm`; iOS's m4a names → `audio/mp4`. */
+export function normalizeAudioMediaType(type: string): string {
+  const bare = type.split(';')[0]!.trim().toLowerCase();
+  if (bare === 'audio/x-m4a' || bare === 'audio/m4a' || bare === 'audio/aac-mp4')
+    return 'audio/mp4';
+  return bare;
+}
+
+function fileNameFor(mediaType: string): string {
+  switch (mediaType) {
+    case 'audio/webm':
+      return 'dictation.webm';
+    case 'audio/ogg':
+      return 'dictation.ogg';
+    case 'audio/mpeg':
+      return 'dictation.mp3';
+    case 'audio/wav':
+      return 'dictation.wav';
+    default:
+      return 'dictation.m4a';
+  }
+}
+
+export interface TranscriptionRequest {
+  readonly apiUrl: string;
+  readonly token: string;
+  readonly clip: DictationClip;
+  /** BCP-47. */
+  readonly language: string;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Transcribe one clip.
+ *
+ * @throws {DictationError} for every refusal; an abort is thrown as `fetch` threw it.
+ */
+export async function requestTranscription(
+  request: TranscriptionRequest,
+): Promise<TranscriptionResult> {
+  if (request.token === '')
+    throw new DictationError('Not authenticated', { code: 'NOT_AUTHENTICATED', status: null });
+  const mediaType = normalizeAudioMediaType(request.clip.mediaType);
+  const form = new FormData();
+  const { file } = request.clip;
+  if (typeof Blob !== 'undefined' && file instanceof Blob) {
+    form.append('file', file, fileNameFor(mediaType));
+  } else {
+    // React Native's FormData takes a file by `{ uri, name, type }`.
+    form.append('file', file as unknown as Blob);
+  }
+  form.append('language', request.language);
+  form.append('durationMs', String(Math.max(0, Math.round(request.clip.durationMs))));
+
+  let response: Response;
+  try {
+    response = await fetch(`${request.apiUrl}/v1/audio/transcriptions`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${request.token}` },
+      body: form,
+      ...(request.signal ? { signal: request.signal } : {}),
+    });
+  } catch (caught: unknown) {
+    if ((caught as { name?: unknown } | null)?.name === 'AbortError') throw caught;
+    throw new DictationError('The transcription request did not reach Alia', {
+      code: null,
+      status: null,
+      retryable: true,
+    });
+  }
+
+  const body: unknown = await response.json().catch(() => null);
+  if (!response.ok) {
+    const envelope =
+      body !== null && typeof body === 'object' ? (body as { error?: unknown }).error : undefined;
+    const error =
+      envelope !== null && typeof envelope === 'object'
+        ? (envelope as { code?: unknown; message?: unknown; retryable?: unknown })
+        : {};
+    const named =
+      typeof error.code === 'string' && SERVER_CODES.has(error.code)
+        ? (error.code as DictationErrorCode)
+        : null;
+    throw new DictationError(
+      typeof error.message === 'string' && error.message !== ''
+        ? error.message
+        : 'Transcription failed',
+      {
+        code:
+          named ??
+          (response.status === 401
+            ? 'NOT_AUTHENTICATED'
+            : response.status === 413
+              ? 'CLIP_TOO_LONG'
+              : null),
+        status: response.status,
+        retryable: error.retryable === true,
+      },
+    );
+  }
+  const result = body !== null && typeof body === 'object' ? (body as Record<string, unknown>) : {};
+  if (typeof result.text !== 'string') {
+    throw new DictationError('Alia answered no transcription', {
+      code: 'TRANSCRIPTION_FAILED',
+      status: response.status,
+    });
+  }
+  return {
+    text: result.text,
+    ...(typeof result.language === 'string' ? { language: result.language } : {}),
+    ...(typeof result.durationMs === 'number' ? { durationMs: result.durationMs } : {}),
+    ...(typeof result.model === 'string' ? { model: result.model } : {}),
+  };
+}