@antelopejs/dms-mailing 0.3.4 → 0.4.0

package/src/pages/sends.ts

@@ -1,49 +1,182 @@
 import { PageController, RegisterPage } from "@antelopejs/interface-dms/page";
 import {
-  Grid,
-  GridRow,
-  KpiCard,
-  type KpiCardProps,
-  PeriodSelector,
-  type TableViewTab,
+  Banner,
+  EmptyState,
+  StatGroup,
+  type TableViewTabFilter,
+  type TableViewView,
 } 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, MODULE_ID, SENDS_PERIOD_SCOPE } from "../constants";
-import { SendsTableAPI } from "../data/sends-table";
+import type { Tone } from "@antelopejs/interface-dms/base/types";
+import { GetModel } from "@antelopejs/interface-database-decorators";
+import type { NavBadgeCount } from "@antelopejs/interface-dms";
+import { getRequestTenantId } from "@antelopejs/interface-dms/request-tenant";
 import {
-  OPERATIONAL_AUDIENCE,
-  PROBLEM_STATUSES,
-  SEND_AUDIENCE_QUERY_KEY,
-  SEND_STATUSES,
-} from "../types";
-import "./module";
+  API_BASE_PATH,
+  MAILING_SENDS_TOPIC,
+  MODULE_ID,
+  SENDS_PERIOD_SCOPE,
+} from "../constants";
+import { SendModel } from "../db";
+import { SendsTableAPI } from "../data/sends-table";
+import { RESOLVED_STAGE, type SendStage } from "../types";
+import { mailingNavCategory } from "./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 DAY_MS = 86_400_000;
+const STAT_COLUMNS = 5;
+const TEMPLATES_PAGE = "/modules/mailing/templates";
+const SUPPRESSIONS_PAGE = "/modules/mailing/suppressions";
+const FIRST_SEND_SNIPPET = [
+  'await SendTemplate("order-confirmed", {',
+  '  to: "margaux@northwind.co",',
+  "  variables: { order },",
+  "});",
+].join("\n");
+
+interface StageView {
+  stage: SendStage;
+  id: string;
+  icon: string;
+  tone?: Tone;
+  /** Narrows the tab further than its stage. */
+  filters?: TableViewTabFilter[];
+}
+
+/** The Problems tab counts like the nav badge: test sends are left out. */
+const REAL_SENDS_ONLY: TableViewTabFilter = {
+  accessorKey: "isTest",
+  value: "false",
+  mode: "is",
+};
+
+const STAGE_VIEWS: StageView[] = [
+  {
+    stage: "problem",
+    id: "problems",
+    icon: "i-ph-warning",
+    tone: "error",
+    filters: [REAL_SENDS_ONLY],
+  },
+  { stage: "in_progress", id: "in-progress", icon: "i-ph-clock" },
+  { stage: "delivered", id: "delivered", icon: "i-ph-check-circle" },
+  { stage: "engaged", id: "engaged", icon: "i-ph-cursor-click" },
+  { stage: "unsubscribed", id: "unsubscribed", icon: "i-ph-user-minus" },
+  { stage: "suppressed", id: "suppressed", icon: "i-ph-prohibit" },
+];
+
+const stageView = (view: StageView): TableViewView => ({
+  id: view.id,
+  label: `$dms_mailing.sends.views.${view.stage}`,
+  icon: view.icon,
+  tone: view.tone,
+  count: true,
+  filters: [
+    { accessorKey: "stage", value: view.stage, mode: "is" },
+    ...(view.filters ?? []),
+  ],
+});
+
+type SendsTableOptions = NonNullable<
+  Parameters<typeof TableView<typeof SendsTableAPI>>[1]
+>;
+type SendRowAction = NonNullable<
+  NonNullable<SendsTableOptions["rowActions"]>["custom"]
+>[number];
+type SendRowRule = NonNullable<SendRowAction["rule"]>;
 
