@unbox-plus/cli 0.20.4

package/template/app/api/cart/share/route.ts

@@ -0,0 +1,21 @@
+// Gera o link compartilhável do carrinho atual: lê {cartId, cartToken} do cookie httpOnly e
+// monta a URL de restauração (ver app/api/cart/link/route.ts, modo id+token). Quem tem o link
+// tem o carrinho — e-mail/endereço/CPF ficam legíveis e editáveis por quem abrir (ver doc 12).
+import { getCartRef, getRecurFreq } from "@/lib/session";
+import { ok, fail } from "@/lib/api";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(req: Request) {
+  const ref = await getCartRef();
+  if (!ref) return fail("Nenhum carrinho ativo para compartilhar.", 404);
+  const origin = new URL(req.url).origin;
+  // No modo hospedado o /checkout deste projeto não existe: o link vai pro checkout da Unbox.
+  const base = process.env.UNBOX_HOSTED_CHECKOUT_URL || `${origin}/checkout`;
+  let url = `${base}?id=${encodeURIComponent(ref.cartId)}&token=${encodeURIComponent(ref.cartToken)}`;
+  // A frequência de assinatura vive só em cookie — sem incluí-la, restaurar esse link em outra
+  // sessão perde a frequência escolhida (ver app/api/cart/link/route.ts).
+  const freq = await getRecurFreq();
+  if (freq) url += `&freq=${encodeURIComponent(freq)}`;
+  return ok({ url });
+}

package/template/app/api/cep/[code]/route.ts

@@ -0,0 +1,18 @@
+// Autocomplete de endereço por CEP (getAddressByPostalCode). Usado no checkout e address book.
+import { withStoreClient } from "@/lib/unbox/store";
+import { ok, fail, failFrom } from "@/lib/api";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(_req: Request, { params }: { params: Promise<{ code: string }> }) {
+  try {
+    const { code } = await params;
+    const cep = (code ?? "").replace(/\D/g, "");
+    if (cep.length !== 8) return fail("CEP inválido.", 422);
+    const addr = await withStoreClient((c) => c.getAddressByPostalCode(cep));
+    if (!addr) return fail("CEP não encontrado.", 404);
+    return ok({ address: addr });
+  } catch (e) {
+    return failFrom(e);
+  }
+}

package/template/app/api/checkout/address/route.ts

@@ -0,0 +1,24 @@
+// Define o endereço de entrega no carrinho → devolve os ids dos fulfillmentGroups.
+import { withStoreClient } from "@/lib/unbox/store";
+import { getCartRef } from "@/lib/session";
+import { ok, fail, failFrom } from "@/lib/api";
+import { addressSchema } from "@/lib/schemas";
+
+export const dynamic = "force-dynamic";
+
+// POST /api/checkout/address { address }
+export async function POST(req: Request) {
+  try {
+    const ref = await getCartRef();
+    if (!ref) return fail("Carrinho não encontrado.", 404);
+    const body = await req.json();
+    const parsed = addressSchema.safeParse(body.address);
+    if (!parsed.success) return fail("Endereço inválido. Confira os campos.", 422, { issues: parsed.error.flatten() });
+
+    await withStoreClient((c) => c.setShippingAddress(ref.cartId, ref.cartToken, parsed.data as any));
+    const groupIds = await withStoreClient((c) => c.getFulfillmentGroupIds(ref.cartId, ref.cartToken));
+    return ok({ fulfillmentGroupIds: groupIds });
+  } catch (e) {
+    return failFrom(e);
+  }
+}

package/template/app/api/checkout/email/route.ts

