@rimelight/seo 0.0.3 → 0.0.4

package/src/schema.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vite-plus/test"
+import { buildArticleSchema, buildBreadcrumbSchema } from "./schema.js"
+
+describe("seo-schema", () => {
+  it("builds TechArticle JSON-LD schema", () => {
+    const schema = buildArticleSchema({
+      type: "TechArticle",
+      title: "Building on Cloudflare Workers",
+      description: "A complete guide to edge rendering",
+      url: "https://rimelight.com/blog/cloudflare-workers",
+      datePublished: new Date("2026-08-01T12:00:00Z"),
+      authorName: "Idan",
+      image: "https://rimelight.com/og/article.png"
+    })
+
+    expect(schema["@context"]).toBe("https://schema.org")
+    expect(schema["@type"]).toBe("TechArticle")
+    expect(schema["headline"]).toBe("Building on Cloudflare Workers")
+    expect(schema["author"]).toEqual({ "@type": "Person", "name": "Idan" })
+    expect(schema["datePublished"]).toBe("2026-08-01T12:00:00.000Z")
+  })
+
+  it("builds BreadcrumbList JSON-LD schema", () => {
+    const schema = buildBreadcrumbSchema([
+      { name: "Home", url: "https://rimelight.com" },
+      { name: "Docs", url: "https://rimelight.com/en/docs" },
+      { name: "Installation", url: "https://rimelight.com/en/docs/installation" }
+    ])
+
+    expect(schema["@type"]).toBe("BreadcrumbList")
+    expect(schema["itemListElement"]).toHaveLength(3)
+    expect(schema["itemListElement"][0]).toEqual({
+      "@type": "ListItem",
+      "position": 1,
+      "name": "Home",
+      "item": "https://rimelight.com"
+    })
+    expect(schema["itemListElement"][2]).toEqual({
+      "@type": "ListItem",
+      "position": 3,
+      "name": "Installation",
+      "item": "https://rimelight.com/en/docs/installation"
+    })
+  })
+})

package/src/schema.ts

@@ -0,0 +1,96 @@
+export interface ArticleSchemaOptions {
+  type?: "TechArticle" | "Article" | "BlogPosting"
+  title: string
+  description?: string
+  url: string
+  datePublished?: string | Date
+  dateModified?: string | Date
+  authorName?: string
+  authorUrl?: string
+  image?: string
+  publisherName?: string
+  publisherLogo?: string
+}
+
+export interface BreadcrumbItem {
+  name: string
+  url: string
+}
+
+/**
+ * Builds Schema.org Article / TechArticle / BlogPosting JSON-LD.
+ */
+export function buildArticleSchema(options: ArticleSchemaOptions): Record<string, any> {
+  const {
+    type = "TechArticle",
+    title,
+    description,
+    url,
+    datePublished,
+    dateModified,
+    authorName,
+    authorUrl,
+    image,
+    publisherName = "Rimelight Entertainment",
+    publisherLogo
+  } = options
+
+  const schema: Record<string, any> = {
+    "@context": "https://schema.org",
+    "@type": type,
+    "headline": title,
+    "mainEntityOfPage": {
+      "@type": "WebPage",
+      "@id": url
+    }
+  }
+
+  if (description) schema["description"] = description
+  if (image) schema["image"] = image
+
+  if (datePublished) {
+    schema["datePublished"] =
+      datePublished instanceof Date ? datePublished.toISOString() : datePublished
+  }
+
+  if (dateModified) {
+    schema["dateModified"] =
+      dateModified instanceof Date ? dateModified.toISOString() : dateModified
+  } else if (datePublished) {
+    schema["dateModified"] = schema["datePublished"]
+  }
+
+  if (authorName) {
+    schema["author"] = {
+      "@type": "Person",
+      "name": authorName,
+      ...(authorUrl ? { url: authorUrl } : {})
+    }
+  }
+
+  if (publisherName) {
+    schema["publisher"] = {
+      "@type": "Organization",
+      "name": publisherName,
+      ...(publisherLogo ? { logo: { "@type": "ImageObject", "url": publisherLogo } } : {})
+    }
+  }
+
+  return schema
+}
+
+/**
+ * Builds Schema.org BreadcrumbList JSON-LD.
+ */
+export function buildBreadcrumbSchema(items: BreadcrumbItem[]): Record<string, any> {
+  return {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    "itemListElement": items.map((item, index) => ({
+      "@type": "ListItem",
+      "position": index + 1,
+      "name": item.name,
+      "item": item.url
+    }))
+  }
+}

