rvis-aiui-kit 1.0.0

package/sdk/modules/device-context/index.js

@@ -0,0 +1,206 @@
+import {
+  COMPLETION_EVENT,
+  COMPLETION_READY_EVENT_STREAM
+} from '../../core/constants.js';
+import { Glass3Error } from '../../utils/errors.js';
+import { stripSensitiveFields } from '../../utils/message.js';
+
+const DEVICE_CONTEXT_DOMAINS = [
+  'identity',
+  'software',
+  'account',
+  'environment',
+  'power',
+  'network',
+  'interaction'
+];
+
+function createParameterError(message) {
+  return new Glass3Error(message, {
+    code: 'INVALID_PARAMS',
+    stage: 'params',
+    namespace: 'rokid.tools',
+    method: 'invoke'
+  });
+}
+
+function buildContextArgs(args, methodName) {
+  if (
+    args !== undefined &&
+    args !== null &&
+    (typeof args !== 'object' || Array.isArray(args))
+  ) {
+    throw createParameterError(
+      `deviceContext.${methodName} parameters must be an object`
+    );
+  }
+
+  const input = args || {};
+  const fields = Object.keys(input);
+  fields.forEach(name => {
+    if (name !== 'domains') {
+      throw createParameterError(
+        `deviceContext.${methodName} does not support ${name}`
+      );
+    }
+  });
+
+  if (input.domains === undefined) return {};
+
+  if (!Array.isArray(input.domains) || input.domains.length === 0) {
+    throw createParameterError(
+      `deviceContext.${methodName} domains must be a non-empty array`
+    );
+  }
+
+  input.domains.forEach((domain, index) => {
+    if (typeof domain !== 'string') {
+      throw createParameterError(
+        `deviceContext.${methodName} domains[${index}] must be a string`
+      );
+    }
+
+    if (DEVICE_CONTEXT_DOMAINS.indexOf(domain) === -1) {
+      throw createParameterError(
+        `deviceContext.${methodName} does not support domain ${domain}`
+      );
+    }
+  });
+
+  return { domains: input.domains.slice() };
+}
+
+function buildGetArgs(args) {
+  return buildContextArgs(args, 'get');
+}
+
+function buildObserveArgs(args) {
+  return buildContextArgs(args, 'observe');
+}
+
+function buildStopObserveArgs(args) {
+  if (
+    !args ||
+    typeof args !== 'object' ||
+    Array.isArray(args) ||
+    typeof args.requestId !== 'string' ||
+    !args.requestId.trim()
+  ) {
+    throw createParameterError(
+      'deviceContext.stopObserve requires a requestId'
+    );
+  }
+
+  const fields = Object.keys(args);
+  if (fields.length !== 1 || fields[0] !== 'requestId') {
+    throw createParameterError(
+      'deviceContext.stopObserve only supports requestId'
+    );
+  }
+
+  return { targetRequestId: args.requestId };
+}
+
+function isStartedResponse(result, requestId) {
+  return Boolean(
+    result &&
+    result.accepted === true &&
+    result.requestId === requestId &&
+    result.toolName === 'observeDeviceContext' &&
+    result.toolAction === 'start' &&
+    result.state === 'started'
+  );
+}
+
+function selectContextEventResult(eventData) {
+  return Object.assign(
+    { requestId: eventData.requestId },
+    stripSensitiveFields(eventData.result)
+  );
+}
+
+const deviceContextGet = {
+  publicModule: 'deviceContext',
+  publicMethod: 'get',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'getDeviceContext',
+  toolAction: 'start',
+
+  completion: COMPLETION_EVENT,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  buildArgs: buildGetArgs,
+  transformEventResult: stripSensitiveFields,
+  isTerminalResult(result) {
+    return Boolean(result && result.eventType === 'snapshot');
+  },
+  selectEventResult: selectContextEventResult
+};
+
+const deviceContextObserve = {
+  publicModule: 'deviceContext',
+  publicMethod: 'observe',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'observeDeviceContext',
+  toolAction: 'start',
+
+  completion: COMPLETION_READY_EVENT_STREAM,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  responseCompletionStates: ['started'],
+  buildArgs: buildObserveArgs,
+  transformEventResult: stripSensitiveFields,
+  isAcceptedResponseResult: isStartedResponse,
+  isErrorResult(result) {
+    return Boolean(result && result.ok === false);
+  },
+  isStreamTerminalResult(result) {
+    return Boolean(
+      result &&
+      (
+        result.eventType === 'invalidated' ||
+        result.state === 'canceled'
+      )
+    );
+  },
+  selectReadyResult(requestId, result) {
+    return {
+      requestId,
+      ok: result.ok,
+      state: result.state
+    };
+  }
+};
+
+const deviceContextStopObserve = {
+  publicModule: 'deviceContext',
+  publicMethod: 'stopObserve',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'observeDeviceContext',
+  toolAction: 'stop',
+
+  completion: COMPLETION_EVENT,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  terminalStates: ['stopped'],
+  buildArgs: buildStopObserveArgs,
+  transformEventResult: stripSensitiveFields,
+  releaseTargetInvocation: {
+    publicModule: 'deviceContext',
+    publicMethod: 'observe'
+  },
+  selectEventResult: selectContextEventResult
+};
+
+export { DEVICE_CONTEXT_DOMAINS };
+export default [
+  deviceContextGet,
+  deviceContextObserve,
+  deviceContextStopObserve
+];

