@pie-players/tts-client-server 0.3.73 → 0.3.74

package/README.md

@@ -39,27 +39,20 @@ const ttsService = new TTSService();
 await ttsService.initialize(provider, {
   apiEndpoint: '/api/tts',  // Your SvelteKit API route
   provider: 'polly',         // Server-side provider to use
-  voiceId: 'Joanna',
+  voice: 'Joanna',
   language: 'en-US',
 });
-
-// Note: `apiEndpoint`, `provider`, and `voiceId` are server-provider-specific
-// options. When using TTSConfig, pass these inside `providerOptions` rather
-// than as top-level fields:
-//
-//   const config: TTSConfig = {
-//     providerOptions: {
-//       apiEndpoint: '/api/tts',
-//       provider: 'polly',
-//       voiceId: 'Joanna',
-//     },
-//     language: 'en-US',
-//   };
 ```
 
-`apiEndpoint` is required when using `ServerTTSProvider` directly. Toolkit-level
-`tools.providers.textToSpeech` integration may provide a default endpoint for
-server-backed backends, but direct client usage should pass this explicitly.
+`apiEndpoint`, `provider`, `voice` and `language` are top-level fields; the
+provider reads none of them from `providerOptions`. `providerOptions` carries
+request extras: the PIE transport forwards its `engine` (when no top-level
+`engine` is set), `sampleRate`, `format` and `speechMarkTypes`, and the custom
+transport reads its `speedRate`.
+
+`apiEndpoint` is required when using `ServerTTSProvider` directly, and
+`initialize` throws without it. Toolkit-level `tools.providers.textToSpeech`
+integration defaults it to `/api/tts` for server-backed backends.
 
 ### With Authentication
 
@@ -67,8 +60,7 @@ server-backed backends, but direct client usage should pass this explicitly.
 await ttsService.initialize(provider, {
   apiEndpoint: '/api/tts',
   provider: 'polly',
-  authToken: 'your-jwt-token',
-  organizationId: 'org-123',
+  authToken: 'your-jwt-token', // sent as `Authorization: Bearer <token>`
 });
 ```
 
