@xexr/blog-platform 1.0.15 → 1.0.17

package/dist/app/blog/[slug]/page.d.ts

@@ -1,6 +1,7 @@
 import type { ReactElement } from "react";
 import type {
   PublishedArticle,
+  PublishedArticleCta,
   PublishedNewsletterSettings,
 } from "../../../types/contracts";
 import type { BlogTheme } from "../../../lib/article-ui";
@@ -28,14 +29,10 @@ export interface ArticlePageProps {
   };
   basePath?: string;
   theme?: BlogTheme;
-  postArticleCta?: {
-    title: string;
-    description?: string;
-    href: string;
-    label: string;
-  };
+  postArticleCta?: PublishedArticleCta;
   newsletter?: PublishedNewsletterSettings;
   newsletterPreviewMode?: boolean;
+  articles?: PublishedArticle[];
   relatedArticles?: PublishedArticle[];
   showShareLinks?: boolean;
 }

package/dist/app/blog/[slug]/page.mdx-security.test.ts

@@ -0,0 +1,135 @@
+import React from "react";
+import { renderToPipeableStream } from "react-dom/server";
+import { PassThrough } from "stream";
+import { describe, expect, it } from "vitest";
+
+import ArticlePage from "./page";
+import type { PublishedArticle } from "../../../types/contracts";
+
+const article: PublishedArticle = {
+  id: "article-security",
+  slug: "mdx-security",
+  title: "MDX security",
+  excerpt: "Renderer hardening fixtures.",
+  content: "Safe content.",
+  readingSeconds: 60,
+  wordCount: 120,
+  publishedAt: "2026-05-13T09:00:00.000Z",
+  updatedAt: "2026-05-13T09:00:00.000Z",
+  author: null,
+  site: {
+    id: "site-1",
+    name: "Example Blog",
+    tagline: "Useful writing",
+    description: "Articles about useful systems.",
+    domain: "example.com",
+    toneAdjectives: [],
+    locale: "en",
+  },
+  topics: [],
+  meta: {
+    canonicalUrl: "https://example.com/blog/mdx-security",
+    keywords: [],
+  },
+  version: 1,
+};
+
+describe("ArticlePage MDX security", () => {
+  it("renders expected markdown and figure HTML through the real article renderer", async () => {
+    const html = await renderToHtml(
+      React.createElement(ArticlePage, {
+        article: {
+          ...article,
+          content: [
+            "## Safe section",
+            "",
+            "<figure>",
+            "",
+            "![Dashboard](https://example.com/dashboard.png)",
+            "",
+            '<figcaption>Dashboard caption <span class="blog-image-credit">Credit: Example</span></figcaption>',
+            "",
+            "</figure>",
+            "",
+            "[Read more](https://example.com/read-more)",
+          ].join("\n"),
+        },
+        showShareLinks: false,
+      }),
+    );
+
+    expect(html).toContain("Safe section");
+    expect(html).toContain("<figure>");
+    expect(html).toContain("<figcaption>");
+    expect(html).toContain("Dashboard caption");
+    expect(html).toContain('src="https://example.com/dashboard.png"');
+    expect(html).toContain('href="https://example.com/read-more"');
+  });
+
+  it("removes executable raw HTML and unsafe URL protocols from rendered articles", async () => {
+    const html = await renderToHtml(
+      React.createElement(ArticlePage, {
+        article: {
+          ...article,
+          content: [
+            "Safe paragraph.",
+            "",
+            "<script>alert('script')</script>",
+            '<img src="https://example.com/safe.png" onerror="alert(1)" alt="event handler" />',
+            '<a href="javascript:alert(2)">unsafe link</a>',
+            '<img src="data:text/html,<script>alert(3)</script>" alt="data url" />',
+            '<iframe src="https://example.com/embed"></iframe>',
+            '<object data="https://example.com/payload"></object>',
+            '<embed src="https://example.com/payload" />',
+          ].join("\n"),
+        },
+        showShareLinks: false,
+      }),
+    );
+
+    const articleBodyHtml = extractArticleBodyHtml(html);
+
+    expect(articleBodyHtml).toContain("Safe paragraph.");
+    expect(articleBodyHtml).toContain("unsafe link");
+    expect(articleBodyHtml).not.toContain("<script");
+    expect(articleBodyHtml).not.toContain("onerror");
+    expect(articleBodyHtml).not.toContain("javascript:");
+    expect(articleBodyHtml).not.toContain("data:text/html");
+    expect(articleBodyHtml).not.toContain("<iframe");
+    expect(articleBodyHtml).not.toContain("<object");
+    expect(articleBodyHtml).not.toContain("<embed");
+  });
+});
+
+function extractArticleBodyHtml(html: string): string {
+  const start = html.indexOf('id="article-body"');
+  const end = html.indexOf('<script type="application/ld+json"', start);
+
+  if (start === -1) {
+    throw new Error("Article body not found in rendered HTML");
+  }
+
+  return end === -1 ? html.slice(start) : html.slice(start, end);
+}
+
+function renderToHtml(element: React.ReactElement): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let html = "";
+    const stream = new PassThrough();
+    stream.setEncoding("utf8");
+    stream.on("data", (chunk: string) => {
+      html += chunk;
+    });
+    stream.on("end", () => resolve(html));
+    stream.on("error", reject);
+
+    const { pipe } = renderToPipeableStream(element, {
+      onAllReady() {
+        pipe(stream);
+      },
+      onError(error) {
+        reject(error instanceof Error ? error : new Error(String(error)));
+      },
+    });
+  });
+}

