rvis-aiui-kit 1.0.0

package/sdk/modules/screen/readme.md

@@ -0,0 +1,110 @@
+# Screen API
+
+Screen 模块通过 `glass3.screen` 控制眼镜息屏和亮屏。
+
+## 方法
+
+| JavaScript API | 说明 |
+| --- | --- |
+| `screen.turnOff()` | 关闭屏幕，并等待 Native 确认操作成功。 |
+| `screen.turnOn()` | 点亮屏幕，并等待 Native 确认操作成功。 |
+
+## `screen.turnOff`
+
+```js
+const result = await glass3.screen.turnOff();
+```
+
+Native 映射：
+
+```json
+{
+  "toolName": "screenOff",
+  "toolAction": "start",
+  "args": { "state": "off" },
+  "extra": {}
+}
+```
+
+## `screen.turnOn`
+
+```js
+const result = await glass3.screen.turnOn();
+```
+
+Native 映射：
+
+```json
+{
+  "toolName": "screenOff",
+  "toolAction": "start",
+  "args": { "state": "on" },
+  "extra": {}
+}
+```
+
+两个方法都不接收参数。Native 的 accepted response 只表示请求已受理；收到
+匹配 requestId 的 `toolResult` event，并且 `result.ok: true`、`result.screen`
+等于本次请求的目标状态时，Promise 才会完成。返回值为：
+
+```js
+{
+  requestId: '...',
+  ok: true,
+  changed: true,
+  screen: 'off'
+}
+```
+
+`changed` 表示 Native 是否实际改变了屏幕状态。如果屏幕原本已经处于目标
+状态，可能返回 `changed: false`，仍然视为调用成功。
+
+## 系统亮屏/息屏状态事件
+
+由系统负责的普通亮屏和息屏会通过页面 `onMessage(messageEvent)` 下发原始 Host RPC 事件：
+
+```js
+{
+  channel: 'rokid.host.rpc',
+  version: '2.0.0',
+  kind: 'event',
+  namespace: 'rokid.device',
+  event: 'screenStateChanged',
+  sequence: 17,
+  data: {
+    state: 'on',
+    source: 'sleep_overlay',
+    revision: 5,
+    changedAtElapsedMs: 888558
+  }
+}
+```
+
+`data.state` 只使用 `on` 和 `off`。页面进入时可默认按亮屏处理，之后以该事件
+作为系统亮屏/息屏状态的来源。页面仍需先调用 `glass3.handleMessage(messageEvent)`
+转发 SDK 消息，再从 `messageEvent.data` 读取此事件。
+
+系统接管普通电源行为时，不要在 `RokidActionSingleClick` 中调用 Screen API，
+也不要调用 `event.preventDefault()`。息屏状态下页面无法依赖 `Enter` 回调；应让
+Host 完成亮屏，再处理 `state: 'on'` 事件。离线“查看”等明确的业务动作仍可主动
+调用 `glass3.screen.turnOn()`。
+
+## 与 Notification 的显示优先级
+
+Native notification 的显示优先级高于屏幕的息屏状态。调用
+`glass3.screen.turnOff()` 不会自动隐藏已经显示的 notification；即使息屏调用
+成功，普通页面内容关闭后，notification 仍可能继续显示。
+
+如果业务要求息屏后不保留任何 notification，需要先保存
+`glass3.notification.show()` 返回的 requestId，并主动调用：
+
+```js
+await glass3.notification.hide({ requestId: notificationRequestId });
+await glass3.screen.turnOff();
+```
+
+Screen 模块不会自动管理或销毁 notification。
+
+页面需要把 `onMessage(messageEvent)` 转发给
+`glass3.handleMessage(messageEvent)`，并在 `onUnload()` 中调用
+`glass3.dispose()`。

package/sdk/modules/tts/index.js

