@weaverse/next 0.1.0-alpha.8 → 1.0.0

package/src/seo.ts

@@ -0,0 +1,157 @@
+import type { PageSEOData } from '@weaverse/schema'
+import type { Metadata } from 'next'
+import type { WeaverseNextLoaderData, WeaverseNextPageData } from './types'
+
+/** Object containing an optional Weaverse page for SEO extraction. */
+export interface WeaverseNextSeoPageContainer {
+  /** Page whose published SEO fields should be formatted. */
+  page?: WeaverseNextPageData | null
+}
+
+/** Input accepted by {@link getWeaverseNextSeoMetadata}. */
+export type WeaverseNextSeoInput =
+  | WeaverseNextLoaderData
+  | WeaverseNextPageData
+  | WeaverseNextSeoPageContainer
+  | null
+  | undefined
+
+/** Open Graph metadata accepted by Next.js's `Metadata` API. */
+export type NextOpenGraph = NonNullable<Metadata['openGraph']>
+
+/** Twitter card metadata accepted by Next.js's `Metadata` API. */
+export type NextTwitter = NonNullable<Metadata['twitter']>
+
+/**
+ * Weaverse page SEO expressed as a subset of Next's `Metadata`. Assignable to
+ * `Metadata` as-is: `const metadata: Metadata = getWeaverseNextSeoMetadata(data)`.
+ */
+export interface WeaverseNextSeoMetadata {
+  /** Canonical URL settings for Next's metadata API. */
+  alternates?: {
+    /** Preferred URL for search indexing. */
+    canonical?: string
+  }
+  /** Page meta description. */
+  description?: string
+  /** Page meta keywords. */
+  keywords?: string
+  /** Open Graph metadata normalized to Next's supported union. */
+  openGraph?: NextOpenGraph
+  /** Search crawler indexing and link-following directives. */
+  robots: {
+    /** Whether crawlers may follow links on the page. */
+    follow: boolean
+    /** Whether crawlers may index the page. */
+    index: boolean
+  }
+  /** Page title. */
+  title?: string
+  /** Twitter card metadata normalized for Next's metadata API. */
+  twitter?: NextTwitter
+}
+
+function hasOpenGraphContent(seo: PageSEOData['openGraph']): boolean {
+  return Boolean(seo?.title || seo?.description || seo?.image || seo?.type)
+}
+
+function hasTwitterContent(seo: PageSEOData['twitter']): boolean {
+  return Boolean(seo?.title || seo?.description || seo?.image || seo?.cardType)
+}
+
+function normalizeTwitterCard(
+  cardType: NonNullable<PageSEOData['twitter']>['cardType']
+): 'summary' | 'summary_large_image' {
+  return cardType === 'summary_large_image' ? 'summary_large_image' : 'summary'
+}
+
+/**
+ * Map a Builder Open Graph type onto Next's `OpenGraphType` union. Every
+ * Builder value except `product` exists in Next's union and is preserved
+ * verbatim; `product` is not modeled by Next and makes `generateMetadata()`
+ * throw, so it degrades to `website` — the closest renderable equivalent.
+ */
+function normalizeOpenGraphType(
+  type: NonNullable<PageSEOData['openGraph']>['type']
+): 'article' | 'profile' | 'video.other' | 'website' {
+  if (type === 'article' || type === 'profile' || type === 'video.other') {
+    return type
+  }
+  return 'website'
+}
+
+/**
+ * Convert Builder SEO fields into metadata accepted by Next.js.
+ *
+ * Unsupported Open Graph product types and incomplete Twitter app/player
+ * cards are safely downgraded to renderable Next.js variants.
+ */
+export function formatWeaverseNextSeoMetadata(
+  seo: PageSEOData | null | undefined
+): WeaverseNextSeoMetadata {
+  let index = seo?.robots?.index !== false
+  let follow = seo?.robots?.follow !== false
+  let metadata: WeaverseNextSeoMetadata = {
+    robots: { index, follow },
+  }
+
+  if (!seo) {
+    return metadata
+  }
+
+  if (seo.title) {
+    metadata.title = seo.title
+  }
+  if (seo.description) {
+    metadata.description = seo.description
+  }
+  if (seo.keywords) {
+    metadata.keywords = seo.keywords
+  }
+  if (seo.canonicalUrl) {
+    metadata.alternates = { canonical: seo.canonicalUrl }
+  }
+
+  let openGraph = seo.openGraph
+  if (hasOpenGraphContent(openGraph)) {
+    metadata.openGraph = {
+      title: openGraph?.title,
+      description: openGraph?.description,
+      images: openGraph?.image ? [openGraph.image] : undefined,
+      type: normalizeOpenGraphType(openGraph?.type),
+    }
+  }
+
+  let twitter = seo.twitter
+  if (hasTwitterContent(twitter)) {
+    // Builder does not collect the descriptors Next requires for `app` cards
+    // (Next throws when they are missing) or `player` cards (which render an
+    // empty, useless card without a player URL and dimensions). Downgrade both
+    // to `summary` rather than emitting metadata Next cannot render.
+    metadata.twitter = {
+      card: normalizeTwitterCard(twitter?.cardType),
+      title: twitter?.title,
+      description: twitter?.description,
+      images: twitter?.image ? [twitter.image] : undefined,
+    }
+  }
+
+  return metadata
+}
+
+/**
+ * Read page SEO from loader data or a page payload and format it for Next.js
+ * `generateMetadata`. Missing data returns indexable/followable robot defaults.
+ */
+export function getWeaverseNextSeoMetadata(
+  data: WeaverseNextSeoInput
+): WeaverseNextSeoMetadata {
+  if (!data) {
+    return formatWeaverseNextSeoMetadata(null)
+  }
+  let page =
+    'items' in data && 'id' in data
+      ? (data as WeaverseNextPageData)
+      : ((data as WeaverseNextSeoPageContainer).page ?? null)
+  return formatWeaverseNextSeoMetadata(page?.seo ?? null)
+}