package/dist/app/blog/[slug]/page.tsx

@@ -4,6 +4,7 @@ import Link from "next/link";
 import { MDXRemote } from "next-mdx-remote-client/rsc";
 import {
   type PublishedArticle,
+  type PublishedArticleCta,
   type PublishedAuthor,
   type PublishedNewsletterSettings,
 } from "../../../types/contracts";
@@ -34,6 +35,7 @@ import {
   formatArticleDateMeta,
   getBlogThemeStyle,
 } from "../../../lib/article-ui";
+import { getRelatedFeaturedArticles } from "../../../lib/related-articles";
 
 export interface ArticlePageProps {
   article: PublishedArticle;
@@ -62,17 +64,14 @@ export interface ArticlePageProps {
   /** Optional theme values for host-site brand integration. */
   theme?: BlogTheme;
   /** Optional post-article CTA supplied by the host site. */
-  postArticleCta?: {
-    title: string;
-    description?: string;
-    href: string;
-    label: string;
-  };
+  postArticleCta?: PublishedArticleCta;
   /** Optional Bloggy-owned newsletter capture configuration. */
   newsletter?: PublishedNewsletterSettings;
   /** Render interactive preview success without persisting subscribers. */
   newsletterPreviewMode?: boolean;
-  /** Optional related articles supplied by the host site. */
+  /** All available articles used to derive topic-first related articles. */
+  articles?: PublishedArticle[];
+  /** Optional pre-ranked related articles supplied by the host site. */
   relatedArticles?: PublishedArticle[];
   /** Whether to render static article share links. */
   showShareLinks?: boolean;
@@ -142,6 +141,7 @@ export default function ArticlePage({
   postArticleCta,
   newsletter,
   newsletterPreviewMode = false,
+  articles = [],
   relatedArticles = [],
   showShareLinks = true,
 }: ArticlePageProps) {
@@ -156,6 +156,7 @@ export default function ArticlePage({
     article.meta.canonicalUrl ??
     buildBlogPath(normalizedBasePath, article.slug);
   const newsletterSettings = newsletter ?? article.site.newsletter;
+  const articleCta = postArticleCta ?? article.cta;
 
   // Use the featured image URL provided by Bloggy (hosted on Bloggy's domain)
   const imageUrl = article.featuredImage;
@@ -164,6 +165,10 @@ export default function ArticlePage({
       article.featuredImageCreditText ??
       article.featuredImageCreditUrl,
   );
+  const resolvedRelatedArticles =
+    relatedArticles.length > 0
+      ? relatedArticles.slice(0, 3)
+      : getRelatedFeaturedArticles(article, articles);
 
   return (
     <article
@@ -445,13 +450,13 @@ export default function ArticlePage({
         </div>
       )}
 
-      {((postArticleCta ?? false) ||
+      {((articleCta ?? false) ||
         (newsletterSettings?.enabled ?? false) ||
         showShareLinks ||
-        relatedArticles.length > 0) && (
+        resolvedRelatedArticles.length > 0) && (
         <div className="mx-auto mt-12 max-w-4xl space-y-8">
           <Separator />
-          {postArticleCta && <PostArticleCta cta={postArticleCta} />}
+          {articleCta && <PostArticleCta cta={articleCta} />}
           {newsletterSettings?.enabled && (
             <NewsletterSignup
               siteId={article.site.id}
@@ -465,9 +470,9 @@ export default function ArticlePage({
           {showShareLinks && (
             <ArticleShareLinks title={article.title} url={articleUrl} />
           )}
-          {relatedArticles.length > 0 && (
+          {resolvedRelatedArticles.length > 0 && (
             <RelatedArticles
-              articles={relatedArticles.slice(0, 3)}
+              articles={resolvedRelatedArticles}
               basePath={normalizedBasePath}
             />
           )}
@@ -707,13 +712,26 @@ function PostArticleCta({
             </p>
           )}
         </div>
-        <Link
-          href={cta.href}
-          className="inline-flex shrink-0 items-center justify-center gap-2 rounded-full bg-[var(--blog-accent)] px-4 py-2 text-sm font-semibold text-white transition-opacity hover:opacity-90"
-        >
-          {cta.label}
-          <ArrowUpRight className="size-4" aria-hidden="true" />
-        </Link>
+        <div className="flex shrink-0 flex-col gap-2 sm:flex-row">
+          {cta.primary && (
+            <Link
+              href={cta.primary.href}
+              className="inline-flex items-center justify-center gap-2 rounded-full bg-[var(--blog-accent)] px-4 py-2 text-sm font-semibold text-white transition-opacity hover:opacity-90"
+            >
+              {cta.primary.label}
+              <ArrowUpRight className="size-4" aria-hidden="true" />
+            </Link>
+          )}
+          {cta.secondary && (
+            <Link
+              href={cta.secondary.href}
+              className="border-border bg-background text-foreground hover:bg-muted inline-flex items-center justify-center gap-2 rounded-full border px-4 py-2 text-sm font-semibold transition-colors"
+            >
+              {cta.secondary.label}
+              <ArrowUpRight className="size-4" aria-hidden="true" />
+            </Link>
+          )}
+        </div>
       </div>
     </div>
   );

package/dist/index-Dr8HaKGm.d.mts

@@ -0,0 +1,229 @@
+/**
+ * Public API contracts for the @xexr/blog-platform package.
+ *
+ * These types define the public interface between Bloggy and external blog platforms.
+ * They must remain stable and backward-compatible to ensure smooth upgrades.
+ *
+ * IMPORTANT: These contracts should never import from the main Bloggy application
+ * to maintain clean separation of concerns and prevent coupling.
+ */
+/**
+ * Public profile and social links for an author.
+ */
+interface PublishedAuthorSocialLinks {
+    /** Author website or profile URL */
+    readonly website?: string;
+    /** X/Twitter profile URL */
+    readonly x?: string;
+    /** Legacy Twitter profile URL */
+    readonly twitter?: string;
+    /** LinkedIn profile URL */
+    readonly linkedin?: string;
+    /** GitHub profile URL */
+    readonly github?: string;
+    /** Public contact email address */
+    readonly email?: string;
+}
+/**
+ * Represents a published author with essential information for bylines and attribution.
+ */
+interface PublishedAuthor {
+    /** Unique identifier for the author */
+    readonly id: string;
+    /** Author's full name */
+    readonly name: string;
+    /** URL-friendly slug for author pages */
+    readonly slug: string;
+    /** Author's bio/description (optional) */
+    readonly bio?: string;
+    /** Author avatar image URL (optional) */
+    readonly avatarUrl?: string;
+    /** Public profile and social links (optional) */
+    readonly socialLinks?: PublishedAuthorSocialLinks;
+    /** Pronouns for proper attribution */
+    readonly pronouns?: string;
+    /** Whether this is a guest author */
+    readonly isGuest: boolean;
+    /** Tone adjectives that describe this author's writing style */
+    readonly toneAdjectives: readonly string[];
+}
+/**
+ * Represents a published site with essential metadata for blog rendering.
+ */
+interface PublishedSite {
+    /** Unique identifier for the site */
+    readonly id: string;
+    /** Site name/title */
+    readonly name: string;
+    /** Site tagline/subtitle */
+    readonly tagline: string;
+    /** Site description */
+    readonly description: string;
+    /** Primary domain for the site */
+    readonly domain: string;
+    /** Site-wide tone adjectives for content context */
+    readonly toneAdjectives: readonly string[];
+    /** Default locale/language code */
+    readonly locale: string;
+    /** Optional Bloggy-owned newsletter capture configuration */
+    readonly newsletter?: PublishedNewsletterSettings;
+}
+/**
+ * Public configuration for Bloggy-owned newsletter capture.
+ */
+interface PublishedNewsletterSettings {
+    /** Whether the capture form should render */
+    readonly enabled: boolean;
+    /** Form heading */
+    readonly title: string;
+    /** Form supporting copy */
+    readonly description: string;
+    /** Submit button label */
+    readonly buttonLabel: string;
+    /** Base URL for the Bloggy instance that receives subscriptions */
+    readonly captureBaseUrl: string;
+    /** Site-scoped public token used to validate public submissions */
+    readonly publicSubscribeToken: string;
+}
+/**
+ * Public post-article CTA configuration.
+ */
+interface PublishedArticleCta {
+    /** CTA heading */
+    readonly title: string;
+    /** Optional supporting copy */
+    readonly description?: string;
+    /** Primary sign-up action */
+    readonly primary?: PublishedArticleCtaAction;
+    /** Secondary learn-more action */
+    readonly secondary?: PublishedArticleCtaAction;
+}
+/**
+ * Public post-article CTA link.
+ */
+interface PublishedArticleCtaAction {
+    /** Button label */
+    readonly label: string;
+    /** Safe http(s) URL or same-site relative path */
+    readonly href: string;
+}
+/**
+ * Public topic/category taxonomy assigned to published articles.
+ */
+interface PublishedTopic {
+    /** Unique identifier for the topic */
+    readonly id: string;
+    /** Display name */
+    readonly name: string;
+    /** URL-friendly slug for topic archive routing */
+    readonly slug: string;
+    /** Optional public description */
+    readonly description?: string;
+    /** Whether this is the article's primary topic */
+    readonly isPrimary: boolean;
+}
+/**
+ * Represents a published article with all necessary metadata for rendering
+ * on external blog platforms.
+ */
+interface PublishedArticle {
+    /** Unique identifier for the article */
+    readonly id: string;
+    /** URL-friendly slug for routing */
+    readonly slug: string;
+    /** Article title/headline */
+    readonly title: string;
+    /** Brief excerpt/summary for meta descriptions and previews */
+    readonly excerpt: string;
+    /** Full article content in markdown format */
+    readonly content: string;
+    /** Estimated reading time in seconds */
+    readonly readingSeconds: number;
+    /** Word count for analytics */
+    readonly wordCount: number;
+    /** Publication date as ISO 8601 string */
+    readonly publishedAt: string;
+    /** Last updated date as ISO 8601 string */
+    readonly updatedAt: string;
+    /** Author information (can be null for anonymous posts) */
+    readonly author: PublishedAuthor | null;
+    /** Site information */
+    readonly site: PublishedSite;
+    /** Optional post-article call-to-action */
+    readonly cta?: PublishedArticleCta;
+    /** Public topic taxonomy assigned to the article */
+    readonly topics?: readonly PublishedTopic[];
+    /** Featured image URL (optional) */
+    readonly featuredImage?: string;
+    /** Alt text for featured image */
+    readonly featuredImageAlt?: string;
+    /** Caption displayed with the featured image */
+    readonly featuredImageCaption?: string;
+    /** Credit text displayed with the featured image */
+    readonly featuredImageCreditText?: string;
+    /** Optional URL for the featured image credit */
+    readonly featuredImageCreditUrl?: string;
+    /** Featured image R2 key for CDN optimization (optional) */
+    readonly featuredImageKey?: string;
+    /** SEO meta tags */
+    readonly meta: {
+        /** Meta title (defaults to article title if not provided) */
+        readonly title?: string;
+        /** Meta description (defaults to excerpt if not provided) */
+        readonly description?: string;
+        /** Canonical URL for SEO */
+        readonly canonicalUrl?: string;
+        /** Keywords for SEO */
+        readonly keywords: readonly string[];
+        /** Open Graph image URL */
+        readonly ogImage?: string;
+    };
+    /** Article version for optimistic locking */
+    readonly version: number;
+}
+/**
+ * Payload structure for publishing operations.
+ * Used when sending publish/unpublish requests to blog platforms.
+ */
+interface PublishPayload {
+    /** The article to publish */
+    readonly article: PublishedArticle;
+    /** Idempotency key to prevent duplicate operations */
+    readonly idempotencyKey: string;
+    /** Optional slug override (defaults to article.slug) */
+    readonly slug?: string;
+    /** Optional meta description override (defaults to article.excerpt) */
+    readonly metaDescription?: string;
+    /** Platform-specific configuration */
+    readonly platformConfig?: Record<string, unknown>;
+    /** Whether this is a dry run (validation only) */
+    readonly dryRun?: boolean;
+}
+/**
+ * Result structure returned from publishing operations.
+ */
+interface PublishResult {
+    /** Whether the operation was successful */
+    readonly success: boolean;
+    /** The published article URL if successful */
+    readonly url?: string;
+    /** Platform-specific post ID */
+    readonly platformPostId?: string;
+    /** Publication timestamp as ISO 8601 string */
+    readonly publishedAt?: string;
+    /** Error information if unsuccessful */
+    readonly error?: {
+        /** Error code (PUB001-PUB011) */
+        readonly code: string;
+        /** Human-readable error message */
+        readonly message: string;
+        /** Additional error details */
+        readonly details?: Record<string, unknown>;
+    };
+    /** Validation warnings (for dry runs or minor issues) */
+    readonly warnings?: readonly string[];
+    /** Idempotency key used for this operation */
+    readonly idempotencyKey: string;
+}
+
+export type { PublishedTopic as P, PublishedArticle as a, PublishedSite as b, PublishedAuthor as c, PublishedNewsletterSettings as d, PublishedArticleCta as e, PublishResult as f, PublishPayload as g, PublishedAuthorSocialLinks as h };