@decocms/apps-nuvemshop 7.74.1

package/src/utils/__tests__/listing.test.ts

@@ -0,0 +1,167 @@
+import type { FilterRange, FilterToggle } from "@decocms/apps-commerce/types";
+import { describe, expect, it } from "vitest";
+import browseFixture from "../../__fixtures__/browse-category.json";
+import { applyListing, SORT_OPTIONS } from "../listing";
+import type { NuvemshopList, NuvemshopProduct } from "../types";
+
+const browse: NuvemshopList<NuvemshopProduct> = browseFixture;
+// camisa-xadrez (189.90, Azul e Preto | Vermelho e Preto), camisa-flanela (169.90 promo, Azul e Preto | Cinza),
+// camiseta-gamer (89.90)
+const products = browse.data;
+const ORIGIN = "https://loja.example";
+const run = (qs = "", count = 24) =>
+  applyListing(products, new URL(`${ORIGIN}/camisas/${qs}`), { origin: ORIGIN, count });
+const toggle = (f: ReturnType<typeof run>["filters"], key: string) =>
+  f.find((x): x is FilterToggle => x.key === key && x["@type"] === "FilterToggle")!;
+
+describe("applyListing — facets", () => {
+  it("builds one toggle facet per attribute with product counts", () => {
+    const cor = toggle(run().filters, "Cor");
+    expect(cor.label).toBe("Cor");
+    expect(cor.values.map((v) => [v.value, v.quantity, v.selected])).toEqual(
+      expect.arrayContaining([
+        ["Azul e Preto", 2, false],
+        ["Cinza", 1, false],
+        ["Vermelho e Preto", 1, false],
+      ]),
+    );
+    expect(cor.values.find((v) => v.value === "Cinza")!.url).toBe(`${ORIGIN}/camisas/?Cor=Cinza`);
+  });
+
+  it("filters by attribute (OR within, AND across) and keeps the URL toggle reversible", () => {
+    const r = run("?Cor=Cinza");
+    expect(r.products.map((p) => p.isVariantOf!.productGroupID)).toEqual(["372190471"]);
+    const cinza = toggle(r.filters, "Cor").values.find((v) => v.value === "Cinza")!;
+    expect(cinza.selected).toBe(true);
+    expect(cinza.url).toBe(`${ORIGIN}/camisas/`);
+    // facet counts ignore their own selection
+    expect(toggle(r.filters, "Cor").values.find((v) => v.value === "Azul e Preto")!.quantity).toBe(
+      2,
+    );
+
+    // Nuvemshop theme format: multiple values joined with "|" (OR)
+    expect(run("?Cor=Cinza|Vermelho+e+Preto").products).toHaveLength(2);
+    expect(run("?Cor=Cinza&Tamanho=P").products).toHaveLength(1);
+  });
+
+  it("adds/removes values in the theme's pipe-joined format", () => {
+    const cor = (qs: string) => toggle(run(qs).filters, "Cor").values;
+    const url = (qs: string, value: string) =>
+      decodeURIComponent(cor(qs).find((v) => v.value === value)!.url);
+    expect(url("?Cor=Cinza", "Azul e Preto")).toBe(`${ORIGIN}/camisas/?Cor=Cinza|Azul+e+Preto`);
+    expect(url("?Cor=Cinza|Azul+e+Preto", "Cinza")).toBe(`${ORIGIN}/camisas/?Cor=Azul+e+Preto`);
+    expect(
+      cor("?Cor=Cinza|Azul+e+Preto")
+        .filter((v) => v.selected)
+        .map((v) => v.value)
+        .sort(),
+    ).toEqual(["Azul e Preto", "Cinza"]);
+  });
+
+  it("shows the card on the variant that matches the selected filter", () => {
+    const [card] = run("?Cor=Cinza").products;
+    expect(card.additionalProperty!.find((p) => p.name === "Cor")!.value).toBe("Cinza");
+  });
+
+  it("offers a price range facet and filters by sale price", () => {
+    const price = run().filters.find((f): f is FilterRange => f["@type"] === "FilterRange")!;
+    expect(price).toMatchObject({ key: "price", values: { min: 89.9, max: 189.9 } });
+    expect(run("?min_price=100&max_price=180").products.map((p) => p.offers!.lowPrice)).toEqual([
+      169.9,
+    ]);
+  });
+
+  it("skips products with no visible variants", () => {
+    const hidden = {
+      ...products[0],
+      variants: products[0].variants!.map((v) => ({ ...v, visible: false })),
+    };
+    const r = applyListing([hidden, products[2]], new URL(`${ORIGIN}/x`), {
+      origin: ORIGIN,
+      count: 24,
+    });
+    expect(r.products).toHaveLength(1);
+  });
+});
+
+describe("applyListing — sort", () => {
+  const ids = (qs: string) => run(qs).products.map((p) => p.offers!.lowPrice);
+  it("sorts in memory by price, name and discount; no sort keeps the API order", () => {
+    expect(ids("")).toEqual([189.9, 169.9, 89.9]);
+    expect(ids("?sort_by=price-ascending")).toEqual([89.9, 169.9, 189.9]);
+    expect(ids("?sort_by=price-descending")).toEqual([189.9, 169.9, 89.9]);
+    expect(run("?sort_by=alpha-ascending").products.map((p) => p.isVariantOf!.name)).toEqual([
+      "Camisa Flanela Montanha",
+      "Camisa Xadrez Lenhador Azul",
+      "Camiseta Gamer Preta Estampada",
+    ]);
+    expect(ids("?sort_by=discount-descending")[0]).toBe(169.9);
+  });
+  it("uses the theme's sort_by values so migrated links keep sorting", () => {
+    expect(run().sortOptions).toBe(SORT_OPTIONS);
+    expect(SORT_OPTIONS.map((o) => o.value)).toEqual([
+      "best-selling",
+      "price-ascending",
+      "price-descending",
+      "alpha-ascending",
+      "alpha-descending",
+      "created-descending",
+      "created-ascending",
+      "discount-descending",
+    ]);
+    const names = (qs: string) => run(qs).products.map((p) => p.isVariantOf!.name);
+    expect(names("?sort_by=alpha-descending")[0]).toBe("Camiseta Gamer Preta Estampada");
+    // created_at order (fixture products share a timestamp → stable API order)
+    expect(names("?sort_by=created-ascending")).toHaveLength(3);
+  });
+});
+
+describe("applyListing — default order and ties (theme parity)", () => {
+  const at = (p: NuvemshopProduct, created_at: string, price?: string) => ({
+    ...p,
+    created_at,
+    variants: p.variants!.map((v) => (price ? { ...v, price, promotional_price: null } : v)),
+  });
+  const older = at(products[0], "2026-01-01T00:00:00+0000", "100.00");
+  const newer = at(products[2], "2026-02-01T00:00:00+0000", "100.00");
+  const list = (qs: string, defaultSort?: string) =>
+    applyListing([older, newer], new URL(`${ORIGIN}/c/${qs}`), {
+      origin: ORIGIN,
+      count: 24,
+      defaultSort,
+    }).products.map((p) => p.isVariantOf!.productGroupID);
+
+  it("applies the configured default sort when there's no sort_by (or an unknown one, e.g. 'user')", () => {
+    expect(list("", "created-descending")).toEqual([String(newer.id), String(older.id)]);
+    expect(list("?sort_by=user", "created-descending")).toEqual([
+      String(newer.id),
+      String(older.id),
+    ]);
+    expect(list("")).toEqual([String(older.id), String(newer.id)]); // no default → API order
+  });
+
+  it("breaks price ties newest-first like the theme", () => {
+    expect(list("?sort_by=price-ascending")).toEqual([String(newer.id), String(older.id)]);
+    expect(list("?sort_by=price-descending")).toEqual([String(newer.id), String(older.id)]);
+  });
+});
+
+describe("applyListing — pagination", () => {
+  it("paginates the filtered set and links next/previous preserving filters", () => {
+    const p1 = run("?Cor=Azul+e+Preto", 1);
+    expect(p1.products).toHaveLength(1);
+    expect(p1.pageInfo).toEqual({
+      currentPage: 1,
+      records: 2,
+      recordPerPage: 1,
+      nextPage: "?Cor=Azul+e+Preto&page=2",
+      previousPage: undefined,
+    });
+    const p2 = run("?Cor=Azul+e+Preto&page=2", 1);
+    expect(p2.pageInfo).toMatchObject({
+      currentPage: 2,
+      nextPage: undefined,
+      previousPage: "?Cor=Azul+e+Preto&page=1",
+    });
+  });
+});

