SDK Node.js (TypeScript)

A SDK oficial Node.js / TypeScript espelha a API pública da SDK Java. Destinada a backends (Express, Fastify, Nest, etc.) — não use secrets no browser.

Requisitos

Node.js ≥ 18.17. TypeScript 5+ recomendado para consumidores TS.

Instalação

npm install @gatekeeperid/sdk

Pacote público no npm: @gatekeeperid/sdk.

Configuração

A SDK não lê variáveis de ambiente sozinha — passe a config explicitamente (igual ao builder Java).

import { GatekeeperClient, GatekeeperAuthService } from "@gatekeeperid/sdk";

const client = new GatekeeperClient({
  baseUrl: process.env.GATEKEEPER_BASE_URL!, // …/sdk/integration/v1
  tenantId: process.env.GATEKEEPER_TENANT_ID!,
  applicationName: process.env.GATEKEEPER_APPLICATION_NAME ?? "my-api",
  environment: process.env.GATEKEEPER_ENVIRONMENT ?? "dev",
  clientId: process.env.GATEKEEPER_CLIENT_ID,
  hmacEnabled: true,
  hmacSecret: process.env.GATEKEEPER_HMAC_SECRET,
});

const auth = new GatekeeperAuthService(client, {
  gkRoleDefaultRegister: "USER",
  autoGenerateExternalId: true,
});

Autenticação (BFF)

const session = await auth.login({ email, password });
await auth.register({ email, password, name: "Ana", last_name: "Silva" });
const me = await auth.me(session.access_token!);
await auth.refresh({ refresh_token: session.refresh_token! });
await auth.logout({ refresh_token: session.refresh_token! });

Social · senha · conta · GK_ROLE

await auth.startSocialLogin("google", redirectUri, state);
await auth.exchangeSocialCode("google", code);
await auth.forgotPassword({ email, redirect_uri: "https://app/login" });
await auth.resetPassword({ token, password, confirmPassword: password });
await auth.changePassword(accessToken, { currentPassword, newPassword, confirmPassword });
await auth.deleteAccount(accessToken, { password, refresh_token });
await auth.updateUserGkRole("gk-user-1", "TUTORING");

Auth no BFF

Exponha /auth/login, /auth/register, etc. no seu backend e delegue a GatekeeperAuthService. Persistência de perfil (endereço, …) é sua; o vínculo com o GateKeeper é external_id (em me também GK_EXTERNAL_ID).

Guia completo: /docs/quickstart.

Authorize

await client.authorize(accessToken, { method: "GET", path: "/api/orders" });
// throws GatekeeperAuthorizationException se negado

Integration plan

await client.sendIntegrationPlanWithFingerprint({
  application_name: "orders-api",
  environment: "dev",
  routes: [
    { method: "GET", path: "/orders", permission: "orders:read", description: "List" },
  ],
});

No boot da aplicação, envie o plan; no middleware, chame authorize. Equivalente ao @GatekeeperProtected do Spring.

Erros tipados

• GatekeeperAuthenticationException — token / sessão
• GatekeeperAuthorizationException — 403 / ACCESS_DENIED
• GatekeeperConfigurationException — HMAC / config
• GatekeeperUnavailableException — rede / timeout

Ver também

SDK Java (Spring Boot) · Referência da API · OpenAPI · FAQ