@jant/core 0.8.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/dist/{app--uxnaIRV.js → app-BzH8jmh3.js} +1199 -262
  2. package/dist/client/.vite/manifest.json +2 -2
  3. package/dist/client/_assets/{client-BT6kpcuG.js → client-S8oryJ0m.js} +1 -1
  4. package/dist/client/_assets/{client-auth-begiT1tq.js → client-auth-Ds9G0IgR.js} +1 -1
  5. package/dist/index.js +1 -1
  6. package/dist/node.js +2 -2
  7. package/package.json +1 -1
  8. package/src/__tests__/helpers/cursor-walk.ts +37 -7
  9. package/src/app.tsx +4 -0
  10. package/src/lib/__tests__/thread-fold.test.ts +43 -0
  11. package/src/lib/api-posts.ts +110 -2
  12. package/src/lib/api-public-posts.ts +263 -0
  13. package/src/lib/api-threads.ts +207 -0
  14. package/src/lib/thread-fold.ts +83 -41
  15. package/src/lib/thread-query.ts +143 -0
  16. package/src/middleware/cors.ts +8 -1
  17. package/src/middleware/deprecation.ts +48 -0
  18. package/src/routes/api/__tests__/mcp.test.ts +89 -0
  19. package/src/routes/api/__tests__/posts.test.ts +78 -0
  20. package/src/routes/api/__tests__/public-access.test.ts +5 -0
  21. package/src/routes/api/__tests__/threads.test.ts +115 -0
  22. package/src/routes/api/posts.ts +15 -104
  23. package/src/routes/api/public/__tests__/threads.test.ts +363 -0
  24. package/src/routes/api/public/archive.ts +82 -81
  25. package/src/routes/api/public/posts.ts +97 -298
  26. package/src/routes/api/public/threads.ts +141 -0
  27. package/src/routes/api/threads.ts +128 -0
  28. package/src/services/__tests__/thread.test.ts +495 -0
  29. package/src/services/index.ts +4 -0
  30. package/src/services/mcp.ts +208 -53
  31. package/src/services/post.ts +222 -43
  32. package/src/services/thread.ts +392 -0
  33. package/src/types/constants.ts +25 -0
  34. package/src/ui/feed/ThreadPreview.tsx +9 -14
  35. package/src/ui/feed/__tests__/thread-preview.test.ts +18 -22
  36. package/src/ui/feed/thread-preview-state.ts +0 -35
