ghost 6.62.0 → 6.63.0

package/core/server/data/tinybird/pipes/mv_hits.pipe

@@ -2,19 +2,23 @@ TOKEN "axis" READ
 
 NODE mv_hits_0
 SQL >
-
-    SELECT timestamp,
+    SELECT
+        timestamp,
         inserted_at,
         -- payload.meta.received_timestamp may be missing or null
-        -- Nullable fields incur performance penalty in clickhouse, so we default to zero (unix epoch) instead of null.
-        parseDateTime64BestEffortOrZero(JSONExtractString(payload, 'meta', 'received_timestamp'), 3) as received_at,
+        -- Nullable fields incur performance penalty in clickhouse, so we default to zero (unix epoch)
+        -- instead of null.
+        parseDateTime64BestEffortOrZero(
+            JSONExtractString(payload, 'meta', 'received_timestamp'), 3
+        ) as received_at,
         action,
         version,
         coalesce(session_id, '0') as session_id,
         JSONExtractString(payload, 'locale') as locale,
         JSONExtractString(payload, 'location') as location,
         case
-            when JSONExtractString(payload, 'referrerSource') = '' then JSONExtractString(payload, 'meta', 'referrerSource')
+            when JSONExtractString(payload, 'referrerSource') = ''
+            then JSONExtractString(payload, 'meta', 'referrerSource')
             else JSONExtractString(payload, 'referrerSource')
         end as referrer,
         JSONExtractString(payload, 'pathname') as pathname,
@@ -35,11 +39,8 @@ SQL >
     FROM analytics_events
     where action = 'page_hit'
 
-
-
 NODE mv_hits_1
 SQL >
-
     SELECT
         site_uuid,
         timestamp,
@@ -47,8 +48,10 @@ SQL >
         inserted_at,
         case
             -- set to -1 if received_at is the unix epoch, or if received_at is after inserted_at
-            when toUnixTimestamp(received_at) = 0 then -1
-            when received_at > inserted_at then -1
+            when toUnixTimestamp(received_at) = 0
+            then -1
+            when received_at > inserted_at
+            then -1
             else date_diff('millisecond', received_at, inserted_at)
         end as ingestion_latency_ms,
         action,
@@ -61,58 +64,91 @@ SQL >
         gift_link,
         location,
         case
-            when referrer = '' then ''
+            when referrer = ''
+            then ''
             -- Social Media Consolidation
-            when referrer IN ('Facebook', 'www.facebook.com', 'l.facebook.com', 'lm.facebook.com', 'm.facebook.com', 'facebook') then 'Facebook'
-            when referrer IN ('Twitter', 'x.com', 'com.twitter.android') then 'Twitter'
-            when referrer IN ('go.bsky.app', 'bsky', 'bsky.app') then 'Bluesky'
-            when referrer IN ('Instagram', 'www.instagram.com') then 'Instagram'
-            when referrer IN ('LinkedIn', 'LINKEDIN_COMPANY') then 'LinkedIn'
-            when referrer IN ('l.threads.com') then 'Threads'
-
+            when
+                referrer IN (
+                    'Facebook',
+                    'www.facebook.com',
+                    'l.facebook.com',
+                    'lm.facebook.com',
+                    'm.facebook.com',
+                    'facebook'
+                )
+            then 'Facebook'
+            when referrer IN ('Twitter', 'x.com', 'com.twitter.android')
+            then 'Twitter'
+            when referrer IN ('go.bsky.app', 'bsky', 'bsky.app')
+            then 'Bluesky'
+            when referrer IN ('Instagram', 'www.instagram.com')
+            then 'Instagram'
+            when referrer IN ('LinkedIn', 'LINKEDIN_COMPANY')
+            then 'LinkedIn'
+            when referrer IN ('l.threads.com')
+            then 'Threads'
             -- Reddit Ecosystem
-            when referrer IN ('www.reddit.com', 'out.reddit.com', 'old.reddit.com', 'com.reddit.frontpage') then 'Reddit'
-
+            when
+                referrer
+                IN ('www.reddit.com', 'out.reddit.com', 'old.reddit.com', 'com.reddit.frontpage')
+            then 'Reddit'
             -- Search Engines (keep distinctions)
-            when referrer IN ('search.brave.com') then 'Brave Search'
-            when referrer IN ('www.ecosia.org') then 'Ecosia'
-
+            when referrer IN ('search.brave.com')
+            then 'Brave Search'
+            when referrer IN ('www.ecosia.org')
+            then 'Ecosia'
             -- Email Services
