@mentra/cloud-client 0.1.0-dev.0

package/node/index.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview The `@mentra/cloud-client/node` build: a server-wired CloudClient.
+ *
+ * This is the import the backend test harness and the dev stack use. It is a
+ * thin wrapper over the shared `CloudClient`: it pre-wires the Node transports
+ * (the `ws` package, `dgram`, and an in-memory store) so a caller passes only
+ * `{ endpoints, auth, ... }` and never has to hand-build sockets. The shared
+ * logic lives entirely in the root build; nothing platform-specific leaks past
+ * this file.
+ *
+ * See docs/issues/004-cloud-client/design.md ("node/index.ts").
+ */
+import { CloudClient as Base } from "@mentra/cloud-client";
+import type { CloudClientConfig } from "@mentra/cloud-client";
+import { nodeTransports } from "./transports";
+
+/**
+ * A `CloudClient` with the Node transports already supplied.
+ *
+ * The constructor takes the full config minus `transports`: the platform build
+ * owns that piece, so a host cannot accidentally pass server sockets to the
+ * device build or vice versa. We forward everything else through unchanged and
+ * inject a fresh transport bundle on construction.
+ */
+export class CloudClient extends Base {
+  constructor(config: Omit<CloudClientConfig, "transports">) {
+    super({ ...config, transports: nodeTransports() });
+  }
+}
+
+// Re-export the public surface so a host can import the client and the types it
+// needs from the single `@mentra/cloud-client/node` entry, matching the device
+// build's ergonomics.
+export type {
+  CloudClientConfig,
+  AuthConfig,
+  SubjectTokenType,
+  CloudClientTransports,
+  WebSocketLike,
+  UdpSocketLike,
+  KeyValueStore,
+  Logger,
+  RuntimeAudioTransport,
+  RuntimeSnapshot,
+  RuntimeStatus,
+  RuntimeTtsSpeakOptions,
+  RuntimeTtsSpeechSource,
+} from "@mentra/cloud-client";
+export {
+  CloudClientError,
+  HttpError,
+  AuthExpiredError,
+  noopLogger,
+} from "@mentra/cloud-client";

package/node/transports.ts

