ghost 6.60.0 → 6.61.0

package/core/server/services/stripe/services/checkout/allowed-countries.js

@@ -0,0 +1,267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STRIPE_ALLOWED_COUNTRIES = void 0;
+exports.isStripeAllowedCountry = isStripeAllowedCountry;
+/**
+ * The countries Stripe Checkout will accept in `shipping_address_collection`.
+ *
+ * Not a general list of countries. This is not a question about which places exist, it is
+ * a question about where this payment processor will ship, and only the processor's answer
+ * decides whether a session can be created at all. A general ISO list gets it wrong in both
+ * directions: it omits places Stripe accepts, and it includes the sanctioned countries
+ * Stripe refuses.
+ *
+ * Measured against the live API at the pinned version by `e2e/scripts/probe-stripe-constraints.ts`,
+ * not read from the SDK's `AllowedCountry` union, because that union is wrong: it omits
+ * `SD`, which the live API accepts. Every other code the union carries was confirmed
+ * accepted, so the union is a subset of this list rather than a different one — which is
+ * what the accompanying test holds it to, so a country Stripe adds cannot pass unnoticed.
+ *
+ * A code Stripe rejects fails the whole session create, which is a publisher who cannot
+ * sell. So this is checked when a publisher chooses a country rather than when a member
+ * tries to buy.
+ */
+exports.STRIPE_ALLOWED_COUNTRIES = [
+    'AC',
+    'AD',
+    'AE',
+    'AF',
+    'AG',
+    'AI',
+    'AL',
+    'AM',
+    'AO',
+    'AQ',
+    'AR',
+    'AT',
+    'AU',
+    'AW',
+    'AX',
+    'AZ',
+    'BA',
+    'BB',
+    'BD',
+    'BE',
+    'BF',
+    'BG',
+    'BH',
+    'BI',
+    'BJ',
+    'BL',
+    'BM',
+    'BN',
+    'BO',
+    'BQ',
+    'BR',
+    'BS',
+    'BT',
+    'BV',
+    'BW',
+    'BY',
+    'BZ',
+    'CA',
+    'CD',
+    'CF',
+    'CG',
+    'CH',
+    'CI',
+    'CK',
+    'CL',
+    'CM',
+    'CN',
+    'CO',
+    'CR',
+    'CV',
+    'CW',
+    'CY',
+    'CZ',
+    'DE',
+    'DJ',
+    'DK',
+    'DM',
+    'DO',
+    'DZ',
+    'EC',
+    'EE',
+    'EG',
+    'EH',
+    'ER',
+    'ES',
+    'ET',
+    'FI',
+    'FJ',
+    'FK',
+    'FO',
+    'FR',
+    'GA',
+    'GB',
+    'GD',
+    'GE',
+    'GF',
+    'GG',
+    'GH',
+    'GI',
+    'GL',
+    'GM',
+    'GN',
+    'GP',
+    'GQ',
+    'GR',
+    'GS',
+    'GT',
+    'GU',
+    'GW',
+    'GY',
+    'HK',
+    'HN',
+    'HR',
+    'HT',
+    'HU',
+    'ID',
+    'IE',
+    'IL',
+    'IM',
+    'IN',
+    'IO',
+    'IQ',
+    'IS',
+    'IT',
+    'JE',
+    'JM',
+    'JO',
+    'JP',
+    'KE',
+    'KG',
+    'KH',
+    'KI',
+    'KM',
+    'KN',
+    'KR',
+    'KW',
+    'KY',
+    'KZ',
+    'LA',
+    'LB',
+    'LC',
+    'LI',
+    'LK',
+    'LR',
+    'LS',
+    'LT',
+    'LU',
+    'LV',
+    'LY',
+    'MA',
+    'MC',
+    'MD',
+    'ME',
+    'MF',
+    'MG',
+    'MK',
+    'ML',
+    'MM',
+    'MN',
+    'MO',
+    'MQ',
+    'MR',
+    'MS',
+    'MT',
+    'MU',
+    'MV',
+    'MW',
+    'MX',
+    'MY',
+    'MZ',
+    'NA',
+    'NC',
+    'NE',
+    'NG',
+    'NI',
+    'NL',
+    'NO',
+    'NP',
+    'NR',
+    'NU',
+    'NZ',
+    'OM',
+    'PA',
+    'PE',
+    'PF',
+    'PG',
+    'PH',
+    'PK',
+    'PL',
+    'PM',
+    'PN',
+    'PR',
+    'PS',
+    'PT',
+    'PY',
+    'QA',
+    'RE',
+    'RO',
+    'RS',
+    'RU',
+    'RW',
+    'SA',
+    'SB',
+    'SC',
+    'SD',
+    'SE',
+    'SG',
+    'SH',
+    'SI',
+    'SJ',
+    'SK',
+    'SL',
+    'SM',
+    'SN',
+    'SO',
+    'SR',
+    'SS',
+    'ST',
+    'SV',
+    'SX',
+    'SZ',
+    'TA',
+    'TC',
+    'TD',
+    'TF',
+    'TG',
+    'TH',
+    'TJ',
+    'TK',
+    'TL',
+    'TM',
+    'TN',
+    'TO',
+    'TR',
+    'TT',
+    'TV',
+    'TW',
+    'TZ',
+    'UA',
+    'UG',
+    'US',
+    'UY',
+    'UZ',
+    'VA',
+    'VC',
+    'VE',
+    'VG',
+    'VN',
+    'VU',
+    'WF',
+    'WS',
+    'XK',
+    'YE',
+    'YT',
+    'ZA',
+    'ZM',
+    'ZW',
+    'ZZ',
+];
+const ALLOWED = new Set(exports.STRIPE_ALLOWED_COUNTRIES);
+function isStripeAllowedCountry(code) {
+    return ALLOWED.has(code);
+}

