@bacano/sdk 1.0.0 → 1.1.0

package/STOREFRONT_PERFORMANCE.md

@@ -0,0 +1,265 @@
+# Storefront performance contract
+
+This is the canonical performance contract for storefronts built with
+`@bacano/sdk`. It applies to static, hybrid and server-rendered storefronts.
+
+## Required architecture
+
+1. Create one `BacanoClient` and mount one `BacanoProvider` at the application
+   root. Do not create independent clients per component or route.
+2. Generate catalog routes and their page data from one build snapshot. Never
+   call `getProductBySlug()` once for every product during the same build.
+3. Render useful catalog and product HTML during the static/server render.
+   Loading skeletons are fallbacks, not the initial production document.
+4. Use the SDK for every Bacano request. Storefronts must not duplicate GraphQL
+   documents, gateway limits, retries or storage transform rules.
+5. Keep build data separate from volatile state. Prices and availability may be
+   refreshed after hydration with the lightweight live-state contract.
+6. A live refresh must preserve the static content when it fails. A public page
+   must not become empty because Bacano is temporarily unavailable.
+
+## Static catalog bootstrap
+
+Use one bootstrap per website build:
+
+```ts
+const bootstrap = await client.catalog.getStaticCatalogBootstrap({
+  categoryListKey: "categorias-web",
+  attributeListKey: "atributos",
+  pageSize: 100,
+  initialPageSize: 24,
+  maxProducts: 10_000,
+  sortBy: "name_asc",
+});
+
+// Render this in the initial catalog HTML.
+const initialCatalogPage = bootstrap.initialPage;
+
+// Reuse the same objects for routes, metadata, JSON-LD and sitemap.
+const productByRoute = new Map(
+  bootstrap.products.map((product) => [product.slug || product.id, product]),
+);
+```
+
+The SDK paginates internally, respects `Retry-After`, rejects inconsistent
+snapshots and avoids repeating facets on every page. Builds must fail clearly
+if this contract fails; they must not silently publish an empty catalog.
+
+### Listing variants and detail variants
+
+The static bootstrap deliberately exposes two projections on each product:
+
+- `product.variants` contains only variants that were saleable when Bacano
+  generated the catalog page. Cards, price ranges, filters and listing
+  visibility must use this projection.
+- `product.detailVariants` also contains enabled, published variants with a
+  public price that are currently sold out. Product detail selectors must use
+  this projection so a customer can see unavailable sizes instead of assuming
+  they do not exist.
+
+Use the public helper so cached snapshots from older SDK versions remain safe:
+
+```ts
+import { getProductDetailVariants } from "@bacano/sdk";
+
+const detailVariants = getProductDetailVariants(product);
+const liveState = await client.catalog.getProductLiveState(
+  detailVariants.map((variant) => variant.id),
+);
+```
+
+`getProduct()` and `getProductBySlug()` expose the complete detail projection
+through `variants` as well. A sold-out variant returns `inStock: false` and
+`maxPurchasableQuantity: 0` from live state. Never use `detailVariants` to
+calculate a card's minimum price or to make a completely sold-out product
+appear in listings.
+
+## Live price and availability
+
+After hydration, refresh only the variants visible on screen:
+
+```ts
+const liveState = await client.catalog.getProductLiveState(visibleVariantIds);
+```
+
+One call accepts at most 100 unique variant IDs. Debounce filter/pagination
+changes and do not refresh the whole static catalog. The response only contains
+variant ID, current pricing, availability and `maxPurchasableQuantity`.
+
+For a local cart, batch all distinct variant IDs when the cart opens and use
+`maxPurchasableQuantity` as the total cap per variant, including units already
+in the cart. Disable quantity increases at the cap and explain that the maximum
+available was reached. Do not poll after every click or persist the limit as
+catalog data: another checkout may consume stock, and Bacano remains
+authoritative when checkout starts and finishes.
+
+## Responsive media
+
+Every SDK product/content media object can expose `responsiveSources`. Use it
+with a realistic `sizes` value so mobile devices do not download desktop media:
+
+```tsx
+import { formatMediaSrcSet } from "@bacano/sdk";
+
+<img
+  src={media.cardUrl || media.url}
+  srcSet={formatMediaSrcSet(media.responsiveSources ?? []) || undefined}
+  sizes="(max-width: 640px) 50vw, (max-width: 1200px) 33vw, 320px"
+  width={320}
+  height={400}
+  loading="lazy"
+  decoding="async"
+  alt={media.altText || product.name}
+/>;
+```
+
+The first visible product image may use eager loading/high priority. Images
+below the fold and recommendation blocks must remain lazy. Storefronts must not
+append storage transformation query parameters manually.
+
+### Banners and full-width heroes
+
+Editorial `ContentMedia` images additionally expose:
+
+```ts
+type ContentMedia = {
+  src?: string | null;
+  url?: string | null;
+  originalUrl?: string | null;
+  thumbnailUrl?: string | null;
+  cardUrl?: string | null;
+  detailUrl?: string | null;
+  heroUrl?: string | null;
+  responsiveSources?: Array<{ width: number; url: string }>;
+  originalWidth?: number | null;
+  originalHeight?: number | null;
+};
+```
+
+`src` and `url` remain available as compatibility aliases. New storefront code
+must select the semantic URL that matches its rendering context.
+
+`heroUrl` is an optimized WebP fallback for wide editorial media. Bacano uses
+the candidates `640`, `960`, `1400`, `1920` and `2560`, but removes every size
+larger than the original file and adds the exact intrinsic width as the final
+candidate. A 1920 px source therefore ends at 1920 px; a 1180 px source ends at
+1180 px. When Bacano cannot determine the dimensions, `heroUrl` safely falls
+back to `originalUrl` and no speculative `srcset` is emitted.
+
+For separate mobile and desktop artwork, keep the breakpoint in the storefront
+and let the browser choose density within each source:
+
+```tsx
+import { formatMediaSrcSet, type ContentMedia } from "@bacano/sdk";
+
+export function EditorialHero({
+  desktop,
+  mobile,
+}: {
+  desktop: ContentMedia;
+  mobile: ContentMedia;
+}) {
+  return (
+    <picture>
+      <source
+        media="(max-width: 767px)"
+        srcSet={formatMediaSrcSet(mobile.responsiveSources ?? []) || undefined}
+        sizes="100vw"
+      />
+      <img
+        src={desktop.heroUrl ?? desktop.originalUrl ?? ""}
+        srcSet={formatMediaSrcSet(desktop.responsiveSources ?? []) || undefined}
+        sizes="100vw"
+        width={desktop.originalWidth ?? undefined}
+        height={desktop.originalHeight ?? undefined}
+        alt={desktop.alt ?? ""}
+        decoding="async"
+      />
+    </picture>
+  );
+}
+```
+
+This contract works in static exports: all URLs are deterministic, cacheable
+gateway URLs and the browser selects the appropriate candidate at runtime for
+device-pixel ratios 1 and 2. Do not use `detailUrl` as the fallback for a
+full-width hero and do not append `w`, `q` or `f` parameters in a storefront.
+
+## Request ownership
+
+- Website initialization: obtain one public configuration and use it to seed the
+  SDK context. Do not resolve the same website again through GraphQL.
+- Catalog build: one paginated bootstrap.
+- Initial catalog navigation: zero mandatory catalog requests after hydration;
+  the static page is already usable.
+- Live state: one batched request for visible variants.
+- Recommendations: load independently and lazily; they must not delay product
+  title, price, selected variant or primary media.
+- Shipping policy and public configuration: read once in the root data layer and
+  share the result.
+
+### Shared website bootstrap
+
+The public configuration is the canonical bootstrap shared by buyer accounts,
+marketing and the SDK client. A static or server-rendered storefront should
+fetch it once, cache it for the build/render window and pass its context into
+the root provider:
+
+```tsx
+import {
+  getWebsiteContextFromPublicConfig,
+  getWebsitePublicConfig,
+} from "@bacano/sdk";
+import { BacanoMarketingProvider, BacanoProvider } from "@bacano/sdk/react";
+
+const publicConfig = await getWebsitePublicConfig({
+  apiUrl,
+  websiteSlug,
+  origin: canonicalOrigin,
+});
+
+<BacanoProvider
+  config={{
+    apiUrl,
+    websiteSlug,
+    initialContext: getWebsiteContextFromPublicConfig(publicConfig),
+  }}
+>
+  <BacanoMarketingProvider
+    publicConfig={publicConfig}
+    scriptLoadStrategy="idle"
+  >
+    {children}
+  </BacanoMarketingProvider>
+</BacanoProvider>;
+```
+
+`scriptLoadStrategy="idle"` prepares the GA4, Meta, and Clarity command queues
+immediately, so events are not lost, but postpones downloading their vendor
+scripts until browser idle time or the first interaction. The default remains
+`"immediate"` for backward compatibility.
+
+If the storefront refreshes public configuration in the browser, it must keep
+the static bootstrap while the refresh is pending and only replace it when the
+payload actually changes. Configuration failure must not blank the storefront.
+
+Mount third-party authentication only on routes that require it, such as
+checkout, sign-in and customer account pages. Public catalog and product pages
+must not download an authentication runtime merely because buyer accounts are
+enabled for the website.
+
+## Acceptance checklist for storefront agents
+
+- [ ] View source contains real product cards/details, not only skeletons.
+- [ ] Routes, sitemap, metadata and JSON-LD reuse the same build bootstrap.
+- [ ] No direct GraphQL and no per-product build fetch loop.
+- [ ] One `BacanoProvider` and no duplicated website/config requests.
+- [ ] The provider receives `initialContext` from the shared public config.
+- [ ] Marketing commands queue before scripts and idle loading loses no events.
+- [ ] Authentication vendor scripts are absent from public catalog routes.
+- [ ] `srcset` and `sizes` are present on catalog and product media.
+- [ ] Live refresh is batched, debounced and failure-safe.
+- [ ] Recommendations and below-fold media do not block the primary content.
+- [ ] Mobile and desktop Lighthouse runs show no material layout shift.
+- [ ] A production trace confirms no duplicated catalog, shipping or website
+      bootstrap calls during the first navigation.