@pickleball/expo-sdk 0.1.1 → 1.0.0

package/src/errors.ts

@@ -126,3 +126,19 @@ export function normalizeError(error: unknown): PickleballExpoError {
   }
   return new UnknownSdkError();
 }
+
+/**
+ * Phiên đã biến mất hẳn phía server (HTTP 404): bị watchdog dọn, thuộc
+ * deployment khác, hoặc ID không hợp lệ. Khác hẳn lỗi mạng/5xx — thử lại không
+ * bao giờ cứu được, nên caller phải bỏ dấu khôi phục thay vì chặn vĩnh viễn.
+ *
+ * Mã HTTP được gắn vào lỗi ở http-session-provider vì envelope trả về chỉ có
+ * code "UNKNOWN", không phân biệt được 404 với 5xx.
+ */
+export function isSessionGoneError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { httpStatus?: unknown }).httpStatus === 404
+  );
+}

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);
-      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,133 +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) {
-  if (
-    isRecord(envelope) &&
-    isRecord(envelope.error) &&
-    typeof envelope.error.code === "string"
-  ) {
-    return errorFromCode(
-      envelope.error.code,
-      typeof envelope.error.message === "string"
-        ? envelope.error.message
-        : undefined,
-    );
-  }
-  return new InvalidResponseError();
-}
-
-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:\/\//.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,16 +1,119 @@
+/**
+ * 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 (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.
+ */
 export * from "./contracts";
-export * from "./match/contracts";
-export * from "./match/engine";
-export { replayMatchEvents, undoLastMatchEvent } from "./match/replay";
-export * from "./match/persistence";
-export * from "./match/provider";
-export * from "./match/remote";
-export * from "./match/voice";
 export * from "./errors";
-export * from "./engine";
-export * from "./http-session-provider";
-export * from "./livekit-room-adapter";
-export * from "./native-runtime";
-export * from "./provider";
-export * from "./livestream-screen";
-export * from "./version";
+export {
+  PickleballLiveProvider,
+  useLivestream,
+  defaultLivestreamTheme,
+  type PickleballLiveProviderProps,
+  type LivestreamContextValue,
+  type LivestreamTheme,
+} from "./provider";
+export {
+  createHttpSessionProvider,
+  type HttpSessionProviderOptions,
+  type HttpSessionProviderPaths,
+} from "./http-session-provider";
+// Đ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,
+  CaptureOrientation,
+  DeviceMetricsSample,
+  LivestreamSnapshot,
+  RoomAdapter,
+  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;
+}

package/src/match/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Entry cho tính năng trận đấu: scoreboard engine, persistence SQLite và
+ * PickleballMatchProvider. Voice/remote có subpath riêng
+ * (@pickleball/expo-sdk/match/voice, /match/remote) — ở đây chỉ re-export
+ * type-only các kiểu xuất hiện trong props của provider.
+ */
+export * from "./contracts";
+export * from "./engine";
+export { replayMatchEvents, undoLastMatchEvent } from "./replay";
+export * from "./persistence";
+export * from "./provider";
+export type {
+  MatchVoiceService,
+  VoiceAudioMode,
+  VoiceRouteState,
+  VoiceTtsOptions,
+} from "./voice/types";
+export type {
+  RemoteActionMapping,
+  RemoteBinding,
+  RemoteHidGestureMapping,
+  RemoteHidVolumeEvent,
+  RemoteInputMode,
+  RemoteMappedAction,
+  RemoteNativeState,
+  RemoteScanAdvertisement,
+  RemoteService,
+  RemoteState,
+} from "./remote/types";

package/src/match/provider.tsx

