@shopbb/helium 0.5.10 → 0.6.0

package/src/createCartHandler.ts

@@ -112,6 +112,36 @@ export function createCartHandler(options: CartHandlerOptions): CartHandler {
     }
   `;
 
+  const CART_DISCOUNT_CODES_UPDATE = /* GraphQL */ `
+    ${DEFAULT_CART_FRAGMENT}
+    mutation CartDiscountCodesUpdate($cartId: ID!, $discountCodes: [String!]) {
+      cartDiscountCodesUpdate(cartId: $cartId, discountCodes: $discountCodes) {
+        cart { ...CartReturn }
+        userErrors { field message code }
+      }
+    }
+  `;
+
+  const CART_DISCOUNT_SELECT = /* GraphQL */ `
+    ${DEFAULT_CART_FRAGMENT}
+    mutation CartDiscountSelect($cartId: ID!, $claimId: ID!) {
+      cartDiscountSelect(cartId: $cartId, claimId: $claimId) {
+        cart { ...CartReturn }
+        userErrors { field message code }
+      }
+    }
+  `;
+
+  const CART_DISCOUNT_CLEAR = /* GraphQL */ `
+    ${DEFAULT_CART_FRAGMENT}
+    mutation CartDiscountClear($cartId: ID!) {
+      cartDiscountClear(cartId: $cartId) {
+        cart { ...CartReturn }
+        userErrors { field message code }
+      }
+    }
+  `;
+
   // ----- Handler methods -----
 
   async function get(): Promise<any | null> {
@@ -177,6 +207,44 @@ export function createCartHandler(options: CartHandlerOptions): CartHandler {
     return { cart: data.cartLinesRemove.cart, userErrors: data.cartLinesRemove.userErrors };
   }
 
+  async function updateDiscountCodes(discountCodes: string[]): Promise<CartResult> {
+    const cartId = getCartId();
+    if (!cartId) {
+      // 没 cart 就先创建一个再应用 discount
+      const created = await create({});
+      if (!created.cart) return created;
+    }
+    const data = await storefront.mutate<{ cartDiscountCodesUpdate: { cart: any; userErrors: any[] } }>(
+      CART_DISCOUNT_CODES_UPDATE,
+      { variables: { cartId: getCartId(), discountCodes } },
+    );
+    return { cart: data.cartDiscountCodesUpdate.cart, userErrors: data.cartDiscountCodesUpdate.userErrors };
+  }
+
+  async function selectDiscount(claimId: string): Promise<CartResult> {
+    const cartId = getCartId();
+    if (!cartId) {
+      return { cart: null, userErrors: [{ message: 'No cart exists', code: 'NO_CART' }] };
+    }
+    const data = await storefront.mutate<{ cartDiscountSelect: { cart: any; userErrors: any[] } }>(
+      CART_DISCOUNT_SELECT,
+      { variables: { cartId, claimId } },
+    );
+    return { cart: data.cartDiscountSelect.cart, userErrors: data.cartDiscountSelect.userErrors };
+  }
+
+  async function clearDiscount(): Promise<CartResult> {
+    const cartId = getCartId();
+    if (!cartId) {
+      return { cart: null, userErrors: [{ message: 'No cart exists', code: 'NO_CART' }] };
+    }
+    const data = await storefront.mutate<{ cartDiscountClear: { cart: any; userErrors: any[] } }>(
+      CART_DISCOUNT_CLEAR,
+      { variables: { cartId } },
+    );
+    return { cart: data.cartDiscountClear.cart, userErrors: data.cartDiscountClear.userErrors };
+  }
+
   return {
     get,
     getCartId,
@@ -185,5 +253,8 @@ export function createCartHandler(options: CartHandlerOptions): CartHandler {
     addLines,
     updateLines,
     removeLines,
+    updateDiscountCodes,
+    selectDiscount,
+    clearDiscount,
   };
 }

package/src/csp/csp.tsx

@@ -0,0 +1,119 @@
+/**
+ * createContentSecurityPolicy + NonceProvider + <Script> + useNonce()
+ *
+ * 对齐 Hydrogen 的 CSP 工具集：服务端生成一次性 nonce（base64 random），通过
+ * Content-Security-Policy 头要求所有 inline script 带这个 nonce 才能执行；
+ * React 组件 <Script nonce> 自动注入 nonce 属性。
+ *
+ * 服务端：
+ *   const { nonce, header, NonceProvider } = createContentSecurityPolicy();
+ *   response.headers.set('Content-Security-Policy', header);
+ *   return ReactDOMServer.renderToReadableStream(
+ *     <NonceProvider value={nonce}><App /></NonceProvider>
+ *   );
+ *
+ * 客户端 / 组件内：
+ *   const nonce = useNonce();
+ *   <script nonce={nonce} dangerouslySetInnerHTML={...} />
+ *   // 或者用 <Script>
+ *   <Script>{`window.foo=1`}</Script>
+ */
+
+import * as React from 'react';
+
+// ============================================================
+// Nonce context
+// ============================================================
+
+const NonceContext = React.createContext<string | null>(null);
+
+export interface NonceProviderProps {
+  value: string;
+  children: React.ReactNode;
+}
+
+export function NonceProvider({ value, children }: NonceProviderProps) {
+  return <NonceContext.Provider value={value}>{children}</NonceContext.Provider>;
+}
+
+export function useNonce(): string | undefined {
+  const nonce = React.useContext(NonceContext);
+  return nonce || undefined;
+}
+
+// ============================================================
+// <Script> — 自动带 nonce 的 script tag
+// ============================================================
+
+export interface ScriptProps extends React.ScriptHTMLAttributes<HTMLScriptElement> {}
+
+export function Script(props: ScriptProps) {
+  const nonce = useNonce();
+  return <script nonce={nonce} {...props} />;
+}
+
+// ============================================================
+// createContentSecurityPolicy
+// ============================================================
+
+export interface CspOptions {
+  /** 额外的 script-src 来源（默认 'self'） */
+  scriptSrc?: string[];
+  /** 额外的 style-src（默认 'self' + 'unsafe-inline'） */
+  styleSrc?: string[];
+  /** 额外的 img-src（默认 'self' + data:） */
+  imgSrc?: string[];
+  /** connect-src（XHR / fetch 允许的目标） */
+  connectSrc?: string[];
+  /** font-src */
+  fontSrc?: string[];
+  /** frame-src */
+  frameSrc?: string[];
+  /** default-src */
+  defaultSrc?: string[];
+  /** Report-only 模式 */
+  reportOnly?: boolean;
+}
+
+export interface CspResult {
+  nonce: string;
+  /** 完整的 Content-Security-Policy header 字符串 */
+  header: string;
+  headerName: 'Content-Security-Policy' | 'Content-Security-Policy-Report-Only';
+  NonceProvider: typeof NonceProvider;
+}
+
+function randomNonce(): string {
+  // Workers / 浏览器 / Node 都有 crypto.getRandomValues
+  if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    let bin = '';
+    for (const b of bytes) bin += String.fromCharCode(b);
+    return btoa(bin).replace(/[+/=]/g, '');
+  }
+  // fallback
+  return Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2);
+}
+
+export function createContentSecurityPolicy(options: CspOptions = {}): CspResult {
+  const nonce = randomNonce();
+  const dirs: string[] = [];
+
+  dirs.push(`default-src ${(options.defaultSrc || ["'self'"]).join(' ')}`);
+  dirs.push(`script-src 'self' 'nonce-${nonce}' 'strict-dynamic' ${(options.scriptSrc || []).join(' ')}`.trim());
+  dirs.push(`style-src 'self' 'unsafe-inline' ${(options.styleSrc || []).join(' ')}`.trim());
+  dirs.push(`img-src 'self' data: blob: ${(options.imgSrc || []).join(' ')}`.trim());
+  if (options.connectSrc?.length) dirs.push(`connect-src 'self' ${options.connectSrc.join(' ')}`);
+  if (options.fontSrc?.length) dirs.push(`font-src 'self' ${options.fontSrc.join(' ')}`);
+  if (options.frameSrc?.length) dirs.push(`frame-src ${options.frameSrc.join(' ')}`);
+  dirs.push(`base-uri 'self'`);
+  dirs.push(`form-action 'self'`);
+
+  return {
+    nonce,
+    header: dirs.join('; '),
+    headerName: options.reportOnly ? 'Content-Security-Policy-Report-Only' : 'Content-Security-Policy',
+    NonceProvider,
+  };
+}

package/src/customer/createCustomerAccountClient.ts

@@ -0,0 +1,89 @@
+/**
+ * createCustomerAccountClient — 对齐 Hydrogen createCustomerAccountClient
+ *
+ * 给"买家账号"操作提供 GraphQL client + 简单 token 管理。
+ *
+ * Hydrogen 用 Customer Account API（OAuth + PKCE）；我们 shopbb 用简化的
+ * buyer JWT（service signed token），所以这里**不实现 OAuth login/logout**，
+ * 只提供 GraphQL query/mutate 和 isLoggedIn 检测。商家用 oxygen 提供的
+ * REST `/api/buyer/login` 完成登录，把 token 存进 localStorage。
+ *
+ * 用法（客户端）：
+ *
+ *   const customer = createCustomerAccountClient({
+ *     customerApiUrl: 'https://api.../customer/api/2026-04/graphql',
+ *     getAccessToken: () => localStorage.getItem('shopbb:buyer_token'),
+ *   });
+ *
+ *   const data = await customer.query(`{ customer { id email } }`);
+ *   await customer.mutate(`mutation { customerAddressCreate(...) { ... } }`);
+ *   const loggedIn = await customer.isLoggedIn();
+ *
+ * 与 Hydrogen 区别：
+ *   - getAccessToken 默认从 localStorage / cookie 取（商家可覆盖）
+ *   - 不带 OAuth redirect helper（commerce 简化）
+ *   - login / logout 由商家应用层负责（调 oxygen REST）
+ */
+
+export interface CustomerAccountClientOptions {
+  /** Customer GraphQL endpoint */
+  customerApiUrl: string;
+  /** Token 取法。不传时从 localStorage 取 'shopbb:buyer_token'。SSR 阶段可传 cookie 解析 */
+  getAccessToken?: () => string | null | Promise<string | null>;
+  /** 自定义 headers（如 store_id） */
+  extraHeaders?: Record<string, string>;
+}
+
+export interface CustomerAccountClient {
+  query<T = any>(query: string, variables?: Record<string, any>): Promise<T>;
+  mutate<T = any>(mutation: string, variables?: Record<string, any>): Promise<T>;
+  isLoggedIn(): Promise<boolean>;
+  getAccessToken(): Promise<string | null>;
+  getApiUrl(): string;
+}
+
+export function createCustomerAccountClient(options: CustomerAccountClientOptions): CustomerAccountClient {
+  const { customerApiUrl, getAccessToken: getter, extraHeaders } = options;
+
+  async function getAccessToken(): Promise<string | null> {
+    if (getter) return await getter();
+    if (typeof localStorage === 'undefined') return null;
+    return localStorage.getItem('shopbb:buyer_token') || localStorage.getItem('shopflare:buyer_token');
+  }
+
+  async function call<T = any>(
+    body: string,
+    variables?: Record<string, any>,
+  ): Promise<T> {
+    const token = await getAccessToken();
+    if (!token) throw new Error('not authenticated');
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${token}`,
+      ...(extraHeaders || {}),
+    };
+    const res = await fetch(customerApiUrl, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ query: body, variables }),
+    });
+    const json: any = await res.json().catch(() => null);
+    if (!res.ok || json?.errors?.length) {
+      throw new Error(json?.errors?.[0]?.message || `Customer API error: HTTP ${res.status}`);
+    }
+    return json.data as T;
+  }
+
+  async function isLoggedIn(): Promise<boolean> {
+    const token = await getAccessToken();
+    return !!token;
+  }
+
+  return {
+    query: (q, v) => call(q, v),
+    mutate: (m, v) => call(m, v),
+    isLoggedIn,
+    getAccessToken,
+    getApiUrl: () => customerApiUrl,
+  };
+}

