@thorprovider/storefront 0.3.1 → 0.4.0-mvp.0

package/assets/templates/app/lib/__STOREFRONT__/session.ts

@@ -0,0 +1,169 @@
+// Generated by Thor Commerce storefront (composition core: session host).
+//
+// Host session cookie — the Next-bound half of the guest session. `./session.core`
+// owns the pure signing and validation; this module owns the cookie.
+//
+// Next.js 16 `cookies()` is async and may only be MUTATED from a Server Action
+// or a Route Handler — never during a Server Component render. `readHostSession`
+// is therefore the only render-safe export; every other export writes or clears
+// the cookie and MUST be called from an action or route. This is why a guest
+// identity is created in an action/route bootstrap, never in a read-only render.
+//
+// The signing secret is required host configuration (`THOR_SESSION_SECRET`),
+// independent of the backend. It is never embedded, generated as a constant, or
+// printed; a missing or too-short secret throws before any cookie is written.
+// No external SDK is called here; commerce data stays behind adapters/runtime.
+
+import { cookies } from 'next/headers'
+import type { StoreContext } from '@thorprovider/types'
+import {
+  AUTH_TOKEN_TTL_SECONDS,
+  SESSION_TTL_SECONDS,
+  authCookieName,
+  bindSessionCart,
+  completeSessionCart,
+  createHostAuth,
+  createHostSession,
+  decodeHostAuth,
+  decodeHostSession,
+  encodeHostAuth,
+  encodeHostSession,
+  sessionCookieName,
+  type HostSessionPayload,
+} from './session.core'
+
+/** Host environment variable that carries the cookie signing secret. */
+export const SESSION_SECRET_ENV = 'THOR_SESSION_SECRET'
+
+/** Read the required host signing secret; throws (loud) when unset. */
+export function getSessionSecret(): string {
+  const secret = process.env[SESSION_SECRET_ENV]
+  if (!secret || secret.trim() === '') {
+    throw new Error(
+      `${SESSION_SECRET_ENV} is required to sign the storefront session cookie; set it in the host environment (never commit or log it).`,
+    )
+  }
+  return secret
+}
+
+/** Hardened cookie flags: httpOnly, SameSite=Lax, secure in production, TTL. */
+function cookieOptions() {
+  return {
+    httpOnly: true,
+    sameSite: 'lax' as const,
+    secure: process.env.NODE_ENV === 'production',
+    path: '/',
+    maxAge: SESSION_TTL_SECONDS,
+  }
+}
+
+/**
+ * READ-ONLY — safe during a Server Component render.
+ *
+ * Returns the verified session, or null for a missing/tampered/expired/wrong-store
+ * cookie. A null result means "no trusted identity"; the caller must obtain one
+ * from a Server Action or Route Handler, never from client-supplied ids.
+ */
+export async function readHostSession(
+  context: StoreContext,
+): Promise<HostSessionPayload | null> {
+  const store = await cookies()
+  const raw = store.get(sessionCookieName(context.storeId))?.value
+  return decodeHostSession(raw, getSessionSecret(), { expectedContext: context })
+}
+
+/** MUTATION — Server Action or Route Handler only. Issues a fresh identity. */
+export async function issueHostSession(context: StoreContext): Promise<HostSessionPayload> {
+  const payload = createHostSession(context)
+  await writeHostSession(context, payload)
+  return payload
+}
+
+/**
+ * MUTATION — Server Action or Route Handler only. Attaches the active backend
+ * cart to the current identity, issuing one first if the cookie is absent or
+ * untrusted (regenerate instead of trusting a client id).
+ */
+export async function bindHostSessionCart(
+  context: StoreContext,
+  cartId: string,
+): Promise<HostSessionPayload> {
+  const current = await readHostSession(context)
+  const next = bindSessionCart(current ?? createHostSession(context), cartId)
+  await writeHostSession(context, next)
+  return next
+}
+
+/**
+ * MUTATION — Server Action or Route Handler only.
+ *
+ * Clears the active cart ONLY on a confirmed order and preserves `receiptCartId`
+ * for recovery. `receiptCartId` must come from the host's own completed cart,
+ * never from client input. On any error or unresolved completion the caller
+ * must NOT call this, so the active cart is retained and no receipt is recorded.
+ */
+export async function completeHostSessionCart(
+  context: StoreContext,
+  receiptCartId: string,
+): Promise<HostSessionPayload> {
+  const current = await readHostSession(context)
+  const next = completeSessionCart(current ?? createHostSession(context), receiptCartId)
+  await writeHostSession(context, next)
+  return next
+}
+
+/** MUTATION — Server Action or Route Handler only. Clears the session cookie. */
+export async function clearHostSession(context: StoreContext): Promise<void> {
+  const store = await cookies()
+  store.delete(sessionCookieName(context.storeId))
+}
+
+async function writeHostSession(
+  context: StoreContext,
+  payload: HostSessionPayload,
+): Promise<void> {
+  const store = await cookies()
+  store.set(
+    sessionCookieName(context.storeId),
+    encodeHostSession(payload, getSessionSecret()),
+    cookieOptions(),
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Customer auth cookie (change: storefront-customer-auth, task 2.1)
+// ---------------------------------------------------------------------------
+//
+// The auth cookie is separate from the guest session cookie and reuses the same
+// host-only secret and hardened flags. It carries only the customer JWT; the
+// guest session payload/version and the guest cart are never read or written
+// here. As with the guest session, only `readAuthToken` is render-safe.
+
+/**
+ * READ-ONLY — safe during a Server Component render.
+ *
+ * Returns the verified customer token, or null for a missing/tampered/expired/
+ * wrong-store cookie. A null result means "not authenticated".
+ */
+export async function readAuthToken(context: StoreContext): Promise<string | null> {
+  const store = await cookies()
+  const raw = store.get(authCookieName(context.storeId))?.value
+  const payload = decodeHostAuth(raw, getSessionSecret(), { expectedStoreId: context.storeId })
+  return payload?.token ?? null
+}
+
+/** MUTATION — Server Action or Route Handler only. Persists the customer token. */
+export async function writeAuthToken(context: StoreContext, token: string): Promise<void> {
+  const store = await cookies()
+  store.set(
+    authCookieName(context.storeId),
+    encodeHostAuth(createHostAuth(context.storeId, token), getSessionSecret()),
+    { ...cookieOptions(), maxAge: AUTH_TOKEN_TTL_SECONDS },
+  )
+}
+
+/** MUTATION — Server Action or Route Handler only. Clears the auth cookie. */
+export async function clearAuthToken(context: StoreContext): Promise<void> {
+  const store = await cookies()
+  store.delete(authCookieName(context.storeId))
+}

package/assets/templates/app/lib/__STOREFRONT__/shell/content.ts

@@ -0,0 +1,96 @@
+// Thor Commerce shell content: brand accents, surface classes, and footer copy.
+//
+// User-owned shell content — reconcile seeds this file once and never rewrites
+// it, so your edits survive `storefront sync`. Plain data only: no React and no
+// server imports.
+//
+// Neutral defaults only: no delivery, shipping, or promo promise is made here,
+// and footer links point only at routes the generated storefront actually
+// serves (`/`, `/categorias`, `/checkout`, and the static pages `/contacto`,
+// `/sobre-nosotros`, `/terminos`, `/privacidad`). Brand colors and copy belong
+// in your own content, never in the package.
+//
+// The scaffold ships no newsletter submit callback, so the footer newsletter is
+// omitted by default. A content-only `newsletter` is swallowed by the block
+// (no form renders); wiring a real host callback to enable it is an external
+// integration, out of scope for the scaffold.
+
+export interface ShellAccent {
+  /** Trailing segment of the site-name wordmark to render with the accent. */
+  text: string
+  /** Consumer-supplied classes for the accent span (e.g. a brand color token). */
+  className?: string
+}
+
+export interface ShellLink {
+  label: string
+  /** A route the storefront actually serves. Omit for a non-link label. */
+  href?: string
+}
+
+export interface ShellLinkColumn {
+  title: string
+  links: ShellLink[]
+}
+
+export interface ShellNewsletter {
+  placeholder?: string
+  buttonLabel: string
+}
+
+/**
+ * Optional trailing accent for the navbar wordmark, e.g. the "Cuba" in
+ * "ElectroCuba". Leave `undefined` to render the wordmark in one colour. The
+ * accent only applies when `text` is a trailing segment of the site name.
+ */
+export const logoAccent: ShellAccent | undefined = undefined
+
+/**
+ * Optional trailing accent for the footer brand name. Same trailing-segment
+ * rule as `logoAccent`.
+ */
+export const brandAccent: ShellAccent | undefined = undefined
+
+/**
+ * Optional classes merged onto the navbar's outer surface (e.g.
+ * `bg-brand-nav text-brand-nav-foreground`). Leave `undefined` for the default.
+ */
+export const navbarClassName: string | undefined = undefined
+
+/**
+ * Optional classes merged onto the footer's outer surface. Leave `undefined`
+ * for the default.
+ */
+export const footerClassName: string | undefined = undefined
+
+/** Neutral footer brand description. No delivery/shipping promise. */
+export const brandDescription: string =
+  'Catálogo en línea de productos para tu hogar y tu negocio.'
+
+/** Neutral footer links — only routes the storefront serves; no dead `#` links. */
+export const linkColumns: ShellLinkColumn[] = [
+  {
+    title: 'Comprar',
+    links: [
+      { label: 'Inicio', href: '/' },
+      { label: 'Todas las categorías', href: '/categorias' },
+      { label: 'Finalizar compra', href: '/checkout' },
+    ],
+  },
+  {
+    title: 'Información',
+    links: [
+      { label: 'Contacto', href: '/contacto' },
+      { label: 'Sobre nosotros', href: '/sobre-nosotros' },
+      { label: 'Términos y condiciones', href: '/terminos' },
+      { label: 'Política de privacidad', href: '/privacidad' },
+    ],
+  },
+]
+
+/**
+ * Footer newsletter content. The scaffold has no working submit handler, so it
+ * is omitted by default (`false`). Setting it without a host-provided callback
+ * renders no form — never a fake one.
+ */
+export const newsletter: false | ShellNewsletter = false

package/assets/templates/app/lib/__STOREFRONT__/shell/props.ts

@@ -0,0 +1,34 @@
+// Thor Commerce shell props: the shell chrome element props composed from the
+// user-owned shell content. Reconcile seeds this file once and never rewrites
+// it; the derived spec (../spec/index.ts) imports these objects and binds them
+// into the shell element tree, so edits here survive `storefront sync`.
+// Plain data only: no React and no server imports.
+
+import {
+  brandAccent,
+  brandDescription,
+  footerClassName,
+  linkColumns,
+  logoAccent,
+  navbarClassName,
+  newsletter,
+} from './content'
+
+export const navbarShellProps = {
+  logoAccent,
+  className: navbarClassName,
+  // Global navigation search is held until a verified backend search contract
+  // exists (E2 task 5.4), so the generated storefront presents NO search
+  // control. A merchant may set this to `true` to opt in once the contract is
+  // verified; the `Navbar4` block still defaults to visible for legacy
+  // consumers that do not set this prop.
+  showSearch: false,
+}
+
+export const footerShellProps = {
+  brandAccent,
+  brandDescription,
+  linkColumns,
+  className: footerClassName,
+  ...(newsletter ? { newsletter } : {}),
+}

package/assets/templates/app/lib/__STOREFRONT__/spec/index.ts

@@ -3,23 +3,110 @@
 // Routes are derived from the view barrel; adding a view never edits this file.
 
 import type { NextAppSpec } from '@json-render/next'
+import { storefrontInitialState } from '../state'
 import { views } from '../views'
+import { footerShellProps, navbarShellProps } from '../shell/props'
 import type { StorefrontElement } from './types'
 
 export type { StorefrontElement }
 
+// The spec's state is a plain record; spreading the typed initial state keeps
+// the single source of truth in ../state while satisfying the index signature.
+const initialState: Record<string, unknown> = { ...storefrontInitialState }
+
 const routes = Object.fromEntries(
-  views.map((view) => [
-    view.route.path,
-    {
-      layout: view.route.layout,
-      loader: view.route.loaderName,
-      metadata: view.route.metadata,
-      ...view.route.entry,
-    },
-  ]),
+  views.flatMap((view) => {
+    // A view declares one route or several; normalise to an array and flatten so
+    // a multi-route view (content-driven static pages) contributes one page per
+    // declared route while a single-route view is unchanged.
+    const viewRoutes = Array.isArray(view.route) ? view.route : [view.route]
+    return viewRoutes.map((route) => [
+      route.path,
+      {
+        layout: route.layout,
+        loader: route.loaderName,
+        metadata: route.metadata,
+        ...route.entry,
+      },
+    ])
+  }),
 )
 
+// The default layout is the storefront chrome shared by every page: the
+// system notice region sits in the notices slot (always first, above the
+// header), the announcement banner and navbar live in the header slot, the
+// footer in the footer slot, and the cart drawer is a page-level child of
+// Layout (rendered outside the slots so it can overlay the whole shell). This
+// mirrors the reference app so a fresh scaffold ships a real storefront, not a
+// bare page.
+const shellElements: Record<string, StorefrontElement> = {
+  // Reserved top region for system/status messages. Only the shell layout
+  // references it, so it renders once and always as the first element.
+  notice: {
+    type: 'SystemNotice',
+    props: {},
+  },
+  banner: {
+    type: 'Banner',
+    props: {
+      badge: 'Novedades',
+      message: 'Descubre el catálogo de __SITE_NAME__.',
+      href: '/categorias',
+      linkLabel: 'Ver catálogo',
+    },
+    visible: { $state: '/bannerDismissed', not: true },
+    on: { dismissBanner: { action: 'dismissBanner' } },
+  },
+  navbar: {
+    type: 'StorefrontNavbar',
+    props: {
+      storeCategories: { $state: '/navCategories' },
+      // Neutral store info: no delivery/COD/shipping promise is made by default.
+      shippingNote: 'Catálogo en línea',
+      utilityLinks: [],
+      logoText: '__SITE_NAME__',
+      logoHref: '/',
+      // Optional wordmark accent and surface classes, configured in the
+      // user-owned shell seam. Spread last so merchant edits win.
+      ...navbarShellProps,
+    },
+    on: {
+      openCart: { action: 'openCart' },
+      goToCheckout: { action: 'goToCheckout' },
+      applyQuantityDelta: { action: 'applyQuantityDelta' },
+      removeFromCart: { action: 'removeFromCart' },
+    },
+  },
+  'cart.drawer': {
+    type: 'CartDrawer',
+    props: {
+      // No fabricated free-shipping threshold or reward: the backend is the only
+      // source of shipping amounts, and a promotion promise is not supported by
+      // the default fixture. A merchant may add promotions as customization.
+      promotions: [],
+      taxRate: 0.0,
+    },
+    visible: { $state: '/cartOpen', eq: true },
+    on: {
+      updateQuantity: { action: 'updateQuantity' },
+      removeFromCart: { action: 'removeFromCart' },
+      goToCheckout: { action: 'goToCheckout' },
+      closeCart: { action: 'closeCart' },
+      refreshCart: { action: 'refreshCart' },
+    },
+  },
+  footer: {
+    type: 'Footer',
+    props: {
+      brandName: '__SITE_NAME__',
+      // Footer brand description, links, accent, and surface classes all come
+      // from the user-owned shell seam. Spread last so merchant edits win; no
+      // delivery/shipping promise and no dead `#` link is shipped by default.
+      ...footerShellProps,
+    },
+  },
+}
+
 export const __STOREFRONT_CAMEL__Spec: NextAppSpec = {
   metadata: {
     title: {
@@ -28,7 +115,7 @@ export const __STOREFRONT_CAMEL__Spec: NextAppSpec = {
     },
     description: 'Tienda online de __SITE_NAME__.',
   },
-  state: {},
+  state: initialState,
   layouts: {
     default: {
       root: 'layout',
@@ -36,11 +123,13 @@ export const __STOREFRONT_CAMEL__Spec: NextAppSpec = {
         layout: {
           type: 'Layout',
           props: {},
-          children: ['slot'],
+          slots: { notices: ['notice'], header: ['banner', 'navbar'], footer: ['footer'] },
+          children: ['slot', 'cart.drawer'],
         },
         // The page content is injected at the Slot element by @json-render/next.
         // Without it the rendered layout drops the page and the store looks empty.
         slot: { type: 'Slot', props: {}, children: [] },
+        ...shellElements,
       },
     },
   },

package/assets/templates/app/lib/__STOREFRONT__/spec/page-root.ts

@@ -19,7 +19,11 @@ export const pageRoot = (
   page: {
     root: id,
     elements: {
-      [id]: { type: 'Layout', props: {}, children },
+      // `Page` is a neutral container, not the shell `Layout`: the shell is
+      // already rendered by the route's layoutSpec, so nesting another Layout
+      // here would duplicate chrome (header/footer/main) and any shell-only
+      // notices.
+      [id]: { type: 'Page', props: {}, children },
       ...elements,
     },
   },

package/assets/templates/app/lib/__STOREFRONT__/spec/seo.ts

@@ -0,0 +1,26 @@
+// Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/spec/seo.ts)
+// Pure SEO helpers shared by the seeded-once `app/sitemap.ts` and `app/robots.ts`
+// host files. Kept free of Next.js, React, and env imports so the logic is
+// testable at the source and the host files stay thin.
+
+/** The routes the storefront can serve as fixed pages (no dynamic `[` segment). */
+export function fixedRoutePaths(routes: Record<string, unknown>): string[] {
+  return Object.keys(routes).filter((path) => !path.includes('['))
+}
+
+/**
+ * Absolute sitemap URLs for the fixed routes. Emits nothing when no site URL is
+ * configured, so no canonical URL is invented.
+ */
+export function sitemapUrls(
+  routes: Record<string, unknown>,
+  siteUrl: string | undefined,
+): string[] {
+  if (!siteUrl) return []
+  return fixedRoutePaths(routes).map((path) => new URL(path, siteUrl).toString())
+}
+
+/** Absolute URL of the sitemap for `robots.txt`, or undefined without a site URL. */
+export function robotsSitemapUrl(siteUrl: string | undefined): string | undefined {
+  return siteUrl ? new URL('/sitemap.xml', siteUrl).toString() : undefined
+}