@@ -0,0 +1,41 @@
+// Grava o e-mail no carrinho (etapa de contato) → habilita recuperação de carrinho abandonado.
+// Chamado pelo checkout assim que o e-mail é válido, antes do placeOrder.
+//
+// É AQUI que o carrinho vira recuperável: com o e-mail gravado, despachamos pro CRM o
+// ponteiro completo (cartId + link pronto com id/token/freq). Sem este evento, o id+token
+// vive só no cookie do cliente e nenhum cron/CRM tem como montar o e-mail de recuperação.
+import { withStoreClient } from "@/lib/unbox/store";
+import { getCartRef, getRecurFreq } from "@/lib/session";
+import { ok, fail, failFrom } from "@/lib/api";
+import { emailSchema } from "@/lib/schemas";
+import { dispatchCrm } from "@/lib/crm";
+import { buildRecoveryUrl } from "@/lib/cart-recovery";
+
+export const dynamic = "force-dynamic";
+
+// POST /api/checkout/email { email }
+export async function POST(req: Request) {
+  try {
+    const ref = await getCartRef();
+    if (!ref) return fail("Carrinho não encontrado.", 404);
+    const body = await req.json();
+    const parsed = emailSchema.safeParse(body.email);
+    if (!parsed.success) return fail("E-mail inválido.", 422);
+
+    await withStoreClient((c) => c.setEmailOnCart(ref.cartId, ref.cartToken, parsed.data));
+
+    // Fire-and-forget: falha de CRM nunca pode travar o checkout.
+    const siteUrl = process.env.NEXT_PUBLIC_SITE_URL ?? "http://localhost:3000";
+    const freq = await getRecurFreq();
+    dispatchCrm({
+      type: "checkout_started",
+      email: parsed.data,
+      cartId: ref.cartId,
+      recoveryUrl: buildRecoveryUrl(siteUrl, ref.cartId, ref.cartToken, freq),
+    }).catch(() => {});
+
+    return ok({ ok: true });
+  } catch (e) {
+    return failFrom(e);
+  }
+}

package/template/app/api/checkout/installments/route.ts

@@ -0,0 +1,16 @@
+// Parcelas (sem juros) para um valor — exibição no checkout (cartão, não assinatura).
+import { withStoreClient } from "@/lib/unbox/store";
+import { ok, fail, failFrom } from "@/lib/api";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(req: Request) {
+  const amount = Number(new URL(req.url).searchParams.get("amount"));
+  if (!Number.isFinite(amount) || amount <= 0) return fail("Valor inválido.", 400);
+  try {
+    const installments = await withStoreClient((c) => c.getInstallments(amount));
+    return ok({ installments });
+  } catch (e) {
+    return failFrom(e, 502);
+  }
+}

package/template/app/api/checkout/route.ts

