@decocms/apps-nuvemshop 7.74.1

package/src/hooks/useCart.ts

@@ -0,0 +1,115 @@
+/**
+ * Client-side cart for the Nuvemshop Storefront API.
+ *
+ * The API has no server cart — only `POST /checkouts`, which opens a core
+ * cart from line items and returns the hosted checkout URL. So the cart
+ * lives in `localStorage` (shared across tabs) and `checkout()` hands it to
+ * the `createCheckout` action, which then redirects.
+ *
+ * Prices/totals aren't stored: render them from the products you already
+ * have; the hosted checkout re-validates stock, prices and the coupon.
+ *
+ * ```tsx
+ * const { items, count, addItem, checkout } = useCart();
+ * <button onClick={() => addItem({ productId, variantId, quantity: 1 })}>Comprar</button>
+ * ```
+ */
+import { useSyncExternalStore } from "react";
+import type { CartItem } from "../actions/createCheckout";
+
+export type { CartItem };
+
+export const CART_STORAGE_KEY = "nuvemshop:cart";
+/** The API sums repeated variants up to 99. */
+const MAX_QTY = 99;
+
+export const addItem = (items: CartItem[], item: CartItem): CartItem[] => {
+  const existing = items.find((i) => i.variantId === item.variantId);
+  if (!existing) return [...items, { ...item, quantity: Math.min(item.quantity, MAX_QTY) }];
+  return setQuantity(items, item.variantId, existing.quantity + item.quantity);
+};
+
+export const setQuantity = (items: CartItem[], variantId: number, quantity: number): CartItem[] =>
+  quantity <= 0
+    ? removeItem(items, variantId)
+    : items.map((i) =>
+        i.variantId === variantId ? { ...i, quantity: Math.min(quantity, MAX_QTY) } : i,
+      );
+
+export const removeItem = (items: CartItem[], variantId: number): CartItem[] =>
+  items.filter((i) => i.variantId !== variantId);
+
+const EMPTY: CartItem[] = [];
+
+function read(): CartItem[] {
+  try {
+    const parsed = JSON.parse(localStorage.getItem(CART_STORAGE_KEY) ?? "[]");
+    return Array.isArray(parsed) ? parsed : EMPTY;
+  } catch {
+    return EMPTY;
+  }
+}
+
+function createCartStore() {
+  let items: CartItem[] | null = null;
+  const listeners = new Set<() => void>();
+  const notify = () => {
+    for (const l of listeners) l();
+  };
+
+  if (typeof window !== "undefined") {
+    window.addEventListener("storage", (e) => {
+      if (e.key !== CART_STORAGE_KEY) return;
+      items = read();
+      notify();
+    });
+  }
+
+  const store = {
+    get: (): CartItem[] => (items ??= typeof localStorage === "undefined" ? EMPTY : read()),
+    set(next: CartItem[]) {
+      items = next;
+      if (typeof localStorage !== "undefined")
+        localStorage.setItem(CART_STORAGE_KEY, JSON.stringify(next));
+      notify();
+    },
+    update: (fn: (items: CartItem[]) => CartItem[]) => store.set(fn(store.get())),
+    subscribe(listener: () => void) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+  return store;
+}
+
+export const cartStore = createCartStore();
+
+/** Creates the Nuvemshop checkout for `items` and navigates to it. */
+export async function checkout(
+  items: CartItem[],
+  coupon?: string,
+  navigate: (url: string) => void = (url) => window.location.assign(url),
+) {
+  const res = await fetch("/deco/invoke/nuvemshop/actions/createCheckout", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ items, coupon }),
+  });
+  if (!res.ok) throw new Error(`Checkout failed (${res.status}): ${await res.text()}`);
+  const { checkoutUrl } = (await res.json()) as { checkoutUrl: string };
+  navigate(checkoutUrl);
+}
+
+export function useCart() {
+  const items = useSyncExternalStore(cartStore.subscribe, cartStore.get, () => EMPTY);
+  return {
+    items,
+    count: items.reduce((n, i) => n + i.quantity, 0),
+    addItem: (item: CartItem) => cartStore.update((c) => addItem(c, item)),
+    setQuantity: (variantId: number, quantity: number) =>
+      cartStore.update((c) => setQuantity(c, variantId, quantity)),
+    removeItem: (variantId: number) => cartStore.update((c) => removeItem(c, variantId)),
+    clear: () => cartStore.set([]),
+    checkout: (coupon?: string) => checkout(items, coupon),
+  };
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export { default as createCheckout } from "./actions/createCheckout";
+export {
+  clearNuvemshopCache,
+  configureNuvemshop,
+  getNuvemshopConfig,
+  type NuvemshopConfig,
+  nuvemshopGet,
+  nuvemshopPost,
+  PRODUCT_FIELDS,
+  setNuvemshopFetch,
+} from "./client";
+export { default as categories } from "./loaders/categories";
+export { default as productDetailsPage } from "./loaders/productDetailsPage";
+export { default as productList } from "./loaders/productList";
+export { default as productListingPage } from "./loaders/productListingPage";
+export { default as relatedProducts } from "./loaders/relatedProducts";
+export { default as shippingOptions } from "./loaders/shippingOptions";
+export { default as suggestions } from "./loaders/suggestions";
+export { configure } from "./mod";
+export { NUVEMSHOP_REGISTRY_ENTRY } from "./registry";
+export { createNuvemshopFetch } from "./utils/instrumentedFetch";
+export { nuvemshopOperationRouter } from "./utils/operationRouter";
+export type * from "./utils/types";

package/src/loaders/categories.ts

@@ -0,0 +1,27 @@
+import type { SiteNavigationElement } from "@decocms/apps-commerce/types";
+import { nuvemshopGet } from "../client";
+import { originOf, type PageProps } from "../utils/request";
+import { categoryChain, categoryPath } from "../utils/transform";
+import type { NuvemshopCategory, NuvemshopList } from "../utils/types";
+
+/**
+ * @title Nuvemshop - Categories
+ * @description Category tree for menus, with Nuvemshop-style nested URLs.
+ */
+export default async function categories(
+  props: PageProps,
+  req?: Request,
+): Promise<SiteNavigationElement[]> {
+  const all =
+    (await nuvemshopGet<NuvemshopList<NuvemshopCategory>>("/categories", { per_page: 200 }))
+      ?.data ?? [];
+  const origin = originOf(props, req);
+  const node = (c: NuvemshopCategory): SiteNavigationElement => ({
+    "@type": "SiteNavigationElement",
+    name: c.name,
+    identifier: String(c.id),
+    url: `${origin}${categoryPath(categoryChain(c, all))}`,
+    children: all.filter((child) => child.parent === c.id).map(node),
+  });
+  return all.filter((c) => !c.parent).map(node);
+}

package/src/loaders/productDetailsPage.ts

@@ -0,0 +1,30 @@
+import type { ProductDetailsPage } from "@decocms/apps-commerce/types";
+import { getNuvemshopConfig, nuvemshopGet } from "../client";
+import { originOf, type PageProps, pageUrlOf } from "../utils/request";
+import { toProductPage } from "../utils/transform";
+import type { NuvemshopProduct } from "../utils/types";
+
+export interface Props extends PageProps {
+  /** @description Product handle or id. Defaults to the `/produtos/<handle>` URL segment (trailing slash optional). */
+  slug?: string;
+}
+
+/**
+ * @title Nuvemshop - Product Details Page
+ * @description Product by handle/id; `?variant=<id>` selects the variant.
+ */
+export default async function productDetailsPage(
+  props: Props,
+  req?: Request,
+): Promise<ProductDetailsPage | null> {
+  const url = pageUrlOf(props, req);
+  const slug = props.slug ?? url.pathname.match(/\/produtos\/([^/]+)/)?.[1];
+  if (!slug) return null;
+  const product = await nuvemshopGet<NuvemshopProduct>(`/products/${encodeURIComponent(slug)}`);
+  if (!product?.variants?.length) return null;
+  return toProductPage(product, {
+    origin: originOf(props, req),
+    currency: getNuvemshopConfig().currency,
+    variantId: url.searchParams.get("variant") ?? url.searchParams.get("skuId"),
+  });
+}

package/src/loaders/productList.ts

@@ -0,0 +1,49 @@
+import type { Product } from "@decocms/apps-commerce/types";
+import { getNuvemshopConfig, nuvemshopGet } from "../client";
+import { originOf, type PageProps } from "../utils/request";
+import { pickVariant, toProduct } from "../utils/transform";
+import type { NuvemshopList, NuvemshopProduct, NuvemshopSort } from "../utils/types";
+
+export interface Props extends PageProps {
+  /** @description Product ids (max 30). Takes precedence over the other selectors. */
+  ids?: number[];
+  /** @description Product handles (max 30). */
+  handles?: string[];
+  /** @description Category id (includes subcategories). */
+  categoryId?: number;
+  /** @description Search term. */
+  query?: string;
+  /** @description Ignored for ids/handles (kept in request order) and search. */
+  sort?: NuvemshopSort;
+  /** @default 12 */
+  count?: number;
+}
+
+/**
+ * @title Nuvemshop - Product List
+ * @description Shelf by ids, handles, category or search term.
+ */
+export default async function productList(props: Props, req?: Request): Promise<Product[]> {
+  const count = props.count ?? 12;
+  const byKeys = props.ids?.length
+    ? { ids: props.ids.join(",") }
+    : props.handles?.length
+      ? { handles: props.handles.join(",") }
+      : null;
+  const list =
+    props.query && !byKeys
+      ? await nuvemshopGet<NuvemshopList<NuvemshopProduct>>("/search/products", {
+          q: props.query,
+          per_page: count,
+        })
+      : await nuvemshopGet<NuvemshopList<NuvemshopProduct>>("/products", {
+          ...byKeys,
+          // The API rejects sort_by combined with ids/handles.
+          ...(!byKeys && { category_id: props.categoryId, sort_by: props.sort }),
+          per_page: count,
+        });
+  const opts = { origin: originOf(props, req), currency: getNuvemshopConfig().currency };
+  return (list?.data ?? [])
+    .filter((p) => p.variants?.length)
+    .map((p) => toProduct(p, pickVariant(p), opts));
+}

package/src/loaders/productListingPage.ts

@@ -0,0 +1,94 @@
+import type { ProductListingPage } from "@decocms/apps-commerce/types";
+import { getNuvemshopConfig, nuvemshopGet } from "../client";
+import { applyListing, LISTING_WINDOW, SORT_PARAM } from "../utils/listing";
+import { originOf, type PageProps, pageUrlOf } from "../utils/request";
+import { categoryChain, categoryPath, toBreadcrumbList } from "../utils/transform";
+import type { NuvemshopCategory, NuvemshopList, NuvemshopProduct } from "../utils/types";
+
+export interface Props extends PageProps {
+  /** @description Search term. Defaults to the `q` URL param. */
+  query?: string;
+  /** @description Pin a category. Defaults to the last segment of the URL path. */
+  categoryId?: number;
+  /** @description Products per page. @default 24 */
+  count?: number;
+}
+
+/**
+ * @title Nuvemshop - Product Listing Page
+ * @description Category or search page with in-memory facets (Cor/Tamanho/price), sort and pagination.
+ */
+export default async function productListingPage(
+  props: Props,
+  req?: Request,
+): Promise<ProductListingPage | null> {
+  const url = pageUrlOf(props, req);
+  const origin = originOf(props, req);
+  const term = (props.query ?? url.searchParams.get("q") ?? "").trim();
+  const { currency, defaultSort = "created-descending" } = getNuvemshopConfig();
+  const opts = { origin, currency, count: props.count ?? 24 };
+
+  if (term) {
+    const found = await nuvemshopGet<NuvemshopList<NuvemshopProduct>>("/search/products", {
+      q: term,
+      per_page: LISTING_WINDOW,
+    });
+    const listing = applyListing(found?.data ?? [], url, opts);
+    return {
+      "@type": "ProductListingPage",
+      ...listing,
+      ...withPageType(listing.pageInfo, "Search"),
+      // /search/products takes no sort_by, so best-selling can't be honoured.
+      // Search keeps the API's relevance order by default; it can't do best-selling (no sort_by).
+      sortOptions: [
+        { value: "relevance", label: "Relevância" },
+        ...listing.sortOptions.filter((o) => o.value !== "best-selling"),
+      ],
+      breadcrumb: { "@type": "BreadcrumbList", itemListElement: [], numberOfItems: 0 },
+      seo: {
+        title: term,
+        description: "",
+        canonical: `${origin}${url.pathname}?q=${encodeURIComponent(term)}`,
+        noIndexing: true,
+      },
+    };
+  }
+
+  const handle = (props.__pagePath ?? url.pathname).split("/").filter(Boolean).at(-1);
+  const key = props.categoryId ?? handle;
+  if (!key) return null;
+  const [category, all] = await Promise.all([
+    nuvemshopGet<NuvemshopCategory>(`/categories/${encodeURIComponent(key)}`),
+    nuvemshopGet<NuvemshopList<NuvemshopCategory>>("/categories", { per_page: 200 }),
+  ]);
+  if (!category) return null;
+  const categories = all?.data ?? [category];
+  const leaf = categories.find((c) => c.id === category.id) ?? category;
+
+  const sort = url.searchParams.get(SORT_PARAM);
+  const list = await nuvemshopGet<NuvemshopList<NuvemshopProduct>>("/products", {
+    category_id: category.id,
+    per_page: LISTING_WINDOW,
+    sort_by: sort === "best-selling" ? sort : undefined,
+  });
+  const listing = applyListing(list?.data ?? [], url, { ...opts, defaultSort });
+
+  return {
+    "@type": "ProductListingPage",
+    ...listing,
+    ...withPageType(listing.pageInfo, leaf.parent ? "SubCategory" : "Category"),
+    breadcrumb: toBreadcrumbList(leaf, categories, origin),
+    seo: {
+      title: leaf.seo_title || leaf.name,
+      description: leaf.seo_description || leaf.description || "",
+      canonical: `${origin}${categoryPath(categoryChain(leaf, categories))}`,
+    },
+  };
+}
+
+const withPageType = (
+  pageInfo: ProductListingPage["pageInfo"],
+  type: "Category" | "SubCategory" | "Search",
+) => ({
+  pageInfo: { ...pageInfo, pageTypes: [type] },
+});

package/src/loaders/relatedProducts.ts

@@ -0,0 +1,41 @@
+import type { Product } from "@decocms/apps-commerce/types";
+import { getNuvemshopConfig, nuvemshopGet } from "../client";
+import { originOf, type PageProps, pageUrlOf } from "../utils/request";
+import { isAvailable, pickVariant, toProduct } from "../utils/transform";
+import type { NuvemshopList, NuvemshopProduct } from "../utils/types";
+
+export interface Props extends PageProps {
+  /** @description Product handle or id. Defaults to the `/produtos/<handle>` URL segment (trailing slash optional). */
+  slug?: string;
+  /** @default 8 */
+  count?: number;
+}
+
+const CANDIDATES = 50;
+
+/**
+ * @title Nuvemshop - Related Products
+ * @description Same rule as the Nuvemshop theme's fallback: products from the product's
+ * category, without itself, in-stock first, refilled with out-of-stock ones.
+ * (The theme prefers ids from a related-products app metafield, which the API doesn't expose.)
+ */
+export default async function relatedProducts(props: Props, req?: Request): Promise<Product[]> {
+  const count = props.count ?? 8;
+  const slug = props.slug ?? pageUrlOf(props, req).pathname.match(/\/produtos\/([^/]+)/)?.[1];
+  if (!slug) return [];
+  const product = await nuvemshopGet<NuvemshopProduct>(`/products/${encodeURIComponent(slug)}`);
+  const category = product?.categories?.[0];
+  if (!product || !category) return [];
+
+  const list = await nuvemshopGet<NuvemshopList<NuvemshopProduct>>("/products", {
+    category_id: category.id,
+    per_page: CANDIDATES,
+  });
+  const others = (list?.data ?? []).filter((p) => p.id !== product.id && p.variants?.length);
+  const inStock = (p: NuvemshopProduct) => p.variants!.some(isAvailable);
+  // ponytail: no shuffle (the theme shuffles) — keeps the result cacheable.
+  const ordered = [...others.filter(inStock), ...others.filter((p) => !inStock(p))].slice(0, count);
+
+  const opts = { origin: originOf(props, req), currency: getNuvemshopConfig().currency };
+  return ordered.map((p) => toProduct(p, pickVariant(p), opts));
+}

package/src/loaders/shippingOptions.ts

@@ -0,0 +1,29 @@
+import { nuvemshopPost } from "../client";
+import type { NuvemshopShippingOption, NuvemshopShippingOptions } from "../utils/types";
+
+export interface Props {
+  zipCode: string;
+  variantId: number;
+  /** @default 1 */
+  quantity?: number;
+}
+
+export type ShippingOption = Omit<NuvemshopShippingOption, "price"> & { price: number };
+
+/**
+ * @title Nuvemshop - Shipping Options
+ * @description Shipping quote for one variant + CEP (the API has no whole-cart quote yet).
+ */
+export default async function shippingOptions(
+  props: Props,
+  req?: Request,
+): Promise<ShippingOption[]> {
+  const res = await nuvemshopPost<NuvemshopShippingOptions>(
+    "/shipping-options",
+    { zip_code: props.zipCode, variant_id: props.variantId, quantity: props.quantity ?? 1 },
+    { buyerIp: req?.headers.get("cf-connecting-ip") },
+  );
+  return res.shipping_options.map((o) => ({ ...o, price: Number(o.price) }));
+}
+
+export const cache = "no-store";

package/src/loaders/suggestions.ts

@@ -0,0 +1,24 @@
+import type { Suggestion } from "@decocms/apps-commerce/types";
+import type { PageProps } from "../utils/request";
+import productList from "./productList";
+
+export interface Props extends PageProps {
+  query?: string;
+  /** @default 6 (same as the theme's search suggestions) */
+  count?: number;
+}
+
+/**
+ * @title Nuvemshop - Search Suggestions
+ * @description Autocomplete: top products for the typed term.
+ */
+export default async function suggestions(props: Props, req?: Request): Promise<Suggestion | null> {
+  const query = props.query?.trim();
+  if (!query) return null;
+  const products = await productList({ ...props, query, count: props.count ?? 6 }, req);
+  return {
+    searches: [{ term: query, href: `/search?q=${encodeURIComponent(query)}` }],
+    products,
+    hits: products.length,
+  };
+}

package/src/manifest.gen.ts

@@ -0,0 +1,31 @@
+// Hand-maintained (the generate-manifests script referenced by other apps doesn't exist).
+// Keys are the `__resolveType` / `/deco/invoke/<key>` names.
+
+import * as actions_createCheckout from "./actions/createCheckout";
+import * as loaders_categories from "./loaders/categories";
+import * as loaders_productDetailsPage from "./loaders/productDetailsPage";
+import * as loaders_productList from "./loaders/productList";
+import * as loaders_productListingPage from "./loaders/productListingPage";
+import * as loaders_relatedProducts from "./loaders/relatedProducts";
+import * as loaders_shippingOptions from "./loaders/shippingOptions";
+import * as loaders_suggestions from "./loaders/suggestions";
+
+const manifest = {
+  name: "nuvemshop",
+  loaders: {
+    "nuvemshop/loaders/categories": loaders_categories,
+    "nuvemshop/loaders/productDetailsPage": loaders_productDetailsPage,
+    "nuvemshop/loaders/productList": loaders_productList,
+    "nuvemshop/loaders/productListingPage": loaders_productListingPage,
+    "nuvemshop/loaders/relatedProducts": loaders_relatedProducts,
+    "nuvemshop/loaders/shippingOptions": loaders_shippingOptions,
+    "nuvemshop/loaders/suggestions": loaders_suggestions,
+  },
+  actions: {
+    "nuvemshop/actions/createCheckout": actions_createCheckout,
+  },
+  sections: {},
+} as const;
+
+export type Manifest = typeof manifest;
+export default manifest;

package/src/mod.ts

@@ -0,0 +1,42 @@
+/**
+ * Nuvemshop app module — standard autoconfig contract (`AppModContract`).
+ *
+ * Block `deco-nuvemshop`:
+ * ```json
+ * { "storeId": "8336778", "token": { "__resolveType": "website/loaders/secret.ts", ... }, "currency": "BRL" }
+ * ```
+ * The token is optional (tokenless access works) but recommended in
+ * production — see `client.ts` for the rate-limit trade-off.
+ */
+import type { AppDefinition, ResolveSecretFn } from "@decocms/apps-commerce/app-types";
+import { configureNuvemshop, type NuvemshopConfig } from "./client";
+import manifest from "./manifest.gen";
+
+export interface NuvemshopState {
+  config: NuvemshopConfig;
+}
+
+export async function configure(
+  block: Record<string, unknown>,
+  resolveSecret: ResolveSecretFn,
+): Promise<AppDefinition<NuvemshopState> | null> {
+  const storeId = block?.storeId == null ? "" : String(block.storeId);
+  if (!/^\d+$/.test(storeId)) return null;
+
+  const token =
+    (await resolveSecret(block.token, "NUVEMSHOP_STOREFRONT_TOKEN")) ??
+    (typeof block.token === "string" ? block.token : undefined);
+
+  const config: NuvemshopConfig = {
+    storeId,
+    token: token || undefined,
+    apiVersion: block.apiVersion as string | undefined,
+    currency: block.currency as string | undefined,
+    defaultSort: block.defaultSort as string | undefined,
+  };
+  configureNuvemshop(config);
+
+  return { name: "nuvemshop", manifest, state: { config } };
+}
+
+export const preview = undefined;

package/src/registry.ts

@@ -0,0 +1,9 @@
+import type { AppRegistryEntry } from "@decocms/apps-commerce/registry";
+
+export const NUVEMSHOP_REGISTRY_ENTRY: AppRegistryEntry = {
+  blockKey: "deco-nuvemshop",
+  module: () => import("./mod"),
+  displayName: "Nuvemshop",
+  category: "commerce",
+  description: "Nuvemshop (Tiendanube) Storefront API commerce integration",
+};