Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

7.8 KB
Raw Blame
/**
 * Streak Tracker for OmniRoute Gamification
 *
 * Tracks consecutive daily active usage per API key.
 * Stores streak data in the existing `key_value` table with
 * namespace `gamification:streaks` to avoid schema changes.
 *
 * @module lib/gamification/streaks
 */

import { getDbInstance, isBuildPhase, isCloud } from "../db/core";

// ─── Types ───────────────────────────────────────────────────────────────────

export interface StreakData {
  /** Current consecutive active days */
  currentStreak: number;
  /** Longest ever consecutive streak */
  longestStreak: number;
  /** Last day the user was active (YYYY-MM-DD) */
  lastActiveDate: string;
  /** Date the current streak started (YYYY-MM-DD) */
  streakStartDate: string;
}

interface StatementLike<TRow = unknown> {
  get: (...params: unknown[]) => TRow | undefined;
  run: (...params: unknown[]) => { changes?: number };
  all: (...params: unknown[]) => TRow[];
}

interface DbLike {
  prepare: <TRow = unknown>(sql: string) => StatementLike<TRow>;
}

interface KeyValueRow {
  value: string;
}

// ─── Constants ───────────────────────────────────────────────────────────────

const NAMESPACE = "gamification:streaks";

/** One day in milliseconds */
const MS_PER_DAY = 86_400_000;

// ─── Helpers ─────────────────────────────────────────────────────────────────

/**
 * Get today's date as YYYY-MM-DD in UTC.
 */
function todayUtc(): string {
  return new Date().toISOString().split("T")[0];
}

/**
 * Get yesterday's date as YYYY-MM-DD in UTC.
 */
function yesterdayUtc(): string {
  return new Date(Date.now() - MS_PER_DAY).toISOString().split("T")[0];
}

function emptyStreak(): StreakData {
  return {
    currentStreak: 0,
    longestStreak: 0,
    lastActiveDate: "",
    streakStartDate: "",
  };
}

/** Stored counters are day counts: finite, integral and never negative. */
function toDayCount(value: unknown): number {
  return typeof value === "number" && Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
}

function parseStreakJson(raw: string): StreakData {
  try {
    const parsed = JSON.parse(raw) as Partial<StreakData>;
    return {
      currentStreak: toDayCount(parsed.currentStreak),
      longestStreak: toDayCount(parsed.longestStreak),
      lastActiveDate: typeof parsed.lastActiveDate === "string" ? parsed.lastActiveDate : "",
      streakStartDate: typeof parsed.streakStartDate === "string" ? parsed.streakStartDate : "",
    };
  } catch {
    return emptyStreak();
  }
}

// ─── Public API ──────────────────────────────────────────────────────────────

/**
 * Get the current streak data for an API key.
 *
 * @param apiKeyId - The API key identifier
 * @returns StreakData with current/longest streak and date info
 *
 * @example
 * const streak = await getStreak("key_abc123");
 * console.log(streak.currentStreak); // 7
 */
export async function getStreak(apiKeyId: string): Promise<StreakData> {
  return readStreak(apiKeyId);
}

/** Synchronous read, so advanceStreak's read-modify-write has no await between them. */
function readStreak(apiKeyId: string): StreakData {
  if (isBuildPhase || isCloud) return emptyStreak();

  const db = getDbInstance() as unknown as DbLike;
  const row = db
    .prepare("SELECT value FROM key_value WHERE namespace = ? AND key = ?")
    .get(NAMESPACE, apiKeyId) as KeyValueRow | undefined;

  if (!row?.value) return emptyStreak();
  return parseStreakJson(row.value);
}

/**
 * Operator-wide streak for the dashboard profile page, which has no single API key
 * (the aggregate mode of `/api/gamification/level`, #3484): the best `currentStreak`
 * and the best `longestStreak` over every key in the namespace. Both are maxima, not
 * sums, and may come from different keys. Malformed rows count as zero.
 *
 * @returns The highest current/longest streak across all API keys
 *
 * @example
 * const agg = await getAggregateStreak();
 * console.log(agg.currentStreak); // 7
 */
export async function getAggregateStreak(): Promise<
  Pick<StreakData, "currentStreak" | "longestStreak">
> {
  const aggregate = { currentStreak: 0, longestStreak: 0 };
  if (isBuildPhase || isCloud) return aggregate;

  const db = getDbInstance() as unknown as DbLike;
  const rows = db
    .prepare("SELECT value FROM key_value WHERE namespace = ?")
    .all(NAMESPACE) as KeyValueRow[];

  for (const row of rows) {
    const streak = parseStreakJson(row.value);
    aggregate.currentStreak = Math.max(aggregate.currentStreak, streak.currentStreak);
    aggregate.longestStreak = Math.max(aggregate.longestStreak, streak.longestStreak);
  }

  return aggregate;
}

/**
 * Update streak for today. Returns the new current streak count.
 *
 * Behavior:
 * - If already active today, returns current streak (no-op).
 * - If active yesterday, increments streak.
 * - Otherwise, resets streak to 1 (new streak).
 *
 * Also updates longestStreak if the new streak is a personal record.
 *
 * @param apiKeyId - The API key identifier
 * @returns New current streak count
 *
 * @example
 * const count = await updateStreak("key_abc123");
 * console.log(count); // 8
 */
export async function updateStreak(apiKeyId: string): Promise<number> {
  const { currentStreak } = await advanceStreak(apiKeyId);
  return currentStreak;
}

/**
 * Result of {@link advanceStreak}.
 */
export interface StreakAdvance {
  /** Current consecutive active days after this call */
  currentStreak: number;
  /**
   * `true` only on the call that extended the streak onto a new consecutive day
   * (yesterday was active, today was not yet counted). `false` when today was
   * already counted, when a new streak starts at 1, or when streaks are disabled.
   */
  extended: boolean;
}

/**
 * Same as {@link updateStreak}, but also reports whether this call extended the
 * streak onto a new consecutive day. The award pipeline uses `extended` to pay
 * the `streak_bonus` reward once per UTC day; repeated requests on the same day
 * see `extended: false` because the record already carries today's date.
 *
 * @param apiKeyId - The API key identifier
 * @returns The new streak count and whether it just extended
 *
 * @example
 * const { currentStreak, extended } = await advanceStreak("key_abc123");
 * if (extended) console.log(`day ${currentStreak} of the streak`);
 */
export async function advanceStreak(apiKeyId: string): Promise<StreakAdvance> {
  if (isBuildPhase || isCloud) return { currentStreak: 0, extended: false };

  const db = getDbInstance() as unknown as DbLike;
  const today = todayUtc();
  // No await between this read and the write below: concurrent calls must not both extend.
  const streak = readStreak(apiKeyId);

  // Already counted today
  if (streak.lastActiveDate === today) {
    return { currentStreak: streak.currentStreak, extended: false };
  }

  const yesterday = yesterdayUtc();
  const extended = streak.lastActiveDate === yesterday;
  // Consecutive day — extend streak; otherwise streak broken or first activity — start fresh
  const newStreak = extended ? streak.currentStreak + 1 : 1;

  const newData: StreakData = {
    currentStreak: newStreak,
    longestStreak: Math.max(newStreak, streak.longestStreak),
    lastActiveDate: today,
    streakStartDate: newStreak === 1 ? today : streak.streakStartDate,
  };

  db.prepare("INSERT OR REPLACE INTO key_value (namespace, key, value) VALUES (?, ?, ?)").run(
    NAMESPACE,
    apiKeyId,
    JSON.stringify(newData)
  );

  return { currentStreak: newStreak, extended };
}