@athenaintel/react 0.23.2 → 0.24.0

package/dist/dictation/recorded-dictation-engine.d.ts

@@ -0,0 +1,66 @@
+import { type DictationEngine } from './dictation-engine';
+export interface DictationTranscribeContext {
+    /** BCP-47 tag the session was started with (host `lang` or the document's). */
+    lang: string;
+    /** Fires when the user cancels or the composer gives up waiting. */
+    signal: AbortSignal;
+}
+/**
+ * Turn a finished recording into text. Receives the whole clip once the user
+ * stops; resolves with the transcript (empty when nothing was said). Should
+ * honour `signal` so a cancelled dictation does not keep uploading.
+ */
+export type DictationTranscriber = (clip: Blob, context: DictationTranscribeContext) => Promise<string>;
+export interface RecordedDictationEngineOptions {
+    transcribe: DictationTranscriber;
+    /**
+     * Preferred `MediaRecorder` container, tried in order until the browser
+     * accepts one. Defaults to Opus in WebM (Chrome, Firefox, Edge) then MP4
+     * (Safari); the browser's own default is the last resort.
+     */
+    mimeTypes?: readonly string[];
+    /**
+     * Upper bound on the transcription round trip; the in-flight request is
+     * aborted when it elapses. Defaults to 90s, above agora's 60s Deepgram
+     * budget plus upload time.
+     */
+    flushTimeoutMs?: number;
+    /**
+     * Longest recording the engine accepts before it stops on its own and
+     * transcribes what it has, exactly as if Stop had been pressed. Bounds a
+     * mic left open by mistake: every recorded minute is a minute billed by the
+     * recognizer, and agora refuses clips over its size cap. Defaults to
+     * 5 minutes; pass `Infinity` to disable.
+     */
+    maxDurationMs?: number;
+}
+export declare const DEFAULT_MAX_RECORDING_MS: number;
+interface MediaRecorderLike extends EventTarget {
+    readonly state: 'inactive' | 'recording' | 'paused';
+    readonly mimeType: string;
+    start: (timeslice?: number) => void;
+    stop: () => void;
+    ondataavailable: ((event: {
+        data: Blob;
+    }) => void) | null;
+    onstop: (() => void) | null;
+    onerror: ((event: Event) => void) | null;
+}
+interface MediaRecorderCtor {
+    new (stream: MediaStream, options?: {
+        mimeType?: string;
+    }): MediaRecorderLike;
+    isTypeSupported?: (type: string) => boolean;
+}
+/** First container the recorder accepts, or undefined for the browser default. */
+export declare function pickRecorderMimeType(Ctor: Pick<MediaRecorderCtor, 'isTypeSupported'>, candidates: readonly string[]): string | undefined;
+/**
+ * Record-then-transcribe: capture the microphone with `MediaRecorder` while
+ * the user talks, then hand the finished clip to `transcribe` on stop. No
+ * interim words are shown; the composer shows a "transcribing" state until
+ * the text lands. Works in every browser with `MediaRecorder`, so the mic is
+ * available where Web Speech is not (Firefox) and the quality is whatever the
+ * server-side recognizer provides.
+ */
+export declare function createRecordedDictationEngine(options: RecordedDictationEngineOptions): DictationEngine;
+export {};

package/dist/dictation/recorded-dictation-engine.js

