Edits to API files

src/jsdoc.json

@@ -0,0 +1,3 @@
+{
+  "plugins": ["plugins/markdown"]
+}

src/libraries/FipamoAdminAPI.js

@@ -27,12 +27,14 @@ export const TASK_PAGE_EDIT = "editPage";
 export const TASK_PAGE_DELETE = "deletePage";
 export const TASK_SEND_MAIL = "sendMail";
 export const TASK_REINDEX_PAGE = "reIndexPages";
+export const TASK_SYNC_SETTNIGS = "syncSite";
+export const TASK_SYNC_NAV = "syncNav";
 //** API STATUS **//
 export const API_ACCESS_GOOD = "apiUseAuthorized";
 export const API_ACCESS_BAD = "apiUseNotAuthorized";
 
 /**
- * A can of methods used to edit install settings, navigation pages.
+ * A can of methods used to edit install settings, navigation pages and content pages
  */
 
 class FipamoAdminAPI {
@@ -63,10 +65,22 @@ class FipamoAdminAPI {
     });
   }
   /**
-   * Promise method for checking credentials. Must login to use Admin API.
+   * Promise method for authenticating and starting a session\
-   * @param {object} data - json object that contains data for set up
+   * **POST**`/api/v1/login`
-   * @property {string} handle - handle for site user
+   * @param {Object[]} data - json object that contains data for set up
-   * @property {string} password - password for site user
+   * @param {string} data[].handle - handle for site user
+   * @param {string} data[].password - password for site user
+   * @example
+   * api.login(data).then(response=>{
+   *    console.log("RESPONSE", response);
+   * })
+   * @returns {object} json object that contains type and status of login request
+   ```
+        {
+          "message":"Example Message of Affirmation or what you're missing!",
+          "type":"exampleType",
+        }
+   ```
    */
   login(data) {
     return new Promise((resolve, reject) => {
@@ -88,31 +102,59 @@ class FipamoAdminAPI {
     });
   }
   /**
-   * Method for saving settings
+   * Method for saving site and navigation settings\
-   * @param {object} data - json object that contains settings data set on the front-end
+   * **POST**`/api/v1/settings/:task`
-   * @property {string} global.base_url - base url for site
+   * @param {string} task - settings being synced `config | navigation`
-   * @property {string} global.title - site title
+   * @param {object[]} data - json object that contains settings data for [site] or [nav]
-   * @property {string} global.descriptions - brief site summary
+   * @param {string} data[].global.base_url - base url for site [site]
-   * @property {string} global.background - url for site feature image for header
+   * @param {string} data[].global.title - site title [site]
-   * @property {boolean} global.private - privacy state for site [disabled]
+   * @param {string} data[].global.descriptions - brief site summary [site]
-   * @property {boolean} global.renderOnSave - property for publishing site when page saved [disabled]
+   * @param {string} data[].global.background - url for site feature image for header [site]
-   * @property {string} global.theme - current theme for site
+   * @param {boolean} data[].global.private - privacy state for site [disabled] [site]
-   * @property {boolean} global.externalAPI - toggle for external API access
+   * @param {boolean} data[].global.renderOnSave - property for publishing site when page saved [disabled] [site]
-   * @property {string} member.handle - current member handle
+   * @param {string} data[].global.theme - current theme for site [site]
-   * @property {string} member.email - current member email
+   * @param {boolean} data[].global.externalAPI - toggle for external API access [site]
-   * @property {string} email.active - current email protocol being used
+   * @param {string} data[].member.handle - current member handle [site]
-   * @property {string} email.smtp.domain - url of smtp service being
+   * @param {string} data[].member.email - current member email [site]
-   * @property {string} email.smtp.email - email account of smtp service
+   * @param {string} data[].email.active - current email protocol being used [site]
-   * @property {string} email.smtp.password - password for email of smtp service
+   * @param {string} data[].email.smtp.domain - url of smtp service being [site]
-   * @property {string} email.mailgun.domain - mailgun domain url
+   * @param {string} data[].email.smtp.email - email account of smtp service [site]
-   * @property {string} email.mailgun.key - mailgun key
+   * @param {string} data[].email.smtp.password - password for email of smtp service [site]
+   * @param {string} data[].email.mailgun.domain - mailgun domain url [site]
+   * @param {string} data[].email.mailgun.key - mailgun key [site]
+   *
+   * @param {string} data[].item.title - page title [nav]
+   * @param {string} data[].item.slug - url safe title [nav]
+   * @param {string} data[].item.uuid - unique identifier [nav]
+   * @param {string} data[].item.path - directory path to associated markdown file [nav]
+   * @example
+   * api.sync(TASK, data).then(response=>{
+   *    console.log("RESPONSE", response);
+   * })
+   * @returns {object} json object that contains type and status of sync request
+   ```
+   *
+     {
+       "message":"Example Message of Affirmation!",
+       "type":"exampleType",
+     }
+   ```
    */
-  syncSettings(data) {
+  sync(task, data) {
     return new Promise((resolve, reject) => {
+      let url = "";
+      switch (task) {
+        case "syncSite":
+          url = API_SETTINGS_SYNC;
+          break;
+        case "syncNav":
+          url = API_NAV_SYNC;
+          break;
+      }
       this._request(
         this.baseURL
-          ? this.baseURL + API_SETTINGS_SYNC + "?key=" + this.key
+          ? this.baseURL + url + "?key=" + this.key
-          : API_SETTINGS_SYNC + "?key=" + this.key,
+          : url + "?key=" + this.key,
         TASK_SETTINGS_WRITE,
         REQUEST_TYPE_POST,
         CONTENT_TYPE_JSON,
@@ -129,10 +171,21 @@ class FipamoAdminAPI {
 
   /**
    * Method for retrieving user authorizing user login
-   * @param {object} data - json object that contains task
+   * @param {object[]} data - json object that contains task
-   * @property {string} task - publishing task [deprecated]
+   * @param {string} data[].task - publishing task
+   * @example
+   * api.publish(TASK).then(response=>{
+   *    console.log("RESPONSE", response);
+   * })
+   * @returns {object} json object that contains type and status of publis request
+   * ```
+      {
+        "message":"Example Message of Affirmation!",
+        "type":"exampleType",
+      }
+   * ```
    */
-  publishSite(data) {
+  publish(data) {
     return new Promise((resolve, reject) => {
       this._request(
         //API_PUBLISH_PAGES,
@@ -152,22 +205,34 @@ class FipamoAdminAPI {
   }
 
   /**
-   * Method for handling page creating and editing
+   * Method for handling page creating and editing\
+   * **POST**`/api/v1/page/:task`
    * @param {string} task - current page action
-   * @param {object} data - form object that contains info for current page being edited/created
+   * @param {object[]} form - form object that contains info for current page being edited/created
-   * @property {string} id - sequence id for page
+   * @param {string} form[].id - sequence id for page, leave empty for new page
-   * @property {string} uuid - unique identifier for page
+   * @param {string} form[].uuid - unique identifier for page, leave empty for new page
-   * @property {string} layout - current page layout
+   * @param {string} form[].layout - current page layout
-   * @property {string} current_title - saved url save title for persistence when changing title
+   * @param {string} form[].current_title - saved url save title for persistence when changing title, leave empty for new page
-   * @property {string} content - markdown body of page
+   * @param {string} form[].content - markdown body of page
-   * @property {string} title - current title of page
+   * @param {string} form[].title - current title of page
-   * @property {string} created - date page was created
+   * @param {string} form[].created - date page was created, leave empty for new page
-   * @property {string} slug - url safe string of page title
+   * @param {string} form[].slug - url safe string of page title
-   * @property {string} tags - comma separated list of tags
+   * @param {string} form[].tags - comma separated list of tags
-   * @property {boolean} menu - property that indicates page is included in site menu
+   * @param {boolean} form[].menu - property that indicates page is included in site menu
-   * @property {boolean} featured - property that indicates page is featured
+   * @param {boolean} form[].featured - property that indicates page is featured
-   * @property {boolean} published - property that indicates page is public
+   * @param {boolean} form[].published - property that indicates page is public
-   * @property {input} feature_image - main image for page
+   * @param {input} form[].feature_image - main image for page
+   * @example
+   * api.pageActions(TASK, data).then(response=>{
+   *    console.log("RESPONSE", response);
+   * })
+   * @returns {object} json object that contains type and status of page edit request
+   ```
+      {
+        "message":"Example Message of Affirmation!",
+        "type":"exampleType",
+      }
+   ```
    */
   pageActions(task, data) {
     let url, event, content;
@@ -218,34 +283,21 @@ class FipamoAdminAPI {
   }
 
   /**
-   * Method for saving pages to be included in main site navigation
+   * Method for sending mail (if completed in settings)\
-   * @param {object} data - json object that contains items to be included in main site navigation
+   * **POST**`/api/v1/mailer`
-   * @property {string} item.title - page title
+   * @param {object[]} message - json object that contains items to be included in main site navigation
-   * @property {string} item.slug - url safe title
+   * @param {string} message[].content - message to send
-   * @property {string} item.uuid - unique identifier
+   * @example
-   * @property {string} item.path - directory path to associated markdown file
+   * api.sendMail(message).then(response=>{
-   */
+   *    console.log("RESPONSE", response);
-  syncNav(data) {
+   * })
-    return new Promise((resolve, reject) => {
+   * @returns {object} json object that contains type and status of page edit request
-      this._request(
+   ```
-        this.baseURL ? this.baseURL + API_NAV_SYNC : API_NAV_SYNC,
+     {
-        TASK_SETTINGS_WRITE,
+       "message":"Example Message of Affirmation!",
-        REQUEST_TYPE_POST,
+       "type":"exampleType"
-        CONTENT_TYPE_JSON,
+     }
-        data
+   ```
-      )
-        .then((result) => {
-          resolve(result);
-        })
-        .catch((err) => {
-          reject(err);
-        });
-    });
-  }
-  /**
-   * Method for sending mail
-   * @param {object} message - json object that contains items to be included in main site navigation
-   * @property {string} content - message to send
    */
   sendMail(message) {
     return new Promise((resolve, reject) => {
@@ -264,27 +316,7 @@ class FipamoAdminAPI {
         });
     });
   }
-  /**
+
-   * Maintenance method to clean up page sequencing [disabled]
-   * @param {object} data - json object that contains items to be included in main site navigation
-   */
-  reindexPages(data) {
-    return new Promise((resolve, reject) => {
-      this._request(
-        this.baseURL ? this.baseURL + API_REINDEX_PAGES : API_REINDEX_PAGES,
-        TASK_REINDEX_PAGE,
-        REQUEST_TYPE_POST,
-        CONTENT_TYPE_JSON,
-        data
-      )
-        .then((result) => {
-          resolve(result);
-        })
-        .catch((err) => {
-          reject(err);
-        });
-    });
-  }
   //--------------------------
   // private
   //--------------------------

src/libraries/FipamoContentAPI.js

@@ -19,15 +19,13 @@ export const API_GET_TAGS = "/api/v1/page/tags";
 export const TASK_GET_CONTENT = "retrieveContent";
 
 /**
- * Fipamo Content API
+ * A bag of methods for getting content from an install.
- * A bag of methods for getting page info from an install.
- * To use remotely, include url of install and user key found in settings in the Dashboard.
  */
 class FipamoContentAPI {
   /**
    * @constructor
-   * @param {string} baseURL - url of site; uses local when empty
+   * @param {string} baseURL - url of install, defaults to local
-   * @param {string} key - user api key
+   * @param {string} key - user api key found in Settings
    * @author Ro
    */
   constructor(baseURL = null, key = null) {
@@ -38,14 +36,61 @@ class FipamoContentAPI {
   }
 
   /**
-   * Promise method for retrieving page data
+   * *Promise method for retrieving page data*\
-   * @param {string} type - type of pages being retrieved; null value defaults to published
+   * **GET**`/api/v1/page/:type`
+   * @param {string} type - type of pages (`published | menu | featured`) being retrieved; null value defaults to `published`
    * @example
    * api.pages('published').then(pages=>{
    *    console.log("Pages Object", pages);
    * })
    * @returns {object} json object that contains pages of requested type
    *
+   * *pages object example*
+   * ```
+    {
+      "pages":
+      [
+        {
+          "id":1,
+          "uuid":"uuid-for-entry",
+          "title":"Entry Title",
+          "feature":"/path/to/image.jpg",
+          "path":"2020/09",
+          "layout":"page",
+          "tags":"these, are, tags",
+          "author":"your-name",
+          "created":"2020 Sep Tue 01",
+          "updated":"2020 Sep Tue 01",
+          "deleted":false,
+          "menu":false,
+          "featured":false,
+          "published":true,
+          "slug":"entry-title",
+          "content":"Premium Content"
+        },
+        {
+          "id":2,
+          "uuid":"uuid-for-entry",
+          "title":"Another Title",
+          "feature":"/path/to/image.jpg",
+          "path":"2020/09",
+          "layout":"page",
+          "tags":"these, are, tags",
+          "author":"your-name",
+          "created":"2020 Sep Tue 01",
+          "updated":"2020 Sep Tue 01",
+          "deleted":false,
+          "menu":false,
+          "featured":false,
+          "published":true,
+          "slug":"another-title",
+          "content":"Premium Content"
+        }
+      ],
+    "totalItems":2
+    }
+   * ```
+   *
    */
   pages(type = null) {
     //set url based on request type
@@ -76,13 +121,36 @@ class FipamoContentAPI {
     });
   }
   /**
-   * Promise method for retrieving single page
+   * *Promise method for retrieving single page*\
+   * **GET** `/api/v1/page/single/:id`
    * @param {string} id - uuid of desired page
    * @example
    * api.page("a-uuid-for-a-page").then(page=>{
         console.log("Page Object", page);
    * })
    * @returns {object} json object that contains data for requested page
+   *
+   * *page object example*
+   * ```
+     {
+       "id":1,
+       "uuid":"uuid-for-entry",
+       "title":"Entry Title",
+       "feature":"/path/to/image.jpg",
+       "path":"2020/09",
+       "layout":"page",
+       "tags":"these, are, tags",
+       "author":"your-name",
+       "created":"2020 Sep Tue 01",
+       "updated":"2020 Sep Tue 01",
+       "deleted":false,
+       "menu":false,
+       "featured":false,
+       "published":true,
+       "slug":"entry-title",
+       "content":"Premium Content"
+     }
+   * ```
    */
   page(id) {
     return new Promise((resolve, reject) => {
@@ -103,12 +171,55 @@ class FipamoContentAPI {
   }
 
   /**
-   * Promise method for retrieving all tags used by pages
+   * *Promise method for retrieving all tags used by pages*\
+   * **GET** `/api/v1/page/tags`
    * @example
    * api.tags().then(tags=>{
        console.log("Tags Object", tags);
    * })
-   * @returns {object} json object that contains tags used by pages
+   * @returns {object} json object that contains site tags and page stubs associated with said tag
+   *
+   * *tags object example*
+   * ```
+      [
+        {
+          "tag_name":"this is a tag",
+          "slug":"this-is-a-tag",
+          "pages":
+            [
+              {
+                "title":"This is a title",
+                "slug":"this-is-a-title",
+                "path":"2021/04"
+              },
+              
+              {
+                "title":"This is another title",
+                "slug":"this-is-another-title",
+                "path":"2020/10"
+              }
+            ]
+        },
+        {
+          "tag_name":"this is another tag",
+          "slug":"this-is-another-tag",
+          "pages":
+            [
+              {
+                "title":"This is a title",
+                "slug":"this-is-a-title",
+                "path":"2021/04"
+              },
+              
+              {
+                "title":"This is another title",
+                "slug":"this-is-another-title",
+                "path":"2020/10"
+              }
+            ]
+        }
+      ]  
+   * ```
    */
   tags() {
     return new Promise((resolve, reject) => {