@tryghost/admin-api 1.6.0 → 1.8.1

package/lib/index.js

@@ -3,9 +3,18 @@ const FormData = require('form-data');
 const fs = require('fs');
 const token = require('./token');
 
-const supportedVersions = ['v2', 'v3', 'v4', 'canary'];
+const supportedVersions = ['v2', 'v3', 'v4', 'v5', 'canary'];
 const packageName = '@tryghost/admin-api';
 
+/**
+ *
+ * @param {Object} options
+ * @param {String} options.url
+ * @param {String} [options.ghostPath]
+ * @param {String} [options.version]
+ * @param {Function} [options.makeRequest]
+ * @param {String} [options.host] Deprecated
+ */
 module.exports = function GhostAdminAPI(options) {
     if (this instanceof GhostAdminAPI) {
         return GhostAdminAPI(options);
@@ -35,7 +44,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,10 +58,7 @@ module.exports = function GhostAdminAPI(options) {
         }
     }
 
-    if (!config.version) {
-        throw new Error(`${packageName} Config Missing: 'version' is required. E.g. ${supportedVersions.join(',')}`);
-    }
-    if (!supportedVersions.includes(config.version)) {
+    if (config.version && !supportedVersions.includes(config.version)) {
         throw new Error(`${packageName} Config Invalid: 'version' ${config.version} is not supported`);
     }
     if (!config.url) {
@@ -69,6 +80,11 @@ 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',
@@ -202,29 +218,52 @@ module.exports = function GhostAdminAPI(options) {
         if (data.file) {
             formData = new FormData();
             formData.append('file', fs.createReadStream(data.file));
+            // NOTE: this default "image" doesn't work for all upload endpoints. Should be moved from here and required as
+            //       an explicit method parameter. Leaving it here for now as I'm focusing on a different problem.
             formData.append('purpose', data.purpose || 'image');
 
             if (data.ref) {
                 formData.append('ref', data.ref);
             }
 
+            if (data.thumbnail) {
+                formData.append('thumbnail', fs.createReadStream(data.thumbnail));
+            }
+
             return formData;
         }
     }
 
     api.images = {
         upload(data) {
-            if (!data) {
-                return Promise.reject(new Error('Missing data'));
-            }
-
-            if (!isValidUpload(data)) {
-                return Promise.reject(new Error('Must be of FormData or include path'));
-            }
+            return makeUploadRequest('images', data, endpointFor('images/upload'));
+        }
+    };
 
-            let formData = getFormData(data);
+    api.media = {
+        /**
+         *
+         * @param {Object} data
+         * @param {String} data.file - file path to a media file
+         * @param {String} [data.thumbnail] - file path to a thumbnail file
+         * @param {String} [data.purpose]
+         * @returns Promise<Object>
+         */
+        upload(data) {
+            return makeUploadRequest('media', data, endpointFor('media/upload'));
+        }
+    };
 
-            return makeUploadRequest('images', formData, endpointFor('images/upload'));
+    api.files = {
+        /**
+         *
+         * @param {Object} data
+         * @param {String} data.file - file path to a media file
+         * @param {String} [data.ref] - reference field returned in the response
+         * @returns Promise<Object>
+         */
+        upload(data) {
+            return makeUploadRequest('files', data, endpointFor('files/upload'));
         }
     };
 
@@ -242,17 +281,7 @@ module.exports = function GhostAdminAPI(options) {
 
     api.themes = {
         upload(data) {
-            if (!data) {
-                return Promise.reject(new Error('Missing data'));
-            }
-
-            if (!isValidUpload(data)) {
-                return Promise.reject(new Error('Must be of FormData or include path'));
-            }
-
-            let formData = getFormData(data);
-
-            return makeUploadRequest('themes', formData, endpointFor('themes/upload'));
+            return makeUploadRequest('themes', data, endpointFor('themes/upload'));
         },
         activate(name) {
             if (!name) {
@@ -266,14 +295,24 @@ module.exports = function GhostAdminAPI(options) {
     return api;
 
     function makeUploadRequest(resourceType, data, endpoint) {
+        if (!data) {
+            return Promise.reject(new Error('Missing data'));
+        }
+
+        if (!isValidUpload(data)) {
+            return Promise.reject(new Error('Must be of FormData or include path'));
+        }
+
+        let formData = getFormData(data);
+
         const headers = {
-            'Content-Type': `multipart/form-data; boundary=${data._boundary}`
+            'Content-Type': `multipart/form-data; boundary=${formData._boundary}`
         };
 
         return makeApiRequest({
             endpoint: endpoint,
             method: 'POST',
-            body: data,
+            body: formData,
             headers
         }).then((apiData) => {
             if (!Array.isArray(apiData[resourceType])) {
@@ -308,7 +347,10 @@ module.exports = function GhostAdminAPI(options) {
 
     function endpointFor(resource, {id, slug, email} = {}) {
         const {ghostPath, version} = config;
-        let endpoint = `/${ghostPath}/api/${version}/admin/${resource}/`;
+
+        let endpoint = version
+            ? `/${ghostPath}/api/${version}/admin/${resource}/`
+            : `/${ghostPath}/api/admin/${resource}/`;
 
         if (id) {
             endpoint = `${endpoint}${id}/`;
@@ -325,9 +367,15 @@ 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)}`
-        });
+        const ghostHeaders = {
+            Authorization: `Ghost ${token(key, version)}`
+        };
+
+        if (!version || ['v4', 'canary'].includes(version)) {
+            ghostHeaders['Accept-Version'] = version || 'v5';
+        }
+
+        headers = Object.assign({}, headers, ghostHeaders);
 
         return makeRequest({
             url,
@@ -339,7 +387,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,19 @@
 const jwt = require('jsonwebtoken');
 
-module.exports = function token(version, key) {
+/**
+ *
+ * @param {String} key - API key to sign JWT with
+ * @param {String} version - API version to use as a part of audience
+ * @returns
+ */
+module.exports = function token(key, version) {
     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,
         algorithm: 'HS256',
         expiresIn: '5m',
-        audience: `/${version}/admin/`
+        audience
     });
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryghost/admin-api",
-  "version": "1.6.0",
+  "version": "1.8.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": "f8813610f5ba4eed4fbcbd025eddf78795fd8aab"
+  "gitHead": "dbf4ab41a6964422987a68c4327336692a54527f"
 }