Merge pull request #119 from conorbronsdon/feat/post-rankings-101

Add rank_posts for bounded post rankings from email statistics (#101)

Author: conorbronsdon

CHANGELOG.md

@@ -9,6 +9,13 @@ and the git tag history (`v0.1.0`–`v0.5.0`).
 ## [Unreleased]
 
 ### Added
+- `rank_posts` (#101) ranks posts by one metric from Substack's dashboard email statistics: views,
+  opened, sent, open_rate, click_through_rate, signups, subscribes, estimated_value or post_date, in
+  either direction. It makes one read of up to 20 rows, Substack's page limit, and reports total and
+  next_offset. Only metrics whose server-side sorting was checked live are accepted. Rows keep
+  Substack's order and mark each ranked value as reported, null or absent, and nothing is filled in
+  or recomputed. Rate denominators are documented as unknown. See
+  [docs/analytics-rankings.md](docs/analytics-rankings.md).
 - Native footnotes in long-form drafts (#104). A GFM reference `[^id]` in a top-level paragraph
   becomes a `footnoteAnchor`, and its one-paragraph definition becomes a `footnote` block directly
   after that paragraph. Numbers follow reference order, matching a structure captured from the
@@ -23,6 +30,16 @@ and the git tag history (`v0.1.0`–`v0.5.0`).
   declared type. Failures return a typed `code` with `upload_attempts: 0`. The Cloudflare Worker returns
   `remote_image_unavailable`. See [docs/remote-images.md](docs/remote-images.md).
 
+### Changed
+- `get_post_analytics` says why a post was not found (#101): `search_result` is `archive_exhausted`
+  when the search reached the end of the published feed with consistent pages (separate reads, so
+  concurrent publishing or deletion can still hide a post), `scan_bound_reached` when the 500-post bound was hit
+  first, or `feed_incomplete` when the feed's pages were incomplete or inconsistent (fewer posts than
+  reported, a changing total, or repeated posts), so an unsearched post's statistics are reported as
+  unknown rather than absent. Not-found
+  results add `scanned` and `feed_capped` (the feed's `isCapped` flag, uninterpreted), and found
+  posts add `stats_available`. Existing fields are unchanged.
+
 ## [1.1.1] - 2026-09-14
 
 ### Fixed

README.md

@@ -233,6 +233,7 @@ authoritative wording.
 | `get_post_comments` | Get comments on a published post |
 | `get_sections` | List your publication's sections (categories) with their IDs |
 | `get_post_analytics` | Get a published post's stats (views, opens, signups, subscribes, reactions) by ID |
+| `rank_posts` | [Rank posts](docs/analytics-rankings.md) by views, opens, sends, rates, signups, subscribes, estimated value or date, keeping null and missing values distinct |
 | `list_scheduled_posts` | List posts scheduled for future publication (read-only; scheduling stays in Substack's editor) |
 
 ### Archive search and draft review

docs/analytics-rankings.md

@@ -0,0 +1,102 @@
+# Post rankings
+
+`rank_posts` ranks posts by one metric from Substack's dashboard email
+statistics. It is a single read and never changes anything.
+
+```json
+{ "metric": "subscribes", "direction": "desc", "limit": 10, "offset": 0 }
+```
+
+| Input | Values | Default |
+| --- | --- | --- |
+| `metric` | `views`, `opened`, `sent`, `open_rate`, `click_through_rate`, `signups`, `subscribes`, `estimated_value`, `post_date` | `views` |
+| `direction` | `desc`, `asc` | `desc` |
+| `limit` | 1–20 | 10 |
+| `offset` | 0 or more | 0 |
+
+Only metrics whose sorting was checked against the live endpoint are accepted.
+The endpoint silently accepts unknown sort fields and misspelled parameters, so
+anything else is rejected before a request is made. No filters are supported:
+an extra argument such as `section_id` is rejected rather than ignored, so a
+result is never presented as filtered when it is not. Substack rejects page
+sizes above 20.
+
+## Result
+
+Each row has its `rank` (position from `offset + 1`), `post_id`, `title`,
+`post_date`, `type`, the ranked `value`, a `value_state`, a fixed set of
+`metrics`, and `absent_metrics`. The page also reports `total`, `returned`,
+`has_more`, `next_offset` and `unreported_in_page`.
+
+| `value_state` | Meaning |
+| --- | --- |
+| `reported` | Substack returned a number (or date) |
+| `null` | Substack returned `null` |
+| `absent` | The row omitted the field |
+
+`null` and `absent` are not zero, and this server never fills them in. In
+`metrics`, both appear as `null`; `absent_metrics` names the omitted fields.
+
+## Ordering and coverage
+
+Rows keep Substack's order; nothing is re-sorted. Checked on September 14, 2026:
+
+- Numeric values are correctly ordered in both directions for every accepted metric.
+- Rows missing a count field come last in descending order and first in ascending order.
+- For `open_rate` and `click_through_rate`, rows with a `null` rate are placed
+  among the numeric rows, not at one end. Treat those positions as unranked.
+
+`total` is Substack's count for its email statistics list. It may exclude posts
+without email statistics, such as posts that were never emailed. Each page is a
+separate read, so rankings can shift between calls if statistics change.
+
+A page must agree with `total`. The page at `offset == total` is empty, which
+ends continuation. An empty or short page before that point, or rows past
+`total`, is rejected instead of being reported as the end of the list.
+
+## Metric meanings
+
+Values are passed through as Substack reports them. Substack does not document
+the denominators or units of `open_rate` and `click_through_rate`, so this server
+does not describe them as percentages of any particular count. `opened` and
+`sent` are Substack's own counts; they are not unique-reader counts unless
+Substack says so. `estimated_value` is Substack's estimate.
+
+`post_date` is Substack's timestamp string, returned unchanged. It must parse as
+a date; its timezone is whatever the string states.
+
+## One post by ID
+
+`get_post_analytics` reads a single post's statistics from the published feed,
+searching the 500 most recent published posts. When the post is not found,
+`search_result` says why. `archive_exhausted` is only reported when the pages agree: a short final
+page with no contradicting total, or full pages that exactly reach a total reported identically on
+every page. Every page is still a separate offset read, not an atomic snapshot. If one post is
+published and another deleted between reads, the total can stay the same while a post shifts past a
+page boundary unseen, so `archive_exhausted` means the search reached the end of the feed as paged,
+not proof that the post never existed. Retry when the feed may be changing.
+
+| `search_result` | Meaning |
+| --- | --- |
+| `archive_exhausted` | The search reached the end of the feed as paged, with consistent pages |
+| `scan_bound_reached` | The 500-post bound was reached first. An older post may exist; its statistics are unknown here, not absent |
+| `feed_incomplete` | The feed's pages were incomplete or inconsistent: fewer posts than the reported total, a total that changed between pages or appeared on only some pages, more posts than the total, or a post repeated across pages. The search cannot rule the post out; its statistics are unknown here |
+
+`scanned` is the number of posts examined. `feed_capped` passes through the
+feed's `isCapped` flag, uninterpreted, or `null` when Substack omits it. A found
+post has `stats_available: false` when Substack returned no statistics for it;
+its metric fields are then `null`, not zero.
+
+## Errors
+
+HTTP 403 or 404 from the statistics endpoint returns `code:
+"analytics_unavailable"` with its `status`. It means Substack did not provide
+statistics to this account or publication, not that the ranking is empty. This
+server does not check publication tier or eligibility in advance; it reports what
+Substack returns.
+
+Rate limiting and other upstream failures return the standard read error with
+`status` and a validated `retry_after` when Substack provides one; there is no
+automatic retry. A response that does not match the expected shape (including
+more rows than requested, duplicate posts or non-numeric metrics) is rejected
+without returning partial results.

scripts/test-container.mjs

@@ -24,8 +24,8 @@ assert.equal(status.version, pkg.version);
 const catalog = async client => {
   assert.equal(client.getServerVersion().version, pkg.version);
   const { tools } = await client.listTools();
-  assert.equal(tools.length, 24);
-  for (const name of ['get_publication', 'list_drafts', 'plan_draft_update', 'update_draft']) assert.ok(tools.some(tool => tool.name === name));
+  assert.equal(tools.length, 25);
+  for (const name of ['get_publication', 'list_drafts', 'plan_draft_update', 'update_draft', 'rank_posts']) assert.ok(tools.some(tool => tool.name === name));
   for (const name of ['publish_post', 'delete_post', 'schedule_post']) assert.ok(!tools.some(tool => tool.name === name));
 };
 const prefix = `substack-smoke-${randomUUID()}`;

scripts/test-package.mjs

@@ -25,7 +25,7 @@ const expectedTools = [
   'list_scheduled_posts', 'list_subscribers', 'update_draft', 'upload_image',
   'search_posts', 'preflight_draft', 'plan_draft_update',
   'get_publication',
-  'list_publication_tags', 'get_post_tags',
+  'list_publication_tags', 'get_post_tags', 'rank_posts',
 ].sort();
 
 const requiredFiles = ['package.json', 'server.json', 'README.md', 'LICENSE', 'CHANGELOG.md',
@@ -138,7 +138,7 @@ try {
   assert.equal(client.getServerVersion()?.version, pkg.version, 'MCP handshake version must match npm');
   const { tools } = await client.listTools({}, { timeout: 10_000 });
   assert.deepEqual(tools.map(tool => tool.name).sort(), expectedTools);
-  assert.equal(tools.filter(tool => tool.outputSchema).length, 20, "Object tools must advertise output schemas");
+  assert.equal(tools.filter(tool => tool.outputSchema).length, 21, "Object tools must advertise output schemas");
   for (const tool of tools) assert.equal(typeof tool.annotations?.readOnlyHint, 'boolean', `Missing annotation: ${tool.name}`);
   console.log(`Installed ${pkg.name}@${pkg.version}: ${packed.files.length} files, both bins load, handshake version agrees, all ${tools.length} tools present.`);
 } finally {