@@ -0,0 +1,75 @@
+import {
+  COMPLETION_ACCEPTED,
+  COMPLETION_EVENT
+} from '../../core/constants.js';
+import { Glass3Error } from '../../utils/errors.js';
+
+function createParameterError(message) {
+  return new Glass3Error(message, {
+    code: 'INVALID_PARAMS',
+    stage: 'params',
+    namespace: 'rokid.tools',
+    method: 'invoke'
+  });
+}
+
+function buildStopArgs(args) {
+  if (
+    !args ||
+    typeof args !== 'object' ||
+    Array.isArray(args) ||
+    typeof args.requestId !== 'string' ||
+    !args.requestId.trim()
+  ) {
+    throw createParameterError('tts.stop requires a requestId');
+  }
+
+  const inputFields = Object.keys(args);
+  if (inputFields.length !== 1 || inputFields[0] !== 'requestId') {
+    throw createParameterError('tts.stop only supports requestId');
+  }
+
+  return {
+    targetRequestId: args.requestId
+  };
+}
+
+const ttsSpeak = {
+  publicModule: 'tts',
+  publicMethod: 'speak',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'tts',
+  toolAction: 'start',
+
+  completion: COMPLETION_ACCEPTED,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  terminalStates: ['finished', 'canceled']
+};
+
+const ttsStop = {
+  publicModule: 'tts',
+  publicMethod: 'stop',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'tts',
+  toolAction: 'stop',
+
+  completion: COMPLETION_EVENT,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  terminalStates: ['stopped'],
+  responseCompletionStates: ['stopped'],
+  buildArgs: buildStopArgs,
+  selectEventResult(eventData) {
+    return Object.assign(
+      { requestId: eventData.requestId },
+      eventData.result
+    );
+  }
+};
+
+export default [ttsSpeak, ttsStop];

package/sdk/modules/tts/readme.md

@@ -0,0 +1,162 @@
+# TTS API
+
+TTS 模块通过 `glass3.tts` 暴露语音播报能力。
+
+| API | 说明 |
+| --- | --- |
+| `tts.speak` | 开始播放一段 TTS。 |
+| `tts.stop` | 停止指定的 TTS 播放。 |
+
+使用 SDK 的页面必须在 `onMessage` 中把宿主消息交给 `glass3.handleMessage`，否则无法收到播放事件。
+
+```js
+import glass3 from 'rvis-aiui-kit';
+
+export default {
+  onMessage(messageEvent) {
+    glass3.handleMessage(messageEvent);
+  },
+
+  onUnload() {
+    glass3.dispose();
+  }
+};
+```
+
+## `tts.speak`
+
+开始播放一段 TTS。
+
+```js
+const result = await glass3.tts.speak(
+  {
+    text: '你好，这是一段播报。',
+    queueMode: 'flush'
+  },
+  {
+    onEvent(eventResult) {
+      console.log('TTS event:', JSON.stringify(eventResult));
+    }
+  }
+);
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `text` | `string` | 是 | 需要播报的文本。当前 SDK 直接透传，不做本地校验。 |
+| `queueMode` | `string` | 否 | 播放队列策略，例如 `flush`。当前 SDK 直接透传。 |
+
+第二个参数是可选的调用选项：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `onEvent` | `function` | 否 | 接收当前播报过程中的事件结果。 |
+
+### 返回值
+
+`tts.speak` 在 fetch 返回 Native 已受理结果后完成，不等待播报结束。
+
+```js
+{
+  requestId: '本次播放的 UUID',
+  ok: true
+}
+```
+
+### 事件
+
+`onEvent` 只接收 Native 消息中的 `message.data.result`。
+
+常见事件：
+
+```js
+{ ok: true, state: 'started' }
+{ ok: true, state: 'finished' }
+{ ok: true, state: 'canceled' }
+```
+
+收到 `finished` 或 `canceled` 后，SDK 会清理本次调用的事件监听。未传 `onEvent` 时，SDK 不保留事件监听。
+
+### Native 映射
+
+| 字段 | 值 |
+| --- | --- |
+| `namespace` | `rokid.tools` |
+| `method` | `invoke` |
+| `toolName` | `tts` |
+| `toolAction` | `start` |
+
+请求协议版本为字符串 `"2.0.0"`。
+
+### 错误
+
+fetch 失败、响应协议不正确或 Native 未受理时，Promise 会抛出 `Glass3Error`。常见错误码包括 `NATIVE_REQUEST_ERROR` 和 `NATIVE_REQUEST_NOT_ACCEPTED`。
+
+## `tts.stop`
+
+停止一次由 `tts.speak` 发起的播放。
+
+```js
+const playback = await glass3.tts.speak({
+  text: '你好，这是一段播报。',
+  queueMode: 'flush'
+});
+
+const result = await glass3.tts.stop({
+  requestId: playback.requestId
+});
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `requestId` | `string` | 是 | `tts.speak` 返回的播放 requestId。只允许传该字段。 |
+
+SDK 会把参数转换为 Native 的 `args`：
+
+```js
+{
+  targetRequestId: playback.requestId
+}
+```
+
+`tts.stop` 会为停止调用创建一个新的 requestId。停止调用的 requestId 与 `targetRequestId` 相互独立。
+
+### 返回值
+
+请求通过校验后，Promise 在收到停止调用自身 requestId 对应的以下任一消息时完成：
+
+- `kind: "event"` 且 `data.result.state: "stopped"`；
+- `kind: "response"` 且 `result.state: "stopped"`。
+
+SDK 会将两种消息结构统一为：
+
+```js
+{
+  requestId: '本次 stop 调用的 UUID',
+  ok: true,
+  state: 'stopped'
+}
+```
+
+`tts.stop` 不提供 `onEvent`。它只等待自己的停止结果，不会主动清理或修改原 `tts.speak` 的事件监听。原播放过程仍可通过自己的 `onEvent` 接收 `canceled` 等事件。
+
+### Native 映射
+
+| 字段 | 值 |
+| --- | --- |
+| `namespace` | `rokid.tools` |
+| `method` | `invoke` |
+| `toolName` | `tts` |
+| `toolAction` | `stop` |
+
+请求协议版本为字符串 `"2.0.0"`。
+
+### 错误
+
+- 参数缺失、类型错误或包含 `requestId` 以外的字段时，Promise 会抛出错误码为 `INVALID_PARAMS` 的 `Glass3Error`。
+- fetch 失败、响应协议不正确或 Native 未受理时，Promise 会按通用 RPC 错误规则抛出 `Glass3Error`。
+- Native 事件返回 `ok: false` 时，Promise 会抛出错误码为 `NATIVE_EVENT_ERROR` 的 `Glass3Error`。

