@wandelbots/nova-js 1.17.1-pr.feat-added-v2-client.64.9ac2247

package/src/lib/v2/NovaCellAPIClient.ts

@@ -0,0 +1,174 @@
+import type { Configuration as BaseConfiguration } from "@wandelbots/nova-api/v2"
+import {
+  ApplicationApi,
+  CellApi,
+  ControllerApi,
+  ControllerInputsOutputsApi,
+  CoordinateSystemsApi,
+  JoggingApi,
+  MotionGroupApi,
+  MotionGroupInfoApi,
+  MotionGroupKinematicsApi,
+  ProgramApi,
+  ProgramLibraryApi,
+  ProgramLibraryMetadataApi,
+  ProgramOperatorApi,
+  StoreCollisionComponentsApi,
+  StoreCollisionScenesApi,
+  StoreObjectApi,
+  SystemApi,
+  TrajectoryExecutionApi,
+  TrajectoryPlanningApi,
+  VirtualRobotApi,
+  VirtualRobotBehaviorApi,
+  VirtualRobotModeApi,
+  VirtualRobotSetupApi,
+} from "@wandelbots/nova-api/v2"
+import type { BaseAPI } from "@wandelbots/nova-api/v2/base"
+import type { AxiosInstance } from "axios"
+import axios from "axios"
+
+type OmitFirstArg<F> = F extends (x: any, ...args: infer P) => infer R
+  ? (...args: P) => R
+  : never
+
+type UnwrapAxiosResponseReturn<T> = T extends (...a: any) => any
+  ? (
+      ...a: Parameters<T>
+    ) => Promise<Awaited<ReturnType<T>> extends { data: infer D } ? D : never>
+  : never
+
+export type WithCellId<T> = {
+  [P in keyof T]: UnwrapAxiosResponseReturn<OmitFirstArg<T[P]>>
+}
+
+export type WithUnwrappedAxiosResponse<T> = {
+  [P in keyof T]: UnwrapAxiosResponseReturn<T[P]>
+}
+
+/**
+ * API client providing type-safe access to all the Nova API REST endpoints
+ * associated with a specific cell id.
+ */
+export class NovaCellAPIClient {
+  constructor(
+    readonly cellId: string,
+    readonly opts: BaseConfiguration & {
+      axiosInstance?: AxiosInstance
+      mock?: boolean
+    },
+  ) {}
+
+  /**
+   * Some TypeScript sorcery which alters the API class methods so you don't
+   * have to pass the cell id to every single one, and de-encapsulates the
+   * response data
+   */
+  private withCellId<T extends BaseAPI>(
+    ApiConstructor: new (
+      config: BaseConfiguration,
+      basePath: string,
+      axios: AxiosInstance,
+    ) => T,
+  ) {
+    const apiClient = new ApiConstructor(
+      {
+        ...this.opts,
+        isJsonMime: (mime: string) => {
+          return mime === "application/json"
+        },
+      },
+      this.opts.basePath ?? "",
+      this.opts.axiosInstance ?? axios.create(),
+    ) as {
+      [key: string | symbol]: any
+    }
+
+    for (const key of Reflect.ownKeys(Reflect.getPrototypeOf(apiClient)!)) {
+      if (key !== "constructor" && typeof apiClient[key] === "function") {
+        const originalFunction = apiClient[key]
+        apiClient[key] = (...args: any[]) => {
+          return originalFunction
+            .apply(apiClient, [this.cellId, ...args])
+            .then((res: any) => res.data)
+        }
+      }
+    }
+
+    return apiClient as WithCellId<T>
+  }
+
+  /**
+   * As withCellId, but only does the response unwrapping
+   */
+  private withUnwrappedResponsesOnly<T extends BaseAPI>(
+    ApiConstructor: new (
+      config: BaseConfiguration,
+      basePath: string,
+      axios: AxiosInstance,
+    ) => T,
+  ) {
+    const apiClient = new ApiConstructor(
+      {
+        ...this.opts,
+        isJsonMime: (mime: string) => {
+          return mime === "application/json"
+        },
+      },
+      this.opts.basePath ?? "",
+      this.opts.axiosInstance ?? axios.create(),
+    ) as {
+      [key: string | symbol]: any
+    }
+
+    for (const key of Reflect.ownKeys(Reflect.getPrototypeOf(apiClient)!)) {
+      if (key !== "constructor" && typeof apiClient[key] === "function") {
+        const originalFunction = apiClient[key]
+        apiClient[key] = (...args: any[]) => {
+          return originalFunction
+            .apply(apiClient, args)
+            .then((res: any) => res.data)
+        }
+      }
+    }
+
+    return apiClient as WithUnwrappedAxiosResponse<T>
+  }
+
+  readonly system = this.withUnwrappedResponsesOnly(SystemApi)
+  readonly cell = this.withUnwrappedResponsesOnly(CellApi)
+
+  readonly motionGroup = this.withCellId(MotionGroupApi)
+  readonly motionGroupInfos = this.withCellId(MotionGroupInfoApi)
+
+  readonly controller = this.withCellId(ControllerApi)
+
+  readonly program = this.withCellId(ProgramApi)
+  readonly programOperator = this.withCellId(ProgramOperatorApi)
+  readonly programLibraryMetadata = this.withCellId(ProgramLibraryMetadataApi)
+  readonly programLibrary = this.withCellId(ProgramLibraryApi)
+
+  readonly controllerIOs = this.withCellId(ControllerInputsOutputsApi)
+
+  readonly motionGroupKinematic = this.withCellId(MotionGroupKinematicsApi)
+  readonly trajectoryPlanning = this.withCellId(TrajectoryPlanningApi)
+  readonly trajectoryExecution = this.withCellId(TrajectoryExecutionApi)
+
+  readonly coordinateSystems = this.withCellId(CoordinateSystemsApi)
+
+  readonly application = this.withCellId(ApplicationApi)
+  readonly applicationGlobal = this.withUnwrappedResponsesOnly(ApplicationApi)
+
+  readonly jogging = this.withCellId(JoggingApi)
+
+  readonly virtualRobot = this.withCellId(VirtualRobotApi)
+  readonly virtualRobotSetup = this.withCellId(VirtualRobotSetupApi)
+  readonly virtualRobotMode = this.withCellId(VirtualRobotModeApi)
+  readonly virtualRobotBehavior = this.withCellId(VirtualRobotBehaviorApi)
+
+  readonly storeObject = this.withCellId(StoreObjectApi)
+  readonly storeCollisionComponents = this.withCellId(
+    StoreCollisionComponentsApi,
+  )
+  readonly storeCollisionScenes = this.withCellId(StoreCollisionScenesApi)
+}

