@antelopejs/dms-mailing 0.3.4 → 0.4.1

package/src/index.ts

@@ -2,18 +2,23 @@ import "./permissions";
 import "./db";
 import path from "node:path";
 import { ImplementInterface } from "@antelopejs/interface-core";
-import { Logging } from "@antelopejs/interface-core/logging";
 import { AddFrontendModule } from "@antelopejs/interface-dms/page";
-import type { ScheduledTask } from "node-cron";
 import {
   registerAutomationNodes,
   unregisterAutomationNodes,
 } from "./automation";
 import { type DmsMailingConfig, setConfig } from "./config";
-import { FRONTEND_MODULE_NAME } from "./constants";
-import { RETENTION_CRON_NAME, scheduleRetention, stopRetention } from "./crons";
+import { API_BASE_PATH, FRONTEND_MODULE_NAME } from "./constants";
+import {
+  ATTENTION_JOB,
+  RETENTION_JOB,
+  type ScheduledJob,
+  scheduleJob,
+  stopJob,
+} from "./crons";
 import { registerTenantExport, unregisterTenantExport } from "./hooks";
 import { registerRealtimeTopics } from "./realtime";
+import { WEBHOOK_SECRET_HEADER } from "./services/webhook-status";
 
 export * from "./data";
 export * from "./data-types";
@@ -22,7 +27,21 @@ export * from "./quick-actions";
 export * from "./routes";
 export type { DmsMailingConfig } from "./config";
 
-let retentionTask: ScheduledTask | undefined;
+const CRON_JOBS = [RETENTION_JOB, ATTENTION_JOB];
+
+/**
+ * The provider webhook (`/events/:provider/:tenantId`), served through the
+ * dashboard's public URL: the front proxy lets it through without an
+ * `Origin`, never sends it a session and relays the secret header, which the
+ * route checks itself.
+ */
+const PROVIDER_WEBHOOK_ENDPOINT = {
+  path: `${API_BASE_PATH}/events/*/*`,
+  methods: ["POST"],
+  headers: [WEBHOOK_SECRET_HEADER],
+};
+
+let scheduledJobs: ScheduledJob[] = [];
 
 export async function construct(config: DmsMailingConfig = {}): Promise<void> {
   setConfig(config);
@@ -39,6 +58,7 @@ export async function construct(config: DmsMailingConfig = {}): Promise<void> {
     renderer: { name: "vue", version: "3" },
     options: { dmsMailing: {} },
     priority: 0,
+    publicEndpoints: [PROVIDER_WEBHOOK_ENDPOINT],
   });
 }
 
@@ -48,15 +68,11 @@ export function destroy(): void {
 }
 
 export function start(): void {
-  retentionTask = scheduleRetention();
+  scheduledJobs = CRON_JOBS.map(scheduleJob);
 }
 
 export async function stop(): Promise<void> {
-  const task = retentionTask;
-  retentionTask = undefined;
-  try {
-    await stopRetention(task);
-  } catch (error) {
-    Logging.Error(`Cron '${RETENTION_CRON_NAME}' failed to stop:`, error);
-  }
+  const jobs = scheduledJobs;
+  scheduledJobs = [];
+  await Promise.all(jobs.map(stopJob));
 }

package/src/pages/editor.ts

@@ -2,9 +2,14 @@ import { PageController, RegisterPage } from "@antelopejs/interface-dms/page";
 import { CustomComponent } from "@antelopejs/interface-dms/base/custom";
 import { DefaultLayout } from "@antelopejs/interface-dms/base/layouts";
 import { MODULE_ID } from "../constants";
+import { mailingNavCategory } from "./module";
 
 const EDITOR_PAGE_ORDER = 2;
 
+/**
+ * The block editor, a record page of Templates: `templates/<id>` reads
+ * Mailing › Templates › <template name> in the breadcrumb.
+ */
 @RegisterPage()
 export class MailingEditorController extends PageController(
   "editor",
@@ -13,10 +18,16 @@ export class MailingEditorController extends PageController(
     description: "$dms_mailing.editor.description",
     icon: "i-ph-pencil-simple",
     module: MODULE_ID,
+    category: mailingNavCategory,
+    urlSlug: "templates/:id",
     order: EDITOR_PAGE_ORDER,
     hidden: true,
   },
-  DefaultLayout({ fullWidth: true }),
+  DefaultLayout({ fullWidth: true, hideHeader: true, fillHeight: true }),
 ) {
-  static editor = CustomComponent("DmsMailingEditor");
+  static editor = CustomComponent("MailingEditor").meta({
+    name: "$dms_mailing.permissions.editor.name",
+    description: "$dms_mailing.permissions.editor.description",
+    icon: "i-ph-pencil-simple",
+  });
 }

