@antelopejs/dms-mailing 0.3.4 → 0.4.1

package/src/services/webhook-status.ts

@@ -0,0 +1,202 @@
+import { Logging } from "@antelopejs/interface-core/logging";
+import { GetModel } from "@antelopejs/interface-database-decorators";
+import { type MailingWebhookStatus, WebhookStatusModel } from "../db";
+import type {
+  SendEventType,
+  WebhookReceipt,
+  WebhookRefusal,
+  WebhookStatus,
+} from "../types";
+import { webhookSecretMatches } from "./events";
+
+/** The message id of the event the settings' "Send a test event" posts. */
+export const WEBHOOK_TEST_MESSAGE_ID = "dms-mailing-webhook-test";
+
+/** The header a provider (or its relay) proves it knows the secret with. */
+export const WEBHOOK_SECRET_HEADER = "x-mailing-webhook-secret";
+
+const WEBHOOK_TEST_EVENT_TYPE: SendEventType = "delivered";
+const WEBHOOK_TEST_TIMEOUT_MS = 10_000;
+const JSON_CONTENT_TYPE = "application/json";
+
+/** What the webhook answers a caller it refuses, in its own words. */
+export const WEBHOOK_REFUSAL_MESSAGES: Record<WebhookRefusal, string> = {
+  missing_secret: `The ${WEBHOOK_SECRET_HEADER} header is missing. Send the webhook secret shown in Mailing > Settings > Provider & webhook.`,
+  bad_secret: `The ${WEBHOOK_SECRET_HEADER} header does not match the webhook secret of this workspace (Mailing > Settings > Provider & webhook). It changes when the secret is rotated.`,
+  invalid_event:
+    'The body is not a mailing event: send JSON with "messageId" and "type".',
+};
+
+/** The body of a refused webhook call. */
+export interface WebhookRefusalBody {
+  error: "webhook_refused";
+  reason: WebhookRefusal;
+  message: string;
+}
+
+/** What "Send a test event" found when it called the webhook URL. */
+export interface WebhookTestOutcome {
+  isReceived: boolean;
+  url: string;
+  durationMs: number;
+  /** The HTTP status the URL answered; absent when it could not be reached. */
+  httpStatus?: number;
+  /** Why the webhook refused the test event. */
+  refusal?: WebhookRefusal;
+  /** Why the URL could not be reached (`ECONNREFUSED`, a timeout…). */
+  networkError?: string;
+}
+
+export type WebhookFetch = (
+  url: string,
+  init: RequestInit,
+) => Promise<Response>;
+
+export function refusalBody(reason: WebhookRefusal): WebhookRefusalBody {
+  return {
+    error: "webhook_refused",
+    reason,
+    message: WEBHOOK_REFUSAL_MESSAGES[reason],
+  };
+}
+
+/** Why a request's secret is refused, `null` when it carries the tenant's. */
+export function secretRefusal(
+  provided: string | undefined,
+  stored: string | undefined,
+): WebhookRefusal | null {
+  if (!provided) return "missing_secret";
+  return webhookSecretMatches(provided, stored) ? null : "bad_secret";
+}
+
+export function isWebhookTestEvent(messageId: string): boolean {
+  return messageId === WEBHOOK_TEST_MESSAGE_ID;
+}
+
+async function writeStatus(
+  tenantId: string,
+  patch: Partial<MailingWebhookStatus>,
+): Promise<void> {
+  try {
+    await GetModel(WebhookStatusModel, tenantId).record(tenantId, patch);
+  } catch (error) {
+    Logging.Error("[dms-mailing] Could not record the webhook status:", error);
+  }
+}
+
+/** Remembers the last request the webhook accepted; never throws. */
+export function noteWebhookReceived(
+  tenantId: string,
+  receipt: Omit<WebhookReceipt, "at">,
+): Promise<void> {
+  return writeStatus(tenantId, {
+    receivedAt: new Date(),
+    receivedProvider: receipt.provider,
+    receivedType: receipt.type,
+    isReceivedMatched: receipt.isMatched,
+    isReceivedTest: receipt.isTest,
+  });
+}
+
+/** Remembers the last request the webhook refused; never throws. */
+export function noteWebhookRefused(
+  tenantId: string,
+  provider: string,
+  reason: WebhookRefusal,
+): Promise<void> {
+  return writeStatus(tenantId, {
+    refusedAt: new Date(),
+    refusedProvider: provider,
+    refusedReason: reason,
+  });
+}
+
+export function toWebhookStatus(
+  row: MailingWebhookStatus | undefined,
+): WebhookStatus {
+  return {
+    lastReceived: row?.receivedAt
+      ? {
+          at: row.receivedAt,
+          provider: row.receivedProvider ?? "",
+          type: row.receivedType ?? "",
+          isMatched: !!row.isReceivedMatched,
+          isTest: !!row.isReceivedTest,
+        }
+      : null,
+    lastRefused:
+      row?.refusedAt && row.refusedReason
+        ? {
+            at: row.refusedAt,
+            provider: row.refusedProvider ?? "",
+            reason: row.refusedReason,
+          }
+        : null,
+  };
+}
+
+export async function readWebhookStatus(
+  tenantId: string,
+): Promise<WebhookStatus> {
+  return toWebhookStatus(
+    await GetModel(WebhookStatusModel, tenantId).get(tenantId),
+  );
+}
+
+const describeError = (error: unknown): string =>
+  error instanceof Error
+    ? String((error.cause as Error | undefined)?.message ?? error.message)
+    : String(error);
+
+async function refusalOf(
+  response: Response,
+): Promise<WebhookRefusal | undefined> {
+  try {
+    const body = (await response.json()) as Partial<WebhookRefusalBody>;
+    return body.reason;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Posts a test event to the webhook URL the settings show, the way a
+ * provider would: the URL, the secret and the event format are all tried.
+ */
+export async function sendWebhookTest(
+  url: string,
+  secret: string,
+  fetcher: WebhookFetch = fetch,
+): Promise<WebhookTestOutcome> {
+  const startedAt = Date.now();
+  const elapsed = () => Date.now() - startedAt;
+  try {
+    const response = await fetcher(url, {
+      method: "POST",
+      headers: {
+        "content-type": JSON_CONTENT_TYPE,
+        [WEBHOOK_SECRET_HEADER]: secret,
+      },
+      body: JSON.stringify({
+        messageId: WEBHOOK_TEST_MESSAGE_ID,
+        type: WEBHOOK_TEST_EVENT_TYPE,
+        details: { test: true },
+      }),
+      signal: AbortSignal.timeout(WEBHOOK_TEST_TIMEOUT_MS),
+    });
+    return {
+      isReceived: response.ok,
+      url,
+      durationMs: elapsed(),
+      httpStatus: response.status,
+      refusal: response.ok ? undefined : await refusalOf(response),
+    };
+  } catch (error) {
+    return {
+      isReceived: false,
+      url,
+      durationMs: elapsed(),
+      networkError: describeError(error),
+    };
+  }
+}

package/src/types/blocks.ts

@@ -29,3 +29,9 @@ export type {
 
 /** Internal to the module: templates are never exposed by status. */
 export type TemplateStatus = "draft" | "live" | "archived";
+
+/** Why a template needs a look on the templates page. */
+export type TemplateAttentionReason =
+  | "stale_draft"
+  | "never_sent"
+  | "missing_locale";

package/src/types/index.ts

@@ -2,3 +2,5 @@ export * from "./blocks";
 export * from "./resolved";
 export * from "./sends";
 export * from "./settings";
+export * from "./suppressions";
+export * from "./webhook";

package/src/types/sends.ts

@@ -1,4 +1,7 @@
-import type { SendStatus } from "@antelopejs/interface-dms-mailing";
+import type {
+  SendEventType,
+  SendStatus,
+} from "@antelopejs/interface-dms-mailing";
 
 /**
  * Send statuses and provider event types are part of the public interface:
@@ -10,7 +13,8 @@ export type {
   SendStatus,
 } from "@antelopejs/interface-dms-mailing";
 
-export const SEND_STATUSES: SendStatus[] = [
+/** What a provider reports; a webhook carries one of these. */
+export const SEND_EVENT_TYPES: SendEventType[] = [
   "queued",
   "sent",
   "delivered",
@@ -22,8 +26,62 @@ export const SEND_STATUSES: SendStatus[] = [
   "unsubscribed",
 ];
 
+/** Every status of a send: the provider's events, and `suppressed`. */
+export const SEND_STATUSES: SendStatus[] = [...SEND_EVENT_TYPES, "suppressed"];
+
 export const PROBLEM_STATUSES: SendStatus[] = ["bounced", "failed", "spam"];
 
+/**
+ * The send log tab a status belongs to. Stored next to the status so a tab is a
+ * single-value filter: a view filter is AND-only and `is` compares one value.
+ * A problem someone already sent again or to another address is `resolved`:
+ * it leaves the Problems tab, the nav badge and the provider banner.
+ */
+export type SendStage =
+  | "problem"
+  | "in_progress"
+  | "delivered"
+  | "engaged"
+  | "unsubscribed"
+  | "suppressed"
+  | "resolved";
+
+export const SEND_STAGES: SendStage[] = [
+  "problem",
+  "in_progress",
+  "delivered",
+  "engaged",
+  "unsubscribed",
+  "suppressed",
+  "resolved",
+];
+
+export const STAGE_BY_STATUS: Record<SendStatus, SendStage> = {
+  queued: "in_progress",
+  sent: "in_progress",
+  delivered: "delivered",
+  opened: "engaged",
+  clicked: "engaged",
+  bounced: "problem",
+  spam: "problem",
+  failed: "problem",
+  unsubscribed: "unsubscribed",
+  suppressed: "suppressed",
+};
+
+const RESOLVABLE_STAGE: SendStage = "problem";
+export const RESOLVED_STAGE: SendStage = "resolved";
+
+export function stageOf(status: SendStatus, isResolved = false): SendStage {
+  const stage = STAGE_BY_STATUS[status];
+  return isResolved && stage === RESOLVABLE_STAGE ? RESOLVED_STAGE : stage;
+}
+
+/** Whether someone already dealt with this send's problem. */
+export function isResolvedStage(stage: SendStage | undefined): boolean {
+  return stage === RESOLVED_STAGE;
+}
+
 /**
  * Which sends a metric describes. The Overview is the business view and hides
  * test sends; the Sends page is the operational log and counts what actually
@@ -41,4 +99,8 @@ export interface SendEventDetails {
   userAgent?: string;
   reason?: string;
   code?: string;
+  /** The provider's own id of the event, to ignore a webhook it retries. */
+  eventId?: string;
+  /** `soft`/`transient` or `hard`/`permanent`, when the provider says so. */
+  bounceType?: string;
 }

package/src/types/suppressions.ts

@@ -0,0 +1,27 @@
+/**
+ * Why an address is on the suppression list: the receiving server said it
+ * does not exist, the recipient reported spam or unsubscribed, or someone
+ * added it by hand.
+ */
+export type SuppressionReason =
+  | "hard_bounce"
+  | "complaint"
+  | "unsubscribe"
+  | "manual";
+
+export const SUPPRESSION_REASONS: SuppressionReason[] = [
+  "hard_bounce",
+  "complaint",
+  "unsubscribe",
+  "manual",
+];
+
+/** What the send log and its drawer say about a suppressed address. */
+export interface SuppressionSummary {
+  id: string;
+  email: string;
+  reason: SuppressionReason;
+  createdAt: Date;
+  /** The send whose event put the address on the list. */
+  sendId?: string;
+}

package/src/types/webhook.ts

@@ -0,0 +1,29 @@
+/** Why the webhook refused a request, as the settings tell it. */
+export type WebhookRefusal = "missing_secret" | "bad_secret" | "invalid_event";
+
+/** The last request the webhook accepted. */
+export interface WebhookReceipt {
+  at: Date;
+  provider: string;
+  type: string;
+  /**
+   * Whether the event was recorded against a send: not when no send carries
+   * its message id, nor when the provider delivered it twice.
+   */
+  isMatched: boolean;
+  /** Sent by the settings' "Send a test event" button. */
+  isTest: boolean;
+}
+
+/** The last request the webhook refused. */
+export interface WebhookRejection {
+  at: Date;
+  provider: string;
+  reason: WebhookRefusal;
+}
+
+/** What the settings show about the webhook. */
+export interface WebhookStatus {
+  lastReceived: WebhookReceipt | null;
+  lastRefused: WebhookRejection | null;
+}

package/src/validation/settings.schema.ts

@@ -1,33 +1,189 @@
+import { domainToASCII } from "node:url";
 import { z } from "zod";
-import { MAX_NAME_LENGTH } from "../constants";
+import { MAX_NAME_LENGTH, SLUG_PATTERN } from "../constants";
+import { MARKETING_CATEGORY } from "../engine";
 
-const MIN_RETENTION_DAYS = 1;
-const MAX_RETENTION_DAYS = 3650;
-const LOCALE_PATTERN = /^[a-z]{2}(-[A-Z]{2})?$/;
-// The generated secret is 48 hex characters; this floor lets an admin paste a
-// provider-issued one without letting them blank the field, which would leave
-// the unauthenticated event endpoint with no gate at all.
-const MIN_WEBHOOK_SECRET_LENGTH = 32;
+export const MIN_RETENTION_DAYS = 1;
+export const MAX_RETENTION_DAYS = 3650;
+const MAX_LOCALE_LENGTH = 35;
+const CATEGORY_ICON_PATTERN = /^i-ph-[a-z0-9-]+$/;
+const CONTROL_CHARACTERS = /\p{Cc}/u;
+const ADDRESS_SEPARATOR = "@";
+const NO_ADDRESS = "";
+/**
+ * The generated secret is 48 hex characters; this floor lets an admin paste a
+ * provider-issued one without letting them blank the field, which would leave
+ * the unauthenticated event endpoint with no gate at all.
+ */
+export const MIN_WEBHOOK_SECRET_LENGTH = 32;
+
+const messageKey = (path: string): string => `$dms_mailing.settings.${path}`;
+const LABEL_REQUIRED = messageKey("categories.label_required");
+const CATEGORY_DUPLICATE = messageKey("categories.label_duplicate");
+const MARKETING_REQUIRED = messageKey("categories.marketing_required");
+const LABEL_PART = "label";
+const UNKNOWN_MOVE_TARGET = "$dms.field_errors.invalid";
+export const WEBHOOK_SECRET_TOO_SHORT = messageKey(
+  "fields.webhookSecret.too_short",
+);
+
+const MISSING_VARIABLES_POLICIES = ["refuse", "send"] as const;
 
 export const categorySchema = z.object({
-  id: z.string().min(1).max(MAX_NAME_LENGTH),
-  label: z.string().min(1).max(MAX_NAME_LENGTH),
-  icon: z.string().min(1),
+  id: z.string().max(MAX_NAME_LENGTH).regex(SLUG_PATTERN),
+  label: z.string().trim().max(MAX_NAME_LENGTH),
+  icon: z.string().regex(CATEGORY_ICON_PATTERN),
 });
 
+/**
+ * A category as the settings form sends it: a kept one, or one removed whose
+ * templates go to `moveTo` (another kept category) once saved.
+ */
+const categoryEntrySchema = categorySchema.extend({
+  moveTo: z.string().regex(SLUG_PATTERN).optional(),
+});
+
+export type CategoryEntry = z.infer<typeof categoryEntrySchema>;
+
+/** Why a category list is refused, and the part of it at fault. */
+interface CategoryIssue {
+  message: string;
+  path: Array<string | number>;
+}
+
+const isKept = (entry: CategoryEntry): boolean => entry.moveTo === undefined;
+
+/**
+ * A kept entry repeating the label (whatever its case) or the id of an
+ * earlier one, under the row it belongs to.
+ */
+function duplicateIssues(entries: CategoryEntry[]): CategoryIssue[] {
+  const labels = new Set<string>();
+  const ids = new Set<string>();
+  const issues: CategoryIssue[] = [];
+  entries.forEach((entry, index) => {
+    if (!isKept(entry) || !entry.label) return;
+    const label = entry.label.toLocaleLowerCase();
+    if (labels.has(label))
+      issues.push({ message: CATEGORY_DUPLICATE, path: [index, LABEL_PART] });
+    else if (ids.has(entry.id))
+      issues.push({ message: CATEGORY_DUPLICATE, path: [index, "id"] });
+    labels.add(label);
+    ids.add(entry.id);
+  });
+  return issues;
+}
+
+/**
+ * A row left without a label. Checked with the whole list rather than as the
+ * label's own minimum, which the form would turn into a browser-side check:
+ * the server words it, under the row, together with the other row issues.
+ */
+function blankLabelIssues(entries: CategoryEntry[]): CategoryIssue[] {
+  return entries.flatMap((entry, index) =>
+    entry.label ? [] : [{ message: LABEL_REQUIRED, path: [index, LABEL_PART] }],
+  );
+}
+
+function marketingIssues(kept: Set<string>): CategoryIssue[] {
+  return kept.has(MARKETING_CATEGORY)
+    ? []
+    : [{ message: MARKETING_REQUIRED, path: [] }];
+}
+
+function moveIssues(
+  entries: CategoryEntry[],
+  kept: Set<string>,
+): CategoryIssue[] {
+  return entries.flatMap((entry, index) =>
+    isKept(entry) || kept.has(entry.moveTo as string)
+      ? []
+      : [{ message: UNKNOWN_MOVE_TARGET, path: [index, "moveTo"] }],
+  );
+}
+
+function refineCategoryEntries(
+  entries: CategoryEntry[],
+  context: z.RefinementCtx,
+): void {
+  const kept = new Set(entries.filter(isKept).map((entry) => entry.id));
+  [
+    ...blankLabelIssues(entries),
+    ...duplicateIssues(entries),
+    ...marketingIssues(kept),
+    ...moveIssues(entries, kept),
+  ].forEach((issue) =>
+    context.addIssue({ code: z.ZodIssueCode.custom, ...issue }),
+  );
+}
+
+/**
+ * The category list of the settings: kept labels and ids are unique, every
+ * move names a kept one, and the marketing category stays.
+ */
+export const categoriesSchema = z
+  .array(categoryEntrySchema)
+  .superRefine(refineCategoryEntries);
+
+function isWellFormedLocale(value: string): boolean {
+  try {
+    return Intl.getCanonicalLocales(value).length === 1;
+  } catch {
+    return false;
+  }
+}
+
+/** An address as typed or pasted, its domain in the ASCII form mail uses. */
+function toAsciiAddress(address: string): string {
+  const separator = address.lastIndexOf(ADDRESS_SEPARATOR);
+  if (separator < 0) return address;
+  const domain = domainToASCII(address.slice(separator + 1));
+  return domain ? `${address.slice(0, separator + 1)}${domain}` : address;
+}
+
+const optionalAddressSchema = z
+  .string()
+  .trim()
+  .transform(toAsciiAddress)
+  .pipe(z.union([z.literal(NO_ADDRESS), z.string().email()]));
+
 export const settingsSchema = z.object({
-  fallbackLocale: z.string().regex(LOCALE_PATTERN),
+  fallbackLocale: z
+    .string()
+    .trim()
+    .max(MAX_LOCALE_LENGTH)
+    .refine(isWellFormedLocale),
   logRetentionDays: z
     .number()
     .int()
     .min(MIN_RETENTION_DAYS)
     .max(MAX_RETENTION_DAYS),
   blockOnMissingVariables: z.boolean(),
-  senderName: z.string().max(MAX_NAME_LENGTH).default(""),
-  senderEmail: z.union([z.string().email(), z.literal("")]).default(""),
-  replyTo: z.union([z.string().email(), z.literal("")]).default(""),
-  webhookSecret: z.string().min(MIN_WEBHOOK_SECRET_LENGTH).max(MAX_NAME_LENGTH),
-  categories: z.array(categorySchema).default([]),
+  senderName: z
+    .string()
+    .trim()
+    .max(MAX_NAME_LENGTH)
+    .refine((value) => !CONTROL_CHARACTERS.test(value)),
+  senderEmail: optionalAddressSchema,
+  replyTo: optionalAddressSchema,
+  webhookSecret: z
+    .string()
+    .min(MIN_WEBHOOK_SECRET_LENGTH, WEBHOOK_SECRET_TOO_SHORT)
+    .max(MAX_NAME_LENGTH),
+  categories: categoriesSchema,
 });
 
+/**
+ * What a write may carry: any of the settings (`null` already turned into
+ * `""` for a cleared one) and the missing-variables choice the form shows.
+ * Anything else is refused.
+ */
+export const settingsPatchSchema = settingsSchema
+  .partial()
+  .extend({
+    missingVariables: z.enum(MISSING_VARIABLES_POLICIES).optional(),
+  })
+  .strict();
+
+export type SettingsPatch = z.infer<typeof settingsPatchSchema>;
 export type SettingsInput = z.input<typeof settingsSchema>;

package/src/validation/templates.schema.ts

@@ -18,6 +18,8 @@ export const createTemplateSchema = z.object({
   category: z.string().optional(),
   /** Absent or empty starts blank; otherwise the template to copy. */
   sourceTemplateId: z.string().optional(),
+  /** A starter template to start from, when no template is copied. */
+  starterId: z.string().optional(),
 });
 
 export const conditionSchema = z.object({
@@ -99,6 +101,20 @@ export const templateContentSchema = z.object({
   locales: z.record(localeContentSchema),
 });
 
+/**
+ * The draft revision the writer last saw; a write behind the stored draft is
+ * refused. Absent writes unconditionally.
+ */
+export const draftRevisionSchema = z.number().int().min(0).optional();
+
+export const publishSchema = z.object({ revision: draftRevisionSchema });
+
+/** Restoring a version writes the draft: it carries the revision too. */
+export const restoreVersionSchema = publishSchema;
+
+/** A published version's number, as the route's parameter spells it. */
+export const versionNumberSchema = z.coerce.number().int().min(1);
+
 export const variableSchema = z.object({
   path: z.string().min(1),
   type: z.enum([
@@ -114,13 +130,40 @@ export const variableSchema = z.object({
   required: z.boolean(),
 });
 
-export const variablesSchema = z.object({ variables: z.array(variableSchema) });
+export const variableListSchema = z.array(variableSchema);
+
+/** Declarations land in the draft, like the content: same revision check. */
+export const variablesSchema = z.object({
+  variables: variableListSchema,
+  revision: draftRevisionSchema,
+});
+
+/**
+ * A draft save: the content and, when given, the variable declarations
+ * (absent keeps the draft's own).
+ */
+export const saveContentSchema = z.object({
+  content: templateContentSchema,
+  variables: variableListSchema.optional(),
+  revision: draftRevisionSchema,
+});
 
 export const testDataSchema = z.object({ data: z.record(z.unknown()) });
 
+/**
+ * Which content a preview renders when it carries none: the working draft
+ * (the default), what customers receive, or a published version number.
+ */
+export const previewVersionSchema = z.union([
+  z.literal("draft"),
+  z.literal("published"),
+  z.number().int().min(1),
+]);
+
 export const previewSchema = z.object({
   /** Absent lets the server pick the tenant fallback (see `pickLocale`). */
   locale: z.string().min(1).optional(),
+  version: previewVersionSchema.optional(),
   content: templateContentSchema.optional(),
   data: z.record(z.unknown()).optional(),
 });
@@ -143,3 +186,12 @@ export const duplicateSchema = z.object({
   slug: slugSchema,
   name: z.string().trim().min(1).max(MAX_NAME_LENGTH),
 });
+
+/** A send again; `to` corrects the address of a bounced send. */
+export const replaySchema = z.object({
+  to: z.string().trim().email().optional(),
+});
+
+export const replayFailedSchema = z.object({
+  since: z.coerce.date().optional(),
+});

package/dist/antelope-modules.d.ts

@@ -1,32 +0,0 @@
-export declare const SHARED_MODULE_SOURCES: {
-    readonly dms: {
-        readonly type: "package";
-        readonly package: "@antelopejs/dms";
-        readonly version: ">=0.4.3 <1.0.0";
-    };
-    readonly mongodb: {
-        readonly type: "package";
-        readonly package: "@antelopejs/mongodb";
-        readonly version: "^1.3.1";
-    };
-    readonly "auth-jwt": {
-        readonly type: "package";
-        readonly package: "@antelopejs/auth-jwt";
-        readonly version: "^1.0.3";
-    };
-    readonly api: {
-        readonly type: "package";
-        readonly package: "@antelopejs/api";
-        readonly version: "^1.3.0";
-    };
-    readonly "file-storage-local": {
-        readonly type: "package";
-        readonly package: "@antelopejs/file-storage-local";
-        readonly version: "^0.1.5";
-    };
-    readonly nodemailer: {
-        readonly type: "package";
-        readonly package: "@antelopejs/nodemailer";
-        readonly version: "^0.0.5";
-    };
-};