@pickleball/expo-sdk 0.1.1 → 0.2.0

package/dist/engine-CCSSqPbZ.d.ts

@@ -0,0 +1,516 @@
+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";
+interface SdkError {
+    code: SdkErrorCode;
+    message: string;
+}
+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;
+}
+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;
+}
+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>;
+}
+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 {
+    /** 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;
+}
+interface TelemetrySink {
+    send(credentials: SdkTelemetryCredentials, events: readonly SdkTelemetryEvent[]): Promise<void>;
+    dispose?(): void;
+}
+interface EngineDependencies {
+    sessionProvider: LivestreamSessionProvider;
+    bootstrapInput: BootstrapInput;
+    roomFactory: () => RoomAdapter;
+    runtime: SdkRuntime;
+    storage: SdkStorage;
+    network: SdkNetwork;
+    telemetry?: TelemetrySink;
+    /** 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;
+    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;
+}
+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 heartbeatTimer?;
+    private elapsedTimer?;
+    private tokenRefreshTimer?;
+    private maxSessionTimer?;
+    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;
+    dispose(): Promise<void>;
+    private replayPendingEnd;
+    private doReplayPendingEnd;
+    private recoverStartupSession;
+    private ensurePendingEndResolved;
+    private readPendingEnd;
+    private ownsInMemorySession;
+    private startTimers;
+    private clearTimers;
+    private clearReconnectTimer;
+    /** 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 { 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 };