bv-ui-core 0.1.1

package/lib/api/statistics.js

@@ -0,0 +1,148 @@
+/* global fetch */
+/**
+ * @fileOverview Module for interacting with the statistcs.json endpoint.
+ *
+ */
+const envPrefixMap = {
+  qa: 'qa.api',
+  staging: 'stg.api',
+  production: 'api'
+};
+
+// Default configuration
+const API_VERSION = 5.4;
+const MAX_REQUESTED_IDS = 100;
+
+/**
+ * Calls the statistics.json API with provided options. Returns a promise that
+ * is fulfilled with an array of Results from the API or rejected with the error
+ * message.
+ *
+ * Example:
+ *
+ * getStatistics({
+ *  productIds: ['product1', 'product2', 'product3'],
+ *  environment: 'qa',
+ *  key: 'clients_api_key',
+ *  type: 'Reviews',
+ *  filters: {
+ *   ContentLocale: 'en_US'
+ *  }
+ * }).then(results => {
+ *   // Do something with results
+ * }, errorMsg => {
+ *   // Do something with error.
+ * })
+ *
+ * https://developer.bazaarvoice.com/docs/read/conversations/statistics/display/5_4
+ *
+ * @param  {Object} options object that contains options
+ * @param  {Array}  options.productIds - array of product IDs
+ * @param  {Array}  options.environment - the data environment
+ * @param  {Array}  options.key - client's api key
+ * @param  {string}  options.type - Using "Reviews" returns statistics for all
+ *         content, including syndicated content (if enabled on your API key).
+ *         If you only want statistics for reviews you own that were written for
+ *         the products specified, use "NativeReviews" instead.
+ * @param  {Object}  [options.filters] - Filters object. Keyed by filter name.
+ * @return {Promise} a promise that will be resolved with the raw results
+ *                   from the statistics call.
+ */
+function getStatistics ({
+  productIds,
+  environment,
+  key,
+  type,
+  incentivized = false,
+  filters = {}
+}) {
+  if (!productIds || !Array.isArray(productIds)) {
+    throw new TypeError('productIds must be an array');
+  }
+
+  const envPrefix = envPrefixMap[environment];
+  if (!envPrefix) {
+    throw new TypeError('environment must be "qa", "staging", or "production"');
+  }
+
+  if (!key) {
+    throw new TypeError('key must be provided');
+  }
+
+  if (!type || !(type === 'Reviews' || type === 'NativeReviews')) {
+    throw new TypeError('type must be "Reviews" or "NativeReviews"');
+  }
+
+  let uri =
+    `https://${envPrefix}.bazaarvoice.com/data/statistics.json` +
+    `?apiversion=${API_VERSION}` +
+    `&passkey=${key}` +
+    `&stats=${type}` +
+    Object.keys(filters)
+      .map(filter => `&filter=${filter}:${filters[filter]}`)
+      .join();
+
+  // We should add `incentivizedStats` request param in case
+  // if `incentivized` flag is enabled that means such reviews
+  // have to be loaded in response 
+  if (incentivized) {
+    uri = uri + `&incentivizedStats=${incentivized}`;
+  }
+
+  // Clone the productIds so we can manipulate it.
+  productIds = [...productIds];
+  const productIdChunks = [];
+
+  if (productIds.length > 100) {
+    console.warn('Requesting more than 100 products is not recommended!');
+  }
+
+  while (productIds.length > 0) {
+    productIdChunks.push(productIds.splice(0, MAX_REQUESTED_IDS));
+  }
+
+  return Promise.all(
+    productIdChunks.map(
+      products =>
+        new Promise((resolve, reject) => {
+          const requestUri = `${uri}&filter=ProductId:${products.join(',')}`;
+          return fetch(requestUri)
+            .then(response => response.json())
+            .then(json => {
+              // If there are errors in the actual response body (from API)
+              // we need to handle them here.
+              if (json.HasErrors) {
+                let errors = json.Errors;
+                // If for some reason errors is empty or doesn't exist,
+                if (!errors || !Array.isArray(errors) || errors.length <= 0) {
+                  reject({
+                    Message: 'An unknown error occurred.',
+                    Code: 'ERROR_UNKNOWN',
+                  });
+                } 
+                else {
+                  // We can reasonably assume that if an error occurred for this
+                  // request it should only have a single error response
+                  // unlike submission api errors, which have multiples.
+                  reject(json.Errors[0]);
+                }
+              } 
+              else {
+                resolve(json.Results);
+              }
+            });
+        })
+    )
+  ).then(results => {
+    if (results.length === 0) {
+      return results;
+    } 
+    else {
+      return results.reduce((a, b) => {
+        return a.concat(b);
+      });
+    }
+  });
+}
+
+module.exports = getStatistics;

