@pickleball/expo-sdk 0.1.1 → 1.0.0

package/src/device-agent/beat-policy.ts

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ */
+
+export const BEAT_SLOW_MS = 60_000;
+export const BEAT_FAST_MS = 12_000;
+export const MQTT_HEALTHY_SILENCE_MS = 45_000;
+export const MQTT_HEALTHY_HOLD_MS = 120_000;
+
+export interface MqttBeatHealth {
+  connected: boolean;
+  subscribed: boolean;
+  lastInboundAt: number;
+  healthySince: number;
+}
+
+/** Đủ CẢ BỐN vế mới được coi là kênh khoẻ. */
+export function mqttBeatHealthy(h: MqttBeatHealth, now: number): boolean {
+  if (!h.connected || !h.subscribed) return false;
+  if (h.lastInboundAt <= 0 || now - h.lastInboundAt >= MQTT_HEALTHY_SILENCE_MS) return false;
+  if (h.healthySince <= 0 || now - h.healthySince < MQTT_HEALTHY_HOLD_MS) return false;
+  return true;
+}
+
+/**
+ * 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.
+ */
+export function nextBeatDelayMs(input: {
+  health: MqttBeatHealth | null;
+  now: number;
+  serverHintMs?: number;
+  busy?: boolean;
+}): number {
+  const hint = input.serverHintMs ?? BEAT_FAST_MS;
+  if (input.busy || !input.health) return BEAT_FAST_MS;
+  const local = mqttBeatHealthy(input.health, input.now) ? BEAT_SLOW_MS : BEAT_FAST_MS;
+  return Math.min(local, hint);
+}

package/src/device-agent/component.tsx

@@ -0,0 +1,60 @@
+import { useEffect, useRef } from "react";
+import type { MqttBeatHealth } from "./beat-policy";
+import { useLivestreamHost } from "../provider";
+import {
+  DeviceAgent,
+  type DeviceAgentDeviceInfo,
+  type DeviceAgentTransport,
+  type DeviceControlChannel,
+  type DeviceHeartbeatExtras,
+  type RemoteStartConfig,
+} from "./agent";
+
+/**
+ * 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.
+ */
+export 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;
+}
+
+export function PickleballDeviceAgent(props: PickleballDeviceAgentProps) {
+  const host = useLivestreamHost();
+
+  // Giữ tham chiếu mới nhất để agent (tạo 1 lần) luôn gọi callback hiện hành
+  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),
+      heartbeatExtras: () => propsRef.current.heartbeatExtras?.(),
+      mqttHealth: () => propsRef.current.mqttHealth?.() ?? null,
+    });
+    agent.start();
+    return () => agent.stop();
+  }, [host]);
+
+  return null;
+}

package/src/device-agent/convex-beat-transport.ts

