@profullstack/leaderboard 0.1.0 → 0.3.0

package/README.md

@@ -4,6 +4,8 @@ A public leaderboard that drops into any site. Score events in, ranked boards ou
 
 Zero dependencies. The core is a Fetch API handler, so it runs in Node, Bun, Deno and at the edge. Adapters for Hono and Next.js. Stores: in-memory, or any SQL client with `execute({ sql, args })` (libsql/Turso, sqlite, Postgres).
 
+It ranks either side of a transaction. Sellers earning, buyers spending, and plain usage are separate boards that never blend, because a publisher earning $900 and a crawler spending $900 are not the same fact.
+
 Built for marketplaces where people sell through properties and niches and earn a growing cut, but every board, badge and metric is yours to define.
 
 ## Install
@@ -84,6 +86,30 @@ Sticky mode is the retention feature. Add `data-sticky="bottom-right"` (or `bott
 
 The widget fires `leaderboard:render` on its container with the JSON as `detail`, for anything you want to do with the numbers.
 
+## Sides of the transaction
+
+Every board declares a `side`:
+
+| `side` | Money | Default label | Example |
+| --- | --- | --- | --- |
+| `sell` | to the actor | Earning | Publishers by revenue, affiliates by commission |
+| `buy` | from the actor | Spending | Crawlers by what they paid for passes |
+| `use` | none | Usage | Pages crawled, API calls, bytes served |
+
+```js
+boards: {
+  earners:  { label: 'Top earners',        metric: 'cents', format: 'usd', side: 'sell', actor: 'Publisher' },
+  spenders: { label: 'Biggest spenders',   metric: 'spent', format: 'usd', side: 'buy',  actor: 'Crawler' },
+  crawled:  { label: 'Most pages crawled', metric: 'pages', format: 'integer', side: 'use', actor: 'Crawler' },
+}
+```
+
+The widget puts a tab per side across the top and the boards of that side beneath, so only one side is ever on screen. `actor` names the column, so the same table reads "Publisher" on one side and "Crawler" on the other. The commission rate is shown only on `sell` boards, since a rate against a buyer would state something false.
+
+The same identity can hold a rank on both sides at once. Their totals are never pooled.
+
+Rename the tabs with `sides: { buy: 'Bots paying us' }`.
+
 ## Metrics
 
 Three kinds, one vocabulary:
@@ -92,7 +118,7 @@ Three kinds, one vocabulary:
 - **Gauges** go in through `set()` and are the current value (properties owned, niches promoted, followers). Boards on a gauge show the same number in every period.
 - **Derived**: `streak` (consecutive UTC days with any `record()`, still current through yesterday) and `bestStreak`.
 
-A board is `{ label, metric, format, unit, min, order, tiebreak }`. `format` is `number`, `integer`, `usd` (cents in) or `percent`. Players below `min` do not appear. Ties break on `tiebreak`, then on who got there first.
+A board is `{ label, metric, format, unit, min, order, tiebreak, side, actor }`. `format` is `number`, `integer`, `usd` (cents in) or `percent`. Players below `min` do not appear. Ties break on `tiebreak`, then on who got there first.
 
 `record()` and `set()` return the badges newly earned, for a toast.
 
@@ -116,12 +142,33 @@ Every number is an option (`base`, `cap`, `perProperty`, `perNiche`, `maxPropert
 ## Stores
 
 ```js
-import { memoryStore, sqlStore } from '@profullstack/leaderboard';
+import { memoryStore, sqlStore, projectionStore } from '@profullstack/leaderboard';
 
-memoryStore();                                        // one process, tests
+memoryStore();                                           // one process, tests
 sqlStore({ execute, prefix: 'lb_', dialect: 'sqlite' })  // or 'postgres'
+projectionStore({ events, gauges, badges })              // rank tables you already have
 ```
 
+### Ranking data you already record
+
+Most sites that want a leaderboard are already recording the facts it would rank. Copying those into a second set of tables is a dual write, and a dual write means the board and the ledger disagree the first time one of them fails. `projectionStore` reads the source instead:
+
+```js
+const store = projectionStore({
+  events: async ({ since }) => {
+    const rows = await sql`select payer, total_cents, created_at from crawl_sales
+                           where created_at >= ${new Date(since)}`;
+    return rows.map((r) => ({
+      player: r.payer, name: r.payer, metric: 'spent',
+      delta: r.total_cents, at: +new Date(r.created_at),
+    }));
+  },
+  badges: sqlStore({ execute }),   // badges are awarded, not derived, so they need a home
+});
+```
+
+`since` is `0` for an all-time board, so the query has to handle "everything". The store is read-only: `record()` and `set()` throw rather than drop a write the next projection would overwrite.
+
 `sqlStore` needs `execute({ sql, args }) -> { rows }`, which is `@libsql/client` as is. `store.schema` is the DDL for your own migration tool; `store.migrate()` runs it. Three tables: events, gauges, badges.
 
 Anything else implements six methods: `append`, `list({ since })`, `setGauge`, `gauges`, `awardBadge`, `badges`. The core reads all events and aggregates in memory, cached for `cacheMs` (15 s); that is fine into the hundreds of thousands of events. Call `lb.invalidate()` after writing to the store from elsewhere.

package/index.d.ts

@@ -1,5 +1,8 @@
 export type Period = 'all' | 'day' | 'week' | 'month';
 export type Format = 'number' | 'integer' | 'usd' | 'percent';
+/** Which side of the transaction a board ranks. Boards are never mixed across sides. */
+export type Side = 'sell' | 'buy' | 'use';
+export const SIDES: Side[];
 
 export interface Event { player: string; name?: string; metric: string; delta: number; at: number }
 
@@ -23,6 +26,16 @@ export interface SqlStoreOptions {
 export interface SqlStore extends Store { schema: string[]; tables: { events: string; gauges: string; badges: string }; migrate(): Promise<void> }
 export function sqlStore(options: SqlStoreOptions): SqlStore;
 
+export interface ProjectionOptions {
+  /** Build events from rows you already have. `since` is 0 for all time. */
+  events(opts: { since: number }): Promise<Event[]> | Event[];
+  gauges?(): Promise<Record<string, { name?: string; at: number; values: Record<string, number> }>> | Record<string, { name?: string; at: number; values: Record<string, number> }>;
+  /** Where awarded badges persist. Defaults to memory, which does not survive a restart. */
+  badges?: Pick<Store, 'awardBadge' | 'badges'>;
+}
+/** A read-only store over existing tables. `record()` and `set()` throw. */
+export function projectionStore(options: ProjectionOptions): Store;
+
 export interface LadderOptions {
   base?: number; cap?: number; perProperty?: number; perNiche?: number; maxProperties?: number; maxNiches?: number;
   propertiesMetric?: string; nichesMetric?: string;
@@ -41,8 +54,16 @@ export interface Badge { id: string; emoji?: string; label?: string; describe?:
 export interface EarnedBadge { id: string; emoji: string; label: string; describe: string; at: number }
 export function defaultBadges(names?: { sales?: string; properties?: string; niches?: string }): Badge[];
 
-export interface BoardOptions { label?: string; metric?: string; format?: Format; unit?: string; min?: number; order?: 'asc' | 'desc'; tiebreak?: string }
-export interface Board { id: string; label: string; metric: string; format: Format; unit: string }
+export interface BoardOptions {
+  label?: string; metric?: string; format?: Format; unit?: string; min?: number;
+  order?: 'asc' | 'desc'; tiebreak?: string;
+  /** Money to this actor is `sell`, money from them is `buy`, volume with no money is `use`. Default `sell`. */
+  side?: Side;
+  /** What one row is, e.g. "Publisher" or "Crawler". Names the column and appears beside the title. */
+  actor?: string;
+}
+export interface Board { id: string; label: string; metric: string; format: Format; unit: string; side: Side; actor: string | null }
+export interface SideGroup { side: Side; label: string; boards: Board[] }
 
 export interface Profile {
   id: string; name: string;
@@ -60,10 +81,11 @@ export interface Profile {
 export interface Row {
   rank: number | null; id: string; name: string; value: number; display: string;
   streak: number; bestStreak: number; badges: Array<{ id: string; emoji: string; label: string }>;
+  /** Set only on `sell` boards: a commission rate is a property of earning. */
   commission?: number; url: string;
 }
 export interface Standing extends Row { qualified: boolean; min: number }
-export interface Top { board: Board; period: Period; periods: Period[]; generatedAt: string; total: number; rows: Row[]; me?: Standing | null }
+export interface Top { board: Board; sides: SideGroup[]; period: Period; periods: Period[]; generatedAt: string; total: number; rows: Row[]; me?: Standing | null }
 
 export interface LeaderboardOptions {
   store?: Store;
@@ -73,6 +95,8 @@ export interface LeaderboardOptions {
   boards?: Record<string, BoardOptions> | Array<BoardOptions & { id: string }>;
   periods?: Period[];
   defaultPeriod?: Period;
+  /** Display names per side. Defaults: sell "Earning", buy "Spending", use "Usage". */
+  sides?: Partial<Record<Side, string>>;
   ladder?: Ladder | boolean;
   badges?: Badge[];
   cacheMs?: number;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@profullstack/leaderboard",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
-  "description": "A public leaderboard with badges, streaks and a commission ladder that drops into any site: score events in, ranked boards + RSS + a share card + an embeddable widget out. Zero dependencies, Fetch API core, Hono and Next adapters.",
+  "description": "A public leaderboard with badges, streaks and a commission ladder that drops into any site. Ranks either side of a transaction, earners and spenders and usage, kept segregated. Zero dependencies, Fetch API core, Hono and Next adapters.",
   "keywords": [
     "leaderboard",
     "gamification",
@@ -17,25 +17,65 @@
     "hono",
     "nextjs",
     "libsql",
-    "turso"
+    "turso",
+    "marketplace",
+    "x402",
+    "crawler"
   ],
-  "repository": { "type": "git", "url": "git+https://github.com/profullstack/leaderboard.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/profullstack/leaderboard.git"
+  },
   "homepage": "https://github.com/profullstack/leaderboard#readme",
-  "bugs": { "url": "https://github.com/profullstack/leaderboard/issues" },
+  "bugs": {
+    "url": "https://github.com/profullstack/leaderboard/issues"
+  },
   "license": "MIT",
   "author": "Profullstack, LLC",
   "exports": {
-    ".": { "types": "./index.d.ts", "import": "./src/index.js" },
-    "./hono": { "types": "./index.d.ts", "import": "./src/hono.js" },
-    "./next": { "types": "./index.d.ts", "import": "./src/next.js" },
-    "./ladder": { "types": "./index.d.ts", "import": "./src/ladder.js" },
-    "./badges": { "types": "./index.d.ts", "import": "./src/badges.js" },
-    "./store/memory": { "types": "./index.d.ts", "import": "./src/store/memory.js" },
-    "./store/sql": { "types": "./index.d.ts", "import": "./src/store/sql.js" }
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./hono": {
+      "types": "./index.d.ts",
+      "import": "./src/hono.js"
+    },
+    "./next": {
+      "types": "./index.d.ts",
+      "import": "./src/next.js"
+    },
+    "./ladder": {
+      "types": "./index.d.ts",
+      "import": "./src/ladder.js"
+    },
+    "./badges": {
+      "types": "./index.d.ts",
+      "import": "./src/badges.js"
+    },
+    "./store/memory": {
+      "types": "./index.d.ts",
+      "import": "./src/store/memory.js"
+    },
+    "./store/sql": {
+      "types": "./index.d.ts",
+      "import": "./src/store/sql.js"
+    },
+    "./store/projection": {
+      "types": "./index.d.ts",
+      "import": "./src/store/projection.js"
+    }
   },
   "types": "./index.d.ts",
-  "files": ["src", "index.d.ts", "README.md", "LICENSE"],
-  "engines": { "node": ">=20.11" },
+  "files": [
+    "src",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
   "sideEffects": false,
   "scripts": {
     "test": "node --test"

package/src/embed.js

@@ -30,6 +30,7 @@ const WIDGET = String.raw`(function () {
   var period = d.period || '';
   var limit = d.limit || '10';
   var me = d.me || '';
+  var side = d.side || '';
   var sticky = d.sticky || '';
   var theme = d.theme || 'auto';
   var refresh = d.refresh === undefined ? 60 : Number(d.refresh) || 0;
@@ -41,6 +42,13 @@ const WIDGET = String.raw`(function () {
     '.pflb *{box-sizing:border-box}.pflb a{color:inherit;text-decoration:none}' +
     '.pflb-head{display:flex;align-items:center;justify-content:space-between;gap:8px;padding:12px 14px;border-bottom:1px solid var(--line);flex-wrap:wrap}' +
     '.pflb-title{font-weight:700;font-size:15px;margin:0}.pflb-tabs{display:flex;gap:4px;flex-wrap:wrap}' +
+    '.pflb-sides{display:flex;gap:2px;padding:8px 14px 0;flex-wrap:wrap}' +
+    '.pflb-sides button{font:inherit;font-size:12px;font-weight:600;padding:6px 12px;border:0;border-bottom:2px solid transparent;background:transparent;color:var(--muted);cursor:pointer}' +
+    '.pflb-sides button.on{color:var(--fg);border-bottom-color:var(--accent)}' +
+    '.pflb-actor{font-size:11px;color:var(--muted);font-weight:400;margin-left:6px}' +
+    '.pflb-boards{display:flex;gap:4px;flex-wrap:wrap;padding:0 14px 10px}' +
+    '.pflb-boards button{font:inherit;font-size:12px;padding:3px 9px;border-radius:6px;border:1px solid var(--line);background:transparent;color:var(--muted);cursor:pointer}' +
+    '.pflb-boards button.on{color:var(--fg);border-color:var(--accent)}' +
     '.pflb-tabs button{font:inherit;font-size:12px;padding:4px 10px;border-radius:999px;border:1px solid var(--line);background:transparent;color:var(--muted);cursor:pointer}' +
     '.pflb-tabs button.on{background:var(--accent);border-color:var(--accent);color:#fff}' +
     '.pflb table{width:100%;border-collapse:collapse}.pflb td,.pflb th{padding:9px 14px;text-align:left;border-bottom:1px solid var(--line);white-space:nowrap}' +
@@ -94,6 +102,17 @@ const WIDGET = String.raw`(function () {
     if (!periods) periods = data.periods || ['all'];
     period = data.period;
     var title = d.title || data.board.label;
+    side = data.board.side;
+    var groups = data.sides || [];
+    // Segregate: one side at a time, never two sides in one list.
+    var sideBar = groups.length > 1 ? '<div class="pflb-sides">' + groups.map(function (g) {
+      return '<button type="button" data-side="' + esc(g.side) + '" class="' + (g.side === side ? 'on' : '') + '">' + esc(g.label) + '</button>';
+    }).join('') + '</div>' : '';
+    var mine = (groups.filter(function (g) { return g.side === side; })[0] || {}).boards || [];
+    var boardBar = mine.length > 1 ? '<div class="pflb-boards">' + mine.map(function (b) {
+      return '<button type="button" data-b="' + esc(b.id) + '" class="' + (b.id === board ? 'on' : '') + '">' + esc(b.label) + '</button>';
+    }).join('') + '</div>' : '';
+    var actor = data.board.actor ? '<span class="pflb-actor">' + esc(data.board.actor) + '</span>' : '';
     var tabs = periods.map(function (p) { return '<button type="button" data-p="' + esc(p) + '" class="' + (p === period ? 'on' : '') + '">' + esc(label(p)) + '</button>'; }).join('');
     var body = rows.length ? rows.map(function (r) {
       var isMe = me && r.id === me;
@@ -112,13 +131,21 @@ const WIDGET = String.raw`(function () {
       var m = data.me;
       meRow = '<tr class="me"><td class="rank">' + (m.rank ? (m.rank < 10 ? '0' : '') + m.rank : '–') + '</td><td class="name">' + esc(m.name) + ' <span style="color:var(--muted);font-weight:400">(you)</span></td><td class="val">' + esc(m.display) + '</td><td class="streak">' + (m.streak ? '🔥' + m.streak : '') + '</td></tr>';
     }
-    root.innerHTML =
-      '<div class="pflb-head"><h3 class="pflb-title">' + esc(title) + '</h3><div class="pflb-tabs">' + tabs + '</div>' + (root.classList.contains('pflb-panel') ? '<button class="pflb-close" aria-label="Close">×</button>' : '') + '</div>' +
+    root.innerHTML = sideBar +
+      '<div class="pflb-head"><h3 class="pflb-title">' + esc(title) + actor + '</h3><div class="pflb-tabs">' + tabs + '</div>' + (root.classList.contains('pflb-panel') ? '<button class="pflb-close" aria-label="Close">×</button>' : '') + '</div>' + boardBar +
       (rows.length || meRow
-        ? '<table><thead><tr><th>#</th><th>Name</th><th style="text-align:right">' + esc(data.board.unit || data.board.label) + '</th><th></th></tr></thead><tbody>' + body + meRow + '</tbody></table>'
+        ? '<table><thead><tr><th>#</th><th>' + esc(data.board.actor || 'Name') + '</th><th style="text-align:right">' + esc(data.board.unit || data.board.label) + '</th><th></th></tr></thead><tbody>' + body + meRow + '</tbody></table>'
         : '<div class="pflb-empty">Nobody on the board yet. Be first.</div>') +
       '<div class="pflb-foot"><span>' + esc(label(period)) + ' · ' + esc(String(data.total || rows.length)) + ' ranked</span><span><a href="' + esc(url('xml')) + '">RSS</a> · <a href="' + esc(origin + base + '?board=' + encodeURIComponent(board) + '&period=' + encodeURIComponent(period)) + '">Full board</a></span></div>';
     root.querySelectorAll('.pflb-tabs button').forEach(function (b) { b.addEventListener('click', function () { period = b.dataset.p; load(root); }); });
+    root.querySelectorAll('.pflb-sides button').forEach(function (b) {
+      b.addEventListener('click', function () {
+        var g = groups.filter(function (x) { return x.side === b.dataset.side; })[0];
+        if (!g || !g.boards.length) return;
+        board = g.boards[0].id; side = g.side; load(root);
+      });
+    });
+    root.querySelectorAll('.pflb-boards button').forEach(function (b) { b.addEventListener('click', function () { board = b.dataset.b; load(root); }); });
     root.querySelectorAll('.share').forEach(function (s) { s.addEventListener('click', function (e) { e.preventDefault(); copy(s.dataset.share, s); }); });
     var close = root.querySelector('.pflb-close');
     if (close) close.addEventListener('click', function () { root.hidden = true; });

package/src/index.js

@@ -7,6 +7,7 @@ export { commissionLadder } from './ladder.js';
 export { defaultBadges } from './badges.js';
 export { memoryStore } from './store/memory.js';
 export { sqlStore } from './store/sql.js';
+export { projectionStore } from './store/projection.js';
 
 const DAY = 86_400_000;
 const PERIODS = { all: 0, day: DAY, week: 7 * DAY, month: 30 * DAY };
@@ -39,6 +40,7 @@ export function createLeaderboard(options = {}) {
   const siteUrl = options.siteUrl ? trimSlash(options.siteUrl) : '';
   const periods = (options.periods ?? ['all', 'week', 'month']).filter((p) => p in PERIODS);
   const defaultPeriod = periods.includes(options.defaultPeriod) ? options.defaultPeriod : periods[0];
+  const sides = { ...DEFAULT_SIDES, ...(options.sides ?? {}) };
   const boards = normaliseBoards(options.boards);
   const defaultBoard = boards[0].id;
   const ladder = options.ladder === undefined ? null : options.ladder === true ? commissionLadder() : options.ladder;
@@ -194,7 +196,7 @@ export function createLeaderboard(options = {}) {
     }
     rows.sort((a, c) => a.rank - c.rank);
     const n = Math.min(limitMax, Math.max(1, Number(limit) || 25));
-    return { board: pub(b), period, periods, generatedAt: new Date(now()).toISOString(), total: rows.length, rows: rows.slice(Number(offset) || 0, (Number(offset) || 0) + n) };
+    return { board: pub(b), sides: boardsIndex().sides, period, periods, generatedAt: new Date(now()).toISOString(), total: rows.length, rows: rows.slice(Number(offset) || 0, (Number(offset) || 0) + n) };
   }
 
   async function standing({ player, board = defaultBoard, period = defaultPeriod } = {}) {
@@ -222,13 +224,17 @@ export function createLeaderboard(options = {}) {
       rank: r, id: p.id, name: p.name, value, display: format(value, b.format),
       streak: p.streak, bestStreak: p.bestStreak,
       badges: p.badges.map(({ id, emoji, label }) => ({ id, emoji, label })),
-      commission: p.commission ? p.commission.rate : undefined,
+      // A commission rate is a property of earning. Showing one against a buyer
+      // or a usage count states something false about the number next to it.
+      commission: b.side === 'sell' && p.commission ? p.commission.rate : undefined,
       url: profileUrl(p.id),
     };
   }
 
   function boardsIndex() {
-    return { site: siteName, siteUrl, basePath, periods, defaultPeriod, boards: boards.map(pub), ladder: ladder ? { base: ladder.base, cap: ladder.cap, describe: ladder.describe() } : null, badges: badges.map(({ id, emoji, label, describe }) => ({ id, emoji, label, describe })) };
+    const grouped = SIDES.filter((side) => boards.some((b) => b.side === side))
+      .map((side) => ({ side, label: sides[side], boards: boards.filter((b) => b.side === side).map(pub) }));
+    return { site: siteName, siteUrl, basePath, periods, defaultPeriod, sides: grouped, boards: boards.map(pub), ladder: ladder ? { base: ladder.base, cap: ladder.cap, describe: ladder.describe() } : null, badges: badges.map(({ id, emoji, label, describe }) => ({ id, emoji, label, describe })) };
   }
 
   /** Fetch-API handler: answers under basePath, null for anything else. */
@@ -272,7 +278,7 @@ export function createLeaderboard(options = {}) {
   }
 
   function rss(result) {
-    const title = `${siteName}: ${result.board.label} (${periodLabel(result.period)})`;
+    const title = `${siteName}: ${result.board.label}, ${sides[result.board.side]} (${periodLabel(result.period)})`;
     const link = `${siteUrl}${basePath}?board=${result.board.id}&period=${result.period}`;
     const items = result.rows.map((r) => {
       const badgeText = r.badges.map((b) => `${b.emoji} ${b.label}`).join(', ');
@@ -299,7 +305,7 @@ ${items.join('\n')}
   function embedPage({ board, period, limit, sticky, theme, me, full }) {
     const attrs = [
       `data-board="${esc(board.id)}"`, `data-period="${esc(period)}"`, `data-limit="${esc(String(limit))}"`,
-      sticky ? `data-sticky="${esc(sticky)}"` : '', theme ? `data-theme="${esc(theme)}"` : '', me ? `data-me="${esc(me)}"` : '',
+      sticky ? `data-sticky="${esc(sticky)}"` : '', theme ? `data-theme="${esc(theme)}"` : '', me ? `data-me="${esc(me)}"` : '', `data-side="${esc(board.side)}"`,
       `data-base="${esc(basePath)}"`,
     ].filter(Boolean).join(' ');
     const title = `${board.label}: ${siteName}`;
@@ -315,10 +321,13 @@ ${items.join('\n')}
   }
 
   function sharePage(p) {
-    const lines = boards.map((b) => {
-      const r = p.ranks[b.id]?.[defaultPeriod];
-      const v = p.values[b.id]?.[defaultPeriod];
-      return r ? `<li><strong>#${r}</strong> on ${esc(b.label)} <span class="muted">(${esc(periodLabel(defaultPeriod))}, ${esc(format(v, b.format))})</span></li>` : '';
+    const lines = SIDES.filter((side) => boards.some((b) => b.side === side)).map((side) => {
+      const items = boards.filter((b) => b.side === side).map((b) => {
+        const r = p.ranks[b.id]?.[defaultPeriod];
+        const v = p.values[b.id]?.[defaultPeriod];
+        return r ? `<li><strong>#${r}</strong> on ${esc(b.label)} <span class="muted">(${esc(periodLabel(defaultPeriod))}, ${esc(format(v, b.format))})</span></li>` : '';
+      }).filter(Boolean).join('');
+      return items ? `<h3 class="side">${esc(sides[side])}</h3><ul>${items}</ul>` : '';
     }).filter(Boolean).join('');
     const bestRank = Math.min(...boards.map((b) => p.ranks[b.id]?.[defaultPeriod] ?? Infinity));
     const headline = Number.isFinite(bestRank) ? `#${bestRank} on ${siteName}` : `${p.name} on ${siteName}`;
@@ -337,11 +346,12 @@ ${items.join('\n')}
 main{max-width:640px;margin:0 auto;padding:40px 20px}h1{font-size:28px;margin:0 0 4px}h2{font-size:12px;text-transform:uppercase;letter-spacing:.12em;color:#8b93a7;margin:24px 0 8px}
 .big{font-size:40px;font-weight:800;margin:0}.muted{color:#8b93a7}ul{list-style:none;padding:0;margin:0}li{padding:8px 0;border-bottom:1px solid #1f2430}.e{font-size:20px;margin-right:6px}
 a{color:#7cc4ff}.stats{display:flex;gap:24px;flex-wrap:wrap}.stats div b{display:block;font-size:22px}
+h3.side{font-size:11px;text-transform:uppercase;letter-spacing:.1em;color:#8b93a7;margin:16px 0 4px;font-weight:600}
 </style></head><body><main>
 <p class="muted"><a href="${esc(boardUrl)}">${esc(siteName)} leaderboard</a></p>
 <h1>${esc(p.name)}</h1><p class="muted">${esc(headline)}</p>
 <div class="stats"><div><b>${p.streak}</b><span class="muted">day streak</span></div><div><b>${p.bestStreak}</b><span class="muted">best streak</span></div><div><b>${p.badges.length}</b><span class="muted">badges</span></div></div>
-<section><h2>Boards</h2><ul>${lines || '<li class="muted">Not on a board yet.</li>'}</ul></section>
+<section><h2>Boards</h2>${lines || '<p class="muted">Not on a board yet.</p>'}</section>
 <section><h2>Badges</h2><ul>${badgeHtml}</ul></section>
 ${ladderHtml}
 <p class="muted" style="margin-top:32px"><a href="${esc(p.shareUrl)}">Share this page</a></p>
@@ -367,17 +377,29 @@ ${ladderHtml}
   };
 }
 
+/**
+ * Which side of the transaction a board ranks. Money flowing to someone is
+ * `sell`, money flowing from them is `buy`, and volume with no money attached
+ * is `use`. Boards are never mixed across sides: a seller earning $900 and a
+ * crawler spending $900 are not comparable, and showing them in one list is a
+ * lie about what the number means.
+ */
+export const SIDES = ['sell', 'buy', 'use'];
+const DEFAULT_SIDES = { sell: 'Earning', buy: 'Spending', use: 'Usage' };
+
 function normaliseBoards(input) {
   const src = input && Object.keys(input).length ? input : { top: { label: 'Top', metric: 'score' } };
   const list = Array.isArray(src) ? src : Object.entries(src).map(([id, b]) => ({ id, ...b }));
   return list.map((b) => {
     if (!b.id || !/^[a-z0-9_-]+$/i.test(b.id)) throw new TypeError(`board id must be [a-z0-9_-]: ${b.id}`);
-    return { id: b.id, label: b.label ?? b.id, metric: b.metric ?? 'score', format: b.format ?? 'number', min: Number.isFinite(b.min) ? b.min : Number.MIN_VALUE, order: b.order === 'asc' ? 'asc' : 'desc', tiebreak: b.tiebreak ?? null, unit: b.unit ?? '' };
+    const side = b.side ?? 'sell';
+    if (!SIDES.includes(side)) throw new TypeError(`board side must be one of ${SIDES.join(', ')}: ${side}`);
+    return { id: b.id, label: b.label ?? b.id, metric: b.metric ?? 'score', format: b.format ?? 'number', min: Number.isFinite(b.min) ? b.min : Number.MIN_VALUE, order: b.order === 'asc' ? 'asc' : 'desc', tiebreak: b.tiebreak ?? null, unit: b.unit ?? '', side, actor: b.actor ?? null };
   });
 }
 
 function pub(b) {
-  return { id: b.id, label: b.label, metric: b.metric, format: b.format, unit: b.unit };
+  return { id: b.id, label: b.label, metric: b.metric, format: b.format, unit: b.unit, side: b.side, actor: b.actor };
 }
 
 function blank(id) {

package/src/store/projection.js

@@ -0,0 +1,58 @@
+import { memoryStore } from './memory.js';
+
+/**
+ * A read-through store over tables you already have.
+ *
+ * Most sites that could show a leaderboard are already recording the facts it
+ * would rank: sales, payments, referral commissions, requests served. Copying
+ * those into a second set of tables means a dual write, and a dual write means
+ * the board and the ledger disagree the first time one of them fails. So
+ * project instead: hand back events built from the rows you already trust.
+ *
+ *   projectionStore({
+ *     events: async ({ since }) => {
+ *       const rows = await sql`select payer, total_cents, created_at from crawl_sales
+ *                              where created_at >= ${new Date(since)}`;
+ *       return rows.map((r) => ({
+ *         player: r.payer, name: r.payer, metric: 'spent',
+ *         delta: r.total_cents, at: +new Date(r.created_at),
+ *       }));
+ *     },
+ *   })
+ *
+ * `since` is 0 for an all-time board, so the query must handle "everything".
+ * Badges still need somewhere durable to live, since they are awarded rather
+ * than derived: pass `badges` (a `sqlStore`, or any object with `awardBadge`
+ * and `badges`). The default keeps them in memory, which is fine for a board
+ * with no badges and wrong for one with them.
+ *
+ * The store is read-only. `record()` and `set()` on a leaderboard backed by a
+ * projection throw, rather than silently dropping a write that the projection
+ * would overwrite on the next read anyway.
+ */
+export function projectionStore({ events, gauges, badges } = {}) {
+  if (typeof events !== 'function') throw new TypeError('projectionStore needs an events({ since }) function');
+  const badgeStore = badges ?? memoryStore();
+  const readOnly = (method) => () => {
+    throw new Error(`${method}() is not available on a projection store: write to the source table instead, the board reads it back`);
+  };
+  return {
+    async list({ since = 0 } = {}) {
+      const rows = (await events({ since })) ?? [];
+      return rows.map((e) => ({
+        player: String(e.player),
+        name: e.name == null ? undefined : String(e.name),
+        metric: String(e.metric),
+        delta: Number(e.delta) || 0,
+        at: Number(e.at) || 0,
+      }));
+    },
+    async gauges() {
+      return (typeof gauges === 'function' ? await gauges() : null) ?? {};
+    },
+    append: readOnly('record'),
+    setGauge: readOnly('set'),
+    awardBadge: (...a) => badgeStore.awardBadge(...a),
+    badges: () => badgeStore.badges(),
+  };
+}