@xexr/blog-platform 1.0.7 → 1.0.8

package/dist/lib/structured-data.ts

@@ -0,0 +1,608 @@
+/**
+ * Structured Data (JSON-LD) utilities for SEO optimization
+ *
+ * This module provides comprehensive schema.org structured data generation
+ * for blog articles, authors, and organizations. It follows Google's
+ * recommended guidelines for structured data markup.
+ *
+ * @see https://developers.google.com/search/docs/appearance/structured-data
+ * @see https://schema.org/
+ */
+
+import type {
+  PublishedArticle,
+  PublishedAuthor,
+  PublishedSite,
+} from "../types/contracts";
+
+/**
+ * Base schema.org context and type
+ */
+interface BaseStructuredData {
+  "@context": "https://schema.org";
+  "@type": string;
+  "@id"?: string;
+}
+
+/**
+ * Person schema for authors
+ * @see https://schema.org/Person
+ */
+export interface PersonSchema extends BaseStructuredData {
+  "@type": "Person";
+  name: string;
+  description?: string;
+  identifier?: string;
+  image?: string;
+  url?: string;
+  sameAs?: string[];
+  jobTitle?: string;
+  affiliation?: OrganizationSchema;
+  knowsAbout?: string[];
+  additionalType?: string;
+}
+
+/**
+ * Organization schema for blog sites
+ * @see https://schema.org/Organization
+ */
+export interface OrganizationSchema extends BaseStructuredData {
+  "@type": "Organization";
+  name: string;
+  description?: string;
+  url?: string;
+  logo?: string;
+  sameAs?: string[];
+  foundingDate?: string;
+  location?: string;
+  contactPoint?: {
+    "@type": "ContactPoint";
+    contactType: string;
+    url?: string;
+    email?: string;
+  };
+}
+
+/**
+ * BlogPosting schema for articles
+ * @see https://schema.org/BlogPosting
+ */
+export interface BlogPostingSchema extends BaseStructuredData {
+  "@type": "BlogPosting";
+  headline: string;
+  description?: string;
+  image?: string | string[];
+  datePublished: string;
+  dateModified?: string;
+  author?: PersonSchema | PersonSchema[];
+  publisher: OrganizationSchema;
+  mainEntityOfPage: {
+    "@type": "WebPage";
+    "@id": string;
+  };
+  keywords?: string | string[];
+  wordCount?: number;
+  timeRequired?: string; // ISO 8601 duration format (PT5M = 5 minutes)
+  inLanguage?: string;
+  isAccessibleForFree?: boolean;
+  genre?: string | string[];
+  about?: {
+    "@type": "Thing";
+    name: string;
+  }[];
+  mentions?: {
+    "@type": "Thing";
+    name: string;
+  }[];
+}
+
+/**
+ * WebSite schema for the blog home page
+ * @see https://schema.org/WebSite
+ */
+export interface WebSiteSchema extends BaseStructuredData {
+  "@type": "WebSite";
+  name: string;
+  description?: string;
+  url: string;
+  publisher: OrganizationSchema;
+  inLanguage?: string;
+  potentialAction?: {
+    "@type": "SearchAction";
+    target: {
+      "@type": "EntryPoint";
+      urlTemplate: string;
+    };
+    "query-input": string;
+  };
+}
+
+/**
+ * BreadcrumbList schema for navigation
+ * @see https://schema.org/BreadcrumbList
+ */
+export interface BreadcrumbListSchema extends BaseStructuredData {
+  "@type": "BreadcrumbList";
+  itemListElement: {
+    "@type": "ListItem";
+    position: number;
+    name: string;
+    item: string;
+  }[];
+}
+
+/**
+ * Options for customizing structured data generation
+ */
+export interface StructuredDataOptions {
+  /** Include optional properties like keywords, mentions, etc. */
+  includeOptionalProperties?: boolean;
+  /** Include search action in WebSite schema */
+  includeSearchAction?: boolean;
+  /** Custom domain override for URLs */
+  customDomain?: string;
+  /** Path prefix for blog URLs (e.g., '/blog', '/articles') */
+  pathPrefix?: string;
+  /** Language code (e.g., 'en-US') */
+  language?: string;
+  /** Whether content is free to access */
+  isAccessibleForFree?: boolean;
+}
+
+/**
+ * Generate comprehensive structured data for a blog article
+ */
+export function generateArticleStructuredData(
+  article: PublishedArticle,
+  options: StructuredDataOptions = {},
+): BlogPostingSchema {
+  const {
+    customDomain,
+    pathPrefix = "/blog",
+    language,
+    isAccessibleForFree = true,
+    includeOptionalProperties = true,
+  } = options;
+
+  const domain = customDomain ?? article.site.domain;
+  const canonicalUrl = customDomain
+    ? `https://${domain}${pathPrefix}/${article.slug}`
+    : (article.meta.canonicalUrl ??
+      `https://${domain}${pathPrefix}/${article.slug}`);
+
+  // Generate author schema
+  const authorSchema = article.author
+    ? generateAuthorStructuredData(article.author, { customDomain, pathPrefix })
+    : undefined;
+
+  // Generate publisher schema
+  const publisherSchema = generateOrganizationStructuredData(article.site, {
+    customDomain,
+    pathPrefix,
+  });
+
+  // Convert reading seconds to ISO 8601 duration
+  const readingMinutes = Math.max(1, Math.ceil(article.readingSeconds / 60));
+  const timeRequired = `PT${readingMinutes}M`;
+
+  const schema: BlogPostingSchema = {
+    "@context": "https://schema.org",
+    "@type": "BlogPosting",
+    "@id": `${canonicalUrl}#article`,
+    headline: article.title,
+    description: article.excerpt,
+    datePublished: article.publishedAt,
+    dateModified: article.updatedAt,
+    author: authorSchema,
+    publisher: publisherSchema,
+    mainEntityOfPage: {
+      "@type": "WebPage",
+      "@id": canonicalUrl,
+    },
+    wordCount: article.wordCount,
+    timeRequired,
+    isAccessibleForFree,
+  };
+
+  // Add optional properties if enabled
+  if (includeOptionalProperties) {
+    // Featured image
+    if (article.featuredImage) {
+      schema.image = article.featuredImage;
+    }
+
+    // Keywords
+    if (article.meta.keywords.length > 0) {
+      schema.keywords = [...article.meta.keywords];
+    }
+
+    // Language
+    if (language ?? article.site.locale) {
+      schema.inLanguage = language ?? article.site.locale;
+    }
+
+    // Extract topics from tone adjectives or keywords for 'about' property
+    if (article.site.toneAdjectives.length > 0) {
+      schema.about = article.site.toneAdjectives.map((topic) => ({
+        "@type": "Thing" as const,
+        name: topic,
+      }));
+    }
+
+    // Genre based on site description or tone
+    if (article.site.toneAdjectives.length > 0) {
+      schema.genre = [...article.site.toneAdjectives];
+    }
+  }
+
+  return schema;
+}
+
+/**
+ * Generate structured data for an author
+ */
+export function generateAuthorStructuredData(
+  author: PublishedAuthor,
+  options: StructuredDataOptions = {},
+): PersonSchema {
+  const { customDomain, pathPrefix = "/blog" } = options;
+
+  const schema: PersonSchema = {
+    "@context": "https://schema.org",
+    "@type": "Person",
+    "@id": `#author-${author.id}`,
+    name: author.name,
+    identifier: author.id,
+  };
+
+  // Add optional properties
+  if (author.bio) {
+    schema.description = author.bio;
+  }
+
+  if (author.avatarUrl) {
+    schema.image = author.avatarUrl;
+  }
+
+  const sameAs = [
+    author.socialLinks?.website,
+    author.socialLinks?.x,
+    author.socialLinks?.linkedin,
+    author.socialLinks?.github,
+  ].filter((url): url is string => Boolean(url));
+
+  if (sameAs.length > 0) {
+    schema.sameAs = sameAs;
+  }
+
+  if (author.slug?.trim()) {
+    const authorUrl = customDomain
+      ? `https://${customDomain}${pathPrefix}/authors/${author.slug}`
+      : `${pathPrefix}/authors/${author.slug}`;
+    schema.url = authorUrl;
+  }
+
+  // Additional type for guest authors
+  if (author.isGuest) {
+    schema.additionalType = "GuestAuthor";
+  }
+
+  // Add knowledge areas from tone adjectives
+  if (author.toneAdjectives && author.toneAdjectives.length > 0) {
+    schema.knowsAbout = [...author.toneAdjectives];
+  }
+
+  return schema;
+}
+
+/**
+ * Generate structured data for a blog site organization
+ */
+export function generateOrganizationStructuredData(
+  site: PublishedSite,
+  options: StructuredDataOptions = {},
+): OrganizationSchema {
+  const { customDomain, pathPrefix = "/blog" } = options;
+
+  const domain = customDomain ?? site.domain;
+  const siteUrl = `https://${domain}${pathPrefix}`;
+
+  const schema: OrganizationSchema = {
+    "@context": "https://schema.org",
+    "@type": "Organization",
+    "@id": `${siteUrl}#organization`,
+    name: site.name,
+    url: siteUrl,
+  };
+
+  // Add optional properties
+  if (site.description?.trim()) {
+    schema.description = site.description;
+  }
+
+  if (site.tagline?.trim()) {
+    schema.description = schema.description
+      ? `${schema.description}. ${site.tagline}`
+      : site.tagline;
+  }
+
+  return schema;
+}
+
+/**
+ * Generate structured data for the blog website
+ */
+export function generateWebSiteStructuredData(
+  site: PublishedSite,
+  options: StructuredDataOptions = {},
+): WebSiteSchema {
+  const {
+    customDomain,
+    pathPrefix = "/blog",
+    language,
+    includeSearchAction = true,
+  } = options;
+
+  const domain = customDomain ?? site.domain;
+  const siteUrl = `https://${domain}${pathPrefix}`;
+
+  const publisherSchema = generateOrganizationStructuredData(site, options);
+
+  const schema: WebSiteSchema = {
+    "@context": "https://schema.org",
+    "@type": "WebSite",
+    "@id": `${siteUrl}#website`,
+    name: site.name,
+    url: siteUrl,
+    publisher: publisherSchema,
+  };
+
+  // Add optional properties
+  if (site.description?.trim()) {
+    schema.description = site.description;
+  }
+
+  if (language ?? site.locale) {
+    schema.inLanguage = language ?? site.locale;
+  }
+
+  // Add search action for better search engine integration
+  if (includeSearchAction) {
+    schema.potentialAction = {
+      "@type": "SearchAction",
+      target: {
+        "@type": "EntryPoint",
+        urlTemplate: `${siteUrl}?search={search_term_string}`,
+      },
+      "query-input": "required name=search_term_string",
+    };
+  }
+
+  return schema;
+}
+
+/**
+ * Generate breadcrumb structured data for navigation
+ */
+export function generateBreadcrumbStructuredData(
+  breadcrumbs: Array<{ name: string; url: string }>,
+  options: StructuredDataOptions = {},
+): BreadcrumbListSchema {
+  const { customDomain } = options;
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    itemListElement: breadcrumbs.map((crumb, index) => ({
+      "@type": "ListItem" as const,
+      position: index + 1,
+      name: crumb.name,
+      item:
+        customDomain && !crumb.url.startsWith("http")
+          ? `https://${customDomain}${crumb.url}`
+          : crumb.url,
+    })),
+  };
+}
+
+/**
+ * Generate combined structured data for a complete article page
+ */
+export function generateCompleteArticleStructuredData(
+  article: PublishedArticle,
+  options: StructuredDataOptions = {},
+): Array<BlogPostingSchema | WebSiteSchema | BreadcrumbListSchema> {
+  const schemas: Array<
+    BlogPostingSchema | WebSiteSchema | BreadcrumbListSchema
+  > = [];
+
+  // Article schema
+  schemas.push(generateArticleStructuredData(article, options));
+
+  // Website schema
+  schemas.push(generateWebSiteStructuredData(article.site, options));
+
+  // Breadcrumb schema for article pages
+  const pathPrefix = options.pathPrefix ?? "/blog";
+  const breadcrumbs = [
+    { name: "Home", url: "/" },
+    { name: article.site.name, url: pathPrefix },
+    { name: article.title, url: `${pathPrefix}/${article.slug}` },
+  ];
+  schemas.push(generateBreadcrumbStructuredData(breadcrumbs, options));
+
+  return schemas;
+}
+
+/**
+ * Generate structured data for the blog home page
+ */
+export function generateBlogHomeStructuredData(
+  site: PublishedSite,
+  featuredArticles: PublishedArticle[] = [],
+  options: StructuredDataOptions = {},
+): Array<WebSiteSchema | BlogPostingSchema> {
+  const schemas: Array<WebSiteSchema | BlogPostingSchema> = [];
+
+  // Website schema for the home page
+  schemas.push(generateWebSiteStructuredData(site, options));
+
+  // Featured articles schemas (limit to first 3-5 for performance)
+  if (featuredArticles.length > 0) {
+    const articleSchemas = featuredArticles
+      .slice(0, 5)
+      .map((article) => generateArticleStructuredData(article, options));
+    schemas.push(...articleSchemas);
+  }
+
+  return schemas;
+}
+
+/**
+ * Validate structured data schema
+ */
+export function validateStructuredData(schema: BaseStructuredData): {
+  isValid: boolean;
+  errors: string[];
+} {
+  const errors: string[] = [];
+
+  // Check required fields
+  if (!schema["@context"]) {
+    errors.push("Missing required @context property");
+  } else if (schema["@context"] !== "https://schema.org") {
+    errors.push("@context must be 'https://schema.org'");
+  }
+
+  if (!schema["@type"]) {
+    errors.push("Missing required @type property");
+  }
+
+  // Type-specific validations
+  if (schema["@type"] === "BlogPosting") {
+    const blogSchema = schema as BlogPostingSchema;
+    if (!blogSchema.headline) {
+      errors.push("BlogPosting: Missing required headline");
+    }
+    if (!blogSchema.datePublished) {
+      errors.push("BlogPosting: Missing required datePublished");
+    }
+    if (!blogSchema.author) {
+      errors.push("BlogPosting: Missing required author");
+    }
+    if (!blogSchema.publisher) {
+      errors.push("BlogPosting: Missing required publisher");
+    }
+  }
+
+  if (schema["@type"] === "Person") {
+    const personSchema = schema as PersonSchema;
+    if (!personSchema.name) {
+      errors.push("Person: Missing required name");
+    }
+  }
+
+  if (schema["@type"] === "Organization") {
+    const orgSchema = schema as OrganizationSchema;
+    if (!orgSchema.name) {
+      errors.push("Organization: Missing required name");
+    }
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Convert structured data to JSON-LD string for HTML embedding
+ */
+export function structuredDataToJsonLd(
+  schema: BaseStructuredData | BaseStructuredData[],
+): string {
+  return JSON.stringify(schema, null, 0);
+}
+
+/**
+ * Create a React script element for JSON-LD structured data
+ */
+export function createStructuredDataScript(
+  schema: BaseStructuredData | BaseStructuredData[],
+) {
+  return {
+    type: "application/ld+json",
+    dangerouslySetInnerHTML: {
+      __html: structuredDataToJsonLd(schema),
+    },
+  };
+}
+
+/**
+ * Extract keywords from article content for structured data
+ */
+export function extractKeywordsFromArticle(
+  article: PublishedArticle,
+): string[] {
+  const keywords = new Set<string>();
+
+  // Add meta keywords
+  article.meta.keywords.forEach((keyword) => keywords.add(keyword));
+
+  // Add site tone adjectives as topical keywords
+  article.site.toneAdjectives.forEach((tone) => keywords.add(tone));
+
+  // Add author tone adjectives
+  if (article.author) {
+    article.author.toneAdjectives.forEach((tone) => keywords.add(tone));
+  }
+
+  return Array.from(keywords);
+}
+
+/**
+ * Error types for structured data operations
+ */
+export class StructuredDataError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly details?: unknown,
+  ) {
+    super(message);
+    this.name = "StructuredDataError";
+  }
+}
+
+/**
+ * Generate structured data with error handling
+ */
+export function safeGenerateArticleStructuredData(
+  article: PublishedArticle,
+  options: StructuredDataOptions = {},
+): { schema?: BlogPostingSchema; error?: StructuredDataError } {
+  try {
+    const schema = generateArticleStructuredData(article, options);
+    const validation = validateStructuredData(schema);
+
+    if (!validation.isValid) {
+      return {
+        error: new StructuredDataError(
+          "Generated schema validation failed",
+          "VALIDATION_FAILED",
+          validation.errors,
+        ),
+      };
+    }
+
+    return { schema };
+  } catch (error) {
+    return {
+      error: new StructuredDataError(
+        "Failed to generate structured data",
+        "GENERATION_FAILED",
+        error,
+      ),
+    };
+  }
+}

