diff --git a/.eslintignore b/.eslintignore index 1521c8b7..1a33f1f2 100644 --- a/.eslintignore +++ b/.eslintignore @@ -1 +1,2 @@ dist +docs diff --git a/.gitignore b/.gitignore index ed0d3c87..aaea7db3 100644 --- a/.gitignore +++ b/.gitignore @@ -86,3 +86,6 @@ typings/ # DynamoDB Local files .dynamodb/ + +# JSDoc output files +docs diff --git a/.jsdoc.json b/.jsdoc.json new file mode 100644 index 00000000..d55a73ec --- /dev/null +++ b/.jsdoc.json @@ -0,0 +1,5 @@ +{ + "opts": { + "template": "node_modules/minami" + } +} diff --git a/README.md b/README.md index 6cb3e812..6fe9d102 100644 --- a/README.md +++ b/README.md @@ -134,4 +134,5 @@ constructorio.recommendations.getUserFeaturedItems({ parameters }).then(function npm run lint # run lint on source code and tests npm run test # run tests npm run coverage # run tests and serves coverage reports from localhost:8081 +npm run docs # build and serve documentation from localhost:8082 ``` diff --git a/package.json b/package.json index a3d68f77..25fc92a5 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,8 @@ "test": "mocha ./spec/* --opts ./mocha.opts --recursive", "precoverage": "rm -rf ./coverage && rm -rf ./.nyc_output", "coverage": "nyc --all --reporter=html npm test", - "postcoverage": "http-server ./coverage -p 8081 -o -c-1" + "postcoverage": "http-server ./coverage -p 8081 -o -c-1", + "docs": "jsdoc --configure ./.jsdoc.json ./README.md --recurse ./src --destination ./docs && http-server ./docs -p 8082 -o -c-1" }, "repository": { "type": "git", @@ -36,6 +37,8 @@ "eslint-config-airbnb-base": "^14.0.0", "eslint-plugin-import": "^2.18.2", "http-server": "^0.11.1", + "jsdoc": "^3.6.3", + "minami": "^1.2.3", "mocha": "^6.2.0", "mocha-jsdom": "^2.0.0", "nyc": "^14.1.1", diff --git a/src/constructorio.js b/src/constructorio.js index 98cbe0a8..6a33dbf7 100644 --- a/src/constructorio.js +++ b/src/constructorio.js @@ -8,7 +8,22 @@ const { recommendations } = require('./modules/recommendations'); const { version } = require('../package.json'); +/** + * Class to instantiate the ConstructorIO client. + */ class ConstructorIO { + /** + * @param {string} apiKey - Constructor.io API key + * @param {string} [serviceUrl='https://ac.cnstrc.com'] - API URL endpoint + * @param {string} [segments] - User segments + * @param {object} [testCells] - User test cells + * @param {string} [clientId] - Client ID, defaults to value supplied by 'constructorio-id' + * @param {string} [sessionId] - Session id, defaults to value supplied by 'constructorio-id' + * @property {object} [search] - Interface to {@link module:search} + * @property {object} [autocomplete] - Interface to {@link module:autocomplete} + * @property {object} [recommendations] - Interface to {@link module:recommendations} + * @returns {class} + */ constructor(options = {}) { const { apiKey, diff --git a/src/modules/autocomplete.js b/src/modules/autocomplete.js index 649c58ce..ec49e7cd 100644 --- a/src/modules/autocomplete.js +++ b/src/modules/autocomplete.js @@ -5,9 +5,12 @@ import Promise from 'es6-promise'; const { fetch } = fetchPonyfill({ Promise }); -/* - * Autocomplete - * - https://docs.constructor.io/rest-api.html#autocomplete +/** + * Interface to autocomplete related API calls. + * + * @module autocomplete + * @inner + * @returns {object} */ export function autocomplete(options) { // Create URL from supplied query (term) and parameters @@ -63,7 +66,16 @@ export function autocomplete(options) { }; return { - // Get autocomplete results for supplied query (term) + /** + * Retrieve autocomplete results from API + * + * @function getResults + * @param {object} [parameters] - Additional parameters to refine result set + * @param {number} [parameters.results] - The number of results to return + * @param {object} [parameters.filters] - Filters used to refine search + * @returns {Promise} + * @see https://docs.constructor.io/rest-api.html#autocomplete + */ getResults: (query, parameters) => { const requestUrl = createAutocompleteUrl(query, parameters); diff --git a/src/modules/recommendations.js b/src/modules/recommendations.js index a80962f1..44a09113 100644 --- a/src/modules/recommendations.js +++ b/src/modules/recommendations.js @@ -5,9 +5,12 @@ import Promise from 'es6-promise'; const { fetch } = fetchPonyfill({ Promise }); -/* - * Recommendations - * - https://docs.constructor.io +/** + * Interface to recommendations related API calls. + * + * @module recommendations + * @inner + * @returns {object} */ export function recommendations(options) { // Create URL from supplied parameters @@ -79,7 +82,16 @@ export function recommendations(options) { }); return { - // Get alternative item recommendations for supplied query (term) + /** + * Get alternative item recommendations for supplied item id(s) + * + * @function getAlternativeItems + * @param {string|array} itemIds - Item ID(s) to retrieve recommendations for + * @param {object} [parameters] - Additional parameters to refine results + * @param {number} [parameters.results] - The number of results to return + * @returns {Promise} + * @see https://docs.constructor.io/rest-api.html + */ getAlternativeItems: (itemIds, parameters) => { parameters = parameters || {}; parameters.itemIds = itemIds; @@ -87,7 +99,16 @@ export function recommendations(options) { return requestAndProcessResponse(createRecommendationsUrl(parameters, 'alternative_items'), 'alternative_items'); }, - // Get complementary item recommendations for supplied query (term) + /** + * Get complementary item recommendations for supplied item id(s) + * + * @function getComplementaryItems + * @param {string|array} itemIds - Item ID(s) to retrieve recommendations for + * @param {object} [parameters] - Additional parameters to refine results + * @param {number} [parameters.results] - The number of results to return + * @returns {Promise} + * @see https://docs.constructor.io/rest-api.html + */ getComplementaryItems: (itemIds, parameters) => { parameters = parameters || {}; parameters.itemIds = itemIds; @@ -95,10 +116,26 @@ export function recommendations(options) { return requestAndProcessResponse(createRecommendationsUrl(parameters, 'complementary_items'), 'complementary_items'); }, - // Get recently viewed item recommendations for supplied query (term) + /** + * Get recently viewed item recommendations + * + * @function getRecentlyViewedItems + * @param {object} [parameters] - Additional parameters to refine results + * @param {number} [parameters.results] - The number of results to return + * @returns {Promise} + * @see https://docs.constructor.io/rest-api.html + */ getRecentlyViewedItems: (parameters) => requestAndProcessResponse(createRecommendationsUrl(parameters, 'recently_viewed_items'), 'recently_viewed_items'), - // Get user featured item recommendations for supplied query (term) + /** + * Get user featured item recommendations + * + * @function getUserFeaturedItems + * @param {object} [parameters] - Additional parameters to refine results + * @param {number} [parameters.results] - The number of results to return + * @returns {Promise} + * @see https://docs.constructor.io/rest-api.html + */ getUserFeaturedItems: (parameters) => requestAndProcessResponse(createRecommendationsUrl(parameters, 'user_featured_items'), 'user_featured_items'), }; } diff --git a/src/modules/search.js b/src/modules/search.js index 7717cf20..b20eefe5 100644 --- a/src/modules/search.js +++ b/src/modules/search.js @@ -5,9 +5,12 @@ import Promise from 'es6-promise'; const { fetch } = fetchPonyfill({ Promise }); -/* - * Search - * - https://docs.constructor.io/rest-api.html#search +/** + * Interface to search related API calls. + * + * @module search + * @inner + * @returns {object} */ export function search(options) { // Create URL from supplied query (term) and parameters @@ -135,7 +138,20 @@ export function search(options) { }; return { - // Get search results for supplied query (term); + /** + * Retrieve search results from API + * + * @function getSearchResults + * @param {string} query - Term to use to perform a search + * @param {object} [parameters] - Additional parameters to refine result set + * @param {number} [parameters.page] - The page number of the results + * @param {number} [parameters.resultsPerPage] - The number of results per page to return + * @param {object} [parameters.filters] - Filters used to refine search + * @param {string} [parameters.sortBy='relevance'] - The sorting method + * @param {string} [parameters.sortOrder='descending'] - The sort order for search results + * @returns {Promise} + * @see https://docs.constructor.io/rest-api.html#search + */ getSearchResults: (query, parameters) => { const requestUrl = createSearchUrl(query, parameters, options); @@ -163,7 +179,19 @@ export function search(options) { }); }, - // Get browse results + /** + * Retrieve browse results from API + * + * @function getBrowseResults + * @param {object} [parameters] - Additional parameters to refine result set + * @param {number} [parameters.page] - The page number of the results + * @param {number} [parameters.resultsPerPage] - The number of results per page to return + * @param {object} [parameters.filters] - Filters used to refine search + * @param {string} [parameters.sortBy='relevance'] - The sorting method + * @param {string} [parameters.sortOrder='descending'] - The sort order for search results + * @returns {Promise} + * @see https://docs.constructor.io + */ getBrowseResults(parameters) { const requestUrl = createBrowseUrl(parameters);