@tryghost/limit-service 1.2.18 → 1.3.0

package/README.md

@@ -2,7 +2,7 @@
 This module is intended to hold **all of the logic** for testing if site:
 - would be over a given limit if they took an action (i.e. added one more thing, switched to a different limit)
 - if they are over a limit already
-- consistent error messages explaining why the limit has been reached 
+- consistent error messages explaining why the limit has been reached
 
 ## Install
 
@@ -25,7 +25,8 @@ const LimitService = require('@tryghost/limit-service');
 const limitService = new LimitService();
 
 // setup limit configuration
-// currently supported limit keys are: staff, members, customThemes, customIntegrations, uploads
+// currently supported limit keys are: staff, members, customThemes, customIntegrations, uploads,
+// limitStripeConnect, limitAnalytics, and limitActivityPub
 // all limit configs support custom "error" configuration that is a template string
 const limits = {
     // staff and member are "max" type of limits accepting "max" configuration
@@ -54,7 +55,7 @@ const limits = {
         error: 'Email sending has been temporarily disabled whilst your account is under review.'
     },
     // following is a "max periodic" type of configuration
-    // note if you use this configuration, the limit service has to also get a 
+    // note if you use this configuration, the limit service has to also get a
     // "subscription" parameter to work as expected
     // emails: {
     //     maxPeriodic: 42,
@@ -65,11 +66,14 @@ const limits = {
         max: 5000000,
         // formatting of the {{ max }} vairable is in MB, e.g: 5MB
         error: 'Your plan supports uploads of max size up to {{max}}. Please upgrade to reenable uploading.'
-    }
+    },
+    limitStripeConnect: {},
+    limitAnalytics: {},
+    limitActivityPub: {}
 };
 
 // This information is needed for the limit service to work with "max periodic" limits