@@ -0,0 +1,110 @@
+// placeOrder — PRODUÇÃO REAL e NÃO-idempotente (doc 11). Proteções:
+//  - rate-limit por IP
+//  - lock por cartId (recusa chamadas concorrentes do mesmo carrinho)
+//  - RELÊ o carrinho imediatamente antes (estado final: itens sem brindes + total do servidor)
+//  - exige frete já selecionado
+//  - em erro: NÃO retenta cegamente (poderia gerar cobrança dupla)
+//  - sucesso: grava token de posse (cookie) e INVALIDA o carrinho
+import { withStoreClient } from "@/lib/unbox/store";
+import { getCartRef, setOrderToken, clearCartRef, getRecurFreq } from "@/lib/session";
+import { acquireCheckoutLock, releaseCheckoutLock } from "@/lib/checkout-lock";
+import { rateLimit, clientIp, LIMITS } from "@/lib/ratelimit";
+import { dispatchCrm } from "@/lib/crm";
+import { placeOrderSchema } from "@/lib/schemas";
+import { ok, fail, failFrom } from "@/lib/api";
+import { isUnboxTimeout } from "@/lib/unbox/client";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(req: Request) {
+  const ip = clientIp(req);
+  const rl = rateLimit(`checkout:${ip}`, LIMITS.checkout.limit, LIMITS.checkout.windowMs);
+  if (!rl.ok) return fail("Muitas tentativas. Aguarde um instante.", 429);
+
+  const ref = await getCartRef();
+  if (!ref) return fail("Carrinho não encontrado.", 404);
+
+  const body = await req.json().catch(() => null);
+  const parsed = placeOrderSchema.safeParse(body);
+  if (!parsed.success) return fail("Dados de pagamento inválidos.", 422, { issues: parsed.error.flatten() });
+
+  if (!acquireCheckoutLock(ref.cartId)) {
+    return fail("Já existe um pedido em andamento para este carrinho.", 409);
+  }
+
+  try {
+    const { email, address, payment, recurringItemsFrequencyId, device } = parsed.data;
+
+    // RELEITURA do carrinho — estado final real (doc 11): evita FULFILLMENT_GROUP_AND_CART_ITEMS_DO_NOT_MATCH_ERROR
+    const cart = await withStoreClient((c) => c.getCart(ref.cartId, ref.cartToken));
+    if (!cart) return fail("Carrinho expirado. Recomece a compra.", 410);
+
+    const selected = (cart.checkout?.fulfillmentGroups ?? []).find((g: any) => g.selectedFulfillmentOption);
+    const fulfillmentMethodId = selected?.selectedFulfillmentOption?.fulfillmentMethod?._id;
+    if (!fulfillmentMethodId) return fail("Selecione uma opção de frete antes de pagar.", 422);
+
+    const total = cart.checkout?.summary?.total?.amount;
+    if (typeof total !== "number") return fail("Não foi possível calcular o total.", 422);
+
+    // Assinatura: o carrinho tem item(ns) isRecurring? A frequência veio em cookie (preferência) ou no body.
+    const hasRecurring = (cart.items?.edges ?? []).some((e: any) => e.node?.isRecurring === true);
+    const freqId = (await getRecurFreq()) ?? recurringItemsFrequencyId ?? undefined;
+    if (hasRecurring) {
+      if (payment.type !== "card") return fail("Assinaturas exigem pagamento com cartão de crédito.", 422);
+      if (!freqId) return fail("Selecione a frequência da assinatura.", 422);
+    }
+
+    const order = await withStoreClient((c) => {
+      const items = c.buildOrderItems(cart); // TODOS os itens, com flags isRecurring/isDiscountedBonusItem (casar c/ o carrinho — senão 502)
+      return c.placeOrder({
+        cartId: ref.cartId,
+        email,
+        address: address as any,
+        fulfillmentMethodId,
+        total,
+        items,
+        payment: payment.type === "pix" ? { type: "pix" } : { type: "card", card: payment.card as any },
+        recurrence: hasRecurring && freqId ? { recurringItemsFrequencyId: freqId } : undefined,
+        // antifraude: device coletado no browser; sem ele o client envia { type: "API" }.
+        device,
+      });
+    });
+
+    const placed = order.orders?.[0];
+    if (!placed) return fail("Não foi possível concluir o pedido.", 502);
+
+    // posse do pedido (guest) + invalida o carrinho (não reutilizar o cartId)
+    if (placed.referenceId && order.token) await setOrderToken(placed.referenceId, order.token);
+    await clearCartRef();
+
+    // CRM (efeito real se CRM_WEBHOOK_URL estiver configurada)
+    // cartId incluso pro CRM conseguir CANCELAR o fluxo de abandono armado no checkout_started.
+    dispatchCrm({ type: "order_created", email, cartId: ref.cartId, orderId: placed._id, referenceId: placed.referenceId }).catch(() => {});
+
+    const pix = placed.payments?.find((p: any) => p?.data?.qrCode)?.data ?? null;
+    return ok({
+      referenceId: placed.referenceId,
+      status: placed.status,
+      paymentType: payment.type,
+      total: placed.summary?.total?.displayAmount,
+      pix: pix ? { qrCode: pix.qrCode } : null,
+      recurringOrderId: placed.recurringOrderId ?? null,
+    });
+  } catch (e) {
+    // ⚠️ NÃO retentar: em timeout/erro o pedido pode ter sido criado. Orientar o cliente a entrar
+    // e checar "meus pedidos" (/conta/pedidos) antes de tentar de novo (evita cobrança dupla).
+    if (isUnboxTimeout(e)) {
+      // Estado DESCONHECIDO: sem resposta dentro do prazo, o pedido pode ter sido criado e cobrado. O
+      // código PLACE_ORDER_TIMEOUT diz ao checkout-client pra NÃO reabrir o botão de pagar.
+      console.error(JSON.stringify({ tag: "[api-erro]", status: 504, erro: "PLACE_ORDER_TIMEOUT", rota: "checkout", cartId: ref.cartId, quando: new Date().toISOString() }));
+      return fail(
+        "O pagamento demorou mais que o esperado e não sabemos se foi concluído. Não pague de novo: confira em Meus pedidos ou no seu e-mail antes de tentar outra vez.",
+        504,
+        { code: "PLACE_ORDER_TIMEOUT" },
+      );
+    }
+    return failFrom(e, 502, { rota: "checkout", cartId: ref.cartId });
+  } finally {
+    releaseCheckoutLock(ref.cartId);
+  }
+}