@@ -0,0 +1,153 @@
+import { DICTATION_ENGINE_ERROR_KINDS } from "./dictation-engine.js";
+const DEFAULT_MIME_TYPES = ["audio/webm;codecs=opus", "audio/webm", "audio/mp4", "audio/ogg;codecs=opus"];
+const DEFAULT_FLUSH_TIMEOUT_MS = 9e4;
+const DEFAULT_MAX_RECORDING_MS = 5 * 6e4;
+function resolveMediaRecorderCtor() {
+  if (typeof window === "undefined") return null;
+  return window.MediaRecorder ?? null;
+}
+function pickRecorderMimeType(Ctor, candidates) {
+  if (!Ctor.isTypeSupported) return void 0;
+  return candidates.find((type) => {
+    var _a;
+    return (_a = Ctor.isTypeSupported) == null ? void 0 : _a.call(Ctor, type);
+  });
+}
+function transcriptionError(error) {
+  return {
+    kind: DICTATION_ENGINE_ERROR_KINDS.connection,
+    message: error instanceof Error && error.message ? error.message : "Transcription failed. Try again."
+  };
+}
+function createRecordedDictationEngine(options) {
+  const {
+    transcribe,
+    mimeTypes = DEFAULT_MIME_TYPES,
+    flushTimeoutMs = DEFAULT_FLUSH_TIMEOUT_MS,
+    maxDurationMs = DEFAULT_MAX_RECORDING_MS
+  } = options;
+  return {
+    id: "recorded-upload",
+    flushTimeoutMs,
+    stoppingLabel: "Transcribing…",
+    isSupported: () => {
+      var _a;
+      return resolveMediaRecorderCtor() !== null && typeof navigator !== "undefined" && typeof ((_a = navigator.mediaDevices) == null ? void 0 : _a.getUserMedia) === "function";
+    },
+    start: ({ stream, lang, callbacks }) => {
+      const Ctor = resolveMediaRecorderCtor();
+      const noop = { stop: () => void 0, abort: () => void 0 };
+      if (!Ctor || !stream) {
+        callbacks.onError({
+          kind: !Ctor ? DICTATION_ENGINE_ERROR_KINDS.unsupported : DICTATION_ENGINE_ERROR_KINDS.permission,
+          message: !Ctor ? "This browser cannot record audio." : "No microphone stream was available."
+        });
+        callbacks.onEnd();
+        return noop;
+      }
+      const mimeType = pickRecorderMimeType(Ctor, mimeTypes);
+      let recorder;
+      try {
+        recorder = new Ctor(stream, mimeType ? { mimeType } : void 0);
+      } catch (error) {
+        callbacks.onError({
+          kind: DICTATION_ENGINE_ERROR_KINDS.unknown,
+          message: error instanceof Error ? error.message : "Recording could not start."
+        });
+        callbacks.onEnd();
+        return noop;
+      }
+      const chunks = [];
+      const upload = new AbortController();
+      let ended = false;
+      let aborted = false;
+      let limitTimer;
+      const clearLimit = () => {
+        if (limitTimer === void 0) return;
+        clearTimeout(limitTimer);
+        limitTimer = void 0;
+      };
+      const end = () => {
+        if (ended) return;
+        ended = true;
+        clearLimit();
+        recorder.ondataavailable = null;
+        recorder.onstop = null;
+        recorder.onerror = null;
+        callbacks.onEnd();
+      };
+      const stopRecorder = () => {
+        if (recorder.state === "inactive") return false;
+        try {
+          recorder.stop();
+          return true;
+        } catch {
+          return false;
+        }
+      };
+      recorder.ondataavailable = (event) => {
+        if (event.data && event.data.size > 0) chunks.push(event.data);
+      };
+      recorder.onerror = () => {
+        callbacks.onError({
+          kind: DICTATION_ENGINE_ERROR_KINDS.unknown,
+          message: "Recording stopped unexpectedly."
+        });
+        end();
+      };
+      recorder.onstop = () => {
+        if (aborted || ended) {
+          end();
+          return;
+        }
+        const clip = new Blob(chunks, { type: recorder.mimeType || mimeType || "audio/webm" });
+        if (clip.size === 0) {
+          end();
+          return;
+        }
+        void transcribe(clip, { lang, signal: upload.signal }).then((text) => {
+          if (ended) return;
+          const trimmed = text.trim();
+          if (trimmed) callbacks.onTranscript({ final: trimmed, interim: "" });
+        }).catch((error) => {
+          if (ended) return;
+          callbacks.onError(transcriptionError(error));
+        }).finally(end);
+      };
+      try {
+        recorder.start();
+      } catch (error) {
+        callbacks.onError({
+          kind: DICTATION_ENGINE_ERROR_KINDS.unknown,
+          message: error instanceof Error ? error.message : "Recording could not start."
+        });
+        end();
+        return noop;
+      }
+      if (Number.isFinite(maxDurationMs) && maxDurationMs > 0) {
+        limitTimer = setTimeout(() => {
+          limitTimer = void 0;
+          if (!ended) stopRecorder();
+        }, maxDurationMs);
+      }
+      return {
+        stop: () => {
+          clearLimit();
+          if (!stopRecorder()) end();
+        },
+        abort: () => {
+          aborted = true;
+          upload.abort();
+          stopRecorder();
+          end();
+        }
+      };
+    }
+  };
+}
+export {
+  DEFAULT_MAX_RECORDING_MS,
+  createRecordedDictationEngine,
+  pickRecorderMimeType
+};
+//# sourceMappingURL=recorded-dictation-engine.js.map

