@jant/core 0.6.16 → 0.7.0

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,7 @@ export type PublicPostMarkdownResponse = PublicPostBaseResponse & {
 };
 
 export type PublicPostResponse =
-  | PublicPostRenderedResponse
-  | PublicPostMarkdownResponse;
+  PublicPostRenderedResponse | PublicPostMarkdownResponse;
 
 function isPublicDetailVisible(post: Post | null): post is Post {
   return (
@@ -151,6 +166,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,
@@ -204,10 +221,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 +280,7 @@ publicPostsApiRoutes.get("/", async (c) => {
           excludePrivate: true,
           excludeLatestHidden: true,
           rootFormat: format,
+          lang,
           sortOrder,
           cursor: cursor ?? undefined,
           limit,
@@ -272,6 +288,7 @@ publicPostsApiRoutes.get("/", async (c) => {
       )
     : await c.var.services.posts.list({
         format,
+        lang,
         status: "published",
         cursor: cursor ?? undefined,
         limit,

package/src/routes/api/smart-collections.ts

@@ -0,0 +1,132 @@
+/**
+ * Smart Collections API Routes
+ */
+
+import { Hono } from "hono";
+import { z } from "zod";
+import type { Bindings } from "../../types.js";
+import type { AppVariables } from "../../types/app-context.js";
+import { requireAuthApi } from "../../middleware/auth.js";
+import {
+  ContentLanguageSchema,
+  CreateSmartCollectionSchema,
+  SmartCollectionIdSchema,
+  SmartCollectionPreviewSchema,
+  UpdateSmartCollectionSchema,
+  parseValidated,
+} from "../../lib/schemas.js";
+import { assertFound, parseIdParam } from "../../lib/errors.js";
+import { ID_PREFIX } from "../../lib/ids.js";
+
+type Env = { Bindings: Bindings; Variables: AppVariables };
+
+export const smartCollectionsApiRoutes = new Hono<Env>();
+
+/**
+ * Address availability, in the shape posts already use.
+ *
+ * `suggest` derives one from a title; `check` answers whether a typed one is
+ * free. Collections answer the same question at `/api/collections/slug`.
+ */
+const SlugQuerySchema = z.discriminatedUnion("mode", [
+  z.object({
+    mode: z.literal("suggest"),
+    title: z.string().trim().max(300).optional(),
+    smartCollectionId: SmartCollectionIdSchema.optional(),
+  }),
+  z.object({
+    mode: z.literal("check"),
+    slug: z.string().trim().toLowerCase().min(1).max(200),
+    smartCollectionId: SmartCollectionIdSchema.optional(),
+  }),
+]);
+
+const PreviewQuerySchema = z.object({
+  lang: ContentLanguageSchema.optional(),
+});
+
+// --- Address ---------------------------------------------------------------
+// Declared before `/:id` so the literal path wins.
+
+smartCollectionsApiRoutes.get("/slug", requireAuthApi(), async (c) => {
+  const query = parseValidated(SlugQuerySchema, c.req.query());
+
+  if (query.mode === "suggest") {
+    const slug = await c.var.services.smartCollections.suggestSlug({
+      title: query.title,
+      excludeId: query.smartCollectionId,
+    });
+    return c.json({ slug });
+  }
+
+  const available = await c.var.services.smartCollections.checkSlugAvailability(
+    query.slug,
+    query.smartCollectionId,
+  );
+  return c.json({ slug: query.slug, available });
+});
+
+// --- Preview ---------------------------------------------------------------
+
+/**
+ * How many threads a set of conditions would gather, against the site total.
+ *
+ * POST rather than GET: the conditions are a typed body in the same shape the
+ * create endpoint validates, and putting them in a URL would mean inventing a
+ * second spelling for them.
+ */
+smartCollectionsApiRoutes.post("/preview", requireAuthApi(), async (c) => {
+  const body = parseValidated(SmartCollectionPreviewSchema, await c.req.json());
+  const query = parseValidated(PreviewQuerySchema, c.req.query());
+
+  const { count, baseline } = await c.var.services.smartCollections.preview(
+    body.selection ?? {},
+    { isAuthenticated: c.var.isAuthenticated, lang: query.lang },
+  );
+
+  c.header("Cache-Control", "no-store");
+  return c.json({ count, baseline });
+});
+
+// --- CRUD ------------------------------------------------------------------
+
+smartCollectionsApiRoutes.get("/", requireAuthApi(), async (c) => {
+  const query = parseValidated(PreviewQuerySchema, c.req.query());
+  const smartCollections =
+    await c.var.services.smartCollections.listDirectoryEntries({
+      isAuthenticated: c.var.isAuthenticated,
+      lang: query.lang,
+    });
+  return c.json({ smartCollections });
+});
+
+smartCollectionsApiRoutes.post("/", requireAuthApi(), async (c) => {
+  const body = parseValidated(CreateSmartCollectionSchema, await c.req.json());
+  const smartCollection = await c.var.services.smartCollections.create(body);
+  return c.json({ smartCollection }, 201);
+});
+
+smartCollectionsApiRoutes.get("/:id", requireAuthApi(), async (c) => {
+  const id = parseIdParam(c.req.param("id"), ID_PREFIX.smartCollection);
+  const smartCollection = await c.var.services.smartCollections.getById(id);
+  assertFound(smartCollection, "Smart collection");
+  return c.json({ smartCollection });
+});
+
+smartCollectionsApiRoutes.put("/:id", requireAuthApi(), async (c) => {
+  const id = parseIdParam(c.req.param("id"), ID_PREFIX.smartCollection);
+  const body = parseValidated(UpdateSmartCollectionSchema, await c.req.json());
+  const smartCollection = await c.var.services.smartCollections.update(
+    id,
+    body,
+  );
+  assertFound(smartCollection, "Smart collection");
+  return c.json({ smartCollection });
+});
+
+smartCollectionsApiRoutes.delete("/:id", requireAuthApi(), async (c) => {
+  const id = parseIdParam(c.req.param("id"), ID_PREFIX.smartCollection);
+  const deleted = await c.var.services.smartCollections.delete(id);
+  assertFound(deleted || null, "Smart collection");
+  return c.json({ success: true });
+});

package/src/routes/api/telegram.ts

@@ -25,6 +25,7 @@ import {
   getTelegramWebhookSecret,
 } from "../../lib/env.js";
 import { timingSafeEqualText } from "../../lib/crypto.js";
+import { runDeferred } from "../../lib/deferred.js";
 import {
   answerCallbackQuery,
   buildDeepLink,
@@ -316,7 +317,7 @@ async function processUpdate(
       posterFileId: media.posterFileId ?? null,
     });
 
-    runDeferred(c, async () => {
+    runDeferred(c, "Telegram", async () => {
       await sleep(ALBUM_BUFFER_DELAY_MS);
       const claimed = await telegram.claimAlbumGroup(botId, mediaGroupId);
       if (claimed.length === 0) return;
@@ -371,45 +372,6 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-/**
- * Schedules background work that must outlive the current HTTP response so
- * Telegram can deliver the next webhook in this chat without waiting.
- *
- * On Cloudflare Workers `c.executionCtx.waitUntil` keeps the worker alive
- * until the promise settles. In Node / tests there's no such API, so we just
- * let the promise float — Node's event loop keeps running it. Either way the
- * promise has its own try/catch so unhandled rejections never bubble up.
- *
- * Background work also tracks the pending-promises array we register on the
- * env binding for tests so a vitest can `await` them after advancing timers.
- */
-function runDeferred(
-  c: {
-    env: Bindings;
-    executionCtx?: { waitUntil: (promise: Promise<unknown>) => void };
-  },
-  work: () => Promise<void>,
-): void {
-  const promise = work().catch((err) => {
-    const message = err instanceof Error ? err.message : String(err);
-    // eslint-disable-next-line no-console -- Background failures must be visible.
-    console.error(`[Jant] Telegram background error: ${message}`);
-  });
-  try {
-    c.executionCtx?.waitUntil(promise);
-  } catch {
-    // executionCtx not available (e.g. Node, tests) — promise still runs.
-  }
-  const pending = (
-    c.env as Bindings & {
-      __telegramPending?: Promise<unknown>[];
-    }
-  ).__telegramPending;
-  if (Array.isArray(pending)) {
-    pending.push(promise);
-  }
-}
-
 /**
  * Convert a message's caption + caption_entities into markdown, returning
  * `null` when there's nothing to record. Centralized so single-media and album

package/src/routes/api/uploads.ts

@@ -116,8 +116,7 @@ function scheduleExpiredUploadCleanup(
     .catch(() => {});
 
   let executionCtx:
-    | { waitUntil: (promise: Promise<unknown>) => void }
-    | undefined;
+    { waitUntil: (promise: Promise<unknown>) => void } | undefined;
   try {
     executionCtx = c.executionCtx;
   } catch {