@antelopejs/dms-mailing 0.9.2 → 0.10.1

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

@@ -35,7 +35,9 @@ export class TemplateModel extends BasicDataModel(
 ) {
   /** The row of `fields`, its name written in every language it holds. */
   static fromFields(fields: TemplateFields): MailingTemplate {
-    return TemplateModel.fromPlainData(fields).localize("*", ["name"]);
+    const row = TemplateModel.fromPlainData(fields);
+    row.localize("*", ["name"]);
+    return row;
   }
 
   /**
@@ -57,19 +59,30 @@ export class TemplateModel extends BasicDataModel(
     return this.insert(TemplateModel.fromFields(fields));
   }
 
+  /**
+   * The stored form of a patch. The row's modifier container (`_internal`,
+   * where the localized name lives) comes out empty when the patch has no
+   * name, and the database merges a row shallowly, so that empty container
+   * would wipe the stored name: it is left out then.
+   */
+  private static storedPatch(row: MailingTemplate, fields: TemplateFields) {
+    const stored = TemplateModel.toDatabase(row);
+    if (fields.name === undefined) delete stored[MODIFIER_CONTAINER];
+    return stored;
+  }
+
   /**
    * Updates a template, a name given holding every language. Every write of
-   * a template goes through here rather than `update`: an update event leaves
-   * the row's modifier container (`_internal`, where the localized name
-   * lives) empty when the patch has no name, and the database merges a row
-   * shallowly, so that empty container would wipe the stored name.
+   * a template goes through here rather than `update`, which would store the
+   * patch's empty modifier container over the name.
    */
   updateFields(id: string, fields: TemplateFields): Promise<number> {
     const row = TemplateModel.fromFields(fields);
     triggerEvent(row, "update");
-    const stored = TemplateModel.toDatabase(row);
-    if (fields.name === undefined) delete stored[MODIFIER_CONTAINER];
-    return this.table.get(id).update(stored).run();
+    return this.table
+      .get(id)
+      .update(TemplateModel.storedPatch(row, fields))
+      .run();
   }
 
   /** Publishes only over the exact semantic revision that was inspected. */
@@ -77,7 +90,10 @@ export class TemplateModel extends BasicDataModel(
     template: MailingTemplate,
     patch: TemplateFields,
   ): Promise<boolean> {
-    const stored = TemplateModel.toDatabase(TemplateModel.fromFields(patch));
+    const stored = TemplateModel.storedPatch(
+      TemplateModel.fromFields(patch),
+      patch,
+    );
     const outcome = await this.table
       .atomicMutation(template._id, {
         type: "update",

package/src/hooks/tenant-export.ts

@@ -102,8 +102,11 @@ async function loadPage<T extends object>(
 
 /** A template as exported: its name in every language. */
 const templateCodec: RowCodec<MailingTemplate> = {
-  fromDatabase: (row) =>
-    TemplateModel.fromDatabase(row)?.localize("*", ["name"]),
+  fromDatabase: (stored) => {
+    const row = TemplateModel.fromDatabase(stored);
+    row?.localize("*", ["name"]);
+    return row;
+  },
 };
 
 export function exportedCollections(tenantId: string): ExportedCollection[] {

package/src/pages/editor.ts

@@ -25,7 +25,7 @@ export class MailingEditorController extends PageController(
   },
   DefaultLayout({ fullWidth: true, hideHeader: true, fillHeight: true }),
 ) {
-  static editor = CustomComponent("MailingEditor").meta({
+  static editor = CustomComponent("MailingTemplateEditor").meta({
     name: "$dms_mailing.permissions.editor.name",
     description: "$dms_mailing.permissions.editor.description",
     icon: "i-ph-pencil-simple",

package/src/routes/sends.ts

@@ -70,6 +70,7 @@ import {
 } from "../services/templates";
 import type { SendStatus, SuppressionSummary, TemplateStatus } from "../types";
 import type { JsonObject } from "../types/json";
+import { parseJsonObject } from "../validation/json";
 import {
   type previewVersionSchema,
   realSendSchema,
@@ -578,9 +579,7 @@ function requestedVersionOf(
 }
 
 function variablesOf(send: MailingSend): JsonObject {
-  // SAFETY: json_variables is written only as JSON.stringify(params.variables ?? {}) (services/send.ts) or
-  // JSON.stringify(send.variables) (services/send-import.ts), both a JsonObject.
-  return JSON.parse(send.json_variables || "{}") as JsonObject;
+  return parseJsonObject(send.json_variables || "{}");
 }
 
 function summarize(template: MailingTemplate): SendTemplateSummary {

package/src/routes/templates.ts

@@ -6,6 +6,7 @@ import {
   Parameter,
   Post,
   Put,
+  type QueryValue,
   type RequestContext,
 } from "@antelopejs/interface-api";
 import { assert, assertValidation } from "@antelopejs/interface-api-util";
@@ -203,14 +204,14 @@ export class TemplatesController extends Controller(
   @Get("/starters/:id/preview")
   async starterPreview(
     @Parameter("id", "param") id: string,
-    @Parameter("locale", "query") requested?: string,
+    @Parameter("locale", "query") requested: QueryValue,
   ) {
     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,
+      requested === true || requested === "" ? undefined : requested,
       settings.fallbackLocale,
     );
     const localeContent = localeContentOf(starter.content, locale);

package/src/services/settings.ts

@@ -10,6 +10,10 @@ import {
 } from "../types";
 import type { JsonObject } from "../types/json";
 import type { SettingsPatch } from "../validation/settings.schema";
+import {
+  parseStored,
+  storedCategoriesSchema,
+} from "../validation/stored.schema";
 
 export const WEBHOOK_SECRET_BYTES = 24;
 
@@ -48,9 +52,11 @@ function toValues(row: MailingSettings): MailingSettingsValues {
     replyTo: row.replyTo,
     webhookSecret: row.webhookSecret,
     webhookSecretSource: storedSecretSource(row.webhookSecretSource),
-    // SAFETY: json_categories is written only by toRow as the JSON.stringify of categories that categoriesSchema
-    // validated (settingsPatchSchema, applyCategory) or that the module defaults supplied.
-    categories: JSON.parse(row.json_categories) as TemplateCategory[],
+    categories: parseStored(
+      row.json_categories,
+      storedCategoriesSchema,
+      "template categories",
+    ),
   };
 }
 

package/src/services/templates.ts

@@ -28,6 +28,13 @@ import type {
 } from "../types";
 import { DEFAULT_FALLBACK_LOCALE } from "../types";
 import type { JsonObject } from "../types/json";
+import { parseJsonObject } from "../validation/json";
+import {
+  parseStored,
+  storedChangesSchema,
+  storedContentSchema,
+  storedVariablesSchema,
+} from "../validation/stored.schema";
 
 export interface TemplateAuthor {
   name?: string;
@@ -74,8 +81,11 @@ export async function refuseTakenSlug<T>(write: Promise<T>): Promise<T> {
 
 /** The content customers receive: the last published version. */
 export function parseContent(template: MailingTemplate): TemplateContent {
-  // SAFETY: json_content is written only as JSON.stringify of a TemplateContent that saveContentSchema validated or the module built.
-  return JSON.parse(template.json_content || EMPTY_CONTENT) as TemplateContent;
+  return parseStored(
+    template.json_content || EMPTY_CONTENT,
+    storedContentSchema,
+    "template content",
+  );
 }
 
 export function hasDraft(template: MailingTemplate): boolean {
@@ -85,8 +95,11 @@ export function hasDraft(template: MailingTemplate): boolean {
 /** The content the editor works on: the draft, or the published content. */
 export function workingContent(template: MailingTemplate): TemplateContent {
   if (!template.json_draft) return parseContent(template);
-  // SAFETY: json_draft is written only as JSON.stringify of a TemplateContent that saveContentSchema validated or the module built.
-  return JSON.parse(template.json_draft) as TemplateContent;
+  return parseStored(
+    template.json_draft,
+    storedContentSchema,
+    "template content",
+  );
 }
 
 /** The version customers receive; 0 for a template never published. */
@@ -105,8 +118,11 @@ export function isPublished(template: MailingTemplate): boolean {
 export function parseVariables(
   template: MailingTemplate,
 ): VariableDefinition[] {
-  // SAFETY: json_variables is written only as JSON.stringify of a VariableDefinition[] that variableListSchema validated or the module built.
-  return JSON.parse(template.json_variables) as VariableDefinition[];
+  return parseStored(
+    template.json_variables,
+    storedVariablesSchema,
+    "variable declarations",
+  );
 }
 
 /**
@@ -118,8 +134,11 @@ export function workingVariables(
 ): VariableDefinition[] {
   if (!hasDraft(template) || !template.json_variables_draft)
     return parseVariables(template);
-  // SAFETY: json_variables_draft is written only as JSON.stringify of a VariableDefinition[] that variableListSchema validated or the module built.
-  return JSON.parse(template.json_variables_draft) as VariableDefinition[];
+  return parseStored(
+    template.json_variables_draft,
+    storedVariablesSchema,
+    "variable declarations",
+  );
 }
 
 /** A template's working state: what a publish would ship. */
@@ -175,8 +194,7 @@ export function pendingChanges(template: MailingTemplate): TemplateChange[] {
 }
 
 export function parseTestData(template: MailingTemplate): JsonObject {
-  // SAFETY: json_test_data is written only as JSON.stringify of an object that its route or declaration schema validated, or the module built.
-  return JSON.parse(template.json_test_data) as JsonObject;
+  return parseJsonObject(template.json_test_data);
 }
 
 interface FooterLabels {
@@ -297,16 +315,18 @@ export async function discardDraft(
 export function parseVersionChanges(
   row: MailingTemplateVersion,
 ): TemplateChange[] {
-  // SAFETY: json_changes is written only as JSON.stringify of the TemplateChange[] from diffContents and diffVariables.
-  return JSON.parse(row.json_changes) as TemplateChange[];
+  return parseStored(row.json_changes, storedChangesSchema, "version changes");
 }
 
 /** The declarations a published version shipped with. */
 export function parseVersionVariables(
   row: MailingTemplateVersion,
 ): VariableDefinition[] {
-  // SAFETY: a version row's json_variables is written only as JSON.stringify of a VariableDefinition[] that variableListSchema validated or the module built.
-  return JSON.parse(row.json_variables) as VariableDefinition[];
+  return parseStored(
+    row.json_variables,
+    storedVariablesSchema,
+    "variable declarations",
+  );
 }
 
 /**
@@ -461,8 +481,7 @@ export async function contentOfVersion(
 export function parseVersionContent(
   row: MailingTemplateVersion,
 ): TemplateContent {
-  // SAFETY: a version row's json_content is written only as JSON.stringify of a TemplateContent that saveContentSchema validated.
-  return JSON.parse(row.json_content) as TemplateContent;
+  return parseStored(row.json_content, storedContentSchema, "template content");
 }
 
 /**

package/src/validation/stored.schema.ts

@@ -0,0 +1,257 @@
+import { z } from "zod";
+import type { MailingTemplateVersion } from "../db/tables";
+import type { TemplateChange, TemplateChangeKind } from "../engine/changes";
+import type {
+  Block,
+  BlockType,
+  Condition,
+  ConditionOperator,
+  TemplateCategory,
+  TemplateContent,
+  TextAlign,
+  VariableDefinition,
+  VariableType,
+} from "../types";
+
+/** What a stored JSON column holds, checked when it is read back. */
+type StoredSchema<T> = z.ZodType<T, z.ZodTypeDef, unknown>;
+
+/**
+ * `text`, a stored JSON column, parsed and read with `schema`: a
+ * `SyntaxError` when it is not JSON, a `TypeError` naming `what` when it does
+ * not hold one, as `parseJsonObject` refuses.
+ */
+export function parseStored<T>(
+  text: string,
+  schema: StoredSchema<T>,
+  what: string,
+): T {
+  const value: unknown = JSON.parse(text);
+  const read = schema.safeParse(value);
+  if (!read.success) throw new TypeError(`expected ${what}`);
+  return read.data;
+}
+
+/** A string that is one of the keys of `members`, which lists every member. */
+function oneOf<T extends string>(members: Record<T, true>): StoredSchema<T> {
+  return z
+    .string()
+    .refine((value): value is T => Object.hasOwn(members, value));
+}
+
+const conditionOperators = {
+  truthy: true,
+  falsy: true,
+  eq: true,
+  ne: true,
+  gt: true,
+  lt: true,
+} satisfies Record<ConditionOperator, true>;
+
+const textAligns = {
+  left: true,
+  center: true,
+  right: true,
+} satisfies Record<TextAlign, true>;
+
+const variableTypes = {
+  string: true,
+  text: true,
+  number: true,
+  money: true,
+  date: true,
+  url: true,
+  boolean: true,
+  array: true,
+} satisfies Record<VariableType, true>;
+
+const blockTypes = {
+  hero: true,
+  heading: true,
+  paragraph: true,
+  code: true,
+  list: true,
+  total: true,
+  button: true,
+  if: true,
+  divider: true,
+  footer: true,
+} satisfies Record<BlockType, true>;
+
+const changeKinds = {
+  locale_added: true,
+  locale_removed: true,
+  subject: true,
+  preheader: true,
+  block_added: true,
+  block_removed: true,
+  block_changed: true,
+  blocks_reordered: true,
+  variable_added: true,
+  variable_removed: true,
+  variable_changed: true,
+} satisfies Record<TemplateChangeKind, true>;
+
+const storedConditionSchema: StoredSchema<Condition> = z
+  .object({
+    path: z.string(),
+    operator: oneOf(conditionOperators),
+    value: z.string(),
+  })
+  .passthrough();
+
+const align = oneOf(textAligns);
+const base = { id: z.string(), visibleIf: storedConditionSchema.nullable() };
+
+/**
+ * A block as the module stores it: the shape of {@link Block} and nothing
+ * more, without the bounds an edit is held to, so every block the module
+ * wrote reads back unchanged.
+ */
+const storedBlockSchema: StoredSchema<Block> = z.lazy(() => storedBlockUnion);
+
+/** Built once: the lazy schema above returns it for every nested block. */
+const storedBlockUnion = z.discriminatedUnion("type", [
+  z
+    .object({
+      ...base,
+      type: z.literal("hero"),
+      imageUrl: z.string(),
+      alt: z.string(),
+    })
+    .passthrough(),
+  z
+    .object({
+      ...base,
+      type: z.literal("heading"),
+      text: z.string(),
+      align,
+      size: z.number(),
+    })
+    .passthrough(),
+  z
+    .object({
+      ...base,
+      type: z.literal("paragraph"),
+      text: z.string(),
+      align,
+    })
+    .passthrough(),
+  z
+    .object({ ...base, type: z.literal("code"), text: z.string() })
+    .passthrough(),
+  z
+    .object({
+      ...base,
+      type: z.literal("list"),
+      source: z.string(),
+      labelPath: z.string(),
+      valuePath: z.string(),
+    })
+    .passthrough(),
+  z
+    .object({
+      ...base,
+      type: z.literal("total"),
+      label: z.string(),
+      value: z.string(),
+    })
+    .passthrough(),
+  z
+    .object({
+      ...base,
+      type: z.literal("button"),
+      text: z.string(),
+      href: z.string(),
+      align,
+    })
+    .passthrough(),
+  z
+    .object({
+      ...base,
+      type: z.literal("if"),
+      condition: storedConditionSchema,
+      children: z.array(storedBlockSchema),
+      elseChildren: z.array(storedBlockSchema).nullable(),
+    })
+    .passthrough(),
+  z.object({ ...base, type: z.literal("divider") }).passthrough(),
+  z
+    .object({
+      ...base,
+      type: z.literal("footer"),
+      text: z.string(),
+      unsubscribeLabel: z.string(),
+      preferencesLabel: z.string(),
+    })
+    .passthrough(),
+]);
+
+/** Stored {@link TemplateContent}: `json_content`, `json_draft`, a version's. */
+export const storedContentSchema: StoredSchema<TemplateContent> = z
+  .object({
+    locales: z.record(
+      z
+        .object({
+          subject: z.string(),
+          preheader: z.string(),
+          blocks: z.array(storedBlockSchema),
+        })
+        .passthrough(),
+    ),
+  })
+  .passthrough();
+
+/** Stored declarations: `json_variables`, `json_variables_draft`, a version's. */
+export const storedVariablesSchema: StoredSchema<VariableDefinition[]> =
+  z.array(
+    z
+      .object({
+        path: z.string(),
+        type: oneOf(variableTypes),
+        required: z.boolean(),
+      })
+      .passthrough(),
+  );
+
+/** A version's `json_changes`, as {@link TemplateChange} lists them. */
+export const storedChangesSchema: StoredSchema<TemplateChange[]> = z.array(
+  z
+    .object({
+      locale: z.string(),
+      kind: oneOf(changeKinds),
+      blockId: z.string().optional(),
+      blockType: oneOf(blockTypes).optional(),
+      variable: z.string().optional(),
+    })
+    .passthrough(),
+);
+
+/**
+ * A template's `json_published_version`: the version row it inserts, whose
+ * `publishedAt` JSON wrote as a string.
+ */
+export const storedVersionRowSchema: StoredSchema<MailingTemplateVersion> = z
+  .object({
+    _id: z.string(),
+    templateId: z.string(),
+    version: z.number(),
+    json_content: z.string(),
+    json_variables: z.string(),
+    locales: z.string(),
+    publishedAt: z.string().transform((at) => new Date(at)),
+    publishedBy: z.string(),
+    json_changes: z.string(),
+  })
+  .passthrough();
+
+/** The settings' `json_categories`, each label one text per language. */
+export const storedCategoriesSchema: StoredSchema<TemplateCategory[]> = z.array(
+  z
+    .object({
+      id: z.string(),
+      label: z.record(z.string()),
+      icon: z.string(),
+    })
+    .passthrough(),
+);