mailery 0.0.0 → 0.1.0

package/dist/index.d.cts

@@ -1,3 +1,243 @@
-declare const VERSION = "0.0.0";
+import { C as ContactAdapter, a as Contact, A as AdapterFilter, M as MailProvider, S as SendArgs, b as SendResult, N as NormalizedEvent, c as Mailer, T as TemplateDoc, d as SuppressionScope } from './null-7gnz1V98.cjs';
+export { e as AuditLogDoc, B as BroadcastDoc, f as BroadcastStatus, g as CircuitBreakerThresholds, h as Collections, i as ContactTagDoc, E as EventDoc, F as FlowDoc, j as FlowGoal, k as FlowRunDoc, l as FlowRunStatus, m as FlowStep, n as FlowVersionDoc, H as HealthDoc, o as HealthStatus, L as LeadDoc, p as MailerConfig, q as NullProvider, O as OutboxDoc, P as Predicate, R as RedisOptions, r as SegmentDefinition, s as SegmentFilter, t as SendDoc, u as SendStatus, v as SubscriptionDoc, w as SubscriptionStatus, x as SuppressionDoc, y as SuppressionReason, z as TemplateKind, D as TemplateVersionDoc, W as WebhookEventDoc, G as ensureIndexes, I as getCollections } from './null-7gnz1V98.cjs';
+import { Db, Filter } from 'mongodb';
+import { Request, Router } from 'express';
+import Handlebars from 'handlebars';
+import 'ioredis';
+import 'zod';
 
