@decocms/apps 0.20.1

package/commerce/utils/canonical.ts

@@ -0,0 +1,11 @@
+import { BreadcrumbList } from "../types/commerce";
+
+export const canonicalFromBreadcrumblist = (
+  b?: BreadcrumbList,
+) => {
+  const items = b?.itemListElement ?? [];
+  if (!Array.isArray(items) || items.length === 0) return undefined;
+
+  return items.reduce((acc, curr) => acc.position < curr.position ? curr : acc)
+    .item;
+};

package/commerce/utils/constants.ts

@@ -0,0 +1,9 @@
+import { ImageObject } from "../types/commerce";
+
+export const DEFAULT_IMAGE: ImageObject = {
+  "@type": "ImageObject",
+  encodingFormat: "image",
+  alternateName: "Default Image Placeholder",
+  url:
+    "https://ozksgdmyrqcxcwhnbepg.supabase.co/storage/v1/object/public/assets/1818/ff6bb37e-0eab-40e1-a454-86856efc278e",
+};

package/commerce/utils/filters.ts

@@ -0,0 +1,10 @@
+export const parseRange = (price: string) => {
+  const splitted = price.split(":");
+
+  const from = Number(splitted?.[0]);
+  const to = Number(splitted?.[1]);
+
+  return Number.isNaN(from) || Number.isNaN(to) ? null : { from, to };
+};
+
+export const formatRange = (from: number, to: number) => `${from}:${to}`;

package/commerce/utils/productToAnalyticsItem.ts

@@ -0,0 +1,67 @@
+import type { AnalyticsItem, BreadcrumbList, Product } from "../types/commerce";
+
+export const mapCategoriesToAnalyticsCategories = (
+  categories: string[],
+): Record<`item_category${number | ""}`, string> => {
+  return categories.slice(0, 5).reduce(
+    (result, category, index) => {
+      result[`item_category${index === 0 ? "" : index + 1}`] = category;
+      return result;
+    },
+    {} as Record<`item_category${number | ""}`, string>,
+  );
+};
+
+export const mapProductCategoryToAnalyticsCategories = (category: string) => {
+  return category.split(">").reduce(
+    (result, category, index) => {
+      result[`item_category${index === 0 ? "" : index + 1}`] = category.trim();
+      return result;
+    },
+    {} as Record<`item_category${number | ""}`, string>,
+  );
+};
+
+export const mapProductToAnalyticsItem = (
+  {
+    product,
+    breadcrumbList,
+    price,
+    listPrice,
+    index = 0,
+    quantity = 1,
+    coupon = "",
+  }: {
+    product: Product;
+    breadcrumbList?: BreadcrumbList;
+    price?: number;
+    listPrice?: number;
+    index?: number;
+    quantity?: number;
+    coupon?: string;
+  },
+): AnalyticsItem => {
+  const { name, productID, inProductGroupWithID, isVariantOf, url } = product;
+  const categories = breadcrumbList?.itemListElement
+    ? mapCategoriesToAnalyticsCategories(
+      breadcrumbList?.itemListElement.map(({ name: _name }) => _name ?? "")
+        .filter(Boolean) ??
+        [],
+    )
+    : mapProductCategoryToAnalyticsCategories(product.category ?? "");
+
+  return {
+    item_id: productID,
+    item_group_id: inProductGroupWithID,
+    quantity,
+    coupon,
+    price,
+    index,
+    discount: Number((price && listPrice ? listPrice - price : 0).toFixed(2)),
+    item_name: isVariantOf?.name ?? name ?? "",
+    item_variant: name,
+    item_brand: product.brand?.name ?? "",
+    item_url: url,
+    ...categories,
+  };
+};

package/commerce/utils/stateByZip.ts

