@unbox-plus/cli 0.20.4

package/template/lib/orders.ts

@@ -0,0 +1,160 @@
+// Acesso a pedido COM verificação de posse (doc 09): cliente logado OU token do placeOrder (cookie).
+import "server-only";
+import { withStoreClient } from "./unbox/store";
+import { getOrderToken } from "./session";
+import { getCustomerClient } from "./customer-session";
+import { orderStatusLabel, paymentStatusLabel } from "./unbox/customer";
+import { formatBRL } from "./format";
+
+// O resolver de `displayAmount` no contexto do cliente (customerOrderByReferenceId) é furado e às
+// vezes devolve "R$NaN,undefined". Por isso formatamos SEMPRE a partir do `.amount` numérico.
+const money = (amount: unknown): string | undefined =>
+  typeof amount === "number" && !Number.isNaN(amount) ? formatBRL(amount) : undefined;
+
+export interface ShapedOrderItem {
+  title: string;
+  variantTitle?: string;
+  quantity: number;
+  displayPrice?: string;
+  displaySubtotal?: string;
+  thumbnail?: string;
+  slug?: string;
+  /** dados p/ refazer o pedido (adicionar ao carrinho) */
+  productId?: string;
+  variantId?: string;
+  price?: number;
+}
+
+export interface ShapedOrder {
+  referenceId: string;
+  status: string;
+  statusLabel: string;
+  paid: boolean;
+  payment: { displayName?: string; captured?: boolean; cardBrand?: string; errorMessage?: string; statusLabel?: string; amount?: string } | null;
+  fulfillment: { status?: string; type?: string; trackingCode?: string }[];
+  items: ShapedOrderItem[];
+  address: ShapedAddress | null;
+  invoiceIssued?: boolean;
+  dispatched?: boolean;
+  delivered?: boolean;
+  total?: string;
+  email?: string;
+}
+
+export interface ShapedAddress {
+  fullName?: string;
+  line?: string; // "Rua X, 123 · Bairro"
+  cityRegion?: string; // "São Paulo/SP · 05724-003"
+}
+
+export interface ShapedOrderSummary {
+  referenceId: string;
+  status: string;
+  statusLabel: string;
+  createdAt?: string;
+  recurring: boolean;
+  dispatched: boolean;
+  delivered: boolean;
+  total?: string;
+  itemCount: number;
+  thumbnails: string[];
+  firstTitles: string[];
+  address: ShapedAddress | null;
+}
+
+function shapeAddress(a: any): ShapedAddress | null {
+  if (!a) return null;
+  const line = [a.address1, a.number].filter(Boolean).join(", ") + (a.neighborhood ? ` · ${a.neighborhood}` : "");
+  const cityRegion = [a.city && a.region ? `${a.city}/${a.region}` : a.city || a.region, a.postal].filter(Boolean).join(" · ");
+  return { fullName: a.fullName || undefined, line: line.trim() || undefined, cityRegion: cityRegion || undefined };
+}
+
+/** Resumo de um pedido para a LISTA: endereço, miniaturas, contagem e total. */
+export function shapeOrderSummary(o: any): ShapedOrderSummary {
+  const groups: any[] = o.fulfillmentGroups ?? [];
+  const items: any[] = groups.flatMap((g: any) => g.items?.nodes ?? []);
+  const address = shapeAddress(groups.find((g: any) => g.data?.shippingAddress)?.data?.shippingAddress);
+  const itemsSum = items.reduce((s: number, it: any) => s + (it.price?.amount ?? 0) * (it.quantity ?? 1), 0);
+  return {
+    referenceId: o.referenceId,
+    status: o.status,
+    statusLabel: orderStatusLabel(o.status),
+    createdAt: o.createdAt,
+    recurring: !!o.recurringOrderId,
+    dispatched: !!o.dispatched,
+    delivered: !!o.delivered,
+    total: money(o.summary?.total?.amount) ?? money(itemsSum > 0 ? itemsSum : undefined),
+    itemCount: items.reduce((s: number, it: any) => s + (it.quantity ?? 1), 0),
+    thumbnails: items.map((it: any) => it.thumbnail).filter(Boolean).slice(0, 4),
+    firstTitles: items.map((it: any) => it.title).filter(Boolean).slice(0, 3),
+    address,
+  };
+}
+
+export function shapeOrder(o: any): ShapedOrder {
+  const pmt = o.payments?.[0];
+  const groups: any[] = o.fulfillmentGroups ?? [];
+  const items: ShapedOrderItem[] = groups.flatMap((g: any) =>
+    (g.items?.nodes ?? []).map((it: any): ShapedOrderItem => {
+      const unit = it.price?.amount;
+      return {
+        title: it.title,
+        variantTitle: it.variantTitle ?? undefined,
+        quantity: it.quantity,
+        displayPrice: money(unit),
+        displaySubtotal: typeof unit === "number" ? money(unit * (it.quantity ?? 1)) : undefined,
+        thumbnail: it.thumbnail ?? undefined,
+        slug: it.productSlug ?? undefined,
+        productId: it.productConfiguration?.productId ?? undefined,
+        variantId: it.productConfiguration?.productVariantId ?? undefined,
+        price: typeof unit === "number" ? unit : undefined,
+      };
+    }),
+  );
+  const itemsSum = items.reduce((s, i) => s + (i.price ?? 0) * i.quantity, 0);
+  return {
+    referenceId: o.referenceId,
+    status: o.status,
+    statusLabel: orderStatusLabel(o.status),
+    paid: o.status === "PROCESSING" || o.status === "COMPLETED" || pmt?.isCaptured === true,
+    payment: pmt
+      ? {
+          displayName: pmt.displayName,
+          captured: pmt.isCaptured,
+          cardBrand: pmt.cardBrand,
+          errorMessage: pmt.captureErrorMessage,
+          statusLabel: pmt.status?.status ? paymentStatusLabel(pmt.status.status) : undefined,
+          amount: money(pmt.amount?.amount),
+        }
+      : null,
+    fulfillment: groups.map((g: any) => ({
+      status: g.status,
+      type: g.type,
+      trackingCode: g.trackingCode,
+    })),
+    items,
+    address: shapeAddress(groups.find((g: any) => g.data?.shippingAddress)?.data?.shippingAddress),
+    invoiceIssued: o.invoiceIssued,
+    dispatched: o.dispatched,
+    delivered: o.delivered,
+    total: money(o.summary?.total?.amount) ?? money(pmt?.amount?.amount) ?? money(itemsSum > 0 ? itemsSum : undefined),
+    email: o.email,
+  };
+}
+
+/** Retorna o pedido se o solicitante tiver posse; senão null. */
+export async function getOwnedOrder(referenceId: string): Promise<ShapedOrder | null> {
+  const customer = await getCustomerClient();
+  if (customer) {
+    try {
+      const o = await customer.order(referenceId);
+      if (o) return shapeOrder(o);
+    } catch {
+      /* cai para o token de guest */
+    }
+  }
+  const token = await getOrderToken(referenceId);
+  if (!token) return null;
+  const o = await withStoreClient((c) => c.getOrder(referenceId, token));
+  return o ? shapeOrder(o) : null;
+}

