@antelopejs/dms-mailing 0.2.2

package/src/data-types/category-type.ts

@@ -0,0 +1,44 @@
+import { CustomComponent } from "@antelopejs/interface-dms/base/custom";
+import {
+  DataType,
+  RegisterDataType,
+} from "@antelopejs/interface-dms/base/data-types";
+import { DefaultDataCompareTypes } from "@antelopejs/interface-dms/base/data-types/compare-types";
+import { z } from "zod";
+import { TEMPLATE_CATEGORY_TYPE_ID } from "../constants";
+
+/**
+ * A template's category. Deliberately **not** a `SelectType`: that builds its
+ * validation from a `z.enum` over build-time items, so every category the user
+ * adds in Settings afterwards would be rejected on save. The authority is the
+ * tenant's settings, so the value is validated as a plain optional string and
+ * the input fetches the current list.
+ *
+ * `IsEmpty` / `IsNotEmpty` are what the table filter offers as
+ * "uncategorised".
+ */
+@RegisterDataType(TEMPLATE_CATEGORY_TYPE_ID)
+export class TemplateCategoryType extends DataType {
+  constructor(public readonly options: Record<string, unknown> = {}) {
+    super(
+      [
+        DefaultDataCompareTypes.Is,
+        DefaultDataCompareTypes.IsNot,
+        DefaultDataCompareTypes.IsEmpty,
+        DefaultDataCompareTypes.IsNotEmpty,
+      ],
+      DefaultDataCompareTypes.Is,
+      options,
+    );
+  }
+
+  protected defaultInputComponent() {
+    return CustomComponent("DmsMailingCategoryInput")
+      .options(this.options)
+      .serializeSync();
+  }
+
+  getValidation() {
+    return z.string().optional();
+  }
+}

package/src/data-types/index.ts

@@ -0,0 +1,2 @@
+export * from "./categories-type";
+export * from "./category-type";

package/src/db/index.ts

@@ -0,0 +1,2 @@
+export * from "./models";
+export * from "./tables";

package/src/db/models/index.ts

@@ -0,0 +1,4 @@
+export * from "./send-events.model";
+export * from "./sends.model";
+export * from "./settings.model";
+export * from "./templates.model";

package/src/db/models/send-events.model.ts

@@ -0,0 +1,46 @@
+import { BasicDataModel } from "@antelopejs/interface-database-decorators";
+import { MAILING_SEND_EVENTS_TABLE_NAME, MailingSendEvent } from "../tables";
+import { SendModel } from "./sends.model";
+
+type NewSendEvent = Omit<MailingSendEvent, "_id">;
+
+const FIRST_ROW_OFFSET = 0;
+
+export class SendEventModel extends BasicDataModel(
+  MailingSendEvent,
+  MAILING_SEND_EVENTS_TABLE_NAME,
+) {
+  async getBySend(sendId: string): Promise<MailingSendEvent[]> {
+    return this.getBy("sendId", sendId);
+  }
+
+  /** Removes a late event if retention finished while its writer was paused. */
+  async insertForActiveSend(event: NewSendEvent): Promise<boolean> {
+    const [id] = await this.insert(event);
+    const send = await new SendModel(this.database).get(event.sendId);
+    if (send && !send.isRetiring) return true;
+    await this.delete(id);
+    return false;
+  }
+
+  /** Keyset pagination remains stable when overlapping sweeps delete earlier rows. */
+  listAfter(after: string, size: number): Promise<MailingSendEvent[]> {
+    return this.table
+      .filter((row) => row.key("_id").gt(after))
+      .orderBy("_id", "asc")
+      .slice(FIRST_ROW_OFFSET, size)
+      .run();
+  }
+
+  /**
+   * Drops a send's whole history in one statement. Retention purges up to
+   * 20 000 sends a night; deleting their events one row at a time turned that
+   * into six figures of round-trips.
+   */
+  deleteBySend(sendId: string): Promise<number> {
+    return this.table
+      .filter((row) => row.key("sendId").eq(sendId))
+      .delete()
+      .run();
+  }
+}

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

