@antelopejs/dms-mailing 0.3.3 → 0.4.0

package/src/data/sends-table.ts

@@ -16,40 +16,106 @@ import {
   Exported,
   Searchable,
   Select,
-  TableViewRoutes,
 } from "@antelopejs/interface-dms/base";
 import { DefaultDataTypes } from "@antelopejs/interface-dms/base/data-types/default-types";
+import {
+  type CellSubline,
+  DefaultDisplays,
+} from "@antelopejs/interface-dms/base/table-view";
 import { TABLES_BASE_PATH } from "../constants";
-import { MailingSend, SendModel } from "../db";
-import { SEND_STATUSES, type SendStatus } from "../types";
+import {
+  MailingSend,
+  normalizeAddress,
+  SendModel,
+  SuppressionModel,
+} from "../db";
+import {
+  RESOLVED_STAGE,
+  SEND_STAGES,
+  SEND_STATUSES,
+  type SendStage,
+  type SendStatus,
+} from "../types";
+import { localeCode, localeFallbackSubline } from "./locale-fallback";
+import { TemplatesTableAPI } from "./templates-table";
+import { READ_ONLY_ROUTES } from "./read-only-routes";
 
 const STATUS_ITEMS = SEND_STATUSES.map((value) => ({
   value,
   label: `$dms_mailing.sends.status.${value}`,
 }));
 
-const readOnlyRoutes = {
-  get: TableViewRoutes.Get,
-  list: TableViewRoutes.List,
-  count: TableViewRoutes.Count,
-  select: TableViewRoutes.Select,
-  ...TableViewRoutes.ExportRoutes,
+/**
+ * Column widths, in px, sized so the visible columns fit a 1440px window
+ * without clipping: an address next to its "Resolved" or "Test" badge, a
+ * provider error such as `connect ECONNREFUSED 127.0.0.1:2525` under the
+ * status, the longest slugs. A phone scrolls the table sideways.
+ */
+const RECIPIENT_COLUMN_WIDTH = 278;
+const STATUS_COLUMN_WIDTH = 250;
+const TEMPLATE_COLUMN_WIDTH = 162;
+const LOCALE_COLUMN_WIDTH = 104;
+const LATENCY_COLUMN_WIDTH = 128;
+const SENT_AT_COLUMN_WIDTH = 126;
+
+const PROBLEM_STAGE: SendStage = "problem";
+
+const STAGE_ITEMS = SEND_STAGES.map((value) => ({
+  value,
+  label: `$dms_mailing.sends.views.${value}`,
+}));
+
+const STATUS_TONES = {
+  queued: "neutral",
+  sent: "info",
+  delivered: "success",
+  opened: "primary",
+  clicked: "primary",
+  bounced: "error",
+  spam: "warning",
+  failed: "error",
+  unsubscribed: "warning",
+  suppressed: "neutral",
+} as const;
+
+const TEST_BADGE = {
+  field: "isTest",
+  equals: true,
+  label: "$dms_mailing.sends.test_badge",
+  tone: "warning" as const,
+};
+
+const RESOLVED_BADGE = {
+  field: "stage",
+  equals: RESOLVED_STAGE,
+  label: "$dms_mailing.sends.status.resolved",
+  tone: "success" as const,
 };
 
 @RegisterDataController()
 export class SendsTableAPI extends DataController(
   MailingSend,
-  readOnlyRoutes,
+  READ_ONLY_ROUTES,
   Controller(`${TABLES_BASE_PATH}/sends`),
 ) {
   @ModelReference()
   @TenantScopedModel(SendModel)
   declare model: SendModel;
 
+  @TenantScopedModel(SuppressionModel)
+  declare suppressions: SuppressionModel;
+
   @Select()
   @Listable()
   @Exported()
+  @Searchable()
   @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.sends.cols.id",
+    type: new DefaultDataTypes.StringType({}),
+    isVisible: false,
+    display: new DefaultDisplays.MonoDisplay({}),
+  })
   declare _id: string;
 
   @Listable()
@@ -58,8 +124,13 @@ export class SendsTableAPI extends DataController(
   @Sortable()
   @Access(AccessMode.ReadOnly)
   @Column({
-    name: "$dms_mailing.sends.cols.recipientEmail",
+    name: "$dms_mailing.sends.cols.recipient",
     type: new DefaultDataTypes.EmailType({}),
+    size: RECIPIENT_COLUMN_WIDTH,
+    display: new DefaultDisplays.IdentityDisplay({
+      subtitleField: "recipientName",
+      badges: [TEST_BADGE, RESOLVED_BADGE],
+    }),
   })
   declare recipientEmail: string;
 
@@ -70,17 +141,44 @@ export class SendsTableAPI extends DataController(
   @Column({
     name: "$dms_mailing.sends.cols.recipientName",
     type: new DefaultDataTypes.StringType({}),
+    isVisible: false,
   })
   declare recipientName: string;
 
+  @Listable()
+  @Exported()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.sends.cols.status",
+    type: new DefaultDataTypes.SelectType({ items: STATUS_ITEMS }),
+    size: STATUS_COLUMN_WIDTH,
+    filterable: true,
+    display: new DefaultDisplays.StatusPillDisplay({
+      tones: STATUS_TONES,
+      subField: "error",
+      liveValues: ["queued"],
+    }),
+  })
+  declare status: SendStatus;
+
+  /**
+   * A relation used as a filter only: the "Template" quick filter lists the
+   * templates by name, the cell keeps the slug the send was made with.
+   */
   @Listable()
   @Exported()
   @Searchable()
   @Access(AccessMode.ReadOnly)
   @Column({
     name: "$dms_mailing.sends.cols.templateSlug",
-    type: new DefaultDataTypes.StringType({}),
+    type: new DefaultDataTypes.RelationType({
+      dataApiController: TemplatesTableAPI,
+      keyMapping: { label: "name", value: "slug" },
+      filterOnly: true,
+    }),
     filterable: true,
+    size: TEMPLATE_COLUMN_WIDTH,
+    display: new DefaultDisplays.MonoDisplay({}),
   })
   declare templateSlug: string;
 
