@seedgrid/fe-backup 2026.7.0

package/scaffold/src/modules/backup/services/backup-api.ts

@@ -0,0 +1,205 @@
+// seedgrid:managed
+
+import {
+  ApiClientError,
+  createApiClient,
+  extractApiErrorMessage,
+  type ApiRequestOptions,
+} from "@/modules/core";
+import { getMessages, translate } from "@/i18n";
+
+import { backupConfig } from "../config";
+
+type AuthRuntime = {
+  getAccessToken: () => Promise<string | null>;
+  refreshAccessToken: () => Promise<string | null>;
+  onAuthFailure: () => void | Promise<void>;
+};
+
+const runtime: AuthRuntime = {
+  getAccessToken: async () => null,
+  refreshAccessToken: async () => null,
+  onAuthFailure: async () => {},
+};
+
+let pendingRefresh: Promise<string | null> | null = null;
+
+const privateClient = createApiClient({
+  baseUrl: backupConfig.apiBaseUrl,
+  getAccessToken: () => runtime.getAccessToken(),
+  refreshAccessToken: () => {
+    if (!pendingRefresh) {
+      pendingRefresh = runtime.refreshAccessToken().finally(() => {
+        pendingRefresh = null;
+      });
+    }
+    return pendingRefresh;
+  },
+  onAuthFailure: () => runtime.onAuthFailure(),
+});
+
+export function configureBackupApi(nextRuntime: Partial<AuthRuntime>) {
+  if (typeof nextRuntime.getAccessToken === "function") {
+    runtime.getAccessToken = nextRuntime.getAccessToken;
+  }
+
+  if (typeof nextRuntime.refreshAccessToken === "function") {
+    runtime.refreshAccessToken = nextRuntime.refreshAccessToken;
+  }
+
+  if (typeof nextRuntime.onAuthFailure === "function") {
+    runtime.onAuthFailure = nextRuntime.onAuthFailure;
+  }
+}
+
+export const backupApi = {
+  get: <T = unknown>(path: string, options?: ApiRequestOptions) =>
+    privateClient.get<T>(path, options),
+  post: <T = unknown>(path: string, options?: ApiRequestOptions) =>
+    privateClient.post<T>(path, options),
+  delete: <T = unknown>(path: string, options?: ApiRequestOptions) =>
+    privateClient.delete<T>(path, options),
+};
+
+export function isApiClientError(error: unknown): error is ApiClientError {
+  return error instanceof ApiClientError;
+}
+
+export function extractBackupApiMessage(error: unknown): string | null {
+  if (error instanceof ApiClientError) {
+    return normalizeReadableErrorMessage(
+      readApiMessage(error.responseBody) ?? extractApiErrorMessage(error)
+    );
+  }
+
+  return normalizeReadableErrorMessage(extractApiErrorMessage(error));
+}
+
+function readApiMessage(body: unknown): string | null {
+  const normalizedBody = normalizeApiBody(body);
+
+  if (!normalizedBody || typeof normalizedBody !== "object") {
+    return pickString(normalizedBody);
+  }
+
+  const record = normalizedBody as Record<string, unknown>;
+
+  if (Array.isArray(record.violations)) {
+    for (const entry of record.violations) {
+      const violationMessage = readRecordMessage(entry);
+
+      if (violationMessage) {
+        return violationMessage;
+      }
+    }
+  }
+
+  if (Array.isArray(record.errors)) {
+    for (const entry of record.errors) {
+      const nestedMessage = readRecordMessage(entry);
+
+      if (nestedMessage) {
+        return nestedMessage;
+      }
+    }
+  }
+
+  return (
+    pickString(record.userMessage) ??
+    pickString(record.detail) ??
+    pickString(record.message) ??
+    pickString(record.error) ??
+    pickString(record.title)
+  );
+}
+
+function normalizeApiBody(body: unknown) {
+  if (typeof body !== "string") {
+    return body;
+  }
+
+  const normalized = body.trim();
+
+  if (!normalized) {
+    return body;
+  }
+
+  try {
+    return JSON.parse(normalized) as unknown;
+  } catch {
+    return body;
+  }
+}
+
+function readRecordMessage(value: unknown) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+
+  const record = value as Record<string, unknown>;
+
+  return (
+    pickString(record.userMessage) ??
+    pickString(record.message) ??
+    pickString(record.error) ??
+    pickString(record.description)
+  );
+}
+
+function normalizeReadableErrorMessage(message: string | null) {
+  const normalized = pickString(message);
+
+  if (!normalized) {
+    return null;
+  }
+
+  if (isServerConnectionError(normalized)) {
+    return translate(
+      getMessages(resolveRuntimeLocale()),
+      "backup.common.server_connection_error"
+    );
+  }
+
+  if (isHtmlContent(normalized)) {
+    return null;
+  }
+
+  return normalized;
+}
+
+function isHtmlContent(message: string) {
+  const trimmed = message.trimStart();
+  return trimmed.startsWith("<!") || trimmed.startsWith("<html") || trimmed.startsWith("<HTML");
+}
+
+function isServerConnectionError(message: string) {
+  const normalized = message.trim().toLowerCase();
+  return (
+    normalized === "fetch failed" ||
+    normalized === "failed to fetch" ||
+    normalized.includes("networkerror") ||
+    normalized.includes("network request failed") ||
+    normalized.includes("load failed")
+  );
+}
+
+function resolveRuntimeLocale() {
+  if (typeof document !== "undefined") {
+    const documentLocale = document.documentElement.lang?.trim();
+    if (documentLocale) return documentLocale;
+  }
+
+  if (typeof navigator !== "undefined") {
+    const browserLocale =
+      navigator.language?.trim() || navigator.languages?.[0]?.trim();
+    if (browserLocale) return browserLocale;
+  }
+
+  return undefined;
+}
+
+function pickString(value: unknown) {
+  return typeof value === "string" && value.trim().length > 0
+    ? value.trim()
+    : null;
+}

