@antelopejs/dms-mailing 0.5.0 → 0.6.0

package/src/services/send-import.ts

@@ -0,0 +1,235 @@
+import { createHash } from "node:crypto";
+import type {
+  EmailEvent,
+  ImportSendsResult,
+  SendImport,
+} from "@antelopejs/interface-dms-mailing";
+import { GetModel } from "@antelopejs/interface-database-decorators";
+import {
+  type ImportedSendRow,
+  type MailingTemplate,
+  SendEventModel,
+  SendModel,
+  TemplateModel,
+} from "../db";
+import { type SendEventType, stageOf } from "../types";
+import {
+  type ParsedImportedSend,
+  sendImportSchema,
+} from "../validation/declarations.schema";
+import { DeclarationError, parseDeclared } from "./declaration-error";
+import {
+  applyEvent,
+  errorAfter,
+  isSameEvent,
+  isSoftBounce,
+  type SendCounters,
+} from "./events";
+import { getSettings } from "./settings";
+import { refreshTemplateAttention } from "./template-attention";
+
+/** Labels an imported send in the log when its caller gives no source. */
+const IMPORT_SOURCE = "import";
+
+const ID_LENGTH = 32;
+/** What an imported send without any event is taken to have reached. */
+const DEFAULT_EVENT: SendEventType = "sent";
+const START: SendCounters = { status: "queued", opens: 0, clicks: 0 };
+
+type ImportedEvent = ParsedImportedSend["events"][number];
+
+/** A send's id from its import key: the same on every run of the import. */
+function importedSendIdOf(tenantId: string, importId: string): string {
+  return createHash("sha256")
+    .update(`${tenantId}\nimport\n${importId}`)
+    .digest("hex")
+    .slice(0, ID_LENGTH);
+}
+
+const addressOf = (to: ParsedImportedSend["to"]) =>
+  typeof to === "string" ? { email: to } : to;
+
+/** Chronological events, with the webhook's retry deduplication rules. */
+function timelineOf(send: ParsedImportedSend): ImportedEvent[] {
+  if (!send.events.length) return [{ type: DEFAULT_EVENT, at: send.sentAt }];
+  const timeline: ImportedEvent[] = [];
+  for (const entry of [...send.events].sort(
+    (left, right) => +left.at - +right.at,
+  )) {
+    const repeated = timeline.some((stored) =>
+      isSameEvent(
+        {
+          type: stored.type as SendEventType,
+          at: stored.at,
+          json_details: JSON.stringify(stored.details ?? {}),
+        },
+        { ...entry, type: entry.type as SendEventType },
+      ),
+    );
+    if (!repeated) timeline.push(entry);
+  }
+  return timeline;
+}
+
+/** The send's columns once its events are applied, as a webhook would. */
+interface FoldedActivity extends SendCounters {
+  error?: string;
+  isSoftBounce?: boolean;
+  lastEventAt: Date;
+}
+
+function foldEvents(
+  send: ParsedImportedSend,
+  timeline: ImportedEvent[],
+): FoldedActivity {
+  return timeline.reduce<FoldedActivity>(
+    (activity, entry) => {
+      const event: EmailEvent = {
+        provider: send.provider ?? IMPORT_SOURCE,
+        messageId: send.providerMessageId ?? "",
+        type: entry.type as SendEventType,
+        at: entry.at,
+        details: entry.details,
+      };
+      const counters = applyEvent(activity, event.type);
+      return {
+        ...counters,
+        error:
+          errorAfter(event, activity.status, counters.status) ?? activity.error,
+        isSoftBounce:
+          event.type === "bounced"
+            ? isSoftBounce(event)
+            : activity.isSoftBounce,
+        lastEventAt: entry.at,
+      };
+    },
+    { ...START, lastEventAt: send.sentAt },
+  );
+}
+
+function sendRow(
+  id: string,
+  send: ParsedImportedSend,
+  template: MailingTemplate,
+  locale: string,
+  activity: FoldedActivity,
+): ImportedSendRow {
+  const recipient = addressOf(send.to);
+  return {
+    _id: id,
+    createdAt: send.sentAt,
+    templateId: template._id,
+    templateSlug: template.slug,
+    locale,
+    requestedLocale: send.locale ?? "",
+    templateVersion: template.publishedVersion,
+    recipientEmail: recipient.email,
+    recipientName: recipient.name,
+    status: activity.status,
+    stage: stageOf(activity.status),
+    provider: send.provider,
+    providerMessageId: send.providerMessageId,
+    latencyMs: null,
+    error: activity.error || undefined,
+    source: send.source ?? IMPORT_SOURCE,
+    json_variables: JSON.stringify(send.variables),
+    opens: activity.opens,
+    clicks: activity.clicks,
+    lastEventAt: activity.lastEventAt,
+    isTest: send.isTest,
+    isSoftBounce: activity.isSoftBounce,
+  };
+}
+
+/** The templates the sends name, by slug; refused before anything is written. */
+async function templatesOf(
+  tenantId: string,
+  sends: ParsedImportedSend[],
+): Promise<Map<string, MailingTemplate>> {
+  const model = GetModel(TemplateModel, tenantId);
+  const slugs = [...new Set(sends.map((send) => send.templateSlug))];
+  const templates = new Map<string, MailingTemplate>();
+  for (const slug of slugs) {
+    const template = await model.getBySlug(slug);
+    if (!template)
+      throw new DeclarationError(
+        "template_not_found",
+        `Imported sends name template "${slug}", which the workspace does not have`,
+      );
+    templates.set(slug, template);
+  }
+  return templates;
+}
+
+/** The id an entry got, and whether this run wrote it. */
+interface EntryOutcome {
+  id: string;
+  isImported: boolean;
+}
+
+/**
+ * Writes one send: its events first, under ids derived from the send's, then
+ * the send itself. A run stopped half-way leaves events no send shows yet,
+ * which the next run completes; a send present means it was fully imported.
+ */
+async function importOne(
+  tenantId: string,
+  send: ParsedImportedSend,
+  template: MailingTemplate,
+  fallbackLocale: string,
+): Promise<EntryOutcome> {
+  const id = importedSendIdOf(tenantId, send.importId);
+  const sends = GetModel(SendModel, tenantId);
+  if (await sends.get(id)) return { id, isImported: false };
+  const timeline = timelineOf(send);
+  const events = GetModel(SendEventModel, tenantId);
+  for (const [index, entry] of timeline.entries()) {
+    await events.insertImported({
+      _id: `${id}-${index}`,
+      sendId: id,
+      type: entry.type as SendEventType,
+      at: entry.at,
+      json_details: JSON.stringify(entry.details ?? {}),
+    });
+  }
+  const locale = send.locale ?? fallbackLocale;
+  const row = sendRow(id, send, template, locale, foldEvents(send, timeline));
+  return { id, isImported: await sends.insertImported(row) };
+}
+
+/**
+ * Writes past sends into the send log with their own dates and events: the
+ * Overview, the template stats and the log then count them like any other.
+ * An import, not a send: nothing is delivered, and no suppression, realtime
+ * update, automation or notification follows. A send whose `importId` was
+ * already imported is skipped untouched. The log retention applies to them
+ * like to any send: one older than the workspace's retention goes at its next
+ * nightly run.
+ */
+export async function importSends(
+  input: SendImport,
+): Promise<ImportSendsResult> {
+  const { tenantId, sends } = parseDeclared(
+    sendImportSchema,
+    input,
+    "invalid_import",
+    "send import",
+  );
+  const templates = await templatesOf(tenantId, sends);
+  const { fallbackLocale } = await getSettings(tenantId);
+  const result: ImportSendsResult = { imported: 0, skipped: 0, sendIds: [] };
+  for (const send of sends) {
+    const template = templates.get(send.templateSlug) as MailingTemplate;
+    const { id, isImported } = await importOne(
+      tenantId,
+      send,
+      template,
+      fallbackLocale,
+    );
+    result.sendIds.push(id);
+    if (isImported) result.imported += 1;
+    else result.skipped += 1;
+  }
+  if (result.imported) await refreshTemplateAttention(tenantId);
+  return result;
+}

