@omniloy/sofia-sdk 1.0.9 → 1.0.11

package/dist/react/index.d.ts

@@ -3,6 +3,9 @@ import { JSX } from 'react/jsx-runtime';
 import * as React_2 from 'react';
 import { VariantProps } from 'class-variance-authority';
 
+/** Where audio stopped flowing, as reported by the recording pipeline. */
+export declare type AudioLossCause = 'mic' | 'network' | 'server';
+
 export declare function Button({ className, variant, size, asChild, isDisabled, isLoading, text, whitespace, rounded, type, ...props }: ButtonProps): JSX.Element;
 
 declare type ButtonProps = React_2.ComponentProps<'button'> & VariantProps<typeof buttonVariants> & {
@@ -15,8 +18,8 @@ declare type ButtonProps = React_2.ComponentProps<'button'> & VariantProps<typeo
 };
 
 declare const buttonVariants: (props?: ({
-    variant?: "report" | "default" | "icon" | "destructive" | "outline" | "secondary" | "ghost" | "empty" | "primary" | null | undefined;
-    size?: "default" | "icon" | "padding" | "empty" | "sm" | "lg" | null | undefined;
+    variant?: "report" | "default" | "destructive" | "outline" | "secondary" | "ghost" | "empty" | "primary" | "icon" | null | undefined;
+    size?: "default" | "empty" | "icon" | "sm" | "lg" | "padding" | null | undefined;
 } & ClassProp) | undefined) => string;
 
 declare interface CuratedReport {
@@ -63,6 +66,11 @@ declare interface InsertionPreviewClassNames {
     cancelButton?: string;
 }
 
+/** Coarse area of the widget the clinician touched. */
+export declare type InteractionKind = 'recording' | 'chat' | 'settings' | 'report' | 'transcript' | 'history' | 'widget';
+
+export 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';
+
 export declare enum LanguageCode {
     ar = "ar",
     ca = "ca",
@@ -252,8 +260,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[];
 }
 
+export declare type RecordingMode = 'consultation' | 'dictation';
+
+export 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.
+ */
+export declare type SdkEventFamily = 'recording' | 'activity' | 'report' | 'lifecycle';
+
+/** Handler shape for the `onEvent` prop. */
+export 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`.
+ */
+export declare type SdkEventName = KnownSdkEventName | (string & {});
+
+declare type SdkEventPayload<N extends SdkEventName> = N extends KnownSdkEventName ? SdkEventPayloadMap[N] : Record<string, unknown>;
+
+export 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 (`'*'`).
+ */
+export declare type SdkEventSubscription = KnownSdkEventName | `${SdkEventFamily}.*` | '*';
+
 /**
  * Get a value from local storage (decrypted)
  * @param key - The key to get the value from
@@ -333,6 +485,9 @@ declare type TTranscriptorSelect = {
     label: string;
 }[];
 
+/** Which free-text surface received keystrokes. Never the text itself. */
+export 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: '...',