mailery 0.4.0 → 0.7.0

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-CGaNDDlQ.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-CGaNDDlQ.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 MailTesterFeedback, d as Mailer, T as TemplateDoc, e as SuppressionScope, D as DeliveryWindow, F as FlowStep, f as SegmentFilter, P as Predicate } from './null-B0rPgE5_.cjs';
+export { g as AuditLogDoc, B as BroadcastDoc, h as BroadcastStatus, i as CircuitBreakerThresholds, j as Collections, k as ContactTagDoc, E as EventDoc, l as FlowDoc, m as FlowGoal, n as FlowRunDoc, o as FlowRunStatus, p as FlowVersionDoc, H as HealthDoc, q as HealthStatus, L as LeadDoc, r as MailerConfig, s as NullProvider, O as OutboxDoc, t as RESERVED_VAR_KEYS, u as RedisOptions, v as SegmentDefinition, w as SendDoc, x as SendStatus, y as SenderDomainConfig, z as SenderDomainRegistry, G as SenderDomainValidation, I as SubscriptionDoc, J as SubscriptionStatus, K as SuppressionDoc, Q as SuppressionReason, U as TemplateKind, V as TemplateVersionDoc, W as VarsAdapter, X as VarsResolveInfo, Y as WebhookEventDoc, Z as defineVars, _ as ensureIndexes, $ as getCollections, a0 as validateSenderDomain, a1 as varsJsonSchema } from './null-B0rPgE5_.cjs';
 import { ObjectId, Db, Filter } from 'mongodb';
 import { Request, Router } from 'express';
 import Handlebars from 'handlebars';
@@ -140,6 +140,37 @@ declare class SendGridProvider implements MailProvider {
     parseWebhookEvents(payload: unknown): NormalizedEvent[];
 }
 
+/**
+ * Mail-Tester deliverability check.
+ *
+ *  1. Operator clicks "Run deliverability check" in the template editor.
+ *  2. Mailery provisions a check (gets a unique test address from Mail-Tester).
+ *  3. Mailery sends the rendered draft to that address via the operator's
+ *     default provider.
+ *  4. Mailery polls Mail-Tester for the score (typically arrives 10-30s after
+ *     receipt) and caches it keyed on a content fingerprint.
+ *  5. If the score is below `minScore` the publish endpoint refuses unless
+ *     the operator passes `bypassMailTester: true` in the publish request.
+ *
+ * The client interface is pluggable so tests inject a stub. Real
+ * implementation hits https://mail-tester.com/api/.
+ */
+
+interface ProvisionedCheck {
+    checkId: string;
+    emailAddress: string;
+}
+interface MailTesterResult {
+    ready: boolean;
+    score: number;
+    feedback: MailTesterFeedback[];
+    rawSummary: string | null;
+}
+interface MailTesterClient {
+    provisionCheck(): Promise<ProvisionedCheck>;
+    fetchResult(checkId: string): Promise<MailTesterResult>;
+}
+
 /**
  * Admin router — serves the prebuilt React SPA + REST endpoints the SPA
  * consumes. Mount inside a host Express app, gated by host auth.
@@ -154,6 +185,11 @@ interface AdminRouterOptions {
     spaDir?: string;
     /** Resolve actor metadata from a Request. Defaults to `human:${req.user?.email || 'anonymous'}`. */
     getActor?: (req: Request) => string;
+    /**
+     * Inject a Mail-Tester client (tests use a stub). When omitted, a real
+     * client is created from `mailer.config.mailTester`.
+     */
+    mailTesterClient?: MailTesterClient;
 }
 declare function createAdminRouter(mailer: Mailer, opts?: AdminRouterOptions): Router;
 
