@ubean/seo 0.1.13 → 0.2.0

package/dist/json-ld.js

@@ -0,0 +1,159 @@
+//#region src/json-ld.ts
+/**
+* 渲染为 `<script type="application/ld+json">` HTML 字符串。
+*
+* 安全性:
+* - `<\/script>` 拆分为 `<\/script>` 防止提前结束 script 标签
+* - U+2028 / U+2029 替换为 Unicode 转义(防止 JS 解析器在 JSON 中断行)
+*
+* @example
+* ```ts
+* renderJsonLdScript({ '@context': 'https://schema.org', '@type': 'Organization', name: 'ubean' })
+* // => <script type="application/ld+json">{"@context":"https://schema.org","@type":"Organization","name":"ubean"}<\/script>
+* ```
+*/
+function renderJsonLdScript(schema) {
+	return `<script type="application/ld+json">${JSON.stringify(schema).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029")}<\/script>`;
+}
+/**
+* 把多个 JSON-LD schema 合并为 `@graph` 数组(对齐 schema.org 推荐做法)。
+*
+* 若输入只有一个 schema,直接返回(避免不必要的 @graph 包装)。
+*/
+function mergeJsonLd(schemas) {
+	if (schemas.length === 0) return {};
+	if (schemas.length === 1) return schemas[0];
+	if (schemas.every((s) => s["@context"] === schemas[0]["@context"]) && schemas[0]["@context"]) return {
+		"@context": schemas[0]["@context"],
+		"@graph": schemas.map(({ "@context": _c, ...rest }) => rest)
+	};
+	return { "@graph": schemas };
+}
+/**
+* 定义一个 JSON-LD schema(纯函数,无副作用)。
+*
+* @example
+* ```ts
+* const org = defineJsonLd({
+*   '@context': 'https://schema.org',
+*   '@type': 'Organization',
+*   name: 'ubean',
+*   url: 'https://ubean.dev'
+* });
+* // 在 SSR 中注入到 head:
+* renderJsonLdScript(org)
+* ```
+*/
+function defineJsonLd(schema) {
+	return schema;
+}
+/**
+* Vue composable:把 JSON-LD schema 注入到 head(通过 `useHead`)。
+*
+* 在非 Vue setup 上下文中静默降级(返回 schema 本身),不抛错。
+*
+* @example
+* ```vue
+* <script setup>
+* useSchemaOrg({
+*   '@context': 'https://schema.org',
+*   '@type': 'Article',
+*   headline: 'My Article',
+*   author: { '@type': 'Person', name: 'John' }
+* });
+* <\/script>
+* ```
+*/
+function useSchemaOrg(schema) {
+	try {
+		const head = globalThis.__UBEAN_HEAD__;
+		if (head && typeof head.push === "function") {
+			const scriptContent = typeof schema === "function" ? JSON.stringify(schema) : JSON.stringify(schema);
+			head.push({ script: [{
+				type: "application/ld+json",
+				innerHTML: scriptContent
+			}] });
+		}
+	} catch {}
+	return schema;
+}
+/**
+* 把多个 JSON-LD schema 渲染为 `<script>` 标签数组(SSR 用)。
+*/
+function renderJsonLdScripts(schemas) {
+	return schemas.map((s) => renderJsonLdScript(s)).join("\n");
+}
+/**
+* 常见 Schema.org 类型的便捷工厂函数(覆盖 80% 用例)。
+*/
+const schemaOrg = {
+	organization(options) {
+		return {
+			"@context": "https://schema.org",
+			"@type": "Organization",
+			name: options.name,
+			...options.url ? { url: options.url } : {},
+			...options.logo ? { logo: options.logo } : {},
+			...options.sameAs ? { sameAs: options.sameAs } : {}
+		};
+	},
+	website(options) {
+		return {
+			"@context": "https://schema.org",
+			"@type": "WebSite",
+			name: options.name,
+			url: options.url,
+			...options.description ? { description: options.description } : {}
+		};
+	},
+	article(options) {
+		return {
+			"@context": "https://schema.org",
+			"@type": "Article",
+			headline: options.headline,
+			author: {
+				"@type": "Person",
+				name: options.author
+			},
+			datePublished: options.datePublished,
+			...options.image ? { image: options.image } : {},
+			...options.publisher ? { publisher: {
+				"@type": "Organization",
+				name: options.publisher
+			} } : {}
+		};
+	},
+	breadcrumb(items) {
+		return {
+			"@context": "https://schema.org",
+			"@type": "BreadcrumbList",
+			itemListElement: items.map((item, i) => ({
+				"@type": "ListItem",
+				position: i + 1,
+				name: item.name,
+				item: item.url
+			}))
+		};
+	},
+	product(options) {
+		return {
+			"@context": "https://schema.org",
+			"@type": "Product",
+			name: options.name,
+			...options.description ? { description: options.description } : {},
+			...options.brand ? { brand: {
+				"@type": "Brand",
+				name: options.brand
+			} } : {},
+			...options.sku ? { sku: options.sku } : {},
+			...options.price ? { offers: {
+				"@type": "Offer",
+				price: options.price,
+				...options.priceCurrency ? { priceCurrency: options.priceCurrency } : {},
+				...options.availability ? { availability: `https://schema.org/${options.availability}` } : {}
+			} } : {}
+		};
+	}
+};
+//#endregion
+export { defineJsonLd, mergeJsonLd, renderJsonLdScript, renderJsonLdScripts, schemaOrg, useSchemaOrg };