@@ -0,0 +1,147 @@
+import { randomUUID } from "node:crypto";
+import { BasicDataModel } from "@antelopejs/interface-database-decorators";
+import type {
+  AtomicMutationOutcome,
+  ValueProxy,
+} from "@antelopejs/interface-database";
+import { MAILING_SENDS_TABLE_NAME, MailingSend } from "../tables";
+
+const FIRST_ROW_OFFSET = 0;
+const SINGLE_ROW = 1;
+
+type NewSend = Omit<
+  MailingSend,
+  "_id" | "createdAt" | "revision" | "isRetiring" | "lastActivityAt"
+>;
+
+type SendActivity = Pick<
+  MailingSend,
+  "status" | "opens" | "clicks" | "lastEventAt" | "provider"
+>;
+
+function canRetire(row: ValueProxy<MailingSend>, limit: Date) {
+  return row
+    .key("createdAt")
+    .lt(limit)
+    .and(row.key("status").ne("queued"))
+    .and(row.key("lastEventAt").default(row.key("createdAt")).lt(limit))
+    .and(row.key("lastActivityAt").default(row.key("createdAt")).lt(limit));
+}
+
+function isInactive(send: MailingSend, limit: Date): boolean {
+  return (
+    send.status !== "queued" &&
+    send.createdAt < limit &&
+    (send.lastEventAt ?? send.createdAt) < limit &&
+    (send.lastActivityAt ?? send.createdAt) < limit
+  );
+}
+
+function wasApplied(outcome: AtomicMutationOutcome): boolean {
+  if (outcome === "unknown")
+    throw new Error("Mailing mutation outcome is unknown; not retrying");
+  return outcome === "applied";
+}
+
+export class SendModel extends BasicDataModel(
+  MailingSend,
+  MAILING_SENDS_TABLE_NAME,
+) {
+  /** Creates a new immutable send identity and initializes its revision. */
+  insertSend(send: NewSend): Promise<string[]> {
+    return this.table
+      .insert({
+        ...send,
+        _id: randomUUID(),
+        createdAt: new Date(),
+        revision: randomUUID(),
+      })
+      .run();
+  }
+
+  /** Reads the stored row, including the revision the mutation contract compares. */
+  getSnapshot(sendId: string): Promise<MailingSend | undefined> {
+    return this.table.get(sendId).run();
+  }
+
+  async getByProviderMessageId(
+    messageId: string,
+  ): Promise<MailingSend | undefined> {
+    const rows = await this.table
+      .getAll(messageId, "providerMessageId")
+      .slice(FIRST_ROW_OFFSET, SINGLE_ROW)
+      .run();
+    return rows[0];
+  }
+
+  listBetween(from: Date, to: Date): Promise<MailingSend[]> {
+    return this.table
+      .filter((row) => row.key("createdAt").ge(from))
+      .filter((row) => row.key("createdAt").lt(to))
+      .run();
+  }
+
+  listOlderThan(limit: Date, pageSize: number): Promise<MailingSend[]> {
+    return this.table
+      .filter((row) => row.key("isRetiring").eq(true).or(canRetire(row, limit)))
+      .slice(FIRST_ROW_OFFSET, pageSize)
+      .run();
+  }
+
+  /** Atomically closes an inactive send to new events; retirement is irreversible. */
+  async retire(sendId: string, limit: Date): Promise<boolean> {
+    const send = await this.getSnapshot(sendId);
+    if (!send) return false;
+    if (send.isRetiring) return true;
+    if (!isInactive(send, limit)) return false;
+    const outcome = await this.table
+      .atomicMutation(sendId, {
+        type: "update",
+        revisionField: "revision",
+        expectedRevision: send.revision,
+        nextRevision: randomUUID(),
+        patch: { isRetiring: true },
+      })
+      .run();
+    if (wasApplied(outcome)) return true;
+    return (await this.get(sendId))?.isRetiring === true;
+  }
+
+  /** Returns the number of retired sends actually deleted, including overlapping sweeps. */
+  async deleteRetired(sendId: string): Promise<number> {
+    const send = await this.getSnapshot(sendId);
+    if (!send?.isRetiring) return 0;
+    const outcome = await this.table
+      .atomicMutation(sendId, {
+        type: "delete",
+        revisionField: "revision",
+        expectedRevision: send.revision,
+      })
+      .run();
+    return Number(wasApplied(outcome));
+  }
+
+  /** Accepts activity only before retirement, using ingestion time rather than provider time. */
+  async recordActivity(
+    send: MailingSend,
+    changes: SendActivity,
+  ): Promise<boolean> {
+    if (send.isRetiring) return false;
+    const patch = Object.fromEntries(
+      Object.entries({
+        ...changes,
+        lastActivityAt: new Date(),
+      }).filter(([, value]) => value !== undefined),
+    );
+    const outcome = await this.table
+      .atomicMutation(send._id, {
+        type: "update",
+        revisionField: "revision",
+        expectedRevision: send.revision,
+        nextRevision: randomUUID(),
+        patch,
+      })
+      .run();
+    return wasApplied(outcome);
+  }
+}

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

