@antelopejs/dms-mailing 0.3.4 → 0.4.1

package/src/routes/settings.ts

@@ -1,25 +1,161 @@
+import { randomBytes } from "node:crypto";
 import {
   Context,
   Controller,
   Get,
-  JSONBody,
   Post,
+  Put,
+  RawBody,
   type RequestContext,
 } from "@antelopejs/interface-api";
-import { assertValidation } from "@antelopejs/interface-api-util";
+import { assert, assertValidation } from "@antelopejs/interface-api-util";
+import { GetApiBaseUrl } from "@antelopejs/interface-dms/api-base-url";
+import { GetClientBaseUrl } from "@antelopejs/interface-dms/client-base-url";
 import { AuthUserWithPermission } from "@antelopejs/interface-dms/guards";
 import { getRequestTenantId } from "@antelopejs/interface-dms/request-tenant";
 import type { User } from "@antelopejs/interface-dms/auth/db";
 import { TenantScopedModel } from "@antelopejs/interface-dms/tenant-scoped-model";
-import { API_BASE_PATH } from "../constants";
-import { TemplateModel } from "../db";
+import { z } from "zod";
+import { API_BASE_PATH, ARCHIVED_STATUS, HTTP_BAD_REQUEST } from "../constants";
+import { parseBody } from "../data/body";
+import { SendModel, TemplateModel } from "../db";
 import { MailingSettingsPage } from "../pages/settings/page";
-import { reassignRemovedCategories } from "../services/categories";
-import { getSettings, saveSettings } from "../services/settings";
-import type { MailingSettingsValues } from "../types";
-import { settingsSchema } from "../validation/settings.schema";
+import {
+  categoryMoves,
+  keptCategories,
+  reassignRemovedCategories,
+} from "../services/categories";
+import { readCapabilities } from "../services/provider";
+import {
+  clearedToEmpty,
+  getSettings,
+  type MissingVariablesPolicy,
+  mergeSettingsPatch,
+  missingVariablesPolicy,
+  saveSettings,
+  WEBHOOK_SECRET_BYTES,
+} from "../services/settings";
+import {
+  readWebhookStatus,
+  sendWebhookTest,
+  type WebhookTestOutcome,
+} from "../services/webhook-status";
+import type { MailingSettingsValues, WebhookStatus } from "../types";
+import {
+  MAX_RETENTION_DAYS,
+  MIN_RETENTION_DAYS,
+  type SettingsPatch,
+  settingsPatchSchema,
+} from "../validation/settings.schema";
+import { retentionLimit } from "../crons/retention";
 
 const INVALID_SETTINGS = "$dms_mailing.errors.invalid_settings";
