@creativeorange/azure-text-to-speech 2.2.3 → 3.0.1

package/README.md

@@ -0,0 +1,455 @@
+# Azure Text to Speech / Speech to Text
+
+Browser package for Azure Cognitive Services Speech with **temporary authorization tokens**. Permanent Azure subscription keys never enter frontend JavaScript.
+
+Package: `@creativeorange/azure-text-to-speech`  
+Current major version: **3.0.0**
+
+## Why version 3 exists
+
+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.
+
+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
+
+```text
+Browser
+  → your backend token endpoint
+  → Azure issueToken endpoint
+  ← temporary Azure token + region
+  → Azure Speech SDK (fromAuthorizationToken)
+```
+
+Supported authentication options:
+
+1. `tokenEndpoint` — simple GET endpoint (Craft, classic sites)
+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
+const textToSpeech = new TextToSpeech({
+    tokenEndpoint: '/actions/azure-speech/token',
+    voice: 'nl-NL-FennaNeural',
+});
+
+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
+const textToSpeech = new TextToSpeech({
+    voice: 'nl-NL-FennaNeural',
+    getAuthorizationToken: async () => {
+        const response = await fetch('/api/azure-speech/token', {
+            credentials: 'same-origin',
+            cache: 'no-store',
+            headers: {
+                Accept: 'application/json',
+            },
+        });
+
+        if (!response.ok) {
+            throw new Error('Could not obtain Azure Speech token');
+        }
+
+        return response.json();
+    },
+});
+
+await textToSpeech.start();
+```
+
+### Speech to Text
+
+```ts
+const speechToText = new SpeechToText({
+    tokenEndpoint: '/actions/azure-speech/token',
+    sourceLanguage: 'nl-NL',
+    targetLanguage: 'nl',
+});
+
+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
+{
+    "token": "temporary-azure-token",
+    "region": "westeurope"
+}
+```
+
+### Options
+
+```ts
+type SpeechAuthorization = {
+    token: string;
+    region: string;
+};
+
+type SpeechAuthenticationOptions = {
+    tokenEndpoint?: string;
+    getAuthorizationToken?: () => Promise<SpeechAuthorization>;
+    tokenRequestOptions?: {
+        headers?: Record<string, string>;
+        credentials?: RequestCredentials;
+        cache?: RequestCache; // default: 'no-store'
+    };
+    tokenLifetimeMs?: number; // default: 8 minutes
+};
+
+type TextToSpeechOptions = SpeechAuthenticationOptions & {
+    voice: string;
+    rate?: number;
+    pitch?: number;
+    url?: string; // lexicon URL
+};
+
+type SpeechToTextOptions = SpeechAuthenticationOptions & {
+    sourceLanguage: string;
+    targetLanguage?: string;
+};
+```
+
+Provide **exactly one** of `tokenEndpoint` or `getAuthorizationToken`.
+
+### Token caching and transport
+
+- 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
+
+TTS:
+
+- `COAzureTTSStartedPlaying`
+- `COAzureTTSFinishedPlaying`
+- `COAzureTTSStoppedPlaying`
+- `COAzureTTSPausedPlaying`
+- `COAzureTTSResumedPlaying`
+- `COAzureTTSError` → `{ detail: { error: { message, code? } } }`
+
+STT:
+
+- `COAzureSTTStartedRecording`
+- `COAzureSTTStoppedRecording`
+- `COAzureSTTError` → `{ detail: { error: { message, code? } } }`
+
+## Migrating from v2 to v3
+
+### Old unsafe usage
+
+```ts
+const textToSpeech = new TextToSpeech(
+    window.azureSpeechKey,
+    'westeurope',
+    'nl-NL-FennaNeural',
+    0,
+    0
+);
+```
+
+Remove Twig/Vite/window exports of the subscription key.
+
+### New safe usage
+
+```ts
+const textToSpeech = new TextToSpeech({
+    tokenEndpoint: '/actions/azure-speech/token',
+    voice: 'nl-NL-FennaNeural',
+    rate: 0,
+    pitch: 0,
+});
+```
+
+### Migration checklist
+
+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.
+4. Replace the old constructor with the options object.
+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.
+8. Test TTS, STT, highlighting, pause/resume, chained playback and prefetching.
+9. **Rotate the previously exposed Azure subscription key.**
+
+## Craft CMS integration
+
+### `.env`
+
+```dotenv
+AZURE_SPEECH_KEY="replace-with-secret-key"
+AZURE_SPEECH_REGION="westeurope"
+```
+
+Never export these values to Twig globals, Vite `define`, or frontend env files.
+
+### Module registration (`config/app.php`)
+
+```php
+<?php
+
+return [
+    'modules' => [
+        'azure-speech' => [
+            'class' => \modules\azurespeech\Module::class,
+        ],
+    ],
+    'bootstrap' => [
+        'azure-speech',
+    ],
+];
+```
+
+Craft action routing uses:
+
+- module ID: `azure-speech`
+- controller ID: `token` (`TokenController`)
+- action: `actionIndex`
+
+Resulting URL:
+
+```text
+/actions/azure-speech/token
+```
+
+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
+
+namespace modules\azurespeech\controllers;
+
+use Craft;
+use craft\web\Controller;
+use yii\web\Response;
+
+class TokenController extends Controller
+{
+    // Craft 4 and Craft 5
+    protected array|bool|int $allowAnonymous = true;
+
+    public function actionIndex(): Response
+    {
+        $key = Craft::parseEnv('$AZURE_SPEECH_KEY');
+        $region = Craft::parseEnv('$AZURE_SPEECH_REGION');
+
+        if (!$key || !$region) {
+            return $this->asFailure(
+                'Azure Speech configuration is missing.'
+            );
+        }
+
+        $client = Craft::createGuzzleClient();
+
+        try {
+            $azureResponse = $client->post(
+                "https://{$region}.api.cognitive.microsoft.com/sts/v1.0/issueToken",
+                [
+                    'headers' => [
+                        'Ocp-Apim-Subscription-Key' => $key,
+                    ],
+                    'timeout' => 10,
+                ]
+            );
+        } catch (\Throwable $exception) {
+            Craft::error(
+                'Could not retrieve an Azure Speech token.',
+                __METHOD__
+            );
+
+            return $this->asFailure(
+                'Speech authorization is temporarily unavailable.'
+            );
+        }
+
+        $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;
+    }
+}
+```
+
+### 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. Do not log tokens or exception details to the browser.
+
+### Frontend initialization
+
+```ts
+import {TextToSpeech, SpeechToText} from '@creativeorange/azure-text-to-speech';
+
+const textToSpeech = new TextToSpeech({
+    tokenEndpoint: '/actions/azure-speech/token',
+    voice: 'nl-NL-FennaNeural',
+});
+
+textToSpeech.start().catch((error) => {
+    console.error('Could not initialize text to speech.', error);
+});
+
+const speechToText = new SpeechToText({
+    tokenEndpoint: '/actions/azure-speech/token',
+    sourceLanguage: 'nl-NL',
+    targetLanguage: 'nl',
+});
+
+speechToText.start().catch((error) => {
+    console.error('Could not initialize speech to text.', error);
+});
+```
+
+### Protecting the Craft token endpoint
+
+A temporary token may appear in the browser. That does **not** mean the endpoint can be public and unlimited.
+
+Recommended controls:
+
+- Craft rate limiting and/or webserver/proxy rate limiting
+- Cloudflare rate limiting when available
+- Authentication when TTS/STT is not meant for anonymous visitors
+- HTTPS only
+- 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.
+
+## Laravel token endpoint
+
+```php
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Route;
+
+Route::get('/api/azure-speech/token', function () {
+    $region = config('services.azure_speech.region');
+
+    $azureResponse = Http::timeout(10)
+        ->withHeaders([
+            'Ocp-Apim-Subscription-Key' =>
+                config('services.azure_speech.key'),
+        ])
+        ->post(
+            "https://{$region}.api.cognitive.microsoft.com/sts/v1.0/issueToken"
+        );
+
+    abort_unless($azureResponse->successful(), 502);
+
+    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.
+
+## Existing browser features
+
+Version 3 keeps the existing client behaviour from the development branch:
+
+- play / pause / resume / stop
+- word-boundary highlighting
+- chained playback (`co-tts.next`)
+- audio prefetching
+- lexicons via `url`
+- voice / rate / pitch setters
+- existing custom browser events
+
+## Development
+
+```bash
+npm ci
+npm run lint
+npm test
+npm run build
+npm run typecheck
+```
+
+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" .
+```
+
+These should return no matches in package source or active examples.
+
+## License
+
+MIT

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,79 @@
+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;
+    interval: any;
+    wordEncounters: number[];
+    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?;
+    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: any;
+        originalHighlightDivInnerHTML: any;
+    }[];
+    preparePlaybackChain(chain: any[]): void;
+    getHighlightDivForNode(node: any): any;
+    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>;
+    clearInterval(): Promise<void>;
+    createInterval(): Promise<void>;
+    getPosition(string: string, subString: string, textOffset: number): number;
+    buildSSML(text: string): string;
+    convertHtmlEntities(input: string): string;
+    private closeSynthesizer;
+    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;
+}