@pickleball/expo-sdk 0.1.1 → 0.2.0

package/dist/version.cjs

@@ -1,35 +1,7 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-// src/version.ts
-var version_exports = {};
-__export(version_exports, {
-  PICKLEBALL_EXPO_SDK_VERSION: () => PICKLEBALL_EXPO_SDK_VERSION
-});
-module.exports = __toCommonJS(version_exports);
+var _chunkTRLASNPQcjs = require('./chunk-TRLASNPQ.cjs');
+require('./chunk-7OX2DSKI.cjs');
 
-// package.json
-var version = "0.1.1";
 
-// src/version.ts
-var PICKLEBALL_EXPO_SDK_VERSION = version;
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  PICKLEBALL_EXPO_SDK_VERSION
-});
+exports.PICKLEBALL_EXPO_SDK_VERSION = _chunkTRLASNPQcjs.PICKLEBALL_EXPO_SDK_VERSION;

package/dist/version.js

@@ -1,6 +1,7 @@
 import {
   PICKLEBALL_EXPO_SDK_VERSION
-} from "./chunk-VHLUJQG5.js";
+} from "./chunk-6JOMESNT.js";
+import "./chunk-KFQGP6VL.js";
 export {
   PICKLEBALL_EXPO_SDK_VERSION
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pickleball/expo-sdk",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Foreground livestream engine, React hooks, UI, and Expo config plugin for Pickleball Live",
   "license": "MIT",
   "repository": {
@@ -27,6 +27,61 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./match": {
+      "react-native": "./src/match/index.ts",
+      "import": {
+        "types": "./dist/match/index.d.ts",
+        "default": "./dist/match/index.js"
+      },
+      "require": {
+        "types": "./dist/match/index.d.cts",
+        "default": "./dist/match/index.cjs"
+      }
+    },
+    "./match/voice": {
+      "react-native": "./src/match/voice/index.ts",
+      "import": {
+        "types": "./dist/match/voice/index.d.ts",
+        "default": "./dist/match/voice/index.js"
+      },
+      "require": {
+        "types": "./dist/match/voice/index.d.cts",
+        "default": "./dist/match/voice/index.cjs"
+      }
+    },
+    "./match/remote": {
+      "react-native": "./src/match/remote/index.ts",
+      "import": {
+        "types": "./dist/match/remote/index.d.ts",
+        "default": "./dist/match/remote/index.js"
+      },
+      "require": {
+        "types": "./dist/match/remote/index.d.cts",
+        "default": "./dist/match/remote/index.cjs"
+      }
+    },
+    "./device-agent": {
+      "react-native": "./src/device-agent/index.ts",
+      "import": {
+        "types": "./dist/device-agent/index.d.ts",
+        "default": "./dist/device-agent/index.js"
+      },
+      "require": {
+        "types": "./dist/device-agent/index.d.cts",
+        "default": "./dist/device-agent/index.cjs"
+      }
+    },
+    "./advanced": {
+      "react-native": "./src/advanced.ts",
+      "import": {
+        "types": "./dist/advanced.d.ts",
+        "default": "./dist/advanced.js"
+      },
+      "require": {
+        "types": "./dist/advanced.d.cts",
+        "default": "./dist/advanced.cjs"
+      }
+    },
     "./plugin": {
       "import": {
         "types": "./dist/plugin.d.ts",
@@ -37,6 +92,7 @@
         "default": "./dist/plugin.cjs"
       }
     },
+    "./app.plugin.js": "./app.plugin.js",
     "./version": {
       "react-native": "./src/version.ts",
       "import": {
@@ -68,11 +124,13 @@
     "video"
   ],
   "sideEffects": [
-    "./dist/native-runtime.*"
+    "./dist/native-runtime.*",
+    "./src/native-runtime.ts"
   ],
   "peerDependencies": {
     "@livekit/react-native": ">=2.11.1 <3",
     "@livekit/react-native-webrtc": ">=144.1.1 <145",
+    "@pickleball/rtmp-native": ">=0.1.0 <1",
     "@react-native-community/netinfo": ">=11 <13",
     "expo": ">=56 <58",
     "expo-audio": ">=56 <58",
@@ -86,7 +144,7 @@
   },
   "dependencies": {
     "@livekit/react-native-expo-plugin": "1.0.2",
-    "expo-speech": "^57.0.1",
+    "convex": "^1.42.1",
     "@pickleball/remote-native": "0.1.0",
     "@pickleball/voice-native": "0.1.0"
   },
@@ -114,10 +172,16 @@
     "react-test-renderer": "19.2.3",
     "tsup": "^8.5.0",
     "typescript": "^5.8.0",
+    "@pickleball/rtmp-native": "0.1.0",
     "@pickleball/shared": "0.1.0"
   },
+  "peerDependenciesMeta": {
+    "@pickleball/rtmp-native": {
+      "optional": true
+    }
+  },
   "scripts": {
-    "build": "tsup src/index.ts src/plugin.ts src/version.ts --format esm,cjs --dts --clean --external react --external react-native --external expo --external expo-sqlite --external livekit-client --external @livekit/react-native --external @livekit/react-native-webrtc",
+    "build": "tsup",
     "test": "jest --runInBand",
     "typecheck": "tsc --noEmit",
     "verify:pack": "node scripts/verify-pack.mjs",

package/src/advanced.ts

@@ -0,0 +1,47 @@
+/**
+ * API nâng cao: engine internals, dependency injection, adapter LiveKit và các
+ * factory runtime mặc định — dùng cho mock/test hoặc tuỳ biến sâu. App tích hợp
+ * thông thường không cần import từ đây.
+ */
+export {
+  LivestreamEngine,
+  LEGAL_LIVESTREAM_TRANSITIONS,
+  PENDING_END_KEY,
+  type EngineDependencies,
+  type RoomAdapter,
+  type RoomConnection,
+  type RoomEvent,
+  type SdkRuntime,
+  type SdkStorage,
+  type SdkNetwork,
+  type TelemetrySink,
+  type LivestreamSnapshot,
+  type DeviceMetricsSample,
+  type CaptureOrientation,
+  type CameraDeviceInfo,
+} from "./engine";
+export {
+  LiveKitRoomAdapter,
+  type NativeLiveKitBindings,
+  type LocalPreviewReference,
+} from "./livekit-room-adapter";
+export {
+  RtmpRoomAdapter,
+  type NativeRtmpBindings,
+  type RtmpStatus,
+} from "./rtmp-room-adapter";
+export {
+  createNativeLiveKitBindings,
+  createDefaultRuntime,
+  createDefaultStorage,
+  createDefaultNetwork,
+  createDefaultTelemetry,
+  createDefaultRoomFactory,
+  // Mode device-rtmp: thiết bị đẩy RTMP thẳng lên server tự host, không dùng
+  // LiveKit. Truyền vào prop roomFactory của PickleballLiveProvider để đổi mode.
+  createRtmpRoomFactory,
+  createNativeRtmpBindings,
+  createDefaultDeviceMetrics,
+} from "./native-runtime";
+// Context nội bộ cho module opt-in (PickleballDeviceAgent) cần engine trực tiếp
+export { useLivestreamHost, type LivestreamHostContextValue } from "./provider";

package/src/device-agent/agent.ts

@@ -0,0 +1,443 @@
+import type { BootstrapInput } from "../contracts";
+import type { DeviceMetricsSample, LivestreamEngine } from "../engine";
+import { normalizeError } from "../errors";
+
+/**
+ * DeviceAgent — đăng ký thiết bị với backend khi app mở và giữ heartbeat
+ * presence (12s/lần khi foreground) qua proxy. Khi dashboard yêu cầu "Kết nối",
+ * heartbeat trả về connect-token → agent mở kênh điều khiển realtime (Convex
+ * websocket) để nhận lệnh start/stop livestream tức thì. Publish/unpublish sau
+ * khi vào standby vẫn đi đường LiveKit data channel sẵn có của engine.
+ */
+
+export interface DeviceAgentDeviceInfo {
+  appVersion?: string;
+  deviceName?: string;
+  deviceModel?: string;
+  osVersion?: string;
+}
+
+export interface DeviceCommand {
+  id: string;
+  type: "start_livestream" | "stop_livestream";
+  payload: { title?: string; visibility?: "public" | "private" };
+  expiresAt: number;
+}
+
+export interface DeviceControlSessionGrant {
+  id: string;
+  token: string;
+  convexUrl: string;
+}
+
+export interface DeviceHeartbeatBody {
+  agentState?: string;
+  currentSessionId?: string | null;
+  appVersion?: string;
+  metrics?: Record<string, number | string>;
+}
+
+export interface DeviceAgentTransport {
+  register(
+    input: BootstrapInput & DeviceAgentDeviceInfo,
+  ): Promise<{ deviceId: string; heartbeatIntervalMs: number }>;
+  heartbeat(
+    input: BootstrapInput & DeviceHeartbeatBody,
+  ): Promise<{ controlSession: DeviceControlSessionGrant | null }>;
+}
+
+/** Kênh điều khiển realtime — mặc định là Convex websocket (convex-control-channel). */
+export interface DeviceControlChannel {
+  attach(controlSessionId: string, token: string): Promise<void>;
+  /** Subscribe lệnh pending — callback gọi lại mỗi khi danh sách đổi. */
+  onCommands(
+    controlSessionId: string,
+    token: string,
+    callback: (commands: DeviceCommand[]) => void,
+  ): () => void;
+  /** Subscribe trạng thái kênh — "ended"/"expired" thì agent tự đóng. */
+  onState(
+    controlSessionId: string,
+    token: string,
+    callback: (state: { status: string }) => void,
+  ): () => void;
+  ack(input: {
+    controlSessionId: string;
+    token: string;
+    commandId: string;
+    status: "acked" | "completed" | "failed";
+    errorMessage?: string;
+    resultSessionId?: string;
+  }): Promise<void>;
+  close(): void;
+}
+
+export interface RemoteStartConfig {
+  consentVersion: string;
+  /** Tiêu đề mặc định khi dashboard không gửi title. */
+  defaultTitle?: string;
+  visibility?: "public" | "private";
+  metadata?: Record<string, string>;
+}
+
+type AppStateListener = (state: "active" | "background" | "inactive") => void;
+
+export interface DeviceAgentOptions {
+  engine: LivestreamEngine;
+  bootstrapInput: BootstrapInput;
+  transport: DeviceAgentTransport;
+  remoteStart: RemoteStartConfig;
+  deviceInfo?: DeviceAgentDeviceInfo;
+  onRemoteSessionStarted?: (sessionId: string) => void;
+  deviceMetrics?: () => Promise<DeviceMetricsSample | null>;
+  /** Factory kênh điều khiển — test truyền fake; mặc định Convex websocket. */
+  createControlChannel?: (convexUrl: string) => DeviceControlChannel;
+  /** Test hook: nguồn app-state; mặc định react-native AppState. */
+  subscribeAppState?: (listener: AppStateListener) => () => void;
+}
+
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 12_000;
+const REGISTER_RETRY_BASE_MS = 2_000;
+const REGISTER_RETRY_MAX_MS = 60_000;
+/** Chỉ các field server chấp nhận (proxy từ chối key lạ trong metrics). */
+const METRIC_FIELDS = [
+  "ramFreeMb",
+  "ramTotalMb",
+  "storageFreeGb",
+  "batteryPct",
+  "batteryTempC",
+  "thermal",
+  "netType",
+  "linkMbps",
+  "rssi",
+  "connQuality",
+] as const;
+
+function defaultSubscribeAppState(listener: AppStateListener): () => void {
+  const { AppState } = require("react-native") as typeof import("react-native");
+  const subscription = AppState.addEventListener("change", (state) => {
+    listener(
+      state === "active" ? "active" : state === "background" ? "background" : "inactive",
+    );
+  });
+  return () => subscription.remove();
+}
+
+function defaultCreateControlChannel(convexUrl: string): DeviceControlChannel {
+  const { createConvexControlChannel } =
+    require("./convex-control-channel") as typeof import("./convex-control-channel");
+  return createConvexControlChannel(convexUrl);
+}
+
+function pickMetrics(
+  sample: DeviceMetricsSample | null,
+): Record<string, number | string> | undefined {
+  if (!sample) return undefined;
+  const metrics: Record<string, number | string> = {};
+  for (const field of METRIC_FIELDS) {
+    const value = (sample as Record<string, unknown>)[field];
+    if (typeof value === "number" && Number.isFinite(value)) metrics[field] = value;
+    else if (typeof value === "string" && value.trim() !== "") metrics[field] = value;
+  }
+  return Object.keys(metrics).length > 0 ? metrics : undefined;
+}
+
+export class DeviceAgent {
+  private readonly options: DeviceAgentOptions;
+  private running = false;
+  private registered = false;
+  private foreground = true;
+  private heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private beatInFlight = false;
+  private registerAttempt = 0;
+  private unsubscribeAppState: (() => void) | null = null;
+
+  private heartbeatFailures = 0;
+  private controlChannel: DeviceControlChannel | null = null;
+  private controlSessionId: string | null = null;
+  private controlUnsubscribers: Array<() => void> = [];
+  private executing = false;
+  private readonly handledCommandIds = new Set<string>();
+
+  constructor(options: DeviceAgentOptions) {
+    this.options = options;
+  }
+
+  start() {
+    if (this.running) return;
+    this.running = true;
+    this.unsubscribeAppState = (
+      this.options.subscribeAppState ?? defaultSubscribeAppState
+    )((state) => this.handleAppState(state));
+    this.schedule(0);
+  }
+
+  stop() {
+    this.running = false;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    this.unsubscribeAppState?.();
+    this.unsubscribeAppState = null;
+    this.closeControlChannel();
+  }
+
+  private handleAppState(state: "active" | "background" | "inactive") {
+    const wasForeground = this.foreground;
+    this.foreground = state === "active";
+    if (!this.running) return;
+    if (this.foreground && !wasForeground) {
+      // Về foreground: beat ngay để dashboard thấy online lại nhanh
+      this.schedule(0);
+    }
+    if (!this.foreground) {
+      if (this.timer) clearTimeout(this.timer);
+      this.timer = null;
+      // App nền không quay được — đóng kênh, server sẽ end control-session
+      this.closeControlChannel();
+    }
+  }
+
+  private schedule(delayMs: number) {
+    if (!this.running || !this.foreground) return;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => {
+      void this.beat();
+    }, delayMs);
+  }
+
+  private async beat() {
+    if (!this.running || !this.foreground || this.beatInFlight) return;
+    this.beatInFlight = true;
+    try {
+      if (!this.registered) {
+        await this.register();
+        if (!this.registered) return; // register() đã schedule retry
+      }
+      await this.heartbeat();
+      this.schedule(this.heartbeatIntervalMs);
+    } finally {
+      this.beatInFlight = false;
+    }
+  }
+
+  private async register() {
+    try {
+      const result = await this.options.transport.register({
+        ...this.options.bootstrapInput,
+        ...this.options.deviceInfo,
+      });
+      if (result.heartbeatIntervalMs > 0) {
+        this.heartbeatIntervalMs = result.heartbeatIntervalMs;
+      }
+      this.registered = true;
+      this.registerAttempt = 0;
+    } catch {
+      // Mạng lỗi/proxy chưa sẵn sàng — backoff rồi thử lại
+      const delay = Math.min(
+        REGISTER_RETRY_BASE_MS * 2 ** this.registerAttempt,
+        REGISTER_RETRY_MAX_MS,
+      );
+      this.registerAttempt += 1;
+      this.schedule(delay);
+    }
+  }
+
+  private async heartbeat() {
+    const snapshot = this.options.engine.getSnapshot();
+    let metrics: Record<string, number | string> | undefined;
+    try {
+      metrics = pickMetrics((await this.options.deviceMetrics?.()) ?? null);
+    } catch {
+      metrics = undefined;
+    }
+    let result: { controlSession: DeviceControlSessionGrant | null };
+    try {
+      result = await this.options.transport.heartbeat({
+        ...this.options.bootstrapInput,
+        agentState: snapshot.state,
+        currentSessionId: snapshot.sessionId,
+        ...(this.options.deviceInfo?.appVersion
+          ? { appVersion: this.options.deviceInfo.appVersion }
+          : {}),
+        ...(metrics ? { metrics } : {}),
+      });
+    } catch {
+      // Lỗi liên tiếp (mạng, hoặc server đã xoá device) → thử re-register.
+      // Register là upsert idempotent nên gọi lại vô hại.
+      this.heartbeatFailures += 1;
+      if (this.heartbeatFailures >= 3) {
+        this.registered = false;
+        this.heartbeatFailures = 0;
+      }
+      return;
+    }
+    this.heartbeatFailures = 0;
+    if (result.controlSession && !this.controlChannel) {
+      this.openControlChannel(result.controlSession);
+    }
+  }
+
+  private openControlChannel(grant: DeviceControlSessionGrant) {
+    let channel: DeviceControlChannel;
+    try {
+      channel = (this.options.createControlChannel ?? defaultCreateControlChannel)(
+        grant.convexUrl,
+      );
+    } catch {
+      return;
+    }
+    this.controlChannel = channel;
+    this.controlSessionId = grant.id;
+    void channel
+      .attach(grant.id, grant.token)
+      .then(() => {
+        if (this.controlChannel !== channel) return;
+        this.controlUnsubscribers.push(
+          channel.onCommands(grant.id, grant.token, (commands) => {
+            void this.executeCommands(channel, grant, commands);
+          }),
+          channel.onState(grant.id, grant.token, (state) => {
+            if (state.status === "ended" || state.status === "expired") {
+              this.closeControlChannel();
+            }
+          }),
+        );
+      })
+      .catch(() => {
+        if (this.controlChannel === channel) this.closeControlChannel();
+      });
+  }
+
+  private closeControlChannel() {
+    for (const unsubscribe of this.controlUnsubscribers) {
+      try {
+        unsubscribe();
+      } catch {
+        /* kênh đã đóng */
+      }
+    }
+    this.controlUnsubscribers = [];
+    try {
+      this.controlChannel?.close();
+    } catch {
+      /* kênh đã đóng */
+    }
+    this.controlChannel = null;
+    this.controlSessionId = null;
+    this.handledCommandIds.clear();
+  }
+
+  private async executeCommands(
+    channel: DeviceControlChannel,
+    grant: DeviceControlSessionGrant,
+    commands: DeviceCommand[],
+  ) {
+    for (const command of commands) {
+      if (this.controlChannel !== channel) return;
+      if (this.handledCommandIds.has(command.id)) continue;
+      this.handledCommandIds.add(command.id);
+      if (this.executing) {
+        // Single-flight: server cũng dedupe, nhưng phòng lệnh dồn trong 1 batch
+        await this.safeAck(channel, grant, command.id, "failed", "Thiết bị đang bận");
+        continue;
+      }
+      this.executing = true;
+      try {
+        await this.executeCommand(channel, grant, command);
+      } finally {
+        this.executing = false;
+      }
+    }
+  }
+
+  private async executeCommand(
+    channel: DeviceControlChannel,
+    grant: DeviceControlSessionGrant,
+    command: DeviceCommand,
+  ) {
+    if (command.expiresAt <= Date.now()) {
+      await this.safeAck(channel, grant, command.id, "failed", "Lệnh đã hết hạn");
+      return;
+    }
+    await this.safeAck(channel, grant, command.id, "acked");
+    try {
+      if (command.type === "start_livestream") {
+        await this.runStartLivestream(command);
+        const sessionId = this.options.engine.getSnapshot().sessionId;
+        await this.safeAck(
+          channel,
+          grant,
+          command.id,
+          "completed",
+          undefined,
+          sessionId ?? undefined,
+        );
+        if (sessionId) this.options.onRemoteSessionStarted?.(sessionId);
+      } else {
+        await this.runStopLivestream();
+        await this.safeAck(channel, grant, command.id, "completed");
+      }
+    } catch (error) {
+      await this.safeAck(
+        channel,
+        grant,
+        command.id,
+        "failed",
+        normalizeError(error).message,
+      );
+    }
+  }
+
+  private async runStartLivestream(command: DeviceCommand) {
+    const engine = this.options.engine;
+    const state = engine.getSnapshot().state;
+    if (state !== "idle" && state !== "ended" && state !== "preview") {
+      throw new Error(`Thiết bị không sẵn sàng (trạng thái ${state})`);
+    }
+    if (state !== "preview") {
+      await engine.prepare();
+    }
+    const remote = this.options.remoteStart;
+    await engine.start(
+      {
+        externalSessionId: `remote-${command.id}`,
+        title: command.payload.title?.trim() || remote.defaultTitle || "Livestream",
+        visibility: command.payload.visibility ?? remote.visibility ?? "public",
+        consentVersion: remote.consentVersion,
+        metadata: { ...remote.metadata, deviceCommandId: command.id },
+        standby: true,
+      },
+      { autoPublish: false },
+    );
+  }
+
+  private async runStopLivestream() {
+    const engine = this.options.engine;
+    if (engine.getSnapshot().sessionId) {
+      await engine.stop("user");
+    }
+  }
+
+  private async safeAck(
+    channel: DeviceControlChannel,
+    grant: DeviceControlSessionGrant,
+    commandId: string,
+    status: "acked" | "completed" | "failed",
+    errorMessage?: string,
+    resultSessionId?: string,
+  ) {
+    try {
+      await channel.ack({
+        controlSessionId: grant.id,
+        token: grant.token,
+        commandId,
+        status,
+        ...(errorMessage !== undefined ? { errorMessage } : {}),
+        ...(resultSessionId !== undefined ? { resultSessionId } : {}),
+      });
+    } catch {
+      /* mất kênh giữa chừng — server cron sẽ expire lệnh */
+    }
+  }
+}