@q9labsai/chalk-react-native 4.0.0

package/src/runtime.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it, vi } from "vitest";
+import { canUseLocalHostBootstrap, getMetroHostFromScriptUrl, isConfiguredLocalApiUrl, isDeviceLocalUrl, resolveAppRuntimeUrl, resolveDeviceLocalUrl, shouldAutoReadClipboard } from "./runtime";
+
+vi.mock("react-native", () => ({
+  NativeModules: { SourceCode: { scriptURL: null } },
+  Platform: {
+    OS: "ios",
+    Version: "17.0",
+    constants: { reactNativeVersion: { major: 0, minor: 83, patch: 2 } },
+  },
+}));
+
+describe("mobile runtime helpers", () => {
+  it("extracts the Metro host from a device script URL", () => {
+    expect(getMetroHostFromScriptUrl("http://192.168.18.245:8081/index.bundle?platform=android")).toBe("192.168.18.245");
+    expect(getMetroHostFromScriptUrl(null)).toBeNull();
+  });
+
+  it("rewrites localhost URLs to the Metro host for device builds", () => {
+    const scriptUrl = "http://192.168.18.245:8081/index.bundle?platform=android";
+
+    expect(resolveDeviceLocalUrl("http://localhost:8080", scriptUrl)).toBe("http://192.168.18.245:8080");
+    expect(resolveDeviceLocalUrl("ws://127.0.0.1:8080/ws", scriptUrl)).toBe("ws://192.168.18.245:8080/ws");
+    expect(resolveDeviceLocalUrl("https://chalk-api.q9labs.ai", scriptUrl)).toBe("https://chalk-api.q9labs.ai");
+  });
+
+  it("falls back to production URLs when release builds still carry localhost env values", () => {
+    expect(resolveDeviceLocalUrl("http://localhost:8080", null, "https://chalk-api.q9labs.ai")).toBe("https://chalk-api.q9labs.ai");
+    expect(resolveDeviceLocalUrl("ws://127.0.0.1:8080/ws", undefined, "wss://chalk-ws.q9labs.ai/ws")).toBe("wss://chalk-ws.q9labs.ai/ws");
+  });
+
+  it("preserves localhost URLs when the dev bundle is also served from localhost", () => {
+    const scriptUrl = "http://localhost:8081/index.bundle?platform=ios";
+
+    expect(resolveDeviceLocalUrl("http://localhost:8080", scriptUrl, "https://chalk-api.q9labs.ai")).toBe("http://localhost:8080");
+    expect(resolveDeviceLocalUrl("ws://127.0.0.1:8080/ws", scriptUrl, "wss://chalk-ws.q9labs.ai/ws")).toBe("ws://127.0.0.1:8080/ws");
+  });
+
+  it("hard-forces production URLs when release builds disallow device-local hosts", () => {
+    expect(
+      resolveAppRuntimeUrl({
+        configuredUrl: "http://localhost:8080",
+        scriptUrl: "file:///android_asset/index.android.bundle",
+        fallbackUrl: "https://chalk-api.q9labs.ai",
+        allowDeviceLocal: false,
+      }),
+    ).toBe("https://chalk-api.q9labs.ai");
+
+    expect(
+      resolveAppRuntimeUrl({
+        configuredUrl: "ws://localhost:8080/ws",
+        scriptUrl: "file:///android_asset/index.android.bundle",
+        fallbackUrl: "wss://chalk-ws.q9labs.ai/ws",
+        allowDeviceLocal: false,
+      }),
+    ).toBe("wss://chalk-ws.q9labs.ai/ws");
+  });
+
+  it("detects local device URLs", () => {
+    expect(isDeviceLocalUrl("http://localhost:8080")).toBe(true);
+    expect(isDeviceLocalUrl("ws://127.0.0.1:8080/ws")).toBe(true);
+    expect(isDeviceLocalUrl("https://chalk-api.q9labs.ai")).toBe(false);
+  });
+
+  it("detects configured local api urls even outside dev mode", () => {
+    expect(isConfiguredLocalApiUrl("http://localhost:8080")).toBe(true);
+    expect(isConfiguredLocalApiUrl(" ws://127.0.0.1:8080/ws ")).toBe(true);
+    expect(isConfiguredLocalApiUrl("https://chalk-api.q9labs.ai")).toBe(false);
+    expect(isConfiguredLocalApiUrl(undefined)).toBe(false);
+  });
+
+  it("only allows host bootstrap for resolved local runtime urls", () => {
+    expect(canUseLocalHostBootstrap("http://localhost:8080", true)).toBe(true);
+    expect(canUseLocalHostBootstrap("https://chalk-api.q9labs.ai", true)).toBe(false);
+    expect(canUseLocalHostBootstrap("http://localhost:8080", false)).toBe(false);
+  });
+
+  it("skips eager clipboard reads on the iOS simulator", () => {
+    expect(shouldAutoReadClipboard({ platform: "ios", isSimulator: true })).toBe(false);
+    expect(shouldAutoReadClipboard({ platform: "ios", isSimulator: false })).toBe(true);
+    expect(shouldAutoReadClipboard({ platform: "android", isSimulator: false })).toBe(true);
+  });
+});