package/template/app/api/checkout/shipping/route.ts

@@ -0,0 +1,65 @@
+// Frete: POST cota TODOS os grupos (doc 11 — N grupos, não 1); PUT seleciona o método por grupo.
+import { withStoreClient } from "@/lib/unbox/store";
+import { getCartRef } from "@/lib/session";
+import { cartResponse } from "@/lib/cart-response";
+import { ok, fail, failFrom } from "@/lib/api";
+
+export const dynamic = "force-dynamic";
+
+// POST /api/checkout/shipping → { groups: [{ groupId, options:[{methodId,name,displayName,price,days}] }] }
+export async function POST() {
+  try {
+    const ref = await getCartRef();
+    if (!ref) return fail("Carrinho não encontrado.", 404);
+
+    const groups = await withStoreClient(async (c) => {
+      const ids = await c.getFulfillmentGroupIds(ref.cartId, ref.cartToken);
+      const out = [];
+      for (const groupId of ids) {
+        const opts = await c.quoteShipping(ref.cartId, ref.cartToken, groupId); // obrigatório (senão options vem vazio)
+        out.push({
+          groupId,
+          options: opts.map((o) => ({
+            methodId: o.fulfillmentMethod._id,
+            name: o.fulfillmentMethod.name,
+            displayName: o.fulfillmentMethod.displayName ?? o.fulfillmentMethod.name,
+            price: o.price?.displayAmount,
+            discountPrice: o.discountPrice?.displayAmount,
+            days: o.fulfillmentMethod.daysToDeliver,
+          })),
+        });
+      }
+      return out;
+    });
+
+    if (!groups.length || groups.every((g) => g.options.length === 0)) {
+      return fail("Não há opções de entrega para este CEP.", 422);
+    }
+    return ok({ groups });
+  } catch (e) {
+    return failFrom(e);
+  }
+}
+
+// PUT /api/checkout/shipping { selections: [{ groupId, methodId }] } → seleciona e devolve o carrinho final
+export async function PUT(req: Request) {
+  try {
+    const ref = await getCartRef();
+    if (!ref) return fail("Carrinho não encontrado.", 404);
+    const { selections } = await req.json();
+    if (!Array.isArray(selections) || !selections.length) return fail("Selecione o frete.");
+
+    const finalCart = await withStoreClient(async (c) => {
+      let last: any = null;
+      for (const s of selections) {
+        last = await c.selectShipping(ref.cartId, ref.cartToken, s.groupId, s.methodId);
+      }
+      return last;
+    });
+    // relê o estado completo (descontos + total final)
+    const full = await withStoreClient((c) => c.getCart(ref.cartId, ref.cartToken));
+    return ok({ cart: await cartResponse(full ?? finalCart) });
+  } catch (e) {
+    return failFrom(e);
+  }
+}

package/template/app/api/checkout-destination/route.ts

