@antelopejs/dms-mailing 0.3.3 → 0.4.0

package/src/db/models/suppressions.model.ts

@@ -0,0 +1,53 @@
+import { createHash } from "node:crypto";
+import { BasicDataModel } from "@antelopejs/interface-database-decorators";
+import { MAILING_SUPPRESSIONS_TABLE_NAME, MailingSuppression } from "../tables";
+
+type NewSuppression = Omit<MailingSuppression, "_id" | "createdAt">;
+
+const ID_LENGTH = 32;
+
+/** The address as the list keeps it: trimmed and lower-cased. */
+export function normalizeAddress(email: string): string {
+  return email.trim().toLowerCase();
+}
+
+/** The id of an address's entry: the same whoever adds it. */
+export function suppressionIdOf(email: string): string {
+  return createHash("sha256")
+    .update(normalizeAddress(email))
+    .digest("hex")
+    .slice(0, ID_LENGTH);
+}
+
+export class SuppressionModel extends BasicDataModel(
+  MailingSuppression,
+  MAILING_SUPPRESSIONS_TABLE_NAME,
+) {
+  async findByEmail(email: string): Promise<MailingSuppression | undefined> {
+    return this.get(suppressionIdOf(email));
+  }
+
+  /** The entries of the addresses given, whatever their case. */
+  async listByEmails(emails: string[]): Promise<MailingSuppression[]> {
+    const unique = [...new Set(emails.map(normalizeAddress))];
+    if (!unique.length) return [];
+    return this.getBy("email", ...unique);
+  }
+
+  /**
+   * Puts an address on the list unless it already is.
+   * @returns Whether this call added it
+   */
+  async add(entry: NewSuppression): Promise<boolean> {
+    const email = normalizeAddress(entry.email);
+    const id = suppressionIdOf(email);
+    if (await this.get(id)) return false;
+    try {
+      await this.insert({ ...entry, email, _id: id });
+      return true;
+    } catch (error) {
+      if (await this.get(id)) return false;
+      throw error;
+    }
+  }
+}

package/src/db/models/template-versions.model.ts

@@ -0,0 +1,23 @@
+import { BasicDataModel } from "@antelopejs/interface-database-decorators";
+import {
+  MAILING_TEMPLATE_VERSIONS_TABLE_NAME,
+  MailingTemplateVersion,
+} from "../tables";
+
+export class TemplateVersionModel extends BasicDataModel(
+  MailingTemplateVersion,
+  MAILING_TEMPLATE_VERSIONS_TABLE_NAME,
+) {
+  async listForTemplate(templateId: string): Promise<MailingTemplateVersion[]> {
+    const rows = await this.getBy("templateId", templateId);
+    return rows.sort((left, right) => right.version - left.version);
+  }
+
+  async getVersion(
+    templateId: string,
+    version: number,
+  ): Promise<MailingTemplateVersion | undefined> {
+    const rows = await this.getBy("templateId", templateId);
+    return rows.find((row) => row.version === version);
+  }
+}

package/src/db/models/templates.model.ts

@@ -1,6 +1,12 @@
 import { BasicDataModel } from "@antelopejs/interface-database-decorators";
 import { MAILING_TEMPLATES_TABLE_NAME, MailingTemplate } from "../tables";
 
+/** The attention fields of a template, as the refresh writes them. */
+export type TemplateAttentionFields = Pick<
+  MailingTemplate,
+  "attention" | "needsAttention"
+>;
+
 export class TemplateModel extends BasicDataModel(
   MailingTemplate,
   MAILING_TEMPLATES_TABLE_NAME,
@@ -9,4 +15,15 @@ export class TemplateModel extends BasicDataModel(
     const rows = await this.getBy("slug", slug);
     return rows[0];
   }
+
+  /**
+   * Writes the attention fields straight to the table: they describe the
+   * template, they are no edit of it, so `updatedAt` stays where it was.
+   */
+  async writeAttention(
+    id: string,
+    fields: TemplateAttentionFields,
+  ): Promise<void> {
+    await this.table.get(id).update(fields).run();
+  }
 }

package/src/db/models/webhook-status.model.ts

@@ -0,0 +1,25 @@
+import { BasicDataModel } from "@antelopejs/interface-database-decorators";
+import {
+  MAILING_WEBHOOK_STATUS_TABLE_NAME,
+  MailingWebhookStatus,
+} from "../tables";
+
+type WebhookStatusPatch = Partial<Omit<MailingWebhookStatus, "_id">>;
+
+export class WebhookStatusModel extends BasicDataModel(
+  MailingWebhookStatus,
+  MAILING_WEBHOOK_STATUS_TABLE_NAME,
+) {
+  /** Writes the tenant's row, creating it on the first call. */
+  async record(tenantId: string, patch: WebhookStatusPatch): Promise<void> {
+    if (await this.get(tenantId)) {
+      await this.update(tenantId, patch);
+      return;
+    }
+    try {
+      await this.insert({ ...patch, _id: tenantId });
+    } catch {
+      await this.update(tenantId, patch);
+    }
+  }
+}

