@antelopejs/dms-mailing 0.3.4 → 0.4.1

package/src/routes/templates.ts

@@ -18,58 +18,154 @@ import {
   HTTP_NOT_FOUND,
   HTTP_UNPROCESSABLE,
 } from "../constants";
-import { collectContentVariablePaths, resolveEmail } from "../engine";
-import { type MailingTemplate, TemplateModel } from "../db";
+import {
+  collectContentVariablePaths,
+  resolveEmail,
+  type TemplateChange,
+} from "../engine";
+import { type MailingTemplate, SendModel, TemplateModel } from "../db";
 import { TemplatesPageController } from "../pages/templates";
+import { forAudience, statsWindowStart } from "../services/metrics";
+import { refreshTemplateAttention } from "../services/template-attention";
 import { renderEmailHtml } from "../services/render";
 import { getSettings } from "../services/settings";
+import { findStarter, STARTER_TEMPLATES } from "../services/starters";
+import {
+  performanceOf,
+  statsOf,
+  type TemplatePerformance,
+  type TemplateStats,
+} from "../services/template-stats";
 import {
   contentFieldsOf,
+  contentOfVersion,
+  discardDraft,
   displayName,
+  hasDraft,
+  isPublished,
+  isStaleRevision,
   localeContentOf,
+  localesWithoutSubject,
   parseContent,
   parseTestData,
   parseVariables,
+  pendingChanges,
   pickLocale,
-  saveContent,
+  publishedVersionOf,
+  publishTemplate,
+  saveDraft,
+  workingContent,
+  workingVariables,
+  requireTemplate,
 } from "../services/templates";
