@aglyn/plugins-marketing 1.0.0-beta.278 → 1.0.0-beta.283

package/src/lib/server/campaign-send.d.ts

@@ -14,6 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { type CampaignPlanLock } from '../model/campaign-plan-lock';
 import { type PluginApiHandler } from '@aglyn/aglyn/server';
 import { type SendingIdentitySource } from '@aglyn/shared-util-email';
 import { type ListUnsubscribeDecision } from '@aglyn/shared-util-email/list-unsubscribe';
@@ -28,10 +29,19 @@ import { type ListUnsubscribeDecision } from '@aglyn/shared-util-email/list-unsu
 export declare function suppressionId(email: string): string;
 /** HMAC for unsubscribe links; env-gated on the shared secret. */
 export declare function unsubscribeSignature(hostId: string, email: string, secret: string, campaignId?: string, topicId?: string): string;
-/** Send failures carry the HTTP status the API route should answer. */
+/**
+ * Send failures carry the HTTP status the API route should answer, and a
+ * machine `reason` when the console answers that refusal with something
+ * other than the sentence (the plan cap's Upgrade button).
+ */
 export declare class CampaignSendError extends Error {
     readonly status: number;
-    constructor(message: string, status: number);
+    readonly reason?: string;
+    /** The plan lock behind a plan-cap refusal, for a client to draw. */
+    readonly planLock?: CampaignPlanLock | null;
+    constructor(message: string, status: number, reason?: string, 
+    /** The plan lock behind a plan-cap refusal, for a client to draw. */
+    planLock?: CampaignPlanLock | null);
 }
 /**
  * The platform send rate had no room for this campaign THIS HOUR (AGL-2409).

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

@@ -19,6 +19,7 @@ import { readListingRevocation } from "@aglyn/aglyn/plugin-manager/plugin-revoca
 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 { CAMPAIGN_PLAN_CAP_REASON, campaignPlanCapMessage, campaignPlanLock } from "../model/campaign-plan-lock.js";
 import { campaignHeldForReviewNotice, campaignPlacedOnHost, campaignSendHeldForReview } from "../model/campaign-container.js";
 import { readPluginRecordCard } from "@aglyn/aglyn/plugin-manager/plugin-record-cards";
 import { hostPublicOrigin } from "@aglyn/aglyn/server";
@@ -184,9 +185,13 @@ const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    * module's published surface.
    */ return sharedUnsubscribeSignature(hostId, email, secret, campaignId, topicId);
 }