package/src/handleCartFormAction.ts

@@ -0,0 +1,129 @@
+/**
+ * handleCartFormAction
+ *
+ * 服务端统一处理 <CartForm> 提交的 helper。对齐 Hydrogen 的"单一 /cart route action"模式：
+ *
+ *   import { CartForm, handleCartFormAction } from '@shopbb/helium';
+ *
+ *   // shopflare server.tsx POST handler
+ *   if (url.pathname === '/cart' && request.method === 'POST') {
+ *     const ctx = createHeliumContext({ ... });
+ *     const response = await handleCartFormAction(request, ctx.cart, {
+ *       responseHeaders: ctx.responseHeaders,
+ *     });
+ *     return response;
+ *   }
+ *
+ * 行为：
+ *   1. 从 request.formData() 调 CartForm.getFormInput 解析出 { action, inputs }
+ *   2. switch(action) 分发到 cartHandler 对应方法
+ *   3. 返回 JSON Response，里面带 { cart, userErrors, errors? } 和 Set-Cookie header
+ *   4. 客户端 fetch 拿到这个 Response，调 CartProvider.applyCart 同步 state
+ *
+ * 也支持 progressive enhancement：JS 没加载时浏览器原生 form POST + 303 redirect 回 referrer。
+ * 通过 query param `?_progressive=1` 或检测 `Accept: text/html` 触发 303 模式。
+ */
+
+import { CartForm, type CartFormInput } from './components/CartForm';
+import type { CartHandler, CartResult } from './types';
+
+export interface HandleCartFormActionOptions {
+  /** 服务端构造的 responseHeaders（Set-Cookie 写在这里） */
+  responseHeaders?: Headers;
+  /** JS 未加载时浏览器原生 form POST → 303 redirect 到这个 URL（默认 Referer 或 /cart） */
+  redirectTo?: string;
+  /**
+   * 自定义 action 处理器（CartForm 支持 `Custom${string}` action）。
+   * 第二个参数是 cartHandler，可以组合调用。
+   */
+  customActions?: Record<string, (inputs: any, cart: CartHandler) => Promise<CartResult>>;
+}
+
+export async function handleCartFormAction(
+  request: Request,
+  cart: CartHandler,
+  options: HandleCartFormActionOptions = {},
+): Promise<Response> {
+  const { responseHeaders, redirectTo, customActions } = options;
+
+  let formData: FormData;
+  try {
+    formData = await request.formData();
+  } catch (e: any) {
+    return jsonResponse({ error: 'Invalid form data: ' + (e.message || e), userErrors: [] }, 400, responseHeaders);
+  }
+
+  let parsed: CartFormInput;
+  try {
+    parsed = CartForm.getFormInput(formData);
+  } catch (e: any) {
+    return jsonResponse({ error: e.message || String(e), userErrors: [] }, 400, responseHeaders);
+  }
+
+  let result: CartResult;
+  try {
+    switch (parsed.action) {
+      case 'LinesAdd':
+        result = await cart.addLines((parsed.inputs as any).lines);
+        break;
+      case 'LinesUpdate':
+        result = await cart.updateLines((parsed.inputs as any).lines);
+        break;
+      case 'LinesRemove':
+        result = await cart.removeLines((parsed.inputs as any).lineIds);
+        break;
+      case 'DiscountCodesUpdate':
+        result = await cart.updateDiscountCodes((parsed.inputs as any).discountCodes || []);
+        break;
+      case 'Create':
+        result = await cart.create((parsed.inputs as any).input);
+        break;
+      default:
+        // shopbb-extension actions
+        if (parsed.action === 'CustomDiscountSelect') {
+          result = await cart.selectDiscount((parsed.inputs as any).claimId);
+          break;
+        }
+        if (parsed.action === 'CustomDiscountClear') {
+          result = await cart.clearDiscount();
+          break;
+        }
+        // 用户自定义
+        if (parsed.action.startsWith('Custom') && customActions && customActions[parsed.action]) {
+          result = await customActions[parsed.action](parsed.inputs, cart);
+          break;
+        }
+        return jsonResponse(
+          { error: `Unknown CartForm action: "${parsed.action}"`, userErrors: [] },
+          400,
+          responseHeaders,
+        );
+    }
+  } catch (e: any) {
+    return jsonResponse({ error: e.message || String(e), userErrors: [] }, 500, responseHeaders);
+  }
+
+  // 写入 Set-Cookie（如果 cart id 变化）
+  if (result.cart?.id && responseHeaders) {
+    cart.setCartId(result.cart.id);
+  }
+
+  // 浏览器原生 form POST（无 JS）→ 303 redirect 回 referrer
+  // 判定：只信 X-Helium-Fetch header（CartForm fetch 显式带）
+  // 没有该 header → 视为原生 form POST，必须用 303 让浏览器跳转（不然显示 raw JSON）
+  const isJsFetch = !!request.headers.get('X-Helium-Fetch');
+  if (!isJsFetch) {
+    const target = redirectTo || request.headers.get('Referer') || '/cart';
+    const headers = new Headers(responseHeaders || {});
+    headers.set('Location', target);
+    return new Response(null, { status: 303, headers });
+  }
+
+  return jsonResponse({ cart: result.cart, userErrors: result.userErrors }, 200, responseHeaders);
+}
+
+function jsonResponse(body: any, status: number, responseHeaders?: Headers): Response {
+  const headers = new Headers(responseHeaders || {});
+  headers.set('Content-Type', 'application/json; charset=utf-8');
+  return new Response(JSON.stringify(body), { status, headers });
+}