package/core/server/services/stripe/services/checkout/completed-session.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectedByPort = exports.CompletedSession = void 0;
+const zod_1 = require("zod");
+const field_ports_1 = require("./field-ports");
+/**
+ * What Ghost reads off a completed session.
+ *
+ * `shipping` is where the address lives at Ghost's pinned Stripe API version; later
+ * versions moved it to `collected_information.shipping_details`. An Event is an immutable
+ * snapshot rendered at the account's version, so nothing in a payload would warn us if
+ * that pin ever changed.
+ *
+ * A tax number is deliberately not read: Stripe keeps it against the customer it invoices
+ * and Ghost never stores one.
+ */
+const Collected = zod_1.z
+    .string()
+    .nullish()
+    .transform((given) => (given && given.trim() !== '' ? given : undefined));
+exports.CompletedSession = zod_1.z
+    .object({
+    custom_fields: zod_1.z
+        .array(zod_1.z
+        .object({
+        key: zod_1.z.string().nullish(),
+        text: zod_1.z.object({ value: Collected }).nullish(),
+    })
+        .nullable())
+        .nullish(),
+    shipping: zod_1.z
+        .object({
+        name: Collected,
+        address: zod_1.z.record(zod_1.z.string(), Collected).nullish(),
+    })
+        .nullish(),
+    customer_details: zod_1.z.object({ phone: Collected }).nullish(),
+})
+    .loose();
+/** Our address type needs at least one part; an empty value would erase what is there. */
+function addressValue(address) {
+    const value = Object.fromEntries(Object.entries(address ?? {}).filter((entry) => entry[1] !== undefined));
+    return Object.keys(value).length > 0 ? value : undefined;
+}
+const PORT_VALUES = {
+    // Stripe returns the recipient's name alongside the address rather than as part of it,
+    // while Ghost keeps a name and an address in two separate custom fields. So the name is
+    // carried back separately here, under its own name, to be routed to its own field.
+    shipping_name: (session) => session.shipping?.name,
+    shipping_address: (session) => addressValue(session.shipping?.address),
+    phone: (session) => session.customer_details?.phone,
+};
+/**
+ * Everything a completed checkout gives back, as a list of pairs: the name Stripe used for
+ * a value, and the value itself. Answers to questions and values Stripe collected on its
+ * own both come back this way, because both are saved by the same route afterwards.
+ *
+ * Order matters. The values Stripe collected come last, so that if a question's answer and
+ * a collected value are both saved into the same custom field, the collected value is the
+ * one the field ends up holding.
+ */
+exports.collectedByPort = exports.CompletedSession.transform((session) => {
+    const answers = (session.custom_fields ?? [])
+        .filter((field) => Boolean(field?.key && field.text?.value))
+        .map((field) => ({ port: field.key, value: field.text.value }));
+    const ports = field_ports_1.STRIPE_PORTS.map((port) => ({ port, value: PORT_VALUES[port](session) })).filter((entry) => entry.value !== undefined);
+    return [...answers, ...ports];
+});

