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

package/src/__tests__/records.test.ts

@@ -1,7 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 vi.mock("@decocms/blocks/cms", () => ({
-	loadBlocks: vi.fn(),
+  loadBlocks: vi.fn(),
 }));
 
 import { loadBlocks } from "@decocms/blocks/cms";
@@ -10,83 +10,83 @@ import { getRecordsByPath } from "../core/records";
 const mockLoadBlocks = loadBlocks as ReturnType<typeof vi.fn>;
 
 beforeEach(() => {
-	vi.clearAllMocks();
+  vi.clearAllMocks();
 });
 
 describe("getRecordsByPath", () => {
-	it("extracts records matching path prefix", () => {
-		mockLoadBlocks.mockReturnValue({
-			"collections/blog/posts/hello": {
-				name: "collections/blog/posts/hello",
-				post: { title: "Hello", slug: "hello" },
-			},
-			"collections/blog/posts/world": {
-				name: "collections/blog/posts/world",
-				post: { title: "World", slug: "world" },
-			},
-		});
+  it("extracts records matching path prefix", () => {
+    mockLoadBlocks.mockReturnValue({
+      "collections/blog/posts/hello": {
+        name: "collections/blog/posts/hello",
+        post: { title: "Hello", slug: "hello" },
+      },
+      "collections/blog/posts/world": {
+        name: "collections/blog/posts/world",
+        post: { title: "World", slug: "world" },
+      },
+    });
 
-		const result = getRecordsByPath("collections/blog/posts", "post");
-		expect(result).toHaveLength(2);
-		expect(result).toEqual(
-			expect.arrayContaining([
-				expect.objectContaining({ title: "Hello", slug: "hello" }),
-				expect.objectContaining({ title: "World", slug: "world" }),
-			]),
-		);
-	});
+    const result = getRecordsByPath("collections/blog/posts", "post");
+    expect(result).toHaveLength(2);
+    expect(result).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ title: "Hello", slug: "hello" }),
+        expect.objectContaining({ title: "World", slug: "world" }),
+      ]),
+    );
+  });
 
-	it("skips non-object blocks", () => {
-		mockLoadBlocks.mockReturnValue({
-			"collections/blog/posts/a": "not-an-object",
-			"collections/blog/posts/b": null,
-			"collections/blog/posts/c": {
-				name: "collections/blog/posts/c",
-				post: { title: "C" },
-			},
-		});
+  it("skips non-object blocks", () => {
+    mockLoadBlocks.mockReturnValue({
+      "collections/blog/posts/a": "not-an-object",
+      "collections/blog/posts/b": null,
+      "collections/blog/posts/c": {
+        name: "collections/blog/posts/c",
+        post: { title: "C" },
+      },
+    });
 
-		const result = getRecordsByPath("collections/blog/posts", "post");
-		expect(result).toHaveLength(1);
-		expect(result[0]).toEqual(expect.objectContaining({ title: "C" }));
-	});
+    const result = getRecordsByPath("collections/blog/posts", "post");
+    expect(result).toHaveLength(1);
+    expect(result[0]).toEqual(expect.objectContaining({ title: "C" }));
+  });
 
-	it("skips blocks without the accessor field", () => {
-		mockLoadBlocks.mockReturnValue({
-			"collections/blog/posts/x": {
-				name: "collections/blog/posts/x",
-				other: { title: "X" },
-			},
-		});
+  it("skips blocks without the accessor field", () => {
+    mockLoadBlocks.mockReturnValue({
+      "collections/blog/posts/x": {
+        name: "collections/blog/posts/x",
+        other: { title: "X" },
+      },
+    });
 
-		const result = getRecordsByPath("collections/blog/posts", "post");
-		expect(result).toEqual([]);
-	});
+    const result = getRecordsByPath("collections/blog/posts", "post");
+    expect(result).toEqual([]);
+  });
 
