@ecomiq/storefront 2.0.20 → 2.0.22

package/README.md

@@ -22,7 +22,9 @@ Peer deps: `react` y `react-dom` ^19.
 import { defineConfig } from '@ecomiq/storefront/config'
 
 export default defineConfig({
-  store: { slug: 'mi-tienda' },
+  domain: 'mi-tienda',
+  // Server-only. Obligatorio en producción para usar una publicación de Cloud.
+  cloud: { baseUrl: 'https://cloud.internal.example' },
 })
 ```
 
@@ -31,10 +33,7 @@ export default defineConfig({
 import { definePage, serverApi } from '@ecomiq/storefront'
 
 export default definePage({
-  loader: async () => {
-    const products = await serverApi.products.list()
-    return { products }
-  },
+  loader: () => serverApi.getProducts({ page: 1, pageSize: 12 }),
   component: ({ data }) => <pre>{JSON.stringify(data.products, null, 2)}</pre>,
 })
 ```
@@ -64,4 +63,71 @@ dev: { port: 3000, runtime: 'workerd' },
 
 `ecomiq build` / `deploy` siempre empaquetan para Cloudflare Workers.
 
+Durante `ecomiq dev`, si `cloud.baseUrl` se omite, el framework conecta a
+`http://127.0.0.1:8020`. En producción no se inventa un hostname: si falta la
+URL o Cloud no tiene una publicación activa, el template conserva su home
+clásica.
+
 Ver el monorepo [ecomiq-storefront](https://github.com/ecomiq/ecomiq-storefront) para la app de referencia y más documentación.
+
+## Storefront declarativo
+
+`StorefrontDefinition v1` permite construir y versionar una tienda sin generar
+código React arbitrario. El contrato valida tema, navegación, footer y ocho
+tipos de sección: `hero`, `product-grid`, `collection-grid`, `promo-banner`,
+`image-text`, `rich-text`, `testimonials` y `newsletter`.
+
+```tsx
+import {
+  StorefrontDefinitionRenderer,
+  createDefaultStorefrontDefinition,
+} from '@ecomiq/storefront'
+
+const definition = createDefaultStorefrontDefinition({
+  storeName: 'Casa Lumbre',
+  description: 'Cerámica producida localmente.',
+})
+
+export function Home() {
+  return (
+    <StorefrontDefinitionRenderer
+      definition={definition}
+      locale="es-PE"
+      currency="PEN"
+      data={{
+        productsBySectionId: {
+          'featured-products': [],
+        },
+        collectionsBySectionId: {
+          'featured-collections': [],
+        },
+      }}
+    />
+  )
+}
+```
+
+Los sistemas que solo necesitan validar o modificar el contrato pueden importar
+el subpath sin cargar el renderer:
+
+```ts
+import {
+  StorefrontDefinitionSchema,
+  StorefrontDefinitionPatchSchema,
+  applyStorefrontDefinitionPatch,
+  type StorefrontDefinitionInput,
+  type StorefrontDefinitionPatchInput,
+} from '@ecomiq/storefront/definition'
+```
+
+Cada definición lleva `version` y `revision`. Los patches son puros, exigen
+`expectedRevision` y conservan el ID de una sección al reemplazarla. Soportan
+`section.add`, `section.replace`, `section.remove`, `section.reorder`,
+`theme.replace`, `navigation.replace` y `footer.replace`.
+
+El template productivo consulta server-side
+`GET /v1/runtime/storefronts/:storeSlug`, revalida la publicación mediante
+ETag y resuelve los `product-grid.source` y `collection-grid.source` contra el
+API storefront. La publicación declarativa reemplaza solo el contenido de la
+home; el layout comercial y las rutas de catálogo, producto, carrito, checkout
+y cuenta siguen siendo las del framework.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecomiq/storefront",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "description": "Micro framework SSR de Ecomiq para storefronts. Páginas, datos y deploy sin configurar nada.",
   "type": "module",
   "license": "MIT",
@@ -32,6 +32,8 @@
       "default": "./src/config.mjs"
     },
     "./ui": "./src/ui/index.ts",
