@sonara/client 0.37.2 → 0.38.0

package/README.md

@@ -14,7 +14,7 @@ await sonara.set("rate", 240);
 await sonara.close();
 ```
 
-- `connect(options)`: finds the shared runtime through `runtime.json`, starts the bundled `sonarad.exe` when none is usable (`autostart`, default on), takes over an idle incompatible one. Options: `clientName` (required), `runtimePath` (default `SONARA_RUNTIME`), `home`, `autostart`, `require`, `extensions`, `keepAlive`.
+- `connect(options)`: finds the shared runtime through `runtime.json`, starts the bundled `sonarad.exe` (`sonarad` on macOS) when none is usable (`autostart`, default on), takes over an idle incompatible one. Options: `clientName` (required), `runtimePath` (default `SONARA_RUNTIME`), `home`, `autostart`, `require`, `extensions`, `keepAlive`.
 - `speak(text, { mode: "append" | "replace", interrupt, label })` resolves with the item id.
 - `control(action)`: `play`, `pause`, `toggle`, `stop`, `skip`, `previous`, `next`, `restart`, `mute`, `unmute`.
 - `set(key, value)` / `get(key)` for `volume` (0..100), `rate` (100..400 wpm), `voice`, `engine`; `voices(engine?)`.

package/dist/cjs/connect.d.ts

@@ -5,12 +5,12 @@ export interface ConnectOptions {
     /** Your app's version (default: this package's version). */
     clientVersion?: string;
     /**
-     * The bundled `sonarad.exe`, started when no usable runtime is running.
+     * The bundled `sonarad.exe` (`sonarad` on macOS), started when no usable runtime is running.
      * Default: `SONARA_RUNTIME` from the environment. With
      * `@sonara/runtime-win32-x64`: `runtimePath()` from that package.
      */
     runtimePath?: string;
-    /** Home folder (default: `SONARA_HOME`, else `%LOCALAPPDATA%\Sonara`). */
+    /** Home folder (default: `SONARA_HOME`, else `%LOCALAPPDATA%\Sonara`; on macOS `~/Library/Application Support/Sonara`). */
     home?: string;
     /** Start the bundled runtime when none is usable (default true). */
     autostart?: boolean;

package/dist/cjs/discovery.d.ts

@@ -1,6 +1,10 @@
 import type { RuntimeInfo } from "./types.js";
-/** The home folder: `home`, else `SONARA_HOME`, else `%LOCALAPPDATA%\Sonara`. */
-export declare function resolveHome(home?: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * The home folder: `home`, else `SONARA_HOME`, else the platform default:
+ * `%LOCALAPPDATA%\Sonara` on Windows, `$HOME/Library/Application Support/Sonara`
+ * on macOS (the runtime and the plugin's launchers use the same path).
+ */
+export declare function resolveHome(home?: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string;
 /** `runtime.json` of `home`, or null when it is missing or unreadable. */
 export declare function readRuntime(home: string): RuntimeInfo | null;
 /** True while process `pid` exists. */

package/dist/cjs/discovery.js

@@ -14,12 +14,22 @@ const errors_js_1 = require("./errors.js");
 /** Exit code of a second `sonarad` for the same user and home. */
 const EXIT_ALREADY_RUNNING = 3;
 const POLL_MS = 50;
-/** The home folder: `home`, else `SONARA_HOME`, else `%LOCALAPPDATA%\Sonara`. */
-function resolveHome(home, env = process.env) {
+/**
+ * The home folder: `home`, else `SONARA_HOME`, else the platform default:
+ * `%LOCALAPPDATA%\Sonara` on Windows, `$HOME/Library/Application Support/Sonara`
+ * on macOS (the runtime and the plugin's launchers use the same path).
+ */
+function resolveHome(home, env = process.env, platform = process.platform) {
     if (home)
         return home;
     if (env.SONARA_HOME)
         return env.SONARA_HOME;
+    if (platform === "darwin") {
+        // posix: a macOS path, whatever the host (tests run it on Windows too).
+        if (env.HOME)
+            return node_path_1.posix.join(env.HOME, "Library", "Application Support", "Sonara");
+        throw new errors_js_1.SonaraError("E_NOT_RUNNING", "no home folder: pass home, or set SONARA_HOME or HOME");
+    }
     if (env.LOCALAPPDATA)
         return (0, node_path_1.join)(env.LOCALAPPDATA, "Sonara");
     throw new errors_js_1.SonaraError("E_NOT_RUNNING", "no home folder: pass home, or set SONARA_HOME or LOCALAPPDATA");

package/dist/cjs/engines.d.ts

@@ -6,8 +6,11 @@
  * engines (`sonarad --no-external-engines`) answers `E_UNSUPPORTED`.
  *
  * A key is sent only in `add` (`secret`), `setKey`, or with a draft profile
- * in `models`; the runtime stores it in Windows Credential Manager (a
- * draft's only for that request) and never returns it.
+ * in `models`; the runtime stores it in the OS key store, Windows Credential
+ * Manager or the macOS Keychain (a draft's only for that request), and never
+ * returns it. A profile's `key_ref` names that store `"credman"` (Windows) or
+ * `"keychain"` (macOS); a runtime takes either on every platform
+ * (`KEY_STORES`, `isStoredKey`).
  *
  * Sonara names no model or voice of its own (protocol 1.5, runtime 0.19.0):
  * `models` and `voices` list the provider's live, and a profile without one
@@ -27,6 +30,14 @@
  */
 import type { Reply } from "./types.js";
 export type Send = (type: string, fields: Record<string, unknown>) => Promise<Reply>;
+/**
+ * The `key_ref` values that name the OS key store: `"credman"` (Windows
+ * Credential Manager) and `"keychain"` (the macOS Keychain). A view says
+ * the runtime platform's name; a profile may send either.
+ */
+export declare const KEY_STORES: readonly string[];
+/** Whether a `key_ref` is a key kept in the OS key store (not `none`, not `env:`). */
+export declare function isStoredKey(keyRef: string | null | undefined): boolean;
 /** How text goes to an engine (#235): a whole message, or each sentence. */
 export type SendMode = "message" | "sentence";
 /** A profile as sent in `engine_add` (spec section 5). */
@@ -37,14 +48,14 @@ export interface EngineProfile {
     url?: string;
     model?: string;
     voice?: string;
-    /** `"none"`, `"credman"` or `"env:NAME"`. */
+    /** `"none"`, `"credman"` or `"keychain"` (the OS key store), or `"env:NAME"`. */
     key_ref?: string | null;
     /** Unset (or null): the kind's default (`message` for the cloud). */
     send_mode?: SendMode | null;
     options?: Record<string, unknown>;
 }
 export interface EngineAddOptions {
-    /** Stored in Credential Manager (forces `key_ref` `credman` when unset). */
+    /** Stored in the OS key store (sets `key_ref` to the store's name when unset). */
     secret?: string;
     /** Change an existing profile; its stored key is kept unless `secret` is given. */
     replace?: boolean;

package/dist/cjs/engines.js

@@ -1,6 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnginesApi = void 0;
+exports.EnginesApi = exports.KEY_STORES = void 0;
+exports.isStoredKey = isStoredKey;
+/**
+ * The `key_ref` values that name the OS key store: `"credman"` (Windows
+ * Credential Manager) and `"keychain"` (the macOS Keychain). A view says
+ * the runtime platform's name; a profile may send either.
+ */
+exports.KEY_STORES = ["credman", "keychain"];
+/** Whether a `key_ref` is a key kept in the OS key store (not `none`, not `env:`). */
+function isStoredKey(keyRef) {
+    return keyRef != null && exports.KEY_STORES.includes(keyRef);
+}
 class EnginesApi {
     constructor(send) {
         this.send = send;

package/dist/cjs/index.d.ts

@@ -13,7 +13,7 @@ export type { Unsubscribe } from "./client.js";
 export { SonaraError } from "./errors.js";
 export type { ErrorCode } from "./errors.js";
 export { AgentApi, ChannelsApi, SystemApi } from "./extensions.js";
-export { EnginesApi } from "./engines.js";
+export { EnginesApi, isStoredKey, KEY_STORES } from "./engines.js";
 export type { EngineAddOptions, EngineModelsDraft, EngineProfile, SendMode, EngineTestOptions, } from "./engines.js";
 export type { AskKind, AudioMode, ChannelOpenOptions, ChannelPolicy, StreamMessage } from "./extensions.js";
 export { readRuntime, resolveHome } from "./discovery.js";

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERSION = exports.PROTOCOL = exports.resolveHome = exports.readRuntime = exports.EnginesApi = exports.SystemApi = exports.ChannelsApi = exports.AgentApi = exports.SonaraError = exports.SonaraClient = exports.connect = void 0;
+exports.VERSION = exports.PROTOCOL = exports.resolveHome = exports.readRuntime = exports.KEY_STORES = exports.isStoredKey = exports.EnginesApi = exports.SystemApi = exports.ChannelsApi = exports.AgentApi = exports.SonaraError = exports.SonaraClient = exports.connect = void 0;
 /**
  * @sonara/client: talk to the Sonara runtime (protocol v1) from Node 18+
  * or an Electron main process. Zero dependencies.
@@ -21,6 +21,8 @@ Object.defineProperty(exports, "ChannelsApi", { enumerable: true, get: function
 Object.defineProperty(exports, "SystemApi", { enumerable: true, get: function () { return extensions_js_1.SystemApi; } });
 var engines_js_1 = require("./engines.js");
 Object.defineProperty(exports, "EnginesApi", { enumerable: true, get: function () { return engines_js_1.EnginesApi; } });
+Object.defineProperty(exports, "isStoredKey", { enumerable: true, get: function () { return engines_js_1.isStoredKey; } });
+Object.defineProperty(exports, "KEY_STORES", { enumerable: true, get: function () { return engines_js_1.KEY_STORES; } });
 var discovery_js_1 = require("./discovery.js");
 Object.defineProperty(exports, "readRuntime", { enumerable: true, get: function () { return discovery_js_1.readRuntime; } });
 Object.defineProperty(exports, "resolveHome", { enumerable: true, get: function () { return discovery_js_1.resolveHome; } });

package/dist/cjs/version.d.ts

@@ -1,5 +1,5 @@
 /** Version of this package, sent as `client.version` in `hello`. */
-export declare const VERSION = "0.37.2";
+export declare const VERSION = "0.38.0";
 /** Protocol this client speaks. */
 export declare const PROTOCOL: {
     readonly major: 1;

package/dist/cjs/version.js

@@ -2,6 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PROTOCOL = exports.VERSION = void 0;
 /** Version of this package, sent as `client.version` in `hello`. */
-exports.VERSION = "0.37.2";
+exports.VERSION = "0.38.0";
 /** Protocol this client speaks. */
 exports.PROTOCOL = { major: 1, minor: 0 };

package/dist/esm/connect.d.ts

@@ -5,12 +5,12 @@ export interface ConnectOptions {
     /** Your app's version (default: this package's version). */
     clientVersion?: string;
     /**
-     * The bundled `sonarad.exe`, started when no usable runtime is running.
+     * The bundled `sonarad.exe` (`sonarad` on macOS), started when no usable runtime is running.
      * Default: `SONARA_RUNTIME` from the environment. With
      * `@sonara/runtime-win32-x64`: `runtimePath()` from that package.
      */
     runtimePath?: string;
-    /** Home folder (default: `SONARA_HOME`, else `%LOCALAPPDATA%\Sonara`). */
+    /** Home folder (default: `SONARA_HOME`, else `%LOCALAPPDATA%\Sonara`; on macOS `~/Library/Application Support/Sonara`). */
     home?: string;
     /** Start the bundled runtime when none is usable (default true). */
     autostart?: boolean;

package/dist/esm/discovery.d.ts

@@ -1,6 +1,10 @@
 import type { RuntimeInfo } from "./types.js";
-/** The home folder: `home`, else `SONARA_HOME`, else `%LOCALAPPDATA%\Sonara`. */
-export declare function resolveHome(home?: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * The home folder: `home`, else `SONARA_HOME`, else the platform default:
+ * `%LOCALAPPDATA%\Sonara` on Windows, `$HOME/Library/Application Support/Sonara`
+ * on macOS (the runtime and the plugin's launchers use the same path).
+ */
+export declare function resolveHome(home?: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string;
 /** `runtime.json` of `home`, or null when it is missing or unreadable. */
 export declare function readRuntime(home: string): RuntimeInfo | null;
 /** True while process `pid` exists. */

package/dist/esm/discovery.js

@@ -1,16 +1,26 @@
 import { spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, posix } from "node:path";
 import { SonaraError } from "./errors.js";
 /** Exit code of a second `sonarad` for the same user and home. */
 const EXIT_ALREADY_RUNNING = 3;
 const POLL_MS = 50;
-/** The home folder: `home`, else `SONARA_HOME`, else `%LOCALAPPDATA%\Sonara`. */
-export function resolveHome(home, env = process.env) {
+/**
+ * The home folder: `home`, else `SONARA_HOME`, else the platform default:
+ * `%LOCALAPPDATA%\Sonara` on Windows, `$HOME/Library/Application Support/Sonara`
+ * on macOS (the runtime and the plugin's launchers use the same path).
+ */
+export function resolveHome(home, env = process.env, platform = process.platform) {
     if (home)
         return home;
     if (env.SONARA_HOME)
         return env.SONARA_HOME;
+    if (platform === "darwin") {
+        // posix: a macOS path, whatever the host (tests run it on Windows too).
+        if (env.HOME)
+            return posix.join(env.HOME, "Library", "Application Support", "Sonara");
+        throw new SonaraError("E_NOT_RUNNING", "no home folder: pass home, or set SONARA_HOME or HOME");
+    }
     if (env.LOCALAPPDATA)
         return join(env.LOCALAPPDATA, "Sonara");
     throw new SonaraError("E_NOT_RUNNING", "no home folder: pass home, or set SONARA_HOME or LOCALAPPDATA");

package/dist/esm/engines.d.ts

@@ -6,8 +6,11 @@
  * engines (`sonarad --no-external-engines`) answers `E_UNSUPPORTED`.
  *
  * A key is sent only in `add` (`secret`), `setKey`, or with a draft profile
- * in `models`; the runtime stores it in Windows Credential Manager (a
- * draft's only for that request) and never returns it.
+ * in `models`; the runtime stores it in the OS key store, Windows Credential
+ * Manager or the macOS Keychain (a draft's only for that request), and never
+ * returns it. A profile's `key_ref` names that store `"credman"` (Windows) or
+ * `"keychain"` (macOS); a runtime takes either on every platform
+ * (`KEY_STORES`, `isStoredKey`).
  *
  * Sonara names no model or voice of its own (protocol 1.5, runtime 0.19.0):
  * `models` and `voices` list the provider's live, and a profile without one
@@ -27,6 +30,14 @@
  */
 import type { Reply } from "./types.js";
 export type Send = (type: string, fields: Record<string, unknown>) => Promise<Reply>;
+/**
+ * The `key_ref` values that name the OS key store: `"credman"` (Windows
+ * Credential Manager) and `"keychain"` (the macOS Keychain). A view says
+ * the runtime platform's name; a profile may send either.
+ */
+export declare const KEY_STORES: readonly string[];
+/** Whether a `key_ref` is a key kept in the OS key store (not `none`, not `env:`). */
+export declare function isStoredKey(keyRef: string | null | undefined): boolean;
 /** How text goes to an engine (#235): a whole message, or each sentence. */
 export type SendMode = "message" | "sentence";
 /** A profile as sent in `engine_add` (spec section 5). */
@@ -37,14 +48,14 @@ export interface EngineProfile {
     url?: string;
     model?: string;
     voice?: string;
-    /** `"none"`, `"credman"` or `"env:NAME"`. */
+    /** `"none"`, `"credman"` or `"keychain"` (the OS key store), or `"env:NAME"`. */
     key_ref?: string | null;
     /** Unset (or null): the kind's default (`message` for the cloud). */
     send_mode?: SendMode | null;
     options?: Record<string, unknown>;
 }
 export interface EngineAddOptions {
-    /** Stored in Credential Manager (forces `key_ref` `credman` when unset). */
+    /** Stored in the OS key store (sets `key_ref` to the store's name when unset). */
     secret?: string;
     /** Change an existing profile; its stored key is kept unless `secret` is given. */
     replace?: boolean;

package/dist/esm/engines.js

@@ -1,3 +1,13 @@
+/**
+ * The `key_ref` values that name the OS key store: `"credman"` (Windows
+ * Credential Manager) and `"keychain"` (the macOS Keychain). A view says
+ * the runtime platform's name; a profile may send either.
+ */
+export const KEY_STORES = ["credman", "keychain"];
+/** Whether a `key_ref` is a key kept in the OS key store (not `none`, not `env:`). */
+export function isStoredKey(keyRef) {
+    return keyRef != null && KEY_STORES.includes(keyRef);
+}
 export class EnginesApi {
     constructor(send) {
         this.send = send;

package/dist/esm/index.d.ts

@@ -13,7 +13,7 @@ export type { Unsubscribe } from "./client.js";
 export { SonaraError } from "./errors.js";
 export type { ErrorCode } from "./errors.js";
 export { AgentApi, ChannelsApi, SystemApi } from "./extensions.js";
-export { EnginesApi } from "./engines.js";
+export { EnginesApi, isStoredKey, KEY_STORES } from "./engines.js";
 export type { EngineAddOptions, EngineModelsDraft, EngineProfile, SendMode, EngineTestOptions, } from "./engines.js";
 export type { AskKind, AudioMode, ChannelOpenOptions, ChannelPolicy, StreamMessage } from "./extensions.js";
 export { readRuntime, resolveHome } from "./discovery.js";

package/dist/esm/index.js

@@ -10,6 +10,6 @@ export { connect } from "./connect.js";
 export { SonaraClient } from "./client.js";
 export { SonaraError } from "./errors.js";
 export { AgentApi, ChannelsApi, SystemApi } from "./extensions.js";
-export { EnginesApi } from "./engines.js";
+export { EnginesApi, isStoredKey, KEY_STORES } from "./engines.js";
 export { readRuntime, resolveHome } from "./discovery.js";
 export { PROTOCOL, VERSION } from "./version.js";

package/dist/esm/version.d.ts

@@ -1,5 +1,5 @@
 /** Version of this package, sent as `client.version` in `hello`. */
-export declare const VERSION = "0.37.2";
+export declare const VERSION = "0.38.0";
 /** Protocol this client speaks. */
 export declare const PROTOCOL: {
     readonly major: 1;

package/dist/esm/version.js

@@ -1,4 +1,4 @@
 /** Version of this package, sent as `client.version` in `hello`. */
-export const VERSION = "0.37.2";
+export const VERSION = "0.38.0";
 /** Protocol this client speaks. */
 export const PROTOCOL = { major: 1, minor: 0 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonara/client",
-  "version": "0.37.2",
+  "version": "0.38.0",
   "description": "Client for the Sonara text-to-speech runtime (protocol v1): connect, speak, control, live state. Zero dependencies.",
   "license": "MIT",
   "repository": {