@rovela-ai/sdk 0.19.4 → 0.19.6

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

@@ -0,0 +1,88 @@
+'use client'
+
+/**
+ * Checkout Page
+ *
+ * Checkout behavior depends on store settings:
+ * - Shipping enabled: Full pre-checkout flow (Address → Shipping → Review → Stripe)
+ * - Shipping disabled: Simple checkout with direct Stripe redirect (no shipping step)
+ *
+ * When shipping is enabled, uses CheckoutFlow component which:
+ * 1. Collects shipping address via ShippingForm
+ * 2. Fetches shipping options via POST /api/checkout/shipping
+ * 3. Shows shipping options grouped by carrier via ShippingOptions
+ * 4. Displays order summary with totals
+ * 5. Redirects to Stripe Checkout for payment (card only, address pre-filled)
+ *
+ * Both manual (zone-based) and Shippo (carrier API) modes are supported.
+ */
+
+import { useEffect } from 'react'
+import { useRouter } from 'next/navigation'
+import { useAuth } from '@rovela-ai/sdk/auth'
+import { useCart } from '@rovela-ai/sdk/cart'
+import { CheckoutFlow, CheckoutButton } from '@rovela-ai/sdk/checkout'
+import { useStoreSettings, useT, useLocalePath } from '@rovela-ai/sdk/core'
+
+export default function CheckoutPage() {
+  const t = useT()
+  const localePath = useLocalePath()
+  const router = useRouter()
+  // `useAuth()` filters out admin sessions (returns null if the signed-in
+  // user is an admin, not a customer). Using it instead of raw `useSession`
+  // prevents an admin's email from being prefilled as the "customer email"
+  // at checkout — which would otherwise leak into the Stripe session.
+  const { customer } = useAuth()
+  const { items } = useCart()
+  const { settings, isLoading: isSettingsLoading } = useStoreSettings()
+  const itemCount = items.reduce((sum, item) => sum + item.quantity, 0)
+
+  // Check if shipping is enabled
+  const shippingEnabled = settings?.shippingEnabled ?? true
+
+  // Redirect to cart if empty
+  useEffect(() => {
+    if (itemCount === 0) {
+      router.push(localePath('/cart'))
+    }
+  }, [itemCount, router, localePath])
+
+  // Don't render checkout if cart is empty
+  if (itemCount === 0) {
+    return null
+  }
+
+  // When shipping is disabled, show simple checkout (direct to Stripe)
+  // This handles the edge case where user navigates directly to /checkout
+  if (!isSettingsLoading && !shippingEnabled) {
+    return (
+      <div className="container mx-auto px-4 sm:px-6 lg:px-8 py-8 max-w-md">
+        <h1 className="text-2xl font-bold font-heading mb-4 text-center">{t('checkoutPage.title')}</h1>
+        <p className="text-muted-foreground mb-8 text-center">
+          {t('checkoutPage.reviewAndPay')}
+        </p>
+        <CheckoutButton size="lg" className="w-full">
+          {t('checkout.proceedToPayment')}
+        </CheckoutButton>
+        <button
+          onClick={() => router.push(localePath('/cart'))}
+          className="w-full mt-4 text-sm text-muted-foreground hover:text-foreground transition-colors"
+        >
+          ← {t('checkoutPage.returnToCart')}
+        </button>
+      </div>
+    )
+  }
+
+  return (
+    <div className="container mx-auto px-4 sm:px-6 lg:px-8 py-8 max-w-6xl">
+      <h1 className="text-2xl font-bold font-heading mb-8">{t('checkoutPage.title')}</h1>
+      <CheckoutFlow
+        customerEmail={customer?.email ?? undefined}
+        customerId={customer?.id ?? undefined}
+        showOrderSummary={true}
+        onCancel={() => router.push(localePath('/cart'))}
+      />
+    </div>
+  )
+}

package/templates/store-template/app/checkout/success/page.tsx

