@carlonicora/nextjs-jsonapi 5.2.0 → 5.3.0

package/messages/it.json

@@ -736,6 +736,15 @@
       }
     }
   },
+  "canvas": {
+    "toolbar": {
+      "fitView": "Adatta alla vista",
+      "tidy": "Riordina",
+      "tidyTooltip": "Cancella le posizioni manuali e rifai il layout automatico",
+      "zoomIn": "Ingrandisci",
+      "zoomOut": "Riduci"
+    }
+  },
   "common": {
     "actions": {
       "submitting": "Invio in corso..."
@@ -906,6 +915,114 @@
     },
     "news": "Contenuti recenti pertinenti"
   },
+  "emailAutomations": {
+    "admin": {
+      "editAutomation": "Modifica automazione",
+      "empty": "Nessuna automazione email.",
+      "newAutomation": "Nuova automazione",
+      "title": "Automazioni email"
+    },
+    "canvas": {
+      "addEmail": "Aggiungi email",
+      "chainError": "Questo collegamento romperebbe la sequenza.",
+      "deleteEmail": "Elimina email",
+      "deleteEmailConfirm": "Eliminare questa email? La sequenza si richiude e chi la stava aspettando passa all'email successiva.",
+      "emptyBody": "Fai clic destro sul canvas o trascina dall'evento per aggiungere la prima.",
+      "emptyTitle": "Ancora nessuna email",
+      "hoursAfterEntering": "ore dopo l'ingresso nell'automazione",
+      "hoursAfterPrevious": "ore dopo l'email precedente",
+      "noTrigger": "Nessun evento",
+      "orphan": "fuori dalla sequenza",
+      "sent": "inviate {count}"
+    },
+    "fields": {
+      "exitTrigger": {
+        "label": "Evento di uscita"
+      },
+      "isActive": {
+        "help": "Spenta, tiene tutti fermi dove sono; le email in ritardo partono quando la riaccendi.",
+        "label": "Attiva"
+      },
+      "name": {
+        "error": "Il nome è obbligatorio",
+        "label": "Nome"
+      },
+      "replyTo": {
+        "error": "Inserisci un indirizzo email valido",
+        "label": "Rispondi a"
+      },
+      "trigger": {
+        "label": "Evento di ingresso",
+        "none": "— nessuno —"
+      }
+    },
+    "list": {
+      "columns": {
+        "active": "Attivi",
+        "completed": "Completati",
+        "name": "Nome",
+        "status": "Stato",
+        "steps": "Email",
+        "trigger": "Evento",
+        "unsubscribed": "Disiscritti"
+      },
+      "status": {
+        "off": "Spenta",
+        "on": "Attiva"
+      }
+    },
+    "recipients": {
+      "columns": {
+        "currentStep": "Prossima email",
+        "email": "Email",
+        "name": "Nome",
+        "nextSendAt": "In programma",
+        "sentCount": "Inviate",
+        "status": "Stato"
+      },
+      "empty": "Nessuno è ancora entrato in questa automazione.",
+      "status": {
+        "active": "Attivi",
+        "all": "Tutti",
+        "completed": "Completati",
+        "exited": "Usciti",
+        "failed": "Non riusciti",
+        "unsubscribed": "Disiscritti"
+      }
+    },
+    "step": {
+      "editTitle": "Modifica email",
+      "fields": {
+        "body": {
+          "error": "Il testo è obbligatorio",
+          "label": "Testo (Markdown)"
+        },
+        "delayHours": {
+          "label": "Attesa"
+        },
+        "subject": {
+          "error": "L'oggetto è obbligatorio",
+          "label": "Oggetto"
+        }
+      },
+      "title": "Nuova email",
+      "unsubscribeHint": "I link per disiscriversi vengono sempre aggiunti sotto il testo.",
+      "variablesHint": "Variabili:"
+    },
+    "tabs": {
+      "canvas": "Canvas",
+      "recipients": "Destinatari"
+    },
+    "unsubscribe": {
+      "alsoStopAll": "Interrompi anche tutte le email promozionali",
+      "invalidBody": "Questo link non è valido.",
+      "invalidTitle": "Link non valido",
+      "loading": "Aggiornamento delle tue preferenze email in corso...",
+      "stoppedAll": "Non riceverai più nessuna email promozionale da noi.",
+      "stoppedAutomation": "Non riceverai altre email da {name}.",
+      "title": "Disiscrizione completata"
+    }
+  },
   "entities": {
     "assistants": "{count, plural, =1 {Assistente} other {Assistenti}}",
     "companies": "{count, plural, =1 {Azienda} other {Aziende}}",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "Next.js JSON:API client with server/client support and caching",
   "author": "Carlo Nicora",
   "license": "GPL-3.0-or-later",
@@ -59,6 +59,11 @@
       "import": "./dist/billing/index.mjs",
       "require": "./dist/billing/index.js"
     },
