leetcode/apps/api/README.md

# srs-api

Cloudflare Worker running the spaced-repetition system: daily digest email,
one-tap logging, `/done` webhook, Saturday review issues, live SVG charts,
and the `/api/stats` feed for the docs progress page.

Live at `https://srs-api.prdlk.workers.dev`.

## Direction of truth

- **D1 owns SRS state** — stages, review dates, attempt history, gate
  scores, boost flags. Nothing else is authoritative.
- **GitHub issues own the catalog** — topics, problems, `set:*`/`diff:*`
  labels, milestones. `catalog.ts` reconciles them into D1 nightly (and via
  `/admin/reconcile`); it recomputes from scratch, never invents rows, and
  never overwrites SRS-owned columns (`stage`, `next_review`).
- **The repo owns the schedule** — `data/schedule.json`, human-edited,
  bundled at deploy. Git history is its audit log.
- The GitHub Project mirror writes `Target Date` and nothing else: it is
  best-effort, so failures log warnings and never block a D1 write, and topic
  rows are never written. SRS stage and first-attempt result stay in D1 only —
  the charts, digest and `/api/stats` read them from there, so mirroring them
  into Project single-selects bought only drift. Do not re-add them.
  `Set`/`Difficulty` are a projection of the issue labels, reconciled by
  `bun run sync-project-fields` at the repo root, not by this Worker.

## The ladder

`new → +3 → +7 → retired`; pass advances, fail resets to `+3`. A problem's
first-ever log enters at `+3` regardless of result. Stage names the NEXT
review's interval, and the two rungs are the same numbers as the `work/3` and
`work/7` buckets `bun run pick` scaffolds re-solves into.

**Sunday is never booked.** Topics run Mon–Fri, the gate is Saturday, and 3/7
are chosen so a solve returns on a working day: only a Thursday solve's `+3`
would land on the rest day, and `workingDay()` in `src/srs.ts` slides it to
Monday. Every scheduled date in the Worker — ladder reviews, levelled
overflow, deferred-Hard release dates — is minted by that one function, so the
rest day cannot be booked and then swallowed by the digest's Sunday branch.
Reviews may slip later, never earlier: pulling one back to Saturday would
shorten the interval it exists to test. `src/srs.test.ts` sweeps the whole
campaign calendar to prove it.

All dates are ET calendar strings anchored at noon UTC (`src/srs.ts`) — never
raw `Date` math.

Blind drills draw only from topics **already learned**: scheduled in an
earlier week (the current week's optional pool is reserved for Saturday's
gate) and with at least one core problem on the ladder — a skipped learning
day never feeds drills just because its calendar week lapsed.

## Routes

| Route | Auth | Purpose |
|---|---|---|
| `GET /log?p&r&d&sig` | HMAC (`LINK_KEY`) | one-tap pass/fail; idempotent per (problem, date, kind); links expire after 3 days |
| `POST /webhook/github` | HMAC (`WEBHOOK_SECRET`) | `/done <n> pass\|fail` comments (owner only, any issue); `review`-issue close → gate scoring |
| `GET /chart/{progress,ladder,heatmap}.svg`, `GET /badge/gate.svg` | public | hand-rolled SVGs, `max-age=300` (GitHub Camo's freshness floor) |
| `GET /api/stats` | public, CORS-pinned to the docs origin | one JSON document for `/progress` |
| `POST /admin/solved` | `Authorization: Bearer <LINK_KEY>` | `{"solved":[{"lc":1,"bucket":1},…]}` — solutions committed under `work/`; the bucket names the rung it settles (1 → `new`, 3 → `+3`, 7 → `+7`), so a first solve enters the ladder and a pushed re-solve advances it. Writes only when the problem stands on that rung, which is what makes re-posting the whole set a no-op. Takes `?dry=1&date=` |
| `POST /admin/due` | `Authorization: Bearer <LINK_KEY>` | read-only: what the ladder has due on `?date=` (default today), oldest first, with the rung/bucket, how late it is, and when it was last seen. The one answer behind the daily `Spaced Repetition` issue |
| `POST /admin/{digest,review,reconcile}` | `Authorization: Bearer <LINK_KEY>` | manual triggers; `digest` takes `?dry=1&force=1&date=` |

## Crons (DST-proof)

Each event has two UTC crons; code fires only when the computed ET hour
matches (`etHour` in `src/srs.ts`, unit-checked in `src/srs.test.ts`):

- `0 12,13 * * *` → 8 AM ET: catalog reconcile, then the digest.
- `0 4,5 * * 6` → midnight ET Saturday: create `Review — Week N` (so the
  8 AM digest can link to it).

## Secrets & bindings

`wrangler secret put` — `GH_PAT` (Issues + Projects RW), `WEBHOOK_SECRET`
(matches the repo webhook), `LINK_KEY` (signs one-tap links, gates admin
routes). Bindings in `wrangler.jsonc`: `DB` (D1 `srs`), `EMAIL`
(`send_email`, restricted to the verified destination). Sender domain
`prdlk.com` is onboarded to Email Sending.

Three Actions workflows talk to this Worker with the `SRS_ADMIN_KEY` repo
secret:

- `sync-d1.yml` sends curriculum issue edits to `POST /admin/reconcile` (the
  morning cron is the backstop).
- `close-solved.yml` sends the whole implemented `work/` set — each entry
  tagged with its bucket — to `POST /admin/solved` on every push to `main`.
  That call is what keeps a committed solution from being invisible here:
  closing an issue is not a state change the Worker can see (the catalog
  reconcile ignores issue state, and only `logAttempt()` moves the ladder), and
  the bucket is what lets a pushed re-solve advance `+3 → +7` instead of
  being read as a stale first solve. `close-solved` still owns the issue close
  itself (it knows the files and the commit), so this path only writes D1 and
  mirrors Project fields.
- `spaced-repetition.yml` reads `POST /admin/due` at 06:00 ET and renders
  today's `Spaced Repetition` issue. Read-only, and the only schedule involved
  is this Worker's ladder.

## Local dev

```sh
cp .dev.vars.example .dev.vars       # or fill GH_PAT/WEBHOOK_SECRET/LINK_KEY
bun install
bunx wrangler d1 migrations apply srs --local
bun run dev                          # wrangler dev on :8787, local D1
curl -X POST -H "Authorization: Bearer $LINK_KEY" \
  "localhost:8787/admin/digest?dry=1&date=2026-08-31"   # prints HTML, sends nothing
bun test src                         # DST guards, date math, the rest-day sweep
```

`?date=` on admin routes is the `SRS_TODAY` equivalent. Migrations are
append-only and applied in order; `0002_ladder_3_7.sql` is the +2/+5/+10 →
`+3`/`+7` rebuild, which also lifts every date that was sitting on a Sunday.
The one-shot importer for the retired `.github/srs/srs.json` is gone — that
state no longer exists, and git history is its record.

## Deploy

```sh
bun run deploy        # from apps/api/, or `bun run api:deploy` at the repo root
```

CI deploys on every push to `main` (`deploy.yml`, gated on `bun run api:test`,
using the `CLOUDFLARE_API_TOKEN`/`CLOUDFLARE_ACCOUNT_ID` repo secrets); the
commands above are for out-of-band deploys. After changing bindings, rerun
`bunx wrangler types`.