@carlonicora/nextjs-jsonapi 6.8.0 → 6.10.0

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(),
+    });
+  }
+}

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

@@ -0,0 +1,73 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { ModuleFactory, ModuleWithPermissions } from "../../../../permissions/types";
+import { EmailBlastAudienceModule } from "../../EmailBlastAudienceModule";
+import { EmailBlastDeliveryModule } from "../../EmailBlastDeliveryModule";
+import { EmailBlastModule } from "../../EmailBlastModule";
+import { EmailBlast } from "../EmailBlast";
+import { EmailBlastAudience } from "../EmailBlastAudience";
+
+// createJsonApi reads Modules.X.name (resolved lazily via ModuleRegistry), so
+// the modules must be registered before a model serialises — same setup as
+// email-automation-models.spec.
+const moduleFactory: ModuleFactory = (params) =>
+  ({
+    pageUrl: params.pageUrl,
+    name: params.name,
+    model: params.model,
+  }) as ModuleWithPermissions;
+
+beforeAll(() => {
+  ModuleRegistry.register("EmailBlast", EmailBlastModule(moduleFactory));
+  ModuleRegistry.register("EmailBlastDelivery", EmailBlastDeliveryModule(moduleFactory));
+  ModuleRegistry.register("EmailBlastAudience", EmailBlastAudienceModule(moduleFactory));
+});
+
+const hydrate = (attributes: Record<string, unknown>) =>
+  ({ jsonApi: { id: "x", type: "t", attributes }, included: [] }) as any;
+
+describe("email blast models", () => {
+  it("rehydrate parses sentAt to a Date and defaults counters to 0", () => {
+    const sent = new EmailBlast().rehydrate(
+      hydrate({
+        subject: "News",
+        body: "Hello",
+        status: "sent",
+        sentAt: "2026-10-27T08:00:00.000Z",
+        recipientCount: 12,
+      }),
+    );
+    expect(sent.sentAt).toBeInstanceOf(Date);
+    expect(sent.sentAt?.toISOString()).toBe("2026-10-27T08:00:00.000Z");
+    expect(sent.recipientCount).toBe(12);
+    expect(sent.status).toBe("sent");
+    expect(sent.sentCount).toBe(0);
+    expect(sent.failedCount).toBe(0);
+    expect(sent.unsubscribedCount).toBe(0);
+
+    const draft = new EmailBlast().rehydrate(hydrate({ subject: "News", body: "Hello" }));
+    expect(draft.sentAt).toBeUndefined();
+    expect(draft.recipientCount).toBeUndefined();
+    expect(draft.replyTo).toBeUndefined();
+    expect(draft.status).toBe("draft");
+  });
+
+  it("createJsonApi emits only subject, body and replyTo", () => {
+    const body = new EmailBlast().createJsonApi({
+      id: "b1",
+      subject: "News",
+      body: "Hello",
+      replyTo: "gm@example.com",
+      ...({ status: "sent", sentCount: 3, failedCount: 1, unsubscribedCount: 1, sentAt: new Date() } as object),
+    });
+    expect(body.data.type).toBe("email-blasts");
+    expect(body.data.id).toBe("b1");
+    expect(body.data.attributes).toEqual({ subject: "News", body: "Hello", replyTo: "gm@example.com" });
+  });
+
+  it("EmailBlastAudience rehydrates recipientCount", () => {
+    const audience = new EmailBlastAudience().rehydrate(hydrate({ recipientCount: 42 }));
+    expect(audience.recipientCount).toBe(42);
+    expect(new EmailBlastAudience().rehydrate(hydrate({})).recipientCount).toBe(0);
+  });
+});

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

@@ -0,0 +1,8 @@
+export enum EmailBlastFields {
+  subject = "subject",
+  status = "status",
+  sentAt = "sentAt",
+  sent = "sent",
+  failed = "failed",
+  unsubscribed = "unsubscribed",
+}

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

@@ -0,0 +1,10 @@
+/**
+ * URL segments of the email-blast child routes. The only place these strings
+ * are written: services build every child URL from here through EndpointCreator.
+ */
+export const EMAIL_BLAST_SEGMENTS = {
+  audience: "recipient-count",
+  test: "test",
+  send: "send",
+  unsubscribe: "unsubscribe",
+} as const;

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

@@ -0,0 +1,10 @@
+export * from "./email-blast.segments";
+export * from "./EmailBlastInterface";
+export * from "./EmailBlast";
+export * from "./EmailBlastService";
+export * from "./EmailBlastDeliveryInterface";
+export * from "./EmailBlastDelivery";
+export * from "./EmailBlastDeliveryService";
+export * from "./EmailBlastAudienceInterface";
+export * from "./EmailBlastAudience";
+export * from "./email-blast.fields";

package/src/features/email-blast/hooks/useEmailBlastTableStructure.tsx

