npm package: @neog-cloud/neog-api-client
Description: Pacote reutilizável para autenticação e consumo da API neog
Latest version: 0.1.4

# Neog Auth Client

Pacote TypeScript reutilizável para autenticação e consumo da API da plataforma neog.

## Instalação

```bash
npm install @neog-cloud/neog-api-client
```

## Configuração

```ts
import { createNeogAuth } from "@neog-cloud/neog-api-client";

const { AuthProvider, useAuth, createNeogClient } = createNeogAuth({
  baseUrl: "https://api_neog",
  authBaseUrl: "https://iam_neog",
  authRealm: "__REALM__",
  authEndpoint: "/realms/{realm}/protocol/openid-connect/token",
  authRequestFormat: "form",
  authGrantType: "password",
  authScope: "openid profile email",
  clientId: "app-id",
  clientSecret: "secret"
});
```

## Variáveis de ambiente (exemplo local)

No app de exemplo (Vite), os valores sensíveis são lidos de um arquivo local de ambiente. Crie um arquivo `.env.local` na pasta do app e preencha as variáveis abaixo (o arquivo fica ignorado por padrão pelo `.gitignore` via `*.local`).

```dotenv
VITE_NEOG_BASE_URL=
VITE_NEOG_AUTH_BASE_URL=
VITE_NEOG_AUTH_REALM=
VITE_NEOG_AUTH_ENDPOINT=/realms/{realm}/protocol/openid-connect/token
VITE_NEOG_AUTH_REQUEST_FORMAT=form
VITE_NEOG_AUTH_GRANT_TYPE=password
VITE_NEOG_AUTH_SCOPE=openid profile email
VITE_NEOG_CLIENT_ID=
VITE_NEOG_CLIENT_SECRET=
```

No exemplo, o `createNeogAuth` usa essas variáveis, evitando valores fixos no repositório.

## AuthProvider e useAuth

```tsx
function App() {
  return (
    <AuthProvider>
      <Routes />
    </AuthProvider>
  );
}

function LoginButton() {
  const { login, logout, isAuthenticated, loading } = useAuth();
  return (
    <div>
      <button disabled={loading} onClick={() => login("user", "pass")}>Login</button>
      <button onClick={logout}>Logout</button>
      <span>{isAuthenticated ? "ok" : "off"}</span>
    </div>
  );
}
```

## NeogClient.post

```ts
const client = createNeogClient();

const response = await client.get<{ id: string }>("/status");

```

## Guia de migração (resumido)

1. Instale o pacote:
   ```bash
  npm install @neog-cloud/neog-api-client
   ```
2. Crie a instância:
   ```ts
  import { createNeogAuth } from "@neog-cloud/neog-api-client";

   const { AuthProvider, useAuth, createNeogClient } = createNeogAuth({
     baseUrl: "https://api_neog",
     authBaseUrl: "https://iam_neog",
     authRealm: "__REALM__",
     authEndpoint: "/realms/{realm}/protocol/openid-connect/token",
     authRequestFormat: "form",
     authGrantType: "password",
     authScope: "openid profile email",
     clientId: "app-id",
     clientSecret: "secret",
   });
   ```
3. Substitua o AuthProvider local:
   ```tsx
   function App() {
     return (
       <AuthProvider>
         <Routes />
       </AuthProvider>
     );
   }
   ```
4. Substitua os imports de `useAuth` locais pelos do pacote (mesmos campos).
5. Substitua as chamadas HTTP por `createNeogClient().post(...)`.

## Persistência e refresh

- Tokens são persistidos em `localStorage` na chave configurável (default: `neog_auth`).
- Em caso de `401`, o cliente tenta refresh com `tokenRefreshEndpoint`.
- Se a API não fornecer refresh token, um `401` exige novo login.

## Segurança

O uso de `clientSecret` no frontend expõe o segredo no bundle. Esta configuração deve ser usada apenas em ambientes controlados e/ou temporariamente, até a adoção de um fluxo mais seguro (ex: BFF ou PKCE).

## Desenvolvimento

```bash
npm run build
npm test
```