package/scaffold/src/modules/backup/services/backup-service.test.ts

@@ -0,0 +1,125 @@
+// seedgrid:managed
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { backupApi } from "./backup-api";
+import { backupService } from "./backup-service";
+import type { ExportRequest, ExportResponse } from "../types";
+
+vi.mock("./backup-api", () => ({
+  backupApi: {
+    get: vi.fn(),
+    post: vi.fn(),
+    delete: vi.fn(),
+  },
+}));
+
+const mockGet = vi.mocked(backupApi.get);
+const mockPost = vi.mocked(backupApi.post);
+const mockDelete = vi.mocked(backupApi.delete);
+
+const makeExportResponse = (
+  overrides: Partial<ExportResponse> = {}
+): ExportResponse => ({
+  jobId: "job-abc-123",
+  status: "REQUESTED",
+  format: "CSV_ZIP",
+  scope: "DOMAIN",
+  progress: 0,
+  createdAt: "2024-01-15T10:30:00",
+  downloadable: false,
+  ...overrides,
+});
+
+describe("backupService.createExportJob", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("posts to /exports with the given request body", async () => {
+    const request: ExportRequest = {
+      format: "CSV_ZIP",
+      scope: "DOMAIN",
+      includeAttachments: false,
+    };
+    const expected = makeExportResponse({ status: "REQUESTED" });
+    mockPost.mockResolvedValueOnce(expected);
+
+    const result = await backupService.createExportJob(request);
+
+    expect(mockPost).toHaveBeenCalledWith("/exports", { body: request });
+    expect(result).toEqual(expected);
+  });
+
+  it("propagates API errors from createExportJob", async () => {
+    const request: ExportRequest = { format: "SQL_DUMP_ZIP", scope: "RAW" };
+    mockPost.mockRejectedValueOnce(new Error("Network error"));
+
+    await expect(backupService.createExportJob(request)).rejects.toThrow(
+      "Network error"
+    );
+  });
+});
+
+describe("backupService.listExportJobs", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("calls GET /exports with page and size query params", async () => {
+    const jobs = [makeExportResponse(), makeExportResponse({ jobId: "job-def-456" })];
+    mockGet.mockResolvedValueOnce(jobs);
+
+    const result = await backupService.listExportJobs({ page: 0, size: 10 });
+
+    expect(mockGet).toHaveBeenCalledWith("/exports?page=0&size=10");
+    expect(result).toHaveLength(2);
+  });
+
+  it("passes the correct page when paginating", async () => {
+    mockGet.mockResolvedValueOnce([]);
+
+    await backupService.listExportJobs({ page: 2, size: 20 });
+
+    expect(mockGet).toHaveBeenCalledWith("/exports?page=2&size=20");
+  });
+});
+
+describe("backupService.getExportStatus", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("fetches status for the given jobId", async () => {
+    const job = makeExportResponse({ status: "RUNNING", progress: 45 });
+    mockGet.mockResolvedValueOnce(job);
+
+    const result = await backupService.getExportStatus("job-abc-123");
+
+    expect(mockGet).toHaveBeenCalledWith("/exports/job-abc-123");
+    expect(result.status).toBe("RUNNING");
+    expect(result.progress).toBe(45);
+  });
+
+  it("URL-encodes the jobId when calling the API", async () => {
+    mockGet.mockResolvedValueOnce(makeExportResponse());
+
+    await backupService.getExportStatus("job/with/slashes");
+
+    expect(mockGet).toHaveBeenCalledWith("/exports/job%2Fwith%2Fslashes");
+  });
+});
+
+describe("backupService.deleteExportJob", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("calls DELETE for the given jobId", async () => {
+    mockDelete.mockResolvedValueOnce(undefined);
+
+    await backupService.deleteExportJob("job-abc-123");
+
+    expect(mockDelete).toHaveBeenCalledWith("/exports/job-abc-123");
+  });
+
+  it("propagates errors from the delete call", async () => {
+    mockDelete.mockRejectedValueOnce(new Error("Not found"));
+
+    await expect(backupService.deleteExportJob("missing-id")).rejects.toThrow(
+      "Not found"
+    );
+  });
+});