package/dist/dictation/recorded-dictation-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorded-dictation-engine.js","sources":["../../src/dictation/recorded-dictation-engine.ts"],"sourcesContent":["import {\n  DICTATION_ENGINE_ERROR_KINDS,\n  type DictationEngine,\n  type DictationEngineError,\n} from './dictation-engine';\n\nexport interface DictationTranscribeContext {\n  /** BCP-47 tag the session was started with (host `lang` or the document's). */\n  lang: string;\n  /** Fires when the user cancels or the composer gives up waiting. */\n  signal: AbortSignal;\n}\n\n/**\n * Turn a finished recording into text. Receives the whole clip once the user\n * stops; resolves with the transcript (empty when nothing was said). Should\n * honour `signal` so a cancelled dictation does not keep uploading.\n */\nexport type DictationTranscriber = (clip: Blob, context: DictationTranscribeContext) => Promise<string>;\n\nexport interface RecordedDictationEngineOptions {\n  transcribe: DictationTranscriber;\n  /**\n   * Preferred `MediaRecorder` container, tried in order until the browser\n   * accepts one. Defaults to Opus in WebM (Chrome, Firefox, Edge) then MP4\n   * (Safari); the browser's own default is the last resort.\n   */\n  mimeTypes?: readonly string[];\n  /**\n   * Upper bound on the transcription round trip; the in-flight request is\n   * aborted when it elapses. Defaults to 90s, above agora's 60s Deepgram\n   * budget plus upload time.\n   */\n  flushTimeoutMs?: number;\n  /**\n   * Longest recording the engine accepts before it stops on its own and\n   * transcribes what it has, exactly as if Stop had been pressed. Bounds a\n   * mic left open by mistake: every recorded minute is a minute billed by the\n   * recognizer, and agora refuses clips over its size cap. Defaults to\n   * 5 minutes; pass `Infinity` to disable.\n   */\n  maxDurationMs?: number;\n}\n\nconst DEFAULT_MIME_TYPES = ['audio/webm;codecs=opus', 'audio/webm', 'audio/mp4', 'audio/ogg;codecs=opus'];\nconst DEFAULT_FLUSH_TIMEOUT_MS = 90_000;\nexport const DEFAULT_MAX_RECORDING_MS = 5 * 60_000;\n\n// lib.dom typings for MediaRecorder vary across the TypeScript versions the\n// SDK supports; describe only what the engine touches.\ninterface MediaRecorderLike extends EventTarget {\n  readonly state: 'inactive' | 'recording' | 'paused';\n  readonly mimeType: string;\n  start: (timeslice?: number) => void;\n  stop: () => void;\n  ondataavailable: ((event: { data: Blob }) => void) | null;\n  onstop: (() => void) | null;\n  onerror: ((event: Event) => void) | null;\n}\ninterface MediaRecorderCtor {\n  new (stream: MediaStream, options?: { mimeType?: string }): MediaRecorderLike;\n  isTypeSupported?: (type: string) => boolean;\n}\n\nfunction resolveMediaRecorderCtor(): MediaRecorderCtor | null {\n  if (typeof window === 'undefined') return null;\n  return (window as unknown as { MediaRecorder?: MediaRecorderCtor }).MediaRecorder ?? null;\n}\n\n/** First container the recorder accepts, or undefined for the browser default. */\nexport function pickRecorderMimeType(\n  Ctor: Pick<MediaRecorderCtor, 'isTypeSupported'>,\n  candidates: readonly string[],\n): string | undefined {\n  if (!Ctor.isTypeSupported) return undefined;\n  return candidates.find((type) => Ctor.isTypeSupported?.(type));\n}\n\nfunction transcriptionError(error: unknown): DictationEngineError {\n  return {\n    kind: DICTATION_ENGINE_ERROR_KINDS.connection,\n    message: error instanceof Error && error.message ? error.message : 'Transcription failed. Try again.',\n  };\n}\n\n/**\n * Record-then-transcribe: capture the microphone with `MediaRecorder` while\n * the user talks, then hand the finished clip to `transcribe` on stop. No\n * interim words are shown; the composer shows a \"transcribing\" state until\n * the text lands. Works in every browser with `MediaRecorder`, so the mic is\n * available where Web Speech is not (Firefox) and the quality is whatever the\n * server-side recognizer provides.\n */\nexport function createRecordedDictationEngine(options: RecordedDictationEngineOptions): DictationEngine {\n  const {\n    transcribe,\n    mimeTypes = DEFAULT_MIME_TYPES,\n    flushTimeoutMs = DEFAULT_FLUSH_TIMEOUT_MS,\n    maxDurationMs = DEFAULT_MAX_RECORDING_MS,\n  } = options;\n  return {\n    id: 'recorded-upload',\n    flushTimeoutMs,\n    stoppingLabel: 'Transcribing…',\n    isSupported: () =>\n      resolveMediaRecorderCtor() !== null &&\n      typeof navigator !== 'undefined' &&\n      typeof navigator.mediaDevices?.getUserMedia === 'function',\n    start: ({ stream, lang, callbacks }) => {\n      const Ctor = resolveMediaRecorderCtor();\n      const noop = { stop: () => undefined, abort: () => undefined };\n      if (!Ctor || !stream) {\n        callbacks.onError({\n          kind: !Ctor ? DICTATION_ENGINE_ERROR_KINDS.unsupported : DICTATION_ENGINE_ERROR_KINDS.permission,\n          message: !Ctor ? 'This browser cannot record audio.' : 'No microphone stream was available.',\n        });\n        callbacks.onEnd();\n        return noop;\n      }\n\n      const mimeType = pickRecorderMimeType(Ctor, mimeTypes);\n      let recorder: MediaRecorderLike;\n      try {\n        recorder = new Ctor(stream, mimeType ? { mimeType } : undefined);\n      } catch (error) {\n        callbacks.onError({\n          kind: DICTATION_ENGINE_ERROR_KINDS.unknown,\n          message: error instanceof Error ? error.message : 'Recording could not start.',\n        });\n        callbacks.onEnd();\n        return noop;\n      }\n\n      const chunks: Blob[] = [];\n      const upload = new AbortController();\n      let ended = false;\n      let aborted = false;\n      let limitTimer: ReturnType<typeof setTimeout> | undefined;\n      const clearLimit = () => {\n        if (limitTimer === undefined) return;\n        clearTimeout(limitTimer);\n        limitTimer = undefined;\n      };\n      const end = () => {\n        if (ended) return;\n        ended = true;\n        clearLimit();\n        recorder.ondataavailable = null;\n        recorder.onstop = null;\n        recorder.onerror = null;\n        callbacks.onEnd();\n      };\n      const stopRecorder = () => {\n        if (recorder.state === 'inactive') return false;\n        try {\n          recorder.stop();\n          return true;\n        } catch {\n          return false;\n        }\n      };\n\n      recorder.ondataavailable = (event) => {\n        if (event.data && event.data.size > 0) chunks.push(event.data);\n      };\n      recorder.onerror = () => {\n        callbacks.onError({\n          kind: DICTATION_ENGINE_ERROR_KINDS.unknown,\n          message: 'Recording stopped unexpectedly.',\n        });\n        end();\n      };\n      recorder.onstop = () => {\n        if (aborted || ended) {\n          end();\n          return;\n        }\n        const clip = new Blob(chunks, { type: recorder.mimeType || mimeType || 'audio/webm' });\n        if (clip.size === 0) {\n          end();\n          return;\n        }\n        void transcribe(clip, { lang, signal: upload.signal })\n          .then((text) => {\n            if (ended) return;\n            const trimmed = text.trim();\n            if (trimmed) callbacks.onTranscript({ final: trimmed, interim: '' });\n          })\n          .catch((error: unknown) => {\n            if (ended) return;\n            callbacks.onError(transcriptionError(error));\n          })\n          .finally(end);\n      };\n\n      try {\n        recorder.start();\n      } catch (error) {\n        callbacks.onError({\n          kind: DICTATION_ENGINE_ERROR_KINDS.unknown,\n          message: error instanceof Error ? error.message : 'Recording could not start.',\n        });\n        end();\n        return noop;\n      }\n\n      if (Number.isFinite(maxDurationMs) && maxDurationMs > 0) {\n        limitTimer = setTimeout(() => {\n          limitTimer = undefined;\n          // Same path as the user's Stop: onstop transcribes the clip and the\n          // words land in the draft. A recorder that is already inactive is a\n          // stop in flight, which must run to completion untouched.\n          if (!ended) stopRecorder();\n        }, maxDurationMs);\n      }\n\n      return {\n        stop: () => {\n          clearLimit();\n          if (!stopRecorder()) end();\n        },\n        abort: () => {\n          aborted = true;\n          upload.abort();\n          stopRecorder();\n          end();\n        },\n      };\n    },\n  };\n}\n"],"names":[],"mappings":"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"}

