@decocms/apps-blog 8.0.0 → 8.1.0-next.0

package/src/core/blogRecords.ts

@@ -0,0 +1,94 @@
+/**
+ * Injectable persistence port for the blog's ratings, reviews and view counts.
+ *
+ * In `deco-cx/apps` these three features talk to the separate `records` app —
+ * a Turso/libsql database driven through `drizzle-orm`, reached as
+ * `await ctx.invoke.records.loaders.drizzle()`. Neither that app nor drizzle
+ * exists in this monorepo, and adding them would make every site that installs
+ * the blog app carry a database client it probably doesn't use.
+ *
+ * So the dependency is inverted, the same way `@decocms/blocks-admin` inverts
+ * its KV dependency via `setFastDeployKVGetter`: this package declares the
+ * operations it needs, and the site injects an implementation at boot. The port
+ * is expressed as *domain* operations rather than as a query builder, so the
+ * table and column names stay on the site's side of the boundary — which is
+ * also why `db/schema.ts` is deliberately not ported.
+ *
+ * With no adapter registered every read degrades to empty and every write to
+ * `null`, mirroring what the Deno app does when the `records` app isn't
+ * installed. That's the common case: a blog with no comments or view counter
+ * works untouched.
+ */
+
+import type { Person } from "@decocms/apps-commerce/types";
+import type { Rating, Review, ViewFromDatabase } from "../types";
+
+export interface ListReviewsOptions {
+  slug: string;
+  /**
+   * `additionalType` values to exclude — the moderation states a site wants
+   * kept out of the public list.
+   */
+  excludeAdditionalTypes?: string[];
+  orderBy: "date_asc" | "date_desc";
+}
+
+export interface UpsertRatingInput {
+  itemReviewed: string;
+  author: Person;
+  ratingValue: number;
+  additionalType?: string;
+}
+
+export interface CreateReviewInput {
+  itemReviewed?: string;
+  author?: Person;
+  reviewHeadline?: string;
+  reviewBody?: string;
+  additionalType?: string;
+  isAnonymous?: boolean;
+  datePublished: string;
+  dateModified: string;
+}
+
+export interface UpdateReviewInput {
+  reviewHeadline?: string;
+  reviewBody?: string;
+  additionalType?: string;
+  dateModified: string;
+}
+
+/**
+ * Every method is optional: a site that only wants view counts implements
+ * `listPostViews`/`incrementPostView` and leaves the rest out.
+ */
+export interface BlogRecordsAdapter {
+  listRatings?(slug: string): Promise<Rating[]>;
+  /**
+   * Creates the rating, or replaces the value of this author's existing rating
+   * for the same item — one rating per author per post.
+   */
+  upsertRating?(input: UpsertRatingInput): Promise<Rating | null>;
+  listReviews?(options: ListReviewsOptions): Promise<Review[]>;
+  getReview?(id: string): Promise<Review | null>;
+  createReview?(input: CreateReviewInput): Promise<Review | null>;
+  updateReview?(id: string, patch: UpdateReviewInput): Promise<Review | null>;
+  listPostViews?(): Promise<ViewFromDatabase[]>;
+  /** Increments (or creates at 1) the view counter, returning the new total. */
+  incrementPostView?(id: string): Promise<{ count: number }>;
+}
+
+const G = globalThis as unknown as { __decoBlogRecordsAdapter?: BlogRecordsAdapter };
+
+/**
+ * Registers the persistence backend for ratings, reviews and view counts.
+ * Call once at boot, before any request is served.
+ */
+export function setBlogRecordsAdapter(adapter: BlogRecordsAdapter): void {
+  G.__decoBlogRecordsAdapter = adapter;
+}
+
+/** The registered adapter, or `undefined` when the site never injected one. */
+export function getBlogRecordsAdapter(): BlogRecordsAdapter | undefined {
+  return G.__decoBlogRecordsAdapter;
+}

package/src/core/categoryTree.ts