package/scaffold/src/modules/backup/services/backup-service.ts

@@ -0,0 +1,34 @@
+// seedgrid:managed
+
+import { backupApi } from "./backup-api";
+import type { ExportRequest, ExportResponse } from "../types";
+
+const EXPORTS_PATH = "/exports";
+
+export const backupService = {
+  async createExportJob(request: ExportRequest): Promise<ExportResponse> {
+    return backupApi.post<ExportResponse>(EXPORTS_PATH, {
+      body: request,
+    });
+  },
+
+  async listExportJobs(params: {
+    page: number;
+    size: number;
+  }): Promise<ExportResponse[]> {
+    const query = new URLSearchParams({
+      page: String(params.page),
+      size: String(params.size),
+    });
+
+    return backupApi.get<ExportResponse[]>(`${EXPORTS_PATH}?${query}`);
+  },
+
+  async getExportStatus(jobId: string): Promise<ExportResponse> {
+    return backupApi.get<ExportResponse>(`${EXPORTS_PATH}/${encodeURIComponent(jobId)}`);
+  },
+
+  async deleteExportJob(jobId: string): Promise<void> {
+    await backupApi.delete(`${EXPORTS_PATH}/${encodeURIComponent(jobId)}`);
+  },
+};

package/scaffold/src/modules/backup/types.ts