-	it("derives id from block name", () => {
-		mockLoadBlocks.mockReturnValue({
-			"collections/blog/posts/my-post": {
-				name: "collections/blog/posts/my-post",
-				post: { title: "My Post" },
-			},
-		});
+  it("derives id from block name", () => {
+    mockLoadBlocks.mockReturnValue({
+      "collections/blog/posts/my-post": {
+        name: "collections/blog/posts/my-post",
+        post: { title: "My Post" },
+      },
+    });
 
-		const result = getRecordsByPath<{ title: string; id?: string }>(
-			"collections/blog/posts",
-			"post",
-		);
-		expect(result[0].id).toBe("my-post");
-	});
+    const result = getRecordsByPath<{ title: string; id?: string }>(
+      "collections/blog/posts",
+      "post",
+    );
+    expect(result[0].id).toBe("my-post");
+  });
 
-	it("returns empty array when no blocks match", () => {
-		mockLoadBlocks.mockReturnValue({
-			"collections/blog/categories/cat": {
-				name: "collections/blog/categories/cat",
-				category: { name: "Cat" },
-			},
-		});
+  it("returns empty array when no blocks match", () => {
+    mockLoadBlocks.mockReturnValue({
+      "collections/blog/categories/cat": {
+        name: "collections/blog/categories/cat",
+        category: { name: "Cat" },
+      },
+    });
 
-		const result = getRecordsByPath("collections/blog/posts", "post");
-		expect(result).toEqual([]);
-	});
+    const result = getRecordsByPath("collections/blog/posts", "post");
+    expect(result).toEqual([]);
+  });
 });

package/src/__tests__/seoSections.test.ts