package/src/pages/index.ts

@@ -1,6 +1,8 @@
-// `./module` is imported first so RegisterModule fires before any
-// @RegisterPage decorator runs: pages look their module up synchronously
-// when the decorator is invoked at import time.
+/**
+ * `./module` is imported first so RegisterModule fires before any
+ * `@RegisterPage` decorator runs: pages look their module up synchronously
+ * when the decorator is invoked at import time.
+ */
 import "./module";
 
 export * from "./module";
@@ -8,4 +10,5 @@ export * from "./overview";
 export * from "./editor";
 export * from "./sends";
 export * from "./settings";
+export * from "./suppressions";
 export * from "./templates";

package/src/pages/module.ts

@@ -1,9 +1,38 @@
-import { RegisterModule } from "@antelopejs/interface-dms/page";
+import { Category, RegisterModule } from "@antelopejs/interface-dms/page";
+import { MODULE_ID } from "../constants";
+import { catalogStatus, moduleVersion } from "../services/catalog";
+
+const MAILING_CATEGORY_ORDER = 0;
+const CONFIGURE_CATEGORY_ORDER = 1;
+const TRANSPARENT_SLUG = "/";
 
 export const mailingModule = RegisterModule({
-  id: "mailing",
+  id: MODULE_ID,
   title: "$dms_mailing.title",
   description: "$dms_mailing.description",
   icon: "i-ph-envelope-simple",
   landingPage: "overview",
+  version: moduleVersion(),
+  catalogCategory: "$dms_mailing.catalog_category",
+  status: catalogStatus,
+});
+
+/** The module's working pages: Overview, Templates and Sends. */
+export const mailingNavCategory = Category("main", {
+  displayName: "$dms_mailing.nav.mailing",
+  icon: "i-ph-envelope-simple",
+  category: mailingModule,
+  urlSlug: TRANSPARENT_SLUG,
+  type: "label",
+  order: MAILING_CATEGORY_ORDER,
+});
+
+/** Where the module is set up: its Settings page. */
+export const mailingConfigureCategory = Category("configure", {
+  displayName: "$dms_mailing.nav.configure",
+  icon: "i-ph-gear-six",
+  category: mailingModule,
+  urlSlug: TRANSPARENT_SLUG,
+  type: "label",
+  order: CONFIGURE_CATEGORY_ORDER,
 });

package/src/pages/overview.ts

@@ -1,173 +1,232 @@
 import { PageController, RegisterPage } from "@antelopejs/interface-dms/page";
 import {
+  ActivityFeed,
   ChartArea,
   ChartCard,
   Grid,
   GridRow,
   KpiCard,
   type KpiCardProps,
-  PeriodSelector,
+  Section,
   TopListCard,
+  VStack,
 } from "@antelopejs/interface-dms/base";
 import { CustomComponent } from "@antelopejs/interface-dms/base/custom";
 import { DefaultLayout } from "@antelopejs/interface-dms/base/layouts";
+import { ButtonVariant } from "@antelopejs/interface-dms/base/types";
 import {
   API_BASE_PATH,
   MAILING_SENDS_TOPIC,
   MODULE_ID,
+  NEW_TEMPLATE_ACTION_ID,
   OVERVIEW_PERIOD_SCOPE,
 } from "../constants";
 import { BUSINESS_AUDIENCE, SEND_AUDIENCE_QUERY_KEY } from "../types";
-import "./module";
+import { mailingNavCategory } from "./module";
 
 const OVERVIEW_ORDER = 0;
 const GRID_GAP = "1rem";
 const CHART_HEIGHT = "260px";
+const WIDE_SPAN = 2;
+const ATTENTION_SKELETON_ROWS = 3;
 
 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,
-  });
+): KpiCardProps => ({
+  title: `$dms_mailing.metrics.${id.replace("-", "_")}`,
+  icon,
+  variant: "stat",
+  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,
-  },
-  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 },
-        ),
-      ),
+/** A group of two KPIs under a heading that says how to read them. */
+const kpiGroup = (id: string, left: KpiCardProps, right: KpiCardProps) =>
+  VStack({ alignment: "stretch" }).child(
+    "group",
+    Section({
+      title: `$dms_mailing.overview.groups.${id}.title`,
+      description: `$dms_mailing.overview.groups.${id}.description`,
+      card: false,
+    }).child(
+      "row",
+      GridRow().child("first", KpiCard(left)).child("second", KpiCard(right)),
+    ),
   );
 