@@ -0,0 +1,104 @@
+"use client";
+
+import { ColumnDef } from "@tanstack/react-table";
+import { useTranslations } from "next-intl";
+import { useMemo } from "react";
+import { Badge, Link } from "../../../shadcnui";
+import { Modules } from "../../../core";
+import { registerTableGenerator, TableContent, usePageUrlGenerator, UseTableStructureHook } from "../../../hooks";
+import { useI18nLocale } from "../../../i18n";
+import { EmailBlastFields } from "../data/email-blast.fields";
+import { EmailBlastInterface, EmailBlastStatus } from "../data/EmailBlastInterface";
+
+const STATUS_VARIANTS: Record<EmailBlastStatus, "softGray" | "softAmber" | "softGreen"> = {
+  draft: "softGray",
+  sending: "softAmber",
+  sent: "softGreen",
+};
+
+export const useEmailBlastTableStructure: UseTableStructureHook<EmailBlastInterface, EmailBlastFields> = (params) => {
+  const t = useTranslations();
+  const locale = useI18nLocale();
+  const generateUrl = usePageUrlGenerator();
+
+  const tableData = useMemo(() => {
+    return params.data.map((blast: EmailBlastInterface) => {
+      const entry: TableContent<EmailBlastInterface> = { jsonApiData: blast };
+      params.fields.forEach((field) => {
+        entry[field] = (blast as any)[field as keyof EmailBlastInterface];
+      });
+      return entry;
+    });
+  }, [params.data, params.fields]);
+
+  // Typography role 15 (numeric): tabular-nums, end-aligned. NEVER
+  // font-mono — no monospace font is loaded in these apps.
+  const numericColumn = (field: EmailBlastFields, header: string, read: (b: EmailBlastInterface) => number) => ({
+    id: field,
+    accessorKey: field,
+    header: header,
+    cell: ({ row }: { row: TableContent<EmailBlastInterface> }) => {
+      const blast: EmailBlastInterface = row.original.jsonApiData;
+      return <span className="block text-xs tabular-nums text-end">{read(blast) ?? 0}</span>;
+    },
+    enableSorting: false,
+    enableHiding: false,
+  });
+
+  const fieldColumnMap: Partial<Record<EmailBlastFields, () => any>> = {
+    [EmailBlastFields.subject]: () => ({
+      id: "subject",
+      accessorKey: "subject",
+      header: t("emailBlasts.list.columns.subject"),
+      cell: ({ row }: { row: TableContent<EmailBlastInterface> }) => {
+        const blast: EmailBlastInterface = row.original.jsonApiData;
+        return <Link href={generateUrl({ page: Modules.EmailBlast, id: blast.id })}>{blast.subject}</Link>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [EmailBlastFields.status]: () => ({
+      id: "status",
+      accessorKey: "status",
+      header: t("emailBlasts.list.columns.status"),
+      cell: ({ row }: { row: TableContent<EmailBlastInterface> }) => {
+        const blast: EmailBlastInterface = row.original.jsonApiData;
+        return <Badge variant={STATUS_VARIANTS[blast.status]}>{t(`emailBlasts.list.status.${blast.status}`)}</Badge>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [EmailBlastFields.sentAt]: () => ({
+      id: "sentAt",
+      accessorKey: "sentAt",
+      header: t("emailBlasts.list.columns.sentAt"),
+      cell: ({ row }: { row: TableContent<EmailBlastInterface> }) => {
+        const blast: EmailBlastInterface = row.original.jsonApiData;
+        if (!blast.sentAt) return <span className="text-muted-foreground text-xs">—</span>;
+        return <span className="text-sm">{blast.sentAt.toLocaleDateString(locale)}</span>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [EmailBlastFields.sent]: () =>
+      numericColumn(EmailBlastFields.sent, t("emailBlasts.list.columns.sent"), (b) => b.sentCount),
+    [EmailBlastFields.failed]: () =>
+      numericColumn(EmailBlastFields.failed, t("emailBlasts.list.columns.failed"), (b) => b.failedCount),
+    [EmailBlastFields.unsubscribed]: () =>
+      numericColumn(
+        EmailBlastFields.unsubscribed,
+        t("emailBlasts.list.columns.unsubscribed"),
+        (b) => b.unsubscribedCount,
+      ),
+  };
+
+  const columns = useMemo(() => {
+    return params.fields.map((field) => fieldColumnMap[field]?.()).filter((col) => col !== undefined) as ColumnDef<
+      TableContent<EmailBlastInterface>
+    >[];
+  }, [params.fields, fieldColumnMap, t, generateUrl, locale]);
+
+  return useMemo(() => ({ data: tableData, columns: columns }), [tableData, columns]);
+};
+
+registerTableGenerator("email-blasts", useEmailBlastTableStructure);

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

@@ -0,0 +1,4 @@
+export * from "./EmailBlastModule";
+export * from "./EmailBlastDeliveryModule";
+export * from "./EmailBlastAudienceModule";
+export * from "./data";

package/src/features/index.ts

@@ -12,6 +12,7 @@ export * from "./billing/stripe-usage";
 export * from "./billing/stripe-promotion-code";
 export * from "./company";
 export * from "./content";
+export * from "./email-blast";
 export * from "./feature";
 export * from "./module";
 export * from "./notification";