ghost 5.117.0 → 5.118.0

package/core/server/services/milestones/InMemoryMilestoneRepository.js

@@ -0,0 +1,119 @@
+/**
+ * @typedef {import('./Milestone')} Milestone
+ * @typedef {import('./MilestonesService').IMilestoneRepository} IMilestoneRepository
+ */
+
+/**
+ * @implements {IMilestoneRepository}
+ */
+module.exports = class InMemoryMilestoneRepository {
+    /** @type {Milestone[]} */
+    #store = [];
+
+    /** @type {Object.<string, true>} */
+    #ids = {};
+
+    /** @type {import('@tryghost/domain-events')} */
+    #DomainEvents;
+
+    /**
+     * @param {object} deps
+     * @param {import('@tryghost/domain-events')} deps.DomainEvents
+     */
+    constructor(deps) {
+        this.#DomainEvents = deps.DomainEvents;
+    }
+
+    /**
+     * @param {Milestone} milestone
+     *
+     * @returns {Promise<void>}
+     */
+    async save(milestone) {
+        if (this.#ids[milestone.id.toHexString()]) {
+            const existingIndex = this.#store.findIndex((item) => {
+                return item.id.equals(milestone.id);
+            });
+            this.#store.splice(existingIndex, 1, milestone);
+        } else {
+            this.#store.push(milestone);
+            this.#ids[milestone.id.toHexString()] = true;
+        }
+
+        for (const event of milestone.events) {
+            this.#DomainEvents.dispatch(event);
+        }
+    }
+
+    /**
+     * @param {'arr'|'members'} type
+     * @param {string} [currency]
+     *
+     * @returns {Promise<Milestone>}
+     */
+    async getLatestByType(type, currency = 'usd') {
+        const allMilestonesForType = await this.getAllByType(type, currency);
+        return allMilestonesForType?.[0];
+    }
+
+    /**
+     * @returns {Promise<Milestone>}
+     */
+    async getLastEmailSent() {
+        return this.#store
+            .filter(item => item.emailSentAt)
+            // sort by emailSentAt desc
+            .sort((a, b) => (b.emailSentAt.valueOf() - a.emailSentAt.valueOf()))
+            // if we end up with more values with the same datetime, pick the highest value
+            .sort((a, b) => b.value - a.value)[0];
+    }
+
+    /**
+     * @param {number} value
+     * @param {string} [currency]
+     *
+     * @returns {Promise<Milestone>}
+     */
+    async getByARR(value, currency = 'usd') {
+        // find a milestone of the ARR type by a given value
+        return this.#store.find((item) => {
+            return item.value === value && item.type === 'arr' && item.currency === currency;
+        });
+    }
+
+    /**
+     * @param {number} value
+     *
+     * @returns {Promise<Milestone>}
+     */
+    async getByCount(value) {
+        // find a milestone of the members type by a given value
+        return this.#store.find((item) => {
+            return item.value === value && item.type === 'members';
+        });
+    }
+
+    /**
+     * @param {'arr'|'members'} type
+     * @param {string} [currency]
+     *
+     * @returns {Promise<Milestone[]>}
+     */
+    async getAllByType(type, currency = 'usd') {
+        if (type === 'arr') {
+            return this.#store
+                .filter(item => item.type === type && item.currency === currency)
+                // sort by created at desc
+                .sort((a, b) => (b.createdAt.valueOf() - a.createdAt.valueOf()))
+                // sort by highest value
+                .sort((a, b) => b.value - a.value);
+        } else {
+            return this.#store
+                .filter(item => item.type === type)
+                // sort by created at desc
+                .sort((a, b) => (b.createdAt.valueOf() - a.createdAt.valueOf()))
+                // sort by highest value
+                .sort((a, b) => b.value - a.value);
+        }
+    }
+};

package/core/server/services/milestones/Milestone.js

