@pickleball/expo-sdk 0.1.1

package/src/errors.ts

@@ -0,0 +1,128 @@
+import type { SdkErrorCode } from "./contracts";
+
+export type ExpoSdkErrorCode =
+  | SdkErrorCode
+  | "CONFIGURATION_ERROR"
+  | "UNSUPPORTED_RUNTIME"
+  | "INVALID_RESPONSE"
+  | "TIMEOUT";
+
+export class PickleballExpoError extends Error {
+  constructor(
+    message: string,
+    readonly code: ExpoSdkErrorCode,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = "PickleballExpoError";
+  }
+}
+
+function namedError(
+  name: string,
+  code: ExpoSdkErrorCode,
+  fallback: string,
+) {
+  return class extends PickleballExpoError {
+    constructor(message = fallback, options?: ErrorOptions) {
+      super(message, code, options);
+      this.name = name;
+    }
+  };
+}
+
+export class PermissionDeniedError extends namedError(
+  "PermissionDeniedError",
+  "PERMISSION_DENIED",
+  "Camera and microphone permissions are required",
+) {}
+export class NetworkUnavailableError extends namedError(
+  "NetworkUnavailableError",
+  "NETWORK_UNAVAILABLE",
+  "A network connection is required",
+) {}
+export class TokenExpiredError extends namedError(
+  "TokenExpiredError",
+  "TOKEN_EXPIRED",
+  "The livestream token expired",
+) {}
+export class UnsupportedSdkError extends namedError(
+  "UnsupportedSdkError",
+  "SDK_UPGRADE_REQUIRED",
+  "This SDK version is no longer supported",
+) {}
+export class UnsupportedRuntimeError extends namedError(
+  "UnsupportedRuntimeError",
+  "UNSUPPORTED_RUNTIME",
+  "Pickleball Live requires an iOS or Android Expo Development Build; Expo Go and web are unsupported",
+) {}
+export class SessionConflictError extends namedError(
+  "SessionConflictError",
+  "SESSION_CONFLICT",
+  "This livestream session conflicts with an active session",
+) {}
+export class RecordingFailureError extends namedError(
+  "RecordingFailureError",
+  "RECORDING_FAILED",
+  "The server recording could not be created",
+) {}
+export class ConsentRequiredError extends namedError(
+  "ConsentRequiredError",
+  "CONSENT_REQUIRED",
+  "Recording consent is required",
+) {}
+export class SdkDisabledError extends namedError(
+  "SdkDisabledError",
+  "SDK_DISABLED",
+  "Livestreaming is disabled for this app",
+) {}
+export class ExpoSdkConfigurationError extends namedError(
+  "ExpoSdkConfigurationError",
+  "CONFIGURATION_ERROR",
+  "The Expo SDK is not configured correctly",
+) {}
+export class InvalidResponseError extends namedError(
+  "InvalidResponseError",
+  "INVALID_RESPONSE",
+  "The session server returned an invalid response",
+) {}
+export class ExpoSdkTimeoutError extends namedError(
+  "ExpoSdkTimeoutError",
+  "TIMEOUT",
+  "The request timed out",
+) {}
+export class UnknownSdkError extends namedError(
+  "UnknownSdkError",
+  "UNKNOWN",
+  "An unknown livestream error occurred",
+) {}
+
+const known: Record<SdkErrorCode, new (message?: string) => PickleballExpoError> = {
+  PERMISSION_DENIED: PermissionDeniedError,
+  NETWORK_UNAVAILABLE: NetworkUnavailableError,
+  TOKEN_EXPIRED: TokenExpiredError,
+  SDK_UPGRADE_REQUIRED: UnsupportedSdkError,
+  SESSION_CONFLICT: SessionConflictError,
+  RECORDING_FAILED: RecordingFailureError,
+  CONSENT_REQUIRED: ConsentRequiredError,
+  SDK_DISABLED: SdkDisabledError,
+  UNKNOWN: UnknownSdkError,
+};
+
+export function errorFromCode(code: string, message?: string) {
+  const Constructor = known[code as SdkErrorCode] ?? UnknownSdkError;
+  return new Constructor(message);
+}
+
+export function normalizeError(error: unknown): PickleballExpoError {
+  if (error instanceof PickleballExpoError) return error;
+  if (error instanceof Error) {
+    const code = (error as Error & { code?: string }).code;
+    if (code) return errorFromCode(code, error.message);
+    if (error instanceof TypeError) {
+      return new NetworkUnavailableError(undefined, { cause: error });
+    }
+    return new UnknownSdkError(error.message, { cause: error });
+  }
+  return new UnknownSdkError();
+}

package/src/http-session-provider.ts

