@tryghost/admin-api 1.7.0 → 1.9.0

package/lib/index.js

@@ -3,9 +3,41 @@ const FormData = require('form-data');
 const fs = require('fs');
 const token = require('./token');
 
-const supportedVersions = ['v2', 'v3', 'v4', 'canary'];
+// NOTE: bump this default when Ghost v5 is released
+const defaultAcceptVersionHeader = 'v4.0';
+const supportedVersions = ['v2', 'v3', 'v4', 'v5', 'canary'];
 const packageName = '@tryghost/admin-api';
 
+/**
+ * This method can go away in favor of only sending 'Accept-Version` headers
+ * once the Ghost API removes a concept of version from it's URLS (with Ghost v5)
+ *
+ * @param {string} [version] version in `v{major}` format
+ * @returns {string}
+ */
+const resolveAPIPrefix = (version) => {
+    let prefix;
+
+    // NOTE: the "version.match(/^v5\.\d+/)" expression should be changed to "version.match(/^v\d+\.\d+/)" once Ghost v5 is out
+    if (version === 'v5' || version === undefined || version.match(/^v5\.\d+/)) {
+        prefix = `/admin/`;
+    } else {
+        prefix = `/${version}/admin/`;
+    }
+
+    return prefix;
+};
+
+/**
+ *
+ * @param {Object} options
+ * @param {String} options.url
+ * @param {String} [options.ghostPath]
+ * @param {String|Boolean} [options.version] - a version string like v3.2, v4.1, v5.8 or boolean 'false' value identifying no Accept-Version header
+ * @param {Function} [options.makeRequest]
+ * @param {Function} [options.generateToken]
+ * @param {String} [options.host] Deprecated
+ */
 module.exports = function GhostAdminAPI(options) {
     if (this instanceof GhostAdminAPI) {
         return GhostAdminAPI(options);
@@ -13,6 +45,8 @@ module.exports = function GhostAdminAPI(options) {
 
     const defaultConfig = {
         ghostPath: 'ghost',
+        generateToken: token,
+        sendAcceptVersionHeader: true,
         makeRequest({url, method, data, params = {}, headers = {}}) {
             return axios({
                 url,
@@ -35,7 +69,12 @@ module.exports = function GhostAdminAPI(options) {
 
     const config = Object.assign({}, defaultConfig, options);
 
-    // new GhostAdminAPI({host: '...'}) is deprecated
+    //
+    /**
+     * host parameter is deprecated
+     * @deprecated use "url" instead
+     * @example new GhostAdminAPI({host: '...'})
+     */
     if (config.host) {
         // eslint-disable-next-line
         console.warn(`${packageName}: The 'host' parameter is deprecated, please use 'url' instead`);
@@ -44,12 +83,36 @@ module.exports = function GhostAdminAPI(options) {
         }
     }
 
-    if (!config.version) {
+    if (config.version === undefined) {
         throw new Error(`${packageName} Config Missing: 'version' is required. E.g. ${supportedVersions.join(',')}`);
     }
-    if (!supportedVersions.includes(config.version)) {
+
+    if (typeof config.version === 'boolean') {
+        config.sendAcceptVersionHeader = config.version;
+
+        if (config.version === true) {
+            config.acceptVersionHeader = defaultAcceptVersionHeader;
+        }
+        config.version = undefined;
+    } else if (!supportedVersions.includes(config.version) && !(config.version.match(/^v\d+\.\d+/))) {
         throw new Error(`${packageName} Config Invalid: 'version' ${config.version} is not supported`);
+    } else if (supportedVersions.includes(config.version) || config.version.match(/^v\d+\.\d+/)) {
+        if (config.version === 'canary') {
+            // eslint-disable-next-line
+            console.warn(`${packageName}: The 'version' parameter has a deprecated format 'canary', please use 'v{major}.{minor}' format instead`);
+
+            config.acceptVersionHeader = defaultAcceptVersionHeader;
+        } else if (config.version.match(/^v\d+$/)) {
+            // eslint-disable-next-line
+            console.warn(`${packageName}: The 'version' parameter has a deprecated format 'v{major}', please use 'v{major}.{minor}' format instead`);
+
+            // CASE: all the v1, v2, v4 ... strings should be normalized to fit 'v{major}.{minor}' format
+            config.acceptVersionHeader = `${config.version}.0`;
+        } else {
+            config.acceptVersionHeader = config.version;
+        }
     }
+
     if (!config.url) {
         throw new Error(`${packageName} Config Missing: 'url' is required. E.g. 'https://site.com'`);
     }
@@ -70,13 +133,11 @@ module.exports = function GhostAdminAPI(options) {
     }
 
     const resources = [
-        // @NOTE: stable
         'posts',
         'pages',
         'tags',
         'webhooks',
         'members',
-        // @NOTE: experimental
         'users'
     ];
 
@@ -331,7 +392,9 @@ module.exports = function GhostAdminAPI(options) {
 
     function endpointFor(resource, {id, slug, email} = {}) {
         const {ghostPath, version} = config;
-        let endpoint = `/${ghostPath}/api/${version}/admin/${resource}/`;
+
+        const apiPrefix = resolveAPIPrefix(version);
+        let endpoint = `/${ghostPath}/api${apiPrefix}${resource}/`;
 
         if (id) {
             endpoint = `${endpoint}${id}/`;
@@ -348,9 +411,19 @@ module.exports = function GhostAdminAPI(options) {
         const {url: apiUrl, key, version, makeRequest} = config;
         const url = `${apiUrl}${endpoint}`;
 
-        headers = Object.assign({}, headers, {
-            Authorization: `Ghost ${token(version, key)}`
-        });
+        let authorizationHeader;
+        const audience = resolveAPIPrefix(version);
+        authorizationHeader = `Ghost ${config.generateToken(key, audience)}`;
+
+        const ghostHeaders = {
+            Authorization: authorizationHeader
+        };
+
+        if (config.acceptVersionHeader) {
+            ghostHeaders['Accept-Version'] = config.acceptVersionHeader;
+        }
+
+        headers = Object.assign({}, headers, ghostHeaders);
 
         return makeRequest({
             url,
@@ -362,7 +435,7 @@ module.exports = function GhostAdminAPI(options) {
             /**
              * @NOTE:
              *
-             * If you are overriding `makeRequest`, we can't garantee that the returned format is the same, but
+             * If you are overriding `makeRequest`, we can't garante that the returned format is the same, but
              * we try to detect & return a proper error instance.
              */
             if (err.response && err.response.data && err.response.data.errors) {

package/lib/token.js

@@ -1,12 +1,18 @@
 const jwt = require('jsonwebtoken');
 
-module.exports = function token(version, key) {
+/**
+ *
+ * @param {String} key - API key to sign JWT with
+ * @param {String} audience - token audience
+ * @returns
+ */
+module.exports = function token(key, audience) {
     const [id, secret] = key.split(':');
 
     return jwt.sign({}, Buffer.from(secret, 'hex'), { // eslint-disable-line no-undef
         keyid: id,
         algorithm: 'HS256',
         expiresIn: '5m',
-        audience: `/${version}/admin/`
+        audience
     });
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryghost/admin-api",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "repository": "https://github.com/TryGhost/SDK/tree/master/packages/admin-api",
   "author": "Ghost Foundation",
   "license": "MIT",
@@ -31,5 +31,5 @@
     "form-data": "^4.0.0",
     "jsonwebtoken": "^8.4.0"
   },
-  "gitHead": "bb3a33a1ff85c0d3efb2972e8d6dd72df458c271"
+  "gitHead": "b4c9597d781809903118a07e5fba16a106ec6053"
 }