+    "./definition": "./src/storefront-definition/contract.ts",
+    "./definition/react": "./src/storefront-definition/index.ts",
     "./styles.css": "./src/styles.css",
     "./internal/page": "./src/runtime/page.tsx",
     "./internal/context": "./src/runtime/context.ts",
@@ -82,7 +84,8 @@
     "vite": "^8.1.0",
     "wrangler": "^4.100.0",
     "zod": "^3.25.0",
-    "@ecomiq/core": "^0.1.7"
+    "@ecomiq/core": "^0.1.8",
+    "@ecomiq/storefront-definition": "^1.0.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/cloud-runtime-client.ts

@@ -0,0 +1,218 @@
+import { z } from 'zod'
+import { StorefrontDefinitionSchema } from '@ecomiq/storefront-definition'
+
+export const CloudRuntimeStoreSlugSchema = z
+  .string()
+  .trim()
+  .min(2)
+  .max(100)
+  .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
+
+export const ActiveStorefrontRuntimeSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    store: z
+      .object({
+        slug: CloudRuntimeStoreSlugSchema,
+      })
+      .strict(),
+    environment: z
+      .object({
+        name: z.literal('production'),
+        status: z.literal('ready'),
+      })
+      .strict(),
+    publication: z
+      .object({
+        sequence: z.number().int().nonnegative(),
+        releaseSequence: z.number().int().nonnegative(),
+        publishedAt: z.string().datetime({ offset: true }),
+      })
+      .strict(),
+    definition: StorefrontDefinitionSchema,
+  })
+  .strict()
+
+export type ActiveStorefrontRuntime = z.infer<
+  typeof ActiveStorefrontRuntimeSchema
+>
+
+export type CloudRuntimeFetch = (
+  input: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<Response>
+
+export interface CloudRuntimeClientOptions {
+  baseUrl: string
+  timeoutMs?: number
+  cacheTtlMs?: number
+  fetch?: CloudRuntimeFetch
+  now?: () => number
+}
+
+interface RuntimeCacheEntry {
+  value: ActiveStorefrontRuntime | null
+  etag?: string
+  expiresAt: number
+}
+
+export class CloudRuntimeResponseError extends Error {
+  readonly status: number
+
+  constructor(status: number) {
+    super(`Cloud runtime respondió HTTP ${status}`)
+    this.name = 'CloudRuntimeResponseError'
+    this.status = status
+  }
+}
+
+const DEFAULT_TIMEOUT_MS = 3_000
+const DEFAULT_CACHE_TTL_MS = 15_000
+const MAX_CACHE_ENTRIES = 100
+
+export class CloudRuntimeClient {
+  readonly baseUrl: string
+  readonly timeoutMs: number
+  readonly cacheTtlMs: number
+
+  private readonly fetchRuntime: CloudRuntimeFetch
+  private readonly now: () => number
+  private readonly cache = new Map<string, RuntimeCacheEntry>()
+  private readonly inFlight = new Map<
+    string,
+    Promise<ActiveStorefrontRuntime | null>
+  >()
+
+  constructor(options: CloudRuntimeClientOptions) {
+    this.baseUrl = new URL(options.baseUrl).toString().replace(/\/$/, '')
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+    this.cacheTtlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS
+    this.fetchRuntime = options.fetch ?? globalThis.fetch
+    this.now = options.now ?? Date.now
+  }
+
+  async resolveActiveStorefront(
+    storeSlugInput: string,
+  ): Promise<ActiveStorefrontRuntime | null> {
+    const storeSlug = CloudRuntimeStoreSlugSchema.parse(storeSlugInput)
+    const cached = this.cache.get(storeSlug)
+    if (cached && cached.expiresAt > this.now()) {
+      return cached.value
+    }
+
+    const activeRequest = this.inFlight.get(storeSlug)
+    if (activeRequest) return activeRequest
+
+    const request = this.requestActiveStorefront(storeSlug, cached).finally(
+      () => {
+        this.inFlight.delete(storeSlug)
+      },
+    )
+    this.inFlight.set(storeSlug, request)
+    return request
+  }
+
+  clearCache(): void {
+    this.cache.clear()
+    this.inFlight.clear()
+  }
+
+  private setCache(storeSlug: string, entry: RuntimeCacheEntry): void {
+    if (!this.cache.has(storeSlug) && this.cache.size >= MAX_CACHE_ENTRIES) {
+      const oldestKey = this.cache.keys().next().value
+      if (oldestKey !== undefined) this.cache.delete(oldestKey)
+    }
+    this.cache.set(storeSlug, entry)
+  }
+
+  private async requestActiveStorefront(
+    storeSlug: string,
+    cached?: RuntimeCacheEntry,
+  ): Promise<ActiveStorefrontRuntime | null> {
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs)
+    const headers = new Headers({ accept: 'application/json' })
+    if (cached?.etag) headers.set('if-none-match', cached.etag)
+
+    try {
+      const response = await this.fetchRuntime(
+        new URL(
+          `/v1/runtime/storefronts/${encodeURIComponent(storeSlug)}`,
+          this.baseUrl,
+        ),
+        {
+          method: 'GET',
+          headers,
+          signal: controller.signal,
+        },
+      )
+
+      if (response.status === 304) {
+        if (!cached) throw new CloudRuntimeResponseError(304)
+        this.setCache(storeSlug, {
+          ...cached,
+          expiresAt: this.now() + this.cacheTtlMs,
+        })
+        return cached.value
+      }
+
+      if (response.status === 404) {
+        this.setCache(storeSlug, {
+          value: null,
+          etag: response.headers.get('etag') ?? undefined,
+          expiresAt: this.now() + this.cacheTtlMs,
+        })
+        return null
+      }
+
+      if (!response.ok) {
+        throw new CloudRuntimeResponseError(response.status)
+      }
+
+      const runtime = ActiveStorefrontRuntimeSchema.parse(
+        await response.json(),
+      )
+      if (runtime.store.slug !== storeSlug) {
+        throw new Error(
+          `Cloud runtime devolvió el store slug ${runtime.store.slug} para ${storeSlug}`,
+        )
+      }
+
+      this.setCache(storeSlug, {
+        value: runtime,
+        etag: response.headers.get('etag') ?? undefined,
+        expiresAt: this.now() + this.cacheTtlMs,
+      })
+      return runtime
+    } finally {
+      clearTimeout(timeout)
+    }
+  }
+}
+
+const sharedClients = new Map<string, CloudRuntimeClient>()
+
+export function getCloudRuntimeClient(
+  options: Omit<CloudRuntimeClientOptions, 'fetch' | 'now'>,
+): CloudRuntimeClient {
+  const key = [
+    new URL(options.baseUrl).toString(),
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS,
+  ].join('|')
+  const current = sharedClients.get(key)
+  if (current) return current
+
+  const client = new CloudRuntimeClient(options)
+  if (sharedClients.size >= 8) {
+    const oldestKey = sharedClients.keys().next().value
+    if (oldestKey !== undefined) sharedClients.delete(oldestKey)
+  }
+  sharedClients.set(key, client)
+  return client
+}
+
+export function resetCloudRuntimeClients(): void {
+  for (const client of sharedClients.values()) client.clearCache()
+  sharedClients.clear()
+}