package/src/utils/__tests__/transform.test.ts

@@ -0,0 +1,212 @@
+import type { Product, ProductDetailsPage } from "@decocms/apps-commerce/types";
+import { describe, expect, expectTypeOf, it } from "vitest";
+import browseFixture from "../../__fixtures__/browse-category.json";
+import categoriesFixture from "../../__fixtures__/categories.json";
+import productFixture from "../../__fixtures__/product.json";
+import customFieldsFixture from "../../__fixtures__/product-custom-fields.json";
+import { pickVariant, toBreadcrumbList, toProduct, toProductPage } from "../transform";
+import type { NuvemshopCategory, NuvemshopList, NuvemshopProduct } from "../types";
+
+// Contract: the captured API responses must satisfy our API types. If the API
+// adds/renames a field in a breaking way, these assignments stop compiling.
+const raw: NuvemshopProduct = productFixture;
+const browse: NuvemshopList<NuvemshopProduct> = browseFixture;
+const categories: NuvemshopList<NuvemshopCategory> = categoriesFixture;
+const withCustomFields: NuvemshopProduct = customFieldsFixture;
+
+const ORIGIN = "https://loja.example";
+const IMG = "https://dcdn-us.mitiendanube.com/stores/008/336/778/products";
+
+describe("toProduct", () => {
+  it("maps a variant with no discount to the commerce Product shape", () => {
+    const product = toProduct(raw, raw.variants![0], { origin: ORIGIN });
+    expectTypeOf(product).toEqualTypeOf<Product>();
+
+    expect(product).toMatchObject({
+      "@type": "Product",
+      productID: "1612648502",
+      sku: "1612648502",
+      name: "P / Azul e Preto",
+      url: `${ORIGIN}/produtos/camisa-xadrez-lenhador-azul?variant=1612648502`,
+      category: "Camisas",
+      additionalProperty: [
+        { "@type": "PropertyValue", name: "Tamanho", value: "P", valueReference: "SPECIFICATION" },
+        {
+          "@type": "PropertyValue",
+          name: "Cor",
+          value: "Azul e Preto",
+          valueReference: "SPECIFICATION",
+        },
+      ],
+      image: [
+        {
+          "@type": "ImageObject",
+          url: `${IMG}/1-0dc6e3225f75c6be6617912360695512-1024-1024.webp`,
+          alternateName: "Camisa Xadrez Lenhador Azul",
+        },
+        {
+          "@type": "ImageObject",
+          url: `${IMG}/2-c444e295855213e1e117912360699859-1024-1024.webp`,
+          alternateName: "Camisa Xadrez Lenhador Azul",
+        },
+      ],
+      offers: {
+        "@type": "AggregateOffer",
+        priceCurrency: "BRL",
+        lowPrice: 189.9,
+        highPrice: 189.9,
+        offerCount: 1,
+        offers: [
+          {
+            "@type": "Offer",
+            sku: "MD001-1-P",
+            price: 189.9,
+            availability: "https://schema.org/InStock",
+            inventoryLevel: { value: 17 },
+            priceSpecification: [
+              {
+                "@type": "UnitPriceSpecification",
+                priceType: "https://schema.org/ListPrice",
+                price: 189.9,
+              },
+              {
+                "@type": "UnitPriceSpecification",
+                priceType: "https://schema.org/SalePrice",
+                price: 189.9,
+              },
+            ],
+          },
+        ],
+      },
+      isVariantOf: {
+        "@type": "ProductGroup",
+        productGroupID: "372190453",
+        name: "Camisa Xadrez Lenhador Azul",
+        url: `${ORIGIN}/produtos/camisa-xadrez-lenhador-azul`,
+      },
+    });
+    expect(product.isVariantOf!.hasVariant).toHaveLength(8);
+    expect(product.isVariantOf!.hasVariant[4].name).toBe("P / Vermelho e Preto");
+  });
+
+  it("uses promotional_price as the sale price and compare_at as the list price", () => {
+    const flanela = browse.data[1];
+    const product = toProduct(flanela, flanela.variants![0], { origin: ORIGIN });
+    expect(product.offers).toMatchObject({ lowPrice: 169.9, highPrice: 199.9 });
+    expect(product.offers!.offers[0].price).toBe(169.9);
+    expect(product.offers!.offers[0].priceSpecification).toEqual([
+      {
+        "@type": "UnitPriceSpecification",
+        priceType: "https://schema.org/ListPrice",
+        price: 199.9,
+      },
+      {
+        "@type": "UnitPriceSpecification",
+        priceType: "https://schema.org/SalePrice",
+        price: 169.9,
+      },
+    ]);
+  });
+
+  it("puts the variant's own image first", () => {
+    const flanela = browse.data[1];
+    const cinza = flanela.variants!.find((v) => v.values[1] === "Cinza")!;
+    const product = toProduct(flanela, cinza, { origin: ORIGIN });
+    expect(product.image![0].url).toBe(flanela.images!.find((i) => i.id === cinza.image_id)!.src);
+    expect(product.image).toHaveLength(flanela.images!.length);
+  });
+
+  it("derives availability from stock_management/stock (null stock = unlimited)", () => {
+    const v = raw.variants![0];
+    const at = (patch: Partial<typeof v>) =>
+      toProduct(raw, { ...v, ...patch }, { origin: ORIGIN }).offers!.offers[0].availability;
+    expect(at({ stock: 0 })).toBe("https://schema.org/OutOfStock");
+    expect(at({ stock: null })).toBe("https://schema.org/InStock");
+    expect(at({ stock: 0, stock_management: false })).toBe("https://schema.org/InStock");
+  });
+
+  it("never leaks the variant cost price", () => {
+    const leaky = { ...raw.variants![0], cost: "42.00" };
+    expect(
+      JSON.stringify(toProduct({ ...raw, variants: [leaky] }, leaky, { origin: ORIGIN })),
+    ).not.toContain("42");
+  });
+
+  it("exposes brand, gtin and custom fields", () => {
+    const product = toProduct(withCustomFields, withCustomFields.variants![0], { origin: ORIGIN });
+    expect(product.brand).toEqual({ "@type": "Brand", name: "ACME" });
+    expect(product.gtin).toBeUndefined(); // barcode: null upstream
+    const v = { ...withCustomFields.variants![0], barcode: "7798446191071" };
+    expect(toProduct(withCustomFields, v, { origin: ORIGIN }).gtin).toBe("7798446191071");
+    expect(product.isVariantOf!.additionalProperty).toContainEqual({
+      "@type": "PropertyValue",
+      name: "manual",
+      value: "https://files.example.com/manuals/ergonomic-chair-freedom-pt.pdf",
+      valueReference: "CUSTOM_FIELD",
+    });
+  });
+
+  it("flags free shipping (the theme's shipping label) only when the product has it", () => {
+    const flag = (free_shipping: boolean) =>
+      toProduct({ ...raw, free_shipping }, raw.variants![0], {
+        origin: ORIGIN,
+      }).isVariantOf!.additionalProperty.filter((p) => p.valueReference === "SHIPPING");
+    expect(flag(true)).toEqual([
+      { "@type": "PropertyValue", name: "freeShipping", value: "true", valueReference: "SHIPPING" },
+    ]);
+    expect(flag(false)).toEqual([]);
+  });
+
+  it("honours a configured currency", () => {
+    expect(
+      toProduct(raw, raw.variants![0], { origin: ORIGIN, currency: "ARS" }).offers!.priceCurrency,
+    ).toBe("ARS");
+  });
+});
+
+describe("pickVariant", () => {
+  it("selects by ?variant= and falls back to the first available variant", () => {
+    const v = raw.variants!;
+    expect(pickVariant(raw, "1612648511").id).toBe(1612648511);
+    expect(pickVariant(raw, "nope").id).toBe(v[0].id);
+    const firstOut = { ...raw, variants: [{ ...v[0], stock: 0 }, v[1]] };
+    expect(pickVariant(firstOut).id).toBe(v[1].id);
+  });
+});
+
+describe("toBreadcrumbList", () => {
+  it("walks the category tree from root to leaf", () => {
+    const masculino = categories.data.find((c) => c.handle === "masculino")!;
+    expect(toBreadcrumbList(masculino, categories.data, ORIGIN)).toEqual({
+      "@type": "BreadcrumbList",
+      numberOfItems: 2,
+      itemListElement: [
+        { "@type": "ListItem", name: "Calçados", item: `${ORIGIN}/calcados`, position: 1 },
+        {
+          "@type": "ListItem",
+          name: "Masculino",
+          item: `${ORIGIN}/calcados/masculino`,
+          position: 2,
+        },
+      ],
+    });
+  });
+});
+
+describe("toProductPage", () => {
+  it("builds a PDP with breadcrumb ending on the product and SEO fallbacks", () => {
+    const page = toProductPage(raw, { origin: ORIGIN, variantId: "1612648503" });
+    expectTypeOf(page).toEqualTypeOf<ProductDetailsPage>();
+    expect(page.product.productID).toBe("1612648503");
+    expect(page.breadcrumbList.itemListElement.map((i) => i.name)).toEqual([
+      "Camisas",
+      "Camisa Xadrez Lenhador Azul",
+    ]);
+    expect(page.seo).toEqual({
+      title: "Camisa Xadrez Lenhador Azul",
+      description: expect.stringMatching(/^Camisa xadrez de flanela macia/),
+      canonical: `${ORIGIN}/produtos/camisa-xadrez-lenhador-azul`,
+    });
+    expect(page.seo!.description).not.toMatch(/<\w+/);
+  });
+});

