@carlonicora/nextjs-jsonapi 6.8.0 → 6.9.0

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";