package/lib/application/README.md

@@ -0,0 +1,96 @@
+# application
+
+The application module provides an Application class that provides methods to
+queue your users' calls until the actual code to support those calls is
+present.
+
+For example, your user may expect to be able to ask your application to render
+immediately after this initial application module is loaded, even though the
+code to perform the rendering has not yet loaded.
+
+The application module is typically used in conjunction with the
+[loader][1] module, [namespacer][2] module, and some configuration data, as
+shown here. Once you create an application instance, it is good practice to add
+it as a property to a namespace:
+
+```js
+var Application = require('bv-ui-core/lib/application');
+var loader = require('bv-ui-core/lib/loader');
+var namespacer = require('bv-ui-core/lib/namespacer');
+var config = require('json!config.json');
+
+// Creates a namespace at window.APP and an application object at
+// window.APP.exampleApp. The config object will be available at
+// window.APP.exampleApp.config.
+namespacer.namespace('APP').registerProperty(
+  'exampleApp',
+  new Application(config)
+);
+
+// Now load following code.
+// loader.load(url).then( ... do something ... );
+```
+
+## ES6 Considerations
+
+This module takes advantage of Promises, which you may need to [polyfill][3]:
+
+- `Promise`: http://caniuse.com/#feat=promises
+
+## Methods to be Called by Users
+
+An application instance provides the following methods:
+
+- `ready(callback)`: (optional) A method intended for your users to call at
+  any time in order to register a callback which will be invoked as soon as
+  your application has been loaded and its API is available to be used.
+  Callback function should be a standard Node errback signature, where its
+  first expected parameter will be an error (if applicable), and its second
+  parameter will be the application instance. The return value is a Promise
+  that you can chain your callbacks onto. The success callbacks (on your
+  `then` Promise chain) will only be given a single input parameter, the
+  application instance, and your failure callbacks (on your `catch` Promise
+  chain) will only be given a single input parameter,
+  the error.
+
+  Note: If you opt to mix and match the callback and the Promise interfaces,
+  be aware that all registered callbacks passed *to* the `ready` function
+  will be executed first, in the order in which they were attached, and then
+  the Promise chain will be resolved or rejected, which will in turn trigger
+  callbacks on the appropriate `then` or `catch` chain.
+
+- `render(config)`: A method intended for your users to call any time after
+  this application module is loaded, passing in configuration information
+  related to a request to render your application.
+
+```js
+APP.exampleApp.render({ productId : 1 });
+```
+
+- `configure(config)`: A method intended for your users to call any time after
+  the application code is loaded, passing in general configuration information
+  not necessarily related to rendering.
+
+## Methods to Be Called by Core Application Code
+
+- `processReady(error)`: A method that your core application code can call in
+  order to access calls to `ready` that have occurred. The only parameter it
+  accepts is an optional one, a load error to be passed to the callbacks in
+  its queue, and to reject its Promise with. It will, from that point on,
+  process all callbacks immediately when passed to the `ready` method. Queued
+  items are processed synchronously, so if your callback is a long-running
+  process, you might want to consider wrapping it in a setTimeout.
+- `processQueue(fn)`: A method that your core application code can call in
+  order to access calls to `render` that have occurred; the provided function
+  will be used to handle those calls, and will then replace the original
+  definition of the `render` method. Queued items are processed on the next
+  tick.
+- `processConfig(fn)`: A method that your core application code can call in
+  order to access calls to `configure` that have occurred; the provided
+  function will be used to handle those calls, and will then replace the
+  original definition of the `configure` method. Queued items are processed
+  synchronously, as they are not expected to have any DOM implications.
+
+[1]: ../loader
+[2]: ../namespacer
+[3]: https://github.com/stefanpenner/es6-promise

package/lib/application/index.js

