@antelopejs/dms-mailing 0.6.0 → 0.7.0

package/src/services/sender-declaration.ts

@@ -0,0 +1,27 @@
+import type { SenderDeclaration } from "@antelopejs/interface-dms-mailing";
+import { senderDeclarationSchema } from "../validation/declarations.schema";
+import { parseDeclared } from "./declaration-error";
+import { getSettings, saveSettings } from "./settings";
+
+/**
+ * Writes the workspace's sender (from name, address, reply-to) a project
+ * sets up when it provisions the workspace. A plain write: the declared
+ * sender replaces the stored one, and later edits in the settings are the
+ * user's.
+ */
+export async function declareSender(input: SenderDeclaration): Promise<void> {
+  const declaration = parseDeclared(
+    senderDeclarationSchema,
+    input,
+    "invalid_sender",
+    "sender declaration",
+  );
+  const { tenantId } = declaration;
+  const settings = await getSettings(tenantId);
+  await saveSettings(tenantId, {
+    ...settings,
+    senderName: declaration.name,
+    senderEmail: declaration.email,
+    replyTo: declaration.replyTo,
+  });
+}

package/src/services/starters.ts

@@ -1,11 +1,11 @@
-import type { MailingTemplate } from "../db";
+import type { TemplateFields } from "../db";
 import type {
   Block,
   LocaleContent,
   TemplateContent,
   VariableDefinition,
 } from "../types";
