@hartren/assistant-js 0.0.0-stage → 2.3.1

package/dist/SpeechRecognitionService/speechConfig.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Speech provider configuration.
+ *
+ * HIPAA: dictation audio and spoken replies can contain PHI. The default provider is the hosted
+ * Hartren API speech service (`/ws/speech/transcribe` and `/ws/speech/speak`, backed by Deepgram).
+ * Browser Web Speech (SpeechRecognition / webkitSpeechRecognition / speechSynthesis) may send audio
+ * or text to the browser/OS vendor (e.g. Google, Microsoft), which has no BAA with us. It is used ONLY
+ * when the host explicitly sets `speechProvider: 'browser'`, or explicitly opts into
+ * `browserTranscriptionFallback: true` (default false). Never as an automatic fallback by default.
+ */
+export declare const speechProvider: {
+    /** Hosted transcription/TTS over WebSocket (Deepgram). Default. */
+    readonly DEEPGRAM: "deepgram";
+    /** Browser Web Speech APIs. Opt-in only (see also the separate browserTranscriptionFallback opt-in). */
+    readonly BROWSER: "browser";
+};
+export type SpeechProvider = (typeof speechProvider)[keyof typeof speechProvider];
+/** Anything other than an explicit 'browser' means the hosted (Deepgram) provider. */
+export declare function normalizeSpeechProvider(provider?: string | null): SpeechProvider;
+export interface SpeechRetryOptions {
+    /** Reconnect attempts after a failure before the final error. Default 3. */
+    maxRetries?: number;
+    /** First retry delay; doubles on each attempt. Default 1000 ms. */
+    baseDelayMs?: number;
+    /** Upper bound for a single retry delay. Default 8000 ms. */
+    maxDelayMs?: number;
+}
+export declare const DEFAULT_SPEECH_RETRY: Required<SpeechRetryOptions>;
+export declare function resolveSpeechRetry(options?: SpeechRetryOptions | null): Required<SpeechRetryOptions>;
+/** Exponential backoff: base * 2^(attempt-1), capped at maxDelayMs. `attempt` starts at 1. */
+export declare function retryDelayMs(attempt: number, options: Required<SpeechRetryOptions>): number;
+/**
+ * Default speech WebSocket origin for a Copilot API URL. The Hartren API serves `/ws/speech/*` at the
+ * host root, so `https://api.example.com/api` → `wss://api.example.com`. A relative API URL ('/api')
+ * resolves against `baseOrigin` (default: window.location.origin). Returns null when it cannot be
+ * resolved to an http(s) URL (the caller then reports transcription-not-configured).
+ */
+export declare function deriveTranscribeWssUrl(copilotApi?: string | null, baseOrigin?: string | null): string | null;
+/**
+ * True when the user's access token may be sent to this speech WebSocket URL: any `wss://` URL, or
+ * plain `ws://` only to localhost / 127.0.0.1 / [::1] (local development). Anything else (a remote
+ * `ws://`, another scheme, an unparsable URL) would expose the token in clear text, so it is refused.
+ */
+export declare function isSpeechSocketUrlAllowed(url?: string | null): boolean;
+/**
+ * The access token has characters a WebSocket subprotocol cannot carry. Retrying cannot help (the
+ * same token comes back), so this is reported once, as final. Fixed text: never includes the token.
+ */
+export declare class InvalidSpeechTokenError extends Error {
+    constructor();
+}
+/** Thrown before any token is read when the speech URL is not allowed (see isSpeechSocketUrlAllowed). */
+export declare class InsecureSpeechUrlError extends Error {
+    constructor();
+}
+/**
+ * WebSocket subprotocol offered on the speech sockets. The Hartren API selects (echoes) only this one;
+ * it never echoes the bearer entry.
+ */
+export declare const SPEECH_WS_PROTOCOL = "hartren.speech.v1";
+/** Prefix of the subprotocol entry that carries the access token: `bearer.<token>`. */
+export declare const SPEECH_WS_BEARER_PREFIX = "bearer.";
+/**
+ * Subprotocols for a speech socket. With a token: [SPEECH_WS_PROTOCOL, 'bearer.<token>'], so the token
+ * travels in the Sec-WebSocket-Protocol header and never in the URL. Without one: none (unchanged
+ * anonymous handshake). Throws (fixed text, no token) when the token has characters a subprotocol
+ * cannot carry.
+ */
+export declare function speechSocketProtocols(token?: string | null): string[];
+/** `code` values on onCopilotError events raised by speech. */
+export declare const SpeechErrorCodes: {
+    /** Deepgram connection failed; a retry is scheduled (`final: false`). */
+    readonly TRANSCRIPTION_RETRYING: "transcription-retrying";
+    /** Deepgram still unavailable after all retries (`final: true`). Dictation stopped. */
+    readonly TRANSCRIPTION_FAILED: "transcription-failed";
+    /** No usable transcription WebSocket URL (none could be determined, or a remote plain ws:// URL was refused). */
+    readonly TRANSCRIPTION_NOT_CONFIGURED: "transcription-not-configured";
+    /** The transcription service sent an error message on an open socket (`final: false`). Its text is in `message`. */
+    readonly TRANSCRIPTION_ERROR: "transcription-error";
+    /** Hosted TTS (/ws/speech/speak) failed. No browser fallback. */
+    readonly TTS_FAILED: "tts-failed";
+    /** Hosted TTS unavailable (no usable WebSocket URL). No browser fallback. */
+    readonly TTS_NOT_CONFIGURED: "tts-not-configured";
+    /** Microphone/VAD setup failed (permission, device). Dictation stopped; no retry. */
+    readonly AUDIO_SETUP_FAILED: "audio-setup-failed";
+    /**
+     * browserTranscriptionFallback only: the hosted socket failed while the browser is online, and
+     * dictation continues with the browser's SpeechRecognition (`final: false`, `reason` says why).
+     */
+    readonly TRANSCRIPTION_FALLBACK: "transcription-fallback";
+    /** browserTranscriptionFallback only: the connection is back and dictation returned to hosted (`final: false`). */
+    readonly TRANSCRIPTION_RESTORED: "transcription-restored";
+    /** speechProvider 'browser' was chosen but this browser has no SpeechRecognition. */
+    readonly BROWSER_SPEECH_UNSUPPORTED: "browser-speech-unsupported";
+};
+export type SpeechErrorCode = (typeof SpeechErrorCodes)[keyof typeof SpeechErrorCodes];