package/src/runtime.ts

@@ -0,0 +1,142 @@
+import { NativeModules, Platform } from "react-native";
+
+const LOCAL_HOSTNAMES = new Set(["localhost", "127.0.0.1", "0.0.0.0"]);
+
+export interface DeviceInfo {
+  appVersion: string | null;
+  platform: string | null;
+  osVersion: string | null;
+  reactNativeVersion: string | null;
+  brand: string | null;
+  manufacturer: string | null;
+  model: string | null;
+  systemName: string | null;
+  interfaceIdiom: string | null;
+  hermesEnabled: boolean;
+  scriptUrl: string | null;
+}
+
+export function shouldAutoReadClipboard({ platform, isSimulator }: { platform: string; isSimulator: boolean }): boolean {
+  return !(platform === "ios" && isSimulator);
+}
+
+export function getReactNativeScriptUrl(): string | null {
+  return NativeModules.SourceCode?.scriptURL ?? NativeModules.SourceCode?.getConstants?.().scriptURL ?? null;
+}
+
+export function getMetroHostFromScriptUrl(scriptUrl: string | null | undefined): string | null {
+  if (!scriptUrl) {
+    return null;
+  }
+
+  try {
+    const parsed = new URL(scriptUrl);
+    return parsed.hostname || null;
+  } catch {
+    return null;
+  }
+}
+
+export function stripTrailingSlash(url: string): string {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+
+export function isDeviceLocalHostname(hostname: string): boolean {
+  return LOCAL_HOSTNAMES.has(hostname);
+}
+
+export function isDeviceLocalUrl(url: string): boolean {
+  try {
+    return isDeviceLocalHostname(new URL(url).hostname);
+  } catch {
+    return false;
+  }
+}
+
+export function isConfiguredLocalApiUrl(configuredUrl?: string | null): boolean {
+  const candidate = configuredUrl?.trim();
+  return !!candidate && isDeviceLocalUrl(candidate);
+}
+
+export function canUseLocalHostBootstrap(apiUrl: string, allowDeviceLocal: boolean): boolean {
+  return allowDeviceLocal && isDeviceLocalUrl(apiUrl);
+}
+
+export function resolveDeviceLocalUrl(url: string, scriptUrl?: string | null, fallbackUrl?: string): string {
+  try {
+    const parsed = new URL(url);
+    if (!isDeviceLocalHostname(parsed.hostname)) {
+      return stripTrailingSlash(url);
+    }
+
+    const metroHost = getMetroHostFromScriptUrl(scriptUrl);
+    if (!metroHost) {
+      if (fallbackUrl) {
+        return stripTrailingSlash(fallbackUrl);
+      }
+      return stripTrailingSlash(url);
+    }
+
+    if (isDeviceLocalHostname(metroHost)) {
+      return stripTrailingSlash(url);
+    }
+
+    parsed.hostname = metroHost;
+    return stripTrailingSlash(parsed.toString());
+  } catch {
+    return stripTrailingSlash(url);
+  }
+}
+
+export function resolveAppRuntimeUrl({ configuredUrl, scriptUrl, fallbackUrl, allowDeviceLocal }: { configuredUrl?: string | null; scriptUrl?: string | null; fallbackUrl: string; allowDeviceLocal: boolean }): string {
+  const candidate = configuredUrl?.trim();
+  if (!candidate) {
+    return stripTrailingSlash(fallbackUrl);
+  }
+
+  if (!allowDeviceLocal && isDeviceLocalUrl(candidate)) {
+    return stripTrailingSlash(fallbackUrl);
+  }
+
+  return resolveDeviceLocalUrl(candidate, scriptUrl, fallbackUrl);
+}
+
+export function getReactNativeVersionString(): string | null {
+  const version = Platform.constants?.reactNativeVersion;
+  if (!version) {
+    return null;
+  }
+
+  const major = typeof version.major === "number" ? version.major : null;
+  const minor = typeof version.minor === "number" ? version.minor : null;
+  const patch = typeof version.patch === "number" ? version.patch : null;
+  if (major === null || minor === null || patch === null) {
+    return null;
+  }
+
+  return `${major}.${minor}.${patch}`;
+}
+
+export function isHermesEnabled(): boolean {
+  return "HermesInternal" in globalThis;
+}
+
+const readPlatformString = (value: unknown): string | null => (typeof value === "string" && value.length > 0 ? value : null);
+
+export function getDeviceInfo({ appVersion = null, scriptUrl = getReactNativeScriptUrl() }: { appVersion?: string | null; scriptUrl?: string | null } = {}): DeviceInfo {
+  const constants = (Platform.constants ?? {}) as Record<string, unknown>;
+
+  return {
+    appVersion,
+    platform: Platform.OS,
+    osVersion: String(Platform.Version),
+    reactNativeVersion: getReactNativeVersionString(),
+    brand: readPlatformString(constants.Brand),
+    manufacturer: readPlatformString(constants.Manufacturer),
+    model: readPlatformString(constants.Model),
+    systemName: readPlatformString(constants.systemName),
+    interfaceIdiom: readPlatformString(constants.interfaceIdiom),
+    hermesEnabled: isHermesEnabled(),
+    scriptUrl,
+  };
+}

package/src/space-client/create-native-space-client.test.ts

@@ -0,0 +1,247 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const createSpaceClientForPlatform = vi.hoisted(() => vi.fn());
+const addAppStateListener = vi.hoisted(() => vi.fn());
+const createV1SyncClient = vi.hoisted(() => vi.fn());
+const createCloudflareSFUHTTPTransport = vi.hoisted(() => vi.fn(() => ({})));
+
+vi.mock("@q9labsai/chalk-client", () => ({
+  AsyncStorageV1PendingTargetStore: vi.fn(),
+  CloudflareSFUClient: vi.fn(),
+  createChalkChatFileHttpTransport: vi.fn(),
+  createChalkWhiteboardV1Client: vi.fn(),
+  createChalkWhiteboardV1FileHttpTransport: vi.fn(),
+  createCloudflareSFUHTTPTransport,
+  createReactNativeSyncLifecycle: vi.fn(() => ({})),
+  createReactNativeWebSocketFactory: vi.fn(() => ({})),
+  createV1SyncClient,
+}));
+vi.mock("@q9labsai/chalk-client/effect", () => ({ createSpaceClientForPlatform }));
+vi.mock("@cloudflare/react-native-webrtc", () => ({
+  RTCPeerConnection: vi.fn(),
+  mediaDevices: {
+    getDisplayMedia: vi.fn(),
+    getUserMedia: vi.fn(),
+  },
+}));
+vi.mock("react-native", () => ({
+  AppState: {
+    addEventListener: addAppStateListener,
+    currentState: "active",
+  },
+}));
+
+import { createNativeSpaceClient } from "./create-native-space-client";
+
+describe("native client creation", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    createSpaceClientForPlatform.mockReturnValue(spaceClient());
+    addAppStateListener.mockReturnValue({ remove: vi.fn() });
+  });
+
+  it("allows multiple native WebSocket attempts before Sync startup expires", () => {
+    createNativeSpaceClient(options());
+
+    expect(createSpaceClientForPlatform.mock.calls[0]?.[1]).toEqual(expect.objectContaining({ syncStartupTimeoutMs: 30_000 }));
+  });
+
+  it("preserves an explicit consumer Sync startup budget", () => {
+    createNativeSpaceClient({ ...options(), syncStartupTimeoutMs: 45_000 });
+
+    expect(createSpaceClientForPlatform.mock.calls[0]?.[1]).toEqual(expect.objectContaining({ syncStartupTimeoutMs: 45_000 }));
+  });
+
+  it("derives the canonical Sync origin from the default API origin", () => {
+    createNativeSpaceClient({ ...options(), baseUrl: undefined, syncUrl: undefined });
+
+    expect(createSpaceClientForPlatform.mock.calls[0]?.[1]).toEqual(expect.objectContaining({ apiBaseUrl: "https://api.chalkmeet.com", syncUrl: "wss://sync.chalkmeet.com/v1/sync" }));
+  });
+
+  it("passes the closed access callback to the client", () => {
+    const getAccess = vi.fn();
+    createNativeSpaceClient({ ...options(), getAccess });
+
+    expect(createSpaceClientForPlatform.mock.calls[0]?.[0]).toEqual(expect.objectContaining({ getAccess }));
+  });
+
+  it("forwards Space join spans into the correlated diagnostic timeline", () => {
+    const journey = {
+      context: { journeyId: "journey", rootJourneyId: "journey", traceparent: "00-11111111111111111111111111111111-2222222222222222-01" },
+      headers: {},
+      recordDiagnostic: vi.fn(),
+      recordRtcSummary: vi.fn(),
+      recordSyncFrame: vi.fn(),
+    };
+
+    createNativeSpaceClient({ ...options(), telemetry: journey });
+    const platform = createSpaceClientForPlatform.mock.calls[0]?.[1] as { readonly onConnectionDiagnostic: (event: unknown) => void };
+    platform.onConnectionDiagnostic({
+      event: "space_join_span",
+      state: "live",
+      epoch: 2,
+      step: "start_media",
+      spanId: "space-join-span-2",
+      parentSpanId: "space-join-span-1",
+      outcome: "succeeded",
+      durationMs: 12,
+      code: "media_start_failed",
+    });
+
+    expect(journey.recordDiagnostic).toHaveBeenCalledWith({
+      category: "connection",
+      code: "space.join.start_media.succeeded",
+      phase: "media",
+      state: "succeeded",
+      metricValue: 12,
+      attributes: {
+        span_id: "space-join-span-2",
+        parent_span_id: "space-join-span-1",
+        step: "start_media",
+        outcome: "succeeded",
+        epoch: 2,
+        failure_code: "media_start_failed",
+      },
+    });
+  });
+
+  it("passes telemetry context into the production Sync constructor", () => {
+    const journey = {
+      context: {
+        journeyId: "journey",
+        rootJourneyId: "journey",
+        traceparent: "00-11111111111111111111111111111111-2222222222222222-01",
+        tracestate: "chalk=native",
+      },
+      headers: {},
+      recordDiagnostic: vi.fn(),
+      recordRtcSummary: vi.fn(),
+      recordSyncFrame: vi.fn(),
+    };
+
+    createNativeSpaceClient({ ...options(), telemetry: journey });
+    const platform = createSpaceClientForPlatform.mock.calls[0]?.[1] as {
+      readonly telemetry: typeof journey.context;
+      readonly dependencies: { readonly createSyncClient: (input: unknown) => unknown };
+    };
+    expect(platform.telemetry).toEqual(journey.context);
+    platform.dependencies.createSyncClient({
+      access: { subject: { tenantId: "tenant", episodeId: "episode", participantId: "participant" } },
+      token: async () => "token",
+      media: {},
+      telemetry: platform.telemetry,
+    });
+
+    expect(createV1SyncClient).toHaveBeenCalledWith(expect.objectContaining({ telemetry: journey.context }));
+  });
+
+  it("revalidates access when the app returns to the foreground", () => {
+    createNativeSpaceClient(options());
+    const platform = createSpaceClientForPlatform.mock.calls[0]?.[1] as {
+      readonly dependencies: { readonly subscribeForeground: (listener: () => void) => () => void };
+    };
+
+    const refresh = vi.fn();
+    const unsubscribe = platform.dependencies.subscribeForeground(refresh);
+    const stateListener = addAppStateListener.mock.calls[0]?.[1] as (state: string) => void;
+
+    stateListener("background");
+    expect(refresh).not.toHaveBeenCalled();
+    stateListener("active");
+    expect(refresh).toHaveBeenCalledOnce();
+
+    unsubscribe();
+    expect(addAppStateListener.mock.results[0]?.value.remove).toHaveBeenCalledOnce();
+  });
+
+  it("bridges verified media credentials to telemetry and clears them at terminal teardown", async () => {
+    const client = spaceClient();
+    createSpaceClientForPlatform.mockReturnValue(client);
+    const setAuthenticatedTelemetryHeaders = vi.fn();
+    const journey = {
+      context: { journeyId: "journey", rootJourneyId: "journey", traceparent: "00-11111111111111111111111111111111-2222222222222222-01" },
+      headers: { "x-chalk-journey-id": "journey" },
+      recordDiagnostic: vi.fn(),
+      recordRtcSummary: vi.fn(),
+      recordSyncFrame: vi.fn(),
+      setAuthenticatedTelemetryHeaders,
+    };
+    createNativeSpaceClient({ ...options(), telemetry: journey });
+    const platform = createSpaceClientForPlatform.mock.calls[0]?.[1] as {
+      readonly dependencies: { readonly createMediaClient: (input: unknown) => unknown };
+    };
+    const credential = vi.fn().mockResolvedValueOnce("media-one").mockResolvedValueOnce("media-two").mockResolvedValueOnce("media-three");
+    platform.dependencies.createMediaClient({
+      access: { subject: { tenantId: "tenant", episodeId: "episode", participantId: "participant" }, media: { clientPayload: {} } },
+      credential,
+      onFailure: vi.fn(),
+      onScreenEnded: vi.fn(),
+    });
+
+    const transport = createCloudflareSFUHTTPTransport.mock.calls.at(-1)?.[0] as { readonly credential: () => Promise<string> };
+    await expect(transport.credential()).resolves.toBe("media-one");
+    await expect(transport.credential()).resolves.toBe("media-two");
+    expect(setAuthenticatedTelemetryHeaders).toHaveBeenNthCalledWith(1, { Authorization: "Bearer media-one" });
+    expect(setAuthenticatedTelemetryHeaders).toHaveBeenNthCalledWith(2, { Authorization: "Bearer media-two" });
+    expect(journey.recordDiagnostic).not.toHaveBeenCalledWith(expect.objectContaining({ attributes: expect.stringContaining("media-") }));
+    expect(JSON.stringify(journey.recordDiagnostic.mock.calls)).not.toContain("media-one");
+
+    client.setStatus("left");
+    expect(setAuthenticatedTelemetryHeaders).toHaveBeenLastCalledWith(undefined);
+    await expect(transport.credential()).resolves.toBe("media-three");
+    client.dispose();
+    expect(setAuthenticatedTelemetryHeaders).toHaveBeenLastCalledWith(undefined);
+    expect(credential).toHaveBeenCalledTimes(3);
+  });
+});
+
+function options() {
+  return {
+    space: "native-space",
+    getAccess: vi.fn(),
+    baseUrl: "https://api.chalk.test",
+    syncUrl: "wss://sync.chalk.test/v1/sync",
+  };
+}
+
+function spaceClient() {
+  const snapshot = {
+    connection: { status: "idle", episode: null, lastError: null },
+    self: { participantId: null, displayName: null, role: null, capabilities: [], handRaised: false, can: () => false },
+    participants: { roster: [], admissionQueue: [] },
+    media: {
+      devices: { microphones: [], cameras: [], speakers: [] },
+      selection: { microphone: null, camera: null, speaker: null },
+      local: {
+        microphone: { source: "microphone", state: "unavailable", track: null },
+        camera: { source: "camera", state: "unavailable", track: null },
+        screen: { source: "screen", state: "unavailable", track: null },
+      },
+      remote: [],
+      screenShare: { source: "screen", state: "unavailable", track: null },
+      incomingRequests: [],
+    },
+    chat: { status: "idle", messages: [], pendingSends: [], readReceipts: [], unreadCount: 0, pagination: { cursor: null, hasOlder: false, historyTruncated: false }, lastError: null },
+    reactions: { active: [] },
+    whiteboard: { open: false, engine: { status: "unsubscribed", sceneId: null, revision: null, error: null } },
+  } as const;
+  let currentSnapshot = snapshot;
+  const listeners = new Set<() => void>();
+  return {
+    media: {},
+    chat: { files: {} },
+    participants: {},
+    reactions: {},
+    whiteboard: { transport: () => null },
+    getSnapshot: () => currentSnapshot,
+    subscribe: (listener: () => void) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    setStatus: (status: "idle" | "failed" | "left") => {
+      currentSnapshot = { ...currentSnapshot, connection: { ...currentSnapshot.connection, status } };
+      listeners.forEach((listener) => listener());
+    },
+    dispose: vi.fn(),
+  };
+}