@carlonicora/nextjs-jsonapi 5.2.0 → 5.3.0

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

@@ -0,0 +1,80 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
+import { EmailAutomationStep } from "./EmailAutomationStep";
+import { EmailAutomationStepInput, EmailAutomationStepInterface } from "./EmailAutomationStepInterface";
+
+export class EmailAutomationStepService extends AbstractService {
+  static async findByAutomation(params: { automationId: string }): Promise<EmailAutomationStepInterface[]> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.EmailAutomation,
+      id: params.automationId,
+      childEndpoint: Modules.EmailAutomationStep,
+    });
+
+    endpoint.addAdditionalParam("fetchAll", "true");
+
+    return this.callApi<EmailAutomationStepInterface[]>({
+      type: Modules.EmailAutomationStep,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+
+  static async create(params: EmailAutomationStepInput): Promise<EmailAutomationStepInterface> {
+    return this.callApi<EmailAutomationStepInterface>({
+      type: Modules.EmailAutomationStep,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: Modules.EmailAutomationStep }).generate(),
+      input: params,
+    });
+  }
+
+  static async update(params: EmailAutomationStepInput): Promise<EmailAutomationStepInterface> {
+    return this.callApi<EmailAutomationStepInterface>({
+      type: Modules.EmailAutomationStep,
+      method: HttpMethod.PATCH,
+      endpoint: new EndpointCreator({ endpoint: Modules.EmailAutomationStep, id: params.id }).generate(),
+      input: params,
+    });
+  }
+
+  static async delete(params: { id: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.EmailAutomationStep,
+      method: HttpMethod.DELETE,
+      endpoint: new EndpointCreator({ endpoint: Modules.EmailAutomationStep, id: params.id }).generate(),
+    });
+  }
+
+  /**
+   * POST email-automation-steps/:stepId/next: continues the chain from stepId to nextStepId.
+   */
+  static async setNext(params: { stepId: string; nextStepId: string }): Promise<EmailAutomationStepInterface> {
+    const step = new EmailAutomationStep();
+    return this.callApi<EmailAutomationStepInterface>({
+      type: Modules.EmailAutomationStep,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.EmailAutomationStep,
+        id: params.stepId,
+        childEndpoint: "next",
+      }).generate(),
+      input: step.createNextJsonApi({ nextStepId: params.nextStepId }),
+      overridesJsonApiCreation: true,
+    });
+  }
+
+  /**
+   * DELETE email-automation-steps/:stepId/next: the step becomes the end of the chain.
+   */
+  static async clearNext(params: { stepId: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.EmailAutomationStep,
+      method: HttpMethod.DELETE,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.EmailAutomationStep,
+        id: params.stepId,
+        childEndpoint: "next",
+      }).generate(),
+    });
+  }
+}

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

@@ -0,0 +1,28 @@
+import { AbstractApiData, JsonApiHydratedDataInterface } from "../../../core";
+import { EmailAutomationTriggerInterface } from "./EmailAutomationTriggerInterface";
+
+export class EmailAutomationTrigger extends AbstractApiData implements EmailAutomationTriggerInterface {
+  private _key?: string;
+  private _label?: string;
+
+  get key(): string {
+    return this._key ?? "";
+  }
+
+  get label(): string {
+    return this._label ?? "";
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    this._key = data.jsonApi.attributes.key;
+    this._label = data.jsonApi.attributes.label;
+
+    return this;
+  }
+
+  createJsonApi(_data?: any): any {
+    throw new Error("EmailAutomationTrigger is declared by the API and is read-only");
+  }
+}

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

@@ -0,0 +1,6 @@
+import { ApiDataInterface } from "../../../core";
+
+export interface EmailAutomationTriggerInterface extends ApiDataInterface {
+  get key(): string;
+  get label(): string;
+}

package/src/features/email-automation/data/__tests__/email-automation-models.spec.ts