package/src/server/configs.ts

@@ -0,0 +1,178 @@
+import type {
+  WeaverseNextBaseConfigs,
+  WeaverseNextRequestContext,
+} from '../types'
+
+const DEFAULT_WEAVERSE_HOST = 'https://studio.weaverse.io'
+const DEFAULT_WEAVERSE_API_BASE = 'https://api.weaverse.io'
+
+/**
+ * Weaverse-controlled apex domains the Studio bridge / data API may be served
+ * from (matched on the host itself and any subdomain). Kept in sync with
+ * Hydrogen's `isTrustedStudioHost`.
+ */
+const TRUSTED_STUDIO_DOMAINS = ['weaverse.io', 'weaverse.dev']
+
+/**
+ * Whether `host` is an origin we trust to resolve page/theme data. The
+ * `weaverseHost` query param is attacker-controllable, so a crafted
+ * `?weaverseHost=` must be rejected before it can point server-side fetches at
+ * an arbitrary origin (SSRF). Only `weaverse.io`/`weaverse.dev` and subdomains
+ * over https are trusted.
+ */
+function isTrustedStudioHost(host: string): boolean {
+  let parsed: URL
+  try {
+    parsed = new URL(host)
+  } catch {
+    return false
+  }
+  if (parsed.protocol !== 'https:') {
+    return false
+  }
+  let { hostname } = parsed
+  return TRUSTED_STUDIO_DOMAINS.some(
+    (domain) => hostname === domain || hostname.endsWith(`.${domain}`)
+  )
+}
+
+function toUrl(value: string | URL): URL | null {
+  try {
+    return typeof value === 'string'
+      ? new URL(value, 'http://localhost')
+      : value
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Extract the request search params from the explicit Next request context.
+ * Prefers `searchParams`, falls back to parsing `url`.
+ */
+export function getContextSearchParams(
+  context?: WeaverseNextRequestContext
+): URLSearchParams {
+  if (context?.searchParams) {
+    return new URLSearchParams(context.searchParams)
+  }
+  if (context?.url) {
+    let url = toUrl(context.url)
+    if (url) {
+      return new URLSearchParams(url.searchParams)
+    }
+  }
+  return new URLSearchParams()
+}
+
+/**
+ * Last value of a (possibly duplicated) query key. Matches Hydrogen's
+ * `getRequestQueries`, which assigns while iterating and so keeps the last
+ * occurrence — Studio appends its own control params, so a stale earlier value
+ * must not win.
+ */
+function lastParam(
+  searchParams: URLSearchParams,
+  key: string
+): string | undefined {
+  let values = searchParams.getAll(key)
+  return values.length ? values.at(-1) : undefined
+}
+
+function coerceBool(value: string | undefined): boolean {
+  return value === 'true'
+}
+
+function readEnv(
+  env: Record<string, string | undefined> | undefined,
+  key: string
+): string | undefined {
+  let fromConfig = env?.[key]
+  if (fromConfig !== undefined) {
+    return fromConfig
+  }
+  if (typeof process !== 'undefined' && process.env) {
+    return process.env[key]
+  }
+  return
+}
+
+/** Overrides used while resolving request-scoped Weaverse configuration. */
+export interface ResolveConfigsOptions {
+  /** Environment values; missing keys fall back to `process.env`. */
+  env?: Record<string, string | undefined>
+  /** Public data API base override. */
+  weaverseApiBase?: string
+  /** Studio origin override. */
+  weaverseHost?: string
+  /** Studio asset version override. */
+  weaverseVersion?: string
+}
+
+/**
+ * Derive Weaverse configs from the request context and env, close to Hydrogen's
+ * `getWeaverseConfigs`. Resolves the trusted host, public API base, design /
+ * preview / revision flags, and public env — but never resolves the final
+ * `projectId` (that priority chain, which may call an async resolver, lives in
+ * the server client). Query/env projectId candidates are returned for the
+ * client to combine with function/string inputs.
+ */
+export function getWeaverseNextConfigs(
+  context?: WeaverseNextRequestContext,
+  options: ResolveConfigsOptions = {}
+): WeaverseNextBaseConfigs {
+  let searchParams = getContextSearchParams(context)
+  let { env } = options
+
+  let queryHost = lastParam(searchParams, 'weaverseHost')
+  // A trusted query host is canonicalized to its origin before use, so a crafted
+  // `?weaverseHost=https://studio.weaverse.io/evil?x=1` can only ever resolve to
+  // `https://studio.weaverse.io` — never carrying an attacker path/query into the
+  // server-side API base.
+  let trustedUrlHost =
+    queryHost && isTrustedStudioHost(queryHost) ? new URL(queryHost).origin : ''
+
+  let configuredHost =
+    options.weaverseHost || readEnv(env, 'WEAVERSE_HOST') || ''
+  let weaverseHost = trustedUrlHost || configuredHost || DEFAULT_WEAVERSE_HOST
+
+  // Public data reads default to the edge proxy, but an explicit custom host
+  // (staging/self-hosted Weaverse) must stay the API base so those deployments
+  // don't fetch page/config data from the production proxy.
+  let weaverseApiBase =
+    trustedUrlHost ||
+    options.weaverseApiBase ||
+    readEnv(env, 'WEAVERSE_PUBLIC_API_BASE') ||
+    (configuredHost && configuredHost !== DEFAULT_WEAVERSE_HOST
+      ? configuredHost
+      : DEFAULT_WEAVERSE_API_BASE)
+
+  let isRevisionPreview =
+    context?.isRevisionPreview ?? searchParams.has('__revisionId')
+  let isDesignMode =
+    context?.isDesignMode ?? coerceBool(lastParam(searchParams, 'isDesignMode'))
+  let isPreviewMode =
+    context?.isPreviewMode ??
+    coerceBool(lastParam(searchParams, 'isPreviewMode'))
+
+  return {
+    queryProjectId: lastParam(searchParams, 'weaverseProjectId') || '',
+    envProjectId: readEnv(env, 'WEAVERSE_PROJECT_ID') || '',
+    weaverseHost,
+    weaverseApiBase,
+    weaverseVersion:
+      lastParam(searchParams, 'weaverseVersion') ||
+      options.weaverseVersion ||
+      '',
+    isDesignMode,
+    isPreviewMode,
+    isRevisionPreview,
+    sectionType:
+      context?.sectionType || lastParam(searchParams, 'sectionType') || '',
+    publicEnv: {
+      PUBLIC_STORE_DOMAIN: readEnv(env, 'PUBLIC_STORE_DOMAIN') || '',
+      PUBLIC_STOREFRONT_API_TOKEN:
+        readEnv(env, 'PUBLIC_STOREFRONT_API_TOKEN') || '',
+    },
+  }
+}

package/src/server/normalize-page-url.ts

@@ -0,0 +1,73 @@
+import { withPathPrefix } from '../request-info'
+import type { WeaverseNextRequestContext } from '../types'
+
+// Query params that influence Weaverse page resolution on the Builder:
+// revision previews, design-mode flags, design-mode draft item overrides,
+// and `weaverse*` control params (host, version, project id). Everything
+// else — utm_*, fbclid, gclid, storefront filters — is irrelevant to which
+// page the Builder returns and would otherwise fragment any fetch cache keyed
+// on the request body. `weaverseDraftItem` is the current draft item param;
+// `__weaverseDraftItem` is kept as a legacy compatibility alias.
+const KEPT_PARAM_RE =
+  /^(?:__revisionId|__weaverseDraftItem|isDesignMode|weaverse)/
+const DATA_SUFFIX = '.data'
+
+/**
+ * Normalize the storefront URL sent in the Builder page API request body.
+ *
+ * The Builder reads only the pathname (locale/type/handle fallback) and the
+ * Weaverse/Studio control params from this URL, so keep exactly those and drop
+ * tracking params. Params are sorted for a stable, cache-friendly string.
+ *
+ * Ported from `@weaverse/hydrogen`'s `normalizePageUrl`, but tolerant of a
+ * relative URL (Next route handlers may only know the pathname).
+ */
+export function normalizeNextPageUrl(url: string): string {
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch {
+    try {
+      parsed = new URL(url, 'http://localhost')
+    } catch {
+      return url
+    }
+  }
+
+  let kept = [...parsed.searchParams].filter(([key]) => KEPT_PARAM_RE.test(key))
+  kept.sort(([a], [b]) => a.localeCompare(b))
+  let search = new URLSearchParams(kept).toString()
+
+  let { pathname } = parsed
+  if (pathname.endsWith(DATA_SUFFIX)) {
+    pathname = pathname.slice(0, -DATA_SUFFIX.length)
+  }
+  return `${parsed.origin}${pathname}${search ? `?${search}` : ''}`
+}
+
+/**
+ * Build an absolute-ish request URL string from the explicit request context,
+ * preferring `url`, then `pathname` + `searchParams`. Used as the input to
+ * {@link normalizeNextPageUrl}.
+ */
+export function resolveRequestUrl(
+  context?: WeaverseNextRequestContext
+): string {
+  if (context?.url) {
+    let raw = String(context.url)
+    let url = new URL(raw, 'http://localhost')
+    let pathname = withPathPrefix(url.pathname, context.i18n)
+    // Unchanged when there is nothing to prefix, so a relative or bare-origin
+    // URL is passed on exactly as the app gave it.
+    if (pathname === url.pathname) {
+      return raw
+    }
+    url.pathname = pathname
+    return url.toString()
+  }
+  let pathname = withPathPrefix(context?.pathname || '/', context?.i18n)
+  let search = context?.searchParams
+    ? new URLSearchParams(context.searchParams).toString()
+    : ''
+  return `http://localhost${pathname}${search ? `?${search}` : ''}`
+}