@pickleball/expo-sdk 0.2.0 → 1.0.0

package/dist/{engine-CCSSqPbZ.d.cts → engine-BSvSdCSE.d.cts}

@@ -2,9 +2,22 @@ type LivestreamState = "idle" | "preparing" | "preview" | "connecting"
 /** Đã vào phòng, chưa phát — chờ lệnh phát từ app hoặc dashboard. */
  | "standby" | "live" | "reconnecting" | "ending" | "ended" | "error";
 type SdkErrorCode = "PERMISSION_DENIED" | "NETWORK_UNAVAILABLE" | "TOKEN_EXPIRED" | "SDK_UPGRADE_REQUIRED" | "SESSION_CONFLICT" | "RECORDING_FAILED" | "CONSENT_REQUIRED" | "SDK_DISABLED" | "UNKNOWN";
+/**
+ * Vì sao 409 SESSION_CONFLICT bị nhận — ba ca cần app hành xử KHÁC NHAU mà
+ * trước đây chỉ phân biệt được bằng đọc chuỗi tiếng Anh trong `message`:
+ * - `superseded`: grant này đã bị grant mới thay (đối tác cấp lại camera-grant)
+ *   → app DỪNG tại chỗ, không `end`, không quay số lại.
+ * - `ended`: phiên đã kết thúc → dọn state, không thử lại.
+ * - `expired`: phiên đã quá trần thời lượng credential → xin grant/phiên mới.
+ */
+type SdkConflictReason = "superseded" | "ended" | "expired";
 interface SdkError {
     code: SdkErrorCode;
     message: string;
+    /** Chỉ có ở 409 SESSION_CONFLICT của namespace /api/v2/camera. */
+    reason?: SdkConflictReason;
+    /** Chỉ có ở 429 — cùng số với header `Retry-After` (giây, làm tròn lên). */
+    retryAfterMs?: number;
 }
 interface BootstrapInput {
     sdkVersion: string;
@@ -43,6 +56,14 @@ interface StartLivestreamInput {
      * Engine tự đặt cờ này theo options.autoPublish; app không cần truyền.
      */
     standby?: boolean;
+    /**
+     * Độ phân giải app THỰC SỰ quay, để server ghi đúng vào phiên. Chỉ app biết
+     * con số này: nó là lựa chọn local và app còn override `config.videoQuality`
+     * mà server trả về. Không khai thì server dùng mặc định của nó (1080) và bản
+     * ghi phiên nói dối — đã cắn 18/08/2026, dashboard báo 1080 trong khi máy
+     * phát 720 suốt.
+     */
+    quality?: 720 | 1080;
 }
 interface SdkTelemetryCredentials {
     endpoint: string;
@@ -64,6 +85,36 @@ interface SdkSessionRefresh {
     telemetry?: SdkTelemetryCredentials;
     config: SdkRemoteConfig;
 }
+type CameraGrantStatus = "scheduled" | "live";
+/**
+ * Camera grant — điện thoại của user ĐỐI TÁC lên sóng (ADR-0002). Backend đối
+ * tác nhận từ REST v1 (POST /api/v1/live-sessions {cameraGrant:true} hoặc
+ * POST /api/v1/live-sessions/{id}/camera-grant) và chuyển NGUYÊN TRẠNG cho app;
+ * app dùng `telemetry.token` làm Bearer với namespace /api/v2/camera/sessions.
+ *
+ * Superset nghiêm ngặt của SdkSessionGrant: `serverUrl` là RTMP ingest
+ * (`rtmp://host:1935/`), `participantToken` là stream key — SDK 0.2 đã nhận
+ * hình dạng này qua isSessionGrant nên không cần validator mới ở lớp engine.
+ */
+interface CameraGrant extends SdkSessionGrant {
+    /** Không bao giờ "ended" — endpoint trả 409 thay vì grant. */
+    status: CameraGrantStatus;
+    matchRef: string | null;
+    courtRef: string | null;
+    watchUrl: string | null;
+    /**
+     * Origin websocket Convex (https://<dep>.convex.cloud) để SDK subscribe lệnh
+     * thay vì poll HTTP 2s; null khi deployment không lộ origin chuẩn → SDK poll.
+     */
+    convexUrl: string | null;
+    issuedAt: number;
+    /**
+     * Hạn dùng của grant. Phiên chờ mà app CHƯA từng kết nối bị dọn sau 30 phút
+     * (RTMP_STANDBY_SILENT_MS) — xin grant đúng lúc user mở camera, đừng cấp sớm
+     * hàng giờ trước trận.
+     */
+    expiresAt: number;
+}
 interface EndLivestreamInput {
     sessionId: string;
     reason: "user" | "background_timeout" | "network_timeout" | "standby_timeout" | "error";
@@ -77,6 +128,22 @@ interface SdkTelemetryEvent {
     name: SdkTelemetryEventName;
     data?: Record<string, unknown>;
 }
+/** Lệnh điều khiển phiên giao qua kênh poll (mode device-rtmp). */
+type SessionCommandAction = "start" | "stop" | "end";
+interface SessionCommandRecord {
+    id: string;
+    action: SessionCommandAction;
+    /** Con trỏ tăng nghiêm ngặt theo phiên — client gửi lại làm `after`. */
+    issuedAt: number;
+}
+interface SessionCommandPollResult {
+    commands: SessionCommandRecord[];
+    /**
+     * Trạng thái phiên phía server — lưới an toàn khi lệnh rơi: "live" mà máy
+     * còn standby thì tự phát, "ended" thì tự kết thúc.
+     */
+    status: "scheduled" | "live" | "ended";
+}
 interface LivestreamSessionProvider {
     bootstrap(input: BootstrapInput): Promise<SdkBootstrap>;
     start(input: StartLivestreamInput): Promise<SdkSessionGrant>;
@@ -318,6 +385,20 @@ type RoomEvent = {
     action: string;
 };
 interface RoomAdapter {
+    /**
+     * Xin quyền camera/mic theo cách của mode. Không có thì engine dùng
+     * runtime.requestPermissions() (getUserMedia của WebRTC — mở camera thật
+     * ~400ms). Mode device-rtmp PHẢI tự xin bằng API quyền thuần: máy Android
+     * MediaTek chỉ cho một camera mở, camera WebRTC chưa nhả là HaishinKit dính
+     * "Too many users (-87)" và preview đen.
+     */
+    requestPermissions?(): Promise<boolean>;
+    /**
+     * true = adapter KHÔNG tự nối lại khi rớt (RTMP: native chỉ báo
+     * "disconnected" rồi đứng im) — engine phải chủ động quay số lại qua retry().
+     * LiveKit bỏ trống: SDK của nó tự hồi và tự bắn "reconnected".
+     */
+    readonly needsManualReconnect?: boolean;
     /** Bật/tắt publish track khi đã ở trong phòng (standby ↔ live). */
     setPublishing?(enabled: boolean): Promise<void>;
     setCaptureOrientation?(orientation: CaptureOrientation): Promise<void>;
@@ -346,18 +427,66 @@ interface SdkNetwork {
     isOnline(): boolean;
     subscribe(listener: (online: boolean) => void): () => void;
 }
+/**
+ * Khi app khởi động lại và thấy dấu của một phiên chưa được dừng có chủ ý, hàm
+ * này quyết định: GIỮ phiên đó để nhận lại, hay kết thúc nó như trước.
+ *
+ * Mặc định (không truyền) = kết thúc, giữ nguyên hành vi cho mọi SDK đối tác.
+ * App first-party trả true khi máy đang gán sân: lúc đó máy sụp nguồn giữa trận
+ * là chuyện của thiết bị gác sân, và nối lại đúng phiên cũ mới giữ được link xem
+ * và VOD liền mạch. Máy không gán sân thì vẫn dọn sạch như cũ.
+ */
+/**
+ * Được phép async có chủ đích: câu trả lời đúng nằm TRÊN ĐĨA (sân đã gán có
+ * persist), còn React state lúc engine khởi động thường CHƯA restore xong.
+ * Bản sync-đọc-state đã gây lỗi thật (18/08/2026): recover chạy trước restore
+ * → keep=false oan → app tự kết án phiên đáng giữ rồi arm phiên chờ THỨ HAI.
+ */
+type KeepSessionOnRestart = () => boolean | Promise<boolean>;
 interface TelemetrySink {
     send(credentials: SdkTelemetryCredentials, events: readonly SdkTelemetryEvent[]): Promise<void>;
     dispose?(): void;
 }
+/**
+ * Kênh nhận lệnh điều khiển cho mode device-rtmp: RTMP không có data channel
+ * nên start/stop/end từ server (match-start của trọng tài, dashboard) về qua
+ * HTTP poll, auth bằng chính telemetry token trong grant.
+ */
+interface SessionCommandChannel {
+    poll(credentials: SdkTelemetryCredentials, after: number): Promise<SessionCommandPollResult>;
+    dispose?(): void;
+}
+/**
+ * Kênh nhận lệnh device-rtmp qua WEBSOCKET (Convex subscription) — thay poll
+ * HTTP 2s cho máy first-party nối thẳng Convex. Lệnh về tức thì, lúc rảnh gần
+ * như 0 function call (poll 2s ở 200 máy là ~518M call/tháng). Có kênh này thì
+ * engine hạ poll về nhịp reconcile chậm làm lưới an toàn; thiếu thì poll như cũ.
+ */
+interface SessionCommandSubscription {
+    /**
+     * Mở subscription cho phiên; `onCommands` được gọi mỗi lần hàng lệnh đổi
+     * (kể cả lần đầu). `onError` báo websocket/token hỏng để engine tăng lại nhịp
+     * poll. Trả hàm huỷ subscription (KHÔNG đóng client — tái dùng qua phiên).
+     */
+    subscribe(credentials: SdkTelemetryCredentials, sessionId: string, onCommands: (commands: SessionCommandRecord[]) => void, onError?: (error: Error) => void): () => void;
+    dispose?(): void;
+}
 interface EngineDependencies {
     sessionProvider: LivestreamSessionProvider;
     bootstrapInput: BootstrapInput;
     roomFactory: () => RoomAdapter;
+    keepSessionOnRestart?: KeepSessionOnRestart;
     runtime: SdkRuntime;
     storage: SdkStorage;
     network: SdkNetwork;
     telemetry?: TelemetrySink;
+    /** Kênh poll lệnh cho phiên device-rtmp; thiếu thì mode này điếc lệnh server. */
+    commandChannel?: SessionCommandChannel;
+    /**
+     * Kênh nhận lệnh qua websocket (first-party). Có thì lệnh về tức thì và poll
+     * tụt về nhịp reconcile; thiếu (máy đối tác qua proxy) thì chỉ dùng poll.
+     */
+    commandSubscription?: SessionCommandSubscription;
     /** Thu chỉ số thiết bị; gọi mỗi nhịp heartbeat khi đang phát. */
     deviceMetrics?: () => Promise<DeviceMetricsSample | null>;
     now?: () => number;
@@ -378,6 +507,16 @@ interface DeviceMetricsSample {
     storageFreeGb?: number;
     netType?: string;
     linkMbps?: number;
+    /** Cường độ sóng WiFi 0-100% — CHỈ Android (iOS không mở cho app). */
+    signalPct?: number;
+    /** IP nội bộ — phân biệt máy đang bám router nào, không cần quyền vị trí. */
+    localIp?: string;
+    /**
+     * Tần số kênh WiFi (MHz) — CHỈ Android. 2412–2484 = băng 2.4 GHz, ≥ 5000 =
+     * 5 GHz. Thay cho SSID (bị khoá sau quyền vị trí): 22/08/2026 một máy rơi từ
+     * AP 5 GHz của giải sang WiFi quán 2.4 GHz mà heartbeat không phân biệt được.
+     */
+    freqMhz?: number;
     rssi?: number;
     connQuality?: string;
     charging?: boolean;
@@ -400,6 +539,14 @@ interface LivestreamSnapshot {
     selectedCameraId: string | null;
     elapsedMs: number;
     isOnline: boolean;
+    /**
+     * Phiên cũ còn sống mà app vừa khởi động lại có thể NHẬN LẠI (thay vì tạo phiên
+     * mới). Chỉ khác null khi engine tìm thấy dấu của một phiên chưa được dừng có
+     * chủ ý VÀ caller nói phiên đó đáng giữ (keepSessionOnRestart). Tầng trên
+     * (AutoResume) đọc trường này để nối lại đúng phiên cũ — giữ nguyên link xem và
+     * VOD liền một mạch.
+     */
+    adoptableSessionId: string | null;
 }
 declare const PENDING_END_KEY = "@pickleball/expo-sdk/pending-end";
 declare const LEGAL_LIVESTREAM_TRANSITIONS: Readonly<Record<LivestreamState, readonly LivestreamState[]>>;
@@ -428,10 +575,23 @@ declare class LivestreamEngine {
     private backgroundTimer?;
     private standbyTimer?;
     private reconnectTimer?;
+    private redialTimer?;
+    /** Đang trong vòng quay số lại — xem doRetry() để biết vì sao cần cờ này. */
+    private redialing;
     private heartbeatTimer?;
     private elapsedTimer?;
     private tokenRefreshTimer?;
     private maxSessionTimer?;
+    private commandPollTimer?;
+    /** Huỷ subscription websocket lệnh của phiên hiện tại (nếu đang mở). */
+    private commandUnsubscribe?;
+    /** Khoá phiên+token đang subscribe — đổi thì resubscribe (token refresh/đổi phiên). */
+    private commandSubscriptionKey?;
+    /** Websocket đã đẩy được ít nhất một lần → coi là sống, cho phép hạ nhịp poll. */
+    private commandSubscriptionActive;
+    /** issuedAt của lệnh cuối đã xử lý — server chỉ trả lệnh mới hơn mốc này. */
+    private commandCursor;
+    private commandPollBackoffMs;
     private grant?;
     private startedAt?;
     /** Đang publish track (live) hay chỉ ngồi trong phòng (standby). */
@@ -471,16 +631,81 @@ declare class LivestreamEngine {
     handleRoomEvent(event: RoomEvent): void;
     handleAppState(state: "active" | "background" | "inactive"): void;
     private ensureBackgroundGraceTimer;
-    dispose(): Promise<void>;
+    /**
+     * `keepSession` = engine bị tháo nhưng phiên phải sống tiếp để lần mở app sau
+     * nhận lại. Mặc định false: giữ NGUYÊN hành vi cũ cho mọi SDK đối tác.
+     *
+     * Lưu ý dispose KHÔNG BAO GIỜ là đường của "người dùng bấm dừng" — nút dừng đi
+     * qua doStop, mà doStop xoá ownedSessionId trước, nên tới đây sessionId đã là
+     * undefined. Vì vậy nhánh end ở đây luôn là teardown NGOÀI Ý MUỐN (app bị giết,
+     * component remount), đúng chỗ cần giữ phiên.
+     */
+    dispose(options?: {
+        keepSession?: boolean;
+    }): Promise<void>;
     private replayPendingEnd;
     private doReplayPendingEnd;
+    /**
+     * Phiên tưởng đáng nhận lại hoá ra đã chết phía server → BỎ dấu để máy arm
+     * phiên mới được.
+     *
+     * Thiếu hàm này là máy kẹt cứng: dấu vẫn nằm đó chặn mọi lượt start (đúng vai
+     * trò chống phiên song song của nó), mà lượt start duy nhất được cho qua lại là
+     * lượt nhận lại chính cái phiên đã chết — không bao giờ thành công. Đã dính
+     * thật 18/08/2026: lưới standby 30 phút kết thúc phiên trong lúc máy ngủ, mở
+     * lại thì app đứng ở "error" vĩnh viễn.
+     */
+    abandonAdoptableSession(sessionId: string): Promise<void>;
     private recoverStartupSession;
+    /**
+     * Dấu phiên cũ chặn thao tác mới cho tới khi nó được giải quyết.
+     *
+     * `externalSessionId` = id lượt start đang xin đi qua; bỏ trống nghĩa là
+     * prepare (mở camera), vốn phải luôn được phép khi đang định nhận lại — không
+     * mở được camera thì không nhận lại được, và đó chính là bẫy làm máy kẹt cứng ở
+     * màn lỗi "The previous livestream is still pending end".
+     */
     private ensurePendingEndResolved;
     private readPendingEnd;
     private ownsInMemorySession;
     private startTimers;
     private clearTimers;
+    /**
+     * Quay số lại với backoff cho adapter cần reconnect thủ công. Mỗi nhịp gọi
+     * retry() (refresh credentials + room.connect + enterSession). Thành công →
+     * enterSession phát "publishing" → nhánh "reconnected" dọn cả hai timer.
+     * Thất bại → doRetry() đưa state về "error" (vẫn còn sessionId) và nhịp sau
+     * retry() lại kéo về "reconnecting" — lặp tới khi doom timer 30s kết liễu.
+     * Backoff thưa dần để không dội server khi ingest thật sự sập.
+     */
+    private scheduleRedial;
+    private clearRedialTimer;
+    private stopRedialing;
     private clearReconnectTimer;
+    /**
+     * Poll lệnh chỉ khi phiên là device-rtmp (grant rtmp://) và đang standby/
+     * live. Ngoài hai trạng thái đó không có gì để điều khiển: connecting chưa
+     * có phiên chạy, reconnecting đã có reconnect timer lo, ending/ended thì thôi.
+     */
+    private commandPollingWanted;
+    private syncCommandPolling;
+    /**
+     * Mở/đổi websocket nhận lệnh cho phiên hiện tại. Chỉ máy first-party có
+     * dependency này (đối tác qua proxy thì undefined → chỉ poll). Resubscribe
+     * khi đổi phiên HOẶC token (refresh) vì cả hai đi vào khoá.
+     */
+    private syncCommandSubscription;
+    private stopCommandSubscription;
+    private stopCommandPolling;
+    private scheduleCommandPoll;
+    private commandPollInterval;
+    /**
+     * Áp lệnh từ poll HOẶC subscription vào cùng một state machine. Subscription
+     * trả cả lệnh CŨ (after:0) nên phải lọc theo con trỏ ở đây; poll đã lọc
+     * server-side (after=cursor) nên bước lọc này vô hại với nó.
+     */
+    private applyCommands;
+    private pollSessionCommands;
     /** Heartbeat kèm chỉ số thiết bị (nếu collector được cung cấp). */
     private sendHeartbeat;
     private sendTelemetry;
@@ -513,4 +738,4 @@ declare class LivestreamEngine {
     private ensureOperation;
 }
 
-export { UnsupportedRuntimeError as A, type BootstrapInput as B, type CameraDeviceInfo as C, type DeviceMetricsSample as D, type EndLivestreamInput as E, UnsupportedSdkError as F, compareSemver as G, errorFromCode as H, InvalidResponseError as I, isSdkRemoteConfig as J, isSdkVersionSupported as K, type LivestreamSessionProvider as L, isSessionGoneError as M, NetworkUnavailableError as N, normalizeError as O, PermissionDeniedError as P, LivestreamEngine as Q, RecordingFailureError as R, type StartLivestreamInput as S, type TelemetrySink as T, UnknownSdkError as U, type RoomConnection as V, type RoomEvent as W, type EngineDependencies as X, LEGAL_LIVESTREAM_TRANSITIONS as Y, PENDING_END_KEY as Z, type CaptureOrientation as a, ConsentRequiredError as b, type EndReason as c, ExpoSdkConfigurationError as d, type ExpoSdkErrorCode as e, ExpoSdkTimeoutError as f, type LivestreamSnapshot as g, type LivestreamState as h, PickleballExpoError as i, type RoomAdapter as j, SDK_TELEMETRY_EVENT_NAMES as k, type SdkBootstrap as l, SdkDisabledError as m, type SdkError as n, type SdkErrorCode as o, type SdkNetwork as p, type SdkRemoteConfig as q, type SdkRuntime as r, type SdkSessionGrant as s, type SdkSessionRefresh as t, type SdkStorage as u, type SdkTelemetryCredentials as v, type SdkTelemetryEvent as w, type SdkTelemetryEventName as x, SessionConflictError as y, TokenExpiredError as z };
+export { normalizeError as $, type SdkTelemetryEvent as A, type BootstrapInput as B, type CameraGrant as C, type DeviceMetricsSample as D, type EndLivestreamInput as E, type SdkTelemetryEventName as F, type SessionCommandAction as G, type SessionCommandChannel as H, InvalidResponseError as I, type SessionCommandPollResult as J, type SessionCommandRecord as K, type LivestreamSessionProvider as L, SessionConflictError as M, NetworkUnavailableError as N, TokenExpiredError as O, PermissionDeniedError as P, UnsupportedRuntimeError as Q, type RoomAdapter as R, type SessionCommandSubscription as S, type TelemetrySink as T, UnknownSdkError as U, UnsupportedSdkError as V, compareSemver as W, errorFromCode as X, isSdkRemoteConfig as Y, isSdkVersionSupported as Z, isSessionGoneError as _, type SdkStorage as a, LivestreamEngine as a0, type RoomConnection as a1, type RoomEvent as a2, type EngineDependencies as a3, LEGAL_LIVESTREAM_TRANSITIONS as a4, PENDING_END_KEY as a5, type SdkSessionGrant as b, type StartLivestreamInput as c, type SdkRemoteConfig as d, type CameraDeviceInfo as e, type CameraGrantStatus as f, type CaptureOrientation as g, ConsentRequiredError as h, type EndReason as i, ExpoSdkConfigurationError as j, type ExpoSdkErrorCode as k, ExpoSdkTimeoutError as l, type LivestreamSnapshot as m, type LivestreamState as n, PickleballExpoError as o, RecordingFailureError as p, SDK_TELEMETRY_EVENT_NAMES as q, type SdkBootstrap as r, type SdkConflictReason as s, SdkDisabledError as t, type SdkError as u, type SdkErrorCode as v, type SdkNetwork as w, type SdkRuntime as x, type SdkSessionRefresh as y, type SdkTelemetryCredentials as z };

package/dist/{engine-CCSSqPbZ.d.ts → engine-BSvSdCSE.d.ts}

@@ -2,9 +2,22 @@ type LivestreamState = "idle" | "preparing" | "preview" | "connecting"
 /** Đã vào phòng, chưa phát — chờ lệnh phát từ app hoặc dashboard. */
  | "standby" | "live" | "reconnecting" | "ending" | "ended" | "error";
 type SdkErrorCode = "PERMISSION_DENIED" | "NETWORK_UNAVAILABLE" | "TOKEN_EXPIRED" | "SDK_UPGRADE_REQUIRED" | "SESSION_CONFLICT" | "RECORDING_FAILED" | "CONSENT_REQUIRED" | "SDK_DISABLED" | "UNKNOWN";
+/**
+ * Vì sao 409 SESSION_CONFLICT bị nhận — ba ca cần app hành xử KHÁC NHAU mà
+ * trước đây chỉ phân biệt được bằng đọc chuỗi tiếng Anh trong `message`:
+ * - `superseded`: grant này đã bị grant mới thay (đối tác cấp lại camera-grant)
+ *   → app DỪNG tại chỗ, không `end`, không quay số lại.
+ * - `ended`: phiên đã kết thúc → dọn state, không thử lại.
+ * - `expired`: phiên đã quá trần thời lượng credential → xin grant/phiên mới.
+ */
+type SdkConflictReason = "superseded" | "ended" | "expired";
 interface SdkError {
     code: SdkErrorCode;
     message: string;
+    /** Chỉ có ở 409 SESSION_CONFLICT của namespace /api/v2/camera. */
+    reason?: SdkConflictReason;
+    /** Chỉ có ở 429 — cùng số với header `Retry-After` (giây, làm tròn lên). */
+    retryAfterMs?: number;
 }
 interface BootstrapInput {
     sdkVersion: string;
@@ -43,6 +56,14 @@ interface StartLivestreamInput {
      * Engine tự đặt cờ này theo options.autoPublish; app không cần truyền.
      */
     standby?: boolean;
+    /**
+     * Độ phân giải app THỰC SỰ quay, để server ghi đúng vào phiên. Chỉ app biết
+     * con số này: nó là lựa chọn local và app còn override `config.videoQuality`
+     * mà server trả về. Không khai thì server dùng mặc định của nó (1080) và bản
+     * ghi phiên nói dối — đã cắn 18/08/2026, dashboard báo 1080 trong khi máy
+     * phát 720 suốt.
+     */
+    quality?: 720 | 1080;
 }
 interface SdkTelemetryCredentials {
     endpoint: string;
@@ -64,6 +85,36 @@ interface SdkSessionRefresh {
     telemetry?: SdkTelemetryCredentials;
     config: SdkRemoteConfig;
 }
+type CameraGrantStatus = "scheduled" | "live";
+/**
+ * Camera grant — điện thoại của user ĐỐI TÁC lên sóng (ADR-0002). Backend đối
+ * tác nhận từ REST v1 (POST /api/v1/live-sessions {cameraGrant:true} hoặc
+ * POST /api/v1/live-sessions/{id}/camera-grant) và chuyển NGUYÊN TRẠNG cho app;
+ * app dùng `telemetry.token` làm Bearer với namespace /api/v2/camera/sessions.
+ *
+ * Superset nghiêm ngặt của SdkSessionGrant: `serverUrl` là RTMP ingest
+ * (`rtmp://host:1935/`), `participantToken` là stream key — SDK 0.2 đã nhận
+ * hình dạng này qua isSessionGrant nên không cần validator mới ở lớp engine.
+ */
+interface CameraGrant extends SdkSessionGrant {
+    /** Không bao giờ "ended" — endpoint trả 409 thay vì grant. */
+    status: CameraGrantStatus;
+    matchRef: string | null;
+    courtRef: string | null;
+    watchUrl: string | null;
+    /**
+     * Origin websocket Convex (https://<dep>.convex.cloud) để SDK subscribe lệnh
+     * thay vì poll HTTP 2s; null khi deployment không lộ origin chuẩn → SDK poll.
+     */
+    convexUrl: string | null;
+    issuedAt: number;
+    /**
+     * Hạn dùng của grant. Phiên chờ mà app CHƯA từng kết nối bị dọn sau 30 phút
+     * (RTMP_STANDBY_SILENT_MS) — xin grant đúng lúc user mở camera, đừng cấp sớm
+     * hàng giờ trước trận.
+     */
+    expiresAt: number;
+}
 interface EndLivestreamInput {
     sessionId: string;
     reason: "user" | "background_timeout" | "network_timeout" | "standby_timeout" | "error";
@@ -77,6 +128,22 @@ interface SdkTelemetryEvent {
     name: SdkTelemetryEventName;
     data?: Record<string, unknown>;
 }
+/** Lệnh điều khiển phiên giao qua kênh poll (mode device-rtmp). */
+type SessionCommandAction = "start" | "stop" | "end";
+interface SessionCommandRecord {
+    id: string;
+    action: SessionCommandAction;
+    /** Con trỏ tăng nghiêm ngặt theo phiên — client gửi lại làm `after`. */
+    issuedAt: number;
+}
+interface SessionCommandPollResult {
+    commands: SessionCommandRecord[];
+    /**
+     * Trạng thái phiên phía server — lưới an toàn khi lệnh rơi: "live" mà máy
+     * còn standby thì tự phát, "ended" thì tự kết thúc.
+     */
+    status: "scheduled" | "live" | "ended";
+}
 interface LivestreamSessionProvider {
     bootstrap(input: BootstrapInput): Promise<SdkBootstrap>;
     start(input: StartLivestreamInput): Promise<SdkSessionGrant>;
@@ -318,6 +385,20 @@ type RoomEvent = {
     action: string;
 };
 interface RoomAdapter {
+    /**
+     * Xin quyền camera/mic theo cách của mode. Không có thì engine dùng
+     * runtime.requestPermissions() (getUserMedia của WebRTC — mở camera thật
+     * ~400ms). Mode device-rtmp PHẢI tự xin bằng API quyền thuần: máy Android
+     * MediaTek chỉ cho một camera mở, camera WebRTC chưa nhả là HaishinKit dính
+     * "Too many users (-87)" và preview đen.
+     */
+    requestPermissions?(): Promise<boolean>;
+    /**
+     * true = adapter KHÔNG tự nối lại khi rớt (RTMP: native chỉ báo
+     * "disconnected" rồi đứng im) — engine phải chủ động quay số lại qua retry().
+     * LiveKit bỏ trống: SDK của nó tự hồi và tự bắn "reconnected".
+     */
+    readonly needsManualReconnect?: boolean;
     /** Bật/tắt publish track khi đã ở trong phòng (standby ↔ live). */
     setPublishing?(enabled: boolean): Promise<void>;
     setCaptureOrientation?(orientation: CaptureOrientation): Promise<void>;
@@ -346,18 +427,66 @@ interface SdkNetwork {
     isOnline(): boolean;
     subscribe(listener: (online: boolean) => void): () => void;
 }
+/**
+ * Khi app khởi động lại và thấy dấu của một phiên chưa được dừng có chủ ý, hàm
+ * này quyết định: GIỮ phiên đó để nhận lại, hay kết thúc nó như trước.
+ *
+ * Mặc định (không truyền) = kết thúc, giữ nguyên hành vi cho mọi SDK đối tác.
+ * App first-party trả true khi máy đang gán sân: lúc đó máy sụp nguồn giữa trận
+ * là chuyện của thiết bị gác sân, và nối lại đúng phiên cũ mới giữ được link xem
+ * và VOD liền mạch. Máy không gán sân thì vẫn dọn sạch như cũ.
+ */
+/**
+ * Được phép async có chủ đích: câu trả lời đúng nằm TRÊN ĐĨA (sân đã gán có
+ * persist), còn React state lúc engine khởi động thường CHƯA restore xong.
+ * Bản sync-đọc-state đã gây lỗi thật (18/08/2026): recover chạy trước restore
+ * → keep=false oan → app tự kết án phiên đáng giữ rồi arm phiên chờ THỨ HAI.
+ */
+type KeepSessionOnRestart = () => boolean | Promise<boolean>;
 interface TelemetrySink {
     send(credentials: SdkTelemetryCredentials, events: readonly SdkTelemetryEvent[]): Promise<void>;
     dispose?(): void;
 }
+/**
+ * Kênh nhận lệnh điều khiển cho mode device-rtmp: RTMP không có data channel
+ * nên start/stop/end từ server (match-start của trọng tài, dashboard) về qua
+ * HTTP poll, auth bằng chính telemetry token trong grant.
+ */
+interface SessionCommandChannel {
+    poll(credentials: SdkTelemetryCredentials, after: number): Promise<SessionCommandPollResult>;
+    dispose?(): void;
+}
+/**
+ * Kênh nhận lệnh device-rtmp qua WEBSOCKET (Convex subscription) — thay poll
+ * HTTP 2s cho máy first-party nối thẳng Convex. Lệnh về tức thì, lúc rảnh gần
+ * như 0 function call (poll 2s ở 200 máy là ~518M call/tháng). Có kênh này thì
+ * engine hạ poll về nhịp reconcile chậm làm lưới an toàn; thiếu thì poll như cũ.
+ */
+interface SessionCommandSubscription {
+    /**
+     * Mở subscription cho phiên; `onCommands` được gọi mỗi lần hàng lệnh đổi
+     * (kể cả lần đầu). `onError` báo websocket/token hỏng để engine tăng lại nhịp
+     * poll. Trả hàm huỷ subscription (KHÔNG đóng client — tái dùng qua phiên).
+     */
+    subscribe(credentials: SdkTelemetryCredentials, sessionId: string, onCommands: (commands: SessionCommandRecord[]) => void, onError?: (error: Error) => void): () => void;
+    dispose?(): void;
+}
 interface EngineDependencies {
     sessionProvider: LivestreamSessionProvider;
     bootstrapInput: BootstrapInput;
     roomFactory: () => RoomAdapter;
+    keepSessionOnRestart?: KeepSessionOnRestart;
     runtime: SdkRuntime;
     storage: SdkStorage;
     network: SdkNetwork;
     telemetry?: TelemetrySink;
+    /** Kênh poll lệnh cho phiên device-rtmp; thiếu thì mode này điếc lệnh server. */
+    commandChannel?: SessionCommandChannel;
+    /**
+     * Kênh nhận lệnh qua websocket (first-party). Có thì lệnh về tức thì và poll
+     * tụt về nhịp reconcile; thiếu (máy đối tác qua proxy) thì chỉ dùng poll.
+     */
+    commandSubscription?: SessionCommandSubscription;
     /** Thu chỉ số thiết bị; gọi mỗi nhịp heartbeat khi đang phát. */
     deviceMetrics?: () => Promise<DeviceMetricsSample | null>;
     now?: () => number;
@@ -378,6 +507,16 @@ interface DeviceMetricsSample {
     storageFreeGb?: number;
     netType?: string;
     linkMbps?: number;
+    /** Cường độ sóng WiFi 0-100% — CHỈ Android (iOS không mở cho app). */
+    signalPct?: number;
+    /** IP nội bộ — phân biệt máy đang bám router nào, không cần quyền vị trí. */
+    localIp?: string;
+    /**
+     * Tần số kênh WiFi (MHz) — CHỈ Android. 2412–2484 = băng 2.4 GHz, ≥ 5000 =
+     * 5 GHz. Thay cho SSID (bị khoá sau quyền vị trí): 22/08/2026 một máy rơi từ
+     * AP 5 GHz của giải sang WiFi quán 2.4 GHz mà heartbeat không phân biệt được.
+     */
+    freqMhz?: number;
     rssi?: number;
     connQuality?: string;
     charging?: boolean;
@@ -400,6 +539,14 @@ interface LivestreamSnapshot {
     selectedCameraId: string | null;
     elapsedMs: number;
     isOnline: boolean;
+    /**
+     * Phiên cũ còn sống mà app vừa khởi động lại có thể NHẬN LẠI (thay vì tạo phiên
+     * mới). Chỉ khác null khi engine tìm thấy dấu của một phiên chưa được dừng có
+     * chủ ý VÀ caller nói phiên đó đáng giữ (keepSessionOnRestart). Tầng trên
+     * (AutoResume) đọc trường này để nối lại đúng phiên cũ — giữ nguyên link xem và
+     * VOD liền một mạch.
+     */
+    adoptableSessionId: string | null;
 }
 declare const PENDING_END_KEY = "@pickleball/expo-sdk/pending-end";
 declare const LEGAL_LIVESTREAM_TRANSITIONS: Readonly<Record<LivestreamState, readonly LivestreamState[]>>;
@@ -428,10 +575,23 @@ declare class LivestreamEngine {
     private backgroundTimer?;
     private standbyTimer?;
     private reconnectTimer?;
+    private redialTimer?;
+    /** Đang trong vòng quay số lại — xem doRetry() để biết vì sao cần cờ này. */
+    private redialing;
     private heartbeatTimer?;
     private elapsedTimer?;
     private tokenRefreshTimer?;
     private maxSessionTimer?;
+    private commandPollTimer?;
+    /** Huỷ subscription websocket lệnh của phiên hiện tại (nếu đang mở). */
+    private commandUnsubscribe?;
+    /** Khoá phiên+token đang subscribe — đổi thì resubscribe (token refresh/đổi phiên). */
+    private commandSubscriptionKey?;
+    /** Websocket đã đẩy được ít nhất một lần → coi là sống, cho phép hạ nhịp poll. */
+    private commandSubscriptionActive;
+    /** issuedAt của lệnh cuối đã xử lý — server chỉ trả lệnh mới hơn mốc này. */
+    private commandCursor;
+    private commandPollBackoffMs;
     private grant?;
     private startedAt?;
     /** Đang publish track (live) hay chỉ ngồi trong phòng (standby). */
@@ -471,16 +631,81 @@ declare class LivestreamEngine {
     handleRoomEvent(event: RoomEvent): void;
     handleAppState(state: "active" | "background" | "inactive"): void;
     private ensureBackgroundGraceTimer;
-    dispose(): Promise<void>;
+    /**
+     * `keepSession` = engine bị tháo nhưng phiên phải sống tiếp để lần mở app sau
+     * nhận lại. Mặc định false: giữ NGUYÊN hành vi cũ cho mọi SDK đối tác.
+     *
+     * Lưu ý dispose KHÔNG BAO GIỜ là đường của "người dùng bấm dừng" — nút dừng đi
+     * qua doStop, mà doStop xoá ownedSessionId trước, nên tới đây sessionId đã là
+     * undefined. Vì vậy nhánh end ở đây luôn là teardown NGOÀI Ý MUỐN (app bị giết,
+     * component remount), đúng chỗ cần giữ phiên.
+     */
+    dispose(options?: {
+        keepSession?: boolean;
+    }): Promise<void>;
     private replayPendingEnd;
     private doReplayPendingEnd;
+    /**
+     * Phiên tưởng đáng nhận lại hoá ra đã chết phía server → BỎ dấu để máy arm
+     * phiên mới được.
+     *
+     * Thiếu hàm này là máy kẹt cứng: dấu vẫn nằm đó chặn mọi lượt start (đúng vai
+     * trò chống phiên song song của nó), mà lượt start duy nhất được cho qua lại là
+     * lượt nhận lại chính cái phiên đã chết — không bao giờ thành công. Đã dính
+     * thật 18/08/2026: lưới standby 30 phút kết thúc phiên trong lúc máy ngủ, mở
+     * lại thì app đứng ở "error" vĩnh viễn.
+     */
+    abandonAdoptableSession(sessionId: string): Promise<void>;
     private recoverStartupSession;
+    /**
+     * Dấu phiên cũ chặn thao tác mới cho tới khi nó được giải quyết.
+     *
+     * `externalSessionId` = id lượt start đang xin đi qua; bỏ trống nghĩa là
+     * prepare (mở camera), vốn phải luôn được phép khi đang định nhận lại — không
+     * mở được camera thì không nhận lại được, và đó chính là bẫy làm máy kẹt cứng ở
+     * màn lỗi "The previous livestream is still pending end".
+     */
     private ensurePendingEndResolved;
     private readPendingEnd;
     private ownsInMemorySession;
     private startTimers;
     private clearTimers;
+    /**
+     * Quay số lại với backoff cho adapter cần reconnect thủ công. Mỗi nhịp gọi
+     * retry() (refresh credentials + room.connect + enterSession). Thành công →
+     * enterSession phát "publishing" → nhánh "reconnected" dọn cả hai timer.
+     * Thất bại → doRetry() đưa state về "error" (vẫn còn sessionId) và nhịp sau
+     * retry() lại kéo về "reconnecting" — lặp tới khi doom timer 30s kết liễu.
+     * Backoff thưa dần để không dội server khi ingest thật sự sập.
+     */
+    private scheduleRedial;
+    private clearRedialTimer;
+    private stopRedialing;
     private clearReconnectTimer;
+    /**
+     * Poll lệnh chỉ khi phiên là device-rtmp (grant rtmp://) và đang standby/
+     * live. Ngoài hai trạng thái đó không có gì để điều khiển: connecting chưa
+     * có phiên chạy, reconnecting đã có reconnect timer lo, ending/ended thì thôi.
+     */
+    private commandPollingWanted;
+    private syncCommandPolling;
+    /**
+     * Mở/đổi websocket nhận lệnh cho phiên hiện tại. Chỉ máy first-party có
+     * dependency này (đối tác qua proxy thì undefined → chỉ poll). Resubscribe
+     * khi đổi phiên HOẶC token (refresh) vì cả hai đi vào khoá.
+     */
+    private syncCommandSubscription;
+    private stopCommandSubscription;
+    private stopCommandPolling;
+    private scheduleCommandPoll;
+    private commandPollInterval;
+    /**
+     * Áp lệnh từ poll HOẶC subscription vào cùng một state machine. Subscription
+     * trả cả lệnh CŨ (after:0) nên phải lọc theo con trỏ ở đây; poll đã lọc
+     * server-side (after=cursor) nên bước lọc này vô hại với nó.
+     */
+    private applyCommands;
+    private pollSessionCommands;
     /** Heartbeat kèm chỉ số thiết bị (nếu collector được cung cấp). */
     private sendHeartbeat;
     private sendTelemetry;
@@ -513,4 +738,4 @@ declare class LivestreamEngine {
     private ensureOperation;
 }
 
-export { UnsupportedRuntimeError as A, type BootstrapInput as B, type CameraDeviceInfo as C, type DeviceMetricsSample as D, type EndLivestreamInput as E, UnsupportedSdkError as F, compareSemver as G, errorFromCode as H, InvalidResponseError as I, isSdkRemoteConfig as J, isSdkVersionSupported as K, type LivestreamSessionProvider as L, isSessionGoneError as M, NetworkUnavailableError as N, normalizeError as O, PermissionDeniedError as P, LivestreamEngine as Q, RecordingFailureError as R, type StartLivestreamInput as S, type TelemetrySink as T, UnknownSdkError as U, type RoomConnection as V, type RoomEvent as W, type EngineDependencies as X, LEGAL_LIVESTREAM_TRANSITIONS as Y, PENDING_END_KEY as Z, type CaptureOrientation as a, ConsentRequiredError as b, type EndReason as c, ExpoSdkConfigurationError as d, type ExpoSdkErrorCode as e, ExpoSdkTimeoutError as f, type LivestreamSnapshot as g, type LivestreamState as h, PickleballExpoError as i, type RoomAdapter as j, SDK_TELEMETRY_EVENT_NAMES as k, type SdkBootstrap as l, SdkDisabledError as m, type SdkError as n, type SdkErrorCode as o, type SdkNetwork as p, type SdkRemoteConfig as q, type SdkRuntime as r, type SdkSessionGrant as s, type SdkSessionRefresh as t, type SdkStorage as u, type SdkTelemetryCredentials as v, type SdkTelemetryEvent as w, type SdkTelemetryEventName as x, SessionConflictError as y, TokenExpiredError as z };
+export { normalizeError as $, type SdkTelemetryEvent as A, type BootstrapInput as B, type CameraGrant as C, type DeviceMetricsSample as D, type EndLivestreamInput as E, type SdkTelemetryEventName as F, type SessionCommandAction as G, type SessionCommandChannel as H, InvalidResponseError as I, type SessionCommandPollResult as J, type SessionCommandRecord as K, type LivestreamSessionProvider as L, SessionConflictError as M, NetworkUnavailableError as N, TokenExpiredError as O, PermissionDeniedError as P, UnsupportedRuntimeError as Q, type RoomAdapter as R, type SessionCommandSubscription as S, type TelemetrySink as T, UnknownSdkError as U, UnsupportedSdkError as V, compareSemver as W, errorFromCode as X, isSdkRemoteConfig as Y, isSdkVersionSupported as Z, isSessionGoneError as _, type SdkStorage as a, LivestreamEngine as a0, type RoomConnection as a1, type RoomEvent as a2, type EngineDependencies as a3, LEGAL_LIVESTREAM_TRANSITIONS as a4, PENDING_END_KEY as a5, type SdkSessionGrant as b, type StartLivestreamInput as c, type SdkRemoteConfig as d, type CameraDeviceInfo as e, type CameraGrantStatus as f, type CaptureOrientation as g, ConsentRequiredError as h, type EndReason as i, ExpoSdkConfigurationError as j, type ExpoSdkErrorCode as k, ExpoSdkTimeoutError as l, type LivestreamSnapshot as m, type LivestreamState as n, PickleballExpoError as o, RecordingFailureError as p, SDK_TELEMETRY_EVENT_NAMES as q, type SdkBootstrap as r, type SdkConflictReason as s, SdkDisabledError as t, type SdkError as u, type SdkErrorCode as v, type SdkNetwork as w, type SdkRuntime as x, type SdkSessionRefresh as y, type SdkTelemetryCredentials as z };