@@ -0,0 +1,31 @@
+// Decide pro onde o botão "ir para o checkout" navega — SEMPRE no servidor, nunca no client
+// (ver lib/checkout-nav.ts). Dois modos, escolhidos no setup do CLI (create-unbox-store) e nunca
+// misturados no mesmo projeto — não há UI de checkout customizada quando o modo é "hospedado":
+//
+// 1) UNBOX_HOSTED_CHECKOUT_URL vazia (padrão) → checkout customizado interno, /checkout.
+// 2) UNBOX_HOSTED_CHECKOUT_URL preenchida → checkout PADRÃO hospedado pela Unbox, no mesmo
+//    domínio da loja (ex.: https://sualoja.com.br/carrinho/finalizar-pedido). Precisa do
+//    {cartId, cartToken} na URL — mesmo contrato do link de recuperação de carrinho (doc 06) —
+//    porque cartToken é httpOnly e o client não tem acesso a ele para montar a URL sozinho.
+import { getCartRef, getRecurFreq } from "@/lib/session";
+import { ok } from "@/lib/api";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  const ref = await getCartRef();
+  const hostedUrl = process.env.UNBOX_HOSTED_CHECKOUT_URL;
+
+  if (!ref) return ok({ url: "/carrinho" }); // nada pra finalizar ainda
+
+  // NOS DOIS MODOS a URL do checkout carrega ?id=&token=[&freq=]&step=1 — mesmo contrato do
+  // link de recuperação. É isso que deixa o CRM montar o e-mail de abandono a partir da URL
+  // navegada (pixel/GTM capturam a URL) e o link colar em outro aparelho. Sem os params na
+  // URL, a recuperação de carrinho não existe pra quem só enxerga a navegação.
+  const base = hostedUrl || "/checkout";
+  let url = `${base}?id=${encodeURIComponent(ref.cartId)}&token=${encodeURIComponent(ref.cartToken)}`;
+  const freq = await getRecurFreq();
+  if (freq) url += `&freq=${encodeURIComponent(freq)}`;
+  url += "&step=1";
+  return ok({ url });
+}

package/template/app/api/order/[ref]/route.ts

@@ -0,0 +1,17 @@
+// Status do pedido com VERIFICAÇÃO DE POSSE (doc 09): referenceId é curto/adivinhável.
+// Usado pelo polling do Pix (checkout e app/checkout/pix/[ref]).
+import { getOwnedOrder } from "@/lib/orders";
+import { ok, fail, failFrom } from "@/lib/api";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(_req: Request, { params }: { params: Promise<{ ref: string }> }) {
+  try {
+    const { ref } = await params;
+    const order = await getOwnedOrder(ref);
+    if (!order) return fail("Pedido não encontrado ou acesso negado.", 403);
+    return ok({ order });
+  } catch (e) {
+    return failFrom(e);
+  }
+}

package/template/app/api/payment-link/route.ts

@@ -0,0 +1,28 @@
+// Cria um Payment Link hospedado pela Unbox (compartilhar carrinho / WhatsApp).
+// ⚠️ Operação de loja (admin-ish). Protegida por REVALIDATE_SECRET (header x-admin-secret) por padrão.
+import { withStoreClient } from "@/lib/unbox/store";
+import { serverEnv } from "@/lib/config";
+import { ok, fail, failFrom } from "@/lib/api";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(req: Request) {
+  // FAIL-CLOSED: sem REVALIDATE_SECRET configurado a rota fica FECHADA, não aberta. A versão
+  // anterior era `if (secret && ...)`: com o secret vazio (o default do .env) a guarda sumia e
+  // qualquer pessoa criava Payment Links reais com a marca da loja, em massa ou pré-preenchidos
+  // para phishing. Mesmo padrão da /api/revalidate.
+  if (!serverEnv.revalidateSecret || req.headers.get("x-admin-secret") !== serverEnv.revalidateSecret) {
+    return fail("Não autorizado.", 401);
+  }
+  try {
+    const body = await req.json();
+    const items = body.items;
+    if (!Array.isArray(items) || !items.length) return fail("Itens inválidos.");
+    const link = await withStoreClient((c) =>
+      c.createPaymentLink({ items, constraints: body.constraints, customerData: body.customerData }),
+    );
+    return ok({ paymentLink: link });
+  } catch (e) {
+    return failFrom(e);
+  }
+}

package/template/app/api/revalidate/route.ts