@@ -0,0 +1,50 @@
+const getStateFromZip = (cep: string) => {
+  // Remove non-numeric characters
+  cep = cep.replace(/\D/g, "");
+
+  // zip range by: https://buscacepinter.correios.com.br/app/faixa_cep_uf_localidade/index.php
+  const zipRange = [
+    { state: "AC", startRange: 69900000, endRange: 69999999 },
+    { state: "AL", startRange: 57000000, endRange: 57999999 },
+    { state: "AM", startRange: 69000000, endRange: 69299999 },
+    { state: "AM", startRange: 69400000, endRange: 69899999 },
+    { state: "AP", startRange: 68900000, endRange: 68999999 },
+    { state: "BA", startRange: 40000000, endRange: 48999999 },
+    { state: "CE", startRange: 60000000, endRange: 63999999 },
+    { state: "DF", startRange: 70000000, endRange: 72799999 },
+    { state: "DF", startRange: 73000000, endRange: 73699999 },
+    { state: "ES", startRange: 29000000, endRange: 29999999 },
+    { state: "GO", startRange: 72800000, endRange: 72999999 },
+    { state: "GO", startRange: 73700000, endRange: 76799999 },
+    { state: "MA", startRange: 65000000, endRange: 65999999 },
+    { state: "MG", startRange: 30000000, endRange: 39999999 },
+    { state: "MS", startRange: 79000000, endRange: 79999999 },
+    { state: "MT", startRange: 78000000, endRange: 78899999 },
+    { state: "PA", startRange: 66000000, endRange: 68899999 },
+    { state: "PB", startRange: 58000000, endRange: 58999999 },
+    { state: "PE", startRange: 50000000, endRange: 56999999 },
+    { state: "PI", startRange: 64000000, endRange: 64999999 },
+    { state: "PR", startRange: 80000000, endRange: 87999999 },
+    { state: "RJ", startRange: 20000000, endRange: 28999999 },
+    { state: "RN", startRange: 59000000, endRange: 59999999 },
+    { state: "RO", startRange: 76800000, endRange: 76999999 },
+    { state: "RR", startRange: 69300000, endRange: 69399999 },
+    { state: "RS", startRange: 90000000, endRange: 99999999 },
+    { state: "SC", startRange: 88000000, endRange: 89999999 },
+    { state: "SE", startRange: 49000000, endRange: 49999999 },
+    { state: "SP", startRange: 1000000, endRange: 19999999 },
+    { state: "TO", startRange: 77000000, endRange: 77999999 },
+  ];
+
+  const zipCode = parseInt(cep);
+
+  for (const range of zipRange) {
+    if (zipCode >= range.startRange && zipCode <= range.endRange) {
+      return range.state;
+    }
+  }
+
+  return "";
+};
+
+export default getStateFromZip;

package/knip.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://unpkg.com/knip@latest/schema.json",
+  "entry": [
+    "vtex/*.ts",
+    "vtex/inline-loaders/*.ts",
+    "commerce/components/*.tsx",
+    "commerce/sdk/*.ts"
+  ],
+  "project": [
+    "**/*.ts",
+    "**/*.tsx"
+  ],
+  "ignoreBinaries": [
+    "semantic-release"
+  ],
+  "ignoreDependencies": [
+    "@decocms/start"
+  ]
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@decocms/apps",
+  "version": "0.20.1",
+  "type": "module",
+  "description": "Deco commerce apps for TanStack Start - Shopify, VTEX, commerce types, analytics utils",
+  "exports": {
+    "./commerce/types": "./commerce/types/commerce.ts",
+    "./commerce/components/JsonLd": "./commerce/components/JsonLd.tsx",
+    "./commerce/components/Image": "./commerce/components/Image.tsx",
+    "./commerce/utils/*": "./commerce/utils/*.ts",
+    "./commerce/sdk/*": "./commerce/sdk/*.ts",
+    "./shopify": "./shopify/index.ts",
+    "./shopify/client": "./shopify/client.ts",
+    "./shopify/loaders/*": "./shopify/loaders/*.ts",
+    "./shopify/actions/*": "./shopify/actions/*.ts",
+    "./shopify/actions/cart/*": "./shopify/actions/cart/*.ts",
+    "./shopify/actions/user/*": "./shopify/actions/user/*.ts",
+    "./shopify/utils/*": "./shopify/utils/*.ts",
+    "./vtex": "./vtex/index.ts",
+    "./vtex/client": "./vtex/client.ts",
+    "./vtex/types": "./vtex/types.ts",
+    "./vtex/actions": "./vtex/actions/index.ts",
+    "./vtex/actions/*": "./vtex/actions/*.ts",
+    "./vtex/loaders": "./vtex/loaders/index.ts",
+    "./vtex/loaders/*": "./vtex/loaders/*.ts",
+    "./vtex/utils": "./vtex/utils/index.ts",
+    "./vtex/utils/*": "./vtex/utils/*.ts",
+    "./vtex/inline-loaders/*": "./vtex/inline-loaders/*.ts",
+    "./vtex/inline-loaders/productDetailsPage": "./vtex/inline-loaders/productDetailsPage.ts",
+    "./vtex/inline-loaders/productListingPage": "./vtex/inline-loaders/productListingPage.ts",
+    "./vtex/inline-loaders/productList": "./vtex/inline-loaders/productList.ts",
+    "./vtex/inline-loaders/relatedProducts": "./vtex/inline-loaders/relatedProducts.ts",
+    "./vtex/inline-loaders/suggestions": "./vtex/inline-loaders/suggestions.ts",
+    "./vtex/hooks": "./vtex/hooks/index.ts",
+    "./vtex/hooks/*": "./vtex/hooks/*.ts",
+    "./vtex/inline-loaders/workflowProducts": "./vtex/inline-loaders/workflowProducts.ts",
+    "./vtex/middleware": "./vtex/middleware.ts",
+    "./vtex/invoke": "./vtex/invoke.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint:unused": "knip",
+    "lint:unused:fix": "knip --fix",
+    "check": "tsc --noEmit && knip"
+  },
+  "keywords": [
+    "deco",
+    "shopify",
+    "vtex",
+    "commerce"
+  ],
+  "author": "deco.cx",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/decocms/apps-start.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@decocms/start": "~0.19.0",
+    "@tanstack/react-query": ">=5",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@decocms/start": "file:../deco-start",
+    "@semantic-release/git": "^10.0.1",
+    "@tanstack/react-query": "^5.90.21",
+    "@types/react": "^19.0.0",
+    "knip": "^5.86.0",
+    "react": "^19.0.0",
+    "typescript": "^5.9.3"
+  }
+}

