@jant/core 0.6.16 → 0.7.0

package/src/routes/api/__tests__/settings.test.ts

@@ -38,9 +38,9 @@ describe("Settings API Routes", () => {
       expect(body.settings.SITE_NAME).toBe("Jant");
       expect(body.settings.SITE_DESCRIPTION).toBe("");
       expect(body.settings.SITE_LANGUAGE).toBe("en");
-      expect(body.settings.PAGE_SIZE).toBe("50");
-      expect(body.settings.SEARCH_PAGE_SIZE).toBe("50");
-      expect(body.settings.ARCHIVE_PAGE_SIZE).toBe("50");
+      expect(body.settings.PAGE_SIZE).toBe("25");
+      expect(body.settings.SEARCH_PAGE_SIZE).toBe("25");
+      expect(body.settings.ARCHIVE_PAGE_SIZE).toBe("25");
       expect(body.settings.RSS_PUBLISH_DELAY_SECONDS).toBe("0");
     });
 
@@ -199,6 +199,27 @@ describe("Settings API Routes", () => {
       expect(body.details.rejectedKeys).toContain("AUTH_SECRET");
     });
 
+    it("rejects the multilingual keys, which only the language page may write", async () => {
+      const { app } = createTestApp({ authenticated: true });
+      app.route("/api/settings", settingsApiRoutes);
+
+      const res = await app.request("/api/settings", {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          MULTILINGUAL_ENABLED: "true",
+          ADDITIONAL_LANGUAGES: "en",
+        }),
+      });
+
+      // Writing these directly would skip the confirmation that stamps
+      // existing posts and the URL-prefix conflict check.
+      expect(res.status).toBe(400);
+      const body = await res.json();
+      expect(body.details.rejectedKeys).toContain("MULTILINGUAL_ENABLED");
+      expect(body.details.rejectedKeys).toContain("ADDITIONAL_LANGUAGES");
+    });
+
     it("rejects internal keys", async () => {
       const { app } = createTestApp({ authenticated: true });
       app.route("/api/settings", settingsApiRoutes);

package/src/routes/api/__tests__/telegram.test.ts

@@ -3,6 +3,7 @@ import { createTestApp } from "../../../__tests__/helpers/app.js";
 import { DEFAULT_TEST_SITE_ID } from "../../../__tests__/helpers/db.js";
 import { telegramWebhookRoutes } from "../telegram.js";
 import type { StorageDriver } from "../../../lib/storage.js";
+import type { DeferredPendingEnv } from "../../../lib/deferred.js";
 
 const BOT_ID = "111111";
 const BOT_TOKEN = `${BOT_ID}:AA-test-token`;
@@ -117,13 +118,13 @@ function setup(
 
   // The webhook ACKs Telegram immediately and runs the album flush in
   // detached promises so subsequent webhooks on the same chat aren't
-  // serialized behind it. Tests have no `executionCtx.waitUntil`, so the
-  // route falls back to writing each promise into `env.__telegramPending`
-  // — collect them here so tests can await the flush before asserting.
+  // serialized behind it. Tests have no `executionCtx.waitUntil`, so
+  // `runDeferred` falls back to writing each promise into
+  // `env.__pendingDeferred` — collect them here so tests can await the flush
+  // before asserting.
   const pending: Promise<unknown>[] = [];
   ctx.app.use("/api/telegram/*", async (c, next) => {
-    (c.env as { __telegramPending?: Promise<unknown>[] }).__telegramPending =
-      pending;
+    (c.env as DeferredPendingEnv).__pendingDeferred = pending;
     return next();
   });
   ctx.app.route("/api/telegram", telegramWebhookRoutes);

package/src/routes/api/collections.ts

@@ -9,9 +9,11 @@ import type { AppVariables } from "../../types/app-context.js";
 import { requireAuthApi } from "../../middleware/auth.js";
 import { requirePublicApiAccess } from "../../middleware/public-content-access.js";
 import {
-  CollectionDirectoryItemIdSchema,
+  CollectionDirectoryRowIdSchema,
   CollectionDescriptionValueSchema,
+  CollectionIdSchema,
   CollectionSortOrderSchema,
+  ContentLanguageSchema,
   CreateCollectionDirectoryItemSchema,
   CreateCollectionSchema,
   PostIdSchema,
@@ -36,12 +38,24 @@ const ThreadAssignSchema = z.object({
 });
 
 const MoveSchema = z.object({
-  after: CollectionDirectoryItemIdSchema.nullable().optional(),
-  before: CollectionDirectoryItemIdSchema.nullable().optional(),
+  after: CollectionDirectoryRowIdSchema.nullable().optional(),
+  before: CollectionDirectoryRowIdSchema.nullable().optional(),
+});
+
+const SlugQuerySchema = z.object({
+  mode: z.literal("check"),
+  slug: z.string().trim().toLowerCase().min(1).max(200),
+  collectionId: CollectionIdSchema.optional(),
 });
 
 const ListCollectionsQuerySchema = z.object({
   view: z.enum(["compose"]).optional(),
+  /**
+   * Content language of the calling view. The directory's Thread counts are
+   * narrowed by it, so the page and this endpoint have to be asked the same
+   * question — see `jant-collection-directory`.
+   */
+  lang: ContentLanguageSchema.optional(),
 });
 
 // List collections (includes Thread counts and directory items)
@@ -50,6 +64,11 @@ collectionsApiRoutes.get("/", requirePublicApiAccess(), async (c) => {
 
   if (query.view === "compose") {
     c.header("Cache-Control", "no-store");
+    // Smart collections are deliberately absent. A post cannot be added to one
+    // by hand — its conditions decide, permanently — so offering it here would
+    // be a control that does nothing. Every "add this post to a collection"
+    // surface leaves them out for the same reason; see the smart collections
+    // design notes on the asymmetry, which is not a gap to be filled in later.
     const collections = await c.var.services.collections.listByRecentActivity();
     return c.json({
       collections,
@@ -57,10 +76,14 @@ collectionsApiRoutes.get("/", requirePublicApiAccess(), async (c) => {
     });
   }
 
-  const directoryData = await c.var.services.collections.listDirectoryData();
+  const directoryData = await c.var.services.collections.listDirectoryData({
+    isAuthenticated: c.var.isAuthenticated,
+    lang: query.lang,
+  });
 
   return c.json({
     collections: directoryData.collections,
+    smartCollections: directoryData.smartCollections,
     directoryItems: directoryData.directoryItems,
   });
 });
@@ -98,13 +121,17 @@ collectionsApiRoutes.put(
 );
 
 // Move directory item — must be before /:id
+//
+// The moved row and its neighbours may each be named by a collection or smart
+// collection id: those are the rows the directory renders without one of its
+// own. The service places them before it moves anything.
 collectionsApiRoutes.put(
   "/directory-items/:id/move",
   requireAuthApi(),
   async (c) => {
-    const id = parseIdParam(
+    const id = parseValidated(
+      CollectionDirectoryRowIdSchema,
       c.req.param("id"),
-      ID_PREFIX.collectionDirectoryItem,
     );
     const body = parseValidated(MoveSchema, await c.req.json());
 
@@ -135,6 +162,22 @@ collectionsApiRoutes.delete(
   },
 );
 
+/**
+ * Address availability, in the shape smart collections already use.
+ *
+ * Declared before `/:id` so the literal path wins. The editing dialog asks
+ * while the author types, so a clash is answered where the decision is being
+ * made rather than on write.
+ */
+collectionsApiRoutes.get("/slug", requireAuthApi(), async (c) => {
+  const query = parseValidated(SlugQuerySchema, c.req.query());
+  const available = await c.var.services.collections.checkSlugAvailability(
+    query.slug,
+    query.collectionId,
+  );
+  return c.json({ slug: query.slug, available });
+});
+
 // Get single collection
 collectionsApiRoutes.get("/:id", requirePublicApiAccess(), async (c) => {
   const id = parseIdParam(c.req.param("id"), ID_PREFIX.collection);

package/src/routes/api/custom-urls.ts

@@ -63,7 +63,6 @@ customUrlsApiRoutes.post("/", requireAuthApi(), async (c) => {
     targetId,
     toPath: body.toPath,
     redirectType,
-    archiveQuery: body.archiveQuery,
   });
 
   return c.json(customUrl, 201);

package/src/routes/api/discover.ts

@@ -0,0 +1,95 @@
+/**
+ * Discover API Routes
+ *
+ * The one address a Discover directory calls besides the feeds it polls.
+ * `GET /api/discover/posts` says, for each post ID it names, whether the post
+ * is in this site's Latest feed and whether its Thread is in the featured
+ * feed. The feed cannot say this about a post pushed past its length, and the
+ * permalink cannot say it about a post hidden from Latest or unfeatured, which
+ * is still a live page — so the directory asks instead of guessing.
+ *
+ * Specified in `docs/feeds.md`. A directory never builds the address: every
+ * feed names it in `<jant:discover status="…">`.
+ */
+
+import { Hono } from "hono";
+import { z } from "zod";
+import type { Bindings } from "../../types.js";
+import type { AppVariables } from "../../types/app-context.js";
+import { DISCOVER_STATUS_MAX_IDS } from "../../lib/discover.js";
+import {
+  featuredFeedSelection,
+  getRssPublishedBefore,
+  latestFeedSelection,
+} from "../../lib/feed-policy.js";
+import { createTypeIdSchema, ID_PREFIX } from "../../lib/ids.js";
+import { ContentLanguageSchema, parseValidated } from "../../lib/schemas.js";
+
+type Env = { Bindings: Bindings; Variables: AppVariables };
+
+export const discoverApiRoutes = new Hono<Env>();
+
+const PostStatusQuerySchema = z.object({
+  id: z
+    .array(createTypeIdSchema(ID_PREFIX.post))
+    .min(1, "Name at least one post with id=")
+    .max(
+      DISCOVER_STATUS_MAX_IDS,
+      `Ask about at most ${DISCOVER_STATUS_MAX_IDS} posts at a time`,
+    ),
+  /** The language view the answer is about, as a language feed is scoped. */
+  lang: ContentLanguageSchema.optional(),
+});
+
+/** Where one post stands in the feeds a directory reads. */
+export interface DiscoverPostStatus {
+  id: string;
+  /** In the Latest feed. */
+  latest: boolean;
+  /** Its Thread is in the featured feed. */
+  featured: boolean;
+}
+
+discoverApiRoutes.get("/posts", async (c) => {
+  // It answers for a site that takes part, and follows the Discover setting
+  // rather than `PUBLIC_API_ENABLED`: it says nothing the public feeds do not,
+  // and a site that turned its JSON API off has not left Discover.
+  if (c.var.appConfig.discover === "none") return c.notFound();
+
+  const query = parseValidated(PostStatusQuerySchema, {
+    id: c.req.queries("id") ?? [],
+    lang: c.req.query("lang"),
+  });
+  const ids = [...new Set(query.id)];
+  // The feeds hold a new post back for the RSS delay, and so does this: the
+  // answer is about the feeds as a reader would fetch them now.
+  const publishedBefore = getRssPublishedBefore(
+    c.var.appConfig.rssPublishDelaySeconds,
+  );
+
+  const [latest, featured] = await Promise.all([
+    c.var.services.posts.list({
+      ...latestFeedSelection({ lang: query.lang, publishedBefore }),
+      ids,
+      limit: ids.length,
+    }),
+    c.var.services.posts.listFeaturedThreadRootIds({
+      ...featuredFeedSelection({ lang: query.lang, publishedBefore }),
+      threadIds: ids,
+      limit: ids.length,
+    }),
+  ]);
+  const inLatest = new Set(latest.map((post) => post.id));
+  const inFeatured = new Set(featured);
+
+  // Every ID asked about is answered, in the order asked. A post that is
+  // deleted, private, a draft, a reply, or not this site's at all comes back
+  // `false` on both: to a directory they all mean the same thing.
+  return c.json({
+    posts: ids.map((id): DiscoverPostStatus => ({
+      id,
+      latest: inLatest.has(id),
+      featured: inFeatured.has(id),
+    })),
+  });
+});

package/src/routes/api/export.ts

@@ -23,10 +23,13 @@ exportApiRoutes.post("/hugo", requireAuthApi(), async (c) => {
       siteUrl: appConfig.siteUrl,
       siteDescription: appConfig.siteDescription,
       siteLanguage: appConfig.siteLanguage,
+      multilingualEnabled: appConfig.multilingualEnabled,
+      additionalLanguages: appConfig.additionalLanguages,
       showJantBrandingOnHome: appConfig.showJantBrandingOnHome,
       publicApiEnabled: appConfig.publicApiEnabled,
       rssFeedsEnabled: appConfig.rssFeedsEnabled,
       mainRssFeed: appConfig.mainRssFeed,
+      archiveDefaultLayout: appConfig.archiveDefaultLayout,
       siteFooter: appConfig.siteFooter,
       showHeaderAvatar: appConfig.showHeaderAvatar,
       siteAvatarUrl: appConfig.siteAvatarUrl,

package/src/routes/api/internal/__tests__/sites.test.ts

@@ -94,8 +94,10 @@ describe("Internal site admin routes", () => {
 
     expect(siteRows).toEqual([{ key: "demo-cloud" }]);
     expect(domainRows).toEqual([{ host: "demo-cloud.example.com" }]);
+    // Provisioned, not completed: the site is real and servable, but its
+    // owner has not yet confirmed the language they write in.
     expect(settingRows).toEqual([
-      { key: "ONBOARDING_STATUS", value: "completed" },
+      { key: "ONBOARDING_STATUS", value: "provisioned" },
       { key: "SITE_LANGUAGE", value: "en" },
       { key: "SITE_NAME", value: "Demo Cloud" },
     ]);
@@ -136,7 +138,7 @@ describe("Internal site admin routes", () => {
       .all(body.siteId) as { key: string; value: string }[];
 
     expect(settingRows).toEqual([
-      { key: "ONBOARDING_STATUS", value: "completed" },
+      { key: "ONBOARDING_STATUS", value: "provisioned" },
       { key: "SITE_LANGUAGE", value: "en" },
       { key: "SITE_NAME", value: "Locale Demo" },
       { key: "TIME_ZONE", value: "Etc/GMT-8" },
@@ -405,6 +407,28 @@ describe("Internal site admin routes", () => {
          VALUES (?, 'SITE_AVATAR', 'sites/${siteId}/avatar.webp', 1774200003)`,
       )
       .run(siteId);
+    // A smart collection filtering by a collection on the same site. The pair
+    // is the shape this endpoint used to die on: the condition column once
+    // carried `ON DELETE restrict`, so clearing `collection` threw partway
+    // through a delete that runs without a transaction on SQLite and D1.
+    sqlite
+      .prepare(
+        `INSERT INTO "collection" ("id", "site_id", "title", "sort_order", "created_at", "updated_at")
+         VALUES ('col_delete_1', ?, 'Notes', 'newest', 1774200004, 1774200004)`,
+      )
+      .run(siteId);
+    sqlite
+      .prepare(
+        `INSERT INTO "smart_collection" ("id", "site_id", "title", "collection_id", "format", "sort", "created_at", "updated_at")
+         VALUES ('smc_delete_1', ?, 'Untitled notes', 'col_delete_1', 'note', 'newest', 1774200005, 1774200005)`,
+      )
+      .run(siteId);
+    sqlite
+      .prepare(
+        `INSERT INTO "path_registry" ("id", "site_id", "path", "kind", "smart_collection_id", "created_at", "updated_at")
+         VALUES ('pth_delete_1', ?, 'untitled-notes', 'slug', 'smc_delete_1', 1774200006, 1774200006)`,
+      )
+      .run(siteId);
 
     const deleteRes = await app.request(`/api/internal/sites/${siteId}`, {
       method: "DELETE",
@@ -436,6 +460,19 @@ describe("Internal site admin routes", () => {
         'SELECT COUNT(*) AS count FROM "site_setting" WHERE "site_id" = ?',
       )
       .get(siteId) as { count: number };
+    const deletedCollectionCount = sqlite
+      .prepare('SELECT COUNT(*) AS count FROM "collection" WHERE "site_id" = ?')
+      .get(siteId) as { count: number };
+    const deletedSmartCollectionCount = sqlite
+      .prepare(
+        'SELECT COUNT(*) AS count FROM "smart_collection" WHERE "site_id" = ?',
+      )
+      .get(siteId) as { count: number };
+    const deletedPathCount = sqlite
+      .prepare(
+        'SELECT COUNT(*) AS count FROM "path_registry" WHERE "site_id" = ?',
+      )
+      .get(siteId) as { count: number };
     const defaultSiteCount = sqlite
       .prepare('SELECT COUNT(*) AS count FROM "site" WHERE "id" = ?')
       .get(DEFAULT_TEST_SITE_ID) as { count: number };
@@ -445,6 +482,9 @@ describe("Internal site admin routes", () => {
     expect(deletedMemberCount.count).toBe(0);
     expect(deletedPostCount.count).toBe(0);
     expect(deletedSettingsCount.count).toBe(0);
+    expect(deletedCollectionCount.count).toBe(0);
+    expect(deletedSmartCollectionCount.count).toBe(0);
+    expect(deletedPathCount.count).toBe(0);
     expect(defaultSiteCount.count).toBe(1);
   });
 

package/src/routes/api/nav-items.ts

@@ -16,8 +16,9 @@ import {
   parseValidated,
 } from "../../lib/schemas.js";
 import { assertFound, parseIdParam, NotFoundError } from "../../lib/errors.js";
+import { AddressQuerySchema, requestInternalPath } from "../../lib/address.js";
+import { toPublicPath } from "../../lib/url.js";
 import { ID_PREFIX } from "../../lib/ids.js";
-import { getCollectionPagePath } from "../../lib/collection-paths.js";
 import { renderSiteHeaderHtml } from "../../lib/site-header-fragment.js";
 
 type Env = { Bindings: Bindings; Variables: AppVariables };
@@ -69,6 +70,51 @@ navItemsApiRoutes.get("/pages", requireAuthApi(), async (c) => {
   return c.json({ pages });
 });
 
+/**
+ * What a pasted address could become in navigation.
+ *
+ * The author is holding a URL, not a title, so searching titles cannot answer
+ * them. The rules stay in the service; this only says which address was asked
+ * about, so the picker can name it back.
+ */
+navItemsApiRoutes.get("/resolve", requireAuthApi(), async (c) => {
+  const { url } = parseValidated(AddressQuerySchema, c.req.query());
+  const path = requestInternalPath(c, url);
+  if (path === null) {
+    return c.json({ resolution: { kind: "external", address: url.trim() } });
+  }
+
+  const resolution = await c.var.services.navItems.resolveNavTarget(path);
+  const address = toPublicPath(path, c.var.appConfig.sitePathPrefix);
+
+  if (resolution.status === "page") {
+    return c.json({
+      resolution: { kind: "page", address, page: resolution.page },
+    });
+  }
+  if (resolution.status === "collection") {
+    return c.json({
+      resolution: {
+        kind: "collection",
+        address,
+        collection: resolution.collection,
+      },
+    });
+  }
+
+  if (resolution.status === "smart_collection") {
+    return c.json({
+      resolution: {
+        kind: "smart_collection",
+        address,
+        smartCollection: resolution.smartCollection,
+      },
+    });
+  }
+
+  return c.json({ resolution: { kind: resolution.status, address } });
+});
+
 // Move nav item (requires auth) — must be before /:id
 navItemsApiRoutes.put("/:id/move", requireAuthApi(), async (c) => {
   const id = parseIdParam(c.req.param("id"), ID_PREFIX.navItem);
@@ -98,16 +144,17 @@ navItemsApiRoutes.post("/", requireAuthApi(), async (c) => {
       placement: body.placement,
     });
   } else if (body.type === "collection") {
-    const collection = await c.var.services.collections.getById(
-      body.collectionId,
-    );
-    if (!collection) throw new NotFoundError("Collection");
-
     item = await c.var.services.navItems.create({
       type: "collection",
       collectionId: body.collectionId,
-      label: body.label || collection.title,
-      url: getCollectionPagePath(collection.slug),
+      label: body.label,
+      placement: body.placement,
+    });
+  } else if (body.type === "smart_collection") {
+    item = await c.var.services.navItems.create({
+      type: "smart_collection",
+      smartCollectionId: body.smartCollectionId,
+      label: body.label,
       placement: body.placement,
     });
   } else if (body.type === "page") {

package/src/routes/api/posts.ts

@@ -7,6 +7,7 @@ import type { Bindings } from "../../types.js";
 import type { AppVariables } from "../../types/app-context.js";
 import { z } from "zod";
 import {
+  ContentLanguageSchema,
   CreatePostApiSchema,
   UpdatePostApiSchema,
   FormatSchema,
@@ -16,7 +17,10 @@ import {
 } from "../../lib/schemas.js";
 import { requireAuthApi } from "../../middleware/auth.js";
 import { toApiAttachment, toApiPost } from "../../lib/api-posts.js";
+import { getPostDisplayTitle } from "../../lib/post-meta.js";
 import { assertFound, NotFoundError, parseIdParam } from "../../lib/errors.js";
+import { AddressQuerySchema, requestInternalPath } from "../../lib/address.js";
+import { toPublicPath } from "../../lib/url.js";
 import { ID_PREFIX } from "../../lib/ids.js";
 import { triggerGitHubSyncInline } from "../../lib/github-sync-trigger.js";
 
@@ -196,6 +200,8 @@ postsApiRoutes.post("/", requireAuthApi(), async (c) => {
       collectionEntries: body.collectionEntries,
       replyToId: body.replyToId,
       quietReply: body.quietReply,
+      language: body.language,
+      translationOfId: body.translationOfId,
       publishedAt: body.publishedAt,
     },
     body.attachments,
@@ -269,6 +275,7 @@ postsApiRoutes.put("/:id", requireAuthApi(), async (c) => {
         collectionIds: body.collectionIds,
         collectionEntries: body.collectionEntries,
         publishedAt: body.publishedAt,
+        language: body.language,
       },
       body.attachments,
       {
@@ -313,6 +320,158 @@ postsApiRoutes.put("/:id", requireAuthApi(), async (c) => {
   );
 });
 
+// =============================================================================
+// Language and translations
+// =============================================================================
+
+const SetLanguageSchema = z.object({ language: ContentLanguageSchema });
+const TranslationCandidatesQuerySchema = z.object({
+  q: z.string().trim().min(1).max(200),
+  limit: z.coerce.number().int().min(1).max(20).optional().default(8),
+});
+const LinkTranslationSchema = z.object({ postId: PostIdSchema });
+
+/**
+ * Set the content language of a whole Thread.
+ *
+ * Thread-wide because `post.language` is uniform inside a Thread — see the
+ * service method for why every language filter depends on that.
+ */
+postsApiRoutes.put("/:id/language", requireAuthApi(), async (c) => {
+  const id = parseIdParam(c.req.param("id"), ID_PREFIX.post);
+  const { language } = parseValidated(SetLanguageSchema, await c.req.json());
+
+  await c.var.services.posts.setThreadLanguage(id, language);
+  await triggerGitHubSyncInline(c);
+
+  return c.json({ success: true, language });
+});
+
+/** List the Thread roots this post is a translation of. */
+postsApiRoutes.get("/:id/translations", requireAuthApi(), async (c) => {
+  const id = parseIdParam(c.req.param("id"), ID_PREFIX.post);
+  const post = assertFound(await c.var.services.posts.getById(id), "Post");
+  const translations = await c.var.services.posts.listTranslations(
+    post.threadId,
+  );
+
+  return c.json({
+    translations: translations.map((translation) => ({
+      id: translation.id,
+      slug: translation.slug,
+      title: translation.title,
+      // What to show in a list: notes are usually untitled, and a slug is not
+      // a name.
+      label: getPostDisplayTitle(translation) || translation.slug,
+      language: translation.language,
+    })),
+  });
+});
+
+/**
+ * Posts this one could be linked to as a translation.
+ *
+ * The eligibility rules live in the service; the menu only renders what comes
+ * back, so it never offers a post the link would refuse.
+ */
+postsApiRoutes.get(
+  "/:id/translations/candidates",
+  requireAuthApi(),
+  async (c) => {
+    const id = parseIdParam(c.req.param("id"), ID_PREFIX.post);
+    const { q, limit } = parseValidated(
+      TranslationCandidatesQuerySchema,
+      c.req.query(),
+    );
+
+    const candidates = await c.var.services.posts.listTranslationCandidates(
+      id,
+      {
+        query: q,
+        limit,
+      },
+    );
+
+    return c.json({
+      candidates: candidates.map((post) => ({
+        id: post.id,
+        slug: post.slug,
+        title: post.title,
+        label: getPostDisplayTitle(post) || post.slug,
+        language: post.language,
+      })),
+    });
+  },
+);
+
+/**
+ * The Thread a pasted address names, and whether it can be linked to this one.
+ *
+ * Separate from the candidate search so a URL never quietly becomes search
+ * words: this endpoint only ever answers about one address, and answers with a
+ * reason when the Thread it names is not eligible.
+ */
+postsApiRoutes.get("/:id/translations/resolve", requireAuthApi(), async (c) => {
+  const id = parseIdParam(c.req.param("id"), ID_PREFIX.post);
+  const { url } = parseValidated(AddressQuerySchema, c.req.query());
+
+  const path = requestInternalPath(c, url);
+  if (path === null) {
+    return c.json({ resolution: { kind: "external", address: url.trim() } });
+  }
+
+  const resolution = await c.var.services.posts.resolveTranslationCandidate(
+    id,
+    path,
+  );
+  const address = toPublicPath(path, c.var.appConfig.sitePathPrefix);
+
+  if (resolution.status === "ok") {
+    const post = resolution.post;
+    return c.json({
+      resolution: {
+        kind: "ok",
+        address,
+        candidate: {
+          id: post.id,
+          slug: post.slug,
+          label: getPostDisplayTitle(post) || post.slug,
+          language: post.language,
+        },
+      },
+    });
+  }
+
+  return c.json({
+    resolution: {
+      kind: resolution.status,
+      address,
+      ...("language" in resolution ? { language: resolution.language } : {}),
+    },
+  });
+});
+
+/** Link two already-published Threads as translations of each other. */
+postsApiRoutes.post("/:id/translations", requireAuthApi(), async (c) => {
+  const id = parseIdParam(c.req.param("id"), ID_PREFIX.post);
+  const { postId } = parseValidated(LinkTranslationSchema, await c.req.json());
+
+  await c.var.services.posts.linkTranslation(id, postId);
+  await triggerGitHubSyncInline(c);
+
+  return c.json({ success: true });
+});
+
+/** Take this Thread out of its translation group. */
+postsApiRoutes.delete("/:id/translations", requireAuthApi(), async (c) => {
+  const id = parseIdParam(c.req.param("id"), ID_PREFIX.post);
+
+  await c.var.services.posts.unlinkTranslation(id);
+  await triggerGitHubSyncInline(c);
+
+  return c.json({ success: true });
+});
+
 // Delete post (requires auth)
 postsApiRoutes.delete("/:id", requireAuthApi(), async (c) => {
   const id = parseIdParam(c.req.param("id"), ID_PREFIX.post);