package/src/sitemap.test.ts

@@ -0,0 +1,191 @@
+import { describe, it, expect } from "vite-plus/test"
+import {
+  buildSitemapUrls,
+  buildSitemapXml,
+  buildSitemapIndexXml,
+  chunkSitemapUrls
+} from "./sitemap.js"
+import type { LocaleConfig, SeoEntry } from "./types.js"
+
+describe("buildSitemapUrls", () => {
+  const config: LocaleConfig = {
+    site: "https://example.com",
+    locales: { en: "en-US", pt: "pt-BR" },
+    defaultLocale: "en"
+  }
+
+  it("builds URLs for a single entry in multiple locales", () => {
+    const entries: SeoEntry[] = [{ path: "/about" }]
+    const urls = buildSitemapUrls(entries, config)
+
+    expect(urls).toHaveLength(2)
+    expect(urls[0]!.loc).toBe("https://example.com/about")
+    expect(urls[1]!.loc).toBe("https://example.com/pt/about")
+  })
+
+  it("includes alternates for multi-locale entries", () => {
+    const entries: SeoEntry[] = [{ path: "/about" }]
+    const urls = buildSitemapUrls(entries, config)
+
+    // Default locale URL should have x-default alternate
+    const defaultUrl = urls.find((u) => u.loc === "https://example.com/about")
+    expect(defaultUrl?.alternates).toHaveLength(2)
+    expect(defaultUrl?.alternates?.[0]!.hreflang).toBe("pt-BR")
+    expect(defaultUrl?.alternates?.[0]!.href).toBe("https://example.com/pt/about")
+    expect(defaultUrl?.alternates?.[1]!.hreflang).toBe("x-default")
+    expect(defaultUrl?.alternates?.[1]!.href).toBe("https://example.com/about")
+
+    // Non-default locale URL should have only the other locale as alternate
+    const ptUrl = urls.find((u) => u.loc === "https://example.com/pt/about")
+    expect(ptUrl?.alternates).toHaveLength(1)
+    expect(ptUrl?.alternates?.[0]!.hreflang).toBe("en-US")
+    expect(ptUrl?.alternates?.[0]!.href).toBe("https://example.com/about")
+  })
+
+  it("handles prefixDefaultLocale option", () => {
+    const configWithPrefix: LocaleConfig = {
+      ...config,
+      prefixDefaultLocale: true
+    }
+    const entries: SeoEntry[] = [{ path: "/about" }]
+    const urls = buildSitemapUrls(entries, configWithPrefix)
+
+    expect(urls[0]!.loc).toBe("https://example.com/en/about")
+    expect(urls[1]!.loc).toBe("https://example.com/pt/about")
+  })
+
+  it("handles trailingSlash option", () => {
+    const configWithSlash: LocaleConfig = {
+      ...config,
+      trailingSlash: "always"
+    }
+    const entries: SeoEntry[] = [{ path: "/about" }]
+    const urls = buildSitemapUrls(entries, configWithSlash)
+
+    expect(urls[0]!.loc).toBe("https://example.com/about/")
+    expect(urls[1]!.loc).toBe("https://example.com/pt/about/")
+  })
+
+  it("includes lastmod when provided", () => {
+    const date = new Date("2024-01-01")
+    const entries: SeoEntry[] = [{ path: "/about", lastmod: date }]
+    const urls = buildSitemapUrls(entries, config)
+
+    expect(urls[0]!.lastmod).toBe(date.toISOString())
+  })
+
+  it("includes changefreq and priority when provided", () => {
+    const entries: SeoEntry[] = [{ path: "/about", changefreq: "weekly", priority: 0.8 }]
+    const urls = buildSitemapUrls(entries, config)
+
+    expect(urls[0]!.changefreq).toBe("weekly")
+    expect(urls[0]!.priority).toBe(0.8)
+  })
+
+  it("restricts to specified locales", () => {
+    const entries: SeoEntry[] = [{ path: "/about", locales: ["en"] }]
+    const urls = buildSitemapUrls(entries, config)
+
+    expect(urls).toHaveLength(1)
+    expect(urls[0]!.loc).toBe("https://example.com/about")
+  })
+})
+
+describe("buildSitemapXml", () => {
+  it("generates valid XML for URLs", () => {
+    const urls = [
+      {
+        loc: "https://example.com/about",
+        lastmod: "2024-01-01T00:00:00.000Z",
+        changefreq: "weekly" as const,
+        priority: 0.8
+      }
+    ]
+
+    const xml = buildSitemapXml(urls)
+
+    expect(xml).toContain('<?xml version="1.0" encoding="UTF-8"?>')
+    expect(xml).toContain("<urlset")
+    expect(xml).toContain("https://example.com/about")
+    expect(xml).toContain("<lastmod>2024-01-01T00:00:00.000Z</lastmod>")
+    expect(xml).toContain("<changefreq>weekly</changefreq>")
+    expect(xml).toContain("<priority>0.8</priority>")
+  })
+
+  it("includes alternates in XML", () => {
+    const urls = [
+      {
+        loc: "https://example.com/about",
+        alternates: [
+          { hreflang: "pt-BR", href: "https://example.com/pt/about" },
+          { hreflang: "x-default", href: "https://example.com/about" }
+        ]
+      }
+    ]
+
+    const xml = buildSitemapXml(urls)
+
+    expect(xml).toContain("xhtml:link")
+    expect(xml).toContain('hreflang="pt-BR"')
+    expect(xml).toContain('hreflang="x-default"')
+  })
+
+  it("escapes XML special characters", () => {
+    const urls = [
+      {
+        loc: "https://example.com/about?query=test&amp;other=value"
+      }
+    ]
+
+    const xml = buildSitemapXml(urls)
+
+    expect(xml).toContain("&amp;")
+  })
+})
+
+describe("buildSitemapIndexXml", () => {
+  it("generates valid sitemap index XML", () => {
+    const sitemaps = ["https://example.com/sitemap-0.xml", "https://example.com/sitemap-1.xml"]
+
+    const xml = buildSitemapIndexXml(sitemaps)
+
+    expect(xml).toContain('<?xml version="1.0" encoding="UTF-8"?>')
+    expect(xml).toContain("<sitemapindex")
+    expect(xml).toContain("https://example.com/sitemap-0.xml")
+    expect(xml).toContain("https://example.com/sitemap-1.xml")
+  })
+})
+
+describe("chunkSitemapUrls", () => {
+  it("chunks URLs at default limit", () => {
+    const urls = Array.from({ length: 50000 }, (_, i) => ({
+      loc: `https://example.com/page-${i}`
+    }))
+
+    const chunks = chunkSitemapUrls(urls)
+
+    expect(chunks).toHaveLength(2)
+    expect(chunks[0]).toHaveLength(45000)
+    expect(chunks[1]).toHaveLength(5000)
+  })
+
+  it("handles custom limit", () => {
+    const urls = Array.from({ length: 100 }, (_, i) => ({
+      loc: `https://example.com/page-${i}`
+    }))
+
+    const chunks = chunkSitemapUrls(urls, 25)
+
+    expect(chunks).toHaveLength(4)
+    expect(chunks[0]).toHaveLength(25)
+  })
+
+  it("returns single chunk for small arrays", () => {
+    const urls = [{ loc: "https://example.com/page-1" }, { loc: "https://example.com/page-2" }]
+
+    const chunks = chunkSitemapUrls(urls)
+
+    expect(chunks).toHaveLength(1)
+    expect(chunks[0]).toHaveLength(2)
+  })
+})