-/** Send failures carry the HTTP status the API route should answer. */ export class CampaignSendError extends Error {
-    constructor(message, status){
-        super(message), this.status = status;
+/**
+ * Send failures carry the HTTP status the API route should answer, and a
+ * machine `reason` when the console answers that refusal with something
+ * other than the sentence (the plan cap's Upgrade button).
+ */ export class CampaignSendError extends Error {
+    constructor(message, status, reason, /** The plan lock behind a plan-cap refusal, for a client to draw. */ planLock){
+        super(message), this.status = status, this.reason = reason, this.planLock = planLock;
     }
 }
 /**
@@ -1324,15 +1329,29 @@ export async function performCampaignSend(options) {
     // a usage of 0 is how a plain limit is read; the ALLOW/REFUSE decision is
     // not made here — it is made by the atomic reservation below.
     const campaignSendLimit = checkQuota(orgForHost == null ? void 0 : orgForHost.org, 'emailSendsPerMonth', 0).limit;
-    const overCapError = ()=>new CampaignSendError(`Monthly campaign email limit reached (${campaignSendLimit}) — upgrade ` + 'in Billing or shrink the audience. Transactional mail — receipts, ' + 'booking reminders, password resets — keeps sending.', 403);
+    // Names the plan that would carry this campaign, so a refusal that reaches
+    // a merchant anyway — a native composer, a scheduled send — still says
+    // what to do. `campaignPlanLock` is the same rule the composer locks Send
+    // with.
+    const overCapError = (used)=>{
+        const lock = campaignPlanLock({
+            limit: campaignSendLimit,
+            used,
+            sendable: sendable.length
+        });
+        return new CampaignSendError(lock ? campaignPlanCapMessage(lock) : `Monthly campaign email limit reached (${campaignSendLimit}) — upgrade ` + 'in Billing or shrink the audience. Transactional mail — receipts, ' + 'booking reminders, password resets — keeps sending.', 403, CAMPAIGN_PLAN_CAP_REASON, lock);
+    };
+    // Read before the pre-check below and kept, so the race refusal after the
+    // atomic claim can still say how much of the allowance was spent.
+    const usedAtPreCheck = await orgCampaignEmailSendsForMonth(orgId, monthKey);
     {
         // A cheap read-only pre-check, so an over-cap campaign is refused before
         // the template load, the experiment read and the campaign id — and so the
         // DRY RUN has an answer without writing anything (AGL-2178: "nothing has
         // been written above this line"). It is not the enforcement; it cannot be,
         // because a read is not a claim.
-        const used = await orgCampaignEmailSendsForMonth(orgId, monthKey);
-        if (used + sendable.length > campaignSendLimit) throw overCapError();
+        const used = usedAtPreCheck;
+        if (used + sendable.length > campaignSendLimit) throw overCapError(used);
     }
     /*
    * Recipient PREVIEW (AGL-2178). The campaign composer mockup shows
@@ -1681,7 +1700,9 @@ export async function performCampaignSend(options) {
         // has not been entered yet, which is exactly why this cannot be left to
         // it.
         await reconcileOrgEmailSendDay(dayClaim.reservation, 0);
-        throw overCapError();
+        // A concurrent campaign took the rest between the pre-check and here, so
+        // the allowance is at least spent down to this campaign's size.
+        throw overCapError(Math.max(usedAtPreCheck, campaignSendLimit - sendable.length + 1));
     }
     const reservation = claim.reservation;
     const dayReservation = dayClaim.reservation;
@@ -3171,12 +3192,41 @@ function storedSendOptionsFrom(snapshot, hostId, senderUid, followUp) {
                 replyTo
             } : {}));
         }
+        /*
+     * THE PLAN'S ANSWER RIDES EVERY DRY RUN, refused or not.
+     *
+     * A composer asks for a preview the moment it opens, and "Send now" and
+     * "Send to more recipients" ask for a dry run before they offer their
+     * confirm, so this is where a plan without campaign email is said before
+     * any button that could only fail.
+     * The native composers draw `planLock` as it comes rather than porting
+     * the rule; the console computes the same `campaignPlanLock` from the
+     * same limit and counter. Read only when the answer is assembled, and
+     * a refusal that already carries its own lock (the cap) keeps it.
+     *
+     * A site outside an organization holds no campaign allowance to read.
+     */ const planLockFor = async (sendable)=>siteOrgId ? campaignPlanLock({
+                limit: checkQuota(orgForSite == null ? void 0 : orgForSite.org, 'emailSendsPerMonth', 0).limit,
+                used: await orgCampaignEmailSendsForMonth(siteOrgId, new Date().toISOString().slice(0, 7)),
+                sendable
+            }) : null;
+        const withPlanLock = (dryRun)=>dryRun.then(async (result)=>{
+                var _result_sendable;
+                return _extends({}, result, {
+                    planLock: await planLockFor(Number((_result_sendable = result.sendable) != null ? _result_sendable : 0))
+                });
+            }, async (error)=>{
+                if (error instanceof CampaignSendError && !error.planLock) {
+                    throw new CampaignSendError(error.message, error.status, error.reason, await planLockFor());
+                }
+                throw error;
+            });
         if (action === 'preview') {
             var _ref18, _ref19;
             var _req_body22, _req_body23, _req_body24;
             // Read-only, and it needs the same admin/editor role as a send: the
             // audience size of someone else's site is not public information.
-            const result = await performCampaignSend(_extends({
+            const result = await withPlanLock(performCampaignSend(_extends({
                 hostId,
                 subject: subject || 'preview',
                 body: body || 'preview',
@@ -3191,12 +3241,12 @@ function storedSendOptionsFrom(snapshot, hostId, senderUid, followUp) {
             } : {}, {
                 senderUid: decoded.uid,
                 dryRun: true
-            }));
+            })));
             return res.status(200).json(result);
         }
         if (action === 'followUp') {
             var _ref20;
-            var _req_body25, _req_body26;
+            var _req_body25, _req_body26, _req_body27;
             /*
        * SEND AN EMAIL THAT HAS ALREADY GONE OUT TO THE PEOPLE IT HAS NOT
        * REACHED.
@@ -3223,9 +3273,10 @@ function storedSendOptionsFrom(snapshot, hostId, senderUid, followUp) {
                     error: 'Unknown email'
                 });
             }
-            const result = await performCampaignSend(_extends({}, storedSendOptionsFrom(sendSnapshot, hostId, decoded.uid, true), ((_req_body26 = req.body) == null ? void 0 : _req_body26.dryRun) ? {
+            const followUpSend = performCampaignSend(_extends({}, storedSendOptionsFrom(sendSnapshot, hostId, decoded.uid, true), ((_req_body26 = req.body) == null ? void 0 : _req_body26.dryRun) ? {
                 dryRun: true
             } : {}));
+            const result = await (((_req_body27 = req.body) == null ? void 0 : _req_body27.dryRun) ? withPlanLock(followUpSend) : followUpSend);
             return res.status(200).json(result);
         }
         /*==========================================
@@ -3255,15 +3306,36 @@ function storedSendOptionsFrom(snapshot, hostId, senderUid, followUp) {
      * it, and only when somebody asks.
      *=========================================*/ if (action === 'draft' || action === 'schedule' || action === 'update') {
             var _ref21, _ref22, _targetSnapshot_get;
-            var _req_body27, _req_body28, _req_body29, _req_body30, _req_body31, _req_body32;
+            var _req_body28, _req_body29, _req_body30, _req_body31, _req_body32, _req_body33;
             const scheduling = action === 'schedule';
-            const sendAtMs = Number((_ref21 = (_req_body27 = req.body) == null ? void 0 : _req_body27.sendAtMs) != null ? _ref21 : 0);
+            const sendAtMs = Number((_ref21 = (_req_body28 = req.body) == null ? void 0 : _req_body28.sendAtMs) != null ? _ref21 : 0);
             if (scheduling && (!Number.isFinite(sendAtMs) || sendAtMs <= Date.now())) {
                 return res.status(400).json({
                     error: 'Pick a future send time'
                 });
             }
-            const campaignId = String((_ref22 = (_req_body28 = req.body) == null ? void 0 : _req_body28.campaignId) != null ? _ref22 : '') || createResourceUid();
+            /*
+       * A PLAN WITH NO CAMPAIGN EMAIL CANNOT SCHEDULE ONE.
+       *
+       * Scheduling writes a document and claims nothing, so without this a
+       * Free workspace could put a campaign on the clock that the processor
+       * can only ever mark `failed` — the refusal arriving hours later, in a
+       * history list, instead of now with an Upgrade path. A plan WITH an
+       * allowance is not refused here: the month may have reset by the send
+       * time, and the send itself enforces the cap.
+       */ if (scheduling) {
+                const lock = campaignPlanLock({
+                    limit: checkQuota(orgForSite == null ? void 0 : orgForSite.org, 'emailSendsPerMonth', 0).limit,
+                    used: 0
+                });
+                if ((lock == null ? void 0 : lock.kind) === 'not-on-plan') {
+                    return res.status(403).json({
+                        error: campaignPlanCapMessage(lock),
+                        reason: CAMPAIGN_PLAN_CAP_REASON
+                    });
+                }
+            }
+            const campaignId = String((_ref22 = (_req_body29 = req.body) == null ? void 0 : _req_body29.campaignId) != null ? _ref22 : '') || createResourceUid();
             // AGL-1771: this branch WRITES, and it is the only campaign write that
             // does not go through `performCampaignSend`'s guard. A `campaignId` of
             // `a/b/c` scheduled the campaign at `campaigns/a/b/c` — which the
@@ -3348,15 +3420,15 @@ function storedSendOptionsFrom(snapshot, hostId, senderUid, followUp) {
                 audience
             }, targetSnapshot.exists ? {} : {
                 createdAtMs: Date.now()
-            }, ((_req_body29 = req.body) == null ? void 0 : _req_body29.segmentId) ? {
+            }, ((_req_body30 = req.body) == null ? void 0 : _req_body30.segmentId) ? {
                 segmentId: String(req.body.segmentId)
-            } : {}, ((_req_body30 = req.body) == null ? void 0 : _req_body30.listId) ? {
+            } : {}, ((_req_body31 = req.body) == null ? void 0 : _req_body31.listId) ? {
                 listId: String(req.body.listId)
             } : {}, topicId ? {
                 topicId
-            } : {}, Array.isArray((_req_body31 = req.body) == null ? void 0 : _req_body31.emails) ? {
+            } : {}, Array.isArray((_req_body32 = req.body) == null ? void 0 : _req_body32.emails) ? {
                 emails: req.body.emails.map(String).slice(0, 500)
-            } : {}, ((_req_body32 = req.body) == null ? void 0 : _req_body32.experimentId) ? {
+            } : {}, ((_req_body33 = req.body) == null ? void 0 : _req_body33.experimentId) ? {
                 experimentId: String(req.body.experimentId)
             } : {}, {
                 /*
@@ -3422,8 +3494,8 @@ function storedSendOptionsFrom(snapshot, hostId, senderUid, followUp) {
         }
         if (action === 'cancel') {
             var _ref23;
-            var _req_body33;
-            const campaignId = String((_ref23 = (_req_body33 = req.body) == null ? void 0 : _req_body33.campaignId) != null ? _ref23 : '');
+            var _req_body34;
+            const campaignId = String((_ref23 = (_req_body34 = req.body) == null ? void 0 : _req_body34.campaignId) != null ? _ref23 : '');
             // AGL-1771: the ref used to be built one line ABOVE the `campaignId ?`
             // check below, which defeated that check — `.doc('')` throws on an empty
             // path segment, so the 400 this branch intends became a 500. Guarding
@@ -3454,7 +3526,7 @@ function storedSendOptionsFrom(snapshot, hostId, senderUid, followUp) {
         }
         if (action === 'sendNow') {
             var _ref24, _sendNowSnapshot_get, _ref25;
-            var _req_body34, _sendNowSnapshot_get1;
+            var _req_body35, _sendNowSnapshot_get1;
             /*==========================================
        * MAIL A DRAFTED OR SCHEDULED EMAIL, NOW.
        *
@@ -3470,7 +3542,7 @@ function storedSendOptionsFrom(snapshot, hostId, senderUid, followUp) {
        * lists, the same topic filtering, the same monthly reservation and the
        * same hourly governor — because it is the same function the scheduled
        * processor and the composer both call.
-       *=========================================*/ const sendNowId = String((_ref24 = (_req_body34 = req.body) == null ? void 0 : _req_body34.campaignId) != null ? _ref24 : '');
+       *=========================================*/ const sendNowId = String((_ref24 = (_req_body35 = req.body) == null ? void 0 : _req_body35.campaignId) != null ? _ref24 : '');
             if (!isDocumentId(sendNowId)) {
                 return res.status(400).json({
                     error: 'Invalid campaignId'
@@ -3548,15 +3620,16 @@ function storedSendOptionsFrom(snapshot, hostId, senderUid, followUp) {
                 });
             }
             try {
-                var _req_body35, _req_body36;
-                const result = await performCampaignSend(_extends({}, storedSendOptionsFrom(sendNowSnapshot, hostId, decoded.uid, false), ((_req_body35 = req.body) == null ? void 0 : _req_body35.dryRun) ? {
+                var _req_body36, _req_body37, _req_body38;
+                const sendNowSend = performCampaignSend(_extends({}, storedSendOptionsFrom(sendNowSnapshot, hostId, decoded.uid, false), ((_req_body36 = req.body) == null ? void 0 : _req_body36.dryRun) ? {
                     dryRun: true
                 } : {}));
+                const result = await (((_req_body37 = req.body) == null ? void 0 : _req_body37.dryRun) ? withPlanLock(sendNowSend) : sendNowSend);
                 /*
          * A dry run writes nothing, so the claim above is the only change it
          * made and it has to be put back — otherwise asking how many people
          * an email would reach would leave it stuck in `sending`.
-         */ if ((_req_body36 = req.body) == null ? void 0 : _req_body36.dryRun) {
+         */ if ((_req_body38 = req.body) == null ? void 0 : _req_body38.dryRun) {
                     await sendNowRef.set({
                         status: sendNowState
                     }, {
@@ -3645,9 +3718,13 @@ function storedSendOptionsFrom(snapshot, hostId, senderUid, followUp) {
         return res.status(200).json(result);
     } catch (error) {
         if (error instanceof CampaignSendError) {
-            return res.status(error.status).json({
+            return res.status(error.status).json(_extends({
                 error: error.message
-            });
+            }, error.reason ? {
+                reason: error.reason
+            } : {}, error.planLock ? {
+                planLock: error.planLock
+            } : {}));
         }
         console.error(error);
         return res.status(500).json({