@@ -0,0 +1,210 @@
+import type { Category } from "../types";
+
+/**
+ * Categories come from a decofile a human edits by hand, so `parentSlug` can
+ * point at nothing, at itself, or back into a cycle. Every walk below is
+ * bounded twice — by a visited set and by this ceiling — so a malformed record
+ * can never hang a request.
+ */
+export const MAX_CATEGORY_DEPTH = 4;
+
+const isValid = (c?: Category | null): c is Category =>
+  !!c &&
+  typeof c.slug === "string" &&
+  c.slug.length > 0 &&
+  typeof c.name === "string" &&
+  c.name.length > 0;
+
+/** Slug -> category. First entry wins when a slug is duplicated. */
+export const indexCategories = (
+  categories: Category[] | null | undefined,
+): Map<string, Category> => {
+  const index = new Map<string, Category>();
+  for (const category of categories ?? []) {
+    if (isValid(category) && !index.has(category.slug)) {
+      index.set(category.slug, category);
+    }
+  }
+  return index;
+};
+
+const parentOf = (category: Category, index: Map<string, Category>): Category | undefined => {
+  const parentSlug = category.parentSlug;
+  if (typeof parentSlug !== "string" || !parentSlug || parentSlug === category.slug) {
+    return undefined;
+  }
+  return index.get(parentSlug);
+};
+
+/**
+ * The ancestor chain of `slug`, root first and the category itself last —
+ * exactly the breadcrumb sequence.
+ *
+ * Returns null whenever the chain cannot be trusted: the slug is unknown, the
+ * walk ran into a cycle, or it went past MAX_CATEGORY_DEPTH. A truncated chain
+ * is worse than none — it would name a breadcrumb and a canonical URL missing
+ * their topmost segments — so callers fall back to the flat behaviour instead.
+ * A dangling `parentSlug` or a self-reference is not an error: the walk just
+ * ends there, treating the category as a root.
+ */
+export const ancestorsOf = (slug: string, index: Map<string, Category>): Category[] | null => {
+  const start = index.get(slug);
+  if (!start) {
+    return null;
+  }
+
+  const chain: Category[] = [];
+  const seen = new Set<string>();
+  let current: Category | undefined = start;
+
+  while (current) {
+    if (seen.has(current.slug) || chain.length >= MAX_CATEGORY_DEPTH) {
+      return null;
+    }
+    seen.add(current.slug);
+    chain.push(current);
+    current = parentOf(current, index);
+  }
+
+  return chain.reverse();
+};
+
+/** Children indexed by parent slug, skipping self-references. */
+const childrenIndex = (categories: Category[]): Map<string, Category[]> => {
+  const children = new Map<string, Category[]>();
+  for (const category of categories) {
+    const parentSlug = category.parentSlug;
+    if (
+      !isValid(category) ||
+      typeof parentSlug !== "string" ||
+      !parentSlug ||
+      parentSlug === category.slug
+    ) {
+      continue;
+    }
+    const siblings = children.get(parentSlug);
+    siblings ? siblings.push(category) : children.set(parentSlug, [category]);
+  }
+  return children;
+};
+
+/**
+ * `slug` plus every category below it. Breadth-first with a visited set, so a
+ * cycle yields a finite set instead of looping. Used to make a parent category
+ * list its children's posts.
+ */
+export const descendantSlugs = (
+  slug: string,
+  categories: Category[] | null | undefined,
+): string[] => {
+  const children = childrenIndex(categories ?? []);
+  const seen = new Set<string>([slug]);
+  let frontier = [slug];
+
+  for (let depth = 0; depth < MAX_CATEGORY_DEPTH && frontier.length; depth++) {
+    const next: string[] = [];
+    for (const parent of frontier) {
+      for (const child of children.get(parent) ?? []) {
+        if (!seen.has(child.slug)) {
+          seen.add(child.slug);
+          next.push(child.slug);
+        }
+      }
+    }
+    frontier = next;
+  }
+
+  return [...seen];
+};
+
+/** Direct children of `slug`, name-sorted. */
+export const childrenOf = (slug: string, categories: Category[] | null | undefined): Category[] =>
+  (childrenIndex(categories ?? []).get(slug) ?? []).sort((a, b) => a.name.localeCompare(b.name));
+
+/** "pai/filho" — the URL path a category chain occupies. */
+export const categoryPathname = (chain: Category[]): string => chain.map((c) => c.slug).join("/");
+
+interface PathOptions {
+  /**
+   * The category segments the router handed the loader. They must be the tail
+   * of the pathname, otherwise the slug was configured by hand and the URL
+   * carries no category to rewrite.
+   */
+  requested?: string[];
+  /**
+   * Known category slugs, for routes that don't hand the category over — the
+   * category segments are the trailing ones that name a real category.
+   */
+  knownSlugs?: Set<string>;
+  /** Segment that stays at the end of the path — a post slug. */
+  trailing?: string;
+}
+
+/**
+ * Rewrites the category portion of a URL with the canonical chain, keeping the
+ * route prefix (`/blog`) and an optional trailing post slug. A request that
+ * reaches a child through a stale or wrong path still renders; this is what
+ * points its canonical at the one true URL so Google consolidates instead of
+ * seeing duplicates.
+ *
+ * Returns null when the URL has no category portion to replace — a route
+ * without a category segment, or a slug that didn't come from the route. The
+ * caller keeps the request URL rather than inventing a path that 404s.
+ */
+export const withCategoryPath = (
+  url: string | URL,
+  chain: Category[],
+  { requested, knownSlugs, trailing }: PathOptions = {},
+): string | null => {
+  if (chain.length === 0) {
+    return null;
+  }
+
+  const parsed = new URL(url);
+  let segments = parsed.pathname.split("/").filter(Boolean);
+
+  if (trailing) {
+    if (segments[segments.length - 1] !== trailing) {
+      return null;
+    }
+    segments = segments.slice(0, -1);
+  }
+
+  if (requested) {
+    const size = requested.length;
+    const tail = segments.slice(Math.max(segments.length - size, 0));
+    if (size === 0 || tail.join("/") !== requested.join("/")) {
+      return null;
+    }
+    segments = segments.slice(0, segments.length - size);
+  } else if (knownSlugs) {
+    const before = segments.length;
+    // Bounded by the chain length: the request can carry at most as many
+    // category segments as the canonical chain has. Without the bound, a
+    // category whose slug collides with the route prefix — `/blog/blog/a-post`
+    // for a category slugged "blog" — strips the prefix too and canonicalizes
+    // to a path the site never serves.
+    while (
+      segments.length &&
+      before - segments.length < chain.length &&
+      knownSlugs.has(segments[segments.length - 1])
+    ) {
+      segments = segments.slice(0, -1);
+    }
+    if (segments.length === before) {
+      return null;
+    }
+  } else {
+    return null;
+  }
+
+  // Slugs are authored by hand, so a stray "/", "?" or "#" would otherwise stop
+  // being one path segment and start being a new segment, a query or a
+  // fragment. Encoded, a malformed slug yields a 404 instead of a canonical
+  // pointing at a different page.
+  const pathname = `/${[...segments, ...chain.map((c) => c.slug), ...(trailing ? [trailing] : [])]
+    .map(encodeURIComponent)
+    .join("/")}`;
+
+  return new URL(pathname, parsed.origin).href;
+};

