Feature/encode sdk version (#371)

* Add query param with SDK encoded suffix (_s=...)
* Set default behaviour to false (instead of true), and add a test to enforce it

Author: patrick-tolosa

cloudinary.js

@@ -1,5 +1,7 @@
 if (Number(process.versions.node.split('.')[0]) < 8) {
-  console.warn('DEPRECATION NOTICE - Node 6 has been scheduled for removal from the Cloudinary SDK')
+  console.warn('DEPRECATION NOTICE - Node 6 has been scheduled for removal from the Cloudinary SDK');
+  // required polyfills for native ES6/7 functions (such as String.prototype.padStart)
+  require('core-js');
   module.exports = require('./lib-es5/cloudinary');
 } else {
   module.exports = require('./lib/cloudinary');

lib-es5/utils/encoding/sdkVersionID/base64Map.js

@@ -0,0 +1,18 @@
+'use strict';
+
+function _toConsumableArray(arr) { if (Array.isArray(arr)) { for (var i = 0, arr2 = Array(arr.length); i < arr.length; i++) { arr2[i] = arr[i]; } return arr2; } else { return Array.from(arr); } }
+
+var chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+var num = 0;
+var map = {};
+
+[].concat(_toConsumableArray(chars)).forEach(function (char) {
+  var key = num.toString(2).padStart(6, '0');
+  map[key] = char;
+  num++;
+});
+
+/**
+ * Map of six-bit binary codes to Base64 characters
+ */
+module.exports = map;

lib-es5/utils/encoding/sdkVersionID/encodeVersion.js

@@ -0,0 +1,44 @@
+'use strict';
+
+var base64Map = require('./base64Map');
+var reverseVersion = require('./revereseVersion');
+
+/**
+ * @description Encodes a semVer-like version string
+ * @param {string} semVer Input can be either x.y.z or x.y
+ * @return {string} A string built from 3 characters of the base64 table that encode the semVer
+ */
+function encodeVersion(semVer) {
+  var strResult = '';
+
+  // support x.y or x.y.z by using 'parts' as a variable
+  var parts = semVer.split('.').length;
+  var paddedStringLength = parts * 6; // we pad to either 12 or 18 characters
+
+  // reverse (but don't mirror) the version. 1.5.15 -> 15.5.1
+  // Pad to two spaces, 15.5.1 -> 15.05.01
+  var paddedReversedSemver = reverseVersion(semVer);
+
+  // turn 15.05.01 to a string '150501' then to a number 150501
+  var num = parseInt(paddedReversedSemver.split('.').join(''));
+
+  // Represent as binary, add left padding to 12 or 18 characters.
+  // 150,501 -> 100100101111100101
+  var paddedBinary = num.toString(2).padStart(paddedStringLength, '0');
+
+  // Stop in case an invalid version number was provided
+  // paddedBinary must be built from sections of 6 bits
+  if (paddedBinary.length % 6 !== 0) {
+    throw 'Version must be smaller than 43.21.26)';
+  }
+
+  // turn every 6 bits into a character using the base64Map
+  paddedBinary.match(/.{1,6}/g).forEach(function (bitString) {
+    // console.log(bitString);
+    strResult += base64Map[bitString];
+  });
+
+  return strResult;
+}
+
+module.exports = encodeVersion;

lib-es5/utils/encoding/sdkVersionID/getSDKFeatureCode.js

@@ -0,0 +1,15 @@
+'use strict';
+
+function getSDKFeatureCode() {
+  var features = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+
+  var defaultCode = '0';
+
+  if (features.responsive) {
+    return 'A';
+  }
+
+  return defaultCode;
+}
+
+module.exports = getSDKFeatureCode;

lib-es5/utils/encoding/sdkVersionID/getSDKVersionID.js

@@ -0,0 +1,55 @@
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+var encodeVersion = require('./encodeVersion');
+var getSDKFeatureCode = require('./getSDKFeatureCode');
+var SDKCode = 'M'; // Constant per SDK
+
+
+/**
+ * @description Removes patch version from the semver if it exists
+ *              Turns x.y.z OR x.y into x.y
+ * @param {'x.y.z' || 'x.y' || string} semVerStr
+ */
+function removePatchFromSemver(semVerStr) {
+  var parts = semVerStr.split('.');
+
+  return `${parts[0]}.${parts[1]}`;
+}
+
+/**
+ * @description Gets the SDK signature by encoding the SDK version and node version
+ * @param {{responsive:boolean}} features
+ * @param {'default' | 'x.y.z' | 'x.y' | string} useSDKVersion Default uses package.json version
+ * @param {'default' | 'x.y.z' | 'x.y' | string} useNodeVersion Default uses process.versions.node
+ * @return {string} encodedSDK sdkVersionID
+ */
+function getSDKVersionID() {
+  var features = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  var useSDKVersion = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 'default';
+  var useNodeVersion = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 'default';
+
+  try {
+    // allow to pass a custom SDKVersion
+    var pkgJSONFile = fs.readFileSync(path.join(__dirname, '../../../../package.json'), 'utf-8');
+
+    var sdkVersion = useSDKVersion === 'default' ? JSON.parse(pkgJSONFile).version : useSDKVersion;
+
+    // allow to pass a custom nodeVersion
+    var nodeVersion = useNodeVersion === 'default' ? process.versions.node : useNodeVersion;
+
+    // Node version should always be in x.y format
+    var twoPartNodeVersion = removePatchFromSemver(nodeVersion);
+    var encodedSDKVersion = encodeVersion(sdkVersion);
+    var encodedNodeVersion = encodeVersion(twoPartNodeVersion);
+    var featureCode = getSDKFeatureCode(features);
+
+    return `${SDKCode}${encodedSDKVersion}${encodedNodeVersion}${featureCode}`;
+  } catch (e) {
+    // Either SDK or Node versions were unparsable
+    return 'E';
+  }
+}
+
+module.exports = getSDKVersionID;

lib-es5/utils/encoding/sdkVersionID/revereseVersion.js

@@ -0,0 +1,22 @@
+'use strict';
+
+/**
+ * @description A semVer like string, x.y.z or x.y is allowed
+ *              Reverses the version positions, x.y.z turns to z.y.x
+ *              Pads each segment with '0' so they have length of 2
+ *              Example: 1.2.3 -> 03.02.01
+ * @param {string} semVer Input can be either x.y.z or x.y
+ * @return {string} in the form of zz.yy.xx (
+ */
+function reverseVersion(semVer) {
+  if (semVer.split('.').length < 2) {
+    throw new Error('invalid semVer, must have at least two segments');
+  }
+
+  // Split by '.', reverse, create new array with padded values and concat it together
+  return semVer.split('.').reverse().map(function (segment) {
+    return segment.padStart(2, '0');
+  }).join('.');
+}
+
+module.exports = reverseVersion;

lib-es5/utils/ensureOption.js

@@ -1,4 +1,4 @@
-"use strict";
+'use strict';
 
 /**
  * Returns an ensureOption function that relies on the provided `defaultOptions` argument
@@ -9,10 +9,18 @@
  */
 function defaults(defaultOptions) {
   return function ensureOption(options, name, defaultValue) {
-    var value = options[name] || defaultOptions[name] || defaultValue;
-    if (value === undefined) {
+    var value = void 0;
+
+    if (typeof options[name] !== 'undefined') {
+      value = options[name];
+    } else if (typeof defaultOptions[name] !== 'undefined') {
+      value = defaultOptions[name];
+    } else if (typeof defaultValue !== 'undefined') {
+      value = defaultValue;
+    } else {
       throw `Must supply ${name}`;
     }
+
     return value;
   };
 }

lib-es5/utils/index.js

@@ -55,6 +55,7 @@ var ensurePresenceOf = require('./ensurePresenceOf');
 var ensureOption = require('./ensureOption').defaults(config());
 var entries = require('./entries');
 var isRemoteUrl = require('./isRemoteUrl');
+var getSDKVersionID = require('./encoding/sdkVersionID/getSDKVersionID');
 
 exports = module.exports;
 var utils = module.exports;
@@ -776,6 +777,22 @@ function url(public_id) {
     var token = generate_token(auth_token);
     resultUrl += `?${token}`;
   }
+
+  var analytics = ensureOption(options, 'analytics', false);
+  var responsive = ensureOption(options, 'responsive', false);
+
+  if (analytics === true) {
+    var sdkVersionID = getSDKVersionID({
+      responsive
+    });
+    // url might already have a '?' query param
+    var appender = '?';
+    if (resultUrl.indexOf('?') >= 0) {
+      appender = '&';
+    }
+    resultUrl = `${resultUrl}${appender}_s=${sdkVersionID}`;
+  }
+
   return resultUrl;
 }
 

lib/utils/encoding/sdkVersionID/base64Map.js

@@ -0,0 +1,15 @@
+let chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+let num = 0;
+let map = {};
+
+[...chars].forEach((char) => {
+  let key = num.toString(2).padStart(6, '0');
+  map[key] = char;
+  num++;
+});
+
+
+/**
+ * Map of six-bit binary codes to Base64 characters
+ */
+module.exports = map;

lib/utils/encoding/sdkVersionID/encodeVersion.js

@@ -0,0 +1,42 @@
+let base64Map = require('./base64Map');
+let reverseVersion = require('./revereseVersion');
+
+/**
+ * @description Encodes a semVer-like version string
+ * @param {string} semVer Input can be either x.y.z or x.y
+ * @return {string} A string built from 3 characters of the base64 table that encode the semVer
+ */
+function encodeVersion(semVer) {
+  let strResult = '';
+
+  // support x.y or x.y.z by using 'parts' as a variable
+  let parts = semVer.split('.').length;
+  let paddedStringLength = parts * 6; // we pad to either 12 or 18 characters
+
+  // reverse (but don't mirror) the version. 1.5.15 -> 15.5.1
+  // Pad to two spaces, 15.5.1 -> 15.05.01
+  let paddedReversedSemver = reverseVersion(semVer);
+
+  // turn 15.05.01 to a string '150501' then to a number 150501
+  let num = parseInt(paddedReversedSemver.split('.').join(''));
+
+  // Represent as binary, add left padding to 12 or 18 characters.
+  // 150,501 -> 100100101111100101
+  let paddedBinary = num.toString(2).padStart(paddedStringLength, '0');
+
+  // Stop in case an invalid version number was provided
+  // paddedBinary must be built from sections of 6 bits
+  if (paddedBinary.length % 6 !== 0) {
+    throw 'Version must be smaller than 43.21.26)';
+  }
+
+  // turn every 6 bits into a character using the base64Map
+  paddedBinary.match(/.{1,6}/g).forEach((bitString) => {
+    // console.log(bitString);
+    strResult += base64Map[bitString];
+  });
+
+  return strResult;
+}
+
+module.exports = encodeVersion;