package/dist/og-image.d.ts

@@ -0,0 +1,196 @@
+//#region src/og-image.d.ts
+/**
+ * Satori 兼容的 VDOM 节点。Satori 接受 React-like 元素树,这里用最小化结构类型
+ * 避免直接依赖 `satori` 类型(它是 optional peer 依赖)。
+ *
+ * 形状与 React.createElement 返回值兼容:`{ type, props: { children, style, ... } }`。
+ */
+interface SatoriNode {
+  type: string;
+  props: {
+    children?: SatoriNode | SatoriNode[] | string;
+    style?: Record<string, unknown>;
+    [key: string]: unknown;
+  };
+}
+/**
+ * Satori 字体描述符。
+ */
+interface SatoriFont {
+  name: string;
+  data: ArrayBuffer | Buffer;
+  weight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+  style?: 'normal' | 'italic';
+}
+/**
+ * `ImageResponse` / `renderOgImage` 共享的渲染选项。
+ */
+interface OgImageOptions {
+  /** 图像宽度(px)。默认 1200。 */
+  width?: number;
+  /** 图像高度(px)。默认 630。 */
+  height?: number;
+  /**
+   * 字体列表。Satori 至少需要一个字体才能渲染。
+   * 用 `loadDefaultFont()` / `loadFontFromFile()` / `loadFontFromUrl()` 生成。
+   */
+  fonts?: SatoriFont[];
+  /**
+   * 是否禁用 resvg 转换(只输出 SVG)。默认 false(输出 PNG)。
+   * 适用于调试或对 PNG 转换有自定义需求的场景。
+   */
+  svgOnly?: boolean;
+  /**
+   * resvg 选项(透传给 `@resvg/resvg-js`)。可选。
+   */
+  resvgOptions?: Record<string, unknown>;
+  /**
+   * 响应的 Cache-Control header。默认 `public, max-age=86400`。
+   */
+  cacheControl?: string;
+  /**
+   * debug:开启 Satori debug 模式(输出额外日志)。默认 false。
+   */
+  debug?: boolean;
+}
+/**
+ * 内置模板的输入参数。
+ */
+interface OgTemplateInput {
+  /** 主标题(必填)。 */
+  title: string;
+  /** 副标题/描述。 */
+  description?: string;
+  /** 站点/作者名(显示在底部)。 */
+  siteName?: string;
+  /** Logo URL 或域名(显示在左上角)。 */
+  logo?: string;
+  /** 主题色(用于背景渐变)。 */
+  themeColor?: string;
+  /** 文本颜色。默认 `#ffffff`。 */
+  textColor?: string;
+  /** 背景图片 URL(可选,覆盖渐变)。 */
+  backgroundImage?: string;
+}
+/**
+ * 默认字体 URL(使用 Google Fonts 的 Inter 字体,常规字重 400)。
+ *
+ * 在生产环境建议使用 `loadFontFromFile()` 加载本地字体,避免运行时网络依赖。
+ */
+declare const DEFAULT_FONT_URL = "https://fonts.gstatic.com/s/inter/v12/UcCO3FwrK3iLTeHuS_fvQtMwCp50KnMa1ZL7.woff2";
+/**
+ * 默认字体名。
+ */
+declare const DEFAULT_FONT_NAME = "Inter";
+/**
+ * 从 URL 加载字体(返回 Satori 兼容的 `SatoriFont`)。
+ *
+ * @example
+ * ```ts
+ * const font = await loadFontFromUrl('https://fonts.gstatic.com/.../inter.woff2', 'Inter');
+ * ```
+ */
+declare function loadFontFromUrl(url: string, name: string, weight?: SatoriFont['weight'], fontStyle?: SatoriFont['style']): Promise<SatoriFont>;
+/**
+ * 从本地文件加载字体。
+ *
+ * @example
+ * ```ts
+ * const font = loadFontFromFile('./fonts/inter-regular.woff2', 'Inter');
+ * ```
+ */
+declare function loadFontFromFile(path: string, name: string, weight?: SatoriFont['weight'], fontStyle?: SatoriFont['style']): SatoriFont;
+/**
+ * 加载默认字体(Inter Regular,从 Google Fonts CDN 拉取)。
+ *
+ * 注意:此函数依赖网络访问。Cloudflare Workers 等边缘环境需要 fetch API 可用。
+ * 离线/生产环境推荐用 `loadFontFromFile()` 替代。
+ */
+declare function loadDefaultFont(): Promise<SatoriFont>;
+/**
+ * 默认 OG 图模板:渐变背景 + 居中标题 + 副标题 + 底部站点名。
+ *
+ * 返回 Satori 兼容的 VDOM 树。
+ */
+declare function defaultTemplate(input: OgTemplateInput): SatoriNode;
+/**
+ * 文章模板:左对齐标题 + 日期/作者元信息。
+ */
+declare function articleTemplate(input: OgTemplateInput & {
+  author?: string;
+  date?: string;
+}): SatoriNode;
+/**
+ * 简单的颜色调亮/调暗工具(用于生成渐变背景)。
+ *
+ * `percent` 为负数调暗,正数调亮。范围 -100..100。
+ */
+declare function shadeColor(hex: string, percent: number): string;
+/**
+ * 把 Satori VDOM 节点渲染为 PNG Buffer(或 SVG 字符串,当 `svgOnly: true` 时)。
+ *
+ * @returns `{ body, contentType }` —— body 为 Buffer/字符串,contentType 为 MIME 类型
+ */
+declare function renderToImage(node: SatoriNode, options?: OgImageOptions): Promise<{
+  body: Buffer | string;
+  contentType: string;
+}>;
+/**
+ * 对齐 Next.js `ImageResponse` 类。接收 Satori VDOM 节点,返回 PNG `Response`。
+ *
+ * 实现策略:body 使用 `ReadableStream`,在 stream 被 consume 时才执行实际的
+ * satori + resvg 渲染。这样构造函数可以保持同步,符合 Next.js
+ * `return new ImageResponse(...)` 的用法。
+ *
+ * @example
+ * ```ts
+ * // src/routes/og.ts
+ * import { ImageResponse, defaultTemplate, loadDefaultFont } from '@ubean/seo/og-image';
+ *
+ * export const GET = defineHandler(async () => {
+ *   const fonts = [await loadDefaultFont()];
+ *   const node = defaultTemplate({ title: 'Hello ubean', siteName: 'ubean' });
+ *   return new ImageResponse(node, { fonts });
+ * });
+ * ```
+ *
+ * 也可用于 `src/opengraph-image.ts` 约定文件:
+ * ```ts
+ * // src/opengraph-image.ts
+ * import { ImageResponse, defaultTemplate, loadDefaultFont } from '@ubean/seo/og-image';
+ * export default async function GET() {
+ *   const fonts = [await loadDefaultFont()];
+ *   return new ImageResponse(defaultTemplate({ title: 'ubean' }), { fonts });
+ * }
+ * ```
+ */
+declare class ImageResponse extends Response {
+  constructor(node: SatoriNode, options?: OgImageOptions);
+}
+/**
+ * 一步到位渲染 OG 图(模板 + 渲染 + Response)。
+ *
+ * @example
+ * ```ts
+ * // src/routes/og.ts
+ * import { renderOgImage } from '@ubean/seo/og-image';
+ * export const GET = defineHandler(async () => {
+ *   return renderOgImage({ title: 'Hello world', siteName: 'ubean' });
+ * });
+ * ```
+ */
+declare function renderOgImage(input: OgTemplateInput, options?: OgImageOptions): Promise<Response>;
+/**
+ * 用文章模板渲染 OG 图。
+ */
+declare function renderArticleOgImage(input: OgTemplateInput & {
+  author?: string;
+  date?: string;
+}, options?: OgImageOptions): Promise<Response>;
+/**
+ * 检测运行时是否安装了 OG 图渲染所需的依赖。
+ * 用于在不实际渲染的情况下判断能力可用性(例如 DevTools 信息展示)。
+ */
+declare function isOgImageSupported(): Promise<boolean>;
+//#endregion
+export { DEFAULT_FONT_NAME, DEFAULT_FONT_URL, ImageResponse, OgImageOptions, OgTemplateInput, SatoriFont, SatoriNode, articleTemplate, defaultTemplate, isOgImageSupported, loadDefaultFont, loadFontFromFile, loadFontFromUrl, renderArticleOgImage, renderOgImage, renderToImage, shadeColor };