@antelopejs/dms-mailing 0.2.2

package/src/pages/overview.ts

@@ -0,0 +1,175 @@
+import { PageController, RegisterPage } from "@antelopejs/interface-dms/page";
+import {
+  ChartArea,
+  ChartCard,
+  Grid,
+  GridRow,
+  KpiCard,
+  type KpiCardProps,
+  PeriodSelector,
+  TopListCard,
+} from "@antelopejs/interface-dms/base";
+import { CustomComponent } from "@antelopejs/interface-dms/base/custom";
+import { DefaultLayout } from "@antelopejs/interface-dms/base/layouts";
+import {
+  API_BASE_PATH,
+  MAILING_ACCESS_PERMISSION,
+  MAILING_SENDS_TOPIC,
+  MODULE_ID,
+  OVERVIEW_PERIOD_SCOPE,
+} from "../constants";
+import { BUSINESS_AUDIENCE, SEND_AUDIENCE_QUERY_KEY } from "../types";
+import "./module";
+
+const OVERVIEW_ORDER = 0;
+const GRID_GAP = "1rem";
+const CHART_HEIGHT = "260px";
+
+const kpi = (
+  id: string,
+  title: string,
+  icon: string,
+  extra: Partial<KpiCardProps> = {},
+) =>
+  KpiCard({
+    title,
+    icon,
+    fetchUrl: `${API_BASE_PATH}/metrics/kpi/${id}?${SEND_AUDIENCE_QUERY_KEY}=${BUSINESS_AUDIENCE}`,
+    periodScope: OVERVIEW_PERIOD_SCOPE,
+    valueFormat: "compact",
+    showSparkline: true,
+    ...extra,
+  });
+
+@RegisterPage()
+export class OverviewPageController extends PageController(
+  "overview",
+  {
+    displayName: "$dms_mailing.overview.title",
+    description: "$dms_mailing.overview.description",
+    icon: "i-ph-chart-pie-slice",
+    module: MODULE_ID,
+    order: OVERVIEW_ORDER,
+    permission: { id: MAILING_ACCESS_PERMISSION },
+  },
+  DefaultLayout({ fullWidth: true }),
+) {
+  static period = PeriodSelector({
+    id: OVERVIEW_PERIOD_SCOPE,
+    variant: "segmented",
+    presets: ["last-7-days", "last-30-days", "last-90-days"],
+    defaultPreset: "last-30-days",
+    defaultComparison: "previous-period",
+    align: "right",
+  });
+
+  static kpis = Grid({ gap: GRID_GAP }).child(
+    "row",
+    GridRow()
+      .child(
+        "sends",
+        kpi("sends", "$dms_mailing.metrics.sends", "i-ph-paper-plane-tilt"),
+      )
+      .child(
+        "deliverability",
+        kpi(
+          "deliverability",
+          "$dms_mailing.metrics.deliverability",
+          "i-ph-check-circle",
+          { valueFormat: "percent" },
+        ),
+      )
+      .child(
+        "open-rate",
+        kpi(
+          "open-rate",
+          "$dms_mailing.metrics.open_rate",
+          "i-ph-envelope-open",
+          { valueFormat: "percent" },
+        ),
+      )
+      .child(
+        "click-rate",
+        kpi(
+          "click-rate",
+          "$dms_mailing.metrics.click_rate",
+          "i-ph-cursor-click",
+          { valueFormat: "percent" },
+        ),
+      )
+      .child(
+        "bounces",
+        kpi("bounces", "$dms_mailing.metrics.bounces", "i-ph-arrow-u-up-left", {
+          invert: true,
+        }),
+      )
+      .child(
+        "unsubscribes",
+        kpi(
+          "unsubscribes",
+          "$dms_mailing.metrics.unsubscribes",
+          "i-ph-user-minus",
+          { invert: true },
+        ),
+      ),
+  );
+
+  static row2 = Grid({ gap: GRID_GAP }).child(
+    "row",
+    GridRow()
+      .child(
+        "volume",
+        ChartCard({
+          title: "$dms_mailing.metrics.volume",
+          // The legend is the one series label the DMS translates: it runs
+          // `primaryLabel`/`comparisonLabel` through `processI18n`, while the
+          // `name` carried by each series goes to ApexCharts verbatim.
+          primaryLabel: "$dms_mailing.metrics.sends",
+          comparisonLabel: "$dms_mailing.metrics.previous",
+          fetchUrl: `${API_BASE_PATH}/metrics/volume`,
+          periodScope: OVERVIEW_PERIOD_SCOPE,
+          chart: ChartArea({
+            height: CHART_HEIGHT,
+            xaxisType: "datetime",
+            smooth: true,
+            showGrid: true,
+            realtimeTopic: MAILING_SENDS_TOPIC,
+          }),
+        }),
+      )
+      .child("attention", CustomComponent("DmsMailingAttentionCard")),
+  );
+
+  static row3 = Grid({ gap: GRID_GAP }).child(
+    "row",
+    GridRow()
+      .child(
+        "ranking",
+        TopListCard({
+          title: "$dms_mailing.metrics.ranking",
+          fetchUrl: `${API_BASE_PATH}/metrics/top-templates?metric=open-rate`,
+          periodScope: OVERVIEW_PERIOD_SCOPE,
+          valueFormat: "percent",
+          showRank: true,
+        }),
+      )
+      .child("funnel", CustomComponent("DmsMailingFunnelCard")),
+  );
+
+  static row4 = Grid({ gap: GRID_GAP }).child(
+    "row",
+    GridRow().child(
+      "domains",
+      TopListCard({
+        title: "$dms_mailing.metrics.domains",
+        // On the card, not on each row: `TopListRow` renders `item.description`
+        // verbatim, so a `$` key would show up raw.
+        description: "$dms_mailing.metrics.domain_sends",
+        fetchUrl: `${API_BASE_PATH}/metrics/domains`,
+        periodScope: OVERVIEW_PERIOD_SCOPE,
+        valueFormat: "percent",
+        showRank: false,
+      }),
+    ),
+  );
+}

