@growth-labs/mailer 0.4.7 → 0.4.8

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export default function mailer(userOptions: MailerOptions): AstroIntegration;
 export type { MailerOptions, ResolvedMailerOptions } from './options.js';
 export { mailerOptionsSchema } from './options.js';
 export type { DigestItem, EmailProvider, EmailQueueMessage, EmailSend, EmailSendStatus, OutboundEmail, SendResult, SiteConfigLookup, SiteMailerConfig, Subscriber, SubscriberFilter, SubscriberStatus, TemplateData, TemplateName, } from './types.js';
+export type { BroadcastRecipient, SendBroadcastParams, SendBroadcastResult, } from './utils/broadcast.js';
+export { sendBroadcast } from './utils/broadcast.js';
 export type { CampaignSchedule, DigestSchedule } from './utils/scheduling.js';
 export { executeCampaignSchedule, executeDigestSchedule, prepareCampaign, prepareDigest, sendBatchCampaigns, } from './utils/scheduling.js';
 export type { MailerEnv } from './utils/send.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAA;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAyB,MAAM,cAAc,CAAA;AAmBxE,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,WAAW,EAAE,aAAa,GAAG,gBAAgB,CAiE3E;AAED,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAExE,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAClD,YAAY,EACX,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,YAAY,GACZ,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC7E,OAAO,EACN,uBAAuB,EACvB,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,kBAAkB,GAClB,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAC7E,OAAO,EACN,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,GACjB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAA;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAyB,MAAM,cAAc,CAAA;AAmBxE,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,WAAW,EAAE,aAAa,GAAG,gBAAgB,CAiE3E;AAED,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAExE,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAClD,YAAY,EACX,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,YAAY,GACZ,MAAM,YAAY,CAAA;AACnB,YAAY,EACX,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,GACnB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC7E,OAAO,EACN,uBAAuB,EACvB,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,kBAAkB,GAClB,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAC7E,OAAO,EACN,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,GACjB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/index.js

@@ -75,6 +75,7 @@ export default function mailer(userOptions) {
 }
 // Re-export options and types
 export { mailerOptionsSchema } from './options.js';