package/src/sitemap.ts

@@ -0,0 +1,166 @@
+import type { LocaleConfig, SeoEntry, SitemapUrl } from "./types.js"
+
+/**
+ * Build fully-resolved sitemap URLs from entries and locale config
+ */
+export function buildSitemapUrls(entries: SeoEntry[], config: LocaleConfig): SitemapUrl[] {
+  const urls: SitemapUrl[] = []
+  const { site, locales, defaultLocale, prefixDefaultLocale, trailingSlash } = config
+
+  for (const entry of entries) {
+    const entryLocales =
+      entry.locales && entry.locales.length > 0 ? entry.locales : Object.keys(locales)
+
+    const entryUrls: SitemapUrl[] = []
+
+    for (const locale of entryLocales) {
+      const isDefault = locale === defaultLocale
+      const localePrefix = !isDefault || prefixDefaultLocale ? `/${locale}` : ""
+
+      let path = entry.path
+      if (trailingSlash === "always" && !path.endsWith("/")) {
+        path += "/"
+      } else if (trailingSlash === "never" && path.endsWith("/")) {
+        path = path.replace(/\/$/, "")
+      }
+
+      const loc = `${site}${localePrefix}${path}`
+
+      const item: SitemapUrl = { loc }
+      if (entry.lastmod) {
+        item.lastmod = entry.lastmod.toISOString()
+      }
+      if (entry.changefreq) {
+        item.changefreq = entry.changefreq
+      }
+      if (entry.priority !== undefined) {
+        item.priority = entry.priority
+      }
+      entryUrls.push(item)
+    }
+
+    // Add alternates if multiple locales
+    if (entryUrls.length > 1) {
+      const defaultUrl = entryUrls.find(
+        (u) => u.loc === `${site}${prefixDefaultLocale ? `/${defaultLocale}` : ""}${entry.path}`
+      )
+
+      for (const url of entryUrls) {
+        url.alternates = entryUrls
+          .filter((u) => u.loc !== url.loc)
+          .map((u) => ({
+            hreflang: extractHreflang(u.loc, locales, defaultLocale),
+            href: u.loc
+          }))
+
+        // Add x-default pointing to default locale
+        // x-default should be on the default URL itself, pointing to itself
+        if (defaultUrl && url.loc === defaultUrl.loc) {
+          url.alternates.push({
+            hreflang: "x-default",
+            href: defaultUrl.loc
+          })
+        }
+      }
+    }
+
+    urls.push(...entryUrls)
+  }
+
+  return urls
+}
+
+/**
+ * Build sitemap XML from resolved URLs
+ */
+export function buildSitemapXml(urls: SitemapUrl[]): string {
+  const urlElements = urls
+    .map((url) => {
+      let xml = `  <url>\n    <loc>${escapeXml(url.loc)}</loc>`
+
+      if (url.lastmod) {
+        xml += `\n    <lastmod>${url.lastmod}</lastmod>`
+      }
+
+      if (url.changefreq) {
+        xml += `\n    <changefreq>${url.changefreq}</changefreq>`
+      }
+
+      if (url.priority !== undefined) {
+        xml += `\n    <priority>${url.priority.toFixed(1)}</priority>`
+      }
+
+      if (url.alternates && url.alternates.length > 0) {
+        for (const alt of url.alternates) {
+          xml += `\n    <xhtml:link rel="alternate" hreflang="${alt.hreflang}" href="${escapeXml(alt.href)}" />`
+        }
+      }
+
+      xml += "\n  </url>"
+      return xml
+    })
+    .join("\n")
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">
+${urlElements}
+</urlset>`
+}
+
+/**
+ * Build sitemap index XML from sitemap URLs
+ */
+export function buildSitemapIndexXml(sitemapUrls: string[]): string {
+  const sitemapElements = sitemapUrls
+    .map(
+      (url) => `  <sitemap>
+    <loc>${escapeXml(url)}</loc>
+  </sitemap>`
+    )
+    .join("\n")
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${sitemapElements}
+</sitemapindex>`
+}
+
+/**
+ * Chunk sitemap URLs into multiple sitemaps (max 50k URLs per sitemap)
+ */
+export function chunkSitemapUrls(urls: SitemapUrl[], limit: number = 45000): SitemapUrl[][] {
+  const chunks: SitemapUrl[][] = []
+  for (let i = 0; i < urls.length; i += limit) {
+    chunks.push(urls.slice(i, i + limit))
+  }
+  return chunks
+}
+
+/**
+ * Extract hreflang from a URL based on locale config
+ */
+function extractHreflang(
+  url: string,
+  locales: Record<string, string>,
+  defaultLocale: string
+): string {
+  for (const [segment, hreflang] of Object.entries(locales)) {
+    if (url.includes(`/${segment}/`) || url.endsWith(`/${segment}`)) {
+      return hreflang
+    }
+  }
+  // Default to the first locale's hreflang if no match
+  return locales[defaultLocale] || "en"
+}
+
+/**
+ * Escape XML special characters
+ */
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;")
+}