@rovela-ai/sdk 0.19.3 → 0.19.5

package/templates/store-template/lib/store-policy.ts

@@ -0,0 +1,68 @@
+/**
+ * Single source of truth for the store's shipping / returns / contact facts,
+ * derived from real configured data (lib/store-config.ts + store_settings).
+ *
+ * Both the Organization JSON-LD (app/layout.tsx) and the visible + marked-up
+ * FAQ (app/faq/page.tsx) read from here, so the structured data ALWAYS mirrors
+ * the visible page content — the invariant search + AI engines require (a
+ * mismatch gets the listing suppressed).
+ */
+
+import { findSettings } from '@rovela-ai/sdk/core/server'
+import type { ReturnPolicyInput } from '@rovela-ai/sdk/core'
+import { storeConfig } from '@/lib/store-config'
+
+type Settings = Awaited<ReturnType<typeof findSettings>>
+
+/** Parse `storeConfig.orders.returnPolicy` ('30-days' | 'no-returns' | '14-days' …) → days. */
+export function returnWindowDays(): number {
+  const p = String(storeConfig.orders?.returnPolicy ?? '30-days')
+  if (/no[-\s]?return/i.test(p)) return 0
+  const m = p.match(/(\d+)/)
+  return m ? parseInt(m[1], 10) : 30
+}
+
+/** Conservative default — merchant states the real policy on /faq + legal. */
+export const RETURN_FEES: 'free' | 'customer-paid' = 'customer-paid'
+
+export function shipsToCountries(settings: Settings): string[] {
+  return settings?.shippingCountries && settings.shippingCountries.length > 0
+    ? settings.shippingCountries
+    : ['US']
+}
+
+export function freeShippingThreshold(settings: Settings): number {
+  return settings?.freeShippingThreshold && settings.freeShippingThreshold > 0
+    ? settings.freeShippingThreshold
+    : 0
+}
+
+/**
+ * Public support email — merchant's own only. Never the `support@store.com`
+ * placeholder or a Rovela address. Falls back to support@<live-domain>.
+ */
+export function supportEmail(settings: Settings): string | null {
+  const fromSettings = settings?.storeEmail?.trim()
+  if (fromSettings) return fromSettings
+  const cfg = storeConfig.supportEmail
+  if (cfg && cfg !== 'support@store.com') return cfg
+  const host = (process.env.NEXT_PUBLIC_APP_URL || '')
+    .replace(/^https?:\/\//, '')
+    .replace(/\/.*$/, '')
+    .trim()
+  const ownDomain =
+    !!host &&
+    !host.endsWith('rovela.app') &&
+    !host.endsWith('vercel.app') &&
+    !host.startsWith('localhost')
+  return ownDomain ? `support@${host}` : null
+}
+
+/** Return-policy shape for `buildStoreJsonLdGraph`. Days `0` ⇒ "returns not permitted". */
+export function returnPolicyInput(settings: Settings): ReturnPolicyInput {
+  return {
+    merchantReturnDays: returnWindowDays(),
+    returnFees: RETURN_FEES,
+    applicableCountry: shipsToCountries(settings)[0] || 'US',
+  }
+}

package/templates/store-template/lib/utils.ts

@@ -0,0 +1,21 @@
+/**
+ * Utility Functions
+ *
+ * Re-exports utilities from @rovela-ai/sdk/core for convenience.
+ * Add any store-specific utilities below the re-exports.
+ */
+
+// Re-export SDK utilities
+export {
+  cn,
+  formatPrice,
+  parsePrice,
+  generateSlug,
+  formatDate,
+  formatRelativeTime,
+  truncate,
+  capitalize,
+  titleCase,
+  isValidEmail,
+  isValidPhone,
+} from '@rovela-ai/sdk/core'

package/templates/store-template/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/templates/store-template/next.config.js

@@ -0,0 +1,105 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // Enable transpilation of the SDK package
+  transpilePackages: ['@rovela-ai/sdk'],
+
+  // Next.js 16 blocks dev-only requests (HMR WebSocket included) from any
+  // origin other than `localhost` by default. Sandbox previews are served
+  // cross-origin via Blaxel's proxy on hostnames like
+  //   <hash>.<region>.preview.bl.run  (e.g. abc...88.us-was-1.preview.bl.run)
+  // The matcher Next uses (server/app-render/csrf-protection.js → `isCsrfOriginAllowed`)
+  // is segment-by-segment: a single `*` matches ONE label only, so
+  // `*.preview.bl.run` matches `foo.preview.bl.run` but NOT
+  // `foo.us-was-1.preview.bl.run` (two leading labels). Use `**` for
+  // cross-label matching — survives Blaxel adding new regions later.
+  // See: https://nextjs.org/docs/app/api-reference/config/next-config-js/allowedDevOrigins
+  allowedDevOrigins: ['**.preview.bl.run', '**.bl.run'],
+
+  // Hide Next.js dev badge — merchants see the sandbox preview during edit
+  // sessions and the badge looks like a bug to non-technical users. No-op in
+  // production builds (badge only renders in `next dev`).
+  devIndicators: false,
+
+  // Skip TypeScript build-time check. The sandbox runs `next dev` continuously
+  // during merchant edits — type errors surface immediately in the preview, so
+  // by the time we redeploy, the code is already validated. Re-checking on
+  // Vercel's build container is wasted time. Belt-and-suspenders only since
+  // Turbopack itself doesn't run tsc.
+  typescript: { ignoreBuildErrors: true },
+
+  // THE WIN: Turbopack filesystem cache for production builds. Vercel
+  // preserves `.next/cache` between deploys; without this flag, Turbopack
+  // ignores it and rebuilds everything from scratch each time (~55s).
+  // With the flag, warm rebuilds reuse cached compiler artifacts and drop
+  // to ~10-15s.
+  //
+  // Empirically validated (2026-05-13): sandbox build time goes from 24s
+  // warm → 5s warm with this flag enabled. Translation for Vercel:
+  // first deploy of a new project stays ~55s (cold), every subsequent
+  // deploy drops to ~10-15s. Opt-in experimental flag in Next.js 16,
+  // expected to graduate to stable.
+  experimental: {
+    turbopackFileSystemCacheForBuild: true,
+  },
+
+  // Ship the blueprint with EVERY serverless function. The email theme
+  // derives brand colors/fonts by reading .rovela/blueprint.json at runtime
+  // through a bundler-invisible loader (the emails graph is client-reachable,
+  // so it cannot statically import fs) -- which also makes the read invisible
+  // to Vercel's file tracer. Without this, only routes that statically import
+  // the SDK's core/config get the file, and every other function (checkout,
+  // webhooks, auth, admin emails) silently falls back to default styling.
+  outputFileTracingIncludes: {
+    '/**': ['./.rovela/blueprint.json'],
+  },
+
+  // Image domains for Unsplash, CDNs, and R2 storage
+  images: {
+    remotePatterns: [
+      {
+        protocol: 'https',
+        hostname: 'images.unsplash.com',
+      },
+      {
+        protocol: 'https',
+        hostname: '*.unsplash.com',
+      },
+      {
+        protocol: 'https',
+        hostname: '*.supabase.co',
+      },
+      {
+        protocol: 'https',
+        hostname: '*.cloudflare.com',
+      },
+      // R2 storage domains
+      {
+        protocol: 'https',
+        hostname: '*.r2.dev',
+      },
+      {
+        protocol: 'https',
+        hostname: '*.r2.cloudflarestorage.com',
+      },
+    ],
+  },
+
+  // Serve the AI-assistant identity file (public/llms.txt, written during
+  // generation) as Markdown, and keep it out of the search index — it's an
+  // identity / anti-hallucination signal for ChatGPT / Perplexity / Claude,
+  // not a ranking page.
+  async headers() {
+    return [
+      {
+        source: '/llms.txt',
+        headers: [
+          { key: 'Content-Type', value: 'text/markdown; charset=utf-8' },
+          { key: 'X-Robots-Tag', value: 'noindex' },
+        ],
+      },
+    ]
+  },
+
+}
+
+module.exports = nextConfig

