feat: add token usage tracking and leaderboard

- Add token_usage table with composite unique index for claw_id + date
- Add API endpoints: POST /token, GET /token/leaderboard, GET /token/stats
- Add TokenLeaderboard component with daily/total period toggle
- Add CLI commands: `token` and `stats` for reporting and viewing usage
- Add Redis caching for leaderboard with 1-minute TTL
- Add shared utilities: authenticateRequest, getTodayDateString
- Use UPSERT pattern for atomic token updates
- Add i18n translations (en/zh) for new UI elements

lib/db/schema.ts

@@ -7,6 +7,7 @@ import {
   datetime,
   json,
   index,
+  uniqueIndex,
 } from "drizzle-orm/mysql-core";
 import { sql } from "drizzle-orm";
 
@@ -70,3 +71,21 @@ export const geoCache = mysqlTable("geo_cache", {
   region: varchar("region", { length: 50 }),
   updatedAt: datetime("updated_at").default(sql`NOW()`),
 });
+
+export const tokenUsage = mysqlTable(
+  "token_usage",
+  {
+    id: bigint("id", { mode: "number" }).primaryKey().autoincrement(),
+    clawId: varchar("claw_id", { length: 21 }).notNull(),
+    date: varchar("date", { length: 10 }).notNull(), // YYYY-MM-DD
+    inputTokens: bigint("input_tokens", { mode: "number" }).notNull().default(0),
+    outputTokens: bigint("output_tokens", { mode: "number" }).notNull().default(0),
+    createdAt: datetime("created_at").default(sql`NOW()`),
+    updatedAt: datetime("updated_at").default(sql`NOW()`),
+  },
+  (table) => [
+    index("token_usage_claw_id_idx").on(table.clawId),
+    index("token_usage_date_idx").on(table.date),
+    uniqueIndex("token_usage_claw_date_unq").on(table.clawId, table.date),
+  ]
+);

lib/redis/index.ts

@@ -105,3 +105,30 @@ export async function getCacheHeatmap(): Promise<string | null> {
 export async function publishEvent(event: object): Promise<void> {
   await redis.publish(CHANNEL_REALTIME, JSON.stringify(event));
 }
+
+// Token Leaderboard Cache
+const TOKEN_LEADERBOARD_DAILY_KEY = "cache:token_leaderboard:daily";
+const TOKEN_LEADERBOARD_TOTAL_KEY = "cache:token_leaderboard:total";
+
+export async function setTokenLeaderboardCache(
+  period: "daily" | "total",
+  date: string,
+  data: string
+): Promise<void> {
+  const key = period === "daily" ? TOKEN_LEADERBOARD_DAILY_KEY : TOKEN_LEADERBOARD_TOTAL_KEY;
+  await redis.set(`${key}:${date}`, data, "EX", 60); // 1 minute cache
+}
+
+export async function getTokenLeaderboardCache(
+  period: "daily" | "total",
+  date: string
+): Promise<string | null> {
+  const key = period === "daily" ? TOKEN_LEADERBOARD_DAILY_KEY : TOKEN_LEADERBOARD_TOTAL_KEY;
+  return redis.get(`${key}:${date}`);
+}
+
+export async function invalidateTokenLeaderboardCache(): Promise<void> {
+  const today = new Date().toISOString().split("T")[0];
+  await redis.del(`${TOKEN_LEADERBOARD_DAILY_KEY}:${today}`);
+  await redis.del(`${TOKEN_LEADERBOARD_TOTAL_KEY}:${today}`);
+}

lib/utils.ts

@@ -1,6 +1,37 @@
 import { type ClassValue, clsx } from "clsx";
 import { twMerge } from "tailwind-merge";
+import { NextRequest, NextResponse } from "next/server";
+import { validateApiKey } from "@/lib/auth/api-key";
 
 export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs));
 }
+
+/**
+ * Get today's date as YYYY-MM-DD string
+ */
+export function getTodayDateString(): string {
+  return new Date().toISOString().split("T")[0];
+}
+
+/**
+ * Authenticate an API request with Bearer token
+ * Returns the claw object if authenticated, or a 401 NextResponse if not
+ */
+export async function authenticateRequest(req: NextRequest) {
+  const authHeader = req.headers.get("authorization");
+  if (!authHeader?.startsWith("Bearer ")) {
+    return NextResponse.json(
+      { error: "Missing or invalid authorization header" },
+      { status: 401 }
+    );
+  }
+
+  const apiKey = authHeader.slice(7);
+  const claw = await validateApiKey(apiKey);
+  if (!claw) {
+    return NextResponse.json({ error: "Invalid API key" }, { status: 401 });
+  }
+
+  return { claw };
+}

lib/validators/schemas.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 
+const MAX_TOKENS = 1_000_000_000_000; // 1 trillion
+
 export const registerSchema = z.object({
   name: z.string().min(1).max(100),
   platform: z.string().optional(),
@@ -19,6 +21,13 @@ export const taskSchema = z.object({
   toolsUsed: z.array(z.string()).optional(),
 });
 
+export const tokenSchema = z.object({
+  inputTokens: z.number().int().nonnegative().max(MAX_TOKENS),
+  outputTokens: z.number().int().nonnegative().max(MAX_TOKENS),
+  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+});
+
 export type RegisterInput = z.infer<typeof registerSchema>;
 export type HeartbeatInput = z.infer<typeof heartbeatSchema>;
 export type TaskInput = z.infer<typeof taskSchema>;
+export type TokenInput = z.infer<typeof tokenSchema>;