A service that collects and manages GitHub API tokens from contributors to distribute rate limits across a shared pool. Inspired by Shields.io's token pool.

1. Contributors authenticate via GitHub OAuth (read-only public data access)
2. Tokens are encrypted (AES-256-GCM) and stored in SQLite
3. Consumer vals import getToken() to get a healthy token using LRU rotation
4. Rate limits are tracked per-token; exhausted tokens are quarantined until reset

This pool powers GitHub API calls in:

• github-zip-api — Fetch GitHub repo contents as zip
• claude-plugins-registry — Plugin registry for Claude Code

Go to https://github.com/settings/developers and create a new OAuth App:

• Application name: Token Pool (or whatever)
• Homepage URL: Your val endpoint
• Callback URL: https://<your-endpoint>/callback
• Scopes: None needed (public data only)

Add these to your val:

GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret
TOKEN_ENCRYPTION_KEY=<32 hex chars>

Generate encryption key: openssl rand -hex 32

Import directly from the pool library — no HTTP API needed (SQLite is shared across your vals and you must set TOKEN_ENCRYPTION_KEY env in the Val):

import {
  getToken,
  parseRateLimitHeaders,
  reportUsage,
} from "https://esm.town/v/kamalnrf/token-pool/lib/pool.ts";

// Get a healthy token (LRU selection)
const t = await getToken();

if (t) {
  const res = await fetch("https://api.github.com/repos/owner/repo", {
    headers: {
      Authorization: `Bearer ${t.token}`,
      "User-Agent": "my-val",
    },
  });

  // Report usage to update rate limit tracking
  await reportUsage(t.id, parseRateLimitHeaders(res.headers));
}

Returns the least-recently-used healthy token, or null if pool is empty/exhausted.

interface TokenWithSecret {
  id: number;
  github_user_id: string;
  github_username: string | null;
  token: string; // Decrypted, ready to use
  rate_limit_remaining: number;
  rate_limit_reset_at: number | null;
  // ...
}

Updates token health after API calls. Tokens with remaining <= 0 are marked unhealthy until reset_at.

Helper to extract rate limit info from GitHub response headers.