@@ -0,0 +1,140 @@
+import type { BootstrapInput } from "../contracts";
+import type {
+  DeviceAgentDeviceInfo,
+  DeviceAgentTransport,
+  DeviceControlSessionGrant,
+  DeviceHeartbeatBody,
+} from "./agent";
+import type { ConvexDeviceRealtime } from "./convex-command-subscription";
+
+/**
+ * Bọc transport HTTP để heartbeat đi đường WEBSOCKET (mutation deviceApp.beat,
+ * 1 function call) thay vì POST /devices/heartbeat (httpAction→runMutation,
+ * 2 call). Ở 1.000 máy nhịp 12s, đó là 216M call/tháng so với 108M — một nửa
+ * hoá đơn chỉ bằng cách đổi đường vận chuyển, không đổi ngữ nghĩa.
+ *
+ * register/pairing GIỮ HTTP: đó là lúc máy CHƯA có deviceToken (chưa auth WS
+ * được), và là việc hiếm — không đáng tối ưu.
+ *
+ * Luật fallback: mọi lỗi WS (mất mạng, token hỏng, server chưa deploy beat...)
+ * → rơi về HTTP NGAY trong nhịp đó, và nghỉ thử WS một quãng để mỗi beat
+ * không phải trả thêm một lần timeout khi WS đang hỏng kéo dài. Máy bản này chạy
+ * với server cũ chưa có `deviceApp.beat` vẫn sống bình thường qua HTTP.
+ */
+
+/** WS hỏng thì nghỉ thử ngần này rồi mới thử lại — tránh mỗi beat +10s timeout. */
+const WS_BEAT_RETRY_MS = 60_000;
+/**
+ * Trần chờ một lượt beat WS. PHẢI có: ConvexClient.mutation KHÔNG tự timeout —
+ * mất mạng là nó xếp hàng chờ reconnect vô hạn, thiếu trần này thì heartbeat
+ * treo và không bao giờ rơi về HTTP. Mutation xếp hàng có thể vẫn chạy SAU khi
+ * mạng về → beat đúp — vô hại, heartbeat lặp là ngữ nghĩa bình thường.
+ */
+const WS_BEAT_TIMEOUT_MS = 10_000;
+
+export 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;
+}
+
+export function withConvexBeat(
+  base: DeviceAgentTransport,
+  realtime: ConvexDeviceRealtime,
+  options: ConvexBeatOptions,
+): DeviceAgentTransport {
+  const now = options.now ?? Date.now;
+  const timeoutMs = options.timeoutMs ?? WS_BEAT_TIMEOUT_MS;
+  let wsBrokenUntil = 0;
+
+  return {
+    register(input: BootstrapInput & DeviceAgentDeviceInfo) {
+      return base.register(input);
+    },
+    async heartbeat(input: BootstrapInput & DeviceHeartbeatBody) {
+      const deviceToken = options.getDeviceToken();
+      if (!deviceToken || now() < wsBrokenUntil) {
+        return base.heartbeat(input);
+      }
+      try {
+        const data = await withTimeout(
+          realtime.beat({
+            deviceToken,
+            // Server tra máy theo token — bootstrapInput (installationId…) chỉ
+            // đường HTTP cần. Chỉ gửi đúng phần mutation beat nhận.
+            agentState: input.agentState,
+            currentSessionId: input.currentSessionId,
+            ...(input.appVersion !== undefined ? { appVersion: input.appVersion } : {}),
+            ...(input.metrics !== undefined ? { metrics: input.metrics } : {}),
+            ...(input.recentExits !== undefined && input.recentExits.length > 0
+              ? { recentExits: input.recentExits }
+              : {}),
+            ...(input.powerState !== undefined ? { powerState: input.powerState } : {}),
+          }),
+          timeoutMs,
+        );
+        options.onData?.("heartbeat", data);
+        // Cùng lý do với http-transport: transport là nơi DUY NHẤT dữ liệu beat
+        // đi qua, không chuyển tiếp ở đây là agent vĩnh viễn không thấy hint.
+        return {
+          controlSession: parseControlSession(data.controlSession),
+          ...(typeof data.beatIntervalMs === "number" &&
+          Number.isFinite(data.beatIntervalMs)
+            ? { beatIntervalMs: data.beatIntervalMs }
+            : {}),
+        };
+      } catch {
+        // Không phân loại lỗi: nguyên nhân nào thì hành động cũng là dùng HTTP
+        // nhịp này và nghỉ thử WS một quãng.
+        wsBrokenUntil = now() + WS_BEAT_RETRY_MS;
+        return base.heartbeat(input);
+      }
+    },
+  };
+}
+
+/** Cùng luật parse với đường HTTP — grant lệch dạng coi như beat hỏng (throw). */
+function parseControlSession(grant: unknown): DeviceControlSessionGrant | null {
+  if (grant === null || grant === undefined) return null;
+  if (
+    grant === null ||
+    typeof grant !== "object" ||
+    typeof (grant as Record<string, unknown>).id !== "string" ||
+    typeof (grant as Record<string, unknown>).token !== "string" ||
+    typeof (grant as Record<string, unknown>).convexUrl !== "string" ||
+    (grant as Record<string, unknown>).convexUrl === ""
+  ) {
+    throw new Error("Invalid controlSession in beat response");
+  }
+  const record = grant as Record<string, unknown>;
+  return {
+    id: record.id as string,
+    token: record.token as string,
+    convexUrl: record.convexUrl as string,
+  };
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error("beat timeout")), ms);
+    (timer as unknown as { unref?: () => void }).unref?.();
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}

package/src/device-agent/convex-command-subscription.ts

