ghost 5.115.0 → 5.116.0

package/core/server/services/slack-notifications/SlackNotifications.js

@@ -0,0 +1,211 @@
+const got = require('got');
+const validator = require('@tryghost/validator');
+const errors = require('@tryghost/errors');
+const ghostVersion = require('@tryghost/version');
+const moment = require('moment');
+
+/**
+ * @typedef {URL} webhookUrl
+ */
+
+/**
+ * @typedef {string} siteUrl
+ */
+
+/**
+ * @typedef {import('@tryghost/logging')} logging
+ */
+
+/**
+ * @typedef {import('./SlackNotificationsService').ISlackNotifications} ISlackNotifications
+ */
+
+/**
+ * @implements {ISlackNotifications}
+ */
+class SlackNotifications {
+    /** @type {URL} */
+    #webhookUrl;
+
+    /** @type {siteUrl} */
+    #siteUrl;
+
+    /** @type {logging} */
+    #logging;
+
+    /**
+     * @param {object} deps
+     * @param {URL} deps.webhookUrl
+     * @param {siteUrl} deps.siteUrl
+     * @param {logging} deps.logging
+     */
+    constructor(deps) {
+        this.#siteUrl = deps.siteUrl;
+        this.#webhookUrl = deps.webhookUrl;
+        this.#logging = deps.logging;
+    }
+
+    /**
+     * @param {object} eventData
+     * @param {import('@tryghost/milestones/lib/InMemoryMilestoneRepository').Milestone} eventData.milestone
+     * @param {object} [eventData.meta]
+     * @param {'import'|'email'|'skipped'|'initial'} [eventData.meta.reason]
+     * @param {number} [eventData.meta.currentValue]
+     *
+     * @returns {Promise<void>}
+     */
+    async notifyMilestoneReceived({milestone, meta}) {
+        if (meta?.reason === 'skipped' || meta?.reason === 'initial') {
+            return;
+        }
+        const hasImportedMembers = meta?.reason === 'import' ? 'has imported members' : null;
+        const lastEmailTooSoon = meta?.reason === 'email' ? 'last email too recent' : null;
+        const emailNotSentReason = hasImportedMembers || lastEmailTooSoon;
+        const milestoneTypePretty = milestone.type === 'arr' ? 'ARR' : 'Members';
+        const valueFormatted = this.#getFormattedAmount({amount: milestone.value, currency: milestone?.currency});
+        const emailSentText = milestone?.emailSentAt ? this.#getFormattedDate(milestone?.emailSentAt) : `no / ${emailNotSentReason}`;
+        const title = `:tada: ${milestoneTypePretty} Milestone ${valueFormatted} reached!`;
+
+        let valueSection;
+
+        if (milestone.type === 'arr') {
+            valueSection = {
+                type: 'section',
+                fields: [
+                    {
+                        type: 'mrkdwn',
+                        text: `*Milestone:*\n${valueFormatted}`
+                    }
+
+                ]
+            };
+
+            if (meta?.currentValue) {
+                valueSection.fields.push({
+                    type: 'mrkdwn',
+                    text: `*Current ARR:*\n${this.#getFormattedAmount({amount: meta.currentValue, currency: milestone?.currency})}`
+                });
+            }
+        } else {
+            valueSection = {
+                type: 'section',
+                fields: [
+                    {
+                        type: 'mrkdwn',
+                        text: `*Milestone:*\n${valueFormatted}`
+                    }
+                ]
+            };
+            if (meta?.currentValue) {
+                valueSection.fields.push({
+                    type: 'mrkdwn',
+                    text: `*Current Members:*\n${this.#getFormattedAmount({amount: meta.currentValue})}`
+                });
+            }
+        }
+
+        const blocks = [
+            {
+                type: 'header',
+                text: {
+                    type: 'plain_text',
+                    text: title,
+                    emoji: true
+                }
+            },
+            {
+                type: 'section',
+                text: {
+                    type: 'mrkdwn',
+                    text: `New *${milestoneTypePretty} Milestone* achieved for <${this.#siteUrl}|${this.#siteUrl}>`
+                }
+            },
+            {
+                type: 'divider'
+            },
+            valueSection,
+            {
+                type: 'section',
+                text: {
+                    type: 'mrkdwn',
+                    text: `*Email sent:*\n${emailSentText}`
+                }
+            }
+        ];
+
+        const slackData = {
+            unfurl_links: false,
+            username: 'Ghost Milestone Service',
+            attachments: [
+                {
+                    color: '#36a64f',
+                    blocks
+                }
+            ]
+        };
+
+        await this.send(slackData, this.#webhookUrl);
+    }
+
+    /**
+     *
+     * @param {object} slackData
+     * @param {URL} url
+     *
+     * @returns {Promise<any>}
+     */
+    async send(slackData, url) {
+        if ((!url || typeof url !== 'string') || !validator.isURL(url)) {
+            const err = new errors.InternalServerError({
+                message: 'URL empty or invalid.',
+                code: 'URL_MISSING_INVALID',
+                context: url
+            });
+
+            return this.#logging.error(err);
+        }
+
+        const requestOptions = {
+            body: JSON.stringify(slackData),
+            headers: {
+                'user-agent': 'Ghost/' + ghostVersion.original + ' (https://github.com/TryGhost/Ghost)'
+            }
+        };
+
+        if (process.env.NODE_ENV?.startsWith('test')) {
+            requestOptions.retry = 0;
+        }
+
+        return await got.post(url, requestOptions);
+    }
+
+    /**
+     * @param {object} options
+     * @param {number} options.amount
+     * @param {string} [options.currency]
+     *
+     * @returns {string}
+     */
+    #getFormattedAmount({amount = 0, currency}) {
+        if (!currency) {
+            return Intl.NumberFormat().format(amount);
+        }
+
+        return Intl.NumberFormat('en', {
+            style: 'currency',
+            currency,
+            currencyDisplay: 'symbol'
+        }).format(amount);
+    }
+
+    /**
+     * @param {string|Date} date
+     *
+     * @returns {string}
+     */
+    #getFormattedDate(date) {
+        return moment(date).format('D MMM YYYY');
+    }
+}
+
+module.exports = SlackNotifications;