@@ -0,0 +1,52 @@
+// Revalidação on-demand (ISR) — chamada por webhook/cron quando catálogo/estoque mudam.
+// Protegida por REVALIDATE_SECRET.
+import { revalidatePath, revalidateTag } from "next/cache";
+import { serverEnv } from "@/lib/config";
+import { ok, fail } from "@/lib/api";
+import { verifyEditorToken } from "@/lib/editable/verify";
+import { conteudoPublicadoAgora } from "@/lib/editable/server";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(req: Request) {
+  const secret = new URL(req.url).searchParams.get("secret") ?? req.headers.get("x-revalidate-secret");
+  const viaSecret = Boolean(serverEnv.revalidateSecret) && secret === serverEnv.revalidateSecret;
+  // O editor publica conteúdo e chama aqui com um JWT (ES256, purpose "revalidate") verificado pela
+  // chave PÚBLICA dele — a loja não guarda segredo do editor.
+  const tokenDoEditor = req.headers.get("x-editor-token");
+  const viaEditor = tokenDoEditor ? await verifyEditorToken(tokenDoEditor, "revalidate") : null;
+  if (!viaSecret && !viaEditor) {
+    return fail("Não autorizado.", 401);
+  }
+  const body = await req.json().catch(() => ({}));
+  const paths: string[] = Array.isArray(body.paths) && body.paths.length ? body.paths : ["/", "/produtos"];
+  // o conteúdo publicado é lido no layout com esta tag; sem purgá-la, o path re-renderiza com o
+  // JSON antigo do Data Cache.
+  if (viaEditor) revalidateTag("unbox-editor-content");
+  // O editor manda as páginas que o conteúdo publicado realmente alcança, e uma delas pode ser uma
+  // ROTA com segmento dinâmico ("/produto/[productSlug]"): trocar o cabeçalho muda todas as páginas
+  // de produto, não uma. Sem o segundo argumento o Next leria os colchetes como caminho literal e não
+  // revalidaria nada — em silêncio.
+  // Caminho que falha NÃO some do recibo: ele fica FORA de `revalidated`, e é assim que o editor
+  // descobre que aquela página continua no ar com o conteúdo antigo (ver lib/recibo.ts do editor).
+  const revalidados: string[] = [];
+  const falhas: string[] = [];
+  for (const p of paths) {
+    try {
+      if (p.includes("[")) revalidatePath(p, "page");
+      else revalidatePath(p);
+      revalidados.push(p);
+    } catch (err) {
+      falhas.push(`${p}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  if (falhas.length) console.warn("[revalidate] caminhos que não revalidaram:", falhas.join(" · "));
+  // O RECIBO. Quem chamou daqui foi o editor, e é com esta resposta que ele decide se pode dizer ao
+  // lojista "a loja já está no ar com a versão N". Purgar o cache não prova isso: prova que a PRÓXIMA
+  // leitura vai buscar de novo. Então a loja vai ler o conteúdo publicado agora e devolve QUAL
+  // documento ela passou a servir (ver `conteudoPublicadoAgora` em lib/editable/server.ts). Sem isto o
+  // editor afirmava "no ar" até para uma loja que nem está ligada a ele.
+  // Só para o editor: o webhook por segredo não precisa do recibo e não paga essa leitura.
+  const conteudo = viaEditor ? await conteudoPublicadoAgora() : null;
+  return ok({ revalidated: revalidados, ...(falhas.length ? { falhas } : {}), via: viaEditor ? "editor" : "secret", conteudo });
+}

package/template/app/api/shipping/quote/route.ts

@@ -0,0 +1,29 @@
+// "Calcule o frete" na PDP (fora do checkout): cota o frete de 1 produto para um CEP.
+import { withStoreClient } from "@/lib/unbox/store";
+import { ok, fail, failFrom } from "@/lib/api";
+
+export const dynamic = "force-dynamic";
+
+// POST /api/shipping/quote { productId, variantId, price, postal }
+export async function POST(req: Request) {
+  try {
+    const { productId, variantId, price, postal } = await req.json();
+    const cep = (postal ?? "").replace(/\D/g, "");
+    if (!productId || !variantId) return fail("Produto inválido.");
+    if (cep.length !== 8) return fail("CEP inválido.", 422);
+
+    const opts = await withStoreClient((c) =>
+      c.quoteShippingForProduct({ productId, productVariantId: variantId, price: price ?? 0.01, quantity: 1 }, cep),
+    );
+    if (!opts.length) return fail("Não há opções de entrega para este CEP.", 422);
+    return ok({
+      options: opts.map((o) => ({
+        displayName: o.fulfillmentMethod.displayName ?? o.fulfillmentMethod.name,
+        price: o.price?.displayAmount,
+        days: o.fulfillmentMethod.daysToDeliver,
+      })),
+    });
+  } catch (e) {
+    return failFrom(e);
+  }
+}

package/template/app/api/subscriptions/[id]/route.ts

@@ -0,0 +1,52 @@
+// Ações de assinatura (recurring order) — só variantes customer* (token do cliente).
+// id = recurringOrderId. action: pause | skip | cancel | items | card | address
+import { requireCustomerClient } from "@/lib/customer-session";
+import { cardSchema, addressSchema } from "@/lib/schemas";
+import { ok, fail, failFrom } from "@/lib/api";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  try {
+    const me = await requireCustomerClient();
+    const { id } = await params;
+    const body = await req.json();
+    const action = body.action as string;
+
+    switch (action) {
+      case "pause":
+        return ok({ subscription: await me.pause(id) });
+      case "skip":
+        return ok({ subscription: await me.skipNextCycle(id) });
+      case "cancel":
+        return ok({ subscription: await me.cancel(id) });
+      case "items": {
+        if (!Array.isArray(body.items)) return fail("Itens inválidos.");
+        return ok({ subscription: await me.updateItems(id, body.items) });
+      }
+      case "card": {
+        const parsed = cardSchema.safeParse(body.card);
+        if (!parsed.success) return fail("Dados do cartão inválidos.", 422);
+        const c = parsed.data;
+        return ok({
+          subscription: await me.updateCard(id, {
+            holderName: c.cardHolder,
+            cardNumber: c.cardNumber,
+            expirationMonth: c.expirationMonth,
+            expirationYear: c.expirationYear,
+            securityCode: c.securityCode,
+          }),
+        });
+      }
+      case "address": {
+        const parsed = addressSchema.safeParse(body.address);
+        if (!parsed.success) return fail("Endereço inválido.", 422);
+        return ok({ subscription: await me.updateAddress(id, parsed.data as any) });
+      }
+      default:
+        return fail("Ação desconhecida.", 400);
+    }
+  } catch (e) {
+    return failFrom(e);
+  }
+}

package/template/app/api/track/route.ts

@@ -0,0 +1,28 @@
+// Acompanhamento de pedido por convidado: exige referenceId + e-mail CORRESPONDENTE.
+// Mitiga a enumeração por referenceId (doc 09): conhecer o código não basta — tem que bater o e-mail.
+import { withStoreClient } from "@/lib/unbox/store";
+import { shapeOrder } from "@/lib/orders";
+import { rateLimit, clientIp } from "@/lib/ratelimit";
+import { emailSchema } from "@/lib/schemas";
+import { ok, fail, failFrom } from "@/lib/api";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(req: Request) {
+  const rl = rateLimit(`track:${clientIp(req)}`, 15, 10 * 60 * 1000);
+  if (!rl.ok) return fail("Muitas tentativas. Aguarde.", 429);
+  try {
+    const { referenceId, email } = await req.json();
+    const e = emailSchema.safeParse(email);
+    if (!referenceId || !e.success) return fail("Informe o código do pedido e o e-mail.", 422);
+
+    const o = await withStoreClient((c) => c.getOrder(String(referenceId).trim()));
+    if (!o || (o.email ?? "").toLowerCase() !== e.data.toLowerCase()) {
+      // resposta uniforme — não revela se o pedido existe
+      return fail("Pedido não encontrado para este código e e-mail.", 404);
+    }
+    return ok({ order: shapeOrder(o) });
+  } catch (e) {
+    return failFrom(e);
+  }
+}