@@ -0,0 +1,17 @@
+// seedgrid:managed
+
+// Um agente anterior tinha redeclarado BackupFormat/ArtifactInfo aqui porque
+// divergiam do que existia em @seedgrid/fe-backup (BackupFormat tinha 8
+// valores fictícios; ArtifactInfo.id era string). Conferi contra o backend
+// real (seedgrid-quarkus-ext-backup/.../domains/BackupFormat.java,
+// dtos/ExportResponse.java) e corrigi @seedgrid/fe-backup pra bater com o
+// contrato de verdade (BackupFormat só tem CSV_ZIP/SQL_DUMP_ZIP; ArtifactInfo.id
+// é number). Com isso não há mais divergência — tudo reexportado da lib.
+export type {
+  ArtifactInfo,
+  BackupFormat,
+  ExportRequest,
+  ExportResponse,
+  ExportScope,
+  ExportStatus,
+} from "@seedgrid/fe-backup";

package/scaffold/src/modules/backup/useBackupAppShellSections.test.tsx

@@ -0,0 +1,61 @@
+// seedgrid:managed
+
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { useBackupAppShellSections } from "./useBackupAppShellSections";
+
+vi.mock("@/i18n", () => ({
+  useI18n: () => ({ t: (key: string) => key }),
+}));
+
+const mockUsePermission = vi.fn();
+
+vi.mock("@/modules/security", () => ({
+  usePermission: (permission: string) => mockUsePermission(permission),
+}));
+
+describe("useBackupAppShellSections", () => {
+  it("returns an empty array when the user has no JOB_READ permission", () => {
+    mockUsePermission.mockReturnValue(false);
+
+    const { result } = renderHook(() => useBackupAppShellSections());
+
+    expect(result.current).toEqual([]);
+  });
+
+  it("returns a backup section when the user has JOB_READ permission", () => {
+    mockUsePermission.mockImplementation((permission: string) =>
+      permission === "JOB_READ"
+    );
+
+    const { result } = renderHook(() => useBackupAppShellSections());
+
+    expect(result.current).toHaveLength(1);
+    expect(result.current[0].id).toBe("backup");
+  });
+
+  it("includes a backup-exports nav item inside the section", () => {
+    mockUsePermission.mockImplementation((permission: string) =>
+      permission === "JOB_READ"
+    );
+
+    const { result } = renderHook(() => useBackupAppShellSections());
+
+    const section = result.current[0];
+    const sectionItem = section.items[0];
+    const exportItem = sectionItem.children?.find(
+      (item) => item.id === "backup-exports"
+    );
+
+    expect(exportItem).toBeDefined();
+  });
+
+  it("passes the JOB_READ permission check to usePermission", () => {
+    mockUsePermission.mockReturnValue(false);
+
+    renderHook(() => useBackupAppShellSections());
+
+    expect(mockUsePermission).toHaveBeenCalledWith("JOB_READ");
+  });
+});

package/scaffold/src/modules/backup/useBackupAppShellSections.tsx

@@ -0,0 +1,50 @@
+"use client";
+
+import { Database } from "lucide-react";
+
+import type {
+  AppShellNavItem,
+  AppShellSection,
+} from "@/components/layout/app-shell-navigation";
+import { useI18n } from "@/i18n";
+import { usePermission } from "@/modules/security";
+
+import { backupConfig } from "./config";
+
+export function useBackupAppShellSections(): AppShellSection[] {
+  const { t } = useI18n();
+  const canReadJobs = usePermission("JOB_READ");
+
+  const items: AppShellNavItem[] = [];
+
+  if (canReadJobs) {
+    items.push({
+      id: "backup-exports",
+      label: t("backup.exports.list.title"),
+      href: backupConfig.routes.exports,
+      icon: <Database size={16} />,
+      order: 10,
+    });
+  }
+
+  if (!items.length) {
+    return [];
+  }
+
+  return [
+    {
+      id: "backup",
+      label: t("backup.common.module_name"),
+      order: 50,
+      items: [
+        {
+          id: "backup-management",
+          label: t("backup.common.module_name"),
+          icon: <Database size={18} />,
+          order: 10,
+          children: items,
+        },
+      ],
+    },
+  ];
+}