@@ -140,10 +132,14 @@ await ttsService.speak('Hello world, this is a test.', {
   "text": "Hello world",
   "speedRate": "medium",
   "lang_id": "en-US",
+  "langId": "en-US",
   "cache": true
 }
 ```
 
+The language travels under both `lang_id` and `langId`, so a server that binds
+JSON in camelCase reads it without a mapping of its own.
+
 ### Custom mode response
 
 ```json
@@ -157,7 +153,7 @@ Speech marks are fetched from the `word` URL and parsed as JSONL.
 
 ### Optional voices endpoint
 
-`GET ${apiEndpoint}/voices` remains optional and is only used when endpoint validation is configured with `endpointValidationMode: "voices"`.
+`GET ${apiEndpoint}/voices` remains optional and is only used when endpoint validation is configured with `endpointValidationMode: "voices"`. With `provider: "polly"` or `"google"` the probe tries `${apiEndpoint}/<provider>/voices` first and falls back to `${apiEndpoint}/voices` when that route returns 404. A failed probe makes the toolkit switch to browser TTS.
 
 ## SvelteKit Implementation Example
 
@@ -181,15 +177,18 @@ interface ServerTTSProviderConfig {
   transportMode?: 'pie' | 'custom';
   endpointMode?: 'synthesizePath' | 'rootPost';
   endpointValidationMode?: 'voices' | 'endpoint' | 'none';
+  validateEndpoint?: boolean; // Probe the endpoint during initialize()
   authToken?: string;         // JWT or API key
   includeAuthOnAssetFetch?: boolean;
   assetOrigins?: string[];    // Trusted origins for Authorization header
-  organizationId?: string;    // For multi-tenant setups
+  credentials?: 'omit' | 'same-origin' | 'include'; // Fetch credentials mode
   headers?: Record<string, string>;  // Custom headers
-  voiceId?: string;           // Voice ID
+  voice?: string;             // Voice ID, e.g. 'Joanna'
+  engine?: 'standard' | 'neural';    // Polly engine
   language?: string;          // Language code
   rate?: number;              // Speech rate (0.25-4.0)
   volume?: number;            // Volume (0-1)
+  providerOptions?: Record<string, unknown>; // Request extras (see Basic Setup)
 }
 ```
 
@@ -218,6 +217,13 @@ server that fall outside a trusted origin set.
   origins in `assetOrigins`; off-allow-list origins are fetched without
   auth. Leave at the default unless your CDN / storage backend actually
   requires the bearer token to read assets.
+- **`credentials`** — the fetch `credentials` mode, unset by default, which
+  leaves the browser default (`"same-origin"`). Set `"include"` when the TTS
+  server sits on another origin and authenticates by cookie; the server must
+  answer CORS with `Access-Control-Allow-Credentials: true` and an explicit
+  origin. Speech-mark and audio fetches to an origin outside `assetOrigins`
+  keep the browser default, so cookies follow the same allow-list as the
+  bearer token.
 
 See
 [`docs/tools-and-accomodations/tool_host_contract.md#backend-endpoints-for-tool-providers`](../../docs/tools-and-accomodations/tool_host_contract.md#backend-endpoints-for-tool-providers)

package/dist/ServerTTSProvider.d.ts

@@ -44,8 +44,9 @@ export interface ServerTTSProviderConfig extends TTSConfig {
      */
     endpointValidationMode?: "voices" | "endpoint" | "none";
     /**
-     * Include auth headers when fetching custom-transport speech marks and audio URLs.
-     * Defaults to false for compatibility.
+     * Send the synthesis request's `Authorization` header, whether it comes from
+     * `headers` or `authToken`, with the custom-transport speech-mark and audio
+     * fetches. Defaults to false for compatibility.
      */
     includeAuthOnAssetFetch?: boolean;
     /**
@@ -59,6 +60,14 @@ export interface ServerTTSProviderConfig extends TTSConfig {
      * responses keep working without explicit configuration.
      */
     assetOrigins?: string[];
+    /**
+     * Fetch `credentials` mode for requests to the TTS server, so a
+     * cookie-authenticated endpoint on another origin receives its cookies.
+     * Speech-mark and audio fetches use it only for an origin trusted with auth
+     * (see `assetOrigins`); others keep the browser default. Unset leaves every
+     * fetch on the browser default, `"same-origin"`.
+     */
+    credentials?: "omit" | "same-origin" | "include";
     /**
      * Validate API endpoint availability during initialization (slower but safer)
      *

package/dist/ServerTTSProvider.js

@@ -85,6 +85,33 @@ function scrubAuthHeaders(headers) {
     }
     return cleaned;
 }
+/**
+ * The `credentials` init for a fetch, spread into it. A cookie leaves the page
+ * for an untrusted asset origin only as the browser default would send it.
+ */
+function fetchCredentials(config, trustedForAuth = true) {
+    if (!config.credentials)
+        return {};
+    if (!trustedForAuth && config.credentials === "include")
+        return {};
+    return { credentials: config.credentials };
+}
+/**
+ * The headers a custom-transport speech-mark or audio fetch starts from: the
+ * synthesis request's `Authorization` header under `includeAuthOnAssetFetch`,
+ * nothing otherwise.
+ */
+function assetFetchHeaders(requestHeaders, config) {
+    const assetHeaders = {};
+    if (!config.includeAuthOnAssetFetch)
+        return assetHeaders;
+    for (const [key, value] of Object.entries(requestHeaders)) {
+        if (key.toLowerCase() === "authorization") {
+            assetHeaders[key] = value;
+        }
+    }
+    return assetHeaders;
+}
 const getTelemetryReporter = (config) => {
     const providerOptions = config.providerOptions && typeof config.providerOptions === "object"
         ? config.providerOptions
@@ -117,13 +144,15 @@ const resolveSupportsSSML = (config) => {
     return SSML_CAPABLE_PIE_PROVIDERS.has(provider);
 };
 const trimTrailingSlash = (value) => value.replace(/\/+$/, "");
-const resolveVoicesValidationUrl = (config) => {
+// Polly and Google probe their provider route first, then the generic
+// `${apiEndpoint}/voices` the integration guides have hosts create.
+const resolveVoicesValidationUrls = (config) => {
     const base = trimTrailingSlash(config.apiEndpoint);
     const provider = (config.provider || "").toLowerCase();
     if (provider === "polly" || provider === "google") {
-        return `${base}/${provider}/voices`;
+        return [`${base}/${provider}/voices`, `${base}/voices`];
     }
-    return `${base}/voices`;
+    return [`${base}/voices`];
 };
 const resolveTransportMode = (config) => {
     if (config.transportMode === "custom")
@@ -248,20 +277,15 @@ const customAdapter = {
         return {
             text,
             speedRate: resolveSpeedRate(config),
+            // Both spellings: servers that bind JSON camelCase never see `lang_id`.
             lang_id: langId,
+            langId,
             cache,
         };
     },
     parseResponse: async (response, config, headers, signal, text) => {
         const data = await response.json();
-        const marksHeaders = {};
-        if (config.includeAuthOnAssetFetch) {
-            for (const [key, value] of Object.entries(headers)) {
-                if (key.toLowerCase() === "authorization") {
-                    marksHeaders[key] = value;
-                }
-            }
-        }
+        const marksHeaders = assetFetchHeaders(headers, config);
         let speechMarks = [];
         const inlineSpeechMarks = parseInlineSpeechMarks(data.speechMarks);
         if (inlineSpeechMarks.length > 0) {
@@ -270,11 +294,13 @@ const customAdapter = {
         else if (typeof data.word === "string" && data.word.length > 0) {
             const marksUrl = parseAssetUrl(data.word, config);
             if (marksUrl !== null) {
-                const effectiveMarksHeaders = isOriginTrustedForAuth(marksUrl, config)
+                const marksTrusted = isOriginTrustedForAuth(marksUrl, config);
+                const effectiveMarksHeaders = marksTrusted
                     ? marksHeaders
                     : scrubAuthHeaders(marksHeaders);
                 const marksResponse = await fetch(marksUrl.toString(), {
                     headers: effectiveMarksHeaders,
+                    ...fetchCredentials(config, marksTrusted),
                     signal,
                     // Fail loud on redirects; the origin allow-list decision
                     // is made pre-redirect and a silent hop could leak auth
@@ -439,6 +465,7 @@ class ServerTTSProviderImpl {
                     headers,
                     body: JSON.stringify(requestBody),
                     signal,
+                    ...fetchCredentials(this.config),
                 });
             }
             catch (error) {
@@ -525,12 +552,7 @@ class ServerTTSProviderImpl {
                 backend: this.config.provider || "server",
                 operation: "fetch-synthesized-audio-asset",
             });
-            const assetHeaders = {};
-            if (this.config.includeAuthOnAssetFetch) {
-                if (this.config.authToken) {
-                    assetHeaders["Authorization"] = `Bearer ${this.config.authToken}`;
-                }
-            }
+            const assetHeaders = assetFetchHeaders(headers, this.config);
             const parsedAssetUrl = parseAssetUrl(audioAssetUrl, this.config);
             if (parsedAssetUrl === null) {
                 await this.emitTelemetry("pie-tool-backend-call-error", {
@@ -543,7 +565,8 @@ class ServerTTSProviderImpl {
                 });
                 throw new Error("TTS asset URL rejected (non-http(s) or malformed)");
             }
-            const effectiveAssetHeaders = isOriginTrustedForAuth(parsedAssetUrl, this.config)
+            const assetTrusted = isOriginTrustedForAuth(parsedAssetUrl, this.config);
+            const effectiveAssetHeaders = assetTrusted
                 ? assetHeaders
                 : scrubAuthHeaders(assetHeaders);
             const audioResponse = await (async () => {
@@ -551,6 +574,7 @@ class ServerTTSProviderImpl {
                     return await fetch(parsedAssetUrl.toString(), {
                         headers: effectiveAssetHeaders,
                         signal,
+                        ...fetchCredentials(this.config, assetTrusted),
                         redirect: "error",
                     });
                 }
@@ -867,19 +891,26 @@ export class ServerTTSProvider {
                 clearTimeout(timeoutId);
                 return true;
             }
-            const validationUrl = mode === "voices"
-                ? resolveVoicesValidationUrl(this.config)
-                : this.adapter.resolveSynthesisUrl(this.config);
+            const validationUrls = mode === "voices"
+                ? resolveVoicesValidationUrls(this.config)
+                : [this.adapter.resolveSynthesisUrl(this.config)];
             const method = mode === "voices" ? "GET" : "OPTIONS";
             try {
-                const response = await fetch(validationUrl, {
-                    method,
-                    headers,
-                    signal: controller.signal,
-                });
+                let reachable = false;
+                for (const validationUrl of validationUrls) {
+                    const response = await fetch(validationUrl, {
+                        method,
+                        headers,
+                        signal: controller.signal,
+                        ...fetchCredentials(this.config),
+                    });
+                    // Some endpoints may not accept OPTIONS; treat 405 as reachable.
+                    reachable = response.ok || response.status === 405;
+                    if (reachable || response.status !== 404)
+                        break;
+                }
                 clearTimeout(timeoutId);
-                // Some endpoints may not accept OPTIONS; treat 405 as reachable.
-                return response.ok || response.status === 405;
+                return reachable;
             }
             catch {
                 clearTimeout(timeoutId);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/tts-client-server",
-	"version": "0.3.73",
+	"version": "0.3.74",
 	"description": "Client-side TTS provider that calls server API for synthesis",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -38,13 +38,13 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@pie-players/pie-players-shared": "0.3.73",
-		"@pie-players/pie-tts": "0.3.73",
-		"@pie-players/tts-server-core": "0.3.73"
+		"@pie-players/pie-players-shared": "0.3.74",
+		"@pie-players/pie-tts": "0.3.74",
+		"@pie-players/tts-server-core": "0.3.74"
 	},
 	"devDependencies": {
 		"typescript": "^5.9.3",
-		"vitest": "^4.1.11"
+		"vitest": "^5.0.3"
 	},
 	"sideEffects": false,
 	"homepage": "https://github.com/pie-framework/pie-players/tree/master/packages/tts-client-server#readme",