@pickleball/expo-sdk 0.1.1 → 1.0.0

package/src/provider.tsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useRef, useSyncExternalStore, type ReactNode } from "react";
+import React, { useEffect, useMemo, 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";
@@ -10,9 +10,12 @@ import {
   type SdkNetwork,
   type SdkRuntime,
   type SdkStorage,
+  type SessionCommandChannel,
+  type SessionCommandSubscription,
   type TelemetrySink,
 } from "./engine";
 import {
+  createDefaultCommandChannel,
   createDefaultDeviceMetrics,
   createDefaultNetwork,
   createDefaultRoomFactory,
@@ -64,10 +67,33 @@ export interface PickleballLiveProviderProps {
   children?: ReactNode;
   sessionProvider: LivestreamSessionProvider;
   bootstrapInput: BootstrapInput;
+  /**
+   * Phiên phải SỐNG TIẾP khi app biến mất giữa chừng (sụp nguồn, bị vuốt tắt,
+   * component remount), để lần mở sau nhận lại đúng phiên cũ — giữ nguyên link
+   * xem và VOD liền một mạch.
+   *
+   * Mặc định false = hành vi cũ: mở app lại là dọn sạch phiên cũ. App gác sân bật
+   * cờ này khi máy đang được gán sân; máy không gán sân vẫn dọn như cũ để không
+   * để lại phiên treo trong các ca ngoài giải.
+   *
+   * Nhận boolean HOẶC hàm (được phép async). App nên truyền HÀM ĐỌC THẲNG ĐĨA:
+   * engine hỏi cờ này đúng lúc khởi động, thường TRƯỚC khi state React kịp
+   * restore — truyền boolean suy từ state là dính race keep=false oan (đã dính
+   * thật 18/08/2026, sinh phiên chờ thứ hai đè phiên live cũ).
+   */
+  keepSessionOnRestart?: boolean | (() => boolean | Promise<boolean>);
   runtime?: SdkRuntime;
   storage?: SdkStorage;
   network?: SdkNetwork;
   telemetry?: TelemetrySink;
+  /** Kênh poll lệnh cho mode device-rtmp — mặc định suy từ telemetry endpoint. */
+  commandChannel?: SessionCommandChannel;
+  /**
+   * Kênh nhận lệnh qua websocket (first-party nối thẳng Convex). Có thì lệnh về
+   * tức thì và poll tụt về nhịp reconcile chậm — cắt phần lớn function call của
+   * đường poll. Thiếu (máy đối tác qua proxy) thì chỉ dùng poll HTTP như cũ.
+   */
+  commandSubscription?: SessionCommandSubscription;
   roomFactory?: () => RoomAdapter;
   deviceMetrics?: EngineDependencies["deviceMetrics"];
   theme?: Partial<LivestreamTheme>;
@@ -75,6 +101,28 @@ export interface PickleballLiveProviderProps {
   onError?: (error: PickleballExpoError) => void;
 }
 
+/**
+ * Context nội bộ cho các module opt-in (VD PickleballDeviceAgent) cần truy cập
+ * engine trực tiếp — export qua "./advanced", không thuộc API tích hợp cơ bản.
+ */
+export interface LivestreamHostContextValue {
+  engine: LivestreamEngine;
+  bootstrapInput: BootstrapInput;
+  deviceMetrics: NonNullable<EngineDependencies["deviceMetrics"]>;
+}
+
+const LivestreamHostContext = React.createContext<LivestreamHostContextValue | null>(null);
+
+export function useLivestreamHost(): LivestreamHostContextValue {
+  const value = React.use(LivestreamHostContext);
+  if (!value) {
+    throw new ExpoSdkConfigurationError(
+      "useLivestreamHost must be used inside PickleballLiveProvider",
+    );
+  }
+  return value;
+}
+
 export interface LivestreamContextValue extends LivestreamSnapshot {
   locale: "vi" | "en";
   theme: LivestreamTheme;
@@ -99,8 +147,35 @@ const LivestreamContext = React.createContext<LivestreamContextValue | null>(nul
 
 export function PickleballLiveProvider(props: PickleballLiveProviderProps) {
   const engineRef = useRef<LivestreamEngine | null>(null);
+  const keepSessionRef = useRef(props.keepSessionOnRestart);
+  keepSessionRef.current = props.keepSessionOnRestart;
+  // dispose() phải quyết NGAY (sync) có giữ phiên hay không, còn prop dạng hàm
+  // thì async — resolve sẵn vào ref này. Khi prop là hàm mà chưa có kết quả,
+  // nghiêng về GIỮ: dọn oan là mất phiên vĩnh viễn (link đổi, VOD tách đôi),
+  // giữ oan thì lưới server (1 giờ live / 30 phút standby) dọn hộ.
+  const resolvedKeepRef = useRef(typeof props.keepSessionOnRestart === "function");
+  useEffect(() => {
+    const value = props.keepSessionOnRestart;
+    if (typeof value !== "function") {
+      resolvedKeepRef.current = value === true;
+      return;
+    }
+    resolvedKeepRef.current = true;
+    let cancelled = false;
+    void Promise.resolve()
+      .then(() => value())
+      .then((keep) => {
+        if (!cancelled) resolvedKeepRef.current = keep === true;
+      })
+      .catch(() => undefined);
+    return () => {
+      cancelled = true;
+    };
+  }, [props.keepSessionOnRestart]);
+  const hostRef = useRef<LivestreamHostContextValue | null>(null);
   const effectGenerationRef = useRef(0);
   if (!engineRef.current) {
+    const deviceMetrics = props.deviceMetrics ?? createDefaultDeviceMetrics();
     const dependencies: EngineDependencies = {
       sessionProvider: props.sessionProvider,
       bootstrapInput: props.bootstrapInput,
@@ -108,10 +183,26 @@ export function PickleballLiveProvider(props: PickleballLiveProviderProps) {
       storage: props.storage ?? createDefaultStorage(),
       network: props.network ?? createDefaultNetwork(),
       telemetry: props.telemetry ?? createDefaultTelemetry(),
-      deviceMetrics: props.deviceMetrics ?? createDefaultDeviceMetrics(),
+      commandChannel: props.commandChannel ?? createDefaultCommandChannel(),
+      ...(props.commandSubscription
+        ? { commandSubscription: props.commandSubscription }
+        : {}),
+      deviceMetrics,
       roomFactory: props.roomFactory ?? createDefaultRoomFactory(),
+      // Đọc qua ref để engine luôn thấy giá trị MỚI NHẤT: engine chỉ dựng một lần
+      // (engineRef), còn prop thì đổi theo việc máy được gán/gỡ sân. Prop dạng
+      // hàm được gọi xuyên qua (engine tự await) — đường cho app đọc thẳng đĩa.
+      keepSessionOnRestart: () => {
+        const value = keepSessionRef.current;
+        return typeof value === "function" ? value() : value === true;
+      },
     };
     engineRef.current = new LivestreamEngine(dependencies);
+    hostRef.current = {
+      engine: engineRef.current,
+      bootstrapInput: props.bootstrapInput,
+      deviceMetrics,
+    };
   }
   const engine = engineRef.current;
   const snapshot = useSyncExternalStore(
@@ -132,7 +223,7 @@ export function PickleballLiveProvider(props: PickleballLiveProviderProps) {
       subscription.remove();
       queueMicrotask(() => {
         if (effectGenerationRef.current === effectGeneration) {
-          void engine.dispose();
+          void engine.dispose({ keepSession: resolvedKeepRef.current });
         }
       });
     };
@@ -142,26 +233,42 @@ export function PickleballLiveProvider(props: PickleballLiveProviderProps) {
     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),
-  };
+  // Hành động ổn định theo engine (không dựng lại mỗi render): các effect phía
+  // trên (AutoResume, useStandbySession, app đối tác) đặt chúng vào dependency
+  // — dựng lại mỗi render là effect huỷ/chạy lại theo nhịp render, timer thử
+  // lại không bao giờ kịp nổ.
+  const actions = useMemo(
+    () => ({
+      prepare: () => engine.prepare(),
+      start: (input: StartLivestreamInput, options?: { autoPublish?: boolean }) =>
+        engine.start(input, options),
+      startPublishing: () => engine.startPublishing(),
+      stopPublishing: () => engine.stopPublishing(),
+      stop: (reason?: EndReason) => engine.stop(reason),
+      retry: () => engine.retry(),
+      switchCamera: () => engine.switchCamera(),
+      setMicrophoneEnabled: (enabled: boolean) => engine.setMicrophoneEnabled(enabled),
+      setCaptureOrientation: (orientation: "portrait" | "landscape") =>
+        engine.setCaptureOrientation(orientation),
+      selectCamera: (deviceId: string) => engine.selectCamera(deviceId),
+    }),
+    [engine],
+  );
+  const locale = props.locale ?? "vi";
+  const theme = useMemo(
+    () => ({ ...defaultLivestreamTheme, ...props.theme }),
+    [props.theme],
+  );
+  const value = useMemo<LivestreamContextValue>(
+    () => ({ ...snapshot, locale, theme, ...actions }),
+    [snapshot, locale, theme, actions],
+  );
   return (
-    <LivestreamContext.Provider value={value}>
-      {props.children}
-    </LivestreamContext.Provider>
+    <LivestreamHostContext.Provider value={hostRef.current}>
+      <LivestreamContext.Provider value={value}>
+        {props.children}
+      </LivestreamContext.Provider>
+    </LivestreamHostContext.Provider>
   );
 }
 

package/src/realtime/index.ts

@@ -0,0 +1,56 @@
+/**
+ * Kênh lệnh realtime qua websocket Convex cho app dùng camera grant.
+ *
+ * Grant có `convexUrl` (origin .convex.cloud) → truyền
+ * `commandSubscription={createGrantCommandSubscription(() => grant?.convexUrl)}`
+ * vào PickleballLiveProvider: lệnh start/stop/end về tức thì và poll HTTP tụt
+ * về nhịp đối chiếu 30s (thay vì 2s/4s — ~3.600 call/giờ/máy).
+ *
+ * Subpath riêng vì kéo theo `convex`; root entry giữ gọn. `./device-agent` vẫn
+ * re-export cùng hàm cho app fleet.
+ */
+import type { SdkTelemetryCredentials, SessionCommandRecord } from "../contracts";
+import {
+  createConvexCommandSubscription,
+  createConvexDeviceRealtime,
+  type ConvexDeviceRealtime,
+} from "../device-agent/convex-command-subscription";
+import type { SessionCommandSubscription } from "../engine";
+
+export { createConvexCommandSubscription, createConvexDeviceRealtime, type ConvexDeviceRealtime };
+
+/**
+ * Subscription cho app dùng camera grant: URL Convex nằm TRONG grant
+ * (`grant.convexUrl`) nên chỉ biết sau khi start — đọc URL lúc engine subscribe
+ * (ngay sau khi vào phiên), dựng MỘT client mỗi origin và tái dùng qua các
+ * phiên. Không có URL (deployment không lộ origin chuẩn) → không subscribe,
+ * engine giữ poll HTTP như cũ.
+ *
+ * Dùng với createCameraGrantProvider: `() => provider.getActiveGrant()?.convexUrl`.
+ */
+export function createGrantCommandSubscription(
+  getConvexUrl: () => string | null | undefined,
+): SessionCommandSubscription {
+  const clients = new Map<string, ConvexDeviceRealtime>();
+  return {
+    subscribe(
+      credentials: SdkTelemetryCredentials,
+      sessionId: string,
+      onCommands: (commands: SessionCommandRecord[]) => void,
+      onError?: (error: Error) => void,
+    ) {
+      const url = getConvexUrl();
+      if (!url) return () => undefined;
+      let realtime = clients.get(url);
+      if (!realtime) {
+        realtime = createConvexDeviceRealtime(url);
+        clients.set(url, realtime);
+      }
+      return realtime.commandSubscription.subscribe(credentials, sessionId, onCommands, onError);
+    },
+    dispose() {
+      for (const realtime of clients.values()) realtime.dispose();
+      clients.clear();
+    },
+  };
+}

package/src/resume-policy.ts

@@ -0,0 +1,85 @@
+/**
+ * Luật quyết định khi nối lại một phiên server còn giữ cho máy này.
+ *
+ * Chuyển từ apps/device-streamer (src/resume-policy.ts) vào SDK để app đối tác
+ * không phải học lại từng cái bẫy đã đo được trên fleet.
+ *
+ * Vì sao cần tách riêng: bản đầu coi MỌI thất bại là "phiên đã chết" và bỏ cuộc
+ * vĩnh viễn sau đúng một lần thử. Hệ quả: máy khởi động lại lúc wifi chưa kịp
+ * lên là mất luôn cơ hội nối lại — đúng ca hay gặp nhất, vì máy vừa mở nguồn
+ * thì wifi luôn lên chậm hơn app.
+ *
+ * Phân biệt hai loại thất bại là toàn bộ giá trị của module này:
+ * - "gone": server nói phiên không còn. Thử lại bao nhiêu cũng vô ích.
+ * - "retry": mạng chưa lên, server trục trặc, phản hồi méo. Phiên có thể vẫn sống.
+ *
+ * Nghi ngờ thì chọn "retry": đoán nhầm thành "gone" là mất phiên vĩnh viễn (link
+ * xem đổi, VOD tách đôi); đoán nhầm thành "retry" chỉ tốn vài request, và đã có
+ * lưới server dọn phiên mồ côi.
+ */
+
+/** Phân loại phản hồi HTTP của endpoint refresh. */
+export type ResumeVerdict = "ok" | "gone" | "retry";
+
+/**
+ * 404 = phiên biến mất hẳn. 409 = phiên đã kết thúc (mọi namespace trả
+ * SESSION_CONFLICT cho thao tác trên phiên ended, và grant bị thay cũng là 409).
+ * 410 = Gone theo chuẩn HTTP. Mọi mã khác — kể cả 401/403 — đều là "retry":
+ * token có thể được cấp lại ở nhịp sau, và một lỗi xác thực tạm thời không phải
+ * bằng chứng phiên đã chết.
+ */
+export function classifyResumeStatus(status: number): ResumeVerdict {
+  if (status === 404 || status === 409 || status === 410) return "gone";
+  if (status >= 200 && status < 300) return "ok";
+  return "retry";
+}
+
+/**
+ * Nhịp thử lại. Nhịp đầu 1 giây vì ca điển hình là "app mở trước khi wifi lên" —
+ * chờ vài giây là xong. Trần 15 giây để một máy chết hẳn không nện server mãi;
+ * số lần thì KHÔNG giới hạn: thà thử mãi còn hơn mất phiên, và lưới server
+ * (1 giờ cho live, 30 phút cho standby) mới là thứ quyết định lúc nào bỏ cuộc.
+ */
+export const RESUME_RETRY_DELAYS_MS = [1_000, 2_000, 4_000, 8_000, 15_000];
+
+export function resumeRetryDelayMs(attempt: number): number {
+  const index = Math.min(Math.max(attempt, 0), RESUME_RETRY_DELAYS_MS.length - 1);
+  return RESUME_RETRY_DELAYS_MS[index];
+}
+
+/**
+ * Bất kỳ ai định TẠO PHIÊN MỚI tự động (AutoTournament của fleet, useStandbySession
+ * của app đối tác) phải NHƯỜNG khi còn phiên chờ nhận lại — nhìn CẢ HAI nguồn.
+ *
+ * Bản đầu chỉ nhìn serverSession (heartbeat, về SAU vài giây); adoptableSessionId
+ * (dấu trên đĩa) có mặt ngay từ lúc engine khởi động xong. Khe hở vài giây đó là
+ * đủ để một lượt arm nổ súng trước AutoResume: hoặc đụng chốt marker (app đứng
+ * màn LỖI), hoặc tệ hơn — lách qua trong đúng cửa sổ race và tạo phiên chờ THỨ
+ * HAI đè phiên live cũ (đo thật đêm 18/08/2026).
+ */
+export function resumeBlocksArm(input: {
+  adoptableSessionId: string | null;
+  serverSessionId: string | null;
+  engineSessionId: string | null;
+}): boolean {
+  if (input.engineSessionId !== null) return false;
+  return input.adoptableSessionId !== null || input.serverSessionId !== null;
+}
+
+/** Quy ước externalSessionId của lượt start NHẬN LẠI — engine chỉ cho lượt này qua chốt marker. */
+export function resumeExternalSessionId(sessionId: string): string {
+  return `resume-${sessionId}`;
+}
+
+/**
+ * Grant nối lại chỉ được tiêu thụ cho ĐÚNG phiên nó được cấp. AutoResume có thể
+ * bắn nhiều lượt (retry, đổi nguồn); không kiểm khớp thì một grant cũ còn sót có
+ * thể bị lượt start của phiên khác nuốt — engine nối vào nhầm phiên, đúng loại lỗi
+ * âm thầm khó truy nhất.
+ */
+export function resumeGrantMatches(
+  externalSessionId: string | undefined,
+  grantSessionId: string,
+): boolean {
+  return externalSessionId === resumeExternalSessionId(grantSessionId);
+}

package/src/resume.ts

@@ -0,0 +1,132 @@
+import type {
+  LivestreamSessionProvider,
+  SdkSessionGrant,
+  StartLivestreamInput,
+} from "./contracts";
+import { isSdkRemoteConfig } from "./contracts";
+import { classifyResumeStatus, resumeGrantMatches } from "./resume-policy";
+import { isFiniteNumber, isRecord, isTelemetryCredentials, type Fetch } from "./session-grant";
+
+/**
+ * Nhận lại phiên sau khi app bị kill/mở lại — phần PROVIDER.
+ *
+ * Kịch bản: máy đang phát, app biến mất (sụp nguồn, OEM giết, vuốt tắt). Server
+ * còn giữ phiên. Lần mở sau engine thấy dấu trên đĩa (adoptableSessionId) nhưng
+ * KHÔNG có grant trong bộ nhớ — phải hỏi server cấp lại credentials của đúng
+ * phiên đó rồi start bằng grant ấy thay vì tạo phiên mới. Link xem và VOD nhờ
+ * vậy liền một mạch.
+ */
+
+export type ResumeAttempt =
+  | { kind: "grant"; grant: SdkSessionGrant; live: boolean }
+  | { kind: "gone" }
+  | { kind: "retry" };
+
+export interface ResumableSessionProvider extends LivestreamSessionProvider {
+  /** Đặt grant cho lượt start kế tiếp có externalSessionId `resume-<id>`. */
+  adoptResumeGrant(grant: SdkSessionGrant): void;
+  /** Hỏi server cấp lại grant cho phiên còn sống. */
+  resume(sessionId: string): Promise<ResumeAttempt>;
+}
+
+/**
+ * Bọc provider: `start()` ưu tiên grant nhận lại nếu khớp phiên, còn lại tạo phiên
+ * mới như thường. Grant chờ nằm trong closure (không biến module) nên hai provider
+ * trong cùng app không dẫm nhau.
+ */
+export function withResume(
+  provider: LivestreamSessionProvider,
+  resume: (sessionId: string) => Promise<ResumeAttempt>,
+): ResumableSessionProvider {
+  let pending: SdkSessionGrant | null = null;
+  return {
+    bootstrap: provider.bootstrap.bind(provider),
+    refresh: provider.refresh.bind(provider),
+    end: provider.end.bind(provider),
+    publish: provider.publish?.bind(provider),
+    unpublish: provider.unpublish?.bind(provider),
+    async start(input: StartLivestreamInput) {
+      const grant = pending;
+      if (grant && resumeGrantMatches(input.externalSessionId, grant.sessionId)) {
+        pending = null;
+        return grant;
+      }
+      return provider.start(input);
+    },
+    adoptResumeGrant(grant) {
+      pending = grant;
+    },
+    resume,
+  };
+}
+
+/** Biến phản hồi refresh (đầy đủ) thành grant; méo → null để caller coi là retry. */
+export function grantFromRefreshPayload(data: unknown): SdkSessionGrant | null {
+  if (
+    !isRecord(data) ||
+    typeof data.sessionId !== "string" ||
+    typeof data.serverUrl !== "string" ||
+    typeof data.participantToken !== "string" ||
+    !isFiniteNumber(data.tokenExpiresAt) ||
+    !isTelemetryCredentials(data.telemetry) ||
+    !isSdkRemoteConfig(data.config)
+  ) {
+    return null;
+  }
+  return {
+    sessionId: data.sessionId,
+    serverUrl: data.serverUrl,
+    participantToken: data.participantToken,
+    playbackUrl: typeof data.playbackUrl === "string" ? data.playbackUrl : null,
+    tokenExpiresAt: data.tokenExpiresAt,
+    telemetry: data.telemetry,
+    config: data.config,
+  };
+}
+
+export interface HttpResumeFetcherOptions {
+  /** URL endpoint refresh của phiên — namespace nào cũng được, miễn trả grant đầy đủ + status. */
+  url(sessionId: string): string;
+  headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+  fetch?: Fetch;
+  timeoutMs?: number;
+}
+
+/**
+ * Gọi endpoint refresh để dựng lại grant. Trả về PHÂN LOẠI chứ không phải
+ * null-cho-mọi-thứ (xem resume-policy): mất mạng/5xx/méo = retry, 404/409/410 =
+ * gone. Chỉ phát tiếp khi server xác nhận phiên ĐANG live — thiếu trường status
+ * coi như không phát: để camera tự lên sóng nhầm còn tệ hơn là chờ một lệnh nữa.
+ */
+export function createHttpResumeFetcher(
+  options: HttpResumeFetcherOptions,
+): (sessionId: string) => Promise<ResumeAttempt> {
+  const fetchImplementation = options.fetch ?? globalThis.fetch;
+  const timeoutMs = options.timeoutMs ?? 10_000;
+  return async (sessionId) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const headers =
+        typeof options.headers === "function" ? await options.headers() : (options.headers ?? {});
+      const response = await fetchImplementation(options.url(sessionId), {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...headers },
+        body: JSON.stringify({}),
+        signal: controller.signal,
+      });
+      const verdict = classifyResumeStatus(response.status);
+      if (verdict !== "ok") return { kind: verdict };
+      const envelope = (await response.json().catch(() => null)) as { data?: unknown } | null;
+      const grant = grantFromRefreshPayload(envelope?.data);
+      if (!grant) return { kind: "retry" };
+      const status = (envelope?.data as { status?: unknown }).status;
+      return { kind: "grant", grant, live: status === "live" };
+    } catch {
+      // fetch ném = mất mạng. Đây CHÍNH LÀ ca hay gặp nhất khi máy vừa mở nguồn.
+      return { kind: "retry" };
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}