-const statusTab = (status: string): TableViewTab => ({
-  id: status,
-  label: `$dms_mailing.sends.status.${status}`,
-  filters: [{ accessorKey: "status", value: status, mode: "is" }],
+/** A provider failure, or a bounce the receiving server called temporary. */
+const REPLAYABLE_PROBLEM: SendRowRule = {
+  or: [
+    { field: "status", equals: "failed" },
+    {
+      and: [
+        { field: "status", equals: "bounced" },
+        { field: "isSoftBounce", equals: true },
+      ],
+    },
+  ],
+};
+
+/** A problem nobody dealt with yet that a send again may fix. */
+const OPEN_REPLAYABLE_PROBLEM: SendRowRule = {
+  and: [REPLAYABLE_PROBLEM, { field: "stage", notEquals: RESOLVED_STAGE }],
+};
+
+/**
+ * "Send again…" on a problem nobody dealt with yet, unless the suppression
+ * list would stop it. A test sent again stays a test, and its confirmation
+ * says so.
+ */
+const sendAgainAction = (isTest: boolean): SendRowAction => ({
+  label: "$dms_mailing.sends.actions.send_again",
+  icon: "i-ph-arrow-clockwise",
+  rule: {
+    and: [
+      OPEN_REPLAYABLE_PROBLEM,
+      { field: "isRecipientSuppressed", notEquals: true },
+      { field: "isTest", equals: isTest },
+    ],
+  },
+  target: {
+    type: "api",
+    url: `${API_BASE_PATH}/sends/{_id}/replay`,
+    method: "POST",
+    successMessage: "$dms_mailing.sends.actions.sent_again",
+  },
+  confirm: {
+    title: "$dms_mailing.sends.confirm.replay_title",
+    description: isTest
+      ? "$dms_mailing.sends.confirm.replay_description_test"
+      : "$dms_mailing.sends.confirm.replay_description",
+    color: "warning",
+    icon: "i-ph-arrow-clockwise",
+    confirmLabel: "$dms_mailing.sends.confirm.replay_confirm",
+  },
 });
 
+/**
+ * In place of "Send again…" when the recipient is on the suppression list:
+ * nothing would leave, the way out is the list, narrowed to the address.
+ */
+const suppressedAddressAction: SendRowAction = {
+  label: "$dms_mailing.sends.actions.suppressed_address",
+  icon: "i-ph-prohibit",
+  rule: {
+    and: [
+      OPEN_REPLAYABLE_PROBLEM,
+      { field: "isRecipientSuppressed", equals: true },
+    ],
+  },
+  target: {
+    type: "page",
+    url: `${SUPPRESSIONS_PAGE}?email={suppressionAddress}`,
+  },
+};
+
+const permissionMeta = (id: string, icon: string) => ({
+  name: `$dms_mailing.permissions.${id}.name`,
+  description: `$dms_mailing.permissions.${id}.description`,
+  icon,
+});
+
+/** Problems of the last 24 hours, the red count next to "Sends" in the nav. */
+async function recentProblems(
+  ctx: Parameters<typeof getRequestTenantId>[0],
+): Promise<NavBadgeCount> {
+  const since = new Date(Date.now() - DAY_MS);
+  const sends = await GetModel(SendModel, getRequestTenantId(ctx)).listBetween(
+    since,
+    new Date(),
+  );
+  const count = sends.filter(
+    (send) => send.stage === "problem" && !send.isTest,
+  ).length;
+  return { count, tone: "error" };
+}
+
 @RegisterPage()
 export class SendsPageController extends PageController(
   "sends",
@@ -52,77 +185,100 @@ export class SendsPageController extends PageController(
     description: "$dms_mailing.sends.description",
     icon: "i-ph-paper-plane-tilt",
     module: MODULE_ID,
+    category: mailingNavCategory,
     order: SENDS_ORDER,
   },
   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 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 health = Banner({
+    fetchUrl: `${API_BASE_PATH}/sends/banner`,
+    realtimeTopic: MAILING_SENDS_TOPIC,
   });
 
-  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,
-        }),
-      ),
-  );
+  /** The period drives this strip only: the log keeps every send. */
+  static stats = StatGroup({
+    layout: "joined",
+    columns: STAT_COLUMNS,
+    skeletonCount: STAT_COLUMNS,
+    label: "$dms_mailing.sends.stats.label",
+    fetchUrl: `${API_BASE_PATH}/sends/stats`,
+    periodScope: SENDS_PERIOD_SCOPE,
+    realtimeTopic: MAILING_SENDS_TOPIC,
+  });
 
   static table = TableView(SendsTableAPI, {
-    caption: "$dms_mailing.sends.title",
+    caption: "$dms_mailing.sends.caption",
     labelKey: "recipientEmail",
     rowIdKey: "_id",
     defaultSort: { field: "createdAt", desc: true },
-    tabs: [
+    /** A template's drawer links to its sends: `?template=<slug>`. */
+    queryParamFilters: { template: { field: "templateSlug", mode: "is" } },
+    searchPlaceholder: "$dms_mailing.sends.search",
+    pageSize: 50,
+    rowClick: "single",
+    views: {
+      layout: "tabs",
+      items: [
+        {
+          id: "all",
+          label: "$dms_mailing.sends.views.all",
+          count: true,
+        },
+        ...STAGE_VIEWS.map(stageView),
+      ],
+      defaultView: "all",
+    },
+    quickFilters: [
       {
-        id: "problems",
-        label: "$dms_mailing.sends.tabs.problems",
-        icon: "i-ph-warning",
-        filters: [
-          {
-            accessorKey: "status",
-            value: PROBLEM_STATUSES.join(","),
-            mode: "is",
-          },
-        ],
+        field: "isTest",
+        label: "$dms_mailing.sends.filters.tests",
+        icon: "i-ph-flask",
+      },
+      {
+        field: "templateSlug",
+        label: "$dms_mailing.sends.filters.template",
+        icon: "i-ph-envelope-simple",
       },
-      ...SEND_STATUSES.map(statusTab),
     ],
+    footer: {
+      countLabel: "$dms_mailing.sends.footer.count",
+      hint: "$dms_mailing.sends.stats.period_hint",
+    },
+    emptyStates: {
+      firstRun: {
+        title: "$dms_mailing.sends.empty.title",
+        description: "$dms_mailing.sends.empty.description",
+        icon: "i-ph-paper-plane-tilt",
+        component: EmptyState({
+          title: "$dms_mailing.sends.empty_log.title",
+          description: "$dms_mailing.sends.empty_log.description",
+          icon: "i-ph-paper-plane-tilt",
+          size: "lg",
+          hatched: true,
+          card: false,
+          code: { content: FIRST_SEND_SNIPPET, language: "typescript" },
+          actions: [
+            {
+              label: "$dms_mailing.sends.empty_log.test_instead",
+              to: TEMPLATES_PAGE,
+              icon: "i-ph-flask",
+              variant: "outline",
+              color: "neutral",
+            },
+          ],
+        }),
+      },
+    },
     rowActions: {
       add: false,
       edit: false,
@@ -133,36 +289,39 @@ export class SendsPageController extends PageController(
       hasSelection: false,
       custom: [
         {
-          label: "$dms_mailing.templates.actions.details",
+          label: "$dms_mailing.sends.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.
+          /**
+           * 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.
+           */
           isDefault: true,
           target: {
-            type: "drawer",
-            component: CustomComponent("DmsMailingSendDrawer"),
-            title: "$dms_mailing.templates.actions.details",
+            type: "sidePanel",
+            component: CustomComponent("MailingSendDrawer").meta(
+              permissionMeta("send_drawer", "i-ph-info"),
+            ),
+            title: "$dms_mailing.sends.actions.details",
+            positionLabel: "$dms_mailing.sends.drawer.position",
           },
         },
         {
-          label: "$dms_mailing.sends.drawer.replay",
-          icon: "i-ph-arrow-clockwise",
+          label: "$dms_mailing.sends.actions.rendering",
+          icon: "i-ph-eye",
           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",
-            },
+            type: "modal",
+            size: "3xl",
+            component: CustomComponent("MailingRenderingModal").meta(
+              permissionMeta("rendering", "i-ph-eye"),
+            ),
+            title: "$dms_mailing.rendering.title",
           },
         },
+        sendAgainAction(false),
+        sendAgainAction(true),
+        suppressedAddressAction,
       ],
     },
-  });
+  }).navBadge({ count: (ctx) => recentProblems(ctx) });
 }

