@greatapps/common 1.1.751 → 1.1.752

package/src/components/modals/promo/AiCreditsOfferModal/components/LoseOfferDialog.tsx

@@ -0,0 +1,97 @@
+'use client';
+
+import { useTranslations } from 'next-intl';
+import { Button } from '../../../../ui/buttons/Button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from '../../../../ui/overlay/Dialog';
+import { Separator } from '../../../../ui/data-display/Separator';
+import { IconAlertTriangle } from '@tabler/icons-react';
+
+interface LoseOfferDialogProps {
+  open: boolean;
+  /** Selo do desconto ("50% OFF") — repetido aqui porque é ele que dói. */
+  discountLabel: string;
+  /** Pacote ofertado, já formatado ("1.000"). */
+  creditsLabel: string;
+  /** Preço cheio formatado: o número que volta a valer. Vazio enquanto a âncora carrega. */
+  fullPriceLabel: string;
+  /** Volta pra oferta (fecha só esta confirmação). */
+  onKeep: () => void;
+  /** Abre mão da oferta e fecha tudo. */
+  onLose: () => void;
+}
+
+/**
+ * Confirmação de saída ("quer mesmo perder essa oferta?").
+ *
+ * É um Dialog SEPARADO, empilhado por cima da oferta com os mesmos z-index do
+ * `InsufficientIaCreditsModal` (overlay 1002 / conteúdo 1003) — assim a oferta continua **visível
+ * atrás do véu**: a pessoa decide olhando exatamente para o que está prestes a perder, que é o
+ * ponto inteiro desta tela.
+ *
+ * O principal é VOLTAR para a oferta; perder fica como secundário, a um clique de distância. A
+ * saída não está escondida — o peso da decisão está na frase, não no botão.
+ */
+export function LoseOfferDialog({
+  open,
+  discountLabel,
+  creditsLabel,
+  fullPriceLabel,
+  onKeep,
+  onLose,
+}: LoseOfferDialogProps) {
+  const translate = useTranslations();
+
+  return (
+    <Dialog open={open} onOpenChange={(next) => !next && onKeep()}>
+      <DialogContent
+        showCloseButton={false}
+        onOpenAutoFocus={(event) => event.preventDefault()}
+        overlayClassName="z-[1002] bg-black/40"
+        className="z-[1003] flex flex-col gap-0 p-0 max-[440px]:w-[calc(100%-32px)] md:w-[420px]! lg:w-[420px]! max-w-[420px]! data-[state=open]:animate-[gp-offer-confirm-in_260ms_cubic-bezier(0.16,1,0.3,1)]"
+      >
+        <DialogHeader className="gap-3 p-5 text-left">
+          <div className="flex w-fit items-center justify-center rounded-lg bg-red-50 p-2.5">
+            <IconAlertTriangle size={20} className="text-red-500" />
+          </div>
+          <div className="flex flex-col gap-2">
+            <DialogTitle className="paragraph-medium-semibold text-zinc-950">
+              {translate('common.promo.aiCreditsOffer.exit.title', { discount: discountLabel })}
+            </DialogTitle>
+            <DialogDescription className="paragraph-small-regular text-zinc-600">
+              {/* Sem preço resolvido (elegibilidade ainda carregando) a frase cai na versão sem
+                  número — prometer "volta a custar" sem dizer quanto é pior do que não dizer. */}
+              {fullPriceLabel
+                ? translate('common.promo.aiCreditsOffer.exit.description', {
+                    credits: creditsLabel,
+                    price: fullPriceLabel,
+                  })
+                : translate('common.promo.aiCreditsOffer.exit.descriptionNoPrice', {
+                    credits: creditsLabel,
+                  })}
+            </DialogDescription>
+          </div>
+        </DialogHeader>
+
+        <Separator />
+
+        {/* Rodapé com os dois botões juntos à esquerda (`gap-2`, sem `justify-between`), o
+            principal primeiro. Ficar é o caminho principal; perder a oferta continua a um clique,
+            mas como ação secundária. */}
+        <div className="flex items-center gap-2 p-5">
+          <Button className="h-10! transition-colors" onClick={onKeep}>
+            {translate('common.promo.aiCreditsOffer.exit.keep')}
+          </Button>
+          <Button variant="secondary" className="h-10! transition-colors" onClick={onLose}>
+            {translate('common.promo.aiCreditsOffer.exit.lose')}
+          </Button>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/src/components/modals/promo/AiCreditsOfferModal/components/OfferIllustration.tsx

@@ -0,0 +1,121 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import Image from 'next/image';
+import { useTranslations } from 'next-intl';
+
+/**
+ * Painel direito da oferta — implementação do design do Figma (`Testes-UI`, nodes `2569:2938` e
+ * `2569:4015`), conferida contra o SVG exportado do bloco inteiro.
+ *
+ * A geometria vem do arquivo, desenhado num painel de **449×606** — praticamente o tamanho real
+ * desta coluna (metade de um modal de 900). Por isso os offsets são os px do próprio design,
+ * ancorados ao CENTRO do painel: a janela tem altura derivada da largura, então âncora percentual
+ * desmontaria a composição quando o modal mudasse de altura; a partir do centro, a distância entre
+ * as peças se mantém.
+ *
+ * O fundo e a janela são os VETORES do arquivo (`offer-panel-background.svg` e
+ * `offer-editor-window.svg`, em `public/promo/` do app consumidor — a lib não publica assets
+ * estáticos), fatiados do SVG do bloco; o cartão é DOM, pra o contador animar.
+ *
+ * Animações em CSS puro (classes `gp-offer-*`, ver o bloco no topo do `AiCreditsOfferModal.tsx`) —
+ * respeitam `prefers-reduced-motion` por conta própria, sem depender de JS. Só o CONTADOR do
+ * cartão é JS (`requestAnimationFrame`): não dá pra fazer "500" nascer de "0" em CSS puro.
+ */
+
+const COUNT_DELAY_MS = 620;
+const COUNT_DURATION_MS = 1150;
+
+function easeOutCubic(t: number): number {
+  return 1 - (1 - t) ** 3;
+}
+
+interface OfferIllustrationProps {
+  /** Pacote ofertado — é ele que o contador persegue. */
+  credits: number;
+  /** Locale de formatação do número (vem do locale da UI). */
+  locale: string;
+}
+
+export function OfferIllustration({ credits, locale }: OfferIllustrationProps) {
+  const translate = useTranslations();
+  const [displayCredits, setDisplayCredits] = useState(0);
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+      setDisplayCredits(credits);
+      return;
+    }
+
+    let frameId: number;
+    const startedAt = performance.now() + COUNT_DELAY_MS;
+
+    const tick = (now: number) => {
+      const elapsed = now - startedAt;
+      if (elapsed < 0) {
+        frameId = requestAnimationFrame(tick);
+        return;
+      }
+      const progress = Math.min(1, elapsed / COUNT_DURATION_MS);
+      setDisplayCredits(Math.round(credits * easeOutCubic(progress)));
+      if (progress < 1) frameId = requestAnimationFrame(tick);
+    };
+
+    frameId = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(frameId);
+  }, [credits]);
+
+  return (
+    <div className="relative h-full w-full overflow-hidden">
+      {/* Fundo: o próprio vetor do arquivo (gradiente + o brilho difuso da quina), extraído do SVG
+          do bloco. Vem como imagem, e não como gradiente CSS + `blur`, pra não haver interpretação
+          no meio: a cor e o desfoque são os do design, byte a byte. 4,7KB. */}
+      <Image
+        src="/promo/offer-panel-background.svg"
+        alt=""
+        fill
+        priority
+        draggable={false}
+        className="object-cover select-none"
+      />
+
+      {/* Janela do editor — o vetor exportado do próprio arquivo (chrome, moldura branca, sombra e
+          o print do canvas embutido). `gp-offer-window-in` anima `translate`/`scale` (propriedades
+          CSS independentes do `transform`), então convive sem conflito com o
+          `-translate-x-1/2 -translate-y-1/2` do Tailwind que centraliza o elemento. */}
+      <div
+        aria-hidden
+        className="gp-offer-window-in absolute top-[calc(50%-27px)] left-[calc(50%+98px)] aspect-[557.57/388.22] w-[132%] -translate-x-1/2 -translate-y-1/2 md:w-[124.2%]"
+      >
+        <Image
+          src="/promo/offer-editor-window.svg"
+          alt=""
+          fill
+          sizes="560px"
+          priority
+          draggable={false}
+          className="select-none"
+        />
+      </div>
+
+      {/* Cartão de créditos (node 2569:4015), solto abaixo da janela, com a folga de gradiente que
+          o arquivo tem. Só no desktop: no mobile a faixa é baixa e ele brigaria com a janela. */}
+      <div className="gp-offer-card-in absolute top-[calc(50%+146px)] left-[49.7%] hidden h-[66px] w-[193.5px] items-center gap-[11.5px] rounded-[15px] border border-[#8BE4FF]/38 bg-white pl-[11.5px] shadow-[0px_4px_25px_0px_rgba(26,26,26,0.03)] md:flex">
+        <span className="gp-offer-icon-pulse flex size-[43.5px] shrink-0 items-center justify-center rounded-[9px] bg-cyan-50">
+          {/* eslint-disable-next-line @next/next/no-img-element -- ícone de 39KB, pesado demais pra inlinear no componente da lib. */}
+          <img src="/iaicon.svg" alt="" width={24} height={24} className="block" />
+        </span>
+        <span className="flex items-baseline gap-1 whitespace-nowrap">
+          <span className="title-large-semibold text-[25px] leading-[29px] tabular-nums text-zinc-950">
+            {displayCredits.toLocaleString(locale)}
+          </span>
+          <span className="paragraph-small-medium text-[14.5px] text-zinc-500">
+            {translate('common.promo.aiCreditsOffer.illustration.credits')}
+          </span>
+        </span>
+      </div>
+    </div>
+  );
+}