@@ -0,0 +1,259 @@
+import type {
+  BootstrapInput,
+  EndLivestreamInput,
+  LivestreamSessionProvider,
+  SdkBootstrap,
+  SdkSessionGrant,
+  SdkSessionRefresh,
+  SdkTelemetryCredentials,
+  StartLivestreamInput,
+} from "./contracts";
+import { isSdkRemoteConfig } from "./contracts";
+import {
+  ExpoSdkConfigurationError,
+  ExpoSdkTimeoutError,
+  InvalidResponseError,
+  NetworkUnavailableError,
+  PickleballExpoError,
+  errorFromCode,
+} from "./errors";
+
+type Fetch = typeof globalThis.fetch;
+type HeadersInput = Record<string, string>;
+
+export interface HttpSessionProviderPaths {
+  bootstrap: string;
+  sessions: string;
+  refresh(sessionId: string): string;
+  end(sessionId: string): string;
+  publish(sessionId: string): string;
+  unpublish(sessionId: string): string;
+}
+
+export interface HttpSessionProviderOptions {
+  /** Base URL of the partner-owned mobile proxy. Never the Pickleball API URL. */
+  baseUrl: string;
+  fetch?: Fetch;
+  headers?: HeadersInput | (() => HeadersInput | Promise<HeadersInput>);
+  timeoutMs?: number;
+  paths?: Partial<HttpSessionProviderPaths>;
+}
+
+const defaultPaths: HttpSessionProviderPaths = {
+  bootstrap: "/bootstrap",
+  sessions: "/sessions",
+  refresh: (sessionId) => `/sessions/${encodeURIComponent(sessionId)}/refresh`,
+  end: (sessionId) => `/sessions/${encodeURIComponent(sessionId)}/end`,
+  publish: (sessionId) => `/sessions/${encodeURIComponent(sessionId)}/publish`,
+  unpublish: (sessionId) =>
+    `/sessions/${encodeURIComponent(sessionId)}/unpublish`,
+};
+
+export function createHttpSessionProvider(
+  options: HttpSessionProviderOptions,
+): LivestreamSessionProvider {
+  const baseUrl = normalizeBaseUrl(options.baseUrl);
+  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(joinUrl(baseUrl, path), {
+        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 bootstrap(input: BootstrapInput) {
+      const data = await post(paths.bootstrap, input);
+      if (!isBootstrap(data)) throw new InvalidResponseError();
+      return data;
+    },
+    async start(input: StartLivestreamInput) {
+      const data = await post(paths.sessions, input);
+      if (!isSessionGrant(data)) throw new InvalidResponseError();
+      return data;
+    },
+    async refresh(sessionId: string) {
+      const data = await post(paths.refresh(sessionId), {});
+      if (!isSessionRefresh(data)) throw new InvalidResponseError();
+      return data;
+    },
+    async end(input: EndLivestreamInput) {
+      const data = await post(paths.end(input.sessionId), input);
+      if (data !== null && data !== undefined) throw new InvalidResponseError();
+    },
+    async publish(sessionId: string) {
+      const data = await post(paths.publish(sessionId), { sessionId });
+      if (!isSessionStatus(data)) throw new InvalidResponseError();
+    },
+    async unpublish(sessionId: string) {
+      const data = await post(paths.unpublish(sessionId), { sessionId });
+      if (!isSessionStatus(data)) throw new InvalidResponseError();
+    },
+  };
+}
+
+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})$/;
+
+function normalizeBaseUrl(value: 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)",
+    );
+  }
+}
+
+function joinUrl(base: string, path: string) {
+  return `${base}/${path.replace(/^\/+/, "")}`;
+}
+
+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);
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+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")
+  );
+}
+
+function isTelemetry(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)
+  );
+}
+
+function isSessionGrant(value: unknown): value is SdkSessionGrant {
+  return (
+    isRecord(value) &&
+    typeof value.sessionId === "string" &&
+    value.sessionId.length > 0 &&
+    typeof value.serverUrl === "string" &&
+    /^wss:\/\//.test(value.serverUrl) &&
+    typeof value.participantToken === "string" &&
+    value.participantToken.length > 0 &&
+    (value.playbackUrl === null || typeof value.playbackUrl === "string") &&
+    isFiniteNumber(value.tokenExpiresAt) &&
+    isTelemetry(value.telemetry) &&
+    isSdkRemoteConfig(value.config)
+  );
+}
+
+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
+  );
+}
+
+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 || isTelemetry(value.telemetry);
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export * from "./contracts";
+export * from "./match/contracts";
+export * from "./match/engine";
+export { replayMatchEvents, undoLastMatchEvent } from "./match/replay";
+export * from "./match/persistence";
+export * from "./match/provider";
+export * from "./match/remote";
+export * from "./match/voice";
+export * from "./errors";
+export * from "./engine";
+export * from "./http-session-provider";
+export * from "./livekit-room-adapter";
+export * from "./native-runtime";
+export * from "./provider";
+export * from "./livestream-screen";
+export * from "./version";