@decocms/apps 0.21.1 → 0.21.3

package/README.md

@@ -0,0 +1,75 @@
+# @decocms/apps
+
+[![npm version](https://img.shields.io/npm/v/@decocms/apps.svg)](https://www.npmjs.com/package/@decocms/apps)
+[![license](https://img.shields.io/npm/l/@decocms/apps.svg)](https://github.com/decocms/apps-start/blob/main/LICENSE)
+
+Commerce integrations for [Deco](https://deco.cx) storefronts on **TanStack Start + React 19 + Cloudflare Workers**.
+
+Provides VTEX and Shopify loaders, actions, hooks, and shared commerce types based on schema.org. Built on top of [`@decocms/start`](https://www.npmjs.com/package/@decocms/start).
+
+## Install
+
+```bash
+npm install @decocms/apps
+```
+
+## Integrations
+
+### VTEX
+
+Full VTEX Intelligent Search and Checkout integration.
+
+| Import | Purpose |
+|--------|---------|
+| `@decocms/apps/vtex` | Configuration and setup |
+| `@decocms/apps/vtex/client` | VTEX API client with SWR caching |
+| `@decocms/apps/vtex/loaders/*` | Product, cart, search, catalog, session, wishlist |
+| `@decocms/apps/vtex/actions/*` | Checkout, auth, newsletter, profile, wishlist |
+| `@decocms/apps/vtex/hooks` | useCart, useUser, useWishlist, useAutocomplete |
+| `@decocms/apps/vtex/inline-loaders/*` | PDP, PLP, product list, suggestions |
+| `@decocms/apps/vtex/middleware` | Cookie propagation and session handling |
+| `@decocms/apps/vtex/invoke` | Server function wrappers |
+| `@decocms/apps/vtex/utils/*` | Transform, enrichment, segment, cookies |
+
+### Shopify
+
+Storefront API integration via GraphQL.
+
+| Import | Purpose |
+|--------|---------|
+| `@decocms/apps/shopify` | Configuration and setup |
+| `@decocms/apps/shopify/client` | Storefront GraphQL client |
+| `@decocms/apps/shopify/loaders/*` | PDP, PLP, product list, cart, user |
+| `@decocms/apps/shopify/actions/cart/*` | Add, update items, coupons |
+| `@decocms/apps/shopify/actions/user/*` | Sign in, sign up |
+| `@decocms/apps/shopify/utils/*` | Transform, cookies, GraphQL queries |
+
+### Shared Commerce
+
+Platform-agnostic types and utilities.
+
+| Import | Purpose |
+|--------|---------|
+| `@decocms/apps/commerce/types` | schema.org Product, Offer, BreadcrumbList, etc. |
+| `@decocms/apps/commerce/components/Image` | Optimized commerce image component |
+| `@decocms/apps/commerce/components/JsonLd` | Structured data for SEO |
+| `@decocms/apps/commerce/sdk/*` | useOffer, formatPrice, analytics, URL utils |
+| `@decocms/apps/commerce/utils/*` | productToAnalyticsItem, canonical, stateByZip |
+
+## Peer Dependencies
+
+- `@decocms/start` >= 0.19.0
+- `@tanstack/react-query` >= 5
+- `react` >= 18
+- `react-dom` >= 18
+
+## Development
+
+```bash
+npm run typecheck   # tsc --noEmit
+npm run check       # typecheck + unused export detection
+```
+
+## License
+
+MIT

package/commerce/components/Image.tsx

@@ -1,144 +1,201 @@
+import type { ImgHTMLAttributes } from "react";
+
+// -------------------------------------------------------------------------
+// Known asset prefixes that get stripped to produce a relative src path
+// -------------------------------------------------------------------------
+
+const DECO_CACHE_URL = "https://assets.decocache.com/";
+const S3_URL = "https://deco-sites-assets.s3.sa-east-1.amazonaws.com/";
+
+// -------------------------------------------------------------------------
+// Configurable CDN domain
+// -------------------------------------------------------------------------
+
+let imageCdnDomain = "decoims.com";
+
 /**
- * Optimized Image component with CDN-aware transforms.
+ * Register the image CDN domain used by `getOptimizedMediaUrl`.
+ * Call once in your site's setup.ts before any page loads.
  *
- * Generates responsive srcset, enforces width/height for CLS prevention,
- * and builds optimized URLs for different image CDNs (VTEX, Shopify,
- * Deco, Cloudflare).
- *
- * @example
- * ```tsx
- * <Image
- *   src="https://store.vteximg.com.br/products/123.jpg"
- *   width={400}
- *   height={400}
- *   alt="Product name"
- *   cdn="vtex"
- * />
- * ```
+ * Available domains:
+ * - `decoims.com` (Cloudflare, default — best compression, same edge as Workers)
+ * - `deco-assets.edgedeco.com` (Azion IMS)
+ * - `deco-assets.decoazn.com` (Azion IMS, legacy)
  */
+export function registerImageCdnDomain(domain: string) {
+  imageCdnDomain = domain.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+}
 
-import type { ImgHTMLAttributes } from "react";
+export function getImageCdnDomain(): string {
+  return imageCdnDomain;
+}
 
-export type ImageCDN = "vtex" | "shopify" | "deco" | "cloudflare" | "none";
+// -------------------------------------------------------------------------
+// Fit options & optimization types
+// -------------------------------------------------------------------------
 
-export interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "width" | "height"> {
-  src: string;
+export type FitOptions = "contain" | "cover";
+
+export const FACTORS = [1, 2];
+
+interface OptimizationOptions {
+  originalSrc: string;
   width: number;
-  height: number;
-  /** Image CDN to use for URL transforms. @default "none" */
-  cdn?: ImageCDN;
-  /**
-   * Responsive sizes descriptor.
-   * @default "(max-width: 768px) 100vw, 50vw"
-   */
-  sizes?: string;
-  /**
-   * Multipliers for srcset generation.
-   * @default [1, 2]
-   */
-  srcSetMultipliers?: number[];
-  /** Preload the image (adds fetchPriority="high"). */
-  preload?: boolean;
+  height?: number;
+  fit: FitOptions;
 }
 
 // -------------------------------------------------------------------------
-// CDN URL builders
+// Platform-specific URL optimizers (fallbacks when the CDN can handle
+// the native platform's resize syntax directly)
 // -------------------------------------------------------------------------
 
-function vtexImageUrl(src: string, width: number, height: number): string {
-  if (src.includes("vteximg.com.br") || src.includes("vtexassets.com")) {
-    return src.replace(
-      /(-\d+-\d+)(\.\w+)$/,
-      `-${width}-${height}$2`,
-    );
-  }
+function optimizeVTEX(originalSrc: string, width: number, height?: number): string {
+  const src = new URL(originalSrc);
+  const [slash, arquivos, ids, rawId, ...rest] = src.pathname.split("/");
+  const [trueId] = rawId.split("-");
 
-  const url = new URL(src, "https://placeholder.com");
-  url.searchParams.set("width", String(width));
-  url.searchParams.set("height", String(height));
-  return url.toString();
+  src.pathname = [
+    slash,
+    arquivos,
+    ids,
+    `${trueId}-${width}-${height ?? width}`,
+    ...rest,
+  ].join("/");
+
+  return src.href;
 }
 
-function shopifyImageUrl(src: string, width: number): string {
-  if (src.includes("cdn.shopify.com")) {
-    return src.replace(/(\.\w+)(\?.*)?$/, `_${width}x$1$2`);
-  }
-  return src;
+function optimizeShopify(originalSrc: string, width: number, height?: number): string {
+  const url = new URL(originalSrc);
+  url.searchParams.set("width", `${width}`);
+  if (height) url.searchParams.set("height", `${height}`);
+  url.searchParams.set("crop", "center");
+  return url.href;
 }
 
-function decoImageUrl(src: string, width: number, height: number): string {
-  if (src.includes("decocache.com") || src.includes("ozksgdmyrqcxcwhnbepg")) {
-    const url = new URL(src);
-    url.searchParams.set("width", String(width));
-    url.searchParams.set("height", String(height));
-    url.searchParams.set("fit", "cover");
-    return url.toString();
+// -------------------------------------------------------------------------
+// Core optimization function
+// Ported from deco-cx/apps website/components/Image.tsx
+// -------------------------------------------------------------------------
+
+/**
+ * Builds an optimized image URL.
+ *
+ * For Deco-hosted images (decocache / S3), strips the known prefix and
+ * routes through the Deco image CDN for edge resize + format conversion.
+ *
+ * For platform-specific images (VTEX, Shopify), rewrites the URL using
+ * the platform's native resize params — no CDN proxy needed.
+ *
+ * Data URIs are returned as-is.
+ */
+export function getOptimizedMediaUrl(opts: OptimizationOptions): string {
+  const { originalSrc, width, height, fit } = opts;
+
+  if (originalSrc.startsWith("data:")) {
+    return originalSrc;
   }
-  return src;
-}
 
-function cloudflareImageUrl(src: string, width: number, height: number): string {
-  return `/cdn-cgi/image/width=${width},height=${height},fit=cover,format=auto,quality=80/${src}`;
-}
+  if (
+    /(vteximg\.com\.br|vtexassets\.com|myvtex\.com)\/arquivos\/ids\/\d+/.test(originalSrc)
+  ) {
+    return optimizeVTEX(originalSrc, width, height);
+  }
 
-function buildUrl(src: string, width: number, height: number, cdn: ImageCDN): string {
-  switch (cdn) {
-    case "vtex": return vtexImageUrl(src, width, height);
-    case "shopify": return shopifyImageUrl(src, width);
-    case "deco": return decoImageUrl(src, width, height);
-    case "cloudflare": return cloudflareImageUrl(src, width, height);
-    default: return src;
+  if (originalSrc.startsWith("https://cdn.shopify.com")) {
+    return optimizeShopify(originalSrc, width, height);
   }
+
+  const imageSource = originalSrc
+    .replace(DECO_CACHE_URL, "")
+    .replace(S3_URL, "")
+    .split("?")[0];
+
+  const params = new URLSearchParams();
+  params.set("fit", fit);
+  params.set("width", `${width}`);
+  if (height) params.set("height", `${height}`);
+
+  return `https://${imageCdnDomain}/image?${params}&src=${imageSource}`;
 }
 
-function buildSrcSet(
-  src: string,
+/**
+ * Generates a srcset string with responsive multipliers.
+ */
+export function getSrcSet(
+  originalSrc: string,
   width: number,
-  height: number,
-  cdn: ImageCDN,
-  multipliers: number[],
-): string {
-  return multipliers
-    .map((m) => {
-      const w = Math.round(width * m);
-      const h = Math.round(height * m);
-      return `${buildUrl(src, w, h, cdn)} ${w}w`;
-    })
-    .join(", ");
+  height?: number,
+  fit?: FitOptions,
+  factors: number[] = FACTORS,
+): string | undefined {
+  const entries: string[] = [];
+
+  for (const factor of factors) {
+    const w = Math.trunc(factor * width);
+    const h = height ? Math.trunc(factor * height) : undefined;
+
+    const src = getOptimizedMediaUrl({
+      originalSrc,
+      width: w,
+      height: h,
+      fit: fit ?? "cover",
+    });
+
+    if (src) {
+      entries.push(`${src} ${w}w`);
+    }
+  }
+
+  return entries.length > 0 ? entries.join(", ") : undefined;
 }
 
 // -------------------------------------------------------------------------
-// Component
+// Image component
 // -------------------------------------------------------------------------
 
+export interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "width" | "height"> {
+  src: string;
+  /** @description Improves Web Vitals (CLS/LCP) */
+  width: number;
+  /** @description Improves Web Vitals (CLS/LCP) */
+  height?: number;
+  /** @description Object-fit */
+  fit?: FitOptions;
+  /** @description Preload the image (adds fetchPriority="high") */
+  preload?: boolean;
+}
+
 export function Image({
   src,
   width,
   height,
-  cdn = "none",
-  sizes = "(max-width: 768px) 100vw, 50vw",
-  srcSetMultipliers = [1, 2],
+  fit = "cover",
   preload,
   loading,
   decoding,
+  srcSet: srcSetProp,
+  sizes,
   ...rest
 }: ImageProps) {
-  const optimizedSrc = buildUrl(src, width, height, cdn);
-  const srcSet = cdn !== "none"
-    ? buildSrcSet(src, width, height, cdn, srcSetMultipliers)
-    : undefined;
+  if (!height && typeof process !== "undefined") {
+    console.warn(`Missing height. This image will NOT be optimized: ${src}`);
+  }
+
+  const srcSet = srcSetProp ?? getSrcSet(src, width, height, fit);
 
   return (
     <img
-      src={optimizedSrc}
+      {...rest}
+      src={src}
       srcSet={srcSet}
-      sizes={srcSet ? sizes : undefined}
+      sizes={srcSet ? (sizes ?? "(max-width: 768px) 100vw, 50vw") : undefined}
       width={width}
       height={height}
       loading={loading ?? (preload ? "eager" : "lazy")}
       decoding={decoding ?? "async"}
       fetchPriority={preload ? "high" : undefined}
-      {...rest}
     />
   );
 }
@@ -147,63 +204,51 @@ export function Image({
 // Picture (responsive art direction)
 // -------------------------------------------------------------------------
 
-export interface PictureSource {
+export interface PictureSourceProps {
   src: string;
   width: number;
-  height: number;
+  height?: number;
   media: string;
-  cdn?: ImageCDN;
+  fit?: FitOptions;
 }
 
 export interface PictureProps extends Omit<ImageProps, "sizes"> {
-  sources: PictureSource[];
+  sources: PictureSourceProps[];
 }
 
-/**
- * Picture component for responsive art direction.
- *
- * @example
- * ```tsx
- * <Picture
- *   sources={[
- *     { src: mobileSrc, width: 375, height: 200, media: "(max-width: 767px)", cdn: "vtex" },
- *     { src: desktopSrc, width: 1200, height: 400, media: "(min-width: 768px)", cdn: "vtex" },
- *   ]}
- *   src={desktopSrc}
- *   width={1200}
- *   height={400}
- *   alt="Banner"
- * />
- * ```
- */
 export function Picture({
   sources,
   src,
   width,
   height,
-  cdn = "none",
+  fit = "cover",
   preload,
   ...rest
 }: PictureProps) {
   return (
     <picture>
-      {sources.map((source, i) => (
-        <source
-          key={i}
-          srcSet={buildUrl(source.src, source.width, source.height, source.cdn ?? cdn)}
-          media={source.media}
-          width={source.width}
-          height={source.height}
-        />
-      ))}
+      {sources.map((source, i) => {
+        const srcSet = getSrcSet(source.src, source.width, source.height, source.fit ?? fit);
+        return (
+          <source
+            key={i}
+            srcSet={srcSet}
+            media={source.media}
+            width={source.width}
+            height={source.height}
+          />
+        );
+      })}
       <Image
         src={src}
         width={width}
         height={height}
-        cdn={cdn}
+        fit={fit}
         preload={preload}
         {...rest}
       />
     </picture>
   );
 }
+
+export default Image;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps",
-  "version": "0.21.1",
+  "version": "0.21.3",
   "type": "module",
   "description": "Deco commerce apps for TanStack Start - Shopify, VTEX, commerce types, analytics utils",
   "exports": {
@@ -61,7 +61,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@decocms/start": "~0.19.0",
+    "@decocms/start": ">=0.19.0",
     "@tanstack/react-query": ">=5",
     "react": ">=18",
     "react-dom": ">=18"