@retion-miniapp/sdk 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.8.3 — 2026-10-28
+
+### Docs
+- Gom hướng dẫn API native, Face ID và speech trước phần xử lý lỗi trong README. Không thay đổi API.
+
+
+## 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

package/README.md

@@ -2,10 +2,6 @@
 
 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
 ```
@@ -24,7 +20,7 @@ npm i @retion-miniapp/sdk
 | [`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 |
+| [`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.
 
@@ -244,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)`
 
@@ -265,6 +261,91 @@ haptic(HapticType.notificationSuccess); // thanh toán xong
 | `rigid` / `soft` | Va chạm cứng / mềm |
 | `notificationSuccess` / `notificationWarning` / `notificationError` | Kết quả thao tác |
 
+
+### Face ID / Touch ID / Android biometrics
+
+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';
+
+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(); }
+}
+```
+
+| 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).
+
 ---
 
 ## Lỗi
@@ -311,74 +392,3 @@ Build + deploy lên app: [`@retion-miniapp/cli`](https://www.npmjs.com/package/@
 ## License
 
 MIT
-
-### Face ID / Touch ID / Android biometrics
-
-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';
-
-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);
-}
-```
-
-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.
-
-### 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.1" ;
+var SDK_VERSION = "0.8.3" ;
 
 // 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.1" ;
+var SDK_VERSION = "0.8.3" ;
 
 // src/apis/app.ts
 var closeApp = () => call("closeApp");

package/package.json

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