@retion-miniapp/sdk 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.8.2 — 2026-10-28
+
+### Docs
+- Rút gọn README theo cách sử dụng Web SDK: cài package, gọi API, nhận kết quả/event và xử lý lỗi. Bỏ lịch sử version và chi tiết triển khai app chủ khỏi hướng dẫn sử dụng. Không thay đổi API.
+
+
+## 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

@@ -19,6 +19,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) | 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.
 
@@ -238,7 +240,7 @@ if (isInHost()) {
 | Lỗi | Khi nào |
 |---|---|
 | `INVALID_PARAMS` | url sai định dạng hoặc scheme bị chặn (`javascript:`, `file:`, `data:`, `about:`, `blob:`) |
-| `NOT_SUPPORTED` | Không ứng dụng nào mở được link, hoặc app chưa hỗ trợ (`@retion-miniapp/react-native` < 0.7.5) |
+| `NOT_SUPPORTED` | Không ứng dụng nào mở được link hoặc tính năng chưa được hỗ trợ |
 
 ### `haptic(type)`
 
@@ -308,22 +310,84 @@ MIT
 
 ### Face ID / Touch ID / Android biometrics
 
-Requires a host version implementing the biometric APIs and a configured native biometric adapter.
+Kiểm tra thiết bị hỗ trợ rồi yêu cầu xác thực:
 
 ```ts
 import { getBiometricAvailability, authenticateBiometric } from '@retion-miniapp/sdk';
 
-const { available, biometryType } = await getBiometricAvailability();
-if (available) {
-  const result = await authenticateBiometric({ reason: 'Xác nhận danh tính', cancelButtonText: 'Huỷ' });
-  if (!result.success) console.log(result.error);
+async function authenticate() {
+  try {
+    const { available } = await getBiometricAvailability();
+    if (!available) return;
+
+    const result = await authenticateBiometric({
+      reason: 'Xác nhận danh tính',
+      cancelButtonText: 'Huỷ',
+    });
+    if (!result.success) {
+      console.log(result.error);
+      return;
+    }
+    // Tiếp tục thao tác sau khi xác thực thành công.
+  } catch (error) {
+    console.error(error);
+  }
+}
+```
+
+| API | Kết quả |
+| --- | --- |
+| `getBiometricAvailability()` | `{ available, biometryType?, error? }` — khả dụng và loại sinh trắc học |
+| `authenticateBiometric({ reason, cancelButtonText? })` | `{ success, error? }` — kết quả xác thực |
+
+`reason` là nội dung hộp xác thực, dài 1–200 ký tự. `cancelButtonText` là nhãn nút huỷ, không bắt buộc, tối đa 80 ký tự.
+
+Kiểm tra `result.success` trước khi tiếp tục. Người dùng huỷ có thể trả `{ success: false, error: 'User cancellation' }`; lỗi khác có thể đi vào `catch`. Loại xác thực do thiết bị quyết định: `FaceID`, `TouchID` hoặc `Biometrics` trên Android.
+
+### Nhận dạng giọng nói
+
+Đăng ký nhận văn bản trước khi bắt đầu nghe:
+
+```ts
+import { startSpeech, stopSpeech, onSpeech } from '@retion-miniapp/sdk';
+
+const offPartial = onSpeech('speech.partial', result => console.log(result.text));
+const offFinal = onSpeech('speech.final', result => console.log(result.text));
+const offError = onSpeech('speech.error', error => console.error(error.code, error.message));
+const offEnd = onSpeech('speech.end', () => console.log('Đã dừng nghe'));
+
+// Gọi khi bấm nút bắt đầu.
+async function startListening() {
+  try { await startSpeech({ lang: 'vi-VN' }); }
+  catch (error) { console.error(error); }
+}
+
+// Gọi khi bấm nút dừng; vẫn giữ listener để nhận câu cuối.
+async function stopListening() {
+  try { await stopSpeech(); }
+  catch (error) { console.error(error); }
+}
+
+// Khi huỷ component: dừng nếu không còn cần nghe và dọn listener.
+async function dispose() {
+  try { await stopSpeech(); }
+  finally { offPartial(); offFinal(); offError(); offEnd(); }
 }
 ```
 
-Từ Web SDK **0.7.3** và host **0.7.8**, kết quả được giữ nguyên từ thư viện native:
-`{ success: boolean, error?: string }`. Người dùng huỷ có thể trả `success: false`; hãy kiểm tra
-`result.success` trước khi tiếp tục. Lỗi native bị reject vẫn đi qua `MiniAppError` của bridge,
-giữ mã và thông báo do native cung cấp khi có. Lỗi bridge như `BUSY`, `INVALID_PARAMS`,
-`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.
+| API / event | Kết quả |
+| --- | --- |
+| `startSpeech(options?)` | Bắt đầu nghe; trả `Promise<void>`, văn bản đến qua event |
+| `stopSpeech()` | Yêu cầu dừng; trả `Promise<void>`, không phải câu cuối |
+| `speech.partial` | `{ text, isFinal, results }` — văn bản tạm thời |
+| `speech.final` | `{ text, isFinal, results }` — văn bản đã chốt |
+| `speech.error` | `{ code, error, message }` — lỗi khi đang nghe |
+| `speech.end` | Phiên nghe đã kết thúc |
+
+Truyền `lang` để chọn ngôn ngữ, ví dụ `vi-VN`, `en-US`. Mặc định là `vi-VN`, không tự đoán ngôn ngữ đang nói. Muốn đổi ngôn ngữ, dừng phiên hiện tại rồi bắt đầu lại.
+
+Các tuỳ chọn khác: `continuous` (mặc định `true`), `interimResults` (`true`), `addsPunctuation` (`true`), `requiresOnDeviceRecognition` (`false`). Khả năng nhận dạng phụ thuộc thiết bị và dịch vụ đang dùng.
+
+Giữ listener sau khi gọi dừng để nhận câu cuối nếu có, và chờ `speech.end`. Nếu cần lưu câu cuối khi rời màn hình, đợi event kết thúc trước khi dọn listener. Huỷ listener không tự dừng nghe.
+
+Lỗi bắt đầu/dừng đi vào `catch`; lỗi trong phiên đến qua `speech.error`. `BUSY` nghĩa là đang có phiên khác, `PERMISSION_DENIED` là chưa được cấp quyền, `NOT_SUPPORTED` là tính năng chưa được hỗ trợ. Xem thêm [xử lý lỗi](#lỗi).

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.2" ;
 
 // 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.2" ;
 
 // 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.2",
   "description": "Retion Mini App SDK — kết nối web mini app với app Retion",
   "keywords": [
     "retion",