@@ -0,0 +1,207 @@
1
+ /**
2
+ * API Thread responses
3
+ *
4
+ * The Thread object the author API, the public API, and MCP return. One shape
5
+ * for all three, parameterized by how each surface renders a Post and how it
6
+ * names one: the author API's Post is the editing view, the public API's the
7
+ * reading view.
8
+ */
9
+
10
+ import type { ThreadSummary } from "../services/thread.js";
11
+ import type { Post } from "../types.js";
12
+ import {
13
+ loadApiPostResponses,
14
+ type ApiPostResponse,
15
+ type ApiPostResponseDeps,
16
+ } from "./api-posts.js";
17
+ import {
18
+ loadPublicPostResponses,
19
+ type PublicPostResponse,
20
+ } from "./api-public-posts.js";
21
+ import { toPublicPath } from "./url.js";
22
+
23
+ /**
24
+ * The homepage fold of one Thread: what it shows either side of the gap, and
25
+ * how much it hides. Which replies it keeps is the site's choice
26
+ * (`lib/thread-fold.ts`) and may change; `hidden` always says how many it left
27
+ * out, so a caller never has to work it out.
28
+ */
29
+ export interface ApiThreadFold<P, G> {
30
+ /** The earliest replies, as context. */
31
+ leading: P[];
32
+ /** How many replies the fold leaves out, between `leading` and `trailing`. */
33
+ hidden: number;
34
+ /** The first reply left out, where a link to the rest opens; null if none. */
35
+ gap: G | null;
36
+ /** The latest replies, oldest first; the newest reply is the last. */
37
+ trailing: P[];
38
+ }
39
+
40
+ /** One Thread, as a Thread list or lookup returns it. */
41
+ export interface ApiThreadResponse<P, G> {
42
+ /** The Thread's ID, which is its root Post's ID. */
43
+ id: string;
44
+ /** Published Posts in the Thread, the root included. */
45
+ postCount: number;
46
+ /** Newest post in the Thread, quiet replies excluded. */
47
+ lastActivityAt: number;
48
+ /** Newest post in the Thread, quiet replies included. */
49
+ threadUpdatedAt: number;
50
+ root: P;
51
+ /** Present when the request asked for it. */
52
+ fold?: ApiThreadFold<P, G>;
53
+ }
54
+
55
+ /** How the author API and MCP name a Post a fold leaves out. */
56
+ export interface ApiThreadGap {
57
+ id: string;
58
+ slug: string;
59
+ }
60
+
61
+ /** The author API's and MCP's Thread object. */
62
+ export type ApiAuthorThreadResponse = ApiThreadResponse<
63
+ ApiPostResponse,
64
+ ApiThreadGap
65
+ >;
66
+
67
+ /** How the public API names a Post a fold leaves out: with its address. */
68
+ export interface PublicThreadGap extends ApiThreadGap {
69
+ permalink: string;
70
+ }
71
+
72
+ /** The public API's Thread object. */
73
+ export type PublicThreadResponse = ApiThreadResponse<
74
+ PublicPostResponse,
75
+ PublicThreadGap
76
+ >;
77
+
78
+ /**
79
+ * Every Post a set of Thread responses renders, so their attachments and
80
+ * counts can be read in one batch: each root, then the replies its fold shows.
81
+ *
82
+ * @param summaries - Threads to respond with
83
+ * @returns The Posts, each once
84
+ * @example
85
+ * const responses = await render(collectThreadResponsePosts(summaries));
86
+ */
87
+ export function collectThreadResponsePosts(summaries: ThreadSummary[]): Post[] {
88
+ const seen = new Map<string, Post>();
89
+ for (const { root, fold } of summaries) {
90
+ seen.set(root.id, root);
91
+ if (!fold) continue;
92
+ for (const post of [
93
+ ...fold.leadingReplies,
94
+ ...fold.trailingReplies,
95
+ fold.latestReply,
96
+ ]) {
97
+ seen.set(post.id, post);
98
+ }
99
+ }
100
+ return [...seen.values()];
101
+ }
102
+
103
+ /**
104
+ * One Thread's response, from Post responses already rendered.
105
+ *
106
+ * @param summary - The Thread
107
+ * @param respond - The rendered response for a Post in it
108
+ * @param reference - How the surface names the Post a fold leaves out
109
+ * @returns The Thread object
110
+ * @example
111
+ * toApiThreadResponse(summary, (post) => byId.get(post.id)!, toGap);
112
+ */
113
+ export function toApiThreadResponse<P, G>(
114
+ summary: ThreadSummary,
115
+ respond: (post: Post) => P,
116
+ reference: (post: Post) => G,
117
+ ): ApiThreadResponse<P, G> {
118
+ const { root, fold } = summary;
119
+ const response: ApiThreadResponse<P, G> = {
120
+ id: root.id,
121
+ postCount: summary.postCount,
122
+ lastActivityAt: root.lastActivityAt,
123
+ threadUpdatedAt: root.threadUpdatedAt,
124
+ root: respond(root),
125
+ };
126
+ if (fold === null) {
127
+ response.fold = { leading: [], hidden: 0, gap: null, trailing: [] };
128
+ } else if (fold) {
129
+ response.fold = {
130
+ leading: fold.leadingReplies.map(respond),
131
+ hidden: fold.hiddenCount,
132
+ gap: fold.firstHiddenReply ? reference(fold.firstHiddenReply) : null,
133
+ trailing: [...fold.trailingReplies, fold.latestReply].map(respond),
134
+ };
135
+ }
136
+ return response;
137
+ }
138
+
139
+ /**
140
+ * The author API's and MCP's Thread objects for Threads already listed.
141
+ *
142
+ * @param deps - Services and app config
143
+ * @param summaries - Threads to respond with, in order
144
+ * @returns One Thread object per summary, in the same order
145
+ * @example
146
+ * const threads = await loadApiThreadResponses(c.var, page.threads);
147
+ */
148
+ export async function loadApiThreadResponses(
149
+ deps: ApiPostResponseDeps,
150
+ summaries: ThreadSummary[],
151
+ ): Promise<ApiAuthorThreadResponse[]> {
152
+ return buildThreadResponses(
153
+ summaries,
154
+ (posts) => loadApiPostResponses(deps, posts),
155
+ (post) => ({ id: post.id, slug: post.slug }),
156
+ );
157
+ }
158
+
159
+ /**
160
+ * The public API's Thread objects for Threads already listed.
161
+ *
162
+ * @param deps - Services and app config
163
+ * @param summaries - Threads to respond with, in order
164
+ * @param options - `content: "markdown"` returns `bodyMarkdown` on every Post
165
+ * @returns One Thread object per summary, in the same order
166
+ * @example
167
+ * const threads = await loadPublicThreadResponses(c.var, page.threads, {});
168
+ */
169
+ export async function loadPublicThreadResponses(
170
+ deps: ApiPostResponseDeps,
171
+ summaries: ThreadSummary[],
172
+ options: { content?: "markdown" } = {},
173
+ ): Promise<PublicThreadResponse[]> {
174
+ return buildThreadResponses(
175
+ summaries,
176
+ (posts) => loadPublicPostResponses(deps, posts, options),
177
+ (post) => ({
178
+ id: post.id,
179
+ slug: post.slug,
180
+ permalink: toPublicPath(`/${post.slug}`, deps.appConfig.sitePathPrefix),
181
+ }),
182
+ );
183
+ }
184
+
185
+ /** Render every Post the Threads show in one batch, then assemble them. */
186
+ async function buildThreadResponses<P, G>(
187
+ summaries: ThreadSummary[],
188
+ render: (posts: Post[]) => Promise<P[]>,
189
+ reference: (post: Post) => G,
190
+ ): Promise<ApiThreadResponse<P, G>[]> {
191
+ const posts = collectThreadResponsePosts(summaries);
192
+ const responses = await render(posts);
193
+ const byId = new Map(
194
+ posts.map((post, index) => [post.id, responses[index]] as const),
195
+ );
196
+ return summaries.map((summary) =>
197
+ toApiThreadResponse(
198
+ summary,
199
+ (post) => {
200
+ const response = byId.get(post.id);
201
+ if (!response) throw new Error(`No response built for post ${post.id}`);
202
+ return response;
203
+ },
204
+ reference,
205
+ ),
206
+ );
207
+ }
@@ -3,15 +3,17 @@
3
3
  *