package/core/server/services/slack-notifications/SlackNotificationsService.js

@@ -0,0 +1,90 @@
+const {MilestoneCreatedEvent} = require('@tryghost/milestones');
+
+/**
+ * @typedef {import('@tryghost/milestones/lib/InMemoryMilestoneRepository').Milestone} Milestone
+ */
+
+/**
+ * @typedef {object} meta
+ * @prop {'import'|'email'} [reason]
+ * @prop {number} [currentValue]
+ */
+
+/**
+ * @typedef {import('@tryghost/logging')} logging
+ */
+
+/**
+ * @typedef {object} ISlackNotifications
+ * @param {logging} logging
+ * @param {URL} siteUrl
+ * @param {URL} webhookUrl
+ * @prop {Object.<Milestone, ?meta>} notifyMilestoneReceived
+ * @prop {(slackData: object, url: URL) => Promise<void>} send
+ */
+
+/**
+ * @typedef {object} config
+ * @prop {boolean} isEnabled
+ * @prop {URL} webhookUrl
+ * @prop {number} minThreshold
+ */
+
+module.exports = class SlackNotificationsService {
+    /** @type {import('@tryghost/domain-events')} */
+    #DomainEvents;
+
+    /** @type {import('@tryghost/logging')} */
+    #logging;
+
+    /** @type {config} */
+    #config;
+
+    /** @type {ISlackNotifications} */
+    #slackNotifications;
+
+    /**
+     *
+     * @param {object} deps
+     * @param {import('@tryghost/domain-events')} deps.DomainEvents
+     * @param {config} deps.config
+     * @param {import('@tryghost/logging')} deps.logging
+     * @param {ISlackNotifications} deps.slackNotifications
+     */
+    constructor(deps) {
+        this.#DomainEvents = deps.DomainEvents;
+        this.#logging = deps.logging;
+        this.#config = deps.config;
+        this.#slackNotifications = deps.slackNotifications;
+    }
+
+    /**
+     *
+     * @param {MilestoneCreatedEvent} type
+     * @param {object} event
+     * @param {object} event.data
+     *
+     * @returns {Promise<void>}
+     */
+    async #handleEvent(type, event) {
+        if (
+            type === MilestoneCreatedEvent
+            && event.data.milestone
+            && this.#config.isEnabled
+            && this.#config.webhookUrl
+            && this.#config.minThreshold < event.data.milestone.value
+        ) {
+            try {
+                await this.#slackNotifications.notifyMilestoneReceived(event.data);
+            } catch (error) {
+                this.#logging.error(error);
+            }
+        }
+    }
+
+    subscribeEvents() {
+        this.#DomainEvents.subscribe(MilestoneCreatedEvent, async (event) => {
+            await this.#handleEvent(MilestoneCreatedEvent, event);
+        });
+    }
+};

