@giancarlosgza/blog-layer 0.0.0-stage → 0.1.0

package/server/utils/blog-data.ts

@@ -0,0 +1,218 @@
+import type { IAuthor } from '#blog/shared/models/author'
+import type { IPost } from '#blog/shared/models/post'
+import type { ISeries } from '#blog/shared/models/series'
+import type { ISettings } from '#blog/shared/models/settings'
+import type { ITag } from '#blog/shared/models/tag'
+import type { IPostSeries, IPostSeriesPart } from '#blog/shared/types/api'
+import { Buffer } from 'node:buffer'
+
+/**
+ * Pure helpers for the cached public read endpoints: Firestore → plain JSON mappers,
+ * public visibility, query param parsing, page slicing and cache keys. Kept free of
+ * Nitro/Firebase imports so they are unit-tested directly.
+ */
+
+/** Constants */
+export const POSTS_PAGE_SIZE = 12
+export const POSTS_MAX_LIMIT = 50
+// Bounds distinct cache entries; the web SDK has no offset, so a page reads page × size docs.
+export const POSTS_MAX_PAGE = 1000
+export const FEATURED_LIMIT = 3
+
+/** Interfaces */
+export interface IPageSlice<T> {
+  items: T[]
+  hasMore: boolean
+}
+
+type TFirestoreData = Record<string, unknown>
+
+/** Serialization */
+function isTimestampLike(value: object): value is { toMillis: () => number } {
+  return typeof (value as { toMillis?: unknown }).toMillis === 'function'
+}
+
+function isDocumentReferenceLike(value: object): value is { path: string } {
+  return typeof (value as { path?: unknown }).path === 'string' && 'firestore' in value
+}
+
+function isPlainObject(value: object): boolean {
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+// Timestamps become Unix ms so the payload is plain JSON and `useDateValue` still reads them.
+export function serializeFirestore<T>(value: T): T {
+  if (value instanceof Date)
+    return value.getTime() as T
+  if (Array.isArray(value))
+    return value.map(item => serializeFirestore(item)) as T
+  if (value && typeof value === 'object') {
+    if (isTimestampLike(value))
+      return value.toMillis() as T
+    // References hold the whole Firestore client (circular); only their path is data.
+    if (isDocumentReferenceLike(value))
+      return value.path as T
+    if (!isPlainObject(value))
+      return String(value) as T
+
+    return Object.fromEntries(
+      Object.entries(value as TFirestoreData).map(([key, item]) => [key, serializeFirestore(item)])
+    ) as T
+  }
+  return value
+}
+
+/** Visibility */
+/** The one rule for public post visibility (drafts and unpublished posts never leave the server). */
+export function isPublishedPost(data: TFirestoreData | IPost | null | undefined): boolean {
+  return data?.isPublished === true
+}
+
+/** Maps a post document, or `null` when it must not be public. */
+export function toPublishedPost(id: string, data: TFirestoreData | null | undefined): IPost | null {
+  return data && isPublishedPost(data) ? toPost(id, data) : null
+}
+
+export function toPublishedPosts(docs: Array<{ id: string, data: TFirestoreData }>): IPost[] {
+  return docs.flatMap((item) => {
+    const post = toPublishedPost(item.id, item.data)
+    return post ? [post] : []
+  })
+}
+
+// Document id wins over a stored `id` field, matching what VueFire exposed.
+export function toPost(id: string, data: TFirestoreData): IPost {
+  return serializeFirestore({ ...data, id } as IPost)
+}
+
+export function toAuthor(id: string, data: TFirestoreData): IAuthor {
+  return serializeFirestore({ ...data, id } as IAuthor)
+}
+
+export function toTag(id: string, data: TFirestoreData): ITag {
+  return serializeFirestore({ ...data, id } as ITag)
+}
+
+export function toSettings(data: TFirestoreData): ISettings {
+  return serializeFirestore(data as unknown as ISettings)
+}
+
+export function toSeries(id: string, data: TFirestoreData): ISeries {
+  return serializeFirestore({ ...data, id, slug: typeof data.slug === 'string' && data.slug ? data.slug : id } as ISeries)
+}
+
+/** Series and featured */
+function positiveOrder(value: unknown): number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 1 ? value : Number.POSITIVE_INFINITY
+}
+
+function createdMs(post: IPost): number {
+  return typeof post.createdAt === 'number' ? post.createdAt : 0
+}
+
+function compareOrder(a: number, b: number): number {
+  return a === b ? 0 : a < b ? -1 : 1
+}
+
+/** Reading order: `seriesOrder` ascending (unnumbered last), then oldest first. */
+export function sortSeriesPosts(posts: IPost[]): IPost[] {
+  return [...posts].sort((a, b) =>
+    compareOrder(positiveOrder(a.seriesOrder), positiveOrder(b.seriesOrder))
+    || createdMs(a) - createdMs(b)
+    || (a.id ?? '').localeCompare(b.id ?? ''))
+}
+
+export function toSeriesParts(posts: IPost[], currentSlug: string): IPostSeriesPart[] {
+  return sortSeriesPosts(posts.filter(post => isPublishedPost(post))).map((post) => {
+    const slug = post.id || post.slug || ''
+    return {
+      slug,
+      title: post.title || slug,
+      seriesOrder: Number.isFinite(positiveOrder(post.seriesOrder)) ? post.seriesOrder as number : null,
+      isCurrent: slug === currentSlug
+    }
+  })
+}
+
+export function toPostSeries(series: ISeries, posts: IPost[], currentSlug: string): IPostSeries {
+  return {
+    slug: series.slug,
+    name: series.name || series.slug,
+    ...(series.description ? { description: series.description } : {}),
+    parts: toSeriesParts(posts, currentSlug)
+  }
+}
+
+/** Home hero: published `featured` posts, `featuredOrder` ascending (unset last), then newest. */
+export function selectFeaturedPosts(posts: IPost[], limit = FEATURED_LIMIT): IPost[] {
+  return posts
+    .filter(post => isPublishedPost(post) && post.featured === true)
+    .sort((a, b) =>
+      compareOrder(positiveOrder(a.featuredOrder), positiveOrder(b.featuredOrder))
+      || createdMs(b) - createdMs(a))
+    .slice(0, limit)
+}
+
+/** Query params */
+function firstValue(raw: unknown): unknown {
+  return Array.isArray(raw) ? raw[0] : raw
+}
+
+/** Positive page number (default 1); `null` when malformed or out of range. */
+export function parsePage(raw: unknown): number | null {
+  const value = firstValue(raw)
+  if (value === undefined || value === null || value === '')
+    return 1
+
+  const text = String(value)
+  if (!/^\d+$/.test(text))
+    return null
+
+  const page = Number.parseInt(text, 10)
+  return page >= 1 && page <= POSTS_MAX_PAGE ? page : null
+}
+
+/** Page size clamped to 1…50 (default 12). */
+export function parseLimit(raw: unknown): number {
+  const value = Number.parseInt(String(firstValue(raw) ?? ''), 10)
+  if (!Number.isFinite(value) || value < 1)
+    return POSTS_PAGE_SIZE
+
+  return Math.min(value, POSTS_MAX_LIMIT)
+}
+
+/** Trimmed non-empty string param, else `null`. */
+export function parseText(raw: unknown): string | null {
+  const value = firstValue(raw)
+  if (typeof value !== 'string')
+    return null
+
+  return value.trim() || null
+}
+
+/** Pagination */
+/**
+ * Slices page `page` out of the first `page × size` results. `hasMore` mirrors the old
+ * `length >= page × size` check, so an exactly full last page still offers a next page.
+ */
+export function slicePage<T>(items: T[], page: number, size: number): IPageSlice<T> {
+  return {
+    items: items.slice((page - 1) * size, page * size),
+    hasMore: items.length >= page * size
+  }
+}
+
+/** Cache keys */
+// Nitro strips non-word characters from keys ("UI/UX" → "UIUX"), so free text is hex-encoded.
+export function encodeKeyPart(value: string | null | undefined): string {
+  return value ? Buffer.from(value, 'utf8').toString('hex') : 'none'
+}
+
+export function postListCacheKey(options: { page: number | null, size: number, tag: string | null }): string {
+  return `page_${options.page ?? 'invalid'}_size_${options.size}_tag_${encodeKeyPart(options.tag)}`
+}
+
+export function pagedCacheKey(id: string, page: number | null): string {
+  return `${encodeKeyPart(id)}_page_${page ?? 'invalid'}`
+}

