@antelopejs/dms-mailing 0.3.4 → 0.4.0

package/src/pages/settings/page.ts

@@ -1,32 +1,24 @@
-import {
-  Category,
-  PageController,
-  RegisterPage,
-  settingsCategory,
-} from "@antelopejs/interface-dms/page";
+import { PageController, RegisterPage } from "@antelopejs/interface-dms/page";
 import { DefaultLayout } from "@antelopejs/interface-dms/base/layouts";
 import { MODULE_ID } from "../../constants";
+import { mailingConfigureCategory } from "../module";
 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,
-});
+const SETTINGS_ORDER = 0;
 
+/** The module's settings, in its own sidebar under Configure. */
 @RegisterPage()
 export class MailingSettingsPage extends PageController(
   "settings",
   {
     displayName: "$dms_mailing.settings.title",
     description: "$dms_mailing.settings.description",
-    icon: "i-ph-gear",
-    category: mailingSettingsCategory,
+    icon: "i-ph-gear-six",
+    module: MODULE_ID,
+    category: mailingConfigureCategory,
+    order: SETTINGS_ORDER,
   },
-  DefaultLayout(),
+  DefaultLayout({ fullWidth: false }),
 ) {
   static content = mailingSettingsForm;
 }

package/src/pages/suppressions.ts

@@ -0,0 +1,157 @@
+import { PageController, RegisterPage } from "@antelopejs/interface-dms/page";
+import type { TableViewView } from "@antelopejs/interface-dms/base";
+import { DefaultDataTypes } from "@antelopejs/interface-dms/base/data-types/default-types";
+import { DefaultLayout } from "@antelopejs/interface-dms/base/layouts";
+import { TableView } from "@antelopejs/interface-dms/base/table-view";
+import { ButtonVariant } from "@antelopejs/interface-dms/base/types";
+import { API_BASE_PATH, MODULE_ID, SENDS_PATH } from "../constants";
+import { SuppressionsTableAPI } from "../data/suppressions-table";
+import { SUPPRESSION_REASONS, type SuppressionReason } from "../types";
+import { mailingConfigureCategory } from "./module";
+
+const SUPPRESSIONS_ORDER = 1;
+const PAGE_SIZE = 50;
+const SUPPRESSIONS_URL = `${API_BASE_PATH}/suppressions`;
+
+const key = (path: string): string => `$dms_mailing.suppressions.${path}`;
+
+const REASON_ICONS: Record<SuppressionReason, string> = {
+  hard_bounce: "i-ph-at",
+  complaint: "i-ph-prohibit",
+  unsubscribe: "i-ph-user-minus",
+  manual: "i-ph-hand",
+};
+
+const reasonView = (reason: SuppressionReason): TableViewView => ({
+  id: reason.replace("_", "-"),
+  label: key(`reasons.${reason}`),
+  icon: REASON_ICONS[reason],
+  count: true,
+  filters: [{ accessorKey: "reason", value: reason, mode: "is" }],
+});
+
+/**
+ * The addresses nothing is sent to any more, in the module's Configure
+ * sidebar next to Settings: a searchable list someone adds to and lifts
+ * entries from, which a settings form cannot hold.
+ */
+@RegisterPage()
+export class SuppressionsPageController extends PageController(
+  "suppressions",
+  {
+    displayName: key("title"),
+    description: key("description"),
+    icon: "i-ph-prohibit",
+    module: MODULE_ID,
+    category: mailingConfigureCategory,
+    order: SUPPRESSIONS_ORDER,
+  },
+  DefaultLayout({ fullWidth: true }),
+) {
+  static table = TableView(SuppressionsTableAPI, {
+    caption: key("caption"),
+    labelKey: "email",
+    rowIdKey: "_id",
+    defaultSort: { field: "createdAt", desc: true },
+    /**
+     * The send drawer links to an address's entry: `?email=<address>`, shown
+     * as a chip the user removes to see every address again.
+     */
+    queryParamFilters: {
+      email: {
+        field: "email",
+        mode: "is",
+        visible: true,
+        label: key("cols.email"),
+      },
+    },
+    searchPlaceholder: key("search"),
+    pageSize: PAGE_SIZE,
+    views: {
+      layout: "tabs",
+      items: [
+        { id: "all", label: key("views.all"), count: true },
+        ...SUPPRESSION_REASONS.map(reasonView),
+      ],
+      defaultView: "all",
+    },
+    footer: { countLabel: key("footer.count") },
+    emptyStates: {
+      firstRun: {
+        title: key("empty.title"),
+        description: key("empty.description"),
+        icon: "i-ph-prohibit",
+      },
+    },
+    customButtons: [
+      {
+        id: "add-suppression",
+        label: key("actions.add"),
+        icon: "i-ph-plus",
+        variant: ButtonVariant.solid,
+        target: {
+          type: "api",
+          url: SUPPRESSIONS_URL,
+          method: "POST",
+          successMessage: key("actions.added"),
+        },
+        confirm: {
+          title: key("add.title"),
+          description: key("add.description"),
+          icon: "i-ph-prohibit",
+          confirmLabel: key("add.confirm"),
+          fields: [
+            {
+              id: "email",
+              label: key("add.email"),
+              type: new DefaultDataTypes.EmailType({}),
+              required: true,
+            },
+            {
+              id: "note",
+              label: key("add.note"),
+              hint: key("add.note_hint"),
+              type: new DefaultDataTypes.StringType({}),
+            },
+          ],
+        },
+      },
+    ],
+    rowActions: {
+      add: false,
+      edit: false,
+      duplicate: false,
+      delete: false,
+      copyLink: false,
+      details: false,
+      hasSelection: false,
+      custom: [
+        {
+          label: key("actions.reactivate"),
+          icon: "i-ph-arrow-counter-clockwise",
+          isVisible: true,
+          showLabel: true,
+          target: {
+            type: "api",
+            url: `${SUPPRESSIONS_URL}/{_id}`,
+            method: "DELETE",
+            successMessage: key("actions.reactivated"),
+          },
+          confirm: {
+            title: key("reactivate.title"),
+            description: key("reactivate.description"),
+            color: "warning",
+            icon: "i-ph-arrow-counter-clockwise",
+            confirmLabel: key("reactivate.confirm"),
+          },
+        },
+        {
+          label: key("actions.see_send"),
+          icon: "i-ph-paper-plane-tilt",
+          rule: { field: "sendId", notEquals: "" },
+          target: { type: "page", url: `${SENDS_PATH}?record={sendId}` },
+        },
+      ],
+    },
+  });
+}