package/src/lib/v2/NovaClient.ts

@@ -0,0 +1,230 @@
+import type { Configuration as BaseConfiguration } from "@wandelbots/nova-api/v2"
+import type { AxiosRequestConfig } from "axios"
+import axios, { isAxiosError } from "axios"
+import urlJoin from "url-join"
+import { loginWithAuth0 } from "../../LoginWithAuth0"
+import { AutoReconnectingWebsocket } from "../AutoReconnectingWebsocket"
+import { availableStorage } from "../availableStorage"
+import { ConnectedMotionGroup } from "./ConnectedMotionGroup"
+import { MockNovaInstance } from "./mock/MockNovaInstance"
+import { MotionStreamConnection } from "./MotionStreamConnection"
+import { NovaCellAPIClient } from "./NovaCellAPIClient"
+
+export type NovaClientConfig = {
+  /**
+   * Url of the deployed Nova instance to connect to
+   * e.g. https://saeattii.instance.wandelbots.io
+   */
+  instanceUrl: string | "https://mock.example.com"
+
+  /**
+   * Identifier of the cell on the Nova instance to connect this client to.
+   * If omitted, the default identifier "cell" is used.
+   **/
+  cellId?: string
+
+  /**
+   * Username for basic auth to the Nova instance.
+   * @deprecated use accessToken instead
+   */
+  username?: string
+
+  /**
+   * Password for basic auth to the Nova instance.
+   * @deprecated use accessToken instead
+   */
+  password?: string
+
+  /**
+   * Access token for Bearer authentication.
+   */
+  accessToken?: string
+} & Omit<BaseConfiguration, "isJsonMime" | "basePath">
+
+type NovaClientConfigWithDefaults = NovaClientConfig & { cellId: string }
+
+/**
+ * EXPERIMENTAL
+ *
+ * This client provides a starting point to migrate NOVA api v2.
+ * As v2 is still in development, this client has to be considered unstable
+ *
+ * Client for connecting to a Nova instance and controlling robots.
+ */
+export class NovaClient {
+  readonly api: NovaCellAPIClient
+  readonly config: NovaClientConfigWithDefaults
+  readonly mock?: MockNovaInstance
+  authPromise: Promise<string | null> | null = null
+  accessToken: string | null = null
+
+  constructor(config: NovaClientConfig) {
+    console.warn("Using experimental NOVA v2 client")
+    const cellId = config.cellId ?? "cell"
+    this.config = {
+      cellId,
+      ...config,
+    }
+    this.accessToken =
+      config.accessToken ||
+      availableStorage.getString("wbjs.access_token") ||
+      null
+
+    if (this.config.instanceUrl === "https://mock.example.com") {
+      this.mock = new MockNovaInstance()
+    }
+
+    // Set up Axios instance with interceptor for token fetching
+    const axiosInstance = axios.create({
+      baseURL: urlJoin(this.config.instanceUrl, "/api/v2"),
+    })
+
+    axiosInstance.interceptors.request.use(async (request) => {
+      if (!request.headers.Authorization) {
+        if (this.accessToken) {
+          request.headers.Authorization = `Bearer ${this.accessToken}`
+        } else if (this.config.username && this.config.password) {
+          request.headers.Authorization = `Basic ${btoa(config.username + ":" + config.password)}`
+        }
+      }
+      return request
+    })
+
+    if (typeof window !== "undefined") {
+      axiosInstance.interceptors.response.use(
+        (r) => r,
+        async (error) => {
+          if (isAxiosError(error)) {
+            if (error.response?.status === 401) {
+              // If we hit a 401, attempt to login the user and retry with
+              // a new access token
+              try {
+                await this.renewAuthentication()
+
+                if (error.config) {
+                  if (this.accessToken) {
+                    error.config.headers.Authorization = `Bearer ${this.accessToken}`
+                  } else {
+                    delete error.config.headers.Authorization
+                  }
+                  return axiosInstance.request(error.config)
+                }
+              } catch (err) {
+                return Promise.reject(err)
+              }
+            } else if (error.response?.status === 503) {
+              // Check if the server as a whole is down
+              const res = await fetch(window.location.href)
+              if (res.status === 503) {
+                // Go to 503 page
+                window.location.reload()
+              }
+            }
+          }
+
+          return Promise.reject(error)
+        },
+      )
+    }
+
+    this.api = new NovaCellAPIClient(cellId, {
+      ...config,
+      basePath: urlJoin(this.config.instanceUrl, "/api/v1"),
+      isJsonMime: (mime: string) => {
+        return mime === "application/json"
+      },
+      baseOptions: {
+        ...(this.mock
+          ? ({
+              adapter: (config) => {
+                return this.mock!.handleAPIRequest(config)
+              },
+            } satisfies AxiosRequestConfig)
+          : {}),
+        ...config.baseOptions,
+      },
+      axiosInstance,
+    })
+  }
+
+  async renewAuthentication(): Promise<void> {
+    if (this.authPromise) {
+      // Don't double up
+      return
+    }
+
+    this.authPromise = loginWithAuth0(this.config.instanceUrl)
+    try {
+      this.accessToken = await this.authPromise
+      if (this.accessToken) {
+        // Cache access token so we don't need to log in every refresh
+        availableStorage.setString("wbjs.access_token", this.accessToken)
+      } else {
+        availableStorage.delete("wbjs.access_token")
+      }
+    } finally {
+      this.authPromise = null
+    }
+  }
+
+  makeWebsocketURL(path: string): string {
+    const url = new URL(
+      urlJoin(
+        this.config.instanceUrl,
+        `/api/v1/cells/${this.config.cellId}`,
+        path,
+      ),
+    )
+    url.protocol = url.protocol.replace("http", "ws")
+    url.protocol = url.protocol.replace("https", "wss")
+
+    // If provided, add basic auth credentials to the URL
+    // NOTE - basic auth is deprecated on websockets and doesn't work in Safari
+    // use tokens instead
+    if (this.accessToken) {
+      url.searchParams.append("token", this.accessToken)
+    } else if (this.config.username && this.config.password) {
+      url.username = this.config.username
+      url.password = this.config.password
+    }
+
+    return url.toString()
+  }
+
+  /**
+   * Retrieve an AutoReconnectingWebsocket to the given path on the Nova instance.
+   * If you explicitly want to reconnect an existing websocket, call `reconnect`
+   * on the returned object.
+   */
+  openReconnectingWebsocket(path: string) {
+    return new AutoReconnectingWebsocket(this.makeWebsocketURL(path), {
+      mock: this.mock,
+    })
+  }
+
+  /**
+   * Connect to the motion state websocket(s) for a given motion group
+   */
+  async connectMotionStream(motionGroupId: string) {
+    return await MotionStreamConnection.open(this, motionGroupId)
+  }
+
+  async connectMotionGroups(
+    motionGroupIds: string[],
+  ): Promise<ConnectedMotionGroup[]> {
+    const { controllers } = await this.api.controller.listControllers()
+
+    return Promise.all(
+      motionGroupIds.map((motionGroupId) =>
+        ConnectedMotionGroup.connect(this, motionGroupId, controllers),
+      ),
+    )
+  }
+
+  async connectMotionGroup(
+    motionGroupId: string,
+  ): Promise<ConnectedMotionGroup> {
+    const motionGroups = await this.connectMotionGroups([motionGroupId])
+    return motionGroups[0]!
+  }
+}

