Allow 'multi' and 'sprite' with urls, add 'download_generated_sprite' and 'download_multi' methods (#493)

Author: YomesInc

lib-es5/uploader.js

@@ -288,36 +288,83 @@ exports.text = function text(content, callback) {
   });
 };
 
+/**
+ * Generate a sprite by merging multiple images into a single large image for reducing network overhead and bypassing
+ * download limitations.
+ *
+ * The process produces 2 files as follows:
+ * - A single image file containing all the images with the specified tag (PNG by default).
+ * - A CSS file that includes the style class names and the location of the individual images in the sprite.
+ *
+ * @param {String|Object} tag     A string specifying a tag that indicates which images to include or an object
+ *                                which includes options and image URLs.
+ * @param {Function}     callback   Callback function
+ * @param {Object}       options  Configuration options. If options are passed as the first parameter, this parameter
+ *                                should be empty
+ *
+ * @return {Object}
+ */
 exports.generate_sprite = function generate_sprite(tag, callback) {
   var options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
 
   return call_api("sprite", callback, options, function () {
-    var transformation = utils.generate_transformation_string(extend({}, options, {
-      fetch_format: options.format
-    }));
-    return [{
-      timestamp: utils.timestamp(),
-      tag: tag,
-      transformation: transformation,
-      async: options.async,
-      notification_url: options.notification_url
-    }];
+    return [utils.build_multi_and_sprite_params(tag, options)];
   });
 };
 
+/**
+ * Returns a signed url to download a sprite
+ *
+ * @param {String|Object} tag     A string specifying a tag that indicates which images to include or an object
+ *                                which includes options and image URLs.
+ * @param {Object}       options  Configuration options. If options are passed as the first parameter, this parameter
+ *                                should be empty
+ *
+ * @returns {string}
+ */
+exports.download_generated_sprite = function download_generated_sprite(tag) {
+  var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+
+  return utils.api_download_url("sprite", utils.build_multi_and_sprite_params(tag, options), options);
+};
+
+/**
+ * Returns a signed url to download a single animated image (GIF, PNG or WebP), video (MP4 or WebM) or a single PDF from
+ * multiple image assets.
+ *
+ * @param {String|Object} tag     A string specifying a tag that indicates which images to include or an object
+ *                                which includes options and image URLs.
+ * @param {Object}       options  Configuration options. If options are passed as the first parameter, this parameter
+ *                                should be empty
+ *
+ * @returns {string}
+ */
+exports.download_multi = function download_multi(tag) {
+  var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+
+  return utils.api_download_url("multi", utils.build_multi_and_sprite_params(tag, options), options);
+};
+
+/**
+ * Creates either a single animated image (GIF, PNG or WebP), video (MP4 or WebM) or a single PDF from multiple image
+ * assets.
+ *
+ * Each asset is included as a single frame of the resulting animated image/video, or a page of the PDF (sorted
+ * alphabetically by their Public ID).
+ *
+ * @param {String|Object} tag     A string specifying a tag that indicates which images to include or an object
+ *                                which includes options and image URLs.
+ * @param {Function}     callback   Callback function
+ * @param {Object}       options  Configuration options. If options are passed as the first parameter, this parameter
+ *                                should be empty
+ *
+ * @return {Object}
+ */
 exports.multi = function multi(tag, callback) {
   var options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
 
   return call_api("multi", callback, options, function () {
-    var transformation = utils.generate_transformation_string(extend({}, options));
-    return [{
-      timestamp: utils.timestamp(),
-      tag: tag,
-      transformation: transformation,
-      format: options.format,
-      async: options.async,
-      notification_url: options.notification_url
-    }];
+    return [utils.build_multi_and_sprite_params(tag, options)];
   });
 };
 

lib-es5/utils/index.js

@@ -313,6 +313,38 @@ function process_radius(radius) {
   return radius.map(normalize_expression).join(':');
 }
 