package/core/server/services/stripe/services/checkout/field-ports.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * What Stripe Checkout will render, measured against the live API at Ghost's pinned
+ * version rather than read from the reference — which disagreed with the API in three of
+ * five probes, missing the field cap and the key format entirely. A wrong bound here fails
+ * the session create, which fails the checkout.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHECKOUT_ELIGIBLE_FIELD_TYPES = exports.MAX_CHECKOUT_LABEL_LENGTH = exports.MAX_CHECKOUT_CUSTOM_FIELDS = exports.STRIPE_PORT = exports.STRIPE_PORTS = void 0;
+exports.isStripePort = isStripePort;
+exports.isCheckoutEligible = isCheckoutEligible;
+/** The names Stripe returns values under, and the only ports a binding for it may use. */
+exports.STRIPE_PORTS = ['shipping_name', 'shipping_address', 'phone'];
+function isStripePort(key) {
+    return exports.STRIPE_PORTS.includes(key);
+}
+exports.STRIPE_PORT = {
+    shippingName: 'shipping_name',
+    shippingAddress: 'shipping_address',
+    phone: 'phone',
+};
+/** Stripe rejects a fourth. */
+exports.MAX_CHECKOUT_CUSTOM_FIELDS = 3;
+/** Stripe caps a custom label at 50, where a field name may be 191 — hence a question label. */
+exports.MAX_CHECKOUT_LABEL_LENGTH = 50;
+/**
+ * What Stripe Checkout can ask for. No `long_text`: its text input caps shorter than that
+ * type allows. No `address`: Stripe has no custom-field equivalent, so an address is
+ * collected through its own parameter instead.
+ */
+exports.CHECKOUT_ELIGIBLE_FIELD_TYPES = ['short_text'];
+function isCheckoutEligible(type) {
+    return exports.CHECKOUT_ELIGIBLE_FIELD_TYPES.includes(type);
+}

