@carlonicora/nextjs-jsonapi 6.7.0 → 6.9.0

package/src/features/email-blast/components/forms/EmailBlastEditor.tsx

@@ -0,0 +1,132 @@
+"use client";
+
+import { zodResolver } from "@hookform/resolvers/zod";
+import { useTranslations } from "next-intl";
+import { ReactNode, useCallback, useMemo } from "react";
+import { useForm } from "react-hook-form";
+import { v4 } from "uuid";
+import { z } from "zod";
+import { EditorSheet, FormInput, FormTextarea } from "../../../../components";
+import { Modules } from "../../../../core";
+import { useI18nRouter } from "../../../../i18n";
+import { EmailBlastInput, EmailBlastInterface } from "../../data/EmailBlastInterface";
+import { EmailBlastService } from "../../data/EmailBlastService";
+
+/** The fixed variable set the blast renderer fills. */
+const TEMPLATE_VARIABLES = ["{{name}}", "{{email}}", "{{url}}", "{{unsubscribeAllUrl}}"];
+
+export type EmailBlastEditorProps = {
+  blast?: EmailBlastInterface;
+  propagateChanges?: (blast: EmailBlastInterface) => void;
+  onSuccess?: () => void | Promise<void>;
+  trigger?: ReactNode;
+  forceShow?: boolean;
+  onClose?: () => void;
+  dialogOpen?: boolean;
+  onDialogOpenChange?: (open: boolean) => void;
+};
+
+function EmailBlastEditorInternal({
+  blast,
+  propagateChanges,
+  onSuccess,
+  trigger,
+  forceShow,
+  onClose,
+  dialogOpen,
+  onDialogOpenChange,
+}: EmailBlastEditorProps) {
+  const t = useTranslations();
+  const router = useI18nRouter();
+  const isEdit = !!blast;
+
+  const formSchema = useMemo(
+    () =>
+      z.object({
+        id: z.uuidv4(),
+        subject: z.string().min(1, { message: t("emailBlasts.editor.fields.subject.error") }),
+        body: z.string().min(1, { message: t("emailBlasts.editor.fields.body.error") }),
+        replyTo: z.string().refine((value) => value === "" || z.email().safeParse(value).success, {
+          message: t("emailBlasts.editor.fields.replyTo.error"),
+        }),
+      }),
+    [t],
+  );
+
+  const getDefaultValues = useCallback(
+    () => ({
+      id: blast?.id ?? v4(),
+      subject: blast?.subject ?? "",
+      body: blast?.body ?? "",
+      replyTo: blast?.replyTo ?? "",
+    }),
+    [blast],
+  );
+
+  const form = useForm<z.infer<typeof formSchema>>({
+    resolver: zodResolver(formSchema),
+    defaultValues: getDefaultValues(),
+  });
+
+  return (
+    <EditorSheet
+      form={form}
+      entityType={t("emailBlasts.editor.title")}
+      entityName={blast?.subject}
+      title={isEdit ? t("emailBlasts.editor.editTitle") : t("emailBlasts.editor.title")}
+      isEdit={isEdit}
+      module={Modules.EmailBlast}
+      size="lg"
+      propagateChanges={propagateChanges}
+      onSuccess={onSuccess}
+      onNavigate={(url) => router.push(url)}
+      onSubmit={async (values) => {
+        const payload: EmailBlastInput = {
+          id: values.id,
+          subject: values.subject,
+          body: values.body,
+          replyTo: values.replyTo || undefined,
+        };
+        return isEdit ? await EmailBlastService.update(payload) : await EmailBlastService.create(payload);
+      }}
+      onReset={getDefaultValues}
+      trigger={trigger}
+      forceShow={forceShow}
+      onClose={onClose}
+      dialogOpen={dialogOpen}
+      onDialogOpenChange={onDialogOpenChange}
+    >
+      <div className="flex w-full flex-col gap-y-4">
+        <FormInput form={form} id="subject" name={t("emailBlasts.editor.fields.subject.label")} isRequired />
+        <FormInput form={form} id="replyTo" name={t("emailBlasts.editor.fields.replyTo.label")} />
+        {/* FormTextarea has no `rows` prop; min-h-72 is the height of ~14 rows. */}
+        <FormTextarea
+          form={form}
+          id="body"
+          name={t("emailBlasts.editor.fields.body.label")}
+          className="min-h-72"
+          isRequired
+          description={
+            <>
+              <span className="block">
+                {t("emailBlasts.editor.variablesHint")}{" "}
+                {TEMPLATE_VARIABLES.map((variable) => (
+                  <span key={variable} className="me-2 text-foreground">
+                    {variable}
+                  </span>
+                ))}
+              </span>
+              <span className="mt-1 block">{t("emailBlasts.editor.unsubscribeHint")}</span>
+            </>
+          }
+        />
+      </div>
+    </EditorSheet>
+  );
+}
+
+export function EmailBlastEditor(props: EmailBlastEditorProps) {
+  return <EmailBlastEditorInternal {...props} />;
+}
+
+export default EmailBlastEditor;