@@ -0,0 +1,50 @@
+'use client'
+
+/**
+ * Checkout Success Page
+ *
+ * Displayed after a successful checkout — Stripe redirect OR a manual-payment
+ * order (`?orderId=` set by the manual checkout path). Clears the cart and
+ * shows the order confirmation.
+ */
+
+import { Suspense, useEffect, useRef } from 'react'
+import { useSearchParams } from 'next/navigation'
+import { useCart } from '@rovela-ai/sdk/cart'
+import { CheckoutSuccess } from '@rovela-ai/sdk/checkout'
+import { useLocalePath } from '@rovela-ai/sdk/core'
+
+function CheckoutSuccessContent() {
+  const localePath = useLocalePath()
+  const { clearCart } = useCart()
+  const hasClearedCart = useRef(false)
+  const searchParams = useSearchParams()
+  const orderId = searchParams.get('orderId') || undefined
+
+  // Clear cart on mount (only once)
+  useEffect(() => {
+    if (!hasClearedCart.current) {
+      clearCart()
+      hasClearedCart.current = true
+    }
+  }, [clearCart])
+
+  return (
+    <div className="container mx-auto px-4 sm:px-6 lg:px-8 py-16">
+      <CheckoutSuccess
+        orderId={orderId}
+        continueShoppingHref={localePath('/products')}
+        viewOrderHref={localePath(orderId ? `/account/orders/${orderId}` : '/account/orders')}
+      />
+    </div>
+  )
+}
+
+export default function CheckoutSuccessPage() {
+  // useSearchParams requires a Suspense boundary for static prerender.
+  return (
+    <Suspense fallback={null}>
+      <CheckoutSuccessContent />
+    </Suspense>
+  )
+}

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

@@ -0,0 +1,24 @@
+import { localizedAlternates, getRequestLocale } from '@rovela-ai/sdk/core/server'
+import { getT } from '@rovela-ai/sdk/core'
+import type { Metadata } from 'next'
+
+/**
+ * Server layout for /contact. The page is a client component and can't export
+ * metadata, so this thin wrapper supplies the self-referencing canonical
+ * (resolved against the root layout's metadataBase).
+ */
+export async function generateMetadata() {
+  const { locale } = await getRequestLocale()
+  return {
+    title: getT(locale)('contactPage.title'),
+    alternates: await localizedAlternates('/contact'),
+  }
+}
+
+export default function ContactLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return children
+}

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

