From c298db912c64c1beb59a825c0d023d5587465f04 Mon Sep 17 00:00:00 2001
From: Daniel Lockyer <hi@daniellockyer.com>
Date: Tue, 7 May 2024 08:36:44 +0200
Subject: [PATCH] Added JSDoc types for API controllers

- this adds a simple set of types to the @tryghost/api-framework
  package that should describe all of the keys available on a
  controller, and then rolls it out to all API controllers
- unfortunately, due to https://github.com/microsoft/TypeScript/issues/47107, we have
  to split apart `module.exports` into a variable assignment in order for type-checking
  to be done
- the main benefit of this is that `frame` is now typed, and editors understand what keys
  are available, so intellisense works properly
---
 ghost/api-framework/index.js                  | 26 +++++++++++++++++++
 .../core/core/server/api/endpoints/actions.js |  5 +++-
 .../server/api/endpoints/announcements.js     |  5 +++-
 .../server/api/endpoints/authentication.js    |  5 +++-
 .../server/api/endpoints/authors-public.js    |  5 +++-
 .../api/endpoints/collections-public.js       |  5 +++-
 .../core/server/api/endpoints/collections.js  |  5 +++-
 .../server/api/endpoints/comments-members.js  |  5 +++-
 .../core/server/api/endpoints/comments.js     |  5 +++-
 .../core/core/server/api/endpoints/config.js  |  5 +++-
 .../api/endpoints/custom-theme-settings.js    |  5 +++-
 ghost/core/core/server/api/endpoints/db.js    |  5 +++-
 .../core/server/api/endpoints/email-post.js   |  5 +++-
 .../server/api/endpoints/email-previews.js    |  5 +++-
 .../core/core/server/api/endpoints/emails.js  |  5 +++-
 .../core/core/server/api/endpoints/explore.js |  5 +++-
 .../server/api/endpoints/feedback-members.js  |  5 +++-
 ghost/core/core/server/api/endpoints/files.js |  5 +++-
 .../core/server/api/endpoints/identities.js   |  5 +++-
 .../core/core/server/api/endpoints/images.js  |  5 +++-
 .../api/endpoints/incoming-recommendations.js |  5 +++-
 .../core/server/api/endpoints/integrations.js |  5 +++-
 .../core/core/server/api/endpoints/invites.js |  5 +++-
 .../core/core/server/api/endpoints/labels.js  |  5 +++-
 ghost/core/core/server/api/endpoints/links.js |  5 +++-
 .../core/server/api/endpoints/mail-events.js  |  5 +++-
 ghost/core/core/server/api/endpoints/mail.js  |  5 +++-
 ghost/core/core/server/api/endpoints/media.js |  5 +++-
 .../api/endpoints/member-signin-urls.js       |  6 ++++-
 .../api/endpoints/members-stripe-connect.js   |  5 +++-
 .../core/core/server/api/endpoints/members.js |  5 +++-
 .../core/server/api/endpoints/mentions.js     |  5 +++-
 .../api/endpoints/newsletters-public.js       |  5 +++-
 .../core/server/api/endpoints/newsletters.js  |  5 +++-
 .../server/api/endpoints/notifications.js     |  5 +++-
 .../core/core/server/api/endpoints/oembed.js  |  5 +++-
 .../server/api/endpoints/offers-public.js     |  5 +++-
 .../core/core/server/api/endpoints/offers.js  |  5 +++-
 .../core/server/api/endpoints/pages-public.js |  5 +++-
 ghost/core/core/server/api/endpoints/pages.js |  5 +++-
 .../core/server/api/endpoints/posts-public.js | 12 ++++++++-
 ghost/core/core/server/api/endpoints/posts.js |  5 +++-
 .../core/server/api/endpoints/previews.js     |  5 +++-
 .../api/endpoints/recommendations-public.js   |  5 +++-
 .../server/api/endpoints/recommendations.js   |  5 +++-
 .../core/server/api/endpoints/redirects.js    |  5 +++-
 ghost/core/core/server/api/endpoints/roles.js |  5 +++-
 .../core/server/api/endpoints/schedules.js    |  6 +++--
 .../core/core/server/api/endpoints/session.js |  5 ++--
 .../server/api/endpoints/settings-public.js   |  5 +++-
 .../core/server/api/endpoints/settings.js     |  5 +++-
 ghost/core/core/server/api/endpoints/site.js  |  5 ++--
 ghost/core/core/server/api/endpoints/slack.js |  5 +++-
 ghost/core/core/server/api/endpoints/slugs.js |  5 +++-
 .../core/server/api/endpoints/snippets.js     |  5 +++-
 ghost/core/core/server/api/endpoints/stats.js |  5 +++-
 .../core/server/api/endpoints/tags-public.js  |  5 +++-
 ghost/core/core/server/api/endpoints/tags.js  |  5 +++-
 .../core/core/server/api/endpoints/themes.js  |  5 +++-
 .../core/server/api/endpoints/tiers-public.js |  5 +++-
 ghost/core/core/server/api/endpoints/tiers.js |  5 +++-
 ghost/core/core/server/api/endpoints/users.js |  5 +++-
 .../core/server/api/endpoints/webhooks.js     |  5 +++-
 63 files changed, 280 insertions(+), 65 deletions(-)

