re-organzied methods in jsdoc and renamed ticks in sync methods to sy…

…ncToken

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agility/content-fetch",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "JavaScript library for the Agility Fetch API (node and browser)",
   "main": "dist/agility-content-fetch.node.js",
   "scripts": {

src/api-client.js

@@ -6,8 +6,8 @@ import getContentItem from './methods/getContentItem'
 import getContentList from './methods/getContentList'
 import getPage from './methods/getPage'
 import getGallery from './methods/getGallery'
-import syncContentItems from './methods/syncContentItems'
-import syncPageItems from './methods/syncPageItems'
+import getSyncContent from './methods/getSyncContent'
+import getSyncPages from './methods/getSyncPages'
 import FilterOperators from './types/FilterOperator'
 import FilterLogicOperators from './types/FilterLogicOperator'
 import SortDirections from './types/SortDirection'
@@ -93,8 +93,8 @@ export default function createClient(userConfig) {
         getContentList: getContentList,
         getPage: getPage,
         getGallery: getGallery,
-        syncContentItems: syncContentItems,
-        syncPageItems: syncPageItems,
+        getSyncContent: getSyncContent,
+        getSyncPages: getSyncPages,
         types: {
             FilterOperators: FilterOperators,
             FilterLogicOperators: FilterLogicOperators,

src/content-fetch.js

@@ -4,11 +4,33 @@
  */
 
 /**
- * Agility Fetch API JS SDK for retrieving content from the Agility CMS
+ * Agility Fetch API JS SDK client for Agility CMS
  * @namespace AgilityFetch.Client
  */
 
 
+ /**
+ * Agility Fetch API JS SDK for retrieving content from the Agility CMS
+ * @namespace AgilityFetch.Client.Content
+ */
+
+  /**
+ * Agility Fetch API JS SDK for retrieving pages from the Agility CMS
+ * @namespace AgilityFetch.Client.Pages
+ */
+
+   /**
+ * Agility Fetch API JS SDK for retrieving media from the Agility CMS
+ * @namespace AgilityFetch.Client.Media
+ */
+
+
+  /**
+ * Agility Fetch API JS SDK for synchronizing content from Agility CMS
+ * @namespace AgilityFetch.Client.Sync
+ */
+
+
 /**
  * Types returned by the the Fetch API
  * @namespace AgilityFetch.Types

src/methods/getContentItem.js

@@ -2,7 +2,7 @@ import { buildRequestUrlPath, buildAuthHeader } from '../utils'
 
 /**
  * Gets the details of a content item by their Content ID.
- * @memberof AgilityFetch.Client
+ * @memberof AgilityFetch.Client.Content
  * @param {Object} requestParams - The paramters for the API request.
  * @param {number} requestParams.contentID - The contentID of the requested item in this language.
  * @param {string} requestParams.languageCode - The language code of the content you want to retrieve.

src/methods/getContentList.js

@@ -2,7 +2,7 @@ import {buildPathUrl, buildRequestUrlPath, buildAuthHeader } from '../utils'
 
 /**
  * Retrieves a list of content items by reference name.
- * @memberof AgilityFetch.Client
+ * @memberof AgilityFetch.Client.Content
  * @param {Object} requestParams - The parameters for the API request.
  * @param {string} requestParams.referenceName - The unique reference name of the content list you wish to retrieve in the specified language.
  * @param {string} requestParams.languageCode - The language code of the content you want to retrieve.

src/methods/getGallery.js

@@ -2,7 +2,7 @@ import { buildRequestUrlPath, buildAuthHeader } from '../utils'
 
 /**
  * Gets the details of a gallery by their Gallery ID.
- * @memberof AgilityFetch.Client
+ * @memberof AgilityFetch.Client.Media
  * @param {Object} requestParams - The parameters for the API request.
  * @param {number} requestParams.galleryID - The galleryID of the requested item in this language.
  * @returns {Promise<AgilityFetch.Types.Gallery>} - Returns a gallery object.

src/methods/getPage.js

@@ -2,7 +2,7 @@ import { buildRequestUrlPath, buildAuthHeader } from '../utils'
 
 /**
  * Gets the details of a page by its Page ID.
- * @memberof AgilityFetch.Client
+ * @memberof AgilityFetch.Client.Pages
  * @param {Object} requestParams - The parameters for the API request.
  * @param {number} requestParams.pageID - The unique page ID of the page you wish to retrieve in the current language.
  * @param {string} requestParams.languageCode - The language code of the content you want to retrieve.

src/methods/getSitemapFlat.js

@@ -2,7 +2,7 @@ import { buildRequestUrlPath, buildAuthHeader } from '../utils'
 
 /**
  * The sitemap, returned in a flat list, where the dictionary key is the page path. This method is ideal for page routing.
- * @memberof AgilityFetch.Client
+ * @memberof AgilityFetch.Client.Pages
  * @param {Object} requestParams - The parameters for the API request.
  * @param {number} requestParams.channelName - The reference name of the digital channel of the sitemap to return. If you only have one channel, your channel reference name is likely *website*.
  * @param {string} requestParams.languageCode - The language code of the content you want to retrieve.

src/methods/getSitemapNested.js

@@ -2,7 +2,7 @@ import { buildRequestUrlPath, buildAuthHeader } from '../utils'
 
 /**
  * Gets the sitemap as an array in a nested format, ideal for generating menus.
- * @memberof AgilityFetch.Client
+ * @memberof AgilityFetch.Client.Pages
  * @param {Object} requestParams - The parameters for the API request.
  * @param {number} requestParams.channelName - The reference name of the digital channel of the sitemap to return. If you only have one channel, your channel reference name is likely *website*.
  * @param {string} requestParams.languageCode - The language code of the content you want to retrieve.

src/methods/getSyncContent.js

@@ -0,0 +1,62 @@
+import { buildRequestUrlPath, buildAuthHeader } from '../utils'
+
+/**
+ * Retrieves a list of content items that need to be synced based on the provided sync content items token, and returns the next sync token.
+ * @memberof AgilityFetch.Client.Sync
+ * @param {Object} requestParams - The paramters for the API request.
+ * @param {number} requestParams.syncToken - The sync token provided in the response to a previous sync API call. To start a new sync, use the value of '0'.
+ * @param {string} requestParams.languageCode - The language code of the content you want to retrieve.
+ * @param {number} [requestParams.pageSize] - The number of items to return back with each call.  Default is 500.
+ * @returns {Promise<AgilityFetch.Types.SyncContent>} - Returns a list of content item objects.
+ * @example
+ * 
+ * import agility from '@agility/content-fetch'
+ * 
+ * const api = agility.getApi({
+ *   guid: 'ade6cf3c',
+ *   apiKey: 'defaultlive.201ffdd0841cacad5bb647e76547e918b0c9ecdb8b5ddb3cf92e9a79b03623cb',
+ * });
+ * 
+ * api.getSyncContent({
+ *      syncToken: '0', //to start a new sync
+ *      languageCode: 'en-us',
+ *      pageSize: 500
+ * })
+ * .then(function(contentList) {
+ *      console.log(contentList.items);
+ * 
+ *      //the next sync token to use, continue to call this method (loop) until no sync token is provided in the response. This indicates your are up to date.
+ *      console.log(contentList.syncToken); 
+ * })
+ * .catch(function(error) {
+ *      console.log(error);
+ * });
+*/
+function getSyncContent(requestParams) {
+
+    validateRequestParams(requestParams);
+
+    const req = {
+        url: `/sync/items?pageSize=${requestParams.pageSize}&syncToken=${requestParams.syncToken}`,
+        method: 'get',
+        baseURL: buildRequestUrlPath(this.config, requestParams.languageCode),
+        headers: buildAuthHeader(this.config),
+        params: {}
+    };
+
+    return this.makeRequest(req);
+}
+
+function validateRequestParams(requestParams) {
+    if (!requestParams.languageCode) {
+        throw new TypeError('You must include a languageCode in your request params.')
+    }
+    else if (requestParams.syncToken == undefined || requestParams.syncToken == null) {
+        throw new TypeError('You must include a syncToken value your request params.  Use zero (0) to start a new sync.');
+    } else {
+        return;
+    }
+}
+
+
+export default getSyncContent;

src/methods/getSyncPages.js

@@ -0,0 +1,62 @@
+import { buildRequestUrlPath, buildAuthHeader } from '../utils'
+
+/**
+ * Retrieves a list of pages that need to be synced based on the provided sync pages token, and returns the next sync token.
+ * @memberof AgilityFetch.Client.Sync
+ * @param {Object} requestParams - The paramters for the API request.
+ * @param {number} requestParams.syncToken - The sync token provided in the response to a previous sync API call. To start a new sync, use the value of '0'.
+ * @param {string} requestParams.languageCode - The language code of the content you want to retrieve.
+ * @param {number} [requestParams.pageSize] - The number of items to return back with each call.  Default is 1000.
+ * @returns {Promise<AgilityFetch.Types.Page>} - Returns a list of content item objects.
+ * @example
+ * 
+ * import agility from '@agility/content-fetch'
+ * 
+ * const api = agility.getApi({
+ *   guid: 'ade6cf3c',
+ *   apiKey: 'defaultlive.201ffdd0841cacad5bb647e76547e918b0c9ecdb8b5ddb3cf92e9a79b03623cb',
+ * });
+ * 
+ * api.getSyncPages({
+ *      syncToken: '0', //to start a new sync
+ *      languageCode: 'en-us',
+ *      pageSize: 500
+ * })
+ * .then(function(pages) {
+ *      console.log(pages.items);
+ * 
+ *      //the next sync token to use, continue to call this method (loop) until no sync token is provided in the response. This indicates your are up to date.
+ *      console.log(pages.syncToken); 
+ * })
+ * .catch(function(error) {
+ *      console.log(error);
+ * });
+*/
+function getSyncPages(requestParams) {
+
+    validateRequestParams(requestParams);
+
+    const req = {
+        url: `/sync/pages?pageSize=${requestParams.pageSize}&syncToken=${requestParams.syncToken}`,
+        method: 'get',
+        baseURL: buildRequestUrlPath(this.config, requestParams.languageCode),
+        headers: buildAuthHeader(this.config),
+        params: {}
+    };
+
+    return this.makeRequest(req);
+}
+
+function validateRequestParams(requestParams) {
+    if (!requestParams.languageCode) {
+        throw new TypeError('You must include a languageCode in your request params.')
+    }
+    else if (requestParams.syncToken == undefined || requestParams.syncToken == null) {
+        throw new TypeError('You must include a syncToken value your request params.  Use zero (0) to start a new sync.');
+    } else {
+        return;
+    }
+}
+
+
+export default getSyncPages;

src/types/SyncContent.js

@@ -0,0 +1,8 @@
+ /**
+ * Defines **Sync Content** response.
+ * @typedef SyncContent
+ * @memberof AgilityFetch.Types
+ * @property {number} syncToken - The sync token to be used in the next call as a continuation token for syncing content. If this is empty, you are up to date.
+* @property {Array.<AgilityFetch.Types.ContentItem>} items - The paginated array of items returned by the request. 
+ */
+

src/types/SyncPages.js

@@ -0,0 +1,8 @@
+ /**
+ * Defines **Sync Pages** response.
+ * @typedef SyncPages
+ * @memberof AgilityFetch.Types
+ * @property {number} syncToken - The sync token to be used in the next call as a continuation token for syncing content. If this is empty, you are up to date.
+* @property {Array.<AgilityFetch.Types.Page>} items - The paginated array of items returned by the request. 
+ */
+

test/syncContentItems.tests.js → test/getSyncContentItems.tests.js

@@ -14,24 +14,24 @@ const ref = {
     updatesMadeToPublishedContentItemID: 15
 }
 
-describe('syncContentItems:', function () {
+describe('getSyncContent:', function () {
 
     this.timeout('120s');
 
-    it('should retrieve the oldest content items and ticks', function (done) {
+    it('should retrieve the oldest content items and next sync token', function (done) {
         var api = createApiClient();
 
-        let ticks = 0;
+        let syncToken = 0;
 
         //sync from scratch
-        api.syncContentItems({
-            ticks: ticks,
+        api.getSyncContent({
+            syncToken: syncToken,
             pageSize: 100,
             languageCode: 'en-us'
         })
             .then(function (syncRet) {
 
-                assert.isTrue(syncRet.ticks > 0, "should return a ticks value.")
+                assert.isTrue(syncRet.syncToken > 0, "should return a syncToken value.")
                 assert.isTrue(syncRet.items.length > 0, "should return items.")
                 done();
             })