@@ -0,0 +1,245 @@
+/**
+ * Scope: the JSON-LD and canonical output of the two SEO section loaders, plus
+ * the `utils/jsonLD.ts` mappers they delegate to. These are the whole reason
+ * the SEO sections exist, and none of it was reachable in this package before.
+ *
+ * Deliberately not covered: rendering the `Seo` component itself (that lives in
+ * `@decocms/apps-website`), and the schema/admin wiring.
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+import { configureBlog } from "../client";
+import { loader as seoPostLoader } from "../sections/Seo/SeoBlogPost";
+import { loader as seoListingLoader } from "../sections/Seo/SeoBlogPostListing";
+import type { BlogPost, BlogPostListingPage, BlogPostPage } from "../types";
+import { toBlogPosting, toBreadcrumbList, withCanonicalBase } from "../utils/jsonLD";
+
+const post = (overrides: Partial<BlogPost> = {}): BlogPost => ({
+  title: "How to brew",
+  slug: "how-to-brew",
+  date: "2024-06-01",
+  excerpt: "A guide",
+  ...overrides,
+});
+
+const page = (p: BlogPost): BlogPostPage => ({
+  "@type": "BlogPostPage",
+  post: p,
+  seo: { title: p.title, description: p.excerpt },
+});
+
+const req = (url = "https://shop.example/blog/coffee/how-to-brew?utm=x") => new Request(url);
+
+const nodesOf = (result: { jsonLDs?: unknown[] }) => (result.jsonLDs ?? []) as any[];
+
+beforeEach(() => {
+  configureBlog({});
+});
+
+describe("withCanonicalBase", () => {
+  it("strips query and hash, keeping origin + pathname", () => {
+    expect(withCanonicalBase("https://a.com/blog/x?q=1#frag")).toBe("https://a.com/blog/x");
+  });
+
+  it("swaps the origin for the configured canonical base", () => {
+    expect(withCanonicalBase("https://preview.a.com/blog/x?q=1", "https://www.a.com")).toBe(
+      "https://www.a.com/blog/x",
+    );
+  });
+
+  it("returns an unparseable relative URL unchanged when no base is configured", () => {
+    expect(withCanonicalBase("/blog/x")).toBe("/blog/x");
+  });
+});
+
+describe("toBlogPosting", () => {
+  it("emits the required BlogPosting fields", () => {
+    const node = toBlogPosting(post({ dateModified: "2024-07-01" }), "https://a.com/blog/x");
+    expect(node["@type"]).toBe("BlogPosting");
+    expect(node.headline).toBe("How to brew");
+    expect(node.datePublished).toBe("2024-06-01");
+    expect(node.dateModified).toBe("2024-07-01");
+    expect(node.mainEntityOfPage).toEqual({ "@type": "WebPage", "@id": "https://a.com/blog/x" });
+  });
+
+  it("omits `@context` — the Seo component adds it when serializing", () => {
+    expect("@context" in toBlogPosting(post())).toBe(false);
+  });
+
+  it("maps authors, defaulting the type to Person and scoping Person-only props", () => {
+    const node = toBlogPosting(
+      post({
+        authors: [
+          { name: "Ana", email: "a@b.com", jobTitle: "Barista", company: "Cafe" },
+          { name: "Acme", email: "c@d.com", type: "Organization", jobTitle: "ignored" },
+        ],
+      }),
+    );
+    expect(node.author).toEqual([
+      {
+        "@type": "Person",
+        name: "Ana",
+        jobTitle: "Barista",
+        worksFor: { "@type": "Organization", name: "Cafe" },
+      },
+      { "@type": "Organization", name: "Acme" },
+    ]);
+  });
+
+  it("emits the publisher as an Organization when configured", () => {
+    const node = toBlogPosting(post(), undefined, {
+      name: "Acme",
+      url: "https://a.com",
+      logo: "logo.png",
+    });
+    expect(node.publisher).toEqual({
+      "@type": "Organization",
+      name: "Acme",
+      url: "https://a.com",
+      logo: { "@type": "ImageObject", url: "logo.png" },
+    });
+  });
+
+  it("drops an aggregateRating stub that would fail the Rich Results Test", () => {
+    // ratingValue present but no count → invalid; and a bare @type stub → invalid.
+    expect(
+      toBlogPosting(post({ aggregateRating: { "@type": "AggregateRating" } })).aggregateRating,
+    ).toBeUndefined();
+    expect(
+      toBlogPosting(post({ aggregateRating: { "@type": "AggregateRating", ratingValue: 4 } }))
+        .aggregateRating,
+    ).toBeUndefined();
+    expect(
+      toBlogPosting(
+        post({ aggregateRating: { "@type": "AggregateRating", ratingValue: 4, ratingCount: 2 } }),
+      ).aggregateRating,
+    ).toEqual({ "@type": "AggregateRating", ratingValue: 4, ratingCount: 2 });
+  });
+
+  it("emits timeRequired only for a finite positive readTime", () => {
+    expect(toBlogPosting(post({ readTime: 7 })).timeRequired).toBe("PT7M");
+    expect(toBlogPosting(post({ readTime: 0 })).timeRequired).toBeUndefined();
+    expect(
+      toBlogPosting(post({ readTime: Number.POSITIVE_INFINITY })).timeRequired,
+    ).toBeUndefined();
+  });
+});
+
+describe("toBreadcrumbList", () => {
+  it("names segments from known categories and humanizes the rest", () => {
+    const node = toBreadcrumbList("https://a.com/blog/cold-brew/my-post", {
+      currentName: "My Post",
+      categories: [{ name: "Cold Brew Coffee", slug: "cold-brew" }],
+    });
+    expect(node.itemListElement).toEqual([
+      { "@type": "ListItem", position: 1, name: "Blog", item: "https://a.com/blog" },
+      {
+        "@type": "ListItem",
+        position: 2,
+        name: "Cold Brew Coffee",
+        item: "https://a.com/blog/cold-brew",
+      },
+      { "@type": "ListItem", position: 3, name: "My Post" },
+    ]);
+  });
+
+  it("omits `item` on the last entry, as Google allows", () => {
+    const node = toBreadcrumbList("https://a.com/blog/x", { currentName: "X" });
+    expect("item" in node.itemListElement[node.itemListElement.length - 1]).toBe(false);
+  });
+});
+
+describe("SeoBlogPost loader", () => {
+  it("emits BlogPosting + BreadcrumbList against the request URL", () => {
+    const result = seoPostLoader({ jsonLD: page(post()) }, req());
+    const [posting, breadcrumb] = nodesOf(result);
+    expect(posting["@type"]).toBe("BlogPosting");
+    expect(breadcrumb["@type"]).toBe("BreadcrumbList");
+    // Query string stripped for both canonical and JSON-LD.
+    expect(posting.url).toBe("https://shop.example/blog/coffee/how-to-brew");
+  });
+
+  it("rewrites the JSON-LD origin to the configured canonical base", () => {
+    configureBlog({ canonicalBaseUrl: "https://www.example.com" });
+    const [posting] = nodesOf(seoPostLoader({ jsonLD: page(post()) }, req()));
+    expect(posting.url).toBe("https://www.example.com/blog/coffee/how-to-brew");
+  });
+
+  it("includes the configured publisher", () => {
+    configureBlog({ publisher: { name: "Acme" } });
+    const [posting] = nodesOf(seoPostLoader({ jsonLD: page(post()) }, req()));
+    expect(posting.publisher).toEqual({ "@type": "Organization", name: "Acme" });
+  });
+
+  it("applies the site title/description templates", () => {
+    configureBlog({ seo: { titleTemplate: "%s | Acme", descriptionTemplate: "%s — read more" } });
+    const result = seoPostLoader({ jsonLD: page(post()) }, req());
+    expect(result.title).toBe("How to brew | Acme");
+    expect(result.description).toBe("A guide — read more");
+  });
+
+  it("prefers explicit overrides over the post's own seo", () => {
+    const result = seoPostLoader(
+      { jsonLD: page(post()), title: "Override", description: "Desc override" },
+      req(),
+    );
+    expect(result.title).toBe("Override");
+    expect(result.description).toBe("Desc override");
+  });
+
+  it("resolves a relative configured canonical against the request URL", () => {
+    const result = seoPostLoader(
+      { jsonLD: { ...page(post()), seo: { canonical: "/blog/canonical-path" } } },
+      req(),
+    );
+    expect(result.canonical).toBe("https://shop.example/blog/canonical-path");
+  });
+
+  it("noIndexes a null data source and emits no JSON-LD", () => {
+    const result = seoPostLoader({ jsonLD: null }, req());
+    expect(result.noIndexing).toBe(true);
+    expect(result.jsonLDs).toEqual([]);
+  });
+
+  it("propagates the post's own noIndexing — the draft-preview path", () => {
+    const result = seoPostLoader({ jsonLD: { ...page(post()), seo: { noIndexing: true } } }, req());
+    expect(result.noIndexing).toBe(true);
+  });
+});
+
+describe("SeoBlogPostListing loader", () => {
+  const listing = (overrides: Partial<BlogPostListingPage> = {}): BlogPostListingPage => ({
+    posts: [post({ slug: "a", title: "A" }), post({ slug: "b", title: "B" })],
+    pageInfo: { currentPage: 1, nextPage: undefined, previousPage: undefined },
+    seo: { title: "Coffee" },
+    ...overrides,
+  });
+
+  it("emits a Blog node listing every post, plus a BreadcrumbList", () => {
+    const [blog, breadcrumb] = nodesOf(
+      seoListingLoader({ jsonLD: listing() }, req("https://shop.example/blog/coffee")),
+    );
+    expect(blog["@type"]).toBe("Blog");
+    expect(blog.name).toBe("Coffee");
+    expect(blog.blogPost.map((p: { headline: string }) => p.headline)).toEqual(["A", "B"]);
+    expect(blog.mainEntityOfPage["@id"]).toBe("https://shop.example/blog/coffee");
+    expect(breadcrumb["@type"]).toBe("BreadcrumbList");
+  });
+
+  it("names the breadcrumb leaf after the active category", () => {
+    const [, breadcrumb] = nodesOf(
+      seoListingLoader(
+        { jsonLD: listing({ category: { name: "Cold Brew", slug: "cold-brew" } }) },
+        req("https://shop.example/blog/cold-brew"),
+      ),
+    );
+    const leaf = breadcrumb.itemListElement.at(-1);
+    expect(leaf.name).toBe("Cold Brew");
+  });
+
+  it("noIndexes a null data source", () => {
+    const result = seoListingLoader({ jsonLD: null }, req());
+    expect(result.noIndexing).toBe(true);
+    expect(result.jsonLDs).toEqual([]);
+  });
+});

package/src/actions/submitRating.ts

@@ -0,0 +1,36 @@
+import type { Person } from "@decocms/apps-commerce/types";
+import { logger, serializeError } from "@decocms/blocks/sdk/logger";
+import { getBlogRecordsAdapter } from "../core/blogRecords";
+import type { Rating } from "../types";
+
+export interface Props {
+  itemReviewed: string;
+  author: Person;
+  ratingValue: number;
+  additionalType?: string;
+}
+
+/**
+ * Records this author's rating for a post, replacing their previous one.
+ *
+ * The "one rating per author per item" rule lives in the adapter rather than
+ * here: the Deno app implemented it as a `select ... where itemReviewed = ? and
+ * (author like %email% or author like %@id%)` followed by an update, which is a
+ * query the site's schema owns. See `core/blogRecords.ts`.
+ *
+ * Returns `null` when no adapter is registered — ratings are opt-in.
+ */
+export default async function submitRating(props: Props): Promise<Rating | null> {
+  const upsert = getBlogRecordsAdapter()?.upsertRating;
+  if (!upsert) {
+    return null;
+  }
+
+  try {
+    return await upsert(props);
+  } catch (e) {
+    const error = serializeError(e);
+    logger.error(error.message, { error, scope: "blog/submitRating" });
+    return null;
+  }
+}