@@ -0,0 +1,101 @@
+import { ConvexClient } from "convex/browser";
+import { anyApi } from "convex/server";
+import type { SdkTelemetryCredentials, SessionCommandRecord } from "../contracts";
+import type { SessionCommandSubscription } from "../engine";
+
+/**
+ * Kênh nhận lệnh device-rtmp qua WEBSOCKET (Convex subscription) thay poll HTTP
+ * 2 giây. Vì sao đổi: poll 2s là 2 function call mỗi 2 giây MỖI MÁY chạy suốt
+ * ngày đêm — ở 200 máy là ~518 triệu call/tháng, gấp 20 lần quota gói Pro.
+ * Subscription chỉ chạy lại (và tính tiền) KHI hàng lệnh của phiên đổi: lệnh về
+ * tức thì (<1s), còn lúc rảnh gần như 0.
+ *
+ * CHỈ dùng cho máy FIRST-PARTY nối thẳng Convex (có URL .convex.cloud). Máy đối
+ * tác đi qua proxy không có đường websocket trực tiếp → giữ nguyên poll HTTP.
+ *
+ * Auth: gửi telemetry token THÔ làm tham số query, backend hash server-side
+ * (sessionCommands.pendingForSession) — client không có crypto. Cùng lối với
+ * deviceControl.pendingCommands (cũng nhận token thô trong query).
+ *
+ * ConvexClient được dựng MỘT lần và tái dùng qua mọi phiên: engine chỉ
+ * subscribe/unsubscribe theo phiên, KHÔNG đóng client giữa chừng (đóng rồi mở
+ * lại là bắt tay websocket mới mỗi lần đổi độ phân giải/phiên).
+ */
+export function createConvexCommandSubscription(
+  convexUrl: string,
+): SessionCommandSubscription {
+  return createConvexDeviceRealtime(convexUrl).commandSubscription;
+}
+
+/**
+ * Mọi kênh Convex realtime của máy first-party trên MỘT websocket duy nhất:
+ * subscription lệnh (đợt 2) + heartbeat 1-call (đợt 3). Convex client tự
+ * multiplex query/mutation trên cùng socket — dựng hai client là trả giá hai
+ * lần bắt tay + hai kết nối phải nuôi.
+ */
+export interface ConvexDeviceRealtime {
+  commandSubscription: SessionCommandSubscription;
+  /**
+   * Heartbeat qua websocket = 1 function call (mutation `deviceApp.beat`),
+   * thay cho đường HTTP httpAction→runMutation = 2 call. Trả envelope `data`
+   * thô cùng hợp đồng với POST /devices/heartbeat. NÉM lỗi khi thất bại —
+   * caller (withConvexBeat) tự rơi về HTTP.
+   */
+  beat(args: Record<string, unknown>): Promise<Record<string, unknown>>;
+  dispose(): void;
+}
+
+export function createConvexDeviceRealtime(convexUrl: string): ConvexDeviceRealtime {
+  const client = new ConvexClient(convexUrl);
+  return {
+    commandSubscription: {
+      subscribe(
+        credentials: SdkTelemetryCredentials,
+        sessionId: string,
+        onCommands: (commands: SessionCommandRecord[]) => void,
+        onError?: (error: Error) => void,
+      ) {
+        return client.onUpdate(
+          anyApi.sessionCommands.pendingForSession,
+          { sessionId, token: credentials.token, after: 0 },
+          (value) => onCommands(toCommands(value)),
+          (error) => onError?.(error),
+        );
+      },
+      // Client dùng chung với beat — đóng ở dispose() của cả cụm, không ở đây.
+      dispose() {},
+    },
+    async beat(args) {
+      const result = await client.mutation(anyApi.deviceApp.beat, args);
+      return result !== null && typeof result === "object" && !Array.isArray(result)
+        ? (result as Record<string, unknown>)
+        : {};
+    },
+    dispose() {
+      void client.close();
+    },
+  };
+}
+
+/** Lọc payload query thành mảng lệnh hợp lệ — bỏ mọi thứ không đúng dạng. */
+function toCommands(value: unknown): SessionCommandRecord[] {
+  if (value === null || typeof value !== "object") return [];
+  const commands = (value as { commands?: unknown }).commands;
+  if (!Array.isArray(commands)) return [];
+  const out: SessionCommandRecord[] = [];
+  for (const item of commands) {
+    if (item === null || typeof item !== "object") continue;
+    const record = item as Record<string, unknown>;
+    if (
+      typeof record.id === "string" &&
+      (record.action === "start" ||
+        record.action === "stop" ||
+        record.action === "end") &&
+      typeof record.issuedAt === "number" &&
+      Number.isFinite(record.issuedAt)
+    ) {
+      out.push({ id: record.id, action: record.action, issuedAt: record.issuedAt });
+    }
+  }
+  return out;
+}

package/src/device-agent/convex-control-channel.ts

@@ -0,0 +1,88 @@
+import { ConvexClient } from "convex/browser";
+import { anyApi } from "convex/server";
+import type { DeviceCommand, DeviceControlChannel } from "./agent";
+
+/**
+ * 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.
+ */
+export function createConvexControlChannel(convexUrl: string): DeviceControlChannel {
+  const client = new ConvexClient(convexUrl);
+  const deviceControl = anyApi.deviceControl;
+
+  function toCommands(value: unknown): DeviceCommand[] {
+    if (!Array.isArray(value)) return [];
+    const commands: DeviceCommand[] = [];
+    for (const item of value) {
+      if (item === null || typeof item !== "object") continue;
+      const record = item as Record<string, unknown>;
+      if (
+        typeof record.id !== "string" ||
+        (record.type !== "start_livestream" &&
+          record.type !== "stop_livestream" &&
+          record.type !== "publish_livestream" &&
+          record.type !== "unpublish_livestream") ||
+        typeof record.expiresAt !== "number"
+      ) {
+        continue;
+      }
+      const payload =
+        record.payload !== null &&
+        typeof record.payload === "object" &&
+        !Array.isArray(record.payload)
+          ? (record.payload as Record<string, unknown>)
+          : {};
+      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 }
+            : {}),
+          ...(typeof payload.courtRef === "string" && payload.courtRef.trim() !== ""
+            ? { courtRef: payload.courtRef }
+            : {}),
+        },
+        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 as Record<string, unknown>).status === "string"
+              ? ((value as Record<string, unknown>).status as string)
+              : "ended";
+          callback({ status });
+        },
+      );
+    },
+    async ack(input) {
+      await client.mutation(deviceControl.ackCommand, { ...input });
+    },
+    close() {
+      void client.close();
+    },
+  };
+}

