@pickleball/expo-sdk 0.1.1 → 1.0.0

package/dist/engine-BSvSdCSE.d.cts

@@ -0,0 +1,741 @@
+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;
+    platform: "ios" | "android";
+    bundleId: string;
+    installationId: string;
+}
+interface SdkRemoteConfig {
+    enabled: boolean;
+    protocolVersion: 1;
+    minSdkVersion: string;
+    recommendedSdkVersion: string;
+    videoQuality: 720 | 1080;
+    reconnectTimeoutMs: number;
+    backgroundGraceMs: number;
+    telemetryIntervalMs: number;
+    maxSessionDurationMs: number;
+    /** Tự kết thúc phiên nếu ngồi standby quá lâu không phát (mặc định 15 phút). */
+    standbyTimeoutMs?: number;
+}
+interface SdkBootstrap {
+    config: SdkRemoteConfig;
+    serverTime: number;
+    rolloutEnabled: boolean;
+    message?: string;
+}
+interface StartLivestreamInput {
+    externalSessionId: string;
+    title: string;
+    visibility?: "public" | "private";
+    consentVersion: string;
+    metadata?: Record<string, string>;
+    /**
+     * true: vào phòng ở chế độ chờ (không publish) — server giữ status
+     * "scheduled" và KHÔNG khởi động recording egress cho tới khi publish.
+     * 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;
+    token: string;
+    expiresAt: number;
+}
+interface SdkSessionGrant {
+    sessionId: string;
+    serverUrl: string;
+    participantToken: string;
+    playbackUrl: string | null;
+    tokenExpiresAt: number;
+    telemetry: SdkTelemetryCredentials;
+    config: SdkRemoteConfig;
+}
+interface SdkSessionRefresh {
+    participantToken?: string;
+    tokenExpiresAt?: number;
+    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";
+}
+type EndReason = EndLivestreamInput["reason"];
+declare const SDK_TELEMETRY_EVENT_NAMES: readonly ["state_changed", "connection_quality", "reconnect", "error", "heartbeat", "session_ended"];
+type SdkTelemetryEventName = (typeof SDK_TELEMETRY_EVENT_NAMES)[number];
+interface SdkTelemetryEvent {
+    sessionId: string;
+    at: number;
+    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>;
+    refresh(sessionId: string): Promise<SdkSessionRefresh>;
+    end(input: EndLivestreamInput): Promise<void>;
+    /**
+     * Báo server bắt đầu phát thật (standby → live): server bật recording
+     * egress + chuyển status live TRƯỚC khi engine publish track. Optional để
+     * giữ tương thích provider cũ — thiếu thì engine bỏ qua bước server.
+     */
+    publish?(sessionId: string): Promise<void>;
+    /** Báo server tạm dừng phát (live → standby): dừng egress, status về chờ. */
+    unpublish?(sessionId: string): Promise<void>;
+}
+declare function isSdkRemoteConfig(value: unknown): value is SdkRemoteConfig;
+declare function compareSemver(left: string, right: string): -1 | 0 | 1;
+declare function isSdkVersionSupported(version: string, minimum: string): boolean;
+
+type ExpoSdkErrorCode = SdkErrorCode | "CONFIGURATION_ERROR" | "UNSUPPORTED_RUNTIME" | "INVALID_RESPONSE" | "TIMEOUT";
+declare class PickleballExpoError extends Error {
+    readonly code: ExpoSdkErrorCode;
+    constructor(message: string, code: ExpoSdkErrorCode, options?: ErrorOptions);
+}
+declare const PermissionDeniedError_base: {
+    new (message?: string, options?: ErrorOptions): {
+        readonly code: ExpoSdkErrorCode;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class PermissionDeniedError extends PermissionDeniedError_base {
+}
+declare const NetworkUnavailableError_base: {
+    new (message?: string, options?: ErrorOptions): {
+        readonly code: ExpoSdkErrorCode;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class NetworkUnavailableError extends NetworkUnavailableError_base {
+}
+declare const TokenExpiredError_base: {
+    new (message?: string, options?: ErrorOptions): {
+        readonly code: ExpoSdkErrorCode;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class TokenExpiredError extends TokenExpiredError_base {
+}
+declare const UnsupportedSdkError_base: {
+    new (message?: string, options?: ErrorOptions): {
+        readonly code: ExpoSdkErrorCode;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class UnsupportedSdkError extends UnsupportedSdkError_base {
+}
+declare const UnsupportedRuntimeError_base: {
+    new (message?: string, options?: ErrorOptions): {
+        readonly code: ExpoSdkErrorCode;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class UnsupportedRuntimeError extends UnsupportedRuntimeError_base {
+}
+declare const SessionConflictError_base: {
+    new (message?: string, options?: ErrorOptions): {
+        readonly code: ExpoSdkErrorCode;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class SessionConflictError extends SessionConflictError_base {
+}
+declare const RecordingFailureError_base: {
+    new (message?: string, options?: ErrorOptions): {
+        readonly code: ExpoSdkErrorCode;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class RecordingFailureError extends RecordingFailureError_base {
+}
+declare const ConsentRequiredError_base: {
+    new (message?: string, options?: ErrorOptions): {
+        readonly code: ExpoSdkErrorCode;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class ConsentRequiredError extends ConsentRequiredError_base {
+}
+declare const SdkDisabledError_base: {
+    new (message?: string, options?: ErrorOptions): {
+        readonly code: ExpoSdkErrorCode;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class SdkDisabledError extends SdkDisabledError_base {
+}
+declare const ExpoSdkConfigurationError_base: {
+    new (message?: string, options?: ErrorOptions): {
+        readonly code: ExpoSdkErrorCode;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class ExpoSdkConfigurationError extends ExpoSdkConfigurationError_base {
+}
+declare const InvalidResponseError_base: {
+    new (message?: string, options?: ErrorOptions): {
+        readonly code: ExpoSdkErrorCode;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class InvalidResponseError extends InvalidResponseError_base {
+}
+declare const ExpoSdkTimeoutError_base: {
+    new (message?: string, options?: ErrorOptions): {
+        readonly code: ExpoSdkErrorCode;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class ExpoSdkTimeoutError extends ExpoSdkTimeoutError_base {
+}
+declare const UnknownSdkError_base: {
+    new (message?: string, options?: ErrorOptions): {
+        readonly code: ExpoSdkErrorCode;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+declare class UnknownSdkError extends UnknownSdkError_base {
+}
+declare function errorFromCode(code: string, message?: string): PickleballExpoError;
+declare function normalizeError(error: unknown): PickleballExpoError;
+/**
+ * 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.
+ */
+declare function isSessionGoneError(error: unknown): boolean;
+
+interface RoomConnection {
+    serverUrl: string;
+    participantToken: string;
+    microphoneEnabled: boolean;
+    /** false: vào phòng nhưng chưa publish track (trạng thái standby). */
+    publish?: boolean;
+}
+type RoomEvent = {
+    type: "reconnecting";
+} | {
+    type: "reconnected";
+} | {
+    type: "disconnected";
+    reason?: string;
+} | {
+    type: "media-error";
+    error: unknown;
+}
+/** Lệnh điều khiển từ dashboard qua LiveKit data channel ({"type":"cmd"}). */
+ | {
+    type: "command";
+    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>;
+    listCameras?(): Promise<CameraDeviceInfo[]>;
+    selectCamera?(deviceId: string, facing: CameraDeviceInfo["facing"]): Promise<void>;
+    preparePreview(quality: 720 | 1080): Promise<unknown>;
+    connect(input: RoomConnection): Promise<void>;
+    disconnect(stopTracks?: boolean): Promise<void>;
+    switchCamera(): Promise<void>;
+    setMicrophoneEnabled(enabled: boolean): Promise<void>;
+    subscribe(listener: (event: RoomEvent) => void): () => void;
+    dispose(): Promise<void>;
+}
+interface SdkRuntime {
+    assertSupported(): void;
+    requestPermissions(): Promise<boolean>;
+    activateKeepAwake(): void | Promise<void>;
+    deactivateKeepAwake(): void | Promise<void>;
+}
+interface SdkStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+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;
+}
+type CaptureOrientation = "portrait" | "landscape";
+interface CameraDeviceInfo {
+    deviceId: string;
+    label: string;
+    facing: "front" | "environment" | "unknown";
+}
+/** Chỉ số thiết bị gửi kèm heartbeat (trường trùng schema deviceMetrics). */
+interface DeviceMetricsSample {
+    batteryPct?: number;
+    batteryTempC?: number;
+    thermal?: number;
+    ramFreeMb?: number;
+    ramTotalMb?: number;
+    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;
+}
+interface LivestreamSnapshot {
+    state: LivestreamState;
+    error: PickleballExpoError | null;
+    config: SdkRemoteConfig | null;
+    sessionId: string | null;
+    previewTrack: unknown;
+    isMicrophoneEnabled: boolean;
+    isCameraFront: boolean;
+    /** Explicit pre-live choice; null follows the window orientation. */
+    captureOrientation: CaptureOrientation | null;
+    /** Mẫu chỉ số thiết bị mới nhất (cập nhật mỗi heartbeat khi live). */
+    deviceMetrics: DeviceMetricsSample | null;
+    /** Cameras reported by the platform after preview was prepared. */
+    cameras: CameraDeviceInfo[];
+    /** Explicitly chosen camera; null when following facing (front/back). */
+    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[]>>;
+declare class LivestreamEngine {
+    private readonly dependencies;
+    private room?;
+    private readonly now;
+    private snapshot;
+    private listeners;
+    private preparePromise?;
+    private startPromise?;
+    private stopPromise?;
+    private retryPromise?;
+    private credentialRefreshPromise?;
+    private pendingReplayPromise?;
+    private startupRecoveryPromise?;
+    private startupRecovered;
+    private pendingReplayError?;
+    private ownedSessionId?;
+    private commandTail;
+    private commandCount;
+    private roomUnsubscribe;
+    private networkUnsubscribe;
+    private networkSubscribed;
+    private latestAppState;
+    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). */
+    private publishing;
+    /** Tổng thời gian đã phát trước lần tạm dừng gần nhất. */
+    private pausedElapsedMs;
+    private sessionDeadline?;
+    private refreshRetryAttempt;
+    private operationGeneration;
+    private liveTimersStarted;
+    private keepAwakeActive;
+    private telemetryInFlight?;
+    private pendingCriticalTelemetry?;
+    private readonly sessionTerminations;
+    private disposePromise?;
+    private disposed;
+    constructor(dependencies: EngineDependencies);
+    getSnapshot: () => LivestreamSnapshot;
+    subscribe: (listener: () => void) => () => boolean;
+    initialize(): Promise<void>;
+    prepare(): Promise<void>;
+    private doPrepare;
+    start(input: StartLivestreamInput, options?: {
+        autoPublish?: boolean;
+    }): Promise<void>;
+    private doStart;
+    stop(reason?: EndReason): Promise<void>;
+    private doStop;
+    retry(): Promise<void>;
+    private doRetry;
+    switchCamera(): Promise<void>;
+    /** Chọn một ống kính cụ thể từ snapshot.cameras. */
+    selectCamera(deviceId: string): Promise<void>;
+    /** Chọn kiểu quay trước khi live; không đổi khi phiên đang hoạt động. */
+    setCaptureOrientation(orientation: CaptureOrientation): Promise<void>;
+    setMicrophoneEnabled(enabled: boolean): Promise<void>;
+    handleRoomEvent(event: RoomEvent): void;
+    handleAppState(state: "active" | "background" | "inactive"): void;
+    private ensureBackgroundGraceTimer;
+    /**
+     * `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;
+    private startTelemetrySend;
+    private refreshCredentials;
+    private transition;
+    private startStandbyTimer;
+    private clearStandbyTimer;
+    private fail;
+    private recordError;
+    private update;
+    private ensureState;
+    private ensureNotDisposed;
+    private ensureRoom;
+    private ensureNetworkSubscription;
+    private requireRoom;
+    private releaseRoom;
+    private enqueueLifecycle;
+    private scheduleTokenRefresh;
+    private scheduleMaxSessionDuration;
+    private restartHeartbeat;
+    private enterSession;
+    /** Bắt đầu phát khi đang standby (từ nút trên app hoặc lệnh dashboard). */
+    startPublishing(): Promise<void>;
+    /** Tạm dừng phát: ngắt kết nối LiveKit hoàn toàn về standby, KHÔNG kết thúc phiên. */
+    stopPublishing(): Promise<void>;
+    private ensureSessionTermination;
+    private abandonGrant;
+    private isOperationCurrent;
+    private ensureOperation;
+}
+
+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 };