4
4
  * How much of a thread the timeline shows, and how much it folds away.
5
5
  *
6
- * A thread appears in two places that cannot select its posts the same way.
7
- * The site paints a page of timeline items and must not load whole threads to
8
- * do it, so `getThreadTimelineContext` ranks replies in SQL and hands the
9
- * buckets down. The feed already holds every reply — `<content>` carries the
10
- * whole chain — so it slices the array it has. Two access paths, one rule.
6
+ * A thread is folded in three places that cannot all select its posts the same
7
+ * way. The site paints a page of timeline items and must not load whole
8
+ * threads to do it, so `getThreadTimelineContext` ranks replies in SQL and
9
+ * hands the windows down; the Threads API's `include=fold` reads the same
10
+ * windows. The feed already holds every reply — `<content>` carries the whole
11
+ * chain — so it slices the array it has. Two access paths, one rule.
11
12
  *
12
- * This module owns what they share: the thresholds, and the arithmetic that
13
- * turns a selection into a hidden count. Whoever changes the shape of the fold
14
- * changes it here, and both surfaces move together.
13
+ * This module owns what they share: the thresholds, how overlapping windows
14
+ * become the replies shown ({@link foldReplyWindows}), and the arithmetic that
15
+ * turns them into a hidden count. Whoever changes the shape of the fold changes
16
+ * it here, and every surface moves together.
15
17
  *