package/src/utils/instrumentedFetch.ts

@@ -0,0 +1,40 @@
+/**
+ * Pre-wired instrumented fetch for Nuvemshop — mirrors the Magento/Shopify
+ * factories: spans + `http.client.request.duration` with
+ * `provider: "nuvemshop"`. It is the client's default transport (like
+ * Salesforce), so sites get instrumentation without calling
+ * `setNuvemshopFetch`. SWR hit/miss is emitted by `createFetchCache`.
+ */
+
+import type { FetchFn } from "@decocms/blocks/sdk/fetchTimeout";
+import {
+  createInstrumentedFetch,
+  type InstrumentedFetch,
+} from "@decocms/blocks/sdk/instrumentedFetch";
+import { recordCommerceMetric, statusClassFor } from "@decocms/blocks/sdk/observability";
+import { nuvemshopOperationRouter } from "./operationRouter";
+
+export interface CreateNuvemshopFetchOptions {
+  /** Underlying fetch to wrap. Defaults to `globalThis.fetch`. */
+  baseFetch?: FetchFn;
+  /** Disable the duration histogram (spans/logs still emit). Default: false. */
+  disableHistogram?: boolean;
+}
+
+export function createNuvemshopFetch(options: CreateNuvemshopFetchOptions = {}): InstrumentedFetch {
+  const { baseFetch, disableHistogram = false } = options;
+  return createInstrumentedFetch({
+    name: "nuvemshop",
+    baseFetch,
+    resolveOperation: nuvemshopOperationRouter,
+    onComplete: disableHistogram
+      ? undefined
+      : (r) =>
+          recordCommerceMetric(r.durationMs, {
+            provider: "nuvemshop",
+            operation: r.operation,
+            status_class: statusClassFor(r.status),
+            cached: r.cached,
+          }),
+  });
+}