package/sdk/utils/api-builder.js

@@ -0,0 +1,16 @@
+export function createApiNamespaces(client, apiMap) {
+  const api = {};
+
+  apiMap.forEach(definition => {
+    if (!api[definition.publicModule]) {
+      api[definition.publicModule] = {};
+    }
+
+    api[definition.publicModule][definition.publicMethod] =
+      function invokeMappedMethod(args, options) {
+        return client.invoke(definition, args, options);
+      };
+  });
+
+  return api;
+}

package/sdk/utils/case.js

@@ -0,0 +1,19 @@
+export function snakeStringToCamelCase(value) {
+  return value.replace(/_([a-z])/g, (match, letter) => letter.toUpperCase());
+}
+
+export function snakeToCamelCase(value) {
+  if (Array.isArray(value)) {
+    return value.map(item => snakeToCamelCase(item));
+  }
+
+  if (!value || typeof value !== 'object') {
+    return value;
+  }
+
+  const converted = {};
+  Object.keys(value).forEach(key => {
+    converted[snakeStringToCamelCase(key)] = snakeToCamelCase(value[key]);
+  });
+  return converted;
+}

package/sdk/utils/errors.js

@@ -0,0 +1,32 @@
+export class Glass3Error extends Error {
+  constructor(message, options) {
+    super(message);
+    const errorOptions = options || {};
+
+    this.name = 'Glass3Error';
+    this.code = errorOptions.code || 'GLASS3_ERROR';
+    this.stage = errorOptions.stage;
+    this.requestId = errorOptions.requestId;
+    this.namespace = errorOptions.namespace;
+    this.method = errorOptions.method;
+    this.details = errorOptions.details;
+    this.cause = errorOptions.cause;
+  }
+}
+
+export function normalizeError(error, context) {
+  if (error instanceof Glass3Error) return error;
+
+  const errorContext = context || {};
+  return new Glass3Error(
+    error && error.message ? error.message : 'Glass3 call failed',
+    {
+      code: errorContext.code,
+      stage: errorContext.stage,
+      requestId: errorContext.requestId,
+      namespace: errorContext.namespace,
+      method: errorContext.method,
+      cause: error
+    }
+  );
+}

