@neog-cloud/neog-api-client 0.1.2

package/README.md

@@ -0,0 +1,129 @@
+# 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
+```

package/dist/auth/AuthProvider.d.ts

@@ -0,0 +1,14 @@
+import React from "react";
+import { AuthContextType, AuthState } from "./types";
+import { NeogAuthOptions } from "./options";
+export type AuthProviderFactory = {
+    AuthProvider: React.FC<{
+        children: React.ReactNode;
+    }>;
+    useAuth: () => AuthContextType;
+    getToken: () => string | null;
+    setToken: (token: string | null, refreshToken?: string | null, user?: AuthState["user"]) => void;
+    logout: () => void;
+    refreshAccessToken: () => Promise<string | null>;
+};
+export declare const createAuthProvider: (options: NeogAuthOptions) => AuthProviderFactory;

package/dist/auth/options.d.ts

@@ -0,0 +1,27 @@
+export type NeogAuthOptions = {
+    baseUrl: string;
+    authBaseUrl?: string;
+    authRealm?: string;
+    authEndpoint: string;
+    authRequestFormat?: "json" | "form";
+    authGrantType?: string;
+    authScope?: string;
+    clientId: string;
+    clientSecret?: string;
+    storageKey?: string;
+    tokenRefreshEndpoint?: string;
+    requestTimeoutMs?: number;
+    onRequestLog?: (info: {
+        url: string;
+        method: string;
+    }) => void;
+    onResponseLog?: (info: {
+        url: string;
+        status: number;
+    }) => void;
+    onErrorLog?: (info: {
+        url: string;
+        status?: number;
+        message: string;
+    }) => void;
+};

package/dist/auth/storage.d.ts

@@ -0,0 +1,13 @@
+export interface StoredAuthState {
+    accessToken: string | null;
+    refreshToken?: string | null;
+    expiresAt?: number | null;
+    user?: {
+        id: string;
+        name?: string;
+        email?: string;
+    } | null;
+}
+export declare const saveAuthState: (storageKey: string, state: StoredAuthState) => void;
+export declare const loadAuthState: (storageKey: string) => StoredAuthState | null;
+export declare const clearAuthState: (storageKey: string) => void;

package/dist/auth/types.d.ts

@@ -0,0 +1,37 @@
+export interface AuthContextType {
+    token: string | null;
+    refreshToken?: string | null;
+    user?: {
+        id: string;
+        name?: string;
+        email?: string;
+    } | null;
+    isAuthenticated: boolean;
+    loading: boolean;
+    error?: string | null;
+    login: (username: string, password: string) => Promise<void>;
+    logout: () => void;
+    getToken: () => string | null;
+    setToken?: (token: string, refreshToken?: string) => void;
+}
+export type AuthState = {
+    token: string | null;
+    refreshToken?: string | null;
+    user?: {
+        id: string;
+        name?: string;
+        email?: string;
+    } | null;
+    isAuthenticated: boolean;
+};
+export type TokenResponse = {
+    access_token: string;
+    refresh_token?: string;
+    expires_in?: number;
+    expires_at?: number;
+    user?: {
+        id: string;
+        name?: string;
+        email?: string;
+    } | null;
+};

package/dist/auth/useAuth.d.ts

@@ -0,0 +1,2 @@
+import { AuthContextType } from "./types";
+export type UseAuthHook = () => AuthContextType;

package/dist/client/neogClient.d.ts

@@ -0,0 +1,29 @@
+import { AxiosInstance } from "axios";
+import { ClientOptions, NeogClient } from "./types";
+export type RefreshTokenHandler = () => Promise<string | null>;
+export type GetTokenHandler = () => string | null;
+export type LogoutHandler = () => void;
+export type CreateClientDeps = {
+    baseUrl: string;
+    getToken: GetTokenHandler;
+    refreshToken: RefreshTokenHandler;
+    logout: LogoutHandler;
+    requestTimeoutMs?: number;
+    defaultHeaders?: Record<string, string>;
+    onRequestLog?: (info: {
+        url: string;
+        method: string;
+    }) => void;
+    onResponseLog?: (info: {
+        url: string;
+        status: number;
+    }) => void;
+    onErrorLog?: (info: {
+        url: string;
+        status?: number;
+        message: string;
+    }) => void;
+};
+export declare const createNeogClient: (deps: CreateClientDeps, opts?: ClientOptions) => NeogClient & {
+    __axios?: AxiosInstance;
+};

package/dist/client/types.d.ts

@@ -0,0 +1,40 @@
+export interface Response<T> {
+    status: "success" | "error" | "valid" | "unchecked" | "warning";
+    message?: string;
+    tecnicalMessage?: string;
+    count: number;
+    page: number;
+    version: string;
+    objects: T[];
+}
+export type Operator = ">" | "<" | "=" | ">=" | "<=" | "like" | "is null" | "is not null" | "" | "in" | "eq" | "ne" | "gt" | "ge" | "lt" | "le" | "notLike" | "notIn" | "isNull" | "isNotNull" | "between" | "notBetween";
+export interface FilterField {
+    column: string;
+    type?: string;
+    value?: any;
+    operator: Operator;
+    caption?: string;
+}
+export interface OrderField {
+    column: string;
+    direction: "asc" | "desc";
+}
+export interface Request<T> {
+    compRefid?: string;
+    branchRefid?: string;
+    version: string;
+    message?: string;
+    objects?: T[];
+    filters?: FilterField[];
+    orderBy?: OrderField[];
+    params?: FilterField[];
+}
+export type ClientOptions = {
+    timeoutMs?: number;
+    headers?: Record<string, string>;
+};
+export interface NeogClient {
+    post<TRequest, TResponse>(methodPath: string, body: Request<TRequest>): Promise<Response<TResponse>>;
+    setAuthHeader(token: string | null): void;
+    get<TResponse>(path: string, params?: any): Promise<TResponse>;
+}