@pickleball/expo-sdk 0.1.1 → 1.0.0

package/src/rtmp-room-adapter.ts

@@ -0,0 +1,348 @@
+import type {
+  CameraDeviceInfo,
+  CaptureOrientation,
+  RoomAdapter,
+  RoomConnection,
+  RoomEvent,
+} from "./engine";
+import { VIDEO_BITRATE_BPS } from "./uplink-check";
+
+/**
+ * Trạng thái từ tầng RTMP native (trùng NativeRtmpStatus của @pickleball/rtmp-native).
+ */
+export type RtmpStatus =
+  | { readonly status: "idle" | "connecting" | "connected" | "publishing" }
+  | { readonly status: "disconnected"; readonly reason?: string }
+  | { readonly status: "error"; readonly code: string; readonly message: string };
+
+/** Phản hồi băng thông từ native (trùng NativeRtmpBandwidth của rtmp-native). */
+export interface RtmpBandwidth {
+  /** false = encoder đang đẩy nhanh hơn đường truyền chịu được. */
+  readonly sufficient: boolean;
+  readonly videoBitrate: number;
+}
+
+/**
+ * Dấu hiệu để UI biết render nguồn nào. LiveKit trả về một track object; RTMP
+ * không có "track" ở JS (khung hình đi thẳng trong native), nên trả marker này
+ * — nếu trả undefined thì UI tưởng chưa có preview và vẽ màn TỐI ĐEN.
+ */
+export interface RtmpPreviewMarker {
+  readonly kind: "rtmp";
+}
+
+/** Bề mặt native mà adapter cần — tiêm vào để test được không cần thiết bị thật. */
+export interface NativeRtmpBindings {
+  prepare(options: {
+    quality: 720 | 1080;
+    landscape: boolean;
+    /** fps mong muốn (24 tiết kiệm băng thông, 30 mặc định) — thiếu = native tự chọn. */
+    frameRate?: 24 | 30 | 60;
+    /**
+     * Camera mở ngay từ đầu. Thiếu = native dùng camera sau mặc định. Đặt ở đây
+     * thay vì gọi selectCamera sau prepare để không phải mở camera hai lần.
+     */
+    cameraId?: string;
+  }): Promise<void>;
+  /**
+   * Xin quyền camera/mic bằng API quyền thuần (PermissionsAndroid, ...).
+   * Không có thì engine rơi về getUserMedia của WebRTC — thứ mở camera thật
+   * và đụng HaishinKit trên máy Android chỉ cho một camera mở cùng lúc.
+   */
+  requestPermissions?(): Promise<boolean>;
+  /** Hướng cầm máy hiện tại — cùng nguồn mà LiveKitRoomAdapter dùng. */
+  isLandscape?(): boolean;
+  connect(options: {
+    url: string;
+    videoBitrate: number;
+    publish: boolean;
+  }): Promise<void>;
+  setPublishing(enabled: boolean): Promise<void>;
+  disconnect(): Promise<void>;
+  switchCamera(): Promise<void>;
+  listCameras(): Array<{ deviceId: string; label: string; facing: string }>;
+  selectCamera(deviceId: string, facing: string): Promise<void>;
+  setMicrophoneEnabled(enabled: boolean): Promise<void>;
+  setVideoBitrate(bitsPerSecond: number): Promise<void>;
+  dispose(): Promise<void>;
+  addStatusListener(listener: (event: RtmpStatus) => void): { remove(): void };
+  /** Optional: bản native cũ chưa phát onBandwidth thì adapter bỏ qua thích ứng. */
+  addBandwidthListener?(
+    listener: (event: RtmpBandwidth) => void,
+  ): { remove(): void };
+}
+
+/**
+ * Bitrate theo mức chất lượng — nằm trong khoảng TikTok khuyến nghị cho live
+ * (720p 3–6 Mbps, 1080p 6–9 Mbps). Thấp hơn khoảng này thì thể thao chuyển động
+ * nhanh như pickleball bị bể khối rất rõ.
+ */
+const VIDEO_BITRATE: Readonly<Record<720 | 1080, number>> = VIDEO_BITRATE_BPS;
+
+/**
+ * Thích ứng bitrate theo phản hồi băng thông của native (thay cho BWE mà
+ * WebRTC cho không). VIDEO_BITRATE là TRẦN, không phải điều kiện: máy/mạng
+ * không kham nổi 6 Mbps thì hạ dần xuống tới sàn và VẪN PHÁT — thà mờ còn
+ * hơn đứng hình hay tràn hàng đợi rồi rớt luồng.
+ *
+ * Hạ nhanh (×0.7 mỗi tín hiệu nghẽn ~2s), hồi chậm (×1.15 sau
+ * RECOVER_AFTER_SUFFICIENT tín hiệu tốt liên tiếp ~10s) — mô hình AIMD.
+ */
+export const BITRATE_FLOOR = 800_000;
+export const DEGRADE_FACTOR = 0.7;
+export const RECOVER_FACTOR = 1.15;
+export const RECOVER_AFTER_SUFFICIENT = 5;
+
+export interface AdaptiveBitrateState {
+  readonly current: number;
+  readonly ceiling: number;
+  readonly sufficientStreak: number;
+}
+
+/** Bước chuyển thuần — tách khỏi adapter để test không cần thiết bị. */
+export function nextBitrateState(
+  state: AdaptiveBitrateState,
+  event: Pick<RtmpBandwidth, "sufficient">,
+): AdaptiveBitrateState {
+  if (!event.sufficient) {
+    return {
+      ...state,
+      current: Math.max(BITRATE_FLOOR, Math.round(state.current * DEGRADE_FACTOR)),
+      sufficientStreak: 0,
+    };
+  }
+  const streak = state.sufficientStreak + 1;
+  if (streak < RECOVER_AFTER_SUFFICIENT || state.current >= state.ceiling) {
+    return { ...state, sufficientStreak: Math.min(streak, RECOVER_AFTER_SUFFICIENT) };
+  }
+  return {
+    ...state,
+    current: Math.min(state.ceiling, Math.round(state.current * RECOVER_FACTOR)),
+    sufficientStreak: 0,
+  };
+}
+
+/**
+ * Adapter cho mode deliveryMode="device-rtmp".
+ *
+ * Thiết bị mã hoá H.264 bằng phần cứng MỘT lần rồi đẩy thẳng RTMP; server chỉ
+ * remux sang HLS. Không có phòng LiveKit, không egress → $0 transcode.
+ *
+ * Khác LiveKitRoomAdapter ở một điểm quan trọng: RTMP **không có kênh dữ liệu**,
+ * nên adapter này không bao giờ phát RoomEvent "command". Lệnh điều khiển từ
+ * dashboard đi đường khác (deviceControl trên Convex) — xem device-agent.
+ */
+export class RtmpRoomAdapter implements RoomAdapter {
+  /**
+   * RTMP không tự hồi: native chỉ phát hiện đứt (watchdog iOS / onDisconnect
+   * Android) và báo "disconnected" — không tự quay số lại. Engine thấy cờ này
+   * là chạy vòng redial backoff. Thiếu cờ: phiên ngồi chờ "reconnected" không
+   * bao giờ tới rồi chết network_timeout sau 30s (prod 17/08/2026).
+   */
+  readonly needsManualReconnect = true;
+
+  private readonly listeners = new Set<(event: RoomEvent) => void>();
+  private nativeSubscription?: { remove(): void };
+  private bandwidthSubscription?: { remove(): void };
+  private quality: 720 | 1080 = 1080;
+  private connected = false;
+  private prepared = false;
+  /** Khung người dùng chọn trên UI (9:16/16:9) — ưu tiên hơn hướng cầm máy. */
+  private captureOrientation?: CaptureOrientation;
+  private bitrateState?: AdaptiveBitrateState;
+
+  /**
+   * Chỉ tồn tại khi bindings hỗ trợ — engine kiểm tra truthiness để quyết định
+   * fallback về runtime.requestPermissions() (getUserMedia), nên KHÔNG được
+   * khai báo method luôn-có rồi tự fallback bên trong.
+   */
+  readonly requestPermissions?: () => Promise<boolean>;
+
+  constructor(
+    private readonly bindings: NativeRtmpBindings,
+    private readonly options: { frameRate?: 24 | 30 | 60; cameraId?: string } = {},
+  ) {
+    const request = bindings.requestPermissions?.bind(bindings);
+    if (request) this.requestPermissions = request;
+  }
+
+  /**
+   * Phần tuỳ chọn của prepare(). Giữ dạng spread có điều kiện: truyền
+   * `frameRate: undefined` xuống Expo Record là ghi đè mặc định của native
+   * bằng null chứ không phải "bỏ qua trường".
+   */
+  private prepareOverrides(): { frameRate?: 24 | 30 | 60; cameraId?: string } {
+    return {
+      ...(this.options.frameRate !== undefined
+        ? { frameRate: this.options.frameRate }
+        : {}),
+      ...(this.options.cameraId !== undefined
+        ? { cameraId: this.options.cameraId }
+        : {}),
+    };
+  }
+
+  async preparePreview(quality: 720 | 1080): Promise<RtmpPreviewMarker> {
+    this.quality = quality;
+    // Khung người dùng chọn (9:16/16:9) là nguồn sự thật; chỉ khi chưa chọn mới
+    // đoán theo hướng cầm máy (mặc định ngang: sân pickleball quay ngang là
+    // chính, và đó cũng là kích thước capture mặc định của HaishinKit).
+    await this.bindings.prepare({
+      quality,
+      landscape: this.captureOrientation
+        ? this.captureOrientation === "landscape"
+        : (this.bindings.isLandscape?.() ?? true),
+      ...this.prepareOverrides(),
+    });
+    this.prepared = true;
+    // Khung hình do PickleballRtmpPreviewView vẽ ở tầng native; JS chỉ cần biết
+    // "đã có preview và là nguồn RTMP" để chọn đúng component hiển thị.
+    return { kind: "rtmp" };
+  }
+
+  async connect(input: RoomConnection) {
+    // Chặn lệch mode: nếu app chọn adapter RTMP nhưng phiên phía server lại là
+    // LiveKit thì serverUrl sẽ là wss://. Không kiểm ở đây thì HaishinKit nhận
+    // URL vô nghĩa và hỏng câm lặng, rất khó truy ngược.
+    if (!/^rtmps?:\/\//i.test(input.serverUrl)) {
+      throw new Error(
+        `Mode device-rtmp cần endpoint rtmp:// nhưng phiên trả về "${input.serverUrl}". ` +
+          "Kiểm tra deliveryMode của app trên server (partnerApps.deliveryMode).",
+      );
+    }
+    // Backend cấp rtmpsUrl kết thúc bằng "/" và rtmpsStreamKey riêng; ghép lại
+    // thành URL publish đầy đủ. Stream key đóng vai trò bearer token của phiên.
+    const url = `${input.serverUrl}${input.participantToken}`;
+    await this.bindings.setMicrophoneEnabled(input.microphoneEnabled);
+    await this.bindings.connect({
+      url,
+      videoBitrate: VIDEO_BITRATE[this.quality],
+      // publish !== false → mặc định phát ngay; false = vào standby.
+      publish: input.publish !== false,
+    });
+    this.connected = true;
+    // Trần theo mức chất lượng của phiên; phản hồi băng thông sẽ điều chỉnh
+    // trong khoảng [BITRATE_FLOOR, trần] mà không bao giờ chặn phát.
+    this.bitrateState = {
+      current: VIDEO_BITRATE[this.quality],
+      ceiling: VIDEO_BITRATE[this.quality],
+      sufficientStreak: 0,
+    };
+  }
+
+  async setPublishing(enabled: boolean) {
+    await this.bindings.setPublishing(enabled);
+  }
+
+  async disconnect(_stopTracks?: boolean) {
+    if (!this.connected) return;
+    this.connected = false;
+    this.bitrateState = undefined;
+    await this.bindings.disconnect();
+  }
+
+  async switchCamera() {
+    await this.bindings.switchCamera();
+  }
+
+  /** Ống kính vật lý (0.5x siêu rộng · 1x · tele) — không có thì UI kẹt ở mặc định. */
+  async listCameras(): Promise<CameraDeviceInfo[]> {
+    return this.bindings.listCameras().map((camera) => ({
+      deviceId: camera.deviceId,
+      label: camera.label,
+      facing:
+        camera.facing === "front" || camera.facing === "environment"
+          ? camera.facing
+          : "unknown",
+    }));
+  }
+
+  async selectCamera(deviceId: string, facing: CameraDeviceInfo["facing"]) {
+    await this.bindings.selectCamera(deviceId, facing);
+  }
+
+  async setMicrophoneEnabled(enabled: boolean) {
+    await this.bindings.setMicrophoneEnabled(enabled);
+  }
+
+  /** Hạ chất lượng khi mạng yếu — thay cho BWE mà WebRTC cho sẵn. */
+  async setVideoBitrate(bitsPerSecond: number) {
+    await this.bindings.setVideoBitrate(bitsPerSecond);
+  }
+
+  async setCaptureOrientation(orientation: CaptureOrientation) {
+    this.captureOrientation = orientation;
+    // Đang preview (chưa phát): prepare lại để đổi khung 9:16 ↔ 16:9 ngay —
+    // native chỉ đổi screen.frame + gắn lại camera, encoder chưa chạy.
+    // Đã kết nối thì KHÔNG đổi giữa luồng: buộc khởi động lại encoder và làm
+    // thủng segment HLS; lựa chọn sẽ áp cho lần prepare kế tiếp.
+    if (this.prepared && !this.connected) {
+      await this.bindings.prepare({
+        quality: this.quality,
+        landscape: orientation === "landscape",
+        ...this.prepareOverrides(),
+      });
+    }
+  }
+
+  subscribe(listener: (event: RoomEvent) => void) {
+    this.listeners.add(listener);
+    if (!this.nativeSubscription) {
+      this.nativeSubscription = this.bindings.addStatusListener((event) => {
+        const mapped = mapStatus(event);
+        if (mapped) this.emit(mapped);
+      });
+    }
+    if (!this.bandwidthSubscription && this.bindings.addBandwidthListener) {
+      this.bandwidthSubscription = this.bindings.addBandwidthListener((event) =>
+        this.handleBandwidth(event),
+      );
+    }
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  async dispose() {
+    this.nativeSubscription?.remove();
+    this.nativeSubscription = undefined;
+    this.bandwidthSubscription?.remove();
+    this.bandwidthSubscription = undefined;
+    this.listeners.clear();
+    this.connected = false;
+    this.bitrateState = undefined;
+    await this.bindings.dispose();
+  }
+
+  private handleBandwidth(event: RtmpBandwidth) {
+    const state = this.bitrateState;
+    if (!this.connected || !state) return;
+    const next = nextBitrateState(state, event);
+    this.bitrateState = next;
+    if (next.current !== state.current) {
+      // Fire-and-forget: chỉnh bitrate lỗi thì giữ mức cũ chứ không rớt luồng.
+      void this.bindings.setVideoBitrate(next.current).catch(() => undefined);
+    }
+  }
+
+  private emit(event: RoomEvent) {
+    for (const listener of this.listeners) listener(event);
+  }
+}
+
+/** Trạng thái native → RoomEvent của engine. `null` = không cần báo lên. */
+export function mapStatus(event: RtmpStatus): RoomEvent | null {
+  switch (event.status) {
+    case "error":
+      return { type: "media-error", error: new Error(event.message) };
+    case "disconnected":
+      return { type: "disconnected", reason: event.reason };
+    case "connecting":
+      return { type: "reconnecting" };
+    case "publishing":
+      return { type: "reconnected" };
+    // "idle"/"connected" là bước trung gian, engine không cần biết.
+    default:
+      return null;
+  }
+}

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 };