mailery 0.5.1 → 0.7.0

package/dist/{null-BYB6v4Iv.d.cts → null-B0rPgE5_.d.cts}

@@ -47,6 +47,24 @@ interface ContactAdapter {
     addTags?(externalId: string, tags: string[]): Promise<void>;
     removeTags?(externalId: string, tags: string[]): Promise<void>;
 }
+/**
+ * Constrains WHEN a send step's email may go out. The flow's waits decide the
+ * earliest moment (T + N days); the window then pushes that moment forward —
+ * never backward — to the next allowed slot:
+ *
+ *  - `timeOfDay` — deliver at this local wall-clock time ('HH:mm'). A send
+ *    arriving after that time waits for the next day's slot (with a short
+ *    grace period so tick jitter doesn't add 24h).
+ *  - `weekdaysOnly` — a slot landing on Saturday/Sunday moves to Monday.
+ *  - `useContactTimezone` — interpret times in `contact.timezone` when set,
+ *    else fall back to `timezone` (IANA name, default UTC).
+ */
+interface DeliveryWindow {
+    weekdaysOnly?: boolean;
+    timeOfDay?: string;
+    useContactTimezone?: boolean;
+    timezone?: string;
+}
 type FlowStep = {
     type: 'wait';
     value: number;
@@ -65,6 +83,7 @@ type FlowStep = {
     templateSlug: string;
     providerOverride?: string;
     vars?: Record<string, unknown>;
+    delivery?: DeliveryWindow;
 } | {
     type: 'tag';
     addTags?: string[];
@@ -375,7 +394,7 @@ type QueueDriverConfig = {
  * server-shaped interfaces.
  */
 type SubscriptionStatus = 'subscribed' | 'pending_doi' | 'unsubscribed' | 'bounced' | 'complained';
-type SendStatus = 'queued' | 'sending' | 'sent' | 'delivered' | 'bounced' | 'complained' | 'failed' | 'suppressed';
+type SendStatus = 'queued' | 'sending' | 'sent' | 'delivered' | 'bounced' | 'complained' | 'failed' | 'suppressed' | 'cancelled';
 type TemplateKind = 'transactional' | 'marketing';
 type SuppressionScope = 'all' | 'marketing' | 'transactional';
 type SuppressionReason = 'unsubscribed' | 'hard_bounce' | 'complaint' | 'manual' | 'list_cleaning' | 'gdpr_forget';
@@ -417,6 +436,63 @@ type SenderDomainValidation = {
 };
 declare function validateSenderDomain(fromEmail: string, templateKind: TemplateKind, registry: SenderDomainRegistry | undefined): SenderDomainValidation;
 
+/**
+ * VarsAdapter — host-provided template variables, resolved at render time.
+ *
+ * The host declares a zod schema (the contract templates can rely on) plus a
+ * `resolve` function that loads those values from the host's own database for
+ * a given contact. Resolved keys are merged into the render context root, so
+ * a schema key `user` is referenced in templates as `{{user.name}}`.
+ *
+ * The schema does double duty: it is exposed to the admin SPA as JSON Schema
+ * (GET /vars-schema) to drive editor autocomplete, and the content linter
+ * uses it to flag `{{paths}}` that don't exist.
+ */
+
+interface VarsResolveInfo {
+    /** Why the vars are being resolved. Previews and tests should be side-effect free. */
+    reason: 'send' | 'preview' | 'test';
+    /** Slug of the template being rendered, when known. */
+    templateSlug?: string;
+    /** Slug of the flow the send belongs to, when the render is part of a flow run. */
+    flowSlug?: string;
+    /** Name of the event that triggered the flow run, when applicable. */
+    eventName?: string;
+    /**
+     * Properties of the triggering event (`mailer.fire(name, id, properties)`).
+     * This is how a resolver scopes lookups for account/topic flows:
+     * `info.eventProperties?.accountId` tells it WHICH account the run is about.
+     * Also available raw in templates as `{{event.*}}`.
+     */
+    eventProperties?: Record<string, unknown>;
+}
+interface VarsAdapter<S extends z.ZodType = z.ZodType> {
+    /** Contract for what `resolve` returns. Root keys become root template variables. */
+    schema: S;
+    /** Load the variables for one contact from the host's data. */
+    resolve(contact: Contact, info: VarsResolveInfo): Promise<z.infer<S>> | z.infer<S>;
+}
+/**
+ * Identity helper that pins `resolve`'s return type to `z.infer<schema>` —
+ * without it, TypeScript widens the schema generic and the return type is
+ * unchecked.
+ *
+ *   const varsAdapter = defineVars({
+ *     schema: z.object({ user: z.object({ name: z.string() }) }),
+ *     async resolve(contact) {
+ *       return { user: { name: await lookupName(contact.externalId) } }
+ *     },
+ *   })
+ */
+declare function defineVars<S extends z.ZodType>(adapter: VarsAdapter<S>): VarsAdapter<S>;
+/**
+ * Render-context keys mailery owns. Resolved vars never override these — a
+ * schema that declares one is rejected at Mailer.init.
+ */
+declare const RESERVED_VAR_KEYS: readonly ["contact", "vars", "event", "unsubscribeUrl", "viewInBrowserUrl", "preferenceCenterUrl", "senderAddress"];
+/** JSON Schema for the adapter's zod schema (wire format for the admin SPA + linter). */
+declare function varsJsonSchema(adapter: VarsAdapter): Record<string, unknown>;
+
 /**
  * Mailer configuration shape. Required + optional surfaces with sane defaults.
  */
@@ -531,6 +607,14 @@ interface MailerConfig {
     db: Db;
     collectionPrefix?: string;
     adapter: ContactAdapter;
+    /**
+     * Optional host-provided template variables. `resolve(contact)` runs at
+     * send/preview/test render time; its result is merged into the template
+     * context root (schema key `user` → `{{user.name}}`). The zod schema
+     * drives admin-editor autocomplete and the `unknown_variable` lint rule.
+     * Build one with `defineVars({ schema, resolve })`.
+     */
+    varsAdapter?: VarsAdapter<any>;
     /**
      * Queue driver selection. One of:
      *   - `{ driver: 'bull', redis: ... }` — BullMQ (default for prod; requires Redis)
@@ -734,7 +818,7 @@ interface FlowVersionDoc {
 }
 interface FlowRunHistoryEntry {
     stepIndex: number;
-    action: 'entered' | 'wait_started' | 'wait_completed' | 'condition_evaluated' | 'branch_taken' | 'sent' | 'send_skipped' | 'tagged' | 'event_fired' | 'webhook_called' | 'exited' | 'failed';
+    action: 'entered' | 'wait_started' | 'wait_completed' | 'condition_evaluated' | 'branch_taken' | 'sent' | 'send_skipped' | 'send_deferred' | 'tagged' | 'event_fired' | 'webhook_called' | 'exited' | 'failed';
     at: Date;
     details?: Record<string, unknown>;
 }
@@ -745,6 +829,17 @@ interface FlowRunDoc {
     flowSlug: string;
     flowVersion: number;
     emailAtEntry: string;
+    /**
+     * Snapshot of the event that triggered this run. Properties surface in
+     * templates as `{{event.*}}` and in `varsAdapter.resolve` via
+     * `info.eventProperties` — this is how account/topic-scoped flows know
+     * which account or topic the run is about. Null for non-event entries.
+     */
+    triggerEvent?: {
+        name: string;
+        properties: Record<string, unknown>;
+        occurredAt: Date;
+    } | null;
     enteredAt: Date;
     status: FlowRunStatus;
     currentStepIndex: number;
@@ -1224,6 +1319,7 @@ interface RunnerContext {
     db: Db;
     collections: Collections;
     adapter: ContactAdapter;
+    varsAdapter?: VarsAdapter;
     providers: Record<string, MailProvider>;
     queues: Queues;
     config: ResolvedConfig;
@@ -1297,6 +1393,33 @@ declare class Mailer {
     suppress(email: string, opts: Omit<SuppressInput, 'email'>): Promise<void>;
     tag(externalId: string, tag: string): Promise<void>;
     untag(externalId: string, tag: string): Promise<void>;
+    /**
+     * Abort every active run of one flow for a contact, immediately. Runs parked
+     * in a `wait` exit too — their delayed wake-up jobs find the run exited and
+     * no-op. Also cancels any of the flow's emails still sitting in the send
+     * queue for this contact (queued or awaiting retry), so an abort means no
+     * further mail, not just no further steps.
+     *
+     * No-op (returns zero counts) when nothing is active. Safe to call from the
+     * same handler that processes the business event ("user upgraded").
+     */
+    abortFlow(flowSlug: string, externalId: string, opts?: {
+        reason?: string;
+    }): Promise<{
+        abortedRuns: number;
+        cancelledSends: number;
+    }>;
+    /**
+     * Abort every active flow run for a contact across all flows. Same semantics
+     * as `abortFlow` — for "stop everything" events (account deleted, churned).
+     */
+    abortAllFlows(externalId: string, opts?: {
+        reason?: string;
+    }): Promise<{
+        abortedRuns: number;
+        cancelledSends: number;
+    }>;
+    private abortActiveRuns;
     /**
      * GDPR right-to-erasure. Hard-deletes the contact's PII and leaves a hashed
      * suppression row to block re-import. INVARIANT 9.
@@ -1346,4 +1469,4 @@ declare class NullProvider implements MailProvider {
     reset(): void;
 }
 
-export { type AdapterFilter as A, type BroadcastDoc as B, type ContactAdapter as C, type SubscriptionDoc as D, type EventDoc as E, type FlowStep as F, type SubscriptionStatus as G, type HealthDoc as H, type SuppressionDoc as I, type SuppressionReason as J, type TemplateKind as K, type LeadDoc as L, type MailProvider as M, type NormalizedEvent as N, type OutboxDoc as O, type Predicate as P, type TemplateVersionDoc as Q, type RunnerContext as R, type SendArgs as S, type TemplateDoc as T, ensureIndexes as U, getCollections as V, type WebhookEventDoc as W, validateSenderDomain as X, type Contact as a, type SendResult as b, type MailTesterFeedback as c, Mailer as d, type SuppressionScope as e, type SegmentFilter as f, type AuditLogDoc as g, type BroadcastStatus as h, type CircuitBreakerThresholds as i, type Collections as j, type ContactTagDoc as k, type FlowDoc as l, type FlowGoal as m, type FlowRunDoc as n, type FlowRunStatus as o, type FlowVersionDoc as p, type HealthStatus as q, type MailerConfig as r, NullProvider as s, type RedisOptions as t, type SegmentDefinition as u, type SendDoc as v, type SendStatus as w, type SenderDomainConfig as x, type SenderDomainRegistry as y, type SenderDomainValidation as z };
+export { getCollections as $, type AdapterFilter as A, type BroadcastDoc as B, type ContactAdapter as C, type DeliveryWindow as D, type EventDoc as E, type FlowStep as F, type SenderDomainValidation as G, type HealthDoc as H, type SubscriptionDoc as I, type SubscriptionStatus as J, type SuppressionDoc as K, type LeadDoc as L, type MailProvider as M, type NormalizedEvent as N, type OutboxDoc as O, type Predicate as P, type SuppressionReason as Q, type RunnerContext as R, type SendArgs as S, type TemplateDoc as T, type TemplateKind as U, type TemplateVersionDoc as V, type VarsAdapter as W, type VarsResolveInfo as X, type WebhookEventDoc as Y, defineVars as Z, ensureIndexes as _, type Contact as a, validateSenderDomain as a0, varsJsonSchema as a1, type SendResult as b, type MailTesterFeedback as c, Mailer as d, type SuppressionScope as e, type SegmentFilter as f, type AuditLogDoc as g, type BroadcastStatus as h, type CircuitBreakerThresholds as i, type Collections as j, type ContactTagDoc as k, type FlowDoc as l, type FlowGoal as m, type FlowRunDoc as n, type FlowRunStatus as o, type FlowVersionDoc as p, type HealthStatus as q, type MailerConfig as r, NullProvider as s, RESERVED_VAR_KEYS as t, type RedisOptions as u, type SegmentDefinition as v, type SendDoc as w, type SendStatus as x, type SenderDomainConfig as y, type SenderDomainRegistry as z };

package/dist/{null-BYB6v4Iv.d.ts → null-B0rPgE5_.d.ts}

@@ -47,6 +47,24 @@ interface ContactAdapter {
     addTags?(externalId: string, tags: string[]): Promise<void>;
     removeTags?(externalId: string, tags: string[]): Promise<void>;
 }
+/**
+ * Constrains WHEN a send step's email may go out. The flow's waits decide the
+ * earliest moment (T + N days); the window then pushes that moment forward —
+ * never backward — to the next allowed slot:
+ *
+ *  - `timeOfDay` — deliver at this local wall-clock time ('HH:mm'). A send
+ *    arriving after that time waits for the next day's slot (with a short
+ *    grace period so tick jitter doesn't add 24h).
+ *  - `weekdaysOnly` — a slot landing on Saturday/Sunday moves to Monday.
+ *  - `useContactTimezone` — interpret times in `contact.timezone` when set,
+ *    else fall back to `timezone` (IANA name, default UTC).
+ */
+interface DeliveryWindow {
+    weekdaysOnly?: boolean;
+    timeOfDay?: string;
+    useContactTimezone?: boolean;
+    timezone?: string;
+}
 type FlowStep = {
     type: 'wait';
     value: number;
@@ -65,6 +83,7 @@ type FlowStep = {
     templateSlug: string;
     providerOverride?: string;
     vars?: Record<string, unknown>;
+    delivery?: DeliveryWindow;
 } | {
     type: 'tag';
     addTags?: string[];
@@ -375,7 +394,7 @@ type QueueDriverConfig = {
  * server-shaped interfaces.
  */
 type SubscriptionStatus = 'subscribed' | 'pending_doi' | 'unsubscribed' | 'bounced' | 'complained';
-type SendStatus = 'queued' | 'sending' | 'sent' | 'delivered' | 'bounced' | 'complained' | 'failed' | 'suppressed';
+type SendStatus = 'queued' | 'sending' | 'sent' | 'delivered' | 'bounced' | 'complained' | 'failed' | 'suppressed' | 'cancelled';
 type TemplateKind = 'transactional' | 'marketing';
 type SuppressionScope = 'all' | 'marketing' | 'transactional';
 type SuppressionReason = 'unsubscribed' | 'hard_bounce' | 'complaint' | 'manual' | 'list_cleaning' | 'gdpr_forget';
@@ -417,6 +436,63 @@ type SenderDomainValidation = {
 };
 declare function validateSenderDomain(fromEmail: string, templateKind: TemplateKind, registry: SenderDomainRegistry | undefined): SenderDomainValidation;
 
+/**
+ * VarsAdapter — host-provided template variables, resolved at render time.
+ *
+ * The host declares a zod schema (the contract templates can rely on) plus a
+ * `resolve` function that loads those values from the host's own database for
+ * a given contact. Resolved keys are merged into the render context root, so
+ * a schema key `user` is referenced in templates as `{{user.name}}`.
+ *
+ * The schema does double duty: it is exposed to the admin SPA as JSON Schema
+ * (GET /vars-schema) to drive editor autocomplete, and the content linter
+ * uses it to flag `{{paths}}` that don't exist.
+ */
+
+interface VarsResolveInfo {
+    /** Why the vars are being resolved. Previews and tests should be side-effect free. */
+    reason: 'send' | 'preview' | 'test';
+    /** Slug of the template being rendered, when known. */
+    templateSlug?: string;
+    /** Slug of the flow the send belongs to, when the render is part of a flow run. */
+    flowSlug?: string;
+    /** Name of the event that triggered the flow run, when applicable. */
+    eventName?: string;
+    /**
+     * Properties of the triggering event (`mailer.fire(name, id, properties)`).
+     * This is how a resolver scopes lookups for account/topic flows:
+     * `info.eventProperties?.accountId` tells it WHICH account the run is about.
+     * Also available raw in templates as `{{event.*}}`.
+     */
+    eventProperties?: Record<string, unknown>;
+}
+interface VarsAdapter<S extends z.ZodType = z.ZodType> {
+    /** Contract for what `resolve` returns. Root keys become root template variables. */
+    schema: S;
+    /** Load the variables for one contact from the host's data. */
+    resolve(contact: Contact, info: VarsResolveInfo): Promise<z.infer<S>> | z.infer<S>;
+}
+/**
+ * Identity helper that pins `resolve`'s return type to `z.infer<schema>` —
+ * without it, TypeScript widens the schema generic and the return type is
+ * unchecked.
+ *
+ *   const varsAdapter = defineVars({
+ *     schema: z.object({ user: z.object({ name: z.string() }) }),
+ *     async resolve(contact) {
+ *       return { user: { name: await lookupName(contact.externalId) } }
+ *     },
+ *   })
+ */
+declare function defineVars<S extends z.ZodType>(adapter: VarsAdapter<S>): VarsAdapter<S>;
+/**
+ * Render-context keys mailery owns. Resolved vars never override these — a
+ * schema that declares one is rejected at Mailer.init.
+ */
+declare const RESERVED_VAR_KEYS: readonly ["contact", "vars", "event", "unsubscribeUrl", "viewInBrowserUrl", "preferenceCenterUrl", "senderAddress"];
+/** JSON Schema for the adapter's zod schema (wire format for the admin SPA + linter). */
+declare function varsJsonSchema(adapter: VarsAdapter): Record<string, unknown>;
+
 /**
  * Mailer configuration shape. Required + optional surfaces with sane defaults.
  */
@@ -531,6 +607,14 @@ interface MailerConfig {
     db: Db;
     collectionPrefix?: string;
     adapter: ContactAdapter;
+    /**
+     * Optional host-provided template variables. `resolve(contact)` runs at
+     * send/preview/test render time; its result is merged into the template
+     * context root (schema key `user` → `{{user.name}}`). The zod schema
+     * drives admin-editor autocomplete and the `unknown_variable` lint rule.
+     * Build one with `defineVars({ schema, resolve })`.
+     */
+    varsAdapter?: VarsAdapter<any>;
     /**
      * Queue driver selection. One of:
      *   - `{ driver: 'bull', redis: ... }` — BullMQ (default for prod; requires Redis)
@@ -734,7 +818,7 @@ interface FlowVersionDoc {
 }
 interface FlowRunHistoryEntry {
     stepIndex: number;
-    action: 'entered' | 'wait_started' | 'wait_completed' | 'condition_evaluated' | 'branch_taken' | 'sent' | 'send_skipped' | 'tagged' | 'event_fired' | 'webhook_called' | 'exited' | 'failed';
+    action: 'entered' | 'wait_started' | 'wait_completed' | 'condition_evaluated' | 'branch_taken' | 'sent' | 'send_skipped' | 'send_deferred' | 'tagged' | 'event_fired' | 'webhook_called' | 'exited' | 'failed';
     at: Date;
     details?: Record<string, unknown>;
 }
@@ -745,6 +829,17 @@ interface FlowRunDoc {
     flowSlug: string;
     flowVersion: number;
     emailAtEntry: string;
+    /**
+     * Snapshot of the event that triggered this run. Properties surface in
+     * templates as `{{event.*}}` and in `varsAdapter.resolve` via
+     * `info.eventProperties` — this is how account/topic-scoped flows know
+     * which account or topic the run is about. Null for non-event entries.
+     */
+    triggerEvent?: {
+        name: string;
+        properties: Record<string, unknown>;
+        occurredAt: Date;
+    } | null;
     enteredAt: Date;
     status: FlowRunStatus;
     currentStepIndex: number;
@@ -1224,6 +1319,7 @@ interface RunnerContext {
     db: Db;
     collections: Collections;
     adapter: ContactAdapter;
+    varsAdapter?: VarsAdapter;
     providers: Record<string, MailProvider>;
     queues: Queues;
     config: ResolvedConfig;
@@ -1297,6 +1393,33 @@ declare class Mailer {
     suppress(email: string, opts: Omit<SuppressInput, 'email'>): Promise<void>;
     tag(externalId: string, tag: string): Promise<void>;
     untag(externalId: string, tag: string): Promise<void>;
+    /**
+     * Abort every active run of one flow for a contact, immediately. Runs parked
+     * in a `wait` exit too — their delayed wake-up jobs find the run exited and
+     * no-op. Also cancels any of the flow's emails still sitting in the send
+     * queue for this contact (queued or awaiting retry), so an abort means no
+     * further mail, not just no further steps.
+     *
+     * No-op (returns zero counts) when nothing is active. Safe to call from the
+     * same handler that processes the business event ("user upgraded").
+     */
+    abortFlow(flowSlug: string, externalId: string, opts?: {
+        reason?: string;
+    }): Promise<{
+        abortedRuns: number;
+        cancelledSends: number;
+    }>;
+    /**
+     * Abort every active flow run for a contact across all flows. Same semantics
+     * as `abortFlow` — for "stop everything" events (account deleted, churned).
+     */
+    abortAllFlows(externalId: string, opts?: {
+        reason?: string;
+    }): Promise<{
+        abortedRuns: number;
+        cancelledSends: number;
+    }>;
+    private abortActiveRuns;
     /**
      * GDPR right-to-erasure. Hard-deletes the contact's PII and leaves a hashed
      * suppression row to block re-import. INVARIANT 9.
@@ -1346,4 +1469,4 @@ declare class NullProvider implements MailProvider {
     reset(): void;
 }
 
-export { type AdapterFilter as A, type BroadcastDoc as B, type ContactAdapter as C, type SubscriptionDoc as D, type EventDoc as E, type FlowStep as F, type SubscriptionStatus as G, type HealthDoc as H, type SuppressionDoc as I, type SuppressionReason as J, type TemplateKind as K, type LeadDoc as L, type MailProvider as M, type NormalizedEvent as N, type OutboxDoc as O, type Predicate as P, type TemplateVersionDoc as Q, type RunnerContext as R, type SendArgs as S, type TemplateDoc as T, ensureIndexes as U, getCollections as V, type WebhookEventDoc as W, validateSenderDomain as X, type Contact as a, type SendResult as b, type MailTesterFeedback as c, Mailer as d, type SuppressionScope as e, type SegmentFilter as f, type AuditLogDoc as g, type BroadcastStatus as h, type CircuitBreakerThresholds as i, type Collections as j, type ContactTagDoc as k, type FlowDoc as l, type FlowGoal as m, type FlowRunDoc as n, type FlowRunStatus as o, type FlowVersionDoc as p, type HealthStatus as q, type MailerConfig as r, NullProvider as s, type RedisOptions as t, type SegmentDefinition as u, type SendDoc as v, type SendStatus as w, type SenderDomainConfig as x, type SenderDomainRegistry as y, type SenderDomainValidation as z };
+export { getCollections as $, type AdapterFilter as A, type BroadcastDoc as B, type ContactAdapter as C, type DeliveryWindow as D, type EventDoc as E, type FlowStep as F, type SenderDomainValidation as G, type HealthDoc as H, type SubscriptionDoc as I, type SubscriptionStatus as J, type SuppressionDoc as K, type LeadDoc as L, type MailProvider as M, type NormalizedEvent as N, type OutboxDoc as O, type Predicate as P, type SuppressionReason as Q, type RunnerContext as R, type SendArgs as S, type TemplateDoc as T, type TemplateKind as U, type TemplateVersionDoc as V, type VarsAdapter as W, type VarsResolveInfo as X, type WebhookEventDoc as Y, defineVars as Z, ensureIndexes as _, type Contact as a, validateSenderDomain as a0, varsJsonSchema as a1, type SendResult as b, type MailTesterFeedback as c, Mailer as d, type SuppressionScope as e, type SegmentFilter as f, type AuditLogDoc as g, type BroadcastStatus as h, type CircuitBreakerThresholds as i, type Collections as j, type ContactTagDoc as k, type FlowDoc as l, type FlowGoal as m, type FlowRunDoc as n, type FlowRunStatus as o, type FlowVersionDoc as p, type HealthStatus as q, type MailerConfig as r, NullProvider as s, RESERVED_VAR_KEYS as t, type RedisOptions as u, type SegmentDefinition as v, type SendDoc as w, type SendStatus as x, type SenderDomainConfig as y, type SenderDomainRegistry as z };