package/dist/lib/topics.ts

@@ -0,0 +1,56 @@
+import type { PublishedArticle, PublishedTopic } from "../types/contracts";
+
+export interface TopicArchive {
+  topic: PublishedTopic;
+  articles: PublishedArticle[];
+}
+
+export function getArticlePrimaryTopic(
+  article: PublishedArticle,
+): PublishedTopic | null {
+  const topics = article.topics ?? [];
+  return topics.find((topic) => topic.isPrimary) ?? topics[0] ?? null;
+}
+
+export function getAllTopics(articles: PublishedArticle[]): PublishedTopic[] {
+  const topicsBySlug = new Map<string, PublishedTopic>();
+
+  for (const article of articles) {
+    for (const topic of article.topics ?? []) {
+      if (!topicsBySlug.has(topic.slug)) {
+        topicsBySlug.set(topic.slug, topic);
+      }
+    }
+  }
+
+  return Array.from(topicsBySlug.values()).sort((a, b) =>
+    a.name.localeCompare(b.name),
+  );
+}
+
+export function getTopicArchive(
+  articles: PublishedArticle[],
+  topicSlug: string,
+): TopicArchive | null {
+  const matchingArticles = articles.filter((article) =>
+    (article.topics ?? []).some((topic) => topic.slug === topicSlug),
+  );
+
+  if (matchingArticles.length === 0) {
+    return null;
+  }
+
+  const topic =
+    matchingArticles
+      .flatMap((article) => article.topics ?? [])
+      .find((candidate) => candidate.slug === topicSlug) ?? null;
+
+  if (!topic) {
+    return null;
+  }
+
+  return {
+    topic,
+    articles: matchingArticles,
+  };
+}

package/dist/lib/urls.ts

@@ -0,0 +1,29 @@
+/**
+ * URL helpers shared by package UI, metadata, and sitemap integrations.
+ */
+
+export function normalizeBlogBasePath(basePath = "/blog"): string {
+  const trimmed = basePath.trim();
+  if (!trimmed || trimmed === "/") return "";
+
+  return trimmed.replace(/^(?!\/)/, "/").replace(/\/+$/, "");
+}
+
+export function buildBlogPath(
+  basePath: string | undefined,
+  slug?: string,
+): string {
+  const normalizedBasePath = normalizeBlogBasePath(basePath);
+  const cleanSlug = slug?.replace(/^\/+/, "").replace(/\/+$/, "");
+
+  if (!cleanSlug) {
+    return normalizedBasePath || "/";
+  }
+
+  return `${normalizedBasePath}/${cleanSlug}`.replace(/\/+/g, "/");
+}
+
+export function getPathPrefixFromBlogUrl(blogUrl: string): string {
+  const parsed = new URL(blogUrl);
+  return normalizeBlogBasePath(parsed.pathname);
+}

package/dist/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}