+const CATEGORIES_REASSIGNED = "$dms_mailing.settings.categories.reassigned";
+const SENDER_NAME_IGNORED = "$dms_mailing.settings.sender_name_ignored";
+const WARNING_COLOR = "warning";
+const EVENTS_PATH = `${API_BASE_PATH}/events`;
+const DEFAULT_PROVIDER_SLUG = "provider";
+const TRAILING_SLASHES = /\/+$/;
+const NEXT_RUN_HOUR = 3;
+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 retentionDaysSchema = z.coerce
+  .number()
+  .int()
+  .min(MIN_RETENTION_DAYS)
+  .max(MAX_RETENTION_DAYS);
+
+/** The settings as the form reads them, with the values derived for display. */
+export interface MailingSettingsResponse extends MailingSettingsValues {
+  /** Where the provider posts its events; read-only. */
+  webhookUrl: string;
+  /** The configured provider, as the read-only provider row shows it. */
+  provider: string;
+  /** `blockOnMissingVariables` as the two choices the form offers. */
+  missingVariables: MissingVariablesPolicy;
+}
+
+/** A toast the settings form shows next to its success one. */
+export interface SettingsNotice {
+  title: string;
+  color?: string;
+  params?: Record<string, unknown>;
+}
+
+export interface SettingsWriteResponse extends MailingSettingsValues {
+  notice?: SettingsNotice;
+}
+
+/** What "Send a test event" did, and the webhook status after it. */
+export interface WebhookTestResponse extends WebhookTestOutcome {
+  status: WebhookStatus;
+}
+
+export interface RetentionPreview {
+  days: number;
+  /** Sends the next nightly run would delete with this retention. */
+  count: number;
+  nextRunAt: string;
+}
+
+function providerSlug(name: string | undefined): string {
+  const slug = (name ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-");
+  return slug || DEFAULT_PROVIDER_SLUG;
+}
+
+/** The next 03:15 the retention cron fires at, server time. */
+export function nextRetentionRun(now: Date = new Date()): Date {
+  const next = new Date(now);
+  next.setHours(NEXT_RUN_HOUR, NEXT_RUN_MINUTE, 0, 0);
+  if (next <= now) next.setDate(next.getDate() + 1);
+  return next;
+}
+
+/**
+ * Where a provider posts the events of a tenant: the API origin, the provider
+ * and the tenant in the path.
+ */
+function webhookUrl(
+  origin: string,
+  provider: string | undefined,
+  tenantId: string,
+): string {
+  return [
+    origin.replace(TRAILING_SLASHES, ""),
+    EVENTS_PATH,
+    `/${providerSlug(provider)}`,
+    `/${encodeURIComponent(tenantId)}`,
+  ].join("");
+}
+
+/** 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)];
+  return formField ? { ...issue, path: [formField, ...rest] } : issue;
+}
+
+/** A refused write: the generic message, and each issue for its field. */
+function invalidSettings(error: unknown): unknown {
+  if (!(error instanceof z.ZodError)) return INVALID_SETTINGS;
+  return { message: INVALID_SETTINGS, issues: error.issues.map(formIssue) };
+}
+
+function senderNotice(values: MailingSettingsValues): SettingsNotice[] {
+  return values.senderName && !values.senderEmail
+    ? [{ title: SENDER_NAME_IGNORED, color: WARNING_COLOR }]
+    : [];
+}
+
+function reassignedNotice(count: number): SettingsNotice[] {
+  return count ? [{ title: CATEGORIES_REASSIGNED, params: { count } }] : [];
+}
 
 export class MailingSettingsController extends Controller(
   `${API_BASE_PATH}/settings`,
@@ -33,34 +169,163 @@ export class MailingSettingsController extends Controller(
   @TenantScopedModel(TemplateModel)
   declare templates: TemplateModel;
 
+  @TenantScopedModel(SendModel)
+  declare sends: SendModel;
+
+  private get tenantId(): string {
+    return getRequestTenantId(this.ctx);
+  }
+
+  /**
+   * The origin a provider reaches the event route on: the dashboard's public
+   * URL (`clientBaseUrl`), whose proxy serves the route to anonymous callers
+   * as a declared public endpoint; else the API origin (`apiBaseUrl`), else
+   * this server's own. Always from the DMS configuration, never from
+   * forwarding headers: the webhook test posts to it from the server.
+   */
+  private async publicOrigin(): Promise<string> {
+    return (
+      (await GetClientBaseUrl()) ??
+      (await GetApiBaseUrl()) ??
+      this.ctx.url.origin
+    );
+  }
+
+  /** The address the provider posts to, as the form shows it. */
+  private async providerWebhookUrl(provider?: string): Promise<string> {
+    return webhookUrl(await this.publicOrigin(), provider, this.tenantId);
+  }
+
   @Get("")
-  read(): Promise<MailingSettingsValues> {
-    return getSettings(getRequestTenantId(this.ctx));
+  async read(): Promise<MailingSettingsResponse> {
+    const [values, capabilities] = await Promise.all([
+      getSettings(this.tenantId),
+      readCapabilities(),
+    ]);
+    return {
+      ...values,
+      webhookUrl: await this.providerWebhookUrl(capabilities?.name),
+      provider: capabilities?.name ?? "",
+      missingVariables: missingVariablesPolicy(values),
+    };
   }
 
-  @Post("")
-  async write(@JSONBody() body: unknown): Promise<MailingSettingsValues> {
-    const values = assertValidation(
-      body,
-      (value) => settingsSchema.parse(value),
-      () => INVALID_SETTINGS,
+  /**
+   * Applies what the form changed. The DMS form puts only the changed fields,
+   * `null` for a cleared one, so the body is a patch over the stored settings:
+   * each field sent is checked, the others are left as stored.
+   */
+  @Put("")
+  async update(@RawBody() raw: Buffer): Promise<SettingsWriteResponse> {
+    const patch = this.readPatch(raw);
+    const current = await getSettings(this.tenantId);
+    const merged = mergeSettingsPatch(current, patch);
+    const entries = patch.categories ?? current.categories;
+    const values = { ...merged, categories: keptCategories(entries) };
+    const saved = await saveSettings(this.tenantId, values);
+    const reassigned = patch.categories
+      ? await this.reassignCategories(values.categories, categoryMoves(entries))
+      : 0;
+    const [notice] = [...reassignedNotice(reassigned), ...senderNotice(saved)];
+    return { ...saved, ...(notice && { notice }) };
+  }
+
+  /** 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);
+    return assertValidation(
+      clearedToEmpty(body as Record<string, unknown>),
+      (value) => settingsPatchSchema.parse(value),
+      invalidSettings,
     );
-    const saved = await saveSettings(getRequestTenantId(this.ctx), values);
-    await this.dropRemovedCategories(values.categories);
-    return saved;
+  }
+
+  /** Issues a new webhook secret; the old one stops working at once. */
+  @Post("/webhook-secret/rotate")
+  async rotateSecret(): Promise<{ value: string }> {
+    const current = await getSettings(this.tenantId);
+    const value = randomBytes(WEBHOOK_SECRET_BYTES).toString("hex");
+    await saveSettings(this.tenantId, { ...current, webhookSecret: value });
+    return { value };
+  }
+
+  /** The last event the webhook accepted, and the last call it refused. */
+  @Get("/webhook-status")
+  async webhookStatus(): Promise<WebhookStatus> {
+    return readWebhookStatus(this.tenantId);
+  }
+
+  /**
+   * Posts a test event to the webhook URL the form shows, with the stored
+   * secret, as a provider would. It reaches no send.
+   */
+  @Post("/webhook-test")
+  async webhookTest(): Promise<WebhookTestResponse> {
+    const [values, capabilities] = await Promise.all([
+      getSettings(this.tenantId),
+      readCapabilities(),
+    ]);
+    const url = await this.providerWebhookUrl(capabilities?.name);
+    const outcome = await sendWebhookTest(url, values.webhookSecret);
+    return { ...outcome, status: await readWebhookStatus(this.tenantId) };
+  }
+
+  @Get("/retention-preview")
+  async retentionPreview(): Promise<RetentionPreview> {
+    const days = await this.previewDays();
+    const nextRunAt = nextRetentionRun();
+    const limit = retentionLimit(days, nextRunAt);
+    return {
+      days,
+      count: await this.sends.countOlderThan(limit),
+      nextRunAt: nextRunAt.toISOString(),
+    };
+  }
+
+  /** The `days` asked for, within the retention bounds, else the stored. */
+  private async previewDays(): Promise<number> {
+    const raw = this.ctx.url.searchParams.get(RETENTION_DAYS_PARAM);
+    if (raw === null)
+      return (await getSettings(this.tenantId)).logRetentionDays;
+    return assertValidation(
+      raw,
+      (value) => retentionDaysSchema.parse(value),
+      invalidSettings,
+    );
+  }
+
+  /**
+   * How many templates sit in each category, for the categories editor. An
+   * archived template is left out: it no longer shows in the gallery.
+   */
+  @Get("/category-usage")
+  async categoryUsage(): Promise<{ counts: Record<string, number> }> {
+    const templates = await this.templates.getAll();
+    const counts: Record<string, number> = {};
+    for (const template of templates) {
+      if (!template.category || template.status === ARCHIVED_STATUS) continue;
+      counts[template.category] = (counts[template.category] ?? 0) + 1;
+    }
+    return { counts };
   }
 
   /**
-   * A deleted category must not leave templates pointing at nothing: they fall
-   * back to no category.
+   * A deleted category must not leave templates pointing at nothing: they go
+   * to the category the form moved them to, else to none.
+   * @returns How many templates changed category
    */
-  private async dropRemovedCategories(
+  private async reassignCategories(
     categories: MailingSettingsValues["categories"],
-  ): Promise<void> {
+    moves: ReadonlyMap<string, string>,
+  ): Promise<number> {
     const templates = await this.templates.getAll();
-    const orphaned = reassignRemovedCategories(templates, categories);
-    for (const id of orphaned) {
-      await this.templates.update(id, { category: "" });
+    const changes = reassignRemovedCategories(templates, categories, moves);
+    for (const { templateId, category } of changes) {
+      await this.templates.update(templateId, { category });
     }
+    return changes.length;
   }
 }

package/src/routes/suppressions.ts

@@ -0,0 +1,87 @@
+import {
+  Context,
+  Controller,
+  Delete,
+  HTTPResult,
+  JSONBody,
+  Parameter,
+  Post,
+  type RequestContext,
+} from "@antelopejs/interface-api";
+import { assert, assertValidation } from "@antelopejs/interface-api-util";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+import { AuthUserWithPermission } from "@antelopejs/interface-dms/guards";
+import { getRequestTenantId } from "@antelopejs/interface-dms/request-tenant";
+import { TenantScopedModel } from "@antelopejs/interface-dms/tenant-scoped-model";
+import { z } from "zod";
+import { API_BASE_PATH, HTTP_CONFLICT, HTTP_NOT_FOUND } from "../constants";
+import { SuppressionModel } from "../db";
+import { SuppressionsPageController } from "../pages/suppressions";
+import { suppressAddress } from "../services/suppressions";
+
+const INVALID_SUPPRESSION = "$dms_mailing.suppressions.errors.invalid";
+const ALREADY_SUPPRESSED = "$dms_mailing.suppressions.errors.already";
+const NOT_SUPPRESSED = "$dms_mailing.suppressions.errors.not_found";
+const EMAIL_FIELD = "email";
+const MAX_NOTE_LENGTH = 500;
+/** A manual entry comes from no send. */
+const NO_SEND = "";
+
+const manualSuppressionSchema = z.object({
+  email: z.string().trim().email(),
+  note: z.string().trim().max(MAX_NOTE_LENGTH).optional(),
+});
+
+/** A refused entry: the generic message, and each issue under its field. */
+function invalidSuppression(error: unknown): unknown {
+  if (!(error instanceof z.ZodError)) return INVALID_SUPPRESSION;
+  return { message: INVALID_SUPPRESSION, issues: error.issues };
+}
+
+/** An address already on the list, told under the address field. */
+const alreadySuppressed = () => ({
+  message: ALREADY_SUPPRESSED,
+  issues: [{ path: [EMAIL_FIELD], message: ALREADY_SUPPRESSED }],
+});
+
+export class SuppressionsController extends Controller(
+  `${API_BASE_PATH}/suppressions`,
+) {
+  @Context()
+  declare ctx: RequestContext;
+
+  @AuthUserWithPermission(SuppressionsPageController)
+  declare user: User;
+
+  @TenantScopedModel(SuppressionModel)
+  declare suppressions: SuppressionModel;
+
+  /** Puts an address on the list by hand: nothing is sent to it any more. */
+  @Post("")
+  async add(@JSONBody() body: unknown): Promise<{ added: true }> {
+    const input = assertValidation(
+      body ?? {},
+      (value) => manualSuppressionSchema.parse(value),
+      invalidSuppression,
+    );
+    const isAdded = await suppressAddress(getRequestTenantId(this.ctx), {
+      email: input.email,
+      reason: "manual",
+      sendId: NO_SEND,
+      detail: input.note || undefined,
+      createdBy: this.user._id,
+    });
+    if (!isAdded) throw new HTTPResult(HTTP_CONFLICT, alreadySuppressed());
+    return { added: true };
+  }
+
+  /** Lifts an address off the list: the next send reaches it again. */
+  @Delete("/:id")
+  async remove(
+    @Parameter("id", "param") id: string,
+  ): Promise<{ removed: true }> {
+    const removed = await this.suppressions.delete(id);
+    assert(removed > 0, HTTP_NOT_FOUND, NOT_SUPPRESSED);
+    return { removed: true };
+  }
+}

package/src/routes/template-versions.ts

@@ -0,0 +1,116 @@
+import {
+  Context,
+  Controller,
+  Get,
+  JSONBody,
+  Parameter,
+  Post,
+  type RequestContext,
+} from "@antelopejs/interface-api";
+import { assert, assertValidation } from "@antelopejs/interface-api-util";
+import { AuthUserWithPermission } from "@antelopejs/interface-dms/guards";
+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";
+import { API_BASE_PATH, HTTP_NOT_FOUND } from "../constants";
+import type { TemplateChange } from "../engine";
+import { TemplateModel, TemplateVersionModel } from "../db";
+import { TemplatesPageController } from "../pages/templates";
+import {
+  displayName,
+  parseVersionChanges,
+  parseVersionVariables,
+  restoreVersionAsDraft,
+  requireTemplate,
+} from "../services/templates";
+import type { VariableDefinition } from "../types";
+import {
+  restoreVersionSchema,
+  versionNumberSchema,
+} from "../validation/templates.schema";
+import { assertCurrentDraft } from "./templates";
+
+const VERSION_NOT_FOUND = "$dms_mailing.errors.version_not_found";
+
+export interface TemplateVersionSummary {
+  version: number;
+  publishedAt: Date;
+  publishedBy: string;
+  locales: string;
+  changes: TemplateChange[];
+  /** The declarations the version shipped with. */
+  variables: VariableDefinition[];
+}
+
+export interface RestoredVersion {
+  /** The draft revision the editor carries on with. */
+  revision: number;
+}
+
+/** A template's published versions: its history, and restoring one. */
+export class TemplateVersionsController extends Controller(
+  `${API_BASE_PATH}/templates`,
+) {
+  @Context()
+  declare ctx: RequestContext;
+
+  @AuthUserWithPermission(TemplatesPageController)
+  declare user: User;
+
+  @TenantScopedModel(TemplateModel)
+  declare templates: TemplateModel;
+
+  @TenantScopedModel(TemplateVersionModel)
+  declare versions: TemplateVersionModel;
+
+  @Get("/:id/versions")
+  async history(
+    @Parameter("id", "param") id: string,
+  ): Promise<{ versions: TemplateVersionSummary[] }> {
+    await requireTemplate(this.templates, id);
+    const rows = await this.versions.listForTemplate(id);
+    return {
+      versions: rows.map((row) => ({
+        version: row.version,
+        publishedAt: row.publishedAt,
+        publishedBy: row.publishedBy,
+        locales: row.locales,
+        changes: parseVersionChanges(row),
+        variables: parseVersionVariables(row),
+      })),
+    };
+  }
+
+  /**
+   * Copies a published version, content and declarations, into the draft:
+   * customers keep the live version until the normal review publishes it.
+   * Like a save, it is refused behind a draft saved elsewhere.
+   */
+  @Post("/:id/versions/:version/restore")
+  async restore(
+    @Parameter("id", "param") id: string,
+    @Parameter("version", "param") version: string,
+    @JSONBody() body: unknown,
+  ): Promise<RestoredVersion> {
+    const { revision } = assertValidation(body ?? {}, (value) =>
+      restoreVersionSchema.parse(value),
+    );
+    const number = assertValidation(
+      version,
+      (value) => versionNumberSchema.parse(value),
+      () => VERSION_NOT_FOUND,
+      HTTP_NOT_FOUND,
+    );
+    const template = await requireTemplate(this.templates, id);
+    assertCurrentDraft(template, revision);
+    const row = await this.versions.getVersion(id, number);
+    assert(row, HTTP_NOT_FOUND, VERSION_NOT_FOUND);
+    const next = await restoreVersionAsDraft(
+      getRequestTenantId(this.ctx),
+      template,
+      row,
+      displayName(this.user),
+    );
+    return { revision: next };
+  }
+}