package/src/pages/settings/form.ts

@@ -1,67 +1,157 @@
-import { Form } from "@antelopejs/interface-dms/base";
+import { Form, type FormSection } from "@antelopejs/interface-dms/base";
+import { CustomComponent } from "@antelopejs/interface-dms/base/custom";
+import type { DataType } from "@antelopejs/interface-dms/base/data-types";
 import { DefaultDataTypes } from "@antelopejs/interface-dms/base/data-types/default-types";
 import { HttpMethod } from "@antelopejs/interface-dms/base/types";
+import { ComponentBuilder } from "@antelopejs/interface-dms/component";
+import { z } from "zod";
 import { API_BASE_PATH } from "../../constants";
 import { TemplateCategoriesType } from "../../data-types";
+import {
+  MAX_RETENTION_DAYS,
+  MIN_RETENTION_DAYS,
+  MIN_WEBHOOK_SECRET_LENGTH,
+  WEBHOOK_SECRET_TOO_SHORT,
+} from "../../validation/settings.schema";
 
-const MIN_RETENTION_DAYS = 1;
-const MAX_RETENTION_DAYS = 3650;
 const RETENTION_STEP = 1;
 const SETTINGS_URL = `${API_BASE_PATH}/settings`;
+const EMAIL_INPUT_COMPONENT = "dms-input-email";
 