package/src/actions/submitReview.ts

@@ -0,0 +1,95 @@
+import type { Person } from "@decocms/apps-commerce/types";
+import { logger, serializeError } from "@decocms/blocks/sdk/logger";
+import { getBlogRecordsAdapter } from "../core/blogRecords";
+import { getReviewById } from "../core/records";
+import type { Review } from "../types";
+
+export interface Props {
+  action: "create" | "update";
+  id?: string;
+  reviewBody?: string;
+  reviewHeadline?: string;
+  itemReviewed?: string;
+  author?: Person;
+  /** Review status */
+  additionalType?: string;
+  isAnonymous?: boolean;
+}
+
+/**
+ * Creates or updates a review. Returns `null` when no adapter is registered, or
+ * when an update targets an id that doesn't exist.
+ */
+export default async function submitReview({
+  reviewBody,
+  reviewHeadline,
+  itemReviewed,
+  id,
+  author,
+  action,
+  additionalType,
+  isAnonymous,
+}: Props): Promise<Review | null> {
+  const adapter = getBlogRecordsAdapter();
+  if (!adapter) {
+    return null;
+  }
+
+  const isoDate = new Date().toISOString();
+
+  try {
+    if (action !== "create") {
+      if (!adapter.updateReview) {
+        return null;
+      }
+      // Read-before-write: the update is a partial patch, and the response has
+      // to carry the fields the caller didn't send (author, datePublished).
+      const storedReview = await getReviewById({ id });
+      if (!storedReview || !id) {
+        return null;
+      }
+      const updateRecord = {
+        additionalType: additionalType ?? storedReview.additionalType,
+        reviewHeadline: reviewHeadline ?? storedReview.reviewHeadline,
+        reviewBody: reviewBody ?? storedReview.reviewBody,
+        dateModified: isoDate,
+      };
+
+      const updated = await adapter.updateReview(id, updateRecord);
+
+      return (
+        updated ?? {
+          ...updateRecord,
+          "@type": "Review",
+          id,
+          itemReviewed: storedReview.itemReviewed,
+          author: author ?? storedReview.author,
+          datePublished: storedReview.datePublished,
+        }
+      );
+    }
+
+    if (!adapter.createReview) {
+      return null;
+    }
+
+    const insertData = {
+      itemReviewed,
+      isAnonymous,
+      author,
+      additionalType,
+      reviewHeadline,
+      reviewBody,
+      datePublished: isoDate,
+      dateModified: isoDate,
+    };
+
+    const created = await adapter.createReview(insertData);
+
+    return created ?? { "@type": "Review", ...insertData };
+  } catch (e) {
+    const error = serializeError(e);
+    logger.error(error.message, { error, scope: "blog/submitReview" });
+    return null;
+  }
+}