@@ -88,11 +186,12 @@ export class SendsTableAPI extends DataController(
   @Exported()
   @Access(AccessMode.ReadOnly)
   @Column({
-    name: "$dms_mailing.sends.cols.status",
-    type: new DefaultDataTypes.SelectType({ items: STATUS_ITEMS }),
+    name: "$dms_mailing.sends.cols.stage",
+    type: new DefaultDataTypes.SelectType({ items: STAGE_ITEMS }),
     filterable: true,
+    isVisible: false,
   })
-  declare status: SendStatus;
+  declare stage: SendStage;
 
   @Listable()
   @Exported()
@@ -100,9 +199,52 @@ export class SendsTableAPI extends DataController(
   @Column({
     name: "$dms_mailing.sends.cols.locale",
     type: new DefaultDataTypes.StringType({}),
+    size: LOCALE_COLUMN_WIDTH,
+    display: new DefaultDisplays.TwoLineDisplay({
+      primaryField: "localeLabel",
+      subField: "localeFallback",
+      subTone: "warning",
+    }),
   })
   declare locale: string;
 
+  @Listable(["locale"])
+  @Access(AccessMode.ReadOnly)
+  get localeLabel(): string {
+    return localeCode(this.locale);
+  }
+
+  @Listable(["locale", "requestedLocale"])
+  @Access(AccessMode.ReadOnly)
+  get localeFallback(): CellSubline | null {
+    return localeFallbackSubline(this.locale, this.requestedLocale);
+  }
+
+  @Listable()
+  @Exported()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.sends.cols.requestedLocale",
+    type: new DefaultDataTypes.StringType({}),
+    isVisible: false,
+  })
+  declare requestedLocale: string;
+
+  /**
+   * Hidden by default: the side panel shows it under "Origin", and the room
+   * goes to the recipient and the provider's error.
+   */
+  @Listable()
+  @Exported()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.sends.cols.source",
+    type: new DefaultDataTypes.StringType({}),
+    isVisible: false,
+    display: new DefaultDisplays.MonoDisplay({}),
+  })
+  declare source: string;
+
   @Listable()
   @Exported()
   @Sortable()
@@ -110,8 +252,10 @@ export class SendsTableAPI extends DataController(
   @Column({
     name: "$dms_mailing.sends.cols.latencyMs",
     type: new DefaultDataTypes.NumberType({}),
+    size: LATENCY_COLUMN_WIDTH,
+    display: new DefaultDisplays.DurationDisplay({ unit: "ms" }),
   })
-  declare latencyMs: number;
+  declare latencyMs: number | null;
 
   @Listable()
   @Exported()
@@ -120,6 +264,8 @@ export class SendsTableAPI extends DataController(
   @Column({
     name: "$dms_mailing.sends.cols.createdAt",
     type: new DefaultDataTypes.DateType({}),
+    size: SENT_AT_COLUMN_WIDTH,
+    display: new DefaultDisplays.RelativeDateDisplay({ style: "relative" }),
   })
   declare createdAt: Date;
 
@@ -127,10 +273,11 @@ export class SendsTableAPI extends DataController(
   @Exported()
   @Access(AccessMode.ReadOnly)
   @Column({
-    name: "$dms_mailing.sends.cols.source",
-    type: new DefaultDataTypes.StringType({}),
+    name: "$dms_mailing.sends.cols.templateVersion",
+    type: new DefaultDataTypes.NumberType({}),
+    isVisible: false,
   })
-  declare source: string;
+  declare templateVersion: number;
 
   @Listable()
   @Exported()
@@ -139,6 +286,7 @@ export class SendsTableAPI extends DataController(
     name: "$dms_mailing.sends.cols.isTest",
     type: new DefaultDataTypes.BooleanType({}),
     filterable: true,
+    isVisible: false,
   })
   declare isTest: boolean;
 
@@ -151,4 +299,41 @@ export class SendsTableAPI extends DataController(
     isVisible: false,
   })
   declare error: string;
+
+  @Listable()
+  @Access(AccessMode.ReadOnly)
+  declare isSoftBounce: boolean;
+
+  @Listable()
+  @Access(AccessMode.ReadOnly)
+  declare replayOf: string;
+
+  @Listable()
+  @Access(AccessMode.ReadOnly)
+  declare replayedBy: string;
+
+  @Listable()
+  @Access(AccessMode.ReadOnly)
+  declare resolvedAt: Date;
+
+  /**
+   * Whether the recipient is on the suppression list: "Send again…" would not
+   * leave, so the row offers the list instead. Read for problems only, the
+   * only rows either action is offered on.
+   */
+  @Listable(["recipientEmail", "stage"])
+  @Access(AccessMode.ReadOnly)
+  get isRecipientSuppressed(): Promise<boolean> | boolean {
+    if (this.stage !== PROBLEM_STAGE || !this.suppressions) return false;
+    return this.suppressions
+      .findByEmail(this.recipientEmail)
+      .then((row) => Boolean(row));
+  }
+
+  /** The address as the suppression list filters on it. */
+  @Listable(["recipientEmail"])
+  @Access(AccessMode.ReadOnly)
+  get suppressionAddress(): string {
+    return normalizeAddress(this.recipientEmail ?? "");
+  }
 }

