@greatapps/common 1.1.739 → 1.1.741

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

@@ -348,6 +348,46 @@ const messages = {
       newPaymentMethod: 'New payment method',
     },
   },
+  billing: {
+    requiredData: {
+      title: 'Complete your billing information',
+      description:
+        'We need this information to issue the invoice for your payments. Filling it in is required to keep using the platform.',
+      addressHeading: 'Billing address',
+      select: 'Select',
+      typeHere: 'Type here',
+      personType: 'Entity type',
+      personTypePf: 'Individual',
+      personTypePj: 'Company',
+      cpf: 'CPF',
+      cnpj: 'CNPJ',
+      fullName: 'Full name',
+      companyName: 'Legal name',
+      financialEmail: 'Billing email',
+      financialEmailPlaceholder: 'billing@company.com',
+      cep: 'ZIP code',
+      postalCode: 'Postal code',
+      street: 'Address',
+      streetNumber: 'Number',
+      neighborhood: 'District',
+      complement: 'Complement',
+      city: 'City',
+      state: 'State',
+      stateProvince: 'State/Province',
+      country: 'Country',
+      submit: 'Save and continue',
+      submitting: 'Saving...',
+      successToast: 'Billing information saved successfully.',
+      errorToast: 'We could not save your billing information, please try again.',
+      requiredField: 'Required field',
+      invalidEmail: 'Invalid email',
+      invalidCep: 'Invalid ZIP code',
+      invalidCpf: 'Invalid CPF',
+      invalidCnpj: 'Invalid CNPJ',
+      invalidCpfChecksum: 'Invalid CPF — check the verification digits',
+      invalidCnpjChecksum: 'Invalid CNPJ — check the verification digits',
+    },
+  },
   navigation: {
     banners: {
       cancelled: {

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

@@ -349,6 +349,46 @@ const messages = {
       newPaymentMethod: 'Nuevo método de pago',
     },
   },
+  billing: {
+    requiredData: {
+      title: 'Completa tus datos de facturación',
+      description:
+        'Necesitamos esta información para emitir la factura de tus pagos. Completarla es obligatorio para seguir usando la plataforma.',
+      addressHeading: 'Dirección de facturación',
+      select: 'Selecciona',
+      typeHere: 'Escribe aquí',
+      personType: 'Tipo de persona',
+      personTypePf: 'Persona física',
+      personTypePj: 'Persona jurídica',
+      cpf: 'CPF',
+      cnpj: 'CNPJ',
+      fullName: 'Nombre completo',
+      companyName: 'Razón social',
+      financialEmail: 'Correo de facturación',
+      financialEmailPlaceholder: 'facturacion@empresa.com',
+      cep: 'Código postal',
+      postalCode: 'Código postal',
+      street: 'Dirección',
+      streetNumber: 'Número',
+      neighborhood: 'Barrio',
+      complement: 'Complemento',
+      city: 'Ciudad',
+      state: 'Estado',
+      stateProvince: 'Estado/Provincia',
+      country: 'País',
+      submit: 'Guardar y continuar',
+      submitting: 'Guardando...',
+      successToast: 'Datos de facturación guardados con éxito.',
+      errorToast: 'No se pudieron guardar los datos de facturación, inténtalo de nuevo.',
+      requiredField: 'Campo obligatorio',
+      invalidEmail: 'Correo electrónico inválido',
+      invalidCep: 'Código postal inválido',
+      invalidCpf: 'CPF inválido',
+      invalidCnpj: 'CNPJ inválido',
+      invalidCpfChecksum: 'CPF inválido — revisa los dígitos verificadores',
+      invalidCnpjChecksum: 'CNPJ inválido — revisa los dígitos verificadores',
+    },
+  },
   navigation: {
     banners: {
       cancelled: {

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

@@ -360,6 +360,48 @@ const messages = {
     },
   },
 
+  // Componente: RequiredBillingDataModal.
+  billing: {
+    requiredData: {
+      title: 'Complete seus dados de cobrança',
+      description:
+        'Precisamos dessas informações para emitir a nota fiscal dos seus pagamentos. O preenchimento é obrigatório para continuar usando a plataforma.',
+      addressHeading: 'Endereço de cobrança',
+      select: 'Selecione',
+      typeHere: 'Digite aqui',
+      personType: 'Tipo de pessoa',
+      personTypePf: 'Pessoa física',
+      personTypePj: 'Pessoa jurídica',
+      cpf: 'CPF',
+      cnpj: 'CNPJ',
+      fullName: 'Nome completo',
+      companyName: 'Razão social',
+      financialEmail: 'E-mail financeiro',
+      financialEmailPlaceholder: 'financeiro@empresa.com',
+      cep: 'CEP',
+      postalCode: 'Código postal',
+      street: 'Endereço',
+      streetNumber: 'Número',
+      neighborhood: 'Bairro',
+      complement: 'Complemento',
+      city: 'Cidade',
+      state: 'UF',
+      stateProvince: 'Estado/Província',
+      country: 'País',
+      submit: 'Salvar e continuar',
+      submitting: 'Salvando...',
+      successToast: 'Dados de cobrança salvos com sucesso.',
+      errorToast: 'Não foi possível salvar os dados de cobrança, tente novamente.',
+      requiredField: 'Campo obrigatório',
+      invalidEmail: 'E-mail inválido',
+      invalidCep: 'CEP inválido',
+      invalidCpf: 'CPF inválido',
+      invalidCnpj: 'CNPJ inválido',
+      invalidCpfChecksum: 'CPF inválido — confira os dígitos verificadores',
+      invalidCnpjChecksum: 'CNPJ inválido — confira os dígitos verificadores',
+    },
+  },
+
   // Componentes de navegação: banners de assinatura, seletor de projeto, links de rodapé, créditos, plano.
   navigation: {
     banners: {

package/src/index.ts

@@ -188,6 +188,7 @@ export {
 export { buildPlanExtras } from "./modules/subscriptions/utils/build-plan-extras";
 export { hasSubscriptionExpired } from "./modules/subscriptions/utils/has-subscription-expired";
 export { hasActivePaidSubscription } from "./modules/subscriptions/utils/has-active-paid-subscription";
+export { hasPaidSubscription } from "./modules/subscriptions/utils/has-paid-subscription";
 export {
   confirmPaymentIfRequired,
   PaymentAuthenticationError,
@@ -213,6 +214,7 @@ export { default as BuyCreditsModal } from "./components/modals/BuyCreditsModal"
 export { default as CreditsDisabledModal } from "./components/modals/CreditsDisabledModal";
 export { default as PaidPlanRequiredModal } from "./components/modals/PaidPlanRequiredModal";
 export { default as AccountDeletionWarningModal } from "./components/modals/AccountDeletionWarningModal";
+export { default as RequiredBillingDataModal } from "./components/modals/billing/RequiredBillingDataModal";
 export { default as AddCardModal } from "./components/modals/cards/AddCardModal";
 export { DeleteCardModal } from "./components/modals/cards/DeleteCardModal";
 export { CannotDeleteCardModal } from "./components/modals/cards/CannotDeleteCardModal";
@@ -516,16 +518,25 @@ export {
   useUpdateAccount,
   useUpdateAccountUser,
   useUpdateAccountUserById,
+  useUpdateBillingData,
   useDeleteAccountUser,
   useDeleteAccount,
   ACCOUNT_USERS_QUERY_KEY,
 } from "./modules/accounts/hooks/useAccountManagement";
 export { useViaCep } from "./modules/accounts/hooks/useViaCep";
 export { useAccountToken } from "./modules/accounts/hooks/use-account-token.hook";
+export { useRequiredBillingData } from "./modules/accounts/hooks/use-required-billing-data.hook";
+export {
+  hasCompleteBillingData,
+  isInternationalAccount,
+  INTERNATIONAL_GATEWAY,
+} from "./modules/accounts/utils/billing-data";
+export type { BillingDataSnapshot } from "./modules/accounts/utils/billing-data";
 
 // Account Types
 export type {
   UpdateAccountRequest,
+  UpdateBillingDataRequest,
   UpdateAccountUserRequest,
   ChangePasswordRequest,
   DeleteAccountActionResult,

package/src/modules/accounts/actions/account-management.action.ts

@@ -10,6 +10,7 @@ import type {
   DeleteAccountRequest,
   UpdateAccountRequest,
   UpdateAccountUserRequest,
+  UpdateBillingDataRequest,
 } from '../types';
 import { twoFactorService } from '../services/two-factor.service';
 import { findUserById } from '../../users/action/find-user-by-id.action';
@@ -51,6 +52,29 @@ export async function updateAccountAction(data: UpdateAccountRequest) {
   });
 }
 
+/**
+ * Cadastro de cobrança/fiscal. Restrito a owner/admin — mesmo recorte de
+ * `manage_subscriptions` no `assertManagementPermission`, replicado aqui pra não
+ * arrastar a checagem de assinatura vigente junto (a conta pode estar em atraso
+ * e ainda assim precisa poder regularizar o cadastro).
+ */
+export async function updateBillingDataAction(data: UpdateBillingDataRequest) {
+  return safeMutationAction(async () => {
+    const userResult = await findUserById();
+    const profile = userResult.success ? userResult.data?.profile : undefined;
+
+    if (profile !== UserProfile.owner && profile !== UserProfile.admin) {
+      throw new ApiError(
+        'Apenas o proprietário ou um administrador pode alterar os dados de cobrança',
+        'FORBIDDEN',
+        403
+      );
+    }
+
+    return accountService.updateAccount(data);
+  });
+}
+
 export async function deleteAccountUserAction(userId: number) {
   return safeMutationAction(() => accountService.deleteAccountUser(userId));
 }

package/src/modules/accounts/hooks/use-required-billing-data.hook.ts

@@ -0,0 +1,38 @@
+'use client';
+
+import { useCurrentAccount } from './current-account.hook';
+import { useActiveSubscription } from '../../subscriptions/hooks/find-active-subscription.hook';
+import { hasPaidSubscription } from '../../subscriptions/utils/has-paid-subscription';
+import { useManagementPermissions } from '../../auth/hooks/useManagementPermissions';
+import { hasCompleteBillingData, isInternationalAccount } from '../utils/billing-data';
+
+/**
+ * Contas que já pagaram mas nunca preencheram o cadastro de cobrança ficam sem
+ * nota fiscal (chamado "Nota fiscal não emitida em pagamentos confirmados").
+ * Este hook diz quando o preenchimento vira obrigatório — o modal que ele
+ * alimenta é bloqueante, então só liga com os dados já carregados e só para
+ * quem consegue resolver: owner/admin.
+ */
+export function useRequiredBillingData() {
+  const { isOwnerOrAdmin } = useManagementPermissions();
+  const { data: account, isPending: isAccountPending } = useCurrentAccount();
+  const {
+    data: { data: [subscription] = [] } = {},
+    isPending: isSubscriptionPending,
+  } = useActiveSubscription();
+
+  const isLoading = isAccountPending || isSubscriptionPending;
+
+  const isRequired =
+    !isLoading &&
+    isOwnerOrAdmin &&
+    hasPaidSubscription(subscription) &&
+    !hasCompleteBillingData(account);
+
+  return {
+    isRequired,
+    isLoading,
+    account,
+    isInternational: isInternationalAccount(account),
+  };
+}

package/src/modules/accounts/hooks/useAccountManagement.ts

@@ -14,6 +14,7 @@ import {
   updateUserAction,
   updateAccountAction,
   updateAccountUserByIdAction,
+  updateBillingDataAction,
   deleteAccountUserAction,
   deleteAccountAction,
 } from '../actions/account-management.action';
@@ -39,6 +40,18 @@ export function useUpdateAccount() {
   });
 }
 
+export function useUpdateBillingData() {
+  const queryClient = useQueryClient();
+  const accountKey = useWlQueryKey([...ACCOUNT_QUERY_KEY]);
+
+  return useMutation({
+    mutationFn: withAction(updateBillingDataAction),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: accountKey });
+    },
+  });
+}
+
 export function useUpdateAccountUser() {
   const queryClient = useQueryClient();
   const accountUsersKey = useAuthQueryKey([...ACCOUNT_USERS_QUERY_KEY]);

package/src/modules/accounts/types.ts

@@ -154,6 +154,7 @@ export interface UpdateAccountRequest {
     financial_document_type?: number;
     financial_document?: string;
     financial_name?: string;
+    financial_email?: string;
     zipcode?: string;
     address?: string;
     address_number?: string;
@@ -164,6 +165,16 @@ export interface UpdateAccountRequest {
     country?: string;
 }
 
+/**
+ * Dados de cobrança/fiscais. É o `UpdateAccountRequest` sem `name` de propósito:
+ * o nome da empresa é exclusivo do owner (ver `updateAccountAction`) e não deve
+ * viajar junto do formulário de cobrança, que também é editável por admin.
+ */
+export type UpdateBillingDataRequest = Omit<
+    UpdateAccountRequest,
+    'name' | 'currency' | 'timezone' | 'bussiness_type'
+>;
+
 export interface UpdateAccountResponse {
     status: 0 | 1;
     message: string;

package/src/modules/accounts/utils/billing-data.ts

@@ -0,0 +1,81 @@
+import type { Account } from '../types';
+
+/**
+ * Gateway das contas cobradas em USD. Elas não têm CPF/CNPJ, bairro nem número —
+ * mesmo critério usado no AddCardModal (`account.gateway === 'stripe_usd'`).
+ */
+export const INTERNATIONAL_GATEWAY = 'stripe_usd';
+
+export type BillingDataSnapshot = Pick<
+  Account,
+  | 'gateway'
+  | 'financial_document'
+  | 'financial_name'
+  | 'financial_email'
+  | 'zipcode'
+  | 'address'
+  | 'address_number'
+  | 'neighborhood'
+  | 'city'
+  | 'state'
+  | 'country'
+>;
+
+type BillingField = keyof Omit<BillingDataSnapshot, 'gateway'>;
+
+/**
+ * Campos exigidos em qualquer país — sem eles a nota fiscal não sai.
+ *
+ * `financial_email` NÃO entra: o backend cai no e-mail do usuário quando ele está
+ * vazio (`financial_email || userDocument.email`, accounts/services.js), então a
+ * nota sai do mesmo jeito. Exigi-lo aqui bloquearia 4.7k contas pagantes da wl 1
+ * em vez das ~460 que de fato estão sem cadastro fiscal. O campo continua no
+ * formulário, pré-preenchido — só não é critério de bloqueio.
+ */
+const INTERNATIONAL_BILLING_FIELDS: readonly BillingField[] = [
+  'financial_name',
+  'zipcode',
+  'address',
+  'city',
+  'state',
+  'country',
+];
+
+/** No Brasil a NF-e também exige documento fiscal, número e bairro. */
+const BR_BILLING_FIELDS: readonly BillingField[] = [
+  ...INTERNATIONAL_BILLING_FIELDS,
+  'financial_document',
+  'address_number',
+  'neighborhood',
+];
+
+export function isInternationalAccount(
+  account: Pick<BillingDataSnapshot, 'gateway'> | null | undefined,
+): boolean {
+  return account?.gateway === INTERNATIONAL_GATEWAY;
+}
+
+function isFilled(value: string | null | undefined): boolean {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+/**
+ * A conta tem todos os dados de cobrança/fiscais necessários pra emissão de nota.
+ * Retorna `false` quando a conta ainda não carregou — quem decide bloquear é o
+ * chamador, que checa o loading antes (ver `useRequiredBillingData`).
+ */
+export function hasCompleteBillingData(
+  account: BillingDataSnapshot | null | undefined,
+): boolean {
+  if (!account) return false;
+
+  const fields = isInternationalAccount(account)
+    ? INTERNATIONAL_BILLING_FIELDS
+    : BR_BILLING_FIELDS;
+
+  for (const field of fields) {
+    if (!isFilled(account[field])) return false;
+  }
+
+  return true;
+}

package/src/modules/subscriptions/utils/has-paid-subscription.ts

@@ -0,0 +1,27 @@
+import type { Subscription } from '../types/subscription.type';
+
+const FREE_PLAN_ID = 5;
+
+type PaidSubscriptionSnapshot = Pick<Subscription, 'type' | 'id_plan' | 'charged'>;
+
+/**
+ * A conta já teve pagamento confirmado numa assinatura paga.
+ *
+ * Diferente de `hasActivePaidSubscription`, aqui NÃO importa se a assinatura
+ * segue vigente: quem pagou e depois cancelou/atrasou continua precisando de
+ * nota fiscal do que já foi cobrado. Por isso o sinal é `charged` (marcado pelo
+ * backend no `bill_paid`), e não `active`/`date_due`.
+ *
+ * Free e trial ficam de fora — nunca houve cobrança a documentar.
+ */
+export function hasPaidSubscription(
+  subscription: PaidSubscriptionSnapshot | undefined | null,
+): boolean {
+  if (!subscription) return false;
+  if (subscription.type === 'free' || subscription.id_plan === FREE_PLAN_ID) {
+    return false;
+  }
+  if (subscription.type === 'trial') return false;
+
+  return subscription.charged === true;
+}

package/src/server.ts

@@ -59,6 +59,7 @@ export {
   updateUserAction,
   updateAccountAction,
   updateAccountUserByIdAction,
+  updateBillingDataAction,
   deleteAccountUserAction,
   deleteAccountAction,
   createAccountUserAction,