package/src/codegen.mjs

@@ -152,7 +152,7 @@ export async function generateApp({ cwd, appDir, frameworkRoot, config }) {
   }
   if (config.theme !== undefined) publicConfig.theme = config.theme
 
-  for (const serverOnlyKey of ['api', 'dev', 'deploy', 'env']) {
+  for (const serverOnlyKey of ['api', 'cloud', 'dev', 'deploy', 'env']) {
     if (Object.hasOwn(publicConfig, serverOnlyKey)) {
       throw new Error(`La clave server-only \`${serverOnlyKey}\` no puede serializarse en app-config.ts`)
     }
@@ -179,7 +179,16 @@ export async function generateApp({ cwd, appDir, frameworkRoot, config }) {
       `    if (import.meta.env.DEV && config.dev?.apiBaseUrl) {\n` +
       `      api = { ...api, baseUrl: config.dev.apiBaseUrl }\n` +
       `    }\n` +
-      `    registerServerConfig({ domain: config.domain, api })\n` +
+      `    let cloud = config.cloud\n` +
+      `    if (import.meta.env.DEV && !cloud?.baseUrl) {\n` +
+      `      cloud = {\n` +
+      `        timeoutMs: cloud?.timeoutMs ?? 3_000,\n` +
+      `        cacheTtlMs: cloud?.cacheTtlMs ?? 15_000,\n` +
+      `        ...cloud,\n` +
+      `        baseUrl: 'http://127.0.0.1:8020',\n` +
+      `      }\n` +
+      `    }\n` +
+      `    registerServerConfig({ domain: config.domain, api, cloud })\n` +
       `    const health = await handleEcomiqHealth(request)\n` +
       `    if (health) return health\n` +
       `    return startServer.fetch(request, ...rest)\n` +

package/src/components/checkout/format.ts

@@ -1,13 +1,6 @@
 import type { CartCheckoutResponse } from '@ecomiq/core'
 
-export function formatMoney(value: number, language: string, currency: string) {
-  return new Intl.NumberFormat(language, {
-    style: 'currency',
-    currency,
-    minimumFractionDigits: 2,
-    maximumFractionDigits: 2,
-  }).format(value)
-}
+export { formatMoney } from '../../format-money'
 
 export function thankYouUrl(cartId: string, transactionId?: string) {
   const q = new URLSearchParams({ cartId })

package/src/config.d.ts

@@ -7,6 +7,22 @@ export interface EcomiqApiConfig {
   timeoutMs?: number
 }
 
+export interface EcomiqCloudConfig {
+  /**
+   * URL privada del plano de control. En producción debe configurarse de forma
+   * explícita; durante `ecomiq dev` el runtime usa http://127.0.0.1:8020.
+   */
+  baseUrl?: string
+  /**
+   * Slug canónico en Cloud. Si se omite, se deriva del primer label de
+   * `domain`.
+   */
+  storeSlug?: string
+  timeoutMs?: number
+  /** TTL del cache de la publicación activa. Default: 15 segundos. */
+  cacheTtlMs?: number
+}
+
 export type EcomiqCloudflareRoute =
   | string
   | {
@@ -33,6 +49,8 @@ export interface EcomiqConfigInput {
    */
   domain: string
   api?: EcomiqApiConfig
+  /** Configuración server-only para resolver la publicación activa. */
+  cloud?: EcomiqCloudConfig
   theme?: EcomiqThemeConfig
   dev?: {
     port?: number
@@ -52,13 +70,20 @@ export interface EcomiqConfigInput {
   env?: Record<string, string>
 }
 
-export interface ResolvedEcomiqConfig extends Omit<EcomiqConfigInput, 'api'> {
+export interface ResolvedEcomiqConfig
+  extends Omit<EcomiqConfigInput, 'api' | 'cloud'> {
   api: {
     baseUrl: string
     version: string
     headers?: Record<string, string>
     timeoutMs: number
   }
+  cloud?: {
+    baseUrl?: string
+    storeSlug?: string
+    timeoutMs: number
+    cacheTtlMs: number
+  }
 }
 
 export function parseConfig(

package/src/config.mjs

@@ -3,7 +3,7 @@
  * Se valida con Zod al arrancar la CLI para dar errores claros.
  *
  * Identidad de tienda, SEO, analytics y menús salen de `/v1/settings`.
- * Aquí solo queda lo operativo: domain, api, theme, dev, deploy, env.
+ * Aquí solo queda lo operativo: domain, api, cloud, theme, dev, deploy, env.
  */
 import { z } from 'zod'
 
@@ -50,6 +50,25 @@ const configSchema = z.object({
       timeoutMs: z.number().int().positive().default(10_000),
     })
     .default({}),
+  /**
+   * Plano de control server-only. `baseUrl` se exige operativamente en
+   * producción; si falta, el storefront degrada a la home clásica.
+   */
+  cloud: z
+    .object({
+      baseUrl: z.string().url().optional(),
+      storeSlug: z
+        .string()
+        .trim()
+        .min(2)
+        .max(100)
+        .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
+        .optional(),
+      timeoutMs: z.number().int().positive().default(3_000),
+      cacheTtlMs: z.number().int().min(0).max(300_000).default(15_000),
+    })
+    .strict()
+    .optional(),
   /** Tokens de tema; sobreescriben las variables CSS del design system. */
   theme: z
     .object({

package/src/format-money.ts

@@ -0,0 +1,31 @@
+export type MoneyLocale = {
+  language: string
+  currency: string
+}
+
+/**
+ * Formatea un monto con `Intl.NumberFormat` (moneda ISO-4217).
+ *
+ * @example
+ * formatMoney(19.9, { language: 'es-PE', currency: 'PEN' })
+ * formatMoney(19.9, 'es-PE', 'PEN')
+ */
+export function formatMoney(value: number, locale: MoneyLocale): string
+export function formatMoney(value: number, language: string, currency: string): string
+export function formatMoney(
+  value: number,
+  languageOrLocale: string | MoneyLocale,
+  currency?: string,
+): string {
+  const language =
+    typeof languageOrLocale === 'string' ? languageOrLocale : languageOrLocale.language
+  const currencyCode =
+    typeof languageOrLocale === 'string' ? currency! : languageOrLocale.currency
+
+  return new Intl.NumberFormat(language, {
+    style: 'currency',
+    currency: currencyCode,
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  }).format(value)
+}

package/src/index.ts

@@ -239,9 +239,20 @@ export { ecomiqOAuthPasswordClient } from './auth/ecomiq-oauth-password-client'
 export { signInWithEcomiqCredentials } from './auth/ecomiq-storefront-sign-in'
 export type { EcomiqSignInCredentials } from './auth/ecomiq-storefront-sign-in'
 export * from './utils'
+export { formatMoney, type MoneyLocale } from './format-money'
 export { Link } from './link'
 export { Await } from '@tanstack/react-router'
-export { Hero, findHeroSection, type HeroProps, type HeroSlide } from './components/hero'
+export {
+  Hero,
+  findHeroSection,
+  type HeroProps,
+  type HeroSlide,
+} from './components/hero'
+export * from './storefront-definition'
+export {
+  definitionForRoute,
+  useDefinition,
+} from './storefront-layout'
 export { z } from 'zod'
 
 /**

package/src/server-config-store.ts

@@ -1,9 +1,17 @@
 import type { CreateApiOptions } from '@ecomiq/core'
 import { createServerOnlyFn } from '@tanstack/react-start'
 
+export interface ServerEcomiqCloudConfig {
+  baseUrl?: string
+  storeSlug?: string
+  timeoutMs?: number
+  cacheTtlMs?: number
+}
+
 export interface ServerEcomiqConfig {
   domain: string
   api?: CreateApiOptions
+  cloud?: ServerEcomiqCloudConfig
 }
 
 const serverConfigKey = Symbol.for('@ecomiq/storefront/server-config')

package/src/server.ts

@@ -71,11 +71,16 @@ import {
   type AddProductToCartInput,
 } from './cart-session'
 import { submitProductReview } from './review-submission'
+import { loadActiveStorefrontHome } from './storefront-runtime'
 
 const getSettingsFn = createServerFn({ method: 'GET' }).handler(() =>
   getStorefrontClient().getSettings(),
 )
 
+const getActiveStorefrontHomeFn = createServerFn({ method: 'GET' }).handler(
+  () => loadActiveStorefrontHome(),
+)
+
 const getStoreIdFn = createServerFn({ method: 'GET' }).handler(() =>
   getStorefrontClient().getStoreId(),
 )
@@ -222,6 +227,7 @@ const getDistrictsFn = createServerFn({ method: 'GET' })
  */
 export const serverApi = {
   getSettings: () => getSettingsFn(),
+  getActiveStorefrontHome: () => getActiveStorefrontHomeFn(),
   getStoreId: () => getStoreIdFn(),
   getCollections: () => getCollectionsFn(),
   getCollectionBySlug: (slug: string) => getCollectionBySlugFn({ data: { slug } }),

package/src/storefront-definition/contract.ts

@@ -0,0 +1 @@
+export * from '@ecomiq/storefront-definition'

package/src/storefront-definition/index.ts

@@ -0,0 +1,2 @@
+export * from './contract'
+export * from './renderer'