@pickleball/expo-sdk 0.2.0 → 1.0.0

package/src/http-session-provider.ts

@@ -2,23 +2,20 @@ import type {
   BootstrapInput,
   EndLivestreamInput,
   LivestreamSessionProvider,
-  SdkBootstrap,
-  SdkSessionGrant,
-  SdkSessionRefresh,
-  SdkTelemetryCredentials,
   StartLivestreamInput,
 } from "./contracts";
-import { isSdkRemoteConfig } from "./contracts";
+import { InvalidResponseError } from "./errors";
 import {
-  ExpoSdkConfigurationError,
-  ExpoSdkTimeoutError,
-  InvalidResponseError,
-  NetworkUnavailableError,
-  PickleballExpoError,
-  errorFromCode,
-} from "./errors";
+  createJsonPoster,
+  isBootstrap,
+  isSessionGrant,
+  isSessionRefresh,
+  isSessionStatus,
+  joinUrl,
+  normalizeBaseUrl,
+  type Fetch,
+} from "./session-grant";
 
-type Fetch = typeof globalThis.fetch;
 type HeadersInput = Record<string, string>;
 
 export interface HttpSessionProviderPaths {
@@ -31,7 +28,11 @@ export interface HttpSessionProviderPaths {
 }
 
 export interface HttpSessionProviderOptions {
-  /** Base URL of the partner-owned mobile proxy. Never the Pickleball API URL. */
+  /**
+   * Base URL của proxy do đối tác host (mô hình cũ) hoặc namespace first-party
+   * `/api/v2/device-app` (app fleet). Không bao giờ là URL PickLive kèm API key.
+   * App đối tác dùng camera grant thì dùng createCameraGrantProvider thay vì đây.
+   */
   baseUrl: string;
   fetch?: Fetch;
   headers?: HeadersInput | (() => HeadersInput | Promise<HeadersInput>);
@@ -53,48 +54,15 @@ export function createHttpSessionProvider(
   options: HttpSessionProviderOptions,
 ): LivestreamSessionProvider {
   const baseUrl = normalizeBaseUrl(options.baseUrl);
-  const fetchImplementation = options.fetch ?? globalThis.fetch;
-  if (typeof fetchImplementation !== "function") {
-    throw new ExpoSdkConfigurationError("A Fetch API implementation is required");
-  }
+  const postJson = createJsonPoster({ fetch: options.fetch, timeoutMs: options.timeoutMs });
   const paths = { ...defaultPaths, ...options.paths };
 
   async function post(path: string, body: unknown): Promise<unknown> {
-    const controller = new AbortController();
-    const timeout = setTimeout(
-      () => controller.abort(),
-      options.timeoutMs ?? 10_000,
-    );
-    try {
-      const extraHeaders =
-        typeof options.headers === "function"
-          ? await options.headers()
-          : (options.headers ?? {});
-      const response = await fetchImplementation(joinUrl(baseUrl, path), {
-        method: "POST",
-        headers: { "Content-Type": "application/json", ...extraHeaders },
-        body: JSON.stringify(body),
-        signal: controller.signal,
-        redirect: "error",
-      });
-      const envelope = await response.json().catch(() => {
-        throw new InvalidResponseError();
-      });
-      if (!response.ok) throw parseProxyError(envelope, response.status);
-      if (!isRecord(envelope) || !("data" in envelope)) {
-        throw new InvalidResponseError();
-      }
-      return envelope.data;
-    } catch (error) {
-      if (controller.signal.aborted) throw new ExpoSdkTimeoutError();
-      if (error instanceof PickleballExpoError) throw error;
-      if (error instanceof TypeError) {
-        throw new NetworkUnavailableError(undefined, { cause: error });
-      }
-      throw error;
-    } finally {
-      clearTimeout(timeout);
-    }
+    const extraHeaders =
+      typeof options.headers === "function"
+        ? await options.headers()
+        : (options.headers ?? {});
+    return postJson(joinUrl(baseUrl, path), body, extraHeaders);
   }
 
   return {
@@ -127,139 +95,3 @@ export function createHttpSessionProvider(
     },
   };
 }
-
-declare const __DEV__: boolean | undefined;
-
-// RFC 1918 private ranges: 10/8, 172.16/12, 192.168/16.
-const PRIVATE_LAN_HOST =
-  /^(?:10\.\d{1,3}\.\d{1,3}\.\d{1,3}|172\.(?:1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3})$/;
-
-function normalizeBaseUrl(value: string) {
-  try {
-    const url = new URL(value);
-    const loopbackHosts = new Set(["localhost", "127.0.0.1", "[::1]"]);
-    const secure = url.protocol === "https:";
-    const localDevelopment =
-      url.protocol === "http:" && loopbackHosts.has(url.hostname);
-    // Dev bundle only (Metro/dev client): a device on the same network must
-    // reach the dev proxy over plain HTTP at a private LAN address. Release
-    // bundles compile __DEV__ to false, so production keeps the HTTPS rule.
-    const devPrivateLan =
-      typeof __DEV__ !== "undefined" &&
-      __DEV__ === true &&
-      url.protocol === "http:" &&
-      PRIVATE_LAN_HOST.test(url.hostname);
-    if (
-      (!secure && !localDevelopment && !devPrivateLan) ||
-      url.username ||
-      url.password
-    ) {
-      throw new Error();
-    }
-    return value.replace(/\/+$/, "");
-  } catch {
-    throw new ExpoSdkConfigurationError(
-      "baseUrl must use HTTPS (HTTP is allowed only for localhost loopback)",
-    );
-  }
-}
-
-function joinUrl(base: string, path: string) {
-  return `${base}/${path.replace(/^\/+/, "")}`;
-}
-
-function parseProxyError(envelope: unknown, httpStatus: number) {
-  const error =
-    isRecord(envelope) &&
-    isRecord(envelope.error) &&
-    typeof envelope.error.code === "string"
-      ? errorFromCode(
-          envelope.error.code,
-          typeof envelope.error.message === "string"
-            ? envelope.error.message
-            : undefined,
-        )
-      : new InvalidResponseError();
-  // Mã lỗi trong envelope không phân biệt được "phiên đã biến mất" (404) với
-  // "server đang trục trặc" (5xx) — cả hai đều là UNKNOWN. Giữ lại mã HTTP để
-  // engine quyết được: 404 thì xoá dấu pending-end, 5xx thì giữ và thử lại.
-  return Object.assign(error, { httpStatus });
-}
-
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function isFiniteNumber(value: unknown): value is number {
-  return typeof value === "number" && Number.isFinite(value);
-}
-
-function isBootstrap(value: unknown): value is SdkBootstrap {
-  return (
-    isRecord(value) &&
-    isSdkRemoteConfig(value.config) &&
-    isFiniteNumber(value.serverTime) &&
-    typeof value.rolloutEnabled === "boolean" &&
-    (value.message === undefined || typeof value.message === "string")
-  );
-}
-
-function isTelemetry(value: unknown): value is SdkTelemetryCredentials {
-  return (
-    isRecord(value) &&
-    typeof value.endpoint === "string" &&
-    /^https:\/\//.test(value.endpoint) &&
-    typeof value.token === "string" &&
-    value.token.length > 0 &&
-    isFiniteNumber(value.expiresAt)
-  );
-}
-
-function isSessionGrant(value: unknown): value is SdkSessionGrant {
-  return (
-    isRecord(value) &&
-    typeof value.sessionId === "string" &&
-    value.sessionId.length > 0 &&
-    typeof value.serverUrl === "string" &&
-    // wss:// cho mode LiveKit, rtmp(s):// cho mode device-rtmp. Trước đây chỉ
-    // chấp nhận wss:// nên grant RTMP bị coi là "phản hồi máy chủ không hợp lệ".
-    // Vẫn chặn ws:// trần để không rơi xuống WebSocket không mã hoá.
-    /^(wss|rtmps?):\/\//.test(value.serverUrl) &&
-    typeof value.participantToken === "string" &&
-    value.participantToken.length > 0 &&
-    (value.playbackUrl === null || typeof value.playbackUrl === "string") &&
-    isFiniteNumber(value.tokenExpiresAt) &&
-    isTelemetry(value.telemetry) &&
-    isSdkRemoteConfig(value.config)
-  );
-}
-
-function isSessionStatus(
-  value: unknown,
-): value is { sessionId: string; status: string } {
-  return (
-    isRecord(value) &&
-    typeof value.sessionId === "string" &&
-    value.sessionId.length > 0 &&
-    typeof value.status === "string" &&
-    value.status.length > 0
-  );
-}
-
-function isSessionRefresh(value: unknown): value is SdkSessionRefresh {
-  if (!isRecord(value) || !isSdkRemoteConfig(value.config)) return false;
-  if (
-    value.participantToken !== undefined &&
-    (typeof value.participantToken !== "string" || !value.participantToken)
-  ) {
-    return false;
-  }
-  if (
-    value.tokenExpiresAt !== undefined &&
-    !isFiniteNumber(value.tokenExpiresAt)
-  ) {
-    return false;
-  }
-  return value.telemetry === undefined || isTelemetry(value.telemetry);
-}

package/src/index.ts

@@ -1,9 +1,12 @@
 /**
- * Entry gọn cho tích hợp livestream cơ bản. Các tính năng khác nằm ở subpath:
+ * Entry gọn cho tích hợp livestream cơ bản (SDK 1.0: RTMP-only, camera grant).
+ * Các tính năng khác nằm ở subpath:
+ *   @pickleball/expo-sdk/ui            — màn hình camera + sheet cấu hình dựng sẵn
+ *   @pickleball/expo-sdk/realtime      — nhận lệnh qua websocket Convex (kéo `convex`)
  *   @pickleball/expo-sdk/match         — scoreboard + persistence
  *   @pickleball/expo-sdk/match/voice   — đọc điểm bằng loa
  *   @pickleball/expo-sdk/match/remote  — remote BLE/HID
- *   @pickleball/expo-sdk/device-agent  — điều khiển từ dashboard
+ *   @pickleball/expo-sdk/device-agent  — điều khiển từ dashboard (app fleet)
  *   @pickleball/expo-sdk/advanced      — engine internals, DI, mock/test
  * Metro không tree-shake nên chỉ import subpath nào app thật sự dùng.
  */
@@ -17,14 +20,88 @@ export {
   type LivestreamContextValue,
   type LivestreamTheme,
 } from "./provider";
-export { LivestreamScreen, type LivestreamScreenProps } from "./livestream-screen";
 export {
   createHttpSessionProvider,
   type HttpSessionProviderOptions,
   type HttpSessionProviderPaths,
 } from "./http-session-provider";
-// Partner dùng để persist token/cấu hình (expo-sqlite localStorage)
-export { createDefaultStorage } from "./native-runtime";
+// Điện thoại đối tác — camera grant từ backend đối tác (ADR-0002)
+export {
+  CAMERA_GRANT_STORAGE_KEY,
+  DEFAULT_LOCAL_CONFIG,
+  createCameraGrantProvider,
+  useCameraGrant,
+  type CameraGrantHandle,
+  type CameraGrantPhase,
+  type CameraGrantProvider,
+  type CameraGrantProviderOptions,
+} from "./camera-grant-provider";
+// Nhận lại phiên sau khi app bị kill
+export {
+  createHttpResumeFetcher,
+  grantFromRefreshPayload,
+  withResume,
+  type HttpResumeFetcherOptions,
+  type ResumableSessionProvider,
+  type ResumeAttempt,
+} from "./resume";
+export {
+  RESUME_RETRY_DELAYS_MS,
+  classifyResumeStatus,
+  resumeBlocksArm,
+  resumeExternalSessionId,
+  resumeGrantMatches,
+  resumeRetryDelayMs,
+  type ResumeVerdict,
+} from "./resume-policy";
+export {
+  PickleballAutoPrepare,
+  PickleballAutoResume,
+  useStandbySession,
+  type PickleballAutoPrepareProps,
+  type PickleballAutoResumeProps,
+  type ResumeAttemptOutcome,
+  type UseStandbySessionOptions,
+} from "./auto-resume";
+export { withLocalVideoQuality } from "./local-video-quality";
+// Cấu hình camera local + điều khiển runtime + đo mạng
+export {
+  CAMERA_SETTINGS_STORAGE_KEY,
+  DEFAULT_CAMERA_SETTINGS,
+  cameraSettingsKey,
+  createCameraSettingsStore,
+  parseCameraSettings,
+  rtmpRoomFactoryFor,
+  useCameraSettings,
+  type AntiFlickerMode,
+  type CameraSettings,
+  type CameraSettingsStore,
+  type CameraSettingsStoreOptions,
+} from "./camera-settings";
+export {
+  applyAntiFlicker,
+  getCameraCapabilities,
+  requestNativePermissions,
+  setExposureBias,
+  setExposureLocked,
+  setFocusLocked,
+  setTorch,
+  setZoom,
+  type CameraCapabilities,
+  type CameraCapabilityRange,
+} from "./camera-controls";
+export {
+  AUDIO_BITRATE_BPS,
+  DEFAULT_UPLOAD_URL,
+  VIDEO_BITRATE_BPS,
+  requiredMbpsFor,
+  runUplinkCheck,
+  verdictFor,
+  type UplinkCheckOptions,
+  type UplinkCheckResult,
+} from "./uplink-check";
+// Runtime RTMP-only + roomFactory RTMP (mode mặc định cho app camera)
+export { createDefaultStorage, createRtmpRoomFactory, createRtmpRuntime } from "./native-runtime";
 // Type-only: xuất hiện trong LivestreamContextValue/ProviderProps
 export type {
   CameraDeviceInfo,
@@ -35,6 +112,8 @@ export type {
   SdkNetwork,
   SdkRuntime,
   SdkStorage,
+  SessionCommandChannel,
+  SessionCommandSubscription,
   TelemetrySink,
 } from "./engine";
 export { PICKLEBALL_EXPO_SDK_VERSION } from "./version";

package/src/local-video-quality.ts

@@ -0,0 +1,43 @@
+import type { LivestreamSessionProvider } from "./contracts";
+
+/**
+ * Độ phân giải là lựa chọn LOCAL của máy — override `videoQuality` mà server trả
+ * trong bootstrap/start/refresh (engine truyền config.videoQuality vào
+ * room.preparePreview nên không cần sửa engine).
+ *
+ * Lúc TẠO phiên phải khai ngược lên server (`quality` trong StartLivestreamInput),
+ * nếu không bản ghi phiên nói dối: mặc định local 720 còn server 1080 — dashboard
+ * báo 1080 trong khi máy phát 720 suốt (18/08/2026). Chốt MỘT lần lúc start:
+ * gọi `resolution()` hai lần có thể ra hai giá trị khác nhau, khai một đằng dùng
+ * một nẻo thì tệ hơn là không khai.
+ */
+export function withLocalVideoQuality<P extends LivestreamSessionProvider>(
+  provider: P,
+  resolution: () => 720 | 1080,
+): P {
+  // Spread giữ nguyên MỌI method khác của provider (resume/adoptResumeGrant của
+  // ResumableSessionProvider, getActiveGrant/subscribe của CameraGrantProvider)
+  // — bọc mà rơi mất chúng là đường nhận lại phiên gãy im lặng ở tầng type.
+  // Provider là object thuần (closure) nên spread đủ; class có method prototype
+  // thì không hỗ trợ.
+  return {
+    ...provider,
+    async bootstrap(input) {
+      const result = await provider.bootstrap(input);
+      return { ...result, config: { ...result.config, videoQuality: resolution() } };
+    },
+    async start(input) {
+      const quality = resolution();
+      const result = await provider.start({ ...input, quality });
+      return { ...result, config: { ...result.config, videoQuality: quality } };
+    },
+    async refresh(sessionId) {
+      const result = await provider.refresh(sessionId);
+      return { ...result, config: { ...result.config, videoQuality: resolution() } };
+    },
+    end: (input) => provider.end(input),
+    // publish/unpublish là optional trong contract — forward nguyên trạng.
+    publish: provider.publish ? (sessionId) => provider.publish!(sessionId) : undefined,
+    unpublish: provider.unpublish ? (sessionId) => provider.unpublish!(sessionId) : undefined,
+  } as P;
+}