package/src/features/email-blast/components/forms/EmailBlastSendDialog.tsx

@@ -0,0 +1,104 @@
+"use client";
+
+import { LoaderCircleIcon, SendIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useEffect, useState } from "react";
+import { errorToast } from "../../../../components/errors/errorToast";
+import {
+  AlertDialog,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from "../../../../shadcnui/ui/alert-dialog";
+import { Button } from "../../../../shadcnui/ui/button";
+import { EmailBlastInterface } from "../../data/EmailBlastInterface";
+import { EmailBlastService } from "../../data/EmailBlastService";
+
+export type EmailBlastSendDialogProps = {
+  blast: EmailBlastInterface;
+  onSuccess?: () => void | Promise<void>;
+};
+
+/**
+ * Header action on a draft blast: asks how many people it reaches now, then sends.
+ * Same AlertDialog shape as AccountDeletionAdminTrigger.
+ */
+export function EmailBlastSendDialog({ blast, onSuccess }: EmailBlastSendDialogProps) {
+  const t = useTranslations();
+  const [open, setOpen] = useState<boolean>(false);
+  const [count, setCount] = useState<number | undefined>(undefined);
+  const [isSending, setIsSending] = useState<boolean>(false);
+
+  // The count is read each time the dialog opens: consent and opt-outs change.
+  useEffect(() => {
+    if (!open) return;
+    let cancelled = false;
+    setCount(undefined);
+    EmailBlastService.findAudience({ id: blast.id })
+      .then((audience) => {
+        if (!cancelled) setCount(audience.recipientCount);
+      })
+      .catch((error) => {
+        if (!cancelled) errorToast({ title: t("common.errors.error"), error });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [open, blast.id, t]);
+
+  const isLoading = count === undefined;
+  const canSend = !isLoading && count > 0 && !isSending;
+
+  const handleSend = async () => {
+    setIsSending(true);
+    try {
+      await EmailBlastService.send({ id: blast.id });
+      await onSuccess?.();
+      setOpen(false);
+    } catch (error) {
+      errorToast({ title: t("common.errors.error"), error });
+    } finally {
+      setIsSending(false);
+    }
+  };
+
+  return (
+    <AlertDialog open={open} onOpenChange={setOpen}>
+      <AlertDialogTrigger render={<Button size="sm" variant="default" />}>
+        <SendIcon />
+        {t("emailBlasts.send.button")}
+      </AlertDialogTrigger>
+      <AlertDialogContent className="flex max-h-[70vh] max-w-3xl flex-col overflow-y-auto">
+        <AlertDialogHeader>
+          <AlertDialogTitle>{t("emailBlasts.send.title")}</AlertDialogTitle>
+          <AlertDialogDescription>
+            {isLoading ? (
+              <LoaderCircleIcon className="animate-spin-slow h-5 w-5" />
+            ) : count === 0 ? (
+              t("emailBlasts.send.nobody")
+            ) : (
+              t("emailBlasts.send.confirm", { count })
+            )}
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <div className="flex justify-end">
+          <Button className="me-2" variant="outline" type="button" onClick={() => setOpen(false)} disabled={isSending}>
+            {t("emailBlasts.send.cancel")}
+          </Button>
+          <Button type="button" variant="default" onClick={handleSend} disabled={!canSend}>
+            {isSending ? (
+              <>
+                {t("emailBlasts.send.action")}
+                <LoaderCircleIcon className="animate-spin-slow h-5 w-5" />
+              </>
+            ) : (
+              t("emailBlasts.send.action")
+            )}
+          </Button>
+        </div>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}

package/src/features/email-blast/components/index.ts

@@ -0,0 +1,5 @@
+export * from "./containers/EmailBlastsListContainer";
+export * from "./containers/EmailBlastContainer";
+export * from "./lists/EmailBlastsList";
+export * from "./forms/EmailBlastEditor";
+export * from "./forms/EmailBlastSendDialog";

package/src/features/email-blast/components/lists/EmailBlastsList.tsx

@@ -0,0 +1,57 @@
+"use client";
+
+import { SendIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { ReactNode } from "react";
+import { ContentListTable } from "../../../../components";
+import { Modules } from "../../../../core";
+import { DataListRetriever, useDataListRetriever } from "../../../../hooks";
+import { EmptyState } from "../../../../shadcnui";
+import { EmailBlastFields } from "../../data/email-blast.fields";
+import { EmailBlastInterface } from "../../data/EmailBlastInterface";
+import { EmailBlastService } from "../../data/EmailBlastService";
+// Registers the "email-blasts" table generator. The blast components ship in the
+// shared ./components entry, which does not re-export feature hooks (HowToList pattern).
+import "../../hooks/useEmailBlastTableStructure";
+import EmailBlastEditor from "../forms/EmailBlastEditor";
+
+type EmailBlastsListProps = {
+  /**
+   * Pass this whenever the list is the page's own content inside a
+   * `RoundPageContainer fullWidth`. Without it ContentListTable wraps itself in
+   * `rounded-md border`, drawing a second bordered card inside the page's
+   * rounded shell.
+   */
+  fullWidth?: boolean;
+};
+
+export function EmailBlastsList({ fullWidth }: EmailBlastsListProps = {}) {
+  const t = useTranslations();
+
+  const data: DataListRetriever<EmailBlastInterface> = useDataListRetriever({
+    retriever: (params) => EmailBlastService.findMany(params),
+    retrieverParams: {},
+    module: Modules.EmailBlast,
+  });
+
+  const functions: ReactNode[] = [<EmailBlastEditor key="create-email-blast" />];
+
+  return (
+    <ContentListTable
+      data={data}
+      fields={[
+        EmailBlastFields.subject,
+        EmailBlastFields.status,
+        EmailBlastFields.sentAt,
+        EmailBlastFields.sent,
+        EmailBlastFields.failed,
+        EmailBlastFields.unsubscribed,
+      ]}
+      tableGeneratorType={Modules.EmailBlast}
+      functions={functions}
+      fullWidth={fullWidth}
+      title={t("emailBlasts.admin.title")}
+      emptyState={<EmptyState icon={SendIcon} title={t("emailBlasts.admin.empty")} />}
+    />
+  );
+}

package/src/features/email-blast/data/EmailBlast.ts

@@ -0,0 +1,89 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { EmailBlastInput, EmailBlastInterface, EmailBlastStatus } from "./EmailBlastInterface";
+
+export class EmailBlast extends AbstractApiData implements EmailBlastInterface {
+  private _subject?: string;
+  private _body?: string;
+  private _replyTo?: string;
+  private _status: EmailBlastStatus = "draft";
+  private _sentAt?: Date;
+  private _recipientCount?: number;
+  private _sentCount?: number;
+  private _failedCount?: number;
+  private _unsubscribedCount?: number;
+
+  get subject(): string {
+    return this._subject ?? "";
+  }
+
+  get body(): string {
+    return this._body ?? "";
+  }
+
+  get replyTo(): string | undefined {
+    return this._replyTo;
+  }
+
+  get status(): EmailBlastStatus {
+    return this._status;
+  }
+
+  get sentAt(): Date | undefined {
+    return this._sentAt;
+  }
+
+  get recipientCount(): number | undefined {
+    return this._recipientCount;
+  }
+
+  get sentCount(): number {
+    return this._sentCount ?? 0;
+  }
+
+  get failedCount(): number {
+    return this._failedCount ?? 0;
+  }
+
+  get unsubscribedCount(): number {
+    return this._unsubscribedCount ?? 0;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attributes = data.jsonApi.attributes;
+    this._subject = attributes.subject;
+    this._body = attributes.body;
+    this._replyTo = attributes.replyTo ?? undefined;
+    this._status = attributes.status ?? "draft";
+    this._sentAt = attributes.sentAt ? new Date(attributes.sentAt) : undefined;
+    this._recipientCount = attributes.recipientCount ?? undefined;
+    this._sentCount = attributes.sentCount;
+    this._failedCount = attributes.failedCount;
+    this._unsubscribedCount = attributes.unsubscribedCount;
+
+    return this;
+  }
+
+  /**
+   * Only the editable text travels: status, counters and sentAt are set by the API.
+   */
+  createJsonApi(data: EmailBlastInput) {
+    const response: any = {
+      data: {
+        type: Modules.EmailBlast.name,
+        id: data.id,
+        attributes: {},
+        meta: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    if (data.subject !== undefined) response.data.attributes.subject = data.subject;
+    if (data.body !== undefined) response.data.attributes.body = data.body;
+    if (data.replyTo !== undefined) response.data.attributes.replyTo = data.replyTo;
+
+    return response;
+  }
+}

package/src/features/email-blast/data/EmailBlastAudience.ts

@@ -0,0 +1,22 @@
+import { AbstractApiData, JsonApiHydratedDataInterface } from "../../../core";
+import { EmailBlastAudienceInterface } from "./EmailBlastAudienceInterface";
+
+export class EmailBlastAudience extends AbstractApiData implements EmailBlastAudienceInterface {
+  private _recipientCount?: number;
+
+  get recipientCount(): number {
+    return this._recipientCount ?? 0;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    this._recipientCount = data.jsonApi.attributes.recipientCount;
+
+    return this;
+  }
+
+  createJsonApi(_data?: any): any {
+    throw new Error("EmailBlastAudience is computed by the API and is read-only");
+  }
+}

package/src/features/email-blast/data/EmailBlastAudienceInterface.ts

@@ -0,0 +1,5 @@
+import { ApiDataInterface } from "../../../core";
+
+export interface EmailBlastAudienceInterface extends ApiDataInterface {
+  get recipientCount(): number;
+}

package/src/features/email-blast/data/EmailBlastDelivery.ts

@@ -0,0 +1,36 @@
+import { AbstractApiData, JsonApiHydratedDataInterface } from "../../../core";
+import { EmailBlastDeliveryInterface, EmailBlastDeliveryStatus } from "./EmailBlastDeliveryInterface";
+
+/** JSON:API type of the POST email-blasts/unsubscribe/:token request body (not a module: nothing is stored). */
+export const EMAIL_BLAST_UNSUBSCRIBE_TYPE = "email-blast-unsubscribes";
+
+export class EmailBlastDelivery extends AbstractApiData implements EmailBlastDeliveryInterface {
+  private _status: EmailBlastDeliveryStatus = "pending";
+
+  get status(): EmailBlastDeliveryStatus {
+    return this._status;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    this._status = data.jsonApi.attributes.status ?? "pending";
+
+    return this;
+  }
+
+  createJsonApi(_data?: any): any {
+    throw new Error("EmailBlastDelivery is created by the API and cannot be created from the client");
+  }
+
+  /**
+   * Body of POST email-blasts/unsubscribe/:token.
+   */
+  createUnsubscribeJsonApi() {
+    return {
+      data: {
+        type: EMAIL_BLAST_UNSUBSCRIBE_TYPE,
+      },
+    };
+  }
+}

package/src/features/email-blast/data/EmailBlastDeliveryInterface.ts

@@ -0,0 +1,7 @@
+import { ApiDataInterface } from "../../../core";
+
+export type EmailBlastDeliveryStatus = "pending" | "sending" | "sent" | "skipped" | "failed";
+
+export interface EmailBlastDeliveryInterface extends ApiDataInterface {
+  get status(): EmailBlastDeliveryStatus;
+}

package/src/features/email-blast/data/EmailBlastDeliveryService.ts

@@ -0,0 +1,25 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
+import { EMAIL_BLAST_SEGMENTS } from "./email-blast.segments";
+import { EmailBlastDelivery } from "./EmailBlastDelivery";
+
+export class EmailBlastDeliveryService extends AbstractService {
+  /**
+   * POST email-blasts/unsubscribe/:token (public). Replies 204: the token holder
+   * receives nothing back.
+   */
+  static async unsubscribe(params: { token: string }): Promise<void> {
+    const delivery = new EmailBlastDelivery();
+
+    await this.callApi({
+      type: Modules.EmailBlastDelivery,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.EmailBlast,
+        id: EMAIL_BLAST_SEGMENTS.unsubscribe,
+        childEndpoint: params.token,
+      }).generate(),
+      input: delivery.createUnsubscribeJsonApi(),
+      overridesJsonApiCreation: true,
+    });
+  }
+}

package/src/features/email-blast/data/EmailBlastInterface.ts

@@ -0,0 +1,22 @@
+import { ApiDataInterface } from "../../../core";
+
+export type EmailBlastStatus = "draft" | "sending" | "sent";
+
+export type EmailBlastInput = {
+  id: string;
+  subject: string;
+  body: string;
+  replyTo?: string;
+};
+
+export interface EmailBlastInterface extends ApiDataInterface {
+  get subject(): string;
+  get body(): string;
+  get replyTo(): string | undefined;
+  get status(): EmailBlastStatus;
+  get sentAt(): Date | undefined;
+  get recipientCount(): number | undefined;
+  get sentCount(): number;
+  get failedCount(): number;
+  get unsubscribedCount(): number;
+}

package/src/features/email-blast/data/EmailBlastService.ts

@@ -0,0 +1,101 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules, NextRef, PreviousRef } from "../../../core";
+import { EMAIL_BLAST_SEGMENTS } from "./email-blast.segments";
+import { EmailBlastAudienceInterface } from "./EmailBlastAudienceInterface";
+import { EmailBlastInput, EmailBlastInterface } from "./EmailBlastInterface";
+
+export class EmailBlastService extends AbstractService {
+  static async findMany(params: { next?: NextRef; previous?: PreviousRef } = {}): Promise<EmailBlastInterface[]> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.EmailBlast });
+
+    if (Modules.EmailBlast.inclusions?.lists?.fields)
+      endpoint.limitToFields(Modules.EmailBlast.inclusions.lists.fields);
+    if (Modules.EmailBlast.inclusions?.lists?.types) endpoint.limitToType(Modules.EmailBlast.inclusions.lists.types);
+
+    return this.callApi<EmailBlastInterface[]>({
+      type: Modules.EmailBlast,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+      next: params.next,
+      previous: params.previous,
+    });
+  }
+
+  static async findOne(params: { id: string }): Promise<EmailBlastInterface> {
+    return this.callApi<EmailBlastInterface>({
+      type: Modules.EmailBlast,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({ endpoint: Modules.EmailBlast, id: params.id }).generate(),
+    });
+  }
+
+  static async create(params: EmailBlastInput): Promise<EmailBlastInterface> {
+    return this.callApi<EmailBlastInterface>({
+      type: Modules.EmailBlast,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: Modules.EmailBlast }).generate(),
+      input: params,
+    });
+  }
+
+  static async update(params: EmailBlastInput): Promise<EmailBlastInterface> {
+    return this.callApi<EmailBlastInterface>({
+      type: Modules.EmailBlast,
+      method: HttpMethod.PATCH,
+      endpoint: new EndpointCreator({ endpoint: Modules.EmailBlast, id: params.id }).generate(),
+      input: params,
+    });
+  }
+
+  static async delete(params: { id: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.EmailBlast,
+      method: HttpMethod.DELETE,
+      endpoint: new EndpointCreator({ endpoint: Modules.EmailBlast, id: params.id }).generate(),
+    });
+  }
+
+  /**
+   * GET email-blasts/:id/recipient-count: how many people the blast would reach now.
+   */
+  static async findAudience(params: { id: string }): Promise<EmailBlastAudienceInterface> {
+    return this.callApi<EmailBlastAudienceInterface>({
+      type: Modules.EmailBlastAudience,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.EmailBlast,
+        id: params.id,
+        childEndpoint: EMAIL_BLAST_SEGMENTS.audience,
+      }).generate(),
+    });
+  }
+
+  /**
+   * POST email-blasts/:id/test: sends the draft to the calling administrator. Replies 204.
+   */
+  static async sendTest(params: { id: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.EmailBlast,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.EmailBlast,
+        id: params.id,
+        childEndpoint: EMAIL_BLAST_SEGMENTS.test,
+      }).generate(),
+    });
+  }
+
+  /**
+   * POST email-blasts/:id/send: starts the send and returns the blast, now `sending`.
+   */
+  static async send(params: { id: string }): Promise<EmailBlastInterface> {
+    return this.callApi<EmailBlastInterface>({
+      type: Modules.EmailBlast,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.EmailBlast,
+        id: params.id,
+        childEndpoint: EMAIL_BLAST_SEGMENTS.send,
+      }).generate(),
+    });
+  }
+}