package/src/utils/listing.ts

@@ -0,0 +1,183 @@
+/**
+ * In-memory PLP: facets, sort and pagination over a window of products.
+ *
+ * The Storefront API (v2026-11) has no facets and only three sorts, while the
+ * Nuvemshop core already filters by variant values and price. Until the API
+ * exposes those, we fetch a window of products and compute everything here.
+ * URL params mirror the core theme (`?Cor=Vermelho|Preto&min_price=100`, values
+ * OR-ed with "|") so links keep working after a migration.
+ *
+ * ponytail: correct only while the category/search fits in one API page
+ * (≤200 products, `LISTING_WINDOW`). Switch to native API facets when they ship.
+ */
+import type { Filter, PageInfo, Product, SortOption } from "@decocms/apps-commerce/types";
+import { isAvailable, type TransformOptions, toProduct, variantPrices } from "./transform";
+import type { NuvemshopProduct, NuvemshopVariant } from "./types";
+
+export const LISTING_WINDOW = 200;
+
+/**
+ * The theme's `sort_by` values (so `?sort_by=alpha-ascending` links keep
+ * working), plus `discount-descending`, which the core doesn't offer.
+ * The theme's "user" (merchant's manual order) isn't in the API, so it's not
+ * offered; `?sort_by=user` falls back to the default sort.
+ */
+export const SORT_OPTIONS: SortOption[] = [
+  { value: "best-selling", label: "Mais vendidos" },
+  { value: "price-ascending", label: "Menor preço" },
+  { value: "price-descending", label: "Maior preço" },
+  { value: "alpha-ascending", label: "A - Z" },
+  { value: "alpha-descending", label: "Z - A" },
+  { value: "created-descending", label: "Mais recentes" },
+  { value: "created-ascending", label: "Mais antigos" },
+  { value: "discount-descending", label: "Maior desconto" },
+];
+
+export const SORT_PARAM = "sort_by";
+
+type Selection = Map<string, Set<string>>;
+
+/** The theme joins multiple values of one filter with "|" (`?Cor=Vermelho|Preto`). */
+const VALUE_SEPARATOR = "|";
+const valuesOf = (params: URLSearchParams, attr: string) =>
+  (params.get(attr) ?? "").split(VALUE_SEPARATOR).filter(Boolean);
+
+const visibleVariants = (p: NuvemshopProduct) =>
+  (p.variants ?? []).filter((v) => v.visible !== false);
+const minPrice = (p: NuvemshopProduct) =>
+  Math.min(...visibleVariants(p).map((v) => variantPrices(v).price));
+const maxDiscount = (p: NuvemshopProduct) =>
+  Math.max(
+    ...visibleVariants(p).map((v) => {
+      const { price, listPrice } = variantPrices(v);
+      return listPrice ? (listPrice - price) / listPrice : 0;
+    }),
+  );
+
+function variantMatches(p: NuvemshopProduct, v: NuvemshopVariant, sel: Selection, skip?: string) {
+  const attrs = p.attributes ?? [];
+  for (const [attr, values] of sel) {
+    if (attr === skip) continue;
+    const i = attrs.indexOf(attr);
+    if (i < 0 || !values.has(v.values[i])) return false;
+  }
+  return true;
+}
+
+const matchingVariants = (p: NuvemshopProduct, sel: Selection, skip?: string) =>
+  visibleVariants(p).filter((v) => variantMatches(p, v, sel, skip));
+
+type Compare = (a: NuvemshopProduct, b: NuvemshopProduct) => number;
+
+/** Newest first; created_at has second precision, so ids break same-second ties. */
+const newest: Compare = (a, b) =>
+  (b.created_at ?? "").localeCompare(a.created_at ?? "") || b.id - a.id;
+
+// Ties fall back to newest-first, as in the theme.
+const sorters: Record<string, Compare> = {
+  "price-ascending": (a, b) => minPrice(a) - minPrice(b) || newest(a, b),
+  "price-descending": (a, b) => minPrice(b) - minPrice(a) || newest(a, b),
+  "discount-descending": (a, b) => maxDiscount(b) - maxDiscount(a) || newest(a, b),
+  "alpha-ascending": (a, b) => a.name.localeCompare(b.name) || newest(a, b),
+  "alpha-descending": (a, b) => b.name.localeCompare(a.name) || newest(a, b),
+  "created-descending": newest,
+  "created-ascending": (a, b) => -newest(a, b),
+};
+
+function withParams(url: URL, mutate: (p: URLSearchParams) => void) {
+  const next = new URL(url);
+  next.searchParams.delete("page");
+  mutate(next.searchParams);
+  return next.toString();
+}
+
+export interface ListingOptions extends TransformOptions {
+  /** Products per page. */
+  count: number;
+  /** Sort applied without (or with an unknown) `sort_by`. Unset = keep the API order (search relevance). */
+  defaultSort?: string;
+}
+
+export function applyListing(source: NuvemshopProduct[], url: URL, opts: ListingOptions) {
+  const products = source.filter((p) => visibleVariants(p).length > 0);
+  const attributes = [...new Set(products.flatMap((p) => p.attributes ?? []))];
+
+  const sel: Selection = new Map();
+  for (const attr of attributes) {
+    const values = valuesOf(url.searchParams, attr);
+    if (values.length) sel.set(attr, new Set(values));
+  }
+  const lo = Number(url.searchParams.get("min_price") ?? Number.NEGATIVE_INFINITY);
+  const hi = Number(url.searchParams.get("max_price") ?? Number.POSITIVE_INFINITY);
+  const inPrice = (p: NuvemshopProduct) => minPrice(p) >= lo && minPrice(p) <= hi;
+
+  const filtered = products.filter((p) => inPrice(p) && matchingVariants(p, sel).length > 0);
+  const sorter = sorters[url.searchParams.get(SORT_PARAM) ?? ""] ?? sorters[opts.defaultSort ?? ""];
+  if (sorter) filtered.sort(sorter);
+
+  // Facet counts ignore their own attribute's selection (standard facet UX).
+  const filters: Filter[] = attributes.map((attr) => {
+    const counts = new Map<string, number>();
+    for (const p of products) {
+      if (!inPrice(p)) continue;
+      const i = (p.attributes ?? []).indexOf(attr);
+      if (i < 0) continue;
+      for (const value of new Set(matchingVariants(p, sel, attr).map((v) => v.values[i]))) {
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+      }
+    }
+    const selected = sel.get(attr) ?? new Set<string>();
+    return {
+      "@type": "FilterToggle",
+      key: attr,
+      label: attr,
+      quantity: counts.size,
+      values: [...counts].map(([value, quantity]) => ({
+        value,
+        label: value,
+        quantity,
+        selected: selected.has(value),
+        url: withParams(url, (p) => {
+          const rest = valuesOf(p, attr).filter((v) => v !== value);
+          const next = selected.has(value) ? rest : [...rest, value];
+          if (next.length) p.set(attr, next.join(VALUE_SEPARATOR));
+          else p.delete(attr);
+        }),
+      })),
+    };
+  });
+  if (products.length) {
+    const prices = products.map(minPrice);
+    filters.push({
+      "@type": "FilterRange",
+      key: "price",
+      label: "Preço",
+      values: { min: Math.min(...prices), max: Math.max(...prices) },
+    });
+  }
+
+  const page = Math.max(1, Number(url.searchParams.get("page")) || 1);
+  const start = (page - 1) * opts.count;
+  const pageLink = (n: number) => {
+    const p = new URLSearchParams(url.search);
+    p.set("page", String(n));
+    return `?${p}`;
+  };
+  const pageInfo: PageInfo = {
+    currentPage: page,
+    records: filtered.length,
+    recordPerPage: opts.count,
+    nextPage: start + opts.count < filtered.length ? pageLink(page + 1) : undefined,
+    previousPage: page > 1 ? pageLink(page - 1) : undefined,
+  };
+
+  return {
+    products: filtered.slice(start, start + opts.count).map((p): Product => {
+      const matches = matchingVariants(p, sel);
+      return toProduct(p, matches.find(isAvailable) ?? matches[0], opts);
+    }),
+    filters,
+    pageInfo,
+    sortOptions: SORT_OPTIONS,
+  };
+}

