Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

15.6 KB
Raw Blame
import type {
  AnalyticsParticipation,
  Leaderboard,
  LeaderboardAccess,
  LeaderboardAccessScope,
  LeaderboardMetric,
  LeaderboardRange,
} from "../types/electron";
import {
  clearPendingLeaderboardLeave,
  readPendingLeaderboardLeave,
  recordPendingLeaderboardLeaveAttempt,
  writePendingLeaderboardLeave,
} from "../lib/pendingLeaderboardLeave";
import {
  getAuthRequestContextSnapshot,
  getValidatedAuthGeneration,
} from "../lib/authRequestContext";
import {
  cloudGet,
  cloudGetForAuthGeneration,
  cloudPatchForAuthGeneration,
  CloudApiError,
} from "./cloudApi";

export interface LeaderboardParticipationAuthContext {
  userId: string;
  authGeneration: number;
}

// The API lists 52 weeks of history plus the current week when it has no rows
// of its own, so anything longer is not a board this client can have asked for.
const LEADERBOARD_MAX_WEEK_STARTS = 53;

// The refresh window drives setInterval, which silently clamps a delay past a
// signed 32-bit millisecond count to 1ms — turning an implausible value into a
// request loop against an endpoint that re-aggregates the roster on every call.
const LEADERBOARD_MAX_REFRESH_SECONDS = 86_400;

const LEADERBOARD_METRICS = new Set<LeaderboardMetric>([
  "total_words",
  "words_per_minute",
  "current_daily_streak",
  "desktop_words",
  "mobile_words",
]);
const LEADERBOARD_ACCESS_STATES = new Set([
  "ready",
  "invite",
  "accept_invite",
  "request_join",
  "create",
]);

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

function isNullableString(value: unknown): value is string | null {
  return value === null || typeof value === "string";
}

function isNonnegativeInteger(value: unknown): value is number {
  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
}

