@omniloy/sofia-sdk 1.0.9 → 1.0.11

package/dist/legacy/webcomponents.d.ts

@@ -1,5 +1,8 @@
 import * as React_2 from 'react';
 
+/** Where audio stopped flowing, as reported by the recording pipeline. */
+declare type AudioLossCause = 'mic' | 'network' | 'server';
+
 declare interface CuratedReport {
     [key: string]: unknown;
 }
@@ -42,6 +45,11 @@ declare interface InsertionPreviewClassNames {
     cancelButton?: string;
 }
 
+/** Coarse area of the widget the clinician touched. */
+declare type InteractionKind = 'recording' | 'chat' | 'settings' | 'report' | 'transcript' | 'history' | 'widget';
+
+declare type KnownSdkEventName = 'recording.started' | 'recording.stopped' | 'recording.audio_lost' | 'recording.microphone_disconnected' | 'recording.heartbeat' | 'activity.interaction' | 'activity.typing' | 'report.generation_started' | 'report.settled' | 'lifecycle.ready' | 'lifecycle.closed';
+
 declare enum LanguageCode {
     ar = "ar",
     ca = "ca",
@@ -218,8 +226,152 @@ export declare interface OmniscribeProps {
      * the appropriate action. To change the delivered shape, change templateExtras.
      */
     handleExtras?: (extras: Extra[]) => void;
+    /**
+     * Subscribe to the SDK's activity stream.
+     *
+     * Called with a typed, PHI-free event whenever something the host asked
+     * for happens inside the widget. Payloads carry only enums, booleans and
+     * numbers — never clinical content, message text or patient identifiers.
+     * Clinical content has its own explicitly scoped channels (`handleReport`,
+     * `onReportApply`, `handleExtras`).
+     *
+     * The primary use case is knowing whether the clinician is working, so the
+     * host can run an inactivity timeout:
+     * ```
+     * onEvent={e => {
+     *   if (e.name === 'recording.started') idleTimer.cancel();
+     *   if (e.name === 'recording.stopped') idleTimer.start();
+     *   if (e.family === 'activity') idleTimer.reset();
+     * }}
+     * ```
+     * Suppress the timer between `report.generation_started` and
+     * `report.settled` — generation runs for tens of seconds with no user
+     * input, and closing the widget there loses the note.
+     *
+     * If the host must keep an *external* session alive (an auto-logout on
+     * inactivity), key off `recording.heartbeat` instead of the
+     * `started`/`stopped` pair. It beats every ~30s while audio is actually
+     * flowing to the transcriber, needs no host-side state, and stops by
+     * itself the moment a recording silently breaks:
+     * ```
+     * onEvent={e => {
+     *   if (e.name === 'recording.heartbeat') session.keepAlive();
+     * }}
+     * ```
+     *
+     * Delivered asynchronously on a microtask, so a slow handler cannot block
+     * recording. Requires `eventSubscriptions`; without it nothing is sent.
+     */
+    onEvent?: SdkEventHandler;
+    /**
+     * Which events `onEvent` should receive. Exact names
+     * (`'recording.started'`), family wildcards (`'recording.*'`), or `'*'`.
+     *
+     * Omitted or empty means no events are delivered — subscription is
+     * explicit so the SDK never does work for a listener that does not exist.
+     */
+    eventSubscriptions?: SdkEventSubscription[];
 }
 
+declare type RecordingMode = 'consultation' | 'dictation';
+
+declare interface SdkEvent<N extends SdkEventName = SdkEventName> {
+    /** Fully qualified name, e.g. `'recording.started'`. */
+    name: N;
+    /** The part of `name` before the dot. */
+    family: SdkEventFamily;
+    level: 'info' | 'warn' | 'error';
+    /** ISO-8601. */
+    ts: string;
+    /**
+     * Monotonic per page load. Restores ordering that the fire-and-forget
+     * analytics POSTs cannot guarantee.
+     */
+    seq: number;
+    sdkVersion: string;
+    /** Random per-session UUID. Not an identifier for a person. */
+    sessionId: string | null;
+    payload: SdkEventPayload<N>;
+}
+
+/**
+ * Public, host-facing SDK event vocabulary.
+ *
+ * PRIVACY INVARIANT — read before adding an event.
+ * No payload field may carry user-, patient-, or clinician-derived text.
+ * Every field is a string-literal union, a boolean, or a number. Errors
+ * travel as codes, never as messages; reports as counts, never as content.
+ * A host that needs clinical content already has purpose-built, explicitly
+ * scoped channels for it (`handleReport`, `onReportApply`, `handleExtras`).
+ * `sdk-events.types.test.ts` fails the build if an unconstrained `string`
+ * appears in `SdkEventPayloadMap`.
+ *
+ * This vocabulary is deliberately separate from the internal analytics
+ * `AppEventName`. Merging them would make every internal telemetry addition
+ * a public breaking change.
+ */
+declare type SdkEventFamily = 'recording' | 'activity' | 'report' | 'lifecycle';
+
+/** Handler shape for the `onEvent` prop. */
+declare type SdkEventHandler = (event: SdkEvent) => void;
+
+/**
+ * Widened on purpose. New event names ship in minor releases, and a closed
+ * union would make every addition a type-level break for hosts that switch
+ * exhaustively. Hosts wanting exhaustiveness narrow to `KnownSdkEventName`.
+ */
+declare type SdkEventName = KnownSdkEventName | (string & {});
+
+declare type SdkEventPayload<N extends SdkEventName> = N extends KnownSdkEventName ? SdkEventPayloadMap[N] : Record<string, unknown>;
+
+declare interface SdkEventPayloadMap {
+    'recording.started': {
+        mode: RecordingMode;
+    };
+    'recording.stopped': {
+        mode: RecordingMode;
+        durationSeconds: number;
+    };
+    'recording.audio_lost': {
+        cause: AudioLossCause;
+        /**
+         * For `mic` / `network`: length of the gap, reported once audio
+         * recovers. For `server`: the recording position at which the socket
+         * closed — capture is torn down on the spot, so there is no gap to
+         * measure.
+         */
+        durationSeconds: number;
+    };
+    'recording.microphone_disconnected': Record<string, never>;
+    /**
+     * Audio is actually flowing to the transcriber. Emitted from the
+     * audio-chunk send path, throttled — see `recording-heartbeat.ts`.
+     * A host that must keep an external session alive while the clinician
+     * records should key off this, not off `started`/`stopped`: it needs no
+     * host-side state and stops by itself the moment a recording silently
+     * breaks.
+     */
+    'recording.heartbeat': Record<string, never>;
+    'activity.interaction': {
+        kind: InteractionKind;
+    };
+    'activity.typing': {
+        surface: TypingSurface;
+    };
+    'report.generation_started': Record<string, never>;
+    'report.settled': {
+        ok: boolean;
+    };
+    'lifecycle.ready': Record<string, never>;
+    'lifecycle.closed': Record<string, never>;
+}
+
+/**
+ * What a host asks for: an exact name, a family wildcard (`'recording.*'`),
+ * or everything (`'*'`).
+ */
+declare type SdkEventSubscription = KnownSdkEventName | `${SdkEventFamily}.*` | '*';
+
 export declare const SofiaSDK: CustomElementConstructor;
 
 declare enum ToastVariation {
@@ -242,6 +394,9 @@ declare type TTranscriptorSelect = {
     label: string;
 }[];
 
+/** Which free-text surface received keystrokes. Never the text itself. */
+declare type TypingSurface = 'chat' | 'note';
+
 /**
  * Host-provided callback that returns whatever the doctor has already written
  * in SINA/HIS, keyed by template property id (e.g. `{ chief_complaint: '...',