-            when referrer IN ('Gmail', 'com.google.android.gm', 'mail.google.com') then 'Gmail'
-            when referrer IN ('Outlook.com') then 'Outlook'
-            when referrer IN ('Yahoo!', 'www.yahoo.com', 'Yahoo! Mail', 'r.search.yahoo.com') then 'Yahoo!'
-            when referrer IN ('AOL Mail') then 'AOL Mail'
-
+            when referrer IN ('Gmail', 'com.google.android.gm', 'mail.google.com')
+            then 'Gmail'
+            when referrer IN ('Outlook.com')
+            then 'Outlook'
+            when referrer IN ('Yahoo!', 'www.yahoo.com', 'Yahoo! Mail', 'r.search.yahoo.com')
+            then 'Yahoo!'
+            when referrer IN ('AOL Mail')
+            then 'AOL Mail'
             -- Content Platforms
-            when referrer IN ('flipboard', 'flipboard.com', 'flipboard.app') then 'Flipboard'
-            when referrer IN ('substack', 'substack.com') then 'Substack'
-            when referrer IN ('Ghost.org', 'ghost.org') then 'Ghost'
-            when referrer IN ('buffer') then 'Buffer'
-            when referrer IN ('Taboola') then 'Taboola'
-            when referrer IN ('AppNexus') then 'AppNexus'
-
+            when referrer IN ('flipboard', 'flipboard.com', 'flipboard.app')
+            then 'Flipboard'
+            when referrer IN ('substack', 'substack.com')
+            then 'Substack'
+            when referrer IN ('Ghost.org', 'ghost.org')
+            then 'Ghost'
+            when referrer IN ('buffer')
+            then 'Buffer'
+            when referrer IN ('Taboola')
+            then 'Taboola'
+            when referrer IN ('AppNexus')
+            then 'AppNexus'
             -- Wikipedia
-            when referrer IN ('en.wikipedia.org', 'en.m.wikipedia.org') then 'Wikipedia'
-
+            when referrer IN ('en.wikipedia.org', 'en.m.wikipedia.org')
+            then 'Wikipedia'
             -- Mastodon Network
-            when referrer IN ('mastodon.social', 'mastodon.online', 'org.joinmastodon.android', 'phanpy.social', 'dev.phanpy.social') then 'Mastodon'
-
+            when
+                referrer IN (
+                    'mastodon.social',
+                    'mastodon.online',
+                    'org.joinmastodon.android',
+                    'phanpy.social',
+                    'dev.phanpy.social'
+                )
+            then 'Mastodon'
             -- News Aggregators
-            when referrer IN ('www.memeorandum.com', 'memeorandum.com') then 'Memeorandum'
-            when referrer IN ('ground.news') then 'Ground News'
-            when referrer IN ('apple.news') then 'Apple News'
-            when referrer IN ('www.smartnews.com') then 'SmartNews'
-
+            when referrer IN ('www.memeorandum.com', 'memeorandum.com')
+            then 'Memeorandum'
+            when referrer IN ('ground.news')
+            then 'Ground News'
+            when referrer IN ('apple.news')
+            then 'Apple News'
+            when referrer IN ('www.smartnews.com')
+            then 'SmartNews'
             -- Keep other sources as-is
-            when domainWithoutWWW(referrer) != '' then domainWithoutWWW(referrer)
+            when domainWithoutWWW(referrer) != ''
+            then domainWithoutWWW(referrer)
             else referrer
         end as source,
         pathname,
         href,
-        case  
-            when device = '' then 'unknown'  
-            else device  
-        end as device,
+        case when device = '' then 'unknown' else device end as device,
         case
             when match(user_agent, 'windows')
             then 'windows'
@@ -146,5 +182,5 @@ SQL >
         utm_content
     FROM mv_hits_0
 
-TYPE materialized
+TYPE MATERIALIZED
 DATASOURCE _mv_hits

package/core/server/lib/db-types/count.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DbCount = void 0;
+const zod_1 = require("zod");
+const databaseCountInput = zod_1.z.union([zod_1.z.number(), zod_1.z.string().regex(/^\d+$/)]);
+/**
+ * A non-negative integer count, whichever database driver handed it back.
+ *
+ * Aggregate functions such as COUNT can return a decimal string from MySQL and
+ * a number from SQLite. Every read normalises to a safe integer so callers do
+ * not need to handle that driver difference themselves.
+ */
+exports.DbCount = zod_1.z.codec(databaseCountInput, zod_1.z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER), {
+    decode: (stored) => (typeof stored === 'string' ? Number(stored) : stored),
+    encode: (value) => value,
+});