@@ -0,0 +1,171 @@
+/**
+ * @fileOverview
+ * A module that provides a minimalist application class, useful for managing
+ * configuration and rendering.
+ */
+
+// --------------------------------------------------------------------------
+// Functions.
+// --------------------------------------------------------------------------
+
+/**
+ * Process a queue.
+ *
+ * @param {Mixed[]} queue An array of queued items.
+ * @param {Function} fn The function to process queue items.
+ * @param {Boolean} sync If true, process synchronously.
+ */
+function processQueue (queue, fn, sync) {
+  if (typeof fn !== 'function') {
+    throw new Error('A function must be provided to process the queue');
+  }
+
+  var originalLength = queue.length;
+
+  function dequeue () {
+    var queueItem = queue.shift();
+
+    if (sync) {
+      fn(queueItem);
+      return;
+    }
+
+    setTimeout(function () {
+      fn(queueItem);
+    }, 0);
+  }
+
+  while (queue.length > 0) {
+    dequeue();
+  }
+
+  return originalLength;
+}
+
+// --------------------------------------------------------------------------
+// Application class definition.
+// --------------------------------------------------------------------------
+
+/**
+ * @class
+ * An application framework capable of managing render and configuration queues.
+ *
+ * @param {Object} config Application configuration.
+ */
+function Application (config) {
+  this.config = config;
+  this._readyQueue = [];
+  this._renderQueue = [];
+  this._configQueue = [];
+  this._promise = new Promise(function (resolve, reject) {
+    this._resolve = resolve;
+    this._reject = reject;
+  }.bind(this));
+  return this;
+}
+
+/**
+ * A method that can be called before the "real" application is
+ * loaded; its job is to queue the ready callbacks that are passed,
+ * so that they can be called when the real app arrives.
+ */
+Application.prototype.ready = function (callback) {
+  if (typeof callback === 'function') {
+    this._readyQueue.push(callback);
+  }
+
+  return this._promise;
+};
+
+/**
+ * A method that can be called before the "real" application is
+ * loaded; its job is to queue the render configuration objects that
+ * are passed, so that they can be handled when the real app arrives.
+ */
+Application.prototype.render = function (config) {
+  return this._renderQueue.push(config);
+};
+
+/**
+ * A method that can be called before the "real" application is
+ * loaded; its job is to queue the applicaiton configuration objects
+ * that are passed, so that they can be handled when the real app
+ * arrives.
+ */
+Application.prototype.configure = function (config) {
+  return this._configQueue.push(config);
+};
+
+/**
+ * The function to be passed to our processQueue function when processing
+ * ready callbacks below.
+ */
+var processReadyFn = function (err, callback) {
+  if (typeof callback === 'function') {
+    callback(err, this);
+  }
+};
+
+/**
+ * To be called by the real application once it is loaded and its API
+ * is fully available to consumers. It processes any passed callbacks as a
+ * queue, then redefines the ready method to process incoming callbacks
+ * immediately. If the current runtime also supports Promises, this will
+ * return a Promise handle that can be used to queue up additional callbacks.
+ *
+ * @param  [Function] callback An optional function to be queued for
+ * processing. Any queued callbacks will be processed prior to resolving the
+ * Promise, if Promises are supported.
+ * @return {Promise} A Promise handle to use for additional callbacks.
+ */
+Application.prototype.processReady = function (err) {
+  var processReady = processReadyFn.bind(this, err);
+  processQueue.call(this, this._readyQueue, processReady, true);
+
+  this._readyQueue.push = processReady;
+
+  this.ready = function (callback) {
+    processReady(callback);
+    return this._promise;
+  };
+  if (err) {
+    this._reject(err);
+  }
+  else {
+    this._resolve(this);
+  }
+};
+
+/**
+ * To be called by the real application once it is ready to handle
+ * queued render calls. It processes the queue using the provided
+ * handler, then redefines the render method using the provided handler.
+ *
+ * @param  {Function} fn The function to handle the queued items; this function
+ * will also effectively replace the render method.
+ * @return {Number} The number of items that were queued.
+ */
+Application.prototype.processQueue = function (fn) {
+  processQueue.call(this, this._renderQueue, fn);
+  this.render = this._renderQueue.push = fn;
+};
+
+/**
+ * To be called by the real application once it is ready to handle
+ * queued configure calls. It processes the queue using the provided
+ * handler, then redefines the configure method using the provided handler.
+ *
+ * @param {Function} fn The function to handle the queued items; this function
+ *   will also effectively replace the configure method.
+ * @return {Number} The number of items that were queued.
+ */
+Application.prototype.processConfig = function (fn) {
+  processQueue.call(this, this._configQueue, fn, true);
+  this.configure = this._configQueue.push = fn;
+};
+
+// --------------------------------------------------------------------------
+// Exports class definition.
+// --------------------------------------------------------------------------
+
+module.exports = Application;

package/lib/body/README.md

@@ -0,0 +1,13 @@
+# Body
+
+This is a shorthand method for accessing the `<body>` element within the
+document. Not only is it shorter, it returns the current body of the current
+context. Also useful in non-browser environments by overloading the function to
+return an appropriate element.
+
+## Usage
+```javascript
+var body = require('body');
+
+var body = body();
+```

package/lib/body/index.js