package/src/utils/operationRouter.ts

@@ -0,0 +1,21 @@
+/**
+ * URL → operation name for Nuvemshop Storefront API calls, plugged into
+ * `createInstrumentedFetch`'s `resolveOperation`. Returns `undefined` when
+ * nothing matches so the framework falls back to `nuvemshop.fetch`.
+ */
+import { extractPathname } from "@decocms/blocks/sdk/urlUtils";
+
+const MATCHERS: ReadonlyArray<[RegExp, string]> = [
+  [/\/stores\/\d+\/search\/products\/?$/, "products.search"],
+  [/\/stores\/\d+\/products\/?$/, "products.browse"],
+  [/\/stores\/\d+\/products\/[^/]+\/?$/, "products.get"],
+  [/\/stores\/\d+\/categories\/?$/, "categories.list"],
+  [/\/stores\/\d+\/categories\/[^/]+\/?$/, "categories.get"],
+  [/\/stores\/\d+\/shipping-options\/?$/, "shipping.options"],
+  [/\/stores\/\d+\/checkouts\/?$/, "checkout.create"],
+];
+
+export function nuvemshopOperationRouter(url: string, _method: string): string | undefined {
+  const pathname = extractPathname(url);
+  return MATCHERS.find(([pattern]) => pattern.test(pathname))?.[1];
+}

package/src/utils/request.ts

@@ -0,0 +1,17 @@
+/** Page props injected by the CMS resolver (`resolve.ts`) into commerce loaders. */
+export interface PageProps {
+  /** @ignore */
+  __pageUrl?: string;
+  /** @ignore */
+  __pagePath?: string;
+}
+
+/** The storefront URL being rendered: CMS-injected page URL, else the invoke request. */
+export const pageUrlOf = (props: PageProps, req?: Request) =>
+  new URL(props.__pageUrl ?? req?.url ?? "https://localhost/", "https://localhost");
+
+/** Absolute origin for product URLs; empty (relative URLs) when unknown. */
+export const originOf = (props: PageProps, req?: Request) => {
+  const url = pageUrlOf(props, req);
+  return url.hostname === "localhost" && !props.__pageUrl && !req ? "" : url.origin;
+};