package/src/lib/v2/ProgramStateConnection.ts

@@ -0,0 +1,255 @@
+import { AxiosError } from "axios"
+import { makeAutoObservable, runInAction } from "mobx"
+import { AutoReconnectingWebsocket } from "../AutoReconnectingWebsocket"
+import { tryParseJson } from "../converters"
+import type { MotionStreamConnection } from "./MotionStreamConnection"
+import type { NovaClient } from "./NovaClient"
+
+export type ProgramRunnerLogEntry = {
+  timestamp: number
+  message: string
+  level?: "warn" | "error"
+}
+
+export enum ProgramState {
+  NotStarted = "not started",
+  Running = "running",
+  Stopped = "stopped",
+  Failed = "failed",
+  Completed = "completed",
+}
+
+export type CurrentProgram = {
+  id?: string
+  wandelscript?: string
+  state?: ProgramState
+}
+
+type ProgramStateMessage = {
+  type: string
+  runner: {
+    id: string
+    state: ProgramState
+    start_time?: number | null
+    execution_time?: number | null
+  }
+}
+
+/**
+ * Interface for running Wandelscript programs on the Nova instance and
+ * tracking their progress and output
+ */
+export class ProgramStateConnection {
+  currentProgram: CurrentProgram = {}
+  logs: ProgramRunnerLogEntry[] = []
+
+  executionState = "idle" as "idle" | "starting" | "executing" | "stopping"
+  currentlyExecutingProgramRunnerId = null as string | null
+
+  programStateSocket: AutoReconnectingWebsocket
+
+  constructor(readonly nova: NovaClient) {
+    makeAutoObservable(this, {}, { autoBind: true })
+
+    this.programStateSocket = nova.openReconnectingWebsocket(`/programs/state`)
+
+    this.programStateSocket.addEventListener("message", (ev) => {
+      const msg = tryParseJson(ev.data)
+
+      if (!msg) {
+        console.error("Failed to parse program state message", ev.data)
+        return
+      }
+      if (msg.type === "update") {
+        this.handleProgramStateMessage(msg)
+      }
+    })
+  }
+
+  /** Handle a program state update from the backend */
+  async handleProgramStateMessage(msg: ProgramStateMessage) {
+    const { runner } = msg
+
+    // Ignoring other programs for now
+    // TODO - show if execution state is busy from another source
+    if (runner.id !== this.currentlyExecutingProgramRunnerId) return
+
+    if (runner.state === ProgramState.Failed) {
+      try {
+        const runnerState = await this.nova.api.program.getProgramRunner(
+          runner.id,
+        )
+
+        // TODO - wandelengine should send print statements in real time over
+        // websocket as well, rather than at the end
+        const stdout = (runnerState as any).stdout
+        if (stdout) {
+          this.log(stdout)
+        }
+        this.logError(
+          `Program runner ${runner.id} failed with error: ${runnerState.error}\n${runnerState.traceback}`,
+        )
+      } catch (err) {
+        this.logError(
+          `Failed to retrieve results for program ${runner.id}: ${err}`,
+        )
+      }
+
+      this.currentProgram.state = ProgramState.Failed
+
+      this.gotoIdleState()
+    } else if (runner.state === ProgramState.Stopped) {
+      try {
+        const runnerState = await this.nova.api.program.getProgramRunner(
+          runner.id,
+        )
+
+        const stdout = (runnerState as any).stdout
+        if (stdout) {
+          this.log(stdout)
+        }
+
+        this.currentProgram.state = ProgramState.Stopped
+        this.log(`Program runner ${runner.id} stopped`)
+      } catch (err) {
+        this.logError(
+          `Failed to retrieve results for program ${runner.id}: ${err}`,
+        )
+      }
+
+      this.gotoIdleState()
+    } else if (runner.state === ProgramState.Completed) {
+      try {
+        const runnerState = await this.nova.api.program.getProgramRunner(
+          runner.id,
+        )
+
+        const stdout = (runnerState as any).stdout
+        if (stdout) {
+          this.log(stdout)
+        }
+        this.log(
+          `Program runner ${runner.id} finished successfully in ${runner.execution_time?.toFixed(2)} seconds`,
+        )
+
+        this.currentProgram.state = ProgramState.Completed
+      } catch (err) {
+        this.logError(
+          `Failed to retrieve results for program ${runner.id}: ${err}`,
+        )
+      }
+
+      this.gotoIdleState()
+    } else if (runner.state === ProgramState.Running) {
+      this.currentProgram.state = ProgramState.Running
+      this.log(`Program runner ${runner.id} now running`)
+    } else if (runner.state !== ProgramState.NotStarted) {
+      console.error(runner)
+      this.logError(
+        `Program runner ${runner.id} entered unexpected state: ${runner.state}`,
+      )
+      this.currentProgram.state = ProgramState.NotStarted
+      this.gotoIdleState()
+    }
+  }
+
+  /** Call when a program is no longer executing */
+  gotoIdleState() {
+    runInAction(() => {
+      this.executionState = "idle"
+    })
+    this.currentlyExecutingProgramRunnerId = null
+  }
+
+  async executeProgram(
+    wandelscript: string,
+    initial_state?: Object,
+    activeRobot?: MotionStreamConnection,
+  ) {
+    this.currentProgram = {
+      wandelscript: wandelscript,
+      state: ProgramState.NotStarted,
+    }
+
+    const { currentProgram: openProgram } = this
+    if (!openProgram) return
+    runInAction(() => {
+      this.executionState = "starting"
+    })
+
+    // WOS-1539: Wandelengine parser currently breaks if there are empty lines with indentation
+    const trimmedCode = openProgram.wandelscript!.replaceAll(/^\s*$/gm, "")
+
+    try {
+      const programRunnerRef = await this.nova.api.program.createProgramRunner(
+        {
+          code: trimmedCode,
+          initial_state: initial_state,
+          default_robot: activeRobot?.wandelscriptIdentifier,
+        } as any,
+        {
+          headers: {
+            "Content-Type": "application/json",
+          },
+        },
+      )
+
+      this.log(`Created program runner ${programRunnerRef.id}"`)
+      runInAction(() => {
+        this.executionState = "executing"
+      })
+      this.currentlyExecutingProgramRunnerId = programRunnerRef.id
+    } catch (error) {
+      if (error instanceof AxiosError && error.response && error.request) {
+        this.logError(
+          `${error.response.status} ${error.response.statusText} from ${error.response.config.url} ${JSON.stringify(error.response.data)}`,
+        )
+      } else {
+        this.logError(JSON.stringify(error))
+      }
+      runInAction(() => {
+        this.executionState = "idle"
+      })
+    }
+  }
+
+  async stopProgram() {
+    if (!this.currentlyExecutingProgramRunnerId) return
+    runInAction(() => {
+      this.executionState = "stopping"
+    })
+
+    try {
+      await this.nova.api.program.stopProgramRunner(
+        this.currentlyExecutingProgramRunnerId,
+      )
+    } catch (err) {
+      // Reactivate the stop button so user can try again
+      runInAction(() => {
+        this.executionState = "executing"
+      })
+      throw err
+    }
+  }
+
+  reset() {
+    this.currentProgram = {}
+  }
+
+  log(message: string) {
+    console.log(message)
+    this.logs.push({
+      timestamp: Date.now(),
+      message,
+    })
+  }
+
+  logError(message: string) {
+    console.log(message)
+    this.logs.push({
+      timestamp: Date.now(),
+      message,
+      level: "error",
+    })
+  }
+}

package/src/lib/v2/index.ts

@@ -0,0 +1,7 @@
+export * from "@wandelbots/nova-api/v2"
+export * from "./ConnectedMotionGroup"
+export * from "./JoggerConnection"
+export * from "./MotionStreamConnection"
+export * from "./NovaCellAPIClient"
+export * from "./NovaClient"
+export * from "./ProgramStateConnection"