16
18
  * ## The fold
17
19
  *
@@ -101,6 +103,73 @@ export interface ThreadFold<T> {
101
103
  hiddenCount: number;
102
104
  }
103
105
 
106
+ /**
107
+ * Fold a thread from its ranked windows: the replies each end of the fold
108
+ * keeps, before any overlap between them is removed.
109
+ *
110
+ * Both access paths arrive here. The feed slices the windows out of the whole
111
+ * chain; the site and the API rank them in SQL (`getThreadTimelineContext`),
112
+ * which hands them over overlapping on purpose. A short thread's windows
113
+ * overlap, and the hero is inside both of them on the shortest ones: with a
114
+ * single reply, that reply is the newest *and* the whole leading window. Each
115
+ * list therefore drops whatever an earlier one already shows, hero first.
116
+ *
117
+ * @param buckets.leadingReplies - The first `THREAD_LEADING_REPLIES` replies
118
+ * @param buckets.trailingReplies - The replies just before the newest, oldest
119
+ * first
120
+ * @param buckets.latestReply - The newest reply
121
+ * @param buckets.nextReply - The reply right after the leading window, the
122
+ * only candidate for the gap; `null` when the thread has no such reply
123
+ * @param buckets.totalReplyCount - Every published reply in the thread
124
+ * @returns The fold
125
+ * @example
126
+ * foldReplyWindows({ leadingReplies: [r1, r2], trailingReplies: [r6, r7],
127
+ * latestReply: r8, nextReply: r3, totalReplyCount: 8 });
128
+ * // leading [r1, r2], trailing [r6, r7], latest r8, firstHidden r3, hidden 3
129
+ */
130
+ export function foldReplyWindows<T extends Identified>({
131
+ leadingReplies: leadingWindow,
132
+ trailingReplies: trailingWindow,
133
+ latestReply,
134
+ nextReply,
135
+ totalReplyCount,
136
+ }: {
137
+ leadingReplies: T[];
138
+ trailingReplies: T[];
139
+ latestReply: T;
140
+ nextReply: T | null;
141
+ totalReplyCount: number;
142
+ }): ThreadFold<T> {
143
+ const shown = new Set([latestReply.id]);
144
+ const keepUnshown = (replies: T[]) =>
145
+ replies.filter((reply) => {
146
+ if (shown.has(reply.id)) return false;
147
+ shown.add(reply.id);
148
+ return true;
149
+ });
150
+ const leadingReplies = keepUnshown(leadingWindow);
151
+ const trailingReplies = keepUnshown(trailingWindow);
152
+ const hiddenCount = getThreadHiddenCount({
153
+ leadingReplies,
154
+ trailingReplies,
155
+ latestReply,
156
+ totalReplyCount,
157
+ });
158
+
159
+ return {
160
+ leadingReplies,
161
+ trailingReplies,
162
+ latestReply,
163
+ // The reply after the leading window is hidden exactly when anything is:
164
+ // the trailing window starts at or before it otherwise.
165
+ firstHiddenReply:
166
+ hiddenCount > 0 && nextReply && !shown.has(nextReply.id)
167
+ ? nextReply
168
+ : null,
169
+ hiddenCount,
170
+ };
171
+ }
172
+
104
173
  /**
105
174
  * Fold a thread whose replies are already in hand.
106
175
  *
@@ -122,40 +191,13 @@ export function foldThreadReplies<T extends Identified>(
122
191
  const latestReply = replies.at(-1);
123
192
  if (!latestReply) return null;
124
193
 
125
- // A short thread's windows overlap, and the hero is inside both of them on
126
- // the shortest ones: with a single reply, that reply is the newest *and* the
127
- // whole leading window. Each list therefore drops whatever an earlier one
128
- // already shows, hero first — the same order `ThreadPreview` dedupes in when
129
- // it walks the buckets the SQL path hands it.
130
- const leadingReplies = replies
131
- .slice(0, THREAD_LEADING_REPLIES)
132
- .filter((reply) => reply.id !== latestReply.id);
133
-
134
- const leadingIds = new Set(leadingReplies.map((reply) => reply.id));
135
- const trailingReplies = replies
136
- .slice(-THREAD_TRAILING_REPLIES, -1)
137
- .filter(
138
- (reply) => reply.id !== latestReply.id && !leadingIds.has(reply.id),
139
- );
140
-
141
- const shown = new Set([
142
- ...leadingIds,
143
- ...trailingReplies.map((reply) => reply.id),
144
- latestReply.id,
145
- ]);
146
-
147
- return {
148
- leadingReplies,
149
- trailingReplies,
194
+ return foldReplyWindows({
195
+ leadingReplies: replies.slice(0, THREAD_LEADING_REPLIES),
196
+ trailingReplies: replies.slice(-THREAD_TRAILING_REPLIES, -1),
150
197
  latestReply,
151
198
  // In thread order, so the gap link lands on the earliest post it stands
152
199
  // for rather than somewhere in the middle of the run it hides.
153
- firstHiddenReply: replies.find((reply) => !shown.has(reply.id)) ?? null,
154
- hiddenCount: getThreadHiddenCount({
155
- leadingReplies,
156
- trailingReplies,
157
- latestReply,
158
- totalReplyCount: replies.length,
159
- }),
160
- };
200
+ nextReply: replies[THREAD_LEADING_REPLIES] ?? null,
201
+ totalReplyCount: replies.length,
202
+ });
161
203
  }
@@ -0,0 +1,143 @@
1
+ /**
2
+ * Thread list queries
3
+ *
4
+ * Reads the filter dimensions a Thread list takes — the archive's, from the
5
+ * same registry — out of an HTTP query string or MCP arguments, so the public
6
+ * API, the author API, and MCP accept one vocabulary.
7
+ *
8
+ * One word differs from the archive page. A Thread list left unfiltered shows
9
+ * what the homepage shows, so it needs a word for "every visibility a reader
10
+ * may see": `visibility=any`. The registry's `visibility=all` is an old
11
+ * spelling of leaving the parameter out, which here would mean the homepage's
12
+ * set — the opposite of what the word says — so a Thread list refuses it.
13
+ */
14
+
15
+ import type { ThreadAudience } from "../services/thread.js";
16
+ import type { Collection } from "../types.js";
17
+ import { ValidationError } from "./errors.js";
18
+ import {
19
+ buildCollectionVocabulary,
20
+ EMPTY_COLLECTION_VOCABULARY,
21
+ parsePostFilterSelectionStrict,
22
+ readCollectionSlugs,
23
+ type ParamReader,
24
+ type PostFilterSelection,
25
+ } from "./filter-dimensions.js";
26
+
27
+ /** What a Thread list's filter parameters asked for. */
28
+ export type ThreadSelectionParse =
29
+ | {
30
+ kind: "selection";
31
+ selection: PostFilterSelection;
32
+ /** `visibility=any`: include what the homepage hides. */
33
+ includeHidden: boolean;
34
+ }
35
+ /** A named collection doesn't exist, so nothing can match. */
36
+ | { kind: "empty" };
37
+
38
+ const READER_VISIBILITIES = ["public", "featured", "hidden", "any"] as const;
39
+ const AUTHOR_VISIBILITIES = [...READER_VISIBILITIES, "private"] as const;
40
+ /** Spellings the registry reads that stay valid here. */
41
+ const LEGACY_VISIBILITIES = ["latest_hidden"] as const;
42
+
43
+ function allowedVisibilities(audience: ThreadAudience): readonly string[] {
44
+ return audience === "reader" ? READER_VISIBILITIES : AUTHOR_VISIBILITIES;
45
+ }
46
+
47
+ /**
48
+ * Read a Thread list's filter dimensions.
49
+ *
50
+ * @param read - Reads one parameter; `undefined` when absent
51
+ * @param present - Every parameter name the request carries
52
+ * @param options.allow - The endpoint's own parameters, which aren't
53
+ * dimensions; anything else unknown is refused
54
+ * @param options.audience - A reader may not name `private`
55
+ * @param options.loadCollections - Loads the collection vocabulary, called only
56
+ * when a collection is named
57
+ * @returns The selection, or `empty` when a named collection doesn't exist
58
+ * @throws {ValidationError} On an unknown parameter or an unreadable value
59
+ * @example
60
+ * const parsed = await parseThreadSelection(read, Object.keys(query), {
61
+ * allow: ["cursor", "limit"],
62
+ * audience: "reader",
63
+ * loadCollections: () => services.collections.list(),
64
+ * });
65
+ */
66
+ export async function parseThreadSelection(
67
+ read: ParamReader,
68
+ present: readonly string[],
69
+ options: {
70
+ allow: readonly string[];
71
+ audience: ThreadAudience;
72
+ loadCollections: () => Promise<Collection[]>;
73
+ },
74
+ ): Promise<ThreadSelectionParse> {
75
+ const visibility = read("visibility");
76
+ if (visibility !== undefined) {
77
+ const allowed = allowedVisibilities(options.audience);
78
+ if (visibility === "all") {
79
+ throw new ValidationError(
80
+ "visibility=all isn't accepted here. Leave visibility out for what the homepage lists, or pass visibility=any for everything.",
81
+ );
82
+ }
83
+ if (
84
+ !allowed.includes(visibility) &&
85
+ !(LEGACY_VISIBILITIES as readonly string[]).includes(visibility)
86
+ ) {
87
+ throw new ValidationError(
88
+ `Invalid visibility value. Allowed: ${allowed.join(", ")}`,
89
+ );
90
+ }
91
+ }
92
+
93
+ const includeHidden = visibility === "any";
94
+ // `any` isn't a registry value: it widens the audience's default rather
95
+ // than filtering, so the registry reads the query as if it were absent.
96
+ const readDimension: ParamReader = (key) =>
97
+ key === "visibility" && includeHidden ? undefined : read(key);
98
+
99
+ // Resolving a slug costs a round trip, paid only when one is named.
100
+ const collections =
101
+ readCollectionSlugs(readDimension).length > 0
102
+ ? buildCollectionVocabulary(await options.loadCollections())
103
+ : EMPTY_COLLECTION_VOCABULARY;
104
+ const parsed = parsePostFilterSelectionStrict(
105
+ readDimension,
106
+ present,
107
+ { collections },
108
+ { allow: options.allow },
109
+ );
110
+
111
+ if (parsed.ok) {
112
+ return { kind: "selection", selection: parsed.selection, includeHidden };
113
+ }
114
+ // A collection that doesn't exist is answered with nothing rather than a
115
+ // rejection: the caller's words were understood, and the site simply holds
116
+ // no such collection.
117
+ if (parsed.issues.every((issue) => issue.param === "collection")) {
118
+ return { kind: "empty" };
119
+ }
120
+ throw new ValidationError(parsed.issues[0]?.message ?? "Validation failed");
121
+ }
122
+
123
+ /**
124
+ * Read `include`: a comma-separated list of extras to attach to each Thread.
125
+ *
126
+ * @param raw - The parameter's value, or `undefined`
127
+ * @returns Whether the fold was asked for
128
+ * @throws {ValidationError} On a value this endpoint doesn't offer
129
+ * @example
130
+ * parseThreadInclude("fold"); // { fold: true }
131
+ */
132
+ export function parseThreadInclude(raw: string | undefined): { fold: boolean } {
133
+ if (raw === undefined || raw === "") return { fold: false };
134
+ const values = raw.split(",").map((value) => value.trim());
135
+ for (const value of values) {
136
+ if (value !== "fold") {
137
+ throw new ValidationError(
138
+ `Invalid include value "${value}". Allowed: fold`,
139
+ );
140
+ }
141
+ }
142
+ return { fold: values.includes("fold") };
143
+ }
@@ -39,7 +39,14 @@ export function apiCors(): MiddlewareHandler<Env> {
39
39
  origin: origins,
40
40
  allowMethods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
41
41
  allowHeaders: ["Content-Type", "Authorization", "MCP-Protocol-Version"],
42
- exposeHeaders: ["Content-Type", "MCP-Protocol-Version"],
42
+ // `Deprecation` and `Link` are how a deprecated endpoint names its
43
+ // replacement; a browser client can't read either unless exposed.
44
+ exposeHeaders: [
45
+ "Content-Type",
46
+ "MCP-Protocol-Version",
47
+ "Deprecation",
48
+ "Link",
49
+ ],
43
50
  credentials: origins !== "*",
44
51
  maxAge: 86400,
45
52
  });