@@ -0,0 +1,19 @@
+/**
+ * @fileOverview
+ * Provides a function to retrieve the body of the current document.
+ *
+ * https://dojotoolkit.org/reference-guide/1.7/dojo/body.html
+ */
+
+// Imports
+var global = require('../global');
+
+var cachedBody;
+
+module.exports = function () {
+  // In some browsers (<= IE8) it is possible to have your code execute before document.body has been populated.
+  // For that reason, we use a fallback of `getElementsByTagName` -- and because it is possible to have multiple
+  // body elements in one page, we specify the first element in the resulting array.
+  cachedBody = cachedBody || global.document.body || global.document.getElementsByTagName('body')[0];
+  return cachedBody;
+};

package/lib/bvFetch/README.md

@@ -0,0 +1,101 @@
+# BvFetch
+
+The BvFetch module provides methods to cache duplicate API calls and interact with the cacheStorage
+
+
+## The following methods are provided:
+
+## BvFetch Parameters
+`shouldCache (Function):` A function that takes the API response JSON as input and returns a boolean indicating whether to cache the response or not. This allows you to implement custom logic based on the response content. If caching is desired, the function should return true; otherwise, false.
+`cacheName (String):` Optional. Specifies the name of the cache to be used. If not provided, the default cache name 'bvCache' will be used.
+`cacheLimit (Integer)`: Optional. Specifies the cache size limit for the cache storage. Its value should be in MB. Default value is 10 MB.
+`excludeHeaders (Array[String])`: Includes the list of headers that are excluded from the cacheKey
+
+
+## bvFetchFunc Method Parameters
+`url (String):` The URL of the API endpoint to fetch data from.
+`options (Object):` Optional request options such as headers, method, etc., as supported by the Fetch API.
+
+## bvFetchFunc Return Value
+`Promise<Response>:` A promise that resolves to the API response. If the response is cached, it returns the cached response. Otherwise, it fetches data from the API endpoint, caches the response according to the caching logic, and returns the fetched response.
+
+## generateCacheKey Method
+
+Generates a cache key as a Request object for a given URL and options, filtering out any headers specified in `excludeHeaders`.
+
+**Parameters:**
+- `url (String)`: The URL of the API endpoint.
+- `options (Object)`: *(Optional)* Request options (e.g., headers, method, etc.).
+
+**Returns:**  
+`Request`: The generated Request object to be used as a cache key.
+
+## retrievecachedRequests Method
+Retrieves cached Requests from the cache storage associated with the provided cache name.
+## retrievecachedRequests Parameters
+This method takes no parameters.
+## retrievecachedRequests Return Value
+`void:` This method does not return anything.
+
+## fetchDataAndCache Method
+Fetches data from the specified URL, caches the response, and returns the response.
+## Parameters
+`url (String):` The URL from which to fetch data.
+`options (Object):` Optional request options such as headers, method, etc., as supported by the 
+Fetch API.
+`cacheKey (String):`
+ The cache key associated with the fetched data.
+## Return Value
+`Promise<Response>:` A promise that resolves to the fetched response.
+
+## fetchFromCache Method
+Function to fetch data from cache.
+## Parameters
+`cacheKey (String):` The cache key to fetch data from the cache.
+## Return Value
+Promise<Response|null>: A Promise that resolves with a Response object if the data is found in cache, or null if the data is not cached or expired.
+
+## cacheData Method
+Caches the provided response with the specified cache key if it meets the criteria for caching.
+## Parameters
+`response (Response):` The response object to be cached.
+`cacheKey (String):` The cache key associated with the response.
+## Return Value
+`void:` This method does not return anything.
+
+
+## flushCache Method Parameters
+This method takes no parameters.
+## flushCache Return Value
+`Promise<void>:` A promise indicating the completion of cache flush operation.
+
+## manageCache Method
+Manages the cache by deleting expired cache entries and maintaining the cache size limit.
+## Parameters
+This method takes no parameters.
+## Return Value
+`void:` This method does not return anything.
+
+
+## Usage with of `BvFetch`:
+
+```js
+var BvFetch = require('bv-ui-core/lib/bvFetch')
+
+// Initialize BV Fetch instance
+const bvFetch = new BVFetch({
+   shouldCache: function(responseJson) => { /* return true or false */ }, // optional, callback function to check if the response is cachable
+   cacheName: "bvCache" // optional, default is "bvCache"
+   cacheLimit: 10, // optional but default is 10
+   excludeHeaders: [], // optional, list of headers to be excluded from cache
+});
+
+// Make API calls using bvFetchFunc method
+bvFetch.bvFetchFunc('https://api.example.com/data')
+  .then(response => {
+    // Handle response
+  })
+  .catch(error => {
+    // Handle error
+  });
+  ```