@pickleball/expo-sdk 0.1.1 → 0.2.0

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

@@ -0,0 +1,157 @@
+import { Q as LivestreamEngine, B as BootstrapInput, D as DeviceMetricsSample } from '../engine-CCSSqPbZ.js';
+
+/**
+ * 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";
+    payload: {
+        title?: string;
+        visibility?: "public" | "private";
+    };
+    expiresAt: number;
+}
+interface DeviceControlSessionGrant {
+    id: string;
+    token: string;
+    convexUrl: string;
+}
+interface DeviceHeartbeatBody {
+    agentState?: string;
+    currentSessionId?: string | null;
+    appVersion?: string;
+    metrics?: Record<string, number | string>;
+}
+interface DeviceAgentTransport {
+    register(input: BootstrapInput & DeviceAgentDeviceInfo): Promise<{
+        deviceId: string;
+        heartbeatIntervalMs: number;
+    }>;
+    heartbeat(input: BootstrapInput & DeviceHeartbeatBody): Promise<{
+        controlSession: DeviceControlSessionGrant | null;
+    }>;
+}
+/** 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>;
+    /** 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;
+}
+declare class DeviceAgent {
+    private readonly options;
+    private running;
+    private registered;
+    private foreground;
+    private heartbeatIntervalMs;
+    private timer;
+    private beatInFlight;
+    private registerAttempt;
+    private unsubscribeAppState;
+    private heartbeatFailures;
+    private controlChannel;
+    private controlSessionId;
+    private controlUnsubscribers;
+    private executing;
+    private readonly handledCommandIds;
+    constructor(options: DeviceAgentOptions);
+    start(): void;
+    stop(): void;
+    private handleAppState;
+    private schedule;
+    private beat;
+    private register;
+    private heartbeat;
+    private openControlChannel;
+    private closeControlChannel;
+    private executeCommands;
+    private executeCommand;
+    private runStartLivestream;
+    private runStopLivestream;
+    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;
+    }>;
+}
+/** Transport HTTP cho DeviceAgent — mirror createHttpSessionProvider. */
+declare function createHttpDeviceAgentTransport(options: HttpDeviceAgentTransportOptions): DeviceAgentTransport;
+
+/**
+ * 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;
+
+/**
+ * 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;
+}
+declare function PickleballDeviceAgent(props: PickleballDeviceAgentProps): null;
+
+export { DeviceAgent, type DeviceAgentDeviceInfo, type DeviceAgentOptions, type DeviceAgentTransport, type DeviceCommand, type DeviceControlChannel, type DeviceControlSessionGrant, type DeviceHeartbeatBody, type HttpDeviceAgentTransportOptions, PickleballDeviceAgent, type PickleballDeviceAgentProps, type RemoteStartConfig, createConvexControlChannel, createHttpDeviceAgentTransport };

package/dist/device-agent/index.js

@@ -0,0 +1,498 @@
+import {
+  ExpoSdkConfigurationError,
+  ExpoSdkTimeoutError,
+  InvalidResponseError,
+  NetworkUnavailableError,
+  PickleballExpoError,
+  errorFromCode,
+  normalizeError,
+  useLivestreamHost
+} from "../chunk-FODE2W2H.js";
+import {
+  __esm,
+  __export,
+  __require,
+  __toCommonJS
+} from "../chunk-KFQGP6VL.js";
+
+// src/device-agent/convex-control-channel.ts
+var convex_control_channel_exports = {};
+__export(convex_control_channel_exports, {
+  createConvexControlChannel: () => createConvexControlChannel
+});
+import { ConvexClient } from "convex/browser";
+import { anyApi } from "convex/server";
+function createConvexControlChannel(convexUrl) {
+  const client = new ConvexClient(convexUrl);
+  const deviceControl = anyApi.deviceControl;
+  function toCommands(value) {
+    if (!Array.isArray(value)) return [];
+    const commands = [];
+    for (const item of value) {
+      if (item === null || typeof item !== "object") continue;
+      const record = item;
+      if (typeof record.id !== "string" || record.type !== "start_livestream" && record.type !== "stop_livestream" || typeof record.expiresAt !== "number") {
+        continue;
+      }
+      const payload = record.payload !== null && typeof record.payload === "object" && !Array.isArray(record.payload) ? record.payload : {};
+      commands.push({
+        id: record.id,
+        type: record.type,
+        payload: {
+          ...typeof payload.title === "string" ? { title: payload.title } : {},
+          ...payload.visibility === "public" || payload.visibility === "private" ? { visibility: payload.visibility } : {}
+        },
+        expiresAt: record.expiresAt
+      });
+    }
+    return commands;
+  }
+  return {
+    async attach(controlSessionId, token) {
+      await client.mutation(deviceControl.deviceAttach, { controlSessionId, token });
+    },
+    onCommands(controlSessionId, token, callback) {
+      return client.onUpdate(
+        deviceControl.pendingCommands,
+        { controlSessionId, token },
+        (value) => callback(toCommands(value))
+      );
+    },
+    onState(controlSessionId, token, callback) {
+      return client.onUpdate(
+        deviceControl.controlSessionState,
+        { controlSessionId, token },
+        (value) => {
+          const status = value !== null && typeof value === "object" && typeof value.status === "string" ? value.status : "ended";
+          callback({ status });
+        }
+      );
+    },
+    async ack(input) {
+      await client.mutation(deviceControl.ackCommand, { ...input });
+    },
+    close() {
+      void client.close();
+    }
+  };
+}
+var init_convex_control_channel = __esm({
+  "src/device-agent/convex-control-channel.ts"() {
+    "use strict";
+  }
+});
+
+// src/device-agent/agent.ts
+var DEFAULT_HEARTBEAT_INTERVAL_MS = 12e3;
+var REGISTER_RETRY_BASE_MS = 2e3;
+var REGISTER_RETRY_MAX_MS = 6e4;
+var METRIC_FIELDS = [
+  "ramFreeMb",
+  "ramTotalMb",
+  "storageFreeGb",
+  "batteryPct",
+  "batteryTempC",
+  "thermal",
+  "netType",
+  "linkMbps",
+  "rssi",
+  "connQuality"
+];
+function defaultSubscribeAppState(listener) {
+  const { AppState } = __require("react-native");
+  const subscription = AppState.addEventListener("change", (state) => {
+    listener(
+      state === "active" ? "active" : state === "background" ? "background" : "inactive"
+    );
+  });
+  return () => subscription.remove();
+}
+function defaultCreateControlChannel(convexUrl) {
+  const { createConvexControlChannel: createConvexControlChannel2 } = (init_convex_control_channel(), __toCommonJS(convex_control_channel_exports));
+  return createConvexControlChannel2(convexUrl);
+}
+function pickMetrics(sample) {
+  if (!sample) return void 0;
+  const metrics = {};
+  for (const field of METRIC_FIELDS) {
+    const value = sample[field];
+    if (typeof value === "number" && Number.isFinite(value)) metrics[field] = value;
+    else if (typeof value === "string" && value.trim() !== "") metrics[field] = value;
+  }
+  return Object.keys(metrics).length > 0 ? metrics : void 0;
+}
+var DeviceAgent = class {
+  options;
+  running = false;
+  registered = false;
+  foreground = true;
+  heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS;
+  timer = null;
+  beatInFlight = false;
+  registerAttempt = 0;
+  unsubscribeAppState = null;
+  heartbeatFailures = 0;
+  controlChannel = null;
+  controlSessionId = null;
+  controlUnsubscribers = [];
+  executing = false;
+  handledCommandIds = /* @__PURE__ */ new Set();
+  constructor(options) {
+    this.options = options;
+  }
+  start() {
+    if (this.running) return;
+    this.running = true;
+    this.unsubscribeAppState = (this.options.subscribeAppState ?? defaultSubscribeAppState)((state) => this.handleAppState(state));
+    this.schedule(0);
+  }
+  stop() {
+    this.running = false;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    this.unsubscribeAppState?.();
+    this.unsubscribeAppState = null;
+    this.closeControlChannel();
+  }
+  handleAppState(state) {
+    const wasForeground = this.foreground;
+    this.foreground = state === "active";
+    if (!this.running) return;
+    if (this.foreground && !wasForeground) {
+      this.schedule(0);
+    }
+    if (!this.foreground) {
+      if (this.timer) clearTimeout(this.timer);
+      this.timer = null;
+      this.closeControlChannel();
+    }
+  }
+  schedule(delayMs) {
+    if (!this.running || !this.foreground) return;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => {
+      void this.beat();
+    }, delayMs);
+  }
+  async beat() {
+    if (!this.running || !this.foreground || this.beatInFlight) return;
+    this.beatInFlight = true;
+    try {
+      if (!this.registered) {
+        await this.register();
+        if (!this.registered) return;
+      }
+      await this.heartbeat();
+      this.schedule(this.heartbeatIntervalMs);
+    } finally {
+      this.beatInFlight = false;
+    }
+  }
+  async register() {
+    try {
+      const result = await this.options.transport.register({
+        ...this.options.bootstrapInput,
+        ...this.options.deviceInfo
+      });
+      if (result.heartbeatIntervalMs > 0) {
+        this.heartbeatIntervalMs = result.heartbeatIntervalMs;
+      }
+      this.registered = true;
+      this.registerAttempt = 0;
+    } catch {
+      const delay = Math.min(
+        REGISTER_RETRY_BASE_MS * 2 ** this.registerAttempt,
+        REGISTER_RETRY_MAX_MS
+      );
+      this.registerAttempt += 1;
+      this.schedule(delay);
+    }
+  }
+  async heartbeat() {
+    const snapshot = this.options.engine.getSnapshot();
+    let metrics;
+    try {
+      metrics = pickMetrics(await this.options.deviceMetrics?.() ?? null);
+    } catch {
+      metrics = void 0;
+    }
+    let result;
+    try {
+      result = await this.options.transport.heartbeat({
+        ...this.options.bootstrapInput,
+        agentState: snapshot.state,
+        currentSessionId: snapshot.sessionId,
+        ...this.options.deviceInfo?.appVersion ? { appVersion: this.options.deviceInfo.appVersion } : {},
+        ...metrics ? { metrics } : {}
+      });
+    } catch {
+      this.heartbeatFailures += 1;
+      if (this.heartbeatFailures >= 3) {
+        this.registered = false;
+        this.heartbeatFailures = 0;
+      }
+      return;
+    }
+    this.heartbeatFailures = 0;
+    if (result.controlSession && !this.controlChannel) {
+      this.openControlChannel(result.controlSession);
+    }
+  }
+  openControlChannel(grant) {
+    let channel;
+    try {
+      channel = (this.options.createControlChannel ?? defaultCreateControlChannel)(
+        grant.convexUrl
+      );
+    } catch {
+      return;
+    }
+    this.controlChannel = channel;
+    this.controlSessionId = grant.id;
+    void channel.attach(grant.id, grant.token).then(() => {
+      if (this.controlChannel !== channel) return;
+      this.controlUnsubscribers.push(
+        channel.onCommands(grant.id, grant.token, (commands) => {
+          void this.executeCommands(channel, grant, commands);
+        }),
+        channel.onState(grant.id, grant.token, (state) => {
+          if (state.status === "ended" || state.status === "expired") {
+            this.closeControlChannel();
+          }
+        })
+      );
+    }).catch(() => {
+      if (this.controlChannel === channel) this.closeControlChannel();
+    });
+  }
+  closeControlChannel() {
+    for (const unsubscribe of this.controlUnsubscribers) {
+      try {
+        unsubscribe();
+      } catch {
+      }
+    }
+    this.controlUnsubscribers = [];
+    try {
+      this.controlChannel?.close();
+    } catch {
+    }
+    this.controlChannel = null;
+    this.controlSessionId = null;
+    this.handledCommandIds.clear();
+  }
+  async executeCommands(channel, grant, commands) {
+    for (const command of commands) {
+      if (this.controlChannel !== channel) return;
+      if (this.handledCommandIds.has(command.id)) continue;
+      this.handledCommandIds.add(command.id);
+      if (this.executing) {
+        await this.safeAck(channel, grant, command.id, "failed", "Thi\u1EBFt b\u1ECB \u0111ang b\u1EADn");
+        continue;
+      }
+      this.executing = true;
+      try {
+        await this.executeCommand(channel, grant, command);
+      } finally {
+        this.executing = false;
+      }
+    }
+  }
+  async executeCommand(channel, grant, command) {
+    if (command.expiresAt <= Date.now()) {
+      await this.safeAck(channel, grant, command.id, "failed", "L\u1EC7nh \u0111\xE3 h\u1EBFt h\u1EA1n");
+      return;
+    }
+    await this.safeAck(channel, grant, command.id, "acked");
+    try {
+      if (command.type === "start_livestream") {
+        await this.runStartLivestream(command);
+        const sessionId = this.options.engine.getSnapshot().sessionId;
+        await this.safeAck(
+          channel,
+          grant,
+          command.id,
+          "completed",
+          void 0,
+          sessionId ?? void 0
+        );
+        if (sessionId) this.options.onRemoteSessionStarted?.(sessionId);
+      } else {
+        await this.runStopLivestream();
+        await this.safeAck(channel, grant, command.id, "completed");
+      }
+    } catch (error) {
+      await this.safeAck(
+        channel,
+        grant,
+        command.id,
+        "failed",
+        normalizeError(error).message
+      );
+    }
+  }
+  async runStartLivestream(command) {
+    const engine = this.options.engine;
+    const state = engine.getSnapshot().state;
+    if (state !== "idle" && state !== "ended" && state !== "preview") {
+      throw new Error(`Thi\u1EBFt b\u1ECB kh\xF4ng s\u1EB5n s\xE0ng (tr\u1EA1ng th\xE1i ${state})`);
+    }
+    if (state !== "preview") {
+      await engine.prepare();
+    }
+    const remote = this.options.remoteStart;
+    await engine.start(
+      {
+        externalSessionId: `remote-${command.id}`,
+        title: command.payload.title?.trim() || remote.defaultTitle || "Livestream",
+        visibility: command.payload.visibility ?? remote.visibility ?? "public",
+        consentVersion: remote.consentVersion,
+        metadata: { ...remote.metadata, deviceCommandId: command.id },
+        standby: true
+      },
+      { autoPublish: false }
+    );
+  }
+  async runStopLivestream() {
+    const engine = this.options.engine;
+    if (engine.getSnapshot().sessionId) {
+      await engine.stop("user");
+    }
+  }
+  async safeAck(channel, grant, commandId, status, errorMessage, resultSessionId) {
+    try {
+      await channel.ack({
+        controlSessionId: grant.id,
+        token: grant.token,
+        commandId,
+        status,
+        ...errorMessage !== void 0 ? { errorMessage } : {},
+        ...resultSessionId !== void 0 ? { resultSessionId } : {}
+      });
+    } catch {
+    }
+  }
+};
+
+// src/device-agent/http-transport.ts
+var defaultPaths = {
+  register: "/devices/register",
+  heartbeat: "/devices/heartbeat"
+};
+function createHttpDeviceAgentTransport(options) {
+  const baseUrl = options.baseUrl.replace(/\/+$/, "");
+  if (baseUrl === "") {
+    throw new ExpoSdkConfigurationError("baseUrl must be a non-empty string");
+  }
+  const fetchImplementation = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImplementation !== "function") {
+    throw new ExpoSdkConfigurationError("A Fetch API implementation is required");
+  }
+  const paths = { ...defaultPaths, ...options.paths };
+  async function post(path, body) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 1e4);
+    try {
+      const extraHeaders = typeof options.headers === "function" ? await options.headers() : options.headers ?? {};
+      const response = await fetchImplementation(
+        `${baseUrl}/${path.replace(/^\/+/, "")}`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json", ...extraHeaders },
+          body: JSON.stringify(body),
+          signal: controller.signal,
+          redirect: "error"
+        }
+      );
+      const envelope = await response.json().catch(() => {
+        throw new InvalidResponseError();
+      });
+      if (!response.ok) throw parseProxyError(envelope);
+      if (!isRecord(envelope) || !("data" in envelope)) {
+        throw new InvalidResponseError();
+      }
+      return envelope.data;
+    } catch (error) {
+      if (controller.signal.aborted) throw new ExpoSdkTimeoutError();
+      if (error instanceof PickleballExpoError) throw error;
+      if (error instanceof TypeError) {
+        throw new NetworkUnavailableError(void 0, { cause: error });
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  return {
+    async register(input) {
+      const data = await post(paths.register, input);
+      if (!isRecord(data) || typeof data.deviceId !== "string" || typeof data.heartbeatIntervalMs !== "number" || !Number.isFinite(data.heartbeatIntervalMs)) {
+        throw new InvalidResponseError();
+      }
+      return {
+        deviceId: data.deviceId,
+        heartbeatIntervalMs: data.heartbeatIntervalMs
+      };
+    },
+    async heartbeat(input) {
+      const data = await post(paths.heartbeat, input);
+      if (!isRecord(data)) throw new InvalidResponseError();
+      const grant = data.controlSession;
+      if (grant === null || grant === void 0) return { controlSession: null };
+      if (!isRecord(grant) || typeof grant.id !== "string" || typeof grant.token !== "string" || typeof grant.convexUrl !== "string" || grant.convexUrl === "") {
+        throw new InvalidResponseError();
+      }
+      return {
+        controlSession: {
+          id: grant.id,
+          token: grant.token,
+          convexUrl: grant.convexUrl
+        }
+      };
+    }
+  };
+}
+function parseProxyError(envelope) {
+  if (isRecord(envelope) && isRecord(envelope.error) && typeof envelope.error.code === "string") {
+    return errorFromCode(
+      envelope.error.code,
+      typeof envelope.error.message === "string" ? envelope.error.message : void 0
+    );
+  }
+  return new InvalidResponseError();
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/device-agent/index.ts
+init_convex_control_channel();
+
+// src/device-agent/component.tsx
+import { useEffect, useRef } from "react";
+function PickleballDeviceAgent(props) {
+  const host = useLivestreamHost();
+  const propsRef = useRef(props);
+  propsRef.current = props;
+  useEffect(() => {
+    const agent = new DeviceAgent({
+      engine: host.engine,
+      bootstrapInput: host.bootstrapInput,
+      deviceMetrics: host.deviceMetrics,
+      transport: propsRef.current.transport,
+      remoteStart: propsRef.current.remoteStart,
+      deviceInfo: propsRef.current.deviceInfo,
+      createControlChannel: propsRef.current.createControlChannel,
+      onRemoteSessionStarted: (sessionId) => propsRef.current.onRemoteSessionStarted?.(sessionId)
+    });
+    agent.start();
+    return () => agent.stop();
+  }, [host]);
+  return null;
+}
+export {
+  DeviceAgent,
+  PickleballDeviceAgent,
+  createConvexControlChannel,
+  createHttpDeviceAgentTransport
+};