@@ -0,0 +1,103 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { ModuleFactory, ModuleWithPermissions } from "../../../../permissions/types";
+import { EmailAutomationEnrollmentModule } from "../../EmailAutomationEnrollmentModule";
+import { EmailAutomationModule } from "../../EmailAutomationModule";
+import { EmailAutomationStepModule } from "../../EmailAutomationStepModule";
+import { EmailAutomationTriggerModule } from "../../EmailAutomationTriggerModule";
+import { EmailAutomation } from "../EmailAutomation";
+import { EMAIL_AUTOMATION_UNSUBSCRIBE_TYPE, EmailAutomationEnrollment } from "../EmailAutomationEnrollment";
+import { EmailAutomationStep } from "../EmailAutomationStep";
+
+// createJsonApi reads Modules.X.name (resolved lazily via ModuleRegistry), so
+// the modules must be registered before a model serialises — mirrors the
+// tokenusage-admin-models.spec setup convention in this package.
+const moduleFactory: ModuleFactory = (params) =>
+  ({
+    pageUrl: params.pageUrl,
+    name: params.name,
+    model: params.model,
+  }) as ModuleWithPermissions;
+
+beforeAll(() => {
+  ModuleRegistry.register("EmailAutomation", EmailAutomationModule(moduleFactory));
+  ModuleRegistry.register("EmailAutomationStep", EmailAutomationStepModule(moduleFactory));
+  ModuleRegistry.register("EmailAutomationEnrollment", EmailAutomationEnrollmentModule(moduleFactory));
+  ModuleRegistry.register("EmailAutomationTrigger", EmailAutomationTriggerModule(moduleFactory));
+});
+
+const hydrate = (attributes: Record<string, unknown>) =>
+  ({ jsonApi: { id: "x", type: "t", attributes }, included: [] }) as any;
+
+describe("email automation models", () => {
+  it("parses the enrollment datetimes into Date, not the wire string", () => {
+    const m = new EmailAutomationEnrollment().rehydrate(
+      hydrate({
+        email: "ada@example.com",
+        status: "active",
+        enrolledAt: "2026-10-21T08:00:00.000Z",
+        nextSendAt: "2026-10-22T08:00:00.000Z",
+        attempts: 0,
+      }),
+    );
+    expect(m.enrolledAt).toBeInstanceOf(Date);
+    expect(m.enrolledAt.toISOString()).toBe("2026-10-21T08:00:00.000Z");
+    expect(m.nextSendAt).toBeInstanceOf(Date);
+    expect(m.nextSendAt?.toISOString()).toBe("2026-10-22T08:00:00.000Z");
+    expect(m.finishedAt).toBeUndefined();
+  });
+
+  it("reads the enrollment computed fields from attributes", () => {
+    const m = new EmailAutomationEnrollment().rehydrate(
+      hydrate({
+        email: "ada@example.com",
+        status: "active",
+        enrolledAt: "2026-10-21T08:00:00.000Z",
+        currentStepSubject: "Welcome aboard",
+        sentCount: 2,
+      }),
+    );
+    expect(m.currentStepSubject).toBe("Welcome aboard");
+    expect(m.sentCount).toBe(2);
+  });
+
+  it("omits undefined automation attributes and includes isActive when given", () => {
+    const body = new EmailAutomation().createJsonApi({ id: "a1", name: "Onboarding", isActive: true });
+    expect(body.data.type).toBe("email-automations");
+    expect(body.data.id).toBe("a1");
+    expect(body.data.attributes).toEqual({ name: "Onboarding", isActive: true });
+    expect("trigger" in body.data.attributes).toBe(false);
+    expect("exitTrigger" in body.data.attributes).toBe(false);
+    expect("replyTo" in body.data.attributes).toBe(false);
+  });
+
+  it("includes isActive false when given", () => {
+    const body = new EmailAutomation().createJsonApi({ id: "a1", name: "Onboarding", isActive: false });
+    expect(body.data.attributes.isActive).toBe(false);
+  });
+
+  it("writes the step's automation relationship", () => {
+    const body = new EmailAutomationStep().createJsonApi({
+      id: "s1",
+      automationId: "a1",
+      subject: "Hello",
+      body: "Hi {{name}}",
+      delayHours: 24,
+    });
+    expect(body.data.type).toBe("email-automation-steps");
+    expect(body.data.attributes).toEqual({ subject: "Hello", body: "Hi {{name}}", delayHours: 24 });
+    expect(body.data.relationships.automation).toEqual({ data: { type: "email-automations", id: "a1" } });
+  });
+
+  it("builds the next-step body", () => {
+    expect(new EmailAutomationStep().createNextJsonApi({ nextStepId: "s2" })).toEqual({
+      data: { type: "email-automation-steps", id: "s2" },
+    });
+  });
+
+  it("builds the unsubscribe body", () => {
+    expect(new EmailAutomationEnrollment().createUnsubscribeJsonApi({ scope: "all" })).toEqual({
+      data: { type: EMAIL_AUTOMATION_UNSUBSCRIBE_TYPE, attributes: { scope: "all" } },
+    });
+  });
+});

