rvis-aiui-kit 1.0.0

package/sdk/modules/camera/index.js

@@ -0,0 +1,380 @@
+import {
+  COMPLETION_EVENT,
+  COMPLETION_READY_EVENT_STREAM
+} from '../../core/constants.js';
+import { snakeToCamelCase } from '../../utils/case.js';
+import { Glass3Error } from '../../utils/errors.js';
+
+const PREVIEW_LAYOUT_FIELDS = [
+  'left',
+  'top',
+  'width',
+  'height',
+  'cornerRadius'
+];
+
+const PREVIEW_FIELDS = PREVIEW_LAYOUT_FIELDS.concat('outline');
+
+const DEFAULT_PREVIEW_ARGS = {
+  left: 0,
+  top: 40,
+  width: 168,
+  height: 103,
+  cornerRadius: 2,
+  outline: true
+};
+
+function createParameterError(message) {
+  return new Glass3Error(message, {
+    code: 'INVALID_PARAMS',
+    stage: 'params',
+    namespace: 'rokid.tools',
+    method: 'invoke'
+  });
+}
+
+function validatePreviewValue(name, value) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw createParameterError(`camera.startPreview ${name} must be a finite number`);
+  }
+
+  if ((name === 'width' || name === 'height') && value <= 0) {
+    throw createParameterError(`camera.startPreview ${name} must be greater than 0`);
+  }
+
+  if (
+    (name === 'left' || name === 'top' || name === 'cornerRadius') &&
+    value < 0
+  ) {
+    throw createParameterError(`camera.startPreview ${name} must not be negative`);
+  }
+}
+
+function buildStartPreviewArgs(args) {
+  if (
+    args !== undefined &&
+    args !== null &&
+    (typeof args !== 'object' || Array.isArray(args))
+  ) {
+    throw createParameterError('camera.startPreview parameters must be an object');
+  }
+
+  const input = args || {};
+  const inputFields = Object.keys(input);
+  let suppliedLayoutCount = 0;
+
+  PREVIEW_LAYOUT_FIELDS.forEach(name => {
+    if (Object.prototype.hasOwnProperty.call(input, name)) {
+      suppliedLayoutCount += 1;
+    }
+  });
+
+  inputFields.forEach(name => {
+    if (PREVIEW_FIELDS.indexOf(name) === -1) {
+      throw createParameterError(`camera.startPreview does not support ${name}`);
+    }
+  });
+
+  if (inputFields.length === 0) {
+    return {
+      left: DEFAULT_PREVIEW_ARGS.left,
+      top: DEFAULT_PREVIEW_ARGS.top,
+      width: DEFAULT_PREVIEW_ARGS.width,
+      height: DEFAULT_PREVIEW_ARGS.height,
+      cornerRadius: DEFAULT_PREVIEW_ARGS.cornerRadius,
+      outline: DEFAULT_PREVIEW_ARGS.outline
+    };
+  }
+
+  if (
+    suppliedLayoutCount !== 0 &&
+    suppliedLayoutCount !== PREVIEW_LAYOUT_FIELDS.length
+  ) {
+    throw createParameterError(
+      'camera.startPreview requires left, top, width, height and cornerRadius together'
+    );
+  }
+
+  if (
+    Object.prototype.hasOwnProperty.call(input, 'outline') &&
+    typeof input.outline !== 'boolean'
+  ) {
+    throw createParameterError('camera.startPreview outline must be a boolean');
+  }
+
+  PREVIEW_LAYOUT_FIELDS.forEach(name => {
+    if (suppliedLayoutCount > 0) {
+      validatePreviewValue(name, input[name]);
+    }
+  });
+
+  return {
+    left: suppliedLayoutCount > 0 ? input.left : DEFAULT_PREVIEW_ARGS.left,
+    top: suppliedLayoutCount > 0 ? input.top : DEFAULT_PREVIEW_ARGS.top,
+    width: suppliedLayoutCount > 0 ? input.width : DEFAULT_PREVIEW_ARGS.width,
+    height: suppliedLayoutCount > 0 ? input.height : DEFAULT_PREVIEW_ARGS.height,
+    cornerRadius: suppliedLayoutCount > 0
+      ? input.cornerRadius
+      : DEFAULT_PREVIEW_ARGS.cornerRadius,
+    outline: input.outline === undefined
+      ? DEFAULT_PREVIEW_ARGS.outline
+      : input.outline
+  };
+}
+
+function buildStopPreviewArgs(args) {
+  if (!args || typeof args.requestId !== 'string' || !args.requestId) {
+    throw createParameterError('camera.stopPreview requires a requestId');
+  }
+
+  return {
+    targetRequestId: args.requestId
+  };
+}
+
+function buildTakePhotoArgs(args) {
+  if (
+    args !== undefined &&
+    args !== null &&
+    (typeof args !== 'object' || Array.isArray(args))
+  ) {
+    throw createParameterError('camera.takePhoto parameters must be an object');
+  }
+
+  const input = args || {};
+  const inputFields = Object.keys(input);
+  inputFields.forEach(name => {
+    if (
+      name !== 'returnBase64' &&
+      name !== 'upload' &&
+      name !== 'timeout'
+    ) {
+      throw createParameterError(`camera.takePhoto does not support ${name}`);
+    }
+  });
+
+  const returnBase64 = input.returnBase64 === undefined
+    ? true
+    : input.returnBase64;
+  const upload = input.upload === undefined ? false : input.upload;
+
+  if (typeof returnBase64 !== 'boolean') {
+    throw createParameterError(
+      'camera.takePhoto returnBase64 must be a boolean'
+    );
+  }
+
+  if (typeof upload !== 'boolean') {
+    throw createParameterError('camera.takePhoto upload must be a boolean');
+  }
+
+  const timeout = input.timeout === undefined ? 5000 : input.timeout;
+  if (!Number.isInteger(timeout) || timeout <= 0) {
+    throw createParameterError(
+      'camera.takePhoto timeout must be a positive integer in milliseconds'
+    );
+  }
+
+  return { returnBase64, upload };
+}
+
+function getTakePhotoTimeoutMs(args) {
+  const input = args || {};
+  return input.timeout === undefined ? 5000 : input.timeout;
+}
+
+function buildStartTakeVideoArgs(args) {
+  if (
+    args !== undefined &&
+    args !== null &&
+    (typeof args !== 'object' || Array.isArray(args))
+  ) {
+    throw createParameterError(
+      'camera.startTakeVideo parameters must be an object'
+    );
+  }
+
+  const input = args || {};
+  const inputFields = Object.keys(input);
+  inputFields.forEach(name => {
+    if (name !== 'enableAudio' && name !== 'segmentMinutes') {
+      throw createParameterError(
+        `camera.startTakeVideo does not support ${name}`
+      );
+    }
+  });
+
+  const enableAudio = input.enableAudio === undefined
+    ? true
+    : input.enableAudio;
+  const segmentMinutes = input.segmentMinutes === undefined
+    ? 20
+    : input.segmentMinutes;
+
+  if (typeof enableAudio !== 'boolean') {
+    throw createParameterError(
+      'camera.startTakeVideo enableAudio must be a boolean'
+    );
+  }
+
+  if (!Number.isInteger(segmentMinutes) || segmentMinutes <= 0) {
+    throw createParameterError(
+      'camera.startTakeVideo segmentMinutes must be a positive integer'
+    );
+  }
+
+  return {
+    enable_audio: enableAudio,
+    segment_minutes: segmentMinutes
+  };
+}
+
+function buildStopTakeVideoArgs(args) {
+  if (
+    !args ||
+    typeof args !== 'object' ||
+    Array.isArray(args) ||
+    typeof args.requestId !== 'string' ||
+    !args.requestId
+  ) {
+    throw createParameterError('camera.stopTakeVideo requires a requestId');
+  }
+
+  const inputFields = Object.keys(args);
+  if (inputFields.length !== 1 || inputFields[0] !== 'requestId') {
+    throw createParameterError('camera.stopTakeVideo only supports requestId');
+  }
+
+  return {
+    targetRequestId: args.requestId
+  };
+}
+
+function selectEventResult(eventData) {
+  return Object.assign(
+    { requestId: eventData.requestId },
+    eventData.result
+  );
+}
+
+const cameraStartPreview = {
+  publicModule: 'camera',
+  publicMethod: 'startPreview',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'cameraPreview',
+  toolAction: 'start',
+
+  completion: COMPLETION_EVENT,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  terminalStates: ['started'],
+  responseCompletionStates: ['started'],
+  buildArgs: buildStartPreviewArgs,
+  selectEventResult
+};
+
+const cameraStopPreview = {
+  publicModule: 'camera',
+  publicMethod: 'stopPreview',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'cameraPreview',
+  toolAction: 'stop',
+
+  completion: COMPLETION_EVENT,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  terminalStates: ['cancel'],
+  buildArgs: buildStopPreviewArgs,
+  selectEventResult
+};
+
+const cameraTakePhoto = {
+  publicModule: 'camera',
+  publicMethod: 'takePhoto',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'takePhoto',
+  toolAction: 'start',
+
+  completion: COMPLETION_EVENT,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  isTerminalResult(result) {
+    return Boolean(result && result.ok === true);
+  },
+  buildArgs: buildTakePhotoArgs,
+  getTimeoutMs: getTakePhotoTimeoutMs,
+  transformEventResult: snakeToCamelCase,
+  selectEventResult(eventData) {
+    return Object.assign(
+      { requestId: eventData.requestId },
+      snakeToCamelCase(eventData.result)
+    );
+  }
+};
+
+const cameraStartTakeVideo = {
+  publicModule: 'camera',
+  publicMethod: 'startTakeVideo',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'lawEnforcementRecord',
+  toolAction: 'start',
+
+  completion: COMPLETION_READY_EVENT_STREAM,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  eventToolActions: ['start', 'stop'],
+  responseCompletionStates: ['started'],
+  buildArgs: buildStartTakeVideoArgs,
+  transformEventResult: snakeToCamelCase,
+  isReadyResult(result) {
+    return result.state === 'started';
+  },
+  isStreamTerminalResult(result) {
+    return result.hasMore === false || result.state === 'canceled';
+  },
+  selectReadyResult(requestId, result) {
+    return {
+      requestId,
+      ok: result.ok
+    };
+  }
+};
+
+const cameraStopTakeVideo = {
+  publicModule: 'camera',
+  publicMethod: 'stopTakeVideo',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'lawEnforcementRecord',
+  toolAction: 'stop',
+
+  completion: COMPLETION_EVENT,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  terminalStates: ['finished'],
+  buildArgs: buildStopTakeVideoArgs,
+  transformEventResult: snakeToCamelCase,
+  selectEventResult(eventData) {
+    return Object.assign(
+      { requestId: eventData.requestId },
+      snakeToCamelCase(eventData.result)
+    );
+  }
+};
+
+export default [
+  cameraStartPreview,
+  cameraStopPreview,
+  cameraTakePhoto,
+  cameraStartTakeVideo,
+  cameraStopTakeVideo
+];

