@pickleball/expo-sdk 0.1.1 → 1.0.0

package/dist/device-agent/index.d.cts

@@ -0,0 +1,493 @@
+import { a0 as LivestreamEngine, B as BootstrapInput, D as DeviceMetricsSample } from '../engine-BSvSdCSE.cjs';
+import { C as ConvexDeviceRealtime } from '../convex-command-subscription-DUgpu75l.cjs';
+export { c as createConvexCommandSubscription, a as createConvexDeviceRealtime } from '../convex-command-subscription-DUgpu75l.cjs';
+
+/**
+ * Nhịp heartbeat thích ứng — bản CHÉP của luật trong
+ * `packages/shared/src/realtime.ts`.
+ *
+ * Vì sao chép chứ không import: gói expo-sdk cố ý KHÔNG phụ thuộc
+ * `@pickleball/shared` (guard `scripts/verify-pack.mjs` chặn), để app đối tác
+ * cài SDK không phải kéo theo cả gói dùng chung của backend. Đổi luật ở đây thì
+ * phải đổi cả hai nơi — bộ test hai bên dùng CÙNG bảng giá trị để phát hiện lệch.
+ */
+declare const BEAT_SLOW_MS = 60000;
+declare const BEAT_FAST_MS = 12000;
+interface MqttBeatHealth {
+    connected: boolean;
+    subscribed: boolean;
+    lastInboundAt: number;
+    healthySince: number;
+}
+/** Đủ CẢ BỐN vế mới được coi là kênh khoẻ. */
+declare function mqttBeatHealthy(h: MqttBeatHealth, now: number): boolean;
+/**
+ * Nhịp kế tiếp = min(luật nội bộ, hint của server), và THIẾU hint thì mặc định
+ * nhanh. Nhờ vậy máy chưa nhận được hint (server cũ, hoặc beat lỗi) không bao
+ * giờ tự ý giãn nhịp, còn tắt rollout chỉ là đổi một biến env phía server.
+ */
+declare function nextBeatDelayMs(input: {
+    health: MqttBeatHealth | null;
+    now: number;
+    serverHintMs?: number;
+    busy?: boolean;
+}): number;
+
+/**
+ * DeviceAgent — đăng ký thiết bị với backend khi app mở và giữ heartbeat
+ * presence (12s/lần khi foreground) qua proxy. Khi dashboard yêu cầu "Kết nối",
+ * heartbeat trả về connect-token → agent mở kênh điều khiển realtime (Convex
+ * websocket) để nhận lệnh start/stop livestream tức thì. Publish/unpublish sau
+ * khi vào standby vẫn đi đường LiveKit data channel sẵn có của engine.
+ */
+interface DeviceAgentDeviceInfo {
+    appVersion?: string;
+    deviceName?: string;
+    deviceModel?: string;
+    osVersion?: string;
+}
+interface DeviceCommand {
+    id: string;
+    type: "start_livestream" | "stop_livestream" | "publish_livestream" | "unpublish_livestream";
+    payload: {
+        title?: string;
+        visibility?: "public" | "private";
+        /** Arm-từ-xa chế độ giải đấu: phiên standby sẽ đậu vào sân này. */
+        courtRef?: string;
+    };
+    expiresAt: number;
+}
+interface DeviceControlSessionGrant {
+    id: string;
+    token: string;
+    convexUrl: string;
+}
+/**
+ * Một lần tiến trình app chết trước đó — Android `ApplicationExitInfo`, native
+ * đã quy đổi `reasonName` ("PACKAGE_UPDATED", "CRASH", "ANR", "OTHER"…). Xem
+ * NativeProcessExit của @pickleball/rtmp-native; iOS không có nguồn tương đương.
+ */
+interface DeviceProcessExit {
+    /** epoch ms lúc chết. */
+    at: number;
+    reason: number;
+    reasonName: string;
+    /** Chuỗi hệ thống, VD "stop com.google.android.webview due to installPackageLI". */
+    description?: string;
+    /** IMPORTANCE_* lúc chết — 100 = đang ở tiền cảnh. */
+    importance?: number;
+    pid?: number;
+}
+interface DeviceHeartbeatBody {
+    agentState?: string;
+    currentSessionId?: string | null;
+    appVersion?: string;
+    metrics?: Record<string, number | string>;
+    /**
+     * Hộp đen: lý do các lần tiến trình chết gần đây. App chỉ cần gửi vài nhịp
+     * đầu sau khi mở (server giữ bản mới nhất, ghi idempotent theo mốc).
+     */
+    recentExits?: DeviceProcessExit[];
+    /**
+     * Trạng thái nguồn app tự khai: "rest" = chế độ nghỉ (camera/service đã tắt,
+     * máy đang nguội). Server chỉ ghi khi đổi — dashboard hiện badge "Đang nghỉ".
+     */
+    powerState?: "rest" | "active";
+    /**
+     * Xin tỉ số kèm response beat — CHỈ bật khi kênh MQTT đứt (đường nhanh
+     * plv1/dev/{id}/score câm); MQTT khoẻ mà vẫn xin là server đọc doc tỉ số
+     * mỗi nhịp vô ích.
+     */
+    wantScore?: boolean;
+}
+/**
+ * Field app tự gắn thêm vào MỖI heartbeat. Hàm được gọi ngay trước khi gửi,
+ * trả undefined/{} khi không có gì — ném lỗi thì bị nuốt, heartbeat vẫn đi.
+ */
+type DeviceHeartbeatExtras = Pick<DeviceHeartbeatBody, "recentExits" | "powerState" | "wantScore">;
+interface DeviceAgentTransport {
+    register(input: BootstrapInput & DeviceAgentDeviceInfo): Promise<{
+        deviceId: string;
+        heartbeatIntervalMs: number;
+    }>;
+    heartbeat(input: BootstrapInput & DeviceHeartbeatBody): Promise<{
+        controlSession: DeviceControlSessionGrant | null;
+        /**
+         * Nhịp server gợi ý cho lượt beat kế (adaptive heartbeat). Optional để
+         * transport/server đời cũ vẫn hợp lệ — thiếu thì agent giữ nhịp nhanh.
+         */
+        beatIntervalMs?: number;
+    }>;
+}
+/** Kênh điều khiển realtime — mặc định là Convex websocket (convex-control-channel). */
+interface DeviceControlChannel {
+    attach(controlSessionId: string, token: string): Promise<void>;
+    /** Subscribe lệnh pending — callback gọi lại mỗi khi danh sách đổi. */
+    onCommands(controlSessionId: string, token: string, callback: (commands: DeviceCommand[]) => void): () => void;
+    /** Subscribe trạng thái kênh — "ended"/"expired" thì agent tự đóng. */
+    onState(controlSessionId: string, token: string, callback: (state: {
+        status: string;
+    }) => void): () => void;
+    ack(input: {
+        controlSessionId: string;
+        token: string;
+        commandId: string;
+        status: "acked" | "completed" | "failed";
+        errorMessage?: string;
+        resultSessionId?: string;
+    }): Promise<void>;
+    close(): void;
+}
+interface RemoteStartConfig {
+    consentVersion: string;
+    /** Tiêu đề mặc định khi dashboard không gửi title. */
+    defaultTitle?: string;
+    visibility?: "public" | "private";
+    metadata?: Record<string, string>;
+}
+type AppStateListener = (state: "active" | "background" | "inactive") => void;
+interface DeviceAgentOptions {
+    engine: LivestreamEngine;
+    bootstrapInput: BootstrapInput;
+    transport: DeviceAgentTransport;
+    remoteStart: RemoteStartConfig;
+    deviceInfo?: DeviceAgentDeviceInfo;
+    onRemoteSessionStarted?: (sessionId: string) => void;
+    deviceMetrics?: () => Promise<DeviceMetricsSample | null>;
+    /** Field bổ sung cho heartbeat (VD recentExits) — xem DeviceHeartbeatExtras. */
+    heartbeatExtras?: () => DeviceHeartbeatExtras | undefined;
+    /**
+     * Sức khoẻ kênh MQTT của app (kênh nằm ở tầng app, không thuộc SDK). Có
+     * nguồn này VÀ server bật rollout thì nhịp beat giãn 12s → 60s; thiếu nó thì
+     * agent chạy y hệt trước đây. Ném lỗi trong callback được coi như "không có".
+     */
+    mqttHealth?: () => MqttBeatHealth | null;
+    /** Factory kênh điều khiển — test truyền fake; mặc định Convex websocket. */
+    createControlChannel?: (convexUrl: string) => DeviceControlChannel;
+    /** Test hook: nguồn app-state; mặc định react-native AppState. */
+    subscribeAppState?: (listener: AppStateListener) => () => void;
+}
+/**
+ * Metrics lần này có đáng gửi so với lần đã gửi không. Hàm thuần để test dễ.
+ * Đáng gửi khi: chưa gửi lần nào; pin vừa THỦNG mốc thấp (đang ≥10% tụt xuống
+ * <10%); pin đổi ≥5% so với mốc đã gửi; đổi mức nhiệt (thermal) hoặc loại mạng.
+ * KHÔNG tính RAM/sóng/nhiệt-độ-pin: chúng nhích liên tục, để mốc 5 phút lo.
+ */
+declare function metricsCrossedThreshold(last: Record<string, number | string> | undefined, next: Record<string, number | string>): boolean;
+declare class DeviceAgent {
+    private readonly options;
+    private running;
+    private registered;
+    private foreground;
+    private heartbeatIntervalMs;
+    /** Nhịp server gợi ý ở beat gần nhất — undefined = server chưa nói gì → 12s. */
+    private serverBeatHintMs;
+    private timer;
+    private beatInFlight;
+    private registerAttempt;
+    private unsubscribeAppState;
+    private heartbeatFailures;
+    /** Metrics đã gửi lần gần nhất + mốc thời gian, để lọc "chỉ gửi khi đổi". */
+    private lastSentMetrics?;
+    private lastMetricsSentAt;
+    private controlChannel;
+    private controlSessionId;
+    private controlUnsubscribers;
+    private executing;
+    private readonly handledCommandIds;
+    constructor(options: DeviceAgentOptions);
+    start(): void;
+    stop(): void;
+    private handleAppState;
+    /**
+     * Đang có phiên hoặc đã mở kênh điều khiển = lệnh tới qua kênh, nhịp thường
+     * là đủ. Rảnh và chưa có kênh = đang chờ lệnh, đập nhanh cho kịp dashboard.
+     */
+    private nextBeatDelay;
+    private schedule;
+    private beat;
+    private register;
+    /**
+     * Lọc metrics cho heartbeat: chỉ trả (và ghi nhớ) khi vượt ngưỡng
+     * (metricsCrossedThreshold) hoặc đã quá METRICS_BASELINE_MS kể từ lần gửi.
+     * Trả undefined = nhịp này không kèm metrics.
+     */
+    private selectMetricsForHeartbeat;
+    private heartbeat;
+    private openControlChannel;
+    private closeControlChannel;
+    private executeCommands;
+    private executeCommand;
+    private runStartLivestream;
+    private runStopLivestream;
+    /**
+     * standby → live theo lệnh dashboard. startPublishing() NUỐT lỗi (recordError
+     * vào snapshot thay vì throw) nên phải kiểm state sau khi gọi — không kiểm là
+     * lệnh được ack "completed" dù thiết bị chưa hề phát.
+     */
+    private runPublish;
+    private runUnpublish;
+    private safeAck;
+}
+
+type Fetch = typeof globalThis.fetch;
+type HeadersInput = Record<string, string>;
+interface HttpDeviceAgentTransportOptions {
+    /** Base URL của proxy đối tác (cùng proxy với session provider). */
+    baseUrl: string;
+    fetch?: Fetch;
+    headers?: HeadersInput | (() => HeadersInput | Promise<HeadersInput>);
+    timeoutMs?: number;
+    paths?: Partial<{
+        register: string;
+        heartbeat: string;
+    }>;
+    /**
+     * Nhận envelope `data` thô sau khi transport validate xong. Validator phía
+     * dưới drop field ngoài contract (deviceToken/pairing/claimed/ownerName của
+     * đường first-party) — app device-streamer đọc chúng qua hook này; contract
+     * partner cũ không đổi.
+     */
+    onData?: (endpoint: "register" | "heartbeat", data: Record<string, unknown>) => void;
+}
+/** Transport HTTP cho DeviceAgent — mirror createHttpSessionProvider. */
+declare function createHttpDeviceAgentTransport(options: HttpDeviceAgentTransportOptions): DeviceAgentTransport;
+
+/**
+ * TournamentController — "chế độ giải đấu" cho điện thoại camera đặt tại sân.
+ *
+ * Vận hành arm máy MỘT lần khi setup giải: controller giữ đúng một phiên
+ * standby gắn sân (metadata.courtRef) đậu trong phòng LiveKit cả ngày ($0
+ * egress). Backend đậu phiên vào bảng courts (bindStandbySession) để REST
+ * match-start của đối tác tiêu thụ: trọng tài bấm start → server claim phiên +
+ * flip live + lệnh "start" qua data channel — không ai chạm điện thoại.
+ *
+ * Khi phiên kết thúc VÌ BẤT KỲ LÝ DO GÌ (match-end, standby_timeout 15 phút,
+ * watchdog, rớt mạng, app khởi động lại) controller tự re-arm phiên standby
+ * mới cho cùng sân sau vài giây — một state machine duy nhất xử lý trận nối
+ * trận, reboot và hồi phục lỗi.
+ */
+
+/** Góc nhìn tối thiểu lên engine — test truyền fake object thường. */
+interface TournamentEngineView {
+    getSnapshot(): {
+        state: string;
+        sessionId: string | null;
+    };
+    subscribe(listener: () => void): () => void;
+    prepare(): Promise<void>;
+    start(input: {
+        externalSessionId: string;
+        title: string;
+        visibility?: "public" | "private";
+        consentVersion: string;
+        metadata?: Record<string, string>;
+    }, options?: {
+        autoPublish?: boolean;
+    }): Promise<void>;
+    stop(reason: "user" | "error"): Promise<void>;
+}
+interface TournamentPersistedState {
+    courtRef: string;
+}
+/** Persist trạng thái armed (AsyncStorage/SQLite tuỳ app) — reboot tự re-arm. */
+interface TournamentStorage {
+    load(): Promise<TournamentPersistedState | null>;
+    save(state: TournamentPersistedState | null): Promise<void>;
+}
+type TournamentPhase = "disarmed" | "arming" | "standby" | "live" | "retry_wait";
+interface TournamentState {
+    armed: boolean;
+    courtRef: string | null;
+    phase: TournamentPhase;
+    lastError: string | null;
+}
+interface TournamentStandbyStart {
+    consentVersion: string;
+    /** Tiêu đề phiên chờ theo sân — mặc định "{courtRef} — chờ trận". */
+    titleFor?: (courtRef: string) => string;
+    visibility?: "public" | "private";
+    metadata?: Record<string, string>;
+}
+interface TournamentControllerOptions {
+    engine: TournamentEngineView | LivestreamEngine;
+    standbyStart: TournamentStandbyStart;
+    storage?: TournamentStorage;
+    onStateChange?: (state: TournamentState) => void;
+    /** Backoff re-arm khi lỗi liên tiếp (test truyền giá trị nhỏ). */
+    rearmBaseDelayMs?: number;
+    rearmMaxDelayMs?: number;
+    /**
+     * Thời gian NHƯỜNG cho engine tự cứu phiên khi nó ở "error" mà còn sessionId.
+     * Phải dài hơn reconnectTimeoutMs của engine (mặc định 30s) để engine kịp
+     * hoặc hồi, hoặc tự cắt bằng network_timeout, trước khi controller can thiệp.
+     */
+    recoveryGraceMs?: number;
+    now?: () => number;
+}
+declare class TournamentController {
+    private readonly options;
+    private readonly engine;
+    private armed;
+    private courtRef;
+    private lastError;
+    private attemptInFlight;
+    private retryAttempt;
+    private retryTimer;
+    /** Mốc hết nhường cho engine tự cứu phiên; null = đang không trong pha đó. */
+    private recoveryDeadline;
+    private unsubscribe;
+    private disposed;
+    /** Tăng mỗi lần arm/disarm — huỷ attempt cũ đang chạy dở. */
+    private armGeneration;
+    constructor(options: TournamentControllerOptions);
+    getState(): TournamentState;
+    /** Khôi phục sau khi app mở lại (reboot giữa giải) — gọi sau engine.initialize(). */
+    restore(): Promise<void>;
+    arm(courtRef: string): Promise<void>;
+    /**
+     * Tắt chế độ giải đấu. Phiên standby đang chờ được nhả (stop); phiên đang
+     * LIVE là trận do đối tác điều khiển — không cắt, chỉ ngừng re-arm.
+     */
+    disarm(): Promise<void>;
+    dispose(): void;
+    private emit;
+    private clearRetry;
+    /** Engine còn đang tự cứu CHÍNH phiên này → nhường, đừng cắt để arm phiên mới. */
+    private isEngineRecovering;
+    private scheduleRecoveryCheck;
+    private handleEngineChange;
+    private scheduleRearm;
+    private ensureStandby;
+}
+
+/**
+ * Kênh điều khiển realtime mặc định: Convex websocket subscribe các function
+ * deviceControl (auth bằng connect-token nhận qua heartbeat — thiết bị không
+ * có account, pattern pairingCode). Chỉ mở khi dashboard yêu cầu "Kết nối",
+ * đóng ngay khi kênh kết thúc → không giữ websocket lúc idle.
+ */
+declare function createConvexControlChannel(convexUrl: string): DeviceControlChannel;
+
+interface ConvexBeatOptions {
+    /** deviceToken hiện tại (đọc mỗi nhịp — token có thể vừa được cấp/đổi). */
+    getDeviceToken: () => string | null | undefined;
+    /**
+     * Cùng hook với createHttpDeviceAgentTransport.onData: đường WS phải đổ
+     * envelope y hệt để handleTransportData (claim/pairing/assignedCourt/
+     * activeSession/preview) không phân biệt beat đến từ đường nào.
+     */
+    onData?: (endpoint: "heartbeat", data: Record<string, unknown>) => void;
+    timeoutMs?: number;
+    /** Test hook. */
+    now?: () => number;
+}
+declare function withConvexBeat(base: DeviceAgentTransport, realtime: ConvexDeviceRealtime, options: ConvexBeatOptions): DeviceAgentTransport;
+
+/**
+ * Bật device-agent: đăng ký thiết bị + heartbeat presence khi app mở, nhận
+ * lệnh start/stop livestream từ dashboard qua kênh điều khiển on-demand.
+ * Render bên trong PickleballLiveProvider (thường là child đầu tiên).
+ * Tách khỏi provider để app không dùng tính năng này không bundle convex.
+ */
+interface PickleballDeviceAgentProps {
+    transport: DeviceAgentTransport;
+    remoteStart: RemoteStartConfig;
+    deviceInfo?: DeviceAgentDeviceInfo;
+    onRemoteSessionStarted?: (sessionId: string) => void;
+    createControlChannel?: (convexUrl: string) => DeviceControlChannel;
+    /** Field bổ sung cho heartbeat (VD recentExits) — đọc qua ref nên đổi hàm không dựng lại agent. */
+    heartbeatExtras?: () => DeviceHeartbeatExtras | undefined;
+    /**
+     * Sức khoẻ kênh MQTT của app — nguồn để agent giãn nhịp beat khi kênh khoẻ
+     * VÀ server bật rollout. Bỏ trống = agent giữ nhịp cũ.
+     */
+    mqttHealth?: () => MqttBeatHealth | null;
+}
+declare function PickleballDeviceAgent(props: PickleballDeviceAgentProps): null;
+
+/**
+ * Kênh MQTT của máy camera — vòng đời kết nối trên WebSocket.
+ *
+ * Vai trò trong kiến trúc: đây là "device plane". Presence do broker phát hiện
+ * ở tầng TCP (LWT) chứ không phải do server đoán từ nhịp heartbeat, nên máy
+ * chết được biết trong ~45s, và biết TỨC THÌ khi app đóng kết nối sạch. Lệnh
+ * start/stop cũng đi đường này; Convex websocket + poll 30s vẫn giữ nguyên làm
+ * lưới an toàn (broker sập không được giết match-start).
+ *
+ * Module này KHÔNG import `@pickleball/shared`: hợp đồng topic/ngưỡng do phía
+ * app truyền vào. Lý do là gói SDK này được publish ra npm và Metro đọc thẳng
+ * `src/`, nên một import workspace ở đây sẽ vỡ khi app ngoài repo cài gói.
+ * Nguồn duy nhất của hợp đồng vẫn là `packages/shared/src/realtime.ts` — chỉ
+ * khác là chỗ nối dây nằm ở app first-party.
+ */
+/** Bề mặt WebSocket tối thiểu mà kênh cần — đủ để test thay bằng đồ giả. */
+interface MqttSocket {
+    binaryType: string;
+    send(data: ArrayBufferView | ArrayBuffer): void;
+    close(): void;
+    onopen: (() => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    onclose: ((event: {
+        code?: number;
+    }) => void) | null;
+}
+interface MqttChannelOptions {
+    /** wss://mqtt.cabinvn.com/mqtt */
+    url: string;
+    deviceId: string;
+    /** Token bền của máy — broker chuyển thẳng cho auth-hook Convex. */
+    deviceToken: string;
+    topics: {
+        status: string;
+        cmd: string;
+        cfg: string;
+        evt: string;
+        score: string;
+    };
+    /** Payload retained lúc kết nối + payload LWT lúc rớt. */
+    statusPayload: (online: boolean) => string;
+    keepaliveS: number;
+    /** Thang backoff (ms); phần tử cuối được lặp lại mãi. */
+    reconnectDelaysMs: readonly number[];
+    onMessage?: (topic: string, payload: string) => void;
+    onConnectionChange?: (connected: boolean) => void;
+    /** Auth bị từ chối (token thu hồi / máy chưa claim) — để app log/khai báo. */
+    onAuthRejected?: (reason: string) => void;
+}
+interface MqttChannelDeps {
+    createSocket?: (url: string, protocols: string[]) => MqttSocket;
+    setTimeout?: (fn: () => void, ms: number) => unknown;
+    clearTimeout?: (handle: unknown) => void;
+    now?: () => number;
+    /** Jitter ±20% chống bão reconnect đồng loạt sau khi broker restart. */
+    random?: () => number;
+}
+/**
+ * Sức khoẻ kênh cho quyết định giãn nhịp beat. `isConnected()` KHÔNG đủ: nối
+ * được mà chưa SUBACK thì máy không nghe được lệnh nào, còn TCP mở mà broker
+ * chết thì `connected` vẫn true tới tận keepalive kế.
+ */
+interface MqttChannelHealth {
+    connected: boolean;
+    subscribed: boolean;
+    lastInboundAt: number;
+    healthySince: number;
+}
+interface MqttChannel {
+    start(): void;
+    /** Đóng CHỦ ĐỘNG: gửi DISCONNECT nên broker KHÔNG bắn LWT. */
+    stop(): void;
+    isConnected(): boolean;
+    health(): MqttChannelHealth;
+    publish(topic: string, payload: string, opts?: {
+        qos?: 0 | 1;
+        retain?: boolean;
+    }): boolean;
+}
+declare function createMqttChannel(o: MqttChannelOptions, deps?: MqttChannelDeps): MqttChannel;
+
+export { BEAT_FAST_MS, BEAT_SLOW_MS, type ConvexBeatOptions, ConvexDeviceRealtime, DeviceAgent, type DeviceAgentDeviceInfo, type DeviceAgentOptions, type DeviceAgentTransport, type DeviceCommand, type DeviceControlChannel, type DeviceControlSessionGrant, type DeviceHeartbeatBody, type DeviceHeartbeatExtras, type DeviceProcessExit, type HttpDeviceAgentTransportOptions, type MqttBeatHealth, type MqttChannel, type MqttChannelDeps, type MqttChannelHealth, type MqttChannelOptions, type MqttSocket, PickleballDeviceAgent, type PickleballDeviceAgentProps, type RemoteStartConfig, TournamentController, type TournamentControllerOptions, type TournamentEngineView, type TournamentPersistedState, type TournamentPhase, type TournamentStandbyStart, type TournamentState, type TournamentStorage, createConvexControlChannel, createHttpDeviceAgentTransport, createMqttChannel, metricsCrossedThreshold, mqttBeatHealthy, nextBeatDelayMs, withConvexBeat };