ghost 6.64.0 → 6.65.0

package/core/server/services/comments/comments-service.js

@@ -13,9 +13,7 @@ const messages = {
   alreadyDisliked: 'This comment was disliked already',
   replyToReply: 'Can not reply to a reply',
   commentsNotEnabled: 'Comments are not enabled for this site.',
-  postIdRequired: 'A post ID is required to read comments.',
   cannotCommentOnPost: 'You do not have permission to comment on this post.',
-  cannotReadComment: 'You do not have permission to read comments on this post',
   cannotEditComment: 'You do not have permission to edit comments',
   cannotPinReply: 'Replies cannot be pinned',
   cannotPinDeletedComment: 'Deleted comments cannot be pinned',
@@ -41,7 +39,8 @@ const COMMENT_STATUSES_IN_REPLY_TO = [COMMENT_STATUS_PUBLISHED, COMMENT_STATUS_H
 // new `comment.get(...)` call has one obvious place to register its column.
 const REPLY_PARENT_REQUIRED_COLUMNS = ['parent_id', 'post_id'];
 const IN_REPLY_TO_REQUIRED_COLUMNS = ['parent_id'];
-const OWNERSHIP_REQUIRED_COLUMNS = ['member_id', 'post_id'];
+const OWNERSHIP_REQUIRED_COLUMNS = ['member_id'];
+const VOTE_REQUIRED_COLUMNS = ['post_id'];
 const REPORT_REQUIRED_COLUMNS = ['post_id', 'member_id', 'html', 'created_at'];
 
 function getColumnList(columns) {
@@ -169,14 +168,11 @@ class CommentsService {
   }
 
   /** @private */
-  checkPostAccess(postModel, memberModel, { action = 'comment' } = {}) {
-    const access = this.contentGating.checkPostAccess(
-      postModel.toJSON(),
-      memberModel ? memberModel.toJSON() : null,
-    );
+  checkPostAccess(postModel, memberModel) {
+    const access = this.contentGating.checkPostAccess(postModel.toJSON(), memberModel.toJSON());
     if (access === this.contentGating.BLOCK_ACCESS) {
       throw new errors.NoPermissionError({
-        message: tpl(action === 'read' ? messages.cannotReadComment : messages.cannotCommentOnPost),
+        message: tpl(messages.cannotCommentOnPost),
       });
     }
   }
@@ -194,32 +190,6 @@ class CommentsService {
     });
   }
 
-  async #checkPostAccessForRead(postId, options) {
-    if (options.isAdmin) {
-      return;
-    }
-
-    if (!postId) {
-      throw new errors.ValidationError({ message: tpl(messages.postIdRequired) });
-    }
-
-    const postModel = await this.models.Post.findOne(
-      { id: postId },
-      { require: true, transacting: options.transacting, withRelated: ['tiers'] },
-    );
-
-    let memberModel = null;
-    const memberId = options.context?.member?.id;
-    if (memberId) {
-      memberModel = await this.models.Member.findOne(
-        { id: memberId },
-        { require: true, transacting: options.transacting, withRelated: ['products'] },
-      );
-    }
-
-    this.checkPostAccess(postModel, memberModel, { action: 'read' });
-  }
-
   /**
    * Primary comment lookup: a single keyed fetch with the allowed statuses
    * applied in the query (`WHERE id = ? AND status IN (...)`), optionally locked
@@ -385,9 +355,27 @@ class CommentsService {
     this.checkCommentAccess(memberModel);
 
     return await this.#withTransaction(options, async (transactionOptions) => {
-      await this.#getPublishedCommentForAction(commentId, transactionOptions, [], {
-        forUpdate: true,
-      });
+      const comment = await this.#getPublishedCommentForAction(
+        commentId,
+        transactionOptions,
+        VOTE_REQUIRED_COLUMNS,
+        {
+          forUpdate: true,
+        },
+      );
+
+      const postModel = await this.models.Post.findOne(
+        {
+          id: comment.get('post_id'),
+        },
+        {
+          require: true,
+          ...transactionOptions,
+          withRelated: ['tiers'],
+        },
+      );
+
+      this.checkPostAccess(postModel, memberModel);
 
       const votes = await this.#getMemberCommentVotes(
         {
@@ -551,7 +539,6 @@ class CommentsService {
    */
   async getComments(options) {
     this.checkEnabled();
-    await this.#checkPostAccessForRead(options.post_id, options);
     const page = await this.models.Comment.findPage(
       withPinnedSelect({ ...options, parentId: null, pinnedFirst: true }),
     );
@@ -691,17 +678,6 @@ class CommentsService {
    */
   async getReplies(id, options, { includeHidden = false } = {}) {
     this.checkEnabled();
-
-    const parentComment = await this.#fetchCommentByID(id, options, {
-      requiredColumns: ['post_id'],
-    });
-
-    if (!parentComment) {
-      throw new errors.NotFoundError({ message: tpl(messages.commentNotFound) });
-    }
-
-    await this.#checkPostAccessForRead(parentComment.get('post_id'), options);
-
     const page = await this.models.Comment.findPage(
       withPinnedSelect({ ...options, parentId: id }, { includeHidden }),
     );
@@ -783,9 +759,7 @@ class CommentsService {
   async getCommentByID(id, options = {}) {
     this.checkEnabled();
 
-    const model = await this.#getReadableCommentByID(id, options, ['post_id']);
-    await this.#checkPostAccessForRead(model.get('post_id'), options);
-    return model;
+    return await this.#getReadableCommentByID(id, options);
   }
 
   /**
@@ -953,9 +927,6 @@ class CommentsService {
       });
     }
 
-    // Mutation responses include replies, so they require the same post access as reads.
-    await this.#checkPostAccessForRead(existingComment.get('post_id'), options);
-
     const model = await this.models.Comment.edit(
       {
         status: COMMENT_STATUS_DELETED,
@@ -991,8 +962,6 @@ class CommentsService {
       });
     }
 
-    await this.#checkPostAccessForRead(existingComment.get('post_id'), options);
-
     if (!comment) {
       return existingComment;
     }

package/core/server/services/comments/comments-stats-service.js

@@ -37,7 +37,7 @@ module.exports = class CommentsStatsService {
       .groupBy('post_id');
 
     /** @type Object<string, number> */
-    let counts = {};
+    const counts = {};
 
     for (const row of results) {
       counts[row.post_id] = row.count;

package/core/server/services/content-import/import/staged-file.js

@@ -5,25 +5,25 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createImportFileStager = createImportFileStager;
 const node_crypto_1 = __importDefault(require("node:crypto"));
-const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
-const fs_extra_1 = __importDefault(require("fs-extra"));
-function createImportFileStager() {
+// Stages uploads at the root of the imports storage adapter. The job reads the staged
+// file from its path, so the adapter is the local store storage:imports defaults to.
+function createImportFileStager(getStorage) {
     return {
         async stage({ filePath, fileName }) {
-            const stagedPath = node_path_1.default.join(node_os_1.default.tmpdir(), `content-csv-import-${node_crypto_1.default.randomUUID()}`);
+            const storage = getStorage();
+            const name = `content-csv-import-${node_crypto_1.default.randomUUID()}`;
             try {
-                await fs_extra_1.default.copyFile(filePath, stagedPath, fs_extra_1.default.constants.COPYFILE_EXCL);
-                await fs_extra_1.default.chmod(stagedPath, 0o600);
+                const url = await storage.save({ name, path: filePath }, storage.storagePath);
+                return { path: node_path_1.default.join(storage.storagePath, storage.urlToPath(url)), name: fileName };
             }
             catch (error) {
-                await fs_extra_1.default.remove(stagedPath).catch(() => { });
+                await storage.delete(name).catch(() => { });
                 throw error;
             }
-            return { path: stagedPath, name: fileName };
         },
         async remove(file) {
-            await fs_extra_1.default.remove(file.path);
+            await getStorage().delete(node_path_1.default.basename(file.path));
         },
     };
 }

package/core/server/services/content-import/index.js

@@ -78,7 +78,7 @@ function makeImporter() {
         }),
         email,
         dispatchJob: (job) => (0, jobs_service_1.getInstance)().dispatch(job),
-        fileStager: (0, staged_file_1.createImportFileStager)(),
+        fileStager: (0, staged_file_1.createImportFileStager)(() => require('../adapter-manager').default.getAdapter('storage:imports')),
         report,
         store: new store_1.ImportRunStore(),
         urlForPost: (post) => (0, post_link_1.urlForImportedPost)(post, {

package/core/server/services/custom-redirects/validation.js

@@ -16,7 +16,7 @@ const messages = {
  * @param {import('@tryghost/adapter-base-redirects').RedirectConfig[]} redirects
  */
 const validate = (redirects) => {
-  if (!_.isArray(redirects)) {
+  if (!Array.isArray(redirects)) {
     throw new errors.ValidationError({
       message: tpl(messages.redirectsWrongFormat),
       help: tpl(messages.redirectsHelp),

package/core/server/services/email-analytics/email-analytics-service-wrapper.js

@@ -4,12 +4,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EmailAnalyticsServiceWrapper = void 0;
-const errors_1 = __importDefault(require("@tryghost/errors"));
 const logging_1 = __importDefault(require("@tryghost/logging"));
 const email_analytics_service_1 = require("./email-analytics-service");
 const fetch_mailgun_events_1 = require("./fetch-mailgun-events");
 class EmailAnalyticsServiceWrapper {
     #logName;
+    #jobType;
+    #completionEvent;
     #config;
     #metrics;
     #service;
@@ -19,25 +20,10 @@ class EmailAnalyticsServiceWrapper {
     get #logPrefix() {
         return `[EmailAnalytics:${this.#logName}]`;
     }
-    get #backgroundJobName() {
-        switch (this.#logName) {
-            case 'newsletters':
-                return 'email-analytics-fetch-latest';
-            case 'automations':
-                return 'email-analytics-automation-fetch-latest';
-            case 'gifts':
-                return 'email-analytics-gift-fetch-latest';
-            default:
-                return `email-analytics-${this.#logName}-fetch-latest`;
-        }
-    }
-    constructor({ logName }) {
+    constructor({ logName, jobType, config, queries, mailgunTags, jobNames, cursorSeed, createEventProcessor, metrics, settingsCache, }) {
         this.#logName = logName;
-    }
-    init({ config, domainEvents, event, queries, mailgunTags, jobNames, cursorSeed, createEventProcessor, metrics, settingsCache, }) {
-        if (this.#service) {
-            return;
-        }
+        this.#jobType = jobType;
+        this.#completionEvent = `${jobType.replaceAll('-', '_')}.completed`;
         this.#config = config;
         this.#metrics = metrics;
         this.#fetchOpenedEvents = Boolean(cursorSeed.eventColumns.opened);
@@ -51,32 +37,12 @@ class EmailAnalyticsServiceWrapper {
         // Log the processing mode on initialization
         const batchProcessingEnabled = this.#config.get('emailAnalytics:batchProcessing');
         logging_1.default.info(`${this.#logPrefix} Initialized with ${batchProcessingEnabled ? 'BATCHED' : 'SEQUENTIAL'} processing mode`);
-        // We currently cannot trigger a non-offloaded job from the job manager
-        // So the email analytics jobs simply emits an event.
-        domainEvents.subscribe(event, async () => {
-            await this.startFetch();
-        });
     }
     get service() {
-        const result = this.#service;
-        if (!result) {
-            throw new errors_1.default.InternalServerError({
-                message: 'EmailAnalyticsServiceWrapper is not initialized with service',
-            });
-        }
-        return result;
-    }
-    #getConfig() {
-        const result = this.#config;
-        if (!result) {
-            throw new errors_1.default.InternalServerError({
-                message: 'EmailAnalyticsServiceWrapper is not initialized with config',
-            });
-        }
-        return result;
+        return this.#service;
     }
     _logJobCompletion(jobType, fetchResult, totalDurationMs, lagSeconds = null) {
-        const config = this.#getConfig();
+        const config = this.#config;
         const { eventCount, apiPollingTimeMs, processingTimeMs, aggregationTimeMs, emailAggregationTimeMs, memberAggregationTimeMs, result, } = fetchResult;
         if (eventCount === 0) {
             return;
@@ -87,7 +53,7 @@ class EmailAnalyticsServiceWrapper {
         const aggregationPercent = totalDurationMs > 0 ? Math.round((aggregationTimeMs / totalDurationMs) * 100) : 0;
         const batchMode = config.get('emailAnalytics:batchProcessing') ? 'BATCHED' : 'SEQUENTIAL';
         const logMessage = [
-            `[Background Job] ${this.#backgroundJobName} processed ${jobType} | ${this.#logPrefix}`,
+            `[Background Job] ${this.#jobType} processed ${jobType} | ${this.#logPrefix}`,
             `${eventCount} events in ${(totalDurationMs / 1000).toFixed(1)}s (${throughput.toFixed(2)} events/s)`,
             ...(lagSeconds === null ? [] : [`Lag: ${(lagSeconds / 60).toFixed(1)}m`]),
             `Mode: ${batchMode}`,
@@ -97,7 +63,7 @@ class EmailAnalyticsServiceWrapper {
         logging_1.default.info({
             system: {
                 event: 'job.completed',
-                job_type: this.#backgroundJobName,
+                job_type: this.#jobType,
                 task: jobType,
                 event_count: eventCount,
                 duration_ms: totalDurationMs,
@@ -112,13 +78,7 @@ class EmailAnalyticsServiceWrapper {
                 const metricName = this.#logName === 'newsletters'
                     ? 'email-analytics-open-throughput'
                     : `email-${this.#logName}-analytics-open-throughput`;
-                const metrics = this.#metrics;
-                if (!metrics) {
-                    throw new errors_1.default.InternalServerError({
-                        message: 'EmailAnalyticsServiceWrapper is not initialized with metrics',
-                    });
-                }
-                metrics.metric(metricName, {
+                this.#metrics.metric(metricName, {
                     value: throughput,
                     events: eventCount,
                     duration: totalDurationMs,
@@ -159,12 +119,12 @@ class EmailAnalyticsServiceWrapper {
                 await this.service.restoreScheduled();
             }
             catch (e) {
-                logging_1.default.error(e, `[Background Job] ${this.#backgroundJobName} failed while restoring scheduled events after ${Date.now() - startedAt}ms`);
+                logging_1.default.error(e, `[Background Job] ${this.#jobType} failed while restoring scheduled events after ${Date.now() - startedAt}ms`);
                 throw e;
             }
         }
         if (this.#fetching) {
-            logging_1.default.info(`[Background Job] ${this.#backgroundJobName} skipped because a fetch is already running`);
+            logging_1.default.info(`[Background Job] ${this.#jobType} skipped because a fetch is already running`);
             return;
         }
         this.#fetching = true;
@@ -194,11 +154,19 @@ class EmailAnalyticsServiceWrapper {
                 this._restartFetch('scheduled backfill');
                 return;
             }
-            logging_1.default.info(`[Background Job] ${this.#backgroundJobName} completed in ${Date.now() - startedAt}ms with ${c1 + c2 + c3 + c4} events | ${this.#logPrefix}`);
+            // The message is unchanged so existing log queries keep matching; the
+            // structured fields are additive.
+            logging_1.default.info({
+                system: {
+                    event: this.#completionEvent,
+                    event_count: c1 + c2 + c3 + c4,
+                    duration_ms: Date.now() - startedAt,
+                },
+            }, `[Background Job] ${this.#jobType} completed in ${Date.now() - startedAt}ms with ${c1 + c2 + c3 + c4} events | ${this.#logPrefix}`);
             this.#fetching = false;
         }
         catch (e) {
-            logging_1.default.error(e, `[Background Job] ${this.#backgroundJobName} failed after ${Date.now() - startedAt}ms`);
+            logging_1.default.error(e, `[Background Job] ${this.#jobType} failed after ${Date.now() - startedAt}ms`);
             // Log again only the error, otherwise we lose the stack trace
             logging_1.default.error(e);
         }
@@ -206,7 +174,7 @@ class EmailAnalyticsServiceWrapper {
     }
     _restartFetch(reason) {
         this.#fetching = false;
-        logging_1.default.info(`[Background Job] ${this.#backgroundJobName} continuing due to ${reason}`);
+        logging_1.default.info(`[Background Job] ${this.#jobType} continuing due to ${reason}`);
         this.startFetch();
     }
 }

package/core/server/services/email-analytics/index.js

@@ -3,7 +3,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.init = exports.gifts = exports.automations = exports.newsletters = void 0;
+exports.init = void 0;
+exports.getNewsletters = getNewsletters;
+exports.getAutomations = getAutomations;
+exports.getGifts = getGifts;
+const strict_1 = __importDefault(require("node:assert/strict"));
 const email_analytics_service_wrapper_1 = require("./email-analytics-service-wrapper");
 // @ts-expect-error This module lacks type definitions.
 const newsletter_email_analytics_batch_processor_1 = require("./newsletter-email-analytics-batch-processor");
@@ -21,16 +25,25 @@ const automation_email_analytics_batch_processor_1 = require("./automation-email
 const gift_email_analytics_batch_processor_1 = require("./gift-email-analytics-batch-processor");
 const start_gift_email_analytics_job_event_1 = require("./events/start-gift-email-analytics-job-event");
 const constants_2 = require("../gifts/constants");
-exports.newsletters = new email_analytics_service_wrapper_1.EmailAnalyticsServiceWrapper({
-    logName: 'newsletters',
-});
-exports.automations = new email_analytics_service_wrapper_1.EmailAnalyticsServiceWrapper({
-    logName: 'automations',
-});
-exports.gifts = new email_analytics_service_wrapper_1.EmailAnalyticsServiceWrapper({
-    logName: 'gifts',
-});
+let newsletters;
+let automations;
+let gifts;
+function getNewsletters() {
+    (0, strict_1.default)(newsletters, 'Newsletter email analytics should be initialized');
+    return newsletters;
+}
+function getAutomations() {
+    (0, strict_1.default)(automations, 'Automation email analytics should be initialized');
+    return automations;
+}
+function getGifts() {
+    (0, strict_1.default)(gifts, 'Gift email analytics should be initialized');
+    return gifts;
+}
 const init = ({ automationsApi, config, db, domainEvents, emailSuppressionList, giftDeliveryService, membersRepository, models: { Email, EmailRecipientFailure, EmailSpamComplaintEvent }, metrics, prometheusClient, settingsCache, }) => {
+    if (newsletters) {
+        return;
+    }
     const queries = new queries_1.Queries(db.knex);
     const newsletterEmailEventProcessor = new email_event_processor_1.default({
         domainEvents,
@@ -62,10 +75,10 @@ const init = ({ automationsApi, config, db, domainEvents, emailSuppressionList,
         name: newsletter_email_analytics_batch_processor_1.AGGREGATE_MEMBER_STATS_METRIC_NAME,
         help: 'Count of member stats aggregations',
     });
-    exports.newsletters.init({
+    newsletters = new email_analytics_service_wrapper_1.EmailAnalyticsServiceWrapper({
+        logName: 'newsletters',
+        jobType: 'email-analytics-fetch-latest',
         config,
-        domainEvents,
-        event: start_email_analytics_job_event_1.StartEmailAnalyticsJobEvent,
         queries,
         mailgunTags: newsletterMailgunTags,
         jobNames: {
@@ -91,10 +104,10 @@ const init = ({ automationsApi, config, db, domainEvents, emailSuppressionList,
             queries,
         }),
     });
-    exports.automations.init({
+    automations = new email_analytics_service_wrapper_1.EmailAnalyticsServiceWrapper({
+        logName: 'automations',
+        jobType: 'email-analytics-automation-fetch-latest',
         config,
-        domainEvents,
-        event: start_automation_email_analytics_job_event_1.StartAutomationEmailAnalyticsJobEvent,
         queries,
         mailgunTags: automationMailgunTags,
         jobNames: {
@@ -116,10 +129,10 @@ const init = ({ automationsApi, config, db, domainEvents, emailSuppressionList,
             automationsApi,
         }),
     });
-    exports.gifts.init({
+    gifts = new email_analytics_service_wrapper_1.EmailAnalyticsServiceWrapper({
+        logName: 'gifts',
+        jobType: 'email-analytics-gift-fetch-latest',
         config,
-        domainEvents,
-        event: start_gift_email_analytics_job_event_1.StartGiftEmailAnalyticsJobEvent,
         queries,
         mailgunTags: giftMailgunTags,
         jobNames: {
@@ -139,5 +152,8 @@ const init = ({ automationsApi, config, db, domainEvents, emailSuppressionList,
         settingsCache,
         createEventProcessor: () => new gift_email_analytics_batch_processor_1.GiftEmailAnalyticsBatchProcessor({ giftDeliveryService }),
     });
+    domainEvents.subscribe(start_email_analytics_job_event_1.StartEmailAnalyticsJobEvent, () => newsletters.startFetch());
+    domainEvents.subscribe(start_automation_email_analytics_job_event_1.StartAutomationEmailAnalyticsJobEvent, () => automations.startFetch());
+    domainEvents.subscribe(start_gift_email_analytics_job_event_1.StartGiftEmailAnalyticsJobEvent, () => gifts.startFetch());
 };
 exports.init = init;

package/core/server/services/email-analytics/jobs/email-analytics-job-scheduler.js

@@ -47,10 +47,11 @@ function randomFiveMinuteCron() {
     const minutes = Math.floor(Math.random() * 5); // 0-4
     return `${seconds} ${minutes}/5 * * * *`;
 }
+function thirtyDaysAgo() {
+    return moment_1.default.utc().subtract(30, 'days').toDate();
+}
 class EmailAnalyticsJobScheduler {
-    #hasScheduledNewslettersJob = false;
-    #hasScheduledAutomationsJob = false;
-    #hasScheduledGiftDeliveriesJob = false;
+    #scheduledJobNames = new Set();
     #models;
     #config;
     #jobManager;
@@ -64,76 +65,46 @@ class EmailAnalyticsJobScheduler {
             this.#config.get('backgroundJobs:emailAnalytics'));
     }
     async scheduleRecurringNewslettersJob(skipNewsletterEmailCheck = false) {
-        if (this.#hasScheduledNewslettersJob) {
-            return;
-        }
-        if (!this.#isConfigured()) {
-            return;
-        }
         // Don't register email analytics job if we have no emails,
         // processor usage from many sites spinning up threads can be high.
         // Mega service will re-run this scheduling task when an email is sent
-        const emailCount = skipNewsletterEmailCheck
-            ? 1
-            : Number(await this.#models.Email.where('created_at', '>', moment_1.default.utc().subtract(30, 'days').toDate())
-                .where('status', '<>', 'failed')
-                .count());
-        if (emailCount > 0 && !this.#hasScheduledNewslettersJob) {
-            const at = randomFiveMinuteCron();
-            logging.info(`[Background Job] email-analytics-fetch-latest scheduled at ${at}`);
-            this.#jobManager.addJob({
-                at,
-                job: path.resolve(__dirname, 'fetch-latest/index.js'),
-                name: 'email-analytics-fetch-latest',
-            });
-            this.#hasScheduledNewslettersJob = true;
-        }
+        await this.#scheduleOnce({
+            name: 'email-analytics-fetch-latest',
+            workerPath: path.resolve(__dirname, 'fetch-latest/index.js'),
+        }, skipNewsletterEmailCheck, async () => Number(await this.#models.Email.where('created_at', '>', thirtyDaysAgo())
+            .where('status', '<>', 'failed')
+            .count()) > 0);
     }
     async scheduleRecurringAutomationsJob(skipAutomationEmailCheck = false) {
-        if (this.#hasScheduledAutomationsJob) {
-            return;
-        }
-        if (!this.#isConfigured()) {
-            return;
-        }
-        const hasAutomatedEmailRecipient = skipAutomationEmailCheck ||
-            Boolean(await this.#models.AutomatedEmailRecipient.query()
-                .where('created_at', '>', moment_1.default.utc().subtract(30, 'days').toDate())
-                .whereNotNull('mailgun_message_id')
-                .first('id'));
-        if (!hasAutomatedEmailRecipient || this.#hasScheduledAutomationsJob) {
-            return;
-        }
-        const at = randomFiveMinuteCron();
-        logging.info(`[Background Job] email-analytics-automation-fetch-latest scheduled at ${at}`);
-        this.#jobManager.addJob({
-            at,
-            job: path.resolve(__dirname, 'automation-fetch-latest/index.js'),
+        await this.#scheduleOnce({
             name: 'email-analytics-automation-fetch-latest',
-        });
-        this.#hasScheduledAutomationsJob = true;
+            workerPath: path.resolve(__dirname, 'automation-fetch-latest/index.js'),
+        }, skipAutomationEmailCheck, async () => Boolean(await this.#models.AutomatedEmailRecipient.query()
+            .where('created_at', '>', thirtyDaysAgo())
+            .whereNotNull('mailgun_message_id')
+            .first('id')));
     }
     async scheduleRecurringGiftDeliveriesJob(skipGiftDeliveryCheck = false) {
-        if (this.#hasScheduledGiftDeliveriesJob || !this.#isConfigured()) {
+        await this.#scheduleOnce({
+            name: 'email-analytics-gift-fetch-latest',
+            workerPath: path.resolve(__dirname, 'gift-fetch-latest/index.js'),
+        }, skipGiftDeliveryCheck, async () => Boolean(await this.#models.GiftDelivery.query()
+            .where('email_sent_at', '>', thirtyDaysAgo())
+            .whereNotNull('email_provider_message_id')
+            .first('id')));
+    }
+    async #scheduleOnce(job, skipRecentSendsCheck, hasRecentSends) {
+        if (this.#scheduledJobNames.has(job.name) || !this.#isConfigured()) {
             return;
         }
-        const hasGiftDelivery = skipGiftDeliveryCheck ||
-            Boolean(this.#models.GiftDelivery &&
-                (await this.#models.GiftDelivery.query()
-                    .where('email_sent_at', '>', moment_1.default.utc().subtract(30, 'days').toDate())
-                    .whereNotNull('email_provider_message_id')
-                    .first('id')));
-        if (!hasGiftDelivery || this.#hasScheduledGiftDeliveriesJob) {
+        const shouldSchedule = skipRecentSendsCheck || (await hasRecentSends());
+        if (!shouldSchedule || this.#scheduledJobNames.has(job.name)) {
             return;
         }
         const at = randomFiveMinuteCron();
-        logging.info(`[Background Job] email-analytics-gift-fetch-latest scheduled at ${at}`);
-        this.#jobManager.addJob({
-            at,
-            job: path.resolve(__dirname, 'gift-fetch-latest/index.js'),
-            name: 'email-analytics-gift-fetch-latest',
-        });
-        this.#hasScheduledGiftDeliveriesJob = true;
+        logging.info(`[Background Job] ${job.name} scheduled at ${at}`);
+        this.#jobManager.addJob({ at, job: job.workerPath, name: job.name });
+        this.#scheduledJobNames.add(job.name);
     }
 }
 exports.EmailAnalyticsJobScheduler = EmailAnalyticsJobScheduler;

package/core/server/services/email-service/README.md

@@ -4,6 +4,41 @@ Renders newsletter emails, splits them into recipient batches, and submits the
 batches to the configured email provider. Domain terms live in
 [CONTEXT.md](CONTEXT.md).
 
+## Job lifecycle
+
+New sends, retries, and boot recovery dispatch a data-only `SendEmailJob`
+containing the email ID through the class-based jobs service. Boot injects
+that service and registers `EmailService.handleSendEmailJob`, which delegates
+to `BatchSendingService.emailJob`. The batch sender refetches the email and
+acquires its status lock before preparing or submitting batches. See the
+[jobs guide](../../../../../../docs/codebase/jobs.md#queues) for queue isolation
+and concurrency limits.
+
+`scheduleEmail()` waits for dispatch to complete, not for submission. The
+current in-memory backend provides no durable acceptance guarantee and drops
+dispatches after shutdown starts without rejecting them. Email status records
+the sending outcome; a job handler returning does not imply submission, since
+it may have skipped the send, recorded a failure, or stopped for shutdown.
+
+Shutdown first stops workers from claiming new batches. The batch sender's
+separate cleanup task waits for active batch preparation and submission even
+if the jobs backend's shutdown wait times out. This tracking currently ends
+before the final email status write. On boot, recovery reschedules eligible
+interrupted sends within `bulkEmail:resumeMaxAgeMs` and skips batches already
+submitted.
+
+## Testing
+
+Tests that publish or retry a newsletter should mock the email provider and
+await `waitForEmailStatus(emailId)` from
+[`test/utils/batch-email-utils.js`](../../../../test/utils/batch-email-utils.js)
+before restoring mocks or deleting fixtures. The helper returns on either
+`submitted` or `failed`, so assert the expected status explicitly.
+
+A terminal email status describes the send's outcome; it does not prove that
+every competing retry or job attempting the status lock has finished. Tests
+which create competing attempts must also wait for those attempts to settle.
+
 ## Sending status
 
 The sending status served by the Admin API's `emails/:id/status` endpoint is