package/server/utils/blog-firestore.ts

@@ -0,0 +1,80 @@
+import type { Query } from 'firebase-admin/firestore'
+import type { IPost } from '#blog/shared/models/post'
+import type { ISeries } from '#blog/shared/models/series'
+import { getFirestore } from 'firebase-admin/firestore'
+
+/**
+ * Admin SDK reads for the cached public endpoints (default app from `server/plugins/firebase.ts`).
+ * The Admin SDK bypasses the Firestore rules, so visibility is enforced here: every post read
+ * filters on `isPublished == true` in the query AND re-checks each document (`toPublishedPosts`).
+ * Public endpoints never read `postDrafts` or `admins`.
+ */
+
+/** Published posts query (base for every public post list). */
+export function publishedPostsQuery(): Query {
+  return getFirestore().collection('posts').where('isPublished', '==', true)
+}
+
+export async function readPublishedPosts(query: Query): Promise<IPost[]> {
+  const snapshot = await query.get()
+  return toPublishedPosts(snapshot.docs.map(item => ({ id: item.id, data: item.data() })))
+}
+
+/** Published posts newest first, sliced to `page` out of the first `page × size`. */
+export async function listPublishedPosts(page: number, size: number, filter: (query: Query) => Query = query => query) {
+  const posts = await readPublishedPosts(
+    filter(publishedPostsQuery()).orderBy('createdAt', 'desc').limit(page * size)
+  )
+  return slicePage(posts, page, size)
+}
+
+// Both reads below use equality filters only (no orderBy), which Firestore serves by merging the
+// single-field indexes, so they need no composite index; ordering happens in memory.
+const SERIES_MAX_PARTS = 100
+const FEATURED_SCAN_LIMIT = 50
+
+/** Published parts of a series in reading order. */
+export async function readSeriesPosts(seriesSlug: string): Promise<IPost[]> {
+  const posts = await readPublishedPosts(
+    publishedPostsQuery().where('seriesSlug', '==', seriesSlug).limit(SERIES_MAX_PARTS)
+  )
+  return sortSeriesPosts(posts)
+}
+
+export async function readSeries(slug: string): Promise<ISeries | null> {
+  const snapshot = await getFirestore().collection('series').doc(slug).get()
+  const data = snapshot.data()
+  return data ? toSeries(snapshot.id, data) : null
+}
+
+const SERIES_LIST_LIMIT = 200
+
+/** Every series name by slug (only the two fields cards need). */
+export async function readSeriesList(): Promise<Array<Pick<ISeries, 'slug' | 'name'>>> {
+  const snapshot = await getFirestore().collection('series').select('name', 'slug').limit(SERIES_LIST_LIMIT).get()
+  return snapshot.docs.map((item) => {
+    const series = toSeries(item.id, item.data())
+    return { slug: series.slug, name: series.name || series.slug }
+  })
+}
+
+/** Home hero posts (`selectFeaturedPosts`). */
+export async function readFeaturedPosts(): Promise<IPost[]> {
+  const posts = await readPublishedPosts(
+    publishedPostsQuery().where('featured', '==', true).limit(FEATURED_SCAN_LIMIT)
+  )
+  return selectFeaturedPosts(posts)
+}
+
+export function notFound(statusMessage = 'Not found'): never {
+  throw createError({ statusCode: 404, statusMessage })
+}
+
+/** Rethrows HTTP errors; anything else (credentials, network, quota) becomes an uncached 503. */
+export function failRead(label: string, error: unknown): never {
+  if (isError(error))
+    throw error
+
+  console.log(`[${label}] Firestore read failed`, error)
+  throw createError({ statusCode: 503, statusMessage: 'Blog data unavailable' })
+}