package/sdk/modules/camera/readme.md

@@ -0,0 +1,302 @@
+# Camera API
+
+Camera 模块通过 `glass3.camera` 暴露拍照、相机预览和分段录像能力。
+
+页面必须把宿主的 `onMessage` 消息交给 `glass3.handleMessage`。页面销毁时可调用 `glass3.dispose()` 清理仍在等待的本地调用。
+
+```js
+import glass3 from 'rvis-aiui-kit';
+```
+
+以上路径适用于 `pages` 下的一级页面，其他目录层级需要相应调整相对路径。
+
+## API 列表
+
+| API | 说明 |
+| --- | --- |
+| `camera.startPreview` | 开启相机画面预览。 |
+| `camera.stopPreview` | 关闭指定的相机预览。 |
+| `camera.takePhoto` | 拍摄照片并等待 Native 返回照片结果。 |
+| `camera.startTakeVideo` | 开始分段录像并持续接收文件事件。 |
+| `camera.stopTakeVideo` | 停止指定的录像。 |
+
+## `camera.startPreview`
+
+```js
+const preview = await glass3.camera.startPreview();
+```
+
+不传参数或传空对象时，SDK 会补齐以下默认值：
+
+```js
+{
+  left: 0,
+  top: 40,
+  width: 168,
+  height: 103,
+  cornerRadius: 2,
+  outline: true
+}
+```
+
+也可以自定义预览区域：
+
+```js
+const preview = await glass3.camera.startPreview({
+  left: 40,
+  top: 60,
+  width: 240,
+  height: 180,
+  cornerRadius: 16,
+  outline: false
+});
+```
+
+只要传入任意一个位置或尺寸参数，就必须同时传入全部五个区域字段。`outline` 可以单独传入；省略时默认为 `true`。SDK 调用 Native 时使用同名的 `outline` 参数。
+
+| 字段 | 类型 | 约束 |
+| --- | --- | --- |
+| `left` | `number` | 有限数字且不能为负数。 |
+| `top` | `number` | 有限数字且不能为负数。 |
+| `width` | `number` | 有限数字且必须大于 `0`。 |
+| `height` | `number` | 有限数字且必须大于 `0`。 |
+| `cornerRadius` | `number` | 有限数字且不能为负数。 |
+| `outline` | `boolean` | 是否使用线框方式呈现预览流画面，默认为 `true`。 |
+
+Promise 在收到以下任一消息后完成：
+
+- `kind: "event"` 且 `data.result.state: "started"`；
+- 已通过请求校验的 `kind: "response"` 且 `result.state: "started"`。
+
+response 消息中的 `ok` 位于外层，而 event 消息中的 `ok` 位于 `data.result`。SDK 会将两种结构统一为以下基础返回格式；event 结果包含的其他 Native 字段仍会保留：
+
+```js
+{
+  requestId: '预览启动 UUID',
+  ok: true,
+  state: 'started'
+}
+```
+
+Native 映射：`rokid.tools / invoke / cameraPreview / start`。
+
+## `camera.stopPreview`
+
+```js
+const result = await glass3.camera.stopPreview({
+  requestId: preview.requestId
+});
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `requestId` | `string` | 是 | `startPreview` 返回的预览启动 ID。 |
+
+SDK 会将其转换为 Native 参数 `targetRequestId`。stop 调用会生成自己的 requestId，并在收到自己的 `state: "cancel"` 事件后完成。
+
+```js
+{
+  requestId: '本次 stop UUID',
+  ok: true,
+  state: 'cancel'
+}
+```
+
+Native 映射：`rokid.tools / invoke / cameraPreview / stop`。
+
+## `camera.takePhoto`
+
+拍摄一张照片。调用不传参数时，SDK 默认要求 Native 返回 Base64，且不上传服务器：
+
+```js
+const photo = await glass3.camera.takePhoto();
+```
+
+也可以显式控制返回方式：
+
+```js
+const photo = await glass3.camera.takePhoto({
+  returnBase64: false,
+  upload: true,
+  timeout: 8000
+});
+```
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `returnBase64` | `boolean` | 否 | `true` | 是否在结果中返回 JPEG Base64。 |
+| `upload` | `boolean` | 否 | `false` | 是否将照片上传服务器。 |
+| `timeout` | `number` | 否 | `5000` | JS 等待照片结果的超时时间，单位毫秒，必须是大于 0 的整数。 |
+
+参数是闭合对象，只支持上面的三个字段。`timeout` 仅用于 JS 侧控制
+Promise，不会发送给 Native。SDK 发送给 Native 的 `args` 仍只包含：
+
+```js
+{
+  returnBase64: false,
+  upload: true
+}
+```
+
+超时从调用 `takePhoto()` 时开始计算，包含等待 Native accepted response 和最终
+照片 event 的时间。fetch 返回 Native 已受理时 Promise 不会完成。只有在超时前
+收到同一 requestId 的成功 `toolResult` 事件后，`await` 才会结束。
+
+超过 `timeout` 后，Promise 会以 `Glass3Error` 拒绝：
+
+```js
+try {
+  await glass3.camera.takePhoto({ timeout: 5000 });
+} catch (error) {
+  if (error.code === 'CALL_TIMEOUT') {
+    // error.stage === 'timeout'
+  }
+}
+```
+
+超时后 SDK 会释放本次调用；随后到达的 response 或照片 event 会被忽略。超时只
+停止 JS 等待，不表示 Native 拍照操作一定被取消。
+
+Native 结果中的下划线字段会递归转换为驼峰，公开返回值示例：
+
+```js
+{
+  requestId: '本次拍照 UUID',
+  ok: true,
+  photoSize: 41056,
+  filePath: '/storage/emulated/0/.../tool_photo_xxx.jpg',
+  width: 1080,
+  height: 720,
+  photoMime: 'image/jpeg',
+  photoBase64: '...',
+  fileUrl: 'https://...',
+  inspectionResultId: 42,
+  uploadError: 'no_session'
+}
+```
+
+`photoMime` 和 `photoBase64` 仅在 `returnBase64: true` 时出现。`fileUrl` 与 `inspectionResultId` 仅在上传成功时出现；上传失败时照片调用本身仍可成功，并通过 `uploadError` 描述上传错误。
+
+Native 映射：`rokid.tools / invoke / takePhoto / start`。
+
+## `camera.startTakeVideo`
+
+开始分段录像。请求通过校验后，Promise 在收到以下任一消息时完成：
+
+- `kind: "event"` 且 `data.result.state: "started"`；
+- `kind: "response"` 且 `result.state: "started"`。
+
+后续分段文件继续通过 `onEvent` 回调。response 不会作为 event 传给 `onEvent`。
+
+```js
+const recording = await glass3.camera.startTakeVideo(
+  {
+    enableAudio: true,
+    segmentMinutes: 20
+  },
+  {
+    onEvent(eventResult) {
+      console.log('recording event:', JSON.stringify(eventResult));
+    }
+  }
+);
+```
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `enableAudio` | `boolean` | 否 | `true` | 是否录音。发送给 Native 时转换为 `enable_audio`。 |
+| `segmentMinutes` | `number` | 否 | `20` | 分段时长，必须是正整数。发送给 Native 时转换为 `segment_minutes`。 |
+
+启动返回值：
+
+```js
+{
+  requestId: '录像启动 UUID',
+  ok: true
+}
+```
+
+`onEvent` 包含启动事件、每一段文件事件和异常事件。Native 下划线字段会递归转换为驼峰：
+
+```js
+{ ok: true, state: 'started' }
+
+{ ok: true, state: 'canceled' }
+
+{
+  ok: true,
+  filePath: '/storage/emulated/0/Pictures/example.mp4',
+  startTime: 1784543000000,
+  endTime: 1784544200000,
+  hasMore: true
+}
+
+{
+  ok: false,
+  errorCode: 500,
+  error: 'recording failed'
+}
+```
+
+`state: "canceled"` 表示录像被系统停止，而不是开发者主动调用 `stopTakeVideo`。该事件有以下特殊关联规则：
+
+- `requestId` 是原 `startTakeVideo` 的 requestId。
+- `toolName` 是 `lawEnforcementRecord`。
+- `toolAction` 是 `stop`，但事件仍属于原 start 调用。
+- SDK 会先把 `{ ok: true, state: "canceled" }` 透传给 start 的 `onEvent`，然后清理该录像流监听。
+
+Native 原始事件示例：
+
+```json
+{
+  "version": "2.0.0",
+  "kind": "event",
+  "namespace": "rokid.tools",
+  "event": "toolResult",
+  "data": {
+    "requestId": "原 start requestId",
+    "toolName": "lawEnforcementRecord",
+    "toolAction": "stop",
+    "frameId": "",
+    "result": {
+      "ok": true,
+      "state": "canceled"
+    },
+    "extra": {}
+  }
+}
+```
+
+`hasMore: false` 表示最后一段，SDK 同样会在透传该事件后清理监听。启动前收到错误会拒绝 Promise；启动后的错误会通过 `onEvent` 透传并结束事件监听。
+
+下行调用映射为 `rokid.tools / invoke / lawEnforcementRecord / start`。上行事件通常使用 `toolAction: "start"`，系统取消事件使用 `toolAction: "stop"`。
+
+## `camera.stopTakeVideo`
+
+```js
+const result = await glass3.camera.stopTakeVideo({
+  requestId: recording.requestId
+});
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `requestId` | `string` | 是 | `startTakeVideo` 返回的录像启动 ID。只允许传该字段。 |
+
+SDK 会将参数转换成 `{ targetRequestId }`。stop 使用独立 requestId，并在收到自己的 `state: "finished"` 事件后完成。
+
+```js
+{
+  requestId: '本次 stop UUID',
+  ok: true,
+  state: 'finished'
+}
+```
+
+`stopTakeVideo` 与 `startTakeVideo` 的本地事件监听相互独立，stop 不会主动清理 start 的监听。
+
+Native 映射：`rokid.tools / invoke / lawEnforcementRecord / stop`。
+
+## 错误
+
+参数错误会抛出错误码为 `INVALID_PARAMS` 的 `Glass3Error`。Native 事件返回 `ok: false` 时，尚未完成的 Promise 会以 `NATIVE_EVENT_ERROR` 拒绝。