@pickleball/expo-sdk 0.2.0 → 1.0.0

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

@@ -20,7 +20,10 @@ export function createConvexControlChannel(convexUrl: string): DeviceControlChan
       const record = item as Record<string, unknown>;
       if (
         typeof record.id !== "string" ||
-        (record.type !== "start_livestream" && record.type !== "stop_livestream") ||
+        (record.type !== "start_livestream" &&
+          record.type !== "stop_livestream" &&
+          record.type !== "publish_livestream" &&
+          record.type !== "unpublish_livestream") ||
         typeof record.expiresAt !== "number"
       ) {
         continue;
@@ -39,6 +42,9 @@ export function createConvexControlChannel(convexUrl: string): DeviceControlChan
           ...(payload.visibility === "public" || payload.visibility === "private"
             ? { visibility: payload.visibility }
             : {}),
+          ...(typeof payload.courtRef === "string" && payload.courtRef.trim() !== ""
+            ? { courtRef: payload.courtRef }
+            : {}),
         },
         expiresAt: record.expiresAt,
       });

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

@@ -24,6 +24,13 @@ export interface HttpDeviceAgentTransportOptions {
   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 = {
@@ -94,6 +101,7 @@ export function createHttpDeviceAgentTransport(
       ) {
         throw new InvalidResponseError();
       }
+      options.onData?.("register", data);
       return {
         deviceId: data.deviceId,
         heartbeatIntervalMs: data.heartbeatIntervalMs,
@@ -102,8 +110,20 @@ export function createHttpDeviceAgentTransport(
     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 };
+      if (grant === null || grant === undefined) {
+        return { controlSession: null, ...beatIntervalMs };
+      }
       if (
         !isRecord(grant) ||
         typeof grant.id !== "string" ||
@@ -119,6 +139,7 @@ export function createHttpDeviceAgentTransport(
           token: grant.token,
           convexUrl: grant.convexUrl,
         } satisfies DeviceControlSessionGrant,
+        ...beatIntervalMs,
       };
     },
   };

package/src/device-agent/index.ts

@@ -1,4 +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";

package/src/device-agent/mqtt-channel.ts

@@ -0,0 +1,379 @@
+import {
+  CONNACK_REASON,
+  decodePackets,
+  encodeConnect,
+  encodeDisconnect,
+  encodePingReq,
+  encodePublish,
+  encodePuback,
+  encodeSubscribe,
+  type MqttPacket,
+} from "./mqtt-codec";
+
+/**
+ * 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ả. */
+export 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;
+}
+
+export 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;
+}
+
+export 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ế.
+ */
+export interface MqttChannelHealth {
+  connected: boolean;
+  subscribed: boolean;
+  lastInboundAt: number;
+  healthySince: number;
+}
+
+export 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;
+}
+
+/**
+ * Auth hỏng thì đừng quay số theo thang thường: token bị thu hồi hoặc máy chưa
+ * được claim là trạng thái kéo dài hàng phút tới hàng giờ, mà mỗi lần thử là
+ * một lượt gọi auth-hook Convex. 5 phút là đủ thưa để 1.000 máy hỏng cùng lúc
+ * cũng không thành bão, vẫn đủ dày để máy vừa được claim tự vào trong 5 phút.
+ */
+const AUTH_RETRY_MS = 5 * 60_000;
+
+export function createMqttChannel(
+  o: MqttChannelOptions,
+  deps: MqttChannelDeps = {},
+): MqttChannel {
+  const createSocket =
+    deps.createSocket ??
+    ((url, protocols) => new WebSocket(url, protocols) as unknown as MqttSocket);
+  const setTimer = deps.setTimeout ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = deps.clearTimeout ?? ((h) => clearTimeout(h as never));
+  const now = deps.now ?? (() => Date.now());
+  const random = deps.random ?? Math.random;
+
+  let socket: MqttSocket | null = null;
+  let buffer = new Uint8Array(0);
+  let connected = false;
+  let stopped = true;
+  let attempt = 0;
+  let packetId = 0;
+  let reconnectTimer: unknown = null;
+  let pingTimer: unknown = null;
+  let lastInboundAt = 0;
+  // Đã SUBACK đủ topic điều khiển chưa, và khoẻ liên tục từ lúc nào. Cả hai
+  // reset trong teardown: nối lại là phải chứng minh khoẻ lại từ đầu, không
+  // được thừa hưởng "đã khoẻ" của phiên kết nối trước.
+  let subscribed = false;
+  let healthySince = 0;
+
+  const nextPacketId = () => {
+    packetId = (packetId % 65_535) + 1;
+    return packetId;
+  };
+
+  const setConnected = (value: boolean) => {
+    if (connected === value) return;
+    connected = value;
+    o.onConnectionChange?.(value);
+  };
+
+  const clearTimers = () => {
+    if (reconnectTimer !== null) {
+      clearTimer(reconnectTimer);
+      reconnectTimer = null;
+    }
+    if (pingTimer !== null) {
+      clearTimer(pingTimer);
+      pingTimer = null;
+    }
+  };
+
+  const send = (bytes: Uint8Array): boolean => {
+    if (!socket) return false;
+    try {
+      socket.send(bytes);
+      return true;
+    } catch {
+      // Socket vừa chết giữa chừng — đóng để rơi vào nhánh reconnect chung,
+      // đừng ném lên trên: kênh này không được phép làm sập engine.
+      teardown(true);
+      return false;
+    }
+  };
+
+  const scheduleReconnect = (delayMs?: number) => {
+    if (stopped || reconnectTimer !== null) return;
+    const base =
+      delayMs ??
+      o.reconnectDelaysMs[Math.min(attempt, o.reconnectDelaysMs.length - 1)] ??
+      30_000;
+    const jitter = base === 0 ? 0 : base * 0.2 * (random() * 2 - 1);
+    attempt += 1;
+    reconnectTimer = setTimer(() => {
+      reconnectTimer = null;
+      open();
+    }, Math.max(0, Math.round(base + jitter)));
+  };
+
+  const teardown = (reconnect: boolean, delayMs?: number) => {
+    clearTimers();
+    setConnected(false);
+    subscribed = false;
+    healthySince = 0;
+    buffer = new Uint8Array(0);
+    const dead = socket;
+    socket = null;
+    if (dead) {
+      dead.onopen = null;
+      dead.onmessage = null;
+      dead.onerror = null;
+      dead.onclose = null;
+      try {
+        dead.close();
+      } catch {
+        // Đóng socket đã chết không phải lỗi.
+      }
+    }
+    if (reconnect) scheduleReconnect(delayMs);
+  };
+
+  /**
+   * Nhịp giữ kết nối. Gửi PINGREQ ở 3/4 keepalive, và nếu quá 1,5× keepalive mà
+   * KHÔNG nhận được byte nào thì tự coi là chết và nối lại — WiFi sân hay rơi
+   * vào cảnh socket "còn mở" trên giấy tờ nhưng không gói nào qua được nữa,
+   * lúc đó chỉ có phía mình tự nghi ngờ mới thoát ra được.
+   */
+  const armPing = () => {
+    if (pingTimer !== null) clearTimer(pingTimer);
+    pingTimer = setTimer(() => {
+      pingTimer = null;
+      if (!socket) return;
+      if (now() - lastInboundAt > o.keepaliveS * 1500) {
+        teardown(true);
+        return;
+      }
+      send(encodePingReq());
+      armPing();
+    }, Math.max(1000, Math.round(o.keepaliveS * 750)));
+  };
+
+  const handlePacket = (p: MqttPacket) => {
+    switch (p.type) {
+      case "connack": {
+        if (p.returnCode !== 0) {
+          const reason = CONNACK_REASON[p.returnCode] ?? `mã ${p.returnCode}`;
+          o.onAuthRejected?.(reason);
+          // 4/5 = sai creds hoặc bị auth-hook từ chối → nghỉ dài, xem AUTH_RETRY_MS.
+          teardown(true, p.returnCode === 4 || p.returnCode === 5 ? AUTH_RETRY_MS : undefined);
+          return;
+        }
+        attempt = 0;
+        setConnected(true);
+        // Trình tự sau CONNACK: khai "tôi sống" (retained, để dashboard thấy
+        // ngay cả khi bridge vừa khởi động lại) rồi mới nhận lệnh.
+        send(
+          encodePublish({
+            topic: o.topics.status,
+            payload: o.statusPayload(true),
+            qos: 1,
+            retain: true,
+            packetId: nextPacketId(),
+          }),
+        );
+        send(
+          encodeSubscribe(nextPacketId(), [
+            { topic: o.topics.cmd, qos: 1 },
+            { topic: o.topics.cfg, qos: 1 },
+            // Tỉ số trận đang ghi (retained) — reconnect là nhận ngay bản mới nhất.
+            { topic: o.topics.score, qos: 1 },
+          ]),
+        );
+        armPing();
+        return;
+      }
+      case "suback": {
+        // Broker xác nhận đã đăng ký topic điều khiển. Trước mốc này máy nối
+        // được nhưng KHÔNG nghe được lệnh nào — không tính là kênh khoẻ.
+        // Mã ≥ 0x80 là broker TỪ CHỐI (ACL) → giữ subscribed = false.
+        if (p.codes.every((c) => c < 0x80)) {
+          subscribed = true;
+          if (healthySince === 0) healthySince = now();
+        }
+        return;
+      }
+      case "publish": {
+        // QoS1 phải ack, không thì broker gửi lại mãi.
+        if (p.qos === 1 && p.packetId !== undefined) send(encodePuback(p.packetId));
+        o.onMessage?.(p.topic, p.payload);
+        return;
+      }
+      default:
+        return;
+    }
+  };
+
+  const open = () => {
+    if (stopped || socket) return;
+    let s: MqttSocket;
+    try {
+      s = createSocket(o.url, ["mqtt"]);
+    } catch {
+      scheduleReconnect();
+      return;
+    }
+    socket = s;
+    s.binaryType = "arraybuffer";
+    lastInboundAt = now();
+
+    s.onopen = () => {
+      if (socket !== s) return;
+      send(
+        encodeConnect({
+          clientId: o.deviceId,
+          username: o.deviceId,
+          password: o.deviceToken,
+          keepaliveS: o.keepaliveS,
+          cleanSession: true,
+          will: {
+            topic: o.topics.status,
+            payload: o.statusPayload(false),
+            qos: 1,
+            retain: true,
+          },
+        }),
+      );
+    };
+
+    s.onmessage = (event) => {
+      if (socket !== s) return;
+      const data = event.data;
+      let chunk: Uint8Array | null = null;
+      if (data instanceof ArrayBuffer) {
+        chunk = new Uint8Array(data);
+      } else if (ArrayBuffer.isView(data)) {
+        // Copy chứ không tạo view lên buffer nền: runtime có thể tái dùng
+        // buffer đó cho frame sau, mà ta còn giữ phần gói dở qua nhiều lượt.
+        chunk = Uint8Array.from(data as unknown as ArrayLike<number>);
+      }
+      // RN trả Blob nếu binaryType không được tôn trọng — bỏ qua còn hơn ném.
+      if (!chunk) return;
+      lastInboundAt = now();
+      const merged = new Uint8Array(buffer.length + chunk.length);
+      merged.set(buffer, 0);
+      merged.set(chunk, buffer.length);
+      const { packets, rest } = decodePackets(merged);
+      // Copy phần dư (thường vài byte của gói chưa trọn) thay vì giữ subarray:
+      // view trỏ vào buffer cũ sẽ ghim cả frame vừa rồi trong bộ nhớ.
+      buffer = Uint8Array.from(rest);
+      for (const p of packets) handlePacket(p);
+    };
+
+    s.onerror = () => {
+      if (socket !== s) return;
+      teardown(true);
+    };
+
+    s.onclose = () => {
+      if (socket !== s) return;
+      teardown(true);
+    };
+  };
+
+  return {
+    start() {
+      if (!stopped) return;
+      stopped = false;
+      attempt = 0;
+      open();
+    },
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      // DISCONNECT sạch KHÔNG kích LWT, nên phải TỰ khai offline trước khi
+      // đóng: thiếu bước này thì máy chủ động gỡ ghép/tắt tính năng sẽ đứng
+      // "online" vĩnh viễn trên dashboard (retained cũ nằm lại trên broker).
+      if (socket && connected) {
+        send(
+          encodePublish({
+            topic: o.topics.status,
+            payload: o.statusPayload(false),
+            qos: 1,
+            retain: true,
+            packetId: nextPacketId(),
+          }),
+        );
+        send(encodeDisconnect());
+      }
+      teardown(false);
+    },
+    isConnected: () => connected,
+    health: () => ({ connected, subscribed, lastInboundAt, healthySince }),
+    publish(topic, payload, opts) {
+      if (!connected) return false;
+      const qos = opts?.qos ?? 0;
+      return send(
+        encodePublish({
+          topic,
+          payload,
+          qos,
+          retain: opts?.retain ?? false,
+          ...(qos === 1 ? { packetId: nextPacketId() } : {}),
+        }),
+      );
+    },
+  };
+}