package/template/lib/queries.ts

@@ -0,0 +1,66 @@
+// Fetchers server-side reutilizáveis. Catálogo/loja/tags são públicos e estáveis → cacheados
+// (unstable_cache, revalidável on-demand via /api/revalidate). cache() dedup por request.
+import "server-only";
+import { cache } from "react";
+import { unstable_cache } from "next/cache";
+import { withStoreClient, getShopContext } from "./unbox/store";
+
+const TTL = 300; // 5 min
+
+export const getShopData = cache(
+  unstable_cache(
+    async () => {
+      const { shopSlug } = await getShopContext();
+      return withStoreClient((c) => c.getShop(shopSlug));
+    },
+    ["unbox-shop"],
+    { revalidate: TTL, tags: ["shop"] },
+  ),
+);
+
+export const getTopTags = cache(
+  unstable_cache(
+    async () => withStoreClient((c) => c.getTags()),
+    ["unbox-top-tags"],
+    { revalidate: 600, tags: ["tags"] },
+  ),
+);
+
+export const getPaymentMethods = cache(
+  unstable_cache(
+    async () => withStoreClient((c) => c.getPaymentMethods()),
+    ["unbox-payment-methods"],
+    { revalidate: TTL, tags: ["shop"] },
+  ),
+);
+
+/**
+ * Lista paginada do catálogo (busca/filtro/ordenação). Cacheado por `opts` — o Next 15 NÃO
+ * cacheia fetch() por padrão (diferente do 13/14), então sem unstable_cache explícito toda
+ * chamada batia direto na Unbox: /produtos, /categoria/* e as ofertas de upsell do checkout
+ * levavam de 1 a 8s por navegação. Com cache: consistentemente < 0.1s em hit.
+ */
+export const getCatalog = cache((opts: {
+  first?: number; offset?: number; searchText?: string; tagIds?: string[];
+  sortBy?: string; sortOrder?: "asc" | "desc";
+} = {}) =>
+  unstable_cache(
+    () => withStoreClient((c) => c.getCatalog(opts)),
+    ["unbox-catalog", JSON.stringify(opts)],
+    { revalidate: TTL, tags: ["catalog"] },
+  )(),
+);
+
+// Cacheado por slug: data cache compartilhado entre requests (revalidável) + dedup por
+// request via cache() — a PDP busca o mesmo slug em generateMetadata e no corpo da página.
+export const getProductBySlug = cache((slug: string) =>
+  unstable_cache(
+    () => withStoreClient((c) => c.getProductBySlug(slug)),
+    ["unbox-product", slug],
+    { revalidate: TTL, tags: ["catalog", `product:${slug}`] },
+  )(),
+);
+
+export async function getDiscountCodes(first = 50) {
+  return withStoreClient((c) => c.listDiscountCodes(first));
+}

