@bacano/sdk 1.0.1 → 1.1.8

package/STOREFRONT_PREVIEW.md

@@ -0,0 +1,499 @@
+# Bacano Storefront Content Preview
+
+Official guide for `@bacano/sdk/react/preview`, available since SDK `1.0.5`.
+
+## Problem solved
+
+Static storefronts should keep their public catalog and editorial pages frozen
+at build time for SEO, speed, reliability, and predictable hosting costs. That
+also means a published Content change is not visible on the public page until
+the storefront is rebuilt and deployed.
+
+The preview entrypoint provides a separate client-side route that reads the
+current **published** Bacano Content on demand and renders it with the
+storefront's own production components:
+
+```text
+Public route:   Bacano Content -> Next build -> static HTML
+Preview route:  Browser -> @bacano/sdk -> current published Content
+```
+
+Preview V1 is not a draft bypass and is not a realtime subscription. An editor
+publishes the entry and then opens or refreshes the preview without rebuilding
+the storefront.
+
+## Architectural contract
+
+### Bacano SDK owns
+
+- Loading, ready, and safe error states.
+- Per-route in-memory cache and simultaneous-request deduplication.
+- Protection against stale responses after navigation or unmount.
+- Forced refresh.
+- Expanded state and four toolbar positions.
+- `sessionStorage` persistence isolated by website slug.
+- The official responsive and accessible toolbar.
+- Neutral route normalization and internal-link interception.
+- A preview-mode signal.
+- A marketing no-op boundary inside the preview tree.
+- SSR-safe module evaluation.
+
+### The storefront owns
+
+- The single preview route, for example `/vista-previa/`.
+- The route map and routes that are safe to preview.
+- The loader that combines Content keys for each route.
+- Mapping Bacano Content to storefront view models.
+- Rendering with the same visual components used by production.
+- Translating preview navigation to its router or query-string convention.
+- `noindex` metadata and sitemap exclusion.
+- Hiding or disabling popups, automatic chat, capture banners, cart drawers,
+  checkout links, and other non-editorial features outside the preview tree.
+
+The SDK does not know whether `/` needs one Content key or six, and it does not
+render Home, About, Blog, Product, Catalog, or Checkout pages.
+
+## Packaging
+
+Import preview only from its dedicated entrypoint:
+
+```tsx
+import {
+  BacanoPreviewShell,
+  interceptPreviewLink,
+  type PreviewRouteLoader,
+} from "@bacano/sdk/react/preview";
+```
+
+It is a separate ESM/CJS entrypoint and is not re-exported by
+`@bacano/sdk/react`. It has no Next.js or Tailwind dependency. The official
+toolbar carries self-contained styles and does not require a stylesheet import.
+Both React entrypoints share the same Bacano client and marketing contexts, so
+preview must remain under the storefront's single `BacanoProvider`.
+
+React `>=18` remains the only peer dependency.
+
+## Required provider hierarchy
+
+Mount exactly one `BacanoProvider` for the storefront, independently of whether
+buyer accounts are enabled:
+
+```tsx
+import { BacanoProvider } from "@bacano/sdk/react";
+
+export function StorefrontProviders({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <BacanoProvider
+      config={{
+        apiUrl: process.env.NEXT_PUBLIC_BACANO_API_URL!,
+        websiteSlug: process.env.NEXT_PUBLIC_BACANO_WEBSITE_SLUG!,
+      }}
+    >
+      {children}
+    </BacanoProvider>
+  );
+}
+```
+
+`BacanoPreviewProvider` consumes this existing client. Do not create another
+client inside the preview loader and do not mount a second `BacanoProvider`.
+
+If Clerk supplies buyer tokens, keep its token callback in this same provider.
+The presence or absence of Clerk must not determine whether the public Bacano
+client exists.
+
+## Public API
+
+### `BacanoPreviewProvider<TDocument>`
+
+Required props:
+
+| Prop          | Purpose                                                 |
+| ------------- | ------------------------------------------------------- |
+| `websiteSlug` | Isolates persisted toolbar state between stores.        |
+| `route`       | Current controlled storefront route.                    |
+| `loadRoute`   | Storefront loader receiving `{ route, force, client }`. |
+| `navigate`    | Updates the preview URL using the storefront router.    |
+
+Optional props:
+
+| Prop                 | Default                 | Purpose                                      |
+| -------------------- | ----------------------- | -------------------------------------------- |
+| `normalizeRoute`     | `normalizePreviewRoute` | Canonicalizes route input.                   |
+| `isPreviewableRoute` | all normalized routes   | Rejects private or transactional routes.     |
+| `initialExpanded`    | `true`                  | Initial toolbar visibility before hydration. |
+| `initialPosition`    | `top-right`             | Initial toolbar corner.                      |
+| `cacheMaxEntries`    | `50`                    | Maximum cached route documents per provider. |
+
+Loader contract:
+
+```ts
+type PreviewRouteLoader<TDocument> = (context: {
+  route: string;
+  force: boolean;
+  client: BacanoClient;
+}) => Promise<TDocument>;
+```
+
+A `null` or `undefined` result becomes the safe `EMPTY_DOCUMENT` state. Loader
+errors are not exposed verbatim in the public UI.
+
+### `useBacanoPreview<TDocument>()`
+
+Returns:
+
+```ts
+{
+  isPreview: true;
+  websiteSlug: string;
+  route: string;
+  status: "idle" | "loading" | "ready" | "error";
+  document: TDocument | null;
+  error: { code: string; message: string } | null;
+  refreshedAt: Date | null;
+  isExpanded: boolean;
+  position: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+  refresh(): Promise<void>;
+  navigate(route: string): void;
+  setExpanded(expanded: boolean): void;
+  setPosition(position): void;
+}
+```
+
+### `BacanoPreviewToolbar`
+
+The optional tokens are deliberately limited:
+
+```tsx
+<BacanoPreviewToolbar
+  websiteName="My store"
+  logo={<img src="/logo.svg" alt="" />}
+  primaryColor="#172033"
+  accentColor="#2f80ed"
+  backgroundColor="#ffffff"
+  locale="es-CO"
+  zIndex={2147483000}
+  suggestedRoutes={["/", "/about", "/blog"]}
+/>
+```
+
+The toolbar provides route input, refresh, collapse/expand, last refresh time,
+safe status messages, keyboard focus, `aria-live`, responsive layout, reduced
+motion support, and four positions.
+
+### `BacanoPreviewShell<TDocument>`
+
+Convenience composition of the provider and toolbar:
+
+```tsx
+<BacanoPreviewShell {...providerProps} toolbar={toolbarProps}>
+  {(preview) => renderPreviewState(preview)}
+</BacanoPreviewShell>
+```
+
+Pass `toolbar={false}` only when the storefront supplies another accessible
+control surface.
+
+## Minimal Next.js static-export example
+
+The SDK contains no Next.js imports. This adapter belongs to the storefront.
+
+```tsx
+// app/vista-previa/page.tsx
+import type { Metadata } from "next";
+import { Suspense } from "react";
+import { PreviewClient } from "./PreviewClient";
+
+export const metadata: Metadata = {
+  title: "Vista previa del sitio",
+  robots: { index: false, follow: false },
+};
+
+export default function PreviewPage() {
+  return (
+    <Suspense fallback={<p>Cargando vista previa...</p>}>
+      <PreviewClient />
+    </Suspense>
+  );
+}
+```
+
+```tsx
+// app/vista-previa/PreviewClient.tsx
+"use client";
+
+import { useSearchParams } from "next/navigation";
+import {
+  BacanoPreviewShell,
+  interceptPreviewLink,
+  normalizePreviewRoute,
+  type PreviewRouteLoader,
+} from "@bacano/sdk/react/preview";
+
+type PreviewDocument =
+  | { kind: "home"; hero: unknown; story: unknown }
+  | { kind: "about"; content: unknown }
+  | { kind: "unsupported"; route: string };
+
+const previewable = new Set(["/", "/about"]);
+
+const loadRoute: PreviewRouteLoader<PreviewDocument> = async ({
+  route,
+  client,
+}) => {
+  if (route === "/") {
+    const [hero, story] = await Promise.all([
+      client.content.getByKey("home-hero"),
+      client.content.getByKey("home-story"),
+    ]);
+    return { kind: "home", hero, story };
+  }
+
+  if (route === "/about") {
+    return {
+      kind: "about",
+      content: await client.content.getByKey("about"),
+    };
+  }
+
+  return { kind: "unsupported", route };
+};
+
+export function PreviewClient() {
+  const searchParams = useSearchParams();
+  const route = normalizePreviewRoute(searchParams.get("route"));
+
+  return (
+    <BacanoPreviewShell
+      websiteSlug={process.env.NEXT_PUBLIC_BACANO_WEBSITE_SLUG!}
+      route={route}
+      loadRoute={loadRoute}
+      isPreviewableRoute={(nextRoute) => previewable.has(nextRoute)}
+      navigate={(nextRoute) => {
+        window.location.assign(
+          `/vista-previa/?route=${encodeURIComponent(nextRoute)}`,
+        );
+      }}
+      toolbar={{
+        websiteName: "My store",
+        suggestedRoutes: Array.from(previewable),
+      }}
+    >
+      {(preview) => {
+        if (preview.status === "loading" && !preview.document) {
+          return <PreviewSkeleton />;
+        }
+        if (preview.status === "error" && !preview.document) {
+          return <PreviewError onRetry={preview.refresh} />;
+        }
+        if (!preview.document) return null;
+
+        return (
+          <div
+            onClickCapture={(event) =>
+              interceptPreviewLink(event, {
+                navigate: preview.navigate,
+                isPreviewableRoute: (nextRoute) => previewable.has(nextRoute),
+              })
+            }
+          >
+            <ProductionRenderer document={preview.document} />
+          </div>
+        );
+      }}
+    </BacanoPreviewShell>
+  );
+}
+```
+
+The example intentionally leaves `PreviewSkeleton`, `PreviewError`, and
+`ProductionRenderer` to the storefront so the page retains its visual language.
+
+## Route map guidance
+
+Keep a finite allowlist. Typical V1 routes include:
+
+- Home.
+- About and other editorial pages.
+- Blog index and published articles.
+- Content-driven catalog landing pages.
+- Published legal pages.
+
+Do not preview in V1:
+
+- Checkout or payment response.
+- Account creation, login, or private account pages.
+- Private orders.
+- Gateway sessions.
+- Any route whose primary purpose is transactional.
+
+Product pages can be added later if the storefront defines an explicit loader
+and non-transactional renderer. The SDK does not enable them automatically.
+
+## Internal-link interception
+
+`interceptPreviewLink()` only captures plain primary clicks on same-origin
+links. It preserves:
+
+- Ctrl/Cmd click.
+- Shift and Alt click.
+- External origins.
+- `target="_blank"`.
+- `download` links.
+- Routes rejected by `isPreviewableRoute`.
+
+The callback receives the normalized public route. The storefront decides how
+to encode it into `/vista-previa/?route=...`.
+
+## Marketing and commercial UI isolation
+
+`BacanoPreviewProvider` overrides `useMarketing()` with a synchronous no-op in
+its subtree. This prevents GA4, Meta, and Clarity browser events from preview renderers,
+even if the root storefront marketing runtime is active.
+
+`useBacanoPreviewMode()` is also available to components placed inside the
+preview boundary:
+
+```tsx
+const isPreview = useBacanoPreviewMode();
+if (isPreview) return null;
+return <CommercialPopup />;
+```
+
+Components rendered above or beside the preview provider cannot read a child
+context. The storefront must therefore hide or disable root-level commercial
+elements on its preview route, including:
+
+- Marketing popups and lead banners.
+- Automatic chat and WhatsApp launchers.
+- Cart drawers and checkout calls to action.
+- Independently mounted analytics providers.
+
+When `BacanoMarketingProvider` is nested inside a preview-mode boundary, it also
+recognizes the signal and remains a no-op.
+
+Server-side conversion events remain protected by keeping all transactional
+routes and actions outside preview. A browser preview flag is not an
+authorization mechanism and must never be sent to bypass commercial rules.
+
+## Security and privacy
+
+V1 calls only the existing public Content methods:
+
+- `client.content.getByKey()`
+- `client.content.getByCategory()`
+- `client.content.getByTag()`
+
+Those contracts return current published content. There is no `includeDrafts`,
+GraphQL bypass, alternate endpoint, admin secret, or permission change.
+
+The route remains publicly reachable, so it must show only information that is
+already public. Keep `noindex`, exclude it from sitemap, and do not place tokens,
+customer data, payment data, or secret identifiers in the preview query string.
+
+A future draft preview requires a Bacano-signed session containing website,
+user, scopes, allowed routes, expiration, revocation, and audit information.
+Never implement drafts using `?includeDrafts=true`.
+
+## Static production guarantees
+
+When the storefront follows this contract:
+
+- Public pages keep their build-time Content snapshots.
+- `output: "export"` remains valid.
+- `generateStaticParams`, sitemap, and public metadata do not change.
+- The preview entrypoint is imported only by its one route.
+- Preview API errors affect only the preview route.
+- A temporary Bacano outage while someone uses preview does not alter the
+  already deployed public storefront.
+
+The build still depends on whatever Bacano data the public static pages request
+at build time. Preview does not change or replace that build contract.
+
+## Validated reference implementation: Baby Rex
+
+Baby Rex validated the official integration with `@bacano/sdk` `1.0.5` on
+2026-08-06. It uses one global `BacanoProvider`; `BacanoPreviewShell` consumes
+that initialized client and the loader receives `{ route, force, client }`.
+
+The validated static production build generated all `417/417` pages. TypeScript,
+lint, unit tests, E2E, preview navigation, cache, refresh, toolbar behavior, and
+the `idle -> loading -> ready` transition passed. No marketing event was emitted
+inside preview.
+
+The implementation removed these generic storefront responsibilities:
+
+- Local `PreviewToolbar.tsx`.
+- Local expanded/position/sessionStorage state.
+- Local loading/error/refreshed-at controller state.
+- Local request-promise cache and forced-refresh orchestration.
+- Generic internal-link interception.
+- Pathname-based marketing suppression inside preview renderers once the SDK
+  boundary covers them.
+
+Baby Rex retained these storefront-specific responsibilities:
+
+- `/vista-previa/page.tsx` and its `noindex` metadata.
+- Sitemap exclusion.
+- `PreviewDocument` union.
+- Route allowlist and suggested routes.
+- `loadPreviewDocument()` mappings for Home, About, Blog, legal pages, and
+  content-driven catalog sections.
+- `PreviewDocumentView` and all production renderers.
+- Storefront-specific skeleton, missing-content, and unsupported-route views.
+- The Next.js adapter that writes `?ruta={encodedRoute}`.
+
+Baby Rex is the implementation reference for integration shape, not a source to
+copy blindly. Other storefronts keep their own route maps, Content keys,
+mappers, and visual components.
+
+## Preview audit contract
+
+An audit must verify both the SDK lifecycle and the storefront result model.
+The SDK lifecycle is `idle`, `loading`, `ready` or `error`; `missing` and
+`unsupported` are storefront document/view outcomes and must not be presented
+as extra SDK statuses.
+
+At minimum, automate or capture evidence for:
+
+- a direct request to the single preview route returning `noindex, nofollow`;
+- the preview route being absent from every sitemap;
+- reuse of the global `BacanoProvider` and initialized `BacanoClient`;
+- a finite route allowlist that rejects account, checkout, payment and order
+  routes;
+- absence of GA4, Meta, Clarity and other effective marketing scripts, requests
+  and events on a direct preview load;
+- `idle -> loading -> ready`, safe error, missing and unsupported rendering;
+- cache reuse, forced refresh and internal navigation;
+- unchanged static HTML, route generation and sitemap for public pages.
+
+The final report must name the requests observed in preview and distinguish an
+unexecuted browser check from a passing zero-request assertion.
+
+## Short checklist for agents
+
+- [ ] Use `@bacano/sdk` `1.0.5` or newer.
+- [ ] Mount exactly one global `BacanoProvider`.
+- [ ] Place `BacanoPreviewShell` below that provider; never create a preview client.
+- [ ] Load only published Content through the `client` supplied to `loadRoute`.
+- [ ] Keep route allowlists, Content keys, mappers, and renderers in the storefront.
+- [ ] Keep preview `noindex`, outside the sitemap, and free of transactional routes.
+- [ ] Hide root-level commercial UI and verify zero marketing events in preview.
+- [ ] Test idle, loading, ready, safe error, refresh, cache, and navigation states.
+- [ ] Test storefront-specific missing and unsupported outcomes.
+- [ ] Capture a direct preview trace proving zero effective marketing traffic.
+- [ ] Verify static public pages and their build output remain unchanged.
+- [ ] Run typecheck, lint, unit tests, E2E, and the complete production build.
+
+## V1 limitations
+
+- Published Content only.
+- Manual refresh; no WebSocket, polling, or subscriptions.
+- In-memory document cache lasts for the mounted provider session.
+- Toolbar preferences use browser `sessionStorage`.
+- The storefront owns all route-specific loaders and renderers.
+- Transactional and private pages are intentionally excluded.