package/dist/dictation/use-athena-dictation-engine.cjs

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const react = require("react");
+const AthenaContext = require("../provider/AthenaContext.cjs");
+const statewireAuthHeaders = require("../runtime/statewire-auth-headers.cjs");
+const dictationEngine = require("./dictation-engine.cjs");
+const recordedDictationEngine = require("./recorded-dictation-engine.cjs");
+function transcriptionUploadUrl(backendUrl) {
+  return `${backendUrl.replace(/\/api\/assistant-ui\/?$/, "").replace(/\/$/, "")}/api/transcription/upload`;
+}
+function transcriptionUploadErrorMessage(status) {
+  switch (status) {
+    case 401:
+    case 403:
+      return "Dictation is not available for this sign-in. Reload and try again.";
+    case 413:
+      return "That recording is too long to transcribe.";
+    case 422:
+      return "The dictation language was rejected. Use a BCP-47 tag such as en-US.";
+    case 429:
+      return "Too many dictations in a row. Wait a moment and try again.";
+    case 503:
+      return "Dictation is not set up on this server.";
+    default:
+      return `Transcription failed (${status}).`;
+  }
+}
+function createAthenaUploadTranscriber(getConfig) {
+  return async (clip, { lang, signal }) => {
+    const config = getConfig();
+    const headers = await statewireAuthHeaders.resolveStatewireAuthHeaders(config, { staleAuth: false });
+    const form = new FormData();
+    const extension = clip.type.includes("mp4") ? "mp4" : clip.type.includes("ogg") ? "ogg" : "webm";
+    form.append("file", clip, `dictation.${extension}`);
+    if (lang) form.append("language", lang);
+    const response = await fetch(transcriptionUploadUrl(config.backendUrl), {
+      method: "POST",
+      headers,
+      body: form,
+      credentials: "include",
+      signal
+    });
+    if (!response.ok) throw new Error(transcriptionUploadErrorMessage(response.status));
+    const payload = await response.json();
+    return typeof payload.transcript === "string" ? payload.transcript : "";
+  };
+}
+function useAthenaDictationEngine(override) {
+  const config = AthenaContext.useAthenaConfig();
+  const configRef = react.useRef(config);
+  configRef.current = config;
+  return react.useMemo(() => {
+    if (override) return override;
+    const recorded = recordedDictationEngine.createRecordedDictationEngine({
+      transcribe: createAthenaUploadTranscriber(() => configRef.current)
+    });
+    return recorded.isSupported() ? recorded : dictationEngine.createWebSpeechDictationEngine();
+  }, [override]);
+}
+exports.createAthenaUploadTranscriber = createAthenaUploadTranscriber;
+exports.transcriptionUploadErrorMessage = transcriptionUploadErrorMessage;
+exports.transcriptionUploadUrl = transcriptionUploadUrl;
+exports.useAthenaDictationEngine = useAthenaDictationEngine;
+//# sourceMappingURL=use-athena-dictation-engine.cjs.map