+export { sendBroadcast } from './utils/broadcast.js';
 export { executeCampaignSchedule, executeDigestSchedule, prepareCampaign, prepareDigest, sendBatchCampaigns, } from './utils/scheduling.js';
 // Re-export utilities for standalone use
 export { sendCampaign, sendDigest, sendTransactional } from './utils/send.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -29,7 +29,7 @@ export interface SubscriberFilter {
 }
 export interface EmailQueueMessage {
     siteId: string;
-    type: 'transactional' | 'campaign' | 'digest';
+    type: 'transactional' | 'campaign' | 'digest' | 'broadcast';
     recipients: QueueRecipient[];
     subject: string;
     htmlTemplate: string;
@@ -77,7 +77,7 @@ export interface EmailSend {
     campaignId?: string;
     email: string;
     subject: string;
-    type: 'transactional' | 'campaign' | 'digest';
+    type: 'transactional' | 'campaign' | 'digest' | 'broadcast';
     status: EmailSendStatus;
     sentAt?: string;
     deliveredAt?: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/utils/broadcast.d.ts

@@ -0,0 +1,82 @@
+import type { ResolvedMailerOptions } from '../options.js';
+import type { MailerEnv } from './send.js';
+/**
+ * One recipient of a broadcast. `subscriberId` is optional: when omitted the
+ * subscriber is resolved by `email` against `gl_subscribers` (needed both for
+ * suppression enforcement and for per-recipient unsubscribe/preferences links).
+ * An email with no matching subscriber row is treated as suppressed (we never
+ * blast an address we cannot honour an unsubscribe for).
+ */
+export interface BroadcastRecipient {
+    email: string;
+    subscriberId?: string;
+}
+export interface SendBroadcastParams {
+    /**
+     * Explicit recipient list. Mutually-resolvable with `segmentName` +
+     * `resolveRecipients`: segmentation itself is NOT built here (WS5 bead 06 is
+     * identity-gated) — `sendBroadcast` takes the list, or a resolver callback
+     * that turns a saved-segment name into the list, from elsewhere.
+     */
+    recipients?: Array<BroadcastRecipient | string>;
+    /**
+     * Name of a saved segment to blast. Resolved to a recipient list by
+     * `resolveRecipients` (provided by the caller / a later segmentation bead).
+     */
+    segmentName?: string;
+    /**
+     * Resolves a saved-segment name to its recipient list. Supplied by the
+     * caller; broadcast does not implement segmentation.
+     */
+    resolveRecipients?: (segmentName: string) => Promise<Array<BroadcastRecipient | string>>;
+    subject: string;
+    html: string;
+    /**
+     * Idempotency key. A re-run with the same `campaignId` will NOT re-send to
+     * any recipient that already has a `gl_email_sends` row for this campaign.
+     * Auto-generated when omitted (a fresh, non-idempotent blast).
+     */
+    campaignId?: string;
+    /** When true, resolve + suppress + dedupe and return counts WITHOUT sending. */
+    dryRun?: boolean;
+    /**
+     * Max recipients packed into a single queue message. Bounds the message
+     * payload well under Cloudflare's 128 KiB queue-message limit. Default 100.
+     */
+    maxRecipientsPerMessage?: number;
+    /**
+     * Max queue messages to enqueue per second, to stay under Cloudflare send /
+     * queue producer rate limits. `0` (default) disables pacing.
+     */
+    messagesPerSecond?: number;
+}
+export interface SendBroadcastResult {
+    campaignId: string;
+    /** Recipients actually queued (dry-run: would-be-queued). */
+    recipientCount: number;
+    /** Recipients skipped because their subscriber row is on the suppression list. */
+    suppressedCount: number;
+    /** Recipients skipped because a `gl_email_sends` row already existed (idempotency). */
+    alreadySentCount: number;
+    /** Number of queue messages enqueued (0 on dry-run). */
+    batchCount: number;
+    dryRun: boolean;
+}
+/**
+ * Send a one-off broadcast blast (Customer.io one-off-blast parity).
+ *
+ * - Takes an explicit recipient list, or a saved-segment name resolved via
+ *   `resolveRecipients` (segmentation is NOT built here — WS5 bead 06).
+ * - Enforces the suppression list: only `active` subscribers are sent;
+ *   unsubscribed / bounced / complained / pending / unknown addresses skip.
+ * - Idempotent on `campaignId`: a re-run never double-sends to a recipient that
+ *   already has a `gl_email_sends` row for the campaign.
+ * - Writes a per-recipient `gl_email_sends` row (`type='broadcast'`, status
+ *   `queued`) before enqueueing.
+ * - Fans out in batches sized for Cloudflare queue/send-rate limits, with
+ *   optional `messagesPerSecond` pacing.
+ * - `dryRun` resolves + suppresses + dedupes and returns the recipient count
+ *   WITHOUT writing rows or enqueueing anything.
+ */
+export declare function sendBroadcast(env: MailerEnv, options: ResolvedMailerOptions, params: SendBroadcastParams): Promise<SendBroadcastResult>;
+//# sourceMappingURL=broadcast.d.ts.map

package/dist/utils/broadcast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"broadcast.d.ts","sourceRoot":"","sources":["../../src/utils/broadcast.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAK1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAsB1C;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,mBAAmB;IACnC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,KAAK,CAAC,kBAAkB,GAAG,MAAM,CAAC,CAAA;IAC/C;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC,kBAAkB,GAAG,MAAM,CAAC,CAAC,CAAA;IAExF,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IAEZ;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB,gFAAgF;IAChF,MAAM,CAAC,EAAE,OAAO,CAAA;IAEhB;;;OAGG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAEhC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,mBAAmB;IACnC,UAAU,EAAE,MAAM,CAAA;IAClB,6DAA6D;IAC7D,cAAc,EAAE,MAAM,CAAA;IACtB,kFAAkF;IAClF,eAAe,EAAE,MAAM,CAAA;IACvB,uFAAuF;IACvF,gBAAgB,EAAE,MAAM,CAAA;IACxB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,OAAO,CAAA;CACf;AAmJD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CAClC,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,qBAAqB,EAC9B,MAAM,EAAE,mBAAmB,GACzB,OAAO,CAAC,mBAAmB,CAAC,CA8H9B"}

package/dist/utils/broadcast.js

@@ -0,0 +1,254 @@
+import { and, eq, inArray } from 'drizzle-orm';
+import { drizzle } from 'drizzle-orm/d1';
+import { ulid } from 'ulidx';
+import { emailSends } from '../schema/sends.js';
+import { subscribers } from '../schema/subscribers.js';
+import { sleep } from './providers.js';
+import { generateToken } from './tokens.js';
+import { injectTrackingPixel, rewriteLinksForTracking } from './tracking.js';
+/**
+ * Statuses that mean "do not send" — the suppression list. A broadcast skips
+ * every recipient whose `gl_subscribers` row carries one of these. `active` is
+ * the ONLY sendable status; everything else (including `pending`, i.e. an
+ * unconfirmed double-opt-in subscriber) is suppressed so a one-off blast can
+ * never re-permission or re-mail a suppressed address.
+ */
+const SUPPRESSED_STATUSES = new Set([
+    'unsubscribed',
+    'bounced',
+    'complained',
+    'pending',
+]);
+function resolveProducerBindings(env, options) {
+    const d1 = env[options.d1Binding];
+    if (!d1) {
+        throw new Error(`[mailer] env.${options.d1Binding} is undefined; ` +
+            'pass d1Binding option to the mailer integration or bind that name in wrangler.toml.');
+    }
+    const queue = env[options.queueBinding];
+    if (!queue) {
+        throw new Error(`[mailer] env.${options.queueBinding} is undefined; ` +
+            'pass queueBinding option to the mailer integration or bind that name in wrangler.toml.');
+    }
+    return { db: drizzle(d1), queue };
+}
+function normalizeRecipient(r) {
+    return typeof r === 'string' ? { email: r } : r;
+}
+/**
+ * Resolve each requested recipient against `gl_subscribers`:
+ *   - dedupe by email (a list may repeat an address)
+ *   - attach the canonical subscriberId + status
+ *   - drop emails with no subscriber row (cannot honour unsubscribe → suppress)
+ * Returns the resolved sendable-candidate set plus the suppressed count.
+ */
+async function resolveAgainstSubscribers(db, requested) {
+    // Dedupe requested emails (case-insensitive, trimmed) preserving first-seen order.
+    const byEmail = new Map();
+    for (const r of requested) {
+        const key = r.email.trim().toLowerCase();
+        if (key.length === 0)
+            continue;
+        if (!byEmail.has(key))
+            byEmail.set(key, { ...r, email: r.email.trim() });
+    }
+    const emails = [...byEmail.values()].map((r) => r.email);
+    if (emails.length === 0)
+        return { candidates: [], suppressedCount: 0 };
+    // Look up subscriber rows for all requested emails.
+    const rows = await db
+        .select({
+        id: subscribers.id,
+        email: subscribers.email,
+        status: subscribers.status,
+    })
+        .from(subscribers)
+        .where(inArray(subscribers.email, emails));
+    const rowByEmail = new Map();
+    for (const row of rows) {
+        rowByEmail.set(row.email.toLowerCase(), {
+            id: row.id,
+            status: row.status,
+        });
+    }
+    const candidates = [];
+    let suppressedCount = 0;
+    for (const r of byEmail.values()) {
+        const row = rowByEmail.get(r.email.toLowerCase());
+        // No subscriber row, or a suppressed status → skip. Never send to an
+        // address we cannot honour an unsubscribe for, and never to a
+        // bounced/complained/unsubscribed/pending one.
+        if (!row || SUPPRESSED_STATUSES.has(row.status)) {
+            suppressedCount++;
+            continue;
+        }
+        candidates.push({ email: r.email, subscriberId: r.subscriberId ?? row.id, status: row.status });
+    }
+    return { candidates, suppressedCount };
+}
+/**
+ * Of the suppression-cleared candidates, drop any that already have a
+ * `gl_email_sends` row for this campaignId — the idempotency guard that makes a
+ * re-run a no-op for already-processed recipients.
+ */
+async function filterAlreadySent(db, campaignId, candidates) {
+    if (candidates.length === 0)
+        return { fresh: [], alreadySentCount: 0 };
+    const candidateEmails = candidates.map((c) => c.email);
+    const existing = await db
+        .select({ email: emailSends.email })
+        .from(emailSends)
+        .where(and(eq(emailSends.campaignId, campaignId), inArray(emailSends.email, candidateEmails)));
+    const sentEmails = new Set(existing.map((row) => row.email.toLowerCase()));
+    const fresh = [];
+    let alreadySentCount = 0;
+    for (const c of candidates) {
+        if (sentEmails.has(c.email.toLowerCase())) {
+            alreadySentCount++;
+            continue;
+        }
+        fresh.push(c);
+    }
+    return { fresh, alreadySentCount };
+}
+/**
+ * Build the broadcast HTML with the tracking pixel + click-rewrite applied
+ * once (the per-recipient {{TRACKING_ID}} is substituted in the consumer).
+ */
+function prepareBroadcastHtml(html, options) {
+    const trackOpenUrl = `${options.siteUrl}${options.trackOpenPath}`;
+    const trackClickUrl = `${options.siteUrl}${options.trackClickPath}`;
+    return rewriteLinksForTracking(injectTrackingPixel(html, trackOpenUrl), trackClickUrl);
+}
+function chunk(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size) {
+        out.push(items.slice(i, i + size));
+    }
+    return out;
+}
+/**
+ * Send a one-off broadcast blast (Customer.io one-off-blast parity).
+ *
+ * - Takes an explicit recipient list, or a saved-segment name resolved via
+ *   `resolveRecipients` (segmentation is NOT built here — WS5 bead 06).
+ * - Enforces the suppression list: only `active` subscribers are sent;
+ *   unsubscribed / bounced / complained / pending / unknown addresses skip.
+ * - Idempotent on `campaignId`: a re-run never double-sends to a recipient that
+ *   already has a `gl_email_sends` row for the campaign.
+ * - Writes a per-recipient `gl_email_sends` row (`type='broadcast'`, status
+ *   `queued`) before enqueueing.
+ * - Fans out in batches sized for Cloudflare queue/send-rate limits, with
+ *   optional `messagesPerSecond` pacing.
+ * - `dryRun` resolves + suppresses + dedupes and returns the recipient count
+ *   WITHOUT writing rows or enqueueing anything.
+ */
+export async function sendBroadcast(env, options, params) {
+    const campaignId = params.campaignId ?? ulid();
+    const dryRun = params.dryRun ?? false;
+    const maxRecipientsPerMessage = Math.max(1, Math.min(params.maxRecipientsPerMessage ?? options.batchSize, 500));
+    const messagesPerSecond = params.messagesPerSecond ?? 0;
+    const { db, queue } = resolveProducerBindings(env, options);
+    // 1. Resolve the recipient list — explicit list and/or a resolved segment.
+    const requestedRaw = [...(params.recipients ?? [])];
+    if (params.segmentName) {
+        if (!params.resolveRecipients) {
+            throw new Error('[mailer] sendBroadcast: segmentName given without resolveRecipients; ' +
+                'segmentation is resolved by the caller (WS5 bead 06), not by the mailer.');
+        }
+        const resolved = await params.resolveRecipients(params.segmentName);
+        requestedRaw.push(...resolved);
+    }
+    if (requestedRaw.length === 0) {
+        throw new Error('[mailer] sendBroadcast: no recipients or segmentName provided');
+    }
+    const requested = requestedRaw.map(normalizeRecipient);
+    // 2. Suppression enforcement + dedupe.
+    const { candidates, suppressedCount } = await resolveAgainstSubscribers(db, requested);
+    // 3. Idempotency — drop recipients already recorded for this campaign.
+    const { fresh, alreadySentCount } = await filterAlreadySent(db, campaignId, candidates);
+    // Dry-run: report the counts and stop before any write or enqueue.
+    if (dryRun) {
+        return {
+            campaignId,
+            recipientCount: fresh.length,
+            suppressedCount,
+            alreadySentCount,
+            batchCount: 0,
+            dryRun: true,
+        };
+    }
+    if (fresh.length === 0) {
+        return {
+            campaignId,
+            recipientCount: 0,
+            suppressedCount,
+            alreadySentCount,
+            batchCount: 0,
+            dryRun: false,
+        };
+    }
+    const html = prepareBroadcastHtml(params.html, options);
+    const now = new Date().toISOString();
+    // 4. Per-recipient row write + queue-recipient build.
+    const queueRecipients = [];
+    for (const recipient of fresh) {
+        const trackingId = ulid();
+        const [unsubscribeToken, preferencesToken] = await Promise.all([
+            generateToken(options.signingSecret, {
+                subscriberId: recipient.subscriberId,
+                action: 'unsubscribe',
+            }),
+            generateToken(options.signingSecret, {
+                subscriberId: recipient.subscriberId,
+                action: 'preferences',
+            }),
+        ]);
+        await db.insert(emailSends).values({
+            id: ulid(),
+            subscriberId: recipient.subscriberId,
+            campaignId,
+            email: recipient.email,
+            subject: params.subject,
+            type: 'broadcast',
+            status: 'queued',
+            trackingId,
+            createdAt: now,
+        });
+        queueRecipients.push({
+            email: recipient.email,
+            subscriberId: recipient.subscriberId,
+            trackingId,
+            unsubscribeToken,
+            preferencesToken,
+        });
+    }
+    // 5. Batched fan-out, paced to the configured send rate.
+    const batches = chunk(queueRecipients, maxRecipientsPerMessage);
+    const intervalMs = messagesPerSecond > 0 ? Math.ceil(1000 / messagesPerSecond) : 0;
+    for (let i = 0; i < batches.length; i++) {
+        const message = {
+            siteId: options.siteId,
+            type: 'broadcast',
+            recipients: batches[i],
+            subject: params.subject,
+            htmlTemplate: html,
+            from: `${options.senderName} <${options.fromAddress}>`,
+            replyTo: options.replyTo,
+            campaignId,
+        };
+        await queue.send(message);
+        if (intervalMs > 0 && i < batches.length - 1) {
+            await sleep(intervalMs);
+        }
+    }
+    return {
+        campaignId,
+        recipientCount: fresh.length,
+        suppressedCount,
+        alreadySentCount,
+        batchCount: batches.length,
+        dryRun: false,
+    };
+}
+//# sourceMappingURL=broadcast.js.map

package/dist/utils/broadcast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"broadcast.js","sourceRoot":"","sources":["../../src/utils/broadcast.ts"],"names":[],"mappings":"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"}