-import type {
-  MailingSettingsValues,
-  TemplateContent,
-  TemplateStatus,
-  VariableDefinition,
+import {
+  BUSINESS_AUDIENCE,
+  type MailingSettingsValues,
+  type TemplateContent,
+  type TemplateStatus,
+  type VariableDefinition,
 } from "../types";
 import {
   duplicateSchema,
   previewSchema,
-  templateContentSchema,
+  publishSchema,
+  saveContentSchema,
   testDataSchema,
   variablesSchema,
 } from "../validation/templates.schema";
 
-const NOT_FOUND = "$dms_mailing.errors.template_not_found";
+const STARTER_NOT_FOUND = "$dms_mailing.errors.starter_not_found";
 const DUPLICATE_SLUG = "$dms_mailing.errors.duplicate_slug";
 const INVALID_CONTENT = "$dms_mailing.errors.invalid_content";
+const INVALID_TRANSITION = "$dms_mailing.errors.invalid_transition";
+const NOTHING_TO_PUBLISH = "$dms_mailing.errors.nothing_to_publish";
+const NOTHING_TO_DISCARD = "$dms_mailing.errors.nothing_to_discard";
+const DRAFT_CONFLICT = "$dms_mailing.errors.draft_conflict";
+const EMPTY_SUBJECT = "$dms_mailing.errors.empty_subject";
+
+type TemplateAction = "publish" | "unpublish" | "archive" | "restore";
+
+/** The statuses each lifecycle action may start from. */
+const ALLOWED_FROM: Record<TemplateAction, TemplateStatus[]> = {
+  publish: ["draft", "live"],
+  unpublish: ["live"],
+  archive: ["draft", "live"],
+  restore: ["archived"],
+};
 
-const STATUS_TRANSITIONS: Record<string, TemplateStatus> = {
-  publish: "live",
+const TARGET_STATUS: Record<
+  Exclude<TemplateAction, "publish">,
+  TemplateStatus
+> = {
   unpublish: "draft",
   archive: "archived",
+  restore: "draft",
+};
+
+/** What a lifecycle action records besides the new status. */
+const TRANSITION_FIELDS: Partial<
+  Record<TemplateAction, () => Partial<MailingTemplate>>
+> = {
+  unpublish: () => ({ unpublishedAt: new Date() }),
 };
 
 export interface CategoriesResponse {
   categories: MailingSettingsValues["categories"];
 }
 
+export interface TemplateSender {
+  name: string;
+  email: string;
+  replyTo: string;
+}
+
 export interface TemplateContentResponse {
   template: MailingTemplate;
+  /** The content the editor works on: the draft, else the published one. */
   content: TemplateContent;
+  /** What customers receive; `null` when the template was never published. */
+  publishedContent: TemplateContent | null;
+  hasDraft: boolean;
+  /** Version customers receive; 0 when never published. */
+  version: number;
+  /** The draft revision a save or a publish must carry back. */
+  revision: number;
+  changes: TemplateChange[];
+  /** The declarations the editor works on: the draft's, else the published. */
   variables: VariableDefinition[];
-  /** Paths the content actually references, across every locale. */
+  /** Paths the working content references, across every locale. */
   detectedVariables: string[];
+  /**
+   * The contract callers send against: the published declarations and the
+   * paths the published content references; `null` when never published.
+   */
+  publishedVariables: VariableDefinition[] | null;
+  publishedDetectedVariables: string[] | null;
   testData: Record<string, unknown>;
   fallbackLocale: string;
+  /** Whether a send missing a variable fails rather than goes out blank. */
+  blockOnMissingVariables: boolean;
   categories: MailingSettingsValues["categories"];
+  sender: TemplateSender;
+}
+
+export interface StarterSummary {
+  id: string;
+  name: string;
+  slug: string;
+  category: string;
+  locales: string[];
+}
+
+/**
+ * Refuses a write of the draft from a writer behind it: it would silently
+ * drop what another editor saved meanwhile.
+ */
+export function assertCurrentDraft(
+  template: MailingTemplate,
+  revision: number | undefined,
+): void {
+  assert(!isStaleRevision(template, revision), HTTP_CONFLICT, DRAFT_CONFLICT);
 }
 
 export class TemplatesController extends Controller(
@@ -84,14 +180,15 @@ export class TemplatesController extends Controller(
   @TenantScopedModel(TemplateModel)
   declare templates: TemplateModel;
 
+  @TenantScopedModel(SendModel)
+  declare sends: SendModel;
+
   private get tenantId(): string {
     return getRequestTenantId(this.ctx);
   }
 
-  private async requireTemplate(id: string): Promise<MailingTemplate> {
-    const template = await this.templates.get(id);
-    assert(template, HTTP_NOT_FOUND, NOT_FOUND);
-    return template;
+  private get author(): string {
+    return displayName(this.user);
   }
 
   /**
@@ -105,48 +202,198 @@ export class TemplatesController extends Controller(
     return { categories: settings.categories };
   }
 
+  @Get("/starters")
+  starters(): { starters: StarterSummary[] } {
+    return {
+      starters: STARTER_TEMPLATES.map((starter) => ({
+        id: starter.id,
+        name: starter.name,
+        slug: starter.slug,
+        category: starter.category,
+        locales: Object.keys(starter.content.locales),
+      })),
+    };
+  }
+
+  /**
+   * A starter's thumbnail, in the `locale` asked for (the interface's) when
+   * the starter has it, else the tenant fallback; its test amounts are
+   * written the way that locale writes them.
+   */
+  @Get("/starters/:id/preview")
+  async starterPreview(
+    @Parameter("id", "param") id: string,
+    @Parameter("locale", "query") requested?: string,
+  ) {
+    const starter = findStarter(id);
+    assert(starter, HTTP_NOT_FOUND, STARTER_NOT_FOUND);
+    const settings = await getSettings(this.tenantId);
+    const locale = pickLocale(
+      starter.content,
+      requested || undefined,
+      settings.fallbackLocale,
+    );
+    const localeContent = localeContentOf(starter.content, locale);
+    assert(localeContent, HTTP_UNPROCESSABLE, INVALID_CONTENT);
+    const email = resolveEmail(localeContent, starter.testDataFor(locale));
+    return { html: await renderEmailHtml(email, locale), locale };
+  }
+
+  /**
+   * Last 30 days of real sends per template, for the gallery cards and the
+   * "Needs attention" tab. Test sends are left out like in the Overview.
+   */
+  @Get("/overview")
+  async overview(): Promise<{ items: TemplateStats[] }> {
+    const [templates, rows] = await Promise.all([
+      this.templates.getAll(),
+      this.sends.listBetween(statsWindowStart(), new Date()),
+    ]);
+    const sends = forAudience(rows, BUSINESS_AUDIENCE);
+    return {
+      items: templates.map((template) =>
+        statsOf(
+          template._id,
+          template.slug,
+          sends.filter((send) => send.templateSlug === template.slug),
+        ),
+      ),
+    };
+  }
+
+  @Get("/:id/performance")
+  async performance(
+    @Parameter("id", "param") id: string,
+  ): Promise<TemplatePerformance> {
+    const template = await requireTemplate(this.templates, id);
+    const rows = await this.sends.listForTemplate(
+      template.slug,
+      statsWindowStart(),
+    );
+    return performanceOf(
+      template._id,
+      template.slug,
+      forAudience(rows, BUSINESS_AUDIENCE),
+    );
+  }
+
   @Get("/:id/content")
   async content(
     @Parameter("id", "param") id: string,
   ): Promise<TemplateContentResponse> {
-    const template = await this.requireTemplate(id);
+    const template = await requireTemplate(this.templates, id);
     const settings = await getSettings(this.tenantId);
-    const content = parseContent(template);
+    const content = workingContent(template);
+    const publishedContent = isPublished(template)
+      ? parseContent(template)
+      : null;
     return {
       template,
       content,
-      variables: parseVariables(template),
+      publishedContent,
+      hasDraft: hasDraft(template),
+      version: publishedVersionOf(template),
+      revision: template.draftRevision,
+      changes: pendingChanges(template),
+      variables: workingVariables(template),
       detectedVariables: collectContentVariablePaths(content),
+      publishedVariables: publishedContent ? parseVariables(template) : null,
+      publishedDetectedVariables: publishedContent
+        ? collectContentVariablePaths(publishedContent)
+        : null,
       testData: parseTestData(template),
       fallbackLocale: settings.fallbackLocale,
+      blockOnMissingVariables: settings.blockOnMissingVariables,
       categories: settings.categories,
+      sender: {
+        name: settings.senderName,
+        email: settings.senderEmail,
+        replyTo: settings.replyTo,
+      },
     };
   }
 
+  /**
+   * Saves the editor's content, and its variable declarations when given, as
+   * the draft; customers and callers keep the published ones. A save carrying
+   * an older revision than the stored draft is refused: it would silently
+   * drop what another editor saved meanwhile.
+   */
   @Post("/:id/content")
   async replaceContent(
     @Parameter("id", "param") id: string,
     @JSONBody() body: unknown,
   ) {
-    const content = assertValidation(
+    const input = assertValidation(
       body,
-      (value) =>
-        templateContentSchema.parse(
-          (value as { content: unknown }).content,
-        ) as TemplateContent,
+      (value) => saveContentSchema.parse(value),
       () => INVALID_CONTENT,
     );
-    await this.requireTemplate(id);
-    await saveContent(this.tenantId, id, content, displayName(this.user));
+    const content = input.content as TemplateContent;
+    const template = await requireTemplate(this.templates, id);
+    assertCurrentDraft(template, input.revision);
+    const variables = input.variables ?? workingVariables(template);
+    const revision = await saveDraft(
+      this.tenantId,
+      template,
+      { content, variables },
+      this.author,
+    );
+    const saved = await requireTemplate(this.templates, id);
     return {
       saved: true,
+      revision,
       detectedVariables: collectContentVariablePaths(content),
+      changes: pendingChanges(saved),
     };
   }
 
+  @Get("/:id/changes")
+  async changes(@Parameter("id", "param") id: string) {
+    const template = await requireTemplate(this.templates, id);
+    return {
+      version: publishedVersionOf(template),
+      revision: template.draftRevision,
+      changes: pendingChanges(template),
+    };
+  }
+
+  /**
+   * Ships the working content. A publish carrying a revision ships only the
+   * draft its review showed: one saved elsewhere since is refused.
+   */
   @Post("/:id/publish")
-  publish(@Parameter("id", "param") id: string) {
-    return this.transition(id, "publish");
+  async publish(
+    @Parameter("id", "param") id: string,
+    @JSONBody() body: unknown,
+  ) {
+    const { revision } = assertValidation(body ?? {}, (value) =>
+      publishSchema.parse(value),
+    );
+    const template = await this.requireTransition(id, "publish");
+    assertCurrentDraft(template, revision);
+    const content = workingContent(template);
+    assert(
+      Object.keys(content.locales).length > 0,
+      HTTP_UNPROCESSABLE,
+      NOTHING_TO_PUBLISH,
+    );
+    assert(
+      localesWithoutSubject(content).length === 0,
+      HTTP_UNPROCESSABLE,
+      EMPTY_SUBJECT,
+    );
+    const outcome = await publishTemplate(this.tenantId, template, this.author);
+    return { status: "live", ...outcome };
+  }
+
+  /** Drops the draft back to the published content; nothing before v1. */
+  @Post("/:id/discard")
+  async discard(@Parameter("id", "param") id: string) {
+    const template = await requireTemplate(this.templates, id);
+    assert(isPublished(template), HTTP_CONFLICT, NOTHING_TO_DISCARD);
+    await discardDraft(this.tenantId, template, this.author);
+    return { discarded: true };
   }
 
   @Post("/:id/unpublish")
@@ -159,32 +406,60 @@ export class TemplatesController extends Controller(
     return this.transition(id, "archive");
   }
 
-  private async transition(id: string, action: string) {
-    const template = await this.requireTemplate(id);
-    const status = STATUS_TRANSITIONS[action] as TemplateStatus;
-    const publishedAt = status === "live" ? new Date() : template.publishedAt;
+  @Post("/:id/restore")
+  restore(@Parameter("id", "param") id: string) {
+    return this.transition(id, "restore");
+  }
+
+  private async requireTransition(
+    id: string,
+    action: TemplateAction,
+  ): Promise<MailingTemplate> {
+    const template = await requireTemplate(this.templates, id);
+    assert(
+      ALLOWED_FROM[action].includes(template.status),
+      HTTP_CONFLICT,
+      INVALID_TRANSITION,
+    );
+    return template;
+  }
+
+  private async transition(
+    id: string,
+    action: Exclude<TemplateAction, "publish">,
+  ) {
+    await this.requireTransition(id, action);
+    const status = TARGET_STATUS[action];
     await this.templates.update(id, {
       status,
-      publishedAt,
-      updatedBy: displayName(this.user),
+      updatedBy: this.author,
+      ...TRANSITION_FIELDS[action]?.(),
     });
+    await refreshTemplateAttention(this.tenantId);
     return { status };
   }
 
+  /**
+   * Writes the variable declarations into the draft, next to its content:
+   * callers keep the published contract until a publish ships them.
+   */
   @Post("/:id/variables")
   async variables(
     @Parameter("id", "param") id: string,
     @JSONBody() body: unknown,
   ) {
-    const { variables } = assertValidation(body, (value) =>
+    const { variables, revision } = assertValidation(body, (value) =>
       variablesSchema.parse(value),
     );
-    await this.requireTemplate(id);
-    await this.templates.update(id, {
-      json_variables: JSON.stringify(variables),
-      updatedBy: displayName(this.user),
-    });
-    return { variables };
+    const template = await requireTemplate(this.templates, id);
+    assertCurrentDraft(template, revision);
+    const next = await saveDraft(
+      this.tenantId,
+      template,
+      { content: workingContent(template), variables },
+      this.author,
+    );
+    return { variables, revision: next };
   }
 
   @Post("/:id/test-data")
@@ -195,7 +470,7 @@ export class TemplatesController extends Controller(
     const { data } = assertValidation(body, (value) =>
       testDataSchema.parse(value),
     );
-    await this.requireTemplate(id);
+    await requireTemplate(this.templates, id);
     await this.templates.update(id, { json_test_data: JSON.stringify(data) });
     return { data };
   }
@@ -210,9 +485,10 @@ export class TemplatesController extends Controller(
       (value) => previewSchema.parse(value),
       () => INVALID_CONTENT,
     );
-    const template = await this.requireTemplate(id);
+    const template = await requireTemplate(this.templates, id);
     const content =
-      (input.content as TemplateContent | undefined) ?? parseContent(template);
+      (input.content as TemplateContent | undefined) ??
+      (await this.previewContent(template, input.version));
     const settings = await getSettings(this.tenantId);
     const locale = pickLocale(content, input.locale, settings.fallbackLocale);
     const localeContent = localeContentOf(content, locale);
@@ -231,6 +507,16 @@ export class TemplatesController extends Controller(
     };
   }
 
+  private previewContent(
+    template: MailingTemplate,
+    version: "draft" | "published" | number | undefined,
+  ): Promise<TemplateContent> | TemplateContent {
+    if (version === "published") return parseContent(template);
+    if (typeof version === "number")
+      return contentOfVersion(this.tenantId, template, version);
+    return workingContent(template);
+  }
+
   @Post("/:id/duplicate")
   async duplicate(
     @Parameter("id", "param") id: string,
@@ -239,18 +525,18 @@ export class TemplatesController extends Controller(
     const { slug, name } = assertValidation(body, (value) =>
       duplicateSchema.parse(value),
     );
-    const source = await this.requireTemplate(id);
+    const source = await requireTemplate(this.templates, id);
     const clash = await this.templates.getBySlug(slug);
     assert(!clash, HTTP_CONFLICT, DUPLICATE_SLUG);
-    const author = displayName(this.user);
     const [copyId] = await this.templates.insert({
       slug,
       name,
       category: source.category,
       status: "draft",
       ...contentFieldsOf(source),
-      updatedBy: author,
+      updatedBy: this.author,
     });
+    await refreshTemplateAttention(this.tenantId);
     return { id: copyId };
   }
 }