screenreader-speech-capture-client 0.1.0 → 0.3.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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Timo Stovermann
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -17,3 +17,7 @@ Your project needs `@types/node`. `@playwright/test` is a peer dependency.
17
17
  - [Repository](https://github.com/TimoSto/screenreader-speech-capture)
18
18
  - [Client documentation](https://github.com/TimoSto/screenreader-speech-capture/blob/main/docs/usage/client.md)
19
19
  - [The bridge](https://www.npmjs.com/package/screenreader-speech-capture)
20
+
21
+ ## License
22
+
23
+ [MIT](https://github.com/TimoSto/screenreader-speech-capture/blob/main/LICENSE)
package/dist/cli.mjs CHANGED
@@ -1,9 +1,9 @@
1
1
  #!/usr/bin/env node
2
- import { _ as IncompatibleBridgeError, d as URL_ENV, g as ClientConfigError, h as BridgeUnreachableError, m as BridgeNotReadyError, n as createClientConfig, p as BridgeHttpError, t as SpeechCaptureClient, v as SpeechTimeoutError, y as SpeechTruncatedError } from "./main-GSQbmJHV.mjs";
2
+ import { _ as IncompatibleBridgeError, d as URL_ENV, g as ClientConfigError, h as BridgeUnreachableError, m as BridgeNotReadyError, n as createClientConfig, p as BridgeHttpError, t as SpeechCaptureClient, v as SpeechTimeoutError, y as SpeechTruncatedError } from "./main-C25OxHlQ.mjs";
3
3
  import { hostname } from "node:os";
4
4
  import { parseArgs } from "node:util";
5
5
  // package.json
6
- var version = "0.1.0";
6
+ var version = "0.3.0";
7
7
  // src/adapters/in/cli/command.ts
8
8
  /** Exit codes (docs/usage/client.md#cli-for-agents). */
9
9
  const EXIT = {
@@ -82,6 +82,7 @@ const OPTIONS = {
82
82
  run: { type: "string" },
83
83
  session: { type: "string" },
84
84
  all: { type: "boolean" },
85
+ outside: { type: "boolean" },
85
86
  x: { type: "string" },
86
87
  y: { type: "string" },
87
88
  button: { type: "string" },
@@ -297,6 +298,10 @@ const SESSION_END = {
297
298
  usage: "session end",
298
299
  description: ["End the current session"]
299
300
  };
301
+ const SESSION_DELETE = {
302
+ usage: "session delete <id>",
303
+ description: ["Delete an ended session and its speech"]
304
+ };
300
305
  const SESSION_LIST = {
301
306
  usage: "session list",
302
307
  description: ["The sessions in the buffer, newest first"]
@@ -306,6 +311,7 @@ const session = {
306
311
  help: [
307
312
  SESSION_START,
308
313
  SESSION_END,
314
+ SESSION_DELETE,
309
315
  SESSION_LIST
310
316
  ],
311
317
  async run(args, { values, speech, out, io }) {
@@ -327,28 +333,49 @@ const session = {
327
333
  await speech().endSession();
328
334
  out("session end", { ended: true }, "Session ended.");
329
335
  return EXIT.ok;
336
+ case "delete": {
337
+ const [raw] = expectArgs(rest, 1, SESSION_DELETE.usage);
338
+ const id = Number(raw);
339
+ if (!/^\d+$/.test(raw) || !Number.isSafeInteger(id) || id < 1) throw new UsageError(`The session id must be an integer >= 1, got "${raw}".`);
340
+ await speech().deleteSession(id);
341
+ out("session delete", { deleted: true }, `Session ${id} deleted.`);
342
+ return EXIT.ok;
343
+ }
330
344
  case "list": {
331
345
  expectArgs(rest, 0, SESSION_LIST.usage);
332
346
  const list = await speech().sessions();
333
347
  out("session list", list, list.sessions.length === 0 ? "No sessions." : list.sessions.map((s) => formatSession(s, s.id === list.currentId)).join("\n"));
334
348
  return EXIT.ok;
335
349
  }
336
- case void 0: throw new UsageError("Missing session action: start, end or list.");
337
- default: throw new UsageError(`Unknown session action "${action}": use start, end or list.`);
350
+ case void 0: throw new UsageError("Missing session action: start, end, delete or list.");
351
+ default: throw new UsageError(`Unknown session action "${action}": use start, end, delete or list.`);
338
352
  }
339
353
  }
340
354
  };
341
355
  const CLEAR = {
342
- usage: "clear",
343
- description: ["Wipe the whole speech buffer, all sessions (for manual use)"]
356
+ usage: "clear [--session <id|current> | --outside]",
357
+ description: ["Wipe the whole speech buffer, all sessions (for manual use); --session clears only the", "current session (it keeps running), --outside only the speech outside sessions"]
344
358
  };
345
359
  const clear = {
346
- options: [],
360
+ options: ["session", "outside"],
347
361
  help: [CLEAR],
348
- async run(args, { speech, out }) {
362
+ async run(args, { values, speech, out }) {
349
363
  expectArgs(args, 0, CLEAR.usage);
350
- await speech().clear();
351
- out("clear", { cleared: true }, "Speech buffer cleared.");
364
+ if (values.session !== void 0 && values.outside) throw new UsageError("Use either --session or --outside.");
365
+ if (values.outside) {
366
+ await speech().clear({ session: "none" });
367
+ out("clear", { cleared: true }, "Speech outside sessions cleared.");
368
+ } else if (values.session === "current") {
369
+ await speech().clear({ session: "current" });
370
+ out("clear", { cleared: true }, "Speech of the current session cleared.");
371
+ } else if (values.session !== void 0) {
372
+ const id = optionalInt(values, "session", 1);
373
+ await speech().clear({ session: id });
374
+ out("clear", { cleared: true }, `Speech of session ${id} cleared.`);
375
+ } else {
376
+ await speech().clear();
377
+ out("clear", { cleared: true }, "Speech buffer cleared.");
378
+ }
352
379
  return EXIT.ok;
353
380
  }
354
381
  };
package/dist/index.d.mts CHANGED
@@ -1,4 +1,4 @@
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";
1
+ import { C as BridgeState, D as SessionList, E as Session, O as SessionRef, S as SpeechEntry, T as ServiceStatus, _ as SilenceOptions, a as PressKeysOptions, b as WaitOptions, c as FocusError, d as ClearOptions, f as GetSpeechOptions, g as Recording, h as ReadyOptions, i as NativeInput, k as StartedSession, l as MouseButton, m as OnSpeechOptions, n as FocusTarget, o as SetFocusOptions, p as GetTextOptions, r as FocusablePage, s as ElementBox, t as ClickOptions, u as ScreenPoint, v as SpeechCapture, w as BridgeStatus, x as SpeechMatch, y as StartSessionOptions } from "./native-input-BS6WaVhV.mjs";
2
2
  /** Bridge URL used when nothing else is configured. */
3
3
  export declare const DEFAULT_BRIDGE_URL = "http://localhost:5151";
4
4
  /** Environment variable with the bridge URL. */
@@ -99,9 +99,10 @@ export declare class SpeechCaptureClient implements SpeechCapture, NativeInput {
99
99
  playwrightEndpoint(): Promise<string>;
100
100
  getSpeech(options?: GetSpeechOptions): Promise<SpeechEntry[]>;
101
101
  getText(options?: GetTextOptions): Promise<string>;
102
- clear(): Promise<void>;
102
+ clear(options?: ClearOptions): Promise<void>;
103
103
  startSession(name: string, options?: StartSessionOptions): Promise<StartedSession>;
104
104
  endSession(): Promise<void>;
105
+ deleteSession(id: number): Promise<void>;
105
106
  sessions(): Promise<SessionList>;
106
107
  mark(label: string): Promise<SpeechEntry>;
107
108
  status(): Promise<BridgeStatus>;
@@ -200,4 +201,4 @@ type SpeechFeedEvent = {
200
201
  */
201
202
  /** Lower case, whitespace runs collapsed to one space, trimmed. */
202
203
  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 };
204
+ export { type BridgeState, type BridgeStatus, type ClearOptions, 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 { 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";
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-C25OxHlQ.mjs";
@@ -7,7 +7,7 @@ import path from "node:path";
7
7
  * `<major>.<minor>` of the HTTP API. Minor versions only add things
8
8
  * (docs/usage/http-api.md#versioning).
9
9
  */
10
- const API_VERSION = "1.14";
10
+ const API_VERSION = "1.18";
11
11
  /** Path prefix of every API route. */
12
12
  const API_PREFIX = "/api/v1";
13
13
  const DEFAULT_CONFIG = {
@@ -890,8 +890,9 @@ const StartSessionResponseSchema = /* @__PURE__ */ pipe(/* @__PURE__ */ object({
890
890
  const CLIENT_HEADER = "x-sr-speech-client";
891
891
  const SessionListSchema = /* @__PURE__ */ pipe(/* @__PURE__ */ object({
892
892
  sessions: /* @__PURE__ */ array(SessionSchema),
893
- currentId: /* @__PURE__ */ nullable(integer$2(1))
894
- }), /* @__PURE__ */ description("`GET /sessions`: the current session and the ended ones with entries in the buffer, newest first."));
893
+ currentId: /* @__PURE__ */ nullable(integer$2(1)),
894
+ outsideEntries: /* @__PURE__ */ pipe(integer$2(0), /* @__PURE__ */ description("Entries in the buffer that were recorded outside any session (`session=none`). Added in API 1.15."))
895
+ }), /* @__PURE__ */ description("`GET /sessions`: the current session and the ended ones with entries in the buffer, newest first, and how many entries lie outside any session."));
895
896
  // ../shared/src/speech.ts
896
897
  const integer$1 = (min) => /* @__PURE__ */ pipe(/* @__PURE__ */ number(), /* @__PURE__ */ integer$3(), /* @__PURE__ */ minValue(min));
897
898
  const timestamp$1 = /* @__PURE__ */ pipe(/* @__PURE__ */ string(), /* @__PURE__ */ isoTimestamp());
@@ -1394,8 +1395,9 @@ var FetchBridgeApi = class {
1394
1395
  hasMore: page.hasMore
1395
1396
  };
1396
1397
  }
1397
- async clear() {
1398
- await this.request("DELETE", "/speech");
1398
+ async clear(session) {
1399
+ const query = session === void 0 ? "" : `?session=${encodeURIComponent(String(session))}`;
1400
+ await this.request("DELETE", `/speech${query}`);
1399
1401
  }
1400
1402
  async mark(label) {
1401
1403
  const body = { label };
@@ -1415,6 +1417,9 @@ var FetchBridgeApi = class {
1415
1417
  async endSession() {
1416
1418
  await this.request("POST", "/sessions/end");
1417
1419
  }
1420
+ async deleteSession(id) {
1421
+ await this.request("DELETE", `/sessions?session=${String(id)}`);
1422
+ }
1418
1423
  async click(request) {
1419
1424
  const body = {
1420
1425
  x: request.x,
@@ -2054,8 +2059,12 @@ var SpeechCaptureService = class {
2054
2059
  allowTruncated: options.allowTruncated
2055
2060
  })).map((e) => e.text).join(options.separator ?? "\n");
2056
2061
  }
2057
- async clear() {
2062
+ async clear(options = {}) {
2058
2063
  await this.compatible();
2064
+ if (options.session !== void 0) {
2065
+ await this.deps.api.clear(options.session);
2066
+ return;
2067
+ }
2059
2068
  await this.deps.api.clear();
2060
2069
  this.#moveTo(0);
2061
2070
  }
@@ -2072,6 +2081,10 @@ var SpeechCaptureService = class {
2072
2081
  await this.compatible();
2073
2082
  await this.deps.api.endSession();
2074
2083
  }
2084
+ async deleteSession(id) {
2085
+ await this.compatible();
2086
+ await this.deps.api.deleteSession(id);
2087
+ }
2075
2088
  async sessions() {
2076
2089
  await this.compatible();
2077
2090
  return this.deps.api.listSessions();
@@ -2368,8 +2381,8 @@ var SpeechCaptureClient = class {
2368
2381
  getText(options) {
2369
2382
  return this.#service.getText(options);
2370
2383
  }
2371
- clear() {
2372
- return this.#service.clear();
2384
+ clear(options) {
2385
+ return this.#service.clear(options);
2373
2386
  }
2374
2387
  startSession(name, options) {
2375
2388
  return this.#service.startSession(name, options);
@@ -2377,6 +2390,9 @@ var SpeechCaptureClient = class {
2377
2390
  endSession() {
2378
2391
  return this.#service.endSession();
2379
2392
  }
2393
+ deleteSession(id) {
2394
+ return this.#service.deleteSession(id);
2395
+ }
2380
2396
  sessions() {
2381
2397
  return this.#service.sessions();
2382
2398
  }
@@ -102,6 +102,13 @@ interface SpeechEntry {
102
102
  }
103
103
  /** What a wait looks for: a substring, a regular expression or a predicate. */
104
104
  type SpeechMatch = string | RegExp | ((entry: SpeechEntry) => boolean);
105
+ interface ClearOptions {
106
+ /**
107
+ * Clear only this scope: the current session (its id or `'current'`) or `'none'` (the speech
108
+ * outside any session). The session keeps running. Needs bridge API 1.17.
109
+ */
110
+ session?: SessionRef | 'none' | undefined;
111
+ }
105
112
  interface GetSpeechOptions {
106
113
  /** Only entries with `seq > since`. Default: the cursor. */
107
114
  since?: number | undefined;
@@ -206,8 +213,13 @@ interface SpeechCapture {
206
213
  getSpeech(options?: GetSpeechOptions): Promise<SpeechEntry[]>;
207
214
  /** All speech after the cursor (or `since`), joined into one string. */
208
215
  getText(options?: GetTextOptions): Promise<string>;
209
- /** Clears the bridge's buffer (all sessions) and resets the cursor. For manual use. */
210
- clear(): Promise<void>;
216
+ /**
217
+ * Clears the bridge's buffer (all sessions) and resets the cursor. For manual use. With
218
+ * `session`, clears only that scope instead (the current session, or `'none'`): the session keeps
219
+ * running and the cursor stays. Rejects with `BridgeHttpError` for an ended session
220
+ * (`INVALID_REQUEST`) or `'current'` with none current (`NOT_FOUND`).
221
+ */
222
+ clear(options?: ClearOptions): Promise<void>;
211
223
  /**
212
224
  * Starts a session (docs/usage/speech-capture.md#sessions): it becomes current and the previous
213
225
  * one ends. Moves the cursor to the session's start, so the next reads and waits only see its
@@ -217,6 +229,12 @@ interface SpeechCapture {
217
229
  startSession(name: string, options?: StartSessionOptions): Promise<StartedSession>;
218
230
  /** Ends the current session. Speech after this belongs to no session. */
219
231
  endSession(): Promise<void>;
232
+ /**
233
+ * Deletes an ended session and its speech from the bridge's buffer (needs bridge API 1.16).
234
+ * Rejects with `BridgeHttpError` (`INVALID_REQUEST`) for the current session and `NOT_FOUND` for
235
+ * an id the bridge never gave out. The cursor stays where it is.
236
+ */
237
+ deleteSession(id: number): Promise<void>;
220
238
  /** The sessions still in the buffer plus the current one, newest first. */
221
239
  sessions(): Promise<SessionList>;
222
240
  /** Inserts a marker. Its `seq` can be used as `since`. */
@@ -319,4 +337,4 @@ interface NativeInput {
319
337
  /** Makes the page's browser window the foreground window with a native click. */
320
338
  setFocus(page: FocusablePage, options?: SetFocusOptions): Promise<void>;
321
339
  }
322
- export { BridgeStatus as C, SessionRef as D, SessionList as E, StartedSession as O, BridgeState as S, Session as T, SpeechCapture as _, PressKeysOptions as a, SpeechMatch as b, FocusError as c, GetSpeechOptions as d, GetTextOptions as f, SilenceOptions as g, Recording as h, NativeInput as i, MouseButton as l, ReadyOptions as m, FocusTarget as n, SetFocusOptions as o, OnSpeechOptions as p, FocusablePage as r, ElementBox as s, ClickOptions as t, ScreenPoint as u, StartSessionOptions as v, ServiceStatus as w, SpeechEntry as x, WaitOptions as y };
340
+ export { BridgeState as C, SessionList as D, Session as E, SessionRef as O, SpeechEntry as S, ServiceStatus as T, SilenceOptions as _, PressKeysOptions as a, WaitOptions as b, FocusError as c, ClearOptions as d, GetSpeechOptions as f, Recording as g, ReadyOptions as h, NativeInput as i, StartedSession as k, MouseButton as l, OnSpeechOptions as m, FocusTarget as n, SetFocusOptions as o, GetTextOptions as p, FocusablePage as r, ElementBox as s, ClickOptions as t, ScreenPoint as u, SpeechCapture as v, BridgeStatus as w, SpeechMatch as x, StartSessionOptions as y };
@@ -1,4 +1,4 @@
1
- import { _ as SpeechCapture, a as PressKeysOptions, i as NativeInput, t as ClickOptions, u as ScreenPoint } from "./native-input-BpZjLyPk.mjs";
1
+ import { a as PressKeysOptions, i as NativeInput, t as ClickOptions, u as ScreenPoint, v as SpeechCapture } from "./native-input-BS6WaVhV.mjs";
2
2
  import { expect } from "@playwright/test";
3
3
  /** When the fixture attaches the speech transcript of a test to the Playwright report. */
4
4
  type AttachMode = 'always' | 'on-failure' | 'off';
@@ -1,4 +1,4 @@
1
- import { a as READ_GEOMETRY_SCRIPT, n as createClientConfig, o as contentCornerPoint, r as playwrightEndpoint, s as parseWindowGeometry, t as SpeechCaptureClient } from "./main-GSQbmJHV.mjs";
1
+ import { a as READ_GEOMETRY_SCRIPT, n as createClientConfig, o as contentCornerPoint, r as playwrightEndpoint, s as parseWindowGeometry, t as SpeechCaptureClient } from "./main-C25OxHlQ.mjs";
2
2
  import { expect, test as test$1 } from "@playwright/test";
3
3
  // src/adapters/in/playwright/test-session.ts
4
4
  /** Name of a test's session: its title path without the project/file prefix. */
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "screenreader-speech-capture-client",
3
- "version": "0.1.0",
3
+ "version": "0.3.0",
4
4
  "description": "Test client for the screenreader-speech-capture bridge: library, Playwright fixture and CLI.",
5
- "license": "UNLICENSED",
5
+ "license": "MIT",
6
6
  "type": "module",
7
7
  "engines": {
8
8
  "node": ">=20"