Custom Hooks

Total: 9 hooks

---

useAuth

Arquivo: src/hooks/use-auth.ts

Hook de autenticação. Busca user e account do Supabase. Gerencia login/logout.

Return

Campo	Tipo	Descrição
userId	string | null	ID do usuário
account	Account | null	Conta ativa
role	AccountRole | null	Role na conta ativa
accounts	AccountWithRole[]	Todas as contas
isLoading	boolean	Estado de carregamento
isAdmin	boolean	Se e platform admin
supportMode	object | null	Support mode info
logout	() => Promise<void>	Função de logout

Comportamento

1. No mount, busca supabase.auth.getUser()
2. Se autenticado, busca /api/accounts para obter contas + active_account_id
3. Determina conta ativa: cookie > store > primeira da lista
4. Persiste em useAuthStore
5. Escuta onAuthStateChange para redirect em SIGNED_OUT
6. Logout: supabase.auth.signOut() + clearAuth + redirect

Uso

• AppLayout (garante auth em toda area protegida)
• SettingsLayout (botao logout)
• TrackingPage
• ProfileSettingsPage

---

useApiQuery<T>

Arquivo: src/hooks/use-api-query.ts

Hook genérico para GET requests com cache e AbortController.

Params

Param	Tipo	Default	Descrição
url	string | null	required	URL da API. null desabilita a query.
options.enabled	boolean	true	Se a query deve ser executada
options.refreshInterval	number	0	Intervalo de refresh em ms (0 = sem refresh)
options.refreshWhenHidden	boolean	true	Se deve fazer refresh quando tab está hidden

Return

Campo	Tipo	Descrição
data	T | null	Dados retornados
isLoading	boolean	Estado de carregamento
error	string | null	Mensagem de erro
refetch	() => Promise<void>	Função para re-buscar dados

Comportamento

• Faz fetch(url) com AbortController
• Cancela request anterior ao fazer nova (abort)
• Extrai json.data ?? json do response
• Suporta refresh periodico via setInterval
• Re-fetch automático quando url ou enabled mudam

Uso

Usado em praticamente TODAS as páginas do app (Dashboard, Chat, Contacts, Analytics, etc.).

---

useApiMutation<TInput>

Arquivo: src/hooks/use-api-mutation.ts

Hook genérico para POST/PUT/PATCH/DELETE requests com toast notifications.

Params (options)

Param	Tipo	Default	Descrição
method	"POST" | "PUT" | "PATCH" | "DELETE"	"POST"	Método HTTP
successMessage	string	undefined	Mensagem de sucesso (toast)
onSuccess	(data: unknown) => void	undefined	Callback após sucesso

Return

Campo	Tipo	Descrição
mutate	(url: string, body?: TInput) => Promise<unknown | null>	Função de mutação
isLoading	boolean	Estado de carregamento
error	string | null	Mensagem de erro

Comportamento

• Faz fetch(url, { method, body: JSON.stringify(body) })
• Em sucesso: toast success (se configurado) + chama onSuccess
• Em erro: toast error + retorna null
• Extrai data?.data ?? data do response

Uso

Usado em todas as operações de escrita (criar contato, atualizar template, excluir automação, etc.).

---

usePáginatedQuery<T>

Arquivo: src/hooks/use-páginated-query.ts

Hook para queries com paginação offset-based (page + limit).

Params

Param	Tipo	Default	Descrição
fetcher	(params) => Promise<PáginatedResult<T>>	required	Função de fetch
options.initialPage	number	1	Página inicial
options.initialLimit	number	20	Itens por página
options.initialSearch	string	""	Busca inicial

Return

Campo	Tipo	Descrição
data	T[]	Dados da página atual
total	number	Total de itens
page	number	Página atual
totalPages	number	Total de páginas
search	string	Busca atual
isLoading	boolean	Estado de carregamento
setPage	(page: number) => void	Navegar para página
setSearch	(search: string) => void	Alterar busca (reseta page=1)
refresh	() => void	Recarregar página atual

---

useCursorPáginatedQuery<T>

Arquivo: src/hooks/use-cursor-páginated-query.ts

Hook para queries com paginação cursor-based (infinite scroll).

Params

