@unbox-plus/cli 0.20.4

package/template/lib/cart-normalize.ts

@@ -0,0 +1,142 @@
+// Normaliza o `cart` cru da Unbox (createCart.cart / anonymousCartByCartId) numa forma única
+// e estável para a UI. Mantém o preço/total SEMPRE como displayAmount do servidor (autoritativo).
+
+export interface UiCartItem {
+  id: string;            // cartItemId (node._id) — usado em update/remove
+  productId: string;
+  variantId: string;
+  title: string;
+  variantTitle?: string;
+  quantity: number;
+  unitPrice: number;
+  displayUnitPrice: string;
+  thumbnail?: string;
+  isRecurring?: boolean;
+  isBonus: boolean;      // isDiscountedBonusItem (brinde) — R$0, excluído do placeOrder
+}
+
+export interface UiShippingAddress {
+  fullName: string;
+  taxPayerId: string;
+  phone: string;
+  address1: string;
+  address2?: string;
+  number: string;
+  neighborhood: string;
+  city: string;
+  region: string;
+  postal: string;
+}
+
+// Placeholders gravados pela cotação de frete antes do endereço estar completo (ver
+// quoteAddress() em checkout-client.tsx) — nunca são endereço real, filtrar ao ler de volta.
+const QUOTE_PLACEHOLDERS = new Set(["Cotação", "—", "0", "00000000000"]);
+
+function cleanAddressField(v: unknown): string {
+  const s = typeof v === "string" ? v.trim() : "";
+  return QUOTE_PLACEHOLDERS.has(s) ? "" : s;
+}
+
+/** Endereço de entrega já gravado no carrinho (se houver), com placeholders de cotação removidos. */
+export function extractShippingAddress(cart: any): UiShippingAddress | null {
+  const fg = cart?.checkout?.fulfillmentGroups ?? [];
+  const raw = fg.find((g: any) => g.data?.shippingAddress)?.data?.shippingAddress;
+  if (!raw) return null;
+  const addr: UiShippingAddress = {
+    fullName: cleanAddressField(raw.fullName),
+    taxPayerId: cleanAddressField(raw.taxPayerId),
+    phone: cleanAddressField(raw.phone),
+    address1: cleanAddressField(raw.address1),
+    address2: cleanAddressField(raw.address2),
+    number: cleanAddressField(raw.number),
+    neighborhood: cleanAddressField(raw.neighborhood),
+    city: cleanAddressField(raw.city),
+    region: cleanAddressField(raw.region),
+    postal: cleanAddressField(raw.postal),
+  };
+  // Se sobrou só CEP/cidade/UF (da cotação) e nada do resto, não é um endereço "salvo" de verdade.
+  const hasSubstance = addr.address1 || addr.fullName || addr.number;
+  return hasSubstance ? addr : null;
+}
+
+export interface UiCart {
+  cartId: string;
+  totalItemQuantity: number;
+  expiresAt?: string;
+  email?: string;
+  shippingAddress?: UiShippingAddress | null;
+  recurringItemsFrequencyId?: string | null;
+  hasRecurring: boolean;
+  /** Frequência de assinatura escolhida (resolvida do cookie + política da loja). */
+  recurringFrequencyId?: string;
+  recurringFrequencyTitle?: string;
+  items: UiCartItem[];
+  discounts: Array<{ id: string; code?: string; displayAmount?: string }>;
+  fulfillmentGroupIds: string[];
+  selectedShipping?: { methodId: string; displayName?: string; displayAmount?: string } | null;
+  summary: {
+    itemTotal?: string;
+    discountTotal?: string;
+    shippingTotal?: string;
+    taxTotal?: string;
+    total?: string;
+    totalAmount?: number;
+  };
+  cartEvents: Array<{ type: string; data?: any }>;
+}
+
+export function normalizeCart(cart: any, extraEvents: any[] = []): UiCart | null {
+  if (!cart) return null;
+  const edges = cart.items?.edges ?? [];
+  const items: UiCartItem[] = edges.map((e: any) => {
+    const n = e.node;
+    return {
+      id: n._id,
+      productId: n.productConfiguration?.productId,
+      variantId: n.productConfiguration?.productVariantId,
+      title: n.title,
+      variantTitle: n.variantTitle,
+      quantity: n.quantity,
+      unitPrice: n.price?.amount ?? 0,
+      displayUnitPrice: n.price?.displayAmount ?? "—",
+      thumbnail: n.thumbnail || undefined,
+      isRecurring: n.isRecurring ?? false,
+      isBonus: n.isDiscountedBonusItem === true,
+    };
+  });
+
+  const fg = cart.checkout?.fulfillmentGroups ?? [];
+  const selected = fg.find((g: any) => g.selectedFulfillmentOption)?.selectedFulfillmentOption;
+  const summary = cart.checkout?.summary ?? {};
+
+  return {
+    cartId: cart._id,
+    totalItemQuantity: cart.totalItemQuantity ?? items.reduce((s, i) => s + i.quantity, 0),
+    expiresAt: cart.expiresAt,
+    email: cart.email || undefined,
+    shippingAddress: extractShippingAddress(cart),
+    recurringItemsFrequencyId: cart.recurringItemsFrequencyId ?? null,
+    hasRecurring: items.some((i) => i.isRecurring),
+    items,
+    discounts: (cart.appliedDiscounts ?? cart.discounts ?? []).map((d: any) => ({
+      id: d._id, code: d.code, displayAmount: d.amount?.displayAmount,
+    })),
+    fulfillmentGroupIds: fg.map((g: any) => g._id),
+    selectedShipping: selected
+      ? {
+          methodId: selected.fulfillmentMethod?._id,
+          displayName: selected.fulfillmentMethod?.displayName ?? selected.fulfillmentMethod?.name,
+          displayAmount: selected.price?.displayAmount,
+        }
+      : null,
+    summary: {
+      itemTotal: summary.itemTotal?.displayAmount,
+      discountTotal: summary.discountTotal?.displayAmount,
+      shippingTotal: summary.fulfillmentTotal?.displayAmount,
+      taxTotal: summary.taxTotal?.displayAmount,
+      total: summary.total?.displayAmount,
+      totalAmount: summary.total?.amount,
+    },
+    cartEvents: [...(cart.cartEvents ?? []), ...extraEvents],
+  };
+}

