mailery 0.2.0 → 0.2.2

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { R as RunnerContext, N as NormalizedEvent, C as ContactAdapter, a as Contact, A as AdapterFilter, M as MailProvider, S as SendArgs, b as SendResult, c as Mailer, T as TemplateDoc, d as SuppressionScope, F as FlowStep, e as SegmentFilter, P as Predicate } from './null-CWw3Gpbl.cjs';
-export { f as AuditLogDoc, B as BroadcastDoc, g as BroadcastStatus, h as CircuitBreakerThresholds, i as Collections, j as ContactTagDoc, E as EventDoc, k as FlowDoc, l as FlowGoal, m as FlowRunDoc, n as FlowRunStatus, o as FlowVersionDoc, H as HealthDoc, p as HealthStatus, L as LeadDoc, q as MailerConfig, r as NullProvider, O as OutboxDoc, s as RedisOptions, t as SegmentDefinition, u as SendDoc, v as SendStatus, w as SubscriptionDoc, x as SubscriptionStatus, y as SuppressionDoc, z as SuppressionReason, D as TemplateKind, G as TemplateVersionDoc, W as WebhookEventDoc, I as ensureIndexes, J as getCollections } from './null-CWw3Gpbl.cjs';
+import { R as RunnerContext, N as NormalizedEvent, C as ContactAdapter, a as Contact, A as AdapterFilter, M as MailProvider, S as SendArgs, b as SendResult, c as Mailer, T as TemplateDoc, d as SuppressionScope, F as FlowStep, e as SegmentFilter, P as Predicate } from './null-DaisDvB_.cjs';
+export { f as AuditLogDoc, B as BroadcastDoc, g as BroadcastStatus, h as CircuitBreakerThresholds, i as Collections, j as ContactTagDoc, E as EventDoc, k as FlowDoc, l as FlowGoal, m as FlowRunDoc, n as FlowRunStatus, o as FlowVersionDoc, H as HealthDoc, p as HealthStatus, L as LeadDoc, q as MailerConfig, r as NullProvider, O as OutboxDoc, s as RedisOptions, t as SegmentDefinition, u as SendDoc, v as SendStatus, w as SenderDomainConfig, x as SenderDomainRegistry, y as SenderDomainValidation, z as SubscriptionDoc, D as SubscriptionStatus, G as SuppressionDoc, I as SuppressionReason, J as TemplateKind, K as TemplateVersionDoc, W as WebhookEventDoc, Q as ensureIndexes, U as getCollections, V as validateSenderDomain } from './null-DaisDvB_.cjs';
 import { ObjectId, Db, Filter } from 'mongodb';
 import { Request, Router } from 'express';
 import Handlebars from 'handlebars';

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { R as RunnerContext, N as NormalizedEvent, C as ContactAdapter, a as Contact, A as AdapterFilter, M as MailProvider, S as SendArgs, b as SendResult, c as Mailer, T as TemplateDoc, d as SuppressionScope, F as FlowStep, e as SegmentFilter, P as Predicate } from './null-CWw3Gpbl.js';
-export { f as AuditLogDoc, B as BroadcastDoc, g as BroadcastStatus, h as CircuitBreakerThresholds, i as Collections, j as ContactTagDoc, E as EventDoc, k as FlowDoc, l as FlowGoal, m as FlowRunDoc, n as FlowRunStatus, o as FlowVersionDoc, H as HealthDoc, p as HealthStatus, L as LeadDoc, q as MailerConfig, r as NullProvider, O as OutboxDoc, s as RedisOptions, t as SegmentDefinition, u as SendDoc, v as SendStatus, w as SubscriptionDoc, x as SubscriptionStatus, y as SuppressionDoc, z as SuppressionReason, D as TemplateKind, G as TemplateVersionDoc, W as WebhookEventDoc, I as ensureIndexes, J as getCollections } from './null-CWw3Gpbl.js';
+import { R as RunnerContext, N as NormalizedEvent, C as ContactAdapter, a as Contact, A as AdapterFilter, M as MailProvider, S as SendArgs, b as SendResult, c as Mailer, T as TemplateDoc, d as SuppressionScope, F as FlowStep, e as SegmentFilter, P as Predicate } from './null-DaisDvB_.js';
+export { f as AuditLogDoc, B as BroadcastDoc, g as BroadcastStatus, h as CircuitBreakerThresholds, i as Collections, j as ContactTagDoc, E as EventDoc, k as FlowDoc, l as FlowGoal, m as FlowRunDoc, n as FlowRunStatus, o as FlowVersionDoc, H as HealthDoc, p as HealthStatus, L as LeadDoc, q as MailerConfig, r as NullProvider, O as OutboxDoc, s as RedisOptions, t as SegmentDefinition, u as SendDoc, v as SendStatus, w as SenderDomainConfig, x as SenderDomainRegistry, y as SenderDomainValidation, z as SubscriptionDoc, D as SubscriptionStatus, G as SuppressionDoc, I as SuppressionReason, J as TemplateKind, K as TemplateVersionDoc, W as WebhookEventDoc, Q as ensureIndexes, U as getCollections, V as validateSenderDomain } from './null-DaisDvB_.js';
 import { ObjectId, Db, Filter } from 'mongodb';
 import { Request, Router } from 'express';
 import Handlebars from 'handlebars';