Param	Tipo	Default	Descrição
baseUrl	string	required	URL base da API
options.limit	number	20	Itens por página
options.enabled	boolean	true	Se a query deve ser executada

Return

Campo	Tipo	Descrição
data	T[]	Todos os dados carregados (acumulados)
isLoading	boolean	Loading da primeira página
isLoadingMore	boolean	Loading de páginas adicionais
hasMore	boolean	Se existem mais itens
loadMore	() => void	Carregar proxima página
refetch	() => void	Recarregar desde o início

Comportamento

• Acumula dados (append) ao fazer loadMore
• refetch() reseta cursor e recarrega do zero
• AbortController para cancelar requests pendentes
• Response esperado: { data: T[], nextCursor: string | null, hasMore: boolean }

Uso

• ContactsPage: lista de contatos com infinite scroll

---

useRealtimeConversations

Arquivo: src/hooks/use-realtime-conversations.ts

Hook para escutar mudancas em tempo real na tabela conversations via Supabase Realtime.

Params

Param	Tipo	Descrição
accountId	string | null	ID da conta (filter)
onInsert	(conversation) => void	Callback para nova conversa
onUpdate	(conversation) => void	Callback para conversa atualizada

Comportamento

• Cria channel Supabase: conversations:{accountId}
• Escuta postgres_changes (INSERT + UPDATE) na tabela conversations
• Filtra por account_id=eq.{accountId}
• Cleanup: remove channel no unmount

Uso

• ChatPage: refetch conversas em INSERT e UPDATE

---

useRealtimeMessages

Arquivo: src/hooks/use-realtime-messages.ts

Hook para escutar mudancas em tempo real na tabela messages via Supabase Realtime.

Params

Param	Tipo	Descrição
conversationId	string | null	ID da conversa ativa

Comportamento

• Cria channel Supabase: messages:{conversationId}
• Escuta postgres_changes (INSERT + UPDATE) na tabela messages
• INSERT: addMessage no chat store
• UPDATE: updateMessageStatus no chat store
• Cleanup: remove channel no unmount

Uso

• ChatPage: adiciona mensagens em tempo real e atualiza status

---

useOnboarding

Arquivo: src/hooks/use-onboarding.ts

Hook para gerenciar checklist de onboarding no dashboard.

Params

Param	Tipo	Descrição
stats	OnboardingStats | null	Stats do dashboard
profiles	OnboardingProfile[]	WhatsApp profiles
accountId	string | null	ID da conta

Return

Campo	Tipo	Descrição
isDismissed	boolean	Se usuário dismissou o checklist
steps	OnboardingStep[]	5 steps com id, label, href, completed
progress	number	Quantos steps completos (0-5)
isComplete	boolean	Se todos os 5 steps estão completos
dismiss	() => void	Função para dismissar

Steps

1. Conta criada — sempre true
2. WhatsApp conectado — profile com status “connected”
3. Primeiro template criado — kpi.templates > 0
4. Contatos importados — kpi.contacts > 0
5. Primeira campanha enviada — alguma campanha com status != “draft”

Persistência

• Dismiss salvo em localStorage com key x17-onboarding-dismissed-{accountId}

---

useUndoRedo

Arquivo: src/hooks/use-undo-redo.ts

Hook para undo/redo no editor de automações.

Params

Param	Tipo	Descrição
setNodes	(updater) => void	Setter de nodes do ReactFlow
setEdges	(updater) => void	Setter de edges do ReactFlow

Return

Campo	Tipo	Descrição
takeSnapshot	(nodes, edges) => void	Salva estado atual no histórico
undo	() => void	Desfaz última ação
redo	() => void	Refaz última ação desfeita
canUndo	boolean	Se pode desfazer
canRedo	boolean	Se pode refazer

Comportamento

• Usa useRef para histórico (past + future stacks)
• MAX_HISTORY = 50 snapshots
• takeSnapshot: push no past, limpa future
• undo: pop do past, push no future, aplica estado
• redo: pop do future, push no past, aplica estado
• Usa structuredClone para deep copy

Uso

• AutomationEditorPage: Ctrl+Z / Ctrl+Shift+Z / Ctrl+Y
• Chamado antes de cada operação destrutiva (add node, delete node, drop, connect)