-export { VERSION };
+/**
+ * MongoContactAdapter — reads contacts directly from the host's `users`
+ * collection (read-mostly; optional narrow tag writes). Mailer never
+ * duplicates identity data — the host is the source of truth.
+ */
+
+interface MongoContactAdapterOptions {
+    db: Db;
+    collection: string;
+    emailField?: string;
+    idField?: string;
+    /** Path to the tags array on the user document. */
+    tagsField?: string;
+    /** When true, mailer writes tags via `$addToSet` / `$pull` on the user doc. */
+    tagsWritable?: boolean;
+    /** 'strings' = ['vip','beta'], 'objects' = [{ name: 'vip' }]. */
+    tagsArrayShape?: 'strings' | 'objects';
+    /** Customize the projection mailer sees. Defaults pick up email + tags + a few common fields. */
+    toContact?: (userDoc: any) => Contact;
+    /** Customize how AdapterFilter becomes a Mongo query. */
+    translateFilter?: (filter: AdapterFilter) => Filter<any>;
+    /** Per-call default for query() limit. */
+    batchSize?: number;
+}
+declare class MongoContactAdapter implements ContactAdapter {
+    private readonly col;
+    private readonly emailField;
+    private readonly idField;
+    private readonly tagsField;
+    private readonly tagsWritable;
+    private readonly tagsArrayShape;
+    private readonly toContactFn;
+    private readonly translateFilterFn;
+    private readonly batchSize;
+    constructor(opts: MongoContactAdapterOptions);
+    getById(externalId: string): Promise<Contact | null>;
+    getByEmail(email: string): Promise<Contact | null>;
+    getBatch(externalIds: string[]): Promise<Map<string, Contact>>;
+    query(filter: AdapterFilter, opts: {
+        limit: number;
+        cursor?: string;
+    }): Promise<{
+        contacts: Contact[];
+        nextCursor?: string;
+    }>;
+    count(filter: AdapterFilter): Promise<number>;
+    addTags?: (externalId: string, tags: string[]) => Promise<void>;
+    removeTags?: (externalId: string, tags: string[]) => Promise<void>;
+    private idFilter;
+    private defaultToContact;
+    private defaultTranslateFilter;
+    private addTagsImpl;
+    private removeTagsImpl;
+}
+
+/**
+ * SendGridProvider — sends mail through @sendgrid/mail, verifies the Event
+ * Webhook signature with the ECDSA public key configured in SendGrid, and
+ * normalizes inbound event payloads into our shared shape.
+ *
+ * Setup steps required on the SendGrid side (one-time):
+ *   1. Authenticate sender domain (SPF, DKIM, DMARC).
+ *   2. Configure event webhook → POST to https://your.host/m/webhooks/sendgrid
+ *   3. Enable: delivered, open, click, bounce, dropped, spamreport, unsubscribe
+ *   4. Generate Signed Event Webhook key → store as webhookVerificationKey
+ */
+
+interface SendGridProviderOptions {
+    apiKey: string;
+    /** ECDSA public key (PEM) from SendGrid → Settings → Mail Settings → Signed Event Webhook. */
+    webhookVerificationKey?: string;
+    /** Send-rate cap per second (BullMQ group limiter consults this). */
+    sendRatePerSecond?: number;
+    /** Sandbox mode bypasses actual delivery — useful in dev/test. */
+    sandbox?: boolean;
+}
+declare class SendGridProvider implements MailProvider {
+    private readonly opts;
+    readonly name = "sendgrid";
+    readonly sendRatePerSecond: number;
+    constructor(opts: SendGridProviderOptions);
+    send(args: SendArgs): Promise<SendResult>;
+    verifyWebhook(rawBody: Buffer, headers: Record<string, string>): Promise<boolean>;
+    parseWebhookEvents(payload: unknown): NormalizedEvent[];
+}
+
+/**
+ * Admin router — serves the prebuilt React SPA + REST endpoints the SPA
+ * consumes. Mount inside a host Express app, gated by host auth.
+ *
+ *   app.use('/admin/mailer', requireAdmin, createAdminRouter(mailer))
+ *
+ * REST routes under /api/* are documented in plans/14-admin-api.md.
+ */
+
+interface AdminRouterOptions {
+    /** Override path to the built SPA. Defaults to `dist/admin/spa` shipped with the package. */
+    spaDir?: string;
+    /** Resolve actor metadata from a Request. Defaults to `human:${req.user?.email || 'anonymous'}`. */
+    getActor?: (req: Request) => string;
+}
+declare function createAdminRouter(mailer: Mailer, opts?: AdminRouterOptions): Router;
+
+/**
+ * Public router — endpoints that must be reachable by email clients and
+ * provider webhooks. Mount under your tracking base path (default `/m`).
+ *
+ *   app.use('/m', createPublicRouter(mailer))
+ *
+ * Routes:
+ *   GET  /open/:sendId.png         — open pixel (records open, returns 1×1 PNG)
+ *   GET  /click/:sendId/:linkId    — click redirect (records click, 302 → target)
+ *   GET  /unsub/:token             — confirmation page (one-click POST link)
+ *   POST /unsub/:token             — RFC 8058 one-click unsubscribe
+ *   POST /webhooks/:provider       — inbound provider event webhook
+ */
+
+interface PublicRouterOptions {
+    /**
+     * Path on disk where unsubscribe events fall back to when Mongo is degraded.
+     * Defaults to /tmp/mailery-pending-unsubs.jsonl.
+     */
+    pendingUnsubsPath?: string;
+}
+declare function createPublicRouter(mailer: Mailer, opts?: PublicRouterOptions): Router;
+
+/**
+ * Template render pipeline.
+ *
+ *  authorMjml + handlebarsContext
+ *     ↓ Handlebars render          → MJML with substituted vars
+ *     ↓ mjml-core compile          → HTML
+ *     ↓ html-to-text derive        → plain text alternative
+ *     ↓ applyTracking(sendId)      → tracked HTML with rewritten links + open pixel
+ *
+ * Subject and preheader run through Handlebars too. Plain text is auto-derived
+ * unless the template explicitly overrides it.
+ */
+
+interface CompileResult {
+    html: string;
+    plainText: string;
+    errors: Array<{
+        line?: number;
+        message: string;
+        tagName?: string;
+        formattedMessage?: string;
+    }>;
+}
+/** Compile MJML → HTML, then derive plain text. Called at template publish time. */
+declare function compileTemplate(mjml: string): Promise<CompileResult>;
+/** Auto-derive plain text from compiled HTML. */
+declare function derivePlaintext(html: string): string;
+interface RenderContext {
+    contact: Contact;
+    vars: Record<string, unknown>;
+    /** URL the recipient hits to one-click unsubscribe. */
+    unsubscribeUrl: string;
+    /** URL to view this email in a browser (when implemented). */
+    viewInBrowserUrl?: string;
+    /** URL for the preference center (when implemented). */
+    preferenceCenterUrl?: string;
+    /** Configured sender postal address (CAN-SPAM). */
+    senderAddress?: string;
+}
+interface RenderedTemplate {
+    subject: string;
+    preheader: string;
+    html: string;
+    plainText: string;
+    fromName: string;
+    fromEmail: string;
+    replyTo: string | null;
+}
+interface RenderOptions {
+    /** Extra Handlebars helpers contributed by the host. */
+    helpers?: Record<string, Handlebars.HelperDelegate>;
+}
+/**
+ * Render a published template against a contact + vars context. Returns the
+ * substituted subject/preheader/html/plainText. Tracking is NOT applied here —
+ * that step needs the send id and runs separately via `applyTracking`.
+ */
+declare function renderTemplate(template: TemplateDoc, ctx: RenderContext, opts?: RenderOptions): Promise<RenderedTemplate>;
+interface TrackingOptions {
+    sendId: string;
+    publicUrl: string;
+    trackOpens: boolean;
+    trackClicks: boolean;
+    /** URL that must NOT be rewritten (e.g. the resolved unsubscribe URL). */
+    preserveUrls?: string[];
+}
+interface TrackingResult {
+    html: string;
+    /** linkId → original URL map; persist on `mailer_sends.links` for click resolution. */
+    links: Array<{
+        linkId: string;
+        url: string;
+    }>;
+}
+/**
+ * Rewrite `<a href>` in `html` to /m/click/<sendId>/<linkId>?... and append an
+ * open pixel. Returns the modified HTML plus the link map to persist on the
+ * send document.
+ */
+declare function applyTracking(html: string, opts: TrackingOptions): TrackingResult;
+
+/**
+ * HMAC-signed tokens for unsubscribe + preference-center URLs.
+ *
+ * Format:  base64url(payload) '.' base64url(hmac)
+ *   payload  = JSON.stringify({ e: email, s: scope, x: expiresAtMs })
+ *   hmac     = HMAC-SHA256(secret, payload)
+ *
+ * Tokens expire because long-lived signed URLs are a liability.
+ */
+
+interface UnsubscribeTokenPayload {
+    email: string;
+    scope: SuppressionScope;
+    expiresAt: Date;
+}
+declare function signUnsubscribeToken(payload: UnsubscribeTokenPayload, secret: string): string;
+declare function verifyUnsubscribeToken(token: string, secret: string, now?: Date): UnsubscribeTokenPayload | null;
+/**
+ * sha256 hex digest, used for storing email hashes (GDPR forget) and dedup helpers.
+ */
+declare function sha256Hex(input: string): string;
+
+/**
+ * Public exports for the `mailery` package.
+ */
+declare const VERSION = "0.1.0";
+
+export { AdapterFilter, type AdminRouterOptions, Contact, ContactAdapter, MailProvider, Mailer, MongoContactAdapter, type MongoContactAdapterOptions, NormalizedEvent, type PublicRouterOptions, SendArgs, SendGridProvider, type SendGridProviderOptions, SendResult, SuppressionScope, TemplateDoc, VERSION, applyTracking, compileTemplate, createAdminRouter, createPublicRouter, derivePlaintext, renderTemplate, sha256Hex, signUnsubscribeToken, verifyUnsubscribeToken };