@@ -0,0 +1,133 @@
+/**
+ * @fileoverview Node/Bun implementations of the three platform transports.
+ *
+ * This is one of the two platform-specific files for a server (the test harness
+ * and the dev stack import it). It maps the abstract transport interfaces the
+ * shared core depends on onto concrete server primitives: the `ws` package for
+ * the WebSocket, Node's `dgram` for UDP audio, and an in-memory Map for token
+ * storage. Nothing here knows about the protocol or the modules above; it only
+ * adapts socket and storage shapes.
+ *
+ * See docs/issues/004-cloud-client/design.md ("node/transports.ts" and "The
+ * pieces passed in per platform").
+ */
+import WebSocket from "ws";
+import { createSocket } from "node:dgram";
+import type {
+  CloudClientTransports,
+  WebSocketLike,
+  UdpSocketLike,
+  KeyValueStore,
+} from "@mentra/cloud-client";
+
+/**
+ * Adapt the `ws` package to `WebSocketLike`.
+ *
+ * The shared core expects callback registration (onOpen/onMessage/...), not the
+ * EventEmitter that `ws` exposes, so each registrar forwards to a `ws` event.
+ * We force every inbound frame to a string because the runtime protocol is text
+ * JSON: `ws` hands binary frames as Buffer/ArrayBuffer, so we normalise to a
+ * UTF-8 string rather than leaking a Buffer up into the protocol layer.
+ */
+function nodeWebSocket(url: string): WebSocketLike {
+  const socket = new WebSocket(url);
+
+  return {
+    send(data: string): void {
+      socket.send(data);
+    },
+    sendBinary(data: Uint8Array): void {
+      socket.send(Buffer.from(data.buffer, data.byteOffset, data.byteLength));
+    },
+    close(): void {
+      socket.close();
+    },
+    onOpen(cb: () => void): void {
+      socket.on("open", cb);
+    },
+    onMessage(cb: (data: string) => void): void {
+      socket.on("message", (data: WebSocket.RawData, isBinary: boolean) => {
+        // The protocol is always text JSON. `ws` still surfaces frames as
+        // Buffer; decode to a UTF-8 string so the runtime never sees raw bytes.
+        cb(isBinary ? data.toString("utf8") : data.toString());
+      });
+    },
+    onClose(cb: (info: { code: number; reason: string }) => void): void {
+      socket.on("close", (code: number, reason: Buffer) => {
+        cb({ code, reason: reason.toString("utf8") });
+      });
+    },
+    onError(cb: (err: unknown) => void): void {
+      socket.on("error", (err: unknown) => {
+        cb(err);
+      });
+    },
+  };
+}
+
+/**
+ * Adapt Node `dgram` to `UdpSocketLike` for the audio path.
+ *
+ * The encrypted frame is built in the shared core, so this adapter only moves
+ * bytes: `send` targets the per-session host/port from `connection.ack`, and
+ * inbound datagrams are handed up as raw bytes. We open an IPv4 UDP socket
+ * because the audio host/port the cloud assigns is an IPv4 endpoint.
+ */
+function nodeUdpSocket(): UdpSocketLike {
+  const socket = createSocket("udp4");
+
+  return {
+    send(bytes: Uint8Array, host: string, port: number): void {
+      socket.send(bytes, port, host);
+    },
+    onMessage(cb: (bytes: Uint8Array) => void): void {
+      socket.on("message", (msg: Buffer) => {
+        cb(msg);
+      });
+    },
+    close(): void {
+      socket.close();
+    },
+  };
+}
+
+/**
+ * An in-memory `KeyValueStore`.
+ *
+ * A server has no OS secure store and usually does not need credentials to
+ * survive a process restart (the test harness re-exchanges on each run), so a
+ * plain Map is enough. Each call returns a resolved promise to match the async
+ * interface the device's secure store requires.
+ */
+function memoryStorage(): KeyValueStore {
+  const map = new Map<string, string>();
+
+  return {
+    get(key: string): Promise<string | null> {
+      return Promise.resolve(map.has(key) ? (map.get(key) as string) : null);
+    },
+    set(key: string, value: string): Promise<void> {
+      map.set(key, value);
+      return Promise.resolve();
+    },
+    delete(key: string): Promise<void> {
+      map.delete(key);
+      return Promise.resolve();
+    },
+  };
+}
+
+/**
+ * Build the Node transport bundle handed to the root `CloudClient`.
+ *
+ * `ws` and `udp` are factories because the runtime opens a fresh socket on every
+ * (re)connect and a fresh UDP socket per session; `storage` is a single instance
+ * because the token state is shared for the client's whole lifetime.
+ */
+export function nodeTransports(): CloudClientTransports {
+  return {
+    ws: nodeWebSocket,
+    udp: nodeUdpSocket,
+    storage: memoryStorage(),
+  };
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@mentra/cloud-client",
+  "version": "0.1.0-dev.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./react-native": "./react-native/index.ts",
+    "./node": "./node/index.ts"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@mentra/cloud-protocol": "^0.1.0-dev.0",
+    "tweetnacl": "^1.0.3"
+  },
+  "devDependencies": {
+    "ws": "^8.18.0",
+    "@types/ws": "^8.5.12"
+  },
+  "peerDependencies": {
+    "ws": "^8.18.0"
+  },
+  "peerDependenciesMeta": {
+    "ws": {
+      "optional": true
+    }
+  },
+  "files": [
+    "src",
+    "react-native",
+    "node",
+    "!src/**/*.test.ts",
+    "!react-native/**/*.test.ts",
+    "!node/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mentra-Community/MentraOS.git",
+    "directory": "cloud-v2/packages/cloud-client"
+  }
+}

package/react-native/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview The React Native build: `@mentra/cloud-client/react-native`.
+ *
+ * This is what the mobile app imports. It is a thin wrapper over the shared
+ * `CloudClient` that supplies the phone's transports (WebSocket, native UDP,
+ * secure storage), so a host only passes `{ endpoints, auth }` and never has to
+ * hand-wire sockets.
+ *
+ * The UDP and secure-storage transports are host-injected (React Native ships
+ * neither). The host wires them once at startup via `setNativeUdp` and
+ * `setSecureStorage`, which are re-exported here for convenience.
+ *
+ * See docs/issues/004-cloud-client/design.md ("react-native/index.ts").
+ */
+import { CloudClient as Base } from "@mentra/cloud-client";
+import type { CloudClientConfig } from "@mentra/cloud-client";
+import { reactNativeTransports } from "./transports";
+
+/**
+ * A `CloudClient` pre-wired with the React Native transports.
+ *
+ * It takes the config minus `transports` (this build fills those in), so on the
+ * phone construction is just `new CloudClient({ endpoints, auth })`.
+ */
+export class CloudClient extends Base {
+  constructor(config: Omit<CloudClientConfig, "transports">) {
+    super({ ...config, transports: reactNativeTransports() });
+  }
+}
+
+// The host wires the phone's native UDP and secure store through these before
+// constructing a client that uses UDP audio or token persistence.
+export { setNativeUdp, setSecureStorage } from "./transports";
+export type { NativeUdpFactory } from "./transports";
+
+// Re-export the public surface so a host can import everything (types, errors,
+// the logger hook) from the platform build without also reaching for the root.
+export * from "@mentra/cloud-client";