package/src/features/email-automation/data/email-automation-enrollment.fields.ts

@@ -0,0 +1,8 @@
+export enum EmailAutomationEnrollmentFields {
+  email = "email",
+  name = "name",
+  status = "status",
+  currentStep = "currentStep",
+  nextSendAt = "nextSendAt",
+  sentCount = "sentCount",
+}

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

@@ -0,0 +1,9 @@
+export enum EmailAutomationFields {
+  name = "name",
+  trigger = "trigger",
+  status = "status",
+  steps = "steps",
+  active = "active",
+  completed = "completed",
+  unsubscribed = "unsubscribed",
+}

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

@@ -0,0 +1,13 @@
+export * from "./EmailAutomationInterface";
+export * from "./EmailAutomation";
+export * from "./EmailAutomationService";
+export * from "./EmailAutomationStepInterface";
+export * from "./EmailAutomationStep";
+export * from "./EmailAutomationStepService";
+export * from "./EmailAutomationEnrollmentInterface";
+export * from "./EmailAutomationEnrollment";
+export * from "./EmailAutomationEnrollmentService";
+export * from "./EmailAutomationTriggerInterface";
+export * from "./EmailAutomationTrigger";
+export * from "./email-automation.fields";
+export * from "./email-automation-enrollment.fields";

package/src/features/email-automation/hooks/index.ts

@@ -0,0 +1,2 @@
+export * from "./useEmailAutomationTableStructure";
+export * from "./useEmailAutomationEnrollmentTableStructure";

package/src/features/email-automation/hooks/useEmailAutomationEnrollmentTableStructure.tsx