package/dist/index.d.ts

@@ -1,3 +1,243 @@
-declare const VERSION = "0.0.0";
+import { C as ContactAdapter, a as Contact, A as AdapterFilter, M as MailProvider, S as SendArgs, b as SendResult, N as NormalizedEvent, c as Mailer, T as TemplateDoc, d as SuppressionScope } from './null-7gnz1V98.js';
+export { e as AuditLogDoc, B as BroadcastDoc, f as BroadcastStatus, g as CircuitBreakerThresholds, h as Collections, i as ContactTagDoc, E as EventDoc, F as FlowDoc, j as FlowGoal, k as FlowRunDoc, l as FlowRunStatus, m as FlowStep, n as FlowVersionDoc, H as HealthDoc, o as HealthStatus, L as LeadDoc, p as MailerConfig, q as NullProvider, O as OutboxDoc, P as Predicate, R as RedisOptions, r as SegmentDefinition, s as SegmentFilter, t as SendDoc, u as SendStatus, v as SubscriptionDoc, w as SubscriptionStatus, x as SuppressionDoc, y as SuppressionReason, z as TemplateKind, D as TemplateVersionDoc, W as WebhookEventDoc, G as ensureIndexes, I as getCollections } from './null-7gnz1V98.js';
+import { Db, Filter } from 'mongodb';
+import { Request, Router } from 'express';
+import Handlebars from 'handlebars';
+import 'ioredis';
+import 'zod';
 
