@decocms/apps-nuvemshop 7.74.1 → 7.76.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps-nuvemshop",
-  "version": "7.74.1",
+  "version": "7.76.0",
   "type": "module",
   "description": "Deco commerce app: Nuvemshop (Tiendanube) Storefront API integration",
   "repository": {
@@ -30,8 +30,9 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.74.1",
-    "@decocms/apps-commerce": "7.74.1"
+    "@decocms/blocks": "7.76.0",
+    "@decocms/apps-commerce": "7.76.0",
+    "@decocms/apps-website": "7.76.0"
   },
   "peerDependencies": {
     "react": "^19.0.0"

package/src/__tests__/account.test.ts

@@ -0,0 +1,250 @@
+import { RequestContext } from "@decocms/blocks/sdk/requestContext";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import login from "../actions/account/login";
+import logout from "../actions/account/logout";
+import register from "../actions/account/register";
+import { configureNuvemshop, setNuvemshopFetch } from "../client";
+import user from "../loaders/user";
+
+const STORE = "https://demodeco.lojavirtualnuvem.com.br";
+const SITE = "https://www.loja.example";
+const ADMIN = "https://api.nuvemshop.com.br/v1/8336778";
+
+type Route = (url: URL, init: RequestInit) => Response | Promise<Response>;
+let routes: Record<string, Route> = {};
+const fetchMock = vi.fn(async (input: string | URL | Request, init: RequestInit = {}) => {
+  const url = new URL(String(input));
+  const key = `${init.method ?? "GET"} ${url.origin}${url.pathname}`;
+  const route = routes[key];
+  if (!route) throw new Error(`unexpected ${key}`);
+  return route(url, init);
+});
+const calls = (key: string) =>
+  fetchMock.mock.calls.filter(
+    ([u, i]) =>
+      `${i?.method ?? "GET"} ${new URL(String(u)).origin}${new URL(String(u)).pathname}` === key,
+  );
+const html = (body: string, init: ResponseInit = {}) =>
+  new Response(body, { ...init, headers: { "content-type": "text/html", ...init.headers } });
+const redirect = (location: string, cookies: string[] = []) => {
+  const headers = new Headers({ location });
+  for (const c of cookies) headers.append("set-cookie", c);
+  return new Response(null, { status: 302, headers });
+};
+const SESSION_SET = `store_session_payload_8336778=NEW; expires=Thu, 05-Nov-2026 23:56:42 GMT; path=/; domain=demodeco.lojavirtualnuvem.com.br; secure; HttpOnly; SameSite=Lax`;
+const inRequest = <T>(fn: () => Promise<T>, cookie = "") =>
+  RequestContext.run(new Request(`${SITE}/deco/invoke/x`, { headers: { cookie } }), async () => {
+    const result = await fn();
+    return { result, setCookies: RequestContext.current!.responseHeaders.getSetCookie() };
+  });
+
+beforeEach(() => {
+  fetchMock.mockClear();
+  routes = {};
+  configureNuvemshop({ storeId: "8336778", storeUrl: STORE, adminToken: "admintoken" });
+  setNuvemshopFetch(fetchMock as unknown as typeof fetch);
+});
+
+describe("login", () => {
+  it("posts the classic form and forwards the store session cookie onto our domain", async () => {
+    const CF =
+      "__cf_bm=abc; HttpOnly; SameSite=None; Secure; Path=/; Domain=lojavirtualnuvem.com.br";
+    routes[`POST ${STORE}/account/login/`] = () => redirect(`${STORE}/account/`, [SESSION_SET, CF]);
+    const { result, setCookies } = await inRequest(
+      () => login({ email: "a@b.com", password: "pw" }),
+      "store_session_payload_8336778=OLD; _ga=GA1.1; other=x",
+    );
+    expect(result).toEqual({ ok: true });
+
+    const [, init] = calls(`POST ${STORE}/account/login/`)[0];
+    expect(String(init!.body)).toBe("email=a%40b.com&password=pw");
+    const headers = new Headers(init!.headers);
+    // only the store's own cookies go upstream — never the site's (_ga, other)
+    expect(headers.get("cookie")).toBe("store_session_payload_8336778=OLD");
+    expect(headers.get("origin")).toBe(STORE);
+    expect(init!.redirect).toBe("manual");
+
+    // only the store session is re-emitted on our domain (not the store's Cloudflare cookies)
+    expect(setCookies).toEqual([
+      SESSION_SET.replace("domain=demodeco.lojavirtualnuvem.com.br", "Domain=www.loja.example"),
+    ]);
+  });
+
+  it.each([
+    [
+      '<div class="alert alert-danger js-login-general-error"> Esses dados estão incorretos.',
+      "invalid_credentials",
+    ],
+    [
+      '<div class="js-account-validation-pending alert alert-danger">Valide seu e-mail',
+      "email_not_validated",
+    ],
+    ["<form id=login-form></form>", "unknown"],
+  ])("maps the login page marker to a reason (%#)", async (marker, error) => {
+    routes[`POST ${STORE}/account/login/`] = () =>
+      redirect(`${STORE}/account/login/`, [SESSION_SET]);
+    routes[`GET ${STORE}/account/login/`] = () => html(`<html>${marker}</html>`);
+    const { result } = await inRequest(() => login({ email: "a@b.com", password: "bad" }));
+    expect(result).toEqual({ ok: false, error });
+    // the follow-up page read reuses the session the POST just set
+    expect(new Headers(calls(`GET ${STORE}/account/login/`)[0][1]!.headers).get("cookie")).toBe(
+      "store_session_payload_8336778=NEW",
+    );
+  });
+
+  it("rejects missing credentials without calling the store", async () => {
+    const { result } = await inRequest(() => login({ email: "", password: "" }));
+    expect(result).toEqual({ ok: false, error: "invalid_credentials" });
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("requires storeUrl", async () => {
+    configureNuvemshop({ storeId: "8336778" });
+    await expect(inRequest(() => login({ email: "a@b.com", password: "pw" }))).rejects.toThrow(
+      /storeUrl/,
+    );
+  });
+});
+
+describe("logout", () => {
+  it("hits /account/logout/ with the session and forwards the expiring cookie", async () => {
+    const expired =
+      "store_session_payload_8336778=deleted; expires=Thu, 01-Jan-1970 00:00:01 GMT; path=/; domain=demodeco.lojavirtualnuvem.com.br";
+    routes[`GET ${STORE}/account/logout/`] = () => redirect(`${STORE}/`, [expired]);
+    const { result, setCookies } = await inRequest(
+      () => logout({}),
+      "store_session_payload_8336778=S",
+    );
+    expect(result).toEqual({ ok: true });
+    expect(setCookies[0]).toContain("Domain=www.loja.example");
+  });
+});
+
+describe("register", () => {
+  const ok = () =>
+    new Response(JSON.stringify({ id: 350524152, email: "a@b.com", active: true }), {
+      status: 201,
+    });
+  const props = { name: "Ana", email: "a@b.com", password: "s3nha-forte", captchaToken: "tok" };
+
+  it("creates the customer through the Admin API (no reCAPTCHA) after verifying Turnstile", async () => {
+    configureNuvemshop({
+      storeId: "8336778",
+      storeUrl: STORE,
+      adminToken: "admintoken",
+      turnstileSecret: "ts",
+    });
+    routes["POST https://challenges.cloudflare.com/turnstile/v0/siteverify"] = () =>
+      Response.json({ success: true });
+    routes[`POST ${ADMIN}/customers`] = ok;
+    const { result } = await inRequest(() => register(props));
+    expect(result).toEqual({ ok: true, customerId: 350524152, emailValidationRequired: true });
+
+    const [, init] = calls(`POST ${ADMIN}/customers`)[0];
+    expect(new Headers(init!.headers).get("authentication")).toBe("bearer admintoken");
+    expect(new Headers(init!.headers).get("user-agent")).toMatch(/deco/);
+    expect(JSON.parse(String(init!.body))).toEqual({
+      name: "Ana",
+      email: "a@b.com",
+      password: "s3nha-forte",
+      send_email_invite: false,
+    });
+    const verify = new URLSearchParams(
+      String(calls("POST https://challenges.cloudflare.com/turnstile/v0/siteverify")[0][1]!.body),
+    );
+    expect(Object.fromEntries(verify)).toMatchObject({ secret: "ts", response: "tok" });
+  });
+
+  it("refuses when bot protection isn't configured (the Admin API has no captcha)", async () => {
+    const { result } = await inRequest(() => register(props));
+    expect(result).toEqual({ ok: false, error: "captcha_not_configured" });
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("allows an explicit opt-out for demos", async () => {
+    configureNuvemshop({
+      storeId: "8336778",
+      storeUrl: STORE,
+      adminToken: "admintoken",
+      allowUnverifiedRegistration: true,
+    });
+    routes[`POST ${ADMIN}/customers`] = ok;
+    expect(
+      (await inRequest(() => register({ ...props, captchaToken: undefined }))).result,
+    ).toMatchObject({ ok: true });
+  });
+
+  it("maps a failed captcha, a taken email and weak input", async () => {
+    configureNuvemshop({
+      storeId: "8336778",
+      storeUrl: STORE,
+      adminToken: "admintoken",
+      turnstileSecret: "ts",
+    });
+    routes["POST https://challenges.cloudflare.com/turnstile/v0/siteverify"] = () =>
+      Response.json({ success: false });
+    expect((await inRequest(() => register(props))).result).toEqual({
+      ok: false,
+      error: "captcha_failed",
+    });
+
+    routes["POST https://challenges.cloudflare.com/turnstile/v0/siteverify"] = () =>
+      Response.json({ success: true });
+    routes[`POST ${ADMIN}/customers`] = () =>
+      Response.json({ email: ["The email must be unique."] }, { status: 422 });
+    expect((await inRequest(() => register(props))).result).toEqual({
+      ok: false,
+      error: "email_taken",
+    });
+
+    expect((await inRequest(() => register({ ...props, email: "nope" }))).result).toEqual({
+      ok: false,
+      error: "invalid_input",
+    });
+    expect((await inRequest(() => register({ ...props, password: "123" }))).result).toEqual({
+      ok: false,
+      error: "invalid_input",
+    });
+  });
+
+  it("requires the admin token", async () => {
+    configureNuvemshop({ storeId: "8336778", storeUrl: STORE, allowUnverifiedRegistration: true });
+    await expect(inRequest(() => register(props))).rejects.toThrow(/adminToken/);
+  });
+});
+
+describe("user", () => {
+  it("returns null without a store session and never calls upstream", async () => {
+    const { result } = await inRequest(() => user({}), "_ga=1");
+    expect(result).toBeNull();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("returns null when the store redirects to login", async () => {
+    routes[`GET ${STORE}/account/`] = () => redirect(`${STORE}/account/login/`);
+    expect((await inRequest(() => user({}), "store_session_payload_8336778=S")).result).toBeNull();
+  });
+
+  it("reads the logged-in customer id from the account page and its data from the Admin API", async () => {
+    routes[`GET ${STORE}/account/`] = () => html("<script>LS.customer = 350524152;</script>");
+    routes[`GET ${ADMIN}/customers/350524152`] = () =>
+      Response.json({
+        id: 350524152,
+        name: "Ana",
+        email: "a@b.com",
+        phone: "11999990000",
+        total_spent: "10.00",
+        addresses: [],
+      });
+    const { result } = await inRequest(() => user({}), "store_session_payload_8336778=S");
+    expect(result).toEqual({ id: 350524152, name: "Ana", email: "a@b.com", phone: "11999990000" });
+  });
+
+  it("falls back to just the id without an admin token", async () => {
+    configureNuvemshop({ storeId: "8336778", storeUrl: STORE });
+    routes[`GET ${STORE}/account/`] = () => html("<script>LS.customer = 7;</script>");
+    expect((await inRequest(() => user({}), "store_session_payload_8336778=S")).result).toEqual({
+      id: 7,
+    });
+  });
+});

package/src/__tests__/mod.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { getNuvemshopConfig } from "../client";
-import { configure } from "../mod";
+import NuvemshopApp, { configure, type Props } from "../mod";
 import { nuvemshopOperationRouter } from "../utils/operationRouter";
 
 const noSecret = async () => null;
@@ -23,17 +23,64 @@ describe("configure", () => {
     }
   });
 
+  it("resolves the admin token and Turnstile secret as secrets and keeps storeUrl", async () => {
+    const keys: string[] = [];
+    await configure(
+      {
+        storeId: "1",
+        storeUrl: "https://loja.example/",
+        adminToken: { e: 1 },
+        turnstileSecret: { e: 2 },
+        allowUnverifiedRegistration: true,
+      },
+      async (_v, key) => {
+        keys.push(key);
+        return `secret-for-${key}`;
+      },
+    );
+    expect(keys).toEqual([
+      "NUVEMSHOP_STOREFRONT_TOKEN",
+      "NUVEMSHOP_ADMIN_TOKEN",
+      "NUVEMSHOP_TURNSTILE_SECRET",
+    ]);
+    expect(getNuvemshopConfig()).toMatchObject({
+      storeUrl: "https://loja.example/",
+      adminToken: "secret-for-NUVEMSHOP_ADMIN_TOKEN",
+      turnstileSecret: "secret-for-NUVEMSHOP_TURNSTILE_SECRET",
+      allowUnverifiedRegistration: true,
+    });
+  });
+
   it("resolves the token through the secret resolver (env fallback key)", async () => {
-    let envKey = "";
+    const keys: string[] = [];
     await configure({ storeId: "1", token: { encrypted: "x" } }, async (_v, key) => {
-      envKey = key;
-      return "tok";
+      keys.push(key);
+      return key === "NUVEMSHOP_STOREFRONT_TOKEN" ? "tok" : null;
     });
-    expect(envKey).toBe("NUVEMSHOP_STOREFRONT_TOKEN");
+    expect(keys[0]).toBe("NUVEMSHOP_STOREFRONT_TOKEN");
     expect(getNuvemshopConfig().token).toBe("tok");
   });
 });
 
+describe("CMS Props (admin form for the deco-nuvemshop block)", () => {
+  it("is the shape configure() reads, and is the default export's input", async () => {
+    const props: Props = {
+      storeId: "8336778",
+      currency: "ARS",
+      defaultSort: "price-ascending",
+      apiVersion: "v2026-11",
+    };
+    expect(NuvemshopApp(props)).toEqual({ state: props });
+    await configure({ ...props }, noSecret);
+    expect(getNuvemshopConfig()).toMatchObject({
+      storeId: "8336778",
+      currency: "ARS",
+      defaultSort: "price-ascending",
+      apiVersion: "v2026-11",
+    });
+  });
+});
+
 describe("nuvemshopOperationRouter", () => {
   const base = "https://storefront-api.tiendanube.com/v2026-11/stores/1";
   it.each([
@@ -44,6 +91,12 @@ describe("nuvemshopOperationRouter", () => {
     [`${base}/categories/calcados`, "categories.get"],
     [`${base}/shipping-options`, "shipping.options"],
     [`${base}/checkouts`, "checkout.create"],
+    ["https://demodeco.lojavirtualnuvem.com.br/account/login/", "store.account.login"],
+    ["https://demodeco.lojavirtualnuvem.com.br/account/logout/", "store.account.logout"],
+    ["https://demodeco.lojavirtualnuvem.com.br/account/", "store.account.page"],
+    ["https://api.nuvemshop.com.br/v1/1/customers", "admin.customers"],
+    ["https://api.nuvemshop.com.br/v1/1/customers/42", "admin.customers"],
+    ["https://challenges.cloudflare.com/turnstile/v0/siteverify", "turnstile.verify"],
     ["https://example.com/other", undefined],
   ])("%s → %s", (url, op) => {
     expect(nuvemshopOperationRouter(url, "GET")).toBe(op);

package/src/actions/account/login.ts

@@ -0,0 +1,30 @@
+import { storeFetch } from "../../store";
+
+export interface Props {
+  email: string;
+  password: string;
+}
+
+export type LoginResult =
+  | { ok: true }
+  | { ok: false; error: "invalid_credentials" | "email_not_validated" | "unknown" };
+
+/**
+ * @title Nuvemshop - Login
+ * @description Signs the buyer into the store session (the theme's login form, server-side).
+ * Success is a redirect to /account/; on failure the login page carries the reason.
+ */
+export default async function login(props: Props): Promise<LoginResult> {
+  if (!props?.email || !props?.password) return { ok: false, error: "invalid_credentials" };
+  const res = await storeFetch("/account/login/", {
+    method: "POST",
+    form: { email: props.email, password: props.password },
+  });
+  if (res.location && new URL(res.location).pathname === "/account/") return { ok: true };
+
+  const page = await (await storeFetch("/account/login/", { cookie: res.cookie })).text();
+  if (page.includes("js-account-validation-pending"))
+    return { ok: false, error: "email_not_validated" };
+  if (page.includes("js-login-general-error")) return { ok: false, error: "invalid_credentials" };
+  return { ok: false, error: "unknown" };
+}

package/src/actions/account/logout.ts

@@ -0,0 +1,10 @@
+import { storeFetch } from "../../store";
+
+/**
+ * @title Nuvemshop - Logout
+ * @description Ends the store session (and forwards the expired session cookie).
+ */
+export default async function logout(_props: unknown): Promise<{ ok: true }> {
+  await storeFetch("/account/logout/");
+  return { ok: true };
+}

package/src/actions/account/register.ts

@@ -0,0 +1,83 @@
+import { RequestContext } from "@decocms/blocks/sdk/requestContext";
+import { nuvemshopAdmin } from "../../admin";
+import { getNuvemshopConfig, nuvemshopFetch } from "../../client";
+
+export interface Props {
+  name: string;
+  email: string;
+  password: string;
+  phone?: string;
+  /** Cloudflare Turnstile token from the registration form. */
+  captchaToken?: string;
+}
+
+export type RegisterResult =
+  | { ok: true; customerId: number; emailValidationRequired: true }
+  | {
+      ok: false;
+      error:
+        | "invalid_input"
+        | "email_taken"
+        | "captcha_failed"
+        | "captcha_not_configured"
+        | "unknown";
+    };
+
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+async function verifyTurnstile(secret: string, token: string | undefined) {
+  if (!token) return false;
+  const remoteip = RequestContext.current?.request.headers.get("cf-connecting-ip") ?? "";
+  const res = await nuvemshopFetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      secret,
+      response: token,
+      ...(remoteip && { remoteip }),
+    }).toString(),
+  });
+  return ((await res.json().catch(() => null)) as { success?: boolean } | null)?.success === true;
+}
+
+/**
+ * @title Nuvemshop - Register
+ * @description Creates a customer through the Admin API. The store's own form needs a reCAPTCHA
+ * bound to its domain; the Admin API has none, so this action requires Cloudflare Turnstile
+ * (`turnstileSecret`) unless `allowUnverifiedRegistration` is set. The store still emails a
+ * validation link before the first login.
+ */
+export default async function register(props: Props): Promise<RegisterResult> {
+  const { turnstileSecret, allowUnverifiedRegistration } = getNuvemshopConfig();
+  const name = props?.name?.trim();
+  const email = props?.email?.trim();
+  if (!name || !email || !EMAIL.test(email) || !props.password || props.password.length < 6) {
+    return { ok: false, error: "invalid_input" };
+  }
+  if (!allowUnverifiedRegistration) {
+    if (!turnstileSecret) return { ok: false, error: "captcha_not_configured" };
+    if (!(await verifyTurnstile(turnstileSecret, props.captchaToken))) {
+      return { ok: false, error: "captcha_failed" };
+    }
+  }
+  const res = await nuvemshopAdmin("/customers", {
+    method: "POST",
+    body: {
+      name,
+      email,
+      password: props.password,
+      ...(props.phone && { phone: props.phone }),
+      send_email_invite: false,
+    },
+  });
+  if (res.status === 422) {
+    const body = (await res.json().catch(() => ({}))) as { email?: string[] };
+    return {
+      ok: false,
+      error: body.email?.some((m) => /unique/i.test(m)) ? "email_taken" : "invalid_input",
+    };
+  }
+  if (!res.ok) return { ok: false, error: "unknown" };
+  const customer = (await res.json()) as { id: number };
+  return { ok: true, customerId: customer.id, emailValidationRequired: true };
+}

package/src/admin.ts

@@ -0,0 +1,23 @@
+/**
+ * Nuvemshop Admin API (`api.nuvemshop.com.br/v1/<store>`) — server-only.
+ * Authenticated with a custom-app token (`adminToken`); used for what the
+ * Storefront API lacks: customer registration (no reCAPTCHA) and account data.
+ */
+import { getNuvemshopConfig, nuvemshopFetch } from "./client";
+
+const ADMIN_BASE = "https://api.nuvemshop.com.br/v1";
+
+export async function nuvemshopAdmin(path: string, init: { method?: string; body?: unknown } = {}) {
+  const { storeId, adminToken } = getNuvemshopConfig();
+  if (!adminToken) throw new Error("Nuvemshop adminToken is not configured (custom app token)");
+  return nuvemshopFetch(`${ADMIN_BASE}/${storeId}${path}`, {
+    method: init.method ?? "GET",
+    headers: {
+      authentication: `bearer ${adminToken}`,
+      // Nuvemshop requires an identifying User-Agent on Admin API calls.
+      "user-agent": "deco.cx storefront (https://deco.cx)",
+      ...(init.body !== undefined && { "content-type": "application/json" }),
+    },
+    body: init.body === undefined ? undefined : JSON.stringify(init.body),
+  });
+}

package/src/client.ts

@@ -32,6 +32,21 @@ export interface NuvemshopConfig {
    * category's configured sort and returns oldest-first. Default "created-descending".
    */
   defaultSort?: string;
+  /**
+   * The store's own domain (e.g. https://demodeco.lojavirtualnuvem.com.br).
+   * Needed for the session endpoints the API doesn't cover (login/logout/account).
+   */
+  storeUrl?: string;
+  /**
+   * Admin API token from a custom app (Configurações → Aplicativos sob medida).
+   * Server-only: used for customer registration and account data. It is NOT a
+   * Storefront token (the Storefront API rejects it).
+   */
+  adminToken?: string;
+  /** Cloudflare Turnstile secret, verified before registering a customer. */
+  turnstileSecret?: string;
+  /** Skip bot verification on registration (demos only — the Admin API has no captcha). */
+  allowUnverifiedRegistration?: boolean;
 }
 
 /**
@@ -100,6 +115,9 @@ export function clearNuvemshopCache() {
 
 const transport = () => (_fetch ??= createNuvemshopFetch() as FetchFn);
 
+/** The instrumented transport shared by every Nuvemshop egress (Storefront, store, Admin). */
+export const nuvemshopFetch: FetchFn = (input, init) => transport()(input, init);
+
 function storeUrl(path: string, params: Record<string, string | number | undefined> = {}) {
   const {
     storeId,

package/src/index.ts

@@ -1,3 +1,6 @@
+export { default as login } from "./actions/account/login";
+export { default as logout } from "./actions/account/logout";
+export { default as register } from "./actions/account/register";
 export { default as createCheckout } from "./actions/createCheckout";
 export {
   clearNuvemshopCache,
@@ -16,8 +19,10 @@ 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 { default as user } from "./loaders/user";
 export { configure } from "./mod";
 export { NUVEMSHOP_REGISTRY_ENTRY } from "./registry";
 export { createNuvemshopFetch } from "./utils/instrumentedFetch";
 export { nuvemshopOperationRouter } from "./utils/operationRouter";
+export { nuvemshopSitemap } from "./utils/sitemap";
 export type * from "./utils/types";

package/src/loaders/user.ts

@@ -0,0 +1,30 @@
+import { nuvemshopAdmin } from "../admin";
+import { getNuvemshopConfig } from "../client";
+import { storeCookies, storeFetch } from "../store";
+
+export interface NuvemshopUser {
+  id: number;
+  name?: string;
+  email?: string;
+  phone?: string | null;
+}
+
+/**
+ * @title Nuvemshop - Logged-in customer
+ * @description The buyer's account from the store session (null when logged out).
+ * Reads the customer id from the store's account page and the profile from the Admin API.
+ */
+export default async function user(_props: unknown): Promise<NuvemshopUser | null> {
+  if (!storeCookies()) return null;
+  const page = await storeFetch("/account/");
+  if (page.status !== 200) return null;
+  const id = Number((await page.text()).match(/LS\.customer\s*=\s*(\d+)/)?.[1]);
+  if (!id) return null;
+  if (!getNuvemshopConfig().adminToken) return { id };
+  const res = await nuvemshopAdmin(`/customers/${id}`);
+  if (!res.ok) return { id };
+  const c = (await res.json()) as NuvemshopUser;
+  return { id: c.id, name: c.name, email: c.email, phone: c.phone };
+}
+
+export const cache = "no-store";

package/src/manifest.gen.ts

@@ -1,6 +1,9 @@
 // Hand-maintained (the generate-manifests script referenced by other apps doesn't exist).
 // Keys are the `__resolveType` / `/deco/invoke/<key>` names.
 
+import * as actions_account_login from "./actions/account/login";
+import * as actions_account_logout from "./actions/account/logout";
+import * as actions_account_register from "./actions/account/register";
 import * as actions_createCheckout from "./actions/createCheckout";
 import * as loaders_categories from "./loaders/categories";
 import * as loaders_productDetailsPage from "./loaders/productDetailsPage";
@@ -9,6 +12,7 @@ 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";
+import * as loaders_user from "./loaders/user";
 
 const manifest = {
   name: "nuvemshop",
@@ -20,8 +24,12 @@ const manifest = {
     "nuvemshop/loaders/relatedProducts": loaders_relatedProducts,
     "nuvemshop/loaders/shippingOptions": loaders_shippingOptions,
     "nuvemshop/loaders/suggestions": loaders_suggestions,
+    "nuvemshop/loaders/user": loaders_user,
   },
   actions: {
+    "nuvemshop/actions/account/login": actions_account_login,
+    "nuvemshop/actions/account/logout": actions_account_logout,
+    "nuvemshop/actions/account/register": actions_account_register,
     "nuvemshop/actions/createCheckout": actions_createCheckout,
   },
   sections: {},

package/src/mod.ts

@@ -9,8 +9,66 @@
  * production — see `client.ts` for the rate-limit trade-off.
  */
 import type { AppDefinition, ResolveSecretFn } from "@decocms/apps-commerce/app-types";
+import type { Secret } from "@decocms/apps-website/mod";
 import { configureNuvemshop, type NuvemshopConfig } from "./client";
 import manifest from "./manifest.gen";
+import type { SortValue } from "./utils/listing";
+
+// -------------------------------------------------------------------------
+// CMS Props — the admin form for the `deco-nuvemshop` block. Sites expose it
+// through a bridge (`src/apps/nuvemshop.ts` re-exporting this module's default
+// and `Props`); generate-schema builds the form from this interface.
+// -------------------------------------------------------------------------
+
+/** @title Nuvemshop */
+export interface Props {
+  /**
+   * @title Store ID
+   * @description Numeric Nuvemshop/Tiendanube store id (e.g. 8336778).
+   */
+  storeId: string;
+  /**
+   * @title Storefront token
+   * @description Optional. Without it all buyers share 120 req/min per IP; with it the store gets 1,200 req/min.
+   */
+  token?: Secret;
+  /**
+   * @title Currency
+   * @description The API returns no currency. @default BRL
+   */
+  currency?: string;
+  /**
+   * @title Default category sort
+   * @description The API doesn't expose the category's configured sort. @default created-descending
+   */
+  defaultSort?: SortValue;
+  /**
+   * @title API version
+   * @default v2026-11
+   */
+  apiVersion?: string;
+  /**
+   * @title Store URL
+   * @description The store's own domain (e.g. https://minhaloja.lojavirtualnuvem.com.br). Required for login/logout/account.
+   */
+  storeUrl?: string;
+  /**
+   * @title Admin API token
+   * @description Custom app token (Configurações → Aplicativos sob medida). Server-only; enables registration and account data.
+   */
+  adminToken?: Secret;
+  /**
+   * @title Turnstile secret
+   * @description Cloudflare Turnstile secret verified before registering customers (the Admin API has no captcha).
+   */
+  turnstileSecret?: Secret;
+  /**
+   * @title Allow registration without bot verification
+   * @description Demos only.
+   * @default false
+   */
+  allowUnverifiedRegistration?: boolean;
+}
 
 export interface NuvemshopState {
   config: NuvemshopConfig;
@@ -27,9 +85,19 @@ export async function configure(
     (await resolveSecret(block.token, "NUVEMSHOP_STOREFRONT_TOKEN")) ??
     (typeof block.token === "string" ? block.token : undefined);
 
+  const secret = async (key: string, env: string) =>
+    (await resolveSecret(block[key], env)) ??
+    (typeof block[key] === "string" ? (block[key] as string) : undefined);
+  const adminToken = await secret("adminToken", "NUVEMSHOP_ADMIN_TOKEN");
+  const turnstileSecret = await secret("turnstileSecret", "NUVEMSHOP_TURNSTILE_SECRET");
+
   const config: NuvemshopConfig = {
     storeId,
     token: token || undefined,
+    storeUrl: block.storeUrl as string | undefined,
+    adminToken: adminToken || undefined,
+    turnstileSecret: turnstileSecret || undefined,
+    allowUnverifiedRegistration: block.allowUnverifiedRegistration === true,
     apiVersion: block.apiVersion as string | undefined,
     currency: block.currency as string | undefined,
     defaultSort: block.defaultSort as string | undefined,
@@ -40,3 +108,8 @@ export async function configure(
 }
 
 export const preview = undefined;
+
+/** Default export for schema generation and app bridges. */
+export default function Nuvemshop(props: Props) {
+  return { state: props };
+}

package/src/store.ts

@@ -0,0 +1,88 @@
+/**
+ * The store's own (theme) session endpoints — the parts the Storefront API
+ * doesn't cover: login, logout and the logged-in account page.
+ *
+ * The session lives in the store's cookies (`store_session_payload_<id>`,
+ * `store_login_session`, …). We forward only those (`store_*`) upstream —
+ * never the site's own cookies — and re-emit the store's `Set-Cookie` on our
+ * domain through `RequestContext.responseHeaders`, so the browser keeps one
+ * session that follows it across our pages.
+ */
+import { RequestContext } from "@decocms/blocks/sdk/requestContext";
+import { getNuvemshopConfig, nuvemshopFetch } from "./client";
+
+const STORE_COOKIE = /^store_/;
+
+export function storeOrigin(): string {
+  const { storeUrl } = getNuvemshopConfig();
+  if (!storeUrl) throw new Error("Nuvemshop storeUrl is not configured (the store's own domain)");
+  return new URL(storeUrl).origin;
+}
+
+/** `store_*` cookies of the current request, as a Cookie header ("" when none). */
+export function storeCookies(): string {
+  const raw = RequestContext.current?.request.headers.get("cookie") ?? "";
+  return raw
+    .split(/;\s*/)
+    .filter((c) => STORE_COOKIE.test(c))
+    .join("; ");
+}
+
+function rewriteDomain(cookie: string, host: string | null) {
+  return host
+    ? cookie.replace(/(;\s*)domain=[^;]*/i, `$1Domain=${host}`)
+    : cookie.replace(/;\s*domain=[^;]*/gi, "");
+}
+
+/** Merge upstream Set-Cookie values into a Cookie header (for follow-up calls in the same action). */
+function mergeCookies(header: string, setCookies: string[]) {
+  const jar = new Map(header ? header.split(/;\s*/).map((c) => [c.split("=")[0], c] as const) : []);
+  for (const s of setCookies) {
+    const kv = s.split(";")[0];
+    const name = kv.split("=")[0];
+    if (STORE_COOKIE.test(name)) jar.set(name, kv);
+  }
+  return [...jar.values()].join("; ");
+}
+
+export interface StoreResponse {
+  status: number;
+  location: string | null;
+  text: () => Promise<string>;
+}
+
+/**
+ * Calls the store with the buyer's store session and forwards any new
+ * session cookies to the browser. `cookie` overrides the request's cookies
+ * (used to chain calls inside one action). Redirects are not followed.
+ */
+export async function storeFetch(
+  path: string,
+  init: { method?: "GET" | "POST"; form?: Record<string, string>; cookie?: string } = {},
+): Promise<StoreResponse & { cookie: string }> {
+  const origin = storeOrigin();
+  const cookie = init.cookie ?? storeCookies();
+  const headers: Record<string, string> = { origin, referer: `${origin}${path}` };
+  if (init.form) headers["content-type"] = "application/x-www-form-urlencoded";
+  if (cookie) headers.cookie = cookie;
+  const res = await nuvemshopFetch(`${origin}${path}`, {
+    method: init.method ?? "GET",
+    headers,
+    body: init.form ? new URLSearchParams(init.form).toString() : undefined,
+    redirect: "manual",
+  });
+  const setCookies = res.headers.getSetCookie();
+  const ctx = RequestContext.current;
+  if (ctx) {
+    const host = new URL(ctx.request.url).hostname;
+    for (const c of setCookies) {
+      if (STORE_COOKIE.test(c)) ctx.responseHeaders.append("set-cookie", rewriteDomain(c, host));
+    }
+  }
+  return {
+    status: res.status,
+    location: res.headers.get("location"),
+    text: () => res.text(),
+    cookie: mergeCookies(cookie, setCookies),
+  };
+}

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

@@ -0,0 +1,57 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import categoriesFixture from "../../__fixtures__/categories.json";
+import { clearNuvemshopCache, configureNuvemshop, setNuvemshopFetch } from "../../client";
+import { nuvemshopSitemap } from "../sitemap";
+
+const json = (body: unknown) =>
+  new Response(JSON.stringify(body), { headers: { "content-type": "application/json" } });
+const page = (n: number, total: number, handles: string[]) => ({
+  data: handles.map((handle, i) => ({
+    id: n * 100 + i,
+    handle,
+    updated_at: `2026-10-0${n}T10:00:00+0000`,
+  })),
+  pagination: { page: n, per_page: 200, total: 3, total_pages: total },
+});
+
+const fetchMock = vi.fn(async (input: string | URL | Request) => {
+  const url = new URL(String(input));
+  if (url.pathname.endsWith("/categories")) return json(categoriesFixture);
+  const p = Number(url.searchParams.get("page") ?? 1);
+  return json(p === 1 ? page(1, 2, ["camisa-a", "camisa-b&c"]) : page(2, 2, ["tenis-x"]));
+});
+
+beforeEach(() => {
+  fetchMock.mockClear();
+  clearNuvemshopCache();
+  configureNuvemshop({ storeId: "8336778" });
+  setNuvemshopFetch(fetchMock as unknown as typeof fetch);
+});
+
+describe("nuvemshopSitemap", () => {
+  it("pages through every product and lists categories with nested URLs", async () => {
+    const xml = await nuvemshopSitemap({ origin: "https://www.loja.example" });
+
+    const productCalls = fetchMock.mock.calls
+      .map(([u]) => new URL(String(u)))
+      .filter((u) => u.pathname.endsWith("/products"));
+    expect(productCalls.map((u) => u.searchParams.get("page"))).toEqual(["1", "2"]);
+    expect(productCalls[0].searchParams.get("per_page")).toBe("200");
+    expect(productCalls[0].searchParams.get("fields")).toBe("handle,updated_at");
+
+    expect(
+      xml.startsWith(
+        '<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+      ),
+    ).toBe(true);
+    expect(xml).toContain(
+      "<url><loc>https://www.loja.example/produtos/camisa-a</loc><lastmod>2026-10-01</lastmod></url>",
+    );
+    expect(xml).toContain("<loc>https://www.loja.example/produtos/tenis-x</loc>");
+    expect(xml).toContain("<loc>https://www.loja.example/produtos/camisa-b&amp;c</loc>"); // XML-escaped
+    expect(xml).toContain("<url><loc>https://www.loja.example/calcados/masculino</loc></url>");
+    expect(xml).toContain("<url><loc>https://www.loja.example/</loc></url>");
+    expect(xml.match(/<url>/g)).toHaveLength(1 + categoriesFixture.data.length + 3);
+    expect(xml.trimEnd().endsWith("</urlset>")).toBe(true);
+  });
+});

package/src/utils/listing.ts

@@ -22,7 +22,17 @@ export const LISTING_WINDOW = 200;
  * 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[] = [
+export type SortValue =
+  | "best-selling"
+  | "price-ascending"
+  | "price-descending"
+  | "alpha-ascending"
+  | "alpha-descending"
+  | "created-descending"
+  | "created-ascending"
+  | "discount-descending";
+
+export const SORT_OPTIONS: (SortOption & { value: SortValue })[] = [
   { value: "best-selling", label: "Mais vendidos" },
   { value: "price-ascending", label: "Menor preço" },
   { value: "price-descending", label: "Maior preço" },

package/src/utils/operationRouter.ts

@@ -1,5 +1,6 @@
 /**
- * URL → operation name for Nuvemshop Storefront API calls, plugged into
+ * URL → operation name for Nuvemshop egress (Storefront API, the store's own
+ * session endpoints, the Admin API and Turnstile), plugged into
  * `createInstrumentedFetch`'s `resolveOperation`. Returns `undefined` when
  * nothing matches so the framework falls back to `nuvemshop.fetch`.
  */
@@ -13,6 +14,11 @@ const MATCHERS: ReadonlyArray<[RegExp, string]> = [
   [/\/stores\/\d+\/categories\/[^/]+\/?$/, "categories.get"],
   [/\/stores\/\d+\/shipping-options\/?$/, "shipping.options"],
   [/\/stores\/\d+\/checkouts\/?$/, "checkout.create"],
+  [/^\/account\/login\/?$/, "store.account.login"],
+  [/^\/account\/logout\/?$/, "store.account.logout"],
+  [/^\/account\/?$/, "store.account.page"],
+  [/^\/v1\/\d+\/customers(\/\d+)?\/?$/, "admin.customers"],
+  [/^\/turnstile\/v0\/siteverify$/, "turnstile.verify"],
 ];
 
 export function nuvemshopOperationRouter(url: string, _method: string): string | undefined {

package/src/utils/sitemap.ts

@@ -0,0 +1,54 @@
+/**
+ * Product + category sitemap built from the Storefront API (which has no
+ * sitemap endpoint). URLs use the same paths as the loaders (`/produtos/<handle>`,
+ * `/<cat>/<sub>`), so they resolve without redirects. Serve it from a site route:
+ *
+ * ```ts
+ * // src/routes/sitemap[.]xml.ts
+ * GET: async ({ request }) => new Response(await nuvemshopSitemap({ origin: new URL(request.url).origin }),
+ *   { headers: { "content-type": "application/xml; charset=utf-8" } })
+ * ```
+ */
+import { nuvemshopGet } from "../client";
+import { categoryChain, categoryPath, productPath } from "./transform";
+import type { NuvemshopCategory, NuvemshopList } from "./types";
+
+// ponytail: one request per 200 products, sequential; split into a sitemap index if a catalog
+// ever outgrows the 50k-URL sitemap limit.
+const PER_PAGE = 200;
+
+const escapeXml = (s: string) =>
+  s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+const entry = (loc: string, lastmod?: string) =>
+  `<url><loc>${escapeXml(loc)}</loc>${lastmod ? `<lastmod>${lastmod.slice(0, 10)}</lastmod>` : ""}</url>`;
+
+export async function nuvemshopSitemap({ origin }: { origin: string }): Promise<string> {
+  const urls = [entry(`${origin}/`)];
+
+  const categories =
+    (await nuvemshopGet<NuvemshopList<NuvemshopCategory>>("/categories", { per_page: PER_PAGE }))
+      ?.data ?? [];
+  for (const c of categories)
+    urls.push(entry(`${origin}${categoryPath(categoryChain(c, categories))}`));
+
+  for (let page = 1, pages = 1; page <= pages; page++) {
+    const list = await nuvemshopGet<NuvemshopList<{ handle: string; updated_at?: string }>>(
+      "/products",
+      {
+        fields: "handle,updated_at",
+        per_page: PER_PAGE,
+        page,
+      },
+    );
+    if (!list) break;
+    pages = list.pagination.total_pages;
+    for (const p of list.data) urls.push(entry(`${origin}${productPath(p.handle)}`, p.updated_at));
+  }
+
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls.join("\n")}\n</urlset>\n`;
+}