package/src/pages/templates.ts

@@ -1,34 +1,58 @@
 import { PageController, RegisterPage } from "@antelopejs/interface-dms/page";
+import { getRequestTenantId } from "@antelopejs/interface-dms/request-tenant";
 import { DefaultLayout } from "@antelopejs/interface-dms/base/layouts";
+import { ButtonVariant, Color } from "@antelopejs/interface-dms/base/types";
 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, MODULE_ID } from "../constants";
-import { TemplatesTableAPI } from "../data/templates-table";
-import "./module";
+import {
+  API_BASE_PATH,
+  ARCHIVED_STATUS,
+  GALLERY_DISPLAY_ID,
+  MODULE_ID,
+  NEW_TEMPLATE_BUTTON_ID,
+  TEMPLATES_PATH,
+} from "../constants";
+import {
+  afterDelete,
+  afterEdit,
+  assertDeletable,
+  assertEditable,
+  TemplatesTableAPI,
+} from "../data/templates-table";
+import { mailingNavCategory } from "./module";
 
 const TEMPLATES_ORDER = 1;
 const TABLE_DISPLAY_ID = "table";
-const EDITOR_URL = "/modules/mailing/editor?id={_id}";
+/** A gallery row holds three or four cards: 24 fills whole rows at most widths. */
+const PAGE_SIZE = 24;
 
 const statusTab = (id: string, icon: string): TableViewTab => ({
   id,
-  label: `$dms_mailing.templates.status.${id}`,
+  label: `$dms_mailing.templates.tabs.${id}`,
   icon,
-  filters: [{ accessorKey: "status", value: id, mode: "is" }],
+  filter: { accessorKey: "status", value: id, mode: "is" },
 });
 