package/template/lib/cart-recovery.ts

@@ -0,0 +1,23 @@
+// Link de recuperação de carrinho — formato ÚNICO usado em todo o projeto.
+// Abrir o link em qualquer browser restaura o carrinho: o CartProvider lê ?id=&token=
+// e chama /api/cart/link, que regrava o cookie e reidrata (mesma convenção do link
+// nativo da Unbox, ex.: finalizar-pedido?...&step=1).
+//
+// Sem "server-only" de propósito: o cron de abandono (scripts/abandoned-cart.ts) roda
+// fora do Next e precisa montar o MESMO link.
+
+export function buildRecoveryUrl(
+  siteUrl: string,
+  cartId: string,
+  cartToken: string,
+  /** Carrinho de assinatura: a frequência vive só em cookie — sem ela no link, o cliente
+   *  reabre o checkout sem frequência e não consegue finalizar. */
+  recurringItemsFrequencyId?: string | null,
+): string {
+  // Checkout hospedado (UNBOX_HOSTED_CHECKOUT_URL): o /checkout deste projeto nem existe —
+  // o link tem que cair no checkout da Unbox, com o mesmo ?id=&token=.
+  const base = process.env.UNBOX_HOSTED_CHECKOUT_URL || `${siteUrl.replace(/\/+$/, "")}/checkout`;
+  let url = `${base}?id=${encodeURIComponent(cartId)}&token=${encodeURIComponent(cartToken)}`;
+  if (recurringItemsFrequencyId) url += `&freq=${encodeURIComponent(recurringItemsFrequencyId)}`;
+  return url + "&step=1";
+}

package/template/lib/cart-response.ts

