@decocms/apps-blog 7.52.1 → 7.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps-blog",
-  "version": "7.52.1",
+  "version": "7.54.0",
   "type": "module",
   "description": "Deco app: blog content and CMS integration",
   "repository": {
@@ -16,10 +16,19 @@
   "exports": {
     ".": "./src/index.ts",
     "./mod": "./src/mod.ts",
+    "./client": "./src/client.ts",
     "./types": "./src/types.ts",
+    "./manifest.gen": "./src/manifest.gen.ts",
     "./loaderMap": "./src/loaderMap.ts",
     "./loaders/*": "./src/loaders/*.ts",
+    "./loaders/extensions/*": "./src/loaders/extensions/*.ts",
+    "./actions/*": "./src/actions/*.ts",
     "./core/*": "./src/core/*.ts",
+    "./utils/*": "./src/utils/*.ts",
+    "./sections/*": "./src/sections/*.tsx",
+    "./sections/Seo/*": "./src/sections/Seo/*.tsx",
+    "./sections/blocks/*": "./src/sections/blocks/*.tsx",
+    "./static/*": "./src/static/*.ts",
     "./registry": "./src/registry.ts"
   },
   "scripts": {
@@ -29,9 +38,9 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.52.1",
-    "@decocms/apps-commerce": "7.52.1",
-    "@decocms/apps-website": "7.52.1"
+    "@decocms/blocks": "7.54.0",
+    "@decocms/apps-commerce": "7.54.0",
+    "@decocms/apps-website": "7.54.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/README.md

@@ -0,0 +1,69 @@
+# `@decocms/apps-blog` — port status
+
+Source of truth: [`deco-cx/apps/blog`](https://github.com/deco-cx/apps/tree/main/blog).
+This package was originally copied from `apps-start`'s already-reduced blog port
+(Task 13 of `docs/apps-monorepo-migration-plan.md`), not from the Deno original,
+so a chunk of the upstream surface was missing. This file tracks what is now in
+sync and what deliberately isn't.
+
+## Ported
+
+| Upstream | Here | Notes |
+|---|---|---|
+| `types.ts` | `src/types.ts` | Full parity, incl. `PostStatus`, `isPublishedStatus`, `isLivePost`, `Publisher`, `Review`/`Rating`/`AggregateRating`, `Ignore`, `ImageCarousel`. `Section` is redeclared as the opaque `any` type — see the docstring, it's what triggers the admin's section picker. |
+| `utils/{date,constants,jsonLD,sanitizeHtml,hardSanitize,blocksToSections}.ts` | `src/utils/` | Near-literal; pure functions. |
+| `core/handlePosts.ts` | `src/core/handlePosts.ts` | Incl. `filterRoutablePosts` and UTC-pinned date sorting. |
+| `core/records.ts` | `src/core/records.ts` | `getRecordsByPath` uses `loadBlocks()` instead of `ctx.get(resolvables)`. Ratings/reviews go through the adapter (below). |
+| `loaders/*.ts` (9) | `src/loaders/` | `ctx` replaced by `src/client.ts`; `(props, req?)` signatures. |
+| `loaders/extensions/*/[ratings,reviews].ts` (6) | `src/loaders/extensions/` | — |
+| `actions/submit{Rating,Review,View}.ts` | `src/actions/` | Persistence via the adapter. |
+| `sections/Seo/*.tsx` (2) | `src/sections/Seo/` | Reuse `Seo`/`renderTemplateString`/`SEOSection` from `@decocms/apps-website/components/Seo`. |
+| `sections/Template.tsx` | `src/sections/Template.tsx` | `renderSection` replaced by `getSyncComponent` from `@decocms/blocks/cms/client`. |
+| `sections/blocks/*.tsx` (17) | `src/sections/blocks/` | `class` → `className`, SVG attrs camelCased; otherwise unchanged. |
+| `static/css.ts` | `src/static/css.ts` | Verbatim. |
+
+## Deliberately not ported
+
+| Upstream | Why |
+|---|---|
+| `db/schema.ts` | Drizzle/SQLite table definitions for the `records` app. Neither the app nor `drizzle-orm` exists in this monorepo, and pulling them in would make every site installing the blog carry a DB client. The table/column names now live on the site's side of `src/core/blogRecords.ts`. |
+| `loaders/extensions/{BlogpostList,BlogpostListing,BlogpostPage}.ts` | Three-line delegations to `website/loaders/extension.ts` — the *generic* extension-composition loader. That loader has not been ported into `@decocms/apps-website`; reimplementing it here would put a website-app concern in the wrong package. The 6 concrete ratings/reviews extensions are ported and callable directly. **Tracked gap: port `website/loaders/extension.ts` into `@decocms/apps-website`.** |
+| `manifest.gen.ts` (as generated) | `scripts/generate-manifests.ts` doesn't exist in this repo (deferred, `docs/apps-monorepo-migration-plan.md`). `src/manifest.gen.ts` is hand-maintained — add new loaders/actions/sections to it manually. |
+| `mod.ts`'s `preview` / `PreviewContainer` | `utils/preview.tsx` is Deno-app scaffolding with no equivalent here; `preview` is `undefined`, matching every other `apps-*` package. |
+
+## Ratings, reviews and view counts
+
+These three features need persistence. Upstream reaches the separate `records`
+app (`await ctx.invoke.records.loaders.drizzle()`); here the dependency is
+inverted, the same way `@decocms/blocks-admin` inverts KV via
+`setFastDeployKVGetter`:
+
+```ts
+import { setBlogRecordsAdapter } from "@decocms/apps-blog";
+
+setBlogRecordsAdapter({
+  listPostViews: () => db.select(...),
+  incrementPostView: (id) => ...,
+  // listRatings, upsertRating, listReviews, getReview, createReview, updateReview
+});
+```
+
+Every method is optional. With **no adapter registered**, reads return `[]`,
+writes return `null`, `submitView` returns `{ count: 0 }`, and `view_asc` /
+`view_desc` sorting falls back to date order — so a blog with no comments and no
+view counter works untouched. Note this differs from upstream on one point:
+the Deno app *threw* `"Deco Records not installed!"` on a view sort without the
+backend; degrading was chosen instead, since view sorting is an enhancement and
+a missing backend shouldn't blank a listing.
+
+## Divergences from upstream worth knowing
+
+- **Title and view sorts are inverted** — `title_asc` yields Z-A, and
+  `view_desc` puts the *least*-viewed post first. Both come from upstream's
+  comparator (`sortOrder === "desc" ? comparison : -comparison` over an `a - b`
+  difference); only the `date` branch, which compares `b - a`, reads the right
+  way round. Preserved on purpose so a site moving off the Deno app sees no
+  reordering — see the comments in `src/core/handlePosts.ts`. Fix upstream
+  first, then here.
+- **`sortPosts([])` throws** (it reads `blogPosts[0]`). Upstream does too;
+  `handlePosts` guards the empty case before calling it.

package/src/__tests__/blogRecords.test.ts

@@ -0,0 +1,270 @@
+/**
+ * Scope: the injectable persistence port that replaces the Deno app's `records`
+ * dependency — that reads/writes route through the registered adapter, and that
+ * everything degrades safely when a site registers none (or a partial one).
+ *
+ * The degrade path is the important half: it is the default for any site that
+ * installs the blog app without a database, so a regression here breaks blogs
+ * that never asked for ratings at all.
+ *
+ * Deliberately not covered: any real database. The adapter boundary exists
+ * precisely so this package never needs one.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import submitRating from "../actions/submitRating";
+import submitReview from "../actions/submitReview";
+import submitView from "../actions/submitView";
+import {
+  type BlogRecordsAdapter,
+  type CreateReviewInput,
+  type ListReviewsOptions,
+  setBlogRecordsAdapter,
+  type UpdateReviewInput,
+} from "../core/blogRecords";
+import { sortPosts } from "../core/handlePosts";
+import { getRatings, getReviews, getReviewsBySlug } from "../core/records";
+import type { BlogPost, Review } from "../types";
+
+const G = globalThis as unknown as { __decoBlogRecordsAdapter?: BlogRecordsAdapter };
+
+const post = (slug: string, date = "2024-01-01"): BlogPost => ({
+  title: slug,
+  slug,
+  date,
+  excerpt: "",
+});
+
+const clearAdapter = () => {
+  delete G.__decoBlogRecordsAdapter;
+};
+
+beforeEach(clearAdapter);
+afterEach(clearAdapter);
+
+describe("with no adapter registered", () => {
+  it("getRatings yields a zeroed aggregate rather than throwing", async () => {
+    const result = await getRatings({ post: post("a") });
+    expect(result.aggregateRating).toEqual({
+      "@type": "AggregateRating",
+      ratingCount: 0,
+      ratingValue: 0,
+      bestRating: 5,
+      worstRating: 1,
+    });
+    expect(result.contentRating).toEqual([]);
+  });
+
+  it("getReviews yields an empty list and a zero count", async () => {
+    const result = await getReviews({ post: post("a") });
+    expect(result.review).toEqual([]);
+    expect(result.aggregateRating?.reviewCount).toBe(0);
+  });
+
+  it("write actions report failure instead of throwing", async () => {
+    expect(
+      await submitRating({ itemReviewed: "a", author: { email: "a@b.com" }, ratingValue: 5 }),
+    ).toBeNull();
+    expect(await submitReview({ action: "create", reviewBody: "hi" })).toBeNull();
+    // A view beacon gets a well-formed response, not an error.
+    expect(await submitView({ id: "a" })).toEqual({ count: 0 });
+  });
+
+  it("view sorting falls back to date order instead of throwing", async () => {
+    // Upstream threw "Deco Records not installed!" here; degrading is the
+    // deliberate difference — see this package's README.
+    const posts = [post("old", "2024-01-01"), post("new", "2024-03-01")];
+    const sorted = await sortPosts(posts, "view_desc");
+    expect(sorted.map((p) => p.slug)).toEqual(["new", "old"]);
+  });
+});
+
+describe("with an adapter registered", () => {
+  it("getRatings aggregates the adapter's rows and stamps the scale", async () => {
+    setBlogRecordsAdapter({
+      listRatings: async () => [
+        { "@type": "Rating", ratingValue: 5 },
+        { "@type": "Rating", ratingValue: 3 },
+      ],
+    });
+
+    const result = await getRatings({ post: post("a") });
+    expect(result.aggregateRating).toMatchObject({ ratingCount: 2, ratingValue: 4 });
+    // bestRating/worstRating are a property of this app's UI, not of the row.
+    expect(result.contentRating?.[0]).toMatchObject({ bestRating: 5, worstRating: 1 });
+  });
+
+  it("getRatings honours ignoreRatings when computing the aggregate", async () => {
+    setBlogRecordsAdapter({
+      listRatings: async () => [
+        { "@type": "Rating", ratingValue: 5 },
+        { "@type": "Rating", ratingValue: 1, additionalType: "spam" },
+      ],
+    });
+
+    const result = await getRatings({
+      post: post("a"),
+      ignoreRatings: { active: true, markedAs: ["spam"] },
+    });
+    expect(result.aggregateRating).toMatchObject({ ratingCount: 1, ratingValue: 5 });
+  });
+
+  it("onlyAggregate omits the per-rating list", async () => {
+    setBlogRecordsAdapter({ listRatings: async () => [{ "@type": "Rating", ratingValue: 4 }] });
+    const result = await getRatings({ post: post("a"), onlyAggregate: true });
+    expect(result.contentRating).toBeUndefined();
+    expect(result.aggregateRating?.ratingValue).toBe(4);
+  });
+
+  it("translates an active ignoreReviews into excludeAdditionalTypes", async () => {
+    const listReviews = vi.fn(async (_opts: ListReviewsOptions): Promise<Review[]> => []);
+    setBlogRecordsAdapter({ listReviews });
+
+    await getReviewsBySlug({
+      slug: "a",
+      ignoreReviews: { active: true, markedAs: ["pending"] },
+      orderBy: "date_asc",
+    });
+    expect(listReviews).toHaveBeenCalledWith({
+      slug: "a",
+      excludeAdditionalTypes: ["pending"],
+      orderBy: "date_asc",
+    });
+  });
+
+  it("leaves excludeAdditionalTypes unset when ignoreReviews is inactive or empty", async () => {
+    const listReviews = vi.fn(async (_opts: ListReviewsOptions): Promise<Review[]> => []);
+    setBlogRecordsAdapter({ listReviews });
+
+    await getReviewsBySlug({ slug: "a", ignoreReviews: { active: false, markedAs: ["x"] } });
+    await getReviewsBySlug({ slug: "a", ignoreReviews: { active: true, markedAs: [] } });
+    for (const call of listReviews.mock.calls) {
+      expect(call[0]).toMatchObject({ excludeAdditionalTypes: undefined });
+    }
+  });
+
+  it("defaults review ordering to date_desc", async () => {
+    const listReviews = vi.fn(async (_opts: ListReviewsOptions): Promise<Review[]> => []);
+    setBlogRecordsAdapter({ listReviews });
+    await getReviewsBySlug({ slug: "a" });
+    expect(listReviews).toHaveBeenCalledWith(expect.objectContaining({ orderBy: "date_desc" }));
+  });
+
+  it("stamps view counts onto posts and sorts by them (inverted, per upstream)", async () => {
+    setBlogRecordsAdapter({
+      listPostViews: async () => [
+        { id: "low", userInteractionCount: 2 },
+        { id: "high", userInteractionCount: 90 },
+      ],
+    });
+
+    const posts = [post("low"), post("high")];
+    // `view_desc` yields least-viewed-first: upstream's comparator is `a - b`
+    // under `desc`. Preserved deliberately — see the comment in handlePosts.ts.
+    expect((await sortPosts(posts, "view_desc")).map((p) => p.slug)).toEqual(["low", "high"]);
+    expect((await sortPosts(posts, "view_asc")).map((p) => p.slug)).toEqual(["high", "low"]);
+    // Either way the counts are attached to the posts, which is what the SEO
+    // JSON-LD reads as interactionStatistic.
+    expect(posts.find((p) => p.slug === "high")?.interactionStatistic).toEqual({
+      "@type": "InteractionCounter",
+      userInteractionCount: 90,
+    });
+  });
+
+  it("increments a view through the adapter", async () => {
+    setBlogRecordsAdapter({ incrementPostView: async () => ({ count: 7 }) });
+    expect(await submitView({ id: "a" })).toEqual({ count: 7 });
+  });
+
+  it("swallows an adapter failure on read and returns the empty shape", async () => {
+    setBlogRecordsAdapter({
+      listRatings: async () => {
+        throw new Error("db down");
+      },
+    });
+    const result = await getRatings({ post: post("a") });
+    expect(result.contentRating).toEqual([]);
+    expect(result.aggregateRating?.ratingCount).toBe(0);
+  });
+
+  it("swallows an adapter failure on write and reports it as null", async () => {
+    setBlogRecordsAdapter({
+      upsertRating: async () => {
+        throw new Error("db down");
+      },
+    });
+    expect(
+      await submitRating({ itemReviewed: "a", author: { email: "a@b.com" }, ratingValue: 5 }),
+    ).toBeNull();
+  });
+
+  it("refuses to update a review that does not exist", async () => {
+    setBlogRecordsAdapter({
+      getReview: async () => null,
+      updateReview: async () => null,
+    });
+    expect(await submitReview({ action: "update", id: "missing", reviewBody: "x" })).toBeNull();
+  });
+
+  it("patches an update over the stored review, preserving untouched fields", async () => {
+    const updateReview = vi.fn(
+      async (_id: string, _patch: UpdateReviewInput): Promise<Review | null> => null,
+    );
+    setBlogRecordsAdapter({
+      getReview: async () => ({
+        "@type": "Review",
+        id: "r1",
+        itemReviewed: "a",
+        reviewBody: "old body",
+        reviewHeadline: "old headline",
+        additionalType: "approved",
+        datePublished: "2024-01-01T00:00:00.000Z",
+        author: { name: "Ana" },
+      }),
+      updateReview,
+    });
+
+    const result = await submitReview({ action: "update", id: "r1", reviewBody: "new body" });
+
+    // Only the sent field changes; headline/status/author/datePublished survive.
+    expect(updateReview).toHaveBeenCalledWith(
+      "r1",
+      expect.objectContaining({
+        reviewBody: "new body",
+        reviewHeadline: "old headline",
+        additionalType: "approved",
+      }),
+    );
+    expect(result).toMatchObject({
+      "@type": "Review",
+      id: "r1",
+      reviewBody: "new body",
+      datePublished: "2024-01-01T00:00:00.000Z",
+      author: { name: "Ana" },
+    });
+  });
+
+  it("creates a review with both timestamps set", async () => {
+    const createReview = vi.fn(async (_input: CreateReviewInput): Promise<Review | null> => null);
+    setBlogRecordsAdapter({ createReview });
+
+    const result = await submitReview({
+      action: "create",
+      itemReviewed: "a",
+      reviewBody: "great",
+    });
+
+    const arg = createReview.mock.calls[0][0];
+    expect(arg.datePublished).toBe(arg.dateModified);
+    expect(result).toMatchObject({ "@type": "Review", reviewBody: "great" });
+  });
+
+  it("returns null when the adapter implements only part of the port", async () => {
+    // A site that wants view counts and nothing else.
+    setBlogRecordsAdapter({ incrementPostView: async () => ({ count: 1 }) });
+    expect(await submitReview({ action: "create", reviewBody: "x" })).toBeNull();
+    expect(
+      await submitRating({ itemReviewed: "a", author: { email: "a@b.com" }, ratingValue: 5 }),
+    ).toBeNull();
+  });
+});

package/src/__tests__/date.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Scope: `utils/date.ts` — the UTC pinning that makes post ordering and
+ * scheduled go-live instants independent of the server's timezone, plus
+ * `scheduledTime`'s strict parse.
+ *
+ * The timezone cases below are the point of the module. They are written by
+ * comparing timestamps rather than by mutating `process.env.TZ` mid-run, which
+ * V8 caches per-isolate and would not reliably take effect; the repo-level
+ * check is `TZ=... bun run test` producing identical output, and the assertions
+ * here encode the invariant that makes that true.
+ */
+
+import { describe, expect, it } from "vitest";
+import { sortPosts } from "../core/handlePosts";
+import type { BlogPost } from "../types";
+import { dateToTime, scheduledTime } from "../utils/date";
+
+const post = (slug: string, date: string): BlogPost => ({
+  title: slug,
+  slug,
+  date,
+  excerpt: "",
+});
+
+describe("dateToTime", () => {
+  it("reads a bare date as midnight UTC, not midnight local", () => {
+    expect(dateToTime("2024-06-01")).toBe(Date.UTC(2024, 5, 1));
+  });
+
+  it("pins an offset-less datetime to UTC", () => {
+    // Plain `new Date("2024-06-01T00:00:00")` is *local* time — in any zone
+    // west of UTC that lands on May 31st, reordering posts across a day
+    // boundary depending on which server answered the request.
+    expect(dateToTime("2024-06-01T00:00:00")).toBe(Date.UTC(2024, 5, 1));
+  });
+
+  it("honours an explicit offset instead of overriding it", () => {
+    expect(dateToTime("2024-06-01T00:00:00-03:00")).toBe(Date.UTC(2024, 5, 1, 3));
+  });
+
+  it("returns 0 rather than NaN for an unparseable value", () => {
+    expect(dateToTime("not a date")).toBe(0);
+  });
+
+  it("orders two dates one day apart identically regardless of host offset", () => {
+    // Both values are absolute instants, so the comparison cannot shift with
+    // the host timezone — this is the property the sort comparator relies on.
+    expect(dateToTime("2024-06-02") - dateToTime("2024-06-01")).toBe(24 * 60 * 60 * 1000);
+  });
+});
+
+describe("sortPosts date ordering is timezone-independent", () => {
+  it("keeps day-boundary dates in order", async () => {
+    const posts = [
+      post("may-31", "2024-05-31"),
+      post("jun-02", "2024-06-02"),
+      post("jun-01", "2024-06-01"),
+    ];
+    const sorted = await sortPosts(posts, "date_desc");
+    expect(sorted.map((p) => p.slug)).toEqual(["jun-02", "jun-01", "may-31"]);
+  });
+
+  it("does not reorder datetimes that differ only by their offset", async () => {
+    // Same instant expressed two ways; neither may sort ahead of the other by
+    // accident of the host zone.
+    const posts = [
+      post("utc", "2024-06-01T03:00:00Z"),
+      post("offset", "2024-06-01T00:00:00-03:00"),
+    ];
+    const sorted = await sortPosts(posts, "date_desc");
+    expect(dateToTime(sorted[0].date)).toBe(dateToTime(sorted[1].date));
+  });
+
+  it("orders a mix of bare dates and full ISO timestamps correctly", async () => {
+    // The concrete regression this module fixes: the previous implementation
+    // built its timestamp as `new Date(\`${date}T00:00:00\`)`, which yields
+    // `Invalid Date` → NaN for any value that already carries a time. A NaN
+    // comparison is treated as 0, so every full-ISO post compared "equal" to
+    // everything and the listing order became arbitrary.
+    const posts = [
+      post("bare-old", "2024-01-01"),
+      post("iso-newest", "2024-12-01T09:30:00Z"),
+      post("bare-mid", "2024-06-01"),
+      post("iso-offset", "2024-03-01T00:00:00-03:00"),
+    ];
+    const sorted = await sortPosts(posts, "date_desc");
+    expect(sorted.map((p) => p.slug)).toEqual(["iso-newest", "bare-mid", "iso-offset", "bare-old"]);
+  });
+});
+
+describe("scheduledTime", () => {
+  it("accepts a bare date as midnight UTC", () => {
+    expect(scheduledTime("2026-09-01")).toBe(Date.UTC(2026, 8, 1));
+  });
+
+  it("accepts a full ISO instant, with or without an offset", () => {
+    expect(scheduledTime("2026-09-01T12:30:00Z")).toBe(Date.UTC(2026, 8, 1, 12, 30));
+    expect(scheduledTime("2026-09-01T12:30:00-03:00")).toBe(Date.UTC(2026, 8, 1, 15, 30));
+  });
+
+  it("rejects a non-ISO string that `Date` would happily parse in local time", () => {
+    expect(scheduledTime("Sep 1 2026")).toBeNull();
+    // "0" is the year 2000 to `Date` — i.e. already live.
+    expect(scheduledTime("0")).toBeNull();
+    expect(scheduledTime("")).toBeNull();
+  });
+
+  it("rejects calendar overflow instead of rolling it forward", () => {
+    expect(scheduledTime("2026-02-31")).toBeNull();
+    expect(scheduledTime("2026-13-01")).toBeNull();
+    expect(scheduledTime("2026-00-10")).toBeNull();
+    expect(scheduledTime("2026-01-00")).toBeNull();
+  });
+
+  it("accepts Feb 29 in a leap year and rejects it otherwise", () => {
+    expect(scheduledTime("2024-02-29")).toBe(Date.UTC(2024, 1, 29));
+    expect(scheduledTime("2026-02-29")).toBeNull();
+  });
+
+  it("rejects out-of-range times", () => {
+    expect(scheduledTime("2026-09-01T24:00:00")).toBeNull();
+    expect(scheduledTime("2026-09-01T12:60:00")).toBeNull();
+    expect(scheduledTime("2026-09-01T12:00:61")).toBeNull();
+  });
+
+  it("rejects an offset that matches the pattern but is not a real instant", () => {
+    expect(scheduledTime("2026-09-01T12:00:00+99:00")).toBeNull();
+  });
+
+  it("returns null, not 0, on failure — so the epoch stays representable", () => {
+    expect(scheduledTime("garbage")).toBeNull();
+    expect(scheduledTime("1970-01-01T00:00:00Z")).toBe(0);
+  });
+});