@@ -0,0 +1,12 @@
+import { BasicDataModel } from "@antelopejs/interface-database-decorators";
+import { MAILING_SETTINGS_TABLE_NAME, MailingSettings } from "../tables";
+
+export class SettingsModel extends BasicDataModel(
+  MailingSettings,
+  MAILING_SETTINGS_TABLE_NAME,
+) {
+  async getSingleton(): Promise<MailingSettings | undefined> {
+    const rows = await this.getAll();
+    return rows[0];
+  }
+}

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

@@ -0,0 +1,12 @@
+import { BasicDataModel } from "@antelopejs/interface-database-decorators";
+import { MAILING_TEMPLATES_TABLE_NAME, MailingTemplate } from "../tables";
+
+export class TemplateModel extends BasicDataModel(
+  MailingTemplate,
+  MAILING_TEMPLATES_TABLE_NAME,
+) {
+  async getBySlug(slug: string): Promise<MailingTemplate | undefined> {
+    const rows = await this.getBy("slug", slug);
+    return rows[0];
+  }
+}

package/src/db/tables/index.ts

@@ -0,0 +1,4 @@
+export * from "./send-events.table";
+export * from "./sends.table";
+export * from "./settings.table";
+export * from "./templates.table";

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

@@ -0,0 +1,31 @@
+import {
+  Field,
+  Index,
+  RegisterTable,
+  Table,
+} from "@antelopejs/interface-database-decorators";
+import { TENANT_SCHEMA_NAME } from "@antelopejs/interface-dms/constants";
+import type { SendEventType } from "../../types";
+
+export const MAILING_SEND_EVENTS_TABLE_NAME = "mailing_send_events";
+
+@RegisterTable(MAILING_SEND_EVENTS_TABLE_NAME, TENANT_SCHEMA_NAME)
+export class MailingSendEvent extends Table {
+  @Field("string")
+  declare _id: string;
+
+  @Index()
+  @Field("string")
+  declare sendId: string;
+
+  @Field("string")
+  declare type: SendEventType;
+
+  @Index()
+  @Field("date")
+  declare at: Date;
+
+  /** JSON-serialized SendEventDetails reported by the provider. */
+  @Field("string")
+  declare json_details: string;
+}

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