package/dist/dictation/use-athena-dictation-engine.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-athena-dictation-engine.cjs","sources":["../../src/dictation/use-athena-dictation-engine.ts"],"sourcesContent":["import { useMemo, useRef } from 'react';\nimport { type AthenaConfig, useAthenaConfig } from '../provider/AthenaContext';\nimport { resolveStatewireAuthHeaders } from '../runtime/statewire-auth-headers';\nimport { createWebSpeechDictationEngine, type DictationEngine } from './dictation-engine';\nimport { createRecordedDictationEngine, type DictationTranscriber } from './recorded-dictation-engine';\n\ninterface UploadTranscriptionResponse {\n  transcript: string;\n}\n\n/** Agora's REST base from the configured backend URL (which may point at a nested endpoint). */\nexport function transcriptionUploadUrl(backendUrl: string): string {\n  return `${backendUrl.replace(/\\/api\\/assistant-ui\\/?$/, '').replace(/\\/$/, '')}/api/transcription/upload`;\n}\n\n/**\n * One line for the composer per way `/transcription/upload` refuses a clip.\n * The copy lives here, apart from the fetch, so it can be pinned by a test.\n */\nexport function transcriptionUploadErrorMessage(status: number): string {\n  switch (status) {\n    case 401:\n    case 403:\n      return 'Dictation is not available for this sign-in. Reload and try again.';\n    case 413:\n      return 'That recording is too long to transcribe.';\n    case 422:\n      return 'The dictation language was rejected. Use a BCP-47 tag such as en-US.';\n    case 429:\n      return 'Too many dictations in a row. Wait a moment and try again.';\n    case 503:\n      return 'Dictation is not set up on this server.';\n    default:\n      return `Transcription failed (${status}).`;\n  }\n}\n\n/**\n * Post a finished clip to agora's `/transcription/upload` route, which runs\n * it through Deepgram and returns the text. Credentials are read at call\n * time so a rotated token is picked up. The session language (host `lang`\n * or the document's) is forwarded so non-English speech is recognised as\n * such; the request is dropped when the engine aborts.\n */\nexport function createAthenaUploadTranscriber(\n  getConfig: () => Pick<AthenaConfig, 'backendUrl' | 'apiKey' | 'token' | 'getToken'>,\n): DictationTranscriber {\n  return async (clip, { lang, signal }) => {\n    const config = getConfig();\n    const headers = await resolveStatewireAuthHeaders(config, { staleAuth: false });\n    const form = new FormData();\n    const extension = clip.type.includes('mp4') ? 'mp4' : clip.type.includes('ogg') ? 'ogg' : 'webm';\n    form.append('file', clip, `dictation.${extension}`);\n    if (lang) form.append('language', lang);\n    const response = await fetch(transcriptionUploadUrl(config.backendUrl), {\n      method: 'POST',\n      headers,\n      body: form,\n      credentials: 'include',\n      signal,\n    });\n    if (!response.ok) throw new Error(transcriptionUploadErrorMessage(response.status));\n    const payload = (await response.json()) as UploadTranscriptionResponse;\n    return typeof payload.transcript === 'string' ? payload.transcript : '';\n  };\n}\n\n/**\n * The composer's default speech engine: record with `MediaRecorder`, then\n * transcribe the clip through agora (Deepgram). Falls back to the browser's\n * Web Speech API only where `MediaRecorder` is missing. A host-provided\n * `engine` always wins.\n */\nexport function useAthenaDictationEngine(override?: DictationEngine): DictationEngine {\n  const config = useAthenaConfig();\n  const configRef = useRef(config);\n  configRef.current = config;\n  return useMemo(() => {\n    if (override) return override;\n    const recorded = createRecordedDictationEngine({\n      transcribe: createAthenaUploadTranscriber(() => configRef.current),\n    });\n    return recorded.isSupported() ? recorded : createWebSpeechDictationEngine();\n  }, [override]);\n}\n"],"names":["resolveStatewireAuthHeaders","useAthenaConfig","useRef","useMemo","createRecordedDictationEngine","createWebSpeechDictationEngine"],"mappings":";;;;;;;AAWO,SAAS,uBAAuB,YAA4B;AACjE,SAAO,GAAG,WAAW,QAAQ,2BAA2B,EAAE,EAAE,QAAQ,OAAO,EAAE,CAAC;AAChF;AAMO,SAAS,gCAAgC,QAAwB;AACtE,UAAQ,QAAA;AAAA,IACN,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT;AACE,aAAO,yBAAyB,MAAM;AAAA,EAAA;AAE5C;AASO,SAAS,8BACd,WACsB;AACtB,SAAO,OAAO,MAAM,EAAE,MAAM,aAAa;AACvC,UAAM,SAAS,UAAA;AACf,UAAM,UAAU,MAAMA,qBAAAA,4BAA4B,QAAQ,EAAE,WAAW,OAAO;AAC9E,UAAM,OAAO,IAAI,SAAA;AACjB,UAAM,YAAY,KAAK,KAAK,SAAS,KAAK,IAAI,QAAQ,KAAK,KAAK,SAAS,KAAK,IAAI,QAAQ;AAC1F,SAAK,OAAO,QAAQ,MAAM,aAAa,SAAS,EAAE;AAClD,QAAI,KAAM,MAAK,OAAO,YAAY,IAAI;AACtC,UAAM,WAAW,MAAM,MAAM,uBAAuB,OAAO,UAAU,GAAG;AAAA,MACtE,QAAQ;AAAA,MACR;AAAA,MACA,MAAM;AAAA,MACN,aAAa;AAAA,MACb;AAAA,IAAA,CACD;AACD,QAAI,CAAC,SAAS,GAAI,OAAM,IAAI,MAAM,gCAAgC,SAAS,MAAM,CAAC;AAClF,UAAM,UAAW,MAAM,SAAS,KAAA;AAChC,WAAO,OAAO,QAAQ,eAAe,WAAW,QAAQ,aAAa;AAAA,EACvE;AACF;AAQO,SAAS,yBAAyB,UAA6C;AACpF,QAAM,SAASC,cAAAA,gBAAA;AACf,QAAM,YAAYC,MAAAA,OAAO,MAAM;AAC/B,YAAU,UAAU;AACpB,SAAOC,MAAAA,QAAQ,MAAM;AACnB,QAAI,SAAU,QAAO;AACrB,UAAM,WAAWC,wBAAAA,8BAA8B;AAAA,MAC7C,YAAY,8BAA8B,MAAM,UAAU,OAAO;AAAA,IAAA,CAClE;AACD,WAAO,SAAS,gBAAgB,WAAWC,gBAAAA,+BAAA;AAAA,EAC7C,GAAG,CAAC,QAAQ,CAAC;AACf;;;;;"}

package/dist/dictation/use-athena-dictation-engine.d.ts

@@ -0,0 +1,25 @@
+import { type AthenaConfig } from '../provider/AthenaContext';
+import { type DictationEngine } from './dictation-engine';
+import { type DictationTranscriber } from './recorded-dictation-engine';
+/** Agora's REST base from the configured backend URL (which may point at a nested endpoint). */
+export declare function transcriptionUploadUrl(backendUrl: string): string;
+/**
+ * One line for the composer per way `/transcription/upload` refuses a clip.
+ * The copy lives here, apart from the fetch, so it can be pinned by a test.
+ */
+export declare function transcriptionUploadErrorMessage(status: number): string;
+/**
+ * Post a finished clip to agora's `/transcription/upload` route, which runs
+ * it through Deepgram and returns the text. Credentials are read at call
+ * time so a rotated token is picked up. The session language (host `lang`
+ * or the document's) is forwarded so non-English speech is recognised as
+ * such; the request is dropped when the engine aborts.
+ */
+export declare function createAthenaUploadTranscriber(getConfig: () => Pick<AthenaConfig, 'backendUrl' | 'apiKey' | 'token' | 'getToken'>): DictationTranscriber;
+/**
+ * The composer's default speech engine: record with `MediaRecorder`, then
+ * transcribe the clip through agora (Deepgram). Falls back to the browser's
+ * Web Speech API only where `MediaRecorder` is missing. A host-provided
+ * `engine` always wins.
+ */
+export declare function useAthenaDictationEngine(override?: DictationEngine): DictationEngine;

package/dist/dictation/use-athena-dictation-engine.js