package/sdk/utils/events.js

@@ -0,0 +1,22 @@
+export function invokeEventCallback(callback, message) {
+  if (typeof callback !== 'function') return;
+
+  console.log('[glass3] onEvent result:', JSON.stringify(message));
+
+  try {
+    const callbackResult = callback(message);
+    if (callbackResult && typeof callbackResult.catch === 'function') {
+      callbackResult.catch(error => {
+        console.error(
+          '[glass3] onEvent callback failed:',
+          JSON.stringify(error)
+        );
+      });
+    }
+  } catch (error) {
+    console.error(
+      '[glass3] onEvent callback failed:',
+      JSON.stringify(error)
+    );
+  }
+}

package/sdk/utils/message.js

@@ -0,0 +1,63 @@
+import {
+  RPC_ORIGIN,
+  RPC_VERSION
+} from '../core/constants.js';
+
+export function extractHostRpcMessage(messageEvent) {
+  if (!messageEvent || messageEvent.origin !== RPC_ORIGIN) return null;
+
+  const rpcMessage = messageEvent.data;
+
+  if (!rpcMessage || rpcMessage.version !== RPC_VERSION) {
+    return null;
+  }
+
+  return rpcMessage;
+}
+
+function isSensitiveFieldName(name) {
+  const normalizedName = String(name).toLowerCase().replace(/[^a-z0-9]/g, '');
+  return normalizedName.indexOf('token') !== -1 ||
+    normalizedName.indexOf('authorization') !== -1 ||
+    normalizedName.indexOf('cookie') !== -1 ||
+    normalizedName.indexOf('secretkey') !== -1 ||
+    normalizedName === 'customerprofile';
+}
+
+function cloneWithoutSensitiveFields(value, redactPhotoBase64) {
+  if (Array.isArray(value)) {
+    return value.map(item => (
+      cloneWithoutSensitiveFields(item, redactPhotoBase64)
+    ));
+  }
+
+  if (!value || typeof value !== 'object') return value;
+
+  const sanitized = {};
+  Object.keys(value).forEach(key => {
+    if (isSensitiveFieldName(key)) return;
+
+    if (
+      redactPhotoBase64 &&
+      (key === 'photo_base64' || key === 'photoBase64') &&
+      typeof value[key] === 'string'
+    ) {
+      sanitized[key] = `[omitted ${value[key].length} base64 chars]`;
+      return;
+    }
+
+    sanitized[key] = cloneWithoutSensitiveFields(
+      value[key],
+      redactPhotoBase64
+    );
+  });
+  return sanitized;
+}
+
+export function stripSensitiveFields(value) {
+  return cloneWithoutSensitiveFields(value, false);
+}
+
+export function redactSensitiveDataForLog(value) {
+  return cloneWithoutSensitiveFields(value, true);
+}

package/sdk/utils/request-id.js

@@ -0,0 +1,18 @@
+const HEX_DIGITS = '0123456789abcdef';
+
+export function createRequestId() {
+  const uuid = new Array(36);
+
+  for (let index = 0; index < uuid.length; index += 1) {
+    uuid[index] = HEX_DIGITS[Math.floor(Math.random() * 16)];
+  }
+
+  uuid[8] = '-';
+  uuid[13] = '-';
+  uuid[18] = '-';
+  uuid[23] = '-';
+  uuid[14] = '4';
+  uuid[19] = HEX_DIGITS[(parseInt(uuid[19], 16) & 0x3) | 0x8];
+
+  return uuid.join('');
+}