@@ -214,8 +250,16 @@ declare function compileMailyTemplate(content: unknown): Promise<CompileResult>;
 /** Auto-derive plain text from compiled HTML. */
 declare function derivePlaintext(html: string): string;
 interface RenderContext {
+    /**
+     * Host-resolved variables (varsAdapter) live at the context root, so a
+     * schema key `user` renders as `{{user.name}}`. Reserved keys below always
+     * win over resolved keys.
+     */
+    [resolvedVar: string]: unknown;
     contact: Contact;
     vars: Record<string, unknown>;
+    /** Properties of the event that triggered the flow run ({{event.*}}). Empty outside flow sends. */
+    event?: Record<string, unknown>;
     /** URL the recipient hits to one-click unsubscribe. */
     unsubscribeUrl: string;
     /** URL to view this email in a browser (when implemented). */
@@ -289,6 +333,20 @@ declare function verifyUnsubscribeToken(token: string, secret: string, now?: Dat
  */
 declare function sha256Hex(input: string): string;
 
+/**
+ * Delivery-window math. Pure — no I/O, no Date.now(); callers pass `now`.
+ *
+ * Given the moment a send step becomes runnable, `computeDeliveryTime`
+ * returns the earliest instant the email is allowed to go out. It only ever
+ * moves forward: a send already inside its window returns `now` unchanged.
+ *
+ * Timezone handling uses the Intl API (no dependency). DST transitions are
+ * resolved with a two-pass offset fix; the worst case during a transition is
+ * being off by the shifted hour, which is fine for email delivery.
+ */
+
+declare function computeDeliveryTime(now: Date, window: DeliveryWindow, contactTimezone?: string): Date;
+
 /**
  * Enumerable option lists for the union types in `./types.ts`. Used by the
  * admin client to render dropdowns + by tooling to enumerate the surface.
@@ -340,6 +398,6 @@ declare const DEDUPE_POLICIES: readonly DedupePolicyOption[];
 /**
  * Public exports for the `mailery` package.
  */
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.7.0";
 
-export { AdapterFilter, type AdminRouterOptions, Contact, ContactAdapter, DEDUPE_POLICIES, type DedupePolicyOption, FLOW_STEP_KINDS, FlowStep, type FlowStepKindOption, MailProvider, Mailer, MongoContactAdapter, type MongoContactAdapterOptions, NormalizedEvent, PREDICATE_KINDS, Predicate, type PredicateKind, type PredicateKindOption, type PublicRouterOptions, SEGMENT_FILTER_KINDS, SegmentFilter, type SegmentFilterKind, type SegmentFilterKindOption, SendArgs, SendGridProvider, type SendGridProviderOptions, SendResult, SuppressionScope, TemplateDoc, VERSION, applyTracking, applyWebhookEvent, compileMailyTemplate, compileTemplate, createAdminRouter, createPublicRouter, defaultFlowStep, defaultPredicate, defaultSegmentFilter, derivePlaintext, dispatchSend, predicateKind, processNewlyFiredEventTriggers, processOneRunStep, renderTemplate, runTick, sha256Hex, signUnsubscribeToken, sweepStrandedFlowRuns, verifyUnsubscribeToken };
+export { AdapterFilter, type AdminRouterOptions, Contact, ContactAdapter, DEDUPE_POLICIES, type DedupePolicyOption, DeliveryWindow, FLOW_STEP_KINDS, FlowStep, type FlowStepKindOption, MailProvider, Mailer, MongoContactAdapter, type MongoContactAdapterOptions, NormalizedEvent, PREDICATE_KINDS, Predicate, type PredicateKind, type PredicateKindOption, type PublicRouterOptions, SEGMENT_FILTER_KINDS, SegmentFilter, type SegmentFilterKind, type SegmentFilterKindOption, SendArgs, SendGridProvider, type SendGridProviderOptions, SendResult, SuppressionScope, TemplateDoc, VERSION, applyTracking, applyWebhookEvent, compileMailyTemplate, compileTemplate, computeDeliveryTime, createAdminRouter, createPublicRouter, defaultFlowStep, defaultPredicate, defaultSegmentFilter, derivePlaintext, dispatchSend, predicateKind, processNewlyFiredEventTriggers, processOneRunStep, renderTemplate, runTick, sha256Hex, signUnsubscribeToken, sweepStrandedFlowRuns, verifyUnsubscribeToken };

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-CGaNDDlQ.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-CGaNDDlQ.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 MailTesterFeedback, d as Mailer, T as TemplateDoc, e as SuppressionScope, D as DeliveryWindow, F as FlowStep, f as SegmentFilter, P as Predicate } from './null-B0rPgE5_.js';
+export { g as AuditLogDoc, B as BroadcastDoc, h as BroadcastStatus, i as CircuitBreakerThresholds, j as Collections, k as ContactTagDoc, E as EventDoc, l as FlowDoc, m as FlowGoal, n as FlowRunDoc, o as FlowRunStatus, p as FlowVersionDoc, H as HealthDoc, q as HealthStatus, L as LeadDoc, r as MailerConfig, s as NullProvider, O as OutboxDoc, t as RESERVED_VAR_KEYS, u as RedisOptions, v as SegmentDefinition, w as SendDoc, x as SendStatus, y as SenderDomainConfig, z as SenderDomainRegistry, G as SenderDomainValidation, I as SubscriptionDoc, J as SubscriptionStatus, K as SuppressionDoc, Q as SuppressionReason, U as TemplateKind, V as TemplateVersionDoc, W as VarsAdapter, X as VarsResolveInfo, Y as WebhookEventDoc, Z as defineVars, _ as ensureIndexes, $ as getCollections, a0 as validateSenderDomain, a1 as varsJsonSchema } from './null-B0rPgE5_.js';
 import { ObjectId, Db, Filter } from 'mongodb';
 import { Request, Router } from 'express';
 import Handlebars from 'handlebars';
@@ -140,6 +140,37 @@ declare class SendGridProvider implements MailProvider {
     parseWebhookEvents(payload: unknown): NormalizedEvent[];
 }
 
+/**
+ * Mail-Tester deliverability check.
+ *
+ *  1. Operator clicks "Run deliverability check" in the template editor.
+ *  2. Mailery provisions a check (gets a unique test address from Mail-Tester).
+ *  3. Mailery sends the rendered draft to that address via the operator's
+ *     default provider.
+ *  4. Mailery polls Mail-Tester for the score (typically arrives 10-30s after
+ *     receipt) and caches it keyed on a content fingerprint.
+ *  5. If the score is below `minScore` the publish endpoint refuses unless
+ *     the operator passes `bypassMailTester: true` in the publish request.
+ *
+ * The client interface is pluggable so tests inject a stub. Real
+ * implementation hits https://mail-tester.com/api/.
+ */
+
+interface ProvisionedCheck {
+    checkId: string;
+    emailAddress: string;
+}
+interface MailTesterResult {
+    ready: boolean;
+    score: number;
+    feedback: MailTesterFeedback[];
+    rawSummary: string | null;
+}
+interface MailTesterClient {
+    provisionCheck(): Promise<ProvisionedCheck>;
+    fetchResult(checkId: string): Promise<MailTesterResult>;
+}
+
 /**
  * Admin router — serves the prebuilt React SPA + REST endpoints the SPA
  * consumes. Mount inside a host Express app, gated by host auth.
@@ -154,6 +185,11 @@ interface AdminRouterOptions {
     spaDir?: string;
     /** Resolve actor metadata from a Request. Defaults to `human:${req.user?.email || 'anonymous'}`. */
     getActor?: (req: Request) => string;
+    /**
+     * Inject a Mail-Tester client (tests use a stub). When omitted, a real
+     * client is created from `mailer.config.mailTester`.
+     */
+    mailTesterClient?: MailTesterClient;
 }
 declare function createAdminRouter(mailer: Mailer, opts?: AdminRouterOptions): Router;
 