@@ -0,0 +1,64 @@
+import { useRef, useMemo } from "react";
+import { useAthenaConfig } from "../provider/AthenaContext.js";
+import { resolveStatewireAuthHeaders } from "../runtime/statewire-auth-headers.js";
+import { createWebSpeechDictationEngine } from "./dictation-engine.js";
+import { createRecordedDictationEngine } from "./recorded-dictation-engine.js";
+function transcriptionUploadUrl(backendUrl) {
+  return `${backendUrl.replace(/\/api\/assistant-ui\/?$/, "").replace(/\/$/, "")}/api/transcription/upload`;
+}
+function transcriptionUploadErrorMessage(status) {
+  switch (status) {
+    case 401:
+    case 403:
+      return "Dictation is not available for this sign-in. Reload and try again.";
+    case 413:
+      return "That recording is too long to transcribe.";
+    case 422:
+      return "The dictation language was rejected. Use a BCP-47 tag such as en-US.";
+    case 429:
+      return "Too many dictations in a row. Wait a moment and try again.";
+    case 503:
+      return "Dictation is not set up on this server.";
+    default:
+      return `Transcription failed (${status}).`;
+  }
+}
+function createAthenaUploadTranscriber(getConfig) {
+  return async (clip, { lang, signal }) => {
+    const config = getConfig();
+    const headers = await resolveStatewireAuthHeaders(config, { staleAuth: false });
+    const form = new FormData();
+    const extension = clip.type.includes("mp4") ? "mp4" : clip.type.includes("ogg") ? "ogg" : "webm";
+    form.append("file", clip, `dictation.${extension}`);
+    if (lang) form.append("language", lang);
+    const response = await fetch(transcriptionUploadUrl(config.backendUrl), {
+      method: "POST",
+      headers,
+      body: form,
+      credentials: "include",
+      signal
+    });
+    if (!response.ok) throw new Error(transcriptionUploadErrorMessage(response.status));
+    const payload = await response.json();
+    return typeof payload.transcript === "string" ? payload.transcript : "";
+  };
+}
+function useAthenaDictationEngine(override) {
+  const config = useAthenaConfig();
+  const configRef = useRef(config);
+  configRef.current = config;
+  return useMemo(() => {
+    if (override) return override;
+    const recorded = createRecordedDictationEngine({
+      transcribe: createAthenaUploadTranscriber(() => configRef.current)
+    });
+    return recorded.isSupported() ? recorded : createWebSpeechDictationEngine();
+  }, [override]);
+}
+export {
+  createAthenaUploadTranscriber,
+  transcriptionUploadErrorMessage,
+  transcriptionUploadUrl,
+  useAthenaDictationEngine
+};
+//# sourceMappingURL=use-athena-dictation-engine.js.map

package/dist/dictation/use-athena-dictation-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-athena-dictation-engine.js","sources":["../../src/dictation/use-athena-dictation-engine.ts"],"sourcesContent":["import { useMemo, useRef } from 'react';\nimport { type AthenaConfig, useAthenaConfig } from '../provider/AthenaContext';\nimport { resolveStatewireAuthHeaders } from '../runtime/statewire-auth-headers';\nimport { createWebSpeechDictationEngine, type DictationEngine } from './dictation-engine';\nimport { createRecordedDictationEngine, type DictationTranscriber } from './recorded-dictation-engine';\n\ninterface UploadTranscriptionResponse {\n  transcript: string;\n}\n\n/** Agora's REST base from the configured backend URL (which may point at a nested endpoint). */\nexport function transcriptionUploadUrl(backendUrl: string): string {\n  return `${backendUrl.replace(/\\/api\\/assistant-ui\\/?$/, '').replace(/\\/$/, '')}/api/transcription/upload`;\n}\n\n/**\n * One line for the composer per way `/transcription/upload` refuses a clip.\n * The copy lives here, apart from the fetch, so it can be pinned by a test.\n */\nexport function transcriptionUploadErrorMessage(status: number): string {\n  switch (status) {\n    case 401:\n    case 403:\n      return 'Dictation is not available for this sign-in. Reload and try again.';\n    case 413:\n      return 'That recording is too long to transcribe.';\n    case 422:\n      return 'The dictation language was rejected. Use a BCP-47 tag such as en-US.';\n    case 429:\n      return 'Too many dictations in a row. Wait a moment and try again.';\n    case 503:\n      return 'Dictation is not set up on this server.';\n    default:\n      return `Transcription failed (${status}).`;\n  }\n}\n\n/**\n * Post a finished clip to agora's `/transcription/upload` route, which runs\n * it through Deepgram and returns the text. Credentials are read at call\n * time so a rotated token is picked up. The session language (host `lang`\n * or the document's) is forwarded so non-English speech is recognised as\n * such; the request is dropped when the engine aborts.\n */\nexport function createAthenaUploadTranscriber(\n  getConfig: () => Pick<AthenaConfig, 'backendUrl' | 'apiKey' | 'token' | 'getToken'>,\n): DictationTranscriber {\n  return async (clip, { lang, signal }) => {\n    const config = getConfig();\n    const headers = await resolveStatewireAuthHeaders(config, { staleAuth: false });\n    const form = new FormData();\n    const extension = clip.type.includes('mp4') ? 'mp4' : clip.type.includes('ogg') ? 'ogg' : 'webm';\n    form.append('file', clip, `dictation.${extension}`);\n    if (lang) form.append('language', lang);\n    const response = await fetch(transcriptionUploadUrl(config.backendUrl), {\n      method: 'POST',\n      headers,\n      body: form,\n      credentials: 'include',\n      signal,\n    });\n    if (!response.ok) throw new Error(transcriptionUploadErrorMessage(response.status));\n    const payload = (await response.json()) as UploadTranscriptionResponse;\n    return typeof payload.transcript === 'string' ? payload.transcript : '';\n  };\n}\n\n/**\n * The composer's default speech engine: record with `MediaRecorder`, then\n * transcribe the clip through agora (Deepgram). Falls back to the browser's\n * Web Speech API only where `MediaRecorder` is missing. A host-provided\n * `engine` always wins.\n */\nexport function useAthenaDictationEngine(override?: DictationEngine): DictationEngine {\n  const config = useAthenaConfig();\n  const configRef = useRef(config);\n  configRef.current = config;\n  return useMemo(() => {\n    if (override) return override;\n    const recorded = createRecordedDictationEngine({\n      transcribe: createAthenaUploadTranscriber(() => configRef.current),\n    });\n    return recorded.isSupported() ? recorded : createWebSpeechDictationEngine();\n  }, [override]);\n}\n"],"names":[],"mappings":";;;;;AAWO,SAAS,uBAAuB,YAA4B;AACjE,SAAO,GAAG,WAAW,QAAQ,2BAA2B,EAAE,EAAE,QAAQ,OAAO,EAAE,CAAC;AAChF;AAMO,SAAS,gCAAgC,QAAwB;AACtE,UAAQ,QAAA;AAAA,IACN,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT;AACE,aAAO,yBAAyB,MAAM;AAAA,EAAA;AAE5C;AASO,SAAS,8BACd,WACsB;AACtB,SAAO,OAAO,MAAM,EAAE,MAAM,aAAa;AACvC,UAAM,SAAS,UAAA;AACf,UAAM,UAAU,MAAM,4BAA4B,QAAQ,EAAE,WAAW,OAAO;AAC9E,UAAM,OAAO,IAAI,SAAA;AACjB,UAAM,YAAY,KAAK,KAAK,SAAS,KAAK,IAAI,QAAQ,KAAK,KAAK,SAAS,KAAK,IAAI,QAAQ;AAC1F,SAAK,OAAO,QAAQ,MAAM,aAAa,SAAS,EAAE;AAClD,QAAI,KAAM,MAAK,OAAO,YAAY,IAAI;AACtC,UAAM,WAAW,MAAM,MAAM,uBAAuB,OAAO,UAAU,GAAG;AAAA,MACtE,QAAQ;AAAA,MACR;AAAA,MACA,MAAM;AAAA,MACN,aAAa;AAAA,MACb;AAAA,IAAA,CACD;AACD,QAAI,CAAC,SAAS,GAAI,OAAM,IAAI,MAAM,gCAAgC,SAAS,MAAM,CAAC;AAClF,UAAM,UAAW,MAAM,SAAS,KAAA;AAChC,WAAO,OAAO,QAAQ,eAAe,WAAW,QAAQ,aAAa;AAAA,EACvE;AACF;AAQO,SAAS,yBAAyB,UAA6C;AACpF,QAAM,SAAS,gBAAA;AACf,QAAM,YAAY,OAAO,MAAM;AAC/B,YAAU,UAAU;AACpB,SAAO,QAAQ,MAAM;AACnB,QAAI,SAAU,QAAO;AACrB,UAAM,WAAW,8BAA8B;AAAA,MAC7C,YAAY,8BAA8B,MAAM,UAAU,OAAO;AAAA,IAAA,CAClE;AACD,WAAO,SAAS,gBAAgB,WAAW,+BAAA;AAAA,EAC7C,GAAG,CAAC,QAAQ,CAAC;AACf;"}