package/template/lib/ratelimit.ts

@@ -0,0 +1,47 @@
+// Rate-limit em memória (token-bucket simples por chave). Protege OTP, signin, checkout e
+// verificação de conta contra spam/abuso/enumeração (doc 09 — o x-captcha-verification NÃO é
+// um captcha real).
+//
+// PROD: substituir por @upstash/ratelimit + Vercel KV (compartilhado entre lambdas). Em dev /
+// single-instance, este mapa em memória é suficiente.
+import "server-only";
+
+interface Bucket { count: number; resetAt: number }
+const store = new Map<string, Bucket>();
+
+export interface RateLimitResult { ok: boolean; remaining: number; resetInMs: number }
+
+/**
+ * @param key      identificador (ex.: `otp:${ip}` ou `otp:${email}`)
+ * @param limit    máximo de chamadas na janela
+ * @param windowMs tamanho da janela em ms
+ */
+export function rateLimit(key: string, limit: number, windowMs: number): RateLimitResult {
+  const now = Date.now();
+  const b = store.get(key);
+  if (!b || now > b.resetAt) {
+    store.set(key, { count: 1, resetAt: now + windowMs });
+    return { ok: true, remaining: limit - 1, resetInMs: windowMs };
+  }
+  b.count += 1;
+  const ok = b.count <= limit;
+  return { ok, remaining: Math.max(0, limit - b.count), resetInMs: b.resetAt - now };
+}
+
+/** Extrai um identificador de IP do request (best-effort, atrás de proxy/Vercel). */
+export function clientIp(req: Request): string {
+  const h = req.headers;
+  return (
+    h.get("x-forwarded-for")?.split(",")[0]?.trim() ||
+    h.get("x-real-ip") ||
+    "unknown"
+  );
+}
+
+/** Limites pré-configurados por rota sensível. */
+export const LIMITS = {
+  otp: { limit: 5, windowMs: 10 * 60 * 1000 },        // 5 / 10min
+  signin: { limit: 10, windowMs: 10 * 60 * 1000 },    // 10 / 10min
+  checkout: { limit: 8, windowMs: 5 * 60 * 1000 },     // 8 / 5min
+  exists: { limit: 20, windowMs: 10 * 60 * 1000 },     // 20 / 10min
+} as const;

package/template/lib/rotas-editaveis.ts