package/src/data/suppressions-table.ts

@@ -0,0 +1,127 @@
+import { Controller } from "@antelopejs/interface-api";
+import {
+  DataController,
+  RegisterDataController,
+} from "@antelopejs/interface-data-api";
+import {
+  Access,
+  AccessMode,
+  Listable,
+  ModelReference,
+  Sortable,
+} from "@antelopejs/interface-data-api/metadata";
+import { TenantScopedModel } from "@antelopejs/interface-dms/tenant-scoped-model";
+import {
+  Column,
+  Exported,
+  Searchable,
+  Select,
+} from "@antelopejs/interface-dms/base";
+import { DefaultDataTypes } from "@antelopejs/interface-dms/base/data-types/default-types";
+import { DefaultDisplays } from "@antelopejs/interface-dms/base/table-view";
+import { TABLES_BASE_PATH } from "../constants";
+import { MailingSuppression, SuppressionModel } from "../db";
+import { SUPPRESSION_REASONS, type SuppressionReason } from "../types";
+import { READ_ONLY_ROUTES } from "./read-only-routes";
+
+const REASON_ITEMS = SUPPRESSION_REASONS.map((value) => ({
+  value,
+  label: `$dms_mailing.suppressions.reasons.${value}`,
+}));
+
+const REASON_TONES = {
+  hard_bounce: "error",
+  complaint: "warning",
+  unsubscribe: "warning",
+  manual: "neutral",
+} as const satisfies Record<SuppressionReason, string>;
+
+const EMAIL_COLUMN_WIDTH = 280;
+const REASON_COLUMN_WIDTH = 200;
+
+/**
+ * The suppression list, read-only here: an address goes on the list and comes
+ * off it through `/api/mailing/suppressions`, which normalizes it and records
+ * who did it.
+ */
+@RegisterDataController()
+export class SuppressionsTableAPI extends DataController(
+  MailingSuppression,
+  READ_ONLY_ROUTES,
+  Controller(`${TABLES_BASE_PATH}/suppressions`),
+) {
+  @ModelReference()
+  @TenantScopedModel(SuppressionModel)
+  declare model: SuppressionModel;
+
+  @Select()
+  @Listable()
+  @Access(AccessMode.ReadOnly)
+  declare _id: string;
+
+  @Listable()
+  @Exported()
+  @Searchable()
+  @Sortable()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.suppressions.cols.email",
+    type: new DefaultDataTypes.EmailType({}),
+    size: EMAIL_COLUMN_WIDTH,
+    filterable: true,
+    display: new DefaultDisplays.MonoDisplay({}),
+  })
+  declare email: string;
+
+  @Listable()
+  @Exported()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.suppressions.cols.reason",
+    type: new DefaultDataTypes.SelectType({ items: REASON_ITEMS }),
+    size: REASON_COLUMN_WIDTH,
+    filterable: true,
+    display: new DefaultDisplays.StatusPillDisplay({
+      tones: REASON_TONES,
+      subField: "detail",
+    }),
+  })
+  declare reason: SuppressionReason;
+
+  @Listable()
+  @Exported()
+  @Searchable()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.suppressions.cols.detail",
+    type: new DefaultDataTypes.StringType({}),
+    isVisible: false,
+  })
+  declare detail: string;
+
+  @Listable()
+  @Exported()
+  @Sortable()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.suppressions.cols.createdAt",
+    type: new DefaultDataTypes.DateType({}),
+    display: new DefaultDisplays.RelativeDateDisplay({ style: "relative" }),
+  })
+  declare createdAt: Date;
+
+  /**
+   * Hidden: a raw id says nothing on screen. The row's "See the send" opens
+   * it, and the export keeps it.
+   */
+  @Listable()
+  @Exported()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.suppressions.cols.sendId",
+    type: new DefaultDataTypes.StringType({}),
+    display: new DefaultDisplays.MonoDisplay({}),
+    isVisible: false,
+  })
+  declare sendId: string;
+}