@@ -0,0 +1,231 @@
+const ObjectID = require('bson-objectid').default;
+const {ValidationError} = require('@tryghost/errors');
+const MilestoneCreatedEvent = require('./MilestoneCreatedEvent');
+
+module.exports = class Milestone {
+    /** @type {Array} */
+    events = [];
+
+    /**
+     * @type {ObjectID}
+     */
+    #id;
+    get id() {
+        return this.#id;
+    }
+
+    /**
+     * @type {'arr'|'members'}
+     */
+    #type;
+    get type() {
+        return this.#type;
+    }
+
+    /** @type {number} */
+    #value;
+    get value() {
+        return this.#value;
+    }
+
+    /** @type {string} */
+    #currency;
+    get currency() {
+        return this.#currency;
+    }
+
+    /** @type {Date} */
+    #createdAt;
+    get createdAt() {
+        return this.#createdAt;
+    }
+
+    /** @type {Date|null} */
+    #emailSentAt;
+    get emailSentAt() {
+        return this.#emailSentAt;
+    }
+
+    toJSON() {
+        return {
+            id: this.id,
+            name: this.name,
+            type: this.type,
+            value: this.value,
+            currency: this.currency,
+            createdAt: this.createdAt,
+            emailSentAt: this.emailSentAt
+        };
+    }
+
+    /** @private */
+    constructor(data) {
+        this.#id = data.id;
+        this.#type = data.type;
+        this.#value = data.value;
+        this.#currency = data.currency;
+        this.#createdAt = data.createdAt;
+        this.#emailSentAt = data.emailSentAt;
+    }
+
+    /**
+     * @returns {string}
+     */
+    get name() {
+        if (this.type === 'arr') {
+            return `arr-${this.value}-${this.currency}`;
+        }
+        return `members-${this.value}`;
+    }
+
+    /**
+     * @param {any} data
+     * @returns {Promise<Milestone>}
+     */
+    static async create(data) {
+        /** @type ObjectID */
+        let id;
+        let isNew = false;
+        if (!data.id) {
+            isNew = true;
+            id = new ObjectID();
+        } else if (typeof data.id === 'string') {
+            id = ObjectID.createFromHexString(data.id);
+        } else if (data.id instanceof ObjectID) {
+            id = data.id;
+        } else {
+            throw new ValidationError({
+                message: 'Invalid ID provided for Milestone'
+            });
+        }
+
+        const type = validateType(data.type);
+        const currency = validateCurrency(type, data?.currency);
+        const value = validateValue(data.value);
+        const name = validateName(data.name, value, type, currency);
+        const emailSentAt = validateEmailSentAt(data);
+
+        /** @type Date */
+        let createdAt;
+        if (data.createdAt instanceof Date) {
+            createdAt = data.createdAt;
+        } else if (data.createdAt) {
+            createdAt = new Date(data.createdAt);
+            if (isNaN(createdAt.valueOf())) {
+                throw new ValidationError({
+                    message: 'Invalid Date'
+                });
+            }
+        } else {
+            createdAt = new Date();
+        }
+
+        const milestone = new Milestone({
+            id,
+            name,
+            type,
+            value,
+            currency,
+            createdAt,
+            emailSentAt
+        });
+
+        if (isNew) {
+            milestone.events.push(MilestoneCreatedEvent.create({milestone, meta: data?.meta}));
+        }
+
+        return milestone;
+    }
+};
+
+/**
+ *
+ * @param {number|null} value
+ *
+ * @returns {number}
+ */
+function validateValue(value) {
+    if (value === undefined || typeof value !== 'number') {
+        throw new ValidationError({
+            message: 'Invalid value'
+        });
+    }
+
+    return value;
+}
+
+/**
+ *
+ * @param {unknown} type
+ *
+ * @returns {'arr'|'members'}
+ */
+function validateType(type) {
+    if (type === 'arr') {
+        return 'arr';
+    }
+
+    return 'members';
+}
+
+/**
+ *
+ * @param {'arr'|'members'} type
+ * @param {string|null} currency
+ *
+ * @returns {string}
+ */
+function validateCurrency(type, currency) {
+    if (type === 'members') {
+        return null;
+    }
+
+    if (!currency || (currency && typeof currency !== 'string' || currency.length > 3)) {
+        return 'usd';
+    }
+
+    return currency;
+}
+
+/**
+ *
+ * @param {string} name
+ * @param {number} value
+ * @param {'arr'|'members'} type
+ * @param {string|null} currency
+ *
+ * @returns {string}
+ */
+function validateName(name, value, type, currency) {
+    if (!name || !name.match(/(arr|members)-\d*/i)) {
+        return type === 'arr' ? `${type}-${value}-${currency}` : `${type}-${value}`;
+    }
+
+    return name;
+}
+
+/**
+ *
+ * @param {object} data
+ * @param {Date|null} data.emailSentAt
+ *
+ * @returns {Date|null}
+ */
+function validateEmailSentAt(data) {
+    let emailSentAt;
+    if (data.emailSentAt instanceof Date) {
+        emailSentAt = data.emailSentAt;
+    } else if (data.emailSentAt) {
+        emailSentAt = new Date(data.emailSentAt);
+        if (isNaN(emailSentAt.valueOf())) {
+            throw new ValidationError({
+                message: 'Invalid Date'
+            });
+        }
+    } else {
+        emailSentAt = null;
+    }
+
+    return emailSentAt;
+}
+

