@decocms/apps-nuvemshop 7.74.1

package/src/__tests__/client.test.ts

@@ -0,0 +1,118 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import productFixture from "../__fixtures__/product.json";
+import {
+  CATEGORY_FIELDS,
+  clearNuvemshopCache,
+  configureNuvemshop,
+  nuvemshopGet,
+  nuvemshopPost,
+  PRODUCT_FIELDS,
+  setNuvemshopFetch,
+} from "../client";
+
+const API = "https://storefront-api.tiendanube.com/v2026-11/stores/8336778";
+
+function mockFetch(body: unknown = productFixture, status = 200) {
+  const fn = vi.fn(
+    async (_url: string | URL | Request, _init?: RequestInit) =>
+      new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json" },
+      }),
+  );
+  setNuvemshopFetch(fn as unknown as typeof fetch);
+  return fn;
+}
+const call = (fn: ReturnType<typeof mockFetch>, i = 0) => ({
+  url: new URL(String(fn.mock.calls[i][0])),
+  headers: new Headers(fn.mock.calls[i][1]?.headers),
+  init: fn.mock.calls[i][1],
+});
+
+beforeEach(() => {
+  clearNuvemshopCache();
+  configureNuvemshop({ storeId: "8336778" });
+});
+
+describe("nuvemshopGet", () => {
+  it("targets the versioned store URL and passes params through", async () => {
+    const fn = mockFetch();
+    await nuvemshopGet("/products", { category_id: 41376194, page: 2, ids: undefined });
+    const { url } = call(fn);
+    expect(`${url.origin}${url.pathname}`).toBe(`${API}/products`);
+    expect(url.searchParams.get("category_id")).toBe("41376194");
+    expect(url.searchParams.get("page")).toBe("2");
+    expect(url.searchParams.has("ids")).toBe(false);
+  });
+
+  it("always asks for the full product field set on product routes", async () => {
+    const fn = mockFetch();
+    await nuvemshopGet("/products/camisa");
+    await nuvemshopGet("/search/products", { q: "x" });
+    expect(call(fn, 0).url.searchParams.get("fields")).toBe(PRODUCT_FIELDS);
+    expect(call(fn, 1).url.searchParams.get("fields")).toBe(PRODUCT_FIELDS);
+    expect(PRODUCT_FIELDS.split(",")).toEqual(
+      expect.arrayContaining(["variants", "images", "attributes"]),
+    );
+    expect(PRODUCT_FIELDS).not.toContain("cost");
+  });
+
+  it("asks for parent/subcategories on category routes (the default selection omits them)", async () => {
+    const fn = mockFetch();
+    await nuvemshopGet("/categories", { per_page: 200 });
+    await nuvemshopGet("/categories/calcados");
+    for (const i of [0, 1]) {
+      expect(call(fn, i).url.searchParams.get("fields")).toBe(CATEGORY_FIELDS);
+    }
+    expect(CATEGORY_FIELDS.split(",")).toEqual(expect.arrayContaining(["parent", "subcategories"]));
+  });
+
+  it("is tokenless by default and sends a bearer token when configured", async () => {
+    const fn = mockFetch();
+    await nuvemshopGet("/categories");
+    expect(call(fn).headers.has("authorization")).toBe(false);
+
+    configureNuvemshop({ storeId: "8336778", token: "secret" });
+    await nuvemshopGet("/categories", { page: 2 }); // same URL would be a cache hit
+    expect(call(fn, 1).headers.get("authorization")).toBe("Bearer secret");
+    expect(call(fn, 1).headers.has("x-linkedstore-buyer-ip")).toBe(false);
+  });
+
+  it("dedups identical GETs through the SWR cache", async () => {
+    const fn = mockFetch();
+    await Promise.all([nuvemshopGet("/products/a"), nuvemshopGet("/products/a")]);
+    await nuvemshopGet("/products/a");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns null on 404", async () => {
+    mockFetch({ error: { code: "resource_not_found", message: "nope" } }, 404);
+    expect(await nuvemshopGet("/products/missing")).toBeNull();
+  });
+
+  it("throws when not configured", async () => {
+    configureNuvemshop(null);
+    await expect(nuvemshopGet("/products")).rejects.toThrow(/not configured/);
+  });
+});
+
+describe("nuvemshopPost", () => {
+  it("posts JSON and forwards the buyer IP only with a token", async () => {
+    const fn = mockFetch({ checkout_url: "https://x" });
+    await nuvemshopPost("/checkouts", { line_items: [] }, { buyerIp: "203.0.113.10" });
+    expect(call(fn).init?.method).toBe("POST");
+    expect(call(fn).headers.has("x-linkedstore-buyer-ip")).toBe(false);
+
+    configureNuvemshop({ storeId: "8336778", token: "secret" });
+    await nuvemshopPost("/checkouts", { line_items: [] }, { buyerIp: "203.0.113.10" });
+    expect(call(fn, 1).headers.get("x-linkedstore-buyer-ip")).toBe("203.0.113.10");
+    expect(JSON.parse(String(call(fn, 1).init?.body))).toEqual({ line_items: [] });
+  });
+
+  it("surfaces the API error message", async () => {
+    mockFetch({ error: { code: "invalid_body", message: "The request body is invalid." } }, 400);
+    await expect(nuvemshopPost("/checkouts", {})).rejects.toThrow(
+      /invalid_body.*The request body is invalid/,
+    );
+  });
+});