package/src/pages/sends.ts

@@ -0,0 +1,174 @@
+import { PageController, RegisterPage } from "@antelopejs/interface-dms/page";
+import {
+  Grid,
+  GridRow,
+  KpiCard,
+  type KpiCardProps,
+  PeriodSelector,
+  type TableViewTab,
+} from "@antelopejs/interface-dms/base";
+import { CustomComponent } from "@antelopejs/interface-dms/base/custom";
+import { DefaultLayout } from "@antelopejs/interface-dms/base/layouts";
+import { TableView } from "@antelopejs/interface-dms/base/table-view";
+import {
+  API_BASE_PATH,
+  MAILING_ACCESS_PERMISSION,
+  MODULE_ID,
+  SENDS_PERIOD_SCOPE,
+} from "../constants";
+import { SendsTableAPI } from "../data/sends-table";
+import {
+  OPERATIONAL_AUDIENCE,
+  PROBLEM_STATUSES,
+  SEND_AUDIENCE_QUERY_KEY,
+  SEND_STATUSES,
+} from "../types";
+import "./module";
+
+const SENDS_ORDER = 3;
+const GRID_GAP = "1rem";
+
+const kpi = (
+  id: string,
+  title: string,
+  icon: string,
+  extra: Partial<KpiCardProps> = {},
+) =>
+  KpiCard({
+    title,
+    icon,
+    fetchUrl: `${API_BASE_PATH}/metrics/kpi/${id}?${SEND_AUDIENCE_QUERY_KEY}=${OPERATIONAL_AUDIENCE}`,
+    periodScope: SENDS_PERIOD_SCOPE,
+    valueFormat: "compact",
+    ...extra,
+  });
+
+const statusTab = (status: string): TableViewTab => ({
+  id: status,
+  label: `$dms_mailing.sends.status.${status}`,
+  filters: [{ accessorKey: "status", value: status, mode: "is" }],
+});
+
+@RegisterPage()
+export class SendsPageController extends PageController(
+  "sends",
+  {
+    displayName: "$dms_mailing.sends.title",
+    description: "$dms_mailing.sends.description",
+    icon: "i-ph-paper-plane-tilt",
+    module: MODULE_ID,
+    order: SENDS_ORDER,
+    permission: { id: MAILING_ACCESS_PERMISSION },
+  },
+  DefaultLayout({ fullWidth: true }),
+) {
+  static provider = CustomComponent("DmsMailingProviderChip");
+
+  static period = PeriodSelector({
+    id: SENDS_PERIOD_SCOPE,
+    variant: "segmented",
+    presets: ["last-24h", "last-7-days", "last-30-days"],
+    defaultPreset: "last-24h",
+    align: "right",
+  });
+
+  static kpis = Grid({ gap: GRID_GAP }).child(
+    "row",
+    GridRow()
+      .child(
+        "sends",
+        kpi("sends", "$dms_mailing.metrics.sends", "i-ph-paper-plane-tilt"),
+      )
+      .child(
+        "deliverability",
+        kpi(
+          "deliverability",
+          "$dms_mailing.metrics.deliverability",
+          "i-ph-check-circle",
+          { valueFormat: "percent" },
+        ),
+      )
+      .child(
+        "bounces",
+        kpi("bounces", "$dms_mailing.metrics.bounces", "i-ph-arrow-u-up-left", {
+          invert: true,
+        }),
+      )
+      .child(
+        "queued",
+        kpi("queued", "$dms_mailing.metrics.queued", "i-ph-clock", {
+          showDelta: false,
+        }),
+      )
+      .child(
+        "latency",
+        kpi("latency", "$dms_mailing.metrics.latency", "i-ph-timer", {
+          valueFormat: "number",
+          invert: true,
+        }),
+      ),
+  );
+
+  static table = TableView(SendsTableAPI, {
+    caption: "$dms_mailing.sends.title",
+    labelKey: "recipientEmail",
+    rowIdKey: "_id",
+    defaultSort: { field: "createdAt", desc: true },
+    tabs: [
+      {
+        id: "problems",
+        label: "$dms_mailing.sends.tabs.problems",
+        icon: "i-ph-warning",
+        filters: [
+          {
+            accessorKey: "status",
+            value: PROBLEM_STATUSES.join(","),
+            mode: "is",
+          },
+        ],
+      },
+      ...SEND_STATUSES.map(statusTab),
+    ],
+    rowActions: {
+      add: false,
+      edit: false,
+      duplicate: false,
+      delete: false,
+      copyLink: false,
+      details: false,
+      hasSelection: false,
+      custom: [
+        {
+          label: "$dms_mailing.templates.actions.details",
+          icon: "i-ph-info",
+          // A send is an append-only record: it cannot be edited, so the
+          // built-in `edit`/`details` row click has nothing to open. Flagging
+          // this action gives the row back its hover affordance and opens the
+          // module's own drawer on double-click, which requires a DMS that
+          // honours `isDefault` on a custom row action.
+          isDefault: true,
+          target: {
+            type: "drawer",
+            component: CustomComponent("DmsMailingSendDrawer"),
+            title: "$dms_mailing.templates.actions.details",
+          },
+        },
+        {
+          label: "$dms_mailing.sends.drawer.replay",
+          icon: "i-ph-arrow-clockwise",
+          target: {
+            type: "api",
+            url: `${API_BASE_PATH}/sends/{_id}/replay`,
+            method: "POST",
+            successMessage: "$dms_mailing.sends.drawer.replayed",
+            confirm: {
+              title: "$dms_mailing.sends.confirm.replay_title",
+              description: "$dms_mailing.sends.confirm.replay_description",
+              confirmColor: "primary",
+            },
+          },
+        },
+      ],
+    },
+  });
+}

