@appilots/web-sdk 0.2.0 → 0.3.0

package/dist/{AppilotsWebRuntime-DZF26UyU.d.mts → webSpeechHost-CrTKADeb.d.mts}

@@ -391,6 +391,13 @@ interface AppilotsClientOptions {
      * id. Identifiers are dashboard-only — never sent to the LLM.
      */
     user?: AppilotsUser;
+    /**
+     * Accessibility: ask the agent to reply in plain language (short
+     * sentences, everyday words, numbered steps). `undefined` defers to the
+     * project setting in the dashboard; `true`/`false` overrides it for this
+     * session. Change it later with `setPlainLanguage`.
+     */
+    plainLanguage?: boolean;
 }
 interface AppilotsUser {
     /** The app's own user id (matches your backend). */
@@ -455,6 +462,8 @@ interface SendMessageContext {
     missionId?: string;
     /** Supported device language, independent of the app/map/visible UI locale. */
     deviceLocale?: SupportedAppilotsLocale;
+    /** Set by the client from `plainLanguage` / `setPlainLanguage`; see there. */
+    plainLanguage?: boolean;
     /**
      * Which client platform this observation came from — `'react-native'`,
      * `'web'`, `'android'`, `'ios'`, or any other client-defined string.
@@ -509,6 +518,7 @@ declare class AppilotsClient {
     private readonly mcpVersion;
     private readonly introspectionReporter;
     private readonly user;
+    private plainLanguage;
     private sessionId;
     private mission;
     private missionDispatchPaused;
@@ -549,6 +559,14 @@ declare class AppilotsClient {
      * must not take the message down with it.
      */
     private introspectionFragment;
+    /**
+     * Per-session plain-language override — e.g. from the signed-in user's
+     * accessibility profile. `undefined` hands the decision back to the
+     * project setting. Applies from the next request on.
+     */
+    setPlainLanguage(value: boolean | undefined): void;
+    /** Every relay-bound context carries the reply-style preference. */
+    private withPreferences;
     sendMessage(content: string, context?: SendMessageContext): Promise<SendMessageResponse>;
     /**
      * Streaming variant of `sendMessage` — consumes the server's SSE
@@ -733,6 +751,87 @@ declare class AppilotsClient {
     }): () => void;
 }
 
+/**
+ * The speech seam.
+ *
+ * The SDK ships no speech engine and never will. Every usable one on
+ * React Native is a native module — `@react-native-voice/voice`,
+ * `expo-speech-recognition`, a vendor SDK — and a dependency here would
+ * force native linking on every integrator, including the majority who
+ * will never turn voice on. Worse, it would pick their engine for them:
+ * the right one depends on the locale they need, whether recognition
+ * may leave the device, and what their app store review already covers.
+ *
+ * So this is an interface and nothing else, injected the same way
+ * `GeometryHost` and the `Alert` in `confirmedDestructiveAlert` are.
+ * Pass an adapter and the mic button appears; pass nothing and
+ * `resolveExperience` reports `input: 'voice'` as an unmet request
+ * rather than rendering a button that does nothing.
+ *
+ * It lives in client-core because the web SDK takes the same contract:
+ * its built-in Web Speech engine is one implementation of it, and a
+ * host that needs recognition to stay on-device (or a vendor engine)
+ * passes its own.
+ *
+ * Everything here is transcription only. Playing audio back is not
+ * modelled, because nothing in the loop produces audio.
+ */
+/** What the SDK needs to run a mic button (hold-to-talk or toggle). */
+interface SpeechHost {
+    /**
+     * Begin listening. Resolve once capture is actually running, so the
+     * UI can wait before telling the user to speak.
+     *
+     * Implementations own permissions: if the OS prompt has not been
+     * accepted, request it here and reject when refused.
+     */
+    start(options: SpeechStartOptions): Promise<void>;
+    /**
+     * Stop listening and resolve with the final transcript.
+     *
+     * Resolving with an empty string is the normal outcome for "the user
+     * pressed and said nothing" — it must not reject for that.
+     */
+    stop(): Promise<string>;
+    /** Abandon the capture. No transcript, no error. */
+    cancel(): Promise<void>;
+    /**
+     * Partial results while the user is still talking, if the engine has
+     * them. Return a disposer. Optional — a host without interim results
+     * simply shows the placeholder until `stop` resolves.
+     */
+    onPartial?(listener: (text: string) => void): () => void;
+    /**
+     * The engine ended the capture on its own — silence timeout, lost
+     * permission, network — without `stop` or `cancel` being called.
+     * `error` is set when it ended by failure. Return a disposer.
+     *
+     * Optional, but without it a UI cannot leave `listening` until the
+     * user presses again: the button would claim to record while the
+     * engine is not.
+     */
+    onEnd?(listener: (error?: unknown) => void): () => void;
+}
+interface SpeechStartOptions {
+    /**
+     * BCP-47 tag resolved from the chat's locale, so a pt-BR chat does
+     * not transcribe against a US English model. Hosts that only support
+     * one locale may ignore it.
+     */
+    locale: string;
+}
+/** Where a mic button is in its cycle. */
+type SpeechState = 'idle' | 'starting' | 'listening' | 'stopping' | 'error';
+/**
+ * Is this object usable as a host?
+ *
+ * Checked at the boundary rather than trusted from the type, because
+ * the value crosses from the host app's JavaScript — where it may have
+ * come from a config file, a lazy import that failed, or a version of
+ * an adapter predating a method.
+ */
+declare function isSpeechHost(value: unknown): value is SpeechHost;
+
 type ActionFailureCategory = 'component-not-found' | 'disabled' | 'validation' | 'network-5xx' | 'network-4xx' | 'screen-timeout' | 'ambiguous-target' | 'unknown';
 interface ActionDiagnose {
     category: ActionFailureCategory;
@@ -1312,7 +1411,17 @@ interface AppilotsWebRuntimeOptions {
     apiKey?: string;
     apiBaseUrl?: string;
     debug?: boolean;
+    /**
+     * How long (ms) the client waits for the assistant before giving up on
+     * a request, and how long a reply stream may stay silent. Default
+     * 60000; agent continuations always get at least 150000. Raise it for
+     * users or networks that need more time — the user's message stays in
+     * the transcript either way.
+     */
+    timeout?: number;
     appVersion?: string;
+    /** Plain-language replies for this session; omit to follow the dashboard. */
+    plainLanguage?: boolean;
     mcpVersion?: string;
     user?: {
         id: string;
@@ -1386,4 +1495,21 @@ declare class AppilotsWebRuntime {
     private screenActionsFor;
 }
 
-export { type AgentAction as A, type ControlEvidence as C, type EscalationState as E, RateLimitedError as R, type ScreenActionMetadataLike as S, WebNavigationAdapter as W, type AppilotsLocale as a, type AgentPermissions as b, type AppilotsEvent as c, type ActionExecutionResult as d, type ActionDiagnose as e, ActionQueueMachine as f, type AgentActionType as g, AppilotsClient as h, type AppilotsEventHandler as i, AppilotsWebRuntime as j, type AppilotsWebRuntimeOptions as k, type ChatMessage as l, ChatSessionMachine as m, type ChatSessionOptions as n, type ChatSessionState as o, type EscalationStrings as p, type WebNavigationAdapterOptions as q, type WebNavigationState as r, type WebRoute as s, type WebScreenMetadata as t, buildPath as u, matchRoute as v };
+/**
+ * A `SpeechHost` over the browser's Web Speech API.
+ *
+ * Opt-in and dependency-free: `createWebSpeechHost()` returns null when
+ * the browser has no `SpeechRecognition` (Firefox, most WebViews), and
+ * the chat hides the mic instead of rendering a button that fails.
+ *
+ * Privacy: in Chrome and Edge the audio is streamed to the vendor's
+ * speech service — it leaves the device. Safari may recognise on-device
+ * or on Apple's servers. Nothing here can make that local; a host that
+ * needs it passes its own `SpeechHost`. See guides/voice-input in the docs.
+ */
+
+declare function isWebSpeechSupported(): boolean;
+/** Null when the browser has no speech recognition. */
+declare function createWebSpeechHost(): SpeechHost | null;
+
+export { type AgentAction as A, isWebSpeechSupported as B, type ControlEvidence as C, matchRoute as D, type EscalationState as E, type MissionView as M, RateLimitedError as R, type ScreenActionMetadataLike as S, WebNavigationAdapter as W, type AppilotsLocale as a, type AgentPermissions as b, type AppilotsEvent as c, type ActionExecutionResult as d, type ActionDiagnose as e, ActionQueueMachine as f, type AgentActionType as g, AppilotsClient as h, type AppilotsEventHandler as i, AppilotsWebRuntime as j, type AppilotsWebRuntimeOptions as k, type ChatMessage as l, ChatSessionMachine as m, type ChatSessionOptions as n, type ChatSessionState as o, type EscalationStrings as p, type SpeechHost as q, type SpeechStartOptions as r, type SpeechState as s, type WebNavigationAdapterOptions as t, type WebNavigationState as u, type WebRoute as v, type WebScreenMetadata as w, buildPath as x, createWebSpeechHost as y, isSpeechHost as z };

package/dist/{AppilotsWebRuntime-DZF26UyU.d.ts → webSpeechHost-CrTKADeb.d.ts}

@@ -391,6 +391,13 @@ interface AppilotsClientOptions {
      * id. Identifiers are dashboard-only — never sent to the LLM.
      */
     user?: AppilotsUser;
+    /**
+     * Accessibility: ask the agent to reply in plain language (short
+     * sentences, everyday words, numbered steps). `undefined` defers to the
+     * project setting in the dashboard; `true`/`false` overrides it for this
+     * session. Change it later with `setPlainLanguage`.
+     */
+    plainLanguage?: boolean;
 }
 interface AppilotsUser {
     /** The app's own user id (matches your backend). */
@@ -455,6 +462,8 @@ interface SendMessageContext {
     missionId?: string;
     /** Supported device language, independent of the app/map/visible UI locale. */
     deviceLocale?: SupportedAppilotsLocale;
+    /** Set by the client from `plainLanguage` / `setPlainLanguage`; see there. */
+    plainLanguage?: boolean;
     /**
      * Which client platform this observation came from — `'react-native'`,
      * `'web'`, `'android'`, `'ios'`, or any other client-defined string.
@@ -509,6 +518,7 @@ declare class AppilotsClient {
     private readonly mcpVersion;
     private readonly introspectionReporter;
     private readonly user;
+    private plainLanguage;
     private sessionId;
     private mission;
     private missionDispatchPaused;
@@ -549,6 +559,14 @@ declare class AppilotsClient {
      * must not take the message down with it.
      */
     private introspectionFragment;
+    /**
+     * Per-session plain-language override — e.g. from the signed-in user's
+     * accessibility profile. `undefined` hands the decision back to the
+     * project setting. Applies from the next request on.
+     */
+    setPlainLanguage(value: boolean | undefined): void;
+    /** Every relay-bound context carries the reply-style preference. */
+    private withPreferences;
     sendMessage(content: string, context?: SendMessageContext): Promise<SendMessageResponse>;
     /**
      * Streaming variant of `sendMessage` — consumes the server's SSE
@@ -733,6 +751,87 @@ declare class AppilotsClient {
     }): () => void;
 }
 
+/**
+ * The speech seam.
+ *
+ * The SDK ships no speech engine and never will. Every usable one on
+ * React Native is a native module — `@react-native-voice/voice`,
+ * `expo-speech-recognition`, a vendor SDK — and a dependency here would
+ * force native linking on every integrator, including the majority who
+ * will never turn voice on. Worse, it would pick their engine for them:
+ * the right one depends on the locale they need, whether recognition
+ * may leave the device, and what their app store review already covers.
+ *
+ * So this is an interface and nothing else, injected the same way
+ * `GeometryHost` and the `Alert` in `confirmedDestructiveAlert` are.
+ * Pass an adapter and the mic button appears; pass nothing and
+ * `resolveExperience` reports `input: 'voice'` as an unmet request
+ * rather than rendering a button that does nothing.
+ *
+ * It lives in client-core because the web SDK takes the same contract:
+ * its built-in Web Speech engine is one implementation of it, and a
+ * host that needs recognition to stay on-device (or a vendor engine)
+ * passes its own.
+ *
+ * Everything here is transcription only. Playing audio back is not
+ * modelled, because nothing in the loop produces audio.
+ */
+/** What the SDK needs to run a mic button (hold-to-talk or toggle). */
+interface SpeechHost {
+    /**
+     * Begin listening. Resolve once capture is actually running, so the
+     * UI can wait before telling the user to speak.
+     *
+     * Implementations own permissions: if the OS prompt has not been
+     * accepted, request it here and reject when refused.
+     */
+    start(options: SpeechStartOptions): Promise<void>;
+    /**
+     * Stop listening and resolve with the final transcript.
+     *
+     * Resolving with an empty string is the normal outcome for "the user
+     * pressed and said nothing" — it must not reject for that.
+     */
+    stop(): Promise<string>;
+    /** Abandon the capture. No transcript, no error. */
+    cancel(): Promise<void>;
+    /**
+     * Partial results while the user is still talking, if the engine has
+     * them. Return a disposer. Optional — a host without interim results
+     * simply shows the placeholder until `stop` resolves.
+     */
+    onPartial?(listener: (text: string) => void): () => void;
+    /**
+     * The engine ended the capture on its own — silence timeout, lost
+     * permission, network — without `stop` or `cancel` being called.
+     * `error` is set when it ended by failure. Return a disposer.
+     *
+     * Optional, but without it a UI cannot leave `listening` until the
+     * user presses again: the button would claim to record while the
+     * engine is not.
+     */
+    onEnd?(listener: (error?: unknown) => void): () => void;
+}
+interface SpeechStartOptions {
+    /**
+     * BCP-47 tag resolved from the chat's locale, so a pt-BR chat does
+     * not transcribe against a US English model. Hosts that only support
+     * one locale may ignore it.
+     */
+    locale: string;
+}
+/** Where a mic button is in its cycle. */
+type SpeechState = 'idle' | 'starting' | 'listening' | 'stopping' | 'error';
+/**
+ * Is this object usable as a host?
+ *
+ * Checked at the boundary rather than trusted from the type, because
+ * the value crosses from the host app's JavaScript — where it may have
+ * come from a config file, a lazy import that failed, or a version of
+ * an adapter predating a method.
+ */
+declare function isSpeechHost(value: unknown): value is SpeechHost;
+
 type ActionFailureCategory = 'component-not-found' | 'disabled' | 'validation' | 'network-5xx' | 'network-4xx' | 'screen-timeout' | 'ambiguous-target' | 'unknown';
 interface ActionDiagnose {
     category: ActionFailureCategory;
@@ -1312,7 +1411,17 @@ interface AppilotsWebRuntimeOptions {
     apiKey?: string;
     apiBaseUrl?: string;
     debug?: boolean;
+    /**
+     * How long (ms) the client waits for the assistant before giving up on
+     * a request, and how long a reply stream may stay silent. Default
+     * 60000; agent continuations always get at least 150000. Raise it for
+     * users or networks that need more time — the user's message stays in
+     * the transcript either way.
+     */
+    timeout?: number;
     appVersion?: string;
+    /** Plain-language replies for this session; omit to follow the dashboard. */
+    plainLanguage?: boolean;
     mcpVersion?: string;
     user?: {
         id: string;
@@ -1386,4 +1495,21 @@ declare class AppilotsWebRuntime {
     private screenActionsFor;
 }
 
-export { type AgentAction as A, type ControlEvidence as C, type EscalationState as E, RateLimitedError as R, type ScreenActionMetadataLike as S, WebNavigationAdapter as W, type AppilotsLocale as a, type AgentPermissions as b, type AppilotsEvent as c, type ActionExecutionResult as d, type ActionDiagnose as e, ActionQueueMachine as f, type AgentActionType as g, AppilotsClient as h, type AppilotsEventHandler as i, AppilotsWebRuntime as j, type AppilotsWebRuntimeOptions as k, type ChatMessage as l, ChatSessionMachine as m, type ChatSessionOptions as n, type ChatSessionState as o, type EscalationStrings as p, type WebNavigationAdapterOptions as q, type WebNavigationState as r, type WebRoute as s, type WebScreenMetadata as t, buildPath as u, matchRoute as v };
+/**
+ * A `SpeechHost` over the browser's Web Speech API.
+ *
+ * Opt-in and dependency-free: `createWebSpeechHost()` returns null when
+ * the browser has no `SpeechRecognition` (Firefox, most WebViews), and
+ * the chat hides the mic instead of rendering a button that fails.
+ *
+ * Privacy: in Chrome and Edge the audio is streamed to the vendor's
+ * speech service — it leaves the device. Safari may recognise on-device
+ * or on Apple's servers. Nothing here can make that local; a host that
+ * needs it passes its own `SpeechHost`. See guides/voice-input in the docs.
+ */
+
+declare function isWebSpeechSupported(): boolean;
+/** Null when the browser has no speech recognition. */
+declare function createWebSpeechHost(): SpeechHost | null;
+
+export { type AgentAction as A, isWebSpeechSupported as B, type ControlEvidence as C, matchRoute as D, type EscalationState as E, type MissionView as M, RateLimitedError as R, type ScreenActionMetadataLike as S, WebNavigationAdapter as W, type AppilotsLocale as a, type AgentPermissions as b, type AppilotsEvent as c, type ActionExecutionResult as d, type ActionDiagnose as e, ActionQueueMachine as f, type AgentActionType as g, AppilotsClient as h, type AppilotsEventHandler as i, AppilotsWebRuntime as j, type AppilotsWebRuntimeOptions as k, type ChatMessage as l, ChatSessionMachine as m, type ChatSessionOptions as n, type ChatSessionState as o, type EscalationStrings as p, type SpeechHost as q, type SpeechStartOptions as r, type SpeechState as s, type WebNavigationAdapterOptions as t, type WebNavigationState as u, type WebRoute as v, type WebScreenMetadata as w, buildPath as x, createWebSpeechHost as y, isSpeechHost as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appilots/web-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Appilots client for web applications: DOM/ARIA introspection, DOM action execution, and a thin React binding — framework-agnostic (React, Vue, vanilla)",
   "main": "dist/index.js",
   "module": "dist/index.mjs",