package/shopify/actions/cart/addItems.ts

@@ -0,0 +1,37 @@
+import { getShopifyClient } from "../../client";
+import { getCartCookie, setCartCookie } from "../../utils/cart";
+import { AddItemToCart } from "../../utils/storefront/queries";
+import type { ShopifyCart } from "../../loaders/cart";
+
+export interface AddItemProps {
+  lines: {
+    merchandiseId: string;
+    attributes?: Array<{ key: string; value: string }>;
+    quantity?: number;
+    sellingPlanId?: string;
+  };
+  requestHeaders: Headers;
+  responseHeaders?: Headers;
+}
+
+export default async function addItems(
+  { lines, requestHeaders, responseHeaders }: AddItemProps,
+): Promise<ShopifyCart | null> {
+  const client = getShopifyClient();
+  const cartId = getCartCookie(requestHeaders);
+
+  if (!cartId) throw new Error("Missing cart cookie");
+
+  const data = await client.query<{
+    payload?: { cart?: ShopifyCart };
+  }>(
+    AddItemToCart,
+    { cartId, lines },
+  );
+
+  if (responseHeaders) {
+    setCartCookie(responseHeaders, cartId);
+  }
+
+  return data.payload?.cart ?? null;
+}

package/shopify/actions/cart/updateCoupons.ts

@@ -0,0 +1,32 @@
+import { getShopifyClient } from "../../client";
+import { getCartCookie, setCartCookie } from "../../utils/cart";
+import { AddCoupon } from "../../utils/storefront/queries";
+import type { ShopifyCart } from "../../loaders/cart";
+
+export interface UpdateCouponsProps {
+  discountCodes: string[];
+  requestHeaders: Headers;
+  responseHeaders?: Headers;
+}
+
+export default async function updateCoupons(
+  { discountCodes, requestHeaders, responseHeaders }: UpdateCouponsProps,
+): Promise<ShopifyCart | null> {
+  const client = getShopifyClient();
+  const cartId = getCartCookie(requestHeaders);
+
+  if (!cartId) throw new Error("Missing cart cookie");
+
+  const data = await client.query<{
+    payload?: { cart?: ShopifyCart };
+  }>(
+    AddCoupon,
+    { cartId, discountCodes },
+  );
+
+  if (responseHeaders) {
+    setCartCookie(responseHeaders, cartId);
+  }
+
+  return data.payload?.cart ?? null;
+}

package/shopify/actions/cart/updateItems.ts

@@ -0,0 +1,32 @@
+import { getShopifyClient } from "../../client";
+import { getCartCookie, setCartCookie } from "../../utils/cart";
+import { UpdateItems } from "../../utils/storefront/queries";
+import type { ShopifyCart } from "../../loaders/cart";
+
+export interface UpdateItemsProps {
+  lines: Array<{ id: string; quantity: number }>;
+  requestHeaders: Headers;
+  responseHeaders?: Headers;
+}
+
+export default async function updateItems(
+  { lines, requestHeaders, responseHeaders }: UpdateItemsProps,
+): Promise<ShopifyCart | null> {
+  const client = getShopifyClient();
+  const cartId = getCartCookie(requestHeaders);
+
+  if (!cartId) throw new Error("Missing cart cookie");
+
+  const data = await client.query<{
+    payload?: { cart?: ShopifyCart };
+  }>(
+    UpdateItems,
+    { cartId, lines },
+  );
+
+  if (responseHeaders) {
+    setCartCookie(responseHeaders, cartId);
+  }
+
+  return data.payload?.cart ?? null;
+}