package/dist/index.js

@@ -2188,6 +2188,25 @@ async function promoteSoftBounces(ctx) {
 // src/server/runner/tick.ts
 var STRANDED_SEND_THRESHOLD_MS = 5 * 60 * 1e3;
 async function runTick(ctx) {
+  await ctx.collections.health.updateOne(
+    { _id: "singleton" },
+    {
+      $set: { updatedAt: /* @__PURE__ */ new Date() },
+      $setOnInsert: {
+        _id: "singleton",
+        windowStartedAt: /* @__PURE__ */ new Date(),
+        windowDurationMs: ctx.config.circuitBreaker.windowMinutes * 60 * 1e3,
+        status: "healthy",
+        trippedAt: null,
+        trippedReason: null,
+        manuallyResumedAt: null,
+        counters: { sent: 0, delivered: 0, bounced: 0, hardBounced: 0, softBounced: 0, complained: 0, failedToSend: 0 },
+        rates: { bounceRate: 0, hardBounceRate: 0, complaintRate: 0, failureRate: 0 }
+      }
+    },
+    { upsert: true }
+  ).catch(() => {
+  });
   await processNewlyFiredEventTriggers(ctx).catch((err) => {
     console.error("mailery: triggers scan failed", err);
   });
@@ -2910,6 +2929,43 @@ var Mailer = class _Mailer {
   }
 };
 
+// src/server/templates/sender-domain.ts
+function validateSenderDomain(fromEmail, templateKind, registry) {
+  if (!registry || Object.keys(registry).length === 0) return { ok: true };
+  const domain = extractDomain(fromEmail);
+  if (!domain) {
+    return {
+      ok: false,
+      code: "invalid_email",
+      reason: `invalid fromEmail "${fromEmail}" \u2014 expected "name@domain"`
+    };
+  }
+  const entry = registry[domain];
+  if (!entry) {
+    const known = Object.keys(registry).join(", ");
+    return {
+      ok: false,
+      code: "unregistered_domain",
+      reason: `sender domain "${domain}" is not declared in senderDomains (allowed: ${known})`
+    };
+  }
+  if (entry.kind === "both") return { ok: true };
+  if (entry.kind !== templateKind) {
+    return {
+      ok: false,
+      code: "wrong_kind",
+      reason: `sender domain "${domain}" is configured for ${entry.kind} email, but this template's kind is ${templateKind}`
+    };
+  }
+  return { ok: true };
+}
+function extractDomain(email) {
+  if (typeof email !== "string") return null;
+  const at = email.lastIndexOf("@");
+  if (at <= 0 || at === email.length - 1) return null;
+  return email.slice(at + 1).toLowerCase().trim();
+}
+
 // src/server/index.ts
 init_mongo();
 
@@ -2939,6 +2995,227 @@ var NullProvider = class {
 
 // src/server/index.ts
 init_sendgrid();
+
+// src/server/api/setup-status.ts
+async function runSetupChecks(mailer) {
+  const checks = [];
+  checks.push(await checkMongo(mailer));
+  checks.push(await checkQueue(mailer));
+  if (mailer.config.queue.driver !== "noop" && !mailer.config.workerless) {
+    checks.push(await checkWorkersHeartbeat(mailer));
+  }
+  checks.push(await checkCircuitBreaker(mailer));
+  checks.push(...checkFromDefaultsAgainstRegistry(mailer));
+  checks.push(...await checkPublishedTemplates(mailer));
+  checks.push(await checkPostalAddress(mailer));
+  checks.push(await checkDoiTemplate(mailer));
+  const overall = checks.some((c) => c.severity === "error") ? "error" : checks.some((c) => c.severity === "warn") ? "warn" : "ok";
+  return {
+    overall,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    checks
+  };
+}
+async function checkMongo(mailer) {
+  try {
+    await mailer.db.admin().ping();
+    return { name: "mongo", label: "MongoDB connection", severity: "ok", message: "reachable" };
+  } catch (err) {
+    return {
+      name: "mongo",
+      label: "MongoDB connection",
+      severity: "error",
+      message: `MongoDB ping failed: ${err?.message ?? err}`,
+      hint: "Mailery is configured against an unreachable Mongo. Sends, flow advancement, and admin reads will all fail."
+    };
+  }
+}
+async function checkQueue(mailer) {
+  const driver = mailer.config.queue.driver;
+  if (driver === "noop") {
+    return {
+      name: "queue",
+      label: "Queue driver",
+      severity: "ok",
+      message: "driver: noop (synchronous-only mode)"
+    };
+  }
+  try {
+    await mailer.queues.send.getWaitingCount();
+    return { name: "queue", label: "Queue driver", severity: "ok", message: `driver: ${driver}` };
+  } catch (err) {
+    return {
+      name: "queue",
+      label: "Queue driver",
+      severity: "error",
+      message: `${driver} queue is not responding: ${err?.message ?? err}`,
+      hint: driver === "bull" ? "Check Redis connectivity (queue.redis.url)." : "Check the @hokify/agenda + Mongo connection."
+    };
+  }
+}
+async function checkWorkersHeartbeat(mailer) {
+  const h = await mailer.collections.health.findOne({ _id: "singleton" });
+  const tickIntervalMs = mailer.config.tickIntervalSeconds * 1e3;
+  const staleAfterMs = Math.max(tickIntervalMs * 3, 3e4);
+  if (!h) {
+    return {
+      name: "workers_heartbeat",
+      label: "Background workers",
+      severity: "warn",
+      message: "no tick has run yet",
+      hint: "If your separate worker process is started, the heartbeat will appear within one tick interval. If you forgot to run `mailer.startWorkers()`, sends will sit queued indefinitely."
+    };
+  }
+  const ageMs = Date.now() - new Date(h.updatedAt).getTime();
+  if (ageMs > staleAfterMs) {
+    return {
+      name: "workers_heartbeat",
+      label: "Background workers",
+      severity: "error",
+      message: `last tick ${humanDuration(ageMs)} ago (expected within ${humanDuration(tickIntervalMs)})`,
+      hint: "Workers appear to be down. Sends and flow advancement are halted. Restart your worker process (`mailer.startWorkers()`)."
+    };
+  }
+  return {
+    name: "workers_heartbeat",
+    label: "Background workers",
+    severity: "ok",
+    message: `last tick ${humanDuration(ageMs)} ago`
+  };
+}
+async function checkCircuitBreaker(mailer) {
+  const h = await mailer.collections.health.findOne({ _id: "singleton" });
+  if (!h || h.status === "healthy") {
+    return { name: "circuit_breaker", label: "Circuit breaker", severity: "ok", message: "healthy" };
+  }
+  if (h.status === "degraded") {
+    return {
+      name: "circuit_breaker",
+      label: "Circuit breaker",
+      severity: "warn",
+      message: "degraded (high failure rate)",
+      hint: "Marketing sends still flow but failure rate is above the degraded threshold. Investigate provider errors before they escalate to tripped."
+    };
+  }
+  return {
+    name: "circuit_breaker",
+    label: "Circuit breaker",
+    severity: "error",
+    message: `tripped: ${h.trippedReason ?? "unknown reason"}`,
+    hint: "Marketing sends are held. Investigate the underlying bounce / complaint cause, then POST /api/health/resume."
+  };
+}
+function checkFromDefaultsAgainstRegistry(mailer) {
+  const registry = mailer.config.senderDomains;
+  if (!registry || Object.keys(registry).length === 0) return [];
+  const out = [];
+  const from = mailer.config.fromDefaults?.email;
+  const tx = mailer.config.transactionalFromDefaults?.email;
+  if (from) {
+    const r = validateSenderDomain(from, "marketing", registry);
+    if (!r.ok) {
+      out.push({
+        name: "from_defaults_marketing",
+        label: "fromDefaults vs senderDomains",
+        severity: "error",
+        message: r.reason,
+        hint: "New marketing templates that fall back to fromDefaults will fail to publish."
+      });
+    }
+  }
+  if (tx) {
+    const r = validateSenderDomain(tx, "transactional", registry);
+    if (!r.ok) {
+      out.push({
+        name: "transactional_from_defaults",
+        label: "transactionalFromDefaults vs senderDomains",
+        severity: "error",
+        message: r.reason,
+        hint: "New transactional templates that fall back to transactionalFromDefaults will fail to publish."
+      });
+    }
+  } else if (from) {
+    const r = validateSenderDomain(from, "transactional", registry);
+    if (!r.ok) {
+      out.push({
+        name: "transactional_fallback",
+        label: "Transactional fallback",
+        severity: "warn",
+        message: `transactionalFromDefaults is unset and fromDefaults (${from}) is invalid for transactional templates`,
+        hint: 'Set transactionalFromDefaults to a transactional-kind domain, or set senderDomains entry for the existing one to "both".'
+      });
+    }
+  }
+  return out;
+}
+async function checkPublishedTemplates(mailer) {
+  const registry = mailer.config.senderDomains;
+  if (!registry || Object.keys(registry).length === 0) return [];
+  const published = await mailer.collections.templates.find({ publishedAt: { $ne: null } }, { projection: { slug: 1, kind: 1, fromEmail: 1 } }).toArray();
+  const broken = [];
+  for (const tpl of published) {
+    const r = validateSenderDomain(tpl.fromEmail, tpl.kind, registry);
+    if (!r.ok) broken.push({ slug: tpl.slug, reason: r.reason });
+  }
+  if (broken.length === 0) return [];
+  const list = broken.slice(0, 5).map((b) => `${b.slug} (${b.reason})`).join("; ");
+  const more = broken.length > 5 ? ` \u2026and ${broken.length - 5} more` : "";
+  return [
+    {
+      name: "published_template_domains",
+      label: "Published templates",
+      severity: "error",
+      message: `${broken.length} published template${broken.length === 1 ? "" : "s"} use a fromEmail that no longer matches senderDomains: ${list}${more}`,
+      hint: "These templates will still send with their stored fromEmail until re-published. Edit each template and republish to surface the validation, or update senderDomains."
+    }
+  ];
+}
+async function checkPostalAddress(mailer) {
+  if (mailer.config.senderAddress) {
+    return { name: "postal_address", label: "CAN-SPAM postal address", severity: "ok", message: "set" };
+  }
+  const marketingCount = await mailer.collections.templates.countDocuments({
+    kind: "marketing",
+    publishedAt: { $ne: null }
+  });
+  if (marketingCount === 0) {
+    return { name: "postal_address", label: "CAN-SPAM postal address", severity: "ok", message: "no published marketing templates yet" };
+  }
+  return {
+    name: "postal_address",
+    label: "CAN-SPAM postal address",
+    severity: "warn",
+    message: `${marketingCount} published marketing template${marketingCount === 1 ? "" : "s"} but senderAddress is unset`,
+    hint: "CAN-SPAM requires a postal address in marketing emails. Set `senderAddress` in your Mailer config and reference it via `{{senderAddress}}` in your templates."
+  };
+}
+async function checkDoiTemplate(mailer) {
+  if (!mailer.config.requireDoubleOptIn) {
+    return { name: "doi_template", label: "DOI template", severity: "ok", message: "DOI not required" };
+  }
+  const tpl = await mailer.collections.templates.findOne({
+    slug: mailer.config.doiTemplateSlug,
+    publishedAt: { $ne: null }
+  });
+  if (tpl) {
+    return { name: "doi_template", label: "DOI template", severity: "ok", message: `template "${tpl.slug}" published` };
+  }
+  return {
+    name: "doi_template",
+    label: "DOI template",
+    severity: "error",
+    message: `requireDoubleOptIn is true but no published template with slug "${mailer.config.doiTemplateSlug}"`,
+    hint: "New subscriptions will silently fail to send confirmation emails. Create and publish a template with this slug, or unset requireDoubleOptIn."
+  };
+}
+function humanDuration(ms) {
+  if (ms < 1e3) return `${ms}ms`;
+  if (ms < 6e4) return `${Math.round(ms / 1e3)}s`;
+  if (ms < 36e5) return `${Math.round(ms / 6e4)}m`;
+  return `${Math.round(ms / 36e5)}h`;
+}
+
+// src/server/api/admin.ts
 var __filename$1 = fileURLToPath(import.meta.url);
 var __dirname$1 = path.dirname(__filename$1);
 function defaultSpaDir() {
@@ -3160,6 +3437,13 @@ function apiRouter(mailer) {
       res.json(rows);
     })
   );
+  r.get(
+    "/setup-status",
+    asyncHandler(async (_req, res) => {
+      const status = await runSetupChecks(mailer);
+      res.json(status);
+    })
+  );
   r.get(
     "/health",
     asyncHandler(async (_req, res) => {
@@ -3333,6 +3617,15 @@ function apiRouter(mailer) {
       if (kind !== "marketing" && kind !== "transactional") {
         return res.status(400).json({ error: "validation_failed", message: "kind must be marketing or transactional" });
       }
+      const resolvedFromEmail = fromEmail ?? (kind === "transactional" ? mailer.config.transactionalFromDefaults?.email : void 0) ?? mailer.config.fromDefaults?.email ?? "noreply@example.com";
+      const senderCheck = validateSenderDomain(resolvedFromEmail, kind, mailer.config.senderDomains);
+      if (!senderCheck.ok) {
+        return res.status(400).json({
+          error: "sender_domain_invalid",
+          code: senderCheck.code,
+          message: senderCheck.reason
+        });
+      }
       const now = /* @__PURE__ */ new Date();
       try {
         await c.templates.insertOne({
@@ -3340,8 +3633,8 @@ function apiRouter(mailer) {
           name,
           description: "",
           kind,
-          fromName: fromName ?? mailer.config.fromDefaults?.name ?? "Mailery",
-          fromEmail: fromEmail ?? mailer.config.fromDefaults?.email ?? "noreply@example.com",
+          fromName: fromName ?? (kind === "transactional" ? mailer.config.transactionalFromDefaults?.name : void 0) ?? mailer.config.fromDefaults?.name ?? "Mailery",
+          fromEmail: resolvedFromEmail,
           replyTo: null,
           providerOverride: null,
           subject: subject ?? `Untitled \u2014 ${name}`,
@@ -3399,6 +3692,18 @@ function apiRouter(mailer) {
       if (typeof fromEmail === "string") set.fromEmail = fromEmail;
       if (typeof replyTo === "string" || replyTo === null) set.replyTo = replyTo;
       if (kind === "marketing" || kind === "transactional") set.kind = kind;
+      if (typeof fromEmail === "string" || kind === "marketing" || kind === "transactional") {
+        const resultingKind = set.kind ?? tpl.kind;
+        const resultingFromEmail = set.fromEmail ?? tpl.fromEmail;
+        const senderCheck = validateSenderDomain(resultingFromEmail, resultingKind, mailer.config.senderDomains);
+        if (!senderCheck.ok) {
+          return res.status(400).json({
+            error: "sender_domain_invalid",
+            code: senderCheck.code,
+            message: senderCheck.reason
+          });
+        }
+      }
       if (typeof trackOpens === "boolean") set.trackOpens = trackOpens;
       if (typeof trackClicks === "boolean") set.trackClicks = trackClicks;
       await c.templates.updateOne({ _id: tpl._id }, { $set: set });
@@ -3417,6 +3722,14 @@ function apiRouter(mailer) {
       if (!tpl) return res.status(404).json({ error: "not_found" });
       const draft = tpl.draft;
       if (!draft) return res.status(400).json({ error: "no_draft" });
+      const senderCheck = validateSenderDomain(tpl.fromEmail, tpl.kind, mailer.config.senderDomains);
+      if (!senderCheck.ok) {
+        return res.status(400).json({
+          error: "sender_domain_invalid",
+          code: senderCheck.code,
+          message: senderCheck.reason
+        });
+      }
       let compiled;
       if (draft.editorJson) {
         compiled = await compileMailyTemplate(draft.editorJson);
@@ -4027,6 +4340,6 @@ var DEDUPE_POLICIES = [
 // src/server/index.ts
 var VERSION = "0.1.0";
 
-export { DEDUPE_POLICIES, FLOW_STEP_KINDS, Mailer, MongoContactAdapter, NullProvider, PREDICATE_KINDS, SEGMENT_FILTER_KINDS, SendGridProvider, VERSION, applyTracking, applyWebhookEvent, compileMailyTemplate, compileTemplate, createAdminRouter, createPublicRouter, defaultFlowStep, defaultPredicate, defaultSegmentFilter, derivePlaintext, dispatchSend, ensureIndexes, getCollections, predicateKind, processNewlyFiredEventTriggers, processOneRunStep, renderTemplate, runTick, sha256Hex, signUnsubscribeToken, sweepStrandedFlowRuns, verifyUnsubscribeToken };
+export { DEDUPE_POLICIES, FLOW_STEP_KINDS, Mailer, MongoContactAdapter, NullProvider, PREDICATE_KINDS, SEGMENT_FILTER_KINDS, SendGridProvider, VERSION, applyTracking, applyWebhookEvent, compileMailyTemplate, compileTemplate, createAdminRouter, createPublicRouter, defaultFlowStep, defaultPredicate, defaultSegmentFilter, derivePlaintext, dispatchSend, ensureIndexes, getCollections, predicateKind, processNewlyFiredEventTriggers, processOneRunStep, renderTemplate, runTick, sha256Hex, signUnsubscribeToken, sweepStrandedFlowRuns, validateSenderDomain, verifyUnsubscribeToken };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map