package/src/db/tables/index.ts

@@ -1,4 +1,7 @@
 export * from "./send-events.table";
 export * from "./sends.table";
 export * from "./settings.table";
+export * from "./suppressions.table";
+export * from "./template-versions.table";
 export * from "./templates.table";
+export * from "./webhook-status.table";

package/src/db/tables/send-events.table.ts

@@ -5,7 +5,7 @@ import {
   Table,
 } from "@antelopejs/interface-database-decorators";
 import { TENANT_SCHEMA_NAME } from "@antelopejs/interface-dms/constants";
-import type { SendEventType } from "../../types";
+import type { SendStatus } from "../../types";
 
 export const MAILING_SEND_EVENTS_TABLE_NAME = "mailing_send_events";
 
@@ -18,8 +18,12 @@ export class MailingSendEvent extends Table {
   @Field("string")
   declare sendId: string;
 
+  /**
+   * A provider event, or the status the send started with (`suppressed`
+   * when nothing was sent).
+   */
   @Field("string")
-  declare type: SendEventType;
+  declare type: SendStatus;
 
   @Field("date")
   declare at: Date;

package/src/db/tables/sends.table.ts

@@ -6,7 +6,7 @@ import {
   Table,
 } from "@antelopejs/interface-database-decorators";
 import { TENANT_SCHEMA_NAME } from "@antelopejs/interface-dms/constants";
-import type { SendStatus } from "../../types";
+import type { SendStage, SendStatus } from "../../types";
 
 export const MAILING_SENDS_TABLE_NAME = "mailing_sends";
 
@@ -27,9 +27,18 @@ export class MailingSend extends Table {
   @Field("string")
   declare templateSlug: string;
 
+  /** Locale the e-mail was rendered in. */
   @Field("string")
   declare locale: string;
 
+  /** Locale the caller asked for; differs from `locale` on a fallback. */
+  @Field("string")
+  declare requestedLocale: string;
+
+  /** Template version the send used; 0 for a test send of a draft. */
+  @Field("number")
+  declare templateVersion: number;
+
   @Index()
   @Field("string")
   declare recipientEmail: string;
@@ -41,6 +50,11 @@ export class MailingSend extends Table {
   @Field("string")
   declare status: SendStatus;
 
+  /** The send log tab a status belongs to, derived from `status`. */
+  @Index()
+  @Field("string")
+  declare stage: SendStage;
+
   @Field("string")
   declare provider?: string;
 
@@ -48,8 +62,9 @@ export class MailingSend extends Table {
   @Field("string")
   declare providerMessageId?: string;
 
+  /** `null` for a send that never reached the provider (suppressed). */
   @Field("number")
-  declare latencyMs: number;
+  declare latencyMs: number | null;
 
   @Field("string")
   declare error?: string;
@@ -81,4 +96,24 @@ export class MailingSend extends Table {
 
   @Field("boolean")
   declare isTest: boolean;
+
+  /** A bounce the receiving server called temporary (a full mailbox, 4.x.x). */
+  @Field("boolean")
+  declare isSoftBounce?: boolean;
+
+  /** The send this one repeats, sent again or to another address. */
+  @Field("string")
+  declare replayOf?: string;
+
+  /** The send that repeated this problem, once someone sent it again. */
+  @Field("string")
+  declare replayedBy?: string;
+
+  /** When someone dealt with this problem by sending it again. */
+  @Field("date")
+  declare resolvedAt?: Date;
+
+  /** Who sent it again: a user id. */
+  @Field("string")
+  declare resolvedBy?: string;
 }

package/src/db/tables/suppressions.table.ts

@@ -0,0 +1,46 @@
+import {
+  CreationTime,
+  Field,
+  Index,
+  RegisterTable,
+  Table,
+} from "@antelopejs/interface-database-decorators";
+import { TENANT_SCHEMA_NAME } from "@antelopejs/interface-dms/constants";
+import type { SuppressionReason } from "../../types";
+
+export const MAILING_SUPPRESSIONS_TABLE_NAME = "mailing_suppressions";
+
+/**
+ * An address nothing is sent to any more. Its id derives from the address, so
+ * an address is on the list once whoever adds it first.
+ */
+@RegisterTable(MAILING_SUPPRESSIONS_TABLE_NAME, TENANT_SCHEMA_NAME)
+export class MailingSuppression extends Table {
+  @Field("string")
+  declare _id: string;
+
+  /** Trimmed and lower-cased. */
+  @Index()
+  @Field("string")
+  declare email: string;
+
+  @Field("string")
+  declare reason: SuppressionReason;
+
+  /** The send whose event put the address on the list. */
+  @Field("string")
+  declare sendId?: string;
+
+  /** The provider's words (`550 5.1.1 …`) or the note of a manual entry. */
+  @Field("string")
+  declare detail?: string;
+
+  /** The user who added it by hand. */
+  @Field("string")
+  declare createdBy?: string;
+
+  @Index()
+  @CreationTime()
+  @Field("date")
+  declare createdAt: Date;
+}

package/src/db/tables/template-versions.table.ts

@@ -0,0 +1,44 @@
+import {
+  Field,
+  Index,
+  RegisterTable,
+  Table,
+} from "@antelopejs/interface-database-decorators";
+import { TENANT_SCHEMA_NAME } from "@antelopejs/interface-dms/constants";
+
+export const MAILING_TEMPLATE_VERSIONS_TABLE_NAME = "mailing_template_versions";
+
+/** One published version of a template, written once and never updated. */
+@RegisterTable(MAILING_TEMPLATE_VERSIONS_TABLE_NAME, TENANT_SCHEMA_NAME)
+export class MailingTemplateVersion extends Table {
+  @Field("string")
+  declare _id: string;
+
+  @Index()
+  @Field("string")
+  declare templateId: string;
+
+  @Field("number")
+  declare version: number;
+
+  /** JSON-serialized TemplateContent of this version. */
+  @Field("string")
+  declare json_content: string;
+
+  /** JSON-serialized VariableDefinition[] declared when it was published. */
+  @Field("string")
+  declare json_variables: string;
+
+  @Field("string")
+  declare locales: string;
+
+  @Field("date")
+  declare publishedAt: Date;
+
+  @Field("string")
+  declare publishedBy: string;
+
+  /** JSON-serialized TemplateChange[] this version brought. */
+  @Field("string")
+  declare json_changes: string;
+}

package/src/db/tables/templates.table.ts

@@ -40,23 +40,68 @@ export class MailingTemplate extends Table {
   @Field("string")
   declare status: TemplateStatus;
 
-  /** JSON-serialized TemplateContent, replaced in place on every save. */
+  /**
+   * JSON-serialized TemplateContent customers receive: the last published
+   * version. Only a publish writes it.
+   */
   @Field("string")
   declare json_content: string;
 
-  /** JSON-serialized VariableDefinition[] declared for this template. */
+  /**
+   * JSON-serialized TemplateContent the editor saves while drafting. Blank when
+   * nothing is waiting to be published.
+   */
+  @Field("string")
+  declare json_draft?: string;
+
+  /** Whether `json_draft` holds changes customers do not receive yet. */
+  @Field("boolean")
+  declare isDraftPending?: boolean;
+
+  @Field("date")
+  declare draftUpdatedAt?: Date;
+
+  @Field("string")
+  declare draftUpdatedBy?: string;
+
+  /**
+   * Moves on with every write of `json_draft`; a save or a publish carrying
+   * an older one is refused. 0 for a new template.
+   */
+  @Field("number")
+  declare draftRevision: number;
+
+  /** Version customers receive; 0 until a first publish. */
+  @Field("number")
+  declare publishedVersion: number;
+
+  @Field("string")
+  declare publishedBy?: string;
+
+  /**
+   * JSON-serialized VariableDefinition[] of the contract callers send
+   * against: the published declarations (the working ones until a first
+   * publish). Only a publish changes them on a published template.
+   */
   @Field("string")
   declare json_variables: string;
 
+  /**
+   * JSON-serialized VariableDefinition[] the draft declares, published with
+   * its content. Blank when the draft declares what `json_variables` does.
+   */
+  @Field("string")
+  declare json_variables_draft?: string;
+
   /** JSON-serialized data set used by the preview and the test send. */
   @Field("string")
   declare json_test_data: string;
 
   /**
-   * Locale codes present in the current version's content, comma-separated.
+   * Locale codes present in the content customers receive (the draft's until
+   * a first publish), comma-separated.
    * Denormalised so a template row can show its coverage without loading the
-   * version. Blank on rows written before this field existed: unknown, not
-   * "none".
+   * version.
    */
   @Field("string")
   declare locales: string;
@@ -66,4 +111,21 @@ export class MailingTemplate extends Table {
 
   @Field("date")
   declare publishedAt?: Date;
+
+  /**
+   * Why the template needs a look (`stale_draft`, `never_sent`,
+   * `missing_locale`), comma-separated; blank when nothing does. Kept by the
+   * attention refresh, never by an edit.
+   */
+  @Field("string")
+  declare attention: string;
+
+  /** Whether `attention` names a reason: what the templates tab filters on. */
+  @Index()
+  @Field("boolean")
+  declare needsAttention: boolean;
+
+  /** When the template last left `live` by an unpublish. */
+  @Field("date")
+  declare unpublishedAt?: Date;
 }

package/src/db/tables/webhook-status.table.ts

@@ -0,0 +1,44 @@
+import {
+  Field,
+  RegisterTable,
+  Table,
+} from "@antelopejs/interface-database-decorators";
+import { TENANT_SCHEMA_NAME } from "@antelopejs/interface-dms/constants";
+import type { WebhookRefusal } from "../../types";
+
+export const MAILING_WEBHOOK_STATUS_TABLE_NAME = "mailing_webhook_status";
+
+/**
+ * The last request the tenant's webhook accepted and the last it refused, one
+ * row keyed by the tenant id. Kept apart from the settings so a webhook call
+ * never changes their revision.
+ */
+@RegisterTable(MAILING_WEBHOOK_STATUS_TABLE_NAME, TENANT_SCHEMA_NAME)
+export class MailingWebhookStatus extends Table {
+  @Field("string")
+  declare _id: string;
+
+  @Field("date")
+  declare receivedAt?: Date;
+
+  @Field("string")
+  declare receivedProvider?: string;
+
+  @Field("string")
+  declare receivedType?: string;
+
+  @Field("boolean")
+  declare isReceivedMatched?: boolean;
+
+  @Field("boolean")
+  declare isReceivedTest?: boolean;
+
+  @Field("date")
+  declare refusedAt?: Date;
+
+  @Field("string")
+  declare refusedProvider?: string;
+
+  @Field("string")
+  declare refusedReason?: WebhookRefusal;
+}

package/src/engine/changes.ts

@@ -0,0 +1,198 @@
+import type {
+  Block,
+  BlockType,
+  LocaleContent,
+  TemplateContent,
+  VariableDefinition,
+} from "../types";
+import { walkBlocks } from "./walk";
+
+export type TemplateChangeKind =
+  | "locale_added"
+  | "locale_removed"
+  | "subject"
+  | "preheader"
+  | "block_added"
+  | "block_removed"
+  | "block_changed"
+  | "blocks_reordered"
+  | "variable_added"
+  | "variable_removed"
+  | "variable_changed";
+
+/**
+ * One difference between the published template and the draft: per locale
+ * for the content, per path for the variable declarations (the contract
+ * callers send against), which belong to no locale.
+ */
+export interface TemplateChange {
+  /** Blank for a change of the variable declarations. */
+  locale: string;
+  kind: TemplateChangeKind;
+  blockId?: string;
+  blockType?: BlockType;
+  /** The declared path a variable change is about. */
+  variable?: string;
+}
+
+/** The locale a change of the variable declarations carries: none. */
+export const CONTRACT_LOCALE = "";
+
+interface BlockSnapshot {
+  type: BlockType;
+  signature: string;
+}
+
+const NESTED_KEYS = new Set(["children", "elseChildren"]);
+
+/**
+ * A value with its object keys sorted at every depth, so two blocks equal but
+ * for the order their fields were written in read the same.
+ */
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .map((key) => [key, canonical((value as Record<string, unknown>)[key])]),
+  );
+}
+
+function ownFields(block: Block): string {
+  const entries = Object.entries(block).filter(
+    ([key]) => !NESTED_KEYS.has(key),
+  );
+  return JSON.stringify(canonical(Object.fromEntries(entries)));
+}
+
+function snapshotBlocks(blocks: Block[]): Map<string, BlockSnapshot> {
+  const snapshots = new Map<string, BlockSnapshot>();
+  walkBlocks(blocks, (block) => {
+    snapshots.set(block.id, { type: block.type, signature: ownFields(block) });
+  });
+  return snapshots;
+}
+
+function orderOf(blocks: Block[]): string[] {
+  const ids: string[] = [];
+  walkBlocks(blocks, (block) => ids.push(block.id));
+  return ids;
+}
+
+function blockChanges(
+  locale: string,
+  before: Map<string, BlockSnapshot>,
+  after: Map<string, BlockSnapshot>,
+): TemplateChange[] {
+  const removed = [...before]
+    .filter(([id]) => !after.has(id))
+    .map(([id, snapshot]) =>
+      blockChange(locale, "block_removed", id, snapshot),
+    );
+  const touched = [...after].flatMap(([id, snapshot]) => {
+    const previous = before.get(id);
+    if (!previous) return [blockChange(locale, "block_added", id, snapshot)];
+    if (previous.signature === snapshot.signature) return [];
+    return [blockChange(locale, "block_changed", id, snapshot)];
+  });
+  return [...touched, ...removed];
+}
+
+function blockChange(
+  locale: string,
+  kind: TemplateChangeKind,
+  blockId: string,
+  snapshot: BlockSnapshot,
+): TemplateChange {
+  return { locale, kind, blockId, blockType: snapshot.type };
+}
+
+function isReordered(before: LocaleContent, after: LocaleContent): boolean {
+  const kept = new Set(orderOf(after.blocks));
+  const previous = orderOf(before.blocks).filter((id) => kept.has(id));
+  const surviving = new Set(previous);
+  const next = orderOf(after.blocks).filter((id) => surviving.has(id));
+  return previous.join() !== next.join();
+}
+
+function localeChanges(
+  locale: string,
+  before: LocaleContent,
+  after: LocaleContent,
+): TemplateChange[] {
+  const changes: TemplateChange[] = [];
+  if (before.subject !== after.subject)
+    changes.push({ locale, kind: "subject" });
+  if (before.preheader !== after.preheader)
+    changes.push({ locale, kind: "preheader" });
+  changes.push(
+    ...blockChanges(
+      locale,
+      snapshotBlocks(before.blocks),
+      snapshotBlocks(after.blocks),
+    ),
+  );
+  if (isReordered(before, after))
+    changes.push({ locale, kind: "blocks_reordered" });
+  return changes;
+}
+
+/**
+ * What publishing `draft` would change for customers who receive `published`,
+ * locale by locale. An empty list means the draft carries nothing new.
+ */
+export function diffContents(
+  published: TemplateContent,
+  draft: TemplateContent,
+): TemplateChange[] {
+  const locales = new Set([
+    ...Object.keys(published.locales),
+    ...Object.keys(draft.locales),
+  ]);
+  return [...locales].sort().flatMap((locale) => {
+    const before = published.locales[locale];
+    const after = draft.locales[locale];
+    if (!before) return [{ locale, kind: "locale_added" as const }];
+    if (!after) return [{ locale, kind: "locale_removed" as const }];
+    return localeChanges(locale, before, after);
+  });
+}
+
+function declarationsByPath(
+  variables: VariableDefinition[],
+): Map<string, string> {
+  return new Map(
+    variables.map((variable) => [
+      variable.path,
+      JSON.stringify(canonical(variable)),
+    ]),
+  );
+}
+
+function variableChange(
+  kind: TemplateChangeKind,
+  variable: string,
+): TemplateChange {
+  return { locale: CONTRACT_LOCALE, kind, variable };
+}
+
+/**
+ * What publishing the draft's variable declarations would change in the
+ * contract, path by path. Their order is not part of it.
+ */
+export function diffVariables(
+  published: VariableDefinition[],
+  draft: VariableDefinition[],
+): TemplateChange[] {
+  const before = declarationsByPath(published);
+  const after = declarationsByPath(draft);
+  const paths = [...new Set([...before.keys(), ...after.keys()])].sort();
+  return paths.flatMap((path) => {
+    const previous = before.get(path);
+    const next = after.get(path);
+    if (previous === undefined) return [variableChange("variable_added", path)];
+    if (next === undefined) return [variableChange("variable_removed", path)];
+    return previous === next ? [] : [variableChange("variable_changed", path)];
+  });
+}

package/src/engine/conditions.ts

@@ -14,17 +14,11 @@ const EVALUATORS: Record<ConditionOperator, Evaluator> = {
   lt: (actual, expected) => asNumber(actual) < asNumber(expected),
 };
 
-/**
- * An unknown operator hides the block rather than throwing. Every entry point
- * validates the operator against a `z.enum`, so this only guards content stored
- * before an operator existed: a missing block is inspectable in the preview,
- * a TypeError mid-send is a mail nobody receives.
- */
+/** Whether `data` passes the condition a block is shown under. */
 export function evaluateCondition(
   condition: Condition,
   data: Record<string, unknown>,
 ): boolean {
   const evaluate = EVALUATORS[condition.operator];
-  if (!evaluate) return false;
   return evaluate(getPath(data, condition.path), condition.value);
 }