feat: new upload parameter - regions

lib/utils/index.js

@@ -35,6 +35,7 @@ const consumeOption = require('./parsing/consumeOption');
 const toArray = require('./parsing/toArray');
 let {base64EncodeURL} = require('./encoding/base64EncodeURL');
 const encodeDoubleArray = require('./encoding/encodeDoubleArray');
+const encodeRegions = require('./encoding/encodeRegions');
 
 const config = require("../config");
 const generate_token = require("../auth_token");
@@ -416,6 +417,7 @@ function build_upload_params(options) {
     use_asset_folder_as_public_id_prefix: utils.as_safe_bool(options.use_asset_folder_as_public_id_prefix),
     visual_search: utils.as_safe_bool(options.visual_search),
     on_success: options.on_success
+    // regions: options.regions
   };
   return utils.updateable_resource_params(options, params);
 }
@@ -720,6 +722,9 @@ function updateable_resource_params(options, params = {}) {
   if (options.visual_search != null) {
     params.visual_search = options.visual_search;
   }
+  if (options.regions != null) {
+    params.regions = encodeRegions(options.regions);
+  }
   return params;
 }
 

test/integration/api/uploader/custom_region_spec.js

@@ -0,0 +1,64 @@
+const assert = require('assert');
+const sinon = require('sinon');
+
+const cloudinary = require('../../../../lib/cloudinary');
+const createTestConfig = require('../../../testUtils/createTestConfig');
+const helper = require('../../../spechelper');
+
+describe('Uploader', () => {
+  beforeEach(function () {
+    cloudinary.config(true);
+    cloudinary.config(createTestConfig());
+  });
+
+  it('should upload with custom region gravity that represents a box', () => {
+    const boxRegionGravityEncoded = '{box_1}1,2,3,4|{box_2}5,6,7,8';
+
+    return helper.provideMockObjects(function (mockXHR, writeSpy, requestSpy) {
+      helper.uploadImage({
+        regions: {
+          'box_1': [[1, 2], [3, 4]],
+          'box_2': [[5, 6], [7, 8]]
+        }
+      });
+
+      sinon.assert.calledWith(requestSpy, sinon.match({
+        method: sinon.match('POST')
+      }));
+
+      sinon.assert.calledWith(writeSpy, sinon.match(helper.uploadParamMatcher('regions', boxRegionGravityEncoded)));
+    });
+  });
+
+  it('should upload with custom region gravity that represents a custom shape', () => {
+    const customRegionGravityEncoded = '{custom_1}1,2,3,4,5,6,7,8|{custom_2}10,11,12,13,14,15';
+
+    return helper.provideMockObjects(function (mockXHR, writeSpy, requestSpy) {
+      helper.uploadImage({
+        regions: {
+          'custom_1': [[1, 2], [3, 4], [5, 6], [7, 8]],
+          'custom_2': [[10, 11], [12, 13], [14, 15]]
+        }
+      });
+
+      sinon.assert.calledWith(requestSpy, sinon.match({
+        method: sinon.match('POST')
+      }));
+
+      sinon.assert.calledWith(writeSpy, sinon.match(helper.uploadParamMatcher('regions', customRegionGravityEncoded)));
+    });
+  });
+
+  it('should not upload with insufficient custom region gravity details', () => {
+    assert.throws(() => {
+      cloudinary.v2.uploader.upload('irrelevant', {
+        regions: {
+          'error_1': [[1, 2]]
+        }
+      });
+    }, {
+      name: 'TypeError',
+      message: 'Regions should contain at least two arrays with two coordinates'
+    });
+  });
+});

types/index.d.ts

@@ -540,10 +540,13 @@ declare module 'cloudinary' {
         disable_promises?: boolean;
         oauth_token?: string;
         use_asset_folder_as_public_id_prefix?: boolean;
+        regions?: Record<string, [RegionCoordinate, RegionCoordinate, ...Array<RegionCoordinate>]>;
 
         [futureKey: string]: any;
     }
 
+    export type RegionCoordinate = [number, number];
+
     export interface ProvisioningApiOptions {
         account_id?: string;
         provisioning_api_key?: string;