@pithy-sh/leaderboard 0.1.0

package/src/error/errors.ts

@@ -0,0 +1,125 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
+
+/**
+ * `@pithy-sh/leaderboard` throw sugar. The `leaderboard/*` codes live in core's closed `KitErrorPayload`
+ * union (CLAUDE.md §Errors: capabilities add their codes to the one union); these subclasses are the
+ * package-local vehicles that set one of those members — the same pattern as `@pithy-sh/media` and
+ * `@pithy-sh/turnstile`. Runtime code in this package throws one of these, never a plain `new Error`.
+ */
+
+/** Variable parts each subclass accepts; `code`/`status` are fixed by the subclass. */
+interface LeaderboardErrorArgs {
+  /** Override the public, safe-to-expose message. */
+  message?: string;
+  /** A remediation hint (CLI action line). */
+  action?: string;
+  /** Internal context for logs + audit. Never serialized to clients. */
+  detail?: string;
+  /**
+   * Values a translating client interpolates into its own wording for this code. Client-facing, so —
+   * unlike `action` and `detail` — these cross the boundary with `message`.
+   */
+  params?: MessageParams;
+}
+
+export class LeaderboardBoardNotFoundError extends PithyError {
+  constructor(args: LeaderboardErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "leaderboard/board_not_found",
+        status: 404,
+        message: args.message ?? "That board does not exist.",
+        action: args.action ?? "Check the board key against the `boards` list in pithy.config.ts.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class LeaderboardEntryNotFoundError extends PithyError {
+  constructor(args: LeaderboardErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "leaderboard/entry_not_found",
+        status: 404,
+        message: args.message ?? "You have no score on that board yet.",
+        action: args.action ?? "Submit a score first.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class LeaderboardScoreRejectedError extends PithyError {
+  constructor(args: LeaderboardErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "leaderboard/score_rejected",
+        status: 400,
+        message: args.message ?? "That score is outside the board's allowed range.",
+        action: args.action ?? "Submit a score within the board's min and max.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class LeaderboardSubmitForbiddenError extends PithyError {
+  constructor(args: LeaderboardErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "leaderboard/submit_forbidden",
+        status: 403,
+        message: args.message ?? "This session may not submit scores.",
+        action:
+          args.action ??
+          "Submit from your trusted server with the board's submit scope, or set `serverAuthoritative: false` to let clients post directly.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class LeaderboardBoardImmutableError extends PithyError {
+  constructor(args: LeaderboardErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "leaderboard/board_immutable",
+        status: 409,
+        message: args.message ?? "That board's definition cannot change.",
+        action: args.action ?? "Give the changed board a new key. The old board keeps its recorded scores.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class LeaderboardInvalidScheduleError extends PithyError {
+  constructor(args: LeaderboardErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "leaderboard/invalid_schedule",
+        status: 500,
+        message: args.message ?? "That board's window schedule is invalid.",
+        action: args.action ?? "Fix the board's `window` CRON expression in pithy.config.ts.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}

package/src/http/guard.ts

@@ -0,0 +1,61 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { ForbiddenError, UnauthorizedError } from "@pithy-sh/core/src/error/pithyError";
+import type { MiddlewareHandler } from "hono";
+import { LeaderboardSubmitForbiddenError } from "../error/errors";
+
+/**
+ * Route guards.
+ *
+ * These depend on the core `AuthContext` seam and nothing else — `@pithy-sh/auth` populates `c.var.auth`,
+ * and leaderboard never reaches into its internals (CLAUDE.md §HTTP). Without auth installed `c.var.auth`
+ * is null and every route below is denied, which is the correct failure: an entry with no stable player
+ * id cannot be keyed, upserted, or rate-limited, so an unauthenticated board is not a degraded board but
+ * an append log of unattributable scores.
+ */
+export function requireAuth(): MiddlewareHandler<PithyHonoEnv> {
+  return async (c, next) => {
+    if (!c.var.auth) {
+      throw new UnauthorizedError({
+        message: "Authentication required.",
+        action: "Sign in and retry with a valid session or bearer token.",
+      });
+    }
+    await next();
+  };
+}
+
+/**
+ * Require the board's submit scope while `serverAuthoritative` is on.
+ *
+ * Every vendor that offers server-authoritative writes ships it **off**; Pithy ships it **on**. The scope
+ * is the seam: mint it for your own trusted server's token and never for a player's, and a device cannot
+ * post a score it invented. Turning `serverAuthoritative` off removes this gate entirely — which is the
+ * vendor default, and is why it is not ours.
+ */
+export function requireSubmitScope(serverAuthoritative: boolean, scope: string): MiddlewareHandler<PithyHonoEnv> {
+  return async (c, next) => {
+    if (serverAuthoritative && !c.var.auth?.scopes.includes(scope)) {
+      throw new LeaderboardSubmitForbiddenError({
+        detail: `Submit requires the ${scope} scope; this session carries [${c.var.auth?.scopes.join(", ") ?? ""}].`,
+      });
+    }
+    await next();
+  };
+}
+
+/** Require the admin scope for moderation — hiding or removing another player's entry. */
+export function requireAdminScope(scope: string): MiddlewareHandler<PithyHonoEnv> {
+  return async (c, next) => {
+    if (!c.var.auth?.scopes.includes(scope)) {
+      throw new ForbiddenError({
+        message: "This session may not moderate leaderboard entries.",
+        action: `Retry with a token carrying the ${scope} scope.`,
+        detail: `Moderation requires the ${scope} scope; this session carries [${c.var.auth?.scopes.join(", ") ?? ""}].`,
+      });
+    }
+    await next();
+  };
+}

package/src/http/handlers.ts

@@ -0,0 +1,221 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { assertBoardDefinition } from "../board/registry";
+import type { LeaderboardBoard, LeaderboardConfig } from "../config/config";
+import type { LeaderboardDatabase } from "../data/tables";
+import { entryStore } from "../entry/store";
+import {
+  LeaderboardBoardNotFoundError,
+  LeaderboardEntryNotFoundError,
+  LeaderboardScoreRejectedError,
+} from "../error/errors";
+import { entriesAround, type RankedEntry, rankOf, topEntries } from "../rank/query";
+import { windowKeyAt } from "../window/schedule";
+import type { HideBody, SegmentBody, SubmitScoreBody, VisibilityBody } from "./schemas";
+
+/**
+ * The leaderboard handlers — pure functions over injected deps. Nothing here touches a Hono `Context`;
+ * the routes unwrap the request and hand the pieces down, which is what makes every case below testable
+ * without a request at all. Nothing here parses, either: the route line declares each shape with
+ * `zValidator`, so a handler receives values that are already the type it names.
+ */
+export interface HandlerDeps {
+  config: LeaderboardConfig;
+  db: LeaderboardDatabase;
+  /** The authenticated player, from the core AuthContext seam. Never from the request body. */
+  userId: string;
+  now: () => Date;
+}
+
+/** The configured board, or a 404. Board keys come from config, so an unknown key is not a lookup miss. */
+function board(deps: HandlerDeps, key: string): LeaderboardBoard {
+  const found = deps.config.boards.find((b) => b.key === key);
+  if (!found) throw new LeaderboardBoardNotFoundError({ detail: `No board configured with key "${key}".` });
+  return found;
+}
+
+/**
+ * Which window a read applies to: the one the client named, or the one open now.
+ *
+ * A named window is not validated against the schedule. A key that never was a window simply selects no
+ * entries, and letting a client read a closed window by key is the feature — that history is in the
+ * adopter's own D1, retained on their terms.
+ */
+function readWindow(deps: HandlerDeps, b: LeaderboardBoard, requested: string | undefined): string {
+  return requested ?? windowKeyAt(b.window, deps.now());
+}
+
+export interface BoardPage {
+  board: string;
+  window: string;
+  entries: RankedEntry[];
+}
+
+export async function submitScore(
+  deps: HandlerDeps,
+  boardKey: string,
+  body: SubmitScoreBody,
+): Promise<{ window: string }> {
+  const b = board(deps, boardKey);
+  const { score } = body;
+  // Server-side bounds are the whole demonstrated anti-cheat baseline. Checked before anything is
+  // written, so a rejected score leaves no trace on the board.
+  if (b.min !== undefined && score < b.min) {
+    throw new LeaderboardScoreRejectedError({ detail: `Score ${score} is below board "${b.key}" min ${b.min}.` });
+  }
+  if (b.max !== undefined && score > b.max) {
+    throw new LeaderboardScoreRejectedError({ detail: `Score ${score} is above board "${b.key}" max ${b.max}.` });
+  }
+  const now = deps.now();
+  // Guard the board's immutable fields before the first write of each board, not after.
+  await assertBoardDefinition(deps.db, b, now);
+  const window = windowKeyAt(b.window, now);
+  await entryStore(deps.db).submit(b, window, deps.userId, score, now, deps.config.visibleByDefault);
+  return { window };
+}
+
+export async function readTop(
+  deps: HandlerDeps,
+  boardKey: string,
+  query: { window?: string; limit: number; offset: number },
+): Promise<BoardPage> {
+  const b = board(deps, boardKey);
+  const window = readWindow(deps, b, query.window);
+  return { board: b.key, window, entries: await topEntries(deps.db, b, window, query.limit, query.offset) };
+}
+
+export async function readSegment(deps: HandlerDeps, boardKey: string, body: SegmentBody): Promise<BoardPage> {
+  const b = board(deps, boardKey);
+  const { userIds, limit, offset, window: requested } = body;
+  const window = readWindow(deps, b, requested);
+  return {
+    board: b.key,
+    window,
+    entries: await topEntries(deps.db, b, window, limit, offset, { segment: userIds }),
+  };
+}
+
+export interface OwnRank {
+  board: string;
+  window: string;
+  userId: string;
+  score: number;
+  rank: number | null;
+  tier: string | null;
+  visible: boolean;
+  /** True when `rank` came from the stored column and may lag the score beside it. */
+  rankStale: boolean;
+}
+
+export async function readOwnRank(deps: HandlerDeps, boardKey: string, query: { window?: string }): Promise<OwnRank> {
+  const b = board(deps, boardKey);
+  const window = readWindow(deps, b, query.window);
+  const materialized = typeof deps.config.rank === "object";
+  const own = await rankOf(deps.db, b, window, deps.userId, materialized);
+  if (!own) {
+    throw new LeaderboardEntryNotFoundError({
+      detail: `User ${deps.userId} has no entry on board "${b.key}" in window ${window}.`,
+    });
+  }
+  return {
+    board: b.key,
+    window,
+    userId: deps.userId,
+    score: own.entry.score,
+    rank: own.rank,
+    tier: own.tier,
+    visible: own.entry.visible,
+    rankStale: materialized,
+  };
+}
+
+export async function readAround(
+  deps: HandlerDeps,
+  boardKey: string,
+  query: { window?: string; radius: number },
+): Promise<BoardPage> {
+  const b = board(deps, boardKey);
+  const window = readWindow(deps, b, query.window);
+  return { board: b.key, window, entries: await entriesAround(deps.db, b, window, deps.userId, query.radius) };
+}
+
+export async function setOwnVisibility(
+  deps: HandlerDeps,
+  boardKey: string,
+  query: { window?: string },
+  body: VisibilityBody,
+): Promise<{ visible: boolean }> {
+  const b = board(deps, boardKey);
+  const { visible } = body;
+  const window = readWindow(deps, b, query.window);
+  const updated = await entryStore(deps.db).setVisibility(b.key, window, deps.userId, visible);
+  if (!updated) {
+    throw new LeaderboardEntryNotFoundError({
+      detail: `User ${deps.userId} has no entry on board "${b.key}" in window ${window} to make ${visible ? "visible" : "hidden"}.`,
+    });
+  }
+  return { visible };
+}
+
+export async function hideEntry(
+  deps: HandlerDeps,
+  boardKey: string,
+  targetUserId: string,
+  query: { window?: string },
+  body: HideBody,
+): Promise<{ hidden: boolean }> {
+  const b = board(deps, boardKey);
+  const { hidden } = body;
+  const window = readWindow(deps, b, query.window);
+  const updated = await entryStore(deps.db).hide(b.key, window, targetUserId, hidden);
+  if (!updated) {
+    throw new LeaderboardEntryNotFoundError({
+      message: "That entry does not exist.",
+      detail: `No entry for user ${targetUserId} on board "${b.key}" in window ${window}.`,
+    });
+  }
+  return { hidden };
+}
+
+export async function removeEntry(
+  deps: HandlerDeps,
+  boardKey: string,
+  targetUserId: string,
+  query: { window?: string },
+): Promise<{ removed: boolean }> {
+  const b = board(deps, boardKey);
+  const window = readWindow(deps, b, query.window);
+  const removed = await entryStore(deps.db).remove(b.key, window, targetUserId);
+  if (!removed) {
+    throw new LeaderboardEntryNotFoundError({
+      message: "That entry does not exist.",
+      detail: `No entry for user ${targetUserId} on board "${b.key}" in window ${window}.`,
+    });
+  }
+  return { removed };
+}
+
+/** The board set, as configured — what a client needs to render a board picker. */
+export function listBoards(deps: HandlerDeps): {
+  boards: Array<{
+    key: string;
+    store: string;
+    direction: string;
+    aggregation: string;
+    window: string | null;
+    tiers: Array<{ key: string; from: number }>;
+  }>;
+} {
+  return {
+    boards: deps.config.boards.map((b) => ({
+      key: b.key,
+      // Always `d1` today; surfaced so a client can tell an exact board from a future approximate one.
+      store: b.store,
+      direction: b.direction,
+      aggregation: b.aggregation,
+      window: b.window ?? null,
+      tiers: b.tiers?.map((t) => ({ key: t.key, from: t.from })) ?? [],
+    })),
+  };
+}

package/src/http/routes.ts

@@ -0,0 +1,202 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { zValidator } from "@hono/zod-validator";
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { validationHook } from "@pithy-sh/core/src/http/validation";
+import type { Context, Hono } from "hono";
+import type { LeaderboardConfig } from "../config/config";
+import { BOOKMARK_HEADER, leaderboardSession, readBookmark } from "../session/bookmark";
+import { requireAdminScope, requireAuth, requireSubmitScope } from "./guard";
+import {
+  type HandlerDeps,
+  hideEntry,
+  listBoards,
+  readAround,
+  readOwnRank,
+  readSegment,
+  readTop,
+  removeEntry,
+  setOwnVisibility,
+  submitScore,
+} from "./handlers";
+import {
+  AroundQuery,
+  BoardParam,
+  EntryParam,
+  HideBody,
+  SegmentBody,
+  SubmitScoreBody,
+  TopQuery,
+  VisibilityBody,
+  WindowQuery,
+} from "./schemas";
+
+/**
+ * The leaderboard routes, each declaring both how a caller is verified and what it may send:
+ *
+ *   GET    /leaderboard                          → list boards    (bearer | session) — takes nothing
+ *   POST   /leaderboard/:board                   → submit a score (bearer | session + submit scope)
+ *                                                  param BoardParam, json SubmitScoreBody
+ *   GET    /leaderboard/:board/top               → top-N page     (bearer | session)
+ *                                                  param BoardParam, query TopQuery
+ *   POST   /leaderboard/:board/segment           → friends/cohort (bearer | session)
+ *                                                  param BoardParam, json SegmentBody
+ *   GET    /leaderboard/:board/me                → my rank        (bearer | session)
+ *                                                  param BoardParam, query WindowQuery
+ *   GET    /leaderboard/:board/around            → around me      (bearer | session)
+ *                                                  param BoardParam, query AroundQuery
+ *   PUT    /leaderboard/:board/me/visibility     → my consent     (bearer | session)
+ *                                                  param BoardParam, query WindowQuery, json VisibilityBody
+ *   PUT    /leaderboard/:board/entries/:userId/hidden → hide entry (bearer | session + admin scope)
+ *                                                  param EntryParam, query WindowQuery, json HideBody
+ *   DELETE /leaderboard/:board/entries/:userId   → remove entry   (bearer | session + admin scope)
+ *                                                  param EntryParam, query WindowQuery
+ *
+ * Every route is gated by {@link requireAuth} — there is no public leaderboard surface, because an entry
+ * with no authenticated player has nothing to key on. Submit additionally requires the board's submit
+ * scope while `serverAuthoritative` is on (the default), and the two moderation routes require the admin
+ * scope. Turnstile, if the adopter runs it, stacks on top as middleware — it is a humanity check, not an
+ * identity, so it never replaces any of the above.
+ *
+ * Validators sit **after** the guards, never before: who you are is decided before what you sent, so an
+ * unauthorised request with a malformed body is still a 401. They sit **before** the handler, which is
+ * what moves a malformed request ahead of the board lookup — an unknown board sent a bad body now answers
+ * 400 rather than 404. The request was never well-formed enough to have a board.
+ */
+export interface LeaderboardRoutesOptions {
+  config: LeaderboardConfig;
+  basePath?: string;
+  /** Test seam: resolve handler deps from the request context. Defaults to the env-based resolver. */
+  resolveDeps?: (c: Context<PithyHonoEnv>, write: boolean) => HandlerDeps & { bookmark(): string | null };
+}
+
+function defaultResolveDeps(config: LeaderboardConfig) {
+  return (c: Context<PithyHonoEnv>, write: boolean): HandlerDeps & { bookmark(): string | null } => {
+    const d1 = (c.env as Record<string, unknown>).DB as D1Database | undefined;
+    if (!d1) {
+      throw new InternalError({
+        message: "The leaderboard is not configured.",
+        action: "Bind a D1 database named DB in wrangler.jsonc.",
+        detail: "The leaderboard capability requires a `DB` D1 binding; none was present on env.",
+      });
+    }
+    // A write anchors at the primary and hands back a bookmark; a read follows the client's bookmark
+    // when it sent one. That round trip is what makes a player see their own submission.
+    const session = leaderboardSession(
+      d1,
+      readBookmark(c.req.raw.headers),
+      write ? "first-primary" : "first-unconstrained",
+    );
+    const auth = c.var.auth;
+    if (!auth) {
+      throw new InternalError({ detail: "requireAuth() must run before a leaderboard handler resolves deps." });
+    }
+    return { config, db: session.db, userId: auth.userId, now: () => new Date(), bookmark: session.bookmark };
+  };
+}
+
+export function registerLeaderboardRoutes(options: LeaderboardRoutesOptions): (app: Hono<PithyHonoEnv>) => void {
+  const base = options.basePath ?? "/leaderboard";
+  const resolve = options.resolveDeps ?? defaultResolveDeps(options.config);
+  const { serverAuthoritative, submitScope, adminScope } = options.config;
+
+  /** Run a handler and return its JSON, attaching the session's bookmark for the client to echo back. */
+  const respond = async <T>(
+    c: Context<PithyHonoEnv>,
+    write: boolean,
+    run: (deps: HandlerDeps) => Promise<T> | T,
+    status: 200 | 201 = 200,
+  ) => {
+    const deps = resolve(c, write);
+    const body = await run(deps);
+    const bookmark = deps.bookmark();
+    if (bookmark) c.header(BOOKMARK_HEADER, bookmark);
+    return c.json(body as object, status);
+  };
+
+  return (app) => {
+    app.get(base, requireAuth(), (c) => respond(c, false, (deps) => listBoards(deps)));
+
+    // Static segments are registered before `:board`-rooted reads so they cannot be shadowed.
+    app.post(
+      `${base}/:board/segment`,
+      requireAuth(),
+      zValidator("param", BoardParam, validationHook),
+      zValidator("json", SegmentBody, validationHook),
+      (c) => respond(c, false, (deps) => readSegment(deps, c.req.valid("param").board, c.req.valid("json"))),
+    );
+
+    app.get(
+      `${base}/:board/top`,
+      requireAuth(),
+      zValidator("param", BoardParam, validationHook),
+      zValidator("query", TopQuery, validationHook),
+      (c) => respond(c, false, (deps) => readTop(deps, c.req.valid("param").board, c.req.valid("query"))),
+    );
+
+    app.get(
+      `${base}/:board/me`,
+      requireAuth(),
+      zValidator("param", BoardParam, validationHook),
+      zValidator("query", WindowQuery, validationHook),
+      (c) => respond(c, false, (deps) => readOwnRank(deps, c.req.valid("param").board, c.req.valid("query"))),
+    );
+
+    app.get(
+      `${base}/:board/around`,
+      requireAuth(),
+      zValidator("param", BoardParam, validationHook),
+      zValidator("query", AroundQuery, validationHook),
+      (c) => respond(c, false, (deps) => readAround(deps, c.req.valid("param").board, c.req.valid("query"))),
+    );
+
+    app.put(
+      `${base}/:board/me/visibility`,
+      requireAuth(),
+      zValidator("param", BoardParam, validationHook),
+      zValidator("query", WindowQuery, validationHook),
+      zValidator("json", VisibilityBody, validationHook),
+      (c) =>
+        respond(c, true, (deps) =>
+          setOwnVisibility(deps, c.req.valid("param").board, c.req.valid("query"), c.req.valid("json")),
+        ),
+    );
+
+    app.put(
+      `${base}/:board/entries/:userId/hidden`,
+      requireAuth(),
+      requireAdminScope(adminScope),
+      zValidator("param", EntryParam, validationHook),
+      zValidator("query", WindowQuery, validationHook),
+      zValidator("json", HideBody, validationHook),
+      (c) => {
+        const { board, userId } = c.req.valid("param");
+        return respond(c, true, (deps) => hideEntry(deps, board, userId, c.req.valid("query"), c.req.valid("json")));
+      },
+    );
+
+    app.delete(
+      `${base}/:board/entries/:userId`,
+      requireAuth(),
+      requireAdminScope(adminScope),
+      zValidator("param", EntryParam, validationHook),
+      zValidator("query", WindowQuery, validationHook),
+      (c) => {
+        const { board, userId } = c.req.valid("param");
+        return respond(c, true, (deps) => removeEntry(deps, board, userId, c.req.valid("query")));
+      },
+    );
+
+    app.post(
+      `${base}/:board`,
+      requireAuth(),
+      requireSubmitScope(serverAuthoritative, submitScope),
+      zValidator("param", BoardParam, validationHook),
+      zValidator("json", SubmitScoreBody, validationHook),
+      (c) => respond(c, true, (deps) => submitScore(deps, c.req.valid("param").board, c.req.valid("json")), 201),
+    );
+  };
+}