@greatapps/common 1.1.790 → 1.1.792

package/src/modules/subscriptions/types/cancel-subscription.type.ts

@@ -0,0 +1,8 @@
+import z from 'zod';
+
+export const CancelSubscriptionRequestSchema = z.object({
+  cancellation_reason: z.string().min(1),
+  cancellation_description: z.string().min(1),
+});
+
+export type CancelSubscriptionRequest = z.infer<typeof CancelSubscriptionRequestSchema>;

package/src/modules/subscriptions/types/create-subscription.type.ts

@@ -0,0 +1,79 @@
+import z from 'zod';
+import type { Subscription } from './subscription.type';
+
+export const CreateSubscriptionPlanItemSchema = z.object({
+  id_addon: z.number(),
+  quantity: z.number(),
+  value: z.number().optional(),
+  trial: z.boolean().optional(),
+});
+
+export const CreateSubscriptionRequestSchema = z.object({
+  id_product: z.number(),
+  id_plan: z.number(),
+  type: z.string(),
+  payment_method: z.number(),
+  payment_method_id: z.string().optional(),
+  id_card: z.union([z.number(), z.string()]).optional(),
+  periodicity: z.number().optional(),
+  date_hiring: z.string().optional(),
+  date_due: z.string().optional(),
+  id_coupon: z.number().optional(),
+  plan_items: z.array(CreateSubscriptionPlanItemSchema.partial({ quantity: true })).optional(),
+  financial_document_type: z.number().optional(),
+  financial_document: z.string().optional(),
+  financial_name: z.string().optional(),
+  financial_email: z.string().optional(),
+  zipcode: z.string().optional(),
+  address: z.string().optional(),
+  address_number: z.string().optional(),
+  address_complement: z.string().optional(),
+  neighborhood: z.string().optional(),
+  city: z.string().optional(),
+  state: z.string().optional(),
+  tracking: z
+    .object({
+      gclid: z.string().optional(),
+      fbclid: z.string().optional(),
+      fbp: z.string().optional(),
+      fbc: z.string().optional(),
+      ga_client_id: z.string().optional(),
+      ga_session_id: z.string().optional(),
+    })
+    .optional(),
+});
+
+export type CreateSubscriptionRequest = z.infer<typeof CreateSubscriptionRequestSchema>;
+
+export const PixCreateSubscriptionDataSchema = z.object({
+  qr_code: z.string().nullable().optional(),
+  payment_link: z.string().nullable().optional(),
+  correlation_id: z.string(),
+  expires_at: z.string().nullable().optional(),
+});
+
+/**
+ * Discrimina por `pending` + `payment_method` + presença de `pix`. `id` aceita null ou string
+ * porque as trilhas de pix do backend divergem nesse campo (ver `SubscriptionPendingPixResponse`).
+ */
+export const CreateSubscriptionPendingPixResponseSchema = z
+  .object({
+    id: z.union([z.string(), z.null()]).optional(),
+    pending: z.literal(true),
+    payment_method: z.literal(3),
+    pix: PixCreateSubscriptionDataSchema,
+  })
+  .passthrough();
+
+export type CreateSubscriptionPendingPixResponse = z.infer<
+  typeof CreateSubscriptionPendingPixResponseSchema
+>;
+
+export type CreateSubscriptionResponse = Subscription | CreateSubscriptionPendingPixResponse;
+
+export function isPendingPixCreateSubscriptionResponse(
+  value: unknown
+): value is CreateSubscriptionPendingPixResponse {
+  return CreateSubscriptionPendingPixResponseSchema.safeParse(value).success;
+}
+

package/src/modules/subscriptions/types/pending-pix-status.type.ts