package/shopify/actions/user/signIn.ts

@@ -0,0 +1,45 @@
+import { getShopifyClient } from "../../client";
+import { SignInWithEmailAndPassword } from "../../utils/storefront/queries";
+import { getUserCookie, setUserCookie } from "../../utils/user";
+
+export interface SignInProps {
+  email: string;
+  password: string;
+  requestHeaders: Headers;
+  responseHeaders?: Headers;
+}
+
+export interface SignInResult {
+  customerAccessTokenCreate: {
+    customerAccessToken?: { accessToken: string; expiresAt: string } | null;
+    customerUserErrors?: Array<{ code?: string; message: string }>;
+  };
+}
+
+export default async function signIn(
+  props: SignInProps,
+): Promise<SignInResult | null> {
+  const client = getShopifyClient();
+  const { email, password, requestHeaders, responseHeaders } = props;
+
+  const existingToken = getUserCookie(requestHeaders);
+  if (existingToken) return null;
+
+  try {
+    const data = await client.query<SignInResult>(
+      SignInWithEmailAndPassword,
+      { email, password },
+    );
+
+    if (data.customerAccessTokenCreate.customerAccessToken && responseHeaders) {
+      setUserCookie(
+        responseHeaders,
+        data.customerAccessTokenCreate.customerAccessToken.accessToken,
+      );
+    }
+
+    return data;
+  } catch {
+    return null;
+  }
+}

package/shopify/actions/user/signUp.ts

@@ -0,0 +1,36 @@
+import { getShopifyClient } from "../../client";
+import { RegisterAccount } from "../../utils/storefront/queries";
+
+export interface SignUpProps {
+  email: string;
+  password: string;
+  firstName?: string;
+  lastName?: string;
+  acceptsMarketing?: boolean;
+}
+
+export interface SignUpResult {
+  customerCreate: {
+    customer?: { id: string } | null;
+    customerUserErrors?: Array<{ code?: string; message: string }>;
+  };
+}
+
+export default async function signUp(
+  props: SignUpProps,
+): Promise<SignUpResult> {
+  const client = getShopifyClient();
+
+  const data = await client.query<SignUpResult>(
+    RegisterAccount,
+    {
+      email: props.email,
+      password: props.password,
+      firstName: props.firstName,
+      lastName: props.lastName,
+      acceptsMarketing: props.acceptsMarketing,
+    },
+  );
+
+  return data;
+}

package/shopify/client.ts

@@ -0,0 +1,58 @@
+import { createGraphqlClient, type GraphQLClient } from "./utils/graphql";
+
+export interface ShopifyConfig {
+  storeName: string;
+  storefrontAccessToken: string;
+  publicUrl?: string;
+}
+
+let _client: GraphQLClient | null = null;
+let _config: ShopifyConfig | null = null;
+let _fetch: typeof fetch | undefined;
+
+/**
+ * Override the fetch function used by the Shopify GraphQL client.
+ * Use this to plug in instrumented fetch for logging/tracing.
+ *
+ * @example
+ * ```ts
+ * import { createInstrumentedFetch } from "@decocms/start/sdk/instrumentedFetch";
+ * import { setShopifyFetch } from "@decocms/apps/shopify";
+ * setShopifyFetch(createInstrumentedFetch("shopify"));
+ * ```
+ */
+export function setShopifyFetch(fetchFn: typeof fetch) {
+  _fetch = fetchFn;
+  if (_config) configureShopify(_config);
+}
+
+export function configureShopify(config: ShopifyConfig) {
+  _config = config;
+  _client = createGraphqlClient(
+    `https://${config.storeName}.myshopify.com/api/2025-04/graphql.json`,
+    {
+      "X-Shopify-Storefront-Access-Token": config.storefrontAccessToken,
+    },
+    _fetch,
+  );
+}
+
+export function getShopifyClient(): GraphQLClient {
+  if (!_client || !_config) {
+    throw new Error(
+      "Shopify not configured. Call configureShopify() first or check deco-shopify.json block."
+    );
+  }
+  return _client;
+}
+
+export function getShopifyConfig(): ShopifyConfig {
+  if (!_config) {
+    throw new Error("Shopify not configured.");
+  }
+  return _config;
+}
+
+export function getBaseUrl(): string {
+  return _config?.publicUrl || "";
+}

