@antelopejs/dms-mailing 0.2.2

package/src/test/unit/tenant-export.test.ts

@@ -0,0 +1,88 @@
+import { GetRegisteredHooks, Hook } from "@antelopejs/interface-dms/hooks";
+import { expect } from "chai";
+import { MODULE_ID } from "../../constants";
+import { registerTenantExport } from "../../hooks";
+import {
+  type ExportPageLoader,
+  jsonArrayChunks,
+} from "../../hooks/tenant-export";
+
+const PAGE_SIZE = 3;
+const EXTRA_ROW = 1;
+const ROW_COUNT = PAGE_SIZE * 2 + EXTRA_ROW;
+
+interface ExportedRow {
+  index: number;
+}
+
+const ROWS: ExportedRow[] = Array.from(
+  { length: ROW_COUNT },
+  (_row, index) => ({ index }),
+);
+
+function pagedLoader(offsets: number[]): ExportPageLoader<ExportedRow> {
+  return (offset, size) => {
+    offsets.push(offset);
+    return Promise.resolve(ROWS.slice(offset, offset + size));
+  };
+}
+
+async function collect(chunks: AsyncGenerator<string>): Promise<string> {
+  let text = "";
+  for await (const chunk of chunks) text += chunk;
+  return text;
+}
+
+describe("[unit] hooks/tenant-export", () => {
+  it("contributes to the tenant data export under the module id", () => {
+    registerTenantExport();
+    const moduleIds = GetRegisteredHooks(Hook.TENANT_DATA_EXPORT).map(
+      (hook) => hook.moduleId,
+    );
+    expect(moduleIds).to.include(MODULE_ID);
+  });
+
+  it("streams a collection as one JSON array read page by page", async () => {
+    const offsets: number[] = [];
+    const signal = new AbortController().signal;
+
+    const text = await collect(
+      jsonArrayChunks(pagedLoader(offsets), signal, PAGE_SIZE),
+    );
+
+    expect(JSON.parse(text)).to.deep.equal(ROWS);
+    expect(offsets).to.deep.equal([0, PAGE_SIZE, PAGE_SIZE * 2]);
+  });
+
+  it("streams an empty array when the collection has no row", async () => {
+    const signal = new AbortController().signal;
+
+    const text = await collect(
+      jsonArrayChunks(() => Promise.resolve([]), signal, PAGE_SIZE),
+    );
+
+    expect(JSON.parse(text)).to.deep.equal([]);
+  });
+
+  it("stops streaming as soon as the export is aborted", async () => {
+    const controller = new AbortController();
+    const offsets: number[] = [];
+    const chunks = jsonArrayChunks(
+      pagedLoader(offsets),
+      controller.signal,
+      PAGE_SIZE,
+    );
+    await chunks.next();
+    controller.abort();
+
+    let aborted = false;
+    try {
+      await collect(chunks);
+    } catch {
+      aborted = true;
+    }
+
+    expect(aborted).to.equal(true);
+    expect(offsets).to.deep.equal([]);
+  });
+});

package/src/test/unit/webhook-secret.test.ts

@@ -0,0 +1,50 @@
+import { expect } from "chai";
+import { webhookSecretMatches } from "../../services/events";
+import { settingsSchema } from "../../validation/settings.schema";
+
+const VALID_SECRET = "a".repeat(48);
+
+const settings = (webhookSecret: string) => ({
+  fallbackLocale: "en",
+  logRetentionDays: 30,
+  blockOnMissingVariables: false,
+  senderName: "",
+  senderEmail: "",
+  replyTo: "",
+  webhookSecret,
+  categories: [],
+});
+
+describe("[unit] webhook secret", () => {
+  // The event endpoint is the module's only unauthenticated route: the secret
+  // is the whole gate, so an absent or blank one must close it, not open it.
+  it("refuses every request when no secret is stored", () => {
+    expect(webhookSecretMatches("", "")).to.equal(false);
+    expect(webhookSecretMatches(undefined, "")).to.equal(false);
+    expect(webhookSecretMatches(VALID_SECRET, "")).to.equal(false);
+  });
+
+  it("refuses a missing or wrong header against a real secret", () => {
+    expect(webhookSecretMatches(undefined, VALID_SECRET)).to.equal(false);
+    expect(webhookSecretMatches("", VALID_SECRET)).to.equal(false);
+    expect(webhookSecretMatches("b".repeat(48), VALID_SECRET)).to.equal(false);
+    expect(webhookSecretMatches("a".repeat(47), VALID_SECRET)).to.equal(false);
+  });
+
+  it("accepts the exact secret", () => {
+    expect(webhookSecretMatches(VALID_SECRET, VALID_SECRET)).to.equal(true);
+  });
+});
+
+describe("[unit] settings validation", () => {
+  it("refuses to store a blank webhook secret", () => {
+    expect(() => settingsSchema.parse(settings(""))).to.throw();
+    expect(() => settingsSchema.parse(settings("short"))).to.throw();
+  });
+
+  it("accepts a secret long enough to be worth guessing", () => {
+    expect(settingsSchema.parse(settings(VALID_SECRET)).webhookSecret).to.equal(
+      VALID_SECRET,
+    );
+  });
+});