package/core/server/services/slack-notifications/service.js

@@ -3,7 +3,7 @@ const config = require('../../../shared/config');
 const logging = require('@tryghost/logging');
 
 class SlackNotificationsServiceWrapper {
-    /** @type {import('@tryghost/slack-notifications/lib/SlackNotificationsService')} */
+    /** @type {import('./SlackNotificationsService')} */
     #api;
 
     /**
@@ -14,13 +14,11 @@ class SlackNotificationsServiceWrapper {
      * @param {URL} deps.webhookUrl
      * @param {number} deps.minThreshold
      *
-     * @returns {import('@tryghost/slack-notifications/lib/SlackNotificationsService')}
+     * @returns {import('./SlackNotificationsService')}
      */
     static create({siteUrl, isEnabled, webhookUrl, minThreshold}) {
-        const {
-            SlackNotificationsService,
-            SlackNotifications
-        } = require('@tryghost/slack-notifications');
+        const SlackNotificationsService = require('./SlackNotificationsService');
+        const SlackNotifications = require('./SlackNotifications');
 
         const slackNotifications = new SlackNotifications({
             webhookUrl,

package/core/server/services/stripe/README.md

@@ -0,0 +1,63 @@
+# Stripe Service
+This package contains code for Ghost's Stripe integration. It interacts with Stripe's API and handles webhooks.
+
+The main export of this package is the `StripeService` class. It includes a wrapper around the Stripe API and webhook handling logic. It is instantiated in Ghost's `core/server/services/stripe` service.
+
+## Stripe API
+The `StripeAPI` class is a wrapper around the Stripe API. It is used by the `StripeService` class to interact with Stripe's API.
+
+## Stripe Webhooks
+Ghost listens for Stripe webhooks to know when a customer has subscribed to a plan, when a subscription has been cancelled, when a payment has failed, etc.
+
+Things to keep in mind when working with Stripe webhooks:
+- Webhooks can arrive out of order. `checkout.session.completed` webhooks may arrive before or after `customer.subscription.created` webhooks.
+- Webhooks can be received and processed in parallel, so you should not rely on the order of the webhooks to determine the order of operations.
+- Operations in Stripe almost always produce multiple events, increasing the likelihood of race conditions.
+
+See Stripe's [Webhooks Guide](https://docs.stripe.com/webhooks) for more information.
+
+### Webhook Manager
+This class is responsible for registering the webhook endpoints with Stripe, so Stripe knows where to send the webhooks.
+
+### Webhook Controller
+This class is responsible for handling the webhook events. It accepts the webhook event payload and delegates it to the appropriate handler based on the event type.
+
+### Events
+The Webhook Controller listens for the following events:
+- `customer.subscription.deleted`
+- `customer.subscription.updated`
+- `customer.subscription.created`
+- `invoice.payment_succeeded`
+- `checkout.session.completed`
+
+
+## Stripe Flows
+
+### Checkout Session Flow: New Subscription
+```mermaid
+sequenceDiagram
+    actor Member as Member
+    participant Portal
+    participant Ghost
+    participant Stripe
+
+    Member->>Portal: Signs up for a paid plan
+    Portal->>Ghost: Create checkout session
+    Ghost->>Stripe: Create checkout session
+    Stripe-->>Ghost: Return session ID
+    Ghost-->>Portal: Return session ID
+    Portal->>Stripe: Redirect to checkout page
+    Note over Portal: Member enters payment details in Stripe's secure portal
+    Stripe-->>Portal: Redirect to success URL
+    
+    par Webhook Events
+        Stripe->>Ghost: customer.subscription.created
+        Ghost->>Ghost: Upsert member and subscription
+        Stripe->>Ghost: checkout.session.completed
+        Ghost->>Ghost: Upsert member and subscription
+        Stripe->>Ghost: customer.subscription.updated
+        Ghost->>Ghost: Upsert member and subscription
+        Stripe->>Ghost: invoice.payment_succeeded
+        Ghost->>Ghost: Record payment
+    end
+```