@jant/core 0.6.16 → 0.7.1

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,7 +200,11 @@ postsApiRoutes.post("/", requireAuthApi(), async (c) => {
       collectionEntries: body.collectionEntries,
       replyToId: body.replyToId,
       quietReply: body.quietReply,
+      language: body.language,
+      translationOfId: body.translationOfId,
       publishedAt: body.publishedAt,
+      createdAt: body.createdAt,
+      updatedAt: body.updatedAt,
     },
     body.attachments,
     {
@@ -269,6 +277,7 @@ postsApiRoutes.put("/:id", requireAuthApi(), async (c) => {
         collectionIds: body.collectionIds,
         collectionEntries: body.collectionEntries,
         publishedAt: body.publishedAt,
+        language: body.language,
       },
       body.attachments,
       {
@@ -313,6 +322,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);

package/src/routes/api/public/__tests__/archive.test.ts

@@ -52,6 +52,117 @@ describe("Public Archive API Routes", () => {
       expect(hidden.visibility).toBe("latest_hidden");
     });
 
+    it("answers the visibility question it was asked", async () => {
+      const { app, services } = createTestApp({ authenticated: false });
+      app.route("/api/public/archive", publicArchiveApiRoutes);
+
+      const plain = await services.posts.create({
+        format: "note",
+        title: "Plain root",
+        bodyMarkdown: "plain",
+      });
+      const hidden = await services.posts.create({
+        format: "note",
+        title: "Hidden root",
+        bodyMarkdown: "hidden",
+        visibility: "latest_hidden",
+      });
+      const featured = await services.posts.create({
+        format: "note",
+        title: "Featured root",
+        bodyMarkdown: "featured",
+        featured: true,
+      });
+
+      const hiddenOnly = await app.request(
+        "/api/public/archive?visibility=hidden",
+      );
+      expect(hiddenOnly.status).toBe(200);
+      const hiddenBody = await hiddenOnly.json();
+      expect(hiddenBody.posts.map((p: { id: string }) => p.id)).toEqual([
+        hidden.id,
+      ]);
+
+      const featuredOnly = await app.request(
+        "/api/public/archive?visibility=featured",
+      );
+      const featuredBody = await featuredOnly.json();
+      expect(featuredBody.posts.map((p: { id: string }) => p.id)).toEqual([
+        featured.id,
+      ]);
+
+      const publicOnly = await app.request(
+        "/api/public/archive?visibility=public",
+      );
+      const publicBody = await publicOnly.json();
+      const publicIds = publicBody.posts.map((p: { id: string }) => p.id);
+      expect(publicIds).toContain(plain.id);
+      expect(publicIds).not.toContain(hidden.id);
+    });
+
+    // The failure this guards: an unknown key is stripped by the schema, so a
+    // caller asking for something this endpoint cannot serve used to get the
+    // whole archive back and no way to tell.
+    it("rejects a visibility it cannot serve instead of widening", async () => {
+      const { app, services } = createTestApp({ authenticated: false });
+      app.route("/api/public/archive", publicArchiveApiRoutes);
+
+      await services.posts.create({
+        format: "note",
+        title: "Plain root",
+        bodyMarkdown: "plain",
+      });
+
+      for (const value of ["private", "nonsense"]) {
+        const res = await app.request(
+          `/api/public/archive?visibility=${value}`,
+        );
+        expect(res.status).toBe(400);
+      }
+    });
+
+    // `latest_hidden` is the stored spelling of `hidden`, which the page and
+    // the feed both read. This endpoint used to be the one surface that called
+    // it nonsense — a value it can serve perfectly, rejected only because it
+    // kept a private copy of the vocabulary.
+    it("reads the stored spelling of hidden, like every other surface", async () => {
+      const { app, services } = createTestApp({ authenticated: false });
+      app.route("/api/public/archive", publicArchiveApiRoutes);
+
+      await services.posts.create({
+        format: "note",
+        title: "Plain root",
+        bodyMarkdown: "plain",
+      });
+      const hidden = await services.posts.create({
+        format: "note",
+        title: "Hidden root",
+        bodyMarkdown: "hidden",
+        visibility: "latest_hidden",
+      });
+
+      const res = await app.request(
+        "/api/public/archive?visibility=latest_hidden",
+      );
+      expect(res.status).toBe(200);
+      const body = await res.json();
+      expect(body.posts.map((p: { id: string }) => p.id)).toEqual([hidden.id]);
+    });
+
+    it("rejects a parameter it does not know", async () => {
+      const { app, services } = createTestApp({ authenticated: false });
+      app.route("/api/public/archive", publicArchiveApiRoutes);
+
+      await services.posts.create({
+        format: "note",
+        title: "Plain root",
+        bodyMarkdown: "plain",
+      });
+
+      const res = await app.request("/api/public/archive?formta=note");
+      expect(res.status).toBe(400);
+    });
+
     it("supports format and limit filters with cursor", async () => {
       const { app, services } = createTestApp({ authenticated: false });
       app.route("/api/public/archive", publicArchiveApiRoutes);

package/src/routes/api/public/archive.ts

@@ -2,8 +2,17 @@ import { Hono } from "hono";
 import { z } from "zod";
 import type { Bindings } from "../../../types.js";
 import type { AppVariables } from "../../../types/app-context.js";
-import { MEDIA_KINDS } from "../../../types.js";
-import { FormatSchema, parseValidated } from "../../../lib/schemas.js";
+import { PUBLIC_ARCHIVE_VISIBILITIES } from "../../../types.js";
+import { ContentLanguageSchema, parseValidated } from "../../../lib/schemas.js";
+import type { DimensionContext } from "../../../lib/filter-dimensions.js";
+import {
+  buildCollectionVocabulary,
+  EMPTY_COLLECTION_VOCABULARY,
+  parsePostFilterSelectionStrict,
+  readCollectionSlugs,
+  toPostFilters,
+} from "../../../lib/filter-dimensions.js";
+import { ValidationError } from "../../../lib/errors.js";
 import { toPublicPost } from "./posts.js";
 import { requirePublicApiEnabled } from "../../../middleware/public-content-access.js";
 
@@ -13,104 +22,91 @@ export const publicArchiveApiRoutes = new Hono<Env>();
 
 publicArchiveApiRoutes.use("*", requirePublicApiEnabled());
 
-const MediaKindSchema = z.enum(MEDIA_KINDS);
-const MEDIA_KIND_LIST = MEDIA_KINDS.join(", ");
-const INVALID_MEDIA_MESSAGE =
-  "Invalid media value. Allowed: any, none, or kinds: " + MEDIA_KIND_LIST;
-
-const BoolFlagSchema = z.enum(["0", "1"]).transform((value) => value === "1");
-const PresenceSchema = z
-  .enum(["any", "none"])
-  .transform((value) => value === "any");
-
+/**
+ * The endpoint's own parameters — everything that is not a filter dimension.
+ *
+ * The dimensions themselves are read by the shared registry, so this endpoint
+ * cannot drift from the page it mirrors. They are listed here only so the strict
+ * parser can tell them apart from a parameter nobody understands.
+ */
 const ListPublicArchiveQuerySchema = z.object({
-  format: FormatSchema.optional(),
-  collection: z.string().optional(),
-  year: z.coerce.number().int().min(1971).optional(),
-  // Kinds list (image,video,...) or presence words: any = posts with any
-  // attachment, none = posts without attachments.
-  media: z
-    .string()
-    .optional()
-    .transform((value, ctx) => {
-      if (!value) return undefined;
-      if (value === "any" || value === "none") return value;
-      const parts = value
-        .split(",")
-        .map((part) => part.trim())
-        .filter((part) => part.length > 0);
-      if (parts.length === 0) return undefined;
-      const result = z.array(MediaKindSchema).safeParse(parts);
-      if (!result.success) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: INVALID_MEDIA_MESSAGE,
-        });
-        return z.NEVER;
-      }
-      return result.data;
-    }),
-  title: PresenceSchema.optional(),
-  replies: PresenceSchema.optional(),
-  // Deprecated: use media=any|none and title=any|none instead.
-  hasMedia: BoolFlagSchema.optional(),
-  hasTitle: BoolFlagSchema.optional(),
+  /** Restrict to one content language. See `/api/public/posts`. */
+  lang: ContentLanguageSchema.optional(),
   cursor: z.string().optional(),
   limit: z.coerce.number().int().min(1).max(100).optional().default(20),
   content: z.enum(["markdown"]).optional(),
 });
 
+const ENDPOINT_PARAMS = ["lang", "cursor", "limit", "content"] as const;
+
+const INVALID_VISIBILITY_MESSAGE =
+  "Invalid visibility value. Allowed: " +
+  PUBLIC_ARCHIVE_VISIBILITIES.map((value) =>
+    value === "latest_hidden" ? "hidden" : value,
+  ).join(", ");
+
 publicArchiveApiRoutes.get("/", async (c) => {
-  const {
-    format,
-    collection,
-    year,
-    media,
-    title,
-    replies,
-    hasMedia,
-    hasTitle,
-    cursor,
-    limit,
-    content,
-  } = parseValidated(ListPublicArchiveQuerySchema, c.req.query());
+  const { lang, cursor, limit, content } = parseValidated(
+    ListPublicArchiveQuerySchema,
+    c.req.query(),
+  );
 
-  const mediaKinds = Array.isArray(media) ? media : undefined;
-  const mediaPresence =
-    media === "any" ? true : media === "none" ? false : undefined;
+  const read = (key: string): string | undefined => c.req.query(key);
 
-  let collectionIds: string[] | undefined;
-  if (collection) {
-    // Accept both "tech,art" and "tech+art", matching the page URL convention.
-    const slugExpression = collection.replace(/,/g, "+");
-    const selection =
-      await c.var.services.collections.resolveSelection(slugExpression);
-    if (!selection || selection.collections.length === 0) {
-      return c.json({ posts: [], nextCursor: null });
-    }
-    collectionIds = selection.collections.map((col) => col.id);
+  // Resolving a collection slug costs a round trip, so it is paid for only when
+  // the caller named one.
+  const slugs = readCollectionSlugs(read);
+  const ctx: DimensionContext = {
+    collections:
+      slugs.length > 0
+        ? buildCollectionVocabulary(await c.var.services.collections.list())
+        : EMPTY_COLLECTION_VOCABULARY,
+  };
+
+  const parsed = parsePostFilterSelectionStrict(
+    read,
+    Object.keys(c.req.query()),
+    ctx,
+    { allow: ENDPOINT_PARAMS },
+  );
+
+  // A collection slug that names nothing is answered as an empty result rather
+  // than a rejection: the caller's words were understood, and this site simply
+  // holds no such collection.
+  if (
+    !parsed.ok &&
+    parsed.issues.every((issue) => issue.param === "collection")
+  ) {
+    return c.json({ posts: [], nextCursor: null });
+  }
+  if (!parsed.ok) {
+    const first = parsed.issues[0];
+    throw new ValidationError(first?.message ?? "Validation failed");
   }
 
-  const publishedAfter =
-    year !== undefined ? Date.UTC(year, 0, 1) / 1000 : undefined;
-  const publishedBefore =
-    year !== undefined ? Date.UTC(year + 1, 0, 1) / 1000 : undefined;
+  // `private` names a set no anonymous caller may see. Rejected rather than
+  // dropped: silently widening the result to the whole archive would answer a
+  // different question under the caller's own words.
+  const visibility = parsed.selection.visibility;
+  if (
+    visibility !== undefined &&
+    !(PUBLIC_ARCHIVE_VISIBILITIES as readonly string[]).includes(visibility)
+  ) {
+    throw new ValidationError(INVALID_VISIBILITY_MESSAGE);
+  }
 
   const posts = await c.var.services.posts.list({
-    format,
-    collectionIds,
+    lang,
     status: "published",
     cursor: cursor ?? undefined,
     limit,
     excludePrivate: true,
     excludeLatestHidden: false,
     excludeReplies: true,
-    publishedAfter,
-    publishedBefore,
-    mediaKinds,
-    hasMedia: mediaPresence ?? hasMedia,
-    hasTitle: title ?? hasTitle,
-    hasReplies: replies,
+    // Ordering is fixed at newest-published-first here, so the year filter
+    // stays on the publication axis — the page's `?sort=` switch has no
+    // counterpart on a cursor keyed off the post id.
+    ...toPostFilters(parsed.selection, { yearAxis: "published" }),
     ignorePinnedSort: true,
   });
 

package/src/routes/api/public/posts.ts

@@ -5,6 +5,7 @@ import type { AppVariables } from "../../../types/app-context.js";
 import { getCollectionPagePath } from "../../../lib/collection-paths.js";
 import {
   CollectionSortOrderSchema,
+  ContentLanguageSchema,
   FormatSchema,
   parseValidated,
 } from "../../../lib/schemas.js";
@@ -31,6 +32,11 @@ publicPostsApiRoutes.use("*", requirePublicApiEnabled());
 
 const ListPublicPostsQuerySchema = z.object({
   format: FormatSchema.optional(),
+  /**
+   * Restrict to one content language. Machine surfaces name the language
+   * explicitly; browsing surfaces express it as a URL prefix instead.
+   */
+  lang: ContentLanguageSchema.optional(),
   collection: z.string().optional(),
   sort: CollectionSortOrderSchema.optional(),
   cursor: z.string().optional(),
@@ -61,6 +67,16 @@ export type PublicPostBaseResponse = {
   previewImageUrl: string | null;
   replyToId: string | null;
   threadId: string;
+  /**
+   * BCP 47 content language, or null on a post written before the site
+   * enabled multilingual content.
+   */
+  language: string | null;
+  /**
+   * Shared by every translation of this Thread. Null when the Thread has no
+   * translations.
+   */
+  translationGroupId: string | null;
   /** Reply published without announcing its Thread. Always false on roots. */
   quietReply: boolean;
   pinnedAt: number | null;
@@ -91,8 +107,25 @@ export type PublicPostMarkdownResponse = PublicPostBaseResponse & {
 };
 
 export type PublicPostResponse =
-  | PublicPostRenderedResponse
-  | PublicPostMarkdownResponse;
+  PublicPostRenderedResponse | PublicPostMarkdownResponse;
+
+/**
+ * The public Markdown for a post, or null for a historical body that isn't
+ * TipTap JSON. One unreadable row answers null and is logged, rather than
+ * failing the whole listing; `bodyHtml` still falls back to stored HTML.
+ */
+function toPublicBodyMarkdown(postId: string, body: string): string | null {
+  try {
+    return tiptapJsonToMarkdown(body);
+  } catch (error) {
+    // eslint-disable-next-line no-console -- A skipped body must leave a trace
+    console.error(
+      `Couldn't convert the body of post ${postId} to Markdown`,
+      error,
+    );
+    return null;
+  }
+}
 
 function isPublicDetailVisible(post: Post | null): post is Post {
   return (
@@ -151,6 +184,8 @@ export function toPublicPost(
     previewImageUrl,
     replyToId: post.replyToId,
     threadId: post.threadId,
+    language: post.language,
+    translationGroupId: post.translationGroupId,
     quietReply: post.quietReply,
     pinnedAt: post.pinnedAt,
     featuredAt: post.featuredAt,
@@ -179,7 +214,9 @@ export function toPublicPost(
   const contentFields =
     options?.content === "markdown"
       ? {
-          bodyMarkdown: post.body ? tiptapJsonToMarkdown(post.body) : null,
+          bodyMarkdown: post.body
+            ? toPublicBodyMarkdown(post.id, post.body)
+            : null,
         }
       : {
           bodyHtml: post.bodyHtml,
@@ -204,10 +241,8 @@ export function toPublicPost(
 }
 
 publicPostsApiRoutes.get("/", async (c) => {
-  const { format, collection, sort, cursor, limit, content } = parseValidated(
-    ListPublicPostsQuerySchema,
-    c.req.query(),
-  );
+  const { format, lang, collection, sort, cursor, limit, content } =
+    parseValidated(ListPublicPostsQuerySchema, c.req.query());
 
   // Resolve collection slug(s) — accepts comma-separated (e.g. "tech,art")
   // or "+" separated (e.g. "tech+art"), matching the page URL convention.
@@ -265,6 +300,7 @@ publicPostsApiRoutes.get("/", async (c) => {
           excludePrivate: true,
           excludeLatestHidden: true,
           rootFormat: format,
+          lang,
           sortOrder,
           cursor: cursor ?? undefined,
           limit,
@@ -272,6 +308,7 @@ publicPostsApiRoutes.get("/", async (c) => {
       )
     : await c.var.services.posts.list({
         format,
+        lang,
         status: "published",
         cursor: cursor ?? undefined,
         limit,