@rovela-ai/sdk 0.19.4 → 0.19.5

package/templates/store-template/app/privacy/page.tsx

@@ -0,0 +1,281 @@
+import type { Metadata } from 'next'
+import { LocaleLink as Link } from '@rovela-ai/sdk/core'
+import { getBlueprint, localizedAlternates, findSettings } from '@rovela-ai/sdk/core/server'
+
+/**
+ * Privacy Policy Page
+ *
+ * Static privacy policy page with standard e-commerce sections.
+ * Store name is pulled from blueprint for personalization.
+ */
+
+// =============================================================================
+// Metadata
+// =============================================================================
+
+export async function generateMetadata(): Promise<Metadata> {
+  let storeName = 'Our Store'
+  try {
+    const blueprint = getBlueprint()
+    storeName = blueprint?.store?.name || process.env.STORE_NAME || storeName
+  } catch {
+    // Blueprint might not exist
+  }
+
+  return {
+    title: 'Privacy Policy',
+    description: `Privacy Policy for ${storeName}. Learn how we collect, use, and protect your personal information.`,
+    alternates: await localizedAlternates('/privacy'),
+  }
+}
+
+// =============================================================================
+// Page Component
+// =============================================================================
+
+export default async function PrivacyPage() {
+  // Get store name for display — LIVE settings first (store_settings is what
+  // the merchant edits in /admin; blueprint + env are build-time fallbacks
+  // that go stale after a rename). Fail-open on DB errors.
+  let storeName = 'Our Store'
+  let supportEmail = ''
+  const liveSettings = await findSettings().catch(() => null)
+
+  try {
+    const blueprint = getBlueprint()
+    storeName =
+      liveSettings?.storeName || blueprint?.store?.name || process.env.STORE_NAME || storeName
+  } catch {
+    storeName = liveSettings?.storeName || process.env.STORE_NAME || storeName
+  }
+
+  // Public contact email = the merchant's own address only. NEVER the platform
+  // transactional sender (RESEND_FROM_EMAIL): surfacing that put
+  // "contact@rovela.ai" on storefront legal pages and read as a template
+  // artifact. Falls back to support@<your-domain> derived from the live host;
+  // if only a *.rovela.app / *.vercel.app / localhost host is available it stays
+  // empty and the email line is hidden (the contact-page link still renders).
+  const storeHost = (process.env.NEXT_PUBLIC_APP_URL || '')
+    .replace(/^https?:\/\//, '')
+    .replace(/\/.*$/, '')
+    .trim()
+  const hasOwnDomain =
+    !!storeHost &&
+    !storeHost.endsWith('rovela.app') &&
+    !storeHost.endsWith('vercel.app') &&
+    !storeHost.startsWith('localhost')
+  // Live store email first — this is the address the merchant actually set
+  // (emails, contact page and JSON-LD already read it); SUPPORT_EMAIL env is
+  // the build-time fallback, support@<domain> the last resort.
+  supportEmail =
+    liveSettings?.storeEmail?.trim() ||
+    process.env.SUPPORT_EMAIL?.trim() ||
+    (hasOwnDomain ? `support@${storeHost}` : '')
+
+  return (
+    <div className="container mx-auto px-4 sm:px-6 lg:px-8 py-16">
+      <div className="max-w-3xl mx-auto">
+        {/* Header */}
+        <div className="mb-12">
+          <h1 className="text-3xl font-bold font-heading">Privacy Policy</h1>
+        </div>
+
+        {/* Content */}
+        <div className="prose prose-neutral dark:prose-invert max-w-none">
+          {/* Introduction */}
+          <section className="mb-10">
+            <p className="text-muted-foreground leading-relaxed">
+              At {storeName}, we are committed to protecting your privacy and ensuring the
+              security of your personal information. This Privacy Policy explains how we collect,
+              use, disclose, and safeguard your information when you visit our website or make
+              a purchase.
+            </p>
+          </section>
+
+          {/* Information We Collect */}
+          <section className="mb-10">
+            <h2 className="text-xl font-semibold font-heading mb-4">
+              Information We Collect
+            </h2>
+            <p className="text-muted-foreground mb-4">
+              We collect information that you provide directly to us, including:
+            </p>
+            <ul className="list-disc pl-6 space-y-2 text-muted-foreground">
+              <li>Name and contact information (email address, phone number, shipping address)</li>
+              <li>Payment information (processed securely through our payment provider)</li>
+              <li>Order history and preferences</li>
+              <li>Communications you send to us</li>
+              <li>Account information if you create an account</li>
+            </ul>
+            <p className="text-muted-foreground mt-4">
+              We also automatically collect certain information when you visit our website,
+              including your IP address, browser type, device information, and browsing behavior.
+            </p>
+          </section>
+
+          {/* How We Use Your Information */}
+          <section className="mb-10">
+            <h2 className="text-xl font-semibold font-heading mb-4">
+              How We Use Your Information
+            </h2>
+            <p className="text-muted-foreground mb-4">
+              We use the information we collect to:
+            </p>
+            <ul className="list-disc pl-6 space-y-2 text-muted-foreground">
+              <li>Process and fulfill your orders</li>
+              <li>Send you order confirmations and shipping updates</li>
+              <li>Respond to your questions and provide customer support</li>
+              <li>Send promotional communications (with your consent)</li>
+              <li>Improve our website and services</li>
+              <li>Detect and prevent fraud</li>
+              <li>Comply with legal obligations</li>
+            </ul>
+          </section>
+
+          {/* Information Sharing */}
+          <section className="mb-10">
+            <h2 className="text-xl font-semibold font-heading mb-4">
+              Information Sharing
+            </h2>
+            <p className="text-muted-foreground mb-4">
+              We do not sell your personal information. We may share your information with:
+            </p>
+            <ul className="list-disc pl-6 space-y-2 text-muted-foreground">
+              <li>Service providers who assist in our operations (payment processors, shipping carriers)</li>
+              <li>Analytics providers to help us understand website usage</li>
+              <li>Legal authorities when required by law</li>
+            </ul>
+          </section>
+
+          {/* Data Security */}
+          <section className="mb-10">
+            <h2 className="text-xl font-semibold font-heading mb-4">
+              Data Security
+            </h2>
+            <p className="text-muted-foreground">
+              We implement appropriate technical and organizational measures to protect your
+              personal information against unauthorized access, alteration, disclosure, or
+              destruction. All payment transactions are encrypted using SSL technology and
+              processed through secure payment providers.
+            </p>
+          </section>
+
+          {/* Cookies */}
+          <section id="cookies" className="mb-10 scroll-mt-24">
+            <h2 className="text-xl font-semibold font-heading mb-4">
+              Cookies and Tracking
+            </h2>
+            <p className="text-muted-foreground mb-4">
+              We use cookies and similar technologies to make this store work
+              and, with your consent, to understand how it is used and show
+              you relevant content. Cookies are grouped into three categories:
+            </p>
+            <ul className="list-disc pl-6 space-y-2 text-muted-foreground">
+              <li>
+                <strong className="text-foreground">Essential.</strong> Required
+                for the store to work — including your cart, session, and
+                sign-in state. Always on; cannot be disabled.
+              </li>
+              <li>
+                <strong className="text-foreground">Analytics.</strong> Help us
+                understand how the store is used so we can improve it.
+                Optional; off unless you choose to allow them.
+              </li>
+              <li>
+                <strong className="text-foreground">Marketing.</strong> Used to
+                measure ads and show you relevant content across sites.
+                Optional; off unless you choose to allow them.
+              </li>
+            </ul>
+            <p className="text-muted-foreground mt-4">
+              You can change your preferences at any time by clicking
+              &ldquo;Cookie preferences&rdquo; in the footer of any page. If
+              you reject non-essential cookies, some features that rely on
+              analytics or personalization may be limited.
+            </p>
+          </section>
+
+          {/* Your Rights */}
+          <section className="mb-10">
+            <h2 className="text-xl font-semibold font-heading mb-4">
+              Your Rights
+            </h2>
+            <p className="text-muted-foreground mb-4">
+              Depending on your location, you may have the right to:
+            </p>
+            <ul className="list-disc pl-6 space-y-2 text-muted-foreground">
+              <li>Access the personal information we hold about you</li>
+              <li>Request correction of inaccurate information</li>
+              <li>Request deletion of your personal information</li>
+              <li>Opt out of marketing communications</li>
+              <li>Data portability</li>
+            </ul>
+          </section>
+
+          {/* Children's Privacy */}
+          <section className="mb-10">
+            <h2 className="text-xl font-semibold font-heading mb-4">
+              Children&apos;s Privacy
+            </h2>
+            <p className="text-muted-foreground">
+              Our website is not intended for children under 13 years of age. We do not
+              knowingly collect personal information from children. If you believe we have
+              collected information from a child, please contact us immediately.
+            </p>
+          </section>
+
+          {/* Changes to Policy */}
+          <section className="mb-10">
+            <h2 className="text-xl font-semibold font-heading mb-4">
+              Changes to This Policy
+            </h2>
+            <p className="text-muted-foreground">
+              We may update this Privacy Policy from time to time. We will notify you of any
+              changes by posting the new policy on this page and updating the &quot;Last updated&quot;
+              date. We encourage you to review this policy periodically.
+            </p>
+          </section>
+
+          {/* Contact Us */}
+          <section className="mb-10">
+            <h2 className="text-xl font-semibold font-heading mb-4">
+              Contact Us
+            </h2>
+            <p className="text-muted-foreground">
+              If you have any questions about this Privacy Policy or our privacy
+              practices, please
+              {supportEmail ? (
+                <>
+                  {' '}contact us at{' '}
+                  <a
+                    href={`mailto:${supportEmail}`}
+                    className="text-primary hover:underline"
+                  >
+                    {supportEmail}
+                  </a>{' '}
+                  or visit our{' '}
+                </>
+              ) : (
+                <>{' '}reach us through our{' '}</>
+              )}
+              <Link href="/contact" className="text-primary hover:underline">
+                contact page
+              </Link>
+              .
+            </p>
+          </section>
+        </div>
+
+        {/* Back to Home */}
+        <div className="mt-12 pt-8 border-t">
+          <Link
+            href="/"
+            className="text-sm text-primary hover:underline"
+          >
+            &larr; Back to Home
+          </Link>
+        </div>
+      </div>
+    </div>
+  )
+}

package/templates/store-template/app/products/[slug]/ProductDetailClient.tsx

@@ -0,0 +1,179 @@
+'use client'
+
+/**
+ * Product Detail — interactive client island.
+ *
+ * Rendered by the server `page.tsx`, which owns metadata + the server-rendered
+ * Product JSON-LD (AI shopping crawlers don't run JS, so schema must be server
+ * side). This component keeps the original interactive UX unchanged:
+ * - ProductGallery: Image gallery
+ * - VariantSelector: Variant selection
+ * - AddToCartButton: Add to cart with feedback
+ * - useProduct: Single product data fetching
+ */
+
+import { useState, useMemo } from 'react'
+import { notFound } from 'next/navigation'
+import { LocaleLink as Link } from '@rovela-ai/sdk/core'
+import { ChevronLeft } from 'lucide-react'
+import {
+  ProductGallery,
+  ProductSpecifications,
+  VariantSelector,
+  useProduct,
+} from '@rovela-ai/sdk/products'
+import { AddToCartButton } from '@rovela-ai/sdk/cart'
+import { useT, useStoreFormatting } from '@rovela-ai/sdk/core'
+import type { ProductVariant } from '@rovela-ai/sdk/core'
+
+export function ProductDetailClient({ slug }: { slug: string }) {
+  const { product, variants, isLoading, error } = useProduct(slug)
+  const [selectedVariant, setSelectedVariant] = useState<ProductVariant | null>(null)
+  const t = useT()
+  // Locale-aware price shapes (active i18n locale + store currency).
+  const { formatPrice } = useStoreFormatting()
+
+  // ALL HOOKS AND COMPUTED VALUES MUST BE ABOVE EARLY RETURNS (Rules of Hooks)
+
+  // Get current variant or default to first (safe even if variants is empty)
+  const currentVariant = selectedVariant || (variants.length > 0 ? variants[0] : null)
+
+  // Compute gallery: variant image + variant video first (when set), then
+  // product images, then product videos. Filter duplicates so a variant
+  // URL that also appears in product arrays only renders once.
+  const galleryMedia = useMemo<string[]>(() => {
+    if (!product) return []
+    const variantUrls = [currentVariant?.image, currentVariant?.video].filter(
+      (u): u is string => !!u
+    )
+    const productImages = product.images || []
+    const productVideos = product.videos || []
+    if (variantUrls.length === 0) {
+      return [...productImages, ...productVideos]
+    }
+    const variantSet = new Set(variantUrls)
+    return [
+      ...variantUrls,
+      ...productImages.filter((u) => !variantSet.has(u)),
+      ...productVideos.filter((u) => !variantSet.has(u)),
+    ]
+  }, [product, currentVariant])
+
+  // Generate a key to reset gallery when variant changes
+  const galleryKey = currentVariant?.id || 'no-variant'
+
+  // Determine price and stock (safe if product is null)
+  const price = currentVariant?.price ?? product?.price ?? 0
+  const comparePrice = product?.comparePrice
+  const inStock = currentVariant
+    ? (currentVariant.inventory ?? 0) > 0
+    : true
+
+  // EARLY RETURNS AFTER ALL HOOKS
+
+  // Loading state
+  if (isLoading) {
+    return (
+      <div className="container mx-auto px-4 sm:px-6 lg:px-8 py-8">
+        <div className="animate-pulse">
+          <div className="h-8 w-48 bg-muted rounded mb-8" />
+          <div className="grid grid-cols-1 lg:grid-cols-2 gap-12">
+            <div className="aspect-square bg-muted rounded-lg" />
+            <div className="space-y-4">
+              <div className="h-10 w-3/4 bg-muted rounded" />
+              <div className="h-6 w-1/4 bg-muted rounded" />
+              <div className="h-24 bg-muted rounded" />
+            </div>
+          </div>
+        </div>
+      </div>
+    )
+  }
+
+  // Error or not found
+  if (error || !product) {
+    notFound()
+  }
+
+  return (
+    <div className="container mx-auto px-4 sm:px-6 lg:px-8 py-8">
+      {/* Breadcrumb */}
+      <nav className="mb-8">
+        <Link
+          href="/products"
+          className="inline-flex items-center text-sm text-muted-foreground hover:text-foreground transition-colors"
+        >
+          <ChevronLeft className="h-4 w-4 mr-1" />
+          {t('listing.backToProducts')}
+        </Link>
+      </nav>
+
+      <div className="grid grid-cols-1 lg:grid-cols-2 gap-12">
+        {/* Product Gallery */}
+        <ProductGallery
+          key={galleryKey}
+          media={galleryMedia}
+          alt={product.name}
+        />
+
+        {/* Product Info */}
+        <div className="flex flex-col">
+          <h1 className="text-3xl font-bold font-heading">{product.name}</h1>
+
+          {/* Price */}
+          <div className="mt-4 flex items-baseline gap-3">
+            <span className="text-2xl font-semibold">
+              {formatPrice(price)}
+            </span>
+            {comparePrice && comparePrice > price && (
+              <span className="text-lg text-muted-foreground line-through">
+                {formatPrice(comparePrice)}
+              </span>
+            )}
+          </div>
+
+          {/* Description */}
+          {product.description && (
+            <p className="mt-6 whitespace-pre-line text-muted-foreground">
+              {product.description}
+            </p>
+          )}
+
+          {/* Variant Selector */}
+          {variants && variants.length > 1 && (
+            <div className="mt-8">
+              <VariantSelector
+                variants={variants}
+                selected={currentVariant}
+                onSelect={setSelectedVariant}
+              />
+            </div>
+          )}
+
+          {/* Add to Cart */}
+          <div className="mt-8">
+            <AddToCartButton
+              product={product}
+              selectedVariant={currentVariant}
+              disabled={!inStock}
+              showFeedback
+              className="w-full sm:w-auto"
+            >
+              {inStock ? t('cart.addToCart') : t('product.outOfStock')}
+            </AddToCartButton>
+          </div>
+
+          {/* Stock Status */}
+          {!inStock && (
+            <p className="mt-4 text-sm text-destructive">
+              {t('product.currentlyOutOfStock')}
+            </p>
+          )}
+        </div>
+      </div>
+
+      {/* Specifications (custom fields) — renders nothing when empty */}
+      <ProductSpecifications metafields={product.metafields} className="mt-12 max-w-3xl" />
+    </div>
+  )
+}

package/templates/store-template/app/products/[slug]/page.tsx

@@ -0,0 +1,149 @@
+/**
+ * Product Detail Page — server shell.
+ *
+ * This is a Server Component so it can emit per-product metadata AND a
+ * server-rendered `Product` + `Offer` JSON-LD block. AI shopping crawlers
+ * (GPTBot, OAI-SearchBot, PerplexityBot) read structured data BEFORE HTML and
+ * do not execute JavaScript, so the schema must be server-rendered here — not
+ * injected by the client island. The interactive UI lives in
+ * `ProductDetailClient` and is unchanged.
+ */
+
+import type { Metadata } from 'next'
+import { cache } from 'react'
+import { notFound } from 'next/navigation'
+import {
+  findProductBySlug,
+  findProductVariants,
+  findSettings,
+  localizedAlternates,
+  getRequestLocale,
+} from '@rovela-ai/sdk/core/server'
+import { localizeCatalogRow } from '@rovela-ai/sdk/core'
+import { buildProductJsonLd, buildBreadcrumbJsonLd, serializeJsonLd } from '@rovela-ai/sdk/core'
+import { ProductDetailClient } from './ProductDetailClient'
+
+const STORE_URL = process.env.NEXT_PUBLIC_APP_URL || ''
+
+// Dedupe the product lookup across generateMetadata + the page render within a request.
+const getProduct = cache((slug: string) =>
+  findProductBySlug(slug).catch(() => null)
+)
+
+function toPlainText(html: string): string {
+  return html
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+type Props = { params: Promise<{ slug: string }> }
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params
+  const fetchedProduct = await getProduct(slug)
+  const { locale: activeLocale, config: localeConfig } = await getRequestLocale()
+  // Shadow with the localized copy so every downstream usage (title, JSON-LD,
+  // breadcrumb, client island props) inherits the translation.
+  const product = fetchedProduct
+    ? localizeCatalogRow(fetchedProduct, activeLocale, localeConfig.defaultLocale)
+    : fetchedProduct
+  if (!product) return { title: 'Product not found' }
+
+  const title = product.metaTitle || product.name
+  const description =
+    product.metaDescription ||
+    (product.description ? toPlainText(product.description).slice(0, 160) : undefined)
+  const image = product.images?.[0]
+
+  return {
+    title,
+    ...(description && { description }),
+    alternates: await localizedAlternates(`/products/${slug}`),
+    ...(product.metaKeywords && product.metaKeywords.length > 0 && {
+      keywords: product.metaKeywords,
+    }),
+    openGraph: {
+      title,
+      ...(description && { description }),
+      type: 'website',
+      url: `/products/${slug}`,
+      ...(image && { images: [{ url: image }] }),
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title,
+      ...(description && { description }),
+      ...(image && { images: [image] }),
+    },
+  }
+}
+
+export default async function ProductPage({ params }: Props) {
+  const { slug } = await params
+  const fetchedProduct = await getProduct(slug)
+  const { locale: activeLocale, config: localeConfig } = await getRequestLocale()
+  // Shadow with the localized copy so every downstream usage (title, JSON-LD,
+  // breadcrumb, client island props) inherits the translation.
+  const product = fetchedProduct
+    ? localizeCatalogRow(fetchedProduct, activeLocale, localeConfig.defaultLocale)
+    : fetchedProduct
+  if (!product) notFound()
+
+  const [variants, settings] = await Promise.all([
+    findProductVariants(product.id).catch(() => []),
+    findSettings().catch(() => null),
+  ])
+
+  // Mirror the canonical out-of-stock logic (see buildOutOfStockCondition in
+  // the SDK): variant products are in stock if any variant has inventory;
+  // non-variant products honor trackInventory + continue-selling.
+  const inStock = product.hasVariants
+    ? variants.some((v) => (v.inventory ?? 0) > 0)
+    : !product.trackInventory ||
+      (product.inventory ?? 0) > 0 ||
+      !!product.continueSellingWhenOutOfStock
+
+  const jsonLd = buildProductJsonLd(
+    {
+      name: product.name,
+      slug: product.slug,
+      description: product.description,
+      price: product.price,
+      images: product.images,
+      sku: product.sku,
+      inStock,
+    },
+    {
+      storeUrl: STORE_URL,
+      storeName: settings?.storeName || process.env.STORE_NAME || 'Store',
+      currency: (settings?.storeCurrency || 'USD').toUpperCase(),
+    }
+  )
+
+  // Breadcrumb trail (Home › Products › product) — server-rendered. Only when
+  // we have an absolute origin to build valid `item` URLs.
+  const breadcrumbJsonLd = STORE_URL
+    ? buildBreadcrumbJsonLd([
+        { name: 'Home', url: `${STORE_URL}/` },
+        { name: 'Products', url: `${STORE_URL}/products` },
+        { name: product.name, url: `${STORE_URL}/products/${product.slug}` },
+      ])
+    : null
+
+  return (
+    <>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: serializeJsonLd(jsonLd) }}
+      />
+      {breadcrumbJsonLd && (
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{ __html: serializeJsonLd(breadcrumbJsonLd) }}
+        />
+      )}
+      <ProductDetailClient slug={slug} />
+    </>
+  )
+}

package/templates/store-template/app/products/layout.tsx

@@ -0,0 +1,26 @@
+import { localizedAlternates, getRequestLocale } from '@rovela-ai/sdk/core/server'
+import { getT } from '@rovela-ai/sdk/core'
+import type { Metadata } from 'next'
+
+/**
+ * Server layout for the /products listing. The listing page is a client
+ * component and can't export metadata, so this wrapper supplies the canonical
+ * for /products. The product detail page (/products/[slug]) sets its OWN
+ * per-product canonical in generateMetadata, which overrides this for those
+ * routes — so it never mis-canonicalizes a product page to the listing.
+ */
+export async function generateMetadata() {
+  const { locale } = await getRequestLocale()
+  return {
+    title: getT(locale)('listing.title'),
+    alternates: await localizedAlternates('/products'),
+  }
+}
+
+export default function ProductsLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return children
+}