package/src/types/blocks.ts

@@ -0,0 +1,31 @@
+/**
+ * The block tree and template content are part of the public interface: the
+ * editor, the engine and every consumer of `SendTemplate` must agree on one
+ * shape, so they are declared in the interface package and only re-exported
+ * here.
+ */
+export type {
+  Block,
+  BlockBase,
+  BlockType,
+  ButtonBlock,
+  CodeBlock,
+  Condition,
+  ConditionOperator,
+  DividerBlock,
+  FooterBlock,
+  HeadingBlock,
+  HeroBlock,
+  IfBlock,
+  ListBlock,
+  LocaleContent,
+  ParagraphBlock,
+  TemplateContent,
+  TextAlign,
+  TotalBlock,
+  VariableDefinition,
+  VariableType,
+} from "@antelopejs/interface-dms-mailing";
+
+/** Internal to the module: templates are never exposed by status. */
+export type TemplateStatus = "draft" | "live" | "archived";

package/src/types/index.ts

@@ -0,0 +1,4 @@
+export * from "./blocks";
+export * from "./resolved";
+export * from "./sends";
+export * from "./settings";

package/src/types/resolved.ts

@@ -0,0 +1,89 @@
+import type { TextAlign } from "./blocks";
+
+export interface ResolvedListRow {
+  label: string;
+  value: string;
+}
+
+export interface ResolvedHero {
+  id: string;
+  type: "hero";
+  imageUrl: string;
+  alt: string;
+}
+
+export interface ResolvedHeading {
+  id: string;
+  type: "heading";
+  text: string;
+  align: TextAlign;
+  size: number;
+}
+
+export interface ResolvedParagraph {
+  id: string;
+  type: "paragraph";
+  text: string;
+  align: TextAlign;
+}
+
+export interface ResolvedCode {
+  id: string;
+  type: "code";
+  text: string;
+}
+
+export interface ResolvedList {
+  id: string;
+  type: "list";
+  rows: ResolvedListRow[];
+}
+
+export interface ResolvedTotal {
+  id: string;
+  type: "total";
+  label: string;
+  value: string;
+}
+
+export interface ResolvedButton {
+  id: string;
+  type: "button";
+  text: string;
+  href: string;
+  align: TextAlign;
+}
+
+export interface ResolvedDivider {
+  id: string;
+  type: "divider";
+}
+
+export interface ResolvedFooter {
+  id: string;
+  type: "footer";
+  text: string;
+  unsubscribeLabel: string;
+  preferencesLabel: string;
+  unsubscribeUrl: string;
+  preferencesUrl: string;
+}
+
+export type ResolvedBlock =
+  | ResolvedHero
+  | ResolvedHeading
+  | ResolvedParagraph
+  | ResolvedCode
+  | ResolvedList
+  | ResolvedTotal
+  | ResolvedButton
+  | ResolvedDivider
+  | ResolvedFooter;
+
+export interface ResolvedEmail {
+  subject: string;
+  preheader: string;
+  blocks: ResolvedBlock[];
+  missing: string[];
+  hiddenBlockIds: string[];
+}

package/src/types/sends.ts

@@ -0,0 +1,44 @@
+import type { SendStatus } from "@antelopejs/interface-dms-mailing";
+
+/**
+ * Send statuses and provider event types are part of the public interface:
+ * they travel through `SendTemplate` and `RecordEmailEvent`, so they are
+ * declared in the interface package and only re-exported here.
+ */
+export type {
+  SendEventType,
+  SendStatus,
+} from "@antelopejs/interface-dms-mailing";
+
+export const SEND_STATUSES: SendStatus[] = [
+  "queued",
+  "sent",
+  "delivered",
+  "opened",
+  "clicked",
+  "bounced",
+  "spam",
+  "failed",
+  "unsubscribed",
+];
+
+export const PROBLEM_STATUSES: SendStatus[] = ["bounced", "failed", "spam"];
+
+/**
+ * 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
+ * went through the provider.
+ */
+export type SendAudience = "business" | "operational";
+
+export const SEND_AUDIENCE_QUERY_KEY = "audience";
+
+export const BUSINESS_AUDIENCE = "business";
+export const OPERATIONAL_AUDIENCE = "operational";
+
+export interface SendEventDetails {
+  url?: string;
+  userAgent?: string;
+  reason?: string;
+  code?: string;
+}

package/src/types/settings.ts

@@ -0,0 +1,24 @@
+export interface TemplateCategory {
+  id: string;
+  label: string;
+  icon: string;
+}
+
+export interface MailingSettingsValues {
+  fallbackLocale: string;
+  logRetentionDays: number;
+  blockOnMissingVariables: boolean;
+  senderName: string;
+  senderEmail: string;
+  replyTo: string;
+  webhookSecret: string;
+  categories: TemplateCategory[];
+}
+
+export const DEFAULT_CATEGORIES: TemplateCategory[] = [
+  { id: "orders", label: "Orders", icon: "i-ph-package" },
+  { id: "account", label: "Account & access", icon: "i-ph-lock" },
+  { id: "billing", label: "Billing", icon: "i-ph-file-text" },
+  { id: "marketing", label: "Marketing", icon: "i-ph-sparkle" },
+  { id: "forms", label: "Forms", icon: "i-ph-textbox" },
+];