package/dist/debugLog.d.ts

@@ -0,0 +1,9 @@
+export declare function setCopilotDebugLogging(on: boolean): void;
+export declare function isCopilotDebugLogging(): boolean;
+/** Logs only when debug logging is on. Use for any message that includes user or AI text. */
+export declare function debugLog(level: 'log' | 'info' | 'error', ...args: unknown[]): void;
+/**
+ * A safe label for an error: its name or code only, never its message (which can carry text).
+ * HTTP failures are labelled by status code, e.g. `HTTP_500`.
+ */
+export declare function errorLabel(error: unknown): string;

package/dist/enums.d.ts

@@ -0,0 +1,42 @@
+import { SpeechRecognitionFailure } from './MicrophoneAccess/MicrophoneAccess';
+export declare enum SpeechRecognitionError {
+    Network = "network",
+    NotAllowed = "not-allowed",
+    ServiceNotAllowed = "service-not-allowed",
+    Aborted = "aborted",
+    AudioCapture = "audio-capture",
+    LanguageNotSupported = "language-not-supported",
+    BadGrammar = "bad-grammar",
+    NoSpeech = "no-speech",
+    MicDenied = "mic-denied",
+    MicDismissed = "mic-dismissed",
+    MicOsBlocked = "mic-os-blocked",
+    MicPolicyBlocked = "mic-policy-blocked",
+    MicNoDevice = "mic-no-device",
+    MicConstraints = "mic-constraints",
+    MicBusy = "mic-busy",
+    MicUnsupported = "mic-unsupported",
+    MicInsecureContext = "mic-insecure-context",
+    MicFailed = "mic-failed",
+    SessionFailed = "session-failed",
+    SocketFailed = "socket-failed",
+    VadAssetFailed = "vad-asset-failed",
+    EngineUnavailable = "engine-unavailable",
+    AudioSetupFailed = "audio-setup-failed"
+}
+export interface ErrorHandlingConfig {
+    action: "stop" | "restart" | "none";
+    emitEvent?: {
+        message: string;
+        stopAgent?: boolean;
+        asPopup?: boolean;
+        code?: SpeechRecognitionFailure;
+    };
+}
+export declare const ERROR_HANDLING_STRATEGIES: Record<SpeechRecognitionError, ErrorHandlingConfig>;
+export declare enum GeneralErrorMessage {
+    ExecutionError = "An error occurred while executing the function. Please try again or contact support if the issue continues.",
+    UnexpectedError = "An unexpected error occurred. Please try again.",
+    NetworkIssue = "Network connection issue detected. Trying to reconnect...",
+    PermissionDenied = "Microphone access denied. Please enable permissions."
+}

package/dist/httpError.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A failed HTTP response. `code` (`HTTP_<status>`) is what gets logged: it is safe to print, while
+ * response bodies are never read into the error.
+ */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(context: string, status: number);
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import CopilotAgent from './CopilotAgent';
+export { copilotMode, normalizeCopilotMode } from './types';
+export type { CopilotMode } from './types';
+export { speechProvider, SpeechErrorCodes, DEFAULT_SPEECH_RETRY, SPEECH_WS_PROTOCOL } from './SpeechRecognitionService/speechConfig';
+export type { SpeechProvider, SpeechRetryOptions, SpeechErrorCode } from './SpeechRecognitionService/speechConfig';
+export type { CopilotError } from './CopilotAgent/CopilotAgent';
+export { setCopilotDebugLogging, isCopilotDebugLogging } from './debugLog';
+export { HttpError } from './httpError';
+export type { AccessTokenProvider, UnauthorizedHandler } from './CopilotAgent/AuthenticationService';
+export type { SpeechRecognitionFailure, MicrophoneEnvironment, } from './MicrophoneAccess/MicrophoneAccess';
+export { SPEECH_RECOGNITION_FAILURES } from './MicrophoneAccess/MicrophoneAccess';
+export default CopilotAgent;