@seedgrid/fe-audit 2026.7.0

package/README.md

@@ -0,0 +1,71 @@
+# @seedgrid/fe-audit
+
+[![npm version](https://img.shields.io/npm/v/%40seedgrid%2Ffe-audit)](https://www.npmjs.com/package/@seedgrid/fe-audit)
+[![npm downloads](https://img.shields.io/npm/dm/%40seedgrid%2Ffe-audit)](https://www.npmjs.com/package/@seedgrid/fe-audit)
+[![TypeScript](https://img.shields.io/badge/types-TypeScript-blue)](https://www.typescriptlang.org/)
+
+Módulo front de **auditoria** do SeedGrid: consulta do trilho de auditoria (audit log) com filtros ricos e detalhe com estado antes/depois para diff. Compõe sobre o motor de sessão do [`@seedgrid/fe-security`](https://www.npmjs.com/package/@seedgrid/fe-security).
+
+## Sumário
+
+- [Funcionalidades](#funcionalidades)
+- [Tela de busca](#tela-de-busca)
+- [Instalação](#instalação)
+- [Uso rápido](#uso-rápido)
+- [Backend correspondente](#backend-correspondente)
+- [Suporte](#suporte)
+
+## Funcionalidades
+
+- **Listagem paginada de logs** com filtros: entidade, operação (`CREATE`/`UPDATE`/`DELETE`/`READ`/`OTHER`), usuário, faixa de datas, faixa de ids, descrição e metadados (`metaKey`/`metaValue`).
+- **Combos de filtro dinâmicos** — endpoints de entidades distintas e usuários distintos alimentam os selects da tela.
+- **Detalhe do registro** — cada `AuditLogEntry` traz `beforeState`/`afterState` (JSON serializado) para renderizar o diff da alteração, além de origem, IP, user-agent e operação técnica.
+
+O pacote exporta:
+
+- `AuditPaths` — contrato dos endpoints REST (`/audit-logs`, `/audit-logs/entities`, `/audit-logs/users`, `/audit-logs/{id}`).
+- DTOs client-safe: `AuditLogEntry`, `AuditLogFilters`, `AuditLogEntityOption`, `AuditLogUserOption`, `AuditOperation`.
+- `createAuditServer` (em `@seedgrid/fe-audit/server`, SERVER-ONLY) — engine tipado de consulta sobre a sessão do fe-security.
+
+## Tela de busca
+
+A tela de busca de auditoria é **scaffold** (o app é dono do código) e é entregue pelo SeedGrid CLI ao adicionar o módulo (`module.json`: `id: "audit"`, `requires: ["security"]`): grid paginado com os filtros acima e painel de detalhe com o diff antes/depois.
+
+## Instalação
+
+```bash
+pnpm add @seedgrid/fe-audit @seedgrid/fe-security @seedgrid/fe-core
+```
+
+## Uso rápido
+
+```ts
+// server-only — compõe sobre a sessão do fe-security
+import { createSecurityServer } from "@seedgrid/fe-security/server";
+import { createAuditServer } from "@seedgrid/fe-audit/server";
+
+const session = createSecurityServer({ /* ... */ });
+export const audit = createAuditServer(session);
+
+// Em uma rota/action:
+const page = await audit.searchLogs({
+  entity: "User",
+  operation: "UPDATE",
+  operationDateFrom: "2026-07-01",
+  page: 0,
+  size: 20,
+});
+```
+
+## Backend correspondente
+
+Audit Log Controller do `seedgrid-report-api` (motor de auditoria da lib `seedgrid-quarkus-lib-audit`). `AuditPaths` é o contrato único front/back.
+
+## Suporte
+
+- Issues: https://github.com/SeedGrid/seedgrid-fe-components/issues
+- Repositório: https://github.com/SeedGrid/seedgrid-fe-components
+
+## Licença
+
+MIT

package/dist/audit.d.ts

@@ -0,0 +1,48 @@
+/** Operações auditadas (AuditOperationEnum). */
+export type AuditOperation = "CREATE" | "UPDATE" | "DELETE" | "READ" | "OTHER";
+/** Registro de auditoria (schema AuditLog). */
+export interface AuditLogEntry {
+    id: number;
+    entity: string;
+    /** AuditOperationEnum; `string` tolera valores futuros. */
+    operation: AuditOperation | string;
+    description: string | null;
+    techOperation: string | null;
+    origin: string | null;
+    ipAddress: string | null;
+    userAgent: string | null;
+    /** LocalDateTime ISO. */
+    operationDateTime: string;
+    userName: string | null;
+    /** Estado antes/depois (JSON serializado, pra o diff na tela de detalhe). */
+    beforeState: string | null;
+    afterState: string | null;
+    metadata?: Record<string, string>;
+}
+/** Filtros do GET /audit-logs (+ page/size quando paginado). */
+export interface AuditLogFilters {
+    description?: string;
+    entity?: string;
+    idFrom?: number;
+    idTo?: number;
+    metaKey?: string;
+    metaValue?: string;
+    operation?: AuditOperation | string;
+    /** LocalDate "yyyy-MM-dd". */
+    operationDateFrom?: string;
+    operationDateTo?: string;
+    userName?: string;
+    page?: number;
+    size?: number;
+}
+/** Opção de entidade pro combo de filtro (GET /audit-logs/entities). */
+export interface AuditLogEntityOption {
+    id: number;
+    entity: string;
+}
+/** Opção de usuário pro combo de filtro (GET /audit-logs/users). */
+export interface AuditLogUserOption {
+    id: number;
+    userName: string;
+}
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAEA,gDAAgD;AAChD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAE/E,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,SAAS,EAAE,cAAc,GAAG,MAAM,CAAC;IACnC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,yBAAyB;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC;IACpC,8BAA8B;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wEAAwE;AACxE,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,oEAAoE;AACpE,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;CAClB"}

package/dist/audit.js

@@ -0,0 +1,2 @@
+// DTOs de audit (espelham o Audit Log Controller do report-api). Client-safe.
+export {};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./audit";
+export * from "./paths";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+// Barrel client-safe (@seedgrid/fe-audit). Tipos + paths. Server helper em /server.
+// A tela de busca de audit é SCAFFOLD (app owns), entregue pelo CLI — não é da lib.
+export * from "./audit";
+export * from "./paths";

package/dist/module.d.ts

@@ -0,0 +1,3 @@
+import type { SeedGridCliModuleManifest } from "@seedgrid/fe-core";
+export declare const module: SeedGridCliModuleManifest;
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAanE,eAAO,MAAM,MAAM,EAAE,yBAIpB,CAAC"}

package/dist/module.js

@@ -0,0 +1,16 @@
+// Reference-adjacent implementation of the manifest read by the SeedGrid CLI
+// (Rust). See seedgrid-cli/docs/adr/0004-module-manifest-contract.md.
+//
+// No `scaffold/` yet: the CLI's old template for this module
+// (templates/modules/audit/src/modules/audit/index.ts.hbs) was a 6-line
+// stub (`export const auditModule = { name, description }`) — no real
+// screens were ever built for audit in the CLI, so there is nothing
+// meaningful to extract. This package already has real logic (DTOs, paths,
+// server engine); the audit list/detail screens themselves are a genuine
+// gap (see the "example apps program" note tracked separately), not
+// something lost in this extraction.
+export const module = {
+    id: "audit",
+    requires: ["security"],
+    configKey: "audit",
+};

package/dist/module.json

@@ -0,0 +1,7 @@
+{
+  "id": "audit",
+  "requires": [
+    "security"
+  ],
+  "configKey": "audit"
+}

package/dist/paths.d.ts

@@ -0,0 +1,11 @@
+export declare const AuditPaths: {
+    /** GET — lista/paginação de logs (aceita os filtros de AuditLogFilters via query). */
+    readonly logs: "/audit-logs";
+    /** GET — entidades distintas (combo de filtro). */
+    readonly entities: "/audit-logs/entities";
+    /** GET — usuários distintos (combo de filtro). */
+    readonly users: "/audit-logs/users";
+    /** GET — log por id. */
+    readonly byId: (id: number | string) => string;
+};
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,UAAU;IACrB,sFAAsF;;IAEtF,mDAAmD;;IAEnD,kDAAkD;;IAElD,wBAAwB;wBACb,MAAM,GAAG,MAAM;CAClB,CAAC"}

package/dist/paths.js

@@ -0,0 +1,12 @@
+// Paths do Audit Log Controller (report-api). Contrato único front/back.
+const seg = (value) => encodeURIComponent(value);
+export const AuditPaths = {
+    /** GET — lista/paginação de logs (aceita os filtros de AuditLogFilters via query). */
+    logs: "/audit-logs",
+    /** GET — entidades distintas (combo de filtro). */
+    entities: "/audit-logs/entities",
+    /** GET — usuários distintos (combo de filtro). */
+    users: "/audit-logs/users",
+    /** GET — log por id. */
+    byId: (id) => `/audit-logs/${seg(String(id))}`,
+};

package/dist/server/create-audit-server.d.ts

@@ -0,0 +1,14 @@
+import type { PaginatedResult, SecurityServer } from "@seedgrid/fe-security";
+import type { AuditLogEntry, AuditLogEntityOption, AuditLogFilters, AuditLogUserOption } from "../audit";
+export interface AuditServer {
+    /** Busca paginada de logs (passe page/size). Filtros viram query string. */
+    searchLogs(filters?: AuditLogFilters): Promise<PaginatedResult<AuditLogEntry>>;
+    /** Entidades distintas pro combo de filtro. */
+    listEntities(): Promise<AuditLogEntityOption[]>;
+    /** Usuários distintos pro combo de filtro. */
+    listUsers(): Promise<AuditLogUserOption[]>;
+    /** Log por id (detalhe before/after). */
+    getById(id: number | string): Promise<AuditLogEntry>;
+}
+export declare function createAuditServer(session: SecurityServer): AuditServer;
+//# sourceMappingURL=create-audit-server.d.ts.map

package/dist/server/create-audit-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-audit-server.d.ts","sourceRoot":"","sources":["../../src/server/create-audit-server.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG7E,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EACnB,MAAM,UAAU,CAAC;AAalB,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,UAAU,CACR,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAAC;IAC3C,+CAA+C;IAC/C,YAAY,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAAC;IAChD,8CAA8C;IAC9C,SAAS,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAC3C,yCAAyC;IACzC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACtD;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,cAAc,GAAG,WAAW,CAatE"}

package/dist/server/create-audit-server.js

@@ -0,0 +1,24 @@
+// Helpers server-side de audit, sobre o motor de sessão do fe-security. SERVER-ONLY
+// (roda em action/route). Só leitura — audit não muta nada.
+//
+//   const session = createSecurityServer({ ... });
+//   export const audit = createAuditServer(session);
+import { AuditPaths } from "../paths";
+function buildQuery(filters) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(filters)) {
+        if (value !== undefined && value !== null && value !== "") {
+            params.set(key, String(value));
+        }
+    }
+    const qs = params.toString();
+    return qs ? `?${qs}` : "";
+}
+export function createAuditServer(session) {
+    return {
+        searchLogs: (filters = {}) => session.apiFetchSecurity(`${AuditPaths.logs}${buildQuery(filters)}`),
+        listEntities: () => session.apiFetchSecurity(AuditPaths.entities),
+        listUsers: () => session.apiFetchSecurity(AuditPaths.users),
+        getById: (id) => session.apiFetchSecurity(AuditPaths.byId(id)),
+    };
+}

package/dist/server/index.d.ts

@@ -0,0 +1,2 @@
+export { createAuditServer, type AuditServer, } from "./create-audit-server";
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,GACjB,MAAM,uBAAuB,CAAC"}

package/dist/server/index.js

@@ -0,0 +1,2 @@
+// Barrel SERVER (@seedgrid/fe-audit/server). Roda em action/route.
+export { createAuditServer, } from "./create-audit-server";

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@seedgrid/fe-audit",
+  "version": "2026.7.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SeedGrid/seedgrid-fe-components.git"
+  },
+  "homepage": "https://github.com/SeedGrid/seedgrid-fe-components",
+  "bugs": {
+    "url": "https://github.com/SeedGrid/seedgrid-fe-components/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@seedgrid/fe-core": "*",
+    "@seedgrid/fe-security": "*"
+  },
+  "devDependencies": {
+    "@seedgrid/fe-core": "2026.7.1",
+    "@seedgrid/fe-security": "2026.7.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "postbuild": "node scripts/emit-module-manifest.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && node --test tests/module-manifest.test.mjs"
+  }
+}