@a4anthony/proctorkit-types 0.2.0 → 0.4.0

package/src/support-context.ts

@@ -0,0 +1,388 @@
+import type { SessionStatus } from "./session.js";
+
+/** Version of the normalized support-context response shape. */
+export type SupportContextSchemaVersion = "1";
+
+declare const supportStableCodeBrand: unique symbol;
+declare const supportStableTokenBrand: unique symbol;
+
+/**
+ * A server-normalized machine code. Domain-owned mappers must use closed
+ * mappings with an `unknown` fallback; never cast or copy raw telemetry.
+ */
+export type SupportStableCode = "unknown" | (string & { readonly [supportStableCodeBrand]: true });
+
+/**
+ * A server-normalized categorical token. Domain-owned mappers must use closed
+ * mappings with an `unknown` fallback; never cast or copy raw telemetry.
+ */
+export type SupportStableToken =
+  | "unknown"
+  | (string & { readonly [supportStableTokenBrand]: true });
+
+export type SupportSemanticVersion = `${number}.${number}.${number}`;
+export type SupportSha256Digest = `sha256:${string}`;
+export type SupportPolicyHref = `/v1/support-context/interpretation/${string}/support-policy`;
+
+export type SupportObservationState = "not_started" | "in_progress" | "complete" | "unavailable";
+
+export type SupportCheckState =
+  | "not_observed"
+  | "pending"
+  | "checking"
+  | "passed"
+  | "failed"
+  | "skipped";
+
+export type SupportCheckKind =
+  | "browser"
+  | "device"
+  | "layout"
+  | "monitor"
+  | "connection"
+  | "microphone"
+  | "speaker"
+  | "camera"
+  | "screen-share";
+
+export type SupportContextSection =
+  | "lifecycle"
+  | "policy"
+  | "preflight"
+  | "resume"
+  | "runtime"
+  | "writing";
+
+export type SupportContextCompletenessState = "empty" | "partial" | "complete";
+
+export type SupportContextWarningCode =
+  | "telemetry_best_effort"
+  | "history_truncated"
+  | "section_unavailable";
+
+export type SupportActivityState = "live" | "inactive" | "suspended";
+
+export type SupportJourneyStage = "opened" | "preflight" | "ready" | "assessment" | "completed";
+
+export type SupportPolicyDecision = "allowed" | "blocked" | "unknown";
+
+export type SupportPreflightVerdict = "not_started" | "in_progress" | "passed" | "failed";
+
+export type SupportDeviceCategory = "built_in" | "usb" | "bluetooth" | "virtual" | "unknown";
+
+export type SupportDeviceKind = "microphone" | "speaker" | "camera";
+
+export type SupportConnectionBand = "fair" | "good" | "excellent";
+
+export type SupportRecordingUploadMode = "direct" | "segments" | "post";
+
+export type SupportResumeCheckState = "checking" | "passed" | "warning" | "failed";
+
+export const SUPPORT_ISSUE_CATEGORIES = [
+  "monitor",
+  "connection",
+  "permissions",
+  "camera",
+  "audio",
+  "screen_share",
+  "compatibility",
+  "runtime_delivery",
+  "device_change",
+  "unknown",
+] as const;
+
+export type SupportIssueCategory = (typeof SUPPORT_ISSUE_CATEGORIES)[number];
+
+export type SupportIssuePhase = "preflight" | "resume" | "runtime" | "writing";
+
+export type SupportBlockedClipboardAction = "paste" | "copy" | "cut";
+
+export type SupportResumeClass =
+  | "refresh"
+  | "brief"
+  | "interruption"
+  | "returned-after-absence"
+  | "unknown";
+
+export type SupportNavigationType =
+  | "navigate"
+  | "reload"
+  | "back_forward"
+  | "prerender"
+  | "unknown";
+
+export type SupportRuntimeBlockerCategory =
+  | "device"
+  | "permission"
+  | "screen_share"
+  | "connection"
+  | "media"
+  | "reverification"
+  | "unknown";
+
+export type SupportRuntimeBlockerState = "active" | "cleared" | "unknown";
+
+export type SupportCoarseDeviceType = "desktop" | "laptop" | "tablet" | "mobile" | "unknown";
+
+export type SupportCoarseBrowser = "chrome" | "edge" | "firefox" | "safari" | "other" | "unknown";
+
+export type SupportCoarseOperatingSystem =
+  | "windows"
+  | "macos"
+  | "linux"
+  | "ios"
+  | "android"
+  | "chromeos"
+  | "other"
+  | "unknown";
+
+export type SupportCoarsePlatform = "desktop" | "tablet" | "mobile" | "unknown";
+
+export type SupportScreenSizeBucket = "small" | "medium" | "large" | "extra_large" | "unknown";
+
+export type SupportLogicalCoreBucket = "1_2" | "3_4" | "5_8" | "9_16" | "17_plus" | "unknown";
+
+export type SupportMemoryBucket =
+  | "under_4_gb"
+  | "4_7_gb"
+  | "8_15_gb"
+  | "16_31_gb"
+  | "32_plus_gb"
+  | "unknown";
+
+export interface SupportContextInterpretationIdentity {
+  contextFormatVersion: SupportSemanticVersion;
+  telemetrySchemaVersion: SupportSemanticVersion;
+  supportProjectionVersion: SupportSemanticVersion;
+  /** Lowercase SHA-256 digest with the `sha256:` prefix. */
+  supportPolicySha256: SupportSha256Digest;
+  supportPolicyHref: SupportPolicyHref;
+}
+
+export interface SupportContextWarning {
+  code: SupportContextWarningCode;
+  section?: SupportContextSection;
+}
+
+export interface SupportContextCompleteness {
+  state: SupportContextCompletenessState;
+  observedSections: SupportContextSection[];
+  /**
+   * Known sections that could not be observed. Values are stable server codes,
+   * never raw exception text.
+   */
+  missingSections: SupportContextSection[];
+  warnings: SupportContextWarning[];
+}
+
+export interface SupportContextResponse {
+  data: SupportContext;
+}
+
+export interface SupportContext {
+  schemaVersion: SupportContextSchemaVersion;
+  interpretation: SupportContextInterpretationIdentity;
+  /** ISO-8601 timestamp. */
+  generatedAt: string;
+  /** ISO-8601 timestamp of the newest persisted source included. */
+  sourceUpdatedAt: string;
+  completeness: SupportContextCompleteness;
+  identity: SupportContextIdentity;
+  lifecycle: SupportLifecycleContext;
+  policy: SupportPolicyContext;
+  preflight: SupportPreflightContext;
+  resume: SupportResumeContext;
+  runtime: SupportRuntimeContext;
+  writing: SupportWritingContext;
+}
+
+export interface SupportContextIdentity {
+  /** Server-normalized opaque digest of the customer correlation value. */
+  correlationId: string;
+  sessionId: string;
+  attemptNumber: number;
+  mode: SupportStableToken;
+  resolvedBy: "correlation_id" | "session_id";
+}
+
+export interface SupportLifecycleContext {
+  observationState: SupportObservationState;
+  sessionStatus: SessionStatus;
+  activityState: SupportActivityState;
+  journeyStage: SupportJourneyStage;
+  /** Stable machine code, never rendered or exception prose. */
+  summaryCode: SupportStableCode;
+  startedAt: string;
+  preflightStartedAt: string | null;
+  runtimeStartedAt: string | null;
+  lastActivityAt: string;
+  endedAt: string | null;
+  lockedAt: string | null;
+  /** Stable end-reason code. */
+  endReason: SupportStableCode | null;
+  requiresReverification: boolean;
+  sittingCount: number;
+}
+
+export interface SupportPolicyContext {
+  observationState: SupportObservationState;
+  /** Stable configured mode, or null when policy has not been observed. */
+  preflightMode: SupportStableToken | null;
+  requiredChecks: SupportCheckKind[];
+  optionalChecks: SupportCheckKind[];
+  disabledChecks: SupportCheckKind[];
+  clipboard: {
+    copy: SupportPolicyDecision;
+    paste: SupportPolicyDecision;
+    cut: SupportPolicyDecision;
+  };
+}
+
+export interface SupportPreflightContext {
+  observationState: SupportObservationState;
+  verdict: SupportPreflightVerdict;
+  startedAt: string | null;
+  completedAt: string | null;
+  durationMs: number | null;
+  checks: SupportCheck[];
+  devices: Partial<Record<SupportDeviceKind, SupportObservedDeviceSet>>;
+  attemptHistory: SupportPreflightAttempt[];
+}
+
+export interface SupportObservedDeviceSet {
+  selected: {
+    category: SupportDeviceCategory;
+    virtual: boolean | null;
+  } | null;
+  availableCount: number;
+  virtualCount: number;
+  lastObservedAt: string | null;
+}
+
+export interface SupportCheck {
+  kind: SupportCheckKind;
+  required: boolean;
+  state: SupportCheckState;
+  /** Stable support code, never raw browser or exception text. */
+  code: SupportStableCode | null;
+  retryCount: number;
+  durationMs: number | null;
+  lastObservedAt: string | null;
+  connection: SupportConnectionObservation | null;
+  microphoneVerification: SupportMicrophoneVerification | null;
+}
+
+export interface SupportConnectionObservation {
+  downloadMbps: number | null;
+  uploadMbps: number | null;
+  latencyMs: number | null;
+  jitterMs: number | null;
+  band: SupportConnectionBand | null;
+  recordingUploadMode: SupportRecordingUploadMode | null;
+  readinessMedianMs: number | null;
+  readinessWindowMs: number | null;
+  readinessSampleCount: number | null;
+}
+
+export interface SupportMicrophoneVerification {
+  /** Stable verification mode. */
+  mode: SupportStableToken | null;
+  /** Stable fallback code, never raw error detail. */
+  fallbackReason: SupportStableCode | null;
+  preparationMs: number | null;
+}
+
+export interface SupportPreflightAttempt {
+  attemptNumber: number;
+  origin: "wizard" | "runtime" | "unknown";
+  verdict: "in_progress" | "passed" | "failed";
+  startedAt: string;
+  completedAt: string | null;
+  durationMs: number | null;
+  sameAsCanonicalDevice: boolean | null;
+  device: SupportCoarseDeviceEnvironment | null;
+}
+
+export interface SupportCoarseDeviceEnvironment {
+  type: SupportCoarseDeviceType;
+  browser: SupportCoarseBrowser;
+  os: SupportCoarseOperatingSystem;
+  platform: SupportCoarsePlatform;
+  screenSize: SupportScreenSizeBucket;
+  logicalCores: SupportLogicalCoreBucket;
+  memory: SupportMemoryBucket;
+}
+
+export interface SupportResumeContext {
+  observationState: SupportObservationState;
+  totalResumes: number;
+  currentOrLatest: SupportResumeObservation | null;
+}
+
+export interface SupportResumeObservation {
+  observedAt: string;
+  class: SupportResumeClass;
+  awayMs: number | null;
+  navigationType: SupportNavigationType | null;
+  completed: boolean;
+  checks: SupportResumeCheck[];
+  changedDevices: SupportCheckKind[];
+}
+
+export interface SupportResumeCheck {
+  kind: SupportCheckKind;
+  state: SupportResumeCheckState;
+  /** Stable reason code. */
+  reason: SupportStableCode | null;
+}
+
+export interface SupportRuntimeContext {
+  observationState: SupportObservationState;
+  activeBlocker: SupportRuntimeBlocker | null;
+  primaryIssue: SupportIssue | null;
+  issues: SupportIssue[];
+  delivery: SupportDeliverySummary;
+}
+
+export interface SupportRuntimeBlocker {
+  openedAt: string;
+  category: SupportRuntimeBlockerCategory;
+  state: SupportRuntimeBlockerState;
+}
+
+export interface SupportIssue {
+  category: SupportIssueCategory;
+  phase: SupportIssuePhase;
+  check: SupportCheckKind | null;
+  /** Stable support code. */
+  code: SupportStableCode;
+  occurrences: number;
+  firstSeenAt: string | null;
+  lastSeenAt: string;
+  blocking: boolean;
+  resolvedAt: string | null;
+}
+
+export interface SupportDeliverySummary {
+  sdkErrors: number;
+  uploadFailures: number;
+  mediaFailures: number;
+  workerFailures: number;
+  drainTimeouts: number;
+  lastFailureAt: string | null;
+  /** Stable failure code, never raw exception text. */
+  lastFailureCode: SupportStableCode | null;
+}
+
+export interface SupportWritingContext {
+  observationState: SupportObservationState;
+  saveFailures: number;
+  lastSaveFailure: { code: SupportStableCode; observedAt: string } | null;
+  clipboard: {
+    blockedPasteAttempts: number;
+    blockedCopyAttempts: number;
+    blockedCutAttempts: number;
+    lastBlockedAction: SupportBlockedClipboardAction | null;
+    lastBlockedAt: string | null;
+  };
+}

package/src/worker-protocol.ts

@@ -44,6 +44,7 @@ export type DeliveryReadinessErrorCode =
   | "upload-config-unreachable"
   | "upload-config-invalid"
   | "media-storage-timeout"
+  | "media-storage-too-slow"
   | "media-storage-unreachable"
   | "media-storage-rejected"
   | "media-storage-invalid-response";