package/src/pages/settings/form.ts

@@ -0,0 +1,67 @@
+import { Form } from "@antelopejs/interface-dms/base";
+import { DefaultDataTypes } from "@antelopejs/interface-dms/base/data-types/default-types";
+import { HttpMethod } from "@antelopejs/interface-dms/base/types";
+import { API_BASE_PATH } from "../../constants";
+import { TemplateCategoriesType } from "../../data-types";
+
+const MIN_RETENTION_DAYS = 1;
+const MAX_RETENTION_DAYS = 3650;
+const RETENTION_STEP = 1;
+const SETTINGS_URL = `${API_BASE_PATH}/settings`;
+
+const label = (id: string): string => `$dms_mailing.settings.fields.${id}`;
+
+export const mailingSettingsForm = Form({
+  fields: [
+    {
+      id: "fallbackLocale",
+      label: label("fallbackLocale"),
+      type: new DefaultDataTypes.StringType({}),
+      required: true,
+    },
+    {
+      id: "logRetentionDays",
+      label: label("logRetentionDays"),
+      type: new DefaultDataTypes.NumberType({
+        min: MIN_RETENTION_DAYS,
+        max: MAX_RETENTION_DAYS,
+        step: RETENTION_STEP,
+      }),
+      required: true,
+    },
+    {
+      id: "blockOnMissingVariables",
+      label: label("blockOnMissingVariables"),
+      type: new DefaultDataTypes.BooleanType({}),
+      required: true,
+    },
+    {
+      id: "senderName",
+      label: label("senderName"),
+      type: new DefaultDataTypes.StringType({}),
+    },
+    {
+      id: "senderEmail",
+      label: label("senderEmail"),
+      type: new DefaultDataTypes.EmailType({}),
+    },
+    {
+      id: "replyTo",
+      label: label("replyTo"),
+      type: new DefaultDataTypes.EmailType({}),
+    },
+    {
+      id: "categories",
+      label: label("categories"),
+      type: new TemplateCategoriesType(),
+    },
+    {
+      id: "webhookSecret",
+      label: label("webhookSecret"),
+      type: new DefaultDataTypes.StringType({}),
+    },
+  ],
+  fetchUrl: SETTINGS_URL,
+  submitUrl: SETTINGS_URL,
+  submitUrlMethod: HttpMethod.post,
+});