package/src/index.ts

@@ -18,8 +18,32 @@ export { createStorefrontClient } from './createStorefrontClient';
 export { createCartHandler, DEFAULT_CART_FRAGMENT } from './createCartHandler';
 export { cartGetIdDefault, cartSetIdDefault } from './cart-id';
 export type { CartSetIdOptions } from './cart-id';
+export { handleCartFormAction } from './handleCartFormAction';
+export type { HandleCartFormActionOptions } from './handleCartFormAction';
 export { CacheNone, CacheShort, CacheLong, CacheCustom } from './cache';
 
+// 服务端工具
+export { createWithCache, InMemoryCache } from './cache/withCache';
+export type { WithCache, WithCacheOptions, CacheKey } from './cache/withCache';
+export { storefrontRedirect } from './routing/storefrontRedirect';
+export type { StorefrontRedirectOptions } from './routing/storefrontRedirect';
+export { getSeoMeta } from './seo/getSeoMeta';
+export type { SeoConfig, SeoResult } from './seo/getSeoMeta';
+export { createCustomerAccountClient } from './customer/createCustomerAccountClient';
+export type { CustomerAccountClient, CustomerAccountClientOptions } from './customer/createCustomerAccountClient';
+export { createContentSecurityPolicy, NonceProvider, useNonce, Script } from './csp/csp';
+export type { CspOptions, CspResult, NonceProviderProps, ScriptProps } from './csp/csp';
+export { getSitemap, getSitemapIndex } from './sitemap/sitemap';
+export type {
+  SitemapResource, GetSitemapOptions, GetSitemapIndexOptions,
+} from './sitemap/sitemap';
+
+// 工具
+export { flattenConnection } from './utils/flattenConnection';
+export type { Connection } from './utils/flattenConnection';
+export { parseGid } from './utils/parseGid';
+export type { ParsedGid } from './utils/parseGid';
+
 // Re-export all types
 export type {
   CacheStrategy,

package/src/routing/storefrontRedirect.ts

@@ -0,0 +1,86 @@
+/**
+ * storefrontRedirect — 对齐 Hydrogen storefrontRedirect
+ *
+ * 商家从老平台搬过来时常有 URL 改写需求，Shopify 在 admin 里维护 redirects 表。
+ * 商家 storefront 收到 404 时，调用 `storefrontRedirect({request, storefront})`
+ * 查 oxygen 的 redirects 表，若有匹配 → 301 / 302 跳到新地址。
+ *
+ * 用法（在 404 catch handler 里）：
+ *
+ *   if (response.status === 404) {
+ *     const redirect = await storefrontRedirect({ request, storefront });
+ *     if (redirect) return redirect;
+ *   }
+ *   return notFound();
+ *
+ * 简化版当前实现：调用 oxygen REST `/api/redirects?path=...`，未来 oxygen 加这条
+ * endpoint。商家可以传 fetcher 自定义查询源。
+ */
+
+export interface StorefrontRedirectOptions {
+  /** 当前 Request，从 URL 取 path 查 redirect */
+  request: Request;
+  /** oxygen Storefront client（用于 GraphQL urlRedirects 查询）；或自定义 fetcher */
+  storefront?: { query: (q: string, opts?: any) => Promise<any> };
+  /**
+   * 自定义查询 redirect：传入 path，返回目标 URL（找不到返回 null）。
+   * 优先级高于 storefront query。
+   */
+  resolveRedirect?: (path: string) => Promise<string | null>;
+  /** 重定向状态码：默认 301（永久） */
+  status?: 301 | 302 | 307 | 308;
+  /** 是否仅域内 path（避免 open redirect 攻击）。默认 true */
+  noExternal?: boolean;
+}
+
+const URL_REDIRECTS_QUERY = /* GraphQL */ `
+  query UrlRedirects($first: Int!, $query: String) {
+    urlRedirects(first: $first, query: $query) {
+      nodes { path target }
+    }
+  }
+`;
+
+export async function storefrontRedirect(
+  options: StorefrontRedirectOptions,
+): Promise<Response | null> {
+  const { request, storefront, resolveRedirect, status = 301, noExternal = true } = options;
+  const url = new URL(request.url);
+  const path = url.pathname + (url.search || '');
+
+  let target: string | null = null;
+
+  if (resolveRedirect) {
+    target = await resolveRedirect(path).catch(() => null);
+  } else if (storefront) {
+    try {
+      const data: any = await storefront.query(
+        URL_REDIRECTS_QUERY,
+        { variables: { first: 1, query: `path:${path}` } },
+      );
+      const match = data?.urlRedirects?.nodes?.find((r: any) => r.path === path);
+      target = match?.target ?? null;
+    } catch {
+      target = null;
+    }
+  }
+
+  if (!target) return null;
+
+  if (noExternal) {
+    // 防 open redirect — 只允许相对路径或同域
+    if (target.startsWith('//') || /^https?:\/\//i.test(target)) {
+      try {
+        const t = new URL(target);
+        if (t.host !== url.host) return null;
+      } catch {
+        return null;
+      }
+    }
+  }
+
+  return new Response(null, {
+    status,
+    headers: { Location: target },
+  });
+}

package/src/seo/getSeoMeta.ts

@@ -0,0 +1,125 @@
+/**
+ * getSeoMeta + <Seo> — 对齐 Hydrogen 的 SEO 工具
+ *
+ * Hydrogen 通过 Remix `meta` export 返回 SeoConfig；我们这里因不绑 Remix，
+ * 提供一个 `getSeoMeta(config)` 函数返回 HTML `<meta>` 字符串，供 SSR
+ * 服务端拼到 `<head>` 里。也提供 `<Seo data={config} />` 客户端组件
+ * （hydrate 阶段更新 document title / meta），用作 SPA 路由切换。
+ *
+ * 用法（服务端）：
+ *
+ *   const seo = getSeoMeta({
+ *     title: product.title,
+ *     description: product.description,
+ *     image: product.featuredImage?.url,
+ *     url: 'https://shop/products/xxx',
+ *     type: 'product',
+ *   });
+ *   // seo = { title, htmlTags: '<title>...</title><meta ...>' }
+ *   const html = `<head>${seo.htmlTags}...</head>`;
+ */
+
+export interface SeoConfig {
+  /** Page title — appears in <title> and og:title */
+  title?: string;
+  /** Suffix appended to title with separator " · " — usually shop name */
+  titleTemplate?: string;
+  /** Meta description / og:description */
+  description?: string;
+  /** Canonical URL / og:url */
+  url?: string;
+  /** og:image */
+  image?: string | { url: string; width?: number; height?: number; altText?: string };
+  /** og:type — "website" | "product" | "article" | ... */
+  type?: 'website' | 'product' | 'article' | string;
+  /** twitter:card — "summary" | "summary_large_image" */
+  twitterCard?: 'summary' | 'summary_large_image' | string;
+  /** Additional og:* fields */
+  og?: Record<string, string>;
+  /** robots — "index,follow" / "noindex" */
+  robots?: string;
+  /** JSON-LD structured data */
+  jsonLd?: Record<string, any> | Array<Record<string, any>>;
+  /** lang — "zh-CN" / "en" */
+  language?: string;
+}
+
+export interface SeoResult {
+  title: string;
+  description: string;
+  /** 直接拼接到 <head> 的 HTML 字符串 */
+  htmlTags: string;
+  /** 关键 meta，方便商家自己拼 */
+  meta: Array<{ name?: string; property?: string; content: string }>;
+  /** 完整 title（含 template） */
+  fullTitle: string;
+}
+
+function escapeHtml(s: string): string {
+  return String(s).replace(/[<>&"']/g, (c) =>
+    ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;', "'": '&#39;' }[c]!),
+  );
+}
+
+/**
+ * 根据 config 生成 <head> 该有的全部 SEO 标签字符串。
+ */
+export function getSeoMeta(config: SeoConfig): SeoResult {
+  const {
+    title, titleTemplate, description = '', url, image, type = 'website',
+    twitterCard = 'summary_large_image', og = {}, robots, jsonLd,
+  } = config;
+
+  const fullTitle = title
+    ? (titleTemplate ? `${title} · ${titleTemplate}` : title)
+    : (titleTemplate || '');
+
+  const imgUrl = typeof image === 'string' ? image : image?.url;
+  const imgAlt = typeof image === 'object' ? image?.altText : undefined;
+  const imgW = typeof image === 'object' ? image?.width : undefined;
+  const imgH = typeof image === 'object' ? image?.height : undefined;
+
+  const meta: SeoResult['meta'] = [];
+  if (description) meta.push({ name: 'description', content: description });
+  if (robots) meta.push({ name: 'robots', content: robots });
+
+  if (fullTitle) meta.push({ property: 'og:title', content: fullTitle });
+  if (description) meta.push({ property: 'og:description', content: description });
+  if (url) meta.push({ property: 'og:url', content: url });
+  meta.push({ property: 'og:type', content: type });
+  if (imgUrl) meta.push({ property: 'og:image', content: imgUrl });
+  if (imgAlt) meta.push({ property: 'og:image:alt', content: imgAlt });
+  if (imgW) meta.push({ property: 'og:image:width', content: String(imgW) });
+  if (imgH) meta.push({ property: 'og:image:height', content: String(imgH) });
+
+  for (const [k, v] of Object.entries(og)) {
+    meta.push({ property: k.startsWith('og:') ? k : `og:${k}`, content: v });
+  }
+
+  meta.push({ name: 'twitter:card', content: twitterCard });
+  if (fullTitle) meta.push({ name: 'twitter:title', content: fullTitle });
+  if (description) meta.push({ name: 'twitter:description', content: description });
+  if (imgUrl) meta.push({ name: 'twitter:image', content: imgUrl });
+
+  const parts: string[] = [];
+  if (fullTitle) parts.push(`<title>${escapeHtml(fullTitle)}</title>`);
+  if (url) parts.push(`<link rel="canonical" href="${escapeHtml(url)}" />`);
+  for (const m of meta) {
+    const attr = m.name ? `name="${m.name}"` : `property="${m.property}"`;
+    parts.push(`<meta ${attr} content="${escapeHtml(m.content)}" />`);
+  }
+  if (jsonLd) {
+    const data = Array.isArray(jsonLd) ? jsonLd : [jsonLd];
+    for (const d of data) {
+      parts.push(`<script type="application/ld+json">${JSON.stringify(d).replace(/</g, '\\u003c')}</script>`);
+    }
+  }
+
+  return {
+    title: fullTitle,
+    description,
+    meta,
+    fullTitle,
+    htmlTags: parts.join('\n'),
+  };
+}