@creativeorange/azure-text-to-speech 3.0.0 → 3.0.2

package/README.md

@@ -7,16 +7,9 @@ Current major version: **3.0.0**
 
 ## Why version 3 exists
 
-In version 2, constructors accepted a permanent Azure subscription key and used:
+In version 2, constructors accepted a permanent Azure subscription key and used `fromSubscription`. That forced the real API key into browser bundles, DevTools, and memory.
 
-```ts
-SpeechConfig.fromSubscription(key, region);
-SpeechTranslationConfig.fromSubscription(key, region);
-```
-
-That forced the real API key into browser bundles, DevTools, and memory. Anyone who can open the page can extract the key and consume your Azure Speech quota.
-
-Version 3 removes that pattern completely. The permanent key stays on your server. The browser only receives short-lived Azure authorization tokens.
+Version 3 removes that pattern completely. The permanent key stays on your server. The browser only receives short-lived Azure authorization tokens via your own backend.
 
 ## Architecture
 
@@ -24,50 +17,63 @@ Version 3 removes that pattern completely. The permanent key stays on your serve
 Browser
   → your backend token endpoint
   → Azure issueToken endpoint
-  ← temporary Azure token
+  ← temporary Azure token + region
   → Azure Speech SDK (fromAuthorizationToken)
 ```
 
 Supported authentication options:
 
 1. `tokenEndpoint` — simple GET endpoint (Craft, classic sites)
-2. `getAuthorizationToken` — custom async provider (Laravel APIs, auth headers, CSRF, etc.)
+2. `getAuthorizationToken` — custom async provider
 
 There is **no** option to pass a permanent subscription key.
 
+The Azure Speech SDK is **bundled** into the published `dist` files, so consumers do not need to install `microsoft-cognitiveservices-speech-sdk` separately. That dependency remains a `devDependency` of this package.
+
 ## Install
 
 ```bash
 npm install @creativeorange/azure-text-to-speech
 ```
 
+TypeScript declarations are published at `dist/main.d.ts`.
+
+```ts
+import {
+    TextToSpeech,
+    SpeechToText,
+    type TextToSpeechOptions,
+    type SpeechToTextOptions,
+    type SpeechAuthorization,
+} from '@creativeorange/azure-text-to-speech';
+```
+
+Always import from the package root. Do not import from `/dist/...` paths.
+
 ## Public API
 
 ### Text to Speech with `tokenEndpoint`
 
 ```ts
-import {TextToSpeech} from '@creativeorange/azure-text-to-speech';
-
 const textToSpeech = new TextToSpeech({
     tokenEndpoint: '/actions/azure-speech/token',
     voice: 'nl-NL-FennaNeural',
-    region: 'westeurope',
 });
 
 await textToSpeech.start();
 ```
 
+The Speech region comes from the token endpoint response, not from frontend configuration. That prevents mismatches between frontend, backend and Azure resource region.
+
 ### Text to Speech with a custom provider
 
 ```ts
