@hoanghong/speaking-core 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.2.0
+
+- Add createSpeakingGateway for shared HTTP/WebSocket/ticket configuration.
+- Validate gateway URLs and malformed ticket responses.
+- Add complete microphone/upload examples and gateway/asset setup instructions.
+- Preserve existing low-level 0.1 APIs.
+
+## 0.1.0
+
+- Initial batch, realtime and browser microphone SDK.

package/README.md

@@ -1,19 +1,120 @@
 # @hoanghong/speaking-core
 
-TypeScript SDK cho batch ASR và realtime WebSocket v1. Không nhúng model hay service credential.
+TypeScript SDK cho FSEL ASR online: batch upload, WebSocket realtime, microphone AudioWorklet. MIT. Ngôn ngữ `en`, `ja`, `ko`, `zh`, `vi`. Không chứa model hoặc service credential.
 
-Exports: `BatchSpeakingClient`, `RealtimeSpeakingClient`, `SpeakingMicrophone`, contracts và errors.
-Microphone dùng AudioWorklet; copy asset `assets/pcm-worklet.js` vào app và truyền `workletUrl`.
+Muốn UI dùng ngay: cài [@hoanghong/speaking-angular](https://www.npmjs.com/package/@hoanghong/speaking-angular). Flutter dùng [fsel_speaking](https://pub.dev/packages/fsel_speaking). Core dành cho người tự thiết kế giao diện browser.
+
+## 1. Cài đặt
 
 ```bash
-npm ci
-npm test
-npm pack
+npm install @hoanghong/speaking-core@^0.2.0
 ```
 
-Realtime `ticketProvider` gọi backend ứng dụng để lấy ticket một lần, không gọi private ASR ticket API
-bằng service token trong browser. Batch `headers` cung cấp token người dùng cho gateway.
-`stop()` chờ ACK toàn bộ audio; `SpeakingMicrophone.stop()` flush phần PCM cuối trước finalize.
-Mất mạng/quá backlog trả lỗi rõ ràng, không tự reconnect/resume hay fallback.
+Cần browser có WebSocket, AudioWorklet, getUserMedia, HTTPS hoặc localhost. Node >=18 dùng cho tooling/batch; microphone chỉ chạy trong browser. Thư viện là ESM.
+
+## 2. Chuẩn bị gateway và asset
+
+Backend ứng dụng cung cấp prefix như `/api/speaking`, xác thực người dùng và relay giao thức FSEL ASR tới server. Chỉ backend giữ service token. Không nhúng khóa S3/service token vào bundle. Địa chỉ gateway quan sát được qua Network; không thể giấu URL mạng trong SDK. Package không kèm server ASR hoặc tài khoản miễn phí; server phải có weights cho ngôn ngữ được chọn.
+
+
+Gateway forward `POST /v1/realtime-tickets`, `WS /v1/realtime`, `POST /v1/transcription-jobs`, `GET/DELETE /v1/transcription-jobs/{id}` sau khi bỏ prefix. Bảo vệ route bằng đăng nhập, quyền sở hữu job và quota; không mở relay công khai dùng service token.
+
+Copy `node_modules/@hoanghong/speaking-core/assets/pcm-worklet.js` sang static asset `assets/speaking/pcm-worklet.js`. Với Angular thêm vào `angular.json` assets:
+
+```json
+{"glob":"pcm-worklet.js","input":"node_modules/@hoanghong/speaking-core/assets","output":"assets/speaking"}
+```
+
+Với bundler khác, dùng chức năng copy static assets tương ứng; URL phải trả JavaScript. Không dùng một HTML fallback làm worklet.
+
+## 3. Ví dụ microphone đầy đủ
+
+HTML của trang:
+
+```html
+<button id="start">Bắt đầu</button>
+<button id="stop" disabled>Dừng</button>
+<button id="cancel" disabled>Hủy</button>
+<pre id="transcript" aria-live="polite"></pre>
+```
+
+Module JavaScript/TypeScript được bundler xử lý sau khi DOM đã có:
+
+```js
+import {
+  createSpeakingGateway, RealtimeSpeakingClient, SpeakingMicrophone,
+} from '@hoanghong/speaking-core';
+
+const config = createSpeakingGateway({ baseUrl: '/api/speaking' });
+const client = new RealtimeSpeakingClient(config.realtime);
+const microphone = new SpeakingMicrophone(client, config.microphone);
+const start = document.querySelector('#start');
+const stop = document.querySelector('#stop');
+const cancel = document.querySelector('#cancel');
+const transcript = document.querySelector('#transcript');
+function idle() { start.disabled = false; stop.disabled = true; cancel.disabled = true; }
+const unsubscribe = client.onEvent(event => {
+  if (event.type === 'partial') transcript.textContent = event.text;
+  if (event.type === 'clientError') { transcript.textContent = event.error.message; idle(); }
+});
+start.onclick = async () => {
+  start.disabled = true;
+  transcript.textContent = 'Đang chuẩn bị…';
+  try {
+    await microphone.start({ language: 'vi' });
+    transcript.textContent = 'Đang nghe…';
+    stop.disabled = false; cancel.disabled = false;
+  } catch (error) { transcript.textContent = String(error); idle(); }
+};
+stop.onclick = async () => {
+  stop.disabled = true;
+  try {
+    const final = await microphone.stop();
+    transcript.textContent = final.result?.text ?? 'Không có lời nói.';
+  } catch (error) { transcript.textContent = String(error); }
+  finally { idle(); }
+};
+cancel.onclick = async () => {
+  try { await microphone.cancel(); transcript.textContent = 'Đã hủy.'; }
+  catch (error) { transcript.textContent = String(error); }
+  finally { idle(); }
+};
+window.addEventListener('pagehide', () => {
+  unsubscribe();
+  void microphone.dispose();
+}, { once: true });
+```
+
+Không tự bắt đầu ghi âm khi load trang. Chờ quyền microphone và `start()` hoàn tất trước khi nói. Khi dùng trong SPA, gọi unsubscribe/dispose ở lifecycle unmount thay vì chỉ pagehide. Không tự reconnect/replay audio sau mất mạng.
+
+## 4. Ví dụ upload đầy đủ
+
+```js
+import { BatchSpeakingClient, createSpeakingGateway } from '@hoanghong/speaking-core';
+
+const batch = new BatchSpeakingClient(createSpeakingGateway().batch);
+export async function transcribeFile(file, signal) {
+  if (file.size > 25 * 1024 * 1024) throw new Error('File tối đa 25 MiB');
+  let job = await batch.submitAudio(file, 'vi', crypto.randomUUID(), 'short_answer', file.name, signal);
+  const deadline = Date.now() + 10 * 60 * 1000;
+  while (!['succeeded', 'no_speech', 'failed', 'cancelled'].includes(job.status)) {
+    if (Date.now() > deadline) throw new Error('Hết thời gian chờ; job có thể còn chạy');
+    if (signal?.aborted) throw new DOMException('Aborted', 'AbortError');
+    await new Promise(resolve => setTimeout(resolve, 1500));
+    job = await batch.getResult(job.job_id, signal);
+  }
+  if (job.error) throw new Error(job.error.message);
+  return job;
+}
+// Truyền File lấy từ input[type=file] vào transcribeFile(file).
+// Chủ động hủy server job: await batch.cancelJob(jobId).
+// AbortSignal chỉ dừng request phía client, không tự hủy job trên server.
+```
+
+## Cấu hình và xử lý lỗi
+
+`createSpeakingGateway({baseUrl, headers, workletUrl, fetch})` trả ba nhóm `batch`, `realtime`, `microphone`. Mặc định base `/api/speaking`, worklet `assets/speaking/pcm-worklet.js`. Relative base dùng origin trang hiện tại; ngoài browser truyền URL HTTP(S) tuyệt đối. HTTPS tự dùng WSS. Không truyền base có userinfo/query/hash. `headers` là callback Promise trả HeadersInit, dùng auth của người dùng ứng dụng nếu cần, không dùng service token dài hạn. Cùng origin sử dụng cookie của ứng dụng; auth khác origin/CORS cần backend cấu hình tương ứng.
+
+Realtime ticket được xin tự động qua POST JSON `language`/`audio_profile`; ticket dùng để authenticate WebSocket. SDK xử lý queue audio có giới hạn, ACK, stop/final flush; microphone thu PCM mono 16 kHz. Realtime tối đa 300 giây theo server. Các constructor cấu hình thủ công 0.1 vẫn dùng được.
 
-Hướng dẫn cấu hình, ví dụ và contract: `docs/realtime-and-sdk.md` ở repository root.
+401/403: kiểm tra auth ứng dụng/gateway. 404: prefix/rewrite/asset. 503: model hoặc tài nguyên server. Worklet MIME/404: kiểm tra copy asset. Microphone denied: quyền và HTTPS. WS timeout: proxy Upgrade/WSS và timeout. `SpeakingError` có `code`, `message`, `status` khi có HTTP status. Không log credential hoặc ticket.

package/dist/gateway.d.ts

@@ -0,0 +1,16 @@
+import { BatchOptions } from './batch.js';
+import { MicrophoneOptions } from './microphone.js';
+import { RealtimeOptions } from './realtime.js';
+export interface SpeakingGatewayOptions {
+    /** Application gateway, e.g. /api/speaking. It must relay /v1 HTTP + WebSocket. */
+    baseUrl?: string;
+    /** Optional short-lived application auth. Never embed the ASR service token. */
+    headers?: () => Promise<HeadersInit>;
+    workletUrl?: string;
+    fetch?: typeof globalThis.fetch;
+}
+export declare function createSpeakingGateway(options?: SpeakingGatewayOptions): {
+    batch: BatchOptions;
+    realtime: RealtimeOptions;
+    microphone: MicrophoneOptions;
+};

package/dist/gateway.js

@@ -0,0 +1,35 @@
+import { SpeakingError } from './contracts.js';
+export function createSpeakingGateway(options = {}) {
+    const origin = typeof location === 'undefined' ? undefined : location.origin;
+    const url = new URL(options.baseUrl ?? '/api/speaking', origin);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+        throw new SpeakingError('INVALID_CONFIG', 'Use an HTTP(S) gateway URL without credentials, query or hash');
+    }
+    const baseUrl = url.href.replace(/\/$/, '');
+    const headers = options.headers ?? (async () => ({}));
+    const request = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const socket = new URL(baseUrl + '/v1/realtime');
+    socket.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    return {
+        batch: { baseUrl, headers, fetch: request },
+        realtime: {
+            websocketUrl: socket.href,
+            ticketProvider: async (start) => {
+                const auth = new Headers(await headers());
+                auth.set('Content-Type', 'application/json');
+                const response = await request(baseUrl + '/v1/realtime-tickets', {
+                    method: 'POST', headers: auth, credentials: 'same-origin',
+                    body: JSON.stringify({ language: start.language, audio_profile: start.audioProfile ?? 'short_answer' }),
+                });
+                const decoded = await response.json().catch(() => ({}));
+                const body = decoded && typeof decoded === 'object' ? decoded : {};
+                if (!response.ok)
+                    throw new SpeakingError(body.code ?? 'HTTP_ERROR', body.message ?? 'Cannot create speaking ticket', response.status);
+                if (typeof body.ticket !== 'string' || !body.ticket)
+                    throw new SpeakingError('INVALID_RESPONSE', 'Gateway returned no ticket');
+                return body.ticket;
+            },
+        },
+        microphone: { workletUrl: options.workletUrl ?? 'assets/speaking/pcm-worklet.js' },
+    };
+}

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export * from './contracts.js';
 export * from './batch.js';
 export * from './realtime.js';
 export * from './microphone.js';
+export * from './gateway.js';

package/dist/index.js

@@ -2,3 +2,4 @@ export * from './contracts.js';
 export * from './batch.js';
 export * from './realtime.js';
 export * from './microphone.js';
+export * from './gateway.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hoanghong/speaking-core",
-  "version": "0.1.0",
-  "description": "FSEL batch and native realtime speaking SDK for browsers",
+  "version": "0.2.0",
+  "description": "Online speaking SDK: gateway configuration, realtime microphone and audio upload",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,7 +15,8 @@
   "files": [
     "dist",
     "assets",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",