@antelopejs/dms-mailing 0.6.0 → 0.7.0

package/src/implementations/dms-mailing/index.ts

@@ -4,6 +4,7 @@ import {
   declareTemplateCategory,
 } from "../../services/declarations";
 import { importSends } from "../../services/send-import";
+import { declareSender } from "../../services/sender-declaration";
 
 export { recordEmailEvent as RecordEmailEvent } from "../../services/events";
 export { sendUnlessSuppressed as SendTemplate } from "../../services/checked-send";
@@ -16,4 +17,5 @@ export const DeclareTemplate = afterDatabaseReady(declareTemplate);
 export const DeclareTemplateCategory = afterDatabaseReady(
   declareTemplateCategory,
 );
+export const DeclareSender = afterDatabaseReady(declareSender);
 export const ImportSends = afterDatabaseReady(importSends);

package/src/index.ts

@@ -1,6 +1,5 @@
 import "./permissions";
 import "./db";
-import path from "node:path";
 import { ImplementInterface } from "@antelopejs/interface-core";
 import { AddFrontendModule } from "@antelopejs/interface-dms/page";
 import {
@@ -8,7 +7,6 @@ import {
   unregisterAutomationNodes,
 } from "./automation";
 import { type DmsMailingConfig, setConfig } from "./config";
-import { API_BASE_PATH, FRONTEND_MODULE_NAME } from "./constants";
 import {
   ATTENTION_JOB,
   RETENTION_JOB,
@@ -22,7 +20,7 @@ import {
   unregisterTenantExport,
 } from "./hooks";
 import { registerRealtimeTopics } from "./realtime";
-import { WEBHOOK_SECRET_HEADER } from "./services/webhook-status";
+import { frontendModule } from "./frontend-module";
 
 export * from "./data";
 export * from "./data-types";
@@ -33,18 +31,6 @@ export type { DmsMailingConfig } from "./config";
 
 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> {
@@ -57,14 +43,7 @@ export async function construct(config: DmsMailingConfig = {}): Promise<void> {
   registerAutomationNodes();
   registerTenantExport();
   registerRealtimeTopics();
-  await AddFrontendModule({
-    name: FRONTEND_MODULE_NAME,
-    sourcePath: path.join(__dirname, "../frontend-vue"),
-    renderer: { name: "vue", version: "3" },
-    options: { dmsMailing: {} },
-    priority: 0,
-    publicEndpoints: [PROVIDER_WEBHOOK_ENDPOINT],
-  });
+  await AddFrontendModule(frontendModule());
 }
 
 export function destroy(): void {

package/src/pages/overview.ts

@@ -23,6 +23,7 @@ import {
 } from "../constants";
 import { BUSINESS_AUDIENCE, SEND_AUDIENCE_QUERY_KEY } from "../types";
 import { mailingNavCategory } from "./module";
+import { MAILING_LIVE, mailingToolbar } from "./toolbar";
 
 const OVERVIEW_ORDER = 0;
 const GRID_GAP = "1rem";
@@ -30,6 +31,7 @@ const CHART_HEIGHT = "260px";
 const WIDE_SPAN = 2;
 const ATTENTION_SKELETON_ROWS = 3;
 
+/** A KPI card of the Overview, refreshed on each send while the page is live. */
 const kpi = (
   id: string,
   icon: string,
@@ -40,6 +42,7 @@ const kpi = (
   variant: "stat",
   fetchUrl: `${API_BASE_PATH}/metrics/kpi/${id}?${SEND_AUDIENCE_QUERY_KEY}=${BUSINESS_AUDIENCE}`,
   periodScope: OVERVIEW_PERIOD_SCOPE,
+  realtimeTopic: MAILING_SENDS_TOPIC,
   valueFormat: "compact",
   showSparkline: true,
   ...extra,
@@ -104,9 +107,11 @@ const activity = Grid({ gap: GRID_GAP }).child(
          * `name` carried by each series goes to ApexCharts verbatim.
          */
         primaryLabel: "$dms_mailing.metrics.sends",
-        comparisonLabel: "$dms_mailing.metrics.previous",
+        /** Neutral: the toolbar compares with the previous period or year. */
+        comparisonLabel: "$dms_mailing.metrics.compared",
         fetchUrl: `${API_BASE_PATH}/metrics/volume`,
         periodScope: OVERVIEW_PERIOD_SCOPE,
+        realtimeTopic: MAILING_SENDS_TOPIC,
         chart: ChartArea({
           height: CHART_HEIGHT,
           xaxisType: "datetime",
@@ -157,11 +162,16 @@ const breakdown = Grid({ gap: GRID_GAP }).child(
         title: "$dms_mailing.metrics.ranking",
         fetchUrl: `${API_BASE_PATH}/metrics/top-templates?metric=open-rate`,
         periodScope: OVERVIEW_PERIOD_SCOPE,
+        realtimeTopic: MAILING_SENDS_TOPIC,
         valueFormat: "percent",
         showRank: true,
         highlightTopN: 2,
         showBar: true,
-        showDelta: false,
+        /**
+         * Each row's change against the window the toolbar compares with;
+         * "No comparison" leaves the rows without one.
+         */
+        showDelta: true,
         skeletonCount: 5,
         emptyLabel: "$dms_mailing.metrics.ranking_empty",
       }),
@@ -173,9 +183,10 @@ const breakdown = Grid({ gap: GRID_GAP }).child(
         description: "$dms_mailing.metrics.domain_sends",
         fetchUrl: `${API_BASE_PATH}/metrics/domains`,
         periodScope: OVERVIEW_PERIOD_SCOPE,
+        realtimeTopic: MAILING_SENDS_TOPIC,
         valueFormat: "percent",
         showRank: false,
-        showDelta: false,
+        showDelta: true,
         skeletonCount: 5,
         emptyLabel: "$dms_mailing.metrics.ranking_empty",
       }),
@@ -192,6 +203,7 @@ export class OverviewPageController extends PageController(
     module: MODULE_ID,
     category: mailingNavCategory,
     order: OVERVIEW_ORDER,
+    live: MAILING_LIVE,
   },
   DefaultLayout({
     fullWidth: true,
@@ -206,19 +218,11 @@ export class OverviewPageController extends PageController(
     ],
   }),
 ) {
-  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 header = mailingToolbar({
+    scope: OVERVIEW_PERIOD_SCOPE,
+    presets: ["last-7-days", "last-30-days", "last-90-days"],
+    defaultPreset: "last-30-days",
+  });
 
   static dashboard = CustomComponent("MailingOverviewGate")
     .meta({

package/src/pages/sends.ts

@@ -23,6 +23,7 @@ import { SendModel } from "../db";
 import { SendsTableAPI } from "../data/sends-table";
 import { RESOLVED_STAGE, type SendStage } from "../types";
 import { mailingNavCategory } from "./module";
+import { MAILING_LIVE, NEW_SENDS_LABEL, mailingToolbar } from "./toolbar";
 
 const SENDS_ORDER = 3;
 const DAY_MS = 86_400_000;
@@ -187,18 +188,15 @@ export class SendsPageController extends PageController(
     module: MODULE_ID,
     category: mailingNavCategory,
     order: SENDS_ORDER,
+    live: MAILING_LIVE,
   },
   DefaultLayout({ fullWidth: true }),
 ) {
-  static header = CustomComponent("MailingPageHeader")
-    .options({
-      periodScope: SENDS_PERIOD_SCOPE,
-      presets: ["last-24h", "last-7-days", "last-30-days"],
-      defaultPreset: "last-24h",
-      defaultComparison: "previous-period",
-      showProvider: true,
-    })
-    .meta(permissionMeta("page_header", "i-ph-plugs-connected"));
+  static header = mailingToolbar({
+    scope: SENDS_PERIOD_SCOPE,
+    presets: ["last-24h", "last-7-days", "last-30-days"],
+    defaultPreset: "last-24h",
+  });
 
   static health = Banner({
     fetchUrl: `${API_BASE_PATH}/sends/banner`,
@@ -226,6 +224,16 @@ export class SendsPageController extends PageController(
     searchPlaceholder: "$dms_mailing.sends.search",
     pageSize: 50,
     rowClick: "single",
+    /**
+     * New sends wait in a "N new sends" strip while the user reads a send,
+     * scrolls down the log or searches it, so the rows do not move under them.
+     */
+    liveHold: {
+      whileRowOpen: true,
+      whileScrolled: true,
+      whileSearching: true,
+      missedLabel: NEW_SENDS_LABEL,
+    },
     views: {
       layout: "tabs",
       items: [
@@ -294,16 +302,24 @@ export class SendsPageController extends PageController(
           /**
            * A send is an append-only record: it cannot be edited, so the
            * built-in `edit`/`details` row click has nothing to open. This
-           * action takes the row click and opens the send in the side panel.
+           * action takes the row click and opens the send in a drawer on the
+           * right, at the DMS's default width (the user's resize is kept).
            */
           isDefault: true,
           target: {
-            type: "sidePanel",
+            type: "drawer",
+            direction: "right",
             component: CustomComponent("MailingSendDrawer").meta(
               permissionMeta("send_drawer", "i-ph-info"),
             ),
             title: "$dms_mailing.sends.actions.details",
+            // Names the open send: its recipient and the template it used.
+            rowTitle: "$dms_mailing.sends.drawer.heading",
             positionLabel: "$dms_mailing.sends.drawer.position",
+            // A side panel keeps the open send in the URL and words a missing
+            // one by default; a drawer does both only when asked.
+            deepLink: true,
+            notFound: {},
           },
         },
         {

package/src/pages/templates.ts

@@ -20,6 +20,7 @@ import {
   assertEditable,
   TemplatesTableAPI,
 } from "../data/templates-table";
+import { localeOfRequest } from "../services/localized-text";
 import { mailingNavCategory } from "./module";
 
 const TEMPLATES_ORDER = 1;
@@ -95,13 +96,6 @@ export class TemplatesPageController extends PageController(
         filter: { accessorKey: "needsAttention", value: "true", mode: "is" },
       },
     ],
-    quickFilters: [
-      {
-        field: "category",
-        label: "$dms_mailing.templates.filters.category",
-        icon: "i-ph-tag",
-      },
-    ],
     footer: {
       countLabel: "$dms_mailing.templates.footer.count",
       hint: "$dms_mailing.templates.footer.hint",
@@ -115,7 +109,7 @@ export class TemplatesPageController extends PageController(
       },
       async edit(ctx, { id, body, current }) {
         await assertEditable(getRequestTenantId(ctx), body, current);
-        return afterEdit(this.model, id, body.name);
+        return afterEdit(this.model, id, body.name, localeOfRequest(ctx));
       },
     },
     rowActions: {
@@ -152,6 +146,8 @@ export class TemplatesPageController extends PageController(
           deepLink: true,
           target: {
             type: "drawer",
+            // On the right, as the gallery opens it (useTemplateDrawer).
+            direction: "right",
             component: templateDrawer,
             title: "$dms_mailing.templates.actions.details",
           },

package/src/pages/toolbar.ts

@@ -0,0 +1,77 @@
+import {
+  type PageToolbarProps,
+  type PeriodComparison,
+  type PeriodPreset,
+  pageToolbar,
+} from "@antelopejs/interface-dms/base";
+import type { ComponentBuilder } from "@antelopejs/interface-dms/component";
+import { CustomComponent } from "@antelopejs/interface-dms/base/custom";
+import type { PageLiveOptions } from "@antelopejs/interface-dms/page";
+import { MODULE_ID } from "../constants";
+
+/** Shortest interval, in seconds, between two refetches of a live block. */
+const LIVE_MAX_RATE_SECONDS = 5;
+
+/**
+ * Direct / Pause of the pages fed by the sends topic. One `rememberKey` for
+ * the module: pausing the Sends log pauses the Overview too.
+ */
+export const MAILING_LIVE: PageLiveOptions = {
+  maxRate: LIVE_MAX_RATE_SECONDS,
+  rememberKey: MODULE_ID,
+};
+
+/** What the paused toggle and a held table call the sends they missed. */
+export const NEW_SENDS_LABEL = "$dms_mailing.live.new_sends";
+
+/**
+ * The comparisons every mailing toolbar offers, in its "vs …" menu: the
+ * previous period by default, the same window a year back, or none, which
+ * leaves the cards without a delta.
+ */
+export const MAILING_COMPARISONS: PeriodComparison[] = [
+  "previous-period",
+  "previous-year",
+  "none",
+];
+
+/** The period a page's toolbar offers. */
+export interface MailingToolbarPeriod {
+  scope: string;
+  presets: PeriodPreset[];
+  defaultPreset: PeriodPreset;
+}
+
+/**
+ * The DMS page toolbar of a mailing page: the provider pill on the left, then
+ * "updated", Direct / Pause and the period with its comparison menu ("vs …").
+ *
+ * The page keeps it under its `header` static, the id the former header
+ * block had, so a role granting it keeps granting the bar.
+ */
+export function mailingToolbar(
+  period: MailingToolbarPeriod,
+): ComponentBuilder<PageToolbarProps> {
+  return pageToolbar({
+    leading: {
+      provider: CustomComponent("MailingProviderPill").meta({
+        name: "$dms_mailing.permissions.provider_pill.name",
+        description: "$dms_mailing.permissions.provider_pill.description",
+        icon: "i-ph-plugs-connected",
+      }),
+    },
+    live: { missedLabel: NEW_SENDS_LABEL },
+    period: {
+      id: period.scope,
+      presets: period.presets,
+      defaultPreset: period.defaultPreset,
+      // More than one comparison: pageToolbar() draws them as a "vs …" menu
+      // on the first one, the previous period.
+      comparisons: MAILING_COMPARISONS,
+    },
+  }).meta({
+    name: "$dms_mailing.permissions.page_header.name",
+    description: "$dms_mailing.permissions.page_header.description",
+    icon: "i-ph-sliders-horizontal",
+  });
+}

package/src/realtime.ts

@@ -31,11 +31,20 @@ export function registerRealtimeTopics(): void {
   }
 }
 
-function publishSendChange(type: string, sendId: string): void {
-  const payload = { ids: [sendId] };
+/**
+ * A send of `tenantId` was created or changed: the sends table and the
+ * Overview / Sends figures of that tenant read again (AntelopeJS/dms#353
+ * scopes the message to it; another workspace hears nothing).
+ */
+function publishSendChange(
+  type: string,
+  tenantId: string,
+  sendId: string,
+): void {
+  const options = { payload: { ids: [sendId] }, tenantId };
   void Promise.all([
-    PublishMessage(SENDS_ROW_TOPIC, type, { payload }),
-    PublishMessage(MAILING_SENDS_TOPIC, type, { payload }),
+    PublishMessage(SENDS_ROW_TOPIC, type, options),
+    PublishMessage(MAILING_SENDS_TOPIC, type, options),
   ]).catch((error: unknown) => {
     Logging.Error(
       `[dms-mailing] Failed to publish "${type}" for send "${sendId}":`,
@@ -44,10 +53,10 @@ function publishSendChange(type: string, sendId: string): void {
   });
 }
 
-export function publishSendCreated(sendId: string): void {
-  publishSendChange(SEND_CREATED_TYPE, sendId);
+export function publishSendCreated(tenantId: string, sendId: string): void {
+  publishSendChange(SEND_CREATED_TYPE, tenantId, sendId);
 }
 
-export function publishSendUpdated(sendId: string): void {
-  publishSendChange(SEND_UPDATED_TYPE, sendId);
+export function publishSendUpdated(tenantId: string, sendId: string): void {
+  publishSendChange(SEND_UPDATED_TYPE, tenantId, sendId);
 }