@xexr/blog-platform 1.1.7 → 1.2.0

package/dist/lib/storage/drizzle.ts

@@ -100,6 +100,7 @@ function toRow(article: PublishedArticle): ArticleRow {
       __bloggyTopics: article.topics ?? [],
       __bloggySeries: article.series ?? null,
       __bloggyCta: article.cta ?? null,
+      ...(article.video && { __bloggyVideo: article.video }),
     }),
     version: article.version,
   };
@@ -128,6 +129,7 @@ function fromRow(row: ArticleRow): PublishedArticle {
     cta: extractCta(row.metaJson),
     topics: extractTopics(row.metaJson),
     series: extractSeries(row.metaJson),
+    ...withVideo(row.metaJson),
     meta: extractMeta(row.metaJson),
     version: row.version,
   };
@@ -137,6 +139,7 @@ type StoredArticleMeta = PublishedArticle["meta"] & {
   __bloggyTopics?: PublishedArticle["topics"];
   __bloggySeries?: PublishedArticle["series"] | null;
   __bloggyCta?: PublishedArticle["cta"] | null;
+  __bloggyVideo?: PublishedArticle["video"];
 };
 
 function parseStoredMeta(metaJson: string): StoredArticleMeta {
@@ -158,8 +161,14 @@ function extractSeries(metaJson: string): PublishedArticle["series"] {
   return parsed.__bloggySeries ?? undefined;
 }
 
+function withVideo(metaJson: string): Pick<PublishedArticle, "video"> {
+  const video = parseStoredMeta(metaJson).__bloggyVideo;
+  return video ? { video } : {};
+}
+
 function extractMeta(metaJson: string): PublishedArticle["meta"] {
   const parsed = parseStoredMeta(metaJson);
+  delete parsed.__bloggyVideo;
   delete parsed.__bloggyTopics;
   delete parsed.__bloggySeries;
   delete parsed.__bloggyCta;

package/dist/lib/structured-data.ts

@@ -15,6 +15,11 @@ import type {
   PublishedSite,
 } from "../types/contracts";
 import { buildAuthorPath } from "./urls";
+import {
+  buildYouTubeStructuredDataEmbedUrl,
+  buildYouTubeThumbnailUrl,
+  isYouTubeVideoId,
+} from "./video";
 
 /**
  * Base schema.org context and type
@@ -95,6 +100,21 @@ export interface BlogPostingSchema extends BaseStructuredData {
     "@type": "Thing";
     name: string;
   }[];
+  video?: VideoObjectSchema;
+}
+
+/**
+ * VideoObject schema for an article's embedded video
+ * @see https://schema.org/VideoObject
+ */
+export interface VideoObjectSchema {
+  "@type": "VideoObject";
+  name: string;
+  description: string;
+  thumbnailUrl: string[];
+  uploadDate: string;
+  duration?: string;
+  embedUrl: string;
 }
 
 /**
@@ -205,6 +225,11 @@ export function generateArticleStructuredData(
     isAccessibleForFree,
   };
 
+  const videoSchema = generateVideoStructuredData(article);
+  if (videoSchema) {
+    schema.video = videoSchema;
+  }
+
   // Add optional properties if enabled
   if (includeOptionalProperties) {
     // Featured image
@@ -239,6 +264,33 @@ export function generateArticleStructuredData(
   return schema;
 }
 
+/**
+ * Generate the VideoObject for an article's video, if it has a valid one
+ */
+export function generateVideoStructuredData(
+  article: PublishedArticle,
+): VideoObjectSchema | undefined {
+  const video = article.video;
+  if (!video || !isYouTubeVideoId(video.id)) {
+    return undefined;
+  }
+
+  const description = video.description?.trim() ?? "";
+
+  return {
+    "@type": "VideoObject",
+    name: video.title,
+    description: description.length > 0 ? description : article.excerpt,
+    thumbnailUrl: [
+      buildYouTubeThumbnailUrl(video.id),
+      ...(article.featuredImage ? [article.featuredImage] : []),
+    ],
+    uploadDate: video.uploadDate,
+    ...(video.duration && { duration: video.duration }),
+    embedUrl: buildYouTubeStructuredDataEmbedUrl(video.id),
+  };
+}
+
 /**
  * Generate structured data for an author
  */

package/dist/lib/video.ts

@@ -0,0 +1,163 @@
+/**
+ * Helpers for article videos (YouTube only).
+ *
+ * Every URL built here goes through `isYouTubeVideoId` first, so a stored id
+ * can never inject markup or a different host into an embed.
+ */
+
+const YOUTUBE_VIDEO_ID_PATTERN = /^[A-Za-z0-9_-]{11}$/;
+const ISO_DURATION_PATTERN = /^PT(?=\d)(?:\d+H)?(?:\d+M)?(?:\d+(?:\.\d+)?S)?$/;
+const ISO_DATE_PREFIX_PATTERN = /^\d{4}-\d{2}-\d{2}(?:$|T)/;
+const YOUTUBE_HOSTS = new Set([
+  "youtube.com",
+  "www.youtube.com",
+  "m.youtube.com",
+  "music.youtube.com",
+  "youtube-nocookie.com",
+  "www.youtube-nocookie.com",
+  "youtu.be",
+]);
+const YOUTUBE_PATH_PREFIXES = ["embed", "shorts", "live", "v"];
+
+export const ARTICLE_VIDEO_TITLE_MAX_LENGTH = 200;
+export const ARTICLE_VIDEO_DESCRIPTION_MAX_LENGTH = 5000;
+
+export function isYouTubeVideoId(value: unknown): value is string {
+  return typeof value === "string" && YOUTUBE_VIDEO_ID_PATTERN.test(value);
+}
+
+export function isIsoDuration(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value !== "PT" &&
+    ISO_DURATION_PATTERN.test(value)
+  );
+}
+
+/** ISO 8601 date or date-time whose calendar date exists (no 31 February). */
+function isIsoDate(value: unknown): value is string {
+  if (typeof value !== "string" || !ISO_DATE_PREFIX_PATTERN.test(value)) {
+    return false;
+  }
+  const datePart = value.slice(0, 10);
+  const parsed = new Date(`${datePart}T00:00:00Z`);
+  return (
+    !Number.isNaN(parsed.getTime()) &&
+    parsed.toISOString().slice(0, 10) === datePart &&
+    !Number.isNaN(Date.parse(value))
+  );
+}
+
+/**
+ * Extract a YouTube video id from a bare id or a YouTube URL
+ * (watch, youtu.be, embed, nocookie embed, shorts, live).
+ */
+export function parseYouTubeVideoId(input: string): string | null {
+  const trimmed = input.trim();
+  if (YOUTUBE_VIDEO_ID_PATTERN.test(trimmed)) return trimmed;
+  if (!trimmed) return null;
+
+  let url: URL;
+  try {
+    url = new URL(
+      /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`,
+    );
+  } catch {
+    return null;
+  }
+
+  const host = url.hostname.toLowerCase();
+  if (!YOUTUBE_HOSTS.has(host)) return null;
+
+  const segments = url.pathname.split("/").filter(Boolean);
+  let candidate: string | null | undefined;
+  if (host === "youtu.be") {
+    candidate = segments[0];
+  } else if (segments[0] === "watch") {
+    candidate = url.searchParams.get("v");
+  } else if (segments[0] && YOUTUBE_PATH_PREFIXES.includes(segments[0])) {
+    candidate = segments[1];
+  }
+
+  return isYouTubeVideoId(candidate) ? candidate : null;
+}
+
+/**
+ * Validate an untrusted `video` value from a publish payload.
+ * Returns a list of human-readable errors; empty when valid.
+ */
+export function validatePublishedArticleVideo(value: unknown): string[] {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return ["Article video must be an object"];
+  }
+
+  const video = value as Record<string, unknown>;
+  const errors: string[] = [];
+
+  if (video.provider !== "youtube") {
+    errors.push('Article video provider must be "youtube"');
+  }
+  if (!isYouTubeVideoId(video.id)) {
+    errors.push("Article video id must be an 11-character YouTube id");
+  }
+  if (typeof video.title !== "string" || !video.title.trim()) {
+    errors.push("Article video title is required");
+  } else if (video.title.length > ARTICLE_VIDEO_TITLE_MAX_LENGTH) {
+    errors.push(
+      `Article video title must be ${ARTICLE_VIDEO_TITLE_MAX_LENGTH} characters or fewer`,
+    );
+  }
+  if (!isIsoDate(video.uploadDate)) {
+    errors.push("Article video uploadDate must be an ISO 8601 date");
+  }
+  if (video.duration !== undefined && !isIsoDuration(video.duration)) {
+    errors.push(
+      "Article video duration must be an ISO 8601 duration such as PT4M13S",
+    );
+  }
+  if (video.verticalId !== undefined && !isYouTubeVideoId(video.verticalId)) {
+    errors.push("Article video verticalId must be an 11-character YouTube id");
+  }
+  if (video.description !== undefined) {
+    if (typeof video.description !== "string") {
+      errors.push("Article video description must be a string");
+    } else if (
+      video.description.length > ARTICLE_VIDEO_DESCRIPTION_MAX_LENGTH
+    ) {
+      errors.push(
+        `Article video description must be ${ARTICLE_VIDEO_DESCRIPTION_MAX_LENGTH} characters or fewer`,
+      );
+    }
+  }
+
+  return errors;
+}
+
+function assertYouTubeVideoId(id: string): void {
+  if (!isYouTubeVideoId(id)) {
+    throw new Error("Invalid YouTube video id");
+  }
+}
+
+/** Privacy-enhanced player URL, loaded only after the reader presses play. */
+export function buildYouTubeEmbedUrl(id: string): string {
+  assertYouTubeVideoId(id);
+  return `https://www.youtube-nocookie.com/embed/${id}?rel=0&autoplay=1`;
+}
+
+/** Canonical player URL for structured data. */
+export function buildYouTubeStructuredDataEmbedUrl(id: string): string {
+  assertYouTubeVideoId(id);
+  return `https://www.youtube.com/embed/${id}`;
+}
+
+export function buildYouTubeWatchUrl(id: string): string {
+  assertYouTubeVideoId(id);
+  return `https://www.youtube.com/watch?v=${id}`;
+}
+
+/** Thumbnail URL for structured data only; the page never requests it. */
+export function buildYouTubeThumbnailUrl(id: string): string {
+  assertYouTubeVideoId(id);
+  return `https://i.ytimg.com/vi/${id}/hqdefault.jpg`;
+}

package/dist/{sitemap-B64QGT4l.d.ts → sitemap-CEjqxRaQ.d.ts}

@@ -1,4 +1,4 @@
-import { a as PublishedArticle, b as PublishedSite, c as PublishedAuthor } from './index-DsXjuPn4.js';
+import { a as PublishedArticle, b as PublishedSite, c as PublishedAuthor } from './index-CmjKzrH-.js';
 
 /**
  * SEO utilities for canonical URL generation and validation.

package/dist/{sitemap-Dy7Q4ATM.d.mts → sitemap-D1eInRA1.d.mts}

@@ -1,4 +1,4 @@
-import { a as PublishedArticle, b as PublishedSite, c as PublishedAuthor } from './index-DsXjuPn4.mjs';
+import { a as PublishedArticle, b as PublishedSite, c as PublishedAuthor } from './index-CmjKzrH-.mjs';
 
 /**
  * SEO utilities for canonical URL generation and validation.

package/dist/sitemap.d.mts

@@ -1,2 +1,2 @@
-import './index-DsXjuPn4.mjs';
-export { B as BlogSitemapConfig, N as NextjsSitemapEntry, S as SitemapChangeFreq, a as SitemapData, b as SitemapEntry, c as SitemapOptions, d as createBlogSitemapRoute, e as createDynamicBlogSitemap, g as generateBlogSitemapEntries, i as generateSitemap, j as generateSitemapIndex, s as sitemapToXml, v as validateSitemap } from './sitemap-Dy7Q4ATM.mjs';
+import './index-CmjKzrH-.mjs';
+export { B as BlogSitemapConfig, N as NextjsSitemapEntry, S as SitemapChangeFreq, a as SitemapData, b as SitemapEntry, c as SitemapOptions, d as createBlogSitemapRoute, e as createDynamicBlogSitemap, g as generateBlogSitemapEntries, i as generateSitemap, j as generateSitemapIndex, s as sitemapToXml, v as validateSitemap } from './sitemap-D1eInRA1.mjs';

package/dist/sitemap.d.ts

@@ -1,2 +1,2 @@
-import './index-DsXjuPn4.js';
-export { B as BlogSitemapConfig, N as NextjsSitemapEntry, S as SitemapChangeFreq, a as SitemapData, b as SitemapEntry, c as SitemapOptions, d as createBlogSitemapRoute, e as createDynamicBlogSitemap, g as generateBlogSitemapEntries, i as generateSitemap, j as generateSitemapIndex, s as sitemapToXml, v as validateSitemap } from './sitemap-B64QGT4l.js';
+import './index-CmjKzrH-.js';
+export { B as BlogSitemapConfig, N as NextjsSitemapEntry, S as SitemapChangeFreq, a as SitemapData, b as SitemapEntry, c as SitemapOptions, d as createBlogSitemapRoute, e as createDynamicBlogSitemap, g as generateBlogSitemapEntries, i as generateSitemap, j as generateSitemapIndex, s as sitemapToXml, v as validateSitemap } from './sitemap-CEjqxRaQ.js';

package/dist/types/contracts.ts

@@ -221,6 +221,38 @@ export interface PublishedSeriesContext {
   readonly articles: readonly PublishedSeriesArticleLink[];
 }
 
+/**
+ * Optional video shown at the top of an article.
+ *
+ * Only YouTube is supported. The page renders a click-to-play preview and
+ * loads the privacy-enhanced player only after the reader presses play.
+ */
+export interface PublishedArticleVideo {
+  /** Video host. Only "youtube" is supported. */
+  readonly provider: "youtube";
+
+  /** 11-character YouTube video id of the landscape video */
+  readonly id: string;
+
+  /** Video title, as on YouTube (used for the player label and VideoObject) */
+  readonly title: string;
+
+  /** Optional video description (VideoObject falls back to the article excerpt) */
+  readonly description?: string;
+
+  /** Upload date as an ISO 8601 date or date-time */
+  readonly uploadDate: string;
+
+  /** Optional ISO 8601 duration, e.g. "PT4M13S" */
+  readonly duration?: string;
+
+  /**
+   * Reserved: YouTube id of a vertical (Shorts) cut of the same video.
+   * Validated and stored, but not rendered yet.
+   */
+  readonly verticalId?: string;
+}
+
 /**
  * Represents a published article with all necessary metadata for rendering
  * on external blog platforms.
@@ -268,6 +300,9 @@ export interface PublishedArticle {
   /** Optional ordered series context for article navigation */
   readonly series?: PublishedSeriesContext;
 
+  /** Optional video shown in place of the featured image at the top */
+  readonly video?: PublishedArticleVideo;
+
   /** Featured image URL (optional) */
   readonly featuredImage?: string;
 

package/dist/types/index.d.mts

@@ -1 +1 @@
-export { h as PublishPayload, f as PublishResult, a as PublishedArticle, c as PublishedAuthor, i as PublishedAuthorSocialLinks, d as PublishedNewsletterSettings, b as PublishedSite, P as PublishedTopic } from '../index-DsXjuPn4.mjs';
+export { h as PublishPayload, f as PublishResult, a as PublishedArticle, i as PublishedArticleVideo, c as PublishedAuthor, j as PublishedAuthorSocialLinks, d as PublishedNewsletterSettings, b as PublishedSite, P as PublishedTopic } from '../index-CmjKzrH-.mjs';

package/dist/types/index.d.ts

@@ -1 +1 @@
-export { h as PublishPayload, f as PublishResult, a as PublishedArticle, c as PublishedAuthor, i as PublishedAuthorSocialLinks, d as PublishedNewsletterSettings, b as PublishedSite, P as PublishedTopic } from '../index-DsXjuPn4.js';
+export { h as PublishPayload, f as PublishResult, a as PublishedArticle, i as PublishedArticleVideo, c as PublishedAuthor, j as PublishedAuthorSocialLinks, d as PublishedNewsletterSettings, b as PublishedSite, P as PublishedTopic } from '../index-CmjKzrH-.js';

package/dist/types/index.ts

@@ -7,6 +7,7 @@
 
 export type {
   PublishedArticle,
+  PublishedArticleVideo,
   PublishedAuthor,
   PublishedAuthorSocialLinks,
   PublishedNewsletterSettings,

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@xexr/blog-platform",
-  "version": "1.1.7",
+  "version": "1.2.0",
   "description": "SEO-friendly blog platform for Next.js 15 with Bloggy integration",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Xexr/bloggy.git",
+    "directory": "packages/blog-platform"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {