@pickleball/expo-sdk 0.1.1

package/src/native-runtime.ts

@@ -0,0 +1,241 @@
+import type { EngineDependencies, SdkNetwork, SdkRuntime, SdkStorage, TelemetrySink } from "./engine";
+import { LiveKitRoomAdapter, type NativeLiveKitBindings } from "./livekit-room-adapter";
+import { UnsupportedRuntimeError } from "./errors";
+
+declare const require: (name: string) => any;
+
+let globalsRegistered = false;
+
+export function createNativeLiveKitBindings(): NativeLiveKitBindings {
+  const reactNativeLiveKit = require("@livekit/react-native");
+  const liveKit = require("livekit-client");
+  return {
+    registerGlobals() {
+      if (!globalsRegistered) {
+        reactNativeLiveKit.registerGlobals();
+        globalsRegistered = true;
+      }
+    },
+    createRoom: () => new liveKit.Room({ adaptiveStream: false, dynacast: false }),
+    createLocalTracks: liveKit.createLocalTracks,
+    startAudioSession: () => reactNativeLiveKit.AudioSession.startAudioSession(),
+    stopAudioSession: () => reactNativeLiveKit.AudioSession.stopAudioSession(),
+    isLandscape() {
+      const { width, height } = require("react-native").Dimensions.get("window");
+      return width > height;
+    },
+    async listCameras() {
+      const { mediaDevices } = require("@livekit/react-native-webrtc");
+      const devices: Array<{
+        kind?: string;
+        deviceId?: string;
+        label?: string;
+        facing?: string;
+      }> = await mediaDevices.enumerateDevices();
+      return devices
+        .filter((device) => device.kind === "videoinput" && device.deviceId)
+        .map((device) => ({
+          deviceId: String(device.deviceId),
+          label: String(device.label ?? ""),
+          facing:
+            device.facing === "front" || device.facing === "environment"
+              ? device.facing
+              : ("unknown" as const),
+        }));
+    },
+    cameraSource: liveKit.Track.Source.Camera,
+    events: {
+      reconnecting: liveKit.RoomEvent.Reconnecting,
+      reconnected: liveKit.RoomEvent.Reconnected,
+      disconnected: liveKit.RoomEvent.Disconnected,
+      mediaDevicesError: liveKit.RoomEvent.MediaDevicesError,
+      dataReceived: liveKit.RoomEvent.DataReceived,
+    },
+  };
+}
+
+export function createDefaultRuntime(): SdkRuntime {
+  const { NativeModules, Platform } = require("react-native");
+  return {
+    assertSupported() {
+      if (
+        (Platform.OS !== "ios" && Platform.OS !== "android") ||
+        !NativeModules.LivekitReactNativeModule
+      ) {
+        throw new UnsupportedRuntimeError();
+      }
+    },
+    async requestPermissions() {
+      try {
+        const { mediaDevices } = require("@livekit/react-native-webrtc");
+        const stream = await mediaDevices.getUserMedia({ audio: true, video: true });
+        for (const track of stream.getTracks()) track.stop();
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    activateKeepAwake() {
+      return require("expo-keep-awake").activateKeepAwakeAsync(
+        "@pickleball/expo-sdk",
+      );
+    },
+    deactivateKeepAwake() {
+      return require("expo-keep-awake").deactivateKeepAwake(
+        "@pickleball/expo-sdk",
+      );
+    },
+  };
+}
+
+export function createDefaultStorage(): SdkStorage {
+  require("expo-sqlite/localStorage/install");
+  return {
+    getItem: async (key) => globalThis.localStorage.getItem(key),
+    setItem: async (key, value) => globalThis.localStorage.setItem(key, value),
+    removeItem: async (key) => globalThis.localStorage.removeItem(key),
+  };
+}
+
+export function createDefaultNetwork(): SdkNetwork {
+  const NetInfo = require("@react-native-community/netinfo").default;
+  let online = true;
+  void NetInfo.fetch().then((state: { isConnected?: boolean | null }) => {
+    online = state.isConnected !== false;
+  });
+  return {
+    isOnline: () => online,
+    subscribe(listener) {
+      return NetInfo.addEventListener((state: { isConnected?: boolean | null }) => {
+        online = state.isConnected !== false;
+        listener(online);
+      });
+    },
+  };
+}
+
+export function createDefaultTelemetry(
+  fetchImplementation = globalThis.fetch,
+  timeoutMs = 10_000,
+): TelemetrySink {
+  const controllers = new Set<AbortController>();
+  return {
+    async send(credentials, events) {
+      const body = JSON.stringify(events.slice(0, 20));
+      if (body.length > 24 * 1024) return;
+      const controller = new AbortController();
+      controllers.add(controller);
+      const timeout = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const response = await fetchImplementation(credentials.endpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${credentials.token}`,
+          },
+          body,
+          signal: controller.signal,
+          redirect: "error",
+        });
+        if (typeof response.text === "function") await response.text();
+        if (!response.ok) {
+          throw Object.assign(new Error("Telemetry rejected"), {
+            status: response.status,
+          });
+        }
+      } finally {
+        clearTimeout(timeout);
+        controllers.delete(controller);
+      }
+    },
+    dispose() {
+      for (const controller of controllers) controller.abort();
+      controllers.clear();
+    },
+  };
+}
+
+export function createDefaultRoomFactory(): EngineDependencies["roomFactory"] {
+  return () => new LiveKitRoomAdapter(createNativeLiveKitBindings());
+}
+
+/**
+ * Thu chỉ số thiết bị cho heartbeat. Mỗi nguồn là optional — thiếu package
+ * (expo-battery/expo-device/expo-file-system) thì bỏ qua trường đó thay vì lỗi.
+ */
+export function createDefaultDeviceMetrics(): NonNullable<
+  EngineDependencies["deviceMetrics"]
+> {
+  return async () => {
+    const metrics: Record<string, unknown> = {};
+    // TODO(debug): gỡ mảng notes + log sau khi xác minh collector trên thiết bị.
+    const notes: string[] = [];
+
+    try {
+      const Battery = require("expo-battery");
+      const level = await Battery.getBatteryLevelAsync();
+      if (typeof level === "number" && level >= 0) {
+        metrics.batteryPct = Math.round(level * 100);
+      } else {
+        notes.push(`battery level=${String(level)}`);
+      }
+      const state = await Battery.getBatteryStateAsync();
+      // BatteryState.CHARGING = 2, FULL = 3 (đang cắm nguồn).
+      if (typeof state === "number") metrics.charging = state === 2 || state === 3;
+    } catch (error) {
+      notes.push(`battery require/call: ${String(error)}`);
+    }
+
+    try {
+      let FileSystem: {
+        getFreeDiskStorageAsync?: () => Promise<number>;
+      };
+      try {
+        FileSystem = require("expo-file-system/legacy");
+      } catch {
+        FileSystem = require("expo-file-system");
+      }
+      if (FileSystem.getFreeDiskStorageAsync) {
+        const freeBytes = await FileSystem.getFreeDiskStorageAsync();
+        metrics.storageFreeGb = Math.round(freeBytes / 1e8) / 10;
+      } else {
+        notes.push("filesystem: getFreeDiskStorageAsync missing");
+      }
+    } catch (error) {
+      notes.push(`filesystem: ${String(error)}`);
+    }
+
+    try {
+      const Device = require("expo-device");
+      if (typeof Device.totalMemory === "number") {
+        metrics.ramTotalMb = Math.round(Device.totalMemory / 1_048_576);
+      }
+    } catch {
+      /* expo-device chưa được cài */
+    }
+
+    try {
+      const NetInfo = require("@react-native-community/netinfo").default;
+      const status = await NetInfo.fetch();
+      if (status?.type) {
+        metrics.netType =
+          status.type === "wifi"
+            ? "WiFi"
+            : status.type === "cellular"
+              ? String(
+                  status.details?.cellularGeneration ?? "cellular",
+                ).toUpperCase()
+              : status.type;
+      }
+    } catch {
+      /* netinfo không khả dụng */
+    }
+
+    // TODO(debug): gỡ sau khi xác minh collector trên thiết bị.
+    if (notes.length > 0) console.log("[pickleball] metrics notes:", notes.join(" | "));
+
+    return Object.keys(metrics).length > 0
+      ? (metrics as import("./engine").DeviceMetricsSample)
+      : null;
+  };
+}

package/src/plugin.ts

@@ -0,0 +1,145 @@
+import {
+  AndroidConfig,
+  createRunOncePlugin,
+  withAndroidManifest,
+  withDangerousMod,
+  withInfoPlist,
+  withPlugins,
+  type ConfigPlugin,
+} from "expo/config-plugins";
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { PICKLEBALL_EXPO_SDK_VERSION } from "./version";
+
+export interface PickleballLivePluginProps {
+  cameraPermission?: string;
+  microphonePermission?: string;
+  bluetoothPermission?: string;
+  consumeHidVolumeKeys?: boolean;
+  liveKit?: {
+    android?: { audioType?: string; enableScreenShareService?: boolean };
+    ios?: { enableMultitaskingCameraAccess?: boolean };
+  };
+}
+
+const ANDROID_PERMISSIONS = [
+  "android.permission.ACCESS_NETWORK_STATE",
+  "android.permission.BLUETOOTH",
+  "android.permission.BLUETOOTH_ADMIN",
+  "android.permission.BLUETOOTH_SCAN",
+  "android.permission.BLUETOOTH_CONNECT",
+  "android.permission.ACCESS_FINE_LOCATION",
+  "android.permission.CAMERA",
+  "android.permission.INTERNET",
+  "android.permission.MODIFY_AUDIO_SETTINGS",
+  "android.permission.RECORD_AUDIO",
+  "android.permission.WAKE_LOCK",
+] as const;
+
+export function injectHidVolumeMainActivity(source: string): string {
+  if (source.includes("PickleballRemoteHidDispatcher.dispatch(event)")) return source;
+  if (!/class\s+MainActivity\s*:\s*ReactActivity\(\)\s*\{/.test(source)) {
+    throw new Error("Pickleball HID volume integration requires a generated Kotlin MainActivity");
+  }
+  if (/override\s+fun\s+dispatchKeyEvent/.test(source)) {
+    throw new Error("MainActivity already overrides dispatchKeyEvent; forward it to PickleballRemoteHidDispatcher manually");
+  }
+  let updated = source;
+  if (!updated.includes("import android.view.KeyEvent")) {
+    updated = updated.replace(/(package\s+[^\n]+\n)/, "$1\nimport android.view.KeyEvent\nimport expo.modules.pickleballremote.PickleballRemoteHidDispatcher\n");
+  }
+  const closing = updated.lastIndexOf("}");
+  return `${updated.slice(0, closing)}\n  override fun dispatchKeyEvent(event: KeyEvent): Boolean {\n    if (PickleballRemoteHidDispatcher.dispatch(event)) return true\n    return super.dispatchKeyEvent(event)\n  }\n${updated.slice(closing)}`;
+}
+
+async function findMainActivity(directory: string): Promise<string | null> {
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      const found = await findMainActivity(path);
+      if (found) return found;
+    } else if (entry.name === "MainActivity.kt") return path;
+  }
+  return null;
+}
+
+const withPickleballLive: ConfigPlugin<PickleballLivePluginProps | undefined> = (
+  config,
+  props = {},
+) => {
+  const cameraPermission =
+    props?.cameraPermission ??
+    "Allow $(PRODUCT_NAME) to use the camera for livestreaming.";
+  const microphonePermission =
+    props?.microphonePermission ??
+    "Allow $(PRODUCT_NAME) to use the microphone for livestreaming.";
+  const bluetoothPermission =
+    props?.bluetoothPermission ??
+    "Cho phép $(PRODUCT_NAME) dùng Bluetooth để nhận thao tác từ nút điều khiển trên sân.";
+
+  config = withPlugins(config, [
+    ["@livekit/react-native-expo-plugin", props?.liveKit],
+  ]);
+  config.ios = { ...config.ios, bitcode: false };
+  config = withInfoPlist(config, (mod) => {
+    mod.modResults.NSCameraUsageDescription = cameraPermission;
+    mod.modResults.NSMicrophoneUsageDescription = microphonePermission;
+    mod.modResults.NSBluetoothAlwaysUsageDescription = bluetoothPermission;
+    return mod;
+  });
+  config = AndroidConfig.Permissions.withPermissions(config, [
+    ...ANDROID_PERMISSIONS,
+  ]);
+  config = withAndroidManifest(config, (mod) => {
+    const manifest = mod.modResults.manifest;
+    const existing = manifest["uses-permission"] ?? [];
+    const requiredAttributes: Record<string, Record<string, string>> = {
+      "android.permission.BLUETOOTH": { "android:maxSdkVersion": "30" },
+      "android.permission.BLUETOOTH_ADMIN": { "android:maxSdkVersion": "30" },
+      "android.permission.ACCESS_FINE_LOCATION": { "android:maxSdkVersion": "30" },
+      "android.permission.BLUETOOTH_SCAN": {
+        "android:usesPermissionFlags": "neverForLocation",
+      },
+    };
+    const byName = new Map<string, (typeof existing)[number]>();
+    for (const entry of existing) {
+      const name = entry.$?.["android:name"];
+      if (name && !byName.has(name)) byName.set(name, entry);
+    }
+    for (const permission of ANDROID_PERMISSIONS) {
+      const entry = byName.get(permission) ?? { $: { "android:name": permission } };
+      entry.$ = {
+        "android:name": permission,
+        ...(requiredAttributes[permission] ?? {}),
+      };
+      byName.set(permission, entry);
+    }
+    const requiredNames = new Set<string>(ANDROID_PERMISSIONS);
+    manifest["uses-permission"] = [
+      ...existing.filter((entry) => {
+        const name = entry.$?.["android:name"];
+        return !name || !requiredNames.has(name);
+      }),
+      ...ANDROID_PERMISSIONS.map((name) => byName.get(name)!),
+    ];
+    return mod;
+  });
+  if (props?.consumeHidVolumeKeys !== false) {
+    config = withDangerousMod(config, ["android", async (mod) => {
+      const root = join(mod.modRequest.platformProjectRoot, "app", "src", "main", "java");
+      const path = await findMainActivity(root);
+      if (!path) throw new Error("Generated Android MainActivity.kt was not found");
+      const source = await readFile(path, "utf8");
+      const updated = injectHidVolumeMainActivity(source);
+      if (updated !== source) await writeFile(path, updated);
+      return mod;
+    }]);
+  }
+  return config;
+};
+
+export default createRunOncePlugin(
+  withPickleballLive,
+  "@pickleball/expo-sdk",
+  PICKLEBALL_EXPO_SDK_VERSION,
+);

package/src/provider.tsx

@@ -0,0 +1,176 @@
+import React, { useEffect, useRef, useSyncExternalStore, type ReactNode } from "react";
+import { AppState } from "react-native";
+import type { BootstrapInput, LivestreamSessionProvider, StartLivestreamInput, EndReason } from "./contracts";
+import { ExpoSdkConfigurationError, type PickleballExpoError } from "./errors";
+import {
+  LivestreamEngine,
+  type EngineDependencies,
+  type LivestreamSnapshot,
+  type RoomAdapter,
+  type SdkNetwork,
+  type SdkRuntime,
+  type SdkStorage,
+  type TelemetrySink,
+} from "./engine";
+import {
+  createDefaultDeviceMetrics,
+  createDefaultNetwork,
+  createDefaultRoomFactory,
+  createDefaultRuntime,
+  createDefaultStorage,
+  createDefaultTelemetry,
+} from "./native-runtime";
+
+export interface LivestreamTheme {
+  background: string;
+  foreground: string;
+  accent: string;
+  danger: string;
+  /** Chữ phụ mờ nhất (labels, chú thích). */
+  muted: string;
+  overlay: string;
+  radius: number;
+  /** Token FintechX — đồng bộ với dashboard web. */
+  surface: string;
+  elevated: string;
+  hairline: string;
+  /** Màu chữ đặt trên nền accent. */
+  ink: string;
+  textSecondary: string;
+  radiusSm: number;
+  fontFamily?: string;
+  fontFamilyBold?: string;
+  displayFontFamily?: string;
+}
+
+/** FintechX design tokens — trùng bộ token trong apps/web/globals.css. */
+export const defaultLivestreamTheme: LivestreamTheme = {
+  background: "#0a0a0b",
+  foreground: "#f5f6f7",
+  accent: "#b4ff39",
+  danger: "#fb7185",
+  muted: "#6c7079",
+  overlay: "rgba(10,10,11,0.82)",
+  radius: 14,
+  surface: "#131417",
+  elevated: "#1b1d21",
+  hairline: "rgba(255,255,255,0.09)",
+  ink: "#0a0a0b",
+  textSecondary: "#a7abb3",
+  radiusSm: 6,
+};
+
+export interface PickleballLiveProviderProps {
+  children?: ReactNode;
+  sessionProvider: LivestreamSessionProvider;
+  bootstrapInput: BootstrapInput;
+  runtime?: SdkRuntime;
+  storage?: SdkStorage;
+  network?: SdkNetwork;
+  telemetry?: TelemetrySink;
+  roomFactory?: () => RoomAdapter;
+  deviceMetrics?: EngineDependencies["deviceMetrics"];
+  theme?: Partial<LivestreamTheme>;
+  locale?: "vi" | "en";
+  onError?: (error: PickleballExpoError) => void;
+}
+
+export interface LivestreamContextValue extends LivestreamSnapshot {
+  locale: "vi" | "en";
+  theme: LivestreamTheme;
+  prepare(): Promise<void>;
+  start(
+    input: StartLivestreamInput,
+    options?: { autoPublish?: boolean },
+  ): Promise<void>;
+  /** Bắt đầu phát khi đang standby. */
+  startPublishing(): Promise<void>;
+  /** Tạm dừng phát về standby (không kết thúc phiên). */
+  stopPublishing(): Promise<void>;
+  stop(reason?: EndReason): Promise<void>;
+  retry(): Promise<void>;
+  switchCamera(): Promise<void>;
+  setMicrophoneEnabled(enabled: boolean): Promise<void>;
+  setCaptureOrientation(orientation: "portrait" | "landscape"): Promise<void>;
+  selectCamera(deviceId: string): Promise<void>;
+}
+
+const LivestreamContext = React.createContext<LivestreamContextValue | null>(null);
+
+export function PickleballLiveProvider(props: PickleballLiveProviderProps) {
+  const engineRef = useRef<LivestreamEngine | null>(null);
+  const effectGenerationRef = useRef(0);
+  if (!engineRef.current) {
+    const dependencies: EngineDependencies = {
+      sessionProvider: props.sessionProvider,
+      bootstrapInput: props.bootstrapInput,
+      runtime: props.runtime ?? createDefaultRuntime(),
+      storage: props.storage ?? createDefaultStorage(),
+      network: props.network ?? createDefaultNetwork(),
+      telemetry: props.telemetry ?? createDefaultTelemetry(),
+      deviceMetrics: props.deviceMetrics ?? createDefaultDeviceMetrics(),
+      roomFactory: props.roomFactory ?? createDefaultRoomFactory(),
+    };
+    engineRef.current = new LivestreamEngine(dependencies);
+  }
+  const engine = engineRef.current;
+  const snapshot = useSyncExternalStore(
+    engine.subscribe,
+    engine.getSnapshot,
+    engine.getSnapshot,
+  );
+
+  useEffect(() => {
+    const effectGeneration = ++effectGenerationRef.current;
+    void engine.initialize();
+    const subscription = AppState.addEventListener("change", (state) => {
+      engine.handleAppState(
+        state === "active" ? "active" : state === "background" ? "background" : "inactive",
+      );
+    });
+    return () => {
+      subscription.remove();
+      queueMicrotask(() => {
+        if (effectGenerationRef.current === effectGeneration) {
+          void engine.dispose();
+        }
+      });
+    };
+  }, [engine]);
+
+  useEffect(() => {
+    if (snapshot.error) props.onError?.(snapshot.error);
+  }, [props.onError, snapshot.error]);
+
+  const value: LivestreamContextValue = {
+    ...snapshot,
+    locale: props.locale ?? "vi",
+    theme: { ...defaultLivestreamTheme, ...props.theme },
+    prepare: () => engine.prepare(),
+    start: (input, options) => engine.start(input, options),
+    startPublishing: () => engine.startPublishing(),
+    stopPublishing: () => engine.stopPublishing(),
+    stop: (reason) => engine.stop(reason),
+    retry: () => engine.retry(),
+    switchCamera: () => engine.switchCamera(),
+    setMicrophoneEnabled: (enabled) => engine.setMicrophoneEnabled(enabled),
+    setCaptureOrientation: (orientation) =>
+      engine.setCaptureOrientation(orientation),
+    selectCamera: (deviceId) => engine.selectCamera(deviceId),
+  };
+  return (
+    <LivestreamContext.Provider value={value}>
+      {props.children}
+    </LivestreamContext.Provider>
+  );
+}
+
+export function useLivestream() {
+  const value = React.use(LivestreamContext);
+  if (!value) {
+    throw new ExpoSdkConfigurationError(
+      "useLivestream must be used inside PickleballLiveProvider",
+    );
+  }
+  return value;
+}

package/src/version.ts

@@ -0,0 +1,4 @@
+import { version } from "../package.json";
+
+/** Package version used by bootstrap and the Expo run-once plugin. */
+export const PICKLEBALL_EXPO_SDK_VERSION: string = version;