-// The interval value has to be 'month' as thats the only interval that was needed for
+// The interval value has to be 'month' as that's the only interval that was needed for
 // current usecase
 // The startDate has to be in ISO 8601 format (https://en.wikipedia.org/wiki/ISO_8601)
 const subscription = {
@@ -154,15 +158,15 @@ db.transaction((transacting) => {
 
 ### Types of limits
 At the moment there are four different types of limits that limit service allows to define. These types are:
-1. `flag` - is an "on/off" switch for certain feature. Example usecase: "disable all emails". It's identified by a `disabled: true` property in the "limits" configuration.
-2. `max` - checks if the maximum amount of the resource has been used up.Example usecase: "disable creating a staff user when maximum of 5 has been reached". To configure this limit add `max: NUMBER` to the configuration. The limits that support max checks are: `members`, `staff`, and `customIntegrations`
+1. `flag` - is an "on/off" switch for certain feature. Example usecase: "disable all emails". It's identified by a `disabled: true` property in the "limits" configuration. It is possible to overwrite the limit by providing a `currentCountQuery` for it. This is useful in cases where we introduce new limits to existing plans and customers have already been using the feature affected by the limit. By providing a `currentCountQuery` that detects if the feature is already in use, we won't disable it.
+2. `max` - checks if the maximum amount of the resource has been used up.Example usecase: "disable creating a staff user when maximum of 5 has been reached". To configure this limit add `max: NUMBER` to the configuration. The limits that support max checks are: `members`, and `staff`
 3. `maxPeriodic` - it's a variation of `max` type with a difference that the check is done over certain period of time. Example usecase: "disable sending emails when the sent emails count has acceded a limit for last billing period". To enable this limit define `maxPeriodic: NUMBER` in the limit configuration and provide a subscription configuration when initializing the limit service instance. The subscription object comes as a separate parameter and has to contain two properties: `startDate` and `interval`, where `startDate` is a date in  ISO 8601 format and period is `'month'` (other values like `'year'` are not supported yet)
-4. `allowList` - checks if provided value is defined in configured "allowlist". Example usecase: "disable theme activation if it is not an official theme". To configure this limit define ` allowlist: ['VALUE_1', 'VALUE_2', 'VALUE_N']` property in the "limits" parameter. 
+4. `allowList` - checks if provided value is defined in configured "allowlist". Example usecase: "disable theme activation if it is not an official theme". To configure this limit define ` allowlist: ['VALUE_1', 'VALUE_2', 'VALUE_N']` property in the "limits" parameter.
 
 ### Supported limits
-There's a limited amount of limits that are supported by limit service. The are defined by "key" property name in the "config" module. List of currently supported limit names: `members`, `staff`, `customIntegrations`, `emails`, `customThemes`, `uploads`. 
+There's a limited amount of limits that are supported by limit service. The are defined by "key" property name in the "config" module. List of currently supported limit names: `members`, `staff`, `customIntegrations`, `emails`, `customThemes`, `uploads`, `limitStripeConnect`, `limitAnalytics`, and `limitActivityPub`.
 
-All limits can act as `flag` or `allowList` types. Only certain (`members`, `staff`, and`customIntegrations`) can have a `max` limit. Only `emails` currently supports the `maxPeriodic` type of limit.
+All limits can act as `flag` or `allowList` types. Only certain (`members`, `staff`) can have a `max` limit. Only `emails` currently supports the `maxPeriodic` type of limit.
 
 ### Frontend usage
 In case the limit check is run without direct access to the database you can override `currentCountQuery` functions for each "max" or "maxPeriodic" type of limit. An example usecase would be a frontend client running in a browser. A browser client can check the limit data through HTTP request and then provide that data to the limit service. Example code to do exactly that:
@@ -217,6 +221,6 @@ Follow the instructions for the top-level repo.
 
 
 
-# Copyright & License 
+# Copyright & License
 
 Copyright (c) 2013-2025 Ghost Foundation - Released under the [MIT license](LICENSE).

package/lib/config.js

@@ -45,16 +45,7 @@ module.exports = {
             return result.length;
         }
     },
-    customIntegrations: {
-        currentCountQuery: async (knex) => {
-            let result = await knex('integrations')
-                .count('id', {as: 'count'})
-                .whereNotIn('type', ['internal', 'builtin'])
-                .first();
-
-            return result.count;
-        }
-    },
+    customIntegrations: {},
     customThemes: {},
     uploads: {
         // NOTE: this function should not ever be used as for uploads we compare the size
@@ -64,5 +55,8 @@ module.exports = {
         // NOTE: the uploads limit is based on file sizes provided in Bytes
         //       a custom formatter is here for more user-friendly formatting when forming an error
         formatter: count => `${count / 1000000}MB`
-    }
+    },
+    limitStripeConnect: {},
+    limitAnalytics: {},
+    limitActivityPub: {}
 };

package/lib/limit.js

@@ -264,14 +264,17 @@ class FlagLimit extends Limit {
      * @param {Number} options.config.disabled - disabled/enabled flag for the limit
      * @param {String} options.config.error - error message to use when limit is reached
      * @param {String} options.helpLink - URL to the resource explaining how the limit works
+     * @param {Function} [options.config.currentCountQuery] - query checking the state that would be compared against the limit
      * @param {Object} [options.db] - instance of knex db connection that currentCountQuery can use to run state check through
      * @param {Object} options.errors - instance of errors compatible with GhostError errors (@tryghost/errors)
      */
     constructor({name, config, helpLink, db, errors}) {
         super({name, error: config.error || '', helpLink, db, errors});
+        const userFacingLimitName = lowerCase(name.replace(/^limit/, ''));
 
         this.disabled = config.disabled;
-        this.fallbackMessage = `Your plan does not support ${lowerCase(this.name)}. Please upgrade to enable ${lowerCase(this.name)}.`;
+        this.fallbackMessage = `Your plan does not support ${userFacingLimitName}. Please upgrade to enable ${userFacingLimitName}.`;
+        this.currentCountQueryFn = config?.currentCountQuery || null;
     }
 
     generateError() {
@@ -287,20 +290,59 @@ class FlagLimit extends Limit {
     }
 
     /**
-     * Flag limits are on/off so using a feature is always over the limit
+     * @param {Object} [options]
+     * @param {Object} [options.transacting] Transaction to run the count query on
+     * @returns {Promise<boolean>} - returns the current count of items that would be compared against the limit
      */
-    async errorIfWouldGoOverLimit() {
-        if (this.disabled) {
+    async currentCountQuery(options = {}) {
+        if (!this.currentCountQueryFn || typeof this.currentCountQueryFn !== 'function') {
+            return false;
+        }
+
+        return await this.currentCountQueryFn(options.transacting ?? this.db?.knex);
+    }
+
+    // As Flag limits are on/off, we won't check against max values.
+    // `errorIfWouldGoOverLimit` and `errorIfIsOverLimit` end up doing the same thing.
+    async _isOrWouldOverLimitError(options = {}) {
+        if (!this.disabled) {
+            return;
+        }
+
+        // If no currentCountQuery is provided, throw error when disabled
+        if (!this.currentCountQueryFn || typeof this.currentCountQueryFn !== 'function') {
             throw this.generateError();
         }
+
+        // If currentCountQuery is provided, check if feature is in use
+        const featureInUse = await this.currentCountQuery(options);
+
+        // Only throw error if feature is NOT in use (allowing grandfathering)
+        if (!featureInUse) {
+            throw this.generateError();
+        }
+    }
+
+    /**
+     * Flag limits are usually on/off so using a feature is always over the limit,
+     * unless the limit has a currentCountQuery function provided to check if the
+     * feature is in use. This is a use case for when we introduce a new limit and
+     * customers have already been using this feature. We don't want to take it
+     * away from them.
+     */
+    async errorIfWouldGoOverLimit(options = {}) {
+        await this._isOrWouldOverLimitError(options);
     }
 
     /**
      * Flag limits are on/off. They don't necessarily mean the limit wasn't possible to reach
-     * NOTE: this method should not be relied on as it's impossible to check the limit was surpassed!
+     * Exception: the limit has a currentCountQuery function provided to check if the
+     * feature is in use. This is a use case for when we introduce a new limit and
+     * customers have already been using this feature. We don't want to take it
+     * away from them.
      */
-    async errorIfIsOverLimit() {
-        return;
+    async errorIfIsOverLimit(options = {}) {
+        await this._isOrWouldOverLimitError(options);
     }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryghost/limit-service",
-  "version": "1.2.18",
+  "version": "1.3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/TryGhost/SDK.git",
@@ -27,12 +27,12 @@
     "c8": "10.1.3",
     "mocha": "11.2.2",
     "should": "13.2.3",
-    "sinon": "20.0.0"
+    "sinon": "21.0.0"
   },
   "dependencies": {
     "@tryghost/errors": "^1.2.26",
     "lodash": "^4.17.21",
     "luxon": "^1.26.0"
   },
-  "gitHead": "c38d4e08913528be6218aea4c25c9704f4c6981d"
+  "gitHead": "a4329bd0bf75c10a862bb1c8761b45a6b08c5c2a"
 }