package/core/server/lib/validate-password.js

@@ -1,131 +1,92 @@
-const _ = require('lodash');
-
-const validator = require('@tryghost/validator');
-
-const tpl = require('@tryghost/tpl');
-const settingsCache = require('../../shared/settings-cache');
-const urlUtils = require('../../shared/url-utils').default;
-
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePassword = validatePassword;
+const tpl_1 = __importDefault(require("@tryghost/tpl"));
+// @ts-expect-error This module lacks type definitions.
+const validator_1 = __importDefault(require("@tryghost/validator"));
+// @ts-expect-error This module lacks type definitions.
+const settings_cache_1 = __importDefault(require("../../shared/settings-cache"));
+const url_utils_1 = __importDefault(require("../../shared/url-utils"));
 const messages = {
-  passwordDoesNotComplyLength: 'Your password must be at least {minLength} characters long.',
-  passwordDoesNotComplySecurity: 'Sorry, you cannot use an insecure password.',
+    passwordTooShort: 'Your password must be at least {minLength} characters long.',
+    passwordTooLong: 'Your password is too long.',
+    passwordDoesNotComplySecurity: 'Sorry, you cannot use an insecure password.',
 };
-
 /**
  * Counts repeated characters in a string. When 50% or more characters are the same,
  * we return false and therefore invalidate the string.
- * @param {string} stringToTest The password string to check.
- * @return {boolean}
  */