@@ -0,0 +1,85 @@
+import {
+  CreationTime,
+  Field,
+  Index,
+  RegisterTable,
+  Table,
+} from "@antelopejs/interface-database-decorators";
+import { TENANT_SCHEMA_NAME } from "@antelopejs/interface-dms/constants";
+import type { SendStatus } from "../../types";
+
+export const MAILING_SENDS_TABLE_NAME = "mailing_sends";
+
+@RegisterTable(MAILING_SENDS_TABLE_NAME, TENANT_SCHEMA_NAME)
+export class MailingSend extends Table {
+  @Field("string")
+  declare _id: string;
+
+  @Index()
+  @CreationTime()
+  @Field("date")
+  declare createdAt: Date;
+
+  @Index()
+  @Field("string")
+  declare templateId: string;
+
+  @Index()
+  @Field("string")
+  declare templateSlug: string;
+
+  @Field("string")
+  declare locale: string;
+
+  @Index()
+  @Field("string")
+  declare recipientEmail: string;
+
+  @Field("string")
+  declare recipientName?: string;
+
+  @Index()
+  @Field("string")
+  declare status: SendStatus;
+
+  @Field("string")
+  declare provider?: string;
+
+  @Index()
+  @Field("string")
+  declare providerMessageId?: string;
+
+  @Field("number")
+  declare latencyMs: number;
+
+  @Field("string")
+  declare error?: string;
+
+  @Field("string")
+  declare source?: string;
+
+  /** JSON-serialized variables the template was rendered with. */
+  @Field("string")
+  declare json_variables: string;
+
+  @Field("number")
+  declare opens: number;
+
+  @Field("number")
+  declare clicks: number;
+
+  @Field("date")
+  declare lastEventAt?: Date;
+
+  @Field("date")
+  declare lastActivityAt?: Date;
+
+  @Field("string")
+  declare revision: string;
+
+  @Field("boolean")
+  declare isRetiring?: boolean;
+
+  @Field("boolean")
+  declare isTest: boolean;
+}

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

@@ -0,0 +1,49 @@
+import {
+  CreationTime,
+  Field,
+  RegisterTable,
+  Table,
+  UpdateTime,
+} from "@antelopejs/interface-database-decorators";
+import { TENANT_SCHEMA_NAME } from "@antelopejs/interface-dms/constants";
+
+export const MAILING_SETTINGS_TABLE_NAME = "mailing_settings";
+
+@RegisterTable(MAILING_SETTINGS_TABLE_NAME, TENANT_SCHEMA_NAME)
+export class MailingSettings extends Table {
+  @Field("string")
+  declare _id: string;
+
+  @CreationTime()
+  @Field("date")
+  declare createdAt: Date;
+
+  @UpdateTime()
+  @Field("date")
+  declare updatedAt: Date;
+
+  @Field("string")
+  declare fallbackLocale: string;
+
+  @Field("number")
+  declare logRetentionDays: number;
+
+  @Field("boolean")
+  declare blockOnMissingVariables: boolean;
+
+  @Field("string")
+  declare senderName: string;
+
+  @Field("string")
+  declare senderEmail: string;
+
+  @Field("string")
+  declare replyTo: string;
+
+  /** JSON-serialized TemplateCategory[] offered when classifying a template. */
+  @Field("string")
+  declare json_categories: string;
+
+  @Field("string")
+  declare webhookSecret: string;
+}

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

@@ -0,0 +1,70 @@
+import {
+  CreationTime,
+  Field,
+  Index,
+  RegisterTable,
+  Table,
+  UpdateTime,
+} from "@antelopejs/interface-database-decorators";
+import { TENANT_SCHEMA_NAME } from "@antelopejs/interface-dms/constants";
+import type { TemplateStatus } from "../../types";
+
+export const MAILING_TEMPLATES_TABLE_NAME = "mailing_templates";
+
+@RegisterTable(MAILING_TEMPLATES_TABLE_NAME, TENANT_SCHEMA_NAME)
+export class MailingTemplate extends Table {
+  @Field("string")
+  declare _id: string;
+
+  @Index()
+  @CreationTime()
+  @Field("date")
+  declare createdAt: Date;
+
+  @Index()
+  @UpdateTime()
+  @Field("date")
+  declare updatedAt: Date;
+
+  @Index()
+  @Field("string")
+  declare slug: string;
+
+  @Field("string")
+  declare name: string;
+
+  @Index()
+  @Field("string")
+  declare category: string;
+
+  @Index()
+  @Field("string")
+  declare status: TemplateStatus;
+
+  /** JSON-serialized TemplateContent, replaced in place on every save. */
+  @Field("string")
+  declare json_content: string;
+
+  /** JSON-serialized VariableDefinition[] declared for this template. */
+  @Field("string")
+  declare json_variables: 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.
+   * Denormalised so a template row can show its coverage without loading the
+   * version. Blank on rows written before this field existed: unknown, not
+   * "none".
+   */
+  @Field("string")
+  declare locales: string;
+
+  @Field("string")
+  declare updatedBy: string;
+
+  @Field("date")
+  declare publishedAt?: Date;
+}

