@unbox-plus/cli 0.20.4

package/template/lib/unbox/customer.ts

@@ -0,0 +1,224 @@
+// UnboxCustomerClient — operações da ÁREA DO CLIENTE final.
+// Usa o token do cliente (obtido via UnboxClient.customerSignIn). NÃO precisa da API key
+// da loja — pode rodar num BFF/Route Handler com o token vindo de um cookie httpOnly.
+
+import { UnboxError, comEnderecoDoGrupo } from "./client";
+import type { AddressInput } from "./types";
+
+const RECURRING_FIELDS = `
+  _id referenceId shopId createdAt updatedAt customerAccountId unboxPayCustomerId
+  status{value createdAt} frequency{_id title periodicity interval}
+  pricingPolicy{type value}
+  cyclesInformation{cycleCount skipNextCycle lastCycleDate nextCycleDate}
+  items{productId variantId productERPCode variantERPCode quantity skipNextCycle}
+  unboxPayCustomerCreditCard{first4Digits last4Digits expirationMonth expirationYear holderName}
+  shippingAddressBook{_id fullName postal address1 number neighborhood city region}
+  discount{discountId code} totalAmount{amount displayAmount}`;
+
+export class UnboxCustomerClient {
+  gqlUrl: string;
+  shopId: string;
+  token: string;
+  language: string;
+
+  constructor(opts: { token: string; shopId: string; gqlUrl?: string; language?: string }) {
+    this.token = opts.token;
+    this.shopId = opts.shopId;
+    this.gqlUrl = opts.gqlUrl ?? "https://core.unbox.com.br/graphql";
+    this.language = opts.language ?? "pt-BR";
+  }
+
+  async gql<T = any>(query: string, variables: Record<string, any> = {}): Promise<T> {
+    const res = await fetch(this.gqlUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${this.token}` },
+      body: JSON.stringify({ query, variables }),
+    });
+    const json = await res.json();
+    if (json.errors?.length) throw new UnboxError(json.errors.map((e: any) => e.message).join(" | "), json.errors);
+    return json.data as T;
+  }
+
+  // --------------------------------------------------------------------- conta
+  async me(): Promise<any> {
+    const q = `query($s:String!){ currentCustomerAccount(shopId:$s){
+      _id email isFirstAccess reuseDataBetweenShops metafields{receiveNewOrderEmail}
+      addressBooks{_id alias fullName postal address1 number neighborhood city region isShippingDefault isBillingDefault}
+      lastAddressUsed{_id postal address1 city region} }}`;
+    const d = await this.gql<{ currentCustomerAccount: any }>(q, { s: this.shopId });
+    return d.currentCustomerAccount;
+  }
+
+  /** Atualiza preferências da conta (ex.: receiveNewOrderEmail, reuseDataBetweenShops). */
+  async updateAccount(input: { receiveNewOrderEmail?: boolean; reuseDataBetweenShops?: boolean }): Promise<any> {
+    const q = `mutation($i:UpdateCustomerAccountInput!){ updateCustomerAccount(input:$i){
+      _id reuseDataBetweenShops metafields{receiveNewOrderEmail} }}`;
+    const d = await this.gql<{ updateCustomerAccount: any }>(q, { i: { shopId: this.shopId, ...input } });
+    return d.updateCustomerAccount;
+  }
+
+  // -------------------------------------------------------------------- pedidos
+  // ⚠️ NÃO pedimos displayStatus: o resolver da Unbox lança
+  //    "Cannot read properties of undefined (reading 'status')" e, por ser non-null,
+  //    derruba a query inteira. Use `status` (enum) + orderStatusLabel() para o rótulo.
+  async orders(opts: { first?: number; filters?: any } = {}): Promise<any> {
+    const q = (endereco: string) => `query($shopId:ID!,$first:ConnectionLimitInt,$filters:CustomerOrderFilterInput){
+      customerOrders(shopId:$shopId,first:$first,filters:$filters,sortBy:_id,sortOrder:desc){
+        totalCount shippingMethods pageInfo{hasNextPage endCursor}
+        nodes{_id referenceId status createdAt
+          recurringOrderId dispatched delivered isBoletoPaid invoiceIssued
+          summary{total{amount displayAmount}}
+          fulfillmentGroups{
+            ${endereco}
+            items{nodes{_id title quantity thumbnail price{amount displayAmount}}}
+          }} }}`;
+    // ⚠️ totalItemQuantity removido: dispara "reading 'shop'" no resolver de customerOrders (bug Unbox).
+    const d = await comEnderecoDoGrupo((endereco) => this.gql<{ customerOrders: any }>(q(endereco), { shopId: this.shopId, first: opts.first ?? 20, filters: opts.filters }));
+    return d.customerOrders;
+  }
+
+  async order(referenceId: string): Promise<any> {
+    // Seleção validada ao vivo. Notas do schema (customer context):
+    //   payments.data → PaymentData (objeto) fica FORA. fulfillmentGroups.data é a união
+    //   OrderFulfillmentGroupData: entra pelo comEnderecoDoGrupo, que repete a consulta sem o
+    //   campo se o servidor não resolver o tipo. trackingUrl NÃO existe (use trackingCode).
+    const q = (endereco: string) => `query($referenceId:ID!,$shopId:ID!){
+      customerOrderByReferenceId(referenceId:$referenceId,shopId:$shopId){
+        _id referenceId status email createdAt
+        summary{total{amount displayAmount}}
+        discounts{code label discount discountMethod}
+        payments{displayName mode processor isCaptured cardBrand captureErrorMessage amount{amount displayAmount}}
+        fulfillmentGroups{
+          status type trackingCode
+          ${endereco}
+          items{nodes{_id title variantTitle quantity thumbnail productSlug price{amount displayAmount} subtotal{displayAmount} productConfiguration{productId productVariantId}}}
+        }
+        recurringOrderId generatedNewRecurringOrder }}`;
+    const d = await comEnderecoDoGrupo((endereco) => this.gql<{ customerOrderByReferenceId: any }>(q(endereco), { referenceId, shopId: this.shopId }));
+    return d.customerOrderByReferenceId;
+  }
+
+  // ----------------------------------------------------------------- assinaturas
+  async subscriptions(opts: { first?: number; status?: string[] } = {}): Promise<any> {
+    const q = `query($filters:CustomerRecurringOrdersFilterInput,$first:ConnectionLimitInt){
+      customerRecurringOrders(filters:$filters,first:$first){
+        totalCount nodes{_id referenceId shopId createdAt unboxPayCustomerId} }}`;
+    const d = await this.gql<{ customerRecurringOrders: any }>(q, { first: opts.first ?? 10, filters: { status: opts.status, shopIds: [this.shopId] } });
+    return d.customerRecurringOrders;
+  }
+
+  async subscription(referenceId: string): Promise<any> {
+    const q = `query($referenceId:String!){ customerRecurringOrderByReferenceId(referenceId:$referenceId){${RECURRING_FIELDS}} }`;
+    const d = await this.gql<{ customerRecurringOrderByReferenceId: any }>(q, { referenceId });
+    return d.customerRecurringOrderByReferenceId;
+  }
+
+  async subscriptionCycles(recurringOrderId: string, first = 20): Promise<any> {
+    const q = `query($filters:RecurringOrderCyclesFilterInput!,$first:ConnectionLimitInt){
+      customerRecurringOrderCycles(filters:$filters,first:$first){
+        totalCount nodes{_id cycleIndex completedAt skipped attemptingRetry manuallyRetried createdAt} }}`;
+    const d = await this.gql<{ customerRecurringOrderCycles: any }>(q, { filters: { recurringOrderId }, first });
+    return d.customerRecurringOrderCycles;
+  }
+
+  /** Pausar/retomar assinatura (toggle — valida ao vivo: customerTogglePauseRecurringOrder). */
+  pause(recurringOrderId: string) {
+    return this.gql(`mutation($id:String!){customerTogglePauseRecurringOrder(recurringOrderId:$id){${RECURRING_FIELDS}}}`, { id: recurringOrderId });
+  }
+  /** Adiar / pular o próximo ciclo. */
+  skipNextCycle(recurringOrderId: string) {
+    return this.gql(`mutation($id:String!){customerSkipNextRecurringOrderCycle(recurringOrderId:$id){${RECURRING_FIELDS}}}`, { id: recurringOrderId });
+  }
+  /** Cancelar assinatura. */
+  cancel(recurringOrderId: string) {
+    return this.gql(`mutation($id:String!){customerCancelRecurringOrder(recurringOrderId:$id){${RECURRING_FIELDS}}}`, { id: recurringOrderId });
+  }
+  /** Trocar itens/quantidade. */
+  updateItems(recurringOrderId: string, items: Array<{ productId: string; variantId: string; quantity: number; skipNextCycle?: boolean }>) {
+    const q = `mutation($i:UpdateRecurringOrderItemsInput){customerUpdateRecurringOrderItems(input:$i){${RECURRING_FIELDS}}}`;
+    return this.gql(q, { i: { recurringOrderId, recurringOrderItems: items.map((x) => ({ ...x, skipNextCycle: x.skipNextCycle ?? false })) } });
+  }
+  /** Trocar cartão da assinatura. */
+  updateCard(recurringOrderId: string, card: { holderName: string; cardNumber: string; expirationMonth: string; expirationYear: string; securityCode: string }) {
+    const q = `mutation($i:UpdateRecurringOrderCreditCardInput!){customerUpdateRecurringOrderCreditCard(input:$i){${RECURRING_FIELDS}}}`;
+    return this.gql(q, { i: { recurringOrderId, creditCardData: card } });
+  }
+  /** Trocar endereço de entrega da assinatura. */
+  updateAddress(recurringOrderId: string, shippingAddress: AddressInput) {
+    const q = `mutation($i:UpdateRecurringOrderShippingAddressInput!){customerUpdateRecurringOrderShippingAddress(input:$i){
+      _id postal address1 number neighborhood city region fullName }}`;
+    return this.gql(q, { i: { recurringOrderId, shippingAddress: { country: "BR", ...shippingAddress } } });
+  }
+
+  // ------------------------------------------------------------------ endereços
+  /**
+   * Busca endereços por ID. ⚠️ `customerAddressBooks` exige ao menos 1 id (não aceita lista vazia).
+   * Para a LISTA COMPLETA do cliente, use `me().addressBooks` (vem em currentCustomerAccount).
+   */
+  async addressBooks(ids: string[]): Promise<any[]> {
+    if (!ids?.length) throw new UnboxError("customerAddressBooks exige ao menos 1 id — use me().addressBooks para a lista completa");
+    const q = `query($i:AddressBooksInput!){ customerAddressBooks(input:$i){
+      _id alias fullName postal address1 address2 number neighborhood city region taxPayerId phone
+      isShippingDefault isBillingDefault }}`;
+    const d = await this.gql<{ customerAddressBooks: any[] }>(q, { i: { addressBooksIds: ids, shopId: this.shopId } });
+    return d.customerAddressBooks;
+  }
+
+  /** Cria/atualiza um endereço do cliente (upsert). Sem `_id` cria; com `_id` atualiza. */
+  async upsertAddress(address: AddressInput & { _id?: string; alias?: string; isShippingDefault?: boolean; isBillingDefault?: boolean }): Promise<any> {
+    const q = `mutation($i:UpsertCustomerAddressBookInput!){ upsertCustomerAddressBook(input:$i){
+      _id alias fullName postal address1 number neighborhood city region isShippingDefault isBillingDefault }}`;
+    const d = await this.gql<{ upsertCustomerAddressBook: any }>(q, { i: { shopId: this.shopId, addressBook: { country: "BR", ...address } } });
+    return d.upsertCustomerAddressBook;
+  }
+
+  /** Remove endereços do address book pelos ids. */
+  async deleteAddresses(ids: string[]): Promise<any> {
+    const q = `mutation($i:DeleteCustomerAddressBooksInput!){ deleteCustomerAddressBooks(input:$i){ _id } }`;
+    const d = await this.gql<{ deleteCustomerAddressBooks: any }>(q, { i: { shopId: this.shopId, addressBooksIds: ids } });
+    return d.deleteCustomerAddressBooks;
+  }
+}
+
+/**
+ * Rótulos PT-BR para Order.status (workaround do displayStatus quebrado na Unbox).
+ * Valores conforme OrderStatusEnum do schema: PENDING, PROCESSING, COMPLETED, CANCELED, FAILED, REFUNDED.
+ */
+export const ORDER_STATUS_LABELS: Record<string, string> = {
+  PENDING: "Aguardando pagamento",
+  PROCESSING: "Em processamento",
+  COMPLETED: "Concluído",
+  CANCELED: "Cancelado",
+  FAILED: "Falhou",
+  REFUNDED: "Reembolsado",
+};
+export function orderStatusLabel(status: string): string {
+  return ORDER_STATUS_LABELS[status] ?? status;
+}
+
+/** Rótulos PT-BR para PaymentStatusEnum. */
+export const PAYMENT_STATUS_LABELS: Record<string, string> = {
+  CREATED: "Criado",
+  PENDING: "Aguardando pagamento",
+  AUTHORIZED: "Autorizado",
+  CAPTURED: "Capturado",
+  PAID: "Pago",
+  CANCELED: "Cancelado",
+  REFUNDED: "Reembolsado",
+  EXPIRED: "Expirado",
+  CHARGED_BACK: "Estornado (chargeback)",
+};
+export function paymentStatusLabel(status: string): string {
+  return PAYMENT_STATUS_LABELS[status] ?? status;
+}
+
+/** Rótulos PT-BR para RecurringOrderStatusEnum (assinatura). */
+export const SUBSCRIPTION_STATUS_LABELS: Record<string, string> = {
+  ACTIVE: "Ativa",
+  PAUSED: "Pausada",
+  CANCELED: "Cancelada",
+  ERROR: "Com erro",
+};
+export function subscriptionStatusLabel(status: string): string {
+  return SUBSCRIPTION_STATUS_LABELS[status] ?? status;
+}

package/template/lib/unbox/errors.ts

@@ -0,0 +1,97 @@
+// errors.ts — tradução de erros/eventos da Unbox em FEEDBACK ao cliente final (PT-BR).
+//
+// A Unbox sinaliza problemas de 3 formas (ver docs 08-feedback-ao-cliente):
+//   1) erro LANÇADO no GraphQL (json.errors[].message = um CÓDIGO, ex. DISCOUNT_CODE_NOT_FOUND_ERROR)
+//   2) campos de FALHA no payload (min/maxOrderQuantityFailures). Obs.: incorrectPriceFailures
+//      NÃO é confiável — o servidor sobrescreve o preço e o campo vem vazio (validado ao vivo).
+//   3) cartEvents[] (eventos informativos: brinde adicionado, cupom removido, etc.)
+//
+// Use friendlyError() no catch das chamadas e cartEventLabel() ao renderizar o carrinho.
+
+import { UnboxError } from "./client";
+
+/** Código de erro (json.errors[].message) → mensagem amigável ao cliente. */
+export const ERROR_MESSAGES: Record<string, string> = {
+  // ---- carrinho / itens ----
+  MISSING_ITEMS_ERROR: "Um ou mais produtos não estão mais disponíveis.",
+  ITEM_ERROR: "Há um problema com um item do seu carrinho.",
+  CREATE_CART_ERROR: "Não foi possível criar o carrinho. Tente novamente.",
+  OUT_OF_STOCK: "Produto esgotado.",
+  // ---- cupom / desconto ----
+  DISCOUNT_CODE_NOT_FOUND_ERROR: "Cupom inválido ou expirado.",
+  DISCOUNT_AVAILABLE_FOR_NON_RECURRING_PRODUCTS_ONLY_ERROR:
+    "Este cupom não vale para itens de assinatura. Troque a assinatura por compra única para usá-lo.",
+  DISCOUNT_AVAILABLE_FOR_RECURRING_PRODUCTS_ONLY_ERROR:
+    "Este cupom só vale para itens de assinatura.",
+  DISCOUNT_NOT_APPLICABLE_ERROR: "Este cupom não se aplica aos itens do seu carrinho.",
+  DISCOUNT_EXPIRED_ERROR: "Cupom expirado.",
+  DISCOUNT_USAGE_LIMIT_REACHED_ERROR: "Este cupom atingiu o limite de uso.",
+  DISCOUNT_MINIMUM_ORDER_NOT_MET_ERROR: "Seu pedido ainda não atingiu o valor mínimo para este cupom.",
+  DISCOUNT_ALREADY_APPLIED_ERROR: "Este cupom já está aplicado ao carrinho.",
+  // ---- endereço / frete ----
+  ADDRESS_BOOK_ERROR: "Endereço inválido. Confira os dados.",
+  NO_FULFILLMENT_OPTIONS: "Não há opções de entrega para este CEP.",
+  // ---- pagamento (recusas do processador / UnboxPay-Zoop) ----
+  INSUFFICIENT_FUNDS_ERROR: "Pagamento recusado: saldo/limite insuficiente.",
+  PAYMENT_ERROR: "Não foi possível processar o pagamento. Tente outro método.",
+  PLACE_ORDER_ERROR: "Não foi possível concluir o pedido. Tente novamente.",
+  CARD_DECLINED_ERROR: "Cartão recusado. Verifique os dados ou use outro cartão.",
+  FULFILLMENT_GROUP_AND_CART_ITEMS_DO_NOT_MATCH_ERROR: "Há um item promocional inválido no pedido. Atualize o carrinho e tente novamente.",
+  // ---- conta do cliente ----
+  CUSTOMER_ACCOUNT_ERROR: "Não foi possível acessar sua conta.",
+  INVALID_CREDENTIALS_ERROR: "Código ou credenciais inválidos.",
+  UNBOX_PAY_CUSTOMER_ERROR: "Falha no cadastro de pagamento. Tente novamente.",
+  // ---- infra / genéricos ----
+  FORBIDDEN_ERROR: "Ação não autorizada. Recarregue a página e tente novamente.", // ex.: falta x-captcha-verification
+  VALIDATION_ERROR: "Alguns dados são inválidos. Revise o formulário.",
+  UNEXPECTED_ERROR: "Algo deu errado. Tente novamente em instantes.",
+  INTERNAL_SERVER_ERROR: "Algo deu errado. Tente novamente em instantes.",
+};
+
+/** O login sem senha (OTP) NÃO responde no formato dos outros erros: em vez de um CÓDIGO_ERRO,
+ *  devolve um corpo OAuth (`{"error":"invalid_grant","error_description":"Wrong email or
+ *  verification code."}`). Sem este dicionário caía no fallback, e quem digitou um código
+ *  expirado lia "Algo deu errado", redigitava o MESMO código e desistia (caso real). */
+const ERROS_OAUTH: [RegExp, string][] = [
+  [/expired_token|code has expired|c[oó]digo expirad/i, "Este código expirou. Peça um novo."],
+  [/invalid_grant|wrong email or verification code/i, "Código incorreto ou expirado. Peça um novo código."],
+  [/too many|rate.?limit/i, "Muitas tentativas. Aguarde um instante e tente de novo."],
+  [/invalid_client|unauthorized_client/i, "Não foi possível validar o acesso. Recarregue a página e tente de novo."],
+];
+
+const FALLBACK = "Algo deu errado. Tente novamente.";
+
+/**
+ * Converte um erro do SDK/Unbox em mensagem amigável ao cliente.
+ * Casa por código exato e por substring (a mensagem do servidor costuma SER o código).
+ */
+export function friendlyError(err: unknown): string {
+  let raw: string;
+  if (err instanceof UnboxError) raw = err.errors?.[0]?.message ?? err.message;
+  else if (err instanceof Error) raw = err.message;
+  else if (err && typeof err === "object") {
+    const o = err as any;
+    raw = o.errors?.[0]?.message ?? o.message ?? String(err);
+  } else raw = String(err);
+  // O corpo OAuth do login por código não casa com nenhum CÓDIGO_ERRO: testar antes do dicionário.
+  for (const [rx, msg] of ERROS_OAUTH) if (rx.test(raw)) return msg;
+  if (ERROR_MESSAGES[raw]) return ERROR_MESSAGES[raw];
+  for (const code of Object.keys(ERROR_MESSAGES)) {
+    if (raw.includes(code)) return ERROR_MESSAGES[code];
+  }
+  // validação de variável GraphQL (ex.: campo obrigatório ausente)
+  if (/required type|got invalid value|Expected/.test(raw)) return ERROR_MESSAGES.VALIDATION_ERROR;
+  return FALLBACK;
+}
+
+/** CartEventEnum (cart.cartEvents[].type) → mensagem informativa ao cliente. */
+export const CART_EVENT_LABELS: Record<string, string> = {
+  SALE_FREE_ITEM_ADDED: "🎁 Você ganhou um brinde!",
+  SALE_FREE_ITEM_CHANGED: "Seu brinde foi atualizado.",
+  SALE_FREE_ITEM_REMOVED: "O brinde foi removido (condição da promoção não atendida).",
+  DISCOUNT_CODE_REMOVED: "O cupom foi removido do carrinho.",
+  DISCOUNT_CODE_RECOVERED: "Seu cupom foi reaplicado.",
+};
+export function cartEventLabel(type: string): string {
+  return CART_EVENT_LABELS[type] ?? type;
+}

package/template/lib/unbox/index.ts

@@ -0,0 +1,10 @@
+export { UnboxClient, UnboxError } from "./client";
+export {
+  UnboxCustomerClient,
+  orderStatusLabel, paymentStatusLabel, subscriptionStatusLabel,
+  ORDER_STATUS_LABELS, PAYMENT_STATUS_LABELS, SUBSCRIPTION_STATUS_LABELS,
+} from "./customer";
+export { friendlyError, cartEventLabel, ERROR_MESSAGES, CART_EVENT_LABELS } from "./errors";
+export { verifyUnboxWebhook, parseUnboxWebhook } from "./webhooks";
+export type { UnboxWebhookEnvelope, UnboxWebhookEventType, UnboxOrderWebhookData } from "./webhooks";
+export type * from "./types";

package/template/lib/unbox/store.ts

@@ -0,0 +1,113 @@
+// Factory do UnboxClient de LOJA (server-only) com cache de token em memória.
+//
+// Regra de ouro (doc 11): NÃO fazer signIn() a cada request. O JWT vale ~24h; cacheamos num
+// singleton de módulo e renovamos com folga (~23h). Em produção serverless, troque este cache
+// por Vercel KV / Edge Config compartilhado entre lambdas (ver pontos `// PROD:`).
+import "server-only";
+import { UnboxClient, UnboxError } from "./client";
+import { serverEnv, hasUnboxCredentials, decodeJwtClaims, SHOP_ID_CLAIM, SHOP_SLUG_CLAIM } from "../config";
+
+interface CachedToken {
+  token: string;
+  expMs: number; // epoch ms em que devemos renovar (exp - folga)
+  shopId: string;
+  shopSlug: string;
+}
+
+// PROD: substituir por KV. Em dev/single-instance, o módulo singleton basta.
+let cache: CachedToken | null = null;
+let inFlight: Promise<CachedToken> | null = null;
+
+const RENEW_BUFFER_MS = 60 * 60 * 1000; // renova 1h antes de expirar
+
+async function doSignIn(): Promise<CachedToken> {
+  if (!hasUnboxCredentials) {
+    throw new Error(
+      "[unbox] credenciais ausentes (UNBOX_API_KEY/UNBOX_USER/UNBOX_PASS) — preencha .env.local. Rodando em modo mockup."
+    );
+  }
+  const client = new UnboxClient({
+    apiKey: serverEnv.apiKey,
+    shopId: serverEnv.shopId,
+    apiBaseUrl: serverEnv.authUrl,
+    gqlUrl: serverEnv.gqlUrl,
+    partnerApiKey: serverEnv.partnerApiKey,
+    partnerGqlUrl: serverEnv.partnerGqlUrl,
+    captchaBypass: serverEnv.captchaBypass,
+  });
+  const token = await client.signIn(serverEnv.user, serverEnv.pass);
+  const claims = decodeJwtClaims(token);
+  const expSec = typeof claims.exp === "number" ? claims.exp : Math.floor(Date.now() / 1000) + 23 * 3600;
+  return {
+    token,
+    expMs: expSec * 1000 - RENEW_BUFFER_MS,
+    shopId: serverEnv.shopId || claims[SHOP_ID_CLAIM] || "",
+    shopSlug: serverEnv.shopSlug || claims[SHOP_SLUG_CLAIM] || "",
+  };
+}
+
+async function getCachedToken(force = false): Promise<CachedToken> {
+  if (!force && cache && Date.now() < cache.expMs) return cache;
+  if (inFlight) return inFlight;
+  inFlight = doSignIn()
+    .then((c) => {
+      cache = c;
+      return c;
+    })
+    .finally(() => {
+      inFlight = null;
+    });
+  return inFlight;
+}
+
+/** shopId/shopSlug resolvidos (env tem prioridade; senão extrai do JWT). */
+export async function getShopContext(): Promise<{ shopId: string; shopSlug: string }> {
+  const c = await getCachedToken();
+  return { shopId: c.shopId, shopSlug: c.shopSlug };
+}
+
+/**
+ * Retorna um UnboxClient de loja já autenticado (token do cache). Re-signin automático
+ * em 401/ACCESS_DENIED (token expirado) é tratado por `withStoreClient`.
+ */
+export async function getStoreClient(): Promise<UnboxClient> {
+  const c = await getCachedToken();
+  const client = new UnboxClient({
+    apiKey: serverEnv.apiKey,
+    shopId: c.shopId,
+    apiBaseUrl: serverEnv.authUrl,
+    gqlUrl: serverEnv.gqlUrl,
+    partnerApiKey: serverEnv.partnerApiKey,
+    partnerGqlUrl: serverEnv.partnerGqlUrl,
+    captchaBypass: serverEnv.captchaBypass,
+  });
+  client.setToken(c.token);
+  return client;
+}
+
+/**
+ * Executa uma operação com o client de loja; se falhar por token expirado
+ * (401/ACCESS_DENIED/FORBIDDEN de auth), força re-signin UMA vez e repete.
+ */
+export async function withStoreClient<T>(fn: (c: UnboxClient) => Promise<T>): Promise<T> {
+  const client = await getStoreClient();
+  try {
+    return await fn(client);
+  } catch (e) {
+    if (isAuthExpired(e)) {
+      const c = await getCachedToken(true);
+      client.setToken(c.token);
+      return fn(client);
+    }
+    throw e;
+  }
+}
+
+function isAuthExpired(e: unknown): boolean {
+  if (e instanceof UnboxError) {
+    const msg = (e.errors?.[0]?.message ?? e.message ?? "").toUpperCase();
+    return /ACCESS_DENIED|UNAUTHENTICATED|TOKEN|EXPIRED|401/.test(msg);
+  }
+  if (e instanceof Error) return /401|ACCESS_DENIED/i.test(e.message);
+  return false;
+}

package/template/lib/unbox/types.ts

@@ -0,0 +1,195 @@
+// Tipos da API Unbox (headless commerce). Apenas tipos — apagados em runtime.
+
+export interface Money {
+  amount: number;
+  displayAmount?: string;
+  currency?: { code: string };
+}
+
+export interface UnboxConfig {
+  /** API key da loja (modelo antigo). Usada no x-api-key (signin REST) e no
+   *  x-captcha-verification (placeOrder, customerOTPRequest, customerPasswordlessSignIn).
+   *  Server-only. Pode ficar vazia quando `partnerApiKey` está configurada. */
+  apiKey: string;
+  /** shopId da loja (ex.: "8EaeSDX99hifhyTQp"). */
+  shopId: string;
+  /** Base REST de auth. Default: https://api.unbox.com.br */
+  apiBaseUrl?: string;
+  /** Endpoint GraphQL do core. Default: https://core.unbox.com.br/graphql */
+  gqlUrl?: string;
+  /** API de PARCEIROS (nova, pública): api key ÚNICA do parceiro, vale para todas as lojas
+   *  dele. Presente → signIn vira mutation GQL na API de parceiros e as leituras com
+   *  paridade (tags, cupons, pedido, parcelas, inventário, webhook, cart template) são
+   *  roteadas para lá. A loja específica é autenticada pelo user/senha no signIn. */
+  partnerApiKey?: string;
+  /** Endpoint GraphQL da API de parceiros. Default: https://partners.unbox.com.br/graphql */
+  partnerGqlUrl?: string;
+  /** x-captcha-verification do signIn na API de parceiros — OBRIGATÓRIO segundo a doc
+   *  oficial (docs.unbox.com.br); fornecido pela Unbox. Sem ele o header é omitido e o
+   *  signIn de parceiros tende a falhar. */
+  captchaBypass?: string;
+  /** Idioma de respostas/rótulos. Default: "pt-BR".
+   *  ⚠️ displayStatus(language) tem resolver quebrado no live — use status cru + orderStatusLabel(). */
+  language?: string;
+  /** Timeout por request (ms). Default: 15000. Aplica a signin e a toda chamada GraphQL. */
+  timeoutMs?: number;
+}
+
+export interface ProductVariant {
+  _id: string;
+  title: string;
+  sku?: string | null;
+  pricing?: Array<{ price: number | null; displayPrice: string; compareAtPrice?: { displayAmount: string } | null }>;
+}
+
+export interface CatalogProduct {
+  _id: string;
+  productId: string;
+  title: string;
+  slug: string;
+  productType: string;
+  isVisible: boolean;
+  isSoldOut: boolean;
+  isBackorder?: boolean;
+  isLowQuantity?: boolean;
+  recurrenceAllowed?: boolean;
+  imageUrls?: string[];
+  videoUrls?: string[];
+  description?: string;
+  additionalInformation?: string;
+  pageTitle?: string;
+  metaDescription?: string;
+  tagIds?: string[];
+  minOrderQuantity?: number | null;
+  maxOrderQuantity?: number | null;
+  pricing?: Array<{ displayPrice: string; price: number | null; minPrice: number; maxPrice: number }>;
+  variants?: ProductVariant[];
+}
+
+export interface Connection<T> {
+  totalCount: number;
+  nodes: T[];
+  pageInfo?: { hasNextPage: boolean; endCursor?: string };
+}
+
+export interface AddressInput {
+  fullName: string;
+  taxPayerId: string;
+  postal: string;
+  address1: string;
+  number: string;
+  neighborhood: string;
+  city: string;
+  region: string;
+  phone: string;        // OBRIGATÓRIO (String!) — validado ao vivo
+  country?: string;     // default "BR" aplicado pelo SDK
+  address2?: string;
+  cityCode?: string;
+  isCommercial?: boolean;
+  trackByMobile?: boolean;
+}
+
+export interface CartItemInput {
+  productId: string;
+  /** ⚠️ É `productVariantId`, NÃO `variantId`. Errar o nome (em payload montado à mão, fora
+   *  deste tipo) devolve um erro de GraphQL que só cita `productConfiguration`, sem dizer
+   *  qual campo faltou — armadilha clássica ao escrever testes contra a API. */
+  productVariantId: string;
+  /** Preço da variante. ⚠️ O servidor SOBRESCREVE com o preço do catálogo (validado ao vivo:
+   *  enviar 0.01 grava o preço real e `incorrectPriceFailures` vem vazio). Envie o preço real
+   *  por correção/UX, mas a fonte da verdade é o catálogo. */
+  price: number;
+  quantity: number;
+  isRecurring?: boolean;
+  thumbnail?: string;
+  currencyCode?: string;
+}
+
+export interface FulfillmentOption {
+  fulfillmentMethod: { _id: string; name: string; displayName?: string; daysToDeliver?: number };
+  price: Money;
+  discountPrice?: { displayAmount?: string };
+}
+
+export interface CartResult {
+  cartId: string;
+  cartToken: string;
+  cart: any;
+  incorrectPriceFailures?: any[];
+  minOrderQuantityFailures?: Array<{ minOrderQuantity: number; quantity: number }>;
+  maxOrderQuantityFailures?: Array<{ maxOrderQuantity: number; quantity: number }>;
+}
+
+export type PaymentType = "pix" | "credit" | "boleto";
+
+/** Fingerprint antifraude/3DS exigido pela Unbox no placeOrder. Vai no NÍVEL RAIZ do
+ *  PlaceOrderInput (irmão de `order` e `payments`), como campo único com enum `type`:
+ *  - BROWSER: dados reais do navegador do comprador (coletados no checkout-client).
+ *  - API: fallback para pedidos originados no servidor (scripts), sem navegador. */
+export type DeviceInput =
+  | {
+      type: "BROWSER";
+      colorDepth: number;
+      javaEnabled: boolean;
+      userAgent: string;
+      language: string;
+      screenHeight: number;
+      screenWidth: number;
+      /** ⚠️ Ponto aberto com a Unbox: enviamos MINUTOS (getTimezoneOffset(), BRT → 180),
+       *  igual ao storefront de referência. A doc mostrava 3 (horas). Se a Unbox confirmar
+       *  horas, dividir por 60 na coleta (checkout-client.tsx). Não quebra o pedido —
+       *  afeta só o sinal de antifraude. */
+      timezoneOffset: number;
+    }
+  | { type: "API" };
+
+export interface CardData {
+  cardHolder: string;
+  cardNumber: string;
+  expirationMonth: string;
+  expirationYear: string;
+  securityCode: string;
+  installments?: number;
+}
+
+export interface PlaceOrderParams {
+  cartId: string;
+  email: string;
+  address: AddressInput;
+  fulfillmentMethodId: string;
+  /** total final (cart.checkout.summary.total.amount após selecionar o frete). */
+  total: number;
+  /** itens finais do carrinho — TODOS (inclusive brindes), com os flags `isRecurring` e
+   *  `isDiscountedBonusItem` (use buildOrderItems). Omitir os flags/brindes → 502 (ver buildOrderItems). */
+  items: Array<{ productConfiguration: { productId: string; productVariantId: string }; price: number; quantity: number; addedAt?: string; thumbnail?: string; isRecurring?: boolean; isDiscountedBonusItem?: boolean }>;
+  payment:
+    | { type: "pix" }
+    | { type: "card"; card: CardData };
+  /** assinatura: cria recurring order. */
+  recurrence?: { recurringItemsFrequencyId: string };
+  /** fingerprint antifraude — omitido, o client envia { type: "API" } como fallback. */
+  device?: DeviceInput;
+}
+
+/** Inventário de uma variante (API de parceiros — simpleInventory). */
+export interface SimpleInventoryInfo {
+  _id: string;
+  canBackorder: boolean;
+  inventoryInStock: number;
+  inventoryReserved: number;
+  isEnabled: boolean;
+  lowInventoryWarningThreshold?: number | null;
+  productConfiguration: { productId: string; productVariantId: string };
+}
+
+export interface SubscriptionFrequency {
+  _id: string;
+  title: string;
+  periodicity: "DAY" | "WEEK" | "MONTH" | string;
+  interval: number;
+}
+
+export interface PaymentLinkConstraints {
+  expirationDate?: string;
+  usageLimit?: number;
+}