package/core/server/services/stripe/services/checkout/session-options.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripeCheckoutCollectionOptions = stripeCheckoutCollectionOptions;
+const logging_1 = __importDefault(require("@tryghost/logging"));
+const field_ports_1 = require("./field-ports");
+/** Keyed on the eligible types, so this and the configure-time rule cannot drift apart. */
+const QUESTION_TYPES = {
+    short_text: 'text',
+};
+function askable(question) {
+    if (!(0, field_ports_1.isCheckoutEligible)(question.type)) {
+        logging_1.default.warn({
+            event: { name: 'stripe.checkout.question_skipped' },
+            customFieldKey: question.key,
+            fieldType: question.type,
+            reason: 'unsupported_type',
+        }, 'Skipping a Stripe checkout question');
+        return false;
+    }
+    if (question.prompt.length > field_ports_1.MAX_CHECKOUT_LABEL_LENGTH) {
+        logging_1.default.warn({
+            event: { name: 'stripe.checkout.question_skipped' },
+            customFieldKey: question.key,
+            promptLength: question.prompt.length,
+            reason: 'label_too_long',
+        }, 'Skipping a Stripe checkout question');
+        return false;
+    }
+    return true;
+}
+/**
+ * Build the collection parameters for a checkout, or nothing at all.
+ *
+ * Returns an object with no keys when a tier asks for nothing, so a caller can spread it
+ * over its session options unconditionally and change nothing.
+ */
+function stripeCheckoutCollectionOptions(checkout) {
+    const options = {};
+    if (!checkout) {
+        return options;
+    }
+    const eligible = checkout.customFields.filter(askable);
+    const questions = eligible.slice(0, field_ports_1.MAX_CHECKOUT_CUSTOM_FIELDS);
+    if (questions.length < eligible.length) {
+        logging_1.default.warn({
+            event: { name: 'stripe.checkout.questions_trimmed' },
+            asked: questions.length,
+            configured: eligible.length,
+        }, 'Some Stripe checkout questions were not asked');
+    }
+    if (questions.length > 0) {
+        options.custom_fields = questions.map((question) => ({
+            // Ghost sends the custom field's own key as the question's identifier, and Stripe
+            // returns the buyer's answer labelled with that same key. Using it in both places
+            // means reading an answer is a direct lookup of the field it belongs to, with
+            // nothing in between that could map it to the wrong one.
+            key: question.key,
+            label: { type: 'custom', custom: question.prompt },
+            type: QUESTION_TYPES[question.type],
+            optional: question.optional,
+        }));
+    }
+    if (checkout.shipping) {
+        // The country list is what makes this reach Stripe at all. An empty
+        // `shipping_address_collection` form-encodes to nothing, so a request built that
+        // way carries no parameter and Stripe accepts it precisely because it was never
+        // asked to collect anything — which reads as success and collects no addresses.
+        //
+        // Defended again here rather than trusted from the settings screen: this is the
+        // checkout path, and a malformed configuration must cost the collection rather than
+        // throw inside a session build.
+        if (checkout.shipping.allowedCountries.length === 0) {
+            logging_1.default.warn({
+                event: { name: 'stripe.checkout.collection_skipped' },
+                port: 'shipping_address',
+                reason: 'no_allowed_countries',
+            }, 'Skipping a Stripe checkout collection');
+        }
+        else {
+            options.shipping_address_collection = {
+                allowed_countries: checkout.shipping.allowedCountries,
+            };
+        }
+    }
+    // Unioned with whatever automatic tax asks for. Both want the same thing, so a site
+    // running the 2024 tax beta keeps collecting and a site that asked for it starts.
+    if (checkout.taxNumber) {
+        options.tax_id_collection = { enabled: true };
+    }
+    if (checkout.phone) {
+        options.phone_number_collection = { enabled: true };
+    }
+    return options;
+}

package/core/server/services/stripe/services/webhook/checkout-session-event-service.js

@@ -2,6 +2,7 @@ const _ = require('lodash');
 const errors = require('@tryghost/errors');
 const logging = require('@tryghost/logging');
 const { canWelcomeEmailReplaceSignupPaidEmail } = require('../../../lib/member-signup-contexts');
+const { collectedByPort } = require('../checkout/completed-session');
 /** @typedef {import('../../../lib/member-signup-contexts').SignupContext} SignupContext */
 
 function isStripeMetadataTrue(value) {
@@ -422,6 +423,11 @@ module.exports = class CheckoutSessionEventService {
       }
     }
 
+    // After the subscription work, and deliberately not part of it: a value the member
+    // gave us for free must never be able to fail the webhook. A throw here would make
+    // Stripe retry the event and risk doing the payment work twice.
+    await this.writeCollectedFields(member.id, session);
+
     if (checkoutType !== 'upgrade') {
       const ghostSignupContext = /** @type {SignupContext | undefined} */ (
         session.metadata?.ghostSignupContext
@@ -440,4 +446,47 @@ module.exports = class CheckoutSessionEventService {
       }
     }
   }