package/dist/utils/index.d.ts

@@ -1,5 +1,7 @@
 export { buildMailerAnalyticsDataPoint, emitMailerAnalyticsEvent, type MailerAnalyticsEvent, } from './analytics.js';
 export { handleBounce, handleComplaint, handleDelivery, updateSendStatus, } from './bounce.js';
+export type { BroadcastRecipient, SendBroadcastParams, SendBroadcastResult, } from './broadcast.js';
+export { sendBroadcast } from './broadcast.js';
 export type { CloudflareEmailSender } from './providers.js';
 export { CloudflareEmailProvider, getProvider, sleep } from './providers.js';
 export type { CampaignSchedule, DigestSchedule } from './scheduling.js';

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,6BAA6B,EAC7B,wBAAwB,EACxB,KAAK,oBAAoB,GACzB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACN,YAAY,EACZ,eAAe,EACf,cAAc,EACd,gBAAgB,GAChB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAC3D,OAAO,EAAE,uBAAuB,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAC5E,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACvE,OAAO,EACN,uBAAuB,EACvB,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,kBAAkB,GAClB,MAAM,iBAAiB,CAAA;AACxB,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AACvE,OAAO,EACN,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,GACjB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACN,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,iBAAiB,EACjB,WAAW,GACX,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACxD,OAAO,EACN,mBAAmB,EACnB,uBAAuB,EACvB,eAAe,GACf,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,6BAA6B,EAC7B,wBAAwB,EACxB,KAAK,oBAAoB,GACzB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACN,YAAY,EACZ,eAAe,EACf,cAAc,EACd,gBAAgB,GAChB,MAAM,aAAa,CAAA;AACpB,YAAY,EACX,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,GACnB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAC9C,YAAY,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAC3D,OAAO,EAAE,uBAAuB,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAC5E,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACvE,OAAO,EACN,uBAAuB,EACvB,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,kBAAkB,GAClB,MAAM,iBAAiB,CAAA;AACxB,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AACvE,OAAO,EACN,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,GACjB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACN,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,iBAAiB,EACjB,WAAW,GACX,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACxD,OAAO,EACN,mBAAmB,EACnB,uBAAuB,EACvB,eAAe,GACf,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA"}

