@wepayments/auth-sdk-react

SDK oficial da WePayments para autenticação em aplicações React.

Este pacote fornece uma solução completa para autenticação baseada em RBAC (Role-Based Access Control), com suporte a múltiplos ambientes, gerenciamento automático de tokens, identificação de usuários internos e sincronização de sessões entre abas do navegador.

🏢 Sobre a WePayments

A WePayments é uma plataforma moderna de infraestrutura financeira, focada em simplificar operações de pagamento e gestão de saldo para empresas. Oferecemos soluções robustas de cobrança, conciliação e controle financeiro, com APIs seguras e flexíveis voltadas para escalabilidade e compliance.

O @wepayments/auth-sdk-react é o SDK que permite que você conecte sua aplicação React ao sistema de autenticação da WePayments de forma segura, performática e com suporte a múltiplos perfis de acesso.

🚀 Instalação

npm install @wepayments/auth-sdk-react

📦 Requisitos

Este pacote exige as seguintes peer dependencies:

{
  "react": "^16.8.0 || ^17.0.0 || ^18.0.0",
  "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0"
}

⚙️ Uso Básico

1. Configure o AuthProvider no nível mais alto da sua aplicação:

import { AuthProvider } from '@wepayments/auth-sdk-react';

function App() {
  return (
    <AuthProvider environment="production">
      <YourApp />
    </AuthProvider>
  );
}

2. Use o hook useAuth em qualquer componente para acessar o contexto de autenticação:

import { useAuth } from '@wepayments/auth-sdk-react';

function Profile() {
  const { user, logout, isAuthenticated, tokens } = useAuth();

  if (!isAuthenticated) {
    return <div>Please log in</div>;
  }

  return (
    <div>
      <h1>Welcome, {user?.name}!</h1>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

🌐 Ambientes Suportados

O SDK permite alternar entre diferentes ambientes da plataforma WePayments por meio da propriedade environment no AuthProvider:

| Ambiente | Descrição | |--------------|-----------------------------------------| | production | Ambiente de produção oficial | | sandbox | Ambiente de testes | | staging | Ambiente de homologação | | development| Ambiente local (usa o mesmo de staging) |

Exemplo:

<AuthProvider 
  environment="production"
  storageKey="custom_storage_key" // opcional
>
  {children}
</AuthProvider>

🧩 Propriedades do AuthProvider

| Propriedade | Tipo | Padrão | Descrição | |-------------|-----------|-----------------|------------------------------------------------------| | environment | string | "development" | Define o ambiente da API | | storageKey | string | "auth_state" | Chave usada para persistir o estado no localStorage| | children | ReactNode | - | Componentes da aplicação envoltos pelo provider |

🔐 Interface User

O objeto user representa os dados do usuário autenticado:

| Campo | Tipo | Descrição | |---------------|--------------------|-----------------------------------------------------| | id | string | ID único do usuário | | email | string | Email do usuário | | name | string | Nome completo | | locale | 'pt' | 'en' | Idioma preferido | | companyId | number | ID da empresa principal | | companies | number[] | Lista de IDs de empresas acessíveis pelo usuário | | permissions | string[] | Permissões atribuídas ao usuário | | roles | string[] | Papéis vinculados ao usuário |

🧠 Interface AuthState

| Campo | Tipo | Descrição | |-------------------|---------------------|------------------------------------------------| | isAuthenticated | boolean | Indica se o usuário está logado | | isLoading | boolean | Indica se a autenticação está em andamento | | user | User | null | Dados do usuário logado | | error | Error | null | Erro de autenticação (se houver) | | internalUser | boolean | Se o usuário é considerado interno | | authStatus | AuthStatus | Status detalhado da sessão | | tokens | AuthTokens | null| Tokens de autenticação |

AuthTokens interface:

| Campo | Tipo | Descrição | |----------------|----------|------------------------------| | token | string | Token de acesso JWT | | refreshToken | string | Token para renovar a sessão |

AuthStatus valores possíveis:

• 'idle'
• 'checking'
• 'refreshing'
• 'authenticated'
• 'redirecting'

🛠 Hook useAuth

const {
  user,
  isAuthenticated,
  isLoading,
  error,
  internalUser,
  authStatus,
  tokens,
  checkAuth,
  logout
} = useAuth();

👥 Identificação de Usuários Internos

O SDK identifica automaticamente se o usuário é interno e salva no parametro internalUser retornado no custom hook useAuth.

🔐 Gerenciamento de Sessão

O SDK cuida automaticamente de:

• Armazenamento seguro de tokens (localStorage)
• Refresh automático de sessão
• Redirecionamento automático para login
• Compartilhamento de sessão entre múltiplas abas
• Suporte a políticas de segurança com Row Level Security (RLS)

✅ Exemplo Completo

import { AuthProvider, useAuth } from '@wepayments/auth-sdk-react';

function AuthenticatedContent() {
  const { user, logout, isLoading, internalUser, tokens } = useAuth();

  if (isLoading) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      <h1>Welcome {user?.name}!</h1>
      <p>Email: {user?.email}</p>
      {internalUser && <p>Internal User Access</p>}
      <button onClick={logout}>Logout</button>
    </div>
  );
}

function App() {
  return (
    <AuthProvider environment="production">
      <AuthenticatedContent />
    </AuthProvider>
  );
}