package/src/pages/settings/index.ts

@@ -0,0 +1,2 @@
+export * from "./form";
+export * from "./page";

package/src/pages/settings/page.ts

@@ -0,0 +1,34 @@
+import {
+  Category,
+  PageController,
+  RegisterPage,
+  settingsCategory,
+} from "@antelopejs/interface-dms/page";
+import { DefaultLayout } from "@antelopejs/interface-dms/base/layouts";
+import { MAILING_SETTINGS_MANAGE_PERMISSION, MODULE_ID } from "../../constants";
+import { mailingSettingsForm } from "./form";
+
+const SETTINGS_ORDER = 3;
+
+export const mailingSettingsCategory = Category(MODULE_ID, {
+  category: settingsCategory,
+  displayName: "$dms_mailing.title",
+  icon: "i-ph-envelope-simple",
+  order: SETTINGS_ORDER,
+  authOnly: true,
+});
+
+@RegisterPage()
+export class MailingSettingsPage extends PageController(
+  "settings",
+  {
+    displayName: "$dms_mailing.settings.title",
+    description: "$dms_mailing.settings.description",
+    icon: "i-ph-gear",
+    category: mailingSettingsCategory,
+    permission: { id: MAILING_SETTINGS_MANAGE_PERMISSION },
+  },
+  DefaultLayout(),
+) {
+  static content = mailingSettingsForm;
+}

