rvis-aiui-kit 1.1.0 → 1.2.1

package/sdk/modules/openapi/client.js

@@ -0,0 +1,517 @@
+import { Glass3Error } from '../../utils/errors.js';
+import { createRequestId } from '../../utils/request-id.js';
+
+const DEFAULT_BASE_URL = 'https://api.rokid.com';
+const VISION_EXTRACT_PATH = '/ar/rvis/openapi/v1/vision/extractions';
+const VISION_EXTRACT_TIMEOUT = 120000;
+const OPENAPI_NAMESPACE = 'rokid.openapi';
+const VISION_EXTRACT_METHOD = 'visionExtract';
+const FIELD_TYPES = ['string', 'number', 'boolean'];
+const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+
+function createOpenApiError(message, options) {
+  const errorOptions = options || {};
+  return new Glass3Error(message, {
+    code: errorOptions.code,
+    stage: errorOptions.stage,
+    requestId: errorOptions.requestId,
+    namespace: OPENAPI_NAMESPACE,
+    method: VISION_EXTRACT_METHOD,
+    details: errorOptions.details,
+    cause: errorOptions.cause
+  });
+}
+
+function createParameterError(message) {
+  return createOpenApiError(message, {
+    code: 'INVALID_PARAMS',
+    stage: 'params'
+  });
+}
+
+function assertPlainObject(value, message) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw createParameterError(message);
+  }
+}
+
+function assertClosedShape(value, allowedFields, methodName) {
+  Object.keys(value).forEach(name => {
+    if (allowedFields.indexOf(name) === -1) {
+      throw createParameterError(`${methodName} does not support ${name}`);
+    }
+  });
+}
+
+function normalizeBaseUrl(value) {
+  const baseUrl = value === undefined ? DEFAULT_BASE_URL : value;
+  if (typeof baseUrl !== 'string' || !baseUrl.trim()) {
+    throw createParameterError('openapi.setConfig baseUrl must be a non-empty string');
+  }
+
+  const normalized = baseUrl.trim().replace(/\/+$/, '');
+  if (normalized.indexOf('https://') !== 0) {
+    throw createParameterError('openapi.setConfig baseUrl must use https');
+  }
+  return normalized;
+}
+
+function validateConfig(options) {
+  assertPlainObject(options, 'openapi.setConfig parameters must be an object');
+  assertClosedShape(options, ['baseUrl', 'apiKey'], 'openapi.setConfig');
+
+  if (typeof options.apiKey !== 'string' || !options.apiKey.trim()) {
+    throw createParameterError('openapi.setConfig apiKey is required');
+  }
+
+  return {
+    baseUrl: normalizeBaseUrl(options.baseUrl),
+    apiKey: options.apiKey.trim()
+  };
+}
+
+function validateField(field, index) {
+  assertPlainObject(
+    field,
+    `openapi.visionExtract fields[${index}] must be an object`
+  );
+  assertClosedShape(
+    field,
+    ['name', 'title', 'type'],
+    `openapi.visionExtract fields[${index}]`
+  );
+
+  if (
+    typeof field.name !== 'string' ||
+    !/^[A-Za-z][A-Za-z0-9_]*$/.test(field.name)
+  ) {
+    throw createParameterError(
+      `openapi.visionExtract fields[${index}].name must be a stable English identifier`
+    );
+  }
+  if (typeof field.title !== 'string' || !field.title.trim()) {
+    throw createParameterError(
+      `openapi.visionExtract fields[${index}].title is required`
+    );
+  }
+  if (FIELD_TYPES.indexOf(field.type) === -1) {
+    throw createParameterError(
+      `openapi.visionExtract fields[${index}].type must be string, number or boolean`
+    );
+  }
+
+  return {
+    name: field.name,
+    title: field.title,
+    type: field.type
+  };
+}
+
+function validateVisionExtractParams(params) {
+  assertPlainObject(
+    params,
+    'openapi.visionExtract parameters must be an object'
+  );
+  assertClosedShape(
+    params,
+    ['image', 'prompt', 'uiType', 'fields'],
+    'openapi.visionExtract'
+  );
+
+  if (typeof params.image !== 'string' || !params.image.trim()) {
+    throw createParameterError('openapi.visionExtract image is required');
+  }
+  const base64Payload = params.image.indexOf('data:') === 0
+    ? params.image.slice(params.image.indexOf(',') + 1)
+    : params.image;
+  const compactPayload = base64Payload.replace(/\s/g, '');
+  const paddingLength = compactPayload.endsWith('==')
+    ? 2
+    : compactPayload.endsWith('=') ? 1 : 0;
+  const estimatedImageBytes = Math.max(
+    0,
+    Math.floor(compactPayload.length * 3 / 4) - paddingLength
+  );
+  if (estimatedImageBytes > MAX_IMAGE_BYTES) {
+    throw createParameterError(
+      'openapi.visionExtract image must not exceed 10MB'
+    );
+  }
+  if (typeof params.prompt !== 'string' || !params.prompt.trim()) {
+    throw createParameterError('openapi.visionExtract prompt is required');
+  }
+  if (params.prompt.length > 8192) {
+    throw createParameterError(
+      'openapi.visionExtract prompt must not exceed 8192 characters'
+    );
+  }
+  if (params.uiType !== 'text' && params.uiType !== 'table') {
+    throw createParameterError(
+      'openapi.visionExtract uiType must be text or table'
+    );
+  }
+
+  const fields = params.fields === undefined ? [] : params.fields;
+  if (!Array.isArray(fields)) {
+    throw createParameterError('openapi.visionExtract fields must be an array');
+  }
+  if (params.uiType === 'table' && (fields.length < 1 || fields.length > 8)) {
+    throw createParameterError(
+      'openapi.visionExtract table fields must contain 1 to 8 items'
+    );
+  }
+  if (params.uiType === 'text' && fields.length > 0) {
+    throw createParameterError(
+      'openapi.visionExtract text fields must be omitted or empty'
+    );
+  }
+
+  const requestParams = {
+    image: params.image,
+    prompt: params.prompt,
+    uiType: params.uiType
+  };
+  if (params.uiType === 'table') {
+    requestParams.fields = fields.map(validateField);
+  }
+  return requestParams;
+}
+
+function validateCallOptions(options) {
+  if (options === undefined) return {};
+  assertPlainObject(
+    options,
+    'openapi.visionExtract call options must be an object'
+  );
+  assertClosedShape(options, ['onEvent'], 'openapi.visionExtract call options');
+  if (
+    options.onEvent !== undefined &&
+    typeof options.onEvent !== 'function'
+  ) {
+    throw createParameterError(
+      'openapi.visionExtract onEvent must be a function'
+    );
+  }
+  return options;
+}
+
+function describeImage(image) {
+  const dataUrlMatch = /^data:([^;,]+);base64,/i.exec(image);
+  return dataUrlMatch
+    ? `[base64 omitted, mime=${dataUrlMatch[1]}, length=${image.length}]`
+    : `[base64 omitted, length=${image.length}]`;
+}
+
+function requestParamsForLog(params) {
+  const sanitized = {
+    image: describeImage(params.image),
+    prompt: params.prompt,
+    uiType: params.uiType
+  };
+  if (params.fields) sanitized.fields = params.fields;
+  return sanitized;
+}
+
+function parseEventData(rawData) {
+  try {
+    return JSON.parse(rawData);
+  } catch (_error) {
+    return rawData;
+  }
+}
+
+function invokeEventCallback(callback, event) {
+  if (typeof callback !== 'function') return;
+  try {
+    const callbackResult = callback(event);
+    if (callbackResult && typeof callbackResult.catch === 'function') {
+      callbackResult.catch(error => {
+        console.error(
+          '[glass3.openapi] onEvent callback failed:',
+          error && error.message ? error.message : String(error)
+        );
+      });
+    }
+  } catch (error) {
+    console.error(
+      '[glass3.openapi] onEvent callback failed:',
+      error && error.message ? error.message : String(error)
+    );
+  }
+}
+
+function errorForLog(error) {
+  return {
+    requestId: error.requestId,
+    code: error.code,
+    stage: error.stage,
+    message: error.message,
+    details: error.details
+  };
+}
+
+export class OpenApiClient {
+  constructor(options) {
+    const clientOptions = options || {};
+    this.createEventSource = clientOptions.createEventSource;
+    this.config = null;
+    this.activeRequests = new Map();
+  }
+
+  setConfig(options) {
+    this.config = validateConfig(options);
+    console.log(
+      '[glass3.openapi] config:',
+      JSON.stringify({
+        baseUrl: this.config.baseUrl,
+        apiKey: '[redacted]'
+      })
+    );
+  }
+
+  visionExtract(params, options) {
+    let requestParams;
+    let callOptions;
+    try {
+      requestParams = validateVisionExtractParams(params);
+      callOptions = validateCallOptions(options);
+      if (!this.config) {
+        throw createOpenApiError(
+          'openapi.setConfig must be called before openapi.visionExtract',
+          {
+            code: 'OPENAPI_NOT_CONFIGURED',
+            stage: 'config'
+          }
+        );
+      }
+      if (typeof this.createEventSource !== 'function') {
+        throw createOpenApiError(
+          'The current runtime does not provide wx.createEventSource',
+          {
+            code: 'OPENAPI_RUNTIME_UNAVAILABLE',
+            stage: 'transport'
+          }
+        );
+      }
+    } catch (error) {
+      return Promise.reject(error);
+    }
+
+    const config = {
+      baseUrl: this.config.baseUrl,
+      apiKey: this.config.apiKey
+    };
+    const requestId = createRequestId();
+    const url = `${config.baseUrl}${VISION_EXTRACT_PATH}`;
+
+    console.log(
+      '[glass3.openapi] request:',
+      JSON.stringify({
+        requestId,
+        method: 'POST',
+        url,
+        params: requestParamsForLog(requestParams)
+      })
+    );
+
+    return new Promise((resolve, reject) => {
+      const invocation = {
+        requestId,
+        task: null,
+        timeoutId: null,
+        settled: false,
+        hasResult: false,
+        finalResult: undefined,
+        resolve,
+        reject
+      };
+
+      const closeTask = () => {
+        if (!invocation.task || typeof invocation.task.close !== 'function') {
+          return;
+        }
+        try {
+          invocation.task.close();
+        } catch (_error) {
+          // The request is already terminal; close failures do not replace it.
+        }
+      };
+
+      const finish = (error, result) => {
+        if (invocation.settled) return;
+        invocation.settled = true;
+        if (invocation.timeoutId !== null) {
+          clearTimeout(invocation.timeoutId);
+          invocation.timeoutId = null;
+        }
+        this.activeRequests.delete(requestId);
+        closeTask();
+
+        if (error) {
+          console.error(
+            '[glass3.openapi] error:',
+            JSON.stringify(errorForLog(error))
+          );
+          reject(error);
+          return;
+        }
+
+        console.log(
+          '[glass3.openapi] response:',
+          JSON.stringify({ requestId, result })
+        );
+        resolve(result);
+      };
+
+      invocation.rejectWith = error => finish(error);
+      this.activeRequests.set(requestId, invocation);
+      invocation.timeoutId = setTimeout(() => {
+        finish(createOpenApiError(
+          `OpenAPI call timed out after ${VISION_EXTRACT_TIMEOUT}ms`,
+          {
+            code: 'CALL_TIMEOUT',
+            stage: 'timeout',
+            requestId,
+            details: { timeout: VISION_EXTRACT_TIMEOUT }
+          }
+        ));
+      }, VISION_EXTRACT_TIMEOUT);
+
+      try {
+        invocation.task = this.createEventSource({
+          url,
+          method: 'POST',
+          header: {
+            Authorization: `Bearer ${config.apiKey}`,
+            'Content-Type': 'application/json',
+            Accept: 'text/event-stream'
+          },
+          data: requestParams
+        });
+
+        invocation.task.onMessage(message => {
+          if (invocation.settled) return;
+
+          const rawData = message && typeof message.data === 'string'
+            ? message.data
+            : '';
+          if (rawData === '[DONE]') {
+            if (!invocation.hasResult) {
+              finish(createOpenApiError(
+                'OpenAPI stream ended without a result event',
+                {
+                  code: 'OPENAPI_PROTOCOL_ERROR',
+                  stage: 'event',
+                  requestId
+                }
+              ));
+              return;
+            }
+            finish(null, invocation.finalResult);
+            return;
+          }
+
+          const event = {
+            type: message && message.event ? message.event : 'message',
+            data: parseEventData(rawData),
+            rawData,
+            id: message && message.id ? message.id : ''
+          };
+
+          console.log(
+            '[glass3.openapi] event:',
+            JSON.stringify({
+              requestId,
+              type: event.type,
+              data: event.data,
+              id: event.id
+            })
+          );
+          invokeEventCallback(callOptions.onEvent, event);
+
+          if (event.type === 'error') {
+            const messageText = event.data && event.data.message
+              ? event.data.message
+              : 'OpenAPI vision extraction failed';
+            finish(createOpenApiError(messageText, {
+              code: 'OPENAPI_SERVICE_ERROR',
+              stage: 'event',
+              requestId,
+              details: event.data
+            }));
+            return;
+          }
+
+          if (event.type === 'result') {
+            if (
+              !event.data ||
+              typeof event.data !== 'object' ||
+              Array.isArray(event.data)
+            ) {
+              finish(createOpenApiError(
+                'OpenAPI result event must contain a JSON object',
+                {
+                  code: 'OPENAPI_PROTOCOL_ERROR',
+                  stage: 'event',
+                  requestId,
+                  details: { rawData }
+                }
+              ));
+              return;
+            }
+            invocation.hasResult = true;
+            invocation.finalResult = event.data;
+          }
+        });
+
+        invocation.task.onError(error => {
+          if (invocation.settled) return;
+          const errMsg = error && error.errMsg
+            ? error.errMsg
+            : 'OpenAPI stream failed';
+          const isHttpError = errMsg.indexOf('HTTP Error:') === 0;
+          finish(createOpenApiError(errMsg, {
+            code: isHttpError
+              ? 'OPENAPI_HTTP_ERROR'
+              : 'OPENAPI_STREAM_ERROR',
+            stage: 'transport',
+            requestId,
+            details: { errMsg }
+          }));
+        });
+
+      } catch (error) {
+        finish(createOpenApiError(
+          error && error.message ? error.message : 'OpenAPI request failed',
+          {
+            code: 'OPENAPI_STREAM_ERROR',
+            stage: 'transport',
+            requestId,
+            cause: error
+          }
+        ));
+      }
+    });
+  }
+
+  dispose() {
+    const invocations = [];
+    this.activeRequests.forEach(invocation => invocations.push(invocation));
+    invocations.forEach(invocation => {
+      invocation.rejectWith(createOpenApiError(
+        'Glass3 call disposed: openapi.visionExtract',
+        {
+          code: 'CALL_DISPOSED',
+          stage: 'dispose',
+          requestId: invocation.requestId
+        }
+      ));
+    });
+  }
+}
+
+export {
+  DEFAULT_BASE_URL,
+  VISION_EXTRACT_PATH,
+  VISION_EXTRACT_TIMEOUT
+};