-function characterOccurance(stringToTest) {
-  const chars = {};
-  let allowedOccurancy;
-  let valid = true;
-
-  stringToTest = _.toString(stringToTest);
-  allowedOccurancy = stringToTest.length / 2;
-
-  // Loop through string and accumulate character counts
-  _.each(stringToTest, function (char) {
-    if (!chars[char]) {
-      chars[char] = 1;
-    } else {
-      chars[char] += 1;
-    }
-  });
-
-  // check if any of the accumulated chars exceed the allowed occurancy
-  // of 50% of the words' length.
-  _.forIn(chars, function (charCount) {
-    if (charCount >= allowedOccurancy) {
-      valid = false;
+function characterOccurrence(stringToTest) {
+    const limit = stringToTest.length / 2;
+    const counts = new Map();
+    for (let i = 0; i < stringToTest.length; i++) {
+        const char = stringToTest[i];
+        const count = (counts.get(char) || 0) + 1;
+        if (count >= limit) {
+            return false;
+        }
+        counts.set(char, count);
     }
-  });
-
-  return valid;
+    return true;
 }
-
-/**
- * Validation against simple password rules
- * Returns false when validation fails and true for a valid password
- * @param {string} password The password string to check.
- * @param {string} email The users email address to validate agains password.
- * @param {string} [blogTitle] Optional blogTitle value, when blog title is not set yet, e. g. in setup process.
- * @return {Object} example for returned validation Object:
- * invalid password: `validationResult: {isValid: false, message: 'Sorry, you cannot use an insecure password.'}`
- * valid password: `validationResult: {isValid: true}`
- */
-function validatePassword(password, email, blogTitle) {
-  const validationResult = { isValid: true };
-  const disallowedPasswords = ['password', 'ghost', 'passw0rd'];
-  let blogUrl = urlUtils.urlFor('home', true);
-
-  const badPasswords = [
-    '1234567890',
-    'qwertyuiop',
-    'qwertzuiop',
-    'asdfghjkl;',
-    'abcdefghij',
-    '0987654321',
-    '1q2w3e4r5t',
-    '12345asdfg',
-  ];
-
-  blogTitle = blogTitle ? blogTitle : settingsCache.get('title');
-  blogUrl = blogUrl.replace(/^http(s?):\/\//, '');
-
-  // password must be longer than 10 characters
-  if (!validator.isLength(password, 10)) {
-    validationResult.isValid = false;
-    validationResult.message = tpl(messages.passwordDoesNotComplyLength, { minLength: 10 });
-
-    return validationResult;
-  }
-
-  // dissallow password from badPasswords list (e. g. '1234567890')
-  _.each(badPasswords, function (badPassword) {
-    if (badPassword === password) {
-      validationResult.isValid = false;
+/** Validation against simple password rules. */
+function validatePassword(password, email, siteTitle) {
+    // password cannot be longer than 256 code units, for performance
+    if (password.length > 256) {
+        return { isValid: false, message: (0, tpl_1.default)(messages.passwordTooLong) };
+    }
+    // password must be longer than 10 characters
+    if (!validator_1.default.isLength(password, 10)) {
+        return { isValid: false, message: (0, tpl_1.default)(messages.passwordTooShort, { minLength: 10 }) };
+    }
+    const invalidValidationResult = {
+        isValid: false,
+        message: (0, tpl_1.default)(messages.passwordDoesNotComplySecurity),
+    };
+    // password must not match with users' email
+    if (email && email.toLowerCase() === password.toLowerCase()) {
+        return invalidValidationResult;
+    }
+    // password must not match with site title
+    siteTitle = siteTitle || settings_cache_1.default.get('title');
+    if (siteTitle && siteTitle.toLowerCase() === password.toLowerCase()) {
+        return invalidValidationResult;
+    }
+    // password must not match with site URL (without protocol, with or without trailing slash)
+    let siteUrl = url_utils_1.default.urlFor('home', true);
+    siteUrl = siteUrl.replace(/^http(s?):\/\//, '');
+    if (siteUrl &&
+        (siteUrl.toLowerCase() === password.toLowerCase() ||
+            siteUrl.toLowerCase().replace(/\/$/, '') === password.toLowerCase())) {
+        return invalidValidationResult;
+    }
+    // disallow password from badPasswords list (e. g. '1234567890')
+    const badPasswords = [
+        '1234567890',
+        'qwertyuiop',
+        'qwertzuiop',
+        'asdfghjkl;',
+        'abcdefghij',
+        '0987654321',
+        '1q2w3e4r5t',
+        '12345asdfg',
+    ];
+    if (badPasswords.includes(password)) {
+        return invalidValidationResult;
+    }
+    // password must not contain the words 'ghost', 'password', or 'passw0rd'
+    const disallowedPasswords = ['password', 'ghost', 'passw0rd'];
+    for (const disallowedPassword of disallowedPasswords) {
+        if (password.toLowerCase().includes(disallowedPassword)) {
+            return invalidValidationResult;
+        }
     }
-  });
-
-  // password must not match with users' email
-  if (email && email.toLowerCase() === password.toLowerCase()) {
-    validationResult.isValid = false;
-  }
-
-  // password must not contain the words 'ghost', 'password', or 'passw0rd'
-  _.each(disallowedPasswords, function (disallowedPassword) {
-    if (password.toLowerCase().indexOf(disallowedPassword) >= 0) {
-      validationResult.isValid = false;
+    // dissallow passwords where 50% or more of characters are the same
+    if (!characterOccurrence(password)) {
+        return invalidValidationResult;
     }
-  });
-
-  // password must not match with blog title
-  if (blogTitle && blogTitle.toLowerCase() === password.toLowerCase()) {
-    validationResult.isValid = false;
-  }
-
-  // password must not match with blog URL (without protocol, with or without trailing slash)
-  if (
-    blogUrl &&
-    (blogUrl.toLowerCase() === password.toLowerCase() ||
-      blogUrl.toLowerCase().replace(/\/$/, '') === password.toLowerCase())
-  ) {
-    validationResult.isValid = false;
-  }
-
-  // dissallow passwords where 50% or more of characters are the same
-  if (!characterOccurance(password)) {
-    validationResult.isValid = false;
-  }
-
-  // Generic error message for the rules where no dedicated error massage is set
-  if (!validationResult.isValid && !validationResult.message) {
-    validationResult.message = tpl(messages.passwordDoesNotComplySecurity);
-  }
-
-  return validationResult;
+    return { isValid: true };
 }
-
-module.exports = validatePassword;

package/core/server/models/action.js

@@ -1,10 +1,10 @@
 const ghostBookshelf = require('./base');
 
-// Member custom fields are owned by a raw-knex service rather than the Bookshelf
+// Member metafields are owned by a raw-knex service rather than the Bookshelf
 // registry. Actions still need a read model for `include=resource` to recognise
 // their polymorphic resource type and load the current field definition.
-const MemberCustomFieldResource = ghostBookshelf.Model.extend({
-  tableName: 'members_custom_fields',
+const MemberMetafieldResource = ghostBookshelf.Model.extend({
+  tableName: 'members_metafields',
 });
 
 const Action = ghostBookshelf.Model.extend(
@@ -26,7 +26,7 @@ const Action = ghostBookshelf.Model.extend(
         candidates.push([User, 'security_action']);
       }
 
-      candidates.push([MemberCustomFieldResource, 'member_custom_field']);
+      candidates.push([MemberMetafieldResource, 'member_custom_field']);
 
       return candidates;
     },

package/core/server/models/base/plugins/filtered-collection.js

@@ -1,3 +1,6 @@
+const _ = require('lodash');
+const { hasPosts } = require('@tryghost/bookshelf-plugins');
+
 /**
  * @param {import('bookshelf')} Bookshelf
  */
@@ -17,6 +20,19 @@ module.exports = function (Bookshelf) {
         // Apply model-specific search behavior
         filteredCollection.applySearchQuery(options);
 
+        // Authors are hidden unless they have posts. Apply that constraint before
+        // fetchPage clones its count query so pagination cannot reveal hidden staff.
+        // Keep this author-specific: tags have separate, established count semantics.
+        if (filteredCollection.shouldHavePosts?.joinTable === 'posts_authors') {
+          filteredCollection.query(
+            hasPosts.addHasPostsWhere(
+              _.result(filteredCollection, 'tableName'),
+              filteredCollection.shouldHavePosts,
+            ),
+          );
+          filteredCollection.shouldHavePosts = null;
+        }
+
         return filteredCollection;
       },
 

package/core/server/models/member.js

@@ -5,9 +5,9 @@ const { chainTransformers } = require('@tryghost/mongo-utils');
 const config = require('../../shared/config');
 const { MemberCommentingCodec } = require('../services/members/commenting');
 const {
-  CUSTOM_FIELDS_RELATION,
-  createCustomFieldsFilterTransformer,
-} = require('../services/members-custom-fields/filter');
+  METAFIELDS_RELATION,
+  createMetafieldsFilterTransformer,
+} = require('../services/members-metafields/filter');
 
 const DEEP_OFFSET_THRESHOLD = 1000;
 
@@ -195,8 +195,8 @@ const Member = ghostBookshelf.Model.extend(
     // getFilteredCollectionQuery. Chaining the metafield filter transformer here covers them
     // all without any call site wiring it.
     applyDefaultAndCustomFilters(options) {
-      if (options.filter && options.filter.includes(`${CUSTOM_FIELDS_RELATION.tableNameAs}.`)) {
-        const transformer = createCustomFieldsFilterTransformer();
+      if (options.filter && options.filter.includes(`${METAFIELDS_RELATION.tableNameAs}.`)) {
+        const transformer = createMetafieldsFilterTransformer();
         options.mongoTransformer = options.mongoTransformer
           ? chainTransformers(options.mongoTransformer, transformer)
           : transformer;
@@ -206,7 +206,7 @@ const Member = ghostBookshelf.Model.extend(
 
     filterRelations() {
       return {
-        metafields: CUSTOM_FIELDS_RELATION,
+        metafields: METAFIELDS_RELATION,
         labels: {
           tableName: 'labels',
           type: 'manyToMany',

package/core/server/models/user.js

@@ -6,7 +6,7 @@ const limitService = require('../services/limits');
 const tpl = require('@tryghost/tpl');
 const errors = require('@tryghost/errors');
 const security = require('@tryghost/security');
-const validatePassword = require('../lib/validate-password');
+const { validatePassword } = require('../lib/validate-password');
 const permissions = require('../services/permissions');
 const urlUtils = require('../../shared/url-utils').default;
 const { setIsRoles } = require('./role-utils');

package/core/server/services/automations/automations-api.js

@@ -78,7 +78,7 @@ const repository = (0, database_automations_repository_1.createDatabaseAutomatio
     fakeWaitHoursMultiplier: (0, fake_wait_hours_multiplier_1.parseFakeWaitHoursMultiplier)(config.get('automations:fakeWaitHoursMultiplier')),
 });
 async function browse() {
-    return await repository.browse();
+    return await repository.browse({ includeStats: true });
 }
 async function read(automationId) {
     const automation = await repository.getById(automationId);

package/core/server/services/automations/database-automations-repository.js

@@ -35,14 +35,16 @@ const messages = {
 const DEFAULT_EMAIL_DESIGN_SETTING_REFERENCE = constants_1.DEFAULT_EMAIL_DESIGN_SETTING_SLUG;
 function createDatabaseAutomationsRepository({ knex, fakeWaitHoursMultiplier, }) {
     return {
-        async browse() {
+        async browse({ includeStats }) {
             return await knex.transaction(async (trx) => {
                 await ensureDefaultAutomations(trx);
-                const rows = await loadAutomations(trx);
+                const data = includeStats
+                    ? (await loadAutomationsWithStats(trx)).map((row) => buildAutomationBrowseResult(row))
+                    : (await loadAutomations(trx)).map((row) => buildAutomationSummary(row));
                 return {
-                    data: rows.map((row) => buildAutomationBrowseResult(row)),
+                    data,
                     meta: {
-                        pagination: buildPagination(rows.length),
+                        pagination: buildPagination(data.length),
                     },
                 };
             });
@@ -671,6 +673,11 @@ async function loadAutomationBySlug(trx, slug) {
     return row ?? null;
 }
 async function loadAutomations(trx) {
+    return await trx('automations')
+        .select('id', 'slug', 'name', 'status', 'created_at', 'updated_at')
+        .orderBy('name');
+}
+async function loadAutomationsWithStats(trx) {
     const inProgressRuns = trx('automation_run_steps')
         .distinct('automation_run_id')
         .where('status', 'pending')

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

@@ -0,0 +1,37 @@
+# Newsletter Email Sending
+
+Newsletter Email Sending covers the preparation and submission of newsletter emails to the configured email provider.
+
+## Language
+
+**Sending status**:
+The state of a newsletter email's send: preparing, submitting, submitted, or failed. It is separate from any later provider-reported outcome.
+_Avoid_: Delivery status, provider outcome
+
+**Sending phase**:
+The part of a send, before it is submitted or fails, that progress and failures are reported against: preparing or submitting.
+_Avoid_: Step, stage
+
+**Preparing**:
+The sending phase while none of a newsletter email's recipient batches has started submitting, including before any sending work has begun.
+_Avoid_: Pending, queued
+
+**Submitting**:
+The sending phase once at least one recipient batch has started submitting to the configured email provider and the send has not yet been submitted or failed.
+_Avoid_: Sending, delivering
+
+**Sending progress**:
+The completed and total recipient counts for the current sending phase.
+_Avoid_: Delivery progress, expected count
+
+**Submitted**:
+Every batch of a newsletter email has been accepted by the configured email provider. Submission does not mean that recipients have received the email.
+_Avoid_: Sent, delivered
+
+**Failed**:
+Sending stopped with an error and will not continue without a retry.
+_Avoid_: Bounced, rejected
+
+**Failed during**:
+The sending phase a failed newsletter email was in when sending stopped.
+_Avoid_: Failure step

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

@@ -0,0 +1,42 @@
+# Email service
+
+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).
+
+## Sending status
+
+The sending status served by the Admin API's `emails/:id/status` endpoint is
+derived on read. `sending-status.ts` owns the derivation from an email and its
+batches with their recipient counts; `SendingStatusService` reads those rows
+and `sending-status-serializers.ts` shapes the response. Submitted is terminal and the batch aggregation only
+describes a send that is still in progress or has failed, so submitted emails answer with the email's stored
+`email_count` as both completed and total; batch creation reconciles that
+column to the recipient rows it built. That also keeps reads of long-finished
+emails cheap, with no query over the batches or recipients. The endpoint is always available; Admin decides
+whether to poll it while a send is active.
+
+The phase is read from the batches: an email is submitting once any batch has
+left `pending`, and preparing otherwise. Batch statuses persist across
+attempts, so a retried email reports submitting with frozen progress while it
+waits for its job, and `failed_during` is the same derivation applied to a
+failed email.
+
+The rough ETA measures recent recipient throughput, including work completed by
+concurrent workers. It stays `null` until enough timing samples are available in
+the current phase and attempt, so short sends may finish without showing an ETA.
+Progress counts update independently of the estimate.
+
+The ETA is always `null` for failed emails and `0` once no work remains in the
+current phase. Batches that failed during the current attempt are not remaining
+work until the email is retried, so the ETA can reach `0` while completed is
+still below total. Consumers should key completion on the status, never the ETA.
+
+Ghost does not record when a sending attempt or phase started, so the ETA uses
+the email's `updated_at` as a proxy for the start of the current attempt: the
+sending job saves the email when it takes its status lock and, when the
+recipient count changed, again after creating batches; a retry or boot resume
+saves it when re-queuing the email. Batches completed before that timestamp
+belong to an earlier attempt and are left out of the rate window. The proxy
+only holds while nothing saves the Email model, or sets `emails.updated_at`
+through a raw update, while batches are being submitted.