@xexr/blog-platform 1.0.10 → 1.0.11

package/README.md

@@ -237,7 +237,7 @@ export default async function ArticlePage({
 }
 ```
 
-> **Note**: The `navigation` prop is optional. You can omit `previousArticle` and `nextArticle` if you don't want article navigation links.
+> **Note**: The `navigation` prop is optional. You can omit `previousArticle` and `nextArticle` if you don't want article navigation links. Bloggy can also publish a site-scoped `newsletter` configuration; pass it through to `BlogHomePage` or `BlogArticlePage` if you are not using the article/site objects returned by Bloggy storage directly. The newsletter form posts back to Bloggy's `/api/newsletter/subscribe` endpoint so subscribers are captured consistently across host apps.
 
 **`app/blog/authors/[slug]/page.tsx`** - Author profile pages:
 

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

@@ -1,8 +1,11 @@
 import type { ReactElement } from "react";
-import type { PublishedArticle } from "../../../types/contracts";
+import type {
+  PublishedArticle,
+  PublishedNewsletterSettings,
+} from "../../../types/contracts";
 import type { BlogTheme } from "../../../lib/article-ui";
 
-interface ArticlePageProps {
+export interface ArticlePageProps {
   article: PublishedArticle;
   className?: string;
   navigation?: {
@@ -31,6 +34,8 @@ interface ArticlePageProps {
     href: string;
     label: string;
   };
+  newsletter?: PublishedNewsletterSettings;
+  newsletterPreviewMode?: boolean;
   relatedArticles?: PublishedArticle[];
   showShareLinks?: boolean;
 }

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

@@ -5,6 +5,7 @@ import { MDXRemote } from "next-mdx-remote-client/rsc";
 import {
   type PublishedArticle,
   type PublishedAuthor,
+  type PublishedNewsletterSettings,
 } from "../../../types/contracts";
 import { cn } from "../../../lib/utils";
 import { ArrowLeft, ArrowUpRight, Globe, Mail } from "lucide-react";
@@ -25,6 +26,7 @@ import {
   buildBlogPath,
   normalizeBlogBasePath,
 } from "../../../lib/urls";
+import { NewsletterSignup } from "../../../components/NewsletterSignup";
 import {
   type BlogTheme,
   extractTableOfContents,
@@ -32,7 +34,7 @@ import {
   getBlogThemeStyle,
 } from "../../../lib/article-ui";
 
-interface ArticlePageProps {
+export interface ArticlePageProps {
   article: PublishedArticle;
   className?: string;
   /** Optional navigation links */
@@ -65,6 +67,10 @@ interface ArticlePageProps {
     href: string;
     label: string;
   };
+  /** 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. */
   relatedArticles?: PublishedArticle[];
   /** Whether to render static article share links. */
@@ -133,6 +139,8 @@ export default function ArticlePage({
   basePath = "/blog",
   theme,
   postArticleCta,
+  newsletter,
+  newsletterPreviewMode = false,
   relatedArticles = [],
   showShareLinks = true,
 }: ArticlePageProps) {
@@ -146,6 +154,7 @@ export default function ArticlePage({
   const articleUrl =
     article.meta.canonicalUrl ??
     buildBlogPath(normalizedBasePath, article.slug);
+  const newsletterSettings = newsletter ?? article.site.newsletter;
 
   // Use the featured image URL provided by Bloggy (hosted on Bloggy's domain)
   const imageUrl = article.featuredImage;
@@ -431,11 +440,22 @@ export default function ArticlePage({
       )}
 
       {((postArticleCta ?? false) ||
+        (newsletterSettings?.enabled ?? false) ||
         showShareLinks ||
         relatedArticles.length > 0) && (
         <div className="mx-auto mt-12 max-w-4xl space-y-8">
           <Separator />
           {postArticleCta && <PostArticleCta cta={postArticleCta} />}
+          {newsletterSettings?.enabled && (
+            <NewsletterSignup
+              siteId={article.site.id}
+              settings={newsletterSettings}
+              sourceSurface="article"
+              sourceArticleSlug={article.slug}
+              sourceUrl={articleUrl}
+              previewMode={newsletterPreviewMode}
+            />
+          )}
           {showShareLinks && (
             <ArticleShareLinks title={article.title} url={articleUrl} />
           )}

package/dist/app/blog/page.d.ts

@@ -0,0 +1,59 @@
+import type { ReactElement } from "react";
+import type {
+  PublishedArticle,
+  PublishedNewsletterSettings,
+  PublishedSite,
+} from "../../types/contracts";
+import type { BlogTheme } from "../../lib/article-ui";
+
+export interface BlogHomePageProps {
+  articles: PublishedArticle[];
+  siteName?: string;
+  siteTagline?: string;
+  className?: string;
+  site?: PublishedSite;
+  includeStructuredData?: boolean;
+  basePath?: string;
+  pagination?: {
+    currentPage: number;
+    totalPages: number;
+    baseUrl?: string;
+  };
+  theme?: BlogTheme;
+  newsletter?: PublishedNewsletterSettings;
+  newsletterPreviewMode?: boolean;
+}
+
+export default function BlogHomePage(props: BlogHomePageProps): ReactElement;
+
+export function generateBlogHomeMetadata(
+  siteName?: string,
+  siteTagline?: string,
+  siteUrl?: string,
+  pagination?: {
+    currentPage: number;
+    totalPages: number;
+  },
+  basePath?: string,
+): {
+  title: string;
+  description: string;
+  openGraph: {
+    title: string;
+    description: string;
+    type: string;
+    url?: string;
+  };
+  twitter: {
+    card: string;
+    title: string;
+    description: string;
+  };
+  alternates: {
+    canonical?: string;
+  };
+  other: {
+    prev?: string;
+    next?: string;
+  };
+};

package/dist/app/blog/page.test.ts

@@ -0,0 +1,83 @@
+import React from "react";
+import { renderToPipeableStream } from "react-dom/server";
+import { PassThrough } from "stream";
+import { describe, expect, it } from "vitest";
+
+import BlogHomePage from "./page";
+import type { PublishedArticle } from "../../types/contracts";
+
+const article: PublishedArticle = {
+  id: "article-1",
+  slug: "useful-routines",
+  title: "Useful routines",
+  excerpt: "A practical guide to keeping routines useful.",
+  content: "Routines work best when they are easy to maintain.",
+  readingSeconds: 360,
+  wordCount: 900,
+  publishedAt: "2026-05-06T12:00:00.000Z",
+  updatedAt: "2026-05-07T12: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",
+  },
+  meta: {
+    canonicalUrl: "https://example.com/blog/useful-routines",
+    keywords: [],
+  },
+  version: 1,
+};
+
+describe("BlogHomePage", () => {
+  it("renders the newsletter form when configured", async () => {
+    const html = await renderToHtml(
+      React.createElement(BlogHomePage, {
+        articles: [article],
+        siteName: "Example Blog",
+        newsletter: {
+          enabled: true,
+          title: "Get product updates",
+          description: "Follow new articles and product notes.",
+          buttonLabel: "Get updates",
+          captureBaseUrl: "https://bloggy.example.com",
+          publicSubscribeToken: "public_subscribe_token",
+        },
+      }),
+    );
+
+    expect(html).toContain("Get product updates");
+    expect(html).toContain("Follow new articles and product notes.");
+    expect(html).toContain('type="email"');
+    expect(html).toContain('name="name"');
+    expect(html.indexOf("Get product updates")).toBeGreaterThan(
+      html.indexOf("Useful routines"),
+    );
+  });
+});
+
+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/page.tsx

@@ -4,6 +4,7 @@ import Image from "next/image";
 import {
   type PublishedArticle,
   type PublishedAuthor,
+  type PublishedNewsletterSettings,
   type PublishedSite,
 } from "../../types/contracts";
 import { cn } from "../../lib/utils";
@@ -19,6 +20,7 @@ import {
 } from "../../lib/urls";
 import { formatDistanceToNow } from "date-fns";
 import { type BlogTheme, getBlogThemeStyle } from "../../lib/article-ui";
+import { NewsletterSignup } from "../../components/NewsletterSignup";
 
 interface BlogHomePageProps {
   articles: PublishedArticle[];
@@ -39,6 +41,10 @@ interface BlogHomePageProps {
   };
   /** Optional theme values for host-site brand integration. */
   theme?: BlogTheme;
+  /** Optional Bloggy-owned newsletter capture configuration. */
+  newsletter?: PublishedNewsletterSettings;
+  /** Render interactive preview success without persisting subscribers. */
+  newsletterPreviewMode?: boolean;
 }
 
 /**
@@ -58,8 +64,12 @@ export default function BlogHomePage({
   basePath = "/blog",
   pagination,
   theme,
+  newsletter,
+  newsletterPreviewMode = false,
 }: BlogHomePageProps) {
   const normalizedBasePath = normalizeBlogBasePath(basePath) || "/";
+  const newsletterSettings = newsletter ?? site?.newsletter;
+  const newsletterSiteId = site?.id ?? articles[0]?.site.id;
 
   return (
     <div
@@ -119,6 +129,16 @@ export default function BlogHomePage({
         )}
       </main>
 
+      {newsletterSettings?.enabled && newsletterSiteId && (
+        <NewsletterSignup
+          siteId={newsletterSiteId}
+          settings={newsletterSettings}
+          sourceSurface="blog_home"
+          previewMode={newsletterPreviewMode}
+          className="mt-10 sm:mt-12"
+        />
+      )}
+
       {/* JSON-LD Structured Data */}
       {includeStructuredData &&
         site &&

package/dist/components/NewsletterSignup.tsx

@@ -0,0 +1,279 @@
+"use client";
+
+import { useState, useSyncExternalStore, type FormEvent } from "react";
+import { ArrowUpRight, Check } from "lucide-react";
+
+import { cn } from "../lib/utils";
+import type { PublishedNewsletterSettings } from "../types/contracts";
+
+export const NEWSLETTER_SUCCESS_MESSAGE =
+  "Thanks, you're on the list. We'll confirm before sending updates.";
+
+export interface NewsletterSignupProps {
+  siteId: string;
+  settings: PublishedNewsletterSettings;
+  sourceSurface: "blog_home" | "article";
+  sourceArticleSlug?: string;
+  sourceUrl?: string;
+  previewMode?: boolean;
+  className?: string;
+}
+
+export function NewsletterSignup({
+  siteId,
+  settings,
+  sourceSurface,
+  sourceArticleSlug,
+  sourceUrl,
+  previewMode = false,
+  className,
+}: NewsletterSignupProps) {
+  const [message, setMessage] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [hasSubmitted, setHasSubmitted] = useState(false);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const subscriptionKey = getSubscriptionStorageKey(siteId);
+  const hasStoredSubscribed = useSyncExternalStore(
+    subscribeToStoredSubscription,
+    () => hasStoredSubscription(subscriptionKey),
+    () => false,
+  );
+  const hasSubscribed = hasSubmitted || (!previewMode && hasStoredSubscribed);
+
+  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    setError(null);
+    setMessage(null);
+
+    const formData = new FormData(event.currentTarget);
+    const honeypot = getFormString(formData, "company");
+
+    if (previewMode) {
+      setMessage(NEWSLETTER_SUCCESS_MESSAGE);
+      setHasSubmitted(true);
+      event.currentTarget.reset();
+      return;
+    }
+
+    setIsSubmitting(true);
+    try {
+      const response = await fetch(
+        `${settings.captureBaseUrl.replace(/\/$/, "")}/api/newsletter/subscribe`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            siteId: Number(siteId),
+            publicSubscribeToken: settings.publicSubscribeToken,
+            email: getFormString(formData, "email"),
+            name: getOptionalFormString(formData, "name"),
+            sourceSurface,
+            sourceUrl: resolveSourceUrl(sourceUrl),
+            sourceArticleSlug: sourceArticleSlug ?? null,
+            honeypot,
+          }),
+        },
+      );
+
+      if (!response.ok) {
+        throw new Error("Newsletter signup failed.");
+      }
+
+      const result: unknown = await response.json().catch(() => null);
+      const successMessage =
+        getNewsletterResponseMessage(result) ?? NEWSLETTER_SUCCESS_MESSAGE;
+
+      storeSubscription(subscriptionKey);
+      setMessage(successMessage);
+      setHasSubmitted(true);
+      event.currentTarget.reset();
+    } catch {
+      setMessage(null);
+      setError("Newsletter signup failed. Please try again.");
+    } finally {
+      setIsSubmitting(false);
+    }
+  }
+
+  return (
+    <section
+      className={cn(
+        "border-y border-[var(--blog-accent-border)] py-5 sm:py-6",
+        className,
+      )}
+      aria-labelledby={`newsletter-${sourceSurface}-title`}
+    >
+      <div className="grid gap-4 lg:grid-cols-[minmax(0,0.9fr)_minmax(0,1.4fr)] lg:items-end">
+        <div className="max-w-xl space-y-1">
+          <h2
+            id={`newsletter-${sourceSurface}-title`}
+            className="text-base leading-6 font-semibold"
+          >
+            {settings.title}
+          </h2>
+          <p className="text-muted-foreground text-sm leading-6">
+            {settings.description}
+          </p>
+        </div>
+
+        {hasSubscribed ? (
+          <div
+            className="flex items-start gap-3 text-sm leading-6 text-emerald-500"
+            role="status"
+            aria-live="polite"
+          >
+            <span className="mt-0.5 inline-flex size-5 shrink-0 items-center justify-center rounded-full bg-emerald-500/15">
+              <Check className="size-3.5" aria-hidden="true" />
+            </span>
+            <p>{message ?? NEWSLETTER_SUCCESS_MESSAGE}</p>
+          </div>
+        ) : (
+          <form onSubmit={handleSubmit} className="space-y-3">
+            <div className="grid gap-2 sm:grid-cols-[minmax(0,0.8fr)_minmax(0,1fr)_auto]">
+              <label
+                className="sr-only"
+                htmlFor={`newsletter-name-${sourceSurface}`}
+              >
+                Name
+              </label>
+              <input
+                id={`newsletter-name-${sourceSurface}`}
+                name="name"
+                type="text"
+                autoComplete="name"
+                placeholder="Name"
+                className="border-input bg-background text-foreground placeholder:text-muted-foreground focus-visible:ring-ring min-h-10 rounded-md border px-3 py-2 text-sm focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none"
+              />
+
+              <label
+                className="sr-only"
+                htmlFor={`newsletter-email-${sourceSurface}`}
+              >
+                Email
+              </label>
+              <input
+                id={`newsletter-email-${sourceSurface}`}
+                name="email"
+                type="email"
+                autoComplete="email"
+                placeholder="Email address"
+                required
+                className="border-input bg-background text-foreground placeholder:text-muted-foreground focus-visible:ring-ring min-h-10 rounded-md border px-3 py-2 text-sm focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none"
+              />
+
+              <input
+                type="text"
+                name="company"
+                tabIndex={-1}
+                autoComplete="off"
+                aria-hidden="true"
+                className="hidden"
+              />
+
+              <button
+                type="submit"
+                disabled={isSubmitting}
+                className="inline-flex min-h-10 w-full shrink-0 items-center justify-center gap-2 rounded-full bg-[var(--blog-accent)] px-5 py-2 text-sm font-semibold text-white transition-opacity hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-60 sm:w-auto"
+              >
+                {isSubmitting ? "Submitting..." : settings.buttonLabel}
+                <ArrowUpRight className="size-4" aria-hidden="true" />
+              </button>
+            </div>
+
+            {error && <p className="text-sm text-red-600">{error}</p>}
+          </form>
+        )}
+      </div>
+    </section>
+  );
+}
+
+function resolveSourceUrl(sourceUrl: string | undefined): string | null {
+  if (sourceUrl?.startsWith("http://") || sourceUrl?.startsWith("https://")) {
+    return sourceUrl;
+  }
+
+  if (typeof window !== "undefined") {
+    return window.location.href;
+  }
+
+  return null;
+}
+
+function getFormString(formData: FormData, key: string): string {
+  const value = formData.get(key);
+  return typeof value === "string" ? value : "";
+}
+
+function getOptionalFormString(formData: FormData, key: string): string | null {
+  const value = getFormString(formData, key).trim();
+  if (value.length === 0) {
+    return null;
+  }
+
+  return value;
+}
+
+function getSubscriptionStorageKey(siteId: string): string {
+  return `bloggy_newsletter_subscribed_${siteId}`;
+}
+
+function hasStoredSubscription(key: string): boolean {
+  if (typeof window === "undefined") {
+    return false;
+  }
+
+  try {
+    if (window.localStorage.getItem(key) === "true") {
+      return true;
+    }
+  } catch {
+    // Ignore storage failures; the subscription API remains the source of truth.
+  }
+
+  if (typeof document === "undefined") {
+    return false;
+  }
+
+  return document.cookie
+    .split(";")
+    .some((cookie) => cookie.trim().startsWith(`${key}=true`));
+}
+
+function storeSubscription(key: string): void {
+  if (typeof window !== "undefined") {
+    try {
+      window.localStorage.setItem(key, "true");
+    } catch {
+      // Ignore storage failures; users can still submit normally.
+    }
+  }
+
+  if (typeof document !== "undefined") {
+    document.cookie = `${key}=true; Max-Age=31536000; Path=/; SameSite=Lax`;
+  }
+}
+
+function subscribeToStoredSubscription(callback: () => void): () => void {
+  if (typeof window === "undefined") {
+    return () => undefined;
+  }
+
+  window.addEventListener("storage", callback);
+  return () => window.removeEventListener("storage", callback);
+}
+
+function getNewsletterResponseMessage(value: unknown): string | null {
+  if (
+    value &&
+    typeof value === "object" &&
+    "message" in value &&
+    typeof value.message === "string"
+  ) {
+    return value.message;
+  }
+
+  return null;
+}