package/src/pages/templates.ts

@@ -0,0 +1,141 @@
+import { PageController, RegisterPage } from "@antelopejs/interface-dms/page";
+import { DefaultLayout } from "@antelopejs/interface-dms/base/layouts";
+import type { TableViewTab } from "@antelopejs/interface-dms/base";
+import { CustomComponent } from "@antelopejs/interface-dms/base/custom";
+import { TableView } from "@antelopejs/interface-dms/base/table-view";
+import {
+  API_BASE_PATH,
+  GALLERY_DISPLAY_ID,
+  MAILING_ACCESS_PERMISSION,
+  MODULE_ID,
+} from "../constants";
+import { TemplatesTableAPI } from "../data/templates-table";
+import "./module";
+
+const TEMPLATES_ORDER = 1;
+const TABLE_DISPLAY_ID = "table";
+const EDITOR_URL = "/modules/mailing/editor?id={_id}";
+
+const statusTab = (id: string, icon: string): TableViewTab => ({
+  id,
+  label: `$dms_mailing.templates.status.${id}`,
+  icon,
+  filters: [{ accessorKey: "status", value: id, mode: "is" }],
+});
+
+const statusAction = (action: string, doneKey: string, icon: string) => ({
+  label: `$dms_mailing.templates.actions.${action}`,
+  icon,
+  target: {
+    type: "api" as const,
+    url: `${API_BASE_PATH}/templates/{_id}/${action}`,
+    method: "POST" as const,
+    successMessage: `$dms_mailing.templates.actions.${doneKey}`,
+  },
+});
+
+@RegisterPage()
+export class TemplatesPageController extends PageController(
+  "templates",
+  {
+    displayName: "$dms_mailing.templates.title",
+    description: "$dms_mailing.templates.description",
+    icon: "i-ph-envelope-simple",
+    module: MODULE_ID,
+    order: TEMPLATES_ORDER,
+    permission: { id: MAILING_ACCESS_PERMISSION },
+  },
+  DefaultLayout({ fullWidth: true }),
+) {
+  static table = TableView(TemplatesTableAPI, {
+    caption: "$dms_mailing.templates.title",
+    labelKey: "name",
+    rowIdKey: "_id",
+    defaultSort: { field: "updatedAt", desc: true },
+    tabs: [
+      statusTab("live", "i-ph-check-circle"),
+      statusTab("draft", "i-ph-pencil-simple"),
+      statusTab("archived", "i-ph-archive"),
+    ],
+    formContainer: { type: "drawer" },
+    rowActions: {
+      add: false,
+      edit: true,
+      details: false,
+      duplicate: false,
+      delete: true,
+      copyLink: false,
+      hasSelection: false,
+      custom: [
+        {
+          label: "$dms_mailing.templates.actions.details",
+          icon: "i-ph-info",
+          target: {
+            type: "drawer",
+            component: CustomComponent("DmsMailingTemplateDrawer"),
+            title: "$dms_mailing.templates.actions.details",
+          },
+        },
+        {
+          label: "$dms_mailing.templates.actions.test_send",
+          icon: "i-ph-paper-plane-tilt",
+          target: {
+            type: "modal",
+            size: "md",
+            component: CustomComponent("DmsMailingTestSendModal"),
+            title: "$dms_mailing.editor.test_send_modal.title",
+          },
+        },
+        {
+          label: "$dms_mailing.templates.actions.send",
+          icon: "i-ph-paper-plane-right",
+          target: {
+            type: "modal",
+            size: "md",
+            component: CustomComponent("DmsMailingTestSendModal").options({
+              mode: "real",
+            }),
+            title: "$dms_mailing.templates.send_modal.title",
+          },
+        },
+        {
+          label: "$dms_mailing.templates.actions.open_editor",
+          icon: "i-ph-pencil-simple",
+          target: { type: "page", url: EDITOR_URL },
+        },
+        statusAction("publish", "published", "i-ph-check"),
+        statusAction("unpublish", "unpublished", "i-ph-eye-slash"),
+        {
+          label: "$dms_mailing.templates.actions.archive",
+          icon: "i-ph-archive",
+          target: {
+            type: "api",
+            url: `${API_BASE_PATH}/templates/{_id}/archive`,
+            method: "POST",
+            successMessage: "$dms_mailing.templates.actions.archived",
+            confirm: {
+              title: "$dms_mailing.templates.confirm.archive_title",
+              description: "$dms_mailing.templates.confirm.archive_description",
+              confirmColor: "warning",
+            },
+          },
+        },
+      ],
+    },
+    customButtons: [
+      {
+        label: "$dms_mailing.templates.actions.create",
+        icon: "i-ph-plus",
+        permission: "add",
+        target: {
+          type: "modal",
+          size: "md",
+          component: CustomComponent("DmsMailingNewTemplateModal"),
+          title: "$dms_mailing.templates.actions.create",
+        },
+      },
+    ],
+    displays: [{ id: GALLERY_DISPLAY_ID }, { id: TABLE_DISPLAY_ID }],
+    defaultDisplay: GALLERY_DISPLAY_ID,
+  });
+}

