reduce api surface, rework

Author: Tsche

.github/workflows/pages.yml

@@ -17,7 +17,6 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      pages: write
     steps:
       - uses: actions/checkout@v5
       - uses: actions/setup-node@v5
@@ -27,12 +26,6 @@ jobs:
           cache-dependency-path: runtime/package-lock.json
       - run: npm ci
         working-directory: runtime
-      # - run: npm run check
-      #   working-directory: runtime
-      # - run: npm run lint
-      #   working-directory: runtime
-      # - run: npm test
-      #   working-directory: runtime
       - run: npm run build
         working-directory: runtime
       - name: Stage Pages metadata

.gitignore

@@ -224,4 +224,5 @@ __marimo__/
 # Streamlit
 .streamlit/secrets.toml
 
-config/data/*
+config/data/*
+vps-config/

README.md

@@ -78,23 +78,35 @@ const resource = resourceFromDocument({
 });
 ```
 
-The bundled read-only discussion example can render the feedback site's test
-thread, including labels, canonical reaction counters, minimized comments, and
-replies:
+The bundled example exercises multiple threads, batched native upvotes, main-post
+reactions, labels, polls, comments, minimized/deleted comments, replies, accepted
+answers, author associations, and GitHub links. Supply
+comma-separated resource keys with `keys`:
 
-`https://feedback.cpp.social/example/?site=feedback-cpp-social&key=feedback%2Fexample&github=link`
+`https://feedback.cpp.social/example/?site=feedback-cpp-social&keys=feedback%2Fexample%2Cfeedback%2Fexample-two&github=link`
 
-## Counter cache
+## API and intent configuration
 
-The service database is a cache of GitHub discussions. It keeps
-lightweight discussion and comment metadata in `discussions` and `comments`,
-content separately in `content`, main-post reactions in `reactions`, comment
-reactions in `comment_reactions`, and discussion labels through
-`discussion_labels`. Reaction rows retain GitHub account IDs when the API
-returns them; an aggregate remainder row is used for accounts not included in
-the returned user page. The public API is read-only for discussion content and
-counters; discussion creation, voting, starring, and comment moderation are not
-exposed.
+Every site must list its required `intents`. Disabled intents return 404 and do
+not activate their refresh paths. The route contract, intent matrix, and audit
+of every server-side GitHub request path are in [docs/API.md](docs/API.md).
+
+The browser runtime sends user-specific viewer queries, native upvotes, and comments
+directly to GitHub. The service handles OAuth, discussion discovery/creation, and
+shared anonymous reads where caching prevents every visitor consuming a GitHub
+request.
+
+Use `--verbose` for privacy-safe route/status/timing and cache-decision logs. It
+does not log credentials, OAuth codes, bodies, origins, resource URLs, or client
+addresses.
+
+## Counter cache and discussion content
+
+The service database keeps discussion identifiers and aggregate counters only.
+Discussion/comment bodies are never persisted or
+reused between requests, preventing deleted content from being served from a
+stale cache. Only concurrent reads for the same thread share an in-flight GitHub
+call.
 
 `cache_fresh_seconds` is the age at which a requested tracked counter needs an
 authoritative GitHub refresh. The default is five seconds. A batched request
@@ -111,28 +123,26 @@ batch. The default is five seconds.
 `refresh_sweep_seconds` controls the low-priority full maintenance cycle. The
 default is 86400 seconds (daily). The service walks only discussions whose last
 authoritative snapshot is that old, in batches of 50 with pacing between full
-batches. Targeted requests and successful votes continue independently.
+batches. Targeted requests and successful upvotes continue independently.
 
-Votes made through the runtime update SQLite immediately using an atomic,
-confirmed delta. These local values are tentative: they do not change the last
-GitHub-refresh timestamp, and the next successful targeted or maintenance refresh
-replaces them with GitHub's absolute counts. Counter responses use `no-cache`, so
+Browser mutations do not write speculative server values. The next successful
+targeted or maintenance refresh replaces counters with GitHub's absolute counts.
+Counter responses use `no-cache`, so
 browsers revalidate with this service; that does not imply a GitHub request while
 the relevant snapshot remains fresh.
 
 The browser runtime keeps the last counter snapshot and the last confirmed viewer
-vote/star state in local storage for up to seven days. Consumers can render them
+native-upvote state in local storage for up to seven days. Consumers can render them
 synchronously while the API request is in flight, avoiding a flash of zero counters
 or unselected vote buttons. Snapshots contain only the site/resource key, discussion
-node ID, counts, viewer state, star state, and save time; authentication tokens are not part of
+node ID, counts, viewer state, and save time; authentication tokens are not part of
 this cache. Storage is optional and failures fall back to the network normally.
 
-Once authenticated, the runtime also resolves the current user's vote and star
+Once authenticated, the runtime also resolves the current user's native-upvote
 state for all visible discussions in one batched GitHub query. That viewer-specific
 snapshot is reused for five minutes, including across reloads, and then refreshed
 on demand. This makes reactions created on GitHub or another device visible without
-turning every counter request into an authenticated GitHub request. Stars map to
-GitHub's `EYES` reaction because Discussions does not provide a star reaction.
+turning every counter request into an authenticated GitHub request.
 
 Operational logs are emitted at GitHub boundaries rather than for every HTTP
 request. Reaction-refresh lines include the site, trigger (`requested` or

config/sites.dev.toml

@@ -12,9 +12,14 @@ http_request_timeout_seconds = 10
 
 [sites.feedback-cpp-social]
 origins = ["https://feedback.cpp.social"]
+mode = "discussion"
 mapping = "key"
 repository = "cppsocial/feedback"
 repository_id = "R_kgDOUc9png"
 installation_id = 162105624
-category = "General"
-category_id = "DIC_kwDOUc9pns4DFwQt"
+default_category = "general"
+intents = ["upvotes", "reactions", "discussion", "comments", "labels", "github_link"]
+
+[sites.feedback-cpp-social.categories.general]
+name = "General"
+id = "DIC_kwDOUc9pns4DFwQt"

config/sites.example.toml

@@ -10,19 +10,30 @@ http_request_timeout_seconds = 10
 
 [sites.example]
 origins = ["https://www.example.com"]
+mode = "discussion"
 mapping = "key"
 repository = "example/site"
 repository_id = "replace-with-repository-node-id"
 installation_id = 1
-category = "Resources"
-category_id = "replace-with-category-node-id"
+default_category = "articles"
+discussion_body = "Discussion for [{title}]({url})."
 
 # Optional cache tuning; these are the defaults.
 # cache_fresh_seconds = 5
 # refresh_cooldown_seconds = 5
 # refresh_sweep_seconds = 86400
 # max_batch_size = 100
-features = ["counters", "viewer_reactions", "voting", "discussion", "comments", "labels", "github_link"]
+intents = ["upvotes", "reactions", "discussion", "comments", "answers", "polls", "authors", "moderation", "comment_reactions", "comment_upvotes", "labels", "github_link"]
 reaction_counters = ["LAUGH", "HOORAY", "CONFUSED", "HEART", "ROCKET", "EYES"]
-upvote_source = "both" # thumbsup, native, or both
-downvotes = true
+
+[sites.example.categories.articles]
+name = "Articles"
+id = "replace-with-articles-category-node-id"
+
+[sites.example.categories.tips]
+name = "Tips"
+id = "replace-with-tips-category-node-id"
+
+[sites.example.categories.updates]
+name = "Updates"
+id = "replace-with-updates-category-node-id"

config/sites.toml

@@ -10,22 +10,30 @@ http_request_timeout_seconds = 10
 
 [sites.feedback-cpp-social]
 origins = ["https://feedback.cpp.social"]
+mode = "discussion"
 mapping = "key"
 repository = "cppsocial/feedback"
 repository_id = "R_kgDOUc9png"
 installation_id = 162105624
-category = "General"
-category_id = "DIC_kwDOUc9pns4DFwQt"
-features = ["counters", "viewer_reactions", "voting", "discussion", "comments", "labels", "github_link"]
+default_category = "general"
+discussion_body = "Feedback for [{title}]({url})"
+intents = ["upvotes", "reactions", "discussion", "comments", "labels", "github_link"]
 reaction_counters = ["LAUGH", "HOORAY", "CONFUSED", "HEART", "ROCKET", "EYES"]
-upvote_source = "both"
-downvotes = true
+
+[sites.feedback-cpp-social.categories.general]
+name = "General"
+id = "DIC_kwDOUc9pns4DFwQt"
 
 [sites.cpp-social]
 origins = ["https://cpp.social"]
+mode = "ranking"
 mapping = "key"
 repository = "cppsocial/site"
 repository_id = "R_kgDOSOfNQQ"
 installation_id = 162105624
-category = "Resources"
-category_id = "DIC_kwDOSOfNQc4DFW7W"
+default_category = "resources"
+intents = ["upvotes"]
+
+[sites.cpp-social.categories.resources]
+name = "Resources"
+id = "DIC_kwDOSOfNQc4DFW7W"

docs/API.md

@@ -0,0 +1,109 @@
+# Feedback API and browser package
+
+The system maps a site-defined resource key to one GitHub Discussion. Resource
+keys are stable and known by the consuming site; use category-qualified keys such
+as `articles/ranges`, `tips/vector-growth`, and `updates/2026-09`. The first path
+component selects a configured GitHub Discussion category. Unrecognised prefixes
+use `default_category`.
+
+There are two site modes:
+
+- `ranking` exposes batched native GitHub Discussion upvote counts. It may also
+  expose explicitly selected reaction counts. It has no discussion-content API.
+- `discussion` can expose a full thread, post reactions, comments and replies,
+  answers, polls, author associations, moderation state, labels, comment
+  reactions/upvotes, and GitHub links. Each extra group is enabled by an intent.
+
+An unauthenticated visitor can read configured data but cannot mutate it. OAuth
+is initiated only by user interaction. The browser then talks directly to
+GitHub for viewer state and mutations; the service never receives the user's
+GitHub token after exchange and provides no general user-token proxy.
+
+## Configuration and intents
+
+Every site declares `mode`, `intents`, one or more categories, and a default
+category. `discussion_body` is the template used only when creating a thread and
+supports `{key}`, `{title}`, and `{url}`.
+
+| Intent | Returned or enabled data |
+| --- | --- |
+| `upvotes` | Native Discussion `upvoteCount`; required for `/reactions` |
+| `reactions` | Main-post reaction groups selected by `reaction_counters` |
+| `discussion` | Authoritative thread read and discussion creation |
+| `comments` | Comments and replies |
+| `answers` | Accepted-answer state |
+| `polls` | Poll question, options, and totals |
+| `authors` | Author identity and `authorAssociation` |
+| `moderation` | Minimized state and reason |
+| `comment_reactions` | Comment/reply reaction totals |
+| `comment_upvotes` | Comment/reply native upvote totals |
+| `labels` | Discussion labels |
+| `github_link` | Discussion/comment URLs and discussion number in counter results |
+
+Ranking mode accepts only `upvotes` and `reactions`. Discussion metadata intents
+require `discussion`; comment-specific metadata requires `comments`. Disabled
+features return 404 and do not add fields to GitHub queries or API responses.
+
+## HTTP routes
+
+All JSON responses contain `v: 1`. Errors are
+`{"v":1,"error":{"code":"...","message":"..."}}`.
+
+| Method | Route | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/sites/{site}/reactions?keys=a,b` | Sorted, deduplicated batch of up to `max_batch_size` counters |
+| `POST` | `/v1/sites/{site}/oauth/authorize` | Start PKCE OAuth with `challenge` and `nonce` |
+| `POST` | `/v1/sites/{site}/oauth/exchange` | Exchange `code`, `state`, and `verifier`; return token plus an origin-bound creation grant |
+| `POST` | `/v1/sites/{site}/discussions/ensure` | Find or create a thread for a validated resource and grant |
+| `GET` | `/v1/sites/{site}/discussion?keys=a` | Fetch one authoritative configured thread |
+
+A minimal counter response is:
+
+```json
+{"v":1,"site":"cpp-social","items":{"resources/42":{"id":"D_...","upvotes":17}}}
+```
+
+`number` is included only for `github_link`; `reactions` is included only when
+`reaction_counters` is non-empty. Cache age and server internals are not exposed.
+Unknown resources have `id: null` and zero counts. Counter responses revalidate
+with an ETag. Discussion and OAuth responses are `no-store`.
+
+## Browser API
+
+`FeedbackClient.reactions(keys)` performs the multi-key service read.
+`createUpvoteControls()` creates accessible buttons, batches their initial read,
+authenticates on activation, creates a missing discussion lazily, and sends the
+native upvote directly to GitHub. `createAuthenticationStatus()` is deliberately
+independent so a site can mount login/status anywhere.
+
+The package also exports direct, typed GitHub helpers for comment/reply creation,
+comment editing/deletion, reactions, poll votes, accepted answers, native
+upvotes, and batched viewer-upvote state. A discussion UI can compose these
+without routing user actions through the service. Authentication tokens are held
+in session storage; counter/viewer snapshots contain no token.
+
+## GitHub request audit and abuse boundaries
+
+The server can contact GitHub only in these places:
+
+1. OAuth code exchange. State, PKCE, exact origins, expiry, and single-purpose
+   creation grants bound the flow.
+2. GitHub App installation-token acquisition. Tokens are cached until shortly
+   before expiry and acquisition is serialized.
+3. Counter refresh. Stale discussion IDs are grouped into `nodes(ids:)` batches
+   of at most 50. Per-site in-flight work is shared, failures have a cooldown,
+   global GitHub concurrency is capped, and maintenance sweeps are paced.
+4. Discussion discovery/creation. Work is serialized per site/resource; exact
+   repository and category matches are required, and the resulting ID is stored.
+5. Discussion reads. A read is authoritative; simultaneous reads of the same
+   thread share only the in-flight request. The response is never retained.
+
+Request sizes, key syntax, JSON fields, body sizes, origins, and batch size are
+bounded. Security headers are applied globally. Logs omit tokens, OAuth codes,
+comment bodies, URLs, origins, and client addresses. `--verbose` enables safe
+route timing and cache/GitHub-boundary diagnostics.
+
+The database stores discussion identity and aggregate counters only. It does not
+store discussion or comment bodies. Consequently a later request cannot serve a
+cached copy of deleted content; deleted nodes returned by GitHub are represented
+only by their deletion state, and frontend renderers must not render their body.

runtime/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cppsocial/feedback-runtime",
   "version": "0.1.0",
-  "private": true,
+  "private": false,
   "type": "module",
   "files": [
     "dist/package"

runtime/pages/example/index.html

@@ -11,11 +11,12 @@
   <body>
     <main>
       <h1>Feedback integration example</h1>
-      <p>This page renders the feedback discussion, canonical reactions, labels, comments, minimized comments, and replies.</p>
+      <p>This page exercises batched native upvotes, multiple discussion threads, reactions, labels, polls, comments, minimized or deleted comments, replies, accepted answers, and GitHub links.</p>
       <p>API: <code id="api-origin"></code></p>
       <div id="authentication-status" class="authentication-status"></div>
       <section id="thread" class="thread"></section>
       <form id="comment-form" class="comment-form">
+        <label>Thread <select id="comment-key"></select></label>
         <textarea id="comment-body" rows="4" maxlength="16000" placeholder="Add a comment"></textarea>
         <button type="submit">Sign in and comment</button>
         <button id="clear-reply" type="button" hidden>Cancel reply</button>

runtime/pages/example/style.css

@@ -31,11 +31,13 @@ main {
 }
 
 .thread {
-  border: 1px solid #ddd;
-  border-radius: 0.5rem;
-  padding: 1rem;
+  display: grid;
+  gap: 1rem;
 }
 
+.discussion { border: 1px solid #ddd; border-radius: 0.5rem; padding: 1rem; }
+.controls { display: flex; flex-wrap: wrap; gap: 0.5rem; margin-top: 1rem; }
+
 .thread h2 {
   font-size: 1rem;
   margin: 0;