Esta versão (v0.7) ainda não foi publicada no npm.
Pular para o conteúdo

Sessão e tokens ​

O login devolve um access token (JWT de vida curta) e um refresh token. O SDK guarda os dois num TokenStore e cuida da renovação:

  • Proativa: antes de cada request, se faltarem menos de 2 minutos para o access token expirar, o SDK renova primeiro.
  • Reativa: se o gateway responder 401 por causa do token (um 401 sem código, como o middleware de autenticação do gateway responde a um token ausente, expirado ou inválido, ou um com TOKEN_EXPIRED ou TOKEN_STALE), o SDK renova e repete o request uma vez. Requests simultâneos compartilham um único refresh. Um 401 com qualquer outro código, como INVALID_CREDENTIALS para a senha atual errada em changePassword ou disable2fa, ou UNAUTHENTICATED/TOKEN_INVALID repassado de um serviço (ex.: um código de verificação errado), chega ao app como veio: sem refresh, sem repetição (a senha não é enviada duas vezes) e sem onAccessTokenRejected.
  • Falha: se o refresh for recusado, a sessão é limpa e onSessionExpired é chamado.
  • Falha transitória: se o refresh cair por rede/timeout ou a resposta vier sem tokens válidos (VALIDATION_ERROR), os tokens atuais são mantidos e o request falha com esse erro; onSessionExpired não é chamado.

Clientes de servidor: autoRefresh: false ​

Clientes de servidor (RSC/SSR) devem usar autoRefresh: false; a renovação fica com o browser ou com um Route Handler.

ts
const enginex = createEnginexClient({
  baseUrl: 'https://gateway.operador.com',
  tenantHost: 'casino.operador.com',
  autoRefresh: false,
})

Com autoRefresh: false, nem o refresh proativo (antes de um request, com o access token perto de expirar) nem o reativo (após um 401) chamam POST /auth/refresh:

  • O access token guardado é usado como está.
  • Um 401 chega ao chamador sem conserto: auth: 'required' rejeita com o erro original do gateway; auth: 'optional' repete sem token — ou seja, uma chamada optional com o token expirado custa dois requests (o 401 e o retry sem token), em vez de um refresh.
  • A sessão local não é limpa e onSessionExpired não é chamado — o servidor não deve decidir isso por um cliente que não é dono da sessão.

Um cliente de servidor por request normalmente lê o access token de um cookie httpOnly (via tokenStore personalizado) e nunca precisa renová-lo: quem faz isso é o browser (com o cliente padrão, autoRefresh: true) ou um Route Handler dedicado.

Quando o app é o dono da sessão ​

Um app que já tem a própria autenticação (um store com login, refresh e logout) não quer que o SDK renove nem grave tokens: dois renovadores trocando o mesmo refresh token derrubam a sessão. Declare isso com sessionOwner: 'app':

ts
import { createEnginexClient } from '@getenginex/sdk'
import { useAuthStore } from '@/stores/auth' // your store: login, logout and refresh belong to the app
import { authStoreTokens } from '@/lib/auth-tokens' // a TokenStore over the app's store

export const enginex = createEnginexClient({
  sessionOwner: 'app',
  tokenStore: authStoreTokens,
  // The gateway refused the current access token: the app renews and writes the new tokens to the store.
  onAccessTokenRejected: () => void useAuthStore.getState().refreshSession(),
})

authStoreTokens é um TokenStore sobre o store do app: o exemplo está em Migrando um player Next.

Com 'app':

  • O SDK só lê o tokenStore para assinar os requests e montar session.get(). Nunca chama POST /auth/refresh e não limpa a sessão; onSessionExpired não é chamado.
  • auth.login e auth.logout (e qualquer escrita de sessão do SDK) rejeitam com CONFIGURATION_ERROR antes de enviar: login e logout são do app.
  • Um 401 chega ao chamador sem conserto (auth: 'optional' ainda repete sem token). Quem renova é o onAccessTokenRejected. A exceção: se o app já gravou um token novo no tokenStore enquanto o request estava em voo, o SDK repete uma vez com o token novo (sem renovar nem gravar nada), e o 401 atrasado não chega ao chamador nem avisa o app.
  • autoRefresh passa a ser false; autoRefresh: true junto com 'app' lança CONFIGURATION_ERROR na criação do cliente. O mesmo vale para onAccessTokenRejected sem sessionOwner: 'app' (com 'sdk', use onSessionExpired).

onAccessTokenRejected é chamado sem argumentos quando o gateway recusa (401 por causa do token, como acima) o access token atual:

  • Uma vez por token. Uma rajada de 401 com o mesmo token (várias queries em paralelo) avisa uma vez só; um 401 atrasado de um token que já foi trocado no tokenStore não avisa (o request é repetido com o token novo). Se o token novo também for recusado, avisa de novo.
  • Dispara também em chamadas auth: 'optional' (ex.: config.get), mesmo quando a repetição sem token dá certo.
  • Não dispara sem token (o UNAUTHENTICATED antes do envio) nem depois de client.dispose(). Uma exceção dentro dele não muda o erro da chamada.
  • O unauthorized do realtime não dispara o onAccessTokenRejected: a conexão WebSocket avisa pelo próprio status (useRealtimeStatus), e a sessão continua sendo do app. Renove o token pelo mesmo caminho do app e a reconexão usa o token novo.

O hook onError continua sendo de observabilidade (um por chamada que falhar), não de renovação.

Onde guardar os tokens ​

StoreSobrevive a reloadEntre abasObservação
memoryTokenStore() (padrão)nãonãoMais seguro contra XSS; o jogador loga de novo ao recarregar.
localStorageTokenStore()simsimLegível por qualquer script da página: use com Content-Security-Policy.
PersonalizadodependedependeImplemente TokenStore (get, set, clear, subscribe).

O localStorageTokenStore sincroniza abas: se outra aba renovar os tokens, esta aba usa os novos em vez de gastar um refresh token já trocado.

Observando a sessão ​

ts
enginex.session.get() // { status: 'authenticated', userId, operatorId, sessionId, expiresAt }
const off = enginex.session.subscribe((s) => console.log(s.status))

session.get() devolve um objeto congelado com a mesma referência enquanto a sessão não muda (uma rotação só do refresh token não conta), e uma referência nova quando ela muda — dá para usar direto com useSyncExternalStore(enginex.session.subscribe, enginex.session.get) no React, sem loop de re-render.

createEnginexClient({ onSessionChange }) é um atalho para session.subscribe.

Callbacks do app (onSessionChange, onSessionExpired, onValidationIssue, listeners de subscribe e do TokenStore) nunca quebram uma operação do SDK: se um deles lançar, o login, o logout ou o request seguem normalmente e o erro é relançado numa microtarefa, então ainda aparece no console e no seu rastreador de erros.