// The week picker formats these with Intl in the render body, where an
// unparseable value throws past every async fallback. "Is a string" is not
// enough: the round trip also rejects a well-shaped day that does not exist.
function isCalendarDate(value: unknown): value is string {
  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
  const parsed = new Date(`${value}T00:00:00.000Z`);
  return Number.isFinite(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
}

function responseData(value: unknown, label: string): unknown {
  if (!isRecord(value) || !("data" in value)) {
    throw new Error(`Malformed ${label} response from cloud`);
  }
  return value.data;
}

function isParticipation(value: unknown): value is AnalyticsParticipation {
  return (
    isRecord(value) &&
    typeof value.configured === "boolean" &&
    typeof value.enabled === "boolean" &&
    isNullableString(value.updatedAt)
  );
}

function isAccessScope(value: unknown): value is LeaderboardAccessScope {
  return (
    isRecord(value) &&
    typeof value.key === "string" &&
    (value.kind === "workspace" || value.kind === "domain") &&
    typeof value.id === "string" &&
    typeof value.name === "string" &&
    isNonnegativeInteger(value.memberCount) &&
    (value.state === "ready" || value.state === "invite") &&
    (value.role === null ||
      value.role === "owner" ||
      value.role === "admin" ||
      value.role === "member")
  );
}

function isInvitation(value: unknown): boolean {
  return (
    value === null ||
    (isRecord(value) &&
      typeof value.workspaceId === "string" &&
      typeof value.workspaceName === "string" &&
      isNullableString(value.inviterName))
  );
}

function isJoinableWorkspace(value: unknown): boolean {
  return (
    value === null ||
    (isRecord(value) &&
      typeof value.id === "string" &&
      typeof value.name === "string" &&
      isNonnegativeInteger(value.memberCount) &&
      (value.requestState === "none" || value.requestState === "pending"))
  );
}

function isLeaderboardAccess(value: unknown): value is LeaderboardAccess {
  return (
    isRecord(value) &&
    LEADERBOARD_ACCESS_STATES.has(String(value.state)) &&
    Array.isArray(value.scopes) &&
    value.scopes.every(isAccessScope) &&
    isNullableString(value.domain) &&
    isNonnegativeInteger(value.colleagueCount) &&
    isInvitation(value.invitation) &&
    isJoinableWorkspace(value.joinableWorkspace)
  );
}

function isLeaderboardMember(value: unknown): boolean {
  return (
    isRecord(value) &&
    typeof value.userId === "string" &&
    isNullableString(value.name) &&
    isNullableString(value.email) &&
    isNullableString(value.image) &&
    isNonnegativeInteger(value.totalWords) &&
    isNonnegativeInteger(value.desktopWords) &&
    isNonnegativeInteger(value.mobileWords) &&
    (value.averageWpm === null || isNonnegativeInteger(value.averageWpm)) &&
    isNonnegativeInteger(value.currentStreakDays) &&
    isNonnegativeInteger(value.rank) &&
    value.rank > 0
  );
}

function isLeaderboard(value: unknown): value is Leaderboard {
  if (!isRecord(value) || !isRecord(value.scope)) return false;
  return (
    typeof value.scope.key === "string" &&
    (value.scope.kind === "workspace" || value.scope.kind === "domain") &&
    typeof value.scope.id === "string" &&
    typeof value.scope.name === "string" &&
    isNullableString(value.viewerUserId) &&
    LEADERBOARD_METRICS.has(value.metric as LeaderboardMetric) &&
    (value.range === "week" || value.range === "all") &&
    (value.weekStart === null || isCalendarDate(value.weekStart)) &&
    Array.isArray(value.availableWeekStarts) &&
    value.availableWeekStarts.length <= LEADERBOARD_MAX_WEEK_STARTS &&
    value.availableWeekStarts.every(isCalendarDate) &&
    Array.isArray(value.leaders) &&
    value.leaders.every(isLeaderboardMember) &&
    Array.isArray(value.members) &&
    value.members.every(isLeaderboardMember) &&
    isNonnegativeInteger(value.totalMembers) &&
    (value.viewerRank === null ||
      (isNonnegativeInteger(value.viewerRank) && value.viewerRank > 0)) &&
    isNonnegativeInteger(value.page) &&
    isNonnegativeInteger(value.pageSize) &&
    value.pageSize > 0 &&
    typeof value.generatedAt === "string" &&
    typeof value.refreshAfterSeconds === "number" &&
    Number.isFinite(value.refreshAfterSeconds) &&
    value.refreshAfterSeconds > 0 &&
    value.refreshAfterSeconds <= LEADERBOARD_MAX_REFRESH_SECONDS
  );
}

const participationOperationTails = new Map<string, Promise<void>>();

async function serializeParticipationOperation<T>(
  context: LeaderboardParticipationAuthContext,
  mutation: () => Promise<T>
): Promise<T> {
  const { userId, authGeneration } = context;
  const previous = participationOperationTails.get(userId) ?? Promise.resolve();
  let release!: () => void;
  const tail = new Promise<void>((resolve) => {
    release = resolve;
  });
  participationOperationTails.set(userId, tail);
  await previous;
  try {
    const runForCapturedAccount = async () => {
      const current = getAuthRequestContextSnapshot();
      if (
        current.sessionUserId !== userId ||
        current.sessionGeneration !== authGeneration ||
        getValidatedAuthGeneration() !== authGeneration
      ) {
        throw new CloudApiError(
          "Authentication context changed before leaderboard participation could be reconciled",
          0,
          "AUTH_CONTEXT_CHANGED"
        );
      }
      return mutation();
    };
    const locks = globalThis.navigator?.locks;
    if (locks) {
      return await locks.request(
        `openwhispr-leaderboard-participation:${userId}`,
        runForCapturedAccount
      );
    }
    return await runForCapturedAccount();
  } finally {
    release();
    if (participationOperationTails.get(userId) === tail) {
      participationOperationTails.delete(userId);
    }
  }
}

async function getParticipation(
  context: LeaderboardParticipationAuthContext
): Promise<AnalyticsParticipation> {
  return serializeParticipationOperation(context, async () => {
    try {
      const response = await cloudGetForAuthGeneration<unknown>(
        "/api/analytics/participation",
        context.authGeneration
      );
      const participation = responseData(response, "leaderboard participation");
      if (!isParticipation(participation)) {
        throw new Error("Malformed leaderboard participation response from cloud");
      }
      return participation;
    } catch (error) {
      // During the staggered rollout, an older API has no participation route.
      // Preserve the existing Insights preference until the API is upgraded.
      if (error instanceof CloudApiError && error.status === 404) {
        return { configured: false, enabled: false, updatedAt: null };
      }
      throw error;
    }
  });
}

async function setParticipation(
  enabled: boolean,
  authGeneration: number
): Promise<AnalyticsParticipation> {
  const response = await cloudPatchForAuthGeneration<unknown>(
    "/api/analytics/participation",
    // Joining starts account history reconciliation, so carry the calendar
    // zone known by this device. Leaving does not start reconciliation.
    enabled
      ? { enabled, timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC" }
      : { enabled },
    authGeneration
  );
  const participation = responseData(response, "leaderboard participation");
  if (!isParticipation(participation)) {
    throw new Error("Malformed leaderboard participation response from cloud");
  }
  return participation;
}

// Codes the main process raises from its auth fence, which runs before the
// request is put on the wire. Nothing reached the API under either of them.
const LOCAL_AUTH_FENCE_CODES = new Set(["AUTH_CONTEXT_CHANGED", "AUTH_CONTEXT_UNVALIDATED"]);

type ParticipationWriteOutcome = "applied" | "refused" | "not_sent" | "unknown";

/**
 * What a failed participation write actually did to the account row.
 *
 * `applied` — cloudPatchForAuthGeneration raises CloudApiError for every
 * transport and HTTP failure, so any other error escaped while reading a body
 * the API had already answered 2xx with. The write landed; only the answer was
 * unreadable.
 * `refused` — a 4xx is the server's own verdict on a request it declined to act
 * on, so the row is untouched.
 * `not_sent` — fenced on this device; the request never left.
 * `unknown` — no response or a server error, so the row may or may not have moved.
 *
 * Only `unknown` needs compensating: banking a leave for the other three either
 * undoes work the account asked for, or strands a record with nothing to undo.
 */
function classifyParticipationWriteFailure(error: unknown): ParticipationWriteOutcome {
  if (!(error instanceof CloudApiError)) return "applied";
  if (error.code != null && LOCAL_AUTH_FENCE_CODES.has(error.code)) return "not_sent";
  if (error.status >= 400 && error.status < 500) return "refused";
  return "unknown";
}

async function joinParticipation(
  context: LeaderboardParticipationAuthContext
): Promise<AnalyticsParticipation> {
  const { userId, authGeneration } = context;
  return serializeParticipationOperation(context, async () => {
    clearPendingLeaderboardLeave(userId);
    try {
      return await setParticipation(true, authGeneration);
    } catch (error) {
      if (classifyParticipationWriteFailure(error) === "unknown") {
        writePendingLeaderboardLeave(userId);
      }
      throw error;
    }
  });
}

async function leaveParticipation(
  context: LeaderboardParticipationAuthContext
): Promise<AnalyticsParticipation> {
  const { userId, authGeneration } = context;
  // Persist the intent before it can wait. If auth changes while this operation
  // is queued, the request is fenced but the original account's leave survives.
  writePendingLeaderboardLeave(userId);
  return serializeParticipationOperation(context, async () => {
    try {
      const participation = await setParticipation(false, authGeneration);
      clearPendingLeaderboardLeave(userId);
      return participation;
    } catch (error) {
      settleUndeliveredLeave(userId, error);
      throw error;
    }
  });
}

/**
 * Retires a pending leave the API has already acted on or can never act on, and
 * otherwise charges it one attempt so it cannot preempt the sync throttle
 * forever. Returns whether the account is still waiting to come off the board.
 */
function settleUndeliveredLeave(userId: string, error: unknown): boolean {
  const outcome = classifyParticipationWriteFailure(error);
  // The row is already false — the API accepted the PATCH and only its answer
  // was unreadable, so there is nothing left to retry.
  if (outcome === "applied") {
    clearPendingLeaderboardLeave(userId);
    return false;
  }
  // An API without the participation route cannot be holding the account on a
  // leaderboard, so the leave has nothing to deliver. Every other refusal is
  // kept: a 429 or a 401 is answered by retrying later, not by dropping the
  // account's opt-out.
  if (outcome === "refused" && error instanceof CloudApiError && error.status === 404) {
    clearPendingLeaderboardLeave(userId);
    return false;
  }
  recordPendingLeaderboardLeaveAttempt(userId);
  return true;
}

/**
 * Retries a leave the user already asked for and the network never delivered,
 * for that account only: a device may take itself off a leaderboard, never put
 * itself on one. Returns whether the account is still waiting for it.
 *
 * The record survives every outcome that leaves the account row untouched, and
 * flushes are trigger-driven (a sync pass, a participation read), so a request
 * that keeps failing costs one call per trigger rather than a loop. It is
 * retired only once the API has acted on it or has shown it never can — see
 * settleUndeliveredLeave.
 */
async function flushPendingLeave(context: LeaderboardParticipationAuthContext): Promise<boolean> {
  const { userId, authGeneration } = context;
  return serializeParticipationOperation(context, async () => {
    // Check inside the mutation lock: an explicit join queued ahead of this
    // retry retires the older leave before it can issue a stale PATCH false.
    if (!readPendingLeaderboardLeave(userId)) return false;
    try {
      await setParticipation(false, authGeneration);
      clearPendingLeaderboardLeave(userId);
      return false;
    } catch (error) {
      console.error("Retrying the leaderboard leave failed:", error);
      return settleUndeliveredLeave(userId, error);
    }
  });
}

async function getAccess(): Promise<LeaderboardAccess> {
  const response = await cloudGet<unknown>("/api/leaderboard/access");
  const access = responseData(response, "leaderboard access");
  if (!isLeaderboardAccess(access))
    throw new Error("Malformed leaderboard access response from cloud");
  return access;
}

async function getLeaderboard(
  scope: LeaderboardAccessScope,
  query: {
    metric: LeaderboardMetric;
    range: LeaderboardRange;
    weekStart?: string | null;
    includeWeekStarts?: boolean;
    page: number;
  }
): Promise<Leaderboard> {
  const params = new URLSearchParams({
    metric: query.metric,
    range: query.range,
    page: String(query.page),
  });
  if (query.range === "week" && query.weekStart) params.set("weekStart", query.weekStart);
  if (query.includeWeekStarts === false) params.set("includeWeekStarts", "false");
  const path =
    scope.kind === "workspace"
      ? `/api/workspaces/${encodeURIComponent(scope.id)}/leaderboard`
      : "/api/leaderboard/domain";
  const response = await cloudGet<unknown>(`${path}?${params.toString()}`);
  const leaderboard = responseData(response, "leaderboard");
  if (!isLeaderboard(leaderboard)) throw new Error("Malformed leaderboard response from cloud");
  return leaderboard;
}

export const LeaderboardService = {
  flushPendingLeave,
  getAccess,
  getLeaderboard,
  getParticipation,
  joinParticipation,
  leaveParticipation,
};