-  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")),
-  );
+const percent: Partial<KpiCardProps> = { valueFormat: "percent" };
+const inverted: Partial<KpiCardProps> = { invert: true };
+
+const kpis = Grid({ gap: GRID_GAP }).child(
+  "row",
+  GridRow()
+    .child(
+      "reach",
+      kpiGroup(
+        "reach",
+        kpi("sends", "i-ph-paper-plane-tilt"),
+        kpi("deliverability", "i-ph-check-circle", percent),
+      ),
+    )
+    .child(
+      "engagement",
+      kpiGroup(
+        "engagement",
+        kpi("open-rate", "i-ph-envelope-open", percent),
+        kpi("click-rate", "i-ph-cursor-click", percent),
+      ),
+    )
+    .child(
+      "health",
+      kpiGroup(
+        "health",
+        kpi("bounces", "i-ph-arrow-u-up-left", inverted),
+        kpi("unsubscribes", "i-ph-user-minus", inverted),
+      ),
+    ),
+);
 
-  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,
+const activity = 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,
+          comparisonStyle: "dashed",
         }),
-      )
-      .child("funnel", CustomComponent("DmsMailingFunnelCard")),
-  );
+      }),
+      { colSpan: WIDE_SPAN },
+    )
+    .child(
+      "attention",
+      ActivityFeed({
+        title: "$dms_mailing.attention_card.title",
+        fetchUrl: `${API_BASE_PATH}/metrics/attention`,
+        periodScope: OVERVIEW_PERIOD_SCOPE,
+        realtimeTopic: MAILING_SENDS_TOPIC,
+        groupByDay: false,
+        /**
+         * A third of the row: titles and template names wrap rather than
+         * end in an ellipsis with no way to read them.
+         */
+        wrap: true,
+        fillHeight: true,
+        skeletonCount: ATTENTION_SKELETON_ROWS,
+        empty: {
+          title: "$dms_mailing.attention_card.empty.title",
+          description: "$dms_mailing.attention_card.empty.description",
+        },
+      }),
+    ),
+);
 
-  static row4 = Grid({ gap: GRID_GAP }).child(
-    "row",
-    GridRow().child(
+const breakdown = Grid({ gap: GRID_GAP }).child(
+  "row",
+  GridRow()
+    .child(
+      "funnel",
+      CustomComponent("MailingFunnelCard").meta({
+        name: "$dms_mailing.permissions.funnel.name",
+        description: "$dms_mailing.permissions.funnel.description",
+        icon: "i-ph-funnel",
+      }),
+    )
+    .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,
+        highlightTopN: 2,
+        showBar: true,
+        showDelta: false,
+        skeletonCount: 5,
+        emptyLabel: "$dms_mailing.metrics.ranking_empty",
+      }),
+    )
+    .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,
+        showDelta: false,
+        skeletonCount: 5,
+        emptyLabel: "$dms_mailing.metrics.ranking_empty",
       }),
     ),
-  );
+);
+
+@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,
+    category: mailingNavCategory,
+    order: OVERVIEW_ORDER,
+  },
+  DefaultLayout({
+    fullWidth: true,
+    headerActions: [
+      {
+        id: "new-template",
+        label: "$dms_mailing.templates.actions.create",
+        icon: "i-ph-plus",
+        variant: ButtonVariant.solid,
+        target: { type: "quickAction", id: NEW_TEMPLATE_ACTION_ID },
+      },
+    ],
+  }),
+) {
+  static header = CustomComponent("MailingPageHeader")
+    .options({
+      periodScope: OVERVIEW_PERIOD_SCOPE,
+      presets: ["last-7-days", "last-30-days", "last-90-days"],
+      defaultPreset: "last-30-days",
+      defaultComparison: "previous-period",
+      showProvider: true,
+    })
+    .meta({
+      name: "$dms_mailing.permissions.page_header.name",
+      description: "$dms_mailing.permissions.page_header.description",
+      icon: "i-ph-plugs-connected",
+    });
+
+  static dashboard = CustomComponent("MailingOverviewGate")
+    .meta({
+      name: "$dms_mailing.permissions.overview_gate.name",
+      description: "$dms_mailing.permissions.overview_gate.description",
+      icon: "i-ph-squares-four",
+    })
+    .child("kpis", kpis)
+    .child("activity", activity)
+    .child("breakdown", breakdown);
 }