package/src/__tests__/loaders.test.ts

@@ -0,0 +1,220 @@
+import type { ProductListingPage } from "@decocms/apps-commerce/types";
+import { beforeEach, describe, expect, expectTypeOf, it, vi } from "vitest";
+import browseFixture from "../__fixtures__/browse-category.json";
+import categoriesFixture from "../__fixtures__/categories.json";
+import checkoutFixture from "../__fixtures__/checkout.json";
+import productFixture from "../__fixtures__/product.json";
+import searchFixture from "../__fixtures__/search.json";
+import shippingFixture from "../__fixtures__/shipping-options.json";
+import createCheckout from "../actions/createCheckout";
+import { clearNuvemshopCache, configureNuvemshop, setNuvemshopFetch } from "../client";
+import categories from "../loaders/categories";
+import productDetailsPage from "../loaders/productDetailsPage";
+import productList from "../loaders/productList";
+import productListingPage from "../loaders/productListingPage";
+import relatedProducts from "../loaders/relatedProducts";
+import shippingOptions from "../loaders/shippingOptions";
+import suggestions from "../loaders/suggestions";
+
+const SITE = "https://loja.example";
+const notFound = { error: { code: "resource_not_found", message: "not found" } };
+const camisas = categoriesFixture.data.find((c) => c.handle === "camisas")!;
+
+const json = (body: unknown, status = 200) =>
+  new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+
+// Routes requests to the captured fixtures, like the real API would.
+const fetchMock = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
+  const url = new URL(String(input));
+  const path = url.pathname.replace(/^\/v2026-11\/stores\/8336778/, "");
+  if (init?.method === "POST") {
+    if (path === "/checkouts") return json(checkoutFixture);
+    if (path === "/shipping-options") return json(shippingFixture);
+  }
+  if (path === "/search/products") return json(searchFixture);
+  if (path === "/products") return json(browseFixture);
+  if (path === "/products/camisa-xadrez-lenhador-azul") return json(productFixture);
+  if (path === "/categories") return json(categoriesFixture);
+  if (path === "/categories/camisas" || path === `/categories/${camisas.id}`) return json(camisas);
+  return json(notFound, 404);
+});
+const lastUrl = (pathEnd: string) =>
+  new URL(
+    String(
+      fetchMock.mock.calls
+        .map((c) => c[0])
+        .reverse()
+        .find((u) => new URL(String(u)).pathname.endsWith(pathEnd)),
+    ),
+  );
+
+beforeEach(() => {
+  fetchMock.mockClear();
+  clearNuvemshopCache();
+  configureNuvemshop({ storeId: "8336778" });
+  setNuvemshopFetch(fetchMock as unknown as typeof fetch);
+});
+
+describe("productListingPage", () => {
+  it("resolves the category from the URL path and returns a PLP", async () => {
+    const plp = await productListingPage({
+      __pageUrl: `${SITE}/camisas/?Cor=Cinza`,
+      __pagePath: "/camisas/",
+    });
+    expectTypeOf(plp).toEqualTypeOf<ProductListingPage | null>();
+    expect(lastUrl("/products").searchParams.get("category_id")).toBe(String(camisas.id));
+    expect(lastUrl("/products").searchParams.get("per_page")).toBe("200");
+    expect(plp!.products).toHaveLength(1);
+    expect(plp!.breadcrumb.itemListElement).toEqual([
+      { "@type": "ListItem", name: "Camisas", item: `${SITE}/camisas`, position: 1 },
+    ]);
+    expect(plp!.pageInfo.pageTypes).toEqual(["Category"]);
+    expect(plp!.seo).toMatchObject({ title: "Camisas", canonical: `${SITE}/camisas` });
+  });
+
+  it("asks the API for best-selling order (the only sort it must do itself)", async () => {
+    await productListingPage({ __pageUrl: `${SITE}/camisas/?sort_by=best-selling` });
+    expect(lastUrl("/products").searchParams.get("sort_by")).toBe("best-selling");
+    await productListingPage({ __pageUrl: `${SITE}/camisas/?sort_by=price-ascending` });
+    expect(lastUrl("/products").searchParams.has("sort_by")).toBe(false);
+  });
+
+  it("searches when there's a term", async () => {
+    const plp = await productListingPage({ __pageUrl: `${SITE}/search/?q=vestido` });
+    expect(lastUrl("/search/products").searchParams.get("q")).toBe("vestido");
+    expect(plp!.products).toHaveLength(searchFixture.data.length);
+    expect(plp!.pageInfo.pageTypes).toEqual(["Search"]);
+    // /search/products takes no sort_by, so best-selling can't be honoured there
+    expect(plp!.sortOptions.map((o) => o.value)).not.toContain("best-selling");
+    expect(plp!.sortOptions[0]).toEqual({ value: "relevance", label: "Relevância" });
+    expect(lastUrl("/search/products").searchParams.has("sort_by")).toBe(false);
+  });
+
+  it("accepts a CMS-pinned categoryId and returns null for unknown categories", async () => {
+    expect(
+      await productListingPage({ categoryId: camisas.id, __pageUrl: `${SITE}/qualquer/` }),
+    ).not.toBeNull();
+    expect(await productListingPage({ __pageUrl: `${SITE}/nao-existe/` })).toBeNull();
+  });
+});
+
+describe("productDetailsPage", () => {
+  it("loads by slug and honours ?variant=", async () => {
+    const pdp = await productDetailsPage({
+      slug: "camisa-xadrez-lenhador-azul",
+      __pageUrl: `${SITE}/produtos/camisa-xadrez-lenhador-azul/?variant=1612648511`,
+    });
+    expect(pdp!.product.productID).toBe("1612648511");
+    expect(pdp!.product.url).toBe(
+      `${SITE}/produtos/camisa-xadrez-lenhador-azul?variant=1612648511`,
+    );
+  });
+
+  it("derives the slug from a /produtos/<handle>/ path and 404s cleanly", async () => {
+    const pdp = await productDetailsPage({
+      __pageUrl: `${SITE}/produtos/camisa-xadrez-lenhador-azul/`,
+    });
+    expect(pdp!.product.isVariantOf!.productGroupID).toBe("372190453");
+    expect(await productDetailsPage({ slug: "nope" })).toBeNull();
+  });
+});
+
+describe("productList", () => {
+  it("lists by category with an API sort and count", async () => {
+    const list = await productList({ categoryId: camisas.id, sort: "price-ascending", count: 2 });
+    const url = lastUrl("/products");
+    expect(url.searchParams.get("sort_by")).toBe("price-ascending");
+    expect(url.searchParams.get("per_page")).toBe("2");
+    expect(list.length).toBeGreaterThan(0);
+  });
+
+  it("lists by ids/handles without sort_by (the API rejects the combination)", async () => {
+    await productList({ ids: [372190453, 372190471], sort: "best-selling" });
+    const url = lastUrl("/products");
+    expect(url.searchParams.get("ids")).toBe("372190453,372190471");
+    expect(url.searchParams.has("sort_by")).toBe(false);
+  });
+
+  it("searches by term", async () => {
+    await productList({ query: "vestido", count: 4 });
+    expect(lastUrl("/search/products").searchParams.get("q")).toBe("vestido");
+  });
+});
+
+describe("relatedProducts", () => {
+  it("follows the theme: same category, without the product itself, in-stock first", async () => {
+    const outOfStock = {
+      ...browseFixture.data[1],
+      variants: browseFixture.data[1].variants.map((v) => ({ ...v, stock: 0 })),
+    };
+    fetchMock
+      .mockImplementationOnce(async () => json(productFixture))
+      .mockImplementationOnce(async () =>
+        json({
+          ...browseFixture,
+          data: [browseFixture.data[0], outOfStock, browseFixture.data[2]],
+        }),
+      );
+    const related = await relatedProducts({ slug: "camisa-xadrez-lenhador-azul" });
+    expect(lastUrl("/products").searchParams.get("category_id")).toBe(String(camisas.id));
+    expect(related.map((p) => p.isVariantOf!.productGroupID)).toEqual([
+      String(browseFixture.data[2].id), // in stock
+      String(outOfStock.id), // refill with out-of-stock
+    ]);
+  });
+
+  it("caps at count and returns [] for an unknown product", async () => {
+    expect(await relatedProducts({ slug: "camisa-xadrez-lenhador-azul", count: 1 })).toHaveLength(
+      1,
+    );
+    expect(await relatedProducts({ slug: "nope" })).toEqual([]);
+  });
+});
+
+describe("suggestions", () => {
+  it("returns products for the term and nothing for a blank one", async () => {
+    const s = await suggestions({ query: "vestido", count: 2 });
+    expect(s!.products).toHaveLength(2);
+    expect(await suggestions({ query: " " })).toBeNull();
+  });
+});
+
+describe("categories", () => {
+  it("builds a navigation tree with nested URLs", async () => {
+    const tree = await categories({}, new Request(`${SITE}/`));
+    const calcados = tree.find((c) => c.name === "Calçados")!;
+    expect(calcados.url).toBe(`${SITE}/calcados`);
+    expect(calcados.children!.map((c) => c.url)).toEqual([
+      `${SITE}/calcados/masculino`,
+      `${SITE}/calcados/feminino`,
+    ]);
+    expect(tree.some((c) => c.name === "Masculino")).toBe(false);
+  });
+});
+
+describe("shippingOptions", () => {
+  it("quotes one variant for a CEP with numeric prices", async () => {
+    const options = await shippingOptions({ zipCode: "01310-100", variantId: 1612648502 });
+    expect(options[0]).toMatchObject({ code: "table_default_123123", price: 0 });
+  });
+});
+
+describe("createCheckout", () => {
+  it("maps cart items to line_items and returns the hosted checkout URL", async () => {
+    const res = await createCheckout({
+      items: [{ productId: 372190453, variantId: 1612648502, quantity: 2 }],
+      coupon: " TEST ",
+    });
+    expect(res.checkoutUrl).toBe(checkoutFixture.checkout_url);
+    const body = JSON.parse(String(fetchMock.mock.calls.at(-1)![1]!.body));
+    expect(body).toEqual({
+      line_items: [{ product_id: 372190453, variant_id: 1612648502, quantity: 2 }],
+      coupon_code: "TEST",
+    });
+  });
+
+  it("rejects an empty cart without calling the API", async () => {
+    await expect(createCheckout({ items: [] })).rejects.toThrow(/empty/);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/mod.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { getNuvemshopConfig } from "../client";
+import { configure } from "../mod";
+import { nuvemshopOperationRouter } from "../utils/operationRouter";
+
+const noSecret = async () => null;
+
+describe("configure", () => {
+  it("returns null without a numeric storeId", async () => {
+    expect(await configure({}, noSecret)).toBeNull();
+    expect(await configure({ storeId: "loja" }, noSecret)).toBeNull();
+  });
+
+  it("works tokenless and registers every manifest handler as a function", async () => {
+    const app = await configure({ storeId: 8336778 }, noSecret);
+    expect(app!.name).toBe("nuvemshop");
+    expect(getNuvemshopConfig()).toMatchObject({ storeId: "8336778", token: undefined });
+    for (const mod of [
+      ...Object.values(app!.manifest.loaders),
+      ...Object.values(app!.manifest.actions!),
+    ]) {
+      expect(typeof (mod as { default: unknown }).default).toBe("function");
+    }
+  });
+
+  it("resolves the token through the secret resolver (env fallback key)", async () => {
+    let envKey = "";
+    await configure({ storeId: "1", token: { encrypted: "x" } }, async (_v, key) => {
+      envKey = key;
+      return "tok";
+    });
+    expect(envKey).toBe("NUVEMSHOP_STOREFRONT_TOKEN");
+    expect(getNuvemshopConfig().token).toBe("tok");
+  });
+});
+
+describe("nuvemshopOperationRouter", () => {
+  const base = "https://storefront-api.tiendanube.com/v2026-11/stores/1";
+  it.each([
+    [`${base}/products?fields=id`, "products.browse"],
+    [`${base}/products/camisa`, "products.get"],
+    [`${base}/search/products?q=x`, "products.search"],
+    [`${base}/categories`, "categories.list"],
+    [`${base}/categories/calcados`, "categories.get"],
+    [`${base}/shipping-options`, "shipping.options"],
+    [`${base}/checkouts`, "checkout.create"],
+    ["https://example.com/other", undefined],
+  ])("%s → %s", (url, op) => {
+    expect(nuvemshopOperationRouter(url, "GET")).toBe(op);
+  });
+});

package/src/actions/createCheckout.ts

@@ -0,0 +1,36 @@
+import { nuvemshopPost } from "../client";
+import type { NuvemshopCheckout, NuvemshopLineItem } from "../utils/types";
+
+export interface CartItem {
+  productId: number;
+  variantId: number;
+  quantity: number;
+}
+
+export interface Props {
+  items: CartItem[];
+  coupon?: string;
+}
+
+/**
+ * @title Nuvemshop - Create Checkout
+ * @description Opens a Nuvemshop cart with the items (and coupon) and returns the hosted checkout URL.
+ */
+export default async function createCheckout(
+  props: Props,
+  req?: Request,
+): Promise<{ checkoutUrl: string }> {
+  if (!props.items?.length) throw new Error("Cannot checkout an empty cart");
+  const line_items: NuvemshopLineItem[] = props.items.map((i) => ({
+    product_id: i.productId,
+    variant_id: i.variantId,
+    quantity: i.quantity,
+  }));
+  const coupon_code = props.coupon?.trim() || undefined;
+  const res = await nuvemshopPost<NuvemshopCheckout>(
+    "/checkouts",
+    { line_items, coupon_code },
+    { buyerIp: req?.headers.get("cf-connecting-ip") },
+  );
+  return { checkoutUrl: res.checkout_url };
+}

package/src/client.ts

@@ -0,0 +1,165 @@
+/**
+ * Nuvemshop (Tiendanube) Storefront API client.
+ *
+ * REST over `https://storefront-api.tiendanube.com/<version>/stores/<id>`.
+ * Access is tokenless (120 req/min per store + client IP) or with a
+ * store-scoped bearer token (1,200 req/min per store). From a Worker every
+ * buyer shares the egress IP, so production stores should configure a token.
+ *
+ * - GETs go through the shared SWR cache (`createFetchCache`) keyed by URL.
+ * - POSTs forward the buyer IP (`X-LinkedStore-Buyer-IP`) when a token is
+ *   set, giving each buyer their own rate-limit bucket. Tokenless requests
+ *   ignore that header, so it's only sent with a token.
+ * - Transport defaults to the instrumented `createNuvemshopFetch()`.
+ */
+
+import { createFetchCache } from "@decocms/blocks/sdk/fetchCache";
+import type { FetchFn } from "@decocms/blocks/sdk/fetchTimeout";
+import { createNuvemshopFetch } from "./utils/instrumentedFetch";
+
+export interface NuvemshopConfig {
+  storeId: string;
+  /** Store-scoped Storefront token. Optional; recommended in production. */
+  token?: string;
+  /** Default "v2026-11". */
+  apiVersion?: string;
+  /** Default "https://storefront-api.tiendanube.com". */
+  baseUrl?: string;
+  /** Currency of the store's prices (the API doesn't return one). Default "BRL". */
+  currency?: string;
+  /**
+   * Category default sort (a theme `sort_by` value). The API doesn't expose a
+   * category's configured sort and returns oldest-first. Default "created-descending".
+   */
+  defaultSort?: string;
+}
+
+/**
+ * Root fields requested for every product. The API's default selection is
+ * only `id,name,handle`. `cost` is deliberately absent.
+ */
+export const PRODUCT_FIELDS = [
+  "id",
+  "name",
+  "handle",
+  "description",
+  "images",
+  "variants",
+  "brand",
+  "tags",
+  "categories",
+  "attributes",
+  "seo_title",
+  "seo_description",
+  "free_shipping",
+  "video_url",
+  "created_at",
+].join(",");
+
+/** The default category selection also lacks `parent`, which breaks trees and breadcrumbs. */
+export const CATEGORY_FIELDS =
+  "id,name,handle,parent,subcategories,description,seo_title,seo_description";
+
+const DEFAULT_FIELDS: [RegExp, string][] = [
+  [/^\/(search\/)?products(\/|$)/, PRODUCT_FIELDS],
+  [/^\/categories(\/|$)/, CATEGORY_FIELDS],
+];
+
+let _config: NuvemshopConfig | null = null;
+let _fetch: FetchFn | undefined;
+
+const cache = createFetchCache({
+  provider: "nuvemshop",
+  maxEntries: 500,
+  // Catalog doesn't need to be second-fresh; a just-published product shouldn't 404 long.
+  freshTtlMs: { success: 120_000, notFound: 10_000, serverError: 0 },
+  staleIfErrorMs: 86_400_000,
+  inflightBackstopMs: 15_000,
+});
+
+export function configureNuvemshop(config: NuvemshopConfig | null) {
+  _config = config;
+}
+
+export function getNuvemshopConfig(): NuvemshopConfig {
+  if (!_config)
+    throw new Error(
+      "Nuvemshop is not configured — add a deco-nuvemshop block or call configureNuvemshop()",
+    );
+  return _config;
+}
+
+/** Override the transport (tests, or a site wrapping its own fetch). */
+export function setNuvemshopFetch(fn: FetchFn) {
+  _fetch = fn;
+}
+
+export function clearNuvemshopCache() {
+  cache.clear();
+}
+
+const transport = () => (_fetch ??= createNuvemshopFetch() as FetchFn);
+
+function storeUrl(path: string, params: Record<string, string | number | undefined> = {}) {
+  const {
+    storeId,
+    apiVersion = "v2026-11",
+    baseUrl = "https://storefront-api.tiendanube.com",
+  } = getNuvemshopConfig();
+  const url = new URL(`${baseUrl}/${apiVersion}/stores/${storeId}${path}`);
+  const fields = DEFAULT_FIELDS.find(([route]) => route.test(path))?.[1];
+  if (fields && params.fields === undefined) params = { ...params, fields };
+  for (const [k, v] of Object.entries(params))
+    if (v !== undefined && v !== "") url.searchParams.set(k, String(v));
+  return url.toString();
+}
+
+function headers(extra?: Record<string, string>) {
+  const { token } = getNuvemshopConfig();
+  return {
+    accept: "application/json",
+    ...(token && { authorization: `Bearer ${token}` }),
+    ...extra,
+  };
+}
+
+async function errorFrom(res: Response) {
+  const body = (await res.json().catch(() => null)) as {
+    error?: { code?: string; message?: string };
+  } | null;
+  return new Error(
+    `Nuvemshop ${res.status} ${body?.error?.code ?? ""}: ${body?.error?.message ?? res.statusText}`,
+  );
+}
+
+/** Cached GET. Resolves `null` on 404 (and other cacheable non-2xx). */
+export function nuvemshopGet<T>(
+  path: string,
+  params?: Record<string, string | number | undefined>,
+): Promise<T | null> {
+  try {
+    const url = storeUrl(path, params);
+    return cache.fetchWithCache<T>(url, () => transport()(url, { headers: headers() }));
+  } catch (e) {
+    return Promise.reject(e);
+  }
+}
+
+export async function nuvemshopPost<T>(
+  path: string,
+  body: unknown,
+  opts: { buyerIp?: string | null } = {},
+): Promise<T> {
+  const url = storeUrl(path);
+  const { token } = getNuvemshopConfig();
+  const res = await transport()(url, {
+    method: "POST",
+    headers: headers({
+      "content-type": "application/json",
+      ...(token && opts.buyerIp && { "x-linkedstore-buyer-ip": opts.buyerIp }),
+    }),
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) throw await errorFrom(res);
+  return res.json() as Promise<T>;
+}

package/src/hooks/__tests__/useCart.test.ts

@@ -0,0 +1,81 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  addItem,
+  CART_STORAGE_KEY,
+  cartStore,
+  checkout,
+  removeItem,
+  setQuantity,
+} from "../useCart";
+
+const shirt = { productId: 1, variantId: 10, quantity: 1 };
+const pants = { productId: 2, variantId: 20, quantity: 1 };
+
+describe("cart reducers", () => {
+  it("adds, merges quantities and caps at 99 (API limit per variant)", () => {
+    expect(addItem([], shirt)).toEqual([shirt]);
+    expect(addItem([shirt], { ...shirt, quantity: 2 })).toEqual([{ ...shirt, quantity: 3 }]);
+    expect(addItem([shirt], { ...shirt, quantity: 500 })[0].quantity).toBe(99);
+  });
+  it("sets quantity and drops the line at 0", () => {
+    expect(setQuantity([shirt, pants], 20, 4)).toEqual([shirt, { ...pants, quantity: 4 }]);
+    expect(setQuantity([shirt, pants], 10, 0)).toEqual([pants]);
+    expect(removeItem([shirt, pants], 10)).toEqual([pants]);
+  });
+});
+
+describe("cartStore", () => {
+  beforeEach(() => {
+    localStorage.clear();
+    cartStore.set([]);
+  });
+
+  it("persists to localStorage and notifies subscribers", () => {
+    const seen = vi.fn();
+    const off = cartStore.subscribe(seen);
+    cartStore.update((items) => addItem(items, shirt));
+    expect(cartStore.get()).toEqual([shirt]);
+    expect(JSON.parse(localStorage.getItem(CART_STORAGE_KEY)!)).toEqual([shirt]);
+    expect(seen).toHaveBeenCalledTimes(1);
+    off();
+  });
+
+  it("picks up writes from other tabs", () => {
+    localStorage.setItem(CART_STORAGE_KEY, JSON.stringify([pants]));
+    window.dispatchEvent(new StorageEvent("storage", { key: CART_STORAGE_KEY }));
+    expect(cartStore.get()).toEqual([pants]);
+  });
+
+  it("survives corrupt storage", () => {
+    localStorage.setItem(CART_STORAGE_KEY, "{not json");
+    window.dispatchEvent(new StorageEvent("storage", { key: CART_STORAGE_KEY }));
+    expect(cartStore.get()).toEqual([]);
+  });
+});
+
+describe("checkout", () => {
+  it("invokes createCheckout and navigates to the hosted checkout", async () => {
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(
+        new Response(JSON.stringify({ checkoutUrl: "https://checkout.example/1" })),
+      );
+    const navigate = vi.fn();
+    await checkout([shirt], "PROMO", navigate);
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(url).toBe("/deco/invoke/nuvemshop/actions/createCheckout");
+    expect(JSON.parse(String(init!.body))).toEqual({ items: [shirt], coupon: "PROMO" });
+    expect(navigate).toHaveBeenCalledWith("https://checkout.example/1");
+    fetchSpy.mockRestore();
+  });
+
+  it("throws the server error instead of navigating", async () => {
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(new Response("boom", { status: 500 }));
+    const navigate = vi.fn();
+    await expect(checkout([shirt], undefined, navigate)).rejects.toThrow(/500/);
+    expect(navigate).not.toHaveBeenCalled();
+    fetchSpy.mockRestore();
+  });
+});