@golive/auth

Login de utilizadores para a tua app — email/password geridos pelo GoLive. Sem dependências, sem firebase/*. Guarda a sessão e renova o token sozinho.

Instalar

O registry npm não é usado — instala a partir do GoLive:

$ npm i https://golive.co.ao/sdk/golive-auth-0.1.0.tgz

Sem passo de build (browser), importa por URL:

import { GoLiveAuth } from "https://golive.co.ao/sdk/auth.js";

As chaves (apiKey, tenant e controlPlane) estão no dashboard, em Autenticação → Integrar no cliente. Activa o serviço primeiro com golive auth enable.

Início rápido

import { GoLiveAuth } from "@golive/auth";

const auth = new GoLiveAuth({
  apiKey: "AIza…",             // chave pública do projecto
  tenant: "…",                 // tenant de autenticação
  controlPlane: "https://…/api", // vem no snippet do dashboard
});

// registar ou entrar
await auth.signUp(email, password);
await auth.signIn(email, password);

// token para o teu backend
const token = await auth.getIdToken();
await fetch("/api/perfil", { headers: { Authorization: `Bearer ${token}` } });

// reagir a login/logout (chama já com o estado actual)
auth.onChange((user) => console.log(user ? user.email : "sem sessão"));

Este SDK lança erros (GoLiveAuthError) — envolve as chamadas em try/catch. É diferente do @golive/data e do @golive/storage, que devolvem { data, error } e nunca lançam.

Configuração

Sem controlPlane o signIn funciona, mas o signUp falha — é o control plane que valida o limite do plano.

signUp(email, password)

Cria um utilizador e inicia a sessão. Devolve Promise<GoLiveUser>. Passa pelo control plane para aplicar o tecto do plano.

try {
  const user = await auth.signUp("ana@loja.ao", "segredo123");
  console.log(user.uid, user.email);
} catch (err) {
  if (err.code === "EMAIL_EXISTS") setErro("Este email já tem conta.");
  else if (err.code === "quota_exceeded") setErro("Limite de utilizadores do plano atingido.");
  else setErro(err.message);
}

No plano Free o tecto é 100 utilizadores por projecto → quota_exceeded. No Pague por uso a escala é maior (1 000 MAU grátis/mês, depois 100 Kz/MAU).

signIn(email, password)

Inicia sessão com email/password. Devolve Promise<GoLiveUser>.

try {
  await auth.signIn(email, password);
} catch (err) {
  if (err.code === "INVALID_LOGIN_CREDENTIALS") setErro("Email ou password errados.");
}

signOut()

Termina a sessão local e limpa o armazenamento. Devolve Promise<void>. Dispara o onChange com null.

await auth.signOut();

getIdToken(forceRefresh?)

Devolve um ID token válido (Promise<string>), renovando-o se estiver a expirar. É este o token que envias ao teu backend em Authorization: Bearer <token>.

const token = await auth.getIdToken();
const fresco = await auth.getIdToken(true);  // força renovação

Lança nao_autenticado se não houver sessão. Chamadas concorrentes partilham uma só renovação.

onChange(callback)

Subscreve mudanças de sessão (login/logout). Chama já com o estado actual. Devolve uma função para cancelar.

const unsub = auth.onChange((user) => {
  setUtilizador(user);           // GoLiveUser | null
});

// mais tarde (ex.: cleanup do useEffect)
unsub();

currentUser

Propriedade (não é função): o utilizador da sessão persistida, ou null. Útil no arranque, antes de qualquer chamada de rede.

if (auth.currentUser) mostrarDashboard(auth.currentUser.email);

sendPasswordReset(email)

Envia um email de recuperação de password. Devolve Promise<void>.

await auth.sendPasswordReset("ana@loja.ao");

updateProfile({ displayName })

Actualiza o perfil do utilizador autenticado. Devolve Promise<GoLiveUser>.

const user = await auth.updateProfile({ displayName: "Ana Silva" });

Tipos

// o utilizador da tua app
interface GoLiveUser {
  uid: string;
  email: string | null;
  displayName: string | null;
  emailVerified: boolean;
  createdAt?: string;
  lastLoginAt?: string;
}

Erros

Todos os métodos lançam GoLiveAuthError, com um .code estável e uma .message legível em português:

Verificar o token no backend

O token é um JWT. No teu backend, valida-o e usa o sub (uid) para saber quem é o utilizador:

// edge function ou backend
export default async (request) => {
  const token = request.headers.get("Authorization")?.replace("Bearer ", "");
  if (!token) return new Response("sem token", { status: 401 });
  // valida e lê o uid do payload
  const payload = JSON.parse(atob(token.split(".")[1]));
  return Response.json({ uid: payload.sub, email: payload.email });
};

Dev Pack (local)

Com o Auth ligado no Dev Pack (golive dev init), aponta os três endpoints para o host local. A env injectada traz GOLIVE_AUTH_ENDPOINT:

const base = import.meta.env.VITE_GOLIVE_AUTH_ENDPOINT
  ?? "http://localhost:18321/__golive/auth";

const auth = new GoLiveAuth({
  apiKey: "dev",
  tenant: "dev",
  endpoints: {
    identity: `${base}/identity/v1`,
    secureToken: `${base}/token/v1`,
    controlPlane: base,   // obrigatório: o signUp passa por aqui
  },
});

Os utilizadores locais ficam em .golive/dev/auth.json (não commites a pasta .golive/) e aparecem no painel /__golive/, no separador Auth — onde também podes criá-los à mão.