@@ -0,0 +1,321 @@
+'use client'
+
+/**
+ * Contact Page
+ *
+ * Contact form that sends messages to the store owner.
+ * Uses SDK email system via /api/contact endpoint.
+ */
+
+import { useState } from 'react'
+import { Mail, Send, CheckCircle, AlertCircle } from 'lucide-react'
+import { useStoreSettings, useT } from '@rovela-ai/sdk/core'
+import { cn, isValidEmail } from '@/lib/utils'
+
+interface FormData {
+  name: string
+  email: string
+  subject: string
+  message: string
+}
+
+interface FormErrors {
+  name?: string
+  email?: string
+  subject?: string
+  message?: string
+}
+
+type FormStatus = 'idle' | 'submitting' | 'success' | 'error'
+
+export default function ContactPage() {
+  const t = useT()
+  const { storeName } = useStoreSettings()
+  const [formData, setFormData] = useState<FormData>({
+    name: '',
+    email: '',
+    subject: '',
+    message: '',
+  })
+  const [errors, setErrors] = useState<FormErrors>({})
+  const [status, setStatus] = useState<FormStatus>('idle')
+  const [errorMessage, setErrorMessage] = useState('')
+
+  const validateForm = (): boolean => {
+    const newErrors: FormErrors = {}
+
+    if (!formData.name.trim() || formData.name.trim().length < 2) {
+      newErrors.name = t('contactPage.nameMin')
+    }
+
+    if (!formData.email.trim()) {
+      newErrors.email = t('form.emailRequired')
+    } else if (!isValidEmail(formData.email)) {
+      newErrors.email = t('form.emailInvalid')
+    }
+
+    if (!formData.subject.trim() || formData.subject.trim().length < 5) {
+      newErrors.subject = t('contactPage.subjectMin')
+    }
+
+    if (!formData.message.trim() || formData.message.trim().length < 10) {
+      newErrors.message = t('contactPage.messageMin')
+    }
+
+    setErrors(newErrors)
+    return Object.keys(newErrors).length === 0
+  }
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+
+    if (!validateForm()) {
+      return
+    }
+
+    setStatus('submitting')
+    setErrorMessage('')
+
+    try {
+      const response = await fetch('/api/contact', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(formData),
+      })
+
+      const data = await response.json()
+
+      if (!response.ok) {
+        throw new Error(data.error || t('contactPage.sendFailed'))
+      }
+
+      setStatus('success')
+      setFormData({ name: '', email: '', subject: '', message: '' })
+    } catch (err) {
+      setStatus('error')
+      setErrorMessage(err instanceof Error ? err.message : t('contactPage.somethingWrong'))
+    }
+  }
+
+  const handleChange = (
+    e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>
+  ) => {
+    const { name, value } = e.target
+    setFormData((prev) => ({ ...prev, [name]: value }))
+    // Clear error when user starts typing
+    if (errors[name as keyof FormErrors]) {
+      setErrors((prev) => ({ ...prev, [name]: undefined }))
+    }
+  }
+
+  return (
+    <div className="container mx-auto px-4 sm:px-6 lg:px-8 py-16">
+      <div className="max-w-2xl mx-auto">
+        {/* Header */}
+        <div className="text-center mb-12">
+          <div className="inline-flex items-center justify-center w-16 h-16 rounded-full bg-primary/10 mb-6">
+            <Mail className="h-8 w-8 text-primary" />
+          </div>
+          <h1 className="text-3xl font-bold font-heading">{t('contactPage.title')}</h1>
+          <p className="mt-4 text-muted-foreground">
+            {t('contactPage.intro')}
+          </p>
+        </div>
+
+        {/* Success State */}
+        {status === 'success' && (
+          <div className="rounded-lg border border-green-200 bg-green-50 dark:bg-green-950/20 dark:border-green-900 p-6 mb-8">
+            <div className="flex items-start gap-4">
+              <CheckCircle className="h-6 w-6 text-green-600 dark:text-green-400 flex-shrink-0 mt-0.5" />
+              <div>
+                <h3 className="font-semibold text-green-800 dark:text-green-200">
+                  {t('contactPage.sentTitle')}
+                </h3>
+                <p className="mt-1 text-sm text-green-700 dark:text-green-300">
+                  {t('contactPage.sentBody', { storeName })}
+                </p>
+                <button
+                  onClick={() => setStatus('idle')}
+                  className="mt-4 text-sm font-medium text-green-700 dark:text-green-300 hover:text-green-800 dark:hover:text-green-200 underline"
+                >
+                  {t('contactPage.sendAnother')}
+                </button>
+              </div>
+            </div>
+          </div>
+        )}
+
+        {/* Error State */}
+        {status === 'error' && (
+          <div className="rounded-lg border border-red-200 bg-red-50 dark:bg-red-950/20 dark:border-red-900 p-6 mb-8">
+            <div className="flex items-start gap-4">
+              <AlertCircle className="h-6 w-6 text-red-600 dark:text-red-400 flex-shrink-0 mt-0.5" />
+              <div>
+                <h3 className="font-semibold text-red-800 dark:text-red-200">
+                  {t('contactPage.failedTitle')}
+                </h3>
+                <p className="mt-1 text-sm text-red-700 dark:text-red-300">
+                  {errorMessage || t('contactPage.failedBody')}
+                </p>
+                <button
+                  onClick={() => setStatus('idle')}
+                  className="mt-4 text-sm font-medium text-red-700 dark:text-red-300 hover:text-red-800 dark:hover:text-red-200 underline"
+                >
+                  {t('contactPage.tryAgain')}
+                </button>
+              </div>
+            </div>
+          </div>
+        )}
+
+        {/* Contact Form */}
+        {status !== 'success' && (
+          <form onSubmit={handleSubmit} className="rounded-lg border bg-card p-6 sm:p-8">
+            <div className="space-y-6">
+              {/* Name Field */}
+              <div>
+                <label
+                  htmlFor="name"
+                  className="block text-sm font-medium mb-2"
+                >
+                  {t('auth.name')}
+                </label>
+                <input
+                  type="text"
+                  id="name"
+                  name="name"
+                  value={formData.name}
+                  onChange={handleChange}
+                  className={cn(
+                    'flex h-10 w-full rounded-md border bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-colors',
+                    errors.name ? 'border-red-500' : 'border-input'
+                  )}
+                  placeholder={t('account.namePlaceholder')}
+                  disabled={status === 'submitting'}
+                />
+                {errors.name && (
+                  <p className="mt-1 text-sm text-red-500">{errors.name}</p>
+                )}
+              </div>
+
+              {/* Email Field */}
+              <div>
+                <label
+                  htmlFor="email"
+                  className="block text-sm font-medium mb-2"
+                >
+                  {t('form.email')}
+                </label>
+                <input
+                  type="email"
+                  id="email"
+                  name="email"
+                  value={formData.email}
+                  onChange={handleChange}
+                  className={cn(
+                    'flex h-10 w-full rounded-md border bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-colors',
+                    errors.email ? 'border-red-500' : 'border-input'
+                  )}
+                  placeholder={t('checkout.emailPlaceholder')}
+                  disabled={status === 'submitting'}
+                />
+                {errors.email && (
+                  <p className="mt-1 text-sm text-red-500">{errors.email}</p>
+                )}
+              </div>
+
+              {/* Subject Field */}
+              <div>
+                <label
+                  htmlFor="subject"
+                  className="block text-sm font-medium mb-2"
+                >
+                  {t('contactPage.subject')}
+                </label>
+                <input
+                  type="text"
+                  id="subject"
+                  name="subject"
+                  value={formData.subject}
+                  onChange={handleChange}
+                  className={cn(
+                    'flex h-10 w-full rounded-md border bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-colors',
+                    errors.subject ? 'border-red-500' : 'border-input'
+                  )}
+                  placeholder={t('contactPage.subjectPlaceholder')}
+                  disabled={status === 'submitting'}
+                />
+                {errors.subject && (
+                  <p className="mt-1 text-sm text-red-500">{errors.subject}</p>
+                )}
+              </div>
+
+              {/* Message Field */}
+              <div>
+                <label
+                  htmlFor="message"
+                  className="block text-sm font-medium mb-2"
+                >
+                  {t('contactPage.message')}
+                </label>
+                <textarea
+                  id="message"
+                  name="message"
+                  rows={5}
+                  value={formData.message}
+                  onChange={handleChange}
+                  className={cn(
+                    'flex w-full rounded-md border bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-colors resize-none',
+                    errors.message ? 'border-red-500' : 'border-input'
+                  )}
+                  placeholder={t('contactPage.messagePlaceholder')}
+                  disabled={status === 'submitting'}
+                />
+                {errors.message && (
+                  <p className="mt-1 text-sm text-red-500">{errors.message}</p>
+                )}
+              </div>
+
+              {/* Submit Button */}
+              <button
+                type="submit"
+                disabled={status === 'submitting'}
+                className={cn(
+                  'w-full flex items-center justify-center gap-2 rounded-md bg-primary px-6 py-3 text-sm font-semibold text-primary-foreground shadow-sm hover:bg-primary/90 transition-colors',
+                  status === 'submitting' && 'opacity-70 cursor-not-allowed'
+                )}
+              >
+                {status === 'submitting' ? (
+                  <>
+                    <div className="h-4 w-4 animate-spin rounded-full border-2 border-primary-foreground border-t-transparent" />
+                    {t('contactPage.sending')}
+                  </>
+                ) : (
+                  <>
+                    <Send className="h-4 w-4" />
+                    {t('contactPage.sendMessage')}
+                  </>
+                )}
+              </button>
+            </div>
+          </form>
+        )}
+
+        {/* Additional Contact Info */}
+        <div className="mt-12 text-center">
+          <p className="text-sm text-muted-foreground">
+            {t('contactPage.reachDirectly')}{' '}
+            <a
+              href={`mailto:${process.env.NEXT_PUBLIC_SUPPORT_EMAIL || 'support@store.com'}`}
+              className="text-primary hover:underline"
+            >
+              {t('contactPage.supportEmail')}
+            </a>
+          </p>
+        </div>
+      </div>
+    </div>
+  )
+}

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