@@ -0,0 +1,48 @@
+// Monta a resposta de carrinho para o BFF: normaliza + anexa a FREQUÊNCIA de assinatura
+// (a frequência não vive no carrinho da Unbox — está no cookie; o título vem da política da loja).
+import "server-only";
+import { normalizeCart, type UiCart } from "./cart-normalize";
+import { getRecurFreq } from "./session";
+import { getShopData, getCatalog } from "./queries";
+
+// Brindes/bônus liberados automaticamente pela Unbox (ex.: item grátis ao atingir um valor no
+// carrinho) não vêm com `thumbnail` na linha do carrinho, mesmo o produto tendo foto real
+// cadastrada — completa buscando no catálogo por productId (já cacheado por getCatalog).
+async function fillMissingThumbnails(cart: UiCart): Promise<void> {
+  const missing = cart.items.filter((i) => !i.thumbnail);
+  if (!missing.length) return;
+  try {
+    const catalog = await getCatalog({ first: 100 });
+    const imageByProductId = new Map<string, string>();
+    for (const n of catalog.nodes ?? []) {
+      const p = n.product ?? n;
+      if (p?.productId && p?.imageUrls?.[0]) imageByProductId.set(p.productId, p.imageUrls[0]);
+    }
+    for (const item of missing) {
+      const url = imageByProductId.get(item.productId);
+      if (url) item.thumbnail = url;
+    }
+  } catch {
+    /* foto é cosmética — nunca quebra a resposta do carrinho */
+  }
+}
+
+export async function cartResponse(rawCart: any, extraEvents: any[] = []): Promise<UiCart | null> {
+  const cart = normalizeCart(rawCart, extraEvents);
+  if (!cart) return null;
+  await fillMissingThumbnails(cart);
+  if (cart.hasRecurring) {
+    const freqId = await getRecurFreq();
+    if (freqId) {
+      cart.recurringFrequencyId = freqId;
+      try {
+        const shop = await getShopData();
+        const f = (shop?.recurringOrdersPolicy?.allowedFrequencies ?? []).find((x: any) => x._id === freqId);
+        if (f?.title) cart.recurringFrequencyTitle = f.title;
+      } catch {
+        /* sem título não quebra a UI */
+      }
+    }
+  }
+  return cart;
+}

package/template/lib/catalog-map.ts

@@ -0,0 +1,54 @@
+// Mapeia o catálogo cru da Unbox para os itens do catálogo da loja (client-side filtering).
+import { resolveProductPrice, parseBRL } from "@/lib/format";
+import type { CatalogProductItem, CatalogCategory } from "@/components/catalog/catalog-client";
+
+export function buildTagMap(tags: any[]): Map<string, string> {
+  const m = new Map<string, string>();
+  for (const t of tags ?? []) if (t?.isVisible !== false) m.set(t._id, t.displayTitle || t.name);
+  return m;
+}
+
+export function buildCategories(tags: any[]): CatalogCategory[] {
+  return (tags ?? [])
+    .filter((t: any) => t?.isVisible !== false)
+    .sort((a: any, b: any) => (a.position ?? 0) - (b.position ?? 0))
+    .map((t: any): CatalogCategory => ({ name: t.displayTitle || t.name, slug: t.slug }));
+}
+
+export function mapCatalogItems(nodes: any[], tagMap: Map<string, string>): CatalogProductItem[] {
+  return (nodes ?? [])
+    .map((n: any) => n.product ?? n)
+    .filter((p: any) => p?.slug)
+    .map((p: any): CatalogProductItem => {
+      const v0 = p.variants?.[0];
+      const rp = resolveProductPrice(p);
+      const price = v0?.pricing?.[0]?.price ?? rp.price ?? 0;
+      const displayOld = v0?.pricing?.[0]?.compareAtPrice?.displayAmount ?? rp.compareAt ?? null;
+      const oldPrice = parseBRL(displayOld);
+      const hasOld = oldPrice != null && oldPrice > price;
+      const offPct = hasOld && oldPrice ? Math.round((1 - price / oldPrice) * 100) : null;
+      const categories = ((p.tagIds ?? []) as string[]).map((id) => tagMap.get(id)).filter(Boolean) as string[];
+      return {
+        slug: p.slug,
+        title: p.title,
+        weight: v0?.title ?? "",
+        categories,
+        price,
+        displayPrice: rp.displayPrice,
+        oldPrice: hasOld ? oldPrice : null,
+        displayOld: hasOld ? displayOld : null,
+        offPct,
+        imageUrl: p.imageUrls?.[0] ?? null,
+        productId: p.productId,
+        variantId: v0?._id ?? null,
+        badge: p.isSoldOut
+          ? { label: "ESGOTADO", bg: "var(--store-surface-2)", fg: "var(--store-muted)" }
+          : hasOld
+            ? { label: "OFERTA", bg: "var(--store-sale-soft)", fg: "var(--store-sale)" }
+            : p.isLowQuantity
+              ? { label: "ÚLTIMAS", bg: "var(--store-cta-soft)", fg: "var(--store-cta-dark)" }
+              : null,
+        soldOut: !!p.isSoldOut,
+      };
+    });
+}