@@ -0,0 +1,33 @@
+import z from 'zod';
+
+export const PendingPixStatusPhaseSchema = z.enum([
+  'creating',
+  'awaiting_authorization',
+  'completed',
+  'rejected',
+  'expired',
+]);
+
+export type PendingPixStatusPhase = z.infer<typeof PendingPixStatusPhaseSchema>;
+
+export const PendingPixStatusDataSchema = z
+  .object({
+    phase: PendingPixStatusPhaseSchema,
+    payment_method: z.number().nullable().optional(),
+    subscription_id: z.union([z.number(), z.string()]).optional(),
+    completed_at: z.string().nullable().optional(),
+    pix: z
+      .object({
+        qr_code: z.string().nullable().optional(),
+        payment_link: z.string().nullable().optional(),
+        correlation_id: z.string().nullable().optional(),
+        expires_at: z.string().nullable().optional(),
+        expires_at_inferred: z.boolean().nullable().optional(),
+        expires_at_source: z.string().nullable().optional(),
+        authorization_created_at: z.string().nullable().optional(),
+      })
+      .optional(),
+  })
+  .passthrough();
+
+export type PendingPixStatusData = z.infer<typeof PendingPixStatusDataSchema>;

package/src/modules/subscriptions/types/subscription.type.ts