package/server/utils/rss.ts

@@ -0,0 +1,212 @@
+import type { IFirestoreDateValue } from '#blog/shared/models/date'
+import type { IPost } from '#blog/shared/models/post'
+import { htmlToExcerpt, resolveAuthorName } from '#blog/shared/utils/blog'
+import { toBlogUrl } from '#blog/shared/utils/blog-path'
+import { toDateMs } from '#blog/shared/utils/date'
+import { sanitizeBlogHtml } from '#blog/shared/utils/sanitize'
+
+/**
+ * Pure RSS 2.0 builders for `server/handlers/rss.xml.ts`: XML escaping, CDATA, RFC 822 dates,
+ * feed post selection and item/channel markup. Free of Nitro/Firebase imports so they are unit-tested.
+ */
+
+/** Constants */
+export const RSS_ITEM_LIMIT = 20
+// Headroom so noindex posts filtered out after the query still leave a full feed.
+export const RSS_QUERY_LIMIT = 50
+export const RSS_DESCRIPTION_MAX = 300
+
+// Characters XML 1.0 forbids even when escaped (C0 controls except tab/LF/CR, U+FFFE/U+FFFF).
+// eslint-disable-next-line no-control-regex
+const INVALID_XML_CHARS = /[\u0000-\u0008\v\f\u000E-\u001F\u{FFFE}\u{FFFF}]/gu
+
+const IMAGE_TYPES: Record<string, string> = {
+  avif: 'image/avif',
+  gif: 'image/gif',
+  jpeg: 'image/jpeg',
+  jpg: 'image/jpeg',
+  png: 'image/png',
+  svg: 'image/svg+xml',
+  webp: 'image/webp'
+}
+
+const NAMED_ENTITIES: Record<string, string> = {
+  amp: '&',
+  apos: '\'',
+  gt: '>',
+  lt: '<',
+  nbsp: ' ',
+  quot: '"'
+}
+
+/** Interfaces */
+export interface IRssItemInput {
+  post: IPost
+  /** Public site origin without a trailing slash. */
+  siteUrl: string
+  /** Where the blog mounts on that site (`blog.basePath`); defaults to the root. */
+  basePath?: string
+  /** Raw `postContents` HTML; sanitized here. */
+  contents?: string
+  /** `dc:creator` when the post has no author name. */
+  defaultAuthor?: string
+}
+
+export interface IRssChannelInput {
+  title: string
+  description: string
+  siteUrl: string
+  /** Absolute URL of the feed itself (`atom:link rel="self"`). */
+  feedUrl: string
+  imageUrl?: string | null
+  lastBuildDate?: Date | null
+  items: string[]
+}
+
+/** Text */
+export function stripInvalidXmlChars(value: string): string {
+  return value.replace(INVALID_XML_CHARS, '')
+}
+
+export function escapeXml(value: unknown): string {
+  return stripInvalidXmlChars(String(value ?? ''))
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+}
+
+// A CDATA section cannot contain "]]>", so each one closes the section and reopens a new one.
+export function toCdata(value: string): string {
+  return `<![CDATA[${stripInvalidXmlChars(value).replaceAll(']]>', ']]]]><![CDATA[>')}]]>`
+}
+
+export function decodeHtmlEntities(value: string): string {
+  return value.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (entity, code: string) => {
+    if (code[0] === '#') {
+      const point = code[1]?.toLowerCase() === 'x'
+        ? Number.parseInt(code.slice(2), 16)
+        : Number.parseInt(code.slice(1), 10)
+      return Number.isInteger(point) && point > 0 && point <= 0x10FFFF ? String.fromCodePoint(point) : entity
+    }
+    return NAMED_ENTITIES[code.toLowerCase()] ?? entity
+  })
+}
+
+function clean(value: string | null | undefined): string {
+  return (value ?? '').replace(/\s+/g, ' ').trim()
+}
+
+function truncate(text: string, maxLength: number): string {
+  return text.length <= maxLength ? text : `${text.slice(0, maxLength - 1).trimEnd()}…`
+}
+
+/** Plain-text excerpt: tags stripped before entities are decoded, so `&lt;div&gt;` stays text. */
+export function htmlToPlainExcerpt(html: string, maxLength = RSS_DESCRIPTION_MAX): string {
+  return truncate(clean(decodeHtmlEntities(htmlToExcerpt(html, Number.POSITIVE_INFINITY))), maxLength)
+}
+
+/** Dates */
+/** RFC 822 date (`Tue, 14 Nov 2023 22:13:20 GMT`); `toUTCString` already emits that format. */
+export function toRfc822Date(value: IFirestoreDateValue): string | null {
+  const ms = toDateMs(value)
+  return ms === null ? null : new Date(ms).toUTCString()
+}
+
+/** Posts */
+export function postSlug(post: Pick<IPost, 'slug' | 'id'>): string {
+  return clean(post.slug) || clean(post.id)
+}
+
+/** Newest-first published posts that may appear in the feed: indexable and addressable. */
+export function selectFeedPosts(posts: IPost[], limit = RSS_ITEM_LIMIT): IPost[] {
+  return posts
+    .filter(post => post.isPublished === true && post.noindex !== true && postSlug(post))
+    .slice(0, limit)
+}
+
+/** Newest create/update time across the feed posts, for `lastBuildDate`. */
+export function latestPostDate(posts: IPost[]): Date | null {
+  const times = posts.flatMap(post => [toDateMs(post.updatedAt), toDateMs(post.createdAt)])
+    .filter((ms): ms is number => ms !== null)
+  return times.length ? new Date(Math.max(...times)) : null
+}
+
+export function imageMimeType(url: string): string | null {
+  let path: string
+  try {
+    // Storage URLs keep the object path encoded (`o/posts%2Fcover.webp?alt=media`).
+    path = decodeURIComponent(new URL(url).pathname)
+  } catch {
+    return null
+  }
+  const extension = /\.([a-z0-9]+)$/i.exec(path)?.[1]?.toLowerCase()
+  return extension ? IMAGE_TYPES[extension] ?? null : null
+}
+
+// Feed readers resolve relative URLs inconsistently, so root-relative links and images become absolute.
+export function absolutizeUrls(html: string, siteUrl: string): string {
+  return html.replace(/(\s(?:href|src)=")\/(?!\/)/g, `$1${siteUrl}/`)
+}
+
+export function resolveFeedDescription(post: IPost, contents = ''): string {
+  return clean(post.seoDescription) || clean(post.shortText) || htmlToPlainExcerpt(contents)
+}
+
+/** Markup */
+export function buildRssItem({ post, siteUrl, basePath, contents = '', defaultAuthor = '' }: IRssItemInput): string {
+  const origin = siteUrl.replace(/\/+$/, '')
+  const link = toBlogUrl(origin, basePath, `/${postSlug(post)}`)
+  const pubDate = toRfc822Date(post.createdAt)
+  const description = resolveFeedDescription(post, contents)
+  const body = contents ? absolutizeUrls(sanitizeBlogHtml(contents), origin) : ''
+  const cover = clean(post.imageURL)
+  const coverType = cover ? imageMimeType(cover) : null
+  const tags = [...new Set((post.tags ?? []).map(tag => clean(tag)).filter(Boolean))]
+
+  const lines = [
+    `<title>${escapeXml(clean(post.title) || 'Article')}</title>`,
+    `<link>${escapeXml(link)}</link>`,
+    `<guid isPermaLink="true">${escapeXml(link)}</guid>`,
+    pubDate ? `<pubDate>${pubDate}</pubDate>` : '',
+    `<dc:creator>${escapeXml(resolveAuthorName(post, defaultAuthor))}</dc:creator>`,
+    ...tags.map(tag => `<category>${escapeXml(tag)}</category>`),
+    `<description>${escapeXml(description)}</description>`,
+    body ? `<content:encoded>${toCdata(body)}</content:encoded>` : '',
+    cover && coverType ? `<enclosure url="${escapeXml(cover)}" length="0" type="${coverType}"/>` : '',
+    cover
+      ? `<media:content url="${escapeXml(cover)}" medium="image"${coverType ? ` type="${coverType}"` : ''}/>`
+      : ''
+  ]
+
+  return `<item>\n${lines.filter(Boolean).map(line => `  ${line}`).join('\n')}\n</item>`
+}
+
+export function buildRssFeed(channel: IRssChannelInput): string {
+  const siteUrl = channel.siteUrl.replace(/\/+$/, '')
+  const title = escapeXml(channel.title)
+  const imageUrl = clean(channel.imageUrl)
+  const lines = [
+    `<title>${title}</title>`,
+    `<link>${escapeXml(siteUrl)}</link>`,
+    `<description>${escapeXml(channel.description)}</description>`,
+    '<language>en</language>',
+    `<lastBuildDate>${(channel.lastBuildDate ?? new Date()).toUTCString()}</lastBuildDate>`,
+    `<atom:link href="${escapeXml(channel.feedUrl)}" rel="self" type="application/rss+xml"/>`,
+    imageUrl
+      ? `<image><url>${escapeXml(imageUrl)}</url><title>${title}</title><link>${escapeXml(siteUrl)}</link></image>`
+      : ''
+  ]
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/">',
+    '<channel>',
+    ...lines.filter(Boolean),
+    ...channel.items,
+    '</channel>',
+    '</rss>',
+    ''
+  ].join('\n')
+}

package/server/utils/sitemap.ts

@@ -0,0 +1,80 @@
+import type { IAuthor } from '#blog/shared/models/author'
+import type { IPost } from '#blog/shared/models/post'
+import type { ISeries } from '#blog/shared/models/series'
+import type { ITag } from '#blog/shared/models/tag'
+import { joinBlogPath } from '#blog/shared/utils/blog-path'
+
+/**
+ * Pure sitemap URL builder for `/api/blog/_sitemap-urls` (Firestore reads live in the route).
+ * Kept free of Nitro/Firebase imports so it is unit-tested directly.
+ */
+
+/** Constants */
+export const SITEMAP_POST_LIMIT = 5000
+
+/** Interfaces */
+type TSitemapChangefreq = 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never'
+type TSitemapPriority = 0 | 0.1 | 0.2 | 0.3 | 0.4 | 0.5 | 0.6 | 0.7 | 0.8 | 0.9 | 1
+
+export interface ISitemapUrl {
+  loc: string
+  lastmod?: string
+  changefreq?: TSitemapChangefreq
+  priority?: TSitemapPriority
+}
+
+export interface ISitemapSources {
+  /** Published posts, newest first. */
+  posts: IPost[]
+  tags: ITag[]
+  authors: IAuthor[]
+  series: ISeries[]
+  /** Where the blog mounts (`blog.basePath`); defaults to the root. */
+  basePath?: string
+}
+
+/** Helpers */
+// The mappers serialize Timestamps to Unix ms, so only numbers carry a date here.
+function lastmod(value: unknown): Pick<ISitemapUrl, 'lastmod'> {
+  return typeof value === 'number' && value > 0 ? { lastmod: new Date(value).toISOString() } : {}
+}
+
+/**
+ * Indexable published posts at `<basePath>/<slug>`, plus tag, author and series hubs.
+ * `noindex` posts stay public by link but are not advertised; a series is listed
+ * only once it has an indexable published part.
+ */
+export function buildSitemapUrls({ posts, tags, authors, series, basePath }: ISitemapSources): ISitemapUrl[] {
+  const loc = (path: string) => joinBlogPath(basePath, path)
+  const urls: ISitemapUrl[] = []
+  const listedSeries = new Set<string>()
+
+  for (const post of posts) {
+    const slug = post.id || post.slug
+    if (post.isPublished !== true || post.noindex === true || !slug)
+      continue
+
+    if (post.seriesSlug)
+      listedSeries.add(post.seriesSlug)
+
+    urls.push({ loc: loc(`/${slug}`), ...lastmod(post.updatedAt || post.createdAt), changefreq: 'weekly', priority: 0.7 })
+  }
+
+  for (const tag of tags) {
+    if (tag.name)
+      urls.push({ loc: loc(`/tags/${tag.name}`), changefreq: 'weekly', priority: 0.4 })
+  }
+
+  for (const author of authors) {
+    if (author.slug)
+      urls.push({ loc: loc(`/authors/${author.slug}`), ...lastmod(author.updatedAt), changefreq: 'weekly', priority: 0.4 })
+  }
+
+  for (const item of series) {
+    const slug = item.id || item.slug
+    if (listedSeries.has(slug))
+      urls.push({ loc: loc(`/series/${slug}`), ...lastmod(item.updatedAt), changefreq: 'weekly', priority: 0.5 })
+  }
+
+  return urls
+}

package/shared/models/author.ts

@@ -0,0 +1,19 @@
+import type { IFirestoreDateValue } from './date'
+
+/**
+ * `authors/{uid}` — author profile. Document ID is the Firebase Auth UID.
+ */
+export interface IAuthor {
+  id?: string
+  uid?: string
+  name: string
+  /** URL slug for the author's public page (e.g. used by the blog's sitemap/author routes). */
+  slug?: string
+  description?: string
+  photoURL?: string
+  profileLink?: string
+  /** Legacy handle shown on the author page; not managed by blog-admin. */
+  username?: string
+  createdAt?: IFirestoreDateValue
+  updatedAt?: IFirestoreDateValue
+}

package/shared/models/date.ts

@@ -0,0 +1,11 @@
+export interface ISerializedTimestamp {
+  seconds: number
+  nanoseconds?: number
+}
+
+export interface IDateWithToDate {
+  toDate: () => Date
+}
+
+/** Firestore `Timestamp`s (client or Admin SDK) match `IDateWithToDate` / `ISerializedTimestamp` structurally. */
+export type IFirestoreDateValue = ISerializedTimestamp | IDateWithToDate | number | Date | string | null | undefined