@antelopejs/dms-mailing 0.7.0 → 0.8.0

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

@@ -1,21 +1,8 @@
-import { afterDatabaseReady } from "../../hooks/database-ready";
-import {
-  declareTemplate,
-  declareTemplateCategory,
+export {
+  declareTemplate as DeclareTemplate,
+  declareTemplateCategory as DeclareTemplateCategory,
 } from "../../services/declarations";
-import { importSends } from "../../services/send-import";
-import { declareSender } from "../../services/sender-declaration";
-
+export { importSends as ImportSends } from "../../services/send-import";
+export { declareSender as DeclareSender } from "../../services/sender-declaration";
 export { recordEmailEvent as RecordEmailEvent } from "../../services/events";
 export { sendUnlessSuppressed as SendTemplate } from "../../services/checked-send";
-
-/*
- * Projects call these from their `start()`, which runs in parallel with the
- * DMS's: they wait for the database the DMS opens there rather than fail.
- */
-export const DeclareTemplate = afterDatabaseReady(declareTemplate);
-export const DeclareTemplateCategory = afterDatabaseReady(
-  declareTemplateCategory,
-);
-export const DeclareSender = afterDatabaseReady(declareSender);
-export const ImportSends = afterDatabaseReady(importSends);

package/src/index.ts

@@ -14,11 +14,7 @@ import {
   scheduleJob,
   stopJob,
 } from "./crons";
-import {
-  registerDatabaseReady,
-  registerTenantExport,
-  unregisterTenantExport,
-} from "./hooks";
+import { registerTenantExport, unregisterTenantExport } from "./hooks";
 import { registerRealtimeTopics } from "./realtime";
 import { frontendModule } from "./frontend-module";
 
@@ -34,7 +30,6 @@ const CRON_JOBS = [RETENTION_JOB, ATTENTION_JOB];
 let scheduledJobs: ScheduledJob[] = [];
 
 export async function construct(config: DmsMailingConfig = {}): Promise<void> {
-  registerDatabaseReady();
   setConfig(config);
   ImplementInterface(
     await import("@antelopejs/interface-dms-mailing"),

package/src/pages/sends.ts

@@ -313,11 +313,13 @@ export class SendsPageController extends PageController(
               permissionMeta("send_drawer", "i-ph-info"),
             ),
             title: "$dms_mailing.sends.actions.details",
-            // Names the open send: its recipient and the template it used.
+            /** 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.
+            /**
+             * 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/settings/form.ts

@@ -7,6 +7,8 @@ import { ComponentBuilder } from "@antelopejs/interface-dms/component";
 import { z } from "zod";
 import { API_BASE_PATH } from "../../constants";
 import { TemplateCategoriesType } from "../../data-types";
+import { missingVariablesPolicy } from "../../services/settings";
+import { MODULE_DEFAULT_SETTINGS } from "../../types";
 import {
   MAX_RETENTION_DAYS,
   MIN_RETENTION_DAYS,
@@ -37,6 +39,18 @@ const field = (id: string) => ({
   description: key(`fields.${id}.description`),
 });
 
+/**
+ * A field holding a module default offers it: "Module default · Use default"
+ * while it holds something else. The retention does not: one click there
+ * could shorten it, and lowering it deletes sends, which its input asks to
+ * confirm instead. Nor do the categories: putting the default list back
+ * would move every template of a custom category.
+ */
+const moduleDefault = (defaultValue: string) => ({
+  defaultValue,
+  offersDefault: true,
+});
+
 const section = (
   id: string,
   icon: string,
@@ -84,12 +98,14 @@ const guards = section("guards", "i-ph-shield-check", [
       ],
     }),
     required: true,
+    ...moduleDefault(missingVariablesPolicy(MODULE_DEFAULT_SETTINGS)),
   },
   {
     ...field("fallbackLocale"),
     type: new DefaultDataTypes.StringType({}),
     inputComponent: CustomComponent("MailingLocaleSelect").serializeSync(),
     required: true,
+    ...moduleDefault(MODULE_DEFAULT_SETTINGS.fallbackLocale),
   },
 ]);
 