package/src/engine/conditions.ts

@@ -0,0 +1,30 @@
+import type { Condition, ConditionOperator } from "../types";
+import { getPath } from "./paths";
+
+type Evaluator = (actual: unknown, expected: string) => boolean;
+
+const asNumber = (value: unknown): number => Number(value);
+
+const EVALUATORS: Record<ConditionOperator, Evaluator> = {
+  truthy: (actual) => Boolean(actual),
+  falsy: (actual) => !actual,
+  eq: (actual, expected) => String(actual) === expected,
+  ne: (actual, expected) => String(actual) !== expected,
+  gt: (actual, expected) => asNumber(actual) > asNumber(expected),
+  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.
+ */
+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);
+}

package/src/engine/coverage.ts

@@ -0,0 +1,67 @@
+import { SYSTEM_VARIABLE_PATHS } from "../constants";
+import type {
+  Block,
+  LocaleContent,
+  TemplateContent,
+  VariableDefinition,
+} from "../types";
+import { getPath, isPresent, normalizePath } from "./paths";
+import { extractTokens } from "./tokens";
+import { walkBlocks } from "./walk";
+
+type PathCollector = (block: Block) => string[];
+
+const textTokens = (...texts: string[]): string[] =>
+  texts.flatMap(extractTokens);
+
+const COLLECTORS: Record<Block["type"], PathCollector> = {
+  hero: (block) =>
+    block.type === "hero" ? textTokens(block.imageUrl, block.alt) : [],
+  heading: (block) => (block.type === "heading" ? textTokens(block.text) : []),
+  paragraph: (block) =>
+    block.type === "paragraph" ? textTokens(block.text) : [],
+  code: (block) => (block.type === "code" ? textTokens(block.text) : []),
+  list: (block) => (block.type === "list" ? [normalizePath(block.source)] : []),
+  total: (block) =>
+    block.type === "total" ? textTokens(block.label, block.value) : [],
+  button: (block) =>
+    block.type === "button" ? textTokens(block.text, block.href) : [],
+  if: (block) =>
+    block.type === "if" ? [normalizePath(block.condition.path)] : [],
+  divider: () => [],
+  footer: (block) => (block.type === "footer" ? textTokens(block.text) : []),
+};
+
+const isUserPath = (path: string): boolean =>
+  !SYSTEM_VARIABLE_PATHS.includes(path);
+
+export function collectVariablePaths(content: LocaleContent): string[] {
+  const paths = new Set<string>(textTokens(content.subject, content.preheader));
+  walkBlocks(content.blocks, (block) => {
+    for (const path of COLLECTORS[block.type](block)) {
+      paths.add(normalizePath(path));
+    }
+    if (block.visibleIf) paths.add(normalizePath(block.visibleIf.path));
+  });
+  return [...paths].filter(isUserPath).sort();
+}
+
+/** Every variable path the content references, across all of its locales. */
+export function collectContentVariablePaths(
+  content: TemplateContent,
+): string[] {
+  const paths = Object.values(content.locales).flatMap((locale) =>
+    collectVariablePaths(locale),
+  );
+  return [...new Set(paths)].sort();
+}
+
+export function missingRequiredVariables(
+  declared: VariableDefinition[],
+  data: Record<string, unknown>,
+): string[] {
+  return declared
+    .filter((variable) => variable.required)
+    .map((variable) => normalizePath(variable.path))
+    .filter((path) => !isPresent(getPath(data, path)));
+}