package/template/lib/catalog.ts

@@ -0,0 +1,3 @@
+// Helpers puros do catálogo (server/client safe).
+
+export const PAGE_SIZE = 24;

package/template/lib/checkout-lock.ts

@@ -0,0 +1,21 @@
+// Lock de checkout por cartId (doc 11): placeOrder NÃO é idempotente e cobra na hora.
+// Evita que dois cliques / duas requisições concorrentes do mesmo carrinho gerem DOIS pedidos.
+//
+// PROD: trocar por lock distribuído (Vercel KV SET NX com TTL / Redis). Em dev é em memória.
+import "server-only";
+
+const locks = new Map<string, number>(); // cartId -> expiresAt
+const TTL_MS = 60 * 1000;
+
+/** Tenta adquirir o lock. Retorna false se já há um placeOrder em voo para este cartId. */
+export function acquireCheckoutLock(cartId: string): boolean {
+  const now = Date.now();
+  const exp = locks.get(cartId);
+  if (exp && exp > now) return false;
+  locks.set(cartId, now + TTL_MS);
+  return true;
+}
+
+export function releaseCheckoutLock(cartId: string): void {
+  locks.delete(cartId);
+}

package/template/lib/checkout-nav.ts

@@ -0,0 +1,22 @@
+"use client";
+
+// Navega pro checkout — decidido pelo SERVIDOR (nunca no client), porque a rota real depende de
+// UNBOX_HOSTED_CHECKOUT_URL (checkout padrão hospedado pela Unbox, doc 06) e essa variável não é
+// NEXT_PUBLIC_. Se configurada, o destino é externo (mesmo domínio da loja, path
+// /carrinho/finalizar-pedido, com ?id=&token=&freq=&step= — o servidor monta a URL completa,
+// nunca o client, porque cartToken é httpOnly e não pode ser lido em JS). Sem a variável, cai no
+// /checkout interno de sempre.
+export async function goToCheckout(router: { push: (href: string) => void }): Promise<void> {
+  try {
+    const res = await fetch("/api/checkout-destination");
+    const data = await res.json().catch(() => ({}));
+    const url: string = data?.url || "/checkout";
+    if (/^https?:\/\//i.test(url)) {
+      window.location.href = url; // destino externo — precisa de navegação completa, não router.push
+    } else {
+      router.push(url);
+    }
+  } catch {
+    router.push("/checkout");
+  }
+}

package/template/lib/config.ts

