@cartbase/storefront 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartbase/storefront",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Storefront SDK + UI component library for Cartbase stores: typed API client, checkout orchestration, cart drawer, product/catalog components, tracking. Source-shipped TypeScript — add it to transpilePackages.",
   "license": "MIT",
   "repository": {
@@ -56,6 +56,7 @@
     "./lib/hooks/use-intersection": "./src/lib/hooks/use-intersection.ts",
     "./lib/hooks/use-toggle-state": "./src/lib/hooks/use-toggle-state.ts",
     "./lib/cookie-names": "./src/lib/cookie-names.ts",
+    "./lib/media-image": "./src/lib/media-image.tsx",
     "./lib/platform": "./src/lib/platform.ts",
     "./lib/visitor": "./src/lib/visitor.ts",
     "./platform": "./src/platform/index.ts",

package/src/api/http.ts

@@ -42,6 +42,42 @@ export interface StorefrontClientConfig {
 export type QueryValue = string | number | boolean | null | undefined
 export type Query = Record<string, QueryValue | QueryValue[]>
 
+/**
+ * The reads the platform's CDN holds for anonymous shoppers (store-api.md
+ * § Caching). Such a request carries the store's publishable key in its
+ * address as `pk`, so the edge can tell one store's answers from another's,
+ * and the shopper's locale as `locale`. A request with a customer token
+ * carries neither: its prices are the shopper's own, and an address without
+ * the key is never held and never served from the hold. Carts, checkout,
+ * consent, customers and every write are never on this list.
+ */
+const CACHEABLE_READ_PREFIXES = [
+  "/api/store/store",
+  "/api/store/menus",
+  "/api/store/regions",
+  "/api/store/collections",
+  "/api/store/products",
+  "/api/store/product-variants",
+  "/api/store/product-categories",
+  "/api/store/product-types",
+  "/api/store/product-tags",
+  "/api/store/reviews",
+  "/api/store/currencies",
+  "/api/store/countries",
+  "/api/store/locales",
+  "/api/store/pages",
+  "/api/store/blogs",
+  "/api/store/metaobjects",
+  "/api/store/url-redirects",
+  "/api/store/return-reasons",
+]
+
+export function isCacheableStoreRead(pathname: string): boolean {
+  return CACHEABLE_READ_PREFIXES.some(
+    (prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`)
+  )
+}
+
 export interface RequestOptions {
   method?: "GET" | "POST" | "DELETE"
   query?: Query
@@ -92,9 +128,23 @@ export class StorefrontClient {
     const locale = this.config.getLocale ? await this.config.getLocale() : null
     if (locale && !headers["x-locale"]) headers["x-locale"] = locale
 
+    // An anonymous catalogue read carries its key (and locale) in the
+    // address, so the platform's CDN may hold the answer for this store.
+    const method = opts.method ?? "GET"
+    const anonymous = !headers.authorization
+    if (
+      method === "GET" &&
+      anonymous &&
+      this.config.publishableKey &&
+      isCacheableStoreRead(url.pathname)
+    ) {
+      url.searchParams.set("pk", this.config.publishableKey)
+      if (locale) url.searchParams.set("locale", locale)
+    }
+
     const doFetch = this.config.fetch ?? fetch
     const res = await doFetch(url.toString(), {
-      method: opts.method ?? "GET",
+      method,
       headers,
       body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
       cache: opts.cache,

package/src/cart-drawer/cross-sell-carousel.tsx

@@ -1,6 +1,6 @@
 "use client"
 
-import Image from "next/image"
+import { StoreImage as Image } from "../lib/media-image"
 import Link from "next/link"
 import { useRef, useState } from "react"
 

package/src/cart-drawer/cross-sell-sidebar.tsx

@@ -1,6 +1,6 @@
 "use client"
 
-import Image from "next/image"
+import { StoreImage as Image } from "../lib/media-image"
 import Link from "next/link"
 
 import type { StoreProduct } from "../api/products"

package/src/cart-drawer/free-gift.tsx

@@ -1,6 +1,6 @@
 "use client"
 
-import Image from "next/image"
+import { StoreImage as Image } from "../lib/media-image"
 
 import { convertToLocale } from "../lib/money"
 import { useCartDrawer } from "./context"

package/src/cart-drawer/item/index.tsx

@@ -1,6 +1,6 @@
 "use client"
 
-import Image from "next/image"
+import { StoreImage as Image } from "../../lib/media-image"
 import Link from "next/link"
 import { type ReactNode } from "react"
 

package/src/cart-drawer/item/upsell.tsx

@@ -1,6 +1,6 @@
 "use client"
 
-import Image from "next/image"
+import { StoreImage as Image } from "../../lib/media-image"
 import Link from "next/link"
 
 import { convertToLocale } from "../../lib/money"

package/src/lib/media-image.tsx

@@ -0,0 +1,39 @@
+import NextImage, { type ImageProps } from "next/image"
+
+/**
+ * The store's picture element (store-speed-law card, step 3, 2026-09-15).
+ *
+ * Product pictures live on the Cartbase media CDN, and Next resizes them on
+ * the store's own project, per device and in the modern formats, which the
+ * scaffold allows through `images.remotePatterns` (next.config.ts). The
+ * scaffold used to ship `images.unoptimized: true` instead, so no picture
+ * was ever resized: a phone downloaded the merchant's full upload.
+ *
+ * A picture from any other host (a catalogue not yet rehosted, a demo
+ * placeholder, a merchant's own asset host) renders as it is instead of
+ * failing the page: Next refuses to resize a host the config does not
+ * list, so this element switches resizing off for those. A merchant who
+ * adds their host to `remotePatterns` gets resizing there too by passing
+ * `unoptimized={false}` where they render it, or by using `next/image`
+ * directly.
+ */
+
+/** The public base of the media CDN (REGISTRY.md, CDN domain). */
+export const MEDIA_HOST = "cartbase.cloud"
+
+/** Is this picture served by the media CDN (or by the app itself)? */
+export function isResizableSrc(src: ImageProps["src"]): boolean {
+  if (typeof src !== "string") return true
+  if (src.startsWith("/")) return true
+  try {
+    const host = new URL(src).hostname
+    return host === MEDIA_HOST || host.endsWith(`.${MEDIA_HOST}`)
+  } catch {
+    return false
+  }
+}
+
+export function StoreImage(props: ImageProps) {
+  const unoptimized = props.unoptimized ?? !isResizableSrc(props.src)
+  return <NextImage {...props} unoptimized={unoptimized} />
+}

package/src/order/order-item.tsx

@@ -1,4 +1,4 @@
-import Image from "next/image"
+import { StoreImage as Image } from "../lib/media-image"
 import { ImageOff } from "lucide-react"
 import { Price } from "../lib/price"
 import { variantCaption } from "../lib/variant-caption"

package/src/products/image-gallery.tsx

@@ -5,7 +5,7 @@
  * (`@cartbase/storefront/api/products`; images arrive rank-ordered from the
  * API). Server-safe.
  */
-import Image from "next/image"
+import { StoreImage as Image } from "../lib/media-image"
 import type { StoreProductImage } from "../api/products"
 
 type ImageGalleryProps = {

package/src/products/thumbnail.tsx

@@ -4,7 +4,7 @@
  * + `StoreProduct.images`). Server-safe (no "use client"): renders inside
  * RSC product grids.
  */
-import Image from "next/image"
+import { StoreImage as Image } from "../lib/media-image"
 import React from "react"
 import { ImageOff } from "lucide-react"