+function build_multi_and_sprite_params(tagOrOptions, options) {
+  var tag = null;
+  if (typeof tagOrOptions === 'string') {
+    tag = tagOrOptions;
+  } else {
+    if (isEmpty(options)) {
+      options = tagOrOptions;
+    } else {
+      throw new Error('First argument must be a tag when additional options are passed');
+    }
+    tag = null;
+  }
+  if (!options && !tag) {
+    throw new Error('Either tag or urls are required');
+  }
+  if (!options) {
+    options = {};
+  }
+  var urls = options.urls;
+  var transformation = generate_transformation_string(extend({}, options, {
+    fetch_format: options.format
+  }));
+  return {
+    tag,
+    transformation,
+    urls,
+    timestamp: utils.timestamp(),
+    async: options.async,
+    notification_url: options.notification_url
+  };
+}
+
 function build_upload_params(options) {
   var params = {
     access_mode: options.access_mode,
@@ -1178,6 +1210,18 @@ function download_backedup_asset(asset_id, version_id) {
   return exports.base_api_url(['download_backup'], options) + "?" + hashToQuery(params);
 }
 
+/**
+ * Utility method to create a signed URL for specified resources.
+ * @param action
+ * @param params
+ * @param options
+ */
+function api_download_url(action, params, options) {
+  var download_params = _extends({}, params, { mode: "download" });
+  var cloudinary_params = exports.sign_request(download_params, options);
+  return exports.api_url(action, options) + "?" + hashToQuery(cloudinary_params);
+}
+
 /**
  * Returns a URL that when invokes creates an archive and returns it.
  * @param {object} options
@@ -1215,10 +1259,10 @@ function download_backedup_asset(asset_id, version_id) {
 function download_archive_url() {
   var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
 
-  var cloudinary_params = exports.sign_request(exports.archive_params(merge(options, {
+  var params = exports.archive_params(merge(options, {
     mode: "download"
-  })), options);
-  return exports.api_url("generate_archive", options) + "?" + hashToQuery(cloudinary_params);
+  }));
+  return api_download_url("generate_archive", params, options);
 }
 
 /**
@@ -1597,6 +1641,8 @@ exports.NOP = function () {};
 exports.generate_auth_token = generate_auth_token;
 exports.getUserAgent = getUserAgent;
 exports.build_upload_params = build_upload_params;
+exports.build_multi_and_sprite_params = build_multi_and_sprite_params;
+exports.api_download_url = api_download_url;
 exports.timestamp = function () {
   return Math.floor(new Date().getTime() / 1000);
 };

lib-es5/v2/uploader.js

@@ -35,4 +35,6 @@ exports.upload_tag_params = uploader.upload_tag_params;
 exports.upload_url = uploader.upload_url;
 exports.image_upload_tag = uploader.image_upload_tag;
 exports.unsigned_image_upload_tag = uploader.unsigned_image_upload_tag;
-exports.create_slideshow = uploader.create_slideshow;
+exports.create_slideshow = uploader.create_slideshow;
+exports.download_generated_sprite = uploader.download_generated_sprite;
+exports.download_multi = uploader.download_multi;

lib/uploader.js

@@ -239,36 +239,76 @@ exports.text = function text(content, callback, options = {}) {
   });
 };
 
+/**
+ * Generate a sprite by merging multiple images into a single large image for reducing network overhead and bypassing
+ * download limitations.
+ *
+ * The process produces 2 files as follows:
+ * - A single image file containing all the images with the specified tag (PNG by default).
+ * - A CSS file that includes the style class names and the location of the individual images in the sprite.
+ *
+ * @param {String|Object} tag     A string specifying a tag that indicates which images to include or an object
+ *                                which includes options and image URLs.
+ * @param {Function}     callback   Callback function
+ * @param {Object}       options  Configuration options. If options are passed as the first parameter, this parameter
+ *                                should be empty
+ *
+ * @return {Object}
+ */
 exports.generate_sprite = function generate_sprite(tag, callback, options = {}) {
   return call_api("sprite", callback, options, function () {
-    const transformation = utils.generate_transformation_string(extend({}, options, {
-      fetch_format: options.format
-    }));
-    return [
-      {
-        timestamp: utils.timestamp(),
-        tag: tag,
-        transformation: transformation,
-        async: options.async,
-        notification_url: options.notification_url
-      }
-    ];
+    return [utils.build_multi_and_sprite_params(tag, options)];
   });
 };
 
+
+/**
+ * Returns a signed url to download a sprite
+ *
+ * @param {String|Object} tag     A string specifying a tag that indicates which images to include or an object
+ *                                which includes options and image URLs.
+ * @param {Object}       options  Configuration options. If options are passed as the first parameter, this parameter
+ *                                should be empty
+ *
+ * @returns {string}
+ */
+exports.download_generated_sprite = function download_generated_sprite(tag, options = {}) {
+  return utils.api_download_url("sprite", utils.build_multi_and_sprite_params(tag, options), options);
+}
+
+/**
+ * Returns a signed url to download a single animated image (GIF, PNG or WebP), video (MP4 or WebM) or a single PDF from
+ * multiple image assets.
+ *
+ * @param {String|Object} tag     A string specifying a tag that indicates which images to include or an object
+ *                                which includes options and image URLs.
+ * @param {Object}       options  Configuration options. If options are passed as the first parameter, this parameter
+ *                                should be empty
+ *
+ * @returns {string}
+ */
+exports.download_multi = function download_multi(tag, options = {}) {
+  return utils.api_download_url("multi", utils.build_multi_and_sprite_params(tag, options), options);
+}
+
+/**
+ * Creates either a single animated image (GIF, PNG or WebP), video (MP4 or WebM) or a single PDF from multiple image
+ * assets.
+ *
+ * Each asset is included as a single frame of the resulting animated image/video, or a page of the PDF (sorted
+ * alphabetically by their Public ID).
+ *
+ * @param {String|Object} tag     A string specifying a tag that indicates which images to include or an object
+ *                                which includes options and image URLs.
+ * @param {Function}     callback   Callback function
+ * @param {Object}       options  Configuration options. If options are passed as the first parameter, this parameter
+ *                                should be empty
+ *
+ * @return {Object}
+ */
 exports.multi = function multi(tag, callback, options = {}) {
   return call_api("multi", callback, options, function () {
-    const transformation = utils.generate_transformation_string(extend({}, options));
-    return [
-      {
-        timestamp: utils.timestamp(),
-        tag: tag,
-        transformation: transformation,
-        format: options.format,
-        async: options.async,
-        notification_url: options.notification_url
-      }
-    ];
+    return [utils.build_multi_and_sprite_params(tag, options)];
   });
 };
 

lib/utils/index.js

@@ -292,6 +292,38 @@ function process_radius(radius) {
   return radius.map(normalize_expression).join(':');
 }
 
+function build_multi_and_sprite_params(tagOrOptions, options) {
+  let tag = null;
+  if (typeof tagOrOptions === 'string') {
+    tag = tagOrOptions;
+  } else {
+    if (isEmpty(options)) {
+      options = tagOrOptions;
+    } else {
+      throw new Error('First argument must be a tag when additional options are passed');
+    }
+    tag = null;
+  }
+  if (!options && !tag) {
+    throw new Error('Either tag or urls are required')
+  }
+  if (!options) {
+    options = {}
+  }
+  const urls = options.urls
+  const transformation = generate_transformation_string(extend({}, options, {
+    fetch_format: options.format
+  }));
+  return {
+    tag,
+    transformation,
+    urls,
+    timestamp: utils.timestamp(),
+    async: options.async,
+    notification_url: options.notification_url
+  };
+}
+
 function build_upload_params(options) {
   let params = {
     access_mode: options.access_mode,
@@ -1081,6 +1113,18 @@ function download_backedup_asset(asset_id, version_id, options = {}) {
   return exports.base_api_url(['download_backup'], options) + "?" + hashToQuery(params);
 }
 
+/**
+ * Utility method to create a signed URL for specified resources.
+ * @param action
+ * @param params
+ * @param options
+ */
+function api_download_url(action, params, options) {
+  const download_params = {...params, mode: "download"}
+  let cloudinary_params = exports.sign_request(download_params, options);
+  return exports.api_url(action, options) + "?" + hashToQuery(cloudinary_params);
+}
+
 /**
  * Returns a URL that when invokes creates an archive and returns it.
  * @param {object} options
@@ -1116,10 +1160,10 @@ function download_backedup_asset(asset_id, version_id, options = {}) {
  * @return {String} archive url
  */
 function download_archive_url(options = {}) {
-  let cloudinary_params = exports.sign_request(exports.archive_params(merge(options, {
+  const params = exports.archive_params(merge(options, {
     mode: "download"
-  })), options);
-  return exports.api_url("generate_archive", options) + "?" + hashToQuery(cloudinary_params);
+  }))
+  return api_download_url("generate_archive", params, options)
 }
 
 /**
@@ -1463,6 +1507,8 @@ exports.NOP = function () {};
 exports.generate_auth_token = generate_auth_token;
 exports.getUserAgent = getUserAgent;
 exports.build_upload_params = build_upload_params;
+exports.build_multi_and_sprite_params = build_multi_and_sprite_params;
+exports.api_download_url = api_download_url;
 exports.timestamp = () => Math.floor(new Date().getTime() / 1000);
 exports.option_consume = consumeOption; // for backwards compatibility
 exports.build_array = toArray; // for backwards compatibility

lib/v2/uploader.js

@@ -34,3 +34,5 @@ exports.upload_url = uploader.upload_url;
 exports.image_upload_tag = uploader.image_upload_tag;
 exports.unsigned_image_upload_tag = uploader.unsigned_image_upload_tag;
 exports.create_slideshow = uploader.create_slideshow;
+exports.download_generated_sprite = uploader.download_generated_sprite;
+exports.download_multi = uploader.download_multi;