package/dist/utils/index.js

@@ -1,5 +1,6 @@
 export { buildMailerAnalyticsDataPoint, emitMailerAnalyticsEvent, } from './analytics.js';
 export { handleBounce, handleComplaint, handleDelivery, updateSendStatus, } from './bounce.js';
+export { sendBroadcast } from './broadcast.js';
 export { CloudflareEmailProvider, getProvider, sleep } from './providers.js';
 export { executeCampaignSchedule, executeDigestSchedule, prepareCampaign, prepareDigest, sendBatchCampaigns, } from './scheduling.js';
 export { sendCampaign, sendDigest, sendTransactional } from './send.js';

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,6BAA6B,EAC7B,wBAAwB,GAExB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACN,YAAY,EACZ,eAAe,EACf,cAAc,EACd,gBAAgB,GAChB,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,uBAAuB,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAE5E,OAAO,EACN,uBAAuB,EACvB,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,kBAAkB,GAClB,MAAM,iBAAiB,CAAA;AAExB,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AACvE,OAAO,EACN,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,GACjB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACN,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,iBAAiB,EACjB,WAAW,GACX,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACxD,OAAO,EACN,mBAAmB,EACnB,uBAAuB,EACvB,eAAe,GACf,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,6BAA6B,EAC7B,wBAAwB,GAExB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACN,YAAY,EACZ,eAAe,EACf,cAAc,EACd,gBAAgB,GAChB,MAAM,aAAa,CAAA;AAMpB,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAE9C,OAAO,EAAE,uBAAuB,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAE5E,OAAO,EACN,uBAAuB,EACvB,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,kBAAkB,GAClB,MAAM,iBAAiB,CAAA;AAExB,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AACvE,OAAO,EACN,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,GACjB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACN,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,iBAAiB,EACjB,WAAW,GACX,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACxD,OAAO,EACN,mBAAmB,EACnB,uBAAuB,EACvB,eAAe,GACf,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growth-labs/mailer",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {

package/src/components/SubscribeForm.astro

@@ -30,6 +30,7 @@ const formId = `gl-subscribe-${Math.random().toString(36).slice(2, 8)}`;
 		method="POST"
 		action={config.subscribePath}
 		data-gl-subscribe-form
+		data-subscribe-path={config.subscribePath}
 	>
 		<div class="gl-subscribe-fields">
 			{showNameField && (
@@ -87,75 +88,87 @@ const formId = `gl-subscribe-${Math.random().toString(36).slice(2, 8)}`;
 	</form>
 </div>
 
-<script define:vars={{ subscribePath: config.subscribePath, formId }}>
-	;(function () {
-		const container = document.getElementById(formId)
-		if (!container) return
-
-		const form = container.querySelector('[data-gl-subscribe-form]')
-		const submitBtn = container.querySelector('[data-gl-submit]')
-		const messageEl = container.querySelector('[data-gl-message]')
-		const successEl = container.querySelector('[data-gl-success]')
-		const errorEl = container.querySelector('[data-gl-error]')
-
-		// Load Turnstile
+<script>
+	// Hoisted (bundled) module shared by every SubscribeForm on the page.
+	// Previously this used `define:vars`, which Astro cannot bundle, so the
+	// whole handler was re-emitted inline per form instance. Now it wires all
+	// forms from one cached script, reading per-form config from data-* attrs.
+	function initGlSubscribeForms() {
+		const forms = document.querySelectorAll<HTMLFormElement>(
+			"[data-gl-subscribe-form]",
+		);
+		if (forms.length === 0) return;
+
+		// Load Turnstile once per page (de-duped) when a subscribe form exists.
 		if (!document.querySelector('script[src*="turnstile"]')) {
-			const script = document.createElement('script')
-			script.src = 'https://challenges.cloudflare.com/turnstile/v0/api.js'
-			script.async = true
-			document.head.appendChild(script)
+			const turnstile = document.createElement("script");
+			turnstile.src = "https://challenges.cloudflare.com/turnstile/v0/api.js";
+			turnstile.async = true;
+			document.head.appendChild(turnstile);
 		}
 
-		form?.addEventListener('submit', async function (e) {
-			e.preventDefault()
-			if (!form || !submitBtn) return
-
-			submitBtn.setAttribute('disabled', 'true')
-			messageEl?.setAttribute('hidden', '')
-			successEl?.setAttribute('hidden', '')
-			errorEl?.setAttribute('hidden', '')
-
-			const formData = new FormData(form)
-			const preferences = formData.getAll('preferences')
-			const turnstileInput = form.querySelector(
-				'[name="cf-turnstile-response"]',
-			)
-			const turnstileToken = turnstileInput?.value ?? ''
-
-			try {
-				const res = await fetch(subscribePath, {
-					method: 'POST',
-					headers: { 'Content-Type': 'application/json' },
-					body: JSON.stringify({
-						email: formData.get('email'),
-						name: formData.get('name') || undefined,
-						source: formData.get('source'),
-						preferences: preferences.length ? preferences : undefined,
-						turnstileToken,
-					}),
-				})
-
-				const data = await res.json()
-
-				messageEl?.removeAttribute('hidden')
-				if (data.success) {
-					successEl?.removeAttribute('hidden')
-					form.reset()
-				} else {
+		for (const form of forms) {
+			if (form.dataset.glWired) continue;
+			form.dataset.glWired = "1";
+
+			const subscribePath = form.getAttribute("data-subscribe-path") || "";
+			const submitBtn = form.querySelector("[data-gl-submit]");
+			const messageEl = form.querySelector("[data-gl-message]");
+			const successEl = form.querySelector("[data-gl-success]");
+			const errorEl = form.querySelector("[data-gl-error]");
+
+			form.addEventListener("submit", async (e) => {
+				e.preventDefault();
+				if (!submitBtn) return;
+
+				submitBtn.setAttribute("disabled", "true");
+				messageEl?.setAttribute("hidden", "");
+				successEl?.setAttribute("hidden", "");
+				errorEl?.setAttribute("hidden", "");
+
+				const formData = new FormData(form);
+				const preferences = formData.getAll("preferences");
+				const turnstileInput = form.querySelector<HTMLInputElement>(
+					'[name="cf-turnstile-response"]',
+				);
+				const turnstileToken = turnstileInput?.value ?? "";
+
+				try {
+					const res = await fetch(subscribePath, {
+						method: "POST",
+						headers: { "Content-Type": "application/json" },
+						body: JSON.stringify({
+							email: formData.get("email"),
+							name: formData.get("name") || undefined,
+							source: formData.get("source"),
+							preferences: preferences.length ? preferences : undefined,
+							turnstileToken,
+						}),
+					});
+
+					const data = await res.json();
+
+					messageEl?.removeAttribute("hidden");
+					if (data.success) {
+						successEl?.removeAttribute("hidden");
+						form.reset();
+					} else if (errorEl) {
+						errorEl.textContent = data.error || "Something went wrong";
+						errorEl.removeAttribute("hidden");
+					}
+				} catch {
+					messageEl?.removeAttribute("hidden");
 					if (errorEl) {
-						errorEl.textContent = data.error || 'Something went wrong'
-						errorEl.removeAttribute('hidden')
+						errorEl.textContent = "Network error. Please try again.";
+						errorEl.removeAttribute("hidden");
 					}
+				} finally {
+					submitBtn.removeAttribute("disabled");
 				}
-			} catch {
-				messageEl?.removeAttribute('hidden')
-				if (errorEl) {
-					errorEl.textContent = 'Network error. Please try again.'
-					errorEl.removeAttribute('hidden')
-				}
-			} finally {
-				submitBtn.removeAttribute('disabled')
-			}
-		})
-	})()
+			});
+		}
+	}
+
+	initGlSubscribeForms();
+	document.addEventListener("astro:page-load", initGlSubscribeForms);
 </script>

package/src/index.ts

@@ -105,6 +105,12 @@ export type {
 	TemplateData,
 	TemplateName,
 } from './types.js'
+export type {
+	BroadcastRecipient,
+	SendBroadcastParams,
+	SendBroadcastResult,
+} from './utils/broadcast.js'
+export { sendBroadcast } from './utils/broadcast.js'
 export type { CampaignSchedule, DigestSchedule } from './utils/scheduling.js'
 export {
 	executeCampaignSchedule,

package/src/types.ts

@@ -39,7 +39,7 @@ export interface SubscriberFilter {
 
 export interface EmailQueueMessage {
 	siteId: string
-	type: 'transactional' | 'campaign' | 'digest'
+	type: 'transactional' | 'campaign' | 'digest' | 'broadcast'
 	recipients: QueueRecipient[]
 	subject: string
 	htmlTemplate: string
@@ -98,7 +98,7 @@ export interface EmailSend {
 	campaignId?: string
 	email: string
 	subject: string
-	type: 'transactional' | 'campaign' | 'digest'
+	type: 'transactional' | 'campaign' | 'digest' | 'broadcast'
 	status: EmailSendStatus
 	sentAt?: string
 	deliveredAt?: string

package/src/utils/broadcast.ts

@@ -0,0 +1,392 @@
+import { and, eq, inArray } from 'drizzle-orm'
+import { drizzle } from 'drizzle-orm/d1'
+import { ulid } from 'ulidx'
+import type { ResolvedMailerOptions } from '../options.js'
+import { emailSends } from '../schema/sends.js'
+import { subscribers } from '../schema/subscribers.js'
+import type { EmailQueueMessage, QueueRecipient, SubscriberStatus } from '../types.js'
+import { sleep } from './providers.js'
+import type { MailerEnv } from './send.js'
+import { generateToken } from './tokens.js'
+import { injectTrackingPixel, rewriteLinksForTracking } from './tracking.js'
+
+type DrizzleDB = ReturnType<typeof drizzle>
+
+/**
+ * Statuses that mean "do not send" — the suppression list. A broadcast skips
+ * every recipient whose `gl_subscribers` row carries one of these. `active` is
+ * the ONLY sendable status; everything else (including `pending`, i.e. an
+ * unconfirmed double-opt-in subscriber) is suppressed so a one-off blast can
+ * never re-permission or re-mail a suppressed address.
+ */
+const SUPPRESSED_STATUSES: ReadonlySet<SubscriberStatus> = new Set<SubscriberStatus>([
+	'unsubscribed',
+	'bounced',
+	'complained',
+	'pending',
+])
+
+// ─── Inputs ───
+
+/**
+ * One recipient of a broadcast. `subscriberId` is optional: when omitted the
+ * subscriber is resolved by `email` against `gl_subscribers` (needed both for
+ * suppression enforcement and for per-recipient unsubscribe/preferences links).
+ * An email with no matching subscriber row is treated as suppressed (we never
+ * blast an address we cannot honour an unsubscribe for).
+ */
+export interface BroadcastRecipient {
+	email: string
+	subscriberId?: string
+}
+
+export interface SendBroadcastParams {
+	/**
+	 * Explicit recipient list. Mutually-resolvable with `segmentName` +
+	 * `resolveRecipients`: segmentation itself is NOT built here (WS5 bead 06 is
+	 * identity-gated) — `sendBroadcast` takes the list, or a resolver callback
+	 * that turns a saved-segment name into the list, from elsewhere.
+	 */
+	recipients?: Array<BroadcastRecipient | string>
+	/**
+	 * Name of a saved segment to blast. Resolved to a recipient list by
+	 * `resolveRecipients` (provided by the caller / a later segmentation bead).
+	 */
+	segmentName?: string
+	/**
+	 * Resolves a saved-segment name to its recipient list. Supplied by the
+	 * caller; broadcast does not implement segmentation.
+	 */
+	resolveRecipients?: (segmentName: string) => Promise<Array<BroadcastRecipient | string>>
+
+	subject: string
+	html: string
+
+	/**
+	 * Idempotency key. A re-run with the same `campaignId` will NOT re-send to
+	 * any recipient that already has a `gl_email_sends` row for this campaign.
+	 * Auto-generated when omitted (a fresh, non-idempotent blast).
+	 */
+	campaignId?: string
+
+	/** When true, resolve + suppress + dedupe and return counts WITHOUT sending. */
+	dryRun?: boolean
+
+	/**
+	 * Max recipients packed into a single queue message. Bounds the message
+	 * payload well under Cloudflare's 128 KiB queue-message limit. Default 100.
+	 */
+	maxRecipientsPerMessage?: number
+
+	/**
+	 * Max queue messages to enqueue per second, to stay under Cloudflare send /
+	 * queue producer rate limits. `0` (default) disables pacing.
+	 */
+	messagesPerSecond?: number
+}
+
+export interface SendBroadcastResult {
+	campaignId: string
+	/** Recipients actually queued (dry-run: would-be-queued). */
+	recipientCount: number
+	/** Recipients skipped because their subscriber row is on the suppression list. */
+	suppressedCount: number
+	/** Recipients skipped because a `gl_email_sends` row already existed (idempotency). */
+	alreadySentCount: number
+	/** Number of queue messages enqueued (0 on dry-run). */
+	batchCount: number
+	dryRun: boolean
+}
+
+interface ResolvedProducerBindings {
+	db: DrizzleDB
+	queue: Queue
+}
+
+function resolveProducerBindings(
+	env: MailerEnv,
+	options: ResolvedMailerOptions,
+): ResolvedProducerBindings {
+	const d1 = env[options.d1Binding] as D1Database | undefined
+	if (!d1) {
+		throw new Error(
+			`[mailer] env.${options.d1Binding} is undefined; ` +
+				'pass d1Binding option to the mailer integration or bind that name in wrangler.toml.',
+		)
+	}
+	const queue = env[options.queueBinding] as Queue | undefined
+	if (!queue) {
+		throw new Error(
+			`[mailer] env.${options.queueBinding} is undefined; ` +
+				'pass queueBinding option to the mailer integration or bind that name in wrangler.toml.',
+		)
+	}
+	return { db: drizzle(d1), queue }
+}
+
+function normalizeRecipient(r: BroadcastRecipient | string): BroadcastRecipient {
+	return typeof r === 'string' ? { email: r } : r
+}
+
+/** A recipient resolved against `gl_subscribers`: sendable, with its id + status. */
+interface ResolvedRecipient {
+	email: string
+	subscriberId: string
+	status: SubscriberStatus
+}
+
+/**
+ * Resolve each requested recipient against `gl_subscribers`:
+ *   - dedupe by email (a list may repeat an address)
+ *   - attach the canonical subscriberId + status
+ *   - drop emails with no subscriber row (cannot honour unsubscribe → suppress)
+ * Returns the resolved sendable-candidate set plus the suppressed count.
+ */
+async function resolveAgainstSubscribers(
+	db: DrizzleDB,
+	requested: BroadcastRecipient[],
+): Promise<{ candidates: ResolvedRecipient[]; suppressedCount: number }> {
+	// Dedupe requested emails (case-insensitive, trimmed) preserving first-seen order.
+	const byEmail = new Map<string, BroadcastRecipient>()
+	for (const r of requested) {
+		const key = r.email.trim().toLowerCase()
+		if (key.length === 0) continue
+		if (!byEmail.has(key)) byEmail.set(key, { ...r, email: r.email.trim() })
+	}
+
+	const emails = [...byEmail.values()].map((r) => r.email)
+	if (emails.length === 0) return { candidates: [], suppressedCount: 0 }
+
+	// Look up subscriber rows for all requested emails.
+	const rows = await db
+		.select({
+			id: subscribers.id,
+			email: subscribers.email,
+			status: subscribers.status,
+		})
+		.from(subscribers)
+		.where(inArray(subscribers.email, emails))
+
+	const rowByEmail = new Map<string, { id: string; status: SubscriberStatus }>()
+	for (const row of rows) {
+		rowByEmail.set((row.email as string).toLowerCase(), {
+			id: row.id as string,
+			status: row.status as SubscriberStatus,
+		})
+	}
+
+	const candidates: ResolvedRecipient[] = []
+	let suppressedCount = 0
+	for (const r of byEmail.values()) {
+		const row = rowByEmail.get(r.email.toLowerCase())
+		// No subscriber row, or a suppressed status → skip. Never send to an
+		// address we cannot honour an unsubscribe for, and never to a
+		// bounced/complained/unsubscribed/pending one.
+		if (!row || SUPPRESSED_STATUSES.has(row.status)) {
+			suppressedCount++
+			continue
+		}
+		candidates.push({ email: r.email, subscriberId: r.subscriberId ?? row.id, status: row.status })
+	}
+
+	return { candidates, suppressedCount }
+}
+
+/**
+ * Of the suppression-cleared candidates, drop any that already have a
+ * `gl_email_sends` row for this campaignId — the idempotency guard that makes a
+ * re-run a no-op for already-processed recipients.
+ */
+async function filterAlreadySent(
+	db: DrizzleDB,
+	campaignId: string,
+	candidates: ResolvedRecipient[],
+): Promise<{ fresh: ResolvedRecipient[]; alreadySentCount: number }> {
+	if (candidates.length === 0) return { fresh: [], alreadySentCount: 0 }
+
+	const candidateEmails = candidates.map((c) => c.email)
+	const existing = await db
+		.select({ email: emailSends.email })
+		.from(emailSends)
+		.where(and(eq(emailSends.campaignId, campaignId), inArray(emailSends.email, candidateEmails)))
+
+	const sentEmails = new Set(existing.map((row) => (row.email as string).toLowerCase()))
+
+	const fresh: ResolvedRecipient[] = []
+	let alreadySentCount = 0
+	for (const c of candidates) {
+		if (sentEmails.has(c.email.toLowerCase())) {
+			alreadySentCount++
+			continue
+		}
+		fresh.push(c)
+	}
+
+	return { fresh, alreadySentCount }
+}
+
+/**
+ * Build the broadcast HTML with the tracking pixel + click-rewrite applied
+ * once (the per-recipient {{TRACKING_ID}} is substituted in the consumer).
+ */
+function prepareBroadcastHtml(html: string, options: ResolvedMailerOptions): string {
+	const trackOpenUrl = `${options.siteUrl}${options.trackOpenPath}`
+	const trackClickUrl = `${options.siteUrl}${options.trackClickPath}`
+	return rewriteLinksForTracking(injectTrackingPixel(html, trackOpenUrl), trackClickUrl)
+}
+
+function chunk<T>(items: T[], size: number): T[][] {
+	const out: T[][] = []
+	for (let i = 0; i < items.length; i += size) {
+		out.push(items.slice(i, i + size))
+	}
+	return out
+}
+
+/**
+ * Send a one-off broadcast blast (Customer.io one-off-blast parity).
+ *
+ * - Takes an explicit recipient list, or a saved-segment name resolved via
+ *   `resolveRecipients` (segmentation is NOT built here — WS5 bead 06).
+ * - Enforces the suppression list: only `active` subscribers are sent;
+ *   unsubscribed / bounced / complained / pending / unknown addresses skip.
+ * - Idempotent on `campaignId`: a re-run never double-sends to a recipient that
+ *   already has a `gl_email_sends` row for the campaign.
+ * - Writes a per-recipient `gl_email_sends` row (`type='broadcast'`, status
+ *   `queued`) before enqueueing.
+ * - Fans out in batches sized for Cloudflare queue/send-rate limits, with
+ *   optional `messagesPerSecond` pacing.
+ * - `dryRun` resolves + suppresses + dedupes and returns the recipient count
+ *   WITHOUT writing rows or enqueueing anything.
+ */
+export async function sendBroadcast(
+	env: MailerEnv,
+	options: ResolvedMailerOptions,
+	params: SendBroadcastParams,
+): Promise<SendBroadcastResult> {
+	const campaignId = params.campaignId ?? ulid()
+	const dryRun = params.dryRun ?? false
+	const maxRecipientsPerMessage = Math.max(
+		1,
+		Math.min(params.maxRecipientsPerMessage ?? options.batchSize, 500),
+	)
+	const messagesPerSecond = params.messagesPerSecond ?? 0
+
+	const { db, queue } = resolveProducerBindings(env, options)
+
+	// 1. Resolve the recipient list — explicit list and/or a resolved segment.
+	const requestedRaw: Array<BroadcastRecipient | string> = [...(params.recipients ?? [])]
+	if (params.segmentName) {
+		if (!params.resolveRecipients) {
+			throw new Error(
+				'[mailer] sendBroadcast: segmentName given without resolveRecipients; ' +
+					'segmentation is resolved by the caller (WS5 bead 06), not by the mailer.',
+			)
+		}
+		const resolved = await params.resolveRecipients(params.segmentName)
+		requestedRaw.push(...resolved)
+	}
+	if (requestedRaw.length === 0) {
+		throw new Error('[mailer] sendBroadcast: no recipients or segmentName provided')
+	}
+	const requested = requestedRaw.map(normalizeRecipient)
+
+	// 2. Suppression enforcement + dedupe.
+	const { candidates, suppressedCount } = await resolveAgainstSubscribers(db, requested)
+
+	// 3. Idempotency — drop recipients already recorded for this campaign.
+	const { fresh, alreadySentCount } = await filterAlreadySent(db, campaignId, candidates)
+
+	// Dry-run: report the counts and stop before any write or enqueue.
+	if (dryRun) {
+		return {
+			campaignId,
+			recipientCount: fresh.length,
+			suppressedCount,
+			alreadySentCount,
+			batchCount: 0,
+			dryRun: true,
+		}
+	}
+
+	if (fresh.length === 0) {
+		return {
+			campaignId,
+			recipientCount: 0,
+			suppressedCount,
+			alreadySentCount,
+			batchCount: 0,
+			dryRun: false,
+		}
+	}
+
+	const html = prepareBroadcastHtml(params.html, options)
+	const now = new Date().toISOString()
+
+	// 4. Per-recipient row write + queue-recipient build.
+	const queueRecipients: QueueRecipient[] = []
+	for (const recipient of fresh) {
+		const trackingId = ulid()
+		const [unsubscribeToken, preferencesToken] = await Promise.all([
+			generateToken(options.signingSecret, {
+				subscriberId: recipient.subscriberId,
+				action: 'unsubscribe',
+			}),
+			generateToken(options.signingSecret, {
+				subscriberId: recipient.subscriberId,
+				action: 'preferences',
+			}),
+		])
+
+		await db.insert(emailSends).values({
+			id: ulid(),
+			subscriberId: recipient.subscriberId,
+			campaignId,
+			email: recipient.email,
+			subject: params.subject,
+			type: 'broadcast',
+			status: 'queued',
+			trackingId,
+			createdAt: now,
+		})
+
+		queueRecipients.push({
+			email: recipient.email,
+			subscriberId: recipient.subscriberId,
+			trackingId,
+			unsubscribeToken,
+			preferencesToken,
+		})
+	}
+
+	// 5. Batched fan-out, paced to the configured send rate.
+	const batches = chunk(queueRecipients, maxRecipientsPerMessage)
+	const intervalMs = messagesPerSecond > 0 ? Math.ceil(1000 / messagesPerSecond) : 0
+
+	for (let i = 0; i < batches.length; i++) {
+		const message: EmailQueueMessage = {
+			siteId: options.siteId,
+			type: 'broadcast',
+			recipients: batches[i],
+			subject: params.subject,
+			htmlTemplate: html,
+			from: `${options.senderName} <${options.fromAddress}>`,
+			replyTo: options.replyTo,
+			campaignId,
+		}
+		await queue.send(message)
+
+		if (intervalMs > 0 && i < batches.length - 1) {
+			await sleep(intervalMs)
+		}
+	}
+
+	return {
+		campaignId,
+		recipientCount: fresh.length,
+		suppressedCount,
+		alreadySentCount,
+		batchCount: batches.length,
+		dryRun: false,
+	}
+}

package/src/utils/index.ts

@@ -9,6 +9,12 @@ export {
 	handleDelivery,
 	updateSendStatus,
 } from './bounce.js'
+export type {
+	BroadcastRecipient,
+	SendBroadcastParams,
+	SendBroadcastResult,
+} from './broadcast.js'
+export { sendBroadcast } from './broadcast.js'
 export type { CloudflareEmailSender } from './providers.js'
 export { CloudflareEmailProvider, getProvider, sleep } from './providers.js'
 export type { CampaignSchedule, DigestSchedule } from './scheduling.js'