-import {TextToSpeech} from '@creativeorange/azure-text-to-speech';
-
 const textToSpeech = new TextToSpeech({
     voice: 'nl-NL-FennaNeural',
-    region: 'westeurope',
     getAuthorizationToken: async () => {
         const response = await fetch('/api/azure-speech/token', {
             credentials: 'same-origin',
+            cache: 'no-store',
             headers: {
                 Accept: 'application/json',
             },
@@ -87,11 +93,8 @@ await textToSpeech.start();
 ### Speech to Text
 
 ```ts
-import {SpeechToText} from '@creativeorange/azure-text-to-speech';
-
 const speechToText = new SpeechToText({
     tokenEndpoint: '/actions/azure-speech/token',
-    region: 'westeurope',
     sourceLanguage: 'nl-NL',
     targetLanguage: 'nl',
 });
@@ -99,6 +102,8 @@ const speechToText = new SpeechToText({
 await speechToText.start();
 ```
 
+Continuous recognition can outlive a single Azure token. After recognition starts successfully, Speech-to-Text refreshes the active recognizer token about every eight minutes (`tokenLifetimeMs`) by setting `recognizer.authorizationToken`.
+
 ### Token endpoint response
 
 ```json
@@ -122,12 +127,12 @@ type SpeechAuthenticationOptions = {
     tokenRequestOptions?: {
         headers?: Record<string, string>;
         credentials?: RequestCredentials;
+        cache?: RequestCache; // default: 'no-store'
     };
     tokenLifetimeMs?: number; // default: 8 minutes
 };
 
 type TextToSpeechOptions = SpeechAuthenticationOptions & {
-    region?: string;
     voice: string;
     rate?: number;
     pitch?: number;
@@ -135,27 +140,20 @@ type TextToSpeechOptions = SpeechAuthenticationOptions & {
 };
 
 type SpeechToTextOptions = SpeechAuthenticationOptions & {
-    region?: string;
     sourceLanguage: string;
     targetLanguage?: string;
 };
 ```
 
-Provide **exactly one** of `tokenEndpoint` or `getAuthorizationToken`:
-
-- both → `Provide either tokenEndpoint or getAuthorizationToken, not both.`
-- neither → `A tokenEndpoint or getAuthorizationToken provider is required.`
+Provide **exactly one** of `tokenEndpoint` or `getAuthorizationToken`.
 
-### Token caching
+### Token caching and transport
 
-Tokens are cached in memory:
-
-- fetched on first use
-- reused while still valid
-- refreshed after about **8 minutes** by default (`tokenLifetimeMs`)
-- parallel callers share one in-flight request
-- invalid/empty token or region values throw clear errors
-- tokens are never logged and never included in error events
+- Tokens are cached in memory and reused while valid.
+- Tokens refresh after about **8 minutes** by default.
+- Parallel callers share one in-flight request.
+- `tokenEndpoint` requests use `credentials: 'same-origin'` and `cache: 'no-store'` by default.
+- Tokens are never logged and never included in error events.
 
 ### Browser events
 
@@ -174,12 +172,8 @@ STT:
 - `COAzureSTTStoppedRecording`
 - `COAzureSTTError` → `{ detail: { error: { message, code? } } }`
 
-Error payloads never contain tokens or authorization headers.
-
 ## Migrating from v2 to v3
 
-This is a **breaking** change. The old positional constructor is removed on purpose.
-
 ### Old unsafe usage
 
 ```ts
@@ -192,22 +186,13 @@ const textToSpeech = new TextToSpeech(
 );
 ```
 
-Or Twig leaking the key into the browser:
-
-```twig
-<script>
-    window.azureSpeechKey = '{{ craft.app.config.general.azureSpeechKey }}';
-</script>
-```
-
-Remove these patterns.
+Remove Twig/Vite/window exports of the subscription key.
 
 ### New safe usage
 
 ```ts
 const textToSpeech = new TextToSpeech({
     tokenEndpoint: '/actions/azure-speech/token',
-    region: 'westeurope',
     voice: 'nl-NL-FennaNeural',
     rate: 0,
     pitch: 0,
@@ -218,13 +203,13 @@ const textToSpeech = new TextToSpeech({
 
 1. Update the package to `3.x`.
 2. Store `AZURE_SPEECH_KEY` and `AZURE_SPEECH_REGION` server-side only.
-3. Add a backend token endpoint (Craft / Laravel / other).
+3. Add a backend token endpoint.
 4. Replace the old constructor with the options object.
-5. Remove every Twig, JavaScript, Vite, Nuxt, or window variable that contained the subscription key.
+5. Remove every frontend variable that contained the subscription key.
 6. Rebuild the frontend.
-7. Confirm in DevTools that the permanent key no longer appears in network responses meant for the page, JS bundles, or globals.
-8. Test TTS, STT, highlighting, pause/resume, chained playback, and prefetching.
-9. **Rotate the previously exposed Azure subscription key.** Treat it as compromised.
+7. Confirm in DevTools that the permanent key no longer appears.
+8. Test TTS, STT, highlighting, pause/resume, chained playback and prefetching.
+9. **Rotate the previously exposed Azure subscription key.**
 
 ## Craft CMS integration
 
@@ -254,13 +239,29 @@ return [
 ];
 ```
 
-With controller ID `token`, the action URL becomes:
+Craft action routing uses:
+
+- module ID: `azure-speech`
+- controller ID: `token` (`TokenController`)
+- action: `actionIndex`
+
+Resulting URL:
 
 ```text
 /actions/azure-speech/token
 ```
 
-### Token controller
+Ensure the module registers its controller namespace, for example in `modules/azurespeech/Module.php`:
+
+```php
+public function init(): void
+{
+    parent::init();
+    // Controllers live in modules\azurespeech\controllers
+}
+```
+
+### Token controller for Craft 4 / Craft 5
 
 ```php
 <?php
@@ -273,7 +274,8 @@ use yii\web\Response;
 
 class TokenController extends Controller
 {
-    protected array|bool $allowAnonymous = true;
+    // Craft 4 and Craft 5
+    protected array|bool|int $allowAnonymous = true;
 
     public function actionIndex(): Response
     {
@@ -289,7 +291,7 @@ class TokenController extends Controller
         $client = Craft::createGuzzleClient();
 
         try {
-            $response = $client->post(
+            $azureResponse = $client->post(
                 "https://{$region}.api.cognitive.microsoft.com/sts/v1.0/issueToken",
                 [
                     'headers' => [
@@ -309,44 +311,50 @@ class TokenController extends Controller
             );
         }
 
-        return $this->asJson([
-            'token' => (string) $response->getBody(),
+        $craftResponse = $this->asJson([
+            'token' => (string) $azureResponse->getBody(),
             'region' => $region,
         ]);
+
+        $craftResponse->getHeaders()->set(
+            'Cache-Control',
+            'private, no-store, max-age=0'
+        );
+        $craftResponse->getHeaders()->set(
+            'Pragma',
+            'no-cache'
+        );
+
+        return $craftResponse;
     }
 }
 ```
 
-For older Craft/PHP versions where a typed property is undesirable:
+### Token controller property for Craft 3 / older PHP
 
 ```php
+// Craft 3 or older PHP versions without union property types
 protected $allowAnonymous = true;
 ```
 
-Use the property form that matches your Craft and PHP version.
+Use the property form that matches your Craft and PHP version. Do not log tokens or exception details to the browser.
 
 ### Frontend initialization
 
 ```ts
-import {TextToSpeech} from '@creativeorange/azure-text-to-speech';
+import {TextToSpeech, SpeechToText} from '@creativeorange/azure-text-to-speech';
 
 const textToSpeech = new TextToSpeech({
     tokenEndpoint: '/actions/azure-speech/token',
-    region: 'westeurope',
     voice: 'nl-NL-FennaNeural',
 });
 
 textToSpeech.start().catch((error) => {
     console.error('Could not initialize text to speech.', error);
 });
-```
-
-```ts
-import {SpeechToText} from '@creativeorange/azure-text-to-speech';
 
 const speechToText = new SpeechToText({
     tokenEndpoint: '/actions/azure-speech/token',
-    region: 'westeurope',
     sourceLanguage: 'nl-NL',
     targetLanguage: 'nl',
 });
@@ -366,12 +374,13 @@ Recommended controls:
 - Cloudflare rate limiting when available
 - Authentication when TTS/STT is not meant for anonymous visitors
 - HTTPS only
-- Short server-side timeouts (for example 10 seconds)
+- Short server-side timeouts
 - Azure budget and usage alerts
 - Azure resource networking restrictions when infrastructure allows it
 - Never put the permanent key in responses or logs
+- Return `Cache-Control: private, no-store, max-age=0`
 
-**CORS alone is not security.** Endpoints can be called outside a browser with `curl` or scripts. Rate limiting, auth, and Azure monitoring remain necessary.
+**CORS alone is not security.** Endpoints can be called outside a browser.
 
 ## Laravel token endpoint
 
@@ -382,7 +391,7 @@ use Illuminate\Support\Facades\Route;
 Route::get('/api/azure-speech/token', function () {
     $region = config('services.azure_speech.region');
 
-    $response = Http::timeout(10)
+    $azureResponse = Http::timeout(10)
         ->withHeaders([
             'Ocp-Apim-Subscription-Key' =>
                 config('services.azure_speech.key'),
@@ -391,53 +400,23 @@ Route::get('/api/azure-speech/token', function () {
             "https://{$region}.api.cognitive.microsoft.com/sts/v1.0/issueToken"
         );
 
-    abort_unless($response->successful(), 502);
+    abort_unless($azureResponse->successful(), 502);
 
-    return response()->json([
-        'token' => $response->body(),
-        'region' => $region,
-    ]);
+    return response()
+        ->json([
+            'token' => $azureResponse->body(),
+            'region' => $region,
+        ])
+        ->header(
+            'Cache-Control',
+            'private, no-store, max-age=0'
+        )
+        ->header('Pragma', 'no-cache');
 })->middleware('throttle:20,1');
 ```
 
 Put this route behind authentication whenever the feature is not public.
 
-Example `config/services.php` entries:
-
-```php
-'azure_speech' => [
-    'key' => env('AZURE_SPEECH_KEY'),
-    'region' => env('AZURE_SPEECH_REGION', 'westeurope'),
-],
-```
-
-Frontend:
-
-```ts
-const textToSpeech = new TextToSpeech({
-    tokenEndpoint: '/api/azure-speech/token',
-    region: 'westeurope',
-    voice: 'nl-NL-FennaNeural',
-});
-```
-
-Or with CSRF / custom headers:
-
-```ts
-const textToSpeech = new TextToSpeech({
-    voice: 'nl-NL-FennaNeural',
-    region: 'westeurope',
-    tokenEndpoint: '/api/azure-speech/token',
-    tokenRequestOptions: {
-        headers: {
-            'X-CSRF-TOKEN': document
-                .querySelector('meta[name="csrf-token"]')
-                ?.getAttribute('content') ?? '',
-        },
-    },
-});
-```
-
 ## Existing browser features
 
 Version 3 keeps the existing client behaviour from the development branch:
@@ -450,36 +429,14 @@ Version 3 keeps the existing client behaviour from the development branch:
 - voice / rate / pitch setters
 - existing custom browser events
 
-## HTML attributes (unchanged)
-
-TTS examples:
-
-```html
-<button co-tts="Hello world">Play</button>
-<button co-tts.pause>Pause</button>
-<button co-tts.resume>Resume</button>
-<button co-tts.stop>Stop</button>
-
-<div id="article" co-tts.highlight co-tts.text="Read this text" co-tts.next="next-block">
-    Read this text
-</div>
-```
-
-STT examples:
-
-```html
-<button co-stt.start="transcript">Start</button>
-<button co-stt.stop>Stop</button>
-<div id="transcript"></div>
-```
-
 ## Development
 
 ```bash
-npm install
-npm run build
-npm test
+npm ci
 npm run lint
+npm test
+npm run build
+npm run typecheck
 ```
 
 Security sanity checks:
@@ -487,9 +444,11 @@ Security sanity checks:
 ```bash
 grep -R "fromSubscription" src
 grep -R "subscriptionKey" src
+grep -R "Ocp-Apim-Subscription-Key" src
+grep -R "@creativeorange/azure-text-to-speech/dist" .
 ```
 
-Both should return no matches in package source.
+These should return no matches in package source or active examples.
 
 ## License
 

package/dist/SpeechToText.d.ts

@@ -0,0 +1,27 @@
+import { TranslationRecognizer } from 'microsoft-cognitiveservices-speech-sdk';
+import { SpeechAuthenticationOptions } from './authentication';
+export type SpeechToTextOptions = SpeechAuthenticationOptions & {
+    sourceLanguage: string;
+    targetLanguage?: string;
+};
+export declare class SpeechToText {
+    region: string;
+    sourceLanguage: string;
+    targetLanguage: string;
+    recognizer: TranslationRecognizer | undefined;
+    private readonly authorizationManager;
+    private readonly authorizationRefreshIntervalMs;
+    private authorizationRefreshTimer?;
+    private stopPromise?;
+    constructor(options: SpeechToTextOptions);
+    start(): Promise<void>;
+    registerBindings(node: any): Promise<void>;
+    private createSpeechTranslationConfig;
+    handleStartModifier(node: any, attr: Attr): Promise<void>;
+    handleStopModifier(node: any, _attr: Attr): Promise<void>;
+    stop(): Promise<void>;
+    private scheduleAuthorizationRefresh;
+    private clearAuthorizationRefreshTimer;
+    private stopRecognizer;
+    private dispatchError;
+}

package/dist/TextToSpeech.d.ts

@@ -0,0 +1,87 @@
+import { SpeechAuthenticationOptions } from './authentication';
+export type TextToSpeechOptions = SpeechAuthenticationOptions & {
+    voice: string;
+    rate?: number;
+    pitch?: number;
+    url?: string;
+};
+export declare class TextToSpeech {
+    region: string;
+    voice: string;
+    rate: number;
+    pitch: number;
+    textToRead: string;
+    wordBoundryList: any[];
+    clickedNode: any;
+    highlightDiv: any;
+    speechConfig: any;
+    audioConfig: any;
+    player: any;
+    synthesizer: any;
+    previousWordBoundary: any;
+    originalHighlightDivInnerHTML: string;
+    currentWord: string;
+    currentOffset: number;
+    wordBoundaryOffset: number;
+    playbackTextOffsetBase: number | undefined;
+    prevTextOffset: number;
+    url: string;
+    prefetchedAudio: Map<string, any>;
+    prefetchPromises: Map<string, Promise<any>>;
+    activePrefetchedAudioUrl: string;
+    playbackSegments: any[];
+    private readonly authorizationManager;
+    private stopPromise?;
+    private playbackSessionId;
+    private highlightInterval?;
+    constructor(options: TextToSpeechOptions);
+    start(): Promise<void>;
+    setVoice(voice: string): this;
+    setRate(rate: number): this;
+    setPitch(pitch: number): this;
+    registerBindings(node: any): Promise<void>;
+    handleIdModifier(node: any, attr: Attr): Promise<void>;
+    handleAjaxModifier(node: any, attr: Attr): Promise<void>;
+    handleDefault(node: any, attr: Attr): Promise<void>;
+    handleWithoutClick(node: any, attr: Attr): Promise<void>;
+    handleStopModifier(node: any, _attr: Attr): Promise<void>;
+    handlePauseModifier(node: any, _attr: Attr): Promise<void>;
+    handleResumeModifier(node: any, _attr: Attr): Promise<void>;
+    stopPlayer(): Promise<void>;
+    private performStopPlayer;
+    private createSpeechConfig;
+    startSynthesizer(_node: any, _attr: Attr): Promise<void>;
+    collectPlaybackChain(node: any): {
+        node: any;
+        text: any;
+        start: number;
+        end: any;
+        highlightDiv: HTMLElement | undefined;
+        originalHighlightDivInnerHTML: string;
+    }[];
+    preparePlaybackChain(chain: any[]): void;
+    getHighlightDivForNode(node: any): HTMLElement | undefined;
+    resetPlaybackSegments(): void;
+    updateChainedHighlight(wordBoundary: any): void;
+    getNodeText(node: any, attr?: Attr | null): any;
+    getPrefetchKey(node: any, text: string): string;
+    clearPrefetchedAudio(): void;
+    prefetchNextNode(node: any): Promise<void>;
+    playPrefetchedNode(node: any): Promise<boolean>;
+    private createPlaybackSession;
+    private isActivePlaybackSession;
+    private invalidatePlaybackSession;
+    private stopHighlightingInterval;
+    private startHighlightingInterval;
+    private updateHighlightForCurrentTime;
+    private highlightTextRange;
+    private setHighlightTargetFromNode;
+    private shouldHighlight;
+    private resetHighlightState;
+    private ensurePlaybackTextOffsetBase;
+    private resetCurrentHighlight;
+    buildSSML(text: string): string;
+    convertHtmlEntities(input: string): string;
+    private closeResource;
+    private dispatchError;
+}

package/dist/authentication.d.ts

@@ -0,0 +1,44 @@
+export type SpeechAuthorization = {
+    token: string;
+    region: string;
+};
+export type SpeechAuthorizationProvider = () => Promise<SpeechAuthorization>;
+export type SpeechTokenRequestOptions = {
+    headers?: Record<string, string>;
+    credentials?: RequestCredentials;
+    cache?: RequestCache;
+};
+export type SpeechAuthenticationOptions = {
+    tokenEndpoint?: string;
+    getAuthorizationToken?: SpeechAuthorizationProvider;
+    tokenRequestOptions?: SpeechTokenRequestOptions;
+    tokenLifetimeMs?: number;
+};
+export type SpeechSafeError = {
+    message: string;
+    code?: string;
+};
+export declare const DEFAULT_TOKEN_LIFETIME_MS: number;
+export declare function createSpeechAuthorizationProvider(options: SpeechAuthenticationOptions): SpeechAuthorizationProvider;
+export declare function validateSpeechAuthorization(value: unknown): SpeechAuthorization;
+export declare function createSafeError(message: string, code?: string): Error & SpeechSafeError;
+export declare function toSafeErrorDetail(error: unknown): SpeechSafeError;
+export declare function sanitizeErrorText(message: string): string;
+export declare function isLikelyAuthorizationError(error: unknown): boolean;
+/**
+ * Fetches, validates, caches and refreshes temporary Azure Speech tokens.
+ * Never logs authorization tokens.
+ */
+export declare class SpeechAuthorizationManager {
+    private authorization?;
+    private authorizationExpiresAt;
+    private authorizationRequest?;
+    private readonly provider;
+    private readonly tokenLifetimeMs;
+    constructor(options: SpeechAuthenticationOptions);
+    getTokenLifetimeMs(): number;
+    getAuthorization(): Promise<SpeechAuthorization>;
+    refreshAuthorization(): Promise<SpeechAuthorization>;
+    clearAuthorization(): void;
+    private fetchAuthorization;
+}