@@ -523,7 +523,9 @@ export function PickleballMatchProvider({
         ? awardRallyToSide("right", "remote")
         : mapped === "undo"
           ? undo("remote")
-          : null;
+          : mapped === "announce"
+            ? replayAnnouncement()
+            : null;
     if (action) void action.catch(() => undefined);
   };
 
@@ -536,7 +538,7 @@ export function PickleballMatchProvider({
       hidGestureRecognizerRef.current ??= new HidVolumeGestureRecognizer({
         ...hidGestureMapping,
         onGesture: (gesture) => {
-          handleRemoteMappedActionRef.current(hidGestureMapping[gesture]);
+          handleRemoteMappedActionRef.current(hidGestureMapping[gesture] ?? "none");
         },
       });
       hidGestureRecognizerRef.current.push(event);

package/src/match/remote/hid-gesture.ts

@@ -16,7 +16,7 @@ export class HidVolumeGestureRecognizer {
   constructor(private readonly options: HidVolumeGestureRecognizerOptions) {}
 
   push(event: RemoteHidVolumeEvent) {
-    if (event.direction !== this.options.direction) return;
+    if (this.options.direction !== "any" && event.direction !== this.options.direction) return;
     if (
       this.lastTimestamp !== null &&
       event.timestamp - this.lastTimestamp > this.options.settleMs
@@ -43,7 +43,15 @@ export class HidVolumeGestureRecognizer {
   private finishBurst() {
     this.clearTimer();
     if (!this.resolved && this.count > 0) {
-      this.options.onGesture(this.count === 1 ? "single" : "double");
+      this.options.onGesture(
+        this.count === 1
+          ? "single"
+          : this.count === 2
+            ? "double"
+            : this.count === 3
+              ? "triple"
+              : "quadruple",
+      );
     }
     this.reset();
   }

package/src/match/remote/types.ts

@@ -2,7 +2,7 @@ export const BTHOME_SERVICE_UUID = "FCD2" as const;
 
 export type RemoteButtonAction = "single" | "double" | "long";
 export type RemoteInputMode = "bthome" | "hidVolume" | "both";
-export type RemoteMappedAction = "left" | "right" | "undo" | "none";
+export type RemoteMappedAction = "left" | "right" | "undo" | "announce" | "none";
 export interface RemoteActionMapping {
   readonly volumeUp: RemoteMappedAction;
   readonly volumeDown: RemoteMappedAction;
@@ -19,17 +19,19 @@ export interface RemoteHidVolumeEvent {
   readonly timestamp: number;
 }
 
-export type RemoteHidGesture = "single" | "double" | "hold";
+export type RemoteHidGesture = "single" | "double" | "triple" | "quadruple" | "hold";
 
 export interface RemoteHidGestureMapping {
-  /** Raw HID direction emitted by the calibrated remote button. */
-  readonly direction: RemoteHidVolumeEvent["direction"];
+  /** Raw HID direction emitted by the calibrated remote button, or "any" for single-button remotes that alternate directions. */
+  readonly direction: RemoteHidVolumeEvent["direction"] | "any";
   /** Quiet window used to close one physical gesture burst. */
   readonly settleMs: number;
   /** Repeated volume changes required to classify a hold before the burst ends. */
   readonly holdEventCount: number;
   readonly single: RemoteMappedAction;
   readonly double: RemoteMappedAction;
+  readonly triple?: RemoteMappedAction;
+  readonly quadruple?: RemoteMappedAction;
   readonly hold: RemoteMappedAction;
 }
 

package/src/match/voice/scheduler.ts

@@ -75,6 +75,7 @@ export class LatestAnnouncementScheduler {
     ]);
     if (generation !== this.generation) return;
 
+    let neuralFailure: unknown = null;
     try {
       const avail = await this.options.engine.availability();
       if (avail === "available") {
@@ -89,17 +90,21 @@ export class LatestAnnouncementScheduler {
       }
     } catch (error) {
       if (controller.signal.aborted || generation !== this.generation) return;
-      this.report(error);
+      // Đọc bằng WAV offline vẫn chạy được — chỉ báo lỗi TTS khi fallback cũng hỏng.
+      neuralFailure = error;
     }
 
+    let fallbackPlayed = false;
     for (const source of planBundledFallback(plan)) {
       if (generation !== this.generation || controller.signal.aborted) return;
       try {
         await this.options.audio.play(source);
+        fallbackPlayed = true;
       } catch (error) {
         this.report(error);
       }
     }
+    if (neuralFailure && !fallbackPlayed) this.report(neuralFailure);
   }
 
   async replayLast(): Promise<void> {

package/src/match/voice/service.ts

@@ -56,11 +56,13 @@ export function createDefaultMatchVoiceService(
     (options.tts
       ? createGeminiVoiceEngine({ ...options.tts, generatedRoot: generatedDirectory() })
       : createUnavailableVoiceEngine());
+  let errorEpoch = 0;
   const scheduler = new LatestAnnouncementScheduler({
     engine,
     audio,
     onError(error) {
       lastError = error;
+      errorEpoch += 1;
       enqueueNotify();
     },
   });
@@ -118,10 +120,20 @@ export function createDefaultMatchVoiceService(
     subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
     announce(previous, current, event) {
       if (!stillActive()) return;
-      void scheduler.enqueue(buildVietnameseAnnouncement(previous, current, event)).catch((error) => {
-        lastError = error instanceof Error ? error : new Error("Announcement failed");
-        notify();
-      });
+      const epochBefore = errorEpoch;
+      void scheduler.enqueue(buildVietnameseAnnouncement(previous, current, event)).then(
+        () => {
+          // Lần đọc trọn vẹn (không lỗi mới nào bị báo) xoá lỗi voice cũ khỏi UI thay vì hiển thị mãi.
+          if (lastError && errorEpoch === epochBefore && stillActive()) {
+            lastError = null;
+            notify();
+          }
+        },
+        (error) => {
+          lastError = error instanceof Error ? error : new Error("Announcement failed");
+          notify();
+        },
+      );
     },
     replayAnnouncement: () => stillActive() ? scheduler.replayLast() : Promise.resolve(),
     testSpeaker: () => stillActive() ? scheduler.testSpeaker() : Promise.resolve(),