@orakl/shared 0.1.0

package/dist/badges.d.ts

@@ -0,0 +1,126 @@
+import type { BadgeAward, BadgeId, BadgeMode, BadgeRunParams } from "@orakl/protocol";
+export type { BadgeAward, BadgeId, BadgeMode, BadgeRunParams, } from "@orakl/protocol";
+export interface BadgeMeta {
+    id: BadgeId;
+    label: string;
+    /** Static one-line description (used on the trials tally). */
+    description: string;
+    icon: string;
+    /** Which modes can award this badge (ADR 0018 mode tags). */
+    modes: readonly BadgeMode[];
+}
+/** Display order, most prestigious first. */
+export declare const BADGE_ORDER: BadgeId[];
+export declare const BADGES: Record<BadgeId, BadgeMeta>;
+/**
+ * Mode context for a run. Solo runs carry the solo mode (normal/endless);
+ * multiplayer runs carry the final ranking data that drives Victor/Podium and
+ * the full-game Flawless rule.
+ */
+export type BadgeContext = {
+    kind: "solo";
+    mode: "normal" | "endless";
+} | {
+    kind: "multiplayer";
+    /** Distinct final rank (1 = winner; see `distinctRanks`). */
+    rank: number;
+    /** Heroes who took part (the field Victor topped). */
+    heroCount: number;
+    /** Questions in the whole game — Flawless requires acing all of them. */
+    totalQuestions: number;
+    /** This player's final score (a 0-score field can't crown a Victor). */
+    score: number;
+    /** Questions actually served in this game. */
+    questionsServed: number;
+};
+export interface BadgeInput {
+    context: BadgeContext;
+    difficulty: "all" | "easy" | "medium" | "hard";
+    /**
+     * Questions in the player's log. In multiplayer this includes recorded
+     * misses: every unanswered round during the player's hero tenure (timeout,
+     * disconnect, quit) counts as a miss.
+     */
+    totalAnswered: number;
+    correctCount: number;
+    /** Session-wide tab-away events. 0 means the player never left the trial. */
+    tabAwayCount: number;
+    /** Peak consecutive-correct streak. */
+    maxStreak: number;
+    /** Per-question timer (ms) — the clock each answer is measured against. */
+    timerDurationMs: number;
+    /** Mean time-to-answer (ms) across the run. */
+    timeToAnswerAvgMs: number;
+    /**
+     * Best "faster than most" reading this run: the highest % of prior correct
+     * solvers any single answer beat on time. Null when no question had enough
+     * samples to judge. Drives the Faster-than-most badge (US #11).
+     */
+    fasterThanMaxPercent: number | null;
+    /**
+     * Total times the player switched a selection before committing, across the
+     * run. 0 means every answer was committed first-try (sure-handed). Undefined
+     * when the client didn't report changes (legacy) — the badge then can't award.
+     */
+    answerChanges?: number;
+    /**
+     * The player's consecutive-days-played streak as of this run (signed-in only).
+     * Drives the Devotee badge; undefined for guests / when not computed.
+     */
+    consecutiveDays?: number;
+    results: Array<{
+        timeToAnswerMs: number;
+        categoryId: string;
+        isCorrect: boolean;
+        /** Difficulty band of this question (for the per-difficulty Polymath badge). */
+        difficulty?: "easy" | "medium" | "hard";
+    }>;
+}
+/** Served-questions floor for the rank badges (victor, podium) and lifetime best-rank — below this a rank isn't a claim. */
+export declare const RANK_BADGE_MIN_QUESTIONS = 6;
+/**
+ * Raw share (0–1) of answers committed before the clock's halfway mark — quick
+ * answers read as decisive (implicit confidence from timing). Null when not
+ * measurable. This is the value the badge gates on (the rounded percent below
+ * is display-only, and rounding up could award the badge under the threshold).
+ */
+export declare function decisiveShare(input: {
+    timerDurationMs: number;
+    results: Array<{
+        timeToAnswerMs: number;
+    }>;
+}): number | null;
+/** Rounded percentage form of {@link decisiveShare}, for display. */
+export declare function decisivenessPercent(input: {
+    timerDurationMs: number;
+    results: Array<{
+        timeToAnswerMs: number;
+    }>;
+}): number | null;
+/** Badges earned by a completed run (solo or multiplayer), in display order. */
+export declare function computeBadges(input: BadgeInput): BadgeAward[];
+/** Four ascending rarity tiers. Index in RARITY_ORDER is the tier level. */
+export type Rarity = "common" | "rare" | "legendary" | "exotic";
+export declare const RARITY_ORDER: Rarity[];
+export declare const RARITY_LABELS: Record<Rarity, string>;
+/**
+ * Canonical tier colours, shared by every surface that renders the rarity
+ * scale (badge chips, legends) so the key always matches the badges it
+ * explains.
+ */
+export declare const RARITY_CHIP_CLASSES: Record<Rarity, string>;
+/** The rarity tier a badge reaches when earned under the given run conditions. */
+export declare function computeBadgeRarity(id: BadgeId, run: BadgeRunParams): Rarity;
+/** Parse a stored badge-id JSON array; malformed/missing/unknown ids read as none. */
+export declare function parseBadgeIds(json: string | null | undefined): BadgeId[];
+export interface BadgeTallyEntry {
+    count: number;
+    /** Highest rarity tier the player has reached for this badge. */
+    bestRarity: Rarity;
+}
+/** Per-badge counts + best rarity across a player's runs (any mode). */
+export type BadgeTally = Partial<Record<BadgeId, BadgeTallyEntry>>;
+/** Fold one earned badge into a tally (count + best rarity). Mutates `tally`. */
+export declare function addToBadgeTally(tally: BadgeTally, id: BadgeId, rarity: Rarity): void;
+/** Merge tallies from different sources (e.g. solo + multiplayer) into one. */
+export declare function mergeBadgeTallies(...tallies: BadgeTally[]): BadgeTally;