package/src/core/handlePosts.ts

@@ -1,88 +1,184 @@
 import type { BlogPost, SortBy } from "../types";
-
-const VALID_SORT_ORDERS = ["asc", "desc"];
+import { isLivePost } from "../types";
+import { VALID_SORT_ORDERS } from "../utils/constants";
+import { dateToTime } from "../utils/date";
+import { getBlogRecordsAdapter } from "./blogRecords";
 
 /**
- * Sort posts by the given criteria.
- * Skips view-based sorting (no Drizzle in this port).
+ * Returns a sorted BlogPost list.
+ *
+ * @param blogPosts Posts to be sorted
+ * @param sortBy Sort option ("date_desc" | "date_asc" | "title_asc" | "title_desc" | "view_asc" | "view_desc")
  */
-export const sortPosts = (blogPosts: BlogPost[], sortBy: SortBy): BlogPost[] => {
-	const parts = sortBy.split("_");
-	const sortMethod = (parts[0] in blogPosts[0] ? parts[0] : "date") as keyof BlogPost;
-	const sortOrder = VALID_SORT_ORDERS.includes(parts[1]) ? parts[1] : "desc";
-
-	return [...blogPosts].sort((a, b) => {
-		if (!a[sortMethod] && !b[sortMethod]) return 0;
-		if (!a[sortMethod]) return 1;
-		if (!b[sortMethod]) return -1;
-
-		const comparison =
-			sortMethod === "date"
-				? new Date(`${b.date}T00:00:00`).getTime() - new Date(`${a.date}T00:00:00`).getTime()
-				: (a[sortMethod]?.toString().localeCompare(b[sortMethod]?.toString() ?? "") ?? 0);
-
-		return sortOrder === "desc" ? comparison : -comparison;
-	});
+export const sortPosts = async (blogPosts: BlogPost[], sortBy: SortBy): Promise<BlogPost[]> => {
+  const splittedSort = sortBy.split("_");
+
+  if (splittedSort[0] === "view") {
+    const views = await getBlogRecordsAdapter()?.listPostViews?.();
+
+    // No adapter (or no rows): fall through to the date sort rather than
+    // returning an arbitrary order. The Deno app threw here when the `records`
+    // app was missing; degrading is the deliberate difference — view sorting is
+    // an enhancement, and a blog without the backend should still render.
+    if (views?.length) {
+      // Act like a real extension: stamp the counts onto the posts.
+      for (const view of views) {
+        const post = blogPosts.find(({ slug }) => slug === view.id);
+        if (post) {
+          post.interactionStatistic = {
+            "@type": "InteractionCounter",
+            userInteractionCount: view.userInteractionCount,
+          };
+        }
+      }
+
+      const viewSortOrder = VALID_SORT_ORDERS.includes(splittedSort[1]) ? splittedSort[1] : "desc";
+
+      return [...blogPosts].sort((a, b) => {
+        const countOfA = a?.interactionStatistic?.userInteractionCount;
+        const countOfB = b?.interactionStatistic?.userInteractionCount;
+        if (!countOfA && !countOfB) {
+          return 0;
+        }
+        // NOTE: inverted, like the title branch below — `view_desc` puts the
+        // *least* viewed post first. Verbatim from upstream
+        // (deco-cx/apps blog/core/handlePosts.ts); only the `date` branch, which
+        // compares `b - a`, reads the right way round. Kept as-is so a site
+        // moving off the Deno app sees no reordering; fix it upstream first.
+        const comparison = (countOfA ?? 0) - (countOfB ?? 0);
+        return viewSortOrder === "desc" ? comparison : -comparison;
+      });
+    }
+  }
+
+  const sortMethod = (splittedSort[0] in blogPosts[0] ? splittedSort[0] : "date") as keyof BlogPost;
+  const sortOrder = VALID_SORT_ORDERS.includes(splittedSort[1]) ? splittedSort[1] : "desc";
+
+  return [...blogPosts].sort((a, b) => {
+    if (!a[sortMethod] && !b[sortMethod]) {
+      return 0; // Both lack the sort key — consider them equal
+    }
+    if (!a[sortMethod]) {
+      return 1; // a lacks the sort key — put it after b
+    }
+    if (!b[sortMethod]) {
+      return -1;
+    }
+    // NOTE: for the non-date keys this reads inverted — `title_asc` yields Z-A.
+    // That is upstream's behaviour (deco-cx/apps blog/core/handlePosts.ts) and
+    // existing content relies on it, so it is preserved here on purpose rather
+    // than "fixed" as a drive-by. Don't flip it without changing upstream too.
+    const comparison =
+      sortMethod === "date"
+        ? dateToTime(b.date) - dateToTime(a.date)
+        : (a[sortMethod]?.toString().localeCompare(b[sortMethod]?.toString() ?? "") ?? 0);
+    return sortOrder === "desc" ? comparison : -comparison;
+  });
 };
 
-/** Filter posts by a single category slug. */
-export const filterPostsByCategory = (posts: BlogPost[], slug?: string): BlogPost[] =>
-	slug ? posts.filter(({ categories }) => categories?.find((c) => c.slug === slug)) : posts;
+/**
+ * Returns a filtered BlogPost list.
+ *
+ * @param posts Posts to be handled
+ * @param slug Category slug, or a list of slugs a post may belong to any of.
+ *   A list is how a parent category pulls in its descendants' posts.
+ *
+ * An omitted slug means "no category filter" and keeps every post. An *empty
+ * list* is the opposite — an explicit, empty set of categories to match, which
+ * nothing belongs to. Upstream conflates the two and answers every post to
+ * both, which turns a related-posts widget for a post with no categories into
+ * a second listing of the whole blog.
+ */
+export const filterPostsByCategory = (posts: BlogPost[], slug?: string | string[]): BlogPost[] => {
+  if (slug === undefined || slug === "") {
+    return posts;
+  }
+  const slugs = new Set(Array.isArray(slug) ? slug : [slug]);
+  return posts.filter(({ categories }) => categories?.some((c) => slugs.has(c?.slug)));
+};
 
 /** Filter posts whose slug is in the given list. */
 export const filterPostsBySlugs = (posts: BlogPost[], postSlugs: string[]): BlogPost[] =>
-	posts.filter(({ slug }) => postSlugs.includes(slug));
+  posts.filter(({ slug }) => postSlugs.includes(slug));
 
 /** Filter posts matching a search term (title, excerpt, content). */
 export const filterPostsByTerm = (posts: BlogPost[], term: string): BlogPost[] =>
-	posts.filter(({ content, excerpt, title }) =>
-		[content, excerpt, title].some((field) => field?.toLowerCase().includes(term.toLowerCase())),
-	);
+  posts.filter(({ content, excerpt, title }) =>
+    [content, excerpt, title].some((field) => field?.toLowerCase().includes(term.toLowerCase())),
+  );
 
 /** Filter posts whose categories overlap with the given slug array. */
 export const filterRelatedPosts = (posts: BlogPost[], slugs: string[]): BlogPost[] =>
-	posts.filter(({ categories }) => categories?.find((c) => slugs.includes(c.slug)));
+  filterPostsByCategory(posts, slugs);
 
 /** Slice posts for pagination. */
 export const slicePosts = (
-	posts: BlogPost[],
-	pageNumber: number,
-	postsPerPage: number,
+  posts: BlogPost[],
+  pageNumber: number,
+  postsPerPage: number,
 ): BlogPost[] => {
-	const startIndex = (pageNumber - 1) * postsPerPage;
-	return posts.slice(startIndex, startIndex + postsPerPage);
+  const startIndex = (pageNumber - 1) * postsPerPage;
+  return posts.slice(startIndex, startIndex + postsPerPage);
 };
 
 /**
- * Combined filter & sort pipeline (no slice).
+ * A record without a slug has no route, so it can never be rendered: listing it
+ * only produces cards linking to the listing itself. Posts that aren't live are
+ * unreachable for a different reason — either the CMS doesn't consider them
+ * ready, or they're scheduled for an instant that hasn't arrived yet — but the
+ * outcome is the same, so both are dropped here, before slicePosts, so `count`
+ * still yields `count` renderable posts.
+ *
+ * A scheduled post crossing its instant flips this filter on the next request
+ * that misses cache; nothing re-deploys and no record is rewritten.
  */
-export default function handlePosts(
-	posts: BlogPost[],
-	sortBy: SortBy,
-	slug?: string | string[],
-	postSlugs?: string[],
-	term?: string,
-	excludePostSlug?: string,
-): BlogPost[] | null {
-	let filtered: BlogPost[];
-
-	if (typeof slug === "string") {
-		filtered =
-			postSlugs && postSlugs.length > 0
-				? filterPostsBySlugs(posts, postSlugs)
-				: filterPostsByCategory(posts, slug);
-		if (term) filtered = filterPostsByTerm(filtered, term);
-	} else if (Array.isArray(slug)) {
-		filtered = filterRelatedPosts(posts, slug);
-	} else {
-		filtered = term ? filterPostsByTerm(posts, term) : posts;
-	}
-
-	if (excludePostSlug) {
-		filtered = filtered.filter(({ slug: s }) => s !== excludePostSlug);
-	}
-
-	if (!filtered || filtered.length === 0) return null;
-
-	return sortPosts(filtered, sortBy);
+export const filterRoutablePosts = (posts: BlogPost[]): BlogPost[] =>
+  // Records come straight from the CMS, so `slug` is only a string by
+  // convention: the typeof guard keeps a malformed one from throwing here and
+  // taking the whole listing down with it.
+  posts.filter((post) => typeof post.slug === "string" && post.slug.trim() && isLivePost(post));
+
+const filterPosts = (
+  allPosts: BlogPost[],
+  slug?: string | string[],
+  postSlugs?: string[],
+  term?: string,
+): BlogPost[] => {
+  const posts = filterRoutablePosts(allPosts);
+
+  const byCategory =
+    postSlugs && postSlugs.length > 0
+      ? filterPostsBySlugs(posts, postSlugs)
+      : filterPostsByCategory(posts, slug);
+
+  return term ? filterPostsByTerm(byCategory, term) : byCategory;
+};
+
+/**
+ * Returns a filtered and sorted BlogPost list. It does not slice.
+ *
+ * @param posts Posts to be handled
+ * @param sortBy Sort option
+ * @param slug Category slug, or an array of slugs, to filter by
+ * @param postSlugs Specific slugs to filter by
+ * @param term Term to filter by
+ * @param excludePostSlug Slug to exclude
+ */
+export default async function handlePosts(
+  posts: BlogPost[],
+  sortBy: SortBy,
+  slug?: string | string[],
+  postSlugs?: string[],
+  term?: string,
+  excludePostSlug?: string,
+): Promise<BlogPost[] | null> {
+  const filteredPosts = filterPosts(posts, slug, postSlugs, term).filter(
+    ({ slug: postSlug }) => postSlug !== excludePostSlug,
+  );
+
+  if (filteredPosts.length === 0) {
+    return null;
+  }
+
+  return sortPosts(filteredPosts, sortBy);
 }