@aglyn/plugins-marketing 1.0.0-beta.199 → 1.0.0-beta.201

package/src/lib/server/campaign-send.js

@@ -14,18 +14,23 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
- */ import { checkQuota, contactMatchesSegment, isEmailTopicId, DEFAULT_CAMPAIGN_TOPIC_ID, readMarketingBasis, resolveMarketingConsentPolicy, splitByMarketingConsent, createResourceUid, decodeStoredNodes, emailStarterSendBlock, resolveBrandingProfile, visibleToHost } from "@aglyn/aglyn/server";
+ */ import { checkQuota, contactMatchesSegment, isEmailTopicId, DEFAULT_CAMPAIGN_TOPIC_ID, readMarketingBasis, resolveMarketingConsentPolicy, splitByMarketingConsent, createResourceUid, decodeStoredNodes, emailStarterSendBlock, resolveBrandingProfile, siteLockdownFromDocs, visibleToHost } from "@aglyn/aglyn/server";
 import { renderRecipientEmail } from "@aglyn/aglyn/app-utils/recipient-email-render";
 import { composeHostComponentNodes } from "@aglyn/aglyn/app-utils/load-referenced-components";
 import { assignExperimentVariant } from "../model/index.js";
-import { campaignPlacedOnHost } from "@aglyn/shared-ui-email-campaigns/model";
+import { campaignHeldForReviewNotice, campaignPlacedOnHost, campaignSendHeldForReview } from "@aglyn/shared-ui-email-campaigns/model";
 import { readPluginRecordCard } from "@aglyn/aglyn/plugin-manager/plugin-record-cards";
 import { hostPublicOrigin } from "@aglyn/aglyn/server";
-import { consentGroupForSite, orgDataCollectionForHost, orgDataQueryForHost, filterSendableForHost, filterTopicSendable, firebaseAdmin, getOrgForHost, meterHostEmail, claimOrgEmailSendBudget, orgCampaignEmailSendsForMonth, readEmailSendRateConfig, readEmailSendRateWindow, reconcileCampaignSendReservation, reserveCampaignEmailSends, resolveHostSendingIdentity } from "@aglyn/tenant-data-admin";
+import { consentGroupForSite, orgDataCollectionForHost, orgDataQueryForHost, filterDeliverableRecipients, filterSendableForHost, filterTopicSendable, firebaseAdmin, getOrgForHost, meterHostEmail, claimOrgEmailSendBudget, orgCampaignEmailSendsForMonth, readEmailSendRateConfig, readEmailSendRateWindow, reconcileCampaignSendReservation, reserveCampaignEmailSends, resolveHostSendingIdentity } from "@aglyn/tenant-data-admin";
 // The leaf, not the barrel: this plugin's specs substitute the barrel
 // wholesale, and the lookup must reach the real index logic under them.
 import { findContactByEmail } from "@aglyn/tenant-data-admin/server/contact-email-index";
 import { isDocumentId } from "@aglyn/tenant-data-admin/server/document-id";
+/*
+ * The LEAF for the phishing screen's hold (AGL-3356), for the reason every
+ * leaf above gives: the specs that reach this file mock the barrel, and a
+ * control that holds a send must be the real one under every harness.
+ */ import { canonicalJson, HELD_SEND_AT_MS, screenOutboundSend } from "@aglyn/tenant-data-admin/server/outbound-send-review";
 /*
  * The LEAF module for the impersonation exemption too, and for a sharper
  * version of the reason the notes below give: every spec that reaches this
@@ -51,6 +56,7 @@ import { filterCadenceSendable, recordMarketingSends } from "@aglyn/tenant-data-
  * from the real module.
  */ import { CAMPAIGN_REACH_CEILING, campaignReachCovers, campaignSettledSize, partitionByCampaignReach, readCampaignReach, readCampaignSettled, recordCampaignReach, recordCampaignSkipped } from "./email-campaign-reach.js";
 import { campaignSendSiteStamp, orgCampaignSends, orgEmailCampaigns, sendIsOnHost } from "./campaign-org-refs.js";