-const statusAction = (action: string, doneKey: string, icon: string) => ({
-  label: `$dms_mailing.templates.actions.${action}`,
+const permissionMeta = (id: string, icon: string) => ({
+  name: `$dms_mailing.permissions.${id}.name`,
+  description: `$dms_mailing.permissions.${id}.description`,
   icon,
-  target: {
-    type: "api" as const,
-    url: `${API_BASE_PATH}/templates/{_id}/${action}`,
-    method: "POST" as const,
-    successMessage: `$dms_mailing.templates.actions.${doneKey}`,
-  },
 });
 
+const templateDrawer = CustomComponent("MailingTemplateDrawer").meta(
+  permissionMeta("template_drawer", "i-ph-info"),
+);
+const testSendModal = CustomComponent("MailingTestSendModal").meta(
+  permissionMeta("test_send", "i-ph-flask"),
+);
+const realSendModal = CustomComponent("MailingRealSendModal").meta(
+  permissionMeta("real_send", "i-ph-paper-plane-right"),
+);
+const newTemplateModal = CustomComponent("MailingNewTemplateModal").meta(
+  permissionMeta("new_template", "i-ph-plus"),
+);
+
 @RegisterPage()
 export class TemplatesPageController extends PageController(
   "templates",
@@ -37,99 +61,172 @@ export class TemplatesPageController extends PageController(
     description: "$dms_mailing.templates.description",
     icon: "i-ph-envelope-simple",
     module: MODULE_ID,
+    category: mailingNavCategory,
     order: TEMPLATES_ORDER,
   },
   DefaultLayout({ fullWidth: true }),
 ) {
   static table = TableView(TemplatesTableAPI, {
-    caption: "$dms_mailing.templates.title",
+    caption: "$dms_mailing.templates.caption",
     labelKey: "name",
     rowIdKey: "_id",
     defaultSort: { field: "updatedAt", desc: true },
+    pageSize: PAGE_SIZE,
+    searchPlaceholder: "$dms_mailing.templates.search",
     tabs: [
+      {
+        id: "all",
+        label: "$dms_mailing.templates.tabs.all",
+        filter: {
+          accessorKey: "status",
+          value: ARCHIVED_STATUS,
+          mode: "is_not",
+        },
+        navBadge: true,
+      },
       statusTab("live", "i-ph-check-circle"),
       statusTab("draft", "i-ph-pencil-simple"),
-      statusTab("archived", "i-ph-archive"),
+      statusTab(ARCHIVED_STATUS, "i-ph-archive"),
+      {
+        id: "attention",
+        label: "$dms_mailing.templates.tabs.attention",
+        icon: "i-ph-warning",
+        iconColor: Color.warning,
+        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",
+    },
     formContainer: { type: "drawer" },
+    guards: {
+      async delete(ctx, { ids }) {
+        const tenantId = getRequestTenantId(ctx);
+        await assertDeletable(tenantId, this.model, ids);
+        return afterDelete(tenantId, ids);
+      },
+      async edit(ctx, { id, body, current }) {
+        await assertEditable(getRequestTenantId(ctx), body, current);
+        return afterEdit(this.model, id, body.name);
+      },
+    },
     rowActions: {
       add: false,
       edit: true,
       details: false,
       duplicate: false,
-      delete: true,
+      delete: {
+        rule: {
+          and: [
+            { field: "status", equals: ARCHIVED_STATUS },
+            { field: "hasSends", notEquals: true },
+          ],
+        },
+        confirm: {
+          title: "$dms_mailing.templates.confirm.delete_title",
+          description: "$dms_mailing.templates.confirm.delete_description",
+          icon: "i-ph-trash",
+          color: "error",
+        },
+      },
       copyLink: false,
       hasSelection: false,
       custom: [
+        {
+          label: "$dms_mailing.templates.actions.open_editor",
+          icon: "i-ph-pencil-simple",
+          isDefault: true,
+          target: { type: "page", url: `${TEMPLATES_PATH}/{_id}` },
+        },
         {
           label: "$dms_mailing.templates.actions.details",
           icon: "i-ph-info",
+          deepLink: true,
           target: {
             type: "drawer",
-            component: CustomComponent("DmsMailingTemplateDrawer"),
+            component: templateDrawer,
             title: "$dms_mailing.templates.actions.details",
           },
         },
         {
           label: "$dms_mailing.templates.actions.test_send",
-          icon: "i-ph-paper-plane-tilt",
+          icon: "i-ph-flask",
           target: {
             type: "modal",
             size: "md",
-            component: CustomComponent("DmsMailingTestSendModal"),
-            title: "$dms_mailing.editor.test_send_modal.title",
+            component: testSendModal,
+            title: "$dms_mailing.test_send.title",
           },
         },
         {
-          label: "$dms_mailing.templates.actions.send",
+          label: "$dms_mailing.templates.actions.real_send",
           icon: "i-ph-paper-plane-right",
+          color: "error",
+          rule: { field: "status", equals: "live" },
           target: {
             type: "modal",
             size: "md",
-            component: CustomComponent("DmsMailingTestSendModal").options({
-              mode: "real",
-            }),
-            title: "$dms_mailing.templates.send_modal.title",
+            component: realSendModal,
+            title: "$dms_mailing.real_send.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",
+          rule: { field: "status", notEquals: ARCHIVED_STATUS },
           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",
-            },
+          },
+          confirm: {
+            title: "$dms_mailing.templates.confirm.archive_title",
+            description: "$dms_mailing.templates.confirm.archive_description",
+            color: "warning",
+          },
+        },
+        {
+          label: "$dms_mailing.templates.actions.restore",
+          icon: "i-ph-arrow-counter-clockwise",
+          rule: { field: "status", equals: ARCHIVED_STATUS },
+          target: {
+            type: "api",
+            url: `${API_BASE_PATH}/templates/{_id}/restore`,
+            method: "POST",
+            successMessage: "$dms_mailing.templates.actions.restored",
           },
         },
       ],
     },
     customButtons: [
       {
+        id: NEW_TEMPLATE_BUTTON_ID,
         label: "$dms_mailing.templates.actions.create",
         icon: "i-ph-plus",
+        variant: ButtonVariant.solid,
         permission: "add",
         target: {
           type: "modal",
-          size: "md",
-          component: CustomComponent("DmsMailingNewTemplateModal"),
-          title: "$dms_mailing.templates.actions.create",
+          size: "lg",
+          component: newTemplateModal,
+          title: "$dms_mailing.new_template.title",
+          description: "$dms_mailing.new_template.description",
         },
       },
     ],
-    displays: [{ id: GALLERY_DISPLAY_ID }, { id: TABLE_DISPLAY_ID }],
+    displays: [
+      { id: GALLERY_DISPLAY_ID, capabilities: { tabs: true, search: true } },
+      { id: TABLE_DISPLAY_ID },
+    ],
     defaultDisplay: GALLERY_DISPLAY_ID,
   });
 }

package/src/permissions.ts

@@ -3,14 +3,16 @@ import { RegisterPermission } from "@antelopejs/interface-dms/permissions";
 import { MAILING_SEND_PERMISSION } from "./constants";
 import { SendsPageController } from "./pages/sends";
 
-// `@RegisterPage` publishes the page synchronously when the class is defined,
-// so the sends page's default permission id is known once it is imported.
+/**
+ * `@RegisterPage` publishes the page synchronously when the class is defined,
+ * so the sends page's default permission id is known once it is imported.
+ */
 const sendsPagePermissionId = GetPermissionId(SendsPageController);
 
 RegisterPermission(MAILING_SEND_PERMISSION, {
   id: MAILING_SEND_PERMISSION,
-  title: "Send e-mails and tests",
+  title: "$dms_mailing.permissions.send.name",
   icon: "i-ph-paper-plane-tilt",
-  description: "Trigger test sends and replay a previous send",
+  description: "$dms_mailing.permissions.send.description",
   dependencies: sendsPagePermissionId ? [sendsPagePermissionId] : [],
 });

package/src/quick-actions.ts

@@ -2,19 +2,26 @@ import {
   QuickAction,
   QuickActionCategory,
 } from "@antelopejs/interface-dms/quick-actions";
-import { MODULE_ID } from "./constants";
+import {
+  MODULE_ID,
+  NEW_TEMPLATE_ACTION_ID,
+  NEW_TEMPLATE_BUTTON_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",
 });
 
+/** Presses the templates table's "New template" button, wherever it is called. */
 export const newTemplateQuickAction = QuickAction(NEW_TEMPLATE_ACTION_ID, {
   category: mailingQuickActionCategory,
-  displayName: "$dms_mailing.templates.actions.new",
+  displayName: "$dms_mailing.templates.actions.create",
   icon: "i-ph-plus",
-  target: { type: "openForm", page: TemplatesPageController },
+  target: {
+    type: "button",
+    page: TemplatesPageController,
+    button: NEW_TEMPLATE_BUTTON_ID,
+  },
 });