@@ -214,8 +250,16 @@ declare function compileMailyTemplate(content: unknown): Promise<CompileResult>;
 /** Auto-derive plain text from compiled HTML. */
 declare function derivePlaintext(html: string): string;
 interface RenderContext {
+    /**
+     * Host-resolved variables (varsAdapter) live at the context root, so a
+     * schema key `user` renders as `{{user.name}}`. Reserved keys below always
+     * win over resolved keys.
+     */
+    [resolvedVar: string]: unknown;
     contact: Contact;
     vars: Record<string, unknown>;
+    /** Properties of the event that triggered the flow run ({{event.*}}). Empty outside flow sends. */
+    event?: Record<string, unknown>;
     /** URL the recipient hits to one-click unsubscribe. */
     unsubscribeUrl: string;
     /** URL to view this email in a browser (when implemented). */
@@ -289,6 +333,20 @@ declare function verifyUnsubscribeToken(token: string, secret: string, now?: Dat
  */
 declare function sha256Hex(input: string): string;
 
+/**
+ * Delivery-window math. Pure — no I/O, no Date.now(); callers pass `now`.
+ *
+ * Given the moment a send step becomes runnable, `computeDeliveryTime`
+ * returns the earliest instant the email is allowed to go out. It only ever
+ * moves forward: a send already inside its window returns `now` unchanged.
+ *
+ * Timezone handling uses the Intl API (no dependency). DST transitions are
+ * resolved with a two-pass offset fix; the worst case during a transition is
+ * being off by the shifted hour, which is fine for email delivery.
+ */
+
+declare function computeDeliveryTime(now: Date, window: DeliveryWindow, contactTimezone?: string): Date;
+
 /**
  * Enumerable option lists for the union types in `./types.ts`. Used by the
  * admin client to render dropdowns + by tooling to enumerate the surface.
@@ -340,6 +398,6 @@ declare const DEDUPE_POLICIES: readonly DedupePolicyOption[];
 /**
  * Public exports for the `mailery` package.
  */
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.7.0";
 
-export { AdapterFilter, type AdminRouterOptions, Contact, ContactAdapter, DEDUPE_POLICIES, type DedupePolicyOption, FLOW_STEP_KINDS, FlowStep, type FlowStepKindOption, MailProvider, Mailer, MongoContactAdapter, type MongoContactAdapterOptions, NormalizedEvent, PREDICATE_KINDS, Predicate, type PredicateKind, type PredicateKindOption, type PublicRouterOptions, SEGMENT_FILTER_KINDS, SegmentFilter, type SegmentFilterKind, type SegmentFilterKindOption, SendArgs, SendGridProvider, type SendGridProviderOptions, SendResult, SuppressionScope, TemplateDoc, VERSION, applyTracking, applyWebhookEvent, compileMailyTemplate, compileTemplate, createAdminRouter, createPublicRouter, defaultFlowStep, defaultPredicate, defaultSegmentFilter, derivePlaintext, dispatchSend, predicateKind, processNewlyFiredEventTriggers, processOneRunStep, renderTemplate, runTick, sha256Hex, signUnsubscribeToken, sweepStrandedFlowRuns, verifyUnsubscribeToken };
+export { AdapterFilter, type AdminRouterOptions, Contact, ContactAdapter, DEDUPE_POLICIES, type DedupePolicyOption, DeliveryWindow, FLOW_STEP_KINDS, FlowStep, type FlowStepKindOption, MailProvider, Mailer, MongoContactAdapter, type MongoContactAdapterOptions, NormalizedEvent, PREDICATE_KINDS, Predicate, type PredicateKind, type PredicateKindOption, type PublicRouterOptions, SEGMENT_FILTER_KINDS, SegmentFilter, type SegmentFilterKind, type SegmentFilterKindOption, SendArgs, SendGridProvider, type SendGridProviderOptions, SendResult, SuppressionScope, TemplateDoc, VERSION, applyTracking, applyWebhookEvent, compileMailyTemplate, compileTemplate, computeDeliveryTime, createAdminRouter, createPublicRouter, defaultFlowStep, defaultPredicate, defaultSegmentFilter, derivePlaintext, dispatchSend, predicateKind, processNewlyFiredEventTriggers, processOneRunStep, renderTemplate, runTick, sha256Hex, signUnsubscribeToken, sweepStrandedFlowRuns, verifyUnsubscribeToken };