@@ -1,147 +1,157 @@
-import z from 'zod';
-import { calendarDateSchema } from '../../../infra/utils/date';
-
-export const SubscriptionItemSchema = z.object({
-  id: z.union([z.number(), z.string()]),
-  deleted: z.number(),
-  datetime_alt: z.coerce.date().nullable().optional(),
-  datetime_del: z.coerce.date().nullable().optional(),
-  datetime_add: z.coerce.date(),
-  id_wl: z.number(),
-  id_subscription: z.union([z.number(), z.string()]),
-  id_addon: z.number().nullable(),
-  addon_name: z.string().optional(),
-  value: z.number().nullable(),
-  currency: z.string(),
-  quantity: z.number().nullable().transform((v) => v ?? 0),
-  payment_status: z.number().nullable(),
-  id_charge: z.union([z.number(), z.string()]).nullable(),
-  trial: z.boolean().nullable(),
-  trial_ends_at: z.coerce.date().nullable().optional(),
-});
-
-export type SubscriptionItem = z.infer<typeof SubscriptionItemSchema>;
-
-export const SubscriptionSchema = z.object({
-  id: z.union([z.number(), z.string()]),
-  deleted: z.number(),
-  datetime_alt: z.coerce.date().nullable().optional(),
-  datetime_del: z.coerce.date().nullable().optional(),
-  datetime_add: z.coerce.date(),
-  id_wl: z.number(),
-  id_account: z.union([z.number(), z.string()]),
-  id_card: z.union([z.number(), z.string()]).nullable(),
-  id_coupon: z.union([z.number(), z.string()]).nullable(),
-  type: z.string(),
-  payment_method: z.number().nullable(),
-  periodicity: z.coerce.number().nullable(),
-  value: z.number().nullable(),
-  id_product: z.number(),
-  id_plan: z.number().nullable(),
-  plan_name: z.string().nullable().optional(),
-  id_gateway: z.union([z.number(), z.string()]).nullable(),
-  gateway_account: z.string().nullable(),
-  date_hiring: calendarDateSchema().nullable(),
-  date_due: calendarDateSchema().nullable(),
-  date_cancellation: calendarDateSchema().nullable(),
-  date_verification: calendarDateSchema().nullable(),
-  cancellation_reason: z.string().nullable(),
-  cancellation_description: z.string().nullable(),
-  active: z.boolean(),
-  charged: z.boolean(),
-  datetime_last_update_periodicity: z.coerce.date().nullable().optional(),
-  card_name: z.string().nullable().optional(),
-  card_brand: z.string().nullable().optional(),
-  card_number: z.string().nullable().optional(),
-  card: z.object({
-    id_card: z.union([z.number(), z.string()]).nullable().optional(),
-    brand: z.string().nullable().optional(),
-    expires_at: z.string().nullable().optional(),
-    last4: z.string().nullable().optional(),
-    name: z.string().nullable().optional(),
-  }).nullable().optional(),
-  /* payment_retry: tentativas de cobrança no cartão (Stripe Smart Retries / dunning),
-   * lidas ao vivo do latest_invoice. null para boleto/pix (sem retries). Ver gapps-r3-api #229. */
-  payment_retry: z.object({
-    attempt_count: z.number(),
-    next_attempt_at: z.string().nullable(),
-    invoice_status: z.string().nullable(),
-  }).nullable().optional(),
-  items: z.array(SubscriptionItemSchema),
-  pending_change: z.object({
-    schedule_id: z.string(),
-    schedule_status: z.string(),
-    kind: z.string(),
-    takes_effect_at: z.number().nullable(),
-    takes_effect_at_iso: z.string().nullable(),
-    new_plan: z.object({
-      id: z.number(),
-      name: z.string(),
-      periodicity: z.number().nullable(),
-      value: z.number(),
-      value_gross: z.number(),
-    }).nullable(),
-    new_items: z.array(z.object({
-      price_id: z.string(),
-      id_addon: z.number().nullable(),
-      addon_name: z.string().nullable(),
-      quantity: z.number(),
-      unit_value: z.number(),
-      value: z.number(),
-      is_plan_base: z.boolean(),
-      is_ai_credit: z.boolean(),
-    })),
-    new_limits: z.record(z.string(), z.number()).nullable().optional(),
-    new_discounts: z.array(z.unknown()),
-    changes: z.array(z.object({
-      type: z.string(),
-      id_addon: z.number().nullable().optional(),
-      addon_name: z.string().nullable().optional(),
-      quantity: z.number().optional(),
-      from: z.unknown().optional(),
-      to: z.unknown().optional(),
-    })),
-  }).nullable().optional(),
-  metadata: z.record(z.string(), z.unknown()).optional(),
-});
-
-export type Subscription = z.infer<typeof SubscriptionSchema>;
-
-/* Desfecho da cobrança imediata pedida com `charge_now` na troca de forma de pagamento
- * (gapps-r3-api, PUT subscriptions/:id/action/payment).
- *
- * Vem separado do `status` da resposta de propósito: quando isto chega, a troca JÁ está firmada
- * no banco e na Stripe. Uma cobrança recusada aqui não desfaz a troca — o dunning da Stripe segue
- * armado no cartão novo —, então a tela precisa contar as duas coisas em separado.
- *
- * `outcome` é a ÚNICA fonte da verdade sobre o que aconteceu, e a tela deve falar só a partir dele.
- * Substituiu um par de booleanos (`attempted`/`paid`) que não distinguia recusa de 3DS pendente: a
- * tela lia `paid: false` depois de um desafio bem-sucedido e anunciava falha para um pagamento que
- * tinha acabado de completar.
- *
- * `amount` vem em centavos, na `currency` da fatura, e é o valor REALMENTE cobrado — não uma
- * previsão feita antes da chamada. */
-export interface ChargeNowResult {
-  outcome: 'charged' | 'requires_action' | 'declined' | 'none';
-  invoice_id?: string;
-  amount?: number | null;
-  currency?: string | null;
-  client_secret?: string;
-  /* Presente em `declined`: a razão que o emissor deu. */
-  message?: string;
-  /* Presente em `none`: por que não houve o que cobrar (`sem_fatura_de_ciclo_aberta`,
-   * `deteccao_falhou`, `sem_contexto_de_cobranca`). */
-  reason?: string;
-}
-
-export interface FindSubscriptionsParams {
-  active?: boolean;
-  trial?: boolean;
-  date_start?: string;
-  date_end?: string;
-  date_hiring_start?: string;
-  date_hiring_end?: string;
-  limit?: number;
-  page?: number;
-  id_product?: number;
-}
+import z from 'zod';
+import { calendarDateSchema } from '../../../infra/utils/date';
+
+export const SubscriptionItemSchema = z.object({
+  id: z.union([z.number(), z.string()]),
+  deleted: z.number(),
+  datetime_alt: z.coerce.date().nullable().optional(),
+  datetime_del: z.coerce.date().nullable().optional(),
+  datetime_add: z.coerce.date(),
+  id_wl: z.number(),
+  id_subscription: z.union([z.number(), z.string()]),
+  id_addon: z.number().nullable(),
+  addon_name: z.string().optional(),
+  value: z.number().nullable(),
+  currency: z.string(),
+  quantity: z.number().nullable().transform((v) => v ?? 0),
+  payment_status: z.number().nullable(),
+  id_charge: z.union([z.number(), z.string()]).nullable(),
+  trial: z.boolean().nullable(),
+  trial_ends_at: z.coerce.date().nullable().optional(),
+});
+
+export type SubscriptionItem = z.infer<typeof SubscriptionItemSchema>;
+
+export const SubscriptionSchema = z.object({
+  id: z.union([z.number(), z.string()]),
+  deleted: z.number(),
+  datetime_alt: z.coerce.date().nullable().optional(),
+  datetime_del: z.coerce.date().nullable().optional(),
+  datetime_add: z.coerce.date(),
+  id_wl: z.number(),
+  id_account: z.union([z.number(), z.string()]),
+  id_card: z.union([z.number(), z.string()]).nullable(),
+  id_coupon: z.union([z.number(), z.string()]).nullable(),
+  type: z.string(),
+  payment_method: z.number().nullable(),
+  periodicity: z.coerce.number().nullable(),
+  value: z.number().nullable(),
+  id_product: z.number(),
+  id_plan: z.number().nullable(),
+  plan_name: z.string().nullable().optional(),
+  id_gateway: z.union([z.number(), z.string()]).nullable(),
+  gateway_account: z.string().nullable(),
+  date_hiring: calendarDateSchema().nullable(),
+  date_due: calendarDateSchema().nullable(),
+  date_cancellation: calendarDateSchema().nullable(),
+  date_verification: calendarDateSchema().nullable(),
+  cancellation_reason: z.string().nullable(),
+  cancellation_description: z.string().nullable(),
+  active: z.boolean(),
+  charged: z.boolean(),
+  datetime_last_update_periodicity: z.coerce.date().nullable().optional(),
+  card_name: z.string().nullable().optional(),
+  card_brand: z.string().nullable().optional(),
+  card_number: z.string().nullable().optional(),
+  card: z.object({
+    id_card: z.union([z.number(), z.string()]).nullable().optional(),
+    brand: z.string().nullable().optional(),
+    expires_at: z.string().nullable().optional(),
+    last4: z.string().nullable().optional(),
+    name: z.string().nullable().optional(),
+  }).nullable().optional(),
+  /* payment_retry: tentativas de cobrança no cartão (Stripe Smart Retries / dunning),
+   * lidas ao vivo do latest_invoice. null para boleto/pix (sem retries). Ver gapps-r3-api #229. */
+  payment_retry: z.object({
+    attempt_count: z.number(),
+    next_attempt_at: z.string().nullable(),
+    invoice_status: z.string().nullable(),
+  }).nullable().optional(),
+  items: z.array(SubscriptionItemSchema),
+  pending_change: z.object({
+    schedule_id: z.string(),
+    schedule_status: z.string(),
+    kind: z.string(),
+    takes_effect_at: z.number().nullable(),
+    takes_effect_at_iso: z.string().nullable(),
+    new_plan: z.object({
+      id: z.number(),
+      name: z.string(),
+      periodicity: z.number().nullable(),
+      value: z.number(),
+      value_gross: z.number(),
+    }).nullable(),
+    new_items: z.array(z.object({
+      price_id: z.string(),
+      id_addon: z.number().nullable(),
+      addon_name: z.string().nullable(),
+      quantity: z.number(),
+      unit_value: z.number(),
+      value: z.number(),
+      is_plan_base: z.boolean(),
+      is_ai_credit: z.boolean(),
+    })),
+    new_limits: z.record(z.string(), z.number()).nullable().optional(),
+    // Descontos aplicados na alteração agendada (periodicidade e cupom), usados no resumo.
+    new_discounts: z.array(
+      z
+        .object({
+          name: z.string().nullish(),
+          kind: z.string().nullish(),
+          percent_off: z.number().nullish(),
+          amount_off: z.number().nullish(),
+        })
+        .passthrough()
+    ),
+    changes: z.array(z.object({
+      type: z.string(),
+      id_addon: z.number().nullable().optional(),
+      addon_name: z.string().nullable().optional(),
+      quantity: z.number().optional(),
+      from: z.unknown().optional(),
+      to: z.unknown().optional(),
+    })),
+  }).nullable().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type Subscription = z.infer<typeof SubscriptionSchema>;
+
+/* Desfecho da cobrança imediata pedida com `charge_now` na troca de forma de pagamento
+ * (gapps-r3-api, PUT subscriptions/:id/action/payment).
+ *
+ * Vem separado do `status` da resposta de propósito: quando isto chega, a troca JÁ está firmada
+ * no banco e na Stripe. Uma cobrança recusada aqui não desfaz a troca — o dunning da Stripe segue
+ * armado no cartão novo —, então a tela precisa contar as duas coisas em separado.
+ *
+ * `outcome` é a ÚNICA fonte da verdade sobre o que aconteceu, e a tela deve falar só a partir dele.
+ * Substituiu um par de booleanos (`attempted`/`paid`) que não distinguia recusa de 3DS pendente: a
+ * tela lia `paid: false` depois de um desafio bem-sucedido e anunciava falha para um pagamento que
+ * tinha acabado de completar.
+ *
+ * `amount` vem em centavos, na `currency` da fatura, e é o valor REALMENTE cobrado — não uma
+ * previsão feita antes da chamada. */
+export interface ChargeNowResult {
+  outcome: 'charged' | 'requires_action' | 'declined' | 'none';
+  invoice_id?: string;
+  amount?: number | null;
+  currency?: string | null;
+  client_secret?: string;
+  /* Presente em `declined`: a razão que o emissor deu. */
+  message?: string;
+  /* Presente em `none`: por que não houve o que cobrar (`sem_fatura_de_ciclo_aberta`,
+   * `deteccao_falhou`, `sem_contexto_de_cobranca`). */
+  reason?: string;
+}
+
+export interface FindSubscriptionsParams {
+  active?: boolean;
+  trial?: boolean;
+  date_start?: string;
+  date_end?: string;
+  date_hiring_start?: string;
+  date_hiring_end?: string;
+  limit?: number;
+  page?: number;
+  id_product?: number;
+}

package/src/modules/subscriptions/utils/addon-buckets.ts

@@ -0,0 +1,129 @@
+import type { SubscriptionItem } from '../types/subscription.type';
+
+export type AddonBucket = {
+  key: string;             // `${idAddon}_${value}` — used as bucketEdits key
+  idAddon: number;
+  value: number;           // unit price (R$)
+  quantity: number;        // current editor qty (edited or original)
+  originalQuantity: number; // qty from subscription (ceiling for alternatives)
+  isPrimary: boolean;      // true = value matches plan price
+};
+
+/**
+ * Groups subscription items for a given addon into price buckets,
+ * applies any in-progress edits, and ensures a primary bucket always exists.
+ *
+ * - Filters items where `id_addon === addonId` and `value > 0`
+ * - Groups by value (backend já entrega value mensal por unidade), summing quantities
+ * - Marks the bucket whose price is within R$0.01 of `planPrice` as primary
+ * - If no bucket is primary, creates a synthetic primary with qty=0
+ * - Applies `bucketEdits[key]` overrides when present
+ * - Sorts: primary first, then by value descending
+ */
+export function getAddonBuckets(
+  addonId: number,
+  subscriptionItems: SubscriptionItem[],
+  planPrice: number,
+  bucketEdits: Record<string, number>,
+): AddonBucket[] {
+  // Filter relevant items
+  const relevant = subscriptionItems.filter(
+    (item) => item.id_addon === addonId && (item.value ?? 0) > 0
+  );
+
+  // Group by value (já é mensal por unidade, conforme contrato do backend),
+  // summing quantities
+  const grouped = new Map<number, number>();
+  for (const item of relevant) {
+    const value = item.value!;
+    grouped.set(value, (grouped.get(value) ?? 0) + item.quantity);
+  }
+
+  // Build buckets
+  const buckets: AddonBucket[] = [];
+  for (const [value, originalQuantity] of grouped.entries()) {
+    const key = `${addonId}_${value}`;
+    const isPrimary = Math.abs(value - planPrice) < 0.01;
+    const quantity = key in bucketEdits ? bucketEdits[key] : originalQuantity;
+    buckets.push({ key, idAddon: addonId, value, quantity, originalQuantity, isPrimary });
+  }
+
+  // Ensure a primary bucket exists
+  const hasPrimary = buckets.some((b) => b.isPrimary);
+  if (!hasPrimary) {
+    const key = `${addonId}_${planPrice}`;
+    const quantity = key in bucketEdits ? bucketEdits[key] : 0;
+    buckets.push({
+      key,
+      idAddon: addonId,
+      value: planPrice,
+      quantity,
+      originalQuantity: 0,
+      isPrimary: true,
+    });
+  }
+
+  // Sort: primary first, then by value descending
+  buckets.sort((a, b) => {
+    if (a.isPrimary !== b.isPrimary) return a.isPrimary ? -1 : 1;
+    return b.value - a.value;
+  });
+
+  return buckets;
+}
+
+/**
+ * Converts addon buckets into the `plan_extras` shape expected by the API.
+ *
+ * Bucket quantities already represent the EXTRA paid domains only
+ * (items with value > 0 from the subscription), never the plan-included base.
+ * All buckets are included (even qty=0) so the backend can explicitly zero them.
+ */
+export function buildDomainPlanExtras(
+  buckets: AddonBucket[],
+): Array<{ id_addon: number; quantity: number; value: number }> {
+  return buckets.map((bucket) => ({
+    id_addon: bucket.idAddon,
+    value: bucket.value,
+    quantity: bucket.quantity,
+  }));
+}
+
+/**
+ * Em fluxos de upgrade/troca de plano (ou reativação), a UI colapsa todos os
+ * extras num único bucket no preço do novo plano. Mas a sub atual pode ter items
+ * em outros preços (ex: extras antigos de R$ 8,50 e R$ 8,90 quando o novo plano
+ * cobra R$ 9,00). Sem enviar esses preços antigos com `quantity: 0`, o backend
+ * mantém os items legados ativos junto com o bucket novo.
+ *
+ * Esta função retorna AddonBucket sintéticos com `quantity: 0` pra cada preço
+ * único da sub atual que difere do `primaryPrice`. A comparação `< 0.01` filtra
+ * apenas ruído de IEEE 754 (ex: 8.500000001 vs 8.5) — preços reais separados por
+ * exatamente R$ 0,01 (ex: 8.50 vs 8.51) são intencionalmente tratados como
+ * distintos.
+ */
+export function buildZeroedOldBuckets(
+  addonId: number,
+  subscriptionItems: SubscriptionItem[],
+  primaryPrice: number,
+): AddonBucket[] {
+  const seen = new Set<number>();
+  const result: AddonBucket[] = [];
+  for (const item of subscriptionItems) {
+    if (item.id_addon !== addonId) continue;
+    const value = item.value ?? 0;
+    if (value <= 0) continue;
+    if (Math.abs(value - primaryPrice) <= 0.01) continue;
+    if (seen.has(value)) continue;
+    seen.add(value);
+    result.push({
+      key: `${addonId}_${value}`,
+      idAddon: addonId,
+      value,
+      quantity: 0,
+      originalQuantity: item.quantity,
+      isPrimary: false,
+    });
+  }
+  return result;
+}

package/src/modules/subscriptions/utils/confirm-payment-if-required.ts

@@ -7,9 +7,16 @@ import type { Stripe } from "@stripe/stripe-js";
  * criar outra, senão vira cobrança duplicada (Asana ID-4743).
  */
 export class PaymentAuthenticationError extends Error {
-  constructor(message: string) {
+  /**
+   * Segredo da cobrança que ficou pendente. A retentativa autentica ESTA cobrança em vez de
+   * criar outra assinatura — sem isso, errar o desafio e tentar de novo cobra duas vezes.
+   */
+  readonly clientSecret?: string;
+
+  constructor(message: string, clientSecret?: string) {
     super(message);
     this.name = "PaymentAuthenticationError";
+    this.clientSecret = clientSecret;
   }
 }
 
@@ -31,6 +38,6 @@ export async function confirmPaymentIfRequired(
 
   const { error } = await stripe.confirmCardPayment(clientSecret);
   if (error) {
-    throw new PaymentAuthenticationError(error.message || fallbackErrorMessage);
+    throw new PaymentAuthenticationError(error.message || fallbackErrorMessage, clientSecret);
   }
 }

package/src/modules/subscriptions/utils/first-period-pricing.ts

@@ -0,0 +1,63 @@
+import type { CouponStripeData } from '../../coupons/types/coupon.type';
+import type { BillingPeriod } from '../types/billing-period.type';
+
+/**
+ * Split de preço para cupom de duração limitada (Stripe `duration: once | repeating`): o 1º
+ * período sai com desconto e os seguintes voltam ao preço cheio. Exibir só o preço descontado
+ * prometeria um valor que não se mantém.
+ */
+export type FirstPeriodPricing = {
+  kind: 'once' | 'repeating';
+  /** Total do 1º período (já com cupom). */
+  firstPrice: number;
+  /** Total recorrente sem o cupom = total + desconto do cupom. */
+  recurringPrice: number;
+  /** Meses de vigência quando `repeating`; null em `once`. */
+  durationMonths: number | null;
+};
+
+/**
+ * Deriva o split 1º período × recorrente. Retorna null (sem split) quando o cupom não tem
+ * duração limitada (`forever`/ausente) ou quando `couponDiscount <= 0` — cupom rejeitado pelo
+ * backend ou não aplicável à periodicidade escolhida (o calculate zera a coluna do período).
+ */
+export function getFirstPeriodPricing(params: {
+  stripeData: CouponStripeData | null | undefined;
+  total: number;
+  couponDiscount: number;
+}): FirstPeriodPricing | null {
+  const { stripeData, total, couponDiscount } = params;
+  const duration = stripeData?.duration;
+
+  if (duration !== 'once' && duration !== 'repeating') return null;
+  if (couponDiscount <= 0) return null;
+
+  return {
+    kind: duration,
+    firstPrice: total,
+    recurringPrice: total + couponDiscount,
+    durationMonths: duration === 'repeating' ? (stripeData?.duration_in_months ?? null) : null,
+  };
+}
+
+/**
+ * Chave do rótulo do 1º período. `firstMonths` só no período mensal com `durationMonths`
+ * inteiro > 1 — nunca renderizar `{count}` vazio; qualquer outro `repeating` aproxima para
+ * "1º {período}", já que a fatura semestral/anual cobre o período inteiro.
+ */
+export function getFirstPeriodLabelKey(
+  period: BillingPeriod,
+  pricing: FirstPeriodPricing
+): 'firstMonthly' | 'firstSemiannual' | 'firstAnnual' | 'firstMonths' {
+  if (
+    pricing.kind === 'repeating' &&
+    period === 'monthly' &&
+    Number.isInteger(pricing.durationMonths) &&
+    (pricing.durationMonths ?? 0) > 1
+  ) {
+    return 'firstMonths';
+  }
+  if (period === 'annual') return 'firstAnnual';
+  if (period === 'semiannual') return 'firstSemiannual';
+  return 'firstMonthly';
+}

package/src/modules/subscriptions/utils/is-api-subscription.ts

@@ -0,0 +1,6 @@
+import type { Subscription } from '../types/subscription.type';
+import { API_PLAN_ID } from '../constants/subscription.constants';
+
+export function isApiSubscription(subscription: Subscription | null | undefined): boolean {
+  return !!subscription && subscription.id_plan === API_PLAN_ID;
+}