package/dist/dictation/use-dictation.cjs

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const react = require("react");
+const athenaDiagnostics = require("../diagnostics/athena-diagnostics.cjs");
+const dictationEngine = require("./dictation-engine.cjs");
+const dictationState = require("./dictation-state.cjs");
+const DEFAULT_STOP_FLUSH_TIMEOUT_MS = 1500;
+const EMPTY_TRANSCRIPT = { final: "", interim: "" };
+function documentLanguage() {
+  if (typeof document !== "undefined" && document.documentElement.lang) {
+    return document.documentElement.lang;
+  }
+  if (typeof navigator !== "undefined" && navigator.language) return navigator.language;
+  return "en-US";
+}
+async function openMicrophone() {
+  var _a;
+  if (typeof navigator === "undefined" || !((_a = navigator.mediaDevices) == null ? void 0 : _a.getUserMedia)) return null;
+  return navigator.mediaDevices.getUserMedia({ audio: true });
+}
+function releaseStream(stream) {
+  if (!stream) return;
+  for (const track of stream.getTracks()) track.stop();
+}
+function useDictation(options = {}) {
+  const engine = react.useMemo(() => options.engine ?? dictationEngine.createWebSpeechDictationEngine(), [options.engine]);
+  const { lang, captureStream = true, onAutoEnd } = options;
+  const [state, dispatch] = react.useReducer(dictationState.dictationReducer, dictationState.INITIAL_DICTATION_STATE);
+  const [stream, setStream] = react.useState(null);
+  const [isSupported, setIsSupported] = react.useState(false);
+  const sessionRef = react.useRef(null);
+  const streamRef = react.useRef(null);
+  const stateRef = react.useRef(state);
+  stateRef.current = state;
+  const transcriptRef = react.useRef(EMPTY_TRANSCRIPT);
+  const onAutoEndRef = react.useRef(onAutoEnd);
+  onAutoEndRef.current = onAutoEnd;
+  const stopWaitersRef = react.useRef([]);
+  const sessionErrorRef = react.useRef(null);
+  const generationRef = react.useRef(0);
+  react.useEffect(() => {
+    setIsSupported(engine.isSupported());
+  }, [engine]);
+  const settleWaiters = react.useCallback((spoken) => {
+    const waiters = stopWaitersRef.current;
+    stopWaitersRef.current = [];
+    const result = { text: spoken, error: sessionErrorRef.current };
+    for (const resolve of waiters) resolve(result);
+  }, []);
+  const releaseSession = react.useCallback(() => {
+    sessionRef.current = null;
+    releaseStream(streamRef.current);
+    streamRef.current = null;
+    setStream(null);
+  }, []);
+  const teardown = react.useCallback(() => {
+    var _a;
+    generationRef.current += 1;
+    (_a = sessionRef.current) == null ? void 0 : _a.abort();
+    releaseSession();
+    transcriptRef.current = EMPTY_TRANSCRIPT;
+    settleWaiters("");
+  }, [releaseSession, settleWaiters]);
+  const reportEngineError = react.useCallback(
+    (engineError) => {
+      athenaDiagnostics.athenaDiagnostics.emit("composer.dictation", {
+        level: "warn",
+        data: { phase: "error", engine: engine.id, kind: engineError.kind }
+      });
+      sessionErrorRef.current = engineError;
+      dispatch({ type: "error", error: engineError });
+    },
+    [engine.id]
+  );
+  const start = react.useCallback(() => {
+    if (sessionRef.current) return;
+    const generation = generationRef.current + 1;
+    generationRef.current = generation;
+    transcriptRef.current = EMPTY_TRANSCRIPT;
+    sessionErrorRef.current = null;
+    dispatch({ type: "start" });
+    athenaDiagnostics.athenaDiagnostics.emit("composer.dictation", {
+      level: "debug",
+      data: { phase: "start", engine: engine.id }
+    });
+    const run = async () => {
+      let microphone = null;
+      if (captureStream) {
+        try {
+          microphone = await openMicrophone();
+        } catch (error) {
+          if (generationRef.current !== generation) {
+            releaseStream(microphone);
+            return;
+          }
+          dispatch({
+            type: "error",
+            error: {
+              kind: dictationEngine.DICTATION_ENGINE_ERROR_KINDS.permission,
+              message: error instanceof DOMException && error.name === "NotFoundError" ? "No microphone was found." : "Microphone access was denied. Allow the microphone for this site and try again."
+            }
+          });
+          return;
+        }
+      }
+      if (generationRef.current !== generation) {
+        releaseStream(microphone);
+        return;
+      }
+      streamRef.current = microphone;
+      setStream(microphone);
+      let terminated = false;
+      const endSession = () => {
+        var _a;
+        terminated = true;
+        const current = stateRef.current;
+        const spoken = dictationState.spokenText(transcriptRef.current);
+        const endedOnItsOwn = stopWaitersRef.current.length === 0 && current.status === dictationState.DICTATION_STATUSES.listening;
+        dispatch({ type: "ended" });
+        releaseSession();
+        settleWaiters(spoken);
+        if (endedOnItsOwn) (_a = onAutoEndRef.current) == null ? void 0 : _a.call(onAutoEndRef, spoken);
+      };
+      let session;
+      try {
+        session = engine.start({
+          stream: microphone,
+          lang: lang ?? documentLanguage(),
+          callbacks: {
+            onTranscript: (update) => {
+              if (generationRef.current !== generation) return;
+              transcriptRef.current = {
+                final: dictationState.joinSpeech(transcriptRef.current.final, update.final),
+                interim: update.interim
+              };
+              dispatch({ type: "transcript", update });
+            },
+            onError: (engineError) => {
+              if (generationRef.current !== generation) return;
+              if (engineError.kind === dictationEngine.DICTATION_ENGINE_ERROR_KINDS.noSpeech) return;
+              reportEngineError(engineError);
+            },
+            onEnd: () => {
+              if (generationRef.current !== generation) return;
+              endSession();
+            }
+          }
+        });
+      } catch (error) {
+        releaseSession();
+        reportEngineError({
+          kind: dictationEngine.DICTATION_ENGINE_ERROR_KINDS.connection,
+          message: error instanceof Error ? error.message : "Dictation could not start."
+        });
+        return;
+      }
+      if (terminated) return;
+      sessionRef.current = session;
+      dispatch({ type: "listening" });
+    };
+    void run();
+  }, [captureStream, engine, lang, releaseSession, reportEngineError, settleWaiters]);
+  const stop = react.useCallback(() => {
+    const session = sessionRef.current;
+    if (!session) {
+      if (stateRef.current.status === dictationState.DICTATION_STATUSES.starting) {
+        teardown();
+        dispatch({ type: "cancel" });
+        return Promise.resolve({ text: "", error: null });
+      }
+      return Promise.resolve({ text: dictationState.spokenText(transcriptRef.current), error: sessionErrorRef.current });
+    }
+    dispatch({ type: "stop" });
+    const flushed = new Promise((resolve) => {
+      stopWaitersRef.current.push(resolve);
+      window.setTimeout(() => {
+        if (sessionRef.current === session) {
+          if (!dictationState.spokenText(transcriptRef.current)) {
+            reportEngineError({
+              kind: dictationEngine.DICTATION_ENGINE_ERROR_KINDS.connection,
+              message: "Transcription timed out. Try again."
+            });
+          }
+          session.abort();
+          dispatch({ type: "ended" });
+          releaseSession();
+          settleWaiters(dictationState.spokenText(transcriptRef.current));
+        }
+      }, engine.flushTimeoutMs ?? DEFAULT_STOP_FLUSH_TIMEOUT_MS);
+    });
+    session.stop();
+    return flushed;
+  }, [engine.flushTimeoutMs, releaseSession, reportEngineError, settleWaiters, teardown]);
+  const cancel = react.useCallback(() => {
+    teardown();
+    dispatch({ type: "cancel" });
+  }, [teardown]);
+  react.useEffect(() => () => teardown(), [teardown]);
+  const isActive = state.status === dictationState.DICTATION_STATUSES.starting || state.status === dictationState.DICTATION_STATUSES.listening || state.status === dictationState.DICTATION_STATUSES.stopping;
+  return {
+    status: state.status,
+    isActive,
+    transcript: state.transcript,
+    text: dictationState.spokenText(state.transcript),
+    error: state.error,
+    stream,
+    isSupported,
+    engine,
+    start,
+    stop,
+    cancel
+  };
+}
+exports.useDictation = useDictation;
+//# sourceMappingURL=use-dictation.cjs.map