-import { footerForCategory } from "../engine";
+import { footerForCategory, formattingLocale } from "../engine";
 import { blankFields, footerBlock } from "./templates";
 
 /**
@@ -31,18 +31,6 @@ type StarterSource = Omit<StarterTemplate, "testData">;
 const DEFAULT_TEST_DATA_LOCALE = "en";
 const STARTER_CURRENCY = "EUR";
 
-/** `locale` when the runtime can format for it, English otherwise. */
-function formattingLocale(locale: string): string {
-  try {
-    return (
-      Intl.NumberFormat.supportedLocalesOf(locale)[0] ??
-      DEFAULT_TEST_DATA_LOCALE
-    );
-  } catch {
-    return DEFAULT_TEST_DATA_LOCALE;
-  }
-}
-
 /** The ordered item of the order starter's test data, by language. */
 const ORDER_LINE_NAMES: Record<string, string> = {
   en: "Ergo chair · Graphite × 4",
@@ -374,7 +362,7 @@ export function findStarter(id: string): StarterTemplate | undefined {
 export function starterFields(
   starter: StarterTemplate,
   locale: string = DEFAULT_TEST_DATA_LOCALE,
-): Partial<MailingTemplate> {
+): TemplateFields {
   return {
     ...blankFields(starter.content),
     json_variables: JSON.stringify(starter.variables),

package/src/services/templates.ts

@@ -10,6 +10,7 @@ import {
 import {
   type MailingTemplate,
   type MailingTemplateVersion,
+  type TemplateFields,
   TemplateModel,
   TemplateSlugModel,
   TemplateVersionModel,
@@ -153,6 +154,25 @@ export interface TemplateDraft {
   variables: VariableDefinition[];
 }
 
+/** A snapshot and the version it belongs to; 0 for a draft. */
+export interface VersionedSnapshot extends TemplateDraft {
+  version: number;
+}
+
+/** What a publish would ship: the draft's content and declarations. */
+export const workingSnapshot = (template: MailingTemplate): TemplateDraft => ({
+  content: workingContent(template),
+  variables: workingVariables(template),
+});
+
+/** What customers receive: the published content and declarations. */
+export const publishedSnapshot = (
+  template: MailingTemplate,
+): TemplateDraft => ({
+  content: parseContent(template),
+  variables: parseVariables(template),
+});
+
 /**
  * What `draft` would change for customers and for the callers' contract. A
  * template never published has nothing to compare against: every locale and
@@ -240,7 +260,7 @@ export function isStaleRevision(
 function draftWriteFields(
   template: MailingTemplate,
   author: string,
-): Partial<MailingTemplate> {
+): TemplateFields {
   return {
     draftRevision: template.draftRevision + 1,
     draftUpdatedAt: new Date(),
@@ -274,7 +294,7 @@ export async function saveDraft(
   const locales = isPublished(template) ? {} : { locales: localesOf(content) };
   const isClean = isPublishedDraft(template, draft);
   const fields = draftWriteFields(template, author);
-  await GetModel(TemplateModel, tenantId).update(template._id, {
+  await GetModel(TemplateModel, tenantId).updateFields(template._id, {
     json_draft: isClean ? "" : JSON.stringify(content),
     json_variables_draft: isClean ? "" : JSON.stringify(variables),
     isDraftPending: !isClean,
@@ -290,7 +310,7 @@ export async function discardDraft(
   template: MailingTemplate,
   author: string,
 ): Promise<void> {
-  await GetModel(TemplateModel, tenantId).update(template._id, {
+  await GetModel(TemplateModel, tenantId).updateFields(template._id, {
     json_draft: "",
     json_variables_draft: "",
     isDraftPending: false,
@@ -353,7 +373,7 @@ export async function publishSnapshot(
   template: MailingTemplate,
   draft: TemplateDraft,
   author: string,
-  metadata: Partial<MailingTemplate> = {},
+  metadata: TemplateFields = {},
 ): Promise<PublishOutcome | undefined> {
   const previous = publishedVersionOf(template);
   const changes = changesOf(template, draft);
@@ -361,7 +381,7 @@ export async function publishSnapshot(
   const version = isUnchanged ? previous : previous + 1;
   const versions = GetModel(TemplateVersionModel, tenantId);
   await versions.materialize(template);
-  const shipped: Partial<MailingTemplate> = isUnchanged
+  const shipped: TemplateFields = isUnchanged
     ? {}
     : {
         json_content: JSON.stringify(draft.content),
@@ -381,7 +401,7 @@ export async function publishSnapshot(
           json_changes: JSON.stringify(changes),
         }),
       };
-  const patch: Partial<MailingTemplate> = {
+  const patch: TemplateFields = {
     ...metadata,
     ...shipped,
     ...history,
@@ -431,19 +451,34 @@ export async function publishTemplate(
   return outcome;
 }
 
-/** The content a send of `version` carried: the draft's for a test of one. */
-export async function contentOfVersion(
+/**
+ * The content and declarations a send of `version` carried: the draft's for
+ * a test of one.
+ */
+export async function snapshotOfVersion(
   tenantId: string,
   template: MailingTemplate,
   version: number,
-): Promise<TemplateContent> {
-  if (!version) return workingContent(template);
+): Promise<TemplateDraft> {
+  if (!version) return workingSnapshot(template);
   const row = await GetModel(TemplateVersionModel, tenantId).getVersion(
     template._id,
     version,
   );
   if (!row) throw new HTTPResult(HTTP_NOT_FOUND, VERSION_NOT_FOUND);
-  return parseVersionContent(row);
+  return {
+    content: parseVersionContent(row),
+    variables: parseVersionVariables(row),
+  };
+}
+
+/** The content a send of `version` carried: the draft's for a test of one. */
+export async function contentOfVersion(
+  tenantId: string,
+  template: MailingTemplate,
+  version: number,
+): Promise<TemplateContent> {
+  return (await snapshotOfVersion(tenantId, template, version)).content;
 }
 
 export function parseVersionContent(
@@ -457,9 +492,7 @@ export function parseVersionContent(
  * copy starts as a draft of the source's working content: it was never
  * published, so customers receive nothing from it yet.
  */
-export function contentFieldsOf(
-  source: MailingTemplate,
-): Partial<MailingTemplate> {
+export function contentFieldsOf(source: MailingTemplate): TemplateFields {
   const content = workingContent(source);
   return {
     json_content: "",
@@ -483,9 +516,9 @@ export async function initializeTemplate(
   tenantId: string,
   templateId: string,
   author: string,
-  fields: Partial<MailingTemplate>,
+  fields: TemplateFields,
 ): Promise<void> {
-  await GetModel(TemplateModel, tenantId).update(templateId, {
+  await GetModel(TemplateModel, tenantId).updateFields(templateId, {
     status: "draft",
     json_variables: "[]",
     json_test_data: "{}",
@@ -495,9 +528,7 @@ export async function initializeTemplate(
   await refreshTemplateAttention(tenantId);
 }
 
-export function blankFields(
-  content: TemplateContent,
-): Partial<MailingTemplate> {
+export function blankFields(content: TemplateContent): TemplateFields {
   return {
     json_content: "",
     json_draft: JSON.stringify(content),

package/src/services/webhook-status.ts

@@ -8,13 +8,13 @@ import type {
   WebhookStatus,
 } from "../types";
 import { webhookSecretMatches } from "./events";
+import { WEBHOOK_SECRET_HEADER } from "../constants";
+
+export { WEBHOOK_SECRET_HEADER };
 
 /** The message id of the event the settings' "Send a test event" posts. */
 export const WEBHOOK_TEST_MESSAGE_ID = "dms-mailing-webhook-test";
 
-/** The header a provider (or its relay) proves it knows the secret with. */
-export const WEBHOOK_SECRET_HEADER = "x-mailing-webhook-secret";
-
 const WEBHOOK_TEST_EVENT_TYPE: SendEventType = "delivered";
 const WEBHOOK_TEST_TIMEOUT_MS = 10_000;
 const JSON_CONTENT_TYPE = "application/json";

package/src/types/settings.ts

@@ -1,4 +1,14 @@
+import type { LocalizedText } from "@antelopejs/interface-dms-mailing";
+
+/** A template category as stored: its label written once per language. */
 export interface TemplateCategory {
+  id: string;
+  label: LocalizedText;
+  icon: string;
+}
+
+/** A template category as one reader sees it: the label in their language. */
+export interface CategoryInLocale {
   id: string;
   label: string;
   icon: string;
@@ -16,9 +26,29 @@ export interface MailingSettingsValues {
 }
 
 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" },
+  {
+    id: "orders",
+    label: { en: "Orders", fr: "Commandes" },
+    icon: "i-ph-package",
+  },
+  {
+    id: "account",
+    label: { en: "Account & access", fr: "Compte et accès" },
+    icon: "i-ph-lock",
+  },
+  {
+    id: "billing",
+    label: { en: "Billing", fr: "Facturation" },
+    icon: "i-ph-file-text",
+  },
+  {
+    id: "marketing",
+    label: { en: "Marketing", fr: "Marketing" },
+    icon: "i-ph-sparkle",
+  },
+  {
+    id: "forms",
+    label: { en: "Forms", fr: "Formulaires" },
+    icon: "i-ph-textbox",
+  },
 ];

package/src/validation/declarations.schema.ts

@@ -1,7 +1,8 @@
+import { LOCALIZED_TEXT_FALLBACK_LOCALE } from "@antelopejs/interface-dms-mailing";
 import { z } from "zod";
 import { MAX_NAME_LENGTH } from "../constants";
 import { SEND_EVENT_TYPES } from "../types";
-import { categorySchema } from "./settings.schema";
+import { categorySchema, settingsSchema } from "./settings.schema";
 import {
   slugSchema,
   templateContentSchema,
@@ -13,6 +14,17 @@ const MAX_IMPORT_ID_LENGTH = 200;
 
 const tenantIdSchema = z.string().trim().min(1);
 
+/**
+ * A name or a label declared from code: one non-blank text per language, the
+ * fallback language's required, since every reader without a text of their
+ * own reads it.
+ */
+export const localizedTextSchema = z
+  .record(z.string().trim().min(1).max(MAX_NAME_LENGTH))
+  .refine((text) => Boolean(text[LOCALIZED_TEXT_FALLBACK_LOCALE]), {
+    message: `a text in "${LOCALIZED_TEXT_FALLBACK_LOCALE}" is required`,
+  });
+
 /**
  * A template declared from code: the slug and name rules of the dashboard's
  * creation, and the content and declarations its editor saves.
@@ -20,7 +32,7 @@ const tenantIdSchema = z.string().trim().min(1);
 export const templateDeclarationSchema = z.object({
   tenantId: tenantIdSchema,
   slug: slugSchema,
-  name: z.string().trim().min(1).max(MAX_NAME_LENGTH),
+  name: localizedTextSchema,
   category: z.string().trim().default(""),
   content: templateContentSchema,
   variables: variableListSchema.default([]),
@@ -34,13 +46,27 @@ export type ParsedTemplateDeclaration = z.infer<
 
 export const categoryDeclarationSchema = categorySchema.extend({
   tenantId: tenantIdSchema,
-  label: z.string().trim().min(1).max(MAX_NAME_LENGTH),
+  label: localizedTextSchema,
 });
 
 export type ParsedCategoryDeclaration = z.infer<
   typeof categoryDeclarationSchema
 >;
 
+const SENDER_REQUIRED = "a sender address is required";
+
+/** A sender declared from code: the settings form's rules, an address required. */
+export const senderDeclarationSchema = z.object({
+  tenantId: tenantIdSchema,
+  email: settingsSchema.shape.senderEmail.pipe(
+    z.string().min(1, SENDER_REQUIRED),
+  ),
+  name: settingsSchema.shape.senderName.default(""),
+  replyTo: settingsSchema.shape.replyTo.default(""),
+});
+
+export type ParsedSenderDeclaration = z.infer<typeof senderDeclarationSchema>;
+
 const recipientSchema = z.union([
   z.string().trim().email(),
   z.object({

package/src/validation/settings.schema.ts

@@ -1,6 +1,7 @@
 import { domainToASCII } from "node:url";
 import { z } from "zod";
 import { MAX_NAME_LENGTH, SLUG_PATTERN } from "../constants";
+import { LOCALIZED_TEXT_FALLBACK_LOCALE } from "@antelopejs/interface-dms-mailing";
 import { MARKETING_CATEGORY } from "../engine";
 
 export const MIN_RETENTION_DAYS = 1;
@@ -31,7 +32,8 @@ const MISSING_VARIABLES_POLICIES = ["refuse", "send"] as const;
 
 export const categorySchema = z.object({
   id: z.string().max(MAX_NAME_LENGTH).regex(SLUG_PATTERN),
-  label: z.string().trim().max(MAX_NAME_LENGTH),
+  /** One label per language (`{ en: "Orders", fr: "Commandes" }`). */
+  label: z.record(z.string().trim().max(MAX_NAME_LENGTH)),
   icon: z.string().regex(CATEGORY_ICON_PATTERN),
 });
 
@@ -45,19 +47,44 @@ const categoryEntrySchema = categorySchema.extend({
 
 export type CategoryEntry = z.infer<typeof categoryEntrySchema>;
 
+/** A category entry as a reader of one language sees its label. */
+interface EntryInLocale {
+  id: string;
+  label: string;
+  moveTo?: string;
+}
+
+/**
+ * Every language a list labels its categories in, the fallback one first:
+ * the rules below hold in each of them.
+ */
+function languagesOf(entries: CategoryEntry[]): string[] {
+  const codes = entries.flatMap((entry) => Object.keys(entry.label));
+  return [...new Set([LOCALIZED_TEXT_FALLBACK_LOCALE, ...codes])];
+}
+
+/** The entries as a reader of `locale` reads them, the fallback filling in. */
+function entriesIn(entries: CategoryEntry[], locale: string): EntryInLocale[] {
+  return entries.map(({ id, label, moveTo }) => ({
+    id,
+    label: label[locale] || label[LOCALIZED_TEXT_FALLBACK_LOCALE] || "",
+    moveTo,
+  }));
+}
+
 /** Why a category list is refused, and the part of it at fault. */
 interface CategoryIssue {
   message: string;
   path: Array<string | number>;
 }
 
-const isKept = (entry: CategoryEntry): boolean => entry.moveTo === undefined;
+const isKept = (entry: EntryInLocale): boolean => entry.moveTo === undefined;
 
 /**
  * A kept entry repeating the label (whatever its case) or the id of an
  * earlier one, under the row it belongs to.
  */
-function duplicateIssues(entries: CategoryEntry[]): CategoryIssue[] {
+function duplicateIssues(entries: EntryInLocale[]): CategoryIssue[] {
   const labels = new Set<string>();
   const ids = new Set<string>();
   const issues: CategoryIssue[] = [];
@@ -79,7 +106,7 @@ function duplicateIssues(entries: CategoryEntry[]): CategoryIssue[] {
  * label's own minimum, which the form would turn into a browser-side check:
  * the server words it, under the row, together with the other row issues.
  */
-function blankLabelIssues(entries: CategoryEntry[]): CategoryIssue[] {
+function blankLabelIssues(entries: EntryInLocale[]): CategoryIssue[] {
   return entries.flatMap((entry, index) =>
     entry.label ? [] : [{ message: LABEL_REQUIRED, path: [index, LABEL_PART] }],
   );
@@ -92,7 +119,7 @@ function marketingIssues(kept: Set<string>): CategoryIssue[] {
 }
 
 function moveIssues(
-  entries: CategoryEntry[],
+  entries: EntryInLocale[],
   kept: Set<string>,
 ): CategoryIssue[] {
   return entries.flatMap((entry, index) =>
@@ -106,20 +133,35 @@ function refineCategoryEntries(
   entries: CategoryEntry[],
   context: z.RefinementCtx,
 ): void {
-  const kept = new Set(entries.filter(isKept).map((entry) => entry.id));
+  const kept = new Set(
+    entries.filter((entry) => entry.moveTo === undefined).map(({ id }) => id),
+  );
+  const labelIssues = languagesOf(entries).flatMap((locale) => {
+    const inLocale = entriesIn(entries, locale);
+    return [...blankLabelIssues(inLocale), ...duplicateIssues(inLocale)];
+  });
+  const seen = new Set<string>();
   [
-    ...blankLabelIssues(entries),
-    ...duplicateIssues(entries),
+    ...labelIssues,
     ...marketingIssues(kept),
-    ...moveIssues(entries, kept),
-  ].forEach((issue) =>
-    context.addIssue({ code: z.ZodIssueCode.custom, ...issue }),
-  );
+    ...moveIssues(entriesIn(entries, LOCALIZED_TEXT_FALLBACK_LOCALE), kept),
+  ]
+    .filter((issue) => {
+      // One issue per row and part, whichever language shows it first.
+      const id = JSON.stringify(issue);
+      if (seen.has(id)) return false;
+      seen.add(id);
+      return true;
+    })
+    .forEach((issue) =>
+      context.addIssue({ code: z.ZodIssueCode.custom, ...issue }),
+    );
 }
 
 /**
- * The category list of the settings: kept labels and ids are unique, every
- * move names a kept one, and the marketing category stays.
+ * The category list of the settings: in every language, each kept label is
+ * set and unique; ids are unique, every move names a kept one, and the
+ * marketing category stays.
  */
 export const categoriesSchema = z
   .array(categoryEntrySchema)

package/src/validation/templates.schema.ts

@@ -182,6 +182,16 @@ export const testSendSchema = previewSchema.extend({
   to: z.array(z.string().email()).min(1).max(MAX_TEST_RECIPIENT_COUNT),
 });
 
+/**
+ * The details a template's drawer or the editor saves: the name typed in the
+ * reader's language, the slug it was read with, the category (`null` clears).
+ */
+export const templateDetailsSchema = z.object({
+  name: z.string().trim().min(1).max(MAX_NAME_LENGTH),
+  slug: z.string().optional(),
+  category: z.string().nullable().optional(),
+});
+
 export const duplicateSchema = z.object({
   slug: slugSchema,
   name: z.string().trim().min(1).max(MAX_NAME_LENGTH),

package/frontend-vue/app/components/PageHeader.vue

@@ -1,94 +0,0 @@
-<script setup lang="ts">
-import { useProviderInfo } from '../composables/useMailingReads'
-import { useSetupHidesPeriod } from '../composables/useOverviewSetup'
-import { presetShortLabelKey } from '../utils/period'
-import type { Component } from 'vue'
-import type { MailingComponentProps } from '../types/component'
-import type { ProviderInfo } from '../types/mailing'
-
-interface PageHeaderProps extends MailingComponentProps {
-	periodScope?: string
-	presets?: string[]
-	defaultPreset?: string
-	defaultComparison?: string
-	showProvider?: boolean
-}
-
-defineOptions({ inheritAttrs: false })
-
-const PERIOD_COMPONENT_SUFFIX = ':period'
-
-const props = withDefaults(defineProps<PageHeaderProps>(), {
-	periodScope: undefined,
-	presets: () => [],
-	defaultPreset: undefined,
-	defaultComparison: undefined,
-	showProvider: true,
-})
-
-const { t } = useI18n()
-
-const StatusPill = resolveComponent('DmsStatusPill') as Component
-const PeriodSelector = resolveComponent('DmsPeriodSelector') as Component
-
-/** Shown as "no provider" when the read fails. */
-const NO_PROVIDER: ProviderInfo = { name: '', connected: false, features: null }
-
-const providerRead = useProviderInfo(() => props.showProvider)
-const provider = computed<ProviderInfo | null>(() =>
-	providerRead.error.value ? NO_PROVIDER : providerRead.data.value,
-)
-const hidesPeriod = useSetupHidesPeriod(props.periodScope)
-
-const presetLabels = computed(() =>
-	Object.fromEntries(
-		props.presets.map((preset) => [preset, t(presetShortLabelKey(preset))]),
-	),
-)
-
-const providerPill = computed(() =>
-	provider.value?.connected
-		? {
-				tone: 'success',
-				dot: 'live',
-				label: t('dms_mailing.page_header.provider_connected', {
-					name: provider.value.name,
-				}),
-			}
-		: {
-				tone: 'warning',
-				dot: 'static',
-				label: t('dms_mailing.page_header.no_provider'),
-			},
-)
-
-function renderProvider() {
-	if (!props.showProvider || !provider.value) return null
-	return h(StatusPill, {
-		...providerPill.value,
-		title: t('dms_mailing.page_header.provider_hint'),
-	})
-}
-
-function renderPeriod() {
-	if (!props.periodScope || hidesPeriod.value) return null
-	return h(PeriodSelector, {
-		id: props.periodScope,
-		componentId: `${props.componentId ?? props.periodScope}${PERIOD_COMPONENT_SUFFIX}`,
-		pageId: props.pageId ?? '',
-		variant: 'segmented',
-		size: 'sm',
-		showRangeLabel: false,
-		presets: props.presets.length ? props.presets : undefined,
-		presetLabels: presetLabels.value,
-		defaultPreset: props.defaultPreset,
-		defaultComparison: props.defaultComparison,
-	})
-}
-
-usePageHeaderActions(() => [renderProvider(), renderPeriod()])
-</script>
-
-<template>
-	<span hidden />
-</template>

package/frontend-vue/app/composables/useOverviewSetup.ts

@@ -1,21 +0,0 @@
-import { computed, type ComputedRef } from 'vue'
-import { useSetupFacts } from './useMailingReads'
-import { needsSetup } from '../utils/overview-setup'
-
-/** The period scope of the Overview page, whose dashboard the setup gates. */
-const OVERVIEW_PERIOD_SCOPE = 'mailing-overview'
-
-/**
- * Whether the page header should hold its period selector back for `scope`:
- * on the Overview, while the setup card stands in for the dashboard, there is
- * no figure for a period to filter. Read from the setup facts the Overview
- * gate shows (one request for both), so a server render hides it as the
- * browser does.
- */
-export function useSetupHidesPeriod(
-	scope: string | undefined,
-): ComputedRef<boolean> {
-	if (scope !== OVERVIEW_PERIOD_SCOPE) return computed(() => false)
-	const { data } = useSetupFacts()
-	return computed(() => !!data.value && needsSetup(data.value))
-}