diff --git a/ghost/api-framework/index.js b/ghost/api-framework/index.js
index 373c844ba2..2fd7fa32f4 100644
--- a/ghost/api-framework/index.js
+++ b/ghost/api-framework/index.js
@@ -1 +1,27 @@
+/** @typedef {object} PermissionsObject */
+/** @typedef {boolean} PermissionsBoolean */
+
+/** @typedef {number} StatusCodeNumber */
+/** @typedef {(result: any) => number} StatusCodeFunction */
+
+/** @typedef {object} ValidationObject */
+
+/**
+ * @typedef {object} ControllerMethod
+ * @property {object} headers
+ * @property {PermissionsBoolean | PermissionsObject} permissions
+ * @property {string[]} [options]
+ * @property {ValidationObject} [validation]
+ * @property {string[]} [data]
+ * @property {StatusCodeFunction | StatusCodeNumber} [statusCode]
+ * @property {object} [response]
+ * @property {function} [cache]
+ * @property {(frame: import('./lib/Frame')) => object} [generateCacheKeyData]
+ * @property {(frame: import('./lib/Frame')) => any} query
+ */
+
+/**
+ * @typedef {Record<string, ControllerMethod | string> & Record<'docName', string>} Controller
+ */
+
 module.exports = require('./lib/api-framework');
