@tryghost/admin-api 1.8.0 → 1.9.1

package/lib/index.js

@@ -3,9 +3,41 @@ const FormData = require('form-data');
 const fs = require('fs');
 const token = require('./token');
 
+// 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 value identifying presence of 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,7 @@ module.exports = function GhostAdminAPI(options) {
 
     const defaultConfig = {
         ghostPath: 'ghost',
+        generateToken: token,
         makeRequest({url, method, data, params = {}, headers = {}}) {
             return axios({
                 url,
@@ -35,7 +68,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,9 +82,34 @@ module.exports = function GhostAdminAPI(options) {
         }
     }
 
-    if (config.version && !supportedVersions.includes(config.version)) {
+    if (config.version === undefined) {
+        throw new Error(`${packageName} Config Missing: 'version' is required. E.g. ${supportedVersions.join(',')}`);
+    }
+
+    if (typeof config.version === 'boolean') {
+        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'`);
     }
@@ -66,19 +129,12 @@ module.exports = function GhostAdminAPI(options) {
         throw new Error(`${packageName} Config Invalid: 'key' ${config.key} must have the following format {A}:{B}, where A is 24 hex characters and B is 64 hex characters`);
     }
 
-    if (config.version === 'v5') {
-        // NOTE: the version parameter is supported but not necessary for non-versioned API, starting with Ghost v5
-        delete config.version;
-    }
-
     const resources = [
-        // @NOTE: stable
         'posts',
         'pages',
         'tags',
         'webhooks',
         'members',
-        // @NOTE: experimental
         'users'
     ];
 
@@ -334,9 +390,8 @@ module.exports = function GhostAdminAPI(options) {
     function endpointFor(resource, {id, slug, email} = {}) {
         const {ghostPath, version} = config;
 
-        let endpoint = version
-            ? `/${ghostPath}/api/${version}/admin/${resource}/`
-            : `/${ghostPath}/api/admin/${resource}/`;
+        const apiPrefix = resolveAPIPrefix(version);
+        let endpoint = `/${ghostPath}/api${apiPrefix}${resource}/`;
 
         if (id) {
             endpoint = `${endpoint}${id}/`;
@@ -353,12 +408,16 @@ module.exports = function GhostAdminAPI(options) {
         const {url: apiUrl, key, version, makeRequest} = config;
         const url = `${apiUrl}${endpoint}`;
 
+        let authorizationHeader;
+        const audience = resolveAPIPrefix(version);
+        authorizationHeader = `Ghost ${config.generateToken(key, audience)}`;
+
         const ghostHeaders = {
-            Authorization: `Ghost ${token(key, version)}`
+            Authorization: authorizationHeader
         };
 
-        if (!version || ['v4', 'canary'].includes(version)) {
-            ghostHeaders['Accept-Version'] = version || 'v5';
+        if (config.acceptVersionHeader) {
+            ghostHeaders['Accept-Version'] = config.acceptVersionHeader;
         }
 
         headers = Object.assign({}, headers, ghostHeaders);

package/lib/token.js

@@ -3,12 +3,11 @@ const jwt = require('jsonwebtoken');
 /**
  *
  * @param {String} key - API key to sign JWT with
- * @param {String} version - API version to use as a part of audience
+ * @param {String} audience - token audience
  * @returns
  */
-module.exports = function token(key, version) {
+module.exports = function token(key, audience) {
     const [id, secret] = key.split(':');
-    const audience = version ? `/${version}/admin/` : '/admin/';
 
     return jwt.sign({}, Buffer.from(secret, 'hex'), { // eslint-disable-line no-undef
         keyid: id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryghost/admin-api",
-  "version": "1.8.0",
+  "version": "1.9.1",
   "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": "36ffe70168eb2ad3eaefa0dc63a35697b284c9e7"
+  "gitHead": "3633e6e946c394c73e53b496477543e98e301aa4"
 }