package/src/actions/submitView.ts

@@ -0,0 +1,28 @@
+import { logger, serializeError } from "@decocms/blocks/sdk/logger";
+import { getBlogRecordsAdapter } from "../core/blogRecords";
+
+export interface Props {
+  id: string;
+}
+
+/**
+ * Increments the view counter for a post, returning the new total.
+ *
+ * Returns `{ count: 0 }` when no adapter is registered: the caller is a
+ * fire-and-forget beacon on page view, so a site without the backend should get
+ * a well-formed response rather than an error.
+ */
+export default async function submitView({ id }: Props): Promise<{ count: number }> {
+  const increment = getBlogRecordsAdapter()?.incrementPostView;
+  if (!increment) {
+    return { count: 0 };
+  }
+
+  try {
+    return await increment(id);
+  } catch (e) {
+    const error = serializeError(e);
+    logger.error(error.message, { error, scope: "blog/submitView" });
+    return { count: 0 };
+  }
+}

package/src/client.ts

@@ -0,0 +1,70 @@
+/**
+ * Blog app singleton configuration.
+ *
+ * Holds what the Deno app carried on `AppContext` (`ctx.categorySlug`,
+ * `ctx.pageSlug`, `ctx.canonicalBaseUrl`, `ctx.publisher`, `ctx.seo`). Loaders
+ * and sections here take plain `(props, req?)`, so there is no `ctx` to read
+ * from — this module is the replacement, matching `configureWebsite` /
+ * `getWebsiteConfig` in `@decocms/apps-website`.
+ *
+ * Uses globalThis to survive Vite module duplication (optimized deps vs raw
+ * source imports can create separate module instances).
+ */
+
+import type { Publisher } from "./types";
+
+/**
+ * SEO defaults the blog's SEO sections fold into their output.
+ *
+ * Structurally a subset of `@decocms/apps-website`'s `WebsiteConfig["seo"]`,
+ * duplicated rather than imported so this stays a *type-only* relationship
+ * across the two apps — an `apps-*` package may not depend on another at
+ * runtime, and the website's own getter throws when unconfigured.
+ */
+export interface BlogSeoDefaults {
+  titleTemplate?: string;
+  descriptionTemplate?: string;
+  [key: string]: unknown;
+}
+
+export interface BlogConfig {
+  /**
+   * Slug pattern of the category route, e.g. `/blog/:category*`. Categories can
+   * nest, so the route must be a catch-all for subcategories to resolve.
+   */
+  categorySlug?: string;
+  /**
+   * Slug pattern of the post route, e.g. `/blog/:category*\/:slug`.
+   */
+  pageSlug?: string;
+  /**
+   * Overrides the origin of the url/mainEntityOfPage emitted in the JSON-LD by
+   * the SEO sections, which otherwise use the request host.
+   */
+  canonicalBaseUrl?: string;
+  /**
+   * Emitted as the publisher of the blog posts in the JSON-LD.
+   */
+  publisher?: Publisher;
+  /**
+   * Site-level SEO defaults (title/description templates and passthrough props).
+   */
+  seo?: BlogSeoDefaults;
+}
+
+const G = globalThis as unknown as { __decoBlogConfig?: BlogConfig };
+
+export function configureBlog(config: BlogConfig): void {
+  G.__decoBlogConfig = config;
+}
+
+/**
+ * Returns the blog config, or `{}` when the app was never configured.
+ *
+ * Deliberately non-throwing, unlike `getWebsiteConfig()`: every field here is
+ * optional and every consumer has a sensible default, so an unconfigured blog
+ * should render with request-derived canonicals rather than 500 the page.
+ */
+export function getBlogConfig(): BlogConfig {
+  return G.__decoBlogConfig ?? {};
+}