@@ -0,0 +1,51 @@
+// Configuração central — lê variáveis de ambiente (server-only) e expõe os identificadores
+// públicos da loja. NUNCA exporte segredos para o cliente daqui.
+import "server-only";
+import { checkEnv } from "./env-check";
+
+// UNBOX_API_KEY/USER/PASS são lidos sem lançar erro aqui — esse módulo é importado
+// pelo layout raiz (toda página), então validar no import quebraria o app inteiro
+// sem credenciais. A validação acontece em lib/unbox/store.ts, só quando uma página
+// de fato tenta buscar dados da API (permite "modo mockup" sem credenciais).
+export const serverEnv = {
+  apiKey: process.env.UNBOX_API_KEY ?? "",
+  user: process.env.UNBOX_USER ?? "",
+  pass: process.env.UNBOX_PASS ?? "",
+  shopId: process.env.UNBOX_SHOP_ID ?? "",
+  shopSlug: process.env.UNBOX_SHOP_SLUG ?? "",
+  authUrl: process.env.UNBOX_AUTH_URL ?? "https://api.unbox.com.br",
+  gqlUrl: process.env.UNBOX_GRAPHQL_URL ?? "https://core.unbox.com.br/graphql",
+  // API pública de PARCEIROS (nova): uma api key única por parceiro, independente do nº de
+  // lojas. Setar UNBOX_PARTNER_API_KEY liga o roteamento: signIn + leituras com paridade
+  // passam por partners.unbox.com.br; o restante (carrinho/checkout/cliente) segue no core
+  // até a Unbox liberar as escritas na API de parceiros. Ver lib/unbox/client.ts.
+  partnerApiKey: process.env.UNBOX_PARTNER_API_KEY ?? "",
+  partnerGqlUrl: process.env.UNBOX_PARTNER_GRAPHQL_URL ?? "https://partners.unbox.com.br/graphql",
+  captchaBypass: process.env.UNBOX_CAPTCHA_BYPASS ?? "",
+  webhookSecret: process.env.UNBOX_WEBHOOK_SECRET ?? "",
+  sessionSecret: process.env.SESSION_SECRET ?? "dev-insecure-session-secret-change-me",
+  crmWebhookUrl: process.env.CRM_WEBHOOK_URL ?? "",
+  revalidateSecret: process.env.REVALIDATE_SECRET ?? "",
+};
+
+// No modelo antigo a loja tem api key própria; no novo, a key é do PARCEIRO. Qualquer uma
+// das duas + user/pass da loja habilita o modo real (sem nenhuma → modo mockup).
+export const hasUnboxCredentials = Boolean(
+  (serverEnv.apiKey || serverEnv.partnerApiKey) && serverEnv.user && serverEnv.pass,
+);
+
+/** Decodifica os claims do JWT (sem validar — só para extrair shopId/shopSlug). */
+export function decodeJwtClaims(jwt: string): Record<string, any> {
+  try {
+    const payload = jwt.split(".")[1];
+    const json = Buffer.from(payload.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf-8");
+    return JSON.parse(json);
+  } catch {
+    return {};
+  }
+}
+
+export const SHOP_ID_CLAIM = "arn:unbox:shopId";
+export const SHOP_SLUG_CLAIM = "arn:unbox:shopSlug";
+
+checkEnv();

package/template/lib/crm.ts

@@ -0,0 +1,40 @@
+// Integração de CRM (carrinho abandonado / e-mails transacionais) — doc 10/11.
+// A recuperação de carrinho é responsabilidade do storefront: ele detecta o abandono e
+// dispara pelo CRM da loja (Revi/Klaviyo). Aqui fazemos um POST real para CRM_WEBHOOK_URL
+// quando configurada.
+import "server-only";
+import { serverEnv } from "./config";
+
+export interface CrmEvent {
+  /** `checkout_started` sai na hora em que o e-mail é gravado no carrinho e SEMPRE carrega
+   *  `recoveryUrl` — é ele que arma o fluxo de abandono no CRM (espere N min; se não chegar
+   *  `order_created` com o mesmo cartId/email, envie o e-mail com o recoveryUrl). */
+  type: "checkout_started" | "abandoned_cart" | "order_created" | "order_paid";
+  email?: string;
+  cartId?: string;
+  orderId?: string;
+  referenceId?: string;
+  /** Link pronto pra restaurar o carrinho (/checkout?id=&token=&freq=&step=) — top-level pra
+   *  quem consumir o webhook (Klaviyo/Revi) achar fácil, sem precisar abrir o payload. */
+  recoveryUrl?: string;
+  payload?: Record<string, any>;
+}
+
+/** Dispara um evento para o CRM. No-op (apenas log) se CRM_WEBHOOK_URL não estiver configurada. */
+export async function dispatchCrm(event: CrmEvent): Promise<{ ok: boolean; skipped?: boolean }> {
+  if (!serverEnv.crmWebhookUrl) {
+    console.info("[crm] CRM_WEBHOOK_URL não configurada — evento ignorado:", event.type);
+    return { ok: true, skipped: true };
+  }
+  try {
+    const res = await fetch(serverEnv.crmWebhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ source: "unbox-storefront", ...event, at: new Date().toISOString() }),
+    });
+    return { ok: res.ok };
+  } catch (e) {
+    console.error("[crm] falha ao despachar evento", e);
+    return { ok: false };
+  }
+}