+    "./email-automations": {
+      "types": "./dist/email-automations/index.d.ts",
+      "import": "./dist/email-automations/index.mjs",
+      "require": "./dist/email-automations/index.js"
+    },
     "./help": {
       "types": "./dist/features/help/index.d.ts",
       "import": "./dist/features/help/index.mjs",
@@ -118,6 +123,7 @@
     "@stripe/react-stripe-js": ">=6.8.0",
     "@stripe/stripe-js": ">=9.13.0",
     "@tanstack/react-table": ">=8.0.0",
+    "@xyflow/react": ">=12.0.0",
     "next": ">=16.4.0",
     "next-intl": ">=4.0.0",
     "react": ">=19.3.0",
@@ -134,6 +140,9 @@
     "@tanstack/react-table": {
       "optional": true
     },
+    "@xyflow/react": {
+      "optional": true
+    },
     "next-intl": {
       "optional": true
     },
@@ -220,6 +229,7 @@
     "@vitejs/plugin-react": "^6.1.2",
     "@vitest/coverage-v8": "^5.0.3",
     "@vitest/ui": "^5.0.3",
+    "@xyflow/react": "^12.12.0",
     "conventional-changelog-conventionalcommits": "9.3.1",
     "eslint": "^9.39.5",
     "eslint-config-prettier": "^10.1.8",

package/src/components/forms/FormFieldWrapper.tsx

@@ -21,7 +21,7 @@ type FormFieldWrapperProps<T extends FieldValues> = {
    * label built by the caller, so the label row stays one element.
    */
   labelAction?: ReactNode;
-  description?: string;
+  description?: ReactNode;
   isRequired?: boolean;
   orientation?: "vertical" | "horizontal" | "responsive";
   className?: string;

package/src/components/forms/FormTextarea.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { ReactNode } from "react";
 import { Textarea } from "../../shadcnui";
 import { cn } from "../../utils";
 import { FormFieldWrapper } from "./FormFieldWrapper";
@@ -21,7 +22,7 @@ export function FormTextarea({
   placeholder?: string;
   className?: string;
   testId?: string;
-  description?: string;
+  description?: ReactNode;
   isRequired?: boolean;
   textareaRef?: React.RefObject<HTMLTextAreaElement>;
 }) {

package/src/core/index.ts

@@ -67,6 +67,14 @@ export * from "../features/content/content.module";
 export * from "../features/content/data";
 export * from "../features/how-to/HowToModule";
 export * from "../features/how-to/data";
+export * from "../features/email-automation/EmailAutomationModule";
+export * from "../features/email-automation/EmailAutomationStepModule";
+export * from "../features/email-automation/EmailAutomationEnrollmentModule";
+export * from "../features/email-automation/EmailAutomationTriggerModule";
+// Email automation data (models, services, interfaces, fields): server-safe, so a
+// server page can wrap EmailAutomationService.findOne in cache(). The client-marked
+// ./email-automations entry carries only components, contexts and hooks.
+export * from "../features/email-automation/data";
 export * from "../features/handbook/HandbookPageModule";
 export * from "../features/handbook/HandbookSectionModule";
 export * from "../features/handbook/HandbookThreadMessageModule";

package/src/core/registry/ModuleRegistry.ts

@@ -41,6 +41,11 @@ export interface FoundationModuleDefinitions {
   // Waitlist modules
   Waitlist: ModuleWithPermissions;
   WaitlistStats: ModuleWithPermissions;
+  // Email automation modules
+  EmailAutomation: ModuleWithPermissions;
+  EmailAutomationStep: ModuleWithPermissions;
+  EmailAutomationEnrollment: ModuleWithPermissions;
+  EmailAutomationTrigger: ModuleWithPermissions;
   // Referral modules
   Referral: ModuleWithPermissions;
   ReferralStats: ModuleWithPermissions;

package/src/email-automations/index.ts

@@ -0,0 +1,5 @@
+// Email automation components - separate entry point to avoid loading @xyflow/react globally
+export * from "../features/email-automation/components";
+export * from "../features/email-automation/contexts/EmailAutomationContext";
+export * from "../features/email-automation/components/canvas/shared";
+export * from "../features/email-automation/hooks";

package/src/features/email-automation/EmailAutomationEnrollmentModule.ts

@@ -0,0 +1,11 @@
+import { UsersIcon } from "lucide-react";
+import { ModuleFactory } from "../../permissions";
+import { EmailAutomationEnrollment } from "./data/EmailAutomationEnrollment";
+
+export const EmailAutomationEnrollmentModule = (factory: ModuleFactory) =>
+  factory({
+    pageUrl: undefined,
+    name: "email-automation-enrollments",
+    model: EmailAutomationEnrollment,
+    icon: UsersIcon,
+  });

package/src/features/email-automation/EmailAutomationModule.ts

@@ -0,0 +1,30 @@
+import { MailIcon } from "lucide-react";
+import { createJsonApiInclusion } from "../../core";
+import { ModuleFactory } from "../../permissions";
+import { EmailAutomation } from "./data/EmailAutomation";
+
+export const EmailAutomationModule = (factory: ModuleFactory) =>
+  factory({
+    moduleId: "3f6c1a2e-7b94-4d1e-8c55-9a0b2e4f6d71",
+    pageUrl: "/administration/email-automations",
+    name: "email-automations",
+    model: EmailAutomation,
+    icon: MailIcon,
+    inclusions: {
+      lists: {
+        fields: [
+          createJsonApiInclusion("email-automations", [
+            "name",
+            "trigger",
+            "exitTrigger",
+            "replyTo",
+            "isActive",
+            "stepCount",
+            "activeCount",
+            "completedCount",
+            "unsubscribedCount",
+          ]),
+        ],
+      },
+    },
+  });

package/src/features/email-automation/EmailAutomationStepModule.ts

@@ -0,0 +1,11 @@
+import { MailIcon } from "lucide-react";
+import { ModuleFactory } from "../../permissions";
+import { EmailAutomationStep } from "./data/EmailAutomationStep";
+
+export const EmailAutomationStepModule = (factory: ModuleFactory) =>
+  factory({
+    pageUrl: undefined,
+    name: "email-automation-steps",
+    model: EmailAutomationStep,
+    icon: MailIcon,
+  });

package/src/features/email-automation/EmailAutomationTriggerModule.ts

@@ -0,0 +1,11 @@
+import { ZapIcon } from "lucide-react";
+import { ModuleFactory } from "../../permissions";
+import { EmailAutomationTrigger } from "./data/EmailAutomationTrigger";
+
+export const EmailAutomationTriggerModule = (factory: ModuleFactory) =>
+  factory({
+    pageUrl: undefined,
+    name: "email-automation-triggers",
+    model: EmailAutomationTrigger,
+    icon: ZapIcon,
+  });

package/src/features/email-automation/components/__tests__/EmailAutomationEditor.spec.tsx

@@ -0,0 +1,104 @@
+import { render, screen, waitFor, within } from "@testing-library/react";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { configureI18n } from "../../../../i18n";
+import { EmailAutomationEditor } from "../forms/EmailAutomationEditor";
+
+// Hoisted so the vi.mock factories below (which run before the module body)
+// can close over them.
+const mocks = vi.hoisted(() => ({
+  findTriggers: vi.fn(),
+  create: vi.fn(),
+  update: vi.fn(),
+}));
+
+vi.mock("../../data/EmailAutomationService", () => ({
+  EmailAutomationService: {
+    findTriggers: mocks.findTriggers,
+    create: mocks.create,
+    update: mocks.update,
+  },
+}));
+
+// Base UI renders a closed Select's options nowhere in the DOM, so FormSelect
+// is replaced by a stub that prints its label, its empty option and its
+// values. Everything else in the barrel stays real.
+vi.mock("../../../../components", async () => {
+  const actual = await vi.importActual<typeof import("../../../../components")>("../../../../components");
+  return {
+    ...actual,
+    FormSelect: (props: {
+      id: string;
+      name?: string;
+      placeholder?: string;
+      allowEmpty?: boolean;
+      values: { id: string; text: string }[];
+    }) => (
+      <div data-testid={`form-select-${props.id}`}>
+        <span>{props.name}</span>
+        {props.allowEmpty && <span data-value="">{props.placeholder}</span>}
+        {props.values.map((value) => (
+          <span key={value.id} data-value={value.id}>
+            {value.text}
+          </span>
+        ))}
+      </div>
+    ),
+  };
+});
+
+const TRIGGERS = [
+  { id: "waitlist-confirmed", key: "waitlist-confirmed", label: "Waitlist confirmed" },
+  { id: "registration-completed", key: "registration-completed", label: "Registration completed" },
+];
+
+// `Modules.EmailAutomation` resolves through the registry at render time.
+beforeAll(() => {
+  ModuleRegistry.register("EmailAutomation", {
+    name: "email-automations",
+    pageUrl: "/administration/email-automations",
+  } as any);
+});
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mocks.findTriggers.mockResolvedValue(TRIGGERS);
+  configureI18n({
+    useRouter: () => ({
+      push: vi.fn(),
+      replace: vi.fn(),
+      back: vi.fn(),
+      forward: vi.fn(),
+      refresh: vi.fn(),
+      prefetch: vi.fn(),
+    }),
+    useTranslations: () => (key: string) => key,
+    Link: ({ children }: any) => children,
+    usePathname: () => "/",
+  });
+});
+
+describe("EmailAutomationEditor", () => {
+  it("renders the five fields by their labels", async () => {
+    render(<EmailAutomationEditor forceShow dialogOpen />);
+
+    expect(await screen.findByText("emailAutomations.fields.name.label")).toBeInTheDocument();
+    expect(screen.getByText("emailAutomations.fields.trigger.label")).toBeInTheDocument();
+    expect(screen.getByText("emailAutomations.fields.exitTrigger.label")).toBeInTheDocument();
+    expect(screen.getByText("emailAutomations.fields.replyTo.label")).toBeInTheDocument();
+    expect(screen.getByText("emailAutomations.fields.isActive.label")).toBeInTheDocument();
+  });
+
+  it("lists the none option plus the trigger labels returned by the API", async () => {
+    render(<EmailAutomationEditor forceShow dialogOpen />);
+
+    const triggerSelect = await screen.findByTestId("form-select-trigger");
+    await waitFor(() => expect(within(triggerSelect).getByText("Waitlist confirmed")).toBeInTheDocument());
+
+    expect(mocks.findTriggers).toHaveBeenCalled();
+    expect(within(triggerSelect).getByText("emailAutomations.fields.trigger.none")).toBeInTheDocument();
+    expect(within(triggerSelect).getByText("Registration completed")).toBeInTheDocument();
+    // The option values are the trigger keys, the visible text the plain label.
+    expect(within(triggerSelect).getByText("Waitlist confirmed")).toHaveAttribute("data-value", "waitlist-confirmed");
+  });
+});

package/src/features/email-automation/components/canvas/EmailAutomationActiveSwitch.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { useState } from "react";
+import { errorToast } from "../../../../components";
+import { Switch, Tooltip, TooltipContent, TooltipTrigger } from "../../../../shadcnui";
+import { useEmailAutomation } from "../../contexts/EmailAutomationContext";
+import { EmailAutomationService } from "../../data/EmailAutomationService";
+
+/**
+ * Inline on/off for the automation page header, so pausing never needs the
+ * editor sheet. Off holds every enrolment in place (spec § "Sending" 3).
+ */
+export function EmailAutomationActiveSwitch() {
+  const t = useTranslations();
+  const { automation, reload } = useEmailAutomation();
+  const [saving, setSaving] = useState<boolean>(false);
+
+  if (!automation) return null;
+
+  const toggle = async (checked: boolean) => {
+    setSaving(true);
+    try {
+      await EmailAutomationService.update({
+        id: automation.id,
+        name: automation.name,
+        trigger: automation.trigger,
+        exitTrigger: automation.exitTrigger,
+        replyTo: automation.replyTo,
+        isActive: checked,
+      });
+      await reload();
+    } catch (error) {
+      errorToast({ title: t("common.errors.error"), error });
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <Tooltip>
+      <TooltipTrigger render={<label className="flex items-center gap-x-2" />}>
+        <Switch checked={automation.isActive} onCheckedChange={(checked) => void toggle(checked)} disabled={saving} />
+        <span className="text-xs">{t("emailAutomations.fields.isActive.label")}</span>
+      </TooltipTrigger>
+      <TooltipContent className="max-w-xs">{t("emailAutomations.fields.isActive.help")}</TooltipContent>
+    </Tooltip>
+  );
+}