@pickleball/expo-sdk 0.2.0 → 1.0.0

package/src/camera-grant-provider.ts

@@ -0,0 +1,392 @@
+import type {
+  CameraGrant,
+  EndLivestreamInput,
+  SdkBootstrap,
+  SdkRemoteConfig,
+  SdkSessionGrant,
+  SdkSessionRefresh,
+  StartLivestreamInput,
+} from "./contracts";
+import type { SdkStorage } from "./engine";
+import {
+  InvalidResponseError,
+  SessionConflictError,
+  TokenExpiredError,
+  errorFromCode,
+} from "./errors";
+import { createDefaultStorage } from "./native-runtime";
+import { classifyResumeStatus, resumeGrantMatches } from "./resume-policy";
+import type { ResumableSessionProvider, ResumeAttempt } from "./resume";
+import {
+  createJsonPoster,
+  httpStatusOf,
+  isCameraGrant,
+  isRecord,
+  isSessionStatus,
+  sessionApiBaseFromTelemetryEndpoint,
+  type Fetch,
+} from "./session-grant";
+import { PICKLEBALL_EXPO_SDK_VERSION } from "./version";
+
+/**
+ * Session provider cho ĐIỆN THOẠI ĐỐI TÁC (camera grant, ADR-0002).
+ *
+ *   App đối tác ──(auth riêng)──► Backend đối tác ──khoá API (chỉ server)──► PickLive REST v1
+ *   App đối tác ◄───────── CameraGrant nguyên trạng ◄──────────
+ *   SDK ──Bearer grant.telemetry.token──► PickLive /api/v2/camera/sessions/{id}/*
+ *
+ * App KHÔNG cầm API key, KHÔNG cấu hình URL PickLive: mọi endpoint suy từ
+ * `telemetry.endpoint` trong grant. Backend đối tác chỉ có đúng một việc — cấp grant.
+ *
+ * Handle phiên `{sessionId, base, token}` được LƯU trong sandbox app (expo-sqlite
+ * localStorage) duy nhất để nhận lại phiên sau khi app bị kill; token khoá theo
+ * một phiên và tự hết hạn. Đây là thay đổi so với lời hứa "token chỉ ở bộ nhớ"
+ * của mô hình proxy cũ — chủ ý, để resume hoạt động.
+ */
+
+export const CAMERA_GRANT_STORAGE_KEY = "@pickleball/expo-sdk/camera-grant";
+
+/** Config local cho bước prepare (engine chỉ dùng enabled/minSdkVersion/videoQuality ở đây). */
+export const DEFAULT_LOCAL_CONFIG: SdkRemoteConfig = {
+  enabled: true,
+  protocolVersion: 1,
+  minSdkVersion: "0.0.0",
+  recommendedSdkVersion: PICKLEBALL_EXPO_SDK_VERSION,
+  videoQuality: 720,
+  reconnectTimeoutMs: 30_000,
+  backgroundGraceMs: 90_000,
+  telemetryIntervalMs: 60_000,
+  maxSessionDurationMs: 6 * 60 * 60_000,
+};
+
+export type CameraGrantPhase = "start" | "refresh" | "resume";
+
+export interface CameraGrantProviderOptions {
+  /**
+   * App đối tác gọi backend đối tác → backend gọi PickLive → trả grant nguyên
+   * trạng. Nhận StartLivestreamInput của engine (kèm `standby`, `quality`) để
+   * backend chuyển tiếp title/quality nếu muốn.
+   */
+  requestGrant(input: StartLivestreamInput): Promise<unknown>;
+  storage?: SdkStorage;
+  storageKey?: string;
+  fetch?: Fetch;
+  timeoutMs?: number;
+  /** Ghi đè config local của bước prepare (VD videoQuality theo cài đặt máy). */
+  localConfig?: Partial<SdkRemoteConfig>;
+  onGrant?(grant: CameraGrant, phase: CameraGrantPhase): void;
+}
+
+export interface CameraGrantHandle {
+  sessionId: string;
+  base: string;
+  token: string;
+  tokenExpiresAt: number;
+  quality?: 720 | 1080;
+  savedAt: number;
+}
+
+export interface CameraGrantProvider extends ResumableSessionProvider {
+  /** Grant đang cầm (null khi chưa có phiên). */
+  getActiveGrant(): CameraGrant | null;
+  subscribe(listener: () => void): () => void;
+  /** Có handle phiên trên đĩa → truyền vào `keepSessionOnRestart` của provider. */
+  hasResumableSession(): Promise<boolean>;
+  /** Quên phiên (logout/đổi user). Backend đối tác nên gọi end phiên đó. */
+  clearStoredSession(): Promise<void>;
+}
+
+function parseHandle(raw: string | null): CameraGrantHandle | null {
+  if (!raw) return null;
+  try {
+    const value = JSON.parse(raw) as unknown;
+    if (
+      !isRecord(value) ||
+      typeof value.sessionId !== "string" ||
+      typeof value.base !== "string" ||
+      typeof value.token !== "string" ||
+      typeof value.tokenExpiresAt !== "number"
+    ) {
+      return null;
+    }
+    return {
+      sessionId: value.sessionId,
+      base: value.base,
+      token: value.token,
+      tokenExpiresAt: value.tokenExpiresAt,
+      ...(value.quality === 720 || value.quality === 1080 ? { quality: value.quality } : {}),
+      savedAt: typeof value.savedAt === "number" ? value.savedAt : 0,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function withStatus(error: unknown): unknown {
+  // 401 từ namespace camera = grant hết hạn/không hợp lệ → engine đi vòng refresh.
+  if (httpStatusOf(error) === 401) {
+    return Object.assign(new TokenExpiredError(), { httpStatus: 401 });
+  }
+  return error;
+}
+
+export function createCameraGrantProvider(
+  options: CameraGrantProviderOptions,
+): CameraGrantProvider {
+  const storage = options.storage ?? createDefaultStorage();
+  const storageKey = options.storageKey ?? CAMERA_GRANT_STORAGE_KEY;
+  const post = createJsonPoster({ fetch: options.fetch, timeoutMs: options.timeoutMs });
+  const listeners = new Set<() => void>();
+
+  let handle: CameraGrantHandle | null = null;
+  let handleLoaded: Promise<void> | null = null;
+  let activeGrant: CameraGrant | null = null;
+  let pendingResume: SdkSessionGrant | null = null;
+
+  const emit = () => {
+    for (const listener of listeners) listener();
+  };
+
+  async function loadHandle() {
+    if (!handleLoaded) {
+      handleLoaded = storage
+        .getItem(storageKey)
+        .then((raw) => {
+          if (handle === null) handle = parseHandle(raw);
+        })
+        .catch(() => undefined);
+    }
+    await handleLoaded;
+  }
+
+  async function saveHandle(next: CameraGrantHandle | null) {
+    handle = next;
+    try {
+      if (next) await storage.setItem(storageKey, JSON.stringify(next));
+      else await storage.removeItem(storageKey);
+    } catch {
+      // Đĩa hỏng thì mất resume, không được chặn phiên đang chạy.
+    }
+  }
+
+  function setActive(grant: CameraGrant | null) {
+    activeGrant = grant;
+    emit();
+  }
+
+  async function adopt(grant: CameraGrant, quality: 720 | 1080 | undefined) {
+    const base = sessionApiBaseFromTelemetryEndpoint(grant.telemetry.endpoint);
+    await saveHandle({
+      sessionId: grant.sessionId,
+      base,
+      token: grant.telemetry.token,
+      tokenExpiresAt: grant.telemetry.expiresAt,
+      ...(quality !== undefined ? { quality } : handle?.quality !== undefined ? { quality: handle.quality } : {}),
+      savedAt: Date.now(),
+    });
+    setActive(grant);
+  }
+
+  function requireHandle(sessionId: string): CameraGrantHandle {
+    if (!handle || handle.sessionId !== sessionId) {
+      // 404 để engine dừng quay số thay vì thử lại vô ích (engine bám mã HTTP).
+      throw Object.assign(
+        new SessionConflictError("No camera grant is held for this session"),
+        { httpStatus: 404 },
+      );
+    }
+    return handle;
+  }
+
+  function bearer(current: CameraGrantHandle) {
+    return { Authorization: `Bearer ${current.token}` };
+  }
+
+  async function call(current: CameraGrantHandle, action: string, body: unknown) {
+    try {
+      return await post(`${current.base}/${action}`, body, bearer(current));
+    } catch (error) {
+      throw withStatus(error);
+    }
+  }
+
+  const provider: CameraGrantProvider = {
+    async bootstrap(): Promise<SdkBootstrap> {
+      await loadHandle();
+      return {
+        config: { ...DEFAULT_LOCAL_CONFIG, ...options.localConfig },
+        serverTime: Date.now(),
+        rolloutEnabled: true,
+      };
+    },
+
+    async start(input: StartLivestreamInput): Promise<SdkSessionGrant> {
+      await loadHandle();
+      const resumeGrant = pendingResume;
+      if (resumeGrant && resumeGrantMatches(input.externalSessionId, resumeGrant.sessionId)) {
+        pendingResume = null;
+        return resumeGrant;
+      }
+      const raw = await options.requestGrant(input);
+      if (!isCameraGrant(raw)) {
+        throw new InvalidResponseError("The partner backend returned an invalid camera grant");
+      }
+      await adopt(raw, input.quality);
+      // engine.start({autoPublish:true}) KHÔNG gọi provider.publish (chỉ
+      // startPublishing từ standby mới gọi) — server phải được lật live TRƯỚC khi
+      // app đẩy RTMP, giống thứ tự start không-standby của proxy cũ.
+      if (input.standby !== true && raw.status !== "live") {
+        const current = requireHandle(raw.sessionId);
+        try {
+          const data = await call(current, "publish", {
+            sessionId: raw.sessionId,
+            ...(input.quality !== undefined ? { quality: input.quality } : {}),
+          });
+          if (!isSessionStatus(data)) throw new InvalidResponseError();
+        } catch (error) {
+          // Engine chỉ nhận grant SAU khi start() resolve, nên publish hỏng ở đây
+          // là không ai end phiên này giúp: phiên treo trên server (đối tác đã
+          // tạo) và handle trên đĩa báo "còn phiên để nhận lại" cho một phiên
+          // chưa từng phát. Kết thúc best-effort rồi dọn handle; app xin grant
+          // mới khi user bấm lại.
+          await call(current, "end", { sessionId: raw.sessionId, reason: "error" }).catch(
+            () => undefined,
+          );
+          await saveHandle(null);
+          setActive(null);
+          throw error;
+        }
+        setActive({ ...raw, status: "live" });
+      }
+      options.onGrant?.(activeGrant ?? raw, "start");
+      return raw;
+    },
+
+    async refresh(sessionId: string): Promise<SdkSessionRefresh> {
+      await loadHandle();
+      const current = requireHandle(sessionId);
+      const data = await call(current, "refresh", {});
+      if (!isCameraGrant(data)) throw new InvalidResponseError();
+      // Ghi đĩa TRƯỚC khi trả: nhịp poll kế đọc token mới từ grant của engine, mà
+      // engine chỉ cập nhật sau khi promise này resolve.
+      await adopt(data, current.quality);
+      options.onGrant?.(data, "refresh");
+      return {
+        participantToken: data.participantToken,
+        tokenExpiresAt: data.tokenExpiresAt,
+        telemetry: data.telemetry,
+        config: data.config,
+      };
+    },
+
+    async end(input: EndLivestreamInput): Promise<void> {
+      await loadHandle();
+      if (!handle || handle.sessionId !== input.sessionId) {
+        // Không cầm grant của phiên đó → coi như đã xong. Ném ở đây là khoá
+        // engine vĩnh viễn ở "Another livestream session is still active".
+        return;
+      }
+      const current = handle;
+      // Bearer đã hết hạn thì KHÔNG có request nào của mình được server nhận
+      // nữa (401 mãi) — và engine chỉ coi 404 là "phiên biến mất", còn lại giữ
+      // dấu pending-end và ném "The previous livestream is still pending end"
+      // ở mọi lượt start sau: máy không bao giờ phát lại được. Token chết là
+      // phiên đó không còn của mình: dọn handle, để lưới server dọn phiên.
+      if (current.tokenExpiresAt <= Date.now()) {
+        await saveHandle(null);
+        setActive(null);
+        return;
+      }
+      try {
+        await call(current, "end", { sessionId: input.sessionId, reason: input.reason });
+      } catch (error) {
+        const status = httpStatusOf(error);
+        // 404/410: phiên biến mất; 409: đã kết thúc hoặc grant bị thay — ở cả ba ca
+        // phiên này không còn là của mình, dọn handle để app arm phiên mới được.
+        if (status !== 404 && status !== 409 && status !== 410) throw error;
+      }
+      await saveHandle(null);
+      setActive(null);
+    },
+
+    async publish(sessionId: string): Promise<void> {
+      await loadHandle();
+      const current = requireHandle(sessionId);
+      const data = await call(current, "publish", {
+        sessionId,
+        ...(current.quality !== undefined ? { quality: current.quality } : {}),
+      });
+      if (!isSessionStatus(data)) throw new InvalidResponseError();
+      if (activeGrant) setActive({ ...activeGrant, status: "live" });
+    },
+
+    async unpublish(sessionId: string): Promise<void> {
+      await loadHandle();
+      const current = requireHandle(sessionId);
+      const data = await call(current, "unpublish", { sessionId });
+      if (!isSessionStatus(data)) throw new InvalidResponseError();
+      if (activeGrant) setActive({ ...activeGrant, status: "scheduled" });
+    },
+
+    adoptResumeGrant(grant: SdkSessionGrant) {
+      pendingResume = grant;
+    },
+
+    async resume(sessionId: string): Promise<ResumeAttempt> {
+      await loadHandle();
+      if (!handle || handle.sessionId !== sessionId) return { kind: "gone" };
+      const current = handle;
+      // Token hết hạn không bao giờ xin được token kế: "retry" ở đây là vòng
+      // lặp vô hạn chặn luôn cả việc arm phiên mới (resumeBlocksArm). Phiên đó
+      // đã bị lưới server dọn từ lâu (no-publisher 1h) — coi là gone.
+      if (current.tokenExpiresAt <= Date.now()) {
+        await saveHandle(null);
+        return { kind: "gone" };
+      }
+      let data: unknown;
+      try {
+        data = await post(`${current.base}/refresh`, {}, bearer(current));
+      } catch (error) {
+        const status = httpStatusOf(error);
+        if (status === undefined) return { kind: "retry" };
+        const verdict = classifyResumeStatus(status);
+        return { kind: verdict === "ok" ? "retry" : verdict };
+      }
+      if (!isCameraGrant(data)) return { kind: "retry" };
+      await adopt(data, current.quality);
+      options.onGrant?.(data, "resume");
+      return { kind: "grant", grant: data, live: data.status === "live" };
+    },
+
+    getActiveGrant: () => activeGrant,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    async hasResumableSession() {
+      await loadHandle();
+      return handle !== null;
+    },
+    async clearStoredSession() {
+      pendingResume = null;
+      await saveHandle(null);
+      setActive(null);
+    },
+  };
+  return provider;
+}
+
+/** Grant hiện hành của provider, theo dõi bằng useSyncExternalStore. */
+export function useCameraGrant(provider: CameraGrantProvider): CameraGrant | null {
+  // Import lười để module này không kéo React vào môi trường không có React.
+  const React = require("react") as typeof import("react");
+  return React.useSyncExternalStore(
+    provider.subscribe,
+    provider.getActiveGrant,
+    provider.getActiveGrant,
+  );
+}
+
+export { errorFromCode as cameraGrantErrorFromCode };

package/src/camera-settings.ts

@@ -0,0 +1,133 @@
+import { useSyncExternalStore } from "react";
+import type { RoomAdapter, SdkStorage } from "./engine";
+import { createDefaultStorage, createRtmpRoomFactory } from "./native-runtime";
+
+/**
+ * Cấu hình camera LOCAL — không phụ thuộc server, sống qua OTA (chuyển từ
+ * apps/device-streamer/src/local-config.ts). Resolution override videoQuality
+ * qua withLocalVideoQuality; fps + cameraId đi vào createRtmpRoomFactory. Đổi
+ * resolution/fps/cameraId → remount provider (dùng cameraSettingsKey làm `key`)
+ * để engine re-prepare.
+ */
+
+export type AntiFlickerMode = "auto" | "50hz" | "60hz";
+
+export interface CameraSettings {
+  resolution: 720 | 1080;
+  /** 60 chỉ chọn được khi capabilities của lens đang gắn báo hỗ trợ. */
+  fps: 24 | 30 | 60;
+  /**
+   * Chống chớp đèn. Mặc định "50hz" (lưới điện VN) chứ KHÔNG phải "auto": để
+   * auto là giao cho HAL đoán tần số, HyperOS đoán trật 60Hz thường xuyên → đèn
+   * LED trong nhà vằn trên sóng. Android-only hiện tại.
+   */
+  antiFlicker: AntiFlickerMode;
+  /**
+   * Camera mặc định mỗi lần mở app. null = camera sau mặc định của native. Cần
+   * vì máy thật có nhiều camera trùng nhãn (Redmi Note 15: hai "Back Camera").
+   */
+  cameraId: string | null;
+}
+
+export const CAMERA_SETTINGS_STORAGE_KEY = "@pickleball/expo-sdk/camera-settings";
+
+export const DEFAULT_CAMERA_SETTINGS: CameraSettings = Object.freeze({
+  resolution: 720,
+  fps: 30,
+  antiFlicker: "50hz",
+  cameraId: null,
+});
+
+/** Parse thuần — giá trị lạ/thiếu rơi về mặc định (config cũ chưa có field vẫn đọc được). */
+export function parseCameraSettings(
+  raw: string | null,
+  defaults: CameraSettings = DEFAULT_CAMERA_SETTINGS,
+): CameraSettings {
+  if (!raw) return { ...defaults };
+  try {
+    const parsed = JSON.parse(raw) as Partial<CameraSettings> | null;
+    if (parsed === null || typeof parsed !== "object") return { ...defaults };
+    return {
+      resolution: parsed.resolution === 1080 ? 1080 : parsed.resolution === 720 ? 720 : defaults.resolution,
+      fps:
+        parsed.fps === 24 || parsed.fps === 30 || parsed.fps === 60 ? parsed.fps : defaults.fps,
+      antiFlicker:
+        parsed.antiFlicker === "auto" || parsed.antiFlicker === "60hz" || parsed.antiFlicker === "50hz"
+          ? parsed.antiFlicker
+          : defaults.antiFlicker,
+      cameraId: typeof parsed.cameraId === "string" ? parsed.cameraId : null,
+    };
+  } catch {
+    return { ...defaults };
+  }
+}
+
+export interface CameraSettingsStore {
+  readonly key: string;
+  get(): CameraSettings;
+  set(patch: Partial<CameraSettings>): void;
+  subscribe(listener: () => void): () => void;
+  /** Nạp từ đĩa; gọi một lần lúc app khởi động. */
+  restore(): Promise<void>;
+  isRestored(): boolean;
+}
+
+export interface CameraSettingsStoreOptions {
+  storage?: SdkStorage;
+  /** Khoá lưu — app fleet giữ khoá cũ để setting sống qua OTA. */
+  key?: string;
+  defaults?: Partial<CameraSettings>;
+}
+
+export function createCameraSettingsStore(
+  options: CameraSettingsStoreOptions = {},
+): CameraSettingsStore {
+  const storage = options.storage ?? createDefaultStorage();
+  const key = options.key ?? CAMERA_SETTINGS_STORAGE_KEY;
+  const defaults: CameraSettings = { ...DEFAULT_CAMERA_SETTINGS, ...options.defaults };
+  let settings: CameraSettings = { ...defaults };
+  let restored = false;
+  const listeners = new Set<() => void>();
+  const emit = () => {
+    for (const listener of listeners) listener();
+  };
+  return {
+    key,
+    get: () => settings,
+    set(patch) {
+      settings = { ...settings, ...patch };
+      void storage.setItem(key, JSON.stringify(settings)).catch(() => undefined);
+      emit();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    async restore() {
+      const raw = await storage.getItem(key).catch(() => null);
+      settings = parseCameraSettings(raw, defaults);
+      restored = true;
+      emit();
+    },
+    isRestored: () => restored,
+  };
+}
+
+export function useCameraSettings(store: CameraSettingsStore): CameraSettings {
+  return useSyncExternalStore(store.subscribe, store.get, store.get);
+}
+
+/** `key` cho PickleballLiveProvider: đổi giá trị → remount → engine re-prepare đúng cấu hình. */
+export function cameraSettingsKey(settings: CameraSettings): string {
+  return `${settings.resolution}:${settings.fps}:${settings.cameraId ?? "default"}`;
+}
+
+/** roomFactory RTMP theo cấu hình (fps + camera mặc định). */
+export function rtmpRoomFactoryFor(settings: CameraSettings): () => RoomAdapter {
+  return createRtmpRoomFactory({
+    frameRate: settings.fps,
+    ...(settings.cameraId ? { cameraId: settings.cameraId } : {}),
+  });
+}

package/src/contracts.ts

@@ -22,9 +22,23 @@ export type SdkErrorCode =
   | "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.
+ */
+export type SdkConflictReason = "superseded" | "ended" | "expired";
+
 export 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;
 }
 
 export interface BootstrapInput {
@@ -67,6 +81,14 @@ export 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;
 }
 
 export interface SdkTelemetryCredentials {
@@ -92,6 +114,38 @@ export interface SdkSessionRefresh {
   config: SdkRemoteConfig;
 }
 
+export 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.
+ */
+export 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;
+}
+
 export interface EndLivestreamInput {
   sessionId: string;
   reason:
@@ -123,6 +177,25 @@ export interface SdkTelemetryEvent {
   data?: Record<string, unknown>;
 }
 
+/** Lệnh điều khiển phiên giao qua kênh poll (mode device-rtmp). */
+export type SessionCommandAction = "start" | "stop" | "end";
+
+export 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;
+}
+
+export 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";
+}
+
 export interface LivestreamSessionProvider {
   bootstrap(input: BootstrapInput): Promise<SdkBootstrap>;
   start(input: StartLivestreamInput): Promise<SdkSessionGrant>;