package/template/lib/customer-session.ts

@@ -0,0 +1,21 @@
+// Factory do UnboxCustomerClient a partir do cookie httpOnly do cliente (área "minha conta").
+// Lança 401 implícito devolvendo null quando não há token.
+import "server-only";
+import { UnboxCustomerClient } from "./unbox/customer";
+import { getCustomerToken } from "./session";
+import { getShopContext } from "./unbox/store";
+
+/** Retorna um UnboxCustomerClient autenticado, ou null se o cliente não estiver logado. */
+export async function getCustomerClient(): Promise<UnboxCustomerClient | null> {
+  const token = await getCustomerToken();
+  if (!token) return null;
+  const { shopId } = await getShopContext();
+  return new UnboxCustomerClient({ token, shopId });
+}
+
+/** Igual ao acima, mas lança um Error 401-like se não logado (para Route Handlers). */
+export async function requireCustomerClient(): Promise<UnboxCustomerClient> {
+  const c = await getCustomerClient();
+  if (!c) throw new Error("UNAUTHENTICATED");
+  return c;
+}

package/template/lib/dataloader.ts

@@ -0,0 +1,23 @@
+// Paginação completa do catálogo por offset (doc 11): NÃO confiar num `first` gigante (há teto
+// de servidor que trunca em silêncio). Itera em lotes até pageInfo.hasNextPage === false.
+import "server-only";
+import { withStoreClient } from "./unbox/store";
+
+const PAGE = 100;
+
+/** Carrega TODOS os itens visíveis do catálogo (para sitemap e listagens completas). */
+export async function loadAllCatalogItems(opts: { tagIds?: string[]; searchText?: string } = {}): Promise<any[]> {
+  const all: any[] = [];
+  let offset = 0;
+  // teto de segurança para não loopar infinito caso a API mude o contrato
+  for (let guard = 0; guard < 100; guard++) {
+    const page = await withStoreClient((c) =>
+      c.getCatalog({ first: PAGE, offset, tagIds: opts.tagIds, searchText: opts.searchText }),
+    );
+    const nodes = page.nodes ?? [];
+    all.push(...nodes);
+    if (!page.pageInfo?.hasNextPage || nodes.length === 0) break;
+    offset += PAGE;
+  }
+  return all;
+}

package/template/lib/editable/config.ts

@@ -0,0 +1,11 @@
+// Identidade desta loja PARA O EDITOR. O CLI carimba o literal no scaffold; EDITOR_URL vem do
+// ambiente (sem ele, o editor fica desligado).
+//
+// `UNBOX_EDITOR_SHOP` é variável PRÓPRIA, de propósito: não reuse `UNBOX_SHOP_SLUG`, que é o slug
+// da loja NA PLATAFORMA (sai do JWT). Os dois costumam coincidir e no dia em que divergirem o
+// editor deixa de achar a loja sem dizer por quê. Este nome tem de bater com o `slug` da entrada
+// dela no shops.json do editor.
+export const STORE_SLUG = process.env.UNBOX_EDITOR_SHOP || "__STORE_SLUG__";
+export const EDITOR_URL = (process.env.EDITOR_URL || "").replace(/\/+$/, "");
+/** Origem do editor vista pelo navegador (frame-ancestors + postMessage). */
+export const EDITOR_ORIGIN = process.env.NEXT_PUBLIC_EDITOR_ORIGIN || "";