@a4anthony/proctorkit-sdk 0.1.1 → 0.2.0

package/src/preflight/system-check.ts

@@ -49,10 +49,7 @@ import {
   type ConnectionQualityOptions,
   type HttpConnectionProbeOptions,
 } from "./connection-quality.js";
-import {
-  runDeepCameraCheck,
-  type DeepCameraCheckOptions,
-} from "./deep-camera-check.js";
+import { runDeepCameraCheck, type DeepCameraCheckOptions } from "./deep-camera-check.js";
 
 export type { CheckKind, CheckOverrides, CheckRow, CheckState, FailCode };
 
@@ -122,14 +119,13 @@ export interface RequiredCapabilitiesConfig {
  */
 export interface ThresholdsConfig {
   /**
-   * Minimum download bandwidth (Mbps) for the connection check to
-   * pass. A measurement below this trips `slow-connection`.
-   * Default: 2.
+   * Download-bandwidth reference used for internal quality telemetry. Browser
+   * Mbps estimates do not decide candidate eligibility. Default: 2.
    */
   minBandwidthMbps?: number;
   /**
-   * Minimum application-path upload bandwidth (Mbps). Upload is the primary
-   * gate for continuous webcam and screen recordings. Default: 2.
+   * Upload-bandwidth reference used for internal quality telemetry. Recording
+   * readiness is derived from the enabled media workload instead. Default: 2.
    */
   minUploadBandwidthMbps?: number;
   /**
@@ -163,6 +159,52 @@ export interface ThresholdsConfig {
   allowMobile?: boolean;
 }
 
+export interface ConnectionReadinessCheckResult {
+  mode: "direct" | "segments" | "post";
+  payloadBytes: number;
+  completionWindowMs: number;
+  sampleDurationsMs: number[];
+  medianCompletionMs: number;
+}
+
+type ReadinessTelemetry = Partial<
+  Pick<
+    CheckRow,
+    | "recordingUploadMode"
+    | "readinessPayloadBytes"
+    | "readinessMedianMs"
+    | "readinessWindowMs"
+    | "readinessSampleCount"
+  >
+>;
+
+function readinessErrorDetails(error: unknown): ReadinessTelemetry {
+  if (!error || typeof error !== "object" || !("details" in error)) return {};
+  const details = (error as { details?: unknown }).details;
+  if (!details || typeof details !== "object") return {};
+  const values = details as Record<string, unknown>;
+  const mode = values["recordingUploadMode"];
+  const payloadBytes = finiteNumber(values["readinessPayloadBytes"]);
+  const medianMs = finiteNumber(values["readinessMedianMs"]);
+  const windowMs = finiteNumber(values["readinessWindowMs"]);
+  const sampleCount = finiteNumber(values["readinessSampleCount"]);
+  return {
+    ...(mode === "direct" || mode === "segments" || mode === "post"
+      ? { recordingUploadMode: mode }
+      : {}),
+    ...(payloadBytes !== undefined ? { readinessPayloadBytes: payloadBytes } : {}),
+    ...(medianMs !== undefined ? { readinessMedianMs: medianMs } : {}),
+    ...(windowMs !== undefined ? { readinessWindowMs: windowMs } : {}),
+    ...(sampleCount !== undefined
+      ? { readinessSampleCount: Math.max(0, Math.floor(sampleCount)) }
+      : {}),
+  };
+}
+
+function finiteNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
 export interface SystemCheckOptions {
   /**
    * Mode controls the row list and the short-circuit behaviour:
@@ -221,6 +263,11 @@ export interface SystemCheckOptions {
    * SDK consumers.
    */
   connectionTest?: HttpConnectionProbeOptions & ConnectionQualityOptions;
+  /**
+   * Optional workload-aware recording-path check. When supplied, this is the
+   * candidate eligibility signal; numeric speed tests remain telemetry only.
+   */
+  connectionReadiness?: () => Promise<ConnectionReadinessCheckResult>;
 }
 
 /** JSON-serialisable final report. No class instances, safe to log + persist. */
@@ -247,20 +294,9 @@ export interface SimulatedCheckResult {
  */
 export type SystemCheckListener = (rows: ReadonlyArray<CheckRow>) => void;
 
-const BROWSER_CLASS_KINDS: CheckKind[] = [
-  "browser",
-  "device",
-  "layout",
-  "monitor",
-  "connection",
-];
-
-const MEDIA_KINDS: CheckKind[] = [
-  "microphone",
-  "speaker",
-  "camera",
-  "screen-share",
-];
+const BROWSER_CLASS_KINDS: CheckKind[] = ["browser", "device", "layout", "monitor", "connection"];
+
+const MEDIA_KINDS: CheckKind[] = ["microphone", "speaker", "camera", "screen-share"];
 
 /**
  * The non-retryable front-runners. Browser and device failures are
@@ -310,6 +346,7 @@ interface ResolvedOptions {
   overrides: CheckOverrides | undefined;
   deepCamera: SystemCheckOptions["deepCamera"];
   connectionTest: SystemCheckOptions["connectionTest"];
+  connectionReadiness: SystemCheckOptions["connectionReadiness"];
 }
 
 export class SystemCheck {
@@ -336,6 +373,7 @@ export class SystemCheck {
       overrides: options.overrides,
       deepCamera: options.deepCamera,
       connectionTest: options.connectionTest,
+      connectionReadiness: options.connectionReadiness,
     };
     this.rows = this.buildInitialRows();
   }
@@ -426,11 +464,9 @@ export class SystemCheck {
           continue;
         }
         if (done) break;
-        const next = await new Promise<ReadonlyArray<CheckRow> | null>(
-          (resolve) => {
-            resolveWaiter = resolve;
-          },
-        );
+        const next = await new Promise<ReadonlyArray<CheckRow> | null>((resolve) => {
+          resolveWaiter = resolve;
+        });
         if (next === null) break;
         yield next;
       }
@@ -495,10 +531,7 @@ export class SystemCheck {
           row.state = { kind: "pass", detail: "Ready" };
         }
         this.notify();
-        if (
-          row.state.kind === "fail" &&
-          BROWSER_CLASS_KINDS.includes(row.kind)
-        ) {
+        if (row.state.kind === "fail" && BROWSER_CLASS_KINDS.includes(row.kind)) {
           browserClassFailed = true;
         }
       }
@@ -529,8 +562,7 @@ export class SystemCheck {
 
     // Short-circuit media when any system-class check failed.
     const browserClassFailed = this.rows.some(
-      (r) =>
-        r.state.kind === "fail" && BROWSER_CLASS_KINDS.includes(r.kind),
+      (r) => r.state.kind === "fail" && BROWSER_CLASS_KINDS.includes(r.kind),
     );
     if (browserClassFailed) {
       this.skipPending(MEDIA_KINDS);
@@ -548,10 +580,7 @@ export class SystemCheck {
     return this.buildReport();
   }
 
-  private async runRow(
-    kind: CheckKind,
-    compute: () => CheckState,
-  ): Promise<void> {
+  private async runRow(kind: CheckKind, compute: () => CheckState): Promise<void> {
     if (!this.hasRow(kind)) return;
     this.setState(kind, { kind: "checking", message: "Checking..." });
     await this.delay(this.options.stepDelayMs);
@@ -580,19 +609,61 @@ export class SystemCheck {
       message: "Testing connection...",
     });
     const start = performance.now();
-    const result = this.options.connectionTest
-      ? applyConnectionQualityToResult(
-          await measureConnectionQuality(
-            createHttpConnectionProbe(this.options.connectionTest),
-            this.options.connectionTest,
-          ),
-          this.options.thresholds.minBandwidthMbps,
-          this.options.thresholds.minUploadBandwidthMbps,
-        )
-      : applySpeedToResult(
-          await measureSpeed(),
-          this.options.thresholds.minBandwidthMbps,
-        );
+    let result: CheckRow;
+    if (this.options.connectionReadiness) {
+      try {
+        const readiness = await this.options.connectionReadiness();
+        result = {
+          kind: "connection",
+          state: { kind: "pass", detail: "Connection available" },
+          recordingUploadMode: readiness.mode,
+          readinessPayloadBytes: readiness.payloadBytes,
+          readinessMedianMs: readiness.medianCompletionMs,
+          readinessWindowMs: readiness.completionWindowMs,
+          readinessSampleCount: readiness.sampleDurationsMs.length,
+        };
+      } catch (error) {
+        const diagnostic =
+          error && typeof error === "object" && "code" in error
+            ? String((error as { code: unknown }).code)
+            : "unavailable";
+        const details = readinessErrorDetails(error);
+        result = {
+          kind: "connection",
+          state: {
+            kind: "fail",
+            code: "speed-test-failed",
+            detail: `Connection readiness failed: ${diagnostic}`,
+          },
+          ...(details.recordingUploadMode !== undefined
+            ? { recordingUploadMode: details.recordingUploadMode }
+            : {}),
+          ...(details.readinessPayloadBytes !== undefined
+            ? { readinessPayloadBytes: details.readinessPayloadBytes }
+            : {}),
+          ...(details.readinessMedianMs !== undefined
+            ? { readinessMedianMs: details.readinessMedianMs }
+            : {}),
+          ...(details.readinessWindowMs !== undefined
+            ? { readinessWindowMs: details.readinessWindowMs }
+            : {}),
+          ...(details.readinessSampleCount !== undefined
+            ? { readinessSampleCount: details.readinessSampleCount }
+            : {}),
+        };
+      }
+    } else {
+      result = this.options.connectionTest
+        ? applyConnectionQualityToResult(
+            await measureConnectionQuality(
+              createHttpConnectionProbe(this.options.connectionTest),
+              this.options.connectionTest,
+            ),
+            this.options.thresholds.minBandwidthMbps,
+            this.options.thresholds.minUploadBandwidthMbps,
+          )
+        : applySpeedToResult(await measureSpeed(), this.options.thresholds.minBandwidthMbps);
+    }
     const elapsed = performance.now() - start;
     if (elapsed < this.options.minSpeedTestMs) {
       await this.delay(this.options.minSpeedTestMs - elapsed);
@@ -613,6 +684,21 @@ export class SystemCheck {
     if (result.band !== undefined) {
       this.setRowField("connection", "band", result.band);
     }
+    if (result.recordingUploadMode !== undefined) {
+      this.setRowField("connection", "recordingUploadMode", result.recordingUploadMode);
+    }
+    if (result.readinessPayloadBytes !== undefined) {
+      this.setRowField("connection", "readinessPayloadBytes", result.readinessPayloadBytes);
+    }
+    if (result.readinessMedianMs !== undefined) {
+      this.setRowField("connection", "readinessMedianMs", result.readinessMedianMs);
+    }
+    if (result.readinessWindowMs !== undefined) {
+      this.setRowField("connection", "readinessWindowMs", result.readinessWindowMs);
+    }
+    if (result.readinessSampleCount !== undefined) {
+      this.setRowField("connection", "readinessSampleCount", result.readinessSampleCount);
+    }
   }
 
   /**
@@ -636,9 +722,7 @@ export class SystemCheck {
    * candidate, so mark any still-pending ones skipped and stop. Returns
    * true if the gate tripped. See {@link GATE_KINDS}.
    */
-  private async runSystemClassSequence(
-    overrides: CheckOverrides,
-  ): Promise<boolean> {
+  private async runSystemClassSequence(overrides: CheckOverrides): Promise<boolean> {
     await this.runRow("browser", () => checkBrowser(overrides).state);
     await this.runRow(
       "device",
@@ -671,9 +755,7 @@ export class SystemCheck {
 
   /** True once a non-retryable gate check (browser/device) has failed. */
   private gateTripped(): boolean {
-    return this.rows.some(
-      (r) => GATE_KINDS.includes(r.kind) && r.state.kind === "fail",
-    );
+    return this.rows.some((r) => GATE_KINDS.includes(r.kind) && r.state.kind === "fail");
   }
 
   /** Mark every still-pending row of the given kinds as skipped. */
@@ -742,11 +824,7 @@ export class SystemCheck {
       message: "Checking permission...",
     });
     const perms = await queryPermissions({ mic: false, camera: true });
-    const camState = await this.resolveCameraState(
-      perms.camera,
-      deviceId,
-      existingStream,
-    );
+    const camState = await this.resolveCameraState(perms.camera, deviceId, existingStream);
     this.setState("camera", camState.state);
     if (camState.photo) this.setRowField("camera", "photo", camState.photo);
     return { attempts: camState.attempts ?? [] };
@@ -788,10 +866,7 @@ export class SystemCheck {
     // a browser without `getDisplayMedia` will fail at session
     // start anyway, but the candidate deserves to know now while
     // they can still switch to a supported browser.
-    if (
-      typeof navigator === "undefined" ||
-      !navigator.mediaDevices?.getDisplayMedia
-    ) {
+    if (typeof navigator === "undefined" || !navigator.mediaDevices?.getDisplayMedia) {
       this.setState("screen-share", {
         kind: "fail",
         code: "screen-share-not-supported",
@@ -1059,9 +1134,8 @@ export class SystemCheck {
  * Convenience wrapper for the common case ("just run it once and give
  * me the report"). Equivalent to `new SystemCheck(options).runOnce()`.
  */
-export const runSystemCheck = async (
-  options: SystemCheckOptions = {},
-): Promise<PreflightReport> => new SystemCheck(options).runOnce();
+export const runSystemCheck = async (options: SystemCheckOptions = {}): Promise<PreflightReport> =>
+  new SystemCheck(options).runOnce();
 
 // ============================================================================
 // Permissions + media-device probing
@@ -1079,9 +1153,7 @@ interface PermissionResults {
   camera: PermissionResult;
 }
 
-const queryPermissions = async (
-  q: PermissionQuery,
-): Promise<PermissionResults> => {
+const queryPermissions = async (q: PermissionQuery): Promise<PermissionResults> => {
   const probe = async (name: PermissionName): Promise<PermissionResult> => {
     if (typeof navigator === "undefined" || !navigator.permissions) {
       return "unknown";
@@ -1147,8 +1219,7 @@ const resolveAudioInputState = async (
         detail: "Permission required",
       };
     }
-    const firstLabel =
-      pickDeviceLabel(devices, deviceId) || "Ready";
+    const firstLabel = pickDeviceLabel(devices, deviceId) || "Ready";
     return { kind: "pass", detail: firstLabel };
   }
   const devices = await enumerateAudioInputs();
@@ -1163,11 +1234,8 @@ const resolveAudioInputState = async (
   return { kind: "pass", detail: label };
 };
 
-const hasLiveVideoStream = (
-  video: HTMLVideoElement | undefined,
-): boolean => {
-  const stream =
-    video?.srcObject instanceof MediaStream ? video.srcObject : null;
+const hasLiveVideoStream = (video: HTMLVideoElement | undefined): boolean => {
+  const stream = video?.srcObject instanceof MediaStream ? video.srcObject : null;
   return stream?.getVideoTracks().some((track) => track.readyState === "live") ?? false;
 };
 
@@ -1176,10 +1244,7 @@ const hasLiveVideoStream = (
  * candidate's specific deviceId resolves, use its label; otherwise
  * fall back to the first labelled device.
  */
-const pickDeviceLabel = (
-  devices: ReadonlyArray<MediaDeviceInfo>,
-  deviceId?: string,
-): string => {
+const pickDeviceLabel = (devices: ReadonlyArray<MediaDeviceInfo>, deviceId?: string): string => {
   if (deviceId) {
     const exact = devices.find((d) => d.deviceId === deviceId);
     if (exact?.label) return exact.label;
@@ -1206,7 +1271,6 @@ const resolveSpeakerState = async (): Promise<CheckState> => {
       detail: "Grant microphone permission to list audio outputs",
     };
   }
-  const label =
-    devices.find((d) => d.label)?.label ?? "Default output";
+  const label = devices.find((d) => d.label)?.label ?? "Default output";
   return { kind: "pass", detail: label };
 };