package/react-native/transports.ts

@@ -0,0 +1,216 @@
+/**
+ * @fileoverview The React Native transports: WebSocket, native UDP, secure store.
+ *
+ * This is the phone-side wiring for the three platform pieces the shared core
+ * takes as inputs (see src/transports.ts). It deliberately imports NOTHING from
+ * "react-native" or any native module, so the package still typechecks in CI
+ * (which runs on Node/Bun, where those modules do not exist). The phone-specific
+ * pieces are reached two ways:
+ *
+ *   - WebSocket: through the RN global `WebSocket`, which React Native provides
+ *     on `globalThis` (same shape as the browser one). We feature-detect it and
+ *     adapt it to WebSocketLike, so no import is needed.
+ *   - UDP and secure storage: through host-injected adapters. React Native has no
+ *     built-in UDP socket or secure key/value store, so the host app supplies the
+ *     real implementations (for example react-native-udp and expo-secure-store)
+ *     and wires them in via the setters below at startup. Until the host wires
+ *     them, calling these throws a clear error instead of failing silently.
+ *
+ * Security: tokens and keys flow through `storage` and the UDP frames, so the
+ * adapters here never log their values.
+ *
+ * See docs/issues/004-cloud-client/design.md ("react-native/transports.ts").
+ */
+import type {
+  CloudClientTransports,
+  WebSocketLike,
+  UdpSocketLike,
+  KeyValueStore,
+} from "../src/transports";
+
+/**
+ * The minimal shape of the global `WebSocket` we rely on, declared locally.
+ *
+ * We cannot use the DOM lib's `WebSocket` type because this package compiles
+ * with `lib: ["ES2022"]` (no DOM), so we describe just the members we touch.
+ * React Native's built-in `WebSocket` and the browser's both satisfy this.
+ */
+interface GlobalWebSocket {
+  send(data: string | ArrayBuffer): void;
+  close(): void;
+  onopen: ((ev: unknown) => void) | null;
+  onmessage: ((ev: { data: unknown }) => void) | null;
+  onclose: ((ev: { code: number; reason: string }) => void) | null;
+  onerror: ((ev: unknown) => void) | null;
+}
+interface GlobalWebSocketCtor {
+  new (url: string): GlobalWebSocket;
+}
+
+/**
+ * Wrap RN's global `WebSocket` (a browser-style event-property socket) into the
+ * callback-based WebSocketLike the runtime expects.
+ *
+ * The runtime registers each callback exactly once and opens a fresh socket per
+ * (re)connect, so a plain property assignment per event is enough; there is no
+ * need for an add/removeEventListener registry here.
+ */
+function adaptWebSocket(raw: GlobalWebSocket): WebSocketLike {
+  return {
+    send(data: string): void {
+      raw.send(data);
+    },
+    sendBinary(data: Uint8Array): void {
+      const copy = new Uint8Array(data.byteLength);
+      copy.set(data);
+      raw.send(copy.buffer);
+    },
+    close(): void {
+      raw.close();
+    },
+    onOpen(cb: () => void): void {
+      raw.onopen = () => cb();
+    },
+    onMessage(cb: (data: string) => void): void {
+      // RN delivers text frames as a string in `ev.data`; we only use text
+      // frames (the wire protocol is JSON), so coerce defensively to string.
+      raw.onmessage = (ev: { data: unknown }) => cb(String(ev.data));
+    },
+    onClose(cb: (info: { code: number; reason: string }) => void): void {
+      raw.onclose = (ev: { code: number; reason: string }) =>
+        cb({ code: ev.code, reason: ev.reason });
+    },
+    onError(cb: (err: unknown) => void): void {
+      raw.onerror = (ev: unknown) => cb(ev);
+    },
+  };
+}
+
+/**
+ * Build the WebSocket factory from the RN global, failing clearly if absent.
+ *
+ * We read the constructor off `globalThis` at call time (not module load) so a
+ * missing global only matters once a socket is actually opened, and the package
+ * still imports cleanly on a server where no global `WebSocket` exists.
+ */
+function makeWsFactory(): (url: string) => WebSocketLike {
+  return (url: string): WebSocketLike => {
+    const Ctor = (globalThis as { WebSocket?: GlobalWebSocketCtor }).WebSocket;
+    if (!Ctor) {
+      throw new Error(
+        "reactNativeTransports: global WebSocket is not available. " +
+          "Use @mentra/cloud-client/node off-device, or run on React Native.",
+      );
+    }
+    return adaptWebSocket(new Ctor(url));
+  };
+}
+
+/**
+ * The UDP socket the host wires in. React Native ships no UDP, so the host app
+ * provides one (for example backed by react-native-udp) via `setNativeUdp`.
+ */
+export type NativeUdpFactory = () => UdpSocketLike;
+
+/**
+ * The host-supplied UDP factory, or null until `setNativeUdp` is called.
+ *
+ * Module-level state is intentional: there is one phone process and one native
+ * UDP capability, so a single injected factory shared by every CloudClient in
+ * the process is the right granularity.
+ */
+let nativeUdpFactory: NativeUdpFactory | null = null;
+
+/**
+ * Wire in the platform's native UDP socket factory.
+ *
+ * The host calls this once during app startup, before constructing a CloudClient
+ * that uses UDP audio. Passing the factory (not a socket) matches UdpSocketLike's
+ * contract that a fresh socket is created per session.
+ */
+export function setNativeUdp(factory: NativeUdpFactory): void {
+  nativeUdpFactory = factory;
+}
+
+/**
+ * The secure key/value store the host wires in. React Native has no built-in
+ * persistent store, so the host provides one (for example expo-secure-store or
+ * react-native-keychain) via `setSecureStorage`.
+ */
+let secureStorage: KeyValueStore | null = null;
+
+/**
+ * Wire in the platform's secure storage.
+ *
+ * The host calls this once at startup so the refresh token survives relaunches.
+ * It must be a secure store (Keychain / Keystore-backed), not plain storage,
+ * because it holds the long-lived refresh token.
+ */
+export function setSecureStorage(store: KeyValueStore): void {
+  secureStorage = store;
+}
+
+/**
+ * A UDP factory that defers to whatever the host injected via `setNativeUdp`.
+ *
+ * It resolves the injected factory lazily, on each `udp()` call, so the host can
+ * wire UDP in any time before the first audio session, not strictly before the
+ * CloudClient is constructed.
+ */
+function makeUdpFactory(): () => UdpSocketLike {
+  return (): UdpSocketLike => {
+    if (!nativeUdpFactory) {
+      throw new Error(
+        "reactNativeTransports: native UDP is not wired. " +
+          "Call setNativeUdp(factory) at app startup before using UDP audio.",
+      );
+    }
+    return nativeUdpFactory();
+  };
+}
+
+/**
+ * A KeyValueStore that defers every call to the host-injected secure store.
+ *
+ * We return a stable wrapper (rather than the injected store directly) so the
+ * host may call `setSecureStorage` after `reactNativeTransports()` has already
+ * been handed to a CloudClient; each operation resolves the store at call time.
+ */
+function makeSecureStorage(): KeyValueStore {
+  function require(): KeyValueStore {
+    if (!secureStorage) {
+      throw new Error(
+        "reactNativeTransports: secure storage is not wired. " +
+          "Call setSecureStorage(store) at app startup (for example expo-secure-store).",
+      );
+    }
+    return secureStorage;
+  }
+  return {
+    get(key: string): Promise<string | null> {
+      return require().get(key);
+    },
+    set(key: string, value: string): Promise<void> {
+      return require().set(key, value);
+    },
+    delete(key: string): Promise<void> {
+      return require().delete(key);
+    },
+  };
+}
+
+/**
+ * Build the React Native transport bundle for `CloudClient`.
+ *
+ * WebSocket comes from the RN global; UDP and secure storage come from the
+ * host-injected adapters (`setNativeUdp` / `setSecureStorage`). The returned
+ * adapters resolve those injections lazily, so the host can wire them at startup
+ * independently of when this bundle is constructed.
+ */
+export function reactNativeTransports(): CloudClientTransports {
+  return {
+    ws: makeWsFactory(),
+    udp: makeUdpFactory(),
+    storage: makeSecureStorage(),
+  };
+}