package/src/components/modals/promo/AiCreditsOfferModal/components/OfferPaymentField.tsx

@@ -0,0 +1,91 @@
+'use client';
+
+import { useTranslations } from 'next-intl';
+import { CardBrandIcon } from '../../../../ui/data-display/CardBrandIcons';
+import { Tooltip, TooltipContent, TooltipTrigger } from '../../../../ui/overlay/Tooltip';
+import { useCards } from '../../../../../modules/cards/hooks/cards.hook';
+import { useModalManager } from '../../../../../store/useModalManager';
+import { IconPencil, IconPlus } from '@tabler/icons-react';
+
+interface OfferPaymentFieldProps {
+  /** Cartão em uso (padrão da conta ou o que acabou de ser cadastrado). */
+  cardId: string;
+  /** Recebe o id do cartão cadastrado no `addCardModal`. */
+  onCardAdded: (cardId: string) => void;
+}
+
+/**
+ * Campo de pagamento da oferta — versão de **um cartão só**.
+ *
+ * Nasceu do `PaymentInfoCard` (mesma moldura, mesma linha "Pagamento", mesmo `CardBrandIcon`,
+ * mesmas chaves de tradução `common.cards.*`), mas sem o seletor e sem o "Nova forma de
+ * pagamento": aqui a pessoa está numa compra única de primeira vez, então ou ela ainda não tem
+ * cartão (e o campo é só o botão de cadastrar) ou já tem (e o campo é só o cartão). Oferecer uma
+ * lista de cartões numa tela cujo objetivo é UM clique era ruído.
+ *
+ * Com cartão, o lápis fica sempre visível e abre o `addCardModal` — o mesmo fluxo padrão da
+ * plataforma, que é por onde se troca a forma de pagamento (não existe edição de cartão: o
+ * gateway guarda o dado, então "editar" é cadastrar outro). Nada de formulário próprio.
+ */
+export function OfferPaymentField({ cardId, onCardAdded }: OfferPaymentFieldProps) {
+  const translate = useTranslations();
+  const { openModal } = useModalManager();
+  const { data: cardsData } = useCards();
+
+  const card = cardsData?.data?.find((item) => item.id.toString() === cardId.toString());
+
+  const handleOpenCardModal = () => {
+    openModal('addCardModal', { onCardAdded });
+  };
+
+  return (
+    <div className="overflow-hidden rounded-lg border border-zinc-200">
+      <div className="flex h-[60px] items-center gap-3 px-4">
+        <span className="paragraph-small-medium w-[100px] text-zinc-500">
+          {translate('common.cards.paymentInfo.payment')}
+        </span>
+
+        {card ? (
+          <>
+            <div className="flex min-w-0 flex-1 flex-col gap-0.5">
+              <span className="paragraph-small-semibold truncate text-zinc-950">{card.name}</span>
+              <span className="paragraph-small-medium text-zinc-950">
+                •••• {card.number?.replaceAll(/\D/g, '')?.slice(-4)}
+              </span>
+            </div>
+
+            <div className="flex shrink-0 items-center gap-2">
+              <CardBrandIcon brand={card.brand} />
+              {/* `z-[1002]`: o tooltip nasce num portal e precisa passar por cima do
+                  `DialogContent` (z-1001), senão fica escondido atrás do modal. */}
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <button
+                    type="button"
+                    onClick={handleOpenCardModal}
+                    aria-label={translate('common.promo.aiCreditsOffer.editPayment')}
+                    className="flex size-8 cursor-pointer items-center justify-center rounded-lg text-zinc-400 transition-colors hover:bg-zinc-100 hover:text-zinc-950"
+                  >
+                    <IconPencil size={18} />
+                  </button>
+                </TooltipTrigger>
+                <TooltipContent side="top" sideOffset={6} className="z-[1002]">
+                  {translate('common.promo.aiCreditsOffer.editPayment')}
+                </TooltipContent>
+              </Tooltip>
+            </div>
+          </>
+        ) : (
+          <button
+            type="button"
+            onClick={handleOpenCardModal}
+            className="paragraph-small-semibold flex h-8 w-fit cursor-pointer items-center rounded-md border border-zinc-200 px-2 text-zinc-950 transition-colors hover:border-zinc-400"
+          >
+            <IconPlus className="size-[18px]" />
+            <span className="px-1.5">{translate('common.cards.paymentInfo.addCard')}</span>
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/components/modals/promo/AiCreditsOfferModal/index.ts

@@ -0,0 +1 @@
+export { default } from './AiCreditsOfferModal';

package/src/components/ui/form/ComboboxField.tsx

@@ -71,7 +71,13 @@ export function ComboboxField({
         </div>
       )}
 
+      {/* `modal` é obrigatório para o combobox funcionar dentro de Dialog modal
+        * (ex.: Preferências): sem ele, o FocusScope do Dialog rouba o foco no
+        * pointerdown da opção (o conteúdo do Popover é portalado pra fora do Dialog)
+        * e o Popover fecha antes do click — a opção nunca é selecionada. Com `modal`,
+        * o Popover entra na pilha de focus scopes do Radix e pausa o do Dialog. */}
       <Popover
+        modal
         open={open}
         onOpenChange={(v) => {
           if (!disabled) {

package/src/handlers.ts

@@ -5,6 +5,8 @@ export { createListChargesHandler } from './modules/charges/handlers/list-charge
 export { createFindChargeByIdHandler } from './modules/charges/handlers/find-charge-by-id.handler';
 
 export { createListIaCreditsHandler } from './modules/ia-credits/handlers/list-ia-credits.handler';
+export { createPurchaseIaCreditsHandler } from './modules/ia-credits/handlers/purchase-ia-credits.handler';
+export { createGetAiCreditsOfferEligibilityHandler } from './modules/ia-credits/handlers/get-offer-eligibility.handler';
 
 export { createCountPagesHandler } from './modules/pages/handlers/count-pages.handler';
 

package/src/i18n/messages/en-us.ts

@@ -612,6 +612,39 @@ const messages = {
     'en-us': 'English (US)',
     'es-es': 'Spanish',
   },
+
+  // Modais promocionais compartilhados entre app/accounts/editor.
+  promo: {
+    // Componente: AiCreditsOfferModal.
+    aiCreditsOffer: {
+      eyebrow: 'First purchase pack',
+      title: '{credits} AI credits <break></break>at {discount}',
+      bullets: {
+        first: 'Build a full page from one prompt.',
+        second: 'Generate copy and images in the editor.',
+        third: 'One-time credits: your plan stays as is.',
+      },
+      discountBadge: '{percent}% OFF',
+      cta: 'Get my credits at {discount}',
+      ctaAddCard: 'Add card and lock in the discount',
+      later: 'Not now',
+      editPayment: 'Edit payment details',
+      close: 'Close',
+      successToast: 'Done! {credits} AI credits are now in your account.',
+      errorToast: 'We could not complete the purchase. Please try again.',
+      cardVerification: 'Your card asked for an extra verification. Try another card.',
+      illustration: {
+        credits: 'credits',
+      },
+      exit: {
+        title: 'Sure you want to lose {discount}?',
+        description: 'This screen will not come back. Leave now and the {credits} credits go back to {price}.',
+        descriptionNoPrice: 'This screen will not come back. Leave now and the {credits} credits go back to full price.',
+        keep: 'Back to the offer',
+        lose: 'Lose my offer',
+      },
+    },
+  },
 } as const;
 
 export default messages;

package/src/i18n/messages/es-es.ts

@@ -613,6 +613,39 @@ const messages = {
     'en-us': 'Inglés (EE. UU.)',
     'es-es': 'Español',
   },
+
+  // Modais promocionais compartilhados entre app/accounts/editor.
+  promo: {
+    // Componente: AiCreditsOfferModal.
+    aiCreditsOffer: {
+      eyebrow: 'Paquete primera compra',
+      title: '{credits} créditos de IA <break></break>con {discount}',
+      bullets: {
+        first: 'Crea una página entera con un prompt.',
+        second: 'Genera textos e imágenes en el editor.',
+        third: 'Créditos sueltos: no tocan tu plan.',
+      },
+      discountBadge: '{percent}% OFF',
+      cta: 'Quiero mis créditos con {discount}',
+      ctaAddCard: 'Agregar tarjeta y asegurar el descuento',
+      later: 'Ahora no',
+      editPayment: 'Editar datos de pago',
+      close: 'Cerrar',
+      successToast: '¡Listo! {credits} créditos de IA ya están en tu cuenta.',
+      errorToast: 'No pudimos completar la compra. Inténtalo de nuevo.',
+      cardVerification: 'Tu tarjeta pidió una verificación extra. Prueba con otra tarjeta.',
+      illustration: {
+        credits: 'créditos',
+      },
+      exit: {
+        title: '¿Seguro que quieres perder {discount}?',
+        description: 'Esta pantalla no vuelve. Si sales ahora, los {credits} créditos vuelven a costar {price}.',
+        descriptionNoPrice: 'Esta pantalla no vuelve. Si sales ahora, los {credits} créditos vuelven al precio completo.',
+        keep: 'Volver a la oferta',
+        lose: 'Perder mi oferta',
+      },
+    },
+  },
 } as const;
 
 export default messages;

package/src/i18n/messages/pt-br.ts

@@ -641,6 +641,39 @@ const messages = {
     description: 'A página que você está procurando não existe. Verifique se digitou corretamente o link que está procurando.',
     backToHome: 'Voltar para o início',
   },
+
+  // Modais promocionais compartilhados entre app/accounts/editor.
+  promo: {
+    // Componente: AiCreditsOfferModal (movido verbatim do gpages — pendência de copy: ver PR).
+    aiCreditsOffer: {
+      eyebrow: 'Pacote primeira compra',
+      title: '{credits} créditos de IA <break></break>com {discount}',
+      bullets: {
+        first: 'Crie uma página inteira com um prompt.',
+        second: 'Gere textos e imagens direto no editor.',
+        third: 'Créditos avulsos: não mexem no seu plano.',
+      },
+      discountBadge: '{percent}% OFF',
+      cta: 'Quero meus créditos com {discount}',
+      ctaAddCard: 'Cadastrar cartão e garantir o desconto',
+      later: 'Agora não',
+      editPayment: 'Editar informações de pagamento',
+      close: 'Fechar',
+      successToast: 'Pronto! {credits} créditos de IA entraram na sua conta.',
+      errorToast: 'Não foi possível concluir a compra. Tente novamente.',
+      cardVerification: 'Seu cartão pediu uma verificação extra. Tente outro cartão.',
+      illustration: {
+        credits: 'créditos',
+      },
+      exit: {
+        title: 'Quer mesmo perder {discount}?',
+        description: 'Esta tela não volta. Saindo agora, os {credits} créditos voltam a custar {price}.',
+        descriptionNoPrice: 'Esta tela não volta. Saindo agora, os {credits} créditos voltam ao preço cheio.',
+        keep: 'Voltar para a oferta',
+        lose: 'Perder minha oferta',
+      },
+    },
+  },
 } as const;
 
 export default messages;

package/src/index.ts

@@ -114,6 +114,28 @@ export type {
   IaCreditAddBatch,
   IaCreditOperation,
 } from "./modules/ia-credits/types";
+export { usePurchaseIaCredits } from "./modules/ia-credits/hooks/purchase-ia-credits.hook";
+export { useAiCreditsOfferEligibility } from "./modules/ia-credits/hooks/use-offer-eligibility.hook";
+export {
+  AI_CREDITS_FIRST_PURCHASE_OFFER,
+  AI_CREDITS_OFFER_ELIGIBILITY_QUERY_KEY,
+  AI_CREDITS_OFFER_MAX_REPEATS,
+  AiCreditsOfferStage,
+  PAYMENT_METHOD_CARD,
+  PAYMENT_METHOD_PIX,
+} from "./modules/ia-credits/constants/ai-credits-offer.constants";
+export type {
+  AiCreditsOfferEligibility,
+  AiCreditsOfferEligibilityResponse,
+  AiCreditsOfferIneligibilityReason,
+  PurchaseIaCreditsInput,
+  PurchaseIaCreditsResult,
+} from "./modules/ia-credits/types/ai-credits-offer.type";
+export {
+  readOfferStageCookie,
+  writeOfferStageCookie,
+} from "./modules/ia-credits/utils/offer-stage-cookie";
+export type { OfferStageRecord } from "./modules/ia-credits/utils/offer-stage-cookie";
 export type {
   Subscription,
   SubscriptionItem,
@@ -224,7 +246,11 @@ export { useBuyCreditsModal } from "./store/useBuyCreditsModal";
 export { useCreditsDisabledModal } from "./store/useCreditsDisabledModal";
 export { usePaidPlanRequiredModal } from "./store/usePaidPlanRequiredModal";
 export { useAccountDeletionWarningModal } from "./store/useAccountDeletionWarningModal";
+export { useAiCreditsOfferModal } from "./store/useAiCreditsOfferModal";
 export { default as BuyCreditsModal } from "./components/modals/BuyCreditsModal";
+export { default as AiCreditsOfferModal } from "./components/modals/promo/AiCreditsOfferModal";
+export { AiCreditsOfferGate } from "./components/layouts/AiCreditsOfferGate";
+export type { AiCreditsOfferGateProps } from "./components/layouts/AiCreditsOfferGate";
 export { default as CreditsDisabledModal } from "./components/modals/CreditsDisabledModal";
 export { default as PaidPlanRequiredModal } from "./components/modals/PaidPlanRequiredModal";
 export { default as AccountFrozenModal } from "./components/modals/AccountFrozenModal";

package/src/modules/auth/utils/get-user-context.ts

@@ -11,6 +11,8 @@ export async function getUserContext(): Promise<{
   id_wl: number;
   id_account: number;
   id_user: number;
+  /** `iat` do JWT — carimbo da sessão de login atual (renovado a cada novo login, não a cada request). */
+  iat: number;
 }> {
   const cookieStore = await cookies();
   const token = process.env.DUMMY_AUTH_TOKEN || cookieStore.get(AUTH_COOKIE_NAME)?.value;
@@ -26,6 +28,7 @@ export async function getUserContext(): Promise<{
       id_wl: Number(payload.id_wl),
       id_account: payload.id_account,
       id_user: payload.id_user,
+      iat: payload.iat,
     };
   } catch {
     throw new ApiError('Token inválido', 'INVALID_TOKEN', 401);

package/src/modules/cards/hooks/cards.hook.ts

@@ -8,7 +8,11 @@ import { useAuthQueryKey } from '../../../hooks/useAuthQueryKey';
 
 export const CARDS_QUERY_KEY = ['cards'] as const;
 
-export function useCards() {
+export interface UseCardsOptions {
+  enabled?: boolean;
+}
+
+export function useCards(options: UseCardsOptions = {}) {
   const queryKey = useAuthQueryKey([...CARDS_QUERY_KEY]);
 
   return useQuery({
@@ -18,5 +22,6 @@ export function useCards() {
       ...result,
       data: result.data.filter((card) => !card.deleted),
     }),
+    enabled: options.enabled ?? true,
   });
 }

package/src/modules/ia-credits/constants/ai-credits-offer.constants.ts

@@ -0,0 +1,41 @@
+/**
+ * Oferta de primeira compra de créditos de IA — o slug é o contrato inteiro com o backend
+ * (gapps-r3-api): ele resolve pacote/preço/elegibilidade a partir dele, o front nunca manda preço.
+ * `credits`/`price` aqui são só o que a UI precisa ANTES do primeiro fetch de elegibilidade (rótulo
+ * do CTA, contador da ilustração) — o preço de tabela ("de R$ 19,90") é a `anchorCents` que vem do
+ * endpoint de elegibilidade, nunca hardcoded.
+ */
+export const AI_CREDITS_FIRST_PURCHASE_OFFER = {
+  slug: 'first-purchase-ia-credits',
+  credits: 500,
+  price: 4.9,
+} as const;
+
+/** 1 = cartão, 3 = pix — mesmos códigos do gapps-r3-api. A oferta só aceita cartão. */
+export const PAYMENT_METHOD_CARD = 1;
+export const PAYMENT_METHOD_PIX = 3;
+
+/**
+ * Escada de estágios da oferta, persistida no cookie `ai-credits-offer-stage`. A ordem importa: o
+ * gate só abre para um estágio MAIOR que o gravado (ver `AiCreditsOfferGate`) — CONVERTED é
+ * terminal, nunca reabre depois dele.
+ */
+export enum AiCreditsOfferStage {
+  NONE = 0,
+  CAMPAIGN_SHOWN = 1,
+  FIRST_USE_SHOWN = 2,
+  HALF_SHOWN = 3,
+  EXHAUSTED_SHOWN = 4,
+  ZERO_SHOWN = 5,
+  CONVERTED = 6,
+}
+
+/**
+ * Teto de REPETIÇÕES dos estágios repetíveis (campanha e sem-crédito) — repetições ALÉM da primeira
+ * aparição, então `3` permite 4 exibições daquele estágio. A campanha é deliberadamente agressiva
+ * (vale inclusive para quem acabou de se cadastrar), mas "agressiva" não é "toda sessão para
+ * sempre": esgotado o teto, a oferta só volta se a conta subir de estágio na escada.
+ */
+export const AI_CREDITS_OFFER_MAX_REPEATS = 3;
+
+export const AI_CREDITS_OFFER_ELIGIBILITY_QUERY_KEY = ['ai-credits-offer-eligibility'] as const;

package/src/modules/ia-credits/handlers/get-offer-eligibility.handler.ts

@@ -0,0 +1,24 @@
+import 'server-only';
+
+import { safeRouteHandler } from '../../../infra/route/safe-route-handler';
+import { getUserContext } from '../../auth/utils/get-user-context';
+import { iaCreditsService } from '../services/ia-credits.service';
+
+/**
+ * `GET /api/ai-credits-offer/eligibility` — proxy da elegibilidade do gapps-r3-api mais o
+ * `sessionIssuedAt` (o `iat` do JWT), que o `AiCreditsOfferGate` usa pra distinguir "mesma sessão de
+ * login" de "sessão nova" nos gatilhos de campanha/zero-créditos. O `iat` é decodificado aqui (rota,
+ * dono do cookie httpOnly) e não no service, que só fala com o backend de créditos.
+ */
+export function createGetAiCreditsOfferEligibilityHandler() {
+  return async function GET() {
+    return safeRouteHandler(async () => {
+      const [{ iat }, eligibility] = await Promise.all([
+        getUserContext(),
+        iaCreditsService.offerEligibility(),
+      ]);
+
+      return { ...eligibility, sessionIssuedAt: iat };
+    });
+  };
+}

package/src/modules/ia-credits/handlers/purchase-ia-credits.handler.ts

@@ -0,0 +1,42 @@
+import 'server-only';
+
+import type { NextRequest } from 'next/server';
+import { ApiError } from '../../../infra/api/types';
+import { PurchaseIaCreditsRequestBodySchema } from '../types/ai-credits-offer.type';
+import { iaCreditsService } from '../services/ia-credits.service';
+
+/**
+ * `POST /api/subscriptions/:id/credits/purchase` — compra avulsa de créditos de IA, comum ou
+ * (com `offer`) a de primeira compra. Desvio deliberado de `safeRouteHandler`: o `BuyOneTimeCreditsModal`
+ * do editor e o `AiCreditsOfferModal` desta lib esperam o envelope CRU do gapps-r3-api direto na
+ * raiz da resposta (`{ status: 1 | 2 | 0, client_secret?, message?, data? }`), inclusive pra
+ * distinguir pago (1), 3DS pendente (2) e recusado (0) — embrulhar em `{ success, data }` quebraria
+ * os dois.
+ */
+export function createPurchaseIaCreditsHandler() {
+  return async function POST(req: NextRequest, { params }: { params: Promise<{ id: string }> }) {
+    const { id } = await params;
+    const parsedBody = PurchaseIaCreditsRequestBodySchema.safeParse(await req.json().catch(() => null));
+
+    if (!parsedBody.success) {
+      return Response.json(
+        { status: 0, message: 'Erro ao comprar créditos de IA' },
+        { status: 400 }
+      );
+    }
+
+    try {
+      const result = await iaCreditsService.purchase(id, {
+        quantity: parsedBody.data.quantity,
+        paymentMethod: parsedBody.data.payment_method,
+        idCard: parsedBody.data.id_card,
+        offer: parsedBody.data.offer,
+      });
+      return Response.json(result);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Erro ao comprar créditos de IA';
+      const status = error instanceof ApiError ? error.statusCode : 500;
+      return Response.json({ status: 0, message }, { status });
+    }
+  };
+}