+import { campaignSendSearchFields } from "../model/campaign-list-query.js";
 /*
  * The LEAF module for the reputation controls too, and for the same reason
  * as the three above it: every spec that reaches this file mocks the
@@ -189,10 +195,33 @@ const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  * Thrown ONLY before anything has been sent, so a caller that retries cannot
  * double-send.
  */ export class CampaignSendDeferredError extends CampaignSendError {
-    constructor(message, /** When the hourly window rolls. */ retryAtMs){
-        super(message, 429), this.retryAtMs = retryAtMs;
+    constructor(message, /** When the hourly window rolls. */ retryAtMs, /**
+     * `429` for a rate, `423` for a suspension (AGL-3356). The subclass is
+     * what a caller acts on; the number is only what the API answers.
+     */ status = 429){
+        super(message, status), this.retryAtMs = retryAtMs;
     }
 }
+/**
+ * The phishing screen held this send for staff review (AGL-3356).
+ *
+ * A DEFERRAL to every caller that handles one, which is the point: the
+ * scheduled processor puts the row back to `scheduled` at the parked time
+ * rather than marking it failed, and the send route's claim is released —
+ * so a held email is neither lost nor mailed. `409` because the merchant's
+ * request conflicts with a review in progress, and the message says so in
+ * words they can act on.
+ */ export class CampaignSendHeldError extends CampaignSendDeferredError {
+    constructor(reference){
+        super('This email is being reviewed before it sends, because new workspaces ' + 'have their first emails checked for impersonation. It has been saved ' + 'and nothing has been sent or counted; it goes out automatically if ' + `it is approved. Reference ${reference}.`, HELD_SEND_AT_MS, 409), this.reference = reference;
+    }
+}
+/**
+ * How long a suspended site's scheduled campaign waits before it is asked
+ * about again (AGL-3356). An hour keeps a locked workspace's due sends from
+ * crowding the processor's read on every fifteen-minute beat, and is short
+ * enough that a lifted suspension resumes the same afternoon.
+ */ export const CAMPAIGN_SUSPENDED_RETRY_MS = 60 * 60 * 1000;
 /**
  * Loads a designed email template's nodes + referenced products for the
  * render pipeline. Throws 400 when the screen isn't an email document.
@@ -327,6 +356,31 @@ const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  * (AGL-3307) — see {@link CampaignListUnsubscribeRecord} in
  * `@aglyn/shared-ui-email-campaigns`, which the campaign page reads.
  */ const LIST_UNSUBSCRIBE_RECORD_FIELD = 'listUnsubscribe';
+/**
+ * The deliverability check over one batch (AGL-3328), against the domain the
+ * campaign leaves from. Fails OPEN — an unreadable check, or one this
+ * deployment did not install, keeps everyone — because the check prevents
+ * bounces and a campaign that stopped for want of it would prevent mail.
+ */ async function checkCampaignDeliverability(emails, identity) {
+    var _ref, _ref1, _ref2;
+    var _String_match;
+    const fromAddress = (_ref = (_String_match = String((_ref1 = identity == null ? void 0 : identity.from) != null ? _ref1 : '').match(/<([^>]+)>/)) == null ? void 0 : _String_match[1]) != null ? _ref : String((_ref2 = identity == null ? void 0 : identity.from) != null ? _ref2 : '');
+    const sendingDomain = (identity == null ? void 0 : identity.domain) || (fromAddress.includes('@') ? fromAddress.slice(fromAddress.lastIndexOf('@') + 1).trim() : null);
+    try {
+        return await filterDeliverableRecipients({
+            emails,
+            sendingDomain,
+            purpose: 'bulk'
+        });
+    } catch (error) {
+        console.error('[campaign] deliverability check unavailable — sending to everyone', error);
+        return {
+            deliverable: emails,
+            noMailServer: [],
+            gatewayHeld: []
+        };
+    }
+}
 export async function performCampaignSend(options) {
     var _ref, _options_senderId, _options_proofFor, _hostPublicOrigin, _options_experimentId;
     var _orgForHost_org, _orgForHost_org1, _consent_get;
@@ -428,6 +482,31 @@ export async function performCampaignSend(options) {
     if (!orgId) {
         throw new CampaignSendError('This site is not part of an organization, so it cannot send campaigns.', 409);
     }
+    /*
+   * A SUSPENDED SITE SENDS NO CAMPAIGN (AGL-3356).
+   *
+   * The console dispatcher refuses a locked caller, but the scheduled
+   * processor and a resumed batch arrive with no caller at all, so the
+   * suspension is asked here, off the two documents this send already holds
+   * — no read is added. The incident behind this was a workspace locked for
+   * phishing whose deferred batches were still queued to go.
+   *
+   * A deferral rather than a failure: a suspension is a pause, and lifting
+   * it must leave the campaign where it was. Thrown before anything is
+   * claimed, counted or sent, so the scheduled processor puts the row back
+   * to `scheduled` and asks again after the delay. Any active lock pauses a
+   * campaign, a read-only maintenance window included, because a campaign is
+   * the one sender that can always wait.
+   */ {
+        const nowMs = Date.now();
+        const lock = siteLockdownFromDocs({
+            org: orgForHost == null ? void 0 : orgForHost.org,
+            host: hostSnapshot.data()
+        }, nowMs);
+        if (lock) {
+            throw new CampaignSendDeferredError(lock.scope === 'org' ? 'This workspace is suspended, so its email is paused. Nothing ' + 'has been sent or counted; it resumes when the suspension is lifted.' : 'This site is suspended, so its email is paused. Nothing has ' + 'been sent or counted; it resumes when the suspension is lifted.', nowMs + CAMPAIGN_SUSPENDED_RETRY_MS, 423);
+        }
+    }
     const sends = orgCampaignSends(firestore, orgId);
     /*==========================================
    * THE FOLLOW-UP'S ADMISSION CHECKS.
@@ -1132,11 +1211,26 @@ export async function performCampaignSend(options) {
    * Fails OPEN on an unreadable counter — see `filterCadenceSendable`. A
    * pace is not a stop, and the two suppression lists above have already
    * removed everybody who asked us to stop entirely.
-   */ const sendable = await filterCadenceSendable(hostId, onTopic, {
+   */ const paced = await filterCadenceSendable(hostId, onTopic, {
         firestore,
         group: consentGroup
     });
     /*
+   * THE FIFTH FILTER: who this send would bounce off (AGL-3328).
+   *
+   * An address whose domain has no mail server is a hard bounce charged to
+   * the sending domain, and an address behind a gateway that refused this
+   * sending domain twice in thirty days is the third refusal in a row —
+   * each one making the next more likely, at that company and at every
+   * other behind the same gateway. `sendEmail` refuses both one message at
+   * a time as well; subtracting them HERE is what makes the count on screen
+   * true before Send, the reason the cadence filter above sits here too.
+   *
+   * Fails OPEN: an audience that could not be checked is mailed as it was
+   * before the check existed.
+   */ const deliverability = await checkCampaignDeliverability(paced, sendingIdentity);
+    const sendable = deliverability.deliverable;
+    /*
    * NOBODY IN THIS BATCH, BUT SOMEBODY AFTER IT.
    *
    * A send whose whole audience is suppressed is a 400 a merchant needs to
@@ -1150,12 +1244,13 @@ export async function performCampaignSend(options) {
    */ if (!sendable.length && consentSplit.mailable.length <= recipients.length) {
         if (options.continuation) return finishContinuation();
         /*
-     * Which of the four filters emptied the batch, because the answer changes
+     * Which of the five filters emptied the batch, because the answer changes
      * what the merchant should do. An audience that unsubscribed is one they
      * have to rebuild; an audience holding for its own cadence is one that
      * becomes mailable on its own, and telling them it "unsubscribed" would
-     * send them looking for a problem that is not there.
-     */ throw new CampaignSendError(onTopic.length ? 'Every recipient has asked this site for mail less often than this' : 'Every recipient has unsubscribed or been suppressed', 400);
+     * send them looking for a problem that is not there. An audience the
+     * deliverability check emptied has addresses that would bounce.
+     */ throw new CampaignSendError(paced.length ? 'Every recipient would bounce: their domains have no mail server, ' + 'or their mail gateway refused this sender twice this month' : onTopic.length ? 'Every recipient has asked this site for mail less often than this' : 'Every recipient has unsubscribed or been suppressed', 400);
     }
     // Monthly cap by the owning org's plan (dark-launch rule, AGL-238).
     //
@@ -1235,7 +1330,12 @@ export async function performCampaignSend(options) {
        * not unsubscribe, and reporting them under a heading that says they
        * did is the netting this readout has refused everywhere else.
        */ suppressed: recipients.length - onTopic.length,
-            cadenceHeld: onTopic.length - sendable.length,
+            cadenceHeld: onTopic.length - paced.length,
+            // Who the deliverability check took out, by why (AGL-3328): "N
+            // recipients excluded: no mail server · M behind a gateway that
+            // refused this sender".
+            noMailServer: deliverability.noMailServer.length,
+            gatewayHeld: deliverability.gatewayHeld.length,
             /*
        * What this send will NOT reach on its first pass, so the composer can
        * say "3,000 people, 500 in the first batch, the rest over the next few
@@ -1298,7 +1398,7 @@ export async function performCampaignSend(options) {
    * that record already carries its own creation stamp. Re-stamping it would
    * move an email's creation date forward every time it was sent again, and
    * the emails list orders drafts on exactly that field.
-   */ const mintsRecord = !options.campaignId;
+   */ const mintsRecord = !options.campaignId || options.mintsRecord === true;
     // Designed email template (AGL-349): loaded once; rendered per
     // recipient with their merge values.
     const template = options.templateScreenId ? await loadEmailTemplate(hostId, options.templateScreenId) : null;
@@ -1332,6 +1432,107 @@ export async function performCampaignSend(options) {
         }, data);
     }
     /*
+   * THE PHISHING SCREEN, for a workspace in its first fortnight (AGL-3356).
+   *
+   * Asked once the copy is final — the design loaded, the experiment's
+   * variants known — and before anything is claimed, counted or sent, so a
+   * hold costs the workspace nothing but the wait. See
+   * `outbound-send-review.ts` for who is screened and what a hold is, and
+   * `outbound-phishing-screen.ts` for what holds.
+   *
+   * A follow-up is not screened: it mails the copy its first send already
+   * carried, which was. A continuation is: its first batch may predate the
+   * screen, and a hold there parks the rest of the audience rather than
+   * mailing it.
+   *
+   * A HOLD PARKS THE SEND, it does not drop it. The record is written as a
+   * scheduled send whose time no processor run reaches, carrying the copy
+   * `storedSendOptionsFrom` reads back, and the review row in the abuse
+   * queue names it. Staff dismissing the row releases it — the send goes
+   * back on the clock and this screen finds it released — and actioning the
+   * row cancels it.
+   */ if (!options.followUp) {
+        var _ref4, _hostSnapshot_data, _options_fromName, _sendingIdentity_from, _options_replyTo, _options_preheader, _options_plainText, _experiment_variants;
+        const sendRef = sends.doc(campaignId);
+        const screened = await screenOutboundSend({
+            kind: 'campaign',
+            path: sendRef.path,
+            hostId,
+            orgId,
+            org: (_ref4 = orgForHost == null ? void 0 : orgForHost.org) != null ? _ref4 : null,
+            host: (_hostSnapshot_data = hostSnapshot.data()) != null ? _hostSnapshot_data : null,
+            subject,
+            fromName: (_options_fromName = options.fromName) != null ? _options_fromName : null,
+            // The verified address it will leave on: a lookalike domain there
+            // holds for every workspace (AGL-3362).
+            fromAddress: (_sendingIdentity_from = sendingIdentity.from) != null ? _sendingIdentity_from : null,
+            replyTo: (_options_replyTo = options.replyTo) != null ? _options_replyTo : null,
+            preheader: (_options_preheader = options.preheader) != null ? _options_preheader : null,
+            bodies: [
+                body,
+                (_options_plainText = options.plainText) != null ? _options_plainText : '',
+                template ? canonicalJson(template) : '',
+                experiment ? canonicalJson((_experiment_variants = experiment.variants) != null ? _experiment_variants : null) : ''
+            ]
+        });
+        if (screened.outcome === 'rejected') {
+            throw new CampaignSendError('This email was reviewed and will not be sent. Contact support if ' + 'you believe this is a mistake.', 403);
+        }
+        if (screened.outcome === 'held') {
+            var _options_emails;
+            await sendRef.set(_extends({}, campaignSendSiteStamp(hostId), options.continuation ? {} : _extends({
+                subject
+            }, campaignSendSearchFields(subject), {
+                body,
+                audience
+            }, mintsRecord ? {
+                createdAtMs: Date.now()
+            } : {}, options.segmentId ? {
+                segmentId: options.segmentId
+            } : {}, options.listId ? {
+                listId: options.listId
+            } : {}, options.topicId ? {
+                topicId: options.topicId
+            } : {}, ((_options_emails = options.emails) == null ? void 0 : _options_emails.length) ? {
+                emails: options.emails.map(String).slice(0, 500)
+            } : {}, experimentId ? {
+                experimentId
+            } : {}, options.templateScreenId ? {
+                templateScreenId: options.templateScreenId
+            } : {}, options.plainText ? {
+                plainText: options.plainText
+            } : {}, options.fromName ? {
+                fromName: options.fromName
+            } : {}, options.replyTo ? {
+                replyTo: options.replyTo
+            } : {}, options.senderId ? {
+                senderId: options.senderId
+            } : {}, options.preheader ? {
+                preheader: options.preheader
+            } : {}, options.displayName ? {
+                displayName: options.displayName
+            } : {}, options.emailCampaignId ? {
+                emailCampaignId: options.emailCampaignId
+            } : mintsRecord ? {
+                emailCampaignId: null
+            } : {}, {
+                scheduledBy: options.senderUid
+            }), {
+                status: 'scheduled',
+                sendAtMs: HELD_SEND_AT_MS,
+                staffReview: {
+                    reviewId: screened.reviewId,
+                    reference: screened.reference,
+                    state: 'held',
+                    heldAtMs: Date.now()
+                }
+            }), {
+                merge: true
+            });
+            throw new CampaignSendHeldError(screened.reference);
+        }
+    }
+    /*
    * PLATFORM SEND-RATE ADMISSION CONTROL (AGL-2409).
    *
    * `sendEmail` governs every message individually and is the hard ceiling.
@@ -1956,7 +2157,8 @@ export async function performCampaignSend(options) {
    * below are stored under: they are true of the send that happened.
    */ const measuresTheAudience = !options.continuation;
     await sends.doc(campaignId).set(_extends({}, campaignSendSiteStamp(hostId), {
-        subject,
+        subject
+    }, campaignSendSearchFields(subject), {
         body,
         audience
     }, mintsRecord ? {
@@ -1993,6 +2195,8 @@ export async function performCampaignSend(options) {
         displayName: options.displayName
     } : {}, options.emailCampaignId ? {
         emailCampaignId: options.emailCampaignId
+    } : mintsRecord ? {
+        emailCampaignId: null
     } : {}, {
         /*
        * WHAT THIS EMAIL DID WITH THE UNSUBSCRIBE HEADER, and why (AGL-3307).
@@ -2035,7 +2239,9 @@ export async function performCampaignSend(options) {
             consentWithheld: additive(consentSplit.withheld)
         } : {}, {
             suppressed: additive(recipients.length - onTopic.length),
-            cadenceHeld: additive(onTopic.length - sendable.length),
+            cadenceHeld: additive(onTopic.length - paced.length),
+            noMailServer: additive(deliverability.noMailServer.length),
+            gatewayHeld: additive(deliverability.gatewayHeld.length),
             /*
          * That this send's links were trackable at all.
          *
@@ -3036,6 +3242,17 @@ function storedSendOptionsFrom(snapshot, hostId, senderUid, followUp) {
        * see the write below — which is console-only text that reached no
        * recipient and therefore contradicts no delivered mail.
        *=========================================*/ const rewritable = !targetSnapshot.exists || targetState === 'draft' || targetState === 'scheduled';
+            /*
+       * A SEND HELD FOR STAFF REVIEW IS NOT THE MERCHANT'S TO REWRITE
+       * (AGL-3356). Scheduling it would move `sendAtMs` off the parked time
+       * and put it on the clock without a decision, and a rewrite of its
+       * copy would reach staff as content they never reviewed. The name is
+       * still theirs (`update`), and so is canceling it.
+       */ if (action !== 'update' && campaignSendHeldForReview(targetSnapshot.data())) {
+                return res.status(409).json({
+                    error: campaignHeldForReviewNotice(targetSnapshot.data())
+                });
+            }
             if (action !== 'update' && !rewritable) {
                 return res.status(409).json({
                     error: targetState === 'sent' ? 'This email has already been sent, so its message and ' + 'audience can no longer be changed. Compose a new email.' : 'This email was canceled, so it can no longer be scheduled. ' + 'Compose a new email.'
@@ -3064,7 +3281,8 @@ function storedSendOptionsFrom(snapshot, hostId, senderUid, followUp) {
                 });
             }
             await targetRef.set(_extends({}, campaignSendSiteStamp(hostId), {
-                subject,
+                subject
+            }, campaignSendSearchFields(subject), {
                 body,
                 audience
             }, targetSnapshot.exists ? {} : {
@@ -3113,7 +3331,9 @@ function storedSendOptionsFrom(snapshot, hostId, senderUid, followUp) {
                 displayName
             } : {}, emailCampaignId ? {
                 emailCampaignId
-            } : {}, scheduling ? {
+            } : targetSnapshot.exists ? {} : {
+                emailCampaignId: null
+            }, scheduling ? {
                 status: 'scheduled',
                 sendAtMs,
                 scheduledAt: firebaseAdmin.firestore.FieldValue.serverTimestamp(),
@@ -3203,6 +3423,12 @@ function storedSendOptionsFrom(snapshot, hostId, senderUid, followUp) {
                 });
             }
             const sendNowState = String((_sendNowSnapshot_get = sendNowSnapshot.get('status')) != null ? _sendNowSnapshot_get : '');
+            // Held for staff review (AGL-3356): "send now" is not a release.
+            if (campaignSendHeldForReview(sendNowSnapshot.data())) {
+                return res.status(409).json({
+                    error: campaignHeldForReviewNotice(sendNowSnapshot.data())
+                });
+            }
             /*
        * Only an email that has not gone out yet. A sent one would be mailed a
        * second time to the whole audience under the same id — which is what
@@ -3305,6 +3531,7 @@ function storedSendOptionsFrom(snapshot, hostId, senderUid, followUp) {
      * which takes no copy from the request at all and subtracts everyone the
      * earlier sends recorded.
      *=========================================*/ const sendId = String((_ref12 = (_req_body15 = req.body) == null ? void 0 : _req_body15.campaignId) != null ? _ref12 : '');
+        /** The id names no record yet, so this send mints it (AGL-3321). */ let mintsNamedRecord = false;
         if (sendId) {
             var _existing_get;
             if (!isDocumentId(sendId)) {
@@ -3313,6 +3540,7 @@ function storedSendOptionsFrom(snapshot, hostId, senderUid, followUp) {
                 });
             }
             const existing = await orgSends.doc(sendId).get();
+            mintsNamedRecord = !existing.exists;
             if (existing.exists && !sendIsOnHost(existing, hostId)) {
                 return res.status(404).json({
                     error: 'Unknown email'
@@ -3334,7 +3562,10 @@ function storedSendOptionsFrom(snapshot, hostId, senderUid, followUp) {
             listId: String((_ref14 = (_req_body17 = req.body) == null ? void 0 : _req_body17.listId) != null ? _ref14 : ''),
             topicId: topicId || undefined,
             emails: Array.isArray((_req_body18 = req.body) == null ? void 0 : _req_body18.emails) ? req.body.emails : undefined,
-            campaignId: sendId,
+            campaignId: sendId
+        }, mintsNamedRecord ? {
+            mintsRecord: true
+        } : {}, {
             experimentId: String((_ref15 = (_req_body19 = req.body) == null ? void 0 : _req_body19.experimentId) != null ? _ref15 : ''),
             templateScreenId: templateScreenId || undefined
         }, plainText ? {