package/sdk/modules/device-context/readme.md

@@ -0,0 +1,243 @@
+# Device Context API
+
+`deviceContext` 模块通过 `glass3.deviceContext` 提供设备上下文查询和订阅能力，覆盖
+设备、软件、账号、运行环境、电量、网络与交互状态。
+
+页面必须在 `onMessage` 中调用 `glass3.handleMessage(messageEvent)`，查询结果和订阅
+事件才能被关联到对应请求。订阅结束前应保存 start requestId，并在页面卸载时调用
+`stopObserve`。
+
+## API
+
+| API | 说明 |
+| --- | --- |
+| `deviceContext.get(options?)` | 一次性获取原子上下文快照。 |
+| `deviceContext.observe(options?, callOptions?)` | 订阅初始快照与后续状态变化。 |
+| `deviceContext.stopObserve({ requestId })` | 停止指定订阅。 |
+
+## Domain
+
+`get` 和 `observe` 接受相同的可选参数：
+
+```js
+{
+  domains: ['identity', 'software', 'account', 'environment']
+}
+```
+
+可选 domain：
+
+```text
+identity, software, account, environment, power, network, interaction
+```
+
+- 省略整个参数、传 `{}` 或传 `{ domains: undefined }` 表示全部 domain；SDK 不会
+  将其展开为固定列表。
+- 显式传入 `domains` 时必须是非空数组，每个元素必须是支持的字符串。
+- 协议未禁止重复 domain，SDK 不主动去重或拒绝。
+- 参数对象是闭合结构，不接受其他字段。
+
+参数不合法时抛出 `code: "INVALID_PARAMS"` 的 `Glass3Error`。
+
+## `deviceContext.get`
+
+```js
+const result = await glass3.deviceContext.get({
+  domains: ['environment', 'power', 'network', 'interaction']
+});
+
+console.log(JSON.stringify(result.snapshot));
+```
+
+accepted response 只表示 Native 已受理。Promise 等到唯一的
+`eventType: "snapshot"` 业务事件后完成：
+
+```js
+{
+  requestId: 'get request UUID',
+  ok: true,
+  eventType: 'snapshot',
+  snapshot: {
+    schemaVersion: '1.0',
+    epoch: 'system-server-process-uuid',
+    revision: 12,
+    capturedAtElapsedMs: 368219,
+    environment: {
+      envType: 'custom',
+      customBaseUrl: 'https://private.example.com/base',
+      endpoints: {
+        apiBaseUrl: 'https://private.example.com/base',
+        h5BaseUrl: 'https://private.example.com/base',
+        inspectH5BaseUrl: 'https://private.example.com/base'
+      },
+      environmentRevision: 2
+    },
+    power: {
+      available: true,
+      levelPercent: 76,
+      charging: false,
+      plugType: 'none'
+    },
+    network: {
+      wifiEnabled: true,
+      localConnected: true,
+      localValidated: true,
+      metered: false,
+      transport: 'wifi',
+      rssi: -54,
+      effectiveRoute: 'glass_direct',
+      online: true
+    },
+    interaction: {
+      screenState: 'on'
+    }
+  }
+}
+```
+
+## `deviceContext.observe`
+
+```js
+const observer = await glass3.deviceContext.observe(
+  {
+    domains: ['account', 'environment', 'power', 'network']
+  },
+  {
+    onEvent(event) {
+      switch (event.eventType) {
+        case 'snapshot':
+          initializeContext(event.snapshot);
+          break;
+        case 'changed':
+          applyContextPatch(event);
+          break;
+        case 'invalidated':
+          clearAccountContext();
+          reloadScene();
+          break;
+      }
+    }
+  }
+);
+```
+
+Promise 在合法的 started response 到达后完成：
+
+```js
+{
+  requestId: 'observe request UUID',
+  ok: true,
+  state: 'started'
+}
+```
+
+要接收初始快照与后续通知，必须提供 `callOptions.onEvent`。首个业务事件固定为
+`eventType: "snapshot"`，结构与 `get` 的 snapshot 事件相同。
+
+实际状态发生边沿变化后，Native 发送增量事件：
+
+```js
+{
+  ok: true,
+  eventType: 'changed',
+  schemaVersion: '1.0',
+  epoch: 'system-server-process-uuid',
+  baseRevision: 12,
+  revision: 13,
+  changedAtElapsedMs: 369100,
+  changedDomains: ['power'],
+  reason: 'battery_changed',
+  patch: {
+    power: {
+      available: true,
+      levelPercent: 75,
+      charging: false,
+      plugType: 'none'
+    }
+  }
+}
+```
+
+SDK 不缓存快照，也不自动合并 patch。调用方合并前必须验证：
+
+```js
+event.epoch === currentSnapshot.epoch &&
+event.baseRevision === currentSnapshot.revision
+```
+
+epoch 不同或 revision 不连续时，不应继续使用旧上下文；应重新查询或重载 Scene。
+
+账号或环境发生隔离边界变化时，Native 发送终态：
+
+```js
+{
+  ok: true,
+  eventType: 'invalidated',
+  state: 'canceled',
+  reason: 'context_invalidated',
+  invalidatedDomains: ['account', 'environment'],
+  requiresReload: true,
+  epoch: 'system-server-process-uuid',
+  revision: 14
+}
+```
+
+该事件会先进入 `onEvent`，随后 SDK 释放订阅监听。调用方必须停止使用旧上下文、
+清除账号相关内存状态并重载 Scene；重载后重新订阅。SDK 不自动执行导航或重载。
+
+## `deviceContext.stopObserve`
+
+```js
+const result = await glass3.deviceContext.stopObserve({
+  requestId: observer.requestId
+});
+```
+
+SDK 将公共参数转换为：
+
+```js
+{ targetRequestId: observer.requestId }
+```
+
+stop 使用独立 requestId，并等待归属于 stop 调用的 stopped event：
+
+```js
+{
+  requestId: 'stop request UUID',
+  ok: true,
+  state: 'stopped'
+}
+```
+
+完成后 SDK 释放目标 observe 的本地监听。协议不会再为原 observe requestId 补发
+第二个终态。
+
+## 可选字段和枚举值
+
+SDK 保留协议字段名和枚举值，不为缺失字段补默认值：
+
+- 电量不可读时没有 `levelPercent`。
+- 非 Wi-Fi 网络没有 `rssi`。
+- 非 custom 环境没有 `customBaseUrl`。
+- `effectiveRoute: "phone_relay"` 时，手机在线状态未同步，首版没有 `online`；不能
+  将眼镜本地网络状态推断为手机中继可用性。
+- `logged_in`、`glass_direct`、`phone_relay` 等枚举字符串不会转成 camelCase。
+
+需要区分 `false` 与“未提供”时，应检查字段是否存在。
+
+## 敏感信息
+
+协议不允许 token、Authorization、Cookie、secretKey 或任何 token 字段进入返回值、
+事件、Schema 和日志。SDK 对业务结果和日志额外执行递归清理；`identity.customerProfile`
+当前不属于公开结构。
+
+## Native 映射
+
+| SDK | `toolName` | `toolAction` |
+| --- | --- | --- |
+| `deviceContext.get` | `getDeviceContext` | `start` |
+| `deviceContext.observe` | `observeDeviceContext` | `start` |
+| `deviceContext.stopObserve` | `observeDeviceContext` | `stop` |
+
+全部调用使用 RPC `version: "2.0.0"`、`namespace: "rokid.tools"`、
+`method: "invoke"`。