package/sdk/modules/openapi/index.js

@@ -0,0 +1,21 @@
+import wx from 'wx';
+import { OpenApiClient } from './client.js';
+
+const openApiClient = new OpenApiClient({
+  createEventSource(options) {
+    return wx.createEventSource(options);
+  }
+});
+
+const openapi = {
+  setConfig(options) {
+    return openApiClient.setConfig(options);
+  },
+
+  visionExtract(params, options) {
+    return openApiClient.visionExtract(params, options);
+  }
+};
+
+export { OpenApiClient, openApiClient, openapi };
+export default openapi;

package/sdk/modules/openapi/readme.md

@@ -0,0 +1,83 @@
+# OpenAPI
+
+`glass3.openapi` 是全局单例，用于从 AIUI 页面直接调用 Rokid OpenAPI。
+它使用 HTTPS 与 SSE，不经过 Host RPC，因此不依赖 `glass3.handleMessage()`；页面仍需在
+卸载时调用 `glass3.dispose()`，以关闭未完成的 SSE 请求。
+
+## 配置
+
+应用启动后配置一次即可：
+
+```js
+glass3.openapi.setConfig({
+  apiKey: '<AK>'
+});
+```
+
+- `apiKey` 必填。
+- `baseUrl` 可选，默认 `https://api.rokid.com`。
+- 测试环境显式传入 `https://api-test.rokid.com`。
+- 重复调用会覆盖后续请求使用的配置，不影响已经发出的请求。
+- 配置只保存在当前 JS 运行实例内，应用重新启动后需要再次配置。
+
+## 图片识别
+
+```js
+const result = await glass3.openapi.visionExtract(
+  {
+    image: 'data:image/jpeg;base64,...',
+    prompt: '图中有什么安全隐患',
+    uiType: 'table',
+    fields: [
+      { name: 'hazard', title: '隐患', type: 'string' },
+      { name: 'suggestion', title: '修改建议', type: 'string' },
+      { name: 'regulation', title: '法规', type: 'string' }
+    ]
+  },
+  {
+    onEvent(event) {
+      console.log(event.type, JSON.stringify(event.data));
+    }
+  }
+);
+```
+
+业务参数：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `image` | `string` | 必填；纯 Base64 或 Base64 Data URL，原图最大 10MB。 |
+| `prompt` | `string` | 必填；最长 8192 字符。 |
+| `uiType` | `string` | 必填；`text` 或 `table`。 |
+| `fields` | `array` | `table` 必填 1–8 项；`text` 时省略或传空数组。 |
+
+`fields` 每项必须提供稳定的英文字段名 `name`、展示名 `title`，以及
+`string`、`number` 或 `boolean` 类型。
+
+`onEvent` 收到：
+
+```js
+{
+  type: 'start' | 'snapshot' | 'discard' | 'result' | 'error',
+  data: {},
+  rawData: '{...}',
+  id: ''
+}
+```
+
+- `data` 优先解析为 JSON；非 JSON 数据保留为字符串。
+- `rawData` 是移除 `data:` 前缀后的原始字符串。
+- `[DONE]` 是内部完成标记，不进入 `onEvent`。
+- Promise 收到 `[DONE]` 后 resolve 最终 `result` 数据。
+- `result.success === false` 是正常业务结果，仍然 resolve。
+- `event:error`、HTTP 错误、网络错误、协议错误和超时会 reject。
+- 单次调用最长等待 120 秒。
+- `onEvent` 自身抛错只记录日志，不改变请求结果。
+
+## 日志与安全
+
+SDK 统一输出 `config`、`request`、`event`、`response` 和 `error` 日志。
+`apiKey`、`Authorization` 与图片 Base64 永远不会原样写入日志；图片只记录 MIME 与长度。
+
+当前 AIUI `EventSourceTask` 不会分发空 `data:` 帧，因此服务端的 `discard` 事件必须携带
+非空数据，例如 `data:{}` 或 `data:null`。服务端也必须始终发送 `data:[DONE]` 结束帧。

