rvis-aiui-kit 1.0.0

package/sdk/api-map.js

@@ -0,0 +1,25 @@
+import audio from './modules/audio/index.js';
+import camera from './modules/camera/index.js';
+import deviceContext from './modules/device-context/index.js';
+import face from './modules/face/index.js';
+import motion from './modules/motion/index.js';
+import notification from './modules/notification/index.js';
+import offlineCommand from './modules/offline-command/index.js';
+import screen from './modules/screen/index.js';
+import tts from './modules/tts/index.js';
+
+// This map is the only mapping between the public JavaScript API and Host RPC.
+// Public names are never inferred from the native namespace or method strings.
+export const API_MAP = [].concat(
+  deviceContext,
+  notification,
+  screen,
+  tts,
+  offlineCommand,
+  audio,
+  camera,
+  face,
+  motion
+);
+
+export default API_MAP;

package/sdk/core/client.js

@@ -0,0 +1,641 @@
+import {
+  COMPLETION_ACCEPTED,
+  COMPLETION_EVENT,
+  COMPLETION_READY_EVENT_STREAM,
+  RPC_VERSION
+} from './constants.js';
+import { HostRpcTransport } from './transport.js';
+import { Glass3Error, normalizeError } from '../utils/errors.js';
+import { invokeEventCallback } from '../utils/events.js';
+import {
+  extractHostRpcMessage,
+  redactSensitiveDataForLog,
+  stripSensitiveFields
+} from '../utils/message.js';
+import { createRequestId } from '../utils/request-id.js';
+
+export class Glass3Client {
+  constructor(options) {
+    const clientOptions = options || {};
+    this.transport = clientOptions.transport || new HostRpcTransport();
+    this.activeInvocations = new Map();
+    this.pendingResponses = new Map();
+  }
+
+  invoke(definition, args, options) {
+    let nativeArgs;
+    let timeoutMs;
+    try {
+      nativeArgs = typeof definition.buildArgs === 'function'
+        ? definition.buildArgs(args)
+        : args || {};
+      timeoutMs = typeof definition.getTimeoutMs === 'function'
+        ? definition.getTimeoutMs(args)
+        : undefined;
+    } catch (error) {
+      return Promise.reject(error);
+    }
+
+    const callOptions = options || {};
+    const requestId = createRequestId();
+    const request = {
+      version: RPC_VERSION,
+      requestId,
+      namespace: definition.namespace,
+      method: definition.method,
+      params: {
+        toolName: definition.toolName,
+        toolAction: definition.toolAction,
+        args: nativeArgs,
+        extra: {}
+      }
+    };
+
+    if (definition.completion === COMPLETION_EVENT) {
+      return this.invokeUntilEvent(definition, request, timeoutMs);
+    }
+
+    if (definition.completion === COMPLETION_READY_EVENT_STREAM) {
+      return this.invokeUntilReadyEventStream(definition, request, callOptions);
+    }
+
+    return this.invokeUntilAccepted(definition, request, callOptions);
+  }
+
+  sendRequest(definition, request) {
+    return new Promise((resolve, reject) => {
+      this.pendingResponses.set(request.requestId, {
+        requestId: request.requestId,
+        definition,
+        resolve,
+        reject
+      });
+
+      let transportResult;
+      try {
+        transportResult = this.transport.send(request);
+      } catch (error) {
+        this.rejectPendingResponse(request.requestId, error);
+        return;
+      }
+
+      Promise.resolve(transportResult).then(
+        response => this.resolvePendingResponse(request.requestId, response),
+        error => this.rejectPendingResponse(request.requestId, error)
+      );
+    });
+  }
+
+  resolvePendingResponse(requestId, response) {
+    const pendingResponse = this.pendingResponses.get(requestId);
+    if (!pendingResponse) return false;
+
+    this.pendingResponses.delete(requestId);
+    pendingResponse.resolve(response);
+    return true;
+  }
+
+  rejectPendingResponse(requestId, error) {
+    const pendingResponse = this.pendingResponses.get(requestId);
+    if (!pendingResponse) return false;
+
+    this.pendingResponses.delete(requestId);
+    pendingResponse.reject(error);
+    return true;
+  }
+
+  invokeUntilAccepted(definition, request, callOptions) {
+    if (typeof callOptions.onEvent === 'function') {
+      this.activeInvocations.set(request.requestId, {
+        requestId: request.requestId,
+        definition,
+        onEvent: callOptions.onEvent
+      });
+    }
+
+    return this.sendRequest(definition, request).then(response => {
+      this.validateAcceptedResponse(definition, request.requestId, response);
+      return {
+        requestId: response.requestId,
+        ok: response.ok
+      };
+    }).catch(error => {
+      this.activeInvocations.delete(request.requestId);
+      throw this.normalizeInvocationError(error, definition, request.requestId);
+    });
+  }
+
+  invokeUntilEvent(definition, request, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      const invocation = {
+        requestId: request.requestId,
+        definition,
+        targetRequestId: request.params.args.targetRequestId,
+        resolve,
+        reject,
+        responseAccepted: false,
+        terminalEventData: null,
+        terminalResponse: null,
+        timeoutId: null
+      };
+
+      this.activeInvocations.set(request.requestId, invocation);
+      if (timeoutMs !== undefined) {
+        invocation.timeoutId = setTimeout(() => {
+          const error = new Glass3Error(
+            `Glass3 call timed out after ${timeoutMs}ms: ${definition.publicModule}.${definition.publicMethod}`,
+            {
+              code: 'CALL_TIMEOUT',
+              stage: 'timeout',
+              requestId: request.requestId,
+              namespace: definition.namespace,
+              method: definition.method,
+              details: { timeout: timeoutMs }
+            }
+          );
+
+          this.rejectPendingResponse(request.requestId, error);
+          this.rejectEventInvocation(invocation, error);
+        }, timeoutMs);
+      }
+
+      this.sendRequest(definition, request).then(response => {
+        this.validateAcceptedResponse(definition, request.requestId, response);
+
+        if (!this.activeInvocations.has(request.requestId)) return;
+        invocation.responseAccepted = true;
+
+        if (this.isCompletionResponse(definition, response)) {
+          invocation.terminalResponse = response;
+        }
+
+        if (invocation.terminalEventData || invocation.terminalResponse) {
+          this.resolveEventInvocation(invocation);
+        }
+      }).catch(error => {
+        this.rejectEventInvocation(
+          invocation,
+          this.normalizeInvocationError(error, definition, request.requestId)
+        );
+      });
+    });
+  }
+
+  invokeUntilReadyEventStream(definition, request, callOptions) {
+    return new Promise((resolve, reject) => {
+      const invocation = {
+        requestId: request.requestId,
+        definition,
+        onEvent: callOptions.onEvent,
+        resolve,
+        reject,
+        responseAccepted: false,
+        readyResult: null,
+        streamTerminated: false,
+        promiseSettled: false
+      };
+
+      this.activeInvocations.set(request.requestId, invocation);
+
+      this.sendRequest(definition, request).then(response => {
+        this.validateAcceptedResponse(definition, request.requestId, response);
+
+        if (!this.activeInvocations.has(request.requestId)) return;
+        invocation.responseAccepted = true;
+
+        if (this.isCompletionResponse(definition, response)) {
+          invocation.readyResult = this.selectCompletionResponseResult(
+            definition,
+            response
+          );
+        }
+
+        if (invocation.readyResult) {
+          this.resolveReadyEventStream(invocation);
+        }
+      }).catch(error => {
+        this.rejectEventInvocation(
+          invocation,
+          this.normalizeInvocationError(error, definition, request.requestId)
+        );
+      });
+    });
+  }
+
+  validateAcceptedResponse(definition, requestId, response) {
+    const acceptedResult = response && response.result;
+    const hasCustomAcceptedResult =
+      typeof definition.isAcceptedResponseResult === 'function';
+    const validAcceptedResult = hasCustomAcceptedResult
+      ? definition.isAcceptedResponseResult(acceptedResult, requestId)
+      : (
+          acceptedResult &&
+          acceptedResult.accepted === true &&
+          acceptedResult.requestId === requestId &&
+          acceptedResult.toolName === definition.toolName &&
+          acceptedResult.toolAction === definition.toolAction
+        );
+    const validResponse = response &&
+      response.version === RPC_VERSION &&
+      response.kind === 'response' &&
+      response.requestId === requestId &&
+      response.ok === true &&
+      validAcceptedResult;
+
+    if (validResponse) return;
+
+    const nativeError = response && response.error;
+    throw new Glass3Error(
+      nativeError && nativeError.message
+        ? nativeError.message
+        : `Native request was not accepted: ${definition.publicModule}.${definition.publicMethod}`,
+      {
+        code: nativeError && nativeError.code
+          ? nativeError.code
+          : 'NATIVE_REQUEST_NOT_ACCEPTED',
+        stage: 'response',
+        requestId,
+        namespace: definition.namespace,
+        method: definition.method,
+        details: stripSensitiveFields(response)
+      }
+    );
+  }
+
+  normalizeInvocationError(error, definition, requestId) {
+    return normalizeError(error, {
+      code: 'NATIVE_REQUEST_ERROR',
+      stage: 'response',
+      requestId,
+      namespace: definition.namespace,
+      method: definition.method
+    });
+  }
+
+  handleMessage(messageEvent) {
+    const messageDataForLog = redactSensitiveDataForLog(
+      messageEvent && messageEvent.data
+    );
+    console.log(
+      '[glass3] Native Origin onMessage:',
+      JSON.stringify({
+        origin: messageEvent && messageEvent.origin,
+        data: messageDataForLog
+      })
+    );
+
+    const rpcMessage = extractHostRpcMessage(messageEvent);
+    if (!rpcMessage) return null;
+
+    console.log(
+      '[glass3] Native onMessage:',
+      JSON.stringify({
+        origin: messageEvent.origin,
+        data: messageDataForLog
+      })
+    );
+
+    if (rpcMessage.kind === 'response') {
+      if (!rpcMessage.requestId) return null;
+
+      const pendingResolved = this.resolvePendingResponse(
+        rpcMessage.requestId,
+        rpcMessage
+      );
+      const completionRecorded = this.recordCompletionResponse(rpcMessage);
+
+      return pendingResolved || completionRecorded ? rpcMessage : null;
+    }
+
+    if (
+      rpcMessage.kind !== 'event' ||
+      !rpcMessage.data ||
+      !rpcMessage.data.requestId
+    ) {
+      return null;
+    }
+
+    const eventData = rpcMessage.data;
+    const invocation = this.activeInvocations.get(eventData.requestId);
+    if (!invocation) return null;
+
+    const definition = invocation.definition;
+    if (
+      rpcMessage.namespace !== definition.eventNamespace ||
+      rpcMessage.event !== definition.eventName ||
+      eventData.toolName !== definition.toolName ||
+      !this.isMatchingEventToolAction(definition, eventData.toolAction)
+    ) {
+      return null;
+    }
+
+    const nativeResult = eventData.result;
+    const result = typeof definition.transformEventResult === 'function'
+      ? definition.transformEventResult(nativeResult)
+      : nativeResult;
+
+    if (definition.completion === COMPLETION_ACCEPTED) {
+      invokeEventCallback(invocation.onEvent, result);
+      if (this.isTerminalResult(definition, result)) {
+        this.activeInvocations.delete(eventData.requestId);
+      }
+      return result;
+    }
+
+    if (definition.completion === COMPLETION_READY_EVENT_STREAM) {
+      invokeEventCallback(invocation.onEvent, result);
+
+      if (this.isStreamErrorResult(definition, result)) {
+        if (invocation.promiseSettled) {
+          this.activeInvocations.delete(eventData.requestId);
+        } else {
+          this.rejectEventInvocation(invocation, new Glass3Error(
+            `Native event failed: ${definition.publicModule}.${definition.publicMethod}`,
+            {
+              code: 'NATIVE_EVENT_ERROR',
+              stage: 'event',
+              requestId: eventData.requestId,
+              namespace: definition.namespace,
+              method: definition.method,
+              details: stripSensitiveFields(eventData)
+            }
+          ));
+        }
+        return result;
+      }
+
+      if (this.isStreamTerminalResult(definition, result)) {
+        invocation.streamTerminated = true;
+      }
+
+      if (!invocation.promiseSettled && this.isReadyResult(definition, result)) {
+        invocation.readyResult = result;
+        if (invocation.responseAccepted) {
+          this.resolveReadyEventStream(invocation);
+        }
+        return result;
+      }
+
+      if (
+        invocation.promiseSettled &&
+        invocation.streamTerminated
+      ) {
+        this.activeInvocations.delete(eventData.requestId);
+      }
+
+      return result;
+    }
+
+    if (result.ok !== true) {
+      this.rejectEventInvocation(invocation, new Glass3Error(
+        `Native event failed: ${definition.publicModule}.${definition.publicMethod}`,
+        {
+          code: 'NATIVE_EVENT_ERROR',
+          stage: 'event',
+          requestId: eventData.requestId,
+          namespace: definition.namespace,
+          method: definition.method,
+          details: stripSensitiveFields(eventData)
+        }
+      ));
+      return result;
+    }
+
+    if (this.isTerminalResult(definition, result)) {
+      invocation.terminalEventData = eventData;
+      if (invocation.responseAccepted) {
+        this.resolveEventInvocation(invocation);
+      }
+    }
+
+    return result;
+  }
+
+  isReadyResult(definition, result) {
+    return typeof definition.isReadyResult === 'function' &&
+      definition.isReadyResult(result);
+  }
+
+  isMatchingEventToolAction(definition, toolAction) {
+    if (Array.isArray(definition.eventToolActions)) {
+      return definition.eventToolActions.indexOf(toolAction) !== -1;
+    }
+
+    return toolAction === definition.toolAction;
+  }
+
+  isStreamErrorResult(definition, result) {
+    if (typeof definition.isErrorResult === 'function') {
+      return definition.isErrorResult(result);
+    }
+
+    return result.ok !== true;
+  }
+
+  isStreamTerminalResult(definition, result) {
+    return typeof definition.isStreamTerminalResult === 'function' &&
+      definition.isStreamTerminalResult(result);
+  }
+
+  isTerminalResult(definition, result) {
+    if (typeof definition.isTerminalResult === 'function') {
+      return definition.isTerminalResult(result);
+    }
+
+    return definition.terminalStates.indexOf(result.state) !== -1;
+  }
+
+  isCompletionResponse(definition, response) {
+    return Array.isArray(definition.responseCompletionStates) &&
+      response &&
+      response.result &&
+      definition.responseCompletionStates.indexOf(
+        response.result.state
+      ) !== -1;
+  }
+
+  selectCompletionResponseResult(definition, response) {
+    if (typeof definition.selectResponseResult === 'function') {
+      return definition.selectResponseResult(response);
+    }
+
+    return {
+      requestId: response.requestId,
+      ok: response.ok,
+      state: response.result.state
+    };
+  }
+
+  recordCompletionResponse(response) {
+    const invocation = this.activeInvocations.get(response.requestId);
+    if (
+      !invocation ||
+      (
+        invocation.definition.completion !== COMPLETION_EVENT &&
+        invocation.definition.completion !== COMPLETION_READY_EVENT_STREAM
+      ) ||
+      !this.isCompletionResponse(invocation.definition, response)
+    ) {
+      return false;
+    }
+
+    try {
+      this.validateAcceptedResponse(
+        invocation.definition,
+        invocation.requestId,
+        response
+      );
+    } catch (error) {
+      return false;
+    }
+
+    if (invocation.definition.completion === COMPLETION_EVENT) {
+      invocation.terminalResponse = response;
+      if (invocation.responseAccepted) {
+        this.resolveEventInvocation(invocation);
+      }
+      return true;
+    }
+
+    if (invocation.promiseSettled) return false;
+
+    invocation.readyResult = this.selectCompletionResponseResult(
+      invocation.definition,
+      response
+    );
+    if (invocation.responseAccepted) {
+      this.resolveReadyEventStream(invocation);
+    }
+    return true;
+  }
+
+  resolveEventInvocation(invocation) {
+    if (!this.activeInvocations.delete(invocation.requestId)) return;
+    this.clearInvocationTimeout(invocation);
+
+    const eventData = invocation.terminalEventData;
+    let result;
+
+    if (eventData) {
+      result = typeof invocation.definition.selectEventResult === 'function'
+        ? invocation.definition.selectEventResult(eventData)
+        : eventData.result;
+    } else {
+      const response = invocation.terminalResponse;
+      result = this.selectCompletionResponseResult(
+        invocation.definition,
+        response
+      );
+    }
+
+    this.releaseTargetInvocation(invocation);
+    invocation.resolve(result);
+  }
+
+  releaseTargetInvocation(invocation) {
+    const targetDefinition = invocation.definition.releaseTargetInvocation;
+    if (!targetDefinition || !invocation.targetRequestId) return;
+
+    const targetInvocation = this.activeInvocations.get(
+      invocation.targetRequestId
+    );
+    if (
+      !targetInvocation ||
+      targetInvocation.definition.publicModule !==
+        targetDefinition.publicModule ||
+      targetInvocation.definition.publicMethod !==
+        targetDefinition.publicMethod
+    ) {
+      return;
+    }
+
+    this.activeInvocations.delete(invocation.targetRequestId);
+  }
+
+  resolveReadyEventStream(invocation) {
+    if (!this.activeInvocations.has(invocation.requestId)) return;
+
+    invocation.promiseSettled = true;
+    const result = typeof invocation.definition.selectReadyResult === 'function'
+      ? invocation.definition.selectReadyResult(
+          invocation.requestId,
+          invocation.readyResult
+        )
+      : invocation.readyResult;
+
+    invocation.resolve(result);
+
+    if (
+      typeof invocation.onEvent !== 'function' ||
+      invocation.streamTerminated
+    ) {
+      this.activeInvocations.delete(invocation.requestId);
+    }
+  }
+
+  rejectEventInvocation(invocation, error) {
+    if (!this.activeInvocations.delete(invocation.requestId)) return;
+    this.clearInvocationTimeout(invocation);
+    invocation.reject(error);
+  }
+
+  clearInvocationTimeout(invocation) {
+    if (
+      !invocation ||
+      invocation.timeoutId === null ||
+      invocation.timeoutId === undefined
+    ) return;
+    clearTimeout(invocation.timeoutId);
+    invocation.timeoutId = null;
+  }
+
+  dispose() {
+    const invocations = [];
+    this.activeInvocations.forEach(invocation => invocations.push(invocation));
+
+    invocations.forEach(invocation => {
+      if (
+        invocation.definition.completion === COMPLETION_EVENT ||
+        (
+          invocation.definition.completion === COMPLETION_READY_EVENT_STREAM &&
+          !invocation.promiseSettled
+        )
+      ) {
+        this.rejectEventInvocation(invocation, new Glass3Error(
+          `Glass3 call disposed: ${invocation.definition.publicModule}.${invocation.definition.publicMethod}`,
+          {
+            code: 'CALL_DISPOSED',
+            stage: 'dispose',
+            requestId: invocation.requestId,
+            namespace: invocation.definition.namespace,
+            method: invocation.definition.method
+          }
+        ));
+      } else {
+        this.activeInvocations.delete(invocation.requestId);
+      }
+    });
+
+    const pendingResponses = [];
+    this.pendingResponses.forEach(pendingResponse => {
+      pendingResponses.push(pendingResponse);
+    });
+
+    pendingResponses.forEach(pendingResponse => {
+      const definition = pendingResponse.definition;
+      this.rejectPendingResponse(
+        pendingResponse.requestId,
+        new Glass3Error(
+          `Glass3 call disposed: ${definition.publicModule}.${definition.publicMethod}`,
+          {
+            code: 'CALL_DISPOSED',
+            stage: 'dispose',
+            requestId: pendingResponse.requestId,
+            namespace: definition.namespace,
+            method: definition.method
+          }
+        )
+      );
+    });
+  }
+}

package/sdk/core/constants.js

@@ -0,0 +1,10 @@
+export const RPC_URL = 'https://ink-host-rpc.invalid/rpc';
+export const RPC_ORIGIN = 'rokid://host-rpc';
+export const RPC_VERSION = '2.0.0';
+
+export const RPC_SUCCESS_STATUS_MIN = 200;
+export const RPC_SUCCESS_STATUS_MAX = 299;
+
+export const COMPLETION_ACCEPTED = 'accepted';
+export const COMPLETION_EVENT = 'event';
+export const COMPLETION_READY_EVENT_STREAM = 'ready-event-stream';