@carlonicora/nextjs-jsonapi 6.6.0 → 6.8.0

package/messages/it.json

@@ -1,4 +1,28 @@
 {
+  "accountDeletion": {
+    "admin": {
+      "body": "L'account sarà eliminato il {date}. L'utente riceve un'email con un link per mantenerlo, e anche accedere lo mantiene.",
+      "bodyNoEmail": "L'account sarà eliminato il {date}. Non abbiamo un indirizzo email per questo utente, quindi solo accedendo potrà mantenerlo.",
+      "confirm": "Elimina account",
+      "confirmLabel": "Scrivi {value} per confermare",
+      "confirmWord": "ELIMINA",
+      "pending": "Eliminazione prevista il {date}",
+      "subscription": "L'abbonamento viene annullato oggi, senza rimborso.",
+      "title": "Eliminare questo account?",
+      "trigger": "Elimina account"
+    },
+    "cancelled": {
+      "body": "Il tuo abbonamento è stato annullato quando lo hai chiesto.",
+      "choosePlan": "Scegli un piano",
+      "title": "Bentornato. Il tuo account non sarà eliminato."
+    },
+    "keep": {
+      "failure": "Questo link non funziona più. Se il tuo account esiste ancora, accedi per mantenerlo.",
+      "login": "Accedi",
+      "successBody": "Non lo elimineremo. L'abbonamento resta annullato: scegli di nuovo un piano da Fatturazione quando accedi.",
+      "successTitle": "Il tuo account è al sicuro"
+    }
+  },
   "administration": {
     "ai_connections": {
       "description": "Provider AI, modelli e catene di fallback"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "6.6.0",
+  "version": "6.8.0",
   "description": "Next.js JSON:API client with server/client support and caching",
   "author": "Carlo Nicora",
   "license": "GPL-3.0-or-later",

package/src/components/index.ts

@@ -20,6 +20,7 @@ export * from "./hero";
 export { parseFiscalData } from "../utils/fiscal-utils";
 
 // Feature components
+export * from "../features/account-deletion/components";
 export * from "../features/auth/components";
 export * from "../features/administration";
 export * from "../features/ai-connection";

package/src/core/index.ts

@@ -30,6 +30,11 @@ export * from "../utils";
 export * from "../permissions";
 
 // Feature data classes, interfaces, and modules
+// Account deletion (opt-in): data, module and the login-notice flag helpers.
+// Server-safe; the client components ship from the components entry.
+export * from "../features/account-deletion/account-deletion.module";
+export * from "../features/account-deletion/data";
+export * from "../features/account-deletion/utils";
 export * from "../features/auth/auth.module";
 export * from "../features/auth/totp-authenticator.module";
 export * from "../features/auth/totp-setup.module";

package/src/core/registry/ModuleRegistry.ts

@@ -96,6 +96,8 @@ export interface FoundationModuleDefinitions {
   AnalyticsBreakdown: ModuleWithPermissions;
   AnalyticsSession: ModuleWithPermissions;
   AnalyticsPageView: ModuleWithPermissions;
+  // Account deletion (opt-in: registered only by apps that enable it)
+  AccountDeletion: ModuleWithPermissions;
 }
 
 // App-specific modules - apps will augment this interface ONLY
@@ -150,6 +152,17 @@ class ModuleRegistryClass {
     return module as ModuleDefinitions[K];
   }
 
+  /**
+   * True when a module is registered under `name`. Never throws, so a component
+   * can check for an opt-in module the app may not have registered.
+   */
+  has(name: string): boolean {
+    // Bootstrap only an empty registry (as findByName does): an app that never
+    // registers `name` must not re-run its bootstrapper on every check.
+    if (this._modules.size === 0) tryBootstrap();
+    return this._modules.has(name);
+  }
+
   findByName(moduleName: string): ModuleWithPermissions {
     // Self-healing: try bootstrap if registry is empty
     if (this._modules.size === 0) {

package/src/features/account-deletion/account-deletion.module.ts

@@ -0,0 +1,13 @@
+import { ModuleFactory } from "../../permissions";
+import { AccountDeletion } from "./data/account-deletion";
+
+/**
+ * Opt-in: an app that turns on `accountDeletion` in its API adds
+ * `AccountDeletion: AccountDeletionModule(moduleFactory)` to its bootstrapper.
+ */
+export const AccountDeletionModule = (factory: ModuleFactory) =>
+  factory({
+    name: "account-deletions",
+    pageUrl: "/account-deletions",
+    model: AccountDeletion,
+  });

package/src/features/account-deletion/components/AccountDeletionAdminTrigger.tsx

@@ -0,0 +1,183 @@
+"use client";
+
+import { LoaderCircleIcon, UserXIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useEffect, useState } from "react";
+import { errorToast } from "../../../components/errors/errorToast";
+import { ModuleRegistry } from "../../../core/registry/ModuleRegistry";
+import { useI18nLocale } from "../../../i18n";
+import { getRoleId } from "../../../roles";
+import {
+  AlertDialog,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from "../../../shadcnui/ui/alert-dialog";
+import { Button } from "../../../shadcnui/ui/button";
+import { Input } from "../../../shadcnui/ui/input";
+import { Label } from "../../../shadcnui/ui/label";
+import { useCurrentUserContext } from "../../user/contexts/CurrentUserContext";
+import { UserInterface } from "../../user/data/user.interface";
+import { AccountDeletionInterface } from "../data/account-deletion.interface";
+import { AccountDeletionService } from "../data/account-deletion.service";
+
+/** Must match the API's default `accountDeletion.graceDays`. */
+const GRACE_DAYS = 7;
+
+/** The words an undeliverable-email user (or an admin on their behalf) types. Same rule as the API. */
+const CONFIRMATION_WORDS = ["DELETE", "ELIMINA"];
+
+export type AccountDeletionAdminTriggerProps = {
+  user: UserInterface;
+};
+
+/**
+ * True when the app registered AccountDeletionModule (the feature is opt-in).
+ */
+export function isAccountDeletionEnabled(): boolean {
+  return ModuleRegistry.has("AccountDeletion");
+}
+
+function matchesConfirmation(status: AccountDeletionInterface, email: string, value: string): boolean {
+  if (status.hasDeliverableEmail) return value.trim().toLowerCase() === email.trim().toLowerCase();
+  return CONFIRMATION_WORDS.includes(value.trim().toUpperCase());
+}
+
+function AccountDeletionAdminTriggerInternal({ user }: AccountDeletionAdminTriggerProps) {
+  const t = useTranslations();
+  const locale = useI18nLocale();
+  const [status, setStatus] = useState<AccountDeletionInterface | undefined>();
+  const [open, setOpen] = useState<boolean>(false);
+  const [confirmation, setConfirmation] = useState<string>("");
+  const [isRequesting, setIsRequesting] = useState<boolean>(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    AccountDeletionService.findByUser({ userId: user.id })
+      .then((response) => {
+        if (!cancelled) setStatus(response);
+      })
+      .catch(() => {
+        if (!cancelled) setStatus(undefined);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [user.id]);
+
+  if (!status) return null;
+
+  const formatDate = (date: Date) =>
+    date.toLocaleDateString(locale, { day: "numeric", month: "long", year: "numeric" });
+
+  if (status.scheduledAt) {
+    return (
+      <span className="text-destructive text-xs font-medium">
+        {t("accountDeletion.admin.pending", { date: formatDate(status.scheduledAt) })}
+      </span>
+    );
+  }
+
+  const deletionDate = new Date();
+  deletionDate.setDate(deletionDate.getDate() + GRACE_DAYS);
+
+  const expected = status.hasDeliverableEmail ? user.email : t("accountDeletion.admin.confirmWord");
+  const canConfirm = matchesConfirmation(status, user.email, confirmation);
+
+  const handleOpenChange = (value: boolean) => {
+    setOpen(value);
+    if (!value) setConfirmation("");
+  };
+
+  const handleRequest = async () => {
+    setIsRequesting(true);
+    try {
+      const response = await AccountDeletionService.requestForUser({ id: user.id, confirmation });
+      if (response) setStatus(response);
+      handleOpenChange(false);
+    } catch (error) {
+      errorToast({ title: t("common.errors.error"), error });
+    } finally {
+      setIsRequesting(false);
+    }
+  };
+
+  return (
+    <AlertDialog open={open} onOpenChange={handleOpenChange}>
+      <AlertDialogTrigger
+        render={
+          <Button
+            size="sm"
+            variant="ghost"
+            className="text-muted-foreground hover:text-destructive"
+            aria-label={t("accountDeletion.admin.trigger")}
+            title={t("accountDeletion.admin.trigger")}
+          />
+        }
+      >
+        <UserXIcon />
+      </AlertDialogTrigger>
+      <AlertDialogContent className="flex max-h-[70vh] max-w-3xl flex-col overflow-y-auto">
+        <AlertDialogHeader>
+          <AlertDialogTitle>{t("accountDeletion.admin.title")}</AlertDialogTitle>
+          <AlertDialogDescription>
+            {status.hasDeliverableEmail
+              ? t("accountDeletion.admin.body", { date: formatDate(deletionDate) })
+              : t("accountDeletion.admin.bodyNoEmail", { date: formatDate(deletionDate) })}
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        {status.hasActiveSubscription && (
+          <p className="text-destructive text-sm">{t("accountDeletion.admin.subscription")}</p>
+        )}
+        <div className="flex w-full flex-col gap-y-2">
+          <Label htmlFor="account-deletion-admin-confirmation">
+            {t("accountDeletion.admin.confirmLabel", { value: expected })}
+          </Label>
+          <Input
+            id="account-deletion-admin-confirmation"
+            className="w-full"
+            autoComplete="off"
+            value={confirmation}
+            onChange={(e) => setConfirmation(e.target.value)}
+          />
+        </div>
+        <div className="flex justify-end">
+          <Button
+            className="me-2"
+            variant="outline"
+            type="button"
+            onClick={() => handleOpenChange(false)}
+            disabled={isRequesting}
+          >
+            {t("ui.buttons.cancel")}
+          </Button>
+          <Button type="button" variant="destructive" onClick={handleRequest} disabled={!canConfirm || isRequesting}>
+            {isRequesting ? (
+              <>
+                {t("ui.buttons.deleting")}
+                <LoaderCircleIcon className="animate-spin-slow h-5 w-5" />
+              </>
+            ) : (
+              t("accountDeletion.admin.confirm")
+            )}
+          </Button>
+        </div>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}
+
+/**
+ * Header action on the user detail page: starts the same 7-day deletion request
+ * the user can make, on their behalf. Platform administrators only, and only in
+ * apps that registered AccountDeletionModule.
+ */
+export function AccountDeletionAdminTrigger({ user }: AccountDeletionAdminTriggerProps) {
+  const { hasRole } = useCurrentUserContext<UserInterface>();
+
+  if (!hasRole(getRoleId().Administrator) || !isAccountDeletionEnabled()) return null;
+
+  return <AccountDeletionAdminTriggerInternal user={user} />;
+}

package/src/features/account-deletion/components/AccountDeletionCancelledNotice.tsx

@@ -0,0 +1,51 @@
+"use client";
+
+import { XIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useEffect, useState } from "react";
+import { Link } from "../../../shadcnui/custom/link";
+import { Alert, AlertAction, AlertDescription, AlertTitle } from "../../../shadcnui/ui/alert";
+import { Button } from "../../../shadcnui/ui/button";
+import { consumeAccountDeletionCancelled } from "../utils/account-deletion-notice";
+
+export type AccountDeletionCancelledNoticeProps = {
+  /** Where the user picks a plan again (their subscription was cancelled with the request). */
+  choosePlanHref: string;
+};
+
+/**
+ * Shown once, on the first page after a login that cancelled a pending account
+ * deletion. The login paths set the flag; this reads and clears it.
+ */
+export function AccountDeletionCancelledNotice({ choosePlanHref }: AccountDeletionCancelledNoticeProps) {
+  const t = useTranslations();
+  const [visible, setVisible] = useState(false);
+
+  // Read in an effect, never during render: sessionStorage is client-only and
+  // the flag is consumed (a render-time read would differ between server and client).
+  useEffect(() => {
+    if (consumeAccountDeletionCancelled()) setVisible(true);
+  }, []);
+
+  if (!visible) return null;
+
+  return (
+    <Alert className="border-success/30 bg-success/15 mb-4">
+      <AlertTitle className="text-success">{t("accountDeletion.cancelled.title")}</AlertTitle>
+      <AlertDescription>
+        <p>{t("accountDeletion.cancelled.body")}</p>
+        {/* Never underlined: colour and weight carry the affordance. */}
+        <div className="mt-1">
+          <Link href={choosePlanHref} className="text-primary font-medium">
+            {t("accountDeletion.cancelled.choosePlan")}
+          </Link>
+        </div>
+      </AlertDescription>
+      <AlertAction>
+        <Button variant="ghost" size="icon-xs" aria-label={t("ui.labels.close")} onClick={() => setVisible(false)}>
+          <XIcon />
+        </Button>
+      </AlertAction>
+    </Alert>
+  );
+}

package/src/features/account-deletion/components/AccountDeletionKeepContainer.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+import { CheckCircle, Loader2, XCircle } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useEffect, useRef, useState } from "react";
+import { SectionHeader } from "../../../components/typography";
+import { buttonVariants } from "../../../shadcnui/ui/button";
+import { Link } from "../../../shadcnui/custom/link";
+import { AccountDeletionService } from "../data/account-deletion.service";
+
+export type AccountDeletionKeepContainerProps = {
+  /** The raw token from the "Keep my account" email link. */
+  token: string | undefined;
+};
+
+type KeepState = "loading" | "success" | "failure";
+
+/**
+ * Landing page of the "Keep my account" email link: cancels the pending
+ * deletion without a login. Every failure shows the same text, so the page
+ * never tells whether an account exists.
+ */
+export function AccountDeletionKeepContainer({ token }: AccountDeletionKeepContainerProps) {
+  const t = useTranslations();
+  const [state, setState] = useState<KeepState>(token ? "loading" : "failure");
+  // The token is single use: a second call (React Strict Mode runs effects
+  // twice in development) would fail and replace the success text.
+  const called = useRef(false);
+
+  useEffect(() => {
+    if (!token || called.current) return;
+    called.current = true;
+
+    AccountDeletionService.keep({ token })
+      .then(() => setState("success"))
+      .catch(() => setState("failure"));
+  }, [token]);
+
+  if (state === "loading") {
+    return (
+      <div className="flex flex-col items-center justify-center space-y-4 py-16 text-center">
+        <Loader2 className="text-primary h-12 w-12 animate-spin" />
+        <p className="text-muted-foreground">{t("ui.buttons.loading")}</p>
+      </div>
+    );
+  }
+
+  if (state === "failure") {
+    return (
+      <div className="flex flex-col items-center justify-center space-y-4 py-16 text-center">
+        <div className="bg-destructive/10 rounded-full p-4">
+          <XCircle className="text-destructive h-12 w-12" />
+        </div>
+        <p className="text-muted-foreground max-w-md">{t("accountDeletion.keep.failure")}</p>
+        <Link href="/login" className={buttonVariants({ variant: "outline" })}>
+          {t("accountDeletion.keep.login")}
+        </Link>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex flex-col items-center justify-center space-y-4 py-16 text-center">
+      <div className="bg-success/15 rounded-full p-4">
+        <CheckCircle className="text-success h-12 w-12" />
+      </div>
+      <SectionHeader level={2}>{t("accountDeletion.keep.successTitle")}</SectionHeader>
+      <p className="text-muted-foreground max-w-md">{t("accountDeletion.keep.successBody")}</p>
+      <Link href="/login" className={buttonVariants()}>
+        {t("accountDeletion.keep.login")}
+      </Link>
+    </div>
+  );
+}

package/src/features/account-deletion/components/index.ts

@@ -0,0 +1,3 @@
+export * from "./AccountDeletionAdminTrigger";
+export * from "./AccountDeletionCancelledNotice";
+export * from "./AccountDeletionKeepContainer";

package/src/features/account-deletion/data/__tests__/AccountDeletion.spec.ts

@@ -0,0 +1,89 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { ApiRequestDataTypeInterface } from "../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { AccountDeletion } from "../account-deletion";
+
+// createJsonApi() resolves Modules.AccountDeletion through the real ModuleRegistry,
+// which is shared across test files in a worker: register only when absent.
+const registerIfAbsent = (key: string, module: ApiRequestDataTypeInterface) => {
+  try {
+    ModuleRegistry.get(key as any);
+  } catch {
+    ModuleRegistry.register(key, module);
+  }
+};
+
+beforeAll(() => {
+  registerIfAbsent("AccountDeletion", { name: "account-deletions", model: AccountDeletion } as any);
+});
+
+const USER_ID = "11111111-1111-4111-8111-111111111111";
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+describe("AccountDeletion", () => {
+  describe("rehydrate", () => {
+    it("parses scheduledAt and requestedAt into Date", () => {
+      const model = new AccountDeletion().rehydrate({
+        jsonApi: {
+          type: "account-deletions",
+          id: USER_ID,
+          attributes: {
+            requestedAt: "2026-10-25T10:00:00.000Z",
+            scheduledAt: "2026-11-01T10:00:00.000Z",
+            hasDeliverableEmail: true,
+            hasActiveSubscription: true,
+            deletesCompany: true,
+            ownedCount: 3,
+            otherTables: ["The Long Road"],
+          },
+        },
+        included: [],
+      } as any);
+
+      expect(model.requestedAt).toBeInstanceOf(Date);
+      expect(model.requestedAt?.toISOString()).toBe("2026-10-25T10:00:00.000Z");
+      expect(model.scheduledAt).toBeInstanceOf(Date);
+      expect(model.scheduledAt?.toISOString()).toBe("2026-11-01T10:00:00.000Z");
+      expect(model.hasDeliverableEmail).toBe(true);
+      expect(model.hasActiveSubscription).toBe(true);
+      expect(model.deletesCompany).toBe(true);
+      expect(model.ownedCount).toBe(3);
+      expect(model.otherTables).toEqual(["The Long Road"]);
+    });
+
+    it("leaves both dates undefined and defaults the rest when nothing is pending", () => {
+      const model = new AccountDeletion().rehydrate({
+        jsonApi: { type: "account-deletions", id: USER_ID, attributes: {} },
+        included: [],
+      } as any);
+
+      expect(model.requestedAt).toBeUndefined();
+      expect(model.scheduledAt).toBeUndefined();
+      expect(model.hasDeliverableEmail).toBe(false);
+      expect(model.hasActiveSubscription).toBe(false);
+      expect(model.deletesCompany).toBe(false);
+      expect(model.ownedCount).toBe(0);
+      expect(model.otherTables).toEqual([]);
+    });
+  });
+
+  describe("createJsonApi", () => {
+    it("type account-deletions, id, attributes.confirmation", () => {
+      const payload = new AccountDeletion().createJsonApi({ id: USER_ID, confirmation: "gm@example.com" });
+
+      expect(payload.data.type).toBe("account-deletions");
+      expect(payload.data.id).toBe(USER_ID);
+      expect(payload.data.attributes).toEqual({ confirmation: "gm@example.com" });
+    });
+  });
+
+  describe("createKeepJsonApi", () => {
+    it("type account-deletions, a v4 id, attributes.token", () => {
+      const payload = new AccountDeletion().createKeepJsonApi({ token: "raw-token" });
+
+      expect(payload.data.type).toBe("account-deletions");
+      expect(payload.data.id).toMatch(UUID_V4);
+      expect(payload.data.attributes).toEqual({ token: "raw-token" });
+    });
+  });
+});

package/src/features/account-deletion/data/account-deletion.interface.ts

@@ -0,0 +1,22 @@
+import { ApiDataInterface } from "../../../core";
+
+/**
+ * A user's account-deletion status and what the deletion removes. Not a stored
+ * entity: the API builds it for one user; its id is that user's id.
+ */
+export interface AccountDeletionInterface extends ApiDataInterface {
+  get requestedAt(): Date | undefined;
+  get scheduledAt(): Date | undefined;
+  get hasDeliverableEmail(): boolean;
+  get hasActiveSubscription(): boolean;
+  get deletesCompany(): boolean;
+  get ownedCount(): number;
+  get otherTables(): string[];
+}
+
+export type AccountDeletionInput = {
+  /** The id of the user whose account is deleted. */
+  id: string;
+  /** The user's email, or DELETE / ELIMINA when the user has no deliverable email. */
+  confirmation: string;
+};

package/src/features/account-deletion/data/account-deletion.service.ts

@@ -0,0 +1,69 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
+import { AccountDeletion } from "./account-deletion";
+import { AccountDeletionInput, AccountDeletionInterface } from "./account-deletion.interface";
+
+export class AccountDeletionService extends AbstractService {
+  /**
+   * GET the signed-in user's deletion status and what a deletion would remove.
+   */
+  static async findMine(): Promise<AccountDeletionInterface> {
+    return this.callApi<AccountDeletionInterface>({
+      type: Modules.AccountDeletion,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({ endpoint: Modules.AccountDeletion, id: "me" }).generate(),
+    });
+  }
+
+  /**
+   * GET another user's deletion status (platform administrators only).
+   */
+  static async findByUser(params: { userId: string }): Promise<AccountDeletionInterface> {
+    return this.callApi<AccountDeletionInterface>({
+      type: Modules.AccountDeletion,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({ endpoint: Modules.AccountDeletion, id: params.userId }).generate(),
+    });
+  }
+
+  /**
+   * POST the signed-in user's own deletion request. `params.id` must be the
+   * signed-in user's id.
+   */
+  static async request(params: AccountDeletionInput): Promise<AccountDeletionInterface> {
+    return this.callApi<AccountDeletionInterface>({
+      type: Modules.AccountDeletion,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: Modules.AccountDeletion }).generate(),
+      input: params,
+    });
+  }
+
+  /**
+   * POST a deletion request on behalf of another user (platform administrators
+   * only). Runs the same 7-day request as the user's own.
+   */
+  static async requestForUser(params: AccountDeletionInput): Promise<AccountDeletionInterface> {
+    return this.callApi<AccountDeletionInterface>({
+      type: Modules.AccountDeletion,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: Modules.AccountDeletion, id: params.id }).generate(),
+      input: params,
+    });
+  }
+
+  /**
+   * POST the token from the "Keep my account" email link. Public: no session.
+   * Throws on any failure, so the page can show the "link no longer works" text.
+   */
+  static async keep(params: { token: string }): Promise<void> {
+    const accountDeletion = new AccountDeletion();
+    await this.callApi<void>({
+      type: Modules.AccountDeletion,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: Modules.AccountDeletion, id: "keep" }).generate(),
+      input: accountDeletion.createKeepJsonApi({ token: params.token }),
+      overridesJsonApiCreation: true, // OK - model method provides proper structure
+      suppressGlobalError: true,
+    });
+  }
+}