package/STOREFRONT_PRODUCT_SPECIFICATIONS.md

@@ -0,0 +1,127 @@
+# Fichas técnicas de producto en storefronts
+
+Este documento define el contrato público de `@bacano/sdk` para mostrar y
+filtrar la información técnica creada por cada comercio en Bacano Content.
+
+La capacidad es independiente de los atributos y variantes comerciales. Las
+variantes continúan siendo la fuente de combinaciones, SKU, precio e
+inventario; una ficha técnica no debe usarse para recrearlas ni modificarlas.
+
+## Lectura en detalle y builds estáticos
+
+`Product.specification` contiene la ficha técnica efectiva del producto o
+`null` cuando no existe una ficha pública con valores. Está disponible en:
+
+- `client.catalog.getProduct()`;
+- `client.catalog.getProductBySlug()`;
+- los productos de `client.catalog.getStaticCatalogBootstrap()`;
+- los productos devueltos por `client.catalog.getCatalogPage()`.
+
+Las tiendas estáticas deben consumir el valor que llega en el bootstrap. Un
+cambio público en la definición o los valores requiere **Publicar cambios** y
+un nuevo build del storefront. Stock, precios y descuentos conservan su flujo
+dinámico independiente.
+
+```tsx
+import type { ProductSpecification } from "@bacano/sdk";
+
+export function ProductTechnicalSpecification({
+  specification,
+}: {
+  specification: ProductSpecification | null;
+}) {
+  if (!specification) return null;
+
+  return (
+    <section aria-labelledby="technical-specification-title">
+      <h2 id="technical-specification-title">Información adicional</h2>
+      {specification.sections.map((section) => (
+        <div key={section.id ?? section.key}>
+          <h3>{section.title}</h3>
+          {section.description ? <p>{section.description}</p> : null}
+          <dl>
+            {section.fields.map((field) => (
+              <div key={field.id}>
+                <dt>{field.label}</dt>
+                <dd>{formatSpecificationValue(field.value)}</dd>
+              </div>
+            ))}
+          </dl>
+        </div>
+      ))}
+    </section>
+  );
+}
+
+function formatSpecificationValue(value: unknown): string {
+  if (typeof value === "boolean") return value ? "Sí" : "No";
+  if (typeof value === "string" || typeof value === "number") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map(formatSpecificationValue).join(", ");
+  }
+  if (value && typeof value === "object") {
+    if ("label" in value && typeof value.label === "string") {
+      return value.label;
+    }
+    if ("unit" in value && "value" in value) {
+      const measure = value as {
+        value: number;
+        unit: { symbol: string };
+      };
+      return `${measure.value} ${measure.unit.symbol}`;
+    }
+  }
+  return "";
+}
+```
+
+Los campos vacíos o internos ya son omitidos por Bacano. El storefront recibe
+la organización por secciones y puede reproducirla o aplicar su propio diseño.
+No debe consultar Hasura, interpretar el JSON editable ni reconstruir unidades
+u opciones por su cuenta.
+
+## Facetas técnicas
+
+Solicitar `filters: true` en `getCatalogPage()` devuelve
+`result.filters.technical`. Cada faceta expone un `fieldId` estable, tipo,
+rango, unidad, opciones y conteos relevantes para los productos públicos y
+vendibles del resultado.
+
+```ts
+const page = await client.catalog.getCatalogPage({
+  categoryListKey: "categorias",
+  attributeListKey: "atributos",
+  categorySlug: "vehiculos-electricos",
+  technicalByField: {
+    "FIELD_UUID_AUTONOMIA": { min: 40, max: 120 },
+    "FIELD_UUID_BATERIA": { optionIds: ["OPTION_UUID_LITIO"] },
+  },
+  include: { products: true, filters: true },
+});
+```
+
+Reglas del filtro:
+
+- los valores seleccionados dentro de una misma faceta se combinan con OR;
+- las facetas diferentes se combinan con AND;
+- número y medida aceptan `min` y `max`;
+- fecha acepta `dateFrom` y `dateTo`;
+- booleano acepta `booleanValues`;
+- lista simple o múltiple acepta `optionIds`;
+- el storefront solo debe enviar IDs publicados por `filters.technical`.
+
+Bacano rechaza como filtro cualquier campo interno, oculto o no marcado como
+filtrable aunque se intente enviar su UUID manualmente.
+
+## Reglas de integración
+
+- No crear GraphQL directo ni consultar el JSON flexible de Content.
+- No persistir una segunda copia de la ficha en el storefront.
+- No convertir fichas técnicas en atributos o variantes.
+- No inventar facetas para campos que Bacano no publica como filtrables.
+- Conservar el orden de secciones, campos y opciones entregado por el SDK.
+- Omitir por completo el bloque cuando `specification` sea `null`.
+- Validar el build estático con productos con y sin ficha antes de publicar.
+