@@ -0,0 +1,192 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// AS PÁGINAS DESTA LOJA — DERIVADAS, NUNCA DIGITADAS.
+//
+// Antes daqui, a lista de páginas que o editor abre morava no `shops.json` do EDITOR: digitada à
+// mão, com slug de produto cravado dentro, e ignorada inteira quando `SHOPS_JSON` existia no
+// ambiente. Para 100 lojas isso não se sustenta — quem sabe quais páginas existem é a loja.
+//
+// A REGRA, uma só, e já mantida por outra pessoa: é editável a página dentro de `app/(loja)/` cujo
+// caminho não casa com nenhum prefixo do `DISALLOW` de `app/robots.ts` (as "áreas privadas/
+// transacionais" que o SEO já declara). Não há segunda lista para alguém esquecer de atualizar: a
+// página nova aparece porque o arquivo dela existe, e some do editor porque o SEO a bloqueou.
+//
+// UMA ENTRADA POR ROTA, não por produto. `/produto/[productSlug]` é UMA página editável (a receita
+// que renderiza todas), e não uma por produto. O exemplo concreto (para a prévia abrir) é resolvido
+// em app/api/unbox/paginas/route.ts, que é quem fala com o catálogo.
+// ═══════════════════════════════════════════════════════════════════════════
+import fs from "node:fs";
+import path from "node:path";
+import { DISALLOW } from "@/app/robots";
+
+const ARQUIVO_DE_PAGINA = /^page\.(tsx|ts|jsx|js)$/;
+
+/** `/conta/pedidos` casa com o prefixo `/conta`; `/contato` NÃO casa (prefixo é segmento, não texto). */
+export function bloqueadaPeloRobots(rota: string): boolean {
+  return DISALLOW.some((d) => rota === d || rota.startsWith(`${d}/`));
+}
+
+// ── AS PÁGINAS QUE SÃO SÓ CABEÇALHO E RODAPÉ, POR REGRA ─────────────────────────────────────────
+// A regra da casa (README do editor, §8) diz o que NÃO vira primitivo: texto legal, rótulo de
+// formulário e de UI, mecânica de compra. Nestas rotas o corpo inteiro é isso, então o que o lojista
+// edita nelas é só o `chrome` (cabeçalho e rodapé). Sem esta lista o gate de cobertura as mediria
+// como qualquer outra página, veria 22% a 65% e reprovaria a loja para sempre; e um gate que sempre
+// reprova é um gate que ninguém lê.
+//
+// NÃO é uma segunda lista de páginas: ela não põe nem tira página do editor (isso é o `DISALLOW`).
+// Ela só diz, das páginas editáveis, quais são só cabeçalho e rodapé POR DECISÃO de quem construiu a
+// loja, com o motivo ao lado. Explícita de propósito: o gate não infere isso do conteúdo, e a página
+// que não está aqui continua sob a régua de 80%. Vai para `GET /api/unbox/paginas` como `soChrome: true`.
+//
+// ROTA NOVA que seja só texto legal ou mecânica de compra entra aqui, com o motivo citando o §8.
+export const SO_CHROME: readonly string[] = [
+  "/termos", // texto legal (termos de uso): §8, "texto legal (política, CNPJ, termos)"
+  "/privacidade", // texto legal (política de privacidade): §8, o mesmo item
+  "/devolucoes", // texto legal (política de trocas e devoluções): §8, o mesmo item
+  "/busca", // campo de busca e resultados do catálogo: §8, "rótulo de formulário e de UI" e "produto do catálogo"
+];
+
+/** `rota` é uma das páginas que, por regra (§8), só tem cabeçalho e rodapé editáveis. Igualdade exata: `/termos/x` não herda. */
+export function soChrome(rota: string): boolean {
+  return SO_CHROME.includes(rota);
+}
+
+// ── OS CONTAINERS QUE CADA ROTA RENDERIZA ───────────────────────────────────────────────────────
+// A regra do modelo: a ORDEM é do container e a COPY é do container. Então "em que outras páginas esta
+// seção aparece?" tem resposta exata: nas rotas que renderizam o mesmo container. O editor só sabia isso
+// DEPOIS de alguém abrir a outra página na prévia (o manifesto é capturado por página): de /produtos, sem
+// /categoria aberta, ele deixava publicar a copy do catálogo sem avisar que ela vale nas categorias. Aqui a
+// loja DECLARA, igual ao SO_CHROME: rota → containers que ela renderiza, FORA o `chrome` (cabeçalho, faixa,
+// rodapé), que é do site inteiro e não se lista. Lista vazia é declaração ("esta página só tem o chrome"),
+// não ausência. Vai para `GET /api/unbox/paginas` como `containers`.
+//
+// O GATE CONFERE (scripts/check-editable.mjs): os containers que o manifesto de cada página mostrou, fora o
+// chrome, têm de ser exatamente estes. Página que renderiza um container que não está aqui, ou que declara um
+// que não aparece, reprova a loja dizendo a rota e o container. É o que impede esta tabela de envelhecer em
+// silêncio quando alguém mexe numa página. Rota editável que não estiver aqui sai SEM o campo, e o gate reprova.
+//
+// ⚠️ ROTA NOVA EM app/(loja)/ ENTRA NESTA TABELA, OU O GATE REPROVA. O nome do container é o que a página
+// (ou o componente que ela renderiza) passa em `<EditableSections container="…">`: tem de ser o MESMO aqui.
+// Página com container próprio declara o nome dele; página que só tem cabeçalho e rodapé declara `[]`.
+export const CONTAINERS_POR_ROTA: Readonly<Record<string, readonly string[]>> = {
+  "/": ["home"], // components/home/combos-home.tsx: a home é a dona do container (manda na ordem, oculta e copia)
+  "/produtos": ["catalogo"], // components/catalog/catalog-client.tsx: /produtos é a dona do container (manda na ordem)
+  "/categoria/[tagSlug]": ["catalogo"], // a categoria reaproveita o catálogo com layout={false}: mesma copy, ordem editada em /produtos
+  "/produto/[productSlug]": ["produto"], // components/product/pdp/*: um molde para todos os produtos
+  "/oferta": ["oferta"], // app/(loja)/oferta/page.tsx: a landing tem container PRÓPRIO (mesmos componentes da home, copy própria)
+  "/busca": [], // só o chrome: campo de busca e resultados do catálogo não viram primitivo (§8)
+  "/termos": [], // só o chrome: texto legal (§8)
+  "/privacidade": [], // só o chrome: texto legal (§8)
+  "/devolucoes": [], // só o chrome: texto legal (§8)
+};
+
+/** os containers que `rota` declara renderizar, fora o chrome; `undefined` = a rota não está na tabela (a loja não declarou; o gate reprova) */
+export function containersDaRota(rota: string): readonly string[] | undefined {
+  return CONTAINERS_POR_ROTA[rota];
+}
+
+/** a descoberta das páginas falhou: quem chama recusa a lista INTEIRA, com este motivo (nunca responde uma parcial) */
+export class ErroDeVarredura extends Error {}
+
+function varrer(dir: string, prefixo: string, saida: string[]) {
+  let itens: fs.Dirent[];
+  try {
+    itens = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (e) {
+    // NÃO engole: uma subpasta ilegível virava lista parcial com 200, a página sumia do seletor e o gate
+    // deixava de medi-la sem dizer NÃO RODOU. O caminho vai relativo: a mensagem é pública.
+    const codigo = (e as NodeJS.ErrnoException | null)?.code;
+    throw new ErroDeVarredura(`não consegui ler ${path.relative(process.cwd(), dir) || dir}${codigo ? ` (${codigo})` : ""}`);
+  }
+  for (const item of itens) {
+    if (item.isDirectory()) {
+      const nome = item.name;
+      // pasta privada (`_x`), slot de rota paralela (`@x`) e rota interceptada (`(.)x`) não são páginas
+      if (nome.startsWith("_") || nome.startsWith("@")) continue;
+      const grupo = /^\(.+\)$/.test(nome); // grupo de rotas: não vira segmento de URL
+      if (!grupo && nome.includes("(")) continue;
+      varrer(path.join(dir, nome), grupo ? prefixo : `${prefixo}/${nome}`, saida);
+    } else if (ARQUIVO_DE_PAGINA.test(item.name)) {
+      saida.push(prefixo || "/");
+    }
+  }
+}
+
+/** a lista do ambiente (`UNBOX_ROTAS_EDITAVEIS`, ver .env.example): só vale quando a raiz não existe, e cada defeito dela é dito */
+function rotasDoAmbiente(raizRelativa: string): string[] {
+  const bruto = process.env.UNBOX_ROTAS_EDITAVEIS;
+  if (!bruto) throw new ErroDeVarredura(`${raizRelativa} não existe (fontes ausentes no pacote da função? confira outputFileTracingIncludes em next.config.ts) e UNBOX_ROTAS_EDITAVEIS não está definida`);
+  let lista: unknown;
+  try {
+    lista = JSON.parse(bruto);
+  } catch (e) {
+    throw new ErroDeVarredura(`UNBOX_ROTAS_EDITAVEIS não é JSON válido (${e instanceof Error ? e.message : String(e)})`);
+  }
+  if (!Array.isArray(lista)) throw new ErroDeVarredura(`UNBOX_ROTAS_EDITAVEIS precisa ser uma lista JSON de rotas, como ["/","/sobre","/produto/[productSlug]"]`);
+  // CADA ENTRADA É CONFERIDA, E UMA INVÁLIDA RECUSA A LISTA INTEIRA. Filtrar a entrada errada
+  // ("produto/[productSlug]" sem a barra, um número) e responder o resto com 200 era a página digitada
+  // errada sumindo do seletor e do gate sem ninguém saber. O motivo diz QUAL entrada e POR QUÊ, para consertar
+  // de uma vez; a lista nunca é filtrada, nem deduplicada antes de ser conferida.
+  const defeitos: string[] = [];
+  lista.forEach((entrada, i) => {
+    const defeito = defeitoDaRota(entrada);
+    if (defeito) defeitos.push(`a entrada ${i + 1} (${mostrarEntrada(entrada)}) ${defeito}`);
+  });
+  if (defeitos.length) {
+    const quantas = defeitos.length === 1 ? "uma entrada inválida" : `${defeitos.length} entradas inválidas`;
+    throw new ErroDeVarredura(`UNBOX_ROTAS_EDITAVEIS foi recusada inteira porque tem ${quantas}: ${defeitos.join("; ")}. ${FORMA_DA_ROTA}`);
+  }
+  if (!lista.length) throw new ErroDeVarredura(`UNBOX_ROTAS_EDITAVEIS está vazia: precisa de pelo menos uma rota, como "/"`);
+  return [...new Set(lista as string[])].sort();
+}
+
+const FORMA_DA_ROTA = `Cada entrada precisa ser uma rota como o Next a escreve: um texto que começa com "/", sem espaço e sem barra dupla, como "/" ou "/produto/[productSlug]"`;
+
+/** o defeito de UMA entrada de `UNBOX_ROTAS_EDITAVEIS`, ou `null` quando ela é uma rota como o Next a escreve */
+function defeitoDaRota(entrada: unknown): string | null {
+  if (typeof entrada !== "string") return `não é texto (é ${tipoDaEntrada(entrada)})`;
+  if (!entrada.startsWith("/")) return `não começa com "/"`;
+  if (/\s/.test(entrada)) return "tem espaço";
+  if (entrada.includes("//")) return `tem barra dupla ("//")`;
+  return null;
+}
+
+function tipoDaEntrada(v: unknown): string {
+  if (v === null) return "nulo";
+  if (Array.isArray(v)) return "uma lista";
+  if (typeof v === "number") return "um número";
+  if (typeof v === "boolean") return "um booleano";
+  if (typeof v === "object") return "um objeto";
+  return typeof v;
+}
+
+/** a entrada como foi escrita no JSON, curta: a mensagem é pública e chega à tela do editor */
+function mostrarEntrada(entrada: unknown): string {
+  const s = JSON.stringify(entrada) ?? String(entrada);
+  return s.length > 60 ? `${s.slice(0, 57)}...` : s;
+}
+
+/**
+ * As rotas de `app/(loja)/`, com os segmentos dinâmicos como o Next os escreve
+ * (`/produto/[productSlug]`) — é essa forma que `revalidatePath(rota, "page")` entende.
+ *
+ * A varredura acontece no servidor, em tempo de execução. Em produção os fontes só existem dentro
+ * da função porque `next.config.ts` os inclui (`outputFileTracingIncludes`); se algum dia isso
+ * deixar de valer (a raiz não existe), `UNBOX_ROTAS_EDITAVEIS` (um JSON de strings) responde no
+ * lugar. Qualquer OUTRA falha (subpasta ilegível, erro de leitura, raiz sem nenhum page.tsx) estoura
+ * `ErroDeVarredura` com o motivo, e quem chama recusa a descoberta inteira: uma lista parcial com 200
+ * é a página sumindo do seletor e do gate em silêncio, que é pior do que um 500 dizendo por quê.
+ */
+export function rotasDaLoja(): string[] {
+  const raizRelativa = path.join("app", "(loja)");
+  const raiz = path.join(process.cwd(), raizRelativa);
+  if (!fs.existsSync(raiz)) return rotasDoAmbiente(raizRelativa);
+  const achadas: string[] = [];
+  varrer(raiz, "", achadas); // propaga a falha: lista parcial não é lista
+  if (!achadas.length) throw new ErroDeVarredura(`a varredura de ${raizRelativa} não achou nenhum page.tsx`);
+  return [...new Set(achadas)].sort();
+}
+
+/** As rotas que o lojista pode editar: as de `app/(loja)/` menos as que o robots bloqueia. Estoura `ErroDeVarredura` quando a descoberta falha. */
+export function rotasEditaveis(): string[] {
+  return rotasDaLoja().filter((r) => !bloqueadaPeloRobots(r));
+}

package/template/lib/sanitize.ts

@@ -0,0 +1,36 @@
+// Sanitização de HTML rico vindo do backend (product.description / additionalInformation)
+// antes de injetar via dangerouslySetInnerHTML — proteção contra XSS (doc 02/08).
+import "server-only";
+import sanitizeHtml from "sanitize-html";
+
+const OPTIONS: sanitizeHtml.IOptions = {
+  allowedTags: [
+    "p", "br", "b", "strong", "i", "em", "u", "s", "ul", "ol", "li",
+    "h1", "h2", "h3", "h4", "h5", "h6", "blockquote", "a", "span", "div",
+    "table", "thead", "tbody", "tr", "th", "td", "img", "hr",
+  ],
+  allowedAttributes: {
+    a: ["href", "title", "target", "rel"],
+    img: ["src", "alt", "width", "height"],
+    span: ["style"],
+    div: ["style"],
+    "*": ["class"],
+  },
+  allowedSchemes: ["http", "https", "mailto"],
+  // força rel seguro em links externos
+  transformTags: {
+    a: sanitizeHtml.simpleTransform("a", { rel: "nofollow noopener noreferrer" }),
+  },
+  allowedStyles: {
+    "*": {
+      "text-align": [/^left$|^right$|^center$|^justify$/],
+      "font-weight": [/^bold$|^\d{3}$/],
+      color: [/^#[0-9a-fA-F]{3,6}$/],
+    },
+  },
+};
+
+export function sanitize(html: string | null | undefined): string {
+  if (!html) return "";
+  return sanitizeHtml(html, OPTIONS);
+}

package/template/lib/schemas.ts

@@ -0,0 +1,78 @@
+// Schemas de validação (zod) usados no BFF. A fonte da verdade de validação é o servidor.
+import { z } from "zod";
+
+const digits = (s: string) => s.replace(/\D/g, "");
+
+/** DDDs em uso no Brasil (Anatel). A Unbox valida o DDD e recusa o pedido: o comprimento
+ *  sozinho não basta (testado contra produção, DDD "01" passa aqui e é recusado lá). */
+const DDD_VALIDOS = new Set([
+  11, 12, 13, 14, 15, 16, 17, 18, 19, 21, 22, 24, 27, 28, 31, 32, 33, 34, 35, 37, 38,
+  41, 42, 43, 44, 45, 46, 47, 48, 49, 51, 53, 54, 55, 61, 62, 63, 64, 65, 66, 67, 68, 69,
+  71, 73, 74, 75, 77, 79, 81, 82, 83, 84, 85, 86, 87, 88, 89, 91, 92, 93, 94, 95, 96, 97, 98, 99,
+]);
+
+/** Normaliza o telefone: só dígitos e SEM o zero à esquerda do DDD. Muita gente escreve
+ *  "011 3333-4444"; com o zero vira 12 dígitos e o DDD chega como "01", que a Unbox recusa.
+ *  Tirar o zero é entender o que a pessoa quis dizer: "011 99360-3233" vira 11993603233 e
+ *  "019 8765-4321" vira DDD 19. */
+const telefone = (s: string) => digits(s).replace(/^0+/, "");
+
+export const addressSchema = z.object({
+  fullName: z.string().min(3, "Informe o nome completo."),
+  // CPF/CNPJ: 11 ou 14 dígitos (taxPayerId é necessário na prática — doc 05)
+  taxPayerId: z.string().transform(digits).refine((v) => v.length === 11 || v.length === 14, "CPF/CNPJ inválido."),
+  postal: z.string().transform(digits).refine((v) => v.length === 8, "CEP inválido."),
+  address1: z.string().min(2, "Informe o logradouro."),
+  number: z.string().min(1, "Informe o número."),
+  neighborhood: z.string().min(1, "Informe o bairro."),
+  city: z.string().min(2, "Informe a cidade."),
+  region: z.string().length(2, "UF deve ter 2 letras."),
+  phone: z.string().transform(telefone)
+    .refine((v) => v.length >= 10 && v.length <= 11, "Telefone inválido: informe DDD e número.")
+    .refine((v) => DDD_VALIDOS.has(Number(v.slice(0, 2))), "DDD inválido. Confira o número com DDD."),
+  country: z.string().default("BR"),
+  address2: z.string().optional(),
+  cityCode: z.string().optional(),
+});
+export type AddressForm = z.infer<typeof addressSchema>;
+
+export const cardSchema = z.object({
+  cardHolder: z.string().min(3, "Nome impresso no cartão."),
+  cardNumber: z.string().transform(digits).refine((v) => v.length >= 13 && v.length <= 19, "Número do cartão inválido."),
+  expirationMonth: z.string().transform(digits).refine((v) => +v >= 1 && +v <= 12, "Mês inválido."),
+  expirationYear: z.string().transform(digits).refine((v) => v.length === 2 || v.length === 4, "Ano inválido."),
+  securityCode: z.string().transform(digits).refine((v) => v.length >= 3 && v.length <= 4, "CVV inválido."),
+  installments: z.number().int().min(1).max(12).optional(),
+});
+
+export const emailSchema = z.string().email("E-mail inválido.");
+
+export const otpSchema = z.object({
+  email: emailSchema,
+  otp: z.string().min(4, "Código inválido."),
+});
+
+// device (antifraude Unbox) coletado no navegador — 8 campos, type BROWSER.
+// timezoneOffset em MINUTOS (getTimezoneOffset(), BRT → 180) — ver ponto aberto em unbox/types.ts.
+export const deviceSchema = z.object({
+  type: z.literal("BROWSER"),
+  colorDepth: z.number(),
+  javaEnabled: z.boolean(),
+  userAgent: z.string().max(1024),
+  language: z.string().max(64),
+  screenHeight: z.number(),
+  screenWidth: z.number(),
+  timezoneOffset: z.number(),
+});
+
+export const placeOrderSchema = z.object({
+  email: emailSchema,
+  address: addressSchema,
+  payment: z.union([
+    z.object({ type: z.literal("pix") }),
+    z.object({ type: z.literal("card"), card: cardSchema }),
+  ]),
+  recurringItemsFrequencyId: z.string().optional(),
+  // opcional: se o browser não mandar, o servidor cai no fallback { type: "API" }.
+  device: deviceSchema.optional(),
+});