package/templates/store-template/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "store",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint ."
+  },
+  "dependencies": {
+    "@rovela-ai/sdk": "0.19.4",
+    "@tailwindcss/forms": "0.5.11",
+    "@tailwindcss/typography": "0.5.19",
+    "autoprefixer": "10.4.24",
+    "lucide-react": "0.555.0",
+    "next": "16.1.6",
+    "next-auth": "4.24.13",
+    "postcss": "8.5.6",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "tailwindcss": "3.4.19"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.13",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "eslint": "9.39.2",
+    "eslint-config-next": "16.1.6",
+    "typescript": "5.9.3"
+  }
+}

package/templates/store-template/postcss.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

package/templates/store-template/proxy.ts

@@ -0,0 +1,150 @@
+import { NextRequest, NextResponse } from 'next/server'
+// Pure locale data (no React, edge-safe). SINGLE SOURCE: adding a language
+// to the SDK automatically extends prefix parsing + geo detection here.
+import { SUPPORTED_LOCALES, COUNTRY_TO_LOCALE } from '@rovela-ai/sdk/locales'
+
+/**
+ * Canonical-host redirect (SEO / trust).
+ *
+ * A deployed store answers on several hosts that all serve identical content:
+ *   - the Rovela deployment URL        ( *.rovela.app )
+ *   - Vercel's deployment aliases      ( *.vercel.app, including per-deploy hashes )
+ *   - the merchant's own custom domain ( e.g. mystore.com ), once verified
+ *
+ * With no single canonical host, search engines and AI shopping crawlers index
+ * EVERY host as a separate site — duplicate content, diluted ranking, and the
+ * platform's *.rovela.app / *.vercel.app URLs surfacing in Google instead of the
+ * merchant's brand. (This is exactly what happened to early stores.)
+ *
+ * Fix: derive the canonical host from NEXT_PUBLIC_APP_URL — the merchant's live
+ * URL, which the platform points at the custom domain once it verifies and then
+ * triggers a rebuild so this value is re-inlined. When that canonical host is a
+ * real custom domain and a request arrives on a DIFFERENT host, 308-redirect to
+ * the canonical host (preserving path, query, method, and body).
+ *
+ * Strictly gated: it only ever fires when the canonical host is a real custom
+ * domain. While a store still lives on *.rovela.app (no custom domain yet), or
+ * inside the sandbox / preview ( *.bl.run ) or on localhost, the canonical host
+ * is NOT a custom domain, so nothing redirects and there are no loops.
+ *
+ * NEXT_PUBLIC_APP_URL is inlined at build time, so this constant is resolved
+ * once per cold start with the value baked into the deployment.
+ */
+
+function resolveCanonicalHost(): string | null {
+  const raw = process.env.NEXT_PUBLIC_APP_URL || ''
+  if (!raw) return null
+
+  let host: string
+  try {
+    host = new URL(raw).host.toLowerCase()
+  } catch {
+    return null
+  }
+
+  // Only a real custom domain is a valid redirect target. Platform + preview +
+  // local hosts are never canonical.
+  if (
+    !host ||
+    host.endsWith('.rovela.app') ||
+    host.endsWith('.vercel.app') ||
+    host.endsWith('.bl.run') ||
+    host.startsWith('localhost') ||
+    host.startsWith('127.0.0.1')
+  ) {
+    return null
+  }
+
+  return host
+}
+
+const CANONICAL_HOST = resolveCanonicalHost()
+
+/**
+ * Locale routing (i18n core — SDK `core/i18n`).
+ *
+ * The proxy stays DB-FREE (edge runtime): it only PARSES the URL and
+ * forwards detection hints as request headers; the redirect DECISIONS
+ * (which need store settings) live in the root layout via the SDK's
+ * `resolveLocaleRedirect`. Contract:
+ *
+ *   /fr/products  → rewrite to /products  + `x-rovela-locale: fr`
+ *   any request   → `x-rovela-geo-locale` (from x-vercel-ip-country, hint
+ *                   only) + `x-rovela-pathname` (ORIGINAL path, prefix
+ *                   included — the layout builds redirects from it)
+ *
+ * Locale prefixes are only parsed for page-like paths — /api, /admin,
+ * Next internals and file requests pass through untouched.
+ */
+function parseLocalePrefix(pathname: string): { locale: string; rest: string } | null {
+  for (const l of SUPPORTED_LOCALES) {
+    if (pathname === `/${l}` || pathname.startsWith(`/${l}/`)) {
+      const rest = pathname.slice(l.length + 1) || '/'
+      // Never treat /fr/api or /fr/admin as localized surfaces.
+      if (rest.startsWith('/api') || rest.startsWith('/admin')) return null
+      return { locale: l, rest }
+    }
+  }
+  return null
+}
+
+function isLocaleEligible(pathname: string): boolean {
+  if (pathname.startsWith('/api') || pathname.startsWith('/admin')) return false
+  if (pathname.startsWith('/_next')) return false
+  // File requests (images, sitemap.xml, robots.txt, …) are never localized.
+  if (/\.[a-zA-Z0-9]+$/.test(pathname)) return false
+  return true
+}
+
+export function proxy(request: NextRequest) {
+  // ── 1. Canonical-host redirect (must run first: one hop lands the visitor
+  //       on the canonical host WITH their original path, locale prefix
+  //       included; the next request there does the locale work). ──
+  const requestHost = (request.headers.get('host') || '').toLowerCase().split(':')[0]
+  if (
+    CANONICAL_HOST &&
+    requestHost &&
+    requestHost !== CANONICAL_HOST &&
+    requestHost !== 'localhost' &&
+    requestHost !== '127.0.0.1'
+  ) {
+    const url = new URL(request.url)
+    url.protocol = 'https:'
+    url.host = CANONICAL_HOST
+    url.port = ''
+    // 308 (permanent + method/body preserving) so Google consolidates ranking
+    // signals onto the canonical host and POSTs to API routes are not broken.
+    return NextResponse.redirect(url, 308)
+  }
+
+  // ── 2. Locale parse + detection hints. ──
+  const url = new URL(request.url)
+  if (!isLocaleEligible(url.pathname)) return NextResponse.next()
+
+  const requestHeaders = new Headers(request.headers)
+  requestHeaders.set('x-rovela-pathname', url.pathname)
+
+  const country = (request.headers.get('x-vercel-ip-country') || '').toUpperCase()
+  // Raw IP country for the cookie-banner region rule (consentRegionExempt).
+  // Missing/unknown country fails CLOSED (banner shows) — see cookie-consent.
+  if (country) requestHeaders.set('x-rovela-country', country)
+  const geoLocale = COUNTRY_TO_LOCALE[country]
+  if (geoLocale) requestHeaders.set('x-rovela-geo-locale', geoLocale)
+
+  const parsed = parseLocalePrefix(url.pathname)
+  if (parsed) {
+    requestHeaders.set('x-rovela-locale', parsed.locale)
+    const rewritten = new URL(url)
+    rewritten.pathname = parsed.rest
+    return NextResponse.rewrite(rewritten, { request: { headers: requestHeaders } })
+  }
+
+  return NextResponse.next({ request: { headers: requestHeaders } })
+}
+
+export const config = {
+  // Run on everything EXCEPT Next internals, static assets, and ACME / domain
+  // verification paths (served by the platform, not the app). The redirect must
+  // still cover pages, API routes, sitemap.xml, robots.txt, and OG images.
+  matcher: ['/((?!_next/static|_next/image|_next/data|\\.well-known|favicon\\.ico).*)'],
+}

