ersatztv/web/src/mediaSources/pinFlowPoll.ts

// The Plex OAuth pin-flow poll STATE MACHINE (design §C1 step 5), as a pure, timer-free module so
// the transitions can be unit-tested with injected state. The Plex screen (slice S6b) drives it:
// after `POST /pin-flow` it opens the auth URL and polls `GET /api/media-sources/plex` every 2s for
// up to 150s, feeding each observation ({ isLocked, isAuthorized }) here to decide what to show and
// whether to keep polling.
//
// KEY INSIGHT (finding 5): `isAuthorized` flips true the moment the token is saved, which is BEFORE
// SynchronizePlexMediaSources discovers the servers and releases the Plex lock. So authorization
// alone is NOT success — the terminal success signal is the lock RELEASING while authorized. Poll
// until the lock releases, not until authorized.
//
//   isLocked & !isAuthorized  -> waiting            (keep polling; user hasn't authorized yet)
//   isLocked &  isAuthorized  -> finalizing         (keep polling; discovering servers)
//  !isLocked &  isAuthorized  -> success            (terminal)
//  !isLocked & !isAuthorized  -> timeout            (terminal; flow ended without auth)
//   isLocked (budget spent)   -> budget-exhausted   (terminal; a large first sync legitimately
//                                                     still holds the lock — not a failure)

export type PinFlowStatus = 'waiting' | 'finalizing' | 'success' | 'timeout' | 'budget-exhausted';

export interface PinFlowObservation {
  isLocked: boolean;
  isAuthorized: boolean;
}

export interface PinFlowState {
  status: PinFlowStatus;
  /** True once the machine has settled and polling should stop. */
  done: boolean;
  /** True only on the successful terminal state. */
  ok: boolean;
  /** User-facing message for the current state. */
  message: string;
}

/** Poll cadence and total budget (design §C1: every 2s for up to 150s). */
export const PIN_FLOW_POLL_INTERVAL_MS = 2000;
export const PIN_FLOW_POLL_BUDGET_MS = 150_000;

const MESSAGES: Record<PinFlowStatus, string> = {
  waiting: 'Waiting for you to authorize in the Plex tab…',
  finalizing: 'Authorized — discovering your Plex servers…',
  success: 'Connected to Plex.',
  timeout: 'Plex sign-in timed out — try again.',
  'budget-exhausted': 'Still working — this can take a while on a large first sync. Use Refresh to check again.'
};

function stateFor(status: PinFlowStatus): PinFlowState {
  return {
    status,
    done: status === 'success' || status === 'timeout' || status === 'budget-exhausted',
    ok: status === 'success',
    message: MESSAGES[status]
  };
}

/** The state shown before the first poll observation arrives. */
export function initialPinFlowState(): PinFlowState {
  return stateFor('waiting');
}

/** True when the elapsed poll time has consumed the whole budget. */
export function isPinFlowBudgetExhausted(elapsedMs: number): boolean {
  return elapsedMs >= PIN_FLOW_POLL_BUDGET_MS;
}

/**
 * Evaluate a single poll observation. `budgetExhausted` reflects whether the poll budget is spent;
 * it only matters while the lock is still held (a released lock is always terminal, success or
 * timeout, regardless of budget).
 */
export function evaluatePinFlow(
  observation: PinFlowObservation,
  options: { budgetExhausted?: boolean } = {}
): PinFlowState {
  const { isLocked, isAuthorized } = observation;

  // Lock released: terminal either way. Success iff authorized.
  if (!isLocked) {
    return stateFor(isAuthorized ? 'success' : 'timeout');
  }

  // Still locked but out of budget: not a failure, just "still working".
  if (options.budgetExhausted) {
    return stateFor('budget-exhausted');
  }

  // Still locked, budget remaining: waiting for auth, or finalizing after auth.
  return stateFor(isAuthorized ? 'finalizing' : 'waiting');
}