package/core/server/services/milestones/MilestoneCreatedEvent.js

@@ -0,0 +1,22 @@
+/**
+ * @typedef {object} MilestoneCreatedEventData
+ */
+
+module.exports = class MilestoneCreatedEvent {
+    /**
+     * @param {MilestoneCreatedEventData} data
+     * @param {Date} timestamp
+     */
+    constructor(data, timestamp) {
+        this.data = data;
+        this.timestamp = timestamp;
+    }
+
+    /**
+     * @param {MilestoneCreatedEventData} data
+     * @param {Date} [timestamp]
+     */
+    static create(data, timestamp) {
+        return new MilestoneCreatedEvent(data, timestamp ?? new Date);
+    }
+};

package/core/server/services/milestones/MilestonesService.js

@@ -0,0 +1,327 @@
+const Milestone = require('./Milestone');
+
+/**
+ * @typedef {object} IMilestoneRepository
+ * @prop {(milestone: Milestone) => Promise<void>} save
+ * @prop {(arr: number, [currency]: string|null) => Promise<Milestone>} getByARR
+ * @prop {(count: number) => Promise<Milestone>} getByCount
+ * @prop {(type: 'arr'|'members', [currency]: string|null) => Promise<Milestone>} getLatestByType
+ * @prop {() => Promise<Milestone>} getLastEmailSent
+ * @prop {(type: 'arr'|'members', [currency]: string|null) => Promise<Milestone[]>} getAllByType
+ */
+
+/**
+ * @typedef {object} IQueries
+ * @prop {() => Promise<number>} getMembersCount
+ * @prop {() => Promise<object>} getARR
+ * @prop {() => Promise<boolean>} hasImportedMembersInPeriod
+ * @prop {() => Promise<string>} getDefaultCurrency
+ */
+
+/**
+ * @typedef {object} milestonesConfig
+ * @prop {Array<object>} milestonesConfig.arr
+ * @prop {string} milestonesConfig.arr.currency
+ * @prop {number[]} milestonesConfig.arr.values
+ * @prop {number[]} milestonesConfig.members
+ * @prop {number} milestonesConfig.minDaysSinceLastEmail
+ */
+
+module.exports = class MilestonesService {
+    /** @type {IMilestoneRepository} */
+    #repository;
+
+    /**
+     * @type {milestonesConfig} */
+    #milestonesConfig;
+
+    /** @type {IQueries} */
+    #queries;
+
+    /**
+     * @param {object} deps
+     * @param {IMilestoneRepository} deps.repository
+     * @param {milestonesConfig} deps.milestonesConfig
+     * @param {IQueries} deps.queries
+     */
+    constructor(deps) {
+        this.#milestonesConfig = deps.milestonesConfig;
+        this.#queries = deps.queries;
+        this.#repository = deps.repository;
+    }
+
+    /**
+     * @param {string} [currency]
+     *
+     * @returns {Promise<Milestone>}
+     */
+    async #getLatestArrMilestone(currency = 'usd') {
+        return this.#repository.getLatestByType('arr', currency);
+    }
+
+    /**
+     * @returns {Promise<Milestone>}
+     */
+    async #getLatestMembersCountMilestone() {
+        return this.#repository.getLatestByType('members', null);
+    }
+
+    /**
+     * @returns {Promise<string>}
+     */
+    async #getDefaultCurrency() {
+        return await this.#queries.getDefaultCurrency();
+    }
+
+    /**
+     * @param {object} milestone
+     * @param {'arr'|'members'} milestone.type
+     * @param {number} milestone.value
+     * @param {string} milestone.currency
+     *
+     * @returns {Promise<boolean>}
+     */
+    async #checkMilestoneExists(milestone) {
+        let foundExistingMilestone = false;
+        let existingMilestone = null;
+
+        if (milestone.type === 'arr') {
+            existingMilestone = await this.#repository.getByARR(milestone.value, milestone.currency) || false;
+        } else if (milestone.type === 'members') {
+            existingMilestone = await this.#repository.getByCount(milestone.value) || false;
+        }
+
+        foundExistingMilestone = existingMilestone ? true : false;
+
+        return foundExistingMilestone;
+    }
+
+    /**
+     * @param {object} milestone
+     * @param {'arr'|'members'} milestone.type
+     * @param {number} milestone.value
+     *
+     * @returns {Promise<Milestone>}
+     */
+    async #createMilestone(milestone) {
+        const newMilestone = await Milestone.create(milestone);
+
+        await this.#repository.save(newMilestone);
+        return newMilestone;
+    }
+
+    /**
+     *
+     * @param {number[]} goalValues
+     * @param {number} current
+     *
+     * @returns {number[]}
+     */
+    #getMatchedMilestones(goalValues, current) {
+        // return all achieved milestones and sort by value ascending
+        return goalValues.filter(value => current >= value)
+            .sort((a, b) => a - b);
+    }
+
+    /**
+     *
+     * @param {object} milestone
+     * @param {number} milestone.value
+     * @param {'arr'|'members'} milestone.type
+     * @param {object} milestone.meta
+     * @param {string|null} [milestone.currency]
+     * @param {Date|null} [milestone.emailSentAt]
+     *
+     * @returns {Promise<Milestone>}
+     */
+    async #saveMileStoneAndSendEmail(milestone) {
+        const {shouldSendEmail, reason} = await this.#shouldSendEmail();
+
+        if (shouldSendEmail) {
+            milestone.emailSentAt = new Date();
+        }
+
+        if (reason) {
+            milestone.meta.reason = reason;
+        }
+
+        return await this.#createMilestone(milestone);
+    }
+
+    /**
+     * @param {object} milestone
+     * @param {number} milestone.value
+     * @param {'arr'|'members'} milestone.type
+     * @param {object} milestone.meta
+     * @param {string|null} [milestone.currency]
+     * @param {Date|null} [milestone.emailSentAt]
+     *
+     * @returns {Promise<Milestone>}
+     */
+    async #saveMileStoneWithoutEmail(milestone) {
+        return await this.#createMilestone(milestone);
+    }
+
+    /**
+     * @returns {Promise<{shouldSendEmail: boolean, reason: string}>}
+     */
+    async #shouldSendEmail() {
+        let emailTooSoon = false;
+        let reason = null;
+        // Two cases in which we don't want to send an email
+        // 1. There has been an import of members within the last week
+        // 2. The last email has been sent less than two weeks ago
+        const lastMilestoneSent = await this.#repository.getLastEmailSent();
+
+        if (lastMilestoneSent) {
+            const differenceInTime = new Date().getTime() - new Date(lastMilestoneSent.emailSentAt).getTime();
+            const differenceInDays = differenceInTime / (1000 * 3600 * 24);
+
+            emailTooSoon = differenceInDays <= this.#milestonesConfig.minDaysSinceLastEmail;
+        }
+
+        const hasMembersImported = await this.#queries.hasImportedMembersInPeriod();
+        const shouldSendEmail = !emailTooSoon && !hasMembersImported;
+
+        if (!shouldSendEmail) {
+            reason = hasMembersImported ? 'import' : 'email';
+        }
+
+        return {shouldSendEmail, reason};
+    }
+
+    /**
+     * @returns {Promise<Milestone>}
+    */
+    async #runARRQueries() {
+        // Fetch the current data from queries
+        const currentARR = await this.#queries.getARR();
+        const defaultCurrency = await this.#getDefaultCurrency();
+
+        // Check the definitions in the milestonesConfig
+        const arrMilestoneSettings = this.#milestonesConfig.arr;
+        const supportedCurrencies = arrMilestoneSettings.map(setting => setting.currency);
+
+        // First check the currency matches
+        if (currentARR.length) {
+            const currentARRForCurrency = currentARR.filter(arr => arr.currency === defaultCurrency && supportedCurrencies.includes(defaultCurrency))[0];
+            const milestonesForCurrency = arrMilestoneSettings.filter(milestoneSetting => milestoneSetting.currency === defaultCurrency)[0];
+
+            if (milestonesForCurrency && currentARRForCurrency) {
+                // get all milestones that have been achieved
+                const achievedMilestones = this.#getMatchedMilestones(milestonesForCurrency.values, currentARRForCurrency.arr);
+
+                // check for previously achieved milestones. We do not send an email when no
+                // previous milestones exist
+                const allMilestonesForCurrency = await this.#repository.getAllByType('arr', defaultCurrency);
+                const isInitialRun = !allMilestonesForCurrency || allMilestonesForCurrency?.length === 0;
+                const highestAchievedMilestone = Math.max(...achievedMilestones);
+
+                if (achievedMilestones && achievedMilestones.length) {
+                    for await (const milestone of achievedMilestones) {
+                        // Fetch the latest milestone for this currency
+                        const latestMilestone = await this.#getLatestArrMilestone(defaultCurrency);
+
+                        // Ensure the milestone doesn't already exist
+                        const milestoneExists = await this.#checkMilestoneExists({value: milestone, type: 'arr', currency: defaultCurrency});
+
+                        if (!milestoneExists) {
+                            if (isInitialRun) {
+                                // No milestones have been saved yet, don't send an email
+                                // for the first initial run
+                                const meta = {
+                                    currentValue: currentARRForCurrency.arr,
+                                    reason: 'initial'
+                                };
+                                await this.#saveMileStoneWithoutEmail({value: milestone, type: 'arr', currency: defaultCurrency, meta});
+                            } else if ((latestMilestone && milestone <= latestMilestone?.value) || milestone < highestAchievedMilestone) {
+                                // The highest achieved milestone is higher than the current on hand.
+                                // Do not send an email, but save it.
+                                const meta = {
+                                    currentValue: currentARRForCurrency.arr,
+                                    reason: 'skipped'
+                                };
+                                await this.#saveMileStoneWithoutEmail({value: milestone, type: 'arr', currency: defaultCurrency, meta});
+                            } else if ((!latestMilestone || milestone > latestMilestone.value)) {
+                                const meta = {
+                                    currentValue: currentARRForCurrency.arr
+                                };
+                                await this.#saveMileStoneAndSendEmail({value: milestone, type: 'arr', currency: defaultCurrency, meta});
+                            }
+                        }
+                    }
+                }
+                return await this.#getLatestArrMilestone(defaultCurrency);
+            }
+        }
+    }
+
+    /**
+     * @returns {Promise<Milestone>}
+    */
+    async #runMemberQueries() {
+        // Fetch the current data
+        const membersCount = await this.#queries.getMembersCount();
+
+        // Check the definitions in the milestonesConfig
+        const membersMilestones = this.#milestonesConfig.members;
+
+        // get the closest milestone we're over now
+        let achievedMilestones = this.#getMatchedMilestones(membersMilestones, membersCount);
+
+        // check for previously achieved milestones. We do not send an email when no
+        // previous milestones exist
+        const allMembersMilestones = await this.#repository.getAllByType('members', null);
+        const isInitialRun = !allMembersMilestones || allMembersMilestones?.length === 0;
+        const highestAchievedMilestone = Math.max(...achievedMilestones);
+
+        if (achievedMilestones && achievedMilestones.length) {
+            for await (const milestone of achievedMilestones) {
+                // Fetch the latest achieved Members milestones
+                const latestMembersMilestone = await this.#getLatestMembersCountMilestone();
+
+                // Ensure the milestone doesn't already exist
+                const milestoneExists = await this.#checkMilestoneExists({value: milestone, type: 'members', currency: null});
+
+                if (!milestoneExists) {
+                    if (isInitialRun) {
+                        // No milestones have been saved yet, don't send an email
+                        // for the first initial run
+                        const meta = {
+                            currentValue: membersCount,
+                            reason: 'initial'
+                        };
+                        await this.#saveMileStoneWithoutEmail({value: milestone, type: 'members', meta});
+                    } else if ((latestMembersMilestone && milestone <= latestMembersMilestone?.value) || milestone < highestAchievedMilestone) {
+                        // The highest achieved milestone is higher than the current on hand.
+                        // Do not send an email, but save it.
+                        const meta = {
+                            currentValue: membersCount,
+                            reason: 'skipped'
+                        };
+                        await this.#saveMileStoneWithoutEmail({value: milestone, type: 'members', meta});
+                    } else if ((!latestMembersMilestone || milestone > latestMembersMilestone.value)) {
+                        const meta = {
+                            currentValue: membersCount
+                        };
+                        await this.#saveMileStoneAndSendEmail({value: milestone, type: 'members', meta});
+                    }
+                }
+            }
+            return await this.#getLatestMembersCountMilestone();
+        }
+    }
+
+    /**
+     * @param {'arr'|'members'} type
+     *
+     * @returns {Promise<Milestone>}
+    */
+    async checkMilestones(type) {
+        if (type === 'arr') {
+            return await this.#runARRQueries();
+        }
+
+        return await this.#runMemberQueries();
+    }
+};