package/templates/store-template/tailwind.config.ts

@@ -0,0 +1,74 @@
+/**
+ * Tailwind CSS Configuration
+ *
+ * NOTE: This file is a placeholder. Claude Agent will regenerate it using:
+ *   import { generateTailwindConfig } from '@rovela-ai/sdk/theme'
+ *   const config = generateTailwindConfig(blueprint.theme)
+ *
+ * This default configuration provides basic styling for the initial build.
+ */
+
+import type { Config } from 'tailwindcss'
+
+const config: Config = {
+  content: [
+    './app/**/*.{js,ts,jsx,tsx,mdx}',
+    './components/**/*.{js,ts,jsx,tsx,mdx}',
+    './lib/**/*.{js,ts,jsx,tsx,mdx}',
+    // Include SDK components
+    './node_modules/@rovela-ai/sdk/**/*.{js,ts,jsx,tsx}',
+  ],
+  theme: {
+    extend: {
+      colors: {
+        // Semantic colors (CSS variables set in globals.css)
+        background: 'hsl(var(--background))',
+        foreground: 'hsl(var(--foreground))',
+        card: {
+          DEFAULT: 'hsl(var(--card))',
+          foreground: 'hsl(var(--card-foreground))',
+        },
+        popover: {
+          DEFAULT: 'hsl(var(--popover))',
+          foreground: 'hsl(var(--popover-foreground))',
+        },
+        primary: {
+          DEFAULT: 'hsl(var(--primary))',
+          foreground: 'hsl(var(--primary-foreground))',
+        },
+        secondary: {
+          DEFAULT: 'hsl(var(--secondary))',
+          foreground: 'hsl(var(--secondary-foreground))',
+        },
+        muted: {
+          DEFAULT: 'hsl(var(--muted))',
+          foreground: 'hsl(var(--muted-foreground))',
+        },
+        accent: {
+          DEFAULT: 'hsl(var(--accent))',
+          foreground: 'hsl(var(--accent-foreground))',
+        },
+        destructive: {
+          DEFAULT: 'hsl(var(--destructive))',
+          foreground: 'hsl(var(--destructive-foreground))',
+        },
+        border: 'hsl(var(--border))',
+        input: 'hsl(var(--input))',
+        ring: 'hsl(var(--ring))',
+      },
+      borderRadius: {
+        lg: 'var(--radius)',
+        md: 'calc(var(--radius) - 2px)',
+        sm: 'calc(var(--radius) - 4px)',
+      },
+      fontFamily: {
+        heading: ['var(--font-heading)', 'system-ui', 'sans-serif'],
+        body: ['var(--font-body)', 'system-ui', 'sans-serif'],
+        mono: ['var(--font-mono)', 'monospace'],
+      },
+    },
+  },
+  plugins: [],
+}
+
+export default config

package/templates/store-template/tsconfig.json

@@ -0,0 +1,41 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./*"
+      ]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/templates/store-template/types/next-auth.d.ts

@@ -0,0 +1,32 @@
+import 'next-auth'
+
+declare module 'next-auth' {
+  interface Session {
+    user: {
+      id: string
+      email: string
+      name?: string | null
+      image?: string | null
+      emailVerified?: boolean
+      role?: 'owner' | 'admin'
+    }
+  }
+
+  interface User {
+    id: string
+    email: string
+    name?: string | null
+    emailVerified?: boolean
+    role?: 'owner' | 'admin'
+  }
+}
+
+declare module 'next-auth/jwt' {
+  interface JWT {
+    id: string
+    email: string
+    name?: string | null
+    emailVerified?: boolean
+    role?: 'owner' | 'admin'
+  }
+}