@pickleball/expo-sdk 0.2.0 → 1.0.0

package/src/session-grant.ts

@@ -0,0 +1,256 @@
+import type {
+  CameraGrant,
+  SdkBootstrap,
+  SdkRemoteConfig,
+  SdkSessionGrant,
+  SdkSessionRefresh,
+  SdkTelemetryCredentials,
+} from "./contracts";
+import { isSdkRemoteConfig } from "./contracts";
+import {
+  ExpoSdkConfigurationError,
+  ExpoSdkTimeoutError,
+  InvalidResponseError,
+  NetworkUnavailableError,
+  PickleballExpoError,
+  errorFromCode,
+} from "./errors";
+
+/**
+ * Validator + helper HTTP dùng chung cho hai session provider:
+ * - createHttpSessionProvider (proxy đối tác / first-party device-app)
+ * - createCameraGrantProvider (điện thoại đối tác, grant từ backend đối tác)
+ *
+ * Tách ra để hai provider không chép luật "grant thế nào là hợp lệ" ra hai nơi
+ * rồi lệch nhau; engine chỉ tin `isSdkRemoteConfig`, còn hình dạng grant là
+ * việc của lớp này.
+ */
+
+export type Fetch = typeof globalThis.fetch;
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+export function isBootstrap(value: unknown): value is SdkBootstrap {
+  return (
+    isRecord(value) &&
+    isSdkRemoteConfig(value.config) &&
+    isFiniteNumber(value.serverTime) &&
+    typeof value.rolloutEnabled === "boolean" &&
+    (value.message === undefined || typeof value.message === "string")
+  );
+}
+
+export function isTelemetryCredentials(value: unknown): value is SdkTelemetryCredentials {
+  return (
+    isRecord(value) &&
+    typeof value.endpoint === "string" &&
+    /^https:\/\//.test(value.endpoint) &&
+    typeof value.token === "string" &&
+    value.token.length > 0 &&
+    isFiniteNumber(value.expiresAt)
+  );
+}
+
+/**
+ * Grant phiên. SDK 1.0 là RTMP-only: `serverUrl` phải là rtmp(s):// (ingest).
+ * Grant LiveKit (wss://) của mô hình cũ bị từ chối ngay ở đây — lỗi
+ * INVALID_RESPONSE rõ ràng thay vì HaishinKit ném lúc connect.
+ */
+export function isSessionGrant(value: unknown): value is SdkSessionGrant {
+  return (
+    isRecord(value) &&
+    typeof value.sessionId === "string" &&
+    value.sessionId.length > 0 &&
+    typeof value.serverUrl === "string" &&
+    /^rtmps?:\/\//i.test(value.serverUrl) &&
+    typeof value.participantToken === "string" &&
+    value.participantToken.length > 0 &&
+    (value.playbackUrl === null || typeof value.playbackUrl === "string") &&
+    isFiniteNumber(value.tokenExpiresAt) &&
+    isTelemetryCredentials(value.telemetry) &&
+    isSdkRemoteConfig(value.config)
+  );
+}
+
+function optionalNullableString(value: unknown): boolean {
+  return value === undefined || value === null || typeof value === "string";
+}
+
+/**
+ * Camera grant (điện thoại đối tác): superset của SdkSessionGrant, BẮT BUỘC là
+ * RTMP và mang `status` để đường nhận lại biết phiên cũ đang phát hay đang chờ.
+ */
+export function isCameraGrant(value: unknown): value is CameraGrant {
+  return (
+    isSessionGrant(value) &&
+    /^rtmps?:\/\//i.test(value.serverUrl) &&
+    ((value as { status?: unknown }).status === "scheduled" ||
+      (value as { status?: unknown }).status === "live") &&
+    optionalNullableString((value as { matchRef?: unknown }).matchRef) &&
+    optionalNullableString((value as { courtRef?: unknown }).courtRef) &&
+    optionalNullableString((value as { watchUrl?: unknown }).watchUrl) &&
+    optionalNullableString((value as { convexUrl?: unknown }).convexUrl)
+  );
+}
+
+export function isSessionRefresh(value: unknown): value is SdkSessionRefresh {
+  if (!isRecord(value) || !isSdkRemoteConfig(value.config)) return false;
+  if (
+    value.participantToken !== undefined &&
+    (typeof value.participantToken !== "string" || !value.participantToken)
+  ) {
+    return false;
+  }
+  if (value.tokenExpiresAt !== undefined && !isFiniteNumber(value.tokenExpiresAt)) {
+    return false;
+  }
+  return value.telemetry === undefined || isTelemetryCredentials(value.telemetry);
+}
+
+export function isSessionStatus(
+  value: unknown,
+): value is { sessionId: string; status: string } {
+  return (
+    isRecord(value) &&
+    typeof value.sessionId === "string" &&
+    value.sessionId.length > 0 &&
+    typeof value.status === "string" &&
+    value.status.length > 0
+  );
+}
+
+/**
+ * Gốc API của phiên suy từ endpoint telemetry trong grant: `…/sessions/{id}/telemetry`
+ * → `…/sessions/{id}`. Đây là cách duy nhất SDK biết namespace (sdk / camera /
+ * device-app) mà không cần app cấu hình URL PickLive nào.
+ */
+export function sessionApiBaseFromTelemetryEndpoint(endpoint: string): string {
+  if (!/^https:\/\//.test(endpoint) || !endpoint.endsWith("/telemetry")) {
+    throw new InvalidResponseError("The telemetry endpoint must be an HTTPS …/telemetry URL");
+  }
+  return endpoint.slice(0, -"/telemetry".length);
+}
+
+declare const __DEV__: boolean | undefined;
+
+// RFC 1918 private ranges: 10/8, 172.16/12, 192.168/16.
+const PRIVATE_LAN_HOST =
+  /^(?:10\.\d{1,3}\.\d{1,3}\.\d{1,3}|172\.(?:1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3})$/;
+
+export function normalizeBaseUrl(value: string): string {
+  try {
+    const url = new URL(value);
+    const loopbackHosts = new Set(["localhost", "127.0.0.1", "[::1]"]);
+    const secure = url.protocol === "https:";
+    const localDevelopment = url.protocol === "http:" && loopbackHosts.has(url.hostname);
+    // Dev bundle only (Metro/dev client): a device on the same network must
+    // reach the dev proxy over plain HTTP at a private LAN address. Release
+    // bundles compile __DEV__ to false, so production keeps the HTTPS rule.
+    const devPrivateLan =
+      typeof __DEV__ !== "undefined" &&
+      __DEV__ === true &&
+      url.protocol === "http:" &&
+      PRIVATE_LAN_HOST.test(url.hostname);
+    if ((!secure && !localDevelopment && !devPrivateLan) || url.username || url.password) {
+      throw new Error();
+    }
+    return value.replace(/\/+$/, "");
+  } catch {
+    throw new ExpoSdkConfigurationError(
+      "baseUrl must use HTTPS (HTTP is allowed only for localhost loopback)",
+    );
+  }
+}
+
+export function joinUrl(base: string, path: string) {
+  return `${base}/${path.replace(/^\/+/, "")}`;
+}
+
+/**
+ * Lỗi từ envelope `{error:{code,message}}` + mã HTTP. Mã HTTP đi kèm vì envelope
+ * không phân biệt được "phiên đã biến mất" (404) với "server trục trặc" (5xx) —
+ * engine cần 404/409 để quyết dừng quay số hay thử lại.
+ */
+export function parseEnvelopeError(
+  envelope: unknown,
+  httpStatus: number,
+): PickleballExpoError & { httpStatus: number; reason?: string; retryAfterMs?: number } {
+  const body = isRecord(envelope) && isRecord(envelope.error) ? envelope.error : null;
+  const error =
+    body && typeof body.code === "string"
+      ? errorFromCode(body.code, typeof body.message === "string" ? body.message : undefined)
+      : new InvalidResponseError();
+  // `reason` (409: superseded|ended|expired) và `retryAfterMs` (429) đi kèm để
+  // app phân biệt ba ca 409 mà không phải đọc chuỗi message.
+  return Object.assign(
+    error,
+    { httpStatus },
+    body && typeof body.reason === "string" ? { reason: body.reason } : {},
+    body && typeof body.retryAfterMs === "number" ? { retryAfterMs: body.retryAfterMs } : {},
+  );
+}
+
+export interface JsonPosterOptions {
+  fetch?: Fetch;
+  timeoutMs?: number;
+}
+
+/**
+ * POST JSON → mở bọc `{data}`; lỗi mạng/timeout/envelope map thành lỗi SDK
+ * (giữ `httpStatus`). Dùng chung cho mọi provider.
+ */
+export function createJsonPoster(options: JsonPosterOptions = {}) {
+  const fetchImplementation = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImplementation !== "function") {
+    throw new ExpoSdkConfigurationError("A Fetch API implementation is required");
+  }
+  const timeoutMs = options.timeoutMs ?? 10_000;
+  return async function post(
+    url: string,
+    body: unknown,
+    headers: Record<string, string> = {},
+  ): Promise<unknown> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetchImplementation(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...headers },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+        redirect: "error",
+      });
+      const envelope = await response.json().catch(() => {
+        throw new InvalidResponseError();
+      });
+      if (!response.ok) throw parseEnvelopeError(envelope, response.status);
+      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);
+    }
+  };
+}
+
+/** Mã HTTP gắn trên lỗi provider, nếu có. */
+export function httpStatusOf(error: unknown): number | undefined {
+  const status = (error as { httpStatus?: unknown } | null)?.httpStatus;
+  return typeof status === "number" ? status : undefined;
+}
+
+export type { SdkRemoteConfig };