package/src/device-agent/http-transport.ts

@@ -0,0 +1,164 @@
+import type { BootstrapInput } from "../contracts";
+import type {
+  DeviceAgentDeviceInfo,
+  DeviceAgentTransport,
+  DeviceControlSessionGrant,
+  DeviceHeartbeatBody,
+} from "./agent";
+import {
+  ExpoSdkConfigurationError,
+  ExpoSdkTimeoutError,
+  InvalidResponseError,
+  NetworkUnavailableError,
+  PickleballExpoError,
+  errorFromCode,
+} from "../errors";
+
+type Fetch = typeof globalThis.fetch;
+type HeadersInput = Record<string, string>;
+
+export 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;
+}
+
+const defaultPaths = {
+  register: "/devices/register",
+  heartbeat: "/devices/heartbeat",
+};
+
+/** Transport HTTP cho DeviceAgent — mirror createHttpSessionProvider. */
+export function createHttpDeviceAgentTransport(
+  options: HttpDeviceAgentTransportOptions,
+): DeviceAgentTransport {
+  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: string, body: unknown): Promise<unknown> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 10_000);
+    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(undefined, { cause: error });
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  return {
+    async register(input: BootstrapInput & DeviceAgentDeviceInfo) {
+      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();
+      }
+      options.onData?.("register", data);
+      return {
+        deviceId: data.deviceId,
+        heartbeatIntervalMs: data.heartbeatIntervalMs,
+      };
+    },
+    async heartbeat(input: BootstrapInput & DeviceHeartbeatBody) {
+      const data = await post(paths.heartbeat, input);
+      if (!isRecord(data)) throw new InvalidResponseError();
+      options.onData?.("heartbeat", data);
+      // Nhịp server gợi ý cho lượt beat kế (adaptive heartbeat). Transport là
+      // NƠI DUY NHẤT dữ liệu beat đi qua, nên field nào không được chuyển tiếp
+      // ở đây thì agent vĩnh viễn không thấy — dù server trả đúng và app đã có
+      // code đọc. Đúng ca đã mất một buổi truy 02/09: server trả 60s, bundle
+      // app có code mới, mà máy vẫn beat 12s vì hint bị chặn ngay chỗ này.
+      const beatIntervalMs =
+        typeof data.beatIntervalMs === "number" && Number.isFinite(data.beatIntervalMs)
+          ? { beatIntervalMs: data.beatIntervalMs }
+          : {};
+      const grant = data.controlSession;
+      if (grant === null || grant === undefined) {
+        return { controlSession: null, ...beatIntervalMs };
+      }
+      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,
+        } satisfies DeviceControlSessionGrant,
+        ...beatIntervalMs,
+      };
+    },
+  };
+}
+
+function parseProxyError(envelope: unknown) {
+  if (
+    isRecord(envelope) &&
+    isRecord(envelope.error) &&
+    typeof envelope.error.code === "string"
+  ) {
+    return errorFromCode(
+      envelope.error.code,
+      typeof envelope.error.message === "string" ? envelope.error.message : undefined,
+    );
+  }
+  return new InvalidResponseError();
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/device-agent/index.ts

@@ -0,0 +1,26 @@
+export * from "./agent";
+export * from "./http-transport";
+export * from "./tournament";
+export { createConvexControlChannel } from "./convex-control-channel";
+export {
+  createConvexCommandSubscription,
+  createConvexDeviceRealtime,
+  type ConvexDeviceRealtime,
+} from "./convex-command-subscription";
+export { withConvexBeat, type ConvexBeatOptions } from "./convex-beat-transport";
+export { PickleballDeviceAgent, type PickleballDeviceAgentProps } from "./component";
+export { createMqttChannel } from "./mqtt-channel";
+export type {
+  MqttChannel,
+  MqttChannelDeps,
+  MqttChannelHealth,
+  MqttChannelOptions,
+  MqttSocket,
+} from "./mqtt-channel";
+export {
+  BEAT_FAST_MS,
+  BEAT_SLOW_MS,
+  mqttBeatHealthy,
+  nextBeatDelayMs,
+  type MqttBeatHealth,
+} from "./beat-policy";