package/src/permissions.ts

@@ -0,0 +1,44 @@
+import {
+  type Permission,
+  RegisterPermission,
+} from "@antelopejs/interface-dms/permissions";
+import {
+  MAILING_ACCESS_PERMISSION,
+  MAILING_SEND_PERMISSION,
+  MAILING_SETTINGS_MANAGE_PERMISSION,
+  MAILING_TEMPLATES_MANAGE_PERMISSION,
+} from "./constants";
+
+const MAILING_PERMISSIONS: Permission[] = [
+  {
+    id: MAILING_ACCESS_PERMISSION,
+    title: "Access mailing",
+    icon: "i-ph-envelope-simple",
+    description: "See templates, sends and mailing metrics",
+  },
+  {
+    id: MAILING_TEMPLATES_MANAGE_PERMISSION,
+    title: "Manage e-mail templates",
+    icon: "i-ph-note-pencil",
+    description: "Create, edit, publish, duplicate and archive templates",
+    dependencies: [MAILING_ACCESS_PERMISSION],
+  },
+  {
+    id: MAILING_SEND_PERMISSION,
+    title: "Send e-mails and tests",
+    icon: "i-ph-paper-plane-tilt",
+    description: "Trigger test sends and replay a previous send",
+    dependencies: [MAILING_ACCESS_PERMISSION],
+  },
+  {
+    id: MAILING_SETTINGS_MANAGE_PERMISSION,
+    title: "Manage mailing settings",
+    icon: "i-ph-sliders",
+    description: "Edit sender identity, retention and template categories",
+    dependencies: [MAILING_ACCESS_PERMISSION],
+  },
+];
+
+for (const permission of MAILING_PERMISSIONS) {
+  RegisterPermission(permission.id, permission);
+}

package/src/quick-actions.ts

@@ -0,0 +1,20 @@
+import {
+  QuickAction,
+  QuickActionCategory,
+} from "@antelopejs/interface-dms/quick-actions";
+import { MODULE_ID } from "./constants";
+import { TemplatesPageController } from "./pages/templates";
+
+const NEW_TEMPLATE_ACTION_ID = "mailing.new-template";
+
+export const mailingQuickActionCategory = QuickActionCategory(MODULE_ID, {
+  displayName: "$dms_mailing.title",
+  icon: "i-ph-envelope-simple",
+});
+
+export const newTemplateQuickAction = QuickAction(NEW_TEMPLATE_ACTION_ID, {
+  category: mailingQuickActionCategory,
+  displayName: "$dms_mailing.templates.actions.new",
+  icon: "i-ph-plus",
+  target: { type: "openForm", page: TemplatesPageController },
+});