package/src/validation/settings.schema.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { MAX_NAME_LENGTH } from "../constants";
+
+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 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),
+});
+
+export const settingsSchema = z.object({
+  fallbackLocale: z.string().regex(LOCALE_PATTERN),
+  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([]),
+});
+
+export type SettingsInput = z.input<typeof settingsSchema>;

package/src/validation/templates.schema.ts

@@ -0,0 +1,145 @@
+import { z } from "zod";
+import { MAX_NAME_LENGTH, MAX_SLUG_LENGTH, SLUG_PATTERN } from "../constants";
+
+const MIN_HEADING_SIZE = 12;
+const MAX_HEADING_SIZE = 48;
+const MAX_TEST_RECIPIENT_COUNT = 5;
+
+export const slugSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(MAX_SLUG_LENGTH)
+  .regex(SLUG_PATTERN);
+
+export const createTemplateSchema = z.object({
+  slug: slugSchema,
+  name: z.string().trim().min(1).max(MAX_NAME_LENGTH),
+  category: z.string().optional(),
+  /** Absent or empty starts blank; otherwise the template to copy. */
+  sourceTemplateId: z.string().optional(),
+});
+
+export const conditionSchema = z.object({
+  path: z.string().min(1),
+  operator: z.enum(["truthy", "falsy", "eq", "ne", "gt", "lt"]),
+  value: z.string(),
+});
+
+const alignSchema = z.enum(["left", "center", "right"]);
+const base = { id: z.string().min(1), visibleIf: conditionSchema.nullable() };
+
+export const blockSchema: z.ZodType<unknown> = z.lazy(() =>
+  z.discriminatedUnion("type", [
+    z.object({
+      ...base,
+      type: z.literal("hero"),
+      imageUrl: z.string(),
+      alt: z.string(),
+    }),
+    z.object({
+      ...base,
+      type: z.literal("heading"),
+      text: z.string(),
+      align: alignSchema,
+      size: z.number().int().min(MIN_HEADING_SIZE).max(MAX_HEADING_SIZE),
+    }),
+    z.object({
+      ...base,
+      type: z.literal("paragraph"),
+      text: z.string(),
+      align: alignSchema,
+    }),
+    z.object({ ...base, type: z.literal("code"), text: z.string() }),
+    z.object({
+      ...base,
+      type: z.literal("list"),
+      source: z.string().min(1),
+      labelPath: z.string().min(1),
+      valuePath: z.string().min(1),
+    }),
+    z.object({
+      ...base,
+      type: z.literal("total"),
+      label: z.string(),
+      value: z.string(),
+    }),
+    z.object({
+      ...base,
+      type: z.literal("button"),
+      text: z.string(),
+      href: z.string(),
+      align: alignSchema,
+    }),
+    z.object({
+      ...base,
+      type: z.literal("if"),
+      condition: conditionSchema,
+      children: z.array(blockSchema),
+      elseChildren: z.array(blockSchema).nullable(),
+    }),
+    z.object({ ...base, type: z.literal("divider") }),
+    z.object({
+      ...base,
+      type: z.literal("footer"),
+      text: z.string(),
+      unsubscribeLabel: z.string(),
+      preferencesLabel: z.string(),
+    }),
+  ]),
+);
+
+export const localeContentSchema = z.object({
+  subject: z.string(),
+  preheader: z.string(),
+  blocks: z.array(blockSchema),
+});
+
+export const templateContentSchema = z.object({
+  locales: z.record(localeContentSchema),
+});
+
+export const variableSchema = z.object({
+  path: z.string().min(1),
+  type: z.enum([
+    "string",
+    "text",
+    "number",
+    "money",
+    "date",
+    "url",
+    "boolean",
+    "array",
+  ]),
+  required: z.boolean(),
+});
+
+export const variablesSchema = z.object({ variables: z.array(variableSchema) });
+
+export const testDataSchema = z.object({ data: z.record(z.unknown()) });
+
+export const previewSchema = z.object({
+  /** Absent lets the server pick the tenant fallback (see `pickLocale`). */
+  locale: z.string().min(1).optional(),
+  content: templateContentSchema.optional(),
+  data: z.record(z.unknown()).optional(),
+});
+
+/**
+ * A real send always uses the saved template: unlike a test send it takes no
+ * `content` override, so what goes out is what is published.
+ */
+export const realSendSchema = z.object({
+  to: z.array(z.string().email()).min(1).max(MAX_TEST_RECIPIENT_COUNT),
+  locale: z.string().min(1).optional(),
+  data: z.record(z.unknown()).optional(),
+});
+
+export const testSendSchema = previewSchema.extend({
+  to: z.array(z.string().email()).min(1).max(MAX_TEST_RECIPIENT_COUNT),
+});
+
+export const duplicateSchema = z.object({
+  slug: slugSchema,
+  name: z.string().trim().min(1).max(MAX_NAME_LENGTH),
+});