package/shopify/index.ts

@@ -0,0 +1,32 @@
+// Client & Config
+export { configureShopify, getShopifyClient, getShopifyConfig, getBaseUrl, setShopifyFetch } from "./client";
+export type { ShopifyConfig } from "./client";
+export { initShopify, initShopifyFromBlocks } from "./init";
+
+// Product Loaders
+export { default as productListLoader } from "./loaders/ProductList";
+export { default as productDetailsPageLoader } from "./loaders/ProductDetailsPage";
+export { default as productListingPageLoader } from "./loaders/ProductListingPage";
+export { default as relatedProductsLoader } from "./loaders/RelatedProducts";
+
+// Cart
+export { getCart, createCart } from "./loaders/cart";
+export type { ShopifyCart, CartLine } from "./loaders/cart";
+export { default as addItems } from "./actions/cart/addItems";
+export { default as updateItems } from "./actions/cart/updateItems";
+export { default as updateCoupons } from "./actions/cart/updateCoupons";
+
+// Shop
+export { default as shopLoader } from "./loaders/shop";
+export type { Shop } from "./loaders/shop";
+
+// User
+export { default as userLoader } from "./loaders/user";
+export type { ShopifyUser } from "./loaders/user";
+export { default as signIn } from "./actions/user/signIn";
+export { default as signUp } from "./actions/user/signUp";
+
+// Cookie utils
+export { getCookies, setCookie } from "./utils/cookies";
+export { getCartCookie, setCartCookie } from "./utils/cart";
+export { getUserCookie, setUserCookie } from "./utils/user";

package/shopify/init.ts

@@ -0,0 +1,40 @@
+import { configureShopify } from "./client";
+
+let initialized = false;
+
+/**
+ * Initialize Shopify from raw block data.
+ * The site is responsible for reading the blocks and passing the config here.
+ */
+export function initShopify(config: {
+  storeName: string;
+  storefrontAccessToken: string;
+}) {
+  if (initialized) return;
+
+  if (!config.storeName || !config.storefrontAccessToken) {
+    console.warn("[Shopify] Missing storeName or storefrontAccessToken.");
+    return;
+  }
+
+  console.log(`[Shopify] Initializing: ${config.storeName}.myshopify.com`);
+  configureShopify(config);
+  initialized = true;
+}
+
+/**
+ * Initialize Shopify from a blocks map (convenience wrapper).
+ * Looks for the "deco-shopify" block and extracts credentials.
+ */
+export function initShopifyFromBlocks(blocks: Record<string, any>) {
+  const shopifyBlock = blocks["deco-shopify"];
+  if (!shopifyBlock) {
+    console.warn("[Shopify] No deco-shopify block found.");
+    return;
+  }
+
+  initShopify({
+    storeName: shopifyBlock.storeName,
+    storefrontAccessToken: shopifyBlock.storefrontAccessToken,
+  });
+}

package/shopify/loaders/ProductDetailsPage.ts

@@ -0,0 +1,35 @@
+import type { ProductDetailsPage } from "../../commerce/types/commerce";
+import { getShopifyClient } from "../client";
+import { GetProduct } from "../utils/storefront/queries";
+import { toProductPage, type ProductShopify } from "../utils/transform";
+import type { Metafield } from "../utils/types";
+
+export interface Props {
+  slug: string;
+  metafields?: Metafield[];
+}
+
+export default async function productDetailsPageLoader(
+  props: Props,
+  url?: URL,
+): Promise<ProductDetailsPage | null> {
+  const client = getShopifyClient();
+  const { slug, metafields = [] } = props;
+
+  const splitted = slug?.split("-") ?? [];
+  const maybeSkuId = Number(splitted[splitted.length - 1]);
+  const handle = splitted.slice(0, maybeSkuId ? -1 : undefined).join("-");
+
+  const data = await client.query<{ product?: ProductShopify }>(
+    GetProduct,
+    { handle, identifiers: metafields },
+  );
+
+  if (!data?.product) return null;
+
+  return toProductPage(
+    data.product,
+    url ?? new URL("https://localhost"),
+    maybeSkuId || undefined,
+  );
+}