package/src/services/templates.ts

@@ -1,7 +1,9 @@
+import { randomUUID } from "node:crypto";
 import { HTTPResult } from "@antelopejs/interface-api";
 import { GetModel } from "@antelopejs/interface-database-decorators";
 import {
   DEFAULT_FALLBACK_LOCALE,
+  HTTP_CONFLICT,
   HTTP_NOT_FOUND,
   LOCALE_LIST_SEPARATOR,
 } from "../constants";
@@ -9,7 +11,9 @@ import {
   type MailingTemplate,
   type MailingTemplateVersion,
   TemplateModel,
+  TemplateSlugModel,
   TemplateVersionModel,
+  templateSlugIdOf,
 } from "../db";
 import { diffContents, diffVariables, type TemplateChange } from "../engine";
 import {
@@ -39,6 +43,7 @@ const NEVER_PUBLISHED = 0;
 const STALE_DRAFT: TemplateAttentionReason = "stale_draft";
 const VERSION_NOT_FOUND = "$dms_mailing.errors.version_not_found";
 const TEMPLATE_NOT_FOUND = "$dms_mailing.errors.template_not_found";
+const DUPLICATE_SLUG = "$dms_mailing.errors.duplicate_slug";
 
 /** The template `id` names; 404 when there is none. */
 export async function requireTemplate(
@@ -50,6 +55,52 @@ export async function requireTemplate(
   return template;
 }
 
+/**
+ * Gives `slug` to the template just inserted; false when another template
+ * holds it. A claim whose template is gone (deleted before its claim was
+ * freed) is taken over, through the same insert that settles a race.
+ */
+async function claimTemplateSlug(
+  tenantId: string,
+  slug: string,
+  templateId: string,
+): Promise<boolean> {
+  const claims = GetModel(TemplateSlugModel, tenantId);
+  const id = templateSlugIdOf(tenantId, slug);
+  if (await claims.insertClaim(id, slug, templateId)) return true;
+  const holder = await claims.get(id);
+  if (holder?.templateId === templateId) return true;
+  if (holder) {
+    const templates = GetModel(TemplateModel, tenantId);
+    if (await templates.get(holder.templateId)) return false;
+    await claims.dropClaimOf(id, holder.templateId);
+  }
+  return claims.insertClaim(id, slug, templateId);
+}
+
+/**
+ * Keeps the template just inserted if it got its slug, or removes it again
+ * and refuses it like any taken slug: two creations racing past the free-slug
+ * check both insert, and only the claim's primary key tells them apart.
+ */
+export async function assertSlugClaimed(
+  tenantId: string,
+  slug: string,
+  templateId: string,
+): Promise<void> {
+  if (await claimTemplateSlug(tenantId, slug, templateId)) return;
+  await GetModel(TemplateModel, tenantId).delete(templateId);
+  throw new HTTPResult(HTTP_CONFLICT, DUPLICATE_SLUG);
+}
+
+/** Frees the slugs of deleted templates for new ones. */
+export async function releaseTemplateSlugs(
+  tenantId: string,
+  templateIds: string[],
+): Promise<void> {
+  await GetModel(TemplateSlugModel, tenantId).releaseTemplates(templateIds);
+}
+
 /** The content customers receive: the last published version. */
 export function parseContent(template: MailingTemplate): TemplateContent {
   return JSON.parse(template.json_content || EMPTY_CONTENT) as TemplateContent;
@@ -291,48 +342,69 @@ export interface PublishOutcome {
   changes: TemplateChange[];
 }
 
-/** What a publish ships: the working content and declarations. */
-interface Shipment {
-  content: TemplateContent;
-  variables: string;
-  version: number;
-  changes: TemplateChange[];
-}
-
 /**
- * Keeps `shipment` as a version row for the history and makes it what
- * customers receive, the draft cleared.
+ * Publishes a snapshot in one conditional write, including declaration
+ * metadata when supplied. A losing writer never inserts speculative history.
+ * The latest version is recoverable from the template after a failed history
+ * insert; before replacing it we must materialize the previous version.
  */
-async function ship(
+export async function publishSnapshot(
   tenantId: string,
   template: MailingTemplate,
-  shipment: Shipment,
+  draft: TemplateDraft,
   author: string,
-): Promise<void> {
-  const { content, variables, version, changes } = shipment;
-  const shipped = {
-    json_content: JSON.stringify(content),
-    json_variables: variables,
-    locales: localesOf(content),
-    publishedAt: new Date(),
-    publishedBy: author,
-  };
-  await GetModel(TemplateVersionModel, tenantId).insert({
-    ...shipped,
-    templateId: template._id,
-    version,
-    json_changes: JSON.stringify(changes),
-  });
-  await GetModel(TemplateModel, tenantId).update(template._id, {
+  metadata: Partial<MailingTemplate> = {},
+): Promise<PublishOutcome | undefined> {
+  const previous = publishedVersionOf(template);
+  const changes = changesOf(template, draft);
+  const isUnchanged = previous > NEVER_PUBLISHED && changes.length === 0;
+  const version = isUnchanged ? previous : previous + 1;
+  const versions = GetModel(TemplateVersionModel, tenantId);
+  await versions.materialize(template);
+  const shipped: Partial<MailingTemplate> = isUnchanged
+    ? {}
+    : {
+        json_content: JSON.stringify(draft.content),
+        json_variables: JSON.stringify(draft.variables),
+        locales: localesOf(draft.content),
+        publishedAt: new Date(),
+        publishedBy: author,
+      };
+  const history = isUnchanged
+    ? {}
+    : {
+        json_published_version: JSON.stringify({
+          ...shipped,
+          _id: randomUUID(),
+          templateId: template._id,
+          version,
+          json_changes: JSON.stringify(changes),
+        }),
+      };
+  const patch: Partial<MailingTemplate> = {
+    ...metadata,
     ...shipped,
+    ...history,
     json_draft: "",
     json_variables_draft: "",
     isDraftPending: false,
-    draftRevision: template.draftRevision + 1,
+    draftRevision:
+      template.draftRevision + Number(!isUnchanged || hasDraft(template)),
     status: "live",
     publishedVersion: version,
+    publishedAt: shipped.publishedAt ?? template.publishedAt ?? new Date(),
     updatedBy: author,
+  };
+  if (
+    !(await GetModel(TemplateModel, tenantId).publishIfCurrent(template, patch))
+  )
+    return undefined;
+  await versions.materialize({
+    json_published_version:
+      patch.json_published_version ?? template.json_published_version,
   });
+  await refreshTemplateAttention(tenantId);
+  return { version, changes };
 }
 
 /**
@@ -345,49 +417,18 @@ export async function publishTemplate(
   template: MailingTemplate,
   author: string,
 ): Promise<PublishOutcome> {
-  const previous = publishedVersionOf(template);
-  const changes = pendingChanges(template);
-  const isUnchanged = previous > NEVER_PUBLISHED && changes.length === 0;
-  const version = isUnchanged ? previous : previous + 1;
-  if (isUnchanged) await markLive(tenantId, template, previous, author);
-  else
-    await ship(
-      tenantId,
-      template,
-      {
-        content: workingContent(template),
-        variables: JSON.stringify(workingVariables(template)),
-        version,
-        changes,
-      },
-      author,
-    );
-  await refreshTemplateAttention(tenantId);
-  return { version, changes };
-}
-
-/** Puts `version` back live; a draft equal to it is dropped on the way. */
-async function markLive(
-  tenantId: string,
-  template: MailingTemplate,
-  version: number,
-  author: string,
-): Promise<void> {
-  const draft = hasDraft(template)
-    ? {
-        json_draft: "",
-        json_variables_draft: "",
-        isDraftPending: false,
-        draftRevision: template.draftRevision + 1,
-      }
-    : {};
-  await GetModel(TemplateModel, tenantId).update(template._id, {
-    status: "live",
-    publishedVersion: version,
-    publishedAt: template.publishedAt ?? new Date(),
-    updatedBy: author,
-    ...draft,
-  });
+  const outcome = await publishSnapshot(
+    tenantId,
+    template,
+    {
+      content: workingContent(template),
+      variables: workingVariables(template),
+    },
+    author,
+  );
+  if (!outcome)
+    throw new HTTPResult(HTTP_CONFLICT, "$dms_mailing.errors.draft_conflict");
+  return outcome;
 }
 
 /** The content a send of `version` carried: the draft's for a test of one. */

package/src/validation/declarations.schema.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { MAX_NAME_LENGTH } from "../constants";
+import { SEND_EVENT_TYPES } from "../types";
+import { categorySchema } from "./settings.schema";
+import {
+  slugSchema,
+  templateContentSchema,
+  variableListSchema,
+} from "./templates.schema";
+
+const MAX_AUTHOR_LENGTH = MAX_NAME_LENGTH;
+const MAX_IMPORT_ID_LENGTH = 200;
+
+const tenantIdSchema = z.string().trim().min(1);
+
+/**
+ * A template declared from code: the slug and name rules of the dashboard's
+ * creation, and the content and declarations its editor saves.
+ */
+export const templateDeclarationSchema = z.object({
+  tenantId: tenantIdSchema,
+  slug: slugSchema,
+  name: z.string().trim().min(1).max(MAX_NAME_LENGTH),
+  category: z.string().trim().default(""),
+  content: templateContentSchema,
+  variables: variableListSchema.default([]),
+  testData: z.record(z.unknown()).default({}),
+  author: z.string().trim().min(1).max(MAX_AUTHOR_LENGTH).optional(),
+});
+
+export type ParsedTemplateDeclaration = z.infer<
+  typeof templateDeclarationSchema
+>;
+
+export const categoryDeclarationSchema = categorySchema.extend({
+  tenantId: tenantIdSchema,
+  label: z.string().trim().min(1).max(MAX_NAME_LENGTH),
+});
+
+export type ParsedCategoryDeclaration = z.infer<
+  typeof categoryDeclarationSchema
+>;
+
+const recipientSchema = z.union([
+  z.string().trim().email(),
+  z.object({
+    email: z.string().trim().email(),
+    name: z.string().optional(),
+  }),
+]);
+
+const importedEventSchema = z.object({
+  type: z.enum(SEND_EVENT_TYPES as [string, ...string[]]),
+  at: z.coerce.date(),
+  details: z.record(z.unknown()).optional(),
+});
+
+const importedSendSchema = z.object({
+  importId: z.string().trim().min(1).max(MAX_IMPORT_ID_LENGTH),
+  templateSlug: slugSchema,
+  to: recipientSchema,
+  sentAt: z.coerce.date(),
+  locale: z.string().trim().min(1).optional(),
+  variables: z.record(z.unknown()).default({}),
+  provider: z.string().optional(),
+  providerMessageId: z.string().optional(),
+  source: z.string().optional(),
+  isTest: z.boolean().default(false),
+  events: z.array(importedEventSchema).default([]),
+});
+
+export type ParsedImportedSend = z.infer<typeof importedSendSchema>;
+
+export const sendImportSchema = z.object({
+  tenantId: tenantIdSchema,
+  sends: z.array(importedSendSchema),
+});

package/frontend-vue/pnpm-workspace.yaml

@@ -1,2 +0,0 @@
-packages:
-  - '.'