package/sdk/modules/face/index.js

@@ -0,0 +1,108 @@
+import {
+  COMPLETION_EVENT,
+  COMPLETION_READY_EVENT_STREAM
+} from '../../core/constants.js';
+import { snakeToCamelCase } from '../../utils/case.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 buildStartRecognizeArgs(args) {
+  if (args === undefined || args === null) return {};
+
+  if (
+    typeof args !== 'object' ||
+    Array.isArray(args) ||
+    Object.keys(args).length !== 0
+  ) {
+    throw createParameterError('face.startRecognize does not accept parameters');
+  }
+
+  return {};
+}
+
+function buildStopRecognizeArgs(args) {
+  if (
+    !args ||
+    typeof args !== 'object' ||
+    Array.isArray(args) ||
+    typeof args.requestId !== 'string' ||
+    !args.requestId
+  ) {
+    throw createParameterError('face.stopRecognize requires a requestId');
+  }
+
+  const inputFields = Object.keys(args);
+  if (inputFields.length !== 1 || inputFields[0] !== 'requestId') {
+    throw createParameterError('face.stopRecognize only supports requestId');
+  }
+
+  return {
+    targetRequestId: args.requestId
+  };
+}
+
+const faceStartRecognize = {
+  publicModule: 'face',
+  publicMethod: 'startRecognize',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'faceRecognize',
+  toolAction: 'start',
+
+  completion: COMPLETION_READY_EVENT_STREAM,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  responseCompletionStates: ['started'],
+  buildArgs: buildStartRecognizeArgs,
+  transformEventResult: snakeToCamelCase,
+  isErrorResult(result) {
+    return Boolean(result && result.ok === false);
+  },
+  isReadyResult(result) {
+    return Boolean(result && result.state === 'started');
+  },
+  isStreamTerminalResult(result) {
+    return Boolean(result && result.state === 'stopped');
+  },
+  selectReadyResult(requestId, result) {
+    return {
+      requestId,
+      ok: result.ok
+    };
+  }
+};
+
+const faceStopRecognize = {
+  publicModule: 'face',
+  publicMethod: 'stopRecognize',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'faceRecognize',
+  toolAction: 'stop',
+
+  completion: COMPLETION_EVENT,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  terminalStates: ['stopped'],
+  responseCompletionStates: ['stopped'],
+  buildArgs: buildStopRecognizeArgs,
+  transformEventResult: snakeToCamelCase,
+  selectEventResult(eventData) {
+    return Object.assign(
+      { requestId: eventData.requestId },
+      snakeToCamelCase(eventData.result)
+    );
+  }
+};
+
+export default [faceStartRecognize, faceStopRecognize];