@retion-miniapp/sdk 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.8.1 — 2026-10-28
+
+### Docs
+- Phát hành README tiếng Việt đầy đủ cho biometric và speech-to-text: setup app chủ, API, response, event, lỗi và vòng đời phiên. Thêm các API mới vào bảng mục lục và liên kết gist hướng dẫn.
+- Khuyên dùng Mini App React Native 0.8.1 để có bản sửa listener speech. Không thay đổi API so với Web SDK 0.8.0.
+
+
+## 0.8.0 — 2026-10-28
+
+### Added
+- Speech-to-text qua bridge Mini App chung: bắt đầu/dừng, event tạm thời/cuối cùng/lỗi/kết thúc. Native tự xin quyền và quản lý phiên micro, huỷ khi mini app đóng/ẩn hoặc app xuống nền.
+
+
 ## 0.7.3 — 2026-10-28
 
 ### Changed

package/README.md

@@ -2,6 +2,10 @@
 
 SDK cho web mini app chạy trong app Retion.
 
+Tài liệu **Web SDK 0.8.1**, dùng với **Mini App React Native 0.8.1** để có đầy đủ Face ID / Touch ID và speech-to-text đã sửa listener native. App chủ tự cấu hình quyền và build native một lần; web chỉ gọi API và nhận kết quả/event.
+
+[Hướng dẫn tích hợp app chủ](https://gist.github.com/vanqui123/e90b4efc40b8a85cc7a4b922ef0378b8) · [Face ID / Touch ID](#face-id--touch-id--android-biometrics) · [Speech-to-text](#nhận-dạng-giọng-nói-080)
+
 ```bash
 npm i @retion-miniapp/sdk
 ```
@@ -19,6 +23,8 @@ npm i @retion-miniapp/sdk
 | [`openScreen({ screen, params })`](#openscreen-screen-params-) | Mở 1 màn hình của app |
 | [`openLink(url)`](#openlinkurl) | Mở link bằng hệ điều hành (deeplink app khác, tel:, mailto:, https) |
 | [`haptic(type)`](#haptictype) | Rung phản hồi (bấm nút, thanh toán xong…) |
+| [`getBiometricAvailability()` / `authenticateBiometric(req)`](#face-id--touch-id--android-biometrics) | Kiểm tra Face ID / Touch ID và trả nguyên kết quả xác thực native |
+| [`startSpeech(options)` / `stopSpeech()` / `onSpeech(event, cb)`](#nhận-dạng-giọng-nói-080) | Bắt đầu/dừng nhận dạng và nhận văn bản tạm thời/cuối cùng |
 
 **1 mini app = 1 trang, load 1 lần.** Mở mini app ở page / conversation khác, app **không nạp lại trang** mà gọi `onContextChange` — thiếu nó web sẽ hiện dữ liệu page cũ. Đổi tổ chức thì app nạp lại trang.
 
@@ -308,7 +314,7 @@ MIT
 
 ### Face ID / Touch ID / Android biometrics
 
-Requires a host version implementing the biometric APIs and a configured native biometric adapter.
+Với Web SDK **0.8.1**, app chủ cài `@retion-miniapp/react-native@0.8.1` và hoàn tất cấu hình quyền/native. Package tự xử lý biometric, không cần truyền adapter. Xem [cấu hình app chủ](https://github.com/vanqui123/retion-miniapp-react-native/blob/main/docs/BIOMETRICS.md).
 
 ```ts
 import { getBiometricAvailability, authenticateBiometric } from '@retion-miniapp/sdk';
@@ -327,3 +333,52 @@ giữ mã và thông báo do native cung cấp khi có. Lỗi bridge như `BUSY`
 `NOT_SUPPORTED`, `NOT_IN_HOST`, `TIMEOUT` vẫn được reject.
 `getBiometricAvailability()` giữ nguyên cả trường `error` của native nếu có.
 API xác minh trên thiết bị, không trả dữ liệu sinh trắc học hoặc token đăng nhập backend.
+
+### Nhận dạng giọng nói (0.8.0)
+
+API speech có từ **0.8.0**. Khuyên dùng Web SDK **0.8.1** và Mini App React Native **0.8.1**, gồm bản sửa đăng ký listener trên đúng native module để nhận text và event kết thúc. App chủ cấu hình Expo Modules, quyền micro/nhận dạng và build native một lần. Không gắn handler speech hay gửi message theo kênh `chat_sdk`. Xem [hướng dẫn cài đặt và hoạt động đầy đủ](https://github.com/vanqui123/retion-miniapp-react-native/blob/main/docs/SPEECH.md).
+
+```ts
+import { startSpeech, stopSpeech, onSpeech } from '@retion-miniapp/sdk';
+
+// Đăng ký một lần khi component được tạo, trước khi bắt đầu nghe.
+const offPartial = onSpeech('speech.partial', result => console.log(result.text));
+const offFinal = onSpeech('speech.final', result => console.log(result.text, result.results));
+const offError = onSpeech('speech.error', error => console.error(error.code, error.message));
+const offEnd = onSpeech('speech.end', () => console.log('Phiên nghe đã kết thúc'));
+
+// Nút bắt đầu gọi hàm này. Promise không trả văn bản.
+async function startListening() {
+  try { await startSpeech({ lang: 'vi-VN' }); }
+  catch (error) { console.error('Không bắt đầu được:', error); }
+}
+
+// Nút dừng: vẫn chờ kết quả cuối hoặc lỗi và event speech.end.
+async function stopListening() {
+  try { await stopSpeech(); }
+  catch (error) { console.error('Không dừng được:', error); }
+}
+
+// Khi rời màn hình trong web: dừng nếu không còn cần nghe, rồi dọn listener.
+// Nếu cần lưu câu cuối, giữ listener cho đến speech.end trước khi dọn.
+async function dispose() {
+  try { await stopSpeech(); }
+  finally { offPartial(); offFinal(); offError(); offEnd(); }
+}
+```
+
+| API / event | Kết quả |
+| --- | --- |
+| `startSpeech(options?)` | `Promise<void>` sau khi xin quyền và gửi lệnh bắt đầu; chờ tối đa 2 phút |
+| `stopSpeech()` | `Promise<void>` khi gửi lệnh dừng; chờ phản hồi bridge tối đa 15 giây, không phải chờ câu cuối |
+| `speech.partial` / `speech.final` | `{ text, isFinal, results, ... }`; giữ dữ liệu native và thêm `text` |
+| `speech.error` | `{ code, error, message, ... }`; lỗi xảy ra trong phiên |
+| `speech.end` | `undefined`; native kết thúc và host đã giải phóng phiên |
+
+Mặc định: `lang: 'vi-VN'`, `continuous: true`, `interimResults: true`, `addsPunctuation: true`, `requiresOnDeviceRecognition: false`. Web có thể truyền các tuỳ chọn này vào `startSpeech`; tính năng nhận dạng tuỳ thuộc dịch vụ và ngôn ngữ trên thiết bị.
+
+Chỉ một mini app được giữ phiên. Phiên đang bận trả `BUSY`; thiếu quyền trả `PERMISSION_DENIED`; tham số sai trả `INVALID_PARAMS`; mini app không còn hoạt động trả `CANCELLED`; thiếu native module trả `NOT_SUPPORTED`. Lỗi khởi động đi vào Promise; lỗi nhận dạng đi qua event. Host cũ có thể không hỗ trợ API. Trình duyệt ngoài host trả `NOT_IN_HOST`.
+
+Dừng không đảm bảo luôn có `speech.final`: native có thể không nhận được lời nói hoặc báo lỗi rồi kết thúc. `speech.final` trong chế độ nghe liên tục cũng không có nghĩa phiên đã kết thúc. Chỉ dựa vào `speech.end` để biết phiên đã được giải phóng.
+
+Đóng/ẩn mini app, reload WebView hoặc app xuống nền sẽ huỷ phiên. Huỷ listener web không tự tắt micro. Hết thời gian chờ web không tự huỷ lời gọi native hoặc đóng hộp xin quyền; nếu không còn muốn nghe, yêu cầu dừng. API speech không phụ thuộc cài đặt ngôn ngữ của Chat SDK.

package/dist/index.cjs

@@ -157,7 +157,7 @@ var on = (event, listener) => {
 };
 
 // src/version.ts
-var SDK_VERSION = "0.8.0" ;
+var SDK_VERSION = "0.8.1" ;
 
 // src/apis/app.ts
 var closeApp = () => call("closeApp");

package/dist/index.js

@@ -155,7 +155,7 @@ var on = (event, listener) => {
 };
 
 // src/version.ts
-var SDK_VERSION = "0.8.0" ;
+var SDK_VERSION = "0.8.1" ;
 
 // src/apis/app.ts
 var closeApp = () => call("closeApp");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retion-miniapp/sdk",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Retion Mini App SDK — kết nối web mini app với app Retion",
   "keywords": [
     "retion",