@@ -0,0 +1,48 @@
1
+ /**
2
+ * Deprecated API endpoints.
3
+ *
4
+ * A deprecated endpoint keeps answering exactly as before until the major
5
+ * release that removes it, and says so on every response, errors included:
6
+ * `Deprecation` (RFC 9745) carries when it was deprecated, and `Link` with
7
+ * `rel="successor-version"` names what replaces it. The docs and the release
8
+ * notes say the same thing in words.
9
+ */
10
+
11
+ import type { MiddlewareHandler } from "hono";
12
+ import type { Bindings } from "../types.js";
13
+ import type { AppVariables } from "../types/app-context.js";
14
+ import { toPublicPath } from "../lib/url.js";
15
+
16
+ type Env = { Bindings: Bindings; Variables: AppVariables };
17
+
18
+ /**
19
+ * When 0.9 deprecated the Thread lists that `/api/public/threads` replaces:
20
+ * the `GET /api/public/posts` list and `GET /api/public/archive`.
21
+ */
22
+ export const THREAD_LIST_DEPRECATED_AT = Date.UTC(2026, 8, 27) / 1000;
23
+
24
+ /**
25
+ * Mark every response of a route as deprecated.
26
+ *
27
+ * @param deprecatedAt - Unix seconds the endpoint was deprecated
28
+ * @param successor - The replacement, as a site path (the site path prefix is
29
+ * added)
30
+ * @returns Hono middleware that sets `Deprecation` and `Link`
31
+ * @example
32
+ * ```ts
33
+ * routes.get("/", deprecated(THREAD_LIST_DEPRECATED_AT, "/api/public/threads"), handler);
34
+ * ```
35
+ */
36
+ export function deprecated(
37
+ deprecatedAt: number,
38
+ successor: string,
39
+ ): MiddlewareHandler<Env> {
40
+ return async (c, next) => {
41
+ await next();
42
+ c.header("Deprecation", `@${deprecatedAt}`);
43
+ c.header(
44
+ "Link",
45
+ `<${toPublicPath(successor, c.var.appConfig.sitePathPrefix)}>; rel="successor-version"`,
46
+ );
47
+ };
48
+ }
@@ -144,6 +144,9 @@ describe("MCP API Routes", () => {
144
144
  );
145
145
 
146
146
  expect(toolNames).toContain("jant_posts_list");
147
+ expect(toolNames).toContain("jant_threads_list");
148
+ expect(toolNames).toContain("jant_threads_get");
149
+ expect(toolNames).toContain("jant_threads_list_posts");
147
150
  expect(toolNames).toContain("jant_collections_add_thread");
148
151
  expect(toolNames).toContain("jant_collections_remove_thread");
149
152
  expect(toolNames).toContain("jant_settings_update");
@@ -213,6 +216,92 @@ describe("MCP API Routes", () => {
213
216
  expect(await services.collections.getThreadIds(collection.id)).toEqual([]);
214
217
  });
215
218
 
219
+ it("reads Threads through tools/call", async () => {
220
+ const { app, services } = createTestApp({ authenticated: true });
221
+ app.route("/api/mcp", mcpApiRoutes);
222
+
223
+ const collection = await services.collections.create({
224
+ slug: "notes",
225
+ title: "Notes",
226
+ });
227
+ const root = await services.posts.create({
228
+ format: "note",
229
+ bodyMarkdown: "Root",
230
+ publishedAt: 1000,
231
+ collectionIds: [collection.id],
232
+ });
233
+ const replies = [];
234
+ let parent = root;
235
+ for (let i = 1; i <= 7; i++) {
236
+ parent = await services.posts.create({
237
+ format: "note",
238
+ bodyMarkdown: `Reply ${i}`,
239
+ replyToId: parent.id,
240
+ publishedAt: 1000 + i,
241
+ createdAt: 1000 + i,
242
+ });
243
+ replies.push(parent);
244
+ }
245
+ const other = await services.posts.create({
246
+ format: "note",
247
+ bodyMarkdown: "Elsewhere",
248
+ publishedAt: 500,
249
+ });
250
+
251
+ const call = async (name: string, args: Record<string, unknown>) => {
252
+ const res = await postMcp(
253
+ app,
254
+ {
255
+ jsonrpc: "2.0",
256
+ id: 40,
257
+ method: "tools/call",
258
+ params: { name, arguments: args },
259
+ },
260
+ { "MCP-Protocol-Version": "2025-06-18" },
261
+ );
262
+ expect(res.status).toBe(200);
263
+ const { result } = await res.json();
264
+ expect(result.isError).toBe(false);
265
+ return result.structuredContent;
266
+ };
267
+
268
+ const all = await call("jant_threads_list", { sort: "published" });
269
+ expect(all.threads.map((thread: { id: string }) => thread.id)).toEqual([
270
+ root.id,
271
+ other.id,
272
+ ]);
273
+ expect(all.threads[0].postCount).toBe(8);
274
+ expect(all.threads[0].fold).toBeUndefined();
275
+
276
+ const inCollection = await call("jant_threads_list", {
277
+ collection: "notes",
278
+ fold: true,
279
+ });
280
+ expect(inCollection.threads).toHaveLength(1);
281
+ expect(inCollection.threads[0].fold.hidden).toBe(2);
282
+ expect(inCollection.threads[0].fold.gap).toEqual({
283
+ id: replies[2]?.id,
284
+ slug: replies[2]?.slug,
285
+ });
286
+
287
+ const thread = await call("jant_threads_get", { id: replies[4]?.id });
288
+ expect(thread).toMatchObject({ id: root.id, postCount: 8 });
289
+
290
+ const walked: string[] = [];
291
+ let cursor: string | undefined;
292
+ for (let page = 0; page < 10; page++) {
293
+ const result = await call("jant_threads_list_posts", {
294
+ id: root.id,
295
+ limit: 3,
296
+ ...(cursor ? { cursor } : {}),
297
+ });
298
+ walked.push(...result.posts.map((post: { id: string }) => post.id));
299
+ cursor = result.nextCursor ?? undefined;
300
+ if (!cursor) break;
301
+ }
302
+ expect(walked).toEqual([root.id, ...replies.map((reply) => reply.id)]);
303
+ });
304
+
216
305
  it("pages posts through tools/call with nextCursor", async () => {
217
306
  const { app, services } = createTestApp({ authenticated: true });
218
307
  app.route("/api/mcp", mcpApiRoutes);