-const label = (id: string): string => `$dms_mailing.settings.fields.${id}`;
+/** An address input that drops the spaces a paste brings along. */
+const trimmedEmailInput = () =>
+  new ComponentBuilder(EMAIL_INPUT_COMPONENT)
+    .options({ modelModifiers: { trim: true } })
+    .serializeSync();
 
-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,
+/** `type`, checked in the browser with `validation` instead of its own. */
+function checkedWith<T extends DataType>(type: T, validation: z.ZodType): T {
+  return Object.assign(type, { getValidation: () => validation });
+}
+
+const key = (path: string): string => `$dms_mailing.settings.${path}`;
+
+const field = (id: string) => ({
+  id,
+  label: key(`fields.${id}.label`),
+  description: key(`fields.${id}.description`),
+});
+
+const section = (
+  id: string,
+  icon: string,
+  fields: FormSection["fields"],
+): FormSection => ({
+  id,
+  label: key(`sections.${id}.title`),
+  description: key(`sections.${id}.description`),
+  icon,
+  fields,
+});
+
+const sender = section("sender", "i-ph-at", [
+  { ...field("senderName"), type: new DefaultDataTypes.StringType({}) },
+  {
+    ...field("senderEmail"),
+    type: new DefaultDataTypes.EmailType({}),
+    inputComponent: trimmedEmailInput(),
+  },
+  {
+    ...field("replyTo"),
+    type: new DefaultDataTypes.EmailType({}),
+    inputComponent: trimmedEmailInput(),
+  },
+]);
+
+const guards = section("guards", "i-ph-shield-check", [
+  {
+    ...field("missingVariables"),
+    type: new DefaultDataTypes.SelectType({
+      display: "cards",
+      items: [
+        {
+          value: "refuse",
+          label: key("fields.missingVariables.refuse"),
+          description: key("fields.missingVariables.refuse_hint"),
+          icon: "i-ph-prohibit",
+        },
+        {
+          value: "send",
+          label: key("fields.missingVariables.send"),
+          description: key("fields.missingVariables.send_hint"),
+          icon: "i-ph-paper-plane-tilt",
+        },
+      ],
+    }),
+    required: true,
+  },
+  {
+    ...field("fallbackLocale"),
+    type: new DefaultDataTypes.StringType({}),
+    inputComponent: CustomComponent("MailingLocaleSelect").serializeSync(),
+    required: true,
+  },
+]);
+
+const provider = section("provider", "i-ph-plugs-connected", [
+  {
+    ...field("provider"),
+    type: new DefaultDataTypes.StringType({}),
+    readonly: true,
+  },
+  {
+    ...field("webhookUrl"),
+    type: new DefaultDataTypes.StringType({ copyable: true }),
+  },
+  {
+    ...field("webhookSecret"),
+    type: checkedWith(
+      new DefaultDataTypes.SecretType({
+        rotateUrl: `${SETTINGS_URL}/webhook-secret/rotate`,
       }),
-      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({}),
-    },
-  ],
+      z.string().min(MIN_WEBHOOK_SECRET_LENGTH, WEBHOOK_SECRET_TOO_SHORT),
+    ),
+    required: true,
+  },
+  {
+    ...field("webhookStatus"),
+    type: new DefaultDataTypes.StringType({}),
+    /**
+     * Reads its own route and never changes the form's value: it is shown,
+     * never saved.
+     */
+    inputComponent: CustomComponent("MailingWebhookStatus").serializeSync(),
+  },
+]);
+
+const retention = section("retention", "i-ph-clock-counter-clockwise", [
+  {
+    ...field("logRetentionDays"),
+    type: new DefaultDataTypes.NumberType({
+      min: MIN_RETENTION_DAYS,
+      max: MAX_RETENTION_DAYS,
+      step: RETENTION_STEP,
+    }),
+    inputComponent: CustomComponent("MailingRetentionInput").serializeSync(),
+    required: true,
+  },
+]);
+
+const categories = section("categories", "i-ph-tag", [
+  { ...field("categories"), type: new TemplateCategoriesType() },
+]);
+
+export const mailingSettingsForm = Form({
+  sections: [sender, guards, provider, retention, categories],
+  sectionNav: "side",
+  fieldsOrientation: "horizontal",
+  saveMode: "bar",
   fetchUrl: SETTINGS_URL,
   submitUrl: SETTINGS_URL,
-  submitUrlMethod: HttpMethod.post,
+  submitUrlMethod: HttpMethod.put,
+  successMessage: key("saved"),
+}).meta({
+  name: "$dms_mailing.permissions.settings_form.name",
+  description: "$dms_mailing.permissions.settings_form.description",
+  icon: "i-ph-gear-six",
 });