@carlonicora/nextjs-jsonapi 5.2.0 → 5.4.0

package/src/features/email-automation/components/unsubscribe/EmailUnsubscribe.tsx

@@ -0,0 +1,99 @@
+"use client";
+
+import { CheckCircle, Loader2, XCircle } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useEffect, useState } from "react";
+import { Button } from "../../../../shadcnui";
+import { SectionHeader } from "../../../../components/typography";
+import { EmailAutomationEnrollmentService } from "../../data/EmailAutomationEnrollmentService";
+
+type UnsubscribeScope = "automation" | "all";
+
+interface Props {
+  token: string;
+  scope: UnsubscribeScope;
+}
+
+type UnsubscribeState = "loading" | "success" | "error";
+
+export function EmailUnsubscribe({ token, scope }: Props) {
+  const t = useTranslations();
+  const [state, setState] = useState<UnsubscribeState>("loading");
+  const [stoppedScope, setStoppedScope] = useState<UnsubscribeScope>(scope);
+  const [automationName, setAutomationName] = useState<string>("");
+  const [isStoppingAll, setIsStoppingAll] = useState<boolean>(false);
+
+  useEffect(() => {
+    async function unsubscribe() {
+      try {
+        const enrollment = await EmailAutomationEnrollmentService.unsubscribe({ token, scope });
+        setAutomationName(enrollment?.automation?.name ?? "");
+        setStoppedScope(scope);
+        setState("success");
+      } catch {
+        setState("error");
+      }
+    }
+
+    unsubscribe();
+  }, [token, scope]);
+
+  const stopAll = async () => {
+    setIsStoppingAll(true);
+    try {
+      await EmailAutomationEnrollmentService.unsubscribe({ token, scope: "all" });
+      setStoppedScope("all");
+    } catch {
+      setState("error");
+    } finally {
+      setIsStoppingAll(false);
+    }
+  };
+
+  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 text-sm">{t("emailAutomations.unsubscribe.loading")}</p>
+      </div>
+    );
+  }
+
+  if (state === "error") {
+    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>
+        <SectionHeader level={2}>{t("emailAutomations.unsubscribe.invalidTitle")}</SectionHeader>
+        <p className="text-muted-foreground max-w-md text-sm leading-relaxed">
+          {t("emailAutomations.unsubscribe.invalidBody")}
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex flex-col items-center justify-center space-y-4 py-16 text-center">
+      <div className="bg-primary/10 rounded-full p-4">
+        <CheckCircle className="text-primary h-12 w-12" />
+      </div>
+      <SectionHeader level={2}>{t("emailAutomations.unsubscribe.title")}</SectionHeader>
+      {stoppedScope === "all" ? (
+        <p className="text-muted-foreground max-w-md text-sm leading-relaxed">
+          {t("emailAutomations.unsubscribe.stoppedAll")}
+        </p>
+      ) : (
+        <>
+          <p className="text-muted-foreground max-w-md text-sm leading-relaxed">
+            {t("emailAutomations.unsubscribe.stoppedAutomation", { name: automationName })}
+          </p>
+          <Button variant="secondary" onClick={stopAll} disabled={isStoppingAll}>
+            {isStoppingAll && <Loader2 className="h-4 w-4 animate-spin" />}
+            {t("emailAutomations.unsubscribe.alsoStopAll")}
+          </Button>
+        </>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,55 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { EmailUnsubscribe } from "../EmailUnsubscribe";
+
+const { unsubscribe } = vi.hoisted(() => ({
+  unsubscribe: vi.fn(),
+}));
+
+vi.mock("../../../data/EmailAutomationEnrollmentService", () => ({
+  EmailAutomationEnrollmentService: {
+    unsubscribe: (params: unknown) => unsubscribe(params),
+  },
+}));
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("EmailUnsubscribe", () => {
+  it("stops the automation and offers to stop every marketing email", async () => {
+    unsubscribe.mockResolvedValue({ automation: { name: "Welcome" } });
+
+    render(<EmailUnsubscribe token="tok" scope="automation" />);
+
+    expect(await screen.findByText("emailAutomations.unsubscribe.stoppedAutomation")).toBeInTheDocument();
+    expect(unsubscribe).toHaveBeenCalledWith({ token: "tok", scope: "automation" });
+
+    fireEvent.click(screen.getByRole("button", { name: "emailAutomations.unsubscribe.alsoStopAll" }));
+
+    expect(await screen.findByText("emailAutomations.unsubscribe.stoppedAll")).toBeInTheDocument();
+    expect(unsubscribe).toHaveBeenLastCalledWith({ token: "tok", scope: "all" });
+    expect(screen.queryByRole("button", { name: "emailAutomations.unsubscribe.alsoStopAll" })).not.toBeInTheDocument();
+  });
+
+  it("shows only the stopped-all message when the link already asks for every email", async () => {
+    unsubscribe.mockResolvedValue({ automation: { name: "Welcome" } });
+
+    render(<EmailUnsubscribe token="tok" scope="all" />);
+
+    expect(await screen.findByText("emailAutomations.unsubscribe.stoppedAll")).toBeInTheDocument();
+    expect(unsubscribe).toHaveBeenCalledWith({ token: "tok", scope: "all" });
+    expect(screen.queryByRole("button", { name: "emailAutomations.unsubscribe.alsoStopAll" })).not.toBeInTheDocument();
+  });
+
+  it("shows the invalid-link state when the call is rejected", async () => {
+    unsubscribe.mockRejectedValue(new Error("Not found"));
+
+    render(<EmailUnsubscribe token="unknown" scope="automation" />);
+
+    await waitFor(() => {
+      expect(screen.getByText("emailAutomations.unsubscribe.invalidTitle")).toBeInTheDocument();
+    });
+    expect(screen.getByText("emailAutomations.unsubscribe.invalidBody")).toBeInTheDocument();
+  });
+});

package/src/features/email-automation/contexts/EmailAutomationContext.tsx

@@ -0,0 +1,175 @@
+"use client";
+
+import { createContext, ReactNode, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { v4 } from "uuid";
+import { EmailAutomationInterface } from "../data/EmailAutomationInterface";
+import { EmailAutomationService } from "../data/EmailAutomationService";
+import { EmailAutomationStepInput, EmailAutomationStepInterface } from "../data/EmailAutomationStepInterface";
+import { EmailAutomationStepService } from "../data/EmailAutomationStepService";
+import { EmailAutomationTriggerInterface } from "../data/EmailAutomationTriggerInterface";
+
+/** A new step: the provider always sets `automationId` and, when absent, a fresh `id`. */
+export type EmailAutomationStepCreateInput = Omit<EmailAutomationStepInput, "id" | "automationId"> & {
+  id?: string;
+  automationId?: string;
+};
+/** A step update: the provider always sets `automationId`. */
+export type EmailAutomationStepUpdateInput = Omit<EmailAutomationStepInput, "automationId"> & { automationId?: string };
+
+export interface EmailAutomationContextType {
+  automation: EmailAutomationInterface | undefined;
+  steps: EmailAutomationStepInterface[];
+  reload: () => Promise<void>;
+  selectedStepId: string | null;
+  select: (id: string | null) => void;
+  createStep: (input: EmailAutomationStepCreateInput) => Promise<EmailAutomationStepInterface>;
+  updateStep: (input: EmailAutomationStepUpdateInput) => Promise<EmailAutomationStepInterface>;
+  deleteStep: (id: string) => Promise<void>;
+  setNext: (stepId: string, nextStepId: string | null) => Promise<void>;
+  updatePosition: (stepId: string, x: number, y: number) => Promise<void>;
+  tidy: () => Promise<void>;
+  triggers: EmailAutomationTriggerInterface[];
+}
+
+const EmailAutomationContext = createContext<EmailAutomationContextType | undefined>(undefined);
+
+export type EmailAutomationProviderProps = {
+  automationId: string;
+  children: ReactNode;
+};
+
+export const EmailAutomationProvider = ({ automationId, children }: EmailAutomationProviderProps) => {
+  const [automation, setAutomation] = useState<EmailAutomationInterface | undefined>(undefined);
+  const [steps, setSteps] = useState<EmailAutomationStepInterface[]>([]);
+  const [triggers, setTriggers] = useState<EmailAutomationTriggerInterface[]>([]);
+  const [selectedStepId, setSelectedStepId] = useState<string | null>(null);
+
+  const reload = useCallback(async () => {
+    const [loadedAutomation, loadedSteps] = await Promise.all([
+      EmailAutomationService.findOne({ id: automationId }),
+      EmailAutomationStepService.findByAutomation({ automationId }),
+    ]);
+    setAutomation(loadedAutomation);
+    setSteps(loadedSteps);
+  }, [automationId]);
+
+  useEffect(() => {
+    void reload();
+  }, [reload]);
+
+  useEffect(() => {
+    let active = true;
+    EmailAutomationService.findTriggers()
+      .then((list) => {
+        if (active) setTriggers(list);
+      })
+      .catch(() => {});
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  const select = useCallback((id: string | null) => setSelectedStepId(id), []);
+
+  const createStep = useCallback(
+    async (input: EmailAutomationStepCreateInput) => {
+      const saved = await EmailAutomationStepService.create({ ...input, id: input.id ?? v4(), automationId });
+      await reload();
+      return saved;
+    },
+    [automationId, reload],
+  );
+
+  const updateStep = useCallback(
+    async (input: EmailAutomationStepUpdateInput) => {
+      const saved = await EmailAutomationStepService.update({ ...input, automationId });
+      await reload();
+      return saved;
+    },
+    [automationId, reload],
+  );
+
+  const deleteStep = useCallback(
+    async (id: string) => {
+      await EmailAutomationStepService.delete({ id });
+      if (selectedStepId === id) setSelectedStepId(null);
+      await reload();
+    },
+    [reload, selectedStepId],
+  );
+
+  const setNext = useCallback(
+    async (stepId: string, nextStepId: string | null) => {
+      if (nextStepId) await EmailAutomationStepService.setNext({ stepId, nextStepId });
+      else await EmailAutomationStepService.clearNext({ stepId });
+      await reload();
+    },
+    [reload],
+  );
+
+  // PATCH with the step's current attributes plus the new position: the step
+  // input type requires subject and body, and sending them unchanged is a no-op.
+  const updatePosition = useCallback(
+    async (stepId: string, x: number, y: number) => {
+      const step = steps.find((candidate) => candidate.id === stepId);
+      if (!step) return;
+      await EmailAutomationStepService.update({
+        id: step.id,
+        automationId,
+        subject: step.subject,
+        body: step.body,
+        delayHours: step.delayHours,
+        positionX: x,
+        positionY: y,
+      });
+      await reload();
+    },
+    [automationId, reload, steps],
+  );
+
+  const tidy = useCallback(async () => {
+    await EmailAutomationService.tidy({ id: automationId });
+    await reload();
+  }, [automationId, reload]);
+
+  const value = useMemo<EmailAutomationContextType>(
+    () => ({
+      automation,
+      steps,
+      reload,
+      selectedStepId,
+      select,
+      createStep,
+      updateStep,
+      deleteStep,
+      setNext,
+      updatePosition,
+      tidy,
+      triggers,
+    }),
+    [
+      automation,
+      steps,
+      reload,
+      selectedStepId,
+      select,
+      createStep,
+      updateStep,
+      deleteStep,
+      setNext,
+      updatePosition,
+      tidy,
+      triggers,
+    ],
+  );
+
+  return <EmailAutomationContext.Provider value={value}>{children}</EmailAutomationContext.Provider>;
+};
+
+export const useEmailAutomation = (): EmailAutomationContextType => {
+  const context = useContext(EmailAutomationContext);
+  if (context === undefined) {
+    throw new Error("useEmailAutomation must be used within an EmailAutomationProvider");
+  }
+  return context;
+};

package/src/features/email-automation/data/EmailAutomation.ts

@@ -0,0 +1,87 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { EmailAutomationInput, EmailAutomationInterface } from "./EmailAutomationInterface";
+
+export class EmailAutomation extends AbstractApiData implements EmailAutomationInterface {
+  private _name?: string;
+  private _trigger?: string;
+  private _exitTrigger?: string;
+  private _replyTo?: string;
+  private _isActive: boolean = false;
+  private _stepCount?: number;
+  private _activeCount?: number;
+  private _completedCount?: number;
+  private _unsubscribedCount?: number;
+
+  get name(): string {
+    return this._name ?? "";
+  }
+
+  get trigger(): string | undefined {
+    return this._trigger;
+  }
+
+  get exitTrigger(): string | undefined {
+    return this._exitTrigger;
+  }
+
+  get replyTo(): string | undefined {
+    return this._replyTo;
+  }
+
+  get isActive(): boolean {
+    return this._isActive;
+  }
+
+  get stepCount(): number {
+    return this._stepCount ?? 0;
+  }
+
+  get activeCount(): number {
+    return this._activeCount ?? 0;
+  }
+
+  get completedCount(): number {
+    return this._completedCount ?? 0;
+  }
+
+  get unsubscribedCount(): number {
+    return this._unsubscribedCount ?? 0;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    this._name = data.jsonApi.attributes.name;
+    this._trigger = data.jsonApi.attributes.trigger ?? undefined;
+    this._exitTrigger = data.jsonApi.attributes.exitTrigger ?? undefined;
+    this._replyTo = data.jsonApi.attributes.replyTo ?? undefined;
+    this._isActive = data.jsonApi.attributes.isActive === true;
+    this._stepCount = data.jsonApi.attributes.stepCount;
+    this._activeCount = data.jsonApi.attributes.activeCount;
+    this._completedCount = data.jsonApi.attributes.completedCount;
+    this._unsubscribedCount = data.jsonApi.attributes.unsubscribedCount;
+
+    return this;
+  }
+
+  createJsonApi(data: EmailAutomationInput) {
+    const response: any = {
+      data: {
+        type: Modules.EmailAutomation.name,
+        id: data.id,
+        attributes: {},
+        meta: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    if (data.name !== undefined) response.data.attributes.name = data.name;
+    if (data.trigger !== undefined) response.data.attributes.trigger = data.trigger;
+    if (data.exitTrigger !== undefined) response.data.attributes.exitTrigger = data.exitTrigger;
+    if (data.replyTo !== undefined) response.data.attributes.replyTo = data.replyTo;
+    if (data.isActive !== undefined) response.data.attributes.isActive = data.isActive;
+
+    return response;
+  }
+}

package/src/features/email-automation/data/EmailAutomationEnrollment.ts

@@ -0,0 +1,105 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import {
+  EmailAutomationEnrollmentInterface,
+  EmailAutomationEnrollmentStatus,
+} from "./EmailAutomationEnrollmentInterface";
+import { EmailAutomationInterface } from "./EmailAutomationInterface";
+
+/** JSON:API type of the POST email-automations/unsubscribe/:token request body (not a module: nothing is stored). */
+export const EMAIL_AUTOMATION_UNSUBSCRIBE_TYPE = "email-automation-unsubscribes";
+
+export class EmailAutomationEnrollment extends AbstractApiData implements EmailAutomationEnrollmentInterface {
+  private _email?: string;
+  private _name?: string;
+  private _status: EmailAutomationEnrollmentStatus = "active";
+  private _enrolledAt?: Date;
+  private _nextSendAt?: Date;
+  private _finishedAt?: Date;
+  private _attempts?: number;
+  private _lastError?: string;
+  private _currentStepSubject?: string;
+  private _sentCount?: number;
+  private _automation?: EmailAutomationInterface;
+
+  get email(): string {
+    return this._email ?? "";
+  }
+
+  get name(): string | undefined {
+    return this._name;
+  }
+
+  get status(): EmailAutomationEnrollmentStatus {
+    return this._status;
+  }
+
+  get enrolledAt(): Date {
+    return this._enrolledAt ?? new Date(0);
+  }
+
+  get nextSendAt(): Date | undefined {
+    return this._nextSendAt;
+  }
+
+  get finishedAt(): Date | undefined {
+    return this._finishedAt;
+  }
+
+  get attempts(): number {
+    return this._attempts ?? 0;
+  }
+
+  get lastError(): string | undefined {
+    return this._lastError;
+  }
+
+  get currentStepSubject(): string | undefined {
+    return this._currentStepSubject;
+  }
+
+  get sentCount(): number {
+    return this._sentCount ?? 0;
+  }
+
+  get automation(): EmailAutomationInterface | undefined {
+    return this._automation;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attributes = data.jsonApi.attributes;
+    this._email = attributes.email;
+    this._name = attributes.name ?? undefined;
+    this._status = attributes.status ?? "active";
+    this._enrolledAt = attributes.enrolledAt ? new Date(attributes.enrolledAt) : undefined;
+    this._nextSendAt = attributes.nextSendAt ? new Date(attributes.nextSendAt) : undefined;
+    this._finishedAt = attributes.finishedAt ? new Date(attributes.finishedAt) : undefined;
+    this._attempts = attributes.attempts;
+    this._lastError = attributes.lastError ?? undefined;
+    this._currentStepSubject = attributes.currentStepSubject ?? undefined;
+    this._sentCount = attributes.sentCount;
+
+    this._automation = this._readIncluded(data, "automation", Modules.EmailAutomation) as EmailAutomationInterface;
+
+    return this;
+  }
+
+  createJsonApi(_data?: any): any {
+    throw new Error("EmailAutomationEnrollment is created by the API and cannot be created from the client");
+  }
+
+  /**
+   * Body of POST email-automations/unsubscribe/:token.
+   */
+  createUnsubscribeJsonApi(params: { scope: "automation" | "all" }) {
+    return {
+      data: {
+        type: EMAIL_AUTOMATION_UNSUBSCRIBE_TYPE,
+        attributes: {
+          scope: params.scope,
+        },
+      },
+    };
+  }
+}

package/src/features/email-automation/data/EmailAutomationEnrollmentInterface.ts

@@ -0,0 +1,18 @@
+import { ApiDataInterface } from "../../../core";
+import { EmailAutomationInterface } from "./EmailAutomationInterface";
+
+export type EmailAutomationEnrollmentStatus = "active" | "completed" | "unsubscribed" | "exited" | "failed";
+
+export interface EmailAutomationEnrollmentInterface extends ApiDataInterface {
+  get email(): string;
+  get name(): string | undefined;
+  get status(): EmailAutomationEnrollmentStatus;
+  get enrolledAt(): Date;
+  get nextSendAt(): Date | undefined;
+  get finishedAt(): Date | undefined;
+  get attempts(): number;
+  get lastError(): string | undefined;
+  get currentStepSubject(): string | undefined;
+  get sentCount(): number;
+  get automation(): EmailAutomationInterface | undefined;
+}

package/src/features/email-automation/data/EmailAutomationEnrollmentService.ts

@@ -0,0 +1,31 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
+import { EmailAutomationEnrollment } from "./EmailAutomationEnrollment";
+import { EmailAutomationEnrollmentInterface } from "./EmailAutomationEnrollmentInterface";
+
+export class EmailAutomationEnrollmentService extends AbstractService {
+  /**
+   * POST email-automations/unsubscribe/:token (public). The scope travels both as
+   * a query parameter and in the body, as the API reads either.
+   */
+  static async unsubscribe(params: {
+    token: string;
+    scope: "automation" | "all";
+  }): Promise<EmailAutomationEnrollmentInterface> {
+    const enrollment = new EmailAutomationEnrollment();
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.EmailAutomation,
+      childEndpoint: "unsubscribe",
+      childId: params.token,
+    });
+
+    endpoint.addAdditionalParam("scope", params.scope);
+
+    return this.callApi<EmailAutomationEnrollmentInterface>({
+      type: Modules.EmailAutomationEnrollment,
+      method: HttpMethod.POST,
+      endpoint: endpoint.generate(),
+      input: enrollment.createUnsubscribeJsonApi({ scope: params.scope }),
+      overridesJsonApiCreation: true,
+    });
+  }
+}

package/src/features/email-automation/data/EmailAutomationInterface.ts

@@ -0,0 +1,22 @@
+import { ApiDataInterface } from "../../../core";
+
+export type EmailAutomationInput = {
+  id: string;
+  name: string;
+  trigger?: string;
+  exitTrigger?: string;
+  replyTo?: string;
+  isActive?: boolean;
+};
+
+export interface EmailAutomationInterface extends ApiDataInterface {
+  get name(): string;
+  get trigger(): string | undefined;
+  get exitTrigger(): string | undefined;
+  get replyTo(): string | undefined;
+  get isActive(): boolean;
+  get stepCount(): number;
+  get activeCount(): number;
+  get completedCount(): number;
+  get unsubscribedCount(): number;
+}