screenreader-speech-capture-client 0.0.1-preview.0 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,203 @@
1
+ import { C as BridgeStatus, D as SessionRef, E as SessionList, O as StartedSession, S as BridgeState, T as Session, _ as SpeechCapture, a as PressKeysOptions, b as SpeechMatch, c as FocusError, d as GetSpeechOptions, f as GetTextOptions, g as SilenceOptions, h as Recording, i as NativeInput, l as MouseButton, m as ReadyOptions, n as FocusTarget, o as SetFocusOptions, p as OnSpeechOptions, r as FocusablePage, s as ElementBox, t as ClickOptions, u as ScreenPoint, v as StartSessionOptions, w as ServiceStatus, x as SpeechEntry, y as WaitOptions } from "./native-input-BpZjLyPk.mjs";
2
+ /** Bridge URL used when nothing else is configured. */
3
+ export declare const DEFAULT_BRIDGE_URL = "http://localhost:5151";
4
+ /** Environment variable with the bridge URL. */
5
+ export declare const URL_ENV = "SR_SPEECH_URL";
6
+ /** Where the effective value came from, highest precedence first. */
7
+ type ValueSource = 'explicit' | 'env' | 'config' | 'default';
8
+ /**
9
+ * Checks a bridge URL and returns it normalised: only `http:` / `https:`, no trailing slash, so
10
+ * API paths can be appended directly.
11
+ */
12
+ export declare function normalizeBridgeUrl(input: string, origin?: string): string;
13
+ /** Settings stored in the client's config file. */
14
+ interface ClientConfig {
15
+ url?: string;
16
+ }
17
+ /** Keys the client config stores, each with the check that normalises a value before saving. */
18
+ declare const CONFIG_KEYS: {
19
+ readonly url: (value: string) => string;
20
+ };
21
+ type ConfigKey = keyof typeof CONFIG_KEYS;
22
+ /** Values passed for this call only (`--url`, `baseUrl`). They win over everything else. */
23
+ type ExplicitValues = Partial<Record<ConfigKey, string | undefined>>;
24
+ interface ConfigValue {
25
+ key: ConfigKey;
26
+ /** The effective value. */
27
+ value: string;
28
+ source: ValueSource;
29
+ }
30
+ interface SetResult {
31
+ key: ConfigKey;
32
+ /** The value as saved, normalised. */
33
+ value: string;
34
+ /** Set when a higher source hides the saved value (today: `SR_SPEECH_URL`). */
35
+ shadowedBy?: 'env';
36
+ }
37
+ /** Read and change the client's per-user settings (docs/usage/client.md#bridge-url). */
38
+ interface ManageClientConfig {
39
+ /** Where the settings are stored, for messages and `config path`. */
40
+ readonly location: string;
41
+ /**
42
+ * The effective value and where it comes from. The store is only read when nothing with a
43
+ * higher precedence is set. Rejects with `ClientConfigError` for an unknown key, an invalid
44
+ * value or a broken store.
45
+ */
46
+ get(key: string, explicit?: ExplicitValues): Promise<ConfigValue>;
47
+ /** {@link get} for every key. */
48
+ list(explicit?: ExplicitValues): Promise<ConfigValue[]>;
49
+ /** Checks, normalises and saves a value. */
50
+ set(key: string, value: string): Promise<SetResult>;
51
+ /** Removes a saved value. */
52
+ unset(key: string): Promise<{
53
+ key: ConfigKey;
54
+ }>;
55
+ }
56
+ /** Environment variable that points the client at a different config file. */
57
+ export declare const CONFIG_PATH_ENV = "SR_SPEECH_CLIENT_CONFIG";
58
+ /**
59
+ * The client's config file: `%APPDATA%\screenreader-speech-capture\client.json` on Windows,
60
+ * `$XDG_CONFIG_HOME` (or `~/.config`) + `screenreader-speech-capture/client.json` on Linux and
61
+ * macOS. It sits next to the bridge's `config.json` (both come from `appDir('config')` in
62
+ * `packages/shared`) but is a separate file, so a bridge and a client on the same machine never
63
+ * share settings. `SR_SPEECH_CLIENT_CONFIG` overrides the path.
64
+ */
65
+ export declare function clientConfigFile(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv, home?: string): string;
66
+ /**
67
+ * The client's per-user settings, stored in the config file (docs/usage/client.md#bridge-url).
68
+ * `SR_SPEECH_URL` and `SR_SPEECH_CLIENT_CONFIG` are read from `env` once, here.
69
+ */
70
+ export declare function createClientConfig(env?: NodeJS.ProcessEnv): ManageClientConfig;
71
+ interface SpeechCaptureClientOptions {
72
+ /**
73
+ * Bridge URL, for example `http://my-test-vm:5151`. Default: `SR_SPEECH_URL`, then the client
74
+ * config file, then `http://localhost:5151` (docs/usage/client.md#bridge-url).
75
+ */
76
+ baseUrl?: string | undefined;
77
+ /** Where `SR_SPEECH_URL` and `SR_SPEECH_CLIENT_CONFIG` are read. Default `process.env`. */
78
+ env?: NodeJS.ProcessEnv;
79
+ /**
80
+ * Names this client to the bridge, which warns when one client ends or replaces another one's
81
+ * session (two clients sharing one screen reader). Default: `<host> pid <process id>`.
82
+ */
83
+ clientName?: string | undefined;
84
+ }
85
+ /**
86
+ * Talks to the bridge (docs/usage/client.md#library): `new SpeechCaptureClient()` uses the stored
87
+ * bridge URL. The URL is resolved on the first request.
88
+ *
89
+ * Wraps the service instead of extending it, so the service's internals stay out of the public
90
+ * type surface (docs/implementation/architecture.md).
91
+ */
92
+ export declare class SpeechCaptureClient implements SpeechCapture, NativeInput {
93
+ #private;
94
+ constructor(options?: SpeechCaptureClientOptions);
95
+ click(point: ScreenPoint, options?: ClickOptions): Promise<void>;
96
+ pressKeys(keys: string | readonly string[], options?: PressKeysOptions): Promise<void>;
97
+ setFocus(page: FocusablePage, options?: SetFocusOptions): Promise<void>;
98
+ /** WebSocket URL of the bridge's Playwright server, for `browserType.connect()`. */
99
+ playwrightEndpoint(): Promise<string>;
100
+ getSpeech(options?: GetSpeechOptions): Promise<SpeechEntry[]>;
101
+ getText(options?: GetTextOptions): Promise<string>;
102
+ clear(): Promise<void>;
103
+ startSession(name: string, options?: StartSessionOptions): Promise<StartedSession>;
104
+ endSession(): Promise<void>;
105
+ sessions(): Promise<SessionList>;
106
+ mark(label: string): Promise<SpeechEntry>;
107
+ status(): Promise<BridgeStatus>;
108
+ waitForReady(options?: ReadyOptions): Promise<BridgeStatus>;
109
+ waitForOutput(match: SpeechMatch, options?: WaitOptions): Promise<SpeechEntry>;
110
+ waitForSequence(matches: readonly SpeechMatch[], options?: WaitOptions): Promise<SpeechEntry[]>;
111
+ waitForSilence(options?: SilenceOptions): Promise<void>;
112
+ record<T>(fn: () => T | Promise<T>, options?: SilenceOptions): Promise<Recording<T>>;
113
+ onSpeech(listener: (entry: SpeechEntry) => void, options?: OnSpeechOptions): () => void;
114
+ cursor(): number;
115
+ setCursor(seq: number): void;
116
+ }
117
+ /**
118
+ * A wait ended without a match. `entries` holds the speech seen while waiting, oldest first.
119
+ * `truncated`: some of the speech it should have looked at was dropped because the bridge's
120
+ * buffer was full, so the match may have been among it.
121
+ */
122
+ export declare class SpeechTimeoutError extends Error {
123
+ readonly entries: SpeechEntry[];
124
+ readonly truncated: boolean;
125
+ name: string;
126
+ constructor(message: string, entries: SpeechEntry[], truncated?: boolean);
127
+ }
128
+ /**
129
+ * `getSpeech` / `getText` without `allowTruncated`: some of the speech asked for was dropped
130
+ * because the bridge's buffer was full, so the read would be incomplete. `entries` holds what is
131
+ * left, oldest first.
132
+ */
133
+ export declare class SpeechTruncatedError extends Error {
134
+ /** The `since` of the read. */
135
+ readonly since: number;
136
+ readonly entries: SpeechEntry[];
137
+ name: string;
138
+ constructor(
139
+ /** The `since` of the read. */
140
+ since: number, entries: SpeechEntry[]);
141
+ }
142
+ /** `waitForReady` timed out: the bridge was not reachable or not `ready` in time. */
143
+ export declare class BridgeNotReadyError extends Error {
144
+ name: string;
145
+ }
146
+ /** The bridge speaks another major version of the HTTP API (docs/usage/http-api.md#versioning). */
147
+ export declare class IncompatibleBridgeError extends Error {
148
+ /** `bridge.apiVersion` reported by the bridge. */
149
+ readonly bridgeApiVersion: string;
150
+ /** The API version this client was built for. */
151
+ readonly clientApiVersion: string;
152
+ name: string;
153
+ constructor(
154
+ /** `bridge.apiVersion` reported by the bridge. */
155
+ bridgeApiVersion: string,
156
+ /** The API version this client was built for. */
157
+ clientApiVersion: string);
158
+ }
159
+ /** No connection to the bridge (wrong URL, bridge not running, network). */
160
+ export declare class BridgeUnreachableError extends Error {
161
+ readonly url: string;
162
+ name: string;
163
+ constructor(url: string, options?: ErrorOptions);
164
+ }
165
+ /** The bridge answered with an error (docs/usage/http-api.md#errors). */
166
+ export declare class BridgeHttpError extends Error {
167
+ readonly status: number;
168
+ /** Machine-readable code, for example `INVALID_REQUEST`. New codes may appear. */
169
+ readonly code: string;
170
+ readonly details?: Record<string, unknown> | undefined;
171
+ name: string;
172
+ constructor(status: number,
173
+ /** Machine-readable code, for example `INVALID_REQUEST`. New codes may appear. */
174
+ code: string, message: string, details?: Record<string, unknown> | undefined);
175
+ }
176
+ /** The config file or a configured value is invalid. */
177
+ export declare class ClientConfigError extends Error {
178
+ name: string;
179
+ }
180
+ /**
181
+ * One event of the live feed (`GET /api/v1/speech/stream`): a new entry, a clear, a session
182
+ * that started or ended, or `truncated` before a replay when some missed entries were already
183
+ * dropped from the bridge's buffer.
184
+ */
185
+ type SpeechFeedEvent = {
186
+ type: 'entry';
187
+ entry: SpeechEntry;
188
+ } | {
189
+ type: 'clear';
190
+ } | {
191
+ type: 'session';
192
+ session: Session;
193
+ } | {
194
+ type: 'truncated';
195
+ };
196
+ /**
197
+ * The `normalize` rule of the HTTP API (docs/usage/http-api.md). The bridge applies it in
198
+ * `GET /speech/wait`, the client in its own waits, so both must use this one copy. It is the only
199
+ * behaviour in this package: it belongs to the contract, not to either side.
200
+ */
201
+ /** Lower case, whitespace runs collapsed to one space, trimmed. */
202
+ export declare function normalizeText(text: string): string;
203
+ export { type BridgeState, type BridgeStatus, type ClickOptions, type ClientConfig, type ConfigKey, type ConfigValue, type ElementBox, type ExplicitValues, FocusError, type FocusTarget, type FocusablePage, type GetSpeechOptions, type GetTextOptions, type ManageClientConfig, type MouseButton, type NativeInput, type OnSpeechOptions, type PressKeysOptions, type ReadyOptions, type Recording, type ScreenPoint, type ServiceStatus, type Session, type SessionList, type SessionRef, type SetFocusOptions, type SetResult, type SilenceOptions, type SpeechCapture, type SpeechCaptureClientOptions, type SpeechEntry, type SpeechFeedEvent, type SpeechMatch, type StartSessionOptions, type StartedSession, type ValueSource, type WaitOptions };
package/dist/index.mjs CHANGED
@@ -1 +1 @@
1
- export { i as BridgeHttpError, a as BridgeNotReadyError, o as BridgeUnreachableError, l as CONFIG_PATH_ENV, d as ClientConfigError, f as DEFAULT_BRIDGE_URL, s as IncompatibleBridgeError, t as SpeechCaptureClient, c as SpeechTimeoutError, p as URL_ENV, u as clientConfigFile, n as createClientConfig, m as normalizeBridgeUrl, r as normalizeText } from "./main-DH_3C5Dp.mjs";
1
+ export { p as BridgeHttpError, m as BridgeNotReadyError, h as BridgeUnreachableError, c as CONFIG_PATH_ENV, g as ClientConfigError, u as DEFAULT_BRIDGE_URL, i as FocusError, _ as IncompatibleBridgeError, t as SpeechCaptureClient, v as SpeechTimeoutError, y as SpeechTruncatedError, d as URL_ENV, l as clientConfigFile, n as createClientConfig, f as normalizeBridgeUrl, b as normalizeText } from "./main-GSQbmJHV.mjs";