diff --git a/ghost/core/core/server/api/endpoints/actions.js b/ghost/core/core/server/api/endpoints/actions.js
index db4149b222..49d7b3f3c7 100644
--- a/ghost/core/core/server/api/endpoints/actions.js
+++ b/ghost/core/core/server/api/endpoints/actions.js
@@ -1,6 +1,7 @@
 const models = require('../../models');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'actions',
 
     browse: {
@@ -20,3 +21,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/announcements.js b/ghost/core/core/server/api/endpoints/announcements.js
index 35f1fe3f40..2a6bbdfd85 100644
--- a/ghost/core/core/server/api/endpoints/announcements.js
+++ b/ghost/core/core/server/api/endpoints/announcements.js
@@ -1,6 +1,7 @@
 const announcementBarSettings = require('../../services/announcement-bar-service');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'announcement',
 
     browse: {
@@ -13,3 +14,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/authentication.js b/ghost/core/core/server/api/endpoints/authentication.js
index 2969b172cc..abfbd78253 100644
--- a/ghost/core/core/server/api/endpoints/authentication.js
+++ b/ghost/core/core/server/api/endpoints/authentication.js
@@ -18,7 +18,8 @@ const messages = {
     notTheBlogOwner: 'You are not the site owner.'
 };
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'authentication',
 
     setup: {
@@ -250,3 +251,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/authors-public.js b/ghost/core/core/server/api/endpoints/authors-public.js
index 408fd64f48..61dc3d4e3f 100644
--- a/ghost/core/core/server/api/endpoints/authors-public.js
+++ b/ghost/core/core/server/api/endpoints/authors-public.js
@@ -19,7 +19,8 @@ const rejectPrivateFieldsTransformer = input => mapQuery(input, function (value,
     };
 });
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'authors',
 
     browse: {
@@ -92,3 +93,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/collections-public.js b/ghost/core/core/server/api/endpoints/collections-public.js
index 67a214540a..b04d7a8c11 100644
--- a/ghost/core/core/server/api/endpoints/collections-public.js
+++ b/ghost/core/core/server/api/endpoints/collections-public.js
@@ -6,7 +6,8 @@ const messages = {
     collectionNotFound: 'Collection not found.'
 };
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'collections',
 
     readBySlug: {
@@ -51,3 +52,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/collections.js b/ghost/core/core/server/api/endpoints/collections.js
index 7885775bb1..5c1ea7c5b1 100644
--- a/ghost/core/core/server/api/endpoints/collections.js
+++ b/ghost/core/core/server/api/endpoints/collections.js
@@ -6,7 +6,8 @@ const messages = {
     collectionNotFound: 'Collection not found.'
 };
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'collections',
 
     browse: {
@@ -136,3 +137,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/comments-members.js b/ghost/core/core/server/api/endpoints/comments-members.js
index 2bbe91d7e0..bcbd63013d 100644
--- a/ghost/core/core/server/api/endpoints/comments-members.js
+++ b/ghost/core/core/server/api/endpoints/comments-members.js
@@ -2,7 +2,8 @@ const commentsService = require('../../services/comments');
 const ALLOWED_INCLUDES = ['member', 'replies', 'replies.member', 'replies.count.likes', 'replies.liked', 'count.replies', 'count.likes', 'liked', 'post', 'parent'];
 const UNSAFE_ATTRS = ['status'];
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'comments',
 
     browse: {
@@ -207,3 +208,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/comments.js b/ghost/core/core/server/api/endpoints/comments.js
index 846dbb9c74..19a103b21d 100644
--- a/ghost/core/core/server/api/endpoints/comments.js
+++ b/ghost/core/core/server/api/endpoints/comments.js
@@ -1,6 +1,7 @@
 const models = require('../../models');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'comments',
 
     edit: {
@@ -26,3 +27,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/config.js b/ghost/core/core/server/api/endpoints/config.js
index 8767a3848c..62c120b1c0 100644
--- a/ghost/core/core/server/api/endpoints/config.js
+++ b/ghost/core/core/server/api/endpoints/config.js
@@ -1,6 +1,7 @@
 const publicConfig = require('../../services/public-config');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'config',
 
     read: {
@@ -13,3 +14,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/custom-theme-settings.js b/ghost/core/core/server/api/endpoints/custom-theme-settings.js
index d6c70ddcc3..f0c99ee884 100644
--- a/ghost/core/core/server/api/endpoints/custom-theme-settings.js
+++ b/ghost/core/core/server/api/endpoints/custom-theme-settings.js
@@ -1,6 +1,7 @@
 const customThemeSettingsService = require('../../services/custom-theme-settings');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'custom_theme_settings',
 
     browse: {
@@ -23,3 +24,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/db.js b/ghost/core/core/server/api/endpoints/db.js
index ce666cc770..14665fa4cb 100644
--- a/ghost/core/core/server/api/endpoints/db.js
+++ b/ghost/core/core/server/api/endpoints/db.js
@@ -8,7 +8,8 @@ const {pool} = require('@tryghost/promise');
 const models = require('../../models');
 const settingsCache = require('../../../shared/settings-cache');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'db',
 
     backupContent: {
@@ -173,3 +174,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/email-post.js b/ghost/core/core/server/api/endpoints/email-post.js
index a2740d6a0e..a78bc8a402 100644
--- a/ghost/core/core/server/api/endpoints/email-post.js
+++ b/ghost/core/core/server/api/endpoints/email-post.js
@@ -7,7 +7,8 @@ const messages = {
     postNotFound: 'Post not found.'
 };
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'email_post',
 
     read: {
@@ -46,3 +47,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/email-previews.js b/ghost/core/core/server/api/endpoints/email-previews.js
index 0fa9d974c4..9f187d4d3b 100644
--- a/ghost/core/core/server/api/endpoints/email-previews.js
+++ b/ghost/core/core/server/api/endpoints/email-previews.js
@@ -1,6 +1,7 @@
 const emailService = require('../../services/email-service');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'email_previews',
 
     read: {
@@ -47,3 +48,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/emails.js b/ghost/core/core/server/api/endpoints/emails.js
index 6cfca55363..1be0c3b5d9 100644
--- a/ghost/core/core/server/api/endpoints/emails.js
+++ b/ghost/core/core/server/api/endpoints/emails.js
@@ -12,7 +12,8 @@ const messages = {
 const allowedBatchIncludes = ['count.recipients'];
 const allowedFailureIncludes = ['member', 'email_recipient'];
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'emails',
 
     browse: {
@@ -180,3 +181,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/explore.js b/ghost/core/core/server/api/endpoints/explore.js
index 83fd0c8bee..aa9c380c4d 100644
--- a/ghost/core/core/server/api/endpoints/explore.js
+++ b/ghost/core/core/server/api/endpoints/explore.js
@@ -1,6 +1,7 @@
 const exploreService = require('../../services/explore');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'explore',
 
     read: {
@@ -13,3 +14,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/feedback-members.js b/ghost/core/core/server/api/endpoints/feedback-members.js
index 0113e18db4..46f6a20ecd 100644
--- a/ghost/core/core/server/api/endpoints/feedback-members.js
+++ b/ghost/core/core/server/api/endpoints/feedback-members.js
@@ -1,6 +1,7 @@
 const feedbackService = require('../../services/audience-feedback');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'feedback',
 
     add: {
@@ -24,3 +25,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/files.js b/ghost/core/core/server/api/endpoints/files.js
index dbc6b70301..72ca1f7b0c 100644
--- a/ghost/core/core/server/api/endpoints/files.js
+++ b/ghost/core/core/server/api/endpoints/files.js
@@ -1,6 +1,7 @@
 const storage = require('../../adapters/storage');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'files',
     upload: {
         statusCode: 201,
@@ -20,3 +21,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/identities.js b/ghost/core/core/server/api/endpoints/identities.js
index 67b2020361..ad0c3a15ca 100644
--- a/ghost/core/core/server/api/endpoints/identities.js
+++ b/ghost/core/core/server/api/endpoints/identities.js
@@ -23,7 +23,8 @@ const sign = async (claims, options) => {
     }, options));
 };
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'identities',
     read: {
         headers: {
@@ -36,3 +37,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/images.js b/ghost/core/core/server/api/endpoints/images.js
index 140e88bd1e..b95dedc0ab 100644
--- a/ghost/core/core/server/api/endpoints/images.js
+++ b/ghost/core/core/server/api/endpoints/images.js
@@ -6,7 +6,8 @@ const imageTransform = require('@tryghost/image-transform');
 const storage = require('../../adapters/storage');
 const config = require('../../../shared/config');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'images',
     upload: {
         statusCode: 201,
@@ -80,3 +81,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/incoming-recommendations.js b/ghost/core/core/server/api/endpoints/incoming-recommendations.js
index cb5d38f52f..66968951a2 100644
--- a/ghost/core/core/server/api/endpoints/incoming-recommendations.js
+++ b/ghost/core/core/server/api/endpoints/incoming-recommendations.js
@@ -1,6 +1,7 @@
 const recommendations = require('../../services/recommendations');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'recommendations',
 
     browse: {
@@ -18,3 +19,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/integrations.js b/ghost/core/core/server/api/endpoints/integrations.js
index 44abcc5d65..6cc2025113 100644
--- a/ghost/core/core/server/api/endpoints/integrations.js
+++ b/ghost/core/core/server/api/endpoints/integrations.js
@@ -12,7 +12,8 @@ const integrationsService = getIntegrationsServiceInstance({
     ApiKeyModel: models.ApiKey
 });
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'integrations',
     browse: {
         headers: {
@@ -163,3 +164,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/invites.js b/ghost/core/core/server/api/endpoints/invites.js
index 0b87ccb284..43a9532da2 100644
--- a/ghost/core/core/server/api/endpoints/invites.js
+++ b/ghost/core/core/server/api/endpoints/invites.js
@@ -10,7 +10,8 @@ const messages = {
     inviteNotFound: 'Invite not found.'
 };
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'invites',
 
     browse: {
@@ -127,3 +128,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/labels.js b/ghost/core/core/server/api/endpoints/labels.js
index 56b10f7637..9ac46efbab 100644
--- a/ghost/core/core/server/api/endpoints/labels.js
+++ b/ghost/core/core/server/api/endpoints/labels.js
@@ -9,7 +9,8 @@ const messages = {
 
 const ALLOWED_INCLUDES = ['count.members'];
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'labels',
 
     browse: {
@@ -161,3 +162,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/links.js b/ghost/core/core/server/api/endpoints/links.js
index 2c05dd2a11..8a11d4e330 100644
--- a/ghost/core/core/server/api/endpoints/links.js
+++ b/ghost/core/core/server/api/endpoints/links.js
@@ -1,7 +1,8 @@
 const linkTrackingService = require('../../services/link-tracking');
 const INVALIDATE_ALL_REDIRECTS = '/r/*';
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'links',
     browse: {
         headers: {
@@ -59,3 +60,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/mail-events.js b/ghost/core/core/server/api/endpoints/mail-events.js
index 7e44595825..2f80d66e14 100644
--- a/ghost/core/core/server/api/endpoints/mail-events.js
+++ b/ghost/core/core/server/api/endpoints/mail-events.js
@@ -1,6 +1,7 @@
 const mailEvents = require('../../services/mail-events');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'mail_events',
     add: {
         headers: {
@@ -12,3 +13,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/mail.js b/ghost/core/core/server/api/endpoints/mail.js
index c917c2f003..74f4765533 100644
--- a/ghost/core/core/server/api/endpoints/mail.js
+++ b/ghost/core/core/server/api/endpoints/mail.js
@@ -35,7 +35,8 @@ _private.sendMail = (object) => {
     });
 };
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'mail',
 
     send: {
@@ -66,3 +67,5 @@ module.exports = {
             });
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/media.js b/ghost/core/core/server/api/endpoints/media.js
index eedcc1e777..a94124ade4 100644
--- a/ghost/core/core/server/api/endpoints/media.js
+++ b/ghost/core/core/server/api/endpoints/media.js
@@ -1,7 +1,8 @@
 const path = require('path');
 const storage = require('../../adapters/storage');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'media',
     upload: {
         statusCode: 201,
@@ -47,3 +48,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/member-signin-urls.js b/ghost/core/core/server/api/endpoints/member-signin-urls.js
index 738ccf1281..b5f0d517e3 100644
--- a/ghost/core/core/server/api/endpoints/member-signin-urls.js
+++ b/ghost/core/core/server/api/endpoints/member-signin-urls.js
@@ -6,8 +6,10 @@ const messages = {
     memberNotFound: 'Member not found.'
 };
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'member_signin_urls',
+
     read: {
         headers: {
             cacheInvalidate: false
@@ -34,3 +36,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/members-stripe-connect.js b/ghost/core/core/server/api/endpoints/members-stripe-connect.js
index a8d6857202..011f33f903 100644
--- a/ghost/core/core/server/api/endpoints/members-stripe-connect.js
+++ b/ghost/core/core/server/api/endpoints/members-stripe-connect.js
@@ -1,6 +1,7 @@
 const membersService = require('../../services/members');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'members_stripe_connect',
     auth: {
         headers: {
@@ -30,3 +31,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/members.js b/ghost/core/core/server/api/endpoints/members.js
index dc5ad308ac..e9d8fb2daf 100644
--- a/ghost/core/core/server/api/endpoints/members.js
+++ b/ghost/core/core/server/api/endpoints/members.js
@@ -29,7 +29,8 @@ const messages = {
 
 const allowedIncludes = ['email_recipients', 'products', 'tiers'];
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'members',
 
     browse: {
@@ -503,3 +504,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/mentions.js b/ghost/core/core/server/api/endpoints/mentions.js
index 6ad4d0f19f..fac92a5e0b 100644
--- a/ghost/core/core/server/api/endpoints/mentions.js
+++ b/ghost/core/core/server/api/endpoints/mentions.js
@@ -1,6 +1,7 @@
 const mentions = require('../../services/mentions');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'mentions',
     browse: {
         headers: {
@@ -37,3 +38,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/newsletters-public.js b/ghost/core/core/server/api/endpoints/newsletters-public.js
index fc8d081543..2b7a600a5d 100644
--- a/ghost/core/core/server/api/endpoints/newsletters-public.js
+++ b/ghost/core/core/server/api/endpoints/newsletters-public.js
@@ -1,6 +1,7 @@
 const models = require('../../models');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'newsletters',
 
     browse: {
@@ -20,3 +21,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/newsletters.js b/ghost/core/core/server/api/endpoints/newsletters.js
index f8eef9ed19..321010a545 100644
--- a/ghost/core/core/server/api/endpoints/newsletters.js
+++ b/ghost/core/core/server/api/endpoints/newsletters.js
@@ -2,7 +2,8 @@ const allowedIncludes = ['count.posts', 'count.members', 'count.active_members']
 
 const newslettersService = require('../../services/newsletters');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'newsletters',
 
     browse: {
@@ -121,3 +122,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/notifications.js b/ghost/core/core/server/api/endpoints/notifications.js
index 8cd31b748b..aa5d20711b 100644
--- a/ghost/core/core/server/api/endpoints/notifications.js
+++ b/ghost/core/core/server/api/endpoints/notifications.js
@@ -3,7 +3,8 @@ const settingsService = require('../../services/settings/settings-service');
 const settingsBREADService = settingsService.getSettingsBREADServiceInstance();
 const internalContext = {context: {internal: true}};
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'notifications',
 
     browse: {
@@ -101,3 +102,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/oembed.js b/ghost/core/core/server/api/endpoints/oembed.js
index d2e2c80c6f..99209b94c6 100644
--- a/ghost/core/core/server/api/endpoints/oembed.js
+++ b/ghost/core/core/server/api/endpoints/oembed.js
@@ -1,6 +1,7 @@
 const oembed = require('../../services/oembed');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'oembed',
 
     read: {
@@ -20,3 +21,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/offers-public.js b/ghost/core/core/server/api/endpoints/offers-public.js
index 54d0e5dd3f..f373c9214a 100644
--- a/ghost/core/core/server/api/endpoints/offers-public.js
+++ b/ghost/core/core/server/api/endpoints/offers-public.js
@@ -6,7 +6,8 @@ const messages = {
     offerNotFound: 'Offer not found.'
 };
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'offers',
 
     read: {
@@ -29,3 +30,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/offers.js b/ghost/core/core/server/api/endpoints/offers.js
index 13fa199a5f..24fd5ce5a9 100644
--- a/ghost/core/core/server/api/endpoints/offers.js
+++ b/ghost/core/core/server/api/endpoints/offers.js
@@ -6,7 +6,8 @@ const messages = {
     offerNotFound: 'Offer not found.'
 };
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'offers',
 
     browse: {
@@ -82,3 +83,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/pages-public.js b/ghost/core/core/server/api/endpoints/pages-public.js
index 8dd89c09b0..9761613169 100644
--- a/ghost/core/core/server/api/endpoints/pages-public.js
+++ b/ghost/core/core/server/api/endpoints/pages-public.js
@@ -20,7 +20,8 @@ const rejectPrivateFieldsTransformer = input => mapQuery(input, function (value,
     };
 });
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'pages',
 
     browse: {
@@ -103,3 +104,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/pages.js b/ghost/core/core/server/api/endpoints/pages.js
index 38c7d29ee4..f3022b9e31 100644
--- a/ghost/core/core/server/api/endpoints/pages.js
+++ b/ghost/core/core/server/api/endpoints/pages.js
@@ -11,7 +11,8 @@ const messages = {
 
 const postsService = getPostServiceInstance();
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'pages',
     browse: {
         headers: {
@@ -282,3 +283,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/posts-public.js b/ghost/core/core/server/api/endpoints/posts-public.js
index 9979a82aca..79e1d9656c 100644
--- a/ghost/core/core/server/api/endpoints/posts-public.js
+++ b/ghost/core/core/server/api/endpoints/posts-public.js
@@ -23,6 +23,12 @@ const rejectPrivateFieldsTransformer = input => mapQuery(input, function (value,
     };
 });
 
+/**
+ *
+ * @param {import('@tryghost/api-framework').Frame} frame
+ * @param {object} options
+ * @returns {object}
+ */
 function generateOptionsData(frame, options) {
     return options.reduce((memo, option) => {
         let value = frame.options?.[option];
@@ -52,7 +58,9 @@ function generateAuthData(frame) {
         };
     }
 }
-module.exports = {
+
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'posts',
 
     browse: {
@@ -172,3 +180,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/posts.js b/ghost/core/core/server/api/endpoints/posts.js
index 6ec3174aa3..51b2f320ea 100644
--- a/ghost/core/core/server/api/endpoints/posts.js
+++ b/ghost/core/core/server/api/endpoints/posts.js
@@ -38,7 +38,8 @@ function getCacheHeaderFromEventString(event, dto) {
     }
 }
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'posts',
     browse: {
         headers: {
@@ -327,3 +328,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/previews.js b/ghost/core/core/server/api/endpoints/previews.js
index e335e89fe0..0bdc71b61c 100644
--- a/ghost/core/core/server/api/endpoints/previews.js
+++ b/ghost/core/core/server/api/endpoints/previews.js
@@ -7,7 +7,8 @@ const messages = {
     postNotFound: 'Post not found.'
 };
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'previews',
 
     read: {
@@ -47,3 +48,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/recommendations-public.js b/ghost/core/core/server/api/endpoints/recommendations-public.js
index dfc98b9e64..63dd88ebbe 100644
--- a/ghost/core/core/server/api/endpoints/recommendations-public.js
+++ b/ghost/core/core/server/api/endpoints/recommendations-public.js
@@ -1,6 +1,7 @@
 const recommendations = require('../../services/recommendations');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'recommendations',
 
     browse: {
@@ -62,3 +63,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/recommendations.js b/ghost/core/core/server/api/endpoints/recommendations.js
index afad5b4d65..c64d6ee7bb 100644
--- a/ghost/core/core/server/api/endpoints/recommendations.js
+++ b/ghost/core/core/server/api/endpoints/recommendations.js
@@ -1,6 +1,7 @@
 const recommendations = require('../../services/recommendations');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'recommendations',
 
     browse: {
@@ -107,3 +108,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/redirects.js b/ghost/core/core/server/api/endpoints/redirects.js
index 6c6ab783a5..c8159215cc 100644
--- a/ghost/core/core/server/api/endpoints/redirects.js
+++ b/ghost/core/core/server/api/endpoints/redirects.js
@@ -2,7 +2,8 @@ const path = require('path');
 
 const customRedirects = require('../../services/custom-redirects');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'redirects',
 
     download: {
@@ -44,3 +45,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/roles.js b/ghost/core/core/server/api/endpoints/roles.js
index a34d29ff3d..a8460599a6 100644
--- a/ghost/core/core/server/api/endpoints/roles.js
+++ b/ghost/core/core/server/api/endpoints/roles.js
@@ -1,6 +1,7 @@
 const models = require('../../models');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'roles',
     browse: {
         headers: {
@@ -20,3 +21,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/schedules.js b/ghost/core/core/server/api/endpoints/schedules.js
index de57ba6a7d..1e964fc495 100644
--- a/ghost/core/core/server/api/endpoints/schedules.js
+++ b/ghost/core/core/server/api/endpoints/schedules.js
@@ -1,8 +1,8 @@
 const models = require('../../models');
-
 const postSchedulingService = require('../../services/posts/post-scheduling-service')();
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'schedules',
     publish: {
         headers: {
@@ -85,3 +85,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/session.js b/ghost/core/core/server/api/endpoints/session.js
index 20d65f86a6..3ea303ed32 100644
--- a/ghost/core/core/server/api/endpoints/session.js
+++ b/ghost/core/core/server/api/endpoints/session.js
@@ -8,7 +8,8 @@ const messages = {
     accessDenied: 'Access Denied.'
 };
 
-const session = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     read(frame) {
         /*
          * TODO
@@ -66,4 +67,4 @@ const session = {
     }
 };
 
-module.exports = session;
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/settings-public.js b/ghost/core/core/server/api/endpoints/settings-public.js
index d89dc61858..72de70973e 100644
--- a/ghost/core/core/server/api/endpoints/settings-public.js
+++ b/ghost/core/core/server/api/endpoints/settings-public.js
@@ -2,7 +2,8 @@ const settingsCache = require('../../../shared/settings-cache');
 const urlUtils = require('../../../shared/url-utils');
 const ghostVersion = require('@tryghost/version');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'settings',
 
     browse: {
@@ -22,3 +23,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/settings.js b/ghost/core/core/server/api/endpoints/settings.js
index a4ad985569..8d128f687f 100644
--- a/ghost/core/core/server/api/endpoints/settings.js
+++ b/ghost/core/core/server/api/endpoints/settings.js
@@ -21,7 +21,8 @@ async function getStripeConnectData(frame) {
     }
 }
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'settings',
 
     browse: {
@@ -179,3 +180,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/site.js b/ghost/core/core/server/api/endpoints/site.js
index e3968325fe..5503356616 100644
--- a/ghost/core/core/server/api/endpoints/site.js
+++ b/ghost/core/core/server/api/endpoints/site.js
@@ -1,6 +1,7 @@
 const publicConfig = require('../../services/public-config');
 
-const site = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'site',
 
     read: {
@@ -14,4 +15,4 @@ const site = {
     }
 };
 
-module.exports = site;
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/slack.js b/ghost/core/core/server/api/endpoints/slack.js
index 8981e6af44..900d9c7f12 100644
--- a/ghost/core/core/server/api/endpoints/slack.js
+++ b/ghost/core/core/server/api/endpoints/slack.js
@@ -1,7 +1,8 @@
 // Used to call the slack ping service, iirc this was done to avoid circular deps a long time ago
 const events = require('../../lib/common/events');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'slack',
     sendTest: {
         headers: {
@@ -13,3 +14,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/slugs.js b/ghost/core/core/server/api/endpoints/slugs.js
index cd381d7815..0e9ed15748 100644
--- a/ghost/core/core/server/api/endpoints/slugs.js
+++ b/ghost/core/core/server/api/endpoints/slugs.js
@@ -12,7 +12,8 @@ const allowedTypes = {
     user: models.User
 };
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'slugs',
     generate: {
         headers: {
@@ -52,3 +53,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/snippets.js b/ghost/core/core/server/api/endpoints/snippets.js
index f235a0a84b..0bfc44507a 100644
--- a/ghost/core/core/server/api/endpoints/snippets.js
+++ b/ghost/core/core/server/api/endpoints/snippets.js
@@ -7,7 +7,8 @@ const messages = {
     snippetAlreadyExists: 'Snippet already exists.'
 };
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'snippets',
 
     browse: {
@@ -131,3 +132,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/stats.js b/ghost/core/core/server/api/endpoints/stats.js
index d36cf3ac58..c73722948e 100644
--- a/ghost/core/core/server/api/endpoints/stats.js
+++ b/ghost/core/core/server/api/endpoints/stats.js
@@ -1,6 +1,7 @@
 const statsService = require('../../services/stats');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'stats',
     memberCountHistory: {
         headers: {
@@ -104,3 +105,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/tags-public.js b/ghost/core/core/server/api/endpoints/tags-public.js
index 528539c9a3..4ce2530895 100644
--- a/ghost/core/core/server/api/endpoints/tags-public.js
+++ b/ghost/core/core/server/api/endpoints/tags-public.js
@@ -9,7 +9,8 @@ const messages = {
     tagNotFound: 'Tag not found.'
 };
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'tags',
 
     browse: {
@@ -76,3 +77,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/tags.js b/ghost/core/core/server/api/endpoints/tags.js
index 9d4485979a..f98420f634 100644
--- a/ghost/core/core/server/api/endpoints/tags.js
+++ b/ghost/core/core/server/api/endpoints/tags.js
@@ -8,7 +8,8 @@ const messages = {
     tagNotFound: 'Tag not found.'
 };
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'tags',
 
     browse: {
@@ -156,3 +157,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/themes.js b/ghost/core/core/server/api/endpoints/themes.js
index e2ca3b5844..4b2f239aa5 100644
--- a/ghost/core/core/server/api/endpoints/themes.js
+++ b/ghost/core/core/server/api/endpoints/themes.js
@@ -6,7 +6,8 @@ const models = require('../../models');
 const events = require('../../lib/common/events');
 const {settingsCache} = require('../../services/settings-helpers');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'themes',
 
     browse: {
@@ -180,3 +181,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/tiers-public.js b/ghost/core/core/server/api/endpoints/tiers-public.js
index 4e2fbc20f4..f0169b3f3f 100644
--- a/ghost/core/core/server/api/endpoints/tiers-public.js
+++ b/ghost/core/core/server/api/endpoints/tiers-public.js
@@ -1,6 +1,7 @@
 const tiersService = require('../../services/tiers');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'tiers',
 
     browse: {
@@ -23,3 +24,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/tiers.js b/ghost/core/core/server/api/endpoints/tiers.js
index 832c74a720..3d3a560870 100644
--- a/ghost/core/core/server/api/endpoints/tiers.js
+++ b/ghost/core/core/server/api/endpoints/tiers.js
@@ -1,6 +1,7 @@
 const tiersService = require('../../services/tiers');
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'tiers',
 
     browse: {
@@ -80,3 +81,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/users.js b/ghost/core/core/server/api/endpoints/users.js
index 4f6d68dad1..68e9ce7b72 100644
--- a/ghost/core/core/server/api/endpoints/users.js
+++ b/ghost/core/core/server/api/endpoints/users.js
@@ -73,7 +73,8 @@ function shouldInvalidateCacheAfterChange(model) {
     return false;
 }
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'users',
 
     browse: {
@@ -287,3 +288,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;
diff --git a/ghost/core/core/server/api/endpoints/webhooks.js b/ghost/core/core/server/api/endpoints/webhooks.js
index ef3fe82e0b..8df5447128 100644
--- a/ghost/core/core/server/api/endpoints/webhooks.js
+++ b/ghost/core/core/server/api/endpoints/webhooks.js
@@ -15,7 +15,8 @@ const webhooksService = getWebhooksServiceInstance({
     WebhookModel: models.Webhook
 });
 
-module.exports = {
+/** @type {import('@tryghost/api-framework').Controller} */
+const controller = {
     docName: 'webhooks',
 
     add: {
@@ -133,3 +134,5 @@ module.exports = {
         }
     }
 };
+
+module.exports = controller;