+
+  /**
+   * This service knows how to read a completed Stripe session. It does not know, and must
+   * not know, which custom field any of those values belongs in — that is what a binding
+   * decides, so no field key appears anywhere in this code.
+   *
+   * Nothing here may be fatal: a throw fails the webhook, which makes Stripe retry it and
+   * risks doing the payment work twice.
+   *
+   * @param {string} memberId
+   * @param {import('stripe').Stripe.Checkout.Session} session
+   */
+  async writeCollectedFields(memberId, session) {
+    // Stamped at create time. A session predating this feature carries none. Read
+    // outside the try so a failure below can name the tier whose answers were lost.
+    const tierId = session.metadata?.ghostTierId;
+
+    try {
+      if (!this.deps.labsService.isSet('membersCustomFields')) {
+        return;
+      }
+
+      if (!tierId) {
+        return;
+      }
+
+      await this.deps.customFieldBindings.writeCollected(
+        memberId,
+        tierId,
+        collectedByPort.parse(session),
+      );
+    } catch (err) {
+      logging.error(
+        {
+          event: { name: 'stripe_checkout.collected_fields.write_failed' },
+          err,
+          memberId,
+          tierId,
+        },
+        'Failed to store the fields a checkout collected',
+      );
+    }
+  }
 };

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

@@ -3,6 +3,7 @@ const debug = require('@tryghost/debug')('stripe');
 const ghostConfig = require('../../../shared/config');
 const stripe = require('stripe');
 const i18n = require('../i18n');
+const { stripeCheckoutCollectionOptions } = require('./services/checkout/session-options');
 
 /* Stripe has the following rate limits:
  *  - For most APIs, 100 read requests per second in live mode, 25 read requests per second in test mode
@@ -556,6 +557,8 @@ module.exports = class StripeAPI {
    * @param {string} options.customerEmail
    * @param {number} options.trialDays
    * @param {string} [options.coupon]
+   * @param {import('../tier-checkout-config').ResolvedCheckout} [options.checkout] What
+   *   the tier's checkout asks for beyond the payment. Absent, or empty, adds nothing.
    *
    * @returns {Promise<ICheckoutSession>}
    */
@@ -636,6 +639,32 @@ module.exports = class StripeAPI {
       hasCustomer: Boolean(customerId),
     });
 
+    // Applied after automatic tax so the two agree about `tax_id_collection`: both ask
+    // for the same thing, and a site with either reason to collect gets it. Nothing is
+    // added for a tier that has configured nothing, so an unconfigured site's request
+    // is unchanged.
+    Object.assign(stripeSessionOptions, stripeCheckoutCollectionOptions(options.checkout));
+
+    // Stripe refuses to collect a tax id for a customer it may not rename:
+    //
+    //   Tax ID collection requires updating business name on the customer. To enable tax
+    //   ID collection for an existing customer, please set `customer_update[name]`.
+    //
+    // Measured against the live API rather than read — `pnpm --filter @tryghost/e2e
+    // stripe:probe` — because the same probe shows shipping and phone collection need no
+    // such thing. Every signed-in checkout carries a customer, so without this a tier
+    // that collects a tax number cannot be bought by an existing member.
+    //
+    // Merged rather than assigned: automatic tax sets this too, and whichever ran first
+    // must not lose its keys. Still never set without a customer, which is the shape
+    // that took the tax beta down.
+    if (stripeSessionOptions.tax_id_collection && customerId) {
+      stripeSessionOptions.customer_update = {
+        ...stripeSessionOptions.customer_update,
+        name: 'auto',
+      };
+    }
+
     const session = await this._stripe.checkout.sessions.create(stripeSessionOptions);
 
     return session;

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

@@ -10,6 +10,7 @@ const InvoiceEventService = require('./services/webhook/invoice-event-service');
 const CheckoutSessionEventService = require('./services/webhook/checkout-session-event-service');
 const ChargeRefundedEventService = require('./services/webhook/charge-refunded-event-service');
 const memberWelcomeEmailService = require('../member-welcome-emails/service');
+const customFields = require('../members-custom-fields');
 
 /**
  * @typedef {object} IStripeServiceConfig
@@ -133,6 +134,12 @@ module.exports = class StripeService {
         memberWelcomeEmailService.init();
         return memberWelcomeEmailService.api.isMemberWelcomeEmailActive('paid');
       },
+      labsService: labs,
+      // A getter because the custom field services are built during boot: reading the
+      // binding at construction would capture the empty value it had beforehand.
+      get customFieldBindings() {
+        return customFields.bindings;
+      },
     });
 
     const chargeRefundedEventService = new ChargeRefundedEventService({