@pickleball/expo-sdk 0.1.1

package/src/contracts.ts

@@ -0,0 +1,211 @@
+export type LivestreamState =
+  | "idle"
+  | "preparing"
+  | "preview"
+  | "connecting"
+  /** Đã vào phòng, chưa phát — chờ lệnh phát từ app hoặc dashboard. */
+  | "standby"
+  | "live"
+  | "reconnecting"
+  | "ending"
+  | "ended"
+  | "error";
+
+export type SdkErrorCode =
+  | "PERMISSION_DENIED"
+  | "NETWORK_UNAVAILABLE"
+  | "TOKEN_EXPIRED"
+  | "SDK_UPGRADE_REQUIRED"
+  | "SESSION_CONFLICT"
+  | "RECORDING_FAILED"
+  | "CONSENT_REQUIRED"
+  | "SDK_DISABLED"
+  | "UNKNOWN";
+
+export interface SdkError {
+  code: SdkErrorCode;
+  message: string;
+}
+
+export interface BootstrapInput {
+  sdkVersion: string;
+  platform: "ios" | "android";
+  bundleId: string;
+  installationId: string;
+}
+
+export interface SdkRemoteConfig {
+  enabled: boolean;
+  protocolVersion: 1;
+  minSdkVersion: string;
+  recommendedSdkVersion: string;
+  videoQuality: 720 | 1080;
+  reconnectTimeoutMs: number;
+  backgroundGraceMs: number;
+  telemetryIntervalMs: number;
+  maxSessionDurationMs: number;
+  /** Tự kết thúc phiên nếu ngồi standby quá lâu không phát (mặc định 15 phút). */
+  standbyTimeoutMs?: number;
+}
+
+export interface SdkBootstrap {
+  config: SdkRemoteConfig;
+  serverTime: number;
+  rolloutEnabled: boolean;
+  message?: string;
+}
+
+export interface StartLivestreamInput {
+  externalSessionId: string;
+  title: string;
+  visibility?: "public" | "private";
+  consentVersion: string;
+  metadata?: Record<string, string>;
+  /**
+   * true: vào phòng ở chế độ chờ (không publish) — server giữ status
+   * "scheduled" và KHÔNG khởi động recording egress cho tới khi publish.
+   * Engine tự đặt cờ này theo options.autoPublish; app không cần truyền.
+   */
+  standby?: boolean;
+}
+
+export interface SdkTelemetryCredentials {
+  endpoint: string;
+  token: string;
+  expiresAt: number;
+}
+
+export interface SdkSessionGrant {
+  sessionId: string;
+  serverUrl: string;
+  participantToken: string;
+  playbackUrl: string | null;
+  tokenExpiresAt: number;
+  telemetry: SdkTelemetryCredentials;
+  config: SdkRemoteConfig;
+}
+
+export interface SdkSessionRefresh {
+  participantToken?: string;
+  tokenExpiresAt?: number;
+  telemetry?: SdkTelemetryCredentials;
+  config: SdkRemoteConfig;
+}
+
+export interface EndLivestreamInput {
+  sessionId: string;
+  reason:
+    | "user"
+    | "background_timeout"
+    | "network_timeout"
+    | "standby_timeout"
+    | "error";
+}
+
+export type EndReason = EndLivestreamInput["reason"];
+
+export const SDK_TELEMETRY_EVENT_NAMES = [
+  "state_changed",
+  "connection_quality",
+  "reconnect",
+  "error",
+  "heartbeat",
+  "session_ended",
+] as const;
+
+export type SdkTelemetryEventName =
+  (typeof SDK_TELEMETRY_EVENT_NAMES)[number];
+
+export interface SdkTelemetryEvent {
+  sessionId: string;
+  at: number;
+  name: SdkTelemetryEventName;
+  data?: Record<string, unknown>;
+}
+
+export interface LivestreamSessionProvider {
+  bootstrap(input: BootstrapInput): Promise<SdkBootstrap>;
+  start(input: StartLivestreamInput): Promise<SdkSessionGrant>;
+  refresh(sessionId: string): Promise<SdkSessionRefresh>;
+  end(input: EndLivestreamInput): Promise<void>;
+  /**
+   * Báo server bắt đầu phát thật (standby → live): server bật recording
+   * egress + chuyển status live TRƯỚC khi engine publish track. Optional để
+   * giữ tương thích provider cũ — thiếu thì engine bỏ qua bước server.
+   */
+  publish?(sessionId: string): Promise<void>;
+  /** Báo server tạm dừng phát (live → standby): dừng egress, status về chờ. */
+  unpublish?(sessionId: string): Promise<void>;
+}
+
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+
+const CONFIG_DURATION_LIMITS = {
+  reconnectTimeoutMs: 10 * 60_000,
+  backgroundGraceMs: 10 * 60_000,
+  telemetryIntervalMs: 60 * 60_000,
+  maxSessionDurationMs: 24 * 60 * 60_000,
+} as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isPositiveDuration(value: unknown, maximum: number) {
+  return (
+    typeof value === "number" &&
+    Number.isFinite(value) &&
+    value > 0 &&
+    value <= maximum
+  );
+}
+
+export function isSdkRemoteConfig(value: unknown): value is SdkRemoteConfig {
+  return (
+    isRecord(value) &&
+    typeof value.enabled === "boolean" &&
+    value.protocolVersion === 1 &&
+    typeof value.minSdkVersion === "string" &&
+    SEMVER.test(value.minSdkVersion) &&
+    typeof value.recommendedSdkVersion === "string" &&
+    SEMVER.test(value.recommendedSdkVersion) &&
+    (value.videoQuality === 720 || value.videoQuality === 1080) &&
+    isPositiveDuration(
+      value.reconnectTimeoutMs,
+      CONFIG_DURATION_LIMITS.reconnectTimeoutMs,
+    ) &&
+    isPositiveDuration(
+      value.backgroundGraceMs,
+      CONFIG_DURATION_LIMITS.backgroundGraceMs,
+    ) &&
+    isPositiveDuration(
+      value.telemetryIntervalMs,
+      CONFIG_DURATION_LIMITS.telemetryIntervalMs,
+    ) &&
+    isPositiveDuration(
+      value.maxSessionDurationMs,
+      CONFIG_DURATION_LIMITS.maxSessionDurationMs,
+    )
+  );
+}
+
+export function compareSemver(left: string, right: string): -1 | 0 | 1 {
+  const a = SEMVER.exec(left);
+  const b = SEMVER.exec(right);
+  if (!a || !b) throw new TypeError("Invalid semantic version");
+  for (let index = 1; index < 4; index += 1) {
+    const av = BigInt(a[index]);
+    const bv = BigInt(b[index]);
+    if (av < bv) return -1;
+    if (av > bv) return 1;
+  }
+  return 0;
+}
+
+export function isSdkVersionSupported(version: string, minimum: string) {
+  try {
+    return compareSemver(version, minimum) >= 0;
+  } catch {
+    return false;
+  }
+}