-export { VERSION };
+/**
+ * MongoContactAdapter — reads contacts directly from the host's `users`
+ * collection (read-mostly; optional narrow tag writes). Mailer never
+ * duplicates identity data — the host is the source of truth.
+ */
+
+interface MongoContactAdapterOptions {
+    db: Db;
+    collection: string;
+    emailField?: string;
+    idField?: string;
+    /** Path to the tags array on the user document. */
+    tagsField?: string;
+    /** When true, mailer writes tags via `$addToSet` / `$pull` on the user doc. */
+    tagsWritable?: boolean;
+    /** 'strings' = ['vip','beta'], 'objects' = [{ name: 'vip' }]. */
+    tagsArrayShape?: 'strings' | 'objects';
+    /** Customize the projection mailer sees. Defaults pick up email + tags + a few common fields. */
+    toContact?: (userDoc: any) => Contact;
+    /** Customize how AdapterFilter becomes a Mongo query. */
+    translateFilter?: (filter: AdapterFilter) => Filter<any>;
+    /** Per-call default for query() limit. */
+    batchSize?: number;
+}
+declare class MongoContactAdapter implements ContactAdapter {
+    private readonly col;
+    private readonly emailField;
+    private readonly idField;
+    private readonly tagsField;
+    private readonly tagsWritable;
+    private readonly tagsArrayShape;
+    private readonly toContactFn;
+    private readonly translateFilterFn;
+    private readonly batchSize;
+    constructor(opts: MongoContactAdapterOptions);
+    getById(externalId: string): Promise<Contact | null>;
+    getByEmail(email: string): Promise<Contact | null>;
+    getBatch(externalIds: string[]): Promise<Map<string, Contact>>;
+    query(filter: AdapterFilter, opts: {
+        limit: number;
+        cursor?: string;
+    }): Promise<{
+        contacts: Contact[];
+        nextCursor?: string;
+    }>;
+    count(filter: AdapterFilter): Promise<number>;
+    addTags?: (externalId: string, tags: string[]) => Promise<void>;
+    removeTags?: (externalId: string, tags: string[]) => Promise<void>;
+    private idFilter;
+    private defaultToContact;
+    private defaultTranslateFilter;
+    private addTagsImpl;
+    private removeTagsImpl;
+}
+
+/**
+ * SendGridProvider — sends mail through @sendgrid/mail, verifies the Event
+ * Webhook signature with the ECDSA public key configured in SendGrid, and
+ * normalizes inbound event payloads into our shared shape.
+ *
+ * Setup steps required on the SendGrid side (one-time):
+ *   1. Authenticate sender domain (SPF, DKIM, DMARC).
+ *   2. Configure event webhook → POST to https://your.host/m/webhooks/sendgrid
+ *   3. Enable: delivered, open, click, bounce, dropped, spamreport, unsubscribe
+ *   4. Generate Signed Event Webhook key → store as webhookVerificationKey
+ */
+
+interface SendGridProviderOptions {
+    apiKey: string;
+    /** ECDSA public key (PEM) from SendGrid → Settings → Mail Settings → Signed Event Webhook. */
+    webhookVerificationKey?: string;
+    /** Send-rate cap per second (BullMQ group limiter consults this). */
+    sendRatePerSecond?: number;
+    /** Sandbox mode bypasses actual delivery — useful in dev/test. */
+    sandbox?: boolean;
+}
+declare class SendGridProvider implements MailProvider {
+    private readonly opts;
+    readonly name = "sendgrid";
+    readonly sendRatePerSecond: number;
+    constructor(opts: SendGridProviderOptions);
+    send(args: SendArgs): Promise<SendResult>;
+    verifyWebhook(rawBody: Buffer, headers: Record<string, string>): Promise<boolean>;
+    parseWebhookEvents(payload: unknown): NormalizedEvent[];
+}
+
+/**
+ * Admin router — serves the prebuilt React SPA + REST endpoints the SPA
+ * consumes. Mount inside a host Express app, gated by host auth.
+ *
+ *   app.use('/admin/mailer', requireAdmin, createAdminRouter(mailer))
+ *
+ * REST routes under /api/* are documented in plans/14-admin-api.md.
+ */
+
+interface AdminRouterOptions {
+    /** Override path to the built SPA. Defaults to `dist/admin/spa` shipped with the package. */
+    spaDir?: string;
+    /** Resolve actor metadata from a Request. Defaults to `human:${req.user?.email || 'anonymous'}`. */
+    getActor?: (req: Request) => string;
+}
+declare function createAdminRouter(mailer: Mailer, opts?: AdminRouterOptions): Router;
+
+/**
+ * Public router — endpoints that must be reachable by email clients and
+ * provider webhooks. Mount under your tracking base path (default `/m`).
+ *
+ *   app.use('/m', createPublicRouter(mailer))
+ *
+ * Routes:
+ *   GET  /open/:sendId.png         — open pixel (records open, returns 1×1 PNG)
+ *   GET  /click/:sendId/:linkId    — click redirect (records click, 302 → target)
+ *   GET  /unsub/:token             — confirmation page (one-click POST link)
+ *   POST /unsub/:token             — RFC 8058 one-click unsubscribe
+ *   POST /webhooks/:provider       — inbound provider event webhook
+ */
+
+interface PublicRouterOptions {
+    /**
+     * Path on disk where unsubscribe events fall back to when Mongo is degraded.
+     * Defaults to /tmp/mailery-pending-unsubs.jsonl.
+     */
+    pendingUnsubsPath?: string;
+}
+declare function createPublicRouter(mailer: Mailer, opts?: PublicRouterOptions): Router;
+
+/**
+ * Template render pipeline.
+ *
+ *  authorMjml + handlebarsContext
+ *     ↓ Handlebars render          → MJML with substituted vars
+ *     ↓ mjml-core compile          → HTML
+ *     ↓ html-to-text derive        → plain text alternative
+ *     ↓ applyTracking(sendId)      → tracked HTML with rewritten links + open pixel
+ *
+ * Subject and preheader run through Handlebars too. Plain text is auto-derived
+ * unless the template explicitly overrides it.
+ */
+
+interface CompileResult {
+    html: string;
+    plainText: string;
+    errors: Array<{
+        line?: number;
+        message: string;
+        tagName?: string;
+        formattedMessage?: string;
+    }>;
+}
+/** Compile MJML → HTML, then derive plain text. Called at template publish time. */
+declare function compileTemplate(mjml: string): Promise<CompileResult>;
+/** Auto-derive plain text from compiled HTML. */
+declare function derivePlaintext(html: string): string;
+interface RenderContext {
+    contact: Contact;
+    vars: Record<string, unknown>;
+    /** URL the recipient hits to one-click unsubscribe. */
+    unsubscribeUrl: string;
+    /** URL to view this email in a browser (when implemented). */
+    viewInBrowserUrl?: string;
+    /** URL for the preference center (when implemented). */
+    preferenceCenterUrl?: string;
+    /** Configured sender postal address (CAN-SPAM). */
+    senderAddress?: string;
+}
+interface RenderedTemplate {
+    subject: string;
+    preheader: string;
+    html: string;
+    plainText: string;
+    fromName: string;
+    fromEmail: string;
+    replyTo: string | null;
+}
+interface RenderOptions {
+    /** Extra Handlebars helpers contributed by the host. */
+    helpers?: Record<string, Handlebars.HelperDelegate>;
+}
+/**
+ * Render a published template against a contact + vars context. Returns the
+ * substituted subject/preheader/html/plainText. Tracking is NOT applied here —
+ * that step needs the send id and runs separately via `applyTracking`.
+ */
+declare function renderTemplate(template: TemplateDoc, ctx: RenderContext, opts?: RenderOptions): Promise<RenderedTemplate>;
+interface TrackingOptions {
+    sendId: string;
+    publicUrl: string;
+    trackOpens: boolean;
+    trackClicks: boolean;
+    /** URL that must NOT be rewritten (e.g. the resolved unsubscribe URL). */
+    preserveUrls?: string[];
+}
+interface TrackingResult {
+    html: string;
+    /** linkId → original URL map; persist on `mailer_sends.links` for click resolution. */
+    links: Array<{
+        linkId: string;
+        url: string;
+    }>;
+}
+/**
+ * Rewrite `<a href>` in `html` to /m/click/<sendId>/<linkId>?... and append an
+ * open pixel. Returns the modified HTML plus the link map to persist on the
+ * send document.
+ */
+declare function applyTracking(html: string, opts: TrackingOptions): TrackingResult;
+
+/**
+ * HMAC-signed tokens for unsubscribe + preference-center URLs.
+ *
+ * Format:  base64url(payload) '.' base64url(hmac)
+ *   payload  = JSON.stringify({ e: email, s: scope, x: expiresAtMs })
+ *   hmac     = HMAC-SHA256(secret, payload)
+ *
+ * Tokens expire because long-lived signed URLs are a liability.
+ */
+
+interface UnsubscribeTokenPayload {
+    email: string;
+    scope: SuppressionScope;
+    expiresAt: Date;
+}
+declare function signUnsubscribeToken(payload: UnsubscribeTokenPayload, secret: string): string;
+declare function verifyUnsubscribeToken(token: string, secret: string, now?: Date): UnsubscribeTokenPayload | null;
+/**
+ * sha256 hex digest, used for storing email hashes (GDPR forget) and dedup helpers.
+ */
+declare function sha256Hex(input: string): string;
+
+/**
+ * Public exports for the `mailery` package.
+ */
+declare const VERSION = "0.1.0";
+
+export { AdapterFilter, type AdminRouterOptions, Contact, ContactAdapter, MailProvider, Mailer, MongoContactAdapter, type MongoContactAdapterOptions, NormalizedEvent, type PublicRouterOptions, SendArgs, SendGridProvider, type SendGridProviderOptions, SendResult, SuppressionScope, TemplateDoc, VERSION, applyTracking, compileTemplate, createAdminRouter, createPublicRouter, derivePlaintext, renderTemplate, sha256Hex, signUnsubscribeToken, verifyUnsubscribeToken };