@@ -0,0 +1,126 @@
+"use client";
+
+import { ColumnDef } from "@tanstack/react-table";
+import { useLocale, useTranslations } from "next-intl";
+import { useMemo } from "react";
+import { Badge } from "../../../shadcnui";
+import { registerTableGenerator, TableContent, UseTableStructureHook } from "../../../hooks";
+import { dateFormatLocale, formatDate } from "../../../utils/date-formatter";
+import { EmailAutomationEnrollmentFields } from "../data/email-automation-enrollment.fields";
+import { EmailAutomationEnrollmentInterface } from "../data/EmailAutomationEnrollmentInterface";
+
+const STATUS_VARIANTS: Record<string, "softGreen" | "softBlue" | "softGray" | "softRed"> = {
+  active: "softGreen",
+  completed: "softBlue",
+  unsubscribed: "softGray",
+  exited: "softGray",
+  failed: "softRed",
+};
+
+export const useEmailAutomationEnrollmentTableStructure: UseTableStructureHook<
+  EmailAutomationEnrollmentInterface,
+  EmailAutomationEnrollmentFields
+> = (params) => {
+  const t = useTranslations();
+  const locale = dateFormatLocale(useLocale());
+
+  const tableData = useMemo(() => {
+    return params.data.map((enrollment: EmailAutomationEnrollmentInterface) => {
+      const entry: TableContent<EmailAutomationEnrollmentInterface> = { jsonApiData: enrollment };
+      params.fields.forEach((field) => {
+        entry[field] = (enrollment as any)[field as keyof EmailAutomationEnrollmentInterface];
+      });
+      return entry;
+    });
+  }, [params.data, params.fields]);
+
+  const empty = <span className="text-muted-foreground text-xs">—</span>;
+
+  const fieldColumnMap: Partial<Record<EmailAutomationEnrollmentFields, () => any>> = {
+    [EmailAutomationEnrollmentFields.email]: () => ({
+      id: "email",
+      accessorKey: "email",
+      header: t("emailAutomations.recipients.columns.email"),
+      cell: ({ row }: { row: TableContent<EmailAutomationEnrollmentInterface> }) => {
+        const enrollment: EmailAutomationEnrollmentInterface = row.original.jsonApiData;
+        return <span className="text-sm">{enrollment.email}</span>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [EmailAutomationEnrollmentFields.name]: () => ({
+      id: "name",
+      accessorKey: "name",
+      header: t("emailAutomations.recipients.columns.name"),
+      cell: ({ row }: { row: TableContent<EmailAutomationEnrollmentInterface> }) => {
+        const enrollment: EmailAutomationEnrollmentInterface = row.original.jsonApiData;
+        return enrollment.name ? <span className="text-sm">{enrollment.name}</span> : empty;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [EmailAutomationEnrollmentFields.status]: () => ({
+      id: "status",
+      accessorKey: "status",
+      header: t("emailAutomations.recipients.columns.status"),
+      cell: ({ row }: { row: TableContent<EmailAutomationEnrollmentInterface> }) => {
+        const enrollment: EmailAutomationEnrollmentInterface = row.original.jsonApiData;
+        return (
+          <Badge
+            variant={STATUS_VARIANTS[enrollment.status] ?? "softGray"}
+            title={enrollment.status === "failed" ? enrollment.lastError : undefined}
+          >
+            {t(`emailAutomations.recipients.status.${enrollment.status}`)}
+          </Badge>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [EmailAutomationEnrollmentFields.currentStep]: () => ({
+      id: "currentStep",
+      accessorKey: "currentStep",
+      header: t("emailAutomations.recipients.columns.currentStep"),
+      cell: ({ row }: { row: TableContent<EmailAutomationEnrollmentInterface> }) => {
+        const enrollment: EmailAutomationEnrollmentInterface = row.original.jsonApiData;
+        return enrollment.currentStepSubject ? <span className="text-sm">{enrollment.currentStepSubject}</span> : empty;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [EmailAutomationEnrollmentFields.nextSendAt]: () => ({
+      id: "nextSendAt",
+      accessorKey: "nextSendAt",
+      header: t("emailAutomations.recipients.columns.nextSendAt"),
+      cell: ({ row }: { row: TableContent<EmailAutomationEnrollmentInterface> }) => {
+        const enrollment: EmailAutomationEnrollmentInterface = row.original.jsonApiData;
+        if (!enrollment.nextSendAt) return empty;
+        return <span className="text-xs tabular-nums">{formatDate(enrollment.nextSendAt, "dateTime", locale)}</span>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [EmailAutomationEnrollmentFields.sentCount]: () => ({
+      id: "sentCount",
+      accessorKey: "sentCount",
+      header: t("emailAutomations.recipients.columns.sentCount"),
+      cell: ({ row }: { row: TableContent<EmailAutomationEnrollmentInterface> }) => {
+        const enrollment: EmailAutomationEnrollmentInterface = row.original.jsonApiData;
+        // Typography role 15 (numeric): tabular-nums, end-aligned.
+        return <span className="block text-xs tabular-nums text-end">{enrollment.sentCount ?? 0}</span>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+  };
+
+  const columns = useMemo(() => {
+    return params.fields.map((field) => fieldColumnMap[field]?.()).filter((col) => col !== undefined) as ColumnDef<
+      TableContent<EmailAutomationEnrollmentInterface>
+    >[];
+  }, [params.fields, fieldColumnMap, t, locale]);
+
+  return useMemo(() => ({ data: tableData, columns: columns }), [tableData, columns]);
+};
+
+registerTableGenerator("email-automation-enrollments", useEmailAutomationEnrollmentTableStructure);

package/src/features/email-automation/hooks/useEmailAutomationTableStructure.tsx

@@ -0,0 +1,119 @@
+"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 { EmailAutomationFields } from "../data/email-automation.fields";
+import { EmailAutomationInterface } from "../data/EmailAutomationInterface";
+
+/**
+ * `context.triggerLabels` maps a trigger key to the label the API declares for
+ * it (EmailAutomationsList loads them). A key the app no longer declares falls
+ * back to the raw key, so a stale automation stays readable.
+ */
+export const useEmailAutomationTableStructure: UseTableStructureHook<
+  EmailAutomationInterface,
+  EmailAutomationFields
+> = (params) => {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+  const triggerLabels: Record<string, string> = params.context?.triggerLabels ?? {};
+
+  const tableData = useMemo(() => {
+    return params.data.map((automation: EmailAutomationInterface) => {
+      const entry: TableContent<EmailAutomationInterface> = { jsonApiData: automation };
+      params.fields.forEach((field) => {
+        entry[field] = (automation as any)[field as keyof EmailAutomationInterface];
+      });
+      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: EmailAutomationFields,
+    header: string,
+    read: (a: EmailAutomationInterface) => number,
+  ) => ({
+    id: field,
+    accessorKey: field,
+    header: header,
+    cell: ({ row }: { row: TableContent<EmailAutomationInterface> }) => {
+      const automation: EmailAutomationInterface = row.original.jsonApiData;
+      return <span className="block text-xs tabular-nums text-end">{read(automation) ?? 0}</span>;
+    },
+    enableSorting: false,
+    enableHiding: false,
+  });
+
+  const fieldColumnMap: Partial<Record<EmailAutomationFields, () => any>> = {
+    [EmailAutomationFields.name]: () => ({
+      id: "name",
+      accessorKey: "name",
+      header: t("emailAutomations.list.columns.name"),
+      cell: ({ row }: { row: TableContent<EmailAutomationInterface> }) => {
+        const automation: EmailAutomationInterface = row.original.jsonApiData;
+        return <Link href={generateUrl({ page: Modules.EmailAutomation, id: automation.id })}>{automation.name}</Link>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [EmailAutomationFields.trigger]: () => ({
+      id: "trigger",
+      accessorKey: "trigger",
+      header: t("emailAutomations.list.columns.trigger"),
+      cell: ({ row }: { row: TableContent<EmailAutomationInterface> }) => {
+        const automation: EmailAutomationInterface = row.original.jsonApiData;
+        if (!automation.trigger) return <span className="text-muted-foreground text-xs">—</span>;
+        return <span className="text-sm">{triggerLabels[automation.trigger] ?? automation.trigger}</span>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [EmailAutomationFields.status]: () => ({
+      id: "status",
+      accessorKey: "status",
+      header: t("emailAutomations.list.columns.status"),
+      cell: ({ row }: { row: TableContent<EmailAutomationInterface> }) => {
+        const automation: EmailAutomationInterface = row.original.jsonApiData;
+        return automation.isActive ? (
+          <Badge variant="softGreen">{t("emailAutomations.list.status.on")}</Badge>
+        ) : (
+          <Badge variant="softGray">{t("emailAutomations.list.status.off")}</Badge>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [EmailAutomationFields.steps]: () =>
+      numericColumn(EmailAutomationFields.steps, t("emailAutomations.list.columns.steps"), (a) => a.stepCount),
+    [EmailAutomationFields.active]: () =>
+      numericColumn(EmailAutomationFields.active, t("emailAutomations.list.columns.active"), (a) => a.activeCount),
+    [EmailAutomationFields.completed]: () =>
+      numericColumn(
+        EmailAutomationFields.completed,
+        t("emailAutomations.list.columns.completed"),
+        (a) => a.completedCount,
+      ),
+    [EmailAutomationFields.unsubscribed]: () =>
+      numericColumn(
+        EmailAutomationFields.unsubscribed,
+        t("emailAutomations.list.columns.unsubscribed"),
+        (a) => a.unsubscribedCount,
+      ),
+  };
+
+  const columns = useMemo(() => {
+    return params.fields.map((field) => fieldColumnMap[field]?.()).filter((col) => col !== undefined) as ColumnDef<
+      TableContent<EmailAutomationInterface>
+    >[];
+  }, [params.fields, fieldColumnMap, t, generateUrl]);
+
+  return useMemo(() => ({ data: tableData, columns: columns }), [tableData, columns]);
+};
+
+registerTableGenerator("email-automations", useEmailAutomationTableStructure);

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

@@ -0,0 +1,5 @@
+export * from "./EmailAutomationModule";
+export * from "./EmailAutomationStepModule";
+export * from "./EmailAutomationEnrollmentModule";
+export * from "./EmailAutomationTriggerModule";
+export * from "./data";