package/sdk/modules/status-bar/index.js

@@ -0,0 +1,78 @@
+import { RPC_CHANNEL } from '../../core/constants.js';
+import { Glass3Error } from '../../utils/errors.js';
+
+const STATUS_BAR_NAMESPACE = 'rokid.statusBar';
+const STATUS_BAR_TIMEOUT_MS = 5000;
+
+function createParameterError(message, method) {
+  return new Glass3Error(message, {
+    code: 'INVALID_PARAMS',
+    stage: 'params',
+    namespace: STATUS_BAR_NAMESPACE,
+    method
+  });
+}
+
+function buildSingleFieldArgs(field, type, method) {
+  return args => {
+    if (!args || typeof args !== 'object' || Array.isArray(args)) {
+      throw createParameterError(
+        `statusBar.${method} parameters must be an object`,
+        method
+      );
+    }
+
+    const fields = Object.keys(args);
+    if (fields.length !== 1 || fields[0] !== field) {
+      throw createParameterError(
+        `statusBar.${method} only supports ${field}`,
+        method
+      );
+    }
+
+    if (typeof args[field] !== type) {
+      throw createParameterError(
+        `statusBar.${method} ${field} must be a ${type}`,
+        method
+      );
+    }
+
+    return { [field]: args[field] };
+  };
+}
+
+function directParams(args) {
+  return args;
+}
+
+function selectResult(response) {
+  return response.result;
+}
+
+function createStatusBarDefinition(publicMethod, field, type) {
+  return {
+    publicModule: 'statusBar',
+    publicMethod,
+
+    namespace: STATUS_BAR_NAMESPACE,
+    method: publicMethod,
+    responseChannel: RPC_CHANNEL,
+
+    buildArgs: buildSingleFieldArgs(field, type, publicMethod),
+    buildRequestParams: directParams,
+    getTimeoutMs() {
+      return STATUS_BAR_TIMEOUT_MS;
+    },
+    isAcceptedResponseResult(result) {
+      if (!result || typeof result.updated !== 'boolean') return false;
+      return publicMethod !== 'setVisible' ||
+        typeof result.visible === 'boolean';
+    },
+    selectAcceptedResult: selectResult
+  };
+}
+
+export default [
+  createStatusBarDefinition('setTitle', 'title', 'string'),
+  createStatusBarDefinition('setVisible', 'visible', 'boolean')
+];