@@ -0,0 +1,153 @@
+import { localizedAlternates, getRequestLocale } from '@rovela-ai/sdk/core/server'
+import type { Metadata } from 'next'
+import { LocaleLink as Link, getT } from '@rovela-ai/sdk/core'
+import { findSettings } from '@rovela-ai/sdk/core/server'
+import { buildFaqJsonLd, serializeJsonLd } from '@rovela-ai/sdk/core'
+import { storeConfig } from '@/lib/store-config'
+import {
+  returnWindowDays,
+  shipsToCountries,
+  freeShippingThreshold,
+  supportEmail,
+} from '@/lib/store-policy'
+
+/**
+ * Store FAQ — server-rendered, with `FAQPage` JSON-LD whose Q&A mirrors the
+ * visible content 1:1 (both read from store_settings + lib/store-policy). FAQ
+ * markup is the single highest-leverage GEO signal (≈3× AI-citation rate), and
+ * AI engines extract answers verbatim, so each answer is self-contained.
+ *
+ * Server Component (no 'use client') so the schema + content are in the initial
+ * HTML — AI crawlers don't execute JavaScript.
+ */
+
+export async function generateMetadata() {
+  const { locale } = await getRequestLocale()
+  const t = getT(locale)
+  return {
+    title: t('faqPage.title'),
+    description: t('faqPage.metaDescription'),
+    alternates: await localizedAlternates('/faq'),
+  }
+}
+
+const COUNTRY_NAMES: Record<string, string> = {
+  US: 'the United States',
+  CA: 'Canada',
+  GB: 'the United Kingdom',
+  AU: 'Australia',
+  NZ: 'New Zealand',
+  IE: 'Ireland',
+  DE: 'Germany',
+  FR: 'France',
+  ES: 'Spain',
+  IT: 'Italy',
+  NL: 'the Netherlands',
+}
+
+function formatCountries(codes: string[]): string {
+  const names = codes.map((c) => COUNTRY_NAMES[c] || c)
+  if (names.length === 1) return names[0]
+  if (names.length === 2) return `${names[0]} and ${names[1]}`
+  return `${names.slice(0, -1).join(', ')}, and ${names[names.length - 1]}`
+}
+
+export default async function FaqPage() {
+  const { locale } = await getRequestLocale()
+  const t = getT(locale)
+  const settings = await findSettings().catch(() => null)
+
+  const countries = shipsToCountries(settings)
+  const freeThreshold = freeShippingThreshold(settings)
+  const email = supportEmail(settings)
+  const returnDays = returnWindowDays()
+  const currency = (settings?.storeCurrency || 'USD').toUpperCase()
+  const guestCheckout = settings?.guestCheckout !== false
+  const processing = String(storeConfig.shipping?.processingTime ?? '1-2-days').replace(/-/g, ' ')
+
+  const faqs: Array<{ question: string; answer: string }> = [
+    {
+      question: 'What payment methods do you accept?',
+      answer:
+        'We accept major credit and debit cards through our secure checkout. Your payment details are encrypted and handled by our payment provider — we never store full card numbers.',
+    },
+    {
+      question: 'Which countries do you ship to?',
+      answer: `We currently ship to ${formatCountries(countries)}.`,
+    },
+    freeThreshold > 0
+      ? {
+          question: 'How much does shipping cost?',
+          answer: `Shipping is calculated at checkout based on your address. Orders over ${freeThreshold} ${currency} qualify for free shipping.`,
+        }
+      : {
+          question: 'How much does shipping cost?',
+          answer:
+            'Shipping is calculated at checkout based on your delivery address and the items in your order.',
+        },
+    {
+      question: 'How long will my order take to arrive?',
+      answer: `Orders are typically processed within ${processing} business days and then shipped. Delivery time depends on your location and the carrier.`,
+    },
+    returnDays > 0
+      ? {
+          question: 'What is your return policy?',
+          answer: `You can return unused items in their original condition within ${returnDays} days of delivery. Return shipping is the customer's responsibility unless the item arrived damaged or incorrect.`,
+        }
+      : {
+          question: 'What is your return policy?',
+          answer:
+            'All sales are final. If your item arrives damaged or incorrect, contact us right away and we will make it right.',
+        },
+    {
+      question: 'Do I need an account to place an order?',
+      answer: guestCheckout
+        ? 'No account is required — you can check out as a guest. Creating an account lets you track orders and check out faster next time.'
+        : 'Please create an account at checkout so you can track your order and manage returns.',
+    },
+    {
+      question: 'How can I contact you?',
+      answer: email
+        ? `Email us at ${email} and we'll get back to you as soon as we can. You can also use our contact page.`
+        : `Reach us through our contact page and we'll get back to you as soon as we can.`,
+    },
+  ]
+
+  const faqJsonLd = buildFaqJsonLd(faqs)
+
+  return (
+    <div className="container mx-auto px-4 sm:px-6 lg:px-8 py-16">
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: serializeJsonLd(faqJsonLd) }}
+      />
+      <div className="max-w-3xl mx-auto">
+        <div className="mb-12">
+          <h1 className="text-3xl font-bold font-heading">{t('faqPage.title')}</h1>
+          <p className="mt-4 text-muted-foreground">
+            {t('faqPage.subtitle')}
+          </p>
+        </div>
+
+        <div className="space-y-10">
+          {faqs.map((f) => (
+            <section key={f.question}>
+              <h2 className="text-xl font-semibold font-heading mb-3">{f.question}</h2>
+              <p className="text-muted-foreground leading-relaxed">{f.answer}</p>
+            </section>
+          ))}
+        </div>
+
+        <div className="mt-12 pt-8 border-t">
+          <p className="text-muted-foreground">
+            {t('faqPage.stillHaveQuestion')}{' '}
+            <Link href="/contact" className="text-primary hover:underline">
+              {t('faqPage.contactUsLink')}
+            </Link>
+            .
+          </p>
+        </div>
+      </div>
+    </div>
+  )
+}