package/src/pages/templates.ts

@@ -146,7 +146,7 @@ export class TemplatesPageController extends PageController(
           deepLink: true,
           target: {
             type: "drawer",
-            // On the right, as the gallery opens it (useTemplateDrawer).
+            /** On the right, as the gallery opens it (`useTemplateDrawer`). */
             direction: "right",
             component: templateDrawer,
             title: "$dms_mailing.templates.actions.details",

package/src/pages/toolbar.ts

@@ -65,8 +65,10 @@ export function mailingToolbar(
       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.
+      /**
+       * More than one comparison: `pageToolbar()` draws them as a "vs …" menu
+       * on the first one, the previous period.
+       */
       comparisons: MAILING_COMPARISONS,
     },
   }).meta({

package/src/routes/events.ts

@@ -17,15 +17,12 @@ import {
   secretRefusal,
   WEBHOOK_SECRET_HEADER,
 } from "../services/webhook-status";
-import {
-  SEND_EVENT_TYPES,
-  type SendEventType,
-  type WebhookRefusal,
-} from "../types";
+import type { WebhookRefusal } from "../types";
+import { sendEventTypeSchema } from "../validation/send-event-type.schema";
 
 const eventSchema = z.object({
   messageId: z.string().min(1),
-  type: z.enum(SEND_EVENT_TYPES as [SendEventType, ...SendEventType[]]),
+  type: sendEventTypeSchema,
   at: z.coerce.date().optional(),
   details: z.record(z.unknown()).optional(),
 });

package/src/routes/metrics.ts

@@ -83,18 +83,20 @@ export interface TopMetric {
   minDeliveries: number;
 }
 
+const OPEN_RATE_METRIC: TopMetric = {
+  extract: (totals) => totals.openRate,
+  minDeliveries: MIN_RANKED_DELIVERIES,
+};
+
 const TOP_METRICS: Record<string, TopMetric> = {
-  "open-rate": {
-    extract: (totals) => totals.openRate,
-    minDeliveries: MIN_RANKED_DELIVERIES,
-  },
+  "open-rate": OPEN_RATE_METRIC,
   "click-rate": {
     extract: (totals) => totals.clickRate,
     minDeliveries: MIN_RANKED_DELIVERIES,
   },
   sends: { extract: (totals) => totals.sends, minDeliveries: 0 },
 };
-const DEFAULT_TOP_METRIC = TOP_METRICS["open-rate"] as TopMetric;
+const DEFAULT_TOP_METRIC = OPEN_RATE_METRIC;
 
 interface FunnelStepDefinition {
   id: string;

package/src/routes/sends.ts

@@ -10,7 +10,7 @@ import {
 } from "@antelopejs/interface-api";
 import { assert, assertValidation } from "@antelopejs/interface-api-util";
 import { AuthUserWithPermission } from "@antelopejs/interface-dms/guards";
-import { ZodError } from "zod";
+import { ZodError, type z } from "zod";
 import { getRequestTenantId } from "@antelopejs/interface-dms/request-tenant";
 import { TenantScopedModel } from "@antelopejs/interface-dms/tenant-scoped-model";
 import type { User } from "@antelopejs/interface-dms/auth/db";
@@ -68,13 +68,9 @@ import {
   requireTemplate,
   snapshotOfVersion,
 } from "../services/templates";
-import type {
-  SendStatus,
-  SuppressionSummary,
-  TemplateContent,
-  TemplateStatus,
-} from "../types";
+import type { SendStatus, SuppressionSummary, TemplateStatus } from "../types";
 import {
+  type previewVersionSchema,
   realSendSchema,
   replayFailedSchema,
   replaySchema,
@@ -98,12 +94,6 @@ const DRAFT_VERSION = 0;
 /** Renders as the recipient got it, not as the editor previews it. */
 const SEND_MODE: InterpolationMode = "send";
 
-interface TestSendInput {
-  locale: string;
-  content?: TemplateContent;
-  data?: Record<string, unknown>;
-}
-
 export interface SendTemplateSummary {
   id: string;
   name: string;
@@ -274,9 +264,9 @@ export class SendsController extends Controller(API_BASE_PATH) {
         tenantId: this.tenantId,
         to: input.to,
         allowSuppressed: [this.user.email],
-        locale: (input as TestSendInput).locale,
-        variables: (input as TestSendInput).data,
-        content: (input as TestSendInput).content,
+        locale: input.locale,
+        variables: input.data,
+        content: input.content,
         version: requestedVersionOf(input.version),
         isTest: true,
         source: TEST_SEND_SOURCE,
@@ -578,8 +568,10 @@ export class SendsController extends Controller(API_BASE_PATH) {
  * The version a test of a published version records: a number names one,
  * "draft" or "published" let the send decide.
  */
-function requestedVersionOf(version: unknown): number | undefined {
-  return typeof version === "number" ? version : undefined;
+function requestedVersionOf(
+  version: z.infer<typeof previewVersionSchema> | undefined,
+): number | undefined {
+  return version === "draft" || version === "published" ? undefined : version;
 }
 
 function variablesOf(send: MailingSend): Record<string, unknown> {

package/src/routes/settings.ts

@@ -48,6 +48,7 @@ import {
   settingsPatchSchema,
 } from "../validation/settings.schema";
 import { retentionLimit } from "../crons/retention";
+import { isJsonObject } from "../validation/guards";
 
 const INVALID_SETTINGS = "$dms_mailing.errors.invalid_settings";
 const CATEGORIES_REASSIGNED = "$dms_mailing.settings.categories.reassigned";
@@ -61,9 +62,9 @@ const NEXT_RUN_MINUTE = 15;
 const RETENTION_DAYS_PARAM = "days";
 
 /** A settings field the form shows under another name. */
-const FORM_FIELD_OF: Record<string, string> = {
-  blockOnMissingVariables: "missingVariables",
-};
+const FORM_FIELD_OF = new Map([
+  ["blockOnMissingVariables", "missingVariables"],
+]);
 
 const retentionDaysSchema = z.coerce
   .number()
@@ -141,12 +142,12 @@ function webhookUrl(
 /** The issue of a refused write, under the form field it belongs to. */
 function formIssue(issue: z.ZodIssue): z.ZodIssue {
   const [field, ...rest] = issue.path;
-  const formField = FORM_FIELD_OF[String(field)];
+  const formField = FORM_FIELD_OF.get(String(field));
   return formField ? { ...issue, path: [formField, ...rest] } : issue;
 }
 
 /** A refused write: the generic message, and each issue for its field. */
-function invalidSettings(error: unknown): unknown {
+function invalidSettings(error: unknown) {
   if (!(error instanceof z.ZodError)) return INVALID_SETTINGS;
   return { message: INVALID_SETTINGS, issues: error.issues.map(formIssue) };
 }
@@ -236,11 +237,9 @@ export class MailingSettingsController extends Controller(
   /** The body as a checked patch; 400 for anything else. */
   private readPatch(raw: Buffer): SettingsPatch {
     const body: unknown = parseBody(raw);
-    const isPatch =
-      typeof body === "object" && body !== null && !Array.isArray(body);
-    assert(isPatch, HTTP_BAD_REQUEST, INVALID_SETTINGS);
+    assert(isJsonObject(body), HTTP_BAD_REQUEST, INVALID_SETTINGS);
     return assertValidation(
-      clearedToEmpty(body as Record<string, unknown>),
+      clearedToEmpty(body),
       (value) => settingsPatchSchema.parse(value),
       invalidSettings,
     );

package/src/routes/suppressions.ts

@@ -33,7 +33,7 @@ const manualSuppressionSchema = z.object({
 });
 
 /** A refused entry: the generic message, and each issue under its field. */
-function invalidSuppression(error: unknown): unknown {
+function invalidSuppression(error: unknown) {
   if (!(error instanceof z.ZodError)) return INVALID_SUPPRESSION;
   return { message: INVALID_SUPPRESSION, issues: error.issues };
 }

package/src/routes/templates.ts

@@ -47,7 +47,6 @@ import {
   type TemplateStats,
 } from "../services/template-stats";
 import {
-  assertSlugClaimed,
   contentFieldsOf,
   discardDraft,
   displayName,
@@ -70,6 +69,7 @@ import {
   workingSnapshot,
   workingContent,
   workingVariables,
+  refuseTakenSlug,
   requireTemplate,
 } from "../services/templates";
 import {
@@ -89,7 +89,6 @@ import {
 } from "../validation/templates.schema";
 
 const STARTER_NOT_FOUND = "$dms_mailing.errors.starter_not_found";
-const DUPLICATE_SLUG = "$dms_mailing.errors.duplicate_slug";
 const INVALID_CONTENT = "$dms_mailing.errors.invalid_content";
 const INVALID_TRANSITION = "$dms_mailing.errors.invalid_transition";
 const NOTHING_TO_PUBLISH = "$dms_mailing.errors.nothing_to_publish";
@@ -353,7 +352,7 @@ export class TemplatesController extends Controller(
       (value) => saveContentSchema.parse(value),
       () => INVALID_CONTENT,
     );
-    const content = input.content as TemplateContent;
+    const { content } = input;
     const template = await requireTemplate(this.templates, id);
     assertCurrentDraft(template, input.revision);
     const variables = input.variables ?? workingVariables(template);
@@ -515,7 +514,7 @@ export class TemplatesController extends Controller(
     const { content, variables } = input.content
       ? {
           ...workingSnapshot(template),
-          content: input.content as TemplateContent,
+          content: input.content,
         }
       : await this.previewSnapshot(template, input.version);
     const settings = await getSettings(this.tenantId);
@@ -543,9 +542,9 @@ export class TemplatesController extends Controller(
     version: "draft" | "published" | number | undefined,
   ): Promise<TemplateDraft> | TemplateDraft {
     if (version === "published") return publishedSnapshot(template);
-    if (typeof version === "number")
-      return snapshotOfVersion(this.tenantId, template, version);
-    return workingSnapshot(template);
+    if (version === undefined || version === "draft")
+      return workingSnapshot(template);
+    return snapshotOfVersion(this.tenantId, template, version);
   }
 
   /**
@@ -573,17 +572,16 @@ export class TemplatesController extends Controller(
       duplicateSchema.parse(value),
     );
     const source = await requireTemplate(this.templates, id);
-    const clash = await this.templates.getBySlug(slug);
-    assert(!clash, HTTP_CONFLICT, DUPLICATE_SLUG);
-    const [copyId] = await this.templates.insertFields({
-      slug,
-      name: withTextIn(undefined, this.locale, name),
-      category: source.category,
-      status: "draft",
-      ...contentFieldsOf(source),
-      updatedBy: this.author,
-    });
-    await assertSlugClaimed(this.tenantId, slug, copyId as string);
+    const [copyId] = await refuseTakenSlug(
+      this.templates.insertFields({
+        slug,
+        name: withTextIn(undefined, this.locale, name),
+        category: source.category,
+        status: "draft",
+        ...contentFieldsOf(source),
+        updatedBy: this.author,
+      }),
+    );
     await refreshTemplateAttention(this.tenantId);
     return { id: copyId };
   }

package/src/services/attention.ts

@@ -11,6 +11,7 @@ import {
   type TemplateAttentionReason,
 } from "../types";
 import { isDeliveryUntracked, type ProviderTracking } from "./metrics";
+import { isNumber } from "../validation/guards";
 
 export type AttentionTone = "error" | "warning" | "neutral";
 
@@ -238,7 +239,7 @@ function namesOf(templates: MailingTemplate[]): ComposedTextParam {
   };
 }
 
-function problemBreakdown(problems: SendSummary[]): Record<string, number> {
+function problemBreakdown(problems: SendSummary[]) {
   const countOf = (status: string) =>
     problems.filter((send) => send.status === status).length;
   return {
@@ -334,9 +335,9 @@ const COUNT_PARAM = "count";
 function feedParams(
   item: AttentionItem,
 ): Record<string, ComposedTextParam> | undefined {
-  const params: Record<string, ComposedTextParam> = { ...item.params };
+  const params = { ...item.params };
   const count = item.count ?? item.params?.[COUNT_PARAM];
-  if (typeof count === "number") {
+  if (isNumber(count)) {
     params[COUNT_PARAM] = { type: "count", value: count };
   }
   return Object.keys(params).length ? params : undefined;

package/src/services/categories.ts

@@ -48,10 +48,10 @@ export function reassignRemovedCategories(
   moves: ReadonlyMap<string, string> = new Map(),
 ): CategoryReassignment[] {
   const kept = new Set(categories.map((category) => category.id));
-  return templates
-    .filter((template) => template.category && !kept.has(template.category))
-    .map((template) => ({
-      templateId: template._id,
-      category: moves.get(template.category as string) ?? "",
-    }));
+  return templates.flatMap((template) => {
+    const { category } = template;
+    return category && !kept.has(category)
+      ? [{ templateId: template._id, category: moves.get(category) ?? "" }]
+      : [];
+  });
 }

package/src/services/checked-send.ts

@@ -10,6 +10,7 @@ import {
   sendTemplate,
 } from "./send";
 import { suppressionsOf } from "./suppressions";
+import { isText } from "../validation/guards";
 
 /**
  * A send the module checks against the suppression list. `allowSuppressed`
@@ -24,8 +25,7 @@ export const SUPPRESSED_ERROR_PREFIX = "$dms_mailing.errors.suppressed.";
 
 const NO_LATENCY = null;
 
-const addressOf = (to: EmailAddress): string =>
-  typeof to === "string" ? to : to.email;
+const addressOf = (to: EmailAddress): string => (isText(to) ? to : to.email);
 
 const toRecipients = (to: EmailAddress | EmailAddress[]): EmailAddress[] =>
   Array.isArray(to) ? to : [to];
@@ -68,16 +68,10 @@ function suppressedMessage(
 async function recordSuppressed(
   slug: string,
   params: CheckedSendParams,
-  blocked: EmailAddress[],
-  rows: Map<string, MailingSuppression>,
+  blocked: { to: EmailAddress; row: MailingSuppression }[],
 ): Promise<SendTemplateResult[]> {
   const prepared = await prepare(params.tenantId, slug, params);
-  const messages = blocked.map((to) =>
-    suppressedMessage(
-      to,
-      rows.get(normalizeAddress(addressOf(to))) as MailingSuppression,
-    ),
-  );
+  const messages = blocked.map(({ to, row }) => suppressedMessage(to, row));
   return recordAll(prepared, params, messages);
 }
 
@@ -103,21 +97,25 @@ export async function sendUnlessSuppressed(
   const recipients = toRecipients(params.to);
   const rows = await blockedRecipients(params, recipients);
   if (!rows.size) return sendTemplate(slug, params);
-  const isBlocked = (to: EmailAddress): boolean =>
-    rows.has(normalizeAddress(addressOf(to)));
-  const blocked = recipients.filter(isBlocked);
-  const suppressedResults = await recordSuppressed(slug, params, blocked, rows);
+  const rowOf = (to: EmailAddress) => rows.get(normalizeAddress(addressOf(to)));
+  const isBlocked = (to: EmailAddress): boolean => rowOf(to) !== undefined;
+  const blocked = recipients.flatMap((to) => {
+    const row = rowOf(to);
+    return row ? [{ to, row }] : [];
+  });
+  const suppressedResults = await recordSuppressed(slug, params, blocked);
   const sentResults = await sendAllowed(
     slug,
     params,
     recipients.filter((to) => !isBlocked(to)),
   );
+  let nextSuppressed = 0;
+  let nextSent = 0;
   return aggregateResults(
-    recipients.map(
-      (to) =>
-        (isBlocked(to)
-          ? suppressedResults.shift()
-          : sentResults.shift()) as SendTemplateResult,
+    recipients.map((to) =>
+      isBlocked(to)
+        ? suppressedResults[nextSuppressed++]
+        : sentResults[nextSent++],
     ),
   );
 }